basalt-ui 1.25.0 → 1.26.0

package/src/section/section.tsx

@@ -0,0 +1,220 @@
+/**
+ * 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
+ * the existing `shadow-basalt-export` guard fires on a consumer's own hand-rolled `Section` /
+ * `PageSection` / `SectionTitle` / `SectionHeading` copy with zero new rule code.
+ *
+ * No `variant`, no border/background of its own — one shaded container level per page belongs to
+ * the cards inside a Section (`ChartCard`/`StatCard`), not to the Section itself.
+ *
+ * `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).
+ *
+ * `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
+ * unmounts. `defaultOpen` picks the state a first visit lands on; a persisted value outranks it.
+ *
+ * `summary` renders under the header and survives a collapse. That is the whole reason it is a
+ * separate slot rather than the first child: a section a reader folded away should still state its
+ * headline figures, or folding it costs them the numbers they were watching.
+ *
+ * `id` turns the root into a scroll anchor, offset by both the shell header height and the
+ * `PageBar`'s measured height (`--basalt-page-bar-h`, wave 4) so an anchor-jumped heading isn't
+ * hidden under either sticky bar.
+ *
+ * @example
+ * import { Section, StatCard } from 'basalt-ui'
+ *
+ * <Section title="Revenue" icon={<IconChartBar size={16} />} count={rows.length}>
+ *   <StatCard title="MRR" value="$48,204" delta={3.1} />
+ * </Section>
+ *
+ * @example
+ * // Collapsible, with tabs and a persisted fold state.
+ * <Section
+ *   id="usage"
+ *   title="Usage"
+ *   collapsible
+ *   persistKey="usage"
+ *   tabs={<ViewTabs field={viewField} />}
+ * >
+ *   <UsageChart />
+ * </Section>
+ */
+import { Children, useId, useMemo, useState } from 'react'
+import type { ReactNode } from 'react'
+import { CtlSlot } from '../theme'
+import { createPersistedState } from '../state'
+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.',
+  )
+}
+
+const UNPERSISTED_KEY = '__local__'
+
+/** 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],
+  )
+  const [persistedOpen, setPersistedOpen] = usePersistedOpen()
+
+  if (persistKey !== undefined) return [persistedOpen, setPersistedOpen] as const
+  return [localOpen, setLocalOpen] as const
+}
+
+function ChevronToggle({
+  open,
+  onToggle,
+  controls,
+}: {
+  open: boolean
+  onToggle: () => void
+  controls: string
+}) {
+  return (
+    <button
+      type="button"
+      className={classes.chevron}
+      data-open={open}
+      aria-expanded={open}
+      aria-controls={controls}
+      aria-label={open ? 'Collapse section' : 'Expand section'}
+      onClick={onToggle}
+    >
+      <svg
+        width={12}
+        height={12}
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth={2.5}
+        aria-hidden="true"
+      >
+        <path d="M6 9l6 6 6-6" strokeLinecap="round" strokeLinejoin="round" />
+      </svg>
+    </button>
+  )
+}
+
+export function Section({
+  title,
+  icon,
+  subtitle,
+  info,
+  value,
+  delta,
+  deltaPeriod,
+  sparkline,
+  count,
+  actions,
+  tabs,
+  collapsible = false,
+  persistKey,
+  defaultOpen = true,
+  summary,
+  id,
+  children,
+}: SectionProps) {
+  const [open, setOpen] = useSectionOpen(persistKey, defaultOpen)
+  const bodyId = useId()
+
+  if (actions !== undefined) warnPastActionBudget(title, actions)
+
+  const headerActions =
+    tabs !== undefined || actions !== undefined || collapsible ? (
+      <>
+        {tabs !== undefined && open && <CtlSlot>{tabs}</CtlSlot>}
+        {actions !== undefined && <CtlSlot>{actions}</CtlSlot>}
+        {collapsible && (
+          <ChevronToggle open={open} onToggle={() => setOpen(!open)} controls={bodyId} />
+        )}
+      </>
+    ) : undefined
+
+  return (
+    <div
+      className={classes.root}
+      {...(id !== undefined && { id })}
+      {...(id !== undefined && {
+        style: {
+          scrollMarginTop:
+            'calc(var(--app-shell-header-height, 0px) + var(--basalt-page-bar-h, 0px))',
+        },
+      })}
+    >
+      <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 })}
+        {...(headerActions !== undefined && { actions: headerActions })}
+      />
+      {summary !== undefined && <div className={classes.summary}>{summary}</div>}
+      {open && (
+        <div id={bodyId} className={classes.body}>
+          {children}
+        </div>
+      )}
+    </div>
+  )
+}

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 classes from './app-header.module.css'
 
 /** Parent/section crumbs — faint. */
 const crumbStyle: CSSProperties = { fontSize: VX.text.md, color: 'var(--vx-faint)' }
@@ -52,37 +53,49 @@ export function AppBreadcrumbs({
   if (!page) return null
   return (
     <Group gap={6} wrap="nowrap" style={{ minWidth: 0 }}>
-      {section && (
-        <>
-          <Text style={crumbStyle} truncate>
-            {section}
-          </Text>
-          <Text style={separatorStyle}>/</Text>
-        </>
-      )}
-      {parent && parentAnchor && (
-        <>
-          <Anchor style={crumbStyle} underline="never" component={parentAnchor} truncate>
-            {parent}
-          </Anchor>
-          <Text style={separatorStyle}>/</Text>
-        </>
-      )}
-      {parent && !parentAnchor && parentHref && (
-        <>
-          <Anchor style={crumbStyle} underline="never" href={parentHref} truncate>
-            {parent}
-          </Anchor>
-          <Text style={separatorStyle}>/</Text>
-        </>
-      )}
-      {parent && !parentAnchor && !parentHref && (
-        <>
-          <Text style={crumbStyle} truncate>
-            {parent}
-          </Text>
-          <Text style={separatorStyle}>/</Text>
-        </>
+      {/*
+        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
+        scarcest space in the app and the breadcrumb is its one elastic side, so `Overview / Dashboard`
+        truncated to `O… / D…` — three crumbs' worth of separators and ellipses saying nothing. The
+        PAGE is the crumb that names where you are; the ancestors are navigation context, and the
+        sidebar (a tap away on the bottom bar) is where a phone reader looks for that.
+      */}
+      {(section !== undefined || parent !== undefined) && (
+        <Group gap={6} wrap="nowrap" className={classes.crumbAncestors} style={{ minWidth: 0 }}>
+          {section && (
+            <>
+              <Text style={crumbStyle} truncate>
+                {section}
+              </Text>
+              <Text style={separatorStyle}>/</Text>
+            </>
+          )}
+          {parent && parentAnchor && (
+            <>
+              <Anchor style={crumbStyle} underline="never" component={parentAnchor} truncate>
+                {parent}
+              </Anchor>
+              <Text style={separatorStyle}>/</Text>
+            </>
+          )}
+          {parent && !parentAnchor && parentHref && (
+            <>
+              <Anchor style={crumbStyle} underline="never" href={parentHref} truncate>
+                {parent}
+              </Anchor>
+              <Text style={separatorStyle}>/</Text>
+            </>
+          )}
+          {parent && !parentAnchor && !parentHref && (
+            <>
+              <Text style={crumbStyle} truncate>
+                {parent}
+              </Text>
+              <Text style={separatorStyle}>/</Text>
+            </>
+          )}
+        </Group>
       )}
       <Text style={currentStyle} truncate>
         {page}

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

@@ -1,7 +1,10 @@
-/* App-shell top bar layout. Desktop: a single 56px row —
- * [burger? · breadcrumb] ········ [page actions] | [global actions].
- * Mobile (< sm): wraps to two rows — lead + global on row 1, the page action row
- * (horizontally scrollable) on row 2. Header height is responsive to match. */
+/* App-shell top bar layout. ONE 48px row on every viewport —
+ * [breadcrumb] ········ [page bar row 1] | [global actions].
+ *
+ * The pre-1.26.0 mobile layout wrapped to a second, always-reserved row for the page actions and
+ * scrolled it sideways. Both are gone (law C7 and law C14): the header height is now the
+ * `appShellHeaderHeight` token at every width, an empty page bar reserves nothing, and overflow
+ * folds into `ActionGroup`'s kebab instead of scrolling out of view. */
 
 /*
  * Transparent header (docs/DESIGN-SPEC.md §5): NO bottom rule at all. The header and the page body
@@ -16,58 +19,95 @@
   height: 100%;
 }
 
+/*
+ * **Exactly ONE side of the header row is elastic, and it is the side whose content can ellipsize.**
+ * That is the whole rule, and both collisions this header has produced were the same violation of
+ * it from opposite directions.
+ *
+ * First the breadcrumb was `flex-shrink: 0`, so it won the whole width and the primary action
+ * rendered UNDERNEATH it. Then BOTH sides were made shrinkable (`.lead` at `0 1 auto`, `.pageBar` at
+ * `1 1 auto` with `min-width: 0` pushed onto its children) — and at 390px the controls, which cannot
+ * clip, shrank below their content and spilled: a flex container with `justify-content: flex-end`
+ * overflows towards its START, so the sync button painted 30px INTO the page title. Measured in
+ * Chrome: the title spanned 119.7–197.1 and the sync button 158.3–188.3.
+ *
+ * So the lead is now the elastic side (`flex: 1 1 auto`, `min-width: 0`, each crumb truncating via
+ * its own `truncate` prop) and the control side is rigid. A row of buttons that genuinely does not
+ * fit is not a shrinking problem — it is the OVERFLOW FOLD's problem, and basalt already owns that
+ * (law C7: below `sm` row 1 is the primary plus ONE kebab).
+ */
 .lead {
   display: flex;
   align-items: center;
   gap: var(--mantine-spacing-sm);
-  flex-shrink: 0;
+  flex: 1 1 auto;
   min-width: 0;
 }
 
-.pageActions {
-  flex: 1 1 auto;
+/* No `overflow: hidden` here or on `.lead` above: Mantine's focus ring is `outline: 2px solid;
+ * outline-offset: 2px` — OUTSIDE the anchor box — and a wrapper clipping this tightly to the
+ * breadcrumb anchors clipped the ring on every edge, leaving the primary in-shell nav link with no
+ * visible focus indicator. Truncation is already owned by each crumb's own `truncate` prop
+ * (`app-breadcrumbs.tsx`, Mantine's `[data-truncate]` rule sets its own `overflow: hidden;
+ * text-overflow: ellipsis; white-space: nowrap` on the element that actually holds the text) — this
+ * wrapper only needs to let its children shrink. */
+.lead * {
   min-width: 0;
-  display: flex;
-  align-items: center;
-  justify-content: flex-end;
-  gap: var(--mantine-spacing-xs);
-  overflow-x: auto;
-  scrollbar-width: thin;
 }
 
-/* Keep the whole control row on one horizontally-scrollable line. Mantine Group
- * defaults to flex-wrap:wrap, which otherwise stacks the nested control groups and
- * clips them against the slim bar's fixed height. */
-.pageActions :global(.mantine-Group-root) {
+/*
+ * The `PageBar` row-1 portal target — the RIGID side of the row (see `.lead` above for the rule and
+ * for the two collisions that established it). Never a scroll container — see the header note above.
+ *
+ * `flex: 0 0 auto` and no `min-width: 0` anywhere below it, deliberately: a button cannot ellipsize,
+ * so letting this side shrink does not make it narrower, it makes it OVERFLOW — leftwards, into the
+ * breadcrumb, because of the `justify-content: flex-end` two lines down. The previous version pushed
+ * `min-width: 0` onto every child for exactly the reason that comment gave (a `wrap="nowrap"` group's
+ * automatic minimum size is its min-content width and flex will not go below it) — the reasoning was
+ * right and the conclusion was backwards: that floor is the row's protection, not its bug.
+ */
+.pageBar {
+  flex: 0 0 auto;
+  display: flex;
   flex-wrap: nowrap;
+  align-items: center;
+  justify-content: flex-end;
+  gap: var(--vx-space-control-gap);
 }
 
+/*
+ * The shell globals sit at the SAME 30px tier as everything else in the row, and they get there the
+ * same way a home's slot does — `HeaderGlobalActions` wraps this region in a `CtlSlot`, so a
+ * consumer's bare `<ActionIcon>` in `globalActions` defaults to `size="ctl"` with no prop at the call
+ * site (law C5). They rendered at Mantine's `md` 28px before, which is 2px under the page group
+ * beside them: close enough to look like a mistake rather than a tier.
+ *
+ * The gap to the page group is `.bar`'s own `sm`, so the globals read as a separate cluster; between
+ * themselves they use the control gap, like every other adjacent-control pair.
+ */
 .global {
   display: flex;
+  flex-wrap: nowrap;
   align-items: center;
-  gap: var(--mantine-spacing-xs);
+  gap: var(--vx-space-control-gap);
   flex-shrink: 0;
 }
 
-@media (max-width: 47.99375em) {
-  .bar {
-    flex-wrap: wrap;
-    align-content: center;
-  }
-
-  .lead {
-    order: 1;
-    flex: 1 1 auto;
-  }
-
-  .global {
-    order: 2;
-  }
+.global :global(.mantine-ActionIcon-root) > svg {
+  width: 1rem;
+  height: 1rem;
+}
 
-  .pageActions {
-    order: 3;
-    flex-basis: 100%;
-    height: var(--vx-space-app-header-mobile-actions-height);
-    justify-content: flex-start;
+/*
+ * The breadcrumb's ANCESTOR crumbs — hidden below `sm`. See `app-breadcrumbs.tsx` for why: at 390px
+ * the row's elastic side truncated `Overview / Dashboard` to `O… / D…`, which is two ellipses and a
+ * separator in place of the one word that says where the reader is.
+ *
+ * `47.99375em` is the `sm` breakpoint in the exact literal form every other basalt CSS module uses —
+ * a media query cannot resolve a custom property.
+ */
+@media (max-width: 47.99375em) {
+  .crumbAncestors {
+    display: none;
   }
 }

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

@@ -5,7 +5,8 @@
 declare const classes: {
   readonly bar: string
   readonly lead: string
-  readonly pageActions: string
+  readonly pageBar: string
   readonly global: string
+  readonly crumbAncestors: string
 }
 export default classes

package/src/shell/app-mobile-nav.module.css

@@ -252,6 +252,14 @@
   background-color: color-mix(in srgb, var(--vx-ink) 10%, transparent);
 }
 
+/* Trailing meta on a block-item row (a timestamp, an owner) — the mobile twin of the sidebar's
+ * `.blockRowMeta`, so the same `SidebarBlockItem.meta` reads the same on both surfaces. */
+.rowMeta {
+  flex: none;
+  font-size: var(--vx-text-micro);
+  color: var(--vx-faint);
+}
+
 /*
  * Active = neutral surface fill + plain text color. Never the identity blue (DESIGN.md). --nl-color
  * forces NavLink's active text/icon color (otherwise the accent) to the plain text color. The

package/src/shell/app-mobile-nav.module.css.d.ts

@@ -19,5 +19,6 @@ declare const classes: {
   readonly sheetHeader: string
   readonly row: string
   readonly rowNested: string
+  readonly rowMeta: string
 }
 export default classes