@stapel/search-react 0.4.0 → 0.8.0

package/src/default/RangeFilterRow.tsx

@@ -0,0 +1,148 @@
+/**
+ * One numeric range row — "Price: from ___ to ___".
+ *
+ * The pair could encode `r.price=100..500`, round-trip it through the URL and
+ * send it, and had no control that produced one. A marketplace without a price
+ * range filter is not a marketplace (audit S-2), and this is the row that fixes
+ * it; `state/ranges.ts` decides which rows exist.
+ *
+ * ── Why it is applied by a button and not by typing ───────────────────────
+ *
+ * A facet checkbox commits on click because a click is a finished thought. A
+ * range is TWO fields, and committing each keystroke would run a search for
+ * `1`, `10`, `100` on the way to `1000` — three wrong result pages, three
+ * history entries' worth of churn, and a facet panel that reshuffles under the
+ * hand still typing. So the row holds a draft and commits on Apply (or Enter),
+ * which is also what makes "from > to" refusable instead of merely empty.
+ */
+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 type { ActionAvailability } from "@stapel/core";
+import { GatedButton } from "@stapel/tokens-antd/skin";
+import { spacing } from "@stapel/tokens";
+import type { SearchRange } from "../api/types.js";
+import type { RangeGroup } from "../state/ranges.js";
+import { isRangeUsable } from "../state/ranges.js";
+import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
+
+/** Floor width of one bound field, so two of them fit a 390px phone row. */
+export const RANGE_FIELD_MIN_WIDTH = 96;
+
+export interface RangeFilterRowProps {
+  readonly group: RangeGroup;
+  /** `null` clears the slug's range entirely. */
+  readonly onApply: (slug: string, range: SearchRange | null) => void;
+}
+
+function toDraft(value: string | undefined): string {
+  return value ?? "";
+}
+
+export function RangeFilterRow(props: RangeFilterRowProps): ReactElement {
+  const t = useT();
+  const { group } = props;
+  const [from, setFrom] = useState(toDraft(group.from));
+  const [to, setTo] = useState(toDraft(group.to));
+  // The URL is still the state: when it moves on its own — Back, a shared
+  // link, "clear all" — the draft follows it rather than keeping a number the
+  // results are no longer about.
+  const applied = useRef<string>(`${toDraft(group.from)}..${toDraft(group.to)}`);
+  const current = `${toDraft(group.from)}..${toDraft(group.to)}`;
+  if (applied.current !== current) {
+    applied.current = current;
+    if (from !== toDraft(group.from)) setFrom(toDraft(group.from));
+    if (to !== toDraft(group.to)) setTo(toDraft(group.to));
+  }
+
+  const draft: SearchRange = {
+    ...(from !== "" ? { from } : {}),
+    ...(to !== "" ? { to } : {}),
+  };
+  const usable = isRangeUsable(draft);
+  const empty = from === "" && to === "";
+  const apply: ActionAvailability = usable
+    ? actionAvailable()
+    : actionBlocked(SEARCH_I18N_KEYS.facetsRangeInvalid);
+
+  const commit = (): void => {
+    if (!usable) return;
+    props.onApply(group.slug, empty ? null : draft);
+  };
+
+  const unit = group.unit === undefined ? "" : ` ${group.unit}`;
+
+  return (
+    <Flex
+      vertical
+      gap={spacing[1]}
+      data-testid={`facet-range-${group.slug}`}
+      data-active={group.active ? "true" : "false"}
+    >
+      <Typography.Text strong>{group.label}</Typography.Text>
+      <Flex gap={spacing[2]} align="center" wrap>
+        <InputNumber
+          value={from === "" ? null : Number(from)}
+          placeholder={t(SEARCH_I18N_KEYS.facetsRangeFrom)}
+          aria-label={`${t(SEARCH_I18N_KEYS.facetsRangeFromAria, {
+            feature: group.label,
+          })}${unit}`}
+          data-testid={`facet-range-${group.slug}-from`}
+          style={{ minWidth: RANGE_FIELD_MIN_WIDTH }}
+          {...(group.min !== undefined ? { min: group.min } : {})}
+          {...(group.max !== undefined ? { max: group.max } : {})}
+          {...(group.step !== undefined ? { step: group.step } : {})}
+          onChange={(value) => {
+            setFrom(value === null || value === undefined ? "" : String(value));
+          }}
+          onPressEnter={commit}
+        />
+        <InputNumber
+          value={to === "" ? null : Number(to)}
+          placeholder={t(SEARCH_I18N_KEYS.facetsRangeTo)}
+          aria-label={`${t(SEARCH_I18N_KEYS.facetsRangeToAria, {
+            feature: group.label,
+          })}${unit}`}
+          data-testid={`facet-range-${group.slug}-to`}
+          style={{ minWidth: RANGE_FIELD_MIN_WIDTH }}
+          {...(group.min !== undefined ? { min: group.min } : {})}
+          {...(group.max !== undefined ? { max: group.max } : {})}
+          {...(group.step !== undefined ? { step: group.step } : {})}
+          onChange={(value) => {
+            setTo(value === null || value === undefined ? "" : String(value));
+          }}
+          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
+            button exists to submit (class C-NOPRIMARY). And no `size="small"`:
+            a filter row that a phone cannot hit is not a filter row, and the
+            shared `SkinTheme` only raises the DEFAULT control height to 44. */}
+        <GatedButton
+          gate={apply}
+          type={usable && !empty ? "primary" : "default"}
+          testId={`facet-range-${group.slug}-apply`}
+          data-analytics="none"
+          data-analytics-reason="a filter is a read, not a flow step"
+          onClick={commit}
+        >
+          {t(SEARCH_I18N_KEYS.facetsRangeApply)}
+        </GatedButton>
+        {group.active && (
+          <Button
+            data-testid={`facet-range-${group.slug}-clear`}
+            data-analytics="none"
+            data-analytics-reason="a filter is a read, not a flow step"
+            onClick={() => {
+              props.onApply(group.slug, null);
+            }}
+          >
+            {t(SEARCH_I18N_KEYS.facetsRangeClear)}
+          </Button>
+        )}
+      </Flex>
+    </Flex>
+  );
+}

package/src/default/RankingDisclosurePane.tsx

@@ -8,13 +8,19 @@
  * shipping.
  */
 import type { ReactElement } from "react";
-import { Empty, Flex, List, Spin, Tag, Typography } from "antd";
-import { matchList, toFlowError, useDescribeFlowError, useT } from "@stapel/core";
+import { Flex, List, Tag, Typography } from "antd";
+import { useFormat, useT } from "@stapel/core";
+import {
+  EmptyState,
+  ErrorAlert,
+  LoadList,
+  SkinTheme,
+} from "@stapel/tokens-antd/skin";
+import { fontSize, spacing } from "@stapel/tokens";
 import type { Scorer } from "../api/types.js";
 import { RankingDisclosure } from "../headless/RankingDisclosure.js";
 import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
-import { ErrorAlert } from "./ErrorAlert.js";
-import { SearchSkinTheme } from "./theme.js";
+import { sortLabel } from "./sortLabels.js";
 import type { ThemeModeProp } from "./types.js";
 
 export interface RankingDisclosurePaneProps extends ThemeModeProp {
@@ -22,17 +28,27 @@ export interface RankingDisclosurePaneProps extends ThemeModeProp {
   readonly type?: string;
 }
 
+/**
+ * The widest a disclosure column may grow. A statutory text is a READING
+ * surface: past this it stops being a paragraph and becomes a banner.
+ */
+export const RANKING_MAX_WIDTH = 720;
+
 export function RankingDisclosurePane(
   props: RankingDisclosurePaneProps
 ): ReactElement {
   const t = useT();
-  const describe = useDescribeFlowError();
+  const format = useFormat();
 
   return (
-    <SearchSkinTheme {...(props.mode !== undefined ? { mode: props.mode } : {})}>
+    <SkinTheme
+      surface="base"
+      {...(props.mode !== undefined ? { mode: props.mode } : {})}
+      style={{ width: "100%", maxWidth: RANKING_MAX_WIDTH }}
+    >
       <RankingDisclosure {...(props.type !== undefined ? { type: props.type } : {})}>
         {(bag) => (
-          <Flex vertical gap={12} data-testid="search-ranking">
+          <Flex vertical gap={spacing[3]} data-testid="search-ranking">
             <Typography.Title level={4} style={{ margin: 0 }}>
               {t(SEARCH_I18N_KEYS.rankingTitle)}
             </Typography.Title>
@@ -40,47 +56,63 @@ export function RankingDisclosurePane(
               {t(SEARCH_I18N_KEYS.rankingIntro)}
             </Typography.Paragraph>
 
-            {matchList(bag.state, {
-              loading: () => (
-                <Flex justify="center" style={{ padding: 16 }}>
-                  <Spin data-testid="ranking-loading" />
-                </Flex>
-              ),
-              failed: (error) => (
+            <LoadList
+              state={bag.state}
+              testId="ranking"
+              skeletonRows={4}
+              onRetry={bag.refetch}
+              empty={
+                <EmptyState
+                  compact
+                  title={t(SEARCH_I18N_KEYS.rankingEmpty)}
+                  testId="ranking-empty"
+                />
+              }
+              failed={(error) => (
                 <ErrorAlert
                   testId="ranking-failed"
-                  error={{
-                    ...describe(toFlowError(error)),
-                    message: t(SEARCH_I18N_KEYS.rankingLoadFailed),
-                  }}
-                />
-              ),
-              empty: () => (
-                <Empty
-                  data-testid="ranking-empty"
-                  description={t(SEARCH_I18N_KEYS.rankingEmpty)}
+                  thrown={error}
+                  message={t(SEARCH_I18N_KEYS.rankingLoadFailed)}
+                  onRetry={bag.refetch}
                 />
-              ),
-              ready: (scorers) => (
+              )}
+            >
+              {(scorers) => (
                 <List<Scorer>
                   data-testid="ranking-list"
                   dataSource={[...scorers]}
                   renderItem={(scorer) => (
                     <List.Item key={scorer.slug} data-scorer={scorer.slug}>
-                      <Flex vertical gap={2} style={{ width: "100%" }}>
-                        <Flex justify="space-between" align="center" gap={8}>
+                      <Flex vertical gap={spacing[1]} style={{ width: "100%" }}>
+                        <Flex justify="space-between" align="center" gap={spacing[2]}>
                           <Typography.Text strong>
                             {t(scorer.description_key)}
                           </Typography.Text>
-                          <Tag>{scorer.weight}</Tag>
+                          {/* A bare "0.3" is a number with no unit in a
+                              statutory text. The tag says what the number IS;
+                              the disclosure's intro already says weights are
+                              relative to each other. */}
+                          <Tag>
+                            {t(SEARCH_I18N_KEYS.rankingWeight)}
+                            {" "}
+                            {format.number(scorer.weight) ?? scorer.weight}
+                          </Tag>
                         </Flex>
                         <Typography.Text type="secondary">
                           {scorer.description}
                         </Typography.Text>
-                        <Typography.Text type="secondary" style={{ fontSize: 12 }}>
+                        <Typography.Text
+                          type="secondary"
+                          style={{ fontSize: fontSize.xs.fontSize }}
+                        >
                           {t(SEARCH_I18N_KEYS.rankingAppliesTo)}
                           {": "}
-                          {scorer.applies_to_sorts.join(", ")}
+                          {/* The sorts a reader can actually choose, by the
+                              names the sort control gives them — not the
+                              registry's slugs. */}
+                          {scorer.applies_to_sorts
+                            .map((sort) => sortLabel(t, sort))
+                            .join(", ")}
                         </Typography.Text>
                         {!scorer.active && (
                           <Typography.Text type="warning" data-testid="ranking-inactive">
@@ -93,11 +125,11 @@ export function RankingDisclosurePane(
                     </List.Item>
                   )}
                 />
-              ),
-            })}
+              )}
+            </LoadList>
 
             {bag.notes.length > 0 && (
-              <Flex vertical gap={2}>
+              <Flex vertical gap={spacing[1]}>
                 <Typography.Text strong>
                   {t(SEARCH_I18N_KEYS.rankingNotes)}
                 </Typography.Text>
@@ -111,6 +143,6 @@ export function RankingDisclosurePane(
           </Flex>
         )}
       </RankingDisclosure>
-    </SearchSkinTheme>
+    </SkinTheme>
   );
 }

package/src/default/SearchBox.tsx

@@ -0,0 +1,130 @@
+/**
+ * `<SearchBox>` — the control this pair shipped a search page without.
+ *
+ * `setText` existed from the first release and had ZERO callers in the whole
+ * repository: the URL codec could carry `q`, the state machine could set it,
+ * the request sent it — and nothing on any screen could type one. A results
+ * page reachable only by editing the address bar is not a search feature, so
+ * this is the blocker of the pair's audit (S-1) and the reason the page is now
+ * a screen rather than a viewer.
+ *
+ * ── What it does, and what it refuses to do ───────────────────────────────
+ *
+ *  - **Types into a draft, searches after a pause.** `useSearchBox` owns the
+ *    debounce and the URL round-trip; this file is the antd shape of it.
+ *  - **Suggests from the INDEX.** `GET /suggest` returns title prefixes out of
+ *    the catalogue — never a query log, because stapel-search keeps none — so
+ *    every suggestion is a search that has results. The endpoint was typed and
+ *    unreachable for three releases (S-8).
+ *  - **Never grows a "no results" dropdown.** With nothing to suggest the menu
+ *    stays shut: an empty popover under a half-typed word says "there is
+ *    nothing" about a search that has not run.
+ *  - **Caps the input at the server's own limit** (200 chars), so
+ *    `error.400.search_query_too_long` is a refusal this control cannot cause.
+ *
+ * Exported from `/default` so a container can mount it in the header —
+ * `nav/manifest.ts` calls `/s` "a navigation TARGET reached from the header's
+ * search box", and this is that box. It needs the same `<SearchStateProvider>`
+ * as everything else; a header outside one renders `<SearchPage>`'s copy.
+ */
+import { useState } from "react";
+import type { ReactElement } from "react";
+import { AutoComplete, Button, Flex, Input } from "antd";
+import { useT } from "@stapel/core";
+import { SkinTheme } from "@stapel/tokens-antd/skin";
+import { spacing } from "@stapel/tokens";
+import { useSearchBox } from "../headless/useSearchBox.js";
+import type { UseSearchBoxOptions } from "../headless/useSearchBox.js";
+import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
+import type { ThemeModeProp } from "./types.js";
+
+export interface SearchBoxProps extends ThemeModeProp, UseSearchBoxOptions {
+  /** Override the placeholder — a category page says what it searches. */
+  readonly placeholder?: string;
+  /** Render the submit button beside the field. Default `true`: on a phone
+   * keyboard "search" is not always offered, and a visible button is. */
+  readonly submitButton?: boolean;
+  readonly autoFocus?: boolean;
+}
+
+export function SearchBox(props: SearchBoxProps): ReactElement {
+  const t = useT();
+  const {
+    mode,
+    placeholder,
+    submitButton,
+    autoFocus,
+    ...boxOptions
+  } = props;
+  const box = useSearchBox(boxOptions);
+  const [open, setOpen] = useState(false);
+
+  const options = box.suggestions.map((value) => ({ value }));
+
+  return (
+    <SkinTheme
+      surface="bare"
+      {...(mode !== undefined ? { mode } : {})}
+      data-testid="search-box"
+    >
+      <Flex gap={spacing[2]} align="center" wrap={false}>
+        <AutoComplete
+          value={box.draft}
+          options={options}
+          // Shut whenever there is nothing to say — see the header. The
+          // open state is the skin's, not antd's: the prop that reports the
+          // menu opening was renamed between antd 5 and 6 and this package
+          // supports both, so nothing here asks antd when to open.
+          open={open && options.length > 0}
+          style={{ flex: 1, minWidth: 0 }}
+          onSelect={(value: string) => {
+            setOpen(false);
+            box.submit(value);
+          }}
+          onChange={(value: string) => {
+            setOpen(true);
+            box.setDraft(value);
+          }}
+        >
+          <Input
+            allowClear={{
+              clearIcon: (
+                <span aria-label={t(SEARCH_I18N_KEYS.boxClear)} role="img">
+                  {"×"}
+                </span>
+              ),
+            }}
+            autoFocus={autoFocus === true}
+            maxLength={box.maxLength}
+            aria-label={t(SEARCH_I18N_KEYS.boxLabel)}
+            placeholder={placeholder ?? t(SEARCH_I18N_KEYS.boxPlaceholder)}
+            data-testid="search-box-input"
+            data-analytics="none"
+            data-analytics-reason="typing a query is a read, not a flow step"
+            onPressEnter={() => {
+              setOpen(false);
+              box.submit();
+            }}
+            onBlur={() => {
+              setOpen(false);
+            }}
+          />
+        </AutoComplete>
+        {submitButton !== false && (
+          <Button
+            type="primary"
+            data-testid="search-box-submit"
+            data-analytics="none"
+            data-analytics-reason="running a search is a read, not a flow step"
+            onClick={() => {
+              setOpen(false);
+              box.submit();
+            }}
+          >
+            {t(SEARCH_I18N_KEYS.boxSubmit)}
+          </Button>
+        )}
+      </Flex>
+    </SkinTheme>
+  );
+}