@stapel/search-react 0.3.1 → 0.7.0

package/src/state/ranges.ts

@@ -0,0 +1,144 @@
+/**
+ * The RANGE half of the filter model — `r.<slug>=from..to`.
+ *
+ * The codec has carried ranges since 0.1 (`setRangeValue`, `RANGE_PREFIX`) and
+ * nothing ever drew one: a marketplace shipped without a price filter because
+ * the panel only knew how to draw checkboxes. This module is the missing half:
+ * which slugs a range row exists for, and what the row is called.
+ *
+ * ── Where a range row comes from, and why it is not the response ───────────
+ *
+ * A facet answer (`facets: {slug: {value: count}}`) enumerates DISCRETE values;
+ * a range is not enumerable and the server never sends one. So the rows come
+ * from the CATEGORY SCHEMA — the same `categoryFeatures` slot that gives the
+ * checkboxes their labels — filtered to the numeric value types, plus every
+ * slug the URL already carries a range for.
+ *
+ * That last clause is the same rule `buildFacetGroups` follows for a filtered
+ * slug that fell out of the plan: a constraint that is ACTIVE must always have
+ * a control that removes it, even when the schema no longer explains it.
+ * Otherwise a shared link narrows the search with nothing on screen to widen it
+ * again.
+ *
+ * `date` is range-capable on the wire and is deliberately NOT here: a date
+ * range needs a date editor, the editor lives in `@stapel/attributes-react`'s
+ * registry, and a numeric input over a Unix timestamp would be worse than no
+ * control at all. The codec still round-trips one a host sets.
+ */
+import { featureConfig, featureName, featureType } from "@stapel/attributes-react";
+import type { FeatureDef } from "@stapel/attributes-react";
+import type { SearchQueryState, SearchRange } from "../api/types.js";
+
+/**
+ * Value types a numeric range row is drawn for (`config.type`, the
+ * stapel-attributes value-type slug).
+ */
+export const RANGE_FEATURE_TYPES: readonly string[] = [
+  "int",
+  "float",
+  "convertible_unit",
+];
+
+/** One `r.<slug>` row of the filter panel. */
+export interface RangeGroup {
+  readonly slug: string;
+  /** The feature's display name (translated when it is a key), else the slug. */
+  readonly label: string;
+  /** The schema entry behind the slug, when the host supplied one. */
+  readonly feature: FeatureDef | undefined;
+  /** The applied bounds, exactly as the URL carries them (strings — the wire
+   * never promised a number, and re-formatting one would rewrite the link). */
+  readonly from: string | undefined;
+  readonly to: string | undefined;
+  /** Bounds the schema declares, for the input's own limits. */
+  readonly min: number | undefined;
+  readonly max: number | undefined;
+  /** Unit suffix the schema declares (`postfix`, or a convertible unit). */
+  readonly unit: string | undefined;
+  /** `1` for an integer feature — a whole-number input for a whole number. */
+  readonly step: number | undefined;
+  /** Whether the URL currently constrains this slug. */
+  readonly active: boolean;
+}
+
+export interface BuildRangeGroupsInput {
+  readonly state: SearchQueryState;
+  readonly categoryFeatures?: readonly FeatureDef[];
+  /** Translator for label keys (the schema's `name` is often one). */
+  readonly t?: (key: string) => string;
+}
+
+function num(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function str(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function translate(t: ((key: string) => string) | undefined, key: string): string {
+  if (t === undefined) return key;
+  const resolved = t(key);
+  return resolved.length > 0 ? resolved : key;
+}
+
+/** Is this feature one a numeric range row is drawn for? */
+export function isRangeFeature(feature: FeatureDef): boolean {
+  const type = featureType(feature);
+  return type !== undefined && RANGE_FEATURE_TYPES.includes(type);
+}
+
+/**
+ * The range rows for the current search: every numeric feature of the
+ * category, in the schema's own order, plus any slug the URL constrains that
+ * the schema does not explain.
+ */
+export function buildRangeGroups(
+  input: BuildRangeGroupsInput
+): readonly RangeGroup[] {
+  const bySlug = new Map<string, FeatureDef>();
+  for (const feature of input.categoryFeatures ?? []) bySlug.set(feature.slug, feature);
+
+  const slugs: string[] = [];
+  for (const feature of input.categoryFeatures ?? []) {
+    if (isRangeFeature(feature)) slugs.push(feature.slug);
+  }
+  for (const slug of Object.keys(input.state.ranges)) {
+    if (!slugs.includes(slug)) slugs.push(slug);
+  }
+
+  return slugs.map((slug) => {
+    const feature = bySlug.get(slug);
+    const config = feature === undefined ? {} : featureConfig(feature);
+    const applied: SearchRange | undefined = input.state.ranges[slug];
+    return {
+      slug,
+      label:
+        feature === undefined ? slug : translate(input.t, featureName(feature)),
+      feature,
+      from: applied?.from,
+      to: applied?.to,
+      min: num(config["min"]),
+      max: num(config["max"]),
+      unit: str(config["postfix"]) ?? str(config["unit_m"]) ?? str(config["unit_i"]),
+      step: feature !== undefined && featureType(feature) === "int" ? 1 : undefined,
+      active: applied !== undefined,
+    };
+  });
+}
+
+/**
+ * Is a from/to pair one the server could ever match?
+ *
+ * `100..50` is syntactically fine and semantically empty, and the backend does
+ * not refuse it — it answers zero results, which reads as "there is nothing
+ * like this" rather than "you typed it backwards". So the panel refuses to
+ * apply it and says why, beside the button (`search.facets.range_invalid`).
+ */
+export function isRangeUsable(range: SearchRange): boolean {
+  if (range.from === undefined || range.to === undefined) return true;
+  const from = Number(range.from);
+  const to = Number(range.to);
+  if (!Number.isFinite(from) || !Number.isFinite(to)) return true;
+  return from <= to;
+}

package/dist/default/ErrorAlert.d.ts

@@ -1,9 +0,0 @@
-import type { CSSProperties, ReactElement, ReactNode } from "react";
-import type { FlowErrorDisplay } from "@stapel/core";
-export declare function ErrorAlert(props: {
-    error: FlowErrorDisplay | undefined;
-    style?: CSSProperties | undefined;
-    testId?: string | undefined;
-    action?: ReactNode;
-}): ReactElement | null;
-//# sourceMappingURL=ErrorAlert.d.ts.map

package/dist/default/ErrorAlert.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"ErrorAlert.d.ts","sourceRoot":"","sources":["../../src/default/ErrorAlert.tsx"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,wBAAgB,UAAU,CAAC,KAAK,EAAE;IAChC,KAAK,EAAE,gBAAgB,GAAG,SAAS,CAAC;IACpC,KAAK,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IAClC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB,GAAG,YAAY,GAAG,IAAI,CAsBtB"}

package/dist/default/ErrorAlert.js

@@ -1,27 +0,0 @@
-import { jsx as _jsx } from "react/jsx-runtime";
-/**
- * The one error surface this pair's default skin renders, so the split copy
- * core produces reaches a screen the same way everywhere (mirrors the
- * docs/notifications/workspaces etalon).
- *
- * Core's `describeFlowError` splits a failure into the sentence a person
- * reads and the technical detail a support agent quotes (owner report
- * 2026-08-09: the status used to be spliced into the sentence, ending in a
- * bare `" (500)"`). The split only helps if a skin renders both halves at
- * their own weights: `message` at normal weight, `detail` muted and small.
- *
- * `undefined` in — including a `detail` core left `undefined` because there
- * was nothing worth quoting — renders nothing rather than an empty line.
- */
-import { Alert, Typography } from "antd";
-export function ErrorAlert(props) {
-    const { error } = props;
-    if (!error)
-        return null;
-    return (_jsx(Alert, { type: "error", showIcon: true, ...(props.style ? { style: props.style } : {}), ...(props.testId ? { "data-testid": props.testId } : {}), ...(props.action ? { action: props.action } : {}), message: error.message, ...(error.detail
-            ? {
-                description: (_jsx(Typography.Text, { type: "secondary", style: { fontSize: 12 }, children: error.detail })),
-            }
-            : {}) }));
-}
-//# sourceMappingURL=ErrorAlert.js.map

package/dist/default/ErrorAlert.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"ErrorAlert.js","sourceRoot":"","sources":["../../src/default/ErrorAlert.tsx"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AAIzC,MAAM,UAAU,UAAU,CAAC,KAK1B;IACC,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC;IACxB,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,OAAO,CACL,KAAC,KAAK,IACJ,IAAI,EAAC,OAAO,EACZ,QAAQ,WACJ,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,KAC3C,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,KACrD,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAClD,OAAO,EAAE,KAAK,CAAC,OAAO,KAClB,CAAC,KAAK,CAAC,MAAM;YACf,CAAC,CAAC;gBACE,WAAW,EAAE,CACX,KAAC,UAAU,CAAC,IAAI,IAAC,IAAI,EAAC,WAAW,EAAC,KAAK,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,YACtD,KAAK,CAAC,MAAM,GACG,CACnB;aACF;YACH,CAAC,CAAC,EAAE,CAAC,GACP,CACH,CAAC;AACJ,CAAC"}

package/dist/default/theme.d.ts

@@ -1,24 +0,0 @@
-import type { CSSProperties, ReactElement, ReactNode } from "react";
-import type { ThemeMode } from "@stapel/tokens-antd";
-export interface SearchSkinThemeProps {
-    /**
-     * Light or dark. Defaults to the mode the host's document declares
-     * (`resolveThemeMode()`). Pass explicitly to pin a side.
-     */
-    readonly mode?: ThemeMode;
-    /** Extra styles merged onto the themed root element (layout only — colors
-     * come from the mode). */
-    readonly style?: CSSProperties;
-    readonly children: ReactNode;
-}
-/**
- * `<SearchSkinTheme/>` — the self-theming wrapper of
- * `@stapel/search-react/default`. Standalone use is supported (wrap any
- * composition of the skin's parts once); the shipped surfaces
- * (`SearchPage`, `SearchResultsPane`, `FacetPanelPane`,
- * `RankingDisclosurePane`) each already wrap themselves, and nested antd
- * `ConfigProvider`s merge, so composing them under one `SearchSkinTheme`
- * stays correct.
- */
-export declare function SearchSkinTheme(props: SearchSkinThemeProps): ReactElement;
-//# sourceMappingURL=theme.d.ts.map

package/dist/default/theme.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"theme.d.ts","sourceRoot":"","sources":["../../src/default/theme.tsx"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAOpE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC;IAC1B;8BAC0B;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;CAC9B;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB,GAAG,YAAY,CAmBzE"}

package/dist/default/theme.js

@@ -1,39 +0,0 @@
-import { jsx as _jsx } from "react/jsx-runtime";
-/**
- * The default skin's INTERNAL theme provider — every `/default` surface wraps
- * itself in this, so the skin is readable no matter what the host supplies
- * (tracker #26: a skin set with no internal provider once inherited a theme
- * bridge serving light-mode values inside a dark document — text on
- * background at 1.00:1). The theme derives from `@stapel/tokens` via
- * `@stapel/tokens-antd`'s `toAntdThemeConfig(mode)`; `mode` defaults to what
- * the HOST's document declares (`resolveThemeMode()` — the `data-theme`
- * attribute `tokens.css` keys its dark block on), never to a hardcoded side.
- *
- * This is also what "override styles" means for this pair: a storefront
- * retheming through the §68 token JSON regenerates its `--stapel-*` custom
- * properties and the result page follows with zero code — a far better deal
- * than a prop-per-colour API, and the reason the skin has none.
- */
-import { useMemo } from "react";
-import { ConfigProvider } from "antd";
-import { resolveThemeMode, toAntdTheme, toAntdThemeConfig, } from "@stapel/tokens-antd";
-/**
- * `<SearchSkinTheme/>` — the self-theming wrapper of
- * `@stapel/search-react/default`. Standalone use is supported (wrap any
- * composition of the skin's parts once); the shipped surfaces
- * (`SearchPage`, `SearchResultsPane`, `FacetPanelPane`,
- * `RankingDisclosurePane`) each already wrap themselves, and nested antd
- * `ConfigProvider`s merge, so composing them under one `SearchSkinTheme`
- * stays correct.
- */
-export function SearchSkinTheme(props) {
-    const mode = props.mode ?? resolveThemeMode();
-    const theme = useMemo(() => toAntdThemeConfig(mode), [mode]);
-    const token = useMemo(() => toAntdTheme(mode), [mode]);
-    return (_jsx(ConfigProvider, { theme: theme, children: _jsx("div", { "data-search-skin-root": true, "data-search-skin-mode": mode, style: {
-                color: token.colorText,
-                backgroundColor: token.colorBgContainer,
-                ...props.style,
-            }, children: props.children }) }));
-}
-//# sourceMappingURL=theme.js.map

package/dist/default/theme.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"theme.js","sourceRoot":"","sources":["../../src/default/theme.tsx"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAEhC,OAAO,EAAE,cAAc,EAAE,MAAM,MAAM,CAAC;AACtC,OAAO,EACL,gBAAgB,EAChB,WAAW,EACX,iBAAiB,GAClB,MAAM,qBAAqB,CAAC;AAe7B;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,KAA2B;IACzD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,IAAI,gBAAgB,EAAE,CAAC;IAC9C,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,iBAAiB,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;IAC7D,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;IACvD,OAAO,CACL,KAAC,cAAc,IAAC,KAAK,EAAE,KAAK,YAC1B,sEAEyB,IAAI,EAC3B,KAAK,EAAE;gBACL,KAAK,EAAE,KAAK,CAAC,SAAS;gBACtB,eAAe,EAAE,KAAK,CAAC,gBAAgB;gBACvC,GAAG,KAAK,CAAC,KAAK;aACf,YAEA,KAAK,CAAC,QAAQ,GACX,GACS,CAClB,CAAC;AACJ,CAAC"}

package/src/default/ErrorAlert.tsx

@@ -1,46 +0,0 @@
-/**
- * The one error surface this pair's default skin renders, so the split copy
- * core produces reaches a screen the same way everywhere (mirrors the
- * docs/notifications/workspaces etalon).
- *
- * Core's `describeFlowError` splits a failure into the sentence a person
- * reads and the technical detail a support agent quotes (owner report
- * 2026-08-09: the status used to be spliced into the sentence, ending in a
- * bare `" (500)"`). The split only helps if a skin renders both halves at
- * their own weights: `message` at normal weight, `detail` muted and small.
- *
- * `undefined` in — including a `detail` core left `undefined` because there
- * was nothing worth quoting — renders nothing rather than an empty line.
- */
-import { Alert, Typography } from "antd";
-import type { CSSProperties, ReactElement, ReactNode } from "react";
-import type { FlowErrorDisplay } from "@stapel/core";
-
-export function ErrorAlert(props: {
-  error: FlowErrorDisplay | undefined;
-  style?: CSSProperties | undefined;
-  testId?: string | undefined;
-  action?: ReactNode;
-}): ReactElement | null {
-  const { error } = props;
-  if (!error) return null;
-  return (
-    <Alert
-      type="error"
-      showIcon
-      {...(props.style ? { style: props.style } : {})}
-      {...(props.testId ? { "data-testid": props.testId } : {})}
-      {...(props.action ? { action: props.action } : {})}
-      message={error.message}
-      {...(error.detail
-        ? {
-            description: (
-              <Typography.Text type="secondary" style={{ fontSize: 12 }}>
-                {error.detail}
-              </Typography.Text>
-            ),
-          }
-        : {})}
-    />
-  );
-}

package/src/default/theme.tsx

@@ -1,66 +0,0 @@
-/**
- * The default skin's INTERNAL theme provider — every `/default` surface wraps
- * itself in this, so the skin is readable no matter what the host supplies
- * (tracker #26: a skin set with no internal provider once inherited a theme
- * bridge serving light-mode values inside a dark document — text on
- * background at 1.00:1). The theme derives from `@stapel/tokens` via
- * `@stapel/tokens-antd`'s `toAntdThemeConfig(mode)`; `mode` defaults to what
- * the HOST's document declares (`resolveThemeMode()` — the `data-theme`
- * attribute `tokens.css` keys its dark block on), never to a hardcoded side.
- *
- * This is also what "override styles" means for this pair: a storefront
- * retheming through the §68 token JSON regenerates its `--stapel-*` custom
- * properties and the result page follows with zero code — a far better deal
- * than a prop-per-colour API, and the reason the skin has none.
- */
-import { useMemo } from "react";
-import type { CSSProperties, ReactElement, ReactNode } from "react";
-import { ConfigProvider } from "antd";
-import {
-  resolveThemeMode,
-  toAntdTheme,
-  toAntdThemeConfig,
-} from "@stapel/tokens-antd";
-import type { ThemeMode } from "@stapel/tokens-antd";
-
-export interface SearchSkinThemeProps {
-  /**
-   * Light or dark. Defaults to the mode the host's document declares
-   * (`resolveThemeMode()`). Pass explicitly to pin a side.
-   */
-  readonly mode?: ThemeMode;
-  /** Extra styles merged onto the themed root element (layout only — colors
-   * come from the mode). */
-  readonly style?: CSSProperties;
-  readonly children: ReactNode;
-}
-
-/**
- * `<SearchSkinTheme/>` — the self-theming wrapper of
- * `@stapel/search-react/default`. Standalone use is supported (wrap any
- * composition of the skin's parts once); the shipped surfaces
- * (`SearchPage`, `SearchResultsPane`, `FacetPanelPane`,
- * `RankingDisclosurePane`) each already wrap themselves, and nested antd
- * `ConfigProvider`s merge, so composing them under one `SearchSkinTheme`
- * stays correct.
- */
-export function SearchSkinTheme(props: SearchSkinThemeProps): ReactElement {
-  const mode = props.mode ?? resolveThemeMode();
-  const theme = useMemo(() => toAntdThemeConfig(mode), [mode]);
-  const token = useMemo(() => toAntdTheme(mode), [mode]);
-  return (
-    <ConfigProvider theme={theme}>
-      <div
-        data-search-skin-root
-        data-search-skin-mode={mode}
-        style={{
-          color: token.colorText,
-          backgroundColor: token.colorBgContainer,
-          ...props.style,
-        }}
-      >
-        {props.children}
-      </div>
-    </ConfigProvider>
-  );
-}