@bendyline/squisq-grid-react 2.11.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bendyline LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE.md

@@ -0,0 +1,16 @@
+# Third-Party Notices for @bendyline/squisq-grid-react
+
+This notice applies to the `@bendyline/squisq-grid-react` npm package.
+Squisq-authored code is licensed under the MIT license in `LICENSE`.
+Third-party components remain under their respective license terms.
+
+## Runtime and peer dependencies
+
+| Package                 | Version              | License | Repository                          |
+| ----------------------- | -------------------- | ------- | ----------------------------------- |
+| @tanstack/react-virtual | 3.14.10              | MIT     | https://github.com/TanStack/virtual |
+| react _(peer)_          | ^18.0.0 \|\| ^19.0.0 | MIT     | https://github.com/facebook/react   |
+| react-dom _(peer)_      | ^18.0.0 \|\| ^19.0.0 | MIT     | https://github.com/facebook/react   |
+
+Copyright and complete license texts for these dependencies are included in
+their respective npm distributions and source repositories.

package/README.md

@@ -0,0 +1,23 @@
+# @bendyline/squisq-grid-react
+
+Virtualized data grid for squisq data sidecars: an in-house columnar store
+behind a Web Worker (`TableStoreClient`, implementing core's
+`TableQueryProvider`), plus a TanStack-Virtual React renderer (`DataGrid`)
+with spreadsheet-style sort/filter/selection/clipboard and journaled cell
+editing.
+
+The Tiptap mount lives in `@bendyline/squisq-editor-react` (the data-card
+widget lazy-imports this package); the grid itself has no editor
+dependencies and works in any React 18/19 host.
+
+```tsx
+import { DataGrid, TableStoreClient, EditJournal } from '@bendyline/squisq-grid-react';
+import '@bendyline/squisq-grid-react/styles';
+
+const provider = new TableStoreClient({ headers, cells });
+<DataGrid provider={provider} journal={new EditJournal()} view={{ sort: [], filter: [] }} />;
+```
+
+Theming: every color resolves through `--squisq-grid-*` CSS custom
+properties with literal fallbacks; hosts re-bind them to their own palette
+(editor-react aliases them onto its chrome tokens).

package/THIRD_PARTY_LICENSES.txt

@@ -0,0 +1,8 @@
+THIRD-PARTY LICENSES FOR @bendyline/squisq-grid-react
+
+Generated from the actual esbuild input graph. Package-local license, copying,
+and notice files are reproduced verbatim. When an npm tarball omits its
+repository license, the pinned upstream copy is vendored and identified below.
+
+COMPONENTS
+

package/dist/index.d.ts

@@ -0,0 +1,376 @@
+import { TableCellValue, TableColumnKind, TableQueryProvider, TableSchema, TableViewState, TableViewResult, TableRowsPage, TableCellEdit, TableEditResult, TableDistinctResult } from '@bendyline/squisq/table';
+import { ReactElement } from 'react';
+
+/**
+ * Columnar ingestion: a format-neutral cell grid → typed columns the worker
+ * kernel operates on. grid-react never parses files itself — the editor
+ * adapter feeds an `IngestTable` built from the lazy formats readers (CSV
+ * strings with a typing pass; XLSX typed `XlsxCell.value`s).
+ *
+ * Layout per column kind:
+ *  - `number`  → `Float64Array data` + `Uint8Array valid` (an explicit blank
+ *    mask — NaN-as-sentinel is rejected because a coercion bug could
+ *    legitimately produce NaN, and masks make blank semantics testable)
+ *  - `string`/`date` → DICTIONARY-encoded: `Int32Array codes` (−1 = blank) +
+ *    `string[] dict`. Chosen because (1) the code array is transferable, so
+ *    the bulk of the bytes move to the worker rather than being cloned;
+ *    (2) locale-aware sort is one `rank` array over unique values instead of
+ *    per-row collation; (3) `contains` lowercasing happens once per dict
+ *    entry. High-cardinality columns degrade gracefully (dict length = row
+ *    count — no worse than `string[]`).
+ *  - `boolean` → `Uint8Array data` + `Uint8Array valid`
+ *
+ * Column typing follows the SHARED rule in `@bendyline/squisq/table`
+ * (`isNumericCellText`: all non-blank cells numeric, no leading-zero
+ * strings) so kernel results stay parity-testable against
+ * `applyTableViewState`.
+ */
+
+/** A format-neutral cell: `null` = blank. */
+type IngestCell = TableCellValue;
+interface IngestColumnHint {
+    /** Force a column kind (XLSX adapters know; CSV lets inference decide). */
+    kind?: TableColumnKind;
+}
+interface IngestTable {
+    headers: string[];
+    /** Row-major cells; ragged rows are padded with blanks. */
+    cells: IngestCell[][];
+    /** Optional per-column hints, index-aligned with `headers`. */
+    hints?: (IngestColumnHint | undefined)[];
+}
+interface NumberColumn {
+    kind: 'number';
+    name: string;
+    data: Float64Array;
+    valid: Uint8Array;
+}
+interface DictColumn {
+    kind: 'string' | 'date';
+    name: string;
+    /** Dictionary code per row; −1 = blank. */
+    codes: Int32Array;
+    dict: string[];
+}
+interface BooleanColumn {
+    kind: 'boolean';
+    name: string;
+    data: Uint8Array;
+    valid: Uint8Array;
+}
+type StoreColumn = NumberColumn | DictColumn | BooleanColumn;
+interface ColumnarTable {
+    columns: StoreColumn[];
+    rowCount: number;
+}
+/** Build typed columns from a neutral cell grid. */
+declare function buildColumnarTable(table: IngestTable): ColumnarTable;
+/** Read one cell back out of typed columns (`null` = blank). */
+declare function columnCellValue(column: StoreColumn, row: number): TableCellValue;
+
+/**
+ * The table kernel — sort/filter/window/edit over transferred typed columns.
+ *
+ * SHIPPING CONSTRAINT: this function's SOURCE is the worker. It is embedded
+ * via `tableKernel.toString()` into a Blob URL (`buildKernelSource`), the
+ * same zero-asset pattern as the teleprompter's PCM worklet — editor
+ * packages ship no runtime asset files, and URL-based workers would force
+ * bundler configuration onto every host. Therefore:
+ *
+ *  - the function must reference NOTHING from module scope (all helpers are
+ *    nested; only web-worker globals like `Intl` are used);
+ *  - tsup must never minify this package (mangled `toString()` output);
+ *    both properties are pinned by tests in `kernel.test.ts`.
+ *
+ * Semantics mirror `applyTableViewState` in `@bendyline/squisq/table`
+ * (numeric compare on number columns, collator-ranked dictionary compare on
+ * text, blanks last regardless of direction, stable sort with source-index
+ * tie-break, filter-then-sort) — parity is a tested property, not an
+ * aspiration. Type/collation rules are COPIED here by necessity (zero
+ * imports); the parity suite is what keeps the copies honest.
+ *
+ * Edits mutate columns in place and NEVER re-permute: a row teleporting out
+ * from under the caret mid-entry is hostile. `applyEdits` reports
+ * `staleView` when an edited cell touched an active sort/filter column so
+ * the UI can offer an explicit refresh.
+ */
+interface KernelColumnPayload {
+    name: string;
+    kind: 'number' | 'string' | 'date' | 'boolean';
+    /** number/boolean: values; string/date: dictionary codes (−1 = blank). */
+    data: Float64Array | Int32Array | Uint8Array;
+    valid?: Uint8Array;
+    dict?: string[];
+}
+interface KernelSortTerm {
+    col: number;
+    dir: 'asc' | 'desc';
+}
+interface KernelFilterClause {
+    col: number;
+    op: '=' | '!=' | '>' | '<' | '>=' | '<=' | '~' | '!~' | '^~' | '$~';
+    value: string;
+    /** Case-sensitive text matching (the grammar's `*` modifier). */
+    caseSensitive?: boolean;
+}
+interface KernelCellEdit {
+    rowId: number;
+    col: number;
+    value: number | string | boolean | null;
+}
+type KernelRequest = {
+    type: 'init';
+    seq: number;
+    columns: KernelColumnPayload[];
+    rowCount: number;
+} | {
+    type: 'setView';
+    seq: number;
+    sort: KernelSortTerm[];
+    filter: KernelFilterClause[];
+} | {
+    type: 'rows';
+    seq: number;
+    start: number;
+    count: number;
+} | {
+    type: 'applyEdits';
+    seq: number;
+    edits: KernelCellEdit[];
+} | {
+    type: 'distinct';
+    seq: number;
+    col: number;
+    limit: number;
+} | {
+    type: 'dispose';
+};
+type KernelCell = number | string | boolean | null;
+type KernelResponse = {
+    type: 'ready';
+    seq: number;
+} | {
+    type: 'viewResult';
+    seq: number;
+    viewRowCount: number;
+} | {
+    type: 'rowsResult';
+    seq: number;
+    start: number;
+    rowIds: number[];
+    cells: KernelCell[][];
+} | {
+    type: 'editResult';
+    seq: number;
+    staleView: boolean;
+} | {
+    type: 'distinctResult';
+    seq: number;
+    values: string[];
+    totalDistinct: number;
+    hasBlank: boolean;
+} | {
+    type: 'error';
+    seq: number;
+    message: string;
+};
+/** The structural slice of a worker global scope the kernel needs. */
+interface KernelScope {
+    onmessage: ((event: {
+        data: KernelRequest;
+    }) => void) | null;
+    postMessage(message: KernelResponse): void;
+}
+declare function tableKernel(scope: KernelScope): void;
+/** The worker source: the kernel applied to the worker's own global scope. */
+declare function buildKernelSource(): string;
+
+/**
+ * TableStoreClient — the in-house columnar store behind the
+ * `TableQueryProvider` contract. Compute (filter/sort/window/edit) runs in
+ * the kernel; the kernel runs in a Blob-URL Web Worker when available and
+ * falls back to an in-process host otherwise (SSR, tests — the fallback is
+ * also the protocol-parity proof, since both paths execute the SAME
+ * `tableKernel` source).
+ *
+ * Transfer note: typed-array halves of the columns are TRANSFERRED to the
+ * worker (zero-copy); dictionaries are structured-cloned. After `init` the
+ * client's own column buffers are detached — the client keeps only the
+ * schema; the ingest source stays with the adapter (it owns save).
+ */
+
+interface KernelHost {
+    post(message: KernelRequest, transfer?: Transferable[]): void;
+    onResponse: (message: KernelResponse) => void;
+    terminate(): void;
+}
+/** In-process host: drives `tableKernel` directly (SSR/tests/parity). */
+declare class LocalKernelHost implements KernelHost {
+    onResponse: (message: KernelResponse) => void;
+    private readonly scope;
+    constructor();
+    post(message: KernelRequest): void;
+    terminate(): void;
+}
+interface TableStoreClientOptions {
+    /** Force the in-process host (tests, SSR probes). */
+    forceLocal?: boolean;
+}
+declare class TableStoreClient implements TableQueryProvider {
+    private readonly host;
+    private readonly schema;
+    private seq;
+    private viewRowCount;
+    private readonly pending;
+    private ready;
+    constructor(table: IngestTable, options?: TableStoreClientOptions);
+    private request;
+    describe(): Promise<TableSchema>;
+    setView(view: TableViewState): Promise<TableViewResult>;
+    rows(start: number, count: number): Promise<TableRowsPage>;
+    applyEdits(edits: TableCellEdit[]): Promise<TableEditResult>;
+    distinct(col: number, limit: number): Promise<TableDistinctResult>;
+    /** Row count under the current view (post-filter). */
+    get currentViewRowCount(): number;
+    dispose(): void;
+}
+
+/**
+ * EditJournal — unsaved cell edits, keyed by immutable source row id.
+ *
+ * Lives on the MAIN thread beside the store client. Row identity is the
+ * source row index assigned at ingest, so an entry is unambiguous under any
+ * sort/filter permutation and unaffected by edits changing sort keys —
+ * identity was never derived from values.
+ *
+ * Batches are the undo unit (one commit = one batch). The journal is
+ * additionally cached module-level by `(cacheKey)` — conventionally
+ * `${path}@${mediaRevision}` — so a widget unmount/remount (ProseMirror
+ * re-decoration) does not lose unsaved edits; a revision bump (save or
+ * re-upload) naturally misses the cache and starts clean.
+ */
+
+interface JournalEntry {
+    rowId: number;
+    col: number;
+    prev: TableCellValue;
+    next: TableCellValue;
+}
+declare class EditJournal {
+    /** Latest value per cell, keyed `rowId:col`. */
+    private readonly latest;
+    private readonly undoStack;
+    private readonly redoStack;
+    get dirtyCount(): number;
+    get canUndo(): boolean;
+    get canRedo(): boolean;
+    isDirty(rowId: number, col: number): boolean;
+    /** Record one committed batch of edits. Clears the redo stack. */
+    commit(entries: JournalEntry[]): void;
+    /** Pop the latest batch; returns the INVERSE edits to apply to the store. */
+    undo(): TableCellEdit[];
+    /** Re-apply the most recently undone batch. */
+    redo(): TableCellEdit[];
+    /** Net outstanding edits (what a Save must persist). */
+    entries(): JournalEntry[];
+    clear(): void;
+    private applyLatest;
+    private rebuildLatest;
+}
+/**
+ * Get (or create) the journal for a cache key. Any entry for the same path
+ * at a DIFFERENT revision is discarded — a revision bump means the bytes
+ * changed underneath the edits.
+ */
+declare function journalFor(path: string, revision: number): EditJournal;
+declare function discardJournal(path: string): void;
+
+/**
+ * DataGrid — the virtualized grid over a `TableQueryProvider`.
+ *
+ * Rendering model: TanStack Virtual drives ROW virtualization only (at the
+ * ~20-column design target, column virtualization buys nothing and costs
+ * sticky-header/selection complexity); columns are a CSS grid template from
+ * the width map. The grid owns a bounded scroll container
+ * (`overscroll-behavior: contain`) — it never scrolls the document.
+ *
+ * Interaction contract (kept in sync with the plan spec):
+ *  - selection: rectangular `{anchor, focus}` in view coordinates; roving
+ *    tabIndex on the focused cell (real focus — the cell editor needs it);
+ *  - keyboard: arrows move, Shift extends, Ctrl/Cmd jumps to data edges,
+ *    PageUp/Down by viewport, Home/End row-wise, Ctrl/Cmd+Home/End
+ *    grid-wise, Enter commits+moves down, Tab commits+moves right, F2 or
+ *    typing opens the editor, Escape cancels, Ctrl/Cmd+A selects all,
+ *    Ctrl/Cmd+Z / +Shift+Z drive the edit journal;
+ *  - clipboard: `copy` writes TSV (`text/plain`) + `<table>` (`text/html`)
+ *    from the selection prefetch cache (capped; truncation is announced);
+ *  - edits: committed per cell through `provider.applyEdits` + the journal;
+ *    the view is NEVER auto re-sorted after an edit — `staleView` drives an
+ *    explicit refresh affordance instead;
+ *  - sort headers cycle asc → desc → none; Shift+click appends a term.
+ *
+ * Theming: every color resolves through `--squisq-grid-*` tokens with
+ * literal fallbacks (see styles/grid.css) so the grid works standalone;
+ * editor-react aliases the tokens onto its chrome palette.
+ */
+
+interface DataGridProps {
+    provider: TableQueryProvider;
+    /** Present = editable; the journal records batches for undo + save. */
+    journal?: EditJournal;
+    view: TableViewState;
+    onViewChange?: (view: TableViewState) => void;
+    /** False = view state is session-only ("not saved to document" hint). */
+    viewPersisted?: boolean;
+    onSave?: () => void | Promise<void>;
+    saving?: boolean;
+    height?: number;
+    /** Reason editing is unavailable (e.g. parquet sidecars). */
+    readOnlyReason?: string;
+    /**
+     * Per-cell lock predicate (source row id + column). A locked cell renders
+     * with a lock affordance and refuses edits while its neighbors stay
+     * editable — how XLSX keeps formula/date cells safe from value patching.
+     */
+    isCellLocked?: (rowId: number, col: number) => boolean;
+    /** Tooltip/announcement for locked cells. */
+    lockedReason?: string;
+    /**
+     * Formula editing, when the host has a calculation engine. A cell whose
+     * `getFormula` returns text edits as `=formula`; any committed draft
+     * starting with `=` routes through `commitFormula`, whose returned
+     * `updates` (the edited cell plus recalculated dependents) are applied to
+     * the provider and the visible cache.
+     */
+    formulaSupport?: FormulaSupport;
+    /**
+     * Notified after each committed VALUE edit. A host mirroring edits into a
+     * calculation engine may RETURN the recalculated dependent updates, which
+     * the grid applies to the provider and the visible cache — this is what
+     * makes formula cells recalc live when a plain value changes.
+     */
+    onCellEdited?: (edit: TableCellEdit) => void | TableCellEdit[] | Promise<void | TableCellEdit[]>;
+    /** Unsaved formula edits (kept outside the value journal) for the save bar. */
+    extraDirtyCount?: number;
+    /**
+     * Discard handler for those formula edits (runs beside journal discard).
+     * The host reverts its engine + provider; the grid then refetches.
+     */
+    onDiscardExtra?: () => void | Promise<void>;
+    className?: string;
+}
+interface FormulaCommitResult {
+    ok: boolean;
+    /** User-facing message when `ok` is false (parse error, budget, …). */
+    error?: string;
+    /** Value updates to apply: the edited cell + recalculated dependents. */
+    updates?: TableCellEdit[];
+}
+interface FormulaSupport {
+    /** Formula source (no `=`) for a cell, or undefined for plain values. */
+    getFormula(rowId: number, col: number): string | undefined;
+    commitFormula(rowId: number, col: number, formula: string): Promise<FormulaCommitResult>;
+}
+declare function DataGrid({ provider, journal, view, onViewChange, viewPersisted, onSave, saving, height, readOnlyReason, isCellLocked, lockedReason, formulaSupport, onCellEdited, extraDirtyCount, onDiscardExtra, className, }: DataGridProps): ReactElement;
+
+export { type ColumnarTable, DataGrid, type DataGridProps, EditJournal, type FormulaCommitResult, type FormulaSupport, type IngestCell, type IngestColumnHint, type IngestTable, type JournalEntry, type KernelCellEdit, type KernelColumnPayload, type KernelRequest, type KernelResponse, type KernelScope, LocalKernelHost, type StoreColumn, TableStoreClient, type TableStoreClientOptions, buildColumnarTable, buildKernelSource, columnCellValue, discardJournal, journalFor, tableKernel };