@pixerate/editor-react 0.14.0 → 0.16.0

package/dist/index.d.cts

@@ -1,15 +1,22 @@
 import * as _tiptap_core from '@tiptap/core';
 import { Editor } from '@tiptap/core';
-import { Template, ColorGradient, FileImportOptions, RichTextPresetOptions, RichClipboardOptions, HistoryState, HistoryManager, Command, HistoryManagerOptions, FileImportState, FileImportController, FileImportControllerOptions, PromptValues, OutlineSnapshot, OutlineHeading, EditorSlotsMap, CommentStoreSnapshot, CommentStore, TrackChangesSnapshot, TrackedChange, ReviewAuthor } from '@pixerate/editor';
-export { ColorGradient, Command, DirtyTracker, DirtyTrackerOptions, HistoryManager, HistoryManagerOptions, HistoryState, OutlineHeading, OutlineSnapshot, OutlineTreeItem, PromptDiagnostic, PromptValues, RichTextPresetOptions, Template, TemplateVersion, Token, TokenType, VariableFormField, createDirtyTracker, createHistoryManager, defaultIsEqual } from '@pixerate/editor';
+import { Template, ColorGradient, FileImportOptions, RichTextPresetOptions, RichClipboardOptions, HistoryState, HistoryManager, HistoryEntry, Command, MergedExecutionOptions, HistoryMark, HistoryManagerOptions, DirtyTrackerOptions, DirtyTracker, FileImportState, FileImportController, FileImportControllerOptions, PromptValues, ParseDataSourceOptions, MergeRecordsOptions, MergeRecordsResult, MergeDataSource, MergeRecord, OutlineSnapshot, OutlineHeading, EditorSlotsMap, CommentStoreSnapshot, CommentStore, TrackChangesSnapshot, TrackedChange, ReviewAuthor, CompareSummary, CompareSource, EditorCompareOptions, FindReplaceSnapshot, FindReplaceMode, FindOptions } from '@pixerate/editor';
+export { BindDirtyToHistoryOptions, ColorGradient, Command, CompareSource, CompareSummary, DirtyTracker, DirtyTrackerOptions, EditorCompareOptions, HistoryDirtyBinding, HistoryEntry, HistoryManager, HistoryManagerOptions, HistoryMark, HistoryState, MergeDataSource, MergeOutput, MergeRecord, MergeRecordsResult, MergedExecutionOptions, OutlineHeading, OutlineSnapshot, OutlineTreeItem, PromptDiagnostic, PromptValues, RichTextPresetOptions, Template, TemplateVersion, Token, TokenType, VariableFormField, bindDirtyToHistory, createDirtyTracker, createHistoryManager, defaultIsEqual, withoutDirty } from '@pixerate/editor';
 import { UseEditorOptions, EditorContentProps as EditorContentProps$1 } from '@tiptap/react';
+import { HistoryManager as HistoryManager$1 } from '@pixerate/editor/history';
 import { ToolRegistry, AgentToolProvider } from '@pixerate/editor/agent';
-import React$1 from 'react';
+import React__default from 'react';
 import { BubbleMenuPluginProps } from '@tiptap/extension-bubble-menu';
 export { FormulaHints, FormulaHintsProps, SpreadsheetContextMenu, SpreadsheetContextMenuProps, SpreadsheetEditor, SpreadsheetEditorProps, SpreadsheetGroupRow, SpreadsheetGroupRowProps, useFillHandle, useSpreadsheetClipboard, useSpreadsheetEditor } from './spreadsheet/index.cjs';
-export { ImageEditor, ImageEditorProps, UseImageEditorReturn, useImageEditor } from './image-editor/index.cjs';
+export { AdjustmentLayersPanel, AdjustmentLayersPanelProps, ControlSlider, ControlSliderProps, CurvesEditor, CurvesEditorProps, Histogram, HistogramProps, ImageEditor, ImageEditorProps, UseImageEditorReturn, useImageEditor, useImageHistogram } from './image-editor/index.cjs';
+export { CommandPalette, CommandPaletteProps, UseCommandPaletteOptions, UseCommandPaletteResult, UseCommandShortcutsOptions, useCommandPalette, useCommandShortcuts, useRegisterCommands } from './commands/index.cjs';
+export { RecoveryPrompt, RecoveryPromptProps, UseAutosaveOptions, UseAutosaveResult, useAutosave } from './persistence/index.cjs';
+export { GenerationSettings, GenerationSettingsProps, JobProgress, JobProgressProps, UseJobProgressOptions, useGenerationPlan, useJobProgress } from './generation/index.cjs';
 import '@pixerate/editor/spreadsheet';
 import '@pixerate/editor/image-editor';
+import '@pixerate/editor/commands';
+import '@pixerate/editor/persistence';
+import '@pixerate/editor/generation';
 
 interface UsePromptEditorProps {
     /**
@@ -144,14 +151,23 @@ declare function useDismissGuard({ isDirty, enabled, onDismiss, }: UseDismissGua
 
 interface UseHistoryResult extends HistoryState {
     manager: HistoryManager;
+    /** History panel rows (undo steps, then redo steps). */
+    entries: HistoryEntry[];
     undo: () => boolean;
     redo: () => boolean;
     clear: () => void;
     execute: (command: Command) => void;
-    executeMerged: (command: Command, options?: {
-        windowMs?: number;
-    }) => void;
+    executeMerged: (command: Command, options?: MergedExecutionOptions) => void;
     batch: (name: string, fn: () => void) => void;
+    /** Undoes / redoes until the entry at `index` is current (`-1` = before all). */
+    goTo: (index: number) => number;
+    /** Captures the current point, e.g. when a drag starts. */
+    mark: () => HistoryMark;
+    /** Takes back every step since `mark` without leaving redo (Escape-cancel). */
+    revertTo: (mark: HistoryMark) => number;
+    /** Joins every merged execute into one step until `endGesture`. */
+    beginGesture: (key: string) => void;
+    endGesture: () => void;
 }
 /**
  * React hook that subscribes to a HistoryManager instance.
@@ -160,6 +176,33 @@ interface UseHistoryResult extends HistoryState {
  */
 declare function useHistory(managerOrOptions?: HistoryManager | HistoryManagerOptions): UseHistoryResult;
 
+interface UseHistoryDirtyOptions<T> extends DirtyTrackerOptions<T> {
+    /** The history whose changes re-check the document. */
+    history: HistoryManager;
+    /** Reads the current document value (the latest function is always used). */
+    getValue: () => T;
+    /** Existing tracker to drive (read on first render only). */
+    tracker?: DirtyTracker<T>;
+}
+interface UseHistoryDirtyResult<T> {
+    /** Whether the document differs from the saved state. Feed it to `useNavigationGuard`. */
+    isDirty: boolean;
+    /** Marks the current document as saved. */
+    markClean: () => void;
+    /** Runs a load / restore without marking the document dirty (re-entrant). */
+    suppress: <R>(fn: () => R) => R;
+    /** Re-checks after a change made outside the history. */
+    refresh: () => boolean;
+    tracker: DirtyTracker<T>;
+}
+/**
+ * Dirty-vs-saved tracking bound to a HistoryManager: undoing back to the saved
+ * state makes the document clean again, selection/viewport changes can be
+ * ignored with `normalize`, and programmatic loads can be wrapped in `suppress`.
+ * Options other than `getValue` and `history` are read on first render only.
+ */
+declare function useHistoryDirty<T>(options: UseHistoryDirtyOptions<T>): UseHistoryDirtyResult<T>;
+
 interface HistoryShortcutsOptions {
     /**
      * Whether the keyboard shortcuts are enabled. Defaults to true.
@@ -179,7 +222,7 @@ interface HistoryShortcutsOptions {
  * Attaches keyboard listeners for Undo (Mod+Z) and Redo (Mod+Shift+Z / Mod+Y).
  * Automatically guards against active text inputs and contenteditable editors.
  */
-declare function useHistoryShortcuts(manager: HistoryManager, options?: HistoryShortcutsOptions): void;
+declare function useHistoryShortcuts(manager: HistoryManager$1, options?: HistoryShortcutsOptions): void;
 
 interface UseFileImportResult extends FileImportState {
     /** Value for `<input type="file" accept={…}>`. */
@@ -210,18 +253,18 @@ declare function useAgentToolProvider(registry: ToolRegistry | null | undefined,
 interface EditorContentProps extends EditorContentProps$1 {
     className?: string;
 }
-declare const EditorContent: React$1.FC<EditorContentProps>;
+declare const EditorContent: React__default.FC<EditorContentProps>;
 
 interface BubbleMenuProps {
     editor: Editor | null;
     className?: string;
-    children: React$1.ReactNode;
+    children: React__default.ReactNode;
     tippyOptions?: BubbleMenuPluginProps["tippyOptions"];
     shouldShow?: BubbleMenuPluginProps["shouldShow"];
     pluginKey?: BubbleMenuPluginProps["pluginKey"];
     updateDelay?: BubbleMenuPluginProps["updateDelay"];
 }
-declare const BubbleMenu: React$1.FC<BubbleMenuProps>;
+declare const BubbleMenu: React__default.FC<BubbleMenuProps>;
 
 interface TemplateRendererProps {
     /** Raw prompt or text string to render */
@@ -246,7 +289,7 @@ interface TemplateRendererProps {
     /** Click callback for variable badges */
     onVariableClick?: (variableName: string) => void;
 }
-declare const TemplateRenderer: React$1.FC<TemplateRendererProps>;
+declare const TemplateRenderer: React__default.FC<TemplateRendererProps>;
 
 interface VariableFormProps {
     /** Prompt whose variables become form fields */
@@ -272,7 +315,83 @@ interface VariableFormProps {
  * using its default as the placeholder. Variables only used by `{?name}`
  * conditions render as checkboxes.
  */
-declare const VariableForm: React$1.FC<VariableFormProps>;
+declare const VariableForm: React__default.FC<VariableFormProps>;
+
+interface MergePreviewProps {
+    /** The prompt merged with each record. */
+    content: string;
+    templates?: Template[];
+    bindings?: Record<string, string>;
+    templateColorMap?: Map<string, ColorGradient>;
+    /** Initial CSV / TSV / JSON data source text. */
+    defaultSource?: string;
+    parseOptions?: ParseDataSourceOptions;
+    /** Drop records matching this condition (e.g. `"status=void"`) when merging. */
+    skipIf?: MergeRecordsOptions["skipIf"];
+    /** Separator between merged outputs (default a blank line; `"none"` for nothing). */
+    separator?: string;
+    maxOutputs?: number;
+    /** Called after "Merge all". */
+    onMerge?: (result: MergeRecordsResult) => void;
+    /** Base file name for downloads (default `merged`). */
+    downloadName?: string;
+    className?: string;
+}
+/**
+ * Mail-merge preview: paste or pick a CSV / JSON data source, check the
+ * automatic field mapping, step through records with the resolved prompt
+ * shown by `TemplateRenderer`, and merge every record into text or JSON.
+ */
+declare const MergePreview: React__default.FC<MergePreviewProps>;
+
+interface UseMergePreviewOptions {
+    /** The prompt merged with each record. */
+    template: string;
+    templates?: Template[];
+    bindings?: Record<string, string>;
+    /** Initial CSV / TSV / JSON text. */
+    initialSource?: string;
+    /** How to read the data source text. */
+    parseOptions?: ParseDataSourceOptions;
+    /** Passed to `mergeRecords` by `merge()`. */
+    skipIf?: MergeRecordsOptions["skipIf"];
+    separator?: string;
+    maxOutputs?: number;
+}
+interface MergePreviewState {
+    sourceText: string;
+    setSourceText: (text: string) => void;
+    /** Reads a picked file (CSV, TSV or JSON) into `sourceText`. */
+    loadFile: (file: Blob) => Promise<void>;
+    source: MergeDataSource;
+    /** Variable names the template uses, in order. */
+    variables: string[];
+    /** Variable → field: automatic matches with the user's overrides applied. */
+    mapping: Record<string, string | null>;
+    setFieldMapping: (variable: string, field: string | null) => void;
+    resetMapping: () => void;
+    /** 0-based index of the previewed record. */
+    index: number;
+    count: number;
+    setIndex: (index: number) => void;
+    next: () => void;
+    prev: () => void;
+    record: MergeRecord | undefined;
+    /** Prompt values for the previewed record. */
+    values: PromptValues;
+    /** Merges every record with the current mapping and stores the result. */
+    merge: () => MergeRecordsResult;
+    result: MergeRecordsResult | null;
+    /** The last merge's outputs as text or JSON. */
+    serialize: (format: "text" | "json") => string;
+}
+/**
+ * Headless state for a mail-merge preview (the counterpart of Svelte's
+ * `createMergePreview`): parses a pasted or loaded data source, matches its
+ * fields to the template's variables (editable), steps through records and
+ * merges them all with `mergeRecords`.
+ */
+declare function useMergePreview(options: UseMergePreviewOptions): MergePreviewState;
 
 /**
  * Subscribes to an editor's heading outline. Returns the headings (flat and
@@ -287,9 +406,9 @@ declare function useOutline(editor: Editor | null | undefined): OutlineSnapshot;
 interface OutlinePanelProps {
     editor: Editor | null;
     /** Heading shown above the list. Pass `null` to hide it. */
-    title?: React$1.ReactNode;
+    title?: React__default.ReactNode;
     /** Content shown when the document has no headings. */
-    emptyState?: React$1.ReactNode;
+    emptyState?: React__default.ReactNode;
     /** Deepest heading level listed. Defaults to 6. */
     maxLevel?: number;
     /** Whether clicking an entry focuses the editor. Defaults to `true`. */
@@ -308,16 +427,16 @@ interface OutlinePanelProps {
  * Clicking an entry moves the caret to that heading; the entry for the
  * section containing the selection is highlighted.
  */
-declare const OutlinePanel: React$1.FC<OutlinePanelProps>;
+declare const OutlinePanel: React__default.FC<OutlinePanelProps>;
 
 interface EditorSlotsProviderProps {
     slots?: Partial<EditorSlotsMap>;
-    children: React$1.ReactNode;
+    children: React__default.ReactNode;
 }
 /**
  * Context provider allowing consumers to inject custom design system components into the editor.
  */
-declare function EditorSlotsProvider({ slots, children }: EditorSlotsProviderProps): React$1.JSX.Element;
+declare function EditorSlotsProvider({ slots, children }: EditorSlotsProviderProps): React__default.JSX.Element;
 /**
  * Hook to access injected design system slots.
  */
@@ -365,7 +484,7 @@ interface CommentsPanelProps {
  * thread selects its text in the editor. Threads with an empty body are
  * drafts (e.g. created by `CommentButton`) and show a compose box.
  */
-declare const CommentsPanel: React$1.FC<CommentsPanelProps>;
+declare const CommentsPanel: React__default.FC<CommentsPanelProps>;
 
 interface ReviewToolbarProps {
     editor: Editor | null;
@@ -384,17 +503,76 @@ interface ReviewToolbarProps {
  * of the current one), and accept or reject the current change or all
  * changes.
  */
-declare const ReviewToolbar: React$1.FC<ReviewToolbarProps>;
+declare const ReviewToolbar: React__default.FC<ReviewToolbarProps>;
 
 interface CommentButtonProps {
     editor: Editor | null;
     className?: string;
-    children?: React$1.ReactNode;
+    children?: React__default.ReactNode;
 }
 /**
  * Adds a draft comment on the selection; drop it into a `BubbleMenu`. The
  * draft is completed in `CommentsPanel`.
  */
-declare const CommentButton: React$1.FC<CommentButtonProps>;
+declare const CommentButton: React__default.FC<CommentButtonProps>;
+
+interface UseDocumentCompareResult {
+    /** Summary of the last comparison, or `null`. */
+    summary: CompareSummary | null;
+    /**
+     * Replaces the editor content with the comparison of two versions (nodes,
+     * JSON or HTML) as tracked changes, ready to review with `ReviewToolbar`.
+     * Returns the summary, or `null` without an editor.
+     */
+    compare: (original: CompareSource, revised: CompareSource, options?: EditorCompareOptions) => CompareSummary | null;
+    /** Forgets the last summary. */
+    clear: () => void;
+}
+/**
+ * Compare two document versions into an editor using `TrackChanges`.
+ * `options` are defaults for every comparison.
+ */
+declare function useDocumentCompare(editor: Editor | null | undefined, options?: EditorCompareOptions): UseDocumentCompareResult;
+
+interface UseFindReplaceResult extends FindReplaceSnapshot {
+    /** Whether the editor has the `FindReplace` extension. */
+    available: boolean;
+    matchCount: number;
+    open: boolean;
+    show: (mode?: FindReplaceMode) => void;
+    close: () => void;
+    setQuery: (query: string) => void;
+    setReplacement: (replacement: string) => void;
+    setOptions: (options: Partial<FindOptions>) => void;
+    toggleOption: (option: keyof FindOptions) => void;
+    next: () => void;
+    previous: () => void;
+    replace: () => void;
+    replaceAll: () => void;
+    clear: () => void;
+}
+/**
+ * Subscribes to an editor's Find and Replace state (`FindReplace` extension)
+ * and exposes its commands.
+ */
+declare function useFindReplace(editor: Editor | null | undefined): UseFindReplaceResult;
+
+interface FindReplaceBarProps {
+    editor: Editor | null;
+    className?: string;
+    /** Render even while the find state is closed (default: only after Mod+F / Mod+H / `openFindReplace`). */
+    alwaysOpen?: boolean;
+    /** Show the "More options" toggle (prefix, suffix, ignore punctuation/white space, literal). Default `true`. */
+    showMoreOptions?: boolean;
+    /** Called after the bar closes (Escape or the close button). */
+    onClose?: () => void;
+}
+/**
+ * Word-style find bar for an editor using the `FindReplace` extension: find
+ * and replace fields, option toggles, "3 of 12" counter, previous/next,
+ * Replace and Replace All. Enter / Shift+Enter step through matches, Enter in
+ * the replace field replaces, Mod+Enter replaces all, Escape closes.
+ */
+declare const FindReplaceBar: React__default.FC<FindReplaceBarProps>;
 
-export { BubbleMenu, type BubbleMenuProps, CommentButton, type CommentButtonProps, CommentsPanel, type CommentsPanelProps, EditorContent, type EditorContentProps, EditorSlotsProvider, type EditorSlotsProviderProps, type HistoryShortcutsOptions, OutlinePanel, type OutlinePanelProps, ReviewToolbar, type ReviewToolbarProps, TemplateRenderer, type TemplateRendererProps, type UseCommentsResult, type UseDismissGuardOptions, type UseDismissGuardReturn, type UseFileImportResult, type UseHistoryResult, type UseNavigationGuardOptions, type UseNavigationGuardReturn, type UsePromptEditorProps, type UseRichEditorProps, type UseTrackChangesResult, VariableForm, type VariableFormProps, useAgentToolProvider, useComments, useDismissGuard, useEditor, useEditorSlots, useFileImport, useHistory, useHistoryShortcuts, useNavigationGuard, useOutline, usePromptEditor, useTrackChanges };
+export { BubbleMenu, type BubbleMenuProps, CommentButton, type CommentButtonProps, CommentsPanel, type CommentsPanelProps, EditorContent, type EditorContentProps, EditorSlotsProvider, type EditorSlotsProviderProps, FindReplaceBar, type FindReplaceBarProps, type HistoryShortcutsOptions, MergePreview, type MergePreviewProps, type MergePreviewState, OutlinePanel, type OutlinePanelProps, ReviewToolbar, type ReviewToolbarProps, TemplateRenderer, type TemplateRendererProps, type UseCommentsResult, type UseDismissGuardOptions, type UseDismissGuardReturn, type UseDocumentCompareResult, type UseFileImportResult, type UseFindReplaceResult, type UseHistoryDirtyOptions, type UseHistoryDirtyResult, type UseHistoryResult, type UseMergePreviewOptions, type UseNavigationGuardOptions, type UseNavigationGuardReturn, type UsePromptEditorProps, type UseRichEditorProps, type UseTrackChangesResult, VariableForm, type VariableFormProps, useAgentToolProvider, useComments, useDismissGuard, useDocumentCompare, useEditor, useEditorSlots, useFileImport, useFindReplace, useHistory, useHistoryDirty, useHistoryShortcuts, useMergePreview, useNavigationGuard, useOutline, usePromptEditor, useTrackChanges };