basalt-ui 1.25.0 → 1.26.0

package/dist/shell/page-bar.module.css

@@ -0,0 +1,178 @@
+/*
+ * `PageBar` layout (docs/CONTROLS-SPEC.md §2.1).
+ *
+ * Law C7 in CSS form: `flex-wrap: nowrap` on every row and NO `overflow-x` anywhere. A home that
+ * scrolls sideways hides its own controls; the fold is computed instead — `More` for actions
+ * (`ActionGroup`), a `Filters (n)` sheet for filters (`FilterSet`'s job, wave 4). The filter
+ * container below only supplies `min-width: 0` so that fold has a box to measure against.
+ */
+
+/* The shell-less bar: both rows, sticky at the top of the document. One layer under the AppShell
+ * header (`--app-shell-header-z-index`, default 100) so it never wins a stacking fight with ordinary
+ * in-flow content — Mantine's Input section, Indicator, sticky table headers, and Slider thumbs all
+ * sit at `z-index: 1` or higher, which used to paint over a bare `z-index: 1` bar while scrolling. */
+.bar {
+  position: sticky;
+  top: 0;
+  z-index: calc(var(--app-shell-header-z-index, 100) - 1);
+  display: flex;
+  flex-direction: column;
+  gap: var(--vx-space-stack-xs);
+  background-color: var(--vx-surface-bg);
+}
+
+/*
+ * Row 2 inside a shell: in the page flow, sticky under the 48px header. `--app-shell-header-height`
+ * is Mantine's own AppShell variable, so the offset tracks the header at any density with no React
+ * state and no measurement. `z-index` sits one layer below the header itself (see `.bar` above) —
+ * high enough to stay above ordinary page content, never above the AppShell header.
+ */
+.row2Sticky {
+  position: sticky;
+  top: var(--app-shell-header-height, 0px);
+  z-index: calc(var(--app-shell-header-z-index, 100) - 1);
+  background-color: var(--vx-surface-bg);
+}
+
+.row1 {
+  display: flex;
+  flex-wrap: nowrap;
+  align-items: center;
+  gap: var(--vx-space-control-gap);
+  min-width: 0;
+  min-height: var(--vx-space-page-bar-row-height);
+}
+
+.lead {
+  display: flex;
+  flex-wrap: nowrap;
+  align-items: center;
+  gap: var(--vx-space-control-gap);
+  flex-shrink: 0;
+  min-width: 0;
+}
+
+.icon {
+  display: inline-flex;
+  align-items: center;
+  color: var(--vx-muted);
+}
+
+/*
+ * The shell-less page title (law C8: the breadcrumb names the page inside a shell, this does it
+ * outside one). Head-font treatment, same 88%/550 as every `WidgetHeader` title.
+ */
+.title {
+  margin: 0;
+  font-family: var(--basalt-font-head);
+  font-size: var(--vx-text-xl);
+  font-weight: 550;
+  font-stretch: 88%;
+  color: var(--vx-ink);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+/*
+ * Icons inside a row-1 button are 16px and sit 6px from their label. Mantine spends
+ * `--mantine-spacing-xs` (11px) on a Button's section gap regardless of the size tier, which is the
+ * BODY tier's number — at 30px it detached the glyph from the word it belongs to. Scoped to the row
+ * rather than themed on `Button` globally: a `size="md"` button in a form still wants Mantine's gap.
+ */
+.row1 :global(.mantine-Button-section[data-position='left']),
+.row2 :global(.mantine-Button-section[data-position='left']) {
+  margin-inline-end: var(--vx-space-control-gap);
+}
+
+.row1 :global(.mantine-Button-section) > svg,
+.row1 :global(.mantine-ActionIcon-root) > svg {
+  width: 1rem;
+  height: 1rem;
+}
+
+/* Actions and sync are right-aligned; the lead (or the breadcrumb, in a shell) holds the left. */
+.row1End {
+  display: flex;
+  flex-wrap: nowrap;
+  align-items: center;
+  justify-content: flex-end;
+  gap: var(--vx-space-control-gap);
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
+/*
+ * Row 2's rhythm is 8px · pills · 8px, NOT a 40px reserved row.
+ *
+ * `min-height: var(--vx-space-page-bar-row-height)` (40px) left a 30px pill floating inside a 40px
+ * box with the 5px above and below it belonging to nothing — and because the row sat in a `Stack`
+ * that already spaced it, the visible gap between the header and the pills read as ~19px while the
+ * gap from the pills to the first card read as ~19px too. Symmetric padding on the row itself is the
+ * same total height (46px vs 40px) with both halves owned by one declaration, so the sticky bar's
+ * published height covers exactly the band it paints.
+ */
+.row2 {
+  display: flex;
+  flex-wrap: nowrap;
+  align-items: center;
+  gap: var(--vx-space-control-gap);
+  min-width: 0;
+  padding-block: var(--vx-space-stack-sm);
+}
+
+.filters {
+  display: flex;
+  flex-wrap: nowrap;
+  align-items: center;
+  gap: var(--vx-space-control-gap);
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
+.filtersEnd {
+  display: flex;
+  flex-wrap: nowrap;
+  align-items: center;
+  gap: var(--vx-space-control-gap);
+  margin-inline-start: auto;
+  flex-shrink: 0;
+}
+
+/*
+ * Law C15 — every touch target inside a home is at least `touchControlHeight` (36px at level 0)
+ * below `sm`, while the VISIBLE box stays the 30px `ctl` tier. `::after` and not `::before`:
+ * Mantine's Button owns `::before` for its loading overlay (`@mantine/core/styles/Button.css`),
+ * so a hit area drawn there would fight it. `pointer-events` stays default so the overlay is the
+ * one receiving the tap.
+ *
+ * `overflow: visible` is LOAD-BEARING, not tidying. Mantine's Button and ActionIcon roots both set
+ * `overflow: hidden` (`Button.css`, `ActionIcon.css`), which clips an overlay that by definition
+ * extends past the 30px box — so without this the 36px target simply does not exist and a tap 3px
+ * above the control misses. What `overflow: hidden` buys those roots is clipping the loading
+ * overlay's blur, and that overlay is only painted under `[data-loading]`, which is excluded below.
+ */
+@media (max-width: 47.99375em) {
+  .row1 :is(button, a),
+  .row2 :is(button, a) {
+    position: relative;
+  }
+
+  .row1 :is(button, a):not([data-loading]),
+  .row2 :is(button, a):not([data-loading]) {
+    overflow: visible;
+  }
+
+  .row1 :is(button, a)::after,
+  .row2 :is(button, a)::after {
+    content: '';
+    position: absolute;
+    top: 50%;
+    left: 50%;
+    translate: -50% -50%;
+    width: 100%;
+    height: 100%;
+    min-width: var(--vx-space-touch-control-height);
+    min-height: var(--vx-space-touch-control-height);
+  }
+}

package/dist/shell/page-bar.module.css.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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 bar: string
+  readonly row2Sticky: string
+  readonly row1: string
+  readonly lead: string
+  readonly icon: string
+  readonly title: string
+  readonly row2: string
+  readonly row1End: string
+  readonly filters: string
+  readonly filtersEnd: string
+}
+export default classes

package/dist/shell/page-bar.test.d.ts

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

package/dist/shell/page-bar.test.d.ts.map

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

package/dist/shell/sidebar-block-model.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The sidebar-block law — every default a `SidebarBlock` leaves unstated, plus the two persisted
+ * fold-key grammars.
+ *
+ * PURE BY CONTRACT, for the same reason `mobile-nav-model.ts` is: three consumers read these
+ * defaults and none of them may disagree. `app-sidebar.tsx` decides where a block renders and
+ * whether the rail keeps it, `sidebar-blocks.tsx` paints it, and `mobile-nav-model.ts` counts the
+ * More-sheet rows it will produce — a count that picks `menu` vs `sheet` before any of it renders.
+ * A default re-derived per call site is how the count and the renderer drift apart (see
+ * `accountRowCount`'s doc for the same failure with account rows).
+ */
+import type { SidebarBlock } from '../nav/types.js';
+/** Envelope version for a persisted fold flag. Bump only if the value stops being a boolean. */
+export declare const FOLD_VERSION = 1;
+/**
+ * `'nav'` renders after the nav sections inside the scroll region; `'bottom'` pins above the
+ * settings footer. A progress block is `'bottom'` — it is a pinned status row, not a nav tail.
+ */
+export declare function sidebarBlockPlacement(block: SidebarBlock): 'nav' | 'bottom';
+/**
+ * The collapsed-rail projection. A list block earns a dot only when it carries a `count` — a rail
+ * icon with no number behind it is a dot that means nothing — and a progress block a ring on the
+ * settings row. A `custom` block has no rail representation at all (arbitrary content in ~48px of
+ * icon column), which is exactly what `sidebarNavExtra` did before it.
+ */
+export declare function sidebarBlockRail(block: SidebarBlock): 'dot' | 'ring' | 'hidden';
+/**
+ * The mobile projection. A list is reachable from More by default — below `sm` the sidebar does
+ * not render at all, so a hidden list is unreachable, not merely unshown. A progress row defaults
+ * to `'hidden'`: it is ambient status, and every More row costs headroom the menu-vs-sheet
+ * threshold is measured against.
+ */
+export declare function sidebarBlockMobile(block: SidebarBlock): 'more' | 'hidden';
+/** Rows a list block paints, honouring `max` — the "Show more" toggle reveals the remainder. */
+export declare function sidebarBlockVisibleCount(itemCount: number, max: number | undefined): number;
+/**
+ * A section label as a storage-key segment. Lowercase, every run of non-alphanumerics collapsed to
+ * one `-`, no leading/trailing separator — `'Awaiting action'` → `'awaiting-action'`.
+ */
+export declare function slugifyLabel(label: string): string;
+/**
+ * `createPersistedState` namespaces every key as `basalt:<key>`, so these return the UNNAMESPACED
+ * halves — the real storage keys are `basalt:sidebar-block:<key>` and
+ * `basalt:sidebar-section:<label-slug>` (`docs/CONTROLS-SPEC.md` §2.3).
+ */
+export declare function sidebarBlockFoldKey(blockKey: string): string;
+export declare function sidebarSectionFoldKey(label: string): string;
+//# sourceMappingURL=sidebar-block-model.d.ts.map

package/dist/shell/sidebar-block-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sidebar-block-model.d.ts","sourceRoot":"","sources":["../../src/shell/sidebar-block-model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAEhD,gGAAgG;AAChG,eAAO,MAAM,YAAY,IAAI,CAAA;AAE7B;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,YAAY,GAAG,KAAK,GAAG,QAAQ,CAG3E;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,GAAG,KAAK,GAAG,MAAM,GAAG,QAAQ,CAS/E;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,GAAG,QAAQ,CAIzE;AAED,gGAAgG;AAChG,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAG3F;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKlD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE3D"}

package/dist/shell/sidebar-block-model.js

@@ -0,0 +1,39 @@
+const FOLD_VERSION = 1;
+function sidebarBlockPlacement(block) {
+  if (block.kind === "progress") return block.placement ?? "bottom";
+  return block.placement ?? "nav";
+}
+function sidebarBlockRail(block) {
+  if (block.kind === "custom") return "hidden";
+  if (block.kind === "progress") return block.rail ?? "ring";
+  if (block.icon === void 0 || block.count === void 0) return "hidden";
+  return block.rail ?? "dot";
+}
+function sidebarBlockMobile(block) {
+  if (block.kind === "custom") return "hidden";
+  if (block.kind === "progress") return block.mobile ?? "hidden";
+  return block.mobile ?? "more";
+}
+function sidebarBlockVisibleCount(itemCount, max) {
+  if (max === void 0 || max >= itemCount) return itemCount;
+  return Math.max(0, max);
+}
+function slugifyLabel(label) {
+  return label.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function sidebarBlockFoldKey(blockKey) {
+  return `sidebar-block:${blockKey}`;
+}
+function sidebarSectionFoldKey(label) {
+  return `sidebar-section:${slugifyLabel(label)}`;
+}
+export {
+  FOLD_VERSION,
+  sidebarBlockFoldKey,
+  sidebarBlockMobile,
+  sidebarBlockPlacement,
+  sidebarBlockRail,
+  sidebarBlockVisibleCount,
+  sidebarSectionFoldKey,
+  slugifyLabel
+};

package/dist/shell/sidebar-blocks.d.ts

@@ -0,0 +1,32 @@
+import type { SidebarBlockTone, SidebarCustomBlock, SidebarListBlock, SidebarProgressBlock } from '../nav/types.js';
+/**
+ * Fold/expand chevron. Lives here rather than in `app-sidebar.tsx` purely for direction: that
+ * module imports this one, so a glyph shared by a collapsible SECTION header and a collapsible
+ * BLOCK header has to sit on this side of the edge or the two files cycle.
+ */
+export declare function IconChevron({ open }: {
+    open: boolean;
+}): import("react").JSX.Element;
+/**
+ * A persisted fold flag (`true` = folded). Exactly one hook call regardless of `key`, so swapping
+ * keys mid-life never moves the hook count.
+ *
+ * Every fold in the sidebar goes through this — block folds at `basalt:sidebar-block:<key>` and
+ * nav-section folds at `basalt:sidebar-section:<label-slug>`. Through 1.25.0 the section folds were
+ * one `useState` keyed by label, so every reload re-opened a section the user had closed.
+ */
+export declare function usePersistedFold(key: string, initial: boolean): readonly [boolean, (next: boolean) => void];
+/** Status dot — the icon fallback for a toned row. Reads `--vx-status-*` through `data-tone`. */
+export declare function SidebarBlockToneDot({ tone }: {
+    tone: SidebarBlockTone;
+}): import("react").JSX.Element;
+/** `value` of `total` as a ring — the collapsed rail's stand-in for a progress block. */
+export declare function SidebarProgressRing({ value, total }: {
+    value: number;
+    total: number;
+}): import("react").JSX.Element;
+/** One block, whichever kind it is. `AppSidebar` places it; this decides nothing but the paint. */
+export declare function SidebarBlockView({ block, }: {
+    block: SidebarListBlock | SidebarProgressBlock | SidebarCustomBlock;
+}): import("react").JSX.Element;
+//# sourceMappingURL=sidebar-blocks.d.ts.map

package/dist/shell/sidebar-blocks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sidebar-blocks.d.ts","sourceRoot":"","sources":["../../src/shell/sidebar-blocks.tsx"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAEV,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,EACrB,MAAM,cAAc,CAAA;AAYrB;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,EAAE,IAAI,EAAE,EAAE;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,+BAgBtD;AAsBD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,OAAO,GACf,SAAS,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC,CAE7C;AAcD,iGAAiG;AACjG,wBAAgB,mBAAmB,CAAC,EAAE,IAAI,EAAE,EAAE;IAAE,IAAI,EAAE,gBAAgB,CAAA;CAAE,+BAEvE;AAED,yFAAyF;AACzF,wBAAgB,mBAAmB,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,+BAwBrF;AA4JD,mGAAmG;AACnG,wBAAgB,gBAAgB,CAAC,EAC/B,KAAK,GACN,EAAE;IACD,KAAK,EAAE,gBAAgB,GAAG,oBAAoB,GAAG,kBAAkB,CAAA;CACpE,+BAIA"}

package/dist/shell/sidebar-blocks.js

@@ -0,0 +1,169 @@
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { Collapse, NavLink, Progress, Text, UnstyledButton } from "@mantine/core";
+import { useState } from "react";
+import { NavCountBadge } from "./nav-count-badge.js";
+import { createPersistedState } from "../state.js";
+import {
+  FOLD_VERSION,
+  sidebarBlockFoldKey,
+  sidebarBlockRail,
+  sidebarBlockVisibleCount
+} from "./sidebar-block-model.js";
+import { IconSlot } from "../theme/icon-slot.js";
+import classes from "./app-sidebar.module.css";
+function IconChevron({ open }) {
+  return /* @__PURE__ */ jsx(
+    "svg",
+    {
+      width: 12,
+      height: 12,
+      viewBox: "0 0 24 24",
+      fill: "none",
+      stroke: "currentColor",
+      strokeWidth: 2,
+      strokeLinecap: "round",
+      strokeLinejoin: "round",
+      "aria-hidden": true,
+      children: open ? /* @__PURE__ */ jsx("path", { d: "M6 9l6 6l6 -6" }) : /* @__PURE__ */ jsx("path", { d: "M9 6l6 6l-6 6" })
+    }
+  );
+}
+const foldStores = /* @__PURE__ */ new Map();
+function foldStore(key, initial) {
+  const cached = foldStores.get(key);
+  if (cached) return cached;
+  const store = createPersistedState({ key, version: FOLD_VERSION, initial });
+  foldStores.set(key, store);
+  return store;
+}
+function usePersistedFold(key, initial) {
+  return foldStore(key, initial)();
+}
+function BlockLabel({ children }) {
+  return /* @__PURE__ */ jsx(Text, { component: "div", className: classes.sectionLabel, children });
+}
+function SidebarBlockToneDot({ tone }) {
+  return /* @__PURE__ */ jsx("span", { className: classes.blockToneDot, "data-tone": tone, "aria-hidden": true });
+}
+function SidebarProgressRing({ value, total }) {
+  const CIRCUMFERENCE = 2 * Math.PI * 8;
+  const ratio = total > 0 ? Math.min(1, Math.max(0, value / total)) : 0;
+  return /* @__PURE__ */ jsx("span", { className: classes.blockRing, "data-basalt-rail-ring": true, children: /* @__PURE__ */ jsxs("svg", { width: 20, height: 20, viewBox: "0 0 20 20", "aria-hidden": true, children: [
+    /* @__PURE__ */ jsx("circle", { cx: 10, cy: 10, r: 8, fill: "none", stroke: "var(--vx-divider)", strokeWidth: 2 }),
+    /* @__PURE__ */ jsx(
+      "circle",
+      {
+        cx: 10,
+        cy: 10,
+        r: 8,
+        fill: "none",
+        stroke: "var(--vx-accent)",
+        strokeWidth: 2,
+        strokeLinecap: "round",
+        strokeDasharray: CIRCUMFERENCE,
+        strokeDashoffset: CIRCUMFERENCE * (1 - ratio),
+        transform: "rotate(-90 10 10)"
+      }
+    )
+  ] }) });
+}
+function BlockRow({ item }) {
+  const rawLead = item.icon ?? (item.tone !== void 0 ? /* @__PURE__ */ jsx(SidebarBlockToneDot, { tone: item.tone }) : void 0);
+  const lead = rawLead === void 0 ? void 0 : /* @__PURE__ */ jsx(IconSlot, { children: rawLead });
+  const meta = item.meta !== void 0 ? /* @__PURE__ */ jsx(Text, { component: "span", className: classes.blockRowMeta, children: item.meta }) : void 0;
+  const interactive = item.Anchor !== void 0 || item.href !== void 0 || item.onClick !== void 0;
+  if (!interactive) {
+    return /* @__PURE__ */ jsxs("div", { className: `${classes.blockRow} ${classes.blockRowStatic}`, children: [
+      lead,
+      /* @__PURE__ */ jsx(Text, { component: "span", className: classes.blockRowLabel, children: item.label }),
+      meta
+    ] });
+  }
+  const shared = {
+    classNames: { root: classes.blockRow },
+    label: item.label,
+    ...lead !== void 0 && { leftSection: lead },
+    ...meta !== void 0 && { rightSection: meta },
+    ...item.onClick !== void 0 && { onClick: item.onClick }
+  };
+  const Anchor = item.Anchor;
+  if (Anchor) return /* @__PURE__ */ jsx(NavLink, { component: Anchor, ...shared });
+  return /* @__PURE__ */ jsx(NavLink, { component: "a", ...item.href !== void 0 && { href: item.href }, ...shared });
+}
+function ListBlock({ block }) {
+  const [folded, setFolded] = usePersistedFold(sidebarBlockFoldKey(block.key), false);
+  const [showAll, setShowAll] = useState(false);
+  const rail = sidebarBlockRail(block);
+  const visible = showAll ? block.items.length : sidebarBlockVisibleCount(block.items.length, block.max);
+  const hidden = block.items.length - visible;
+  const label = /* @__PURE__ */ jsxs(Fragment, { children: [
+    block.icon !== void 0 && /* @__PURE__ */ jsxs("span", { className: classes.blockIcon, children: [
+      block.icon,
+      rail === "dot" && /* @__PURE__ */ jsx("span", { className: classes.blockDot, "aria-hidden": true })
+    ] }),
+    /* @__PURE__ */ jsx(BlockLabel, { children: block.label }),
+    block.count ? /* @__PURE__ */ jsx(NavCountBadge, { count: block.count }) : null
+  ] });
+  const body = /* @__PURE__ */ jsxs("div", { className: classes.blockItems, children: [
+    block.items.slice(0, visible).map((item) => /* @__PURE__ */ jsx(BlockRow, { item }, item.key)),
+    hidden > 0 || showAll ? /* @__PURE__ */ jsx(
+      UnstyledButton,
+      {
+        className: classes.blockMore,
+        onClick: () => setShowAll(!showAll),
+        "aria-expanded": showAll,
+        children: showAll ? "Show less" : "Show more"
+      }
+    ) : null
+  ] });
+  return /* @__PURE__ */ jsx("div", { className: classes.block, "data-rail": rail, children: block.collapsible === true ? /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsxs(
+      UnstyledButton,
+      {
+        className: `${classes.blockHeader} ${classes.blockHeaderButton}`,
+        onClick: () => setFolded(!folded),
+        "aria-expanded": !folded,
+        children: [
+          label,
+          /* @__PURE__ */ jsx(IconChevron, { open: !folded })
+        ]
+      }
+    ),
+    /* @__PURE__ */ jsx(Collapse, { expanded: !folded, children: body })
+  ] }) : /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx("div", { className: classes.blockHeader, children: label }),
+    body
+  ] }) });
+}
+function ProgressBlock({ block }) {
+  const percent = block.total > 0 ? Math.min(100, Math.max(0, block.value / block.total * 100)) : 0;
+  const inner = /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsxs("div", { className: classes.blockProgressHead, children: [
+      /* @__PURE__ */ jsx(BlockLabel, { children: block.label }),
+      /* @__PURE__ */ jsxs(Text, { component: "span", className: classes.blockRowMeta, children: [
+        block.value,
+        " of ",
+        block.total
+      ] })
+    ] }),
+    /* @__PURE__ */ jsx(Progress, { value: percent, size: "xs", "aria-label": block.label })
+  ] });
+  return /* @__PURE__ */ jsx("div", { className: classes.block, "data-rail": sidebarBlockRail(block), children: block.onClick !== void 0 ? /* @__PURE__ */ jsx(UnstyledButton, { className: classes.blockProgress, onClick: block.onClick, children: inner }) : /* @__PURE__ */ jsx("div", { className: classes.blockProgress, children: inner }) });
+}
+function CustomBlock({ block }) {
+  return /* @__PURE__ */ jsx("div", { className: classes.block, "data-rail": "hidden", children: block.node });
+}
+function SidebarBlockView({
+  block
+}) {
+  if (block.kind === "list") return /* @__PURE__ */ jsx(ListBlock, { block });
+  if (block.kind === "progress") return /* @__PURE__ */ jsx(ProgressBlock, { block });
+  return /* @__PURE__ */ jsx(CustomBlock, { block });
+}
+export {
+  IconChevron,
+  SidebarBlockToneDot,
+  SidebarBlockView,
+  SidebarProgressRing,
+  usePersistedFold
+};

package/dist/shell/sidebar-search.d.ts

@@ -1,3 +1,14 @@
+import type { BarAction } from '../controls/actions.js';
+/**
+ * The ⌘K row's trailing icon buttons — ONE or TWO, by type (`docs/CONTROLS-SPEC.md` §2.3).
+ *
+ * The tuple IS the enforcement: a third button pushes the search trigger under the width where its
+ * placeholder stays readable, and there is no third thing a sidebar search row is for. Each entry
+ * renders icon-only at the `icon` tier (24px, `--ai-size-icon`) with `label` demoted to the
+ * accessible name; a `kind: 'menu'` entry becomes an `OverflowMenu` kebab, a `kind: 'custom'` one
+ * is mounted verbatim.
+ */
+export type SidebarSearchActions = [BarAction] | [BarAction, BarAction];
 export type SidebarSearchConfig = {
     /** Opens the search palette — e.g. `openSpotlight` from `basalt-ui/commands`. */
     onOpen: () => void;
@@ -6,7 +17,8 @@ export type SidebarSearchConfig = {
     /** Keyboard-shortcut hint shown on the right (e.g. '⌘K'). Auto-detected mac/other when omitted. */
     shortcut?: string;
 };
-export declare function SidebarSearch({ onOpen, placeholder, shortcut, collapsed, }: SidebarSearchConfig & {
+export declare function SidebarSearch({ onOpen, placeholder, shortcut, actions, collapsed, }: SidebarSearchConfig & {
+    actions?: SidebarSearchActions;
     collapsed?: boolean;
 }): import("react").JSX.Element;
 //# sourceMappingURL=sidebar-search.d.ts.map

package/dist/shell/sidebar-search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sidebar-search.d.ts","sourceRoot":"","sources":["../../src/shell/sidebar-search.tsx"],"names":[],"mappings":"AAYA,MAAM,MAAM,mBAAmB,GAAG;IAChC,iFAAiF;IACjF,MAAM,EAAE,MAAM,IAAI,CAAA;IAClB,2CAA2C;IAC3C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,mGAAmG;IACnG,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,CAAA;AAsBD,wBAAgB,aAAa,CAAC,EAC5B,MAAM,EACN,WAAuB,EACvB,QAAQ,EACR,SAAS,GACV,EAAE,mBAAmB,GAAG;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,+BAiC/C"}
+{"version":3,"file":"sidebar-search.d.ts","sourceRoot":"","sources":["../../src/shell/sidebar-search.tsx"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAGpD;;;;;;;;GAQG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,EAAE,SAAS,CAAC,CAAA;AAEvE,MAAM,MAAM,mBAAmB,GAAG;IAChC,iFAAiF;IACjF,MAAM,EAAE,MAAM,IAAI,CAAA;IAClB,2CAA2C;IAC3C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,mGAAmG;IACnG,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,CAAA;AAgED,wBAAgB,aAAa,CAAC,EAC5B,MAAM,EACN,WAAuB,EACvB,QAAQ,EACR,OAAO,EACP,SAAS,GACV,EAAE,mBAAmB,GAAG;IAAE,OAAO,CAAC,EAAE,oBAAoB,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,+BA6C/E"}

package/dist/shell/sidebar-search.js

@@ -1,5 +1,6 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 import { ActionIcon, Kbd, Text, UnstyledButton } from "@mantine/core";
+import { OverflowMenu } from "../controls/actions.js";
 import classes from "./sidebar-search.module.css";
 function IconSearch() {
   return /* @__PURE__ */ jsxs(
@@ -21,10 +22,37 @@ function IconSearch() {
     }
   );
 }
+function initial(label) {
+  return [...label][0]?.toUpperCase() ?? "?";
+}
+function SearchAction({ action }) {
+  if (action.kind === "custom") return action.node;
+  if (action.kind === "menu") {
+    return /* @__PURE__ */ jsx(OverflowMenu, { actions: action.items, trigger: "kebab", label: action.label });
+  }
+  const shared = {
+    variant: "subtle",
+    size: "icon",
+    className: classes.actionBtn,
+    "aria-label": action.label,
+    disabled: action.disabled === true,
+    ...action.onClick !== void 0 && { onClick: action.onClick }
+  };
+  const body = action.icon ?? initial(action.label);
+  const Anchor = action.Anchor;
+  if (Anchor !== void 0) {
+    return /* @__PURE__ */ jsx(ActionIcon, { component: 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 SidebarSearch({
   onOpen,
   placeholder = "Search\u2026",
   shortcut,
+  actions,
   collapsed
 }) {
   const isMac = typeof navigator !== "undefined" && /Mac|iPhone|iPod|iPad/i.test(navigator.platform);
@@ -42,7 +70,7 @@ function SidebarSearch({
       }
     );
   }
-  return /* @__PURE__ */ jsxs(
+  const trigger = /* @__PURE__ */ jsxs(
     UnstyledButton,
     {
       type: "button",
@@ -56,6 +84,11 @@ function SidebarSearch({
       ]
     }
   );
+  if (actions === void 0) return trigger;
+  return /* @__PURE__ */ jsxs("div", { className: classes.row, children: [
+    trigger,
+    actions.map((action) => /* @__PURE__ */ jsx(SearchAction, { action }, action.key))
+  ] });
 }
 export {
   SidebarSearch

package/dist/shell/sidebar-search.module.css

@@ -5,6 +5,18 @@
  * button as a matched pair, so the two must never drift onto different depth tokens.
  */
 
+/*
+ * The row that appears ONLY when `search.actions` is supplied — one or two icon-only buttons beside
+ * the trigger. Without actions the trigger stays the row's sole node (no wrapper), so the DOM of
+ * every consumer that doesn't use them is untouched.
+ */
+.row {
+  display: flex;
+  align-items: center;
+  gap: var(--vx-space-sidebar-search-gap);
+  min-width: 0;
+}
+
 .trigger {
   display: flex;
   align-items: center;
@@ -74,3 +86,17 @@
   background-color: color-mix(in srgb, var(--vx-ink) 6%, transparent) !important;
   color: var(--vx-ink) !important;
 }
+
+/* Trailing search-row action — the same ghost treatment as `.ghostIcon` / `.railBtn`, at the `icon`
+ * tier (24px) the component asks for explicitly. Never re-points `--ai-size`: unlike `.railBtn`,
+ * this button is NOT a second state of the trigger and must not track its height. */
+.actionBtn {
+  flex: none;
+  color: var(--vx-faint) !important;
+  border-radius: var(--vx-radius-ctrl) !important;
+}
+
+.actionBtn:hover {
+  background-color: color-mix(in srgb, var(--vx-ink) 6%, transparent) !important;
+  color: var(--vx-ink) !important;
+}

package/dist/shell/sidebar-search.module.css.d.ts

@@ -4,8 +4,10 @@
  * (`noUncheckedIndexedAccess`, `noPropertyAccessFromIndexSignature`, `exactOptionalPropertyTypes`).
  */
 declare const classes: {
+  readonly row: string
   readonly trigger: string
   readonly label: string
   readonly railBtn: string
+  readonly actionBtn: string
 }
 export default classes