@stapel/search-react 0.11.0 → 0.12.0

package/src/default/SearchBox.tsx

@@ -16,6 +16,16 @@
  *    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).
+ *  - **Reaches the CATALOGUE, not only the titles.** stapel-search 0.7.0
+ *    answers with CATEGORIES too, and they render as their own group above the
+ *    terms: on a live classified deployment, typing a word that names a
+ *    section answered listing titles and nothing else, so the search field
+ *    could not reach a category at all. Each row prints the ancestor path
+ *    (three catalogues have a "Shorts"; only the path tells them apart) and
+ *    the live listing count, and follows the server's own `category` string.
+ *    See
+ *    `useSearchBox` for why the group is absent rather than empty when the
+ *    server says it had no provider.
  *  - **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.
@@ -28,16 +38,43 @@
  * 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 type { ReactElement, ReactNode } from "react";
+import { AutoComplete, Button, Flex, Input, Typography } from "antd";
+import { useT, useTPlural } 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 type { SuggestCategory } from "../api/types.js";
 import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
 import type { ThemeModeProp } from "./types.js";
 
+/**
+ * The separator between the ancestor names of a category row.
+ *
+ * The same one the vocabulary and hierarchical formatters use fleet-wide, so a
+ * path reads identically in the box, on a card and in the composer.
+ */
+const PATH_SEPARATOR = " / ";
+
+/** Marks a menu row as a DESTINATION rather than a search term.
+ *
+ * The kind travels on the option OBJECT and never inside its `value`: a
+ * category's `category` string and a title prefix are both strings, and
+ * telling them apart by sniffing the text is how a term that happens to look
+ * like a path silently navigates somewhere. */
+interface BoxOption {
+  readonly value: string;
+  readonly label?: ReactNode;
+  readonly stapelCategory?: SuggestCategory;
+}
+
+/** A labelled group of rows — antd renders the label as a group heading. */
+interface BoxOptionGroup {
+  readonly label: ReactNode;
+  readonly options: BoxOption[];
+}
+
 export interface SearchBoxProps extends ThemeModeProp, UseSearchBoxOptions {
   /** Override the placeholder — a category page says what it searches. */
   readonly placeholder?: string;
@@ -47,6 +84,33 @@ export interface SearchBoxProps extends ThemeModeProp, UseSearchBoxOptions {
   readonly autoFocus?: boolean;
 }
 
+/** One destination row: the ancestor path, and how many live listings are
+ * behind it. */
+function CategoryRow(props: {
+  readonly category: SuggestCategory;
+  readonly showCount: boolean;
+}): ReactElement {
+  const tPlural = useTPlural();
+  const { category } = props;
+  return (
+    <Flex
+      justify="space-between"
+      align="center"
+      gap={spacing[2]}
+      data-testid={`search-box-category-${category.category}`}
+    >
+      {/* The whole path, not the leaf: three catalogues have a "Shorts", and
+          the path is the only thing that says which one this is. */}
+      <span>{category.path.join(PATH_SEPARATOR)}</span>
+      {props.showCount && (
+        <Typography.Text type="secondary">
+          {tPlural(SEARCH_I18N_KEYS.boxCategoryCount, { count: category.count })}
+        </Typography.Text>
+      )}
+    </Flex>
+  );
+}
+
 export function SearchBox(props: SearchBoxProps): ReactElement {
   const t = useT();
   const {
@@ -59,7 +123,62 @@ export function SearchBox(props: SearchBoxProps): ReactElement {
   const box = useSearchBox(boxOptions);
   const [open, setOpen] = useState(false);
 
-  const options = box.suggestions.map((value) => ({ value }));
+  const categoryOptions: BoxOption[] = box.categories.map(
+    (category) => ({
+      // The server's own string, verbatim — it is unique per row and it is
+      // exactly what the SERP's `category` parameter takes.
+      value: category.category,
+      label: (
+        <CategoryRow
+          category={category}
+          showCount={!box.categoryCountsUnknown}
+        />
+      ),
+      stapelCategory: category,
+    })
+  );
+  const termOptions: BoxOption[] = box.suggestions.map((value) => ({ value }));
+
+  /*
+   * Destinations FIRST, then terms.
+   *
+   * A classified's box is a navigation control before it is a text filter:
+   * the person who typed a section's name wants the section, and the titles
+   * that happen to contain the word are the fallback, not the answer. The
+   * server ranks the destinations by live listing count and this list keeps
+   * that order.
+   *
+   * The group is absent — not empty — when the server had no category
+   * provider, which falls out of `box.categories` being empty: a heading over
+   * nothing would be the box claiming the catalogue has no such section, a
+   * claim the answer never made. See `useSearchBox`.
+   */
+  const options: (BoxOption | BoxOptionGroup)[] =
+    categoryOptions.length > 0
+      ? [
+          {
+            label: (
+              <span data-testid="search-box-categories-heading">
+                {t(SEARCH_I18N_KEYS.boxCategories)}
+              </span>
+            ),
+            options: categoryOptions,
+          },
+          ...(termOptions.length > 0
+            ? [
+                {
+                  label: (
+                    <span data-testid="search-box-terms-heading">
+                      {t(SEARCH_I18N_KEYS.boxSuggestions)}
+                    </span>
+                  ),
+                  options: termOptions,
+                },
+              ]
+            : []),
+        ]
+      : termOptions;
+  const hasOptions = categoryOptions.length > 0 || termOptions.length > 0;
 
   return (
     <SkinTheme
@@ -75,10 +194,19 @@ export function SearchBox(props: SearchBoxProps): ReactElement {
           // 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}
+          open={open && hasOptions}
           style={{ flex: 1, minWidth: 0 }}
-          onSelect={(value: string) => {
+          onSelect={(value: string, option: BoxOption | BoxOptionGroup) => {
             setOpen(false);
+            // A destination navigates; a term searches. The kind is read off
+            // the option OBJECT, never sniffed out of the text — see
+            // `BoxOption`.
+            const category =
+              "stapelCategory" in option ? option.stapelCategory : undefined;
+            if (category !== undefined) {
+              box.chooseCategory(category);
+              return;
+            }
             box.submit(value);
           }}
           onChange={(value: string) => {

package/src/default/SearchPage.tsx

@@ -71,6 +71,7 @@ import type { FeatureDef } from "@stapel/attributes-react";
 import { SearchStateProvider, useSearchState } from "../headless/SearchStateProvider.js";
 import type { SearchParamsAdapter } from "../headless/SearchStateProvider.js";
 import { useFacetPanel } from "../headless/FacetPanel.js";
+import type { FacetLabelResolver } from "../headless/useFacetLabels.js";
 import { useAppliedCount } from "../headless/useAppliedCount.js";
 import type { ParseSearchStateOptions } from "../state/urlState.js";
 import type { SearchGeo } from "../api/types.js";
@@ -147,13 +148,40 @@ export interface SearchPageProps extends ThemeModeProp, ParseSearchStateOptions
   readonly renderCard?: SearchCardRenderer;
   readonly categoryFeatures?: readonly FeatureDef[];
   readonly locale?: string;
+  /**
+   * Name the facet values neither the answer nor the category schema names —
+   * see {@link FacetLabelResolver}.
+   *
+   * Set once here and it reaches BOTH filter surfaces, the desktop panel and
+   * the phone chip row, the same way `geoLabel` does. It is the seam a
+   * `ref_select` facet needs: its config carries a pointer to a vocabulary and
+   * no option table, the vocabulary is a service this pair does not talk to,
+   * and a server older than stapel-search 0.4.0 sends no `facet_labels` to
+   * cover for it — so without this the chips print `apple` and `128-gb`.
+   */
+  readonly resolveFacetLabels?: FacetLabelResolver;
   /** Render the query box at the top. `false` for a container whose HEADER
    * already mounts `<SearchBox>` — one box per screen, not two. */
   readonly searchBox?: boolean;
   /** BCP-47 tags this deployment indexes, for the language filter. */
   readonly languages?: readonly string[];
-  /** The catalogue picker slot — see {@link FacetPanelPaneProps}. */
+  /**
+   * The catalogue picker slot — see {@link FacetPanelPaneProps}.
+   *
+   * It reaches TWO surfaces: the filter panel's category row, and — on the
+   * phone — the LEADING chip of the filter row, which opens the same control
+   * in the same kind of sheet as every other chip. The owner's navigation
+   * model chooses levels 1-2 from tiles and everything deeper as a
+   * characteristic, and on a result list that is what a chip is.
+   */
   readonly renderCategoryFilter?: (slot: CategoryFilterSlotProps) => ReactNode;
+  /**
+   * What the current category is CALLED — the chip's own text. The pair holds
+   * a path of slugs and no way to turn one into a catalogue name; absent, the
+   * chip states the path's last segment. See
+   * {@link FilterChipsProps.categoryLabel}.
+   */
+  readonly categoryLabel?: ReactNode;
   /** The location control slot (`geo-react`). */
   readonly renderGeoFilter?: (slot: GeoFilterSlotProps) => ReactNode;
   /**
@@ -273,9 +301,11 @@ interface SearchPageBodyProps {
   readonly renderCard?: SearchCardRenderer;
   readonly categoryFeatures?: readonly FeatureDef[];
   readonly locale?: string;
+  readonly resolveFacetLabels?: FacetLabelResolver;
   readonly searchBox?: boolean;
   readonly languages?: readonly string[];
   readonly renderCategoryFilter?: (slot: CategoryFilterSlotProps) => ReactNode;
+  readonly categoryLabel?: ReactNode;
   readonly renderGeoFilter?: (slot: GeoFilterSlotProps) => ReactNode;
   readonly geoLabel?: ReactNode;
   readonly footer?: ReactNode;
@@ -301,11 +331,12 @@ interface SearchPageBodyProps {
 function SearchPageBody(props: SearchPageBodyProps): ReactElement {
   const t = useT();
   const tPlural = useTPlural();
-  const { categoryFeatures, locale, filtersHeader } = props;
+  const { categoryFeatures, locale, resolveFacetLabels, filtersHeader } = props;
   const { state } = useSearchState();
   const facets = useFacetPanel({
     ...(categoryFeatures !== undefined ? { categoryFeatures } : {}),
     ...(locale !== undefined ? { locale } : {}),
+    ...(resolveFacetLabels !== undefined ? { resolveFacetLabels } : {}),
   });
   const applied = useAppliedCount();
   const surface = useDialogSurface();
@@ -379,6 +410,7 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
           {...(layout === "sheet" ? { heading: null } : {})}
           {...(categoryFeatures !== undefined ? { categoryFeatures } : {})}
           {...(locale !== undefined ? { locale } : {})}
+          {...(resolveFacetLabels !== undefined ? { resolveFacetLabels } : {})}
           {...(props.languages !== undefined ? { languages: props.languages } : {})}
           {...(props.renderCategoryFilter !== undefined
             ? { renderCategoryFilter: props.renderCategoryFilter }
@@ -392,9 +424,32 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
     </Flex>
   );
 
-  // The toolbar over the results: how they are ARRANGED, how they are ORDERED,
-  // how many per page — and the surface's own action at the trailing end.
-  const toolbar = (
+  /*
+   * The toolbar over the results: how they are ARRANGED, how they are ORDERED,
+   * how many per page — and the surface's own action at the trailing end.
+   *
+   * TWO shapes, because at 390px the desktop shape is not a smaller version of
+   * itself, it is four stacked rows. The phone form is the reference's own
+   * sort row: the ordering at one end, the surface's action at the other, one
+   * line, nothing else. `pageSize` is already the surface's call; the view
+   * switch draws nothing for a single view and stays in the row for the
+   * surfaces that offer two.
+   */
+  const phoneToolbar = layout === "sheet";
+  const toolbar = phoneToolbar ? (
+    <Flex
+      align="center"
+      justify="space-between"
+      gap={spacing[2]}
+      style={{ width: "100%" }}
+    >
+      <Flex align="center" gap={spacing[2]} style={{ minWidth: 0 }}>
+        <ViewSwitch views={views} value={view.id} onChange={changeView} />
+        <SortSelect compact />
+      </Flex>
+      {props.resultsAction}
+    </Flex>
+  ) : (
     <Flex align="center" wrap gap={spacing[3]}>
       <ViewSwitch views={views} value={view.id} onChange={changeView} />
       <SortSelect />
@@ -406,6 +461,7 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
   const results = (
     <SearchResultsPane
       toolbar={toolbar}
+      {...(phoneToolbar ? { header: "compact" as const } : {})}
       headingLevel={props.resultsHeadingLevel ?? 1}
       {...(view.render !== undefined ? { renderResults: view.render } : {})}
       {...(view.layout !== undefined ? { layout: view.layout } : {})}
@@ -456,10 +512,24 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
             }}
             {...(categoryFeatures !== undefined ? { categoryFeatures } : {})}
             {...(locale !== undefined ? { locale } : {})}
+            {...(resolveFacetLabels !== undefined ? { resolveFacetLabels } : {})}
+            /* The catalogue picker becomes the row's leading chip. The panel
+               behind the circle keeps its own copy of the control; both write
+               the same `category` parameter, so they cannot disagree. */
+            {...(props.renderCategoryFilter !== undefined
+              ? { renderCategoryFilter: props.renderCategoryFilter }
+              : {})}
+            {...(props.categoryLabel !== undefined
+              ? { categoryLabel: props.categoryLabel }
+              : {})}
             {...(props.renderGeoFilter !== undefined
               ? { renderGeoFilter: props.renderGeoFilter }
               : {})}
             {...(props.geoLabel !== undefined ? { geoLabel: props.geoLabel } : {})}
+            /* The row above already states the location and opens its own
+               sheet, so the chip would be the second control over one filter
+               — see `FilterChipsProps.geoChip`. */
+            {...(props.resultsHeader !== undefined ? { geoChip: false } : {})}
           />
           <SkinDialog
             open={sheetOpen}
@@ -512,9 +582,11 @@ export function SearchPage(props: SearchPageProps): ReactElement {
     renderCard,
     categoryFeatures,
     locale,
+    resolveFacetLabels,
     searchBox,
     languages,
     renderCategoryFilter,
+    categoryLabel,
     renderGeoFilter,
     geoLabel,
     defaultGeo,
@@ -543,9 +615,11 @@ export function SearchPage(props: SearchPageProps): ReactElement {
           {...(renderCard !== undefined ? { renderCard } : {})}
           {...(categoryFeatures !== undefined ? { categoryFeatures } : {})}
           {...(locale !== undefined ? { locale } : {})}
+          {...(resolveFacetLabels !== undefined ? { resolveFacetLabels } : {})}
           {...(searchBox !== undefined ? { searchBox } : {})}
           {...(languages !== undefined ? { languages } : {})}
           {...(renderCategoryFilter !== undefined ? { renderCategoryFilter } : {})}
+          {...(categoryLabel !== undefined ? { categoryLabel } : {})}
           {...(renderGeoFilter !== undefined ? { renderGeoFilter } : {})}
           {...(geoLabel !== undefined ? { geoLabel } : {})}
           {...(footer !== undefined ? { footer } : {})}

package/src/default/SearchResultsPane.tsx

@@ -33,6 +33,7 @@ import {
   GatedButton,
   LoadList,
   SkinTheme,
+  visuallyHidden,
 } from "@stapel/tokens-antd/skin";
 import { spacing } from "@stapel/tokens";
 import type { SearchItem } from "../api/types.js";
@@ -168,6 +169,28 @@ export interface SearchResultsPaneProps extends ThemeModeProp {
    * heading list is for.
    */
   readonly headingLevel?: 1 | 2 | 3 | 4 | 5;
+  /**
+   * How the row above the results is arranged. Default `"banner"`.
+   *
+   * `"banner"` — the heading on the left, the count and the toolbar on the
+   * right of one line. A desktop results page, where that line is wide enough
+   * to hold all three.
+   *
+   * `"compact"` — the phone form, and it is a different SHAPE rather than the
+   * same shape at a smaller size. At 390px the banner's one line wraps to
+   * four: a display-size "Results", the count under it, the sort control under
+   * that, and the surface's action under that — a whole viewport of chrome
+   * above the first card, which is what a live phone SERP printed. Compact
+   * gives the toolbar its own row (the surface arranges it: sort at one end,
+   * its action at the other) and puts the COUNT immediately above the cards,
+   * where it is a caption for the list rather than a fourth heading.
+   *
+   * The heading does not disappear — a results screen whose only heading is
+   * gone has a document outline that starts at the footer. It becomes
+   * visually hidden, so a screen reader's heading list is unchanged and the
+   * viewport is not spent saying "Results" over a list of results.
+   */
+  readonly header?: "banner" | "compact";
 }
 
 function Count(props: { bag: SearchResultsBag }): ReactElement | null {
@@ -248,19 +271,33 @@ export function SearchResultsPane(props: SearchResultsPaneProps): ReactElement {
       <SearchResults {...(props.enabled !== undefined ? { enabled: props.enabled } : {})}>
         {(bag) => (
           <Flex vertical gap={spacing[4]}>
-            <Flex justify="space-between" align="center" wrap gap={spacing[2]}>
-              <Typography.Title
-                level={props.headingLevel ?? 4}
-                style={{ margin: 0 }}
-                data-testid="search-results-heading"
-              >
-                {props.heading ?? t(SEARCH_I18N_KEYS.resultsTitle)}
-              </Typography.Title>
-              <Flex align="center" wrap gap={spacing[3]}>
-                <Count bag={bag} />
+            {props.header === "compact" ? (
+              <Flex vertical gap={spacing[2]} data-testid="search-results-header-compact">
+                <Typography.Title
+                  level={props.headingLevel ?? 4}
+                  style={visuallyHidden}
+                  data-testid="search-results-heading"
+                >
+                  {props.heading ?? t(SEARCH_I18N_KEYS.resultsTitle)}
+                </Typography.Title>
                 {props.toolbar}
+                <Count bag={bag} />
+              </Flex>
+            ) : (
+              <Flex justify="space-between" align="center" wrap gap={spacing[2]}>
+                <Typography.Title
+                  level={props.headingLevel ?? 4}
+                  style={{ margin: 0 }}
+                  data-testid="search-results-heading"
+                >
+                  {props.heading ?? t(SEARCH_I18N_KEYS.resultsTitle)}
+                </Typography.Title>
+                <Flex align="center" wrap gap={spacing[3]}>
+                  <Count bag={bag} />
+                  {props.toolbar}
+                </Flex>
               </Flex>
-            </Flex>
+            )}
 
             <DegradationNotice
               degradations={bag.degradations}

package/src/default/SortSelect.tsx

@@ -34,10 +34,37 @@ import { sortLabelKey } from "./sortLabels.js";
  */
 export const SORT_SELECT_MIN_WIDTH = 200;
 
+/** Why `sort=distance` is refused without a centre — the server's own code, so
+ * the control and the 400 it would have earned say the same sentence. */
+const SORT_DISTANCE_BLOCKED = "error.400.search_sort_needs_center";
+
 export interface SortSelectProps {
   /** The sort the SERVER applied, shown when the URL names none. Omitted, it
    * is read from the page already in cache — see {@link useAppliedSort}. */
   readonly appliedSort?: string | undefined;
+  /**
+   * The one-line form, for a phone toolbar. Default `false`.
+   *
+   * Three things change, and the third is the interesting one:
+   *
+   *  - the "Sort" caption goes (the select already shows a sort by name; the
+   *    accessible name keeps the word);
+   *  - the {@link SORT_SELECT_MIN_WIDTH} floor goes, so the control shares one
+   *    row with whatever the surface puts beside it instead of pushing it to
+   *    the next line;
+   *  - the blocked option's REASON moves from a line under the control into
+   *    the option's own label.
+   *
+   * That last move is not the reason being dropped. This file exists because
+   * the reason used to live in a `title=` a phone can never surface, and a
+   * phone is exactly where "sort by distance" is greyed out most often. On a
+   * 390px toolbar the reason as a separate row costs a whole band of the
+   * viewport above the first result — so it goes where the person actually
+   * meets the refusal: on the disabled row of the open list, which a screen
+   * reader reads out with the option and a thumb reads at the moment of the
+   * tap. Nothing is hidden; it is closer to the thing it explains.
+   */
+  readonly compact?: boolean;
 }
 
 export function SortSelect(props: SortSelectProps): ReactElement {
@@ -65,7 +92,48 @@ export function SortSelect(props: SortSelectProps): ReactElement {
   // four sorts work perfectly well without a location.
   const distance: ActionAvailability = hasCentre
     ? actionAvailable()
-    : actionBlocked("error.400.search_sort_needs_center");
+    : actionBlocked(SORT_DISTANCE_BLOCKED);
+
+  const optionsFor = (describedBy?: string): {
+    readonly value: string;
+    readonly label: string;
+    readonly disabled: boolean;
+  }[] =>
+    values.map((value) => {
+      const key = sortLabelKey(value);
+      const label = key !== undefined ? t(key) : value;
+      const blocked = value === "distance" && !hasCentre;
+      return {
+        value,
+        // In the compact form the option carries its own reason — see
+        // `SortSelectProps.compact`. Elsewhere `GatedControl` renders it once,
+        // beside the control, and repeating it here would say it twice.
+        label:
+          blocked && props.compact === true && describedBy === undefined
+            ? `${label} — ${t(SORT_DISTANCE_BLOCKED)}`
+            : label,
+        disabled: blocked,
+      };
+    });
+
+  if (props.compact === true) {
+    return (
+      <Select<string>
+        data-testid="search-sort"
+        data-stapel-gated={hasCentre ? "available" : "blocked"}
+        aria-label={t(SEARCH_I18N_KEYS.sortLabel)}
+        // `minWidth: 0` and not the floor: a control that refuses to be
+        // narrower than 200px is a control that wraps a two-item toolbar onto
+        // two rows at 390px.
+        style={{ minWidth: 0, flex: "0 1 auto" }}
+        value={active ?? null}
+        onChange={(next) => {
+          setSort(next);
+        }}
+        options={optionsFor()}
+      />
+    );
+  }
 
   return (
     <GatedControl gate={distance} testId="search-sort-gate">
@@ -83,14 +151,7 @@ export function SortSelect(props: SortSelectProps): ReactElement {
             onChange={(next) => {
               setSort(next);
             }}
-            options={values.map((value) => {
-              const key = sortLabelKey(value);
-              return {
-                value,
-                label: key !== undefined ? t(key) : value,
-                disabled: value === "distance" && !hasCentre,
-              };
-            })}
+            options={optionsFor(bind["aria-describedby"] ?? "")}
           />
         </Flex>
       )}

package/src/default/index.ts

@@ -48,8 +48,16 @@ export type {
   SearchResultsRenderer,
 } from "./SearchResultsPane.js";
 
-export { FilterChips, CHIP_ROW_CLASS, CHIP_ROW_STYLE_HREF, chipRowCss } from "./FilterChips.js";
-export type { FilterChipsProps } from "./FilterChips.js";
+export {
+  FilterChips,
+  CHIP_BAND_ORDER,
+  CHIP_ROW_CLASS,
+  CHIP_ROW_STYLE_HREF,
+  categoryLeaf,
+  chipRowCss,
+  orderChipFilters,
+} from "./FilterChips.js";
+export type { ChipBand, ChipSpec, FilterChipsProps } from "./FilterChips.js";
 
 export { LocationSummaryLine } from "./LocationSummaryLine.js";
 export type { LocationSummaryLineProps } from "./LocationSummaryLine.js";

package/src/headless/FacetPanel.tsx

@@ -6,6 +6,8 @@ import type { FacetMeta, SearchRange } from "../api/types.js";
 import { useSearchQuery } from "../model/queries.js";
 import { buildFacetGroups } from "../state/facets.js";
 import type { FacetGroup } from "../state/facets.js";
+import { useHostFacetLabels } from "./useFacetLabels.js";
+import type { FacetLabelResolver } from "./useFacetLabels.js";
 import { useSearchState } from "./SearchStateProvider.js";
 
 /** The bag `<FacetPanel>` hands its render prop. */
@@ -87,6 +89,8 @@ export function FacetPanel(props: {
   /** BCP-47 tag for `date`-typed option labels. Defaults to the runtime's. */
   locale?: string;
   enabled?: boolean;
+  /** The host's vocabulary lookup — see {@link FacetLabelResolver}. */
+  resolveFacetLabels?: FacetLabelResolver;
   children: (bag: FacetPanelBag) => ReactNode;
 }): ReactNode {
   return props.children(
@@ -96,6 +100,9 @@ export function FacetPanel(props: {
         : {}),
       ...(props.locale !== undefined ? { locale: props.locale } : {}),
       ...(props.enabled !== undefined ? { enabled: props.enabled } : {}),
+      ...(props.resolveFacetLabels !== undefined
+        ? { resolveFacetLabels: props.resolveFacetLabels }
+        : {}),
     })
   );
 }
@@ -116,6 +123,13 @@ export function useFacetPanel(props: {
   categoryFeatures?: readonly FeatureDef[];
   locale?: string;
   enabled?: boolean;
+  /**
+   * The host's lookup for values neither the answer nor the schema names —
+   * see {@link FacetLabelResolver}. Threaded here rather than into each skin
+   * so the chip row and the filter panel, which both call this hook, cannot
+   * end up printing two different words for one value.
+   */
+  resolveFacetLabels?: FacetLabelResolver;
 } = {}): FacetPanelBag {
   const { state: searchState, setFilter, setRange, clearAll, toggleFilter, activeFilters } =
     useSearchState();
@@ -142,8 +156,13 @@ export function useFacetPanel(props: {
     })
   );
 
+  // The host seam runs AFTER `buildFacetGroups`, on what it could not name:
+  // the precedence is server captions, then the schema's own option table,
+  // then this. See `useFacetLabels.ts`.
+  const labelled = useHostFacetLabels(groups, props.resolveFacetLabels, props.locale);
+
   return {
-    state: groups,
+    state: labelled,
     approximate: meta.approximate,
     skipped: meta.skipped,
     counted: meta.counted,