basalt-ui 1.25.0 → 1.26.0

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

@@ -0,0 +1,83 @@
+/**
+ * The sidebar-block law — every default a `SidebarBlock` leaves unstated, plus the two persisted
+ * fold-key grammars.
+ *
+ * PURE BY CONTRACT, for the same reason `mobile-nav-model.ts` is: three consumers read these
+ * defaults and none of them may disagree. `app-sidebar.tsx` decides where a block renders and
+ * whether the rail keeps it, `sidebar-blocks.tsx` paints it, and `mobile-nav-model.ts` counts the
+ * More-sheet rows it will produce — a count that picks `menu` vs `sheet` before any of it renders.
+ * A default re-derived per call site is how the count and the renderer drift apart (see
+ * `accountRowCount`'s doc for the same failure with account rows).
+ */
+import type { SidebarBlock } from '../nav/types'
+
+/** Envelope version for a persisted fold flag. Bump only if the value stops being a boolean. */
+export const FOLD_VERSION = 1
+
+/**
+ * `'nav'` renders after the nav sections inside the scroll region; `'bottom'` pins above the
+ * settings footer. A progress block is `'bottom'` — it is a pinned status row, not a nav tail.
+ */
+export function sidebarBlockPlacement(block: SidebarBlock): 'nav' | 'bottom' {
+  if (block.kind === 'progress') return block.placement ?? 'bottom'
+  return block.placement ?? 'nav'
+}
+
+/**
+ * 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.
+ */
+export function sidebarBlockRail(block: SidebarBlock): 'dot' | 'ring' | 'hidden' {
+  if (block.kind === 'custom') return 'hidden'
+  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
+  // occupying ~48px of icon column with a label the rail has already hidden. This overrides an
+  // explicit `rail: 'dot'` too: that combination is a config mistake, not a shape to render blank.
+  if (block.icon === undefined || block.count === undefined) return 'hidden'
+  return block.rail ?? 'dot'
+}
+
+/**
+ * The mobile projection. A list is reachable from More by default — below `sm` the sidebar does
+ * not render at all, so a hidden list is unreachable, not merely unshown. A progress row defaults
+ * to `'hidden'`: it is ambient status, and every More row costs headroom the menu-vs-sheet
+ * threshold is measured against.
+ */
+export function sidebarBlockMobile(block: SidebarBlock): 'more' | 'hidden' {
+  if (block.kind === 'custom') return 'hidden'
+  if (block.kind === 'progress') return block.mobile ?? 'hidden'
+  return block.mobile ?? 'more'
+}
+
+/** Rows a list block paints, honouring `max` — the "Show more" toggle reveals the remainder. */
+export function sidebarBlockVisibleCount(itemCount: number, max: number | undefined): number {
+  if (max === undefined || max >= itemCount) return itemCount
+  return Math.max(0, max)
+}
+
+/**
+ * A section label as a storage-key segment. Lowercase, every run of non-alphanumerics collapsed to
+ * one `-`, no leading/trailing separator — `'Awaiting action'` → `'awaiting-action'`.
+ */
+export function slugifyLabel(label: string): string {
+  return label
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}
+
+/**
+ * `createPersistedState` namespaces every key as `basalt:<key>`, so these return the UNNAMESPACED
+ * halves — the real storage keys are `basalt:sidebar-block:<key>` and
+ * `basalt:sidebar-section:<label-slug>` (`docs/CONTROLS-SPEC.md` §2.3).
+ */
+export function sidebarBlockFoldKey(blockKey: string): string {
+  return `sidebar-block:${blockKey}`
+}
+
+export function sidebarSectionFoldKey(label: string): string {
+  return `sidebar-section:${slugifyLabel(label)}`
+}

package/src/shell/sidebar-blocks.tsx

@@ -0,0 +1,301 @@
+/**
+ * Sidebar blocks — the renderer for `SidebarBlock[]` (`docs/CONTROLS-SPEC.md` §2.3, law C13).
+ *
+ * A block is the "Awaiting action" / "Recents" / "Getting started 1 of 5" shape every consumer
+ * hand-rolled into `sidebarNavExtra`: a micro-label, a short list of NON-destination rows, and
+ * sometimes a fold. Because it arrives as DATA, basalt owns the two projections a `ReactNode` slot
+ * could never express — the collapsed rail (a dot on the icon, a ring on the settings row) and the
+ * mobile More sheet (`app-mobile-nav.tsx`).
+ *
+ * Styling deliberately lives in `app-sidebar.module.css`, not in a module of its own: the
+ * collapsed-rail rules are `.root[data-collapsed] …` descendant selectors, and `.root` is that
+ * 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 { useState } from 'react'
+import type { ReactNode } from 'react'
+import type {
+  SidebarBlockItem,
+  SidebarBlockTone,
+  SidebarCustomBlock,
+  SidebarListBlock,
+  SidebarProgressBlock,
+} from '../nav/types'
+import { NavCountBadge } from './nav-count-badge'
+import { createPersistedState } from '../state'
+import {
+  FOLD_VERSION,
+  sidebarBlockFoldKey,
+  sidebarBlockRail,
+  sidebarBlockVisibleCount,
+} from './sidebar-block-model'
+import { IconSlot } from '../theme/icon-slot'
+import classes from './app-sidebar.module.css'
+
+/**
+ * Fold/expand chevron. Lives here rather than in `app-sidebar.tsx` purely for direction: that
+ * module imports this one, so a glyph shared by a collapsible SECTION header and a collapsible
+ * BLOCK header has to sit on this side of the edge or the two files cycle.
+ */
+export function IconChevron({ open }: { open: boolean }) {
+  return (
+    <svg
+      width={12}
+      height={12}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={2}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden
+    >
+      {open ? <path d="M6 9l6 6l6 -6" /> : <path d="M9 6l6 6l-6 6" />}
+    </svg>
+  )
+}
+
+/**
+ * One memoized `createPersistedState` store per fold key — the same module-scope factory pattern
+ * (and the same reason for it) as `collapseStore` in `index.tsx`: `createPersistedState` is a
+ * per-key FACTORY, so calling it during render would allocate a fresh store and a fresh
+ * `useSyncExternalStore` subscription on every commit. The FIRST caller's `initial` wins, which is
+ * what makes a `defaultCollapsed` a seed rather than a value that fights the persisted one.
+ */
+const foldStores = new Map<string, () => readonly [boolean, (next: boolean) => void]>()
+
+function foldStore(
+  key: string,
+  initial: boolean,
+): () => readonly [boolean, (next: boolean) => void] {
+  const cached = foldStores.get(key)
+  if (cached) return cached
+  const store = createPersistedState<boolean>({ key, version: FOLD_VERSION, initial })
+  foldStores.set(key, store)
+  return store
+}
+
+/**
+ * A persisted fold flag (`true` = folded). Exactly one hook call regardless of `key`, so swapping
+ * keys mid-life never moves the hook count.
+ *
+ * Every fold in the sidebar goes through this — block folds at `basalt:sidebar-block:<key>` and
+ * nav-section folds at `basalt:sidebar-section:<label-slug>`. Through 1.25.0 the section folds were
+ * one `useState` keyed by label, so every reload re-opened a section the user had closed.
+ */
+export function usePersistedFold(
+  key: string,
+  initial: boolean,
+): readonly [boolean, (next: boolean) => void] {
+  return foldStore(key, initial)()
+}
+
+/**
+ * Block micro-label. Reuses `.sectionLabel` — the SAME class a nav section header uses, so a block
+ * heading and a section heading cannot drift apart (docs/DESIGN-SPEC.md §3).
+ */
+function BlockLabel({ children }: { children: ReactNode }) {
+  return (
+    <Text component="div" className={classes.sectionLabel}>
+      {children}
+    </Text>
+  )
+}
+
+/** Status dot — the icon fallback for a toned row. Reads `--vx-status-*` through `data-tone`. */
+export function SidebarBlockToneDot({ tone }: { tone: SidebarBlockTone }) {
+  return <span className={classes.blockToneDot} data-tone={tone} aria-hidden />
+}
+
+/** `value` of `total` as a ring — the collapsed rail's stand-in for a progress block. */
+export function SidebarProgressRing({ value, total }: { value: number; total: number }) {
+  // r=8 in a 20x20 box: the circumference is a constant, so the arc is a dash offset rather than a
+  // path computed per render.
+  const CIRCUMFERENCE = 2 * Math.PI * 8
+  const ratio = total > 0 ? Math.min(1, Math.max(0, value / total)) : 0
+  return (
+    <span className={classes.blockRing} data-basalt-rail-ring>
+      <svg width={20} height={20} viewBox="0 0 20 20" aria-hidden>
+        <circle cx={10} cy={10} r={8} fill="none" stroke="var(--vx-divider)" strokeWidth={2} />
+        <circle
+          cx={10}
+          cy={10}
+          r={8}
+          fill="none"
+          stroke="var(--vx-accent)"
+          strokeWidth={2}
+          strokeLinecap="round"
+          strokeDasharray={CIRCUMFERENCE}
+          strokeDashoffset={CIRCUMFERENCE * (1 - ratio)}
+          transform="rotate(-90 10 10)"
+        />
+      </svg>
+    </span>
+  )
+}
+
+/**
+ * One list row. A row with no `Anchor`, `href` or `onClick` is NOT a link — the "Recents" shape is
+ * plain text, and wrapping it in an `<a>` with nowhere to go is what makes a keyboard walk through
+ * the sidebar land on dead stops.
+ */
+function BlockRow({ item }: { item: SidebarBlockItem }) {
+  // Through `IconSlot` like every other `icon` prop in the framework: a block row's leading mark is
+  // a consumer-supplied glyph, and the row's 20px rhythm cannot be at the mercy of what size that
+  // glyph declares for itself (`theme/icon-slot.tsx`). The tone dot is basalt's own and already
+  // square, but it goes through the same box so the two cases align to the same column.
+  const rawLead =
+    item.icon ?? (item.tone !== undefined ? <SidebarBlockToneDot tone={item.tone} /> : undefined)
+  const lead = rawLead === undefined ? undefined : <IconSlot>{rawLead}</IconSlot>
+  const meta =
+    item.meta !== undefined ? (
+      <Text component="span" className={classes.blockRowMeta}>
+        {item.meta}
+      </Text>
+    ) : undefined
+
+  const interactive =
+    item.Anchor !== undefined || item.href !== undefined || item.onClick !== undefined
+  if (!interactive) {
+    return (
+      <div className={`${classes.blockRow} ${classes.blockRowStatic}`}>
+        {lead}
+        <Text component="span" className={classes.blockRowLabel}>
+          {item.label}
+        </Text>
+        {meta}
+      </div>
+    )
+  }
+
+  const shared = {
+    classNames: { root: classes.blockRow },
+    label: item.label,
+    ...(lead !== undefined && { leftSection: lead }),
+    ...(meta !== undefined && { rightSection: meta }),
+    ...(item.onClick !== undefined && { onClick: item.onClick }),
+  }
+  const Anchor = item.Anchor
+  if (Anchor) return <NavLink component={Anchor} {...shared} />
+  return <NavLink component="a" {...(item.href !== undefined && { href: item.href })} {...shared} />
+}
+
+/**
+ * A `kind: 'list'` block. Two independent states, deliberately: the FOLD is persisted (a user who
+ * closes "Recents" keeps it closed across reloads) while "Show more" is ephemeral — it is a
+ * momentary reach into a longer list, not a preference, and persisting it would quietly grow the
+ * sidebar for good.
+ */
+function ListBlock({ block }: { block: SidebarListBlock }) {
+  const [folded, setFolded] = usePersistedFold(sidebarBlockFoldKey(block.key), false)
+  const [showAll, setShowAll] = useState(false)
+
+  const rail = sidebarBlockRail(block)
+  const visible = showAll
+    ? block.items.length
+    : sidebarBlockVisibleCount(block.items.length, block.max)
+  const hidden = block.items.length - visible
+
+  const label = (
+    <>
+      {block.icon !== undefined && (
+        <span className={classes.blockIcon}>
+          {block.icon}
+          {rail === 'dot' && <span className={classes.blockDot} aria-hidden />}
+        </span>
+      )}
+      <BlockLabel>{block.label}</BlockLabel>
+      {block.count ? <NavCountBadge count={block.count} /> : null}
+    </>
+  )
+
+  const body = (
+    <div className={classes.blockItems}>
+      {block.items.slice(0, visible).map((item) => (
+        <BlockRow key={item.key} item={item} />
+      ))}
+      {hidden > 0 || showAll ? (
+        <UnstyledButton
+          className={classes.blockMore}
+          onClick={() => setShowAll(!showAll)}
+          aria-expanded={showAll}
+        >
+          {showAll ? 'Show less' : 'Show more'}
+        </UnstyledButton>
+      ) : null}
+    </div>
+  )
+
+  return (
+    <div className={classes.block} data-rail={rail}>
+      {block.collapsible === true ? (
+        <>
+          <UnstyledButton
+            className={`${classes.blockHeader} ${classes.blockHeaderButton}`}
+            onClick={() => setFolded(!folded)}
+            aria-expanded={!folded}
+          >
+            {label}
+            <IconChevron open={!folded} />
+          </UnstyledButton>
+          <Collapse expanded={!folded}>{body}</Collapse>
+        </>
+      ) : (
+        <>
+          <div className={classes.blockHeader}>{label}</div>
+          {body}
+        </>
+      )}
+    </div>
+  )
+}
+
+/** A `kind: 'progress'` block — the "Getting started 1 of 5" row pinned above the footer. */
+function ProgressBlock({ block }: { block: SidebarProgressBlock }) {
+  const percent =
+    block.total > 0 ? Math.min(100, Math.max(0, (block.value / block.total) * 100)) : 0
+  const inner = (
+    <>
+      <div className={classes.blockProgressHead}>
+        <BlockLabel>{block.label}</BlockLabel>
+        <Text component="span" className={classes.blockRowMeta}>
+          {block.value} of {block.total}
+        </Text>
+      </div>
+      <Progress value={percent} size="xs" aria-label={block.label} />
+    </>
+  )
+
+  return (
+    <div className={classes.block} data-rail={sidebarBlockRail(block)}>
+      {block.onClick !== undefined ? (
+        <UnstyledButton className={classes.blockProgress} onClick={block.onClick}>
+          {inner}
+        </UnstyledButton>
+      ) : (
+        <div className={classes.blockProgress}>{inner}</div>
+      )}
+    </div>
+  )
+}
+
+/** A `kind: 'custom'` block — consumer content, hidden on the rail exactly as `navExtra` was. */
+function CustomBlock({ block }: { block: SidebarCustomBlock }) {
+  return (
+    <div className={classes.block} data-rail="hidden">
+      {block.node}
+    </div>
+  )
+}
+
+/** One block, whichever kind it is. `AppSidebar` places it; this decides nothing but the paint. */
+export function SidebarBlockView({
+  block,
+}: {
+  block: SidebarListBlock | SidebarProgressBlock | SidebarCustomBlock
+}) {
+  if (block.kind === 'list') return <ListBlock block={block} />
+  if (block.kind === 'progress') return <ProgressBlock block={block} />
+  return <CustomBlock block={block} />
+}

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

@@ -5,6 +5,18 @@
  * button as a matched pair, so the two must never drift onto different depth tokens.
  */
 
+/*
+ * The row that appears ONLY when `search.actions` is supplied — one or two icon-only buttons beside
+ * the trigger. Without actions the trigger stays the row's sole node (no wrapper), so the DOM of
+ * every consumer that doesn't use them is untouched.
+ */
+.row {
+  display: flex;
+  align-items: center;
+  gap: var(--vx-space-sidebar-search-gap);
+  min-width: 0;
+}
+
 .trigger {
   display: flex;
   align-items: center;
@@ -74,3 +86,17 @@
   background-color: color-mix(in srgb, var(--vx-ink) 6%, transparent) !important;
   color: var(--vx-ink) !important;
 }
+
+/* Trailing search-row action — the same ghost treatment as `.ghostIcon` / `.railBtn`, at the `icon`
+ * tier (24px) the component asks for explicitly. Never re-points `--ai-size`: unlike `.railBtn`,
+ * this button is NOT a second state of the trigger and must not track its height. */
+.actionBtn {
+  flex: none;
+  color: var(--vx-faint) !important;
+  border-radius: var(--vx-radius-ctrl) !important;
+}
+
+.actionBtn:hover {
+  background-color: color-mix(in srgb, var(--vx-ink) 6%, transparent) !important;
+  color: var(--vx-ink) !important;
+}

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

@@ -4,8 +4,10 @@
  * (`noUncheckedIndexedAccess`, `noPropertyAccessFromIndexSignature`, `exactOptionalPropertyTypes`).
  */
 declare const classes: {
+  readonly row: string
   readonly trigger: string
   readonly label: string
   readonly railBtn: string
+  readonly actionBtn: string
 }
 export default classes

package/src/shell/sidebar-search.tsx

@@ -8,8 +8,22 @@
  * surface + shadow-card, control radius, faint icon/label, mono `Kbd` shortcut hint.
  */
 import { ActionIcon, Kbd, Text, UnstyledButton } from '@mantine/core'
+import type { ReactNode } from 'react'
+import { OverflowMenu } from '../controls/actions'
+import type { BarAction } from '../controls/actions'
 import classes from './sidebar-search.module.css'
 
+/**
+ * The ⌘K row's trailing icon buttons — ONE or TWO, by type (`docs/CONTROLS-SPEC.md` §2.3).
+ *
+ * The tuple IS the enforcement: a third button pushes the search trigger under the width where its
+ * placeholder stays readable, and there is no third thing a sidebar search row is for. Each entry
+ * renders icon-only at the `icon` tier (24px, `--ai-size-icon`) with `label` demoted to the
+ * accessible name; a `kind: 'menu'` entry becomes an `OverflowMenu` kebab, a `kind: 'custom'` one
+ * is mounted verbatim.
+ */
+export type SidebarSearchActions = [BarAction] | [BarAction, BarAction]
+
 export type SidebarSearchConfig = {
   /** Opens the search palette — e.g. `openSpotlight` from `basalt-ui/commands`. */
   onOpen: () => void
@@ -39,12 +53,55 @@ function IconSearch() {
   )
 }
 
+/** The first grapheme of a label — the fallback body for an action shipping no icon. */
+function initial(label: string): string {
+  return [...label][0]?.toUpperCase() ?? '?'
+}
+
+/**
+ * One trailing action as an icon-only button. `size="icon"` is EXPLICIT here, not inherited: the
+ * search row is chrome, not a control home, so no `CtlSlot` wraps it and nothing else would resolve
+ * the tier (`--ai-size-icon`, declared by `cssVariablesResolver` — spec §5).
+ */
+function SearchAction({ action }: { action: BarAction }): ReactNode {
+  if (action.kind === 'custom') return action.node
+  if (action.kind === 'menu') {
+    return <OverflowMenu actions={action.items} trigger="kebab" label={action.label} />
+  }
+  const shared = {
+    variant: 'subtle' as const,
+    size: 'icon',
+    className: classes.actionBtn,
+    'aria-label': action.label,
+    disabled: action.disabled === true,
+    ...(action.onClick !== undefined && { onClick: action.onClick }),
+  }
+  const body = action.icon ?? initial(action.label)
+  const Anchor = action.Anchor
+  if (Anchor !== undefined) {
+    return (
+      <ActionIcon component={Anchor} {...shared}>
+        {body}
+      </ActionIcon>
+    )
+  }
+  if (action.link !== undefined) {
+    return (
+      <ActionIcon component="a" href={action.link.to} {...shared}>
+        {body}
+      </ActionIcon>
+    )
+  }
+  return <ActionIcon {...shared}>{body}</ActionIcon>
+}
+
 export function SidebarSearch({
   onOpen,
   placeholder = 'Search…',
   shortcut,
+  actions,
   collapsed,
-}: SidebarSearchConfig & { collapsed?: boolean }) {
+}: SidebarSearchConfig & { actions?: SidebarSearchActions; collapsed?: boolean }) {
   // SSR-safe mac detection, matching the shell's other shortcut-hint logic.
   const isMac = typeof navigator !== 'undefined' && /Mac|iPhone|iPod|iPad/i.test(navigator.platform)
   const hint = shortcut ?? (isMac ? '⌘K' : 'Ctrl K')
@@ -63,7 +120,7 @@ export function SidebarSearch({
     )
   }
 
-  return (
+  const trigger = (
     <UnstyledButton
       type="button"
       className={classes.trigger}
@@ -77,4 +134,16 @@ export function SidebarSearch({
       <Kbd size="xs">{hint}</Kbd>
     </UnstyledButton>
   )
+
+  // No wrapper without actions — the trigger stays the row's only node, exactly as it shipped.
+  if (actions === undefined) return trigger
+
+  return (
+    <div className={classes.row}>
+      {trigger}
+      {actions.map((action) => (
+        <SearchAction key={action.key} action={action} />
+      ))}
+    </div>
+  )
 }