@lp-labs/table-model 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Libin Prasanth
+
+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/README.md

@@ -1,3 +1,67 @@
-# Temporary Holding Version
+# @lp-labs/table-model
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A small validated table occupancy model. Cells are rectangular spans; any overlap or out-of-range
+operation is rejected before the existing table state changes.
+
+## Install
+
+```sh
+npm install @lp-labs/table-model
+```
+
+```js
+import { createTableModel } from '@lp-labs/table-model';
+
+const table = createTableModel(3, 4, [
+  {
+    id: 'title',
+    row: 0,
+    column: 0,
+    rowSpan: 1,
+    columnSpan: 3,
+    value: 'Quarterly report',
+  },
+  { id: 'amount', row: 1, column: 0, value: '42' },
+]);
+console.log(table.cellAt(0, 2)); // the spanning title cell
+table.moveCell('amount', 2, 0);
+table.resizeCell('title', 1, 4);
+```
+
+## API
+
+- `createTableModel(rowCount, columnCount, cells?, options?)` creates a table with positive integer
+  dimensions. A cell has a unique `id`, zero-based `row` and `column`, optional positive
+  `rowSpan`/`columnSpan` (default 1), and optional text `value`.
+- `TableModel.rowCount` and `TableModel.columnCount` expose the immutable table dimensions.
+- `TableModel.cells()` returns copied cell records in insertion order.
+- `TableModel.cellAt(row, column)` returns a copied occupying cell or `undefined` for an empty or
+  out-of-table position.
+- `TableModel.addCell(cell)`, `moveCell(id, row, column)`, and `resizeCell(id, rowSpan, columnSpan)`
+  validate the complete candidate layout before committing. A failure leaves every cell unchanged.
+- `TableModel.removeCell(id)` returns `true` when removed and `false` when absent.
+- `TableCell`, `TableModel`, and `TableModelOptions` are exported types.
+
+Options `maxRows`, `maxColumns`, and `maxCells` default to 10,000, 10,000, and 100,000 and may only
+lower those limits. Coordinates are zero-based. The model stores plain text values, not formulas,
+styles, row/column metadata, or rendered HTML.
+
+Invalid IDs, dimensions, spans, values, duplicates, overlaps, and capacity violations throw
+`TypeError` or `RangeError`; unknown IDs for move/resize throw `TypeError`. Mutating methods are
+atomic with respect to validation failures.
+
+## Module formats and customization
+
+ESM, CommonJS, and TypeScript declarations are included. For CommonJS, use
+`const { createTableModel } = require('@lp-labs/table-model')`. Adapt application-specific values
+to text in your own layer, or add a separately validated payload map keyed by cell ID.
+
+There are no runtime or peer dependencies. TypeScript and Prettier are development-only.
+
+## Support
+
+If this library is useful to you, consider supporting its maintenance with a [donation via PayPal](https://www.paypal.me/LibinPrasanth).
+
+## Author
+
+Created by [Libin Prasanth](https://www.linkedin.com/in/libinprasanth/). Connect on LinkedIn for updates and discussion.

package/dist/cjs/index.d.ts

@@ -0,0 +1,24 @@
+export interface TableCell {
+    id: string;
+    row: number;
+    column: number;
+    rowSpan?: number;
+    columnSpan?: number;
+    value?: string;
+}
+export interface TableModelOptions {
+    maxRows?: number;
+    maxColumns?: number;
+    maxCells?: number;
+}
+export interface TableModel {
+    readonly rowCount: number;
+    readonly columnCount: number;
+    cells(): TableCell[];
+    cellAt(row: number, column: number): TableCell | undefined;
+    addCell(cell: TableCell): void;
+    moveCell(id: string, row: number, column: number): void;
+    resizeCell(id: string, rowSpan: number, columnSpan: number): void;
+    removeCell(id: string): boolean;
+}
+export declare function createTableModel(rowCount: number, columnCount: number, initialCells?: Iterable<TableCell>, options?: TableModelOptions): TableModel;

package/dist/cjs/index.js

@@ -0,0 +1,201 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTableModel = createTableModel;
+const MAX_ROWS = 10_000;
+const MAX_COLUMNS = 10_000;
+const MAX_CELLS = 100_000;
+function limit(value, maximum, name) {
+    const result = value ?? maximum;
+    if (!Number.isSafeInteger(result) || result < 1 || result > maximum) {
+        throw new RangeError(`${name} must be an integer from 1 to ${maximum}.`);
+    }
+    return result;
+}
+function integer(value, name) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        throw new RangeError(`${name} must be a nonnegative integer.`);
+}
+function copyCell(cell) {
+    if (!cell || typeof cell !== 'object')
+        throw new TypeError('A cell is required.');
+    if (typeof cell.id !== 'string' || !cell.id.trim() || cell.id.length > 128) {
+        throw new TypeError('Cell ID must be a nonempty string up to 128 characters.');
+    }
+    integer(cell.row, 'row');
+    integer(cell.column, 'column');
+    const rowSpan = cell.rowSpan ?? 1;
+    const columnSpan = cell.columnSpan ?? 1;
+    if (!Number.isSafeInteger(rowSpan) || rowSpan < 1)
+        throw new RangeError('rowSpan must be positive.');
+    if (!Number.isSafeInteger(columnSpan) || columnSpan < 1)
+        throw new RangeError('columnSpan must be positive.');
+    if (cell.value !== undefined && typeof cell.value !== 'string') {
+        throw new TypeError('Cell value must be text.');
+    }
+    return Object.freeze({
+        id: cell.id,
+        row: cell.row,
+        column: cell.column,
+        rowSpan,
+        columnSpan,
+        ...(cell.value === undefined ? {} : { value: cell.value }),
+    });
+}
+function createTableModel(rowCount, columnCount, initialCells = [], options = {}) {
+    const maxRows = limit(options.maxRows, MAX_ROWS, 'maxRows');
+    const maxColumns = limit(options.maxColumns, MAX_COLUMNS, 'maxColumns');
+    const maxCells = limit(options.maxCells, MAX_CELLS, 'maxCells');
+    if (!Number.isSafeInteger(rowCount) || rowCount < 1 || rowCount > maxRows) {
+        throw new RangeError(`rowCount must be an integer from 1 to ${maxRows}.`);
+    }
+    if (!Number.isSafeInteger(columnCount) || columnCount < 1 || columnCount > maxColumns) {
+        throw new RangeError(`columnCount must be an integer from 1 to ${maxColumns}.`);
+    }
+    if (initialCells == null || typeof initialCells[Symbol.iterator] !== 'function') {
+        throw new TypeError('Initial cells must be iterable.');
+    }
+    let cells = [];
+    const validate = (candidate) => {
+        if (candidate.length > maxCells)
+            throw new RangeError('Cell capacity exceeded.');
+        const ids = new Set();
+        const columnEdges = new Set();
+        for (const cell of candidate) {
+            if (cell.row + cell.rowSpan > rowCount || cell.column + cell.columnSpan > columnCount) {
+                throw new RangeError(`Cell ${cell.id} exceeds table dimensions.`);
+            }
+            if (ids.has(cell.id))
+                throw new TypeError(`Duplicate cell ID: ${cell.id}`);
+            ids.add(cell.id);
+            columnEdges.add(cell.column);
+            columnEdges.add(cell.column + cell.columnSpan);
+        }
+        if (candidate.length < 2)
+            return;
+        const edges = [...columnEdges].sort((a, b) => a - b);
+        const edgeIndex = new Map(edges.map((edge, index) => [edge, index]));
+        const events = candidate.flatMap((cell) => [
+            { row: cell.row, delta: 1, cell },
+            { row: cell.row + cell.rowSpan, delta: -1, cell },
+        ]);
+        events.sort((first, second) => first.row - second.row || first.delta - second.delta);
+        const segmentCount = edges.length - 1;
+        const maximum = new Array(segmentCount * 4).fill(0);
+        const lazy = new Array(segmentCount * 4).fill(0);
+        const apply = (node, delta) => {
+            maximum[node] = maximum[node] + delta;
+            lazy[node] = lazy[node] + delta;
+        };
+        const push = (node) => {
+            if (lazy[node] === 0)
+                return;
+            apply(node * 2, lazy[node]);
+            apply(node * 2 + 1, lazy[node]);
+            lazy[node] = 0;
+        };
+        const update = (node, left, right, queryLeft, queryRight, delta) => {
+            if (queryLeft <= left && right <= queryRight) {
+                apply(node, delta);
+                return;
+            }
+            push(node);
+            const middle = Math.floor((left + right) / 2);
+            if (queryLeft <= middle) {
+                update(node * 2, left, middle, queryLeft, queryRight, delta);
+            }
+            if (queryRight > middle) {
+                update(node * 2 + 1, middle + 1, right, queryLeft, queryRight, delta);
+            }
+            maximum[node] = Math.max(maximum[node * 2], maximum[node * 2 + 1]);
+        };
+        const queryMaximum = (node, left, right, queryLeft, queryRight) => {
+            if (queryLeft <= left && right <= queryRight)
+                return maximum[node];
+            push(node);
+            const middle = Math.floor((left + right) / 2);
+            let result = 0;
+            if (queryLeft <= middle) {
+                result = queryMaximum(node * 2, left, middle, queryLeft, queryRight);
+            }
+            if (queryRight > middle) {
+                result = Math.max(result, queryMaximum(node * 2 + 1, middle + 1, right, queryLeft, queryRight));
+            }
+            return result;
+        };
+        for (const event of events) {
+            const left = edgeIndex.get(event.cell.column);
+            const right = edgeIndex.get(event.cell.column + event.cell.columnSpan) - 1;
+            if (event.delta < 0) {
+                update(1, 0, segmentCount - 1, left, right, -1);
+            }
+            else {
+                if (queryMaximum(1, 0, segmentCount - 1, left, right) > 0) {
+                    throw new RangeError(`Cell ${event.cell.id} overlaps another cell.`);
+                }
+                update(1, 0, segmentCount - 1, left, right, 1);
+            }
+        }
+    };
+    for (const inputCell of initialCells) {
+        if (cells.length >= maxCells)
+            throw new RangeError('Cell capacity exceeded.');
+        const cell = copyCell(inputCell);
+        cells.push(cell);
+    }
+    validate(cells);
+    const requireCell = (id) => {
+        const cell = cells.find((item) => item.id === id);
+        if (!cell)
+            throw new TypeError(`Unknown cell ID: ${id}`);
+        return cell;
+    };
+    return {
+        rowCount,
+        columnCount,
+        cells() {
+            return cells.map((cell) => ({ ...cell }));
+        },
+        cellAt(row, column) {
+            integer(row, 'row');
+            integer(column, 'column');
+            if (row >= rowCount || column >= columnCount)
+                return undefined;
+            const cell = cells.find((item) => row >= item.row &&
+                row < item.row + item.rowSpan &&
+                column >= item.column &&
+                column < item.column + item.columnSpan);
+            return cell ? { ...cell } : undefined;
+        },
+        addCell(inputCell) {
+            const cell = copyCell(inputCell);
+            const candidate = [...cells, cell];
+            validate(candidate);
+            cells = candidate;
+        },
+        moveCell(id, row, column) {
+            integer(row, 'row');
+            integer(column, 'column');
+            const previous = requireCell(id);
+            const candidate = cells.map((cell) => cell.id === id ? copyCell({ ...cell, row, column }) : cell);
+            validate(candidate);
+            if (!previous)
+                throw new TypeError(`Unknown cell ID: ${id}`);
+            cells = candidate;
+        },
+        resizeCell(id, rowSpan, columnSpan) {
+            const previous = requireCell(id);
+            const candidate = cells.map((cell) => cell.id === id ? copyCell({ ...cell, rowSpan, columnSpan }) : cell);
+            validate(candidate);
+            if (!previous)
+                throw new TypeError(`Unknown cell ID: ${id}`);
+            cells = candidate;
+        },
+        removeCell(id) {
+            const index = cells.findIndex((cell) => cell.id === id);
+            if (index < 0)
+                return false;
+            cells = cells.filter((cell) => cell.id !== id);
+            return true;
+        },
+    };
+}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/esm/index.d.ts

@@ -0,0 +1,24 @@
+export interface TableCell {
+    id: string;
+    row: number;
+    column: number;
+    rowSpan?: number;
+    columnSpan?: number;
+    value?: string;
+}
+export interface TableModelOptions {
+    maxRows?: number;
+    maxColumns?: number;
+    maxCells?: number;
+}
+export interface TableModel {
+    readonly rowCount: number;
+    readonly columnCount: number;
+    cells(): TableCell[];
+    cellAt(row: number, column: number): TableCell | undefined;
+    addCell(cell: TableCell): void;
+    moveCell(id: string, row: number, column: number): void;
+    resizeCell(id: string, rowSpan: number, columnSpan: number): void;
+    removeCell(id: string): boolean;
+}
+export declare function createTableModel(rowCount: number, columnCount: number, initialCells?: Iterable<TableCell>, options?: TableModelOptions): TableModel;

package/dist/esm/index.js

@@ -0,0 +1,198 @@
+const MAX_ROWS = 10_000;
+const MAX_COLUMNS = 10_000;
+const MAX_CELLS = 100_000;
+function limit(value, maximum, name) {
+    const result = value ?? maximum;
+    if (!Number.isSafeInteger(result) || result < 1 || result > maximum) {
+        throw new RangeError(`${name} must be an integer from 1 to ${maximum}.`);
+    }
+    return result;
+}
+function integer(value, name) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        throw new RangeError(`${name} must be a nonnegative integer.`);
+}
+function copyCell(cell) {
+    if (!cell || typeof cell !== 'object')
+        throw new TypeError('A cell is required.');
+    if (typeof cell.id !== 'string' || !cell.id.trim() || cell.id.length > 128) {
+        throw new TypeError('Cell ID must be a nonempty string up to 128 characters.');
+    }
+    integer(cell.row, 'row');
+    integer(cell.column, 'column');
+    const rowSpan = cell.rowSpan ?? 1;
+    const columnSpan = cell.columnSpan ?? 1;
+    if (!Number.isSafeInteger(rowSpan) || rowSpan < 1)
+        throw new RangeError('rowSpan must be positive.');
+    if (!Number.isSafeInteger(columnSpan) || columnSpan < 1)
+        throw new RangeError('columnSpan must be positive.');
+    if (cell.value !== undefined && typeof cell.value !== 'string') {
+        throw new TypeError('Cell value must be text.');
+    }
+    return Object.freeze({
+        id: cell.id,
+        row: cell.row,
+        column: cell.column,
+        rowSpan,
+        columnSpan,
+        ...(cell.value === undefined ? {} : { value: cell.value }),
+    });
+}
+export function createTableModel(rowCount, columnCount, initialCells = [], options = {}) {
+    const maxRows = limit(options.maxRows, MAX_ROWS, 'maxRows');
+    const maxColumns = limit(options.maxColumns, MAX_COLUMNS, 'maxColumns');
+    const maxCells = limit(options.maxCells, MAX_CELLS, 'maxCells');
+    if (!Number.isSafeInteger(rowCount) || rowCount < 1 || rowCount > maxRows) {
+        throw new RangeError(`rowCount must be an integer from 1 to ${maxRows}.`);
+    }
+    if (!Number.isSafeInteger(columnCount) || columnCount < 1 || columnCount > maxColumns) {
+        throw new RangeError(`columnCount must be an integer from 1 to ${maxColumns}.`);
+    }
+    if (initialCells == null || typeof initialCells[Symbol.iterator] !== 'function') {
+        throw new TypeError('Initial cells must be iterable.');
+    }
+    let cells = [];
+    const validate = (candidate) => {
+        if (candidate.length > maxCells)
+            throw new RangeError('Cell capacity exceeded.');
+        const ids = new Set();
+        const columnEdges = new Set();
+        for (const cell of candidate) {
+            if (cell.row + cell.rowSpan > rowCount || cell.column + cell.columnSpan > columnCount) {
+                throw new RangeError(`Cell ${cell.id} exceeds table dimensions.`);
+            }
+            if (ids.has(cell.id))
+                throw new TypeError(`Duplicate cell ID: ${cell.id}`);
+            ids.add(cell.id);
+            columnEdges.add(cell.column);
+            columnEdges.add(cell.column + cell.columnSpan);
+        }
+        if (candidate.length < 2)
+            return;
+        const edges = [...columnEdges].sort((a, b) => a - b);
+        const edgeIndex = new Map(edges.map((edge, index) => [edge, index]));
+        const events = candidate.flatMap((cell) => [
+            { row: cell.row, delta: 1, cell },
+            { row: cell.row + cell.rowSpan, delta: -1, cell },
+        ]);
+        events.sort((first, second) => first.row - second.row || first.delta - second.delta);
+        const segmentCount = edges.length - 1;
+        const maximum = new Array(segmentCount * 4).fill(0);
+        const lazy = new Array(segmentCount * 4).fill(0);
+        const apply = (node, delta) => {
+            maximum[node] = maximum[node] + delta;
+            lazy[node] = lazy[node] + delta;
+        };
+        const push = (node) => {
+            if (lazy[node] === 0)
+                return;
+            apply(node * 2, lazy[node]);
+            apply(node * 2 + 1, lazy[node]);
+            lazy[node] = 0;
+        };
+        const update = (node, left, right, queryLeft, queryRight, delta) => {
+            if (queryLeft <= left && right <= queryRight) {
+                apply(node, delta);
+                return;
+            }
+            push(node);
+            const middle = Math.floor((left + right) / 2);
+            if (queryLeft <= middle) {
+                update(node * 2, left, middle, queryLeft, queryRight, delta);
+            }
+            if (queryRight > middle) {
+                update(node * 2 + 1, middle + 1, right, queryLeft, queryRight, delta);
+            }
+            maximum[node] = Math.max(maximum[node * 2], maximum[node * 2 + 1]);
+        };
+        const queryMaximum = (node, left, right, queryLeft, queryRight) => {
+            if (queryLeft <= left && right <= queryRight)
+                return maximum[node];
+            push(node);
+            const middle = Math.floor((left + right) / 2);
+            let result = 0;
+            if (queryLeft <= middle) {
+                result = queryMaximum(node * 2, left, middle, queryLeft, queryRight);
+            }
+            if (queryRight > middle) {
+                result = Math.max(result, queryMaximum(node * 2 + 1, middle + 1, right, queryLeft, queryRight));
+            }
+            return result;
+        };
+        for (const event of events) {
+            const left = edgeIndex.get(event.cell.column);
+            const right = edgeIndex.get(event.cell.column + event.cell.columnSpan) - 1;
+            if (event.delta < 0) {
+                update(1, 0, segmentCount - 1, left, right, -1);
+            }
+            else {
+                if (queryMaximum(1, 0, segmentCount - 1, left, right) > 0) {
+                    throw new RangeError(`Cell ${event.cell.id} overlaps another cell.`);
+                }
+                update(1, 0, segmentCount - 1, left, right, 1);
+            }
+        }
+    };
+    for (const inputCell of initialCells) {
+        if (cells.length >= maxCells)
+            throw new RangeError('Cell capacity exceeded.');
+        const cell = copyCell(inputCell);
+        cells.push(cell);
+    }
+    validate(cells);
+    const requireCell = (id) => {
+        const cell = cells.find((item) => item.id === id);
+        if (!cell)
+            throw new TypeError(`Unknown cell ID: ${id}`);
+        return cell;
+    };
+    return {
+        rowCount,
+        columnCount,
+        cells() {
+            return cells.map((cell) => ({ ...cell }));
+        },
+        cellAt(row, column) {
+            integer(row, 'row');
+            integer(column, 'column');
+            if (row >= rowCount || column >= columnCount)
+                return undefined;
+            const cell = cells.find((item) => row >= item.row &&
+                row < item.row + item.rowSpan &&
+                column >= item.column &&
+                column < item.column + item.columnSpan);
+            return cell ? { ...cell } : undefined;
+        },
+        addCell(inputCell) {
+            const cell = copyCell(inputCell);
+            const candidate = [...cells, cell];
+            validate(candidate);
+            cells = candidate;
+        },
+        moveCell(id, row, column) {
+            integer(row, 'row');
+            integer(column, 'column');
+            const previous = requireCell(id);
+            const candidate = cells.map((cell) => cell.id === id ? copyCell({ ...cell, row, column }) : cell);
+            validate(candidate);
+            if (!previous)
+                throw new TypeError(`Unknown cell ID: ${id}`);
+            cells = candidate;
+        },
+        resizeCell(id, rowSpan, columnSpan) {
+            const previous = requireCell(id);
+            const candidate = cells.map((cell) => cell.id === id ? copyCell({ ...cell, rowSpan, columnSpan }) : cell);
+            validate(candidate);
+            if (!previous)
+                throw new TypeError(`Unknown cell ID: ${id}`);
+            cells = candidate;
+        },
+        removeCell(id) {
+            const index = cells.findIndex((cell) => cell.id === id);
+            if (index < 0)
+                return false;
+            cells = cells.filter((cell) => cell.id !== id);
+            return true;
+        },
+    };
+}

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@lp-labs/table-model",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Validated span-aware table layout and atomic cell operations.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": "\u003e=18"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "npm run build \u0026\u0026 node scripts/check-types.mjs",
+    "test": "npm run build \u0026\u0026 node --test tests/*.test.mjs",
+    "format": "prettier --write src scripts tests *.json README.md",
+    "format:check": "prettier --check src scripts tests *.json README.md",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "prettier": "^3.6.2"
+  },
+  "prettier": {
+    "singleQuote": true,
+    "semi": true,
+    "trailingComma": "all",
+    "printWidth": 100,
+    "endOfLine": "lf"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "author": {
+    "name": "Libin Prasanth",
+    "url": "https://www.linkedin.com/in/libinprasanth/"
+  },
+  "funding": {
+    "type": "paypal",
+    "url": "https://www.paypal.me/LibinPrasanth"
+  }
+}