basalt-ui 1.31.0 → 1.32.1

package/src/charts/primitives/chart-frame-layout.ts

@@ -286,38 +286,46 @@ const legendEntryWidth = (item: LegendEntry): number =>
   )
 
 /**
- * The greedy chip-width wrap {@link entriesWithinRows} runs — split out so
- * {@link entriesWithinChipRows} can run it a second time against a narrower, reserve-adjusted
- * width without duplicating the wrap arithmetic. `allowZero` (default false) drops the "the first
- * entry always fits" guarantee a bare row-fit needs (a raw width-vs-0 check is meaningless
- * otherwise): without it, the SAME entry the caller is about to also draw an `All N` chip beside
- * would always be counted as fitting even when the two together provably don't.
+ * The ONE greedy wrap every legend fit runs — the same wrap the flex container performs, measured
+ * rather than assumed. Each item costs `widthOf(item)` (plus `gap` after the row's first) and
+ * `extraAfter(i)` more once placed (a group divider is its own flex item). `allowZero` (default
+ * false) drops the "the first entry always fits" guarantee a bare row-fit needs: a reserved pass
+ * (the `All N` chip already took its room) must be able to answer 0, or the SAME entry the caller
+ * is about to draw the chip beside would always count as fitting even when the two provably don't.
  */
-function fitChipRows(
-  items: readonly LegendEntry[],
-  width: number,
-  rows: number,
-  allowZero = false,
+function fitGreedyRows<T>(
+  items: readonly T[],
+  fit: {
+    widthOf: (item: T) => number
+    gap: number
+    width: number
+    rows: number
+    allowZero?: boolean
+    extraAfter?: (index: number) => number
+  },
 ): number {
   let row = 1
   let x = 0
   let fitted = 0
-  for (const item of items) {
-    const w = legendEntryWidth(item)
-    const next = x === 0 ? w : x + VX.legendGap + w
-    if (x === 0 && allowZero && next > width) return 0
-    if (next > width && x > 0) {
+  for (const [i, item] of items.entries()) {
+    const w = fit.widthOf(item)
+    const next = x === 0 ? w : x + fit.gap + w
+    if (x === 0 && fit.allowZero === true && next > fit.width) return 0
+    if (next > fit.width && x > 0) {
       row += 1
-      if (row > rows) return fitted
+      if (row > fit.rows) return fitted
       x = w
     } else {
       x = next
     }
     fitted += 1
+    x += fit.extraAfter?.(i) ?? 0
   }
   return fitted
 }
 
+const chipFit = { widthOf: legendEntryWidth, gap: VX.legendGap }
+
 /** How many of `items` fit in `rows` wrapped rows of `width` — the same greedy wrap the flex
  * container performs, measured rather than assumed (`docs/CHARTS-SPEC.md` §1). */
 export function entriesWithinRows(
@@ -325,7 +333,7 @@ export function entriesWithinRows(
   width: number,
   rows: number,
 ): number {
-  return fitChipRows(items, width, rows)
+  return fitGreedyRows(items, { ...chipFit, width, rows })
 }
 
 /**
@@ -342,44 +350,15 @@ export function entriesWithinChipRows(
   rows: number,
 ): number {
   const total = items.length
-  const fittedNoReserve = fitChipRows(items, width, rows)
+  const fittedNoReserve = entriesWithinRows(items, width, rows)
   if (fittedNoReserve >= total) return fittedNoReserve
   const reserve = measureText(`All ${total}`, VX.legendFontSize) + VX.legendGap
-  return fitChipRows(items, Math.max(width - reserve, 0), rows, true)
-}
-
-/** The greedy dot-pitch wrap `entriesWithinDotRows` runs twice — once optimistically, once against
- * a width that already gave up the `All N` chip's room. A group divider is its own flex item, so it
- * costs one more pitch before the next dot. `allowZero` (default false) mirrors {@link fitChipRows}'s
- * own flag: without it the first dot always counts as fitted regardless of `width`, which is wrong
- * for the reserved pass once reserving has left no usable room at all. */
-function fitDotRows(
-  items: readonly LegendEntry[],
-  width: number,
-  rows: number,
-  dividerAfter: ReadonlySet<number>,
-  allowZero = false,
-): number {
-  let row = 1
-  let x = 0
-  let fitted = 0
-  for (let i = 0; i < items.length; i += 1) {
-    // `DOT_PITCH` already IS one dot's full footprint (its own size plus the gap to a neighbour,
-    // `LEGEND_DOT_SIZE + DOTS_HIT_GAP`) — adding `LEGEND_DOT_SIZE` again here double-counted every
-    // dot after the row's first, wrapping a legend to `All N` well before it actually overflowed.
-    const next = x === 0 ? LEGEND_DOT_SIZE : x + DOT_PITCH
-    if (x === 0 && allowZero && next > width) return 0
-    if (next > width && x > 0) {
-      row += 1
-      if (row > rows) return fitted
-      x = LEGEND_DOT_SIZE
-    } else {
-      x = next
-    }
-    fitted += 1
-    if (dividerAfter.has(i)) x += DOT_PITCH
-  }
-  return fitted
+  return fitGreedyRows(items, {
+    ...chipFit,
+    width: Math.max(width - reserve, 0),
+    rows,
+    allowZero: true,
+  })
 }
 
 /**
@@ -398,11 +377,20 @@ export function entriesWithinDotRows(
   rows: number,
   dividerAfter: ReadonlySet<number> = new Set(),
 ): number {
+  // A dot is `LEGEND_DOT_SIZE` wide and `DOT_PITCH` already IS its full footprint (size plus the
+  // gap to a neighbour) — so the gap is the pitch LESS the dot; adding the dot again double-counted
+  // every dot after the row's first and wrapped to `All N` well before it overflowed.
+  const dotFit = {
+    widthOf: () => LEGEND_DOT_SIZE,
+    gap: DOT_PITCH - LEGEND_DOT_SIZE,
+    rows,
+    extraAfter: (i: number) => (dividerAfter.has(i) ? DOT_PITCH : 0),
+  }
   const total = items.length
-  const fittedNoReserve = fitDotRows(items, width, rows, dividerAfter)
+  const fittedNoReserve = fitGreedyRows(items, { ...dotFit, width })
   if (fittedNoReserve >= total) return fittedNoReserve
   const reserve = measureText(`All ${total}`, VX.legendFontSize) + DOT_PITCH
-  return fitDotRows(items, Math.max(width - reserve, 0), rows, dividerAfter, true)
+  return fitGreedyRows(items, { ...dotFit, width: Math.max(width - reserve, 0), allowZero: true })
 }
 
 /**

package/src/charts/primitives/legend-disclosure.tsx

@@ -0,0 +1,177 @@
+import type { CSSProperties, ReactNode } from 'react'
+import { useCallback, useEffect, useId, useRef, useState } from 'react'
+import { createPortal } from 'react-dom'
+import { alpha, VX } from '../../tokens'
+import { useDismissOnOutside } from '../cursor/touch-pin'
+import { LEGEND_ROW_GAP } from './chart-frame-layout'
+
+const DISCLOSURE_PANEL: CSSProperties = {
+  position: 'fixed',
+  zIndex: VX.zIndexFloating,
+  display: 'flex',
+  flexDirection: 'column',
+  gap: LEGEND_ROW_GAP,
+  // theme-allow raw-scroll-container — a fixed floating panel of one legend, not app chrome
+  overflowY: 'auto',
+  // `<dialog open>` brings UA chrome (centring margin, border, fit-content box) this resets.
+  margin: 0,
+  border: 'none',
+  width: 'auto',
+  height: 'auto',
+  padding: 10,
+  boxSizing: 'border-box',
+  backgroundColor: VX.surface.overlay,
+  boxShadow: VX.shadowOverlay,
+  color: VX.muted,
+  borderRadius: VX.radiusCard,
+}
+
+/** A popover never collapses below one usable row, however little room the chip leaves. */
+const DISCLOSURE_MIN_HEIGHT = 96
+
+/** A popover hangs off its chip (flipping above when there is no room below); a sheet is docked. */
+function disclosurePlacement(chip: DOMRect, coarse: boolean): CSSProperties {
+  if (coarse) {
+    return {
+      left: 0,
+      right: 0,
+      bottom: 0,
+      maxHeight: '60dvh',
+      borderBottomLeftRadius: 0,
+      borderBottomRightRadius: 0,
+      padding: '12px 16px calc(12px + env(safe-area-inset-bottom, 0px))',
+    }
+  }
+  const below = window.innerHeight - chip.bottom
+  const left = Math.max(8, Math.min(chip.left, window.innerWidth - 248))
+  const base = { left, right: 'auto', minWidth: 200, maxWidth: 'calc(100vw - 16px)' }
+  return below >= 200 || below >= chip.top
+    ? { ...base, top: chip.bottom + 4, maxHeight: Math.max(below - 12, DISCLOSURE_MIN_HEIGHT) }
+    : {
+        ...base,
+        bottom: window.innerHeight - chip.top + 4,
+        maxHeight: Math.max(chip.top - 12, DISCLOSURE_MIN_HEIGHT),
+      }
+}
+
+/**
+ * `ChartLegend`'s `All N` disclosure state: which button opened it (the chip, or a dots-mode entry)
+ * and where the fixed panel sits. Focus moves into the panel on open and back to that trigger on
+ * EVERY close path; a scroll outside the panel or a resize closes it, since it is fixed to where the
+ * trigger WAS.
+ */
+export function useLegendDisclosure(coarse: boolean) {
+  const [placement, setPlacement] = useState<CSSProperties | null>(null)
+  const triggerRef = useRef<HTMLButtonElement | null>(null)
+  const panelRef = useRef<HTMLDialogElement>(null)
+  const panelId = useId()
+  const wasOpen = useRef(false)
+  const open = placement !== null
+  const close = useCallback(() => setPlacement(null), [])
+  const openFrom = (trigger: HTMLButtonElement) => {
+    triggerRef.current = trigger
+    setPlacement(disclosurePlacement(trigger.getBoundingClientRect(), coarse))
+  }
+
+  useEffect(() => {
+    if (open) panelRef.current?.focus()
+    else if (wasOpen.current) triggerRef.current?.focus()
+    wasOpen.current = open
+  }, [open])
+
+  // Shared with the chart cursors' own outside-dismiss (`useChartCursor`/`useDiscreteCursor`, see
+  // `touch-pin.ts`); the panel's own scroll is not an outside one.
+  const isInsidePanel = useCallback(
+    (target: Node): boolean =>
+      panelRef.current?.contains(target) === true || triggerRef.current?.contains(target) === true,
+    [],
+  )
+  useDismissOnOutside({
+    enabled: open,
+    isInside: isInsidePanel,
+    onDismiss: close,
+    dismissOnResize: true,
+    scrollExemptInside: true,
+  })
+
+  // The coarse sheet claims `aria-modal` (below), which is a claim that Tab cannot leave it — a
+  // native `<dialog open>` (no `showModal()`) does not enforce that on its own (B14). Wrap Tab at
+  // the panel's own first/last focusable rather than the fine popover, which is dismissed by an
+  // outside click/Escape just as easily and never claimed to be modal in the first place.
+  useEffect(() => {
+    if (!open || !coarse) return
+    const panel = panelRef.current
+    if (panel === null) return
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key !== 'Tab') return
+      const focusable = panel.querySelectorAll<HTMLElement>(
+        'button, [tabindex]:not([tabindex="-1"])',
+      )
+      const first = focusable[0]
+      const last = focusable[focusable.length - 1]
+      if (first === undefined || last === undefined) return
+      if (e.shiftKey && document.activeElement === first) {
+        e.preventDefault()
+        last.focus()
+      } else if (!e.shiftKey && document.activeElement === last) {
+        e.preventDefault()
+        first.focus()
+      }
+    }
+    panel.addEventListener('keydown', onKeyDown)
+    return () => panel.removeEventListener('keydown', onKeyDown)
+  }, [open, coarse])
+
+  return { open, panelId, openFrom, close, panel: { panelRef, panelId, coarse, placement, close } }
+}
+
+/** The portalled panel itself — a popover under the chip on a fine pointer, a docked sheet (over a
+ * scrim) on a coarse one. Fixed-position, so opening it never grows the legend band. */
+export function LegendDisclosure({
+  panelRef,
+  panelId,
+  coarse,
+  placement,
+  close,
+  fontSize,
+  children,
+}: ReturnType<typeof useLegendDisclosure>['panel'] & {
+  fontSize: number
+  children: ReactNode
+}) {
+  if (placement === null) return null
+  return createPortal(
+    <>
+      {coarse && (
+        <div
+          aria-hidden
+          onPointerDown={(e) => {
+            e.stopPropagation()
+            close()
+          }}
+          style={{
+            position: 'fixed',
+            inset: 0,
+            // One below the panel it sits behind — still `VX.zIndexFloating`-derived, never a
+            // second unrelated literal (B14).
+            zIndex: VX.zIndexFloating - 1,
+            backgroundColor: alpha(VX.neutral, 0.35),
+          }}
+        />
+      )}
+      <dialog
+        ref={panelRef}
+        id={panelId}
+        open
+        tabIndex={-1}
+        aria-label="Legend"
+        {...(coarse && { 'aria-modal': true })}
+        data-basalt-legend-disclosure={coarse ? 'sheet' : 'popover'}
+        style={{ ...DISCLOSURE_PANEL, fontSize, ...placement }}
+      >
+        {children}
+      </dialog>
+    </>,
+    document.body,
+  )
+}

package/src/controls/controls.module.css

@@ -49,6 +49,11 @@
   flex-shrink: 0;
 }
 
+/* theme-allow-file raw-media-query — the ControlRow's own C9 swap (pills inline, the rest in a
+   sheet) keys on the SIZE CLASS by design: the sheet is compact-class chrome, the same axis the
+   shell's bottom bar reads. Every width query here is `SIZE_CLASSES.medium`, pinned by
+   `breakpoint-literals.test.ts`. */
+
 /* Below `sm` only the first `inline` slots are pills; the rest live in the sheet. */
 @media (max-width: 52.49375em) {
   .pillSlot:not([data-inline]) {

package/src/controls/sync-button.module.css

@@ -45,6 +45,7 @@
  * width itself, pinned to the `ctl` height so the box is square. This module is unlayered, so it
  * outranks `@layer mantine` regardless of specificity.
  */
+/* theme-allow raw-media-query — the control's own C9 icon-only swap at the compact size class */
 @media (max-width: 52.49375em) {
   .label,
   .age {

package/src/dashboard/stat-group.module.css

@@ -15,24 +15,24 @@
  * one: a query with no container resolves to false, so a shell-only context would have silently
  * pinned every non-shell consumer to the base count.
  *
- * The `@supports not` block below it is the pre-2023 fallback and the ONLY place the old viewport
- * law survives. It is written as an exclusive alternative rather than as a base the container
- * queries override, because the rail's `:nth-child` suppressors are MORE specific than the rule
- * that draws the border: two overlapping laws would each suppress a different set of leading cells
- * and the rail would lose hairlines in the middle of a row. One law at a time, chosen by support.
+ * The literals are the container-class law (`CONTAINER_CLASSES`, `tokens/size-classes.ts`): the
+ * `sm` count opens at `wide` (800px), not at the viewport-era 768. Two are StatGroup's own and say
+ * so: 260px (one column, below) and 1200px, where the full `cols` count opens. The class table
+ * stops at 800, and 800 is too early for a full KPI row — four cells of ~190px clamp a value a real
+ * dashboard prints (`tests/layout/page-aside.layout.test.ts` measures ~195px against the 844px row
+ * a claimed aside leaves). Conditions are px, never `em`: `em` inside a `@container` condition
+ * resolves against the CONTAINER's font-size, so a consumer panel with smaller text would silently
+ * move the boundary. A condition cannot read a custom property, so the numbers are written; the
+ * COUNTS are custom properties the component sets per instance.
  *
- * The literals: `@container` conditions are stated in px, `@media` ones in Mantine's own `em`
- * (`--mantine-breakpoint-sm` 48em, `--mantine-breakpoint-lg` 75em). Both spellings name the same
- * boundary at the 16px initial font size — 768px and 1200px — but `em` inside a `@container`
- * condition resolves against the CONTAINER's font-size rather than the root's, so a consumer panel
- * with smaller text would silently move the breakpoint. px is the only spelling that cannot drift.
- * (`47.99375em` → `767.9px`, `74.99375em` → `1199.9px`.) A condition still cannot read a custom property either way, so the numbers are written;
- * the COUNTS are custom properties the component sets per instance.
+ * No viewport fallback: basalt's own CSS already requires `color-mix()` (Safari 16.2, Chrome 111,
+ * Firefox 113), and every one of those parses `@container` — a `@supports not (container-type)`
+ * block is unreachable in any browser that renders basalt at all.
  */
 
 .container {
   container-type: inline-size;
-  container-name: basalt-stat-group;
+  container-name: basalt-grid;
 }
 
 .root {
@@ -45,7 +45,7 @@
 
 /* 260px is StatGroup's own literal (docs/DESIGN-CORE.md § Layout, elevation, shapes), not a container class: one column below it,
  * so every cell leads a row and the rail draws no leading hairline at all. */
-@container basalt-stat-group (max-width: 259.9px) {
+@container basalt-grid (max-width: 259.9px) {
   .root {
     grid-template-columns: minmax(0, 1fr);
   }
@@ -56,13 +56,13 @@
   }
 }
 
-@container basalt-stat-group (min-width: 768px) {
+@container basalt-grid (min-width: 800px) {
   .root {
     grid-template-columns: repeat(var(--basalt-stat-group-cols-sm), minmax(0, 1fr));
   }
 }
 
-@container basalt-stat-group (min-width: 1200px) {
+@container basalt-grid (min-width: 1200px) {
   .root {
     grid-template-columns: repeat(var(--basalt-stat-group-cols-lg), minmax(0, 1fr));
   }
@@ -83,14 +83,14 @@
   padding-inline-start: var(--vx-space-stack-md);
 }
 
-@container basalt-stat-group (max-width: 767.9px) {
+@container basalt-grid (max-width: 799.9px) {
   .root[data-divided] > *:nth-child(2n + 1) {
     border-inline-start: 0;
     padding-inline-start: 0;
   }
 }
 
-@container basalt-stat-group (min-width: 768px) and (max-width: 1199.9px) {
+@container basalt-grid (min-width: 800px) and (max-width: 1199.9px) {
   .root[data-divided][data-sm-cols='2'] > *:nth-child(2n + 1),
   .root[data-divided][data-sm-cols='3'] > *:nth-child(3n + 1) {
     border-inline-start: 0;
@@ -98,7 +98,7 @@
   }
 }
 
-@container basalt-stat-group (min-width: 1200px) {
+@container basalt-grid (min-width: 1200px) {
   .root[data-divided][data-cols='2'] > *:nth-child(2n + 1),
   .root[data-divided][data-cols='3'] > *:nth-child(3n + 1),
   .root[data-divided][data-cols='4'] > *:nth-child(4n + 1),
@@ -107,48 +107,3 @@
     padding-inline-start: 0;
   }
 }
-
-/*
- * The pre-container-query fallback — Safari < 16, Chrome < 106, Firefox < 110. Verbatim the law
- * this file shipped before, keyed on the viewport, and reachable ONLY where `@container` is not.
- * A browser that cannot parse `container-type` also cannot parse the `@container` blocks above, so
- * the two sets are never live at once.
- */
-@supports not (container-type: inline-size) {
-  @media (min-width: 48em) {
-    .root {
-      grid-template-columns: repeat(var(--basalt-stat-group-cols-sm), minmax(0, 1fr));
-    }
-  }
-
-  @media (min-width: 75em) {
-    .root {
-      grid-template-columns: repeat(var(--basalt-stat-group-cols-lg), minmax(0, 1fr));
-    }
-  }
-
-  @media (max-width: 47.99375em) {
-    .root[data-divided] > *:nth-child(2n + 1) {
-      border-inline-start: 0;
-      padding-inline-start: 0;
-    }
-  }
-
-  @media (min-width: 48em) and (max-width: 74.99375em) {
-    .root[data-divided][data-sm-cols='2'] > *:nth-child(2n + 1),
-    .root[data-divided][data-sm-cols='3'] > *:nth-child(3n + 1) {
-      border-inline-start: 0;
-      padding-inline-start: 0;
-    }
-  }
-
-  @media (min-width: 75em) {
-    .root[data-divided][data-cols='2'] > *:nth-child(2n + 1),
-    .root[data-divided][data-cols='3'] > *:nth-child(3n + 1),
-    .root[data-divided][data-cols='4'] > *:nth-child(4n + 1),
-    .root[data-divided][data-cols='5'] > *:nth-child(5n + 1) {
-      border-inline-start: 0;
-      padding-inline-start: 0;
-    }
-  }
-}

package/src/dashboard/widget-grid.module.css

@@ -15,18 +15,19 @@
  * container. A span resolved against the viewport while the tracks follow the container is exactly
  * the phantom-track defect `WidgetGrid.Item`'s context clamp exists to prevent.
  *
- * The literals: px in `@container`, Mantine's own `em` in the `@supports not` fallback — same
- * boundary (768px / 1200px at the 16px initial font size), but `em` inside a `@container`
- * condition resolves against the CONTAINER's font-size, so px is the only spelling that cannot
- * drift. A condition cannot read a custom property either way, so the numbers are written; the
- * COUNTS are custom properties, set once per instance by the component — three hand-written
- * `repeat()` blocks would have to enumerate every `cols` value, and the whole point of this
- * primitive is that a consumer states one desktop number and basalt owns the rest.
+ * The literals are the container-class law, as in `stat-group.module.css`: the `sm` count opens
+ * at `wide` (800px); 1200px, where the full `cols` count opens, is the grid's own boundary above
+ * the class table's top step. px, never `em` (an `em` condition resolves against the container's
+ * font-size). A condition cannot read a custom property, so the numbers are written; the COUNTS
+ * are custom properties, set once per instance by the component — three hand-written `repeat()`
+ * blocks would have to enumerate every `cols` value, and the whole point of this primitive is that
+ * a consumer states one desktop number and basalt owns the rest. No viewport fallback, for the
+ * reason `stat-group.module.css` states: nothing that renders basalt lacks `@container`.
  */
 
 .container {
   container-type: inline-size;
-  container-name: basalt-widget-grid;
+  container-name: basalt-grid;
 }
 
 .root {
@@ -47,7 +48,7 @@
   min-width: 0;
 }
 
-@container basalt-widget-grid (min-width: 768px) {
+@container basalt-grid (min-width: 800px) {
   .root {
     grid-template-columns: repeat(var(--basalt-widget-grid-cols-sm), minmax(0, 1fr));
   }
@@ -57,7 +58,7 @@
   }
 }
 
-@container basalt-widget-grid (min-width: 1200px) {
+@container basalt-grid (min-width: 1200px) {
   .root {
     grid-template-columns: repeat(var(--basalt-widget-grid-cols-lg), minmax(0, 1fr));
   }
@@ -66,31 +67,3 @@
     grid-column: span var(--basalt-widget-grid-span-lg);
   }
 }
-
-/*
- * The pre-container-query fallback — Safari < 16, Chrome < 106, Firefox < 110. Verbatim the law
- * this file shipped before, keyed on the viewport, and reachable ONLY where `@container` is not: a
- * browser that cannot parse `container-type` cannot parse the blocks above either, so the two sets
- * are never live at once.
- */
-@supports not (container-type: inline-size) {
-  @media (min-width: 48em) {
-    .root {
-      grid-template-columns: repeat(var(--basalt-widget-grid-cols-sm), minmax(0, 1fr));
-    }
-
-    .item {
-      grid-column: span var(--basalt-widget-grid-span-sm);
-    }
-  }
-
-  @media (min-width: 75em) {
-    .root {
-      grid-template-columns: repeat(var(--basalt-widget-grid-cols-lg), minmax(0, 1fr));
-    }
-
-    .item {
-      grid-column: span var(--basalt-widget-grid-span-lg);
-    }
-  }
-}