@stapel/search-react 0.11.0 → 0.13.0

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/cardPhotos.ts

@@ -0,0 +1,195 @@
+/**
+ * WHAT A SEARCH CARD ACTUALLY STORES FOR A PHOTO, and how it becomes something
+ * `@stapel/image` can draw.
+ *
+ * ── The defect this file exists to end ────────────────────────────────────
+ *
+ * The default card used to read `card.image` expecting an object with a `url`
+ * key, and fall back to `card.image_url`. Neither is what this fleet emits:
+ *
+ *  - `image_url` is a convention NOTHING in the fleet writes. It was declared
+ *    in `GENERIC_CARD_FIELDS`, drawn in the demos from a data URI, and never
+ *    once served by a backend.
+ *  - `card.image` IS emitted — by `stapel-classified`'s search projection —
+ *    and it is a plain `<type>/<hash>` STRING, not an object.
+ *  - where a card DOES carry an object (chat's subject card, which serves the
+ *    same CDN render descriptor its attachments carry), that object has `ref`
+ *    and `variants[]` and NO top-level `url` — so the `"url" in rich` guard
+ *    rejected the one rich shape the fleet has.
+ *
+ * The net effect was a card with no photo on every consumer that did not pass
+ * its own `renderCard`. Read the two real shapes instead, and read `images[]`
+ * first: since stapel-classified 0.7.0 the projection carries the whole
+ * gallery in seller order, deduplicated and capped by `CARD_IMAGES_LIMIT`,
+ * with the singular `image` kept as `images[0]`.
+ *
+ * ── Three shapes, one output ──────────────────────────────────────────────
+ *
+ * 1. A CDN reference (`"image/9f2c…"`) — resolved through the runtime's
+ *    {@link SearchImageResolver}, the same seam `@stapel/listings-react`
+ *    states, for the same reason: no contract in this fleet resolves a
+ *    stranger's reference, so the deployment hands its own knowledge in once.
+ * 2. A URL a doc type stored directly (`"https://…"`, `"/media/…"`,
+ *    `"data:image/…"`) — no ladder to shop, so it degrades to `source:
+ *    "link"`. A CDN reference is `<type>/<hash>`: no scheme and no leading
+ *    slash, so the two are told apart by shape and never by a guess.
+ * 3. A render descriptor object — `variants[]` with a `tier` each, an inline
+ *    `preview_b64`, geometry. Read defensively (the field is `unknown` by
+ *    contract) exactly as `@stapel/chat-react` reads the same descriptor.
+ */
+import type { StapelImage } from "@stapel/image";
+import type { SearchImageResolver } from "../model/runtime.js";
+
+/** A card's photo fields, and how many of them the card carried at all. */
+export interface CardPhotos {
+  /**
+   * How many photo entries the card STORES — before resolving. `0` means the
+   * doc type has no photo for this row (or no photo field at all), which is a
+   * different thing from "a photo nothing could resolve", and the card draws
+   * the two differently.
+   */
+  readonly stored: number;
+  /** The ones that became something drawable, in the stored order. */
+  readonly images: readonly StapelImage[];
+}
+
+function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function str(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function num(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+/**
+ * A stored string that is already a URL rather than a CDN reference.
+ *
+ * stapel-cdn's unit is `<type>/<hash>` — a relative pair with no scheme and no
+ * leading slash — so anything carrying a scheme, a protocol-relative prefix or
+ * a leading `/` is a URL the doc type stored itself.
+ */
+function isUrl(value: string): boolean {
+  return (
+    value.startsWith("/") ||
+    value.startsWith("data:") ||
+    /^[a-z][a-z0-9+.-]*:/i.test(value)
+  );
+}
+
+/** A bare URL as the descriptor `<Image>` consumes: one rung, no ladder. */
+function linkImage(url: string): StapelImage {
+  return {
+    source: "link",
+    url,
+    mime: null,
+    width: null,
+    height: null,
+    aspect: null,
+    square: false,
+    preview_b64: null,
+    variants: [],
+  };
+}
+
+/**
+ * One rung of a render descriptor's ladder, in `@stapel/image`'s spelling.
+ *
+ * `tier` arrives in two spellings inside the SAME array — an int for the
+ * ladder rungs and the string sentinel `"original"` for the entry the snapshot
+ * builder appends. `String()` is right for both, which is why there is no
+ * branch here (`@stapel/cdn-react`'s `model/refs.ts` argues it at length).
+ */
+function rung(value: unknown): StapelImage["variants"][number] | undefined {
+  if (!isRecord(value)) return undefined;
+  const url = str(value["url"]);
+  if (url === undefined) return undefined;
+  const tier = value["tier"];
+  const branch = value["branch"];
+  return {
+    tier: typeof tier === "number" || typeof tier === "string" ? String(tier) : "",
+    branch: branch === "w" || branch === "h" ? branch : null,
+    url,
+    width: num(value["width"]),
+    height: num(value["height"]),
+  };
+}
+
+/**
+ * A CDN render descriptor → the descriptor `<Image>` consumes.
+ *
+ * The display URL is the descriptor's own `url` when it has one, else the
+ * `original` rung, else the largest rung — a snapshot carries no
+ * `original_url`, so the top of the ladder IS the original. With no rung at
+ * all the inline `preview_b64` is used: a real, honestly blurry image beats
+ * nothing. A descriptor with neither is not drawable and says so.
+ */
+function metaImage(meta: Readonly<Record<string, unknown>>): StapelImage | undefined {
+  const raw = meta["variants"];
+  const variants = (Array.isArray(raw) ? raw : [])
+    .map(rung)
+    .filter((v): v is StapelImage["variants"][number] => v !== undefined);
+  const original = variants.find((v) => v.tier === "original");
+  const largest = variants.reduce<StapelImage["variants"][number] | undefined>(
+    (best, v) => {
+      const size = Number(v.tier);
+      if (!Number.isFinite(size)) return best;
+      return best === undefined || size > Number(best.tier) ? v : best;
+    },
+    undefined
+  );
+  const preview = str(meta["preview_b64"]);
+  const url = str(meta["url"]) ?? original?.url ?? largest?.url ?? preview;
+  if (url === undefined) return undefined;
+  return {
+    source: "cdn",
+    url,
+    mime: str(meta["mime"]) ?? null,
+    width: num(meta["width"]),
+    height: num(meta["height"]),
+    aspect: num(meta["aspect"]),
+    square: meta["square"] === true,
+    preview_b64: preview ?? null,
+    variants,
+  };
+}
+
+/** One stored entry, in whichever of the three shapes it arrived. */
+export function cardImage(
+  value: unknown,
+  resolve: SearchImageResolver | undefined
+): StapelImage | undefined {
+  const ref = str(value);
+  if (ref !== undefined) {
+    return isUrl(ref) ? linkImage(ref) : resolve?.(ref);
+  }
+  if (isRecord(value)) return metaImage(value);
+  return undefined;
+}
+
+/**
+ * The card's gallery: `images[]` when the doc type carries one, the singular
+ * `image` otherwise.
+ *
+ * Never both — `stapel-classified` stores `image` as `images[0]`, so reading
+ * the singular after the list would draw the first photo twice. The singular
+ * stays the fallback for a doc type that never grew a list.
+ */
+export function readCardPhotos(
+  card: Readonly<Record<string, unknown>>,
+  resolve: SearchImageResolver | undefined
+): CardPhotos {
+  const list = card["images"];
+  const stored: readonly unknown[] = Array.isArray(list)
+    ? list
+    : card["image"] === undefined || card["image"] === null
+      ? []
+      : [card["image"]];
+  const images = stored
+    .map((entry) => cardImage(entry, resolve))
+    .filter((image): image is StapelImage => image !== undefined);
+  return { stored: stored.length, images };
+}

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,

package/src/headless/useFacetLabels.ts

@@ -0,0 +1,172 @@
+/**
+ * The HOST LABEL SEAM — the third source of a facet option's caption, and the
+ * only one that can reach a vocabulary.
+ *
+ * ── The defect ────────────────────────────────────────────────────────────
+ *
+ * A live classified deployment's category schema types `vendor`, `model`,
+ * `memory_size` and `color_ref_select` as `ref_select`: their config carries
+ * no `options` table at all, only a POINTER —
+ * `{"optionsRef": {"level": "Vendor", "vocabulary": "avito-phone-catalog"}}`.
+ * The words live in the vocabulary the pointer names, which is a different
+ * service with a different client. So the two label sources this pair already
+ * has both come up empty: the answer's `facet_labels` because the deployed
+ * server predates stapel-search 0.4.0 and sends no such key, and the schema
+ * because a pointer is not a table. The chips printed `apple`, `128-gb`,
+ * `chernyy` — storage slugs, at buyers.
+ *
+ * This pair must not grow a vocabulary client to fix that: it would tie every
+ * storefront's search to a service it may not run, and the host ALREADY has
+ * that client (`@stapel/attributes-react`'s `VocabularyClientProvider` is
+ * mounted for the composer). So the fetch is the host's and the discipline is
+ * this module's — the same division as `renderGeoFilter` and
+ * `renderCategoryFilter`, one seam lower because what crosses it is data
+ * rather than a control.
+ *
+ * ── Precedence, stated once ───────────────────────────────────────────────
+ *
+ *   1. the answer's `facet_labels`  — the server saw the write-time snapshot;
+ *   2. the feature def's inline `options` table — for the plain `select`
+ *      family, which carries its words with it;
+ *   3. this resolver;
+ *   4. the raw value.
+ *
+ * `buildFacetGroups` has already applied 1 and 2 by the time this hook runs,
+ * and it leaves an option it could not name with `label === value` — which is
+ * what makes "did anyone name this?" answerable without a second lookup. Only
+ * those values are asked about, so the host is never called for a value the
+ * server or the schema already captioned, and a resolver that returns nothing
+ * for a value leaves the raw value on screen. A chip that silently dropped an
+ * option would be worse than one showing a slug: the option is real, it has a
+ * count, and it is the only way to reach those documents.
+ *
+ * ── The fetch discipline ──────────────────────────────────────────────────
+ *
+ * TanStack Query, exactly like the pair's other three reads, and for the four
+ * reasons that made it right there:
+ *
+ *  - **batched per group.** One call per facet slug carrying every unresolved
+ *    value of it, not one call per chip.
+ *  - **cached.** `staleTime: Infinity` — a vocabulary term's caption changes
+ *    when somebody edits the catalogue, not between two clicks on a filter.
+ *  - **deduplicated.** The chip row, the filter panel and the page's layout
+ *    probe each call `useFacetPanel`, so three components ask for the same
+ *    group's captions in one render pass; one query key means one request.
+ *  - **aborted on supersession.** The `signal` is the query's own, so a
+ *    resolver that honours it stops a request whose answer nobody will read.
+ */
+import { useQueries } from "@tanstack/react-query";
+import { mapLoad } from "@stapel/core";
+import type { LoadState } from "@stapel/core";
+import type { FeatureDef } from "@stapel/attributes-react";
+import { searchQueryKeys } from "../model/queryKeys.js";
+import type { FacetGroup } from "../state/facets.js";
+
+/** What the host is asked to name. */
+export interface FacetLabelRequest {
+  /** The facet slug — `vendor`, `color_ref_select`. */
+  readonly slug: string;
+  /**
+   * The category's own def for the slug, when the host supplied a schema.
+   * It carries the `optionsRef` pointer (vocabulary + level) a resolver needs
+   * to know WHICH vocabulary these codes belong to, so a host does not have to
+   * keep a second copy of the schema to answer.
+   */
+  readonly feature: FeatureDef | undefined;
+  /**
+   * The values nobody has named yet, sorted. Only the unresolved ones: a
+   * resolver is never asked about a value the server or the schema captioned.
+   */
+  readonly values: readonly string[];
+}
+
+/**
+ * A host's answer: `{value: caption}`.
+ *
+ * Partial answers are the expected case, not an error — a code the vocabulary
+ * no longer holds simply is not in the map, and its chip keeps printing the
+ * raw value. Returning `{}` is a legitimate "I cannot name any of these".
+ */
+export type FacetLabelResolver = (
+  request: FacetLabelRequest,
+  options: { readonly signal: AbortSignal }
+) => Promise<Readonly<Record<string, string>>>;
+
+/** One frozen empty list, so a render with no unresolved values is stable. */
+const NO_REQUESTS: readonly FacetLabelRequest[] = [];
+
+/** The values of one group nobody has named — see the precedence note above. */
+function unresolvedValues(group: FacetGroup): readonly string[] {
+  return group.options
+    .filter((option) => option.label === option.value)
+    .map((option) => option.value)
+    .sort((a, b) => a.localeCompare(b));
+}
+
+function isCaptionMap(value: unknown): value is Readonly<Record<string, string>> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Fill in what the server and the schema could not name, through the host.
+ *
+ * Returns the groups UNCHANGED — same object identity — when there is no
+ * resolver or nothing came back, so a page with the seam unwired pays neither
+ * a request nor a re-render.
+ */
+export function useHostFacetLabels(
+  groups: LoadState<readonly FacetGroup[]>,
+  resolve: FacetLabelResolver | undefined,
+  locale: string | undefined
+): LoadState<readonly FacetGroup[]> {
+  const requests: readonly FacetLabelRequest[] =
+    resolve === undefined || groups.status !== "ready"
+      ? NO_REQUESTS
+      : groups.data
+          .map((group) => ({
+            slug: group.slug,
+            feature: group.feature,
+            values: unresolvedValues(group),
+          }))
+          .filter((request) => request.values.length > 0);
+
+  const answers = useQueries({
+    queries: requests.map((request) => ({
+      queryKey: searchQueryKeys.facetLabels(request.slug, request.values, locale),
+      queryFn: async ({ signal }: { signal: AbortSignal }): Promise<unknown> =>
+        resolve === undefined ? {} : await resolve(request, { signal }),
+      staleTime: Number.POSITIVE_INFINITY,
+      // A vocabulary that answered 500 answers 500 again a millisecond later,
+      // and three retries only delay the chip's raw value by three round
+      // trips — the same discipline the pair's other reads keep.
+      retry: false,
+    })),
+  });
+
+  const captions = new Map<string, Readonly<Record<string, string>>>();
+  requests.forEach((request, index) => {
+    const data = answers[index]?.data;
+    if (isCaptionMap(data)) captions.set(request.slug, data);
+  });
+  if (captions.size === 0) return groups;
+
+  return mapLoad(groups, (list) =>
+    list.map((group) => {
+      const named = captions.get(group.slug);
+      if (named === undefined) return group;
+      return {
+        ...group,
+        options: group.options.map((option) => {
+          // Precedence again, enforced rather than assumed: an option whose
+          // label already differs from its value was named by the server or
+          // the schema, and the host does not get to overwrite either.
+          if (option.label !== option.value) return option;
+          const caption = named[option.value];
+          return caption === undefined || caption.length === 0
+            ? option
+            : { ...option, label: caption };
+        }),
+      };
+    })
+  );
+}