basalt-ui 1.26.0 → 1.28.0

package/dist/shell/isomorphic-layout-effect.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Internal — `useLayoutEffect` in the browser, `useEffect` on the server.
+ *
+ * The standard isomorphic pattern, so an SSR render never trips React's "useLayoutEffect does
+ * nothing on the server" warning. The branch reads a global that cannot change between renders, so
+ * the hook identity is stable across every render of every caller.
+ *
+ * One module rather than one `const` per file: `page-bar.tsx` and `page-aside.tsx` declared the
+ * same line with the same doc, and the second copy's doc already said "see `page-bar.tsx`'s copy".
+ * Not exported from any barrel — this is a shell-internal utility, not a published hook.
+ */
+import { useEffect } from 'react';
+export declare const useIsomorphicLayoutEffect: typeof useEffect;
+//# sourceMappingURL=isomorphic-layout-effect.d.ts.map

package/dist/shell/isomorphic-layout-effect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"isomorphic-layout-effect.d.ts","sourceRoot":"","sources":["../../src/shell/isomorphic-layout-effect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,SAAS,EAAmB,MAAM,OAAO,CAAA;AAElD,eAAO,MAAM,yBAAyB,kBAA8D,CAAA"}

package/dist/shell/isomorphic-layout-effect.js

@@ -0,0 +1,5 @@
+import { useEffect, useLayoutEffect } from "react";
+const useIsomorphicLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
+export {
+  useIsomorphicLayoutEffect
+};

package/dist/shell/mobile-nav-model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mobile-nav-model.d.ts","sourceRoot":"","sources":["../../src/shell/mobile-nav-model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EACV,eAAe,EAEf,cAAc,EAGd,YAAY,EAEZ,cAAc,EACf,MAAM,cAAc,CAAA;AAGrB,mGAAmG;AACnG,eAAO,MAAM,uBAAuB,IAAI,CAAA;AAExC;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,IAAI,CAAA;AAExC,iGAAiG;AACjG,eAAO,MAAM,eAAe,WAAW,CAAA;AAEvC,MAAM,MAAM,uBAAuB,GAAG;IACpC,MAAM,CAAC,EAAE,eAAe,GAAG,SAAS,CAAA;IACpC;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB,CAAA;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,GAAG,SAAS,GAAG,MAAM,CAQjF;AAgSD;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,cAAc,EAAE,EAC1B,IAAI,CAAC,EAAE,uBAAuB,GAC7B,cAAc,CA2EhB"}
+{"version":3,"file":"mobile-nav-model.d.ts","sourceRoot":"","sources":["../../src/shell/mobile-nav-model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EACV,eAAe,EAEf,cAAc,EAGd,YAAY,EAEZ,cAAc,EACf,MAAM,cAAc,CAAA;AAGrB,mGAAmG;AACnG,eAAO,MAAM,uBAAuB,IAAI,CAAA;AAExC;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,IAAI,CAAA;AAExC,iGAAiG;AACjG,eAAO,MAAM,eAAe,WAAW,CAAA;AAEvC,MAAM,MAAM,uBAAuB,GAAG;IACpC,MAAM,CAAC,EAAE,eAAe,GAAG,SAAS,CAAA;IACpC;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB,CAAA;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,GAAG,SAAS,GAAG,MAAM,CAQjF;AAwVD;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,cAAc,EAAE,EAC1B,IAAI,CAAC,EAAE,uBAAuB,GAC7B,cAAc,CA2EhB"}

package/dist/shell/mobile-nav-model.js

@@ -43,6 +43,12 @@ function flattenItems(items, out) {
     flattenItems(item.children ?? [], out);
   }
 }
+function pushWithChildren(out, item, children) {
+  const next = { ...item };
+  if (children.length > 0) next.children = children;
+  else delete next.children;
+  out.push(next);
+}
 function pruneTree(items, keep) {
   const out = [];
   for (const item of items) {
@@ -51,10 +57,24 @@ function pruneTree(items, keep) {
       out.push(...children);
       continue;
     }
-    const next = { ...item };
-    if (children.length > 0) next.children = children;
-    else delete next.children;
-    out.push(next);
+    pushWithChildren(out, item, children);
+  }
+  return out;
+}
+function pruneOverflowTree(items, isHidden, isCovered) {
+  const out = [];
+  for (const item of items) {
+    const children = pruneOverflowTree(item.children ?? [], isHidden, isCovered);
+    if (isHidden(item)) {
+      out.push(...children);
+      continue;
+    }
+    if (isCovered(item)) {
+      if (children.length === 0) continue;
+      out.push({ ...item, active: false, children });
+      continue;
+    }
+    pushWithChildren(out, item, children);
   }
   return out;
 }
@@ -183,9 +203,10 @@ function buildOverflow(sections, covered) {
   for (const section of sections) {
     const hidden = isSectionHidden(section);
     if (hidden) continue;
-    const items = pruneTree(
+    const items = pruneOverflowTree(
       section.items,
-      (item) => placementOf(item, hidden) !== "hidden" && !covered.has(item.key)
+      (item) => placementOf(item, hidden) === "hidden",
+      (item) => covered.has(item.key)
     );
     if (items.length === 0) continue;
     groups.push({ key: section.label, label: section.label, items });

package/dist/shell/nav-count-badge.d.ts

@@ -1,3 +1,7 @@
+import type { BasaltProps } from '../common/props.js';
+export type NavCountBadgeProps = BasaltProps & {
+    count: number;
+};
 /**
  * Sidebar nav count badge (docs/DESIGN-SPEC.md §5): mono micro (11px), ink-8% bg, radius 5, height 16,
  * padding 0 5px, muted text; `marginLeft: auto` pins it to the row end on any render path.
@@ -5,7 +9,5 @@
  * combinations land on the ink-tint idiom. Returns `null` for a zero/empty count so the badge slot
  * stays clean ("ink earns its color", DESIGN.md).
  */
-export declare function NavCountBadge({ count }: {
-    count: number;
-}): import("react").JSX.Element | null;
+export declare function NavCountBadge({ count, className, style }: NavCountBadgeProps): import("react").JSX.Element | null;
 //# sourceMappingURL=nav-count-badge.d.ts.map

package/dist/shell/nav-count-badge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"nav-count-badge.d.ts","sourceRoot":"","sources":["../../src/shell/nav-count-badge.tsx"],"names":[],"mappings":"AASA;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,EAAE,KAAK,EAAE,EAAE;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,sCAsBzD"}
+{"version":3,"file":"nav-count-badge.d.ts","sourceRoot":"","sources":["../../src/shell/nav-count-badge.tsx"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAElD,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAEhE;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,kBAAkB,sCAwB5E"}

package/dist/shell/nav-count-badge.js

@@ -1,12 +1,14 @@
 import { jsx } from "react/jsx-runtime";
 import { Badge } from "@mantine/core";
 import { VX } from "../tokens/index.js";
-function NavCountBadge({ count }) {
+function NavCountBadge({ count, className, style }) {
   if (!count) return null;
   return /* @__PURE__ */ jsx(
     Badge,
     {
       size: "sm",
+      ...className !== void 0 && { className },
+      ...style !== void 0 && { style },
       styles: {
         root: {
           backgroundColor: "color-mix(in srgb, var(--vx-ink) 8%, transparent)",

package/dist/shell/page-aside.d.ts

@@ -0,0 +1,43 @@
+import type { ReactNode } from 'react';
+import type { BasaltProps, SlotStylesProps } from '../common/props.js';
+type AsideRegion = {
+    /** The node inside `AppShell.Aside` the panel portals into. `null` outside a shell, and until
+     * the outlet mounts. */
+    target: HTMLElement | null;
+    setTarget: (el: HTMLElement | null) => void;
+    /** True only under `BasaltShell` — the provider is shell-internal, so the context IS the probe. */
+    inShell: boolean;
+    /** A page is rendering a `PageAside` into the region; until then it has zero width. */
+    claimed: boolean;
+    /** The claiming page's fold state, published back so the shell can size the region. */
+    folded: boolean;
+    claim: () => () => void;
+    publishFolded: (folded: boolean) => void;
+};
+/**
+ * Internal — mounted by `BasaltShell` inside `PageBarProvider`. Owns the portal target, the claim
+ * that turns the region on, and the mirrored fold flag the shell reads for `aside.width`.
+ */
+export declare function AsideProvider({ children }: {
+    children: ReactNode;
+}): ReactNode;
+/** Internal — the region's state, read by `BasaltShell` to size `AppShell.Aside`. */
+export declare function useAsideRegion(): Pick<AsideRegion, 'claimed' | 'folded'>;
+/** Internal — the node inside `AppShell.Aside` the active page's panel portals into. */
+export declare function AsideOutlet({ className }: {
+    className?: string;
+}): import("react").JSX.Element;
+/** The three boxes `PageAside` paints, in every projection (`common/props.ts`). */
+export type PageAsideSlot = 'root' | 'header' | 'body';
+export type PageAsideProps = BasaltProps & SlotStylesProps<PageAsideSlot> & {
+    /** Header label; also the accessible name of the region. */
+    title: string;
+    /** Persists the fold at `basalt:aside:<persistKey>`. Omit for an unpersisted fold. */
+    persistKey?: string;
+    /** Fold state on first render, respected only while nothing is persisted. @default false */
+    defaultFolded?: boolean;
+    children: ReactNode;
+};
+export declare function PageAside(props: PageAsideProps): ReactNode;
+export {};
+//# sourceMappingURL=page-aside.d.ts.map

package/dist/shell/page-aside.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-aside.d.ts","sourceRoot":"","sources":["../../src/shell/page-aside.tsx"],"names":[],"mappings":"AAqDA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAQnE,KAAK,WAAW,GAAG;IACjB;4BACwB;IACxB,MAAM,EAAE,WAAW,GAAG,IAAI,CAAA;IAC1B,SAAS,EAAE,CAAC,EAAE,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAA;IAC3C,mGAAmG;IACnG,OAAO,EAAE,OAAO,CAAA;IAChB,uFAAuF;IACvF,OAAO,EAAE,OAAO,CAAA;IAChB,uFAAuF;IACvF,MAAM,EAAE,OAAO,CAAA;IACf,KAAK,EAAE,MAAM,MAAM,IAAI,CAAA;IACvB,aAAa,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAA;CACzC,CAAA;AAcD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,GAAG,SAAS,CAyB9E;AAED,qFAAqF;AACrF,wBAAgB,cAAc,IAAI,IAAI,CAAC,WAAW,EAAE,SAAS,GAAG,QAAQ,CAAC,CAGxE;AAED,wFAAwF;AACxF,wBAAgB,WAAW,CAAC,EAAE,SAAS,EAAE,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,+BAGhE;AA8CD,mFAAmF;AACnF,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAA;AAEtD,MAAM,MAAM,cAAc,GAAG,WAAW,GACtC,eAAe,CAAC,aAAa,CAAC,GAAG;IAC/B,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAA;IACb,sFAAsF;IACtF,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,4FAA4F;IAC5F,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,QAAQ,EAAE,SAAS,CAAA;CACpB,CAAA;AAoEH,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,CAqH1D"}

package/dist/shell/page-aside.js

@@ -0,0 +1,202 @@
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useMemo,
+  useState,
+  useSyncExternalStore
+} from "react";
+import { createPortal } from "react-dom";
+import { useMantineTheme } from "@mantine/core";
+import { cx } from "../common/props.js";
+import { assertRequiredProps } from "../common/validate.js";
+import { usePersistedOrLocal } from "../state/persisted-or-local.js";
+import { FilterSetScope } from "../controls/filter-context.js";
+import { useAsidePanelSlot } from "./page-bar.js";
+import { useIsomorphicLayoutEffect } from "./isomorphic-layout-effect.js";
+import classes from "./page-aside.module.css";
+const NO_REGION = {
+  target: null,
+  setTarget: () => {
+  },
+  inShell: false,
+  claimed: false,
+  folded: false,
+  claim: () => () => {
+  },
+  publishFolded: () => {
+  }
+};
+const AsideContext = createContext(NO_REGION);
+function AsideProvider({ children }) {
+  const [target, setTarget] = useState(null);
+  const [claims, setClaims] = useState(0);
+  const [folded, setFolded] = useState(false);
+  const claim = useCallback(() => {
+    setClaims((n) => n + 1);
+    return () => {
+      setClaims((n) => n - 1);
+      setFolded(false);
+    };
+  }, []);
+  const value = {
+    target,
+    setTarget,
+    inShell: true,
+    claimed: claims > 0,
+    folded,
+    claim,
+    publishFolded: setFolded
+  };
+  return /* @__PURE__ */ jsx(AsideContext.Provider, { value, children });
+}
+function useAsideRegion() {
+  const { claimed, folded } = useContext(AsideContext);
+  return { claimed, folded };
+}
+function AsideOutlet({ className }) {
+  const { setTarget } = useContext(AsideContext);
+  return /* @__PURE__ */ jsx("div", { ref: setTarget, className });
+}
+function mediaQueryList(query) {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") return null;
+  return window.matchMedia(query);
+}
+function useMediaQueryMatches(query, fallback) {
+  const list = useMemo(() => mediaQueryList(query), [query]);
+  const subscribe = useCallback(
+    (onStoreChange) => {
+      if (list === null) return () => {
+      };
+      list.addEventListener("change", onStoreChange);
+      return () => {
+        list.removeEventListener("change", onStoreChange);
+      };
+    },
+    [list]
+  );
+  const getSnapshot = useCallback(() => list?.matches ?? fallback, [list, fallback]);
+  const getServerSnapshot = useCallback(() => fallback, [fallback]);
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}
+function IconAsideFold({ folded }) {
+  return /* @__PURE__ */ jsxs(
+    "svg",
+    {
+      width: 16,
+      height: 16,
+      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: "M15 4v16" }),
+        folded ? /* @__PURE__ */ jsx("path", { d: "M10 9l-3 3l3 3" }) : /* @__PURE__ */ jsx("path", { d: "M8 9l3 3l-3 3" })
+      ]
+    }
+  );
+}
+function IconAsidePanel() {
+  return /* @__PURE__ */ jsxs(
+    "svg",
+    {
+      width: 16,
+      height: 16,
+      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: "M15 4v16" })
+      ]
+    }
+  );
+}
+function FoldButton({ folded, onToggle }) {
+  return /* @__PURE__ */ jsx(
+    "button",
+    {
+      type: "button",
+      className: classes.fold,
+      "aria-expanded": !folded,
+      "aria-label": folded ? "Expand panel" : "Collapse panel",
+      onClick: onToggle,
+      children: /* @__PURE__ */ jsx(IconAsideFold, { folded })
+    }
+  );
+}
+function PageAside(props) {
+  assertRequiredProps("PageAside", props, ["title"], {
+    title: "it names the region \u2014 it is the header text AND the `aria-label` on the landmark."
+  });
+  const { title, persistKey, defaultFolded = false, children, className, style, classNames } = props;
+  const { target, inShell, claim, publishFolded } = useContext(AsideContext);
+  const { host: panelHost, claim: claimPanel, target: panelTarget } = useAsidePanelSlot();
+  const theme = useMantineTheme();
+  const desktop = useMediaQueryMatches(`(min-width: ${theme.breakpoints.sm})`, true);
+  const [folded, setFolded] = usePersistedOrLocal({
+    scope: "aside",
+    persistKey,
+    initial: defaultFolded
+  });
+  const portalled = inShell && desktop;
+  const projected = !portalled && panelHost;
+  const [settled, setSettled] = useState(false);
+  const panelClaim = useMemo(() => ({ title, icon: /* @__PURE__ */ jsx(IconAsidePanel, {}) }), [title]);
+  useIsomorphicLayoutEffect(() => {
+    setSettled(true);
+  }, []);
+  useIsomorphicLayoutEffect(() => {
+    if (!portalled) return;
+    return claim();
+  }, [portalled, claim]);
+  useIsomorphicLayoutEffect(() => {
+    if (!portalled) return;
+    publishFolded(folded);
+  }, [portalled, folded, publishFolded]);
+  useIsomorphicLayoutEffect(() => {
+    if (!projected) return;
+    return claimPanel(panelClaim);
+  }, [projected, panelClaim, claimPanel]);
+  const panel = /* @__PURE__ */ jsx(
+    "section",
+    {
+      className: cx(classes.panel, classNames?.root, className),
+      "data-basalt-page-aside": portalled ? "shell" : "standalone",
+      "aria-label": title,
+      ...style !== void 0 && { style },
+      children: portalled && folded ? /* @__PURE__ */ jsx("div", { className: classes.rail, children: /* @__PURE__ */ jsx(FoldButton, { folded: true, onToggle: () => setFolded(false) }) }) : /* @__PURE__ */ jsxs(Fragment, { children: [
+        /* @__PURE__ */ jsxs("div", { className: cx(classes.header, classNames?.header), "data-basalt-page-aside-header": "", children: [
+          /* @__PURE__ */ jsx("span", { className: classes.title, children: title }),
+          portalled && /* @__PURE__ */ jsx(FoldButton, { folded: false, onToggle: () => setFolded(true) })
+        ] }),
+        /* @__PURE__ */ jsx("div", { className: cx(classes.body, classNames?.body), children: /* @__PURE__ */ jsx(FilterSetScope, { surface: "panel", registry: null, children }) })
+      ] })
+    }
+  );
+  if (projected) {
+    if (panelTarget === null) return null;
+    return createPortal(
+      /* @__PURE__ */ jsx(FilterSetScope, { surface: "sheet", registry: null, children }),
+      panelTarget
+    );
+  }
+  if (!portalled) return inShell && !settled ? null : panel;
+  if (target === null) return null;
+  return createPortal(panel, target);
+}
+export {
+  AsideOutlet,
+  AsideProvider,
+  PageAside,
+  useAsideRegion
+};

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

@@ -0,0 +1,174 @@
+/*
+ * `PageAside` chrome (`docs/ASIDE-SPEC.md` §0, wave 1).
+ *
+ * Two forms, one class set, told apart by `data-basalt-page-aside`: `"shell"` is the portalled
+ * panel that fills `AppShell.Aside` and owns the region's paint, `"standalone"` is the in-flow node
+ * a phone (or a shell-less app) renders where the page wrote it — plain flow content, no surface of
+ * its own, exactly like the block that used to live in the page's second column.
+ */
+
+/* The `AppShell.Aside` inner node the panel portals into — a bare box, so an UNCLAIMED region
+ * paints nothing at all (law C14). Every pixel of chrome belongs to `.panel` below. */
+.outlet {
+  display: flex;
+  height: 100%;
+}
+
+.panel {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  gap: var(--vx-space-stack-md, 0.75rem);
+}
+
+/*
+ * The portalled form. Paints only the page background (the same surface the sidebar and the sticky
+ * page bar sit on — neither declares one, both inherit the body). The leading edge is the
+ * `AppShell.Aside` region seam (docs/DESIGN-SPEC.md §5) — same token, same pixel, now produced by
+ * the same rule as the other three region edges, so two 1px lines can never sit side by side.
+ */
+.panel[data-basalt-page-aside='shell'] {
+  flex: 1;
+  height: 100%;
+  gap: 0;
+  background-color: var(--vx-surface-bg);
+}
+
+/*
+ * Header row — the title (`.title` below, shared by both forms), plus the fold toggle in the
+ * portalled form only, at `sectionHeaderHeight` (standalone) / the header band (shell, below).
+ * Same horizontal inset every sidebar region aligns to.
+ */
+.header {
+  display: flex;
+  flex: none;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--vx-space-control-gap);
+  min-height: var(--vx-space-section-header-height, 2.25rem);
+}
+
+/* The portalled form's band matches the SHELL-OWNED page-bar band exactly, whenever one is
+ * present (`--basalt-page-bar-h`, `docs/DESIGN-SPEC.md` §5) — not a fixed 48px. `PageBar`
+ * publishes that var on `documentElement` from a ResizeObserver on the band's own content
+ * (`shell/page-bar.tsx`), so it inherits down to every descendant, this header included, with no
+ * extra wiring. Two seams, one line: MEASURED on `/cbbi` 1440x900, the band's outer edge (its own
+ * `border-bottom`, `app-main.module.css` `.band:not(:empty)`) used to sit at y87 while this header
+ * (unconditionally `var(--app-shell-header-height)`, 48px) sat at y96 — 9px apart.
+ *
+ * The `+ 1px` is not decorative. `--basalt-page-bar-h` measures the band's CONTENT box only (the
+ * portalled row-2 wrapper `page-bar.tsx` attaches its ResizeObserver to); the band's own
+ * `border-bottom` is drawn OUTSIDE that box, on a plain `height: auto` element, so it ADDS a pixel
+ * the published var never counted. This header is the opposite shape — an explicit `min-height`
+ * under the page's global `box-sizing: border-box` reset — so its OWN `border-bottom` is absorbed
+ * INSIDE whatever height is declared instead of adding on top. Feeding the raw var straight in
+ * therefore undershoots by exactly the band's border: `calc(38px + 1px)` = 39px, matching the
+ * band's true painted height, while the no-band fallback nets out unchanged (`calc((48px - 1px) +
+ * 1px)` = 48px) because the same `+ 1px` also wraps that branch. Without a `PageBar` there is no
+ * band seam to align to, so the header keeps closing the ordinary 48px top belt
+ * (`docs/DESIGN-SPEC.md` §5) the header and sidebar-brand bands also close.
+ */
+.panel[data-basalt-page-aside='shell'] .header {
+  padding-inline: var(--vx-space-row-inset-x);
+  min-height: calc(
+    var(
+        --basalt-page-bar-h,
+        calc(var(--app-shell-header-height, var(--vx-space-section-header-height, 2.25rem)) - 1px)
+      ) +
+      1px
+  );
+  border-bottom: 1px solid var(--vx-divider);
+}
+
+/* A real title (docs/DESIGN-SPEC.md §5): mirrors `widget-header.module.css` `.heading` and the
+ * breadcrumb's current-page treatment — the three 48px bands each carry one 550-weight head-font
+ * name. */
+.title {
+  font-family: var(--basalt-font-head);
+  font-size: var(--vx-text-md);
+  font-weight: 550;
+  font-stretch: 88%;
+  color: var(--vx-ink);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* The body scrolls, the header does not — `min-height: 0` is what lets a flex child shrink below
+ * its content and actually become a scroll box. In flow (standalone) it is plain content: no
+ * scroll region, no inset, so it sits in the page's own rhythm. */
+.body {
+  display: flex;
+  flex-direction: column;
+  gap: var(--vx-space-stack-md, 0.75rem);
+  min-width: 0;
+}
+
+.panel[data-basalt-page-aside='shell'] .body {
+  flex: 1;
+  min-height: 0;
+  overflow-y: auto;
+  padding-inline: var(--vx-space-row-inset-x);
+  padding-block: var(--vx-space-stack-md, 0.75rem);
+}
+
+/*
+ * FLUSH chrome (`docs/ASIDE-SPEC.md` §3, wave 2). An aside's groups separate with a hairline, not
+ * with cards — Lightroom, not a dashboard: at ~300px a stack of bordered, inset panels spends most
+ * of the column on its own edges, and the reader's job here is comparing rows across groups rather
+ * than reading one card at a time.
+ *
+ * It is drawn HERE and not in `Section`, on the `.body`'s own children, for two reasons. The
+ * component does not know where it is mounted (there is no aside context and no prop that would
+ * tell it), and a body child is not necessarily a `Section` at all — a bare `PanelRow`, a chart, a
+ * paragraph all take the same rhythm. `> * + *`, so the first child never draws a rule under the
+ * header that already bounds it.
+ */
+.body > * + * {
+  border-top: 1px solid var(--vx-divider);
+  padding-top: var(--vx-space-stack-md, 0.75rem);
+}
+
+/* The folded rail: one button, top-aligned, centred in the rail's own width. */
+.rail {
+  display: flex;
+  flex: 1;
+  justify-content: center;
+  align-items: flex-start;
+  padding-top: var(--vx-space-stack-xs, 0.25rem);
+}
+
+/*
+ * The fold toggle — a plain control sized to the `ctl` tier by hand, verbatim from `Section`'s
+ * chevron (`section/section.module.css`), including the `calc(<rem> * var(--mantine-scale))`
+ * reconstruction that keeps it tracking a scaled Button beside it. No `< sm` hit-area overlay
+ * (unlike that chevron): the toggle exists only in the portalled form, which is `sm` and up.
+ */
+/* Deliberately NOT shared with `section/section.module.css`'s `.chevron`, which it echoes: the two
+ * live in different CSS modules and this repo keeps one module per component, so sharing would need
+ * a third module + `composes` across that boundary. They also differ where it counts — `.fold` is
+ * `--vx-faint` and draws no rotation or C15 touch overlay, because the aside's fold is a desktop-
+ * only control. */
+.fold {
+  position: relative;
+  display: inline-flex;
+  flex: none;
+  align-items: center;
+  justify-content: center;
+  width: calc(var(--vx-space-control-height-ctl) * var(--mantine-scale, 1));
+  height: calc(var(--vx-space-control-height-ctl) * var(--mantine-scale, 1));
+  appearance: none;
+  margin: 0;
+  padding: 0;
+  border: none;
+  background: none;
+  border-radius: var(--vx-radius-ctrl);
+  color: var(--vx-faint);
+  cursor: pointer;
+}
+
+.fold:hover,
+.fold:focus-visible {
+  color: var(--vx-ink);
+  background: var(--vx-surface-subtle);
+}

package/dist/shell/page-aside.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.
+ */
+declare const classes: {
+  readonly outlet: string
+  readonly panel: string
+  readonly header: string
+  readonly title: string
+  readonly body: string
+  readonly rail: string
+  readonly fold: string
+}
+export default classes

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

@@ -1,8 +1,22 @@
 import type { ReactNode } from 'react';
+import type { BasaltProps, SlotStylesProps } from '../common/props.js';
 import type { ActionGroupProps, BarAction, GlobalAction } from '../controls/actions.js';
 import type { SyncButtonProps } from '../controls/sync-button.js';
 /** The custom property row 2's measured height is published on. */
 export declare const PAGE_BAR_HEIGHT_VAR = "--basalt-page-bar-h";
+/**
+ * What a `PageAside` publishes when it projects itself into row 2 below `sm`
+ * (`docs/ASIDE-SPEC.md` §0 "Desktop and mobile are one declaration"). Metadata only — the aside's
+ * CHILDREN never travel through this context: they are portalled into the sheet's own node
+ * ({@link PageBarSlots.panelTarget}), because a `ReactNode` in state would be a fresh object on
+ * every parent render and the claim effect would loop.
+ */
+export type AsidePanelClaim = {
+    /** The aside's `title` — the pill's accessible name and the sheet's heading. */
+    readonly title: string;
+    /** The aside's own glyph, supplied by the claimant so this module owns no aside iconography. */
+    readonly icon: ReactNode;
+};
 /**
  * Internal — mounted by `BasaltShell`. Owns the portal target, and the single-kebab claim that
  * lets the shell fall back to its OWN kebab on a route that renders no `PageBar`.
@@ -15,9 +29,48 @@ export declare function PageBarProvider({ globalActions, children, }: {
 export declare function PageBarOutlet({ className }: {
     className?: string;
 }): import("react").JSX.Element;
+/**
+ * Internal — the BAND between the header and the scrollport that the active page's row 2 portals
+ * into. `BasaltShell` mounts exactly one.
+ *
+ * It is rendered unconditionally and is a zero-height, seam-less box while no `PageBar` claims it:
+ * law C14 says an empty home renders nothing, and an outlet that only existed once something was
+ * inside it could not be a portal target in the first place. The `:empty` seam rule in
+ * `app-main.module.css` is what makes "nothing mounted" and "nothing painted" the same state.
+ */
+export declare function PageBarBandOutlet({ className }: {
+    className?: string;
+}): import("react").JSX.Element;
 /** Internal — `true` while a page's `ActionGroup` owns the header's one mobile kebab. */
 export declare function usePageKebabClaimed(): boolean;
-export type PageBarProps = {
+/**
+ * Internal — the seam `PageAside` projects itself through below `sm` (`docs/ASIDE-SPEC.md` §0).
+ * `host` says whether there is a row 2 to hang the pill off at all; `claim` publishes the aside's
+ * title and glyph; `target` is the node inside the opened sheet its children portal into.
+ */
+export declare function useAsidePanelSlot(): {
+    host: boolean;
+    claim: (panel: AsidePanelClaim) => () => void;
+    target: HTMLElement | null;
+};
+/**
+ * The boxes `PageBar` paints (`common/props.ts`). `root` is whichever element is the bar's own
+ * outer node for the active mode — the shell-less standalone bar, or row 2's wrapper inside the
+ * shell's band (row 1 portals into the app-shell header and has no wrapper of PageBar's own,
+ * which is what `row1`/`row2` target directly).
+ *
+ * `className`/`classNames.root` land on that same root — the shell-less
+ * `<div data-basalt-page-bar="standalone">`, or row 2's band wrapper
+ * (`data-basalt-page-bar="shell"`) inside a `BasaltShell`. The one thing only the consumer's own
+ * layout knows is bleeding the sticky bar across its container's gutters
+ * (`margin-inline: calc(var(--gutter) * -1); padding-inline: var(--gutter)`) for the shell-less
+ * form. Scope that CSS through this class, not through a global `[data-basalt-page-bar]` selector:
+ * the data attributes are stable enough to READ (a shell-less consumer can style
+ * `[data-basalt-page-bar="standalone"]` in a pinch, and this doc is the promise that the value
+ * stays), but a global rule reaches every page in the app including the ones that want neither.
+ */
+export type PageBarSlot = 'root' | 'row1' | 'row2';
+export type PageBarProps = BasaltProps & SlotStylesProps<PageBarSlot> & {
     /**
      * Read only when there is no `BasaltShell` outlet (a shell-less app such as linewatch). Inside a
      * shell the breadcrumb names the page and this is ignored.
@@ -33,19 +86,6 @@ export type PageBarProps = {
     filtersEnd?: BarAction[];
     /** One `ViewTabs`. */
     tabs?: ReactNode;
-    /**
-     * Added to the bar's ROOT — the shell-less `<div data-basalt-page-bar="standalone">`, or row 2's
-     * sticky wrapper (`data-basalt-page-bar="shell"`) inside a `BasaltShell`. The seam for the two
-     * things only the consumer's own layout knows: bleeding the sticky bar across its container's
-     * gutters (`margin-inline: calc(var(--gutter) * -1); padding-inline: var(--gutter)`) and drawing
-     * a hairline under it (`border-bottom: 1px solid var(--vx-border)`).
-     *
-     * Scope that CSS through this class, not through a global `[data-basalt-page-bar]` selector: the
-     * data attributes are stable enough to READ (a shell-less consumer can style
-     * `[data-basalt-page-bar="standalone"]` in a pinch, and this doc is the promise that the value
-     * stays), but a global rule reaches every page in the app including the ones that want neither.
-     */
-    className?: string;
 };
-export declare function PageBar({ title, icon, actions, sync, filters, filtersEnd, tabs, className, }: PageBarProps): ReactNode;
+export declare function PageBar({ title, icon, actions, sync, filters, filtersEnd, tabs, className, style, classNames, }: PageBarProps): ReactNode;
 //# sourceMappingURL=page-bar.d.ts.map