@stapel/search-react 0.22.0 → 0.23.0

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";
@@ -95,7 +100,12 @@ export type { PopularValuesProps } from "./PopularValues.js";
 export { PartitionChips } from "./PartitionChips.js";
 export type { PartitionChild, PartitionChipsProps } from "./PartitionChips.js";
 
-export { FacetPanelPane } from "./FacetPanelPane.js";
+export {
+  FacetPanelPane,
+  FACET_OPEN_GROUPS,
+  FACET_SEARCH_THRESHOLD,
+  FACET_VISIBLE_GROUPS,
+} from "./FacetPanelPane.js";
 export type {
   FacetPanelPaneProps,
   CategoryFilterSlotProps,

package/src/i18n/es.ts

@@ -96,6 +96,9 @@ export const searchI18nBundleEs: I18nDictionary = {
   "search.facets.dictionary_search": "Buscar un valor",
   "search.facets.dictionary_empty": "Ningún valor coincide con esto",
   "search.facets.dictionary_chosen": "Elegido",
+  "search.facets.dictionary_any": "Cualquiera",
+  "search.facets.all_filters": "Todos los filtros ({count})",
+  "search.facets.range_bounds": "de {min} a {max}",
   "search.facets.popular_all": "Todos",
   "search.partition.all": "Todos",
   "search.partition.label": "Sección",

package/src/i18n/keys.ts

@@ -171,6 +171,28 @@ export const SEARCH_I18N_KEYS = {
   /** Over the values already chosen, which stay visible whatever the box
    * says — a filter a person cannot see is a filter they cannot remove. */
   facetsDictionaryChosen: "search.facets.dictionary_chosen",
+  /**
+   * The closed dictionary FIELD with nothing chosen — "no constraint on this
+   * axis", the way a classified says it ("Any make", shortened to "Any").
+   *
+   * Not `facetsPopularAll` and not `partitionAll`, which are both the word
+   * "All": those two name a WIDER SET a person can move to, and this one
+   * names the absence of a narrowing. The three read alike in English and
+   * diverge in every language with gender or case.
+   */
+  facetsDictionaryAny: "search.facets.dictionary_any",
+  /**
+   * The tail of the rail, folded: how many groups are behind one control.
+   * `{count}` is a number in parentheses, not a counted noun, so this is not
+   * a plural family — the same shape as `facetsClearAll`.
+   */
+  facetsAllFilters: "search.facets.all_filters",
+  /**
+   * The bounds of a picker axis, said in words when what was typed is
+   * outside them — a year before the catalogue's own floor otherwise does
+   * nothing at all, silently.
+   */
+  facetsRangeBounds: "search.facets.range_bounds",
   /** The way from the "popular values" block into the whole control. The
    * block is a shortcut over the busiest values, so the link has to say that
    * the rest exist. */
@@ -497,6 +519,9 @@ export const searchI18nBundleEn: Record<string, string> = {
   "search.facets.dictionary_search": "Find a value",
   "search.facets.dictionary_empty": "No value matches this",
   "search.facets.dictionary_chosen": "Chosen",
+  "search.facets.dictionary_any": "Any",
+  "search.facets.all_filters": "All filters ({count})",
+  "search.facets.range_bounds": "from {min} to {max}",
   "search.facets.popular_all": "All",
   "search.partition.all": "All",
   "search.partition.label": "Section",

package/src/i18n/ru.ts

@@ -125,6 +125,9 @@ export const searchI18nBundleRu: I18nDictionary = {
   "search.facets.dictionary_search": "Найти значение",
   "search.facets.dictionary_empty": "Такого значения здесь нет",
   "search.facets.dictionary_chosen": "Выбрано",
+  "search.facets.dictionary_any": "Любая",
+  "search.facets.all_filters": "Все фильтры ({count})",
+  "search.facets.range_bounds": "от {min} до {max}",
   "search.facets.popular_all": "Все",
   "search.partition.all": "Все",
   "search.partition.label": "Раздел",

package/src/index.ts

@@ -116,8 +116,11 @@ export type {
 export {
   FACETABLE_FEATURE_TYPES,
   buildFacetGroups,
+  facetGroupHasEvidence,
+  facetGroupIsDrawable,
   facetOptionLabel,
   isFacetableFeature,
+  orderFacetGroupsBySchema,
 } from "./state/facets.js";
 export type {
   BuildFacetGroupsInput,
@@ -134,6 +137,7 @@ export {
 
 export {
   RANGE_FEATURE_TYPES,
+  RANGE_PICKER_MAX_VALUES,
   buildRangeGroups,
   coreRangeLabelKey,
   isRangeFeature,

package/src/state/facets.ts

@@ -96,6 +96,46 @@ function warnUnnamedGroup(slug: string): void {
   );
 }
 
+/** Slugs already reported as undrawable — one warning per slug per page. */
+const warnedUndrawable = new Set<string>();
+
+/**
+ * An axis that reached the panel with nothing to draw, said once, in
+ * development only.
+ *
+ * Measured on a live classified's cars branch: `make_ref_select`,
+ * `model` and `generation` are `ref_select` features whose config is a bare
+ * `optionsRef` pointer into a vocabulary — there is no option table in the
+ * schema and there never will be — so whenever the server's facet plan does
+ * not COUNT them there is nothing on the client to enumerate, and the group
+ * left the rail without a word while every `select`-typed comfort option
+ * (steering side, power steering, heating) drew its schema table and stayed.
+ * buyer's report was "I cannot pick a make".
+ *
+ * The panel still refuses to draw a heading over nothing — that is the right
+ * call — but the disappearance is a WIRING FAULT with two possible owners
+ * (the server's plan skipped a required axis, or the host threaded the wrong
+ * category's schema), and neither of them can see it from the page.
+ */
+function warnUndrawableGroup(group: FacetGroup): void {
+  const env = typeof process === "undefined" ? undefined : process.env;
+  if (env?.NODE_ENV === "production") return;
+  if (warnedUndrawable.has(group.slug)) return;
+  warnedUndrawable.add(group.slug);
+  console.warn(
+    `[search-react] facet group "${group.slug}" has no values to draw: the ` +
+      `answer did not count it${
+        group.feature === undefined
+          ? " and the category schema passed to this page does not define it"
+          : " and its config carries a vocabulary pointer, not an option table"
+      }, so the group is not rendered.` +
+      (group.feature?.mandatory === true
+        ? " The schema marks this axis REQUIRED — a buyer cannot narrow by a" +
+          " field every seller had to fill."
+        : "")
+  );
+}
+
 /**
  * Value types whose values are a BOUNDED OPTION SET — the only kind of
  * feature a person can be offered as a filter.
@@ -222,6 +262,105 @@ export function orderFacetGroups(
   return [...groups].sort(compareFacetsByEvidence);
 }
 
+/**
+ * Does the ANSWER have evidence for this axis — at least one value some
+ * candidate actually carries?
+ *
+ * The one fact that outranks every other rule in this module. A bucket with a
+ * count above zero is the server saying "documents in this result set have
+ * this value", and no schema opinion, no missing feature list and no type
+ * table may take an axis like that off the screen.
+ */
+export function facetGroupHasEvidence(group: FacetGroup): boolean {
+  return group.options.some((option) => (option.count ?? 0) > 0);
+}
+
+/**
+ * Is there anything for a surface to DRAW here?
+ *
+ * Shared by the rail and the chip row, which each used to hold their own
+ * `options.length > 0` — one predicate, or the two surfaces drift into two
+ * opinions about what an empty group is.
+ *
+ * A group with no options is a heading over nothing: after
+ * {@link buildFacetGroups} learned to read the schema, what is left in that
+ * state is a `ref_select` whose config is a bare `optionsRef` pointer and
+ * which the server did not count — nothing to enumerate from either side. It
+ * is not drawn, and in development it is NAMED: a required axis (the make on
+ * cars leaf) disappearing out of a rail is exactly the fault this pair spent
+ * a release chasing, and it must not disappear silently a second time.
+ *
+ * A group the reader has already FILTERED on is drawn whatever its options
+ * say — a constraint with no control to remove it is worse than a bare
+ * heading.
+ */
+export function facetGroupIsDrawable(group: FacetGroup): boolean {
+  if (group.selected.length > 0) return true;
+  if (group.options.length > 0) return true;
+  warnUndrawableGroup(group);
+  return false;
+}
+
+/**
+ * The order the RAIL puts groups in: the category's own schema order, with
+ * the axes the schema calls required in front of it.
+ *
+ * Evidence order ({@link compareFacetsByEvidence}) answers "which axis does
+ * this corpus fill in", which is the right question for a chip row that has
+ * room for four. It is the wrong question for a rail: on a cars leaf with
+ * three listings the busiest axis is whichever three values happen to be
+ * counted, so the rail opened on condition and colour while make, model and
+ * year — the three fields the schema marks
+ * `mandatory`, i.e. the three every seller had to fill and every buyer
+ * narrows by first — sat below them or off the fold entirely.
+ *
+ * So: the schema's own order, which is the order the composer asks the
+ * seller to fill the form in, with required first. Four bands:
+ *
+ *  1. `pinned` slugs, in the order given — the axis a page has already
+ *     decided is its subject (a partition's own field).
+ *  2. schema-required (`mandatory: true`), in schema order.
+ *  3. everything else the schema names, in schema order.
+ *  4. what the schema does not name at all — including EVERY group when the
+ *     host passed no feature list, which is the live parent-node case — in
+ *     evidence order, because with no schema there is no other order to have.
+ *
+ * Stable: within a band the comparator falls through to evidence and then to
+ * the order `buildFacetGroups` gave, so equal-ranked groups never reshuffle.
+ */
+export function orderFacetGroupsBySchema(input: {
+  readonly groups: readonly FacetGroup[];
+  /** The category schema, in the order the category declares it. */
+  readonly categoryFeatures?: readonly FeatureDef[];
+  /** Slugs pinned above everything, in the order given. */
+  readonly pinned?: readonly string[];
+}): readonly FacetGroup[] {
+  const schemaIndex = new Map<string, number>();
+  (input.categoryFeatures ?? []).forEach((feature, index) => {
+    if (!schemaIndex.has(feature.slug)) schemaIndex.set(feature.slug, index);
+  });
+  const pinnedIndex = new Map<string, number>();
+  (input.pinned ?? []).forEach((slug, index) => {
+    if (!pinnedIndex.has(slug)) pinnedIndex.set(slug, index);
+  });
+
+  const band = (group: FacetGroup): number => {
+    if (pinnedIndex.has(group.slug)) return 0;
+    if (!schemaIndex.has(group.slug)) return 3;
+    return group.feature?.mandatory === true ? 1 : 2;
+  };
+  const within = (group: FacetGroup): number =>
+    pinnedIndex.get(group.slug) ?? schemaIndex.get(group.slug) ?? 0;
+
+  return [...input.groups].sort((a, b) => {
+    const byBand = band(a) - band(b);
+    if (byBand !== 0) return byBand;
+    const byOrder = within(a) - within(b);
+    if (byOrder !== 0) return byOrder;
+    return compareFacetsByEvidence(a, b);
+  });
+}
+
 export interface BuildFacetGroupsInput {
   /** The envelope's `facets`: `{slug: {value: count}}`. */
   readonly facets: Readonly<Record<string, Readonly<Record<string, number>>>>;
@@ -467,6 +606,19 @@ export function buildFacetGroups(input: BuildFacetGroupsInput): readonly FacetGr
     seen.add(slug);
     // Applied first, type second — in that order, so an `imei` somebody
     // somehow got into a link keeps the control that removes it.
+    //
+    // EVIDENCE does not enter here, and the reason is worth stating because
+    // the opposite was tried: a counted bucket cannot promote a slug the
+    // schema NAMES AND DISOWNS. An `imei` the engine counted is still not a
+    // filter — a free-text identifier enumerates one term per document — and
+    // a `visibility: "owner"` feature is one the canon says is never
+    // facetable at all. What evidence does outrank is SILENCE: an absent def,
+    // an untyped def, and the whole empty feature list the live cars page
+    // passes at its parent node all answer "not a verdict"
+    // (see {@link isFacetableFeature}), so a counted axis is never dropped
+    // for a schema that says nothing about it. That is the live case; a
+    // wrong-schema case where some other category types `make_ref_select` as
+    // free text is not one this pair can tell apart from a real `imei`.
     const applied = (input.state.filters[slug] ?? []).length > 0;
     if (!applied && !isFacetableFeature(bySlug.get(slug))) continue;
     slugs.push(slug);

package/src/state/ranges.ts

@@ -76,6 +76,19 @@ export interface RangeGroup {
    * category forgot to declare an attribute for it.
    */
   readonly core: boolean;
+  /**
+   * The values this axis can take, when it is a BOUNDED INTEGER small enough
+   * to pick from — `undefined` for every other axis, including price.
+   *
+   * A year is not a number a person types, it is one of a hundred-odd values,
+   * and the reference classified draws it as two pickers. `min`/`max` from
+   * the schema (`year: 1900..2027` on a live cars leaf) bound the list;
+   * {@link RANGE_PICKER_MAX_VALUES} is where a picker stops being one and
+   * becomes a scroll with a search box in it, at which point two typed fields
+   * are the better control. Descending, because the busy end of a bounded
+   * axis is its top: a year picker that opens on 1900 is a picker nobody uses.
+   */
+  readonly picker: readonly number[] | undefined;
   /**
    * ISO 4217 code when the row is money, so the control can read as money
    * instead of as a bare integer. Only ever set on a core axis: an attribute
@@ -131,6 +144,36 @@ function translate(t: ((key: string) => string) | undefined, key: string): strin
   return resolved.length > 0 ? resolved : key;
 }
 
+/**
+ * How many values a bounded integer may have and still be a PICKER.
+ *
+ * 300 covers every year range a catalogue declares (a live cars leaf is
+ * 1900..2027, 128 values) and a door count, a seat count, a floor number,
+ * and stops well short of a mileage (1..1000000), which is a number people
+ * type and never a list.
+ */
+export const RANGE_PICKER_MAX_VALUES = 300;
+
+/**
+ * The value list for a bounded integer axis, or `undefined`.
+ *
+ * A CORE axis never gets one: price is unbounded by construction and the
+ * server does not declare bounds for it.
+ */
+function pickerValues(
+  feature: FeatureDef | undefined,
+  min: number | undefined,
+  max: number | undefined
+): readonly number[] | undefined {
+  if (feature === undefined) return undefined;
+  if (featureType(feature) !== "int") return undefined;
+  if (min === undefined || max === undefined) return undefined;
+  if (!Number.isInteger(min) || !Number.isInteger(max)) return undefined;
+  const span = max - min + 1;
+  if (span < 2 || span > RANGE_PICKER_MAX_VALUES) return undefined;
+  return Array.from({ length: span }, (_, i) => max - i);
+}
+
 /** Is this feature one a numeric range row is drawn for? */
 export function isRangeFeature(feature: FeatureDef): boolean {
   const type = featureType(feature);
@@ -190,6 +233,7 @@ export function buildRangeGroups(
         ? undefined
         : (str(config["postfix"]) ?? str(config["unit_m"]) ?? str(config["unit_i"])),
       step: feature !== undefined && featureType(feature) === "int" ? 1 : undefined,
+      picker: isCore ? undefined : pickerValues(feature, num(config["min"]), num(config["max"])),
       active: applied !== undefined,
       core: isCore,
       currency: isCore ? str(input.currency) : undefined,