@lilt-ui/charts 0.4.0 → 0.6.0

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

@@ -0,0 +1,11 @@
+import { ReactElement } from 'react';
+/** The largest positive value a `bars` legend measures against, or null when there is none. */
+export declare function legendMeterScale(values: readonly (number | null)[]): number | null;
+/**
+ * A thin bar under a legend value, as long as the value against the largest one shown. Missing,
+ * zero and negative values draw an empty track rather than a false sliver.
+ */
+export declare function LegendMeter({ value, scale, }: {
+    value: number | null;
+    scale: number | null;
+}): ReactElement;

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

@@ -1,4 +1,5 @@
 import { CSSProperties, ReactNode } from 'react';
+import { CardLegend, ChartLegendSwatch, ChartLegendVariant } from '../types';
 export interface ValueLegendEntry {
     id: string;
     label: string;
@@ -6,9 +7,14 @@ export interface ValueLegendEntry {
     value: number | null;
     formattedValue: string;
 }
+/** The legend layout a card's `legend` prop names: its value tiles are the `cards` layout. */
+export declare const cardLegendVariant: (legend: CardLegend) => ChartLegendVariant;
 export interface ValueLegendProps<Entries extends readonly ValueLegendEntry[]> {
     items: Entries;
-    variant?: 'cards' | 'inline';
+    /** `cards` (default), `inline`, `list`, `pills`, or `bars`. */
+    variant?: ChartLegendVariant;
+    /** The mark beside each label: `square` (default), `dot`, or `line`. */
+    swatch?: ChartLegendSwatch;
     activeId?: NoInfer<Entries[number]['id']> | null;
     selectedId?: NoInfer<Entries[number]['id']> | null;
     onHoverIdChange?: (id: NoInfer<Entries[number]['id']> | null) => void;
@@ -29,4 +35,4 @@ export interface ValueLegendProps<Entries extends readonly ValueLegendEntry[]> {
     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;
+export declare function ValueLegend<const Entries extends readonly ValueLegendEntry[]>({ items, variant, swatch, 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/lifecycle/loading-layer.d.ts

@@ -1,5 +1,7 @@
 import { ReactElement } from 'react';
-import { ChartAxisStyle } from '../types';
+import { ChartAxisStyle, ChartBarAppearance, ChartLoadingStyle } from '../types';
+import { LoadingMark } from '../marks/contract';
+export { skeletonClock, SKELETON_CYCLE } from './use-skeleton-clock';
 export interface LoadingLayerProps {
     width: number;
     height: number;
@@ -12,17 +14,26 @@ export interface LoadingLayerProps {
     reducedMotion: boolean;
     id: string;
     /** The marks the skeleton stands in for. */
-    marks?: 'line' | 'bars' | 'area-stack' | 'bar-stack';
+    marks?: 'line' | 'bars' | 'area-stack' | 'bar-stack' | 'columns';
+    mark?: LoadingMark;
     compact?: boolean;
     barCount?: number;
     seriesCount?: number;
+    barAppearances?: readonly ChartBarAppearance[];
+    barWidth?: number;
     showLine?: boolean;
+    lineDepth?: 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;
+    /**
+     * How the skeleton moves: `shimmer` (default) sweeps a highlight over still shapes, `draw`
+     * reveals bars or contours in order, and `breathe` lets them rise and settle.
+     */
+    loadingStyle?: ChartLoadingStyle;
 }
 export declare const SKELETON_CONTOUR: number[];
 export interface SkeletonGeometry {
@@ -35,4 +46,4 @@ export interface SkeletonGeometry {
     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;
+export declare function LoadingLayer({ width, height, left, right, top, bottom, visible, opacity, reducedMotion, id, marks, mark, compact, barCount, seriesCount, barAppearances, barWidth, showLine, lineDepth, axis, inset: labelInset, edge, loadingStyle, }: LoadingLayerProps): ReactElement | null;

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

@@ -0,0 +1,6 @@
+/** A neutral HTML bar; its container chooses motion and flat or solid paint. */
+export declare function SkeletonBlock({ width, height, step, }: {
+    width?: string;
+    height?: number;
+    step?: number;
+}): import("react/jsx-runtime").JSX.Element;

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

@@ -1,7 +1,19 @@
 import { ReactNode } from 'react';
+import { ChartLoadingStyle } from '../types';
+export declare const SKELETON_INK = "color-mix(in srgb, var(--lilt-skeleton) 64%, var(--lilt-surface))";
 export interface SkeletonSheenProps {
     /** The skeleton shapes. Their CSS paints them with `--lilt-skeleton-paint`. */
     children: ReactNode;
+    /** A plain silhouette when shaded children contain their own SVG definitions. */
+    mask?: ReactNode;
+    /**
+     * For rings: a white path with `pathLength={1}`, `strokeDasharray="1"`, and the
+     * `lilt-skeleton__sweep` class. Drawing sweeps it round; breathing fills and empties part of
+     * it. Other skeletons move each mark on its own with `data-skeleton` (see loading.css).
+     */
+    sweep?: ReactNode;
+    loadingStyle?: ChartLoadingStyle;
+    depth?: boolean;
     /** The area the sheen sweeps across, in the SVG's own units. */
     width: number;
     height: number;
@@ -13,6 +25,7 @@ export interface SkeletonSheenProps {
 /**
  * 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.
+ * the sheen lights only the placeholder and never the space around it. With `draw` or `breathe`
+ * the highlight gives way to the marks' own motion.
  */
-export declare function SkeletonSheen({ children, width, height, x, y, reduced, }: SkeletonSheenProps): import("react/jsx-runtime").JSX.Element;
+export declare function SkeletonSheen({ children, mask, sweep, loadingStyle, depth, width, height, x, y, reduced, }: SkeletonSheenProps): import("react/jsx-runtime").JSX.Element;

package/dist/lifecycle/use-skeleton-clock.d.ts

@@ -0,0 +1,5 @@
+import { ChartLoadingStyle } from '../types';
+export declare const SKELETON_CYCLE = 2800;
+export declare function skeletonClock(now: number): string;
+/** Read the shared wall clock after hydration, including when the selected style changes. */
+export declare function useSkeletonClock<Element extends HTMLElement | SVGElement>(active: boolean, style: ChartLoadingStyle): import('react').RefObject<Element | null>;

package/dist/marks/contract.d.ts

@@ -2,6 +2,19 @@ import { ReactElement, ReactNode } from 'react';
 import { ChartSnapshot } from '../chart-context';
 import { NormalizedRow } from '../engine/normalize';
 import { ChartSeries } from '../types';
+import { RangeScales } from '../engine/ranges';
+/** A neutral column uses the mark's own geometry, never an accepted observation. */
+export interface LoadingMark {
+    kind: string;
+    depth?: boolean;
+    render: (input: {
+        cx: number;
+        low: number;
+        high: number;
+        scales: RangeScales;
+        mask: boolean;
+    }) => ReactNode;
+}
 /**
  * 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.
@@ -17,6 +30,7 @@ export interface MarkSpec<P> {
     series: (props: P) => string;
     /** Field IDs the mark reads from its series. */
     fields: (props: P) => readonly string[];
+    loading?: (props: P) => LoadingMark;
     /** Draws one observation emphasized, over the dimmed marks, while it is inspected. */
     highlight?: (props: P, input: MarkHighlightInput) => ReactNode;
 }
@@ -31,6 +45,7 @@ export interface PlotMark {
     series: string;
     layout: MarkSpec<unknown>['layout'];
     fields: readonly string[];
+    loading?: LoadingMark;
     highlight?: (input: MarkHighlightInput) => ReactNode;
 }
 export declare function defineMark<P>(component: (props: P) => ReactElement, spec: MarkSpec<P>): (props: P) => ReactElement;

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

@@ -0,0 +1,3 @@
+import { LoadingMark } from './contract';
+/** Range placeholders draw through the same geometry as the measured marks. */
+export declare function rangeLoadingMark(kind: 'range' | 'error' | 'boxplot', depth?: boolean): LoadingMark;

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

@@ -11,6 +11,14 @@ export interface RangeMarkState {
     /** The reveal mask while the entrance sweeps in. */
     mask: string | undefined;
     clipPath: string;
+    /** Like `clipPath`, with headroom above the plot for the tops of marks drawn with depth. */
+    depthClip: {
+        id: string;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
     reducedMotion: boolean;
     inspecting: boolean;
 }

package/dist/primitives/depth-paint.d.ts

@@ -0,0 +1,107 @@
+import { ReactElement, SVGProps } from 'react';
+/** Positive lightens toward white, negative darkens toward black, in oklab to keep chroma. */
+export declare const shade: (color: string, amount: number) => string;
+/**
+ * Gradient stops through `[offset, shade]` keys, eased between each pair. Linear ramps between
+ * a few stops leave visible bands where the slope changes; smoothstep keeps every join soft.
+ */
+export declare function ramp(color: string, keys: readonly (readonly [number, number])[]): import("react/jsx-runtime").JSX.Element[];
+/** Flat face colors for marks drawn in batches, where one gradient per shape would cost too much. */
+export declare const prismShades: (color: string) => {
+    front: string;
+    top: string;
+    side: string;
+};
+/** Batched prism faces: every side, then every top, then every front, each in its own shade. */
+export declare function PrismPaths({ batches, front, }: {
+    batches: {
+        sides: {
+            entries(): {
+                color: string;
+                d: string;
+            }[];
+        };
+        tops: {
+            entries(): {
+                color: string;
+                d: string;
+            }[];
+        };
+        fronts: {
+            entries(): {
+                color: string;
+                d: string;
+            }[];
+        };
+    };
+    /** Front paint for a color; defaults to the color itself. */
+    front?: (color: string) => SVGProps<SVGPathElement>;
+}): ReactElement;
+/** A clip with headroom for the tops of marks drawn with depth. */
+export declare function DepthClip({ clip, }: {
+    clip: {
+        id: string;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}): ReactElement;
+export interface TubeLayer {
+    strokeWidth: number;
+    /** Shade applied to the band's color, as in `shade`. */
+    amount: number;
+    transform: string;
+}
+/**
+ * The cross-section of a band lit as a tube or a groove, as stacked strokes of its centerline:
+ * the full width first, then ever narrower strokes moved toward the light. Every layer stays
+ * inside the full stroke, round caps included, so the band's outline never changes: a ring,
+ * arc, or progress track keeps its exact angle and length.
+ *
+ * A `tube` bulges toward the reader: a shaded rim, a lit crown, and a narrow highlight toward
+ * the upper left. A `groove` is cut into the card: its upper-left wall is in shadow.
+ */
+export declare function tubeLayers(width: number, kind?: 'tube' | 'groove', 
+/** Where the light falls from, as a unit vector; the upper left by default. */
+light?: readonly [number, number]): TubeLayer[];
+/** A soft shadow under a drawing lit from the upper left, lifting it off the card. */
+export declare function DropShadow({ id, size, region, }: {
+    id: string;
+    size: number;
+    /**
+     * The area the shadow may cover, in the SVG's units. Defaults to a margin around the shape,
+     * which is too tight for a thin, nearly flat line.
+     */
+    region?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}): ReactElement;
+/**
+ * A line drawn as a lit tube: every layer of `tubeLayers` along one path. The centerline stays
+ * the line's own path, so every point reads exactly where the flat line puts it.
+ */
+export declare function TubePath({ d, color, width, dasharray, opacity, pathLength, className, }: {
+    d: string;
+    color: string;
+    width: number;
+    dasharray?: string;
+    opacity?: number;
+    /** With `dasharray`, lets every layer draw along the line together, e.g. a loading pen. */
+    pathLength?: number;
+    /** Set on every layer. */
+    className?: string;
+}): ReactElement;
+/** The width a line takes as a tube: wide enough for its light to read. */
+export declare const tubeWidth: (lineWidth?: number) => number;
+/**
+ * A lit sphere for any circle, mapped to the circle's own bounds: a highlight toward the upper
+ * left, the series color through the middle, and shade at the far rim.
+ */
+export declare function SphereGradient({ id, color }: {
+    id: string;
+    color: string;
+}): ReactElement;

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

@@ -0,0 +1,18 @@
+import { barMarkPath, BarGeometry } from '../engine/bars';
+/**
+ * Paint only: the chart still measures, inspects, and animates the original bar geometry.
+ * One key light sits above, in front, and to the left: the roof is brightest, the front is lit
+ * and falls off toward the floor, and the side turns away into shade. Edges come from the faces
+ * meeting, never from stroked lines. `active` raises the light on the inspected bar.
+ */
+export declare function IsometricBar({ bar, mark, id, color, fill, fillOpacity, stroke, strokeWidth, active, }: {
+    bar: BarGeometry;
+    mark: Parameters<typeof barMarkPath>[1];
+    id: string;
+    color: string;
+    fill: string;
+    fillOpacity: number;
+    stroke?: string;
+    strokeWidth?: number;
+    active?: boolean;
+}): import("react/jsx-runtime").JSX.Element | null;