@stapel/search-react 0.22.0 → 0.24.0

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.22.0",
+  "version": "0.24.0",
   "defined": [],
   "flows": []
 }

package/src/api/types.ts

@@ -30,6 +30,19 @@ export type Schemas = components["schemas"];
  */
 export type FacetLabels = Schemas["FacetLabels"] & {
   readonly label?: string | null;
+  /**
+   * Whether {@link label} is a translation KEY rather than a caption, the way
+   * `translatable` says it for the values.
+   *
+   * Measured on a live answer (`category=141/151`, 2026-09-04): the server
+   * sends it beside every label — a make caption with
+   * `label_translatable: false`, a condition caption with `true` — and the
+   * describe it. Declared, not consumed: this pair passes the group heading
+   * through its translator either way, and a caption that is not a key comes
+   * back unchanged (`translate()` keeps a key it cannot resolve). Typed so a
+   * fixture captured from the wire is not a type error.
+   */
+  readonly label_translatable?: boolean;
 };
 
 /** `facet_labels` as a whole: `{slug: {label, translatable, values}}`. */

package/src/default/FacetGroupControl.tsx

@@ -66,7 +66,7 @@ import { useState } from "react";
 import type { CSSProperties, ReactElement } from "react";
 import { Button, Checkbox, Flex, Input, Typography } from "antd";
 import { useT } from "@stapel/core";
-import { radii, spacing } from "@stapel/tokens";
+import { controls, cssVar, radii, spacing } from "@stapel/tokens";
 import {
   VOCABULARY_BACKED_TYPES,
   featureConfig,
@@ -181,18 +181,28 @@ export function isDictionaryFacet(group: FacetGroup): boolean {
 /**
  * Which of the four shapes a group takes.
  *
- * Order matters: a hierarchical facet is nested even when it is single-choice,
- * because losing the tree costs more than losing the pills; and a dictionary
- * is a dictionary before it is a checkbox list, because the checkbox list is
- * the shape it was drawn as when nobody could pick a make.
+ * Order matters, and it changed in one place after a live measurement:
+ *
+ *  - a hierarchical facet is nested even when it is single-choice, because
+ *    losing the tree costs more than losing the pills;
+ *  - a DICTIONARY outranks the pills. The make axis on the live cars leaf
+ *    `maxSelected: 1` over a 418-value vocabulary, so "pick one" won and the
+ *    control it produced was four hundred pills in a 280px rail — a wall
+ *    with a different border radius. Above the fold the shape a person needs
+ *    is a search box, whether or not they may tick two; below it,
+ *    single-choice still means pills, because `isDictionaryFacet` requires
+ *    more than {@link FACET_DICTIONARY_THRESHOLD} counted buckets;
+ *  - and a dictionary is a dictionary before it is a checkbox list, because
+ *    the checkbox list is the shape it was drawn as when nobody could pick a
+ *    make.
  */
 export function facetGroupShape(group: FacetGroup): FacetGroupShape {
   const feature = group.feature;
   if (feature !== undefined && featureType(feature) === "hierarchical_select") {
     return "nested";
   }
-  if (singleChoice(feature)) return "segmented";
-  return isDictionaryFacet(group) ? "dictionary" : "checkbox";
+  if (isDictionaryFacet(group)) return "dictionary";
+  return singleChoice(feature) ? "segmented" : "checkbox";
 }
 
 /**
@@ -519,6 +529,105 @@ function DictionaryBody(props: {
   );
 }
 
+/**
+ * The closed face of a dictionary group on DESKTOP: a select-shaped field
+ * that reads what is chosen, or "Any".
+ *
+ * A 418-value vocabulary rendered as a permanently-open box plus a scrolling
+ * list is right in a phone sheet, where the sheet IS the disclosure and there
+ * is one group on screen. In a 280px rail it is the whole rail: the reference
+ * classified draws the make as a field reading "Any" that opens the
+ * searchable list, and every axis under it stays reachable at a glance.
+ *
+ * A native `<button role="combobox">` rather than antd's `Select`, for the
+ * same reason the option pills are native buttons: the list underneath is
+ * this component's — it carries per-option counts, a chosen block and a fold
+ * — and a `Select` that only lends its trigger is a dependency on a popup
+ * layer for a border. `aria-expanded` on a real button is the disclosure
+ * pattern; Escape closes, and the field keeps focus so the next Tab goes
+ * where the person expects.
+ */
+const DICTIONARY_FIELD: CSSProperties = {
+  display: "flex",
+  alignItems: "center",
+  gap: spacing[1],
+  inlineSize: "100%",
+  minBlockSize: controls.height,
+  paddingInline: spacing[2],
+  paddingBlock: spacing[1],
+  border: `1px solid ${cssVar("border")}`,
+  borderRadius: cssVar("radius-md"),
+  background: cssVar("surface"),
+  color: "inherit",
+  font: "inherit",
+  textAlign: "start",
+  cursor: "pointer",
+};
+
+/** The chosen values, or the word for "no constraint on this axis". Never a
+ * count: "3 chosen" makes a person open the field to find out which three. */
+const DICTIONARY_FIELD_TEXT: CSSProperties = {
+  flex: "1 1 auto",
+  minInlineSize: 0,
+  overflow: "hidden",
+  textOverflow: "ellipsis",
+  whiteSpace: "nowrap",
+};
+
+function DictionaryField(props: {
+  readonly group: FacetGroup;
+  readonly onToggle: (slug: string, value: string) => void;
+  readonly visible: number;
+}): ReactElement {
+  const t = useT();
+  const { group } = props;
+  const [open, setOpen] = useState(false);
+  const chosen = group.options.filter((option) => option.selected);
+  const text =
+    chosen.length > 0
+      ? chosen.map((option) => option.label).join(", ")
+      : t(SEARCH_I18N_KEYS.facetsDictionaryAny);
+  return (
+    <Flex vertical gap={spacing[1]}>
+      <button
+        type="button"
+        role="combobox"
+        aria-expanded={open}
+        aria-haspopup="listbox"
+        aria-label={group.label}
+        style={DICTIONARY_FIELD}
+        data-testid={`facet-dictionary-field-${group.slug}`}
+        data-chosen={chosen.length}
+        data-analytics="none"
+        data-analytics-reason="opening a filter group is a read, not a flow step"
+        onKeyDown={(event) => {
+          if (event.key === "Escape" && open) {
+            event.preventDefault();
+            setOpen(false);
+          }
+          if (event.key === "ArrowDown" && !open) {
+            event.preventDefault();
+            setOpen(true);
+          }
+        }}
+        onClick={() => {
+          setOpen((was) => !was);
+        }}
+      >
+        <span style={DICTIONARY_FIELD_TEXT}>{text}</span>
+        <ChevronGlyph open={open} />
+      </button>
+      {open && (
+        <DictionaryBody
+          group={group}
+          onToggle={props.onToggle}
+          visible={props.visible}
+        />
+      )}
+    </Flex>
+  );
+}
+
 export interface FacetGroupControlProps {
   readonly group: FacetGroup;
   readonly onToggle: (slug: string, value: string) => void;
@@ -538,6 +647,14 @@ export interface FacetGroupControlProps {
   /** Whether a `collapsible` group STARTS open. Default `true`. The initial
    * 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.
+   */
+  readonly dictionaryMode?: "field" | "inline";
 }
 
 export function FacetGroupControl(props: FacetGroupControlProps): ReactElement {
@@ -618,13 +735,21 @@ 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" && (
-        <DictionaryBody
-          group={group}
-          onToggle={props.onToggle}
-          visible={limit ?? FACET_VISIBLE_OPTIONS}
-        />
-      )}
+      {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" && (
         <>

package/src/default/FacetPanelPane.tsx

@@ -95,7 +95,11 @@ import type { FacetPanelBag } from "../headless/FacetPanel.js";
 import type { FacetLabelResolver } from "../headless/useFacetLabels.js";
 import { useSearchState } from "../headless/SearchStateProvider.js";
 import { useAppliedCount } from "../headless/useAppliedCount.js";
-import { facetCoverage, orderFacetGroups } from "../state/facets.js";
+import {
+  facetCoverage,
+  facetGroupIsDrawable,
+  orderFacetGroupsBySchema,
+} from "../state/facets.js";
 import type { FacetGroup } from "../state/facets.js";
 import { FacetGroupControl } from "./FacetGroupControl.js";
 import { buildRangeGroups } from "../state/ranges.js";
@@ -176,6 +180,17 @@ export const FACET_OPEN_GROUPS = 5;
  */
 export const FACET_SEARCH_THRESHOLD = 6;
 
+/**
+ * How many groups the rail draws before the rest go behind one control.
+ *
+ * The reference classified shows a make, a price, a year and a handful of
+ * body axes, and then the word "all filters" — eight is the count that fills
+ * a 900px rail once the partition row and the price have taken their share,
+ * and it is the point past which a person is scanning rather than reading.
+ * The tail is not hidden: `facetsAllFilters` names how many are in it.
+ */
+export const FACET_VISIBLE_GROUPS = 8;
+
 /** What a host's category control is handed. */
 export interface CategoryFilterSlotProps {
   /** The `root/leaf` path the search is narrowed to, if any. */
@@ -256,6 +271,37 @@ export interface FacetPanelPaneProps extends ThemeModeProp {
    * count-bearing bar above that one would be the same sentence twice.
    */
   readonly footerBar?: boolean;
+  /**
+   * The partition control, drawn at the TOP of the panel — above the price,
+   * above every facet.
+   *
+   * A partition (`children_as: "chips"`) is not a filter among filters: it is
+   * which of one template's halves the page is about, and the reference
+   * classified puts it first for that reason (a car-type row: all, used,
+   * new). It is a slot rather than a component because the
+   * children come from the catalogue tree, which is `categories-react`'s;
+   * `<PartitionChips variant="segmented">` is what a host usually puts here.
+   */
+  readonly partition?: ReactNode;
+  /**
+   * Slugs pinned above every other group, in the order given — the axis a
+   * page has already decided is its subject. See
+   * {@link orderFacetGroupsBySchema}.
+   */
+  readonly pinnedFacets?: readonly string[];
+  /**
+   * How many groups before the tail folds under "All filters (K)". Default
+   * {@link FACET_VISIBLE_GROUPS}; `null` draws every group, which is what a
+   * phone sheet devoted to filtering wants.
+   */
+  readonly visibleGroups?: number | null;
+  /**
+   * 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.
+   */
+  readonly dictionaryMode?: "field" | "inline";
 }
 
 /**
@@ -463,6 +509,10 @@ export function FacetPanelPane(props: FacetPanelPaneProps): ReactElement {
   // panel is drawn, never what the search is, so it must not survive into a
   // shared link the way everything in `useSearchState` does.
   const [filterQuery, setFilterQuery] = useState("");
+  // Whether the tail past `visibleGroups` is open. Presentation, like the
+  // panel's own search box: the URL is the search, and how much of the rail a
+  // person has unfolded is not part of it.
+  const [tailOpen, setTailOpen] = useState(false);
 
   return (
     <SkinTheme {...(props.mode !== undefined ? { mode: props.mode } : {})}>
@@ -540,6 +590,12 @@ export function FacetPanelPane(props: FacetPanelPaneProps): ReactElement {
               )}
             </Flex>
 
+            {/* The partition first: which half of one template this page is
+                about is not a filter among filters. */}
+            {props.partition !== undefined && (
+              <div data-testid="search-partition">{props.partition}</div>
+            )}
+
             <CategoryFilter
               {...(props.renderCategoryFilter !== undefined
                 ? { render: props.renderCategoryFilter }
@@ -617,25 +673,34 @@ export function FacetPanelPane(props: FacetPanelPaneProps): ReactElement {
                 // case: a `ref_select` whose config is a bare pointer into
                 // a vocabulary this pair cannot read. A heading with no
                 // control under it names nothing, so it is not drawn.
-                // Evidence order, the chip row's rule applied to the rail:
-                // answered axes first, then the ones this corpus actually
-                // fills. Schema order is the catalogue importer's, and an
-                // imported catalogue's is alphabetical-by-accident.
-                const drawable = orderFacetGroups(
-                  groups.filter((group) => group.options.length > 0)
-                );
+                // SCHEMA order, required first — see
+                // `orderFacetGroupsBySchema`. The rail ranked by evidence for
+                // two releases, which on a three-listing cars leaf put
+                // condition and colour above make, model and year:
+                // the busiest axis is the right question for a chip row with
+                // room for four and the wrong one for the column a person
+                // narrows a catalogue in. Groups the schema does not name
+                // keep evidence order among themselves.
+                const drawable = orderFacetGroupsBySchema({
+                  groups: groups.filter(facetGroupIsDrawable),
+                  ...(props.categoryFeatures !== undefined
+                    ? { categoryFeatures: props.categoryFeatures }
+                    : {}),
+                  ...(props.pinnedFacets !== undefined
+                    ? { pinned: props.pinnedFacets }
+                    : {}),
+                });
                 // Which groups OPEN — see the module note. Chosen groups are
-                // open unconditionally below; here the answer's evidence
-                // picks the rest: the top counted groups by coverage, and a
-                // group the server never counted sums to zero, so the wall
-                // of "not counted" rows starts as headers.
-                const openByEvidence = new Set(
+                // open unconditionally below; the rest are the first
+                // FACET_OPEN_GROUPS of the order above, so the panel's first
+                // screen is the axes the category itself calls required. A
+                // group the server never counted starts as a header, which is
+                // what keeps the wall of "not counted" rows folded.
+                const openByOrder = new Set(
                   drawable
-                    .filter((group) => group.counted)
-                    .map((group) => [group, facetCoverage(group)] as const)
-                    .sort((a, b) => b[1] - a[1])
+                    .filter((group) => group.counted || facetCoverage(group) > 0)
                     .slice(0, FACET_OPEN_GROUPS)
-                    .map(([group]) => group.slug)
+                    .map((group) => group.slug)
                 );
                 const searchable = drawable.length >= FACET_SEARCH_THRESHOLD;
                 const needle = searchable
@@ -648,6 +713,33 @@ export function FacetPanelPane(props: FacetPanelPaneProps): ReactElement {
                   );
                 const listed =
                   needle === "" ? drawable : drawable.filter(matches);
+                // The tail. Only while nothing is typed: a query has already
+                // narrowed the list, and folding its answer would hide the
+                // thing that was looked for. One group over the limit is not
+                // folded — a control that reveals exactly one heading costs
+                // more than it saves.
+                const groupLimit =
+                  props.visibleGroups === null
+                    ? null
+                    : (props.visibleGroups ?? FACET_VISIBLE_GROUPS);
+                const tailFolded =
+                  groupLimit !== null &&
+                  needle === "" &&
+                  listed.length > groupLimit + 1;
+                // A CONSTRAINT NEVER FOLDS. The fold hides axes a person has
+                // not touched; a group they have chosen a value in stays in
+                // the visible band wherever the schema put it, because the
+                // control that removes a filter is the one they came back
+                // for. (The rail used to rank answered axes to the top for
+                // this; schema order is stable under a click, which a rail
+                // that reshuffles as you tick is not.)
+                const shownGroups =
+                  tailFolded && !tailOpen && groupLimit !== null
+                    ? listed.filter(
+                        (group, index) =>
+                          index < groupLimit || group.selected.length > 0
+                      )
+                    : listed;
                 return (
                   <Flex vertical gap={spacing[4]}>
                     {searchable && (
@@ -684,7 +776,7 @@ export function FacetPanelPane(props: FacetPanelPaneProps): ReactElement {
                         a closed header is not an answer. Remounting is the
                         honest way to re-ask the question; the person's own
                         opens and closes come back when the box clears. */}
-                    {listed.map((group) => (
+                    {shownGroups.map((group) => (
                       <FacetGroupControl
                         key={needle === "" ? group.slug : `${group.slug}:match`}
                         group={group}
@@ -693,10 +785,30 @@ export function FacetPanelPane(props: FacetPanelPaneProps): ReactElement {
                         defaultOpen={
                           needle !== "" ||
                           group.selected.length > 0 ||
-                          openByEvidence.has(group.slug)
+                          openByOrder.has(group.slug)
                         }
+                        {...(props.dictionaryMode !== undefined
+                          ? { dictionaryMode: props.dictionaryMode }
+                          : {})}
                       />
                     ))}
+                    {tailFolded && (
+                      <Button
+                        style={{ alignSelf: "flex-start" }}
+                        data-testid="facets-all-filters"
+                        data-analytics="none"
+                        data-analytics-reason="opening the filter tail is a read, not a flow step"
+                        onClick={() => {
+                          setTailOpen((was) => !was);
+                        }}
+                      >
+                        {tailOpen
+                          ? t(SEARCH_I18N_KEYS.facetsShowLess)
+                          : t(SEARCH_I18N_KEYS.facetsAllFilters, {
+                              count: listed.length - (groupLimit ?? 0),
+                            })}
+                      </Button>
+                    )}
                     <Typography.Text type="secondary">
                       {t(SEARCH_I18N_KEYS.facetsDrillDownHint)}
                     </Typography.Text>