TenantAtlas/docs/research/filament-v5-notes.md

# SECTION A — FILAMENT V5 NOTES (BULLETS + SOURCES)

## Versioning & Base Requirements
- Rule: Filament v5 requires Livewire v4.0+.
  When: Always when installing/upgrading Filament v5. When NOT: Never target Livewire v3 in a v5 codebase.
  Source: https://filamentphp.com/docs/5.x/upgrade-guide — “Upgrading Livewire”

## Panels — Configuration
- Rule: Panels are configured via dedicated panel providers; the default admin panel ships at `/admin`.
  When: Always—centralize panel setup (resources/pages/widgets/plugins) here. When NOT: Don’t scatter core panel configuration across unrelated providers.
  Source: https://filamentphp.com/docs/5.x/panel-configuration — “The default admin panel”
- Rule: New panel providers must be registered in `bootstrap/providers.php` for Laravel 11+ (or `config/app.php` for Laravel 10 and below).
  When: When adding a new panel or if panel creation didn’t auto-register. When NOT: Don’t register panel providers in `bootstrap/app.php`.
  Source: https://filamentphp.com/docs/5.x/panel-configuration — “Creating a new panel”
- Rule: Use `path()` to change a panel’s URL prefix; `path('')` mounts at `/` and can conflict with existing routes.
  When: When `/admin` is not desired. When NOT: Don’t set `path('')` if `/` is already routed in `routes/web.php`.
  Source: https://filamentphp.com/docs/5.x/panel-configuration — “Changing the path”
- Rule: Use render hooks to inject Blade content into Filament layouts without publishing internal views.
  When: When inserting banners/scripts/partials into specific layout locations. When NOT: Don’t publish Filament views for small layout tweaks.
  Source: https://filamentphp.com/docs/5.x/advanced/render-hooks — “Registering render hooks”

## Navigation — Groups, Ordering, Visibility
- Rule: Navigation is built from resources/pages/clusters and can be grouped, sorted, and conditionally shown/hidden.
  When: Always—use groups/sorting for predictable IA. When NOT: Don’t treat “hidden navigation” as authorization; still enforce policies/access checks.
  Source: https://filamentphp.com/docs/5.x/navigation/overview — “Introduction”
- Rule: Clusters group resources/pages under a single nav item and provide sub-navigation.
  When: When the sidebar becomes too large and needs hierarchy. When NOT: Don’t cluster if it reduces discoverability for your users.
  Source: https://filamentphp.com/docs/5.x/navigation/clusters — “Introduction”
- Rule: Cluster code structure (moving pages/resources into a cluster directory) is recommended, not required; behavior depends on `$cluster`.
  When: When you want consistent organization. When NOT: Don’t treat the directory layout as mandatory.
  Source: https://filamentphp.com/docs/5.x/navigation/clusters — “Code structure recommendations for panels using clusters”
- Rule: The user menu is configured via `userMenuItems()` with Action objects and supports conditional visibility and sidebar placement.
  When: When adding account-related links/actions. When NOT: Don’t put destructive actions there without confirmation + authorization.
  Source: https://filamentphp.com/docs/5.x/navigation/user-menu — “Introduction”

## Theming & Branding — CSS Hooks, Colors, Icons
- Rule: Filament exposes CSS hook classes (prefixed `fi-`) and recommends discovering them via browser DevTools.
  When: When styling core UI safely. When NOT: Don’t rely on brittle selectors; request/PR missing hooks instead of hacking around them.
  Source: https://filamentphp.com/docs/5.x/styling/css-hooks — “Discovering hook classes”
- Rule: Apply styling by targeting hook classes (including Tailwind `@apply`) and use `!important` sparingly.
  When: When overriding default spacing/appearance in a maintainable way. When NOT: Don’t blanket `!important` your theme.
  Source: https://filamentphp.com/docs/5.x/styling/css-hooks — “Applying styles to hook classes”
- Rule: Customize the default semantic color palettes via `FilamentColor::register()` (e.g., primary, danger, etc.).
  When: When aligning Filament semantics to your brand palette. When NOT: Don’t hardcode per-component hex values when semantics suffice.
  Source: https://filamentphp.com/docs/5.x/styling/colors — “Customizing the default colors”
- Rule: Replace default UI icons globally via `FilamentIcon::register()` (icon aliases map to your chosen icons).
  When: When standardizing iconography or switching icon sets. When NOT: Don’t hardcode SVGs everywhere when aliases cover the UI.
  Source: https://filamentphp.com/docs/5.x/styling/icons — “Replacing the default icons”

## Asset System — Global + Lazy / On-Demand
- Rule: Register shared assets via `FilamentAsset::register()`; assets are published into `/public` when `php artisan filament:assets` runs.
  When: For app/plugin assets loaded by Filament. When NOT: Don’t assume assets exist in production without the publish step.
  Source: https://filamentphp.com/docs/5.x/advanced/assets — “The FilamentAsset facade”
- Rule: Lazy-load CSS with `x-load-css` and prevent auto-loading via `loadedOnRequest()` for page-specific styles.
  When: For heavy CSS used only on certain pages/components. When NOT: Don’t lazy-load tiny styles used everywhere.
  Source: https://filamentphp.com/docs/5.x/advanced/assets — “Lazy loading CSS”
- Rule: Lazy-load JavaScript with `x-load-js` and prevent auto-loading via `loadedOnRequest()` for page-specific scripts.
  When: For heavy JS libraries used only on a subset of pages/widgets. When NOT: Don’t lazy-load scripts required for baseline panel behavior.
  Source: https://filamentphp.com/docs/5.x/advanced/assets — “Lazy loading JavaScript”

## Plugin System — Mechanics + Panel Scoping
- Rule: Panel plugins integrate via a Plugin object; standalone plugins integrate via a service provider (no panel binding).
  When: When deciding whether a package needs panel-specific registration. When NOT: Don’t force a Plugin object for standalone-only components.
  Source: https://filamentphp.com/docs/5.x/plugins/getting-started — “The Plugin object”
- Rule: Plugin assets should be registered in the plugin’s service provider so Filament can manage publishing/loading.
  When: When shipping CSS/JS/Alpine components with a package. When NOT: Don’t register package assets ad-hoc only in app panel providers.
  Source: https://filamentphp.com/docs/5.x/plugins/getting-started — “Registering assets”
- Rule: Panel-scoped module/plugin registration can be centralized using `Panel::configureUsing()` for modular architectures.
  When: When modules should enable Filament artifacts only for specific panels. When NOT: Don’t register all modules globally if panels target different audiences.
  Source: https://filamentphp.com/docs/5.x/advanced/modular-architecture — “Registering plugins conditionally for specific panels”
- Rule: Panel plugins are configurable per panel; treat “enabled in panel A” and “enabled in panel B” as independent configuration contexts.
  When: When the same app has multiple panels with different modules enabled. When NOT: Don’t assume a plugin is active across all panels.
  Source: https://filamentphp.com/docs/5.x/plugins/panel-plugins — “Introduction”

## Actions — Modals, Confirmation, Execution
- Rule: Use `Action::make(...)->action(...)` to execute logic; use `requiresConfirmation()` for confirmation modals.
  When: For destructive or high-impact actions. When NOT: Don’t skip confirmation for destructive operations.
  Source: https://filamentphp.com/docs/5.x/actions/modals — “Confirmation modals”
- Rule: Action modals can render a schema to collect input; submitted modal data is available to the action handler.
  When: When you need “form-in-action” workflows. When NOT: Don’t create bespoke modals when schema-in-modal is sufficient.
  Source: https://filamentphp.com/docs/5.x/actions/modals — “Rendering a form in a modal”

## Resources & Pages — Global Search, Queries
- Rule: Global search returns results for a resource only if it has an Edit or View page; otherwise the resource returns no results.
  When: When enabling global search for a resource. When NOT: Don’t expect global search on resources without Edit/View pages.
  Source: https://filamentphp.com/docs/5.x/resources/global-search — “Setting global search result titles”
- Rule: If global search result details access relationships, override the global search query to eager-load them to avoid N+1.
  When: Any time you return relationship-backed details. When NOT: Don’t lazy-load relationships in global search rendering.
  Source: https://filamentphp.com/docs/5.x/resources/global-search — “Adding extra details to global search results”
- Rule: You can disable search term splitting for performance on large datasets.
  When: When global search becomes expensive. When NOT: Don’t disable if multi-word relevance is important.
  Source: https://filamentphp.com/docs/5.x/resources/global-search — “Disabling search term splitting”

## Tables — Empty States
- Rule: Tables support empty-state content and can add empty-state actions to guide first-time users.
  When: Always—empty-state guidance improves “first run” UX. When NOT: Don’t leave empty lists without a clear next step when creation is expected.
  Source: https://filamentphp.com/docs/5.x/tables/empty-state — “Adding empty state actions”

## Testing
- Rule: Filament testing distinguishes Livewire components (pages/relation managers/widgets) from non-Livewire classes (resources/actions/schema objects).
  When: When choosing what to mount with `Livewire::test()`. When NOT: Don’t try to Livewire-test non-Livewire classes directly.
  Source: https://filamentphp.com/docs/5.x/testing/overview — “What is a Livewire component when using Filament?”
- Rule: Actions have dedicated testing guidance; follow it for asserting action execution and side effects.
  When: When actions drive critical business workflows. When NOT: Don’t leave actions untested if they mutate data or trigger external effects.
  Source: https://filamentphp.com/docs/5.x/testing/testing-actions — “Testing actions”

## OPINIONATED — best practices not explicitly mandated by docs
- Rule: Standardize destructive actions: danger styling + requiresConfirmation() + policy authorization + success/error notification.
  When: For delete/force-delete/restore/bulk destructive ops. When NOT: For trivial, reversible toggles.

## UNVERIFIED — not explicitly stated in the cited v5 pages above
- Rule: If you need confirmation or a modal, prefer `->action(...)` + `->requiresConfirmation()`; use `->url(...)` for navigation links.
  When: When deciding whether an action should execute vs navigate. When NOT: Don’t assume modal/confirmation behavior for URL-only actions without verifying in docs.
  Source: https://filamentphp.com/docs/5.x/actions/modals — “Confirmation modals”