@stapel/search-react 0.28.0 → 0.29.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stapel/search-react",
-  "version": "0.28.0",
+  "version": "0.29.1",
   "description": "Headless React pair for stapel-search: a typed query client, TanStack Query hooks, and a URL-first state codec that makes a search shareable by construction (filters, ranges, geo, sort and the keyset cursor all live in the query string). Drill-down facets rendered with their remaining counts and with the server's own honesty flags — approximate, skipped, degraded — never swallowed; keyset pagination with the window refusal named; DSA Art. 26 `promoted` marking carried into every card slot and the P2B Art. 5 ranking disclosure exposed as data. Zero visual opinion in the main entry; an opt-in /default subpath ships the antd skin, and /router binds the codec to react-router's useSearchParams.",
   "license": "MIT",
   "repository": {
@@ -57,9 +57,9 @@
       "limit": "13.75 KB"
     },
     {
-      "name": "default — the antd skin (query box + a typeahead that offers CATEGORY destinations with their live counts, filters incl. ranges/geo/category slots + the phone chip row with its leading category chip and the location summary row + the rail's evidence-ranked disclosure groups, panel search and sticky count/clear footer, results incl. the view switch, the card photo GALLERY as a SkinCarousel strip, the empty state's derived exits, ranking, the dictionary control for a vocabulary facet, the popular-values block, the partition row in both its chip and segmented variants, the select-style dictionary FIELD the desktop rail opens, the from/to pickers a bounded integer axis draws and the rail's own scrollbar sheet) must stay out of the main bundle. Raised 24.5 → 25.5 KB for those four controls, then 25.5 → 26.25 KB for the chip row's APPLIED mode — one chip per applied value and per numeric bound, each removing that one constraint beside a rail that is already on screen (a storefront was carrying its own copy of it), then 26.25 → 27 KB for the \"search in other categories\" LINE — which is a net deletion on the page that mounts it, replacing a full-width block of one row per section that arrived after the results and pushed them, then 27 → 27.75 KB for the two frames the page now tells apart: the dictionary FIELD reaching `<SearchPage>` at all (per-layout default, field in the rail and inline in the sheet) and the footer bar being static in a column and sticky in a sheet, where it used to be pinned over the last two groups everywhere, then 27.75 → 28.5 KB for `categoryHref` on the other-categories line — a real `<a href>` per row with a modifier-click left to the browser, instead of a `<button>` with no address a person could open in a new tab",
+      "name": "default — the antd skin (query box + a typeahead that offers CATEGORY destinations with their live counts, filters incl. ranges/geo/category slots + the phone chip row with its leading category chip and the location summary row + the rail's evidence-ranked disclosure groups, panel search and sticky count/clear footer, results incl. the view switch, the card photo GALLERY as a SkinCarousel strip, the empty state's derived exits, ranking, the dictionary control for a vocabulary facet, the popular-values block, the partition row in both its chip and segmented variants, the select-style dictionary FIELD the desktop rail opens, the from/to pickers a bounded integer axis draws and the rail's own scrollbar sheet) must stay out of the main bundle. Raised 24.5 → 25.5 KB for those four controls, then 25.5 → 26.25 KB for the chip row's APPLIED mode — one chip per applied value and per numeric bound, each removing that one constraint beside a rail that is already on screen (a storefront was carrying its own copy of it), then 26.25 → 27 KB for the \"search in other categories\" LINE — which is a net deletion on the page that mounts it, replacing a full-width block of one row per section that arrived after the results and pushed them, then 27 → 27.75 KB for the two frames the page now tells apart: the dictionary FIELD reaching `<SearchPage>` at all (per-layout default, field in the rail and inline in the sheet) and the footer bar being static in a column and sticky in a sheet, where it used to be pinned over the last two groups everywhere, then 27.75 → 28.5 KB for `categoryHref` on the other-categories line — a real `<a href>` per row with a modifier-click left to the browser, instead of a `<button>` with no address a person could open in a new tab, then 28.5 → 29.25 KB for the phone's dictionary SHEET — a trigger row over the shared `SkinPickerSheet` with a recommended band, an alphabetical rest paged fifty at a time and a draft committed in one write, which is the control the composer's vocabulary picker already was while the buyer got a wall of checkboxes",
       "path": "dist/default/index.js",
-      "limit": "28.5 KB"
+      "limit": "29.25 KB"
     },
     {
       "name": "router — the react-router binding is opt-in; the main entry must never pull a router",
@@ -67,9 +67,9 @@
       "limit": "1 KB"
     },
     {
-      "name": "i18n/ru — the Russian bundle is opt-in, not carried by the main entry",
+      "name": "i18n/ru — the Russian bundle is opt-in, not carried by the main entry. Raised 4.75 → 5 KB for the dictionary sheet's three headings",
       "path": "dist/i18n/ru.js",
-      "limit": "4.75 KB"
+      "limit": "5 KB"
     },
     {
       "name": "i18n/es — the Spanish bundle is opt-in, not carried by the main entry. Raised 3.5 → 3.75 KB for the three strings of the other-categories line",
@@ -81,7 +81,7 @@
     "@stapel/attributes-react": ">=0.4.0",
     "@stapel/core": ">=0.18.1 <1.0.0",
     "@stapel/image": ">=0.3.0",
-    "@stapel/tokens-antd": ">=0.11.0",
+    "@stapel/tokens-antd": ">=0.12.0",
     "@tanstack/react-query": "^5.0.0",
     "antd": ">=5.20.0 <7",
     "react": ">=19",
@@ -116,10 +116,10 @@
     "typescript": "^5.8.3",
     "vitest": "^3.2.4",
     "@stapel/attributes-react": "^0.16.0",
-    "@stapel/image": "^0.4.2",
     "@stapel/showcase": "^0.3.0",
-    "@stapel/tokens": "^0.7.0",
     "@stapel/core": "^0.25.1",
+    "@stapel/image": "^0.4.2",
+    "@stapel/tokens": "^0.7.0",
     "@stapel/tokens-antd": "^0.17.0"
   },
   "engines": {

package/src/analytics/generated/events.json

@@ -1,7 +1,7 @@
 {
   "$generated": "by scripts/gen-events.mjs — do not edit; drift-gated (pnpm gen:events:check)",
   "package": "@stapel/search-react",
-  "version": "0.28.0",
+  "version": "0.29.1",
   "defined": [],
   "flows": []
 }

package/src/default/FacetGroupControl.tsx

@@ -62,10 +62,12 @@
  * them visible as before: folding everything would leave a heading over
  * nothing. Chosen options are always visible, wherever their count went.
  */
-import { useState } from "react";
+import { useMemo, useState } from "react";
 import type { CSSProperties, ReactElement } from "react";
 import { Button, Checkbox, Flex, Input, Typography } from "antd";
 import { useT } from "@stapel/core";
+import { SkinPickerSheet } from "@stapel/tokens-antd/skin";
+import type { PickerGroup, PickerOption } from "@stapel/tokens-antd/skin";
 import { controls, cssVar, radii, spacing } from "@stapel/tokens";
 import { featureConfig, featureType } from "@stapel/attributes-react";
 import type { FeatureDef } from "@stapel/attributes-react";
@@ -632,6 +634,246 @@ function DictionaryField(props: {
   );
 }
 
+/**
+ * How many values the sheet's «All values» band adds per page.
+ *
+ * Fifty is the vocabulary endpoint's own page size, and it is the number past
+ * which a phone list stops being scrolled and starts being searched. Reaching
+ * the end of the list asks for the next fifty, so a 418-make level is a
+ * scroll rather than 418 mounted rows.
+ */
+export const FACET_SHEET_PAGE = 50;
+
+/** One facet option as the shared picker reads it. The count rides along as
+ * the row's second line: a filter without its remaining count is the
+ * drill-down facet turned naive, and that rule does not stop at a sheet. */
+function pickerRow(option: FacetOption, notCounted: string): PickerOption {
+  return {
+    value: option.value,
+    label: option.label,
+    description: option.count === null ? notCounted : String(option.count),
+  };
+}
+
+/**
+ * A dictionary group on a PHONE: a trigger row, and a nested sheet.
+ *
+ * ── What the buyer was looking at ─────────────────────────────────────────
+ *
+ * The composer's own vocabulary picker (`@stapel/attributes-react`'s
+ * `ref_select` editor) is a trigger that opens a sheet with a search box, a
+ * recommended band and the rest — zero checkboxes. The buyer's filter sheet
+ * drew the SAME axis as a wall of eight checkboxes with a "Find a value" box
+ * and a "Show all (38)" under it, and no way to say "any". Two halves of one
+ * product teaching two different gestures for one dictionary is the defect;
+ * this mode is the half that moved.
+ *
+ * ── Why the shared `SkinPickerSheet` and not a local one ──────────────────
+ *
+ * It is the same component the composer's picker draws: the search box pinned
+ * above the list, the checkmarks, the commit button above the home indicator,
+ * the swipe/Esc/back dismissal, the skeleton and the empty arm. A pair that
+ * re-derives that gets a near-miss of it, which is exactly how the two halves
+ * drifted the first time.
+ *
+ * ── The two bands ─────────────────────────────────────────────────────────
+ *
+ * «Recommended» is the busiest values BY COUNT — the answer's own evidence,
+ * capped at {@link FACET_VISIBLE_OPTIONS} — with the chosen values in front
+ * of it, because a filter a person cannot see is a filter they cannot remove.
+ * «All values» is everything else, alphabetically, a page at a time. Once
+ * something is typed the bands collapse into one: a "Recommended" heading
+ * over rows that do not answer the box is the stale-list defect wearing a
+ * hat.
+ *
+ * The box filters LOCALLY and across alphabets (`translitPrefixMatch`, the
+ * same matcher the desktop field uses), so a Cyrillic spelling of a Latin
+ * make finds it. Nothing here touches the URL: what a person typed to FIND a
+ * filter is not part of the search they would share. The COMMIT does — the
+ * whole draft is written to the slug's URL key at once.
+ */
+function DictionarySheet(props: {
+  readonly group: FacetGroup;
+  readonly onSetValues: (slug: string, values: readonly string[]) => void;
+}): ReactElement {
+  const t = useT();
+  const { group } = props;
+  const [open, setOpen] = useState(false);
+  const [needle, setNeedle] = useState("");
+  const [page, setPage] = useState(FACET_SHEET_PAGE);
+
+  const chosen = group.options.filter((option) => option.selected);
+  const query = needle.trim();
+
+  const { groups, total } = useMemo(() => {
+    const notCounted = t(SEARCH_I18N_KEYS.facetsNotCounted);
+    const hit = (option: FacetOption): boolean =>
+      query === "" ||
+      translitPrefixMatch(query, option.label) ||
+      translitPrefixMatch(query, option.value);
+    const selected = group.options.filter((option) => option.selected);
+    const byCount = [...group.options].sort(
+      (a, b) => (b.count ?? 0) - (a.count ?? 0)
+    );
+
+    if (query !== "") {
+      // One band while the box holds something: the chosen values first (they
+      // are the ones with an off-switch to reach), then the evidence order.
+      const hits = [
+        ...selected.filter(hit),
+        ...byCount.filter((option) => !option.selected && hit(option)),
+      ];
+      return {
+        total: hits.length,
+        groups: [
+          {
+            key: "all",
+            label: t(SEARCH_I18N_KEYS.facetsDictionaryAllValues),
+            options: hits.slice(0, page).map((o) => pickerRow(o, notCounted)),
+          },
+        ] as readonly PickerGroup[],
+      };
+    }
+
+    // The band never drops a chosen value, however cold it is: its cap grows
+    // to hold them rather than pushing one of them into the alphabet.
+    const cap = Math.max(FACET_VISIBLE_OPTIONS, selected.length);
+    const band: FacetOption[] = [];
+    const banded = new Set<string>();
+    for (const option of [...selected, ...byCount]) {
+      if (banded.has(option.value) || band.length >= cap) continue;
+      band.push(option);
+      banded.add(option.value);
+    }
+    const rest = group.options
+      .filter((option) => !banded.has(option.value))
+      .sort((a, b) => a.label.localeCompare(b.label));
+    return {
+      total: band.length + Math.min(rest.length, page),
+      groups: [
+        {
+          key: "band",
+          label: t(SEARCH_I18N_KEYS.facetsDictionaryRecommended),
+          options: band.map((o) => pickerRow(o, notCounted)),
+        },
+        {
+          key: "all",
+          label: t(SEARCH_I18N_KEYS.facetsDictionaryAllValues),
+          options: rest.slice(0, page).map((o) => pickerRow(o, notCounted)),
+        },
+      ] as readonly PickerGroup[],
+    };
+  }, [group, query, page, t]);
+
+  // How many rows exist behind the current page — what "there is more" means.
+  const available = group.options.length;
+
+  const text =
+    chosen.length > 0
+      ? chosen.map((option) => option.label).join(", ")
+      : t(SEARCH_I18N_KEYS.facetsDictionaryAny);
+
+  return (
+    <>
+      <button
+        type="button"
+        aria-haspopup="dialog"
+        aria-expanded={open}
+        aria-label={group.label}
+        style={DICTIONARY_FIELD}
+        data-testid={`facet-dictionary-trigger-${group.slug}`}
+        data-chosen={chosen.length}
+        data-analytics="none"
+        data-analytics-reason="opening a filter group is a read, not a flow step"
+        onClick={() => {
+          setOpen(true);
+        }}
+      >
+        <span style={DICTIONARY_FIELD_TEXT}>{text}</span>
+        {chosen.length > 0 && (
+          <Typography.Text
+            type="secondary"
+            data-testid={`facet-dictionary-trigger-count-${group.slug}`}
+          >
+            {chosen.length}
+          </Typography.Text>
+        )}
+        <ChevronGlyph open={open} />
+      </button>
+      <SkinPickerSheet
+        mode="multi"
+        open={open}
+        onClose={() => {
+          setOpen(false);
+          setNeedle("");
+          setPage(FACET_SHEET_PAGE);
+        }}
+        title={group.label}
+        testId={`facet-dictionary-sheet-${group.slug}`}
+        doneLabel={t(SEARCH_I18N_KEYS.facetsDictionaryDone)}
+        searchPlaceholder={t(SEARCH_I18N_KEYS.facetsDictionarySearch)}
+        emptyLabel={t(SEARCH_I18N_KEYS.facetsDictionaryEmpty)}
+        // The caller owns the filtering — the sheet's own local filter matches
+        // on the label only, and this axis is searched across alphabets.
+        searchValue={needle}
+        onSearchChange={(next) => {
+          setNeedle(next);
+          setPage(FACET_SHEET_PAGE);
+        }}
+        groups={groups}
+        // Everything handed over is drawn: the paging above is this
+        // component's, so the sheet's own row cap must not fold it again.
+        maxRows={Math.max(1, total)}
+        onEndReached={() => {
+          setPage((current) =>
+            current >= available ? current : current + FACET_SHEET_PAGE
+          );
+        }}
+        values={group.selected}
+        onChange={(values) => {
+          props.onSetValues(group.slug, values);
+        }}
+      />
+    </>
+  );
+}
+
+/**
+ * The three faces of one dictionary, chosen by mode.
+ *
+ * `"sheet"` without a bulk setter falls back to the FIELD rather than to the
+ * inline wall: a trigger that opens a list is the shape both surfaces are
+ * moving to, and the wall is the thing the pass named.
+ */
+function DictionaryControl(props: {
+  readonly group: FacetGroup;
+  readonly mode: "field" | "inline" | "sheet" | undefined;
+  readonly onToggle: (slug: string, value: string) => void;
+  readonly onSetValues?: (slug: string, values: readonly string[]) => void;
+  readonly visible: number;
+}): ReactElement {
+  const { onSetValues } = props;
+  if (props.mode === "sheet" && onSetValues !== undefined) {
+    return <DictionarySheet group={props.group} onSetValues={onSetValues} />;
+  }
+  if (props.mode === "field" || props.mode === "sheet") {
+    return (
+      <DictionaryField
+        group={props.group}
+        onToggle={props.onToggle}
+        visible={props.visible}
+      />
+    );
+  }
+  return (
+    <DictionaryBody
+      group={props.group}
+      onToggle={props.onToggle}
+      visible={props.visible}
+    />
+  );
+}
+
 export interface FacetGroupControlProps {
   readonly group: FacetGroup;
   readonly onToggle: (slug: string, value: string) => void;
@@ -652,13 +894,31 @@ export interface FacetGroupControlProps {
    * value only — the person owns the state after the first click. */
   readonly defaultOpen?: boolean;
   /**
-   * How a `"dictionary"` group is drawn. `"field"` is the desktop shape — a
-   * select-style field reading its chosen values or "Any", which opens the
-   * searchable list; `"inline"` (the default) keeps the list open, the shape
-   * a phone sheet wants because the sheet is already the disclosure.
-   * Meaningless for the other three shapes.
+   * How a `"dictionary"` group is drawn. Meaningless for the other three
+   * shapes.
+   *
+   *  - `"field"` — the desktop shape: a select-style field reading its chosen
+   *    values or "Any", which opens the searchable list under it;
+   *  - `"sheet"` — the PHONE shape: a trigger row reading the same sentence,
+   *    opening a nested picker sheet with a search box, a recommended band
+   *    and the rest. The same control the composer's vocabulary picker is, so
+   *    one dictionary is one gesture on both halves of the product. Needs
+   *    {@link FacetGroupControlProps.onSetValues} — the sheet commits a whole
+   *    draft at once, and a per-value toggle cannot apply one; without it the
+   *    group falls back to `"field"`;
+   *  - `"inline"` (the default) keeps the list open — a group that is already
+   *    the only thing on its surface, such as a per-chip sheet.
    */
-  readonly dictionaryMode?: "field" | "inline";
+  readonly dictionaryMode?: "field" | "inline" | "sheet";
+  /**
+   * Write a slug's chosen values in ONE go — `useFacetPanel`'s `setValues`.
+   *
+   * `onToggle` reads the current state to flip one value, so N toggles in one
+   * tick collapse into the last one; a sheet that commits a draft of several
+   * ticks needs the bulk write. Optional so no existing host changes, and
+   * only `dictionaryMode: "sheet"` reads it.
+   */
+  readonly onSetValues?: (slug: string, values: readonly string[]) => void;
 }
 
 export function FacetGroupControl(props: FacetGroupControlProps): ReactElement {
@@ -739,21 +999,17 @@ export function FacetGroupControl(props: FacetGroupControlProps): ReactElement {
       {/* Closed means NOT RENDERED, not hidden: a hundred `display:none`
           checkboxes are still a hundred stops for a screen reader, and the
           measured rail held 118 of them. */}
-      {open &&
-        shape === "dictionary" &&
-        (props.dictionaryMode === "field" ? (
-          <DictionaryField
-            group={group}
-            onToggle={props.onToggle}
-            visible={limit ?? FACET_VISIBLE_OPTIONS}
-          />
-        ) : (
-          <DictionaryBody
-            group={group}
-            onToggle={props.onToggle}
-            visible={limit ?? FACET_VISIBLE_OPTIONS}
-          />
-        ))}
+      {open && shape === "dictionary" && (
+        <DictionaryControl
+          group={group}
+          mode={props.dictionaryMode}
+          onToggle={props.onToggle}
+          {...(props.onSetValues !== undefined
+            ? { onSetValues: props.onSetValues }
+            : {})}
+          visible={limit ?? FACET_VISIBLE_OPTIONS}
+        />
+      )}
 
       {open && shape !== "dictionary" && (
         <>

package/src/default/FacetPanelPane.tsx

@@ -105,7 +105,7 @@ import { FacetGroupControl } from "./FacetGroupControl.js";
 import { buildRangeGroups } from "../state/ranges.js";
 import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
 import { LanguageSelect } from "./LanguageSelect.js";
-import { RangeFilterRow } from "./RangeFilterRow.js";
+import { RANGE_ROW_MIN_HEIGHT, RangeFilterRow, RangeRowSkeleton } from "./RangeFilterRow.js";
 import type { ThemeModeProp } from "./types.js";
 
 /**
@@ -315,10 +315,12 @@ export interface FacetPanelPaneProps extends ThemeModeProp {
   /**
    * How a DICTIONARY group is drawn. `"field"` is the desktop shape — a
    * select-style field reading its chosen values or "Any", which opens the
-   * searchable list; `"inline"` (the default) keeps the list open, which is
-   * the phone sheet's shape because a sheet is already a disclosure.
+   * searchable list under it; `"sheet"` is the phone's — the same trigger
+   * row, opening a nested picker sheet with a search box, a recommended band
+   * and the rest, which is the control the composer's vocabulary picker
+   * already is; `"inline"` (the default) keeps the list open.
    */
-  readonly dictionaryMode?: "field" | "inline";
+  readonly dictionaryMode?: "field" | "inline" | "sheet";
 }
 
 /**
@@ -828,6 +830,7 @@ export function FacetPanelPane(props: FacetPanelPaneProps): ReactElement {
                         key={needle === "" ? group.slug : `${group.slug}:match`}
                         group={group}
                         onToggle={bag.toggle}
+                        onSetValues={bag.setValues}
                         collapsible
                         defaultOpen={
                           needle !== "" ||
@@ -873,23 +876,57 @@ export function FacetPanelPane(props: FacetPanelPaneProps): ReactElement {
                 phone). It is a real filter for the person who wants it, so it
                 is not deleted; it is ranked where the chip row already ranks
                 it. */}
-            {attributeRanges.length > 0 && (
+            {/* The reservation, not just the rows (D361).
+                On a live category feed at 1536px this block's arrival was a
+                53px jump: `attributeRanges` draws from the CATEGORY SCHEMA
+                (`props.categoryFeatures`), and a host that fetches the
+                schema alongside the search answer had nothing here at all
+                until both landed — no host slot reserved the box, so the
+                rail grew under the reader's eye the instant it did.
+
+                Two things can be unknown at first paint, and each gets its
+                own reservation:
+                 - the SCHEMA itself (`categoryFeatures` undefined) — the
+                   axis count is unknown, so the fallback is one row's floor,
+                   a guess rather than nothing;
+                 - the ANSWER (`bag.state` not yet "ready") with a known
+                   schema — the axis COUNT is already certain from the
+                   schema, so the rail draws that many skeleton rows, each
+                   `RANGE_ROW_MIN_HEIGHT` tall like the real one it will
+                   become. Same count in both arms, so the swap from
+                   skeleton to `<RangeFilterRow>` costs no further height. */}
+            {props.categoryFeatures === undefined ? (
               <>
                 <Divider style={{ margin: 0 }} />
-                <Flex
-                  vertical
-                  gap={spacing[3]}
-                  data-testid="search-ranges-attributes"
-                >
-                  {attributeRanges.map((group) => (
-                    <RangeFilterRow
-                      key={group.slug}
-                      group={group}
-                      onApply={bag.setRange}
-                    />
-                  ))}
-                </Flex>
+                <div
+                  aria-hidden="true"
+                  data-testid="search-ranges-attributes-reserve"
+                  style={{ minBlockSize: RANGE_ROW_MIN_HEIGHT }}
+                />
               </>
+            ) : (
+              attributeRanges.length > 0 && (
+                <>
+                  <Divider style={{ margin: 0 }} />
+                  <Flex
+                    vertical
+                    gap={spacing[3]}
+                    data-testid="search-ranges-attributes"
+                  >
+                    {bag.state.status === "ready"
+                      ? attributeRanges.map((group) => (
+                          <RangeFilterRow
+                            key={group.slug}
+                            group={group}
+                            onApply={bag.setRange}
+                          />
+                        ))
+                      : attributeRanges.map((group) => (
+                          <RangeRowSkeleton key={group.slug} />
+                        ))}
+                  </Flex>
+                </>
+              )
             )}
 
             {footerBar !== "none" && (

package/src/default/RangeFilterRow.tsx

@@ -17,7 +17,7 @@
  */
 import { useRef, useState } from "react";
 import type { ReactElement } from "react";
-import { Button, Flex, InputNumber, Select, Typography } from "antd";
+import { Button, Flex, InputNumber, Select, Skeleton, Typography } from "antd";
 import { actionAvailable, actionBlocked, useFormat, useT } from "@stapel/core";
 import type { ActionAvailability } from "@stapel/core";
 import { GatedButton } from "@stapel/tokens-antd/skin";
@@ -30,6 +30,49 @@ import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
 /** Floor width of one bound field, so two of them fit a 390px phone row. */
 export const RANGE_FIELD_MIN_WIDTH = 96;
 
+/**
+ * One row's reserved block-size — a label line plus one control row, the two
+ * lines every real row draws. Used both as the skeleton row's floor and as
+ * the whole reserve when the schema itself is not known yet (D361: a 53px
+ * jump inside the rail when the attribute-range block had no box to arrive
+ * into, because nothing reserved its height before the answer landed).
+ */
+export const RANGE_ROW_MIN_HEIGHT = 76;
+
+/** Floor width of the label placeholder in {@link RangeRowSkeleton} — a
+ * named one-off, not a spacing step: it bounds a text skeleton, not a gap. */
+const RANGE_SKELETON_LABEL_WIDTH = 160;
+
+/**
+ * The unrevealed shape of one range row — same two lines, same field widths,
+ * no numbers. Drawn for a slug the schema already names while the answer
+ * that would fill it (bounds, applied value, unit) has not landed yet, so
+ * the rail's box is the row's own final height from the first paint rather
+ * than growing into it once the real row replaces this one.
+ */
+export function RangeRowSkeleton(): ReactElement {
+  return (
+    <Flex
+      vertical
+      gap={spacing[1]}
+      aria-hidden="true"
+      data-testid="facet-range-skeleton"
+      style={{ minBlockSize: RANGE_ROW_MIN_HEIGHT }}
+    >
+      <Skeleton.Input
+        active
+        size="small"
+        style={{ maxWidth: RANGE_SKELETON_LABEL_WIDTH }}
+      />
+      <Flex gap={spacing[2]} align="center" wrap>
+        <Skeleton.Input active style={{ minWidth: RANGE_FIELD_MIN_WIDTH }} />
+        <Skeleton.Input active style={{ minWidth: RANGE_FIELD_MIN_WIDTH }} />
+        <Skeleton.Button active />
+      </Flex>
+    </Flex>
+  );
+}
+
 export interface RangeFilterRowProps {
   readonly group: RangeGroup;
   /** `null` clears the slug's range entirely. */

package/src/default/SearchPage.tsx

@@ -272,14 +272,18 @@ export interface SearchPageProps extends ThemeModeProp, ParseSearchStateOptions
    * the two frames want opposite shapes and only this component knows which
    * one it is drawing: the desktop rail gets `"field"` (a select-style «Any»
    * that opens the searchable list — a 418-value vocabulary held open in a
-   * 280px column is the whole column), the phone sheet gets `"inline"`
-   * (the sheet is already the disclosure). Set it to override both.
+   * 280px column is the whole column), the phone sheet gets `"sheet"` — the
+   * same trigger row, opening a nested picker with a search box, a
+   * recommended band and the rest.
    *
-   * It was unreachable through this component until now: the panel had the
-   * prop, `<SearchPage>` forwarded nothing, and a storefront that mounts the
-   * page rather than the pane could not get the field at all.
+   * The phone default was `"inline"`, which drew the axis as a wall of
+   * checkboxes with a "Find a value" box over it while the COMPOSER's picker
+   * for the very same vocabulary was a trigger and a sheet. One dictionary,
+   * two gestures, depending on which half of the product you were in. Set it
+   * to override both; `"inline"` is still there for a surface that is
+   * already devoted to one group.
    */
-  readonly dictionaryMode?: "field" | "inline";
+  readonly dictionaryMode?: "field" | "inline" | "sheet";
   /**
    * How many groups the rail draws before the rest fold behind "All filters"
    * — see {@link FacetPanelPaneProps.visibleGroups}.
@@ -455,7 +459,7 @@ export interface SearchPageProps extends ThemeModeProp, ParseSearchStateOptions
 
 interface SearchPageBodyProps {
   readonly renderCard?: SearchCardRenderer;
-  readonly dictionaryMode?: "field" | "inline";
+  readonly dictionaryMode?: "field" | "inline" | "sheet";
   readonly visibleGroups?: number | null;
   readonly categoryFeatures?: readonly FeatureDef[];
   readonly renderEmptyExits?: () => ReactNode;
@@ -587,7 +591,7 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
             : // STATIC, not sticky: the rail scrolls with the page, and a bar
               // pinned to the port's floor sat on top of the last groups.
               { footerBar: "static" as const })}
-          dictionaryMode={props.dictionaryMode ?? (layout === "sheet" ? "inline" : "field")}
+          dictionaryMode={props.dictionaryMode ?? (layout === "sheet" ? "sheet" : "field")}
           // `??` would treat an explicit `null` ("never fold") the same as
           // "not set": `visibleGroups` uses `null` as a real value, unlike
           // `dictionaryMode` above, so only `undefined` falls through.

package/src/default/index.ts

@@ -107,6 +107,7 @@ export {
   facetOptionNodes,
   isDictionaryFacet,
   FACET_DICTIONARY_THRESHOLD,
+  FACET_SHEET_PAGE,
   FACET_VISIBLE_OPTIONS,
 } from "./FacetGroupControl.js";
 export type {

package/src/headless/FacetPanel.tsx

@@ -89,6 +89,15 @@ export interface FacetPanelBag {
   readonly activeFilters: number;
 
   toggle(slug: string, value: string): void;
+  /**
+   * Write one slug's chosen values WHOLE — the bulk half of `toggle`.
+   *
+   * `toggle` reads the state it flips, so several of them in one tick
+   * collapse into the last. A control that holds a draft and applies it once
+   * — the phone's dictionary sheet — needs to say the whole list, and a
+   * storefront replaying a saved search needs the same call.
+   */
+  setValues(slug: string, values: readonly string[]): void;
   setRange(slug: string, range: SearchRange | null): void;
   clear(slug: string): void;
   clearAll(): void;
@@ -224,6 +233,7 @@ export function useFacetPanel(props: {
       envelope.data.degraded.includes(FACET_PLAN_EVIDENCE),
     activeFilters,
     toggle: toggleFilter,
+    setValues: setFilter,
     setRange,
     clear: (slug) => {
       setFilter(slug, []);

package/src/i18n/es.ts

@@ -93,6 +93,9 @@ export const searchI18nBundleEs: I18nDictionary = {
   "search.facets.dictionary_empty": "Ningún valor coincide con esto",
   "search.facets.dictionary_chosen": "Elegido",
   "search.facets.dictionary_any": "Cualquiera",
+  "search.facets.dictionary_recommended": "Recomendados",
+  "search.facets.dictionary_all_values": "Todos los valores",
+  "search.facets.dictionary_done": "Listo",
   "search.facets.all_filters": "Todos los filtros ({count})",
   "search.facets.range_bounds": "de {min} a {max}",
   "search.facets.popular_all": "Todos",