@galaxy-io/dls 1.6.0 → 2.0.0

package/dist/charts/types.d.ts

@@ -1,354 +1,213 @@
-import type { ReactNode } from "react";
 /**
- * Shared types for the chart components (`BarChart`, `LineChart`, `PieChart`).
+ * Shared chart vocabulary (`@galaxy-io/dls/charts/types`): the palette, the curve, and the prop
+ * and data types every chart composes. Types and enums only, so importing this module pulls in no
+ * optional peer (`d3-scale`, `d3-shape`) and no component.
  *
- * Every data type is generic over its key unions, and the inference is
- * deliberately one-directional: `TMetric` comes from the keys of the `series`
- * record and from nowhere else, with {@link NoInfer} applied to every
- * data-shaped prop.
+ * Every chart is generic over its series keys, and the inference is one-directional: the key
+ * union comes from the keys of the `series` record and from nowhere else, and every data-shaped
+ * prop wraps it in `NoInfer`. Were the keys also inferred from the data, an inline
+ * `{ metric: "revenue" }` would widen to `string` and every check below would quietly become a
+ * no-op.
  *
- * That asymmetry is what makes the guarantees real. Were `TMetric` also
- * inferred from the data, an inline `{ metric: "revenue" }` would widen to
- * `string`, TypeScript would pick the supertype, and every check below would
- * quietly become a no-op — type safety that looks present but is not.
- *
- * ```ts
- * <BarChart
- *   series={{
- *     revenue: { label: "Revenue" },
- *     cost: { label: "Cost" },
- *   }}
- *   groups={[
- *     { label: "Q1", bars: [{ metric: "revenu", components: [] }] },
- *     //                              ^ Type '"revenu"' is not assignable to
- *     //                                type '"revenue" | "cost"'.
- *   ]}
+ * ```tsx
+ * <LineChart
+ *   series={{ revenue: { label: "Revenue" }, cost: { label: "Cost" } }}
+ *   lines={[{ metric: "revenu", points: [] }]}
+ *   //                ^ Type '"revenu"' is not assignable to type '"revenue" | "cost"'.
  * />
  * ```
- *
- * The same union then makes aggregates exhaustive, spell-checks legend and
- * ordering props, and narrows callback parameters for `ts-pattern`.
  */
+import type { AriaAttributes, CSSProperties, ReactNode } from "react";
+import type { Hex } from "../theme/tokens/types.js";
 /**
- * Semantic color slot for a series, resolved against the active theme at render
- * time by `resolveChartPaletteColor` in `chartTheme.ts`.
- *
- * Deliberately an enum of slots rather than a hex string: consumer data should
- * never carry raw color, and every rendered color has to come from
- * `theme.color.*` so both themes stay correct.
+ * Series color slot. Members are canonical color-set names (Constitution
+ * III.4). The first eight are the automatic order (purple leads); the rest are for explicit,
+ * meaningful assignment only.
  */
 export declare enum ChartPalette {
+    /** `text.purple`. First in the automatic order. */
     PURPLE = "PURPLE",
+    /** `text.pink`. */
     PINK = "PINK",
+    /** `text.blue`. */
     BLUE = "BLUE",
+    /** `text.teal`. */
     TEAL = "TEAL",
+    /** `text.lime`. */
     LIME = "LIME",
+    /** `text.orange`. */
     ORANGE = "ORANGE",
+    /** `text.yellow`. */
     YELLOW = "YELLOW",
+    /** `text.green`. Last in the automatic order. */
     GREEN = "GREEN",
-    RED = "RED",
+    /** `text.success`. Explicit assignment only. */
+    SUCCESS = "SUCCESS",
+    /** `text.warning`. Explicit assignment only. */
+    WARNING = "WARNING",
+    /** `text.error` (1.x `RED`). Explicit assignment only. */
+    ERROR = "ERROR",
+    /** `text.indigo` (no gray in charts). Explicit assignment only. */
     PRIMARY = "PRIMARY",
+    /** `text.sky` (no gray in charts). Explicit assignment only. */
     SECONDARY = "SECONDARY",
-    TERTIARY = "TERTIARY",
-    WARNING = "WARNING"
+    /** `text.violet` (no gray in charts). Explicit assignment only. */
+    TERTIARY = "TERTIARY"
 }
-/**
- * Built-in value formats. Supplies an `Intl`-based default for axis ticks,
- * value labels and tooltip rows so callers don't have to write the same
- * formatter three times.
- *
- * A `valueFormatter` prop always wins over this when both are given.
- */
-export declare enum ChartValueUnit {
-    /** Locale-grouped integer, e.g. `1,250`. */
-    PLAIN = "PLAIN",
-    /** Locale currency with no decimals, e.g. `$1,250`. */
-    CURRENCY = "CURRENCY",
-    /** Percentage of a 0–100 value, e.g. `42%`. */
-    PERCENT = "PERCENT",
-    /** Abbreviated magnitude, e.g. `1.3K`, `4.2M`. */
-    COMPACT = "COMPACT"
+/** How segments between points are drawn (LineChart, AreaChart, Sparkline). 1.x `LineChartCurve`. */
+export declare enum ChartCurve {
+    /** Straight segments. */
+    LINEAR = "LINEAR",
+    /** Monotone cubic: smooth without overshooting the data. */
+    SMOOTH = "SMOOTH",
+    /** Right-angled steps (step-after). */
+    STEP = "STEP"
 }
+/** @internal Emphasis of a rendered mark, applied as a `css` class (`CHART_MARK_STATE_TO_CSS_MAP`). */
+export declare enum ChartMarkState {
+    /** Full strength: the default, and the engaged category or series. */
+    ACTIVE = "ACTIVE",
+    /** Softened: outside the engaged series, the selection, or while loading. */
+    MUTED = "MUTED",
+    /** Barely softened: off-category marks where a cursor band already carries the emphasis. */
+    DIMMED = "DIMMED"
+}
+/** @internal Which chart is rendering; phrases the default accessible name only. */
+export declare enum ChartKind {
+    /** `LineChart`. */
+    LINE = "LINE",
+    /** `AreaChart`. */
+    AREA = "AREA",
+    /** `BarChart`. */
+    BAR = "BAR",
+    /** `PieChart`. */
+    PIE = "PIE",
+    /** `Heatmap`. */
+    HEATMAP = "HEATMAP"
+}
+/** @internal Where the legend sits relative to the plot. */
+export declare enum ChartLegendPlacement {
+    /** Beneath the plot, one line (cartesian charts, Heatmap). */
+    BOTTOM = "BOTTOM",
+    /** Beside the plot, one column, vertically centered (PieChart). */
+    RIGHT = "RIGHT"
+}
+/** @internal Shape of a hit target. */
+export declare enum ChartTargetShape {
+    /** A rectangle: a category band or a bar. */
+    RECT = "RECT",
+    /** A path: an arc outline, redrawn transparent. */
+    PATH = "PATH"
+}
+/** Formats a value for the value axis, the tooltip and the keyboard announcement. */
 export type ChartValueFormatter = (value: number) => string;
+/** Formats a raw category label for the axis and the tooltip heading. */
 export type ChartLabelFormatter = (label: string) => string;
-/**
- * How one series is presented: what to call it and which palette slot it owns.
- *
- * Holds no data and no key — the key is the record key in
- * {@link ChartSeriesStyles}, which is exactly what makes that record
- * exhaustive.
- */
+/** How one series is presented. The key is the record key in `ChartSeriesStyles`. */
 export interface ChartSeriesStyle {
-    /** Name shown in the legend, tooltip and accessible labels. */
+    /** Name shown in the legend, the tooltip and the accessible summary. */
     label: string;
-    /**
-     * Palette slot. Defaults to the series' position in the record, walked
-     * through `CHART_PALETTE_ORDER`.
-     */
+    /** Palette slot. Defaults to the series' position in the record, walked through the automatic order. */
     color?: ChartPalette;
+    /** Raw color for a data-driven series color. Discouraged: it does not follow the theme. Wins over `color`. */
+    hex?: Hex;
 }
 /**
- * Presentation for every series, keyed by series key.
- *
- * A `Record` over the key union rather than an array of `{ key, name }` is the
- * single most load-bearing decision in this model. An array can be wrong in
- * four independent ways — missing entry, extra entry, duplicate key, misspelt
- * key — and TypeScript catches none of them. A record catches all four, because
- * its *keys are the type*.
+ * Presentation for every series, keyed by series key. A `Record` over the key union rather than
+ * an array of `{ key, label }`: a missing, extra, duplicate or misspelt key is a type error.
  */
 export type ChartSeriesStyles<TKey extends string> = Record<TKey, ChartSeriesStyle>;
-export interface ChartMargin {
-    top: number;
-    right: number;
-    bottom: number;
-    left: number;
-}
-/** Override for the computed value axis domain. */
+/** Override for the computed value axis. */
 export interface ChartValueDomain {
     /** Lower bound. Defaults to `min(0, smallest value)`. */
     min: number;
     /** Upper bound. Defaults to `max(0, largest value)`. */
     max: number;
-    /** Approximate tick count passed to d3's `scale.ticks()`. */
+    /** Approximate tick count (d3 `scale.ticks()`). */
     tickCount: number;
 }
-/**
- * Which chart is being rendered.
- *
- * Exists so the frame can phrase a default accessible name — a pie has slices
- * where the cartesian charts have categories. Deliberately not a styling hook:
- * nothing else branches on it.
- */
-export declare enum ChartKind {
-    BAR = "BAR",
-    LINE = "LINE",
-    PIE = "PIE"
-}
-/**
- * Where the legend sits relative to the plot.
- *
- * Its own enum rather than a branch on {@link ChartKind}, which promises to be
- * nothing but a label for the accessible name.
- */
-export declare enum ChartLegendPlacement {
-    /** Beneath the plot, wrapping — the cartesian layout. */
-    BOTTOM = "BOTTOM",
-    /** Beside the plot, stacked, vertically centred on it — the pie layout. */
-    RIGHT = "RIGHT"
-}
-/** How the category axis copes when labels outgrow their slots. */
-export declare enum ChartCategoryLabelMode {
-    /** Render every label that fits; otherwise show every nth. The default. */
-    AUTO = "AUTO",
-    /** Render every label, ellipsizing any that overflow its slot. */
-    TRUNCATE = "TRUNCATE",
-    /** Render every label unconditionally, overlap included. */
-    ALL = "ALL"
-}
-/**
- * Emphasis level of a rendered mark.
- *
- * Travels to the DOM as a `data-state` attribute rather than a styled-component
- * prop: `@linaria/react` skips prop filtering entirely for SVG tags (its
- * `allTagsSet` is built with a missing spread, so `has('rect')` is false and
- * `propsAsIs` turns on), which would forward a `$`-prefixed prop straight to the
- * DOM and trigger a React warning.
- */
-export declare enum ChartMarkState {
-    /** Full strength — the default, and the hovered category. */
-    ACTIVE = "active",
-    /** Softened, for marks outside the engaged series or category. */
-    MUTED = "muted",
-    /**
-     * Barely softened — a whisper of {@link MUTED}.
-     *
-     * Used where another affordance already carries the emphasis and strong
-     * muting would be a second, louder voice: BarChart's category axis dims
-     * like this because the cursor band is the highlight.
-     */
-    DIMMED = "dimmed"
-}
-/** Which pair of a rectangle's corners carries the radius. */
-export declare enum BarCorners {
-    /** Cap for a bar growing up from the baseline. */
-    TOP = "TOP",
-    /** Cap for a bar growing down from the baseline. */
-    BOTTOM = "BOTTOM",
-    /** Interior stack segment — square on both ends. */
-    NONE = "NONE"
-}
-/**
- * How bar values are scaled before rendering.
- *
- * Note there is no grouped-vs-stacked mode: with the group → bar → component
- * hierarchy, several `bars` in a group render side by side and several
- * `components` in a bar render on top of each other, so a chart can be grouped
- * and stacked at the same time.
- */
-export declare enum BarChartNormalization {
-    /** Plot raw values. */
-    NONE = "NONE",
-    /** Scale each bar's components to fill the axis — a 100% stacked chart. */
-    PERCENT = "PERCENT"
+/** Short titles beside the axes. */
+export interface ChartAxisLabels {
+    /** Title under the category axis. */
+    category?: string;
+    /** Title beside the value axis, rotated. */
+    value?: string;
 }
 /**
- * One stacked segment of a bar.
+ * Which marks a chart's `selection` covers. A descriptor: a mark matches when every field present
+ * matches it, and a field the mark does not have never excludes it.
  *
- * A bar with a single component is just a plain unstacked bar.
- */
-export interface BarChartComponentDatum<TComponentKey extends string = string> {
-    /** Identifies this segment; must be unique within its bar. */
-    key: TComponentKey;
-    /** Human-readable name, shown in the tooltip and legend. */
-    label: string;
-    /** Segment magnitude. Negative values stack below the zero baseline. */
-    value: number;
-    /** Palette slot override. Defaults to the segment's position in the palette. */
-    color?: ChartPalette;
-}
-/**
- * One bar within a group: a stack of components for a single metric.
- */
-export interface BarChartBarDatum<TMetric extends string, TComponentKey extends string = string> {
-    /** Which metric this bar represents, e.g. `"prospected"`. */
-    metric: TMetric;
-    /** Segments of the bar, stacked in array order outward from the baseline. */
-    components: BarChartComponentDatum<TComponentKey>[];
-}
-/**
- * One category on the x-axis, holding one bar per metric.
- */
-export interface BarChartGroupDatum<TMetric extends string, TComponentKey extends string = string> {
-    /** Label rendered beneath this group on the category axis. */
-    label: string;
-    /** Bars in this group, rendered left to right in array order. */
-    bars: BarChartBarDatum<TMetric, TComponentKey>[];
-}
-/** How the segments between points are interpolated. */
-export declare enum LineChartCurve {
-    /** Straight segments. */
-    LINEAR = "LINEAR",
-    /** Monotone cubic — smooth without overshooting the data. */
-    SMOOTH = "SMOOTH",
-    /** Right-angled steps. */
-    STEP = "STEP"
-}
-/** One point on a line. */
-export interface LineChartPointDatum {
-    /** Category this point sits on; must match a category on the axis. */
-    x: string;
-    /**
-     * Value on the value axis.
-     *
-     * `null` breaks the line into separate segments. That is deliberately not the
-     * same as `0`: a missing reading and a reading of zero are different claims,
-     * and plotting a gap as zero draws a spike to the baseline that never
-     * happened.
-     */
-    y: number | null;
-}
-/**
- * One line in a line chart.
- *
- * Carries no label or colour — those come from the chart's `series` record,
- * keyed by `metric`, so the legend, tooltip and stroke cannot disagree.
+ * ```ts
+ * { categoryKey: "00:00" }                      // the whole 00:00 column
+ * { seriesKey: "failed" }                       // every failure, all columns
+ * { categoryKey: "00:00", seriesKey: "failed" } // one segment
+ * ```
  */
-export interface LineChartLineDatum<TMetric extends string> {
-    /** Which metric this line represents. Must be a key of the `series` record. */
-    metric: TMetric;
-    /**
-     * Points in category order.
-     *
-     * Sparse series are fine — categories absent here are treated as gaps, and
-     * the category axis is the union across every line.
-     */
-    points: LineChartPointDatum[];
-    /** Stroke width in px. Defaults to the shared line width. */
-    strokeWidth?: number;
-    /** Dash length in px. Solid when omitted. */
-    dashSize?: number;
-    /** Fill the area between the line and the baseline. */
-    showArea?: boolean;
+export interface ChartSelection<TSeriesKey extends string = string> {
+    /** Raw category label, never `labelFormatter` output (the vocabulary `ChartGroupProvider` matches on). */
+    categoryKey?: string;
+    /** What this chart's legend names: metrics, stack components or slices. */
+    seriesKey?: TSeriesKey;
 }
+/** One descriptor, several, or none. */
+export type ChartSelectionInput<TSeriesKey extends string = string> = ChartSelection<TSeriesKey> | ChartSelection<TSeriesKey>[] | null;
 /**
- * One slice of a pie or donut.
- *
- * Carries no label or colour — those come from the chart's `series` record,
- * keyed by `key`, so the legend, tooltip and arc cannot disagree.
+ * What a click (or Enter / Space on the active category) reports. Its fields are exactly those a
+ * `ChartSelection` is built from, so feeding an event back as a selection is the common case.
  */
-export interface PieChartSliceDatum<TSlice extends string> {
-    /** Which slice this is. Must be a key of the `series` record. */
-    key: TSlice;
-    /**
-     * Slice magnitude.
-     *
-     * A pie shows parts of a whole, so negative values have no meaning here and
-     * are coerced to zero rather than silently inverting an arc.
-     */
-    value: number;
+export interface ChartSelectionEvent<TSeriesKey extends string = string> {
+    /** Position of the category on the axis, from 0. */
+    categoryIndex: number;
+    /** Raw category label, matching `ChartSelection.categoryKey`. */
+    categoryKey: string;
+    /** The mark's series. Absent when the category, not one mark, was chosen. */
+    seriesKey?: TSeriesKey;
+    /** The mark's own value. Absent whenever `seriesKey` is. */
+    value?: number;
 }
-/** One label/value row in the tooltip. */
+/** One label / value row in the tooltip. */
 export interface ChartTooltipRow {
     /** React key, unique within the tooltip. */
     key: string;
-    /** Row label — a component label, line label or slice label. */
+    /** Series (or slice) label. */
     label: string;
-    value: number;
-    /** Already run through the resolved formatter. */
+    /** The reading; `null` is a gap and reads "—". */
+    value: number | null;
+    /** `value` already run through the chart's `valueFormatter` ("—" for a gap). */
     formattedValue: string;
+    /** Swatch color: a `var(--gx-…)` string or the series `hex`. */
     color: string;
 }
-/** Everything the tooltip needs to render, independent of chart type. */
+/** Everything the tooltip shows, independent of chart type. */
 export interface ChartTooltipModel {
-    /** Heading — the hovered category, or the slice label for a pie. */
+    /** Heading: the formatted category, or the slice label for a pie. */
     label: string;
+    /** One row per series at the category. Never empty when passed to `renderTooltip`. */
     rows: ChartTooltipRow[];
-    /** Anchor in container coordinates, margins already applied. */
+    /** Anchor x in plot-box coordinates. */
     anchorX: number;
+    /** Anchor y in plot-box coordinates. */
     anchorY: number;
 }
+/** Replaces the tooltip body; positioning stays with the chart. Never called with empty `rows`. */
+export type ChartTooltipRenderer = (model: ChartTooltipModel) => ReactNode;
 /**
- * A tooltip model whose anchor is still in plot coordinates.
- *
- * Structurally identical to {@link ChartTooltipModel} — the difference is the
- * coordinate space, which TypeScript cannot enforce. It carries its own name
- * anyway, because `ChartFrame` accepting "container coordinates" and then adding
- * a margin to them is exactly the sort of thing a reader has to be able to see
- * from the signature.
- *
- * Charts build this; `ChartFrame` applies the margin translate once, in the
- * component that already owns the `<g transform>`.
+ * @internal A tooltip model whose anchor is still in plot (inset) coordinates. Charts build this;
+ * `ChartFrame` adds the insets once.
  */
 export interface ChartPlotTooltipModel {
+    /** Heading. */
     label: string;
+    /** Rows; empty means "No data". */
     rows: ChartTooltipRow[];
-    /** Anchor in plot coordinates. */
+    /** Anchor x in plot coordinates. */
     anchorX: number;
+    /** Anchor y in plot coordinates. */
     anchorY: number;
 }
 /**
- * Render prop for replacing the tooltip body. Positioning stays with the chart.
- *
- * Never called with empty `rows` — with a custom renderer installed, a
- * hovered category with no data opens no tooltip at all (the built-in body
- * is the one that knows how to say "No data") — so `rows[0]`-style
- * assumptions are safe here.
- */
-export type ChartTooltipRenderer = (model: ChartTooltipModel) => ReactNode;
-/** Which shape a category's hit target is drawn as. */
-export declare enum ChartTargetShape {
-    /** Cartesian charts: a full-height band over the category. */
-    RECT = "RECT",
-    /** Radial charts: the arc's own outline, redrawn transparent. */
-    PATH = "PATH"
-}
-/**
- * One category's interactive target, in plot coordinates.
- *
- * Array position *is* the category index — already true of every geometry
- * builder's output — so there is no index field that could fall out of step.
- * `key` is carried separately because a pie's arcs reorder, where bar and line
- * indices do not.
+ * @internal One category's hover target, in plot coordinates. Array position is the category
+ * index; `key` is separate because a pie's arcs reorder.
  */
 export type ChartCategoryTarget = {
     key: string;
@@ -363,20 +222,11 @@ export type ChartCategoryTarget = {
     d: string;
 };
 /**
- * One rendered mark's own target, in plot coordinates.
- *
- * Drawn above the category targets and bound to *clicks* only. Hover stays
- * per category — crossing between two segments of one stack re-enters the
- * category the pointer already had, so the tooltip holds still. That banding is
- * why a two-pixel segment is as easy to hover as a two-hundred-pixel one, and a
- * click layer laid over it must not undo it.
- *
- * Unlike {@link ChartCategoryTarget}, array position says nothing about the
- * category here, so each target names its own.
+ * @internal One mark's click target, drawn above the category targets. Hover stays per category;
+ * this layer only refines the click.
  */
 export type ChartMarkTarget = {
     key: string;
-    /** The category this mark sits in — its hover, and its selection event. */
     categoryIndex: number;
     shape: ChartTargetShape.RECT;
     x: number;
@@ -389,189 +239,70 @@ export type ChartMarkTarget = {
     shape: ChartTargetShape.PATH;
     d: string;
 };
-/**
- * Which marks a chart's `selection` covers.
- *
- * A *descriptor* rather than a coordinate: a mark matches when every field
- * present matches it, and a field the mark has no notion of never excludes it.
- * One shape therefore spells every granularity without a mode flag —
- *
- * ```ts
- * { categoryKey: "00:00" }                      // the whole 00:00 column
- * { seriesKey: "failed" }                       // every failure, all columns
- * { categoryKey: "00:00", seriesKey: "failed" } // one segment
- * ```
- *
- * — and that last rule is what stops a category selection from muting a
- * LineChart's strokes, which span every category and belong to none.
- */
-export interface ChartSelection<TSeriesKey extends string = string> {
-    /**
-     * Raw category label, never `labelFormatter` output — the same vocabulary
-     * `ChartGroupProvider` matches on, for the same reason: two charts formatting
-     * one label differently must still agree on what it names.
-     */
-    categoryKey?: string;
-    /**
-     * Whatever this chart's legend names: components in a stacked bar, metrics in
-     * an unstacked one or a line chart, slices in a pie. The same key the mute
-     * axis uses, so a selection and the legend cannot describe different things.
-     */
-    seriesKey?: TSeriesKey;
-}
-/** One descriptor, several, or none. */
-export type ChartSelectionInput<TSeriesKey extends string = string> = ChartSelection<TSeriesKey> | ChartSelection<TSeriesKey>[] | null;
-/**
- * What a click reports.
- *
- * Deliberately thin — no rows, no colors, no formatted strings. The caller
- * already holds the data it passed in and can look the rest up by key, and a
- * presentation-shaped payload is the kind that becomes load-bearing and then
- * cannot be changed. The fields are exactly those a {@link ChartSelection} is
- * built from, so feeding an event straight back as one is the common case.
- */
-export interface ChartSelectionEvent<TSeriesKey extends string = string> {
-    categoryIndex: number;
-    /** Raw label, matching {@link ChartSelection.categoryKey}. */
-    categoryKey: string;
-    /** Absent when the click landed on empty plot rather than on a mark. */
-    seriesKey?: TSeriesKey;
-    /** The mark's own value, before any normalization. Absent whenever
-     * {@link seriesKey} is. */
-    value?: number;
-}
-/** One legend entry. */
+/** @internal One legend entry: the swatch inputs, not a resolved color. */
 export interface ChartLegendItem {
+    /** Series key; isolates the series on hover. */
     key: string;
+    /** Series label. */
     label: string;
-    color: string;
-}
-/** Fixed-size chart: both dimensions given in px. */
-export interface ChartFixedSize {
-    fillWidth?: false;
-    fillHeight?: false;
-    width: number;
-    height: number;
-    aspectRatio?: never;
-}
-/** Container-width chart with an explicit height. */
-export interface ChartFluidFixedHeight {
-    fillWidth: true;
-    fillHeight?: false;
-    width?: never;
-    height: number;
-    aspectRatio?: never;
-}
-/** Container-width chart whose height follows its width. */
-export interface ChartFluidRatioHeight {
-    fillWidth: true;
-    fillHeight?: false;
-    width?: never;
-    height?: never;
-    /** Width ÷ height. `2` is a 2:1 landscape plot. */
-    aspectRatio: number;
-}
-/** Fixed-width chart that takes its height from the container. */
-export interface ChartFixedWidthFluidHeight {
-    fillWidth?: false;
-    fillHeight: true;
-    width: number;
-    height?: never;
-    aspectRatio?: never;
-}
-/** Chart that fills its container on both axes — a dashboard tile. */
-export interface ChartFluidBothAxes {
-    fillWidth: true;
-    fillHeight: true;
-    width?: never;
-    height?: never;
-    aspectRatio?: never;
+    /** Palette slot of the swatch, when the series has no `hex`. */
+    palette?: ChartPalette;
+    /** Raw swatch color; wins over `palette`. */
+    hex?: Hex;
 }
-/**
- * The five legal ways to size a chart.
- *
- * A union rather than independent optional props, because the failure mode of
- * the optional version is a chart that resolves to 0×0 and renders as nothing at
- * all, with no error anywhere. Here `<BarChart fillWidth />` with neither
- * `height` nor `aspectRatio` simply does not compile, and neither does
- * `fillHeight` alongside a `height` that would contradict it.
- *
- * **`fillHeight` is not the mirror of `fillWidth`, and carries a requirement the
- * type system cannot check.** Width flows down from the parent, so `fillWidth`
- * is satisfied by any block container. Height flows *up* from content, so
- * `fillHeight` needs an ancestor with a definite height — an explicit size, a
- * flex or grid track, or absolute positioning. Given one, the chart fills it;
- * given a content-sized parent there is nothing to fill and the chart collapses,
- * which `useChartDimensions` warns about in development.
- */
-export type ChartSize = ChartFixedSize | ChartFluidFixedHeight | ChartFluidRatioHeight | ChartFixedWidthFluidHeight | ChartFluidBothAxes;
-/**
- * Props common to every chart.
- *
- * Data props are declared per chart, since their shapes and generics differ.
- */
-export interface BaseChartProps {
-    /** Space around the plot area. Merged over the defaults. */
-    margin?: Partial<ChartMargin>;
-    /** Built-in value format. Ignored when `valueFormatter` is given. */
-    valueUnit?: ChartValueUnit;
-    /** Full control over value rendering. Wins over `valueUnit`. */
+/** Props every chart takes (the shared vocabulary in `chartgroupprovider.md`). */
+export interface BaseChartProps<TKey extends string> extends AriaAttributes {
+    /**
+     * Formats values on the value axis, in the tooltip and in the keyboard announcement.
+     * @default (value) => formatNumber(value, { precision: 2 })
+     */
     valueFormatter?: ChartValueFormatter;
     /**
-     * Format category labels, wherever a category is named.
-     *
-     * That is the axis and the tooltip heading on the cartesian charts, and
-     * additionally the legend on a pie — whose legend lists *slices*, which are
-     * its categories. Bar and line legends name series, which come from the
-     * `series` record and are not categories, so this does not reach them.
+     * Shows the legend (beneath the plot; beside it for PieChart). Entries that do not fit collapse behind "+N more".
+     * @default true
      */
-    labelFormatter?: ChartLabelFormatter;
-    /** Replace the tooltip body. Collision handling stays with the chart. */
-    tooltipRenderer?: ChartTooltipRenderer;
-    /** Suppress the tooltip and its hit targets entirely. */
-    noTooltip?: boolean;
+    hasLegend?: boolean;
     /**
-     * Cap on tooltip rows. Rows past the cap collapse into an inert "+N more"
-     * line. Applies to the built-in body only; a custom `tooltipRenderer`
-     * receives the full model. Clamped to at least 1.
+     * Shows the tooltip on hover and keyboard focus. With `false` and no `onSelect`, the plot is a static image.
+     * @default true
      */
-    tooltipMaxItems?: number;
-    /** Show the legend beneath the plot. */
-    showLegend?: boolean;
+    hasTooltip?: boolean;
+    /** Replaces the tooltip body; positioning stays with the chart. Never called with empty rows. */
+    renderTooltip?: ChartTooltipRenderer;
     /**
-     * Stricter cap on inline legend entries, on top of the automatic fit. The
-     * legend never outgrows the plot: a horizontal legend holds one line of the
-     * plot's width, a side-placed legend one column of the plot's height, and
-     * entries that would not fit collapse behind a "+N more" trigger whose
-     * tooltip lists them — still hoverable, so a collapsed series isolates
-     * exactly like a visible one. This prop only lowers the inline count
-     * further.
+     * With no data yet, a `Skeleton` fills the plot; with data, marks recede and interaction pauses until it clears. Sets `aria-busy`.
+     * @default false
      */
-    legendMaxItems?: number;
-    /** Render the loading treatment instead of the data. */
     isLoading?: boolean;
-    /** Shown when there is nothing to plot. Defaults to a centred "No data". */
-    contentWhenEmpty?: ReactNode;
-    /** Accessible name for the chart. */
+    /**
+     * Header of the `EmptyState` shown in the plot when there is nothing to plot.
+     * @default No data available
+     */
+    placeholder?: string;
+    /** Called when a mark or category is clicked, or Enter / Space is pressed on the active category. Supplying it makes the plot selectable. */
+    onSelect?: (event: ChartSelectionEvent<TKey>) => void;
+    /** Which marks read as selected: matching marks hold full strength, the rest recede. Presentational; the chart never writes it. */
+    selection?: ChartSelectionInput<TKey>;
+    /** Accessible name of the chart. @default derived, e.g. Line chart, 12 categories, 3 series */
     ariaLabel?: string;
-    /** Longer description, associated via `aria-describedby`. */
-    ariaDescription?: string;
-}
-/**
- * Props shared by the two cartesian charts (bar and line).
- *
- * Composed into each chart's props with `&` rather than `extends`, since
- * {@link ChartSize} is a union and an interface cannot extend one.
- */
-export interface BaseCartesianChartProps extends BaseChartProps {
-    /** Draw horizontal grid lines at each value tick. */
-    showGrid?: boolean;
-    /** Override the computed value axis domain and tick count. */
+    /** DOM id on the root `<div>`. */
+    id?: string;
+    /** Any `data-*` attribute, forwarded to the root `<div>`. */
+    [dataAttribute: `data-${string}`]: string | number | boolean | undefined;
+    /** Extra class on the root `<div>`. */
+    className?: string;
+    /** Inline style on the root `<div>`; only for setting CSS custom properties. */
+    style?: CSSProperties;
+}
+/** Props the cartesian charts (Line, Area, Bar) add to `BaseChartProps`. */
+export interface BaseCartesianChartProps<TKey extends string> extends BaseChartProps<TKey> {
+    /**
+     * Formats category labels on the axis and in the tooltip heading. Sync and selection still match raw labels.
+     * @default (label) => label
+     */
+    labelFormatter?: ChartLabelFormatter;
+    /** Overrides the value axis `min`, `max` and approximate `tickCount`. @default derived from the data, always including 0 */
     valueDomain?: Partial<ChartValueDomain>;
-    /** How the category axis handles labels too long or too many to fit. */
-    categoryLabelMode?: ChartCategoryLabelMode;
-    /** Title rendered alongside the category axis. */
-    categoryAxisTitle?: string;
-    /** Title rendered alongside the value axis. */
-    valueAxisTitle?: string;
+    /** Short titles beside the category axis and the value axis. */
+    axisLabels?: ChartAxisLabels;
 }