logisheets-core 1.9.0 → 1.10.0

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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "logisheets-core",
-    "version": "1.9.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.9.0"
+        "logisheets-web": "^1.10.0"
     },
     "devDependencies": {
+        "@types/node": "^18",
         "logisheets-web": "workspace:*",
-        "typescript": "^5.5.0",
+        "typescript": "^6.0.0",
         "vitest": "3.2.6"
     }
 }