basalt-ui 1.26.0 → 1.28.0

package/dist/section/section.d.ts

@@ -1,6 +1,40 @@
 import type { ReactNode } from 'react';
+import type { BasaltProps, SlotStylesProps } from '../common/props.js';
+import type { SlotActions } from '../controls/actions.js';
+import type { QueryEmptyCopy, QueryStateLike } from '../dashboard/query-state.js';
 import type { WidgetHeaderProps } from '../widget-header/index.js';
-export type SectionProps = Omit<WidgetHeaderProps, 'tier'> & {
+/**
+ * The three boxes `Section` paints, and the whole styling seam it offers (`common/props.ts`):
+ * `root` is the outer stack, `header` is the `WidgetHeader` row, `body` is the collapsible content
+ * box. `summary` is deliberately absent — it is a one-row readout under the header, not a layout
+ * box a consumer positions.
+ */
+export type SectionSlot = 'root' | 'header' | 'body';
+export type SectionProps = Omit<WidgetHeaderProps, 'tier' | 'classNames' | 'actions'> & BasaltProps & SlotStylesProps<SectionSlot> & {
+    /**
+     * Header actions, in either form (law C15): a typed `BarAction[]`, which basalt projects through
+     * the SAME row `PageBar` and `ActionGroup` use — ≤3 inline, the rest folded into `More`, one
+     * kebab below `sm` — or an opaque `ReactNode` a caller drew itself, rendered verbatim. The ≤3
+     * budget (C6) is checked against whichever form is given.
+     */
+    actions?: SlotActions;
+    /**
+     * The section's async result. Given one, the BODY renders through `QueryState` at the section
+     * tier — pending / error-with-retry / empty each REPLACE `children`, data renders them — while
+     * the header, the fold chevron and `summary` stay drawn throughout, so a section never blinks out
+     * of the page while it refetches.
+     *
+     * This is law C3's uniform container contract (`docs/CONTROLS-SPEC.md` §1): without it every
+     * caller re-derives the four-way switch `QueryState` exists to delete, and gets it wrong in the
+     * one direction that matters — "nothing here" printed over a 500.
+     */
+    query?: QueryStateLike<unknown>;
+    /**
+     * Copy for `query`'s EMPTY branch, rendered through `EmptyState` like every other one. Omit to
+     * render nothing when the result is empty — `QueryState`'s own contract, unchanged. Ignored
+     * without `query`.
+     */
+    empty?: QueryEmptyCopy;
     /** Rendered in the header row, in its own `CtlSlot` — hidden while the section is collapsed. */
     tabs?: ReactNode;
     /** Renders a chevron toggle in the header; the header stays drawn when closed, only `children`
@@ -20,5 +54,5 @@ export type SectionProps = Omit<WidgetHeaderProps, 'tier'> & {
     id?: string;
     children: ReactNode;
 };
-export declare function Section({ title, icon, subtitle, info, value, delta, deltaPeriod, sparkline, count, actions, tabs, collapsible, persistKey, defaultOpen, summary, id, children, }: SectionProps): import("react").JSX.Element;
+export declare function Section({ actions, query, empty, tabs, collapsible, persistKey, defaultOpen, summary, id, children, className, style, classNames, ...headerProps }: SectionProps): import("react").JSX.Element;
 //# sourceMappingURL=section.d.ts.map

package/dist/section/section.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"section.d.ts","sourceRoot":"","sources":["../../src/section/section.tsx"],"names":[],"mappings":"AA8CA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAGzD,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC,GAAG;IAC3D,gGAAgG;IAChG,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB;8CAC0C;IAC1C,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB;uBACmB;IACnB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;uGACmG;IACnG,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB;;uDAEmD;IACnD,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB,qGAAqG;IACrG,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,QAAQ,EAAE,SAAS,CAAA;CACpB,CAAA;AAgFD,wBAAgB,OAAO,CAAC,EACtB,KAAK,EACL,IAAI,EACJ,QAAQ,EACR,IAAI,EACJ,KAAK,EACL,KAAK,EACL,WAAW,EACX,SAAS,EACT,KAAK,EACL,OAAO,EACP,IAAI,EACJ,WAAmB,EACnB,UAAU,EACV,WAAkB,EAClB,OAAO,EACP,EAAE,EACF,QAAQ,GACT,EAAE,YAAY,+BAiDd"}
+{"version":3,"file":"section.d.ts","sourceRoot":"","sources":["../../src/section/section.tsx"],"names":[],"mappings":"AAiDA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEtC,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAKnE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAGtD,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAG9E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAGzD;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAA;AAMpD,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,iBAAiB,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAAC,GACnF,WAAW,GACX,eAAe,CAAC,WAAW,CAAC,GAAG;IAC7B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,WAAW,CAAA;IACrB;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE,cAAc,CAAC,OAAO,CAAC,CAAA;IAC/B;;;;OAIG;IACH,KAAK,CAAC,EAAE,cAAc,CAAA;IACtB,gGAAgG;IAChG,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB;8CAC0C;IAC1C,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB;uBACmB;IACnB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;uGACmG;IACnG,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB;;uDAEmD;IACnD,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB,qGAAqG;IACrG,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,QAAQ,EAAE,SAAS,CAAA;CACpB,CAAA;AAyDH,wBAAgB,OAAO,CAAC,EACtB,OAAO,EACP,KAAK,EACL,KAAK,EACL,IAAI,EACJ,WAAmB,EACnB,UAAU,EACV,WAAkB,EAClB,OAAO,EACP,EAAE,EACF,QAAQ,EACR,SAAS,EACT,KAAK,EACL,UAAU,EACV,GAAG,WAAW,EACf,EAAE,YAAY,+BA4Fd"}

package/dist/section/section.js

@@ -1,34 +1,19 @@
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
-import { Children, useId, useMemo, useState } from "react";
+import { Children, useId } from "react";
+import { cx } from "../common/props.js";
+import { BASALT_PREFIX } from "../common/errors.js";
+import { useValidateProps } from "../common/validate.js";
 import { CtlSlot } from "../theme/index.js";
-import { createPersistedState } from "../state.js";
+import { BarActionSlot, isBarActionList } from "../controls/actions.js";
+import { useFilterSurface } from "../controls/filter-context.js";
+import { QueryState } from "../dashboard/query-state.js";
+import { usePersistedOrLocal } from "../state/persisted-or-local.js";
 import { WidgetHeader } from "../widget-header/index.js";
 import classes from "./section.module.css";
-function isDev() {
-  return process.env["NODE_ENV"] !== "production";
-}
-function warnPastActionBudget(title, actions) {
-  if (!isDev()) return;
-  const count = Children.count(actions);
-  if (count <= 3) return;
-  console.warn(
-    `Section "${title}": ${count} actions exceeds the \u22643 budget (docs/CONTROLS-SPEC.md C6) \u2014 move the rest behind a menu.`
-  );
-}
-const UNPERSISTED_KEY = "__local__";
-function useSectionOpen(persistKey, defaultOpen) {
-  const [localOpen, setLocalOpen] = useState(defaultOpen);
-  const usePersistedOpen = useMemo(
-    () => createPersistedState({
-      key: `section:${persistKey ?? UNPERSISTED_KEY}`,
-      version: 1,
-      initial: defaultOpen
-    }),
-    [persistKey, defaultOpen]
-  );
-  const [persistedOpen, setPersistedOpen] = usePersistedOpen();
-  if (persistKey !== void 0) return [persistedOpen, setPersistedOpen];
-  return [localOpen, setLocalOpen];
+function actionBudgetMessage(title, actions) {
+  const count = isBarActionList(actions) ? actions.length : Children.count(actions);
+  if (count <= 3) return null;
+  return `${BASALT_PREFIX} Section "${title}": ${count} actions exceeds the \u22643 budget (docs/CONTROLS-SPEC.md C6) \u2014 move the rest behind a menu.`;
 }
 function ChevronToggle({
   open,
@@ -62,61 +47,68 @@ function ChevronToggle({
   );
 }
 function Section({
-  title,
-  icon,
-  subtitle,
-  info,
-  value,
-  delta,
-  deltaPeriod,
-  sparkline,
-  count,
   actions,
+  query,
+  empty,
   tabs,
   collapsible = false,
   persistKey,
   defaultOpen = true,
   summary,
   id,
-  children
+  children,
+  className,
+  style,
+  classNames,
+  ...headerProps
 }) {
-  const [open, setOpen] = useSectionOpen(persistKey, defaultOpen);
+  const { title } = headerProps;
+  useValidateProps(
+    "Section",
+    () => [
+      persistKey !== void 0 && !collapsible ? `${BASALT_PREFIX} Section "${title}": \`persistKey\` is set but \`collapsible\` is false \u2014 there is no fold to persist. Add \`collapsible\`, or drop \`persistKey\`.` : null,
+      actions === void 0 ? null : actionBudgetMessage(title, actions)
+    ],
+    [persistKey, collapsible, title, actions]
+  );
+  const [open, setOpen] = usePersistedOrLocal({
+    scope: "section",
+    persistKey,
+    initial: defaultOpen
+  });
   const bodyId = useId();
-  if (actions !== void 0) warnPastActionBudget(title, actions);
+  const tier = useFilterSurface() === "pill" ? "section" : "group";
+  const anchorStyle = id === void 0 ? void 0 : { scrollMarginTop: "var(--vx-space-sticky-header-clearance)" };
+  const rootStyle = anchorStyle === void 0 && style === void 0 ? void 0 : { ...anchorStyle, ...style };
   const headerActions = tabs !== void 0 || actions !== void 0 || collapsible ? /* @__PURE__ */ jsxs(Fragment, { children: [
     tabs !== void 0 && open && /* @__PURE__ */ jsx(CtlSlot, { children: tabs }),
-    actions !== void 0 && /* @__PURE__ */ jsx(CtlSlot, { children: actions }),
+    actions !== void 0 && /* @__PURE__ */ jsx(CtlSlot, { children: /* @__PURE__ */ jsx(BarActionSlot, { actions }) }),
     collapsible && /* @__PURE__ */ jsx(ChevronToggle, { open, onToggle: () => setOpen(!open), controls: bodyId })
   ] }) : void 0;
   return /* @__PURE__ */ jsxs(
     "div",
     {
-      className: classes.root,
+      className: cx(classes.root, classNames?.root, className),
+      "data-tier": tier,
       ...id !== void 0 && { id },
-      ...id !== void 0 && {
-        style: {
-          scrollMarginTop: "calc(var(--app-shell-header-height, 0px) + var(--basalt-page-bar-h, 0px))"
-        }
-      },
+      ...rootStyle !== void 0 && { style: rootStyle },
       children: [
         /* @__PURE__ */ jsx(
           WidgetHeader,
           {
-            tier: "section",
-            title,
-            ...icon !== void 0 && { icon },
-            ...subtitle !== void 0 && { subtitle },
-            ...info !== void 0 && { info },
-            ...value !== void 0 && { value },
-            ...delta !== void 0 && { delta },
-            ...deltaPeriod !== void 0 && { deltaPeriod },
-            ...sparkline !== void 0 && { sparkline },
-            ...count !== void 0 && { count },
+            tier,
+            ...headerProps,
+            ...classNames?.header !== void 0 && { className: classNames.header },
             ...headerActions !== void 0 && { actions: headerActions }
           }
         ),
         summary !== void 0 && /* @__PURE__ */ jsx("div", { className: classes.summary, children: summary }),
-        open && /* @__PURE__ */ jsx("div", { id: bodyId, className: classes.body, children })
+        open && /* @__PURE__ */ jsx("div", { id: bodyId, className: cx(classes.body, classNames?.body), children: query === void 0 ? children : (
+          // `tier="section"` is the compact one: a bare spinner rather than a 64px centred
+          // block, and the error alert without the page-level stack around it. A Section IS the
+          // region, so the state belongs inside its body, never around its header.
+          /* @__PURE__ */ jsx(QueryState, { query, tier: "section", ...empty !== void 0 && { empty }, children })
+        ) })
       ]
     }
   );

package/dist/section/section.module.css

@@ -22,6 +22,17 @@
   gap: var(--vx-space-stack-md, 0.75rem);
 }
 
+/*
+ * `group` tier (an aside/inspector Section): zero gap between children. `PanelRow`s already own
+ * their own vertical rhythm — `--vx-space-row-inset-y` (6px) plus the `.row + .row` hairline — so
+ * stacking the 12px `stack-md` gap ON TOP made a one-line row's pitch 55px with the hairline sitting
+ * 33/22 off-centre in it. At gap 0 the pitch is 43px and the rule is centred (Trellis ≈29, Quiver
+ * ≈33, the sidebar's own rows 33) — no negative margins, the gap simply isn't there to fight.
+ */
+.root[data-tier='group'] .body {
+  gap: 0;
+}
+
 /*
  * `summary` — the always-visible row under the header. No border, no background (the Section owns
  * neither); it is a plain flow row, so a consumer's `Group` of stats or one line of `Text` lands

package/dist/shell/account-types.d.ts

@@ -5,8 +5,11 @@
  * on any auth library and ships no `./auth` subpath — this is the seam, not an adapter.
  */
 import type { ReactNode } from 'react';
-/** Badge tone for a role/plan chip. No dedicated tone union exists elsewhere in the shell/tokens
- * layers, so this is defined locally. */
+/**
+ * Badge tone for a role/plan chip. A different member set from `common`'s `Tone` (`common/props.ts`,
+ * audit A13) — `'neutral' | 'brand'` have no `Tone` equivalent — so this stays its own type rather
+ * than an alias; see `Tone` for the base three-tone vocabulary the rest of the framework shares.
+ */
 export type AccountBadgeTone = 'neutral' | 'brand' | 'success' | 'warn';
 /** The signed-in user's identity. `image` is nullable and currently unused by `SidebarAccount`
  * (which renders a generic, non-personalized icon rather than an avatar/initials) — kept on the

package/dist/shell/account-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"account-types.d.ts","sourceRoot":"","sources":["../../src/shell/account-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEtC;yCACyC;AACzC,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAA;AAEvE;;uFAEuF;AACvF,MAAM,MAAM,cAAc,GAAG;IAC3B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB,CAAA;AAED,yDAAyD;AACzD,MAAM,MAAM,UAAU,GAAG;IACvB,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,gBAAgB,CAAA;CACxB,CAAA;AAED,8EAA8E;AAC9E,MAAM,MAAM,UAAU,GAAG;IACvB,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,UAAU,GAAG,UAAU,GAAG,MAAM,CAAA;IACjE,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,QAAQ,CAAC,EAAE,IAAI,GAAG,IAAI,CAAA;IACtB,IAAI,CAAC,EAAE,gBAAgB,CAAA;CACxB,CAAA;AAED,mGAAmG;AACnG,MAAM,MAAM,eAAe,GAAG;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,OAAO,EAAE,MAAM,IAAI,CAAA;IACnB,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,GACrB;IAAE,MAAM,EAAE,iBAAiB,CAAA;CAAE,GAC7B;IAAE,MAAM,EAAE,eAAe,CAAC;IAAC,QAAQ,EAAE,cAAc,CAAC;IAAC,IAAI,CAAC,EAAE,UAAU,CAAC;IAAC,IAAI,CAAC,EAAE,UAAU,CAAA;CAAE,CAAA;AAE/F,kGAAkG;AAClG,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAA;IACrB,SAAS,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACtC,eAAe,CAAC,EAAE,MAAM,IAAI,CAAA;IAC5B,eAAe,CAAC,EAAE,MAAM,IAAI,CAAA;IAC5B,gDAAgD;IAChD,SAAS,CAAC,EAAE,MAAM,IAAI,CAAA;IACtB,cAAc,CAAC,EAAE,eAAe,EAAE,CAAA;CACnC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,KAAK,EAAE,kBAAkB,CAAA;IACzB,OAAO,CAAC,EAAE,oBAAoB,CAAA;IAC9B;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB,CAAA"}
+{"version":3,"file":"account-types.d.ts","sourceRoot":"","sources":["../../src/shell/account-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEtC;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAA;AAEvE;;uFAEuF;AACvF,MAAM,MAAM,cAAc,GAAG;IAC3B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB,CAAA;AAED,yDAAyD;AACzD,MAAM,MAAM,UAAU,GAAG;IACvB,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,gBAAgB,CAAA;CACxB,CAAA;AAED,8EAA8E;AAC9E,MAAM,MAAM,UAAU,GAAG;IACvB,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,UAAU,GAAG,UAAU,GAAG,MAAM,CAAA;IACjE,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,QAAQ,CAAC,EAAE,IAAI,GAAG,IAAI,CAAA;IACtB,IAAI,CAAC,EAAE,gBAAgB,CAAA;CACxB,CAAA;AAED,mGAAmG;AACnG,MAAM,MAAM,eAAe,GAAG;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,OAAO,EAAE,MAAM,IAAI,CAAA;IACnB,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,GACrB;IAAE,MAAM,EAAE,iBAAiB,CAAA;CAAE,GAC7B;IAAE,MAAM,EAAE,eAAe,CAAC;IAAC,QAAQ,EAAE,cAAc,CAAC;IAAC,IAAI,CAAC,EAAE,UAAU,CAAC;IAAC,IAAI,CAAC,EAAE,UAAU,CAAA;CAAE,CAAA;AAE/F,kGAAkG;AAClG,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAA;IACrB,SAAS,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACtC,eAAe,CAAC,EAAE,MAAM,IAAI,CAAA;IAC5B,eAAe,CAAC,EAAE,MAAM,IAAI,CAAA;IAC5B,gDAAgD;IAChD,SAAS,CAAC,EAAE,MAAM,IAAI,CAAA;IACtB,cAAc,CAAC,EAAE,eAAe,EAAE,CAAA;CACnC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,KAAK,EAAE,kBAAkB,CAAA;IACzB,OAAO,CAAC,EAAE,oBAAoB,CAAA;IAC9B;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB,CAAA"}

package/dist/shell/app-brand.d.ts

@@ -0,0 +1,13 @@
+import type { BasaltProps } from '../common/props.js';
+import type { AccountMenuItem } from './account-types.js';
+import type { BrandConfig } from './index.js';
+export type AppBrandProps = BasaltProps & {
+    brand: BrandConfig & {
+        menu?: AccountMenuItem[];
+    };
+    /** Desktop rail state — the zone narrows with the navbar and shows the toggle alone. */
+    collapsed: boolean;
+    onToggleCollapse: () => void;
+};
+export declare function AppBrand({ brand, collapsed, onToggleCollapse, className, style }: AppBrandProps): import("react").JSX.Element;
+//# sourceMappingURL=app-brand.d.ts.map

package/dist/shell/app-brand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-brand.d.ts","sourceRoot":"","sources":["../../src/shell/app-brand.tsx"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAClD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AA2E1C,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG;IACxC,KAAK,EAAE,WAAW,GAAG;QAAE,IAAI,CAAC,EAAE,eAAe,EAAE,CAAA;KAAE,CAAA;IACjD,wFAAwF;IACxF,SAAS,EAAE,OAAO,CAAA;IAClB,gBAAgB,EAAE,MAAM,IAAI,CAAA;CAC7B,CAAA;AAED,wBAAgB,QAAQ,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,aAAa,+BAuC/F"}

package/dist/shell/app-brand.js

@@ -0,0 +1,94 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import { ActionIcon, Group, Menu, Text, UnstyledButton } from "@mantine/core";
+import { cx } from "../common/props.js";
+import { IconChevron } from "./sidebar-blocks.js";
+import { VX } from "../tokens/index.js";
+import { useBasaltSpacing } from "../theme/index.js";
+import classes from "./app-brand.module.css";
+function IconCollapse({ collapsed }) {
+  return /* @__PURE__ */ jsxs(
+    "svg",
+    {
+      width: 18,
+      height: 18,
+      viewBox: "0 0 24 24",
+      fill: "none",
+      stroke: "currentColor",
+      strokeWidth: 2,
+      strokeLinecap: "round",
+      strokeLinejoin: "round",
+      "aria-hidden": true,
+      children: [
+        /* @__PURE__ */ jsx("path", { d: "M4 4h16v16H4z" }),
+        /* @__PURE__ */ jsx("path", { d: "M9 4v16" }),
+        collapsed ? /* @__PURE__ */ jsx("path", { d: "M14 9l3 3l-3 3" }) : /* @__PURE__ */ jsx("path", { d: "M16 9l-3 3l3 3" })
+      ]
+    }
+  );
+}
+function BrandName({
+  brand,
+  menuWidth
+}) {
+  const label = /* @__PURE__ */ jsx(Text, { className: classes.brandName, fz: VX.text.xl, fw: 550, children: brand.name });
+  const menu = brand.menu;
+  if (menu === void 0 || menu.length === 0) return label;
+  return /* @__PURE__ */ jsxs(Menu, { position: "bottom-start", withArrow: true, width: menuWidth, zIndex: 500, children: [
+    /* @__PURE__ */ jsx(Menu.Target, { children: /* @__PURE__ */ jsxs(UnstyledButton, { className: classes.brandButton, "aria-label": `${brand.name} workspace`, children: [
+      label,
+      /* @__PURE__ */ jsx(IconChevron, { open: true })
+    ] }) }),
+    /* @__PURE__ */ jsx(Menu.Dropdown, { children: menu.map((entry) => /* @__PURE__ */ jsx(
+      Menu.Item,
+      {
+        leftSection: entry.icon,
+        ...entry.danger === true && { color: "red" },
+        onClick: entry.onClick,
+        children: entry.label
+      },
+      entry.key
+    )) })
+  ] });
+}
+function AppBrand({ brand, collapsed, onToggleCollapse, className, style }) {
+  const { step } = useBasaltSpacing();
+  return /* @__PURE__ */ jsxs(
+    Group,
+    {
+      className: cx(classes.brand, className),
+      gap: "sm",
+      wrap: "nowrap",
+      ...style !== void 0 && { style },
+      children: [
+        /* @__PURE__ */ jsxs(Group, { className: classes.brandLead, gap: "sm", wrap: "nowrap", children: [
+          brand.logoSrc && /* @__PURE__ */ jsx(
+            "img",
+            {
+              src: brand.logoSrc,
+              alt: brand.logoAlt ?? brand.name,
+              width: 26,
+              height: 26,
+              style: { display: "block" }
+            }
+          ),
+          /* @__PURE__ */ jsx(BrandName, { brand, menuWidth: step.sidebarAccountMenuWidth })
+        ] }),
+        /* @__PURE__ */ jsx(
+          ActionIcon,
+          {
+            variant: "subtle",
+            size: 28,
+            visibleFrom: "sm",
+            className: classes.ghostIcon,
+            onClick: onToggleCollapse,
+            "aria-label": collapsed ? "Expand sidebar" : "Collapse sidebar",
+            children: /* @__PURE__ */ jsx(IconCollapse, { collapsed })
+          }
+        )
+      ]
+    }
+  );
+}
+export {
+  AppBrand
+};

package/dist/shell/app-brand.module.css

@@ -0,0 +1,109 @@
+/*
+ * The header's leading zone (docs/DESIGN-SPEC.md §5). Moved here from `app-sidebar.module.css`
+ * verbatim — the brand did not change, only where it is painted.
+ *
+ * NO border and no background: the zone is part of the header row, so the header's own
+ * `AppShell.Header` region seam is the only line under it. The sidebar column below now starts
+ * directly with `SidebarSearch`.
+ *
+ * The zone's WIDTH is `--app-shell-navbar-offset`, so it tracks the rail collapse with no React
+ * state and lands its trailing edge exactly on the sidebar|main seam. The negative
+ * `margin-inline-start` cancels `AppShell.Header`'s own `px` inset so the zone starts at the
+ * viewport edge and re-applies that inset as padding — which is what puts the brand lead on the
+ * same x as the sidebar rows below it.
+ */
+.zone {
+  flex: 0 0 var(--app-shell-navbar-offset, 0rem);
+  width: var(--app-shell-navbar-offset, 0rem);
+  min-width: 0;
+  display: flex;
+  align-items: center;
+  /* The full header row, not just the toggle's own 28px — so the zone's box is the band it looks
+   * like, and the rail's centred toggle centres against the whole row. */
+  align-self: stretch;
+  margin-inline-start: calc(-1 * var(--app-shell-padding, 0px));
+  padding-inline: var(--app-shell-padding, 0px);
+  overflow: hidden;
+  /* Mantine's own AppShell timing, so the zone and the navbar under it move as one box. */
+  transition-property: flex-basis, width;
+  transition-duration: var(--app-shell-transition-duration);
+  transition-timing-function: var(--app-shell-transition-timing-function);
+}
+
+/* Below `sm` there is no navbar at all (the bottom bar is the whole nav), so the zone would be a
+ * zero-width box holding a hidden toggle. The breadcrumb owns the phone header's lead. */
+@media (max-width: 47.99375em) {
+  .zone {
+    display: none;
+  }
+}
+
+.brand {
+  justify-content: space-between;
+  align-items: center;
+  flex: 1 1 auto;
+  min-width: 0;
+  height: 100%;
+}
+
+.brandLead {
+  min-width: 0;
+}
+
+/* Brand name — head font at stretch 88% (docs/DESIGN-SPEC.md §3); the 18px/550 land as `fz`/`fw`
+ * props (inline, deterministic against Mantine's own Text base rule). */
+.brandName {
+  font-family: var(--basalt-font-head);
+  font-stretch: 88%;
+}
+
+/* Workspace switcher (`brand.menu`) — the brand name plus a chevron, as a row-shaped trigger. The
+ * chevron is faint until hover so the brand still reads as the brand, not as a control. */
+.brandButton {
+  display: flex;
+  align-items: center;
+  gap: var(--vx-space-sidebar-section-label-gap);
+  min-width: 0;
+  padding: 0;
+  color: var(--vx-faint);
+  cursor: pointer;
+}
+
+.brandButton:hover {
+  color: var(--vx-ink);
+}
+
+/*
+ * Icon-only ghost button in shell chrome (the collapse toggle) — docs/DESIGN-SPEC.md §5:
+ * transparent, faint icon, hover ink-6% + ink, radius 6. `!important` because it competes with
+ * Mantine's own compiled ActionIcon variant CSS. This is the one copy — `sidebar-search.module.css`
+ * mirrors it rather than keeping its own duplicate.
+ */
+.ghostIcon {
+  color: var(--vx-faint) !important;
+  border-radius: var(--vx-radius-ctrl) !important;
+}
+
+.ghostIcon:hover {
+  background-color: color-mix(in srgb, var(--vx-ink) 6%, transparent) !important;
+  color: var(--vx-ink) !important;
+}
+
+/*
+ * The rail form, mirroring exactly what the sidebar's own brand row did when collapsed: the lead
+ * (logo + name) hides and the toggle centres. The zone drops its inset so the toggle's centre lands
+ * on the rail's icon column rather than 13px right of it.
+ */
+@media (min-width: 48em) {
+  .zone[data-collapsed] {
+    padding-inline: 0;
+  }
+
+  .zone[data-collapsed] .brand {
+    justify-content: center;
+  }
+
+  .zone[data-collapsed] .brandLead {
+    display: none;
+  }
+}

package/dist/shell/app-brand.module.css.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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. HAND-MAINTAINED:
+ * there is no generator, so a new class in `app-brand.module.css` must be added here too.
+ */
+declare const classes: {
+  readonly zone: string
+  readonly brand: string
+  readonly brandLead: string
+  readonly brandName: string
+  readonly brandButton: string
+  readonly ghostIcon: string
+}
+export default classes

package/dist/shell/app-breadcrumbs.d.ts

@@ -1,5 +1,6 @@
 import type { NavAnchor } from '../nav/types.js';
-export declare function AppBreadcrumbs({ section, parent, parentAnchor, parentHref, page, }: {
+import type { BasaltProps } from '../common/props.js';
+export type AppBreadcrumbsProps = BasaltProps & {
     section?: string;
     /** Parent item label — shown when the active page is a nested child (e.g. "Dashboard"). */
     parent?: string | undefined;
@@ -11,5 +12,6 @@ export declare function AppBreadcrumbs({ section, parent, parentAnchor, parentHr
     /** Parent item href — the no-router fallback; ignored when `parentAnchor` is present. */
     parentHref?: string | undefined;
     page?: string;
-}): import("react").JSX.Element | null;
+};
+export declare function AppBreadcrumbs({ section, parent, parentAnchor, parentHref, page, className, style, }: AppBreadcrumbsProps): import("react").JSX.Element | null;
 //# sourceMappingURL=app-breadcrumbs.d.ts.map

package/dist/shell/app-breadcrumbs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app-breadcrumbs.d.ts","sourceRoot":"","sources":["../../src/shell/app-breadcrumbs.tsx"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAmB7C,wBAAgB,cAAc,CAAC,EAC7B,OAAO,EACP,MAAM,EACN,YAAY,EACZ,UAAU,EACV,IAAI,GACL,EAAE;IACD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,2FAA2F;IAC3F,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3B;;;OAGG;IACH,YAAY,CAAC,EAAE,SAAS,GAAG,SAAS,CAAA;IACpC,yFAAyF;IACzF,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAA;CACd,sCAqDA"}
+{"version":3,"file":"app-breadcrumbs.d.ts","sourceRoot":"","sources":["../../src/shell/app-breadcrumbs.tsx"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAE7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAkBlD,MAAM,MAAM,mBAAmB,GAAG,WAAW,GAAG;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,2FAA2F;IAC3F,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3B;;;OAGG;IACH,YAAY,CAAC,EAAE,SAAS,GAAG,SAAS,CAAA;IACpC,yFAAyF;IACzF,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAA;CACd,CAAA;AAED,wBAAgB,cAAc,CAAC,EAC7B,OAAO,EACP,MAAM,EACN,YAAY,EACZ,UAAU,EACV,IAAI,EACJ,SAAS,EACT,KAAK,GACN,EAAE,mBAAmB,sCA0DrB"}

package/dist/shell/app-breadcrumbs.js

@@ -16,30 +16,41 @@ function AppBreadcrumbs({
   parent,
   parentAnchor,
   parentHref,
-  page
+  page,
+  className,
+  style
 }) {
   if (!page) return null;
-  return /* @__PURE__ */ jsxs(Group, { gap: 6, wrap: "nowrap", style: { minWidth: 0 }, children: [
-    (section !== void 0 || parent !== void 0) && /* @__PURE__ */ jsxs(Group, { gap: 6, wrap: "nowrap", className: classes.crumbAncestors, style: { minWidth: 0 }, children: [
-      section && /* @__PURE__ */ jsxs(Fragment, { children: [
-        /* @__PURE__ */ jsx(Text, { style: crumbStyle, truncate: true, children: section }),
-        /* @__PURE__ */ jsx(Text, { style: separatorStyle, children: "/" })
-      ] }),
-      parent && parentAnchor && /* @__PURE__ */ jsxs(Fragment, { children: [
-        /* @__PURE__ */ jsx(Anchor, { style: crumbStyle, underline: "never", component: parentAnchor, truncate: true, children: parent }),
-        /* @__PURE__ */ jsx(Text, { style: separatorStyle, children: "/" })
-      ] }),
-      parent && !parentAnchor && parentHref && /* @__PURE__ */ jsxs(Fragment, { children: [
-        /* @__PURE__ */ jsx(Anchor, { style: crumbStyle, underline: "never", href: parentHref, truncate: true, children: parent }),
-        /* @__PURE__ */ jsx(Text, { style: separatorStyle, children: "/" })
-      ] }),
-      parent && !parentAnchor && !parentHref && /* @__PURE__ */ jsxs(Fragment, { children: [
-        /* @__PURE__ */ jsx(Text, { style: crumbStyle, truncate: true, children: parent }),
-        /* @__PURE__ */ jsx(Text, { style: separatorStyle, children: "/" })
-      ] })
-    ] }),
-    /* @__PURE__ */ jsx(Text, { style: currentStyle, truncate: true, children: page })
-  ] });
+  return /* @__PURE__ */ jsxs(
+    Group,
+    {
+      gap: 6,
+      wrap: "nowrap",
+      ...className !== void 0 && { className },
+      style: { minWidth: 0, ...style },
+      children: [
+        (section !== void 0 || parent !== void 0) && /* @__PURE__ */ jsxs(Group, { gap: 6, wrap: "nowrap", className: classes.crumbAncestors, style: { minWidth: 0 }, children: [
+          section && /* @__PURE__ */ jsxs(Fragment, { children: [
+            /* @__PURE__ */ jsx(Text, { style: crumbStyle, truncate: true, children: section }),
+            /* @__PURE__ */ jsx(Text, { style: separatorStyle, children: "/" })
+          ] }),
+          parent && parentAnchor && /* @__PURE__ */ jsxs(Fragment, { children: [
+            /* @__PURE__ */ jsx(Anchor, { style: crumbStyle, underline: "never", component: parentAnchor, truncate: true, children: parent }),
+            /* @__PURE__ */ jsx(Text, { style: separatorStyle, children: "/" })
+          ] }),
+          parent && !parentAnchor && parentHref && /* @__PURE__ */ jsxs(Fragment, { children: [
+            /* @__PURE__ */ jsx(Anchor, { style: crumbStyle, underline: "never", href: parentHref, truncate: true, children: parent }),
+            /* @__PURE__ */ jsx(Text, { style: separatorStyle, children: "/" })
+          ] }),
+          parent && !parentAnchor && !parentHref && /* @__PURE__ */ jsxs(Fragment, { children: [
+            /* @__PURE__ */ jsx(Text, { style: crumbStyle, truncate: true, children: parent }),
+            /* @__PURE__ */ jsx(Text, { style: separatorStyle, children: "/" })
+          ] })
+        ] }),
+        /* @__PURE__ */ jsx(Text, { style: currentStyle, truncate: true, children: page })
+      ]
+    }
+  );
 }
 export {
   AppBreadcrumbs

package/dist/shell/app-header.module.css

@@ -1,5 +1,9 @@
-/* App-shell top bar layout. ONE 48px row on every viewport —
- * [breadcrumb] ········ [page bar row 1] | [global actions].
+/* App-shell top bar layout. ONE 48px row on every viewport, spanning the FULL viewport width —
+ * [brand | collapse] [breadcrumb] ········ [page bar row 1] | [global actions].
+ *
+ * The leading zone is `app-brand.module.css`'s `.zone`: exactly `--app-shell-navbar-offset` wide,
+ * so its trailing edge lands on the sidebar|main seam and the breadcrumb after it starts on Main's
+ * own content edge. It is absent below `sm`, where there is no navbar to align with.
  *
  * The pre-1.26.0 mobile layout wrapped to a second, always-reserved row for the page actions and
  * scrolled it sideways. Both are gone (law C7 and law C14): the header height is now the
@@ -7,9 +11,10 @@
  * folds into `ActionGroup`'s kebab instead of scrolling out of view. */
 
 /*
- * Transparent header (docs/DESIGN-SPEC.md §5): NO bottom rule at all. The header and the page body
- * share the same page background, so a separator only draws a line across an already-continuous
- * surface. The AppShell's own built-in border is disabled too (`withBorder={false}` in index.tsx).
+ * Transparent header (docs/DESIGN-SPEC.md §5): background stays the page body's own. Its bottom
+ * edge is the `AppShell.Header` region seam, drawn by Mantine off `--app-shell-border-color` →
+ * `--vx-divider`, running edge to edge now that the shell uses Mantine's DEFAULT layout rather than
+ * `alt` — never a border in this module.
  */
 .bar {
   display: flex;