@stapel/search-react 0.15.0 → 0.18.0

package/nav-manifest.json

@@ -1,6 +1,6 @@
 {
   "package": "@stapel/search-react",
-  "version": "0.15.0",
+  "version": "0.18.0",
   "entries": [
     {
       "id": "search.results",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stapel/search-react",
-  "version": "0.15.0",
+  "version": "0.18.0",
   "description": "Headless React pair for stapel-search: a typed query client, TanStack Query hooks, and a URL-first state codec that makes a search shareable by construction (filters, ranges, geo, sort and the keyset cursor all live in the query string). Drill-down facets rendered with their remaining counts and with the server's own honesty flags — approximate, skipped, degraded — never swallowed; keyset pagination with the window refusal named; DSA Art. 26 `promoted` marking carried into every card slot and the P2B Art. 5 ranking disclosure exposed as data. Zero visual opinion in the main entry; an opt-in /default subpath ships the antd skin, and /router binds the codec to react-router's useSearchParams.",
   "license": "MIT",
   "repository": {
@@ -57,9 +57,9 @@
       "limit": "11 KB"
     },
     {
-      "name": "default — the antd skin (query box + a typeahead that offers CATEGORY destinations with their live counts, filters incl. ranges/geo/category slots + the phone chip row with its leading category chip and the location summary row, results incl. the view switch, the card photo GALLERY as a SkinCarousel strip, the empty state's derived exits, ranking) must stay out of the main bundle",
+      "name": "default — the antd skin (query box + a typeahead that offers CATEGORY destinations with their live counts, filters incl. ranges/geo/category slots + the phone chip row with its leading category chip and the location summary row + the rail's evidence-ranked disclosure groups, panel search and sticky count/clear footer, results incl. the view switch, the card photo GALLERY as a SkinCarousel strip, the empty state's derived exits, ranking) must stay out of the main bundle",
       "path": "dist/default/index.js",
-      "limit": "21 KB"
+      "limit": "22 KB"
     },
     {
       "name": "router — the react-router binding is opt-in; the main entry must never pull a router",
@@ -115,12 +115,12 @@
     "size-limit": "^11.2.0",
     "typescript": "^5.8.3",
     "vitest": "^3.2.4",
-    "@stapel/core": "^0.22.0",
+    "@stapel/attributes-react": "^0.11.1",
+    "@stapel/core": "^0.23.1",
     "@stapel/image": "^0.4.2",
     "@stapel/showcase": "^0.3.0",
-    "@stapel/attributes-react": "^0.8.1",
-    "@stapel/tokens": "^0.6.0",
-    "@stapel/tokens-antd": "^0.11.0"
+    "@stapel/tokens": "^0.7.0",
+    "@stapel/tokens-antd": "^0.14.0"
   },
   "engines": {
     "node": ">=22"

package/src/analytics/generated/events.json

@@ -1,7 +1,7 @@
 {
   "$generated": "by scripts/gen-events.mjs — do not edit; drift-gated (pnpm gen:events:check)",
   "package": "@stapel/search-react",
-  "version": "0.15.0",
+  "version": "0.18.0",
   "defined": [],
   "flows": []
 }

package/src/api/generated/schema.ts

@@ -137,25 +137,29 @@ export interface components {
     schemas: {
         /** @description One destination in the dropdown, ready to render and ready to follow. */
         CategorySuggestion: {
-            /** @description Category id. */
+            /** @description Category id. A `listings`-graded row derives it from the path's leaf segment. */
             id: number;
-            /** @description Category slug. */
+            /** @description Category slug. Empty on a `listings`-graded row: no comm Function in the fleet resolves a path id to its slug or name yet. */
             slug: string;
-            /** @description The category's own display name. */
+            /** @description The category's own display name. On a `listings`-graded row this is the leaf id as a truthful segment — render such rows by their `count` instead. */
             name: string;
-            /** @description Display names root->leaf, e.g. ['Мужская одежда', 'Шорты']. This is what distinguishes three categories that share a name. */
+            /** @description Display names root->leaf, e.g. ['Мужская одежда', 'Шорты']. This is what distinguishes three categories that share a name. `listings`-graded rows carry the id segments here. */
             path: string[];
             /** @description The ancestry as ids joined with '/'. Pass it verbatim as the `category` parameter of /query — do not re-join path segments yourself. */
             category: string;
-            /** @description Live listings a buyer would see under this category, descendants included — the same number the SERP reports for it. */
+            /** @description Live listings a buyer would see under this category, descendants included — the same number the SERP reports for it. On a `listings`-graded row: how many of them match the typed query, which is the count a `?q=…&category=…` tap will show. */
             count: number;
             /** @description Number of segments in `path`. */
             depth: number;
             /**
-             * @description How the name matched. Informational; ranking is by `count`.
+             * @description How the row earned its place: the four name grades from `categories.suggest`, or `listings` — a goods-driven row, offered because documents matching the query live there even though no category name says the word. Ranking: strong grades (exact/prefix/word) and `listings` sort as one class above `substring`; within a class, stocked before empty, then grade, then count desc, then depth, then name. `vector` rows — embedding-space neighbours offered when nothing first-class matched — always sit below every deterministic row, ordered by similarity.
              *
+             *     * `exact` - exact
              *     * `prefix` - prefix
+             *     * `word` - word
              *     * `substring` - substring
+             *     * `listings` - listings
+             *     * `vector` - vector
              */
             match: components["schemas"]["MatchEnum"];
         };
@@ -175,6 +179,8 @@ export interface components {
             counted: string[];
             /** @description Plan slugs dropped at MAX_FACET_FIELDS — reported, not vanished. */
             skipped: string[];
+            /** @description `f.<slug>`/`r.<slug>` filters this answer did NOT apply, because the category marks the slug non-public (`FeatureDef.visibility` is `owner` or `staff`). A hidden value is not indexed and is not filterable: letting `?f.vin=<value>` through would make the index an exact-match oracle over an identifier. The answer is wider than what was asked for, and says so here rather than silently. */
+            dropped_filters: string[];
             /** @description Range slugs that address a core document column rather than an attribute (`r.price`). Offer them as filters unconditionally: they exist for every document in every category, which is why they are not in the category's own plan. */
             core_ranges: string[];
         };
@@ -191,11 +197,15 @@ export interface components {
             stale_reason?: string;
         };
         /**
-         * @description * `prefix` - prefix
+         * @description * `exact` - exact
+         *     * `prefix` - prefix
+         *     * `word` - word
          *     * `substring` - substring
+         *     * `listings` - listings
+         *     * `vector` - vector
          * @enum {string}
          */
-        MatchEnum: "prefix" | "substring";
+        MatchEnum: "exact" | "prefix" | "word" | "substring" | "listings" | "vector";
         /** @description The P2B Art. 5 disclosure, generated from the scorer registry. */
         RankingResponse: {
             doc_type: string;
@@ -283,7 +293,7 @@ export interface components {
             took_ms: number;
         };
         SuggestResponse: {
-            /** @description Destinations, ranked by live listing count desc, then depth, then name. */
+            /** @description Destinations, ranked by match class (strong name grades and goods-driven rows above substring), then stocked before empty, then grade, then live listing count desc, then depth, then name. */
             categories: components["schemas"]["CategorySuggestion"][];
             /** @description Title prefixes from the index. */
             terms: string[];
@@ -291,7 +301,7 @@ export interface components {
             items: string[];
             /** @description Which dictionary answered — the same resolution /query reports. */
             language: string;
-            /** @description What this answer could not do: `category_suggestions` (no provider for category names), `category_rollup` (no ancestry, so counts would read 0). */
+            /** @description What this answer could not do: `category_suggestions` (no provider for category names), `category_rollup` (no ancestry, so counts would read 0), `category_listing_suggestions` (no name matched and the configured engine does not implement the optional goods-driven verb, or it failed). */
             degraded: string[];
             backend: string;
         };

package/src/default/FacetGroupControl.tsx

@@ -31,6 +31,31 @@
  * A group with NO schema (the host passed no `categoryFeatures`, or the slug
  * is not in it) is a flat checkbox list — the honest default, and the shape
  * every group had before.
+ *
+ * ── The group can be a disclosure, and closed it is NOT in the DOM ─────────
+ *
+ * Measured on a live classified deployment's cars leaf at 1440×900: the 280px
+ * rail carried 5717px of content — 40 groups, 118 checkboxes, 66 fields — as
+ * one flat column. No amount of per-group folding fixes forty headings' worth
+ * of open controls, so the group itself can close: `collapsible` turns the
+ * label into a real `<button aria-expanded>` with a chevron and, when values
+ * are chosen inside, the count of them — the one fact a closed group owes its
+ * header. Closed means the options are not rendered at all: a hundred
+ * `display:none` checkboxes are still a hundred stops for a screen reader.
+ * Both props default to today's behaviour (always open, no disclosure), so no
+ * existing host changes; WHICH groups open is the panel's decision, not this
+ * component's — see `FacetPanelPane`.
+ *
+ * ── Uncounted options are the fold's tail, not the group's face ────────────
+ *
+ * The same walk found "not counted" printed 100+ times down the default view.
+ * The sentence is honest and it stays — but an option with no evidence behind
+ * it must not stand in front of one that has some, so options with
+ * `count: null` and nothing chosen sort AFTER every counted one and live
+ * behind the existing "Show all (N)" fold. A group whose options are ALL
+ * uncounted (a schema-only group — the server never counted the slug) keeps
+ * them visible as before: folding everything would leave a heading over
+ * nothing. Chosen options are always visible, wherever their count went.
  */
 import { useState } from "react";
 import type { CSSProperties, ReactElement } from "react";
@@ -114,28 +139,50 @@ export function facetGroupShape(group: FacetGroup): FacetGroupShape {
   return singleChoice(feature) ? "segmented" : "checkbox";
 }
 
+/**
+ * Is this node in the group's uncounted tail — an option with no evidence
+ * behind it AND no choice on it? Only meaningful in a group that has counted
+ * evidence at all: see {@link facetOptionNodes}.
+ */
+function uncountedUnchosen(node: FacetOptionNode): boolean {
+  return node.option.count === null && !node.option.selected;
+}
+
 /** The group's options in render order, carrying the depth the schema gives. */
 export function facetOptionNodes(group: FacetGroup): readonly FacetOptionNode[] {
+  let nodes: readonly FacetOptionNode[];
   if (facetGroupShape(group) !== "nested" || group.feature === undefined) {
-    return group.options.map((option) => ({ option, depth: 0 }));
-  }
-  const depths = optionDepths(featureConfig(group.feature)["options"]);
-  // Depth alone would leave children beside strangers: the options are
-  // re-ordered so each child follows its own parent, and a value the schema
-  // does not know keeps depth 0 rather than being hidden under someone.
-  const byValue = new Map(group.options.map((option) => [option.value, option]));
-  const out: FacetOptionNode[] = [];
-  const emitted = new Set<string>();
-  for (const [value, depth] of depths) {
-    const option = byValue.get(value);
-    if (option === undefined) continue;
-    out.push({ option, depth });
-    emitted.add(value);
-  }
-  for (const option of group.options) {
-    if (!emitted.has(option.value)) out.push({ option, depth: 0 });
+    nodes = group.options.map((option) => ({ option, depth: 0 }));
+  } else {
+    const depths = optionDepths(featureConfig(group.feature)["options"]);
+    // Depth alone would leave children beside strangers: the options are
+    // re-ordered so each child follows its own parent, and a value the schema
+    // does not know keeps depth 0 rather than being hidden under someone.
+    const byValue = new Map(group.options.map((option) => [option.value, option]));
+    const out: FacetOptionNode[] = [];
+    const emitted = new Set<string>();
+    for (const [value, depth] of depths) {
+      const option = byValue.get(value);
+      if (option === undefined) continue;
+      out.push({ option, depth });
+      emitted.add(value);
+    }
+    for (const option of group.options) {
+      if (!emitted.has(option.value)) out.push({ option, depth: 0 });
+    }
+    nodes = out;
   }
-  return out;
+
+  // An option nobody counted must not stand in front of one with evidence:
+  // the uncounted, unchosen tail sorts after everything else (stable — both
+  // halves keep their own order) and folds behind "Show all" in the
+  // component below. Only in a group that HAS counted evidence: a schema-only
+  // group is all `null`, and demoting all of it would reorder nothing while
+  // telling the fold to hide the entire group behind its own heading.
+  if (!group.options.some((option) => option.count !== null)) return nodes;
+  const tail = nodes.filter(uncountedUnchosen);
+  if (tail.length === 0) return nodes;
+  return [...nodes.filter((node) => !uncountedUnchosen(node)), ...tail];
 }
 
 /** A count, or the honest "we did not count this". Never a zero standing in
@@ -229,6 +276,57 @@ function OptionPill(props: {
   );
 }
 
+/**
+ * The disclosure header, as a NATIVE button with the chrome stripped.
+ *
+ * Native rather than antd's `Button`, because this is a heading that happens
+ * to toggle, not an action: it must inherit the heading's type and colour and
+ * sit flush with the group's left edge, and undoing a themed button's
+ * padding, border, background and hover for every surface it lands on is more
+ * style than the button brings. `aria-expanded` on a real `<button>` is the
+ * whole disclosure pattern; the chevron only draws what it already says.
+ */
+const DISCLOSURE_HEADER: CSSProperties = {
+  display: "flex",
+  alignItems: "center",
+  gap: spacing[1],
+  width: "100%",
+  padding: 0,
+  border: "none",
+  background: "none",
+  color: "inherit",
+  font: "inherit",
+  textAlign: "start",
+  cursor: "pointer",
+};
+
+/** The disclosure's state, drawn. Points down over a closed group ("there is
+ * more below") and flips once it is open. */
+function ChevronGlyph(props: { readonly open: boolean }): ReactElement {
+  return (
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      role="img"
+      aria-hidden="true"
+      focusable="false"
+      style={{
+        marginInlineStart: "auto",
+        flex: "0 0 auto",
+        ...(props.open ? { transform: "rotate(180deg)" } : {}),
+      }}
+    >
+      <path d="m6 9 6 6 6-6" />
+    </svg>
+  );
+}
+
 export interface FacetGroupControlProps {
   readonly group: FacetGroup;
   readonly onToggle: (slug: string, value: string) => void;
@@ -238,23 +336,48 @@ export interface FacetGroupControlProps {
   /** How many options before "Show all". Default {@link FACET_VISIBLE_OPTIONS};
    * `null` shows every option (a sheet devoted to one group has the room). */
   readonly visibleOptions?: number | null;
+  /**
+   * Make the group a disclosure: the heading becomes a real button and the
+   * options can leave the DOM entirely. Default `false` — today's always-open
+   * group, so no existing host changes. Meaningless with `heading: false`:
+   * a disclosure with no header is a group nothing can reopen.
+   */
+  readonly collapsible?: boolean;
+  /** Whether a `collapsible` group STARTS open. Default `true`. The initial
+   * value only — the person owns the state after the first click. */
+  readonly defaultOpen?: boolean;
 }
 
 export function FacetGroupControl(props: FacetGroupControlProps): ReactElement {
   const t = useT();
   const { group } = props;
   const [expanded, setExpanded] = useState(false);
+  const [openState, setOpenState] = useState(props.defaultOpen !== false);
   const shape = facetGroupShape(group);
   const nodes = facetOptionNodes(group);
 
+  const disclosure = props.collapsible === true && props.heading !== false;
+  const open = !disclosure || openState;
+
   const limit =
     props.visibleOptions === null
       ? null
       : (props.visibleOptions ?? FACET_VISIBLE_OPTIONS);
+  // The demoted tail `facetOptionNodes` sorted to the end: uncounted,
+  // unchosen options in a group that has counted evidence. They are ALWAYS
+  // behind the fold — the "one row over the limit" exemption below is about
+  // not hiding one counted row, and these rows say "not counted".
+  const demoted = group.options.some((option) => option.count !== null)
+    ? nodes.filter(uncountedUnchosen).length
+    : 0;
   // A group one row over the limit is not truncated: hiding a single option
   // behind "Show all (9)" costs a tap to reveal exactly one thing.
-  const collapsible = limit !== null && nodes.length > limit + 1;
-  const shown = collapsible && !expanded ? nodes.slice(0, limit) : nodes;
+  const folded =
+    limit !== null && (nodes.length > limit + 1 || demoted > 0);
+  const shown =
+    folded && !expanded
+      ? nodes.slice(0, Math.min(limit ?? nodes.length, nodes.length - demoted))
+      : nodes;
 
   return (
     <Flex
@@ -264,48 +387,82 @@ export function FacetGroupControl(props: FacetGroupControlProps): ReactElement {
       data-counted={group.counted ? "true" : "false"}
       data-shape={shape}
     >
-      {props.heading !== false && (
-        <Typography.Text strong>{group.label}</Typography.Text>
-      )}
+      {props.heading !== false &&
+        (disclosure ? (
+          <button
+            type="button"
+            style={DISCLOSURE_HEADER}
+            aria-expanded={open}
+            data-testid={`facet-toggle-${group.slug}`}
+            data-analytics="none"
+            data-analytics-reason="opening a filter group is a read, not a flow step"
+            onClick={() => {
+              setOpenState((was) => !was);
+            }}
+          >
+            <Typography.Text strong>{group.label}</Typography.Text>
+            {/* The one fact a closed group owes its header: how many of its
+                values are CHOSEN. Not the option count — that is what the
+                fold's own "Show all (N)" answers once the group is open. */}
+            {group.selected.length > 0 && (
+              <Typography.Text
+                type="secondary"
+                data-testid={`facet-toggle-count-${group.slug}`}
+              >
+                {group.selected.length}
+              </Typography.Text>
+            )}
+            <ChevronGlyph open={open} />
+          </button>
+        ) : (
+          <Typography.Text strong>{group.label}</Typography.Text>
+        ))}
 
-      {shape === "segmented" ? (
-        <Flex wrap gap={spacing[2]}>
-          {shown.map((node) => (
-            <OptionPill
-              key={node.option.value}
-              group={group}
-              option={node.option}
-              onToggle={props.onToggle}
-            />
-          ))}
-        </Flex>
-      ) : (
-        shown.map((node) => (
-          <CheckboxRow
-            key={node.option.value}
-            group={group}
-            node={node}
-            onToggle={props.onToggle}
-          />
-        ))
-      )}
+      {/* Closed means NOT RENDERED, not hidden: a hundred `display:none`
+          checkboxes are still a hundred stops for a screen reader, and the
+          measured rail held 118 of them. */}
+      {open && (
+        <>
+          {shape === "segmented" ? (
+            <Flex wrap gap={spacing[2]}>
+              {shown.map((node) => (
+                <OptionPill
+                  key={node.option.value}
+                  group={group}
+                  option={node.option}
+                  onToggle={props.onToggle}
+                />
+              ))}
+            </Flex>
+          ) : (
+            shown.map((node) => (
+              <CheckboxRow
+                key={node.option.value}
+                group={group}
+                node={node}
+                onToggle={props.onToggle}
+              />
+            ))
+          )}
 
-      {collapsible && (
-        <Button
-          type="link"
-          size="small"
-          style={{ alignSelf: "flex-start", paddingInline: 0 }}
-          data-testid={`facet-more-${group.slug}`}
-          data-analytics="none"
-          data-analytics-reason="expanding a filter group is a read, not a flow step"
-          onClick={() => {
-            setExpanded((was) => !was);
-          }}
-        >
-          {expanded
-            ? t(SEARCH_I18N_KEYS.facetsShowLess)
-            : t(SEARCH_I18N_KEYS.facetsShowAll, { count: nodes.length })}
-        </Button>
+          {folded && (
+            <Button
+              type="link"
+              size="small"
+              style={{ alignSelf: "flex-start", paddingInline: 0 }}
+              data-testid={`facet-more-${group.slug}`}
+              data-analytics="none"
+              data-analytics-reason="expanding a filter group is a read, not a flow step"
+              onClick={() => {
+                setExpanded((was) => !was);
+              }}
+            >
+              {expanded
+                ? t(SEARCH_I18N_KEYS.facetsShowLess)
+                : t(SEARCH_I18N_KEYS.facetsShowAll, { count: nodes.length })}
+            </Button>
+          )}
+        </>
       )}
     </Flex>
   );