@tensor_1/react 2.37.0 → 2.39.0

package/README.md

@@ -198,12 +198,15 @@ Radial mode still shortens long labels to fit its ring, but every node carries i
 - **`Tabs overflow="scroll"`** keeps a long tab row on one line that scrolls sideways. The selected tab is always scrolled into view, and edge buttons appear only on the side that has hidden tabs. The buttons are pointer-only: keyboard users move with Arrow, Home and End. Combine it with `TabPanel keepMounted` on a record page with many sections.
 - **`Stat tone`** (`warning`, `danger`) draws a toned outline and value; the label stays muted, so the tone never replaces words. `size="compact"` fits dense fact bands.
 - **`Stat onActivate`** makes the whole tile a button that opens an editor (`aria-haspopup="dialog"`). Pass `activateLabel` (e.g. "change") so the name reads "Priority: P1, change", and `expanded` while the editor is open. The ref points at the button, for anchoring a popover.
+- **`Stat pending`** is for a tile whose action is still running (a save, a state change). The button gets `aria-busy="true"` and `aria-disabled="true"`, is dimmed with a progress cursor, and calls neither `onActivate` nor your `onClick` / `onKeyDown` until `pending` is false again. It is never natively `disabled`, so it keeps focus and a screen reader can still read it. Only a tile with `onActivate` has the state; a read-only tile and a link tile ignore the prop.
+- **Tiles in one row line up.** A grid or flex row stretches its tiles to the tallest one. Read-only, button and link tiles all start their label and value at the same offset from the top edge, whatever the height (before 2.38.0 a button tile centred its rows).
 - **`CopyButton`** copies `value`. Name it for what it copies (`label="Copy email"`), pass `copiedLabel`, and pass `failedLabel` so a refused copy is explained rather than silent.
 
 ```tsx
 <Tabs value={tab} onChange={setTab} overflow="scroll">{tabs}</Tabs>
 <Stat label={t('sla')} value={remaining} tone={breached ? 'danger' : 'neutral'} size="compact" />
 <Stat ref={anchor} label={t('priority')} value="P1" onActivate={openEditor} activateLabel={t('change')} expanded={open} size="compact" />
+<Stat label={t('state')} value={state} onActivate={resolve} activateLabel={t('resolve')} haspopup={false} pending={saving} size="compact" />
 <CopyButton value={email} label={t('copyEmail')} copiedLabel={t('copied')} failedLabel={t('copyFailed')} />
 ```
 
@@ -673,6 +676,53 @@ A two-way diff of two texts (HAR-1368; TENSOR's knowledge-article version diff).
 - **Long texts:** `context` keeps that many unchanged lines around each change. Longer runs fold behind "Show n unchanged lines", and focus moves to the first revealed line. Over `maxTokens` (20 000) a note replaces the diff. Past `maxEdits` (2 000) the changed middle shows as one replacement instead of stalling.
 - Pure model for tests and servers: `diffText`, `diffTokens`, `textDiffRows`, `tokenizeText`.
 
+### Decision-grade charts: `chart/analytic`, `ChartPanels`, `CorrelationScatter`, `InsightCard`
+
+Charts that answer a decision (HAR-1553, HAR-1554, HAR-1556). The product computes the data — series, thresholds, events, forecasts with bounds, coverage — and writes the words; UIx draws. `@tensor_1/react/chart/analytic` is its own tree-shaken ECharts build (≤ 185 kB Brotli).
+
+```tsx
+import { ChartPanels, CorrelationScatter } from '@tensor_1/react/chart/analytic';
+import { InsightCard } from '@tensor_1/react';
+
+<InsightCard
+  eyebrow="Delivery health · last 15 days"
+  headline="Review is the bottleneck: 18.7 h, over budget for 3 days"
+  sowhat="Cap work in Review at 8 or add a reviewer this week."
+  status={{ tone: 'warning', label: 'Over budget' }}
+  kpis={[{ value: '18.7 h', label: 'Residence in Review',
+           comparison: { text: '↑ 3.7 h over the 15 h budget', tone: 'negative' },
+           target: { actual: 18.7, target: 15, ranges: [[0, 10], [10, 15], [15, 24]] } }]}
+  coverage={{ covered: 412, total: 431, note: 'items timed', partialPeriod: 'Today is partial.' }}
+  actions={<Link href="/review?state=waiting">Open the 10 items waiting in Review</Link>}
+  layout="split"
+  aside={<CorrelationScatter points={points} xLabel="Items in Review" yLabel="Residence (h)"
+                             breakpoint={{ x: 9, label: 'Knee ≈ 9 items' }} ariaLabel="…" />}
+>
+  <ChartPanels
+    x={{ type: 'category', values: days }}
+    partialLast
+    events={[{ at: 'Sep 1', kind: 'Release', label: 'Release freeze starts' }]}
+    panels={[
+      { id: 'residence', title: 'Residence', unit: 'h', kind: 'line',
+        series: [{ id: 'review', label: 'Review', values: review }],
+        thresholds: [{ value: 15, kind: 'budget', tone: 'warning', label: '15 h budget', badSide: 'above' }],
+        forecast: { from: 'Today', level: 0.8, method: 'linear', points: projection },
+        comparison: { label: 'Previous 15 days', values: previous } },
+      { id: 'wip', title: 'Work in Review', unit: 'items', kind: 'bar', series: [{ id: 'wip', label: 'Items', values: wip }] },
+    ]}
+    ariaLabel="Residence and work in Review, daily for 15 days"
+  />
+</InsightCard>
+```
+
+- **One axis, never two.** A panel has one unit and one y axis; two measures of different scale go on two panels on the same x axis, read with one crosshair and one tooltip that lists every panel at the hovered x. `group` links the crosshair across cards.
+- **Only a projection is dashed.** A threshold is a solid reference line labelled in the right gutter with its bad side shaded; the first point past it is ringed and named ("Crossed Sep 2"). The previous period is a thin solid ghost. Events sit in a lane of pins above the plot, which owns their tooltip and click (`onEventClick`, else the event's `href`), with unlabeled lines through every panel. `partialLast` shades the still-filling period.
+- **Honest correlation.** `CorrelationScatter` shows r and n with "association, not cause", refuses a trend below `minPoints` (default 8) and gives every point a 26 px hit target.
+- **Words.** Every word is a label: `labels` on `ChartPanels` (`DEFAULT_CHART_PANELS_LABELS`, including `formatX` / `formatValue`), on `CorrelationScatter` (`DEFAULT_CORRELATION_SCATTER_LABELS`) and on `InsightCard` (`DEFAULT_INSIGHT_CARD_LABELS`).
+- **Text alternatives.** One hidden table per panel (with lower, upper, threshold and event columns when given) and one for the scatter; `ariaLabel` is required.
+- **Building blocks.** The overlay helpers (`thresholdMarks`, `eventMarks`, `forecastSeries`, `comparisonSeries`, `partialPeriod`, `crossingPoints`, `combineMarks`) return option fragments for a hand-built `Chart` option; `chartPanelsModel` and `correlationScatterModel` are the pure models the components draw. `linearFit`, `quantiles` and `predictionBand` are on the root entry, so a server computes the same fit the chart draws.
+- `Chart`'s `option` may be a function of the theme's chart tokens; it is re-run when the theme flips, so colours you pass from `uixChartTokens` follow light and dark.
+
 ### DashboardGrid
 
 The layout grid for dashboard widgets (HAR-1555; TENSOR's role dashboards). Pure layout: drag-and-drop, persistence and widget chrome stay in the product. Server-renderable.

package/dist/{chart-theme-Cl0IrkKQ.d.cts → ChartCore-BKK2HEfi.d.cts}

@@ -2,6 +2,74 @@ import * as react from 'react';
 import { CSSProperties, ReactNode, HTMLAttributes } from 'react';
 import { EChartsOption, ECharts } from 'echarts';
 
+/** Where tokens are read from: an element (its computed style), or a reader for tests and non-DOM use. */
+type ChartTokenSource = Element | ((token: string) => string);
+/** The analytic chart roles: reference lines, threshold zones, forecast bands, events, partial periods. */
+interface UixChartTokens {
+    palette: string[];
+    neutral: string;
+    grid: string;
+    axis: string;
+    reference: string;
+    zoneWarning: string;
+    zoneDanger: string;
+    forecastBand: string;
+    event: string;
+    partial: string;
+    comparison: string;
+    /** Status hues for an emphasised mark (a point that breaches); never a series colour. */
+    warning: string;
+    danger: string;
+    surface: string;
+    text: string;
+    textMuted: string;
+    border: string;
+    fontSans: string;
+    fontMono: string;
+}
+/** Resolve the chart tokens once (current theme). */
+declare function uixChartTokens(source?: ChartTokenSource): UixChartTokens;
+/**
+ * The base option every UIx chart merges under the consumer's option (the consumer wins).
+ * Axis defaults apply to every x/y axis, whether the consumer passes one axis or an array.
+ */
+declare function uixChartTheme(source?: ChartTokenSource): EChartsOption;
+/** A vertical area fill that fades the series colour (28 % → 6 % → 0) toward the baseline. */
+declare function uixChartAreaGradient(color: string): {
+    type: "linear";
+    x: number;
+    y: number;
+    x2: number;
+    y2: number;
+    colorStops: {
+        offset: number;
+        color: string;
+    }[];
+};
+/**
+ * Merge the theme under a consumer option: plain objects merge deeply, everything else (arrays,
+ * series, data, functions) is the consumer's. Array-valued components (`xAxis: [...]`, `title: [...]`)
+ * take the theme entry per element.
+ */
+declare function mergeChartTheme(theme: EChartsOption, option: EChartsOption): EChartsOption;
+
+interface ChartEngine {
+    init(element: HTMLElement, theme?: string | null, options?: {
+        renderer?: 'svg' | 'canvas';
+    }): ECharts;
+    /** Optional: links charts that share a `group` (one crosshair and tooltip across cards). */
+    connect?(group: string): void;
+}
+/** An option, or a function that builds it from the chart tokens of the current theme (re-run on a theme flip). */
+type ChartOption = EChartsOption | ((tokens: UixChartTokens) => EChartsOption);
+/** A further text alternative: one visually hidden table (ChartPanels gives one per panel). */
+interface ChartTable {
+    caption: string;
+    headers: string[];
+    rows: ChartTableRow[];
+}
+/** An ECharts event handler; `params` is ECharts' event object. */
+type ChartEventHandler = (params: unknown) => void;
 declare function uixChartPalette(): string[];
 interface ChartTableRow {
     [key: string]: string | number;
@@ -20,7 +88,8 @@ interface ChartLabels {
 }
 declare const DEFAULT_CHART_LABELS: ChartLabels;
 interface ChartProps {
-    option: EChartsOption;
+    /** The ECharts option, or a function of the theme's chart tokens (re-run when the theme flips). */
+    option: ChartOption;
     title?: string;
     subtitle?: string;
     height?: string | number;
@@ -42,6 +111,12 @@ interface ChartProps {
      * grid and the UIx tooltip — and re-applies it when the page theme changes. `'none'` renders `option` as is.
      */
     theme?: 'uix' | 'none';
+    /** Charts with the same group share one crosshair and tooltip (`echarts.connect`). */
+    group?: string;
+    /** ECharts event handlers by event name (`click` for drill-down). */
+    onEvents?: Record<string, ChartEventHandler>;
+    /** Further hidden data tables (after `tableData`), each named in the chart's description. */
+    tables?: ChartTable[];
 }
 interface ChartMetricProps extends HTMLAttributes<HTMLDivElement> {
     value: ReactNode;
@@ -61,52 +136,4 @@ interface ChartLegendItemProps extends HTMLAttributes<HTMLLIElement> {
 }
 declare function ChartLegendItem({ label, color, swatch, className, style, ...props }: ChartLegendItemProps): react.JSX.Element;
 
-/** Where tokens are read from: an element (its computed style), or a reader for tests and non-DOM use. */
-type ChartTokenSource = Element | ((token: string) => string);
-/** The analytic chart roles: reference lines, threshold zones, forecast bands, events, partial periods. */
-interface UixChartTokens {
-    palette: string[];
-    neutral: string;
-    grid: string;
-    axis: string;
-    reference: string;
-    zoneWarning: string;
-    zoneDanger: string;
-    forecastBand: string;
-    event: string;
-    partial: string;
-    comparison: string;
-    surface: string;
-    text: string;
-    textMuted: string;
-    border: string;
-    fontSans: string;
-    fontMono: string;
-}
-/** Resolve the chart tokens once (current theme). */
-declare function uixChartTokens(source?: ChartTokenSource): UixChartTokens;
-/**
- * The base option every UIx chart merges under the consumer's option (the consumer wins).
- * Axis defaults apply to every x/y axis, whether the consumer passes one axis or an array.
- */
-declare function uixChartTheme(source?: ChartTokenSource): EChartsOption;
-/** A vertical area fill that fades the series colour (28 % → 6 % → 0) toward the baseline. */
-declare function uixChartAreaGradient(color: string): {
-    type: "linear";
-    x: number;
-    y: number;
-    x2: number;
-    y2: number;
-    colorStops: {
-        offset: number;
-        color: string;
-    }[];
-};
-/**
- * Merge the theme under a consumer option: plain objects merge deeply, everything else (arrays,
- * series, data, functions) is the consumer's. Array-valued components (`xAxis: [...]`, `title: [...]`)
- * take the theme entry per element.
- */
-declare function mergeChartTheme(theme: EChartsOption, option: EChartsOption): EChartsOption;
-
-export { type ChartProps as C, DEFAULT_CHART_LABELS as D, type UixChartTokens as U, type ChartLabels as a, ChartLegend as b, ChartLegendItem as c, type ChartLegendItemProps as d, type ChartLegendProps as e, ChartMetric as f, type ChartMetricProps as g, type ChartTableRow as h, type ChartTokenSource as i, uixChartPalette as j, uixChartTheme as k, uixChartTokens as l, mergeChartTheme as m, uixChartAreaGradient as u };
+export { type ChartLabels as C, DEFAULT_CHART_LABELS as D, type UixChartTokens as U, type ChartProps as a, type ChartEngine as b, type ChartEventHandler as c, ChartLegend as d, ChartLegendItem as e, type ChartLegendItemProps as f, type ChartLegendProps as g, ChartMetric as h, type ChartMetricProps as i, type ChartOption as j, type ChartTable as k, type ChartTableRow as l, type ChartTokenSource as m, mergeChartTheme as n, uixChartPalette as o, uixChartTheme as p, uixChartTokens as q, uixChartAreaGradient as u };

package/dist/chart-analytic-guide.d.ts

@@ -0,0 +1,6 @@
+export { DEFAULT_CHART_PANELS_LABELS, chartPanelsModel } from './chart-panels-model.js';
+export { DEFAULT_CORRELATION_SCATTER_LABELS, correlationScatterModel, formatCorrelation } from './correlation-scatter-model.js';
+import 'echarts';
+import './chart-theme.js';
+import './chart-analytic-model.js';
+import './chart-stats.js';

package/dist/chart-analytic-guide.js

@@ -0,0 +1,10 @@
+import { chartPanelsModel } from "./chart-panels-model.js";
+import { correlationScatterModel, formatCorrelation, DEFAULT_CORRELATION_SCATTER_LABELS } from "./correlation-scatter-model.js";
+import { DEFAULT_CHART_PANELS_LABELS } from "./chart-panels-model.js";
+export {
+  DEFAULT_CHART_PANELS_LABELS,
+  DEFAULT_CORRELATION_SCATTER_LABELS,
+  chartPanelsModel,
+  correlationScatterModel,
+  formatCorrelation
+};

package/dist/chart-analytic-model.d.ts

@@ -0,0 +1,141 @@
+import { ScatterSeriesOption, MarkLineComponentOption, MarkAreaComponentOption, MarkPointComponentOption, LineSeriesOption } from 'echarts';
+import { UixChartTokens } from './chart-theme.js';
+
+/** A position on the x axis: a category name, or a time value (ms or ISO string) on a time axis. */
+type ChartX = string | number;
+/** A target line, a limit or a zone. `to` turns a line into a zone between `value` and `to`. */
+interface ChartThreshold {
+    value: number;
+    to?: number;
+    kind: 'target' | 'limit' | 'floor' | 'budget';
+    tone: 'neutral' | 'warning' | 'danger';
+    label: string;
+    /** The side that is bad: shades from the line to the edge of the axis on that side. */
+    badSide?: 'above' | 'below';
+}
+/** Something that happened at (or from `at` to `to`) on the time axis. */
+interface ChartEvent {
+    at: ChartX;
+    to?: ChartX;
+    kind: string;
+    label: string;
+    href?: string;
+    tone?: 'neutral' | 'warning' | 'danger';
+}
+/** A projection with its uncertainty, computed by the consumer. `from` is the last actual x. */
+interface ChartForecast {
+    from: ChartX;
+    points: {
+        x: ChartX;
+        y: number;
+        lower: number;
+        upper: number;
+    }[];
+    /** Central coverage of the band, 0–1 (0.8 = 80 %). */
+    level: number;
+    /** How it was computed, for the tooltip and the table ("linear over 8 weeks"). */
+    method: string;
+}
+/** The previous period's values on the same x positions (a ghost line). */
+interface ChartComparison {
+    label: string;
+    values: (number | null)[];
+}
+/** Every word the overlays draw. English defaults in {@link DEFAULT_ANALYTIC_LABELS}. */
+interface ChartAnalyticLabels {
+    projection: string;
+    /** The band's name in the legend, the tooltip and the table, e.g. "80 % range". */
+    range: (level: number) => string;
+    partial: string;
+    crossed: (x: string) => string;
+    lower: string;
+    upper: string;
+    threshold: string;
+    event: string;
+    /** How an x value is written in labels and tables. */
+    formatX: (x: ChartX) => string;
+}
+declare const DEFAULT_ANALYTIC_LABELS: ChartAnalyticLabels;
+/** Series-level mark fragments; spread into one series, or combine several with {@link combineMarks}. */
+interface ChartMarks {
+    markLine?: MarkLineComponentOption;
+    markArea?: MarkAreaComponentOption;
+    markPoint?: MarkPointComponentOption;
+}
+/** Merge mark fragments into one (a series carries one markLine, one markArea and one markPoint). */
+declare function combineMarks(...fragments: (ChartMarks | null | undefined)[]): ChartMarks;
+/**
+ * Threshold lines and zones. A line is solid reference ink with its label in the right gutter
+ * (the plot needs `grid.right` ≥ 96 px; ChartPanels reserves it). A zone (`to`, or `badSide` with an
+ * axis `extent`) is a token wash. Lines never take a status hue: the zone carries the tone.
+ */
+declare function thresholdMarks(thresholds: readonly ChartThreshold[], options: {
+    tokens: UixChartTokens;
+    extent?: [number, number];
+}): ChartMarks;
+/** One pin in the event lane: [x, 0, index into the events]. */
+type ChartEventPin = [ChartX, number, number];
+/** The event lane: a thin row above the plot that owns the events' tooltip and click-through. */
+interface ChartEventLane {
+    series: ScatterSeriesOption;
+}
+/**
+ * Events: unlabeled solid lines through the plot (ranges as a light wash) plus the pins of the lane.
+ * The tone is carried by the pin's shape (circle, triangle, diamond) in event ink, never by a status
+ * hue, so the lane stays calm. Put `lane.series` on the lane's grid (ChartPanels does).
+ */
+declare function eventMarks(events: readonly ChartEvent[], options: {
+    tokens: UixChartTokens;
+    xAxisIndex?: number;
+    yAxisIndex?: number;
+    seriesId?: string;
+}): ChartMarks & {
+    lane: ChartEventLane;
+};
+/**
+ * A forecast as three series: a hidden lower bound, the band stacked on it (upper − lower) in
+ * `--uix-chart-forecast-band`, and the dashed centre line in the series colour, starting at `from`.
+ * The centre carries a light "Projection" wash from `from` to the last point.
+ */
+declare function forecastSeries(forecast: ChartForecast, options: {
+    name: string;
+    colorIndex?: number;
+    tokens: UixChartTokens;
+    labels?: Partial<ChartAnalyticLabels>;
+    /** The last actual value, so the dashed line starts where the solid one ends. */
+    fromValue?: number | null;
+    xAxisIndex?: number;
+    yAxisIndex?: number;
+    idPrefix?: string;
+}): LineSeriesOption[];
+/** The previous period as a thin SOLID ghost line (dashes are reserved for projections). */
+declare function comparisonSeries(comparison: ChartComparison, options: {
+    x: readonly ChartX[];
+    tokens: UixChartTokens;
+    xAxisIndex?: number;
+    yAxisIndex?: number;
+    id?: string;
+}): LineSeriesOption;
+/**
+ * The last, still-filling period: a shaded wash from the previous bucket (`from`) to `lastX`,
+ * labelled "Partial" at the foot of the plot. On a category line axis the points sit on the
+ * categories, so the wash spans the segment that leads into the partial point.
+ */
+declare function partialPeriod(lastX: ChartX, options: {
+    tokens: UixChartTokens;
+    from?: ChartX;
+    labels?: Partial<ChartAnalyticLabels>;
+}): ChartMarks;
+/**
+ * Indexes where the series first enters the bad side of a threshold (after being on the good side
+ * or at the start of a run of nulls). `badSide` defaults to `above` (`floor` thresholds: `below`).
+ */
+declare function findCrossings(values: readonly (number | null)[], threshold: Pick<ChartThreshold, 'value' | 'badSide' | 'kind'>): number[];
+/** A ringed point at each first crossing, labelled "Crossed <x>" above it. */
+declare function crossingPoints(values: readonly (number | null)[], threshold: ChartThreshold, options: {
+    x: readonly ChartX[];
+    tokens: UixChartTokens;
+    labels?: Partial<ChartAnalyticLabels>;
+}): ChartMarks;
+
+export { type ChartAnalyticLabels, type ChartComparison, type ChartEvent, type ChartEventLane, type ChartEventPin, type ChartForecast, type ChartMarks, type ChartThreshold, type ChartX, DEFAULT_ANALYTIC_LABELS, combineMarks, comparisonSeries, crossingPoints, eventMarks, findCrossings, forecastSeries, partialPeriod, thresholdMarks };

package/dist/chart-analytic-model.js

@@ -0,0 +1,252 @@
+const DEFAULT_ANALYTIC_LABELS = {
+  projection: "Projection",
+  range: (level) => `${Math.round(level * 100)}% range`,
+  partial: "Partial",
+  crossed: (x) => `Crossed ${x}`,
+  lower: "Lower",
+  upper: "Upper",
+  threshold: "Threshold",
+  event: "Event",
+  formatX: (x) => String(x)
+};
+const GUTTER_LABEL_WIDTH = 88;
+const markLineBase = (data) => ({
+  silent: true,
+  symbol: "none",
+  animation: false,
+  data
+});
+const markAreaBase = (data) => ({ silent: true, animation: false, data });
+function combineMarks(...fragments) {
+  const lines = [];
+  const areas = [];
+  const points = [];
+  for (const fragment of fragments) {
+    if (!fragment) continue;
+    if (fragment.markLine?.data) lines.push(...fragment.markLine.data);
+    if (fragment.markArea?.data) areas.push(...fragment.markArea.data);
+    if (fragment.markPoint?.data) points.push(...fragment.markPoint.data);
+  }
+  const out = {};
+  if (lines.length) out.markLine = markLineBase(lines);
+  if (areas.length) out.markArea = markAreaBase(areas);
+  if (points.length) out.markPoint = { animation: false, data: points };
+  return out;
+}
+const zoneColor = (tone, tokens) => tone === "danger" ? tokens.zoneDanger : tone === "warning" ? tokens.zoneWarning : tokens.forecastBand;
+function thresholdMarks(thresholds, options) {
+  const { tokens, extent } = options;
+  const lines = [];
+  const areas = [];
+  for (const threshold of thresholds) {
+    if (!Number.isFinite(threshold.value)) continue;
+    const zoneTo = threshold.to ?? (threshold.badSide && extent ? threshold.badSide === "above" ? extent[1] : extent[0] : void 0);
+    if (zoneTo != null && Number.isFinite(zoneTo) && zoneTo !== threshold.value) {
+      areas.push([
+        { yAxis: Math.min(threshold.value, zoneTo), itemStyle: { color: zoneColor(threshold.tone, tokens) } },
+        { yAxis: Math.max(threshold.value, zoneTo) }
+      ]);
+    }
+    lines.push({
+      yAxis: threshold.value,
+      lineStyle: { color: tokens.reference, width: 1, type: "solid" },
+      label: {
+        show: true,
+        position: "end",
+        formatter: threshold.label,
+        color: tokens.textMuted,
+        fontFamily: tokens.fontSans,
+        fontSize: 11,
+        width: GUTTER_LABEL_WIDTH,
+        overflow: "truncate",
+        distance: 6
+      }
+    });
+  }
+  return combineMarks(
+    lines.length ? { markLine: markLineBase(lines) } : null,
+    areas.length ? { markArea: markAreaBase(areas) } : null
+  );
+}
+const PIN_SYMBOL = {
+  neutral: "circle",
+  warning: "triangle",
+  danger: "diamond"
+};
+function eventMarks(events, options) {
+  const { tokens } = options;
+  const lines = [];
+  const areas = [];
+  events.forEach((event) => {
+    if (event.to != null) {
+      areas.push([{ xAxis: event.at, itemStyle: { color: tokens.forecastBand } }, { xAxis: event.to }]);
+    }
+    lines.push({ xAxis: event.at, lineStyle: { color: tokens.event, width: 1, type: "solid", opacity: 0.7 }, label: { show: false } });
+  });
+  const lane = {
+    series: {
+      id: options.seriesId ?? "uix-event-lane",
+      type: "scatter",
+      xAxisIndex: options.xAxisIndex ?? 0,
+      yAxisIndex: options.yAxisIndex ?? 0,
+      data: events.map((event, index) => ({
+        value: [event.at, 0, index],
+        symbol: PIN_SYMBOL[event.tone ?? "neutral"]
+      })),
+      symbolSize: 10,
+      itemStyle: { color: tokens.event, borderColor: tokens.surface, borderWidth: 2 },
+      emphasis: { scale: 1.3 },
+      cursor: "pointer",
+      animation: false,
+      z: 5
+    }
+  };
+  return {
+    ...combineMarks(
+      lines.length ? { markLine: markLineBase(lines) } : null,
+      areas.length ? { markArea: markAreaBase(areas) } : null
+    ),
+    lane
+  };
+}
+function forecastSeries(forecast, options) {
+  const labels = { ...DEFAULT_ANALYTIC_LABELS, ...options.labels };
+  const { tokens } = options;
+  const color = tokens.palette[(options.colorIndex ?? 0) % tokens.palette.length] || tokens.palette[0];
+  const stack = `${options.idPrefix ?? "forecast"}-band`;
+  const axes = { xAxisIndex: options.xAxisIndex ?? 0, yAxisIndex: options.yAxisIndex ?? 0 };
+  const points = forecast.points.filter((p) => [p.y, p.lower, p.upper].every(Number.isFinite));
+  const start = options.fromValue != null && Number.isFinite(options.fromValue) ? [{ x: forecast.from, y: options.fromValue, lower: options.fromValue, upper: options.fromValue }] : [];
+  const all = [...start, ...points];
+  const last = points[points.length - 1];
+  const prefix = options.idPrefix ?? "forecast";
+  return [
+    {
+      id: `${prefix}-lower`,
+      name: `${options.name} \xB7 ${labels.lower}`,
+      type: "line",
+      ...axes,
+      stack,
+      data: all.map((p) => [p.x, p.lower]),
+      lineStyle: { opacity: 0 },
+      symbol: "none",
+      silent: true,
+      tooltip: { show: false },
+      animation: false,
+      z: 1
+    },
+    {
+      id: `${prefix}-band`,
+      name: `${options.name} \xB7 ${labels.range(forecast.level)}`,
+      type: "line",
+      ...axes,
+      stack,
+      data: all.map((p) => [p.x, p.upper - p.lower]),
+      lineStyle: { opacity: 0 },
+      areaStyle: { color: tokens.forecastBand, opacity: 1 },
+      symbol: "none",
+      silent: true,
+      tooltip: { show: false },
+      animation: false,
+      z: 1
+    },
+    {
+      id: `${prefix}-centre`,
+      name: `${options.name} \xB7 ${labels.projection}`,
+      type: "line",
+      ...axes,
+      data: all.map((p) => [p.x, p.y]),
+      lineStyle: { color, width: 2, type: "dashed" },
+      itemStyle: { color },
+      symbol: "none",
+      animation: false,
+      z: 3,
+      ...last ? {
+        markArea: markAreaBase([[
+          {
+            xAxis: forecast.from,
+            itemStyle: { color: "transparent" },
+            label: { show: true, position: "insideTop", formatter: labels.projection, color: tokens.textMuted, fontFamily: tokens.fontSans, fontSize: 11 }
+          },
+          { xAxis: last.x }
+        ]])
+      } : {}
+    }
+  ];
+}
+function comparisonSeries(comparison, options) {
+  return {
+    id: options.id ?? "comparison",
+    name: comparison.label,
+    type: "line",
+    xAxisIndex: options.xAxisIndex ?? 0,
+    yAxisIndex: options.yAxisIndex ?? 0,
+    data: options.x.map((x, i) => [x, comparison.values[i] ?? null]),
+    lineStyle: { color: options.tokens.comparison, width: 1.5, type: "solid" },
+    itemStyle: { color: options.tokens.comparison },
+    symbol: "none",
+    connectNulls: false,
+    animation: false,
+    z: 1
+  };
+}
+function partialPeriod(lastX, options) {
+  const labels = { ...DEFAULT_ANALYTIC_LABELS, ...options.labels };
+  return {
+    markArea: markAreaBase([[
+      {
+        xAxis: options.from ?? lastX,
+        itemStyle: { color: options.tokens.partial },
+        label: { show: true, position: "insideBottom", formatter: labels.partial, color: options.tokens.textMuted, fontFamily: options.tokens.fontSans, fontSize: 11 }
+      },
+      { xAxis: lastX }
+    ]])
+  };
+}
+function findCrossings(values, threshold) {
+  const side = threshold.badSide ?? (threshold.kind === "floor" ? "below" : "above");
+  const bad = (v) => side === "above" ? v > threshold.value : v < threshold.value;
+  const out = [];
+  let previous = null;
+  values.forEach((value, index) => {
+    if (value == null || !Number.isFinite(value)) {
+      previous = null;
+      return;
+    }
+    const isBad = bad(value);
+    if (isBad && previous === false) out.push(index);
+    previous = isBad;
+  });
+  return out;
+}
+function crossingPoints(values, threshold, options) {
+  const labels = { ...DEFAULT_ANALYTIC_LABELS, ...options.labels };
+  const data = findCrossings(values, threshold).map((index) => ({
+    name: labels.crossed(labels.formatX(options.x[index])),
+    coord: [options.x[index], values[index]],
+    symbol: "circle",
+    symbolSize: 10,
+    itemStyle: { color: options.tokens.surface, borderColor: options.tokens.text, borderWidth: 2 },
+    label: {
+      show: true,
+      position: "top",
+      distance: 8,
+      formatter: labels.crossed(labels.formatX(options.x[index])),
+      color: options.tokens.text,
+      fontFamily: options.tokens.fontSans,
+      fontSize: 11
+    }
+  }));
+  return data.length ? { markPoint: { animation: false, data } } : {};
+}
+export {
+  DEFAULT_ANALYTIC_LABELS,
+  combineMarks,
+  comparisonSeries,
+  crossingPoints,
+  eventMarks,
+  findCrossings,
+  forecastSeries,
+  partialPeriod,
+  thresholdMarks
+};