@extable/core 0.1.0

package/dist/lockManager.d.ts

@@ -0,0 +1,15 @@
+import type { LockMode, ServerAdapter, UserInfo } from './types';
+export declare class LockManager {
+    private lockedRows;
+    private mode;
+    private server?;
+    private user?;
+    constructor(mode: LockMode, server?: ServerAdapter, user?: UserInfo);
+    setMode(mode: LockMode): void;
+    setUser(user?: UserInfo): void;
+    selectRow(rowId: string): Promise<void>;
+    unlockOnMove(currentRowId?: string): Promise<void>;
+    unlockOnCommit(keepRowId?: string): Promise<void>;
+    unlockRows(rowIds: string[]): Promise<void>;
+    getLockedRows(): Set<string>;
+}

package/dist/renderers.d.ts

@@ -0,0 +1,129 @@
+import type { DataModel } from "./dataModel";
+import type { SelectionRange, EditMode } from "./types";
+export interface ViewportState {
+    scrollTop: number;
+    scrollLeft: number;
+    clientWidth: number;
+    clientHeight: number;
+    deltaX: number;
+    deltaY: number;
+    timestamp: number;
+}
+export interface Renderer {
+    mount(root: HTMLElement): void;
+    render(state?: ViewportState): void;
+    destroy(): void;
+    getCellElements(): NodeListOf<HTMLElement> | null;
+    hitTest(event: MouseEvent): {
+        rowId: string;
+        colKey: string | null;
+        element?: HTMLElement;
+        rect: DOMRect;
+    } | null;
+    setActiveCell(rowId: string | null, colKey: string | null): void;
+    setSelection(ranges: SelectionRange[]): void;
+}
+export declare class HTMLRenderer implements Renderer {
+    private dataModel;
+    private tableEl;
+    private defaultRowHeight;
+    private rowHeaderWidth;
+    private activeRowId;
+    private activeColKey;
+    private selection;
+    private valueFormatCache;
+    private measureCache;
+    private frame;
+    constructor(dataModel: DataModel);
+    mount(root: HTMLElement): void;
+    setActiveCell(rowId: string | null, colKey: string | null): void;
+    setSelection(ranges: SelectionRange[]): void;
+    render(_state?: ViewportState): void;
+    destroy(): void;
+    getCellElements(): NodeListOf<HTMLElement> | null;
+    hitTest(event: MouseEvent): {
+        rowId: string;
+        colKey: string;
+        element: HTMLElement;
+        rect: DOMRect;
+    } | {
+        rowId: string;
+        colKey: null;
+        element: HTMLElement;
+        rect: DOMRect;
+    } | null;
+    private renderHeader;
+    private renderRow;
+    private updateActiveClasses;
+    private applySelectionClasses;
+    private formatValue;
+}
+export declare class CanvasRenderer implements Renderer {
+    private getEditMode;
+    private static readonly MAX_CANVAS_DIM_PX;
+    private static readonly ROW_HEIGHT_MEASURE_CHUNK;
+    private static readonly ROW_HEIGHT_MEASURE_TIME_BUDGET_MS;
+    private static readonly TEXT_MEASURE_CACHE_MAX;
+    private root;
+    private canvas;
+    private spacer;
+    private overlayLayer;
+    private tooltip;
+    private tooltipTarget;
+    private tooltipMessage;
+    private dataModel;
+    private readonly rowHeight;
+    private readonly headerHeight;
+    private readonly lineHeight;
+    private readonly padding;
+    private readonly rowHeaderWidth;
+    private activeRowId;
+    private activeColKey;
+    private selection;
+    private valueFormatCache;
+    private textMeasureCache;
+    private frame;
+    private cursorTimer;
+    private pendingCursorPoint;
+    private hoverHeaderColKey;
+    private hoverHeaderIcon;
+    private rowHeightCacheKey;
+    private rowHeightMeasuredVersion;
+    private rowHeightMeasureRaf;
+    private rowHeightMeasureTask;
+    private heightIndex;
+    constructor(dataModel: DataModel, getEditMode?: () => EditMode);
+    mount(root: HTMLElement): void;
+    setActiveCell(rowId: string | null, colKey: string | null): void;
+    setSelection(ranges: SelectionRange[]): void;
+    render(state?: ViewportState): void;
+    destroy(): void;
+    private ensureHeightIndex;
+    private applyRowHeightUpdates;
+    private getRowHeightCacheKey;
+    private cancelRowHeightMeasurement;
+    private scheduleRowHeightMeasurement;
+    private runRowHeightMeasurement;
+    private handleClick;
+    getCellElements(): null;
+    hitTest(event: MouseEvent): {
+        rowId: string;
+        colKey: string;
+        rect: DOMRect;
+    } | {
+        rowId: string;
+        colKey: null;
+        rect: DOMRect;
+    } | null;
+    private isPointInSelection;
+    private handlePointerMove;
+    private handlePointerLeave;
+    private positionTooltipAtRect;
+    private refreshTooltipPosition;
+    private getCellRect;
+    private updateCanvasCursor;
+    private measureRowHeight;
+    private wrapLines;
+    private drawCellText;
+    private formatValue;
+}

package/dist/selectionManager.d.ts

@@ -0,0 +1,135 @@
+import type { Command, EditMode, SelectionRange } from "./types";
+import type { DataModel } from "./dataModel";
+type EditHandler = (cmd: Command, commit: boolean) => void;
+type RowSelectHandler = (rowId: string) => void;
+type MoveHandler = (rowId?: string) => void;
+type HitTest = (event: MouseEvent) => {
+    rowId: string;
+    colKey: string | null;
+    element?: HTMLElement;
+    rect: DOMRect;
+} | null;
+type ActiveChange = (rowId: string | null, colKey: string | null) => void;
+type ContextMenuHandler = (rowId: string | null, colKey: string | null, clientX: number, clientY: number) => void;
+type SelectionChange = (ranges: SelectionRange[]) => void;
+type UndoRedoHandler = () => void;
+export declare class SelectionManager {
+    private dataModel;
+    private onActiveChange;
+    private onSelectionChange;
+    private onUndo;
+    private onRedo;
+    private root;
+    private editMode;
+    private onEdit;
+    private onRowSelect;
+    private onMove;
+    private hitTest;
+    private onContextMenu;
+    private handleDocumentContextMenu;
+    private selectionRanges;
+    private inputEl;
+    private floatingInputWrapper;
+    private selectionInput;
+    private copyToastEl;
+    private copyToastTimer;
+    private selectionMode;
+    private lastBooleanCell;
+    private selectionAnchor;
+    private dragging;
+    private dragStart;
+    private pointerDownClient;
+    private dragMoved;
+    private dragSelectionChanged;
+    private suppressNextClick;
+    private fillDragging;
+    private fillSource;
+    private fillEndRowIndex;
+    private rootCursorBackup;
+    private lastPointerClient;
+    private autoScrollRaf;
+    private autoScrollActive;
+    private activeCell;
+    private activeHost;
+    private activeHostOriginalText;
+    private composing;
+    private lastCompositionEnd;
+    private readonly handleSelectionBlur;
+    private isCellReadonly;
+    constructor(root: HTMLElement, editMode: EditMode, onEdit: EditHandler, onRowSelect: RowSelectHandler, onMove: MoveHandler, hitTest: HitTest, dataModel: DataModel, isCellReadonly: (rowId: string, colKey: string) => boolean, onActiveChange: ActiveChange, onContextMenu: ContextMenuHandler, onSelectionChange: SelectionChange, onUndo: UndoRedoHandler, onRedo: UndoRedoHandler);
+    setEditMode(mode: EditMode): void;
+    syncAfterRowsChanged(): void;
+    navigateToCell(rowId: string, colKey: string): void;
+    cancelEditing(): void;
+    destroy(): void;
+    onScroll(scrollTop: number, scrollLeft: number): void;
+    private bind;
+    private updateFillHandleFlag;
+    private findColumn;
+    private pad2;
+    private formatLocalDateForInput;
+    private formatLocalTimeForInput;
+    private formatLocalDateTimeForInput;
+    private normalizeTemporalInitialValue;
+    private ensureCopyToast;
+    private teardownCopyToast;
+    private positionCopyToast;
+    private showCopyToast;
+    private ensureSelectionInput;
+    private focusSelectionInput;
+    private openEditorAtActiveCell;
+    private escapeCssAttrValue;
+    private findHtmlCellElement;
+    private computeCanvasCellRect;
+    private computeCanvasCellBoxContent;
+    private getCanvasCellMetrics;
+    private ensureVisibleCell;
+    private moveActiveCell;
+    private handlePointerDown;
+    private getHitAtClientPoint;
+    private updateDragFromClientPoint;
+    private updateFillDragFromClientPoint;
+    private computeAutoScrollDelta;
+    private startAutoScroll;
+    private stopAutoScroll;
+    private handlePointerMove;
+    private handlePointerUp;
+    private commitFill;
+    private teardownSelectionInput;
+    private handleSelectionCopy;
+    private handleSelectionCut;
+    private handleSelectionPaste;
+    private handleSelectionCompositionStart;
+    copySelection(): Promise<void>;
+    pasteFromClipboard(): Promise<void>;
+    private handleSelectionKeydown;
+    private getActiveIndices;
+    private normalizeRange;
+    private getCopyRange;
+    private cellToClipboardString;
+    private escapeHtml;
+    private buildSelectionClipboardPayload;
+    private clearSelectionValues;
+    private parseClipboardGrid;
+    private parseTsv;
+    private parseHtmlTable;
+    private coerceCellValue;
+    private applyClipboardGrid;
+    private createEditor;
+    private autosize;
+    private positionFloatingContentBox;
+    private handleClick;
+    private toggleBoolean;
+    private handleContextMenu;
+    private applySelectionFromHit;
+    private mergeRanges;
+    private activateCellElement;
+    private activateFloating;
+    private handleKey;
+    private commitEdit;
+    private readActiveValue;
+    private bindImmediateCommit;
+    private cancelEdit;
+    private teardownInput;
+}
+export {};

package/dist/styleResolver.d.ts

@@ -0,0 +1,10 @@
+import type { ColumnSchema, ResolvedCellStyle, StyleDelta } from "./types";
+import type { DataModel } from "./dataModel";
+export declare function columnFormatToStyle(col: ColumnSchema): ResolvedCellStyle;
+export declare function mergeStyle(base: ResolvedCellStyle, override?: StyleDelta | null): ResolvedCellStyle;
+export declare function resolveCellStyles(dataModel: DataModel, rowId: string, col: ColumnSchema): {
+    columnStyle: ResolvedCellStyle;
+    cellStyle: StyleDelta;
+    resolved: ResolvedCellStyle;
+};
+export declare function styleToCssText(style: ResolvedCellStyle): string;

package/dist/types.d.ts

@@ -0,0 +1,300 @@
+export type CellPrimitive = string | number | boolean | null;
+export type CellValue = CellPrimitive | Date | {
+    kind: "enum";
+    value: string;
+} | {
+    kind: "tags";
+    values: string[];
+};
+export type ColumnType = "string" | "number" | "boolean" | "datetime" | "date" | "time" | "enum" | "tags";
+export type ResolvedCellStyle = {
+    backgroundColor?: string;
+    textColor?: string;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strike?: boolean;
+};
+export type StyleDelta = Partial<ResolvedCellStyle>;
+export type DiagnosticLevel = "warning" | "error";
+export type CellDiagnostic = {
+    level: DiagnosticLevel;
+    message: string;
+    source: "formula" | "conditionalStyle";
+};
+export type FormulaOk = string | boolean | number | Date;
+export type FormulaWarn<T extends FormulaOk> = readonly [value: T, warning: Error];
+export type FormulaReturn<T extends FormulaOk = FormulaOk> = T | FormulaWarn<T>;
+export type ConditionalStyleFn<TData extends object = object> = (data: TData) => StyleDelta | null | Error;
+export type Updater<T> = T | ((oldValue: T) => T);
+export type CellAddress = {
+    rowId: string;
+    colKey: string;
+} | {
+    rowIndex: number;
+    colIndex: number;
+} | {
+    rowId: string;
+    colIndex: number;
+} | {
+    rowIndex: number;
+    colKey: string;
+};
+export type CellTarget = {
+    rowId: string;
+    colKey: string;
+};
+export interface ColumnSchema<TData extends object = object, RData extends object = TData, TType extends ColumnType = ColumnType, K extends string = string> {
+    key: K;
+    type: TType;
+    header?: string;
+    readonly?: boolean;
+    /**
+     * When true, enforce uniqueness within this column (per table).
+     * Duplicate (non-empty) values mark all duplicated cells as invalid.
+     */
+    unique?: boolean;
+    nullable?: boolean;
+    string?: {
+        maxLength?: number;
+        regex?: string;
+    };
+    number?: {
+        precision?: number;
+        scale?: number;
+        signed?: boolean;
+        thousandSeparator?: boolean;
+        negativeRed?: boolean;
+        format?: string;
+    };
+    enum?: {
+        options: string[];
+        allowCustom?: boolean;
+    };
+    tags?: {
+        options: string[];
+        allowCustom?: boolean;
+    };
+    booleanDisplay?: "checkbox" | string | [string, string];
+    dateFormat?: string;
+    timeFormat?: string;
+    dateTimeFormat?: string;
+    width?: number;
+    wrapText?: boolean;
+    style?: {
+        textColor?: string;
+        backgroundColor?: string;
+        align?: "left" | "right" | "center";
+        decorations?: {
+            strike?: boolean;
+            underline?: boolean;
+            bold?: boolean;
+            italic?: boolean;
+        };
+    };
+    formula?: (data: TData) => unknown;
+    conditionalStyle?: ConditionalStyleFn<RData>;
+}
+export type InferSchemaData<TColumns extends readonly ColumnSchema<any>[]> = {
+    [I in keyof TColumns]: TColumns[I] extends ColumnSchema<infer TData, any, infer TType, infer K> ? K extends keyof TData ? TData[K] : never : never;
+} extends (infer U)[] ? U extends object ? U : Record<string, unknown> : Record<string, unknown>;
+export interface Schema<TData extends object = object, RData extends object = TData> {
+    columns: ColumnSchema<TData, RData>[];
+    row?: {
+        conditionalStyle?: ConditionalStyleFn<RData>;
+    };
+}
+/**
+ * Helper to lock schema generics so `formula`/`conditionalStyle` receive the correct row type.
+ * Usage: `const schema = defineSchema<MyRow>({ columns: [...], row: {...} });`
+ */
+export declare const defineSchema: <TData extends object, RData extends object = TData>(schema: Schema<TData, RData>) => Schema<TData, RData>;
+export type RowObject<T extends object = Record<string, unknown>> = {
+    _readonly?: boolean;
+} & T & Record<string, unknown>;
+export type NullableData<T extends object = object> = T[] | null | undefined;
+export type ViewFilterOp = {
+    kind: "op";
+    key: string;
+    op: "eq" | "neq" | "lt" | "lte" | "gt" | "gte" | "contains";
+    value: unknown;
+};
+export type ViewFilterValues = {
+    kind: "values";
+    key: string;
+    /** Allow-list of selected non-blank values. */
+    values: unknown[];
+    /** When true, blanks (null/undefined/"") are included. */
+    includeBlanks?: boolean;
+};
+export type ViewFilter = ViewFilterOp | ViewFilterValues;
+export type ColumnDiagnosticFilter = {
+    errors?: boolean;
+    warnings?: boolean;
+};
+export type ColumnDiagnosticFilterMap = Record<string, ColumnDiagnosticFilter>;
+export interface ViewSort {
+    key: string;
+    dir: "asc" | "desc";
+}
+export interface View {
+    hiddenColumns?: string[];
+    filters?: ViewFilter[];
+    sorts?: ViewSort[];
+    /**
+     * Column-scoped diagnostic quick filters.
+     * Key is the column key (stringified).
+     */
+    columnDiagnostics?: ColumnDiagnosticFilterMap;
+    userId?: string;
+    columnWidths?: Record<string, number>;
+    rowHeights?: Record<string, number>;
+    wrapText?: Record<string, boolean>;
+}
+export type RenderMode = "html" | "canvas" | "auto";
+export type EditMode = "direct" | "commit" | "readonly";
+export type LockMode = "none" | "row";
+export interface Command {
+    kind: "edit" | "deleteRow" | "insertRow" | "updateView" | "lock" | "unlock";
+    rowId?: string;
+    colKey?: string;
+    rowData?: RowObject;
+    prev?: unknown;
+    next?: unknown;
+    payload?: unknown;
+}
+export interface UserInfo {
+    id: string;
+    name: string;
+}
+export interface ServerAdapter {
+    fetchInitial?: () => Promise<{
+        data: Record<string, unknown>[];
+        view?: View;
+        schema?: Schema;
+        user: UserInfo;
+    }>;
+    lockRow: (rowId: string, user: UserInfo) => Promise<void>;
+    unlockRows: (rowIds: string[], user: UserInfo) => Promise<void>;
+    commit: (commands: Command[], user: UserInfo) => Promise<void>;
+    subscribe: (onEvent: (event: ServerEvent) => void) => () => void;
+}
+export type ServerEvent = {
+    type: "update";
+    commands: Command[];
+    user: UserInfo;
+};
+export interface CoreOptions {
+    renderMode?: RenderMode;
+    editMode?: EditMode;
+    lockMode?: LockMode;
+    /** Loading UI configuration used when `defaultData` is `null`. */
+    loading?: {
+        /** Enable built-in loading overlay/spinner. Default: true */
+        enabled?: boolean;
+    };
+    defaultClass?: string | string[];
+    defaultStyle?: Partial<CSSStyleDeclaration>;
+    server?: ServerAdapter;
+    user?: UserInfo;
+    findReplace?: {
+        /** Enable Find/Replace feature (engine + integrations). Default: true */
+        enabled?: boolean;
+        /**
+         * Enable the default built-in UI and its shortcut bindings. Default: true
+         * Note: legacy name is `dialog`; `sidebar` is the preferred name.
+         */
+        sidebar?: boolean;
+        /** @deprecated Use `sidebar` instead. */
+        dialog?: boolean;
+        /**
+         * When true, always intercept `Ctrl/Cmd+F` and show extable's search sidebar.
+         * Use this when the table is the primary focus of the page and browser Find/Reload should be overridden.
+         * Default: true (always intercept).
+         */
+        enableSearch?: boolean;
+    };
+}
+export interface TableConfig<T extends object = Record<string, unknown>> {
+    data: T[] | null;
+    view: View;
+    schema: Schema;
+}
+export type HistoryCommandKind = Command["kind"];
+export type UndoRedoStep = {
+    batchId: string | null;
+    kinds: HistoryCommandKind[];
+    commandCount: number;
+    label: string;
+};
+export type UndoRedoHistory = {
+    /** Top (index 0) is the next undo step. */
+    undo: UndoRedoStep[];
+    /** Top (index 0) is the next redo step. */
+    redo: UndoRedoStep[];
+};
+export interface InternalRow {
+    id: string;
+    raw: RowObject;
+    displayIndex: number;
+}
+export type SelectionKind = "cells" | "rows";
+export interface SelectionRange {
+    kind: SelectionKind;
+    startRow: number;
+    endRow: number;
+    startCol: number;
+    endCol: number;
+}
+export type ToggleState = "on" | "off" | "mixed" | "disabled";
+export type ColorState = string | "mixed" | null | "disabled";
+export type TableError = {
+    scope: "validation" | "commit" | "render" | "formula" | "conditionalStyle" | "unknown";
+    message: string;
+    target?: {
+        rowId?: string;
+        colKey?: string;
+    };
+};
+export type TableState = {
+    canCommit: boolean;
+    pendingCommandCount: number;
+    pendingCellCount?: number;
+    undoRedo: {
+        canUndo: boolean;
+        canRedo: boolean;
+    };
+    renderMode: "html" | "canvas";
+    ui: {
+        searchPanelOpen: boolean;
+    };
+    activeErrors: TableError[];
+};
+export type TableStateListener = (next: TableState, prev: TableState | null) => void;
+export type RowStateSnapshot<TInput extends object = Record<string, unknown>, TResult extends object = TInput> = {
+    rowId: string;
+    rowIndex: number;
+    data: TResult;
+    pending?: Partial<TInput>;
+    diagnostics?: TableError[];
+};
+export type RowChangeReason = "new" | "edit" | "delete";
+export type RowStateListener<TInput extends object = Record<string, unknown>, TResult extends object = TInput> = (rowId: string, next: RowStateSnapshot<TInput, TResult> | null, prev: RowStateSnapshot<TInput, TResult> | null, reason: RowChangeReason) => void;
+export type SelectionSnapshot = {
+    ranges: SelectionRange[];
+    activeRowIndex: number | null;
+    activeRowKey: string | null;
+    activeColumnIndex: number | null;
+    activeColumnKey: string | null;
+    activeValueRaw: unknown;
+    activeValueDisplay: string;
+    activeValueType: ColumnType | null;
+    diagnostic: CellDiagnostic | null;
+    styles: {
+        columnStyle: Partial<ResolvedCellStyle>;
+        cellStyle: Partial<ResolvedCellStyle>;
+        resolved: Partial<ResolvedCellStyle>;
+    };
+};
+export type SelectionChangeReason = "selection" | "edit" | "style" | "schema" | "view" | "data" | "unknown";
+export type SelectionListener = (next: SelectionSnapshot, prev: SelectionSnapshot | null, reason: SelectionChangeReason) => void;

package/dist/utils.d.ts

@@ -0,0 +1,3 @@
+export declare function generateId(): string;
+export declare function toArray<T>(value: T | T[] | undefined): T[] | undefined;
+export declare function removeFromParent(el: Element | null | undefined): void;

package/dist/validation.d.ts

@@ -0,0 +1,2 @@
+import type { ColumnSchema } from "./types";
+export declare function validateCellValue(value: unknown, col: ColumnSchema): string | null;

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@extable/core",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./style.css": "./dist/index.css",
+    "./index.css": "./dist/index.css"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": [
+    "./dist/index.css"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json --emitDeclarationOnly && vite build",
+    "test": "vitest run",
+    "lint": "biome lint .",
+    "format": "biome format --write ."
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shibukawa/extable.git"
+  },
+  "author": "Yoshiki Shibukawa",
+  "license": "Apache-2.0",
+  "peerDependencies": {}
+}