logisheets-core 1.8.0 → 1.10.0

package/README.md

@@ -0,0 +1,72 @@
+# logisheets-core
+
+UI-free LogiSheets logic — the portable core shared by every host. It holds all
+the high-level workbook operations (styling, blocks, fields, validation, crafts,
+transactions, permissions) with **no rendering and no runtime of its own**, so
+the exact same code runs in the browser app and in a headless Node runtime.
+
+It depends on [`logisheets-web`](https://www.npmjs.com/package/logisheets-web)
+for **types only** — the concrete engine `Client` is injected by the host:
+
+- the **browser app** injects the worker-backed client from `logisheets-engine`;
+- [`logisheets-runtime`](https://www.npmjs.com/package/logisheets-runtime)
+  injects a synchronous client built on the Node WASM engine.
+
+## Installation
+
+```bash
+npm install logisheets-core logisheets-web
+```
+
+`logisheets-web` is a peer dependency (used for types). This package is
+ESM-only.
+
+## Usage
+
+You rarely construct the engine `Client` yourself — a host normally provides it.
+Given a `Client`, `WorkbookOps` is the high-level operation layer:
+
+```ts
+import {WorkbookOps} from 'logisheets-core'
+import type {Client} from 'logisheets-web'
+
+declare const client: Client // supplied by the host (browser worker or Node)
+
+const ops = new WorkbookOps(client)
+
+await ops.inputCell(0, 0, 0, 'Hello')          // sheet 0, cell A1
+await ops.createSheet(1, 'Summary')
+await ops.setSheetColor(0, '#4472C4')
+```
+
+`WorkbookOps` covers cell input (including block cells and cell images), sheet
+management (create / delete / rename / color), block operations (move, remove,
+insert rows), and style payload generation (borders, fills, alignment, wrap).
+
+## Subpath exports
+
+Focused utilities are available without pulling in the whole surface:
+
+| Import | Contents |
+|--------|----------|
+| `logisheets-core` | Full surface: ops, format, crafts, validation, fields, values, transactions, permissions |
+| `logisheets-core/strings` | String helpers |
+| `logisheets-core/type-guard` | Runtime type guards for engine types |
+| `logisheets-core/selection` | Selection helpers |
+| `logisheets-core/utils` | General utilities |
+| `logisheets-core/value` | Cell-value helpers |
+
+## Where it fits
+
+```
+logisheets-web / logisheets  (WASM engine, per host)
+                │  Client (types only)
+                ▼
+        logisheets-core        ← you are here (UI-free logic)
+        ┌───────┴────────┐
+   Browser App     logisheets-runtime (Node)
+```
+
+## License
+
+MIT — part of the [LogiSheets](https://github.com/logisky/LogiSheets) project.

package/dist/craft/events.d.ts

@@ -0,0 +1,68 @@
+/** The kinds of canvas events forwarded to a craft. */
+export type CraftCanvasEventType = 'mousedown' | 'mousemove' | 'mouseup' | 'click' | 'dblclick' | 'contextmenu' | 'wheel' | 'keydown' | 'keyup';
+/**
+ * A serialized, realm-safe snapshot of a canvas DOM event, plus the resolved
+ * cell under the pointer. Passed to the craft's handler. It is a plain object
+ * (not the live DOM event) so it crosses the iframe boundary cleanly; the craft
+ * cannot mutate host event state — it only returns a decision.
+ */
+export interface CraftCanvasEvent {
+    type: CraftCanvasEventType;
+    /** Viewport coordinates (mouse/wheel only; 0 for keyboard). */
+    clientX: number;
+    clientY: number;
+    /** Coordinates relative to the data canvas's top-left (mouse/wheel only). */
+    offsetX: number;
+    offsetY: number;
+    /** Which view the event came from ('main' or a secondary view id). */
+    viewId: string;
+    /** The sheet shown in that view. */
+    sheetIdx: number;
+    /** Cell under the pointer, or null when outside the data area / keyboard. */
+    row: number | null;
+    col: number | null;
+    button: number;
+    buttons: number;
+    deltaX: number;
+    deltaY: number;
+    key: string;
+    code: string;
+    altKey: boolean;
+    ctrlKey: boolean;
+    metaKey: boolean;
+    shiftKey: boolean;
+    /** True when the event repeats (held key). */
+    repeat: boolean;
+}
+/**
+ * What a craft returns from its handler. `true` (or `{handled: true}`) tells
+ * the host to consume the event — the engine never sees it. `false`, `void`, or
+ * `{handled: false}` lets it pass through to the engine unchanged.
+ */
+export type CraftInputDecision = boolean | {
+    handled: boolean;
+} | void;
+export type CraftInputHandler = (e: CraftCanvasEvent) => CraftInputDecision;
+/** Host: mark the active craft (its id, i.e. its iframe src), or null. */
+export declare function setActiveCraft(craftId: string | null): void;
+/** The currently-active craft id, or null. */
+export declare function getActiveCraft(): string | null;
+/**
+ * Craft (via injection): register a canvas-input handler. Returns a disposer.
+ * Re-registering replaces the previous handler for that craft.
+ */
+export declare function registerCraftInputHandler(craftId: string, handler: CraftInputHandler): () => void;
+/**
+ * Whether an active craft has a handler ready. The interceptor checks this
+ * first so it does no work (no event serialization) unless a craft is actually
+ * listening — important since this runs on every mousemove.
+ */
+export declare function hasActiveCraftInputHandler(): boolean;
+/**
+ * Host: deliver an event to the active craft and get its decision. Never
+ * throws — a craft handler that throws is treated as "not handled" so a buggy
+ * craft can't wedge the spreadsheet.
+ */
+export declare function dispatchCraftCanvasEvent(evt: CraftCanvasEvent): {
+    handled: boolean;
+};

package/dist/craft/events.js

@@ -0,0 +1,71 @@
+// Canvas input routing for the ACTIVE craft.
+//
+// When a craft is active (its panel is open and it is the selected craft), the
+// host lets it see mouse/keyboard events happening on the spreadsheet canvas
+// BEFORE the engine does, and the craft decides — synchronously — whether the
+// engine should still handle each one. This is the seam that lets a craft
+// implement its own canvas tool (custom selection, drawing, drag gestures)
+// without forking the engine.
+//
+// The craft registers a handler through the injected `window.onCanvasInput`
+// (see the craft panel). The host (the per-view interceptor) calls
+// `dispatchCraftCanvasEvent` from a capture-phase DOM listener; if the active
+// craft's handler returns "handled", the host stops the event from reaching
+// the engine. The call is synchronous end-to-end — the iframe is same-origin,
+// so there is no postMessage hop — which is what makes a real pass-through
+// decision possible mid-dispatch.
+// Which craft is active right now (panel open + selected). null = none, so the
+// interceptor is a no-op and the engine behaves normally.
+let activeCraftId = null;
+// Per-craft handlers. A craft's handler stays registered while its iframe is
+// alive; only the active craft's handler is ever invoked.
+const handlers = new Map();
+/** Host: mark the active craft (its id, i.e. its iframe src), or null. */
+export function setActiveCraft(craftId) {
+    activeCraftId = craftId;
+}
+/** The currently-active craft id, or null. */
+export function getActiveCraft() {
+    return activeCraftId;
+}
+/**
+ * Craft (via injection): register a canvas-input handler. Returns a disposer.
+ * Re-registering replaces the previous handler for that craft.
+ */
+export function registerCraftInputHandler(craftId, handler) {
+    handlers.set(craftId, handler);
+    return () => {
+        if (handlers.get(craftId) === handler)
+            handlers.delete(craftId);
+    };
+}
+/**
+ * Whether an active craft has a handler ready. The interceptor checks this
+ * first so it does no work (no event serialization) unless a craft is actually
+ * listening — important since this runs on every mousemove.
+ */
+export function hasActiveCraftInputHandler() {
+    return activeCraftId !== null && handlers.has(activeCraftId);
+}
+/**
+ * Host: deliver an event to the active craft and get its decision. Never
+ * throws — a craft handler that throws is treated as "not handled" so a buggy
+ * craft can't wedge the spreadsheet.
+ */
+export function dispatchCraftCanvasEvent(evt) {
+    if (activeCraftId === null)
+        return { handled: false };
+    const handler = handlers.get(activeCraftId);
+    if (!handler)
+        return { handled: false };
+    try {
+        const r = handler(evt);
+        const handled = r === true || (typeof r === 'object' && r !== null && r.handled === true);
+        return { handled };
+    }
+    catch (e) {
+        // eslint-disable-next-line no-console
+        console.error('[craft-events] handler threw', e);
+        return { handled: false };
+    }
+}

package/dist/craft/index.d.ts

@@ -1,4 +1,6 @@
 export * from './runtime.js';
 export * from './state.js';
+export * from './storage.js';
+export * from './events.js';
 export * from './manifest.js';
 export * from './rpc.js';

package/dist/craft/index.js

@@ -1,4 +1,6 @@
 export * from './runtime.js';
 export * from './state.js';
+export * from './storage.js';
+export * from './events.js';
 export * from './manifest.js';
 export * from './rpc.js';

package/dist/craft/storage.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The per-craft handle injected onto the craft iframe's `window` as
+ * `window.craftStorage`. All keys/values are scoped to the owning craft; a
+ * craft can neither see nor touch another craft's namespace.
+ */
+export interface CraftStorage {
+    /** Read a value, or `null` if the key was never set. */
+    get(key: string): Promise<string | null>;
+    /** Write a value, overwriting any previous one. */
+    set(key: string, value: string): Promise<void>;
+    /** Delete a single key. A no-op if it doesn't exist. */
+    remove(key: string): Promise<void>;
+    /** List every key this craft has stored. */
+    keys(): Promise<string[]>;
+    /** Delete every key in THIS craft's namespace only. */
+    clear(): Promise<void>;
+}
+/**
+ * The platform-specific store the host injects at startup. It is the same
+ * shape as {@link CraftStorage} but takes an explicit `craftId`, so a single
+ * backend instance serves every craft while keeping their namespaces isolated.
+ * Concrete implementations (localStorage, Tauri app-data) live host-side; core
+ * only defines the seam, mirroring how the engine Client is injected.
+ */
+export interface CraftStorageBackend {
+    get(craftId: string, key: string): Promise<string | null>;
+    set(craftId: string, key: string, value: string): Promise<void>;
+    remove(craftId: string, key: string): Promise<void>;
+    keys(craftId: string): Promise<string[]>;
+    clear(craftId: string): Promise<void>;
+}
+/**
+ * Install the concrete backend for this host. Called once at app startup
+ * (e.g. localStorage in the browser, a Tauri command bridge on the desktop).
+ * Until this runs, craft storage transparently uses an in-memory fallback.
+ */
+export declare function setCraftStorageBackend(backend: CraftStorageBackend): void;
+/**
+ * Build the per-craft {@link CraftStorage} handle the host injects as
+ * `window.craftStorage`. It closes over `craftId` and forwards to whichever
+ * backend is active at call time, so swapping the backend affects every craft
+ * uniformly and the craft can never reach outside its own namespace.
+ */
+export declare function makeCraftStorage(craftId: string): CraftStorage;

package/dist/craft/storage.js

@@ -0,0 +1,73 @@
+// Device-scoped, per-craft key/value storage.
+//
+// This is the sibling of craft STATE (see ./state.ts) but with the opposite
+// scope. Craft state rides the workbook's AppData, so it travels inside the
+// .xlsx and is per-document. Craft storage instead lives on the DEVICE — the
+// browser origin's localStorage on the web, and the app-data directory on the
+// desktop — so it persists across workbooks and never leaves the machine.
+//
+// A craft (running in its iframe) reaches storage through the injected
+// `window.craftStorage` object, which the host binds to that craft's id. Every
+// operation is async because the desktop backend talks to the native side over
+// IPC; the web backend wraps synchronous localStorage in resolved promises so
+// both platforms present the same interface.
+//
+// Values are opaque strings — the craft owns its own schema, exactly as with
+// craft state. The store is plaintext on both platforms, so crafts must not use
+// it for secrets.
+// In-memory fallback used until a host injects a real backend, and on hosts
+// with no persistent store (SSR, a Node runtime, or a browser in private mode
+// where localStorage throws). Data lives only for the session.
+class MemoryCraftStorageBackend {
+    constructor() {
+        this.crafts = new Map();
+    }
+    ns(craftId) {
+        let m = this.crafts.get(craftId);
+        if (!m) {
+            m = new Map();
+            this.crafts.set(craftId, m);
+        }
+        return m;
+    }
+    async get(craftId, key) {
+        const v = this.ns(craftId).get(key);
+        return v === undefined ? null : v;
+    }
+    async set(craftId, key, value) {
+        this.ns(craftId).set(key, value);
+    }
+    async remove(craftId, key) {
+        this.ns(craftId).delete(key);
+    }
+    async keys(craftId) {
+        return [...this.ns(craftId).keys()];
+    }
+    async clear(craftId) {
+        this.crafts.delete(craftId);
+    }
+}
+let activeBackend = new MemoryCraftStorageBackend();
+/**
+ * Install the concrete backend for this host. Called once at app startup
+ * (e.g. localStorage in the browser, a Tauri command bridge on the desktop).
+ * Until this runs, craft storage transparently uses an in-memory fallback.
+ */
+export function setCraftStorageBackend(backend) {
+    activeBackend = backend;
+}
+/**
+ * Build the per-craft {@link CraftStorage} handle the host injects as
+ * `window.craftStorage`. It closes over `craftId` and forwards to whichever
+ * backend is active at call time, so swapping the backend affects every craft
+ * uniformly and the craft can never reach outside its own namespace.
+ */
+export function makeCraftStorage(craftId) {
+    return {
+        get: (key) => activeBackend.get(craftId, key),
+        set: (key, value) => activeBackend.set(craftId, key, value),
+        remove: (key) => activeBackend.remove(craftId, key),
+        keys: () => activeBackend.keys(craftId),
+        clear: () => activeBackend.clear(craftId),
+    };
+}

package/dist/field/index.d.ts

@@ -1,6 +1,6 @@
 import type { Value } from 'logisheets-web';
 import type { Violation } from '../validation/index.js';
-export type FieldTypeEnum = 'enum' | 'multiSelect' | 'datetime' | 'boolean' | 'string' | 'number' | 'image' | 'fieldRef' | 'multiSelectRef';
+export type FieldTypeEnum = 'unspecified' | 'enum' | 'multiSelect' | 'datetime' | 'boolean' | 'string' | 'number' | 'image' | 'fieldRef' | 'multiSelectRef';
 export interface EnumValue {
     id: string;
     label: string;

package/dist/ops/index.d.ts

@@ -83,6 +83,28 @@ export declare class WorkbookOps {
      * clear (see the drag-to-move overlay, which cancels on collision).
      */
     moveBlock(sheetIdx: number, blockId: number, newMasterRow: number, newMasterCol: number): Promise<ActionEffect>;
+    /**
+     * Sort a block's records by the named field. Rows are reordered for a
+     * row-schema block, columns for a col-schema block. The engine computes a
+     * type-aware order (numbers numerically, text lexicographically, blanks
+     * last); the reorder is one undoable transaction.
+     *
+     * Throws for random-schema blocks (no fields) or an unknown field name.
+     */
+    sortBlock(sheetIdx: number, blockId: number, field: string, asc?: boolean, undoable?: boolean): Promise<ActionEffect>;
+    /**
+     * Move a single block line (column or row) from one position to another —
+     * positional `remove(from)` then `insert(to)` on the block's line order
+     * (`MoveBlockLine`). For a row-schema form block, a FIELD is a column, so
+     * reordering fields is `isRow = false` with block-inner column indices.
+     *
+     * `to` is the index in the post-removal frame (matching the engine's
+     * `move_line`). The field's stable line id keeps its cell data, and the
+     * schema's per-field `idx` is re-derived from the new position on the next
+     * read — so both data and field order follow the move automatically; no
+     * re-`bindFormSchema` is needed.
+     */
+    moveBlockLine(sheetIdx: number, blockId: number, from: number, to: number, isRow?: boolean, undoable?: boolean): Promise<ActionEffect>;
     /** Apply font styling (bold/italic/underline/strike/color/size). */
     setFont(sheetIdx: number, data: SelectedData, update: FontStyle): Promise<void>;
     /** Apply horizontal/vertical alignment. */
@@ -137,6 +159,35 @@ export declare class WorkbookOps {
         keyIdx: number;
         fields: readonly FormBlockField[];
     }): Promise<void>;
+    /**
+     * Edit an EXISTING form-backed block: rename it, re-type / re-formula its
+     * existing fields, and/or append new fields — in one transaction. The v1
+     * contract is **fields are never removed**, so the column count is
+     * monotonically non-decreasing: `fields.length >= currentColCnt`. That
+     * keeps this safe with only a *tail* `resizeBlock` (new columns are
+     * appended, existing field columns — and the cells/formulas that
+     * reference them — are untouched, and no schema entry is ever orphaned).
+     *
+     * `fields` is the FULL field list (existing fields first, in their
+     * current order, followed by any newly-added fields). Existing fields
+     * MUST keep their original `renderId` so the block's cells stay wired to
+     * their render/type metadata; the host reconstructs the list from
+     * `BlockInfo.schema.fields[i].renderId`.
+     *
+     * Order matters: the `resizeBlock` runs BEFORE `bindFormSchema` so the
+     * appended field columns exist when the schema binds to them. Validation
+     * / editability formulas are carried on `FieldInfo` (the field type) via
+     * the host's FieldManager, same as `createFormBlock`, so this only needs
+     * to round-trip each field's value-formula template.
+     */
+    editFormBlock(opts: {
+        sheetIdx: number;
+        blockId: number;
+        currentColCnt: number;
+        refName: string;
+        keyIdx: number;
+        fields: readonly FormBlockField[];
+    }): Promise<void>;
     /**
      * Apply a caller-built payload list as one transaction (at the host's
      * temp-mode). Escape hatch for operations whose payload construction still

package/dist/ops/index.js

@@ -140,6 +140,56 @@ export class WorkbookOps {
             },
         ], true);
     }
+    /**
+     * Sort a block's records by the named field. Rows are reordered for a
+     * row-schema block, columns for a col-schema block. The engine computes a
+     * type-aware order (numbers numerically, text lexicographically, blanks
+     * last); the reorder is one undoable transaction.
+     *
+     * Throws for random-schema blocks (no fields) or an unknown field name.
+     */
+    async sortBlock(sheetIdx, blockId, field, asc = true, undoable = true) {
+        const order = await this.client.getBlockSortOrder({
+            sheetIdx,
+            blockId,
+            field,
+            asc,
+        });
+        if (isErrorMessage(order)) {
+            throw new Error('Sort failed: ' + order.msg);
+        }
+        return this.apply([
+            {
+                type: 'reorderBlockLines',
+                value: {
+                    sheetIdx,
+                    blockId,
+                    isRow: order.isRow,
+                    newOrder: order.newOrder,
+                },
+            },
+        ], undoable);
+    }
+    /**
+     * Move a single block line (column or row) from one position to another —
+     * positional `remove(from)` then `insert(to)` on the block's line order
+     * (`MoveBlockLine`). For a row-schema form block, a FIELD is a column, so
+     * reordering fields is `isRow = false` with block-inner column indices.
+     *
+     * `to` is the index in the post-removal frame (matching the engine's
+     * `move_line`). The field's stable line id keeps its cell data, and the
+     * schema's per-field `idx` is re-derived from the new position on the next
+     * read — so both data and field order follow the move automatically; no
+     * re-`bindFormSchema` is needed.
+     */
+    moveBlockLine(sheetIdx, blockId, from, to, isRow = false, undoable = true) {
+        return this.apply([
+            {
+                type: 'moveBlockLine',
+                value: { sheetIdx, blockId, from, to, isRow },
+            },
+        ], undoable);
+    }
     // ---- formatting -----------------------------------------------------
     //
     // Each method turns the current sheet + selection into style-update
@@ -274,6 +324,71 @@ export class WorkbookOps {
         ];
         await this.apply(payloads, true);
     }
+    /**
+     * Edit an EXISTING form-backed block: rename it, re-type / re-formula its
+     * existing fields, and/or append new fields — in one transaction. The v1
+     * contract is **fields are never removed**, so the column count is
+     * monotonically non-decreasing: `fields.length >= currentColCnt`. That
+     * keeps this safe with only a *tail* `resizeBlock` (new columns are
+     * appended, existing field columns — and the cells/formulas that
+     * reference them — are untouched, and no schema entry is ever orphaned).
+     *
+     * `fields` is the FULL field list (existing fields first, in their
+     * current order, followed by any newly-added fields). Existing fields
+     * MUST keep their original `renderId` so the block's cells stay wired to
+     * their render/type metadata; the host reconstructs the list from
+     * `BlockInfo.schema.fields[i].renderId`.
+     *
+     * Order matters: the `resizeBlock` runs BEFORE `bindFormSchema` so the
+     * appended field columns exist when the schema binds to them. Validation
+     * / editability formulas are carried on `FieldInfo` (the field type) via
+     * the host's FieldManager, same as `createFormBlock`, so this only needs
+     * to round-trip each field's value-formula template.
+     */
+    async editFormBlock(opts) {
+        const { sheetIdx, blockId, currentColCnt, refName, keyIdx, fields } = opts;
+        const newColCnt = fields.length;
+        if (newColCnt < currentColCnt) {
+            throw new Error(`editFormBlock cannot remove fields: got ${newColCnt} field(s) ` +
+                `for a block with ${currentColCnt} column(s).`);
+        }
+        const payloads = [];
+        if (newColCnt !== currentColCnt) {
+            payloads.push({
+                type: 'resizeBlock',
+                value: {
+                    sheetIdx,
+                    id: blockId,
+                    newColCnt,
+                },
+            });
+        }
+        payloads.push({
+            type: 'bindFormSchema',
+            value: {
+                refName,
+                sheetIdx,
+                blockId,
+                fieldFrom: 0,
+                row: true,
+                keyIdx: keyIdx < 0 ? 0 : keyIdx,
+                fields: fields.map((f) => f.name),
+                renderIds: fields.map((f) => f.renderId),
+                fieldFormulas: fields.map((f) => f.valueFormula ?? ''),
+                validationFormulas: [],
+                editabilityFormulas: [],
+            },
+        });
+        payloads.push(...fields.map((f) => ({
+            type: 'upsertFieldRenderInfo',
+            value: {
+                renderId: f.renderId,
+                diyRender: f.diyRender,
+                styleUpdate: { setNumFmt: f.numFmt ?? '' },
+            },
+        })));
+        await this.apply(payloads, true);
+    }
     // ---- generic / temp-branch -----------------------------------------
     /**
      * Apply a caller-built payload list as one transaction (at the host's

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "logisheets-core",
-    "version": "1.8.0",
+    "version": "1.10.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",
@@ -44,11 +44,12 @@
     "author": "Jeremy He",
     "license": "MIT",
     "peerDependencies": {
-        "logisheets-web": "^1.8.0"
+        "logisheets-web": "^1.10.0"
     },
     "devDependencies": {
+        "@types/node": "^18",
         "logisheets-web": "workspace:*",
-        "typescript": "^5.5.0",
-        "vitest": "^2.0.0"
+        "typescript": "^6.0.0",
+        "vitest": "3.2.6"
     }
 }