@synopackageland/ui 0.20.3 → 0.20.4

package/dist/grid/cells/registry.d.ts

@@ -0,0 +1,56 @@
+import { GridCell, GridCellRenderer, GridCellTextGetter, GridHostExpose, GridRect } from '../contracts';
+import { GridCellTheme } from '../theme';
+import { GridCellAction, GridCellHit, GridCellKind, GridCellKindRenderer, GridCellLabels, GridCellStatus, GridCellValue } from './types';
+export interface GridCellsOptions {
+    /** The value to draw for a cell; null or undefined draws nothing. */
+    getValue: (cell: GridCell) => GridCellValue | null | undefined;
+    /** Saving dot or failed mark for a cell. */
+    getStatus?: (cell: GridCell) => GridCellStatus | null | undefined;
+    /** Blocks `update` actions (a read-only column, record or grid). */
+    isReadonly?: (cell: GridCell) => boolean;
+    /** Translated words for the accessible text (`useGridCells` fills them). */
+    labels: GridCellLabels;
+    /** BCP 47 locale for number grouping. Default `en-US`. */
+    locale?: string;
+    /** Element whose tokens give the colours, re-read whenever the host's theme changes (usually the grid's wrapper). */
+    themeRoot?: () => Element | null | undefined;
+    /** Fixed colours instead of `themeRoot` (tests, previews). */
+    theme?: GridCellTheme;
+    /** Called once per batch of loaded avatars/thumbnails; pass the host's `invalidate`. */
+    onImageLoad?: () => void;
+    /** Replace or add renderers per kind. */
+    renderers?: Partial<{
+        [K in GridCellKind]: GridCellKindRenderer<Extract<GridCellValue, {
+            kind: K;
+        }>>;
+    }>;
+}
+export interface GridCells {
+    /** One renderer for every column: `:cell-renderer="cells.cellRenderer"`. */
+    renderer: GridCellRenderer;
+    cellRenderer: () => GridCellRenderer;
+    /** Plain text of a cell, for `:get-cell-text` (assistive tech and the focus owner). */
+    getCellText: GridCellTextGetter;
+    /** Target under a point in cell coordinates. */
+    hitTest: (cell: GridCell, point: {
+        x: number;
+        y: number;
+    }, rect: Pick<GridRect, 'width' | 'height'>, wasActive: boolean) => GridCellHit | null;
+    /** Keyboard equivalent on the active cell (Enter / Space toggles a checkbox, digits rate, Backspace clears a rating). */
+    keyAction: (cell: GridCell, key: string) => GridCellAction | null;
+    /**
+     * Handlers for an element wrapping `<GridHost>` that turn a click into a
+     * first-click action: the host selects the cell on pointerdown, the click
+     * then hits the area under the pointer. Bind `onPointerdown` in the capture
+     * phase (`@pointerdown.capture`).
+     */
+    clickHandlers: (host: () => GridHostExpose | null | undefined, onAction: (action: GridCellAction, cell: GridCell) => void) => {
+        onPointerdown: (event: PointerEvent) => void;
+        onClick: (event: MouseEvent) => void;
+    };
+    setLabels: (labels: GridCellLabels) => void;
+    setTheme: (theme: GridCellTheme) => void;
+    /** Drops loaded images. */
+    clearImages: () => void;
+}
+export declare const createGridCells: (options: GridCellsOptions) => GridCells;

package/dist/grid/cells/renderers.d.ts

@@ -0,0 +1,8 @@
+import { GridCellKind, GridCellKindRenderer, GridCellValueOf } from './types';
+type R<K extends GridCellKind> = GridCellKindRenderer<GridCellValueOf<K>>;
+export declare const defaultGridCellRenderers: {
+    [K in GridCellKind]: R<K>;
+};
+/** Clears the hit regions remembered from earlier draws (tests, or after a font change). */
+export declare const clearGridCellRegions: () => void;
+export {};

package/dist/grid/cells/status.d.ts

@@ -0,0 +1,6 @@
+import { GridRect } from '../contracts';
+import { GridCellTheme } from '../theme';
+import { GridCellStatus } from './types';
+export declare const PENDING_DOT = 6;
+/** 6 px dot 3 px in from the top-right corner, ringed with the surface colour; or a 2 px danger inset. */
+export declare const drawGridCellStatus: (ctx: CanvasRenderingContext2D, rect: GridRect, status: GridCellStatus, theme: GridCellTheme) => void;

package/dist/grid/cells/types.d.ts

@@ -0,0 +1,200 @@
+import { GridCellDrawArgs, GridRect } from '../contracts';
+import { GridCellTheme } from '../theme';
+/** Colour family of a chip: `--ui-{tone}-soft` / `--ui-{tone}-text`; scale names alias the matching tone. */
+export type GridChipTone = 'neutral' | 'info' | 'success' | 'warning' | 'danger' | 'blue' | 'green' | 'orange' | 'red' | 'gray';
+export interface GridChip {
+    label: string;
+    tone?: GridChipTone;
+    /** Explicit colours win over `tone` (for example a select option's own colour). */
+    fill?: string;
+    color?: string;
+}
+export interface GridPerson {
+    name: string;
+    /** Loaded once and drawn when ready; initials until then and on failure. */
+    avatarUrl?: string;
+}
+export interface GridRecordLink {
+    id: string;
+    label: string;
+}
+export interface GridAttachment {
+    id: string;
+    name: string;
+    /** Image thumbnail; files without one draw an extension badge. */
+    thumbnailUrl?: string;
+}
+/** Teable's number formatting (packages/core, MIT). */
+export type GridNumberFormat = {
+    type: 'decimal';
+    precision?: number;
+} | {
+    type: 'percent';
+    precision?: number;
+} | {
+    type: 'currency';
+    precision?: number;
+    symbol?: string;
+};
+interface GridCellValueBase {
+    /** No first-click actions (checkbox, rating). Links and buttons still act. */
+    readonly?: boolean;
+}
+export type GridCellValue = GridCellValueBase & ({
+    kind: 'text';
+    text: string;
+}
+/** Multi-line text: one line in the row, newlines shown as spaces. */
+ | {
+    kind: 'longText';
+    text: string;
+}
+/** Right aligned. `text` overrides the formatted value. */
+ | {
+    kind: 'number';
+    value: number | null;
+    format?: GridNumberFormat;
+    text?: string;
+}
+/** Single or multiple select; chips in order. */
+ | {
+    kind: 'select';
+    options: GridChip[];
+} | {
+    kind: 'person';
+    people: GridPerson[];
+}
+/** Already formatted for the viewer's locale and the field's format. */
+ | {
+    kind: 'date';
+    text: string;
+} | {
+    kind: 'boolean';
+    value: boolean;
+}
+/** `value` 0 (empty) to `max` (default 5). */
+ | {
+    kind: 'rating';
+    value: number;
+    max?: number;
+}
+/** URL, email or phone: text with a link icon that opens on the first click. */
+ | {
+    kind: 'url';
+    text: string;
+    href: string;
+}
+/** Linked records as chips. */
+ | {
+    kind: 'link';
+    records: GridRecordLink[];
+} | {
+    kind: 'attachment';
+    files: GridAttachment[];
+}
+/** Completion ring plus percentage; `value` from 0 to 1. */
+ | {
+    kind: 'progress';
+    value: number | null;
+} | {
+    kind: 'button';
+    label: string;
+    disabled?: boolean;
+}
+/** Formula, lookup, rollup, created/modified: read-only text in the muted colour. */
+ | {
+    kind: 'derived';
+    text: string;
+    align?: 'start' | 'end';
+});
+export type GridCellKind = GridCellValue['kind'];
+export type GridCellValueOf<K extends GridCellKind> = Extract<GridCellValue, {
+    kind: K;
+}>;
+/** Saving dot or failed mark drawn over the cell without changing its box. */
+export type GridCellStatus = 'pending' | 'error';
+/**
+ * What a hit area or key asks the caller to do. The renderers never write:
+ * `update` carries the new value (`null` clears) for the caller's optimistic write.
+ */
+export type GridCellAction = {
+    type: 'update';
+    value: boolean | number | null;
+} | {
+    type: 'open-url';
+    href: string;
+} | {
+    type: 'open-record';
+    id: string;
+} | {
+    type: 'open-attachment';
+    id: string;
+} | {
+    type: 'press';
+};
+export interface GridCellHit {
+    action: GridCellAction;
+    /** The hit area in cell coordinates (0, 0 = the cell's top-left). */
+    area: GridRect;
+}
+/** Translated words the accessible text needs; `useGridCells` fills them from the UI locale. */
+export interface GridCellLabels {
+    checked: string;
+    unchecked: string;
+    /** `{value}` and `{max}` placeholders. */
+    rating: string;
+    saving: string;
+    failed: string;
+}
+/** Sizes that follow the row height, so the same cell reads at every density. */
+export interface GridCellMetrics {
+    rowHeight: number;
+    padding: number;
+    /** Chip and avatar height. */
+    chip: number;
+    /** Checkbox, star and link-icon size. */
+    icon: number;
+    fontSize: number;
+    chipFontSize: number;
+}
+/** What `describe` gets besides the value. */
+export interface GridCellTextContext {
+    labels: GridCellLabels;
+    /** BCP 47 locale for number grouping. */
+    locale: string;
+}
+export interface GridCellPaintArgs extends GridCellDrawArgs, GridCellTextContext {
+    cellTheme: GridCellTheme;
+    metrics: GridCellMetrics;
+    images: GridImageSource;
+}
+/** Where a pointer landed, in cell coordinates, and whether the cell was already active before the press. */
+export interface GridCellHitInput {
+    point: {
+        x: number;
+        y: number;
+    };
+    size: {
+        width: number;
+        height: number;
+    };
+    metrics: GridCellMetrics;
+    wasActive: boolean;
+}
+export interface GridImageSource {
+    /** A ready image, or undefined while it loads (the cache asks for a redraw when it lands). */
+    get: (url: string) => CanvasImageSource | undefined;
+}
+export interface GridCellKindRenderer<V extends GridCellValue = GridCellValue> {
+    draw: (ctx: CanvasRenderingContext2D, args: GridCellPaintArgs, value: V) => void;
+    /** Plain text for assistive tech and copy. */
+    describe: (value: V, context: GridCellTextContext) => string;
+    /**
+     * Target under the pointer, if any. Checkbox, rating, link icon and button
+     * act on the first click; chips and thumbnails only when `wasActive`.
+     */
+    hitTest?: (value: V, input: GridCellHitInput) => GridCellHit | null;
+    /** Keyboard equivalent of the hit areas (Enter, Space, digits, Backspace). */
+    keyAction?: (value: V, key: string) => GridCellAction | null;
+}
+export {};

package/dist/grid/cells/use.d.ts

@@ -0,0 +1,7 @@
+import { GridCells, GridCellsOptions } from './registry';
+import { GridCellLabels } from './types';
+export type UseGridCellsOptions = Omit<GridCellsOptions, 'labels'> & {
+    /** Caller wording; missing words come from the UI locale. */
+    labels?: Partial<GridCellLabels>;
+};
+export declare const useGridCells: (options: UseGridCellsOptions) => GridCells;

package/dist/grid/clipboard/copy.d.ts

@@ -0,0 +1,17 @@
+import { GridCell } from '../contracts';
+import { GridCellBlock } from '../range/block';
+import { GridClipboardData } from './write';
+/** Text of each cell of a block, row by row. */
+export declare const readBlock: (block: GridCellBlock, getText: (cell: GridCell) => string) => string[][];
+/** Clipboard data for rows of cell text: TSV, plus an HTML table when there is more than one cell. */
+export declare const clipboardData: (rows: readonly (readonly string[])[]) => GridClipboardData;
+/** True when every row of the block is loaded, so the copy can be synchronous. */
+export declare const isBlockLoaded: (block: GridCellBlock, isRowLoaded?: (rowIndex: number) => boolean) => boolean;
+/** A copy or cut from the grid finished. The caller shows feedback (for example a “Copied N cells” toast). */
+export interface GridCopyEvent {
+    block: GridCellBlock;
+    cellCount: number;
+    cut: boolean;
+    /** False when the browser refused the write or rows could not be loaded; a cut then clears nothing. */
+    ok: boolean;
+}

package/dist/grid/clipboard/index.d.ts

@@ -0,0 +1,4 @@
+export * from './tsv';
+export * from './write';
+export * from './proposal';
+export { readBlock, clipboardData, isBlockLoaded, type GridCopyEvent } from './copy';

package/dist/grid/clipboard/proposal.d.ts

@@ -0,0 +1,35 @@
+import { GridCell, GridSelectionState } from '../contracts';
+import { GridBounds, GridCellRange } from '../range/block';
+export interface GridPasteProposal {
+    /** Top-left target cell: the start of the selection. */
+    start: GridCell;
+    /**
+     * Cell text, row by row, already fitted to the grid: columns past the last
+     * column are dropped; rows past the last row are kept (see `extraRows`).
+     * Plain data: a leading `=` is text, not a formula.
+     */
+    values: string[][];
+    /** The target block, which may reach past the last row. */
+    target: GridCellRange;
+    /** Cells in `values`. */
+    cellCount: number;
+    /** Rows of `values` past the last row; the caller may offer to add them. */
+    extraRows: number;
+    /** Clipboard columns dropped because they fall past the last column. */
+    droppedColumns: number;
+    /** Target columns that are read-only; the caller skips them (and may say so). */
+    readonlyColumns: number[];
+    /** True when one copied cell was repeated over the selected block. */
+    repeated: boolean;
+}
+export interface GridPasteContext extends GridBounds {
+    /** Whether a column takes no writes (the column's `readonly`, or the whole grid). */
+    isReadonlyColumn?: (columnIndex: number) => boolean;
+}
+/**
+ * The proposal for pasting `text` at `selection`, or null when there is
+ * nothing to paste or nowhere to paste it. One copied cell over a cell range
+ * fills the range, as spreadsheets do; anything else pastes from the start
+ * cell at its own size.
+ */
+export declare const buildPasteProposal: (text: string, selection: GridSelectionState, context: GridPasteContext) => GridPasteProposal | null;

package/dist/grid/clipboard/tsv.d.ts

@@ -0,0 +1,14 @@
+/** Rows of cell text to clipboard text. Rows end with CRLF between them, none at the end. */
+export declare const toTsv: (rows: readonly (readonly string[])[]) => string;
+/**
+ * Clipboard text to rows of cell text. Short rows are padded with empty cells
+ * so the result is rectangular; one trailing line break (Excel adds one) is
+ * dropped. Empty text gives no rows.
+ */
+export declare const parseTsv: (text: string) => string[][];
+/**
+ * An HTML table for rich targets (Sheets, Excel, Docs), or undefined for a
+ * single cell, as Baserow does (copyPasteHelper.js `prepareHTMLData`, MIT):
+ * one cell pastes better as plain text.
+ */
+export declare const toHtmlTable: (rows: readonly (readonly string[])[]) => string | undefined;

package/dist/grid/clipboard/write.d.ts

@@ -0,0 +1,21 @@
+export interface GridClipboardData {
+    /** Tab-separated text (`toTsv`). */
+    text: string;
+    /** Optional HTML table (`toHtmlTable`). */
+    html?: string;
+}
+/** Sets the data on a native copy or cut event. False when the event has no clipboard data. */
+export declare const writeClipboardEvent: (event: ClipboardEvent, data: GridClipboardData) => boolean;
+export interface GridClipboardEnvironment {
+    clipboard?: Pick<Clipboard, 'write' | 'writeText'>;
+    ClipboardItem?: typeof ClipboardItem;
+    hasFocus?: () => boolean;
+    /** Runs `retry` once when the window gets focus back. */
+    onFocus?: (retry: () => void) => void;
+}
+/**
+ * Writes data that may still be loading. Resolves once the clipboard holds it;
+ * rejects when the browser refuses or the data fails, so a cut clears nothing.
+ * Call it inside the user gesture (key or click handler).
+ */
+export declare const writeClipboardAsync: (data: Promise<GridClipboardData>, environment?: GridClipboardEnvironment) => Promise<void>;

package/dist/grid/contracts.d.ts

@@ -0,0 +1,200 @@
+import { IGridTheme } from '../grid-core/theme';
+import { GridPasteProposal } from './clipboard/proposal';
+/** A cell as `[columnIndex, rowIndex]`; the row is the data row index. */
+export type GridCell = readonly [columnIndex: number, rowIndex: number];
+/** A run of rows or columns `[from, to]`, or a cell corner `[column, row]` for cell selections. */
+export type GridRange = readonly [number, number];
+export interface GridColumn {
+    /** Stable id, used in callbacks so a reorder does not confuse the caller. */
+    id: string;
+    /** Header text, already translated; also the column's accessible name. */
+    name: string;
+    /** Width in CSS px. Default 150. */
+    width?: number;
+    /** Smallest width a resize reaches. Default 100 (Teable). */
+    minWidth?: number;
+    /** No edit requests for this column (the grid can still select and copy it). */
+    readonly?: boolean;
+    /** Shows the header menu chevron; the caller opens the menu on `header-menu`. */
+    hasMenu?: boolean;
+    /** Reserves room for a type icon; drawn by `drawIcon`. */
+    hasIcon?: boolean;
+    isPrimary?: boolean;
+    description?: string;
+    /** Free tag for the caller's cell renderer lookup (for example a field type). */
+    type?: string;
+    /**
+     * Editor for this column when the host has `getEditText`: `text` (default),
+     * `long-text` (wraps, Shift+Enter for a newline), `number` (right aligned),
+     * or `custom` (the host emits `edit-request` and the caller opens its own
+     * editor, for example a select popover).
+     */
+    editor?: GridEditorKind;
+}
+/** Built-in editors run on the focus owner itself; `custom` is the caller's. */
+export type GridEditorKind = 'text' | 'long-text' | 'number' | 'custom';
+export type GridSelectionKind = 'none' | 'cells' | 'rows' | 'columns';
+/**
+ * The selection the caller sees. `cells`: `ranges` is `[anchor, head]`, each
+ * `[column, row]`. `rows` / `columns`: `ranges` is a list of `[from, to]` runs.
+ */
+export interface GridSelectionState {
+    kind: GridSelectionKind;
+    ranges: readonly GridRange[];
+    activeCell: GridCell | null;
+}
+/** Rows and columns that intersect the viewport, inclusive. */
+export interface GridVisibleRange {
+    startRow: number;
+    stopRow: number;
+    startColumn: number;
+    stopColumn: number;
+}
+/** A rectangle in CSS px relative to the host's top-left corner. */
+export interface GridRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Why the host asks for an editor. The host never opens one itself; the
+ * caller (or the grid edit layer) decides.
+ *
+ * - `key`: a printable key on a selected cell. The key was not cancelled, so
+ *   its character is already in the focus owner; `replace` is true.
+ * - `composition`: an input method started composing on a selected cell.
+ * - `enter`, `f2`, `dblclick`: edit the current value with the caret at the end.
+ * - `tap`: a second finger tap on the selected cell (touch, spec §14). The
+ *   grid edits `text` and `number` in place; `long-text` and `custom` come
+ *   out as `edit-request` with this trigger, so a phone host opens its record
+ *   sheet (or its own editor when it fits the screen).
+ */
+export type GridEditTrigger = 'key' | 'composition' | 'enter' | 'f2' | 'dblclick' | 'tap';
+export interface GridEditRequest {
+    cell: GridCell;
+    column: GridColumn;
+    trigger: GridEditTrigger;
+    /** True when the typed text replaces the value. */
+    replace: boolean;
+}
+/** Where the selection goes after a commit: Enter moves down, Tab right, Shift+Tab left. */
+export type GridEditMove = 'down' | 'right' | 'left' | 'none';
+/**
+ * What ended the edit with a commit: a key, a press on another cell or header
+ * (`pointer`), a press outside the grid, focus leaving (`blur`, including the
+ * window losing focus) or the selection changing by API (`selection`).
+ */
+export type GridCellCommitReason = 'enter' | 'tab' | 'pointer' | 'outside' | 'blur' | 'selection';
+/**
+ * A built-in editor committed a changed value. Write it to the row model
+ * inside the handler (the host repaints the cell, hides the editor and moves
+ * the selection right after, in the same task), then save in the background
+ * and report progress through `cellStatus`.
+ */
+export interface GridCellCommit {
+    cell: GridCell;
+    column: GridColumn;
+    /** The editor's text; parsing it is the caller's job (`validateEdit` can reject it first). */
+    value: string;
+    previous: string;
+    reason: GridCellCommitReason;
+}
+/** A built-in edit ended; `committed` is false after Esc or when nothing changed. */
+export interface GridEditEnd {
+    cell: GridCell;
+    column: GridColumn;
+    committed: boolean;
+}
+/**
+ * Save state of one cell, owned by the caller (the host never writes data):
+ * `saving` (with `createCellStatusStore`, only for saves slower than 300 ms)
+ * or `error` with its translated reason. The cell renderer draws the marks
+ * (`useGridCells` `getStatus`, mapped with `cellStatusMark`); the host shows
+ * an error's message under the active cell.
+ */
+export type GridCellSaveStatus = {
+    state: 'saving';
+} | {
+    state: 'error';
+    message: string;
+} | null;
+/** What a cell renderer gets. Coordinates are canvas CSS px. */
+export interface GridCellDrawArgs extends GridRect {
+    cell: GridCell;
+    column: GridColumn;
+    theme: IGridTheme;
+    isActive: boolean;
+    /** The row has not loaded yet: draw a placeholder, not a value. */
+    isLoading: boolean;
+}
+/**
+ * Vendor extension point for custom cells (task 27 registers its renderers
+ * here). `draw` paints inside the cell rect; it must not read the DOM.
+ */
+export interface GridCellRenderer {
+    draw: (ctx: CanvasRenderingContext2D, args: GridCellDrawArgs) => void;
+}
+export interface GridIconDrawArgs {
+    kind: 'drag' | 'expand' | 'add' | 'primary' | 'description' | 'column';
+    x: number;
+    y: number;
+    size: number;
+    theme: IGridTheme;
+    column?: GridColumn;
+}
+export type GridRowControl = 'drag' | 'expand' | 'checkbox';
+export type GridDraggable = 'none' | 'column' | 'row' | 'all';
+export type GridSelectable = 'none' | 'cell' | 'row' | 'column' | 'all';
+/** The caller's text for each cell: drawn by the default renderer and read to assistive tech. */
+export type GridCellTextGetter = (cell: GridCell) => string;
+export interface GridContextMenuEvent {
+    selection: GridSelectionState;
+    /** Pointer position relative to the host. */
+    x: number;
+    y: number;
+}
+export interface GridReorderEvent {
+    /** The dragged runs (`[from, to]`), in index order. */
+    ranges: readonly GridRange[];
+    /** Where they land, counted before they are removed. */
+    dropIndex: number;
+}
+/** Imperative handle (`ref` on `<GridHost>`). */
+export interface GridHostExpose {
+    /** Moves focus to the grid's focus owner, unless a foreign dialog holds focus. */
+    focus: () => boolean;
+    /** The hidden textarea that holds focus over the active cell; the edit layer may take it over. */
+    focusOwner: () => HTMLTextAreaElement | null;
+    /** Rect of a cell relative to the host, after scroll and frozen columns; null when out of range. */
+    getCellRect: (cell: GridCell) => GridRect | null;
+    /** Minimal instant scroll that brings the cell into view with a 16 px margin. */
+    scrollToCell: (cell: GridCell) => void;
+    getSelection: () => GridSelectionState;
+    /** Replaces the selection; `activeCell` defaults to the first cell of a cell selection. */
+    setSelection: (selection: Omit<GridSelectionState, 'activeCell'> & {
+        activeCell?: GridCell | null;
+    }) => void;
+    /** Redraws cell content (call after data changes that do not change props). */
+    invalidate: () => void;
+    /** Re-reads colour tokens, for example after the app switches theme. */
+    refreshTheme: () => void;
+    /** True while a built-in editor is open. */
+    isEditing: () => boolean;
+    /**
+     * Commits an open built-in editor (before a toolbar action, for example).
+     * False when the draft is invalid or an IME is still composing, so the
+     * editor stays open.
+     */
+    commitEdit: () => boolean;
+    /** Reverts and closes an open built-in editor, keeping the selection. */
+    cancelEdit: () => void;
+    /**
+     * Copies (or cuts) the selection through the async clipboard API, for a menu
+     * or toolbar command; call it inside the click handler. Emits
+     * `clipboard-copy`; resolves false when nothing was copied.
+     */
+    copy: (cut?: boolean) => Promise<boolean>;
+    /** Parses `text` against the selection and emits `paste-request`, for a paste command that read the clipboard itself. */
+    paste: (text: string) => GridPasteProposal | null;
+}

package/dist/grid/edit/cell-status.d.ts

@@ -0,0 +1,33 @@
+import { GridCellStatus as GridCellMark } from '../cells/types';
+import { GridCellSaveStatus } from '../contracts';
+/** Saves faster than this never show the saving mark (spec §3.4). */
+export declare const SAVING_MARK_DELAY_MS = 300;
+export interface GridSaveTicket {
+    /** The save landed: drop the saving mark. */
+    done(): void;
+    /** The save failed; the caller has rolled the value back. Shows the error mark with this (translated) reason. */
+    fail(message: string): void;
+}
+export interface GridCellStatusStore {
+    /** Status for a key, as the host's `cellStatus` returns it. */
+    get(key: string): GridCellSaveStatus;
+    /** A save started for this key. A newer save for the same key replaces the older one. */
+    track(key: string): GridSaveTicket;
+    fail(key: string, message: string): void;
+    clear(key: string): void;
+    dispose(): void;
+}
+export interface GridCellStatusStoreOptions {
+    /** Something visible changed: call the host's `invalidate()`. */
+    onChange: () => void;
+    delayMs?: number;
+    setTimer?: (run: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+}
+/**
+ * Keys are the caller's (for example `${rowId}:${fieldId}`), so marks stay on
+ * their record when rows are sorted or inserted.
+ */
+export declare function createCellStatusStore(options: GridCellStatusStoreOptions): GridCellStatusStore;
+/** The mark the cell renderer draws for a save state (`useGridCells` `getStatus`). */
+export declare function cellStatusMark(status: GridCellSaveStatus): GridCellMark | null;