@stapel/search-react 0.21.0 → 0.23.0

package/src/default/PartitionChips.tsx

@@ -0,0 +1,204 @@
+/**
+ * `<PartitionChips>` — the children of a `chips` category, as one row of
+ * single-select chips.
+ *
+ * A partition is a category whose children are not subcategories but one
+ * template split by a value their names express: buy / sell / let / rent,
+ * new / used, for boys / for girls. They keep their
+ * ids, their paths and their URLs — a listing still lands on a child — and
+ * only the PRESENTATION changes: the parent draws a feed, and the children
+ * are a choice above it rather than a grid of tiles the visitor has to pass
+ * through.
+ *
+ * Which categories are a partition is not decided here and not decided by
+ * this pair: `children_as` is a stored, derivable field on the category, and
+ * the storefront hands this component the children it resolved. What this
+ * component owns is that the choice is SINGLE-select and that "all" — the
+ * parent, unnarrowed — is one of the options rather than a way of clearing
+ * the others.
+ *
+ * ── Why a radiogroup and not a row of toggles ─────────────────────────────
+ *
+ * Because exactly one of them is true at a time, and `aria-pressed` buttons
+ * say the opposite: they announce a set of independent switches, so a screen
+ * reader user hears no reason why pressing one released another. A radiogroup
+ * with roving tabindex is the pattern for "one of these": Tab reaches the row
+ * once and lands on the chosen chip, the arrow keys move along it, and the
+ * group's own name says what is being chosen.
+ */
+import { useRef } from "react";
+import type {
+  CSSProperties,
+  KeyboardEvent as ReactKeyboardEvent,
+  ReactElement,
+  ReactNode,
+} from "react";
+import { Button } from "antd";
+import { useT } from "@stapel/core";
+import { cssVar, radii, spacing } from "@stapel/tokens";
+import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
+
+/** One child of a partitioned category. `path` is the slash-joined id path
+ * the `category` parameter takes — the same string `SearchQueryState.category`
+ * carries, so a host never rebuilds it from ids. */
+export interface PartitionChild {
+  readonly id: number | string;
+  readonly path: string;
+  readonly name: string;
+}
+
+export interface PartitionChipsProps {
+  /** The children, in the order the catalogue declares them. */
+  readonly items: readonly PartitionChild[];
+  /** The chosen child's `path`, or `null` for the parent itself. CONTROLLED:
+   * this row keeps no state, because the choice is a `category` in the URL. */
+  readonly value: string | null;
+  readonly onChange: (path: string | null) => void;
+  /** The first chip's label. Defaults to `search.partition.all`. */
+  readonly allLabel?: ReactNode;
+  /** The row's accessible name. Defaults to `search.partition.label`. */
+  readonly label?: string;
+  /**
+   * Which shape the row takes. `"chips"` (the default) is the phone's: a
+   * wrapping row of rounded pills above the feed. `"segmented"` is the
+   * desktop RAIL's — one joined control under the axis's own label, which is
+   * how the reference classified draws the same choice (a car-type row:
+   * all, used, new) and what a 280px column has room for.
+   *
+   * The SEMANTICS do not vary with it. Both are the same `radiogroup` with
+   * the same roving tabindex and the same arrow keys — a segmented look is a
+   * border-radius decision, and swapping in a component that draws joined
+   * cells by giving up "exactly one of these is true" would trade the
+   * accessible half of this control for the visible half.
+   */
+  readonly variant?: "chips" | "segmented";
+}
+
+const CHIP: CSSProperties = { borderRadius: radii.full };
+
+const ROW: CSSProperties = {
+  display: "flex",
+  flexWrap: "wrap",
+  gap: spacing[2],
+};
+
+/**
+ * The segmented row: one joined control, no gaps, the group's own outline.
+ *
+ * `gap: 0` plus a shared border is what makes three buttons read as one
+ * control — the thing a rail needs, because a wrapping pill row in a 280px
+ * column is two ragged lines. `overflow: hidden` clips the cells' own corners
+ * to the group's radius so the ends are round and the joins are square.
+ */
+const SEGMENTED_ROW: CSSProperties = {
+  display: "flex",
+  gap: 0,
+  inlineSize: "100%",
+  border: `1px solid ${cssVar("border")}`,
+  borderRadius: cssVar("radius-md"),
+  overflow: "hidden",
+};
+
+/** One cell of the segmented row: an equal share of the width, square joins,
+ * no border of its own — the group draws the outline. */
+const SEGMENTED_CELL: CSSProperties = {
+  flex: "1 1 0",
+  minInlineSize: 0,
+  borderRadius: 0,
+  borderInline: "none",
+  borderBlock: "none",
+};
+
+/** The row's cells, as `[value, label]` — the parent first, then the
+ * children in catalogue order. */
+function cells(
+  items: readonly PartitionChild[],
+  allLabel: ReactNode
+): readonly (readonly [string | null, ReactNode])[] {
+  return [
+    [null, allLabel] as const,
+    ...items.map((item) => [item.path, item.name] as const),
+  ];
+}
+
+export function PartitionChips(props: PartitionChipsProps): ReactElement {
+  const t = useT();
+  const row = useRef<HTMLDivElement>(null);
+  const options = cells(
+    props.items,
+    props.allLabel ?? t(SEARCH_I18N_KEYS.partitionAll)
+  );
+
+  /**
+   * Arrow keys move the choice AND the focus, which is what a radiogroup
+   * does: in a single-select row the focused option is the selected one, so
+   * moving focus without choosing would leave the two disagreeing.
+   */
+  const onKeyDown =
+    (index: number) =>
+    (event: ReactKeyboardEvent): void => {
+    const step =
+      event.key === "ArrowRight" || event.key === "ArrowDown"
+        ? 1
+        : event.key === "ArrowLeft" || event.key === "ArrowUp"
+          ? -1
+          : event.key === "Home"
+            ? -index
+            : event.key === "End"
+              ? options.length - 1 - index
+              : 0;
+    if (step === 0) return;
+    event.preventDefault();
+    const next = (index + step + options.length) % options.length;
+    const cell = options[next];
+    if (cell === undefined) return;
+    props.onChange(cell[0]);
+    const buttons = row.current?.querySelectorAll<HTMLElement>('[role="radio"]');
+    buttons?.[next]?.focus();
+  };
+
+  // A `value` naming no cell (a link into a child that has since moved) must
+  // still leave the row reachable by Tab, so the roving stop falls back to the
+  // parent chip rather than vanishing.
+  const active = options.findIndex(([value]) => value === props.value);
+  const stop = active >= 0 ? active : 0;
+
+  const segmented = props.variant === "segmented";
+  return (
+    <div
+      style={segmented ? SEGMENTED_ROW : ROW}
+      data-variant={segmented ? "segmented" : "chips"}
+      ref={row}
+      role="radiogroup"
+      aria-label={props.label ?? t(SEARCH_I18N_KEYS.partitionLabel)}
+      data-testid="partition-chips"
+    >
+      {options.map(([value, label], index) => {
+        const selected = value === props.value;
+        return (
+          <Button
+            key={value ?? "__all__"}
+            size="small"
+            {...(segmented ? {} : { shape: "round" as const })}
+            type={selected ? "primary" : "default"}
+            role="radio"
+            aria-checked={selected}
+            // Roving tabindex: the row is ONE Tab stop and it lands on the
+            // chosen chip, not on the first of eight.
+            tabIndex={index === stop ? 0 : -1}
+            style={segmented ? SEGMENTED_CELL : CHIP}
+            data-testid={`partition-chip-${value ?? "all"}`}
+            data-analytics="none"
+            data-analytics-reason="choosing a section is a read, not a flow step"
+            onKeyDown={onKeyDown(index)}
+            onClick={() => {
+              props.onChange(value);
+            }}
+          >
+            {label}
+          </Button>
+        );
+      })}
+    </div>
+  );
+}

package/src/default/PopularValues.tsx

@@ -0,0 +1,151 @@
+/**
+ * `<PopularValues>` — the busiest values of one facet, printed as words a
+ * person can click, above the results.
+ *
+ * A dictionary facet in the rail answers "narrow this list"; it does not
+ * answer "what is IN this category". On a feed page of a cars leaf the second
+ * question is the one a visitor arrives with, and its answer is already in the
+ * envelope: `Toyota 802` is a bucket and its count. Printed as a multi-column
+ * block it is a table of contents for the category — the eleven makes that
+ * account for most of it, in one glance, each one a filter.
+ *
+ * ── What it is NOT ────────────────────────────────────────────────────────
+ *
+ * Not a replacement for the facet control: it shows the busy head of ONE
+ * group and says so with a link into the whole thing (`onShowAll`). Not a
+ * second source of counts either — the numbers are the answer's own
+ * drill-down counts, the same ones the checkbox rows carry, so a value cannot
+ * read `802` here and `93` in the panel.
+ *
+ * ── Hidden on a phone by a PROP ───────────────────────────────────────────
+ *
+ * `hidden` rather than a media query inside, because whether a 390px screen
+ * has room for a block of forty links is a decision about the PAGE, and the
+ * page is the storefront's. A component that hid itself below some width of
+ * its own choosing would take that decision away from the only surface that
+ * knows what else is on screen — and would still render the DOM, which is
+ * what `display: none` costs a screen reader.
+ */
+import type { CSSProperties, ReactElement, ReactNode } from "react";
+import { Button, Flex, Typography } from "antd";
+import { useT } from "@stapel/core";
+import { spacing } from "@stapel/tokens";
+import type { FacetGroup, FacetOption } from "../state/facets.js";
+import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
+
+/** How many values the block prints before the link into the full control. */
+export const POPULAR_VALUES_LIMIT = 12;
+
+/** How many columns the list flows into. Three fills a desktop content column
+ * without turning a make into a two-line wrap. */
+export const POPULAR_VALUES_COLUMNS = 3;
+
+/** A value with no evidence behind it is not a popular value. Uncounted
+ * options carry `count: null` and are dropped here rather than printed with a
+ * blank where the number belongs — the block IS the numbers. */
+function hasEvidence(option: FacetOption): boolean {
+  return option.count !== null && option.count > 0;
+}
+
+/** The busiest values of the group, count-descending, capped. */
+export function popularOptions(
+  group: FacetGroup,
+  limit: number = POPULAR_VALUES_LIMIT
+): readonly FacetOption[] {
+  return [...group.options.filter(hasEvidence)]
+    .sort((a, b) => (b.count ?? 0) - (a.count ?? 0))
+    .slice(0, limit);
+}
+
+const ROW: CSSProperties = {
+  // `break-inside` keeps a value and its count on one line when the browser
+  // decides where the column ends.
+  breakInside: "avoid",
+  display: "flex",
+  gap: spacing[2],
+  alignItems: "baseline",
+};
+
+export interface PopularValuesProps {
+  /** The group to print — normally the first `ref_select` of the plan. */
+  readonly group: FacetGroup;
+  /** Apply one value. Same signature as the panel's `toggle`, so a host can
+   * hand the facet bag's own function straight in. */
+  readonly onApply: (slug: string, value: string) => void;
+  /** Draw nothing. The phone, decided by the page — see the module note. */
+  readonly hidden?: boolean;
+  /** How many values. Default {@link POPULAR_VALUES_LIMIT}. */
+  readonly limit?: number;
+  /** How many columns. Default {@link POPULAR_VALUES_COLUMNS}. */
+  readonly columns?: number;
+  /** The block's heading. Defaults to the group's own label; `null` draws
+   * none, for a surface that has already named the axis. */
+  readonly heading?: ReactNode;
+  /** Open the full control. Absent draws no link — a link that goes nowhere
+   * is worse than a block that stops. */
+  readonly onShowAll?: () => void;
+}
+
+export function PopularValues(props: PopularValuesProps): ReactElement | null {
+  const t = useT();
+  const { group } = props;
+  if (props.hidden === true) return null;
+  const options = popularOptions(group, props.limit ?? POPULAR_VALUES_LIMIT);
+  if (options.length === 0) return null;
+
+  return (
+    <Flex
+      vertical
+      gap={spacing[2]}
+      data-testid={`popular-values-${group.slug}`}
+      data-label-source={group.labelSource}
+    >
+      {props.heading !== null && (
+        <Typography.Text strong>{props.heading ?? group.label}</Typography.Text>
+      )}
+      <div
+        style={{
+          columnCount: props.columns ?? POPULAR_VALUES_COLUMNS,
+          columnGap: spacing[4],
+        }}
+      >
+        {options.map((option) => (
+          <div key={option.value} style={ROW}>
+            <Button
+              type="link"
+              size="small"
+              style={{ paddingInline: 0, height: "auto" }}
+              data-testid={`popular-value-${group.slug}-${option.value}`}
+              data-analytics="none"
+              data-analytics-reason="a filter is a read, not a flow step"
+              onClick={() => {
+                props.onApply(group.slug, option.value);
+              }}
+            >
+              {option.label}
+            </Button>
+            <Typography.Text
+              type="secondary"
+              data-testid={`popular-count-${group.slug}-${option.value}`}
+            >
+              {option.count}
+            </Typography.Text>
+          </div>
+        ))}
+      </div>
+      {props.onShowAll !== undefined && (
+        <Button
+          type="link"
+          size="small"
+          style={{ alignSelf: "flex-start", paddingInline: 0 }}
+          data-testid={`popular-all-${group.slug}`}
+          data-analytics="none"
+          data-analytics-reason="opening a filter control is a read, not a flow step"
+          onClick={props.onShowAll}
+        >
+          {t(SEARCH_I18N_KEYS.facetsPopularAll)}
+        </Button>
+      )}
+    </Flex>
+  );
+}

package/src/default/RangeFilterRow.tsx

@@ -17,7 +17,7 @@
  */
 import { useRef, useState } from "react";
 import type { ReactElement } from "react";
-import { Button, Flex, InputNumber, Typography } from "antd";
+import { Button, Flex, InputNumber, Select, Typography } from "antd";
 import { actionAvailable, actionBlocked, useFormat, useT } from "@stapel/core";
 import type { ActionAvailability } from "@stapel/core";
 import { GatedButton } from "@stapel/tokens-antd/skin";
@@ -70,6 +70,100 @@ function boundSuffix(
   }
 }
 
+/**
+ * One bound of a PICKER axis — a bounded integer small enough to choose from
+ * (`RangeGroup.picker`), which on a cars leaf is the year.
+ *
+ * The founder's walk of the live page put it plainly: the year was a bare
+ * number field. A year is not a quantity a person computes, it is one of a
+ * hundred-odd values, and every classified draws it as two pickers.
+ *
+ * Typing still works, and the rule is the same one `attributes-react` is
+ * building for a bounded integer field: what a person types is a value, not a
+ * query. While the typed text IS a valid value inside the bounds the list
+ * narrows to it and gets out of the way; the moment it is not — a letter, a
+ * year before the catalogue's own floor — the full list comes back WITH the
+ * bounds said in words, because "1899" silently doing nothing is the defect
+ * this replaces.
+ */
+function BoundPicker(props: {
+  readonly group: RangeGroup;
+  readonly bound: "from" | "to";
+  readonly value: string;
+  readonly onChange: (value: string) => void;
+  readonly onCommit: () => void;
+}): ReactElement {
+  const t = useT();
+  const { group } = props;
+  const [typed, setTyped] = useState("");
+  const values = group.picker ?? [];
+  const min = group.min ?? values[values.length - 1];
+  const max = group.max ?? values[0];
+  const query = typed.trim();
+  const asNumber = Number(query);
+  // "Valid" is the whole rule: a number, whole, and inside the axis's own
+  // bounds. Anything else is a query that matched nothing, not a value.
+  const valid =
+    query !== "" &&
+    /^-?\d+$/.test(query) &&
+    Number.isInteger(asNumber) &&
+    (min === undefined || asNumber >= min) &&
+    (max === undefined || asNumber <= max);
+  const listed = valid
+    ? values.filter((value) => String(value).startsWith(query))
+    : values;
+  return (
+    <Flex vertical gap={spacing[1]}>
+      <Select
+        showSearch
+        allowClear
+        value={props.value === "" ? null : props.value}
+        searchValue={typed}
+        // The list is already narrowed above, by the rule this control is
+        // about; antd's own substring filter would narrow it a second time
+        // and by a different rule.
+        filterOption={false}
+        placeholder={t(
+          props.bound === "from"
+            ? SEARCH_I18N_KEYS.facetsRangeFrom
+            : SEARCH_I18N_KEYS.facetsRangeTo
+        )}
+        aria-label={t(
+          props.bound === "from"
+            ? SEARCH_I18N_KEYS.facetsRangeFromAria
+            : SEARCH_I18N_KEYS.facetsRangeToAria,
+          { feature: group.label }
+        )}
+        data-testid={`facet-range-${group.slug}-${props.bound}`}
+        style={{ minWidth: RANGE_FIELD_MIN_WIDTH }}
+        options={listed.map((value) => ({
+          value: String(value),
+          label: String(value),
+        }))}
+        onSearch={setTyped}
+        onChange={(next: string | null) => {
+          setTyped("");
+          props.onChange(next ?? "");
+        }}
+        onBlur={props.onCommit}
+      />
+      {/* Said only when the typing has gone outside the axis — a hint over an
+          untouched field is chrome. */}
+      {query !== "" && !valid && (
+        <Typography.Text
+          type="secondary"
+          data-testid={`facet-range-${group.slug}-${props.bound}-bounds`}
+        >
+          {t(SEARCH_I18N_KEYS.facetsRangeBounds, {
+            min: String(min ?? ""),
+            max: String(max ?? ""),
+          })}
+        </Typography.Text>
+      )}
+    </Flex>
+  );
+}
+
 export function RangeFilterRow(props: RangeFilterRowProps): ReactElement {
   const t = useT();
   const format = useFormat();
@@ -138,6 +232,25 @@ export function RangeFilterRow(props: RangeFilterRowProps): ReactElement {
         {suffix === undefined ? group.label : `${group.label}, ${suffix}`}
       </Typography.Text>
       <Flex gap={spacing[2]} align="center" wrap>
+        {group.picker !== undefined ? (
+          <>
+            <BoundPicker
+              group={group}
+              bound="from"
+              value={from}
+              onChange={setFrom}
+              onCommit={commit}
+            />
+            <BoundPicker
+              group={group}
+              bound="to"
+              value={to}
+              onChange={setTo}
+              onCommit={commit}
+            />
+          </>
+        ) : (
+        <>
         <InputNumber
           value={from === "" ? null : Number(from)}
           placeholder={t(SEARCH_I18N_KEYS.facetsRangeFrom)}
@@ -172,6 +285,8 @@ export function RangeFilterRow(props: RangeFilterRowProps): ReactElement {
           }}
           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

package/src/default/SearchPage.tsx

@@ -66,7 +66,7 @@ import type { CSSProperties, ReactElement, ReactNode } from "react";
 import { Button, Flex } from "antd";
 import { SkinDialog, SkinTheme, useDialogSurface } from "@stapel/tokens-antd/skin";
 import { useT, useTPlural } from "@stapel/core";
-import { spacing } from "@stapel/tokens";
+import { cssVar, spacing } from "@stapel/tokens";
 import type { FeatureDef } from "@stapel/attributes-react";
 import { SearchStateProvider, useSearchState } from "../headless/SearchStateProvider.js";
 import type { SearchParamsAdapter } from "../headless/SearchStateProvider.js";
@@ -126,6 +126,50 @@ export const FILTERS_RAIL_WIDTH = 280;
  * `alignSelf: flex-start` is load-bearing: a flex child stretches to the row's
  * height by default, and a stretched box has nothing to stick to.
  */
+/** The class the rail's own scrollbar rules are hung on. */
+export const RAIL_CLASS = "stapel-search-rail";
+
+/** The `href` the hoisted rail sheet is deduplicated by. */
+export const RAIL_STYLE_HREF = "stapel-search-rail";
+
+/**
+ * The rail scrolls, and its scrollbar must not sit ON the filters.
+ *
+ * `scrollbar-width: thin` and `scrollbar-gutter: stable` (below, in `RAIL`)
+ * are the standard half of this and they are not enough: on every WebKit
+ * platform with overlay scrollbars — a Mac by default, every iOS browser —
+ * the bar is drawn OVER the content and the gutter reserves nothing, so the
+ * walker saw the bar lying across the right edge of the checkbox labels.
+ *
+ * So the rail also declares a CLASSIC scrollbar through the WebKit
+ * pseudo-elements: a bar with a real width, which pushes the panel's content
+ * in by exactly that much instead of floating above it, drawn in the token
+ * palette so it is the panel's own hairline in both themes rather than a
+ * hard-coded grey that glows in the dark one. `--stapel-*` custom properties
+ * resolve per theme at paint time, which is why this is a sheet and not a
+ * pair of computed inline values: an inline colour would freeze whichever
+ * theme was mounted first.
+ *
+ * Emitted as one hoisted `<style>` (React 19 dedupes by `href`), because a
+ * pseudo-element is unreachable from an inline style — the same reason
+ * `<LocationSummaryLine>` hoists one.
+ */
+export function railScrollbarCss(): string {
+  const rail = `.${RAIL_CLASS}`;
+  return [
+    // A real width: an overlay bar occupies no space and therefore overlaps.
+    `${rail}::-webkit-scrollbar{inline-size:8px;block-size:8px}`,
+    `${rail}::-webkit-scrollbar-track{background:transparent}`,
+    `${rail}::-webkit-scrollbar-thumb{background:${cssVar("border")};` +
+      `border-radius:${cssVar("radius-full")}}`,
+    `${rail}::-webkit-scrollbar-thumb:hover{background:${cssVar("text-subtle")}}`,
+    // Firefox/Chromium's standard properties, stated here too so the rule
+    // travels with the class when the panel is used outside `<SearchPage>`.
+    `${rail}{scrollbar-width:thin;scrollbar-gutter:stable;` +
+      `scrollbar-color:${cssVar("border")} transparent}`,
+  ].join("\n");
+}
+
 const RAIL: CSSProperties = {
   flex: `0 0 ${String(FILTERS_RAIL_WIDTH)}px`,
   // Both bounds, not just the upper one. `flex-shrink: 0` already holds the
@@ -208,6 +252,14 @@ export interface SearchPageProps extends ThemeModeProp, ParseSearchStateOptions
    * coordinate, with or without it.
    */
   readonly geoLabel?: ReactNode;
+  /**
+   * The partition control, drawn at the top of the filter panel — see
+   * {@link FacetPanelPaneProps.partition}.
+   */
+  readonly partition?: ReactNode;
+  /** Facet slugs pinned above every other group — see
+   * {@link FacetPanelPaneProps.pinnedFacets}. */
+  readonly pinnedFacets?: readonly string[];
   /** Print the engine's list of uncounted facet slugs in the filter panel.
    * Default `false` — see {@link FacetPanelPaneProps.skippedNotice}. */
   readonly skippedNotice?: boolean;
@@ -639,7 +691,14 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
         </>
       ) : showFilters ? (
         <Flex align="flex-start" gap={spacing[5]} data-testid="search-page-columns">
-          <div style={RAIL}>{panel}</div>
+          <div className={RAIL_CLASS} style={RAIL}>
+            {/* The rail's scrollbar, in the gutter and in the token palette —
+                see `railScrollbarCss`. Hoisted, deduped by `href`. */}
+            <style href={RAIL_STYLE_HREF} precedence="default">
+              {railScrollbarCss()}
+            </style>
+            {panel}
+          </div>
           {/* ONE heading and ONE sort control. The page used to caption
               the toolbar "Results" and then mount a pane whose own heading
               says "Results" again — the live /s page printed both, one

package/src/default/index.ts

@@ -40,7 +40,12 @@
  */
 
 // ── surfaces ────────────────────────────────────────────────────────────────
-export { SearchPage } from "./SearchPage.js";
+export {
+  SearchPage,
+  RAIL_CLASS,
+  RAIL_STYLE_HREF,
+  railScrollbarCss,
+} from "./SearchPage.js";
 export type { SearchPageProps, SearchFiltersLayout } from "./SearchPage.js";
 
 export { SearchResultsPane, RESULTS_MAX_WIDTH } from "./SearchResultsPane.js";
@@ -72,6 +77,8 @@ export {
   FacetGroupControl,
   facetGroupShape,
   facetOptionNodes,
+  isDictionaryFacet,
+  FACET_DICTIONARY_THRESHOLD,
   FACET_VISIBLE_OPTIONS,
 } from "./FacetGroupControl.js";
 export type {
@@ -80,7 +87,25 @@ export type {
   FacetOptionNode,
 } from "./FacetGroupControl.js";
 
-export { FacetPanelPane } from "./FacetPanelPane.js";
+// ── the browse surfaces a storefront PLACES (this pair does not lay them
+//    out: where a popular-values block or a partition row belongs on a
+//    category page is the page's decision) ──────────────────────────────────
+export {
+  PopularValues,
+  popularOptions,
+  POPULAR_VALUES_COLUMNS,
+  POPULAR_VALUES_LIMIT,
+} from "./PopularValues.js";
+export type { PopularValuesProps } from "./PopularValues.js";
+export { PartitionChips } from "./PartitionChips.js";
+export type { PartitionChild, PartitionChipsProps } from "./PartitionChips.js";
+
+export {
+  FacetPanelPane,
+  FACET_OPEN_GROUPS,
+  FACET_SEARCH_THRESHOLD,
+  FACET_VISIBLE_GROUPS,
+} from "./FacetPanelPane.js";
 export type {
   FacetPanelPaneProps,
   CategoryFilterSlotProps,

package/src/headless/useFacetLabels.ts

@@ -32,7 +32,7 @@
  *   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
+ * and it marks an option it could not name `labelSource: "none"` — 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
@@ -98,7 +98,7 @@ 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)
+    .filter((option) => option.labelSource === "none")
     .map((option) => option.value)
     .sort((a, b) => a.localeCompare(b));
 }
@@ -157,14 +157,14 @@ export function useHostFacetLabels(
       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;
+          // Precedence again, enforced rather than assumed: an option the
+          // server or the schema already named is not the host's to
+          // overwrite. The source says so; the strings cannot.
+          if (option.labelSource !== "none") return option;
           const caption = named[option.value];
           return caption === undefined || caption.length === 0
             ? option
-            : { ...option, label: caption };
+            : { ...option, label: caption, labelSource: "host" as const };
         }),
       };
     })