@lilt-ui/charts 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## 0.6.0
+
+Charts have three loading styles, with skeletons shaped for each family and refreshed palettes.
+
+### Loading
+
+- `loadingStyle` accepts `shimmer` (the default), `draw`, or `breathe` on charts and cards, including finance charts. `ChartLoadingStyle` is exported for typed consumers.
+- Loading skeletons follow each chart's geometry, including candles, range marks, rings, funnels, and flows. Moving skeletons share a clock so cards on a page move together.
+- Loading motion respects reduced-motion preferences and `motion="none"`; placeholders do not present invented readings as data.
+
+### Palettes
+
+- Iris uses violet, rose, and amber; Cobalt uses blue, cyan, and indigo; Emerald uses green, lime, and teal. Default series colors follow Iris, with matching light and dark palettes.
+
+## 0.5.0
+
+Every chart that can carry it gets depth with one prop, and legends come in five layouts.
+
+### Depth
+
+- `depth` gives a card depth. Every shape keeps its exact value; depth only adds light, shade and shadow, lit from the upper left.
+- Bars, stacks, Combo and stat card bars become square blocks with a lit top and a shaded side; the front keeps the measured height. `barStyle="isometric"` gives the same look.
+- Range bars, box plots and candle bodies become solid blocks. Box plot whiskers run through the middle of each block and the median wraps around it; candle wicks pass through the body.
+- Radial donuts, pies, half donuts and rings, Progress rings and the stat card ring are lit tubes, with tracks cut into the card as grooves. Angles stay exact.
+- Lines on Line, Area, Combo, stat card, Price, Indicator and Depth charts are lit tubes along their own path, with a soft shadow. Dashed references stay flat.
+- Scatter points are lit spheres; Slope draws a tube between two spheres, and dumbbells match.
+- The Funnel is a pipe: each stage shaded as a cylinder of its own thickness, with curved seams and rounded ends.
+- Sankey flows are lit pipes of their exact width and nodes are small blocks.
+- Heatmap cells are low tiles of one height; color alone still carries the value.
+- Horizontal Bar (`barStyle="isometric"`), the stat card meter and Order book levels are solid blocks; Activity Ring dots are small pucks.
+
+### Legends
+
+- Cards take `legend`: `tiles` (the default), `inline`, `list` rows, tinted `pills`, or `bars` that draw each value against the largest. Radial keeps its own `list` with shares.
+- `legendSwatch` sets the mark beside each label: `square` (the default), `dot`, or `line`.
+- `Legend` and `ValueLegend` take the same layouts as `variant`, and the marks as `swatch`.
+
+### Breaking
+
+- `OrderBook` names its level count `levels`; `depth` is the 3D switch on every card.
+
 ## 0.4.0
 
 Every chart works with a finger, and pins shared across linked charts glide from point to point.

package/dist/activity-ring.d.ts

@@ -1,5 +1,5 @@
 import { ReactNode } from 'react';
-import { ChartMotion } from './types';
+import { ChartLoadingStyle, ChartMotion } from './types';
 export interface ActivitySelection<Row> {
     hour: number;
     row: Row | null;
@@ -23,10 +23,13 @@ export interface ActivityRingProps<Row> {
     onSelectionChange?: (selection: ActivitySelection<Row> | null) => void;
     /** `loading` keeps showing the last accepted day until new data is ready. */
     status?: 'ready' | 'loading';
+    loadingStyle?: ChartLoadingStyle;
     /** A new key drops the accepted day and any selection. */
     resetKey?: string | number;
     motion?: ChartMotion;
     height?: number;
+    /** Turns each dot into a small puck with walls receding up and to the right. */
+    depth?: boolean;
     'aria-label': string;
     className?: string;
 }
@@ -40,5 +43,5 @@ export declare function activitySlots<Row>(data: readonly Row[], hour: (row: Row
  * The 24-hour dot ring inside `ActivityRingCard`: one column of dots per time slot, filled by
  * how much happened then. One tab stop; arrow keys step around the day and Enter pins a slot.
  */
-export declare function ActivityRing<Row>({ data, hour, value, maximum, bucketMinutes, dotDensity, unit, formatValue, center, onSelectionChange, status, resetKey, motion, height, className, 'aria-label': ariaLabel, }: ActivityRingProps<Row>): import("react/jsx-runtime").JSX.Element;
+export declare function ActivityRing<Row>({ data, hour, value, maximum, bucketMinutes, dotDensity, unit, formatValue, center, onSelectionChange, status, loadingStyle, resetKey, motion, height, depth, className, 'aria-label': ariaLabel, }: ActivityRingProps<Row>): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/cards/activity-ring-card.d.ts

@@ -1,5 +1,5 @@
 import { CSSProperties, ReactElement, ReactNode } from 'react';
-import { ChartMotion, ChartPalette, ChartStyle, ChartSurface } from '../types';
+import { ChartLoadingStyle, ChartMotion, ChartPalette, ChartStyle, ChartSurface } from '../types';
 import { CardRange } from './cartesian-card';
 import { NumericKey } from './keys';
 import { AnimatedNumberVariant } from '../motion/animated-number';
@@ -21,6 +21,8 @@ export interface ActivityRingCardProps<Row, Key extends NumericKey<Row>> {
     maximum?: number;
     /** How the resting headline sums up the day: `sum` (default), `mean`, or `max`. */
     aggregate?: ActivityAggregate;
+    /** Turns each dot into a small puck with walls receding up and to the right. */
+    depth?: boolean;
     /** Ring height in pixels, at least 180. Defaults to 280. */
     height?: number;
     /** Resting headline. Defaults to the `aggregate` of every recorded slot. */
@@ -45,6 +47,7 @@ export interface ActivityRingCardProps<Row, Key extends NumericKey<Row>> {
     numberStyle?: AnimatedNumberVariant;
     palette?: ChartPalette;
     loading?: boolean;
+    loadingStyle?: ChartLoadingStyle;
     /** `none` turns off decorative motion; reduced-motion users get this automatically. */
     motion?: ChartMotion;
     className?: string;
@@ -57,4 +60,4 @@ export declare function clockLabel(hour: number): string;
  * filled by how much happened then. Hovering or stepping around the ring reads each slot in the
  * headline; tiles name the busiest and quietest times.
  */
-export declare function ActivityRingCard<Row, const Key extends NumericKey<Row>>({ title, data: suppliedData, hour, value, bucketMinutes, unit, maximum: suppliedMaximum, aggregate, height, headline: suppliedHeadline, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, valueFormat, locale, formatValue: suppliedFormatValue, color, surface, badge, numberStyle, palette, loading, motion, className, style, }: ActivityRingCardProps<Row, Key>): ReactElement;
+export declare function ActivityRingCard<Row, const Key extends NumericKey<Row>>({ title, data: suppliedData, hour, value, bucketMinutes, unit, maximum: suppliedMaximum, aggregate, height, depth, headline: suppliedHeadline, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, valueFormat, locale, formatValue: suppliedFormatValue, color, surface, badge, numberStyle, palette, loading, loadingStyle, motion, className, style, }: ActivityRingCardProps<Row, Key>): ReactElement;

package/dist/cards/bar-chart-card.d.ts

@@ -22,13 +22,16 @@ export interface BarChartCardProps<Row, Key extends NumericKey<Row>> extends Car
     barWidth?: number;
     /**
      * How bars are drawn: `solid` (default), `segmented` into small cells, `needle` (thin segmented
-     * lines; the hovered bar expands), `gradient` fading toward the baseline, or `outline`.
+     * lines; the hovered bar expands), `gradient` fading toward the baseline, `outline`, or
+     * `isometric` with a shaded top and side around the measured front face.
      */
     barStyle?: ChartBarAppearance;
+    /** Shorthand for depth across every card family: here it makes `barStyle` default to `isometric`. */
+    depth?: boolean;
 }
 /**
  * A complete bar chart card: headline, delta, period, plot, and value tiles.
  * Dashed series draw as reference lines over the bars. Bars stay inside the card padding by
  * default, so every label centers on its bar.
  */
-export declare function BarChartCard<Row, const Key extends NumericKey<Row>>({ stack, radius, corners, tracks, barWidth, barStyle, ...props }: BarChartCardProps<Row, Key>): ReactElement;
+export declare function BarChartCard<Row, const Key extends NumericKey<Row>>({ stack, radius, corners, tracks, barWidth, depth, barStyle, ...props }: BarChartCardProps<Row, Key>): ReactElement;

package/dist/cards/box-plot-card.d.ts

@@ -21,10 +21,12 @@ export interface BoxPlotCardProps<Row> extends SharedProps<Row> {
     color?: string;
     /** Draw samples beyond the whiskers as dots. Defaults to true. */
     outliers?: boolean;
+    /** Draws each box as a solid block receding up and to the right; the front keeps Q1 and Q3. */
+    depth?: boolean;
 }
 /**
  * Distributions side by side: quartile boxes, a median line, Tukey whiskers and outliers,
  * computed from each row's raw samples. The headline is the median of every sample.
  */
-export declare function BoxPlotCard<Row>({ data, x, samples, label, color, outliers, headline, ...props }: BoxPlotCardProps<Row>): ReactElement;
+export declare function BoxPlotCard<Row>({ data, x, samples, label, color, outliers, depth, headline, ...props }: BoxPlotCardProps<Row>): ReactElement;
 export {};

package/dist/cards/cartesian-card.d.ts

@@ -1,5 +1,5 @@
 import { CSSProperties, ReactElement, ReactNode } from 'react';
-import { ChartController, ChartMargins, ChartTooltipContext, NumericXConfig, TimeXConfig, ChartAxis, ChartBarAppearance, ChartBackground, ChartCurve, ChartMotion, ChartPalette, ChartHoverReadout, ChartHoverStyle, ChartSeries, ChartTooltipIndicator, ChartStyle, ChartSurface } from '../types';
+import { ChartController, ChartMargins, ChartTooltipContext, NumericXConfig, TimeXConfig, ChartAxis, ChartBarAppearance, ChartBackground, ChartCurve, ChartMotion, ChartPalette, ChartHoverReadout, ChartHoverStyle, ChartSeries, ChartTooltipIndicator, ChartStyle, ChartSurface, CardLegend, ChartLegendSwatch, ChartLoadingStyle } from '../types';
 import { NumericKey, ResolvedX, XKey, XKind } from './keys';
 import { CardAggregate } from './format';
 import { AnimatedNumberVariant } from '../motion/animated-number';
@@ -84,8 +84,20 @@ export interface CartesianCardProps<Row, Key extends NumericKey<Row>> {
     /** Period select. Each range replaces data, delta and headline. */
     ranges?: readonly CardRange<Row>[];
     defaultRange?: string;
-    /** Per-series stat tiles under the plot. Defaults to true. */
+    /** Per-series stat tiles under the plot. Defaults to true; false hides the legend. */
     tiles?: boolean;
+    /**
+     * How the legend under the plot lays out: value `tiles` (default), compact `inline` labels,
+     * `list` rows, tinted `pills`, or `bars` that also draw each value against the largest.
+     */
+    legend?: CardLegend;
+    /** The mark beside each legend label: `square` (default), `dot`, or `line`. */
+    legendSwatch?: ChartLegendSwatch;
+    /**
+     * Gives the plot depth: lines become lit tubes with a soft shadow, and bar cards draw
+     * `isometric` blocks. Every point and bar still reads its exact value.
+     */
+    depth?: boolean;
     /** Plot height in pixels. Defaults to 240. */
     height?: number;
     /** Number format for the headline, tiles, and axis, e.g. `{ style: 'currency', currency: 'USD' }`. */
@@ -172,6 +184,12 @@ export interface CartesianCardProps<Row, Key extends NumericKey<Row>> {
      */
     sync?: string;
     loading?: boolean;
+    /**
+     * How the skeleton moves while `loading`: `shimmer` (default) sweeps a highlight over still
+     * shapes, `draw` reveals bars or contours in order, `breathe` lets them rise and settle.
+     * Moving skeletons on a page share a clock.
+     */
+    loadingStyle?: ChartLoadingStyle;
     /** `none` turns off decorative motion; reduced-motion users get this automatically. */
     motion?: ChartMotion;
     className?: string;
@@ -246,6 +264,7 @@ export interface CardMarks {
 }
 /** Panes drawn under the main plot, linked to it: same data, x, margins and crosshair. */
 export interface CardPaneContext<Row> {
+    loadingStyle?: ChartLoadingStyle;
     data: readonly Row[];
     x: TimeXConfig<Row> | NumericXConfig<Row>;
     controller: ChartController;
@@ -266,7 +285,7 @@ export declare const CARD_PADDING = 20;
  * The shared card body: headline, delta, period, plot, and value tiles, with hover sync and
  * range comparison. Area, Line, and Bar cards differ only in their `shape`.
  */
-export declare function CartesianCard<Row, Key extends NumericKey<Row>>({ shape, title, data: suppliedData, x, series: seriesInput, headline: suppliedHeadline, aggregate: suppliedAggregate, headlineSeries, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, tiles, height, valueFormat, locale, formatValue: suppliedFormatValue, formatAxisValue: suppliedFormatAxisValue, formatX, xType, compare, target: suppliedTarget, forecast, sync, axis, hover, hoverStyle, background, spotlight, surface, badge, numberStyle, palette, bleed, axisInset, pillSeries, pillValue, pillPosition, tooltipIndicator, loading, motion, className, style, panes, live, heading, restCaption, normal, onNormalChange, }: Omit<CartesianCardProps<Row, Key>, 'series'> & {
+export declare function CartesianCard<Row, Key extends NumericKey<Row>>({ shape, title, data: suppliedData, x, series: seriesInput, headline: suppliedHeadline, aggregate: suppliedAggregate, headlineSeries, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, tiles, legend, legendSwatch, depth, height, valueFormat, locale, formatValue: suppliedFormatValue, formatAxisValue: suppliedFormatAxisValue, formatX, xType, compare, target: suppliedTarget, forecast, sync, axis, hover, hoverStyle, background, spotlight, surface, badge, numberStyle, palette, bleed, axisInset, pillSeries, pillValue, pillPosition, tooltipIndicator, loading, loadingStyle, motion, className, style, panes, live, heading, restCaption, normal, onNormalChange, }: Omit<CartesianCardProps<Row, Key>, 'series'> & {
     series: readonly CoreSeries<Key>[];
     shape: CardShape;
     /** Linked panes under the plot, such as volume or indicators. */

package/dist/cards/combo-chart-card.d.ts

@@ -36,8 +36,10 @@ export interface ComboChartCardProps<Row, Key extends NumericKey<Row>> extends O
     tracks?: boolean;
     /** Maximum bar width in pixels; bars never exceed their slot. */
     barWidth?: number;
-    /** `solid` (default), `segmented`, `needle`, `gradient`, or `outline`. */
+    /** `solid` (default), `segmented`, `needle`, `gradient`, `outline`, or `isometric`. */
     barStyle?: ChartBarAppearance;
+    /** Shorthand for depth across every card family: here it makes `barStyle` default to `isometric`. */
+    depth?: boolean;
     /** `smooth` (default) or `linear` line segments. */
     curve?: 'smooth' | 'linear';
     /** Mark every line observation with a small dot. Defaults to true. */
@@ -48,4 +50,4 @@ export interface ComboChartCardProps<Row, Key extends NumericKey<Row>> extends O
  * The headline totals the bars; every series gets a tile, and the pill reads whichever mark is
  * nearest the pointer.
  */
-export declare function ComboChartCard<Row, const Key extends NumericKey<Row>>({ bars, lines, lineScale, stack, radius, corners, tracks, barWidth, barStyle, curve, points, aggregate, pillPosition, ...props }: ComboChartCardProps<Row, Key>): ReactElement;
+export declare function ComboChartCard<Row, const Key extends NumericKey<Row>>({ bars, lines, lineScale, stack, radius, corners, tracks, barWidth, depth, barStyle, curve, points, aggregate, pillPosition, ...props }: ComboChartCardProps<Row, Key>): ReactElement;

package/dist/cards/funnel-chart-card.d.ts

@@ -1,5 +1,5 @@
 import { CSSProperties, ReactElement, ReactNode } from 'react';
-import { ChartMotion, ChartPalette, ChartStyle, ChartSurface } from '../types';
+import { ChartLoadingStyle, ChartMotion, ChartPalette, ChartStyle, ChartSurface, CardLegend, ChartLegendSwatch } from '../types';
 import { CardRange } from './cartesian-card';
 import { NumericKey, TextKey } from './keys';
 import { AnimatedNumberVariant } from '../motion/animated-number';
@@ -17,6 +17,11 @@ export interface FunnelChartCardProps<Row, Key extends NumericKey<Row>> {
     colors?: 'stages' | 'single';
     /** A quiet full-height lane behind each stage, marking where 100% sits. Defaults to false. */
     tracks?: boolean;
+    /**
+     * Gives the funnel depth: a pipe seen a little from the right, every stage shaded as a cylinder
+     * of its own thickness, with curved seams and elliptical ends. Band heights still read true.
+     */
+    depth?: boolean;
     /** Plot height in pixels. Defaults to 180. */
     height?: number;
     /** Resting headline. Defaults to the first stage. */
@@ -29,6 +34,13 @@ export interface FunnelChartCardProps<Row, Key extends NumericKey<Row>> {
     /** Period select. Each range replaces data, delta, and headline; bands ease to their new size. */
     ranges?: readonly CardRange<Row>[];
     defaultRange?: string;
+    /**
+     * How the legend lays out: value `tiles` (default), compact `inline` labels, `list` rows, tinted
+     * `pills`, or `bars` that also draw each value against the largest.
+     */
+    legend?: CardLegend;
+    /** The mark beside each legend label: `square` (default), `dot`, or `line`. */
+    legendSwatch?: ChartLegendSwatch;
     valueFormat?: Intl.NumberFormatOptions;
     locale?: string;
     formatValue?: (value: number) => string;
@@ -41,6 +53,7 @@ export interface FunnelChartCardProps<Row, Key extends NumericKey<Row>> {
     numberStyle?: AnimatedNumberVariant;
     palette?: ChartPalette;
     loading?: boolean;
+    loadingStyle?: ChartLoadingStyle;
     /** `none` turns off decorative motion; reduced-motion users get this automatically. */
     motion?: ChartMotion;
     className?: string;
@@ -54,9 +67,21 @@ export declare function stageShare(share: number | null): string;
  * stay level.
  */
 export declare function stagePath(index: number, height: number, next: number | null, curve: 'smooth' | 'linear'): string;
+/**
+ * Upright strips that tile one stage's band from left to right, each as tall as the band where
+ * it stands, so a gradient mapped to each strip shades the band like a cylinder of that local
+ * thickness. Strips overlap a little; the stage's own outline trims them.
+ */
+export declare function pipeStrips(index: number, height: number, next: number | null, curve: 'smooth' | 'linear'): {
+    x: number;
+    width: number;
+    half: number;
+}[];
+/** Half of a pipe's elliptical cross-section at `x`: the side facing `right` or left. */
+export declare function pipeEnd(x: number, half: number, rx: number, side: 'left' | 'right'): string;
 /**
  * A funnel card: stages left to right, each band sized by its share of the first stage, with
  * its percentage on the band and its count in a tile beneath. Hovering a stage reads it in the
  * headline with the conversion from the step before.
  */
-export declare function FunnelChartCard<Row, const Key extends NumericKey<Row>>({ title, data: suppliedData, category, value, curve, colors, tracks, height, headline: suppliedHeadline, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, valueFormat, locale, formatValue: suppliedFormatValue, color, surface, badge, numberStyle, palette, loading, motion: motionMode, className, style, }: FunnelChartCardProps<Row, Key>): ReactElement;
+export declare function FunnelChartCard<Row, const Key extends NumericKey<Row>>({ title, data: suppliedData, category, value, curve, colors, tracks, depth, height, headline: suppliedHeadline, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, valueFormat, legend, legendSwatch, locale, formatValue: suppliedFormatValue, color, surface, badge, numberStyle, palette, loading, loadingStyle, motion: motionMode, className, style, }: FunnelChartCardProps<Row, Key>): ReactElement;

package/dist/cards/heatmap-chart-card.d.ts

@@ -1,5 +1,5 @@
 import { CSSProperties, ReactElement, ReactNode } from 'react';
-import { ChartMotion, ChartPalette, ChartStyle, ChartSurface } from '../types';
+import { ChartLoadingStyle, ChartMotion, ChartPalette, ChartStyle, ChartSurface } from '../types';
 import { CardRange } from './cartesian-card';
 import { NumericKey, TextKey } from './keys';
 import { AnimatedNumberVariant } from '../motion/animated-number';
@@ -32,6 +32,11 @@ export interface HeatmapChartCardProps<Row, Key extends NumericKey<Row>> {
     radius?: number;
     /** Space between cells in pixels. Defaults to 4. */
     gap?: number;
+    /**
+     * Raises every cell as a cushioned tile with a lit top edge and a soft shadow. All tiles share
+     * one height: color still carries the value.
+     */
+    depth?: boolean;
     /** Resting headline. Defaults to the `aggregate` of every known cell. */
     headline?: number;
     /** Fractional change shown as a chip, e.g. 0.052 → +5.2%. */
@@ -54,6 +59,7 @@ export interface HeatmapChartCardProps<Row, Key extends NumericKey<Row>> {
     numberStyle?: AnimatedNumberVariant;
     palette?: ChartPalette;
     loading?: boolean;
+    loadingStyle?: ChartLoadingStyle;
     /** `none` turns off decorative motion; reduced-motion users get this automatically. */
     motion?: ChartMotion;
     className?: string;
@@ -104,4 +110,4 @@ export declare function labelTier(index: number, count: number): 'major' | 'mino
  * labeled. Hovering or focusing a cell reads it in the headline; arrow keys move between cells.
  * Missing cells are hatched and say "No data", so they never read as zero.
  */
-export declare function HeatmapChartCard<Row, const Key extends NumericKey<Row>>({ title, data: suppliedData, x, y, value, columns, rows: rowOrder, domain, aggregate, height, radius, gap, headline: suppliedHeadline, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, valueFormat, locale, formatValue: suppliedFormatValue, color, surface, badge, numberStyle, palette, loading, motion: motionMode, className, style, }: HeatmapChartCardProps<Row, Key>): ReactElement;
+export declare function HeatmapChartCard<Row, const Key extends NumericKey<Row>>({ title, data: suppliedData, x, y, value, columns, rows: rowOrder, domain, aggregate, height, radius, gap, depth, headline: suppliedHeadline, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, valueFormat, locale, formatValue: suppliedFormatValue, color, surface, badge, numberStyle, palette, loading, loadingStyle, motion: motionMode, className, style, }: HeatmapChartCardProps<Row, Key>): ReactElement;

package/dist/cards/horizontal-bar-chart-card.d.ts

@@ -1,5 +1,5 @@
 import { CSSProperties, ReactElement, ReactNode } from 'react';
-import { ChartMotion, ChartPalette, ChartStyle, ChartSurface, RankingOrder } from '../types';
+import { ChartLoadingStyle, ChartMotion, ChartPalette, ChartStyle, ChartSurface, RankingOrder } from '../types';
 import { CardRange } from './cartesian-card';
 import { NumericKey, TextKey } from './keys';
 import { AnimatedNumberVariant } from '../motion/animated-number';
@@ -33,9 +33,13 @@ export interface HorizontalBarChartCardProps<Row, Key extends NumericKey<Row>> {
     /** Number each row by rank. Defaults to false. */
     rank?: boolean;
     /**
-     * `inline` (default) sets each label on a soft bar; `track` draws a slim bar under the label.
+     * `inline` (default) sets each label on a soft bar; `track` draws a slim bar under the label;
+     * `isometric` draws a solid block under the label whose front ends at the value, with a lit
+     * roof and a shaded end receding behind it.
      */
-    barStyle?: 'inline' | 'track';
+    barStyle?: 'inline' | 'track' | 'isometric';
+    /** Shorthand for depth across every card family: here it makes `barStyle` default to `isometric`. */
+    depth?: boolean;
     valueFormat?: Intl.NumberFormatOptions;
     locale?: string;
     formatValue?: (value: number) => string;
@@ -48,6 +52,7 @@ export interface HorizontalBarChartCardProps<Row, Key extends NumericKey<Row>> {
     numberStyle?: AnimatedNumberVariant;
     palette?: ChartPalette;
     loading?: boolean;
+    loadingStyle?: ChartLoadingStyle;
     /** `none` turns off decorative motion; reduced-motion users get this automatically. */
     motion?: ChartMotion;
     className?: string;
@@ -57,4 +62,4 @@ export interface HorizontalBarChartCardProps<Row, Key extends NumericKey<Row>> {
  * A ranked list card: each row carries a bar, its value, and its share of the total. Hovering a
  * row reads it in the headline; click pins it and the arrow keys move through the list.
  */
-export declare function HorizontalBarChartCard<Row, const Key extends NumericKey<Row>>({ title, data: suppliedData, category, value, headline: suppliedHeadline, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, sort, limit, otherLabel, share, rank, barStyle, valueFormat, locale, formatValue: suppliedFormatValue, color, surface, badge, numberStyle, palette, loading, motion: motionMode, className, style, }: HorizontalBarChartCardProps<Row, Key>): ReactElement;
+export declare function HorizontalBarChartCard<Row, const Key extends NumericKey<Row>>({ title, data: suppliedData, category, value, headline: suppliedHeadline, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, sort, limit, otherLabel, share, rank, depth, barStyle, valueFormat, locale, formatValue: suppliedFormatValue, color, surface, badge, numberStyle, palette, loading, loadingStyle, motion: motionMode, className, style, }: HorizontalBarChartCardProps<Row, Key>): ReactElement;

package/dist/cards/progress-card.d.ts

@@ -1,6 +1,6 @@
 import { CSSProperties, ReactElement, ReactNode } from 'react';
 import { AnimatedNumberVariant } from '../motion/animated-number';
-import { ChartMotion, ChartPalette, ChartStyle, ChartSurface } from '../types';
+import { ChartLoadingStyle, ChartMotion, ChartPalette, ChartStyle, ChartSurface } from '../types';
 export interface ProgressRange {
     id: string;
     label: string;
@@ -22,6 +22,11 @@ export interface ProgressCardProps {
      * a half ring that opens downward.
      */
     variant?: 'ring' | 'thick' | 'gauge';
+    /**
+     * Gives the ring depth: the fill is lit as a tube and the track becomes a groove. The arc keeps
+     * its exact angle.
+     */
+    depth?: boolean;
     /** Fractional change shown as a chip, e.g. 0.052 → +5.2%. */
     delta?: number;
     deltaTone?: 'default' | 'inverse' | 'neutral';
@@ -44,6 +49,7 @@ export interface ProgressCardProps {
     numberStyle?: AnimatedNumberVariant;
     palette?: ChartPalette;
     loading?: boolean;
+    loadingStyle?: ChartLoadingStyle;
     motion?: ChartMotion;
     className?: string;
     style?: CSSProperties | ChartStyle;
@@ -52,4 +58,4 @@ export interface ProgressCardProps {
  * One value against a goal: the value in the header, and a large ring or gauge with the
  * percentage reached. Past the goal the ring stays full and the percentage keeps counting.
  */
-export declare function ProgressCard({ title, value: suppliedValue, target: suppliedTarget, label, variant, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, footer, valueFormat, locale, formatValue, color, surface, badge, numberStyle, palette, loading, motion: motionMode, className, style, }: ProgressCardProps): ReactElement;
+export declare function ProgressCard({ title, value: suppliedValue, target: suppliedTarget, label, variant, depth, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, footer, valueFormat, locale, formatValue, color, surface, badge, numberStyle, palette, loading, loadingStyle, motion: motionMode, className, style, }: ProgressCardProps): ReactElement;

package/dist/cards/radar-chart-card.d.ts

@@ -1,5 +1,5 @@
 import { CSSProperties, ReactElement, ReactNode } from 'react';
-import { ChartMotion, ChartPalette, ChartStyle, ChartSurface } from '../types';
+import { ChartLoadingStyle, ChartMotion, ChartPalette, ChartStyle, ChartSurface, CardLegend, ChartLegendSwatch } from '../types';
 import { CardRange, CardSeries } from './cartesian-card';
 import { NumericKey, TextKey } from './keys';
 import { AnimatedNumberVariant } from '../motion/animated-number';
@@ -34,6 +34,13 @@ export interface RadarChartCardProps<Row, Key extends NumericKey<Row>> {
     /** Period select. Each range replaces data, delta, and headline; profiles ease to their shape. */
     ranges?: readonly CardRange<Row>[];
     defaultRange?: string;
+    /**
+     * How the legend lays out: value `tiles` (default), compact `inline` labels, `list` rows, tinted
+     * `pills`, or `bars` that also draw each value against the largest.
+     */
+    legend?: CardLegend;
+    /** The mark beside each legend label: `square` (default), `dot`, or `line`. */
+    legendSwatch?: ChartLegendSwatch;
     valueFormat?: Intl.NumberFormatOptions;
     locale?: string;
     formatValue?: (value: number) => string;
@@ -44,6 +51,7 @@ export interface RadarChartCardProps<Row, Key extends NumericKey<Row>> {
     numberStyle?: AnimatedNumberVariant;
     palette?: ChartPalette;
     loading?: boolean;
+    loadingStyle?: ChartLoadingStyle;
     /** `none` turns off decorative motion; reduced-motion users get this automatically. */
     motion?: ChartMotion;
     className?: string;
@@ -89,5 +97,5 @@ export declare function profilePath(fractions: readonly (number | null)[], radiu
  * shape of strengths and gaps reads at a glance. Hovering or stepping around the spokes reads
  * every profile at that dimension.
  */
-export declare function RadarChartCard<Row, const Key extends NumericKey<Row>>({ title, data: suppliedData, category, series, domain: suppliedDomain, aggregate, grid, height, headline: suppliedHeadline, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, valueFormat, locale, formatValue: suppliedFormatValue, surface, badge, numberStyle, palette, loading, motion: motionMode, className, style, }: RadarChartCardProps<Row, Key>): ReactElement;
+export declare function RadarChartCard<Row, const Key extends NumericKey<Row>>({ title, data: suppliedData, category, series, domain: suppliedDomain, aggregate, grid, height, headline: suppliedHeadline, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, valueFormat, legend, legendSwatch, locale, formatValue: suppliedFormatValue, surface, badge, numberStyle, palette, loading, loadingStyle, motion: motionMode, className, style, }: RadarChartCardProps<Row, Key>): ReactElement;
 export {};

package/dist/cards/radial-chart-card.d.ts

@@ -1,5 +1,5 @@
 import { CSSProperties, ReactElement, ReactNode } from 'react';
-import { ChartMotion, ChartPalette, ChartStyle, ChartSurface, RankingOrder } from '../types';
+import { ChartMotion, ChartLoadingStyle, ChartPalette, ChartStyle, ChartSurface, RankingOrder, CardLegend, ChartLegendSwatch } from '../types';
 import { CardRange } from './cartesian-card';
 import { NumericKey, TextKey } from './keys';
 import { RankedRow } from './rank';
@@ -19,10 +19,19 @@ export interface RadialChartCardProps<Row, Key extends NumericKey<Row>> {
      */
     variant?: RadialChartCardVariant;
     /**
-     * `list` rows with value and share, value `tiles`, or an `inline` key. Defaults to tiles for
-     * rings, inline for semi, and list otherwise.
+     * Gives the chart depth: every band is lit as a tube from the upper left, ring tracks become
+     * grooves, and a soft shadow lifts the chart off the card. Outlines keep their exact angles,
+     * so shares read the same as the flat chart.
      */
-    legend?: 'list' | 'tiles' | 'inline';
+    depth?: boolean;
+    /**
+     * `list` rows with value and share, value `tiles`, an `inline` key, tinted `pills`, or `bars`
+     * that also draw each value against the largest. Defaults to tiles for rings, inline for semi,
+     * and list otherwise.
+     */
+    legend?: CardLegend;
+    /** The mark beside each legend label: `square` (default), `dot`, or `line`. */
+    legendSwatch?: ChartLegendSwatch;
     /** Resting headline. Defaults to the total of every slice. */
     headline?: number;
     /** Fractional change shown as a chip, e.g. 0.082 → +8.2%. */
@@ -52,6 +61,8 @@ export interface RadialChartCardProps<Row, Key extends NumericKey<Row>> {
     numberStyle?: AnimatedNumberVariant;
     palette?: ChartPalette;
     loading?: boolean;
+    /** Shimmer (default), a clockwise draw, or a gentle pulse. Honors reduced motion. */
+    loadingStyle?: ChartLoadingStyle;
     /** `none` turns off decorative motion; reduced-motion users get this automatically. */
     motion?: ChartMotion;
     className?: string;
@@ -75,5 +86,5 @@ export declare function ringAngles(rows: readonly RankedRow[]): Slice[];
  * A donut or pie card: the headline total, slices with a matching legend, and each slice's
  * share. Hovering a slice or a legend row reads it in the headline.
  */
-export declare function RadialChartCard<Row, const Key extends NumericKey<Row>>({ title, data: suppliedData, category, value, variant, legend, headline: suppliedHeadline, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, limit, otherLabel, sort, valueFormat, locale, formatValue: suppliedFormatValue, surface, badge, numberStyle, palette, loading, motion: motionMode, className, style, }: RadialChartCardProps<Row, Key>): ReactElement;
+export declare function RadialChartCard<Row, const Key extends NumericKey<Row>>({ title, data: suppliedData, category, value, variant, depth, legend, legendSwatch, headline: suppliedHeadline, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, limit, otherLabel, sort, valueFormat, locale, formatValue: suppliedFormatValue, surface, badge, numberStyle, palette, loading, loadingStyle, motion: motionMode, className, style, }: RadialChartCardProps<Row, Key>): ReactElement;
 export {};

package/dist/cards/range-chart-card.d.ts

@@ -17,6 +17,8 @@ export interface RangeChartCardProps<Row, Key extends NumericKey<Row>> extends S
     color?: string;
     /** `bar` (default) floats a bar from low to high; `error` draws whiskers around the value. */
     display?: 'bar' | 'error';
+    /** Draws each bar as a solid block receding up and to the right. Error bars stay flat. */
+    depth?: boolean;
     /** Per-series stat tile under the plot. Defaults to false. */
     tiles?: boolean;
 }
@@ -24,5 +26,5 @@ export interface RangeChartCardProps<Row, Key extends NumericKey<Row>> extends S
  * Ranges per observation: floating bars from low to high, or error bars around a value. The
  * headline summarizes the values (the mean by default) and hover reads the range's ends.
  */
-export declare function RangeChartCard<Row, const Key extends NumericKey<Row>>({ low, high, value, label, color, display, aggregate, tiles, ...props }: RangeChartCardProps<Row, Key>): ReactElement;
+export declare function RangeChartCard<Row, const Key extends NumericKey<Row>>({ low, high, value, label, color, display, depth, aggregate, tiles, ...props }: RangeChartCardProps<Row, Key>): ReactElement;
 export {};

package/dist/cards/sankey-chart-card.d.ts

@@ -1,6 +1,6 @@
 import { CSSProperties, ReactElement, ReactNode } from 'react';
 import { SankeyGraph, SankeyLink, SankeyNode } from '../engine/sankey';
-import { ChartMotion, ChartPalette, ChartStyle, ChartSurface } from '../types';
+import { ChartLoadingStyle, ChartMotion, ChartPalette, ChartStyle, ChartSurface } from '../types';
 import { CardRange } from './cartesian-card';
 import { NumericKey, TextKey } from './keys';
 import { AnimatedNumberVariant } from '../motion/animated-number';
@@ -20,6 +20,11 @@ export interface SankeyChartCardProps<Row, Key extends NumericKey<Row>> {
      */
     conservation?: 'loss' | 'strict';
     /** Plot height in pixels. Defaults to 280. */
+    /**
+     * Gives the diagram depth: flows become lit pipes and nodes small blocks. Flow widths and node
+     * heights stay exact.
+     */
+    depth?: boolean;
     height?: number;
     /** Resting headline. Defaults to everything entering the first steps. */
     headline?: number;
@@ -41,6 +46,7 @@ export interface SankeyChartCardProps<Row, Key extends NumericKey<Row>> {
     numberStyle?: AnimatedNumberVariant;
     palette?: ChartPalette;
     loading?: boolean;
+    loadingStyle?: ChartLoadingStyle;
     /** `none` turns off decorative motion; reduced-motion users get this automatically. */
     motion?: ChartMotion;
     className?: string;
@@ -65,5 +71,5 @@ export declare function sankeyGraph<Row>({ data, source, target, value, conserva
  * amount that moved. Hovering or stepping through flows with the arrow keys reads each in the
  * headline with its share of the step it left.
  */
-export declare function SankeyChartCard<Row, const Key extends NumericKey<Row>>({ title, data: suppliedData, source, target, value, conservation, height, headline: suppliedHeadline, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, valueFormat, locale, formatValue: suppliedFormatValue, surface, badge, numberStyle, palette, loading, motion: motionMode, className, style, }: SankeyChartCardProps<Row, Key>): ReactElement;
+export declare function SankeyChartCard<Row, const Key extends NumericKey<Row>>({ title, data: suppliedData, source, target, value, conservation, depth, height, headline: suppliedHeadline, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, valueFormat, locale, formatValue: suppliedFormatValue, surface, badge, numberStyle, palette, loading, loadingStyle, motion: motionMode, className, style, }: SankeyChartCardProps<Row, Key>): ReactElement;
 export {};

package/dist/cards/scatter-chart-card.d.ts

@@ -1,5 +1,5 @@
 import { CSSProperties, ReactElement, ReactNode } from 'react';
-import { ChartMotion, ChartPalette, ChartStyle, ChartSurface } from '../types';
+import { ChartLoadingStyle, ChartMotion, ChartPalette, ChartStyle, ChartSurface, CardLegend, ChartLegendSwatch } from '../types';
 import { CardRange } from './cartesian-card';
 import { NumericKey, TextKey } from './keys';
 import { AnimatedNumberVariant } from '../motion/animated-number';
@@ -26,6 +26,8 @@ export interface ScatterChartCardProps<Row, Key extends NumericKey<Row>> {
     yLabel?: string;
     /** A least-squares line through the points, with its r² in the footer. */
     trend?: boolean;
+    /** Draws each point as a lit sphere with a soft contact shadow; centers and sizes stay exact. */
+    depth?: boolean;
     /** Plot height in pixels, including the axes. Defaults to 260. */
     height?: number;
     /** How the resting headline sums up `y`: `sum` (default), `mean`, or `max`. */
@@ -40,6 +42,13 @@ export interface ScatterChartCardProps<Row, Key extends NumericKey<Row>> {
     /** Period select. Each range replaces data, delta, and headline; points glide to their place. */
     ranges?: readonly CardRange<Row>[];
     defaultRange?: string;
+    /**
+     * How the legend lays out: value `tiles` (default), compact `inline` labels, `list` rows, tinted
+     * `pills`, or `bars` that also draw each value against the largest.
+     */
+    legend?: CardLegend;
+    /** The mark beside each legend label: `square` (default), `dot`, or `line`. */
+    legendSwatch?: ChartLegendSwatch;
     /** Number format for `y`: the headline, legend, and y axis. */
     valueFormat?: Intl.NumberFormatOptions;
     /** Number format for `x`, e.g. `{ style: 'currency', currency: 'USD' }`. */
@@ -56,6 +65,7 @@ export interface ScatterChartCardProps<Row, Key extends NumericKey<Row>> {
     numberStyle?: AnimatedNumberVariant;
     palette?: ChartPalette;
     loading?: boolean;
+    loadingStyle?: ChartLoadingStyle;
     /** `none` turns off decorative motion; reduced-motion users get this automatically. */
     motion?: ChartMotion;
     className?: string;
@@ -88,4 +98,4 @@ export declare function clipTrend(fit: {
  * and colored by group. Hovering or stepping through points with the arrow keys reads each one in
  * the headline, with its position marked on both axes.
  */
-export declare function ScatterChartCard<Row, const Key extends NumericKey<Row>>({ title, data: suppliedData, x, y, size, sizeLabel, group, label, xLabel, yLabel, trend, height, aggregate, headline: suppliedHeadline, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, valueFormat, xFormat, locale, formatValue: suppliedFormatValue, formatX: suppliedFormatX, color, surface, badge, numberStyle, palette, loading, motion: motionMode, className, style, }: ScatterChartCardProps<Row, Key>): ReactElement;
+export declare function ScatterChartCard<Row, const Key extends NumericKey<Row>>({ title, data: suppliedData, x, y, size, sizeLabel, group, label, xLabel, yLabel, trend, depth, height, aggregate, headline: suppliedHeadline, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, valueFormat, legend, legendSwatch, xFormat, locale, formatValue: suppliedFormatValue, formatX: suppliedFormatX, color, surface, badge, numberStyle, palette, loading, loadingStyle, motion: motionMode, className, style, }: ScatterChartCardProps<Row, Key>): ReactElement;

package/dist/cards/slope-chart-card.d.ts

@@ -1,6 +1,6 @@
 import { CSSProperties, ReactElement, ReactNode } from 'react';
 import { SlopeOrder } from '../engine/slope';
-import { ChartMotion, ChartPalette, ChartStyle, ChartSurface } from '../types';
+import { ChartLoadingStyle, ChartMotion, ChartPalette, ChartStyle, ChartSurface } from '../types';
 import { CardRange } from './cartesian-card';
 import { NumericKey, TextKey } from './keys';
 import { AnimatedNumberVariant } from '../motion/animated-number';
@@ -24,6 +24,11 @@ export interface SlopeChartCardProps<Row, Key extends NumericKey<Row>> {
      * categories as rows with both values on one shared scale.
      */
     variant?: 'slope' | 'dumbbell';
+    /**
+     * Draws each change as a lit tube between two spheres, with a soft shadow. Ends stay exactly on
+     * their values.
+     */
+    depth?: boolean;
     /** `change` (default) puts the largest gain first, `to` the largest later value, `input` keeps your order. */
     sort?: SlopeOrder;
     /**
@@ -59,6 +64,7 @@ export interface SlopeChartCardProps<Row, Key extends NumericKey<Row>> {
     numberStyle?: AnimatedNumberVariant;
     palette?: ChartPalette;
     loading?: boolean;
+    loadingStyle?: ChartLoadingStyle;
     /** `none` turns off decorative motion; reduced-motion users get this automatically. */
     motion?: ChartMotion;
     className?: string;
@@ -70,4 +76,4 @@ export interface SlopeChartCardProps<Row, Key extends NumericKey<Row>> {
  * category reads its later value and change in the headline; click pins it, and the arrow keys
  * move through categories.
  */
-export declare function SlopeChartCard<Row, const Key extends NumericKey<Row>>({ title, data: suppliedData, category, from, to, fromLabel, toLabel, variant, sort, aggregate, headline: suppliedHeadline, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, color, height, valueFormat, locale, formatValue: suppliedFormatValue, surface, badge, numberStyle, palette, loading, motion: motionMode, className, style, }: SlopeChartCardProps<Row, Key>): ReactElement;
+export declare function SlopeChartCard<Row, const Key extends NumericKey<Row>>({ title, data: suppliedData, category, from, to, fromLabel, toLabel, variant, depth, sort, aggregate, headline: suppliedHeadline, delta: suppliedDelta, deltaTone, range, ranges, defaultRange, color, height, valueFormat, locale, formatValue: suppliedFormatValue, surface, badge, numberStyle, palette, loading, loadingStyle, motion: motionMode, className, style, }: SlopeChartCardProps<Row, Key>): ReactElement;