basalt-ui 1.34.1 → 1.35.0

package/dist/shell/sidebar-blocks.js

@@ -1,5 +1,5 @@
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
-import { Collapse, NavLink, Progress, Text, UnstyledButton } from "@mantine/core";
+import { Collapse, NavLink, Popover, Progress, Text, UnstyledButton } from "@mantine/core";
 import { useState } from "react";
 import { NavCountBadge } from "./nav-count-badge.js";
 import { createPersistedState } from "../state.js";
@@ -150,15 +150,23 @@ function ProgressBlock({ block }) {
   ] });
   return /* @__PURE__ */ jsx("div", { className: classes.block, "data-rail": sidebarBlockRail(block), children: block.onClick !== void 0 ? /* @__PURE__ */ jsx(UnstyledButton, { className: classes.blockProgress, onClick: block.onClick, children: inner }) : /* @__PURE__ */ jsx("div", { className: classes.blockProgress, children: inner }) });
 }
-function CustomBlock({ block }) {
-  return /* @__PURE__ */ jsx("div", { className: classes.block, "data-rail": "hidden", children: block.node });
+function CustomBlock({ block, collapsed }) {
+  const rail = sidebarBlockRail(block);
+  if (collapsed && rail === "icon") {
+    return /* @__PURE__ */ jsx("div", { className: classes.block, "data-rail": "icon", children: /* @__PURE__ */ jsxs(Popover, { position: "right-start", withArrow: false, offset: 4, withinPortal: true, zIndex: 400, children: [
+      /* @__PURE__ */ jsx(Popover.Target, { children: /* @__PURE__ */ jsx(UnstyledButton, { className: classes.blockRailTrigger, "aria-label": block.label, children: /* @__PURE__ */ jsx(IconSlot, { children: block.icon }) }) }),
+      /* @__PURE__ */ jsx(Popover.Dropdown, { p: "xs", className: classes.blockRailPopover, children: block.node })
+    ] }) });
+  }
+  return /* @__PURE__ */ jsx("div", { className: classes.block, "data-rail": rail, children: block.node });
 }
 function SidebarBlockView({
-  block
+  block,
+  collapsed = false
 }) {
   if (block.kind === "list") return /* @__PURE__ */ jsx(ListBlock, { block });
   if (block.kind === "progress") return /* @__PURE__ */ jsx(ProgressBlock, { block });
-  return /* @__PURE__ */ jsx(CustomBlock, { block });
+  return /* @__PURE__ */ jsx(CustomBlock, { block, collapsed });
 }
 export {
   IconChevron,

package/dist/surfaces.js

@@ -357,8 +357,8 @@ const SURFACES = {
     layer: "mantine-coupled",
     rule: "controls",
     skill: ["basalt-design"],
-    // The text lane of law C1 — the plugin's `control-outside-home` seen through a 12-line host-tag
-    // window, since a regex scan has no ancestry. Same law, same wave, same promotion.
+    // The text lane of law C1 — the plugin's `control-outside-home` seen through a host-tag nesting
+    // count, since a regex scan has no AST. Same law, same wave, same promotion.
     guardKinds: ["raw-selection-control"],
     // The control tier itself (laws C1/C3/C5/C9). `hand-rolled-filter`, `control-size-literal` and
     // `responsive-twin` all ship `error`; the two C1 placement rules are the grace entries in

package/dist/tokens/index.js

@@ -557,7 +557,7 @@ function warnConsumerVxName(name) {
   if (!BASALT_VX_FAMILIES.includes(family) || warnedVxNames.has(name)) return;
   warnedVxNames.add(name);
   console.warn(
-    `[basalt] ${name} is inside basalt's own --vx-${family} family \u2014 name your series group something basalt does not own (groupTokens('app', \u2026)). Throws from 1.35.0.`
+    `[basalt] ${name} is inside basalt's own --vx-${family} family \u2014 name your series group something basalt does not own (groupTokens('app', \u2026)). Throws from 1.36.0.`
   );
 }
 function seriesTokens(map, prefix = "") {

package/llms.txt

@@ -1,4 +1,4 @@
-# basalt-ui v1.34.1
+# basalt-ui v1.35.0
 # Opinionated framework for Mantine-based React apps — theme, app shell, visx charts, toolchain presets
 #
 # basalt-ui is an opinionated framework for Mantine-based React apps.
@@ -19,7 +19,7 @@
 # ./tokens.css subpath. Guide: docs/FRAMEWORK-FREE.md in the repo.
 
 Package: basalt-ui
-Version: 1.34.1
+Version: 1.35.0
 
 ## basalt-ui
 Import: import { ... } from 'basalt-ui'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "basalt-ui",
-  "version": "1.34.1",
+  "version": "1.35.0",
   "description": "Opinionated framework for Mantine-based React apps — theme, app shell, visx charts, toolchain presets",
   "keywords": [
     "charts",

package/src/guard/index.ts

@@ -738,8 +738,8 @@ const PROSE_CONTEXT_TAG = /<(?:Prose|ArticleLayout|Modal|Drawer)(?![\w])/
  * does not need to: both mean "a raw control here is not homeless".
  *
  * The three subtree homes are the plugin's `BASALT_HOST_TAGS`, mirrored here so one law does not
- * read differently in the two lanes. The plugin gates them on the tag's basalt IMPORT; a 12-line
- * regex window has no import graph, so this lane matches by name and accepts the missed warn on a
+ * read differently in the two lanes. The plugin gates them on the tag's basalt IMPORT; a regex walk
+ * has no import graph, so this lane matches by name and accepts the missed warn on a
  * consumer's own `PanelRow` — the same direction every approximation in this scan already leans.
  *
  * The name set is the plugin's `CONTROL_HOST_TAGS` ∪ `BASALT_HOST_TAGS`; `oxlint-plugin.test.ts` ›
@@ -749,16 +749,31 @@ const CONTROL_HOST_TAG =
   /<(?:SettingsRow|FormRow|FormGroup|Modal|Drawer|Popover\.Dropdown|Menu\.Dropdown|Composer|FilterSet|PageAside|PanelRow)(?![\w])/
 
 /**
- * How far ABOVE a control the host-tag window reaches, in lines.
- *
- * The text lane has no ancestry, so "inside a SettingsRow" is approximated by "a SettingsRow opens
- * within the last N lines". 12 covers every row shape in the five consumer repos (label +
- * description + the `control={` line); past that the window would start swallowing the next row's
- * control, which is the direction that makes the kind silent rather than noisy. The plugin rule
- * (`basalt/control-outside-home`) is the one that answers this exactly — this kind exists for the
- * PreToolUse hook lane, which sees one file's TEXT and no AST at all.
+ * Open and close tags of the same host names, for the ancestry walk in {@link insideHostTag}. The
+ * opening alternative tolerates `=>` inside props (`onChange={(v) => …}`) like
+ * {@link RAW_SELECTION_CONTROL_TAG} does, and a `/>` ending marks a self-closing host, which opens
+ * nothing.
  */
-const CONTROL_HOST_WINDOW_LINES = 12
+const CONTROL_HOST_TAG_SCAN = new RegExp(
+  `<(/?)(?:${/\(\?:([^)]*)\)/.exec(CONTROL_HOST_TAG.source)?.[1] ?? ''})(?![\\w])(?:=>|[^>])*?>`,
+  'g',
+)
+
+/**
+ * Whether `offset` sits inside a host tag — one opened before it and not yet closed. The text lane
+ * has no AST, but the nesting of host tags in plain JSX is countable: +1 per opening tag, −1 per
+ * closing one, self-closing tags neither. That is what the plugin's `control-outside-home` answers
+ * by walking ancestors, so a control 40 lines under its `<SettingsRow>` is as homed here as there,
+ * and one after the row closed is not — the cases a fixed line window got wrong in both directions.
+ */
+function insideHostTag(codeText: string, offset: number): boolean {
+  let depth = 0
+  for (const m of codeText.slice(0, offset).matchAll(CONTROL_HOST_TAG_SCAN)) {
+    if (m[1] === '/') depth = Math.max(0, depth - 1)
+    else if (!m[0].endsWith('/>')) depth += 1
+  }
+  return depth > 0
+}
 
 /**
  * A file whose BASENAME declares it is an overlay's or a form's own body — the cross-file half of
@@ -768,7 +783,7 @@ const CONTROL_HOST_WINDOW_LINES = 12
  *
  * Law C1's cross-file case is advisory by declaration (`docs/CONTROLS-SPEC.md` §6, "Honest
  * coverage"), and this kind was paying for it: a `<Select>` inside `edit-session-modal.tsx` whose
- * `<Modal>` is rendered by the parent route is outside BOTH the 12-line host window and any
+ * `<Modal>` is rendered by the parent route is outside any
  * ancestry walk, because the host tag is not in the file at all. argo carried 9 of them.
  *
  * KEBAB and PascalCase both count, because a repo picks one file-naming law and the convention has
@@ -917,12 +932,14 @@ export type GraceEntry = { since: string; promote: string; why: string }
 export const GRACE_PERIOD_KINDS: Partial<Record<GuardKind, GraceEntry>> = {
   'unknown-vx-token': {
     since: '1.34.0',
-    promote: '1.35.0',
+    promote: '1.36.0',
     why:
       'New kind at 1.33.0 (consumer-loop r2 B3): obsidian lost its 44px touch floor to a removed ' +
       '`var(--vx-space-touch-target)` that nothing reported. WIDENED at 1.34.0 (image-gen r4: ' +
       '`var(--vx-surface-2)` rendered transparent, unreported) to every unemitted name inside a ' +
-      'basalt-owned family, so the grace restarts: warn through 1.34.x, error at 1.35.0.',
+      'basalt-owned family, so the grace restarts: warn through 1.34.x, error at 1.35.0. EXTENDED one minor at 1.35.0: that ' +
+      'minor ships the shell a11y fixes consumers are upgrading for, and the promotion also turns the ' +
+      'seriesTokens warning into a throw — not a change to bundle into that bump. Error at 1.36.0.',
   },
 }
 
@@ -2232,7 +2249,7 @@ export const GUARD_RULES = {
   },
   'raw-selection-control': {
     kind: 'raw-selection-control',
-    pattern: RAW_SELECTION_CONTROL_TAG, // handled inline (full-text tag-scoped scan + host window)
+    pattern: RAW_SELECTION_CONTROL_TAG, // handled inline (full-text tag-scoped scan + host ancestry)
     // JSX-tag-shaped (`<Select …>`) — never appears in CSS text.
     appliesTo: (relPath) => !relPath.endsWith('.css'),
     message:
@@ -2760,7 +2777,7 @@ export function checkSource(text: string, relPath: string, cfg: GuardConfig): Fi
     }
   }
 
-  // raw-selection-control — full-text tag scan plus the host WINDOW (see CONTROL_HOST_WINDOW_LINES).
+  // raw-selection-control — full-text tag scan plus the host ancestry walk (see insideHostTag).
   // Three file-level exemptions mirror the plugin rule's, so the two lanes agree on the same file:
   // a file that DEFINES a basalt control (and imports none — see CONTROL_OWNER_DEF) cannot be told
   // to use one, a file importing `@mantine/form` is a form — C1's third home, whose inputs are not
@@ -2774,8 +2791,7 @@ export function checkSource(text: string, relPath: string, cfg: GuardConfig): Fi
   ) {
     for (const m of codeText.matchAll(RAW_SELECTION_CONTROL_TAG)) {
       const startLine = codeText.slice(0, m.index ?? 0).split('\n').length
-      const windowStart = Math.max(0, startLine - 1 - CONTROL_HOST_WINDOW_LINES)
-      if (CONTROL_HOST_TAG.test(codeLines.slice(windowStart, startLine).join('\n'))) continue
+      if (insideHostTag(codeText, m.index ?? 0)) continue
       const endLine = startLine + (m[0].split('\n').length - 1)
       if (isAllowedInRange(startLine, endLine, 'raw-selection-control')) continue
       findings.push({

package/src/shell/app-mobile-nav.tsx

@@ -33,6 +33,7 @@ import type {
   SidebarBlock,
   SidebarBlockItem,
   SidebarItem,
+  SidebarCustomBlock,
   SidebarListBlock,
   SidebarProgressBlock,
 } from './nav-types'
@@ -127,6 +128,14 @@ type ActionRow = {
   onClick?: ((e: MouseEvent<HTMLElement>) => void) | undefined
   /** Mirrors `SettingsMenuItem.active` — a trailing check + `aria-current` in every row form. */
   active?: boolean
+  /** Mirrors `SettingsMenuItem.current` — `'page'` swaps the check for the nav active style. */
+  current?: 'selection' | 'page'
+}
+
+/** `aria-current` for an action row — `"page"` for a destination, `"true"` for a chosen value. */
+function rowCurrent(row: ActionRow): 'page' | 'true' | undefined {
+  if (!row.active) return undefined
+  return row.current === 'page' ? 'page' : 'true'
 }
 
 /**
@@ -198,6 +207,7 @@ function settingsRows(items: SettingsMenuItem[] | undefined): ActionRow[] {
     icon: item.icon,
     onClick: item.onClick,
     ...(item.active !== undefined && { active: item.active }),
+    ...(item.current !== undefined && { current: item.current }),
   }))
 }
 
@@ -248,10 +258,10 @@ const menuActionRow = (row: ActionRow, sectionStart = false) => (
     key={row.key}
     className={sectionStart ? `${classes.menuItem} ${classes.menuSectionStart}` : classes.menuItem}
     leftSection={row.icon}
-    rightSection={row.active ? <IconCheck /> : undefined}
+    rightSection={row.active && row.current !== 'page' ? <IconCheck /> : undefined}
     {...(row.danger ? { color: 'red' } : {})}
     onClick={(event: MouseEvent<HTMLElement>) => row.onClick?.(event)}
-    aria-current={row.active ? 'true' : undefined}
+    aria-current={rowCurrent(row)}
   >
     {row.label}
   </Menu.Item>
@@ -353,12 +363,13 @@ export function MobileNav({
    * applies — the count that picked `menu` vs `sheet` and the rows that render must agree.
    */
   const moreBlocks = (blocks ?? []).filter(
-    (block): block is SidebarListBlock | SidebarProgressBlock =>
-      block.kind !== 'custom' &&
-      sidebarBlockMobile(block) === 'more' &&
-      (block.kind !== 'list' || block.items.length > 0),
+    (block): block is SidebarListBlock | SidebarProgressBlock | SidebarCustomBlock =>
+      sidebarBlockMobile(block) === 'more' && (block.kind !== 'list' || block.items.length > 0),
+  )
+  // The blocks that open a nested sheet — a list's rows, or a custom block's node.
+  const sheetBlocks = moreBlocks.filter(
+    (block): block is SidebarListBlock | SidebarCustomBlock => block.kind !== 'progress',
   )
-  const listBlocks = moreBlocks.filter((block): block is SidebarListBlock => block.kind === 'list')
 
   /**
    * Whether the More surface's UNLABELLED tail (blocks + account + settings) opens its own band —
@@ -369,10 +380,10 @@ export function MobileNav({
   const tailRule = (slot: SurfaceSlot): boolean =>
     moreBlocks.length + extraRows.length > 0 && slotHasRows(slot)
 
-  /** A list block raises its nested sheet; a progress block just fires its own handler. */
+  /** A list or custom block raises its nested sheet; a progress block just fires its own handler. */
   const activateBlock = (block: (typeof moreBlocks)[number]) => {
     close()
-    if (block.kind === 'list') {
+    if (block.kind !== 'progress') {
       // ONE FRAME, deliberately. `close()` starts the Menu's `returnFocus` (it restores focus to
       // the More tab) while the nested Drawer traps focus on mount — in the same handler the two
       // race, and focus lands wherever the loser wrote last, which is how a tap on a block row
@@ -614,13 +625,14 @@ export function MobileNav({
       classNames={{ root: classes.row }}
       label={row.label}
       leftSection={row.icon}
-      rightSection={row.active ? <IconCheck /> : undefined}
+      rightSection={row.active && row.current !== 'page' ? <IconCheck /> : undefined}
       {...(row.danger ? { color: 'red' } : {})}
       onClick={(event: MouseEvent<HTMLElement>) => {
         row.onClick?.(event)
         close()
       }}
-      aria-current={row.active ? 'true' : undefined}
+      active={row.active === true && row.current === 'page'}
+      aria-current={rowCurrent(row)}
     />
   )
 
@@ -773,7 +785,7 @@ export function MobileNav({
    * exit transition would play against a blank sheet; a closed Mantine Drawer renders nothing, so N
    * instances cost N nothings.
    */
-  const blockSheet = (block: SidebarListBlock) => (
+  const blockSheet = (block: SidebarListBlock | SidebarCustomBlock) => (
     <Drawer
       key={`block-${block.key}`}
       opened={openBlockKey === block.key}
@@ -799,7 +811,11 @@ export function MobileNav({
       }}
     >
       <ScrollArea.Autosize mah="62dvh" type="scroll" offsetScrollbars="present" scrollbarSize={8}>
-        <Stack gap={1}>{block.items.map(blockItemRow)}</Stack>
+        {block.kind === 'list' ? (
+          <Stack gap={1}>{block.items.map(blockItemRow)}</Stack>
+        ) : (
+          block.node
+        )}
       </ScrollArea.Autosize>
     </Drawer>
   )
@@ -815,13 +831,16 @@ export function MobileNav({
         if (slot.kind === 'menu') return menuSlot(slot)
         return sheetSlot(slot)
       })}
-      {listBlocks.map(blockSheet)}
+      {sheetBlocks.map(blockSheet)}
     </nav>
   )
 }
 
 /** `Awaiting action · 3` — the row's whole job is to say how much is behind it. */
-function blockRowLabel(block: SidebarListBlock | SidebarProgressBlock): string {
+function blockRowLabel(
+  block: SidebarListBlock | SidebarProgressBlock | SidebarCustomBlock,
+): string {
+  if (block.kind === 'custom') return block.label ?? ''
   return block.kind === 'list'
     ? `${block.label} · ${block.count ?? block.items.length}`
     : `${block.label} · ${block.value} of ${block.total}`

package/src/shell/app-sidebar-account.tsx

@@ -101,6 +101,9 @@ export function SidebarAccount(props: BasaltAccountProps & BasaltProps) {
     return (
       <UnstyledButton
         className={cx(classes.accountRow, className)}
+        // The collapsed rail hides `.accountText` (display:none), which drops "Sign in" from the
+        // accessibility tree — the label keeps the button nameable with only the glyph showing.
+        aria-label="Sign in"
         onClick={actions?.onSignIn}
         {...(style !== undefined && { style })}
       >

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

@@ -249,6 +249,21 @@
   color: var(--vx-ink);
 }
 
+/* A settings entry that IS the current page (`SettingsMenuItem.current: 'page'`) — the nav row's
+ * active treatment (theme/nav-link.module.css): accent fill, weight 600, accent icon. */
+.footerBtn[aria-current='page'],
+.settingsMenuItem[aria-current='page'] {
+  background-color: color-mix(in srgb, var(--vx-accent) 12%, transparent);
+  color: var(--vx-ink);
+  font-weight: 600;
+}
+
+.footerBtn[aria-current='page'] > svg,
+.footerBtn[aria-current='page'] .footerIconSlot > svg,
+.settingsMenuItem[aria-current='page'] [data-position='left'] {
+  color: var(--vx-accent);
+}
+
 .footerText {
   flex: 1;
   text-align: left;
@@ -399,6 +414,25 @@
   color: var(--vx-ink);
 }
 
+/* A custom block's rail trigger (`rail: 'icon'`) — a footer-row-sized icon target. */
+.blockRailTrigger {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: var(--vx-space-row-inset-y) var(--vx-space-row-inset-x);
+  border-radius: var(--vx-radius-ctrl);
+  color: var(--vx-faint);
+}
+
+.blockRailTrigger:hover {
+  background-color: color-mix(in srgb, var(--vx-ink) 6%, transparent);
+  color: var(--vx-ink);
+}
+
+.blockRailPopover {
+  min-width: 220px;
+}
+
 .blockIcon {
   position: relative;
   display: flex;
@@ -717,6 +751,11 @@
     display: none;
   }
 
+  .root[data-collapsed] .block[data-rail='icon'] {
+    display: flex;
+    justify-content: center;
+  }
+
   .root[data-collapsed] .block[data-rail='dot'] .blockHeader {
     justify-content: center;
     padding: 0;

package/src/shell/app-sidebar.module.css.d.ts

@@ -42,5 +42,8 @@ declare const classes: {
   readonly footerLinks: string
   readonly footerIconSlot: string
   readonly footerVersion: string
+  readonly settingsMenuItem: string
+  readonly blockRailTrigger: string
+  readonly blockRailPopover: string
 }
 export default classes

package/src/shell/app-sidebar.tsx

@@ -183,6 +183,12 @@ function hasActiveDescendant(item: SidebarItem): boolean {
   return item.children?.some((c) => hasActiveDescendant(c)) ?? false
 }
 
+/** `aria-current` for a settings entry: `"page"` for a destination, `"true"` for a chosen value. */
+function settingsCurrent(entry: SettingsMenuItem): 'page' | 'true' | undefined {
+  if (!entry.active) return undefined
+  return entry.current === 'page' ? 'page' : 'true'
+}
+
 /**
  * Renders a nav link body without the Tooltip/Box wrapper.
  *
@@ -488,7 +494,7 @@ export function AppSidebar(props: AppSidebarProps) {
             className={classes.footerBtn}
             onClick={entry.onClick}
             aria-label={entry.label}
-            aria-current={entry.active ? 'true' : undefined}
+            aria-current={settingsCurrent(entry)}
           >
             {/* A FIXED slot, so rows align on one icon column whether or not each ships an icon —
                 and the gear fallback is functional, not decorative: in the collapsed rail the label
@@ -501,7 +507,7 @@ export function AppSidebar(props: AppSidebarProps) {
             </Text>
             {/* The rail ring rides the FIRST row only — one progress block is one mark. */}
             {index === 0 ? ringMark : null}
-            {entry.active ? <IconCheck /> : null}
+            {entry.active && entry.current !== 'page' ? <IconCheck /> : null}
           </UnstyledButton>
         ))}
         {versionLabel !== undefined && (
@@ -526,10 +532,11 @@ export function AppSidebar(props: AppSidebarProps) {
             {settingsItems.map((entry) => (
               <Menu.Item
                 key={entry.key}
+                className={classes.settingsMenuItem}
                 leftSection={entry.icon}
-                rightSection={entry.active ? <IconCheck /> : undefined}
+                rightSection={entry.active && entry.current !== 'page' ? <IconCheck /> : undefined}
                 onClick={entry.onClick}
-                aria-current={entry.active ? 'true' : undefined}
+                aria-current={settingsCurrent(entry)}
               >
                 {entry.label}
               </Menu.Item>
@@ -576,7 +583,7 @@ export function AppSidebar(props: AppSidebarProps) {
             <NavSection key={section.label} section={section} collapsed={collapsed} />
           ))}
           {navBlocks.map((block) => (
-            <SidebarBlockView key={block.key} block={block} />
+            <SidebarBlockView key={block.key} block={block} collapsed={collapsed} />
           ))}
         </Stack>
       </ScrollArea>
@@ -584,7 +591,7 @@ export function AppSidebar(props: AppSidebarProps) {
       {(bottomBlocks.length > 0 || settingsRow !== null || account !== undefined) && (
         <Stack gap={0} className={classes.footer}>
           {bottomBlocks.map((block) => (
-            <SidebarBlockView key={block.key} block={block} />
+            <SidebarBlockView key={block.key} block={block} collapsed={collapsed} />
           ))}
           {settingsRow}
           {account !== undefined && (

package/src/shell/index.tsx

@@ -130,10 +130,16 @@ export type SettingsMenuItem = {
   label: string
   icon?: ReactNode
   onClick?: (e: MouseEvent) => void
-  /** This entry is the current selection (e.g. the active theme radio, the open dev tool) — a
-   * trailing check glyph renders in every form (flat footer row, gear `Menu.Item`, the mobile
-   * More-sheet row) and the row carries `aria-current="true"`. */
+  /** This entry is the current one (e.g. the active theme radio, the open dev tool, the open
+   * settings page) — how it shows is `current`. */
   active?: boolean
+  /**
+   * What `active` means. `'selection'` (default) is a chosen value: a trailing check glyph in every
+   * form (flat footer row, gear `Menu.Item`, the mobile More-sheet row) and `aria-current="true"`.
+   * `'page'` is a navigation destination: no check, the nav-item active style, and
+   * `aria-current="page"` — what a router-backed settings entry wants.
+   */
+  current?: 'selection' | 'page'
 }
 
 export type BasaltShellProps = BasaltProps & {
@@ -167,8 +173,9 @@ export type BasaltShellProps = BasaltProps & {
    * Because they are data, basalt owns the projections the two `ReactNode` slots could not express:
    * a `list` with a `count` becomes a dot on its icon in the collapsed rail, a `progress` block
    * becomes a ring on the settings row, and a block with `mobile: 'more'` becomes one More-sheet
-   * row opening a nested sheet of its items. A `kind: 'custom'` block is desktop-only, exactly as
-   * `sidebarNavExtra` was.
+   * row opening a nested sheet of its items. A `kind: 'custom'` block is desktop-only and hidden in the rail, exactly
+   * as `sidebarNavExtra` was, unless it opts in with `icon` + `label` (a rail icon opening it in a
+   * popover) and `mobile: 'more'` (a More row opening it in a sheet).
    */
   sidebarBlocks?: SidebarBlock[]
   /**

package/src/shell/nav-types.ts

@@ -139,9 +139,10 @@ export type SidebarProgressBlock = {
 }
 
 /**
- * DESKTOP ONLY — arbitrary consumer content (a tree, a filter panel) that no set of rows can
- * express. Replaced `BasaltShellProps.sidebarNavExtra`; hidden on the collapsed rail and absent
- * from mobile for the same reason that prop was.
+ * Arbitrary consumer content (a tree, a filter panel) that no set of rows can express. Replaced
+ * `BasaltShellProps.sidebarNavExtra`. By default desktop-only and hidden on the collapsed rail,
+ * exactly as that prop was; `icon` + `label` opt it into the rail (as an icon opening the node in a
+ * popover) and `mobile: 'more'` into the More sheet.
  */
 export type SidebarCustomBlock = {
   kind: 'custom'
@@ -149,6 +150,21 @@ export type SidebarCustomBlock = {
   node: ReactNode
   /** @default 'nav' */
   placement?: 'nav' | 'bottom'
+  /** The rail icon. Needs `label` too: an icon-only trigger must be nameable. */
+  icon?: ReactNode
+  /** The rail icon's accessible name, the popover heading and the More row / sheet title. */
+  label?: string
+  /**
+   * Collapsed-rail projection: `'icon'` swaps the node for `icon`, which opens it in a popover.
+   * @default 'icon' when both `icon` and `label` are set, `'hidden'` otherwise
+   */
+  rail?: 'icon' | 'hidden'
+  /**
+   * Below `sm` there is no sidebar: `'more'` makes one More row, labelled `label`, that opens the
+   * node in a sheet. Needs `label`.
+   * @default 'hidden'
+   */
+  mobile?: 'more' | 'hidden'
 }
 
 /**

package/src/shell/sidebar-block-model.ts

@@ -26,11 +26,17 @@ export function sidebarBlockPlacement(block: SidebarBlock): 'nav' | 'bottom' {
 /**
  * The collapsed-rail projection. A list block earns a dot only when it carries a `count` — a rail
  * icon with no number behind it is a dot that means nothing — and a progress block a ring on the
- * settings row. A `custom` block has no rail representation at all (arbitrary content in ~48px of
- * icon column), which is exactly what `sidebarNavExtra` did before it.
+ * settings row. A `custom` block has a rail form only when it opts in (see below), which is
+ * `sidebarNavExtra`'s old hidden-in-the-rail behaviour otherwise.
  */
-export function sidebarBlockRail(block: SidebarBlock): 'dot' | 'ring' | 'hidden' {
-  if (block.kind === 'custom') return 'hidden'
+export function sidebarBlockRail(block: SidebarBlock): 'dot' | 'ring' | 'icon' | 'hidden' {
+  // A `custom` block is arbitrary content with no icon-column form of its own, so it is hidden
+  // unless the consumer supplied the icon AND the name that make a rail trigger. Like a list's dot,
+  // that overrides an explicit `rail: 'icon'` without them.
+  if (block.kind === 'custom') {
+    if (block.icon === undefined || block.label === undefined) return 'hidden'
+    return block.rail ?? 'icon'
+  }
   if (block.kind === 'progress') return block.rail ?? 'ring'
   // A dot has to sit ON something. With no `icon` there is no rail node to badge, and with no
   // `count` there is no number behind the dot — either way the block leaves the rail rather than
@@ -47,7 +53,9 @@ export function sidebarBlockRail(block: SidebarBlock): 'dot' | 'ring' | 'hidden'
  * threshold is measured against.
  */
 export function sidebarBlockMobile(block: SidebarBlock): 'more' | 'hidden' {
-  if (block.kind === 'custom') return 'hidden'
+  // A custom block's More row is named by `label`; without one there is nothing to name it.
+  if (block.kind === 'custom')
+    return block.mobile === 'more' && block.label !== undefined ? 'more' : 'hidden'
   if (block.kind === 'progress') return block.mobile ?? 'hidden'
   return block.mobile ?? 'more'
 }

package/src/shell/sidebar-blocks.tsx

@@ -12,7 +12,7 @@
  * module's class. A second CSS module would hash `.block*` into a different name than the rail
  * rules could ever select.
  */
-import { Collapse, NavLink, Progress, Text, UnstyledButton } from '@mantine/core'
+import { Collapse, NavLink, Popover, Progress, Text, UnstyledButton } from '@mantine/core'
 import { useState } from 'react'
 import type { ReactNode } from 'react'
 import type {
@@ -280,10 +280,33 @@ function ProgressBlock({ block }: { block: SidebarProgressBlock }) {
   )
 }
 
-/** A `kind: 'custom'` block — consumer content, hidden on the rail exactly as `navExtra` was. */
-function CustomBlock({ block }: { block: SidebarCustomBlock }) {
+/**
+ * A `kind: 'custom'` block — consumer content. Without `icon` + `label` it is hidden on the rail
+ * exactly as `navExtra` was (CSS only, the node stays mounted). With them the rail swaps the node
+ * for its icon, which opens the node in a popover: that swap is JS-gated on `collapsed`, because
+ * the trigger is a different element and nothing in the node's own subtree could express it. The
+ * popover mounts only while open, so the inline node is never duplicated.
+ */
+function CustomBlock({ block, collapsed }: { block: SidebarCustomBlock; collapsed: boolean }) {
+  const rail = sidebarBlockRail(block)
+  if (collapsed && rail === 'icon') {
+    return (
+      <div className={classes.block} data-rail="icon">
+        <Popover position="right-start" withArrow={false} offset={4} withinPortal zIndex={400}>
+          <Popover.Target>
+            <UnstyledButton className={classes.blockRailTrigger} aria-label={block.label}>
+              <IconSlot>{block.icon}</IconSlot>
+            </UnstyledButton>
+          </Popover.Target>
+          <Popover.Dropdown p="xs" className={classes.blockRailPopover}>
+            {block.node}
+          </Popover.Dropdown>
+        </Popover>
+      </div>
+    )
+  }
   return (
-    <div className={classes.block} data-rail="hidden">
+    <div className={classes.block} data-rail={rail}>
       {block.node}
     </div>
   )
@@ -292,10 +315,12 @@ function CustomBlock({ block }: { block: SidebarCustomBlock }) {
 /** One block, whichever kind it is. `AppSidebar` places it; this decides nothing but the paint. */
 export function SidebarBlockView({
   block,
+  collapsed = false,
 }: {
   block: SidebarListBlock | SidebarProgressBlock | SidebarCustomBlock
+  collapsed?: boolean
 }) {
   if (block.kind === 'list') return <ListBlock block={block} />
   if (block.kind === 'progress') return <ProgressBlock block={block} />
-  return <CustomBlock block={block} />
+  return <CustomBlock block={block} collapsed={collapsed} />
 }

package/src/surfaces.ts

@@ -564,8 +564,8 @@ export const SURFACES = {
     layer: 'mantine-coupled',
     rule: 'controls',
     skill: ['basalt-design'],
-    // The text lane of law C1 — the plugin's `control-outside-home` seen through a 12-line host-tag
-    // window, since a regex scan has no ancestry. Same law, same wave, same promotion.
+    // The text lane of law C1 — the plugin's `control-outside-home` seen through a host-tag nesting
+    // count, since a regex scan has no AST. Same law, same wave, same promotion.
     guardKinds: ['raw-selection-control'],
     // The control tier itself (laws C1/C3/C5/C9). `hand-rolled-filter`, `control-size-literal` and
     // `responsive-twin` all ship `error`; the two C1 placement rules are the grace entries in

package/src/tokens/index.ts

@@ -824,7 +824,7 @@ function warnConsumerVxName(name: string): void {
   if (!BASALT_VX_FAMILIES.includes(family) || warnedVxNames.has(name)) return
   warnedVxNames.add(name)
   console.warn(
-    `[basalt] ${name} is inside basalt's own --vx-${family} family — name your series group something basalt does not own (groupTokens('app', …)). Throws from 1.35.0.`,
+    `[basalt] ${name} is inside basalt's own --vx-${family} family — name your series group something basalt does not own (groupTokens('app', …)). Throws from 1.36.0.`,
   )
 }