basalt-ui 1.41.0 → 2.0.0

package/src/charts/types.ts

@@ -0,0 +1,242 @@
+/**
+ * The public prop vocabulary of `basalt-ui/charts` (`docs/V2-SPEC.md` § 9). React-free and
+ * engine-light: the only engine type named here is the mark array `marks` returns.
+ */
+import type { StoredChartSpec } from '@tanstack/charts/types/core'
+import type { BasaltProps } from '../common/props'
+import type { ContainerClass } from '../tokens/size-classes'
+import type { CurveName } from './curves'
+
+/** What `x` may return. The value type picks the x scale (§ 9.4): `Date` → time, `number` → linear,
+ * `string` → point (lines) or band (bars). */
+export type ChartX = Date | number | string
+
+/**
+ * A plotted series — the single source of truth for color, dash, legend entry and tooltip row. The
+ * legend and the tooltip are derived from it, never authored beside it.
+ */
+export type ChartSeries<T> = {
+  key: string
+  label: string
+  /** A `VX.*` ref or a consumer series token (`var(--…)`), never a literal. */
+  color: string
+  /** `null` is an ABSENCE, never a zero: a gap in the line, no tooltip row, out of the domain. A
+   * series whose `getValue` is always `null` is a legend-only entry (a zone or reference key). */
+  getValue: (d: T) => number | null
+  /** The legend swatch shape. Default: the kind's own mark (`line` in `Lines`, `bar` in `Bars`). */
+  mark?: 'line' | 'bar' | 'area'
+  /** Default `'solid'`; `'dashed'` is `VX.dashArray` on the line, the legend and the tooltip. */
+  dash?: 'solid' | 'dashed'
+  /** Interpolation between points. Default `'monotone'`. A piecewise-constant quantity (a price
+   * tier, a config value) is a step: a smoothed curve draws values that never existed. */
+  curve?: CurveName
+  strokeWidth?: number
+  /** Dims the plotted stroke (a faint companion line). Strokes only. */
+  strokeOpacity?: number
+  /** Bars and areas. */
+  fillOpacity?: number
+  /** `Lines`: a soft gradient fill under the line — `true` in the series color, or a color ref. */
+  area?: boolean | string
+  /** Which y axis the series is measured against. `'right'` needs the chart's `y2`. */
+  axis?: 'left' | 'right'
+  /** Legend grouping: series → overlay → reference. Default `'series'`. */
+  role?: 'series' | 'overlay' | 'reference'
+  /** `false` keeps it out of the legend (a companion line folded under `parent`). Default `true`. */
+  legend?: boolean
+  /** `false` draws and legends it but never lists it as a tooltip row. Default `true`. */
+  tooltip?: boolean
+  /** A companion (an MA line) names its parent, so a legend toggle and hover keep the pair. */
+  parent?: string
+  /** A short qualifier after the label in the legend and the tooltip row, in muted text. */
+  note?: string
+  /** Per-series tooltip value format; receives the datum so a row can read more than the value. */
+  formatValue?: (v: number, d: T) => string
+  /** A marker at a point (a PR star, a status dot); `null` for none. */
+  getMarker?: (d: T) => { color?: string; r?: number; fillOpacity?: number; ring?: boolean } | null
+}
+
+/** One y axis. */
+export type AxisConfig<T> = {
+  /**
+   * `'auto'` (default) derives the domain from the VISIBLE series plus this axis' finite zone and
+   * reference-line bounds; a tuple fixes it; a function computes it from the data and the visible
+   * series (so a legend toggle can shrink a stacked domain).
+   */
+  domain?:
+    | readonly [number, number]
+    | 'auto'
+    | ((data: readonly T[], visible: readonly ChartSeries<T>[]) => readonly [number, number])
+  /** When `'auto'`: the raw upper bound is at least this; padding applies after. */
+  autoMaxFloor?: number
+  /** When `'auto'`: the lower bound is at most this. Default `0` (a zero baseline); `Infinity` pads
+   * down from the data minimum instead. Ignored on a log axis. */
+  autoMinCeil?: number
+  /** When `'auto'`: padding multiplier away from the data. Default `1.1`. */
+  autoPad?: number
+  /** A tick count, or the exact tick values. Default: one per ~48px of plot height, ≤ 5. */
+  ticks?: number | readonly number[]
+  /** Tick and tooltip formatter. Default: compact numbers (`12.5k`). */
+  format?: (v: number) => string
+  /** Horizontal grid rules. Default: on for `y`, off for `y2`. */
+  grid?: boolean
+  /** Round the domain outward to nice ticks. Default `false` (a fixed domain stays fixed). */
+  nice?: boolean
+  /** Default `'linear'`. A log axis floors at the smallest positive visible value. */
+  scale?: 'linear' | 'log'
+}
+
+/** A horizontal band on one y axis. `±Infinity` reaches the plot edge. */
+export type ZoneSpec = {
+  from: number
+  to: number
+  fill: string
+  axisSide?: 'left' | 'right'
+}
+
+/**
+ * A vertical band between two x values. An omitted bound is the plot's own edge. `'edge'` widens a
+ * present bound by half a sample step, so a band covers its terminal samples in full (a night
+ * from one hour to another, both hours included).
+ */
+export type XZoneSpec<X extends ChartX = ChartX> = {
+  from?: X
+  to?: X
+  fill: string
+  align?: 'center' | 'edge'
+}
+
+/** A horizontal reference line — annotation only, no domain role beyond staying inside the plot. */
+export type RefLine = {
+  value: number
+  color: string
+  dashed?: boolean
+  axis?: 'left' | 'right'
+}
+
+/** A fill between the line and a value, on one side of it, tracking the line. */
+export type Threshold = {
+  value: number
+  side: 'above' | 'below'
+  fill: string
+}
+
+/** How a sibling chart's cursor value lands on this chart's x values. Strings always match exactly. */
+export type CursorResolution = 'exact' | 'nearest' | 'leading'
+
+/** One tooltip row, as data. */
+export type ChartTooltipRow = {
+  label: string
+  value: string
+  /** The row swatch; omitted, the row has none. */
+  color?: string
+}
+
+export type ChartTooltipConfig<T, X extends ChartX = ChartX> = {
+  /** The tooltip title. Default: the x value through `formatX`'s long form (a date reads
+   * `Mon Sep 1 2026`). */
+  formatHeader?: (x: X, d: T) => string
+  /** Rows after the per-series rows (a total, a zone badge, a context line). `visible`/`hidden` are
+   * the legend's split, so a row never names a series the plot no longer draws. */
+  rows?: (
+    d: T,
+    ctx: { visible: readonly ChartSeries<T>[]; hidden: readonly ChartSeries<T>[] },
+  ) => readonly ChartTooltipRow[]
+  /** Show this chart's tooltip while it FOLLOWS a sibling's cursor. Default `false`: only the chart
+   * under the pointer or keyboard focus shows a tooltip and a live region. */
+  onFollow?: boolean
+}
+
+export type ChartLegendConfig = {
+  /** Default `'bottom'`. `'header'` draws the legend at the top of the chart body, spaced as the
+   * enclosing `ChartCard`'s header legend row (in the chart's own markup, so it is in the server
+   * HTML and the header never grows); outside a card it is `'top'`. */
+  placement?: 'top' | 'bottom' | 'header'
+  /** Visually separate roles: series | overlay | reference. */
+  groups?: boolean
+  /** Clicking an entry hides that series. Default: on whenever there are two or more entries. */
+  toggle?: boolean
+}
+
+/** A height per container class, `base` below `regular`. A plain number is fixed. */
+export type ResponsiveChartHeight = {
+  base: number
+  regular?: number
+  wide?: number
+}
+
+/** The three "nothing to draw" states, pending → error → empty. */
+export type ChartState = {
+  pending?: boolean
+  /** Truthy = the query failed; an `Error`'s message is the label. */
+  error?: unknown
+  /** `true`, or the empty label itself. */
+  empty?: boolean | string
+}
+
+/** A row of `plot.rows(key)`: one per datum, `y: null` kept as a gap. */
+export type PlotRow<T, X extends ChartX = ChartX> = {
+  x: X
+  y: number | null
+  series: string
+  datum: T
+}
+
+/** What `CartesianChart`'s `marks` receives. */
+export type PlotContext<T, X extends ChartX = ChartX> = {
+  /** One row per datum for a VISIBLE series; a hidden series returns `[]`, so a legend toggle hides
+   * the mark, its tooltip row and its share of the auto domain together. */
+  rows: (key: string) => PlotRow<T, X>[]
+  /** `series` minus what the legend toggled off. */
+  visible: readonly ChartSeries<T>[]
+  /** The legend entry under the pointer, for emphasis; `null` when none. */
+  highlighted: string | null
+  /** The measured container class (`regular` on the server). */
+  containerClass: ContainerClass
+  /** The chart's size in px, for a kind that lays out labels against the plot. */
+  width: number
+  height: number
+  /** Bind a mark to the right axis with `yScale: plot.y2` (present only with a `y2` config). */
+  y2: 'y2' | undefined
+  /** The resolved y domain (and the right axis', with `y2`): basalt's, never the engine's. */
+  yDomain: readonly [number, number]
+  y2Domain: readonly [number, number] | undefined
+}
+
+/** The marks a `marks` function returns: TanStack marks from the allowed `@tanstack/charts/*`
+ * subpaths (V2-SPEC § 9.8). basalt re-exports none. */
+export type ChartMarks = StoredChartSpec['marks']
+
+export type CartesianChartProps<T, X extends ChartX = ChartX> = BasaltProps & {
+  /** The accessible name. Required: a chart without one is an unlabeled image. */
+  ariaLabel: string
+  data: readonly T[]
+  x: (d: T) => X
+  series: readonly ChartSeries<T>[]
+  /** The plot's marks. Draw `plot.rows(key)` / `plot.visible`, never `series` directly. */
+  marks: (plot: PlotContext<T, X>) => ChartMarks
+  y?: AxisConfig<T>
+  /** A right axis; series with `axis: 'right'` and marks bound to `plot.y2` read it. */
+  y2?: AxisConfig<T>
+  /** A tick count, or the exact x tick values. Default: by container class. */
+  xTicks?: number | readonly X[]
+  /** Tick label for an x value. Default: `DD.MM` for dates, compact numbers, strings verbatim. */
+  formatX?: (x: X) => string
+  zones?: readonly ZoneSpec[]
+  xZones?: readonly XZoneSpec<X>[]
+  refLines?: readonly RefLine[]
+  /** `false` hides the legend. */
+  legend?: ChartLegendConfig | false
+  /** Default: the height law (measured width × class ratio, 160–420px, ≤ 45vh on touch). */
+  height?: number | ResponsiveChartHeight
+  state?: ChartState
+  /** Joins a named cursor group instead of the page-shared default. */
+  cursorGroup?: string
+  /** Default `'nearest'`. `'leading'` for a series keyed by a bucket's leading edge (a weekly
+   * value keyed by its Monday). */
+  cursorResolution?: CursorResolution
+  tooltip?: ChartTooltipConfig<T, X> | false
+}
+
+/** The x channel of a `plot.rows()` row, as an accessor (a field name does not type-check against a
+ * generic `X`). */
+export const rowX = <T, X extends ChartX>(row: PlotRow<T, X>): X => row.x

package/src/cli/audit-allows.ts

@@ -75,19 +75,10 @@ function diagnosticCounts(
 }
 
 /**
- * The oxlint half of the audit: what each plugin-rule annotation still suppresses.
- *
- * The `check-theme` half proves a verdict by re-running `checkSource` with one occurrence
- * neutralized. The `error`-severity design rules do not live there — they live in the oxlint
- * plugin — so the audit declined to judge them and printed "not a check-theme kind". In a
- * chart-heavy consumer that was 8 of 8 and 11 of 14: a CI gate that exited 0 having inspected
- * nothing. The method generalizes exactly, one level over: neutralize the annotation, re-run
- * oxlint over that file, and the findings that appear are what it covers.
- *
- * oxlint has no stdin mode, so a probe has to be a real file. It is written BESIDE the original —
- * same directory, so the same `.oxlintrc.json`, the same `charts/` path segment, the same nearest
- * `package.json` — and removed in a `finally`. Returns null when oxlint cannot be run at all, which
- * is a "cannot judge", never a "dead".
+ * The oxlint half of the audit: what each plugin-rule annotation still suppresses. The annotation is
+ * neutralized and oxlint re-run over that file. oxlint has no stdin mode, so the probe is a real file
+ * written BESIDE the original (same `.oxlintrc.json`, path segments and nearest `package.json`) and
+ * removed in a `finally`. Returns null when oxlint cannot run: "cannot judge", never "dead".
  */
 function probePluginRules(
   cwd: string,
@@ -164,23 +155,10 @@ function probePluginRules(
 
 /**
  * `check-theme --audit-allows` — list every active waiver and prove, per waiver, whether it still
- * suppresses anything.
- *
- * The accountability release shipped `theme-allow-unscoped`, which reports a waiver that names no
- * rule — but a waiver that is perfectly well written and covers a finding that no longer exists is
- * invisible to it, and to everything else. Two consumers found five of those by hand, by editing
- * the token out and re-running the guard. This is that method, automated: for each annotation the
- * file is re-checked with THAT occurrence neutralized, and the findings that appear are exactly
- * what it suppresses. Nothing is inferred from the annotation's text, so the audit cannot disagree
- * with the scan — it IS the scan, run twice.
- *
- * `basalt.exemptRules` entries are audited the same way, one pattern at a time. That also answers
- * the question the key could never answer for itself: a pattern that matches no scanned file (a
- * real relative path, say, where the matcher takes whole path SEGMENTS) suppresses nothing and is
- * reported as dead rather than passing silently.
- *
- * Exit 1 when anything is dead, so it can be wired into CI as a gate. A waiver nobody re-checks is
- * how a rule quietly stops applying to the file that needed the exception most.
+ * suppresses anything: the file is re-checked with THAT occurrence neutralized and the findings that
+ * appear are exactly what it suppresses, so the audit cannot disagree with the scan. `exemptRules`
+ * entries are audited one pattern at a time; a pattern matching no scanned file is reported dead.
+ * Exits 1 when anything is dead, so it can gate CI.
  */
 export function auditAllows(
   cwd: string,

package/src/cli/config.ts

@@ -13,7 +13,7 @@ export type BasaltConfig = {
    * off every guard kind whose remedy is a Mantine component, a Mantine prop or the React theme
    * factory, leaving the color and typography kinds live. Default: `'mantine'`.
    *
-   * Deliberately not inferred from a missing `@mantine/core`: silencing 17 rules (the live count is
+   * Deliberately not inferred from a missing `@mantine/core`: silencing the Mantine-coupled rules (the live count is
    * `TOKENS_ONLY_DISABLED_KINDS.size`, which the check-theme banner prints) is a decision, and
    * a repo that keeps Mantine in a workspace package would otherwise switch off half its own guard
    * without saying so. `basalt-ui doctor` detects the shape and tells you to set this.
@@ -93,26 +93,12 @@ export type BasaltConfig = {
    * `inline-display` check.
    */
   inlineDisplay?: boolean
-  /**
-   * Flag raw `<AxisLeft>` / `<AxisBottom>` / `<AxisRight>` visx JSX inside chart files (a path
-   * containing `/charts/`) — these bypass the `AxisLeftNumeric` / `AxisBottomDate` /
-   * `AxisRightNumeric` primitives that carry the theme tokens + smart ticks. The legitimate wrapper
-   * (`Axes.tsx`, which IS the primitive) is exempt. Default: `true` (ON). Set `false` to disable the
-   * `raw-visx-axis` check.
-   */
-  rawVisxAxis?: boolean
   /**
    * Flag a hardcoded duration/spring/ease literal inline in a `transition={{...}}` prop — route it
    * through `MOTION_DURATION` / `MOTION_SPRING` / `MOTION_EASE_STANDARD` instead. Default: `true`
    * (ON). Set `false` to disable the `raw-motion-value` check.
    */
   rawMotionValue?: boolean
-  /**
-   * Flag a chart entry-point JSX tag (`MultiLine`/`Bars`/`Donut`/`DualPanel`/`Heatmap`/`ZonedLine`/
-   * `StackedArea`/`LineSparkline`/`BarSparkline`) missing an `ariaLabel` prop. Default: `true`
-   * (ON). Set `false` to disable the `chart-missing-aria-label` check.
-   */
-  chartMissingAriaLabel?: boolean
   /**
    * Flag a raw lowercase `<input>`/`<select>`/`<textarea>` JSX element — it bypasses the entire
    * theme, not just the iOS font-size floor. Use the Mantine equivalents (`TextInput`,
@@ -133,21 +119,14 @@ export type BasaltConfig = {
    */
   seriesModulePath?: string
   /**
-   * Per-rule, per-path exemptions — complements whole-file `exempt` (which skips ALL rules for a
-   * file) and the hardcoded per-kind `appliesTo` scoping (e.g. `raw-visx-axis` → chart files
-   * only). Each value is a list of patterns matched against a finding's relative path. A pattern
-   * may be a whole path segment (`'agent'` matches `src/agent/x.tsx`, not `src/agenting.ts`), a
-   * relative path (`'public/site.webmanifest'`), a directory prefix, or a glob — `*` stops at `/`,
-   * `**` does not, and a slash-free glob also matches the basename, so `'*.module.css'` works.
-   * A trailing `/` is stripped. An entry that suppresses nothing is reported, and
-   * `check-theme --audit-allows` exits 1 on it. Default: `{}` (no exemptions).
+   * Per-rule, per-path exemptions, complementing whole-file `exempt`. A pattern is matched against a
+   * finding's relative path: a path segment (`'agent'` matches `src/agent/x.tsx`, not
+   * `src/agenting.ts`), a relative path, a directory prefix, or a glob (`*` stops at `/`, `**` does
+   * not; a slash-free glob also matches the basename). An entry that suppresses nothing is reported
+   * and `check-theme --audit-allows` exits 1 on it. Default: `{}`.
    *
-   * Two forms per kind. The bare array is paths only. The object form adds the REASON, which is
-   * the half a `theme-allow` carries and this key could not: JSON has no comments, so a
-   * `.webmanifest` / `.json` finding's only escape is this key, and it was un-reviewable by
-   * construction — the rationale ended up in a CLAUDE.md paragraph nobody reads next to the diff.
-   * `check-theme --audit-allows` prints the reason (or names its absence) beside what the entry
-   * still suppresses. The array form stays supported and unchanged; nothing here is required.
+   * The bare array is paths only; the object form adds the REASON (JSON has no comments, so a
+   * `.webmanifest` finding's only escape is this key), which `--audit-allows` prints.
    *
    * @example
    * { exemptRules: { 'inline-display': ['agent'] } } // inline-display never fires under src/agent/**
@@ -157,22 +136,14 @@ export type BasaltConfig = {
    */
   exemptRules?: Partial<Record<GuardKind, ExemptRuleEntry>>
   /**
-   * Declares an intentional `ai` package major-version skew across workspace packages, exempting
-   * `doctor`'s `ai-major-parity` hard check. The value IS the reason — a bare `true` is rejected,
-   * because the whole point of this key is that the pairing is written down, not just switched off.
-   * A written declaration is the pin `basalt/ai-sdk-major`'s own comment notes is otherwise missing.
-   *
-   * Semantics: absent (or present but not a non-empty string) → the skew still hard-fails exactly as
-   * without this key. A non-empty string with a skew present → `doctor` passes, echoing both the
-   * skew and this reason. A non-empty string with NO skew present → `doctor` warns that the
-   * exemption is stale and can be deleted (an exemption nobody re-checks is how a real, later skew
-   * slips through unnoticed).
+   * Declares an intentional `ai` package major-version skew, exempting `doctor`'s `ai-major-parity`
+   * hard check. The value IS the reason; a bare `true` is rejected. Absent or empty: the skew still
+   * fails. A reason with a skew: `doctor` passes and echoes both. A reason with NO skew: `doctor`
+   * warns the exemption is stale.
    *
    * @example
-   * // apps/api streams on ai@5; apps/dashboard parses on ai@7; a producer-side TransformStream
-   * // neutralizes the one enum value that differs between the two majors.
-   * { aiMajorSkewReason: 'apps/api pinned to ai@5, apps/dashboard on ai@7 — the skew is neutralized '
-   *   + 'by a producer-side TransformStream in apps/api/src/stream-transform.ts' }
+   * { aiMajorSkewReason: 'apps/api pinned to ai@5, apps/dashboard on ai@7 — neutralized by a '
+   *   + 'producer-side TransformStream in apps/api/src/stream-transform.ts' }
    */
   aiMajorSkewReason?: string
 }