@stapel/search-react 0.22.0 → 0.24.0

package/src/default/FilterChips.tsx

@@ -1,6 +1,42 @@
 /**
- * `<FilterChips>` — the phone's filter row: one horizontally scrolling line of
- * chips, each of which opens its OWN picker.
+ * `<FilterChips>` — the filter row, in its two modes.
+ *
+ * ## `mode="openers"` (the default): the phone's row
+ *
+ * One horizontally scrolling line of chips, each of which opens its OWN
+ * picker. Everything below this heading describes that mode.
+ *
+ * ## `mode="applied"`: the row a rail on screen needs
+ *
+ * Where the panel is already drawn — the desktop column — a row of openers is
+ * the wrong shape twice over: it prints the whole rail a second time, and no
+ * chip in it REMOVES anything without opening a modal over the results. A
+ * storefront hit exactly that (a 2377px filter column; picking two values left
+ * nothing between the header and the first card, and dropping one of them
+ * meant scrolling the rail until its button came back) and wrote its own row.
+ * This mode is that row, in the pair:
+ *
+ *  - one chip per applied facet VALUE and per applied numeric range, never per
+ *    axis — "Brand" with three values chosen is three chips, three removals;
+ *  - each chip names the axis AND the value ("Brand: Bosch", "Price: from 100
+ *    to 500"), because beside a dozen axes a bare value names nothing;
+ *  - each chip is a real `<button>` whose press removes THAT constraint, and
+ *    whose accessible name says so — not an antd `Tag closable`, whose close
+ *    icon is a `<span>` with no tab stop, i.e. a constraint a keyboard can
+ *    read and cannot drop;
+ *  - the same clear-all the rail's footer runs, beside the chips instead of a
+ *    column-height away;
+ *  - nothing applied, nothing drawn. An empty band above the results is
+ *    furniture, and this row's whole claim is that it is there only when it
+ *    has something to say.
+ *
+ * Both modes read the SAME bag (`useFacetPanel`, `buildRangeGroups` over the
+ * page's own state) the rail reads, so no two surfaces can disagree about what
+ * is applied or about what a value is called — including the label path:
+ * the answer's `facet_labels` first, the category schema second, the raw slug
+ * marked as such third. Every applied chip stamps `data-label-source` and
+ * `data-value-label-source` so a storefront's test fails on a raw index term
+ * rather than eyeballing one.
  *
  * ## What it replaces, and why the replacement is not cosmetic
  *
@@ -133,8 +169,11 @@ import type { FacetLabelResolver } from "../headless/useFacetLabels.js";
 import { useSearchState } from "../headless/SearchStateProvider.js";
 import { buildRangeGroups } from "../state/ranges.js";
 import type { RangeGroup } from "../state/ranges.js";
-import { compareFacetsByEvidence } from "../state/facets.js";
-import type { FacetGroup } from "../state/facets.js";
+import {
+  compareFacetsByEvidence,
+  facetGroupIsDrawable,
+} from "../state/facets.js";
+import type { FacetGroup, FacetLabelSource } from "../state/facets.js";
 import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
 import { FacetGroupControl } from "./FacetGroupControl.js";
 import { RangeFilterRow } from "./RangeFilterRow.js";
@@ -287,7 +326,11 @@ export function capChipRow(
   return { visible: specs.slice(0, cut), overflow: specs.length - cut };
 }
 
-export interface FilterChipsProps {
+/** What the row is FOR — see this module's opening note. */
+export type FilterChipsMode = "openers" | "applied";
+
+/** What both modes read the search through. */
+export interface FilterChipsCommonProps {
   /** The category's feature schema — the source of option labels, of which
    * slugs get a range chip, of which slugs are choosable at all, and of how
    * each group is drawn. */
@@ -299,6 +342,11 @@ export interface FilterChipsProps {
    * value cannot read one way on a chip and another way inside the sheet.
    */
   readonly resolveFacetLabels?: FacetLabelResolver;
+}
+
+export interface FilterChipsOpenerProps extends FilterChipsCommonProps {
+  /** The default. Every chip OPENS a picker; see the module note. */
+  readonly mode?: "openers";
   /**
    * The catalogue picker (`categories-react`), same slot the panel takes.
    *
@@ -332,6 +380,20 @@ export interface FilterChipsProps {
   readonly maxRowChips?: number | null;
 }
 
+/**
+ * The applied row: one chip per constraint, each of which removes it.
+ *
+ * None of the opener props are here and that is the point — a row that draws
+ * only what is applied has no picker to open, no capped tail to stand in front
+ * of and no category chip (narrowing the category is a navigation, not a
+ * filter this row can drop).
+ */
+export interface FilterChipsAppliedProps extends FilterChipsCommonProps {
+  readonly mode: "applied";
+}
+
+export type FilterChipsProps = FilterChipsOpenerProps | FilterChipsAppliedProps;
+
 /**
  * The label a chip carries: the group's name alone when nothing is chosen,
  * and the CHOICE when something is — "Brand" becomes "Bosch", "Brand, +2".
@@ -370,7 +432,22 @@ export function categoryLeaf(path: string): string | undefined {
   return /^\d+$/.test(leaf) ? undefined : leaf;
 }
 
+/**
+ * The row, in whichever mode was asked for.
+ *
+ * Two components rather than one with a branch in it: the modes share the
+ * search they read and share nothing they DRAW, and a single body would have
+ * to run both sets of hooks on every render of either.
+ */
 export function FilterChips(props: FilterChipsProps): ReactElement | null {
+  return props.mode === "applied" ? (
+    <AppliedChipRow {...props} />
+  ) : (
+    <OpenerChipRow {...props} />
+  );
+}
+
+function OpenerChipRow(props: FilterChipsOpenerProps): ReactElement | null {
   const t = useT();
   const { state, setCategory } = useSearchState();
   const bag = useFacetPanel({
@@ -400,7 +477,7 @@ export function FilterChips(props: FilterChipsProps): ReactElement | null {
   });
   const groups =
     bag.state.status === "ready"
-      ? bag.state.data.filter((group) => group.options.length > 0)
+      ? bag.state.data.filter(facetGroupIsDrawable)
       : [];
 
   const close = (): void => {
@@ -641,6 +718,236 @@ export function FilterChips(props: FilterChipsProps): ReactElement | null {
   );
 }
 
+/* ── the applied row ────────────────────────────────────────────────────── */
+
+type Translate = (key: string, params?: Record<string, unknown>) => string;
+
+/** Which constraint one applied chip drops. */
+export type AppliedChipTarget =
+  | { readonly kind: "facet"; readonly slug: string; readonly value: string }
+  | { readonly kind: "range"; readonly slug: string };
+
+/** One applied constraint, resolved to the words it prints and what it drops. */
+export interface AppliedChip {
+  readonly key: string;
+  readonly target: AppliedChipTarget;
+  /** What the AXIS is called, and which source named it. */
+  readonly name: string;
+  readonly nameSource: FacetLabelSource;
+  /** What the VALUE is called, and which source named it. */
+  readonly value: string;
+  readonly valueSource: FacetLabelSource;
+}
+
+/** The chip's own test hook — the constraint it drops, spelled out. */
+export function appliedChipTestId(target: AppliedChipTarget): string {
+  return target.kind === "facet"
+    ? `search-applied-chip-${target.slug}-${target.value}`
+    : `search-applied-chip-range-${target.slug}`;
+}
+
+/**
+ * A numeric constraint as one phrase.
+ *
+ * The bounds print exactly as the URL carries them — the wire never promised a
+ * number and reformatting one would rewrite the link — except on a core MONEY
+ * axis, where the currency the answer's own cards carry turns "1000" into
+ * money, the same way the cards do.
+ */
+export function rangeChipText(range: RangeGroup, t: Translate): string {
+  const one = (bound: string): string => {
+    const n = Number(bound);
+    if (range.currency !== undefined && Number.isFinite(n)) {
+      return new Intl.NumberFormat(undefined, {
+        style: "currency",
+        currency: range.currency,
+        maximumFractionDigits: 0,
+      }).format(n);
+    }
+    return range.unit === undefined ? bound : `${bound} ${range.unit}`;
+  };
+  if (range.from !== undefined && range.to !== undefined) {
+    return t(SEARCH_I18N_KEYS.filtersChipRangeBetween, {
+      from: one(range.from),
+      to: one(range.to),
+    });
+  }
+  if (range.from !== undefined) {
+    return t(SEARCH_I18N_KEYS.filtersChipRangeFrom, { from: one(range.from) });
+  }
+  return t(SEARCH_I18N_KEYS.filtersChipRangeTo, { to: one(range.to ?? "") });
+}
+
+/**
+ * Where a range axis got its NAME — the same three-source question the facet
+ * groups answer for themselves, asked of the other half of the model.
+ *
+ * A core axis is named by the answer declaring it (`facet_meta.core_ranges`)
+ * and this package's own catalogue; a category attribute is named by the
+ * schema; a slug the URL constrains that neither explains prints as itself,
+ * and that is `"none"` — the same honest bottom the rail marks.
+ */
+export function rangeLabelSource(range: RangeGroup): FacetLabelSource {
+  if (range.core) return "server";
+  return range.feature === undefined ? "none" : "schema";
+}
+
+/**
+ * Every applied constraint of the current search, in the order the rail states
+ * them: the facet values first, in the order the groups came in, then the
+ * numeric ranges.
+ *
+ * Pure, and exported, because "one chip per VALUE" is the whole shape of the
+ * row — a build that collapsed three chosen brands into one chip would remove
+ * three filters with one press and no test that only counts chips would see
+ * it.
+ */
+export function buildAppliedChips(input: {
+  readonly groups: readonly FacetGroup[];
+  readonly ranges: readonly RangeGroup[];
+  readonly t: Translate;
+}): readonly AppliedChip[] {
+  const chips: AppliedChip[] = [];
+  for (const group of input.groups) {
+    for (const option of group.options) {
+      if (!option.selected) continue;
+      chips.push({
+        key: `f.${group.slug}=${option.value}`,
+        target: { kind: "facet", slug: group.slug, value: option.value },
+        name: group.label,
+        nameSource: group.labelSource,
+        value: option.label,
+        valueSource: option.labelSource,
+      });
+    }
+  }
+  for (const range of input.ranges) {
+    if (!range.active) continue;
+    const source = rangeLabelSource(range);
+    chips.push({
+      key: `r.${range.slug}`,
+      target: { kind: "range", slug: range.slug },
+      name: range.label,
+      nameSource: source,
+      value: rangeChipText(range, input.t),
+      // The bounds are the person's own numbers — nobody had to name them.
+      valueSource: source,
+    });
+  }
+  return chips;
+}
+
+/** The applied row wraps: it stands beside a rail, not on a 390px scroller,
+ * and a constraint pushed off the line is a constraint with no control. */
+const APPLIED_ROW: CSSProperties = {
+  display: "flex",
+  alignItems: "center",
+  gap: spacing[2],
+  flexWrap: "wrap",
+  // Room for the focus ring of the first chip, which a flush edge clips.
+  paddingBlock: spacing[1],
+};
+
+function AppliedChipRow(props: FilterChipsAppliedProps): ReactElement | null {
+  const t = useT();
+  const { state } = useSearchState();
+  const bag = useFacetPanel({
+    ...(props.categoryFeatures !== undefined
+      ? { categoryFeatures: props.categoryFeatures }
+      : {}),
+    ...(props.locale !== undefined ? { locale: props.locale } : {}),
+    ...(props.resolveFacetLabels !== undefined
+      ? { resolveFacetLabels: props.resolveFacetLabels }
+      : {}),
+  });
+  const ranges = buildRangeGroups({
+    state,
+    ...(props.categoryFeatures !== undefined
+      ? { categoryFeatures: props.categoryFeatures }
+      : {}),
+    coreRanges: bag.coreRanges,
+    ...(bag.currency !== undefined ? { currency: bag.currency } : {}),
+    t,
+  });
+
+  /* NOTHING IS DRAWN UNTIL THE ANSWER LANDS.
+   *
+   * Both halves of a chip are named by the envelope: the heading path
+   * (`facet_labels[<slug>]`), and — for a range — the answer's own declaration
+   * of which axes are CORE columns (`facet_meta.core_ranges`). Before it, an
+   * `r.price` the URL carries is a slug this row has no name for, so it would
+   * draw a chip captioned with that slug and rename it a moment later. A
+   * caption that changes under the reader is worse than a caption that
+   * arrives; the panel is the control in the meantime.
+   */
+  const answered = bag.state.status === "ready";
+  const chips = buildAppliedChips({
+    groups: answered ? bag.state.data : [],
+    ranges: answered ? ranges : [],
+    t,
+  });
+  if (chips.length === 0) return null;
+
+  const remove = (target: AppliedChipTarget): void => {
+    if (target.kind === "facet") bag.toggle(target.slug, target.value);
+    else bag.setRange(target.slug, null);
+  };
+
+  return (
+    <div
+      style={APPLIED_ROW}
+      role="group"
+      aria-label={t(SEARCH_I18N_KEYS.filtersAppliedLabel)}
+      data-testid="search-applied-chips"
+    >
+      {chips.map((chip) => {
+        const text = t(SEARCH_I18N_KEYS.filtersChipPair, {
+          name: chip.name,
+          value: chip.value,
+        });
+        return (
+          <Button
+            key={chip.key}
+            shape="round"
+            size="small"
+            style={CHIP}
+            data-testid={appliedChipTestId(chip.target)}
+            /* The two halves of the caption, marked with what named each of
+               them. `[data-label-source="none"]` is the assertion that a raw
+               index term ever reached this row. */
+            data-label-source={chip.nameSource}
+            data-value-label-source={chip.valueSource}
+            data-analytics="none"
+            data-analytics-reason="dropping a filter is a read, not a flow step"
+            aria-label={t(SEARCH_I18N_KEYS.filtersChipRemove, { filter: text })}
+            onClick={() => {
+              remove(chip.target);
+            }}
+          >
+            <span>{text}</span>
+            <span aria-hidden="true">{"×"}</span>
+          </Button>
+        );
+      })}
+      {/* The SAME action the rail's own footer runs, beside the chips instead
+          of a column-height down the page. */}
+      <Button
+        type="link"
+        size="small"
+        style={{ paddingInline: 0 }}
+        data-testid="search-applied-chips-clear"
+        data-analytics="none"
+        data-analytics-reason="dropping the filters is a read, not a flow step"
+        onClick={() => {
+          bag.clearAll();
+        }}
+      >
+        {t(SEARCH_I18N_KEYS.facetsClearAll, { count: bag.activeFilters })}
+      </Button>
+    </div>
+  );
+}
+
 /** The mark on the "all filters" chip: something is applied. Not a count —
  * the counts are on the chips beside it, and a number inside a 32px circle is
  * a number nobody reads. */

package/src/default/PartitionChips.tsx

@@ -35,7 +35,7 @@ import type {
 } from "react";
 import { Button } from "antd";
 import { useT } from "@stapel/core";
-import { radii, spacing } from "@stapel/tokens";
+import { cssVar, radii, spacing } from "@stapel/tokens";
 import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
 
 /** One child of a partitioned category. `path` is the slash-joined id path
@@ -58,6 +58,20 @@ export interface PartitionChipsProps {
   readonly allLabel?: ReactNode;
   /** The row's accessible name. Defaults to `search.partition.label`. */
   readonly label?: string;
+  /**
+   * Which shape the row takes. `"chips"` (the default) is the phone's: a
+   * wrapping row of rounded pills above the feed. `"segmented"` is the
+   * desktop RAIL's — one joined control under the axis's own label, which is
+   * how the reference classified draws the same choice (a car-type row:
+   * all, used, new) and what a 280px column has room for.
+   *
+   * The SEMANTICS do not vary with it. Both are the same `radiogroup` with
+   * the same roving tabindex and the same arrow keys — a segmented look is a
+   * border-radius decision, and swapping in a component that draws joined
+   * cells by giving up "exactly one of these is true" would trade the
+   * accessible half of this control for the visible half.
+   */
+  readonly variant?: "chips" | "segmented";
 }
 
 const CHIP: CSSProperties = { borderRadius: radii.full };
@@ -68,6 +82,33 @@ const ROW: CSSProperties = {
   gap: spacing[2],
 };
 
+/**
+ * The segmented row: one joined control, no gaps, the group's own outline.
+ *
+ * `gap: 0` plus a shared border is what makes three buttons read as one
+ * control — the thing a rail needs, because a wrapping pill row in a 280px
+ * column is two ragged lines. `overflow: hidden` clips the cells' own corners
+ * to the group's radius so the ends are round and the joins are square.
+ */
+const SEGMENTED_ROW: CSSProperties = {
+  display: "flex",
+  gap: 0,
+  inlineSize: "100%",
+  border: `1px solid ${cssVar("border")}`,
+  borderRadius: cssVar("radius-md"),
+  overflow: "hidden",
+};
+
+/** One cell of the segmented row: an equal share of the width, square joins,
+ * no border of its own — the group draws the outline. */
+const SEGMENTED_CELL: CSSProperties = {
+  flex: "1 1 0",
+  minInlineSize: 0,
+  borderRadius: 0,
+  borderInline: "none",
+  borderBlock: "none",
+};
+
 /** The row's cells, as `[value, label]` — the parent first, then the
  * children in catalogue order. */
 function cells(
@@ -122,9 +163,11 @@ export function PartitionChips(props: PartitionChipsProps): ReactElement {
   const active = options.findIndex(([value]) => value === props.value);
   const stop = active >= 0 ? active : 0;
 
+  const segmented = props.variant === "segmented";
   return (
     <div
-      style={ROW}
+      style={segmented ? SEGMENTED_ROW : ROW}
+      data-variant={segmented ? "segmented" : "chips"}
       ref={row}
       role="radiogroup"
       aria-label={props.label ?? t(SEARCH_I18N_KEYS.partitionLabel)}
@@ -136,14 +179,14 @@ export function PartitionChips(props: PartitionChipsProps): ReactElement {
           <Button
             key={value ?? "__all__"}
             size="small"
-            shape="round"
+            {...(segmented ? {} : { shape: "round" as const })}
             type={selected ? "primary" : "default"}
             role="radio"
             aria-checked={selected}
             // Roving tabindex: the row is ONE Tab stop and it lands on the
             // chosen chip, not on the first of eight.
             tabIndex={index === stop ? 0 : -1}
-            style={CHIP}
+            style={segmented ? SEGMENTED_CELL : CHIP}
             data-testid={`partition-chip-${value ?? "all"}`}
             data-analytics="none"
             data-analytics-reason="choosing a section is a read, not a flow step"

package/src/default/RangeFilterRow.tsx

@@ -17,7 +17,7 @@
  */
 import { useRef, useState } from "react";
 import type { ReactElement } from "react";
-import { Button, Flex, InputNumber, Typography } from "antd";
+import { Button, Flex, InputNumber, Select, Typography } from "antd";
 import { actionAvailable, actionBlocked, useFormat, useT } from "@stapel/core";
 import type { ActionAvailability } from "@stapel/core";
 import { GatedButton } from "@stapel/tokens-antd/skin";
@@ -70,6 +70,100 @@ function boundSuffix(
   }
 }
 
+/**
+ * One bound of a PICKER axis — a bounded integer small enough to choose from
+ * (`RangeGroup.picker`), which on a cars leaf is the year.
+ *
+ * The founder's walk of the live page put it plainly: the year was a bare
+ * number field. A year is not a quantity a person computes, it is one of a
+ * hundred-odd values, and every classified draws it as two pickers.
+ *
+ * Typing still works, and the rule is the same one `attributes-react` is
+ * building for a bounded integer field: what a person types is a value, not a
+ * query. While the typed text IS a valid value inside the bounds the list
+ * narrows to it and gets out of the way; the moment it is not — a letter, a
+ * year before the catalogue's own floor — the full list comes back WITH the
+ * bounds said in words, because "1899" silently doing nothing is the defect
+ * this replaces.
+ */
+function BoundPicker(props: {
+  readonly group: RangeGroup;
+  readonly bound: "from" | "to";
+  readonly value: string;
+  readonly onChange: (value: string) => void;
+  readonly onCommit: () => void;
+}): ReactElement {
+  const t = useT();
+  const { group } = props;
+  const [typed, setTyped] = useState("");
+  const values = group.picker ?? [];
+  const min = group.min ?? values[values.length - 1];
+  const max = group.max ?? values[0];
+  const query = typed.trim();
+  const asNumber = Number(query);
+  // "Valid" is the whole rule: a number, whole, and inside the axis's own
+  // bounds. Anything else is a query that matched nothing, not a value.
+  const valid =
+    query !== "" &&
+    /^-?\d+$/.test(query) &&
+    Number.isInteger(asNumber) &&
+    (min === undefined || asNumber >= min) &&
+    (max === undefined || asNumber <= max);
+  const listed = valid
+    ? values.filter((value) => String(value).startsWith(query))
+    : values;
+  return (
+    <Flex vertical gap={spacing[1]}>
+      <Select
+        showSearch
+        allowClear
+        value={props.value === "" ? null : props.value}
+        searchValue={typed}
+        // The list is already narrowed above, by the rule this control is
+        // about; antd's own substring filter would narrow it a second time
+        // and by a different rule.
+        filterOption={false}
+        placeholder={t(
+          props.bound === "from"
+            ? SEARCH_I18N_KEYS.facetsRangeFrom
+            : SEARCH_I18N_KEYS.facetsRangeTo
+        )}
+        aria-label={t(
+          props.bound === "from"
+            ? SEARCH_I18N_KEYS.facetsRangeFromAria
+            : SEARCH_I18N_KEYS.facetsRangeToAria,
+          { feature: group.label }
+        )}
+        data-testid={`facet-range-${group.slug}-${props.bound}`}
+        style={{ minWidth: RANGE_FIELD_MIN_WIDTH }}
+        options={listed.map((value) => ({
+          value: String(value),
+          label: String(value),
+        }))}
+        onSearch={setTyped}
+        onChange={(next: string | null) => {
+          setTyped("");
+          props.onChange(next ?? "");
+        }}
+        onBlur={props.onCommit}
+      />
+      {/* Said only when the typing has gone outside the axis — a hint over an
+          untouched field is chrome. */}
+      {query !== "" && !valid && (
+        <Typography.Text
+          type="secondary"
+          data-testid={`facet-range-${group.slug}-${props.bound}-bounds`}
+        >
+          {t(SEARCH_I18N_KEYS.facetsRangeBounds, {
+            min: String(min ?? ""),
+            max: String(max ?? ""),
+          })}
+        </Typography.Text>
+      )}
+    </Flex>
+  );
+}
+
 export function RangeFilterRow(props: RangeFilterRowProps): ReactElement {
   const t = useT();
   const format = useFormat();
@@ -138,6 +232,25 @@ export function RangeFilterRow(props: RangeFilterRowProps): ReactElement {
         {suffix === undefined ? group.label : `${group.label}, ${suffix}`}
       </Typography.Text>
       <Flex gap={spacing[2]} align="center" wrap>
+        {group.picker !== undefined ? (
+          <>
+            <BoundPicker
+              group={group}
+              bound="from"
+              value={from}
+              onChange={setFrom}
+              onCommit={commit}
+            />
+            <BoundPicker
+              group={group}
+              bound="to"
+              value={to}
+              onChange={setTo}
+              onCommit={commit}
+            />
+          </>
+        ) : (
+        <>
         <InputNumber
           value={from === "" ? null : Number(from)}
           placeholder={t(SEARCH_I18N_KEYS.facetsRangeFrom)}
@@ -172,6 +285,8 @@ export function RangeFilterRow(props: RangeFilterRowProps): ReactElement {
           }}
           onPressEnter={commit}
         />
+        </>
+        )}
         {/* Primary when there is something to apply, secondary when there is
             not. It used to be the other way round — filled over two empty
             fields, ghosted the moment the person had typed the numbers the