basalt-ui 1.41.0 → 2.0.0

package/src/charts/utils/ticks.ts

@@ -1,239 +0,0 @@
-import { VX } from '../../tokens'
-import type { ChartTier } from '../primitives/chart-frame-layout'
-import { maxTextWidth } from './measure-text'
-
-/** 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
- * (`chartMetrics().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
-}
-
-/**
- * The horizontal room one 45°-rotated x label takes: its projected box (`cos 45°` of the width plus
- * one line box) plus the gap. A tilted label still competes with its neighbour for this much, so
- * thinning by the bare `VX.minPxPerTick` floor let two of them touch as soon as the plot widened.
- */
-export function rotatedXLabelPx(labels: string[], fontPx: number = VX.axisFont): number {
-  return (
-    Math.ceil(COS_45 * (maxTextWidth(labels, fontPx) + Math.ceil(fontPx * 1.35))) + 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 REPLACES the `VX.minPxPerTick` constant whenever it is supplied, in either
- * direction — a wide label needs more room than the constant assumed (a `formatX` returning
- * `Mar 08 14:00` used to overlap at every width, the one side of the chart that did not follow
- * §1's "measure what you paint" law), and a narrow one (single-digit band labels) can pack in
- * MORE ticks than the constant would allow, which the floor used to suppress (R2C-11). Omit it and
- * the constant is what governs, same as before.
- *
- * 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.
- *
- * `anchorTerminals` (default false) mirrors the SAME flag `autoMargin`/`Axes.tsx` take: when the
- * axis anchors index 0 and the last index at their TEXT edge rather than their centre
- * (`terminalAnchor`), each reaches a FULL label's width toward its neighbour instead of half, so
- * the plain per-tick pitch above (sized for two centred labels) isn't enough at either boundary —
- * `Bars` with 30 daily "Jan DD HH:MM" keys overlapped there at phone width even though the interior
- * pitch was fine (R2C-6). The SAME rule then applies, symmetrically, to the tick right after
- * index 0. 1.5× is a deliberately generous (cheap, simple) stand-in for "one label plus half a
- * label" rather than measuring the split precisely; it's skipped when `labelPx` is only the bare
- * `VX.minPxPerTick` floor, which has no relationship to how wide a label actually is. Index 0
- * always survives (never the one dropped here) and `last` is always (re-)added below, so dropping
- * any OTHER index never breaks the "at least 2 ticks" floor.
- */
-export function smartTicks(
-  dates: string[],
-  xMax: number,
-  labelPx?: number,
-  anchorTerminals = false,
-): string[] {
-  if (dates.length === 0) return []
-  // A non-positive `labelPx` (a caller's own arithmetic gone wrong, or an explicit 0) is not "no
-  // measurement" — `labelPx ?? VX.minPxPerTick` let it through as-is, and `xMax / 0` then floors
-  // `maxTicks` to `Infinity`, which used to make EVERY tick "fit" and skip thinning entirely.
-  const perTick = labelPx !== undefined && labelPx > 0 ? labelPx : VX.minPxPerTick
-  const maxTicks = Math.max(2, Math.floor(xMax / perTick))
-  const last = dates.length - 1
-  // `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
-  // Only a REAL measured label (not the bare `VX.minPxPerTick` floor, which knows nothing about how
-  // wide a label actually is) earns the wider terminal clearance below.
-  const anchored = anchorTerminals && labelPx !== undefined && labelPx > 0
-
-  const keep = new Set<number>()
-  if (dates.length <= maxTicks) {
-    // Every date already fits with no thinning — round 3: this used to `return dates` here,
-    // skipping the terminal-clearance pass below entirely. A terminal-anchored label still reaches
-    // a FULL label's width toward its neighbour (not half, like a centred one), which the plain
-    // per-tick spacing above does not itself guarantee, so the same pass has to run here too.
-    for (let i = 0; i <= last; i += 1) keep.add(i)
-  } else {
-    const step = Math.ceil(dates.length / maxTicks)
-    for (let i = 0; i <= last; i += step) keep.add(i)
-
-    const BOUNDARY_FACTOR = 1.5
-    const boundaryPx = anchored ? perTick * BOUNDARY_FACTOR : perTick
-    // The final key is appended unconditionally, even when the step misses it — but only dropping
-    // the grid tick right before it when the two would otherwise sit closer than one tick's width.
-    // This is the "would an APPEND overlap" concern; it does nothing when the step already lands on
-    // `last` (nothing is being appended), which is the gap the anchored pass below closes.
-    const lastOnGrid = Math.floor(last / step) * step
-    if (lastOnGrid !== last) {
-      const gapPx = (last - lastOnGrid) * pxPerIndex
-      if (lastOnGrid > 0 && gapPx > 0 && gapPx < boundaryPx) keep.delete(lastOnGrid)
-      keep.add(last)
-    }
-  }
-
-  if (anchored && keep.size > 1) {
-    const BOUNDARY_FACTOR = 1.5
-    const boundaryPx = perTick * BOUNDARY_FACTOR
-    // START: the kept index right after 0 needs a FULL label's clearance from it, not the plain
-    // per-tick pitch a centred label would settle for.
-    const sorted = [...keep].toSorted((a, b) => a - b)
-    const second = sorted[1]
-    if (second !== undefined && second !== last && second * pxPerIndex < boundaryPx) {
-      keep.delete(second)
-    }
-    // END: the same check, mirrored, against whatever is now the second-to-last kept index —
-    // computed AFTER the START drop above (not from the original grid), and unconditional of
-    // whether `last` was naturally on the grid or had to be appended (round 3's fix: previously this
-    // only ran inside the `lastOnGrid !== last` branch above, so a grid that already landed on
-    // `last` skipped it — the 13-dates/60px-label/260px-width counter-example this closes: step 4
-    // lands on index 12, leaving its neighbour at index 8 only 80px away, under the 90px a
-    // full-width terminal label needs).
-    const afterHead = [...keep].toSorted((a, b) => a - b)
-    const secondLast = afterHead[afterHead.length - 2]
-    if (
-      secondLast !== undefined &&
-      secondLast !== 0 &&
-      (last - secondLast) * pxPerIndex < boundaryPx
-    ) {
-      keep.delete(secondLast)
-    }
-  }
-
-  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. */
-export function smartTicksEvery(dates: string[], count: number): string[] {
-  if (dates.length === 0) return []
-  if (dates.length <= count) return dates
-  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/commands/overlays-mount.tsx

@@ -1,333 +0,0 @@
-/**
- * overlays-mount — composable overlay mount for basalt-ui apps.
- *
- * `BasaltOverlays` bundles ModalsProvider, Spotlight, and Notifications into a single mount point.
- * Put it inside BasaltProvider, before the router. It is the ONLY notifications mount — the
- * standalone `basalt-ui/notifications` overlay it superseded is gone (C1 consolidation); mounting
- * a second, hand-rolled `<Notifications />` alongside `<BasaltOverlays notifications />` still
- * double-mounts the overlay and is still wrong for the same reason.
- *
- * Every layer — ModalsProvider included — mounts as a SIBLING of `children`, never as a wrapper:
- * see the comment in the component body (R1). `@mantine/modals`' imperative API (`modals.open*`,
- * and so basalt's own `overlays.open`) is a window CustomEvent bus that ModalsProvider subscribes
- * to, so nothing needs to be inside it; the one thing a sibling cannot serve is Mantine's
- * `useModals()` context hook.
- *
- * Each overlay system is opt-in via props (all default to true). Use flags to disable layers the
- * app does not need — e.g. a charts-only app that has no commands can set `spotlight={false}`.
- * A disabled layer's optional peer is NEVER imported — each layer is lazy-loaded (React.lazy +
- * dynamic import()) only when its flag is true, and degrades to a no-op fallback instead of
- * crashing when the peer is absent.
- *
- * Optional peers required (only when the corresponding layer is enabled):
- *   @mantine/modals ^9.3.0     (for modals)
- *   @mantine/spotlight ^9.3.0  (for spotlight)
- *   @mantine/notifications ^9.3.0 (for notifications)
- *   @tanstack/react-hotkeys ^0.10.0 (optional — keybindings degrade to no-op when absent)
- *
- * Spotlight live store: BasaltOverlays uses a basalt-owned createSpotlight() store so the
- * spotlight instance is separate from Mantine's default global. The store is created lazily (on
- * first use, whether from mounting the spotlight layer or from calling openSpotlight()/
- * closeSpotlight()) so @mantine/spotlight is never imported until actually needed. Import
- * `basaltSpotlight` and call `basaltSpotlight.open()` / `basaltSpotlight.close()` from consumer
- * code. The re-exported `openSpotlight` / `closeSpotlight` helpers delegate to this store.
- *
- * @example
- * // main.tsx — mount <BasaltOverlays>. Use the layered bundle — the unlayered one outranks
- * // basalt's `@layer basalt` styles regardless of specificity:
- * import { BasaltOverlays } from 'basalt-ui/commands'
- * import '@mantine/spotlight/styles.layer.css'
- *
- * createRoot(root).render(
- *   <BasaltProvider>
- *     <BasaltOverlays>
- *       <App />
- *     </BasaltOverlays>
- *   </BasaltProvider>
- * )
- *
- * // Disable spotlight for apps without commands — @mantine/spotlight is then never imported:
- * <BasaltOverlays spotlight={false}>
- *   <App />
- * </BasaltOverlays>
- *
- * // Open/close programmatically:
- * import { openSpotlight, closeSpotlight } from 'basalt-ui/commands'
- * openSpotlight()
- */
-import type { ComponentType, ReactNode } from 'react'
-import { lazy, Suspense } from 'react'
-import type { ModalsProviderProps } from '@mantine/modals'
-import type { NotificationsProps } from '@mantine/notifications'
-import type { SpotlightActionData } from '@mantine/spotlight'
-import { runCommand } from './define-commands'
-import type { CommandId } from './define-commands'
-import { useModalsLayer } from './define-overlays'
-import { toSpotlightActions } from './projectors'
-import { useCommandHotkeys } from './useCommandHotkeys'
-import { useNotificationsMountGuard } from '../notifications/mount-guard'
-
-// ── Lazy @mantine/spotlight resolution (module-wide singleton) ────────────────
-
-type SpotlightModule = typeof import('@mantine/spotlight')
-type SpotlightStore = ReturnType<SpotlightModule['createSpotlight']>[0]
-type SpotlightActions = ReturnType<SpotlightModule['createSpotlight']>[1]
-type SpotlightHandle = { store: SpotlightStore; actions: SpotlightActions }
-
-let spotlightHandlePromise: Promise<SpotlightHandle | undefined> | undefined
-
-/**
- * Lazily resolves @mantine/spotlight and creates the basalt-owned createSpotlight() store.
- * Memoized module-wide so the spotlight layer's SpotlightMount and the openSpotlight/
- * closeSpotlight helpers share one store instance. Resolves to undefined when the peer is
- * absent — callers degrade to a no-op instead of crashing.
- */
-function loadSpotlightHandle(): Promise<SpotlightHandle | undefined> {
-  spotlightHandlePromise ??= import('@mantine/spotlight')
-    .then(({ createSpotlight }) => {
-      const [store, actions] = createSpotlight()
-      return { store, actions }
-    })
-    .catch(() => undefined)
-  return spotlightHandlePromise
-}
-
-// ── basaltSpotlight singleton ─────────────────────────────────────────────────
-
-/**
- * Basalt-owned Spotlight actions (open/close/toggle), backed by a lazily-created
- * createSpotlight() store so @mantine/spotlight is only imported on first use.
- *
- * @example
- * import { basaltSpotlight } from 'basalt-ui/commands'
- * basaltSpotlight.open()
- */
-export const basaltSpotlight = {
-  open: (): void => {
-    void loadSpotlightHandle().then((handle) => handle?.actions.open())
-  },
-  close: (): void => {
-    void loadSpotlightHandle().then((handle) => handle?.actions.close())
-  },
-  toggle: (): void => {
-    void loadSpotlightHandle().then((handle) => handle?.actions.toggle())
-  },
-}
-
-// ── openSpotlight / closeSpotlight ────────────────────────────────────────────
-
-/** Open the basalt Spotlight palette programmatically. */
-export function openSpotlight(): void {
-  basaltSpotlight.open()
-}
-
-/** Close the basalt Spotlight palette programmatically. */
-export function closeSpotlight(): void {
-  basaltSpotlight.close()
-}
-
-// ── BasaltOverlaysProps ───────────────────────────────────────────────────────
-
-export type BasaltOverlaysProps = {
-  /** Mount @mantine/modals ModalsProvider. Default: true. */
-  modals?: boolean
-  /** Mount @mantine/spotlight Spotlight with mod+K shortcut. Default: true. */
-  spotlight?: boolean
-  /** Mount @mantine/notifications Notifications overlay. Default: true. */
-  notifications?: boolean
-  /**
-   * Activate @tanstack/react-hotkeys keybindings for all registered commands. Default: true.
-   * Degrades to no-op when @tanstack/react-hotkeys peer is absent — safe to leave enabled.
-   */
-  hotkeys?: boolean
-  /** Override or extend the Notifications props (position, autoClose, limit, etc.). Defaults: position="bottom-right", autoClose=4000, limit=5. */
-  notificationsProps?: Omit<NotificationsProps, 'children'>
-  /**
-   * Extra Spotlight actions merged with the command-projected actions — e.g.
-   * toRouteActions(nav, { onNavigate }) for page navigation. Rendered BEFORE the command actions
-   * and grouped by each action's `group`. A static snapshot, same as the command projection.
-   */
-  spotlightActions?: SpotlightActionData[]
-  /**
-   * Auto-project the registered command bus into Spotlight actions. Default: true. Set false when
-   * the app supplies the FULL action list itself via `spotlightActions` (e.g. to decorate commands
-   * with kind badges built from `toSpotlightActions()`) — this avoids the commands appearing twice.
-   */
-  projectCommands?: boolean
-  /** App content (required). */
-  children: ReactNode
-}
-
-// ── Lazy ModalsProvider (falls back to rendering nothing) ─────────────────────
-
-/** Missing-peer fallback. Mounted childless (see BasaltOverlays), so it renders nothing. */
-function PassthroughFragment({ children }: ModalsProviderProps) {
-  return <>{children}</>
-}
-
-const LazyModalsProvider = lazy(() =>
-  import('@mantine/modals')
-    .then((m) => ({ default: m.ModalsProvider }))
-    .catch(() => ({ default: PassthroughFragment })),
-)
-Object.assign(LazyModalsProvider, { displayName: 'LazyModalsProvider' })
-
-// ── Lazy SpotlightMount (falls back to rendering nothing) ─────────────────────
-
-function NullFallback(): ReactNode {
-  return null
-}
-
-/**
- * Lazily resolves @mantine/spotlight and mounts Spotlight with a live-updating actions list
- * synced to the command registry, sharing the store created by loadSpotlightHandle().
- *
- * Actions are a snapshot at render time — sufficient because commands are registered at module
- * load before BasaltOverlays mounts. A future reactive stash can add a version counter here.
- */
-const LazySpotlightMount = lazy<
-  ComponentType<{ extraActions?: SpotlightActionData[]; projectCommands?: boolean }>
->(() =>
-  Promise.all([import('@mantine/spotlight'), loadSpotlightHandle()])
-    .then(([{ Spotlight }, handle]) => {
-      if (handle === undefined) return { default: NullFallback }
-      // Re-bind as a fresh const so the non-undefined narrowing above survives into the
-      // nested closure below (TS does not carry a parameter narrowing into nested functions).
-      const spotlightHandle: SpotlightHandle = handle
-
-      function SpotlightMountInner({
-        extraActions,
-        projectCommands = true,
-      }: {
-        extraActions?: SpotlightActionData[]
-        projectCommands?: boolean
-      }): ReactNode {
-        const commandActions = projectCommands
-          ? toSpotlightActions((id) => {
-              spotlightHandle.actions.close()
-              void runCommand(id as CommandId)
-            })
-          : []
-        const actions = [...(extraActions ?? []), ...commandActions]
-
-        // maxHeight bounds the results ScrollArea so the palette has ONE inner scroller — without it
-        // a long action list overflows the modal content box too, producing a double scrollbar.
-        return (
-          <Spotlight
-            store={spotlightHandle.store}
-            actions={actions}
-            shortcut="mod + K"
-            maxHeight={420}
-          />
-        )
-      }
-
-      return { default: SpotlightMountInner }
-    })
-    .catch(() => ({ default: NullFallback })),
-)
-Object.assign(LazySpotlightMount, { displayName: 'LazySpotlightMount' })
-
-// ── Lazy Notifications (falls back to rendering nothing) ──────────────────────
-
-function NotificationsFallback(_props: NotificationsProps): ReactNode {
-  return null
-}
-
-const LazyNotifications = lazy<ComponentType<NotificationsProps>>(() =>
-  import('@mantine/notifications')
-    .then((m) => ({ default: m.Notifications as ComponentType<NotificationsProps> }))
-    .catch(() => ({ default: NotificationsFallback })),
-)
-Object.assign(LazyNotifications, { displayName: 'LazyNotifications' })
-
-// ── NotificationsLayer (runs the shared duplicate-mount guard, F15) ───────────
-
-/** Wraps `LazyNotifications` so `useNotificationsMountGuard` only fires while this layer is
- * actually enabled — the shared counter guards against any second `<Notifications />` mount. */
-function NotificationsLayer({
-  notificationsProps,
-}: {
-  notificationsProps: Omit<NotificationsProps, 'children'> | undefined
-}) {
-  useNotificationsMountGuard()
-  return (
-    <Suspense fallback={null}>
-      <LazyNotifications
-        position="bottom-right"
-        autoClose={4000}
-        limit={5}
-        {...notificationsProps}
-      />
-    </Suspense>
-  )
-}
-
-// ── HotkeysMount (inner component — ensures hook is inside component tree) ────
-
-/** Mounts useCommandHotkeys inside the overlay tree. Graceful no-op when peer is absent. */
-function HotkeysMount() {
-  useCommandHotkeys()
-  return null
-}
-
-// ── BasaltOverlays ────────────────────────────────────────────────────────────
-
-/**
- * Composable overlay mount — renders ModalsProvider, Spotlight and Notifications as siblings of
- * `children`. All three layers are enabled by default; pass `false` to disable. A disabled layer's
- * optional peer is never imported.
- *
- * Mount exactly ONE BasaltOverlays per app — a second instance double-mounts `<Notifications />`.
- *
- * @example
- * <BasaltProvider>
- *   <BasaltOverlays>
- *     <RouterProvider router={router} />
- *   </BasaltOverlays>
- * </BasaltProvider>
- */
-export function BasaltOverlays({
-  modals: enableModals = true,
-  spotlight: enableSpotlight = true,
-  notifications: enableNotifications = true,
-  hotkeys: enableHotkeys = true,
-  notificationsProps,
-  spotlightActions,
-  projectCommands = true,
-  children,
-}: BasaltOverlaysProps) {
-  // Register the modals layer this mount serves, so `overlays.confirm` can reject with a named
-  // error instead of returning a promise nothing will ever settle (nothing subscribes to the modals
-  // event bus when no provider is up). With `modals={false}` nothing is registered here — a
-  // consumer mounting `<ModalsProvider>` themselves calls `registerModalsProvider()` instead.
-  useModalsLayer(enableModals)
-
-  // `children` sits OUTSIDE every Suspense boundary, and that is load-bearing (R1): React.lazy
-  // suspends on its first render even when the module is already warm, so a boundary wrapping the
-  // app defers the app's FIRST COMMIT past a microtask tick. TanStack Router's async loadMatches
-  // then resolves into that window and setStates onto the not-yet-mounted Transitioner fiber —
-  // "Can't perform a React state update on a component that hasn't mounted yet". The old shape
-  // also rendered `children` twice (once as the fallback, once resolved), running every effect in
-  // the app in both trees. Never put `children` under a lazy boundary here.
-  return (
-    <>
-      {enableSpotlight && (
-        <Suspense fallback={null}>
-          <LazySpotlightMount
-            projectCommands={projectCommands}
-            {...(spotlightActions !== undefined && { extraActions: spotlightActions })}
-          />
-        </Suspense>
-      )}
-      {enableNotifications && <NotificationsLayer notificationsProps={notificationsProps} />}
-      {enableHotkeys && <HotkeysMount />}
-      {enableModals && (
-        <Suspense fallback={null}>
-          <LazyModalsProvider />
-        </Suspense>
-      )}
-      {children}
-    </>
-  )
-}

package/src/commands/useCommandHotkeys.ts

@@ -1,114 +0,0 @@
-/**
- * useCommandHotkeys — binds the active command registry to keyboard shortcuts via
- * @tanstack/react-hotkeys.
- *
- * OPTIONAL PEER: @tanstack/react-hotkeys is an optional peer dependency. This hook degrades
- * gracefully to a no-op when the peer is absent — core imports cleanly with the peer missing.
- *
- * Implementation: uses dynamic import() inside useEffect to lazily resolve the optional peer.
- * Registration is imperative via the `getHotkeyManager()` singleton (re-exported from
- * @tanstack/react-hotkeys → @tanstack/hotkeys). Each effect run registers all shortcut commands
- * and returns a cleanup that unregisters them. This is fully rules-of-hooks compliant and works
- * in strict ESM environments (no require()).
- *
- * No HotkeysProvider is required — @tanstack/react-hotkeys uses a singleton HotkeyManager.
- *
- * @example
- * // Typical placement — inside BasaltOverlays so keybindings are active whenever overlays mount:
- * useCommandHotkeys()
- *
- * // Standalone consumer:
- * import { useCommandHotkeys } from 'basalt-ui/commands'
- * function App() {
- *   useCommandHotkeys()
- *   return <RouterProvider router={router} />
- * }
- */
-import { useEffect } from 'react'
-import { getActiveCommands } from './define-commands'
-
-// ── HotkeyManager peer types (erased at runtime) ──────────────────────────────
-
-// We only import types here — the actual module is loaded dynamically inside useEffect.
-// This keeps the module resolvable even when the peer is absent (no static import).
-
-type HotkeyHandle = {
-  unregister: () => void
-  callback: (event: KeyboardEvent) => void
-}
-
-type HotkeyManagerType = {
-  register: (
-    hotkey: string,
-    callback: (event: KeyboardEvent) => void,
-    options?: { preventDefault?: boolean },
-  ) => HotkeyHandle
-}
-
-type PeerModule = {
-  getHotkeyManager: () => HotkeyManagerType
-}
-
-// ── useCommandHotkeys ─────────────────────────────────────────────────────────
-
-/**
- * Reads the active command registry and binds each command's `shortcut` to its `run()` via
- * the @tanstack/react-hotkeys HotkeyManager singleton. Degrades to a no-op when the optional
- * peer is absent.
- *
- * Registers on mount, unregisters on unmount. Re-runs whenever the effect deps change.
- * Commands without a shortcut are skipped. Commands where `when()` returns false at press time
- * are silently skipped (the binding stays registered; the when-gate fires in the callback).
- *
- * @example
- * useCommandHotkeys()
- */
-export function useCommandHotkeys(): void {
-  useEffect(() => {
-    let handles: HotkeyHandle[] = []
-    let cancelled = false
-
-    const bind = async (): Promise<void> => {
-      let peer: PeerModule
-      try {
-        peer = (await import('@tanstack/react-hotkeys')) as unknown as PeerModule
-      } catch {
-        // Peer absent — stay no-op.
-        return
-      }
-      if (cancelled) return
-      if (typeof peer.getHotkeyManager !== 'function') return
-
-      const manager = peer.getHotkeyManager()
-      const cmds = getActiveCommands()
-
-      for (const [, cmd] of Object.entries(cmds)) {
-        if (cmd.shortcut === undefined) continue
-
-        const handle = manager.register(
-          cmd.shortcut,
-          (event: KeyboardEvent) => {
-            // Respect the when() gate at execution time (not registration time)
-            if (cmd.when !== undefined && !cmd.when()) return
-            // Only prevent default when the command will actually run
-            event.preventDefault()
-            void cmd.run()
-          },
-          // preventDefault: false — we handle it manually above, gated on when()
-          { preventDefault: false },
-        )
-        handles.push(handle)
-      }
-    }
-
-    void bind()
-
-    return () => {
-      cancelled = true
-      for (const handle of handles) {
-        handle.unregister()
-      }
-      handles = []
-    }
-  }, [])
-}