Filament Auto Filters Laravel Package

Product Decisions This Supports

• Build vs. buy for faceted filtering. The package already owns the "distinct values for a filter" problem; release 1.4.1 extends that to the presentation layer. That removes a common reason teams write bespoke option-building code (formatting currency, mapping enum keys to human labels, enforcing a display order), which shifts the build-vs-buy call toward buy for admin/reporting surfaces.
• Filter UX on the roadmap. You can now commit to user-facing filter dropdowns that read as product copy rather than raw database values — e.g. 12.50 => "$12.50", pending_review => "Pending review", plan tiers in lifecycle order rather than alphabetical. This is a shippable UX improvement, not just a developer convenience.
• Controlled ordering as a product lever. Because an associative map preserves the order you return, ordering becomes a deliberate product decision (value ascending, severity, pipeline stage) instead of incidental natural sort. Previously only the flat-list behavior (natural sort, value-as-label) was available.
• Performance guardrails stay intact. distinct_max_options still applies to the mapped format, so allowing rich labels doesn't open a new path to unbounded dropdowns. No new capacity or infra review is triggered by adopting the feature.
• Low-risk scope. This is an additive, opt-in change in a patch release. No breaking changes, no deprecations, no migration work — it can ride along with the next routine dependency bump rather than needing its own roadmap slot.

When to Consider This Package

Consider it when:

• You're on Laravel and need distinct option lists for filters/facets derived from existing data, with a bounded size enforced by configuration.
• Your option values are not self-explanatory to end users — money, enums, codes, IDs — and you need a label mapping at the point of option generation rather than a presentation layer downstream.
• You need deterministic ordering of options that reflects business logic, not alphabetical/natural sort.
• You want a single customization hook (distinctOptionsUsing) rather than per-endpoint formatting code, so label behavior stays consistent across screens.
• You can accept a synchronous, threshold-bounded option list.

Look elsewhere when:

• Option cardinality is unbounded or very large (tens of thousands of distinct values) — you want async search/typeahead backed by a search index (Scout + Meilisearch/Algolia, or a dedicated facet service) rather than a capped distinct query.
• You need multi-select counts alongside labels, hierarchical facets, or faceted counts that vary with other applied filters — that's a search-platform concern, not an option-list concern.
• You're not on Laravel, or you'd be adopting the package solely for this one hook (a handful of lines in your own code may be cheaper than a dependency).
• You need localization of labels at render time: the map is built where the options are built, so per-request locale switching, translation keys, or currency conversion need to be handled by you — verify the hook resolves against the current request/user context before relying on it.

Specific caution for 1.4.1: switching an option list from the flat format to the associative format silently drops blank values. If any legitimate option is represented by an empty string (e.g. an "unassigned"/"not set" bucket), that filter choice will disappear from the UI when you migrate to the map. Treat that as a product behavior change to QA on each list you convert, and decide whether "not set" needs a placeholder value rather than blank. Second, the map's order and labels are now yours to maintain — label drift (a renamed status, a stale currency format) becomes a product-owned defect rather than something the package normalizes for you.

How to Pitch It (Stakeholders)

For executives: A routine, additive patch to a dependency we use to generate filter options. It lets our filter dropdowns show human-readable, correctly formatted, deliberately ordered choices — dollar amounts instead of 12.5, "Pending review" instead of pending_review, pipeline stages in workflow order — without new backend work. No breaking changes, no migration, no added infrastructure; the existing cap on option counts still protects performance. Cost is a small amount of configuration plus QA on the specific filters we convert.

For engineering: Version 1.4.1 lets distinctOptionsUsing return an associative value => label map. Order and labels pass through untouched, blank values are discarded, and distinct_max_options is still enforced; returning a flat list preserves the current behavior exactly. Adoption is opt-in per option list, so we can convert filters incrementally and roll back one at a time. Two things to watch in review: (1) blank-valued options are dropped in map mode — confirm no "unset" facet is lost, and (2) labels and ordering are now our responsibility to keep accurate. Recommend converting the highest-traffic filters first and adding a test per converted list asserting the expected key/label pairs.