Fin Codex Laravel Package

Getting Started

This release is a maintenance patch (v0.5.6) — no new APIs, no breaking changes — but it is the release to be on if you run Filament 4.15+/5.10+, because the previous version silently broke tab switching on the article list.

Minimal path to a working install:

composer require finity-labs/fin-codex
php artisan vendor:publish --tag="fin-codex-config"
php artisan vendor:publish --tag="fin-codex-migrations"
php artisan migrate

Then register the plugin on your panel:

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(FinCodexPlugin::make());
}

Where to look first:

1. The ArticleResource list page — it is the integration surface most people touch, and it is what this release changed.
2. The Files tab / nested file table — the second schema component; worth reading before you customise it.
3. The published config — check the disk and upload rules before you seed content, since file paths are baked into records.

First use case: create an article, attach files through the Files tab, then click back and forth between tabs. On v0.5.5 with Filament 4.15/5.10 the Files tab would show the previous tab's table on the switching request; v0.5.6 fixes exactly that, so it is also the fastest smoke test after upgrading.

Implementation Patterns

Upgrade-and-verify workflow. Treat this release as "pin Filament, bump fin-codex, click the tabs." If you are on Filament < 4.15 nothing changes functionally, but upgrading is still recommended because the test-suite fix means the package now validates against 4.12.6 through 5.10.x rather than a narrow markup snapshot.

Schema composition over schema branching. The fix encodes a pattern worth copying in your own custom pages: keep both the table and the nested file component in the schema at all times, and decide which one is visible as the schema renders (a ->visible(fn () => ...) closure), rather than conditionally adding components based on $this->activeTab. Conditional inclusion forces the schema to be built from Livewire state that is not yet updated when the page hydrates.

// Preferred: both components exist, visibility is resolved at render
Tabs::make()->tabs([
    Tab::make('Files')->schema([
        $this->table,          // always present
        $this->fileTable,      // always present
    ]),
]);

Extending the resource. Subclass the article resource or its list page and override table() / getHeaderActions() as usual; because the page keeps the nested component mounted rather than swapping it in, overrides survive tab switches instead of being re-registered mid-request.

Testing pattern. This release explicitly moved the package's own suite off Filament's private markup and onto stable state assertions. Adopt the same discipline in your app tests:

// Do this — stable, version-agnostic
livewire(ListArticles::class)
    ->call('setActiveTab', 'files')
    ->assertSee('your-file-id')
    ->assertSeeHtml('id="your-relation-manager-id"');

// Not this — breaks on Filament point releases
->assertSeeHtml('fi-tabs-strip')  // wrapper element changed in 4.15.2 / 5.10.2

Assert on the ids fin-codex emits, which tab panel has content, and which relation manager is mounted — those held from 4.12.6 through 5.10.x.

Integration tip. If you render the codex list inside your own page or a panel widget, mount it once and toggle tabs internally; do not re-mount the component per tab, or you reintroduce the hydration-ordering problem the release just fixed.

Gotchas and Tips

• Hydration order is the root cause, not the symptom. Filament 4.15+/5.10+ resolve and cache a resource page's record on every Livewire update, so the content schema is built and cached before the tab change is applied. Any custom page that computes its schema from a Livewire property mutated in the same request will render one state behind. Move such decisions into render-time closures.
• Don't assert Filament internals. The 4.15.2/5.10.2 changes touched the section persistence key format, the tab strip's wrapper element, and empty wrappers for inactive tab panels. Three unrelated markup changes in one point release — expect more. Assert on ids, visible content, and mounted components instead.
• Bump Filament and fin-codex together in CI. The supported range is now 4.12.6–5.10.x; a matrix that includes both sides of the 4.15 boundary will catch tab regressions before users do.
• Debugging a "wrong tab content" report. Open the network tab and inspect the Livewire update payload: confirm the tab property is in the payload and that the response re-renders the expected panel. If the panel is correct in the payload but stale on screen, it is a schema-caching issue, not a front-end one.
• Cached schema across requests. Page-level schema caching means clearing php artisan optimize:clear (and any Filament component cache) is a legitimate first step when behaviour differs between php artisan serve and a queued/Octane worker.
• Extension points. The clean seams are the plugin config (disk, accepted MIME types), the file relation manager, and the list page subclass. Avoid editing published views to change which tab is active — that path is exactly what this release had to rewrite.
• No deprecations in this release. Nothing to remove from your code; the only action item is the upgrade itself if you are on Filament 4.15/5.10 or asserting the package's markup in your own tests.