feat: opt-in shared library UX and filter-based permission assignment

Keep classic Shared with Me and single-user assignment as defaults.
Host apps can enable nested shared items in Library, hide Shared with Me,
bulk Manage Permissions, and community/role/signup user filters.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: scottgrayson

CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to `:package_name` will be documented in this file.
 
+## v1.3.5 - 2026-07-10
+
+### What's Changed
+
+* Opt-in sharing/permission UX for host apps (defaults preserve classic behavior):
+  * `sharing.shared_with_me` (default `true`)
+  * `sharing.show_nested_shared_in_library` (default `false`)
+  * `permissions.bulk_manage_action` (default `false`)
+  * `permissions.filter_based_assignment` (default `false`)
+  * optional `user_filters` for community / role / signup date
+
+**Full Changelog**: https://github.com/TappNetwork/Filament-Library/compare/v1.3.4...v1.3.5
+
 ## v1.3.4 - 2026-07-09
 
 ### What's Changed

config/filament-library.php

@@ -18,6 +18,79 @@
     */
     'user_model' => env('FILAMENT_LIBRARY_USER_MODEL', 'App\\Models\\User'),
 
+    /*
+    |--------------------------------------------------------------------------
+    | Sharing behavior
+    |--------------------------------------------------------------------------
+    |
+    | Defaults preserve the classic package UX. Host apps can opt into the
+    | newer "shared items live in the main library" workflow.
+    |
+    */
+    'sharing' => [
+        /*
+        | Show the Shared with Me navigation item and page.
+        */
+        'shared_with_me' => env('FILAMENT_LIBRARY_SHARED_WITH_ME', true),
+
+        /*
+        | When true, nested (non-root) items with explicit per-user permissions
+        | also appear in the main Library view. Root-level shared items already
+        | appear there regardless of this setting.
+        */
+        'show_nested_shared_in_library' => env('FILAMENT_LIBRARY_SHOW_NESTED_SHARED', false),
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Permission assignment UI
+    |--------------------------------------------------------------------------
+    |
+    | Defaults keep the classic single-user permission form and hide the
+    | library-table bulk Manage Permissions action.
+    |
+    */
+    'permissions' => [
+        /*
+        | Show Manage Permissions as a table bulk action.
+        */
+        'bulk_manage_action' => env('FILAMENT_LIBRARY_BULK_MANAGE_PERMISSIONS', false),
+
+        /*
+        | When true, the permissions relation manager uses filter-based
+        | multi-user assignment. When false, it uses the classic single-user form.
+        */
+        'filter_based_assignment' => env('FILAMENT_LIBRARY_FILTER_BASED_ASSIGNMENT', false),
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | User assignment filters
+    |--------------------------------------------------------------------------
+    |
+    | Optional filters shown when filter-based assignment (or the bulk manage
+    | action) is enabled. Host apps can enable community and role filters by
+    | pointing these options at their own models.
+    |
+    */
+    'user_filters' => [
+        'community' => [
+            'enabled' => false,
+            'model' => null,
+            'title_attribute' => 'name',
+            'user_foreign_key' => 'community_id',
+        ],
+        'role' => [
+            'enabled' => false,
+            'model' => null,
+            'title_attribute' => 'name',
+        ],
+        'signup_date' => [
+            'enabled' => false,
+            'column' => 'created_at',
+        ],
+    ],
+
     /*
     |--------------------------------------------------------------------------
     | Model class overrides

src/FilamentLibraryPlugin.php

@@ -164,12 +164,7 @@ public function register(Panel $panel): void
                     ->group('Resource Library')
                     ->sort(3)
                     ->isActiveWhen(fn () => request()->routeIs("filament.{$panelId}.resources.library.my-documents")),
-                NavigationItem::make('Shared with Me')
-                    ->url(fn () => $libraryItemResourceClass::getUrl('shared-with-me'))
-                    ->icon('heroicon-o-share')
-                    ->group('Resource Library')
-                    ->sort(4)
-                    ->isActiveWhen(fn () => request()->routeIs("filament.{$panelId}.resources.library.shared-with-me")),
+                ...static::sharedWithMeNavigationItem($panelId, $libraryItemResourceClass),
                 NavigationItem::make('Created by Me')
                     ->url(fn () => $libraryItemResourceClass::getUrl('created-by-me'))
                     ->icon('heroicon-o-user')
@@ -208,6 +203,26 @@ public function boot(Panel $panel): void
         });
     }
 
+    /**
+     * @param  class-string<LibraryItemResource>  $libraryItemResourceClass
+     * @return array<int, NavigationItem>
+     */
+    protected static function sharedWithMeNavigationItem(string $panelId, string $libraryItemResourceClass): array
+    {
+        if (! config('filament-library.sharing.shared_with_me', true)) {
+            return [];
+        }
+
+        return [
+            NavigationItem::make('Shared with Me')
+                ->url(fn () => $libraryItemResourceClass::getUrl('shared-with-me'))
+                ->icon('heroicon-o-share')
+                ->group('Resource Library')
+                ->sort(4)
+                ->isActiveWhen(fn () => request()->routeIs("filament.{$panelId}.resources.library.shared-with-me")),
+        ];
+    }
+
     public static function make(): static
     {
         return app(static::class);

src/Resources/LibraryItemResource.php

@@ -23,6 +23,7 @@
 use Tapp\FilamentLibrary\FilamentLibraryPlugin;
 use Tapp\FilamentLibrary\Models\LibraryItem;
 use Tapp\FilamentLibrary\Resources\RelationManagers\LibraryItemPermissionsRelationManager;
+use Tapp\FilamentLibrary\Tables\Actions\BulkManagePermissionsAction;
 
 class LibraryItemResource extends Resource
 {
@@ -165,7 +166,6 @@ public static function table(Table $table): Table
         // - PublicLibrary (public files)
         // - MyLibrary (personal documents)
         // - CreatedByMe (user's created items)
-        // - SharedWithMe (shared items)
         // - SearchAll (search results)
         // The list pages only override getTableQuery() for filtering, not the columns
         return $table
@@ -338,6 +338,7 @@ public static function table(Table $table): Table
             ])
             ->toolbarActions([
                 BulkActionGroup::make([
+                    ...static::bulkManagePermissionsActions(),
                     DeleteBulkAction::make()
                         ->visible(fn (): bool => auth()->user() && auth()->user()->can('deleteAny', static::getModel()))
                         ->successRedirectUrl(function () {
@@ -382,7 +383,7 @@ public static function getPages(): array
         return [
             'index' => Pages\ListLibraryItems::route('/'),
             'my-documents' => Pages\MyLibrary::route('/my-documents'),
-            'shared-with-me' => Pages\SharedWithMe::route('/shared-with-me'),
+            ...static::sharedWithMePage(),
             'created-by-me' => Pages\CreatedByMe::route('/created-by-me'),
             'favorites' => Pages\Favorites::route('/favorites'),
             'public' => Pages\PublicLibrary::route('/public'),
@@ -398,6 +399,34 @@ public static function getPages(): array
         ];
     }
 
+    /**
+     * @return array<string, \Filament\Resources\Pages\PageRegistration>
+     */
+    protected static function sharedWithMePage(): array
+    {
+        if (! config('filament-library.sharing.shared_with_me', true)) {
+            return [];
+        }
+
+        return [
+            'shared-with-me' => Pages\SharedWithMe::route('/shared-with-me'),
+        ];
+    }
+
+    /**
+     * @return array<int, BulkManagePermissionsAction>
+     */
+    protected static function bulkManagePermissionsActions(): array
+    {
+        if (! config('filament-library.permissions.bulk_manage_action', false)) {
+            return [];
+        }
+
+        return [
+            BulkManagePermissionsAction::make(),
+        ];
+    }
+
     public static function getEditUrl($record): string
     {
         return match ($record->type) {

src/Resources/Pages/ListLibraryItems.php

@@ -227,30 +227,37 @@ protected function getTableQuery(): Builder
         if ($this->parentId) {
             $query->where('parent_id', $this->parentId);
         } else {
-            // Show items at root level based on user permissions
             $user = auth()->user();
-            $query->whereNull('parent_id')
-                ->where(function ($q) use ($user) {
-                    $q->where('general_access', 'anyone_can_view');
-
-                    // Admins can see all items (including private/inherit)
-                    if ($user && FilamentLibraryPlugin::isLibraryAdmin($user)) {
-                        $q->orWhere(function ($adminQuery) {
-                            $adminQuery->whereIn('general_access', ['private', 'inherit']);
+            $showNestedShared = (bool) config('filament-library.sharing.show_nested_shared_in_library', false);
+
+            $query->where(function (Builder $visibility) use ($user, $showNestedShared): void {
+                $visibility->where(function (Builder $root) use ($user): void {
+                    $root->whereNull('parent_id')
+                        ->where(function (Builder $access) use ($user): void {
+                            $access->where('general_access', 'anyone_can_view');
+
+                            if ($user && FilamentLibraryPlugin::isLibraryAdmin($user)) {
+                                $access->orWhereIn('general_access', ['private', 'inherit']);
+                            }
+
+                            if ($user) {
+                                $access->orWhere('created_by', $user->id)
+                                    ->orWhereHas('permissions', function (Builder $permissions) use ($user): void {
+                                        $permissions->where('user_id', $user->id);
+                                    });
+                            }
                         });
-                    }
-
-                    // Creators can see their own items (even if private)
-                    if ($user) {
-                        $q->orWhere('created_by', $user->id);
-
-                        // Users can see items explicitly shared with them
-                        $q->orWhereHas('permissions', function ($pq) use ($user) {
-                            $pq->where('user_id', $user->id);
-                        });
-                    }
-                })
-                ->where('name', 'not like', "%'s Personal Folder");
+                });
+
+                if ($user && $showNestedShared) {
+                    $visibility->orWhere(function (Builder $sharedNested) use ($user): void {
+                        $sharedNested->whereNotNull('parent_id')
+                            ->whereHas('permissions', function (Builder $permissions) use ($user): void {
+                                $permissions->where('user_id', $user->id);
+                            });
+                    });
+                }
+            })->where('name', 'not like', "%'s Personal Folder");
         }
 
         return $query;