@stapel/search-react 0.10.0 → 0.12.0

package/src/default/FilterChips.tsx

@@ -41,11 +41,69 @@
  *
  * ## The library is not inventing a classified's filters
  *
- * A chip exists for each facet group the SERVER returned, each numeric range
- * the CATEGORY SCHEMA declares, and the location — plus the leading
- * "all filters" chip. Nothing here knows what a "brand" or a "mileage" is;
- * a deployment with three facets gets three chips and a deployment with none
- * gets the leading chip alone.
+ * A chip exists for each facet group the SERVER returned AND the category
+ * schema types as choosable (`isFacetableFeature` — an `imei` is counted and
+ * is not a filter), each numeric range the CATEGORY SCHEMA declares, the
+ * location, and the host's category control — plus the leading "all filters"
+ * chip. Nothing here knows what a "brand" or a "mileage" is; a deployment with
+ * three facets gets three chips and a deployment with none gets the leading
+ * chip alone.
+ *
+ * ## The ORDER of the row is the whole product
+ *
+ * At 390px a person sees roughly four chips before the fold, and everything
+ * past them costs a horizontal flick most people never make. On a live phone
+ * category the first seven were battery health, four parcel dimensions and two
+ * wholesale counts — every one of them a numeric ATTRIBUTE the category
+ * happens to declare, drawn before the condition, the vendor and the model
+ * anybody actually narrows by, and before the price.
+ *
+ * That is an ORDERING defect, not a facetability one, and it is fixed as one:
+ * nothing is deleted, because this package cannot tell a battery-health axis
+ * from a parcel-width axis and must not pretend to. Two categories declare
+ * `int` attributes and one of them is `mileage`. So the row states its order
+ * instead, out of evidence it actually has:
+ *
+ *   1. **the category chip** — narrowing the category decides which chips
+ *      exist at all, the facet plan being derived from the leaf;
+ *   2. **the location chip** — the other host-slot filter;
+ *   3. **everything APPLIED**, in band order below. A constraint a person has
+ *      set has to be reachable without a flick, or the row states filters that
+ *      are on screen only if you go looking;
+ *   4. then everything unapplied, in band order:
+ *      **core range axes** (`facet_meta.core_ranges` — the SERVER declaring an
+ *      axis that exists for every document in every category: `price`), then
+ *      **counted facet groups** (the server counted them for this search and
+ *      each carries its remaining counts — the strongest evidence the row has
+ *      that these are the axes this corpus is narrowed by), then
+ *      **the category's numeric attributes**, which are form fields the
+ *      composer collects and which no flag in the schema distinguishes from an
+ *      axis a buyer uses.
+ *
+ * Band 3's attributes keep their controls, whole, in the panel behind the
+ * leading circle and at the tail of this row. `buildRangeGroups` is untouched:
+ * a rule that DELETED them would have to answer "on what evidence", and
+ * `facet_meta.skipped` — the one server signal that names a slug — means the
+ * counter ran out of plan slots at `MAX_FACET_FIELDS`, not that a person
+ * cannot filter by it. `r.<slug>` still answers for a skipped slug.
+ *
+ * ## Why the CATEGORY leads the row
+ *
+ * The owner's navigation model puts levels 1-2 of the catalogue on tiles and
+ * every level below them behind a cascading child selector, chosen "as a
+ * characteristic" — on the result list and in the composer alike. On the SERP
+ * that selector is a chip like any other, and it is the FIRST one, because
+ * narrowing the category is what changes which other chips exist at all: the
+ * facet plan is derived from the leaf category, so every chip to its right is
+ * downstream of it.
+ *
+ * The pair does not draw that selector. Walking the tree belongs to
+ * `categories-react`, so the chip is the host's `renderCategoryFilter` in the
+ * same sheet the other chips open, and a row whose host filled no such slot
+ * renders exactly as it did before. There is no synthesized category FACET
+ * anywhere here and there must not be one: the server counts no category
+ * buckets and the index has no read path for them, so any count this row drew
+ * beside a child category would be a number nobody could check.
  */
 import { useState } from "react";
 import type { CSSProperties, ReactElement, ReactNode } from "react";
@@ -55,14 +113,19 @@ import { useT } from "@stapel/core";
 import { radii, spacing } from "@stapel/tokens";
 import type { FeatureDef } from "@stapel/attributes-react";
 import { useFacetPanel } from "../headless/FacetPanel.js";
+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 type { FacetGroup } from "../state/facets.js";
 import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
 import { FacetGroupControl } from "./FacetGroupControl.js";
 import { RangeFilterRow } from "./RangeFilterRow.js";
 import { geoSummaryFallback } from "./FacetPanelPane.js";
-import type { GeoFilterSlotProps } from "./FacetPanelPane.js";
+import type {
+  CategoryFilterSlotProps,
+  GeoFilterSlotProps,
+} from "./FacetPanelPane.js";
 import { CHIP_GEO_TEST_IDS, GeoSheet, useApplyLabel } from "./geoSheet.js";
 
 /** The class the scroller carries, for {@link chipRowCss}. */
@@ -102,11 +165,99 @@ const CHIP: CSSProperties = { flex: "0 0 auto", borderRadius: radii.full };
 /** Which picker is open, if any. `null` closes everything. */
 type OpenChip = string | null;
 
+/**
+ * The three bands the row's non-slot chips fall into, most-evidenced first.
+ *
+ * `core_range` is the SERVER's own declaration (`facet_meta.core_ranges`) that
+ * an axis exists for every document in every category. `facet` is a group the
+ * server COUNTED for this search, which arrives with the remaining counts that
+ * make it a drill-down. `attribute_range` is a numeric field the category
+ * declares and nothing ranks — see this module's ordering note.
+ */
+export type ChipBand = "core_range" | "facet" | "attribute_range";
+
+/** Band order, stated once. */
+export const CHIP_BAND_ORDER: readonly ChipBand[] = [
+  "core_range",
+  "facet",
+  "attribute_range",
+];
+
+/** One non-slot chip, resolved to the band and the applied state it sorts by. */
+export type ChipSpec =
+  | { readonly band: "core_range" | "attribute_range"; readonly range: RangeGroup }
+  | { readonly band: "facet"; readonly facet: FacetGroup };
+
+/** Has the person set this filter? */
+function specApplied(spec: ChipSpec): boolean {
+  return spec.band === "facet" ? spec.facet.selected.length > 0 : spec.range.active;
+}
+
+/**
+ * The row's order: applied first, then band, then the order each source
+ * already came in.
+ *
+ * Exported because the order IS the fix — the defect it closes is invisible to
+ * a test that only asks whether a chip exists, and a rule stated in prose next
+ * to an unexercised implementation is a rule that drifts.
+ *
+ * `Array.prototype.sort` is stable in every runtime this pair supports, so
+ * equal-ranked chips keep the order `buildRangeGroups` and `buildFacetGroups`
+ * gave them — a closed set's authored order survives all the way to the row.
+ */
+export function orderChipFilters(
+  ranges: readonly RangeGroup[],
+  facets: readonly FacetGroup[]
+): readonly ChipSpec[] {
+  const specs: ChipSpec[] = [
+    ...ranges.map(
+      (range): ChipSpec =>
+        range.core
+          ? { band: "core_range", range }
+          : { band: "attribute_range", range }
+    ),
+    ...facets.map((facet): ChipSpec => ({ band: "facet", facet })),
+  ];
+  return [...specs].sort((a, b) => {
+    const applied = Number(specApplied(b)) - Number(specApplied(a));
+    if (applied !== 0) return applied;
+    return CHIP_BAND_ORDER.indexOf(a.band) - CHIP_BAND_ORDER.indexOf(b.band);
+  });
+}
+
 export interface FilterChipsProps {
   /** The category's feature schema — the source of option labels, of which
-   * slugs get a range chip, and of how each group is drawn. */
+   * slugs get a range chip, of which slugs are choosable at all, and of how
+   * each group is drawn. */
   readonly categoryFeatures?: readonly FeatureDef[];
   readonly locale?: string;
+  /**
+   * Name the values neither the answer nor the schema names — see
+   * {@link FacetLabelResolver}. The same prop reaches the filter panel, so a
+   * value cannot read one way on a chip and another way inside the sheet.
+   */
+  readonly resolveFacetLabels?: FacetLabelResolver;
+  /**
+   * The catalogue picker (`categories-react`), same slot the panel takes.
+   *
+   * Filled, it becomes the row's LEADING chip and opens in the same sheet as
+   * every other chip. Unfilled, the row draws no category chip at all — and
+   * that is not a constraint left without a control: the whole panel is one
+   * tap away behind the leading circle, and it carries the "search the whole
+   * catalogue" button for a link that arrived narrowed.
+   */
+  readonly renderCategoryFilter?: (slot: CategoryFilterSlotProps) => ReactNode;
+  /**
+   * What the current category is CALLED, in words.
+   *
+   * The pair holds a `root/leaf` PATH of slugs and nothing that turns one into
+   * a catalogue name — the tree belongs to `categories-react`, and whoever
+   * rendered the picker has the name already. Absent, the chip falls back to
+   * the path's last segment, which is the honest half-answer: it is what the
+   * search is actually narrowed to, it fits a 390px row where the whole path
+   * does not, and it is never invented.
+   */
+  readonly categoryLabel?: ReactNode;
   /** The location control (`geo-react`), same slot the panel takes. Without
    * it the location chip appears only when the URL already carries a point,
    * so a shared link can still be widened. */
@@ -123,6 +274,16 @@ export interface FilterChipsProps {
   /** Open the whole panel — the leading chip's action. The page owns that
    * sheet, because the page is the surface it covers. */
   readonly onOpenAll: () => void;
+  /**
+   * Draw the location chip. Default `true`.
+   *
+   * `false` for a surface that already states the location ABOVE this row —
+   * `<LocationSummaryLine>` is that surface, and the phone SERP mounts both.
+   * Together they printed two location controls one line apart — the summary
+   * sentence over the chip's own prompt — opening two different sheets over
+   * one filter, which is the same constraint asked about twice.
+   */
+  readonly geoChip?: boolean;
 }
 
 /**
@@ -140,24 +301,47 @@ function chipLabel(group: FacetGroup, t: (key: string, p?: Record<string, unknow
     : `${first.label}${t(SEARCH_I18N_KEYS.filtersChipMore, { count: chosen.length - 1 })}`;
 }
 
-export function FilterChips(props: FilterChipsProps): ReactElement {
+/**
+ * The last segment of a `root/leaf` category path.
+ *
+ * A chip has room for one word, and the whole path is what the panel prints on
+ * a surface with a column to spend. This is the pair's LAST resort — a host
+ * that renders the picker knows the catalogue's own name for the node and
+ * passes `categoryLabel` — but it is a real narrowing stated with a value the
+ * URL genuinely carries, which is the line the geo chip draws too: never print
+ * a coordinate, always print the name you actually have.
+ */
+export function categoryLeaf(path: string): string {
+  const parts = path.split("/").filter((part) => part.length > 0);
+  return parts[parts.length - 1] ?? path;
+}
+
+export function FilterChips(props: FilterChipsProps): ReactElement | null {
   const t = useT();
-  const { state } = useSearchState();
+  const { state, setCategory } = useSearchState();
   const bag = useFacetPanel({
     ...(props.categoryFeatures !== undefined
       ? { categoryFeatures: props.categoryFeatures }
       : {}),
     ...(props.locale !== undefined ? { locale: props.locale } : {}),
+    ...(props.resolveFacetLabels !== undefined
+      ? { resolveFacetLabels: props.resolveFacetLabels }
+      : {}),
   });
   const applyLabel = useApplyLabel();
   const surface = useDialogSurface();
   const [open, setOpen] = useState<OpenChip>(null);
 
+  // Same source as the panel's rows, so the phone chip row and the desktop
+  // panel cannot disagree about which axes exist: the core columns come from
+  // the ANSWER (`facet_meta.core_ranges`) and the currency off its cards.
   const ranges = buildRangeGroups({
     state,
     ...(props.categoryFeatures !== undefined
       ? { categoryFeatures: props.categoryFeatures }
       : {}),
+    coreRanges: bag.coreRanges,
+    ...(bag.currency !== undefined ? { currency: bag.currency } : {}),
     t,
   });
   const groups =
@@ -197,8 +381,25 @@ export function FilterChips(props: FilterChipsProps): ReactElement {
     </SkinDialog>
   );
 
+  // The category chip exists only where a host can actually draw the picker:
+  // a chip that opened an empty sheet would be a filter affordance leading
+  // nowhere, and the whole panel behind the leading circle already carries the
+  // control that widens a narrowed link.
+  const showCategoryChip = props.renderCategoryFilter !== undefined;
+  const category = state.category;
+  // Same rule as every other chip: the CHOICE when there is one, the filter's
+  // own name when there is not.
+  const categoryChipLabel: ReactNode =
+    category === undefined
+      ? t(SEARCH_I18N_KEYS.categoryTitle)
+      : (props.categoryLabel ?? categoryLeaf(category));
+
+  const ordered = orderChipFilters(ranges, groups);
+
   const geo = state.geo;
-  const showGeoChip = props.renderGeoFilter !== undefined || geo !== undefined;
+  const showGeoChip =
+    props.geoChip !== false &&
+    (props.renderGeoFilter !== undefined || geo !== undefined);
   // Nothing applied: the chip is the FILTER's name ("Location"), because there
   // is no constraint to describe yet. Applied: the host's name for the place,
   // and failing that the sentence that admits the pair does not know it.
@@ -207,6 +408,21 @@ export function FilterChips(props: FilterChipsProps): ReactElement {
       ? t(SEARCH_I18N_KEYS.geoTitle)
       : (props.geoLabel ?? geoSummaryFallback(geo, t));
 
+  /*
+   * A row of one button is not a chip row.
+   *
+   * The leading circle is the whole-panel door, and it is the only child this
+   * row is guaranteed. On a deployment whose plan has no facets for the
+   * current query — a free-text search with no category is exactly that: the
+   * plan comes from the CATEGORY's feature defs, so `facets` comes back `{}` —
+   * the row rendered as a lone circle floating between the location line and
+   * the results, a third filter affordance next to two working ones. When
+   * there is nothing to state, the row states nothing and the surface above
+   * keeps its own door.
+   */
+  const hasChips = showCategoryChip || showGeoChip || ordered.length > 0;
+  if (!hasChips) return null;
+
   return (
     <>
       <style href={CHIP_ROW_STYLE_HREF} precedence="default">
@@ -238,59 +454,95 @@ export function FilterChips(props: FilterChipsProps): ReactElement {
           {bag.activeFilters > 0 && <ActiveDot />}
         </Button>
 
-        {showGeoChip && (
+        {/* FIRST, before every facet chip: narrowing the category is what
+            decides which facet chips exist at all. */}
+        {showCategoryChip && (
           <Button
             style={CHIP}
             shape="round"
-            type={geo !== undefined ? "primary" : "default"}
-            data-testid="search-chip-geo"
+            type={category !== undefined ? "primary" : "default"}
+            data-testid="search-chip-category"
             data-analytics="none"
             data-analytics-reason="a filter is a read, not a flow step"
             onClick={() => {
-              setOpen("geo");
+              setOpen("category");
             }}
           >
-            {geoChipLabel}
+            {categoryChipLabel}
           </Button>
         )}
 
-        {ranges.map((group) => (
+        {showGeoChip && (
           <Button
-            key={group.slug}
             style={CHIP}
             shape="round"
-            type={group.active ? "primary" : "default"}
-            data-testid={`search-chip-range-${group.slug}`}
+            type={geo !== undefined ? "primary" : "default"}
+            data-testid="search-chip-geo"
             data-analytics="none"
             data-analytics-reason="a filter is a read, not a flow step"
             onClick={() => {
-              setOpen(`range:${group.slug}`);
+              setOpen("geo");
             }}
           >
-            {group.label}
+            {geoChipLabel}
           </Button>
-        ))}
+        )}
 
-        {groups.map((group) => (
-          <Button
-            key={group.slug}
-            style={CHIP}
-            shape="round"
-            type={group.selected.length > 0 ? "primary" : "default"}
-            data-testid={`search-chip-${group.slug}`}
-            data-analytics="none"
-            data-analytics-reason="a filter is a read, not a flow step"
-            onClick={() => {
-              setOpen(`facet:${group.slug}`);
-            }}
-          >
-            {chipLabel(group, t)}
-          </Button>
-        ))}
+        {/* One list, in the row's stated order — see this module's ordering
+            note. Rendering ranges and facets as two separate `.map`s is what
+            put seven parcel dimensions in front of the price. */}
+        {ordered.map((spec) =>
+          spec.band === "facet" ? (
+            <Button
+              key={`facet:${spec.facet.slug}`}
+              style={CHIP}
+              shape="round"
+              type={spec.facet.selected.length > 0 ? "primary" : "default"}
+              data-testid={`search-chip-${spec.facet.slug}`}
+              data-band={spec.band}
+              data-analytics="none"
+              data-analytics-reason="a filter is a read, not a flow step"
+              onClick={() => {
+                setOpen(`facet:${spec.facet.slug}`);
+              }}
+            >
+              {chipLabel(spec.facet, t)}
+            </Button>
+          ) : (
+            <Button
+              key={`range:${spec.range.slug}`}
+              style={CHIP}
+              shape="round"
+              type={spec.range.active ? "primary" : "default"}
+              data-testid={`search-chip-range-${spec.range.slug}`}
+              data-band={spec.band}
+              data-analytics="none"
+              data-analytics-reason="a filter is a read, not a flow step"
+              onClick={() => {
+                setOpen(`range:${spec.range.slug}`);
+              }}
+            >
+              {spec.range.label}
+            </Button>
+          )
+        )}
       </div>
 
       {/* One sheet per chip, rendered only for the open one: a dozen mounted
           dialogs is a dozen focus traps waiting for a stray `open`. */}
+      {open === "category" &&
+        props.renderCategoryFilter !== undefined &&
+        sheetFor(
+          "category",
+          t(SEARCH_I18N_KEYS.categoryTitle),
+          props.renderCategoryFilter({
+            value: category,
+            onChange: (path) => {
+              setCategory(path);
+            },
+          })
+        )}
+
       {open?.startsWith("facet:") === true &&
         (() => {
           const slug = open.slice("facet:".length);

package/src/default/LocationSummaryLine.tsx

@@ -151,6 +151,11 @@ export function LocationSummaryLine(
           )}
         </Button>
 
+        {/* "Filters", not "All filters": this end of the row shares 390px
+            with a place name that can run to fifteen characters, and the word
+            the person is looking for is the noun. The panel's own heading
+            still says "All filters" — there it is naming a sheet, not a
+            door. */}
         {/* The count, not a dot: this row has the width to say how many. */}
         <Badge
           count={activeFilters}
@@ -166,7 +171,7 @@ export function LocationSummaryLine(
             data-analytics-reason="opening the filter sheet is a read, not a flow step"
             onClick={props.onOpenAll}
           >
-            {t(SEARCH_I18N_KEYS.filtersAll)}
+            {t(SEARCH_I18N_KEYS.filtersShort)}
           </Button>
         </Badge>
       </Flex>

package/src/default/RangeFilterRow.tsx

@@ -18,7 +18,7 @@
 import { useRef, useState } from "react";
 import type { ReactElement } from "react";
 import { Button, Flex, InputNumber, Typography } from "antd";
-import { actionAvailable, actionBlocked, useT } from "@stapel/core";
+import { actionAvailable, actionBlocked, useFormat, useT } from "@stapel/core";
 import type { ActionAvailability } from "@stapel/core";
 import { GatedButton } from "@stapel/tokens-antd/skin";
 import { spacing } from "@stapel/tokens";
@@ -40,8 +40,39 @@ function toDraft(value: string | undefined): string {
   return value ?? "";
 }
 
+/**
+ * The suffix a bound field carries: a currency SYMBOL for a money axis, the
+ * category's own unit string otherwise.
+ *
+ * `group.currency` is an ISO 4217 code and `RUB` beside an input is not what
+ * money looks like anywhere; `Intl` knows the symbol per locale, so the code
+ * goes in and «₽» comes out. An unsupported code falls back to the code
+ * itself — still better than nothing, and it never throws inside a render.
+ */
+function boundSuffix(
+  format: ReturnType<typeof useFormat>,
+  group: RangeGroup
+): string | undefined {
+  if (group.currency === undefined) return group.unit;
+  if (!/^[A-Za-z]{3}$/.test(group.currency)) return group.currency;
+  try {
+    const sample = format.number(0, {
+      style: "currency",
+      currency: group.currency.toUpperCase(),
+      currencyDisplay: "narrowSymbol",
+      maximumFractionDigits: 0,
+    });
+    if (sample === null) return group.currency;
+    const symbol = sample.replace(/[\s\u00a0\u202f0-9.,]/g, "");
+    return symbol.length > 0 ? symbol : group.currency;
+  } catch {
+    return group.currency;
+  }
+}
+
 export function RangeFilterRow(props: RangeFilterRowProps): ReactElement {
   const t = useT();
+  const format = useFormat();
   const { group } = props;
   const [from, setFrom] = useState(toDraft(group.from));
   const [to, setTo] = useState(toDraft(group.to));
@@ -71,7 +102,23 @@ export function RangeFilterRow(props: RangeFilterRowProps): ReactElement {
     props.onApply(group.slug, empty ? null : draft);
   };
 
-  const unit = group.unit === undefined ? "" : ` ${group.unit}`;
+  const suffix = boundSuffix(format, group);
+  const unit = suffix === undefined ? "" : ` ${suffix}`;
+  // Thousands grouping inside the field, because a price is read in
+  // thousands: `119000` is a wall of digits and `119 000` is a number. The
+  // parser is digits-only, so whatever the locale's separator turns out to
+  // be, the value that leaves the control is still the one the URL carries.
+  const grouping =
+    group.core
+      ? {
+          formatter: (value: string | number | undefined): string =>
+            value === undefined || value === ""
+              ? ""
+              : (format.number(Number(value)) ?? String(value)),
+          parser: (value: string | undefined): string =>
+            (value ?? "").replace(/[^\d.-]/g, ""),
+        }
+      : {};
 
   return (
     <Flex
@@ -79,8 +126,17 @@ export function RangeFilterRow(props: RangeFilterRowProps): ReactElement {
       gap={spacing[1]}
       data-testid={`facet-range-${group.slug}`}
       data-active={group.active ? "true" : "false"}
+      data-core={group.core ? "true" : "false"}
     >
-      <Typography.Text strong>{group.label}</Typography.Text>
+      {/* The unit lives in the HEADING, not in the fields. It used to live
+          only in an aria-label, so a sighted reader of a money row saw two
+          bare integers and had to infer the currency from the results. antd
+          deprecated `addonAfter` on InputNumber in favour of `Space.Compact`,
+          and two addons plus an Apply button do not survive a 390px row —
+          "Price, RUB" states it once and costs no width. */}
+      <Typography.Text strong data-testid={`facet-range-${group.slug}-label`}>
+        {suffix === undefined ? group.label : `${group.label}, ${suffix}`}
+      </Typography.Text>
       <Flex gap={spacing[2]} align="center" wrap>
         <InputNumber
           value={from === "" ? null : Number(from)}
@@ -90,6 +146,7 @@ export function RangeFilterRow(props: RangeFilterRowProps): ReactElement {
           })}${unit}`}
           data-testid={`facet-range-${group.slug}-from`}
           style={{ minWidth: RANGE_FIELD_MIN_WIDTH }}
+          {...grouping}
           {...(group.min !== undefined ? { min: group.min } : {})}
           {...(group.max !== undefined ? { max: group.max } : {})}
           {...(group.step !== undefined ? { step: group.step } : {})}
@@ -106,6 +163,7 @@ export function RangeFilterRow(props: RangeFilterRowProps): ReactElement {
           })}${unit}`}
           data-testid={`facet-range-${group.slug}-to`}
           style={{ minWidth: RANGE_FIELD_MIN_WIDTH }}
+          {...grouping}
           {...(group.min !== undefined ? { min: group.min } : {})}
           {...(group.max !== undefined ? { max: group.max } : {})}
           {...(group.step !== undefined ? { step: group.step } : {})}