basalt-ui 1.25.0 → 1.27.0

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

@@ -1 +1 @@
-{"version":3,"file":"app-sidebar.d.ts","sourceRoot":"","sources":["../../src/shell/app-sidebar.tsx"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AACtC,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAC5D,OAAO,KAAK,EAAe,cAAc,EAAE,MAAM,cAAc,CAAA;AAG/D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAEzD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAK3D,MAAM,MAAM,eAAe,GAAG;IAC5B,KAAK,EAAE,WAAW,CAAA;IAClB,QAAQ,EAAE,cAAc,EAAE,CAAA;IAC1B,SAAS,EAAE,OAAO,CAAA;IAClB,gBAAgB,EAAE,MAAM,IAAI,CAAA;IAC5B;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,gBAAgB,EAAE,CAAA;IACtC;;;;OAIG;IACH,OAAO,CAAC,EAAE,kBAAkB,CAAA;IAC5B;;;OAGG;IACH,MAAM,CAAC,EAAE,mBAAmB,CAAA;IAC5B;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAA;CACrB,CAAA;AAqQD,wBAAgB,UAAU,CAAC,EACzB,KAAK,EACL,QAAQ,EACR,SAAS,EACT,gBAAgB,EAChB,iBAAiB,EACjB,OAAO,EACP,MAAM,EACN,QAAQ,GACT,EAAE,eAAe,+BAuJjB"}
+{"version":3,"file":"app-sidebar.d.ts","sourceRoot":"","sources":["../../src/shell/app-sidebar.tsx"],"names":[],"mappings":"AAoCA,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAe,cAAc,EAAE,MAAM,cAAc,CAAA;AAG7E,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAE1E,OAAO,KAAK,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAgBjF,MAAM,MAAM,eAAe,GAAG;IAC5B;;;;OAIG;IACH,KAAK,EAAE,WAAW,GAAG;QAAE,IAAI,CAAC,EAAE,eAAe,EAAE,CAAA;KAAE,CAAA;IACjD,QAAQ,EAAE,cAAc,EAAE,CAAA;IAC1B,SAAS,EAAE,OAAO,CAAA;IAClB,gBAAgB,EAAE,MAAM,IAAI,CAAA;IAC5B;;;;;;;;;;;OAWG;IACH,iBAAiB,CAAC,EAAE,gBAAgB,EAAE,CAAA;IACtC;;;;;;;;;;;;;;;;OAgBG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAA;IACvC;;;;OAIG;IACH,OAAO,CAAC,EAAE,kBAAkB,CAAA;IAC5B;;;;OAIG;IACH,MAAM,CAAC,EAAE,mBAAmB,GAAG;QAAE,OAAO,CAAC,EAAE,oBAAoB,CAAA;KAAE,CAAA;IACjE;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,YAAY,EAAE,CAAA;CACxB,CAAA;AA4VD,wBAAgB,UAAU,CAAC,EACzB,KAAK,EACL,QAAQ,EACR,SAAS,EACT,gBAAgB,EAChB,iBAAiB,EACjB,YAAqB,EACrB,OAAO,EACP,MAAM,EACN,MAAM,GACP,EAAE,eAAe,+BAiKjB"}

package/dist/shell/app-sidebar.js

@@ -14,10 +14,21 @@ import {
   UnstyledButton
 } from "@mantine/core";
 import { useDisclosure } from "@mantine/hooks";
-import { useEffect, useRef, useState } from "react";
+import { useEffect, useRef } from "react";
 import { NavCountBadge } from "./nav-count-badge.js";
 import { SidebarAccount } from "./app-sidebar-account.js";
 import { SidebarSearch } from "./sidebar-search.js";
+import {
+  IconChevron,
+  SidebarBlockView,
+  SidebarProgressRing,
+  usePersistedFold
+} from "./sidebar-blocks.js";
+import {
+  sidebarBlockPlacement,
+  sidebarBlockRail,
+  sidebarSectionFoldKey
+} from "./sidebar-block-model.js";
 import { VX } from "../tokens/index.js";
 import { useBasaltSpacing } from "../theme/index.js";
 import classes from "./app-sidebar.module.css";
@@ -42,23 +53,6 @@ function IconCollapse({ collapsed }) {
     }
   );
 }
-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" })
-    }
-  );
-}
 function IconGear() {
   return /* @__PURE__ */ jsxs(
     "svg",
@@ -81,6 +75,31 @@ function IconGear() {
 }
 const HOVER_OPEN_DELAY = 150;
 const HOVER_CLOSE_DELAY = 200;
+const FLAT_SETTINGS_MAX = 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 hasActiveDescendant(item) {
   if (item.active) return true;
   return item.children?.some((c) => hasActiveDescendant(c)) ?? false;
@@ -93,6 +112,15 @@ function NavLinkBody({ item, active }) {
     leftSection: item.icon,
     rightSection: item.badge ?? (item.count ? /* @__PURE__ */ jsx(NavCountBadge, { count: item.count }) : void 0),
     active,
+    // Basalt is the one that stamps `aria-current`, not the theme and not a router `<Link>`'s own
+    // default (which a consumer's `SidebarItem.Anchor` may compute independently) — mirrors
+    // `app-mobile-nav.tsx`'s identical pattern so both surfaces agree on what "active" means.
+    "aria-current": active ? "page" : void 0,
+    // `item.ancestor` (a parent on the winner's path — `useNav`'s exclusivity pass) is NEVER
+    // active and never carries `aria-current`; it only earns a `data-ancestor` hook for CSS. A
+    // leaf item never has `ancestor` set, so this is a no-op there — shared here rather than
+    // duplicated per render path.
+    ...item.ancestor === true && { "data-ancestor": true },
     ...item.onClick !== void 0 && { onClick: item.onClick }
   };
   if (Anchor) {
@@ -100,8 +128,36 @@ function NavLinkBody({ item, active }) {
   }
   return /* @__PURE__ */ jsx(NavLink, { component: "a", ...item.href !== void 0 && { href: item.href }, ...shared });
 }
-function SectionLabel({ children, flush }) {
-  return /* @__PURE__ */ jsx(Text, { component: "div", px: flush ? 0 : "xs", mb: flush ? 0 : 4, className: classes.sectionLabel, children });
+function SectionLabel({ children }) {
+  return /* @__PURE__ */ jsx(Text, { component: "div", px: 0, mb: 0, className: classes.sectionLabel, children });
+}
+function NavSection({ section, collapsed }) {
+  const [folded, setFolded] = usePersistedFold(
+    sidebarSectionFoldKey(section.label),
+    Boolean(section.defaultCollapsed)
+  );
+  const items = section.items.map((item) => /* @__PURE__ */ jsx(NavItemRow, { item, collapsed }, item.key));
+  if (!section.collapsible) {
+    return /* @__PURE__ */ jsxs("div", { children: [
+      /* @__PURE__ */ jsx("div", { className: classes.sectionBand, children: /* @__PURE__ */ jsx(SectionLabel, { children: section.label }) }),
+      /* @__PURE__ */ jsx(Stack, { gap: 1, children: items })
+    ] });
+  }
+  return /* @__PURE__ */ jsxs("div", { children: [
+    /* @__PURE__ */ jsxs(
+      UnstyledButton,
+      {
+        className: `${classes.sectionBand} ${classes.sectionHeader}`,
+        onClick: () => setFolded(!folded),
+        "aria-expanded": !folded,
+        children: [
+          /* @__PURE__ */ jsx(SectionLabel, { children: section.label }),
+          /* @__PURE__ */ jsx(IconChevron, { open: !folded })
+        ]
+      }
+    ),
+    /* @__PURE__ */ jsx(Collapse, { expanded: !folded, children: /* @__PURE__ */ jsx(Stack, { gap: 1, children: items }) })
+  ] });
 }
 function NavItemRow({ item, collapsed }) {
   const [opened, { open, close }] = useDisclosure(false);
@@ -213,33 +269,51 @@ function AppSidebar({
   collapsed,
   onToggleCollapse,
   settingsMenuItems,
+  settingsMenu = "auto",
   account,
   search,
-  navExtra
+  blocks
 }) {
   const { step } = useBasaltSpacing();
-  const [collapsedSections, setCollapsedSections] = useState(
-    () => Object.fromEntries(sections.map((s) => [s.label, Boolean(s.defaultCollapsed)]))
+  const navBlocks = (blocks ?? []).filter((block) => sidebarBlockPlacement(block) === "nav");
+  const bottomBlocks = (blocks ?? []).filter((block) => sidebarBlockPlacement(block) === "bottom");
+  const railRing = bottomBlocks.find(
+    (block) => block.kind === "progress" && sidebarBlockRail(block) === "ring"
   );
-  const renderSectionItems = (section) => section.items.map((item) => /* @__PURE__ */ jsx(NavItemRow, { item, collapsed }, item.key));
-  const hasSettingsMenu = (settingsMenuItems?.length ?? 0) > 0;
-  const settingsRow = hasSettingsMenu ? /* @__PURE__ */ jsx(Group, { ...account ? {} : { className: classes.footer }, gap: "xs", wrap: "nowrap", children: /* @__PURE__ */ jsxs(Menu, { position: "right-start", withArrow: true, width: step.sidebarSettingsMenuWidth, zIndex: 500, children: [
+  const settingsItems = settingsMenuItems ?? [];
+  const versionLabel = brand.version !== void 0 ? `${brand.name} v${brand.version}` : void 0;
+  const ringMark = collapsed && railRing !== void 0 && railRing.kind === "progress" ? /* @__PURE__ */ jsx(SidebarProgressRing, { value: railRing.value, total: railRing.total }) : null;
+  const flatSettings = settingsMenu === "flat" || settingsMenu === "auto" && settingsItems.length <= FLAT_SETTINGS_MAX;
+  const settingsRow = settingsItems.length === 0 ? null : flatSettings ? /* @__PURE__ */ jsxs("div", { className: classes.footerLinks, children: [
+    settingsItems.map((entry, index) => /* @__PURE__ */ jsxs(
+      UnstyledButton,
+      {
+        className: classes.footerBtn,
+        onClick: entry.onClick,
+        "aria-label": entry.label,
+        children: [
+          /* @__PURE__ */ jsx("span", { className: classes.footerIconSlot, children: entry.icon ?? /* @__PURE__ */ jsx(IconGear, {}) }),
+          /* @__PURE__ */ jsx(Text, { className: classes.footerText, fz: VX.text.md, children: entry.label }),
+          index === 0 ? ringMark : null
+        ]
+      },
+      entry.key
+    )),
+    versionLabel !== void 0 && /* @__PURE__ */ jsx(Text, { component: "div", className: classes.footerVersion, children: versionLabel })
+  ] }) : /* @__PURE__ */ jsx(Group, { gap: "xs", wrap: "nowrap", children: /* @__PURE__ */ jsxs(Menu, { position: "right-start", withArrow: true, width: step.sidebarSettingsMenuWidth, zIndex: 500, children: [
     /* @__PURE__ */ jsx(Menu.Target, { children: /* @__PURE__ */ jsxs(UnstyledButton, { className: classes.footerBtn, "aria-label": "Settings", children: [
       /* @__PURE__ */ jsx(IconGear, {}),
-      /* @__PURE__ */ jsx(Text, { className: classes.footerText, fz: VX.text.md, children: "Settings" })
+      /* @__PURE__ */ jsx(Text, { className: classes.footerText, fz: VX.text.md, children: "Settings" }),
+      ringMark
     ] }) }),
     /* @__PURE__ */ jsxs(Menu.Dropdown, { children: [
-      settingsMenuItems?.map((entry) => /* @__PURE__ */ jsx(Menu.Item, { leftSection: entry.icon, onClick: entry.onClick, children: entry.label }, entry.key)),
-      brand.version && /* @__PURE__ */ jsxs(Fragment, { children: [
+      settingsItems.map((entry) => /* @__PURE__ */ jsx(Menu.Item, { leftSection: entry.icon, onClick: entry.onClick, children: entry.label }, entry.key)),
+      versionLabel !== void 0 && /* @__PURE__ */ jsxs(Fragment, { children: [
         /* @__PURE__ */ jsx(Menu.Divider, {}),
-        /* @__PURE__ */ jsxs(Menu.Label, { children: [
-          brand.name,
-          " v",
-          brand.version
-        ] })
+        /* @__PURE__ */ jsx(Menu.Label, { children: versionLabel })
       ] })
     ] })
-  ] }) }) : null;
+  ] }) });
   return /* @__PURE__ */ jsxs(Stack, { gap: 0, h: "100%", className: classes.root, "data-collapsed": collapsed || void 0, children: [
     /* @__PURE__ */ jsxs(Group, { className: classes.brand, gap: "sm", wrap: "nowrap", children: [
       /* @__PURE__ */ jsxs(Group, { className: classes.brandLead, gap: "sm", wrap: "nowrap", children: [
@@ -253,7 +327,7 @@ function AppSidebar({
             style: { display: "block" }
           }
         ),
-        /* @__PURE__ */ jsx(Text, { className: classes.brandName, fz: VX.text.xl, fw: 550, children: brand.name })
+        /* @__PURE__ */ jsx(BrandName, { brand, menuWidth: step.sidebarAccountMenuWidth })
       ] }),
       /* @__PURE__ */ jsx(
         ActionIcon,
@@ -278,40 +352,15 @@ function AppSidebar({
         className: classes.navScroll,
         classNames: { viewport: classes.navViewport },
         children: /* @__PURE__ */ jsxs(Stack, { gap: 0, className: classes.nav, children: [
-          sections.map((section) => {
-            if (!section.collapsible) {
-              return /* @__PURE__ */ jsxs("div", { children: [
-                /* @__PURE__ */ jsx("div", { className: classes.sectionBand, children: /* @__PURE__ */ jsx(SectionLabel, { flush: true, children: section.label }) }),
-                /* @__PURE__ */ jsx(Stack, { gap: 1, children: renderSectionItems(section) })
-              ] }, section.label);
-            }
-            const isOpen = !collapsedSections[section.label];
-            return /* @__PURE__ */ jsxs("div", { children: [
-              /* @__PURE__ */ jsxs(
-                UnstyledButton,
-                {
-                  className: `${classes.sectionBand} ${classes.sectionHeader}`,
-                  onClick: () => setCollapsedSections((prev) => ({
-                    ...prev,
-                    [section.label]: !prev[section.label]
-                  })),
-                  "aria-expanded": isOpen,
-                  children: [
-                    /* @__PURE__ */ jsx(SectionLabel, { flush: true, children: section.label }),
-                    /* @__PURE__ */ jsx(IconChevron, { open: isOpen })
-                  ]
-                }
-              ),
-              /* @__PURE__ */ jsx(Collapse, { expanded: isOpen, children: /* @__PURE__ */ jsx(Stack, { gap: 1, children: renderSectionItems(section) }) })
-            ] }, section.label);
-          }),
-          navExtra !== void 0 && navExtra !== null && /* @__PURE__ */ jsx("div", { className: classes.navExtra, children: navExtra })
+          sections.map((section) => /* @__PURE__ */ jsx(NavSection, { section, collapsed }, section.label)),
+          navBlocks.map((block) => /* @__PURE__ */ jsx(SidebarBlockView, { block }, block.key))
         ] })
       }
     ),
-    account ? /* @__PURE__ */ jsxs(Stack, { gap: 0, className: classes.footer, children: [
+    (bottomBlocks.length > 0 || settingsRow !== null || account !== void 0) && /* @__PURE__ */ jsxs(Stack, { gap: 0, className: classes.footer, children: [
+      bottomBlocks.map((block) => /* @__PURE__ */ jsx(SidebarBlockView, { block }, block.key)),
       settingsRow,
-      /* @__PURE__ */ jsx(
+      account !== void 0 && /* @__PURE__ */ jsx(
         SidebarAccount,
         {
           state: account.state,
@@ -319,7 +368,7 @@ function AppSidebar({
           ...account.showEmail !== void 0 && { showEmail: account.showEmail }
         }
       )
-    ] }) : settingsRow
+    ] })
   ] });
 }
 export {

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

@@ -40,30 +40,63 @@
 
 /* Inactive rows: muted text + faint icon. Active rows keep the theme's ink text (via `--nl-color`)
  * untouched — this selector only ever matches when neither `data-active` nor `aria-current="page"`
- * is present. */
-.link:not([data-active]):not([aria-current='page']) {
+ * is present. `[data-ancestor]` is excluded too: it gets its own ink/accent treatment below and
+ * must not fall through to muted/faint here. */
+.link:not([data-active]):not([aria-current='page']):not([data-ancestor]) {
   color: var(--vx-muted) !important;
 }
 
-.link:not([data-active]):not([aria-current='page'])
+.link:not([data-active]):not([aria-current='page']):not([data-ancestor])
   :global(.mantine-NavLink-section[data-position='left']) {
   color: var(--vx-faint);
 }
 
 /* Hover — ink-6% tint + ink text, for inactive rows only (an active row already carries the
- * theme's stronger ink-9% tint and keeps its own hover via `--nl-hover`). */
+ * theme's stronger ink-9% tint and keeps its own hover via `--nl-hover`; an ancestor row gets its
+ * own hover rule below so its accent icon survives the pointer). */
 @media (hover: hover) {
-  .link:not([data-active]):not([aria-current='page']):hover {
+  .link:not([data-active]):not([aria-current='page']):not([data-ancestor]):hover {
     background-color: color-mix(in srgb, var(--vx-ink) 6%, transparent) !important;
     color: var(--vx-ink) !important;
   }
 
-  .link:not([data-active]):not([aria-current='page']):hover
+  .link:not([data-active]):not([aria-current='page']):not([data-ancestor]):hover
     :global(.mantine-NavLink-section[data-position='left']) {
     color: var(--vx-ink);
   }
 }
 
+/*
+ * Ancestor row (`SidebarItem.ancestor` — a parent on the path to the active row, never active
+ * itself, never `aria-current`): must read visibly WEAKER than active and visibly STRONGER than a
+ * hovered inactive row, since all three now share the same 6%/9% ink-tint family. Active carries a
+ * persistent `--nl-bg` ink-9% fill + weight 600 (theme `nav-link.module.css`); a hovered inactive
+ * row carries a transient ink-6% fill. An ancestor therefore gets NO fill at rest (unlike active)
+ * and NO weight change (still 400, unlike active's 600) — only the ink label + accent icon that an
+ * active row also carries, so it reads as "on the path" without claiming to BE the destination.
+ */
+.link[data-ancestor] {
+  color: var(--vx-ink) !important;
+}
+
+.link[data-ancestor] :global(.mantine-NavLink-section[data-position='left']) {
+  color: var(--vx-accent);
+}
+
+/* Hover still adds the shared ink-6% tint (same as any inactive row), but must not let the plain
+ * inactive hover rule above flatten the icon back to ink — that rule is excluded via
+ * `:not([data-ancestor])`, and this one re-asserts the accent icon on top of the shared tint. */
+@media (hover: hover) {
+  .link[data-ancestor]:hover {
+    background-color: color-mix(in srgb, var(--vx-ink) 6%, transparent) !important;
+    color: var(--vx-ink) !important;
+  }
+
+  .link[data-ancestor]:hover :global(.mantine-NavLink-section[data-position='left']) {
+    color: var(--vx-accent);
+  }
+}
+
 /*
  * Icon-only ghost buttons in shell chrome (collapse toggle, mobile close) — docs/DESIGN-SPEC.md
  * §5: transparent, faint icon, hover ink-6% + ink, radius 6. `!important` for the same reason as
@@ -113,6 +146,22 @@
   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);
+}
+
 /*
  * Nav scroll region — a Mantine ScrollArea, whose overlay scrollbar is absolutely positioned inside
  * the (position: relative; overflow: hidden) root, so it floats over the rows instead of reserving
@@ -151,7 +200,7 @@
 
 /*
  * Footer settings row — IDENTICAL geometry to a nav row (padding 6px 10px, radius 6, gap 10,
- * 13px): muted text + faint icon at rest, ink-6% tint + ink on hover, exactly like an inactive
+ * 15px): muted text + faint icon at rest, ink-6% tint + ink on hover, exactly like an inactive
  * nav item, so the footer never reads as a separate control family.
  */
 .footerBtn {
@@ -211,7 +260,7 @@
 }
 
 /*
- * Identity initials block (docs/DESIGN-SPEC.md §5): 28px, radius 7, ink-10% bg, mono 10.5px
+ * Identity initials block (docs/DESIGN-SPEC.md §5): 28px, radius 7, ink-10% bg, mono micro (11px)
  * weight 500, muted — replaces the generic person glyph for the authenticated state.
  */
 .avatar {
@@ -236,7 +285,7 @@
   color: var(--vx-ink);
 }
 
-/* Meta line under the name (email / "FREE · MEMBER") — mono 9.5px, uppercase, faint, tracked
+/* Meta line under the name (email / "FREE · MEMBER") — mono micro (11px), uppercase, faint, tracked
  * 0.03em. */
 .accountMeta {
   font-family: var(--basalt-font-mono);
@@ -293,6 +342,214 @@
   color: var(--vx-ink);
 }
 
+/*
+ * ── Sidebar blocks (docs/CONTROLS-SPEC.md §2.3) ────────────────────────────────────────────────
+ *
+ * Same spacing-only separation law as the nav sections above: no rules, no bands, no fills. A
+ * block's rows are 32px (`--vx-space-sidebar-block-row-height`) — one step under a nav row, since
+ * a block row is reference material rather than a destination.
+ */
+.block {
+  min-width: 0;
+}
+
+.blockHeader {
+  display: flex;
+  align-items: center;
+  gap: var(--vx-space-nav-icon-gap);
+  width: 100%;
+  padding: 0 var(--vx-space-row-inset-x);
+  margin-bottom: var(--vx-space-sidebar-section-label-gap);
+}
+
+/* The header's label takes the free width so a count badge / chevron sits hard right. */
+.blockHeader > div:first-of-type {
+  flex: 1;
+  min-width: 0;
+  text-align: left;
+}
+
+/* Collapsible variant — text-only hover, exactly like `.sectionHeader`; never a band. */
+.blockHeaderButton {
+  color: var(--vx-faint);
+  cursor: pointer;
+}
+
+.blockHeaderButton:hover .sectionLabel {
+  color: var(--vx-ink);
+}
+
+.blockIcon {
+  position: relative;
+  display: flex;
+  flex: none;
+  align-items: center;
+  color: var(--vx-faint);
+}
+
+/*
+ * Rail dot — the collapsed rail's whole representation of a `count`. Hidden in the expanded
+ * sidebar, where the count renders as a real `NavCountBadge` instead: a dot and a number saying
+ * the same thing twice is noise, and the rail has no room for the number.
+ */
+.blockDot {
+  position: absolute;
+  top: -2px;
+  inset-inline-end: -3px;
+  display: none;
+  width: 7px;
+  height: 7px;
+  border-radius: 999px;
+  background-color: var(--vx-accent);
+  box-shadow: 0 0 0 2px var(--mantine-color-body);
+}
+
+.blockItems {
+  display: flex;
+  flex-direction: column;
+}
+
+/* Block row — 32px, small text, muted; the same ink-6% hover every other sidebar row uses. */
+.blockRow {
+  display: flex;
+  align-items: center;
+  gap: var(--vx-space-nav-icon-gap);
+  min-height: var(--vx-space-sidebar-block-row-height);
+  padding: 0 var(--vx-space-row-inset-x) !important;
+  border-radius: var(--vx-radius-ctrl) !important;
+  font-size: var(--vx-text-sm);
+  color: var(--vx-muted);
+}
+
+.blockRow :global(.mantine-NavLink-label) {
+  font-size: var(--vx-text-sm);
+}
+
+.blockRow :global(.mantine-NavLink-section[data-position='left']) {
+  margin-inline-end: 0;
+  color: var(--vx-faint);
+}
+
+@media (hover: hover) {
+  .blockRow:not(.blockRowStatic):hover {
+    background-color: color-mix(in srgb, var(--vx-ink) 6%, transparent) !important;
+    color: var(--vx-ink) !important;
+  }
+}
+
+/* A non-interactive row (the "Recents" shape) keeps the geometry and drops every affordance. */
+.blockRowStatic {
+  cursor: default;
+}
+
+.blockRowLabel {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.blockRowMeta {
+  flex: none;
+  font-size: var(--vx-text-micro);
+  color: var(--vx-faint);
+}
+
+/* Status dot standing in for a missing row icon — reads the per-scheme `--vx-status-*` solid. */
+.blockToneDot {
+  flex: none;
+  width: 6px;
+  height: 6px;
+  border-radius: 999px;
+  background-color: var(--vx-status-neutral);
+}
+
+.blockToneDot[data-tone='good'] {
+  background-color: var(--vx-status-good);
+}
+
+.blockToneDot[data-tone='warn'] {
+  background-color: var(--vx-status-warn);
+}
+
+.blockToneDot[data-tone='bad'] {
+  background-color: var(--vx-status-bad);
+}
+
+/* "Show more" — a text affordance, not a button surface. */
+.blockMore {
+  min-height: var(--vx-space-sidebar-block-row-height);
+  padding: 0 var(--vx-space-row-inset-x);
+  text-align: left;
+  font-size: var(--vx-text-sm);
+  color: var(--vx-faint);
+}
+
+.blockMore:hover {
+  color: var(--vx-ink);
+}
+
+/* Progress block — label + `n of m` over a thin track. */
+.blockProgress {
+  display: block;
+  width: 100%;
+  padding: var(--vx-space-row-inset-y) var(--vx-space-row-inset-x);
+  border-radius: var(--vx-radius-ctrl);
+  text-align: left;
+}
+
+.blockProgress:hover {
+  background-color: color-mix(in srgb, var(--vx-ink) 6%, transparent);
+}
+
+.blockProgressHead {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--vx-space-nav-icon-gap);
+  margin-bottom: var(--vx-space-sidebar-section-label-gap);
+}
+
+/* The rail's progress mark, rendered on the settings row (never inside the block). */
+.blockRing {
+  display: flex;
+  flex: none;
+  align-items: center;
+}
+
+/*
+ * Flat footer links — `settingsMenuItems` at three or fewer, rendered as rows instead of a gear
+ * menu (see `AppSidebar`'s JSDoc for the threshold). Each row IS a `.footerBtn`, so the two
+ * renderings are the same geometry.
+ */
+.footerLinks {
+  display: flex;
+  flex-direction: column;
+}
+
+/* Fixed 18px icon column for a flat footer row — an icon-less row keeps the label aligned with
+ * its neighbours instead of sliding left. */
+.footerIconSlot {
+  display: flex;
+  flex: none;
+  align-items: center;
+  justify-content: center;
+  width: 18px;
+  color: var(--vx-faint);
+}
+
+.footerBtn:hover .footerIconSlot {
+  color: var(--vx-ink);
+}
+
+.footerVersion {
+  padding: var(--vx-space-row-inset-y) var(--vx-space-row-inset-x);
+  font-family: var(--basalt-font-mono);
+  font-size: var(--vx-text-micro);
+  color: var(--vx-faint);
+}
+
 /*
  * Inline child items — indent under the parent with the ONE allowed sidebar line: a 1px
  * `--vx-divider` left guide on the WRAPPER (not per row, so hover tints don't break the line).
@@ -350,9 +607,9 @@
 }
 
 /*
- * Icon-rail (collapsed) — desktop only. Gated behind min-width: sm (48em) so the mobile drawer keeps
- * full labels even when the persisted collapse flag is on. Hide the brand text, section labels and
- * nav labels; center the remaining icons.
+ * Icon-rail (collapsed) — desktop only. Gated behind min-width: sm (48em) so the sidebar doesn't
+ * exist at all below that breakpoint (see `MobileNav`) regardless of the persisted collapse flag.
+ * Hide the brand text, section labels and nav labels; center the remaining icons.
  */
 @media (min-width: 48em) {
   .root[data-collapsed] .brand {
@@ -421,14 +678,40 @@
     display: none;
   }
 
-  /* `navExtra` has no sensible icon-rail representation (arbitrary consumer content, not a nav
-   * row) — hide it in the rail, same treatment as `.childList`. It stays mounted (never a JS
-   * conditional on `collapsed`): `collapsed` is one value shared by the desktop rail AND the
-   * mobile drawer (`AppShell.Navbar`'s `collapsed: { mobile: !mobileOpened }` only ever un-collapses
-   * the mobile side), and the rail-vs-drawer split lives ENTIRELY in this media query, never in JS —
-   * a JS gate on `collapsed` would also drop `navExtra` from the mobile drawer, which opens at full
-   * width regardless of the persisted rail state. */
-  .root[data-collapsed] .navExtra {
+  /*
+   * Block rail projection (`sidebarBlockRail`). `hidden` and `ring` blocks leave the rail entirely
+   * — a `custom` block is arbitrary consumer content with no icon-column representation (the
+   * treatment `navExtra` had), and a progress block's rail form is the ring on the settings row
+   * below, not a squashed track. A `dot` block keeps its icon and nothing else.
+   *
+   * All of it is CSS, never a JS conditional on `collapsed`: the navbar is permanently
+   * `collapsed: { mobile: true }` (there is no mobile drawer — see `MobileNav`), so `collapsed`
+   * means only the desktop expanded-vs-rail state, and this media query is what applies it.
+   */
+  .root[data-collapsed] .block[data-rail='hidden'],
+  .root[data-collapsed] .block[data-rail='ring'] {
+    display: none;
+  }
+
+  .root[data-collapsed] .block[data-rail='dot'] .blockHeader {
+    justify-content: center;
+    padding: 0;
+    margin-bottom: 0;
+  }
+
+  .root[data-collapsed] .block[data-rail='dot'] .blockHeader > *:not(.blockIcon) {
+    display: none;
+  }
+
+  .root[data-collapsed] .block[data-rail='dot'] .blockItems {
+    display: none;
+  }
+
+  .root[data-collapsed] .blockDot {
+    display: block;
+  }
+
+  .root[data-collapsed] .footerVersion {
     display: none;
   }
 }