@pixerate/editor-react 0.11.0 → 0.12.0

package/dist/index.d.cts

@@ -1,11 +1,12 @@
 import * as _tiptap_core from '@tiptap/core';
 import { Editor } from '@tiptap/core';
 import * as _pixerate_editor from '@pixerate/editor';
-import { Template, ColorGradient, RichTextPresetOptions, HistoryState, HistoryManager, Command, HistoryManagerOptions, SpreadsheetControllerOptions, SpreadsheetDocument, CellCoordinate, CellRange, SpreadsheetController, SpreadsheetColumn, SpreadsheetRow, SpreadsheetDataSource, CellData, EditorSlotsMap } from '@pixerate/editor';
-export { ColorGradient, Command, DirtyTracker, DirtyTrackerOptions, HistoryManager, HistoryManagerOptions, HistoryState, RichTextPresetOptions, Template, TemplateVersion, Token, TokenType, createDirtyTracker, createHistoryManager, defaultIsEqual } from '@pixerate/editor';
+import { Template, ColorGradient, FileImportOptions, RichTextPresetOptions, RichClipboardOptions, HistoryState, HistoryManager, Command, HistoryManagerOptions, FileImportState, FileImportController, FileImportControllerOptions, PromptValues, OutlineSnapshot, OutlineHeading, SpreadsheetControllerOptions, CellRange, SpreadsheetDocument, CellCoordinate, SpreadsheetController, SpreadsheetColumn, SpreadsheetRow, SpreadsheetDataSource, CellData, SpreadsheetMenuItem, SpreadsheetRowGroup, SpreadsheetViewColumn, 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 { UseEditorOptions, EditorContentProps as EditorContentProps$1 } from '@tiptap/react';
+import { ToolRegistry, AgentToolProvider } from '@pixerate/editor/agent';
 import * as React$1 from 'react';
-import React__default from 'react';
+import React__default, { RefObject } from 'react';
 import { BubbleMenuPluginProps } from '@tiptap/extension-bubble-menu';
 export { ImageEditor, ImageEditorProps, UseImageEditorReturn, useImageEditor } from './image-editor/index.cjs';
 import '@pixerate/editor/image-editor';
@@ -58,11 +59,28 @@ interface UsePromptEditorProps {
     jsonVariables?: string[];
     /** Animation speed for gradient decorations */
     speed?: number;
+    /**
+     * Import text from .md, .html, .txt and .rtf files dropped onto the editor
+     * (opt-in). Content is always inserted as plain text. Pasting keeps the
+     * plain-text paste handler, so pasted files are not imported.
+     */
+    fileImport?: Omit<FileImportOptions, "asPlainText"> | boolean;
 }
-declare function usePromptEditor({ content, onContentChange, templates, templateColorMap: userColorMap, isEditing, placeholder, className, onEscape, onKeyDown, onSelectionChange, onSlashCommandMatch, clearSlashCommand, slashCommandActive, onMilestone, containerId, jsonVariables, speed, }: UsePromptEditorProps): _tiptap_core.Editor | null;
+declare function usePromptEditor({ content, onContentChange, templates, templateColorMap: userColorMap, isEditing, placeholder, className, onEscape, onKeyDown, onSelectionChange, onSlashCommandMatch, clearSlashCommand, slashCommandActive, onMilestone, containerId, jsonVariables, speed, fileImport, }: UsePromptEditorProps): _tiptap_core.Editor | null;
 
 interface UseRichEditorProps extends UseEditorOptions {
     richTextOptions?: RichTextPresetOptions;
+    /**
+     * Import .md, .html, .txt and .rtf files dropped or pasted into the editor
+     * at the drop position (opt-in; same as `richTextOptions.fileImport`).
+     */
+    fileImport?: FileImportOptions | boolean;
+    /**
+     * Copy/paste lossless ProseMirror slices between editors via the
+     * `application/x.pixerate.document+json` clipboard type (opt-in; same as
+     * `richTextOptions.richClipboard`).
+     */
+    richClipboard?: RichClipboardOptions | boolean;
 }
 /**
  * Hook to initialize a TipTap rich-text editor instance with pre-configured extensions.
@@ -163,6 +181,32 @@ interface HistoryShortcutsOptions {
  */
 declare function useHistoryShortcuts(manager: HistoryManager, options?: HistoryShortcutsOptions): void;
 
+interface UseFileImportResult extends FileImportState {
+    /** Value for `<input type="file" accept={…}>`. */
+    accept: string;
+    /** Opens the browser file picker and imports the chosen files at the selection. */
+    openFilePicker: FileImportController["openFilePicker"];
+    /** Imports files (e.g. from your own `<input>` or drop zone) at `at` or the selection. */
+    importFiles: FileImportController["importFiles"];
+}
+/**
+ * Imports markdown, HTML, plain-text and RTF files (or anything registered
+ * with `registerImportAdapter` for the `document` target) into an editor.
+ * Pair it with `useEditor({ fileImport: true })` to also accept dropped files.
+ */
+declare function useFileImport(editor: Editor | null | undefined, options?: FileImportControllerOptions): UseFileImportResult;
+
+/**
+ * Registers a tool provider with a `ToolRegistry` while the component is
+ * mounted and unregisters it on unmount (the registry then announces the
+ * change through `onListChanged`).
+ *
+ * Memoize the provider (e.g. `useMemo(() => createRichTextToolProvider(editor,
+ * { id }), [editor])`): a new provider object re-registers it. Pass `null`
+ * while it isn't ready.
+ */
+declare function useAgentToolProvider(registry: ToolRegistry | null | undefined, provider: AgentToolProvider | null | undefined): void;
+
 interface EditorContentProps extends EditorContentProps$1 {
     className?: string;
 }
@@ -188,6 +232,13 @@ interface TemplateRendererProps {
     templateColorMap?: Map<string, ColorGradient>;
     /** Whether to resolve nested templates recursively before displaying */
     resolve?: boolean;
+    /** Template version bindings used when `resolve` is set */
+    bindings?: Record<string, string>;
+    /**
+     * Variable values. When set, variables show their value (or default),
+     * sections whose condition fails are hidden, and section tags are dropped.
+     */
+    values?: PromptValues;
     /** Custom class name for the wrapper */
     className?: string;
     /** Click callback for template badges */
@@ -197,7 +248,109 @@ interface TemplateRendererProps {
 }
 declare const TemplateRenderer: React__default.FC<TemplateRendererProps>;
 
+interface VariableFormProps {
+    /** Prompt whose variables become form fields */
+    content: string;
+    /** Templates searched recursively for further variables */
+    templates?: Template[];
+    /** Template version bindings */
+    bindings?: Record<string, string>;
+    /** Entered text per variable (controlled). Omit to let the form keep its own state. */
+    values?: Record<string, string>;
+    /** Initial entered text when uncontrolled */
+    defaultValues?: Record<string, string>;
+    /**
+     * Called on every edit with the values to resolve with (blank fields
+     * dropped so defaults apply) and the raw entered text.
+     */
+    onChange?: (values: PromptValues, entered: Record<string, string>) => void;
+    /** Custom class name for the wrapper */
+    className?: string;
+}
+/**
+ * Renders one input per prompt variable: labelled with its description,
+ * using its default as the placeholder. Variables only used by `{?name}`
+ * conditions render as checkboxes.
+ */
+declare const VariableForm: React__default.FC<VariableFormProps>;
+
+/**
+ * Subscribes to an editor's heading outline. Returns the headings (flat and
+ * nested) and the id of the heading whose section contains the selection.
+ * Re-renders only when the outline or the active heading changes.
+ *
+ * Install the `Outline` extension (`richTextOptions: { outline: true }`) for
+ * stable heading ids; without it, headings are still listed.
+ */
+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__default.ReactNode;
+    /** Content shown when the document has no headings. */
+    emptyState?: React__default.ReactNode;
+    /** Deepest heading level listed. Defaults to 6. */
+    maxLevel?: number;
+    /** Whether clicking an entry focuses the editor. Defaults to `true`. */
+    focusOnNavigate?: boolean;
+    /** Custom class name for the wrapper. */
+    className?: string;
+    /** Class name for each entry button. */
+    itemClassName?: string;
+    /** Class name added to the entry of the section containing the selection. */
+    activeItemClassName?: string;
+    /** Called after navigating to a heading. */
+    onNavigate?: (heading: OutlineHeading) => void;
+}
+/**
+ * Navigation sidebar listing the document's headings (Word's Navigation pane).
+ * Clicking an entry moves the caret to that heading; the entry for the
+ * section containing the selection is highlighted.
+ */
+declare const OutlinePanel: React__default.FC<OutlinePanelProps>;
+
 declare function useSpreadsheetEditor(options?: SpreadsheetControllerOptions): {
+    viewModel: _pixerate_editor.SpreadsheetViewModel;
+    undo: () => void;
+    redo: () => void;
+    sortRows: (keys: _pixerate_editor.SortKey[], options?: {
+        range?: CellRange | null;
+    }) => boolean;
+    getFilterState: () => _pixerate_editor.SpreadsheetFilterState;
+    setFilterRules: (rules: _pixerate_editor.NewFilterRule[]) => void;
+    addFilterRule: (rule: _pixerate_editor.NewFilterRule) => string;
+    updateFilterRule: (ruleId: string, changes: Partial<Omit<_pixerate_editor.FilterRule, "id">>) => void;
+    removeFilterRule: (ruleId: string) => void;
+    clearFilters: () => void;
+    setFiltersEnabled: (enabled: boolean) => void;
+    toggleFilters: () => void;
+    setHeaderRowCount: (count: number) => void;
+    setFooterRowCount: (count: number) => void;
+    setHeaderColumnCount: (count: number) => void;
+    setFrozenRowCount: (count: number) => void;
+    setFrozenColumnCount: (count: number) => void;
+    hideRows: (indices: number[]) => void;
+    unhideRows: (indices: number[]) => void;
+    hideColumns: (indices: number[]) => void;
+    unhideColumns: (indices: number[]) => void;
+    unhideAll: () => void;
+    getMerges: () => CellRange[];
+    getMergeAt: (row: number, col: number) => CellRange | null;
+    mergeCells: (range?: CellRange | null) => boolean;
+    unmergeCells: (range?: CellRange | null) => boolean;
+    autofill: (source: CellRange, target: CellRange) => boolean;
+    groupRowsBy: (colId: string, summaries?: _pixerate_editor.GroupSummary[]) => void;
+    ungroupRows: () => void;
+    setGroupSummary: (colId: string, aggregate: _pixerate_editor.GroupAggregate | null) => void;
+    setGroupCollapsed: (key: string, collapsed: boolean) => void;
+    toggleGroupCollapsed: (key: string) => void;
+    getGroups: () => _pixerate_editor.SpreadsheetRowGroup[];
+    transposeRange: (range?: CellRange | null) => boolean;
+    exportToCsv: (options?: _pixerate_editor.CsvExportOptions) => string;
+    importFromCsv: (csv: string, options?: _pixerate_editor.CsvImportOptions) => void;
+    copyToClipboardData: (range?: CellRange | null) => _pixerate_editor.SpreadsheetClipboardData;
+    pasteClipboardData: (source: _pixerate_editor.SpreadsheetClipboardSource, target?: _pixerate_editor.CellPosition) => boolean;
     document: SpreadsheetDocument;
     activeCell: CellCoordinate | null;
     selectedRange: CellRange | null;
@@ -226,8 +379,6 @@ declare function useSpreadsheetEditor(options?: SpreadsheetControllerOptions): {
     recalculateAll: () => void;
     exportToTsv: (range?: CellRange | null) => string;
     importFromTsv: (data: string) => void;
-    undo: () => void;
-    redo: () => void;
 };
 
 interface SpreadsheetEditorProps {
@@ -244,6 +395,75 @@ interface SpreadsheetEditorProps {
 }
 declare const SpreadsheetEditor: React__default.FC<SpreadsheetEditorProps>;
 
+interface SpreadsheetContextMenuProps {
+    items: SpreadsheetMenuItem[];
+    x: number;
+    y: number;
+    onClose: () => void;
+}
+/** The table context menu (sort, filter, freeze, hide, merge, categories, transpose). */
+declare const SpreadsheetContextMenu: React__default.FC<SpreadsheetContextMenuProps>;
+
+interface SpreadsheetGroupRowProps {
+    group: SpreadsheetRowGroup;
+    columns: SpreadsheetViewColumn[];
+    /** Column the rows are grouped by: shows the group label and toggle. */
+    groupColId: string;
+    onToggle: (key: string) => void;
+    /** Render a trailing cell for the "add column" column. */
+    trailingCell?: boolean;
+}
+/** A category header row: collapse toggle, label, row count and per-column summaries. */
+declare const SpreadsheetGroupRow: React__default.FC<SpreadsheetGroupRowProps>;
+
+type SpreadsheetState = ReturnType<typeof useSpreadsheetEditor>;
+/**
+ * Copy and paste for the grid. Copy writes TSV, an HTML table and the
+ * lossless `application/x.pixerate.spreadsheet+json` format; paste prefers
+ * that format, then HTML, then TSV.
+ *
+ * The listeners are on `document`: with no text selection the browser fires
+ * `copy`/`paste` at `<body>`, not at the focused grid. Text inputs inside the
+ * grid keep native copy/paste.
+ */
+declare function useSpreadsheetClipboard(gridRef: RefObject<HTMLElement | null>, state: SpreadsheetState, readOnly: boolean): {
+    copyShortcutFallback: () => void;
+};
+/**
+ * Fill handle dragging: press on the handle, move over cells, release to
+ * autofill from the selection into the dragged range (one undo step).
+ */
+declare function useFillHandle(state: SpreadsheetState): {
+    fillTarget: CellRange | null;
+    isFilling: boolean;
+    startFill: (e: {
+        preventDefault(): void;
+        stopPropagation(): void;
+    }) => void;
+    extendFill: (row: number, col: number) => void;
+};
+
+interface FormulaHintsProps {
+    /** The input being edited (a cell editor or the formula bar). */
+    inputRef: React__default.RefObject<HTMLInputElement | null>;
+    /** The input's current value. */
+    value: string;
+    /** Called with the new value when a suggestion is accepted. */
+    onAccept: (value: string) => void;
+    /** Maximum number of function suggestions (default 8). */
+    limit?: number;
+}
+/**
+ * Formula autocomplete for an input: while the value starts with `=`, lists
+ * functions matching the name at the caret (name, signature, description) and,
+ * inside a call, shows the signature with the current argument highlighted.
+ *
+ * Keys are handled on the input itself, before the grid sees them: ArrowUp /
+ * ArrowDown move the selection, Tab accepts it, Escape closes the list.
+ * Enter is left alone so it still commits the cell.
+ */
+declare const FormulaHints: React__default.FC<FormulaHintsProps>;
+
 interface EditorSlotsProviderProps {
     slots?: Partial<EditorSlotsMap>;
     children: React__default.ReactNode;
@@ -257,4 +477,69 @@ declare function EditorSlotsProvider({ slots, children }: EditorSlotsProviderPro
  */
 declare function useEditorSlots(): EditorSlotsMap;
 
-export { BubbleMenu, type BubbleMenuProps, EditorContent, type EditorContentProps, EditorSlotsProvider, type EditorSlotsProviderProps, type HistoryShortcutsOptions, SpreadsheetEditor, type SpreadsheetEditorProps, TemplateRenderer, type TemplateRendererProps, type UseDismissGuardOptions, type UseDismissGuardReturn, type UseHistoryResult, type UseNavigationGuardOptions, type UseNavigationGuardReturn, type UsePromptEditorProps, type UseRichEditorProps, useDismissGuard, useEditor, useEditorSlots, useHistory, useHistoryShortcuts, useNavigationGuard, usePromptEditor, useSpreadsheetEditor };
+interface UseCommentsResult extends CommentStoreSnapshot {
+    store: CommentStore | null;
+}
+/**
+ * Subscribes to a comment store: pass the store itself, or an editor using
+ * the `Comments` extension (`null` while the editor is being created).
+ */
+declare function useComments(source: Editor | CommentStore | null | undefined): UseCommentsResult;
+interface UseTrackChangesResult extends TrackChangesSnapshot {
+    currentChange: TrackedChange | null;
+    setEnabled: (enabled: boolean) => void;
+    toggle: () => void;
+    accept: (id: string) => void;
+    reject: (id: string) => void;
+    acceptAll: () => void;
+    rejectAll: () => void;
+    next: () => void;
+    previous: () => void;
+}
+/**
+ * Subscribes to the tracked-change state of an editor using the
+ * `TrackChanges` extension and exposes its commands.
+ */
+declare function useTrackChanges(editor: Editor | null | undefined): UseTrackChangesResult;
+
+interface CommentsPanelProps {
+    editor: Editor | null;
+    /** Defaults to the store of the editor's `Comments` extension. */
+    store?: CommentStore;
+    /** Author of replies. Defaults to the `Comments` extension's author. */
+    author?: ReviewAuthor;
+    /** Initially show resolved threads. */
+    showResolved?: boolean;
+    className?: string;
+    formatTime?: (timestamp: number) => string;
+    emptyMessage?: string;
+}
+/**
+ * Lists comment threads with reply, resolve and delete actions. Clicking a
+ * 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__default.FC<CommentsPanelProps>;
+
+interface ReviewToolbarProps {
+    editor: Editor | null;
+    className?: string;
+}
+/**
+ * Toolbar for tracked changes: toggle tracking, step through changes, and
+ * accept or reject the current change or all changes.
+ */
+declare const ReviewToolbar: React__default.FC<ReviewToolbarProps>;
+
+interface CommentButtonProps {
+    editor: Editor | null;
+    className?: string;
+    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__default.FC<CommentButtonProps>;
+
+export { BubbleMenu, type BubbleMenuProps, CommentButton, type CommentButtonProps, CommentsPanel, type CommentsPanelProps, EditorContent, type EditorContentProps, EditorSlotsProvider, type EditorSlotsProviderProps, FormulaHints, type FormulaHintsProps, type HistoryShortcutsOptions, OutlinePanel, type OutlinePanelProps, ReviewToolbar, type ReviewToolbarProps, SpreadsheetContextMenu, type SpreadsheetContextMenuProps, SpreadsheetEditor, type SpreadsheetEditorProps, SpreadsheetGroupRow, type SpreadsheetGroupRowProps, 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, useFillHandle, useHistory, useHistoryShortcuts, useNavigationGuard, useOutline, usePromptEditor, useSpreadsheetClipboard, useSpreadsheetEditor, useTrackChanges };