@lilt-ui/charts 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog
+
+## 0.3.0
+
+Charts that know what normal looks like, dashboards that arrange themselves around what needs attention, pins shared across linked charts, and segmented axes.
+
+### Watch
+
+- `normal` on Line and unstacked Area cards watches one series. Layers are off unless set: `limits`, `around` another series with a `tolerance`, `learn` from its own history by `week`, `day`, or `all`, `given` similar conditions, `when` to skip rows such as maintenance, `rules` across series, and `history` to learn from rows the card does not draw.
+- The card draws the normal band, recolors unusual stretches, keeps limits on screen, and says "Unusually low since Tue 2 PM". With `breakdown`, an unusual reading says which segment caused it: "98% of the drop is Mobile Safari".
+- `onNormalChange` reports whether the series is unusual, how badly, why, and since when.
+- `ChartBoard` and `BoardItem`, from `@lilt-ui/charts/watch`, rank cards by what needs attention. Each card carries its state in its glass tab and on its edge: Needs attention with Acknowledge, Seen, Back to normal, or Pinned. Nothing moves while the viewer points at or works inside the board.
+- `toast` alerts the viewer to cards that turn unusual off screen, with View; `memory` marks incidents new since the last visit; `onEvent` and its `show()` feed your own alerts.
+- The engine is exported for custom UI: `evaluateNormal`, `trackNormalStatus`, `explainReadings`, `explainDeviation`, `describeFlag`, `describeExplanation`, `flatline`, `jump`, `boardReducer`, and `rankBoard`.
+- `CardFrameContext` lets a container give the card inside it a tab, an edge tone, and a handle.
+
+### Axes
+
+- `axis="segmented"` draws rounded segments between ticks instead of one continuous line, with y labels beside them; the segment under the pointer lights up.
+- `axis` takes one preset per axis, e.g. `{ x: 'minimal', y: 'segmented' }`; an axis left out is `minimal`.
+- A segmented axis takes a `gradient` to read as a range: `true` fades the first series' color from faint to full, or pass colors low to high, e.g. `['var(--lilt-positive)', 'var(--lilt-negative)']`.
+
+### Pins
+
+- A click on a linked card pins every card in its `sync` group. The clicked card shows the pin, the others show a ghost of it that names where it came from, and any of them releases it.
+- Alt-click (Option-click) pins one card only, and Alt+Enter does the same from the keyboard; linked cards keep following the pointer. `model.actions.pin(x, { local: true })` does it in code.
+- Pins travel between points with the crosshair's quick spring, and the pin glyph sits centered in its marker.
+
+## 0.2.0
+
+Finance charts, range charts, and series that carry more than one value.
+
+### Breaking
+
+- A series' `interval` is replaced by `fields`: named companion values in the series' unit, such as a forecast's low and high, quartiles, or a candle's open, high, and low. Fields fit the y axis, appear in hover, and range marks read them by ID.
+- `IntervalBand` now names the fields it draws: `<IntervalBand series="revenue" lower="low" upper="high" />`.
+- Tooltip content (`ChartTooltipContext.series[]`) has `fields` instead of `interval`.
+
+Cards are unchanged: `forecast={{ from, lower, upper }}` works as before. See "Upgrading from 0.1" in the README.
+
+### Finance, from `@lilt-ui/charts/finance`
+
+- `CandlestickChartCard`: candles, hollow candles, OHLC bars, or a price area colored by direction, with an optional linked volume pane, a log scale, and live mode. Hover reads the candle's open, high, and low beside its date.
+- `IndicatorChartCard`: simple or exponential averages and Bollinger bands over the price, with RSI, MACD, or volume panes underneath that move together on hover. Each pane reads its own value.
+- `PriceChartCard`: a ticker with its latest price, change, and change in money; `versus` rebases other instruments to percent change on one axis.
+- `DepthChartCard`: how much could trade at each price on the buy and sell side, with the gap between the best prices and the total resting on each side.
+- `OrderBook`: resting orders as an accessible table, each level with a bar sized by the total behind it; changed levels highlight briefly.
+- `PortfolioChartCard`: what an account is worth next to what went into it, with how far it sits below its best value in a linked pane.
+- `Candles`, a primitive that draws any number of candles into a handful of paths.
+- Helpers: `sma`, `ema`, `rsi` (Wilder), `macd`, `bollinger`, `drawdown`, `rebase`, and `depthLevels`.
+- `--lilt-candle-up` and `--lilt-candle-down` tokens, following `--lilt-positive` and `--lilt-negative`.
+
+### Charts
+
+- `RangeChartCard`: floating bars from low to high, or error bars around a value.
+- `BoxPlotCard`: quartiles, a median, Tukey whiskers, and outliers computed from raw samples. `summarizeBox` returns the same statistics.
+- Primitives: `RangeBar`, `ErrorBar`, and `BoxPlot`.
+- `series.colorAt(row)` colors one bar, candle, range, or point, such as a falling day in red.
+- `y.scale: 'log'` spaces values by ratio, with ticks on 1, 2, and 5.
+- `ReferenceBand axis="y"` shades a range of values, such as RSI 30–70.
+- `ChartPlot slots` gives every observation a bar-width slot, so a line pane lines up with bars or candles beside it.
+
+### Fixes
+
+- A card `valueFormat` with more than one minimum fraction digit, such as two-decimal prices, no longer throws.
+
+## 0.1.0
+
+The first release: Area, Line, Bar, Combo, Horizontal bar, Stat, Radial, Progress, Activity ring, Funnel, Heatmap, Scatter, Sankey, Radar, and Slope cards, with linked hover, targets, forecasts, and range comparison.

package/README.md

@@ -14,6 +14,8 @@
 <p align="center">
   <a href="https://liltui.vercel.app"><strong>Documentation</strong></a> ·
   <a href="https://liltui.vercel.app/charts/area">Charts</a> ·
+  <a href="https://liltui.vercel.app/finance/candlestick">Finance</a> ·
+  <a href="https://liltui.vercel.app/watch">Watch</a> ·
   <a href="https://liltui.vercel.app/llms.txt">llms.txt</a>
 </p>
 
@@ -82,6 +84,107 @@ That's the whole card: the headline, the change chip, value tiles, and hover all
 | **Rankings**         | Horizontal bar, with shares and an "Other" row                       |
 | **Flows and change** | Funnel, Sankey, and Slope                                            |
 | **Patterns**         | Heatmap, Scatter, and Radar                                          |
+| **Spread**           | Range (floating or error bars) and Box plot, from raw samples        |
+| **Markets**          | Candlestick, Indicators, Price, Depth, Order book, and Portfolio     |
+
+## Finance charts
+
+Candlesticks, indicators, and order books ship from their own entry point, so apps that never draw a candle never load one:
+
+```tsx
+'use client';
+
+import { CandlestickChartCard } from '@lilt-ui/charts/finance';
+
+const candles = [
+  {
+    date: new Date('2026-08-20'),
+    open: 243.1,
+    high: 246.4,
+    low: 241.8,
+    close: 245.2,
+    volume: 2410000,
+  },
+  {
+    date: new Date('2026-08-21'),
+    open: 245.2,
+    high: 247.0,
+    low: 243.9,
+    close: 244.6,
+    volume: 1980000,
+  },
+];
+
+export function MarketCard() {
+  return (
+    <CandlestickChartCard
+      title="SOL · USDC"
+      data={candles}
+      x="date"
+      open="open"
+      high="high"
+      low="low"
+      close="close"
+      volume="volume"
+      valueFormat={{ style: 'currency', currency: 'USD' }}
+    />
+  );
+}
+```
+
+| Card                   | What it shows                                                                  |
+| ---------------------- | ------------------------------------------------------------------------------ |
+| `CandlestickChartCard` | Candles, hollow candles, OHLC bars, or a price area, with a linked volume pane |
+| `IndicatorChartCard`   | Moving averages or Bollinger bands over the price; RSI, MACD, or volume panes  |
+| `PriceChartCard`       | A ticker with its latest price and change, or several instruments rebased      |
+| `DepthChartCard`       | How much could trade at each price, buying and selling, and the gap between    |
+| `OrderBook`            | Resting orders level by level, the best prices meeting in the middle           |
+| `PortfolioChartCard`   | What an account is worth next to what went in, and its fall from its best      |
+
+Candles draw into a handful of paths however many there are, so years of daily history stay fast. `scale="log"` spaces long histories by ratio, and `live` follows new rows as they arrive. The indicator math (`sma`, `ema`, `rsi`, `macd`, `bollinger`, `drawdown`, `depthLevels`) is exported too, for your own layouts.
+
+## Watch
+
+Tell a chart what normal looks like, and it says when something isn't:
+
+```tsx
+<LineChartCard
+  title="Orders"
+  data={lastTwoDays}
+  x="hour"
+  series={[{ key: 'orders' }]}
+  normal={{
+    history: earlierWeeks, // learn from weeks you don't draw
+    learn: 'week', // same hour, same weekday
+    limits: { min: 10 }, // a line you set
+    when: (hour) => !hour.maintenance, // never judge downtime
+    breakdown: (hour) => hour.devices, // say which device caused it
+  }}
+/>
+```
+
+The card draws a calm band where the series should be, recolors unusual stretches, and says "Unusually low since Tue 2 PM". Hover an unusual reading and it says why: "98% of the drop is Mobile Safari". Every layer is off until you set it.
+
+Wrap cards in a board and the dashboard arranges itself around what needs attention:
+
+```tsx
+import { BoardItem, ChartBoard } from '@lilt-ui/charts/watch';
+
+<ChartBoard aria-label="Store health" toast>
+  <BoardItem id="orders" title="Orders">
+    <AreaChartCard
+      title="Orders"
+      data={rows}
+      x="hour"
+      series={[{ key: 'orders' }]}
+      normal={{ learn: 'week' }}
+    />
+  </BoardItem>
+  {/* …more cards */}
+</ChartBoard>;
+```
+
+Cards that need attention rise, what you've seen calms down, and what clears settles back. Nothing moves while you're reading, and a toast finds you when something breaks off screen.
 
 ## Built in, one prop away
 
@@ -89,6 +192,7 @@ That's the whole card: the headline, the change chip, value tiles, and hover all
 - **Targets and forecasts.** `target` draws a goal line and counts the points that reach it. `forecast` marks projected rows and keeps them out of the headline.
 - **Pin and compare.** Click to pin a point. Add `compare` and drag across a chart to see what changed.
 - **Honest data.** `null` is a gap, never a zero, and missing values say so.
+- **Watch.** `normal` flags what's unusual and says why; a `ChartBoard` raises what needs attention.
 - **Calm by default.** Keyboard navigation, screen reader labels, and motion that respects reduced-motion settings.
 
 ## Fits your design system
@@ -102,6 +206,22 @@ Every Lilt style lives in the `lilt` cascade layer, so your CSS wins without spe
 @import 'tailwindcss';
 ```
 
+## Upgrading from 0.1
+
+0.2 replaces a series' `interval` with named `fields`, which carry any companion values: a forecast's low and high, quartiles, or a candle's open, high, and low. `IntervalBand` now names the fields it reads:
+
+```tsx
+// 0.1
+{ id: 'revenue', accessor: (row) => row.revenue, interval: { lower: (row) => row.low, upper: (row) => row.high, meaning: 'Forecast' } }
+<IntervalBand series="revenue" />
+
+// 0.2
+{ id: 'revenue', accessor: (row) => row.revenue, fields: { low: { label: 'Low', accessor: (row) => row.low }, high: { label: 'High', accessor: (row) => row.high } } }
+<IntervalBand series="revenue" lower="low" upper="high" />
+```
+
+Cards are unchanged: `forecast={{ from, lower, upper }}` works as before. Tooltip content reads `series[].fields` instead of `series[].interval`.
+
 ## License
 
 MIT © Lilt UI

package/dist/analysis-BJRmXHOB.js

@@ -0,0 +1,62 @@
+//#region src/engine/ranking.ts
+function e(e, t, n) {
+	let r = /* @__PURE__ */ new Set();
+	return e.map((e, i) => {
+		let a = t.id(e), o = t.label(e), s = n(e);
+		if (typeof a != "string" || !a.trim()) throw Error(`Invalid category at row ${i + 1}: a non-empty string ID is required.`);
+		if (r.has(a)) throw Error(`Duplicate category ID "${a}".`);
+		if (typeof o != "string" || !o.trim()) throw Error(`Invalid label for category "${a}".`);
+		if (s !== null && (typeof s != "number" || !Number.isFinite(s))) throw Error(`Invalid value for category "${a}": expected a finite number or null.`);
+		return r.add(a), {
+			id: a,
+			label: o,
+			datum: e,
+			value: s
+		};
+	});
+}
+function t(e, t) {
+	return t === "input" ? [...e] : [...e].sort((e, n) => {
+		if (e.value === null && n.value !== null) return 1;
+		if (n.value === null && e.value !== null) return -1;
+		let r = (e.value ?? 0) - (n.value ?? 0);
+		return r ? r * (t === "descending" ? -1 : 1) : e.id < n.id ? -1 : +(e.id > n.id);
+	});
+}
+function n(e) {
+	let t = 0, n = 0;
+	for (let r of e) r.value !== null && (t = Math.min(t, r.value), n = Math.max(n, r.value));
+	return t === n ? [0, 1] : [t, n];
+}
+function r(e, t) {
+	let n = (e) => (e - t[0]) / (t[1] - t[0]) * 100, r = n(0), i = e === null ? r : n(e);
+	return {
+		zero: r,
+		left: Math.min(r, i),
+		width: Math.abs(i - r)
+	};
+}
+//#endregion
+//#region src/engine/analysis.ts
+function i(e, t) {
+	if (e !== null && (!Number.isFinite(e) || e < 0)) throw Error(`${t} must be a non-negative finite number or null.`);
+}
+function a(t) {
+	let n = e(t.data, t.category, t.value), r = Infinity;
+	for (let e of n) if (i(e.value, `Stage ${e.id}`), e.value !== null) {
+		if (e.value > r) throw Error(`Stage ${e.id} exceeds a preceding stage; cumulative funnel counts must not increase.`);
+		r = e.value;
+	}
+	let a = n[0]?.value;
+	return n.map((e, t) => {
+		let r = n[t - 1]?.value;
+		return {
+			...e,
+			share: e.value !== null && a != null && a > 0 ? e.value / a : null,
+			conversion: e.value !== null && r != null && r > 0 ? e.value / r : null,
+			drop: e.value !== null && r != null ? r - e.value : null
+		};
+	});
+}
+//#endregion
+export { n as a, r as i, e as n, t as r, a as t };

package/dist/cards/area-chart-card.d.ts

@@ -1,6 +1,7 @@
 import { ReactElement } from 'react';
-import { CartesianCardProps } from './cartesian-card';
+import { CardNormal, CartesianCardProps } from './cartesian-card';
 import { NumericKey } from './keys';
+import { NormalReport } from '../watch/board/board-state';
 export type { CardRange, CardSeries } from './cartesian-card';
 export interface AreaChartCardProps<Row, Key extends NumericKey<Row>> extends CartesianCardProps<Row, Key> {
     /**
@@ -11,6 +12,14 @@ export interface AreaChartCardProps<Row, Key extends NumericKey<Row>> extends Ca
     stack?: boolean | 'percent';
     /** `smooth` uses a monotone curve; `linear` draws straight segments. */
     curve?: 'smooth' | 'linear';
+    /**
+     * Watch one series against what is normal for it: a calm band where it is expected, a ring on
+     * each unusual reading, and a header note while it stays unusual. Every layer is off unless
+     * set. Unstacked cards only.
+     */
+    normal?: CardNormal<Row, NoInfer<Key>>;
+    /** Called when the watched series' status changes, such as when an incident starts or clears. */
+    onNormalChange?: (report: NormalReport | null) => void;
 }
 /**
  * A complete area chart card: headline, delta, period, plot, and value tiles.

package/dist/cards/box-plot-card.d.ts

@@ -0,0 +1,30 @@
+import { ReactElement } from 'react';
+import { BoxSummary } from '../engine/box';
+import { CartesianCardProps } from './cartesian-card';
+import { KeysOfType } from './keys';
+/** One box, with its x value and the row it came from. */
+interface BoxRow<Row> {
+    x: string | number | Date;
+    median: number | null;
+    box: BoxSummary | null;
+    source: Row;
+}
+type SharedProps<Row> = Omit<CartesianCardProps<BoxRow<Row>, 'median'>, 'series' | 'data' | 'ranges' | 'x' | 'headlineSeries' | 'pillSeries' | 'target' | 'forecast' | 'bleed' | 'tiles' | 'aggregate'>;
+export interface BoxPlotCardProps<Row> extends SharedProps<Row> {
+    data?: readonly Row[];
+    /** One box per row, placed by this field: labels, numbers, or dates. */
+    x: KeysOfType<Row, string | number | Date>;
+    /** Field holding each row's raw samples; Lilt computes the quartiles, whiskers and outliers. */
+    samples: KeysOfType<Row, readonly number[]>;
+    /** Names the series in hover. Defaults to "Median". */
+    label?: string;
+    color?: string;
+    /** Draw samples beyond the whiskers as dots. Defaults to true. */
+    outliers?: boolean;
+}
+/**
+ * Distributions side by side: quartile boxes, a median line, Tukey whiskers and outliers,
+ * computed from each row's raw samples. The headline is the median of every sample.
+ */
+export declare function BoxPlotCard<Row>({ data, x, samples, label, color, outliers, headline, ...props }: BoxPlotCardProps<Row>): ReactElement;
+export {};

package/dist/cards/cartesian-card.d.ts

@@ -1,8 +1,11 @@
 import { CSSProperties, ReactElement, ReactNode } from 'react';
-import { ChartAxisStyle, ChartBarAppearance, ChartBackground, ChartCurve, ChartMotion, ChartPalette, ChartHoverReadout, ChartHoverStyle, ChartTooltipIndicator, ChartStyle, ChartSurface } from '../types';
+import { ChartController, ChartMargins, ChartTooltipContext, NumericXConfig, TimeXConfig, ChartAxis, ChartBarAppearance, ChartBackground, ChartCurve, ChartMotion, ChartPalette, ChartHoverReadout, ChartHoverStyle, ChartSeries, ChartTooltipIndicator, ChartStyle, ChartSurface } from '../types';
 import { NumericKey, ResolvedX, XKey, XKind } from './keys';
 import { CardAggregate } from './format';
 import { AnimatedNumberVariant } from '../motion/animated-number';
+import { NormalSpec } from '../watch/engine/normal';
+import { NormalBreakdown } from '../watch/engine/explain';
+import { NormalReport } from '../watch/board/board-state';
 export interface CardSeries<Key extends string> {
     /** A numeric field of each row. */
     key: Key;
@@ -31,6 +34,24 @@ export interface CardForecast<Row> {
     /** Names the projected region and the hover caption. Defaults to "Forecast". */
     label?: string;
 }
+/**
+ * What normal looks like for one series of a line or unstacked area card. Every layer is off
+ * unless set; see `NormalSpec`. Projected rows are never judged.
+ */
+export interface CardNormal<Row, Key extends string = string> extends NormalSpec<Row> {
+    /** The watched series. Defaults to the headline series, then the first solid series. */
+    series?: Key;
+    /**
+     * Earlier rows to learn from without drawing them, such as the weeks before the day on screen.
+     * They come before `data`, in the same shape.
+     */
+    history?: readonly Row[];
+    /**
+     * Split a reading into the segments that add up to it, such as orders by device, so an unusual
+     * reading can say which segment caused it: "91% of the drop is Mobile Safari".
+     */
+    breakdown?: NormalBreakdown<Row>;
+}
 export interface CardRange<Row> {
     id: string;
     label: string;
@@ -76,8 +97,11 @@ export interface CartesianCardProps<Row, Key extends NumericKey<Row>> {
     formatX?: (value: string | number | Date) => string;
     /** Override x inference. Numbers default to `number`; use `time` for timestamps. */
     xType?: XKind;
-    /** Axis preset: `minimal` (default), `dots`, `inline`, `ruler`, or `classic`. */
-    axis?: ChartAxisStyle;
+    /**
+     * Axis preset: `minimal` (default), `dots`, `inline`, `ruler`, `classic`, or `segmented`, for
+     * both axes or one per axis, e.g. `{ x: 'minimal', y: { style: 'segmented', gradient: true } }`.
+     */
+    axis?: ChartAxis;
     /** Texture behind the plot: `dots` (default), `grid`, `lines`, or `none`. */
     background?: ChartBackground;
     /** Brighten the background around the hovered point. Defaults to true. */
@@ -143,7 +167,8 @@ export interface CartesianCardProps<Row, Key extends NumericKey<Row>> {
     /**
      * Link hover and pins with every card that uses the same name. Cards match by x: labels
      * exactly, dates and numbers to the nearest row. Every linked card shows its hover marks,
-     * pills, and headline at that point; only the card that owns a pin shows its release control.
+     * pills, and headline at that point. A click pins every linked card: the clicked card shows the
+     * pin and the others a ghost of it, and any of them releases it. Alt-click pins one card only.
      */
     sync?: string;
     loading?: boolean;
@@ -191,16 +216,71 @@ export type CardShape = {
     /** Curve and point markers of lines drawn over the bars. */
     curve?: ChartCurve;
     points?: boolean;
-};
+} | CardMarks;
+/**
+ * Column marks drawn from each series' fields, such as candles or range bars. Cards built on
+ * this shape keep every Cartesian card behaviour: headline, ranges, hover sync and tiles.
+ */
+export interface CardMarks {
+    kind: 'marks';
+    /** A stable description of everything below, so memoized series only rebuild when it changes. */
+    id: string;
+    /** Descriptor options for a series by key, such as its fields, colors, curve, or area. */
+    series?: (key: string) => Partial<ChartSeries<never>> | undefined;
+    /**
+     * The marks for the drawn series, as elements or fragments of them (not wrapped in a
+     * component), so the plot can find column marks. Dashed references still draw as lines.
+     */
+    draw: (ids: readonly string[]) => ReactNode;
+    includeZero: boolean;
+    scale?: 'linear' | 'log';
+    curve?: ChartCurve;
+    /** Values the y axis must reach, such as outliers beyond the fields. */
+    include?: readonly number[];
+    /** Slot every observation like a bar, so linked bar panes line up. Column marks imply it. */
+    slots?: boolean;
+    /** Label the x axis here. Turn off when a pane below carries it. Defaults to true. */
+    xAxis?: boolean;
+    /** Extra text after the hovered x in the headline caption, e.g. open, high and low. */
+    describe?: (inspection: ChartTooltipContext) => string | null;
+}
+/** Panes drawn under the main plot, linked to it: same data, x, margins and crosshair. */
+export interface CardPaneContext<Row> {
+    data: readonly Row[];
+    x: TimeXConfig<Row> | NumericXConfig<Row>;
+    controller: ChartController;
+    margins: ChartMargins;
+    /** The main plot's `axisInset` and `slots`, so a pane's observations sit under its own. */
+    axisInset: number;
+    slots: boolean;
+    axis: ChartAxis;
+    loading: boolean;
+    motion?: ChartMotion;
+    hoverStyle: ChartHoverStyle;
+    formatValue: (value: number) => string;
+    formatAxis: (value: number) => string;
+}
 /** Matches the default `--lilt-card-padding`. */
 export declare const CARD_PADDING = 20;
 /**
  * The shared card body: headline, delta, period, plot, and value tiles, with hover sync and
  * range comparison. Area, Line, and Bar cards differ only in their `shape`.
  */
-export declare function CartesianCard<Row, Key extends NumericKey<Row>>({ shape, title, data: suppliedData, x, series: seriesInput, headline: suppliedHeadline, aggregate: suppliedAggregate, headlineSeries, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, tiles, height, valueFormat, locale, formatValue: suppliedFormatValue, formatAxisValue: suppliedFormatAxisValue, formatX, xType, compare, target: suppliedTarget, forecast, sync, axis, hover, hoverStyle, background, spotlight, surface, badge, numberStyle, palette, bleed, axisInset, pillSeries, pillValue, pillPosition, tooltipIndicator, loading, motion, className, style, }: Omit<CartesianCardProps<Row, Key>, 'series'> & {
+export declare function CartesianCard<Row, Key extends NumericKey<Row>>({ shape, title, data: suppliedData, x, series: seriesInput, headline: suppliedHeadline, aggregate: suppliedAggregate, headlineSeries, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, tiles, height, valueFormat, locale, formatValue: suppliedFormatValue, formatAxisValue: suppliedFormatAxisValue, formatX, xType, compare, target: suppliedTarget, forecast, sync, axis, hover, hoverStyle, background, spotlight, surface, badge, numberStyle, palette, bleed, axisInset, pillSeries, pillValue, pillPosition, tooltipIndicator, loading, motion, className, style, panes, live, heading, restCaption, normal, onNormalChange, }: Omit<CartesianCardProps<Row, Key>, 'series'> & {
     series: readonly CoreSeries<Key>[];
     shape: CardShape;
+    /** Linked panes under the plot, such as volume or indicators. */
+    panes?: (context: CardPaneContext<Row>) => ReactNode;
+    /** Follow the newest observation as rows arrive. */
+    live?: boolean;
+    /** Richer title content, such as a ticker and its name; `title` still labels the chart. */
+    heading?: ReactNode;
+    /** Text beside the delta at rest, such as an absolute change, from the active data. */
+    restCaption?: (data: readonly Row[]) => ReactNode;
+    /** Watch one series against its normal. Line and unstacked area cards only. */
+    normal?: CardNormal<Row, NoInfer<Key>>;
+    /** Called when the watched series' status changes. */
+    onNormalChange?: (report: NormalReport | null) => void;
 }): ReactElement;
 /** The plot position where projections begin: a label's row, or the date or number itself. */
 export declare function forecastPosition<Row>(data: readonly Row[], x: string, resolved: ResolvedX<Row>, from: string | number): number | null;

package/dist/cards/chart-card.d.ts

@@ -20,8 +20,19 @@ export interface ChartCardProps {
     style?: CSSProperties | ChartStyle;
     'aria-label'?: string;
 }
+/**
+ * What a container such as a watch board adds to the card directly inside it: a tab that takes
+ * the badge's place, a tone for the card's edge, and a control that floats on the top edge.
+ */
+export interface CardFrame {
+    badge?: ReactNode;
+    tone?: 'warning' | 'critical' | null;
+    handle?: ReactNode;
+}
+/** Set by a container around one card. Cards nested inside that card do not see it. */
+export declare const CardFrameContext: import('react').Context<CardFrame | null>;
 /** The card surface every Lilt card shares: padding, radius, border, and theme tokens. */
-export declare function ChartCard({ children, surface, palette, motion, numberStyle, badge, className, style, 'aria-label': ariaLabel, }: ChartCardProps): ReactElement;
+export declare function ChartCard({ children, surface, palette, motion, numberStyle, badge: ownBadge, className, style, 'aria-label': ariaLabel, }: ChartCardProps): ReactElement;
 export interface CardBadgeProps {
     children?: ReactNode;
     className?: string;

package/dist/cards/line-chart-card.d.ts

@@ -1,6 +1,7 @@
 import { ReactElement } from 'react';
-import { CartesianCardProps } from './cartesian-card';
+import { CardNormal, CartesianCardProps } from './cartesian-card';
 import { NumericKey } from './keys';
+import { NormalReport } from '../watch/board/board-state';
 export interface LineChartCardProps<Row, Key extends NumericKey<Row>> extends CartesianCardProps<Row, Key> {
     /** `smooth` uses a monotone curve, `linear` straight segments, `step` holds each value flat. */
     curve?: 'smooth' | 'linear' | 'step';
@@ -11,6 +12,14 @@ export interface LineChartCardProps<Row, Key extends NumericKey<Row>> extends Ca
      * zero when the absolute level matters.
      */
     baseline?: 'auto' | 'zero';
+    /**
+     * Watch one series against what is normal for it: a calm band where it is expected, a ring on
+     * each unusual reading, and a header note while it stays unusual. Every layer is off unless
+     * set. Unstacked cards only.
+     */
+    normal?: CardNormal<Row, NoInfer<Key>>;
+    /** Called when the watched series' status changes, such as when an incident starts or clears. */
+    onNormalChange?: (report: NormalReport | null) => void;
 }
 /**
  * A complete line chart card: headline, delta, period, plot, and value tiles.

package/dist/cards/range-chart-card.d.ts

@@ -0,0 +1,28 @@
+import { ReactElement } from 'react';
+import { CartesianCardProps } from './cartesian-card';
+import { NumericKey } from './keys';
+type SharedProps<Row, Key extends NumericKey<Row>> = Omit<CartesianCardProps<Row, Key>, 'series' | 'headlineSeries' | 'pillSeries' | 'target' | 'forecast' | 'bleed' | 'tiles'>;
+export interface RangeChartCardProps<Row, Key extends NumericKey<Row>> extends SharedProps<Row, Key> {
+    /** Field holding the low end of each range. */
+    low: Key;
+    /** Field holding the high end of each range. */
+    high: Key;
+    /**
+     * Field holding each measured value, such as a mean inside its uncertainty. It drives the
+     * headline and pills. Defaults to `high`.
+     */
+    value?: Key;
+    /** Names the series in hover and tiles. Defaults to the value key. */
+    label?: string;
+    color?: string;
+    /** `bar` (default) floats a bar from low to high; `error` draws whiskers around the value. */
+    display?: 'bar' | 'error';
+    /** Per-series stat tile under the plot. Defaults to false. */
+    tiles?: boolean;
+}
+/**
+ * Ranges per observation: floating bars from low to high, or error bars around a value. The
+ * headline summarizes the values (the mean by default) and hover reads the range's ends.
+ */
+export declare function RangeChartCard<Row, const Key extends NumericKey<Row>>({ low, high, value, label, color, display, aggregate, tiles, ...props }: RangeChartCardProps<Row, Key>): ReactElement;
+export {};