basalt-ui 1.27.0 → 1.28.0

package/src/section/section.tsx

@@ -1,6 +1,9 @@
 /**
  * Section — the tier-2 heading composer (docs/CONTROLS-SPEC.md §2.2, law C8): a page-level content
- * grouping under `WidgetHeader tier="section"`. Named exactly `Section` — not `PageSection` — so
+ * grouping under `WidgetHeader tier="section"` — or `tier="group"` when the section renders on the
+ * `PageAside` panel surface, resolved from `useFilterSurface()` and never a call-site prop (law C1:
+ * no fourth home, no new prop — the aside decides, not the caller). Named exactly `Section` — not
+ * `PageSection` — so
  * the existing `shadow-basalt-export` guard fires on a consumer's own hand-rolled `Section` /
  * `PageSection` / `SectionTitle` / `SectionHeading` copy with zero new rule code.
  *
@@ -9,8 +12,8 @@
  *
  * `actions` and `tabs` are two separate `CtlSlot`-wrapped fragments rendered in the header row
  * (C1/C5) via `WidgetHeader`'s single `actions` slot; `tabs` hides while the section is collapsed.
- * `Section` holds ≤3 actions (C6) — past that, a dev-only console warning fires (the AST guard
- * lands in wave 6).
+ * `Section` holds ≤3 actions (C6) — past that, a dev-only `useValidateProps` message fires once per
+ * title (the AST guard lands in wave 6).
  *
  * `collapsible` state persists via `createPersistedState('basalt:section:<persistKey>')` when
  * `persistKey` is given, else it is local `useState` — the header always stays drawn, only the body
@@ -43,77 +46,101 @@
  *   <UsageChart />
  * </Section>
  */
-import { Children, useId, useMemo, useState } from 'react'
+import { Children, useId } from 'react'
 import type { ReactNode } from 'react'
+import { cx } from '../common/props'
+import type { BasaltProps, SlotStylesProps } from '../common/props'
+import { BASALT_PREFIX } from '../common/errors'
+import { useValidateProps } from '../common/validate'
 import { CtlSlot } from '../theme'
-import { createPersistedState } from '../state'
+import { BarActionSlot, isBarActionList } from '../controls/actions'
+import type { SlotActions } from '../controls/actions'
+import { useFilterSurface } from '../controls/filter-context'
+import { QueryState } from '../dashboard/query-state'
+import type { QueryEmptyCopy, QueryStateLike } from '../dashboard/query-state'
+import { usePersistedOrLocal } from '../state/persisted-or-local'
 import { WidgetHeader } from '../widget-header'
 import type { WidgetHeaderProps } from '../widget-header'
 import classes from './section.module.css'
 
-export type SectionProps = Omit<WidgetHeaderProps, 'tier'> & {
-  /** Rendered in the header row, in its own `CtlSlot` — hidden while the section is collapsed. */
-  tabs?: ReactNode
-  /** Renders a chevron toggle in the header; the header stays drawn when closed, only `children`
-   * (and `tabs`) unmount. @default false */
-  collapsible?: boolean
-  /** Persists the fold state at `basalt:section:<persistKey>`. Omit for a local, unpersisted fold
-   * (`useState`). */
-  persistKey?: string
-  /** The fold state a section opens on, respected only while no persisted value exists — a section
-   * a reader has closed stays closed. `false` is what a long secondary block wants. @default true */
-  defaultOpen?: boolean
-  /** Rendered directly under the header and ALWAYS visible, collapsed or not: a collapsed section
-   * still states its headline figures, which is what makes collapsing it a real option. Keep it to
-   * one row — the body is what `children` is for. */
-  summary?: ReactNode
-  /** Turns the root into a scroll anchor (`id` + `scroll-margin-top` cleared for both sticky bars). */
-  id?: string
-  children: ReactNode
-}
-
-/** The house dev gate (`data/data-table.tsx`, `provider`, `charts/kinds/BandStrip` use the same
- * expression): `basaltViteConfig` defines `process.env.NODE_ENV`, so a production bundle
- * constant-folds this to `false` and drops the warning. Read per call, never hoisted. */
-function isDev(): boolean {
-  return process.env['NODE_ENV'] !== 'production'
-}
-
-/** ≤3 actions is C6 (docs/CONTROLS-SPEC.md §1) — the AST guard (`basalt/page-bar-budget`) lands in
- * wave 6; this is the dev-only stopgap so the budget is visible before the lint rule exists. */
-function warnPastActionBudget(title: string, actions: ReactNode): void {
-  if (!isDev()) return
-  const count = Children.count(actions)
-  if (count <= 3) return
-  console.warn(
-    `Section "${title}": ${count} actions exceeds the ≤3 budget (docs/CONTROLS-SPEC.md C6) — ` +
-      'move the rest behind a menu.',
-  )
-}
+/**
+ * The three boxes `Section` paints, and the whole styling seam it offers (`common/props.ts`):
+ * `root` is the outer stack, `header` is the `WidgetHeader` row, `body` is the collapsible content
+ * box. `summary` is deliberately absent — it is a one-row readout under the header, not a layout
+ * box a consumer positions.
+ */
+export type SectionSlot = 'root' | 'header' | 'body'
 
-const UNPERSISTED_KEY = '__local__'
+// `classNames` is omitted alongside `tier`: `WidgetHeader` publishes its OWN slot union now, and
+// intersecting the two would let a caller write `classNames={{ metric: … }}` on a `Section` and get
+// silence. Section's three slots are its whole styling contract; the header's own slots are reached
+// on a `WidgetHeader`.
+export type SectionProps = Omit<WidgetHeaderProps, 'tier' | 'classNames' | 'actions'> &
+  BasaltProps &
+  SlotStylesProps<SectionSlot> & {
+    /**
+     * Header actions, in either form (law C15): a typed `BarAction[]`, which basalt projects through
+     * the SAME row `PageBar` and `ActionGroup` use — ≤3 inline, the rest folded into `More`, one
+     * kebab below `sm` — or an opaque `ReactNode` a caller drew itself, rendered verbatim. The ≤3
+     * budget (C6) is checked against whichever form is given.
+     */
+    actions?: SlotActions
+    /**
+     * The section's async result. Given one, the BODY renders through `QueryState` at the section
+     * tier — pending / error-with-retry / empty each REPLACE `children`, data renders them — while
+     * the header, the fold chevron and `summary` stay drawn throughout, so a section never blinks out
+     * of the page while it refetches.
+     *
+     * This is law C3's uniform container contract (`docs/CONTROLS-SPEC.md` §1): without it every
+     * caller re-derives the four-way switch `QueryState` exists to delete, and gets it wrong in the
+     * one direction that matters — "nothing here" printed over a 500.
+     */
+    query?: QueryStateLike<unknown>
+    /**
+     * Copy for `query`'s EMPTY branch, rendered through `EmptyState` like every other one. Omit to
+     * render nothing when the result is empty — `QueryState`'s own contract, unchanged. Ignored
+     * without `query`.
+     */
+    empty?: QueryEmptyCopy
+    /** Rendered in the header row, in its own `CtlSlot` — hidden while the section is collapsed. */
+    tabs?: ReactNode
+    /** Renders a chevron toggle in the header; the header stays drawn when closed, only `children`
+     * (and `tabs`) unmount. @default false */
+    collapsible?: boolean
+    /** Persists the fold state at `basalt:section:<persistKey>`. Omit for a local, unpersisted fold
+     * (`useState`). */
+    persistKey?: string
+    /** The fold state a section opens on, respected only while no persisted value exists — a section
+     * a reader has closed stays closed. `false` is what a long secondary block wants. @default true */
+    defaultOpen?: boolean
+    /** Rendered directly under the header and ALWAYS visible, collapsed or not: a collapsed section
+     * still states its headline figures, which is what makes collapsing it a real option. Keep it to
+     * one row — the body is what `children` is for. */
+    summary?: ReactNode
+    /** Turns the root into a scroll anchor (`id` + `scroll-margin-top` cleared for both sticky bars). */
+    id?: string
+    children: ReactNode
+  }
 
-/** Collapse state — `createPersistedState` when `persistKey` is given, else local `useState`.
- * Both hooks are always called (stable order across renders); only the unpersisted branch's setter
- * is ever invoked when `persistKey` is absent, so no unpersisted Section writes to storage. */
-function useSectionOpen(
-  persistKey: string | undefined,
-  defaultOpen: boolean,
-): readonly [boolean, (next: boolean) => void] {
-  const [localOpen, setLocalOpen] = useState(defaultOpen)
-  const usePersistedOpen = useMemo(
-    () =>
-      createPersistedState<boolean>({
-        key: `section:${persistKey ?? UNPERSISTED_KEY}`,
-        version: 1,
-        initial: defaultOpen,
-      }),
-    [persistKey, defaultOpen],
+/**
+ * ≤3 actions is C6 (docs/CONTROLS-SPEC.md §1) — the AST guard (`basalt/page-bar-budget`) lands in
+ * wave 6; this is the dev-only stopgap so the budget is visible before the lint rule exists.
+ *
+ * Returns the message rather than logging it, because it is a {@link useValidateProps} check now:
+ * it used to `console.warn` straight from the render body, which said it again on every keystroke
+ * that re-rendered the page. The title is IN the message on purpose — the dedup key is
+ * `${component} ${message}`, so two over-budget sections only both get heard because they name
+ * themselves.
+ */
+function actionBudgetMessage(title: string, actions: SlotActions): string | null {
+  // Both arms of the union are counted, and the typed one is counted EXACTLY: `Children.count` over
+  // a `BarAction[]` would report the array's length as one child.
+  const count = isBarActionList(actions) ? actions.length : Children.count(actions)
+  if (count <= 3) return null
+  return (
+    `${BASALT_PREFIX} Section "${title}": ${count} actions exceeds the ≤3 budget ` +
+    '(docs/CONTROLS-SPEC.md C6) — move the rest behind a menu.'
   )
-  const [persistedOpen, setPersistedOpen] = usePersistedOpen()
-
-  if (persistKey !== undefined) return [persistedOpen, setPersistedOpen] as const
-  return [localOpen, setLocalOpen] as const
 }
 
 function ChevronToggle({
@@ -151,16 +178,9 @@ function ChevronToggle({
 }
 
 export function Section({
-  title,
-  icon,
-  subtitle,
-  info,
-  value,
-  delta,
-  deltaPeriod,
-  sparkline,
-  count,
   actions,
+  query,
+  empty,
   tabs,
   collapsible = false,
   persistKey,
@@ -168,17 +188,66 @@ export function Section({
   summary,
   id,
   children,
+  className,
+  style,
+  classNames,
+  ...headerProps
 }: SectionProps) {
-  const [open, setOpen] = useSectionOpen(persistKey, defaultOpen)
+  const { title } = headerProps
+
+  // Two dev-only checks, one hook — both are misuses that RENDER fine, which is what puts them in
+  // `useValidateProps` rather than in `assertRequiredProps`.
+  //
+  //  1. A `persistKey` with nothing to fold writes a localStorage key nobody ever reads back — the
+  //     shape a consumer lands on after deleting `collapsible` and leaving the key behind.
+  //  2. More than three header actions (C6). This used to `console.warn` from the render body, so a
+  //     page that re-rendered on every keystroke reprinted it every keystroke.
+  useValidateProps(
+    'Section',
+    () => [
+      persistKey !== undefined && !collapsible
+        ? `${BASALT_PREFIX} Section "${title}": \`persistKey\` is set but \`collapsible\` is ` +
+          'false — there is no fold to persist. Add `collapsible`, or drop `persistKey`.'
+        : null,
+      actions === undefined ? null : actionBudgetMessage(title, actions),
+    ],
+    [persistKey, collapsible, title, actions],
+  )
+
+  const [open, setOpen] = usePersistedOrLocal({
+    scope: 'section',
+    persistKey,
+    initial: defaultOpen,
+  })
   const bodyId = useId()
+  // The aside decides, not the call site (law C1): a Section on the PageAside panel surface, or on
+  // its mobile sheet projection, renders the quiet `group` tier automatically — a Section never
+  // lives inside a pill FilterSet fold, so `'pill'` (the context default outside any provider) is
+  // the only surface that stays `section`.
+  const tier = useFilterSurface() === 'pill' ? 'section' : 'group'
 
-  if (actions !== undefined) warnPastActionBudget(title, actions)
+  // The anchor offset is Section's own, so the caller's `style` merges OVER it rather than
+  // replacing it — a consumer setting a margin must not silently drop the scroll offset.
+  //
+  // NO chrome height in this offset. An anchor scroll happens inside the SCROLLPORT, and since
+  // `AppShell.Main` became that box (`shell/app-main.module.css`) BOTH the app header and `PageBar`
+  // row 2's band are shell regions rendered outside it — counting either would land every `#anchor`
+  // that far below its own heading. What is left is breathing room, which is exactly what
+  // `--vx-space-sticky-header-clearance` means (tokens/palette.ts, `deriveSpacing`).
+  const anchorStyle =
+    id === undefined ? undefined : { scrollMarginTop: 'var(--vx-space-sticky-header-clearance)' }
+  const rootStyle =
+    anchorStyle === undefined && style === undefined ? undefined : { ...anchorStyle, ...style }
 
   const headerActions =
     tabs !== undefined || actions !== undefined || collapsible ? (
       <>
         {tabs !== undefined && open && <CtlSlot>{tabs}</CtlSlot>}
-        {actions !== undefined && <CtlSlot>{actions}</CtlSlot>}
+        {actions !== undefined && (
+          <CtlSlot>
+            <BarActionSlot actions={actions} />
+          </CtlSlot>
+        )}
         {collapsible && (
           <ChevronToggle open={open} onToggle={() => setOpen(!open)} controls={bodyId} />
         )}
@@ -187,32 +256,30 @@ export function Section({
 
   return (
     <div
-      className={classes.root}
+      className={cx(classes.root, classNames?.root, className)}
+      data-tier={tier}
       {...(id !== undefined && { id })}
-      {...(id !== undefined && {
-        style: {
-          scrollMarginTop:
-            'calc(var(--app-shell-header-height, 0px) + var(--basalt-page-bar-h, 0px))',
-        },
-      })}
+      {...(rootStyle !== undefined && { style: rootStyle })}
     >
       <WidgetHeader
-        tier="section"
-        title={title}
-        {...(icon !== undefined && { icon })}
-        {...(subtitle !== undefined && { subtitle })}
-        {...(info !== undefined && { info })}
-        {...(value !== undefined && { value })}
-        {...(delta !== undefined && { delta })}
-        {...(deltaPeriod !== undefined && { deltaPeriod })}
-        {...(sparkline !== undefined && { sparkline })}
-        {...(count !== undefined && { count })}
+        tier={tier}
+        {...headerProps}
+        {...(classNames?.header !== undefined && { className: classNames.header })}
         {...(headerActions !== undefined && { actions: headerActions })}
       />
       {summary !== undefined && <div className={classes.summary}>{summary}</div>}
       {open && (
-        <div id={bodyId} className={classes.body}>
-          {children}
+        <div id={bodyId} className={cx(classes.body, classNames?.body)}>
+          {query === undefined ? (
+            children
+          ) : (
+            // `tier="section"` is the compact one: a bare spinner rather than a 64px centred
+            // block, and the error alert without the page-level stack around it. A Section IS the
+            // region, so the state belongs inside its body, never around its header.
+            <QueryState query={query} tier="section" {...(empty !== undefined && { empty })}>
+              {children}
+            </QueryState>
+          )}
         </div>
       )}
     </div>

package/src/shell/account-types.ts

@@ -6,8 +6,11 @@
  */
 import type { ReactNode } from 'react'
 
-/** Badge tone for a role/plan chip. No dedicated tone union exists elsewhere in the shell/tokens
- * layers, so this is defined locally. */
+/**
+ * Badge tone for a role/plan chip. A different member set from `common`'s `Tone` (`common/props.ts`,
+ * audit A13) — `'neutral' | 'brand'` have no `Tone` equivalent — so this stays its own type rather
+ * than an alias; see `Tone` for the base three-tone vocabulary the rest of the framework shares.
+ */
 export type AccountBadgeTone = 'neutral' | 'brand' | 'success' | 'warn'
 
 /** The signed-in user's identity. `image` is nullable and currently unused by `SidebarAccount`

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

@@ -0,0 +1,109 @@
+/*
+ * The header's leading zone (docs/DESIGN-SPEC.md §5). Moved here from `app-sidebar.module.css`
+ * verbatim — the brand did not change, only where it is painted.
+ *
+ * NO border and no background: the zone is part of the header row, so the header's own
+ * `AppShell.Header` region seam is the only line under it. The sidebar column below now starts
+ * directly with `SidebarSearch`.
+ *
+ * The zone's WIDTH is `--app-shell-navbar-offset`, so it tracks the rail collapse with no React
+ * state and lands its trailing edge exactly on the sidebar|main seam. The negative
+ * `margin-inline-start` cancels `AppShell.Header`'s own `px` inset so the zone starts at the
+ * viewport edge and re-applies that inset as padding — which is what puts the brand lead on the
+ * same x as the sidebar rows below it.
+ */
+.zone {
+  flex: 0 0 var(--app-shell-navbar-offset, 0rem);
+  width: var(--app-shell-navbar-offset, 0rem);
+  min-width: 0;
+  display: flex;
+  align-items: center;
+  /* The full header row, not just the toggle's own 28px — so the zone's box is the band it looks
+   * like, and the rail's centred toggle centres against the whole row. */
+  align-self: stretch;
+  margin-inline-start: calc(-1 * var(--app-shell-padding, 0px));
+  padding-inline: var(--app-shell-padding, 0px);
+  overflow: hidden;
+  /* Mantine's own AppShell timing, so the zone and the navbar under it move as one box. */
+  transition-property: flex-basis, width;
+  transition-duration: var(--app-shell-transition-duration);
+  transition-timing-function: var(--app-shell-transition-timing-function);
+}
+
+/* Below `sm` there is no navbar at all (the bottom bar is the whole nav), so the zone would be a
+ * zero-width box holding a hidden toggle. The breadcrumb owns the phone header's lead. */
+@media (max-width: 47.99375em) {
+  .zone {
+    display: none;
+  }
+}
+
+.brand {
+  justify-content: space-between;
+  align-items: center;
+  flex: 1 1 auto;
+  min-width: 0;
+  height: 100%;
+}
+
+.brandLead {
+  min-width: 0;
+}
+
+/* Brand name — head font at stretch 88% (docs/DESIGN-SPEC.md §3); the 18px/550 land as `fz`/`fw`
+ * props (inline, deterministic against Mantine's own Text base rule). */
+.brandName {
+  font-family: var(--basalt-font-head);
+  font-stretch: 88%;
+}
+
+/* Workspace switcher (`brand.menu`) — the brand name plus a chevron, as a row-shaped trigger. The
+ * chevron is faint until hover so the brand still reads as the brand, not as a control. */
+.brandButton {
+  display: flex;
+  align-items: center;
+  gap: var(--vx-space-sidebar-section-label-gap);
+  min-width: 0;
+  padding: 0;
+  color: var(--vx-faint);
+  cursor: pointer;
+}
+
+.brandButton:hover {
+  color: var(--vx-ink);
+}
+
+/*
+ * Icon-only ghost button in shell chrome (the collapse toggle) — docs/DESIGN-SPEC.md §5:
+ * transparent, faint icon, hover ink-6% + ink, radius 6. `!important` because it competes with
+ * Mantine's own compiled ActionIcon variant CSS. This is the one copy — `sidebar-search.module.css`
+ * mirrors it rather than keeping its own duplicate.
+ */
+.ghostIcon {
+  color: var(--vx-faint) !important;
+  border-radius: var(--vx-radius-ctrl) !important;
+}
+
+.ghostIcon:hover {
+  background-color: color-mix(in srgb, var(--vx-ink) 6%, transparent) !important;
+  color: var(--vx-ink) !important;
+}
+
+/*
+ * The rail form, mirroring exactly what the sidebar's own brand row did when collapsed: the lead
+ * (logo + name) hides and the toggle centres. The zone drops its inset so the toggle's centre lands
+ * on the rail's icon column rather than 13px right of it.
+ */
+@media (min-width: 48em) {
+  .zone[data-collapsed] {
+    padding-inline: 0;
+  }
+
+  .zone[data-collapsed] .brand {
+    justify-content: center;
+  }
+
+  .zone[data-collapsed] .brandLead {
+    display: none;
+  }
+}

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

@@ -0,0 +1,14 @@
+/**
+ * Typed CSS-module declaration (the S4 CSS-modules path). Named string props — not an index
+ * signature — so dot access stays verbatim under the package's strict flags. HAND-MAINTAINED:
+ * there is no generator, so a new class in `app-brand.module.css` must be added here too.
+ */
+declare const classes: {
+  readonly zone: string
+  readonly brand: string
+  readonly brandLead: string
+  readonly brandName: string
+  readonly brandButton: string
+  readonly ghostIcon: string
+}
+export default classes

package/src/shell/app-brand.tsx

@@ -0,0 +1,140 @@
+/**
+ * `AppBrand` — the brand identity plus the sidebar-collapse toggle, rendered as the HEADER's
+ * leading zone.
+ *
+ * It used to be the sidebar's own first row, an `appShellHeaderHeight` band under `layout="alt"`
+ * where the header was inset beside the navbar and the two bands sat side by side. With the header
+ * spanning the full viewport width, that band became a SECOND 48px row painted under the header
+ * seam — two horizontal rules where the design has one. So the markup moved up into the header,
+ * unchanged: same `BrandConfig`, same `brand.menu` workspace switcher, same collapse toggle, same
+ * rail behaviour (the lead hides, the toggle centres).
+ *
+ * It is internal — `BasaltShell` is the only mount. `AppSidebar` still takes `brand` because
+ * `brand.version` labels its settings footer; it simply no longer paints the row.
+ */
+import { ActionIcon, Group, Menu, Text, UnstyledButton } from '@mantine/core'
+import { cx } from '../common/props'
+import type { BasaltProps } from '../common/props'
+import type { AccountMenuItem } from './account-types'
+import type { BrandConfig } from './index'
+import { IconChevron } from './sidebar-blocks'
+import { VX } from '../tokens'
+import { useBasaltSpacing } from '../theme'
+import classes from './app-brand.module.css'
+
+/** Inline collapse/expand chevrons — keeps the shell icon-dependency-free. */
+function IconCollapse({ collapsed }: { collapsed: boolean }) {
+  return (
+    <svg
+      width={18}
+      height={18}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={2}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden
+    >
+      <path d="M4 4h16v16H4z" />
+      <path d="M9 4v16" />
+      {collapsed ? <path d="M14 9l3 3l-3 3" /> : <path d="M16 9l-3 3l3 3" />}
+    </svg>
+  )
+}
+
+/**
+ * The brand name, and — when `brand.menu` is supplied — the workspace switcher it becomes.
+ *
+ * The entries are `AccountMenuItem`s: the shell already had exactly this row shape (label, icon,
+ * onClick, danger) for the account menu, and a second vocabulary for the same dropdown would be
+ * two things to keep in step for no gain. The chevron is inline text, not an icon dependency.
+ */
+function BrandName({
+  brand,
+  menuWidth,
+}: {
+  brand: BrandConfig & { menu?: AccountMenuItem[] }
+  menuWidth: number
+}) {
+  const label = (
+    <Text className={classes.brandName} fz={VX.text.xl} fw={550}>
+      {brand.name}
+    </Text>
+  )
+  const menu = brand.menu
+  if (menu === undefined || menu.length === 0) return label
+
+  return (
+    <Menu position="bottom-start" withArrow width={menuWidth} zIndex={500}>
+      <Menu.Target>
+        <UnstyledButton className={classes.brandButton} aria-label={`${brand.name} workspace`}>
+          {label}
+          {/* `open` is the DOWN glyph — a switcher's affordance points at its dropdown, and this is
+              the same chevron every fold in the sidebar uses rather than a second one. */}
+          <IconChevron open />
+        </UnstyledButton>
+      </Menu.Target>
+      <Menu.Dropdown>
+        {menu.map((entry) => (
+          <Menu.Item
+            key={entry.key}
+            leftSection={entry.icon}
+            {...(entry.danger === true && { color: 'red' })}
+            onClick={entry.onClick}
+          >
+            {entry.label}
+          </Menu.Item>
+        ))}
+      </Menu.Dropdown>
+    </Menu>
+  )
+}
+
+export type AppBrandProps = BasaltProps & {
+  brand: BrandConfig & { menu?: AccountMenuItem[] }
+  /** Desktop rail state — the zone narrows with the navbar and shows the toggle alone. */
+  collapsed: boolean
+  onToggleCollapse: () => void
+}
+
+export function AppBrand({ brand, collapsed, onToggleCollapse, className, style }: AppBrandProps) {
+  // Density-tracking Menu dropdown width, read at the ACTIVE resolved level — same reason
+  // `AppSidebar` reads it rather than the frozen level-0 constant (`tokens/palette.ts`).
+  const { step } = useBasaltSpacing()
+  return (
+    <Group
+      className={cx(classes.brand, className)}
+      gap="sm"
+      wrap="nowrap"
+      {...(style !== undefined && { style })}
+    >
+      <Group className={classes.brandLead} gap="sm" wrap="nowrap">
+        {brand.logoSrc && (
+          <img
+            src={brand.logoSrc}
+            alt={brand.logoAlt ?? brand.name}
+            width={26}
+            height={26}
+            style={{ display: 'block' }}
+          />
+        )}
+        <BrandName brand={brand} menuWidth={step.sidebarAccountMenuWidth} />
+      </Group>
+      <ActionIcon
+        variant="subtle"
+        // A numeric size, not the named `"md"` — same opt-out as `connectivity-indicator.tsx`'s
+        // toolbar icon (see that comment): this is a plain collapse-toggle icon, not a control meant
+        // to match a `size="md"` Input/Button, so it must not pick up the theme's `ActionIcon.extend`
+        // control-height override. Reproduces Mantine's own static `--ai-size-md` (28px).
+        size={28}
+        visibleFrom="sm"
+        className={classes.ghostIcon}
+        onClick={onToggleCollapse}
+        aria-label={collapsed ? 'Expand sidebar' : 'Collapse sidebar'}
+      >
+        <IconCollapse collapsed={collapsed} />
+      </ActionIcon>
+    </Group>
+  )
+}

package/src/shell/app-breadcrumbs.tsx

@@ -14,6 +14,7 @@ import { Anchor, Group, Text } from '@mantine/core'
 import type { CSSProperties } from 'react'
 import type { NavAnchor } from '../nav/types'
 import { VX } from '../tokens'
+import type { BasaltProps } from '../common/props'
 import classes from './app-header.module.css'
 
 /** Parent/section crumbs — faint. */
@@ -31,13 +32,7 @@ const currentStyle: CSSProperties = {
   color: 'var(--vx-ink)',
 }
 
-export function AppBreadcrumbs({
-  section,
-  parent,
-  parentAnchor,
-  parentHref,
-  page,
-}: {
+export type AppBreadcrumbsProps = BasaltProps & {
   section?: string
   /** Parent item label — shown when the active page is a nested child (e.g. "Dashboard"). */
   parent?: string | undefined
@@ -49,10 +44,25 @@ export function AppBreadcrumbs({
   /** Parent item href — the no-router fallback; ignored when `parentAnchor` is present. */
   parentHref?: string | undefined
   page?: string
-}) {
+}
+
+export function AppBreadcrumbs({
+  section,
+  parent,
+  parentAnchor,
+  parentHref,
+  page,
+  className,
+  style,
+}: AppBreadcrumbsProps) {
   if (!page) return null
   return (
-    <Group gap={6} wrap="nowrap" style={{ minWidth: 0 }}>
+    <Group
+      gap={6}
+      wrap="nowrap"
+      {...(className !== undefined && { className })}
+      style={{ minWidth: 0, ...style }}
+    >
       {/*
         The ANCESTOR crumbs, in one box so CSS can drop them below `sm` — law C9's swap, owned by the
         component, no JS media query and no first-paint flash. On a phone the header row is the