@stapel/search-react 0.4.0 → 0.8.0

package/src/default/FilterChips.tsx

@@ -0,0 +1,415 @@
+/**
+ * `<FilterChips>` — the phone's filter row: one horizontally scrolling line of
+ * chips, each of which opens its OWN picker.
+ *
+ * ## What it replaces, and why the replacement is not cosmetic
+ *
+ * The phone filter path was a single full-width "Filters (3)" button that
+ * opened the whole panel. Everything about a search — the category, the price,
+ * the brand, where — was behind one tap onto a sheet you then had to scroll,
+ * and NOTHING about what was already applied was visible on the results page
+ * itself except a number in brackets. The chips row states the filters ON the
+ * page: the ones you have set read as set, the ones you have not are one tap
+ * from their own small picker, and the whole panel is still there behind the
+ * leading chip for the person who wants all of it at once.
+ *
+ * ## The row scrolls; the PAGE does not
+ *
+ * A row of chips wider than a 390px phone is the point — it is how the row
+ * holds eight filters. What must not happen is the page's own body growing a
+ * horizontal scrollbar, which is what a `flex-wrap: nowrap` row without an
+ * `overflow-x` owner does: the chips push the document wider, every other
+ * element on the page slides, and the visitor is left rubber-banding the whole
+ * screen sideways to read a price. So the row owns its overflow
+ * (`overflow-x: auto`), contains its overscroll so a flick past the last chip
+ * does not start scrolling the page behind it, and hides the scrollbar itself
+ * (a 15px grey trough under a 32px chip is chrome nobody asked for) — through
+ * a hoisted stylesheet, because `::-webkit-scrollbar` and `scrollbar-width`
+ * cannot be written as inline style.
+ *
+ * Hiding a scrollbar is only safe because nothing here is reachable ONLY by
+ * dragging it: every chip is a real `<button>`, so Tab walks the row and the
+ * browser scrolls the focused chip into view on its own.
+ *
+ * ## Every picker is a `SkinDialog`
+ *
+ * Which means every picker is a BOTTOM SHEET on a phone and a modal above it
+ * (owner ruling 2026-08-24, enforced by `stapel/no-bare-dialog`). The chips
+ * row is a phone surface, so in practice it is always the sheet — but the
+ * component does not decide that, the substrate does, and a tablet rendering
+ * the row gets the tablet answer without this file knowing.
+ *
+ * ## 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.
+ */
+import { useState } from "react";
+import type { CSSProperties, ReactElement, ReactNode } from "react";
+import { Button, Flex, Typography } from "antd";
+import { SkinDialog, useDialogSurface } from "@stapel/tokens-antd/skin";
+import { SlotPlaceholder, useT, useTPlural } from "@stapel/core";
+import { radii, spacing } from "@stapel/tokens";
+import type { FeatureDef } from "@stapel/attributes-react";
+import { useFacetPanel } from "../headless/FacetPanel.js";
+import { useAppliedCount } from "../headless/useAppliedCount.js";
+import { useSearchState } from "../headless/SearchStateProvider.js";
+import { buildRangeGroups } 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 type { GeoFilterSlotProps } from "./FacetPanelPane.js";
+
+/** The class the scroller carries, for {@link chipRowCss}. */
+export const CHIP_ROW_CLASS = "stapel-filter-chips";
+
+/** The `href` the hoisted chip-row stylesheet is deduplicated by. */
+export const CHIP_ROW_STYLE_HREF = "stapel-search-filter-chips";
+
+/**
+ * The two rules an inline style cannot express: Firefox's `scrollbar-width`
+ * and WebKit's `::-webkit-scrollbar`. Static (no theme values), so one hoisted
+ * copy serves the document.
+ */
+export function chipRowCss(): string {
+  return [
+    `.${CHIP_ROW_CLASS}{scrollbar-width:none;-ms-overflow-style:none}`,
+    `.${CHIP_ROW_CLASS}::-webkit-scrollbar{display:none}`,
+  ].join("");
+}
+
+/** The scroller: one line, its own overflow, nobody else's. */
+const ROW: CSSProperties = {
+  display: "flex",
+  alignItems: "center",
+  gap: spacing[2],
+  flexWrap: "nowrap",
+  overflowX: "auto",
+  // A flick past the last chip must not hand the gesture to the page.
+  overscrollBehaviorInline: "contain",
+  // Room for the focus ring of the first and last chip, which a flush edge
+  // clips into invisibility.
+  paddingBlock: spacing[1],
+};
+
+const CHIP: CSSProperties = { flex: "0 0 auto", borderRadius: radii.full };
+
+/** Which picker is open, if any. `null` closes everything. */
+type OpenChip = string | null;
+
+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. */
+  readonly categoryFeatures?: readonly FeatureDef[];
+  readonly locale?: string;
+  /** 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. */
+  readonly renderGeoFilter?: (slot: GeoFilterSlotProps) => ReactNode;
+  /** 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;
+}
+
+/**
+ * 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".
+ * A chip that reads "Brand" while filtering to Bosch is a lie the person can
+ * only catch by opening it.
+ */
+function chipLabel(group: FacetGroup, t: (key: string, p?: Record<string, unknown>) => string): string {
+  const chosen = group.options.filter((option) => option.selected);
+  const first = chosen[0];
+  if (first === undefined) return group.label;
+  return chosen.length === 1
+    ? first.label
+    : `${first.label}${t(SEARCH_I18N_KEYS.filtersChipMore, { count: chosen.length - 1 })}`;
+}
+
+export function FilterChips(props: FilterChipsProps): ReactElement {
+  const t = useT();
+  const tPlural = useTPlural();
+  const { state, setGeo } = useSearchState();
+  const bag = useFacetPanel({
+    ...(props.categoryFeatures !== undefined
+      ? { categoryFeatures: props.categoryFeatures }
+      : {}),
+    ...(props.locale !== undefined ? { locale: props.locale } : {}),
+  });
+  const applied = useAppliedCount();
+  const surface = useDialogSurface();
+  const [open, setOpen] = useState<OpenChip>(null);
+
+  const ranges = buildRangeGroups({
+    state,
+    ...(props.categoryFeatures !== undefined
+      ? { categoryFeatures: props.categoryFeatures }
+      : {}),
+    t,
+  });
+  const groups =
+    bag.state.status === "ready"
+      ? bag.state.data.filter((group) => group.options.length > 0)
+      : [];
+
+  // The same sentence the panel's own commit button says, for the same reason:
+  // the results are BEHIND this sheet, so the button that closes it is the
+  // only place a person learns what their choice did.
+  const applyLabel =
+    applied.count === null || applied.kind === "unknown"
+      ? t(SEARCH_I18N_KEYS.filtersApply)
+      : tPlural(
+          applied.kind === "at_least"
+            ? SEARCH_I18N_KEYS.filtersShowCountAtLeast
+            : SEARCH_I18N_KEYS.filtersShowCount,
+          { count: applied.count }
+        );
+
+  const close = (): void => {
+    setOpen(null);
+  };
+
+  const sheetFor = (
+    id: string,
+    title: string,
+    body: ReactNode
+  ): ReactElement => (
+    <SkinDialog
+      open={open === id}
+      onClose={close}
+      title={title}
+      dismissLabel={t(SEARCH_I18N_KEYS.filtersDismiss)}
+      data-testid={`filter-chip-sheet-${id}`}
+      footer={
+        <Button
+          block
+          type="primary"
+          data-testid={`filter-chip-apply-${id}`}
+          data-analytics="none"
+          data-analytics-reason="the filter is already applied; this closes the sheet"
+          onClick={close}
+        >
+          {applyLabel}
+        </Button>
+      }
+    >
+      {body}
+    </SkinDialog>
+  );
+
+  const geo = state.geo;
+  const showGeoChip = props.renderGeoFilter !== undefined || geo !== undefined;
+  const geoLabel =
+    geo === undefined
+      ? t(SEARCH_I18N_KEYS.geoTitle)
+      : geo.kind === "bbox"
+        ? t(SEARCH_I18N_KEYS.geoBox)
+        : t(SEARCH_I18N_KEYS.geoCenter, {
+            lat: geo.lat.toFixed(3),
+            lon: geo.lon.toFixed(3),
+          });
+
+  return (
+    <>
+      <style href={CHIP_ROW_STYLE_HREF} precedence="default">
+        {chipRowCss()}
+      </style>
+      <div
+        className={CHIP_ROW_CLASS}
+        style={ROW}
+        role="group"
+        aria-label={t(SEARCH_I18N_KEYS.filtersChipsLabel)}
+        data-testid="search-filter-chips"
+        data-surface={surface}
+      >
+        {/* The leading chip: the whole panel, in one icon-sized target. It is
+            icon-only because it is the one chip whose meaning does not change
+            — and it carries a DOT, not a count, because the counts are already
+            written on the chips beside it. */}
+        <Button
+          shape="circle"
+          aria-label={t(SEARCH_I18N_KEYS.filtersAll)}
+          icon={<SlidersGlyph />}
+          style={CHIP}
+          data-testid="search-filters-open"
+          data-active={bag.activeFilters > 0 ? "true" : "false"}
+          data-analytics="none"
+          data-analytics-reason="opening the filter sheet is a read, not a flow step"
+          onClick={props.onOpenAll}
+        >
+          {bag.activeFilters > 0 && <ActiveDot />}
+        </Button>
+
+        {showGeoChip && (
+          <Button
+            style={CHIP}
+            shape="round"
+            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("geo");
+            }}
+          >
+            {geoLabel}
+          </Button>
+        )}
+
+        {ranges.map((group) => (
+          <Button
+            key={group.slug}
+            style={CHIP}
+            shape="round"
+            type={group.active ? "primary" : "default"}
+            data-testid={`search-chip-range-${group.slug}`}
+            data-analytics="none"
+            data-analytics-reason="a filter is a read, not a flow step"
+            onClick={() => {
+              setOpen(`range:${group.slug}`);
+            }}
+          >
+            {group.label}
+          </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>
+        ))}
+      </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?.startsWith("facet:") === true &&
+        (() => {
+          const slug = open.slice("facet:".length);
+          const group = groups.find((candidate) => candidate.slug === slug);
+          return group === undefined
+            ? null
+            : sheetFor(
+                open,
+                group.label,
+                <FacetGroupControl
+                  group={group}
+                  onToggle={bag.toggle}
+                  heading={false}
+                  // A sheet devoted to ONE group has the room for all of it;
+                  // "Show all" inside it would be a fold inside a fold.
+                  visibleOptions={null}
+                />
+              );
+        })()}
+
+      {open?.startsWith("range:") === true &&
+        (() => {
+          const slug = open.slice("range:".length);
+          const group = ranges.find((candidate) => candidate.slug === slug);
+          return group === undefined
+            ? null
+            : sheetFor(
+                open,
+                group.label,
+                <RangeFilterRow group={group} onApply={bag.setRange} />
+              );
+        })()}
+
+      {open === "geo" &&
+        sheetFor(
+          "geo",
+          t(SEARCH_I18N_KEYS.geoTitle),
+          <Flex vertical gap={spacing[3]}>
+            {/* SETTING a centre needs a geocoder, which is `geo-react`'s and
+                the deployment's. ADJUSTING or CLEARING one the URL already
+                carries does not — which is why the chip still opens on a
+                shared link with no slot filled, and why the absence of the
+                slot is NAMED in development rather than left as a gap under
+                the sheet's title. */}
+            {props.renderGeoFilter?.({
+              value: geo,
+              onChange: (next) => {
+                setGeo(next);
+              },
+            }) ?? <SlotPlaceholder name="renderGeoFilter" data-testid="search-chip-geo-slot" />}
+            {geo !== undefined && (
+              <>
+                <Typography.Text type="secondary" data-testid="search-chip-geo-summary">
+                  {geoLabel}
+                </Typography.Text>
+                <Button
+                  style={{ alignSelf: "flex-start" }}
+                  data-testid="search-chip-geo-clear"
+                  data-analytics="none"
+                  data-analytics-reason="a filter is a read, not a flow step"
+                  onClick={() => {
+                    setGeo(null);
+                  }}
+                >
+                  {t(SEARCH_I18N_KEYS.geoClear)}
+                </Button>
+              </>
+            )}
+          </Flex>
+        )}
+    </>
+  );
+}
+
+/** 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. */
+function ActiveDot(): ReactElement {
+  return (
+    <span
+      aria-hidden="true"
+      data-testid="search-filters-dot"
+      style={{
+        position: "absolute",
+        insetInlineEnd: spacing[1],
+        insetBlockStart: spacing[1],
+        width: spacing[2],
+        height: spacing[2],
+        borderRadius: radii.full,
+        background: "currentColor",
+      }}
+    />
+  );
+}
+
+/** Sliders — the one glyph a filter control is universally drawn with. Inline
+ * SVG, like every other glyph in the fleet's skins: no icon-font dependency. */
+function SlidersGlyph(): ReactElement {
+  return (
+    <svg
+      width="18"
+      height="18"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.75"
+      strokeLinecap="round"
+      role="img"
+      aria-hidden="true"
+    >
+      <path d="M4 7h10M18 7h2M4 17h4M12 17h8" />
+      <circle cx="16" cy="7" r="2.2" />
+      <circle cx="10" cy="17" r="2.2" />
+    </svg>
+  );
+}

package/src/default/LanguageSelect.tsx

@@ -0,0 +1,93 @@
+/**
+ * The query's LANGUAGE — `lang`, and the reason it is a filter rather than a
+ * display preference.
+ *
+ * `lang` does two things server-side (`query.py`): it picks the ANALYZER (so a
+ * Russian word stems as Russian rather than as an unknown token) and it
+ * NARROWS the corpus to documents indexed in that language. Getting it wrong therefore changes
+ * which results exist, not how they are written — which is why the control
+ * lives in the filter panel beside the facets and not in a settings menu.
+ *
+ * ── Which languages a deployment has is not this pair's fact ───────────────
+ *
+ * The index's languages come from what has been indexed; there is no endpoint
+ * that lists them. So the host names them (`languages`), and the labels come
+ * from `Intl.DisplayNames` in the reader's own locale — each language named
+ * the way THIS reader would name it — rather than from a translation table this
+ * pair would have to carry for every language a deployment might index.
+ *
+ * With no `languages` prop the control renders only when the URL already
+ * carries one, and then only to REMOVE it: a constraint that arrived in a
+ * shared link must always have a control that widens it again.
+ */
+import { useMemo } from "react";
+import type { ReactElement } from "react";
+import { Flex, Select, Typography } from "antd";
+import { useOptionalI18n, useT } from "@stapel/core";
+import { spacing } from "@stapel/tokens";
+import { useSearchState } from "../headless/SearchStateProvider.js";
+import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
+
+/** Width of the language select — a language name plus room for a long one. */
+export const LANGUAGE_SELECT_MIN_WIDTH = 176;
+
+export interface LanguageSelectProps {
+  /** BCP-47 tags the deployment indexes (e.g. `["ru", "en"]`). */
+  readonly languages?: readonly string[];
+}
+
+/**
+ * A language tag as a person reads it, in THEIR locale. Falls back to the tag
+ * itself where the runtime has no name for it — a tag is at least honest,
+ * where a blank option is unclickable.
+ */
+function languageName(tag: string, locale: string): string {
+  try {
+    const names = new Intl.DisplayNames([locale], { type: "language" });
+    return names.of(tag) ?? tag;
+  } catch {
+    return tag;
+  }
+}
+
+export function LanguageSelect(props: LanguageSelectProps): ReactElement | null {
+  const t = useT();
+  // The reader's locale names the languages. Optional on purpose: every other
+  // control in this skin renders outside a provider (English floor) rather
+  // than throwing, and a language list is not the place to break that.
+  const locale = useOptionalI18n()?.locale ?? "en";
+  const { state, setLanguage } = useSearchState();
+  const active = state.lang;
+  const languages = props.languages;
+
+  const options = useMemo(() => {
+    const tags = [...(languages ?? [])];
+    if (active !== undefined && !tags.includes(active)) tags.push(active);
+    return [
+      { value: "", label: t(SEARCH_I18N_KEYS.languageAny) },
+      ...tags.map((tag) => ({ value: tag, label: languageName(tag, locale) })),
+    ];
+  }, [languages, active, locale, t]);
+
+  // Nothing offered and nothing applied: a select with one option ("any") is a
+  // control that cannot do anything, which §83 calls a dead control.
+  if ((languages ?? []).length === 0 && active === undefined) return null;
+
+  return (
+    <Flex gap={spacing[2]} align="center" wrap>
+      <Typography.Text type="secondary" aria-hidden="true">
+        {t(SEARCH_I18N_KEYS.languageLabel)}
+      </Typography.Text>
+      <Select<string>
+        data-testid="search-language"
+        aria-label={t(SEARCH_I18N_KEYS.languageLabel)}
+        style={{ minWidth: LANGUAGE_SELECT_MIN_WIDTH }}
+        value={active ?? ""}
+        onChange={(next) => {
+          setLanguage(next === "" ? null : next);
+        }}
+        options={options}
+      />
+    </Flex>
+  );
+}

package/src/default/PageSizeSelect.tsx

@@ -0,0 +1,80 @@
+/**
+ * How many results a page carries — `limit`, the fifth of the nine state
+ * setters that had no control.
+ *
+ * The offered sizes are the pair's, not the schema's: `docs/schema.json`
+ * declares `limit` as a bare integer, and the backend clamps it to
+ * `1..MAX_PAGE_SIZE` (100) with `DEFAULT_PAGE_SIZE` 24 when it is absent. So
+ * the select offers a short ladder around that default and never sends
+ * something the server would have to clamp — a person who lands on a link
+ * carrying `limit=37` keeps it (it is offered as its own option) rather than
+ * being silently moved to 24, which would change what a shared link shows.
+ *
+ * A page size is a PREFERENCE, not a step through the results: `setLimit`
+ * replaces the history entry rather than pushing one, so Back still undoes the
+ * last filter and not the last time somebody widened the page.
+ */
+import type { ReactElement } from "react";
+import { Flex, Select, Typography } from "antd";
+import { useT } from "@stapel/core";
+import { fontSize, spacing } from "@stapel/tokens";
+import { useSearchState } from "../headless/SearchStateProvider.js";
+import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
+
+/** The shipped ladder, around stapel-search's own `DEFAULT_PAGE_SIZE` (24). */
+export const SEARCH_PAGE_SIZES: readonly number[] = [12, 24, 48, 96];
+
+/** Width of the size select — the widest option plus its caption. */
+export const PAGE_SIZE_SELECT_MIN_WIDTH = 148;
+
+export interface PageSizeSelectProps {
+  /** Override the offered ladder (a deployment with its own `MAX_PAGE_SIZE`). */
+  readonly sizes?: readonly number[];
+  /** What the server uses when the URL names none. Default 24. */
+  readonly defaultSize?: number;
+}
+
+export function PageSizeSelect(props: PageSizeSelectProps): ReactElement {
+  const t = useT();
+  const { state, setLimit } = useSearchState();
+  const ladder = props.sizes ?? SEARCH_PAGE_SIZES;
+  const active = state.limit ?? props.defaultSize ?? 24;
+  const offLadder = !ladder.includes(active);
+  const values = offLadder ? [...ladder, active].sort((a, b) => a - b) : ladder;
+
+  return (
+    <Flex vertical gap={spacing[1]} data-off-ladder={offLadder ? "true" : "false"}>
+      <Flex gap={spacing[2]} align="center">
+        <Typography.Text type="secondary" aria-hidden="true">
+          {t(SEARCH_I18N_KEYS.limitLabel)}
+        </Typography.Text>
+        <Select<number>
+          data-testid="search-limit"
+          aria-label={t(SEARCH_I18N_KEYS.limitLabel)}
+          style={{ minWidth: PAGE_SIZE_SELECT_MIN_WIDTH }}
+          value={active}
+          onChange={(next) => {
+            setLimit(next);
+          }}
+          options={values.map((size) => ({
+            value: size,
+            label: t(SEARCH_I18N_KEYS.limitOption, { count: size }),
+          }))}
+        />
+      </Flex>
+      {/* Keeping a link's own page size is a DECISION, and a decision nobody
+          is told about is indistinguishable from a default. "37 per page" in
+          the box looks like the deployment's ladder until this line says
+          where it came from. */}
+      {offLadder && (
+        <Typography.Text
+          type="secondary"
+          style={{ fontSize: fontSize.xs.fontSize }}
+          data-testid="search-limit-from-link"
+        >
+          {t(SEARCH_I18N_KEYS.limitFromLink)}
+        </Typography.Text>
+      )}
+    </Flex>
+  );
+}