feat: Add strict hierarchical breadcrumbs option

[ahmed-rashad-alnaggar]

Summary

Closes discussion #19515.

Adds an opt-in strict hierarchical breadcrumbs mode, configurable per-panel via Panel::breadcrumbs():

$panel->breadcrumbs(strictHierarchical: true);

By default, breadcrumbs for a page are built from its resource and parent record relationships (e.g. an EditRecord page's breadcrumbs come from its resource's list/view pages, plus any parent resources for nested resources). When strict hierarchical mode is enabled, breadcrumbs are instead (additionally) built by walking the page's full navigational hierarchy — cluster ancestry, navigation group, and navigation parent item — and combining that chain with the existing resource/parent-record breadcrumbs.

Changes

• Filament\Panel\Concerns\HasBreadcrumbs: extended breadcrumbs() with a second bool|Closure $strictHierarchical = false parameter, and added hasStrictHierarchicalBreadcrumbs() alongside the existing hasBreadcrumbs().
• Filament\Pages\Page: added $breadcrumb property, getBreadcrumb(), and getHierarchicalBreadcrumbs(), which recursively resolves cluster, navigation group, and navigation parent item breadcrumbs for a page. getBreadcrumbs() now checks Filament::getCurrentOrDefaultPanel()->hasStrictHierarchicalBreadcrumbs() and prepends the hierarchical chain when enabled.
• Filament\Resources\Pages\Page: getResourceBreadcrumbs() now checks strict mode first and, when enabled, prepends static::getHierarchicalBreadcrumbs() ahead of the existing resource/parent-record breadcrumbs; falls back to the previous cluster-only behavior otherwise.

Behavior

• Strict mode disabled (default): unchanged — breadcrumbs resolve exactly as before, via cluster + resource/parent-record relationships.
• Strict mode enabled: breadcrumbs are [...hierarchical chain, ...resource/parent-record breadcrumbs, page's own breadcrumb]. The hierarchical chain and resource/record breadcrumbs are combined, not one replacing the other.

[ahmed-rashad-alnaggar]

Before this potentially gets merged, I wanted to float an idea for feedback.

Right now strictHierarchical only affects breadcrumbs. I was thinking it might make sense to generalize this into a panel-wide "strict hierarchical navigation" concept, rather than a breadcrumbs-only flag — so the same setting also governs URL/slug generation (e.g. nesting a resource's slug under its navigation parent item / group / cluster), keeping breadcrumbs and slugs consistent with each other instead of having them independently configurable and potentially out of sync.

Something like:

$panel->strictHierarchicalNavigation(true);

which hasStrictHierarchicalBreadcrumbs() (and a future slug-generation check) would both read from, instead of breadcrumbs having its own separate toggle.

Wanted to raise this in case it changes the shape of the API here — happy to rework this PR to fit that direction if it seems worth pursuing, or keep it scoped to breadcrumbs only if slugs should stay a separate concern. Let me know what you think.

[danharrin]

Just a heads up: I don't think I am going to have time to properly review and test this before the next minor release, which is very close to release already.

[ahmed-rashad-alnaggar]

Converting to draft to fix bugs regarding clusters and sub navigation.

[ahmed-rashad-alnaggar]

Fixed!