logisheets-engine 1.0.0

package/dist/types/lib/adapters/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Framework adapters for logisheets-engine.
+ * Provides compatibility layers for React and other frameworks.
+ */
+export { convertCanvasPropsToAdapterProps, type SpreadsheetAdapterProps, type CanvasAdapterProps, type UseSpreadsheetConfig, type UseSpreadsheetReturn, } from "./react";

package/dist/types/lib/adapters/react.d.ts

@@ -0,0 +1,88 @@
+/**
+ * React adapter for logisheets-engine Svelte components.
+ * This module provides React wrappers around the Svelte components,
+ * allowing seamless integration with LogiSheets React application.
+ */
+import type { SelectedData, SheetInfo, CellLayout } from "logisheets-web";
+import type { Grid, EngineConfig } from "$types/index";
+import type { ContextMenuItem, ContextMenuContext } from "../components/contextMenuTypes";
+/**
+ * Props for the React Spreadsheet component adapter.
+ * These mirror the Svelte component props but follow React conventions.
+ */
+export interface SpreadsheetAdapterProps {
+    /** Currently selected data */
+    selectedData?: SelectedData;
+    /** Active sheet index */
+    activeSheet?: number;
+    /** Cell layouts for custom rendering */
+    cellLayouts?: CellLayout[];
+    /** Engine configuration */
+    config?: Partial<EngineConfig>;
+    /** Show sheet tabs at bottom */
+    showSheetTabs?: boolean;
+    /** Show scrollbars */
+    showScrollbars?: boolean;
+    /** Custom context menu items */
+    contextMenuItems?: ContextMenuItem[];
+    /** Callback when selection changes */
+    onSelectedDataChange?: (data: SelectedData) => void;
+    /** Callback when active sheet changes */
+    onActiveSheetChange?: (sheet: number) => void;
+    /** Callback when grid updates */
+    onGridChange?: (grid: Grid | null) => void;
+    /** Callback when sheets list changes */
+    onSheetsChange?: (sheets: readonly SheetInfo[]) => void;
+    /** Callback when context menu item is clicked */
+    onContextMenuItemClick?: (item: ContextMenuItem, context: ContextMenuContext | null) => void;
+}
+/**
+ * LogiSheets-compatible props that follow the existing LogiSheets naming conventions.
+ * Use this interface when migrating from LogiSheets Canvas component.
+ */
+export interface CanvasAdapterProps {
+    selectedData: SelectedData;
+    selectedData$: (e: SelectedData) => void;
+    activeSheet: number;
+    activeSheet$: (s: number) => void;
+    selectedDataContentChanged$: (e: object) => void;
+    grid: Grid | null;
+    setGrid: (grid: Grid | null) => void;
+    cellLayouts: CellLayout[];
+}
+/**
+ * Convert LogiSheets-style props to engine adapter props.
+ * This helps when migrating from the existing LogiSheets Canvas component.
+ */
+export declare function convertCanvasPropsToAdapterProps(props: CanvasAdapterProps): SpreadsheetAdapterProps;
+/**
+ * Hook configuration for creating a React-integrated spreadsheet instance.
+ * This can be used with custom React hooks to manage spreadsheet state.
+ */
+export interface UseSpreadsheetConfig {
+    /** Initial selected data */
+    initialSelectedData?: SelectedData;
+    /** Initial active sheet index */
+    initialActiveSheet?: number;
+    /** Engine configuration */
+    config?: Partial<EngineConfig>;
+}
+/**
+ * Return type for useSpreadsheet hook (to be implemented in React wrapper package)
+ */
+export interface UseSpreadsheetReturn {
+    /** Current selected data */
+    selectedData: SelectedData;
+    /** Set selected data */
+    setSelectedData: (data: SelectedData) => void;
+    /** Current active sheet */
+    activeSheet: number;
+    /** Set active sheet */
+    setActiveSheet: (sheet: number) => void;
+    /** Current grid */
+    grid: Grid | null;
+    /** Current sheets list */
+    sheets: readonly SheetInfo[];
+    /** Props to spread on the Spreadsheet component */
+    spreadsheetProps: SpreadsheetAdapterProps;
+}

package/dist/types/lib/block/enum_set_manager.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Represents a single variant in an enum
+ */
+export interface EnumVariant {
+    /** Unique identifier for this variant */
+    id: string;
+    /** The string value of this variant (must be unique within the enum) */
+    value: string;
+    /** Color associated with this variant (hex color code) */
+    color: string;
+}
+/**
+ * Represents a complete enum definition
+ */
+export interface EnumInfo {
+    /** Unique identifier for this enum */
+    id: string;
+    /** Name of the enum */
+    name: string;
+    /** Description of the enum */
+    description?: string;
+    /** List of variants in this enum */
+    variants: EnumVariant[];
+}
+/**
+ * Manager for all enum sets in the application
+ * Ensures uniqueness of variant values within each enum
+ */
+export declare class EnumSetManager {
+    constructor();
+    private enums;
+    /**
+     * Get an enum by its ID
+     * @param id The unique identifier of the enum
+     * @returns The EnumInfo if found, undefined otherwise
+     */
+    get(id: string): EnumInfo | undefined;
+    /**
+     * Get all registered enums
+     * @returns Array of all EnumInfo objects
+     */
+    getAll(): EnumInfo[];
+    /**
+     * Check if an enum exists
+     * @param id The unique identifier of the enum
+     * @returns true if the enum exists, false otherwise
+     */
+    has(id: string): boolean;
+    /**
+     * Register a new enum or update an existing one
+     * @param id The unique identifier for this enum
+     * @param name The name of the enum
+     * @param variants The list of variants
+     * @param description Optional description
+     * @throws Error if variant values are not unique within the enum
+     * @returns The created/updated EnumInfo
+     */
+    set(id: string, name: string, variants: EnumVariant[], description?: string): EnumInfo;
+    /**
+     * Update an existing enum
+     * @param id The unique identifier of the enum
+     */
+    update(id: string, info: EnumInfo): EnumInfo;
+    /**
+     * Add a variant to an existing enum
+     * @param enumId The ID of the enum
+     * @param variant The variant to add
+     * @throws Error if enum doesn't exist or variant value already exists
+     * @returns The updated EnumInfo
+     */
+    addVariant(enumId: string, variant: EnumVariant): EnumInfo;
+    /**
+     * Remove a variant from an enum
+     * @param enumId The ID of the enum
+     * @param variantId The ID of the variant to remove
+     * @throws Error if enum doesn't exist
+     * @returns The updated EnumInfo
+     */
+    removeVariant(enumId: string, variantId: string): EnumInfo;
+    /**
+     * Delete an enum
+     * @param id The unique identifier of the enum to delete
+     * @returns true if the enum was deleted, false if it didn't exist
+     */
+    delete(id: string): boolean;
+    /**
+     * Clear all enums
+     */
+    clear(): void;
+    /**
+     * Get the number of registered enums
+     * @returns The count of enums
+     */
+    count(): number;
+    /**
+     * Find enums by name (case-insensitive partial match)
+     * @param query The search query
+     * @returns Array of matching EnumInfo objects
+     */
+    search(query: string): EnumInfo[];
+    /**
+     * Validate that all variant values are unique within the list
+     * @param variants The list of variants to validate
+     * @throws Error if duplicate values are found
+     */
+    private validateVariantUniqueness;
+    /**
+     * Export all enums as JSON
+     * @returns JSON string representation of all enums
+     */
+    toJSON(): string;
+    /**
+     * Import enums from JSON
+     * @param json JSON string representation of enums
+     * @throws Error if JSON is invalid
+     */
+    fromJSON(json: string): void;
+}

package/dist/types/lib/block/field_manager.d.ts

@@ -0,0 +1,236 @@
+/**
+ * Represents a field's type and configuration
+ */
+export type FieldTypeEnum = {
+    type: "enum";
+    id: string;
+} | {
+    type: "multiSelect";
+    id: string;
+} | {
+    type: "datetime";
+    formatter: string;
+} | {
+    type: "boolean";
+} | {
+    type: "string";
+    validation: string;
+} | {
+    type: "number";
+    validation: string;
+    formatter: string;
+} | {
+    type: "image";
+}
+/**
+ * Reference to another block's field. The dropdown options are pulled
+ * dynamically from the target block at render time. The validation
+ * formula carries an existence check so dangling refs surface as a
+ * warning indicator.
+ */
+ | {
+    type: "fieldRef";
+    sheetId: number;
+    blockId: number;
+    fieldName: string;
+    validation: string;
+}
+/**
+ * Reference to another block's field, picking multiple values. Storage
+ * is a comma-separated string in the cell. Renderer parses the string
+ * into a list and shows a multi-select dropdown sourced from the same
+ * (sheetId, blockId, fieldName) target as `fieldRef`. v1 does not
+ * auto-inject existence validation — dangling refs are not surfaced.
+ */
+ | {
+    type: "multiSelectRef";
+    sheetId: number;
+    blockId: number;
+    fieldName: string;
+    validation: string;
+};
+/**
+ * Represents a complete field definition
+ */
+export interface FieldInfo {
+    /** Unique identifier for this field (cannot be changed or reused) */
+    id: string;
+    /** Sheet ID this field belongs to */
+    sheetId: number;
+    /** Block ID this field belongs to */
+    blockId: number;
+    /**
+     * Block-schema ref name (the `refName` passed to `bindFormSchema`).
+     * Optional because fields may be created before the schema is bound;
+     * the host fills this in once the bind happens.
+     */
+    refName?: string;
+    /** Name of the field */
+    name: string;
+    /** Type of the field */
+    type: FieldTypeEnum;
+    /** Optional description */
+    description?: string;
+    /** Whether this field is required */
+    required: boolean;
+    /**
+     * Whether this field's values must be unique within the block.
+     * Used by the composer to enumerate eligible target fields when
+     * configuring a `fieldRef` cell. The actual duplicate check is
+     * enforced by an auto-injected COUNTIF validation formula.
+     */
+    unique: boolean;
+    /** Default value */
+    defaultValue?: string;
+    /**
+     * Optional value-formula template for this field. When set, every row
+     * of the block carries a derived formula in this column rather than a
+     * free-form user value. Placeholders:
+     *
+     *   `#FIELD("name")` → absolute A1 reference to the same row's cell
+     *                       in the named sibling field.
+     *   `#KEY`            → this row's key value, quoted as a string
+     *                       literal.
+     *
+     * Templated fields are constraints, not defaults — `userEditable` is
+     * forced to `false` by {@link FieldManager.create} when a template is
+     * present (the UI offers no edit affordance). Use
+     * {@link expandFieldFormula} to substitute the placeholders against a
+     * concrete row before writing into a cell.
+     */
+    valueFormula?: string;
+    /**
+     * Field-level write permission for the player (non-owner caller).
+     * Two shapes:
+     *
+     *   - `boolean` — static decision evaluated synchronously by the host
+     *     UI guard. `false` permanently locks the field's cells against
+     *     player edits; `true` always allows.
+     *   - `string` — a formula evaluated per cell. Same placeholders as
+     *     `valueFormula` (`#FIELD("name")`, `#KEY`) plus `#PLACEHOLDER`
+     *     (the cell being checked). At widget mount the host installs
+     *     this formula onto a per-cell `UserEditable` shadow ephemeral
+     *     (via `getShadowCellId({kind: 'userEditable'})` +
+     *     `EphemeralCellInput`) — same machinery validation cells use —
+     *     then subscribes to the shadow value and toggles the widget's
+     *     read-only state accordingly.
+     *   - `undefined` — fall back to block-owner rules (default behavior):
+     *     only the owner of the block can write; if the block has no
+     *     owner, anyone can write.
+     *
+     * The engine itself doesn't enforce this flag — boolean is host-UI
+     * only, and the string path piggy-backs on the engine's generic
+     * ephemeral-cell evaluator without any schema-side knowledge of
+     * "user editable" as a concept. The block owner is unaffected by
+     * either form; owners always retain write access.
+     */
+    userEditable?: boolean | string;
+}
+/**
+ * Manager for all fields in the application
+ * Ensures field IDs are unique and immutable
+ */
+export declare class FieldManager {
+    private fields;
+    private _counter;
+    /**
+     * Generate a unique field ID
+     * @returns A unique field ID that will never be reused
+     */
+    private generateFieldId;
+    /**
+     * Create a new field
+     * @param sheetId The sheet ID
+     * @param blockId The block ID
+     * @param fieldData Field configuration (without id)
+     * @returns The created FieldInfo with generated ID
+     */
+    create(sheetId: number, blockId: number, fieldData: Omit<FieldInfo, "id" | "sheetId" | "blockId">): FieldInfo;
+    /**
+     * Get a field by its composite key
+     * @param fieldId The field ID
+     * @returns The FieldInfo if found, undefined otherwise
+     */
+    get(fieldId: string): FieldInfo | undefined;
+    /**
+     * Get all fields for a specific sheet and block
+     * @param sheetId The sheet ID
+     * @param blockId The block ID
+     * @returns Array of all FieldInfo objects for the block
+     */
+    getByBlock(sheetId: number, blockId: number): FieldInfo[];
+    /**
+     * Get all fields for a specific sheet
+     * @param sheetId The sheet ID
+     * @returns Array of all FieldInfo objects for the sheet
+     */
+    getBySheet(sheetId: number): FieldInfo[];
+    /**
+     * Get all fields
+     * @returns Array of all FieldInfo objects
+     */
+    getAll(): FieldInfo[];
+    /**
+     * Check if a field exists
+     * @param fieldId The field ID
+     * @returns true if the field exists, false otherwise
+     */
+    has(fieldId: string): boolean;
+    /**
+     * Update a field (ID cannot be changed)
+     * @param fieldId The field ID
+     * @param updates Partial field updates
+     * @returns The updated FieldInfo, or undefined if field not found
+     * @throws Error if attempting to change the field ID
+     */
+    update(fieldId: string, updates: Partial<Omit<FieldInfo, "id" | "sheetId" | "blockId">>): FieldInfo | undefined;
+    /**
+     * Set the schema ref-name on every field of a block. Call this right
+     * after the corresponding `bindFormSchema` payload — the host knows
+     * the refName at bind time, the field manager doesn't, so we stamp it
+     * onto every field belonging to the block.
+     */
+    setBlockRefName(sheetId: number, blockId: number, refName: string): void;
+    /**
+     * Delete a field
+     * @param fieldId The field ID
+     * @returns true if the field was deleted, false if it didn't exist
+     * @note The field ID will never be reused even after deletion
+     */
+    delete(fieldId: string): boolean;
+    /**
+     * Delete all fields for a specific block
+     * @param sheetId The sheet ID
+     * @param blockId The block ID
+     * @returns Number of fields deleted
+     */
+    deleteBlock(sheetId: number, blockId: number): number;
+    /**
+     * Delete all fields for a specific sheet
+     * @param sheetId The sheet ID
+     * @returns Number of fields deleted
+     */
+    deleteSheet(sheetId: number): number;
+    /**
+     * Clear all fields
+     * @note Field IDs remain reserved to prevent reuse
+     */
+    clear(): void;
+    /**
+     * Get the total number of fields
+     * @returns The count of fields
+     */
+    count(): number;
+    /**
+     * Search fields by name (case-insensitive partial match)
+     * @param query The search query
+     * @returns Array of matching FieldInfo objects
+     */
+    search(query: string): FieldInfo[];
+    /**
+     * Import fields from JSON
+     * @param json JSON string representation of fields
+     * @throws Error if JSON is invalid
+     */
+    fromJSON(json: string): void;
+}

package/dist/types/lib/block/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Block management module - handles field definitions and enum sets for blocks.
+ */
+export { BlockManager, LOGISHEETS_BUILTIN_CRAFT_ID, FIELD_AND_VALIDATION_TAG, } from "./manager";
+export { EnumSetManager, type EnumInfo, type EnumVariant, } from "./enum_set_manager";
+export { FieldManager, type FieldInfo, type FieldTypeEnum, } from "./field_manager";
+export { expandFieldFormula, colIdxToLetters } from "./value_formula";

package/dist/types/lib/block/manager.d.ts

@@ -0,0 +1,25 @@
+/**
+ * BlockManager - manages block fields and enum sets for the spreadsheet engine.
+ * This is used to define custom field types and validations for blocks.
+ */
+import type { BlockField } from "logisheets-web";
+import { EnumSetManager } from "./enum_set_manager";
+import { FieldManager } from "./field_manager";
+import type { WorkbookClient } from "../clients/workbook";
+export declare const LOGISHEETS_BUILTIN_CRAFT_ID = "logisheets";
+export declare const FIELD_AND_VALIDATION_TAG = 80;
+/**
+ * BlockManager is used to load and manage block-related data,
+ * including field definitions and enum sets.
+ *
+ * Block IDs, block ranges and craft URLs are supposed to be stored in the workbook file.
+ * And when the application starts, it will fetch the craft manifest from the URL, register it and bind the blocks.
+ */
+export declare class BlockManager {
+    private readonly _workbookClient?;
+    constructor(_workbookClient?: WorkbookClient | undefined);
+    enumSetManager: EnumSetManager;
+    fieldManager: FieldManager;
+    getPersistentData(blockFields: readonly BlockField[]): string;
+    parseAppData(data: string): void;
+}

package/dist/types/lib/block/value_formula.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Field-level value-formula substitution.
+ *
+ * A field carries a `valueFormula` template on its FieldInfo. Templates
+ * use two placeholders:
+ *
+ *   `#FIELD("name")` → absolute A1 reference to the same row's cell in
+ *                       the sibling field named `name`.
+ *   `#KEY`            → the row's key value, quoted as a string literal.
+ *
+ * Substitution is host-side: callers (block-composer's row-add path,
+ * block-interface's +Add Row handler, or any craft programmatically
+ * inserting rows) call {@link expandFieldFormula} to produce a concrete
+ * Excel formula, then write it via `blockInput` / `cellInput`.
+ *
+ * The engine itself sees only the resulting plain formula — A1 refs and
+ * BLOCKREF calls behave normally. Constraint enforcement (templated
+ * fields are uneditable) is handled by FieldManager + the block-interface
+ * widgets.
+ */
+/** 0-based column index → Excel column letters: 0→A, 25→Z, 26→AA, … */
+export declare function colIdxToLetters(col: number): string;
+/**
+ * Substitute `#FIELD("name")` and `#KEY` placeholders in `template`
+ * against a concrete row of a block.
+ *
+ * - `fields` is the ordered list of field names occupying the block's
+ *   columns (left-to-right). The Nth entry corresponds to absolute col
+ *   `colStart + N`.
+ * - `sheetRowZero` is the 0-based absolute sheet row of this row.
+ * - `colStart` is the 0-based absolute sheet col of the block's first
+ *   field (typically `BlockInfo.colStart`).
+ * - `key` is the row's key value as a string. The host substitutes it
+ *   as a literal (with `"` doubled per Excel string escaping rules).
+ *   Passing `""` is allowed when the key isn't known yet — `#KEY`
+ *   becomes the empty string literal `""`.
+ *
+ * Throws if the template references a `#FIELD("X")` where `X` isn't in
+ * `fields`.
+ */
+export declare function expandFieldFormula(params: {
+    template: string;
+    fields: readonly string[];
+    sheetRowZero: number;
+    colStart: number;
+    key: string;
+}): string;

package/dist/types/lib/clients/index.d.ts

@@ -0,0 +1,3 @@
+export { WorkbookClient } from "./workbook";
+export { OffscreenClient } from "./offscreen";
+export { DataService } from "./service";

package/dist/types/lib/clients/offscreen.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Offscreen Client - communicates with the worker for rendering operations.
+ */
+import type { Grid, AppropriateHeight } from "$types/index";
+import type { ErrorMessage } from "logisheets-web";
+type Resp<T> = Promise<T | ErrorMessage>;
+export declare class OffscreenClient {
+    private _worker;
+    private _resolvers;
+    private _rid;
+    constructor(worker: Worker);
+    init(canvas: OffscreenCanvas, dpr: number): Resp<void>;
+    render(sheetId: number, anchorX: number, anchorY: number): Resp<Grid>;
+    getAppropriateHeights(sheetId: number, anchorX: number, anchorY: number): Resp<readonly AppropriateHeight[]>;
+    resize(width: number, height: number, dpr: number): Resp<Grid>;
+    setLicense(apiKey: string, domain: string): Resp<{
+        valid: boolean;
+        reason?: string;
+    }>;
+    clearLicense(): void;
+    private _call;
+}
+export {};

package/dist/types/lib/clients/service.d.ts

@@ -0,0 +1,48 @@
+/**
+ * DataService - main service for interacting with the spreadsheet engine.
+ * Combines WorkbookClient and OffscreenClient functionality.
+ */
+import type { SheetInfo, SheetDimension, MergeCell, Transaction, ErrorMessage } from "logisheets-web";
+import { Cell } from "logisheets-web";
+import { WorkbookClient } from "./workbook";
+import type { Grid } from "$types/index";
+type Resp<T> = Promise<T | ErrorMessage>;
+export declare class DataService {
+    private _workbook;
+    private _offscreen;
+    private _sheetInfos;
+    private _sheetIdx;
+    private _sheetId;
+    private _sheetUpdateCallback;
+    private _lastRender;
+    constructor(worker: Worker);
+    private _init;
+    render(sheetId: number, anchorX: number, anchorY: number): Resp<Grid>;
+    resize(width: number, height: number, dpr: number): Resp<Grid>;
+    initOffscreen(canvas: OffscreenCanvas): Resp<void>;
+    setLicense(apiKey: string): Resp<{
+        valid: boolean;
+        reason?: string;
+    }>;
+    clearLicense(): void;
+    loadWorkbook(buf: Uint8Array, name: string): Resp<Grid>;
+    setCurrentSheetIdx(idx: number): void;
+    getCurrentSheetIdx(): number;
+    getCurrentSheetId(): number;
+    getCurrentSheetName(): string;
+    getCacheAllSheetInfo(): readonly SheetInfo[];
+    getSheetDimension(sheetIdx: number): Resp<SheetDimension>;
+    getCellInfo(sheetIdx: number, row: number, col: number): Resp<Cell>;
+    getMergedCells(sheetIdx: number, targetStartRow: number, targetStartCol: number, targetEndRow: number, targetEndCol: number): Resp<readonly MergeCell[]>;
+    getAvailableBlockId(sheetIdx: number): Resp<number>;
+    checkFormula(formula: string): Promise<boolean>;
+    handleTransaction(transaction: Transaction, temp?: boolean): Resp<void>;
+    handleTransactionAndAdjustRowHeights(transaction: Transaction, onlyIncrease?: boolean, fromRowIdx?: number, toRowIdx?: number): Resp<void>;
+    undo(): Resp<void>;
+    redo(): Resp<void>;
+    getWorkbook(): WorkbookClient;
+    registerSheetUpdatedCallback(f: () => void): void;
+    registerCellUpdatedCallback(f: () => void, callbackId?: number): void;
+    registerHeaderUpdatedCallback(f: (sheetIdxes: readonly number[]) => void): void;
+}
+export {};