@lilt-ui/charts 0.1.0

package/dist/engine/geometry.d.ts

@@ -0,0 +1,73 @@
+import { ChartCurve, ChartObservationStatus, ChartSeries } from '../types';
+import { NormalizedData } from './normalize';
+import { BarGeometry } from './bars';
+import { StackMode } from './stack';
+export interface ScreenPoint {
+    x: number;
+    y: number;
+}
+export interface LinearPiece {
+    kind: 'line';
+    from: ScreenPoint;
+    to: ScreenPoint;
+}
+export interface CubicPiece {
+    kind: 'cubic';
+    from: ScreenPoint;
+    control1: ScreenPoint;
+    control2: ScreenPoint;
+    to: ScreenPoint;
+}
+export type CurvePiece = LinearPiece | CubicPiece;
+export interface GeometrySegment {
+    status?: ChartObservationStatus;
+    points: readonly ScreenPoint[];
+    pieces: readonly CurvePiece[];
+    path: string;
+    areaPath: string;
+    startX: number;
+    endX: number;
+}
+export interface SeriesGeometry {
+    seriesId: string;
+    curve: ChartCurve;
+    segments: readonly GeometrySegment[];
+    isolated: readonly ScreenPoint[];
+}
+export interface PlotGeometry {
+    series: Readonly<Record<string, SeriesGeometry>>;
+    bars: Readonly<Record<string, readonly BarGeometry[]>>;
+    bands: Readonly<Record<string, readonly string[]>>;
+    baselineY: number;
+}
+/** Series that stack, in chart series order, and how their layers are drawn. */
+export interface GeometryStack {
+    series: readonly string[];
+    mode: StackMode;
+    /** Draw each layer as bar segments rather than an area band. */
+    bars: boolean;
+    /** A sum stack with values below zero: positives rise from zero and negatives hang below. */
+    signed: boolean;
+    /** Animated visibility of each layer, from 0 to 1. */
+    weights?: Readonly<Record<string, number>>;
+}
+export interface GeometryBuildOptions<T> {
+    plotLeft: number;
+    plotTop: number;
+    plotWidth: number;
+    plotHeight: number;
+    xDomain: readonly [number, number];
+    yDomain: readonly [number, number];
+    series: readonly ChartSeries<T>[];
+    curveBySeries: Readonly<Record<string, ChartCurve>>;
+    xInset?: number;
+    /** Grouped bars outside any stack, in slot order. */
+    barSeries?: readonly string[];
+    barGroupWidth?: number;
+    barGap?: number;
+    stack?: GeometryStack;
+    /** Series plotted against their own value scale, e.g. a rate line over revenue bars. */
+    yDomainBySeries?: Readonly<Record<string, readonly [number, number]>>;
+}
+export declare function buildGeometry<T>(data: NormalizedData<T>, options: GeometryBuildOptions<T>): PlotGeometry;
+export declare function pointAtX(geometry: SeriesGeometry, x: number): ScreenPoint | null;

package/dist/engine/lifecycle.d.ts

@@ -0,0 +1,10 @@
+export type LifecyclePhase = 'pending' | 'loading' | 'handoff' | 'revealing' | 'ready' | 'updating' | 'empty' | 'error';
+export interface LifecycleGeneration {
+    next: () => number;
+    current: () => number;
+    isCurrent: (generation: number) => boolean;
+}
+export declare function createLifecycleGeneration(): LifecycleGeneration;
+export declare function durationForPhase(phase: 'initial' | 'handoff' | 'matched-update' | 'topology-update', reducedMotion: boolean, animateIn?: boolean): number;
+/** Preserve full data fidelity while avoiding repeated per-sample geometry tweens. */
+export declare function skipDataTweenForWorkload(sampleCount: number, millisecondsSinceLastUpdate: number): boolean;

package/dist/engine/lookup.d.ts

@@ -0,0 +1,3 @@
+export declare function nearestVisibleRowIndex<T extends {
+    x: number;
+}>(rows: readonly T[], domain: readonly [number, number], pixel: number, xToPixel: (x: number) => number): number | null;

package/dist/engine/normalize.d.ts

@@ -0,0 +1,21 @@
+import { ChartObservationStatus, ChartSeries, ChartXConfig } from '../types';
+export interface NormalizedRow<T> {
+    datum: T;
+    sourceIndex: number;
+    x: number;
+    categoryId?: string;
+    values: Readonly<Record<string, number | null>>;
+    statuses: Readonly<Record<string, ChartObservationStatus>>;
+    intervals: Readonly<Record<string, {
+        lower: number;
+        upper: number;
+    } | null>>;
+}
+export interface NormalizedData<T> {
+    rows: readonly NormalizedRow<T>[];
+    series: readonly ChartSeries<T>[];
+    xType: 'time' | 'number' | 'category';
+}
+export declare function normalizeData<T>(data: readonly T[], series: readonly ChartSeries<T>[], x: ChartXConfig<T>): NormalizedData<T>;
+export declare function hasFiniteValue<T>(data: NormalizedData<T>, seriesId?: string): boolean;
+export declare function hasMatchingTopology<T>(a: NormalizedData<T>, b: NormalizedData<T>, series: readonly ChartSeries<T>[]): boolean;

package/dist/engine/ranking.d.ts

@@ -0,0 +1,20 @@
+import { RankingOrder } from '../types';
+export interface RankingCategory<T> {
+    id: (row: T) => string;
+    label: (row: T) => string;
+}
+export interface RankingRow<T> {
+    id: string;
+    label: string;
+    datum: T;
+    value: number | null;
+}
+export declare function normalizeRanking<T>(data: readonly T[], category: RankingCategory<T>, accessor: (row: T) => number | null): RankingRow<T>[];
+export declare function orderRanking<T>(rows: readonly RankingRow<T>[], order: RankingOrder): RankingRow<T>[];
+export declare function rankingDomain<T>(rows: readonly RankingRow<T>[]): readonly [number, number];
+/** Relative geometry leaves layout and resizing to the host's available width. */
+export declare function rankingBar(value: number | null, domain: readonly [number, number]): {
+    zero: number;
+    left: number;
+    width: number;
+};

package/dist/engine/sankey.d.ts

@@ -0,0 +1,36 @@
+export interface SankeyNode {
+    id: string;
+    label: string;
+}
+export interface SankeyLink {
+    id: string;
+    source: string;
+    target: string;
+    value: number | null;
+}
+export type ConservationPolicy = 'strict' | 'allow-loss';
+export interface SankeyGraph<Node extends SankeyNode = SankeyNode, Link extends SankeyLink = SankeyLink> {
+    nodes: readonly Node[];
+    links: readonly Link[];
+    depth: Readonly<Record<string, number>>;
+    losses: Readonly<Record<string, number | null>>;
+}
+export interface PositionedSankeyNode extends SankeyNode {
+    depth: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    total: number;
+}
+export interface PositionedSankeyLink extends SankeyLink {
+    path: string;
+    width: number;
+    sourceY: number;
+    targetY: number;
+}
+export declare function normalizeSankey<Node extends SankeyNode, Link extends SankeyLink>(nodes: readonly Node[], links: readonly Link[], conservation: ConservationPolicy): SankeyGraph<Node, Link>;
+export declare function layoutSankey(graph: SankeyGraph, width: number, height: number, compact?: boolean): {
+    nodes: PositionedSankeyNode[];
+    links: PositionedSankeyLink[];
+};

package/dist/engine/scatter.d.ts

@@ -0,0 +1,15 @@
+export interface ScatterPoint<T> {
+    id: string;
+    label: string;
+    row: T;
+    x: number | null;
+    y: number | null;
+    size: number | null;
+}
+export interface PositionedScatterPoint<T> extends ScatterPoint<T> {
+    cx: number;
+    cy: number;
+    radius: number;
+}
+/** Nearest candidate wins; a repeated click can cycle coincident points. */
+export declare function hitTestScatter<T>(points: readonly PositionedScatterPoint<T>[], x: number, y: number, selectedId: string | null, cycle?: boolean): string | null;

package/dist/engine/slope.d.ts

@@ -0,0 +1,46 @@
+/** One category measured at two points, with its change between them. */
+export interface SlopeRow {
+    id: string;
+    label: string;
+    from: number | null;
+    to: number | null;
+    /** `to − from`, or null when either end is missing. */
+    change: number | null;
+    /**
+     * Fractional change against a positive starting value, e.g. 0.12 for +12%. Null when either
+     * end is missing or the start is zero or negative, where a percentage has no honest meaning.
+     */
+    ratio: number | null;
+}
+/** `change` puts the largest gain first, `to` the largest end value, `input` keeps your order. */
+export type SlopeOrder = 'change' | 'to' | 'input';
+/** The change between two measurements under the positive-baseline percentage policy. */
+export declare function changeBetween(from: number | null, to: number | null): {
+    change: null;
+    ratio: null;
+} | {
+    change: number;
+    ratio: number | null;
+};
+export declare function slopeRows<Row>(data: readonly Row[], category: string, from: string, to: string, order?: SlopeOrder): SlopeRow[];
+/**
+ * One number for each end: the `sum` (default) or `mean` of the categories. `to` covers every
+ * observed later value; the change compares only categories measured at both ends, so a category
+ * that is new or has not reported yet never reads as growth or loss.
+ */
+export declare function slopeTotals(rows: readonly SlopeRow[], aggregate?: 'sum' | 'mean'): {
+    change: null;
+    ratio: null;
+    to: number | null;
+} | {
+    change: number;
+    ratio: number | null;
+    to: number | null;
+};
+/** A value domain around both ends with a little headroom, so no dot touches an edge. */
+export declare function slopeDomain(rows: readonly SlopeRow[]): readonly [number, number];
+/**
+ * Move label positions apart until neighbours are at least `gap` apart, staying within
+ * [min, max] and as close to their targets as possible. Returns positions in input order.
+ */
+export declare function spreadLabels(targets: readonly number[], gap: number, min: number, max: number): number[];

package/dist/engine/stack.d.ts

@@ -0,0 +1,11 @@
+import { ChartSeries, ChartStackMode } from '../types';
+import { NormalizedData, NormalizedRow } from './normalize';
+export type StackMode = ChartStackMode;
+/** Value of the last displayed stack boundary, in the axis's units. */
+export declare function stackInspectionValue(values: readonly (number | null)[], mode: StackMode): number | null;
+/** Whether a sum stack has values below zero, which then stack downward from the baseline. */
+export declare function hasNegativeContribution<T>(data: NormalizedData<T>, ids: readonly string[]): boolean;
+export declare function validateStack<T>(data: NormalizedData<T>, series: readonly ChartSeries<T>[], mode?: StackMode): void;
+/** A missing contribution makes the total unknown, not zero. Hidden series do not contribute. */
+export declare function stackTotal<T>(row: NormalizedRow<T>, ids: readonly string[]): number | null;
+export declare function stackDomainData<T>(data: NormalizedData<T>, series: readonly ChartSeries<T>[], mode?: StackMode): NormalizedData<T>;

package/dist/export-chart-svg.d.ts

@@ -0,0 +1,8 @@
+/** Browser-side static export for SVG-backed chart plots. HTML readouts and legends are not included. */
+export interface ChartSvgExportOptions {
+    title: string;
+    description?: string;
+    /** Defaults to the chart's resolved --lilt-surface color. */
+    background?: string;
+}
+export declare function serializeChartSvg(root: Element, options: ChartSvgExportOptions): string;

package/dist/index.d.ts

@@ -0,0 +1,73 @@
+export { Chart, useChartComparison } from './runtime/chart-runtime';
+export { createCartesianChartModel, useCartesianChartModel, useCartesianModelState, } from './model/cartesian-model';
+export { useChartState } from './model/use-chart-state';
+export type { CartesianChartModel, CartesianModelState, CartesianSummaryQuery, CartesianSummaryResult, } from './model/cartesian-model';
+export { ComparisonDetails } from './toolkit/comparison-details';
+export type { ComparisonDetailsProps } from './toolkit/comparison-details';
+export { ChartPlot } from './chart-plot';
+export { ChartToolbar } from './toolkit/chart-toolbar';
+export { ChartReadout } from './toolkit/chart-readout';
+export { ChartOverview } from './toolkit/chart-overview';
+export { ChartBrush } from './toolkit/chart-brush';
+export { Area } from './primitives/area';
+export { IntervalBand } from './primitives/interval-band';
+export { Line } from './primitives/line';
+export { Bar } from './primitives/bar';
+export type { SankeyNode, SankeyLink, ConservationPolicy } from './engine/sankey';
+export { serializeChartSvg } from './export-chart-svg';
+export type { ChartSvgExportOptions } from './export-chart-svg';
+export { Grid } from './primitives/grid';
+export { XAxis, YAxis } from './primitives/axes';
+export { Tooltip } from './interaction/tooltip';
+export { Legend } from './interaction/legend';
+export { ValueLegend, type ValueLegendEntry, type ValueLegendProps, } from './interaction/value-legend';
+export { createChartController } from './interaction/chart-controller';
+export { useChartSync } from './interaction/chart-sync';
+export type { ChartSyncPosition } from './interaction/chart-sync';
+export { Annotations, ReferenceBand } from './primitives/annotations';
+export { ReferenceLine } from './primitives/reference-line';
+export { ChangeComparison } from './primitives/change-comparison';
+export { AnimatedNumber } from './motion/animated-number';
+export type { AnimatedNumberProps, AnimatedNumberVariant } from './motion/animated-number';
+export type { ChartAxisStyle, ChartBackground, ChartPalette, ChartHoverReadout, ChartHoverStyle, ChartTooltipIndicator, ChartSurface, AreaProps, IntervalBandProps, ReferenceLineProps, BarProps, ChartCurve, ChartFillTreatment, ChartObservationStatus, ChartMargins, ChartMotion, ChartProps, ChartPlotProps, ChartToolbarProps, ChartReadoutProps, ChartOverviewProps, ChartBrushProps, ChartSeries, ChartStyle, ChartLineStyle, ChartAreaStyle, ChartBarStyle, ChartBarAppearance, ChartBarLayout, ChartBars, ChartStack, ChartStackMode, ChartStatus, ChartXConfig, ChartYConfig, ChartSelection, ChartAnnotation, ChartCompareConfig, ChartComparison, ChartComparisonSeries, ChartComparisonResult, ChartComparisonContext, ChartController, ChartControllerInspection, ChartControllerSnapshot, ChartFocusConfig, ChartLiveConfig, ChartPercentagePolicy, ChartRange, ChangeComparisonProps, AnnotationsProps, ReferenceBandProps, LegendProps, LineProps, NumericXConfig, CategoryXConfig, PrimitiveProps, GridProps, TimeXConfig, TooltipProps, ChartTooltipContext, ChartLegendValue, XAxisProps, YAxisProps, } from './types';
+export { summarizeRange, toChartCsv } from './data/chart-data';
+export { funnelRows as summarizeFunnelStages } from './engine/analysis';
+export type { FunnelRow as FunnelStageSummary } from './engine/analysis';
+export type { ChartSummary, CsvColumn } from './data/chart-data';
+export { ChartRangeSummary } from './toolkit/chart-range-summary';
+export type { ChartRangeSummaryProps } from './toolkit/chart-range-summary';
+export { AreaChartCard } from './cards/area-chart-card';
+export type { AreaChartCardProps, CardSeries, CardRange } from './cards/area-chart-card';
+export { LineChartCard } from './cards/line-chart-card';
+export type { LineChartCardProps } from './cards/line-chart-card';
+export { BarChartCard } from './cards/bar-chart-card';
+export type { BarChartCardProps } from './cards/bar-chart-card';
+export type { CardForecast, CardTarget, CartesianCardProps } from './cards/cartesian-card';
+export { StatCard } from './cards/stat-card';
+export type { StatCardProps, StatCardChart } from './cards/stat-card';
+export type { CardAggregate } from './cards/format';
+export { HorizontalBarChartCard } from './cards/horizontal-bar-chart-card';
+export type { HorizontalBarChartCardProps } from './cards/horizontal-bar-chart-card';
+export { ComboChartCard } from './cards/combo-chart-card';
+export type { ComboChartCardProps, ComboLineSeries } from './cards/combo-chart-card';
+export { RadialChartCard } from './cards/radial-chart-card';
+export type { RadialChartCardProps, RadialChartCardVariant } from './cards/radial-chart-card';
+export { ProgressCard } from './cards/progress-card';
+export type { ProgressCardProps, ProgressRange } from './cards/progress-card';
+export { FunnelChartCard } from './cards/funnel-chart-card';
+export type { FunnelChartCardProps } from './cards/funnel-chart-card';
+export { HeatmapChartCard } from './cards/heatmap-chart-card';
+export type { HeatmapAggregate, HeatmapChartCardProps } from './cards/heatmap-chart-card';
+export { ScatterChartCard } from './cards/scatter-chart-card';
+export type { ScatterAggregate, ScatterChartCardProps } from './cards/scatter-chart-card';
+export { SankeyChartCard } from './cards/sankey-chart-card';
+export type { SankeyChartCardProps } from './cards/sankey-chart-card';
+export { RadarChartCard } from './cards/radar-chart-card';
+export type { RadarAggregate, RadarChartCardProps } from './cards/radar-chart-card';
+export { SlopeChartCard } from './cards/slope-chart-card';
+export type { SlopeChartCardProps, SlopeOrder } from './cards/slope-chart-card';
+export { ActivityRingCard } from './cards/activity-ring-card';
+export type { ActivityAggregate, ActivityRingCardProps } from './cards/activity-ring-card';
+export { ChartCard, ChartCardHeader, ChartCardTitle, ChartCardValue, ChartCardDelta, ChartCardCaption, ChartCardRange, CardBadge, } from './cards/chart-card';
+export type { ChartCardProps, ChartCardHeaderProps, ChartCardValueProps, ChartCardDeltaProps, ChartCardRangeProps, ChartCardRangeOption, CardBadgeProps, } from './cards/chart-card';
+export type { KeysOfType, NumericKey, TextKey, XKey, XKind } from './cards/keys';