@elabs-ai/components-data 4.1.0 → 5.0.0

package/dist/index.d.ts

@@ -1,14 +1,200 @@
 import * as react from 'react';
-import { ReactNode, InputHTMLAttributes, ButtonHTMLAttributes, Ref, ReactElement } from 'react';
-import { RowData, ColumnDef, Table, SortingState, OnChangeFn, VisibilityState, ColumnFiltersState, PaginationState, ColumnPinningState, ColumnSizingState, RowSelectionState, Row } from '@tanstack/react-table';
+import { CSSProperties, ReactNode, InputHTMLAttributes, ButtonHTMLAttributes, Ref, ReactElement, TdHTMLAttributes, ThHTMLAttributes, LiHTMLAttributes, HTMLAttributes } from 'react';
+import { RowPinningState, RowData, ColumnDef, Table, SortingState, OnChangeFn, VisibilityState, ColumnFiltersState, PaginationState, ColumnPinningState, ColumnSizingState, RowSelectionState, Row } from '@tanstack/react-table';
 export { CellContext, ColumnDef, ColumnMeta, ColumnPinningState, ColumnSizingState, Row, RowSelectionState, Table } from '@tanstack/react-table';
-import { FilterChipProps as FilterChipProps$1 } from '@elabs-ai/components-ui';
+import { ColorScaleDomain, FilterChipProps as FilterChipProps$1, ColorScale, ColorScaleSpec } from '@elabs-ai/components-ui';
 
 /**
- * `DataTable`'s `columnDef.meta` contract, read by the header/body/skeleton
- * cell renderers. Set `numeric: true` on a column to get `tabular-nums` +
- * end-alignment on both the `<th>` and every `<td>` (including the loading
- * skeleton) for free.
+ * sticky-rows.ts — `DataTable`'s `stickyRows` (RM-123): rows such as an
+ * "average" or "total" that stay at the top or bottom of EVERY page and after
+ * every sort.
+ *
+ * Built on TanStack's own row pinning (`keepPinnedRows`), so the table model is
+ * unchanged: a sticky row keeps its id, its selection and its `data` index; it
+ * is only rendered outside the sorted / paged centre rows.
+ */
+type DataTableStickyRowPosition = "top" | "bottom";
+/** Decides, per record, whether its row sticks to the top or the bottom (or neither). */
+type DataTableStickyRows<TData> = (row: TData, index: number) => DataTableStickyRowPosition | undefined;
+/**
+ * The TanStack `rowPinning` state for `stickyRows` over `data`, in data order.
+ * Row ids follow TanStack's own rule: `getRowId(row, index)`, else the index.
+ */
+declare function stickyRowPinning<TData>(data: readonly TData[], stickyRows: DataTableStickyRows<TData> | undefined, getRowId?: (row: TData, index: number) => string): RowPinningState;
+
+/** A table container's width tier. */
+type DataTableBreakpoint = "narrow" | "wide";
+/** A width (CSS px) below `narrow` is narrow. */
+declare const DATA_TABLE_BREAKPOINT_THRESHOLDS: {
+    readonly narrow: 450;
+};
+/** The tier for a measured container width. */
+declare function tableBreakpointForWidth(width: number): DataTableBreakpoint;
+/**
+ * Measures the element the returned `ref` is attached to with a
+ * `ResizeObserver` and returns its tier. Re-renders only when the TIER changes.
+ * `enabled: false` skips the observer entirely (a table that uses no
+ * breakpoint behaviour pays nothing).
+ */
+declare function useTableBreakpoint<E extends Element = HTMLDivElement>(enabled?: boolean): {
+    ref: (node: E | null) => void;
+    breakpoint: DataTableBreakpoint;
+};
+
+/**
+ * column-meta.ts — the typed `columnDef.meta` contract `DataTable` reads.
+ *
+ * `numeric` / `align` (#69) style a column; everything else is the editorial
+ * presentation layer (RM-123): an in-cell visual, a number format, categorical
+ * colouring, per-breakpoint visibility and column sizing. Every key is optional
+ * and a column without them renders exactly as before.
+ *
+ * `data` never imports `@elabs-ai/components-charts` (one-way dependency
+ * graph), so the number-format shape below is a STRUCTURAL twin of charts'
+ * `ChartValueFormatSpec` (RM-109): a spec written for a chart type-checks here
+ * unchanged, and formats the same way.
+ */
+/**
+ * A number format — the same object shape as charts' `ChartValueFormatSpec`.
+ *
+ * - `style`: `"number"` (default), `"currency"`, or `"percent"` (fraction in,
+ *   `%` out).
+ * - `decimals`: maximum fraction digits. `optionalDecimals: false` makes it
+ *   the minimum too.
+ * - `abbreviate`: `true` always compact (`1.5K`), `false` never, `"auto"`
+ *   (default) from 1,000 up. Percent is never compacted.
+ * - `sign`: `"auto"` (minus only), `"always"` (`+`/`-`), `"parens"` (`(12)`).
+ * - `prefix` / `suffix`: literal text around the number.
+ * - `grouping: false` drops the thousands separator.
+ * - `currency`: ISO 4217 code for `style: "currency"` (default `"USD"`).
+ */
+interface DataTableValueFormatSpec {
+    style?: "number" | "currency" | "percent";
+    decimals?: number;
+    optionalDecimals?: boolean;
+    abbreviate?: boolean | "auto";
+    sign?: "auto" | "always" | "parens";
+    prefix?: string;
+    suffix?: string;
+    grouping?: boolean;
+    currency?: string;
+}
+/** An in-cell bar: the value as a horizontal bar from zero. */
+interface DataTableBarVisual {
+    kind: "bar";
+    /** `"regular"` (default) sits beside the value; `"slim"` is a thin rule under it. */
+    style?: "regular" | "slim";
+    /** Paint the grey remainder of the range behind the bar. */
+    track?: boolean;
+    /**
+     * The range a full-width bar spans. `"column"` (default): this column's own
+     * min / max; `"table"`: shared by every bar column with `range: "table"`;
+     * `[min, max]`: fixed. Zero is always inside the range.
+     */
+    range?: readonly [min: number, max: number] | "column" | "table";
+    /** Row key whose category picks the bar colour (`--chart-1…12`). */
+    colorBy?: string;
+    /**
+     * The `colorBy` key's title, or `false` to draw no key. Default `true`: a
+     * category carried by hue alone is unreadable without one (WCAG 1.4.1), so
+     * the key is opt-OUT — turn it off only when the table prints the category
+     * in a column of its own.
+     */
+    legend?: string | boolean;
+    /** Paint negative values in the negative token. Default `true`. */
+    negative?: boolean;
+}
+/** An in-cell sparkline across several numeric row keys (one point per key). */
+interface DataTableSparklineVisual {
+    kind: "sparkline";
+    /** Row keys, in x order. */
+    keys: readonly string[];
+    /** Fill the area under the line. */
+    fill?: boolean;
+    /** `"ends"` prints the first and last values beside the line. Default `"none"`. */
+    labels?: "ends" | "none";
+    /** Drawing height in px. Default 24. */
+    height?: number;
+    /** `"cell"` (default): this row's own min / max; `"column"`: shared by every row. */
+    range?: "cell" | "column";
+}
+/** In-cell mini columns across several numeric row keys. */
+interface DataTableColumnsVisual {
+    kind: "columns";
+    keys: readonly string[];
+    /** Drawing height in px. Default 24. */
+    height?: number;
+    /** `"cell"` (default): this row's own max; `"column"`: shared by every row. */
+    range?: "cell" | "column";
+}
+/**
+ * A heatmap colour scale. Resolved by `colorScaleFor` (`@elabs-ai/components-ui`),
+ * so the colours are `--chart-seq-*` / `--chart-div-*` ramp tokens.
+ */
+interface DataTableHeatmapScale {
+    /** `"stepped"` cuts countable classes; `"continuous"` snaps to the nearest ramp step. */
+    type: "stepped" | "continuous";
+    /** How many classes (stepped) or Jenks classes (continuous `jenks`). Default 5. */
+    steps?: number;
+    /**
+     * `"linear"` (default) equal widths; `"quantile"` equal counts; `"jenks"`
+     * natural breaks; `"custom"` the `breaks` you pass (always stepped).
+     */
+    method?: "linear" | "quantile" | "jenks" | "custom";
+    /** `method: "custom"` only: the inner thresholds, ascending. */
+    breaks?: readonly number[];
+    /** `[min, max]`, or `[min, center, max]` to pin the ramp's middle colour. */
+    domain?: ColorScaleDomain;
+    /** Default `"diverging"` when `domain` has a centre, else `"sequential"`. */
+    palette?: "sequential" | "diverging";
+}
+/** The cell's background is the value's ramp colour. */
+interface DataTableHeatmapVisual {
+    kind: "heatmap";
+    scale: DataTableHeatmapScale;
+    /** Hide the printed value visually; screen readers, sorting and copy still read it. */
+    hideValue?: boolean;
+    /**
+     * Print the scale's colour key above the table. `true` titles it with the
+     * column header; a string is the title (use it when one heatmap spans several
+     * columns — the key is printed once per shared scale).
+     */
+    legend?: boolean | string;
+}
+type DataTableCellVisual = DataTableBarVisual | DataTableSparklineVisual | DataTableColumnsVisual | DataTableHeatmapVisual;
+/**
+ * Categorical conditional formatting: the category in row key `key` picks a
+ * `--chart-1…12` colour, painted as a background wash or as text ink, on this
+ * column's cell or on the whole row.
+ */
+interface DataTableColorBy {
+    key: string;
+    target: "background" | "text";
+    /** Default `"cell"`. */
+    scope?: "cell" | "row";
+    /**
+     * The colour key's title, or `false` to draw none. Default `true` — see
+     * `DataTableBarVisual.legend`.
+     */
+    legend?: string | boolean;
+}
+/**
+ * Show a column at a table breakpoint. `true` / `false` for every width, or
+ * `{ base, narrow }`: `base` is the wide value, `narrow` applies below 450 px.
+ */
+type DataTableShowAt = boolean | {
+    base: boolean;
+    narrow?: boolean;
+};
+/** `markdown: true` or options. Images are off unless `images: true`. */
+interface DataTableMarkdownOptions {
+    images?: boolean;
+}
+/**
+ * `DataTable`'s `columnDef.meta` contract, read by the header, body, card and
+ * skeleton cell renderers. Set `numeric: true` on a column to get
+ * `tabular-nums` + end-alignment on both the `<th>` and every `<td>`
+ * (including the loading skeleton) for free.
  */
 interface DataTableColumnMeta {
     /** Numeric column: tabular figures + end alignment on header and cells. */
@@ -20,11 +206,42 @@ interface DataTableColumnMeta {
      * alignment away from `"end"`.
      */
     align?: "start" | "center" | "end";
+    /**
+     * An in-cell visual (bar, sparkline, mini columns, heatmap). The cell keeps
+     * its value as text — visually hidden only with `hideValue` — so sorting,
+     * copy and screen readers still read the number. Replaces the column's
+     * `cell` renderer.
+     */
+    visual?: DataTableCellVisual;
+    /** Number format for the printed value (the charts `valueFormat` object shape). */
+    format?: DataTableValueFormatSpec;
+    /** Categorical colouring driven by another row key. */
+    colorBy?: DataTableColorBy;
+    /** Per-breakpoint visibility; render-only, never written to `columnVisibility`. */
+    showAt?: DataTableShowAt;
+    /** Column width as a percentage of the table width. */
+    width?: number;
+    /** Minimum column width in px. */
+    minWidth?: number;
+    /** Extra inline style on this column's header and body cells. */
+    style?: CSSProperties;
+    /** Render a string value as safe inline markdown (bold, italic, links, `sup`, `code`). */
+    markdown?: boolean | DataTableMarkdownOptions;
 }
 declare module "@tanstack/react-table" {
     interface ColumnMeta<TData extends RowData, TValue> extends DataTableColumnMeta {
     }
 }
+/**
+ * The printed text for a cell value. Numbers go through `format` (or the
+ * locale's plain number format); anything else is stringified; nullish is `""`.
+ */
+declare function formatCellValue(value: unknown, format: DataTableValueFormatSpec | undefined, formatNumber: (n: number, opts?: Intl.NumberFormatOptions) => string): string;
+/** Whether a column is shown at `breakpoint` (no `showAt` → always). */
+declare function resolveShowAt(showAt: DataTableShowAt | undefined, breakpoint: DataTableBreakpoint): boolean;
+/** The inline style for `meta.width` (%), `meta.minWidth` (px) and `meta.style`. */
+declare function columnSizeStyle(meta: DataTableColumnMeta | undefined): CSSProperties | undefined;
+
 /** Snapshot of table slice state — used for saved-view serialise/rehydrate. */
 interface DataTableViewState {
     sorting: SortingState;
@@ -266,6 +483,61 @@ interface DataTableProps<TData, TValue> extends Omit<React.HTMLAttributes<HTMLDi
      * (a `border-border-strong` divider between rows, no stripes).
      */
     zebra?: boolean;
+    /**
+     * Draw a quiet `--rule` hairline between columns (header and body). Off by
+     * default. Pinned cells keep their own seam and never take a divider.
+     */
+    columnDividers?: boolean;
+    /**
+     * `"table"` (default): always a `<table>`. `"cards"`: always one card per
+     * row (a `<dl>` of header → cell). `"auto"`: cards while the table's own
+     * container is narrower than 450 px, a `<table>` above. Only the markup
+     * changes; sorting, filtering, paging and selection use the same table.
+     */
+    layout?: "auto" | "table" | "cards";
+    /**
+     * Rows pinned to the top or bottom of every page. An "average" or "total"
+     * row stays put through sorting, paging and search. Receives each record
+     * and its `data` index.
+     */
+    stickyRows?: DataTableStickyRows<TData>;
+    /**
+     * Prepend a 1…n rank column, in `data` order. Sticky rows are not ranked;
+     * the rank travels with its row — sorting never renumbers it.
+     */
+    showRanks?: boolean;
+    /**
+     * What the rank column is CALLED — its accessible name, its `title`, the
+     * term in the cards layout, and the key printed above the table. Defaults to
+     * the locale seam (`data.table.rankHeader` / `data.table.rankKey`).
+     *
+     * The number is the row's position in `data`, not its position on screen, so
+     * beside a sorted column it reads 2, 1, 6, 4 on purpose. A column headed by
+     * a bare "#" gives a reader no way to know that; this names it.
+     */
+    rankLabel?: string;
+    /** `"compact"` tightens row and header height. Default `"default"`. */
+    density?: "default" | "compact";
+    /**
+     * Span an ungrouped column's header over the empty group rows. With
+     * grouped headers, the placeholder cells above a column merge into one.
+     */
+    mergeEmptyHeaders?: boolean;
+    /**
+     * `"exact"`: a row matches only when a cell equals the query. Default
+     * `"contains"` (TanStack's substring search); both ignore case.
+     */
+    searchMode?: "contains" | "exact";
+    /**
+     * Hide the header row visually (a pixel heatmap). The headers stay for
+     * screen readers, and a focused sort button still shows itself.
+     *
+     * Sorting is then KEYBOARD-reachable, not clickable: the band has no height,
+     * so it offers no hit area — deliberately, since an invisible click target
+     * over the first data row would be worse than none. Tab to the column's sort
+     * button (it becomes visible on focus) and press Enter.
+     */
+    hideHeader?: boolean;
     /**
      * Opt-in row drag-reorder. Off by default — an existing table renders
      * byte-identical markup with no extra DOM per row until this is set.
@@ -283,6 +555,10 @@ interface DataTableProps<TData, TValue> extends Omit<React.HTMLAttributes<HTMLDi
      * is silently disabled (a dev warning fires) when both are set. Combining
      * it with active `sorting` also fires a dev warning (both still work, but
      * a sort re-orders the very rows a drag just moved, which reads as broken).
+     *
+     * Table-only. The card layout (`layout="cards"`, or `"auto"` at the narrow
+     * tier) has no grip column and no row to drop onto, so reorder is a no-op
+     * there and `onRowReorder` never fires; a dev warning says so once per mount.
      */
     enableRowReorder?: boolean;
     /**
@@ -366,7 +642,7 @@ declare const DataTableWithRef: <TData, TValue>(props: DataTableProps<TData, TVa
 interface SearchInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "onChange" | "value"> {
     value: string;
     onValueChange: (value: string) => void;
-    /** Visually-hidden accessible label. Defaults to "Search". */
+    /** Visually-hidden accessible label. Defaults to the localized "Search" microcopy. */
     label?: string;
     containerClassName?: string;
 }
@@ -379,7 +655,7 @@ interface SearchInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "
  * `<Input>` explicitly AND gates the clear button — while disabled the clear
  * affordance is hidden so it can't mutate the filter mid-request (#269/#8).
  */
-declare function SearchInput({ value, onValueChange, label, placeholder, className, containerClassName, disabled, ...props }: SearchInputProps): react.JSX.Element;
+declare const SearchInput: react.ForwardRefExoticComponent<SearchInputProps & react.RefAttributes<HTMLInputElement>>;
 
 interface FilterBarProps {
     /** Left cluster: search + facet filters. */
@@ -479,4 +755,272 @@ declare function toCsv<TData extends Record<string, unknown>>(rows: TData[], opt
  */
 declare function downloadCsv<TData extends Record<string, unknown>>(rows: TData[], opts?: DownloadCsvOptions<TData>): void;
 
-export { ColumnPicker, type ColumnPickerProps, type CsvColumn, DataTableWithRef as DataTable, type DataTableColumnMeta, type DataTableProps, type DataTableRowClickHandler, type DataTableServerArgs, type DataTableViewState, type DownloadCsvOptions, FacetFilter, type FacetFilterProps, type FacetOption, FilterBar, type FilterBarProps, FilterChip, type FilterChipProps, SearchInput, type SearchInputProps, type ToCsvOptions, createSelectionColumn, downloadCsv, toCsv };
+/**
+ * cell-scales.ts — the shared scales behind `DataTable`'s in-cell visuals
+ * (RM-123). Pure: no React, no DOM.
+ *
+ * Every visual cell reads ONE scale per column, computed once over the full
+ * data (never the current page, filter or sort), so a bar, a sparkline or a
+ * heatmap colour means the same thing on every page and after every sort.
+ * Colour decisions (heatmap ramps, categories) come from `colorScaleFor`
+ * (`@elabs-ai/components-ui`) — the one value → colour-token scale `charts`,
+ * `data` and `maps` share — so colours are `var(--chart-…)` references.
+ */
+
+/** `[min, max]` of the finite numbers in a set. */
+interface NumericExtent {
+    min: number;
+    max: number;
+}
+/** The extent of the finite numbers in `values`; `null` when there are none. */
+declare function extentOf(values: readonly unknown[]): NumericExtent | null;
+/** A bar domain always contains zero, so a bar is always measured from zero. */
+declare function barDomain(range: DataTableBarVisual["range"], column: NumericExtent | null, table: NumericExtent | null): readonly [number, number];
+/**
+ * Where a bar sits inside its track, as percentages of the track width:
+ * `start` is the inline-start edge, `size` the length. Negative values grow
+ * toward inline-start from zero. Both are clamped to 0…100.
+ */
+declare function barGeometry(value: number, domain: readonly [number, number]): {
+    start: number;
+    size: number;
+    zero: number;
+    negative: boolean;
+};
+/** A row's numbers for `keys`, `null` where a key holds no finite number. */
+declare function seriesValues(original: unknown, keys: readonly string[]): (number | null)[];
+/** The `ColorScaleSpec` a heatmap scale asks `colorScaleFor` for. */
+declare function heatmapColorScaleSpec(scale: DataTableHeatmapScale): ColorScaleSpec;
+/** Everything a column's visual cells share. Only the parts the column uses are set. */
+interface DataTableColumnScale {
+    /** Extent of the column's own values. */
+    extent: NumericExtent | null;
+    /** Bar visual: the resolved `[lo, hi]` (always contains zero). */
+    barDomain?: readonly [number, number];
+    /** Bar `colorBy`: the category → colour scale. */
+    barCategory?: ColorScale;
+    /** Sparkline / columns: extent of every row's series values. */
+    seriesExtent?: NumericExtent | null;
+    /**
+     * Heatmap: the value → ramp-colour scale. Heatmap columns with an identical
+     * `scale` spec SHARE one scale over all their values (one heatmap across
+     * several columns); `heatmapGroup` names it.
+     */
+    heatmap?: ColorScale;
+    heatmapGroup?: string;
+    /** `meta.colorBy`: the category → colour scale. */
+    category?: ColorScale;
+}
+/** A minimal row: what `computeColumnScales` needs from a TanStack row. */
+interface ScaleRow {
+    original: unknown;
+    getValue: (columnId: string) => unknown;
+}
+/** A minimal column: its id and meta. */
+interface ScaleColumn {
+    id: string;
+    meta: DataTableColumnMeta | undefined;
+}
+/**
+ * One scale per column that needs one (a `visual` or a `colorBy`), over ALL
+ * `rows`. Columns with neither are absent from the map.
+ */
+declare function computeColumnScales(columns: readonly ScaleColumn[], rows: readonly ScaleRow[]): Map<string, DataTableColumnScale>;
+
+/**
+ * ranks-column.tsx — `DataTable`'s `showRanks` column (RM-123).
+ *
+ * A rank belongs to the ROW: it is the row's 1-based position in the `data`
+ * you passed (sticky rows excluded), so re-sorting, filtering or paging moves
+ * the numbers with their rows and never renumbers them. It is rendered beside
+ * the TanStack columns, not as one, so the table model is unchanged.
+ */
+/** Row id → rank (1…n in data order), skipping the ids in `exclude`. */
+declare function computeRowRanks(rowIds: readonly string[], exclude?: ReadonlySet<string>): Map<string, number>;
+interface DataTableRankHeaderProps extends ThHTMLAttributes<HTMLTableCellElement> {
+    /**
+     * The column's accessible NAME, and its `title`. Defaults to the locale
+     * seam's `data.table.rankHeader`.
+     *
+     * The visible glyph stays "#" — it has to, in a 40px column — so the glyph
+     * is decorative (`aria-hidden`) and this string is what the column is
+     * actually called. Without it the header's accessible name is the single
+     * character "#", which says nothing about WHICH position is printed: beside
+     * a sorted column the numbers legitimately read 2, 1, 6, 4 and a reader has
+     * no way to learn why. `DataTable` prints the same rule visibly, once, above
+     * the table (`data-slot="data-table-rank-key"`).
+     */
+    label?: string;
+}
+/**
+ * The ranks column's header cell: "#" as the visible glyph, `label` as the
+ * name AT reads.
+ */
+declare const DataTableRankHeader: react.ForwardRefExoticComponent<DataTableRankHeaderProps & react.RefAttributes<HTMLTableCellElement>>;
+/** One row's rank cell; `rank` undefined (a sticky row) renders empty. */
+declare const DataTableRankCell: react.ForwardRefExoticComponent<TdHTMLAttributes<HTMLTableCellElement> & {
+    rank?: string;
+} & react.RefAttributes<HTMLTableCellElement>>;
+
+/**
+ * card-layout.tsx — `DataTable`'s transposed card rows (RM-123, `layout`).
+ *
+ * Under the table's `narrow` breakpoint (`layout="auto"`) or always
+ * (`layout="cards"`), each row renders as one card: a `<dl>` whose terms are
+ * the column headers and whose details are the row's cells. Only the markup
+ * changes — the TanStack model (sorting, filtering, paging, selection) is the
+ * same instance the table uses, so the toolbar and pager keep working.
+ */
+/** One term / detail pair of a card. */
+interface DataTableCardField {
+    /** Stable key: the column id. */
+    id: string;
+    term: ReactNode;
+    value: ReactNode;
+    /** Extra classes / style for the detail (alignment, a colour wash). */
+    className?: string;
+    style?: React.CSSProperties;
+}
+/** The list that holds the cards. Rows are separated by a strong divider. */
+declare const DataTableCardList: react.ForwardRefExoticComponent<HTMLAttributes<HTMLUListElement> & react.RefAttributes<HTMLUListElement>>;
+interface DataTableCardProps extends LiHTMLAttributes<HTMLLIElement> {
+    fields: readonly DataTableCardField[];
+    /** Content above the fields (the selection checkbox, the rank, the row action). */
+    lead?: ReactNode;
+    /** `compact` tightens the padding, like the table's `density="compact"`. */
+    density?: "default" | "compact";
+}
+/** One row as a card: a `<dl>` of header → cell pairs. */
+declare const DataTableCard: react.ForwardRefExoticComponent<DataTableCardProps & react.RefAttributes<HTMLLIElement>>;
+
+interface BarCellProps extends HTMLAttributes<HTMLDivElement> {
+    /** The number the bar draws; `null` draws no bar. */
+    value: number | null;
+    /** The printed (formatted) value. Always in the accessible tree. */
+    label: string;
+    /** `[lo, hi]` of the track; always contains zero (see `barDomain`). */
+    domain: readonly [number, number];
+    /** `"regular"` (default): bar beside the value; `"slim"`: a thin bar under it. */
+    variant?: "regular" | "slim";
+    /** Paint the grey remainder of the track. */
+    track?: boolean;
+    /** A category colour (`var(--chart-N)`) that replaces the positive fill. */
+    fillColor?: string | null;
+    /** Paint a negative value in the negative token. Default `true`. */
+    negativeColor?: boolean;
+    /**
+     * Room reserved for the printed value, in `ch` (`labelBoxCh` over the whole
+     * column). Every bar in a column then shares one track length, so bar lengths
+     * compare down the column and a diverging column's zero rule keeps one x.
+     * Unset (or `"slim"`, where the bar sits under the value) leaves the value
+     * box to size itself.
+     */
+    labelWidth?: number;
+}
+/**
+ * An in-cell bar (CSS only). The bar grows from zero — toward inline-end for a
+ * positive value, toward inline-start for a negative one — inside a track that
+ * spans the column's shared domain. The value stays printed beside it.
+ */
+declare const BarCell: react.ForwardRefExoticComponent<BarCellProps & react.RefAttributes<HTMLDivElement>>;
+
+interface CategoryLegendProps extends HTMLAttributes<HTMLDivElement> {
+    /** A categorical scale — its `categories`, in first-seen order. */
+    scale: ColorScale;
+    /** What the colours divide the rows BY (the `colorBy` key, or a nicer name). */
+    title?: string;
+    /** Print a category value; defaults to `String`. */
+    formatCategory?: (value: string | number) => string;
+}
+/**
+ * A `colorBy` column's colour key: one named swatch per category.
+ *
+ * A categorical fill answers "which group", and unlike a bar's length or a
+ * heatmap's ramp there is nothing in the cell to read it off. Without a key the
+ * category is carried by hue alone — unreadable to anyone who cannot separate
+ * those hues, and unnameable by everyone else (WCAG 1.4.1). This is the same
+ * key `HeatmapLegend` gives an ordered scale, for an unordered one.
+ */
+declare const CategoryLegend: react.ForwardRefExoticComponent<CategoryLegendProps & react.RefAttributes<HTMLDivElement>>;
+
+interface SparklineCellProps extends HTMLAttributes<HTMLDivElement> {
+    values: readonly (number | null)[];
+    /** The y domain: this row's own extent (`range: "cell"`) or the column's. */
+    domain: NumericExtent | null;
+    /** Every value as text, for screen readers, sorting and copy. */
+    label: string;
+    /** Printed first / last values (with `labels: "ends"`). */
+    ends?: readonly [first: string, last: string];
+    /**
+     * Room reserved for those two labels, in `ch` (`labelBoxCh` over the whole
+     * column). The drawing takes what they leave over, so one reservation per
+     * column keeps every row's line on the same x scale.
+     */
+    endsWidth?: readonly [first: number, last: number];
+    fill?: boolean;
+    /** Drawing height in px. Default 24. */
+    height?: number;
+}
+/** An in-cell sparkline: a ≤ 40-line inline SVG on a shared or own y domain. */
+declare const SparklineCell: react.ForwardRefExoticComponent<SparklineCellProps & react.RefAttributes<HTMLDivElement>>;
+
+interface ColumnsCellProps extends HTMLAttributes<HTMLDivElement> {
+    /** One entry per row key, in x order; a `null` value draws no column. */
+    values: readonly {
+        key: string;
+        value: number | null;
+    }[];
+    /** The value domain: this row's own extent or the column's. Zero is always added. */
+    domain: NumericExtent | null;
+    /** Every value as text, for screen readers, sorting and copy. */
+    label: string;
+    /** Drawing height in px. Default 24. */
+    height?: number;
+}
+/** In-cell mini columns: a ≤ 40-line inline SVG, columns grow from a zero rule. */
+declare const ColumnsCell: react.ForwardRefExoticComponent<ColumnsCellProps & react.RefAttributes<HTMLDivElement>>;
+
+/**
+ * The `<td>` style that paints a heatmap cell: the value's ramp colour (a
+ * `var(--chart-seq-*)` / `var(--chart-div-*)` reference from `colorScaleFor`),
+ * so a theme flip re-colours it with no re-render. `null` (no data) paints
+ * nothing.
+ */
+declare function heatmapCellStyle(color: string | null): CSSProperties | undefined;
+interface HeatmapCellProps extends HTMLAttributes<HTMLSpanElement> {
+    /** The printed (formatted) value. Always in the accessible tree. */
+    label: string;
+    /** Hide the value visually; it stays for screen readers, sorting and copy. */
+    hideValue?: boolean;
+}
+/**
+ * A heatmap cell's content. The `<td>` carries the colour
+ * ({@link heatmapCellStyle}); a visible value sits on a card plate, so its ink
+ * reads on every ramp step in every theme without resolving the colour.
+ */
+declare const HeatmapCell: react.ForwardRefExoticComponent<HeatmapCellProps & react.RefAttributes<HTMLSpanElement>>;
+interface HeatmapLegendProps extends HTMLAttributes<HTMLDivElement> {
+    scale: ColorScale;
+    /** What the colours measure (the column's header). */
+    title?: string;
+    formatValue: (value: number) => string;
+}
+/**
+ * A heatmap column's colour key: one swatch per class (stepped) or a ramp
+ * strip (continuous), with the class bounds printed in the `text-meta` role.
+ */
+declare const HeatmapLegend: react.ForwardRefExoticComponent<HeatmapLegendProps & react.RefAttributes<HTMLDivElement>>;
+
+/** `true` for a URL a cell may link to or load. */
+declare function isSafeCellUrl(url: string): boolean;
+/** Parses `text` into React nodes. Exported for tests. */
+declare function parseCellMarkdown(text: string, images?: boolean, keyPrefix?: string): ReactNode[];
+interface MarkdownCellProps extends HTMLAttributes<HTMLSpanElement> {
+    text: string;
+    /** Render `![alt](src)` as an image. Default `false` (the alt text prints). */
+    images?: boolean;
+}
+/** A cell rendered from safe inline markdown (see {@link parseCellMarkdown}). */
+declare const MarkdownCell: react.ForwardRefExoticComponent<MarkdownCellProps & react.RefAttributes<HTMLSpanElement>>;
+
+export { BarCell, type BarCellProps, CategoryLegend, type CategoryLegendProps, ColumnPicker, type ColumnPickerProps, ColumnsCell, type ColumnsCellProps, type CsvColumn, DATA_TABLE_BREAKPOINT_THRESHOLDS, DataTableWithRef as DataTable, type DataTableBarVisual, type DataTableBreakpoint, DataTableCard, type DataTableCardField, DataTableCardList, type DataTableCardProps, type DataTableCellVisual, type DataTableColorBy, type DataTableColumnMeta, type DataTableColumnScale, type DataTableColumnsVisual, type DataTableHeatmapScale, type DataTableHeatmapVisual, type DataTableMarkdownOptions, type DataTableProps, DataTableRankCell, DataTableRankHeader, type DataTableRowClickHandler, type DataTableServerArgs, type DataTableShowAt, type DataTableSparklineVisual, type DataTableStickyRowPosition, type DataTableStickyRows, type DataTableValueFormatSpec, type DataTableViewState, type DownloadCsvOptions, FacetFilter, type FacetFilterProps, type FacetOption, FilterBar, type FilterBarProps, FilterChip, type FilterChipProps, HeatmapCell, type HeatmapCellProps, HeatmapLegend, type HeatmapLegendProps, MarkdownCell, type MarkdownCellProps, type NumericExtent, SearchInput, type SearchInputProps, SparklineCell, type SparklineCellProps, type ToCsvOptions, barDomain, barGeometry, columnSizeStyle, computeColumnScales, computeRowRanks, createSelectionColumn, downloadCsv, extentOf, formatCellValue, heatmapCellStyle, heatmapColorScaleSpec, isSafeCellUrl, parseCellMarkdown, resolveShowAt, seriesValues, stickyRowPinning, tableBreakpointForWidth, toCsv, useTableBreakpoint };