@lilt-ui/charts 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lilt UI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+<h1 align="center">Lilt Charts</h1>
+
+<p align="center">
+  React chart cards with feeling.<br />
+  Pass your rows, name the fields, and get a finished card.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@lilt-ui/charts"><img alt="npm version" src="https://img.shields.io/npm/v/@lilt-ui/charts?color=7c5cff&label=npm" /></a>
+  <img alt="TypeScript types included" src="https://img.shields.io/npm/types/@lilt-ui/charts?color=7c5cff" />
+  <img alt="MIT license" src="https://img.shields.io/npm/l/@lilt-ui/charts?color=7c5cff" />
+</p>
+
+<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/llms.txt">llms.txt</a>
+</p>
+
+<picture>
+  <source media="(prefers-color-scheme: light)" srcset="https://cdn.jsdelivr.net/npm/@lilt-ui/charts/media/hero-light.webp" />
+  <img alt="A Lilt sales card with segmented stacked bars beside the headline “Give your data a little Lilt.”" src="https://cdn.jsdelivr.net/npm/@lilt-ui/charts/media/hero-dark.webp" />
+</picture>
+
+## Install
+
+```bash
+npm install @lilt-ui/charts
+# or: pnpm add @lilt-ui/charts
+# or: yarn add @lilt-ui/charts
+# or: bun add @lilt-ui/charts
+```
+
+Lilt needs React and React DOM 19. Every card, variant, and prop is documented at [liltui.vercel.app](https://liltui.vercel.app). Import the stylesheet once, in your root layout or app entry:
+
+```ts
+import '@lilt-ui/charts/styles.css';
+```
+
+## Your first card
+
+```tsx
+'use client';
+
+import { AreaChartCard } from '@lilt-ui/charts';
+
+const visitors = [
+  { month: 'Jan', organic: 2400, paid: 800 },
+  { month: 'Feb', organic: 2800, paid: 700 },
+  { month: 'Mar', organic: 3100, paid: 900 },
+];
+
+export function VisitorsCard() {
+  return (
+    <AreaChartCard
+      title="Visitors"
+      data={visitors}
+      x="month"
+      series={[
+        { key: 'organic', label: 'Organic' },
+        { key: 'paid', label: 'Paid' },
+      ]}
+    />
+  );
+}
+```
+
+That's the whole card: the headline, the change chip, value tiles, and hover all come from your rows. `x` and each series `key` are checked against your data, so a typo is a type error, not a blank chart.
+
+## Every card, finished
+
+<picture>
+  <source media="(prefers-color-scheme: light)" srcset="https://cdn.jsdelivr.net/npm/@lilt-ui/charts/media/cards-light.webp" />
+  <img alt="Stat cards with sparklines, bars, and a goal meter above a needle bar chart and a retention heatmap" src="https://cdn.jsdelivr.net/npm/@lilt-ui/charts/media/cards-dark.webp" />
+</picture>
+
+| For                  | Cards                                                                |
+| -------------------- | -------------------------------------------------------------------- |
+| **Trends**           | Area, Line, Bar, and Combo cards, overlapping, stacked, or as shares |
+| **At a glance**      | Stat cards with a sparkline, bars, a meter, or a ring                |
+| **Parts and goals**  | Radial, Progress, and Activity ring                                  |
+| **Rankings**         | Horizontal bar, with shares and an "Other" row                       |
+| **Flows and change** | Funnel, Sankey, and Slope                                            |
+| **Patterns**         | Heatmap, Scatter, and Radar                                          |
+
+## Built in, one prop away
+
+- **Linked hover.** Give cards the same `sync` name and they read the same moment together.
+- **Targets and forecasts.** `target` draws a goal line and counts the points that reach it. `forecast` marks projected rows and keeps them out of the headline.
+- **Pin and compare.** Click to pin a point. Add `compare` and drag across a chart to see what changed.
+- **Honest data.** `null` is a gap, never a zero, and missing values say so.
+- **Calm by default.** Keyboard navigation, screen reader labels, and motion that respects reduced-motion settings.
+
+## Fits your design system
+
+Cards follow shadcn theme variables when your app defines them: `--card`, `--card-foreground`, `--muted-foreground`, `--border`, `--ring`, and `--chart-1` to `--chart-5`. Anything you leave out falls back to Lilt's own palette.
+
+Every Lilt style lives in the `lilt` cascade layer, so your CSS wins without specificity tricks. With Tailwind, declare the layer order once at the top of your global stylesheet:
+
+```css
+@layer theme, base, lilt, components, utilities;
+@import 'tailwindcss';
+```
+
+## License
+
+MIT © Lilt UI

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,25 @@
+# Third-party notices
+
+The legend's isolate glyph uses the CenterFocusIcon SVG paths from Hugeicons Free.
+
+MIT License
+
+Copyright (c) 2025 Hugeicons
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/activity-ring.d.ts

@@ -0,0 +1,44 @@
+import { ReactNode } from 'react';
+import { ChartMotion } from './types';
+export interface ActivitySelection<Row> {
+    hour: number;
+    row: Row | null;
+    value: number | null;
+    pinned: boolean;
+}
+export interface ActivityRingProps<Row> {
+    data: readonly Row[];
+    hour: (row: Row) => number;
+    value: (row: Row) => number | null;
+    /** Explicit positive upper bound for dot intensity. Values must be in [0, maximum]. */
+    maximum: number;
+    /** Minutes per position across a full 24-hour cycle. Must divide 1,440. */
+    bucketMinutes?: number;
+    /** Number of radial dots used to show intensity. */
+    dotDensity?: number;
+    unit: string;
+    formatValue?: (value: number) => string;
+    /** Content at the centre; defaults to the peak reading. */
+    center?: ReactNode;
+    onSelectionChange?: (selection: ActivitySelection<Row> | null) => void;
+    /** `loading` keeps showing the last accepted day until new data is ready. */
+    status?: 'ready' | 'loading';
+    /** A new key drops the accepted day and any selection. */
+    resetKey?: string | number;
+    motion?: ChartMotion;
+    height?: number;
+    'aria-label': string;
+    className?: string;
+}
+interface Slot<Row> {
+    hour: number;
+    row: Row | null;
+    value: number | null;
+}
+export declare function activitySlots<Row>(data: readonly Row[], hour: (row: Row) => number, value: (row: Row) => number | null, maximum: number, bucketMinutes?: number): readonly Slot<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 {};

package/dist/analysis-BLLWEKBw.js

@@ -0,0 +1,105 @@
+//#region src/data/chart-data.ts
+function e(e, t) {
+	let n = t.range;
+	if (n && (!Number.isFinite(n.startX) || !Number.isFinite(n.endX))) throw Error("Range bounds must be finite.");
+	let r = n ? Math.min(n.startX, n.endX) : -Infinity, i = n ? Math.max(n.startX, n.endX) : Infinity, a = 0, o = 0, s = 0, c = Infinity, l = -Infinity, u = Infinity, d = -Infinity, f = null, p = null, m = /* @__PURE__ */ new Set();
+	for (let n of e) {
+		let e = Number(t.x(n));
+		if (!Number.isFinite(e)) throw Error("Summary positions must be finite numbers or valid dates.");
+		if (e < r || e > i) continue;
+		if (m.has(e)) throw Error("Summary positions must be unique.");
+		m.add(e);
+		let h = t.value(n);
+		if (h !== null && (typeof h != "number" || !Number.isFinite(h))) throw Error("Summary values must be finite numbers or null.");
+		if (e < u && (u = e, f = h), e > d && (d = e, p = h), h === null) {
+			o++;
+			continue;
+		}
+		a++, s += h, c = Math.min(c, h), l = Math.max(l, h);
+	}
+	if (!Number.isFinite(s)) throw Error("Summary total exceeds the finite numeric range.");
+	return {
+		count: a,
+		missing: o,
+		total: a ? s : null,
+		mean: a ? s / a : null,
+		min: a ? c : null,
+		max: a ? l : null,
+		first: f,
+		last: p,
+		change: f === null || p === null ? null : p - f
+	};
+}
+function t(e, t) {
+	if (!t.length) throw Error("CSV needs at least one column.");
+	let n = (e) => {
+		if (typeof e == "number" && !Number.isFinite(e)) throw Error("CSV numbers must be finite.");
+		if (e instanceof Date && !Number.isFinite(e.getTime())) throw Error("CSV dates must be valid.");
+		let t = e === null ? "" : e instanceof Date ? e.toISOString() : String(e);
+		return typeof e == "string" && /^[\s]*[=+\-@]|^[\t\r\n]/.test(t) && (t = "'" + t), /[",\r\n]/.test(t) ? `"${t.replaceAll("\"", "\"\"")}"` : t;
+	};
+	return [t.map((e) => n(e.header)).join(","), ...e.map((e) => t.map((t) => n(t.value(e))).join(","))].join("\r\n") + "\r\n";
+}
+//#endregion
+//#region src/engine/ranking.ts
+function n(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 r(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 i(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 a(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 o(e, t) {
+	if (e !== null && (!Number.isFinite(e) || e < 0)) throw Error(`${t} must be a non-negative finite number or null.`);
+}
+function s(e) {
+	let t = n(e.data, e.category, e.value), r = Infinity;
+	for (let e of t) if (o(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 i = t[0]?.value;
+	return t.map((e, n) => {
+		let r = t[n - 1]?.value;
+		return {
+			...e,
+			share: e.value !== null && i != null && i > 0 ? e.value / i : 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 { i as a, a as i, n, e as o, r, t as s, s as t };

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

@@ -0,0 +1,60 @@
+import { CSSProperties, ReactElement, ReactNode } from 'react';
+import { ChartMotion, ChartPalette, ChartStyle, ChartSurface } from '../types';
+import { CardRange } from './cartesian-card';
+import { NumericKey } from './keys';
+import { AnimatedNumberVariant } from '../motion/animated-number';
+/** How the resting headline sums up the day. */
+export type ActivityAggregate = 'sum' | 'mean' | 'max';
+export interface ActivityRingCardProps<Row, Key extends NumericKey<Row>> {
+    title: string;
+    /** One row per time slot. Omit when `ranges` supplies the data. */
+    data?: readonly Row[];
+    /** Numeric field with the time of day in hours, from 0 up to 24; 14.5 is 14:30. */
+    hour: NumericKey<Row>;
+    /** How much happened in the slot. `null` means not recorded; zero means nothing happened. */
+    value: Key;
+    /** Minutes per slot around the day. Must divide 1,440. Defaults to 60. */
+    bucketMinutes?: number;
+    /** What `value` counts, e.g. "requests". Defaults to the `value` field's name. */
+    unit?: string;
+    /** Value that fills a slot's dots completely. Defaults to a round number above the peak. */
+    maximum?: number;
+    /** How the resting headline sums up the day: `sum` (default), `mean`, or `max`. */
+    aggregate?: ActivityAggregate;
+    /** Ring height in pixels, at least 180. Defaults to 280. */
+    height?: number;
+    /** Resting headline. Defaults to the `aggregate` of every recorded slot. */
+    headline?: number;
+    /** Fractional change shown as a chip, e.g. 0.052 → +5.2%. */
+    delta?: number;
+    deltaTone?: 'default' | 'inverse' | 'neutral';
+    /** Static period label, e.g. "Today". */
+    range?: string;
+    /** Period select. Each range replaces data, delta, and headline. */
+    ranges?: readonly CardRange<Row>[];
+    defaultRange?: string;
+    valueFormat?: Intl.NumberFormatOptions;
+    locale?: string;
+    formatValue?: (value: number) => string;
+    /** Any CSS color for the dots. Defaults to the palette's first color. */
+    color?: string;
+    surface?: ChartSurface;
+    /** A glass tab tucked behind the card's top edge, e.g. a caption, a command, or actions. */
+    badge?: ReactNode;
+    /** Headline motion: `count` (default), `pop`, `slide`, `roll`, `flow`, or `scramble`. */
+    numberStyle?: AnimatedNumberVariant;
+    palette?: ChartPalette;
+    loading?: boolean;
+    /** `none` turns off decorative motion; reduced-motion users get this automatically. */
+    motion?: ChartMotion;
+    className?: string;
+    style?: CSSProperties | ChartStyle;
+}
+/** "14:00" for 14, "03:20" for 3.333…; the day wraps at 24:00. */
+export declare function clockLabel(hour: number): string;
+/**
+ * An activity ring card: a 24-hour day wrapped into a ring of dot columns, each slot's dots
+ * 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;

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

@@ -0,0 +1,19 @@
+import { ReactElement } from 'react';
+import { CartesianCardProps } from './cartesian-card';
+import { NumericKey } from './keys';
+export type { CardRange, CardSeries } from './cartesian-card';
+export interface AreaChartCardProps<Row, Key extends NumericKey<Row>> extends CartesianCardProps<Row, Key> {
+    /**
+     * Stack the areas: `true` adds them, `'percent'` shows each series' share of its period, and
+     * the headline and tiles then read shares of the latest period. Omit to overlap them. Dashed
+     * series stay reference lines over the stack.
+     */
+    stack?: boolean | 'percent';
+    /** `smooth` uses a monotone curve; `linear` draws straight segments. */
+    curve?: 'smooth' | 'linear';
+}
+/**
+ * A complete area chart card: headline, delta, period, plot, and value tiles.
+ * The headline and tiles follow the hovered point.
+ */
+export declare function AreaChartCard<Row, const Key extends NumericKey<Row>>({ stack, curve, ...props }: AreaChartCardProps<Row, Key>): ReactElement;

package/dist/cards/area-chart-card.typecheck.d.ts

@@ -0,0 +1,9 @@
+export declare const valid: import("react/jsx-runtime").JSX.Element;
+export declare const wrongKey: import("react/jsx-runtime").JSX.Element;
+export declare const textSeries: import("react/jsx-runtime").JSX.Element;
+export declare const wrongX: import("react/jsx-runtime").JSX.Element;
+export declare const ranged: import("react/jsx-runtime").JSX.Element;
+export declare const lineCard: import("react/jsx-runtime").JSX.Element;
+export declare const lineTypo: import("react/jsx-runtime").JSX.Element;
+export declare const barCard: import("react/jsx-runtime").JSX.Element;
+export declare const barTypo: import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,34 @@
+import { ReactElement } from 'react';
+import { CartesianCardProps } from './cartesian-card';
+import { NumericKey } from './keys';
+import { ChartBarAppearance } from '../types';
+export interface BarChartCardProps<Row, Key extends NumericKey<Row>> extends CartesianCardProps<Row, Key> {
+    /**
+     * Stack the bars: `true` adds them, `'percent'` shows each series' share of its period, and
+     * the headline and tiles then read shares of the latest period. Omit to group them side by
+     * side. Dashed series stay reference lines over the bars, such as a target.
+     */
+    stack?: boolean | 'percent';
+    /** Corner radius in pixels. Defaults to 6. */
+    radius?: number;
+    /**
+     * `end` (default) rounds each bar's value end; `all` rounds every corner, so stacked segments
+     * read as separate rounded blocks.
+     */
+    corners?: 'end' | 'all';
+    /** Quiet full-height lanes behind each bar or stack. Defaults to false. */
+    tracks?: boolean;
+    /** Maximum bar width in pixels; bars never exceed their slot. */
+    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`.
+     */
+    barStyle?: ChartBarAppearance;
+}
+/**
+ * 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;

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

@@ -0,0 +1,206 @@
+import { CSSProperties, ReactElement, ReactNode } from 'react';
+import { ChartAxisStyle, ChartBarAppearance, ChartBackground, ChartCurve, ChartMotion, ChartPalette, ChartHoverReadout, ChartHoverStyle, ChartTooltipIndicator, ChartStyle, ChartSurface } from '../types';
+import { NumericKey, ResolvedX, XKey, XKind } from './keys';
+import { CardAggregate } from './format';
+import { AnimatedNumberVariant } from '../motion/animated-number';
+export interface CardSeries<Key extends string> {
+    /** A numeric field of each row. */
+    key: Key;
+    /** Defaults to the key. */
+    label?: string;
+    /** Any CSS color. Defaults to the next palette color. */
+    color?: string;
+    /**
+     * A reference such as a previous period or target: drawn as a dashed line without a fill and
+     * left out of the headline total.
+     */
+    dashed?: boolean;
+}
+/** A goal each point should reach. A number, or a value with its own line label. */
+export type CardTarget = number | {
+    value: number;
+    label?: string;
+};
+/** Rows from `from` onward are projections rather than measurements. */
+export interface CardForecast<Row> {
+    /** The x value of the first projected row: a label, number, or Date. */
+    from: string | number | Date;
+    /** Fields holding the low and high end of the projection, drawn as a band around it. */
+    lower?: NumericKey<Row>;
+    upper?: NumericKey<Row>;
+    /** Names the projected region and the hover caption. Defaults to "Forecast". */
+    label?: string;
+}
+export interface CardRange<Row> {
+    id: string;
+    label: string;
+    data: readonly Row[];
+    delta?: number;
+    headline?: number;
+}
+/** Props every Cartesian card shares. Each card adds its own shape options. */
+export interface CartesianCardProps<Row, Key extends NumericKey<Row>> {
+    title: string;
+    /** One row per x position. Omit when `ranges` supplies the data. */
+    data?: readonly Row[];
+    /** Field used for the x axis: labels, numbers, or dates. */
+    x: XKey<Row>;
+    series: readonly CardSeries<Key>[];
+    /** Resting headline. Defaults to the total of every series except dashed references. */
+    headline?: number;
+    /**
+     * How the headline and tiles summarize the period at rest: `sum` (default) for counts and
+     * money, `mean` or `max` for rates such as latency, `last` for levels such as seats.
+     */
+    aggregate?: CardAggregate;
+    /** Make the headline follow one series instead of the total, e.g. p95 latency. */
+    headlineSeries?: NoInfer<Key>;
+    /** Fractional change shown as a chip, e.g. 0.082 → +8.2%. */
+    delta?: number;
+    deltaTone?: 'default' | 'inverse' | 'neutral';
+    /** Static period label, e.g. "This year". */
+    range?: string;
+    /** 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. */
+    tiles?: boolean;
+    /** Plot height in pixels. Defaults to 240. */
+    height?: number;
+    /** Number format for the headline, tiles, and axis, e.g. `{ style: 'currency', currency: 'USD' }`. */
+    valueFormat?: Intl.NumberFormatOptions;
+    locale?: string;
+    /** Full control over value text. Takes precedence over `valueFormat`. */
+    formatValue?: (value: number) => string;
+    formatAxisValue?: (value: number) => string;
+    formatX?: (value: string | number | Date) => string;
+    /** Override x inference. Numbers default to `number`; use `time` for timestamps. */
+    xType?: XKind;
+    /** Axis preset: `minimal` (default), `dots`, `inline`, `ruler`, or `classic`. */
+    axis?: ChartAxisStyle;
+    /** Texture behind the plot: `dots` (default), `grid`, `lines`, or `none`. */
+    background?: ChartBackground;
+    /** Brighten the background around the hovered point. Defaults to true. */
+    spotlight?: boolean;
+    /** Card treatment: `elevated` (default), `outline`, or `ghost` inside your own card. */
+    surface?: ChartSurface;
+    /** A glass tab tucked behind the card's top edge, e.g. a caption, a command, or actions. */
+    badge?: ReactNode;
+    /** Headline motion: `count` (default), `pop`, `slide`, `roll`, `flow`, or `scramble`. */
+    numberStyle?: AnimatedNumberVariant;
+    /** Series color set. Explicit series colors still win. */
+    palette?: ChartPalette;
+    /**
+     * Run marks to the card's edges. Line and area cards fade past the first and last
+     * observations. With `false`, data starts and ends at the plot edges and edge labels hang into
+     * the card padding to stay centered.
+     */
+    bleed?: boolean;
+    /**
+     * Padding in pixels between the plot edges and axis labels or pills.
+     * Defaults to the card padding (20) when `bleed` is on, otherwise 0.
+     */
+    axisInset?: number;
+    /**
+     * What the hovered point shows, one readout at a time: `pills` (default) on the axes, a
+     * `tooltip` with every series, or `headline`, which leaves the plot to the hover dots.
+     */
+    hover?: ChartHoverReadout;
+    /** How the pills or tooltip look: `soft` (default), `solid`, or `accent`. */
+    hoverStyle?: ChartHoverStyle;
+    /**
+     * Which series the y pill follows and the tooltip leads with: `nearest` (default) tracks the
+     * line closest to the pointer, a series key locks it, and `total` follows the top of a stack.
+     */
+    pillSeries?: 'nearest' | 'total' | NoInfer<Key>;
+    /** Stacks: show the series' own value (`series`, default) or its stacked height (`stack`). */
+    pillValue?: 'series' | 'stack';
+    /**
+     * Where the value pill sits: `mark` above the hovered bar or point, `axis` on the y axis.
+     * `auto` (default) uses `mark` when the axis shows no y labels.
+     */
+    pillPosition?: 'auto' | 'axis' | 'mark';
+    /** Series marker on each tooltip row: `square` (default), `dot`, or `line`. */
+    tooltipIndicator?: ChartTooltipIndicator;
+    /**
+     * Enable range comparison by dragging across the plot. Off by default. `true` or `'headline'`
+     * reads the change out in the headline; `'badge'` reads it out in the card's badge tab and
+     * leaves the headline and tiles at rest.
+     */
+    compare?: boolean | 'headline' | 'badge';
+    /**
+     * The value each point should reach, drawn as a dashed line. The hovered point reads against
+     * it, and at rest the header counts points on target. With `deltaTone="inverse"`, on target
+     * means at or below it.
+     */
+    target?: CardTarget;
+    /**
+     * Mark rows from `forecast.from` onward as projections: drawn dotted, left out of the headline
+     * and tiles, and captioned "Forecast" on hover. `lower` and `upper` add a range band on line
+     * and unstacked area cards; each bound must contain the projected value.
+     */
+    forecast?: CardForecast<Row>;
+    /**
+     * Link hover and pins with every card that uses the same name. Cards match by x: labels
+     * exactly, dates and numbers to the nearest row. Every linked card shows its hover marks,
+     * pills, and headline at that point; only the card that owns a pin shows its release control.
+     */
+    sync?: string;
+    loading?: boolean;
+    /** `none` turns off decorative motion; reduced-motion users get this automatically. */
+    motion?: ChartMotion;
+    className?: string;
+    style?: CSSProperties | ChartStyle;
+}
+/**
+ * Series options only some cards expose. The Combo card draws `as: 'line'` series over its bars,
+ * optionally on their own scale and with their own number format and summary.
+ */
+export interface CoreSeries<Key extends string> extends CardSeries<Key> {
+    as?: 'line';
+    scale?: 'secondary';
+    valueFormat?: Intl.NumberFormatOptions;
+    aggregate?: CardAggregate;
+}
+/**
+ * How a card combines its series: `false` side by side (bars) or overlapping (areas), `sum`
+ * adds them, `percent` shows each series' share of its period.
+ */
+export type CardStack = false | 'sum' | 'percent';
+/** The public `stack` prop: `true` adds series, `'percent'` shows shares. */
+export declare function cardStack(stack: boolean | 'percent' | undefined): CardStack;
+/** How a specific card draws its marks; everything else is shared. */
+export type CardShape = {
+    kind: 'area';
+    stack: CardStack;
+    curve: ChartCurve;
+} | {
+    kind: 'line';
+    curve: ChartCurve;
+    points: boolean;
+    zero: boolean;
+} | {
+    kind: 'bar';
+    stack: CardStack;
+    radius: number;
+    /** `end` rounds each bar's value end; `all` rounds every corner of every bar and segment. */
+    corners: 'end' | 'all';
+    tracks: boolean;
+    barWidth?: number;
+    appearance: ChartBarAppearance;
+    /** Curve and point markers of lines drawn over the bars. */
+    curve?: ChartCurve;
+    points?: boolean;
+};
+/** 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'> & {
+    series: readonly CoreSeries<Key>[];
+    shape: CardShape;
+}): 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;