@lilt-ui/charts 0.12.2 → 0.13.1

package/README.md

@@ -15,7 +15,6 @@
   <a href="https://liltui.vercel.app"><strong>Documentation</strong></a> ·
   <a href="https://liltui.vercel.app/charts/area">Charts</a> ·
   <a href="https://liltui.vercel.app/finance/candlestick">Finance</a> ·
-  <a href="https://liltui.vercel.app/watch">Watch</a> ·
   <a href="https://liltui.vercel.app/llms.txt">llms.txt</a>
 </p>
 
@@ -77,7 +76,7 @@ export function VisitorsCard() {
 }
 ```
 
-That's the whole card: the headline, the change chip, value tiles, and hover all come from your rows. `x` and each series `key` are checked against your data, so a typo is a type error, not a blank chart.
+The headline, value tiles, and hover come from your rows. Supply `delta` when you want a change chip, for example `delta={0.082}` for +8.2%. `x` and each series `key` are checked against your data, so a typo is a type error, not a blank chart.
 
 ## Every card, finished
 
@@ -86,16 +85,21 @@ 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, 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        |
+| 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                                |
+| **Cool**             | 23 spatial families, from Skyline and Terrain to Chord loom, Sunburst terraces, and Voxel cloud |
+
+### Charts drawn in depth
+
+[Explore the Cool families](https://liltui.vercel.app/charts/skyline): Skyline, Block city, Hex city, Voxel waffle, Terrain, Ridgeline, Spiral year, Event helix, Chord loom, Arc bridges, Rank ribbons, Parallel ribbons, Contour islands, Sunburst terraces, Cluster constellation, Ternary prism, Wind rose, Marimekko blocks, Intersection towers, Horizon folds, Circle archipelago, Helix ribbons, and Voxel cloud. Each is its own card with its own data contract.
 
 ### Companion cards
 
@@ -103,6 +107,8 @@ That's the whole card: the headline, the change chip, value tiles, and hover all
 
 They take the same `depth`, loading, empty, and header props as every other card, plus `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).
 
+Existing family pages also cover `StreamgraphCard`, `DivergingBarCard`, `MirroredBarCard`, `NestedDonutCard`, `ComparativeFunnelCard`, `GoalPacingCard`, `MilestoneProgressCard`, `ViolinCard`, and `CorrelationMatrixCard`. Line supports indexed growth; Line and unstacked Area accept supplied forecast bands; Horizontal Bar supports lollipops; Scatter supports ordered trails; and Treemap supports group drill-down.
+
 ## Finance charts
 
 Candlesticks, indicators, and order books ship from their own entry point, so apps that never draw a candle never load one:
@@ -159,58 +165,14 @@ export function MarketCard() {
 
 Candles draw into a handful of paths however many there are, so years of daily history stay fast. `scale="log"` spaces long histories by ratio, and `live` follows new rows as they arrive. The indicator math (`sma`, `ema`, `rsi`, `macd`, `bollinger`, `drawdown`, `depthLevels`) is exported too, for your own layouts.
 
-## Watch
-
-Tell a chart what normal looks like, and it says when something isn't:
-
-```tsx
-<LineChartCard
-  title="Orders"
-  data={lastTwoDays}
-  x="hour"
-  series={[{ key: 'orders' }]}
-  normal={{
-    history: earlierWeeks, // learn from weeks you don't draw
-    learn: 'week', // same hour, same weekday
-    limits: { min: 10 }, // a line you set
-    when: (hour) => !hour.maintenance, // never judge downtime
-    breakdown: (hour) => hour.devices, // say which device caused it
-  }}
-/>
-```
-
-The card draws a calm band where the series should be, recolors unusual stretches, and says "Unusually low since Tue 2 PM". Hover an unusual reading and it says why: "98% of the drop is Mobile Safari". Every layer is off until you set it.
-
-Wrap cards in a board and the dashboard arranges itself around what needs attention:
-
-```tsx
-import { BoardItem, ChartBoard } from '@lilt-ui/charts/watch';
-
-<ChartBoard aria-label="Store health" toast>
-  <BoardItem id="orders" title="Orders">
-    <AreaChartCard
-      title="Orders"
-      data={rows}
-      x="hour"
-      series={[{ key: 'orders' }]}
-      normal={{ learn: 'week' }}
-    />
-  </BoardItem>
-  {/* …more cards */}
-</ChartBoard>;
-```
-
-Cards that need attention rise, what you've seen calms down, and what clears settles back. Nothing moves while you're reading, and a toast finds you when something breaks off screen.
-
 ## Built in, one prop away
 
-- **Linked hover.** Give cards the same `sync` name and they read the same moment together.
-- **Targets and forecasts.** `target` draws a goal line and counts the points that reach it. `forecast` marks projected rows and keeps them out of the headline.
-- **Pin and compare.** Click any mark to pin it; press anywhere off the marks, or Escape, to let go. Add `compare` and drag across a chart to see what changed, in the headline or, with `compare="badge"`, in the card's tab.
+- **Linked hover.** Cards with `sync`, including Area, Line, Bar, Combo, and Stat, read the same moment together. Stat also needs `x`.
+- **Targets and forecasts.** On Area, Line, Bar, and Combo cards, `target` draws a goal line and counts the points that reach it. `forecast` marks supplied projected rows and keeps them out of the headline. Lilt does not estimate forecasts.
+- **Pin and compare.** On cards with inspection, click a mark to pin it; press off the marks, or Escape, to let go. Cards with `compare` let you drag across the plot to see what changed, in the headline or, with `compare="badge"`, in the card's tab. Check the family's props for availability.
 - **Honest data.** `null` is a gap, never a zero, and missing values say so.
 - **Loading and empty.** `loading` shows a skeleton that `"shimmer"`s, `"draw"`s, or `"breathe"`s in the chart's own shape, then hands over to the data. A period with no rows shows a still empty state, or your own with `empty`, and the headline reads a dash, never zero.
 - **Long series.** Line and area cards draw tens of thousands of points from four per pixel column; hover, tiles, and exports still read every row.
-- **Watch.** `normal` flags what's unusual and says why; a `ChartBoard` raises what needs attention.
 - **Calm by default.** Keyboard navigation, screen reader labels, and motion that respects reduced-motion settings.
 
 ## Fits your design system

package/dist/cards/arc-bridges-card.d.ts

@@ -0,0 +1,17 @@
+import { NumericKey, TextKey } from './keys';
+import { ObservationsCardProps, ObservationScene } from './observations-card';
+export interface ArcBridgesCardProps<Row, Key extends NumericKey<Row>> extends ObservationsCardProps<Row> {
+    source: TextKey<Row>;
+    target: TextKey<Row>;
+    value: Key;
+    /** Arch height as a fraction of the available plot height, 0.3–1. Default 0.85. */
+    rise?: number;
+    /** Maximum ribbon width in pixels, 4–28. Default 18. */
+    thickness?: number;
+}
+export declare function arcBridgesLayout<Row>(data: readonly Row[], source: string, target: string, value: string, width: number, height: number, options?: {
+    rise?: number;
+    thickness?: number;
+    color?: string;
+}): ObservationScene<Row>;
+export declare function ArcBridgesCard<Row, const Key extends NumericKey<Row>>({ source, target, value, rise, thickness, color, height, ...props }: ArcBridgesCardProps<Row, Key>): import("react/jsx-runtime").JSX.Element;

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

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

package/dist/cards/block-city-card.d.ts

@@ -0,0 +1,21 @@
+import { NumericKey, TextKey } from './keys';
+import { ObservationsCardProps, ObservationScene } from './observations-card';
+import { PrismGridOptions } from './prism-grid';
+export interface BlockCityCardProps<Row, Key extends NumericKey<Row>> extends Omit<ObservationsCardProps<Row>, 'legend' | 'legendSwatch'>, PrismGridOptions {
+    /** Columns, running away to the right, in first-seen order. */
+    x: TextKey<Row>;
+    /** Rows, coming toward the viewer, in first-seen order. */
+    y: TextKey<Row>;
+    value: Key;
+    /** Fixed value domain that must contain every value. Defaults to zero through the largest. */
+    domain?: readonly [number, number];
+}
+/**
+ * Any two categories as a city block: one prism per pair, whose height and color both carry the
+ * value. Pairs without a row stay as a low slab so a gap never reads as zero.
+ */
+export declare function blockCityLayout<Row>(data: readonly Row[], x: string, y: string, value: string, width: number, height: number, options?: PrismGridOptions & {
+    domain?: readonly [number, number];
+    color?: string;
+}): ObservationScene<Row>;
+export declare function BlockCityCard<Row, const Key extends NumericKey<Row>>({ x, y, value, domain, rise, gap, color, height, ...props }: BlockCityCardProps<Row, Key>): import("react/jsx-runtime").JSX.Element;

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

@@ -14,5 +14,35 @@ export interface CalendarHeatmapCardProps<Row, Key extends NumericKey<Row>> exte
     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 type CalendarOptions<Row> = Pick<CalendarHeatmapCardProps<Row, NumericKey<Row>>, 'from' | 'to' | 'today' | 'weekStartsOn' | 'domain' | 'color' | 'locale'>;
+export interface CalendarCell<Row> {
+    day: number;
+    column: number;
+    row: number;
+    datum: Row | null;
+    reading: number | null;
+    /** Position of the reading in the domain, 0 to 1. */
+    share: number;
+    color: string;
+    future: boolean;
+}
+/** Validates the rows and places every day of the range in a week column and weekday row. */
+export declare function calendarCells<Row>(data: readonly Row[], date: string, value: string, options: CalendarOptions<Row>): {
+    error?: string;
+    cells: CalendarCell<Row>[];
+    weeks: number;
+    weekStart: 0 | 1;
+};
+export declare function cellMark<Row>(cell: CalendarCell<Row>): {
+    id: string;
+    label: string;
+    datum: Row | null;
+    value: number | null;
+    color: string;
+    missing: boolean;
+    future: boolean;
+    detail: string | undefined;
+};
+export declare const monthFormatter: (locale: string | undefined) => Intl.DateTimeFormat;
+export declare function calendarLayout<Row>(data: readonly Row[], date: string, value: string, width: number, height: number, options?: CalendarOptions<Row>): 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

@@ -4,9 +4,6 @@ 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';
 export interface CardSeries<Key extends string> {
     /** A numeric field of each row. */
     key: Key;
@@ -27,6 +24,12 @@ export type CardTarget = number | {
 };
 /** Rows from `from` onward are projections rather than measurements. */
 export interface CardForecast<Row> {
+    /** Supplied uncertainty envelopes, ordered widest to narrowest. Values are never estimated. */
+    bands?: readonly {
+        lower: NumericKey<Row>;
+        upper: NumericKey<Row>;
+        label: string;
+    }[];
     /** The x value of the first projected row: a label, number, or Date. */
     from: string | number | Date;
     /** Fields holding the low and high end of the projection, drawn as a band around it. */
@@ -35,24 +38,6 @@ export interface CardForecast<Row> {
     /** Names the projected region and the hover caption. Defaults to "Forecast". */
     label?: string;
 }
-/**
- * What normal looks like for one series of a line or unstacked area card. Every layer is off
- * unless set; see `NormalSpec`. Projected rows are never judged.
- */
-export interface CardNormal<Row, Key extends string = string> extends NormalSpec<Row> {
-    /** The watched series. Defaults to the headline series, then the first solid series. */
-    series?: Key;
-    /**
-     * Earlier rows to learn from without drawing them, such as the weeks before the day on screen.
-     * They come before `data`, in the same shape.
-     */
-    history?: readonly Row[];
-    /**
-     * Split a reading into the segments that add up to it, such as orders by device, so an unusual
-     * reading can say which segment caused it: "91% of the drop is Mobile Safari".
-     */
-    breakdown?: NormalBreakdown<Row>;
-}
 export interface CardRange<Row> {
     id: string;
     label: string;
@@ -131,7 +116,7 @@ export interface CartesianCardProps<Row, Key extends NumericKey<Row>> {
     /**
      * Draw a long line or area from each pixel column's first, last, lowest and highest
      * observation, so tens of thousands of points stay fast to hover. The ink is the same, and the
-     * headline, tiles, hover, Watch and exports still read every row. Defaults to true.
+     * headline, tiles, hover and exports still read every row. Defaults to true.
      */
     decimate?: boolean;
     /** Card treatment: `elevated` (default), `outline`, or `ghost` inside your own card. */
@@ -244,6 +229,7 @@ export type CardShape = {
     curve: ChartCurve;
     points: boolean;
     zero: boolean;
+    indexed?: boolean;
 } | {
     kind: 'bar';
     stack: CardStack;
@@ -309,7 +295,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, empty, 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, }: Omit<CartesianCardProps<Row, Key>, 'series'> & {
     series: readonly CoreSeries<Key>[];
     shape: CardShape;
     /** Linked panes under the plot, such as volume or indicators. */
@@ -320,10 +306,6 @@ export declare function CartesianCard<Row, Key extends NumericKey<Row>>({ shape,
     heading?: ReactNode;
     /** Text beside the delta at rest, such as an absolute change, from the active data. */
     restCaption?: (data: readonly Row[]) => ReactNode;
-    /** Watch one series against its normal. Line and unstacked area cards only. */
-    normal?: CardNormal<Row, NoInfer<Key>>;
-    /** Called when the watched series' status changes. */
-    onNormalChange?: (report: NormalReport | null) => void;
 }): ReactElement;
 /** The plot position where projections begin: a label's row, or the date or number itself. */
 export declare function forecastPosition<Row>(data: readonly Row[], x: string, resolved: ResolvedX<Row>, from: string | number): number | null;

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

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

package/dist/cards/chord-loom-card.d.ts

@@ -0,0 +1,17 @@
+import { NumericKey, TextKey } from './keys';
+import { ObservationsCardProps, ObservationScene } from './observations-card';
+export interface ChordLoomCardProps<Row, Key extends NumericKey<Row>> extends ObservationsCardProps<Row> {
+    source: TextKey<Row>;
+    target: TextKey<Row>;
+    value: Key;
+    /** Vertical proportion of the circular frame, 0.4–1. Default 0.68. */
+    tilt?: number;
+    /** Gap between node sectors in radians, 0–0.16. Default 0.06. */
+    gap?: number;
+}
+export declare function chordLoomLayout<Row>(data: readonly Row[], source: string, target: string, value: string, width: number, height: number, options?: {
+    tilt?: number;
+    gap?: number;
+    color?: string;
+}): ObservationScene<Row>;
+export declare function ChordLoomCard<Row, const Key extends NumericKey<Row>>({ source, target, value, tilt, gap, color, height, ...props }: ChordLoomCardProps<Row, Key>): import("react/jsx-runtime").JSX.Element;

package/dist/cards/circle-archipelago-card.d.ts

@@ -0,0 +1,9 @@
+import { NumericKey, TextKey } from './keys';
+import { ObservationsCardProps } from './observations-card';
+export { circleArchipelagoLayout } from './hierarchy-layouts';
+export interface CircleArchipelagoCardProps<Row, Key extends NumericKey<Row>> extends ObservationsCardProps<Row> {
+    path: TextKey<Row>;
+    value: Key;
+    padding?: number;
+}
+export declare function CircleArchipelagoCard<Row, const Key extends NumericKey<Row>>({ path, value, padding, color, height, depth, ...props }: CircleArchipelagoCardProps<Row, Key>): import("react/jsx-runtime").JSX.Element;

package/dist/cards/cluster-constellation-card.d.ts

@@ -0,0 +1,16 @@
+import { NumericKey, TextKey, KeysOfType } from './keys';
+import { ObservationsCardProps } from './observations-card';
+export { clusterConstellationLayout } from './spatial-point-layouts';
+export interface ClusterConstellationCardProps<Row, Key extends NumericKey<Row>> extends ObservationsCardProps<Row> {
+    label: TextKey<Row>;
+    x: NumericKey<Row>;
+    y: NumericKey<Row>;
+    z: NumericKey<Row>;
+    value: Key;
+    connections: KeysOfType<Row, readonly string[]>;
+    group?: TextKey<Row>;
+    yaw?: number;
+    elevation?: number;
+    size?: number;
+}
+export declare function ClusterConstellationCard<Row, const Key extends NumericKey<Row>>({ label, x, y, z, value, connections, group, yaw, elevation, size, color, height, depth, ...props }: ClusterConstellationCardProps<Row, Key>): import("react/jsx-runtime").JSX.Element;

package/dist/cards/comparison-forms.d.ts

@@ -0,0 +1,30 @@
+import { NumericKey, TextKey } from './keys';
+import { CardSeries } from './cartesian-card';
+import { ObservationsCardProps, ObservationScene } from './observations-card';
+export interface DivergingBarCardProps<Row, Key extends NumericKey<Row>> extends ObservationsCardProps<Row> {
+    category: TextKey<Row>;
+    series: readonly (CardSeries<Key> & {
+        side: 'negative' | 'neutral' | 'positive';
+    })[];
+    /** Normalize each complete response to 100%. Neutral responses straddle zero. */
+    percent?: boolean;
+}
+export interface MirroredBarCardProps<Row, Key extends NumericKey<Row>> extends ObservationsCardProps<Row> {
+    category: TextKey<Row>;
+    left: Key;
+    right: Key;
+    leftLabel?: string;
+    rightLabel?: string;
+}
+export interface ComparativeFunnelCardProps<Row, Key extends NumericKey<Row>> extends ObservationsCardProps<Row> {
+    stage: TextKey<Row>;
+    cohorts: readonly [CardSeries<Key>, CardSeries<Key>];
+}
+export declare function divergingLayout<Row>(data: readonly Row[], category: string, series: readonly (CardSeries<string> & {
+    side: 'negative' | 'neutral' | 'positive';
+})[], percent: boolean, width: number, height: number): ObservationScene<Row>;
+export declare function mirroredLayout<Row>(data: readonly Row[], category: string, keys: readonly [string, string], labels: readonly [string, string], width: number, height: number): ObservationScene<Row>;
+export declare function comparativeFunnelLayout<Row>(data: readonly Row[], stage: string, cohorts: readonly CardSeries<string>[], width: number, height: number): ObservationScene<Row>;
+export declare function DivergingBarCard<Row, const Key extends NumericKey<Row>>({ category, series, percent, ...props }: DivergingBarCardProps<Row, Key>): import("react/jsx-runtime").JSX.Element;
+export declare function MirroredBarCard<Row, const Key extends NumericKey<Row>>({ category, left, right, leftLabel, rightLabel, ...props }: MirroredBarCardProps<Row, Key>): import("react/jsx-runtime").JSX.Element;
+export declare function ComparativeFunnelCard<Row, const Key extends NumericKey<Row>>({ stage, cohorts, ...props }: ComparativeFunnelCardProps<Row, Key>): import("react/jsx-runtime").JSX.Element;

package/dist/cards/composition-forms.d.ts

@@ -0,0 +1,10 @@
+import { NumericKey, TextKey } from './keys';
+import { ObservationsCardProps, ObservationScene } from './observations-card';
+export interface NestedDonutCardProps<Row, Key extends NumericKey<Row>> extends ObservationsCardProps<Row> {
+    /** Unique leaf paths separated by /. Parent totals are calculated from leaves. */
+    path: TextKey<Row>;
+    value: Key;
+    hole?: number;
+}
+export declare function nestedDonutLayout<Row>(data: readonly Row[], path: string, value: string, hole: number, width: number, height: number): ObservationScene<Row>;
+export declare function NestedDonutCard<Row, const Key extends NumericKey<Row>>({ path, value, hole, ...props }: NestedDonutCardProps<Row, Key>): import("react/jsx-runtime").JSX.Element;

package/dist/cards/contour-islands-card.d.ts

@@ -0,0 +1,25 @@
+import { NumericKey, TextKey } from './keys';
+import { ObservationsCardProps, ObservationScene } from './observations-card';
+export interface ContourIslandsCardProps<Row, Key extends NumericKey<Row>> extends Omit<ObservationsCardProps<Row>, 'legend' | 'legendSwatch'> {
+    x: Key;
+    y: Key;
+    label: TextKey<Row>;
+    /** Optional nonnegative density weight. Without it each observation has weight one. */
+    weight?: Key;
+    /** Kernel bandwidth as a fraction of each axis span, 0.04–0.25. Default 0.1. */
+    bandwidth?: number;
+    /** Number of contour terraces, 3–9. Default 6. */
+    levels?: number;
+}
+export declare const placeholderCloud: {
+    name: string;
+    x: number;
+    y: number;
+}[];
+export declare function contourIslandsLayout<Row>(data: readonly Row[], xKey: string, yKey: string, label: string, width: number, height: number, options?: {
+    weight?: string;
+    bandwidth?: number;
+    levels?: number;
+    color?: string;
+}): ObservationScene<Row>;
+export declare function ContourIslandsCard<Row, const Key extends NumericKey<Row>>({ x, y, label, weight, bandwidth, levels, color, height, ...props }: ContourIslandsCardProps<Row, Key>): import("react/jsx-runtime").JSX.Element;

package/dist/cards/density-contours.d.ts

@@ -0,0 +1,3 @@
+import { Point } from './sculpted-geometry';
+/** Marching squares on a padded density grid. Segments join into closed contour rings. */
+export declare function densityContours(grid: readonly (readonly number[])[], threshold: number): Point[][];

package/dist/cards/distribution-forms.d.ts

@@ -0,0 +1,37 @@
+import { NumericKey, TextKey } from './keys';
+import { CardSeries } from './cartesian-card';
+import { ObservationsCardProps, ObservationScene } from './observations-card';
+export interface ViolinCardProps<Row, Key extends NumericKey<Row>> extends ObservationsCardProps<Row> {
+    category: TextKey<Row>;
+    value: Key;
+    label?: TextKey<Row>;
+    points?: boolean;
+    /** Kernel bandwidth in measurement units; defaults to a data-derived bandwidth per group. */
+    bandwidth?: number;
+    scale?: 'width' | 'density';
+}
+export interface CorrelationMatrixCardProps<Row, Key extends NumericKey<Row>> extends ObservationsCardProps<Row> {
+    metrics: readonly CardSeries<Key>[];
+    /** Minimum complete pairs per coefficient; defaults to 3. */
+    minPairs?: number;
+}
+export declare function quantileSorted(values: readonly number[], p: number): number | null;
+export declare function violinDensity(values: readonly number[], bandwidth?: number): {
+    points: {
+        x: number;
+        density: number;
+    }[];
+    median: number;
+    low: number;
+    high: number;
+    bandwidth: number;
+} | null;
+export declare function violinLayout<Row>(data: readonly Row[], category: string, value: string, label: string | undefined, points: boolean, bandwidth: number | undefined, scale: 'width' | 'density', width: number, height: number): ObservationScene<Row>;
+/** Pearson correlation from complete pairs, scaled before centering to avoid overflow. */
+export declare function pairedCorrelation(pairs: readonly (readonly [number | null, number | null])[], minPairs?: number): {
+    value: number | null;
+    count: number;
+};
+export declare function correlationLayout<Row>(data: readonly Row[], metrics: readonly CardSeries<string>[], minPairs: number, width: number, height: number): ObservationScene<Row>;
+export declare function ViolinCard<Row, const Key extends NumericKey<Row>>({ category, value, label, points, bandwidth, scale, aggregate, ...props }: ViolinCardProps<Row, Key>): import("react/jsx-runtime").JSX.Element;
+export declare function CorrelationMatrixCard<Row, const Key extends NumericKey<Row>>({ metrics, minPairs, valueFormat, legend, ...props }: CorrelationMatrixCardProps<Row, Key>): import("react/jsx-runtime").JSX.Element;

package/dist/cards/event-helix-card.d.ts

@@ -0,0 +1,26 @@
+import { NumericKey, TextKey, XKey } from './keys';
+import { ObservationsCardProps, ObservationScene } from './observations-card';
+export interface EventHelixCardProps<Row, Key extends NumericKey<Row>> extends ObservationsCardProps<Row> {
+    /** Unique event label, including for simultaneous events. */
+    label: TextKey<Row>;
+    date: XKey<Row>;
+    value: Key;
+    group?: TextKey<Row>;
+    /** One revolution per UTC day or week. Default day. */
+    cycle?: 'day' | 'week';
+    /** Vertical spacing between turns, 26–100 pixels. Default 54. */
+    pitch?: number;
+}
+export declare const placeholderEvents: {
+    event: string;
+    date: string;
+    value: number;
+    group: string;
+}[];
+export declare function eventHelixLayout<Row>(data: readonly Row[], label: string, date: string, value: string, width: number, height: number, options?: {
+    group?: string;
+    cycle?: 'day' | 'week';
+    pitch?: number;
+    color?: string;
+}): ObservationScene<Row>;
+export declare function EventHelixCard<Row, const Key extends NumericKey<Row>>({ label, date, value, group, cycle, pitch, color, height, ...props }: EventHelixCardProps<Row, Key>): import("react/jsx-runtime").JSX.Element;

package/dist/cards/helix-ribbons-card.d.ts

@@ -0,0 +1,14 @@
+import { NumericKey, TextKey } from './keys';
+import { ObservationsCardProps } from './observations-card';
+export { helixRibbonsLayout } from './spatial-series-layouts';
+export interface HelixRibbonsCardProps<Row, Key extends NumericKey<Row>> extends ObservationsCardProps<Row> {
+    series: TextKey<Row>;
+    cycle: NumericKey<Row>;
+    phase: NumericKey<Row>;
+    value: Key;
+    yaw?: number;
+    elevation?: number;
+    thickness?: number;
+    maxGap?: number;
+}
+export declare function HelixRibbonsCard<Row, const Key extends NumericKey<Row>>({ series, cycle, phase, value, yaw, elevation, thickness, maxGap, color, height, depth, ...props }: HelixRibbonsCardProps<Row, Key>): import("react/jsx-runtime").JSX.Element;

package/dist/cards/hex-city-card.d.ts

@@ -0,0 +1,25 @@
+import { NumericKey, TextKey } from './keys';
+import { ObservationsCardProps, ObservationScene } from './observations-card';
+export interface HexCityCardProps<Row, Key extends NumericKey<Row>> extends Omit<ObservationsCardProps<Row>, 'legendSwatch'> {
+    /** Unique name for each hexagon. */
+    label: TextKey<Row>;
+    value: Key;
+    /** Colors hexagons by a category and adds its legend. */
+    group?: TextKey<Row>;
+    /** `rank` (default) puts the largest value in the middle and works outward; `order` keeps rows in order. */
+    arrange?: 'rank' | 'order';
+    /** How many hexagon widths the largest value rises, default 2. */
+    rise?: number;
+    /** Space between hexagons as a share of their size, 0 to 0.5, default 0.12. */
+    gap?: number;
+    /** Fixed value domain that must contain every value. Defaults to zero through the largest. */
+    domain?: readonly [number, number];
+}
+/**
+ * A honeycomb of hexagonal prisms: one per row, standing as tall as its value. By default the
+ * largest value stands in the middle and the city falls away toward its edges.
+ */
+export declare function hexCityLayout<Row>(data: readonly Row[], label: string, value: string, width: number, height: number, options?: Pick<HexCityCardProps<Row, NumericKey<Row>>, 'arrange' | 'rise' | 'gap' | 'domain' | 'color'> & {
+    group?: string;
+}): ObservationScene<Row>;
+export declare function HexCityCard<Row, const Key extends NumericKey<Row>>({ label, value, group, arrange, rise, gap, domain, color, legend, height, ...props }: HexCityCardProps<Row, Key>): import("react/jsx-runtime").JSX.Element;

package/dist/cards/hierarchy-layouts.d.ts

@@ -0,0 +1,21 @@
+import { Branch } from './spatial-hierarchy';
+import { Scene } from './spatial-geometry';
+export declare function sunburstTerracesLayout<Row>(data: readonly Row[], path: string, value: string, width: number, height: number, options?: {
+    tilt?: number;
+    rise?: number;
+    color?: string;
+}): Scene<Row>;
+interface Packed<Row> {
+    node: Branch<Row>;
+    x: number;
+    y: number;
+    r: number;
+    children: Packed<Row>[];
+}
+/** Deterministic tangent candidates. Every leaf keeps the same area/value scale. */
+export declare function packHierarchy<Row>(node: Branch<Row>, padding: number): Packed<Row>;
+export declare function circleArchipelagoLayout<Row>(data: readonly Row[], path: string, value: string, width: number, height: number, options?: {
+    padding?: number;
+    color?: string;
+}): Scene<Row>;
+export {};

package/dist/cards/horizon-folds-card.d.ts

@@ -0,0 +1,10 @@
+import { NumericKey, TextKey } from './keys';
+import { ObservationsCardProps } from './observations-card';
+export { horizonFoldsLayout } from './spatial-series-layouts';
+export interface HorizonFoldsCardProps<Row, Key extends NumericKey<Row>> extends ObservationsCardProps<Row> {
+    series: TextKey<Row>;
+    time: NumericKey<Row>;
+    value: Key;
+    bands?: number;
+}
+export declare function HorizonFoldsCard<Row, const Key extends NumericKey<Row>>({ series, time, value, bands, color, height, depth, ...props }: HorizonFoldsCardProps<Row, Key>): import("react/jsx-runtime").JSX.Element;

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

@@ -42,7 +42,7 @@ export interface HorizontalBarChartCardProps<Row, Key extends NumericKey<Row>> {
      * `isometric` draws a solid block under the label whose front ends at the value, with a lit
      * roof and a shaded end receding behind it.
      */
-    barStyle?: 'inline' | 'track' | 'isometric';
+    barStyle?: 'inline' | 'track' | 'isometric' | 'lollipop';
     /** Shorthand for depth across every card family: here it makes `barStyle` default to `isometric`. */
     depth?: boolean;
     valueFormat?: Intl.NumberFormatOptions;

package/dist/cards/intersection-towers-card.d.ts

@@ -0,0 +1,9 @@
+import { NumericKey, KeysOfType } from './keys';
+import { ObservationsCardProps } from './observations-card';
+export { intersectionTowersLayout } from './spatial-composition-layouts';
+export interface IntersectionTowersCardProps<Row, Key extends NumericKey<Row>> extends ObservationsCardProps<Row> {
+    members: KeysOfType<Row, readonly string[]>;
+    value: Key;
+    sort?: 'value' | 'input';
+}
+export declare function IntersectionTowersCard<Row, const Key extends NumericKey<Row>>({ members, value, sort, color, height, depth, ...props }: IntersectionTowersCardProps<Row, Key>): import("react/jsx-runtime").JSX.Element;