Filament Sticky Columns Laravel Package

Technical Evaluation

Architecture Fit

• Low architectural intrusion: The package leverages Filament’s existing column system via macros (->sticky()) and a drop-in StickyColumn class, avoiding deep modifications to core Filament logic. This aligns well with Laravel/PHP’s composable design patterns.
• UI-focused: Targets horizontal scrollability (not vertical), a common pain point in data-heavy Filament tables (e.g., audit logs, financial data). Mimics Excel/Google Sheets behavior, which users intuitively understand.
• Filament-agnostic core: Underlying CSS/JS is generic and could theoretically work with other table libraries, but tightly coupled to Filament’s table markup (e.g., .fi-ta-table-wrapper). Risk of breakage if Filament’s HTML structure changes (e.g., v6+).

Integration Feasibility

• Minimal dependencies: Only requires Filament v3–v5 and Livewire v3–v4, with no PHP extensions or complex setup. Composer install + asset publishing is sufficient.
• Two integration paths:
  1. Vite-recommended: Zero Filament asset pipeline overhead (preferred for modern Laravel apps).
  2. Filament assets pipeline: Works but requires filament:assets (legacy systems).
• Dynamic content support: Includes a window.FilamentStickyColumns.refresh() API for SPAs or AJAX-driven tables (e.g., real-time updates).

Technical Risk

• CSS/JS conflicts:
  • Z-index collisions: Sticky columns use a default z-index: 10 (configurable). Conflicts possible if other Filament plugins (e.g., tooltips, modals) use overlapping values.
  • Scroll container detection: Relies on Filament’s table wrapper classes (.fi-ta-table-wrapper). Filament v4+ introduced .fi-ta-content-ctn.fi-fixed-positioning-context, which the package now supports, but edge cases may exist (e.g., custom table layouts).
• Performance:
  • Auto-offset calculation: Uses offsetWidth in JavaScript, which is lightweight but could introduce minor layout thrashing if tables are highly dynamic (e.g., columns added/removed via JS).
  • Shadow rendering: Adds a scroll shadow effect, which may impact rendering in complex tables (e.g., nested scrollable regions).
• Filament version lock-in: No backward compatibility guarantees across Filament major versions (e.g., v3 → v6). Package may need updates for Filament’s breaking changes.

Key Questions

1. Table complexity:
   • Does the target Filament table have nested scrollable regions (e.g., tables inside modals/drawers)? If so, manual offset tuning may be required.
   • Are there custom column types (e.g., from plugins) that might not support the ->sticky() macro?
2. Asset pipeline:
   • Is the project using Vite (recommended) or the Filament asset pipeline? Vite avoids hard refreshes but requires manual CSS/JS imports.
3. Dynamic updates:
   • Will sticky columns need to reapply on Livewire events (e.g., livewire:update) beyond the default hooks? If so, window.FilamentStickyColumns.refresh() may need manual triggering.
4. Dark mode:
   • Does the Filament panel use custom dark mode themes? The package inherits Filament’s surface colors, but overrides may be needed for consistency.
5. Scaling:
   • How many sticky columns per table are planned? Performance testing may be needed for tables with >5 sticky columns.
6. Testing coverage:
   • Are there automated tests for the package in the target environment? The package includes Pest tests, but integration tests should validate Filament-specific edge cases.

Integration Approach

Stack Fit

• Laravel/PHP: Zero runtime overhead; package is pure PHP/CSS/JS with no Laravel-specific logic beyond Filament.
• Filament v3–v5: Native support with version-specific hooks (e.g., Livewire v3/4 compatibility). Filament v6+ would require validation.
• Livewire: Leverages Livewire’s commit/navigated events for reactivity. No server-side logic changes needed.
• Frontend:
  • Vite: Preferred for cache-busting and modern asset handling.
  • Legacy: Filament’s filament:assets pipeline works but may require manual filament:assets runs post-update.

Migration Path

1. Assessment phase:
   • Audit target Filament tables for custom column types or non-standard markup (e.g., tables inside modals).
   • Verify Filament version and Livewire version compatibility.
2. Installation:

   composer require zeeshantariq/filament-sticky-columns
   

   • Publish config (optional):

     php artisan vendor:publish --tag="filament-sticky-columns-config"
     

3. Asset integration:
   • Vite path (recommended):
     • Import CSS in resources/css/filament/admin/theme.css:

       @import "../../../../vendor/zeeshantariq/filament-sticky-columns/resources/css/filament-sticky-columns.css";
       

     • Import JS in a Vite entry point (e.g., resources/js/filament/app.js):

       import '../../../../vendor/zeeshantariq/filament-sticky-columns/resources/js/filament-sticky-columns.js';
       

     • Run npm run dev or npm run build.
   • Filament assets path:
     • Run php artisan filament:assets to publish JS/CSS.
     • Clear cache if needed: php artisan cache:clear.
4. Implementation:
   • Option A (drop-in): Replace TextColumn with StickyColumn:

     StickyColumn::make('id')->right()->badge();
     

   • Option B (macro): Add ->sticky() to any column:

     TextColumn::make('status')->stickyRight();
     

   • Option C (manual offsets): For edge cases:

     StickyColumn::make('name')->sticky(offset: 80);
     

5. Testing:
   • Validate sticky behavior in dark/light mode.
   • Test horizontal scrolling and shadow visibility.
   • Verify Livewire updates (e.g., pagination, sorting) preserve stickiness.

Compatibility

• Filament plugins: Risk of CSS/JS conflicts if other plugins modify table markup or use overlapping z-index values. Test with:
  • Filament Forms (if tables are embedded).
  • Third-party column types (e.g., filament-spatie-laravel-medialibrary).
• Custom themes: If Filament uses custom CSS variables or shadow overrides, the package’s background: 'auto' may need adjustment.
• Browser support: Relies on modern CSS positioning (no IE11 support required).

Sequencing

1. Low-risk tables first: Start with non-critical tables (e.g., admin dashboards) to validate integration.
2. Critical tables last: Apply to high-impact tables (e.g., financial reports) only after confirming stability.
3. A/B testing: Consider feature flags to toggle sticky columns for specific user groups during rollout.
4. Rollback plan:
   • Remove CSS/JS imports and ->sticky() calls.
   • Revert to php artisan filament:assets if Vite integration fails.

Operational Impact

Maintenance

• Dependency updates:
  • Monitor Filament major versions for breaking changes (e.g., table markup updates).
  • Composer scripts can automate filament:assets post-update:

    "post-update": "php artisan filament:assets"
    

• Configuration drift:
  • Centralized config (config/filament-sticky-columns.php) reduces risk of hardcoded values.
  • Z-index and shadow settings may need tuning across tables.
• Debugging:
  • DOM inspection: Verify data-sticky="left/right" attributes exist on <th>/<td> (not nested divs).
  • Browser DevTools: Check for CSS conflicts (e.g., !important overrides).

Support

• Common issues:
  • Sticky columns not applying: 80% of cases are due to missing assets or incorrect table markup (e.g., custom column types).
  • Offset miscalculations: Resolved via ->sticky(offset: X) or manual CSS adjustments.
  • Dark mode inconsistencies: Override background config if Filament’s surface colors don’t match.
• Documentation gaps:
  • Filament v4+ note in README is critical but may be overlooked. Add a wiki page or internal runbook for the team.