logisheets-core 1.8.0 → 1.9.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/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.9.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,11 @@
     "author": "Jeremy He",
     "license": "MIT",
     "peerDependencies": {
-        "logisheets-web": "^1.8.0"
+        "logisheets-web": "^1.9.0"
     },
     "devDependencies": {
         "logisheets-web": "workspace:*",
         "typescript": "^5.5.0",
-        "vitest": "^2.0.0"
+        "vitest": "3.2.6"
     }
 }