@lilt-ui/charts 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+## 0.2.0
+
+Finance charts, range charts, and series that carry more than one value.
+
+### Breaking
+
+- A series' `interval` is replaced by `fields`: named companion values in the series' unit, such as a forecast's low and high, quartiles, or a candle's open, high, and low. Fields fit the y axis, appear in hover, and range marks read them by ID.
+- `IntervalBand` now names the fields it draws: `<IntervalBand series="revenue" lower="low" upper="high" />`.
+- Tooltip content (`ChartTooltipContext.series[]`) has `fields` instead of `interval`.
+
+Cards are unchanged: `forecast={{ from, lower, upper }}` works as before. See "Upgrading from 0.1" in the README.
+
+### Finance, from `@lilt-ui/charts/finance`
+
+- `CandlestickChartCard`: candles, hollow candles, OHLC bars, or a price area colored by direction, with an optional linked volume pane, a log scale, and live mode. Hover reads the candle's open, high, and low beside its date.
+- `IndicatorChartCard`: simple or exponential averages and Bollinger bands over the price, with RSI, MACD, or volume panes underneath that move together on hover. Each pane reads its own value.
+- `PriceChartCard`: a ticker with its latest price, change, and change in money; `versus` rebases other instruments to percent change on one axis.
+- `DepthChartCard`: how much could trade at each price on the buy and sell side, with the gap between the best prices and the total resting on each side.
+- `OrderBook`: resting orders as an accessible table, each level with a bar sized by the total behind it; changed levels highlight briefly.
+- `PortfolioChartCard`: what an account is worth next to what went into it, with how far it sits below its best value in a linked pane.
+- `Candles`, a primitive that draws any number of candles into a handful of paths.
+- Helpers: `sma`, `ema`, `rsi` (Wilder), `macd`, `bollinger`, `drawdown`, `rebase`, and `depthLevels`.
+- `--lilt-candle-up` and `--lilt-candle-down` tokens, following `--lilt-positive` and `--lilt-negative`.
+
+### Charts
+
+- `RangeChartCard`: floating bars from low to high, or error bars around a value.
+- `BoxPlotCard`: quartiles, a median, Tukey whiskers, and outliers computed from raw samples. `summarizeBox` returns the same statistics.
+- Primitives: `RangeBar`, `ErrorBar`, and `BoxPlot`.
+- `series.colorAt(row)` colors one bar, candle, range, or point, such as a falling day in red.
+- `y.scale: 'log'` spaces values by ratio, with ticks on 1, 2, and 5.
+- `ReferenceBand axis="y"` shades a range of values, such as RSI 30–70.
+- `ChartPlot slots` gives every observation a bar-width slot, so a line pane lines up with bars or candles beside it.
+
+### Fixes
+
+- A card `valueFormat` with more than one minimum fraction digit, such as two-decimal prices, no longer throws.
+
+## 0.1.0
+
+The first release: Area, Line, Bar, Combo, Horizontal bar, Stat, Radial, Progress, Activity ring, Funnel, Heatmap, Scatter, Sankey, Radar, and Slope cards, with linked hover, targets, forecasts, and range comparison.

package/README.md

@@ -14,6 +14,7 @@
 <p align="center">
   <a href="https://liltui.vercel.app"><strong>Documentation</strong></a> ·
   <a href="https://liltui.vercel.app/charts/area">Charts</a> ·
+  <a href="https://liltui.vercel.app/finance/candlestick">Finance</a> ·
   <a href="https://liltui.vercel.app/llms.txt">llms.txt</a>
 </p>
 
@@ -82,6 +83,64 @@ That's the whole card: the headline, the change chip, value tiles, and hover all
 | **Rankings**         | Horizontal bar, with shares and an "Other" row                       |
 | **Flows and change** | Funnel, Sankey, and Slope                                            |
 | **Patterns**         | Heatmap, Scatter, and Radar                                          |
+| **Spread**           | Range (floating or error bars) and Box plot, from raw samples        |
+| **Markets**          | Candlestick, Indicators, Price, Depth, Order book, and Portfolio     |
+
+## Finance charts
+
+Candlesticks, indicators, and order books ship from their own entry point, so apps that never draw a candle never load one:
+
+```tsx
+'use client';
+
+import { CandlestickChartCard } from '@lilt-ui/charts/finance';
+
+const candles = [
+  {
+    date: new Date('2026-08-20'),
+    open: 243.1,
+    high: 246.4,
+    low: 241.8,
+    close: 245.2,
+    volume: 2410000,
+  },
+  {
+    date: new Date('2026-08-21'),
+    open: 245.2,
+    high: 247.0,
+    low: 243.9,
+    close: 244.6,
+    volume: 1980000,
+  },
+];
+
+export function MarketCard() {
+  return (
+    <CandlestickChartCard
+      title="SOL · USDC"
+      data={candles}
+      x="date"
+      open="open"
+      high="high"
+      low="low"
+      close="close"
+      volume="volume"
+      valueFormat={{ style: 'currency', currency: 'USD' }}
+    />
+  );
+}
+```
+
+| Card                   | What it shows                                                                  |
+| ---------------------- | ------------------------------------------------------------------------------ |
+| `CandlestickChartCard` | Candles, hollow candles, OHLC bars, or a price area, with a linked volume pane |
+| `IndicatorChartCard`   | Moving averages or Bollinger bands over the price; RSI, MACD, or volume panes  |
+| `PriceChartCard`       | A ticker with its latest price and change, or several instruments rebased      |
+| `DepthChartCard`       | How much could trade at each price, buying and selling, and the gap between    |
+| `OrderBook`            | Resting orders level by level, the best prices meeting in the middle           |
+| `PortfolioChartCard`   | What an account is worth next to what went in, and its fall from its best      |
+
+Candles draw into a handful of paths however many there are, so years of daily history stay fast. `scale="log"` spaces long histories by ratio, and `live` follows new rows as they arrive. The indicator math (`sma`, `ema`, `rsi`, `macd`, `bollinger`, `drawdown`, `depthLevels`) is exported too, for your own layouts.
 
 ## Built in, one prop away
 
@@ -102,6 +161,22 @@ Every Lilt style lives in the `lilt` cascade layer, so your CSS wins without spe
 @import 'tailwindcss';
 ```
 
+## Upgrading from 0.1
+
+0.2 replaces a series' `interval` with named `fields`, which carry any companion values: a forecast's low and high, quartiles, or a candle's open, high, and low. `IntervalBand` now names the fields it reads:
+
+```tsx
+// 0.1
+{ id: 'revenue', accessor: (row) => row.revenue, interval: { lower: (row) => row.low, upper: (row) => row.high, meaning: 'Forecast' } }
+<IntervalBand series="revenue" />
+
+// 0.2
+{ id: 'revenue', accessor: (row) => row.revenue, fields: { low: { label: 'Low', accessor: (row) => row.low }, high: { label: 'High', accessor: (row) => row.high } } }
+<IntervalBand series="revenue" lower="low" upper="high" />
+```
+
+Cards are unchanged: `forecast={{ from, lower, upper }}` works as before. Tooltip content reads `series[].fields` instead of `series[].interval`.
+
 ## License
 
 MIT © Lilt UI

package/dist/analysis-BJRmXHOB.js

@@ -0,0 +1,62 @@
+//#region src/engine/ranking.ts
+function e(e, t, n) {
+	let r = /* @__PURE__ */ new Set();
+	return e.map((e, i) => {
+		let a = t.id(e), o = t.label(e), s = n(e);
+		if (typeof a != "string" || !a.trim()) throw Error(`Invalid category at row ${i + 1}: a non-empty string ID is required.`);
+		if (r.has(a)) throw Error(`Duplicate category ID "${a}".`);
+		if (typeof o != "string" || !o.trim()) throw Error(`Invalid label for category "${a}".`);
+		if (s !== null && (typeof s != "number" || !Number.isFinite(s))) throw Error(`Invalid value for category "${a}": expected a finite number or null.`);
+		return r.add(a), {
+			id: a,
+			label: o,
+			datum: e,
+			value: s
+		};
+	});
+}
+function t(e, t) {
+	return t === "input" ? [...e] : [...e].sort((e, n) => {
+		if (e.value === null && n.value !== null) return 1;
+		if (n.value === null && e.value !== null) return -1;
+		let r = (e.value ?? 0) - (n.value ?? 0);
+		return r ? r * (t === "descending" ? -1 : 1) : e.id < n.id ? -1 : +(e.id > n.id);
+	});
+}
+function n(e) {
+	let t = 0, n = 0;
+	for (let r of e) r.value !== null && (t = Math.min(t, r.value), n = Math.max(n, r.value));
+	return t === n ? [0, 1] : [t, n];
+}
+function r(e, t) {
+	let n = (e) => (e - t[0]) / (t[1] - t[0]) * 100, r = n(0), i = e === null ? r : n(e);
+	return {
+		zero: r,
+		left: Math.min(r, i),
+		width: Math.abs(i - r)
+	};
+}
+//#endregion
+//#region src/engine/analysis.ts
+function i(e, t) {
+	if (e !== null && (!Number.isFinite(e) || e < 0)) throw Error(`${t} must be a non-negative finite number or null.`);
+}
+function a(t) {
+	let n = e(t.data, t.category, t.value), r = Infinity;
+	for (let e of n) if (i(e.value, `Stage ${e.id}`), e.value !== null) {
+		if (e.value > r) throw Error(`Stage ${e.id} exceeds a preceding stage; cumulative funnel counts must not increase.`);
+		r = e.value;
+	}
+	let a = n[0]?.value;
+	return n.map((e, t) => {
+		let r = n[t - 1]?.value;
+		return {
+			...e,
+			share: e.value !== null && a != null && a > 0 ? e.value / a : null,
+			conversion: e.value !== null && r != null && r > 0 ? e.value / r : null,
+			drop: e.value !== null && r != null ? r - e.value : null
+		};
+	});
+}
+//#endregion
+export { n as a, r as i, e as n, t as r, a as t };

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

@@ -0,0 +1,30 @@
+import { ReactElement } from 'react';
+import { BoxSummary } from '../engine/box';
+import { CartesianCardProps } from './cartesian-card';
+import { KeysOfType } from './keys';
+/** One box, with its x value and the row it came from. */
+interface BoxRow<Row> {
+    x: string | number | Date;
+    median: number | null;
+    box: BoxSummary | null;
+    source: Row;
+}
+type SharedProps<Row> = Omit<CartesianCardProps<BoxRow<Row>, 'median'>, 'series' | 'data' | 'ranges' | 'x' | 'headlineSeries' | 'pillSeries' | 'target' | 'forecast' | 'bleed' | 'tiles' | 'aggregate'>;
+export interface BoxPlotCardProps<Row> extends SharedProps<Row> {
+    data?: readonly Row[];
+    /** One box per row, placed by this field: labels, numbers, or dates. */
+    x: KeysOfType<Row, string | number | Date>;
+    /** Field holding each row's raw samples; Lilt computes the quartiles, whiskers and outliers. */
+    samples: KeysOfType<Row, readonly number[]>;
+    /** Names the series in hover. Defaults to "Median". */
+    label?: string;
+    color?: string;
+    /** Draw samples beyond the whiskers as dots. Defaults to true. */
+    outliers?: 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 {};

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

@@ -1,5 +1,5 @@
 import { CSSProperties, ReactElement, ReactNode } from 'react';
-import { ChartAxisStyle, ChartBarAppearance, ChartBackground, ChartCurve, ChartMotion, ChartPalette, ChartHoverReadout, ChartHoverStyle, ChartTooltipIndicator, ChartStyle, ChartSurface } from '../types';
+import { ChartController, ChartMargins, ChartTooltipContext, NumericXConfig, TimeXConfig, ChartAxisStyle, ChartBarAppearance, ChartBackground, ChartCurve, ChartMotion, ChartPalette, ChartHoverReadout, ChartHoverStyle, ChartSeries, ChartTooltipIndicator, ChartStyle, ChartSurface } from '../types';
 import { NumericKey, ResolvedX, XKey, XKind } from './keys';
 import { CardAggregate } from './format';
 import { AnimatedNumberVariant } from '../motion/animated-number';
@@ -191,16 +191,67 @@ export type CardShape = {
     /** Curve and point markers of lines drawn over the bars. */
     curve?: ChartCurve;
     points?: boolean;
-};
+} | CardMarks;
+/**
+ * Column marks drawn from each series' fields, such as candles or range bars. Cards built on
+ * this shape keep every Cartesian card behaviour: headline, ranges, hover sync and tiles.
+ */
+export interface CardMarks {
+    kind: 'marks';
+    /** A stable description of everything below, so memoized series only rebuild when it changes. */
+    id: string;
+    /** Descriptor options for a series by key, such as its fields, colors, curve, or area. */
+    series?: (key: string) => Partial<ChartSeries<never>> | undefined;
+    /**
+     * The marks for the drawn series, as elements or fragments of them (not wrapped in a
+     * component), so the plot can find column marks. Dashed references still draw as lines.
+     */
+    draw: (ids: readonly string[]) => ReactNode;
+    includeZero: boolean;
+    scale?: 'linear' | 'log';
+    curve?: ChartCurve;
+    /** Values the y axis must reach, such as outliers beyond the fields. */
+    include?: readonly number[];
+    /** Slot every observation like a bar, so linked bar panes line up. Column marks imply it. */
+    slots?: boolean;
+    /** Label the x axis here. Turn off when a pane below carries it. Defaults to true. */
+    xAxis?: boolean;
+    /** Extra text after the hovered x in the headline caption, e.g. open, high and low. */
+    describe?: (inspection: ChartTooltipContext) => string | null;
+}
+/** Panes drawn under the main plot, linked to it: same data, x, margins and crosshair. */
+export interface CardPaneContext<Row> {
+    data: readonly Row[];
+    x: TimeXConfig<Row> | NumericXConfig<Row>;
+    controller: ChartController;
+    margins: ChartMargins;
+    /** The main plot's `axisInset` and `slots`, so a pane's observations sit under its own. */
+    axisInset: number;
+    slots: boolean;
+    axis: ChartAxisStyle;
+    loading: boolean;
+    motion?: ChartMotion;
+    hoverStyle: ChartHoverStyle;
+    formatValue: (value: number) => string;
+    formatAxis: (value: number) => string;
+}
 /** Matches the default `--lilt-card-padding`. */
 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, }: 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, 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, }: Omit<CartesianCardProps<Row, Key>, 'series'> & {
     series: readonly CoreSeries<Key>[];
     shape: CardShape;
+    /** Linked panes under the plot, such as volume or indicators. */
+    panes?: (context: CardPaneContext<Row>) => ReactNode;
+    /** Follow the newest observation as rows arrive. */
+    live?: boolean;
+    /** Richer title content, such as a ticker and its name; `title` still labels the chart. */
+    heading?: ReactNode;
+    /** Text beside the delta at rest, such as an absolute change, from the active data. */
+    restCaption?: (data: readonly Row[]) => ReactNode;
 }): ReactElement;
 /** The plot position where projections begin: a label's row, or the date or number itself. */
 export declare function forecastPosition<Row>(data: readonly Row[], x: string, resolved: ResolvedX<Row>, from: string | number): number | null;

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

@@ -0,0 +1,28 @@
+import { ReactElement } from 'react';
+import { CartesianCardProps } from './cartesian-card';
+import { NumericKey } from './keys';
+type SharedProps<Row, Key extends NumericKey<Row>> = Omit<CartesianCardProps<Row, Key>, 'series' | 'headlineSeries' | 'pillSeries' | 'target' | 'forecast' | 'bleed' | 'tiles'>;
+export interface RangeChartCardProps<Row, Key extends NumericKey<Row>> extends SharedProps<Row, Key> {
+    /** Field holding the low end of each range. */
+    low: Key;
+    /** Field holding the high end of each range. */
+    high: Key;
+    /**
+     * Field holding each measured value, such as a mean inside its uncertainty. It drives the
+     * headline and pills. Defaults to `high`.
+     */
+    value?: Key;
+    /** Names the series in hover and tiles. Defaults to the value key. */
+    label?: string;
+    color?: string;
+    /** `bar` (default) floats a bar from low to high; `error` draws whiskers around the value. */
+    display?: 'bar' | 'error';
+    /** Per-series stat tile under the plot. Defaults to false. */
+    tiles?: boolean;
+}
+/**
+ * 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 {};