@stapel/search-react 0.16.0 → 0.18.1

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"];
         };
@@ -193,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;
@@ -285,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[];
@@ -293,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>
   );