@lilt-ui/charts 0.1.0 → 0.3.0

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

@@ -1,5 +1,5 @@
 import { MotionValue } from 'motion/react';
-import { ChartAxisStyle, ChartHoverStyle } from '../types';
+import { ChartAxis, 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. */
@@ -11,7 +11,8 @@ export interface AxisCursor {
     y: MotionValue<number>;
     /** 1 while this chart owns an inspection, else 0. */
     active: MotionValue<number>;
-    style: ChartAxisStyle;
+    /** The preset each axis uses. */
+    axis: ResolvedAxis;
     pill: ChartHoverStyle;
     /** Padding between the plot edges and axis labels or pills, for plots that run edge to edge. */
     inset: number;
@@ -26,5 +27,14 @@ 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;
+/** The preset each axis uses, and a segmented axis's color scale. */
+export interface ResolvedAxis {
+    x: ChartAxisStyle;
+    y: ChartAxisStyle;
+    xGradient?: boolean | readonly string[];
+    yGradient?: boolean | readonly string[];
+}
+/** Split an `axis` prop into one preset per axis. An axis left out is `minimal`. */
+export declare function resolveAxis(axis: ChartAxis | undefined): ResolvedAxis;
 /** 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/chart-sync.d.ts

@@ -13,6 +13,8 @@ interface SyncState {
     readonly pinned: boolean;
     /** The card whose pointer or keyboard set this position. */
     readonly source: string;
+    /** That card's name, so linked cards can say where a pin came from. */
+    readonly label?: string;
 }
 /** Inspections this bridge writes into a card's controller carry this owner. */
 export declare const SYNC_OWNER = "sync";
@@ -27,9 +29,17 @@ export declare function useChartSync(name: string | undefined): ChartSyncPositio
  * card has no row there.
  */
 export declare function syncTarget(state: Pick<SyncState, 'key' | 'kind'>, kind: XKind, labels: readonly string[], positions: readonly number[]): number | null;
+export interface CardSyncOptions {
+    /** The card's name, shown on linked cards' pins: "Pinned from Revenue". */
+    label?: string;
+    /** Releases the card's own pin when a linked card releases the group's. */
+    release?: () => void;
+}
 /**
  * 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.
+ * A pin is shared unless it is local, as Alt-click makes it; a shared pin can be released from
+ * any card in the group, and local pins stay put.
  */
-export declare function useCardSync<Row>(name: string | undefined, controller: ChartController, data: readonly Row[], x: string, resolved: ResolvedX<Row>): void;
+export declare function useCardSync<Row>(name: string | undefined, controller: ChartController, data: readonly Row[], x: string, resolved: ResolvedX<Row>, { label, release }?: CardSyncOptions): void;
 export {};

package/dist/interaction/field-values.d.ts

@@ -0,0 +1,12 @@
+import { ReactElement } from 'react';
+import { ChartSeries, ChartTooltipField } from '../types';
+/** A series' companion values for one row, in descriptor order. */
+export declare function fieldEntries<T>(descriptor: ChartSeries<T>, values: Readonly<Record<string, number | null>> | undefined, format: (value: number) => string): ChartTooltipField[];
+export declare function FieldList({ fields }: {
+    fields: readonly ChartTooltipField[];
+}): ReactElement;
+export declare function FieldValues<T>({ descriptor, values, format, }: {
+    descriptor: ChartSeries<T>;
+    values: Readonly<Record<string, number | null>> | undefined;
+    format: (value: number) => string;
+}): ReactElement | null;

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

@@ -1,6 +1,13 @@
 import { ReactElement, ReactNode } from 'react';
 import { ChartSelection, ChartSeries, ChartTooltipContext } from '../types';
 import { ChartSnapshot } from '../chart-context';
+import { PlotMark } from '../marks/contract';
+/** How the crosshair travels between points; pins travel the same way. */
+export declare const SPRING_TRANSITION: {
+    stiffness: number;
+    damping: number;
+    mass: number;
+};
 interface InspectionLayerProps<T> {
     snapshot: ChartSnapshot<T>;
     selection: ChartSelection<T> | null;
@@ -24,6 +31,8 @@ interface InspectionLayerProps<T> {
     hideAxisBadges?: boolean;
     peer?: boolean;
     onCompareFromHere?: () => void;
+    /** Range marks in the plot; column marks draw their own highlight instead of a point. */
+    marks?: readonly PlotMark[];
 }
-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 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, marks, }: InspectionLayerProps<T>): ReactElement;
 export {};

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

@@ -0,0 +1,8 @@
+import { ReactElement } from 'react';
+/**
+ * Lilt's pin, shared by every control that pins something. With `release`, the struck-through
+ * pin waits underneath and takes over on hover or focus, meaning "unpin".
+ */
+export declare function PinGlyphs({ release }: {
+    release?: boolean;
+}): ReactElement;

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

@@ -3,10 +3,18 @@ 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.
+ * On a linked chart the pin arrived from elsewhere, so the marker is a ghost of the one that
+ * was clicked: it still releases the group's pin, but keyboard users meet only the original.
  */
-export declare function PinMarker({ left, top, reducedMotion, onRelease, }: {
+export declare function PinMarker({ left, top, reducedMotion, ghost, from, local, onRelease, }: {
     left: number;
     top: number;
     reducedMotion: boolean;
+    /** Pinned from a linked chart. */
+    ghost?: boolean;
+    /** The linked chart's name, for the tooltip. */
+    from?: string;
+    /** Pinned on this chart only. */
+    local?: boolean;
     onRelease: () => void;
 }): ReactElement;

package/dist/marks/contract.d.ts

@@ -0,0 +1,49 @@
+import { ReactElement, ReactNode } from 'react';
+import { ChartSnapshot } from '../chart-context';
+import { NormalizedRow } from '../engine/normalize';
+import { ChartSeries } from '../types';
+/**
+ * The private contract every range mark is built on. A mark is an ordinary primitive that
+ * draws from the chart context; its spec tells the plot how to lay it out and inspect it.
+ * The contract is internal until it has proved itself across several marks.
+ */
+export interface MarkSpec<P> {
+    /**
+     * `column` marks give each observation a bar-like slot, so the plot insets its edges, and
+     * replace the line point with their own highlight on inspection. `overlay` marks, such as a
+     * band behind a line, leave layout and inspection to the line.
+     */
+    layout: 'column' | 'overlay';
+    series: (props: P) => string;
+    /** Field IDs the mark reads from its series. */
+    fields: (props: P) => readonly string[];
+    /** Draws one observation emphasized, over the dimmed marks, while it is inspected. */
+    highlight?: (props: P, input: MarkHighlightInput) => ReactNode;
+}
+export interface MarkHighlightInput {
+    row: NormalizedRow<unknown>;
+    snapshot: ChartSnapshot<unknown>;
+    descriptor: ChartSeries<unknown>;
+    color: string;
+}
+/** A mark found among a plot's children, with its props bound. */
+export interface PlotMark {
+    series: string;
+    layout: MarkSpec<unknown>['layout'];
+    fields: readonly string[];
+    highlight?: (input: MarkHighlightInput) => ReactNode;
+}
+export declare function defineMark<P>(component: (props: P) => ReactElement, spec: MarkSpec<P>): (props: P) => ReactElement;
+/** Marks placed directly in a plot, or inside fragments there, in document order. */
+export declare function collectMarks(children: ReactNode): PlotMark[];
+/** The descriptor a mark draws, after checking it carries every field the mark reads. */
+export declare function markSeries<T>(mark: string, descriptors: readonly ChartSeries<T>[], series: string, fields: readonly string[]): {
+    descriptor: ChartSeries<T>;
+    index: number;
+};
+/** Field values of one row, or null when any of them is missing. */
+export declare function rowFields(row: NormalizedRow<unknown>, series: string, fields: readonly string[]): number[] | null;
+/** An observation's own color, falling back to the series color. */
+export declare function observationColor<T>(descriptor: ChartSeries<T>, row: NormalizedRow<T>, fallback: string): string;
+/** Rows whose x lies in the visible domain. */
+export declare function rowsInView<T>(snapshot: ChartSnapshot<T>): readonly NormalizedRow<T>[];

package/dist/marks/use-range-mark.d.ts

@@ -0,0 +1,19 @@
+import { ChartSnapshot } from '../chart-context';
+import { RangeScales } from '../engine/ranges';
+import { ChartSeries } from '../types';
+export interface RangeMarkState {
+    descriptor: ChartSeries<unknown>;
+    color: string;
+    scales: RangeScales;
+    snapshot: ChartSnapshot<unknown>;
+    /** Group opacity: hidden, dimmed behind focus or inspection, or full. */
+    opacity: number | string;
+    /** The reveal mask while the entrance sweeps in. */
+    mask: string | undefined;
+    clipPath: string;
+    reducedMotion: boolean;
+    inspecting: boolean;
+}
+export declare function scalesFor(snapshot: ChartSnapshot<unknown>, series: string): RangeScales;
+/** Shared state for a mark drawn from a series' fields. */
+export declare function useRangeMark(mark: string, series: string, fields: readonly string[], layout: 'column' | 'overlay'): RangeMarkState;

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

@@ -1,4 +1,4 @@
-import { ChartComparisonResult, ChartPercentagePolicy, ChartController, ChartSeries, ChartYConfig, ChartTooltipContext, NumericXConfig, TimeXConfig, ChartRange } from '../types';
+import { ChartComparisonResult, ChartPercentagePolicy, ChartController, ChartSeries, ChartYConfig, ChartTooltipContext, NumericXConfig, TimeXConfig, ChartRange, ChartPinOptions } from '../types';
 import { LegendSnapshot } from '../runtime/chart-runtime';
 export type CartesianModelLegendItem<Id extends string> = LegendSnapshot['series'][number] & {
     id: Id;
@@ -63,7 +63,7 @@ export interface CartesianSummaryResult<Id extends string> {
 export interface CartesianModelActions<SeriesId extends string> {
     readonly inspect: (x: number) => void;
     readonly clearInspection: () => void;
-    readonly pin: (x: number) => void;
+    readonly pin: (x: number, options?: ChartPinOptions) => void;
     readonly release: () => void;
     readonly setVisibleSeries: (ids: readonly SeriesId[]) => void;
     readonly focusSeries: (id: SeriesId | null) => void;
@@ -94,7 +94,7 @@ export interface CartesianChartModel<Row, SeriesId extends string> {
 type ModelActions = {
     inspect: (x: number) => void;
     clearInspection: () => void;
-    pin: (x: number) => void;
+    pin: (x: number, options?: ChartPinOptions) => void;
     release: () => void;
     setVisibleSeries: (ids: readonly string[]) => void;
     focusSeries: (id: string | null) => void;

package/dist/primitives/annotations.d.ts

@@ -1,4 +1,4 @@
 import { ReactElement } from 'react';
 import { AnnotationsProps, ReferenceBandProps } from '../types';
 export declare function Annotations({ items, onSelectionChange, className, }: AnnotationsProps): ReactElement;
-export declare function ReferenceBand({ from, to, label, color, className, }: ReferenceBandProps): ReactElement;
+export declare function ReferenceBand({ from, to, label, color, axis, className, }: ReferenceBandProps): ReactElement;

package/dist/primitives/axis-segments.d.ts

@@ -0,0 +1,23 @@
+import { ReactElement } from 'react';
+import { MotionValue } from 'motion/react';
+/** One stop of a segmented axis gradient, low values first. */
+export interface AxisGradientStop {
+    color: string;
+    opacity?: number;
+}
+/**
+ * A segmented axis: rounded segments between ticks instead of one continuous line, with a gap at
+ * each tick. With a gradient, one scale runs the length of the axis, low values first, so the
+ * axis reads as a range; the segment under the pointer lights up.
+ */
+export declare function AxisSegments({ stops, cross, vertical, gradient, cursor, active, opacity, }: {
+    /** Pixel positions that bound the segments, in any order. */
+    stops: readonly number[];
+    /** Where the segments sit across the axis: x for a vertical axis, y for a horizontal one. */
+    cross: number;
+    vertical: boolean;
+    gradient: readonly AxisGradientStop[] | null;
+    cursor: MotionValue<number>;
+    active: MotionValue<number>;
+    opacity?: number;
+}): ReactElement | null;

package/dist/primitives/box-plot.d.ts

@@ -0,0 +1,4 @@
+import { ReactElement } from 'react';
+import { BoxPlotProps } from '../types';
+/** Quartile boxes with a median line and whiskers; the series value is the median. */
+export declare const BoxPlot: (props: BoxPlotProps) => ReactElement;

package/dist/primitives/error-bar.d.ts

@@ -0,0 +1,4 @@
+import { ReactElement } from 'react';
+import { ErrorBarProps } from '../types';
+/** Whiskers from one field to another around each value, such as a measurement's uncertainty. */
+export declare const ErrorBar: (props: ErrorBarProps) => ReactElement;

package/dist/primitives/interval-band.d.ts

@@ -1,4 +1,4 @@
 import { ReactElement } from 'react';
 import { IntervalBandProps } from '../types';
-/** A supplied lower/upper envelope in the descriptor's own unit. */
-export declare function IntervalBand({ series, className }: IntervalBandProps): ReactElement;
+/** A supplied envelope between two of a line series' fields, e.g. a forecast's low and high. */
+export declare const IntervalBand: (props: IntervalBandProps) => ReactElement;

package/dist/primitives/range-bar.d.ts

@@ -0,0 +1,4 @@
+import { ReactElement } from 'react';
+import { RangeBarProps } from '../types';
+/** A floating bar per observation, from one field to another, such as a low to a high. */
+export declare const RangeBar: (props: RangeBarProps) => ReactElement;