basalt-ui 1.34.0 → 1.35.0

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.`,
   )
 }