@alfadocs/ui-kit 1.54.3 → 1.55.0

package/dist/components/heatmap/heatmap-format.d.ts

@@ -0,0 +1,59 @@
+import type { TFunction } from 'i18next';
+import type { HeatmapColumn, HeatmapGroup, HeatmapRow, ModelCell } from './heatmap-model';
+import type { HeatmapAggregate } from './heatmap-scale';
+/** What the values are: plain numbers, or rates between 0 and 1. */
+export type HeatmapValueType = 'number' | 'rate';
+/**
+ * What privacy mode masks. `rows`: the row labels, which name people,
+ * chairs or patients. `all`: the column and group labels too. The kit rule
+ * (src/components/_shared/privacy-mask.tsx) is to mask the identity and keep
+ * time, place and status, so columns (hours, days) and groups (practices)
+ * stay readable unless the host asks for more.
+ */
+export type HeatmapPrivacyScope = 'rows' | 'all';
+/** The default value format: a percentage for rates, a decimal otherwise. */
+export declare function defaultValueFormatter(locale: string, valueType: HeatmapValueType): (value: number) => string;
+/** Whole-number format for counts. */
+export declare function countFormatter(locale: string): (count: number) => string;
+/** Builds every sentence the heatmap speaks or shows. */
+export interface HeatmapDescriber {
+    /** True when privacy mode hides the row labels. */
+    masksRows: boolean;
+    /** True when privacy mode hides the column labels. */
+    masksColumns: boolean;
+    /** True when privacy mode hides the group labels. */
+    masksGroups: boolean;
+    rowLabel: (row: HeatmapRow) => string;
+    columnLabel: (column: HeatmapColumn) => string;
+    groupLabel: (groupId: string) => string;
+    /** A cell by its headers: "Tuesday, 10:00". */
+    cellName: (rowText: string, columnText: string) => string;
+    /** A group header row: "Mos Eisley (Average)". */
+    groupRowText: (groupText: string, method: HeatmapAggregate) => string;
+    /** A cell as the table view shows it: "26%, 10 of 39". */
+    tableText: (cell: ModelCell) => string;
+    /** Label for a margin: "Total" for a sum, "Average" for a mean. */
+    methodLabel: (method: HeatmapAggregate) => string;
+    /** The value as text: formatted, a cell label, "no data" or "too few". */
+    valueText: (cell: ModelCell) => string;
+    /** The value as shown inside a cell, or '' when the cell shows none. */
+    visibleText: (cell: ModelCell) => string;
+    /** "10 of 39" for a rate, "39 records" otherwise; null without a count. */
+    countText: (cell: ModelCell) => string | null;
+    /** "Tuesday, 10:00: 26%, 10 of 39". */
+    sentence: (rowText: string, columnText: string, cell: ModelCell) => string;
+    /** Format for a raw value, used by the legend. */
+    formatValue: (value: number) => string;
+}
+export interface DescriberOptions {
+    t: TFunction<'ui'>;
+    privacyMode: boolean;
+    /** What privacy mode masks. Default `rows`. */
+    privacyScope?: HeatmapPrivacyScope;
+    valueType: HeatmapValueType;
+    formatValue: (value: number) => string;
+    formatCount: (count: number) => string;
+    groups?: readonly HeatmapGroup[];
+}
+export declare function createDescriber({ t, privacyMode, privacyScope, valueType, formatValue, formatCount, groups, }: DescriberOptions): HeatmapDescriber;
+//# sourceMappingURL=heatmap-format.d.ts.map

package/dist/components/heatmap/heatmap-grid.d.ts

@@ -0,0 +1,66 @@
+import type { HeatmapDescriber } from './heatmap-format';
+import { type BodyRow, type HeatmapCellInfo, type HeatmapColumn, type HeatmapRow, type HeatmapTotals, type ModelCell } from './heatmap-model';
+import { type HeatmapAggregate, type ResolvedHeatmapScale } from './heatmap-scale';
+import { type HeatmapPalette } from './heatmap-variants';
+/** How the selection behaves. */
+export type HeatmapSelectionMode = 'none' | 'single' | 'multiple' | 'range';
+/** A position in the navigable matrix: a body or footer row and a column
+ *  (the last column is the row-totals column when there is one). */
+export interface GridPosition {
+    rowKey: string;
+    col: number;
+}
+/** Internal selection key for a data cell: its row id and column id, never
+ *  its position, so a change to the columns cannot move it. */
+export declare const selectionKey: (rowId: string, columnId: string | number) => string;
+/** The row id and the column id (as a string) a selection key holds. */
+export declare const splitSelectionKey: (key: string) => [string, string];
+export interface HeatmapGridProps {
+    title: string;
+    rowsLabel?: string;
+    rows: readonly HeatmapRow[];
+    columns: readonly HeatmapColumn[];
+    matrix: readonly ModelCell[][];
+    body: readonly BodyRow[];
+    scale: ResolvedHeatmapScale;
+    palette: HeatmapPalette;
+    describer: HeatmapDescriber;
+    showValues: boolean;
+    totals: HeatmapTotals | null;
+    rowTotals: HeatmapAggregate | false;
+    columnTotals: HeatmapAggregate | false;
+    /** How a group header's per-column totals are worked out. */
+    groupColumnMethod: HeatmapAggregate;
+    /** Each group's public id: what DOM hooks carry, never a label. */
+    groupIds: ReadonlyMap<string, string>;
+    minCount?: number;
+    selectionMode: HeatmapSelectionMode;
+    /** Selection keys (row id + column id) of the selected cells. */
+    selected: ReadonlySet<string>;
+    /** Column index for the column id a selection key holds. */
+    columnIndexOfKey: (columnKey: string) => number | undefined;
+    interactive: boolean;
+    virtualised: boolean;
+    size: 'sm' | 'md' | 'lg';
+    density: 'compact' | 'default';
+    cellInfo: (rowIndex: number, columnIndex: number) => HeatmapCellInfo;
+    /** A data cell's tooltip text. */
+    tooltipText: (cell: HeatmapCellInfo) => string;
+    /** Describe the focused data cell with its tooltip text (a consumer's
+     *  renderTooltip says more than the cell's name). */
+    describeFocused: boolean;
+    /** A data cell was activated by click, Enter or Space. `select` is false
+     *  for a click that only reports the cell (a range press already chose). */
+    onActivate: (rowIndex: number, columnIndex: number, select: boolean) => void;
+    /** Range drag or Shift+arrows: select the rectangle anchor to target. */
+    onRange: (anchor: {
+        rowIndex: number;
+        col: number;
+    }, target: {
+        rowIndex: number;
+        col: number;
+    }) => void;
+    onToggleGroup: (groupId: string) => void;
+}
+export declare function HeatmapGrid(props: HeatmapGridProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=heatmap-grid.d.ts.map

package/dist/components/heatmap/heatmap-legend.d.ts

@@ -0,0 +1,36 @@
+import { type HeatmapScale } from './heatmap-scale';
+import { type HeatmapPalette } from './heatmap-variants';
+export interface HeatmapLegendProps {
+    /**
+     * `stepped` separates the ten steps; `continuous` joins them in a bar.
+     * A quantile or threshold scale always shows its bands, one swatch per
+     * step it uses, with the cut points between them.
+     */
+    variant?: 'stepped' | 'continuous';
+    /** Palette. Inside a Heatmap it defaults to the Heatmap's. */
+    palette?: HeatmapPalette;
+    /** Scale. Inside a Heatmap it defaults to the Heatmap's resolved scale. */
+    scale?: HeatmapScale;
+    /** Values an `auto` or quantile scale is worked out from (outside a Heatmap). */
+    values?: readonly number[];
+    /** Formats the end labels. Inside a Heatmap it defaults to the Heatmap's. */
+    valueFormatter?: (value: number) => string;
+    /** Show the key for empty cells. Inside a Heatmap: when any cell is empty. */
+    showEmpty?: boolean;
+    /** Show the key for low-sample cells. Inside a Heatmap: when any is. */
+    showLowSample?: boolean;
+    /** The sample threshold, named in the low-sample key. Inside a Heatmap it
+     *  defaults to the Heatmap's `minCount`. */
+    minCount?: number;
+    className?: string;
+}
+/**
+ * Heatmap.Legend: the colour steps with the low and high ends of the scale,
+ * plus keys for empty and low-sample cells. A diverging scale shows its
+ * midpoint between the two hues as a neutral swatch carrying the midpoint
+ * value, the colour of a cell exactly on it. Inside a Heatmap it reads the
+ * Heatmap's scale; render it elsewhere with `legend={false}` on the Heatmap
+ * and the same `scale`, `palette` and `values` here.
+ */
+export declare const HeatmapLegend: import("react").ForwardRefExoticComponent<HeatmapLegendProps & import("react").RefAttributes<HTMLDivElement>>;
+//# sourceMappingURL=heatmap-legend.d.ts.map

package/dist/components/heatmap/heatmap-model.d.ts

@@ -0,0 +1,152 @@
+import { type AggregateResult, type HeatmapAggregate } from './heatmap-scale';
+/** One row of the heatmap. */
+export interface HeatmapRow {
+    /** Stable, opaque id. Emitted in DOM hooks, so never a name. */
+    id: string;
+    /** Visible label. Masked in privacy mode. */
+    label: string;
+    /**
+     * Group id. Rows that share it are grouped when `groupRows` is on. Without
+     * a matching entry in `groups` the id doubles as the visible label, so it
+     * may be a name: privacy mode masks it, and DOM hooks and agent state
+     * carry an index-based id (`group-1`, `group-2` in order of first
+     * appearance), never this one.
+     */
+    group?: string;
+}
+/** One column of the heatmap. */
+export interface HeatmapColumn {
+    /**
+     * Stable, opaque id. Emitted in DOM hooks (`data-heatmap-cell-id`) and in
+     * agent state, so never a name.
+     */
+    id: string | number;
+    /**
+     * Visible label. Masked in privacy mode only with `privacyScope="all"`:
+     * columns are usually hours or days, which privacy mode keeps.
+     */
+    label: string;
+}
+/** A group's visible label, keyed by the id rows carry in `group`. */
+export interface HeatmapGroup {
+    /** Stable, opaque id. Emitted in DOM hooks and agent state, so never a name. */
+    id: string;
+    /**
+     * Visible label. Masked in privacy mode only with `privacyScope="all"`:
+     * groups are usually practices or sites, which privacy mode keeps.
+     */
+    label: string;
+}
+/**
+ * The id each group shows to DOM hooks and agents. A group listed in
+ * `groups` keeps its own (opaque) id. One that is not has only its id for a
+ * label, which may be a name, so it gets `group-<n>` by order of first
+ * appearance instead.
+ */
+export declare function publicGroupIds(rows: readonly HeatmapRow[], groups: readonly HeatmapGroup[] | undefined): Map<string, string>;
+/** The data behind one cell. */
+export interface HeatmapCellData {
+    /** The value to colour. `null` means no data. */
+    value: number | null;
+    /**
+     * How many records the value rests on (the denominator of a rate). Weights
+     * the mean totals and drives `minCount`.
+     */
+    count?: number;
+    /**
+     * Text shown and announced instead of the formatted value, for example
+     * "Closed". Replaced by the formatted value in privacy mode.
+     */
+    label?: string;
+}
+/** What `getCell` or the `cells` matrix may hold for a cell. */
+export type HeatmapCellInput = HeatmapCellData | number | null | undefined;
+/** How a cell renders: a coloured value, no data, or too few records. */
+export type HeatmapCellStatus = 'value' | 'empty' | 'low-sample';
+/** Addresses one cell. */
+export interface HeatmapCellKey {
+    rowId: string;
+    columnId: string | number;
+}
+/** Everything known about one cell, as passed to callbacks. */
+export interface HeatmapCellInfo extends HeatmapCellKey {
+    row: HeatmapRow;
+    column: HeatmapColumn;
+    /** Index into the `rows` prop. */
+    rowIndex: number;
+    /** Index into the `columns` prop. */
+    columnIndex: number;
+    value: number | null;
+    count?: number;
+    label?: string;
+    status: HeatmapCellStatus;
+    /**
+     * Colour step, 0 to 9, when `status` is `'value'`; otherwise null. On a
+     * diverging scale a value exactly on the midpoint keeps step 5 but is
+     * painted in the neutral `--heatmap-midpoint` colour: compare `value`
+     * with the midpoint to tell it from the palest step above.
+     */
+    step: number | null;
+}
+/** A cell after normalisation. */
+export interface ModelCell {
+    value: number | null;
+    count?: number;
+    label?: string;
+    status: HeatmapCellStatus;
+}
+/** How rows are ordered (within their group when grouped). */
+export type HeatmapSortRows = 'none' | 'label' | 'total-asc' | 'total-desc';
+/** Whether a cell or total falls below the sample threshold. */
+export declare function isLowSample(count: number | undefined, minCount: number | undefined): boolean;
+/** Normalises one cell input. */
+export declare function toModelCell(input: HeatmapCellInput, minCount: number | undefined): ModelCell;
+/** Builds the `[row][column]` matrix in the order of the props. */
+export declare function buildMatrix(rows: readonly HeatmapRow[], columns: readonly HeatmapColumn[], getCell: ((row: HeatmapRow, column: HeatmapColumn, rowIndex: number, columnIndex: number) => HeatmapCellInput) | undefined, cells: readonly (readonly HeatmapCellInput[])[] | undefined, minCount: number | undefined): ModelCell[][];
+/** The values that render a colour, for the scale's domain. */
+export declare function shownValues(matrix: readonly ModelCell[][]): number[];
+/** Whether at least one cell carries data (a value or a low sample). */
+export declare function hasAnyData(matrix: readonly ModelCell[][]): boolean;
+export interface HeatmapTotals {
+    /** Per row index (props order), by the row method. */
+    rows: AggregateResult[];
+    /** Per column index, by the column method. */
+    columns: AggregateResult[];
+    /** Every cell, by the row method (it sits in the row-totals column). */
+    grand: AggregateResult;
+    /** Per group id: one result per column, by the group column method. */
+    groupColumns: Map<string, AggregateResult[]>;
+    /** Per group id: every cell in the group, by the row method (it sits in
+     *  the row-totals column). */
+    groups: Map<string, AggregateResult>;
+}
+/**
+ * Works out every margin. A total in the row-totals column (a row's, a
+ * group's, the grand total) uses the row method, so the column means one
+ * thing; a group's per-column totals use the group column method. Low-sample
+ * cells count: their data is real, only too thin to show on its own.
+ */
+export declare function computeTotals(matrix: readonly ModelCell[][], rows: readonly HeatmapRow[], columnCount: number, rowMethod: HeatmapAggregate, columnMethod: HeatmapAggregate, groupColumnMethod: HeatmapAggregate): HeatmapTotals;
+/** A row the grid body renders. */
+export type BodyRow = {
+    kind: 'group';
+    /** Navigation key, unique among body rows. */
+    key: string;
+    groupId: string;
+    collapsed: boolean;
+    /** Row indexes (props order) in display order. */
+    rowIndexes: number[];
+} | {
+    kind: 'data';
+    key: string;
+    rowIndex: number;
+    groupId?: string;
+};
+export declare const dataRowKey: (rowId: string) => string;
+export declare const groupRowKey: (groupId: string) => string;
+export declare const FOOTER_ROW_KEY = "f";
+/** Orders row indexes. Ties keep the props order (a stable sort). */
+export declare function sortRowIndexes(indexes: readonly number[], rows: readonly HeatmapRow[], totals: readonly AggregateResult[], sort: HeatmapSortRows, collator: Intl.Collator): number[];
+/** Builds the body: group headers (when grouping) and data rows. */
+export declare function buildBodyRows(rows: readonly HeatmapRow[], sortedIndexes: readonly number[], groupRows: boolean, collapsed: ReadonlySet<string>): BodyRow[];
+//# sourceMappingURL=heatmap-model.d.ts.map

package/dist/components/heatmap/heatmap-scale.d.ts

@@ -0,0 +1,125 @@
+/** Number of colour steps every palette carries. */
+export declare const HEATMAP_STEPS = 10;
+/**
+ * How values map to colour steps.
+ *
+ * - `sequential`: low to high. `domain: 'auto'` (the default) uses the min
+ *   and max of the cells that show a value; a fixed `[min, max]` clamps.
+ * - `diverging`: two hues either side of `midpoint`. `auto` makes the
+ *   domain symmetric around the midpoint, so equal distances either side
+ *   get equal intensity. The midpoint defaults to 0, or to the centre of a
+ *   fixed domain that does not include 0.
+ * - `quantile`: equal-count buckets (default 10) from the shown values.
+ *   Repeated values never split: buckets that would cut through a run of
+ *   equal values merge, so the minimum always takes the first step.
+ * - `threshold`: ascending cut points; `n` thresholds make `n + 1`
+ *   buckets, spread across the ten steps. At most nine; duplicates merge.
+ *
+ * A fixed domain is `[min, max]`. A reversed pair is put in order, with a
+ * warning in development builds.
+ */
+export type HeatmapScale = {
+    type: 'sequential';
+    domain?: 'auto' | readonly [number, number];
+} | {
+    type: 'diverging';
+    domain?: 'auto' | readonly [number, number];
+    midpoint?: number;
+} | {
+    type: 'quantile';
+    buckets?: number;
+} | {
+    type: 'threshold';
+    thresholds: readonly number[];
+};
+/** A scale with its domain worked out against the data. */
+export interface ResolvedHeatmapScale {
+    type: HeatmapScale['type'];
+    /** Low end of the domain, or of the data for quantile and threshold. */
+    min: number | null;
+    /** High end of the domain, or of the data for quantile and threshold. */
+    max: number | null;
+    /** Diverging only: the value that separates the two hues. */
+    midpoint?: number;
+    /** Quantile and threshold: the ascending bucket edges. */
+    thresholds: readonly number[];
+    /** Maps a value to a step, 0 to 9. */
+    stepOf: (value: number) => number;
+}
+/** Min and max of the finite values, or null when there are none. */
+export declare function extent(values: readonly number[]): [number, number] | null;
+/**
+ * Sequential step: the domain is cut into ten equal bands. A value on a
+ * band edge takes the band above; the top edge belongs to the top step.
+ * Values outside the domain clamp to the end steps.
+ */
+export declare function sequentialStep(value: number, low: number, high: number): number;
+/**
+ * Diverging step: steps 0 to 4 sit below the midpoint (0 is the furthest),
+ * steps 5 to 9 above it (9 is the furthest). Ten steps have no middle one,
+ * so a value exactly on the midpoint takes step 5, the palest step above.
+ * It is painted in the neutral midpoint colour instead (see `onMidpoint`).
+ */
+export declare function divergingStep(value: number, low: number, midpoint: number, high: number): number;
+/**
+ * Whether a value sits exactly on a diverging scale's midpoint, so it is
+ * painted neutral (`--heatmap-midpoint`) rather than in either hue. Exact
+ * up to floating-point rounding, a few units in the last place of the
+ * scale's largest magnitude: the centre of [0.1, 0.2] is computed as
+ * 0.15000000000000002, and 0.1 + 0.2 - 0.3 is not quite 0. A value that
+ * merely rounds to the midpoint when printed keeps its step. Other scale
+ * types have no midpoint.
+ */
+export declare function onMidpoint(scale: ResolvedHeatmapScale, value: number): boolean;
+/**
+ * Quantile of a sorted array at `p` (0 to 1), interpolating linearly
+ * between neighbours (the R-7 method spreadsheets use).
+ */
+export declare function quantileSorted(sorted: readonly number[], p: number): number;
+/** The `buckets - 1` inner edges that cut sorted values into equal counts. */
+export declare function quantileThresholds(sorted: readonly number[], buckets: number): number[];
+/**
+ * Quantile edges that cut something. Each raw edge moves up to the first
+ * value at or above it, which puts every value in the same bucket but makes
+ * the edge a value the data holds, so no bucket is left empty (an edge
+ * between two values could cut a band nothing falls in). Then edges that
+ * repeat go: when many values repeat (60% of cells at zero), several raw
+ * edges land on the same value, and kept they would put the minimum
+ * mid-scale. An edge at the minimum has nothing below it, so it goes too.
+ */
+export declare function usableQuantileEdges(sorted: readonly number[], buckets: number): number[];
+/** How many edges are at or below `value`: its bucket, 0 to edges.length. */
+export declare function thresholdBucket(value: number, thresholds: readonly number[]): number;
+/** Spreads bucket `bucket` of `bucketCount` evenly across the ten steps. */
+export declare function bucketStep(bucket: number, bucketCount: number): number;
+/**
+ * Works out a scale against the values that will be shown. Pass only the
+ * values of cells that render a colour: empty and low-sample cells must not
+ * stretch the domain.
+ */
+export declare function resolveScale(scale: HeatmapScale, values: readonly number[]): ResolvedHeatmapScale;
+/** How a margin combines its cells. */
+export type HeatmapAggregate = 'sum' | 'mean';
+/** One cell as aggregation sees it. */
+export interface AggregateInput {
+    value: number | null;
+    count?: number;
+}
+/** A combined value and the count behind it. */
+export interface AggregateResult {
+    value: number | null;
+    /** Sum of the counts, when any cell carried one. */
+    count?: number;
+}
+/** Sum of the values; empty cells are skipped. Null when nothing is left. */
+export declare function sumOf(cells: readonly AggregateInput[]): AggregateResult;
+/**
+ * Mean weighted by count: sum(value x count) / sum(count). This is the only
+ * correct way to combine rates (26% of 39 and 50% of 2 is 27%, not 38%).
+ * A cell without a count weighs 1, so data with no counts at all gets a
+ * plain mean. Cells with a count of 0 add nothing.
+ */
+export declare function weightedMean(cells: readonly AggregateInput[]): AggregateResult;
+/** Combines cells with the given method. */
+export declare function aggregate(cells: readonly AggregateInput[], method: HeatmapAggregate): AggregateResult;
+//# sourceMappingURL=heatmap-scale.d.ts.map

package/dist/components/heatmap/heatmap-table-view.d.ts

@@ -0,0 +1,35 @@
+import type { HeatmapDescriber } from './heatmap-format';
+import type { BodyRow, HeatmapColumn, HeatmapRow, HeatmapTotals, ModelCell } from './heatmap-model';
+import type { HeatmapAggregate } from './heatmap-scale';
+/** Starts fetching the table chunk ahead of a switch to the table view, so
+ * the switch does not wait on the download. Safe to call repeatedly. */
+export declare function preloadHeatmapTable(): void;
+export interface HeatmapTableViewProps {
+    title: string;
+    rowsLabel?: string;
+    rows: readonly HeatmapRow[];
+    columns: readonly HeatmapColumn[];
+    matrix: readonly ModelCell[][];
+    /** Group headers and rows in display order, every group expanded. */
+    body: readonly BodyRow[];
+    grouped: boolean;
+    /** Each group's public id, for the table's row ids (never a label). */
+    groupIds: ReadonlyMap<string, string>;
+    describer: HeatmapDescriber;
+    totals: HeatmapTotals | null;
+    rowTotals: HeatmapAggregate | false;
+    columnTotals: HeatmapAggregate | false;
+    groupColumnMethod: HeatmapAggregate;
+    minCount?: number;
+    /** The table failed to load or render (announced by the heatmap). */
+    onLoadError?: () => void;
+}
+/**
+ * The heatmap's "View as table": the same rows, columns, values, counts and
+ * totals as a DataTable, so every number is reachable without colour and
+ * without a pointer. Group header rows carry their totals, and rows stay in
+ * their groups in the grid's order. Labels go through the same privacy
+ * masking as the grid.
+ */
+export declare function HeatmapTableView({ title, rowsLabel, rows, columns, matrix, body, grouped, groupIds, describer, totals, rowTotals, columnTotals, groupColumnMethod, minCount, onLoadError, }: HeatmapTableViewProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=heatmap-table-view.d.ts.map

package/dist/components/heatmap/heatmap-tooltip.d.ts

@@ -0,0 +1,40 @@
+import type { ReactElement } from 'react';
+import type { HeatmapCellInfo } from './heatmap-model';
+export interface HeatmapTooltipProps {
+    /** The cell the tooltip describes. */
+    cell: HeatmapCellInfo;
+    /**
+     * Tooltip text. Defaults to the Heatmap's `renderTooltip`, or to the
+     * sentence every cell is named with ("Tuesday, 10:00: 26%, 10 of 39").
+     * Plain text only: the kit Tooltip never carries interactive content.
+     */
+    label?: string;
+    /** Controlled open state. */
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** Logical side. Default `'top'`. */
+    side?: 'top' | 'end' | 'bottom' | 'start';
+    /** The trigger. */
+    children: ReactElement;
+}
+/**
+ * Heatmap.Tooltip: the kit Tooltip with a cell's description. The grid uses
+ * it for the cell under the pointer or the keyboard focus; a consumer can
+ * use it to describe a cell somewhere else, with the same wording and the
+ * same privacy masking.
+ */
+export declare function HeatmapTooltip({ cell, label, open, onOpenChange, side, children, }: HeatmapTooltipProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace HeatmapTooltip {
+    var displayName: string;
+}
+/**
+ * The anchor the grid hangs a cell's tooltip on: an inert box over the
+ * cell, so the cell itself never re-mounts (and never drops focus) when the
+ * tooltip moves to it. Takes the text, not a cell, so a group header cell
+ * (which has no single row) gets one too.
+ */
+export declare function HeatmapCellTooltip({ label, onOpenChange, }: {
+    label: string;
+    onOpenChange: (open: boolean) => void;
+}): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=heatmap-tooltip.d.ts.map

package/dist/components/heatmap/heatmap-variants.d.ts

@@ -0,0 +1,87 @@
+/** Palettes, each backed by ten `--heatmap-<palette>-<step>` tokens. */
+export type HeatmapPalette = 'primary' | 'success' | 'destructive' | 'diverging';
+/** One colour step of one palette, the neutral midpoint of a diverging
+ *  scale, or a cell with no colour of its own. */
+export type HeatmapTone = `${HeatmapPalette}-${0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9}` | 'midpoint' | 'empty' | 'low-sample' | 'aggregate';
+/** The tone for a palette step. */
+export declare const stepTone: (palette: HeatmapPalette, step: number) => HeatmapTone;
+/** Root: a column of legend bar, grid and live region. Never wider than
+ *  its container, so the page never scrolls sideways. */
+export declare const heatmapRootVariants: (props?: import("class-variance-authority/types").ClassProp | undefined) => string;
+/** The bar above the grid: legend at the start, view toggle at the end. */
+export declare const heatmapToolbarVariants: (props?: import("class-variance-authority/types").ClassProp | undefined) => string;
+/** The scroll box. Only this box scrolls; sticky headers stick to it. */
+export declare const heatmapScrollerVariants: (props?: import("class-variance-authority/types").ClassProp | undefined) => string;
+/**
+ * The table view's box. `fit` lets the DataTable grow with its rows up to
+ * the maximum; `capped` holds the maximum and the DataTable fills it,
+ * scrolling inside.
+ */
+export declare const heatmapTableViewVariants: (props?: ({
+    capped?: boolean | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+/**
+ * The grid. Columns come from `--heatmap-columns` (set on the scroll box);
+ * rows share the column tracks through subgrid. Size sets the cell box,
+ * density the gap, and a virtualised grid pins every track to one size so
+ * the window arithmetic holds.
+ */
+export declare const heatmapGridVariants: (props?: ({
+    size?: "sm" | "md" | "lg" | null | undefined;
+    density?: "default" | "compact" | null | undefined;
+    virtualised?: boolean | null | undefined;
+    totalsColumn?: boolean | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+/** A row: spans every column and lines its cells up through subgrid. */
+export declare const heatmapRowVariants: (props?: ({
+    position?: "body" | "footer" | "header" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+/** A spacer standing in for rows or columns the window skipped. */
+export declare const heatmapSpacerVariants: (props?: ({
+    axis?: "row-lead" | "row-middle" | "row-tail" | "col-lead" | "col-middle" | "col-tail" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+/** Column header: the hour, day or other column label. */
+export declare const heatmapColumnHeaderVariants: (props?: ({
+    corner?: boolean | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+/** Row header: the row's label, sticky at the inline start. */
+export declare const heatmapRowHeaderVariants: (props?: ({
+    kind?: "data" | "group" | "total" | null | undefined;
+    virtualised?: boolean | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+/** The label inside a row header. */
+export declare const heatmapRowLabelVariants: (props?: ({
+    virtualised?: boolean | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+/**
+ * A cell. Colour comes from `tone`; selection, focus and hover come from
+ * state attributes so a cell's classes only change when its data does.
+ *
+ * Focus: an inset ring in `--ring` over an inset band of the page colour,
+ * so it reads on every step. Selection: a dark line framed by two light
+ * ones, also inset, so it reads on every step too and is a shape, not a
+ * colour. On a focused, selected cell the selection lines move inward by
+ * `--focus-ring-width`, so the ring (3px in the accessible theme) never
+ * covers them. Windows high contrast keeps the cell colours
+ * (forced-color-adjust: none) and paints focus in the system Highlight
+ * colour.
+ */
+export declare const heatmapCellVariants: (props?: ({
+    tone?: HeatmapTone | null | undefined;
+    interactive?: boolean | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+/** Legend container. */
+export declare const heatmapLegendVariants: (props?: import("class-variance-authority/types").ClassProp | undefined) => string;
+/** The bar of colour steps in the legend. It shrinks with its container
+ *  rather than pushing the page wider. */
+export declare const heatmapLegendBarVariants: (props?: ({
+    variant?: "stepped" | "continuous" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+/** A legend swatch: a step in the bar, the key for an empty or low-sample
+ *  cell, or the diverging midpoint, which carries its value in its own ink.
+ *  Same tone classes as the cells. */
+export declare const heatmapSwatchVariants: (props?: ({
+    tone?: HeatmapTone | null | undefined;
+    shape?: "label" | "key" | "stepped" | "continuous" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+//# sourceMappingURL=heatmap-variants.d.ts.map

package/dist/components/heatmap/heatmap-window.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Cell count above which the grid virtualises. Measured in Chromium on a
+ * production build (heatmap mdx, "Performance"): a full render took about
+ * 10 ms at 840 cells and 14 ms (p95 18 ms) at 1,200, against the 16 ms
+ * budget in src/docs/19-performance.mdx. Above 1,000 cells the window keeps
+ * render and hover cost tied to the viewport, not to the data.
+ */
+export declare const VIRTUALISE_CELL_THRESHOLD = 1000;
+/** Rows or columns rendered beyond each edge of the viewport. */
+export declare const OVERSCAN = 3;
+/** Inputs for one axis. All lengths in CSS pixels. */
+export interface AxisMetrics {
+    /** Scroll offset along the axis (absolute; RTL scrollLeft is negative). */
+    offset: number;
+    /** Visible length of the scroll container along the axis. */
+    viewport: number;
+    /** Space before the first item: the sticky header or row header. */
+    lead: number;
+    /** Item length plus the gap after it. */
+    pitch: number;
+    /** Number of items on the axis. */
+    count: number;
+}
+/** Half-open range `[start, end)` of item indexes in view. */
+export declare function visibleRange({ offset, viewport, lead, pitch, count }: AxisMetrics, overscan?: number): [number, number];
+/** What an axis renders: item indexes and the spans of the gaps. */
+export interface AxisWindow {
+    /** Sorted item indexes to render. */
+    indexes: number[];
+    /** Items skipped before the first rendered one. */
+    lead: number;
+    /**
+     * Items skipped between the pinned (focused) item and the visible range,
+     * when the pinned item lies outside it. Zero otherwise.
+     */
+    middle: number;
+    /** Where the middle gap sits: after this many rendered items. */
+    middleAfter: number;
+    /** Items skipped after the last rendered one. */
+    tail: number;
+}
+/** Combines the visible range with the item that must stay rendered. */
+export declare function axisWindow(range: [number, number], count: number, pinned: number | null): AxisWindow;
+/** A window that renders everything (the grid below the threshold). */
+export declare function fullWindow(count: number): AxisWindow;
+/**
+ * A window with every index at or past `count` dropped: what a window built
+ * for more items renders in the one pass before it is worked out again.
+ * Returns the same window when nothing is past the end.
+ */
+export declare function trimWindow(window: AxisWindow, count: number): AxisWindow;
+/** Whether two windows render the same items (skips a needless render). */
+export declare function sameWindow(a: AxisWindow, b: AxisWindow): boolean;
+//# sourceMappingURL=heatmap-window.d.ts.map