logisheets-formula-editor 1.15.0 → 1.16.0

package/dist/core.js

@@ -13410,7 +13410,9 @@ function kd(s) {
     [!0, !0],
     [!1, !0],
     [!0, !1]
-  ][(o + 1) % 4], h = n.map((c) => `${l ? "$" : ""}${c.col}${a ? "$" : ""}${c.row}`).join(":");
+  ][(o + 1) % 4], h = n.map(
+    (c) => `${l ? "$" : ""}${c.col}${a ? "$" : ""}${c.row}`
+  ).join(":");
   return t + h;
 }
 let Un = null, Ni = null;
@@ -13751,6 +13753,8 @@ function Nd(s, e) {
       ]);
     }, w = en.of([
       {
+        // Deleting the opener of an empty pair (e.g. the `(` of an
+        // autocompleted `SUM()`) also removes its closer.
         key: "Backspace",
         run: (b) => {
           const { state: k } = b, { from: S, to: D } = k.selection.main;

package/dist/inline.js

@@ -46,10 +46,15 @@ function Ne(U) {
   }
   function G() {
     if (q(), !a) return;
-    const e = Ee(k, a, X(), {
-      originX: w.x,
-      originY: w.y
-    });
+    const e = Ee(
+      k,
+      a,
+      X(),
+      {
+        originX: w.x,
+        originY: w.y
+      }
+    );
     for (const i of e) {
       const o = document.createElement("div");
       o.style.cssText = `position:absolute;pointer-events:none;opacity:0.3;z-index:0;left:${i.x}px;top:${i.y}px;width:${i.width}px;height:${i.height}px;background-color:${se(i.colorIndex)};`, T.appendChild(o), M.push(o);
@@ -73,7 +78,10 @@ function Ne(U) {
       f.startPos,
       f.startPos + f.text.length,
       e
-    ) : c.insertText(e), f = { text: e, startPos: (f == null ? void 0 : f.startPos) ?? i };
+    ) : c.insertText(e), f = {
+      text: e,
+      startPos: (f == null ? void 0 : f.startPos) ?? i
+    };
   }
   function D(e, i) {
     if (!t) return;
@@ -90,7 +98,12 @@ function Ne(U) {
   }
   async function ge(e, i) {
     if (!t) return;
-    const o = y(), l = P ?? { row: t.row, col: t.col }, u = { sheetIdx: o, rowIdx: l.row, colIdx: l.col, direction: e }, x = W.getWorkbook(), d = i ? await x.getDataBoundary(u) : await x.getNextVisibleCell(u);
+    const o = y(), l = P ?? { row: t.row, col: t.col }, u = {
+      sheetIdx: o,
+      rowIdx: l.row,
+      colIdx: l.col,
+      direction: e
+    }, x = W.getWorkbook(), d = i ? await x.getDataBoundary(u) : await x.getNextVisibleCell(u);
     if (!d || ve(d)) return;
     const { x: S, y: Q } = d;
     P = { row: Q, col: S };
@@ -138,7 +151,13 @@ function Ne(U) {
       defaultWidth: 100,
       defaultHeight: 25
     });
-    h = o, t = { sheetName: X(), sheetIdx: u, row: e, col: i, position: x }, g = !0, E == null || E(!0), r = document.createElement("div"), r.className = "logisheets-inline-cell-editor", r.style.cssText = "position:absolute;display:flex;align-items:center;box-sizing:border-box;z-index:1000;background:#fff;overflow:hidden;border:1px solid #4a90d9;box-shadow:0 1px 4px rgba(0,0,0,0.18);", T.appendChild(r);
+    h = o, t = {
+      sheetName: X(),
+      sheetIdx: u,
+      row: e,
+      col: i,
+      position: x
+    }, g = !0, E == null || E(!0), r = document.createElement("div"), r.className = "logisheets-inline-cell-editor", r.style.cssText = "position:absolute;display:flex;align-items:center;box-sizing:border-box;z-index:1000;background:#fff;overflow:hidden;border:1px solid #4a90d9;box-shadow:0 1px 4px rgba(0,0,0,0.18);", T.appendChild(r);
     const d = document.createElement("div");
     d.style.width = "100%", d.style.boxSizing = "border-box", r.appendChild(d), K(), V(o), c = me(d, {
       getDisplayUnits: B.getDisplayUnits,

package/dist/src/lib/FormulaEditor.d.ts

@@ -1,5 +1,11 @@
 import { EditorView } from '@codemirror/view';
 import { FormulaEditorProps } from './types';
+/**
+ * Imperative API exposed through `ref` — a subset of the core's
+ * `FormulaEditorHandle` (no `updateOptions` / `destroy`; props and unmount
+ * cover those). Positions are UTF-16 offsets into the whole text, leading '='
+ * included. Calls before mount or after unmount are no-ops.
+ */
 export interface FormulaEditorRef {
     focus: () => void;
     blur: () => void;
@@ -13,5 +19,9 @@ export interface FormulaEditorRef {
     getCursorPosition: () => number;
     getView: () => EditorView | null;
 }
+/**
+ * React formula editor. Renders a `<div>` host and mounts the core editor into
+ * it once; see `FormulaEditorProps` for which props are live.
+ */
 export declare const FormulaEditor: import('react').ForwardRefExoticComponent<FormulaEditorProps & import('react').RefAttributes<FormulaEditorRef>>;
 //# sourceMappingURL=FormulaEditor.d.ts.map

package/dist/src/lib/FormulaEditor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FormulaEditor.d.ts","sourceRoot":"","sources":["../../../src/lib/FormulaEditor.tsx"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAA;AAEhD,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,SAAS,CAAA;AAE/C,MAAM,WAAW,gBAAgB;IAC7B,KAAK,EAAE,MAAM,IAAI,CAAA;IACjB,IAAI,EAAE,MAAM,IAAI,CAAA;IAChB,QAAQ,EAAE,MAAM,MAAM,CAAA;IACtB,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACjC,6CAA6C;IAC7C,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAClC,uEAAuE;IACvE,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAC9D,kCAAkC;IAClC,iBAAiB,EAAE,MAAM,MAAM,CAAA;IAC/B,OAAO,EAAE,MAAM,UAAU,GAAG,IAAI,CAAA;CACnC;AAED,eAAO,MAAM,aAAa,iHAgEzB,CAAA"}
+{"version":3,"file":"FormulaEditor.d.ts","sourceRoot":"","sources":["../../../src/lib/FormulaEditor.tsx"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAA;AAEhD,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,SAAS,CAAA;AAE/C;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC7B,KAAK,EAAE,MAAM,IAAI,CAAA;IACjB,IAAI,EAAE,MAAM,IAAI,CAAA;IAChB,QAAQ,EAAE,MAAM,MAAM,CAAA;IACtB,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACjC,6CAA6C;IAC7C,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAClC,uEAAuE;IACvE,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAC9D,kCAAkC;IAClC,iBAAiB,EAAE,MAAM,MAAM,CAAA;IAC/B,OAAO,EAAE,MAAM,UAAU,GAAG,IAAI,CAAA;CACnC;AAED;;;GAGG;AACH,eAAO,MAAM,aAAa,iHAgEzB,CAAA"}

package/dist/src/lib/core.d.ts

@@ -9,6 +9,17 @@
  *   const editor = createFormulaEditor(el, { getDisplayUnits, ... })
  *
  * The React `<FormulaEditor>` (the package root) is a thin wrapper over this.
+ *
+ * Main exports: `createFormulaEditor` + its option / handle types, the
+ * bundled `builtinFormulaFunctions`, the wire types shared with the engine
+ * (`FormulaDisplayInfo`, `TokenUnit`, `CellRef`, ...) and small utils.
+ *
+ * The editor never tokenizes on its own: the host must supply
+ * `getDisplayUnits` (usually via `createEngineFormulaSource` from `./engine`).
+ * Without a `formulaFunctions` list, autocomplete and signature help are
+ * silent — pass `builtinFormulaFunctions` for the default set. Hosts in this
+ * repo: the root app's edit bar (via the React root) and the `/inline`
+ * in-cell controller used alongside `logisheets-engine`.
  */
 export { createFormulaEditor } from './editor';
 export type { FormulaEditorHandle, FormulaEditorOptions } from './editor';

package/dist/src/lib/core.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../../src/lib/core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAC,mBAAmB,EAAC,MAAM,UAAU,CAAA;AAC5C,YAAY,EAAC,mBAAmB,EAAE,oBAAoB,EAAC,MAAM,UAAU,CAAA;AAGvE,OAAO,EAAC,uBAAuB,EAAC,MAAM,aAAa,CAAA;AAEnD,cAAc,SAAS,CAAA;AACvB,cAAc,SAAS,CAAA"}
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../../src/lib/core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAC,mBAAmB,EAAC,MAAM,UAAU,CAAA;AAC5C,YAAY,EAAC,mBAAmB,EAAE,oBAAoB,EAAC,MAAM,UAAU,CAAA;AAGvE,OAAO,EAAC,uBAAuB,EAAC,MAAM,aAAa,CAAA;AAEnD,cAAc,SAAS,CAAA;AACvB,cAAc,SAAS,CAAA"}

package/dist/src/lib/editor.d.ts

@@ -3,18 +3,35 @@ import { FormulaEditorConfig, FormulaFunction, GetDisplayUnitsFunc } from './typ
 /**
  * Options for {@link createFormulaEditor}. These mirror the React component's
  * props minus the React-only bits — the React `style` prop maps to `style`
- * here (applied to the host element).
+ * here (applied to the host element) — plus the core-only `onArrowKey`.
+ *
+ * Text need not be a formula: plain text is edited without highlighting,
+ * autocomplete or point mode. Callbacks receive the full document text,
+ * including any leading '='.
  */
 export interface FormulaEditorOptions {
-    /** Initial value (with leading '='). */
+    /**
+     * Initial value; later changes pushed via `updateOptions({value})` are
+     * written into the document (controlled mode).
+     */
     value?: string;
     /** Initial value when `value` is not given. */
     defaultValue?: string;
     /** Where to place the cursor on creation (default: 'end'). */
     initialCursorPosition?: 'start' | 'end';
+    /**
+     * Fires on every document change — typing, `setValue`, `insertText`,
+     * `replaceRange` and controlled `value` updates alike.
+     */
     onChange?: (value: string) => void;
+    /** Fires when the editable content loses focus; typical commit point. */
     onBlur?: (value: string) => void;
+    /**
+     * Plain Enter while no autocomplete list is open (Enter accepts the
+     * completion instead). Enter never inserts a newline; Alt+Enter does.
+     */
     onSubmit?: (value: string) => void;
+    /** Escape. The editor does not revert the text itself. */
     onCancel?: () => void;
     /**
      * Point-mode: called on an arrow / Ctrl+Arrow key while the caret sits where
@@ -30,40 +47,84 @@ export interface FormulaEditorOptions {
     }) => boolean;
     /** Fetch token / cell-ref info from the host (required). */
     getDisplayUnits: GetDisplayUnitsFunc;
-    /** Functions offered by autocomplete + signature help. */
+    /**
+     * Functions offered by autocomplete + signature help. Defaults to an EMPTY
+     * list (no suggestions) — pass `builtinFormulaFunctions` for the bundled
+     * set.
+     */
     formulaFunctions?: FormulaFunction[];
-    /** Current sheet name (for local cell-ref coloring). */
+    /**
+     * Current sheet name (for local cell-ref coloring). Defaults to '', so
+     * only refs with no sheet prefix count as local.
+     */
     sheetName?: string;
+    /** Merged over the defaults; see `updateOptions` for live changes. */
     config?: FormulaEditorConfig;
-    /** Extra class(es) added to the host element. */
+    /**
+     * Extra class(es) added to the host element. Applied at creation and on
+     * a config-triggered rebuild only; classes are never removed.
+     */
     className?: string;
-    /** Extra inline styles merged onto the host element. */
+    /** Extra inline styles merged onto the host element (same timing). */
     style?: Partial<CSSStyleDeclaration>;
 }
-/** Imperative handle returned by {@link createFormulaEditor}. */
+/**
+ * Imperative handle returned by {@link createFormulaEditor}.
+ *
+ * Positions are 0-based UTF-16 code-unit offsets (JS string indices) into the
+ * whole document, leading '=' included. Every text-changing method fires
+ * `onChange`. After `destroy()` the methods are no-ops (`getValue()` returns
+ * '', `getView()` null).
+ */
 export interface FormulaEditorHandle {
+    /** Focus without scrolling the page to the editor. */
     focus(): void;
     blur(): void;
     getValue(): string;
+    /** Replace the whole document. */
     setValue(value: string): void;
-    /** Insert text at the current cursor position. */
+    /** Insert text at the caret and move the caret after it. */
     insertText(text: string): void;
-    /** Replace a range — useful for swapping a previously-inserted ref. */
+    /**
+     * Replace `[from, to)` and put the caret after the new text — useful for
+     * swapping a previously-inserted ref.
+     */
     replaceRange(from: number, to: number, text: string): void;
     getCursorPosition(): number;
+    /**
+     * The underlying CodeMirror view, for advanced use. A config change
+     * replaces it, so don't hold on to it across `updateOptions`.
+     */
     getView(): EditorView | null;
     /**
      * Update live options without recreating the editor. Callback / function-
      * list / sheet-name changes apply immediately; a changed `config` rebuilds
      * the view (preserving text + cursor); a changed controlled `value` is
      * dispatched into the document.
+     *
+     * Callbacks can be cleared by passing the key with `undefined`;
+     * `getDisplayUnits` / `formulaFunctions` cannot (falsy is ignored). The
+     * rebuild on a config change drops undo history, and when it happens any
+     * `value` in the same call is ignored. A new `sheetName` takes effect at
+     * the next highlight refresh, not immediately. Do not call after
+     * `destroy()` — a config change would mount a fresh view.
      */
     updateOptions(opts: Partial<FormulaEditorOptions>): void;
+    /**
+     * Tear down the view, pending refresh timer and blur listener. Must be
+     * called when the host element goes away. The host element keeps the
+     * classes / inline styles the editor added.
+     */
     destroy(): void;
 }
 /**
  * Create a formula editor mounted into `parent`. Returns an imperative handle;
  * call `destroy()` when done.
+ *
+ * The CodeMirror view is appended to `parent`, which also gets the
+ * `formula-editor` class and sizing / border styles. `getDisplayUnits` is
+ * called immediately when the initial text is a formula. Does not throw on a failing
+ * host callback: `getDisplayUnits` errors are logged to the console.
  */
 export declare function createFormulaEditor(parent: HTMLElement, options: FormulaEditorOptions): FormulaEditorHandle;
 //# sourceMappingURL=editor.d.ts.map

package/dist/src/lib/editor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"editor.d.ts","sourceRoot":"","sources":["../../../src/lib/editor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EACH,UAAU,EAQb,MAAM,kBAAkB,CAAA;AAUzB,OAAO,KAAK,EAER,mBAAmB,EACnB,eAAe,EACf,mBAAmB,EACtB,MAAM,SAAS,CAAA;AA0YhB;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACjC,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,+CAA+C;IAC/C,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,8DAA8D;IAC9D,qBAAqB,CAAC,EAAE,OAAO,GAAG,KAAK,CAAA;IACvC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IAClC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IAChC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IAClC,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAA;IACrB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,CACT,SAAS,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,EAC3C,SAAS,EAAE;QAAC,IAAI,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAC,KACzC,OAAO,CAAA;IACZ,4DAA4D;IAC5D,eAAe,EAAE,mBAAmB,CAAA;IACpC,0DAA0D;IAC1D,gBAAgB,CAAC,EAAE,eAAe,EAAE,CAAA;IACpC,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,MAAM,CAAC,EAAE,mBAAmB,CAAA;IAC5B,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,wDAAwD;IACxD,KAAK,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAA;CACvC;AAED,iEAAiE;AACjE,MAAM,WAAW,mBAAmB;IAChC,KAAK,IAAI,IAAI,CAAA;IACb,IAAI,IAAI,IAAI,CAAA;IACZ,QAAQ,IAAI,MAAM,CAAA;IAClB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,kDAAkD;IAClD,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,uEAAuE;IACvE,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1D,iBAAiB,IAAI,MAAM,CAAA;IAC3B,OAAO,IAAI,UAAU,GAAG,IAAI,CAAA;IAC5B;;;;;OAKG;IACH,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC,oBAAoB,CAAC,GAAG,IAAI,CAAA;IACxD,OAAO,IAAI,IAAI,CAAA;CAClB;AAcD;;;GAGG;AACH,wBAAgB,mBAAmB,CAC/B,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,oBAAoB,GAC9B,mBAAmB,CAggBrB"}
+{"version":3,"file":"editor.d.ts","sourceRoot":"","sources":["../../../src/lib/editor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EACH,UAAU,EAQb,MAAM,kBAAkB,CAAA;AAUzB,OAAO,KAAK,EAER,mBAAmB,EACnB,eAAe,EACf,mBAAmB,EACtB,MAAM,SAAS,CAAA;AA0ZhB;;;;;;;;GAQG;AACH,MAAM,WAAW,oBAAoB;IACjC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,+CAA+C;IAC/C,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,8DAA8D;IAC9D,qBAAqB,CAAC,EAAE,OAAO,GAAG,KAAK,CAAA;IACvC;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IAClC,yEAAyE;IACzE,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IAChC;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IAClC,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAA;IACrB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,CACT,SAAS,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,EAC3C,SAAS,EAAE;QAAC,IAAI,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAC,KACzC,OAAO,CAAA;IACZ,4DAA4D;IAC5D,eAAe,EAAE,mBAAmB,CAAA;IACpC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,eAAe,EAAE,CAAA;IACpC;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,sEAAsE;IACtE,MAAM,CAAC,EAAE,mBAAmB,CAAA;IAC5B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,sEAAsE;IACtE,KAAK,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAA;CACvC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IAChC,sDAAsD;IACtD,KAAK,IAAI,IAAI,CAAA;IACb,IAAI,IAAI,IAAI,CAAA;IACZ,QAAQ,IAAI,MAAM,CAAA;IAClB,kCAAkC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,4DAA4D;IAC5D,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B;;;OAGG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1D,iBAAiB,IAAI,MAAM,CAAA;IAC3B;;;OAGG;IACH,OAAO,IAAI,UAAU,GAAG,IAAI,CAAA;IAC5B;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC,oBAAoB,CAAC,GAAG,IAAI,CAAA;IACxD;;;;OAIG;IACH,OAAO,IAAI,IAAI,CAAA;CAClB;AAcD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAC/B,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,oBAAoB,GAC9B,mBAAmB,CAsgBrB"}

package/dist/src/lib/engine.d.ts

@@ -1,6 +1,16 @@
 import { CellRef, FormulaFunction, GetDisplayUnitsFunc } from './types';
-/** The slice of a workbook client the source needs. */
+/**
+ * The slice of a workbook client the source needs. Only
+ * `getDisplayUnitsOfFormula` is used by {@link createEngineFormulaSource}; the
+ * two navigation methods are for the `/inline` controller's point mode. All
+ * indices are 0-based.
+ */
 export interface FormulaWorkbook {
+    /**
+     * Lex a formula body (no leading '='). Resolves to a
+     * {@link FormulaDisplayInfo} on success or an error-message object
+     * otherwise; the source tells them apart by the `tokenUnits` key.
+     */
     getDisplayUnitsOfFormula(formula: string): Promise<unknown>;
     /**
      * Point-mode arrow move: the next visible cell in a direction (skips hidden
@@ -24,9 +34,17 @@ export interface FormulaWorkbook {
 }
 /** The slice of an engine `DataService` the source needs. */
 export interface EngineFormulaServices {
+    /** Called per request, not cached, so a swapped workbook is picked up. */
     getWorkbook(): FormulaWorkbook;
+    /**
+     * Whether a formula (text as typed, including the leading '=') parses.
+     * Expected to resolve `false` rather than reject on an engine error.
+     */
     checkFormula(formula: string): Promise<boolean>;
-    /** Sheet name for a given index — used to build cross-sheet references. */
+    /**
+     * Sheet name for a 0-based sheet index — used by `/inline` to qualify
+     * cross-sheet references. Not used by {@link createEngineFormulaSource}.
+     */
     getSheetNameByIdx(idx: number): string;
 }
 export interface EngineFormulaSourceOptions {
@@ -41,7 +59,11 @@ export interface EngineFormulaSourceOptions {
      */
     onCellRefs?: (cellRefs: readonly CellRef[]) => void;
 }
-/** Props the editor consumes, derived from the engine. */
+/**
+ * Props derived from the engine. The editor itself consumes
+ * `getDisplayUnits` + `formulaFunctions`; `checkFormula` is for the host's
+ * commit path — the editor never validates on its own.
+ */
 export interface EngineFormulaSource {
     getDisplayUnits: GetDisplayUnitsFunc;
     checkFormula: (formula: string) => Promise<boolean>;
@@ -50,6 +72,12 @@ export interface EngineFormulaSource {
 /**
  * Build the editor's data props from an engine `DataService`. Spread the result
  * into `createFormulaEditor` / `<FormulaEditor>`.
+ *
+ * The returned `getDisplayUnits` never rejects: an engine error, a thrown
+ * call, or an unlexable formula all resolve `undefined` (no highlighting) and report
+ * an empty ref list to `onCellRefs`, so an overlay clears instead of showing
+ * stale highlights. `checkFormula` is passed through unchanged. Holds no
+ * resources — nothing to dispose.
  */
 export declare function createEngineFormulaSource(services: EngineFormulaServices, options?: EngineFormulaSourceOptions): EngineFormulaSource;
 //# sourceMappingURL=engine.d.ts.map

package/dist/src/lib/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/lib/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EACR,OAAO,EAEP,eAAe,EACf,mBAAmB,EACtB,MAAM,SAAS,CAAA;AAGhB,uDAAuD;AACvD,MAAM,WAAW,eAAe;IAC5B,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAC3D;;;;;OAKG;IACH,kBAAkB,CAAC,MAAM,EAAE;QACvB,QAAQ,EAAE,MAAM,CAAA;QAChB,MAAM,EAAE,MAAM,CAAA;QACd,MAAM,EAAE,MAAM,CAAA;QACd,SAAS,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;KAC9C,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IACpB,uEAAuE;IACvE,eAAe,CAAC,MAAM,EAAE;QACpB,QAAQ,EAAE,MAAM,CAAA;QAChB,MAAM,EAAE,MAAM,CAAA;QACd,MAAM,EAAE,MAAM,CAAA;QACd,SAAS,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;KAC9C,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CACvB;AAED,6DAA6D;AAC7D,MAAM,WAAW,qBAAqB;IAClC,WAAW,IAAI,eAAe,CAAA;IAC9B,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAC/C,2EAA2E;IAC3E,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;CACzC;AAED,MAAM,WAAW,0BAA0B;IACvC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,eAAe,EAAE,CAAA;IACpC;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,KAAK,IAAI,CAAA;CACtD;AAED,0DAA0D;AAC1D,MAAM,WAAW,mBAAmB;IAChC,eAAe,EAAE,mBAAmB,CAAA;IACpC,YAAY,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IACnD,gBAAgB,EAAE,eAAe,EAAE,CAAA;CACtC;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACrC,QAAQ,EAAE,qBAAqB,EAC/B,OAAO,GAAE,0BAA+B,GACzC,mBAAmB,CA8BrB"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/lib/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EACR,OAAO,EAEP,eAAe,EACf,mBAAmB,EACtB,MAAM,SAAS,CAAA;AAGhB;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC5B;;;;OAIG;IACH,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAC3D;;;;;OAKG;IACH,kBAAkB,CAAC,MAAM,EAAE;QACvB,QAAQ,EAAE,MAAM,CAAA;QAChB,MAAM,EAAE,MAAM,CAAA;QACd,MAAM,EAAE,MAAM,CAAA;QACd,SAAS,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;KAC9C,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IACpB,uEAAuE;IACvE,eAAe,CAAC,MAAM,EAAE;QACpB,QAAQ,EAAE,MAAM,CAAA;QAChB,MAAM,EAAE,MAAM,CAAA;QACd,MAAM,EAAE,MAAM,CAAA;QACd,SAAS,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;KAC9C,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CACvB;AAED,6DAA6D;AAC7D,MAAM,WAAW,qBAAqB;IAClC,0EAA0E;IAC1E,WAAW,IAAI,eAAe,CAAA;IAC9B;;;OAGG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAC/C;;;OAGG;IACH,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;CACzC;AAED,MAAM,WAAW,0BAA0B;IACvC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,eAAe,EAAE,CAAA;IACpC;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,KAAK,IAAI,CAAA;CACtD;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAChC,eAAe,EAAE,mBAAmB,CAAA;IACpC,YAAY,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IACnD,gBAAgB,EAAE,eAAe,EAAE,CAAA;CACtC;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACrC,QAAQ,EAAE,qBAAqB,EAC/B,OAAO,GAAE,0BAA+B,GACzC,mBAAmB,CA8BrB"}

package/dist/src/lib/functions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"functions.d.ts","sourceRoot":"","sources":["../../../src/lib/functions.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,SAAS,CAAA;AAG5C,eAAO,MAAM,uBAAuB,EAAE,eAAe,EACxB,CAAA"}
+{"version":3,"file":"functions.d.ts","sourceRoot":"","sources":["../../../src/lib/functions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,SAAS,CAAA;AAG5C,eAAO,MAAM,uBAAuB,EAAE,eAAe,EACxB,CAAA"}

package/dist/src/lib/index.d.ts

@@ -8,6 +8,18 @@
  * This root entry includes the React `<FormulaEditor>` component. For a
  * framework-agnostic (vanilla / Vue / Svelte / Angular) build with no React
  * dependency, import from `logisheets-formula-editor/core` instead.
+ *
+ * Main exports: `FormulaEditor` / `FormulaEditorRef` (React), everything from
+ * `./core` (`createFormulaEditor`, types, utils, `builtinFormulaFunctions`)
+ * and from `./engine` (`createEngineFormulaSource`). The in-cell editor
+ * controller is NOT re-exported here — it needs the `logisheets-engine` peer
+ * at runtime, so it lives only at the `logisheets-formula-editor/inline`
+ * subpath.
+ *
+ * Consumers in this repo: the root app's edit bar
+ * (src/components/content/edit-bar.tsx) mounts `<FormulaEditor>` wired with
+ * `createEngineFormulaSource`; the app's grid uses `/inline` for in-cell
+ * editing (src/components/spreadsheet-view/inline-cell-editor.tsx).
  */
 export { FormulaEditor } from './FormulaEditor';
 export type { FormulaEditorRef } from './FormulaEditor';

package/dist/src/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAA;AAC7C,YAAY,EAAC,gBAAgB,EAAC,MAAM,iBAAiB,CAAA;AAGrD,cAAc,QAAQ,CAAA;AAGtB,cAAc,UAAU,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAA;AAC7C,YAAY,EAAC,gBAAgB,EAAC,MAAM,iBAAiB,CAAA;AAGrD,cAAc,QAAQ,CAAA;AAItB,cAAc,UAAU,CAAA"}

package/dist/src/lib/inline.d.ts

@@ -29,7 +29,12 @@ export interface FormulaEditEntry {
  * committing, and sheet tabs / other canvases know not to steal focus.
  */
 export interface FormulaCoordinator {
+    /** Called when an edit enters formula mode (text starts with '='). */
     setActive(entry: FormulaEditEntry): void;
+    /**
+     * Called when that edit leaves formula mode or finishes. Implementations
+     * should ignore an entry that is no longer the active one.
+     */
     clear(entry: FormulaEditEntry): void;
     getActive(): FormulaEditEntry | null;
     isFormulaEditing(): boolean;
@@ -43,7 +48,11 @@ export interface InlineCellEditorOptions {
     /** Emits startEdit / selectionChange / invalidFormula for this view
      *  (an engine `Session`, or the `Engine` itself for the main view). */
     eventSource: Pick<Session, 'on' | 'off'>;
-    /** Engine data service — `getWorkbook()` + `checkFormula()`. */
+    /**
+     * Engine data service — `getWorkbook()` (display units + point-mode
+     * navigation), `checkFormula()`, and `getSheetNameByIdx()` for qualifying
+     * cross-sheet refs.
+     */
     dataService: EngineFormulaServices;
     /** Stable id of the view that owns this editor (cross-view routing). */
     viewId: string;
@@ -52,7 +61,9 @@ export interface InlineCellEditorOptions {
     /** Current sheet name (read fresh; used for local cell-ref coloring). */
     getSheetName: () => string;
     /** Commit a cell value (the host's input/ops layer). The return value is
-     *  awaited but otherwise ignored, so `void`/any Promise is fine. */
+     *  awaited but otherwise ignored, so `void`/any Promise is fine. `text` is
+     *  trimmed; a formula has already passed `checkFormula`. A rejection
+     *  propagates and leaves the editor open. */
     inputCell: (sheetIdx: number, row: number, col: number, text: string) => unknown;
     /** Move the view's selection (e.g. after committing). */
     setSelection: (data: SelectedData) => void;
@@ -79,13 +90,23 @@ export interface InlineCellEditorOptions {
     onEditRefused?: (sheetIdx: number, row: number, col: number) => void;
     /** Autocomplete / signature functions. Default: bundled built-ins. */
     formulaFunctions?: FormulaFunction[];
-    /** Maps a reference index to a CSS color. Default: built-in palette. */
+    /**
+     * Maps a reference index to a CSS color for the grid overlays. Default:
+     * built-in palette. The in-editor text highlight always uses the built-in
+     * palette, so a custom mapping makes the two disagree.
+     */
     getHighlightColor?: (index: number) => string;
     /** Base editor config (merged over the in-cell defaults). */
     editorConfig?: FormulaEditorConfig;
-    /** Called when a committed formula fails validation. */
+    /**
+     * Called when a committed formula fails validation (the editor stays
+     * open), and on the event source's `invalidFormula` event.
+     */
     onInvalidFormula?: () => void;
-    /** Reports whether an editor is open (so the canvas can avoid stealing focus). */
+    /**
+     * Reports whether an editor is open (so the canvas can avoid stealing
+     * focus). `false` is also reported by `destroy()`, open editor or not.
+     */
     onEditingChange?: (editing: boolean) => void;
     /** Bumped after commits / selection moves so dependents re-read content. */
     onContentChanged?: () => void;
@@ -101,13 +122,29 @@ export interface InlineCellEditorOptions {
         shift: boolean;
     }) => boolean;
 }
+/** Handle returned by {@link createInlineCellEditor}. */
 export interface InlineCellEditorHandle {
     /** Call on every grid change/render: repositions the editor and repaints
      *  highlights (parks the editor off-screen if its cell scrolled away). */
     setGrid(grid: Grid | null): void;
     isEditing(): boolean;
+    /** Editing and the text starts with '=' (i.e. point mode is on). */
     isEditingFormula(): boolean;
+    /**
+     * Unsubscribe from the event source and close any open edit WITHOUT
+     * committing it. Call when the view is torn down.
+     */
     destroy(): void;
 }
+/**
+ * Wire an in-cell formula editor to one engine view. Subscribes to
+ * `eventSource` immediately; nothing is mounted until a `startEdit` arrives.
+ *
+ * The host must keep the grid current via `setGrid` — `startEdit` is ignored
+ * while no grid is known, and positions / highlights go stale otherwise.
+ * Commit runs on Enter, on blur of a plain-text edit, or when the selection
+ * moves to another cell; a formula edit is not committed on blur (point mode)
+ * and a failing `checkFormula` keeps it open. Escape cancels.
+ */
 export declare function createInlineCellEditor(options: InlineCellEditorOptions): InlineCellEditorHandle;
 //# sourceMappingURL=inline.d.ts.map

package/dist/src/lib/inline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"inline.d.ts","sourceRoot":"","sources":["../../../src/lib/inline.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"inline.d.ts","sourceRoot":"","sources":["../../../src/lib/inline.ts"],"names":[],"mappings":"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"}

package/dist/src/lib/types.d.ts

@@ -1,7 +1,10 @@
 /**
  * Types for the Formula Editor
  *
- * These match the backend API types from logisheets-web
+ * The wire types (`TokenType`, `TokenUnit`, `CellRef`, `FormulaDisplayInfo`)
+ * mirror logisheets-web's generated bindings for the Rust
+ * `lexer4fmt::FormulaDisplayInfo` (crates/controller/lexer4fmt/src/fmt.rs);
+ * they are redeclared here so the package has no logisheets-web dependency.
  */
 /**
  * Token types returned by the backend lexer.
@@ -14,14 +17,23 @@ export type TokenType = 'funcName' | 'funcArg' | 'cellReference' | 'errorConstan
  */
 export interface TokenUnit {
     tokenType: TokenType;
-    /** Start index in the formula string (0-based, excludes leading '=') */
+    /**
+     * Start offset into the formula body (the text after the leading '=').
+     * 0-based UTF-8 BYTE offset, not a JS string index — it only matches the
+     * string index for ASCII text; the editor converts before use.
+     */
     start: number;
-    /** End index in the formula string (exclusive) */
+    /** End offset, exclusive; same basis as `start`. */
     end: number;
 }
 /**
  * Cell reference info parsed by the backend.
  * Used for highlighting cell references with colors.
+ *
+ * `row*` / `col*` are 0-based indices (A1 is row 0, col 0); `*2` is set only
+ * for a range. A missing row or column means that part was not written (e.g.
+ * a whole-column `A:A`). Sheet / workbook names are as written, without the
+ * surrounding quotes; `sheet2` is set only for a 3D `Sheet1:Sheet2!` ref.
  */
 export interface CellRef {
     workbook?: string;
@@ -35,6 +47,9 @@ export interface CellRef {
 /**
  * The complete display info returned by the backend for a formula.
  * This is what the editor receives from `getDisplayUnitsOfFormula`.
+ *
+ * Invariant: `cellRefs[i]` belongs to the i-th `cellReference` token in
+ * `tokenUnits` (same order), which is how highlight colors stay paired.
  */
 export interface FormulaDisplayInfo {
     cellRefs: readonly CellRef[];
@@ -42,19 +57,28 @@ export interface FormulaDisplayInfo {
 }
 /**
  * Function to fetch formula display info from backend.
- * The editor calls this whenever the text changes.
+ * The editor calls this on creation and ~100 ms after the last edit
+ * (debounced), only while the text is a formula (see `isFormula`).
+ *
+ * A rejection is caught and logged, and the previous highlighting is kept;
+ * resolving `undefined` clears it. Responses are applied in completion order,
+ * so an implementation should not let a slow call outlive a newer one.
  *
  * @param formula - The formula text (with leading '=' stripped)
  * @returns Promise resolving to FormulaDisplayInfo or undefined if not a formula
  */
 export type GetDisplayUnitsFunc = (formula: string) => Promise<FormulaDisplayInfo | undefined>;
 /**
- * A formula function definition for autocomplete.
+ * A formula function definition for autocomplete and signature help.
+ * Names are matched case-insensitively against the typed function name.
  */
 export interface FormulaFunction {
     /** Function name, e.g. "SUM" */
     name: string;
-    /** Description of what the function does */
+    /**
+     * Description of what the function does — shown verbatim, so pass
+     * already-localized text (the editor does no i18n lookup).
+     */
     description: string;
     /** Function arguments */
     args: FormulaArg[];
@@ -71,7 +95,10 @@ export interface FormulaFunction {
 export interface FormulaArg {
     argName: string;
     description: string;
-    /** If true, this argument can repeat */
+    /**
+     * If true, this argument and the ones after it repeat (signature help
+     * shows `name, name1, name2, ...`).
+     */
     startRepeated?: boolean;
 }
 /**
@@ -121,6 +148,11 @@ export interface FormulaEditorConfig {
 }
 /**
  * Props for the FormulaEditor component.
+ *
+ * Every prop except `defaultValue`, `initialCursorPosition`, `className` and
+ * `style` is re-synced on each render; those four are read once at mount.
+ * Point-mode arrow handling (`onArrowKey`) is only exposed by the vanilla
+ * `createFormulaEditor`.
  */
 export interface FormulaEditorProps {
     /** Current value (controlled) */
@@ -129,11 +161,18 @@ export interface FormulaEditorProps {
     defaultValue?: string;
     /** Initial cursor position: 'start' or 'end' (default: 'end') */
     initialCursorPosition?: 'start' | 'end';
-    /** Called when value changes */
+    /**
+     * Called when value changes — including programmatic `setValue` /
+     * controlled `value` updates, not just typing.
+     */
     onChange?: (value: string) => void;
     /** Called when editor loses focus - use this to commit the value */
     onBlur?: (value: string) => void;
-    /** Called when Enter is pressed (without modifier keys) */
+    /**
+     * Called when Enter is pressed (without modifier keys) while no
+     * autocomplete list is open — Enter accepts the completion instead.
+     * Alt+Enter inserts a newline.
+     */
     onSubmit?: (value: string) => void;
     /** Called when Escape is pressed */
     onCancel?: () => void;
@@ -141,7 +180,10 @@ export interface FormulaEditorProps {
     getDisplayUnits: GetDisplayUnitsFunc;
     /** List of available formula functions for autocomplete */
     formulaFunctions?: FormulaFunction[];
-    /** Current sheet name (for determining if cell refs are local) */
+    /**
+     * Current sheet name, compared against `CellRef.sheet1` to decide which
+     * refs are local (only local refs get a colored background).
+     */
     sheetName?: string;
     /** Configuration options */
     config?: FormulaEditorConfig;
@@ -155,5 +197,6 @@ export interface FormulaEditorProps {
  * Returns a different color for each reference index to distinguish them.
  */
 export declare const CELL_REF_COLORS: string[];
+/** Palette color for the `index`-th reference; wraps after six. */
 export declare function getCellRefColor(index: number): string;
 //# sourceMappingURL=types.d.ts.map

package/dist/src/lib/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/lib/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/lib/types.ts"],"names":[],"mappings":"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"}

package/dist/src/lib/utils.d.ts

@@ -14,6 +14,10 @@ export interface DisplayUnit {
  * Convert formula display info to display units for rendering.
  * The offset accounts for the leading '=' being stripped before sending to backend.
  *
+ * Treats token offsets as string indices, so it is only correct for ASCII
+ * formulas — the backend emits UTF-8 byte offsets (see `TokenUnit`). The
+ * CodeMirror editor does not use this; it converts offsets itself.
+ *
  * @param formula - The full formula string (including leading '=')
  * @param displayInfo - Token info from backend
  * @returns Array of display units for rendering
@@ -25,14 +29,18 @@ export declare function convertToDisplayUnits(formula: string, displayInfo: Form
  */
 export declare function isLocalCellRef(cellRef: CellRef, currentSheet: string): boolean;
 /**
- * Simple fuzzy match using longest common subsequence.
+ * Case-insensitive subsequence match: every query char must appear in
+ * `target` in order (greedy, first occurrence). `indices` are the matched
+ * positions in `target`; an empty query matches everything.
  */
 export declare function fuzzyMatch(query: string, target: string): {
     matched: boolean;
     indices: number[];
 };
 /**
- * Check if text starts with '=' indicating a formula.
+ * Whether the text is a formula: starts with '=' after trimming, or is an
+ * array formula `{=...}`. Note the editor strips the '=' only when it is the
+ * very first character, so ` =A1` or `{=A1}` reach `getDisplayUnits` as-is.
  */
 export declare function isFormula(text: string): boolean;
 /**
@@ -48,9 +56,14 @@ export declare function isFormula(text: string): boolean;
  * R1C1, structured refs, …) so the caller can leave it untouched.
  */
 export declare function cycleReferenceAbsolute(text: string): string | null;
+/**
+ * Width in CSS pixels of `text` rendered in `font` (a CSS font shorthand).
+ * Falls back to 8 px per char when no 2D context is available.
+ */
 export declare function measureText(text: string, font: string): number;
 /**
- * Generate a simple UUID.
+ * Generate a v4-shaped UUID from `Math.random` — fine for DOM ids, not
+ * cryptographically unique.
  */
 export declare function simpleUuid(): string;
 //# sourceMappingURL=utils.d.ts.map

package/dist/src/lib/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/lib/utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAE,kBAAkB,EAAE,OAAO,EAAC,MAAM,SAAS,CAAA;AAEnE;;GAEG;AACH,eAAO,MAAM,GAAG,OAAO,CAAA;AAEvB;;GAEG;AACH,MAAM,WAAW,WAAW;IACxB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,SAAS,GAAG,KAAK,GAAG,OAAO,CAAA;CACpC;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACjC,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,kBAAkB,GAChC,WAAW,EAAE,CAqCf;AAqBD;;;GAGG;AACH,wBAAgB,cAAc,CAC1B,OAAO,EAAE,OAAO,EAChB,YAAY,EAAE,MAAM,GACrB,OAAO,CAcT;AAED;;GAEG;AACH,wBAAgB,UAAU,CACtB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACf;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAC,CAqBvC;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAQ/C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAkClE;AAQD,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAS9D;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAMnC"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/lib/utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAE,kBAAkB,EAAE,OAAO,EAAC,MAAM,SAAS,CAAA;AAEnE;;GAEG;AACH,eAAO,MAAM,GAAG,OAAO,CAAA;AAEvB;;GAEG;AACH,MAAM,WAAW,WAAW;IACxB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,SAAS,GAAG,KAAK,GAAG,OAAO,CAAA;CACpC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACjC,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,kBAAkB,GAChC,WAAW,EAAE,CAqCf;AAqBD;;;GAGG;AACH,wBAAgB,cAAc,CAC1B,OAAO,EAAE,OAAO,EAChB,YAAY,EAAE,MAAM,GACrB,OAAO,CAcT;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACtB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACf;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAC,CAqBvC;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAQ/C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAoClE;AAOD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAS9D;AAED;;;GAGG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAMnC"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "logisheets-formula-editor",
-    "version": "1.15.0",
+    "version": "1.16.0",
     "description": "Excel-style formula editor for spreadsheets — syntax highlighting, per-reference cell-ref coloring, and function autocomplete, built on CodeMirror 6. Ships a React component and a framework-agnostic core.",
     "author": "Jeremy He",
     "license": "MIT",