@lilt-ui/charts 0.9.2 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.11.0
+
+Every chart has a quiet empty state, and it can be yours.
+
+- A period with no data shows the same empty state on every card family: a still dot field around "No data for this period" by default, or `empty="shape"` for the chart's own outline at a whisper behind the message. Neither moves, so an empty chart never reads as loading.
+- `empty` takes a built-in look, any element of your own, or `null` for nothing. The chart places it in the plot area, inset to the card's padding; an empty card keeps its size. `ChartEmpty` is the built-in look as a component, so `empty={<ChartEmpty>No visits yet</ChartEmpty>}` keeps it with your words. Composed charts take `empty` on `Chart`.
+- Empty cards no longer claim a value: the headline reads a dash instead of 0, a supplied `delta` chip steps aside, and every family uses the same wording. An empty radial card keeps its height instead of collapsing to its header.
+
+## 0.10.0
+
+Every chart family now moves with one motion language, and cards are softer by default.
+
+- Added `TreemapChartCard` for flat or grouped part-to-whole layouts, `CalendarHeatmapCard` for UTC daily activity, `TimelineChartCard` for intervals with overlapping lanes, and `StripChartCard` for strip/beeswarm distributions.
+- All four include flat/depth paint, shared shimmer/draw/breathe skeletons and the existing opacity exit, reduced motion, retained rows during refresh, header composition, keyboard inspection, pin/release, and consumer-owned selection readouts.
+- Treemap has its own showcase page. The other additions live as forms of Heatmap, Range, and Scatter, with matching Preview/Code, data, props, shared settings, and loading controls.
+- Period switches morph on lines and areas. When time or number data changes to rows that share x values with the old ones, such as 7 → 21 days, the chart draws both sets while the x and y domains glide: shared points move to their new places, new days arrive from the edge and dropped days leave through it, in one layer. Unrelated rows still cross-fade; reduced motion still switches instantly.
+- Every chart family moves the same way. Horizontal bar rows blur while they travel to a new rank and drain away on leaving; radial slices land on the spring, departing slices collapse and new ones blur in; activity ring columns regrow dot by dot round the day; progress and stat rings land on the spring; funnel stages, radar vertices and sankey flows reshape from where they are instead of redrawing; scatter points, observation marks (treemap, calendar, timeline, strip) travel on the spring and departing ones shrink away; heatmap and calendar cells re-colour in a diagonal ripple. A light motion blur passes over each family as its period changes (line, area, combo, range, box and finance charts included; live charts excepted), and nothing animates on a plain resize. Data arriving after the last row grows out of it, so a line draws itself forward.
+- Bars snap when the set of bars changes, such as a shorter period. New bars rise out of the floor with a soft blur, rippling in; leaving bars drain back into it and narrow toward the gap, which the rest start closing partway through; bars that stay spring to their new place, width and height. A light motion blur passes over the plot as it happens. Bars are tracked by category on category axes, so a reordered chart moves each bar to its new slot. The first entrance uses the same arrival, so loading a page and changing period feel like one motion. Value-only updates are unchanged, and reduced motion switches instantly.
+- Showing or hiding a line or area series glides the y scale in a single layer while the series fades, instead of cross-fading two charts. Bars and stacks keep their existing transitions.
+- Cards draw Lilt's own period select instead of the native one: a pill that opens a frosted list of periods, with a blur swap of the chosen label, a highlight that travels between options, and the listbox keys (arrows, Home/End, Enter, Escape, type-ahead) returning focus to the pill. `ChartComponentsProvider rangeSelect={…}` swaps in your own select for every card below it, typed by `ChartRangeSelectProps`.
+- Softer cards by default. Elevated cards use a 24px radius and are lifted by tone and a hairline shadow instead of a border. The period select, card actions, delta chip, and axis hover badges are pills. Legend tiles lose their outline. The soft and accent tooltips are frosted glass (opaque under reduced transparency) with an 18px radius. Area fills fade fully to transparent. Colors, palettes, plot backgrounds (dots stay the default), and geometry are unchanged; `--lilt-card-radius` still overrides the radius.
+
 ## 0.9.2
 
 Cards can fit inside an existing dashboard widget without duplicating its heading and legend.

package/README.md

@@ -76,16 +76,22 @@ That's the whole card: the headline, the change chip, value tiles, and hover all
   <img alt="Stat cards with sparklines, bars, and a goal meter above a needle bar chart and a retention heatmap" src="https://cdn.jsdelivr.net/npm/@lilt-ui/charts/media/cards-dark.webp" />
 </picture>
 
-| For                  | Cards                                                                |
-| -------------------- | -------------------------------------------------------------------- |
-| **Trends**           | Area, Line, Bar, and Combo cards, overlapping, stacked, or as shares |
-| **At a glance**      | Stat cards with a sparkline, bars, a meter, or a ring                |
-| **Parts and goals**  | Radial, Progress, and Activity ring                                  |
-| **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     |
+| For                  | Cards                                                                   |
+| -------------------- | ----------------------------------------------------------------------- |
+| **Trends**           | Area, Line, Bar, and Combo cards, overlapping, stacked, or as shares    |
+| **At a glance**      | Stat cards with a sparkline, bars, a meter, or a ring                   |
+| **Parts and goals**  | Radial, Treemap, Progress, and Activity ring                            |
+| **Rankings**         | Horizontal bar, with shares and an "Other" row                          |
+| **Flows and change** | Funnel, Sankey, and Slope                                               |
+| **Patterns**         | Heatmap (matrix and calendar), Scatter (points, strip, beeswarm), Radar |
+| **Spread**           | Range (floating bars, error bars, timeline intervals) and Box plot      |
+| **Markets**          | Candlestick, Indicators, Price, Depth, Order book, and Portfolio        |
+
+### More ways to read observations
+
+`TreemapChartCard` reads `label`, `value`, and an optional `group` for one parent level. `CalendarHeatmapCard` reads `date` and `value`, with optional inclusive UTC `from`/`to` bounds. `TimelineChartCard` reads `label`, `start`, and `end`, and packs overlaps within optional `lane` categories. `StripChartCard` reads `category` and `value`; `display="beeswarm"` separates collisions without moving numeric positions.
+
+All four support `depth`, `loadingStyle="shimmer" | "draw" | "breathe"`, the shared skeleton fade, and reduced motion. Background refreshes keep accepted readings. They also accept `header={false}`, `onSelectionChange`, and `renderReadout` for your own presentation. Treemap areas must be nonnegative, calendar dates are UTC, and timeline durations are measured in milliseconds (displayed as hours by default).
 
 ## Finance charts
 
@@ -199,6 +205,26 @@ Cards that need attention rise, what you've seen calms down, and what clears set
 
 Omit `title` to render no visible title. `header={false}` removes the entire header, including the headline, delta and period controls. Cards with legend layouts accept `legend={false}` independently. `surface="ghost"` only removes the visual frame. Give embedded charts an `aria-label`; pass `data` directly when your app owns the period selector.
 
+Cards with `ranges` draw Lilt's period select: a pill that opens a frosted list, with arrows, Home/End, Enter, Escape and type-ahead. To use your design system's select in every card instead, wrap them once:
+
+```tsx
+import { ChartComponentsProvider, type ChartRangeSelectProps } from '@lilt-ui/charts';
+
+function PeriodSelect({ value, options, onValueChange, ...rest }: ChartRangeSelectProps) {
+  return (
+    <Select value={value} onValueChange={onValueChange} aria-label={rest['aria-label']}>
+      {options.map((option) => (
+        <SelectItem key={option.id} value={option.id}>
+          {option.label}
+        </SelectItem>
+      ))}
+    </Select>
+  );
+}
+
+<ChartComponentsProvider rangeSelect={PeriodSelect}>{children}</ChartComponentsProvider>;
+```
+
 `RadialChartCard` keeps its centre and pointer interaction with the legend hidden. Tab to the graphic and use arrows to inspect, Enter/Space to pin, and Escape to clear. With a controlled `selected`, Escape requests `onSelectedChange(null)` in every legend layout.
 
 Cards follow shadcn theme variables when your app defines them: `--card`, `--card-foreground`, `--muted-foreground`, `--border`, `--ring`, and `--chart-1` to `--chart-5`. Anything you leave out falls back to Lilt's own palette.

package/dist/cards/activity-ring-card.d.ts

@@ -1,5 +1,5 @@
 import { CSSProperties, ReactElement, ReactNode } from 'react';
-import { ChartLoadingStyle, ChartMotion, ChartPalette, ChartStyle, ChartSurface } from '../types';
+import { ChartLoadingStyle, ChartEmptyState, ChartMotion, ChartPalette, ChartStyle, ChartSurface } from '../types';
 import { CardRange } from './cartesian-card';
 import { NumericKey } from './keys';
 import { AnimatedNumberVariant } from '../motion/animated-number';
@@ -53,6 +53,11 @@ export interface ActivityRingCardProps<Row, Key extends NumericKey<Row>> {
     palette?: ChartPalette;
     loading?: boolean;
     loadingStyle?: ChartLoadingStyle;
+    /**
+     * What the card shows when the period has no data: `dots` (default), the chart's own `shape`,
+     * your own element such as `<ChartEmpty>No visits yet</ChartEmpty>`, or `null` for nothing.
+     */
+    empty?: ChartEmptyState;
     /** `none` turns off decorative motion; reduced-motion users get this automatically. */
     motion?: ChartMotion;
     className?: string;
@@ -65,4 +70,4 @@ export declare function clockLabel(hour: number): string;
  * filled by how much happened then. Hovering or stepping around the ring reads each slot in the
  * headline; tiles name the busiest and quietest times.
  */
-export declare function ActivityRingCard<Row, const Key extends NumericKey<Row>>({ title, header, 'aria-label': ariaLabel, data: suppliedData, hour, value, bucketMinutes, unit, maximum: suppliedMaximum, aggregate, height, depth, headline: suppliedHeadline, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, valueFormat, locale, formatValue: suppliedFormatValue, color, surface, badge, numberStyle, palette, loading, loadingStyle, motion, className, style, }: ActivityRingCardProps<Row, Key>): ReactElement;
+export declare function ActivityRingCard<Row, const Key extends NumericKey<Row>>({ title, header, 'aria-label': ariaLabel, data: suppliedData, hour, value, bucketMinutes, unit, maximum: suppliedMaximum, aggregate, height, depth, headline: suppliedHeadline, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, valueFormat, locale, formatValue: suppliedFormatValue, color, surface, badge, numberStyle, palette, loading, loadingStyle, empty: emptyState, motion, className, style, }: ActivityRingCardProps<Row, Key>): ReactElement;

package/dist/cards/calendar-heatmap-card.d.ts

@@ -0,0 +1,18 @@
+import { NumericKey, TimeKey } from './keys';
+import { ObservationsCardProps, ObservationScene } from './observations-card';
+/** Calendar dates are UTC days. Date-only strings are validated rather than rolled over. */
+export declare function utcDate(value: unknown): number | null;
+export interface CalendarHeatmapCardProps<Row, Key extends NumericKey<Row>> extends Omit<ObservationsCardProps<Row>, 'legend' | 'legendSwatch'> {
+    date: TimeKey<Row>;
+    value: Key;
+    /** Inclusive UTC date bounds. Default to the observed range. */
+    from?: string | number | Date;
+    to?: string | number | Date;
+    /** Monday by default; Sunday is 0. */
+    weekStartsOn?: 0 | 1;
+    /** UTC day used to distinguish unobserved future dates. Defaults to today. */
+    today?: string | number | Date;
+    domain?: readonly [number, number];
+}
+export declare function calendarLayout<Row>(data: readonly Row[], date: string, value: string, width: number, height: number, options?: Pick<CalendarHeatmapCardProps<Row, NumericKey<Row>>, 'from' | 'to' | 'today' | 'weekStartsOn' | 'domain' | 'color' | 'locale'>): ObservationScene<Row>;
+export declare function CalendarHeatmapCard<Row, const Key extends NumericKey<Row>>({ date, value, from, to, weekStartsOn, today, domain, color, locale, ...props }: CalendarHeatmapCardProps<Row, Key>): import("react/jsx-runtime").JSX.Element;

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

@@ -1,8 +1,9 @@
 import { CSSProperties, ReactElement, ReactNode } from 'react';
-import { ChartController, ChartMargins, ChartTooltipContext, NumericXConfig, TimeXConfig, ChartAxis, ChartBarAppearance, ChartBackground, ChartCurve, ChartMotion, ChartPalette, ChartHoverReadout, ChartHoverStyle, ChartSeries, ChartTooltipIndicator, ChartStyle, ChartSurface, CardLegend, ChartLegendSwatch, ChartLoadingStyle } from '../types';
+import { ChartController, ChartMargins, ChartTooltipContext, NumericXConfig, TimeXConfig, ChartAxis, ChartBarAppearance, ChartBackground, ChartCurve, ChartMotion, ChartPalette, ChartHoverReadout, ChartHoverStyle, ChartSeries, ChartTooltipIndicator, ChartStyle, ChartSurface, CardLegend, ChartLegendSwatch, ChartLoadingStyle, ChartEmptyState } from '../types';
 import { NumericKey, ResolvedX, XKey, XKind } from './keys';
 import { CardAggregate } from './format';
 import { AnimatedNumberVariant } from '../motion/animated-number';
+import { ChartEmptyShape } from '../lifecycle/chart-empty';
 import { NormalSpec } from '../watch/engine/normal';
 import { NormalBreakdown } from '../watch/engine/explain';
 import { NormalReport } from '../watch/board/board-state';
@@ -206,6 +207,11 @@ export interface CartesianCardProps<Row, Key extends NumericKey<Row>> {
      * Moving skeletons on a page share a clock.
      */
     loadingStyle?: ChartLoadingStyle;
+    /**
+     * What the plot shows when the period has no data: `dots` (default), the chart's own `shape`,
+     * your own element such as `<ChartEmpty>No visits yet</ChartEmpty>`, or `null` for nothing.
+     */
+    empty?: ChartEmptyState;
     /** `none` turns off decorative motion; reduced-motion users get this automatically. */
     motion?: ChartMotion;
     className?: string;
@@ -277,6 +283,8 @@ export interface CardMarks {
     xAxis?: boolean;
     /** Extra text after the hovered x in the headline caption, e.g. open, high and low. */
     describe?: (inspection: ChartTooltipContext) => string | null;
+    /** The outline the `shape` empty look draws. Defaults to `bars` for column marks. */
+    emptyShape?: ChartEmptyShape;
 }
 /** Panes drawn under the main plot, linked to it: same data, x, margins and crosshair. */
 export interface CardPaneContext<Row> {
@@ -301,7 +309,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, header, 'aria-label': ariaLabel, data: suppliedData, x, series: seriesInput, headline: suppliedHeadline, aggregate: suppliedAggregate, headlineSeries, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, tiles, legend, legendSwatch, depth, height, valueFormat, locale, formatValue: suppliedFormatValue, formatAxisValue: suppliedFormatAxisValue, formatX, xType, compare, target: suppliedTarget, forecast, sync, axis, hover, hoverStyle, background, spotlight, decimate, surface, badge, numberStyle, palette, bleed, axisInset, pillSeries, pillValue, pillPosition, tooltipIndicator, loading, loadingStyle, motion, className, style, panes, live, heading, restCaption, normal, onNormalChange, }: Omit<CartesianCardProps<Row, Key>, 'series'> & {
+export declare function CartesianCard<Row, Key extends NumericKey<Row>>({ shape, title, header, 'aria-label': ariaLabel, data: suppliedData, x, series: seriesInput, headline: suppliedHeadline, aggregate: suppliedAggregate, headlineSeries, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, tiles, legend, legendSwatch, depth, height, valueFormat, locale, formatValue: suppliedFormatValue, formatAxisValue: suppliedFormatAxisValue, formatX, xType, compare, target: suppliedTarget, forecast, sync, axis, hover, hoverStyle, background, spotlight, decimate, surface, badge, numberStyle, palette, bleed, axisInset, pillSeries, pillValue, pillPosition, tooltipIndicator, loading, loadingStyle, empty, 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. */

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

@@ -85,5 +85,8 @@ export interface ChartCardRangeProps<Option extends ChartCardRangeOption> {
     value?: NoInfer<Option['id']>;
     onValueChange?: (id: NoInfer<Option['id']>) => void;
 }
-/** Period pill. Renders a native select when options are supplied. */
+/**
+ * Period pill. With options it becomes Lilt's period select, or the select supplied through
+ * `ChartComponentsProvider`.
+ */
 export declare function ChartCardRange<const Option extends ChartCardRangeOption>({ label, options, value, onValueChange, }: ChartCardRangeProps<Option>): import("react/jsx-runtime").JSX.Element;

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

@@ -1,5 +1,5 @@
 import { CSSProperties, ReactElement, ReactNode } from 'react';
-import { ChartLoadingStyle, ChartMotion, ChartPalette, ChartStyle, ChartSurface, CardLegend, ChartLegendSwatch } from '../types';
+import { ChartLoadingStyle, ChartEmptyState, ChartMotion, ChartPalette, ChartStyle, ChartSurface, CardLegend, ChartLegendSwatch } from '../types';
 import { CardRange } from './cartesian-card';
 import { NumericKey, TextKey } from './keys';
 import { AnimatedNumberVariant } from '../motion/animated-number';
@@ -67,6 +67,11 @@ export interface FunnelChartCardProps<Row, Key extends NumericKey<Row>> {
     palette?: ChartPalette;
     loading?: boolean;
     loadingStyle?: ChartLoadingStyle;
+    /**
+     * What the card shows when the period has no data: `dots` (default), the chart's own `shape`,
+     * your own element such as `<ChartEmpty>No visits yet</ChartEmpty>`, or `null` for nothing.
+     */
+    empty?: ChartEmptyState;
     /** `none` turns off decorative motion; reduced-motion users get this automatically. */
     motion?: ChartMotion;
     className?: string;
@@ -97,4 +102,4 @@ export declare function pipeEnd(x: number, half: number, rx: number, side: 'left
  * its percentage on the band and its count in a tile beneath. Hovering a stage reads it in the
  * headline with the conversion from the step before.
  */
-export declare function FunnelChartCard<Row, const Key extends NumericKey<Row>>({ title, header, 'aria-label': ariaLabel, data: suppliedData, category, value, curve, colors, tracks, depth, height, headline: suppliedHeadline, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, valueFormat, legend, legendSwatch, locale, formatValue: suppliedFormatValue, color, surface, badge, numberStyle, palette, selected, onSelectedChange, loading, loadingStyle, motion: motionMode, className, style, }: FunnelChartCardProps<Row, Key>): ReactElement;
+export declare function FunnelChartCard<Row, const Key extends NumericKey<Row>>({ title, header, 'aria-label': ariaLabel, data: suppliedData, category, value, curve, colors, tracks, depth, height, headline: suppliedHeadline, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, valueFormat, legend, legendSwatch, locale, formatValue: suppliedFormatValue, color, surface, badge, numberStyle, palette, selected, onSelectedChange, loading, loadingStyle, empty: emptyState, motion: motionMode, className, style, }: FunnelChartCardProps<Row, Key>): ReactElement;

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

@@ -1,5 +1,5 @@
 import { CSSProperties, ReactElement, ReactNode } from 'react';
-import { ChartLoadingStyle, ChartMotion, ChartPalette, ChartStyle, ChartSurface } from '../types';
+import { ChartLoadingStyle, ChartEmptyState, ChartMotion, ChartPalette, ChartStyle, ChartSurface } from '../types';
 import { CardRange } from './cartesian-card';
 import { NumericKey, TextKey } from './keys';
 import { AnimatedNumberVariant } from '../motion/animated-number';
@@ -65,6 +65,11 @@ export interface HeatmapChartCardProps<Row, Key extends NumericKey<Row>> {
     palette?: ChartPalette;
     loading?: boolean;
     loadingStyle?: ChartLoadingStyle;
+    /**
+     * What the card shows when the period has no data: `dots` (default), the chart's own `shape`,
+     * your own element such as `<ChartEmpty>No visits yet</ChartEmpty>`, or `null` for nothing.
+     */
+    empty?: ChartEmptyState;
     /** `none` turns off decorative motion; reduced-motion users get this automatically. */
     motion?: ChartMotion;
     className?: string;
@@ -115,4 +120,4 @@ export declare function labelTier(index: number, count: number): 'major' | 'mino
  * labeled. Hovering or focusing a cell reads it in the headline; arrow keys move between cells.
  * Missing cells are hatched and say "No data", so they never read as zero.
  */
-export declare function HeatmapChartCard<Row, const Key extends NumericKey<Row>>({ title, header, 'aria-label': ariaLabel, data: suppliedData, x, y, value, columns, rows: rowOrder, domain, aggregate, height, radius, gap, depth, headline: suppliedHeadline, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, valueFormat, locale, formatValue: suppliedFormatValue, color, surface, badge, numberStyle, palette, loading, loadingStyle, motion: motionMode, className, style, }: HeatmapChartCardProps<Row, Key>): ReactElement;
+export declare function HeatmapChartCard<Row, const Key extends NumericKey<Row>>({ title, header, 'aria-label': ariaLabel, data: suppliedData, x, y, value, columns, rows: rowOrder, domain, aggregate, height, radius, gap, depth, headline: suppliedHeadline, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, valueFormat, locale, formatValue: suppliedFormatValue, color, surface, badge, numberStyle, palette, loading, loadingStyle, empty: emptyState, motion: motionMode, className, style, }: HeatmapChartCardProps<Row, Key>): ReactElement;

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

@@ -1,5 +1,5 @@
 import { CSSProperties, ReactElement, ReactNode } from 'react';
-import { ChartLoadingStyle, ChartMotion, ChartPalette, ChartStyle, ChartSurface, RankingOrder } from '../types';
+import { ChartLoadingStyle, ChartEmptyState, ChartMotion, ChartPalette, ChartStyle, ChartSurface, RankingOrder } from '../types';
 import { CardRange } from './cartesian-card';
 import { NumericKey, TextKey } from './keys';
 import { AnimatedNumberVariant } from '../motion/animated-number';
@@ -65,6 +65,11 @@ export interface HorizontalBarChartCardProps<Row, Key extends NumericKey<Row>> {
     palette?: ChartPalette;
     loading?: boolean;
     loadingStyle?: ChartLoadingStyle;
+    /**
+     * What the card shows when the period has no data: `dots` (default), the chart's own `shape`,
+     * your own element such as `<ChartEmpty>No visits yet</ChartEmpty>`, or `null` for nothing.
+     */
+    empty?: ChartEmptyState;
     /** `none` turns off decorative motion; reduced-motion users get this automatically. */
     motion?: ChartMotion;
     className?: string;
@@ -74,4 +79,4 @@ export interface HorizontalBarChartCardProps<Row, Key extends NumericKey<Row>> {
  * A ranked list card: each row carries a bar, its value, and its share of the total. Hovering a
  * row reads it in the headline; click pins it and the arrow keys move through the list.
  */
-export declare function HorizontalBarChartCard<Row, const Key extends NumericKey<Row>>({ title, header, 'aria-label': ariaLabel, data: suppliedData, category, value, headline: suppliedHeadline, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, sort, limit, otherLabel, share, rank, depth, barStyle, valueFormat, locale, formatValue: suppliedFormatValue, color, surface, badge, numberStyle, palette, selected, onSelectedChange, loading, loadingStyle, motion: motionMode, className, style, }: HorizontalBarChartCardProps<Row, Key>): ReactElement;
+export declare function HorizontalBarChartCard<Row, const Key extends NumericKey<Row>>({ title, header, 'aria-label': ariaLabel, data: suppliedData, category, value, headline: suppliedHeadline, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, sort, limit, otherLabel, share, rank, depth, barStyle, valueFormat, locale, formatValue: suppliedFormatValue, color, surface, badge, numberStyle, palette, selected, onSelectedChange, loading, loadingStyle, empty: emptyState, motion: motionMode, className, style, }: HorizontalBarChartCardProps<Row, Key>): ReactElement;

package/dist/cards/keys.d.ts

@@ -8,6 +8,8 @@ export type NumericKey<Row> = KeysOfType<Row, number | null | undefined>;
 export type TextKey<Row> = KeysOfType<Row, string>;
 /** Row keys usable as an x position: labels, numbers, or dates. */
 export type XKey<Row> = KeysOfType<Row, string | number | Date>;
+/** Nullable time fields for observations whose endpoints may still be missing. */
+export type TimeKey<Row> = KeysOfType<Row, string | number | Date | null | undefined>;
 export type XKind = 'category' | 'number' | 'time';
 export interface ResolvedX<Row> {
     kind: XKind;

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

@@ -0,0 +1,87 @@
+import { ReactNode } from 'react';
+import { CardLegend, ChartLegendSwatch, ChartLoadingStyle, ChartEmptyState, CategorySelection } from '../types';
+import { ChartCardProps } from './chart-card';
+import { CardRange } from './cartesian-card';
+/** Shared presentation options for observation-based cards. */
+export interface ObservationsCardProps<Row> extends Omit<ChartCardProps, 'children'> {
+    title?: string;
+    header?: boolean;
+    data?: readonly Row[];
+    height?: number;
+    depth?: boolean;
+    color?: string;
+    headline?: number;
+    aggregate?: 'sum' | 'mean' | 'max';
+    delta?: number;
+    deltaTone?: 'default' | 'inverse' | 'neutral';
+    range?: string;
+    ranges?: readonly CardRange<Row>[];
+    defaultRange?: string;
+    valueFormat?: Intl.NumberFormatOptions;
+    locale?: string;
+    formatValue?: (value: number) => string;
+    legend?: CardLegend | false;
+    legendSwatch?: ChartLegendSwatch;
+    loading?: boolean;
+    loadingStyle?: ChartLoadingStyle;
+    /**
+     * What the card shows when the period has no data: `dots` (default), the chart's own `shape`,
+     * your own element such as `<ChartEmpty>No visits yet</ChartEmpty>`, or `null` for nothing.
+     */
+    empty?: ChartEmptyState;
+    onSelectionChange?: (selection: CategorySelection<Row | null> | null) => void;
+    /** Optional consumer-owned readout, also available when the header is hidden. */
+    renderReadout?: (selection: CategorySelection<Row | null> | null) => ReactNode;
+}
+export interface ObservationMark<Row> {
+    id: string;
+    label: string;
+    datum: Row | null;
+    value: number | null;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    color: string;
+    group?: string;
+    text?: string;
+    detail?: string;
+    shape?: 'dot' | 'bar' | 'tile';
+    missing?: boolean;
+    future?: boolean;
+}
+export interface ObservationScene<Row> {
+    marks: ObservationMark<Row>[];
+    labels?: {
+        x: number;
+        y: number;
+        text: string;
+        anchor?: 'start' | 'middle' | 'end';
+    }[];
+    /** All readings, including observations with no visible area or position. */
+    readings?: {
+        id: string;
+        label: string;
+        value: number | null;
+        detail?: string;
+    }[];
+    groups?: {
+        id: string;
+        label: string;
+        color: string;
+        value: number | null;
+    }[];
+    note?: string;
+    error?: string;
+    height?: number;
+    width?: number;
+}
+export declare const seriesColor: (index: number) => string;
+export declare const readField: (row: unknown, key: string) => unknown;
+export declare const readNumber: (row: unknown, key: string) => number | null;
+/** Private shell: every family uses the same inspection, card and skeleton lifecycle. */
+export declare function ObservationsCard<Row>({ title, header, data: suppliedData, height, depth, headline, aggregate, delta, deltaTone, range, ranges, defaultRange, valueFormat, locale, formatValue, legend, legendSwatch, loading, loadingStyle, empty: emptyState, onSelectionChange, renderReadout, motion, className, color, layout, placeholder, family, ...frame }: ObservationsCardProps<Row> & {
+    family: string;
+    layout: (data: readonly Row[], width: number, height: number) => ObservationScene<Row>;
+    placeholder: (width: number, height: number) => ObservationScene<Row>;
+}): import("react/jsx-runtime").JSX.Element;

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

@@ -1,5 +1,5 @@
 import { CSSProperties, ReactElement, ReactNode } from 'react';
-import { ChartLoadingStyle, ChartMotion, ChartPalette, ChartStyle, ChartSurface, CardLegend, ChartLegendSwatch } from '../types';
+import { ChartLoadingStyle, ChartEmptyState, ChartMotion, ChartPalette, ChartStyle, ChartSurface, CardLegend, ChartLegendSwatch } from '../types';
 import { CardRange, CardSeries } from './cartesian-card';
 import { NumericKey, TextKey } from './keys';
 import { AnimatedNumberVariant } from '../motion/animated-number';
@@ -58,6 +58,11 @@ export interface RadarChartCardProps<Row, Key extends NumericKey<Row>> {
     palette?: ChartPalette;
     loading?: boolean;
     loadingStyle?: ChartLoadingStyle;
+    /**
+     * What the card shows when the period has no data: `dots` (default), the chart's own `shape`,
+     * your own element such as `<ChartEmpty>No visits yet</ChartEmpty>`, or `null` for nothing.
+     */
+    empty?: ChartEmptyState;
     /** `none` turns off decorative motion; reduced-motion users get this automatically. */
     motion?: ChartMotion;
     className?: string;
@@ -103,5 +108,5 @@ export declare function profilePath(fractions: readonly (number | null)[], radiu
  * shape of strengths and gaps reads at a glance. Hovering or stepping around the spokes reads
  * every profile at that dimension.
  */
-export declare function RadarChartCard<Row, const Key extends NumericKey<Row>>({ title, header, 'aria-label': ariaLabel, data: suppliedData, category, series, domain: suppliedDomain, aggregate, grid, height, headline: suppliedHeadline, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, valueFormat, legend, legendSwatch, locale, formatValue: suppliedFormatValue, surface, badge, numberStyle, palette, loading, loadingStyle, motion: motionMode, className, style, }: RadarChartCardProps<Row, Key>): ReactElement;
+export declare function RadarChartCard<Row, const Key extends NumericKey<Row>>({ title, header, 'aria-label': ariaLabel, data: suppliedData, category, series, domain: suppliedDomain, aggregate, grid, height, headline: suppliedHeadline, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, valueFormat, legend, legendSwatch, locale, formatValue: suppliedFormatValue, surface, badge, numberStyle, palette, loading, loadingStyle, empty: emptyState, motion: motionMode, className, style, }: RadarChartCardProps<Row, Key>): ReactElement;
 export {};

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

@@ -1,5 +1,5 @@
 import { CSSProperties, ReactElement, ReactNode } from 'react';
-import { ChartMotion, ChartLoadingStyle, ChartPalette, ChartStyle, ChartSurface, RankingOrder, CardLegend, ChartLegendSwatch } from '../types';
+import { ChartMotion, ChartLoadingStyle, ChartEmptyState, ChartPalette, ChartStyle, ChartSurface, RankingOrder, CardLegend, ChartLegendSwatch } from '../types';
 import { CardRange } from './cartesian-card';
 import { NumericKey, TextKey } from './keys';
 import { RankedRow } from './rank';
@@ -86,6 +86,11 @@ export interface RadialChartCardProps<Row, Key extends NumericKey<Row>> {
     loading?: boolean;
     /** Shimmer (default), a clockwise draw, or a gentle pulse. Honors reduced motion. */
     loadingStyle?: ChartLoadingStyle;
+    /**
+     * What the card shows when the period has no data: `dots` (default), the chart's own `shape`,
+     * your own element such as `<ChartEmpty>No visits yet</ChartEmpty>`, or `null` for nothing.
+     */
+    empty?: ChartEmptyState;
     /** `none` turns off decorative motion; reduced-motion users get this automatically. */
     motion?: ChartMotion;
     className?: string;
@@ -119,5 +124,5 @@ export declare function ringAngles(rows: readonly RankedRow[]): Slice[];
  * A donut or pie card: the headline total, slices with a matching legend, and each slice's
  * share. Hovering a slice or a legend row reads it in the headline.
  */
-export declare function RadialChartCard<Row, const Key extends NumericKey<Row>>({ title, header, 'aria-label': ariaLabel, data: suppliedData, category, value, variant, depth, legend, legendSwatch, headline: suppliedHeadline, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, limit, otherLabel, sort, valueFormat, locale, formatValue: suppliedFormatValue, surface, badge, numberStyle, palette, selected, onSelectedChange, colors: fixedColors, center, loading, loadingStyle, motion: motionMode, className, style, }: RadialChartCardProps<Row, Key>): ReactElement;
+export declare function RadialChartCard<Row, const Key extends NumericKey<Row>>({ title, header, 'aria-label': ariaLabel, data: suppliedData, category, value, variant, depth, legend, legendSwatch, headline: suppliedHeadline, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, limit, otherLabel, sort, valueFormat, locale, formatValue: suppliedFormatValue, surface, badge, numberStyle, palette, selected, onSelectedChange, colors: fixedColors, center, loading, loadingStyle, empty: emptyState, motion: motionMode, className, style, }: RadialChartCardProps<Row, Key>): ReactElement;
 export {};

package/dist/cards/range-select.d.ts

@@ -0,0 +1,28 @@
+import { ComponentType, ReactNode } from 'react';
+/** What a card hands its period select: the periods, the chosen one, and how to change it. */
+export interface ChartRangeSelectProps {
+    value: string;
+    options: readonly {
+        id: string;
+        label: string;
+    }[];
+    onValueChange: (id: string) => void;
+    /** Accessible name for the control, e.g. "Period". */
+    'aria-label': string;
+}
+/**
+ * Swap in your own components for the controls cards draw. `rangeSelect` replaces every card's
+ * period select below it, so an app can use its design system's select (shadcn, Base UI, …).
+ * Without it, cards use Lilt's own.
+ */
+export declare function ChartComponentsProvider({ rangeSelect, children, }: {
+    rangeSelect?: ComponentType<ChartRangeSelectProps>;
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function useCustomRangeSelect(): ComponentType<ChartRangeSelectProps> | null;
+/**
+ * Lilt's period select: a pill that opens a frosted list of periods. It follows the listbox
+ * pattern, so arrows, Home, End, Enter, Escape and typing a period's first letter all work,
+ * and focus returns to the pill when the list closes.
+ */
+export declare function RangeSelect({ value, options, onValueChange, 'aria-label': ariaLabel, }: ChartRangeSelectProps): import("react/jsx-runtime").JSX.Element;

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

@@ -1,6 +1,6 @@
 import { CSSProperties, ReactElement, ReactNode } from 'react';
 import { SankeyGraph, SankeyLink, SankeyNode } from '../engine/sankey';
-import { ChartLoadingStyle, ChartMotion, ChartPalette, ChartStyle, ChartSurface } from '../types';
+import { ChartLoadingStyle, ChartEmptyState, ChartMotion, ChartPalette, ChartStyle, ChartSurface } from '../types';
 import { CardRange } from './cartesian-card';
 import { NumericKey, TextKey } from './keys';
 import { AnimatedNumberVariant } from '../motion/animated-number';
@@ -52,6 +52,11 @@ export interface SankeyChartCardProps<Row, Key extends NumericKey<Row>> {
     palette?: ChartPalette;
     loading?: boolean;
     loadingStyle?: ChartLoadingStyle;
+    /**
+     * What the card shows when the period has no data: `dots` (default), the chart's own `shape`,
+     * your own element such as `<ChartEmpty>No visits yet</ChartEmpty>`, or `null` for nothing.
+     */
+    empty?: ChartEmptyState;
     /** `none` turns off decorative motion; reduced-motion users get this automatically. */
     motion?: ChartMotion;
     className?: string;
@@ -76,5 +81,5 @@ export declare function sankeyGraph<Row>({ data, source, target, value, conserva
  * amount that moved. Hovering or stepping through flows with the arrow keys reads each in the
  * headline with its share of the step it left.
  */
-export declare function SankeyChartCard<Row, const Key extends NumericKey<Row>>({ title, header, 'aria-label': ariaLabel, data: suppliedData, source, target, value, conservation, depth, height, headline: suppliedHeadline, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, valueFormat, locale, formatValue: suppliedFormatValue, surface, badge, numberStyle, palette, loading, loadingStyle, motion: motionMode, className, style, }: SankeyChartCardProps<Row, Key>): ReactElement;
+export declare function SankeyChartCard<Row, const Key extends NumericKey<Row>>({ title, header, 'aria-label': ariaLabel, data: suppliedData, source, target, value, conservation, depth, height, headline: suppliedHeadline, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, valueFormat, locale, formatValue: suppliedFormatValue, surface, badge, numberStyle, palette, loading, loadingStyle, empty: emptyState, motion: motionMode, className, style, }: SankeyChartCardProps<Row, Key>): ReactElement;
 export {};

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

@@ -1,5 +1,5 @@
 import { CSSProperties, ReactElement, ReactNode } from 'react';
-import { ChartLoadingStyle, ChartMotion, ChartPalette, ChartStyle, ChartSurface, CardLegend, ChartLegendSwatch } from '../types';
+import { ChartLoadingStyle, ChartEmptyState, ChartMotion, ChartPalette, ChartStyle, ChartSurface, CardLegend, ChartLegendSwatch } from '../types';
 import { CardRange } from './cartesian-card';
 import { NumericKey, TextKey } from './keys';
 import { AnimatedNumberVariant } from '../motion/animated-number';
@@ -72,6 +72,11 @@ export interface ScatterChartCardProps<Row, Key extends NumericKey<Row>> {
     palette?: ChartPalette;
     loading?: boolean;
     loadingStyle?: ChartLoadingStyle;
+    /**
+     * What the card shows when the period has no data: `dots` (default), the chart's own `shape`,
+     * your own element such as `<ChartEmpty>No visits yet</ChartEmpty>`, or `null` for nothing.
+     */
+    empty?: ChartEmptyState;
     /** `none` turns off decorative motion; reduced-motion users get this automatically. */
     motion?: ChartMotion;
     className?: string;
@@ -104,4 +109,4 @@ export declare function clipTrend(fit: {
  * and colored by group. Hovering or stepping through points with the arrow keys reads each one in
  * the headline, with its position marked on both axes.
  */
-export declare function ScatterChartCard<Row, const Key extends NumericKey<Row>>({ title, header, 'aria-label': ariaLabel, data: suppliedData, x, y, size, sizeLabel, group, label, xLabel, yLabel, trend, depth, height, aggregate, headline: suppliedHeadline, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, valueFormat, legend, legendSwatch, xFormat, locale, formatValue: suppliedFormatValue, formatX: suppliedFormatX, color, surface, badge, numberStyle, palette, loading, loadingStyle, motion: motionMode, className, style, }: ScatterChartCardProps<Row, Key>): ReactElement;
+export declare function ScatterChartCard<Row, const Key extends NumericKey<Row>>({ title, header, 'aria-label': ariaLabel, data: suppliedData, x, y, size, sizeLabel, group, label, xLabel, yLabel, trend, depth, height, aggregate, headline: suppliedHeadline, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, valueFormat, legend, legendSwatch, xFormat, locale, formatValue: suppliedFormatValue, formatX: suppliedFormatX, color, surface, badge, numberStyle, palette, loading, loadingStyle, empty: emptyState, motion: motionMode, className, style, }: ScatterChartCardProps<Row, Key>): ReactElement;

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

@@ -1,6 +1,6 @@
 import { CSSProperties, ReactElement, ReactNode } from 'react';
 import { SlopeOrder } from '../engine/slope';
-import { ChartLoadingStyle, ChartMotion, ChartPalette, ChartStyle, ChartSurface } from '../types';
+import { ChartLoadingStyle, ChartEmptyState, ChartMotion, ChartPalette, ChartStyle, ChartSurface } from '../types';
 import { CardRange } from './cartesian-card';
 import { NumericKey, TextKey } from './keys';
 import { AnimatedNumberVariant } from '../motion/animated-number';
@@ -70,6 +70,11 @@ export interface SlopeChartCardProps<Row, Key extends NumericKey<Row>> {
     palette?: ChartPalette;
     loading?: boolean;
     loadingStyle?: ChartLoadingStyle;
+    /**
+     * What the card shows when the period has no data: `dots` (default), the chart's own `shape`,
+     * your own element such as `<ChartEmpty>No visits yet</ChartEmpty>`, or `null` for nothing.
+     */
+    empty?: ChartEmptyState;
     /** `none` turns off decorative motion; reduced-motion users get this automatically. */
     motion?: ChartMotion;
     className?: string;
@@ -81,4 +86,4 @@ export interface SlopeChartCardProps<Row, Key extends NumericKey<Row>> {
  * category reads its later value and change in the headline; click pins it, and the arrow keys
  * move through categories.
  */
-export declare function SlopeChartCard<Row, const Key extends NumericKey<Row>>({ title, header, 'aria-label': ariaLabel, data: suppliedData, category, from, to, fromLabel, toLabel, variant, depth, sort, aggregate, headline: suppliedHeadline, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, color, height, valueFormat, locale, formatValue: suppliedFormatValue, surface, badge, numberStyle, palette, loading, loadingStyle, motion: motionMode, className, style, }: SlopeChartCardProps<Row, Key>): ReactElement;
+export declare function SlopeChartCard<Row, const Key extends NumericKey<Row>>({ title, header, 'aria-label': ariaLabel, data: suppliedData, category, from, to, fromLabel, toLabel, variant, depth, sort, aggregate, headline: suppliedHeadline, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, color, height, valueFormat, locale, formatValue: suppliedFormatValue, surface, badge, numberStyle, palette, loading, loadingStyle, empty: emptyState, motion: motionMode, className, style, }: SlopeChartCardProps<Row, Key>): ReactElement;

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

@@ -1,5 +1,5 @@
 import { CSSProperties, ReactElement, ReactNode } from 'react';
-import { ChartBarAppearance, ChartLoadingStyle, ChartMotion, ChartPalette, ChartStyle, ChartSurface } from '../types';
+import { ChartBarAppearance, ChartLoadingStyle, ChartEmptyState, ChartMotion, ChartPalette, ChartStyle, ChartSurface } from '../types';
 import { NumericKey, XKey, XKind } from './keys';
 import { CardAggregate } from './format';
 import { AnimatedNumberVariant } from '../motion/animated-number';
@@ -70,10 +70,15 @@ export interface StatCardProps<Row, Key extends NumericKey<Row>> {
     palette?: ChartPalette;
     loading?: boolean;
     loadingStyle?: ChartLoadingStyle;
+    /**
+     * What the trend shows when the period has no data: `dots` (default), the chart's own `shape`,
+     * your own element, or `null` for nothing. The headline reads a dash either way.
+     */
+    empty?: ChartEmptyState;
     motion?: ChartMotion;
     className?: string;
     style?: CSSProperties | ChartStyle;
 }
 /** Cells of a meter: whole cells up to the value, then one cell trimmed to the exact remainder. */
 export declare function meterCells(ratio: number, count?: number): number[];
-export declare function StatCard<Row, const Key extends NumericKey<Row>>({ title, header, 'aria-label': ariaLabel, data, value: valueKey, x, xType, headline: suppliedHeadline, aggregate, delta, deltaTone, caption, chart, depth, barStyle, target, sync, height, color, aside, valueFormat, locale, formatValue: suppliedFormatValue, formatX, surface, badge, numberStyle, palette, loading, motion, loadingStyle, className, style, }: StatCardProps<Row, Key>): ReactElement;
+export declare function StatCard<Row, const Key extends NumericKey<Row>>({ title, header, 'aria-label': ariaLabel, data, value: valueKey, x, xType, headline: suppliedHeadline, aggregate, delta, deltaTone, caption, chart, depth, barStyle, target, sync, height, color, aside, valueFormat, locale, formatValue: suppliedFormatValue, formatX, surface, badge, numberStyle, palette, loading, motion, loadingStyle, empty, className, style, }: StatCardProps<Row, Key>): ReactElement;

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

@@ -0,0 +1,15 @@
+import { NumericKey, TextKey } from './keys';
+import { ObservationsCardProps, ObservationScene } from './observations-card';
+export interface StripChartCardProps<Row, Key extends NumericKey<Row>> extends Omit<ObservationsCardProps<Row>, 'legend' | 'legendSwatch'> {
+    category: TextKey<Row>;
+    value: Key;
+    /** Unique point identity and accessible name. Falls back to the row index. */
+    label?: TextKey<Row>;
+    /** Strip uses deterministic vertical jitter; beeswarm avoids collisions. */
+    display?: 'strip' | 'beeswarm';
+    radius?: number;
+}
+/** Move only across the category band; each numeric position stays exact. */
+export declare function swarmOffsets(positions: readonly number[], diameter: number): number[];
+export declare function stripLayout<Row>(data: readonly Row[], category: string, value: string, label: string | undefined, width: number, height: number, display: 'strip' | 'beeswarm', radius: number, format: (value: number) => string, color?: string): ObservationScene<Row>;
+export declare function StripChartCard<Row, const Key extends NumericKey<Row>>({ category, value, label, display, radius, color, locale, valueFormat, formatValue, aggregate, ...props }: StripChartCardProps<Row, Key>): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,18 @@
+import { TextKey, TimeKey } from './keys';
+import { ObservationsCardProps, ObservationScene } from './observations-card';
+export interface TimelineChartCardProps<Row> extends ObservationsCardProps<Row> {
+    label: TextKey<Row>;
+    /** Optional stable identity when labels repeat. */
+    id?: TextKey<Row>;
+    start: TimeKey<Row>;
+    end: TimeKey<Row>;
+    /** Intervals sharing a lane stack into subrows when they overlap. */
+    lane?: TextKey<Row>;
+    /** Optional color category, such as a machine state. */
+    group?: TextKey<Row>;
+    /** Formats UTC axis labels and interval endpoints. */
+    formatTime?: (timestamp: number) => string;
+}
+export declare function intervalTime(value: unknown): number | null;
+export declare function timelineLayout<Row>(data: readonly Row[], options: Pick<TimelineChartCardProps<Row>, 'label' | 'id' | 'start' | 'end' | 'lane' | 'group' | 'color'>, width: number, height: number, formatTime: (time: number) => string): ObservationScene<Row>;
+export declare function TimelineChartCard<Row>({ label, id, start, end, lane, group, color, formatTime: suppliedFormatTime, locale, formatValue, aggregate, ...props }: TimelineChartCardProps<Row>): import("react/jsx-runtime").JSX.Element;