basalt-ui 1.40.3 → 2.0.0

package/src/charts/kinds/ZonedLine.tsx

@@ -1,301 +0,0 @@
-import { AreaClosed, LinePath } from '@visx/shape'
-import { Threshold } from '@visx/threshold'
-import { memo, useMemo } from 'react'
-import { assertRequiredProps } from '../../common/validate'
-import type { BasaltProps } from '../../common/props'
-import type { CursorResolution } from '../cursor/resolve'
-import { AreaGradient, areaFillUrl } from '../primitives/AreaGradient'
-import type { CartesianTooltipConfig, AxisConfig, PlotContext } from '../primitives/CartesianChart'
-import { CartesianChart } from '../primitives/CartesianChart'
-import type { ResponsiveChartHeight } from '../primitives/ChartFrame'
-import type { XZoneSpec } from '../primitives/XZoneRects'
-import type { ZoneSpec } from '../primitives/ZoneRects'
-import type { ChartState } from '../primitives/ChartPending'
-import { curveFor, definedOn, LINE_OVERLAY_STROKE_WIDTH, toPlotPoint } from '../series'
-import type { ChartLegendConfig, ChartSeries } from '../series'
-import { VX } from '../../tokens'
-
-/** Semi-transparent fill above (or below) a threshold value, tracking the line. */
-export type ZonedLineThreshold = {
-  value: number
-  side: 'above' | 'below'
-  fill: string
-}
-
-/** Dashed horizontal reference line — visual annotation only, no fill. */
-export type ZonedLineRefLine = {
-  value: number
-  color: string
-  /** Solid by default; set true for a dashed line. */
-  dashed?: boolean
-}
-
-export type ZonedLineProps<T> = BasaltProps & {
-  data: T[]
-  /** Height in px, or one per size step (`{ base, sm?, md?, lg? }`). Default 240. Forwarded
-   * unchanged; `ChartFrameProps.height` owns the law — steps resolve off the MEASURED width. */
-  height?: number | ResponsiveChartHeight
-  chartId: string
-  /** Extracts the x-axis category (date string) from a data point. */
-  getX: (d: T) => string
-  /** Single-series line — the sole source of truth for color, dash, legend, and tooltip row. Pass
-   * exactly one entry (kept as an array for parity with the other kinds and so `CartesianChart` /
-   * `deriveLegend` / `deriveTooltipRows` can consume it directly). */
-  series: ChartSeries<T>[]
-  /** Y-axis. Collapses the old `yDomain` / `yAutoMaxFloor` / `yAutoMinCeil` / `yAutoPad` /
-   * `numTicksY` / `formatYTick` prop soup into one object. */
-  y?: AxisConfig<T>
-  zones?: ZoneSpec[]
-  /** Vertical x-range overlays (time windows), rendered behind the line. Bounds are `getX`
-   * domain keys. */
-  xZones?: XZoneSpec[]
-  thresholds?: ZonedLineThreshold[]
-  refLines?: ZonedLineRefLine[]
-  /** Exact number of x ticks. Default: as many as fit. Ignored when `xTickValues` is set. */
-  xTicks?: number
-  /** Which domain keys get a tick, from the full key list and the resolved plot width. Takes
-   * precedence over `xTicks` — see `CartesianChartProps.xTickValues` for why a count is not
-   * always enough. */
-  xTickValues?: (keys: readonly string[], xMax: number) => readonly string[]
-  /** X tick label formatter. Default `fmtAxisDate` (DD.MM). */
-  formatX?: (key: string) => string
-  /** Tilt the x tick labels 45° or 90°, or `0` to opt out of the phone tier's auto-rotation —
-   * see `CartesianChartProps.xLabelRotate`. */
-  xLabelRotate?: 0 | 45 | 90
-  /**
-   * How a sibling chart's broadcast cursor key resolves against this chart's points. Default
-   * `'nearest'`. Pass `'leading'` when `getX` returns a bucket's leading edge (a weekly series
-   * keyed by its Monday) — see `CursorResolution`.
-   */
-  cursorResolution?: CursorResolution
-  /** Tooltip config — `label` for a right-aligned header badge (e.g. zone name with zone color),
-   * `extraRows` for rows appended after the derived row. `false` disables the tooltip entirely. */
-  tooltip?: CartesianTooltipConfig<T> | false
-  /**
-   * Opt-in soft gradient fill under the line. Pass a color token to tint the area
-   * with that hue — the modern single-hue look. `true` falls back to the series color. Off by
-   * default (a neutral fill under the neutral line just reads as grey haze). Strength is global
-   * via `--vx-area-top` / `--vx-area-bottom` (tunable in the dev theme lab).
-   */
-  areaFill?: string | boolean
-  /** Legend config forwarded to `CartesianChart`; `false` disables the legend (sparkline escape).
-   * Default `{ placement: 'bottom' }`. */
-  legend?: ChartLegendConfig | false
-  /** Accessible text alternative, forwarded to `CartesianChart` as `aria-label` (+ `role="group"`). */
-  ariaLabel?: string
-  /** Forwarded to `CartesianChart` — see `ChartPending`'s JSDoc for the three-state rationale. */
-  isPending?: boolean
-  /** The three "nothing to draw" states in one prop — pending → error → empty. See
-   * `ChartState`; `isPending` stays a supported alias for `state={{ pending: true }}`. */
-  state?: ChartState
-}
-
-type Pt<T> = T & { __y: number | null }
-
-/**
- * Every row, in x order, with `__y: null` where the series reports no value. The null row STAYS in
- * the array — see `MultiLine`'s `seriesPoints`: dropping it makes `LinePath`/`AreaClosed`/
- * `Threshold` join straight across a coverage hole, drawing a measurement that was never taken.
- * The shared `defined` guard below is what turns it back into a gap.
- */
-function linePoints<T>(series: ChartSeries<T> | undefined, data: readonly T[]): Pt<T>[] {
-  if (!series) return []
-  return data.map((d) => Object.assign({}, d, { __y: toPlotPoint(series.getValue(d)) }) as Pt<T>)
-}
-
-/**
- * Single-series line chart with zone backgrounds, threshold fills, an optional area gradient,
- * reference lines, and a shared-cursor tooltip. Covers the line-with-zones pattern. Does NOT
- * handle dual-panel charts (keep those bespoke).
- *
- * Composes `CartesianChart` for measuring, scales, grid, zones/x-zones, axes, the shared cursor,
- * and the derived tooltip — this kind draws ONLY the marks (thresholds, area fill, and the line).
- * Single-series, so the legend is optional in practice but present by default.
- *
- * X-axis is built from the full `data` array so the calendar is preserved even when the series has
- * nulls; the line, the area fill and the threshold fills all BREAK at a null point, leaving a real
- * gap rather than interpolating across it.
- */
-function ZonedLineInner<T>(props: ZonedLineProps<T>) {
-  // F-ERR-1: name the component and the prop. Without this a missing accessor surfaces
-  // from inside visx as `undefined is not a function`, which `BasaltErrorBoundary`
-  // swallows into a blank subtree that names nothing.
-  assertRequiredProps('ZonedLine', props, ['data', 'getX', 'series'])
-  const {
-    data,
-    chartId,
-    getX,
-    series,
-    y,
-    zones,
-    xZones,
-    thresholds,
-    refLines,
-    xTicks,
-    xTickValues,
-    formatX,
-    xLabelRotate,
-    cursorResolution,
-    tooltip,
-    areaFill,
-    height,
-    legend,
-    ariaLabel,
-    isPending,
-    state,
-    className,
-    style,
-  } = props
-
-  // Default the line overlay to the redesign's 1.9px stroke (docs/DESIGN-SPEC.md §5) — applied
-  // once here so the plotted line, the derived legend swatch, and the derived tooltip row agree.
-  const styledSeries = useMemo<ChartSeries<T>[]>(
-    () =>
-      series.map((s) => ({
-        ...s,
-        strokeWidth: s.strokeWidth ?? LINE_OVERLAY_STROKE_WIDTH,
-      })),
-    [series],
-  )
-
-  return (
-    <CartesianChart
-      data={data}
-      chartId={chartId}
-      getX={getX}
-      series={styledSeries}
-      {...(y !== undefined && { y })}
-      {...(zones !== undefined && { zones })}
-      {...(xZones !== undefined && { xZones })}
-      {...(refLines !== undefined && { refLines })}
-      {...(xTicks !== undefined && { xTicks })}
-      {...(xTickValues !== undefined && { xTickValues })}
-      {...(formatX !== undefined && { formatX })}
-      {...(xLabelRotate !== undefined && { xLabelRotate })}
-      {...(cursorResolution !== undefined && { cursorResolution })}
-      {...(tooltip !== undefined && { tooltip })}
-      {...(height !== undefined && { height })}
-      {...(legend !== undefined && { legend })}
-      {...(ariaLabel !== undefined && { ariaLabel })}
-      {...(isPending !== undefined && { isPending })}
-      {...(state !== undefined && { state })}
-      {...(className !== undefined && { className })}
-      {...(style !== undefined && { style })}
-    >
-      {(ctx: PlotContext<T>) => (
-        <ZonedLineMarks
-          getX={getX}
-          chartId={chartId}
-          thresholds={thresholds ?? []}
-          areaFill={areaFill}
-          ctx={ctx}
-        />
-      )}
-    </CartesianChart>
-  )
-}
-
-/** Draws the threshold fills, the optional area gradient, and the line for the (single) visible
- * series. Hidden via the legend toggle draws nothing, same as every other kind. */
-function ZonedLineMarks<T>({
-  getX,
-  chartId,
-  thresholds,
-  areaFill,
-  ctx,
-}: {
-  getX: (d: T) => string
-  chartId: string
-  thresholds: ZonedLineThreshold[]
-  areaFill: string | boolean | undefined
-  ctx: PlotContext<T>
-}) {
-  const { data, visible, xScale, yScale, yMax } = ctx
-  const primary = visible[0]
-  // Memoized: the shared cursor re-renders every chart on every pointer frame, and this both
-  // walks the full series and clones an object per point.
-  const pts = useMemo(() => linePoints(primary, data), [primary, data])
-
-  // ONE guard for all three shapes below, covering two absences. A null value is a documented GAP
-  // (`ChartSeries.getValue`), and a non-positive value on a log axis maps to NaN via `yScale` —
-  // without `defined` the first is drawn as an interpolated straight line across a coverage hole
-  // and the second emits a NaN path command, which per SVG error handling blanks the ENTIRE path
-  // from that point on.
-  const defined = definedOn(yScale)
-  // ONE curve for all three shapes: the threshold band, the area fill and the line are the SAME
-  // series drawn three ways, so a step line over a monotone fill would be two different readings
-  // of one measurement.
-  const curve = curveFor(primary?.curve)
-  // Never reached with a null `__y`: d3's line/area generators call the position accessors only
-  // for points `defined` accepted. The `NaN` floor is a type-level one, and it can never paint at
-  // zero the way a `?? 0` would.
-  const yOf = (d: Pt<T>) => yScale(d.__y ?? NaN)
-
-  // Area is opt-in: pass a color token to get a cohesive single-hue fill under the line.
-  // (A neutral fill under the neutral line just reads as grey haze, so there is no default-on.)
-  const showArea = areaFill !== undefined && areaFill !== false
-  const areaColor = typeof areaFill === 'string' ? areaFill : primary?.color
-  const areaId = `${chartId}-area`
-
-  return (
-    <>
-      {thresholds.map((t, i) => (
-        <Threshold<Pt<T>>
-          key={`thr-${i}`}
-          id={`${chartId}-thr-${i}`}
-          data={pts}
-          defined={defined}
-          x={(d) => xScale(getX(d)) ?? 0}
-          y0={() => yScale(t.value)}
-          y1={yOf}
-          clipAboveTo={0}
-          clipBelowTo={yMax}
-          curve={curve}
-          belowAreaProps={{ fill: t.side === 'above' ? t.fill : 'transparent' }}
-          aboveAreaProps={{ fill: t.side === 'below' ? t.fill : 'transparent' }}
-        />
-      ))}
-
-      {showArea && areaColor !== undefined && (
-        <>
-          <defs>
-            <AreaGradient id={areaId} color={areaColor} />
-          </defs>
-          <AreaClosed<Pt<T>>
-            data={pts}
-            defined={defined}
-            x={(d) => xScale(getX(d)) ?? 0}
-            y={yOf}
-            yScale={yScale}
-            curve={curve}
-            fill={areaFillUrl(areaId)}
-          />
-        </>
-      )}
-
-      {primary && (
-        <LinePath<Pt<T>>
-          data={pts}
-          defined={defined}
-          x={(d) => xScale(getX(d)) ?? 0}
-          y={yOf}
-          stroke={primary.color}
-          strokeWidth={primary.strokeWidth ?? LINE_OVERLAY_STROKE_WIDTH}
-          strokeDasharray={primary.dash === 'dashed' ? VX.dashArray : undefined}
-          strokeOpacity={primary.strokeOpacity ?? 1}
-          curve={curve}
-        />
-      )}
-    </>
-  )
-}
-
-/**
- * Hand-memoized: React Compiler does not process the shipped dist, so the hot ZonedLine kind is
- * wrapped in `React.memo` to retain the auto-memoization it had as source (parity with Bars).
- */
-const ZonedLineMemo = memo(ZonedLineInner)
-// Without it every kind reads as `Memo` in React DevTools (audit A16) — a profiler flame
-// graph of nine identically-named nodes names nothing.
-ZonedLineMemo.displayName = 'ZonedLine'
-export const ZonedLine = ZonedLineMemo as typeof ZonedLineInner

package/src/charts/kinds/band-chrome.tsx

@@ -1,91 +0,0 @@
-import type { ReactNode } from 'react'
-import type { BandPlot, BandTooltipConfig } from '../hooks/useBandPlot'
-import { AxisBottomDate } from '../primitives/Axes'
-import { ChartTooltipFloat, TooltipBody, TooltipHeader } from '../primitives/ChartTooltip'
-import { cursorSliderProps, HoverOverlay } from '../primitives/HoverOverlay'
-
-/**
- * The chrome `BandStrip` and `MirroredBars` share around their own marks — the slot axis, the
- * keyboard/pointer overlay and the tooltip shell — so the two `useBandPlot` kinds cannot drift in
- * any of them. Internal; neither is exported from a barrel.
- *
- * theme-allow-file hand-rolled-plot — the slot axis and overlay of the two declared banded
- * exceptions (`BandStrip`, `MirroredBars`), which carry the same waiver for the same reason.
- */
-
-/** A 0..1 share. Non-finite (a 0/0 fold count) reads as "nothing is absent" — the conservative
- * end, since the alternative is a band that does not render at all. */
-export function clampFraction(value: number | undefined): number {
-  if (value === undefined || !Number.isFinite(value)) return 0
-  return Math.min(Math.max(value, 0), 1)
-}
-
-/** The slot axis under a `height`-tall band row, plus the hover/keyboard overlay over it. */
-export function BandAxisOverlay<T>({
-  band,
-  height,
-  getX,
-  formatX,
-  ariaLabel,
-}: {
-  band: BandPlot<T>
-  height: number
-  getX: (d: T) => string
-  formatX: (key: string) => string
-  ariaLabel: string | undefined
-}) {
-  return (
-    <>
-      <AxisBottomDate
-        top={height}
-        scale={band.scale}
-        tickValues={band.tickValues}
-        tickFormat={(v) => formatX(String(v))}
-        anchorTerminals={band.xAnchorTerminals}
-        {...(band.xWrapWidth !== undefined && { wrapWidth: band.xWrapWidth })}
-      />
-      <HoverOverlay
-        width={band.plotWidth}
-        height={height}
-        {...cursorSliderProps({ cursor: band.cursor, data: band.bands, getX, formatX, ariaLabel })}
-      />
-    </>
-  )
-}
-
-/** The tooltip shell: header (+ badge), the consumer's prepended rows, the kind's own derived
- * `children` rows, the consumer's extra rows. Renders nothing off-hover or with `tooltip: false`. */
-export function BandTooltip<T>({
-  band,
-  tooltip,
-  getX,
-  hidden,
-  children,
-}: {
-  band: BandPlot<T>
-  tooltip: BandTooltipConfig<T> | false | undefined
-  getX: (d: T) => string
-  hidden: ReadonlySet<string>
-  children: ReactNode
-}) {
-  const { point } = band
-  if (!band.showTooltip || point === null) return null
-  const cfg = tooltip === false ? undefined : tooltip
-  const badge = cfg?.label === undefined ? null : cfg.label(point)
-  return (
-    <ChartTooltipFloat anchor={band.tooltipAnchor} ariaLive={band.ariaLive}>
-      <TooltipHeader
-        date={getX(point)}
-        {...(cfg?.formatHeader !== undefined && {
-          format: (key: string) => cfg.formatHeader?.(key, point) ?? key,
-        })}
-        {...(badge !== null && { label: badge.text, labelColor: badge.color })}
-      />
-      <TooltipBody>
-        {cfg?.prependRows?.(point, { hidden })}
-        {children}
-        {cfg?.extraRows?.(point, { hidden })}
-      </TooltipBody>
-    </ChartTooltipFloat>
-  )
-}

package/src/charts/kinds/donut-layout.ts

@@ -1,82 +0,0 @@
-import type { ContainerClass } from '../../tokens/size-classes'
-
-/** Aspect (frame W/H) above which the legend moves beside the ring. */
-export const SIDE_LEGEND_ASPECT = 1.5
-/** Aspect a side layout must fall below before it stacks again — the gap stops a legend whose own
- * placement changes the measured height from flipping the layout back and forth. */
-export const STACK_LEGEND_ASPECT = 1.35
-/** Most slices kept before the rest fold into "Other" (so 7 or more slices fold). */
-export const DONUT_MAX_SLICES = 6
-export const OTHER_KEY = '__other'
-/** Side layout: the ring's diameter never exceeds this share of the frame width. */
-export const SIDE_RING_MAX_WIDTH_SHARE = 0.55
-/** Space kept between the ring's outer edge and the plot box. */
-export const RING_PADDING = 4
-
-export type DonutLayout = { side: boolean }
-
-/** Side legend only on a wide-enough frame (`micro`/`compact` always stack under the ring).
- * `wasSide` applies hysteresis: an already-side layout stays side until W/H falls below
- * {@link STACK_LEGEND_ASPECT}. */
-export function resolveDonutLayout(input: {
-  frameW: number
-  frameH: number
-  containerClass: ContainerClass
-  wasSide?: boolean
-}): DonutLayout {
-  const { frameW, frameH, containerClass, wasSide = false } = input
-  const roomy = containerClass !== 'micro' && containerClass !== 'compact'
-  if (!roomy || frameH <= 0) return { side: false }
-  const aspect = frameW / frameH
-  return { side: wasSide ? aspect >= STACK_LEGEND_ASPECT : aspect > SIDE_LEGEND_ASPECT }
-}
-
-/** Ring outer radius: never negative and never wider than the plot; the side layout also caps the
- * diameter at {@link SIDE_RING_MAX_WIDTH_SHARE} of the frame width. */
-export function resolveDonutRadius(input: {
-  plotW: number
-  plotH: number
-  frameW: number
-  side: boolean
-}): number {
-  const { plotW, plotH, frameW, side } = input
-  const diameter = side
-    ? Math.min(plotW, plotH, SIDE_RING_MAX_WIDTH_SHARE * frameW)
-    : Math.min(plotW, plotH)
-  return Math.max(0, diameter / 2 - RING_PADDING)
-}
-
-/** Share of `total` as a whole percent; an empty total is 0%. */
-export function sharePercent(value: number, total: number): number {
-  return total > 0 ? Math.round((value / total) * 100) : 0
-}
-
-/** A slice value a ring can draw: non-finite or negative counts as 0. */
-const safeValue = (value: number): number => (Number.isFinite(value) && value > 0 ? value : 0)
-
-/** The key for the synthesized "Other" bucket — {@link OTHER_KEY}, prefixed until no input key uses it. */
-export function resolveOtherKey(keys: readonly string[]): string {
-  const taken = new Set(keys)
-  let key = OTHER_KEY
-  while (taken.has(key)) key = `_${key}`
-  return key
-}
-
-/** Keeps the top {@link DONUT_MAX_SLICES} by value (in original order) and sums the rest into one
- * trailing "Other" entry. Non-finite and negative values count as 0. */
-export function foldOther<T extends { key: string; value: number }>(
-  slices: readonly T[],
-): { kept: T[]; other: number | null } {
-  const safe = slices.map((s) => ({ ...s, value: safeValue(s.value) }))
-  if (safe.length <= DONUT_MAX_SLICES) return { kept: safe, other: null }
-  const top = new Set(
-    safe
-      .toSorted((a, b) => b.value - a.value)
-      .slice(0, DONUT_MAX_SLICES)
-      .map((s) => s.key),
-  )
-  return {
-    kept: safe.filter((s) => top.has(s.key)),
-    other: safe.reduce((sum, s) => (top.has(s.key) ? sum : sum + s.value), 0),
-  }
-}