basalt-ui 1.27.0 → 1.29.0

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

@@ -1,4 +1,5 @@
 import type { ReactNode } from 'react';
+import type { BasaltProps } from '../common/props.js';
 import type { FieldHandle, NumberField } from '../state.js';
 /** One row of a numeric preset set. Narrower than `FilterOption` — a preset is never `disabled`:
  *  the set is declared at the call site, so a row that should not be offered is left out. */
@@ -6,7 +7,7 @@ export type NumberFilterOption = {
     readonly value: number;
     readonly label: string;
 };
-export type NumberFilterProps = {
+export type NumberFilterProps = BasaltProps & {
     readonly field: FieldHandle<NumberField>;
     /** The popover/sheet heading and the accessible name — never the pill text, which reads the
      *  VALUE (see `EnumFilter`'s doc for why a pill may only print what is selected). */
@@ -15,12 +16,13 @@ export type NumberFilterProps = {
     /** Present → the radio-list form. Absent → the stepper form. */
     readonly options?: readonly NumberFilterOption[];
     /**
-     * The stepper's increment. Ignored in the `options` form, which has no stepper.
+     * The stepper's increment, overriding the field's own. Ignored in the `options` form, which has
+     * no stepper.
      *
-     * @default 1 — and for an `int: true` field that is also the only sane grain, so it is what the
-     * field's own declaration produces without this prop.
+     * @default `field.step` — the field's declared grain, which is `1` for an `int: true` field that
+     * declared none. Absent on both, the input keeps Mantine's own default of 1.
      */
     readonly step?: number;
 };
-export declare function NumberFilter({ field, label, icon, options, step }: NumberFilterProps): ReactNode;
+export declare function NumberFilter(props: NumberFilterProps): ReactNode;
 //# sourceMappingURL=number-filter.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"number-filter.d.ts","sourceRoot":"","sources":["../../src/controls/number-filter.tsx"],"names":[],"mappings":"AAoDA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AACtC,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAQxD;6FAC6F;AAC7F,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB,CAAA;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,WAAW,CAAC,CAAA;IACxC;yFACqF;IACrF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAA;IACzB,gEAAgE;IAChE,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAA;IAChD;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CACvB,CAAA;AAED,wBAAgB,YAAY,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,iBAAiB,GAAG,SAAS,CAsBhG"}
+{"version":3,"file":"number-filter.d.ts","sourceRoot":"","sources":["../../src/controls/number-filter.tsx"],"names":[],"mappings":"AAwDA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AACtC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAElD,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AASxD;6FAC6F;AAC7F,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB,CAAA;AAED,MAAM,MAAM,iBAAiB,GAAG,WAAW,GAAG;IAC5C,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,WAAW,CAAC,CAAA;IACxC;yFACqF;IACrF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAA;IACzB,gEAAgE;IAChE,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAA;IAChD;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CACvB,CAAA;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,SAAS,CAmChE"}

package/dist/controls/number-filter.js

@@ -1,12 +1,18 @@
 import { jsx } from "react/jsx-runtime";
 import { NumberInput } from "@mantine/core";
 import { useEffect, useRef, useState } from "react";
+import { assertRequiredProps } from "../common/validate.js";
 import classes from "./controls.module.css";
 import { EnumFilter } from "./enum-filter.js";
 import { useFilterRegistration, useFilterSurface } from "./filter-context.js";
 import { FilterPill } from "./filter-pill.js";
-import { SheetField, useControlName } from "./filter-sheet.js";
-function NumberFilter({ field, label, icon, options, step }) {
+import { useControlName } from "./filter-sheet.js";
+import { PanelRow } from "./panel-row.js";
+function NumberFilter(props) {
+  assertRequiredProps("NumberFilter", props, ["field"], {
+    field: "bind it to a store field (`store.field.<name>`), never a value/onChange pair."
+  });
+  const { field, label, icon, options, step, className, style } = props;
   if (options !== void 0) {
     return /* @__PURE__ */ jsx(
       NumberChoice,
@@ -14,17 +20,22 @@ function NumberFilter({ field, label, icon, options, step }) {
         field,
         label,
         options,
-        ...icon !== void 0 && { icon }
+        ...icon !== void 0 && { icon },
+        ...className !== void 0 && { className },
+        ...style !== void 0 && { style }
       }
     );
   }
+  const grain = step ?? field.step;
   return /* @__PURE__ */ jsx(
     NumberStepper,
     {
       field,
       label,
       ...icon !== void 0 && { icon },
-      ...step !== void 0 && { step }
+      ...grain !== void 0 && { step: grain },
+      ...className !== void 0 && { className },
+      ...style !== void 0 && { style }
     }
   );
 }
@@ -32,7 +43,9 @@ function NumberChoice({
   field,
   label,
   icon,
-  options
+  options,
+  className,
+  style
 }) {
   const [value, setValue] = field.use();
   const rows = options.map((option) => ({ value: String(option.value), label: option.label }));
@@ -57,7 +70,9 @@ function NumberChoice({
       label,
       numeric: true,
       options: rows,
-      ...icon !== void 0 && { icon }
+      ...icon !== void 0 && { icon },
+      ...className !== void 0 && { className },
+      ...style !== void 0 && { style }
     }
   );
 }
@@ -65,7 +80,9 @@ function NumberStepper({
   field,
   label,
   icon,
-  step
+  step,
+  className,
+  style
 }) {
   const [value, setValue] = field.use();
   const surface = useFilterSurface();
@@ -74,7 +91,8 @@ function NumberStepper({
   useFilterRegistration(!isDefault, () => {
     field.clear();
   });
-  const { labelId, nameProps } = useControlName(label, inSheet);
+  const inPanel = surface === "panel";
+  const { labelId, nameProps } = useControlName(label, inSheet || inPanel);
   const draft = useCommittedNumber(value, setValue, { min: field.min, max: field.max });
   const input = /* @__PURE__ */ jsx(
     NumberInput,
@@ -84,7 +102,7 @@ function NumberStepper({
       ...field.min !== void 0 && { min: field.min },
       ...field.max !== void 0 && { max: field.max },
       ...field.int && { allowDecimal: false },
-      ...step !== void 0 ? { step } : field.int && { step: 1 },
+      ...step !== void 0 && { step },
       value: draft.value,
       onChange: draft.set,
       onBlur: draft.commit,
@@ -95,8 +113,17 @@ function NumberStepper({
       }
     }
   );
-  if (inSheet) {
-    return /* @__PURE__ */ jsx(SheetField, { label, labelId, children: input });
+  if (inPanel || inSheet) {
+    return /* @__PURE__ */ jsx(
+      PanelRow,
+      {
+        label,
+        labelId,
+        ...className !== void 0 && { className },
+        ...style !== void 0 && { style },
+        children: input
+      }
+    );
   }
   return /* @__PURE__ */ jsx(
     FilterPill,
@@ -105,6 +132,8 @@ function NumberStepper({
       numeric: true,
       active: !isDefault,
       ...icon !== void 0 && { icon },
+      ...className !== void 0 && { className },
+      ...style !== void 0 && { style },
       children: /* @__PURE__ */ jsx("div", { className: classes.optionList, children: input })
     }
   );

package/dist/controls/panel-row.d.ts

@@ -0,0 +1,132 @@
+import type { ReactNode, RefObject } from 'react';
+import type { BasaltProps } from '../common/props.js';
+/**
+ * Past three options a panel row's choice is a `Select`, not a track. Same arithmetic as
+ * `ViewTabs`' phone form, against the aside's ~300px rather than a phone's: a four-segment track at
+ * that width gives each label ~60px, which truncates every word longer than "Previous".
+ *
+ * **The count, not the whole law.** Three options at three WORDS' worth of label is not the same
+ * claim as three options at three SENTENCES' worth — "Same period last year" clipped mid-word
+ * inside its equal third even at a set of exactly three. `PANEL_TRACK_MAX` is the cheap first gate;
+ * `useTrackFits` (below) is the actual width check that decides whether the track renders at all.
+ */
+export declare const PANEL_TRACK_MAX = 3;
+export type PanelRowProps = BasaltProps & {
+    /** The row's name. Rendered above the control, `xs`/550 — never inside it. */
+    readonly label: string;
+    /** Info glyph + tooltip beside the label — the same affordance `WidgetHeader.info` draws. */
+    readonly hint?: string;
+    /**
+     * The current value, mono and right-aligned on the label line. A slider's readout, a range's
+     * resolved window — anything the control itself does not print.
+     */
+    readonly readout?: ReactNode;
+    /**
+     * A control that rides the LABEL line instead of taking one of its own — a `Switch`, and by
+     * design almost nothing else. Anything with a width belongs in `children`.
+     */
+    readonly end?: ReactNode;
+    /** Dims the row. The control inside keeps its own `disabled` — this is the visual half. */
+    readonly disabled?: boolean;
+    /**
+     * Stamped on the label so the control can point `aria-labelledby` at it. The CONTROL owns the id
+     * (it renders this row), so an id published downward could never reach it — see
+     * `useControlName`'s doc.
+     */
+    readonly labelId?: string;
+    /**
+     * When set, renders the label as a `<label htmlFor={htmlFor}>` instead of a bare `<span>`, so
+     * clicking the label text also activates the control — the affordance Mantine's own labelled
+     * inputs give for free. Pass the `end` control's id (a `Switch`, typically).
+     */
+    readonly htmlFor?: string;
+    /** The full-width control line. Omitted for a row whose control rides `end`. */
+    readonly children?: ReactNode;
+};
+export declare function PanelRow({ label, hint, readout, end, disabled, labelId, htmlFor, children, className, style, }: PanelRowProps): ReactNode;
+/** One option as both surfaces render it — `disabled` is the `SegmentedControl` half. */
+export type PanelChoiceOption = {
+    readonly value: string;
+    readonly label: string;
+    readonly disabled?: boolean;
+};
+export type PanelChoiceProps = {
+    /** The control's accessible name, as `useControlName` resolved it for this surface. */
+    readonly nameProps: {
+        'aria-labelledby': string;
+    } | {
+        'aria-label': string;
+    };
+    readonly value: string;
+    readonly options: readonly PanelChoiceOption[];
+    /** Numeric labels (`7d` / `30d`) get the mono treatment `segmented-control.module.css` owns. */
+    readonly numeric?: boolean;
+    readonly onChange: (next: string) => void;
+};
+/**
+ * Fit-checks a full-width track: {@link PANEL_TRACK_MAX} (and `ViewTabs`' own `PHONE_TRACK_MAX`) is
+ * the cheap COUNT gate, not the whole law — three short labels and three long ones are not the same
+ * claim at a ~300px column or a phone sheet ("Same period last year" clipped mid-word inside its
+ * equal third even though the set was exactly three; "Week"/"Absolute" clipped inside their equal
+ * column at the phone tier even though the ROOT read as fitting its parent — see
+ * {@link measureMounted}'s doc for why that needs a second signal). This hook is the width gate
+ * underneath the count cap, shared so `PanelChoice` and `ViewTabs`' phone form cannot drift the way
+ * their two hand-rolled ternaries already had once (`PanelChoice`'s own doc).
+ *
+ * **A LIVE toggle, not a one-way latch — it reverts.** The moment the track overflows, `PanelChoice`
+ * swaps it for a `Select`, which un-mounts the only element `measureMounted` could otherwise read.
+ * Two refs survive that swap on purpose: `trackWidthRef` remembers the track's own last-measured
+ * width (refreshed live whenever it IS mounted, used only as a cheap pre-filter — see below — never
+ * as the final answer), and `parentRef` holds the layout parent found once, at the FIRST mount — the
+ * same DOM node hosts either form (`PanelChoice`/`ViewTabs` return one or the other as their sole
+ * element, never a wrapper that differs between them), so it is never itself removed by the swap.
+ * The `ResizeObserver` therefore never watches a node this hook is about to lose: it observes the
+ * PARENT for the whole hook's lifetime and the TRACK only while it exists.
+ *
+ * While `Select` is showing, an observer tick with room to spare (`parent.clientWidth` at or past
+ * the remembered `trackWidthRef`) SPECULATIVELY re-mounts the track rather than trying to predict
+ * the exact threshold from a cached number — the two-signal check above cannot be run without a
+ * live root, and a WRONG guess here is not user-visible: the second effect below re-verifies with
+ * `measureMounted` the instant the fresh root exists, inside the SAME `useLayoutEffect` pass, and
+ * reverts synchronously before paint if the speculation was wrong. Nothing here can loop — a
+ * `ResizeObserver` only fires again on a GENUINE subsequent size change, not because React
+ * re-rendered.
+ *
+ * A SECOND, dependency-free `useLayoutEffect` is what performs that verification (and, on the
+ * ordinary growth-first-detected-while-mounted path, is also what re-arms the observer on the
+ * track's own root once it exists) — the FIRST effect only runs once per `[countFits, dataKey]`,
+ * but the track itself mounts and unmounts every time `fits` changes, and a `ResizeObserver` has to
+ * be told about each new node explicitly; this second effect runs after every render and is a
+ * no-op unless `rootRef.current` is a node it is not already watching.
+ *
+ * The check is THREE-VALUED, not two — `unknown` alongside `fits`/`overflow` — because a
+ * `clientWidth` of `0` is not evidence of overflow, it is evidence the ancestor chain has not been
+ * LAID OUT yet: the aside animates its width in from 0 while `PageAside` claims the region
+ * (`docs/ASIDE-SPEC.md` §0), and every ancestor up to the aside panel itself reads `0` for one or
+ * more layout passes while that transition is in flight. `unknown` updates nothing — it is simply
+ * not yet an answer, and the observer keeps watching for the ancestor chain to settle.
+ *
+ * `useLayoutEffect` runs BEFORE the browser paints, so a CONFIDENT overflow reading is never
+ * actually shown as a track first: the synchronous `setState` for it lands before paint, not after.
+ *
+ * `dataKey` is a caller-built string identifying the CURRENT option set (not read inside the effect
+ * body, just what forces it to re-run — a fresh mount, a fresh `parentRef`/`trackWidthRef` — when
+ * the rendered labels change) — primitive on purpose, so it is an honest `useLayoutEffect`
+ * dependency rather than a fresh array reference on every render.
+ */
+export declare function useTrackFits(countFits: boolean, dataKey: string): {
+    rootRef: RefObject<HTMLDivElement | null>;
+    fits: boolean;
+};
+/**
+ * The single-choice control a panel row draws: a full-width track while the set fits both
+ * {@link PANEL_TRACK_MAX} and the width check {@link useTrackFits} runs, a `Select` past either.
+ *
+ * Internal, and one component rather than the same ternary in each control: `EnumFilter` and
+ * `ViewTabs` both wrote it out and had already drifted — `ViewTabs`' copy lost `data-numeric`, so a
+ * numeric tab set rendered proportional in the aside and mono everywhere else. The split point is
+ * the geometry of a ~300px column, which is a property of the ROW, not of any one filter, so it
+ * belongs beside the row that imposes it.
+ */
+export declare function PanelChoice({ nameProps, value, options, numeric, onChange, }: PanelChoiceProps): ReactNode;
+//# sourceMappingURL=panel-row.d.ts.map

package/dist/controls/panel-row.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"panel-row.d.ts","sourceRoot":"","sources":["../../src/controls/panel-row.tsx"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAKlD;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,IAAI,CAAA;AAEhC,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG;IACxC,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,6FAA6F;IAC7F,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,CAAA;IAC5B;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,SAAS,CAAA;IACxB,2FAA2F;IAC3F,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAA;CAC9B,CAAA;AAED,wBAAgB,QAAQ,CAAC,EACvB,KAAK,EACL,IAAI,EACJ,OAAO,EACP,GAAG,EACH,QAAQ,EACR,OAAO,EACP,OAAO,EACP,QAAQ,EACR,SAAS,EACT,KAAK,GACN,EAAE,aAAa,GAAG,SAAS,CAiC3B;AAED,yFAAyF;AACzF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,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,gBAAgB,GAAG;IAC7B,uFAAuF;IACvF,QAAQ,CAAC,SAAS,EAAE;QAAE,iBAAiB,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,CAAA;IAC5E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,OAAO,EAAE,SAAS,iBAAiB,EAAE,CAAA;IAC9C,gGAAgG;IAChG,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CAC1C,CAAA;AAyDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,OAAO,EAClB,OAAO,EAAE,MAAM,GACd;IAAE,OAAO,EAAE,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CA0F9D;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,EAC1B,SAAS,EACT,KAAK,EACL,OAAO,EACP,OAAO,EACP,QAAQ,GACT,EAAE,gBAAgB,GAAG,SAAS,CAiC9B"}

package/dist/controls/panel-row.js

@@ -0,0 +1,173 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import { SegmentedControl, Select } from "@mantine/core";
+import { useLayoutEffect, useRef, useState } from "react";
+import { cx } from "../common/props.js";
+import { CtlSlot } from "../theme/index.js";
+import { InfoGlyph } from "../dashboard/widget-header.js";
+import classes from "./panel-row.module.css";
+const PANEL_TRACK_MAX = 3;
+function PanelRow({
+  label,
+  hint,
+  readout,
+  end,
+  disabled,
+  labelId,
+  htmlFor,
+  children,
+  className,
+  style
+}) {
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      className: cx(classes.row, className),
+      ...disabled === true && { "data-disabled": true },
+      ...style !== void 0 && { style },
+      children: /* @__PURE__ */ jsxs(CtlSlot, { children: [
+        /* @__PURE__ */ jsxs("div", { className: classes.head, children: [
+          htmlFor !== void 0 ? /* @__PURE__ */ jsx(
+            "label",
+            {
+              htmlFor,
+              className: classes.label,
+              ...labelId !== void 0 && { id: labelId },
+              children: label
+            }
+          ) : /* @__PURE__ */ jsx("span", { className: classes.label, ...labelId !== void 0 && { id: labelId }, children: label }),
+          hint !== void 0 && /* @__PURE__ */ jsx(InfoGlyph, { text: hint }),
+          readout !== void 0 && /* @__PURE__ */ jsx("span", { className: classes.readout, children: readout }),
+          end !== void 0 && /* @__PURE__ */ jsx("span", { className: classes.end, children: end })
+        ] }),
+        children !== void 0 && /* @__PURE__ */ jsx("div", { className: classes.control, children })
+      ] })
+    }
+  );
+}
+function layoutParent(el) {
+  let parent = el.parentElement;
+  while (parent !== null && getComputedStyle(parent).display === "contents") {
+    parent = parent.parentElement;
+  }
+  return parent;
+}
+const TRACK_LABEL_SELECTOR = ".mantine-SegmentedControl-label";
+function measureMounted(root, parent) {
+  if (parent.clientWidth === 0) return "unknown";
+  if (root.offsetWidth > parent.clientWidth) return "overflow";
+  const labels = root.querySelectorAll(TRACK_LABEL_SELECTOR);
+  for (const label of labels) {
+    if (label.scrollWidth > label.clientWidth) return "overflow";
+  }
+  return "fits";
+}
+function useTrackFits(countFits, dataKey) {
+  const rootRef = useRef(null);
+  const [rootFits, setRootFits] = useState(true);
+  const observerRef = useRef(null);
+  const parentRef = useRef(null);
+  const trackWidthRef = useRef(0);
+  const observedRootRef = useRef(null);
+  useLayoutEffect(() => {
+    if (!countFits) return;
+    const root = rootRef.current;
+    if (root === null) return;
+    const parent = layoutParent(root);
+    if (parent === null) return;
+    parentRef.current = parent;
+    trackWidthRef.current = root.offsetWidth;
+    const resolve = () => {
+      const p = parentRef.current;
+      if (p === null) return;
+      const liveRoot = rootRef.current;
+      if (liveRoot !== null) {
+        const result = measureMounted(liveRoot, p);
+        trackWidthRef.current = liveRoot.offsetWidth;
+        if (result === "unknown") return;
+        const fits = result === "fits";
+        setRootFits((current) => current === fits ? current : fits);
+        return;
+      }
+      if (p.clientWidth === 0 || trackWidthRef.current === 0) return;
+      if (p.clientWidth >= trackWidthRef.current) setRootFits(true);
+    };
+    if (typeof ResizeObserver === "undefined") {
+      resolve();
+      return;
+    }
+    const observer = new ResizeObserver(resolve);
+    observerRef.current = observer;
+    observer.observe(parent);
+    observer.observe(root);
+    observedRootRef.current = root;
+    resolve();
+    return () => {
+      observer.disconnect();
+      observerRef.current = null;
+      observedRootRef.current = null;
+    };
+  }, [countFits, dataKey]);
+  useLayoutEffect(() => {
+    const observer = observerRef.current;
+    const root = rootRef.current;
+    const parent = parentRef.current;
+    if (observer === null || root === null || observedRootRef.current === root) return;
+    if (observedRootRef.current !== null) observer.unobserve(observedRootRef.current);
+    observer.observe(root);
+    observedRootRef.current = root;
+    trackWidthRef.current = root.offsetWidth;
+    if (parent === null) return;
+    const result = measureMounted(root, parent);
+    if (result === "unknown") return;
+    const fits = result === "fits";
+    setRootFits((current) => current === fits ? current : fits);
+  });
+  return { rootRef, fits: countFits && rootFits };
+}
+function PanelChoice({
+  nameProps,
+  value,
+  options,
+  numeric,
+  onChange
+}) {
+  const data = options.map((option) => ({
+    value: option.value,
+    label: option.label,
+    disabled: option.disabled === true
+  }));
+  const countFits = options.length <= PANEL_TRACK_MAX;
+  const { rootRef, fits } = useTrackFits(countFits, data.map((d) => d.value).join("|"));
+  if (fits) {
+    return /* @__PURE__ */ jsx(
+      SegmentedControl,
+      {
+        ref: rootRef,
+        ...nameProps,
+        fullWidth: true,
+        value,
+        data,
+        ...numeric === true && { "data-numeric": true },
+        onChange
+      }
+    );
+  }
+  return /* @__PURE__ */ jsx(
+    Select,
+    {
+      ...nameProps,
+      value,
+      allowDeselect: false,
+      data,
+      onChange: (next) => {
+        if (next !== null) onChange(next);
+      }
+    }
+  );
+}
+export {
+  PANEL_TRACK_MAX,
+  PanelChoice,
+  PanelRow,
+  useTrackFits
+};

package/dist/controls/panel-row.module.css

@@ -0,0 +1,86 @@
+/*
+ * The `panel` surface's row skeleton (`docs/ASIDE-SPEC.md` §1, §3) — the inspector archetype's
+ * geometry, and nothing else.
+ *
+ * **Label ABOVE, never beside (G4).** At an aside's ~300px a label, a control and a readout on one
+ * line leave the control ~90px, which for a 20-step slider is under 12px per step. So the row is two
+ * lines: a head line (label · hint · readout, or label · a `Switch`) and a full-width control line.
+ * The toggle is the one exception, because a switch beside a label costs nothing and a switch on its
+ * own line reads as a second control.
+ *
+ * Rows separate with a `--vx-divider` hairline rather than sitting in cards — Lightroom, not a
+ * dashboard (`docs/ASIDE-SPEC.md` §3). The vertical inset is `--vx-space-row-inset-y` (6), the
+ * INSPECTOR row's, deliberately not `--vx-space-settings-row-inset-y` (10), which belongs to a
+ * settings FORM row and is nearly twice the height in a column that has none to spare.
+ */
+
+.row {
+  display: flex;
+  flex-direction: column;
+  gap: var(--vx-space-stack-xs, 0.25rem);
+  min-width: 0;
+  padding-block: var(--vx-space-row-inset-y);
+}
+
+/* Between rows only — never above the first or below the last, where the aside's own section
+ * chrome already draws the boundary. */
+.row + .row {
+  border-top: 1px solid var(--vx-divider);
+}
+
+/* `disabled` dims the BODY, it does not remove it: an inspector row that is off still states what it
+ * would control, and the control inside keeps its own `disabled` semantics. */
+.row[data-disabled] {
+  opacity: 0.55;
+}
+
+.head {
+  display: flex;
+  align-items: center;
+  gap: var(--vx-space-control-gap, 0.375rem);
+  min-width: 0;
+}
+
+.label {
+  font-size: var(--vx-text-xs);
+  font-weight: 550;
+  color: var(--vx-ink);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/*
+ * The readout is MONO and right-aligned: it is a number that changes while a thumb is dragged, and a
+ * proportional face would reflow the head line on every frame. `margin-inline-start: auto` is what
+ * pushes it (or, in a toggle row, the `end` control) to the trailing edge without a spacer element.
+ */
+.readout {
+  margin-inline-start: auto;
+  flex: none;
+  font-family: var(--basalt-font-mono);
+  font-size: var(--vx-text-xs);
+  font-variant-numeric: tabular-nums;
+  color: var(--vx-muted);
+}
+
+.end {
+  display: inline-flex;
+  align-items: center;
+  flex: none;
+  margin-inline-start: auto;
+}
+
+/* A readout AND an `end` control: the readout already took the auto margin, so the control just
+ * follows it across the gap. */
+.readout + .end {
+  margin-inline-start: 0;
+}
+
+/* Column flex, so a control with no width of its own fills the row rather than shrinking to its
+ * content — the row IS the width, which is why no control in it carries a `w` (law C5). */
+.control {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+}

package/dist/controls/panel-row.module.css.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Typed CSS-module declaration (the S4 CSS-modules path). Named string props — not an index
+ * signature — so dot access stays verbatim under the package's strict flags.
+ */
+declare const classes: {
+  readonly row: string
+  readonly head: string
+  readonly label: string
+  readonly readout: string
+  readonly end: string
+  readonly control: string
+}
+export default classes

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

@@ -1,4 +1,5 @@
 import type { ComponentType, ReactNode } from 'react';
+import type { BasaltProps } from '../common/props.js';
 import type { FieldHandle, RangeField } from '../state.js';
 /**
  * The contract a custom-range picker satisfies — `basalt-ui/controls-dates`' `DateRangePicker`, or a
@@ -16,7 +17,7 @@ export type RangeCustomPickerProps = {
     }) => void;
 };
 /** Everything about the props that does not depend on the field's `custom` flag. */
-type RangeFilterBase<P extends string, C extends boolean> = {
+type RangeFilterBase<P extends string, C extends boolean> = BasaltProps & {
     /**
      * A range handle from either store factory. Generic over the field's `custom` flag so a
      * `field.range({ ... })` WITHOUT `custom` (whose handle is `RangeField<P, false>`, and whose

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

@@ -1 +1 @@
-{"version":3,"file":"range-filter.d.ts","sourceRoot":"","sources":["../../src/controls/range-filter.tsx"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAc,MAAM,UAAU,CAAA;AAwCnE;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,CAAA;IACxF,QAAQ,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAA;CAChE,CAAA;AAED,oFAAoF;AACpF,KAAK,eAAe,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,OAAO,IAAI;IAC1D;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;IAC7C;qFACiF;IACjF,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAA;IACzB,yGAAyG;IACzG,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACxB,CAAA;AAED,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,OAAO,GAAG,OAAO,IAAI,eAAe,CAC3F,CAAC,EACD,CAAC,CACF,GAAG;IACF;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,aAAa,CAAC,sBAAsB,CAAC,CAAA;CAC9D,CAAA;AAED,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,OAAO,GAAG,OAAO,EACvE,KAAK,EAAE,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,GAC5B,SAAS,CAyGX"}
+{"version":3,"file":"range-filter.d.ts","sourceRoot":"","sources":["../../src/controls/range-filter.tsx"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAGlD,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAc,MAAM,UAAU,CAAA;AAsCnE;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,CAAA;IACxF,QAAQ,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAA;CAChE,CAAA;AAED,oFAAoF;AACpF,KAAK,eAAe,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,OAAO,IAAI,WAAW,GAAG;IACxE;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;IAC7C;qFACiF;IACjF,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAA;IACzB,yGAAyG;IACzG,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACxB,CAAA;AAED,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,OAAO,GAAG,OAAO,IAAI,eAAe,CAC3F,CAAC,EACD,CAAC,CACF,GAAG;IACF;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,aAAa,CAAC,sBAAsB,CAAC,CAAA;CAC9D,CAAA;AAED,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,OAAO,GAAG,OAAO,EACvE,KAAK,EAAE,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,GAC5B,SAAS,CA4IX"}