oasis-editor 0.0.138 → 0.0.140

package/dist/app/client/publicDocumentApi.d.ts

@@ -0,0 +1,223 @@
+import { EditorBlockNode, EditorDocument, EditorParagraphNode, EditorPosition, EditorTextStyle } from '../../core/model.js';
+import { createEditorParagraph, createEditorTable } from '../../core/editorState.js';
+
+/** Current version of the editor document schema. */
+export declare const EDITOR_SCHEMA_VERSION = 1;
+/**
+ * Selects a specific node in the document tree. Used as a targeting mechanism
+ * for edit operations and queries.
+ */
+export type DocumentSelector = {
+    nodeId: string;
+} | {
+    text: string;
+    occurrence?: number;
+} | {
+    headingPath: string[];
+} | {
+    tableId: string;
+    row: number;
+    column: number;
+} | {
+    bookmark: string;
+} | {
+    contentControlTag: string;
+};
+/** A range between two positions in the document. */
+export interface DocumentRange {
+    start: EditorPosition;
+    end: EditorPosition;
+}
+/** Descriptor for a node in a semantic document snapshot. */
+export interface SemanticNode {
+    id: string;
+    type: string;
+    text?: string;
+    node: unknown;
+}
+/** Descriptor for a text match found by the find API. */
+export interface DocumentMatch {
+    selector: {
+        nodeId: string;
+    };
+    paragraphId: string;
+    text: string;
+    start: number;
+    end: number;
+}
+/** An item in the document outline (heading hierarchy). */
+export interface DocumentOutlineItem {
+    id: string;
+    level: number;
+    text: string;
+    path: string[];
+}
+/** Immutable snapshot of the document's semantic structure. */
+export interface SemanticDocumentSnapshot {
+    schemaVersion: number;
+    documentId: string;
+    text: string;
+    outline: DocumentOutlineItem[];
+    nodes: SemanticNode[];
+}
+/** Non-fatal warning produced during an operation. */
+export type OasisWarning = {
+    code: string;
+    message: string;
+    nodeId?: string;
+};
+/** Error codes for operation failures. */
+export type OasisErrorCode = "NODE_NOT_FOUND" | "AMBIGUOUS_SELECTOR" | "INVALID_RANGE" | "VALIDATION_FAILED" | "READ_ONLY" | "UNSUPPORTED_OPERATION" | "DOCUMENT_VERSION_CONFLICT" | "IMPORT_FAILED" | "EXPORT_FAILED" | "ABORTED";
+/** Structured error information returned on operation failure. */
+export interface OasisError {
+    code: OasisErrorCode;
+    message: string;
+    expectedVersion?: number;
+    actualVersion?: number;
+    details?: unknown;
+}
+/**
+ * Wraps a successful value or an error with its metadata.
+ * @typeParam T - The type of the success value.
+ */
+export type OasisResult<T> = {
+    ok: true;
+    value: T;
+    version: number;
+    warnings: OasisWarning[];
+} | {
+    ok: false;
+    error: OasisError;
+};
+/** A single edit operation to be applied to the document. */
+export type EditOperation = {
+    op: "insertText";
+    target: DocumentSelector;
+    text: string;
+    offset?: number;
+} | {
+    op: "replaceText";
+    target: DocumentSelector;
+    text: string;
+} | {
+    op: "deleteRange";
+    range: DocumentRange;
+} | {
+    op: "insertParagraph";
+    text?: string;
+    after?: DocumentSelector;
+} | {
+    op: "insertBlocks";
+    blocks: EditorBlockNode[];
+    after?: DocumentSelector;
+} | {
+    op: "deleteNode";
+    target: DocumentSelector;
+} | {
+    op: "setTextStyle";
+    target: DocumentSelector;
+    style: EditorTextStyle;
+} | {
+    op: "setParagraphStyle";
+    target: DocumentSelector;
+    style: {
+        styleId: string;
+    };
+} | {
+    op: "insertTable";
+    rows: string[][];
+    after?: DocumentSelector;
+} | {
+    op: "updateTableCell";
+    target: {
+        tableId: string;
+        row: number;
+        column: number;
+    };
+    text: string;
+};
+/** Describes the origin/actor of an edit request. */
+export interface EditActor {
+    type: string;
+    actorId?: string;
+    label?: string;
+}
+/** Request to apply one or more edit operations to the document. */
+export interface ApplyEditRequest {
+    operations: EditOperation[];
+    expectedVersion?: number;
+    transactionId?: string;
+    idempotencyKey?: string;
+    origin?: EditActor;
+}
+/** Result value returned after applying edit operations. */
+export interface ApplyEditValue {
+    changedNodeIds: string[];
+    createdNodeIds: string[];
+}
+/**
+ * Deep-clones a document.
+ * @param document - The document to clone.
+ * @returns A deep copy of the document.
+ */
+export declare function cloneDocument<T extends EditorDocument>(document: T): T;
+/**
+ * Ensures the document has a schemaVersion property set.
+ * @param document - The document to normalize.
+ * @returns The normalized document.
+ */
+export declare function normalizeDocument(document: EditorDocument): EditorDocument;
+/**
+ * Validates document structure, returning errors if any.
+ * @param document - The document to validate.
+ * @returns An OasisResult indicating success or listing validation errors.
+ */
+export declare function validateDocument(document: EditorDocument): OasisResult<true>;
+/**
+ * Creates a new empty editor document.
+ * @param options - Optional initial blocks and title.
+ * @returns A new EditorDocument.
+ */
+export declare function createDocument(options?: {
+    blocks?: EditorBlockNode[];
+    title?: string;
+}): EditorDocument;
+/** Creates an empty paragraph node. Alias for {@link createEditorParagraph}. */
+export declare const createParagraph: typeof createEditorParagraph;
+/**
+ * Creates a heading paragraph.
+ * @param text - The heading text.
+ * @param options - Options including the heading level.
+ * @returns A new heading paragraph node.
+ */
+export declare function createHeading(text: string, options?: {
+    level?: number;
+}): EditorParagraphNode;
+/**
+ * Creates a table node from a 2D array of string cell values.
+ * @param rows - A 2D array where each inner array represents a row of cell values.
+ * @returns A new table node.
+ */
+export declare function createTable(rows: string[][]): ReturnType<typeof createEditorTable>;
+/**
+ * Creates a query object for read-only document inspection.
+ * @param document - The document to query against.
+ * @returns An object with snapshot, getText, getNode, find, and outline methods.
+ */
+export declare function queryDocument(document: EditorDocument): {
+    snapshot: () => SemanticDocumentSnapshot;
+    getText: (target?: DocumentSelector | DocumentRange) => string;
+    getNode: (selector: DocumentSelector) => SemanticNode | null;
+    find: (text: string) => DocumentMatch[];
+    outline: () => DocumentOutlineItem[];
+};
+/**
+ * Applies an array of edit operations to a document.
+ * @param document - The document to mutate.
+ * @param operations - The operations to apply.
+ * @returns The mutated document along with metadata about changed and created nodes.
+ */
+export declare function applyDocumentOperations(document: EditorDocument, operations: EditOperation[]): {
+    document: EditorDocument;
+    value: ApplyEditValue;
+};

package/dist/app/controllers/documentIO/DocumentExporter.d.ts

@@ -1,11 +1,19 @@
 import { EditorDocument } from '../../../core/model.js';
 
+/** Dependencies required by {@link createDocumentExporter}. */
 export interface DocumentExporterDeps {
     document: () => EditorDocument;
     focusInput: () => void;
     download?: (blob: Blob, filename: string) => void;
 }
+/**
+ * Creates a document exporter with support for .docx and .pdf output.
+ * @param deps - The dependencies required for exporting.
+ * @returns An object with export methods.
+ */
 export declare function createDocumentExporter(deps: DocumentExporterDeps): {
-    handleExportDocx: () => Promise<void>;
-    handleExportPdf: () => Promise<void>;
+    handleExportDocx: () => Promise<Blob>;
+    handleExportPdf: () => Promise<Blob>;
+    exportDocxBlob: () => Promise<Blob>;
+    exportPdfBlob: () => Promise<Blob>;
 };

package/dist/app/controllers/documentIO/DocumentImporter.d.ts

@@ -2,6 +2,7 @@ import { EditorState, getDocumentParagraphs } from '../../../core/model.js';
 import { EditorLogger } from '../../../utils/logger.js';
 import { ImportProgressPhase } from './importProgress.js';
 
+/** Dependencies required by {@link createDocumentImporter}. */
 export interface DocumentImporterDeps {
     applyState: (state: EditorState) => void;
     stabilizeLayoutAfterImport: () => Promise<void>;
@@ -14,6 +15,11 @@ export interface DocumentImporterDeps {
     now: () => number;
     logger: EditorLogger;
 }
+/**
+ * Creates a document importer that handles file import with progress tracking.
+ * @param deps - The dependencies required for importing.
+ * @returns An object with the `handleImportFile` method.
+ */
 export declare function createDocumentImporter(deps: DocumentImporterDeps): {
     handleImportFile: (file: File | null) => Promise<void>;
 };

package/dist/app/controllers/useEditorDocumentIO.d.ts

@@ -23,8 +23,10 @@ export declare function createEditorDocumentIO(deps: UseEditorDocumentIOProps):
 declare function createEditorDocumentIOImpl(deps: UseEditorDocumentIOProps): {
     importProgress: import('solid-js').Accessor<ImportProgressState | null>;
     handleImportFile: (file: File | null) => Promise<void>;
-    handleExportDocx: () => Promise<void>;
-    handleExportPdf: () => Promise<void>;
+    handleExportDocx: () => Promise<Blob>;
+    handleExportPdf: () => Promise<Blob>;
+    exportDocxBlob: () => Promise<Blob>;
+    exportPdfBlob: () => Promise<Blob>;
     insertImageFromFile: (file: File, position?: EditorPosition | null) => Promise<void>;
     handleInsertImage: (file: File | null) => Promise<void>;
 };

package/dist/app/controllers/useEditorFindReplace.d.ts

@@ -2,6 +2,7 @@ import { MergeKey } from '../../core/transactionMergeKeys.js';
 import { FindOptions, FindReplaceMatch } from '../services/FindReplaceService.js';
 import { EditorState } from '../../core/model.js';
 
+/** Result of the {@link useEditorFindReplace} hook. */
 export interface UseEditorFindReplaceResult {
     searchTerm: () => string;
     setSearchTerm: (term: string) => void;
@@ -18,6 +19,7 @@ export interface UseEditorFindReplaceResult {
     isOpen: () => boolean;
     setIsOpen: (open: boolean) => void;
 }
+/** Dependencies required by {@link useEditorFindReplace}. */
 export interface FindReplaceDeps {
     state: EditorState;
     applyState: (next: EditorState) => void;
@@ -26,4 +28,9 @@ export interface FindReplaceDeps {
     }) => void;
     focusInput: () => void;
 }
+/**
+ * SolidJS hook that drives find-and-replace state and actions.
+ * @param deps - The dependencies required by the hook.
+ * @returns The find/replace state and action methods.
+ */
 export declare function useEditorFindReplace(deps: FindReplaceDeps): UseEditorFindReplaceResult;

package/dist/app/controllers/useEditorPersistence.d.ts

@@ -1,14 +1,24 @@
 import { EditorDocument, EditorState } from '../../core/model.js';
 import { EditorLogger } from '../../utils/logger.js';
 
+/** Current persistence status indicator. */
 export type PersistenceStatus = "Saved" | "Saving..." | "Error" | "Initial";
+/** Return value of the {@link useEditorPersistence} hook. */
 export interface UseEditorPersistenceResult {
     status: () => PersistenceStatus;
 }
+/** Minimal persistence interface for saving and loading documents. */
 export interface DocumentPersistence {
     saveDocument(doc: EditorDocument): Promise<void>;
     loadDocument(): Promise<EditorDocument | null>;
 }
+/**
+ * SolidJS hook that manages auto-saving the editor document via a persistence backend.
+ * @param state - The editor state to watch for changes.
+ * @param onLoaded - Callback invoked when a previously saved document is loaded.
+ * @param options - Configuration including the persistence backend and logger.
+ * @returns The persistence status.
+ */
 export declare function useEditorPersistence(state: EditorState, onLoaded: (doc: EditorDocument) => void, options: {
     enabled?: boolean;
     persistence: DocumentPersistence;

package/dist/app/services/FindReplaceService.d.ts

@@ -1,12 +1,21 @@
 import { EditorDocument, EditorPosition } from '../../core/model.js';
 
+/** Describes a single match found by the find service. */
 export interface FindReplaceMatch {
     anchor: EditorPosition;
     focus: EditorPosition;
     paragraphIndex: number;
 }
+/** Options that control how find searches operate. */
 export interface FindOptions {
     matchCase?: boolean;
     wholeWord?: boolean;
 }
+/**
+ * Searches a document for the given term and returns all matches.
+ * @param doc - The document to search.
+ * @param searchTerm - The text to search for.
+ * @param options - Search options (case sensitivity, whole word).
+ * @returns An array of match descriptors.
+ */
 export declare function findMatchesInDocument(doc: EditorDocument, searchTerm: string, options?: FindOptions): FindReplaceMatch[];

package/dist/app/services/indexedDbPersistence.d.ts

@@ -1,20 +1,29 @@
 import { EditorDocument } from '../../core/model.js';
 
+/** Options for configuring an IndexedDB persistence instance. */
 export interface IndexedDbPersistenceOptions {
     /** Key under which the document is stored. Distinct keys isolate editors. */
     key?: string;
     dbName?: string;
     storeName?: string;
 }
+/** IndexedDB-backed persistence contract for saving and loading documents. */
 export interface IndexedDbPersistence {
+    /** Persists the document to IndexedDB. */
     saveDocument(doc: EditorDocument): Promise<void>;
+    /** Loads the document from IndexedDB, or null if none exists. */
     loadDocument(): Promise<EditorDocument | null>;
+    /** Removes the stored document from IndexedDB. */
     clearDocument(): Promise<void>;
+    /** Closes the database connection. */
     close(): void;
 }
 /**
- * Create an IndexedDB-backed persistence instance. Each call owns its own
+ * Creates an IndexedDB-backed persistence instance. Each call owns its own
  * connection and storage key, so two editors on the same page never share a
  * document slot. There is intentionally no module-level singleton.
+ *
+ * @param options - Configuration options for the persistence instance.
+ * @returns A new IndexedDbPersistence instance.
  */
 export declare function createIndexedDbPersistence(options?: IndexedDbPersistenceOptions): IndexedDbPersistence;

package/dist/app/services/tablePropertiesService.d.ts

@@ -1,15 +1,24 @@
 import { EditorState } from '../../core/model.js';
 import { TablePropertiesDialogApplyValues, TablePropertiesDialogInitialValues } from '../../ui/components/Dialogs/TablePropertiesDialog.js';
 
-/** Whether the current selection sits inside a table. */
+/**
+ * @param state - The current editor state.
+ * @returns Whether the current selection sits inside a table.
+ */
 export declare function hasActiveTable(state: EditorState): boolean;
 /**
- * Reads the active table/cell into the dialog's initial values, or `null` when
- * the selection is not inside a table.
+ * Reads the active table/cell into the dialog's initial values.
+ * @param state - The current editor state.
+ * @param activeTab - The default active tab in the dialog.
+ * @returns The dialog initial values, or `null` when the selection is not inside a table.
  */
 export declare function readTableProperties(state: EditorState, activeTab?: TablePropertiesDialogInitialValues["activeTab"]): TablePropertiesDialogInitialValues | null;
 /**
  * Applies the dialog's submitted values to the active table/cell, returning the
  * next state. A no-op when the selection is no longer inside a table.
+ *
+ * @param state - The current editor state.
+ * @param values - The dialog values to apply.
+ * @returns The next editor state.
  */
 export declare function applyTableProperties(state: EditorState, values: TablePropertiesDialogApplyValues): EditorState;

package/dist/app/services/userPreferences.d.ts

@@ -1,4 +1,8 @@
+/** @returns Whether the welcome overlay has been seen. */
 export declare function getWelcomeSeen(): boolean;
+/** Marks the welcome overlay as seen. */
 export declare function setWelcomeSeen(): void;
+/** @returns Whether the user prefers precise font rendering. */
 export declare function getPreciseFontPreference(): boolean;
+/** @param on - Whether precise font rendering should be enabled. */
 export declare function setPreciseFontPreference(on: boolean): void;