logisheets 1.15.1 → 1.16.0

package/dist/src/client.d.ts

@@ -1,16 +1,49 @@
 import type { ErrorMessage, ActionEffect, SheetCellId, WorkbookMethods, HandleTransactionParams } from './bindings';
 import type { CustomFunc } from './api';
+/** An async engine reply: the value, or an {@link ErrorMessage} on failure. */
 export type Resp<T> = Promise<T | ErrorMessage>;
 /**
- * The client is the interface for the workbook. This is used when the workbook
- * is wrapped by a server.
+ * The async engine contract shared logic codes against. Every method of the
+ * generated {@link WorkbookMethods} is `method(params) => Promise<T |
+ * ErrorMessage>`, bound to one workbook.
+ *
+ * Implementations: logisheets-engine's worker-backed `WorkbookClient` in the
+ * browser, and logisheets-runtime's `handle()` proxy on Node. The
+ * `register*` members below are host-side subscriptions; the Node proxy does
+ * not implement them, so code that must run headless should not rely on them.
+ *
+ * Failure contract (holds for every implementation):
+ *  - Methods never reject for an engine-level failure; they resolve an
+ *    `ErrorMessage` (check with `isErrorMessage`).
+ *  - `handleTransaction` does NOT resolve an `ErrorMessage` when the engine
+ *    refuses the edit. It resolves an `ActionEffect` whose
+ *    `status.type === 'err'`, with the reason in `errorMessage`, and nothing
+ *    is applied. A caller that needs the write to land must check `status`.
  */
 export interface Client extends WorkbookMethods {
+    /** Resolves once the engine can serve calls (the browser worker has
+     *  loaded its WASM). Await it before the first call. */
     isReady(): Promise<void>;
+    /**
+     * `handleTransaction` without the host's per-cell change notifications.
+     * Same failure contract: a rejection is `status.type === 'err'`.
+     */
     handleTransactionWithoutEvents(params: HandleTransactionParams): Resp<ActionEffect>;
+    /** Register a custom formula function. Not implemented by the browser
+     *  worker client. */
     registerCustomFunc(f: CustomFunc): void;
+    /** Fires after a transaction the engine reports as changing cells
+     *  (status `cell` / `sheetAndCell`). */
     registerCellUpdatedCallback(f: () => void): void;
+    /** Fires after a transaction the engine reports as changing sheet-level
+     *  state (status `sheet` / `sheetAndCell`). */
     registerSheetUpdatedCallback(f: () => void): void;
+    /**
+     * Subscribe to value changes of the cell currently at (sheetIdx, rowIdx,
+     * colIdx), all 0-based. The coordinate is resolved to a stable cell id
+     * once, so the subscription follows the cell if rows/cols move. Resolves
+     * an `ErrorMessage` if the coordinate cannot be resolved.
+     */
     registerCellValueChangedCallback(sheetIdx: number, rowIdx: number, colIdx: number, callback: () => void): Resp<void>;
     /**
      * Like {@link registerCellValueChangedCallback} but takes a
@@ -20,6 +53,10 @@ export interface Client extends WorkbookMethods {
      * round-trip.
      */
     registerCellValueChangedByCellId(cellId: SheetCellId, callback: () => void): void;
+    /** Like {@link registerCellValueChangedCallback}, but fires when the cell
+     *  is removed (its row/col deleted). */
     registerCellRemovedCallback(sheetIdx: number, rowIdx: number, colIdx: number, callback: () => void): Resp<void>;
+    /** Subscribe to a cell's shadow (validation) cell. Not implemented by the
+     *  browser worker client. */
     registerShadowCellValueChangedCallback(sheetIdx: number, rowIdx: number, colIdx: number, callback: () => void): Resp<number>;
 }

package/dist/src/layout.d.ts

@@ -1,3 +1,5 @@
+/** A per-cell overlay (marker colour, tooltip) a craft asks the host to draw
+ *  via `window.setCellLayouts`. Row and column are 0-based sheet coordinates. */
 export interface CellLayout {
     readonly sheetIdx: number;
     readonly row: number;

package/dist/src/types.d.ts

@@ -1,10 +1,15 @@
 import { CellCoordinate } from './bindings';
+/** Stable ids of a block's lines; they survive inserts and reorders, unlike
+ *  indexes. See `Workbook.getBlockRowId` / `getBlockColId`. */
 export type RowId = number;
 export type ColId = number;
+/** What the user has selected on one sheet (0-based indexes). */
 export interface Selection {
     readonly sheetIdx: number;
     readonly data: SelectedData;
 }
+/** Either whole rows/columns or a cell rectangle; `data` is absent when
+ *  nothing is selected. */
 export interface SelectedData {
     readonly data?: {
         ty: 'line';
@@ -15,6 +20,7 @@ export interface SelectedData {
     };
     readonly source: 'editbar' | 'none';
 }
+/** A cell rectangle; both bounds inclusive. */
 export interface SelectedCellRange {
     readonly startRow: number;
     readonly endRow: number;
@@ -26,6 +32,8 @@ export interface SelectedLines {
     readonly end: number;
     readonly type: 'row' | 'col';
 }
+/** Top-left cell of the selection (`y` = row, `x` = column). Throws when
+ *  nothing is selected. */
 export declare function getFirstCell(v: SelectedData): CellCoordinate;
 export declare function getSelectedCellRange(v: SelectedData): SelectedCellRange | undefined;
 export declare function getSelectedLines(v: SelectedData): SelectedLines | undefined;

package/dist/src/types.js

@@ -3,6 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getFirstCell = getFirstCell;
 exports.getSelectedCellRange = getSelectedCellRange;
 exports.getSelectedLines = getSelectedLines;
+/** Top-left cell of the selection (`y` = row, `x` = column). Throws when
+ *  nothing is selected. */
 function getFirstCell(v) {
     const r = getSelectedCellRange(v);
     if (r)

package/dist/src/utils.d.ts

@@ -1 +1,5 @@
+/**
+ * A 0-based column index as A1 column letters: 0 -> `A`, 25 -> `Z`,
+ * 26 -> `AA`. Throws for a negative or non-integer index.
+ */
 export declare function toA1notation(index: number): string;

package/dist/src/utils.js

@@ -1,6 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toA1notation = toA1notation;
+/**
+ * A 0-based column index as A1 column letters: 0 -> `A`, 25 -> `Z`,
+ * 26 -> `AA`. Throws for a negative or non-integer index.
+ */
 function toA1notation(index) {
     /**
      * The algorithm employed here is the same as converting numbers between

package/dist/wasm/logisheets_wasm_server.d.ts

@@ -1,11 +1,18 @@
 /* tslint:disable */
 /* eslint-disable */
+/**
+ * The single RPC entry point. `msg` is a [`Message`] as JS (a bare method
+ * name for a unit variant, otherwise `{method, value}`); `book_id` names the
+ * workbook and is required by everything except `newWorkbook`, which returns
+ * the id to use. Answers the method's result or an `ErrorMessage`, told apart
+ * by shape on the JS side.
+ */
 export function handle(msg: any, book_id?: number | null): any;
 /**
- * Input: AsyncFuncResult
- * Output: ActionAffect
+ * Render a text value with an Excel number-format code (for the `@` text
+ * section). Falls back to the text itself on an unsupported format.
  */
-export function input_async_result(id: number, result: any): any;
+export function format_text(fmt: string, text: string): string;
 /**
  * Render a number with an Excel number-format code, natively via `ssf-rs`
  * (the Rust port of SheetJS `ssf`). Replaces the browser's old dependency on
@@ -14,7 +21,8 @@ export function input_async_result(id: number, result: any): any;
  */
 export function format_number(fmt: string, value: number): string;
 /**
- * Render a text value with an Excel number-format code (for the `@` text
- * section). Falls back to the text itself on an unsupported format.
+ * Deliver the values the host computed for this workbook's async functions:
+ * an `AsyncFuncResult` in, an `ActionEffect` or an `ErrorMessage` out. Like
+ * `rpc::handle`, this must never panic.
  */
-export function format_text(fmt: string, text: string): string;
+export function input_async_result(id: number, result: any): any;

package/dist/wasm/logisheets_wasm_server.js

@@ -171,6 +171,11 @@ function debugString(val) {
     return className;
 }
 /**
+ * The single RPC entry point. `msg` is a [`Message`] as JS (a bare method
+ * name for a unit variant, otherwise `{method, value}`); `book_id` names the
+ * workbook and is required by everything except `newWorkbook`, which returns
+ * the id to use. Answers the method's result or an `ErrorMessage`, told apart
+ * by shape on the JS side.
  * @param {any} msg
  * @param {number | null} [book_id]
  * @returns {any}
@@ -181,15 +186,27 @@ module.exports.handle = function(msg, book_id) {
 };
 
 /**
- * Input: AsyncFuncResult
- * Output: ActionAffect
- * @param {number} id
- * @param {any} result
- * @returns {any}
+ * Render a text value with an Excel number-format code (for the `@` text
+ * section). Falls back to the text itself on an unsupported format.
+ * @param {string} fmt
+ * @param {string} text
+ * @returns {string}
  */
-module.exports.input_async_result = function(id, result) {
-    const ret = wasm.input_async_result(id, result);
-    return ret;
+module.exports.format_text = function(fmt, text) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        const ptr0 = passStringToWasm0(fmt, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(text, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ret = wasm.format_text(ptr0, len0, ptr1, len1);
+        deferred3_0 = ret[0];
+        deferred3_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+    }
 };
 
 /**
@@ -217,27 +234,16 @@ module.exports.format_number = function(fmt, value) {
 };
 
 /**
- * Render a text value with an Excel number-format code (for the `@` text
- * section). Falls back to the text itself on an unsupported format.
- * @param {string} fmt
- * @param {string} text
- * @returns {string}
+ * Deliver the values the host computed for this workbook's async functions:
+ * an `AsyncFuncResult` in, an `ActionEffect` or an `ErrorMessage` out. Like
+ * `rpc::handle`, this must never panic.
+ * @param {number} id
+ * @param {any} result
+ * @returns {any}
  */
-module.exports.format_text = function(fmt, text) {
-    let deferred3_0;
-    let deferred3_1;
-    try {
-        const ptr0 = passStringToWasm0(fmt, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
-        const len0 = WASM_VECTOR_LEN;
-        const ptr1 = passStringToWasm0(text, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
-        const len1 = WASM_VECTOR_LEN;
-        const ret = wasm.format_text(ptr0, len0, ptr1, len1);
-        deferred3_0 = ret[0];
-        deferred3_1 = ret[1];
-        return getStringFromWasm0(ret[0], ret[1]);
-    } finally {
-        wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
-    }
+module.exports.input_async_result = function(id, result) {
+    const ret = wasm.input_async_result(id, result);
+    return ret;
 };
 
 module.exports.__wbg_String_eecc4a11987127d6 = function(arg0, arg1) {

package/dist/wasm/package.json

@@ -3,7 +3,7 @@
   "collaborators": [
     "JeremyHe <yiliang.he@qq.com>"
   ],
-  "version": "1.15.1",
+  "version": "1.16.0",
   "files": [
     "logisheets_wasm_server_bg.wasm",
     "logisheets_wasm_server.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "logisheets",
-  "version": "1.15.1",
+  "version": "1.16.0",
   "description": "Node.js bindings for LogiSheets — a Rust + WebAssembly spreadsheet engine that reads, edits, and writes real .xlsx (Excel) files (formulas, styles, and structure preserved) with no browser required.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/wasm/logisheets_wasm_server.d.ts

@@ -1,11 +1,18 @@
 /* tslint:disable */
 /* eslint-disable */
+/**
+ * The single RPC entry point. `msg` is a [`Message`] as JS (a bare method
+ * name for a unit variant, otherwise `{method, value}`); `book_id` names the
+ * workbook and is required by everything except `newWorkbook`, which returns
+ * the id to use. Answers the method's result or an `ErrorMessage`, told apart
+ * by shape on the JS side.
+ */
 export function handle(msg: any, book_id?: number | null): any;
 /**
- * Input: AsyncFuncResult
- * Output: ActionAffect
+ * Render a text value with an Excel number-format code (for the `@` text
+ * section). Falls back to the text itself on an unsupported format.
  */
-export function input_async_result(id: number, result: any): any;
+export function format_text(fmt: string, text: string): string;
 /**
  * Render a number with an Excel number-format code, natively via `ssf-rs`
  * (the Rust port of SheetJS `ssf`). Replaces the browser's old dependency on
@@ -14,7 +21,8 @@ export function input_async_result(id: number, result: any): any;
  */
 export function format_number(fmt: string, value: number): string;
 /**
- * Render a text value with an Excel number-format code (for the `@` text
- * section). Falls back to the text itself on an unsupported format.
+ * Deliver the values the host computed for this workbook's async functions:
+ * an `AsyncFuncResult` in, an `ActionEffect` or an `ErrorMessage` out. Like
+ * `rpc::handle`, this must never panic.
  */
-export function format_text(fmt: string, text: string): string;
+export function input_async_result(id: number, result: any): any;

package/wasm/logisheets_wasm_server.js

@@ -171,6 +171,11 @@ function debugString(val) {
     return className;
 }
 /**
+ * The single RPC entry point. `msg` is a [`Message`] as JS (a bare method
+ * name for a unit variant, otherwise `{method, value}`); `book_id` names the
+ * workbook and is required by everything except `newWorkbook`, which returns
+ * the id to use. Answers the method's result or an `ErrorMessage`, told apart
+ * by shape on the JS side.
  * @param {any} msg
  * @param {number | null} [book_id]
  * @returns {any}
@@ -181,15 +186,27 @@ module.exports.handle = function(msg, book_id) {
 };
 
 /**
- * Input: AsyncFuncResult
- * Output: ActionAffect
- * @param {number} id
- * @param {any} result
- * @returns {any}
+ * Render a text value with an Excel number-format code (for the `@` text
+ * section). Falls back to the text itself on an unsupported format.
+ * @param {string} fmt
+ * @param {string} text
+ * @returns {string}
  */
-module.exports.input_async_result = function(id, result) {
-    const ret = wasm.input_async_result(id, result);
-    return ret;
+module.exports.format_text = function(fmt, text) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        const ptr0 = passStringToWasm0(fmt, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(text, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ret = wasm.format_text(ptr0, len0, ptr1, len1);
+        deferred3_0 = ret[0];
+        deferred3_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+    }
 };
 
 /**
@@ -217,27 +234,16 @@ module.exports.format_number = function(fmt, value) {
 };
 
 /**
- * Render a text value with an Excel number-format code (for the `@` text
- * section). Falls back to the text itself on an unsupported format.
- * @param {string} fmt
- * @param {string} text
- * @returns {string}
+ * Deliver the values the host computed for this workbook's async functions:
+ * an `AsyncFuncResult` in, an `ActionEffect` or an `ErrorMessage` out. Like
+ * `rpc::handle`, this must never panic.
+ * @param {number} id
+ * @param {any} result
+ * @returns {any}
  */
-module.exports.format_text = function(fmt, text) {
-    let deferred3_0;
-    let deferred3_1;
-    try {
-        const ptr0 = passStringToWasm0(fmt, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
-        const len0 = WASM_VECTOR_LEN;
-        const ptr1 = passStringToWasm0(text, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
-        const len1 = WASM_VECTOR_LEN;
-        const ret = wasm.format_text(ptr0, len0, ptr1, len1);
-        deferred3_0 = ret[0];
-        deferred3_1 = ret[1];
-        return getStringFromWasm0(ret[0], ret[1]);
-    } finally {
-        wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
-    }
+module.exports.input_async_result = function(id, result) {
+    const ret = wasm.input_async_result(id, result);
+    return ret;
 };
 
 module.exports.__wbg_String_eecc4a11987127d6 = function(arg0, arg1) {

package/wasm/package.json

@@ -3,7 +3,7 @@
   "collaborators": [
     "JeremyHe <yiliang.he@qq.com>"
   ],
-  "version": "1.15.1",
+  "version": "1.16.0",
   "files": [
     "logisheets_wasm_server_bg.wasm",
     "logisheets_wasm_server.js",