basalt-ui 1.41.0 → 2.0.0

package/src/charts/StackedArea.tsx

@@ -0,0 +1,80 @@
+/**
+ * `StackedArea` — n area bands stacked bottom-to-top in `series` order over the rung
+ * (`docs/V2-SPEC.md` § 9.3). A band's keys and colors are plain `series` data, so a dynamic group
+ * set is the caller mapping its groups to entries. The y domain is the visible stack total, so a
+ * legend toggle shrinks the axis; the tooltip lists the top band first, matching the plot.
+ *
+ * A stack is only as dense as its sparsest band: a row where ANY visible band is `null` has no
+ * total, so every band gaps across it. Reading it as `0` would claim a measured zero.
+ */
+import { areaY } from '@tanstack/charts/area'
+import { stack } from '@tanstack/charts/stack'
+import { useCallback, useMemo } from 'react'
+import type { ReactElement } from 'react'
+import { CartesianRung } from './CartesianChart'
+import { chartCurve } from './curves'
+import { emphasis } from './marks'
+import { rowX } from './types'
+import type { CartesianChartProps, ChartMarks, ChartSeries, ChartX, PlotContext } from './types'
+
+const DEFAULT_BAND_OPACITY = 0.85
+
+/** A band. Stacked areas read the left axis and draw no line, so the line fields are absent. */
+export type StackedAreaBand<T> = Pick<
+  ChartSeries<T>,
+  'key' | 'label' | 'color' | 'getValue' | 'formatValue' | 'tooltip' | 'legend' | 'role' | 'note'
+> & {
+  /** Default 0.85. */
+  fillOpacity?: number
+}
+
+export type StackedAreaProps<T, X extends ChartX = ChartX> = Omit<
+  CartesianChartProps<T, X>,
+  'marks' | 'y' | 'y2' | 'series'
+> & {
+  /** The bands, bottom to top. */
+  series: readonly StackedAreaBand<T>[]
+  /** No `scale`: a log axis has no additive zero to stack from. */
+  y?: Omit<NonNullable<CartesianChartProps<T, X>['y']>, 'scale'>
+}
+
+export function StackedArea<T, X extends ChartX = ChartX>(
+  props: StackedAreaProps<T, X>,
+): ReactElement {
+  const { series: bands, ...rest } = props
+  // `mark: 'bar'` is what the rung sums for the auto domain, and the legend/tooltip swatch.
+  const series = useMemo<ChartSeries<T>[]>(
+    () => bands.map((s) => ({ ...s, mark: 'bar' as const })),
+    [bands],
+  )
+
+  const marks = useCallback((plot: PlotContext<T, X>): ChartMarks => {
+    const visible = plot.visible
+    if (visible.length === 0) return []
+    const byKey = new Map(visible.map((s) => [s.key, s]))
+    const h = plot.highlighted
+    const columns = visible.map((s) => plot.rows(s.key))
+    // A row is dense when every visible band has a value there; one pass over the columns.
+    const dense = columns[0]?.map((_, i) => columns.every((col) => col[i]?.y !== null)) ?? []
+    const rows = columns.flatMap((col) => col.map((r, i) => (dense[i] ? r : { ...r, y: null })))
+    return [
+      areaY(rows, {
+        id: 'bands',
+        x: rowX,
+        y: 'y',
+        z: 'series',
+        fill: (r) => {
+          const s = byKey.get(r.series)
+          if (!s) return 'transparent'
+          const pct = Math.round((s.fillOpacity ?? DEFAULT_BAND_OPACITY) * emphasis(h, s) * 100)
+          return `color-mix(in srgb, ${s.color} ${pct}%, transparent)`
+        },
+        fillOpacity: 1,
+        curve: chartCurve('monotone'),
+        layout: stack({ order: visible.map((s) => s.key) }),
+      }),
+    ]
+  }, [])
+
+  return <CartesianRung {...rest} series={series} marks={marks} reverseRows stack="stacked" />
+}

package/src/charts/box.tsx

@@ -0,0 +1,96 @@
+/**
+ * The CSS-owned chart box (`chart-box.module.css`): the single element whose height the page lays
+ * out around. A chart, its pending placeholder and a `ChartCard` fallback all render inside one, so a
+ * `<Suspense>` fallback occupies exactly the box the chart will. Knows no engine, no legend, no card.
+ */
+import type { CSSProperties, ReactElement, ReactNode } from 'react'
+import { cx } from '../common/props'
+import classes from './chart-box.module.css'
+import type { ResponsiveChartHeight } from './types'
+
+/** `undefined` is the height law; a number is fixed; `'fill'` is the parent's height. */
+export type ChartBoxHeight = number | ResponsiveChartHeight | 'fill' | undefined
+
+/** Height = width × ratio, per container class, clamped to {@link HEIGHT_MIN}–{@link HEIGHT_MAX}. */
+export const HEIGHT_RATIO = { micro: 0.5, compact: 0.62, regular: 0.5, wide: 0.4 } as const
+export const HEIGHT_MIN = 160
+export const HEIGHT_MAX = 420
+
+/**
+ * A stated height at or under this makes the enclosing `ChartCard` render its short header (the
+ * subtitle folds, the KPI numeral drops to `lg`, the top inset trims): the card is then under
+ * ~280 px once the header's own ~100 px is added. Written onto the box as `data-basalt-chart-short`,
+ * from the prop, so the server HTML already says it and CSS (`:has`) applies it — no height
+ * measurement, nothing to flip after hydration.
+ */
+export const SHORT_CHART_HEIGHT = 180
+
+const statedMax = (height: ChartBoxHeight): number | undefined => {
+  if (typeof height === 'number') return height
+  if (typeof height !== 'object') return undefined
+  return Math.max(height.base, height.regular ?? 0, height.wide ?? 0)
+}
+
+const px = (n: number): string => `${n}px`
+const law = (ratio: number): string =>
+  `clamp(${px(HEIGHT_MIN)}, ${ratio * 100}cqw, ${px(HEIGHT_MAX)})`
+
+/** The four custom properties the stylesheet selects between by the frame's container class. */
+export type ChartBoxVars = CSSProperties &
+  Record<'--bc-micro' | '--bc-compact' | '--bc-regular' | '--bc-wide', string>
+
+/** The four per-class heights (micro, compact, regular, wide) a height prop resolves to. */
+function classHeights(height: Exclude<ChartBoxHeight, 'fill'>): [string, string, string, string] {
+  if (height === undefined) {
+    return [
+      law(HEIGHT_RATIO.micro),
+      law(HEIGHT_RATIO.compact),
+      law(HEIGHT_RATIO.regular),
+      law(HEIGHT_RATIO.wide),
+    ]
+  }
+  if (typeof height === 'number') return [px(height), px(height), px(height), px(height)]
+  const regular = height.regular ?? height.base
+  return [px(height.base), px(height.base), px(regular), px(height.wide ?? regular)]
+}
+
+export function chartBoxVars(height: Exclude<ChartBoxHeight, 'fill'>): ChartBoxVars {
+  const [micro, compact, regular, wide] = classHeights(height)
+  return {
+    '--bc-micro': micro,
+    '--bc-compact': compact,
+    '--bc-regular': regular,
+    '--bc-wide': wide,
+  }
+}
+
+/** `data-basalt-chart-short`: a stated height at or under {@link SHORT_CHART_HEIGHT}. */
+export const isShortChart = (height: ChartBoxHeight): boolean =>
+  (statedMax(height) ?? Number.POSITIVE_INFINITY) <= SHORT_CHART_HEIGHT
+
+export function ChartBox(props: {
+  height?: ChartBoxHeight
+  className?: string
+  children: ReactNode
+}): ReactElement {
+  const { height, className, children } = props
+  const fill = height === 'fill'
+  return (
+    // `data-basalt-box` is the hook `ChartCard` uses to tell a chart body from a measured one; a
+    // fill box states no height of its own, so it reads `fill` and the card still measures.
+    <div
+      className={cx(classes.frame, fill && classes.fillFrame)}
+      data-basalt-box={fill ? 'fill' : ''}
+      {...(isShortChart(height) && { 'data-basalt-chart-short': '' })}
+    >
+      <div
+        className={cx(classes.box, fill && classes.fill, className)}
+        {...(!fill && { style: chartBoxVars(height) })}
+      >
+        {children}
+      </div>
+    </div>
+  )
+}
+
+export const stateClass = classes.state

package/src/charts/card-context.ts

@@ -0,0 +1,11 @@
+/**
+ * The seam between a chart and its enclosing `ChartCard`: a chart whose legend is
+ * `placement: 'header'` renders it at the top of its own body, styled as the card's header legend
+ * row, when it knows it sits in a card. In the chart's own markup rather than handed to the header
+ * from an effect, so the legend is in the server HTML and hydration grows nothing (W10).
+ */
+import { createContext, useContext } from 'react'
+
+export const ChartCardContext = createContext(false)
+
+export const useInChartCard = (): boolean => useContext(ChartCardContext)

package/src/charts/chart-box.module.css

@@ -0,0 +1,64 @@
+/*
+ * The chart box — the one place a chart's height is decided (docs/V2-SPEC.md § 9.6, W10 SSR
+ * contract). The box is sized by CSS from its container's own width, so the server HTML, the first
+ * paint and the hydrated page all agree before any script runs; the engine MEASURES this box, it
+ * is never handed a height. Only the svg's internal geometry may change after hydration.
+ *
+ * `box.tsx` writes the four per-class heights as `--bc-*`; the unnamed container queries below pick
+ * one by the frame's inline size. The literals are CONTAINER_CLASSES (a query cannot read a custom
+ * property); `breakpoint-literals.test.ts` pins them. Mantine-free: `src/charts/**` imports no
+ * `@mantine/*`.
+ */
+
+.frame {
+  container-type: inline-size;
+  width: 100%;
+  min-width: 0;
+}
+
+.box {
+  position: relative;
+  height: var(--bc-micro);
+}
+
+@container (min-width: 240px) {
+  .box {
+    height: var(--bc-compact);
+  }
+}
+
+@container (min-width: 480px) {
+  .box {
+    height: var(--bc-regular);
+  }
+}
+
+@container (min-width: 800px) {
+  .box {
+    height: var(--bc-wide);
+  }
+}
+
+/* A coarse pointer never gets a chart taller than 45% of the viewport (small viewport: a
+ * collapsing mobile URL bar must not resize it). */
+@media (pointer: coarse) {
+  .box {
+    max-height: 45svh;
+  }
+}
+
+/* Fills its parent (a Heatmap that matches a sibling's height): the frame and the box both take the
+ * parent's definite height, or a percentage on the auto-height frame would resolve to nothing. */
+.fillFrame {
+  height: 100%;
+}
+
+.fill {
+  height: 100%;
+  max-height: none;
+}
+
+.state {
+  width: 100%;
+  height: 100%;
+}

package/src/charts/chart-box.module.css.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Typed CSS-module declaration (the S4 CSS-modules path). Named string props — not an index
+ * signature — so dot access stays verbatim under the package's strict flags.
+ */
+declare const classes: {
+  readonly frame: string
+  readonly box: string
+  readonly fillFrame: string
+  readonly fill: string
+  readonly state: string
+}
+export default classes

package/src/charts/chart-card.module.css

@@ -0,0 +1,25 @@
+/*
+ * ChartCard's header inset, by the card's own inline size (W10 SSR contract). A card under 480px
+ * trims the header's top inset: the subtitle has already folded into the info glyph there, and the
+ * chart below is sized by the 160–420px law, so a narrow card is a short one. Decided in CSS, not
+ * from a post-hydration height measurement, so the server HTML is the hydrated header. The literal
+ * is CONTAINER_CLASSES.regular (`breakpoint-literals.test.ts`).
+ */
+
+.header {
+  padding: 4px var(--vx-space-card-inset-x, 0.8125rem) 4px;
+}
+
+@container (min-width: 480px) {
+  .header {
+    padding-top: var(--vx-space-card-inset-y, 0.6875rem);
+  }
+}
+
+/* A short card trims it at any width: its chart states a small `height` (`data-basalt-chart-short`,
+ * in the server HTML), or, for a body that is not a chart, `ChartCard` measured it under 280px. */
+/* (`data-basalt-chart-short` is written by `ChartBox`, `box.tsx`; the same `:is` is in
+ * `dashboard/widget-header.module.css`.) */
+:is([data-basalt-card-short], [data-basalt-chart-card]:has([data-basalt-chart-short])) .header {
+  padding-top: 4px;
+}

package/src/charts/chart-card.module.css.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Typed CSS-module declaration (the S4 CSS-modules path). Named string props — not an index
+ * signature — so dot access stays verbatim under the package's strict flags.
+ */
+declare const classes: {
+  readonly header: string
+}
+export default classes

package/src/charts/chart-legend.module.css

@@ -0,0 +1,38 @@
+/*
+ * The derived legend's responsive mode, in CSS (docs/V2-SPEC.md § 9.6, W10 SSR contract): none below
+ * 240px, dots below 480px, chips from 480px, by the enclosing chart's inline size — so the legend in
+ * the server HTML is the legend of the hydrated page. `ChartLegend` renders both swatches; this
+ * file shows one. Literals are CONTAINER_CLASSES (`breakpoint-literals.test.ts`); the container is
+ * the chart root (`CartesianChart.tsx`), whose `container-type` this relies on.
+ */
+
+.auto {
+  display: none;
+}
+
+.auto .chip {
+  display: none;
+}
+
+@container (min-width: 240px) {
+  .auto {
+    display: flex;
+    column-gap: var(--bc-dots-gap);
+    --vx-hit-gap: var(--bc-dots-gap);
+  }
+}
+
+@container (min-width: 480px) {
+  .auto {
+    column-gap: var(--bc-legend-gap);
+    --vx-hit-gap: var(--bc-legend-gap);
+  }
+
+  .auto .dot {
+    display: none;
+  }
+
+  .auto .chip {
+    display: inline-flex;
+  }
+}

package/src/charts/chart-legend.module.css.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Typed CSS-module declaration (the S4 CSS-modules path). Named string props — not an index
+ * signature — so dot access stays verbatim under the package's strict flags.
+ */
+declare const classes: {
+  readonly auto: string
+  readonly dot: string
+  readonly chip: string
+}
+export default classes