@stapel/search-react 0.3.1 → 0.7.0

package/src/default/SortSelect.tsx

@@ -10,24 +10,29 @@
  *
  * `sort=distance` needs a centre — the server answers
  * `error.400.search_sort_needs_center` without one. The option is therefore
- * DISABLED with the reason named when no geo centre is set, rather than
- * offered and then refused.
+ * DISABLED when no geo centre is set, and the REASON is rendered beside the
+ * control through `GatedControl`, not in a `title=` a phone can never surface.
+ * That is the whole defect this file used to carry: the one sort a person
+ * would most want on a phone was greyed out with its explanation in a hover.
  */
 import type { ReactElement } from "react";
 import { Flex, Select, Typography } from "antd";
-import { useT } from "@stapel/core";
+import { actionAvailable, actionBlocked, useT } from "@stapel/core";
+import type { ActionAvailability } from "@stapel/core";
+import { GatedControl } from "@stapel/tokens-antd/skin";
+import { spacing } from "@stapel/tokens";
 import { SEARCH_SORTS } from "../api/types.js";
 import { useAppliedSort } from "../headless/useAppliedSort.js";
 import { useSearchState } from "../headless/SearchStateProvider.js";
 import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
+import { sortLabelKey } from "./sortLabels.js";
 
-const SORT_LABEL_KEY: Readonly<Record<string, string>> = {
-  relevance: SEARCH_I18N_KEYS.sortRelevance,
-  newest: SEARCH_I18N_KEYS.sortNewest,
-  price_asc: SEARCH_I18N_KEYS.sortPriceAsc,
-  price_desc: SEARCH_I18N_KEYS.sortPriceDesc,
-  distance: SEARCH_I18N_KEYS.sortDistance,
-};
+/**
+ * The select's floor width. Off the spacing scale on purpose and named for it:
+ * it is the width of the longest shipped sort label ("Price: low to high") at
+ * the default type step, so the control does not resize as the choice changes.
+ */
+export const SORT_SELECT_MIN_WIDTH = 200;
 
 export interface SortSelectProps {
   /** The sort the SERVER applied, shown when the URL names none. Omitted, it
@@ -54,33 +59,41 @@ export function SortSelect(props: SortSelectProps): ReactElement {
       ? [...SEARCH_SORTS, active]
       : SEARCH_SORTS;
 
+  // The gate is about ONE option, not the whole control — so the binding's
+  // `aria-describedby` is spread onto the select (a screen reader hears the
+  // reason with the control) and its `disabled` deliberately is not: the other
+  // four sorts work perfectly well without a location.
+  const distance: ActionAvailability = hasCentre
+    ? actionAvailable()
+    : actionBlocked("error.400.search_sort_needs_center");
+
   return (
-    <Flex gap={8} align="center">
-      <Typography.Text type="secondary">
-        {t(SEARCH_I18N_KEYS.sortLabel)}
-      </Typography.Text>
-      <Select<string>
-        data-testid="search-sort"
-        style={{ minWidth: 180 }}
-        value={active ?? null}
-        onChange={(next) => {
-          setSort(next);
-        }}
-        options={values.map((value) => {
-          const key = SORT_LABEL_KEY[value];
-          const needsCentre = value === "distance" && !hasCentre;
-          return {
-            value,
-            label: key !== undefined ? t(key) : value,
-            disabled: needsCentre,
-            // A disabled control states its reason (the ActionAvailability
-            // canon), even inside a select.
-            ...(needsCentre
-              ? { title: t("error.400.search_sort_needs_center") }
-              : {}),
-          };
-        })}
-      />
-    </Flex>
+    <GatedControl gate={distance} testId="search-sort-gate">
+      {(bind) => (
+        <Flex gap={spacing[2]} align="center">
+          <Typography.Text type="secondary" aria-hidden="true">
+            {t(SEARCH_I18N_KEYS.sortLabel)}
+          </Typography.Text>
+          <Select<string>
+            data-testid="search-sort"
+            aria-label={t(SEARCH_I18N_KEYS.sortLabel)}
+            aria-describedby={bind["aria-describedby"]}
+            style={{ minWidth: SORT_SELECT_MIN_WIDTH }}
+            value={active ?? null}
+            onChange={(next) => {
+              setSort(next);
+            }}
+            options={values.map((value) => {
+              const key = sortLabelKey(value);
+              return {
+                value,
+                label: key !== undefined ? t(key) : value,
+                disabled: value === "distance" && !hasCentre,
+              };
+            })}
+          />
+        </Flex>
+      )}
+    </GatedControl>
   );
 }

package/src/default/UrlIssueNotice.tsx

@@ -9,10 +9,28 @@
  */
 import type { ReactElement } from "react";
 import { Alert } from "antd";
+import { spacing } from "@stapel/tokens";
 import { useT } from "@stapel/core";
+import { FILTER_PREFIX, RANGE_PREFIX } from "../state/urlState.js";
 import { useSearchState } from "../headless/SearchStateProvider.js";
 import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
 
+/**
+ * The parameter as a person can recognise it.
+ *
+ * The codec reports the WIRE name, which for a facet or a range carries the
+ * prefix that tells the backend which family it belongs to (`r.price`,
+ * `f.brand`). That prefix is a protocol detail: the sentence is read by
+ * somebody who followed a link, and "price" is the part of `r.price` they
+ * have any chance of recognising.
+ */
+function readableParam(param: string): string {
+  for (const prefix of [RANGE_PREFIX, FILTER_PREFIX]) {
+    if (param.startsWith(prefix)) return param.slice(prefix.length);
+  }
+  return param;
+}
+
 export function UrlIssueNotice(): ReactElement | null {
   const t = useT();
   const { issues } = useSearchState();
@@ -22,12 +40,12 @@ export function UrlIssueNotice(): ReactElement | null {
       type="warning"
       showIcon
       data-testid="search-url-issues"
-      message={t(SEARCH_I18N_KEYS.urlIssuesTitle)}
+      title={t(SEARCH_I18N_KEYS.urlIssuesTitle)}
       description={
-        <ul style={{ margin: 0, paddingInlineStart: 20 }}>
+        <ul style={{ margin: 0, paddingInlineStart: spacing[5] }}>
           {issues.map((issue) => (
             <li key={`${issue.param}:${issue.code}`}>
-              {t(issue.messageKey, { param: issue.param })}
+              {t(issue.messageKey, { param: readableParam(issue.param) })}
             </li>
           ))}
         </ul>

package/src/default/index.ts

@@ -6,48 +6,74 @@
  * never pays for this bundle (enforced by size-limit and the bundle-purity
  * test).
  *
- * Three override levers, none of which requires forking anything:
+ * Five override levers, none of which requires forking anything:
  *
  *  1. **`renderCard`** — the card slot. A storefront passes
  *     `<ListingCard>` from `@stapel/listings-react/default`; the generic card
  *     here is the documented default, not the intended end state (spec §3.7).
  *     `renderResults` is the level above it: the whole layout, for a container
  *     whose arrangement is not "cards in a grid".
- *  2. **`categoryFeatures`** — the facet-label slot. The server sends
- *     `{value: count}` and no labels; the schema that names them lives in
- *     categories, and the container hands it in (spec §6.2 item 2).
- *  3. **retheming through the §68 token JSON** — every surface wraps itself
- *     in `<SearchSkinTheme>`, so a host's regenerated `--stapel-*` custom
+ *  2. **`categoryFeatures`** — the facet-label slot, and the source of which
+ *     slugs get a numeric range row. The server sends `{value: count}` and no
+ *     labels; the schema that names them lives in categories, and the
+ *     container hands it in (spec §6.2 item 2).
+ *  3. **`renderCategoryFilter`** — the catalogue picker. `categories-react`
+ *     owns walking the tree; this pair owns the `category` parameter.
+ *  4. **`renderGeoFilter`** — the location control. `geo-react` owns the map
+ *     and the geocoder; this pair owns `lat`/`lon`/`radius_km`/`bbox`, and
+ *     keeps the controls that WIDEN a location a link already carries.
+ *  5. **retheming through the §68 token JSON** — every surface wraps itself
+ *     in the shared `SkinTheme`, so a host's regenerated `--stapel-*` custom
  *     properties reach this skin with zero code.
+ *
+ * The pair's own `theme.tsx` and `ErrorAlert.tsx` are GONE as of 0.6.0: both
+ * were copies of a decision now stated once in `@stapel/tokens-antd/skin`
+ * (`SkinTheme`, `ErrorAlert`). A host that imported `SearchSkinTheme` imports
+ * `SkinTheme` from the substrate instead — same props, one implementation, and
+ * a runtime `data-theme` flip actually repaints it.
  */
 
 // ── surfaces ────────────────────────────────────────────────────────────────
 export { SearchPage } from "./SearchPage.js";
-export type { SearchPageProps } from "./SearchPage.js";
+export type { SearchPageProps, SearchFiltersLayout } from "./SearchPage.js";
 
-export { SearchResultsPane } from "./SearchResultsPane.js";
+export { SearchResultsPane, RESULTS_MAX_WIDTH } from "./SearchResultsPane.js";
 export type {
   SearchResultsPaneProps,
   SearchResultsRenderer,
 } from "./SearchResultsPane.js";
 
 export { FacetPanelPane } from "./FacetPanelPane.js";
-export type { FacetPanelPaneProps } from "./FacetPanelPane.js";
+export type {
+  FacetPanelPaneProps,
+  CategoryFilterSlotProps,
+  GeoFilterSlotProps,
+} from "./FacetPanelPane.js";
 
-export { RankingDisclosurePane } from "./RankingDisclosurePane.js";
+export { RankingDisclosurePane, RANKING_MAX_WIDTH } from "./RankingDisclosurePane.js";
 export type { RankingDisclosurePaneProps } from "./RankingDisclosurePane.js";
 
+// ── controls, exported so a host can compose its own layout ─────────────────
+export { SearchBox } from "./SearchBox.js";
+export type { SearchBoxProps } from "./SearchBox.js";
+export { SortSelect, SORT_SELECT_MIN_WIDTH } from "./SortSelect.js";
+export type { SortSelectProps } from "./SortSelect.js";
+export { PageSizeSelect, SEARCH_PAGE_SIZES } from "./PageSizeSelect.js";
+export type { PageSizeSelectProps } from "./PageSizeSelect.js";
+export { LanguageSelect } from "./LanguageSelect.js";
+export type { LanguageSelectProps } from "./LanguageSelect.js";
+
 // ── parts, exported so a host can compose or wrap one ───────────────────────
 export { SearchResultCard, GENERIC_CARD_FIELDS } from "./SearchResultCard.js";
 export type { SearchCardProps, SearchCardRenderer } from "./SearchResultCard.js";
 export { DegradationNotice } from "./DegradationNotice.js";
-export type { DegradationNoticeProps } from "./DegradationNotice.js";
+export type {
+  DegradationNoticeProps,
+  DegradationNoticeVariant,
+} from "./DegradationNotice.js";
 export { UrlIssueNotice } from "./UrlIssueNotice.js";
-export { SortSelect } from "./SortSelect.js";
-export type { SortSelectProps } from "./SortSelect.js";
-export { ErrorAlert } from "./ErrorAlert.js";
+export { RangeFilterRow } from "./RangeFilterRow.js";
+export type { RangeFilterRowProps } from "./RangeFilterRow.js";
 
 // ── theming ─────────────────────────────────────────────────────────────────
-export { SearchSkinTheme } from "./theme.js";
-export type { SearchSkinThemeProps } from "./theme.js";
 export type { ThemeModeProp } from "./types.js";

package/src/default/sortLabels.ts

@@ -0,0 +1,34 @@
+/**
+ * A sort SLUG as the skin names it, in one place.
+ *
+ * `relevance`, `price_asc`, `distance` are wire values: the URL carries them,
+ * the envelope reports them, and the ranking disclosure lists them per scorer.
+ * The sort SELECT translated them and the disclosure did not, so the same page
+ * offered "Most relevant" in the control and stamped "Applies to: relevance"
+ * under every parameter — the registry's word, in a statutory text, next to
+ * the human word for the same thing.
+ *
+ * A slug the pair does not ship is returned as it is. Deployments register
+ * their own scorers and sorts, and an unknown one is a real value that belongs
+ * on screen; only an invented label would be worse.
+ */
+import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
+
+const SORT_LABEL_KEY: Readonly<Record<string, string>> = {
+  relevance: SEARCH_I18N_KEYS.sortRelevance,
+  newest: SEARCH_I18N_KEYS.sortNewest,
+  price_asc: SEARCH_I18N_KEYS.sortPriceAsc,
+  price_desc: SEARCH_I18N_KEYS.sortPriceDesc,
+  distance: SEARCH_I18N_KEYS.sortDistance,
+};
+
+/** The i18n key for a shipped sort, or `undefined` for a deployment's own. */
+export function sortLabelKey(sort: string): string | undefined {
+  return SORT_LABEL_KEY[sort];
+}
+
+/** The sort's name for a reader, falling back to the slug. */
+export function sortLabel(t: (key: string) => string, sort: string): string {
+  const key = SORT_LABEL_KEY[sort];
+  return key === undefined ? sort : t(key);
+}

package/src/headless/FacetPanel.tsx

@@ -72,6 +72,34 @@ export function FacetPanel(props: {
   enabled?: boolean;
   children: (bag: FacetPanelBag) => ReactNode;
 }): ReactNode {
+  return props.children(
+    useFacetPanel({
+      ...(props.categoryFeatures !== undefined
+        ? { categoryFeatures: props.categoryFeatures }
+        : {}),
+      ...(props.locale !== undefined ? { locale: props.locale } : {}),
+      ...(props.enabled !== undefined ? { enabled: props.enabled } : {}),
+    })
+  );
+}
+
+/**
+ * The same bag, as a hook — for a caller that has to know what the panel WILL
+ * render before it renders it.
+ *
+ * The one real caller is `<SearchPage>`: a facet column is a quarter of a
+ * catalogue page, and on a deployment whose plan has no facets at all it was
+ * a quarter of every results page spent on an empty-state illustration
+ * repeating "no filters for this search". Whether to lay out that column is a
+ * LAYOUT decision, and layout is decided by the component that owns the grid
+ * — which therefore has to be able to ask. A render prop cannot answer a
+ * question asked one level up.
+ */
+export function useFacetPanel(props: {
+  categoryFeatures?: readonly FeatureDef[];
+  locale?: string;
+  enabled?: boolean;
+} = {}): FacetPanelBag {
   const { state: searchState, setFilter, setRange, clearAll, toggleFilter, activeFilters } =
     useSearchState();
   const t = useT();
@@ -96,7 +124,7 @@ export function FacetPanel(props: {
     })
   );
 
-  return props.children({
+  return {
     state: groups,
     approximate: meta.approximate,
     skipped: meta.skipped,
@@ -109,5 +137,5 @@ export function FacetPanel(props: {
       setFilter(slug, []);
     },
     clearAll,
-  });
+  };
 }

package/src/headless/SearchResults.tsx

@@ -15,15 +15,36 @@ import type {
 } from "../api/types.js";
 import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
 import { useSearchQuery } from "../model/queries.js";
-import { countIsEstimate, parseDegradations } from "../state/degradations.js";
+import {
+  countIsEstimate,
+  countKind,
+  parseDegradations,
+} from "../state/degradations.js";
+import type { SearchCountKind } from "../state/degradations.js";
 import { useSearchState } from "./SearchStateProvider.js";
 
 /** What the envelope says about this page, beside the rows. */
 export interface SearchPageInfo {
-  /** Total matches — an ESTIMATE unless {@link SearchPageInfo.exactTotal}. */
-  readonly count: number;
+  /**
+   * Total matches, or `null` when the engine cannot say — which is a real
+   * state and NOT zero. Read it together with {@link SearchPageInfo.countKind}:
+   * a `count` under `"at_least"` is a floor, not a total.
+   */
+  readonly count: number | null;
   readonly exactTotal: boolean;
-  /** `true` when `count` must be rendered as approximate ("≈", "about"). */
+  /** The server's own word: `count` is a floor ("at least N"), not a total. */
+  readonly countIsLowerBound: boolean;
+  /**
+   * The one value a skin needs to choose a sentence: `"exact"` → "N",
+   * `"at_least"` → "N+", `"unknown"` → no count at all.
+   */
+  readonly countKind: SearchCountKind;
+  /**
+   * `true` when `count` must not be rendered as a plain number.
+   *
+   * @deprecated Equivalent to `countKind !== "exact"` and blind to
+   * `count: null`. Use {@link SearchPageInfo.countKind}.
+   */
   readonly countIsEstimate: boolean;
   readonly hasNext: boolean;
   readonly hasPrev: boolean;
@@ -102,6 +123,13 @@ export function SearchResults(props: {
       : {
           count: data.count,
           exactTotal: data.exact_total,
+          countIsLowerBound: data.count_is_lower_bound === true,
+          countKind: countKind(
+            data.count,
+            data.count_is_lower_bound,
+            data.exact_total,
+            degradations
+          ),
           countIsEstimate: countIsEstimate(data.exact_total, degradations),
           hasNext: data.has_next,
           hasPrev: data.has_prev,

package/src/headless/useAppliedCount.ts

@@ -0,0 +1,41 @@
+/**
+ * How many results the page currently in cache holds, and whether that number
+ * may be spoken as a number.
+ *
+ * The same trick as {@link useAppliedSort}: `enabled: false` on the key
+ * `<SearchResults>` populates, so a control that wants to SAY the count
+ * subscribes to the answer already on screen instead of issuing a second
+ * search of its own. A filter sheet whose button reads "Show 25 results" is
+ * the difference between committing to a change and guessing at one, and it
+ * must not cost a request to know that.
+ *
+ * Not exported from the package entry: it is the shape `<SearchPage>` needs to
+ * label one button, and a public hook would be a second, thinner way to ask
+ * what `<SearchResults>` already answers in full.
+ */
+import { useSearchQuery } from "../model/queries.js";
+import { countKind, parseDegradations } from "../state/degradations.js";
+import type { SearchCountKind } from "../state/degradations.js";
+import { useSearchState } from "./SearchStateProvider.js";
+
+export interface AppliedCount {
+  /** `null` when the engine cannot say — never rendered as `0`. */
+  readonly count: number | null;
+  readonly kind: SearchCountKind;
+}
+
+export function useAppliedCount(): AppliedCount {
+  const { state } = useSearchState();
+  const query = useSearchQuery(state, { enabled: false });
+  const data = query.data;
+  if (data === undefined) return { count: null, kind: "unknown" };
+  return {
+    count: data.count,
+    kind: countKind(
+      data.count,
+      data.count_is_lower_bound,
+      data.exact_total,
+      parseDegradations(data.degraded)
+    ),
+  };
+}

package/src/headless/useScorerNames.ts

@@ -0,0 +1,36 @@
+/**
+ * Scorer SLUGS turned into the names the disclosure already gives them.
+ *
+ * `degraded[]` reports a scorer the engine could not evaluate as
+ * `"scorer:geo_decay"` — a registry identifier, because that is the only
+ * handle the query envelope has. Printed straight into a sentence it reads
+ * "The ranking parameter “geo_decay” was not applied", which is a developer's
+ * word in a shopper's banner (class C-DEVCOPY).
+ *
+ * The name is not this pair's to invent: the backend already publishes one per
+ * scorer on `GET /ranking` (`description_key`, a translation key). So the
+ * lookup goes there — through the SAME cache entry `<RankingDisclosure>`
+ * fills, with `enabled: false`, so a result page never issues a second request
+ * for a label. When the disclosure has not been read the map is empty and the
+ * banner falls back to the slug, which is what it said before and is at least
+ * traceable.
+ */
+import { useT } from "@stapel/core";
+import { useRankingDisclosure } from "../model/queries.js";
+import { useSearchState } from "./SearchStateProvider.js";
+
+/** `(slug) => name`, or `undefined` when nothing in cache names that slug. */
+export type ScorerNameLookup = (slug: string) => string | undefined;
+
+export function useScorerNames(): ScorerNameLookup {
+  const t = useT();
+  const { state } = useSearchState();
+  const query = useRankingDisclosure(state.type, { enabled: false });
+  const scorers = query.data?.scorers;
+  return (slug: string) => {
+    const scorer = scorers?.find((candidate) => candidate.slug === slug);
+    if (scorer === undefined) return undefined;
+    const named = t(scorer.description_key);
+    return named.length > 0 && named !== scorer.description_key ? named : undefined;
+  };
+}

package/src/headless/useSearchBox.ts

@@ -0,0 +1,189 @@
+/**
+ * The query box, headless — the state machine behind `<SearchBox>`.
+ *
+ * ── The one legitimate second copy of the state ────────────────────────────
+ *
+ * This pair's rule is that the URL is the state and no component keeps a copy.
+ * A text input is the single exception the rule has to make: what a person has
+ * TYPED is not yet what they have SEARCHED for, and committing every keystroke
+ * to the URL would make the address bar (and the request, and the query cache)
+ * chase the keyboard. So the draft lives here, for as long as it takes to stop
+ * typing, and the URL is still the only place a SEARCH is recorded.
+ *
+ * Two properties keep that honest:
+ *
+ *  1. **The URL wins whenever it moves on its own.** Back, a shared link
+ *     opening, a host calling `setText` elsewhere — the draft is reset to the
+ *     committed `q`. The box can never show a word the results are not about.
+ *  2. **Committing REPLACES the history entry** (`setText` already does), so a
+ *     ten-letter word is one entry and Back still removes the last FILTER
+ *     rather than the last letter.
+ *
+ * The suggestion list is asked for the DEBOUNCED prefix, not the draft — one
+ * request per pause, not per keystroke, on an endpoint the backend throttles.
+ */
+import { useCallback, useEffect, useRef, useState } from "react";
+import { loadStateFromQuery, mapLoad } from "@stapel/core";
+import type { LoadState } from "@stapel/core";
+import { useSearchState } from "./SearchStateProvider.js";
+import { useSuggest } from "../model/queries.js";
+import {
+  SEARCH_BOX_DEBOUNCE_MS,
+  SEARCH_BOX_SUGGEST_DEBOUNCE_MS,
+  SEARCH_QUERY_MAX_CHARS,
+  SUGGEST_MIN_CHARS,
+} from "../state/limits.js";
+
+/** What a query box needs to read and move the search text. */
+export interface SearchBoxBag {
+  /** What is in the input right now. */
+  readonly draft: string;
+  /** What the URL — and therefore the results — is about. */
+  readonly committed: string;
+  /** The draft has not reached the URL yet (a search is about to run). */
+  readonly pending: boolean;
+  /**
+   * Title prefixes for the typeahead — the READY answer only.
+   *
+   * A typeahead has no surface for "we could not fetch suggestions": the box
+   * must stay typeable and a person is mid-word. So a failed or in-flight
+   * suggest shows nothing, and the three answers stay distinguishable in
+   * {@link SearchBoxBag.suggestState} for a skin that wants to say more.
+   */
+  readonly suggestions: readonly string[];
+  /** The suggest read as a state, unflattened. */
+  readonly suggestState: LoadState<readonly string[]>;
+  /** A suggestion request is in flight for a prefix nothing is shown for yet. */
+  readonly suggestLoading: boolean;
+  /** Characters a prefix needs before the index is asked. */
+  readonly minSuggestChars: number;
+  readonly maxLength: number;
+
+  /** Type. Commits after {@link SEARCH_BOX_DEBOUNCE_MS} of quiet. */
+  setDraft(next: string): void;
+  /** Commit now — Enter, the Search button, or picking a suggestion. */
+  submit(value?: string): void;
+  /** Empty the box AND the search (an empty `q` is a valid browse). */
+  clear(): void;
+}
+
+export interface UseSearchBoxOptions {
+  readonly debounceMs?: number;
+  /** Ask the index for prefixes. Default `true`. */
+  readonly suggest?: boolean;
+  /** Quiet time before the index is asked (default
+   * {@link SEARCH_BOX_SUGGEST_DEBOUNCE_MS}). */
+  readonly suggestDebounceMs?: number;
+  /** How many suggestions to ask for (backend clamps to 25). Default 8. */
+  readonly suggestLimit?: number;
+}
+
+/** One frozen empty list, so a render with no suggestions is a stable value. */
+const NO_SUGGESTIONS: readonly string[] = [];
+
+export function useSearchBox(options: UseSearchBoxOptions = {}): SearchBoxBag {
+  const { state, setText } = useSearchState();
+  const committed = state.q;
+  const debounceMs = options.debounceMs ?? SEARCH_BOX_DEBOUNCE_MS;
+
+  const [draft, setDraftState] = useState(committed);
+  // What the URL said the last time we looked. When it changes underneath us
+  // — Back, a shared link, a host control — the draft follows it; when it
+  // changes BECAUSE we committed, `draft === committed` already and the reset
+  // is a no-op.
+  const lastCommitted = useRef(committed);
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  if (lastCommitted.current !== committed) {
+    lastCommitted.current = committed;
+    if (draft !== committed) setDraftState(committed);
+  }
+
+  const cancel = useCallback((): void => {
+    if (timer.current !== null) {
+      clearTimeout(timer.current);
+      timer.current = null;
+    }
+  }, []);
+
+  // A pending commit must not fire into an unmounted tree, and a box that is
+  // unmounted mid-word has not searched for that word.
+  useEffect(() => cancel, [cancel]);
+
+  const commit = useCallback(
+    (value: string): void => {
+      cancel();
+      if (value !== committed) setText(value);
+    },
+    [cancel, committed, setText]
+  );
+
+  const setDraft = useCallback(
+    (next: string): void => {
+      const clipped = next.slice(0, SEARCH_QUERY_MAX_CHARS);
+      setDraftState(clipped);
+      cancel();
+      timer.current = setTimeout(() => {
+        timer.current = null;
+        if (clipped !== committed) setText(clipped);
+      }, debounceMs);
+    },
+    [cancel, committed, debounceMs, setText]
+  );
+
+  const submit = useCallback(
+    (value?: string): void => {
+      const next = (value ?? draft).slice(0, SEARCH_QUERY_MAX_CHARS);
+      setDraftState(next);
+      commit(next);
+    },
+    [commit, draft]
+  );
+
+  const clear = useCallback((): void => {
+    setDraftState("");
+    commit("");
+  }, [commit]);
+
+  // The index is asked about the SETTLED prefix, never the keystroke: one
+  // request per pause on an endpoint the backend throttles. `useSuggest` then
+  // refuses anything below `SUGGEST_MIN_CHARS` and keys the rest by prefix, so
+  // backspacing to a prefix already asked about costs nothing.
+  const suggestDebounceMs =
+    options.suggestDebounceMs ?? SEARCH_BOX_SUGGEST_DEBOUNCE_MS;
+  const [suggestPrefix, setSuggestPrefix] = useState(committed);
+  useEffect(() => {
+    const handle = setTimeout(() => {
+      setSuggestPrefix(draft);
+    }, suggestDebounceMs);
+    return () => {
+      clearTimeout(handle);
+    };
+  }, [draft, suggestDebounceMs]);
+
+  const suggest = useSuggest({
+    type: state.type,
+    q: suggestPrefix,
+    ...(options.suggestLimit !== undefined ? { limit: options.suggestLimit } : {}),
+    enabled: options.suggest !== false,
+  });
+
+  const suggestState = mapLoad(
+    loadStateFromQuery(suggest),
+    (data) => data.items as readonly string[]
+  );
+
+  return {
+    draft,
+    committed,
+    pending: draft !== committed,
+    suggestions: suggestState.status === "ready" ? suggestState.data : NO_SUGGESTIONS,
+    suggestState,
+    suggestLoading: suggest.isLoading && suggest.fetchStatus === "fetching",
+    minSuggestChars: SUGGEST_MIN_CHARS,
+    maxLength: SEARCH_QUERY_MAX_CHARS,
+    setDraft,
+    submit,
+    clear,
+  };
+}