@bendyline/squisq-editor-react 2.10.2 → 2.11.0

package/dist/{shell-vNr6KOF9.d.ts → shell-DInMVUpf.d.ts}

@@ -1,5 +1,9 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ReactNode, RefObject } from 'react';
+import { TableCellEdit, TableCellValue } from '@bendyline/squisq/table';
+import { CalcEngineConfig, CalcEngine } from '@bendyline/squisq-calc';
+import { IngestTable } from '@bendyline/squisq-grid-react';
+import { XlsxWorkbookGrids } from '@bendyline/squisq-formats/xlsx';
+import { ReactNode, RefObject, ReactElement } from 'react';
 import { Doc, MediaProvider, ViewportPreset, Theme } from '@bendyline/squisq/schemas';
 import { FenceRendererMap } from '@bendyline/squisq/fence';
 import { MarkdownDocument } from '@bendyline/squisq/markdown';
@@ -10,6 +14,141 @@ import { Editor } from '@tiptap/core';
 import { editor } from 'monaco-editor';
 import { CodeBlockCopyHandler } from '@bendyline/squisq-react';
 
+/**
+ * Sidecar bytes → the grid's neutral `IngestTable`, via lazy formats
+ * imports (the `processTextFile`-docx precedent — formats stays out of the
+ * static graph).
+ *
+ * CSV/TSV additionally sniff and RETAIN the source conventions the save
+ * path must reproduce (delimiter, newline flavor, trailing newline, BOM)
+ * plus the original parsed `string[][]` — unedited cells re-serialize from
+ * the parse product, never from typed columns, so untouched values have no
+ * float-rendering drift. XLSX resolves the heading's `sheet`/`anchor`
+ * region (the summary card used to ignore those), keeps typed cell values,
+ * and carries the address map + per-cell formula/date locks the in-place
+ * patch save needs; parquet stays read-only.
+ */
+
+interface CsvSourceMeta {
+    delimiter: string;
+    newline: '\r\n' | '\n';
+    trailingNewline: boolean;
+    bom: boolean;
+    /** The parsed source rows INCLUDING the header row — the save baseline. */
+    rows: string[][];
+    hasHeader: boolean;
+}
+interface XlsxSourceMeta {
+    /** Worksheet the region lives on. */
+    sheet: string;
+    /** 0-based grid row/col of the region's top-left cell (the header row, when there is one). */
+    anchorRow: number;
+    anchorCol: number;
+    hasHeader: boolean;
+    /**
+     * Body cells (`"row:col"`, body coordinates) locked WITHOUT a calculation
+     * engine: formula cells + date-styled cells. With an engine session,
+     * formula cells unlock and only `dateLocked` + `masterLocked` remain.
+     */
+    locked: ReadonlySet<string>;
+    /** Date-styled body cells — locked in every mode this milestone. */
+    dateLocked: ReadonlySet<string>;
+    /**
+     * Shared-formula MASTERS — locked even with an engine, because the
+     * in-place patcher refuses to replace them (their followers' `si` would
+     * dangle). Followers edit freely (they simply leave the group).
+     */
+    masterLocked: ReadonlySet<string>;
+    /** Body-cell formulas (no leading `=`), for display + engine seeding. */
+    formulas: ReadonlyMap<string, string>;
+    /** The full raw workbook — the calc engine seeds from ALL sheets, since
+     * region formulas routinely reference cells outside the region. */
+    grids: XlsxWorkbookGrids;
+}
+interface IngestedSidecar {
+    ingest: IngestTable;
+    /** Present only for CSV/TSV. */
+    csv?: CsvSourceMeta;
+    /** Present only for XLSX — the address map + per-cell locks the save needs. */
+    xlsx?: XlsxSourceMeta;
+    /** Present when editing is unavailable, with the user-facing reason. */
+    readOnlyReason?: string;
+}
+/** Tooltip shown on locked XLSX cells. */
+declare const XLSX_LOCKED_REASON = "Formula and date cells become editable with the calculation engine (Phase 3)";
+declare function ingestSidecarBytes(bytes: ArrayBuffer, ext: string, params: {
+    sheet?: string;
+    anchor?: string;
+    headerRow?: boolean;
+}): Promise<IngestedSidecar>;
+
+/**
+ * XLSX formula editing in the data card: an in-house calc-engine session
+ * behind the grid's `FormulaSupport` seam.
+ *
+ * The engine seeds from the ENTIRE workbook (`XlsxWorkbookGrids`) — region
+ * formulas routinely reference cells outside the region — with formula
+ * cells seeded as formulas and value cells as values (date cells converted
+ * back to serials, since the importer normalized them to ISO strings).
+ *
+ * Display discipline: the store keeps showing the file's CACHED values
+ * until an edit actually changes something. After each committed edit the
+ * session diffs the region's formula cells against its own previous engine
+ * values and returns only the CHANGES as `TableCellEdit`s — and a cell
+ * whose engine value is `#NAME?` (a function this tier doesn't implement)
+ * never overwrites its cached display.
+ *
+ * `@bendyline/squisq-calc` is a regular dependency reached only via
+ * dynamic `import()` (the grid-react pattern) — code-split, and a load
+ * failure just means formula cells stay locked.
+ */
+
+/**
+ * Builds the engine a formula session runs on. The default is the in-house
+ * tier; a host may inject any `CalcEngine` backend (e.g. IronCalc via
+ * `@bendyline/squisq-calc/ironcalc`) — the session only speaks the
+ * contract. A factory failure falls back to the in-house tier.
+ */
+type CalcEngineFactory = (config: CalcEngineConfig) => Promise<CalcEngine>;
+interface FormulaSessionOptions {
+    engineFactory?: CalcEngineFactory;
+}
+interface FormulaEditRecord {
+    formula: string;
+    /** Engine result, when scalar — persisted as the cached `<v>`. */
+    cachedValue?: number | boolean | string;
+}
+interface XlsxFormulaSession {
+    getFormula(bodyRow: number, col: number): string | undefined;
+    /** Date cells + shared-formula masters stay locked; formulas edit. */
+    isCellLocked(bodyRow: number, col: number): boolean;
+    commitFormula(bodyRow: number, col: number, formula: string): Promise<{
+        ok: boolean;
+        error?: string;
+        updates?: TableCellEdit[];
+    }>;
+    /**
+     * Mirror a plain value edit into the engine and return the recalculated
+     * dependent updates (region formula cells whose values changed) — the
+     * live-recalc half of "edit Units, watch Revenue follow".
+     */
+    noteValueEdit(bodyRow: number, col: number, value: TableCellValue): Promise<TableCellEdit[]>;
+    readonly dirtyCount: number;
+    /** Unsaved formula edits, keyed `"row:col"` (body coordinates). */
+    formulaEdits(): ReadonlyMap<string, FormulaEditRecord>;
+    /** Revert to the loaded workbook; returns the display updates to re-apply. */
+    discard(): Promise<TableCellEdit[]>;
+    /** Forget the edits after a successful save (values stay current). */
+    markSaved(): void;
+    dispose(): void;
+}
+/**
+ * Create the engine session, or null when formula editing can't be offered
+ * (calc module unavailable, or the workbook blows the interactive budget —
+ * the standing NHS-stress-workbook rule: degrade, never hang).
+ */
+declare function createXlsxFormulaSession(meta: XlsxSourceMeta, options?: FormulaSessionOptions): Promise<XlsxFormulaSession | null>;
+
 /**
  * Configuration a Scene host (diagram / drawing / layout widget) supplies
  * so the shared inline text editor knows how to read and write the text of
@@ -378,6 +517,10 @@ interface EditorContextValue extends EditorState, EditorActions {
      * override it.
      */
     proofingDefaultEnabled: boolean;
+    /** Whether spelling findings are surfaced (host preference). */
+    proofingSpellingEnabled: boolean;
+    /** Whether grammar/style findings are surfaced (host preference). */
+    proofingGrammarEnabled: boolean;
     /**
      * Host-owned, per-document storage for dismissed findings. Ignores
      * are never written into the document; without a store they last only
@@ -484,6 +627,10 @@ interface EditorProviderProps {
     proofing?: ProofingCapability | null;
     /** Host default enable state for proofing (default true). */
     proofingDefaultEnabled?: boolean;
+    /** Whether spelling findings are surfaced (default true). */
+    proofingSpellingEnabled?: boolean;
+    /** Whether grammar/style findings are surfaced (default true). */
+    proofingGrammarEnabled?: boolean;
     /** Host-owned per-document storage for dismissed proofing findings. */
     proofingIgnoreStore?: ProofingIgnoreStore | null;
     /**
@@ -618,7 +765,7 @@ interface ViewPreferences {
     /** Document vs. block-at-a-time layout. */
     layoutMode?: LayoutMode;
 }
-declare function EditorProvider({ initialMarkdown, initialView, articleId, colorScheme: initialColorScheme, workspaceContainer, allowVersioning, versionBasename, versioningPrunePolicy, versioningAutoSaveIdleMs, onSaveVersion, mediaProvider, imageDisplayMode, mentionProvider, proofing, proofingDefaultEnabled, proofingIgnoreStore, documentLinkProvider, fenceRenderers, linkSchemes, allowRecording, allowNarrate, preserveSourceWrapping, fileName, saveCoverImageOutput, saveDashboardImageOutput, language, findMode: controlledFindMode, onFindModeChange, inlinePreview, showStatusBar, outline, blockTags, blockTagVisibility: initialBlockTagVisibility, themeInheritance, layoutMode, viewPreferences, onViewPreferencesChange, children, }: EditorProviderProps): react_jsx_runtime.JSX.Element;
+declare function EditorProvider({ initialMarkdown, initialView, articleId, colorScheme: initialColorScheme, workspaceContainer, allowVersioning, versionBasename, versioningPrunePolicy, versioningAutoSaveIdleMs, onSaveVersion, mediaProvider, imageDisplayMode, mentionProvider, proofing, proofingDefaultEnabled, proofingSpellingEnabled, proofingGrammarEnabled, proofingIgnoreStore, documentLinkProvider, fenceRenderers, linkSchemes, allowRecording, allowNarrate, preserveSourceWrapping, fileName, saveCoverImageOutput, saveDashboardImageOutput, language, findMode: controlledFindMode, onFindModeChange, inlinePreview, showStatusBar, outline, blockTags, blockTagVisibility: initialBlockTagVisibility, themeInheritance, layoutMode, viewPreferences, onViewPreferencesChange, children, }: EditorProviderProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Host-supplied context sections rendered INSIDE the Monaco (raw/code)
@@ -839,6 +986,12 @@ interface EditorShellProps {
     onSaveVersion?: (result: SaveVersionResult) => void;
     /** Show the Files toggle in the toolbar. Defaults to true when mediaProvider is passed. */
     showFilesToggle?: boolean;
+    /**
+     * Open the Files panel when its accessory bin becomes non-empty. The user
+     * can still close it normally; it opens again only when the visible count
+     * changes. Defaults to false.
+     */
+    showFilesWhenNotEmpty?: boolean;
     /**
      * Show the toolbar's built-in text, block, and contextual formatting
      * controls. The toolbar, Insert menu, and host-provided slots remain
@@ -890,6 +1043,13 @@ interface EditorShellProps {
      * (Slack, Discord). When omitted, the editor behaves normally.
      */
     submitOnEnter?: () => void;
+    /**
+     * Calc backend for the data card's XLSX formula sessions (default: the
+     * in-house tier from `@bendyline/squisq-calc`). Hosts inject e.g.
+     * IronCalc: `(config) => import('@bendyline/squisq-calc/ironcalc')
+     * .then((m) => m.createIronCalcEngine({ ...config, wasmSource }))`.
+     */
+    calcEngineFactory?: CalcEngineFactory;
     /**
      * Host-supplied context dictionary rendered inside the Monaco (raw / code)
      * surface: collapsible markdown sections injected above anchor lines, plus
@@ -1006,6 +1166,18 @@ interface EditorShellProps {
      * and the user's session toggle in the View menu override this.
      */
     proofingDefaultEnabled?: boolean;
+    /**
+     * Whether spelling findings (red squiggles) are shown (default `true`).
+     * A host-level preference, deliberately independent of the enable
+     * layers above: turning both this and `proofingGrammarEnabled` off is
+     * equivalent to turning proofing off, and loads no engine.
+     */
+    proofingSpellingEnabled?: boolean;
+    /**
+     * Whether grammar and style findings (green/blue squiggles) are shown
+     * (default `true`). See {@link EditorShellProps.proofingSpellingEnabled}.
+     */
+    proofingGrammarEnabled?: boolean;
     /**
      * Host-owned storage for findings the user dismissed with "Ignore",
      * scoped per document (`load`/`save` receive a
@@ -1193,7 +1365,7 @@ interface EditorShellProps {
  * Complete markdown editor shell with toolbar, view switcher, and three
  * editing modes: Raw (Monaco), WYSIWYG (Tiptap), and Preview.
  */
-declare function EditorShell({ initialMarkdown, initialView, hostMode, defaultViewportPreset, articleId, basePath, onChange, onLinkClick, showCodeCopyButton, onCopyCode, colorScheme, className, height, minHeight, maxHeight, mediaProvider, workspaceContainer, allowVersioning, versionBasename, versioningPrunePolicy, versioningAutoSaveIdleMs, onSaveVersion, showFilesToggle, showFormattingControls, showInsertControls, allowBinaryDownloads, toolbarSlotLeft, toolbarSlotAfterActions, toolbarSlotRight, statusBarSlotRight, showPlayTab, allowPresentationWindow, allowPresentationFullscreen, allowPrint, submitOnEnter, codeContext, fullWidth, uxFont, thinMargins, writeCanvasSettings, showStatusBar, imageDisplayMode, fileName, saveCoverImageOutput, saveDashboardImageOutput, language, findMode, onFindModeChange, mentionProvider, proofing, proofingDefaultEnabled, proofingIgnoreStore, documentLinkProvider, fenceRenderers, linkSchemes, allowRecording, allowNarrate, preserveSourceWrapping, placeholder, readOnly, imageSrc, imageAlt, imageMode, imageEditorContainer, onImageExport, inlinePreview, inlinePreviewWidth, outline, outlineWidth, blockTags, blockTagVisibility, themeInheritance, viewPreferences, onViewPreferencesChange, themeOverride, }: EditorShellProps): react_jsx_runtime.JSX.Element;
+declare function EditorShell({ initialMarkdown, initialView, hostMode, defaultViewportPreset, articleId, basePath, onChange, onLinkClick, showCodeCopyButton, onCopyCode, colorScheme, className, height, minHeight, maxHeight, mediaProvider, workspaceContainer, allowVersioning, versionBasename, versioningPrunePolicy, versioningAutoSaveIdleMs, onSaveVersion, showFilesToggle, showFilesWhenNotEmpty, showFormattingControls, showInsertControls, allowBinaryDownloads, toolbarSlotLeft, toolbarSlotAfterActions, toolbarSlotRight, statusBarSlotRight, showPlayTab, allowPresentationWindow, allowPresentationFullscreen, allowPrint, submitOnEnter, calcEngineFactory, codeContext, fullWidth, uxFont, thinMargins, writeCanvasSettings, showStatusBar, imageDisplayMode, fileName, saveCoverImageOutput, saveDashboardImageOutput, language, findMode, onFindModeChange, mentionProvider, proofing, proofingDefaultEnabled, proofingSpellingEnabled, proofingGrammarEnabled, proofingIgnoreStore, documentLinkProvider, fenceRenderers, linkSchemes, allowRecording, allowNarrate, preserveSourceWrapping, placeholder, readOnly, imageSrc, imageAlt, imageMode, imageEditorContainer, onImageExport, inlinePreview, inlinePreviewWidth, outline, outlineWidth, blockTags, blockTagVisibility, themeInheritance, viewPreferences, onViewPreferencesChange, themeOverride, }: EditorShellProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Shared editor context menu.
@@ -1241,7 +1413,7 @@ interface EditorContextMenuProviderProps {
  * Context-menu owner used by EditorShell. Exported for hosts that compose the
  * lower-level RawEditor/WysiwygEditor primitives into their own shell.
  */
-declare function EditorContextMenuProvider({ rootRef, readOnly, children, }: EditorContextMenuProviderProps): JSX.Element;
+declare function EditorContextMenuProvider({ rootRef, readOnly, children, }: EditorContextMenuProviderProps): ReactElement;
 
 /**
  * RawEditor
@@ -1299,12 +1471,24 @@ interface WysiwygEditorProps {
     readOnly?: boolean;
     /** Host-controlled base text size and line spacing for the Write canvas. */
     writeCanvasSettings?: WriteCanvasSettings;
+    /**
+     * Open the shell's Files panel — the data card's "Show in Files" button.
+     * Receives the sidecar path so hosts with a focusable file list can jump
+     * to it. Omitted (e.g. no media provider host) hides the affordance.
+     */
+    onOpenFilesPanel?: (relativePath?: string) => void;
+    /**
+     * Calc backend for the data card's formula sessions. Default: the
+     * in-house tier. A host may inject another `CalcEngine` implementation
+     * (e.g. IronCalc via `@bendyline/squisq-calc/ironcalc`).
+     */
+    calcEngineFactory?: CalcEngineFactory;
 }
 /**
  * Rich WYSIWYG markdown editor built on Tiptap (ProseMirror).
  * Binds to the shared EditorContext for source synchronization.
  */
-declare function WysiwygEditor({ placeholder, className, submitOnEnter, readOnly, writeCanvasSettings, }: WysiwygEditorProps): react_jsx_runtime.JSX.Element;
+declare function WysiwygEditor({ placeholder, className, submitOnEnter, readOnly, writeCanvasSettings, onOpenFilesPanel, calcEngineFactory, }: WysiwygEditorProps): react_jsx_runtime.JSX.Element;
 
 interface PreviewPanelProps {
     /** Base path for resolving media URLs in DocPlayer */
@@ -1331,4 +1515,4 @@ interface PreviewPanelProps {
  */
 declare function PreviewPanel({ basePath, className, workspaceContainer, onLinkClick, showCodeCopyButton, onCopyCode, }: PreviewPanelProps): react_jsx_runtime.JSX.Element;
 
-export { type BlockTagVisibility as B, type CodeContext as C, type DashboardImageSaveOutput as D, type EditorHostMode as E, type ImageDisplayMode as I, type LayoutMode as L, type MentionCandidate as M, PreviewPanel as P, RawEditor as R, type SceneTextChannel as S, type ThemeInheritance as T, type ViewPreferences as V, type WriteCanvasSettings as W, type CodeContextSection as a, type CoverImageSaveOutput as b, type DocumentLinkCandidate as c, type DocumentLinkProvider as d, type EditorActions as e, type EditorColorScheme as f, type EditorContextMenuContext as g, type EditorContextMenuItem as h, type EditorContextMenuItemVisibility as i, EditorContextMenuProvider as j, type EditorContextMenuProviderProps as k, type EditorContextValue as l, type EditorMode as m, EditorProvider as n, type EditorProviderProps as o, EditorShell as p, type EditorShellProps as q, type EditorState as r, type EditorView as s, type MentionProvider as t, type PreviewPanelProps as u, type RawEditorProps as v, WysiwygEditor as w, type WysiwygEditorProps as x, useEditorContext as y, useEditorContextMenuItems as z };
+export { WysiwygEditor as A, type BlockTagVisibility as B, type CodeContext as C, type DashboardImageSaveOutput as D, type EditorHostMode as E, type FormulaEditRecord as F, type WysiwygEditorProps as G, XLSX_LOCKED_REASON as H, type ImageDisplayMode as I, type XlsxFormulaSession as J, createXlsxFormulaSession as K, type LayoutMode as L, type MentionCandidate as M, ingestSidecarBytes as N, useEditorContext as O, PreviewPanel as P, useEditorContextMenuItems as Q, RawEditor as R, type SceneTextChannel as S, type ThemeInheritance as T, type ViewPreferences as V, type WriteCanvasSettings as W, type XlsxSourceMeta as X, type CalcEngineFactory as a, type CsvSourceMeta as b, type CodeContextSection as c, type CoverImageSaveOutput as d, type DocumentLinkCandidate as e, type DocumentLinkProvider as f, type EditorActions as g, type EditorColorScheme as h, type EditorContextMenuContext as i, type EditorContextMenuItem as j, type EditorContextMenuItemVisibility as k, EditorContextMenuProvider as l, type EditorContextMenuProviderProps as m, type EditorContextValue as n, type EditorMode as o, EditorProvider as p, type EditorProviderProps as q, EditorShell as r, type EditorShellProps as s, type EditorState as t, type EditorView as u, type FormulaSessionOptions as v, type IngestedSidecar as w, type MentionProvider as x, type PreviewPanelProps as y, type RawEditorProps as z };