@lilt-ui/charts 0.9.1 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 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.
+
+### Card composition
+
+- Every chart card accepts an optional `title`, an independent `aria-label`, and `header={false}`. Omitted titles render no title element. Hiding the header removes the headline, delta and period controls without reserving their space. Depth summary stats follow the header; order book column headings and stat ring graphics remain.
+- Cards with legend layouts accept `legend={false}` without changing their data, colours or marks. Existing layouts and defaults remain. `surface="ghost"` continues to change only the visual frame.
+- Radial cards keep custom centre content, controlled selection and pointer inspection with the header and legend hidden. The graphic supports keyboard inspection and pinning, with a screen-reader data table and no stale readings while loading.
+
+### Fixes
+
+- Escape releases a radial pin in every legend layout, including inline, and requests `onSelectedChange(null)` for controlled selection.
+
+### Documentation
+
+- Family prop tables, card composition guidance, a radial Plot only preview and its generated source, package READMEs, API contract and both LLM references describe the same embedding controls.
+
 ## 0.9.1
 
 Charts fit small dashboard widgets, and category cards share their selection with your page. From a first adoption in an existing app.

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
 
@@ -197,6 +203,30 @@ Cards that need attention rise, what you've seen calms down, and what clears set
 
 ## Fits your design system
 
+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.
 
 Every Lilt style lives in the `lilt` cascade layer, so your CSS wins without specificity tricks. With Tailwind, declare the layer order once at the top of your global stylesheet:

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

@@ -6,7 +6,12 @@ import { AnimatedNumberVariant } from '../motion/animated-number';
 /** How the resting headline sums up the day. */
 export type ActivityAggregate = 'sum' | 'mean' | 'max';
 export interface ActivityRingCardProps<Row, Key extends NumericKey<Row>> {
-    title: string;
+    /** Optional visible title. Use aria-label to name an embedded chart. */
+    title?: string;
+    /** Show the header, including headline and period controls. Defaults to true. */
+    header?: boolean;
+    /** Accessible name, independent of the visible title. */
+    'aria-label'?: string;
     /** One row per time slot. Omit when `ranges` supplies the data. */
     data?: readonly Row[];
     /** Numeric field with the time of day in hours, from 0 up to 24; 14.5 is 14:30. */
@@ -60,4 +65,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, 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, 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

@@ -61,7 +61,12 @@ export interface CardRange<Row> {
 }
 /** Props every Cartesian card shares. Each card adds its own shape options. */
 export interface CartesianCardProps<Row, Key extends NumericKey<Row>> {
-    title: string;
+    /** Optional visible title. Use aria-label to name an embedded chart. */
+    title?: string;
+    /** Show the header, including headline and period controls. Defaults to true. */
+    header?: boolean;
+    /** Accessible name, independent of the visible title. */
+    'aria-label'?: string;
     /** One row per x position. Omit when `ranges` supplies the data. */
     data?: readonly Row[];
     /** Field used for the x axis: labels, numbers, or dates. */
@@ -89,8 +94,9 @@ export interface CartesianCardProps<Row, Key extends NumericKey<Row>> {
     /**
      * How the legend under the plot lays out: value `tiles` (default), compact `inline` labels,
      * `list` rows, tinted `pills`, or `bars` that also draw each value against the largest.
+     * False removes the legend without changing the data or marks.
      */
-    legend?: CardLegend;
+    legend?: CardLegend | false;
     /** The mark beside each legend label: `square` (default), `dot`, or `line`. */
     legendSwatch?: ChartLegendSwatch;
     /**
@@ -295,7 +301,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, 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, 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

@@ -1,4 +1,4 @@
-import { CSSProperties, ReactElement, ReactNode } from 'react';
+import { CSSProperties, KeyboardEventHandler, ReactElement, ReactNode } from 'react';
 import { AnimatedNumberVariant } from '../motion/animated-number';
 import { ChartMotion, ChartPalette, ChartStyle, ChartSurface } from '../types';
 export interface ChartCardProps {
@@ -19,6 +19,7 @@ export interface ChartCardProps {
     className?: string;
     style?: CSSProperties | ChartStyle;
     'aria-label'?: string;
+    onKeyDown?: KeyboardEventHandler<HTMLElement>;
 }
 /**
  * What a container such as a watch board adds to the card directly inside it: a tab that takes
@@ -32,7 +33,7 @@ export interface CardFrame {
 /** 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: ownBadge, className, style, 'aria-label': ariaLabel, }: ChartCardProps): ReactElement;
+export declare function ChartCard({ children, surface, palette, motion, numberStyle, badge: ownBadge, className, style, 'aria-label': ariaLabel, onKeyDown, }: ChartCardProps): ReactElement;
 export interface CardBadgeProps {
     children?: ReactNode;
     className?: string;
@@ -84,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

@@ -4,7 +4,12 @@ import { CardRange } from './cartesian-card';
 import { NumericKey, TextKey } from './keys';
 import { AnimatedNumberVariant } from '../motion/animated-number';
 export interface FunnelChartCardProps<Row, Key extends NumericKey<Row>> {
-    title: string;
+    /** Optional visible title. Use aria-label to name an embedded chart. */
+    title?: string;
+    /** Show the header, including headline and period controls. Defaults to true. */
+    header?: boolean;
+    /** Accessible name, independent of the visible title. */
+    'aria-label'?: string;
     /** One row per stage, in funnel order. Omit when `ranges` supplies the data. */
     data?: readonly Row[];
     /** Text field that names each stage. Names must be unique. */
@@ -37,8 +42,9 @@ export interface FunnelChartCardProps<Row, Key extends NumericKey<Row>> {
     /**
      * How the legend lays out: value `tiles` (default), compact `inline` labels, `list` rows, tinted
      * `pills`, or `bars` that also draw each value against the largest.
+     * False removes the legend without changing the data or marks.
      */
-    legend?: CardLegend;
+    legend?: CardLegend | false;
     /** The mark beside each legend label: `square` (default), `dot`, or `line`. */
     legendSwatch?: ChartLegendSwatch;
     valueFormat?: Intl.NumberFormatOptions;
@@ -91,4 +97,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, 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, motion: motionMode, className, style, }: FunnelChartCardProps<Row, Key>): ReactElement;

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

@@ -6,7 +6,12 @@ import { AnimatedNumberVariant } from '../motion/animated-number';
 /** How the resting headline summarizes every known cell. */
 export type HeatmapAggregate = 'sum' | 'mean' | 'max';
 export interface HeatmapChartCardProps<Row, Key extends NumericKey<Row>> {
-    title: string;
+    /** Optional visible title. Use aria-label to name an embedded chart. */
+    title?: string;
+    /** Show the header, including headline and period controls. Defaults to true. */
+    header?: boolean;
+    /** Accessible name, independent of the visible title. */
+    'aria-label'?: string;
     /** One row per cell. Omit when `ranges` supplies the data. */
     data?: readonly Row[];
     /** Text field that places a cell in a column, e.g. the hour. */
@@ -110,4 +115,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, 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, motion: motionMode, className, style, }: HeatmapChartCardProps<Row, Key>): ReactElement;

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

@@ -5,7 +5,12 @@ import { NumericKey, TextKey } from './keys';
 import { AnimatedNumberVariant } from '../motion/animated-number';
 export { rankRows } from './rank';
 export interface HorizontalBarChartCardProps<Row, Key extends NumericKey<Row>> {
-    title: string;
+    /** Optional visible title. Use aria-label to name an embedded chart. */
+    title?: string;
+    /** Show the header, including headline and period controls. Defaults to true. */
+    header?: boolean;
+    /** Accessible name, independent of the visible title. */
+    'aria-label'?: string;
     /** One row per category. Omit when `ranges` supplies the data. */
     data?: readonly Row[];
     /** Text field that names each row. Names must be unique. */
@@ -69,4 +74,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, 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, 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,82 @@
+import { ReactNode } from 'react';
+import { CardLegend, ChartLegendSwatch, ChartLoadingStyle, 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;
+    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, 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/progress-card.d.ts

@@ -10,7 +10,12 @@ export interface ProgressRange {
     delta?: number;
 }
 export interface ProgressCardProps {
-    title: string;
+    /** Optional visible title. Use aria-label to name an embedded chart. */
+    title?: string;
+    /** Show the header, including headline and period controls. Defaults to true. */
+    header?: boolean;
+    /** Accessible name, independent of the visible title. */
+    'aria-label'?: string;
     /** The measured amount. `null` shows a dash and an empty track, never zero. */
     value?: number | null;
     /** The goal, in the same unit as the value. */
@@ -58,4 +63,4 @@ export interface ProgressCardProps {
  * One value against a goal: the value in the header, and a large ring or gauge with the
  * percentage reached. Past the goal the ring stays full and the percentage keeps counting.
  */
-export declare function ProgressCard({ title, value: suppliedValue, target: suppliedTarget, label, variant, depth, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, footer, valueFormat, locale, formatValue, color, surface, badge, numberStyle, palette, loading, loadingStyle, motion: motionMode, className, style, }: ProgressCardProps): ReactElement;
+export declare function ProgressCard({ title, header, 'aria-label': ariaLabel, value: suppliedValue, target: suppliedTarget, label, variant, depth, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, footer, valueFormat, locale, formatValue, color, surface, badge, numberStyle, palette, loading, loadingStyle, motion: motionMode, className, style, }: ProgressCardProps): ReactElement;

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

@@ -6,7 +6,12 @@ import { AnimatedNumberVariant } from '../motion/animated-number';
 /** How the resting headline sums up the first series across dimensions. */
 export type RadarAggregate = 'mean' | 'sum' | 'max';
 export interface RadarChartCardProps<Row, Key extends NumericKey<Row>> {
-    title: string;
+    /** Optional visible title. Use aria-label to name an embedded chart. */
+    title?: string;
+    /** Show the header, including headline and period controls. Defaults to true. */
+    header?: boolean;
+    /** Accessible name, independent of the visible title. */
+    'aria-label'?: string;
     /** One row per dimension, in the order to draw them clockwise from the top. */
     data?: readonly Row[];
     /** Text field that names each dimension. Names must be unique. */
@@ -37,8 +42,9 @@ export interface RadarChartCardProps<Row, Key extends NumericKey<Row>> {
     /**
      * How the legend lays out: value `tiles` (default), compact `inline` labels, `list` rows, tinted
      * `pills`, or `bars` that also draw each value against the largest.
+     * False removes the legend without changing the data or marks.
      */
-    legend?: CardLegend;
+    legend?: CardLegend | false;
     /** The mark beside each legend label: `square` (default), `dot`, or `line`. */
     legendSwatch?: ChartLegendSwatch;
     valueFormat?: Intl.NumberFormatOptions;
@@ -97,5 +103,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, 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, motion: motionMode, className, style, }: RadarChartCardProps<Row, Key>): ReactElement;
 export {};

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

@@ -6,7 +6,12 @@ import { RankedRow } from './rank';
 import { AnimatedNumberVariant } from '../motion/animated-number';
 export type RadialChartCardVariant = 'donut' | 'pie' | 'semi' | 'rings';
 export interface RadialChartCardProps<Row, Key extends NumericKey<Row>> {
-    title: string;
+    /** Optional visible title. Use aria-label to name an embedded chart. */
+    title?: string;
+    /** Show the header, including headline and period controls. Defaults to true. */
+    header?: boolean;
+    /** Accessible name, independent of the visible title. */
+    'aria-label'?: string;
     /** One row per category. Omit when `ranges` supplies the data. */
     data?: readonly Row[];
     /** Text field that names each slice. Names must be unique. */
@@ -28,8 +33,9 @@ export interface RadialChartCardProps<Row, Key extends NumericKey<Row>> {
      * `list` rows with value and share, value `tiles`, an `inline` key, tinted `pills`, or `bars`
      * that also draw each value against the largest. Defaults to tiles for rings, inline for semi,
      * and list otherwise.
+     * False removes the legend without changing the data or marks.
      */
-    legend?: CardLegend;
+    legend?: CardLegend | false;
     /** The mark beside each legend label: `square` (default), `dot`, or `line`. */
     legendSwatch?: ChartLegendSwatch;
     /** Resting headline. Defaults to the total of every slice. */
@@ -113,5 +119,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, 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, 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

@@ -5,7 +5,12 @@ import { CardRange } from './cartesian-card';
 import { NumericKey, TextKey } from './keys';
 import { AnimatedNumberVariant } from '../motion/animated-number';
 export interface SankeyChartCardProps<Row, Key extends NumericKey<Row>> {
-    title: string;
+    /** Optional visible title. Use aria-label to name an embedded chart. */
+    title?: string;
+    /** Show the header, including headline and period controls. Defaults to true. */
+    header?: boolean;
+    /** Accessible name, independent of the visible title. */
+    'aria-label'?: string;
     /** One row per flow between two steps. Omit when `ranges` supplies the data. */
     data?: readonly Row[];
     /** Text field naming the step a flow leaves. */
@@ -71,5 +76,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, 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, motion: motionMode, className, style, }: SankeyChartCardProps<Row, Key>): ReactElement;
 export {};

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

@@ -6,7 +6,12 @@ import { AnimatedNumberVariant } from '../motion/animated-number';
 /** How the resting headline sums up every plotted point's `y`. */
 export type ScatterAggregate = 'sum' | 'mean' | 'max';
 export interface ScatterChartCardProps<Row, Key extends NumericKey<Row>> {
-    title: string;
+    /** Optional visible title. Use aria-label to name an embedded chart. */
+    title?: string;
+    /** Show the header, including headline and period controls. Defaults to true. */
+    header?: boolean;
+    /** Accessible name, independent of the visible title. */
+    'aria-label'?: string;
     /** One row per point. Omit when `ranges` supplies the data. */
     data?: readonly Row[];
     /** Numeric field for the horizontal position. */
@@ -45,8 +50,9 @@ export interface ScatterChartCardProps<Row, Key extends NumericKey<Row>> {
     /**
      * How the legend lays out: value `tiles` (default), compact `inline` labels, `list` rows, tinted
      * `pills`, or `bars` that also draw each value against the largest.
+     * False removes the legend without changing the data or marks.
      */
-    legend?: CardLegend;
+    legend?: CardLegend | false;
     /** The mark beside each legend label: `square` (default), `dot`, or `line`. */
     legendSwatch?: ChartLegendSwatch;
     /** Number format for `y`: the headline, legend, and y axis. */
@@ -98,4 +104,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, 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, motion: motionMode, className, style, }: ScatterChartCardProps<Row, Key>): ReactElement;

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

@@ -6,7 +6,12 @@ import { NumericKey, TextKey } from './keys';
 import { AnimatedNumberVariant } from '../motion/animated-number';
 export type { SlopeOrder } from '../engine/slope';
 export interface SlopeChartCardProps<Row, Key extends NumericKey<Row>> {
-    title: string;
+    /** Optional visible title. Use aria-label to name an embedded chart. */
+    title?: string;
+    /** Show the header, including headline and period controls. Defaults to true. */
+    header?: boolean;
+    /** Accessible name, independent of the visible title. */
+    'aria-label'?: string;
     /** One row per category with both measurements. Omit when `ranges` supplies the data. */
     data?: readonly Row[];
     /** Text field that names each row. Names must be unique. */
@@ -76,4 +81,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, 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, motion: motionMode, className, style, }: SlopeChartCardProps<Row, Key>): ReactElement;

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

@@ -6,7 +6,12 @@ import { AnimatedNumberVariant } from '../motion/animated-number';
 export type StatCardChart = 'area' | 'line' | 'bars' | 'meter' | 'ring' | 'none';
 export interface StatCardProps<Row, Key extends NumericKey<Row>> {
     /** The metric's name, e.g. "Revenue". Also names the card for screen readers. */
-    title: string;
+    /** Optional visible title. Use aria-label to name an embedded chart. */
+    title?: string;
+    /** Show the header, including headline and period controls. Defaults to true. */
+    header?: boolean;
+    /** Accessible name, independent of the visible title. */
+    'aria-label'?: string;
     /** One row per observation. Optional when `headline` is supplied. */
     data?: readonly Row[];
     /** Numeric field to summarize and chart. */
@@ -71,4 +76,4 @@ export interface StatCardProps<Row, Key extends NumericKey<Row>> {
 }
 /** 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, 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, 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;