@akinon/pz-theme 2.0.37-beta.0 → 2.0.37

package/src/blocks/facet-filters-block.tsx

@@ -0,0 +1,1686 @@
+'use client';
+
+import React, { useEffect, useRef, useState } from 'react';
+import { usePathname, useRouter, useSearchParams } from 'next/navigation';
+import { useLocalization } from '@akinon/next/hooks';
+import { getResponsiveValue, partAttrs } from '../utils';
+import { useOverlay } from '../hooks/use-overlay';
+import { hasItemTemplate, ItemTemplateList } from './item-template';
+import { BlockRendererProps } from './block-renderer-registry';
+import {
+  buildListingHref,
+  listingPlaceholderStyle,
+  readToggle,
+  useListingContext,
+  ListingFacet,
+  ListingFacetChoice
+} from './listing-context';
+
+type ToggleIconVariant = 'chevron' | 'plus' | 'none';
+
+const TOGGLE_ICON_VARIANTS: ToggleIconVariant[] = ['chevron', 'plus', 'none'];
+
+type TriggerIconVariant = 'funnel' | 'sliders' | 'none';
+
+const TRIGGER_ICON_VARIANTS: TriggerIconVariant[] = [
+  'funnel',
+  'sliders',
+  'none'
+];
+
+const clampNumber = (
+  value: unknown,
+  fallback: number,
+  min: number,
+  max: number
+) => {
+  const numeric = Math.round(Number(value));
+  if (!Number.isFinite(numeric)) return fallback;
+  return Math.min(max, Math.max(min, numeric));
+};
+
+const OPTION_ORDERS = [
+  'default',
+  'label-asc',
+  'label-desc',
+  'count-desc'
+] as const;
+
+type OptionOrder = (typeof OPTION_ORDERS)[number];
+
+/**
+ * The affordance next to a collapsible group heading. `chevron` is the shipped
+ * look; `plus` is the second most asked for and `none` lets a brand rely on
+ * the heading alone.
+ */
+const ToggleIcon = ({
+  variant,
+  isCollapsed
+}: {
+  variant: ToggleIconVariant;
+  isCollapsed: boolean;
+}) => {
+  if (variant === 'none') return null;
+
+  if (variant === 'plus') {
+    return (
+      <svg
+        width="14"
+        height="14"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="1.8"
+        {...partAttrs('icon', { open: !isCollapsed })}
+      >
+        <path d="M4 12h16" />
+        {isCollapsed && <path d="M12 4v16" />}
+      </svg>
+    );
+  }
+
+  return (
+    <svg
+      width="14"
+      height="14"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.8"
+      {...partAttrs('icon', { open: !isCollapsed })}
+      style={{
+        transform: isCollapsed ? 'none' : 'rotate(180deg)',
+        transition: 'transform 150ms'
+      }}
+    >
+      <path d="M6 9l6 6 6-6" />
+    </svg>
+  );
+};
+
+/**
+ * The glyph on the panel trigger. Both audited designs pair a mark with the
+ * word ("Filtrele", "Filtre & Sıralama"), and the two marks in circulation are
+ * the funnel and the slider stack — so both ship, and `none` leaves the word
+ * alone.
+ */
+const TriggerIcon = ({ variant }: { variant: TriggerIconVariant }) => {
+  if (variant === 'none') return null;
+
+  return (
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.8"
+      strokeLinecap="round"
+      aria-hidden="true"
+      {...partAttrs('trigger-icon')}
+    >
+      {variant === 'sliders' ? (
+        <>
+          <path d="M4 7h16M4 12h16M4 17h16" />
+          <circle cx="9" cy="7" r="2" fill="currentColor" stroke="none" />
+          <circle cx="15" cy="12" r="2" fill="currentColor" stroke="none" />
+          <circle cx="8" cy="17" r="2" fill="currentColor" stroke="none" />
+        </>
+      ) : (
+        <path d="M3 5h18l-7 8v6l-4 2v-8L3 5z" strokeLinejoin="round" />
+      )}
+    </svg>
+  );
+};
+
+const CloseIcon = () => (
+  <svg
+    width="18"
+    height="18"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="1.8"
+    strokeLinecap="round"
+    aria-hidden="true"
+  >
+    <path d="M6 6l12 12M18 6L6 18" />
+  </svg>
+);
+
+/**
+ * Facet keys a designer typed. Free text on purpose: the keys are the brand's
+ * own attribute names, so no fixed list could offer the right ones. Commas and
+ * newlines both separate, because a designer will use either.
+ */
+const readFacetKeys = (value: unknown, currentBreakpoint: string): string[] =>
+  String(getResponsiveValue(value, currentBreakpoint, '') ?? '')
+    .split(/[,\n]/)
+    .map((key) => key.trim().toLowerCase())
+    .filter(Boolean);
+
+const orderChoices = (
+  choices: ListingFacetChoice[],
+  order: OptionOrder,
+  locale?: string
+): ListingFacetChoice[] => {
+  if (order === 'default') return choices;
+
+  // Copied before sorting: the array belongs to the memoised listing context
+  // and sorting in place would reorder it for every other block too.
+  const sorted = choices.slice();
+
+  if (order === 'count-desc') {
+    sorted.sort((a, b) => b.quantity - a.quantity);
+    return sorted;
+  }
+
+  const direction = order === 'label-desc' ? -1 : 1;
+  // The locale is explicit: an implicit collation resolves to the Node default
+  // on the server and the browser's on the client, which reorders the list
+  // between SSR and hydration.
+  sorted.sort(
+    (a, b) => direction * String(a.label).localeCompare(String(b.label), locale)
+  );
+  return sorted;
+};
+
+/**
+ * A count template is the designer's own wording — "({count})", "· {count}",
+ * "{count} selected". A template that forgot the placeholder still has to show
+ * the number, so it is appended rather than dropped.
+ */
+const formatCount = (template: string, count: number): string =>
+  template.includes('{count}')
+    ? template.replace('{count}', String(count))
+    : `${template} ${count}`.trim();
+
+/**
+ * Sorted `key=value` pairs, for comparing two querystrings by CONTENT.
+ * Staging rebuilds the query by delete+append, so a value the shopper toggled
+ * on and back off comes out in a different order than the URL it started from
+ * — a raw string compare would report a pending change that is not there.
+ *
+ * `Array.sort()` with no comparator, never a collator: this is an equality
+ * probe, not a list anyone reads, and a locale-aware sort would answer
+ * differently on the server than in the browser.
+ */
+const sortedQueryEntries = (query: string): string =>
+  Array.from(new URLSearchParams(query).entries())
+    .map(([key, value]) => `${key}=${value}`)
+    .sort()
+    .join('&');
+
+const sameQuery = (a: string, b: string): boolean =>
+  sortedQueryEntries(a) === sortedQueryEntries(b);
+
+/**
+ * The same comparison with the page cursor left out of both sides. Staging
+ * drops the cursor on every toggle because a filter change invalidates it —
+ * correct on the way out, but its absence is not itself something to commit.
+ * Counted as a difference it lights the Apply button up on a panel that
+ * differs in nothing, and committing then throws a shopper on page 4 back to
+ * page 1 having changed nothing.
+ */
+const sameFilterQuery = (a: string, b: string, pageKey: string): boolean => {
+  const withoutPage = (query: string): string => {
+    const params = new URLSearchParams(query);
+    // An empty key is "this composition has no cursor to ignore", not a
+    // parameter named "" — see `pageQueryParam` below.
+    if (pageKey) params.delete(pageKey);
+    return params.toString();
+  };
+
+  return sameQuery(withoutPage(a), withoutPage(b));
+};
+
+/** What the property falls back to when a facet has claimed the typed key. */
+const DEFAULT_PAGE_QUERY_PARAM = 'page';
+
+/**
+ * The designer's preferred facet order. Commerce decides the order it returns
+ * facets in, and a brand that wanted size above colour had no way to say so
+ * short of one block per facet with the styling duplicated on each. Named
+ * facets come first in the order given; the rest keep commerce's order behind
+ * them, so naming one facet does not reshuffle the others.
+ */
+const orderFacets = (
+  facets: ListingFacet[],
+  order: string[]
+): ListingFacet[] => {
+  if (order.length === 0) return facets;
+
+  const rankOf = (facet: ListingFacet): number => {
+    // Key or display name, the same pair `includeFacets` matches on: a
+    // designer reads "Beden" off the page, not "attributes_size".
+    const identity = [facet.key, facet.name].map((value) =>
+      String(value || '').toLowerCase()
+    );
+    const rank = order.findIndex((key) => identity.includes(key));
+    return rank === -1 ? Number.MAX_SAFE_INTEGER : rank;
+  };
+
+  return facets
+    .map((facet, index) => ({ facet, index, rank: rankOf(facet) }))
+    // The original index is the tiebreak, so the unnamed facets keep the order
+    // commerce sent rather than whatever the sort happens to do with equal ranks.
+    .sort((a, b) => a.rank - b.rank || a.index - b.index)
+    .map((entry) => entry.facet);
+};
+
+/**
+ * Functional listing block: commerce facets/filters. Facet CONTENT and the
+ * querystring keys are commerce-driven (`search_key` per facet, exactly as
+ * the category API returns them); the editor owns layout, ordering, wording
+ * and styling.
+ *
+ * A child marked as the item template replaces the option ROW, repeated inside
+ * every group, so headings, collapsing and "show more" keep working around it.
+ *
+ * The `panel` layout renders ONLY a trigger and opens the same groups in a
+ * drawer or modal over the page — the arrangement both audited brand designs
+ * use, where the toolbar shows a word plus a glyph and the facets live behind
+ * it. Every other layout is untouched.
+ *
+ * Parts: list, group, label, selected-count, icon, option-list, option-search,
+ * no-match, option, checkbox, count, show-more, panel, trigger, trigger-icon,
+ * trigger-count, backdrop, panel-header, panel-title, close, panel-footer,
+ * clear, apply.
+ * Properties: layout, collapsible, defaultCollapsed, toggleIcon, showCounts,
+ * countTemplate, showCheckbox, optionOrder, hideZeroCounts, maxVisibleOptions,
+ * showMoreLabel, showLessLabel, pageQueryParam, triggerLabel, triggerIcon,
+ * panelMode, panelSide, panelWidth, showPanelHeader, panelTitle, showClose,
+ * closeLabel, showBackdrop, closeOnBackdrop, closeOnEscape, lockScroll,
+ * showClear, clearLabel, showApply, applyLabel, applyMode, facetOrder,
+ * showOptionSearch, optionSearchLabel, optionSearchMinOptions, noMatchLabel,
+ * showSelectedCount, selectedCountTemplate, showTriggerCount,
+ * triggerCountTemplate, showDropdownClose, closeOnOutsideClick.
+ */
+const FacetFiltersBlock = ({
+  block,
+  placeholderId,
+  sectionId,
+  selectedBlockId = null,
+  currentBreakpoint = 'desktop',
+  isDesigner = false
+}: BlockRendererProps) => {
+  const listing = useListingContext();
+  const router = useRouter();
+  const pathname = usePathname();
+  const searchParams = useSearchParams();
+  const { locale } = useLocalization();
+  const [collapsedKeys, setCollapsedKeys] = useState<Record<string, boolean>>(
+    {}
+  );
+  const [expandedKeys, setExpandedKeys] = useState<Record<string, boolean>>({});
+  const [searchTerms, setSearchTerms] = useState<Record<string, string>>({});
+  /**
+   * The querystring the shopper has built but not committed, or null when
+   * nothing is staged and the URL is the truth. A string rather than a
+   * URLSearchParams so React's identity check actually compares the value.
+   */
+  const [stagedQuery, setStagedQuery] = useState<string | null>(null);
+  // Closed on load, in the designer too: the author opens it from the trigger
+  // and the panel is then a real, stylable element on the canvas.
+  const [panelOpen, setPanelOpen] = useState(false);
+  const triggerRef = useRef<HTMLButtonElement | null>(null);
+  const rootRef = useRef<HTMLDivElement | null>(null);
+
+  const layout = String(
+    getResponsiveValue(block.properties?.layout, currentBreakpoint, 'sidebar')
+  );
+  // Which facets this block shows. A brand puts the same block on the page
+  // twice — once as the subcategory row across the top, once as the rail —
+  // and each instance names the facets it owns. Empty means all of them,
+  // which is what every published composition has.
+  const includeFacets = readFacetKeys(
+    block.properties?.includeFacets,
+    currentBreakpoint
+  );
+  const excludeFacets = readFacetKeys(
+    block.properties?.excludeFacets,
+    currentBreakpoint
+  );
+  // Empty means "however commerce sent them", which is what every published
+  // composition renders today.
+  const facetOrder = readFacetKeys(
+    block.properties?.facetOrder,
+    currentBreakpoint
+  );
+  const showAllOption = readToggle(
+    block.properties?.showAllOption,
+    currentBreakpoint,
+    false
+  );
+  const allLabel = String(
+    getResponsiveValue(block.properties?.allLabel, currentBreakpoint, 'All')
+  );
+  const collapsible = readToggle(
+    block.properties?.collapsible,
+    currentBreakpoint,
+    true
+  );
+  const defaultCollapsed = readToggle(
+    block.properties?.defaultCollapsed,
+    currentBreakpoint,
+    false
+  );
+  const showCounts = readToggle(
+    block.properties?.showCounts,
+    currentBreakpoint,
+    true
+  );
+  const showCheckbox = readToggle(
+    block.properties?.showCheckbox,
+    currentBreakpoint,
+    true
+  );
+  const hideZeroCounts = readToggle(
+    block.properties?.hideZeroCounts,
+    currentBreakpoint,
+    false
+  );
+  const countTemplate = String(
+    getResponsiveValue(
+      block.properties?.countTemplate,
+      currentBreakpoint,
+      '({count})'
+    )
+  );
+  const toggleIconRaw = String(
+    getResponsiveValue(block.properties?.toggleIcon, currentBreakpoint, 'chevron')
+  );
+  const toggleIcon = (
+    TOGGLE_ICON_VARIANTS.includes(toggleIconRaw as ToggleIconVariant)
+      ? toggleIconRaw
+      : 'chevron'
+  ) as ToggleIconVariant;
+  const optionOrderRaw = String(
+    getResponsiveValue(block.properties?.optionOrder, currentBreakpoint, 'default')
+  );
+  const optionOrder = (
+    OPTION_ORDERS.includes(optionOrderRaw as OptionOrder)
+      ? optionOrderRaw
+      : 'default'
+  ) as OptionOrder;
+  const maxVisibleRaw = Math.round(
+    Number(
+      getResponsiveValue(block.properties?.maxVisibleOptions, currentBreakpoint, 0)
+    )
+  );
+  // 0 means "no cap", which is what every published composition renders today.
+  const maxVisibleOptions =
+    Number.isFinite(maxVisibleRaw) && maxVisibleRaw > 0 ? maxVisibleRaw : 0;
+  const showMoreLabel = String(
+    getResponsiveValue(
+      block.properties?.showMoreLabel,
+      currentBreakpoint,
+      'Show more'
+    )
+  );
+  const showLessLabel = String(
+    getResponsiveValue(
+      block.properties?.showLessLabel,
+      currentBreakpoint,
+      'Show less'
+    )
+  );
+  const pageQueryParamRaw = String(
+    getResponsiveValue(
+      block.properties?.pageQueryParam,
+      currentBreakpoint,
+      DEFAULT_PAGE_QUERY_PARAM
+    )
+  );
+  // A sixty-option colour or brand facet is unusable without one; off by
+  // default because no published composition has ever drawn an input here.
+  const showOptionSearch = readToggle(
+    block.properties?.showOptionSearch,
+    currentBreakpoint,
+    false
+  );
+  const optionSearchLabel = String(
+    getResponsiveValue(
+      block.properties?.optionSearchLabel,
+      currentBreakpoint,
+      'Search'
+    )
+  );
+  const optionSearchMinRaw = Math.round(
+    Number(
+      getResponsiveValue(
+        block.properties?.optionSearchMinOptions,
+        currentBreakpoint,
+        0
+      )
+    )
+  );
+  // 0 means "every group", which is what turning the toggle on plainly implies.
+  const optionSearchMinOptions =
+    Number.isFinite(optionSearchMinRaw) && optionSearchMinRaw > 0
+      ? optionSearchMinRaw
+      : 0;
+  const noMatchLabel = String(
+    getResponsiveValue(block.properties?.noMatchLabel, currentBreakpoint, 'No matches')
+  );
+  const showSelectedCount = readToggle(
+    block.properties?.showSelectedCount,
+    currentBreakpoint,
+    false
+  );
+  const selectedCountTemplate = String(
+    getResponsiveValue(
+      block.properties?.selectedCountTemplate,
+      currentBreakpoint,
+      '({count})'
+    )
+  );
+  // Dropdown layout only: the floating panel had no way out of its own.
+  const showDropdownClose = readToggle(
+    block.properties?.showDropdownClose,
+    currentBreakpoint,
+    false
+  );
+  const closeOnOutsideClick = readToggle(
+    block.properties?.closeOnOutsideClick,
+    currentBreakpoint,
+    false
+  );
+
+  // Panel layout only. Read unconditionally so the hook order never depends on
+  // the layout a breakpoint resolved to.
+  const triggerLabel = String(
+    getResponsiveValue(block.properties?.triggerLabel, currentBreakpoint, 'Filters')
+  );
+  const triggerIconRaw = String(
+    getResponsiveValue(block.properties?.triggerIcon, currentBreakpoint, 'funnel')
+  );
+  const triggerIcon = (
+    TRIGGER_ICON_VARIANTS.includes(triggerIconRaw as TriggerIconVariant)
+      ? triggerIconRaw
+      : 'funnel'
+  ) as TriggerIconVariant;
+  const panelMode = String(
+    getResponsiveValue(block.properties?.panelMode, currentBreakpoint, 'drawer')
+  );
+  const panelSide = String(
+    getResponsiveValue(block.properties?.panelSide, currentBreakpoint, 'right')
+  );
+  const panelWidth = clampNumber(
+    getResponsiveValue(block.properties?.panelWidth, currentBreakpoint, 360),
+    360,
+    240,
+    720
+  );
+  const panelTitle = String(
+    getResponsiveValue(block.properties?.panelTitle, currentBreakpoint, 'Filters')
+  );
+  const closeLabel = String(
+    getResponsiveValue(block.properties?.closeLabel, currentBreakpoint, 'Close')
+  );
+  const clearLabel = String(
+    getResponsiveValue(block.properties?.clearLabel, currentBreakpoint, 'Clear all')
+  );
+  const applyLabel = String(
+    getResponsiveValue(block.properties?.applyLabel, currentBreakpoint, 'Apply')
+  );
+  const showPanelHeader = readToggle(
+    block.properties?.showPanelHeader,
+    currentBreakpoint,
+    true
+  );
+  const showClose = readToggle(
+    block.properties?.showClose,
+    currentBreakpoint,
+    true
+  );
+  const showBackdrop = readToggle(
+    block.properties?.showBackdrop,
+    currentBreakpoint,
+    true
+  );
+  const closeOnBackdrop = readToggle(
+    block.properties?.closeOnBackdrop,
+    currentBreakpoint,
+    true
+  );
+  const closeOnEscape = readToggle(
+    block.properties?.closeOnEscape,
+    currentBreakpoint,
+    true
+  );
+  const lockScroll = readToggle(
+    block.properties?.lockScroll,
+    currentBreakpoint,
+    true
+  );
+  const showClear = readToggle(
+    block.properties?.showClear,
+    currentBreakpoint,
+    false
+  );
+  const showApply = readToggle(
+    block.properties?.showApply,
+    currentBreakpoint,
+    false
+  );
+  const showTriggerCount = readToggle(
+    block.properties?.showTriggerCount,
+    currentBreakpoint,
+    false
+  );
+  const triggerCountTemplate = String(
+    getResponsiveValue(
+      block.properties?.triggerCountTemplate,
+      currentBreakpoint,
+      '({count})'
+    )
+  );
+  const applyMode = String(
+    getResponsiveValue(block.properties?.applyMode, currentBreakpoint, 'immediate')
+  );
+
+  /**
+   * Staging is opt-in, panel-only, and dead without an Apply button.
+   *
+   * Published compositions apply a choice the moment it is picked and the
+   * descriptor promised exactly that, so the URL must keep being written on
+   * the tick unless a designer deliberately asks for the other behaviour.
+   * `showApply` is part of the gate rather than a separate warning: staging
+   * with no way to commit would strand the shopper with a panel that filters
+   * nothing.
+   */
+  const layoutIsPanel = layout === 'panel';
+  const layoutIsDropdown = layout === 'dropdown';
+  const stagedApply = layoutIsPanel && showApply && applyMode === 'staged';
+
+  // Every way out of the panel is a designer toggle, so a composition can
+  // legally have all of them off and seal a shopper inside. Only a POINTER
+  // route counts here — Escape does not exist on the phone where this layout
+  // is used most — and when none survives the header and its close button are
+  // forced back on and Escape re-armed. An authored composition must never be
+  // a trap, so this cannot be toggled away.
+  const hasPointerDismissRoute =
+    (showPanelHeader && showClose) ||
+    (showBackdrop && closeOnBackdrop) ||
+    showApply;
+  const panelHeaderVisible = showPanelHeader || !hasPointerDismissRoute;
+  const closeVisible = showClose || !hasPointerDismissRoute;
+  const escapeClosesPanel = closeOnEscape || !hasPointerDismissRoute;
+
+  /**
+   * Escape, the scroll lock, the focus trap, returning focus to the trigger
+   * and the `aria-modal` claim are the shared overlay primitive's, not this
+   * block's.
+   *
+   * They used to be three effects here, and the focus trap among them
+   * registered a DOCUMENT-level `focusin` listener that pulled focus back into
+   * THIS panel. A listing page routinely has a second panel up at the same
+   * time — a store panel, a size picker, a quick view — and two such listeners
+   * each read the other's panel as "outside" and pulled against each other
+   * until the tab died with a call-stack overflow. The primitive keeps one
+   * stack for the page: only the overlay on top traps focus, claims
+   * `aria-modal` and answers Escape, and the scroll lock is counted across
+   * every block instead of captured per block.
+   *
+   * `modal` is `showBackdrop` because the panel only actually covers the page
+   * when a backdrop is drawn; without one the page underneath stays clickable
+   * (see the root's pointer-events), so the claim would be the opposite of
+   * what is true and the trap would have nothing to trap against.
+   *
+   * `manageFocus` is on regardless: a dialog that never receives focus leaves
+   * a keyboard or screen-reader shopper parked on the trigger while the panel
+   * they just opened is out of reach, and that is as true of the backdropless
+   * panel as of the modal one.
+   *
+   * `isDesigner` keeps all of it inert — on the canvas the panel is held open
+   * to be styled, and nothing may steal focus into the iframe, freeze the page
+   * being styled, or close the thing the author is working on.
+   */
+  const overlay = useOverlay<HTMLDivElement>({
+    open: panelOpen,
+    onClose: () => setPanelOpen(false),
+    isDesigner,
+    modal: showBackdrop,
+    lockScroll,
+    closeOnEscape: escapeClosesPanel,
+    manageFocus: true,
+    returnFocusRef: triggerRef
+  });
+
+  const appliedQuery = searchParams ? searchParams.toString() : '';
+
+  useEffect(() => {
+    /**
+     * Opening the panel, closing it, and a URL written from anywhere else all
+     * mean the same thing: the staging slate starts empty. A shopper who
+     * backs out of the panel — backdrop, Escape, the close button — must not
+     * find their abandoned choice still ticked the next time they open it,
+     * and must never have it applied behind their back.
+     */
+    setStagedQuery(null);
+  }, [panelOpen, appliedQuery]);
+
+  useEffect(() => {
+    // Only the dropdown floats over the page and so can be dismissed by
+    // clicking past it; every other layout sits in flow. Skipped in the
+    // designer, where a click on the canvas is the author selecting an
+    // element, not a shopper dismissing a menu.
+    if (!layoutIsDropdown || !closeOnOutsideClick || isDesigner) return undefined;
+
+    const handlePointerDown = (event: MouseEvent) => {
+      const root = rootRef.current;
+      if (!root || root.contains(event.target as Node)) return;
+
+      // Back to every group's default, which for a dropdown is closed. Bailing
+      // out when nothing is open keeps an unrelated click from re-rendering.
+      setCollapsedKeys((current) =>
+        Object.values(current).some((collapsed) => collapsed === false)
+          ? {}
+          : current
+      );
+    };
+
+    document.addEventListener('mousedown', handlePointerDown);
+    return () => document.removeEventListener('mousedown', handlePointerDown);
+  }, [layoutIsDropdown, closeOnOutsideClick, isDesigner]);
+
+  const allFacets = listing?.facets || [];
+
+  /**
+   * The page cursor, refused when a facet already owns the key.
+   *
+   * `pageQueryParam` is free text, and a merchant who types a facet's own
+   * `search_key` into it turns every "drop the cursor" into "drop that
+   * filter": the key comes off each href this block writes, and — because the
+   * staged-versus-applied comparison ignores it on BOTH sides — a genuine
+   * choice under that facet compares equal, so Apply commits nothing and just
+   * shuts the panel on the shopper.
+   *
+   * Commerce owns the search keys, so a collision means the property is wrong,
+   * not the facet. Falling back to the shipped default keeps a real cursor
+   * being dropped on a filter change; an empty key (the default is claimed
+   * too) means this listing has no cursor to drop, which is strictly better
+   * than erasing a filter.
+   */
+  const pageQueryParam = allFacets.some(
+    (facet) => facet.searchKey === pageQueryParamRaw
+  )
+    ? allFacets.some((facet) => facet.searchKey === DEFAULT_PAGE_QUERY_PARAM)
+      ? ''
+      : DEFAULT_PAGE_QUERY_PARAM
+    : pageQueryParamRaw;
+
+  /** Drops the page cursor, when this composition has one to drop. */
+  const deletePageCursor = (params: URLSearchParams): URLSearchParams => {
+    if (pageQueryParam) params.delete(pageQueryParam);
+    return params;
+  };
+
+  const facets = allFacets.filter((facet) => {
+    // Both the key and the display name are matched: a designer reads the name
+    // off the page ("Beden"), not the internal key ("attributes_size").
+    const identity = [facet.key, facet.name].map((value) =>
+      String(value || '').toLowerCase()
+    );
+    const named = (keys: string[]) =>
+      keys.some((key) => identity.includes(key));
+
+    if (includeFacets.length > 0 && !named(includeFacets)) return false;
+
+    return !named(excludeFacets);
+  });
+
+  const orderedFacets = orderFacets(facets, facetOrder);
+
+  /**
+   * The staged querystring parsed, or null when nothing is staged. Read from
+   * `stagedApply` as well as the state so a stale string can never leak into a
+   * composition that applies as you pick.
+   */
+  const stagedParams =
+    stagedApply && stagedQuery !== null ? new URLSearchParams(stagedQuery) : null;
+
+  /** Where the next toggle is computed from: the staged query, else the URL. */
+  const pendingParams = (): URLSearchParams =>
+    new URLSearchParams(stagedQuery !== null ? stagedQuery : appliedQuery);
+
+  /**
+   * What the shopper's tick shows right now. Applied selection is commerce's
+   * answer (`isSelected`) rather than a re-reading of the URL — commerce
+   * normalises values and is the one that decided what the page is filtered
+   * by. Only while staging does the pending query take over.
+   */
+  const isChoicePending = (
+    facet: ListingFacet,
+    choice: ListingFacetChoice
+  ): boolean =>
+    stagedParams
+      ? stagedParams.getAll(facet.searchKey).includes(choice.value)
+      : choice.isSelected;
+
+  /** Toggles one choice inside the given params, in place. */
+  const toggleChoiceParams = (
+    params: URLSearchParams,
+    facet: ListingFacet,
+    choice: ListingFacetChoice,
+    isSelected: boolean
+  ): URLSearchParams => {
+    // Any filter change invalidates the current page cursor.
+    deletePageCursor(params);
+
+    if (facet.widgetType === 'multiselect') {
+      const existing = params.getAll(facet.searchKey);
+      const next = existing.includes(choice.value)
+        ? existing.filter((value) => value !== choice.value)
+        : existing.concat(choice.value);
+
+      params.delete(facet.searchKey);
+      next.forEach((value) => params.append(facet.searchKey, value));
+    } else if (isSelected) {
+      params.delete(facet.searchKey);
+    } else {
+      params.set(facet.searchKey, choice.value);
+    }
+
+    return params;
+  };
+
+  /**
+   * The URL that toggles one choice. Split out from the click handler so a
+   * designer-authored option row can bind a link to `item.url` and still
+   * filter — a custom row has no way to reach the handler.
+   */
+  const hrefForChoice = (
+    facet: ListingFacet,
+    choice: ListingFacetChoice
+  ): string =>
+    buildListingHref(
+      pathname || listing?.path || '',
+      toggleChoiceParams(
+        new URLSearchParams(appliedQuery),
+        facet,
+        choice,
+        choice.isSelected
+      )
+    );
+
+  /** The same page with this facet dropped — what the "All" link points at. */
+  const hrefForReset = (facet: ListingFacet): string => {
+    const params = deletePageCursor(new URLSearchParams(appliedQuery));
+    params.delete(facet.searchKey);
+
+    return buildListingHref(pathname || listing?.path || '', params);
+  };
+
+  const handleSelect = (facet: ListingFacet, choice: ListingFacetChoice) => {
+    // Navigating inside the designer iframe would drop the author out of the
+    // page they are editing, so clicks are inert there.
+    if (isDesigner) return;
+
+    if (stagedApply) {
+      // On a phone over a slow connection, a fetch per tap is the whole
+      // problem the Apply button exists to solve. Nothing reaches the URL
+      // until the shopper commits.
+      setStagedQuery(
+        toggleChoiceParams(
+          pendingParams(),
+          facet,
+          choice,
+          isChoicePending(facet, choice)
+        ).toString()
+      );
+      return;
+    }
+
+    router.push(hrefForChoice(facet, choice));
+  };
+
+  // A designer can author the option row itself. The template repeats inside
+  // each group rather than replacing the groups, so the headings, the collapse
+  // behaviour and the "show more" affordance keep working around it.
+  const hasCustomOption = hasItemTemplate(block, currentBreakpoint);
+
+  if (facets.length === 0) {
+    return isDesigner ? (
+      <div data-facet-filters="" style={listingPlaceholderStyle}>
+        Filters (no facet data)
+      </div>
+    ) : null;
+  }
+
+  // `panel` renders the trigger only; the groups below are drawn inside the
+  // drawer/modal instead of in the page flow.
+  const isPanel = layout === 'panel';
+  // `dropdown` is a topbar whose options live in a panel that opens over the
+  // grid instead of pushing it down — the arrangement most brands ask for on a
+  // listing page, where a left rail costs too much width.
+  const isDropdown = !isPanel && layout === 'dropdown';
+  // A row of links, which is how a brand puts its subcategories across the top
+  // of a listing. They are anchors rather than buttons on purpose: this row is
+  // navigation — a crawler has to follow it, and a shopper has to be able to
+  // open one in a new tab.
+  const isPills = !isPanel && layout === 'pills';
+  const isTopbar = isDropdown || layout === 'topbar';
+
+  /**
+   * Enough of a chip to read as one before a designer touches it. Every value
+   * here is overridable through the `pill` part, and the part carries the
+   * selected state so the active subcategory can look different.
+   */
+  const pillStyle = (selected: boolean): React.CSSProperties => ({
+    display: 'inline-flex',
+    alignItems: 'center',
+    gap: '6px',
+    padding: 'var(--facet-filters-pill-padding, 6px 14px)',
+    borderRadius: 'var(--facet-filters-pill-radius, 999px)',
+    border: '1px solid var(--facet-filters-border, #d1d5db)',
+    background: selected
+      ? 'var(--facet-filters-pill-active-bg, #111827)'
+      : 'var(--facet-filters-pill-bg, transparent)',
+    color: selected
+      ? 'var(--facet-filters-pill-active-color, #ffffff)'
+      : 'inherit',
+    textDecoration: 'none',
+    cursor: 'pointer',
+    whiteSpace: 'nowrap'
+  });
+
+  const facetGroups = orderedFacets.map((facet) => {
+    // A pill row is always open: there is no heading to collapse it from.
+    const isCollapsed = isPills
+      ? false
+      : isDropdown
+      ? collapsedKeys[facet.key] !== false
+      : collapsible && (collapsedKeys[facet.key] ?? defaultCollapsed);
+    const isExpanded = expandedKeys[facet.key] === true;
+
+    const availableChoices = hideZeroCounts
+      ? facet.choices.filter(
+          (choice) => choice.quantity > 0 || choice.isSelected
+        )
+      : facet.choices;
+    // The pill row is navigation, not a filter panel — no heading, no
+    // checkboxes and no search box either.
+    const searchVisible =
+      !isPills &&
+      showOptionSearch &&
+      (optionSearchMinOptions === 0 ||
+        availableChoices.length >= optionSearchMinOptions);
+    const searchTerm = searchVisible ? (searchTerms[facet.key] || '').trim() : '';
+    /**
+     * Lowercased with the page's locale rather than the host's: Turkish "İ"
+     * folds to "i̇" and "I" to "ı", so a shopper searching "istanbul" in a
+     * tr-TR store finds nothing under an implicit collation. There is no
+     * hydration risk — the term is always empty until someone types.
+     */
+    const normalizedTerm = searchTerm.toLocaleLowerCase(locale);
+    const searchedChoices = normalizedTerm
+      ? availableChoices.filter((choice) =>
+          String(choice.label).toLocaleLowerCase(locale).includes(normalizedTerm)
+        )
+      : availableChoices;
+
+    const visibleChoices = orderChoices(searchedChoices, optionOrder, locale);
+    const facetHasSelection = facet.choices.some(
+      (choice) => choice.isSelected
+    );
+    // Counted over every choice, not the visible ones: a selection hidden
+    // behind "show more" or filtered out by a search term is still applied.
+    const pendingCount = facet.choices.filter((choice) =>
+      isChoicePending(facet, choice)
+    ).length;
+    // Per group, and by comparison rather than by count: swapping one option
+    // for another leaves the count where it was but is still a staged change.
+    const groupHasStagedChange =
+      stagedParams !== null &&
+      facet.choices.some(
+        (choice) => isChoicePending(facet, choice) !== choice.isSelected
+      );
+    const hasOverflow =
+      maxVisibleOptions > 0 && visibleChoices.length > maxVisibleOptions;
+    const shownChoices =
+      hasOverflow && !isExpanded
+        ? visibleChoices.slice(0, maxVisibleOptions)
+        : visibleChoices;
+    const noMatch = normalizedTerm.length > 0 && shownChoices.length === 0;
+
+    /**
+     * The count beside a group heading. It follows the ticks the shopper is
+     * looking at, which while staging is the PENDING selection — the trigger
+     * badge is the one that reports what is actually applied.
+     */
+    const selectedCountBadge =
+      showSelectedCount && pendingCount > 0 ? (
+        <span
+          data-facet-selected-count=""
+          {...partAttrs('selected-count', { staged: groupHasStagedChange })}
+          style={{ opacity: 0.7, marginLeft: '4px' }}
+        >
+          {formatCount(selectedCountTemplate, pendingCount)}
+        </span>
+      ) : null;
+
+    // A `<ul>` may only hold `<li>`; the designer's row is a block, so
+    // the custom path renders the same flex column as a plain container.
+    const OptionsTag = (hasCustomOption ? 'div' : 'ul') as 'ul';
+    const showMoreButton = (
+      <button
+        type="button"
+        data-facet-show-more=""
+        aria-expanded={isExpanded}
+        {...partAttrs('show-more', { open: isExpanded })}
+        onClick={() =>
+          setExpandedKeys((current) => ({
+            ...current,
+            [facet.key]: !isExpanded
+          }))
+        }
+        style={{
+          background: 'none',
+          border: 'none',
+          padding: '2px 0',
+          cursor: 'pointer',
+          color: 'inherit',
+          font: 'inherit',
+          textDecoration: 'underline',
+          textAlign: 'left'
+        }}
+      >
+        {isExpanded ? showLessLabel : showMoreLabel}
+      </button>
+    );
+
+    /**
+     * Sixty colours or four hundred brands is a scroll, not a choice. The box
+     * lives inside the options list so the floating dropdown panel keeps it
+     * and the group heading keeps its own layout; it is a row of the list
+     * rather than a sibling, which is why it is wrapped in `<li>` whenever the
+     * list is a real `<ul>`.
+     */
+    const searchInput = (
+      <input
+        type="search"
+        data-facet-option-search=""
+        {...partAttrs('option-search')}
+        value={searchTerms[facet.key] || ''}
+        // Local state only: nothing is fetched, stored or navigated, so this
+        // stays live in the designer where the author can style it as typed in.
+        onChange={(event) =>
+          setSearchTerms((current) => ({
+            ...current,
+            [facet.key]: event.target.value
+          }))
+        }
+        placeholder={optionSearchLabel}
+        // Named per group: several of these boxes sit on one page and
+        // "Search" alone tells a screen-reader user nothing about which.
+        aria-label={`${optionSearchLabel} ${facet.name}`.trim()}
+        style={{
+          width: '100%',
+          boxSizing: 'border-box',
+          border: '1px solid var(--facet-filters-border, #d1d5db)',
+          borderRadius: 'inherit',
+          background: 'transparent',
+          color: 'inherit',
+          font: 'inherit',
+          padding: '6px 8px',
+          outline: 'none'
+        }}
+      />
+    );
+
+    // An empty box under a search term reads as a broken filter; say so.
+    const noMatchNotice = (
+      <span
+        data-facet-no-match=""
+        {...partAttrs('no-match')}
+        style={{ opacity: 0.7 }}
+      >
+        {noMatchLabel}
+      </span>
+    );
+
+    /**
+     * The dropdown's floating panel had no control of its own: the only way
+     * back out was the heading that opened it. Shares the `close` part with
+     * the drawer's header button so one styling group dresses both.
+     */
+    const dropdownCloseButton = (
+      <button
+        type="button"
+        data-facet-dropdown-close=""
+        {...partAttrs('close')}
+        aria-label={closeLabel}
+        onClick={() =>
+          setCollapsedKeys((current) => ({ ...current, [facet.key]: true }))
+        }
+        style={{
+          display: 'inline-flex',
+          alignSelf: 'flex-end',
+          background: 'none',
+          border: 'none',
+          padding: '4px',
+          cursor: 'pointer',
+          color: 'inherit'
+        }}
+      >
+        <CloseIcon />
+      </button>
+    );
+
+    return (
+      <div
+        key={facet.key}
+        data-facet-group={facet.key}
+        {...partAttrs('group', { open: !isCollapsed })}
+        style={{
+          minWidth: isTopbar ? '180px' : undefined,
+          // The panel is positioned against its own facet, not the row.
+          position: isDropdown ? 'relative' : undefined
+        }}
+      >
+        {isPills ? null : collapsible || isDropdown ? (
+          <button
+            type="button"
+            data-facet-toggle=""
+            aria-expanded={!isCollapsed}
+            {...partAttrs('label', { open: !isCollapsed })}
+            onClick={() =>
+              setCollapsedKeys((current) => ({
+                ...current,
+                [facet.key]: !isCollapsed
+              }))
+            }
+            style={{
+              display: 'flex',
+              alignItems: 'center',
+              justifyContent: 'space-between',
+              width: '100%',
+              gap: '8px',
+              background: 'none',
+              cursor: 'pointer',
+              color: 'inherit',
+              font: 'inherit',
+              fontWeight: 600,
+              ...(isDropdown
+                ? {
+                    borderStyle: 'solid',
+                    borderWidth: '1px',
+                    borderColor: 'var(--facet-filters-border, #d1d5db)',
+                    padding: '10px 12px'
+                  }
+                : { border: 'none', padding: '8px 0' })
+            }}
+          >
+            {/* The badge sits INSIDE the name span so the heading keeps its
+                two children and `space-between` still parks the icon on the
+                far edge. */}
+            <span>
+              {facet.name}
+              {selectedCountBadge}
+            </span>
+            <ToggleIcon variant={toggleIcon} isCollapsed={isCollapsed} />
+          </button>
+        ) : (
+          <div
+            data-facet-title=""
+            {...partAttrs('label')}
+            style={{ padding: '8px 0', fontWeight: 600 }}
+          >
+            {facet.name}
+            {selectedCountBadge}
+          </div>
+        )}
+
+        {!isCollapsed && (
+          <OptionsTag
+            data-facet-choices=""
+            {...partAttrs('option-list', {
+              empty: shownChoices.length === 0
+            })}
+            {...(isDropdown ? partAttrs('panel', { open: true }) : null)}
+            style={{
+              listStyle: 'none',
+              margin: 0,
+              padding: isDropdown ? '12px' : 0,
+              display: 'flex',
+              flexDirection: isPills ? 'row' : 'column',
+              flexWrap: isPills ? 'wrap' : 'nowrap',
+              gap: isPills ? 'var(--facet-filters-pill-gap, 8px)' : '6px',
+              ...(isDropdown
+                ? {
+                    // Floating so opening a filter does not push the grid
+                    // down — the whole reason a brand moves filters up top.
+                    position: 'absolute',
+                    zIndex: 20,
+                    top: 'calc(100% + 4px)',
+                    left: 0,
+                    minWidth: '100%',
+                    maxHeight: '320px',
+                    overflowY: 'auto',
+                    background: 'var(--facet-filters-panel-bg, #ffffff)',
+                    border:
+                      '1px solid var(--facet-filters-border, #d1d5db)',
+                    boxShadow: '0 8px 24px rgba(0, 0, 0, 0.12)'
+                  }
+                : null)
+            }}
+          >
+            {isDropdown &&
+              showDropdownClose &&
+              (hasCustomOption ? (
+                dropdownCloseButton
+              ) : (
+                <li style={{ display: 'flex', justifyContent: 'flex-end' }}>
+                  {dropdownCloseButton}
+                </li>
+              ))}
+
+            {searchVisible &&
+              (hasCustomOption ? searchInput : <li>{searchInput}</li>)}
+
+            {hasCustomOption && (
+              <ItemTemplateList
+                block={block}
+                items={shownChoices.map((choice) => ({
+                  label: choice.label,
+                  name: choice.label,
+                  value: choice.value,
+                  count: choice.quantity,
+                  // The tick the shopper sees, staged included — a custom row
+                  // binding `item.selected` has to agree with the built-in one.
+                  selected: isChoicePending(facet, choice),
+                  // Stays the immediate-apply href: an authored row renders a
+                  // real link, and a link has to lead somewhere. Staging is the
+                  // built-in row's contract, not the anchor's.
+                  url: hrefForChoice(facet, choice)
+                }))}
+                placeholderId={placeholderId}
+                sectionId={sectionId}
+                isDesigner={isDesigner}
+                selectedBlockId={selectedBlockId}
+                currentBreakpoint={currentBreakpoint}
+                designerPlaceholderCount={4}
+              />
+            )}
+
+            {isPills && !hasCustomOption && showAllOption && (
+              <li>
+                <a
+                  data-facet-choice="__all__"
+                  data-facet-selected={facetHasSelection ? 'false' : 'true'}
+                  {...partAttrs('pill', { selected: !facetHasSelection })}
+                  href={isDesigner ? undefined : hrefForReset(facet)}
+                  aria-current={facetHasSelection ? undefined : 'page'}
+                  onClick={(event) => {
+                    event.preventDefault();
+                    if (isDesigner) return;
+                    router.push(hrefForReset(facet));
+                  }}
+                  style={pillStyle(!facetHasSelection)}
+                >
+                  {allLabel}
+                </a>
+              </li>
+            )}
+
+            {isPills &&
+              !hasCustomOption &&
+              shownChoices.map((choice) => (
+                <li key={`${facet.key}-${choice.value}`}>
+                  <a
+                    data-facet-choice={choice.value}
+                    data-facet-selected={choice.isSelected ? 'true' : 'false'}
+                    // One part per element: data-part holds a single value, so
+                    // a second spread would overwrite the first. A pill is its
+                    // own part with its own controls.
+                    {...partAttrs('pill', {
+                      selected: choice.isSelected,
+                      empty: choice.quantity === 0
+                    })}
+                    href={isDesigner ? undefined : hrefForChoice(facet, choice)}
+                    aria-current={choice.isSelected ? 'page' : undefined}
+                    onClick={(event) => {
+                      // The href is what makes it navigation; the handler is
+                      // what keeps it a client transition. A modified click
+                      // (new tab, download) is left to the browser.
+                      if (
+                        event.metaKey ||
+                        event.ctrlKey ||
+                        event.shiftKey ||
+                        event.altKey
+                      ) {
+                        return;
+                      }
+                      event.preventDefault();
+                      handleSelect(facet, choice);
+                    }}
+                    style={pillStyle(choice.isSelected)}
+                  >
+                    <span>{choice.label}</span>
+                    {showCounts && choice.quantity > 0 && (
+                      <span {...partAttrs('count')} style={{ opacity: 0.6 }}>
+                        {formatCount(countTemplate, choice.quantity)}
+                      </span>
+                    )}
+                  </a>
+                </li>
+              ))}
+
+            {!isPills &&
+              !hasCustomOption &&
+              shownChoices.map((choice) => {
+              // While staging, the tick follows the pending query and `staged`
+              // marks the ones that differ from what the page is actually
+              // filtered by — that difference IS the staged-versus-applied
+              // story the shopper needs before committing. Off staging both
+              // read straight from commerce, exactly as before.
+              const isPending = isChoicePending(facet, choice);
+              const isStaged = stagedParams !== null && isPending !== choice.isSelected;
+
+              return (
+              <li key={`${facet.key}-${choice.value}`}>
+                <button
+                  type="button"
+                  data-facet-choice={choice.value}
+                  data-facet-selected={isPending ? 'true' : 'false'}
+                  aria-pressed={isPending}
+                  {...partAttrs('option', {
+                    selected: isPending,
+                    staged: isStaged,
+                    empty: choice.quantity === 0
+                  })}
+                  onClick={() => handleSelect(facet, choice)}
+                  style={{
+                    display: 'flex',
+                    alignItems: 'center',
+                    gap: '8px',
+                    width: '100%',
+                    background: 'none',
+                    border: 'none',
+                    padding: '2px 0',
+                    cursor: 'pointer',
+                    color: 'inherit',
+                    font: 'inherit',
+                    textAlign: 'left',
+                    fontWeight: isPending ? 600 : 400
+                  }}
+                >
+                  {showCheckbox && (
+                    <span
+                      aria-hidden="true"
+                      {...partAttrs('checkbox', {
+                        checked: isPending,
+                        staged: isStaged
+                      })}
+                      style={{
+                        width: '14px',
+                        height: '14px',
+                        flex: '0 0 auto',
+                        border: '1px solid currentColor',
+                        borderRadius: '2px',
+                        background: isPending
+                          ? 'currentColor'
+                          : 'transparent'
+                      }}
+                    />
+                  )}
+                  <span>{choice.label}</span>
+                  {showCounts && choice.quantity > 0 && (
+                    <span
+                      {...partAttrs('count')}
+                      style={{ opacity: 0.6 }}
+                    >
+                      {formatCount(countTemplate, choice.quantity)}
+                    </span>
+                  )}
+                </button>
+              </li>
+              );
+            })}
+
+            {noMatch &&
+              (hasCustomOption ? noMatchNotice : <li>{noMatchNotice}</li>)}
+
+            {hasOverflow &&
+              (hasCustomOption ? (
+                showMoreButton
+              ) : (
+                <li>{showMoreButton}</li>
+              ))}
+          </OptionsTag>
+        )}
+      </div>
+    );
+  });
+
+  if (!isPanel) {
+    return (
+      <div
+        data-facet-filters=""
+        // Only read by the dropdown's outside-click dismissal, to tell "past
+        // the panel" from "inside this block".
+        ref={rootRef}
+        data-facet-layout={
+          isPills
+            ? 'pills'
+            : isDropdown
+            ? 'dropdown'
+            : isTopbar
+            ? 'topbar'
+            : 'sidebar'
+        }
+        {...partAttrs('list')}
+        style={{
+          display: 'flex',
+          flexDirection: isTopbar ? 'row' : 'column',
+          flexWrap: isTopbar || isPills ? 'wrap' : 'nowrap',
+          gap: 'var(--facet-filters-gap, 16px)'
+        }}
+      >
+        {facetGroups}
+      </div>
+    );
+  }
+
+  const isModal = panelMode === 'modal';
+
+  /** Drops every facet's key, which is what "clear all" means here. */
+  const handleClear = () => {
+    if (stagedApply) {
+      // Nothing commits until Apply, clearing included — so the panel stays
+      // open and the shopper can pick again before committing once.
+      if (isDesigner) return;
+
+      const params = deletePageCursor(pendingParams());
+      facets.forEach((facet) => params.delete(facet.searchKey));
+      setStagedQuery(params.toString());
+      return;
+    }
+
+    setPanelOpen(false);
+    // Navigating inside the designer iframe would drop the author out of the
+    // page they are editing, so the control is inert there.
+    if (isDesigner) return;
+
+    const params = deletePageCursor(new URLSearchParams(appliedQuery));
+    facets.forEach((facet) => params.delete(facet.searchKey));
+
+    router.push(buildListingHref(pathname || listing?.path || '', params));
+  };
+
+  const hasStagedChanges =
+    stagedApply &&
+    stagedQuery !== null &&
+    !sameFilterQuery(stagedQuery, appliedQuery, pageQueryParam);
+
+  /**
+   * The only place a staged composition writes the URL. In an apply-as-you-
+   * pick composition there is nothing staged, so this stays what it always
+   * was: "I am done here", never a second request.
+   *
+   * Guarded on the very answer that lights the button up, not on "something
+   * was staged": a shopper who ticks a box and unticks it has staged twice and
+   * changed nothing, and in App Router a push there is a full navigation —
+   * RSC refetch, scroll to top, a history entry that makes Back look dead.
+   */
+  const handleApply = () => {
+    if (!isDesigner && hasStagedChanges && stagedQuery !== null) {
+      router.push(
+        buildListingHref(
+          pathname || listing?.path || '',
+          new URLSearchParams(stagedQuery)
+        )
+      );
+    }
+
+    setPanelOpen(false);
+  };
+
+  /**
+   * What the page is ACTUALLY filtered by. Deliberately the applied count and
+   * not the staged one: the badge describes the results behind the panel, and
+   * next to a group heading counting the staged ticks it is what makes the
+   * difference between the two visible.
+   */
+  const appliedFacetCount = facets.reduce(
+    (total, facet) =>
+      total + facet.choices.filter((choice) => choice.isSelected).length,
+    0
+  );
+
+  return (
+    <div data-facet-filters="" data-facet-layout="panel">
+      <button
+        type="button"
+        data-facet-trigger=""
+        ref={triggerRef}
+        {...partAttrs('trigger', { open: panelOpen })}
+        aria-haspopup="dialog"
+        aria-expanded={panelOpen}
+        onClick={() => setPanelOpen(true)}
+        style={{
+          display: 'inline-flex',
+          alignItems: 'center',
+          gap: 'var(--facet-filters-trigger-gap, 8px)',
+          background: 'none',
+          border: 'none',
+          padding: 0,
+          cursor: 'pointer',
+          color: 'inherit',
+          font: 'inherit'
+        }}
+      >
+        <TriggerIcon variant={triggerIcon} />
+        <span data-facet-trigger-label="">{triggerLabel}</span>
+        {showTriggerCount && appliedFacetCount > 0 && (
+          <span
+            data-facet-trigger-count=""
+            {...partAttrs('trigger-count')}
+            style={{ opacity: 0.7 }}
+          >
+            {formatCount(triggerCountTemplate, appliedFacetCount)}
+          </span>
+        )}
+      </button>
+
+      {panelOpen && (
+        <div
+          data-facet-panel-root=""
+          style={{
+            position: 'fixed',
+            inset: 0,
+            zIndex: 1000,
+            display: 'flex',
+            padding: isModal ? '16px' : 0,
+            // With the backdrop off nothing is drawn over the page, but this
+            // root still covers the whole viewport — it would swallow every
+            // click as an invisible sheet of glass. Letting events through it
+            // (and re-enabling them on the panel) keeps the page alive.
+            pointerEvents: showBackdrop ? undefined : 'none'
+          }}
+        >
+          {showBackdrop && (
+            <div
+              data-facet-backdrop=""
+              {...partAttrs('backdrop', { open: true })}
+              onClick={() => {
+                if (closeOnBackdrop) setPanelOpen(false);
+              }}
+              style={{
+                position: 'absolute',
+                inset: 0,
+                background: 'rgba(0, 0, 0, 0.5)'
+              }}
+            />
+          )}
+
+          <div
+            data-facet-panel=""
+            data-facet-panel-mode={isModal ? 'modal' : 'drawer'}
+            {...partAttrs('panel', { open: true })}
+            role="dialog"
+            // Carries the panel ref and the `aria-modal` claim, and the claim
+            // is made only where it is true: never without a backdrop, never
+            // in the designer, and never on the lower of two open panels,
+            // which is not the one hiding the page. Spread after `role` so the
+            // attribute order the golden captured stays put.
+            {...overlay.overlayProps}
+            aria-label={panelTitle || triggerLabel}
+            // Focus target of last resort, for a panel whose every control the
+            // designer turned off.
+            tabIndex={-1}
+            style={{
+              display: 'flex',
+              flexDirection: 'column',
+              background: 'var(--facet-filters-panel-bg, #ffffff)',
+              color: 'inherit',
+              textAlign: 'left',
+              outline: 'none',
+              pointerEvents: showBackdrop ? undefined : 'auto',
+              ...(isModal
+                ? {
+                    // `margin: auto` inside the flex root is what centres it;
+                    // the backdrop is out of flow and does not compete.
+                    position: 'relative',
+                    margin: 'auto',
+                    width: '100%',
+                    maxWidth: `${panelWidth}px`,
+                    maxHeight: '85vh',
+                    boxShadow: '0 12px 32px rgba(0, 0, 0, 0.18)'
+                  }
+                : {
+                    position: 'absolute',
+                    top: 0,
+                    bottom: 0,
+                    [panelSide === 'left' ? 'left' : 'right']: 0,
+                    width: `min(${panelWidth}px, 92vw)`,
+                    boxShadow: '0 0 24px rgba(0, 0, 0, 0.2)'
+                  })
+            }}
+          >
+            {panelHeaderVisible && (
+              <div
+                data-facet-panel-header=""
+                {...partAttrs('panel-header')}
+                style={{
+                  display: 'flex',
+                  alignItems: 'center',
+                  justifyContent: 'space-between',
+                  gap: '12px',
+                  flex: '0 0 auto',
+                  padding: '12px 16px',
+                  borderBottom:
+                    '1px solid var(--facet-filters-border, #d1d5db)'
+                }}
+              >
+                <span
+                  data-facet-panel-title=""
+                  {...partAttrs('panel-title')}
+                  style={{ fontWeight: 600 }}
+                >
+                  {panelTitle}
+                </span>
+                {closeVisible && (
+                  <button
+                    type="button"
+                    data-facet-panel-close=""
+                    {...partAttrs('close')}
+                    aria-label={closeLabel}
+                    onClick={() => setPanelOpen(false)}
+                    style={{
+                      display: 'inline-flex',
+                      background: 'none',
+                      border: 'none',
+                      padding: '4px',
+                      cursor: 'pointer',
+                      color: 'inherit'
+                    }}
+                  >
+                    <CloseIcon />
+                  </button>
+                )}
+              </div>
+            )}
+
+            <div
+              data-facet-panel-body=""
+              {...partAttrs('list')}
+              style={{
+                display: 'flex',
+                flexDirection: 'column',
+                flex: '1 1 auto',
+                gap: 'var(--facet-filters-gap, 16px)',
+                padding: '16px',
+                overflowY: 'auto'
+              }}
+            >
+              {facetGroups}
+            </div>
+
+            {(showClear || showApply) && (
+              <div
+                data-facet-panel-footer=""
+                {...partAttrs('panel-footer')}
+                style={{
+                  display: 'flex',
+                  gap: '8px',
+                  flex: '0 0 auto',
+                  padding: '12px 16px',
+                  borderTop: '1px solid var(--facet-filters-border, #d1d5db)'
+                }}
+              >
+                {showClear && (
+                  <button
+                    type="button"
+                    data-facet-clear=""
+                    {...partAttrs('clear')}
+                    onClick={handleClear}
+                    style={{
+                      flex: '1 1 0',
+                      padding: '10px 12px',
+                      background: 'none',
+                      borderStyle: 'solid',
+                      borderWidth: '1px',
+                      borderColor: 'var(--facet-filters-border, #d1d5db)',
+                      cursor: 'pointer',
+                      color: 'inherit',
+                      font: 'inherit'
+                    }}
+                  >
+                    {clearLabel}
+                  </button>
+                )}
+                {showApply && (
+                  <button
+                    type="button"
+                    data-facet-apply=""
+                    // `staged` lights the button up while there is something
+                    // waiting to be committed, so the shopper can tell a panel
+                    // they have changed from one they have not.
+                    {...partAttrs('apply', { staged: hasStagedChanges })}
+                    onClick={handleApply}
+                    style={{
+                      flex: '1 1 0',
+                      padding: '10px 12px',
+                      border: 'none',
+                      background: '#111827',
+                      color: '#ffffff',
+                      cursor: 'pointer',
+                      font: 'inherit'
+                    }}
+                  >
+                    {applyLabel}
+                  </button>
+                )}
+              </div>
+            )}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+};
+
+export default FacetFiltersBlock;