@lilt-ui/charts 0.1.0

package/dist/interaction/adaptive-readout.d.ts

@@ -0,0 +1,16 @@
+import { ReactElement, ReactNode } from 'react';
+import { ChartSnapshot } from '../chart-context';
+import { ChartSelection, ChartSeries, ChartTooltipContext } from '../types';
+export interface AdaptiveReadoutProps<T> {
+    snapshot: ChartSnapshot<T>;
+    series: readonly ChartSeries<T>[];
+    selection: ChartSelection<T> | null;
+    sharedX?: number;
+    peer: boolean;
+    pinned: boolean;
+    onRelease: () => void;
+    onCompareFromHere?: () => void;
+    renderContent?: (context: ChartTooltipContext) => ReactNode;
+    reducedMotion: boolean;
+}
+export declare function AdaptiveReadout<T>({ snapshot, series, selection, sharedX, peer, pinned, onRelease, onCompareFromHere, renderContent, reducedMotion, }: AdaptiveReadoutProps<T>): ReactElement;

package/dist/interaction/axis-cursor.d.ts

@@ -0,0 +1,30 @@
+import { MotionValue } from 'motion/react';
+import { ChartAxisStyle, ChartHoverStyle } from '../types';
+/** Visual center of x tick labels below the plot; pills center on the same line. */
+export declare const X_LABEL_CENTER = 22;
+/** The inspection pill positions, shared so axis labels can react to the approaching pill. */
+export interface AxisCursor {
+    /** Center of the x pill, which stays inside the plot near its edges. */
+    x: MotionValue<number>;
+    /** The inspected position itself, for marks that must line up with the crosshair. */
+    pointerX: MotionValue<number>;
+    y: MotionValue<number>;
+    /** 1 while this chart owns an inspection, else 0. */
+    active: MotionValue<number>;
+    style: ChartAxisStyle;
+    pill: ChartHoverStyle;
+    /** Padding between the plot edges and axis labels or pills, for plots that run edge to edge. */
+    inset: number;
+    /** Continue lines and areas, faded, from the first and last observations to the plot edges. */
+    runoff: boolean;
+    /** How far edge labels may hang past the plot edges to stay centered on their ticks. */
+    overhang: number;
+    /** Where the value pill sits: on the y axis, or above the hovered mark. */
+    pillPosition: 'axis' | 'mark';
+}
+export declare const AxisCursorContext: import('react').Context<AxisCursor>;
+export declare function useAxisCursor(): AxisCursor;
+/** 1 when far from the pill, easing to 0 when the pill is on top of the label. */
+export declare function proximityOpacity(distance: number, reach: number, active: number): number;
+/** Pills sit on the y axis when it has labels, and above the hovered mark when it does not. */
+export declare function resolvePillPosition(position: 'auto' | 'axis' | 'mark', style: ChartAxisStyle): 'axis' | 'mark';

package/dist/interaction/brush-gesture.d.ts

@@ -0,0 +1,15 @@
+export type BrushDrag = {
+    kind: 'start' | 'end' | 'move' | 'create';
+    anchor: number;
+    start: number;
+    end: number;
+    pointerId: number;
+};
+/** A cancelled drag cannot publish a range when pointer-up arrives later. */
+export declare function createBrushGesture(): {
+    readonly active: BrushDrag | null;
+    start(drag: BrushDrag): void;
+    move(index: number, last: number): readonly [number, number] | null;
+    finish(index: number, last: number): readonly [number, number] | null;
+    cancel(): void;
+};

package/dist/interaction/brush-view.d.ts

@@ -0,0 +1,12 @@
+import { ReactElement } from 'react';
+import { ChartSnapshot } from '../chart-context';
+import { ChartRange } from '../types';
+interface BrushViewProps<T> {
+    snapshot: ChartSnapshot<T>;
+    range: ChartRange | null;
+    seriesId: string;
+    reducedMotion: boolean;
+    onFocus: (range: ChartRange | null) => void;
+}
+export declare function BrushView<T>({ snapshot, range, seriesId, reducedMotion, onFocus, }: BrushViewProps<T>): ReactElement;
+export {};

package/dist/interaction/chart-controller.d.ts

@@ -0,0 +1,6 @@
+import { ChartController } from '../types';
+/**
+ * Creates a tiny framework-agnostic interaction store. Reuse one instance to link charts,
+ * or pass it to compact and expanded chart mounts to preserve the user's place.
+ */
+export declare function createChartController(): ChartController;

package/dist/interaction/chart-sync.d.ts

@@ -0,0 +1,35 @@
+import { ChartController } from '../types';
+import { ResolvedX, XKind } from '../cards/keys';
+/** The hovered or pinned position a sync group shares, in the x field's own terms. */
+export interface ChartSyncPosition {
+    /** The hovered x value: the Date, number, or label of the row under the pointer. */
+    readonly value: Date | number | string;
+    readonly kind: XKind;
+    readonly pinned: boolean;
+}
+interface SyncState {
+    readonly key: number | string;
+    readonly kind: XKind;
+    readonly pinned: boolean;
+    /** The card whose pointer or keyboard set this position. */
+    readonly source: string;
+}
+/** Inspections this bridge writes into a card's controller carry this owner. */
+export declare const SYNC_OWNER = "sync";
+/**
+ * Read a sync group's shared position from any component, e.g. to show the hovered date in your
+ * own dashboard header. Returns null while nothing in the group is hovered or pinned.
+ */
+export declare function useChartSync(name: string | undefined): ChartSyncPosition | null;
+/**
+ * Where a shared position lands in one card: labels match exactly, and dates or numbers snap to
+ * the nearest row within half a step, so a weekly card follows a daily one. Returns null when the
+ * card has no row there.
+ */
+export declare function syncTarget(state: Pick<SyncState, 'key' | 'kind'>, kind: XKind, labels: readonly string[], positions: readonly number[]): number | null;
+/**
+ * Link a card's hover and pin to every other card in the same named group. The card's own
+ * controller stays the source of truth; this bridge only copies positions between controllers.
+ */
+export declare function useCardSync<Row>(name: string | undefined, controller: ChartController, data: readonly Row[], x: string, resolved: ResolvedX<Row>): void;
+export {};

package/dist/interaction/comparison-answer.d.ts

@@ -0,0 +1,11 @@
+import { ChartComparison, ChartComparisonSeries, ChartPercentagePolicy, ChartRange, ChartSeries } from '../types';
+import { NormalizedData } from '../engine/normalize';
+export interface ComparisonAnswer {
+    values: string;
+    change: string;
+    percentage: string | null;
+    unavailable: string | null;
+}
+/** Every visible descriptor keeps its own units, gaps and baseline policy. */
+export declare function comparisonRows<T>(data: NormalizedData<T>, range: ChartRange, series: readonly ChartSeries<T>[], formatValue: (value: number) => string, percentage?: ChartPercentagePolicy): readonly ChartComparisonSeries[];
+export declare function comparisonAnswer(comparison: ChartComparison, formatValue: (value: number) => string): ComparisonAnswer;

package/dist/interaction/comparison-layer.d.ts

@@ -0,0 +1,19 @@
+import { KeyboardEvent, PointerEvent, ReactElement } from 'react';
+import { ChartComparison, ChartComparisonSeries } from '../types';
+import { ChartSnapshot } from '../chart-context';
+export type ComparisonEndpoint = 'start' | 'end';
+interface ComparisonLayerProps<T> {
+    snapshot: ChartSnapshot<T>;
+    comparison: ChartComparison;
+    rows: readonly ChartComparisonSeries[];
+    reducedMotion: boolean;
+    preview?: boolean;
+    onEndpointPointerDown?: (handle: ComparisonEndpoint, event: PointerEvent<HTMLDivElement>) => void;
+    onEndpointPointerMove?: (handle: ComparisonEndpoint, event: PointerEvent<HTMLDivElement>) => void;
+    onEndpointPointerUp?: (handle: ComparisonEndpoint, event: PointerEvent<HTMLDivElement>) => void;
+    onEndpointCancel?: () => void;
+    onEndpointCommit?: () => void;
+    onEndpointKeyDown?: (handle: ComparisonEndpoint, event: KeyboardEvent<HTMLDivElement>) => void;
+}
+export declare function ComparisonLayer<T>({ snapshot, comparison, rows, reducedMotion, onEndpointPointerDown, onEndpointPointerMove, onEndpointPointerUp, onEndpointCancel, onEndpointCommit, onEndpointKeyDown, preview, }: ComparisonLayerProps<T>): ReactElement;
+export {};

package/dist/interaction/comparison-tooltip.d.ts

@@ -0,0 +1,14 @@
+import { ReactNode } from 'react';
+import { ChartComparisonContext } from '../types';
+/** Placement only. Comparison content is explicitly supplied by the consumer. */
+export declare function ComparisonTooltip({ comparison, renderContent, startX, endX, top, width, height, className, ariaLabel, }: {
+    comparison: ChartComparisonContext;
+    renderContent: (context: ChartComparisonContext) => ReactNode;
+    startX: number;
+    endX: number;
+    top: number;
+    width: number;
+    height: number;
+    className?: string;
+    ariaLabel?: string;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/interaction/focus-overview.d.ts

@@ -0,0 +1,10 @@
+import { ReactElement } from 'react';
+import { ChartRange } from '../types';
+import { ChartSnapshot } from '../chart-context';
+interface FocusOverviewProps<T> {
+    snapshot: ChartSnapshot<T>;
+    range: ChartRange;
+    series: string;
+}
+export declare function FocusOverview<T>({ snapshot, range, series }: FocusOverviewProps<T>): ReactElement;
+export {};

package/dist/interaction/inspection-layer.d.ts

@@ -0,0 +1,29 @@
+import { ReactElement, ReactNode } from 'react';
+import { ChartSelection, ChartSeries, ChartTooltipContext } from '../types';
+import { ChartSnapshot } from '../chart-context';
+interface InspectionLayerProps<T> {
+    snapshot: ChartSnapshot<T>;
+    selection: ChartSelection<T> | null;
+    series: readonly ChartSeries<T>[];
+    seriesColors?: Readonly<Record<string, string>>;
+    paintId?: (seriesId: string, treatment: 'fade' | 'hatch' | 'dots') => string;
+    renderContent?: (context: ChartTooltipContext) => ReactNode;
+    inspectionSeries?: string;
+    /** Stacked pills: the stack `total`, the active series' own value, or its stacked edge. */
+    stackedPill?: 'total' | 'series' | 'stack';
+    pinIcon?: ReactNode;
+    tooltipClassName?: string;
+    tooltipAriaLabel?: string;
+    width: number;
+    height: number;
+    reducedMotion: boolean;
+    highlightMaskId: string;
+    crossGradientId: string;
+    compactPlot?: boolean;
+    inlineOnly?: boolean;
+    hideAxisBadges?: boolean;
+    peer?: boolean;
+    onCompareFromHere?: () => void;
+}
+export declare function InspectionLayer<T>({ snapshot, selection, series, seriesColors, paintId, renderContent, inspectionSeries, stackedPill, pinIcon, tooltipClassName, tooltipAriaLabel, width, height, reducedMotion, highlightMaskId, crossGradientId, compactPlot, inlineOnly, hideAxisBadges, peer, onCompareFromHere, }: InspectionLayerProps<T>): ReactElement;
+export {};

package/dist/interaction/legend.d.ts

@@ -0,0 +1,50 @@
+import { ReactElement, ReactNode } from 'react';
+import { ChartComparisonSeries, ChartLegendValue, LegendProps } from '../types';
+import { CartesianChartModel } from '../model/cartesian-model';
+type ModelLegendEntry<Id extends string> = ChartLegendValue & {
+    id: Id;
+    color: string;
+};
+export type ModelObservationLegendEntry<Row> = ChartLegendValue & {
+    color: string;
+    x: number;
+    row: Row;
+    sourceIndex: number;
+};
+type ModelLegendBase<Row, Id extends string> = Omit<LegendProps, 'series' | 'by' | 'renderValue' | 'renderLabel' | 'renderSwatch' | 'renderDifference' | 'renderItem'> & {
+    model: CartesianChartModel<Row, Id>;
+};
+type ModelSeriesLegendProps<Row, Id extends string> = ModelLegendBase<Row, Id> & {
+    by?: 'series';
+    series?: NoInfer<Id>;
+    renderValue?: (entry: ModelLegendEntry<Id>) => ReactNode;
+    renderLabel?: (entry: ModelLegendEntry<Id>) => ReactNode;
+    renderSwatch?: (entry: ModelLegendEntry<Id>) => ReactNode;
+    renderDifference?: (difference: ChartComparisonSeries<Id>, entry: ModelLegendEntry<Id>) => ReactNode;
+    renderItem?: (entry: ModelLegendEntry<Id>, actions: {
+        toggle: () => void;
+        focus: () => void;
+        isolate: () => void;
+        comparison: ChartComparisonSeries<Id> | null;
+    }) => ReactNode;
+};
+type ModelObservationLegendProps<Row, Id extends string> = ModelLegendBase<Row, Id> & {
+    by: 'observation';
+    series: NoInfer<Id>;
+    renderValue?: (entry: ModelObservationLegendEntry<Row>) => ReactNode;
+    renderLabel?: (entry: ModelObservationLegendEntry<Row>) => ReactNode;
+    renderSwatch?: (entry: ModelObservationLegendEntry<Row>) => ReactNode;
+    renderItem?: (entry: ModelObservationLegendEntry<Row>, actions: {
+        toggle: () => void;
+        focus: () => void;
+        isolate: () => void;
+        comparison: null;
+    }) => ReactNode;
+};
+export type ModelLegendProps<Row, Id extends string> = ModelSeriesLegendProps<Row, Id> | ModelObservationLegendProps<Row, Id>;
+/** Normal-flow presentation; placement belongs to the consumer's layout. */
+export declare function Legend<Row, Id extends string>(props: ModelLegendProps<Row, Id>): ReactElement | null;
+export declare function Legend(props?: LegendProps & {
+    model?: never;
+}): ReactElement | null;
+export {};

package/dist/interaction/pin-marker.d.ts

@@ -0,0 +1,12 @@
+import { ReactElement } from 'react';
+export declare const PIN_SIZE = 24;
+/**
+ * The marker above a pinned crosshair. It fades in with a soft blur, follows the pinned point,
+ * and releases the pin when clicked; on hover it shows the release glyph instead of the pin.
+ */
+export declare function PinMarker({ left, top, reducedMotion, onRelease, }: {
+    left: number;
+    top: number;
+    reducedMotion: boolean;
+    onRelease: () => void;
+}): ReactElement;

package/dist/interaction/tooltip-context.d.ts

@@ -0,0 +1,4 @@
+import { ChartSnapshot } from '../chart-context';
+import { NormalizedRow } from '../engine/normalize';
+import { ChartSeries, ChartTooltipContext } from '../types';
+export declare function tooltipContext<T>(snapshot: ChartSnapshot<T>, row: NormalizedRow<T>, series: readonly ChartSeries<T>[], pinned: boolean, activeSeriesId?: string | null): ChartTooltipContext<T>;

package/dist/interaction/tooltip-view.d.ts

@@ -0,0 +1,26 @@
+import { ReactNode } from 'react';
+import { ChartComparisonContext, ChartTooltipContext } from '../types';
+import { AdaptiveReadoutProps } from './adaptive-readout';
+export interface TooltipView {
+    inspection: ChartTooltipContext | null;
+    comparison: ChartComparisonContext | null;
+    colors: Readonly<Record<string, string>>;
+    x: number;
+    compareStartX: number;
+    compareEndX: number;
+    top: number;
+    width: number;
+    height: number;
+    reducedMotion: boolean;
+    compact: boolean;
+    narrow: boolean;
+    peer: boolean;
+    adaptive: Omit<AdaptiveReadoutProps<unknown>, 'renderContent'> | null;
+    onRelease: () => void;
+    onCompareFromHere?: () => void;
+}
+export declare function TooltipViewProvider({ value, children, }: {
+    value: TooltipView;
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function useTooltipView(): TooltipView;

package/dist/interaction/tooltip.d.ts

@@ -0,0 +1,10 @@
+import { ReactElement } from 'react';
+import { TooltipProps } from '../types';
+import { CartesianChartModel } from '../model/cartesian-model';
+/** A real, optional HTML part in ChartPlot's tooltip slot. */
+export declare function Tooltip<Row, Id extends string>(props: TooltipProps<Row, Id> & {
+    model: CartesianChartModel<Row, Id>;
+}): ReactElement | null;
+export declare function Tooltip(props?: TooltipProps & {
+    model?: never;
+}): ReactElement | null;

package/dist/interaction/use-category-state.d.ts

@@ -0,0 +1,24 @@
+import { KeyboardEvent } from 'react';
+import { CategorySelection, ChartStatus } from '../types';
+import { RankingRow } from '../engine/ranking';
+/** Retain accepted observations during refreshes; only a new identity clears them. */
+export declare function useAcceptedRows<R>(incoming: readonly R[] | null, status: ChartStatus, resetKey?: string | number): {
+    rows: readonly R[] | null;
+    firstLoad: boolean;
+    skeleton: boolean;
+};
+export declare function useCategoryState<T>(rows: readonly RankingRow<T>[], interactive: boolean, onChange: ((selection: CategorySelection<T> | null) => void) | undefined, resetKey?: string | number, columns?: number, selectedId?: string | null, onSelectedIdChange?: (id: string | null) => void, hasAcceptedRows?: boolean, externalHoverId?: string | null): {
+    active: RankingRow<T> | undefined;
+    pinned: string | null;
+    bind: (id: string, index: number) => {
+        ref: (node: HTMLButtonElement | null) => void;
+        tabIndex: number;
+        'aria-pressed': boolean;
+        onPointerEnter: () => void;
+        onPointerLeave: () => void;
+        onFocus: () => void;
+        onBlur: () => void;
+        onClick: () => void;
+        onKeyDown: (event: KeyboardEvent<HTMLButtonElement>) => void;
+    };
+};

package/dist/interaction/use-pinned-selection.d.ts

@@ -0,0 +1,3 @@
+import { SetStateAction } from 'react';
+/** User selection can be owned by a dashboard; hover remains local to the chart. */
+export declare function usePinnedSelection(controlled: string | null | undefined, onChange?: (id: string | null) => void): readonly [string | null, (next: SetStateAction<string | null>) => void, () => void];

package/dist/interaction/value-legend.d.ts

@@ -0,0 +1,32 @@
+import { CSSProperties, ReactNode } from 'react';
+export interface ValueLegendEntry {
+    id: string;
+    label: string;
+    color: string;
+    value: number | null;
+    formattedValue: string;
+}
+export interface ValueLegendProps<Entries extends readonly ValueLegendEntry[]> {
+    items: Entries;
+    variant?: 'cards' | 'inline';
+    activeId?: NoInfer<Entries[number]['id']> | null;
+    selectedId?: NoInfer<Entries[number]['id']> | null;
+    onHoverIdChange?: (id: NoInfer<Entries[number]['id']> | null) => void;
+    onSelectedIdChange?: (id: NoInfer<Entries[number]['id']> | null) => void;
+    /** Series currently hidden from the chart. */
+    hiddenIds?: readonly NoInfer<Entries[number]['id']>[];
+    /**
+     * Makes the legend a visibility control: clicking a tile hides or shows its series, and each
+     * tile offers "Only" and "Show all". The last visible series can't be hidden.
+     */
+    onHiddenIdsChange?: (ids: NoInfer<Entries[number]['id']>[]) => void;
+    renderLabel?: (entry: Entries[number]) => ReactNode;
+    renderValue?: (entry: Entries[number]) => ReactNode;
+    renderSwatch?: (entry: Entries[number]) => ReactNode;
+    renderItem?: (entry: Entries[number]) => ReactNode;
+    'aria-label'?: string;
+    className?: string;
+    style?: CSSProperties;
+}
+/** Family-neutral values and layout. The consumer supplies measurements and interaction ownership. */
+export declare function ValueLegend<const Entries extends readonly ValueLegendEntry[]>({ items, variant, activeId, selectedId, onHoverIdChange, onSelectedIdChange, hiddenIds, onHiddenIdsChange, renderLabel, renderValue, renderSwatch, renderItem, 'aria-label': ariaLabel, className, style, }: ValueLegendProps<Entries>): import("react/jsx-runtime").JSX.Element;

package/dist/interaction/visibility.d.ts

@@ -0,0 +1,8 @@
+export interface VisibilityIsolation {
+    id: string;
+    restore: readonly string[];
+    expected: readonly string[];
+    previous: readonly string[];
+}
+export declare function sameVisibleSet(a: readonly string[], b: readonly string[]): boolean;
+export declare function reconcileIsolation(isolation: VisibilityIsolation | null, visible: readonly string[], available: readonly string[]): VisibilityIsolation | null;

package/dist/lifecycle/loading-layer.d.ts

@@ -0,0 +1,38 @@
+import { ReactElement } from 'react';
+import { ChartAxisStyle } from '../types';
+export interface LoadingLayerProps {
+    width: number;
+    height: number;
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+    visible: boolean;
+    opacity: number;
+    reducedMotion: boolean;
+    id: string;
+    /** The marks the skeleton stands in for. */
+    marks?: 'line' | 'bars' | 'area-stack' | 'bar-stack';
+    compact?: boolean;
+    barCount?: number;
+    seriesCount?: number;
+    showLine?: boolean;
+    /** Mirror the real axis: which placeholders and grid rows to draw. Defaults to `classic`. */
+    axis?: ChartAxisStyle;
+    /** Padding between the plot edges and label placeholders, as on the real axis. */
+    inset?: number;
+    /** Gap between the plot edges and the skeleton shape; 0 when marks run edge to edge. */
+    edge?: number;
+}
+export declare const SKELETON_CONTOUR: number[];
+export interface SkeletonGeometry {
+    plotWidth: number;
+    plotBottom: number;
+    contour: string;
+    areaPath: string;
+    gridRows: string;
+    yBars: string;
+    xBars: string;
+}
+export declare function buildSkeletonGeometry({ width, height, left, right, top, bottom, axis, inset, edge, }: Pick<LoadingLayerProps, 'width' | 'height' | 'left' | 'right' | 'top' | 'bottom' | 'axis' | 'inset' | 'edge'>): SkeletonGeometry;
+export declare function LoadingLayer({ width, height, left, right, top, bottom, visible, opacity, reducedMotion, id, marks, compact, barCount, seriesCount, showLine, axis, inset: labelInset, edge, }: LoadingLayerProps): ReactElement | null;

package/dist/lifecycle/skeleton-sheen.d.ts

@@ -0,0 +1,18 @@
+import { ReactNode } from 'react';
+export interface SkeletonSheenProps {
+    /** The skeleton shapes. Their CSS paints them with `--lilt-skeleton-paint`. */
+    children: ReactNode;
+    /** The area the sheen sweeps across, in the SVG's own units. */
+    width: number;
+    height: number;
+    x?: number;
+    y?: number;
+    /** Draw the shapes without the moving highlight. */
+    reduced?: boolean;
+}
+/**
+ * Skeleton shapes with the same moving highlight as the Cartesian loading state. The shapes are
+ * drawn once for the eye and once more, in white, as the mask the highlight shows through, so
+ * the sheen lights only the placeholder and never the space around it.
+ */
+export declare function SkeletonSheen({ children, width, height, x, y, reduced, }: SkeletonSheenProps): import("react/jsx-runtime").JSX.Element;

package/dist/lifecycle/status-content.d.ts

@@ -0,0 +1,6 @@
+import { ReactNode } from 'react';
+export declare function StatusContent({ kind, message, retry, }: {
+    kind: 'empty' | 'error' | 'refresh-error';
+    message: string;
+    retry?: () => ReactNode;
+}): React.ReactElement;

package/dist/model/cartesian-model.d.ts

@@ -0,0 +1,132 @@
+import { ChartComparisonResult, ChartPercentagePolicy, ChartController, ChartSeries, ChartYConfig, ChartTooltipContext, NumericXConfig, TimeXConfig, ChartRange } from '../types';
+import { LegendSnapshot } from '../runtime/chart-runtime';
+export type CartesianModelLegendItem<Id extends string> = LegendSnapshot['series'][number] & {
+    id: Id;
+};
+export type CartesianModelObservation<Row> = LegendSnapshot['observations'][number] & {
+    row: Row;
+};
+export interface CartesianModelState<Row, SeriesId extends string> {
+    readonly availability: 'loading' | 'ready' | 'error';
+    readonly acceptedRevision: number;
+    readonly inspection: ChartTooltipContext<Row, SeriesId> | null;
+    readonly comparison: ChartComparisonResult<SeriesId, Row> | null;
+    readonly visibleSeries: readonly SeriesId[];
+    readonly legend: readonly CartesianModelLegendItem<SeriesId>[];
+    readonly observations: readonly CartesianModelObservation<Row>[];
+}
+export interface CartesianModelFrame<Row, Id extends string> {
+    readonly data: readonly Row[];
+    readonly x: TimeXConfig<Row> | NumericXConfig<Row>;
+    readonly y?: ChartYConfig;
+    readonly series: readonly (ChartSeries<Row> & {
+        readonly id: Id;
+    })[];
+}
+export interface CartesianModelInput<Row, Id extends string> extends CartesianModelFrame<Row, Id> {
+    readonly status?: 'loading' | 'ready' | 'error';
+    readonly resetKey?: string | number;
+    readonly control?: CartesianModelControl<Id>;
+}
+export interface CartesianModelControl<Id extends string> {
+    readonly inspection?: {
+        readonly x: number;
+        readonly pinned: boolean;
+    } | null;
+    readonly visibleSeries?: readonly Id[];
+    readonly comparison?: ChartRange | null;
+    readonly onInspectionRequest?: (inspection: {
+        readonly x: number;
+        readonly pinned: boolean;
+    } | null) => void;
+    readonly onVisibleSeriesRequest?: (ids: readonly Id[]) => void;
+    readonly onComparisonRequest?: (range: ChartRange | null) => void;
+}
+export interface CartesianSummaryQuery<Id extends string> {
+    readonly measure: Id;
+    readonly scope?: ChartRange | null;
+    readonly aggregate: 'sum' | 'mean' | 'min' | 'max' | 'first' | 'last' | 'change';
+    readonly missing?: 'exclude' | 'require-complete';
+}
+export interface CartesianSummaryResult<Id extends string> {
+    readonly measure: Id;
+    readonly value: number | null;
+    readonly formattedValue: string;
+    readonly unit: string | null;
+    readonly coverage: {
+        readonly observed: number;
+        readonly missing: number;
+        readonly total: number;
+    };
+    readonly unavailableReason: string | null;
+}
+export interface CartesianModelActions<SeriesId extends string> {
+    readonly inspect: (x: number) => void;
+    readonly clearInspection: () => void;
+    readonly pin: (x: number) => void;
+    readonly release: () => void;
+    readonly setVisibleSeries: (ids: readonly SeriesId[]) => void;
+    readonly focusSeries: (id: SeriesId | null) => void;
+    readonly compare: (range: ChartRange, percentage?: ChartPercentagePolicy) => void;
+    readonly clearComparison: () => void;
+    readonly focusComparison: () => void;
+    readonly fullRange: () => void;
+}
+/** Carries the source row and declared series IDs across JSX component boundaries. */
+export interface CartesianChartModel<Row, SeriesId extends string> {
+    readonly data: readonly Row[];
+    readonly x: TimeXConfig<Row> | NumericXConfig<Row>;
+    readonly series: readonly (ChartSeries<Row> & {
+        readonly id: SeriesId;
+    })[];
+    readonly getFrame: () => CartesianModelFrame<Row, SeriesId>;
+    readonly getAcceptedFrame: () => CartesianModelFrame<Row, SeriesId> | null;
+    readonly getAvailability: () => CartesianModelState<Row, SeriesId>['availability'];
+    readonly getResetKey: () => string | number | undefined;
+    /** Internal view projection of persistent inspection, comparison and focus. */
+    readonly getController: () => ChartController;
+    readonly update: (frame: CartesianModelInput<Row, SeriesId>) => void;
+    readonly summarize: (query: CartesianSummaryQuery<SeriesId>) => CartesianSummaryResult<SeriesId>;
+    readonly actions: CartesianModelActions<SeriesId>;
+    readonly getSnapshot: () => CartesianModelState<Row, SeriesId>;
+    readonly subscribe: (listener: () => void) => () => void;
+}
+type ModelActions = {
+    inspect: (x: number) => void;
+    clearInspection: () => void;
+    pin: (x: number) => void;
+    release: () => void;
+    setVisibleSeries: (ids: readonly string[]) => void;
+    focusSeries: (id: string | null) => void;
+    compare: (range: ChartRange) => void;
+    clearComparison: () => void;
+    focusComparison: () => void;
+    fullRange: () => void;
+};
+/** Internal publication from the accepted Cartesian plot; presentation never recalculates values. */
+export declare function publishCartesianModel<Row, Id extends string>(model: CartesianChartModel<Row, Id>, state: Pick<CartesianModelState<Row, Id>, 'inspection' | 'comparison' | 'visibleSeries' | 'legend'>, actions: ModelActions): void;
+/** Release a view's callbacks without changing the model's accepted frame or persistent state. */
+export declare function detachCartesianModel<Row, Id extends string>(model: CartesianChartModel<Row, Id>): void;
+/** Subscribe from any React component that has the handle, including outside Chart. */
+export declare function useCartesianModelState<Row, Id extends string>(model: CartesianChartModel<Row, Id>): CartesianModelState<Row, Id>;
+/** Define descriptors once; literal IDs and source-row metadata remain inferred. */
+export declare function createCartesianChartModel<Row, const Series extends readonly ChartSeries<NoInfer<Row>>[]>({ data, x, y, series, status, resetKey, control, }: {
+    readonly data: readonly Row[];
+    readonly x: TimeXConfig<NoInfer<Row>> | NumericXConfig<NoInfer<Row>>;
+    readonly y?: ChartYConfig;
+    readonly series: Series;
+    readonly status?: 'loading' | 'ready' | 'error';
+    readonly resetKey?: string | number;
+    readonly control?: CartesianModelControl<Series[number]['id']>;
+}): CartesianChartModel<Row, Series[number]['id']>;
+/** Keep a Cartesian handle stable while ready input frames change. */
+export declare function useCartesianChartModel<Row, const Series extends readonly ChartSeries<NoInfer<Row>>[]>(input: {
+    readonly data: readonly Row[];
+    readonly x: TimeXConfig<NoInfer<Row>> | NumericXConfig<NoInfer<Row>>;
+    readonly y?: ChartYConfig;
+    readonly series: Series;
+    readonly status?: 'loading' | 'ready' | 'error';
+    readonly resetKey?: string | number;
+    readonly control?: CartesianModelControl<Series[number]['id']>;
+}, status?: 'ready' | 'loading' | 'error'): CartesianChartModel<Row, Series[number]['id']>;
+export {};

package/dist/model/cartesian-model.typecheck.d.ts

@@ -0,0 +1 @@
+export declare function ModelComposition(): import("react/jsx-runtime").JSX.Element;

package/dist/model/use-chart-state.d.ts

@@ -0,0 +1,6 @@
+export interface ChartStateSource<Snapshot> {
+    getSnapshot: () => Snapshot;
+    subscribe: (listener: () => void) => () => void;
+}
+/** Subscribe to one model slice without changing the type carried by its handle. */
+export declare function useChartState<Snapshot, Selected>(model: ChartStateSource<Snapshot>, selector: (snapshot: Snapshot) => Selected): Selected;