basalt-ui 1.25.0 → 1.26.0

package/dist/controls/actions.d.ts

@@ -0,0 +1,169 @@
+import type { ReactNode } from 'react';
+import type { NavAnchor } from '../nav/types.js';
+import type { AnyNavLink } from '../router-tanstack/nav.js';
+/**
+ * A button-shaped action. `Anchor` is the router seam basalt HOSTS (the same seam `SidebarItem`
+ * uses — pass the one `useNav` builds, or your router's `Link`); `link` is the no-router fallback
+ * and only its `to` is honoured, since resolving `search`/`params` needs a router. Supply `Anchor`
+ * whenever the destination carries either.
+ */
+export type BarActionItem = {
+    key: string;
+    label: string;
+    kind?: undefined;
+    icon?: ReactNode;
+    onClick?: () => void;
+    link?: AnyNavLink;
+    Anchor?: NavAnchor;
+    disabled?: boolean;
+    loading?: boolean;
+    danger?: boolean;
+    /**
+     * Joins this action to its adjacent `group: true` siblings into ONE `ControlGroup` — shared
+     * borders, radius on the outer ends only, no gap. Declare it on every member of the run: a set of
+     * three where the middle one omits it is two runs of one, which is the same row it was before.
+     *
+     * It is an opt-in because "these act on the same thing" is a fact only the caller has. A `‹ Today ›`
+     * stepper is the shape; three independent actions that happen to sit beside each other are not, and
+     * joining those would claim a relationship the reader would then have to un-learn.
+     */
+    group?: true;
+    /** Mobile placement. @default 'bar' for `primary`, `'more'` for everything else */
+    mobile?: 'bar' | 'more' | 'hidden';
+};
+/** A nested group. Always folds into the `More` menu on both viewports — it never takes bar width. */
+export type BarActionMenu = {
+    key: string;
+    kind: 'menu';
+    label: string;
+    icon?: ReactNode;
+    items: BarAction[];
+};
+/** An escape hatch for a control basalt does not model (a live chip, a consumer's own widget). */
+export type BarActionCustom = {
+    key: string;
+    kind: 'custom';
+    node: ReactNode;
+    mobile?: 'bar' | 'more' | 'hidden';
+};
+export type BarAction = BarActionItem | BarActionMenu | BarActionCustom;
+/**
+ * A home's `actions` slot. `primary` is SINGULAR by type — that is the whole enforcement of law
+ * C6's "exactly one primary"; there is no runtime check because a second one cannot be written.
+ */
+export type ActionGroupProps = {
+    primary?: BarAction;
+    secondary?: BarAction[];
+};
+/**
+ * A shell-owned, persistent header action (timer, notifications, a global `SyncButton`).
+ * `node` is rendered as-is — basalt owns only the placement.
+ *
+ * Below `sm` a `'more'` action renders inside the header's single kebab, which means its `node` is
+ * mounted a second time there (lazily — a Mantine `Menu.Dropdown` mounts its children on open).
+ * Keep `'more'` for self-contained nodes and give anything holding live state `mobile: 'bar'`,
+ * which renders exactly once.
+ */
+export type GlobalAction = {
+    key: string;
+    node: ReactNode;
+    /** @default 'bar' for the first two, `'more'` for the rest */
+    mobile?: 'bar' | 'more' | 'hidden';
+};
+/** Secondaries rendered inline on desktop; the rest fold into `More` (`docs/CONTROLS-SPEC.md` §2.1). */
+export declare const DESKTOP_SECONDARY_MAX = 3;
+/** `GlobalAction`s without an explicit `mobile` that still land on the mobile bar. */
+export declare const MOBILE_GLOBAL_BAR_MAX = 2;
+/**
+ * What the shell hands the page's `ActionGroup` so the header ends up with ONE kebab instead of
+ * two: the shell's `mobile: 'more'` global actions (already mapped to `kind: 'custom'` rows), and
+ * a claim the mobile kebab takes on mount. While a page's kebab holds the claim, the shell renders
+ * no kebab of its own.
+ *
+ * Lives here, in the lowest layer, so `src/shell/**` imports downward into `src/controls/**` and
+ * never the reverse — a context declared in the shell would make `./controls` pull the shell in.
+ */
+export type BarExtras = {
+    mobileMoreActions: readonly BarAction[];
+    /** Claims the single mobile kebab. Returns the release, so it works straight out of an effect. */
+    claimKebab: () => () => void;
+};
+/** Internal — mounted by `BasaltShell` (via `PageBarProvider`), never by a consumer. */
+export declare function BarExtrasProvider({ value, children, }: {
+    value: BarExtras;
+    children: ReactNode;
+}): ReactNode;
+/** Resolved mobile placement of one action. A `kind: 'menu'` group is always a `More` row. */
+export declare function barActionMobile(action: BarAction, isPrimary: boolean): 'bar' | 'more' | 'hidden';
+/** `GlobalAction[]` → the same placement law, with "the first two ride the bar" as the default. */
+export declare function globalActionMobile(action: GlobalAction, index: number): 'bar' | 'more' | 'hidden';
+/** A `GlobalAction` reaching a `BarAction` slot — the kebab renders one row shape, not two. */
+export declare function globalActionAsBarAction(action: GlobalAction): BarActionCustom;
+export type OverflowMenuProps = {
+    actions: readonly BarAction[];
+    /**
+     * `more` — the labelled desktop `More` button. `kebab` — the mobile ⋯ icon button.
+     * @default 'more'
+     */
+    trigger?: 'more' | 'kebab';
+    /** Trigger label (and the kebab's accessible name). @default 'More' */
+    label?: string;
+};
+/**
+ * The overflow fold — the only place an action that doesn't fit goes (law C7). Rows are 44px below
+ * `sm` (`--vx-space-sheet-row-height`), so the mobile kebab is already a touch surface without a
+ * second, sheet-shaped component.
+ */
+export declare function OverflowMenu({ actions, trigger, label, }: OverflowMenuProps): ReactNode;
+/**
+ * Internal — the shared projection behind `ActionGroup` (and `PageBar`'s two rows).
+ *
+ * `host` is the whole reason this is not just `ActionGroup`. The shell's `mobile: 'more'` global
+ * actions must land in EXACTLY ONE kebab, and the only instance entitled to them is `PageBar`'s
+ * row 1. When every `ActionGroup` read `BarExtrasContext`, a page with `filtersEnd` (or any
+ * consumer composing an `ActionGroup` into a `Section`/`ChartCard` `actions` slot) grew a SECOND
+ * kebab that re-mounted the shell's global nodes and stole the claim from the shell's own fallback.
+ * `host: 'slot'` — the public `ActionGroup`'s value — gets `NO_EXTRAS`: no global rows, no claim.
+ */
+type BarActionRowProps = ActionGroupProps & {
+    /** `page` = `PageBar` row 1, the one instance that reads the shell extras and takes the claim. */
+    host: 'page' | 'slot';
+    /**
+     * `desktop` renders the desktop variant only — `PageBar` row 2, whose items live in the row-1
+     * kebab below `sm` (spec §2.1: mobile row 2 is tabs + the first pill + `Filters (n)`, nothing
+     * else). @default 'both'
+     */
+    viewport?: 'both' | 'desktop';
+    /**
+     * Actions projected onto the MOBILE variant only, never the desktop row — `PageBar.filtersEnd`,
+     * whose desktop home is row 2. Each still obeys its own `mobile` placement, so a `'bar'` one
+     * becomes an inline icon button and a `'hidden'` one stays desktop-only.
+     */
+    mobileOnly?: readonly BarAction[];
+    /**
+     * The home's `SyncButton`, mounted ONCE between the secondaries and the primary — see the ordering
+     * note in the body. Only `PageBar` row 1 passes it; a home with no sync passes nothing and the
+     * desktop row stays a single group.
+     */
+    syncNode?: ReactNode;
+};
+export declare function BarActionRow({ primary, secondary, host, viewport, mobileOnly, syncNode, }: BarActionRowProps): ReactNode;
+/**
+ * A home's `actions` slot, projected for both viewports.
+ *
+ * Desktop: `primary` as a `filled` button · up to `DESKTOP_SECONDARY_MAX` secondaries as `default`
+ * buttons · everything past that, plus every `kind: 'menu'`, in one `More` menu.
+ * Mobile: `primary` as an icon button when it ships an icon and a compact labelled button when it
+ * does not · one kebab holding every `mobile: 'more'` action · `mobile: 'hidden'` drops the action
+ * entirely.
+ *
+ * The shell's `mobile: 'more'` global actions are folded in by `PageBar`'s ROW-1 group only, not by
+ * this component — see `BarActionRowProps.host` for why every other home has to stay out of them.
+ *
+ * @example
+ * <PageBar actions={{ primary: { key: 'new', label: 'New run', onClick: start },
+ *                     secondary: [{ key: 'export', label: 'Export', onClick: exportCsv }] }} />
+ */
+export declare function ActionGroup(props: ActionGroupProps): ReactNode;
+export {};
+//# sourceMappingURL=actions.d.ts.map

package/dist/controls/actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../../src/controls/actions.tsx"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AACtC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAC7C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AAKxD;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;IACpB,IAAI,CAAC,EAAE,UAAU,CAAA;IACjB,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,IAAI,CAAA;IACZ,mFAAmF;IACnF,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,QAAQ,CAAA;CACnC,CAAA;AAED,sGAAsG;AACtG,MAAM,MAAM,aAAa,GAAG;IAC1B,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,KAAK,EAAE,SAAS,EAAE,CAAA;CACnB,CAAA;AAED,kGAAkG;AAClG,MAAM,MAAM,eAAe,GAAG;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,QAAQ,CAAA;IACd,IAAI,EAAE,SAAS,CAAA;IACf,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,QAAQ,CAAA;CACnC,CAAA;AAED,MAAM,MAAM,SAAS,GAAG,aAAa,GAAG,aAAa,GAAG,eAAe,CAAA;AAEvE;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB,SAAS,CAAC,EAAE,SAAS,EAAE,CAAA;CACxB,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,SAAS,CAAA;IACf,8DAA8D;IAC9D,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,QAAQ,CAAA;CACnC,CAAA;AAED,wGAAwG;AACxG,eAAO,MAAM,qBAAqB,IAAI,CAAA;AAEtC,sFAAsF;AACtF,eAAO,MAAM,qBAAqB,IAAI,CAAA;AAEtC;;;;;;;;GAQG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,iBAAiB,EAAE,SAAS,SAAS,EAAE,CAAA;IACvC,kGAAkG;IAClG,UAAU,EAAE,MAAM,MAAM,IAAI,CAAA;CAC7B,CAAA;AASD,wFAAwF;AACxF,wBAAgB,iBAAiB,CAAC,EAChC,KAAK,EACL,QAAQ,GACT,EAAE;IACD,KAAK,EAAE,SAAS,CAAA;IAChB,QAAQ,EAAE,SAAS,CAAA;CACpB,GAAG,SAAS,CAEZ;AAED,8FAA8F;AAC9F,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,GAAG,KAAK,GAAG,MAAM,GAAG,QAAQ,CAGhG;AAED,mGAAmG;AACnG,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,QAAQ,CAEjG;AAED,+FAA+F;AAC/F,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,YAAY,GAAG,eAAe,CAE7E;AAgKD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,OAAO,EAAE,SAAS,SAAS,EAAE,CAAA;IAC7B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IAC1B,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,EAC3B,OAAO,EACP,OAAgB,EAChB,KAAc,GACf,EAAE,iBAAiB,GAAG,SAAS,CA4C/B;AAED;;;;;;;;;GASG;AACH,KAAK,iBAAiB,GAAG,gBAAgB,GAAG;IAC1C,kGAAkG;IAClG,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;IACrB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7B;;;;OAIG;IACH,UAAU,CAAC,EAAE,SAAS,SAAS,EAAE,CAAA;IACjC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAA;CACrB,CAAA;AAgDD,wBAAgB,YAAY,CAAC,EAC3B,OAAO,EACP,SAAS,EACT,IAAI,EACJ,QAAiB,EACjB,UAAe,EACf,QAAQ,GACT,EAAE,iBAAiB,GAAG,SAAS,CA6G/B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,SAAS,CAE9D"}

package/dist/controls/actions.js

@@ -0,0 +1,287 @@
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { ActionIcon, Button, Group, Menu } from "@mantine/core";
+import { createContext, useContext, useEffect } from "react";
+import { IconSlot } from "../theme/icon-slot.js";
+import { ControlGroup } from "./control-group.js";
+import classes from "./actions.module.css";
+const DESKTOP_SECONDARY_MAX = 3;
+const MOBILE_GLOBAL_BAR_MAX = 2;
+const NO_EXTRAS = {
+  mobileMoreActions: [],
+  claimKebab: () => () => {
+  }
+};
+const BarExtrasContext = createContext(NO_EXTRAS);
+function BarExtrasProvider({
+  value,
+  children
+}) {
+  return /* @__PURE__ */ jsx(BarExtrasContext.Provider, { value, children });
+}
+function barActionMobile(action, isPrimary) {
+  if (action.kind === "menu") return "more";
+  return action.mobile ?? (isPrimary ? "bar" : "more");
+}
+function globalActionMobile(action, index) {
+  return action.mobile ?? (index < MOBILE_GLOBAL_BAR_MAX ? "bar" : "more");
+}
+function globalActionAsBarAction(action) {
+  return { key: action.key, kind: "custom", node: action.node, mobile: "more" };
+}
+function DotsGlyph() {
+  return /* @__PURE__ */ jsxs("svg", { width: 18, height: 18, viewBox: "0 0 24 24", fill: "currentColor", "aria-hidden": true, children: [
+    /* @__PURE__ */ jsx("circle", { cx: 12, cy: 5, r: 1.75 }),
+    /* @__PURE__ */ jsx("circle", { cx: 12, cy: 12, r: 1.75 }),
+    /* @__PURE__ */ jsx("circle", { cx: 12, cy: 19, r: 1.75 })
+  ] });
+}
+function ChevronGlyph() {
+  return /* @__PURE__ */ jsx("svg", { width: 14, height: 14, viewBox: "0 0 24 24", fill: "none", "aria-hidden": true, children: /* @__PURE__ */ jsx(
+    "path",
+    {
+      d: "M6 9l6 6 6-6",
+      stroke: "currentColor",
+      strokeWidth: 2,
+      strokeLinecap: "round",
+      strokeLinejoin: "round"
+    }
+  ) });
+}
+const MOBILE_PRIMARY_PADDING_X = 10;
+const BAR_GAP = 6;
+function BarButton({
+  action,
+  variant,
+  px
+}) {
+  const shared = {
+    variant,
+    ...px !== void 0 && { px },
+    disabled: action.disabled === true,
+    loading: action.loading === true,
+    // EVERY icon in this file goes through `IconSlot` — the box is the framework's, never the
+    // caller's glyph (see `theme/icon-slot.tsx`). Mantine's `leftSection` is a bare flex box with no
+    // size of its own, so a consumer's `width="24"` SVG used to set this row's height.
+    ...action.icon !== void 0 && { leftSection: /* @__PURE__ */ jsx(IconSlot, { children: action.icon }) },
+    ...action.danger === true && { color: "red" },
+    ...action.onClick !== void 0 && { onClick: action.onClick }
+  };
+  if (action.Anchor !== void 0) {
+    return /* @__PURE__ */ jsx(Button, { component: action.Anchor, ...shared, children: action.label });
+  }
+  if (action.link !== void 0) {
+    return /* @__PURE__ */ jsx(Button, { component: "a", href: action.link.to, ...shared, children: action.label });
+  }
+  return /* @__PURE__ */ jsx(Button, { ...shared, children: action.label });
+}
+function BarIconButton({
+  action,
+  variant
+}) {
+  const shared = {
+    variant,
+    "aria-label": action.label,
+    disabled: action.disabled === true,
+    loading: action.loading === true,
+    ...action.danger === true && { color: "red" },
+    ...action.onClick !== void 0 && { onClick: action.onClick }
+  };
+  const body = /* @__PURE__ */ jsx(IconSlot, { children: action.icon });
+  if (action.Anchor !== void 0) {
+    return /* @__PURE__ */ jsx(ActionIcon, { component: action.Anchor, ...shared, children: body });
+  }
+  if (action.link !== void 0) {
+    return /* @__PURE__ */ jsx(ActionIcon, { component: "a", href: action.link.to, ...shared, children: body });
+  }
+  return /* @__PURE__ */ jsx(ActionIcon, { ...shared, children: body });
+}
+function MenuRow({ action }) {
+  const shared = {
+    className: action.danger === true ? `${classes.menuItem} ${classes.menuItemDanger}` : classes.menuItem,
+    disabled: action.disabled === true,
+    ...action.icon !== void 0 && { leftSection: /* @__PURE__ */ jsx(IconSlot, { children: action.icon }) },
+    ...action.onClick !== void 0 && { onClick: action.onClick }
+  };
+  if (action.Anchor !== void 0 && action.disabled !== true) {
+    return /* @__PURE__ */ jsx(Menu.Item, { component: action.Anchor, ...shared, children: action.label });
+  }
+  if (action.link !== void 0 && action.disabled !== true) {
+    return /* @__PURE__ */ jsx(Menu.Item, { component: "a", href: action.link.to, ...shared, children: action.label });
+  }
+  return /* @__PURE__ */ jsx(Menu.Item, { ...shared, children: action.label });
+}
+function menuRows(actions) {
+  return actions.flatMap((action) => {
+    if (action.kind === "menu") {
+      return [
+        /* @__PURE__ */ jsx(Menu.Label, { children: action.label }, `${action.key}-label`),
+        ...menuRows(action.items)
+      ];
+    }
+    if (action.kind === "custom") {
+      return [
+        /* @__PURE__ */ jsx("div", { className: classes.customRow, children: action.node }, action.key)
+      ];
+    }
+    return [/* @__PURE__ */ jsx(MenuRow, { action }, action.key)];
+  });
+}
+function OverflowMenu({
+  actions,
+  trigger = "more",
+  label = "More"
+}) {
+  if (actions.length === 0) return null;
+  return /* @__PURE__ */ jsxs(
+    Menu,
+    {
+      position: "bottom-end",
+      offset: 6,
+      withinPortal: true,
+      zIndex: 400,
+      closeOnItemClick: true,
+      closeOnClickOutside: true,
+      closeOnEscape: true,
+      trapFocus: true,
+      returnFocus: true,
+      menuItemTabIndex: 0,
+      children: [
+        /* @__PURE__ */ jsx(Menu.Target, { children: trigger === "kebab" ? (
+          // `size="ctl"` explicitly, not inherited: the kebab is rendered by `HeaderGlobalActions`
+          // too, which is shell chrome rather than a home's slot, so there is no `CtlSlot` above it
+          // there. 28px beside 30px buttons is the mismatch the header read as.
+          /* @__PURE__ */ jsx(ActionIcon, { variant: "subtle", size: "ctl", "aria-label": label, children: /* @__PURE__ */ jsx(IconSlot, { className: classes.kebabIcon, children: /* @__PURE__ */ jsx(DotsGlyph, {}) }) })
+        ) : /* @__PURE__ */ jsx(
+          Button,
+          {
+            variant: "default",
+            rightSection: /* @__PURE__ */ jsx(IconSlot, { className: classes.chevronIcon, children: /* @__PURE__ */ jsx(ChevronGlyph, {}) }),
+            children: label
+          }
+        ) }),
+        /* @__PURE__ */ jsx(Menu.Dropdown, { children: menuRows(actions) })
+      ]
+    }
+  );
+}
+function joinRuns(actions, opts) {
+  const joinable = (action) => action.kind === void 0 && action.key !== opts.excludeKey && (action.group === true || opts.viewport === "mobile" && action.icon !== void 0);
+  const runs = [];
+  for (const action of actions) {
+    const tail = runs.at(-1);
+    if (joinable(action) && tail !== void 0 && tail.every(joinable)) tail.push(action);
+    else runs.push([action]);
+  }
+  return runs;
+}
+function BarActionRow({
+  primary,
+  secondary,
+  host,
+  viewport = "both",
+  mobileOnly = [],
+  syncNode
+}) {
+  const context = useContext(BarExtrasContext);
+  const extras = host === "page" ? context : NO_EXTRAS;
+  const list = secondary ?? [];
+  const flat = list.filter((a) => a.kind !== "menu");
+  const menus = list.filter((a) => a.kind === "menu");
+  const inline = flat.slice(0, DESKTOP_SECONDARY_MAX);
+  const desktopOverflow = [...flat.slice(DESKTOP_SECONDARY_MAX), ...menus];
+  const wantsMobile = viewport === "both";
+  const mobileList = [...list, ...mobileOnly];
+  const mobileBar = wantsMobile ? [
+    ...primary !== void 0 && barActionMobile(primary, true) === "bar" ? [primary] : [],
+    ...mobileList.filter((a) => barActionMobile(a, false) === "bar")
+  ] : [];
+  const mobileMore = wantsMobile ? [
+    ...primary !== void 0 && barActionMobile(primary, true) === "more" ? [primary] : [],
+    ...mobileList.filter((a) => barActionMobile(a, false) === "more"),
+    ...extras.mobileMoreActions
+  ] : [];
+  const claimsKebab = mobileMore.length > 0;
+  const claimKebab = extras.claimKebab;
+  useEffect(() => {
+    if (!claimsKebab) return;
+    return claimKebab();
+  }, [claimsKebab, claimKebab]);
+  const desktopPrimary = primary !== void 0 ? /* @__PURE__ */ jsx(BarEntry, { action: primary, emphasis: "primary" }) : null;
+  const hasDesktop = primary !== void 0 || list.length > 0;
+  const hasMobile = mobileBar.length > 0 || claimsKebab;
+  if (!hasDesktop && !hasMobile && syncNode === void 0) return null;
+  const desktopLead = inline.length > 0 || desktopOverflow.length > 0 || syncNode === void 0;
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    hasDesktop && desktopLead && /* @__PURE__ */ jsxs(Group, { gap: BAR_GAP, wrap: "nowrap", visibleFrom: "sm", children: [
+      joinRuns(inline, { viewport: "desktop" }).map(
+        (run) => run.length === 1 ? /* @__PURE__ */ jsx(BarEntry, { action: run[0], emphasis: "secondary" }, run[0].key) : /* @__PURE__ */ jsx(ControlGroup, { children: run.map((action) => /* @__PURE__ */ jsx(BarEntry, { action, emphasis: "secondary", iconOnly: true }, action.key)) }, `join-${run[0].key}`)
+      ),
+      /* @__PURE__ */ jsx(OverflowMenu, { actions: desktopOverflow }),
+      syncNode === void 0 && desktopPrimary
+    ] }),
+    syncNode,
+    syncNode !== void 0 && desktopPrimary !== null && /* @__PURE__ */ jsx(Group, { gap: BAR_GAP, wrap: "nowrap", visibleFrom: "sm", children: desktopPrimary }),
+    hasMobile && /* @__PURE__ */ jsxs(Group, { gap: BAR_GAP, wrap: "nowrap", hiddenFrom: "sm", children: [
+      joinRuns(mobileBar, { viewport: "mobile", excludeKey: primary?.key }).map(
+        (run) => run.length === 1 ? /* @__PURE__ */ jsx(
+          BarEntry,
+          {
+            action: run[0],
+            emphasis: run[0].key === primary?.key ? "mobile-primary" : "mobile-secondary"
+          },
+          run[0].key
+        ) : /* @__PURE__ */ jsx(ControlGroup, { children: run.map((action) => /* @__PURE__ */ jsx(
+          BarEntry,
+          {
+            action,
+            emphasis: action.key === primary?.key ? "mobile-primary" : "mobile-secondary"
+          },
+          action.key
+        )) }, `join-${run[0].key}`)
+      ),
+      claimsKebab && /* @__PURE__ */ jsx(OverflowMenu, { actions: mobileMore, trigger: "kebab", label: "More actions" })
+    ] })
+  ] });
+}
+function ActionGroup(props) {
+  return /* @__PURE__ */ jsx(BarActionRow, { ...props, host: "slot" });
+}
+function BarEntry({
+  action,
+  emphasis,
+  iconOnly
+}) {
+  if (action.kind === "custom") return /* @__PURE__ */ jsx("span", { className: classes.customSlot, children: action.node });
+  if (action.kind === "menu") return /* @__PURE__ */ jsx(OverflowMenu, { actions: [action], label: action.label });
+  if (emphasis === "mobile-primary") return /* @__PURE__ */ jsx(MobileBarEntry, { action, variant: "filled" });
+  if (emphasis === "mobile-secondary") return /* @__PURE__ */ jsx(MobileBarEntry, { action, variant: "subtle" });
+  if (iconOnly === true && action.icon !== void 0) {
+    return /* @__PURE__ */ jsx(BarIconButton, { action, variant: "default" });
+  }
+  return /* @__PURE__ */ jsx(BarButton, { action, variant: emphasis === "primary" ? "filled" : "default" });
+}
+function MobileBarEntry({
+  action,
+  variant
+}) {
+  if (action.icon !== void 0) return /* @__PURE__ */ jsx(BarIconButton, { action, variant });
+  return /* @__PURE__ */ jsx(
+    BarButton,
+    {
+      action,
+      variant: variant === "filled" ? "filled" : "default",
+      px: MOBILE_PRIMARY_PADDING_X
+    }
+  );
+}
+export {
+  ActionGroup,
+  BarActionRow,
+  BarExtrasProvider,
+  DESKTOP_SECONDARY_MAX,
+  MOBILE_GLOBAL_BAR_MAX,
+  OverflowMenu,
+  barActionMobile,
+  globalActionAsBarAction,
+  globalActionMobile
+};

package/dist/controls/actions.module.css

@@ -0,0 +1,62 @@
+/*
+ * `OverflowMenu` row chrome. Rows are `ctl`-tier (30px) on desktop and 44px below `sm`
+ * (`--vx-space-sheet-row-height`, law C15) — the mobile kebab IS the sheet, so there is no second
+ * component for the touch case.
+ */
+
+.menuItem {
+  min-height: calc(var(--vx-space-control-height-ctl) * var(--mantine-scale, 1));
+}
+
+/*
+ * Danger rows read the status token, not a Mantine shade — `--vx-bad-solid` resolves per color
+ * scheme, a pinned `red.6` does not (see the `mantine-shade-index` guard).
+ */
+.menuItemDanger {
+  color: var(--vx-bad-solid);
+}
+
+/* A `kind: 'custom'` row hosts the consumer's own node, so it only supplies the row box. */
+.customRow {
+  display: flex;
+  align-items: center;
+  min-height: calc(var(--vx-space-control-height-ctl) * var(--mantine-scale, 1));
+  padding: 0 var(--vx-space-row-inset-x);
+}
+
+@media (max-width: 47.99375em) {
+  .menuItem,
+  .customRow {
+    min-height: var(--vx-space-sheet-row-height);
+  }
+}
+
+/*
+ * A `kind: 'custom'` node's slot — see `BarEntry`'s doc. The whole point is the HEIGHT: basalt does
+ * not draw the node, so the only thing it can guarantee is the box it sits in. `inline-flex` +
+ * `align-items: center` centres a 20px Badge inside the 30px tier instead of letting it sit on the
+ * row's baseline, and `flex: none` keeps it out of the row's own shrink arithmetic.
+ */
+.customSlot {
+  display: inline-flex;
+  flex: none;
+  align-items: center;
+  height: calc(var(--vx-space-control-height-ctl) * var(--mantine-scale, 1));
+}
+
+/*
+ * The fold's own two glyphs, sized by overriding the icon slot's box var — never by the `width`
+ * attribute on the SVG, which is a presentation attribute the slot's CSS outranks anyway. The kebab
+ * reads at 18px because it is the ENTIRE content of an icon button (there is no label beside it to
+ * balance against), while `More`'s trailing chevron is the same 14px every pill's trailing
+ * affordance takes (`controls.module.css`'s `.glyph`).
+ */
+.kebabIcon {
+  --vx-space-icon-size: 1.125rem;
+}
+
+.chevronIcon {
+  --vx-space-icon-size: 0.875rem;
+
+  color: var(--vx-faint);
+}

package/dist/controls/actions.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 menuItem: string
+  readonly menuItemDanger: string
+  readonly customRow: string
+  readonly customSlot: string
+  readonly kebabIcon: string
+  readonly chevronIcon: string
+}
+export default classes

package/dist/controls/actions.test.d.ts

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

package/dist/controls/actions.test.d.ts.map

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

package/dist/controls/actions.type-guard.test.d.ts

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

package/dist/controls/actions.type-guard.test.d.ts.map

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

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

@@ -0,0 +1,41 @@
+/**
+ * `CompareFilter` — the period-comparison enum every dashboard grows
+ * (`docs/CONTROLS-SPEC.md` §3). A `SelectFilter` narrowed to the three values basalt names, so the
+ * label, the option order and the fallback are the same on every page instead of three per app.
+ *
+ * @example
+ * // compare: field.enum(['none', 'previous', 'year'], 'none')
+ * <CompareFilter field={analytics.field.compare} />
+ */
+import type { ReactNode } from 'react';
+import type { EnumField, FieldHandle } from '../state.js';
+/** The three comparison bases — declare the field as `field.enum(COMPARE_VALUES, 'none')`. */
+export type CompareValue = 'none' | 'previous' | 'year';
+/** The declared value order, so a consumer's `field.enum` and this control cannot disagree. */
+export declare const COMPARE_VALUES: readonly CompareValue[];
+/**
+ * The three option labels basalt names — the other half of "the same on every page instead of three
+ * per app", which this control promised and did not deliver.
+ *
+ * `field.enum` labels an option with the raw VALUE until a consumer calls `store.labels()`, so a
+ * `CompareFilter` over an unlabelled field printed `none` / `previous` / `year` in its popover and,
+ * now that the pill reads the value (see `EnumFilter`'s doc), in the bar too. Every app then wrote
+ * the same three strings into its own `labels()` call, which is three chances to disagree about what
+ * `year` means.
+ *
+ * These are DEFAULTS, not overrides: a field whose label differs from its value has been labelled
+ * deliberately, and that label wins. Detecting it as `label !== value` is exactly the signal
+ * `optionsFor` leaves behind (`state/fields.ts` — `label: map?.[value] ?? value`), so nothing new
+ * has to be threaded through the store to ask the question.
+ */
+export declare const COMPARE_LABELS: Readonly<Record<CompareValue, string>>;
+export type CompareFilterProps = {
+    readonly field: FieldHandle<EnumField<CompareValue>>;
+    /** @default 'Compare' */
+    readonly label?: string;
+    /** Leading pill icon. Defaults to an arrows-swap glyph — like `RangeFilter`'s calendar, the mark
+     *  is part of what makes the pill legible as a period comparison. */
+    readonly icon?: ReactNode;
+};
+export declare function CompareFilter({ field, label, icon }: CompareFilterProps): ReactNode;
+//# sourceMappingURL=compare-filter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"compare-filter.d.ts","sourceRoot":"","sources":["../../src/controls/compare-filter.tsx"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AACtC,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAItD,8FAA8F;AAC9F,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,CAAA;AAEvD,+FAA+F;AAC/F,eAAO,MAAM,cAAc,EAAE,SAAS,YAAY,EAAiC,CAAA;AAEnF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAIjE,CAAA;AAED,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC,CAAA;IACpD,yBAAyB;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB;yEACqE;IACrE,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAA;CAC1B,CAAA;AAED,wBAAgB,aAAa,CAAC,EAAE,KAAK,EAAE,KAAiB,EAAE,IAAI,EAAE,EAAE,kBAAkB,GAAG,SAAS,CAS/F"}

package/dist/controls/compare-filter.js

@@ -0,0 +1,23 @@
+import { jsx } from "react/jsx-runtime";
+import { EnumFilter } from "./enum-filter.js";
+import { SwapGlyph } from "./glyphs.js";
+const COMPARE_VALUES = ["none", "previous", "year"];
+const COMPARE_LABELS = {
+  none: "No comparison",
+  previous: "Previous period",
+  year: "Same period last year"
+};
+function CompareFilter({ field, label = "Compare", icon }) {
+  const options = field.options.map(
+    (option) => option.label === option.value && isCompareValue(option.value) ? { value: option.value, label: COMPARE_LABELS[option.value] } : option
+  );
+  return /* @__PURE__ */ jsx(EnumFilter, { field, label, icon: icon ?? /* @__PURE__ */ jsx(SwapGlyph, {}), options });
+}
+function isCompareValue(value) {
+  return COMPARE_VALUES.includes(value);
+}
+export {
+  COMPARE_LABELS,
+  COMPARE_VALUES,
+  CompareFilter
+};

package/dist/controls/control-group.d.ts

@@ -0,0 +1,19 @@
+import type { ReactNode } from 'react';
+export type ControlGroupProps = {
+    readonly children: ReactNode;
+    /**
+     * `none` (the default) JOINS the children: no gap, one shared hairline between each pair, and the
+     * corner radius only on the outer ends, so the set reads as one box.
+     *
+     * `tight` keeps the tier's own control gap and only guarantees the alignment and the no-wrap. It
+     * is for a set that belongs together but must stay separately pressable — three destructive
+     * actions, or a pair where one child is `filled` and joining it would put a fill edge against a
+     * border edge.
+     *
+     * @default 'none'
+     */
+    readonly gap?: 'none' | 'tight';
+    readonly className?: string;
+};
+export declare function ControlGroup({ children, gap, className }: ControlGroupProps): ReactNode;
+//# sourceMappingURL=control-group.d.ts.map

package/dist/controls/control-group.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control-group.d.ts","sourceRoot":"","sources":["../../src/controls/control-group.tsx"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAGtC,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAA;IAC5B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IAC/B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAC5B,CAAA;AAED,wBAAgB,YAAY,CAAC,EAAE,QAAQ,EAAE,GAAY,EAAE,SAAS,EAAE,EAAE,iBAAiB,GAAG,SAAS,CAWhG"}