@stapel/search-react 0.42.0 → 0.42.2

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 { breakpoints, cssVar, spacing } from "@stapel/tokens";
+import { breakpoints, 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";
@@ -78,6 +78,11 @@ import type { SearchGeo } from "../api/types.js";
 import { buildRangeGroups } from "../state/ranges.js";
 import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
 import { useRailFits } from "./railFit.js";
+import {
+  RAIL_SCROLLBAR_CLASS,
+  RAIL_STYLE_HREF,
+  railScrollbarCss,
+} from "./scrollbar.js";
 import { FacetPanelPane } from "./FacetPanelPane.js";
 import type {
   CategoryFilterSlotProps,
@@ -267,14 +272,19 @@ export const FILTERS_RAIL_WIDTH = 280;
 export const RAIL_CLASS = "stapel-search-rail";
 
 /**
- * The class that carries the SKIN's scrollbar — present under
- * `railScrollbar: "styled"` and absent under `"system"`, so the two arms are
- * one class apart and a stand can read which one is on screen.
+ * The skin's scrollbar, which is no longer only the RAIL's — the dictionary
+ * facet inside the panel is a scroll port too, and it kept the platform's bar
+ * painted over its count column. The rule set, the class, the `href` and the
+ * track's width now live in `./scrollbar.ts` so both ports mount one hoisted
+ * sheet; they are re-exported here unchanged because they are this package's
+ * published surface.
  */
-export const RAIL_SCROLLBAR_CLASS = "stapel-search-rail-scrollbar";
-
-/** The `href` the hoisted rail sheet is deduplicated by. */
-export const RAIL_STYLE_HREF = "stapel-search-rail";
+export {
+  RAIL_SCROLLBAR_CLASS,
+  RAIL_SCROLLBAR_WIDTH,
+  RAIL_STYLE_HREF,
+  railScrollbarCss,
+} from "./scrollbar.js";
 
 /** Whose scrollbar the rail's own scroll port draws — see
  * {@link SearchPageProps.railScrollbar}. */
@@ -284,75 +294,6 @@ export type SearchRailScrollbar = "styled" | "system";
  * {@link SearchPageProps.railScroll}. */
 export type SearchRailScroll = "internal" | "page";
 
-/**
- * The scrollbar's track width, in CSS pixels.
- *
- * Not on the spacing scale on purpose, and not a spacing decision: this is the
- * thickness of a hairline instrument, the size every platform's own overlay
- * bar lands within, and the number the storefront's owner named. Six is thin
- * enough to read as part of the panel and thick enough to grab.
- */
-const RAIL_SCROLLBAR_WIDTH = 6;
-
-/**
- * The rail scrolls, and the bar that says so is the SKIN's, not the platform's.
- *
- * The system bar was never a decision — it is what an `overflow-y: auto` box
- * gets when nobody says otherwise, and on the storefront it landed as a grey
- * chrome-coloured strip standing next to the filters in a dark theme. What it
- * is replaced with:
- *
- *  - a 6px track with no arrows and no track fill — the rail's own hairline,
- *    not a widget;
- *  - a thumb that is TRANSPARENT at rest and appears on `:hover` of the rail
- *    (which is what a pointer scrolling inside it is doing) and on
- *    `:focus-within` (which is what a keyboard is doing). A coarse pointer
- *    fires neither, so under `(pointer: coarse)` the thumb stands — a touch
- *    surface with an invisible scrollbar is a rail with no sign it has a tail;
- *  - `scrollbar-gutter: stable`, so the panel's right edge does not move when
- *    the thumb arrives.
- *
- * Both vendor forms, because they are not alternatives: Firefox reads
- * `scrollbar-width`/`scrollbar-color` and nothing else, WebKit and Chromium
- * read the `::-webkit-scrollbar` pseudo-elements and (in Chromium) the
- * standard properties too.
- *
- * The colours are `--stapel-*` custom properties, which resolve per theme at
- * paint time — an inline colour or a `useToken()` value would freeze whichever
- * theme was mounted first. This design system's neutral vocabulary has no
- * `colorFill*` ramp of its own: `border` IS its tertiary-fill role (the
- * hairline every pane is separated by) and `text-subtle` is that role one step
- * stronger, which is what the thumb takes when a pointer is on the thumb
- * itself.
- *
- * 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 bar = `.${RAIL_SCROLLBAR_CLASS}`;
-  const size = `${String(RAIL_SCROLLBAR_WIDTH)}px`;
-  const thumb = cssVar("border");
-  const awake = `${bar}:hover,${bar}:focus-within`;
-  return [
-    // ── Firefox ────────────────────────────────────────────────────────────
-    `${bar}{scrollbar-width:thin;scrollbar-gutter:stable;` +
-      `scrollbar-color:transparent transparent}`,
-    `${awake}{scrollbar-color:${thumb} transparent}`,
-    // ── WebKit / Chromium ──────────────────────────────────────────────────
-    `${bar}::-webkit-scrollbar{inline-size:${size};block-size:${size}}`,
-    `${bar}::-webkit-scrollbar-track{background:transparent}`,
-    `${bar}::-webkit-scrollbar-thumb{background:transparent;` +
-      `border-radius:${cssVar("radius-full")}}`,
-    `${bar}:hover::-webkit-scrollbar-thumb,` +
-      `${bar}:focus-within::-webkit-scrollbar-thumb{background:${thumb}}`,
-    `${bar}::-webkit-scrollbar-thumb:hover{background:${cssVar("text-subtle")}}`,
-    // ── A surface with no hover at all ─────────────────────────────────────
-    `@media (pointer:coarse){${bar}{scrollbar-color:${thumb} transparent}` +
-      `${bar}::-webkit-scrollbar-thumb{background:${thumb}}}`,
-  ].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

package/src/default/SearchResultsPane.tsx

@@ -159,6 +159,35 @@ export const RESULTS_TOOLBAR_TOP_VAR = "--stapel-search-toolbar-top";
 /** The `href` the hoisted toolbar sheet is deduplicated by. */
 export const RESULTS_TOOLBAR_STYLE_HREF = "stapel-search-toolbar";
 
+/**
+ * THE LAYER A STICKY CHROME BAND PAINTS ON (D473).
+ *
+ * The row used to say `z-index: 1`, which is not a layer above the feed — it
+ * is a layer IN it. Measured on a live stand at 1440, scrolled 900px: a feed
+ * card's favourite overlay is `position: absolute; z-index: 2` and its photo
+ * counter is `z-index: 1`, so the heart painted over the pinned bar and the
+ * counter tied with it and won on document order. Reviewers read the same
+ * thing at 390, 768 and 1440 in both themes — a card's heart and its "1 of N"
+ * badge over the "105 listings / List / Sort" row, with the card underneath
+ * sliced mid-price.
+ *
+ * `20` is the fleet's existing number for exactly this shape: `listings-react`
+ * pins its condensed listing bar at `z-index: 20`, "above a page's own content
+ * and deliberately below the range a modal layer uses". `@stapel/tokens` ships
+ * NO z-index vocabulary (it carries colour roles, spacing, radii, breakpoints
+ * and type — no layering scale), so there is no role to read this from; the
+ * number is published here rather than written twice as a literal, and the two
+ * pins (the host's inline one and the default rule set) both read it, or they
+ * would drift into a bar that is over the feed on one arm and under it on the
+ * other.
+ *
+ * The ceiling is as load-bearing as the floor: `<PublicShell>`'s header is
+ * `z-index: 1000` and antd's popups start at `zIndexPopupBase` (1000), so the
+ * band has to stay well below both — a sort select must still open OVER its
+ * own bar, and the bar must still pass UNDER the header it is pinned beneath.
+ */
+export const RESULTS_TOOLBAR_Z_INDEX = 20;
+
 /**
  * The default pin's rule set.
  *
@@ -175,8 +204,9 @@ export function toolbarStickyCss(): string {
     `${bar}{position:sticky;top:var(${RESULTS_TOOLBAR_TOP_VAR},0px);` +
     // Over the cards, under the page's own chrome — and under antd's popups,
     // so the sort select still opens over its own bar. Opaque, or the cards
-    // scroll THROUGH the row.
-    `z-index:1;background:${cssVar("surface")}}}`
+    // scroll THROUGH the row. See {@link RESULTS_TOOLBAR_Z_INDEX} for why the
+    // layer is what it is.
+    `z-index:${String(RESULTS_TOOLBAR_Z_INDEX)};background:${cssVar("surface")}}}`
   );
 }
 
@@ -356,8 +386,9 @@ function toolbarPinStyle(pin: SearchToolbarPin | undefined): CSSProperties | und
     position: "sticky",
     top: pin.top ?? 0,
     // Over the cards, under the page's own chrome — and under antd's popups,
-    // so the sort select still opens over its own bar.
-    zIndex: 1,
+    // so the sort select still opens over its own bar. The SAME layer the
+    // default rule set uses — see {@link RESULTS_TOOLBAR_Z_INDEX}.
+    zIndex: RESULTS_TOOLBAR_Z_INDEX,
     // Opaque, or the cards scroll THROUGH the bar. The theme's own surface
     // role, resolved at paint time, so it follows the brand and the dark side
     // without a second colour being written here.

package/src/default/focusRing.ts

@@ -0,0 +1,100 @@
+/**
+ * A focus ring the KEYBOARD gets and the mouse does not.
+ *
+ * On a live storefront, clicking the "collapse" control under a facet group
+ * left a red outline standing around it until something else took focus. The
+ * ring itself is right — it is the design system's `:focus-visible` outline,
+ * and a keyboard must have it — but it was being drawn for a POINTER, which is
+ * the one modality that already knows where it clicked.
+ *
+ * ── Why `:focus-visible` alone is not the fix ─────────────────────────────
+ *
+ * The usual answer, "draw the ring on `:focus-visible` and not on `:focus`",
+ * was already true here: antd draws its button ring from
+ * `&:not(:disabled):focus-visible` and nothing in this pair or the storefront's
+ * sheet draws one on bare `:focus`. `:focus-visible` is a HEURISTIC, though,
+ * not a statement about the last input device: the engine may match it for a
+ * click when focus lands on an element whose surroundings have just changed
+ * under it — which is exactly what a disclosure toggle does to its own list.
+ * Suppressing the ring on `:focus:not(:focus-visible)` therefore fixes nothing
+ * on the very control that showed the defect.
+ *
+ * ── What this states instead ──────────────────────────────────────────────
+ *
+ * The modality, as a fact the control records for itself: a pointer press
+ * stamps `data-pointer-focus` on the element, and the first key it sees — or
+ * losing focus — clears it. The sheet then turns the ring OFF while that stamp
+ * is on, and leaves every other case to the design system. Tab to the control
+ * and the ring is there; click it and it is not; click it and then Tab back to
+ * it and it is there again, because the stamp died with the blur.
+ *
+ * The attribute is written straight to the node rather than held in state, on
+ * purpose: it is presentation the frame does not depend on, one control at a
+ * time, and a `useState` per facet button would re-render a rail of forty
+ * groups to paint an outline. React does not own this attribute, so nothing
+ * it renders fights over it.
+ *
+ * The class is doubled in the selector (`.c.c[…]`) for exactly one reason:
+ * specificity. antd's own ring is `.ant-btn:not(:disabled):focus-visible`
+ * (0,3,0); a single class plus the attribute plus the pseudo-class ties it, and
+ * a tie is settled by whichever stylesheet the engine saw last — which for a
+ * runtime CSS-in-JS design system is not a thing this pair gets to decide.
+ */
+import type { CSSProperties } from "react";
+
+/** The class the pointer-focus rule is hung on. */
+export const POINTER_FOCUS_CLASS = "stapel-search-pointer-focus";
+
+/** The attribute a pointer press stamps, and a key or a blur clears. */
+export const POINTER_FOCUS_ATTR = "data-pointer-focus";
+
+/** The `href` the hoisted focus sheet is deduplicated by (React 19). */
+export const POINTER_FOCUS_STYLE_HREF = "stapel-search-pointer-focus";
+
+/** See the module note. */
+export function pointerFocusCss(): string {
+  const c = `.${POINTER_FOCUS_CLASS}`;
+  return `${c}${c}[${POINTER_FOCUS_ATTR}]:focus-visible{outline:none;box-shadow:none}`;
+}
+
+/**
+ * The handlers a control spreads to opt into the rule above.
+ *
+ * Typed against the DOM rather than against React's synthetic event so the
+ * same object fits a native `<button>` and antd's `<Button>` — both forward
+ * these three props to the element, which is the only thing this needs.
+ */
+export interface PointerFocusProps {
+  readonly className: string;
+  readonly onPointerDown: (event: { currentTarget: Element }) => void;
+  readonly onKeyDown: (event: { currentTarget: Element }) => void;
+  readonly onBlur: (event: { currentTarget: Element }) => void;
+}
+
+/**
+ * Spread onto any control whose ring should be the keyboard's alone.
+ *
+ * A constant, not a hook: it closes over nothing, so one object serves every
+ * control in the tree and a facet group of forty rows allocates none.
+ */
+export const POINTER_FOCUS: PointerFocusProps = {
+  className: POINTER_FOCUS_CLASS,
+  onPointerDown: (event) => {
+    event.currentTarget.setAttribute(POINTER_FOCUS_ATTR, "");
+  },
+  onKeyDown: (event) => {
+    event.currentTarget.removeAttribute(POINTER_FOCUS_ATTR);
+  },
+  onBlur: (event) => {
+    event.currentTarget.removeAttribute(POINTER_FOCUS_ATTR);
+  },
+};
+
+/** {@link POINTER_FOCUS} with a className of the caller's own merged in. */
+export function pointerFocus(className: string): PointerFocusProps {
+  return { ...POINTER_FOCUS, className: `${className} ${POINTER_FOCUS_CLASS}` };
+}
+
+/** Nothing this module styles inline — exported so a host composing its own
+ * control can state the same intent without re-deriving the selector. */
+export const POINTER_FOCUS_NO_RING: CSSProperties = { outline: "none" };

package/src/default/index.ts

@@ -54,6 +54,21 @@ export {
   railStyle,
 } from "./SearchPage.js";
 export { RAIL_OFFSET_PROPERTY, useRailFits } from "./railFit.js";
+export {
+  RAIL_SCROLLBAR_WIDTH,
+  SCROLL_GUTTER_INLINE_END,
+  SCROLL_LIST_INSET_BLOCK_START,
+} from "./scrollbar.js";
+export {
+  POINTER_FOCUS,
+  POINTER_FOCUS_ATTR,
+  POINTER_FOCUS_CLASS,
+  POINTER_FOCUS_NO_RING,
+  POINTER_FOCUS_STYLE_HREF,
+  pointerFocus,
+  pointerFocusCss,
+} from "./focusRing.js";
+export type { PointerFocusProps } from "./focusRing.js";
 export type {
   SearchPageProps,
   SearchFiltersLayout,
@@ -91,6 +106,7 @@ export {
   RESULTS_TOOLBAR_STICKY_CLASS,
   RESULTS_TOOLBAR_STYLE_HREF,
   RESULTS_TOOLBAR_TOP_VAR,
+  RESULTS_TOOLBAR_Z_INDEX,
   resultsColumnsCss,
   toolbarRowMinHeight,
   toolbarStickyCss,
@@ -178,6 +194,7 @@ export {
   POPULAR_VALUES_COLUMNS,
   POPULAR_VALUES_LADDER,
   POPULAR_VALUES_LIMIT,
+  POPULAR_VALUES_MAX_COLUMNS,
   POPULAR_VALUES_STYLE_HREF,
   POPULAR_VALUE_COLUMN_WIDTH,
 } from "./PopularValues.js";

package/src/default/scrollbar.ts

@@ -0,0 +1,119 @@
+/**
+ * The skin's scrollbar — one rule set, for every scroll port this pair owns.
+ *
+ * It started as the rail's own: `<SearchPage>` replaced the platform bar
+ * standing next to the filters with a 6px hairline in the token palette. But
+ * the rail is not the only box in the panel that scrolls — a dictionary facet
+ * (the make axis, 418 car makes) is a scroll port INSIDE the rail, and kept the
+ * platform's bar: on the live storefront the system thumb was painted over the
+ * count column, so «Chery 5» read as «Chery» with the 5 under a grey strip.
+ *
+ * A box that scrolls owes the reader two things, and both are here:
+ *
+ *  - `scrollbar-gutter: stable`, so the space the bar needs is subtracted from
+ *    the CONTENT box rather than overlaid on it, and the box's right edge does
+ *    not move when the thumb arrives;
+ *  - a thumb that is the skin's — a 6px track with no arrows and no track
+ *    fill, transparent at rest, appearing on `:hover` (a pointer scrolling
+ *    inside it) and `:focus-within` (a keyboard), and standing permanently
+ *    under `(pointer: coarse)`, where neither fires and an invisible bar is a
+ *    box with no sign it has a tail.
+ *
+ * Both vendor forms, because they are not alternatives: Firefox reads
+ * `scrollbar-width`/`scrollbar-color` and nothing else, WebKit and Chromium
+ * read the `::-webkit-scrollbar` pseudo-elements and (in Chromium) the
+ * standard properties too.
+ *
+ * The colours are `--stapel-*` custom properties, which resolve per theme at
+ * paint time — an inline colour or a `useToken()` value would freeze whichever
+ * theme was mounted first. This design system's neutral vocabulary has no
+ * `colorFill*` ramp of its own: `border` IS its tertiary-fill role (the
+ * hairline every pane is separated by) and `text-subtle` is that role one step
+ * stronger, which is what the thumb takes when a pointer is on the thumb
+ * itself.
+ *
+ * Emitted as one hoisted `<style href precedence>` (React 19 dedupes by
+ * `href`), because a pseudo-element is unreachable from an inline style — so
+ * the rail and the dictionary list mount the SAME element, once, however many
+ * of each are on screen.
+ *
+ * The names still say "rail" and they stay that way: they are this package's
+ * published surface, and a hoisted sheet is identified by its `href`. Renaming
+ * them would break every host that reads the class to assert which bar is on
+ * screen, and would buy nothing but a tidier word.
+ */
+import type { CSSProperties } from "react";
+import { cssVar, spacing } from "@stapel/tokens";
+
+/**
+ * The class that carries the SKIN's scrollbar — present on the rail under
+ * `railScrollbar: "styled"` and absent under `"system"`, so the two arms are
+ * one class apart and a stand can read which one is on screen. Always present
+ * on a scroll port INSIDE the panel, which is not a surface a host chose.
+ */
+export const RAIL_SCROLLBAR_CLASS = "stapel-search-rail-scrollbar";
+
+/** The `href` the hoisted rail sheet is deduplicated by. */
+export const RAIL_STYLE_HREF = "stapel-search-rail";
+
+/**
+ * The scrollbar's track width, in CSS pixels.
+ *
+ * Not on the spacing scale on purpose, and not a spacing decision: this is the
+ * thickness of a hairline instrument, the size every platform's own overlay
+ * bar lands within, and the number the storefront's owner named. Six is thin
+ * enough to read as part of the panel and thick enough to grab.
+ */
+export const RAIL_SCROLLBAR_WIDTH = 6;
+
+/** See the module note. */
+export function railScrollbarCss(): string {
+  const bar = `.${RAIL_SCROLLBAR_CLASS}`;
+  const size = `${String(RAIL_SCROLLBAR_WIDTH)}px`;
+  const thumb = cssVar("border");
+  const awake = `${bar}:hover,${bar}:focus-within`;
+  return [
+    // ── Firefox ────────────────────────────────────────────────────────────
+    `${bar}{scrollbar-width:thin;scrollbar-gutter:stable;` +
+      `scrollbar-color:transparent transparent}`,
+    `${awake}{scrollbar-color:${thumb} transparent}`,
+    // ── WebKit / Chromium ──────────────────────────────────────────────────
+    `${bar}::-webkit-scrollbar{inline-size:${size};block-size:${size}}`,
+    `${bar}::-webkit-scrollbar-track{background:transparent}`,
+    `${bar}::-webkit-scrollbar-thumb{background:transparent;` +
+      `border-radius:${cssVar("radius-full")}}`,
+    `${bar}:hover::-webkit-scrollbar-thumb,` +
+      `${bar}:focus-within::-webkit-scrollbar-thumb{background:${thumb}}`,
+    `${bar}::-webkit-scrollbar-thumb:hover{background:${cssVar("text-subtle")}}`,
+    // ── A surface with no hover at all ─────────────────────────────────────
+    `@media (pointer:coarse){${bar}{scrollbar-color:${thumb} transparent}` +
+      `${bar}::-webkit-scrollbar-thumb{background:${thumb}}}`,
+  ].join("\n");
+}
+
+/**
+ * What a scroll port inside the panel reserves at its trailing edge.
+ *
+ * `scrollbar-gutter: stable` is the rule and the sheet above states it; this
+ * is the same number as a value, for the ROW to keep its last column clear of.
+ * `scrollbar-gutter` subtracts the gutter from the scroll container's content
+ * box, which is enough on every engine that honours it — and is ignored
+ * outright by Safari, where an overlay thumb still lands on top of whatever
+ * sits at the trailing edge. A count is the one thing in a facet row that
+ * lives there, so it carries the gutter as padding of its own: correct twice
+ * over on Chromium and Firefox, and the only thing standing between the number
+ * and the thumb on WebKit.
+ */
+export const SCROLL_GUTTER_INLINE_END: CSSProperties = {
+  paddingInlineEnd: RAIL_SCROLLBAR_WIDTH,
+};
+
+/**
+ * The top of a list that sits directly under a control.
+ *
+ * The dictionary list's first row was drawn flush against the box that filters
+ * it — at a glance the row read as clipped BY the input rather than as the
+ * first value under it. One step of the scale is the whole fix; it is stated
+ * here rather than inline so the rail's two scroll ports open the same way.
+ */
+export const SCROLL_LIST_INSET_BLOCK_START: number = spacing[1];