basalt-ui 1.25.0 → 1.26.0

package/dist/controls/enum-filter.js

@@ -0,0 +1,91 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import { Button, Radio, Stack } from "@mantine/core";
+import classes from "./controls.module.css";
+import { useFilterRegistration, useFilterSurface } from "./filter-context.js";
+import { FilterPill } from "./filter-pill.js";
+import { SheetField, SheetOptionList, useControlName } from "./filter-sheet.js";
+function EnumFilter({
+  field,
+  label,
+  icon,
+  clearable,
+  options: optionsProp
+}) {
+  const [value, setValue] = field.use();
+  const surface = useFilterSurface();
+  const isDefault = field.isDefault(value);
+  useFilterRegistration(!isDefault, () => {
+    setValue(field.fallback);
+  });
+  const options = optionsProp ?? field.options;
+  const selected = options.find((option) => option.value === value);
+  const inSheet = surface === "sheet";
+  const { labelId } = useControlName(label, inSheet);
+  if (inSheet) {
+    return /* @__PURE__ */ jsx(SheetField, { label, labelId, children: /* @__PURE__ */ jsx(
+      SheetOptionList,
+      {
+        mode: "single",
+        labelId,
+        selected: [value],
+        options,
+        onToggle: (next) => {
+          setValue(next);
+        }
+      }
+    ) });
+  }
+  const body = (
+    // Mantine's OWN `label` prop, not an `aria-label`: `Radio.Group` overwrites both `aria-label`
+    // and `aria-labelledby` with its own `aria-labelledby` pointing at the `Input.Wrapper` label it
+    // renders — which, with no `label` passed, points at an element that does not exist. So the only
+    // way to name this group is to give it the label. It doubles as the heading in both surfaces:
+    // the group needs the FILTER's name ('Currency'), which the pill cannot supply because the pill
+    // reads the VALUE ('EUR') once set.
+    /* @__PURE__ */ jsxs(
+      Radio.Group,
+      {
+        label,
+        classNames: { label: classes.groupLabel },
+        value,
+        onChange: (next) => {
+          setValue(next);
+        },
+        children: [
+          /* @__PURE__ */ jsx(Stack, { gap: 2, children: options.map((option) => /* @__PURE__ */ jsx(
+            Radio,
+            {
+              value: option.value,
+              label: option.label,
+              ...option.disabled === true && { disabled: true }
+            },
+            option.value
+          )) }),
+          clearable === true && !isDefault && /* @__PURE__ */ jsx(
+            Button,
+            {
+              variant: "subtle",
+              size: "ctl",
+              onClick: () => {
+                setValue(field.fallback);
+              },
+              children: "Clear"
+            }
+          )
+        ]
+      }
+    )
+  );
+  return /* @__PURE__ */ jsx(
+    FilterPill,
+    {
+      label: selected?.label ?? label,
+      active: !isDefault,
+      ...icon !== void 0 && { icon },
+      children: /* @__PURE__ */ jsx("div", { className: classes.optionList, children: body })
+    }
+  );
+}
+export {
+  EnumFilter
+};

package/dist/controls/filter-context.d.ts

@@ -0,0 +1,55 @@
+import type { ReactNode } from 'react';
+/** Which form a control renders. Provided by `FilterSet`; `'pill'` when there is no `FilterSet`. */
+export type FilterSurface = 'pill' | 'sheet';
+/**
+ * The form this control should render — the ONE thing a control branches on.
+ *
+ * @example
+ * const surface = useFilterSurface()
+ * if (surface === 'sheet') return <SheetField label={label}>…</SheetField>
+ */
+export declare function useFilterSurface(): FilterSurface;
+/** What one filter reports about itself, keyed internally by a `useId()` per mount. */
+export type FilterRegistration = {
+    /** `!field.isDefault(value)` — the only input to `Filters (n)` and the pill's accent border. */
+    readonly isActive: boolean;
+    /** Writes the field back to its fallback. Called by `Reset all`. */
+    readonly reset: () => void;
+};
+type FilterRegistry = {
+    register(key: string, registration: FilterRegistration): void;
+    unregister(key: string): void;
+};
+export type FilterSetScopeProps = {
+    readonly surface: FilterSurface;
+    /** `null` on a second copy of the same children (the fold dropdown, the sheet). */
+    readonly registry: FilterRegistry | null;
+    readonly children: ReactNode;
+};
+/** Provides both contexts at once — every place FilterSet mounts children goes through this. */
+export declare function FilterSetScope({ surface, registry, children }: FilterSetScopeProps): ReactNode;
+/**
+ * Report this filter's active/reset state to the enclosing `FilterSet`. Call it unconditionally —
+ * it no-ops outside a registering scope (a bare filter with no `FilterSet`, the fold dropdown, the
+ * sheet), which is what keeps it hook-safe in every control.
+ *
+ * @example
+ * const [value, setValue] = field.use()
+ * useFilterRegistration(!field.isDefault(value), () => setValue(field.fallback))
+ */
+export declare function useFilterRegistration(isActive: boolean, reset: () => void): void;
+export type FilterCensus = {
+    readonly registry: FilterRegistry;
+    /** How many registered filters are non-default — `Filters (n)`. */
+    readonly activeCount: number;
+    /** Resets every registered filter. */
+    readonly resetAll: () => void;
+};
+/**
+ * The registry side, for `FilterSet` itself. The map is a ref (registration happens in children's
+ * effects, which must not re-render the parent mid-commit) and the COUNT is state, so only a real
+ * change in the count re-renders the bar.
+ */
+export declare function useFilterCensus(): FilterCensus;
+export {};
+//# sourceMappingURL=filter-context.d.ts.map

package/dist/controls/filter-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter-context.d.ts","sourceRoot":"","sources":["../../src/controls/filter-context.tsx"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEtC,oGAAoG;AACpG,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,OAAO,CAAA;AAI5C;;;;;;GAMG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,CAEhD;AAED,uFAAuF;AACvF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,gGAAgG;IAChG,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,MAAM,IAAI,CAAA;CAC3B,CAAA;AAED,KAAK,cAAc,GAAG;IACpB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,kBAAkB,GAAG,IAAI,CAAA;IAC7D,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B,CAAA;AAID,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAA;IAC/B,mFAAmF;IACnF,QAAQ,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAA;IACxC,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAA;CAC7B,CAAA;AAED,gGAAgG;AAChG,wBAAgB,cAAc,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE,mBAAmB,GAAG,SAAS,CAM9F;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,IAAI,GAAG,IAAI,CAkBhF;AAED,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAA;IACjC,mEAAmE;IACnE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,sCAAsC;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,CAAA;CAC9B,CAAA;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,YAAY,CAiC9C"}

package/dist/controls/filter-context.js

@@ -0,0 +1,69 @@
+import { jsx } from "react/jsx-runtime";
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState
+} from "react";
+const FilterSurfaceContext = createContext("pill");
+function useFilterSurface() {
+  return useContext(FilterSurfaceContext);
+}
+const FilterRegistryContext = createContext(null);
+function FilterSetScope({ surface, registry, children }) {
+  return /* @__PURE__ */ jsx(FilterSurfaceContext.Provider, { value: surface, children: /* @__PURE__ */ jsx(FilterRegistryContext.Provider, { value: registry, children }) });
+}
+function useFilterRegistration(isActive, reset) {
+  const registry = useContext(FilterRegistryContext);
+  const key = useId();
+  const resetRef = useRef(reset);
+  resetRef.current = reset;
+  const stableReset = useCallback(() => {
+    resetRef.current();
+  }, []);
+  useEffect(() => {
+    if (registry === null) return;
+    registry.register(key, { isActive, reset: stableReset });
+    return () => {
+      registry.unregister(key);
+    };
+  }, [registry, key, isActive, stableReset]);
+}
+function useFilterCensus() {
+  const entries = useRef(/* @__PURE__ */ new Map());
+  const [activeCount, setActiveCount] = useState(0);
+  const sync = useCallback(() => {
+    let next = 0;
+    for (const entry of entries.current.values()) {
+      if (entry.isActive) next += 1;
+    }
+    setActiveCount((current) => current === next ? current : next);
+  }, []);
+  const registry = useMemo(
+    () => ({
+      register(key, registration) {
+        entries.current.set(key, registration);
+        sync();
+      },
+      unregister(key) {
+        entries.current.delete(key);
+        sync();
+      }
+    }),
+    [sync]
+  );
+  const resetAll = useCallback(() => {
+    for (const entry of entries.current.values()) entry.reset();
+  }, []);
+  return { registry, activeCount, resetAll };
+}
+export {
+  FilterSetScope,
+  useFilterCensus,
+  useFilterRegistration,
+  useFilterSurface
+};

package/dist/controls/filter-pill.d.ts

@@ -0,0 +1,28 @@
+import type { ReactNode } from 'react';
+export type FilterPillProps = {
+    readonly label: string;
+    readonly icon?: ReactNode;
+    /** Non-default → accent-tinted border. Derived from `field.isDefault(value)`, never hand-set. */
+    readonly active?: boolean;
+    /** Mono label, for a numeric preset set (`7d` / `30d`) — the same law `[data-numeric]` applies
+     *  to a numeric SegmentedControl label (`theme/segmented-control.module.css`). */
+    readonly numeric?: boolean;
+    /** Popover body. Omit for a press-to-act pill. */
+    readonly children?: ReactNode;
+    readonly onClick?: () => void;
+    /** Accessible name when the visible label is a bare count (`+2`). */
+    readonly ariaLabel?: string;
+    /**
+     * `aria-pressed` for the press-to-act mode (`ToggleFilter`) — without it the on/off state is
+     * carried by a border colour and nothing else. Deliberately NOT set on a popover-target pill,
+     * where `aria-expanded` (which Mantine's `Popover.Target` supplies) is the correct state.
+     */
+    readonly pressed?: boolean;
+    readonly className?: string;
+    /** Set by `FilterSet` on its own fold/sheet pills; a filter never passes either of these. */
+    readonly hideGlyph?: boolean;
+    /** `data-shown` — the CSS hook that reveals the `+N` fold pill once folding is needed. */
+    readonly shown?: boolean;
+};
+export declare function FilterPill({ label, icon, active, numeric, children, onClick, ariaLabel, pressed, className, hideGlyph, shown, }: FilterPillProps): ReactNode;
+//# sourceMappingURL=filter-pill.d.ts.map

package/dist/controls/filter-pill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter-pill.d.ts","sourceRoot":"","sources":["../../src/controls/filter-pill.tsx"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAKtC,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAA;IACzB,iGAAiG;IACjG,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;IACzB;sFACkF;IAClF,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;IAC1B,kDAAkD;IAClD,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAA;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;IAC7B,qEAAqE;IACrE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,6FAA6F;IAC7F,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;IAC5B,0FAA0F;IAC1F,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CACzB,CAAA;AAED,wBAAgB,UAAU,CAAC,EACzB,KAAK,EACL,IAAI,EACJ,MAAM,EACN,OAAO,EACP,QAAQ,EACR,OAAO,EACP,SAAS,EACT,OAAO,EACP,SAAS,EACT,SAAS,EACT,KAAK,GACN,EAAE,eAAe,GAAG,SAAS,CA2D7B"}

package/dist/controls/filter-pill.js

@@ -0,0 +1,70 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import { Button, Popover } from "@mantine/core";
+import { useState } from "react";
+import { IconSlot } from "../theme/icon-slot.js";
+import classes from "./controls.module.css";
+import { UpDownGlyph } from "./glyphs.js";
+function FilterPill({
+  label,
+  icon,
+  active,
+  numeric,
+  children,
+  onClick,
+  ariaLabel,
+  pressed,
+  className,
+  hideGlyph,
+  shown
+}) {
+  const [opened, setOpened] = useState(false);
+  const target = /* @__PURE__ */ jsx(
+    Button,
+    {
+      variant: "default",
+      size: "ctl",
+      className: className === void 0 ? classes.pill : `${classes.pill} ${className}`,
+      classNames: { label: classes.pillLabel },
+      ...active === true && { "data-active": true },
+      ...numeric === true && { "data-numeric": true },
+      ...ariaLabel !== void 0 && { "aria-label": ariaLabel },
+      ...pressed !== void 0 && children === void 0 && { "aria-pressed": pressed },
+      ...shown === true && { "data-shown": true },
+      ...icon !== void 0 && {
+        // `IconSlot` owns the 16px box and the optical centring; `.pillIcon` adds only the pill's
+        // muted-then-ink colour law. A consumer's glyph can no longer set this row's height.
+        leftSection: /* @__PURE__ */ jsx(IconSlot, { className: classes.pillIcon, children: icon })
+      },
+      ...hideGlyph !== true && {
+        rightSection: /* @__PURE__ */ jsx(IconSlot, { className: classes.glyph, children: /* @__PURE__ */ jsx(UpDownGlyph, {}) })
+      },
+      onClick: onClick ?? (() => {
+        setOpened((current) => !current);
+      }),
+      children: label
+    }
+  );
+  if (children === void 0) return target;
+  return /* @__PURE__ */ jsxs(
+    Popover,
+    {
+      opened,
+      onChange: setOpened,
+      onDismiss: () => {
+        setOpened(false);
+      },
+      position: "bottom-start",
+      withinPortal: true,
+      shadow: "md",
+      radius: "sm",
+      trapFocus: true,
+      children: [
+        /* @__PURE__ */ jsx(Popover.Target, { children: target }),
+        /* @__PURE__ */ jsx(Popover.Dropdown, { className: classes.dropdown, children })
+      ]
+    }
+  );
+}
+export {
+  FilterPill
+};

package/dist/controls/filter-set.d.ts

@@ -0,0 +1,13 @@
+import type { ReactNode } from 'react';
+export type FilterSetProps = {
+    readonly children: ReactNode;
+    /**
+     * How many children stay inline pills below `sm`. The rest are reachable only through the
+     * `Filters (n)` sheet — which always holds every child, inline ones included.
+     *
+     * @default 1
+     */
+    readonly inline?: number;
+};
+export declare function FilterSet({ children, inline }: FilterSetProps): ReactNode;
+//# sourceMappingURL=filter-set.d.ts.map

package/dist/controls/filter-set.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter-set.d.ts","sourceRoot":"","sources":["../../src/controls/filter-set.tsx"],"names":[],"mappings":"AAkCA,OAAO,KAAK,EAAE,SAAS,EAAa,MAAM,OAAO,CAAA;AAYjD,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAA;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB,CAAA;AAED,wBAAgB,SAAS,CAAC,EAAE,QAAQ,EAAE,MAAU,EAAE,EAAE,cAAc,GAAG,SAAS,CAoF7E"}

package/dist/controls/filter-set.js

@@ -0,0 +1,125 @@
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { Children, isValidElement, useCallback, useEffect, useRef, useState } from "react";
+import classes from "./controls.module.css";
+import { FilterSetScope, useFilterCensus } from "./filter-context.js";
+import { FilterPill } from "./filter-pill.js";
+import { FilterSheet } from "./filter-sheet.js";
+import { FunnelGlyph } from "./glyphs.js";
+const FOLD_PILL_WIDTH = 52;
+const FALLBACK_GAP = 6;
+function FilterSet({ children, inline = 1 }) {
+  const items = Children.toArray(children);
+  const { registry, activeCount, resetAll } = useFilterCensus();
+  const [sheetOpened, setSheetOpened] = useState(false);
+  const rowRef = useRef(null);
+  const fit = useOverflowFit(rowRef, items.length);
+  const openSheet = useCallback(() => {
+    setSheetOpened(true);
+  }, []);
+  const closeSheet = useCallback(() => {
+    setSheetOpened(false);
+  }, []);
+  if (items.length === 0) return null;
+  const folded = items.slice(fit);
+  const anyFoldedOnMobile = items.length > inline;
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsxs("div", { className: classes.pillRow, ref: rowRef, "data-filter-row": true, children: [
+      /* @__PURE__ */ jsx(FilterSetScope, { surface: "pill", registry, children: items.map((child, index) => (
+        // `Children.toArray` already stamped a stable `.0`/`.1`-style key on every child, so
+        // the slot wrapper reuses it rather than inventing an array-index key.
+        /* @__PURE__ */ jsx(
+          "div",
+          {
+            className: classes.pillSlot,
+            "data-filter-slot": true,
+            ...index < inline && { "data-inline": true },
+            ...index >= fit && { "data-folded": true },
+            children: child
+          },
+          slotKey(child, index)
+        )
+      )) }),
+      /* @__PURE__ */ jsx(
+        FilterPill,
+        {
+          label: `+${folded.length}`,
+          ariaLabel: `${folded.length} more filters`,
+          className: classes.foldPill,
+          hideGlyph: true,
+          shown: folded.length > 0,
+          children: /* @__PURE__ */ jsx("div", { className: classes.optionList, children: /* @__PURE__ */ jsx(FilterSetScope, { surface: "sheet", registry: null, children: folded }) })
+        }
+      ),
+      anyFoldedOnMobile && /* @__PURE__ */ jsx(
+        FilterPill,
+        {
+          label: activeCount > 0 ? `Filters (${activeCount})` : "Filters",
+          active: activeCount > 0,
+          icon: /* @__PURE__ */ jsx(FunnelGlyph, {}),
+          className: classes.sheetPill,
+          hideGlyph: true,
+          onClick: openSheet
+        }
+      )
+    ] }),
+    anyFoldedOnMobile && /* @__PURE__ */ jsx(FilterSheet, { opened: sheetOpened, onClose: closeSheet, onResetAll: resetAll, children: /* @__PURE__ */ jsx(FilterSetScope, { surface: "sheet", registry: null, children: items }) })
+  ] });
+}
+function useOverflowFit(rowRef, count) {
+  const [fit, setFit] = useState(count);
+  const widths = useRef([]);
+  useEffect(() => {
+    const row = rowRef.current;
+    if (row === null) return;
+    if (typeof ResizeObserver === "undefined") {
+      setFit(count);
+      return;
+    }
+    const measure = () => {
+      const slots = [...row.querySelectorAll("[data-filter-slot]")];
+      slots.forEach((slot, index) => {
+        const width = slot.offsetWidth;
+        if (width > 0) widths.current[index] = width;
+      });
+      const available = row.clientWidth;
+      if (available <= 0) {
+        setFit(count);
+        return;
+      }
+      const gap = readGap(row);
+      const bare = fitCount(widths.current, count, gap, available, 0);
+      setFit(
+        bare === count ? count : fitCount(widths.current, count, gap, available, FOLD_PILL_WIDTH)
+      );
+    };
+    measure();
+    const observer = new ResizeObserver(measure);
+    observer.observe(row);
+    for (const slot of row.querySelectorAll("[data-filter-slot]")) {
+      observer.observe(slot);
+    }
+    return () => {
+      observer.disconnect();
+    };
+  }, [rowRef, count]);
+  return fit;
+}
+function fitCount(widths, count, gap, available, reserve) {
+  let used = reserve === 0 ? 0 : reserve + gap;
+  for (let index = 0; index < count; index += 1) {
+    used += (index === 0 ? 0 : gap) + (widths[index] ?? 0);
+    if (used > available) return index;
+  }
+  return count;
+}
+function slotKey(child, index) {
+  if (isValidElement(child) && child.key !== null) return child.key;
+  return String(index);
+}
+function readGap(row) {
+  const parsed = Number.parseFloat(getComputedStyle(row).columnGap);
+  return Number.isFinite(parsed) ? parsed : FALLBACK_GAP;
+}
+export {
+  FilterSet
+};

package/dist/controls/filter-set.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=filter-set.test.d.ts.map

package/dist/controls/filter-set.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter-set.test.d.ts","sourceRoot":"","sources":["../../src/controls/filter-set.test.tsx"],"names":[],"mappings":""}

package/dist/controls/filter-sheet.d.ts

@@ -0,0 +1,117 @@
+import type { ReactNode } from 'react';
+export type FilterSheetProps = {
+    readonly opened: boolean;
+    readonly onClose: () => void;
+    readonly onResetAll: () => void;
+    readonly title?: string;
+    readonly children: ReactNode;
+};
+/**
+ * `Reset all` rides the HEADER, beside the title and the close ×, not a footer.
+ *
+ * A bottom drawer's footer is the one region a phone cannot promise is on screen: the sheet grows
+ * with its content, so with six filters open the reset button sat below the fold and the only way to
+ * reach it was to scroll past every row it would have undone. The header is fixed by construction.
+ * It also removes the sheet's last horizontal rule — a footer needs separating from the rows above
+ * it, a header does not (`docs/CONTROLS-SPEC.md` §2.1: hairlines between OPTION rows only).
+ */
+export declare function FilterSheet({ opened, onClose, onResetAll, title, children, }: FilterSheetProps): ReactNode;
+/** One row of a {@link SheetOptionList}. */
+export type SheetOption = {
+    readonly value: string;
+    readonly label: string;
+    readonly disabled?: boolean;
+};
+export type SheetOptionListProps = {
+    /** `single` renders radio semantics, `multi` checkbox semantics. */
+    readonly mode: 'single' | 'multi';
+    /** The selected value(s) — a one-element array in `single` mode. */
+    readonly selected: readonly string[];
+    readonly options: readonly SheetOption[];
+    readonly onToggle: (value: string) => void;
+    /** The `SheetField` heading this list is named by. */
+    readonly labelId: string;
+};
+/**
+ * The sheet's ONE list form (`docs/CONTROLS-SPEC.md` §2.1): every option is a 44px full-width row,
+ * label left, a check at the trailing edge when selected, a 1px hairline between rows and nowhere
+ * else.
+ *
+ * **It replaced a `SegmentedControl` and a Mantine `Radio` list, for two different reasons.** The
+ * range presets rendered as a `orientation="vertical"` SegmentedControl, which in a full-width sheet
+ * is a stack of left-aligned labels inside a tinted track — it read as a broken control, not as a
+ * choice, and it carried the track's own inset so it aligned with nothing else in the sheet. The
+ * enum/multi filters rendered Mantine `Radio`/`Checkbox` rows, which put a 20px dot or box in the
+ * leading position of every row; at six filters the sheet was a column of controls rather than a
+ * column of options, and the leading marks pushed every label off the sheet's own text column.
+ *
+ * The semantics are a real native `<input>` inside the row's `<label>`, visually hidden — not
+ * `role="radio"` on a div. A hidden native input keeps the arrow-key group behaviour, the
+ * form-association and the announced state for free, and `<label>` wrapping it makes the whole 44px
+ * box the hit target (C15) without a single `onClick` on a non-interactive element.
+ */
+export declare function SheetOptionList({ mode, selected, options, onToggle, labelId, }: SheetOptionListProps): ReactNode;
+export type SheetDisclosureProps = {
+    readonly label: string;
+    readonly expanded: boolean;
+    readonly onToggle: () => void;
+    readonly children: ReactNode;
+};
+/**
+ * A 44px row that expands its own body inline — the sheet's answer to a control too large to sit in
+ * the list unconditionally (`RangeFilter`'s custom date picker, which is a whole calendar). Same row
+ * geometry as a {@link SheetOptionList} option, so the disclosure reads as the list's last entry
+ * rather than as a different kind of thing.
+ */
+export declare function SheetDisclosure({ label, expanded, onToggle, children, }: SheetDisclosureProps): ReactNode;
+export type SheetFieldProps = {
+    readonly label: string;
+    /** Stamped on the heading so a control can point `aria-labelledby` at it — see `useControlName`. */
+    readonly labelId?: string;
+    readonly children: ReactNode;
+};
+/** A labelled block inside the sheet — the sheet form's outer shell for every control. */
+export declare function SheetField({ label, labelId, children }: SheetFieldProps): ReactNode;
+/**
+ * Names a control that has no VISIBLE Mantine `label`, and does it differently per surface — which
+ * is the whole reason this is one helper instead of an `aria-label` sprinkled per call site.
+ *
+ * In the SHEET the visible `SheetField` heading is right there, so the control points at it
+ * (`aria-labelledby`) and the heading stops being decoration. In the PILL surface there is no
+ * visible name to point at — the pill text is the VALUE (`EUR`, `30d`, `3 channels`) — so the
+ * control carries the filter's own name instead. Either way the announced name is what is being
+ * filtered, not what it currently holds.
+ *
+ * The id is generated by the CONTROL, not by `SheetField`, because the control renders its own
+ * `SheetField`: an id published downward through context could never reach the sibling that needs it.
+ *
+ * @example
+ * const { labelId, nameProps } = useControlName(label, inSheet)
+ * <Radio.Group {...nameProps} …/>
+ * // and, in the sheet branch: <SheetField label={label} labelId={labelId}>…</SheetField>
+ */
+export declare function useControlName(label: string, inSheet: boolean): {
+    labelId: string;
+    nameProps: {
+        'aria-labelledby': string;
+    } | {
+        'aria-label': string;
+    };
+};
+export type SheetRowProps = {
+    readonly children: ReactNode;
+};
+/** One 44px full-width row (`--vx-space-sheet-row-height`). */
+export declare function SheetRow({ children }: SheetRowProps): ReactNode;
+/** The class every sheet-form list item shares, for controls that render their own row element. */
+export declare const sheetRowClass: string;
+/**
+ * `classNames` for a Radio/Checkbox/Switch rendered as a sheet row — stretches its `body` and
+ * `<label>` across the full 44px so the whole row is the touch target, not the middle 20px of it.
+ */
+export declare const sheetRowClassNames: {
+    readonly root: string;
+    readonly body: string;
+    readonly label: string;
+};
+//# sourceMappingURL=filter-sheet.d.ts.map

package/dist/controls/filter-sheet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter-sheet.d.ts","sourceRoot":"","sources":["../../src/controls/filter-sheet.tsx"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAGtC,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAA;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,IAAI,CAAA;IAC/B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAA;CAC7B,CAAA;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,EAC1B,MAAM,EACN,OAAO,EACP,UAAU,EACV,KAAiB,EACjB,QAAQ,GACT,EAAE,gBAAgB,GAAG,SAAS,CAoB9B;AAqBD,4CAA4C;AAC5C,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAC5B,CAAA;AAED,MAAM,MAAM,oBAAoB,GAAG;IACjC,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAA;IACjC,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC,QAAQ,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,CAAA;IACxC,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IAC1C,sDAAsD;IACtD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB,CAAA;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,EAC9B,IAAI,EACJ,QAAQ,EACR,OAAO,EACP,QAAQ,EACR,OAAO,GACR,EAAE,oBAAoB,GAAG,SAAS,CA+ClC;AAED,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,CAAA;IAC7B,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAA;CAC7B,CAAA;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,EAC9B,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,QAAQ,GACT,EAAE,oBAAoB,GAAG,SAAS,CAoBlC;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,oGAAoG;IACpG,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAA;CAC7B,CAAA;AAED,0FAA0F;AAC1F,wBAAgB,UAAU,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,eAAe,GAAG,SAAS,CASnF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,OAAO,GACf;IACD,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE;QAAE,iBAAiB,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,CAAA;CACpE,CAMA;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAA;CAC7B,CAAA;AAED,+DAA+D;AAC/D,wBAAgB,QAAQ,CAAC,EAAE,QAAQ,EAAE,EAAE,aAAa,GAAG,SAAS,CAE/D;AAED,mGAAmG;AACnG,eAAO,MAAM,aAAa,QAAmB,CAAA;AAE7C;;;GAGG;AACH,eAAO,MAAM,kBAAkB;;;;CAIrB,CAAA"}