tabulark 0.0.4 → 0.1.0

package/dist/view/canvas-table-view-public.d.ts

@@ -0,0 +1,58 @@
+import type { TableHandle } from "../client.js";
+/** Stable, high-level sizing and cache controls for the Canvas table view. */
+export interface CanvasTableViewControllerOptions {
+    readonly rowHeight?: number;
+    readonly headerHeight?: number;
+    readonly rowHeaderWidth?: number;
+    readonly columnWidth?: number;
+    readonly minColumnWidth?: number;
+    readonly maxColumnWidth?: number;
+    readonly columnWidths?: Readonly<Record<string, number>>;
+    readonly scrollPixelLimit?: number;
+    readonly overscanRows?: number;
+    readonly overscanColumns?: number;
+    /** Hard bound for decoded render/cache cells. */
+    readonly maxWindowCells?: number;
+}
+/** Stable theme tokens accepted by the high-level Canvas table view. */
+export interface CanvasTableViewTheme {
+    readonly background: string;
+    readonly foreground: string;
+    readonly mutedForeground: string;
+    readonly headerBackground: string;
+    readonly headerForeground: string;
+    readonly alternateRowBackground: string;
+    readonly gridLine: string;
+    readonly selectionBackground: string;
+    readonly selectionBorder: string;
+    readonly activeCellBorder: string;
+    readonly loadingBackground: string;
+    readonly font: string;
+    readonly headerFont: string;
+}
+/** Stable options for mounting a Canvas preview from a logical table handle. */
+export interface CanvasTableViewOptions {
+    readonly container: HTMLElement;
+    readonly table: TableHandle;
+    readonly controllerOptions?: CanvasTableViewControllerOptions;
+    /**
+     * Applies static spreadsheet presentation metadata when available.
+     * Workbook colors never override the system palette in forced-colors mode.
+     */
+    readonly presentation?: "auto" | "ignore";
+    readonly ariaLabel?: string;
+    readonly theme?: Partial<CanvasTableViewTheme>;
+    readonly maxDevicePixelRatio?: number;
+    /** Testable clipboard seam; navigator.clipboard.writeText is used by default. */
+    readonly writeClipboard?: (text: string) => Promise<void> | void;
+    readonly onError?: (error: unknown) => void;
+}
+/** Stable lifecycle surface for a mounted Canvas table view. */
+export interface CanvasTableView {
+    readonly element: HTMLDivElement;
+    focus(options?: FocusOptions): void;
+    destroy(): void;
+    dispose(): void;
+}
+/** Mounts an accessible, viewport-driven Canvas preview. */
+export declare function createCanvasTableView(options: CanvasTableViewOptions): CanvasTableView;

package/dist/view/canvas-table-view.d.ts

@@ -0,0 +1,32 @@
+import type { TableHandle } from "../client.js";
+import { type CanvasTableTheme } from "./canvas-painter.js";
+import { type TableViewController } from "./controller.js";
+import type { TableControllerOptions } from "./types.js";
+export interface CanvasTableViewOptions {
+    readonly container: HTMLElement;
+    /** Provide either a table or a preconfigured controller, never both. */
+    readonly table?: TableHandle;
+    /** Provide either a controller or a table, never both. */
+    readonly controller?: TableViewController;
+    readonly controllerOptions?: TableControllerOptions;
+    /**
+     * Applies static spreadsheet sizing metadata when a TableHandle provides it.
+     * Workbook colors never override the system palette in forced-colors mode.
+     */
+    readonly presentation?: "auto" | "ignore";
+    readonly ariaLabel?: string;
+    readonly theme?: Partial<CanvasTableTheme>;
+    readonly maxDevicePixelRatio?: number;
+    /** Testable clipboard seam; navigator.clipboard.writeText is used by default. */
+    readonly writeClipboard?: (text: string) => Promise<void> | void;
+    readonly onError?: (error: unknown) => void;
+}
+export interface CanvasTableView {
+    readonly element: HTMLDivElement;
+    readonly controller: TableViewController;
+    focus(options?: FocusOptions): void;
+    destroy(): void;
+    dispose(): void;
+}
+/** Mounts an accessible, viewport-driven Canvas preview. */
+export declare function createCanvasTableView(options: CanvasTableViewOptions): CanvasTableView;

package/dist/view/controller.d.ts

@@ -0,0 +1,34 @@
+import type { TableHandle, Unsubscribe } from "../client.js";
+import { type MergedCellRegion, type SpreadsheetPresentation } from "../model.js";
+import { type CellLoadState, type CellPosition, type HitTestResult, type MoveActiveCellOptions, type NavigationCommand, type PixelRect, type SetActiveCellOptions, type TableControllerOptions, type TableSelection, type TableViewSnapshot, type ViewportUpdate } from "./types.js";
+export interface TableViewController {
+    readonly metadata: TableHandle["metadata"];
+    readonly columnWidths: readonly number[];
+    readonly minColumnWidth: number;
+    readonly maxColumnWidth: number;
+    getSnapshot(): Readonly<TableViewSnapshot>;
+    subscribe(listener: (snapshot: Readonly<TableViewSnapshot>) => void): Unsubscribe;
+    updateViewport(viewport: ViewportUpdate): void;
+    setActiveCell(cell: CellPosition, options?: SetActiveCellOptions): void;
+    extendSelection(cell: CellPosition, options?: Omit<SetActiveCellOptions, "extendSelection">): void;
+    setSelection(anchor: CellPosition, focus?: CellPosition): void;
+    clearSelection(): void;
+    moveActive(command: NavigationCommand, options?: MoveActiveCellOptions): void;
+    ensureCellVisible(cell: CellPosition): void;
+    ensureColumnVisible(columnIndex: number): void;
+    resizeColumn(columnIndex: number, width: number): void;
+    autosizeColumn(columnIndex: number, measuredWidth: number): void;
+    /** Applies validated static worksheet geometry in one controller generation. */
+    applySpreadsheetPresentation(presentation: SpreadsheetPresentation): void;
+    /** Updates merge interaction geometry for the currently loaded presentation window. */
+    setMergedCells(regions: readonly MergedCellRegion[]): void;
+    hitTest(x: number, y: number, resizeHandleWidth?: number): HitTestResult;
+    cellRect(cell: CellPosition): Readonly<PixelRect>;
+    selectionRect(selection?: TableSelection | null): Readonly<PixelRect> | null;
+    getCell(rowIndex: number, columnIndex: number): CellLoadState;
+    copySelection(options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<string>;
+    dispose(): void;
+}
+export declare function createTableController(table: TableHandle, options?: TableControllerOptions): TableViewController;

package/dist/view/layout.d.ts

@@ -0,0 +1,34 @@
+import type { PresentationAxisEntry, TableMetadata } from "../model.js";
+import { type GridRange, type HitTestResult, type PixelRect, type ScrollAxisLayout, type SparseAxisGeometry, type TableLayout, type ViewportUpdate } from "./types.js";
+export interface LayoutOptions {
+    readonly rowHeight?: number;
+    readonly headerHeight?: number;
+    readonly rowHeaderWidth?: number;
+    readonly scrollPixelLimit?: number;
+    readonly overscanRows?: number;
+    readonly overscanColumns?: number;
+    readonly rowEntries?: readonly PresentationAxisEntry[];
+    readonly hiddenColumns?: readonly boolean[];
+    readonly frozenRows?: number;
+    readonly frozenColumns?: number;
+}
+export declare function createTableLayout(metadata: Readonly<TableMetadata>, columnWidths: readonly number[], viewport: ViewportUpdate, options?: LayoutOptions): Readonly<TableLayout>;
+export declare function createScrollAxis(logicalContentSize: number, logicalViewportSize: number, physicalOffset: number, pixelLimit?: number): Readonly<ScrollAxisLayout>;
+export declare function logicalToPhysicalOffset(axis: ScrollAxisLayout, logicalOffset: number): number;
+export declare function physicalToLogicalOffset(axis: ScrollAxisLayout, physicalOffset: number): number;
+export declare function hitTest(layout: TableLayout, x: number, y: number, _columnWidths: readonly number[], resizeHandleWidth?: number): HitTestResult;
+export declare function cellRect(layout: TableLayout, _columnWidths: readonly number[], rowIndex: number, columnIndex: number): Readonly<PixelRect>;
+export declare function columnHeaderRect(layout: TableLayout, _columnWidths: readonly number[], columnIndex: number): Readonly<PixelRect>;
+export declare function rowHeaderRect(layout: TableLayout, rowIndex: number): Readonly<PixelRect>;
+export declare function selectionRect(layout: TableLayout, _columnWidths: readonly number[], range: GridRange): Readonly<PixelRect> | null;
+export declare function columnOffsets(columnWidths: readonly number[]): readonly number[];
+export declare function extentValue(extent: TableMetadata["extent"]["rows"]): number;
+/** Builds a compact sparse axis without allocating one entry per worksheet row. */
+export declare function createSparseAxisGeometry(count: number, defaultSize: number, entries?: readonly PresentationAxisEntry[]): Readonly<SparseAxisGeometry>;
+/** Logical offset at the start of an axis index. */
+export declare function axisPosition(geometry: SparseAxisGeometry, index: number): number;
+/** Effective axis extent, zero when a row/column is hidden. */
+export declare function axisSize(geometry: SparseAxisGeometry, index: number): number;
+/** Finds the visible axis index containing a logical pixel offset. */
+export declare function axisIndexAtOffset(geometry: SparseAxisGeometry, offset: number): number | null;
+export declare function nextVisibleAxisIndex(geometry: SparseAxisGeometry, from: number, direction?: -1 | 1): number | null;

package/dist/view/selection.d.ts

@@ -0,0 +1,7 @@
+import type { CellPosition, GridRange, NavigationCommand, TableSelection } from "./types.js";
+export declare function createSelection(anchor: CellPosition, focus?: CellPosition): Readonly<TableSelection>;
+export declare function selectionRange(anchor: CellPosition, focus: CellPosition): Readonly<GridRange>;
+export declare function containsCell(range: GridRange, cell: CellPosition): boolean;
+export declare function clampCell(cell: CellPosition, rowCount: number, columnCount: number): Readonly<CellPosition> | null;
+export declare function moveCell(cell: CellPosition, command: NavigationCommand, rowCount: number, columnCount: number, pageRowCount: number): Readonly<CellPosition> | null;
+export declare function assertCellPosition(value: CellPosition, name: string): void;

package/dist/view/types.d.ts

@@ -0,0 +1,184 @@
+import type { TableMetadata } from "../model.js";
+export declare const DEFAULT_ROW_HEIGHT = 28;
+export declare const DEFAULT_HEADER_HEIGHT = 36;
+export declare const DEFAULT_ROW_HEADER_WIDTH = 64;
+export declare const DEFAULT_COLUMN_WIDTH = 160;
+export declare const DEFAULT_MIN_COLUMN_WIDTH = 64;
+export declare const DEFAULT_MAX_COLUMN_WIDTH = 640;
+export declare const DEFAULT_SCROLL_PIXEL_LIMIT = 16000000;
+export declare const DEFAULT_OVERSCAN_ROWS = 8;
+export declare const DEFAULT_OVERSCAN_COLUMNS = 1;
+/** A zero-based table coordinate. */
+export interface CellPosition {
+    readonly rowIndex: number;
+    readonly columnIndex: number;
+}
+/** A zero-based, half-open rectangular table range. */
+export interface GridRange {
+    readonly rowStart: number;
+    readonly rowEnd: number;
+    readonly columnStart: number;
+    readonly columnEnd: number;
+}
+export interface TableSelection {
+    readonly anchor: Readonly<CellPosition>;
+    readonly focus: Readonly<CellPosition>;
+    readonly range: Readonly<GridRange>;
+}
+export interface PixelRect {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+export interface IndexRange {
+    readonly start: number;
+    readonly end: number;
+}
+export interface ScrollAxisLayout {
+    readonly logicalContentSize: number;
+    readonly logicalViewportSize: number;
+    readonly logicalOffset: number;
+    readonly logicalMaxOffset: number;
+    readonly physicalContentSize: number;
+    readonly physicalOffset: number;
+    readonly physicalMaxOffset: number;
+    readonly compressed: boolean;
+}
+export interface VisibleColumn {
+    readonly index: number;
+    readonly id: string;
+    readonly name: string;
+    /** Viewport-relative left edge in CSS pixels. */
+    readonly x: number;
+    readonly width: number;
+    /** True when the column is pinned at the workbook's frozen boundary. */
+    readonly frozen: boolean;
+}
+export interface VisibleRow {
+    readonly index: number;
+    /** Viewport-relative top edge in CSS pixels. */
+    readonly y: number;
+    readonly height: number;
+    /** True when the row is pinned at the workbook's frozen boundary. */
+    readonly frozen: boolean;
+}
+export interface SparseAxisOverride {
+    readonly index: number;
+    readonly size: number;
+    /** Cumulative size delta through and including this override. */
+    readonly cumulativeDelta: number;
+}
+/** Compact geometry for a potentially million-row spreadsheet axis. */
+export interface SparseAxisGeometry {
+    readonly count: number;
+    readonly defaultSize: number;
+    readonly contentSize: number;
+    readonly overrides: readonly Readonly<SparseAxisOverride>[];
+}
+export interface TableLayout {
+    readonly width: number;
+    readonly height: number;
+    readonly devicePixelRatio: number;
+    readonly rowHeight: number;
+    readonly headerHeight: number;
+    readonly rowHeaderWidth: number;
+    readonly bodyWidth: number;
+    readonly bodyHeight: number;
+    readonly rowCount: number;
+    readonly columnCount: number;
+    readonly rows: Readonly<{
+        readonly visible: Readonly<IndexRange>;
+        readonly overscan: Readonly<IndexRange>;
+    }>;
+    readonly columns: Readonly<{
+        readonly visible: Readonly<IndexRange>;
+        readonly overscan: Readonly<IndexRange>;
+    }>;
+    readonly visibleColumns: readonly Readonly<VisibleColumn>[];
+    readonly overscanColumns: readonly Readonly<VisibleColumn>[];
+    readonly visibleRows: readonly Readonly<VisibleRow>[];
+    readonly overscanRows: readonly Readonly<VisibleRow>[];
+    /** Effective widths use zero for workbook-hidden columns. */
+    readonly effectiveColumnWidths: readonly number[];
+    readonly rowGeometry: Readonly<SparseAxisGeometry>;
+    readonly frozenRowCount: number;
+    readonly frozenColumnCount: number;
+    readonly frozenRowExtent: number;
+    readonly frozenColumnExtent: number;
+    /** Frozen segments are loaded separately when the scroll window is distant. */
+    readonly frozenRowRange: Readonly<IndexRange>;
+    readonly frozenColumnRange: Readonly<IndexRange>;
+    readonly horizontal: Readonly<ScrollAxisLayout>;
+    readonly vertical: Readonly<ScrollAxisLayout>;
+    /** Spacer dimensions for a native scroll host, including sticky headers. */
+    readonly spacerWidth: number;
+    readonly spacerHeight: number;
+}
+export type HitTestResult = Readonly<{
+    kind: "outside";
+}> | Readonly<{
+    kind: "corner";
+}> | Readonly<{
+    kind: "column-header";
+    columnIndex: number;
+}> | Readonly<{
+    kind: "column-resize";
+    columnIndex: number;
+    boundaryX: number;
+}> | Readonly<{
+    kind: "row-header";
+    rowIndex: number;
+}> | Readonly<{
+    kind: "cell";
+    rowIndex: number;
+    columnIndex: number;
+}>;
+export type CellLoadState = Readonly<{
+    status: "loading";
+}> | Readonly<{
+    status: "unavailable";
+}> | Readonly<{
+    status: "loaded";
+    value: string | null;
+}>;
+export type TableViewStatus = "loading" | "ready" | "error" | "closed";
+export interface TableViewSnapshot {
+    readonly generation: number;
+    readonly status: TableViewStatus;
+    readonly metadata: Readonly<TableMetadata>;
+    readonly layout: Readonly<TableLayout>;
+    readonly activeCell: Readonly<CellPosition> | null;
+    readonly selection: Readonly<TableSelection> | null;
+    readonly error?: unknown;
+}
+export interface ViewportUpdate {
+    readonly width: number;
+    readonly height: number;
+    /** Native scroll-host offset in CSS pixels. */
+    readonly scrollLeft: number;
+    /** Native scroll-host offset in CSS pixels. */
+    readonly scrollTop: number;
+    readonly devicePixelRatio?: number;
+}
+export interface TableControllerOptions {
+    readonly rowHeight?: number;
+    readonly headerHeight?: number;
+    readonly rowHeaderWidth?: number;
+    readonly columnWidth?: number;
+    readonly minColumnWidth?: number;
+    readonly maxColumnWidth?: number;
+    readonly columnWidths?: Readonly<Record<string, number>>;
+    readonly scrollPixelLimit?: number;
+    readonly overscanRows?: number;
+    readonly overscanColumns?: number;
+    /** Hard bound for decoded render/cache cells. */
+    readonly maxWindowCells?: number;
+}
+export type NavigationCommand = "left" | "right" | "up" | "down" | "page-up" | "page-down" | "row-start" | "row-end" | "table-start" | "table-end";
+export interface SetActiveCellOptions {
+    readonly extendSelection?: boolean;
+    readonly scrollIntoView?: boolean;
+}
+export interface MoveActiveCellOptions extends SetActiveCellOptions {
+}

package/dist/wasm/arrow/tabulark_arrow.d.ts

@@ -0,0 +1,126 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * Dedicated Arrow IPC runtime artifact implementing adapter ABI v2.
+ */
+export class WasmRuntime {
+  free(): void;
+  /**
+   * Returns the frozen official adapter ID.
+   */
+  adapterId(): string;
+  /**
+   * Begins an open without copying the full source into WebAssembly.
+   *
+   * IPC Files request only their trailer, footer, and record metadata here.
+   * IPC Streams request bounded sequential chunks.
+   */
+  beginOpen(options: any, source_length: number): any;
+  /**
+   * Starts a range read. Streams complete from retained decoded batches;
+   * Files request only dictionaries and intersecting record blocks.
+   */
+  beginRead(table_handle: number, request: any): any;
+  /**
+   * Opens the source's single logical table.
+   */
+  openTable(source_handle: number, table_id: string): any;
+  /**
+   * Idempotently closes one table and its in-flight reads.
+   */
+  closeTable(table_handle: number): boolean;
+  /**
+   * Idempotently closes one source, its tables, and all child reads.
+   */
+  closeSource(source_handle: number): boolean;
+  /**
+   * Returns no static presentation for Arrow IPC tables.
+   */
+  presentation(table_handle: number): any;
+  /**
+   * Cancels and releases a pending adapter operation.
+   */
+  cancelOperation(operation_handle: number): boolean;
+  /**
+   * Returns the Worker protocol version.
+   */
+  protocolVersion(): number;
+  /**
+   * Supplies exactly one requested source byte range and advances an open
+   * or File range-read operation.
+   */
+  continueOperation(operation_handle: number, absolute_offset: number, bytes: Uint8Array, eof: boolean): any;
+  /**
+   * Returns the official adapter ABI version.
+   */
+  adapterApiVersion(): number;
+  /**
+   * Returns typed-buffer layout version one.
+   */
+  batchLayoutVersion(): number;
+  /**
+   * Returns no range presentation for Arrow IPC tables.
+   */
+  readPresentationRange(table_handle: number, request: any): any;
+  /**
+   * Creates an empty Arrow adapter runtime.
+   */
+  constructor(config: any);
+  /**
+   * Returns the latest table metadata.
+   */
+  metadata(table_handle: number): any;
+  /**
+   * Releases all operations, tables, and sources.
+   */
+  shutdown(): void;
+}
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+  readonly memory: WebAssembly.Memory;
+  readonly __wbg_wasmruntime_free: (a: number, b: number) => void;
+  readonly wasmruntime_adapterApiVersion: (a: number) => number;
+  readonly wasmruntime_adapterId: (a: number, b: number) => void;
+  readonly wasmruntime_batchLayoutVersion: (a: number) => number;
+  readonly wasmruntime_beginOpen: (a: number, b: number, c: number, d: number) => void;
+  readonly wasmruntime_beginRead: (a: number, b: number, c: number, d: number) => void;
+  readonly wasmruntime_cancelOperation: (a: number, b: number) => number;
+  readonly wasmruntime_closeSource: (a: number, b: number) => number;
+  readonly wasmruntime_closeTable: (a: number, b: number) => number;
+  readonly wasmruntime_continueOperation: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+  readonly wasmruntime_metadata: (a: number, b: number, c: number) => void;
+  readonly wasmruntime_new: (a: number, b: number) => void;
+  readonly wasmruntime_openTable: (a: number, b: number, c: number, d: number, e: number) => void;
+  readonly wasmruntime_presentation: (a: number, b: number, c: number) => void;
+  readonly wasmruntime_protocolVersion: (a: number) => number;
+  readonly wasmruntime_readPresentationRange: (a: number, b: number, c: number, d: number) => void;
+  readonly wasmruntime_shutdown: (a: number) => void;
+  readonly __wbindgen_export_0: (a: number, b: number) => number;
+  readonly __wbindgen_export_1: (a: number, b: number, c: number, d: number) => number;
+  readonly __wbindgen_export_2: (a: number) => void;
+  readonly __wbindgen_add_to_stack_pointer: (a: number) => number;
+  readonly __wbindgen_export_3: (a: number, b: number, c: number) => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+/**
+* Instantiates the given `module`, which can either be bytes or
+* a precompiled `WebAssembly.Module`.
+*
+* @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+*
+* @returns {InitOutput}
+*/
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+* If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+* for everything else, calls `WebAssembly.instantiate` directly.
+*
+* @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+*
+* @returns {Promise<InitOutput>}
+*/
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;