basalt-ui 1.34.1 → 1.36.0

package/src/common/index.ts

@@ -19,4 +19,5 @@ export {
 } from './errors'
 export { useValidateProps, assertRequiredProps, resetValidatedProps } from './validate'
 export { scrollParentOf, SCROLLPORT_ATTRIBUTE } from './scroll-parent'
+export { useCoarsePointer } from './use-media-query'
 export { MOTION_DURATION, MOTION_EASE_STANDARD, MOTION_SPRING } from './motion'

package/src/common/use-media-query.ts

@@ -54,3 +54,13 @@ export function useMediaQuery(query: string, serverFallback: boolean): boolean {
   const getServerSnapshot = useCallback(() => serverFallback, [serverFallback])
   return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot)
 }
+
+/**
+ * Whether the primary pointer is coarse — the JS twin of `--vx-hit`'s `(pointer: coarse)` query.
+ * For a branch CSS cannot express (mount one of two components, attach a keydown listener); styling
+ * stays `@media (pointer: coarse)` in a CSS module. Server and hydration snapshot is `false`; a
+ * `createRoot` app reads the real pointer on its first render.
+ */
+export function useCoarsePointer(): boolean {
+  return useMediaQuery('(pointer: coarse)', false)
+}

package/src/common/vx-families.ts

@@ -2,7 +2,7 @@
 
 /**
  * The families every emitted `--vx-*` name lives in (`basaltVxFamilies`) — basalt-owned:
- * `unknown-vx-token` judges every name inside one, and `groupTokens`/`seriesTokens` warn on a
+ * `unknown-vx-token` judges every name inside one, and `groupTokens`/`seriesTokens` throw on a
  * consumer ref there.
  */
 export const BASALT_VX_FAMILIES: readonly string[] = [

package/src/{forms → controls}/form-layout.tsx

@@ -1,6 +1,8 @@
 /**
- * ./forms — the form layout primitives: `FormSection`, `FormRow`, `FormGroup`, `FormActions`.
- * Mantine-coupled. Optional peer: @mantine/form (these four need none of it — they are layout).
+ * ./controls — the form layout primitives: `FormSection`, `FormRow`, `FormGroup`, `FormActions`.
+ * Mantine-coupled. They need no `@mantine/form` (layout only), which is why they live here and not
+ * in `./forms`, whose barrel value-imports it: importing a row from there made a consumer install a
+ * peer it never used. `./forms` re-exports them as deprecated aliases until 1.37.0.
  *
  * The gap they close (audit B #5 / §4): `./forms` shipped no layout at all, so the only row
  * primitive in the package was `SettingsRow` over in `./dashboard` — which is the SETTINGS-page
@@ -22,11 +24,11 @@ import type { ReactNode } from 'react'
 import { cx } from '../common/props'
 import type { BasaltProps, SlotStylesProps } from '../common/props'
 import { assertRequiredProps } from '../common/validate'
-import { BarActionSlot } from '../controls/actions'
-import type { SlotActions } from '../controls/actions'
+import { BarActionSlot } from './actions'
+import type { SlotActions } from './actions'
 import { WidgetHeader } from '../dashboard'
 import type { WidgetHeaderTitleProps } from '../dashboard'
-import { useFormState } from './form-state'
+import { useFormState } from '../forms/form-state'
 import classes from './form-layout.module.css'
 
 // ── the two fragments FormRow and FormGroup both paint ────────────────────────

package/src/controls/index.ts

@@ -53,3 +53,19 @@ export { ViewTabs, type ViewTabsOption, type ViewTabsProps } from './view-tabs'
 // docs. The filters above render their own panel forms; there is nothing extra to import for them.
 export { PanelRow, type PanelRowProps } from './panel-row'
 export { SliderControl, type SliderControlProps } from './slider-control'
+
+// ── The form layout (moved from ./forms in 1.36.0) ────────────────────────────────────────────
+// Layout needs no `@mantine/form`, and `./forms`' barrel value-imports it — so a consumer rendering
+// a `FormRow` had to install a peer it never used. `./forms` re-exports these until 1.37.0.
+export {
+  FormSection,
+  FormRow,
+  FormGroup,
+  FormActions,
+  type FormSectionProps,
+  type FormSectionSlot,
+  type FormRowProps,
+  type FormRowSlot,
+  type FormGroupProps,
+  type FormActionsProps,
+} from './form-layout'

package/src/forms/index.ts

@@ -6,10 +6,12 @@
  * `basalt-ui`. Same reason `./charts` and `./tokens` stay off the root barrel, one optional peer
  * over. Import everything below from `basalt-ui/forms`.
  *
- * Five pieces: the form (`useBasaltForm` + `inputProps`/`fieldKey`), the layout
- * (`FormSection` / `FormRow` / `FormGroup` / `FormActions`), the submit lifecycle
+ * Four pieces: the form (`useBasaltForm` + `inputProps`/`fieldKey`), the submit lifecycle
  * (`useFormSubmit` + `FormStateProvider`), the list field (`useFieldArray`) and the draft
- * (`useFormDraft`).
+ * (`useFormDraft`). The layout (`FormSection` / `FormRow` / `FormGroup` / `FormActions`) moved to
+ * `basalt-ui/controls` in 1.36.0 — it needs no `@mantine/form` — and stays here as deprecated
+ * aliases until 1.37.0, as do the `useForm`/`schemaResolver` re-exports (import from
+ * `@mantine/form`).
  *
  * Optional peer: @mantine/form ^9.3.0 — install with: bun add @mantine/form
  */
@@ -22,16 +24,31 @@ export type { UseBasaltFormOptions } from './create-form'
 // Two calls, never one object: `key` inside a spread is a React 19 warning. See field.ts.
 export { inputProps, fieldKey } from './field'
 
-// ── layout — law C1's third home, the form row ────────────────────────────────
-export { FormSection, FormRow, FormGroup, FormActions } from './form-layout'
+// ── layout — moved to ./controls (1.36.0), deprecated aliases until 1.37.0 ─────
+export {
+  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.37.0. */
+  FormSection,
+  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.37.0. */
+  FormRow,
+  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.37.0. */
+  FormGroup,
+  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.37.0. */
+  FormActions,
+} from '../controls/form-layout'
 export type {
+  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.37.0. */
   FormSectionProps,
+  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.37.0. */
   FormSectionSlot,
+  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.37.0. */
   FormRowProps,
+  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.37.0. */
   FormRowSlot,
+  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.37.0. */
   FormGroupProps,
+  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.37.0. */
   FormActionsProps,
-} from './form-layout'
+} from '../controls/form-layout'
 
 // ── submit lifecycle ──────────────────────────────────────────────────────────
 export { useFormSubmit, isFieldErrorEnvelope } from './use-form-submit'
@@ -51,6 +68,16 @@ export type { FormErrorSummaryProps } from './FormErrorSummary'
 export { useFormDraft, DEFAULT_AUTOSAVE_DEBOUNCE_MS } from './use-form-draft'
 export type { UseFormDraftOptions, UseFormDraftReturn } from './use-form-draft'
 
-// ── @mantine/form re-exports (convenience) ────────────────────────────────────
-export { useForm, schemaResolver } from '@mantine/form'
-export type { UseFormReturnType, UseFormInput } from '@mantine/form'
+// ── @mantine/form re-exports — deprecated, zero consumers import them from here ──
+export {
+  /** @deprecated Import from '@mantine/form' — removed in 1.37.0. */
+  useForm,
+  /** @deprecated Import from '@mantine/form' — removed in 1.37.0. */
+  schemaResolver,
+} from '@mantine/form'
+export type {
+  /** @deprecated Import from '@mantine/form' — removed in 1.37.0. */
+  UseFormReturnType,
+  /** @deprecated Import from '@mantine/form' — removed in 1.37.0. */
+  UseFormInput,
+} from '@mantine/form'

package/src/guard/index.ts

@@ -334,7 +334,7 @@ const KNOWN_VX_NAMES: ReadonlySet<string> = new Set(BASALT_VX_NAMES)
  * emitted set, so `--vx-surface-2` and a bare root like `--vx-space` are both findings.
  *
  * That judgement is honest only because no consumer ref may point into these families:
- * `groupTokens`/`seriesTokens` warn on a name inside one (and throw once this kind promotes). A name in any OTHER family (argo's
+ * `groupTokens`/`seriesTokens` throw on a name inside one. A name in any OTHER family (argo's
  * `--vx-activity-*`, rb's `--vx-confidence-*`) may be a consumer group declared in a file this scan
  * cannot see, and is never judged.
  */
@@ -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_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.
  */
-const CONTROL_HOST_WINDOW_LINES = 12
+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
@@ -878,6 +893,8 @@ export type GraceEntry = { since: string; promote: string; why: string }
 
 /**
  * Kinds still inside their grace minor — reported, not fatal, until the next minor promotes them.
+ * Empty since 1.36.0: `unknown-vx-token`, the last tenant, promoted (its grace ran one minor past
+ * 1.35.0 to keep the factory throw out of the a11y release).
  * See {@link GuardSeverity} for the doctrine and why basalt-ui in particular needs it.
  *
  * Adding a kind here is part of shipping it; removing the entry IS the promotion, and belongs in
@@ -914,17 +931,7 @@ export type GraceEntry = { since: string; promote: string; why: string }
  *   'raw-font-family': { since: '1.4.0', promote: '1.5.0', why: 'introduced 1.4.0 — …' },
  * }
  */
-export const GRACE_PERIOD_KINDS: Partial<Record<GuardKind, GraceEntry>> = {
-  'unknown-vx-token': {
-    since: '1.34.0',
-    promote: '1.35.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.',
-  },
-}
+export const GRACE_PERIOD_KINDS: Partial<Record<GuardKind, GraceEntry>> = {}
 
 /** A kind's effective severity: consumer override first, then the grace table, then `error`. */
 function severityOf(kind: GuardKind, cfg: GuardConfig): GuardSeverity {
@@ -2232,7 +2239,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:
@@ -2255,7 +2262,7 @@ export const GUARD_RULES = {
   'unknown-vx-token': {
     kind: 'unknown-vx-token',
     pattern: VX_VAR_REF, // handled inline (basalt-owned families); entry keeps the registry complete
-    message: `var() names a --vx-* token basalt does not emit, so it resolves to its fallback (or to nothing) with no error anywhere. Judged: every name inside a basalt-owned family (${[...BASALT_VX_FAMILY_SET].join(', ')}) — pick the token from basalt-ui/tokens.css; your own series belong in a family of their own (groupTokens warns on one inside basalt's). Removed names and their replacements: ${Object.entries(
+    message: `var() names a --vx-* token basalt does not emit, so it resolves to its fallback (or to nothing) with no error anywhere. Judged: every name inside a basalt-owned family (${[...BASALT_VX_FAMILY_SET].join(', ')}) — pick the token from basalt-ui/tokens.css; your own series belong in a family of their own (groupTokens throws on one inside basalt's, in dev builds). Removed names and their replacements: ${Object.entries(
       REMOVED_VX_NAMES,
     )
       .map(([from, to]) => `${from} → ${to ?? '(deleted, no replacement)'}`)
@@ -2760,7 +2767,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 +2781,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/index.ts

@@ -31,6 +31,7 @@ export {
   cx,
   scrollParentOf,
   SCROLLPORT_ATTRIBUTE,
+  useCoarsePointer,
 } from './common'
 
 export { createBasaltTheme, baseTheme, cssVariablesResolver } from './theme'

package/src/provider/index.tsx

@@ -113,10 +113,11 @@ export type BasaltProviderProps = {
   connectivity?: Omit<ConnectivityProviderProps, 'children'>
   /**
    * The size class `useSizeClass()` reports on the server and during hydration, before `matchMedia`
-   * can answer. Default `'compact'` (mobile-first). An SSR app that knows the device class (UA
-   * hint, cookie) passes it so the first frame already matches. An SSR desktop app SHOULD pass it:
-   * without it the first paint is `'compact'`, and `PageAside`/`ThreadWorkspace` remount after
-   * hydration when the real class lands.
+   * can answer. Default `'compact'` (mobile-first). SSR only: a client-rendered (`createRoot`) app
+   * reads `matchMedia` on its first render and never sees this value. An SSR app that knows the
+   * device class (UA hint, cookie) passes it so the first frame already matches. An SSR desktop app
+   * SHOULD pass it: without it the first paint is `'compact'`, and `PageAside`/`ThreadWorkspace`
+   * remount after hydration when the real class lands.
    */
   sizeClassHint?: SizeClass
 } & Omit<MantineProviderProps, 'children' | 'theme' | 'defaultColorScheme' | 'cssVariablesResolver'>

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[]
   /**