logisheets-core 1.1.0 → 1.3.0

package/dist/craft/index.d.ts

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

package/dist/craft/index.js

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

package/dist/craft/manifest.d.ts

@@ -0,0 +1,10 @@
+export interface CraftManifest {
+    /**
+     * The path of the runtime JS file
+     */
+    readonly rtJs: string;
+    /**
+     * The path of the html url which is used in web
+     */
+    readonly html: string;
+}

package/dist/craft/manifest.js

@@ -0,0 +1 @@
+export {};

package/dist/craft/rpc.d.ts

@@ -0,0 +1,17 @@
+export interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id?: string | number | null;
+    method: string;
+    params?: unknown;
+}
+export interface JsonRpcError {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+export interface JsonRpcResponse {
+    jsonrpc: '2.0';
+    id: string | number | null;
+    result?: unknown;
+    error?: JsonRpcError;
+}

package/dist/craft/rpc.js

@@ -0,0 +1,8 @@
+// JSON-RPC 2.0 wire types shared across the craft contract.
+//
+// These describe the envelope a craft's runtime sees in `onRequest` /
+// `onResponse` (see ./runtime.ts). They live in logisheets-core — the shared,
+// host-neutral layer — so both the craft interface here and the Node host's
+// RpcServer (logisheets-runtime) can reference one definition. The host owns
+// the transport (HTTP, dispatch, error mapping); these are only the shapes.
+export {};

package/dist/craft/runtime.d.ts

@@ -0,0 +1,46 @@
+import type { Result } from 'logisheets-web';
+import type { Violation } from '../validation/index.js';
+import type { JsonRpcRequest, JsonRpcResponse } from './rpc.js';
+/**
+ * A craft's persisted state. It is always a JSON object (the craft serializes
+ * it to a string for storage in AppData, and the host treats that string as
+ * opaque). Craft authors narrow this by supplying their own type argument to
+ * {@link CraftRuntime}.
+ */
+export type CraftState = Record<string, unknown>;
+/**
+ * A lifecycle hook may run engine operations, which are async on every host.
+ * So every hook may return its {@link Result} directly or a promise of it; the
+ * host always awaits before inspecting the value.
+ */
+export type MaybePromise<T> = T | Promise<T>;
+/**
+ * The headless logic of a craft, reconstructed by a host from a workbook's
+ * persisted craft state.
+ *
+ * `S` is the craft's own state shape (defaults to a generic JSON object,
+ * {@link CraftState}). `W` is the host's workbook handle — logisheets-core is
+ * host-neutral and does not know the concrete type, so each host binds it: the
+ * Node runtime to its `Workbook`, the browser to its craft workbook wrapper.
+ *
+ * The hooks fire around a single JSON-RPC exchange in this order:
+ *
+ *   onLoad      once, when the workbook is opened — rehydrate from state
+ *   onRequest   inputs of an incoming request are about to be applied
+ *   onValidate  inputs are now in place; check them BEFORE a response is read
+ *   onResponse  the response has been produced and is about to be returned
+ */
+export interface CraftRuntime<S extends CraftState = CraftState, W = unknown> {
+    onLoad: (s: S, wb: W) => MaybePromise<Result<void>>;
+    onRequest: (req: JsonRpcRequest, s: S, wb: W) => MaybePromise<Result<void>>;
+    /**
+     * Called once an RPC request's inputs have been written into the workbook
+     * but BEFORE its response is read back — the gateway's validation
+     * checkpoint. Returns the cells that fail their rules (empty when all
+     * pass). A host that gets a non-empty result should reject the request and
+     * roll the inputs back rather than return a response computed from invalid
+     * input. Optional: a craft with no validation needs simply omits it.
+     */
+    onValidate?: (s: S, wb: W) => MaybePromise<Result<readonly Violation[]>>;
+    onResponse: (resp: JsonRpcResponse, s: S, wb: W) => MaybePromise<Result<void>>;
+}

package/dist/craft/runtime.js

@@ -0,0 +1 @@
+export {};

package/dist/craft/state.d.ts

@@ -0,0 +1,5 @@
+export declare function setCraftState(craftId: string, json: string): void;
+export declare function getCraftState(craftId: string): string | undefined;
+export declare function clearCraftState(craftId: string): void;
+export declare function getPersistentCraftStates(): Record<string, string>;
+export declare function loadPersistentCraftStates(data: unknown): void;

package/dist/craft/state.js

@@ -0,0 +1,48 @@
+// Host-held store of opaque per-craft JSON state.
+//
+// A craft (running in its iframe) pushes its own serialized state here via the
+// injected `setCraftState(json)` API, keyed by the craft's id (its iframe src
+// path — stable across sessions). On file save the host folds the whole store
+// into the AppData envelope under `craftStates`; on load it is rehydrated, so a
+// craft can read its previous state back via `getCraftState()` the next time
+// its iframe mounts.
+//
+// The host treats each entry as an opaque string and never parses it — the
+// craft owns its own schema. This state lives entirely outside the engine's
+// undo/redo Status (it rides AppData, a side channel on the workbook), so
+// writing it never pollutes edit history.
+const craftStates = new Map();
+// Push a craft's serialized state. Called from the iframe-injected
+// `setCraftState`; `craftId` is captured per-iframe by the host.
+export function setCraftState(craftId, json) {
+    if (!craftId)
+        return;
+    craftStates.set(craftId, json);
+}
+// Read a craft's last-known state (e.g. the one rehydrated from the loaded
+// workbook). Returns undefined if the craft never stored anything.
+export function getCraftState(craftId) {
+    return craftStates.get(craftId);
+}
+export function clearCraftState(craftId) {
+    craftStates.delete(craftId);
+}
+// Snapshot every craft's state for persistence into the AppData envelope.
+export function getPersistentCraftStates() {
+    const out = {};
+    for (const [craftId, json] of craftStates)
+        out[craftId] = json;
+    return out;
+}
+// Rehydrate the store from a previously-persisted snapshot. Replaces the
+// current contents so a freshly-loaded workbook doesn't inherit stale state
+// from a prior one.
+export function loadPersistentCraftStates(data) {
+    craftStates.clear();
+    if (!data || typeof data !== 'object')
+        return;
+    for (const [craftId, json] of Object.entries(data)) {
+        if (typeof json === 'string')
+            craftStates.set(craftId, json);
+    }
+}

package/dist/craft-interactions/index.js

@@ -362,9 +362,10 @@ export function getPersistentInteractions() {
     return out;
 }
 export function loadPersistentInteractions(data) {
-    if (!data || typeof data !== 'object')
-        return;
-    const d = data;
+    // Always clear first, then repopulate from whatever the workbook carried.
+    // Passing undefined/null (a workbook with no interaction state) therefore
+    // resets to empty rather than leaving the previous workbook's state behind.
+    const d = (data && typeof data === 'object' ? data : {});
     // Radio
     radioBindings.clear();
     if (Array.isArray(d.radioBindings)) {

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export * from './port.js';
 export * from './ops/index.js';
 export * from './format/index.js';
 export * from './craft-interactions/index.js';
+export * from './craft/index.js';
 export * from './validation/index.js';
 export * from './field/index.js';
 export * from './value/index.js';

package/dist/index.js

@@ -7,6 +7,7 @@ export * from './port.js';
 export * from './ops/index.js';
 export * from './format/index.js';
 export * from './craft-interactions/index.js';
+export * from './craft/index.js';
 export * from './validation/index.js';
 export * from './field/index.js';
 export * from './value/index.js';

package/dist/ops/index.d.ts

@@ -1,4 +1,4 @@
-import type { Payload, ActionEffect, SelectedData, Alignment, StPatternType, Value } from 'logisheets-web';
+import type { Payload, ActionEffect, SelectedData, Alignment, StPatternType, Value, SheetCellId } from 'logisheets-web';
 import type { Client } from '../port.js';
 import { type ValidationRule, type Violation } from '../validation/index.js';
 import { type FieldColumn } from '../field/index.js';
@@ -136,7 +136,24 @@ export declare class WorkbookOps {
      * Lifted verbatim out of the browser's ValidationCell component so the
      * Node runtime gets the same operation.
      */
-    setValidationRule(sheetIdx: number, row: number, col: number, formula: string): Promise<void>;
+    setValidationRule(sheetIdx: number, row: number, col: number, formula: string): Promise<SheetCellId>;
+    /**
+     * Read a set of *installed* validation shadows by their ids and interpret
+     * each — the read half of {@link setValidationRule}.
+     *
+     * The engine evaluates each shadow reactively (with `#PLACEHOLDER` bound to
+     * its target cell), so a caller that cached the shadow ids at install time
+     * gets the up-to-date verdicts here in a single batch read, with no
+     * coordinate resolution. `rule` is carried only into the returned
+     * {@link Violation} for reporting; the evaluation is entirely the engine's.
+     *
+     * Returns one {@link Violation} per failing cell (passing cells and empty
+     * shadows contribute nothing), in input order.
+     */
+    checkValidationShadows(entries: readonly {
+        shadow: SheetCellId;
+        rule: ValidationRule;
+    }[]): Promise<Violation[]>;
     /**
      * Evaluate an Excel formula (no leading `=`) in a sheet and return its
      * Value. Parks the formula in a throwaway ephemeral cell, reads the result

package/dist/ops/index.js

@@ -17,7 +17,7 @@
 // UI side effects (refocus, toasts, event buses, closing dialogs) stay in the
 // host — only the engine-facing operation lives here.
 import { makeTransaction } from '../transaction/index.js';
-import { checkValidations as checkValidationsPure, } from '../validation/index.js';
+import { checkValidations as checkValidationsPure, interpretValidation, } from '../validation/index.js';
 import { checkFieldConstraints as checkFieldConstraintsPure, } from '../field/index.js';
 import { generateFontPayload, generateAlgnmentPayload, generateWrapTextPayload, generateNumFmtPayload, generatePatternFillPayload, generateBorderPayloads, } from '../format/index.js';
 function isErrorMessage(v) {
@@ -269,6 +269,43 @@ export class WorkbookOps {
                 },
             },
         ], false);
+        // Return the shadow's stable id so callers can cache it and later read
+        // the verdict back by id (see {@link checkValidationShadows}) without
+        // re-resolving the cell's coordinates.
+        return shadow;
+    }
+    /**
+     * Read a set of *installed* validation shadows by their ids and interpret
+     * each — the read half of {@link setValidationRule}.
+     *
+     * The engine evaluates each shadow reactively (with `#PLACEHOLDER` bound to
+     * its target cell), so a caller that cached the shadow ids at install time
+     * gets the up-to-date verdicts here in a single batch read, with no
+     * coordinate resolution. `rule` is carried only into the returned
+     * {@link Violation} for reporting; the evaluation is entirely the engine's.
+     *
+     * Returns one {@link Violation} per failing cell (passing cells and empty
+     * shadows contribute nothing), in input order.
+     */
+    async checkValidationShadows(entries) {
+        if (entries.length === 0)
+            return [];
+        const infos = await this.client.batchGetCellInfoById({
+            ids: entries.map((e) => e.shadow),
+        });
+        if (isErrorMessage(infos)) {
+            throw new Error('Failed to read shadow cells: ' + infos.msg);
+        }
+        const out = [];
+        for (let i = 0; i < entries.length; i++) {
+            const info = infos[i];
+            if (!info)
+                continue;
+            const violation = interpretValidation(entries[i].rule, info.value);
+            if (violation)
+                out.push(violation);
+        }
+        return out;
     }
     /**
      * Evaluate an Excel formula (no leading `=`) in a sheet and return its

package/dist/utils/uuid.js

@@ -1,4 +1,14 @@
 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));
+    return '10000000-1000-4000-8000-100000000000'.replace(/[018]/g, (c) => (+c ^ (randomByte() & (15 >> (+c / 4)))).toString(16));
+}
+// `crypto` isn't a typed global here (this package targets ES2020 with no DOM
+// lib, and it must run on both the browser and Node). Reach it through
+// `globalThis` when available (browsers, Node >= 19) and fall back to
+// Math.random otherwise — these ids aren't security-sensitive.
+function randomByte() {
+    const webcrypto = globalThis.crypto;
+    if (webcrypto?.getRandomValues) {
+        return webcrypto.getRandomValues(new Uint8Array(1))[0];
+    }
+    return Math.floor(Math.random() * 256);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "logisheets-core",
-    "version": "1.1.0",
+    "version": "1.3.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,7 +44,7 @@
     "author": "Jeremy He",
     "license": "MIT",
     "peerDependencies": {
-        "logisheets-web": "^1.1.0"
+        "logisheets-web": "^1.3.0"
     },
     "devDependencies": {
         "logisheets-web": "workspace:*",

package/dist/selection/index.d.ts

@@ -1 +0,0 @@
-export * from './model.js';

package/dist/selection/index.js

@@ -1 +0,0 @@
-export * from './model.js';

package/dist/selection/model.d.ts

@@ -1,10 +0,0 @@
-export declare class SelectionModel<T> {
-    #private;
-    readonly multi: boolean;
-    readonly data: readonly T[];
-    constructor(multi?: boolean, data?: readonly T[]);
-    get selected(): readonly T[];
-    toggle(data: T): void;
-    select(data: T): void;
-    deSelect(data: T): void;
-}

package/dist/selection/model.js

@@ -1,38 +0,0 @@
-var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
-    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
-};
-var _SelectionModel_selected;
-export class SelectionModel {
-    constructor(multi = false, data = []) {
-        this.multi = multi;
-        this.data = data;
-        _SelectionModel_selected.set(this, new Map());
-        data.forEach((d) => {
-            __classPrivateFieldGet(this, _SelectionModel_selected, "f").set(d, true);
-        });
-    }
-    get selected() {
-        const selecteds = [];
-        __classPrivateFieldGet(this, _SelectionModel_selected, "f").forEach((checked, d) => {
-            if (!checked)
-                return;
-            selecteds.push(d);
-        });
-        return selecteds;
-    }
-    toggle(data) {
-        if (__classPrivateFieldGet(this, _SelectionModel_selected, "f").has(data))
-            __classPrivateFieldGet(this, _SelectionModel_selected, "f").set(data, true);
-        else
-            __classPrivateFieldGet(this, _SelectionModel_selected, "f").set(data, false);
-    }
-    select(data) {
-        __classPrivateFieldGet(this, _SelectionModel_selected, "f").set(data, true);
-    }
-    deSelect(data) {
-        __classPrivateFieldGet(this, _SelectionModel_selected, "f").set(data, false);
-    }
-}
-_SelectionModel_selected = new WeakMap();

package/dist/strings/common_length.d.ts

@@ -1,4 +0,0 @@
-export declare function commonSuffix(a: string, b: string): string;
-export declare function commonSuffixLength(a: string, b: string): number;
-export declare function commonPrefix(a: string, b: string): string;
-export declare function commonPrefixLength(a: string, b: string): number;

package/dist/strings/common_length.js

@@ -1,28 +0,0 @@
-export function commonSuffix(a, b) {
-    const strs = [];
-    const aLastIndex = a.length - 1;
-    const bLastIndex = b.length - 1;
-    const len = Math.min(a.length, b.length);
-    for (let i = 0; i < len; i += 1) {
-        if (a.charCodeAt(aLastIndex - i) !== b.charCodeAt(bLastIndex - i))
-            break;
-        strs.push(a[i]);
-    }
-    return strs.join('');
-}
-export function commonSuffixLength(a, b) {
-    return commonSuffix(a, b).length;
-}
-export function commonPrefix(a, b) {
-    const strs = [];
-    const len = Math.min(a.length, b.length);
-    for (let i = 0; i < len; i += 1) {
-        if (a.charCodeAt(i) !== b.charCodeAt(i))
-            break;
-        strs.push(a[i]);
-    }
-    return strs.join('');
-}
-export function commonPrefixLength(a, b) {
-    return commonPrefix(a, b).length;
-}

package/dist/structured/index.d.ts

@@ -1,41 +0,0 @@
-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

@@ -1,50 +0,0 @@
-// 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;
-}