basalt-ui 1.41.0 → 2.0.1

package/src/charts/ChartCard.tsx

@@ -0,0 +1,178 @@
+/**
+ * The standard chart wrapper: a card with a `WidgetHeader tier="widget"` title row (icon, info,
+ * value, delta, count, actions) over a clipped chart body. `WidgetHeader` is itself Mantine-free,
+ * so `./charts` still resolves with no `@mantine/*` installed. The `actions` slot carries only
+ * `data-basalt-tier="widget"`; a basalt control there sizes itself.
+ *
+ * The header renders only when one of title/info/value/actions/icon/count is set. A chart's
+ * `legend={{ placement: 'header' }}` legend is drawn by the chart, at the top of the body under the
+ * header, so it is in the server HTML and the header never grows on hydration.
+ */
+import { useRef, useState } from 'react'
+import type { CSSProperties, ReactElement, ReactNode } from 'react'
+import { useIsomorphicLayoutEffect } from '../common/isomorphic-layout-effect'
+import { cx } from '../common/props'
+import type { BasaltProps, SlotStylesProps } from '../common/props'
+import type { DeltaPolarity } from '../dashboard/delta-badge'
+import { WidgetHeader } from '../dashboard/widget-header'
+import { VX } from '../tokens'
+import { ChartCardContext } from './card-context'
+import classes from './chart-card.module.css'
+import { ChartPlaceholder, resolveChartState } from './state'
+import type { ChartState, ResponsiveChartHeight } from './types'
+
+// Depth is `shadow-card` (a whisper shadow with the 1px ring baked in), never a border, so a
+// ChartCard reads exactly like a Mantine Card. Only the body clips; the header must let
+// `WidgetHeader`'s info bubble overhang the card edge.
+const cardStyle: CSSProperties = {
+  display: 'flex',
+  flexDirection: 'column',
+  minHeight: 0,
+  containerType: 'inline-size',
+  containerName: 'basalt-card',
+  borderRadius: VX.radiusCard,
+  boxShadow: VX.shadowCard,
+  backgroundColor: VX.surface.panel,
+}
+/**
+ * Below this rendered height the header folds its subtitle whatever the width (the header-economy
+ * law): `data-basalt-card-short` is the hook `widget-header.module.css` reacts to. Leaving the
+ * state needs `CARD_SHORT_HEIGHT + SHORT_EXIT_SLACK`: the fold changes the card's own height, and
+ * without the band a card whose unfolded height sits just above the line flip-flops forever.
+ */
+const CARD_SHORT_HEIGHT = 280
+const SHORT_EXIT_SLACK = 24
+
+/** A `ChartBox` that states a height (any but `fill`): `box.tsx` writes `data-basalt-box`. */
+const STATED_BOX = '[data-basalt-box]:not([data-basalt-box="fill"])'
+
+/** The card's measured height through the hysteresis band above. */
+function useShortCard(): { ref: (el: HTMLDivElement | null) => void; short: boolean } {
+  const [node, setNode] = useState<HTMLDivElement | null>(null)
+  const [short, setShort] = useState(false)
+  const shortRef = useRef(false)
+  useIsomorphicLayoutEffect(() => {
+    if (!node) return
+    // A card holding a chart box that states its own height (the law default included) is short, or
+    // not, by that box in CSS (`data-basalt-chart-short`, written by `ChartBox`, `box.tsx`);
+    // measuring it as well would flip it after hydration. A `fill` box states nothing, so it is
+    // measured like any other body. The answer cannot change while the box is mounted.
+    if (node.querySelector(STATED_BOX)) {
+      shortRef.current = false
+      setShort(false)
+      return
+    }
+    if (typeof ResizeObserver === 'undefined') return
+    const observer = new ResizeObserver((entries) => {
+      const height = entries[0]?.borderBoxSize?.[0]?.blockSize ?? node.offsetHeight
+      const limit = shortRef.current ? CARD_SHORT_HEIGHT + SHORT_EXIT_SLACK : CARD_SHORT_HEIGHT
+      const next = height > 0 && height < limit
+      if (next === shortRef.current) return
+      shortRef.current = next
+      setShort(next)
+    })
+    observer.observe(node)
+    return () => observer.disconnect()
+  }, [node])
+  return { ref: setNode, short }
+}
+const bodyClipStyle: CSSProperties = {
+  borderBottomLeftRadius: VX.radiusCard,
+  borderBottomRightRadius: VX.radiusCard,
+  overflow: 'hidden',
+  flex: '1 1 auto',
+  minHeight: 0,
+  display: 'flex',
+  flexDirection: 'column',
+  padding: '2px var(--vx-space-card-inset-x, 0.8125rem) var(--vx-space-card-inset-y, 0.6875rem)',
+}
+
+/** The three boxes a `ChartCard` paints. */
+export type ChartCardSlot = 'root' | 'header' | 'body'
+
+export type ChartCardProps = BasaltProps &
+  SlotStylesProps<ChartCardSlot> & {
+    title?: string
+    icon?: ReactNode
+    /** A muted line below the title row; does not by itself render the header. */
+    subtitle?: string
+    /** `WidgetHeader`'s info glyph beside the title. */
+    info?: string
+    /** A pre-formatted metric value, with `delta` on the hero row. */
+    value?: string
+    delta?: number
+    deltaPeriod?: string
+    deltaPolarity?: DeltaPolarity
+    /** A mono count tag after the title. */
+    count?: number
+    /** Right-aligned controls. */
+    actions?: ReactNode
+    /** A resolved state replaces `children` with its placeholder; the header stays. */
+    state?: ChartState
+    /** Body height while a placeholder shows. Default: the chart height law, i.e. exactly the box an
+     * unsized chart takes — pass the chart's own `height` when it states one, so a `<Suspense
+     * fallback={<ChartCard state={{ pending: true }} …/>}>` reserves the final size. */
+    placeholderHeight?: number | ResponsiveChartHeight
+    /** A retry button or a "clear filters" link under the placeholder. */
+    stateAction?: ReactNode
+    children?: ReactNode
+  }
+
+/** A header renders when one of these is set (a subtitle or delta alone does not). */
+const HEADER_TRIGGERS = ['title', 'info', 'value', 'icon', 'count'] as const
+
+export function ChartCard({
+  actions,
+  state,
+  placeholderHeight,
+  stateAction,
+  className,
+  classNames,
+  style,
+  children,
+  ...header
+}: ChartCardProps): ReactElement {
+  const { ref, short } = useShortCard()
+  const resolved = resolveChartState(state)
+  const hasHeader = actions !== undefined || HEADER_TRIGGERS.some((k) => header[k] !== undefined)
+
+  return (
+    <ChartCardContext.Provider value>
+      <div
+        ref={ref}
+        data-basalt-chart-card=""
+        className={cx(classNames?.root, className)}
+        style={{ ...cardStyle, ...style }}
+        {...(resolved === 'pending' && { 'aria-busy': 'true' })}
+        {...(short && { 'data-basalt-card-short': '' })}
+      >
+        {hasHeader && (
+          <div className={cx(classes.header, classNames?.header)}>
+            <WidgetHeader
+              tier="widget"
+              {...header}
+              title={header.title ?? ''}
+              {...(actions !== undefined && {
+                actions: <span data-basalt-tier="widget">{actions}</span>,
+              })}
+            />
+          </div>
+        )}
+        <div
+          {...(classNames?.body !== undefined && { className: classNames.body })}
+          style={bodyClipStyle}
+        >
+          {resolved === null ? (
+            children
+          ) : (
+            <ChartPlaceholder
+              state={state}
+              {...(placeholderHeight !== undefined && { height: placeholderHeight })}
+              action={stateAction}
+            />
+          )}
+        </div>
+      </div>
+    </ChartCardContext.Provider>
+  )
+}

package/src/charts/Donut.tsx

@@ -0,0 +1,256 @@
+/**
+ * `Donut` — a share-of-total ring on the engine's `polar` container (`docs/V2-SPEC.md` § 9.3).
+ * At most six slices are drawn; the rest fold into a neutral "Other". The legend is derived from
+ * the slices (a toggle drops a slice from the ring and the tooltip; every share is still taken of
+ * ALL slices, so the legend and the tooltip never disagree). It sits beside the ring in a 480px
+ * container or wider, below it otherwise (`donut.module.css`, decided in CSS so the server HTML is
+ * the hydrated layout). No cursor: a ring has no shared axis.
+ */
+import { tooltip as tooltipHost } from '@tanstack/charts/tooltip'
+import { portal } from '@tanstack/charts/tooltip/portal'
+import { pie, polar, radialArc } from '@tanstack/charts/polar'
+import type { ChartPoint, StoredChartSpec } from '@tanstack/charts/types/core'
+import { useCallback, useId, useMemo, useState } from 'react'
+import type { CSSProperties, ReactElement } from 'react'
+import type { BasaltProps } from '../common/props'
+import { alpha, VX } from '../tokens'
+import type { CartesianDefinition } from './compile'
+import { ChartEngine, idPrefixOf } from './host'
+import { ChartLegend } from './legend'
+import { useCoarsePointer } from '../common/use-media-query'
+import { chartBoxVars, isShortChart } from './box'
+import classes from './donut.module.css'
+import { ChartPlaceholder, resolveChartState } from './state'
+import { CHART_THEME, DIMMED } from './theme'
+import type { ChartSeries, ChartState, ResponsiveChartHeight } from './types'
+
+export type DonutDatum<K extends string = string> = { key: K; value: number }
+
+export type DonutProps<K extends string = string> = BasaltProps & {
+  /** The accessible name. Required. */
+  ariaLabel: string
+  data: readonly DonutDatum<K>[]
+  /** A `VX.*` ref or a consumer series token per key. */
+  colorForKey: (key: K) => string
+  formatValue: (v: number) => string
+  /** Legend and tooltip label for a key. Default: the key. */
+  seriesLabel?: (key: K) => string
+  /** The ring's centre text, and the smaller line under it. */
+  centerLabel?: string
+  centerSubLabel?: string
+  /** Default 240. */
+  height?: number | ResponsiveChartHeight
+  state?: ChartState
+}
+
+/** Slices kept before the rest fold into "Other". */
+const MAX_SLICES = 6
+const DEFAULT_HEIGHT = 240
+const INNER_RATIO = 0.62
+
+/** `id` is the internal identity (legend key, hidden set, arc key): `k:<key>` for a datum, `other`
+ * for the fold. A consumer key can never equal `other`, whatever it is called. */
+type Slice = { id: string; label: string; color: string; value: number }
+const OTHER_ID = 'other'
+
+const identityLabel = (key: string): string => key
+
+/** Duplicate keys add up; a non-finite or non-positive value is an ABSENCE and drops out, it is
+ * not a zero-width slice. First-seen order. */
+function aggregate<K extends string>(data: readonly DonutDatum<K>[]): DonutDatum<K>[] {
+  const sums = new Map<K, number>()
+  for (const d of data) {
+    if (!Number.isFinite(d.value) || d.value <= 0) continue
+    sums.set(d.key, (sums.get(d.key) ?? 0) + d.value)
+  }
+  return [...sums].map(([key, value]) => ({ key, value }))
+}
+
+/** The six largest keep their place; everything else sums into one trailing remainder. */
+function foldOther<K extends string>(
+  all: readonly DonutDatum<K>[],
+): {
+  kept: DonutDatum<K>[]
+  other: number | null
+} {
+  if (all.length <= MAX_SLICES) return { kept: [...all], other: null }
+  const top = new Set(
+    all
+      .toSorted((a, b) => b.value - a.value)
+      .slice(0, MAX_SLICES)
+      .map((d) => d.key),
+  )
+  let other = 0
+  const kept: DonutDatum<K>[] = []
+  for (const d of all) {
+    if (top.has(d.key)) kept.push(d)
+    else other += d.value
+  }
+  return { kept, other }
+}
+
+const percent = (value: number, total: number): string =>
+  `${total > 0 ? Math.round((value / total) * 100) : 0}%`
+
+const centerStyle: CSSProperties = {
+  position: 'absolute',
+  inset: 0,
+  display: 'flex',
+  flexDirection: 'column',
+  alignItems: 'center',
+  justifyContent: 'center',
+  pointerEvents: 'none',
+  fontFamily: 'var(--basalt-font-mono)',
+}
+
+// A size container: the row inside lays the legend beside or under the ring by this width (CSS).
+// `width: 100%`: a size container takes no width from its content (see `CartesianChart`'s root).
+const rootStyle: CSSProperties = { containerType: 'inline-size', width: '100%', minWidth: 0 }
+
+export function Donut<K extends string = string>(props: DonutProps<K>): ReactElement {
+  const {
+    ariaLabel,
+    data,
+    colorForKey,
+    formatValue,
+    seriesLabel = identityLabel,
+    centerLabel,
+    centerSubLabel,
+    height = DEFAULT_HEIGHT,
+    state,
+    className,
+    style,
+  } = props
+  const chartId = useId()
+  const coarse = useCoarsePointer()
+  const [hidden, setHidden] = useState<ReadonlySet<string>>(() => new Set())
+  const [highlighted, setHighlighted] = useState<string | null>(null)
+  const onToggle = useCallback((key: string) => {
+    setHidden((prev) => {
+      const next = new Set(prev)
+      if (!next.delete(key)) next.add(key)
+      return next
+    })
+  }, [])
+
+  const slices = useMemo<Slice[]>(() => {
+    const { kept, other } = foldOther(aggregate(data))
+    const out: Slice[] = kept.map((d) => ({
+      id: `k:${d.key}`,
+      label: seriesLabel(d.key),
+      color: colorForKey(d.key),
+      value: d.value,
+    }))
+    if (other !== null)
+      out.push({ id: OTHER_ID, label: 'Other', color: alpha(VX.neutral, 0.5), value: other })
+    return out
+  }, [data, colorForKey, seriesLabel])
+  const total = slices.reduce((sum, s) => sum + s.value, 0)
+
+  const series = useMemo<ChartSeries<Slice>[]>(
+    () =>
+      slices.map((s) => ({
+        key: s.id,
+        label: s.label,
+        color: s.color,
+        mark: 'bar' as const,
+        getValue: () => s.value,
+        note: `${formatValue(s.value)} · ${percent(s.value, total)}`,
+      })),
+    [slices, total, formatValue],
+  )
+
+  const definition = useMemo<CartesianDefinition>(() => {
+    const drawn = slices.filter((s) => !hidden.has(s.id))
+    const arcs = pie(drawn, { value: 'value' })
+    return {
+      chart: (): StoredChartSpec => ({
+        marks: [
+          polar({
+            inset: 4,
+            scales: { angle: null, radius: null },
+            marks: [
+              radialArc(arcs, {
+                key: 'id',
+                innerRadius: ({ radius }) => radius * INNER_RATIO,
+                cornerRadius: 3,
+                fill: (a) =>
+                  highlighted === null || highlighted === a.id ? a.color : alpha(a.color, DIMMED),
+              }),
+            ],
+          }),
+        ],
+        scales: { x: null, y: null },
+        theme: CHART_THEME,
+      }),
+      tooltip: {
+        use: tooltipHost,
+        portal,
+        content: (points: readonly ChartPoint[]) => {
+          const slice = points[0]?.datum as Slice | undefined
+          if (!slice) return { rows: [] }
+          return {
+            title: slice.label,
+            rows: [
+              { label: 'Value', value: formatValue(slice.value), color: slice.color },
+              { label: 'Share', value: percent(slice.value, total) },
+            ],
+          }
+        },
+      },
+    }
+  }, [slices, hidden, highlighted, total, formatValue])
+
+  const legend = (
+    <ChartLegend
+      series={series}
+      hidden={hidden}
+      mode="chips"
+      groups={false}
+      toggle={series.length >= 2}
+      onToggle={onToggle}
+      onHighlight={setHighlighted}
+    />
+  )
+  const resolved = resolveChartState(state)
+  return (
+    <div
+      data-basalt-chart=""
+      {...(className !== undefined && { className })}
+      style={{ ...rootStyle, ...style }}
+    >
+      <div className={classes.row}>
+        <div
+          className={classes.ring}
+          style={chartBoxVars(height)}
+          {...(isShortChart(height) && { 'data-basalt-chart-short': '' })}
+        >
+          {resolved === null ? (
+            <ChartEngine
+              definition={definition}
+              ariaLabel={ariaLabel}
+              height="fill"
+              idPrefix={idPrefixOf(chartId)}
+              coarse={coarse}
+            />
+          ) : (
+            <ChartPlaceholder state={state} height="fill" />
+          )}
+          {resolved === null && (centerLabel !== undefined || centerSubLabel !== undefined) && (
+            <div style={centerStyle}>
+              {centerLabel !== undefined && (
+                <span style={{ color: VX.ink, fontSize: VX.text.lg, fontWeight: 600 }}>
+                  {centerLabel}
+                </span>
+              )}
+              {centerSubLabel !== undefined && (
+                <span style={{ color: VX.axis, fontSize: VX.text.micro }}>{centerSubLabel}</span>
+              )}
+            </div>
+          )}
+        </div>
+        {resolved === null && legend}
+      </div>
+    </div>
+  )
+}