@lilt-ui/charts 0.2.0 → 0.4.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/inspection-layer.d.ts

@@ -2,6 +2,12 @@ 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;

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/interaction/use-category-state.d.ts

@@ -10,7 +10,9 @@ export declare function useAcceptedRows<R>(incoming: readonly R[] | null, status
 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;
+    glideRef: (node: Element | null) => void;
     bind: (id: string, index: number) => {
+        'data-glide-id': string;
         ref: (node: HTMLButtonElement | null) => void;
         tabIndex: number;
         'aria-pressed': boolean;

package/dist/interaction/use-touch-glide.d.ts

@@ -0,0 +1,26 @@
+/** How long a still finger rests before it glides in any direction instead of scrolling. */
+export declare const TOUCH_HOLD_MS = 320;
+/** How far a finger travels before it counts as a swipe rather than a tap. */
+export declare const TOUCH_SLOP = 8;
+export interface TouchGlideOptions<T> {
+    /** What sits under the finger: an item id, a spoke index, or null for empty glass. */
+    resolve: (clientX: number, clientY: number, root: Element) => T | null;
+    /** Called as the finger glides, and with null when the gesture ends without a lift. */
+    onGlide: (value: T | null) => void;
+    /** A glide lifted over an item: pin it. */
+    onLift?: (value: T | null) => void;
+    /** A tap with no glide. Leave unset where the item's own click already handles taps. */
+    onTap?: (value: T | null) => void;
+    disabled?: boolean;
+}
+/** Finds the nearest `data-glide-id` under a point, for families whose marks are elements. */
+export declare function glideTarget(clientX: number, clientY: number, root: Element): string | null;
+/**
+ * Touch for charts whose marks are separate elements, or are found by position. A finger has no
+ * hover and a touch stays with the element it first landed on, so this follows the point under
+ * the finger instead. A sideways swipe glides at once (the plot pans only vertically); a press and
+ * hold glides in any direction without scrolling the page; lifting after a glide pins.
+ *
+ * Returns a callback ref for the plot, so a plot that mounts after loading is still wired.
+ */
+export declare function useTouchGlide<T>(options: TouchGlideOptions<T>): (node: Element | null) => void;

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/motion/use-glide.d.ts

@@ -6,8 +6,12 @@ export interface GlideSpring {
 }
 /**
  * A motion value that springs to each target it is given and always lands exactly on it.
- * Every move is its own animation to a known destination, rather than a spring that follows
- * another value, so an interrupted gesture or a paused frame can never leave it resting short
- * of its target. A new target takes over from wherever the value is.
+ * Every move is its own glide to a known destination, rather than a spring that follows another
+ * value, so an interrupted gesture or a paused frame can never leave it resting short of its
+ * target. A new target takes over from wherever the value is, keeping its speed.
+ *
+ * The spring advances by at most one frame's time per frame. When the page stalls, such as while
+ * linked charts re-render together, the glide carries on from where it was instead of jumping
+ * ahead to where the clock says it should be.
  */
 export declare function useGlide(initial: number, spring: GlideSpring): readonly [MotionValue<number>, (to: number, instant?: boolean) => void];

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;