@eifi1/ui-kit 0.7.0 → 0.8.0

package/dist/components/series-chart.d.ts

@@ -1,7 +1,9 @@
 import * as react from 'react';
-import { ReactNode } from 'react';
-import { ZoomBinding } from './chart-zoom.js';
+import { ReactNode, RefObject } from 'react';
+import { ZoomAxesSetting, ZoomBinding } from './chart-zoom.js';
+import { LegendEntry } from './toggle-legend.js';
 import { SeriesChartLabels } from './series-chart-labels.js';
+import { TimeTickUnit } from './series-chart-ticks.js';
 import 'recharts';
 
 interface SeriesChartSeries {
@@ -16,15 +18,93 @@ interface SeriesChartSeries {
      *  reference against the measurement. Shorthand for `dash: 1`. */
     dashed?: boolean;
     /** Which of {@link STROKE_PATTERNS} this line takes, for charts where the stroke says
-     *  WHICH QUANTITY and the colour says WHICH MEASUREMENT. */
-    dash?: number;
+     *  WHICH QUANTITY and the colour says WHICH MEASUREMENT.
+     *
+     *  Or an SVG `stroke-dasharray` string of the caller's own, for a pattern the five do
+     *  not have: keksdose's `"4 3"`, a tighter dash than the ladder's `"5 4"` that its
+     *  hand-drawn recharts lines used before the kit. The legend
+     *  entry ({@link seriesLegendEntries}) carries the same string, so it draws the same
+     *  pattern. */
+    dash?: number | string;
     /** `stepAfter`, for a whole-number channel that jumps rather than travels — a
      *  straight line between index 0 and index 1 draws an index of 0.5, which does not
      *  exist. Drawn in the {@link STEP_DASH} pattern, whatever `dash` says. */
     step?: boolean;
     /** Which of `axes` this line is measured on. Default: `"y"`, the single one. */
     axis?: string;
+    /**
+     * The mark. `"line"` (the default) is what every chart before 0.8.0 drew. `"bar"` and
+     * `"area"` are read as a LENGTH from zero, so the axis they stand on always includes
+     * zero (see `SeriesChartAxis.includeZero`) and the zoom treats them differently (see
+     * `defaultZoomAxes`). Bars without a `stack` stand side by side in each slot — the
+     * grouped bars of keksdose's payee report.
+     */
+    type?: SeriesChartType;
+    /**
+     * Bars or areas with the same `stack` are drawn on top of each other and the axis is
+     * fitted to their SUM (positive and negative layers apart, like recharts'
+     * `stackOffset="sign"`). keksdose's spending-by-category area. Ignored on a line:
+     * recharts cannot stack one.
+     */
+    stack?: string;
+    /**
+     * Marks on the line's (or area's) points. `true` rings every sample — the price
+     * history, where a shop has a value only on the days somebody shopped there and the
+     * dots are the only thing saying which points were MEASURED. A function decides per
+     * point: `true` for the default dot, `false`/`null` for none, or any SVG node drawn
+     * as-is at `point.cx`/`point.cy` — a buy/sell marker on keksdose's paper price.
+     * Never called for a point with no value. Bars have no points, and ignore it.
+     */
+    dot?: boolean | ((point: SeriesChartPoint) => ReactNode);
+    /** Line (or area outline) weight in px. Default 2, or 1.5 for a `step`. keksdose
+     *  draws the subject of a chart at 2.5 and the reference it is read against at 1.5. */
+    strokeWidth?: number;
+    /** `"linear"` for a line that must not look smoothed — keksdose's cash-buffer
+     *  PROJECTION, a straight extrapolation that a monotone curve would dress up as data.
+     *  Default `"monotone"`; `step` wins over both. */
+    curve?: "monotone" | "linear";
+    /** An area's or bar's fill opacity. Default: 1 for a bar, 0.55 for a stacked area
+     *  (the layers must stay tellable apart where they meet) and 0.2 for a single one. */
+    fillOpacity?: number;
+    /**
+     * The dot that follows the pointer along a line or an area. `false` takes it off a
+     * series that is not a measurement — keksdose's cash-buffer PROJECTION, where a hover
+     * ring on the extrapolated line reads as a sampled value (`cash-buffer-chart.tsx`).
+     * `{ r }` sets its radius. Default: recharts' dot. Bars have none, and ignore it.
+     */
+    activeDot?: boolean | {
+        r?: number;
+    };
+}
+/** What a series draws. See {@link SeriesChartSeries.type}. */
+type SeriesChartType = "line" | "bar" | "area";
+/** One point of a series, as a `dot` function is handed it. */
+interface SeriesChartPoint {
+    /** The series' key. */
+    key: string;
+    /** The row's position in `rows`. */
+    index: number;
+    /** The caller's own row, with everything the chart did not plot still in it. */
+    row: SeriesChartRow;
+    /** The abscissa in the caller's terms: the number, the category, or (time) a Date. */
+    x: SeriesChartXValue;
+    value: number;
+    /** Where the point is drawn, in the chart's pixels. */
+    cx: number;
+    cy: number;
+    /** The series' paint, `var(--color-<key>)`. */
+    color: string;
 }
+/** A row of a series chart: one abscissa value and the series' values at it. Anything
+ *  else in it (a raw ISO period for a drilldown) rides along untouched and is handed
+ *  back in {@link SeriesChartPoint.row} and {@link SeriesChartHit.row}. */
+type SeriesChartRow = Readonly<Record<string, unknown>>;
+/** An abscissa value: a number (`x.type: "number"`), a category (a string, a number or
+ *  a Date standing for a period), or a time (a Date, epoch ms or an ISO string). */
+type SeriesChartXValue = number | string | Date;
+/** Ticks a caller decides — a list, or a function of the domain on show, so a zoom
+ *  window gets ticks from the same rule instead of none. */
+type SeriesChartTickValues<T> = readonly T[] | ((domain: [number, number]) => readonly T[] | undefined);
 interface SeriesChartAxisShape {
     id: string;
     /**
@@ -49,6 +129,21 @@ interface SeriesChartAxisShape {
      *  tooltip gets it from `valueFormat`. Default: `Intl.NumberFormat` in the kit's
      *  locale, up to two fraction digits. */
     format?: (value: number) => string;
+    /**
+     * The tick values, instead of the round ones the chart picks. For a grid the DATA
+     * dictates — keksdose's price axes tick on whole cents (`pricePaddedDomain`), where a
+     * 1/2/5 ladder would print €1.25 under a formatter that can only say €1.3. Values
+     * outside the domain on show are dropped; a function is asked again for every zoom
+     * window, so the cent grid can refine with it.
+     */
+    tickValues?: SeriesChartTickValues<number>;
+    /**
+     * Keep zero inside the fitted band. On by default for an axis carrying a bar or an
+     * area — their length IS the value, and a truncated baseline draws 40 as three times
+     * 20 — and off for lines, whose shape is the point (a stock price anchored at zero is
+     * a hairline). A pinned `domain` is left alone either way.
+     */
+    includeZero?: boolean;
 }
 /**
  * A y axis — and a VISIBLE one says what it measures.
@@ -66,21 +161,111 @@ type SeriesChartAxis = SeriesChartAxisShape & ({
     title?: string;
     hide: true;
 });
+/**
+ * What a tick or the tooltip heading of the abscissa is handed besides its position —
+ * the value in the caller's own terms, which on a category or time axis is not the
+ * number the plot runs on.
+ */
+interface SeriesChartXTick {
+    /** The number itself, the row's category, or (time) a Date. */
+    value: SeriesChartXValue;
+    /** The slot, on a category axis: the row's index in `rows`. */
+    index?: number;
+    /** On a time axis: what one step of the ticks on show is, so a label can say as much
+     *  as it means — a month start as "Mar 26", a midnight as "14 Mar". */
+    unit?: TimeTickUnit;
+}
 interface SeriesChartX {
+    /**
+     * What the abscissa is.
+     *
+     * - `"number"` (the default) — a number line, and all a chart before 0.8.0 could draw.
+     * - `"category"` — PERIODS or names, one evenly spaced slot per row, in row order:
+     *   keksdose's months, quarters and budget categories, which it used to hand recharts
+     *   preformatted. The values stay the caller's own — `"2026-05"`, a Date for the
+     *   month, a category name — and need not be sortable, unique or numeric. The plot
+     *   runs on the slot INDEX, which is what lets it zoom: a drag across the third to the
+     *   ninth month shows those months, a tick on each whole slot and the bars clipped at
+     *   the edge. What else zooms depends on the MARKS, not the axis — see `zoomAxes`.
+     * - `"time"` — real TIME: a Date, epoch ms or an ISO string per row, placed by when
+     *   it happened. keksdose's price history and cash buffer, where a slot per row would
+     *   draw two receipts a day apart and two five months apart the same width. Ticks fall
+     *   on calendar boundaries (midnights, Mondays, month and quarter starts, new years)
+     *   in local time; a date-only ISO string is LOCAL midnight, not the UTC one
+     *   `new Date("2026-05-01")` gives, which lands on the previous day west of Greenwich.
+     *   Zooms like a number line.
+     */
+    type?: "number" | "category" | "time";
     /** Row key of the abscissa. Default `"x"`, which is what {@link mergeSeries} writes. */
     key?: string;
     /** What the abscissa is, with its unit. Drawn under the axis. */
     title?: string;
-    /** A tick, formatted — bare, like the y axes'. */
-    format?: (value: number) => string;
+    /**
+     * A tick, formatted — bare, like the y axes'.
+     *
+     * `value` is the POSITION on the number line the plot runs on — the number itself,
+     * epoch ms, or the slot index — so the one-argument formatters every chart before
+     * 0.8.0 passes keep their meaning, and a time axis' `(ms) => …` is the tickFormatter
+     * keksdose already has. The caller's own value (the category, the Date) is `tick.value`.
+     * Default: the kit's number format; a category as is (a number formatted, a Date as a
+     * medium date); a time as much of the date as the tick step means.
+     */
+    format?: (value: number, tick: SeriesChartXTick) => string;
     /**
      * Whether this chart prints the abscissa's ticks. On by default; off for every chart
      * of a stack sharing one x window but the bottom one, which prints them for all. It
      * costs no alignment: the x mapping is decided by the margins and the y bands.
      */
     ticks?: boolean;
-    /** The tooltip's heading. Default: the abscissa value through `format`. */
-    label?: (value: number) => ReactNode;
+    /** The tooltip's heading. Default: `format` — or, on a time axis, a medium date (with
+     *  the time for hourly data), since a tick's "Mar 26" is not which day it was. */
+    label?: (value: number, tick: SeriesChartXTick) => ReactNode;
+    /** The ticks instead of the automatic ones, in the caller's terms: numbers, the
+     *  categories to label, or instants. See `SeriesChartAxis.tickValues`. */
+    tickValues?: SeriesChartTickValues<SeriesChartXValue>;
+    /**
+     * Tilt the tick labels by this many degrees — negative rises to the right. For long
+     * category names that do not fit side by side: keksdose's budget performance draws its
+     * categories at −45° (`budget-performance-tab.tsx`). The label is anchored by its END
+     * for a negative angle and its START for a positive one, so it hangs off the tick
+     * instead of being centred across it; the anchor is physical, like the plot (see
+     * `ChartContainer`), so it is the same in RTL. The band under the axis grows to the
+     * rotated height of the longest label on show, estimated from its length (at most
+     * 120 px, past which a label is clipped). Default 0.
+     */
+    tickAngle?: number;
+    /**
+     * On a `"number"` axis, tick only on whole numbers: a step of 1 at the least, so a
+     * five-point index series reads 0 1 2 3 4 rather than 0 0.5 1 … 4 — ticks at
+     * positions no row can have (keksdose's short step series). A zoom window that holds
+     * no whole number falls back to the ordinary ticks rather than to none.
+     *
+     * AUTOMATIC by default — on when every row's x is a whole number — because that is
+     * exactly the case the half ticks are wrong in, and it changes nothing elsewhere: a
+     * span wider than about eight already ticks on whole steps. `false` for a continuous
+     * quantity that merely happens to be sampled on whole numbers (1 Hz steps) and whose
+     * zoom should still be ruled in fractions; `true` to force it over rows that are not.
+     * Ignored on category (already one tick per slot) and time axes.
+     */
+    integerTicks?: boolean;
+}
+/** Room for the tooltip beyond the chart — see {@link SeriesChartProps.tooltip}. */
+interface SeriesChartTooltip {
+    /** Let the tooltip run past the chart's own box on that axis instead of recharts
+     *  clamping it inside. Default: `{ x: true }` when `boundary` is set, else neither. */
+    allowEscapeViewBox?: {
+        x?: boolean;
+        y?: boolean;
+    };
+    /**
+     * The element that actually CLIPS the chart — usually a horizontal-scroll wrapper
+     * around a chart wider than the card. The tooltip then flips to the left of the cursor
+     * when it would spill past that element's visible right edge (see
+     * `ChartTooltipContent`'s `boundaryRef`), rather than against the wide chart's far edge
+     * the reader has not scrolled to. keksdose's budget performance, which keeps a scroll
+     * wrapper and a per-category `minWidth` (`budget-performance-tab.tsx`).
+     */
+    boundary?: RefObject<HTMLElement | null>;
 }
 /**
  * A vertical segment in data coordinates — two y at one x, which a row-per-abscissa
@@ -99,9 +284,74 @@ interface SeriesChartSpan {
     /** Default: `var(--text-muted)`. */
     color?: string;
 }
+/** The colours a reference or a marker can take by name — the kit's semantic tokens,
+ *  so a threshold reads the same on every chart and flips with the theme. */
+type SeriesChartTone = "muted" | "brand" | "income" | "expense" | "net" | "success" | "warning" | "danger" | "info";
+/**
+ * A line across the whole plot at one value: a threshold, a target, an event.
+ *
+ * keksdose's cash buffer draws "one month of runway" across at y = 30 and the projected
+ * depletion date down at its x. Unlike a {@link SeriesChartSpan}, which closes a shape
+ * in data coordinates, a reference spans the plot, whatever the zoom.
+ *
+ * A reference is part of the FITTED band: one outside the data widens the axis to show
+ * it, because a threshold the reader cannot see is not a threshold. A pinned domain or a
+ * zoom window does not widen — there it is discarded when outside, like a span.
+ */
+interface SeriesChartReference {
+    /** Distinct within the chart. Default: its position in the list. */
+    key?: string;
+    /** `"x"` for a vertical line at an abscissa, otherwise the id of the y axis the value
+     *  is measured on. Default `"y"`, the single one — so no y axis may be called `"x"`. */
+    axis?: string;
+    /** An abscissa in the x axis' own terms (a category, a Date) for `axis: "x"`, a
+     *  number on that axis otherwise. A category the rows do not have draws nothing. */
+    value: SeriesChartXValue;
+    /** Written along the line, inside the plot at its top-left. SVG text: a string. */
+    label?: string;
+    /** Default `"muted"`. `color` wins over it. */
+    tone?: SeriesChartTone;
+    color?: string;
+    /** Which of `STROKE_PATTERNS`. Default 1, dashed: a reference is not data, and a
+     *  solid line reads as a series nobody put in the legend. */
+    dash?: number;
+}
+/**
+ * A single labelled point — today's figure on keksdose's cash buffer, the month the
+ * projection runs dry. For a mark on EVERY sample, or on the samples that meet a test,
+ * use the series' `dot` instead; a marker is for a point that is a fact of its own.
+ * Fitted like a reference: it widens the band it would otherwise fall outside of.
+ */
+interface SeriesChartMarker {
+    /** Distinct within the chart. Default: its position in the list. */
+    key?: string;
+    /** In the x axis' own terms, like a reference's `value`. */
+    x: SeriesChartXValue;
+    y: number;
+    /** The y axis `y` is measured on. Default `"y"`. */
+    axis?: string;
+    /** Written above the point. */
+    label?: string;
+    /** Default `"brand"`. `color` wins over it. */
+    tone?: SeriesChartTone;
+    color?: string;
+    /** Radius in px. Default 4.5. */
+    r?: number;
+}
+/** What a click on the plot picked. */
+interface SeriesChartHit {
+    /** The row's position in `rows`. */
+    index: number;
+    /** The caller's own row — with its `rawPeriod`, id or whatever the drilldown needs. */
+    row: SeriesChartRow;
+    x: SeriesChartXValue;
+    /** The series, when the click landed ON a bar. A click anywhere else picks the slot
+     *  (the period), not a series. */
+    key?: string;
+}
 interface SeriesChartProps {
     /** One row per abscissa value. A missing key is a hole (see `connectNulls`). */
-    rows: Record<string, number>[];
+    rows: readonly SeriesChartRow[];
     series: SeriesChartSeries[];
     /** Default: one untitled axis, `"y"`. */
     axes?: SeriesChartAxis[];
@@ -109,9 +359,13 @@ interface SeriesChartProps {
     /** A value in the tooltip, where a number stands on its own and needs its unit.
      *  Default: `Intl.NumberFormat` in the kit's locale. */
     valueFormat?: (value: number) => string;
-    /** Tailwind height class. Default `h-72`. The empty state takes it too, so a chart
-     *  losing its last line does not relayout the page under it. */
-    height?: string;
+    /** Tailwind height class, or a height in pixels. Default `h-72`. The empty state
+     *  takes it too, so a chart losing its last line does not relayout the page under it.
+     *  A number is for a height the caller holds as a number — keksdose's report charts
+     *  take `height = 260` as a prop and wrap the chart in a `SizedSeriesChart` div
+     *  (reports/charts/networth-line.tsx) only to turn it into a style, since a class
+     *  cannot be built from a number Tailwind never saw. */
+    height?: string | number;
     /** Bridge holes left by sources sampled on different grids. See {@link mergeSeries}. */
     connectNulls?: boolean;
     /** Shown, centred at the chart's height, instead of an empty chart. Default: the
@@ -124,6 +378,26 @@ interface SeriesChartProps {
      */
     animationMs?: number;
     spans?: SeriesChartSpan[];
+    /** Lines across the plot at one value. */
+    references?: SeriesChartReference[];
+    /** Single labelled points. */
+    markers?: SeriesChartMarker[];
+    /**
+     * Which axes a drag may zoom: `"both"`, `"x"`, `"y"` or `"none"`. Default: read off
+     * the marks — see `defaultZoomAxes` (lines both, areas x, bars none). An axis carrying
+     * bars or areas never takes a DRAGGED y window: it refits to the x window, from zero.
+     * Ignored by `StaticSeriesChart`, which does not zoom.
+     */
+    zoomAxes?: ZoomAxesSetting;
+    /**
+     * A click on the plot: the slot under the pointer, and the series when it landed on a
+     * bar. keksdose's drilldowns — a payee's month, a budget line, a spending category.
+     * A drag that zoomed is not a click.
+     */
+    onPointClick?: (hit: SeriesChartHit) => void;
+    /** Where the tooltip may go: for a chart inside a scroll wrapper. See
+     *  {@link SeriesChartTooltip}. */
+    tooltip?: SeriesChartTooltip;
     /** Supplied by `withChartZoom` and by nothing else. */
     zoom?: ZoomBinding;
     /** Per-chart strings over `<UiKitProvider labels={{ seriesChart }}>`. */
@@ -188,20 +462,41 @@ declare function mergeSeries(sources: SeriesSource[]): Record<string, number>[];
  * a digit or a hyphen gets a leading `_`.
  */
 declare function seriesKey(...parts: (string | number)[]): string;
+/**
+ * The band an axis carrying bars or areas draws: the data's extent with ZERO in it,
+ * padded only on the sides that are not zero — bars standing on a frame's bottom edge,
+ * not floating four per cent above it on a band of air nobody asked for.
+ * `undefined` when there is nothing to fit.
+ */
+declare function anchoredBand(extent: readonly [number, number] | undefined): [number, number] | undefined;
+/**
+ * Series with their colours settled BEFORE any are switched off.
+ *
+ * A series with no `color` takes `paletteFor(its position)` — and a legend toggle that
+ * hands the chart a shorter list moves every later series one position up, repainting
+ * it in its neighbour's colour on each click. Resolving the colours on the full list
+ * and filtering after keeps each series in the colour its legend entry shows.
+ */
+declare function visibleSeries(series: readonly SeriesChartSeries[], hidden: ReadonlySet<string>): SeriesChartSeries[];
+/**
+ * The `ToggleLegend` entries for a chart's FULL series list — colours resolved the way
+ * the chart resolves them, and a stroke mark for a line drawn in a pattern (dashed,
+ * step) so the key promises the stroke the plot draws. A bar or an area is a swatch.
+ * Pair with {@link visibleSeries} for the chart itself.
+ */
+declare function seriesLegendEntries(series: readonly SeriesChartSeries[]): LegendEntry[];
 /**
  * {@link SeriesChart} without the zoom: the same picture, no drag layer, no reset
  * button. For a thumbnail, a print view, or a chart the consumer wraps in its own
  * interaction.
  */
-declare function StaticSeriesChart({ rows, x, series, axes, valueFormat, height, connectNulls, empty, animationMs, spans, zoom, labels: labelsProp, locale, className, }: SeriesChartProps): react.JSX.Element;
+declare function StaticSeriesChart(props: SeriesChartProps): react.JSX.Element;
 /**
  * The series chart, zoomable. Drag across the plot to zoom (the drag's shape picks the
  * axes), double-click or press the reset button to go back; wrap several in
- * `SharedXZoom` to move their x windows together.
+ * `SharedXZoom` to move their x windows together. Which axes zoom depends on the marks
+ * — see {@link SeriesChartProps.zoomAxes}.
  */
-declare const SeriesChart: {
-    (props: SeriesChartProps): react.JSX.Element;
-    displayName: string;
-};
+declare function SeriesChart(props: SeriesChartProps): react.JSX.Element;
 
-export { AXIS_TICK_WIDTH, AXIS_TITLE_STRIP, SeriesChart, type SeriesChartAxis, type SeriesChartProps, type SeriesChartSeries, type SeriesChartSpan, type SeriesChartX, type SeriesSource, StaticSeriesChart, axisBandWidth, mergeSeries, oneAxis, padBand, paddedDomain, seriesKey, soleSeriesColor };
+export { AXIS_TICK_WIDTH, AXIS_TITLE_STRIP, SeriesChart, type SeriesChartAxis, type SeriesChartHit, type SeriesChartMarker, type SeriesChartPoint, type SeriesChartProps, type SeriesChartReference, type SeriesChartRow, type SeriesChartSeries, type SeriesChartSpan, type SeriesChartTickValues, type SeriesChartTone, type SeriesChartTooltip, type SeriesChartType, type SeriesChartX, type SeriesChartXTick, type SeriesChartXValue, type SeriesSource, StaticSeriesChart, TimeTickUnit, anchoredBand, axisBandWidth, mergeSeries, oneAxis, padBand, paddedDomain, seriesKey, seriesLegendEntries, soleSeriesColor, visibleSeries };