twico-ui 1.8.0 → 1.9.0

package/dist/index.d.cts

@@ -546,23 +546,40 @@ declare function Carousel(props: CarouselProps): React.JSX.Element;
 type ChartDatum<K extends string = "value"> = { label: React.ReactNode } & { [P in K]: number };
 
 /**
- * Lightweight, dependency-free SVG chart — bar or line, single or multi-series,
- * with grid, axes, animated entrance, tooltips, and optional legend. Generic over
- * the series keys `K` so the data rows are type-checked (e.g.
- * `<Chart series={["sales"]} data={[{ label, sales: 12 }]} />`).
+ * Cartesian chart — vertical/horizontal bars (grouped or stacked), line, and area
+ * (straight / smooth / stepped), single or multi-series, with grid, axes, tooltips,
+ * and an optional legend. Dependency-free inline SVG. Generic over the series keys
+ * `K` so the data rows are type-checked (e.g.
+ * `<Chart series={["sales"]} data={[{ label, sales: 12 }]} />`). For pie/donut,
+ * scatter/bubble, radar, heatmap, gauge, funnel, treemap, candlestick, boxplot and
+ * range charts use the dedicated sibling components.
  *
- * @startingPoint section="Data display" subtitle="Bar / line chart (no deps)" viewport="700x280"
+ * @startingPoint section="Data display" subtitle="Bar / line / area chart (no deps)" viewport="700x280"
  */
 interface ChartProps<K extends string = "value"> extends React.HTMLAttributes<HTMLDivElement> {
-  /** @default "bar" */
-  type?: "bar" | "line";
+  /** Chart type. `"column"` is an alias of `"bar"` (vertical bars). @default "bar" */
+  type?: "bar" | "column" | "line" | "area";
   /** Data points. Each has a `label` + one numeric field per series key. (`K` is inferred from `series`, not from `data`.) */
   data: ChartDatum<NoInfer<K>>[];
-  /** Series field names (defaults to `["value"]`). Multiple = grouped bars / multi-line. */
+  /** Series field names (defaults to `["value"]`). Multiple = grouped bars / multi-line / stacked. */
   series?: K[];
   /** Pixel height. @default 220 */
   height?: number;
-  /** Horizontal grid lines. @default true */
+  /** Stack multi-series bars/areas instead of grouping them side by side. @default false */
+  stacked?: boolean;
+  /** Render bars horizontally (value axis along the bottom). Ignored for line/area. @default false */
+  horizontal?: boolean;
+  /** Line/area interpolation. @default "straight" */
+  curve?: "straight" | "smooth" | "stepped";
+  /** Shorthand for `curve="smooth"`. @default false */
+  smooth?: boolean;
+  /** Show point markers on line charts. @default true */
+  showDots?: boolean;
+  /** Print each value as a data label on the bars/points. @default false */
+  showValues?: boolean;
+  /** Play the entrance animation (bars grow, lines draw); respects `prefers-reduced-motion`. @default true */
+  animate?: boolean;
+  /** Grid lines. @default true */
   showGrid?: boolean;
   /** Axis labels. @default true */
   showAxis?: boolean;
@@ -582,6 +599,653 @@ interface ChartProps<K extends string = "value"> extends React.HTMLAttributes<HT
 
 declare function Chart<K extends string = "value">(props: ChartProps<K>): React.JSX.Element;
 
+/** A single pie/donut slice: a `label`, its numeric `value`, and an optional override `color`. */
+interface PieChartDatum {
+  /** Slice label (shown in the legend, tooltip, and hidden data table). */
+  label: React.ReactNode;
+  /** Slice magnitude; the share is `value / total`. Negative values are treated as `0`. */
+  value: number;
+  /** Optional per-slice CSS color; falls back to the cycled token palette. */
+  color?: string;
+}
+
+/**
+ * Pie / donut chart — proportional slices of a whole from a single value series,
+ * with per-slice tooltips, an optional legend, optional percentage labels, and a
+ * donut center label. Dependency-free inline SVG. For bar/line/area use `Chart`;
+ * for other shapes use the dedicated sibling components (gauge, radar, funnel, …).
+ *
+ * @startingPoint section="Data display" subtitle="Pie / donut chart (no deps)" viewport="700x280"
+ */
+interface PieChartProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "color"> {
+  /** Slices to plot; each is a `{ label, value, color? }`. Only positive values contribute a slice. */
+  data: PieChartDatum[];
+  /** Render as a donut (ring) instead of a filled pie, using the default `innerRadius`. @default false */
+  donut?: boolean;
+  /** Inner-hole radius as a fraction (0..1) of the outer radius. @default 0.6 when `donut`, else 0 */
+  innerRadius?: number;
+  /** Angle (deg, clockwise from 12 o'clock) where the first slice starts. @default 0 */
+  startAngle?: number;
+  /** Gap (deg) inserted between adjacent slices. @default 0 */
+  padAngle?: number;
+  /** Draw a percentage label centered on each non-hairline slice. @default false */
+  showLabels?: boolean;
+  /** Show the slice legend below the chart. @default true */
+  showLegend?: boolean;
+  /** Content for a donut's center; defaults to the formatted total when `donut`. Ignored for a solid pie. */
+  centerLabel?: React.ReactNode;
+  /** Formatter for tooltip and hidden data-table values. @default toLocaleString */
+  valueFormat?: (value: number) => string;
+  /** Pixel height; the square chart is sized from this. @default 260 */
+  height?: number;
+  /** Per-slice colors (any CSS color), cycled when shorter than `data`. Defaults to the built-in token palette. */
+  colors?: string[];
+  /** Accessible name for the `<svg role="img">`. Per-slice values live in the hidden data table, not this label. Defaults to `"pie chart"`/`"donut chart"`; also accepts `aria-label`. */
+  ariaLabel?: string;
+  /** Render a visually-hidden data table as an accessible text alternative (WCAG 1.1.1). @default true */
+  tableFallback?: boolean;
+  /** Caption for the hidden data table; defaults to the chart's accessible label. */
+  caption?: React.ReactNode;
+}
+
+declare function PieChart(props: PieChartProps): React.JSX.Element;
+
+/** A single donut slice — same shape as {@link PieChartDatum}. */
+type DonutChartDatum = PieChartDatum;
+
+/**
+ * Donut chart — a {@link PieChart} preset rendered as a ring (hollow center).
+ * Accepts every PieChart prop; `donut` defaults to `true`.
+ *
+ * @startingPoint section="Data display" subtitle="Donut chart (no deps)" viewport="700x280"
+ */
+interface DonutChartProps extends PieChartProps {}
+
+declare function DonutChart(props: DonutChartProps): React.JSX.Element;
+
+/** One radial bar in a multi-ring gauge — a value plus an optional label/color. */
+interface GaugeSeries {
+  /** The ring's value, mapped through the shared `min`/`max` domain. */
+  value: number;
+  /** Legend label for this ring. */
+  label?: React.ReactNode;
+  /** Ring color (any CSS color); defaults to the built-in token palette, cycled. */
+  color?: string;
+}
+
+/**
+ * Radial gauge / radial-bar chart — renders a single `value` as a thick arc that
+ * sweeps between `startAngle` and `endAngle`, with the value + an optional caption
+ * in the center. Pass `series` to draw multiple concentric rings (radial-bar).
+ * Dependency-free inline SVG; every color/size is a design token so dark mode is
+ * automatic. For bar/line/area use `Chart`; for slices use `PieChart`/`DonutChart`.
+ *
+ * @startingPoint section="Data display" subtitle="Radial gauge / radial-bar (no deps)" viewport="700x280"
+ */
+interface GaugeProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "color"> {
+  /** The value to display, mapped from `min`..`max` onto the arc sweep. @default 0 */
+  value?: number;
+  /** Lower bound of the value domain (maps to `startAngle`). @default 0 */
+  min?: number;
+  /** Upper bound of the value domain (maps to `endAngle`). @default 100 */
+  max?: number;
+  /** Sweep start angle in degrees (0 = top, clockwise). @default -110 */
+  startAngle?: number;
+  /** Sweep end angle in degrees (0 = top, clockwise). @default 110 */
+  endAngle?: number;
+  /** Ring stroke width as a fraction of the radius. @default 0.16 */
+  thickness?: number;
+  /** Show the formatted value in the center (single gauge only). @default true */
+  showValue?: boolean;
+  /** Small caption rendered under the center value (single gauge only). */
+  label?: React.ReactNode;
+  /** Formats the center value + hidden-table cells; defaults to a rounded integer. */
+  valueFormat?: (value: number) => string;
+  /** Value-arc color (any CSS color). @default "var(--color-primary)" */
+  color?: string;
+  /** Background track color (any CSS color). @default "var(--color-surface-sunken)" */
+  trackColor?: string;
+  /** SVG width/height in pixels (the gauge is square). @default 200 */
+  size?: number;
+  /** Multiple concentric radial bars; when set, the single `value`/`label` are ignored. */
+  series?: GaugeSeries[];
+  /** Show the legend for a multi-ring (`series`) gauge. @default true */
+  showLegend?: boolean;
+  /** Accessible name for the `<svg role="img">`; defaults to a value summary. Also accepts `aria-label`. */
+  ariaLabel?: string;
+  /** Render a visually-hidden data table as an accessible text alternative (WCAG 1.1.1). @default true */
+  tableFallback?: boolean;
+  /** Caption for the hidden data table; defaults to the gauge's accessible label. */
+  caption?: React.ReactNode;
+}
+
+declare function Gauge(props: GaugeProps): React.JSX.Element;
+
+/**
+ * A Sparkline data point: either a bare number, or an object with a numeric
+ * `value` plus an optional `label` (used only for tooltips / the hidden table).
+ */
+type SparklineDatum = number | { value: number; label?: React.ReactNode };
+
+/**
+ * Sparkline — a minimal, word-sized trend chart (line, area, or bars) with no
+ * axes, grid, ticks, or legend, meant to sit inline beside text or inside a
+ * table cell / stat tile. Dependency-free inline SVG that scales to fill its
+ * vertical space, with an optional emphasised trailing dot. For a full chart
+ * with axes, tooltips, and a legend use the `Chart` component.
+ *
+ * @startingPoint section="Data display" subtitle="Tiny inline trend line (no deps)" viewport="700x280"
+ */
+interface SparklineProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "color"> {
+  /** Data points: bare numbers, or `{ value, label }` objects. */
+  data: SparklineDatum[];
+  /** Trend style. `"area"` fills below the line; `"bar"` draws thin columns. @default "line" */
+  type?: "line" | "area" | "bar";
+  /** Shorthand for `type="area"` (fills the region below the line). @default false */
+  area?: boolean;
+  /** Stroke / fill color (any CSS color). @default "var(--color-primary)" */
+  color?: string;
+  /** Viewbox width in pixels. @default 120 */
+  width?: number;
+  /** Pixel height. @default 40 */
+  height?: number;
+  /** Line stroke width in pixels (ignored for bars). @default 2 */
+  strokeWidth?: number;
+  /** Line/area interpolation. @default "smooth" */
+  curve?: "straight" | "smooth" | "stepped";
+  /** Emphasize the last point with a filled dot. @default false */
+  showDots?: boolean;
+  /** Pin the low end of the value scale (else derived from the data's minimum). */
+  min?: number;
+  /** Pin the high end of the value scale (else derived from the data's maximum). */
+  max?: number;
+  /** Value formatter for tooltips + the hidden data table. @default toLocaleString */
+  valueFormat?: (value: number) => string;
+  /** Accessible name for the `<svg role="img">`; defaults to a spoken summary (point count + first/last/min/max, or +latest when a table is present). Also accepts `aria-label`. */
+  ariaLabel?: string;
+  /** Render a visually-hidden data table as a text alternative (WCAG 1.1.1); off by default since the summarizing aria-label usually suffices for a sparkline. @default false */
+  tableFallback?: boolean;
+  /** Caption for the hidden data table; defaults to the accessible label. */
+  caption?: React.ReactNode;
+}
+
+declare function Sparkline(props: SparklineProps): React.JSX.Element;
+
+/** A single x/y point, with an optional `z` (bubble size) and a display `label`. */
+interface ScatterPoint {
+  /** Horizontal value (mapped to the x axis). */
+  x: number;
+  /** Vertical value (mapped to the y axis). */
+  y: number;
+  /** Optional third dimension — sizes the dot when the chart is in bubble mode. */
+  z?: number;
+  /** Optional per-point label used in the tooltip (falls back to the series name). */
+  label?: React.ReactNode;
+}
+
+/** One plotted series: an optional name/color plus its list of points. */
+interface ScatterSeries {
+  /** Series name — shown in the legend and used as the tooltip/table label. */
+  name?: string;
+  /** Series color (any CSS color); defaults to the built-in token palette, cycled. */
+  color?: string;
+  /** The series' data points. */
+  points: ScatterPoint[];
+}
+
+/**
+ * Scatter / bubble chart — plots x/y points across two nice-scaled numeric axes,
+ * one or many series, with grid, axis titles, tooltips, an optional legend and a
+ * hidden data table. Give points a numeric `z` (or set `bubble`) to size the dots
+ * by a third dimension. Dependency-free inline SVG; keeps its aspect ratio so the
+ * dots stay round. For bars/line/area use `Chart`; for other shapes use the
+ * dedicated sibling components.
+ *
+ * @startingPoint section="Data display" subtitle="Scatter / bubble plot (no deps)" viewport="700x280"
+ */
+interface ScatterChartProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "color"> {
+  /** The series to plot; each has optional `name`/`color` and a list of `{ x, y, z?, label? }` points. */
+  series: ScatterSeries[];
+  /** Size the dots by their `z` value (bubble chart). Auto-enabled when any point has a numeric `z`. @default false */
+  bubble?: boolean;
+  /** Maximum bubble radius in pixels (the largest `z` maps to this). @default 26 */
+  maxBubble?: number;
+  /** Fixed dot radius in pixels when not in bubble mode. @default 4.5 */
+  dotRadius?: number;
+  /** Pixel height (also sets the SVG aspect ratio). @default 300 */
+  height?: number;
+  /** Axis title drawn beneath the x axis. */
+  xLabel?: React.ReactNode;
+  /** Axis title drawn (rotated) beside the y axis. */
+  yLabel?: React.ReactNode;
+  /** Grid lines. @default true */
+  showGrid?: boolean;
+  /** Series legend. Defaults to `true` when there is more than one series. */
+  showLegend?: boolean;
+  /** Formatter for x values in tooltips + the hidden table (defaults to `valueFormat`). */
+  xFormat?: (value: number) => string;
+  /** Formatter for y values in tooltips + the hidden table (defaults to `valueFormat`). */
+  yFormat?: (value: number) => string;
+  /** Fallback value formatter for x/y/z (locale-grouped numbers by default). */
+  valueFormat?: (value: number) => string;
+  /** Accessible name for the chart's `<svg role="img">`. Per-point values are exposed via the hidden data table, not this label. Defaults to `"scatter chart"` / `"bubble chart"`; also accepts `aria-label`. */
+  ariaLabel?: string;
+  /** Render a visually-hidden data table as an accessible text alternative (WCAG 1.1.1). @default true */
+  tableFallback?: boolean;
+  /** Caption for the hidden data table; defaults to the chart's accessible label. */
+  caption?: React.ReactNode;
+}
+
+declare function ScatterChart(props: ScatterChartProps): React.JSX.Element;
+
+/**
+ * Bubble chart — a {@link ScatterChart} preset that sizes each dot by its point's
+ * `z` value. Accepts every ScatterChart prop; `bubble` defaults to `true`.
+ *
+ * @startingPoint section="Data display" subtitle="Bubble chart (no deps)" viewport="700x280"
+ */
+interface BubbleChartProps extends ScatterChartProps {}
+
+declare function BubbleChart(props: BubbleChartProps): React.JSX.Element;
+
+/**
+ * A radar-chart row: each row is one **axis** (category), carrying a `label`
+ * plus one numeric field per series key `K`. `K` is normally inferred from the
+ * `series` prop (e.g. `{ label: "Speed", team: 80, rival: 65 }`).
+ */
+type RadarDatum<K extends string = "value"> = { label: React.ReactNode } & { [P in K]: number };
+
+/**
+ * Radar / spider chart — one or more series drawn as closed polygons over a
+ * shared set of categorical axes radiating from a center, with concentric grid
+ * rings, spokes, per-axis labels, tooltips, and an optional legend. Dependency-free
+ * inline SVG. Generic over the series keys `K` so the data rows are type-checked
+ * (e.g. `<RadarChart series={["team"]} data={[{ label: "Speed", team: 80 }]} />`).
+ * For cartesian bars/lines/areas use `Chart`; for other shapes use the dedicated
+ * sibling components.
+ *
+ * @startingPoint section="Data display" subtitle="Radar / spider chart (no deps)" viewport="700x280"
+ */
+interface RadarChartProps<K extends string = "value"> extends React.HTMLAttributes<HTMLDivElement> {
+  /** Data rows — one per **axis**. Each has a `label` + one numeric field per series key. (`K` is inferred from `series`, not from `data`.) */
+  data: RadarDatum<NoInfer<K>>[];
+  /** Series field names to plot as polygons (defaults to `["value"]`). Multiple = several overlaid polygons. */
+  series?: K[];
+  /** Radial maximum (the value at the outer ring). Defaults to a "nice" ceiling of the largest datum. */
+  max?: number;
+  /** Number of concentric grid rings. @default 4 */
+  levels?: number;
+  /** Fill each polygon at low opacity (in addition to its stroke). @default true */
+  fill?: boolean;
+  /** Series legend. Defaults to `true` when more than one series is plotted, else `false`. */
+  showLegend?: boolean;
+  /** Draw a marker dot at each polygon vertex. @default true */
+  showDots?: boolean;
+  /** Per-series colors (any CSS color), cycled when shorter than `series`. Defaults to the built-in token palette. */
+  colors?: string[];
+  /** Tooltip value formatter (also formats the hidden data-table cells). */
+  valueFormat?: (value: number) => string;
+  /** Pixel height; the chart uses a square canvas of this size. @default 300 */
+  height?: number;
+  /** Accessible name for the chart's `<svg role="img">`. Per-point values are exposed via the hidden data table, not this label. Defaults to `"radar chart"`; also accepts `aria-label`. */
+  ariaLabel?: string;
+  /** Render a visually-hidden data table as an accessible text alternative (WCAG 1.1.1). @default true */
+  tableFallback?: boolean;
+  /** Caption for the hidden data table; defaults to the chart's accessible label. */
+  caption?: React.ReactNode;
+}
+
+declare function RadarChart<K extends string = "value">(props: RadarChartProps<K>): React.JSX.Element;
+
+/** A single polar-area slice: a `label`, its numeric `value`, and an optional override `color`. */
+interface PolarAreaDatum {
+  /** Category label — shown in the legend, the per-slice tooltip, and the hidden data table. */
+  label: React.ReactNode;
+  /** The value this slice encodes; its radius scales with the square root so the slice's area is proportional. */
+  value: number;
+  /** Optional fixed CSS color for this slice (overrides the cycled palette color). */
+  color?: string;
+}
+
+/**
+ * Polar-area (Coxcomb / Nightingale rose) chart — equal-angle slices whose
+ * *radius* encodes each value, laid over concentric value rings. Radius scales
+ * with `√value` so a slice's **area** is proportional to its value (the
+ * statistically honest encoding). Dependency-free inline SVG, with per-slice
+ * tooltips, an optional legend, and a visually-hidden data table. For plain
+ * proportional wedges use `PieChart` / `DonutChart`; for a spoked multi-axis
+ * shape use `RadarChart`.
+ *
+ * @startingPoint section="Data display" subtitle="Polar-area / rose chart (no deps)" viewport="700x280"
+ */
+interface PolarAreaChartProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Data points — one equal-angle slice each, in order clockwise from `startAngle`. */
+  data: PolarAreaDatum[];
+  /** Radial maximum (the value at the outer ring). Defaults to a "nice" ceiling of the largest value. */
+  max?: number;
+  /** Number of concentric grid rings (and value tick labels). @default 4 */
+  levels?: number;
+  /** Angle in degrees of the first slice's leading edge, clockwise from 12 o'clock. @default 0 */
+  startAngle?: number;
+  /** Show the per-slice legend. @default true */
+  showLegend?: boolean;
+  /** Tooltip value formatter (also formats the hidden data-table cells). @default fmtNumber */
+  valueFormat?: (value: number) => string;
+  /** Pixel height; the square plotting area is centered within the full-width container. @default 280 */
+  height?: number;
+  /** Per-slice colors (any CSS color), cycled across slices. Defaults to the built-in token palette. */
+  colors?: string[];
+  /** Accessible name for the chart's `<svg role="img">`. Defaults to `"polar area chart"`; also accepts `aria-label`. */
+  ariaLabel?: string;
+  /** Render a visually-hidden data table as an accessible text alternative (WCAG 1.1.1). @default true */
+  tableFallback?: boolean;
+  /** Caption for the hidden data table; defaults to the chart's accessible label. */
+  caption?: React.ReactNode;
+}
+
+declare function PolarAreaChart(props: PolarAreaChartProps): React.JSX.Element;
+
+/**
+ * One heatmap cell: an `x` (column) and `y` (row) coordinate plus a numeric
+ * `value` that drives the cell's color intensity. Missing (x, y) combinations
+ * render as faint empty cells.
+ */
+interface HeatmapDatum {
+  /** Column key. Column order follows first appearance in `data`. */
+  x: string | number;
+  /** Row key. Row order follows first appearance in `data`. */
+  y: string | number;
+  /** Numeric magnitude mapped onto the `min`…`max` color scale. */
+  value: number;
+}
+
+/**
+ * Heatmap — a matrix of colored cells keyed by (x, y), each shaded by a
+ * single-hue intensity scale between `min` and `max`. Ordered X columns and Y
+ * rows are derived from the data in first-seen order; absent cells render faint.
+ * Dependency-free inline SVG, with per-cell tooltips, a gradient scale legend,
+ * and a visually-hidden data table. Dark mode is automatic through tokens.
+ *
+ * @startingPoint section="Data display" subtitle="Matrix heatmap (no deps)" viewport="700x280"
+ */
+interface HeatmapProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Cells to plot. X columns and Y rows are derived from these in first-seen order. */
+  data: HeatmapDatum[];
+  /** Low end of the color scale. Defaults to the minimum value in `data`. */
+  min?: number;
+  /** High end of the color scale. Defaults to the maximum value in `data`. */
+  max?: number;
+  /** Base token color for the high end; cells mix it over transparent by intensity. @default "var(--brand-500)" */
+  colorScale?: string;
+  /** Print each cell's formatted value at its center. @default false */
+  showValues?: boolean;
+  /** Gap in pixels between adjacent cells. @default 2 */
+  cellGap?: number;
+  /** Cell corner radius in pixels. @default 2 */
+  radius?: number;
+  /** Optional title rendered beneath the X-axis category labels. */
+  xLabel?: React.ReactNode;
+  /** Optional title rendered rotated alongside the Y-axis category labels. */
+  yLabel?: React.ReactNode;
+  /** Show the low→high gradient scale legend below the grid. @default true */
+  showLegend?: boolean;
+  /** Value formatter for tooltips, printed cell values, and the hidden table. @default fmtNumber */
+  valueFormat?: (value: number) => string;
+  /** Pixel height of the chart. @default 300 */
+  height?: number;
+  /** Accessible name for the chart's `<svg role="img">`. Per-cell values are exposed via the hidden data table, not this label. Defaults to `"heatmap"`; also accepts `aria-label`. */
+  ariaLabel?: string;
+  /** Render a visually-hidden data table as an accessible text alternative (WCAG 1.1.1). @default true */
+  tableFallback?: boolean;
+  /** Caption for the hidden data table; defaults to the chart's accessible label. */
+  caption?: React.ReactNode;
+}
+
+declare function Heatmap(props: HeatmapProps): React.JSX.Element;
+
+/** A funnel stage: a `label`, its numeric `value`, and an optional override `color`. */
+interface FunnelDatum {
+  /** Stage name, rendered centered on the band and in the hidden data table. */
+  label: React.ReactNode;
+  /** Stage magnitude. Band width (or height, when horizontal) is scaled to the largest stage. */
+  value: number;
+  /** Optional fill for this stage (any CSS color); defaults to the cycled token palette. */
+  color?: string;
+}
+
+/**
+ * Funnel chart — descending stages drawn as centered trapezoids that taper from
+ * each stage's value to the next, for conversion / drop-off flows. Each band is
+ * scaled to the largest stage, with the top stage as the 100% baseline for the
+ * per-stage percentage. Dependency-free inline SVG with per-band `<title>` tooltips
+ * and a visually-hidden data table. For bars/lines/areas use `Chart`; for part-of-whole
+ * shares use `PieChart`.
+ *
+ * @startingPoint section="Data display" subtitle="Descending funnel stages (no deps)" viewport="700x280"
+ */
+interface FunnelChartProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Funnel stages, ordered from the widest/top stage to the narrowest. */
+  data: FunnelDatum[];
+  /** Print each stage's formatted value in its centered caption. @default true */
+  showValues?: boolean;
+  /** Print each stage's percentage of the first (top) stage in its caption. @default true */
+  showPercent?: boolean;
+  /** Lay the funnel out left→right (tapering vertically) instead of top→bottom. @default false */
+  horizontal?: boolean;
+  /** Pixel gap between adjacent stages. @default 2 */
+  gap?: number;
+  /** Pixel height of the chart. @default 300 */
+  height?: number;
+  /** Per-stage colors (any CSS color), cycled when shorter than `data`. Defaults to the token palette. */
+  colors?: string[];
+  /** Value formatter for captions, tooltips, and the hidden data-table cells. @default toLocaleString */
+  valueFormat?: (value: number) => string;
+  /** Accessible name for the chart's `<svg role="img">`; per-stage values live in the hidden table. Defaults to `"funnel chart"`; also accepts `aria-label`. */
+  ariaLabel?: string;
+  /** Render a visually-hidden data table as an accessible text alternative (WCAG 1.1.1). @default true */
+  tableFallback?: boolean;
+  /** Caption for the hidden data table; defaults to the chart's accessible label. */
+  caption?: React.ReactNode;
+}
+
+declare function FunnelChart(props: FunnelChartProps): React.JSX.Element;
+
+/** One treemap tile: a `label`, its numeric `value` (relative area), and an optional override `color`. */
+interface TreemapDatum {
+  /** Tile label — rendered inside the tile when it fits and as the data-table row header. */
+  label: React.ReactNode;
+  /** Non-negative magnitude; the tile's area is this value as a share of the total (negatives are clamped to 0). */
+  value: number;
+  /** Optional per-tile fill (any CSS color); overrides the cycled palette color for this tile. */
+  color?: string;
+}
+
+/**
+ * Treemap — a squarified partition of a rectangle into tiles sized in proportion
+ * to a flat list of values (Bruls/Huizing/van Wijk squarified layout), packed to
+ * keep tile aspect ratios near 1:1. Dependency-free inline SVG with per-tile
+ * labels, hover tooltips, and a visually-hidden data table. Good for showing the
+ * relative weight of parts within a whole (spend by category, storage by bucket).
+ *
+ * @startingPoint section="Data display" subtitle="Squarified treemap (no deps)" viewport="700x280"
+ */
+interface TreemapProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Tiles to lay out. Each has a `label`, a non-negative `value`, and an optional `color`. */
+  data: TreemapDatum[];
+  /** Draw the value under the label inside tiles tall enough to fit both lines. @default true */
+  showValues?: boolean;
+  /** Formatter for the tooltip, in-tile value, and data-table cells. @default toLocaleString */
+  valueFormat?: (value: number) => string;
+  /** Pixel height (also sets the SVG's aspect ratio; width fills the container). @default 300 */
+  height?: number;
+  /** Tile colors (any CSS color), cycled by index. Defaults to the built-in token palette; a datum's `color` wins. */
+  colors?: string[];
+  /** Gap in px inset between adjacent tiles. @default 2 */
+  gap?: number;
+  /** Accessible name for the chart's `<svg role="img">`. Per-tile values are exposed via the hidden data table, not this label. Defaults to `"treemap"`; also accepts `aria-label`. */
+  ariaLabel?: string;
+  /** Render a visually-hidden data table (value + share) as an accessible text alternative (WCAG 1.1.1). @default true */
+  tableFallback?: boolean;
+  /** Caption for the hidden data table; defaults to the chart's accessible label. */
+  caption?: React.ReactNode;
+}
+
+declare function Treemap(props: TreemapProps): React.JSX.Element;
+
+/**
+ * One OHLC period: a `label` plus the `open`, `high`, `low` and `close` prices.
+ * The body spans open→close and the wick spans low→high.
+ */
+interface CandlestickDatum {
+  /** Period label shown on the x axis (and in the hidden data table). */
+  label: React.ReactNode;
+  /** Opening price for the period. */
+  open: number;
+  /** Highest price reached in the period (top of the wick). */
+  high: number;
+  /** Lowest price reached in the period (bottom of the wick). */
+  low: number;
+  /** Closing price for the period; `close >= open` renders an up (green) candle. */
+  close: number;
+}
+
+/**
+ * Candlestick (OHLC) chart — one candle per period with a high→low wick and an
+ * open→close body, colored by direction (up vs. down), plus a shared value axis,
+ * grid, per-candle tooltips and an accessible data table. Dependency-free inline
+ * SVG. For bars/lines/areas use `Chart`; for other shapes use the dedicated
+ * sibling chart components.
+ *
+ * @startingPoint section="Data display" subtitle="OHLC candlestick chart (no deps)" viewport="700x280"
+ */
+interface CandlestickProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** OHLC data points, one candle each, in chronological order. */
+  data: CandlestickDatum[];
+  /** Color for up candles (`close >= open`), any CSS color. @default "var(--color-success)" */
+  upColor?: string;
+  /** Color for down candles (`close < open`), any CSS color. @default "var(--color-danger)" */
+  downColor?: string;
+  /** Pixel height. @default 300 */
+  height?: number;
+  /** Horizontal value grid lines. @default true */
+  showGrid?: boolean;
+  /** Value axis + category labels. @default true */
+  showAxis?: boolean;
+  /** Tooltip value formatter (also formats the hidden data-table cells). @default toLocaleString */
+  valueFormat?: (value: number) => string;
+  /** Accessible name for the chart's `<svg role="img">`. Defaults to `"candlestick chart"`; also accepts `aria-label`. */
+  ariaLabel?: string;
+  /** Render a visually-hidden data table as an accessible text alternative (WCAG 1.1.1). @default true */
+  tableFallback?: boolean;
+  /** Caption for the hidden data table; defaults to the chart's accessible label. */
+  caption?: React.ReactNode;
+}
+
+declare function Candlestick(props: CandlestickProps): React.JSX.Element;
+
+/**
+ * A single box-and-whisker summary: a `label` plus the five-number distribution
+ * (`min`, `q1`, `median`, `q3`, `max`) and optional `outliers` drawn as points.
+ */
+interface BoxplotDatum {
+  /** Category label, rendered under the box and in the hidden data table. */
+  label: React.ReactNode;
+  /** Lower whisker end (distribution minimum, excluding outliers). */
+  min: number;
+  /** First quartile — the bottom edge of the box. */
+  q1: number;
+  /** Median — the bold line inside the box. */
+  median: number;
+  /** Third quartile — the top edge of the box. */
+  q3: number;
+  /** Upper whisker end (distribution maximum, excluding outliers). */
+  max: number;
+  /** Individual outlier values drawn as small circles beyond the whiskers. */
+  outliers?: number[];
+}
+
+/**
+ * Box-and-whisker chart — one box per category summarising a five-number
+ * distribution (min, Q1, median, Q3, max) with whiskers, a bold median line,
+ * and optional outlier points. Dependency-free inline SVG, theme-aware via
+ * design tokens. For bar/line/area use `Chart`; for other shapes use the
+ * dedicated sibling components.
+ *
+ * @startingPoint section="Data display" subtitle="Box-and-whisker distribution chart" viewport="700x280"
+ */
+interface BoxplotProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** The boxes to plot, one per category, each a five-number summary. */
+  data: BoxplotDatum[];
+  /** Box fill/stroke accent (any CSS color). @default "var(--color-primary)" */
+  color?: string;
+  /** Pixel height. @default 300 */
+  height?: number;
+  /** Horizontal grid lines at the value ticks. @default true */
+  showGrid?: boolean;
+  /** Value axis and category labels. @default true */
+  showAxis?: boolean;
+  /** Tooltip/table value formatter. @default toLocaleString */
+  valueFormat?: (value: number) => string;
+  /** Accessible name for the chart's `<svg role="img">`. Per-box values are exposed via the hidden data table, not this label. @default "box plot" */
+  ariaLabel?: string;
+  /** Render a visually-hidden data table as an accessible text alternative (WCAG 1.1.1). @default true */
+  tableFallback?: boolean;
+  /** Caption for the hidden data table; defaults to the chart's accessible label. */
+  caption?: React.ReactNode;
+}
+
+declare function Boxplot(props: BoxplotProps): React.JSX.Element;
+
+/**
+ * One range value: a `label` plus its numeric `min` and `max` bounds. For a
+ * range bar this is the start→end of a timeline row; for a range area it is the
+ * lower/upper value at that category position.
+ */
+interface RangeDatum {
+  /** Row/category label — shown on the axis and in the hidden data table. */
+  label: React.ReactNode;
+  /** Lower bound of the range (bar start / lower band edge). */
+  min: number;
+  /** Upper bound of the range (bar end / upper band edge). */
+  max: number;
+  /** Optional per-row bar color (any CSS color); overrides the palette. Applies to `type="bar"` only. */
+  color?: string;
+}
+
+/**
+ * Range chart — horizontal range bars (a timeline / Gantt of one min→max band
+ * per row) or a range area (a shaded band between a per-category min line and
+ * max line), with a shared value axis, grid, tooltips and an accessible data
+ * table. Dependency-free inline SVG. For bars/lines/areas use `Chart`; for other
+ * shapes use the dedicated sibling chart components.
+ *
+ * @startingPoint section="Data display" subtitle="Range bar / range area chart (no deps)" viewport="700x280"
+ */
+interface RangeChartProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** `"bar"` = horizontal range bars (timeline/Gantt); `"area"` = a band between a min and max line. @default "bar" */
+  type?: "bar" | "area";
+  /** Range data points, each with a `label`, `min` and `max` (bars run top→bottom; the area runs left→right). */
+  data: RangeDatum[];
+  /** Pixel height. @default 300 */
+  height?: number;
+  /** Value grid lines (vertical for bars, horizontal for the area). @default true */
+  showGrid?: boolean;
+  /** Value axis + category labels. @default true */
+  showAxis?: boolean;
+  /** Palette for bar fills / the area band, cycled by index. Defaults to the built-in token palette. */
+  colors?: string[];
+  /** Tooltip value formatter (also formats the hidden data-table cells). @default toLocaleString */
+  valueFormat?: (value: number) => string;
+  /** Accessible name for the chart's `<svg role="img">`. Defaults to `"range <type> chart"`; also accepts `aria-label`. */
+  ariaLabel?: string;
+  /** Render a visually-hidden data table as an accessible text alternative (WCAG 1.1.1). @default true */
+  tableFallback?: boolean;
+  /** Caption for the hidden data table; defaults to the chart's accessible label. */
+  caption?: React.ReactNode;
+}
+
+declare function RangeChart(props: RangeChartProps): React.JSX.Element;
+
 /**
  * Checkbox with animated checkmark, label, description, and indeterminate state.
  */
@@ -2840,4 +3504,4 @@ declare function useFocusTrap<T extends HTMLElement = HTMLElement>(
  */
 declare function usePortal(): (node: React.ReactNode) => React.ReactPortal | React.ReactNode | null;
 
-export { Accordion, type AccordionItem, type AccordionProps, type ActionTone, Alert, type AlertProps, Anchor, type AnchorProps, AppShell, type AppShellProps, Avatar, AvatarMenu, type AvatarMenuProps, type AvatarProps, Badge, type BadgeProps, type BarTone, Box, type BoxOwnProps, type BoxProps, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, Button, type ButtonProps, Card, type CardProps, Carousel, type CarouselProps, Chart, type ChartDatum, type ChartProps, Checkbox, type CheckboxProps, Code, type CodeProps, ColorPicker, type ColorPickerProps, ColorSchemeScript, type ColorSchemeScriptOptions, type ColorSchemeScriptProps, Combobox, type ComboboxGroup, type ComboboxOption, type ComboboxProps, type Command, CommandPalette, type CommandPaletteProps, Container, type ContainerOwnProps, type ContainerProps, Currency, CurrencyField, type CurrencyFieldProps, type CurrencyOption, type CurrencyProps, Datatable, type DatatableBatchAction, type DatatableColumn, type DatatableFilter, type DatatableFilterOp, type DatatableNumberOp, type DatatableProps, type DatatableQuery, type DatatableRowAction, type DatatableStringOp, DatePicker, type DatePickerProps, type DateRange, DateRangePicker, type DateRangePickerProps, Dialog, type DialogProps, Divider, type DividerProps, Drawer, type DrawerProps, EmptyState, type EmptyStateProps, Field, type FieldProps, FileUpload, type FileUploadProps, Form, type FormProps, Grid, type GridOwnProps, type GridProps, Heading, type HeadingOwnProps, type HeadingProps, type HeadingSize, IconButton, type IconButtonProps, Image, type ImageProps, Input, type InputProps, Kanban, type KanbanCard, type KanbanColumn, type KanbanProps, Kbd, type KbdProps, Label, type LabelProps, List, type ListItemData, type ListProps, Menu, type MenuItemDef, type MenuProps, MultiSelect, type MultiSelectGroup, type MultiSelectOption, type MultiSelectProps, Navbar, type NavbarLink, type NavbarProps, type Option, type OptionGroup, Pagination, type PaginationProps, type PolymorphicAs, type PolymorphicComponent, type PolymorphicProps, type PolymorphicPropsWithRef, type PolymorphicRef, Popover, type PopoverProps, Portal, type PortalProps, Pre, type PreProps, Progress, type ProgressProps, Radio, RadioGroup, type RadioGroupOption, type RadioGroupProps, type RadioProps, Rating, type RatingProps, type ResponsiveColumns, Select, type SelectGroup, type SelectOption, type SelectProps, Sidebar, type SidebarItem, type SidebarProps, Skeleton, type SkeletonProps, Slider, type SliderProps, Spinner, type SpinnerProps, Stack, type StackOwnProps, type StackProps, Stat, type StatProps, type Step, Stepper, type StepperProps, Switch, type SwitchProps, type Sx, type TabItem, Table, type TableColumn, type TableProps, Tabs, type TabsProps, Tag, type TagProps, Text, type TextOwnProps, type TextProps, type TextTone, Textarea, type TextareaProps, type Theme, ThemeProvider, type ThemeProviderProps, type ThemeTokens, Timeline, type TimelineItem, type TimelineProps, Toast, type ToastApi, type ToastOptions, type ToastProps, ToastProvider, type ToastProviderProps, type ToastTone, ToastViewport, type ToastViewportProps, type Tone, Tooltip, type TooltipProps, type TreeNode, TreeView, type TreeViewProps, TwicoProvider, type TwicoProviderProps, type UseColorSchemeOptions, type UseFocusTrapOptions, type UseKeyPressOptions, type UseMediaQueryOptions, VisuallyHidden, type VisuallyHiddenProps, createTheme, getColorSchemeScript, runDatatableQuery, useClickOutside, useColorScheme, useControllableState, useCopyToClipboard, useDebouncedCallback, useDebouncedValue, useDisclosure, useEventListener, useFocusTrap, useHover, useId, useIntersectionObserver, useInterval, useIsomorphicLayoutEffect, useKeyPress, useLocalStorage, useMediaQuery, useMounted, usePortal, usePrefersReducedMotion, usePrevious, useScrollLock, useTimeout, useToast, useToggle, useWindowSize };
+export { Accordion, type AccordionItem, type AccordionProps, type ActionTone, Alert, type AlertProps, Anchor, type AnchorProps, AppShell, type AppShellProps, Avatar, AvatarMenu, type AvatarMenuProps, type AvatarProps, Badge, type BadgeProps, type BarTone, Box, type BoxOwnProps, type BoxProps, Boxplot, type BoxplotDatum, type BoxplotProps, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, BubbleChart, type BubbleChartProps, Button, type ButtonProps, Candlestick, type CandlestickDatum, type CandlestickProps, Card, type CardProps, Carousel, type CarouselProps, Chart, type ChartDatum, type ChartProps, Checkbox, type CheckboxProps, Code, type CodeProps, ColorPicker, type ColorPickerProps, ColorSchemeScript, type ColorSchemeScriptOptions, type ColorSchemeScriptProps, Combobox, type ComboboxGroup, type ComboboxOption, type ComboboxProps, type Command, CommandPalette, type CommandPaletteProps, Container, type ContainerOwnProps, type ContainerProps, Currency, CurrencyField, type CurrencyFieldProps, type CurrencyOption, type CurrencyProps, Datatable, type DatatableBatchAction, type DatatableColumn, type DatatableFilter, type DatatableFilterOp, type DatatableNumberOp, type DatatableProps, type DatatableQuery, type DatatableRowAction, type DatatableStringOp, DatePicker, type DatePickerProps, type DateRange, DateRangePicker, type DateRangePickerProps, Dialog, type DialogProps, Divider, type DividerProps, DonutChart, type DonutChartDatum, type DonutChartProps, Drawer, type DrawerProps, EmptyState, type EmptyStateProps, Field, type FieldProps, FileUpload, type FileUploadProps, Form, type FormProps, FunnelChart, type FunnelChartProps, type FunnelDatum, Gauge, type GaugeProps, type GaugeSeries, Grid, type GridOwnProps, type GridProps, Heading, type HeadingOwnProps, type HeadingProps, type HeadingSize, Heatmap, type HeatmapDatum, type HeatmapProps, IconButton, type IconButtonProps, Image, type ImageProps, Input, type InputProps, Kanban, type KanbanCard, type KanbanColumn, type KanbanProps, Kbd, type KbdProps, Label, type LabelProps, List, type ListItemData, type ListProps, Menu, type MenuItemDef, type MenuProps, MultiSelect, type MultiSelectGroup, type MultiSelectOption, type MultiSelectProps, Navbar, type NavbarLink, type NavbarProps, type Option, type OptionGroup, Pagination, type PaginationProps, PieChart, type PieChartDatum, type PieChartProps, PolarAreaChart, type PolarAreaChartProps, type PolarAreaDatum, type PolymorphicAs, type PolymorphicComponent, type PolymorphicProps, type PolymorphicPropsWithRef, type PolymorphicRef, Popover, type PopoverProps, Portal, type PortalProps, Pre, type PreProps, Progress, type ProgressProps, RadarChart, type RadarChartProps, type RadarDatum, Radio, RadioGroup, type RadioGroupOption, type RadioGroupProps, type RadioProps, RangeChart, type RangeChartProps, type RangeDatum, Rating, type RatingProps, type ResponsiveColumns, ScatterChart, type ScatterChartProps, type ScatterPoint, type ScatterSeries, Select, type SelectGroup, type SelectOption, type SelectProps, Sidebar, type SidebarItem, type SidebarProps, Skeleton, type SkeletonProps, Slider, type SliderProps, Sparkline, type SparklineDatum, type SparklineProps, Spinner, type SpinnerProps, Stack, type StackOwnProps, type StackProps, Stat, type StatProps, type Step, Stepper, type StepperProps, Switch, type SwitchProps, type Sx, type TabItem, Table, type TableColumn, type TableProps, Tabs, type TabsProps, Tag, type TagProps, Text, type TextOwnProps, type TextProps, type TextTone, Textarea, type TextareaProps, type Theme, ThemeProvider, type ThemeProviderProps, type ThemeTokens, Timeline, type TimelineItem, type TimelineProps, Toast, type ToastApi, type ToastOptions, type ToastProps, ToastProvider, type ToastProviderProps, type ToastTone, ToastViewport, type ToastViewportProps, type Tone, Tooltip, type TooltipProps, type TreeNode, TreeView, type TreeViewProps, Treemap, type TreemapDatum, type TreemapProps, TwicoProvider, type TwicoProviderProps, type UseColorSchemeOptions, type UseFocusTrapOptions, type UseKeyPressOptions, type UseMediaQueryOptions, VisuallyHidden, type VisuallyHiddenProps, createTheme, getColorSchemeScript, runDatatableQuery, useClickOutside, useColorScheme, useControllableState, useCopyToClipboard, useDebouncedCallback, useDebouncedValue, useDisclosure, useEventListener, useFocusTrap, useHover, useId, useIntersectionObserver, useInterval, useIsomorphicLayoutEffect, useKeyPress, useLocalStorage, useMediaQuery, useMounted, usePortal, usePrefersReducedMotion, usePrevious, useScrollLock, useTimeout, useToast, useToggle, useWindowSize };