Meilifacets Laravel Package

Product Decisions This Supports

• Search and listing UX roadmap: 0.2.3 turns the faceted listing from a sidebar-filter pattern into a configurable storefront surface — default sort inheritance from WooCommerce, a « Show more » row overflow mode, and per-listing Blade card components. These are directly roadmap-visible features (merchandising, catalog browsing, mobile filter ergonomics) rather than internal plumbing.
• Build vs. buy on search: The package now covers WooCommerce default product sorting (server-side and in-browser, including under a variation filter) via Contracts\DefaultSortedListing. That is a strong argument to buy/extend this rather than build a bespoke Meilisearch + WooCommerce sorting layer, since sort semantics are a common source of parity bugs.
• Theming and design-system investments: Contracts\CardComponentListing and <x-meilifacets::listing.card> with CardBinding let each listing render through the project’s own Blade card component, on the server and in the browser-cloned template. That supports design-system consolidation decisions and reduces one-off markup per listing.
• Feature flag / configuration strategy: row-overflow="show-more" vs. the 0.2.2 default side-sheet, plus the renamed meilifacets.drawer.row.limit key, is a config-and-defaults decision. PMs should plan a deliberate rollout: keep side-sheet as fallback while validating « Show more » on high-traffic category pages.
• Release and upgrade planning: The upgrade requires wp meiliscout index, php artisan module:publish MeiliFacets, cache clearing, and a config key move from row_limit to row.limit. This is a planned maintenance window, not a hotfix — it affects release cadence and QA scope for any theme that copied results, drawer, or facets views.
• Risk tracking against user-facing gaps: The known-issues list (single-selection facet hiding other values, silent failed browser searches with stale URL filters, variant duplication in term counts, attribute archives not showing the browsed variant’s variant) feeds directly into support-load forecasts and “do not ship to these catalogs yet” decisions.

When to Consider This Package

Consider it when:

• You run WooCommerce on WordPress with a Laravel-adjacent toolchain (WP-CLI, php artisan, Composer, Blade components) and want Meilisearch-backed faceted product listings.
• You need merchandising parity: the listing should follow WooCommerce’s Appearance › Customize › WooCommerce › Product Catalog › Default product sorting, including when no sort is chosen and no term is searched, and under a variation filter.
• You want filters presented in the desktop row with an overflow pattern (« Show more » opening the same drawer as a side sheet), rather than a permanently docked sidebar.
• You want listings rendered through your project’s own card component, not a package-owned card, and you are willing to publish and maintain copied views.
• Your team can absorb a Beta-stage API contract and a reindex-and-republish upgrade cycle, and you can test against the specific known issues before exposing them to customers.

Look elsewhere or defer when:

• You need stable public APIs before 1.0 — the release explicitly warns that PHP classes, interfaces, and data-meili attributes may change.
• You depend on « Popularity » or « Average rating » as the listing default order; both are explicitly unsupported today.
• You rely on attribute archives (/pa_volume/400ml/) showing the browsed term’s variant — currently a documented “leave Enable archives? unchecked” limitation.
• You need robust no-JavaScript fallback for the drawer: past the row limit on a wide screen, the side sheet requires the browser client, and « Filters » / « Show more » will open nothing if it fails to start.
• You operate high-volume imports or bulk edits — saving a product reindexes once per WooCommerce meta write and resends index settings each pass, which can leave the engine’s queue behind; the fix is scoped to MeiliScout, not this package.
• Your theme has moved the drawer’s media past 48em and would need to redeclare the side sheet block, or has heavily customized copied results, drawer, or facets views that you cannot re-copy on this cadence.

How to Pitch It (Stakeholders)

For executives: This release makes the product listing behave more like the storefront merchandising team expects — it inherits WooCommerce’s default product sorting, supports a « Show more » filter row on desktop, and renders results through our own card component. It is a capability release on a Beta package, so the recommendation is a scoped pilot on selected category pages, not a storefront-wide switch, until the documented issues around single-selection facets, failed-search messaging, and attribute archives are resolved.

For engineering: Plan this as a coordinated upgrade: composer update pollora/meilifacets, wp meiliscout index, php artisan module:publish MeiliFacets, then clear page cache. The breaking surface is narrow but real — move meilifacets.drawer.row_limit to meilifacets.drawer.row.limit, re-copy any theme overrides of results, drawer, or facets, replace :card with :binding="CardBinding::of($card)" on <x-meilifacets::listing.card>, drop listing.card-template, and update any .meilifacetsFacets[data-apply] selector to target the listing root. Optional: use CardBinding::standalone($card) for cards outside a listing. Treat the PHP contracts and data-meili attributes as unstable until 1.0, and keep row-overflow="side-sheet" as the fallback default while « Show more » is validated.

For product and support: Set expectations that this is a Beta with known gaps: a chosen single-selection facet hides its sibling values, a failed browser search shows no message while the URL keeps the unapplied filter, variants sharing a term count once per variant, and attribute archives do not show the browsed term’s variant. Budget QA for these specific paths and hold « Show more » and card-component rollouts behind a feature flag until they pass.