basalt-ui 1.24.0 → 1.26.0

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