v2.4.3

Filament Page Header v2.4.3

Filament Page Header 2.4.3 fixes the documentation version selector introduced with the versioned documentation experience.

This is a documentation-site fix only. There are no package runtime, public API, dependency, Filament CSS, or Filament JavaScript changes in this release.

Fixed documentation version selector

The documentation version picker no longer displays the same release twice as separate Latest and major-version entries.

Previously, when the latest release belonged to the current major, the selector could show:

Latest (v2.4.2)
2.x (v2.4.2)

The selector now displays one entry per deployed major and marks the latest channel inline:

2.x (v2.4.3) — Latest

This keeps the distinction between the canonical Latest documentation URL and permanent major-version channels internally, without exposing duplicate choices to users.

Fixed SPA navigation lifecycle

The version selector is now correctly re-initialized when navigating between documentation pages using Astro/Starlight SPA navigation.

Previously, navigating through the documentation could replace the selector DOM without re-running its initialization logic, causing the control to fall back to its initial server-rendered state.

The selector now:

• re-synchronizes on astro:page-load;
• initializes replacement selectors after SPA navigation;
• keeps the active documentation channel selected correctly;
• avoids duplicate change event listeners;
• avoids unnecessary repeated manifest requests.

Version manifest behavior

The versions.json schema and documentation publication model remain unchanged.

The canonical package documentation URL still represents Latest, while permanent major channels such as /2.x/ continue to point to the latest published release for that major.

The change is limited to how those channels are presented and initialized in the documentation UI.

Compatibility

Filament Page Header 2.x continues to support:

• PHP ^8.3
• Filament ^4.12.6 || ^5.8.1
• Laravel 12 and 13

No dependency requirements have changed.

Upgrade

Update normally with Composer:

composer update mortalkiller/filament-page-header

No application code or configuration changes are required.

There is no need to republish Filament assets specifically for this release because the package runtime assets are unchanged.

Verification

The release state has passed:

• Package tests
• Code quality
• Package standard
• Documentation build
• JavaScript tests
• PHP compatibility coverage
• Browser tests on Filament 4.12.6 and Filament 5.x

Full changelog

Compare v2.4.2...v2.4.3 on GitHub for the exact changes included in this release.

v2.4.2

Filament Page Header v2.4.2

Filament Page Header 2.4.2 is a corrective documentation release.

v2.4.1 was published before the final README documentation change was merged into the maintained 2.x branch. Because published Composer package versions and Git tags must remain immutable, v2.4.1 has not been moved or recreated.

This release publishes the intended documentation from the correct repository commit.

There are no runtime, API, dependency, CSS, or JavaScript changes in this release.

New "Why" section

The README now includes an early Why section explaining the problem Filament Page Header is designed to solve.

It clarifies that Filament's native page headers are intentionally suitable for many applications, while this package becomes useful when multiple pages need richer and reusable presentation such as:

• identity and imagery;
• status information;
• metadata;
• responsive native actions;
• sticky headers;
• compact-on-scroll presentation.

The section also makes the package boundaries explicit:

• Filament Page Header remains fully opt-in;
• pages that do not need a richer header can continue using Filament's native header unchanged;
• records and application data remain application-owned;
• authorization remains controlled by Filament and the consuming application;
• native actions remain native Filament actions;
• breadcrumbs and sub-navigation continue to use Filament's navigation system;
• the package provides reusable header composition rather than replacing Filament's page architecture.

The README Contents section has also been updated to include the new Why section.

Documentation improvements from 2.4.1

This release also includes the documentation improvements introduced after v2.4.0, including the refined documentation version selector that matches the Starlight theme controls more closely.

The version selector keeps its existing behavior while improving:

• light and dark theme integration;
• typography and spacing;
• focus states;
• disabled states;
• responsive behavior;
• constrained-width handling.

These changes affect the documentation site only.

Why a new patch release?

v2.4.1 had already been published before the final README change was merged.

Published package versions must remain immutable, particularly once they may have been observed by Packagist or Composer clients.

Instead of moving the existing v2.4.1 tag to a different commit, v2.4.2 is published from the correct 2.x state.

This preserves reproducible Composer installs and ensures that:

v2.4.1

always refers to its original commit, while:

v2.4.2

contains the intended final documentation.

Compatibility

Filament Page Header 2.x continues to support:

• PHP ^8.3
• Filament ^4.12.6 || ^5.8.1
• Laravel 12 and 13

No dependency requirements have changed.

Upgrade

Update normally with Composer:

composer update mortalkiller/filament-page-header

No application code or configuration changes are required.

There is no need to republish Filament assets specifically for this release because the package runtime CSS and JavaScript are unchanged.

Full changelog

Compare v2.4.1...v2.4.2 on GitHub for the exact changes included in this corrective release.

v2.4.1

Filament Page Header v2.4.1

Filament Page Header 2.4.1 is a documentation and maintenance release focused on improving the package's documentation experience and making its purpose clearer to new users.

There are no runtime API changes in this release and no application code changes are required when upgrading from v2.4.0.

Improved documentation version selector

The documentation version selector has been refined to better match Starlight's native theme controls.

The selector now:

• keeps the existing native select and version navigation behavior;
• uses the same transparent, borderless appearance as the theme control;
• follows the documentation theme's typography, spacing and chevron styling;
• supports light and dark modes;
• includes consistent focus and disabled states;
• handles constrained widths and mobile layouts more cleanly.

This is a documentation-site presentation change only and does not affect the package runtime.

New "Why" section

The README now includes an early Why section explaining the problem Filament Page Header is designed to solve.

It clarifies that Filament's native headers are intentionally appropriate for many applications, while the package becomes useful when multiple pages need richer identity, metadata, status information, responsive actions, sticky behavior or compact-on-scroll presentation.

The section also makes the package boundaries clearer:

• Filament Page Header remains opt-in;
• pages that do not need a richer header can keep the native Filament header unchanged;
• records, authorization, native actions, breadcrumbs and sub-navigation remain under Filament's control;
• the package focuses on reusable header composition rather than replacing Filament's page system.

The README Contents has also been updated to include the new section.

Maintainer documentation

Development documentation has been updated to clarify how the MortalKiller developing-filament-packages maintainer skill is consumed in standalone package repositories.

Standalone package development reads the installed skill directly from the mortalkiller/filament-package-standard development dependency rather than treating Testbench as a Laravel Boost project root.

This does not affect consumers of Filament Page Header.

Compatibility

Filament Page Header 2.x continues to support:

• PHP ^8.3
• Filament ^4.12.6 || ^5.8.1
• Laravel 12 and 13

No dependency requirements have changed.

Upgrade

Update normally with Composer:

composer update mortalkiller/filament-page-header

No application code changes are required.

There is also no need to republish Filament assets specifically for this release because the changes since v2.4.0 do not modify the package's runtime CSS or JavaScript.

Full changelog

Compare v2.4.0...v2.4.1 on GitHub for the complete set of changes.

v2.4.0

Filament Page Header v2.4.0

Filament Page Header 2.4 adds native page action positioning and compact-mode action visibility controls while preserving Filament's existing action system.

Existing headers keep their current behavior by default. The new action controls are opt-in and fully backwards compatible with the 2.x line.

What's new

Native action positioning

Page header actions can now be positioned using a typed API:

use MortalKiller\FilamentPageHeader\Enums\HeaderActionsPosition;

Header::make()
    ->actionsPosition(HeaderActionsPosition::Below);

Available positions:

• HeaderActionsPosition::Start
• HeaderActionsPosition::End — default behavior
• HeaderActionsPosition::Below

Desktop positioning uses logical start/end alignment and supports RTL layouts.

Mobile keeps the existing full-width action area regardless of the configured desktop position.

Compact action selection

Compact headers can now choose which native Filament page actions remain visible:

use MortalKiller\FilamentPageHeader\CompactHeader;

Header::make()
    ->compact()
    ->whenCompact(
        fn (CompactHeader $compact) => $compact
            ->actions([
                'save',
                'approve',
            ])
    );

Action identifiers use the native Filament action name rather than the displayed label.

The inverse API is also available:

Header::make()
    ->compact()
    ->whenCompact(
        fn (CompactHeader $compact) => $compact
            ->hideActions([
                'delete',
                'duplicate',
            ])
    );

The last action-selection call wins.

Special cases:

->actions([])

hides all native actions in compact mode.

->hideActions([])

keeps all native actions.

Without action configuration, all actions allowed by Filament remain visible, preserving the existing package behavior.

Native Filament behavior preserved

Action control remains presentation-only.

The package continues to use the original cached Filament action instances and preserves:

• action authorization and visibility
• disabled states
• original action ordering
• nested ActionGroup structures
• dropdown actions
• button groups
• confirmation dialogs
• actions containing forms
• form submission targets
• render hooks around native page actions
• Livewire behavior
• keyboard focus and active interactions
• SPA navigation

Actions are not cloned or rendered separately between expanded and compact states.

Compact transitions do not send additional Livewire requests.

Action groups

Compact filtering works recursively with native Filament action groups.

When only selected child actions remain, the original group structure is preserved.

Groups that become empty in compact mode are removed from the presentation instead of leaving empty dropdowns or controls.

Nested groups and teleported dropdown positioning are also supported.

Improved interaction handling

This release adds dedicated handling for action-heavy headers, including:

• preserving an already-open dropdown while entering compact mode
• keeping a focused action available until focus moves away
• preserving modal and action-form state during compact transitions
• recalculating empty action groups after Livewire visibility changes
• cleaning up action presentation state during SPA navigation

Documentation

Added documentation for native action control, including:

• action positioning
• compact inclusion and exclusion
• action naming
• groups and dropdowns
• forms and modals
• authorization behavior
• custom action-view considerations
• responsive behavior

The README and API reference have also been updated.

Full documentation:

https://docs.pedromonteiro.dev/filament-page-header/

Testing

The feature is covered across PHP, JavaScript and browser tests.

Browser coverage includes:

• Start, End, and Below positioning
• LTR and RTL layouts
• mobile action layouts
• compact inclusion and exclusion
• individual actions
• nested action groups
• button groups
• dropdown actions
• teleported dropdown positioning
• hidden and unauthorized actions
• disabled actions
• render hooks
• keyboard focus
• action forms
• confirmation dialogs
• Livewire visibility changes
• SPA navigation
• expanded/compact transitions

The compatibility matrix was validated against the supported Filament 4 and Filament 5 lines.

Compatibility

Filament Page Header 2.x continues to support:

• PHP ^8.3
• Filament ^4.12.6 || ^5.8.1
• Laravel 12 and 13

Upgrade

Update normally with Composer:

composer update mortalkiller/filament-page-header

Then republish Filament assets:

php artisan filament:assets

Republishing assets is required because this release includes updated CSS and JavaScript for native action control.

No application code changes are required unless you want to use the new functionality.

Full changelog

v2.3.2...v2.4.0

v2.3.2

Filament Page Header v2.3.2

This patch release focuses on package maintenance, CI supply-chain hardening, and the new major-based release and documentation workflow.

There are no runtime API changes in this release and no application code changes are required when upgrading from v2.3.1.

Changed

• Adopted MortalKiller Filament Package Standard v1 repository conventions and collaboration files.
• Moved development and maintenance to permanent major branches such as 2.x, without a separate stable-promotion branch.
• Added release-tag documentation publishing: pull requests and pushes validate documentation, while stable GitHub Releases publish documentation from the exact release tag.
• Added versioned documentation channels so the canonical documentation URL remains Latest while /2.x/ tracks the newest published 2.x documentation.
• Added rollback protection so older releases or stale workflow re-runs cannot replace newer documentation.
• Updated the README CI badge to track the maintained 2.x branch.
• Added canonical package metadata and maintenance scripts without changing runtime dependencies or compatibility.

CI and security hardening

• Reusable GitHub Actions workflows and supporting tooling are pinned to reviewed full commit SHAs.
• Preserved the existing PHP compatibility matrix for Filament 4 and 5.
• Preserved JavaScript tests and Chromium browser coverage.
• Documentation builds remain part of CI, but branch builds no longer receive production deployment access.

Compatibility

Filament Page Header 2.x continues to support:

• PHP ^8.3
• Filament ^4.12.6 || ^5.8.1
• Laravel 12 and 13

Upgrade

Update normally with Composer:

composer update mortalkiller/filament-page-header

No Filament asset republish is required specifically for this release because no runtime CSS or JavaScript changed.

Documentation

Full documentation:

https://docs.pedromonteiro.dev/filament-page-header/

After this release is published, the release-documentation workflow will publish the exact v2.3.2 source to the 2.x documentation channel and update Latest when eligible.

Full changelog

v2.3.1...v2.3.2

v2.3.1

Patch release. No API changes.

Fixed

• PageHeaderPlugin::register() no longer registers its STYLES_AFTER render hook a
  second time when the plugin is registered twice on the same panel. Previously this
  emitted the page-header.css <link> twice in the document head.

  Panel::plugin() runs a plugin's register() before adding it to the panel's plugin
  map, so a second registration now returns early. The later instance still replaces the
  earlier one in the map, which means an application's own configuration remains
  authoritative regardless of registration order.

  This matters for packages that register PageHeaderPlugin on a panel on your behalf:
  registering your own configured instance alongside them is now safe in either order.

Upgrading: no action required.

v2.3.0

Filament Page Header v2.3.0

Filament Page Header 2.3 adds native Filament navigation support to the page header, including configurable breadcrumbs, Page/Resource sub-navigation, and compact-mode navigation control.

Existing headers keep their current behavior by default. Navigation features are opt-in.

What's new

Native header navigation

Breadcrumbs can now be positioned outside the header, inside the header, or hidden:

use MortalKiller\FilamentPageHeader\Enums\BreadcrumbPosition;

Header::make()
    ->breadcrumbs(BreadcrumbPosition::Inside);

Available positions:

• BreadcrumbPosition::Outside — default behavior
• BreadcrumbPosition::Inside
• BreadcrumbPosition::Hidden

Native Filament Page/Resource sub-navigation can now be moved into the page header:

Header::make()
    ->subNavigation();

The package continues to use Filament's native navigation data, including:

• URLs
• authorization
• active state
• icons and badges
• SPA navigation
• record sub-navigation
• ManageRelatedRecords

Relation Manager content tabs remain in their normal page-content location.

Compact navigation control

Breadcrumbs and sub-navigation can participate in the typed compact configuration:

use MortalKiller\FilamentPageHeader\CompactHeader;
use MortalKiller\FilamentPageHeader\Enums\HeaderPart;

Header::make()
    ->subNavigation()
    ->compact()
    ->whenCompact(fn (CompactHeader $compact) => $compact
        ->show(
            HeaderPart::Breadcrumbs,
            HeaderPart::SubNavigation,
        ));

New compact parts:

HeaderPart::Breadcrumbs
HeaderPart::SubNavigation

Native navigation blocks support show(). Field-level only() selection is intentionally not supported for navigation.

Refined desktop sub-navigation

Desktop sub-navigation now integrates directly into the header instead of looking like a second nested container.

The active tab:

• follows the panel primary color
• uses a simple underline
• aligns with the lower edge of the header
• keeps consistent spacing in expanded and compact layouts

Mobile continues to use Filament's native sub-navigation dropdown.

Keyboard focus is preserved when navigation would otherwise collapse in compact mode.

New documentation site

The package now has a dedicated Astro + Starlight documentation site:

https://docs.pedromonteiro.dev/filament-page-header/

It includes:

• installation and compatibility guides
• complete configuration documentation
• generator guide
• migration guide
• API reference
• local development guide
• testing guide
• roadmap
• security documentation

The API reference covers the main public package APIs including PageHeaderPlugin, Header, MetadataEntry, CompactHeader, HasPageHeader, HeaderOptions, and the package enums.

Documentation deployment

Documentation builds are now validated in GitHub Actions and automatically deployed from the 2.x branch.

Manual documentation deployment through workflow_dispatch is also supported.

Expanded test coverage

Navigation behavior is covered across PHP and browser tests, including:

• breadcrumbs inside, outside, and hidden
• native Page/Resource sub-navigation
• record sub-navigation
• ManageRelatedRecords
• Relation Manager coexistence
• SPA navigation
• compact-mode visibility
• desktop tabs and mobile dropdowns
• light and dark themes
• Livewire updates
• keyboard focus
• layout stability

Upgrade

Update the package:

composer update mortalkiller/filament-page-header

Then republish Filament assets:

php artisan filament:assets

Republishing assets is important because this release includes updated CSS and JavaScript for header navigation.

Compatibility

Filament Page Header 2.x supports:

• Filament ^4.12.6 || ^5.8.1
• PHP ^8.3
• Laravel 12 and 13

Full changelog

v2.2.0...v2.3.0

v2.2.0

v2.2.0 — Artisan page header generator

Added

• Added the new make:filament-page-header Artisan command for setting up page headers on existing Filament Resources.
• Added interactive selection of the Resource pages that should use HasPageHeader.
• Added support for explicit non-interactive page selection with repeated --page options.
• Added --panel support for applications with multiple Filament panels.
• Added --no-pages to generate the conventional header schema without modifying Resource page classes.
• Added --force to deliberately replace an existing generated header schema.

Example:

php artisan make:filament-page-header OrderResource

Or explicitly:

php artisan make:filament-page-header OrderResource \
    --panel=admin \
    --page=list \
    --page=view \
    --page=edit

The generator creates the conventional Resource header schema and safely adds HasPageHeader to the selected standard Resource pages without duplicating imports or trait declarations.

Documentation

• Added dedicated documentation for custom page header record contexts through getPageHeaderRecord().
• Added examples for tenant-backed pages.
• Added examples for parent-record contexts.
• Added examples for settings and singleton models.
• Added examples for custom Filament pages backed by an Eloquent model.
• Added support documentation for array-backed header contexts.
• Documented Create-page behavior when no persisted record exists.
• Documented multi-panel usage and clarified that the plugin must be registered separately on each panel that should use custom headers.
• Clarified that changing the header record context does not change Resource persistence, page authorization, action authorization, or application access rules.
• Added dedicated generator documentation covering interactive usage, non-interactive usage, multi-panel applications, existing schemas, and supported Resource page types.
• Added a public project roadmap documenting the planned direction for developer experience, header navigation, and action controls.

Improved

• Existing header schemas are preserved by default when the generator is run again.
• Resource resolution supports short names, fully-qualified class names, and multi-panel applications.
• Repeated generator runs avoid duplicate HasPageHeader imports and trait declarations.

Testing

• Added regression coverage for generator behavior, repeated execution, schema protection, page selection, and invalid option combinations.
• Improved browser asset-loading tests so they also work correctly from branch names containing /.
• Validated the package across the supported Filament 4 and Filament 5 test matrix.

Upgrade notes

This release is backwards compatible with existing 2.x applications.

No application code or configuration changes are required when upgrading.

After updating the package, continue to publish Filament assets as usual:

php artisan filament:assets

v2.1.5

Fixed

• Load the page header stylesheet in the initial document head instead of waiting for Alpine to request it.
• Prevent the visible layout shift that could occur while the header CSS was loading.
• Preserve lazy loading for the Alpine component while ensuring the header is styled before the first content paint.
• Keep the stylesheet scoped to Filament panels where the plugin is registered.
• Preserve correct stylesheet ordering after the panel theme.
• Fix action alignment compatibility with newer Filament 5 releases.

Improved

• Added regression coverage for initial rendering without JavaScript.
• Added browser coverage for delayed CSS and JavaScript loading.
• Added coverage for SPA navigation, panel isolation, stylesheet duplication, and theme precedence.
• Added compatibility coverage for Filament action alignment changes.

No application code or configuration changes are required when upgrading.

v2.1.4

Changed

• Replaced the previous package showcase image with the new dark-theme version.
• Updated the README to use the new filament-page-header-dark-2560x1440.jpg showcase.

This is a documentation-only release with no runtime, API, or dependency changes.