@galaxy-io/dls 1.2.6 → 1.3.0

package/dist/charts/types.d.ts

@@ -1,80 +1,548 @@
 import type { ReactNode } from "react";
-/** A single data point with a category label and series values */
-export interface ChartDatum {
-    /** Category label (x-axis for bar/line, slice label for pie) */
-    label: string;
-    /** Numeric values keyed by series key. e.g. { revenue: 150, cost: 80 } */
-    values: Record<string, number>;
+/**
+ * Shared types for the chart components (`BarChart`, `LineChart`, `PieChart`).
+ *
+ * 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.
+ *
+ * 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"'.
+ *   ]}
+ * />
+ * ```
+ *
+ * The same union then makes aggregates exhaustive, spell-checks legend and
+ * ordering props, and narrows callback parameters for `ts-pattern`.
+ */
+/**
+ * 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.
+ */
+export declare enum ChartPalette {
+    PURPLE = "PURPLE",
+    PINK = "PINK",
+    BLUE = "BLUE",
+    TEAL = "TEAL",
+    LIME = "LIME",
+    ORANGE = "ORANGE",
+    YELLOW = "YELLOW",
+    GREEN = "GREEN",
+    RED = "RED"
 }
-/** Describes one series in the chart */
-export interface ChartSeriesConfig {
-    /** Unique key matching a key in ChartDatum.values */
-    key: string;
-    /** Human-readable name shown in legend/tooltip */
-    name: string;
-    /** Override color (hex). Falls back to palette order. */
-    color?: string;
-}
-/** A single slice in a pie/donut chart */
-export interface PieSlice {
-    /** Slice label shown in legend/tooltip */
+/**
+ * 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"
+}
+export type ChartValueFormatter = (value: number) => string;
+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.
+ */
+export interface ChartSeriesStyle {
+    /** Name shown in the legend, tooltip and accessible labels. */
     label: string;
-    /** Numeric value determining slice size */
-    value: number;
-    /** Override color (hex). Falls back to palette order. */
-    color?: string;
+    /**
+     * Palette slot. Defaults to the series' position in the record, walked
+     * through `CHART_PALETTE_ORDER`.
+     */
+    color?: ChartPalette;
 }
+/**
+ * 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*.
+ */
+export type ChartSeriesStyles<TKey extends string> = Record<TKey, ChartSeriesStyle>;
 export interface ChartMargin {
     top: number;
     right: number;
     bottom: number;
     left: number;
 }
-export type ChartValueFormatter = (value: number) => string;
-export type ChartLabelFormatter = (label: string) => string;
-export interface ChartTooltipItem {
-    seriesKey: string;
-    seriesName: string;
+/** Override for the computed value axis domain. */
+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()`. */
+    tickCount: number;
+}
+/** 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 or pinned category. */
+    ACTIVE = "active",
+    /** Softened, for categories other than the hovered one. */
+    MUTED = "muted",
+    /** Furthest back, for categories outside a pinned one. */
+    FADED = "faded"
+}
+/** 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"
+}
+/**
+ * One stacked segment of a bar.
+ *
+ * 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, TPivot extends string = string, TComponentKey extends string = string> {
+    /** Which metric this bar represents, e.g. `"prospected"`. */
+    metric: TMetric;
+    /** Optional dimension the bar is split by, e.g. `"persona"`. */
+    pivot?: TPivot;
+    /** 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, TPivot extends string = 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, TPivot, TComponentKey>[];
+}
+/**
+ * A single rendered rectangle.
+ *
+ * The geometry layer flattens the group/bar/component hierarchy into an array
+ * of these, so rendering is a plain `.map()` with no nested loops or
+ * accumulators in the component body.
+ */
+export interface BarChartRect<TMetric extends string, TComponentKey extends string = string> {
+    /**
+     * React key: `${groupIndex}:${barIndex}:${componentKey}`.
+     *
+     * Deliberately index-based rather than label-based — group labels are free to
+     * repeat, and duplicated keys would silently drop rectangles.
+     */
+    id: string;
+    groupIndex: number;
+    barIndex: number;
+    metric: TMetric;
+    componentKey: TComponentKey;
+    /** The component's label, carried through for the tooltip. */
+    label: string;
+    /** The raw value, before any normalization. */
     value: number;
+    /**
+     * The `[from, to]` interval this segment occupies in value space.
+     * Under {@link BarChartNormalization.PERCENT} this is normalized to 0–1.
+     */
+    valueRange: [number, number];
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Resolved from the theme — never a raw hex from consumer data. */
     color: string;
+    /** Interior stack segments get {@link BarCorners.NONE}. */
+    corners: BarCorners;
+    /** Corner radius in px, reduced for narrow bars so the curve can't dominate. */
+    radius: number;
 }
-export interface ChartTooltipData {
-    /** The category label */
+/**
+ * A category's invisible hit target and tooltip anchor.
+ *
+ * Hit testing happens per group rather than per rectangle: a two-pixel bar is
+ * then exactly as hoverable as a two-hundred-pixel one, and moving the pointer
+ * between segments inside one group fires nothing, so the tooltip stays put
+ * instead of jumping between segment tops.
+ */
+export interface BarChartGroupBand {
+    groupIndex: number;
     label: string;
-    /** Series values for this datum */
-    items: ChartTooltipItem[];
-    /** Pixel position for tooltip anchor */
+    /** Tiles edge to edge with its neighbours, so there are no dead gutters. */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Group centre, at the top of its tallest bar. Stable while hovering. */
+    anchorX: number;
+    anchorY: number;
+    /** True when every component in the group is zero or absent. */
+    isEmpty: boolean;
+}
+/** 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.
+ */
+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;
+}
+/** One line, resolved to SVG paths. */
+export interface LineChartPath<TMetric extends string> {
+    /** React key. Equal to the metric, which is unique by construction. */
+    id: string;
+    metric: TMetric;
+    lineIndex: number;
+    /** `d` for the stroke. Empty when the line has no plottable points. */
+    path: string;
+    /** `d` for the area fill. Present only when the line opted into an area. */
+    areaPath?: string;
+    /** Pre-serialised `stroke-dasharray`. Absent for a solid line. */
+    dashArray?: string;
+    strokeWidth: number;
+    color: string;
+}
+/** One point, resolved to pixels. */
+export interface LineChartPoint<TMetric extends string> {
+    /** React key. `${metric}:${categoryIndex}`. */
+    id: string;
+    metric: TMetric;
+    categoryIndex: number;
+    value: number;
     x: number;
     y: number;
+    color: string;
+}
+/**
+ * One category column: the hit target and everything the tooltip needs.
+ *
+ * Line charts hit-test by column rather than by proximity to a stroke, so the
+ * whole vertical band is a target and the tooltip reports every line at once.
+ */
+export interface LineChartColumn<TMetric extends string> {
+    categoryIndex: number;
+    label: string;
+    /** x of the category tick. */
+    x: number;
+    /** Full-height hit target, tiling with its neighbours. */
+    bandX: number;
+    bandWidth: number;
+    /** Points present in this column, one per line that has a value here. */
+    points: LineChartPoint<TMetric>[];
+    /** Topmost point in the column — where the tooltip anchors. */
+    anchorY: number;
+}
+/**
+ * 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.
+ */
+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;
+}
+/** React key used for the bucket that absorbs slices below the fold threshold. */
+export declare const AGGREGATED_SLICE_KEY = "__other__";
+/** One rendered arc. */
+export interface PieChartArc<TSlice extends string> {
+    /** React key. The slice key, or {@link AGGREGATED_SLICE_KEY}. */
+    id: string;
+    /**
+     * The originating slice, or `null` for the aggregated bucket.
+     *
+     * Nullable rather than widened to `string` so callers must acknowledge the
+     * synthetic arc instead of accidentally treating it as a real slice key.
+     */
+    sliceKey: TSlice | null;
+    label: string;
+    /** Summed value for the aggregated bucket, the slice's own otherwise. */
+    value: number;
+    /** Share of the total, 0–1. */
+    share: number;
+    /** `d` for the arc. */
+    path: string;
+    /** Radians, clockwise from 12 o'clock. */
+    startAngle: number;
+    endAngle: number;
+    /** Anchor for the tooltip, just outside the arc's outer edge. */
+    anchorX: number;
+    anchorY: number;
+    color: string;
+    /** True for the bucket produced by folding small slices together. */
+    isAggregated: boolean;
+}
+/** 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. */
+    label: string;
+    /** Optional grouping label, used when bars are split by a pivot. */
+    group?: string;
+    value: number;
+    /** Already run through the resolved formatter. */
+    formattedValue: string;
+    color: string;
+}
+/** Everything the tooltip needs to render, independent of chart type. */
+export interface ChartTooltipModel {
+    /** Heading — the hovered category, or the slice label for a pie. */
+    label: string;
+    rows: ChartTooltipRow[];
+    /** Anchor in container coordinates, margins already applied. */
+    anchorX: number;
+    anchorY: number;
+}
+/**
+ * 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>`.
+ */
+export interface ChartPlotTooltipModel {
+    label: string;
+    rows: ChartTooltipRow[];
+    /** Anchor in plot coordinates. */
+    anchorX: number;
+    anchorY: number;
 }
-/** Custom render function for tooltip body */
-export type ChartTooltipRenderer = (data: ChartTooltipData) => ReactNode;
-/** Base props shared by all chart components */
+/** Render prop for replacing the tooltip body. Positioning stays with the chart. */
+export type ChartTooltipRenderer = (model: ChartTooltipModel) => ReactNode;
+/** One legend entry. */
+export interface ChartLegendItem {
+    key: string;
+    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;
+}
+/**
+ * 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 {
-    /** The data to render */
-    data: ChartDatum[];
-    /** Series configuration (order determines stacking/legend order) */
-    series: ChartSeriesConfig[];
-    /** Chart width in pixels. Optional when fillWidth is true. */
-    width?: number;
-    /** Chart height in pixels. Optional when aspectRatio is provided. */
-    height?: number;
-    /** Margins around the plot area */
+    /** Space around the plot area. Merged over the defaults. */
     margin?: Partial<ChartMargin>;
-    /** When true, chart fills container width */
-    fillWidth?: boolean;
-    /** Aspect ratio (width/height). Used to auto-calculate height when fillWidth is true. */
-    aspectRatio?: number;
-    /** Format y-axis / value labels. Default: toLocaleString() */
+    /** Built-in value format. Ignored when `valueFormatter` is given. */
+    valueUnit?: ChartValueUnit;
+    /** Full control over value rendering. Wins over `valueUnit`. */
     valueFormatter?: ChartValueFormatter;
-    /** Format x-axis / category labels. Default: identity */
+    /** Format category labels. Applied to the axis *and* the tooltip heading. */
     labelFormatter?: ChartLabelFormatter;
-    /** Custom tooltip renderer. If omitted, uses default ChartTooltip */
+    /** Replace the tooltip body. Collision handling stays with the chart. */
     tooltipRenderer?: ChartTooltipRenderer;
-    /** Disable tooltip entirely */
+    /** Suppress the tooltip and its hit targets entirely. */
     noTooltip?: boolean;
-    /** Show legend */
+    /** Show the legend beneath the plot. */
     showLegend?: boolean;
-    /** Accessible label for the chart SVG */
+    /** 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. */
     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. */
+    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;
 }