oasis-editor 0.0.138 → 0.0.139

package/dist/core/Editor.d.ts

@@ -7,7 +7,7 @@ import { OasisEditor, OasisPlugin } from './plugin.js';
  * Options accepted by the synchronous `new Editor(...)` path. Plugins are
  * deliberately absent: they need async initialization and so are only valid via
  * {@link Editor.create}. Encoding that in the type (rather than a runtime throw)
- * makes the precondition checkable at compile time (L1).
+ * makes the precondition checkable at compile time.
  */
 export interface SynchronousEditorOptions {
     doc?: EditorDocument;
@@ -20,6 +20,7 @@ export interface SynchronousEditorOptions {
 export interface EditorCreateOptions extends SynchronousEditorOptions {
     plugins?: OasisPlugin[];
 }
+/** Core editor class providing state management, command dispatch, and plugin lifecycle. */
 export declare class Editor implements OasisEditor {
     private stateStore;
     private setState;
@@ -27,14 +28,45 @@ export declare class Editor implements OasisEditor {
     private listeners;
     readonly commands: CommandRegistry;
     readonly ui: PluginUiRegistry;
+    /**
+     * @param options - Options for synchronous construction (no plugins).
+     */
     constructor(options?: SynchronousEditorOptions);
+    /**
+     * Creates an editor instance asynchronously, initializing all provided plugins.
+     * @param options - Options including plugins to load.
+     * @returns A promise that resolves to the initialized editor.
+     */
     static create(options?: EditorCreateOptions): Promise<Editor>;
     private initializeState;
+    /** @returns The current editor state. */
     get state(): EditorState;
+    /**
+     * Applies a state updater function and emits a "change:data" event.
+     * @param updater - Function that receives the current state and returns the new state.
+     */
     dispatch(updater: (state: EditorState) => EditorState): void;
+    /** Destroys the editor, cleaning up plugins, commands, UI, and listeners. */
     destroy(): Promise<void>;
+    /**
+     * Subscribes to an event.
+     * @param event - The event name.
+     * @param callback - The handler to invoke when the event fires.
+     * @returns An unsubscribe function.
+     */
     on(event: string, callback: (...args: unknown[]) => void): () => void;
+    /**
+     * Subscribes to a single emission of an event.
+     * @param event - The event name.
+     * @param callback - The handler to invoke once.
+     * @returns An unsubscribe function.
+     */
     once(event: string, callback: (...args: unknown[]) => void): () => void;
+    /**
+     * Removes a previously subscribed event handler.
+     * @param event - The event name.
+     * @param callback - The handler to remove.
+     */
     off(event: string, callback: (...args: unknown[]) => void): void;
     private emit;
     private createCommandContext;

package/dist/core/commands/CommandBus.d.ts

@@ -1,9 +1,35 @@
 import { CommandState, OasisEditor } from '../plugin.js';
 import { CommandRef } from './CommandRef.js';
 
+/**
+ * Untyped command bus that accepts {@link CommandRef} references. Used
+ * internally when command names are known only at runtime.
+ * @typeParam TState - The command state type.
+ */
 export interface CommandBus<TState = CommandState> {
+    /**
+     * Executes a command by reference, with an optional payload override.
+     * @param command - The command reference.
+     * @param payloadOverride - Optional payload override.
+     * @returns The command's result.
+     */
     execute(command: CommandRef, payloadOverride?: unknown): unknown;
+    /**
+     * @param command - The command reference.
+     * @param payloadOverride - Optional payload override.
+     * @returns Whether the command can execute.
+     */
     canExecute(command: CommandRef, payloadOverride?: unknown): boolean;
+    /**
+     * @param command - The command reference.
+     * @returns The command's reactive state.
+     */
     state(command: CommandRef): TState;
 }
+/**
+ * Creates a command bus backed by the editor's command registry.
+ * The bus resolves command references before delegating to the registry.
+ * @param editor - The editor instance.
+ * @returns A new CommandBus.
+ */
 export declare function createEditorCommandBus(editor: OasisEditor): CommandBus;

package/dist/core/commands/publicCommandTypes.d.ts

@@ -3,19 +3,27 @@ import { EditorPageMargins } from '../model.js';
 import { TextCaseMode } from './text.js';
 import { TableBorderPreset } from './table.js';
 
+/** Payload for the `insertTable` command. */
 export interface InsertTablePayload {
     rows: number;
     columns: number;
 }
+/** Payload for the `setFontSize` command. */
 export interface SetFontSizePayload {
     size: number | string | null;
 }
+/** Payload for the `setPageMargins` command. */
 export interface SetPageMarginsPayload extends Partial<EditorPageMargins> {
 }
+/** Payload for the `setSpecialIndent` command. */
 export interface SetSpecialIndentPayload {
     kind: "none" | "firstLine" | "hanging";
     value?: number | null;
 }
+/**
+ * Maps every built-in command name to its expected payload type.
+ * Commands with `undefined` payload accept no arguments.
+ */
 export interface OasisCommandPayloads {
     selectAll: undefined;
     insertFootnote: undefined;
@@ -126,17 +134,62 @@ export interface OasisCommandPayloads {
     tableDistributeRows: undefined;
     insertTable: InsertTablePayload;
 }
+/** Maps commands to their typed return values. Commands not listed return `unknown`. */
 export interface OasisCommandResults {
     documentStyles: unknown;
     [command: string]: unknown;
 }
+/** A valid built-in command name. */
 export type OasisCommandName = keyof OasisCommandPayloads & string;
+/**
+ * Infers the argument tuple for a typed command based on its payload type.
+ * @typeParam TCommand - The command name.
+ */
 export type CommandPayloadArgs<TCommand extends OasisCommandName> = OasisCommandPayloads[TCommand] extends undefined ? [payload?: undefined] : [payload: OasisCommandPayloads[TCommand]];
+/**
+ * Typed command bus that provides type-safe execute/canExecute/state methods
+ * for built-in commands, while also accepting runtime {@link CommandRef} overloads.
+ * @typeParam TState - The command state type.
+ */
 export interface TypedCommandBus<TState> {
+    /**
+     * Type-safe execute for known commands.
+     * @param command - The command name.
+     * @param args - The command payload.
+     * @returns The command result.
+     */
     execute<TCommand extends OasisCommandName>(command: TCommand, ...args: CommandPayloadArgs<TCommand>): TCommand extends keyof OasisCommandResults ? OasisCommandResults[TCommand] : unknown;
+    /**
+     * Runtime execute via CommandRef.
+     * @param command - The command reference.
+     * @param payloadOverride - Optional payload override.
+     * @returns The command result.
+     */
     execute(command: CommandRef, payloadOverride?: unknown): unknown;
+    /**
+     * Type-safe canExecute for known commands.
+     * @param command - The command name.
+     * @param args - The command payload.
+     * @returns Whether the command can execute.
+     */
     canExecute<TCommand extends OasisCommandName>(command: TCommand, ...args: CommandPayloadArgs<TCommand>): boolean;
+    /**
+     * Runtime canExecute via CommandRef.
+     * @param command - The command reference.
+     * @param payloadOverride - Optional payload override.
+     * @returns Whether the command can execute.
+     */
     canExecute(command: CommandRef, payloadOverride?: unknown): boolean;
+    /**
+     * Type-safe state for known commands.
+     * @param command - The command name.
+     * @returns The command state.
+     */
     state<TCommand extends OasisCommandName>(command: TCommand): TState;
+    /**
+     * Runtime state via CommandRef.
+     * @param command - The command reference.
+     * @returns The command state.
+     */
     state(command: CommandRef): TState;
 }

package/dist/core/model/types/document.d.ts

@@ -138,6 +138,8 @@ export interface EditorEndnotes {
     continuationSeparator?: EditorBlockNode[];
 }
 export interface EditorDocument {
+    /** Serialized document schema revision. Missing values are treated as v1. */
+    schemaVersion?: number;
     id: string;
     pageSettings?: EditorPageSettings;
     sections?: EditorSection[];

package/dist/core/plugin.d.ts

@@ -3,7 +3,9 @@ import { EditorState } from './model.js';
 import { CommandRef } from './commands/CommandRef.js';
 import { RibbonGroupResizePolicy, RibbonRow, RibbonSize, RibbonTabId } from './pluginUiTypes.js';
 
+/** Function signature for unsubscribing from a subscription. */
 export type Unsubscribe = () => void;
+/** Context passed to command execution and refresh callbacks. */
 export interface OasisCommandContext {
     editor: OasisEditor;
     commands: OasisCommandRegistry;
@@ -12,24 +14,62 @@ export interface OasisCommandContext {
     getDocument(): EditorState["document"];
     getSelection(): EditorState["selection"];
 }
+/**
+ * A single command — an action that can be executed and optionally refreshed for state.
+ * @typeParam TPayload - The command's payload type.
+ * @typeParam TResult - The command's result type.
+ */
 export interface OasisCommand<TPayload = unknown, TResult = unknown> {
     execute: (payload?: TPayload, context?: OasisCommandContext) => TResult;
     refresh?: (payload?: TPayload, context?: OasisCommandContext) => CommandState;
 }
+/** Registry for named commands, providing register, lookup, execution, and state queries. */
 export interface OasisCommandRegistry {
+    /**
+     * Registers a command by name.
+     * @param name - The command name.
+     * @param command - The command implementation.
+     */
     register: <TPayload = unknown, TResult = unknown>(name: string, command: OasisCommand<TPayload, TResult>) => void;
+    /** @param name - The command name to unregister. */
     unregister: (name: string) => void;
+    /**
+     * @param name - The command name.
+     * @returns The command implementation, or undefined.
+     */
     get: (name: string) => OasisCommand | undefined;
+    /**
+     * @param name - The command name.
+     * @returns Whether the command is registered.
+     */
     has: (name: string) => boolean;
+    /**
+     * Executes a registered command.
+     * @param name - The command name.
+     * @param payload - Optional payload.
+     * @returns The command's result.
+     */
     execute: <TPayload = unknown, TResult = unknown>(name: string, payload?: TPayload) => TResult;
+    /**
+     * @param name - The command name.
+     * @param payload - Optional payload.
+     * @returns Whether the command can execute in the current state.
+     */
     canExecute: (name: string, payload?: unknown) => boolean;
+    /**
+     * @param name - The command name.
+     * @param payload - Optional payload.
+     * @returns The command's reactive state.
+     */
     state: (name: string, payload?: unknown) => CommandState;
 }
+/** Reactive state of a command: whether it is enabled, active, and any associated value. */
 export interface CommandState {
     isEnabled: boolean;
     isActive?: boolean;
     value?: unknown;
 }
+/** Core editor interface exposed to plugins and the runtime. */
 export interface OasisEditor {
     readonly state: EditorState;
     readonly commands: OasisCommandRegistry;
@@ -38,7 +78,13 @@ export interface OasisEditor {
     once: (event: string, callback: (...args: unknown[]) => void) => Unsubscribe;
     off: (event: string, callback: (...args: unknown[]) => void) => void;
 }
+/** A plugin reference — either a plugin name string or a plugin instance. */
 export type PluginReference = string | OasisPlugin;
+/**
+ * Toolbar/menu contribution descriptor. Contributions dispatch exclusively
+ * through the command registry — register the command in `commands`, then
+ * reference it here by name. There is no inline-callback escape hatch.
+ */
 export interface PluginAction {
     id: string;
     command: CommandRef;
@@ -50,14 +96,18 @@ export interface PluginAction {
     ribbonGroupResize?: RibbonGroupResizePolicy;
     order?: number;
 }
+/** Menu item contribution extending {@link PluginAction} with path, shortcut, and separator. */
 export interface PluginMenuItem extends PluginAction {
     path: string;
     shortcut?: string;
     separator?: boolean;
     labelKey?: string;
 }
+/** Whether a floating action is scoped to the editor container or the viewport. */
 export type FloatingActionScope = "container" | "viewport";
+/** Placement options for floating action buttons. */
 export type FloatingActionPlacement = "bottom-right" | "bottom-left" | "top-right" | "top-left";
+/** Contribution descriptor for a floating action button. */
 export interface FloatingActionContribution extends PluginAction {
     label?: string;
     labelKey?: string;
@@ -66,11 +116,14 @@ export interface FloatingActionContribution extends PluginAction {
     placement?: FloatingActionPlacement;
     order?: number;
 }
+/** How a side panel is displayed: docked alongside the editor or overlaid on top. */
 export type SidePanelMode = "dock" | "overlay";
+/** Extended render context passed to UI contributions. */
 export interface PluginUiRenderContext extends OasisCommandContext {
     panelId?: string;
     closePanel?: () => void;
 }
+/** Contribution descriptor for a side panel added by a plugin. */
 export interface SidePanelContribution {
     id: string;
     title: string;
@@ -81,15 +134,18 @@ export interface SidePanelContribution {
     order?: number;
     render: (context: PluginUiRenderContext) => JSX.Element;
 }
+/** UI contributions a plugin can provide: floating actions and side panels. */
 export interface OasisPluginUiContributions {
     floatingActions?: FloatingActionContribution[];
     sidePanels?: SidePanelContribution[];
 }
+/** Snapshot of the current plugin UI state. */
 export interface OasisPluginUiSnapshot {
     floatingActions: FloatingActionContribution[];
     sidePanels: SidePanelContribution[];
     activeSidePanelId: string | null;
 }
+/** Registry for plugin-contributed UI elements. */
 export interface OasisPluginUiRegistry {
     registerFloatingAction(contribution: FloatingActionContribution): Unsubscribe;
     registerSidePanel(contribution: SidePanelContribution): Unsubscribe;
@@ -99,6 +155,10 @@ export interface OasisPluginUiRegistry {
     getSnapshot(): OasisPluginUiSnapshot;
     onChange(callback: () => void): Unsubscribe;
 }
+/**
+ * An Oasis editor plugin. Plugins extend the editor with custom commands,
+ * keymaps, toolbar items, menu items, and UI contributions.
+ */
 export interface OasisPlugin {
     name: string;
     requires?: PluginReference[];

package/dist/import/DocumentFormatImporter.d.ts

@@ -6,21 +6,37 @@ import { EditorDocument } from '../core/model.js';
  * specific file format.
  */
 export type ImportStage = "opening" | "parsing" | "finishing";
+/**
+ * Callback type for reporting import progress.
+ * @param stage - The current import stage.
+ * @param progress - Optional progress fraction (0-1).
+ */
 export type ImportProgressReporter = (stage: ImportStage, progress?: number) => void;
 /**
  * A pluggable document format importer. Adding support for a new format means
  * implementing this interface and registering it — no consumer of the import
- * pipeline (controller, UI) needs to change (Open/Closed, Dependency Inversion).
+ * pipeline (controller, UI) needs to change.
  */
 export interface DocumentFormatImporter {
     /** Stable identifier, e.g. "docx" or "html". */
     readonly id: string;
     /** File extensions handled, lowercase and dot-prefixed, e.g. [".html", ".htm"]. */
     readonly accept: readonly string[];
-    /** Whether this importer can handle the given file (by extension). */
+    /**
+     * @param file - The file to check.
+     * @returns Whether this importer can handle the given file (by extension).
+     */
     matches(file: File): boolean;
-    /** Parse the raw bytes into an editor document. */
+    /**
+     * Parse the raw bytes into an editor document.
+     * @param buffer - The file contents as an ArrayBuffer.
+     * @param onProgress - Optional progress reporter.
+     * @returns The parsed document.
+     */
     import(buffer: ArrayBuffer, onProgress?: ImportProgressReporter): Promise<EditorDocument>;
 }
-/** Returns the lowercase dot-extension of a file name, e.g. ".html". */
+/**
+ * @param fileName - The file name.
+ * @returns The lowercase dot-extension of a file name, e.g. ".html".
+ */
 export declare function fileExtension(fileName: string): string;

package/dist/import/documentImporterRegistry.d.ts

@@ -1,6 +1,10 @@
 import { DocumentFormatImporter } from './DocumentFormatImporter.js';
 
-/** Finds the importer that can handle the given file, if any. */
+/**
+ * Finds the importer that can handle the given file.
+ * @param file - The file to check.
+ * @returns The matching importer, or undefined.
+ */
 export declare function resolveImporterForFile(file: File): DocumentFormatImporter | undefined;
-/** Comma-separated extension list for an `<input type="file" accept>`. */
+/** @returns A comma-separated extension list for an `<input type="file" accept>`. */
 export declare function importFileAccept(): string;