logisheets-core 1.1.0

package/dist/structured/index.d.ts

@@ -0,0 +1,41 @@
+import type { Value } from 'logisheets-web';
+/** The slice of the engine that structured-data ops actually need. */
+export interface EnginePort {
+    /** Apply a cell-input transaction. Returns the engine's status object. */
+    handleTransaction(tx: GatewayTransaction): {
+        status: {
+            type: string;
+        };
+    };
+    /** Read a single cell's evaluated value. */
+    getValue(sheetIdx: number, row: number, col: number): Value;
+}
+export interface GatewayTransaction {
+    payloads: ReadonlyArray<{
+        type: 'cellInput';
+        value: {
+            sheetIdx: number;
+            row: number;
+            col: number;
+            content: string;
+        };
+    }>;
+    undoable: boolean;
+    temp: boolean;
+}
+export interface WriteTarget {
+    sheetIdx: number;
+    startRow: number;
+    startCol: number;
+}
+/**
+ * Import: write `records` (rows of string cells) into the sheet, anchored at
+ * (startRow, startCol). One transaction for the whole block. Returns true on
+ * an `ok` engine status.
+ */
+export declare function writeRecords(port: EnginePort, target: WriteTarget, records: ReadonlyArray<ReadonlyArray<string>>, undoable?: boolean): boolean;
+/**
+ * Export: read a `rows` x `cols` rectangle of evaluated values back out as a
+ * 2-D array, anchored at (startRow, startCol).
+ */
+export declare function readRecords(port: EnginePort, target: WriteTarget, rows: number, cols: number): Value[][];

package/dist/structured/index.js

@@ -0,0 +1,50 @@
+// Structured-data primitives — the engine-facing core of data-gateway.
+//
+// These functions are the import/export building blocks: write a 2-D block of
+// records into the workbook, and read a rectangle of records back out. They
+// are PURE LOGIC: they never import a concrete engine. They talk to whatever
+// engine the host injects through the minimal `EnginePort` seam below.
+//
+//   - browser:  wrap logisheets-engine's worker-backed client as an EnginePort
+//   - node:     wrap logisheets' synchronous handle()/Workbook as an EnginePort
+//
+// The payload/value shapes are imported as TYPES from logisheets-web, so this
+// file still carries no runtime dependency.
+/**
+ * Import: write `records` (rows of string cells) into the sheet, anchored at
+ * (startRow, startCol). One transaction for the whole block. Returns true on
+ * an `ok` engine status.
+ */
+export function writeRecords(port, target, records, undoable = true) {
+    const payloads = [];
+    records.forEach((row, r) => {
+        row.forEach((content, c) => {
+            payloads.push({
+                type: 'cellInput',
+                value: {
+                    sheetIdx: target.sheetIdx,
+                    row: target.startRow + r,
+                    col: target.startCol + c,
+                    content,
+                },
+            });
+        });
+    });
+    const effect = port.handleTransaction({ payloads, undoable, temp: false });
+    return effect.status.type === 'ok';
+}
+/**
+ * Export: read a `rows` x `cols` rectangle of evaluated values back out as a
+ * 2-D array, anchored at (startRow, startCol).
+ */
+export function readRecords(port, target, rows, cols) {
+    const out = [];
+    for (let r = 0; r < rows; r++) {
+        const line = [];
+        for (let c = 0; c < cols; c++) {
+            line.push(port.getValue(target.sheetIdx, target.startRow + r, target.startCol + c));
+        }
+        out.push(line);
+    }
+    return out;
+}

package/dist/transaction/index.d.ts

@@ -0,0 +1,8 @@
+import type { Transaction, Payload } from 'logisheets-web';
+export type { Transaction, Payload };
+/**
+ * Build a {@link Transaction}. `temp` is explicit here — the host decides
+ * where it comes from (the App reads its global temp-mode toggle; a runtime
+ * passes false). This keeps the construction logic free of any store.
+ */
+export declare function makeTransaction(payloads: readonly Payload[], undoable: boolean, temp: boolean): Transaction;

package/dist/transaction/index.js

@@ -0,0 +1,11 @@
+// Transaction construction — the engine-neutral core of building an edit
+// transaction. The browser app wraps this with a store-bound `tx()` that
+// supplies the temp-mode flag; the Node runtime builds transactions directly.
+/**
+ * Build a {@link Transaction}. `temp` is explicit here — the host decides
+ * where it comes from (the App reads its global temp-mode toggle; a runtime
+ * passes false). This keeps the construction logic free of any store.
+ */
+export function makeTransaction(payloads, undoable, temp) {
+    return { payloads, undoable, temp };
+}

package/dist/type-guard/index.d.ts

@@ -0,0 +1,3 @@
+export * from './string.js';
+export * from './u8.js';
+export * from './propterty.js';

package/dist/type-guard/index.js

@@ -0,0 +1,3 @@
+export * from './string.js';
+export * from './u8.js';
+export * from './propterty.js';

package/dist/type-guard/propterty.d.ts

@@ -0,0 +1 @@
+export declare function hasOwnProperty<T, K extends PropertyKey>(obj: T, prop: K): obj is T & Record<K, unknown>;

package/dist/type-guard/propterty.js

@@ -0,0 +1,3 @@
+export function hasOwnProperty(obj, prop) {
+    return Object.prototype.hasOwnProperty.call(obj, prop);
+}

package/dist/type-guard/string.d.ts

@@ -0,0 +1 @@
+export declare function isString(value: unknown): value is string;

package/dist/type-guard/string.js

@@ -0,0 +1,3 @@
+export function isString(value) {
+    return typeof value === 'string';
+}

package/dist/type-guard/u8.d.ts

@@ -0,0 +1 @@
+export declare function isArrayBuffer(value: unknown): value is ArrayBuffer;

package/dist/type-guard/u8.js

@@ -0,0 +1,3 @@
+export function isArrayBuffer(value) {
+    return value instanceof ArrayBuffer;
+}

package/dist/utils/a1notation.d.ts

@@ -0,0 +1,18 @@
+export declare function isA1notation(value: unknown): boolean;
+export declare function parseA1notation(value: string): {
+    cs: number;
+    rs: number;
+    ce?: number;
+    re?: number;
+} | undefined;
+/**
+ * Convert a 0-based column index to A1-notation, i.e., A, BC, etc..
+ *
+ * Note that the in Excel A1-notation, row indices are plain integers and don't
+ * need to be formatted to A1-notation.
+ */
+export declare function toA1notation(index: number): string;
+/**
+ * Convert a A1-notation to 0-based column index, i.e., A, BC, etc..
+ */
+export declare function toZeroBasedNotation(notation: string): number;

package/dist/utils/a1notation.js

@@ -0,0 +1,76 @@
+// https://github.com/FLighter7/a1-notation
+import { upperCase } from '../strings/index.js';
+import { isString } from '../type-guard/index.js';
+const a1notationReg = /^(?<cs>[A-Z]+)(?<rs>\d+)(:(?<ce>[A-Z]+)(?<re>\d+))?$/i;
+const notationReq = /^[A-Z]/;
+export function isA1notation(value) {
+    if (!isString(value))
+        return false;
+    return a1notationReg.test(upperCase(value));
+}
+// zero-based
+export function parseA1notation(value) {
+    const result = upperCase(value).match(a1notationReg);
+    if (!result?.groups)
+        return;
+    const { ce, re, cs, rs } = result.groups;
+    return {
+        cs: toZeroBasedNotation(cs),
+        rs: parseInt(rs) - 1,
+        ce: ce ? toZeroBasedNotation(ce) : undefined,
+        re: re ? parseInt(re) - 1 : undefined,
+    };
+}
+/**
+ * Convert a 0-based column index to A1-notation, i.e., A, BC, etc..
+ *
+ * Note that the in Excel A1-notation, row indices are plain integers and don't
+ * need to be formatted to A1-notation.
+ */
+export function toA1notation(index) {
+    /**
+     * The algorithm employed here is the same as converting numbers between
+     * different bases, e.g., decimal vs. hexadecimal.
+     *
+     * The A1-notation uses A-Z as the basic letters.  Therefore it is
+     * intrinsically a 26-based notation.
+     */
+    if (!Number.isSafeInteger(index) || index < 0)
+        throw Error(`Invalid column index '${index}'. Must be a non-negative integer.`);
+    // Use 0-based index internally.
+    let n = index;
+    let ret = '';
+    while (n > -1) {
+        // 26 = number of letters from A to Z
+        // 0x41 = 65 = the code point of 'A'
+        const codePoint = (n % 26) + 0x41;
+        ret = String.fromCodePoint(codePoint) + ret;
+        n = Math.floor(n / 26) - 1;
+    }
+    return ret;
+}
+/**
+ * Convert a A1-notation to 0-based column index, i.e., A, BC, etc..
+ */
+export function toZeroBasedNotation(notation) {
+    const n = upperCase(notation);
+    if (!n.match(notationReq) || n === '')
+        throw Error(`Invalid notation ${n}. Must be a [A-Z] character.`);
+    let index = 0;
+    // Calculation method:
+    // Example:
+    //
+    //   position:                           "ABC"
+    //   char                           "A"       "B"       "C"
+    //   charCode                        65        66       67
+    //   number                          1         2        3
+    //   powNumber                       2         1        0
+    //   sum=number*26^powNumber       1*26^2    2*26^1   3*26^0
+    //   numberSum(one_based_index) =  1*26^2 + 2*26^1 + 3*26^0  = 731
+    //   index(zero_based_index) = numSum - 1 = 730
+    for (let pos = 0; pos < n.length; pos += 1) {
+        const powNumber = n.length - 1 - pos;
+        index += Math.pow(26, powNumber) * (n.charCodeAt(pos) - 64);
+    }
+    return index - 1;
+}

package/dist/utils/array.d.ts

@@ -0,0 +1,2 @@
+export declare function initArr<T>(len: number, value?: T): T[];
+export declare function initTable<T>(initValue: T): T[][];

package/dist/utils/array.js

@@ -0,0 +1,12 @@
+import { MAX_LEN } from './const.js';
+export function initArr(len, value) {
+    return new Array(len).fill(value);
+}
+export function initTable(initValue) {
+    const table = [];
+    for (let i = 0; i <= MAX_LEN; i += 1) {
+        const row = initArr(MAX_LEN, initValue);
+        table.push(row);
+    }
+    return table;
+}

package/dist/utils/clone.d.ts

@@ -0,0 +1,2 @@
+export declare function shallowCopy(curr: any, target: any): void;
+export declare function deepCopy(curr: any, target: any): void;

package/dist/utils/clone.js

@@ -0,0 +1,25 @@
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function shallowCopy(curr, target) {
+    if (typeof curr !== 'object' || typeof target !== 'object')
+        return;
+    for (const key in curr) {
+        if (Object.prototype.hasOwnProperty.call(curr, key)) {
+            target[key] = curr[key];
+        }
+    }
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function deepCopy(curr, target) {
+    if (typeof curr !== 'object' || typeof target !== 'object')
+        return;
+    for (const key in curr) {
+        const v = curr[key];
+        if (typeof v !== 'object') {
+            target[key] = v;
+        }
+        else {
+            const value = Array.isArray(v) ? [] : {};
+            deepCopy(curr[key], value);
+        }
+    }
+}

package/dist/utils/const.d.ts

@@ -0,0 +1,7 @@
+export declare const DEBUG_WEB = true;
+export declare const DEBUG_ERR = true;
+export declare const MAX_LEN = 128;
+export declare enum AttributeName {
+    SELECTOR_DND_HANDLE = "data-selector-dnd-handle",
+    SELECTOR_DND_MASK = "data-selector-dnd-mask"
+}

package/dist/utils/const.js

@@ -0,0 +1,8 @@
+export const DEBUG_WEB = true;
+export const DEBUG_ERR = true;
+export const MAX_LEN = 128;
+export var AttributeName;
+(function (AttributeName) {
+    AttributeName["SELECTOR_DND_HANDLE"] = "data-selector-dnd-handle";
+    AttributeName["SELECTOR_DND_MASK"] = "data-selector-dnd-mask";
+})(AttributeName || (AttributeName = {}));

package/dist/utils/equal.d.ts

@@ -0,0 +1 @@
+export declare function equal(a: any, b: any): boolean;

package/dist/utils/equal.js

@@ -0,0 +1,11 @@
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function equal(a, b) {
+    let result = true;
+    Object.keys(a).forEach((key) => {
+        if (!b[key])
+            result = false;
+        if (a[key] !== b[key])
+            result = false;
+    });
+    return result;
+}

package/dist/utils/index.d.ts

@@ -0,0 +1,6 @@
+export * from './a1notation.js';
+export * from './array.js';
+export * from './clone.js';
+export * from './const.js';
+export * from './equal.js';
+export * from './uuid.js';

package/dist/utils/index.js

@@ -0,0 +1,6 @@
+export * from './a1notation.js';
+export * from './array.js';
+export * from './clone.js';
+export * from './const.js';
+export * from './equal.js';
+export * from './uuid.js';

package/dist/utils/uuid.d.ts

@@ -0,0 +1 @@
+export declare function simpleUuid(): string;

package/dist/utils/uuid.js

@@ -0,0 +1,4 @@
+export function simpleUuid() {
+    return '10000000-1000-4000-8000-100000000000'.replace(/[018]/g, (c) => (+c ^
+        (crypto.getRandomValues(new Uint8Array(1))[0] & (15 >> (+c / 4)))).toString(16));
+}

package/dist/validation/index.d.ts

@@ -0,0 +1,34 @@
+import type { Value } from 'logisheets-web';
+/** One cell's validation rule. `formula` is an Excel expression (no leading
+ * `=`) that should reference the target cell(s) and evaluate to a boolean,
+ * e.g. `A1>0` or `LEN(B2)<=10`. */
+export interface ValidationRule {
+    sheetIdx: number;
+    row: number;
+    col: number;
+    formula: string;
+}
+export type ViolationKind = 'failed' | 'error' | 'required' | 'duplicate' | 'membership';
+export interface Violation {
+    sheetIdx: number;
+    row: number;
+    col: number;
+    formula?: string;
+    kind: ViolationKind;
+    message: string;
+}
+/**
+ * Interpret a single evaluated validation result. Mirrors the branch logic
+ * in the browser's ValidationCell:
+ *   - empty            -> valid (nothing to check)
+ *   - bool false       -> failed
+ *   - error            -> formula error
+ *   - anything else    -> unexpected, treated as error
+ */
+export declare function interpretValidation(rule: ValidationRule, value: Value): Violation | null;
+/**
+ * Check every rule and return the cells that break their validation. Pure:
+ * the caller supplies `evalFormula` (WorkbookOps wraps the engine). `rules`
+ * are evaluated against the values already resolved by the caller.
+ */
+export declare function checkValidations(rules: readonly ValidationRule[], evalFormula: (sheetIdx: number, formula: string) => Value): Violation[];

package/dist/validation/index.js

@@ -0,0 +1,60 @@
+// Validation — headless rule checking.
+//
+// A validation rule is just a formula that must evaluate to TRUE for the cell
+// to be valid (this is exactly the model used by the browser's ValidationCell:
+// it writes `=<formula>` into a shadow/ephemeral cell, lets the WASM engine
+// evaluate it, and reads back a bool). The *evaluation* lives entirely in the
+// engine, so it already runs on Node — this module is only the pure result
+// interpretation. The engine access is supplied by the caller as a plain
+// `evalFormula` function (WorkbookOps wraps the Client); see ../ops.
+/**
+ * Interpret a single evaluated validation result. Mirrors the branch logic
+ * in the browser's ValidationCell:
+ *   - empty            -> valid (nothing to check)
+ *   - bool false       -> failed
+ *   - error            -> formula error
+ *   - anything else    -> unexpected, treated as error
+ */
+export function interpretValidation(rule, value) {
+    if (value === undefined)
+        return null;
+    // The engine represents an empty cell as the literal string 'empty'.
+    if (value === 'empty')
+        return null;
+    const v = value;
+    if (v.type === 'empty')
+        return null;
+    if (v.type === 'bool') {
+        if (v.value === false) {
+            return {
+                ...rule,
+                kind: 'failed',
+                message: 'Value does not meet validation criteria',
+            };
+        }
+        return null;
+    }
+    if (v.type === 'error') {
+        return {
+            ...rule,
+            kind: 'error',
+            message: 'Validation formula error: ' + String(v.value),
+        };
+    }
+    return { ...rule, kind: 'error', message: 'Unexpected validation result' };
+}
+/**
+ * Check every rule and return the cells that break their validation. Pure:
+ * the caller supplies `evalFormula` (WorkbookOps wraps the engine). `rules`
+ * are evaluated against the values already resolved by the caller.
+ */
+export function checkValidations(rules, evalFormula) {
+    const out = [];
+    for (const rule of rules) {
+        const value = evalFormula(rule.sheetIdx, rule.formula);
+        const violation = interpretValidation(rule, value);
+        if (violation)
+            out.push(violation);
+    }
+    return out;
+}

package/dist/value/index.d.ts

@@ -0,0 +1,9 @@
+import type { Value } from 'logisheets-web';
+/** The engine represents an empty cell as the literal string 'empty'. */
+export declare function isValueEmpty(v: Value): boolean;
+/** Extract a string, or '' for non-string / empty values. */
+export declare function valueToString(val: Value): string;
+/** Extract a number, or null for non-number / empty values. */
+export declare function valueToNumber(val: Value): number | null;
+/** Coerce any Value to its display string (str / number / bool). */
+export declare function valueToDisplayString(val: Value): string;

package/dist/value/index.js

@@ -0,0 +1,49 @@
+// Pure Value helpers — parsing/formatting/emptiness of engine cell values.
+//
+// These are data transformations with no UI or engine dependency (the Value
+// type is imported as a type only), so they are shared by the App's renderers
+// and any Node-side logic.
+/** The engine represents an empty cell as the literal string 'empty'. */
+export function isValueEmpty(v) {
+    if (v === undefined)
+        return true;
+    if (v === 'empty')
+        return true;
+    const x = v;
+    if (x.type === 'empty')
+        return true;
+    if (x.type === 'str' && (x.value === '' || x.value === undefined))
+        return true;
+    return false;
+}
+/** Extract a string, or '' for non-string / empty values. */
+export function valueToString(val) {
+    if (val === 'empty')
+        return '';
+    const x = val;
+    if (x.type === 'str')
+        return x.value;
+    return '';
+}
+/** Extract a number, or null for non-number / empty values. */
+export function valueToNumber(val) {
+    if (val === 'empty')
+        return null;
+    const x = val;
+    if (x.type === 'number')
+        return x.value;
+    return null;
+}
+/** Coerce any Value to its display string (str / number / bool). */
+export function valueToDisplayString(val) {
+    if (val === 'empty')
+        return '';
+    const x = val;
+    if (x.type === 'str')
+        return x.value;
+    if (x.type === 'number')
+        return String(x.value);
+    if (x.type === 'bool')
+        return x.value ? 'TRUE' : 'FALSE';
+    return '';
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+    "name": "logisheets-core",
+    "version": "1.1.0",
+    "description": "UI-free LogiSheets logic — runs in the browser or on Node. Depends on logisheets-web only for types; the engine Client is injected by the host.",
+    "main": "./dist/index.js",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "type": "module",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        },
+        "./strings": {
+            "types": "./dist/strings/index.d.ts",
+            "default": "./dist/strings/index.js"
+        },
+        "./type-guard": {
+            "types": "./dist/type-guard/index.d.ts",
+            "default": "./dist/type-guard/index.js"
+        },
+        "./selection": {
+            "types": "./dist/selection/index.d.ts",
+            "default": "./dist/selection/index.js"
+        },
+        "./utils": {
+            "types": "./dist/utils/index.d.ts",
+            "default": "./dist/utils/index.js"
+        },
+        "./value": {
+            "types": "./dist/value/index.d.ts",
+            "default": "./dist/value/index.js"
+        }
+    },
+    "scripts": {
+        "build": "tsc -p tsconfig.build.json",
+        "typecheck": "tsc --noEmit",
+        "test": "vitest run",
+        "prepack": "yarn build"
+    },
+    "files": [
+        "dist"
+    ],
+    "author": "Jeremy He",
+    "license": "MIT",
+    "peerDependencies": {
+        "logisheets-web": "^1.1.0"
+    },
+    "devDependencies": {
+        "logisheets-web": "workspace:*",
+        "typescript": "^5.5.0",
+        "vitest": "^2.0.0"
+    }
+}