@cosmicdrift/kumiko-renderer 0.373.0 → 0.377.0

package/dist/web/widgets/charts.d.ts

@@ -0,0 +1,208 @@
+import { type ReactNode } from "react";
+import { type StackedAreaDateFormat, type StackedAreaInitialWindow, type StackedAreaRanges, type StackedAreaWindowSelection } from "./chart-window.ts";
+import { type StatusTone } from "./status-badge.tsx";
+export type StatusBarEntry = {
+    /** Stable key (z.B. ISO-Datum). */
+    readonly key: string;
+    /** Balkenhöhe 0..1 (z.B. operational=1, degraded=0.75, outage=0.25). */
+    readonly level: number;
+    readonly tone: StatusTone;
+    /** Tooltip-Text (<title>) — translated vom Caller. */
+    readonly label?: string;
+};
+/** Status bar strip (e.g. 90-day uptime): variable-height bars with
+ *  gradient fade + tick line on top; the last entry gets a "now"
+ *  accent stripe. `dense` swaps this for a flat-fill, fixed-size
+ *  variant sized to fit a table cell instead of stretching to `w-full`. */
+export declare function StatusBarChart({ entries, ariaLabel, startLabel, endLabel, highlightLast, dense, testId, }: {
+    readonly entries: readonly StatusBarEntry[];
+    readonly ariaLabel: string;
+    /** Achsen-Beschriftung links/rechts unter dem Chart — translated. */
+    readonly startLabel?: string;
+    readonly endLabel?: string;
+    readonly highlightLast?: boolean;
+    /** Compact variant for table cells: fixed intrinsic size (no `w-full` stretch), flat fills instead of gradients, no tick marks. */
+    readonly dense?: boolean;
+    readonly testId?: string;
+}): ReactNode;
+/** Quadratic-durch-Mittelpunkte-Trick: glättet die Zick-Zack-Linie ohne
+ *  Overshoot (~5 Zeilen statt Catmull-Rom/Bezier-Fit). */
+export declare function smoothPath(pts: ReadonlyArray<{
+    readonly x: number;
+    readonly y: number;
+}>): string;
+export type TimeseriesPoint = {
+    readonly atMs: number;
+    /** null = Ausfall/kein Wert → fällt auf die Grundlinie (sichtbarer Einbruch). */
+    readonly value: number | null;
+};
+export type TimeseriesYAxis = {
+    /** Number of gridlines including the zero baseline (min 2). Tick values are
+     *  rounded to 1/2/5 x 10^n steps and the y-scale reaches the top tick. */
+    readonly ticks: number;
+    /** Label text per tick value (unit, locale). Default: the plain number. */
+    readonly format?: (value: number) => string;
+    /** Ready-to-display unit (e.g. "ms"), shown once above the tick labels so
+     *  `format` can stay unit-free. */
+    readonly unit?: string;
+};
+/** Pixel height, or one height per viewport class. `narrowBelowPx` defaults
+ *  to the shared narrow-viewport breakpoint (768). */
+export type TimeseriesHeight = number | {
+    readonly narrow: number;
+    readonly wide: number;
+    readonly narrowBelowPx?: number;
+};
+export type TimeseriesXAxis = {
+    /** Number of evenly spaced time labels (min 2). */
+    readonly ticks: number;
+    readonly format: (atMs: number) => string;
+};
+export type TimeseriesReferenceLine = {
+    /** Same unit as the point values (e.g. a p95 or SLO threshold in ms). */
+    readonly value: number;
+    /** Translated by the caller. */
+    readonly label: string;
+    readonly tone?: StatusTone;
+};
+/** Zeitreihen-Linien-Chart (geglättete Linie + Flächen-Verlauf). x-Achse =
+ *  ZEIT im Fenster windowStartMs..windowEndMs, nicht Index — 5 Min Daten in
+ *  einem 30-Tage-Fenster ergeben ehrlich einen schmalen Streifen rechts. */
+export declare function TimeseriesChart({ points, windowStartMs, windowEndMs, tone, ariaLabel, axisLabels, xAxis, yAxis, height, markers, formatMarkerTime, referenceLines, emptyContent, testId, }: {
+    readonly points: readonly TimeseriesPoint[];
+    readonly windowStartMs: number;
+    readonly windowEndMs: number;
+    readonly tone?: StatusTone;
+    readonly ariaLabel: string;
+    /** Achsen-Zeile unter dem Chart (translated/formatiert vom Caller). */
+    readonly axisLabels?: {
+        readonly start: string;
+        readonly mid?: string;
+        readonly end: string;
+    };
+    /** Date axis with n evenly spaced labels; replaces `axisLabels` when set. */
+    readonly xAxis?: TimeseriesXAxis;
+    /** Gridlines plus value labels in a left gutter. */
+    readonly yAxis?: TimeseriesYAxis;
+    /** Chart height in px. Default: 64 (`h-16`). */
+    readonly height?: TimeseriesHeight;
+    /** Numbered pins on the x-axis plus a numbered list below the chart. */
+    readonly markers?: readonly ChartMarker[];
+    readonly formatMarkerTime?: (atMs: number) => string;
+    /** Dashed horizontal threshold lines (e.g. p95); they extend the y-scale
+     *  when above the data maximum. Non-finite and negative values are dropped. */
+    readonly referenceLines?: readonly TimeseriesReferenceLine[];
+    /** Rendered instead of the chart when there is no value; a single value
+     *  is drawn as a point. */
+    readonly emptyContent?: ReactNode;
+    readonly testId?: string;
+}): ReactNode;
+export type ChartTone = "positive" | "negative" | "active" | "neutral";
+export declare function chartToneColor(tone: ChartTone): string;
+export type ChartSeries = {
+    readonly key: string;
+    /** Translated by the caller. */
+    readonly label: string;
+    readonly points: readonly TimeseriesPoint[];
+};
+export type ChartMarker = {
+    readonly atMs: number;
+    readonly label: string;
+    /** Colors the pin and, on StackedAreaChart, draws a dashed guide line in the plot. */
+    readonly color?: string;
+    /** Translated by the caller. Groups markers into one legend entry when `markerLegend` is "legend". */
+    readonly legendLabel?: string;
+};
+/** Unstacked line drawn over a StackedAreaChart on the same y scale. */
+export type ChartLine = ChartSeries & {
+    readonly dashed?: boolean;
+};
+export type SegmentBarRow = {
+    readonly key: string;
+    readonly label: string;
+    readonly value: number;
+    readonly segments: readonly {
+        readonly key: string;
+        readonly label: string;
+        readonly value: number;
+    }[];
+};
+type ToneMap = Readonly<Record<string, ChartTone>>;
+/** Key -> raw CSS color; wins over the tone map. */
+type ColorMap = Readonly<Record<string, string>>;
+export declare function assignPinRows(fractions: readonly number[]): readonly number[];
+/** Vertically stacked bars per bucket (x axis = bucket, not time).
+ *  The last bucket carries `todayLabel` when it contains `windowEndMs` and
+ *  has day granularity. */
+export declare function StackedBarChart({ series, windowEndMs, tones, colors, ariaLabel, todayLabel, formatBucketLabel, formatValue, formatAxisValue, emptyContent, testId, }: {
+    readonly series: readonly ChartSeries[];
+    readonly windowEndMs: number;
+    readonly tones?: ToneMap;
+    readonly colors?: ColorMap;
+    readonly ariaLabel: string;
+    readonly todayLabel: string;
+    readonly formatBucketLabel: (atMs: number) => string;
+    readonly formatValue?: (value: number) => string;
+    /** y-axis tick labels only; defaults to `formatValue`. */
+    readonly formatAxisValue?: (value: number) => string;
+    readonly emptyContent?: ReactNode;
+    readonly testId?: string;
+}): ReactNode;
+/** One horizontally stacked bar per row; bar length is relative to the
+ *  largest row so rows stay comparable. */
+export declare function SegmentBarChart({ rows, tones, colors, ariaLabel, formatValue, testId, }: {
+    readonly rows: readonly SegmentBarRow[];
+    readonly tones?: ToneMap;
+    readonly colors?: ColorMap;
+    readonly ariaLabel: string;
+    readonly formatValue?: (value: number) => string;
+    readonly testId?: string;
+}): ReactNode;
+/** Stacked bands over time. Right of `todayMs` is the forecast: lighter
+ *  fill plus a vertical "today" line. */
+export declare function StackedAreaChart({ series: allSeries, windowStartMs: fullWindowStartMs, windowEndMs: fullWindowEndMs, todayMs, tones, colors, markers: allMarkers, lines: allLines, ranges, initialWindow, brush, windowSelection, onWindowSelectionChange, brushLabels, ariaLabel, todayLabel, formatBucketLabel, formatValue, formatAxisValue, formatMarkerTime, dateFormat, timeZone, markerLegend, markerLabels, scrollable, showLegendTotals, emptyContent, testId, }: {
+    readonly series: readonly ChartSeries[];
+    readonly windowStartMs: number;
+    readonly windowEndMs: number;
+    readonly todayMs?: number;
+    readonly tones?: ToneMap;
+    readonly colors?: ColorMap;
+    readonly markers?: readonly ChartMarker[];
+    /** Drawn over the bands, not stacked. A `null` value breaks the line. */
+    readonly lines?: readonly ChartLine[];
+    /** Range presets anchored at today; uncontrolled, the widget renders the switch itself. */
+    readonly ranges?: StackedAreaRanges;
+    /** Uncontrolled start window; "from-today" ignores the default range and starts at today. */
+    readonly initialWindow?: StackedAreaInitialWindow;
+    /** Scrubber under the plot to drag the visible window; starts at today without `ranges`. */
+    readonly brush?: boolean;
+    readonly windowSelection?: StackedAreaWindowSelection;
+    /** Makes the window controlled: no own range switch, `windowSelection` is the only source. */
+    readonly onWindowSelectionChange?: (selection: StackedAreaWindowSelection) => void;
+    /** aria-labels of the two brush handles. */
+    readonly brushLabels?: {
+        readonly start: string;
+        readonly end: string;
+    };
+    readonly ariaLabel: string;
+    readonly todayLabel: string;
+    readonly formatBucketLabel: (atMs: number, format: StackedAreaDateFormat) => string;
+    readonly formatValue?: (value: number) => string;
+    /** y-axis tick labels only (legend and totals keep `formatValue`); defaults to `formatValue`. */
+    readonly formatAxisValue?: (value: number) => string;
+    readonly formatMarkerTime?: (atMs: number, format: StackedAreaDateFormat) => string;
+    /** Overrides the automatic format (month and year once the visible window spans 18 months). */
+    readonly dateFormat?: StackedAreaDateFormat;
+    /** Zone the x-axis ticks align to; must match the zone `formatBucketLabel` formats in. Default UTC. */
+    readonly timeZone?: string;
+    /** "legend": unnumbered pins with tooltip, one dashed legend entry per marker label and color. */
+    readonly markerLegend?: "list" | "legend";
+    /** Writes each marker label vertically next to its guide line on wide containers; narrow ones keep the pins. */
+    readonly markerLabels?: boolean;
+    /** Fixed width per bucket; the plot scrolls horizontally, y ticks stay put. */
+    readonly scrollable?: boolean;
+    readonly showLegendTotals?: boolean;
+    readonly emptyContent?: ReactNode;
+    readonly testId?: string;
+}): ReactNode;
+export {};