@lilt-ui/charts 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # 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.

package/README.md

@@ -15,6 +15,7 @@
   <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>
 
@@ -142,12 +143,56 @@ export function MarketCard() {
 
 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
 
 - **Linked hover.** Give cards the same `sync` name and they read the same moment together.
 - **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

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/cartesian-card.d.ts

@@ -1,8 +1,11 @@
 import { CSSProperties, ReactElement, ReactNode } from 'react';
-import { ChartController, ChartMargins, ChartTooltipContext, NumericXConfig, TimeXConfig, ChartAxisStyle, ChartBarAppearance, ChartBackground, ChartCurve, ChartMotion, ChartPalette, ChartHoverReadout, ChartHoverStyle, ChartSeries, 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;
@@ -228,7 +253,7 @@ export interface CardPaneContext<Row> {
     /** The main plot's `axisInset` and `slots`, so a pane's observations sit under its own. */
     axisInset: number;
     slots: boolean;
-    axis: ChartAxisStyle;
+    axis: ChartAxis;
     loading: boolean;
     motion?: ChartMotion;
     hoverStyle: ChartHoverStyle;
@@ -241,7 +266,7 @@ 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, panes, live, heading, restCaption, }: 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. */
@@ -252,6 +277,10 @@ export declare function CartesianCard<Row, Key extends NumericKey<Row>>({ shape,
     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.