@synopackageland/ui 0.20.2 → 0.20.4

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;

package/dist/grid/edit/edit-session.d.ts

@@ -0,0 +1,97 @@
+import { EditCommitResult } from '../../interaction/editSession';
+import { GridCell, GridCellCommitReason, GridEditMove, GridEditTrigger, GridEditorKind } from '../contracts';
+/** `edit` changes the value; `view` shows a read-only cell in full (Enter on a formula, for example). */
+export type GridEditMode = 'edit' | 'view';
+export interface GridEditBegin {
+    cell: GridCell;
+    kind: Exclude<GridEditorKind, 'custom'>;
+    mode: GridEditMode;
+    trigger: GridEditTrigger;
+    /** The cell's editable text, from the loaded row (never fetched). */
+    value: string;
+}
+/** What the focus owner should show when an edit begins. */
+export interface GridEditStart {
+    /** The text to put in the focus owner: '' when the typed key replaces the value. */
+    text: string;
+    /** Put the caret after the text (Enter, F2, double-click). */
+    caretAtEnd: boolean;
+}
+export type GridEditKeyInput = Pick<KeyboardEvent, 'key' | 'shiftKey' | 'altKey'> & {
+    commandKey: boolean;
+    /** An input method owns the key: composing, keyCode 229, or Safari's Enter right after `compositionend`. */
+    imeOwned: boolean;
+};
+/**
+ * - `pass`: leave the key to the focus owner (characters, caret keys, a newline)
+ * - `prevent`: the session used the key; cancel it and stop it there
+ */
+export type GridEditKeyResult = 'pass' | 'prevent';
+export interface GridEditState {
+    readonly active: boolean;
+    readonly cell: GridCell | null;
+    readonly mode: GridEditMode;
+    readonly kind: Exclude<GridEditorKind, 'custom'>;
+    readonly draft: string;
+    readonly composing: boolean;
+    readonly dirty: boolean;
+    /** Message from a rejected commit; the editor stays open with a danger ring. */
+    readonly error: string | null;
+    readonly version: number;
+}
+export interface GridEditCommitInput {
+    cell: GridCell;
+    value: string;
+    previous: string;
+    move: GridEditMove;
+    reason: GridCellCommitReason;
+}
+export interface GridEditSessionOptions {
+    /** Return a translated message to keep the editor open (an unparsable number, for example). */
+    validate?: (cell: GridCell, text: string) => string | null | undefined;
+    /** Write the value to the row model now, synchronously; saving is the caller's job. */
+    onCommit: (commit: GridEditCommitInput) => void;
+    /** The edit ended without a commit (Esc, or nothing changed). */
+    onEnd?: (cell: GridCell, committed: boolean) => void;
+    onChange?: (state: GridEditState) => void;
+}
+export declare class GridEditSession {
+    private readonly session;
+    private readonly options;
+    private mode;
+    private kind;
+    /** Where the selection goes once the pending commit lands (a commit can wait for composition to end). */
+    private pending;
+    private wrote;
+    readonly state: GridEditState;
+    constructor(options: GridEditSessionOptions);
+    /**
+     * Enters edit synchronously, in the same handler as the key, press or
+     * composition that asked for it. A second request for the cell already being
+     * edited (the IME keydown, then its `compositionstart`) changes nothing.
+     */
+    begin(request: GridEditBegin): GridEditStart | null;
+    /** The focus owner's text changed (typing, paste, IME). Ignored in view mode. */
+    input(text: string): void;
+    /** Composition start/end. Ending it runs a commit that was waiting for it (Enter or a press during composition). */
+    setComposing(composing: boolean): void;
+    /**
+     * The key table while editing (§3.4). Command keys that an IME owns pass to
+     * it untouched; a commit that is still waiting for composition keeps the
+     * selection where it is.
+     */
+    keyDown(event: GridEditKeyInput): GridEditKeyResult;
+    /**
+     * Ends the edit, writing the draft when it changed. `invalid` keeps the
+     * editor open; `composing` defers the commit to the end of composition.
+     * After the first commit the session is idle, so a second call (Enter, then
+     * the blur it causes) never writes twice.
+     */
+    commit(reason: GridCellCommitReason, move?: GridEditMove): EditCommitResult;
+    /** Esc: revert and leave edit, keeping the selection. False while composing (Esc belongs to the IME). */
+    cancel(): boolean;
+    /** Where the last commit sent the selection; read inside `onCommit`/`onEnd`. */
+    get lastMove(): GridEditMove;
+    /** What ended the last edit (`blur` after Esc or a deferred commit); read inside `onEnd`. */
+    get lastReason(): GridCellCommitReason;
+}

package/dist/grid/edit/use-grid-edit.d.ts

@@ -0,0 +1,48 @@
+import { ShallowRef } from 'vue';
+import { GridCell, GridCellCommitReason, GridColumn, GridEditMove, GridEditTrigger } from '../contracts';
+import { TextBox } from '../focus/editor-style';
+import { GridEditCommitInput, GridEditMode, GridEditState } from './edit-session';
+export interface UseGridEditOptions {
+    owner: () => HTMLTextAreaElement | null | undefined;
+    /** The grid's root: presses inside it are the grid's own. */
+    root: () => HTMLElement | null | undefined;
+    /** Built-in editing is on (the host has `getEditText`). */
+    enabled: () => boolean;
+    getEditText: (cell: GridCell) => string;
+    validate?: (cell: GridCell, column: GridColumn, text: string) => string | null | undefined;
+    columnAt: (index: number) => GridColumn | undefined;
+    rowHeight: () => number;
+    /** From `measureTextBox`, so the editor text sits where the canvas draws it. */
+    textBox: () => TextBox | null;
+    /** Long text shows a hint band only when the caller gives its (translated) text. */
+    hasHint: () => boolean;
+    /** The grid has a selection (presses outside then clear it). */
+    hasSelection: () => boolean;
+    onCommit: (commit: GridEditCommitInput & {
+        column: GridColumn;
+    }) => void;
+    onEnd: (cell: GridCell, column: GridColumn, committed: boolean) => void;
+    moveSelection: (move: Exclude<GridEditMove, 'none'>) => void;
+    clearSelection: () => void;
+    refocus: () => void;
+}
+export interface GridEditHandle {
+    /** One shallowRef bump per session change. */
+    state: Readonly<ShallowRef<GridEditState>>;
+    /** Wrapped lines the open editor needs (long text and the read-only view). */
+    lines: Readonly<ShallowRef<number>>;
+    readonly active: boolean;
+    /** True when this column edits in place (not `custom`). */
+    isInline: (column: GridColumn) => boolean;
+    /** Opens the editor for an edit or view request; false when the column is not inline. */
+    open: (cell: GridCell, column: GridColumn, trigger: GridEditTrigger, mode: GridEditMode) => boolean;
+    /** Keydown on the focus owner while open; true when the session used it. */
+    keyDown: (event: KeyboardEvent, commandKey: boolean) => boolean;
+    compositionStart: () => void;
+    compositionEnd: () => void;
+    input: () => void;
+    blur: () => void;
+    commit: (reason: GridCellCommitReason) => boolean;
+    cancel: () => void;
+}
+export declare function useGridEdit(options: UseGridEditOptions): GridEditHandle;

package/dist/grid/focus/editor-style.d.ts

@@ -0,0 +1,67 @@
+import { IGridTheme } from '../../grid-core/theme';
+import { GridEditorKind } from '../contracts';
+/** Ring width outside the cell box while editing. */
+export declare const EDITOR_RING_PX = 2;
+/** Inner radius; with the 2 px ring the outer corner is Teable's 6 px. */
+export declare const EDITOR_RADIUS_PX = 4;
+/** Line height of wrapped text in the long-text editor and the read-only view. */
+export declare const WRAP_LINE_HEIGHT_PX = 20;
+export declare const LONG_TEXT_MIN_LINES = 2;
+export declare const WRAP_MAX_LINES = 5;
+/** Bottom band for the "Shift + Enter for a new line" hint (spec: 16-22 px). */
+export declare const HINT_BAND_PX = 16;
+export type FocusOwnerTheme = Pick<IGridTheme, 'fontFamily' | 'fontSizeSM' | 'cellTextColor' | 'cellBg' | 'cellLineColorActived'>;
+export interface FocusOwnerLook {
+    /** A built-in editor (or the read-only view) is open on this element. */
+    open: boolean;
+    kind: Exclude<GridEditorKind, 'custom'>;
+    view: boolean;
+    invalid: boolean;
+    /** Shows the hint band (long text with a caller-provided hint). */
+    hint: boolean;
+    rowHeight: number;
+    /** Wrapped lines the text needs, measured by the caller; ignored for single-line editors. */
+    lines: number;
+    theme: FocusOwnerTheme;
+    dangerColor: string;
+    /** The grid font's box and where the canvas draws its baseline, from `measureTextBox`; null when unknown. */
+    textBox?: TextBox | null;
+}
+type PaddingLook = Pick<FocusOwnerLook, 'kind' | 'view' | 'hint' | 'rowHeight' | 'textBox'>;
+/** The grid font's box (CSS content area) and the canvas baseline, in CSS px. */
+export interface TextBox {
+    ascent: number;
+    descent: number;
+    /** How far below the row's middle the canvas draws the alphabetic baseline. */
+    drop: number;
+}
+/**
+ * The grid draws text with `textBaseline = 'middle'` at the row centre, and
+ * engines put that baseline differently (13 px Verdana: Chromium 3.73 px
+ * below the middle, WebKit 5 px), so ask the canvas rather than assume.
+ */
+export declare function measureTextBox(doc: Document, fontSize: number, fontFamily: string): TextBox | null;
+/**
+ * Padding and line height that put the first line's baseline where the canvas
+ * draws it. Engines floor the half-leading, so a fractional line height cannot
+ * land a fractional baseline: the line box is the font's own box (no
+ * leading), at whole pixels, placed by the top padding. Wrapped text keeps
+ * its 20 px lines and moves the first one the same way. Without metrics
+ * (no canvas), the text centres on the row.
+ */
+export declare function editorPadding(look: PaddingLook): {
+    top: number;
+    bottom: number;
+    lineHeight: number;
+};
+/** Editor height: the row for single-line editors; 2-5 lines (1-5 in the read-only view) for wrapped text, never less than the row. */
+export declare function editorHeight(look: PaddingLook & Pick<FocusOwnerLook, 'lines'>): number;
+/** Lines the content needs, from the textarea's scrollHeight measured at zero height. */
+export declare function measuredLines(scrollHeight: number, look: PaddingLook): number;
+/** Inline style of the focus owner textarea. */
+export declare function focusOwnerStyle(look: FocusOwnerLook): Record<string, string>;
+/** The hint band's text, inside the editor's bottom padding. */
+export declare function hintStyle(look: Pick<FocusOwnerLook, 'theme'>): Record<string, string>;
+/** The error reason under the cell: an overlay, never in flow. */
+export declare function messageStyle(look: Pick<FocusOwnerLook, 'theme'>): Record<string, string>;
+export {};

package/dist/grid/host/GridHost.vue.d.ts

@@ -0,0 +1,137 @@
+import { IGridTheme } from '../../grid-core/theme';
+import { GridCopyEvent, GridPasteProposal } from '../clipboard';
+import { GridCellBlock } from '../range/block';
+import { GridFillRequest } from '../range/fill';
+import { GridCell, GridCellCommit, GridCellSaveStatus, GridEditEnd, GridCellRenderer, GridCellTextGetter, GridColumn, GridContextMenuEvent, GridDraggable, GridEditRequest, GridHostExpose, GridIconDrawArgs, GridRect, GridReorderEvent, GridRowControl, GridSelectable, GridSelectionState, GridVisibleRange } from '../contracts';
+type __VLS_Props = {
+    columns: GridColumn[];
+    rowCount: number;
+    /** Text of each cell: drawn by the default renderer and read to assistive tech. */
+    getCellText: GridCellTextGetter;
+    /** Accessible name of the grid, already translated. */
+    label: string;
+    /** Accessible name of a row, already translated. Default: the row number. */
+    getRowLabel?: (rowIndex: number) => string;
+    /** False draws the row as a static placeholder bar until its data arrives. */
+    isRowLoaded?: (rowIndex: number) => boolean;
+    /** Custom cell painter per column (vendor extension for field renderers). */
+    cellRenderer?: (column: GridColumn, columnIndex: number) => GridCellRenderer | undefined;
+    drawIcon?: (ctx: CanvasRenderingContext2D, icon: GridIconDrawArgs) => void;
+    /** First load: skeleton rows at the real row height, after `loadingDelay`. */
+    loading?: boolean;
+    loadingDelay?: number;
+    readonly?: boolean;
+    /** A caller's own editor (a `custom` column) is open over the active cell: keys belong to it, not to the grid. */
+    editing?: boolean;
+    /**
+     * The editable text of a cell, from the loaded row. Given, the grid edits
+     * `text`, `long-text` and `number` columns in place on its focus owner and
+     * emits `cell-commit`; read-only cells open a read-only view on Enter.
+     */
+    getEditText?: (cell: GridCell) => string;
+    /** Return a translated message to keep the editor open with a danger ring (an unparsable number, for example). */
+    validateEdit?: (cell: GridCell, column: GridColumn, text: string) => string | null | undefined;
+    /** Save state per cell (see `createCellStatusStore`): an error's message shows under the active cell; call `invalidate()` when it changes. The cell renderer draws the marks. */
+    cellStatus?: (cell: GridCell) => GridCellSaveStatus;
+    /** Hint at the bottom of the long-text editor, already translated (for example “Shift + Enter for a new line”). */
+    editHint?: string;
+    /** Row and header height in px. Default: the `--ui-grid-row-height` / `--ui-grid-header-height` tokens. */
+    rowHeight?: number;
+    headerHeight?: number;
+    freezeColumnCount?: number;
+    rowControls?: GridRowControl[];
+    selectable?: GridSelectable;
+    draggable?: GridDraggable;
+    columnResizable?: boolean;
+    /** Shows the fill handle on a cell range; a drag emits `fill-request`. */
+    fillable?: boolean;
+    /** Text a copy puts on the clipboard for a cell. Default: `getCellText`. */
+    getCopyText?: GridCellTextGetter;
+    /**
+     * Text of a block that has rows not loaded yet (`isRowLoaded` false), row by
+     * row. Without it, copying such a block fails with `ok: false`.
+     */
+    resolveCopy?: (block: GridCellBlock) => Promise<string[][]>;
+    themeOverrides?: Partial<IGridTheme>;
+    /** Row tinted as open: the record shown in the caller's sheet or panel, so the user keeps their place. */
+    highlightedRow?: number | null;
+};
+type __VLS_Slots = {
+    /** Shown over the body when there are no rows and nothing is loading. Default: “No data”. */
+    empty?: () => unknown;
+    /** Layer above the focus owner for editors and popovers (task 26). */
+    overlay?: (scope: {
+        activeCell: GridCell | null;
+        getCellRect: (cell: GridCell) => GridRect | null;
+    }) => unknown;
+};
+declare const __VLS_base: import('vue').DefineComponent<__VLS_Props, GridHostExpose, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    "context-menu": (event: GridContextMenuEvent) => any;
+    "selection-change": (state: GridSelectionState) => any;
+    "edit-request": (request: GridEditRequest) => any;
+    "cell-commit": (commit: GridCellCommit) => any;
+    "edit-end": (end: GridEditEnd) => any;
+    "clear-request": (selection: GridSelectionState) => any;
+    "row-expand": (rowIndex: number, columnIndex?: number | undefined) => any;
+    "header-menu": (columnIndex: number, rect: GridRect) => any;
+    "column-resize": (columnIndex: number, width: number) => any;
+    "column-resize-end": (columnIndex: number, width: number) => any;
+    "column-width-save": (columnIndex: number, width: number) => any;
+    "fill-request": (request: GridFillRequest) => any;
+    "clipboard-copy": (event: GridCopyEvent) => any;
+    "paste-request": (proposal: GridPasteProposal) => any;
+    "column-reorder": (event: GridReorderEvent) => any;
+    "row-reorder": (event: GridReorderEvent) => any;
+    "visible-range-change": (range: GridVisibleRange) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{
+    "onContext-menu"?: ((event: GridContextMenuEvent) => any) | undefined;
+    "onSelection-change"?: ((state: GridSelectionState) => any) | undefined;
+    "onEdit-request"?: ((request: GridEditRequest) => any) | undefined;
+    "onCell-commit"?: ((commit: GridCellCommit) => any) | undefined;
+    "onEdit-end"?: ((end: GridEditEnd) => any) | undefined;
+    "onClear-request"?: ((selection: GridSelectionState) => any) | undefined;
+    "onRow-expand"?: ((rowIndex: number, columnIndex?: number | undefined) => any) | undefined;
+    "onHeader-menu"?: ((columnIndex: number, rect: GridRect) => any) | undefined;
+    "onColumn-resize"?: ((columnIndex: number, width: number) => any) | undefined;
+    "onColumn-resize-end"?: ((columnIndex: number, width: number) => any) | undefined;
+    "onColumn-width-save"?: ((columnIndex: number, width: number) => any) | undefined;
+    "onFill-request"?: ((request: GridFillRequest) => any) | undefined;
+    "onClipboard-copy"?: ((event: GridCopyEvent) => any) | undefined;
+    "onPaste-request"?: ((proposal: GridPasteProposal) => any) | undefined;
+    "onColumn-reorder"?: ((event: GridReorderEvent) => any) | undefined;
+    "onRow-reorder"?: ((event: GridReorderEvent) => any) | undefined;
+    "onVisible-range-change"?: ((range: GridVisibleRange) => any) | undefined;
+}>, {
+    loading: boolean;
+    readonly: boolean;
+    rowHeight: number;
+    draggable: GridDraggable;
+    selectable: GridSelectable;
+    editing: boolean;
+    freezeColumnCount: number;
+    rowControls: GridRowControl[];
+    drawIcon: (ctx: CanvasRenderingContext2D, icon: GridIconDrawArgs) => void;
+    headerHeight: number;
+    columnResizable: boolean;
+    fillable: boolean;
+    getRowLabel: (rowIndex: number) => string;
+    isRowLoaded: (rowIndex: number) => boolean;
+    cellRenderer: (column: GridColumn, columnIndex: number) => GridCellRenderer | undefined;
+    loadingDelay: number;
+    getEditText: (cell: GridCell) => string;
+    validateEdit: (cell: GridCell, column: GridColumn, text: string) => string | null | undefined;
+    cellStatus: (cell: GridCell) => GridCellSaveStatus;
+    editHint: string;
+    getCopyText: GridCellTextGetter;
+    resolveCopy: (block: GridCellBlock) => Promise<string[][]>;
+    themeOverrides: Partial<IGridTheme>;
+    highlightedRow: number | null;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/grid/host/controller.d.ts

@@ -0,0 +1,219 @@
+import { AutoScroller } from '../../grid-core/auto-scroll';
+import { ColumnResizeController } from '../../grid-core/column-resize';
+import { CoordinateManager } from '../../grid-core/coordinate';
+import { DragController } from '../../grid-core/drag';
+import { IGridRenderProps, IVisibleRegion } from '../../grid-core/renderer/layout';
+import { SelectionController } from '../../grid-core/selection-controller';
+import { IGridTheme } from '../../grid-core/theme';
+import { IColumnResizeState, IDragState, IGridColumn, IMouseState, IPosition, IRowControlItem, IScrollState } from '../../grid-core/types';
+import { GridCell, GridColumn, GridDraggable, GridEditTrigger, GridRange, GridRect, GridRowControl, GridSelectable, GridSelectionState, GridVisibleRange } from '../contracts';
+import { GridFillRequest } from '../range/fill';
+export interface GridHostConfig {
+    columns: readonly GridColumn[];
+    /** Data rows to lay out (skeleton rows while the first page loads). */
+    rowCount: number;
+    rowHeight: number;
+    headerHeight: number;
+    freezeColumnCount: number;
+    rowControls: readonly GridRowControl[];
+    selectable: GridSelectable;
+    draggable: GridDraggable;
+    columnResizable: boolean;
+    /** No edit or clear requests. */
+    readonly: boolean;
+    /** Shows the fill handle on a cell range (ignored when read-only). */
+    fillable?: boolean;
+    /**
+     * Touch UI (a coarse primary pointer): no fill handle and no column resize
+     * handle, as in Teable's touch layer. Touch gestures go through `tap` and
+     * `longPress`, never through the pointer methods. At a grid width of
+     * `PHONE_MAX_WIDTH` or less it is the phone layout (see `isPhone`).
+     */
+    touch?: boolean;
+}
+export interface GridHostHooks {
+    /** Something visible changed; draw on the next frame. */
+    render: () => void;
+    selectionChange: (state: GridSelectionState) => void;
+    /** Scroll the host's scroller to this position now (auto-scroll, keyboard). */
+    scrollTo: (left: number, top: number) => void;
+    editRequest: (cell: GridCell, column: GridColumn, trigger: GridEditTrigger, replace: boolean) => void;
+    /** Enter, F2 or double-click on a read-only cell: show its value in full (the edit layer's read-only view). */
+    viewRequest?: (cell: GridCell, column: GridColumn, trigger: GridEditTrigger) => void;
+    clearRequest: (selection: GridSelectionState) => void;
+    /** Open the row's record. `columnIndex`: the tapped field, on a phone (scroll the record to it). */
+    rowExpand: (rowIndex: number, columnIndex?: number) => void;
+    headerMenu: (columnIndex: number, rect: GridRect) => void;
+    columnResize: (columnIndex: number, width: number, done: boolean) => void;
+    reorder: (kind: 'columns' | 'rows', ranges: readonly GridRange[], dropIndex: number) => void;
+    contextMenu: (selection: GridSelectionState, point: IPosition) => void;
+    visibleRangeChange: (range: GridVisibleRange) => void;
+    /** A fill-handle drag ended past the source rows; the selection already covers source and target. */
+    fill?: (request: GridFillRequest) => void;
+}
+export interface GridPointerInput extends IPosition {
+    shiftKey: boolean;
+    /** The platform command key: Cmd on macOS, Ctrl elsewhere. */
+    commandKey: boolean;
+}
+export type GridKeyInput = Pick<KeyboardEvent, 'key' | 'keyCode' | 'shiftKey' | 'altKey' | 'metaKey' | 'ctrlKey' | 'isComposing'> & {
+    /** The platform command key: Cmd on macOS, Ctrl elsewhere. */
+    commandKey: boolean;
+};
+/** `prevent`: the host cancels the key. `pass`: the key goes on to the focus owner. `ignore`: not the grid's key. */
+export type GridKeyResult = 'prevent' | 'pass' | 'ignore';
+/** Width of the row header: the row number, plus 24 px per row control beyond the first. */
+export declare const rowHeaderWidth: (controls: readonly GridRowControl[]) => number;
+/** Grid widths up to this are a phone on touch: a tap opens the record (Teable's `(max-width: 640px)`). */
+export declare const PHONE_MAX_WIDTH = 640;
+/** The phone's row header: row numbers only, as Teable's touch grid. */
+export declare const PHONE_ROW_HEADER_WIDTH = 50;
+export declare class GridHostController {
+    coord: CoordinateManager;
+    scroll: IScrollState;
+    mouseState: IMouseState;
+    readonly selection: SelectionController;
+    readonly resize: ColumnResizeController;
+    readonly drag: DragController;
+    readonly autoScroller: AutoScroller;
+    /** The grid-core column list; a new array whenever columns or widths change. */
+    gridColumns: IGridColumn[];
+    rowControls: IRowControlItem[];
+    dragState: IDragState;
+    resizeState: IColumnResizeState;
+    /** Bumped on every change that needs the cached cell layer redrawn. */
+    contentVersion: number;
+    theme: Pick<IGridTheme, 'iconSizeXS' | 'iconSizeMD'>;
+    private config;
+    private width;
+    private height;
+    /** Live widths from a resize in progress or not yet echoed back through `columns`. */
+    private widthOverrides;
+    private visible;
+    private down;
+    private lastPoint;
+    private lastModifiers;
+    private lastSelection;
+    /** The source block while the fill handle is dragged. */
+    private fillSource;
+    private readonly hooks;
+    constructor(config: GridHostConfig, hooks: GridHostHooks);
+    /**
+     * Touch on a grid no wider than 640 px. There a tap opens the record (the
+     * cell and its editor cannot fit beside the keyboard), the row header shows
+     * numbers only and no column is frozen: Teable's phone grid.
+     */
+    get isPhone(): boolean;
+    private visibleRowControls;
+    private gutterWidth;
+    private createCoordinate;
+    private applyColumns;
+    /**
+     * Frozen columns that fit: the scrolling part keeps at least 240 px, so on a
+     * phone a wide first column stops freezing (Teable's getMaxFreezeColumnCount).
+     */
+    private freezeCount;
+    configure(next: GridHostConfig): void;
+    /** Drops a selection that points past the data after rows or columns went away. */
+    private clampSelection;
+    get settings(): Readonly<GridHostConfig>;
+    setViewport(width: number, height: number): void;
+    get viewport(): {
+        width: number;
+        height: number;
+    };
+    /** Scrollable content size for the scroller's spacer. */
+    get contentSize(): {
+        width: number;
+        height: number;
+    };
+    /** The scroller moved (native scroll or our own `scrollTo`). */
+    setScroll(left: number, top: number): void;
+    private scrollTo;
+    private updateVisible;
+    get visibleRegion(): IVisibleRegion;
+    /** Marks cell content stale (data, columns or theme changed). */
+    invalidate(): void;
+    getSelection(): GridSelectionState;
+    setSelection(next: Omit<GridSelectionState, 'activeCell'> & {
+        activeCell?: GridCell | null;
+    }): void;
+    private selectCell;
+    getCellRect(cell: GridCell): GridRect | null;
+    /** Minimal scroll that shows the cell with Teable's 16 px buffer; instant. */
+    scrollToCell(cell: GridCell): void;
+    private regionContext;
+    private get isFillEnabled();
+    /** No resize handle on touch: a 5 px edge is no finger target (Teable has none on touch either). */
+    private get isResizeEnabled();
+    /** True while the fill handle is dragged. */
+    get isFilling(): boolean;
+    /**
+     * The data cell under a drag, with the pointer clamped to the body: past an
+     * edge, over a header or over blank space it is the nearest visible cell, so
+     * the head never leaves the data while auto-scroll runs.
+     */
+    private cellUnderDrag;
+    /** The row under a fill drag (vertical only). */
+    private fillTargetRow;
+    activeCellBound(): {
+        columnIndex: number;
+        rowIndex: number;
+        width: number;
+        height: number;
+    } | null;
+    hitTest(point: IPosition): IMouseState;
+    /** Returns true when the press belongs to the grid (the host then claims focus). */
+    pointerDown(input: GridPointerInput): boolean;
+    /** Hover and gestures. `fromAutoScroll` re-derives the head after an auto-scroll tick. */
+    pointerMove(input: GridPointerInput, fromAutoScroll?: boolean): void;
+    pointerUp(input: GridPointerInput): void;
+    private endFill;
+    /** Pointer left the host without a press. */
+    pointerLeave(): void;
+    /** Lost pointer capture or Esc during a gesture: nothing moves, the width comes back. */
+    cancelGesture(): boolean;
+    get isGestureActive(): boolean;
+    doubleClick(point: IPosition): void;
+    contextMenu(point: IPosition): boolean;
+    /** True when `cell` is the active cell and the whole selection. */
+    private isSoleActiveCell;
+    /**
+     * A finger tap (no move past the slop, released before the long press).
+     * The tapped row or header keeps a pressed tint until `clearTapFeedback`.
+     *
+     * - A cell on a phone (`isPhone`): selects it and opens the record
+     *   (`rowExpand` with the column), as Teable's touch grid.
+     * - A cell on a wider touch screen: the first tap selects it, a second tap
+     *   on the selected cell asks for an edit (`tap` trigger).
+     * - A header with a menu opens the menu, as in Teable's touch layer (the
+     *   16 px chevron is no finger target); without one it selects the column.
+     * - The row header is one target: on a phone it opens the record; wider, it
+     *   expands the row with the `expand` control, else toggles the checkbox.
+     *
+     * There is no range, fill or drag on touch.
+     */
+    tap(input: IPosition): void;
+    /** Ends the pressed tint of the last tap (the host calls it about 400 ms later). */
+    clearTapFeedback(): void;
+    /** A finger held still for 250 ms: the context menu, as a right click (keeps a selection it lands in). */
+    longPress(input: IPosition): boolean;
+    private requestEdit;
+    /**
+     * After an edit of `cell` commits: Enter moves down, Tab right, Shift+Tab
+     * left (Teable's enterCommitSelection / tabSelection), from the edited cell.
+     */
+    moveAfterEdit(cell: GridCell, move: 'down' | 'right' | 'left'): void;
+    /** An input method started composing on the selected cell. */
+    compositionStart(): void;
+    /**
+     * Key on the focus owner while no editor is open (spec §3.1–3.2). Printable
+     * and IME keys pass through so the first character lands in the focus owner.
+     */
+    keyDown(event: GridKeyInput): GridKeyResult;
+    /** Everything `drawGrid` needs except the theme and the cell/icon painters. */
+    frame(): Omit<IGridRenderProps, 'theme' | 'drawCell' | 'drawIcon' | 'height'>;
+    /** Cursor for the current hover state; set on the same move (spec §3.12). */
+    get cursor(): string;
+    dispose(): void;
+}

package/dist/grid/host/dom.d.ts

@@ -0,0 +1,10 @@
+/** macOS and iPadOS use Cmd as the command key; everything else uses Ctrl. */
+export declare const isMacPlatform: () => boolean;
+export interface GridDensity {
+    rowHeight: number;
+    headerHeight: number;
+}
+/** Row and header height from the density tokens in effect on `el` (task 08 owns their values). */
+export declare const readGridDensity: (el: Element, fallback?: GridDensity) => GridDensity;
+/** Skeleton rows for the first load: as many whole rows as fit under the header (spec §3.12). */
+export declare const skeletonRowCount: (viewportHeight: number, headerHeight: number, rowHeight: number) => number;

package/dist/grid/index.d.ts

@@ -0,0 +1,8 @@
+export { default as GridHost } from './host/GridHost.vue';
+export type * from './contracts';
+export type { IGridTheme as GridTheme } from '../grid-core/theme';
+export * from './cells';
+export { createGridCellTheme, readGridCellTheme, gridCellMetrics, defaultGridCellTheme, GRID_CELL_TOKENS, GRID_CHIP_TOKENS, type GridCellTheme, type GridChipColors } from './theme';
+export { cellStatusMark, createCellStatusStore, SAVING_MARK_DELAY_MS, type GridCellStatusStore, type GridCellStatusStoreOptions, type GridSaveTicket } from './edit/cell-status';
+export { cellRange, selectionBlock, selectionStart, blockCellCount, planFill, filledRange, fillSeries, type GridCellRange, type GridCellBlock, type GridBounds, type GridFillRequest, type GridFillDirection, type GridFillValue } from './range';
+export { toTsv, parseTsv, toHtmlTable, buildPasteProposal, writeClipboardAsync, writeClipboardEvent, type GridPasteProposal, type GridPasteContext, type GridCopyEvent, type GridClipboardData } from './clipboard';

package/dist/grid/range/block.d.ts

@@ -0,0 +1,30 @@
+import { GridCell, GridSelectionState } from '../contracts';
+/** A rectangle of cells, inclusive on both ends. */
+export interface GridCellRange {
+    startColumn: number;
+    endColumn: number;
+    startRow: number;
+    endRow: number;
+}
+/**
+ * The cells a selection covers, as ordered row and column indexes. A cell
+ * selection is one rectangle; a row selection covers every column of its
+ * rows; a column selection covers every row of its columns. Several runs
+ * (Cmd+click on headers) are joined in index order, as Teable copies them.
+ */
+export interface GridCellBlock {
+    rows: readonly number[];
+    columns: readonly number[];
+}
+export interface GridBounds {
+    rowCount: number;
+    columnCount: number;
+}
+/** The rectangle of a cell selection, clamped to the data; null for other kinds. */
+export declare const cellRange: (state: Pick<GridSelectionState, "kind" | "ranges">, bounds: GridBounds) => GridCellRange | null;
+/** The cells a selection covers; null when nothing is selected or there is no data. */
+export declare const selectionBlock: (state: Pick<GridSelectionState, "kind" | "ranges">, bounds: GridBounds) => GridCellBlock | null;
+/** The top-left cell of a selection: where a paste starts. */
+export declare const selectionStart: (state: GridSelectionState, bounds: GridBounds) => GridCell | null;
+/** Number of cells in a block. */
+export declare const blockCellCount: (block: GridCellBlock) => number;