basalt-ui 1.27.0 → 1.28.0

package/src/charts/utils/ticks.ts

@@ -1,12 +1,101 @@
 import { VX } from '../../tokens'
+import type { ChartTier } from '../primitives/chart-frame-layout'
+import { maxTextWidth } from './measure-text'
 
-/** Pick evenly-spaced tick values that fit the available width */
-export function smartTicks(dates: string[], xMax: number): string[] {
+/** The gap one x tick label wants from its neighbour, on top of its measured width. */
+const X_TICK_LABEL_GAP = 8
+
+/**
+ * The horizontal room one x tick label needs: the widest string in `labels`, plus breathing space
+ * to its neighbour. Feeds `smartTicks`, which otherwise thinned the axis by a constant that knew
+ * nothing about what was actually painted (`docs/CHARTS-SPEC.md` §1). Shared by `CartesianChart`,
+ * `useBandPlot` and `DualPanel` — the three call sites that used to reimplement this formula.
+ *
+ * `fontPx` defaults to `VX.axisFont`; a phone-tier chart passes its own smaller tick font
+ * (`chartTierMetrics().axisFont`) so the spacing is derived from the size actually painted.
+ */
+export function xLabelPxFor(labels: string[], fontPx: number = VX.axisFont): number {
+  return maxTextWidth(labels, fontPx) + X_TICK_LABEL_GAP
+}
+
+/**
+ * Pick evenly-spaced tick values that fit the available width.
+ *
+ * `labelPx` is the width one formatted label actually needs (measured, plus the gap it wants from
+ * its neighbour) and overrides the `VX.minPxPerTick` floor whenever it is wider. Without it the
+ * spacing came from that constant alone regardless of what was painted, so a `formatX` returning
+ * `Mar 08 14:00` overlapped at every width — the one side of the chart that did not follow §1's
+ * "measure what you paint" law. Omit it and nothing moves.
+ *
+ * The final key is still appended when the step misses the last index — a thinned axis would
+ * otherwise paint no label at the right edge at all — but it no longer prints ON TOP of its
+ * neighbour. An appended tick lands a PARTIAL step from the last one on the grid, so at any tick
+ * count wide enough labels overlap there; measured at `/charts-stress` block (f1), `Mar 13 14:00`
+ * and `Mar 14 14:00` printed over each other at 1440px. When that gap is narrower than one label,
+ * the grid tick before it is dropped instead. Index 0 is never dropped: the left edge is the one
+ * label a reader orients from.
+ */
+export function smartTicks(dates: string[], xMax: number, labelPx?: number): string[] {
   if (dates.length === 0) return []
-  const maxTicks = Math.max(2, Math.floor(xMax / VX.minPxPerTick))
+  const perTick = Math.max(VX.minPxPerTick, labelPx ?? 0)
+  const maxTicks = Math.max(2, Math.floor(xMax / perTick))
   if (dates.length <= maxTicks) return dates
   const step = Math.ceil(dates.length / maxTicks)
-  return dates.filter((_, i) => i % step === 0 || i === dates.length - 1)
+  const last = dates.length - 1
+
+  const keep = new Set<number>()
+  for (let i = 0; i <= last; i += step) keep.add(i)
+
+  const lastOnGrid = Math.floor(last / step) * step
+  if (lastOnGrid !== last) {
+    // `scalePoint({ padding: 0.5 })` spreads N points over `xMax`, so one index is `xMax / N` wide.
+    const pxPerIndex = dates.length > 0 ? xMax / dates.length : 0
+    const gapPx = (last - lastOnGrid) * pxPerIndex
+    if (lastOnGrid > 0 && gapPx > 0 && gapPx < perTick) keep.delete(lastOnGrid)
+    keep.add(last)
+  }
+
+  return dates.filter((_, i) => keep.has(i))
+}
+
+/**
+ * Which of a BAND axis's category labels may be painted so that no two neighbours overlap — the
+ * same measured law {@link smartTicks} applies to a point axis, for a chart that lays its labels
+ * out itself instead of through the `Axis*` primitives.
+ *
+ * `Heatmap` was the one kind rendering labels as plain `<text>`, and therefore the one kind exempt
+ * from §1's measured-margin law: it printed all 12 columns at 390px, ten of them overlapping. Here
+ * `bandPx` is the pitch between two neighbouring labels (a cell's width for columns, its height for
+ * rows) and `labelPx` the room one label needs ({@link xLabelPxFor} for a horizontal run, the line
+ * box for a vertical one); a label is kept every `ceil(labelPx / bandPx)` bands, so the gap between
+ * two painted labels is never narrower than one label.
+ *
+ * The first and last band always keep theirs — they are the two a reader orients from — and when
+ * the last one lands a partial step from the grid, the grid label before it is dropped rather than
+ * printed underneath, exactly as `smartTicks` does with its appended final tick.
+ */
+export function thinLabels(
+  labels: readonly string[],
+  bandPx: number,
+  labelPx: number,
+): Set<number> {
+  const keep = new Set<number>()
+  const last = labels.length - 1
+  if (last < 0) return keep
+  keep.add(0)
+  if (last === 0) return keep
+  if (bandPx <= 0 || labelPx <= 0) {
+    keep.add(last)
+    return keep
+  }
+  const step = Math.max(1, Math.ceil(labelPx / bandPx))
+  for (let i = 0; i <= last; i += step) keep.add(i)
+  const lastOnGrid = Math.floor(last / step) * step
+  if (lastOnGrid !== last && lastOnGrid > 0 && (last - lastOnGrid) * bandPx < labelPx) {
+    keep.delete(lastOnGrid)
+  }
+  keep.add(last)
+  return keep
 }
 
 /** Variant of smartTicks that targets an exact tick count rather than deriving from width. */
@@ -16,3 +105,59 @@ export function smartTicksEvery(dates: string[], count: number): string[] {
   const step = Math.ceil(dates.length / count)
   return dates.filter((_, i) => i % step === 0 || i === dates.length - 1)
 }
+
+/**
+ * The fewest x ticks an axis may thin down to before rotating is the cheaper trade. Two ticks
+ * (`smartTicks`' own floor) is a labelled left edge and a labelled right edge and nothing to read
+ * between them — at that point the axis has stopped being an axis.
+ */
+const MIN_HORIZONTAL_TICKS = 3
+
+/** Horizontal projection of a 45°-rotated label — `cos 45°`. A tilted label still competes for
+ * horizontal room, just for `0.71×` of it. */
+const COS_45 = Math.SQRT1_2
+
+/**
+ * The phone tier's default x-label rotation: 45° when the labels are so wide that fewer than
+ * {@link MIN_HORIZONTAL_TICKS} of them fit side by side, else none.
+ *
+ * `xLabelRotate` already existed as the answer to a `formatX` too wide to repeat horizontally
+ * (`docs/CHARTS-SPEC.md` §1) — it just had to be reached for by hand, per chart, by someone who
+ * had already seen it collide on a phone. This makes it the DEFAULT at phone width and only there:
+ * rotating trades horizontal crowding for bottom-gutter depth, which is the cheap axis on a narrow
+ * viewport and the expensive one on a wide screen that had room all along. Opt out with an
+ * explicit `xLabelRotate: 0`.
+ *
+ * Deliberately measured against the same `labelPx` `smartTicks` thins by, so the decision and the
+ * thinning cannot disagree about how wide a label is.
+ *
+ * **Wanting to rotate is not the same as rotating fitting.** A rotated label reaches into the LEFT
+ * gutter (`rotatedLabelExtents`), so rotating BUYS bottom-gutter depth and SPENDS plot width — and
+ * at a narrow enough box it spends more than it buys. `/charts-stress` block (f1) is the case:
+ * three clean horizontal labels at 390, and at 320 an auto-rotation that reached off the left edge
+ * and bought not one extra label for it. So the trade is CHECKED, not assumed. Pass `rotatedXMax`
+ * (the width left once `autoMargin({ rotate: 45 })` has taken its deeper left gutter) and the
+ * rotation is taken only when the rotated axis paints MORE labels than the flat one at its
+ * projected pitch (`labelPx · cos 45°`), and at least two of them. Otherwise the axis stays flat
+ * and `smartTicks` thins further — two readable horizontal labels beat two tilted ones in a
+ * narrower plot. Omit `rotatedXMax` and the check is skipped.
+ */
+export function autoXLabelRotate(input: {
+  tier: ChartTier
+  /** Plot width available to the x axis, from the UNROTATED margin. */
+  xMax: number
+  /** What one x label needs horizontally ({@link xLabelPxFor}). */
+  labelPx: number
+  /** Plot width that would REMAIN once the rotated margin takes its deeper left gutter
+   * (`autoMargin({ rotate: 45 })`). Omit to skip the fit check. */
+  rotatedXMax?: number
+}): 0 | 45 {
+  const { tier, xMax, labelPx, rotatedXMax } = input
+  if (tier !== 'phone') return 0
+  if (labelPx <= 0 || xMax <= 0) return 0
+  const flatLabels = Math.floor(xMax / labelPx)
+  if (flatLabels >= MIN_HORIZONTAL_TICKS) return 0
+  if (rotatedXMax === undefined) return 45
+  const rotatedLabels = Math.floor(rotatedXMax / (labelPx * COS_45))
+  return rotatedLabels >= 2 && rotatedLabels > flatLabels ? 45 : 0
+}

package/src/cli/index.ts

@@ -3186,7 +3186,7 @@ const AGENT_LINE_BUDGETS: Readonly<Record<string, number>> = {
   'agent/rules/basalt-mantine.md': 180,
   'agent/rules/basalt-charts.md': 140,
   'agent/rules/basalt-state.md': 160,
-  'agent/rules/basalt-controls.md': 160,
+  'agent/rules/basalt-controls.md': 185,
   'agent/rules/basalt-batteries.md': 220,
   'agent/skills/basalt-app/SKILL.md': 100,
   'agent/skills/basalt-design/SKILL.md': 100,
@@ -3304,9 +3304,14 @@ export function checkCoverage(flags: readonly string[] = []): number {
   }
 
   // ── Assertion 5: every real package.json exports key has a SURFACES entry ────
-  // Excludes ./styles.css and ./configs/* (non-JS assets / raw file paths).
+  // Excludes ./styles.css, ./package.json and ./configs/* (non-JS assets / raw file paths).
   for (const exportKey of pkgExports) {
-    if (exportKey === '.' || exportKey === './styles.css' || exportKey.startsWith('./configs/'))
+    if (
+      exportKey === '.' ||
+      exportKey === './styles.css' ||
+      exportKey === './package.json' ||
+      exportKey.startsWith('./configs/')
+    )
       continue
     if (!Object.hasOwn(SURFACES, exportKey)) {
       failures.push(`package.json exports key '${exportKey}' has no matching SURFACES entry`)

package/src/commands/ShortcutsHelp.tsx

@@ -19,13 +19,15 @@
  */
 import { useEffect, useState } from 'react'
 import { Box, Group, Kbd, Stack, Text, Title } from '@mantine/core'
+import type { BasaltProps } from '../common/props'
+import { cx } from '../common/props'
 import { toShortcutList } from './projectors'
 import { detectMac, parseShortcut } from './shortcut-format'
 import { VX } from '../tokens'
 
 // ── ShortcutsHelpProps ────────────────────────────────────────────────────────
 
-export type ShortcutsHelpProps = {
+export type ShortcutsHelpProps = BasaltProps & {
   /** Section title. Default: 'Keyboard shortcuts'. */
   title?: string
   /** Max-width passthrough (Mantine style prop). */
@@ -69,7 +71,12 @@ function ShortcutRow({
  * @example
  * <ShortcutsHelp title="Keyboard shortcuts" />
  */
-export function ShortcutsHelp({ title = 'Keyboard shortcuts', maw }: ShortcutsHelpProps) {
+export function ShortcutsHelp({
+  title = 'Keyboard shortcuts',
+  maw,
+  className,
+  style,
+}: ShortcutsHelpProps) {
   // Default false — SSR and first client render produce non-mac glyphs (no hydration mismatch).
   // Post-mount effect flips to true on macOS, triggering a single client-only re-render.
   const [isMac, setIsMac] = useState(false)
@@ -94,7 +101,7 @@ export function ShortcutsHelp({ title = 'Keyboard shortcuts', maw }: ShortcutsHe
   }
 
   return (
-    <Box maw={maw}>
+    <Box maw={maw} className={cx(className)} {...(style !== undefined && { style })}>
       <Title order={5} mb="sm">
         {title}
       </Title>

package/src/commands/define-commands.ts

@@ -24,6 +24,7 @@
  */
 import type { ReactNode } from 'react'
 import type { Slot } from '../register'
+import { isDev } from '../utils/is-dev'
 
 // ── Context ───────────────────────────────────────────────────────────────────
 
@@ -171,8 +172,7 @@ export function defineCommand(cmd: Command): Command {
 export function runCommand(id: CommandId, ctx?: CommandRunContext): void | Promise<void> {
   const cmd = activeCommands[id as string]
   if (cmd === undefined) {
-    if (process.env['NODE_ENV'] !== 'production')
-      console.warn(`[basalt] runCommand: no command registered for "${id}"`)
+    if (isDev()) console.warn(`[basalt] runCommand: no command registered for "${id}"`)
     return
   }
   return cmd.run(ctx)

package/src/commands/define-overlays.ts

@@ -26,7 +26,10 @@
  * overlays.open('nonexistent', {})                         // ✗ tsc error
  */
 import type { ReactNode } from 'react'
+import { useEffect } from 'react'
+import { missingLayer } from '../common/errors'
 import type { Slot } from '../register'
+import { isDev } from '../utils/is-dev'
 
 // ── Lazy @mantine/modals resolution ───────────────────────────────────────────
 // @mantine/modals is an OPTIONAL peer — never imported at module evaluation time, so importing
@@ -43,6 +46,60 @@ function loadModals(): Promise<ModalsSingleton | undefined> {
   return modalsPromise
 }
 
+// ── Modals-layer availability ─────────────────────────────────────────────────
+
+/**
+ * How many `ModalsProvider`s are live right now — a COUNTER, not a flag, for the same reason
+ * `notifications/mount-guard.ts` counts: two overlapping mounts are normal (a route swap mounts the
+ * next `BasaltOverlays` before unmounting the previous one), and a last-write-wins boolean reports
+ * the teardown of the OLD one as "no layer" while the new one is serving.
+ *
+ * It is the availability test `overlays.confirm` runs, because `@mantine/modals`' imperative API is
+ * a window event bus: with nothing subscribed the dialog never appears and the promise never
+ * settles. The previous version read `BasaltOverlays`' own `modals` flag instead, which refused the
+ * call whenever a mounted shell passed `modals={false}` — even though the consumer had mounted their
+ * own `<ModalsProvider>`, which is the very remedy the error message names.
+ */
+let mountedModalsProviders = 0
+
+/**
+ * Declare that a `@mantine/modals` `<ModalsProvider>` is mounted and serving, and get back the
+ * function that retracts it. `BasaltOverlays` calls this for its own provider; a consumer mounting
+ * the provider THEMSELVES (with `<BasaltOverlays modals={false} />`, or with no `BasaltOverlays` at
+ * all) calls it too, or `overlays.confirm` cannot tell their provider from no provider and rejects.
+ *
+ * There is no way to detect the provider from outside React — its context is only readable through
+ * `useModals()`, and `confirm` is an imperative call with no component to read it from. So the
+ * registration is explicit.
+ *
+ * @example
+ * useEffect(() => registerModalsProvider(), [])
+ * // …beside your own <ModalsProvider> mount.
+ */
+export function registerModalsProvider(): () => void {
+  mountedModalsProviders++
+  let released = false
+  return () => {
+    // Idempotent: an effect cleanup React runs twice (StrictMode remount) must not drive the count
+    // below the number of providers actually on screen.
+    if (released) return
+    released = true
+    mountedModalsProviders--
+  }
+}
+
+/**
+ * Internal — `BasaltOverlays` registers its OWN lazy `ModalsProvider` here, and only when it
+ * actually renders one. Deliberately NOT on the `./commands` barrel (internal wiring only, same as
+ * `notifications/mount-guard`); the consumer-facing half is {@link registerModalsProvider}.
+ */
+export function useModalsLayer(enabled: boolean): void {
+  useEffect(() => {
+    if (!enabled) return
+    return registerModalsProvider()
+  }, [enabled])
+}
+
 // ── Overlay + OverlayMap ──────────────────────────────────────────────────────
 
 /**
@@ -138,6 +195,143 @@ export function defineOverlay<P = Record<string, unknown>>(overlay: Overlay<P>):
   return overlay
 }
 
+// ── confirm ───────────────────────────────────────────────────────────────────
+
+/** Options for {@link overlays.confirm} — a two-button dialog that resolves to the answer. */
+export type ConfirmOptions = {
+  /** Dialog title — the question itself ("Delete photo.jpg?"), not a category. */
+  title: ReactNode
+  /** Optional body under the title. A plain string is fine; a ReactNode renders as-is. */
+  body?: ReactNode
+  /** Confirm button label. Default: 'Confirm'. */
+  confirmLabel?: string
+  /** Cancel button label. Default: 'Cancel'. */
+  cancelLabel?: string
+  /** Paint the confirm button in the destructive tone (the theme's derived `red` family). */
+  danger?: boolean
+  /** Runs once, before the promise resolves `true`. */
+  onConfirm: () => void
+  /** Runs once on cancel, escape, click-outside or the close button — every non-confirm exit. */
+  onCancel?: () => void
+}
+
+/** Options for {@link overlays.confirmDelete} — the delete idiom over {@link ConfirmOptions}. */
+export type ConfirmDeleteOptions = {
+  /**
+   * The singular noun for what is being deleted — `'item'`, `'photo'`, `'API key'`. Pluralised by
+   * appending `s` when `count` is not 1; a noun that does not pluralise that way calls
+   * {@link overlays.confirm} directly with its own title.
+   */
+  subject: string
+  /** How many. Default: 1. */
+  count?: number
+  /** Runs once, before the promise resolves `true`. */
+  onConfirm: () => void
+}
+
+/**
+ * Open a confirm dialog and resolve to the user's answer — `true` on confirm, `false` on every
+ * other exit (cancel, escape, click-outside, the close button). `onConfirm`/`onCancel` fire exactly
+ * once each at most, before the promise settles.
+ *
+ * Rejects with a named `[basalt]` error when the modals layer cannot serve the dialog — the
+ * `@mantine/modals` peer is absent, or no `ModalsProvider` is registered as live (see
+ * {@link registerModalsProvider}). Both would otherwise leave the promise pending forever: the
+ * imperative API is a window event bus with nothing subscribed.
+ *
+ * @example
+ * if (await overlays.confirm({ title: 'Discard draft?', onConfirm: () => reset() })) navigate('/')
+ *
+ * @example
+ * await overlays.confirm({
+ *   title: 'Revoke access?',
+ *   body: 'The key stops working immediately.',
+ *   confirmLabel: 'Revoke',
+ *   danger: true,
+ *   onConfirm: () => revoke(),
+ * })
+ */
+async function confirm(options: ConfirmOptions): Promise<boolean> {
+  const {
+    title,
+    body,
+    confirmLabel = 'Confirm',
+    cancelLabel = 'Cancel',
+    danger = false,
+    onConfirm,
+    onCancel,
+  } = options
+
+  const modals = await loadModals()
+  if (modals === undefined) {
+    throw new Error(
+      missingLayer(
+        'overlays.confirm',
+        '@mantine/modals',
+        'install the @mantine/modals peer and mount <BasaltOverlays>',
+      ),
+    )
+  }
+  if (mountedModalsProviders === 0) {
+    throw new Error(
+      missingLayer(
+        'overlays.confirm',
+        'a mounted <ModalsProvider>',
+        'drop `modals={false}` from <BasaltOverlays>, or mount <ModalsProvider> yourself and call ' +
+          'registerModalsProvider() from an effect for as long as it is up',
+      ),
+    )
+  }
+
+  return new Promise<boolean>((resolve) => {
+    // Mantine fires onCancel AND onClose on the cancel button, and onClose alone on escape /
+    // click-outside / the X — so the answer is settled once here and every later edge is a no-op.
+    let settled = false
+    const settle = (confirmed: boolean): void => {
+      if (settled) return
+      settled = true
+      try {
+        if (confirmed) onConfirm()
+        else onCancel?.()
+      } finally {
+        resolve(confirmed)
+      }
+    }
+
+    modals.openConfirmModal({
+      title,
+      ...(body !== undefined && { children: body }),
+      labels: { confirm: confirmLabel, cancel: cancelLabel },
+      // The destructive tone is the theme's `red` family (derived from the palette, bound to the
+      // --vx-* status tokens by cssVariablesResolver) — never a raw color.
+      ...(danger && { confirmProps: { color: 'red' } }),
+      onConfirm: () => settle(true),
+      onCancel: () => settle(false),
+      onClose: () => settle(false),
+    })
+  })
+}
+
+/**
+ * The delete confirmation every app writes — `confirm` with the destructive tone, the `Delete`
+ * label and a counted title already filled in.
+ *
+ * @example
+ * overlays.confirmDelete({ subject: 'item', count: 3, onConfirm: () => removeSelected() })
+ * // → "Delete 3 items?"
+ */
+function confirmDelete(options: ConfirmDeleteOptions): Promise<boolean> {
+  const { subject, count = 1, onConfirm } = options
+  const what = count === 1 ? subject : `${count} ${subject}s`
+  return confirm({
+    title: `Delete ${what}?`,
+    body: 'This cannot be undone.',
+    confirmLabel: 'Delete',
+    danger: true,
+    onConfirm,
+  })
+}
+
 // ── overlays controller ───────────────────────────────────────────────────────
 
 /**
@@ -155,8 +349,13 @@ type OverlayProps<K extends OverlayKey> = Overlays extends { [_K in K]: Overlay<
  * quick-edit panels). For shareable/back-button/refreshable overlays use route masks via
  * ./router-tanstack.
  *
+ * `open` needs a REGISTERED overlay; `confirm`/`confirmDelete` need none — they are the two-button
+ * dialog every app was hand-writing as a registry entry.
+ *
  * @example
  * overlays.open('confirm:delete', { name: 'photo.jpg' })
+ * await overlays.confirm({ title: 'Discard draft?', danger: true, onConfirm: () => reset() })
+ * overlays.confirmDelete({ subject: 'item', count: 3, onConfirm: () => removeSelected() })
  * overlays.close()
  */
 export const overlays = {
@@ -173,7 +372,7 @@ export const overlays = {
   open<K extends OverlayKey>(key: K, props: OverlayProps<K>): void {
     const spec = activeOverlays[key as string]
     if (spec === undefined) {
-      if (process.env['NODE_ENV'] !== 'production')
+      if (isDev())
         console.warn(`[basalt] overlays.open: no overlay registered for "${String(key)}"`)
       return
     }
@@ -185,6 +384,22 @@ export const overlays = {
     )
   },
 
+  /**
+   * Open a confirm dialog and resolve to the answer — see {@link confirm}.
+   *
+   * @example
+   * const ok = await overlays.confirm({ title: 'Discard draft?', onConfirm: () => reset() })
+   */
+  confirm,
+
+  /**
+   * The one-line delete idiom over {@link confirm} — see {@link confirmDelete}.
+   *
+   * @example
+   * overlays.confirmDelete({ subject: 'item', count: 3, onConfirm: () => removeSelected() })
+   */
+  confirmDelete,
+
   /**
    * Close all open overlays (delegates to modals.closeAll()).
    *

package/src/commands/index.ts

@@ -28,6 +28,15 @@
  * import { runCommand } from 'basalt-ui/commands'
  * runCommand('file:save')
  *
+ * // usage.ts — the registry-free confirm dialog:
+ * import { overlays } from 'basalt-ui/commands'
+ * const ok = await overlays.confirm({ title: 'Discard draft?', onConfirm: () => reset() })
+ * overlays.confirmDelete({ subject: 'item', count: 3, onConfirm: () => removeSelected() })
+ *
+ * // Mounting ModalsProvider yourself instead of letting <BasaltOverlays> do it:
+ * import { registerModalsProvider } from 'basalt-ui/commands'
+ * useEffect(() => registerModalsProvider(), [])
+ *
  * // Open/close Spotlight programmatically:
  * import { openSpotlight, closeSpotlight } from 'basalt-ui/commands'
  * openSpotlight()
@@ -49,9 +58,12 @@ export {
   defineOverlays,
   defineOverlay,
   overlays,
+  registerModalsProvider,
   type Overlay,
   type OverlayMap,
   type OverlayKey,
+  type ConfirmOptions,
+  type ConfirmDeleteOptions,
 } from './define-overlays'
 
 // ── Projectors ────────────────────────────────────────────────────────────────