@bikdotai/bik-component-library 0.0.793 → 0.0.795-beta.0

package/dist/cjs/src/editor/BikEditor.types.d.ts

@@ -0,0 +1,709 @@
+/**
+ * ┌─────────────────────────────────────────────────────────────────────────┐
+ * │  PUBLIC API LAYER — zero editor-framework imports                        │
+ * │                                                                           │
+ * │  This file is the consumer contract for BikEditor. It has NO dependency  │
+ * │  on TipTap, Lexical, Slate, or any other rich-text library.              │
+ * │                                                                           │
+ * │  If the underlying editor is ever swapped, ONLY the implementation files  │
+ * │  change — this file, src/editor/index.ts, and all consumer code stay as- │
+ * │  is. The files that would change are:                                     │
+ * │    • BikEditor.tsx        — wires props into the editor instance          │
+ * │    • BikEditor.utils.ts   — HTML / document-state adapters               │
+ * │    • extensions/          — extension / plugin layer                      │
+ * └─────────────────────────────────────────────────────────────────────────┘
+ */
+import React from 'react';
+/**
+ * Opt in to specific editor capabilities. Both default to `false`.
+ *
+ * @example
+ * // Email editor with full rich text support
+ * <BikEditor features={{ richPaste: true, richTypography: true }} />
+ */
+export interface EditorFeatures {
+    /** Preserve HTML formatting on paste. Default: `false`. */
+    richPaste?: boolean;
+    /** Enable font family, font size, text alignment, highlight, subscript, superscript, and image. Default: `false`. */
+    richTypography?: boolean;
+    /**
+     * Restrict which inline marks are active in the editor.
+     * When set, only the listed marks are registered — all others are disabled
+     * (no rendering, no keyboard shortcuts, no paste preservation).
+     * Omit to allow all marks (default).
+     *
+     * @example
+     * // LiveChat: bold only, no italic / underline / strike
+     * features={{ allowedMarks: ['bold'] }}
+     */
+    allowedMarks?: Array<'bold' | 'italic' | 'strike' | 'underline' | 'code'>;
+}
+/**
+ * A named content section placed below the main body, separated by an invisible divider.
+ *
+ * Sections let you split a single editor instance into independently readable
+ * and writable zones — for example: body / signature / forwarded mail.
+ *
+ * @example
+ * sections={[
+ *   { id: 'signature', content: '<p>Best regards,<br/>Alice</p>' },
+ *   { id: 'forwarded', content: '<p>--- Forwarded message ---</p>' },
+ * ]}
+ */
+export interface EditorSection {
+    /**
+     * Unique identifier. Used in ref methods: `getSectionContent(id)`,
+     * `setSectionContent(id, html)`, `focusSection(id)`, `clearSection(id)`.
+     * The string `'body'` is reserved for the main content above all dividers.
+     */
+    id: string;
+    /** Initial HTML content of this section. */
+    content: string;
+}
+/**
+ * Data passed to the `onPaste` callback.
+ * Return `true` from your handler to suppress BikEditor's default paste handling
+ * (rich-paste and plain-text stripping won't run for that event).
+ */
+export interface PasteData {
+    /** All files in the clipboard (images, PDFs, etc.). */
+    files: File[];
+    /** Image files only — a filtered subset of `files`. */
+    images: File[];
+    /** Plain text from the clipboard. */
+    text: string;
+    /** HTML from the clipboard (empty string if the source doesn't provide HTML). */
+    html: string;
+    /** The raw browser ClipboardEvent — for advanced use. */
+    event: ClipboardEvent;
+}
+/**
+ * A custom keyboard shortcut registered with the editor.
+ *
+ * @example
+ * shortcuts={[
+ *   // Mod = Cmd on Mac, Ctrl on Windows/Linux
+ *   { key: 'Enter', modifiers: ['mod'], handler: handleSend },
+ *   { key: 's',     modifiers: ['mod'], handler: handleSave },
+ *   { key: 'k',     modifiers: ['mod', 'shift'], handler: openLinkModal },
+ * ]}
+ */
+export interface KeyboardShortcut {
+    /** Key name. Use the same strings as KeyboardEvent.key, e.g. `'Enter'`, `'s'`, `'k'`. */
+    key: string;
+    /**
+     * Modifier keys.
+     * `'mod'` maps to Cmd on macOS and Ctrl on Windows/Linux — prefer it over
+     * `'ctrl'` for cross-platform shortcuts.
+     */
+    modifiers?: Array<'mod' | 'ctrl' | 'shift' | 'alt'>;
+    /** Called when the shortcut fires. Returning nothing is fine. */
+    handler: () => void;
+}
+/** Content object returned by onChange, onSend, getContent(), and getSectionContent(). */
+export interface EditorSnapshot {
+    /** Serialised HTML. Safe to pass back to setContent() or setSectionContent(). */
+    html: string;
+    /** Plain text, stripped of all marks and block nodes. */
+    text: string;
+    /** True when the document contains no user-visible content. */
+    isEmpty: boolean;
+    /** Character count at this point in time. */
+    characterCount: number;
+}
+/** One item shown in the @agent or #team mention dropdown. */
+export interface MentionItem {
+    /** Unique identifier stored as a node attribute. Used to look up the item later. */
+    id: string | number;
+    /** Display name shown in the dropdown and inserted into the document. */
+    label: string;
+    /** Avatar image URL. Shown in the built-in row when renderMentionItem is not provided. */
+    avatarUrl?: string;
+    /** When true, a green presence dot appears in the built-in row. */
+    isOnline?: boolean;
+    /** Any extra data your app needs. Passed back as-is in onMentionSelected. */
+    meta?: Record<string, unknown>;
+}
+/** One item shown in the / slash-command dropdown. */
+export interface SlashCommandItem {
+    /** Unique identifier. */
+    id: string;
+    /** Short command name shown as the primary label in the menu. */
+    label: string;
+    /** Optional one-line description shown below the label in the built-in row. */
+    description?: string;
+}
+/**
+ * Props passed to the `renderDropdown` function in `MentionConfig`.
+ * `activeIndex` is the keyboard-navigated row — highlight it in your UI.
+ * Call `onSelect(item)` when the user picks one.
+ */
+export interface MentionDropdownRenderProps {
+    items: MentionItem[];
+    /** The text the user typed after the `@` or `#` trigger. */
+    query: string;
+    /**
+     * Index of the currently highlighted row (arrow-key navigation).
+     * The editor manages this automatically — just use it for visual highlighting.
+     */
+    activeIndex: number;
+    /** Call this when the user selects an item (click, touch, etc.). */
+    onSelect: (item: MentionItem) => void;
+}
+/**
+ * Everything related to @ and # mention dropdowns, in one place.
+ *
+ * @example
+ * mentions={{
+ *   agents: [{ id: 1, label: 'Alice', avatarUrl: '...' }],
+ *   teams:  [{ id: 't1', label: 'Support' }],
+ *   onSelect: (item, char) => console.log(char, item),
+ * }}
+ */
+export interface MentionConfig {
+    /** Items shown when the user types `@`. */
+    agents?: MentionItem[];
+    /** Items shown when the user types `#`. */
+    teams?: MentionItem[];
+    /** Called when the user picks an item. `char` is `'@'` or `'#'`. */
+    onSelect?: (item: MentionItem, char: '@' | '#') => void;
+    /**
+     * Custom renderer for each row in the dropdown.
+     * `isActive` is `true` when that row is currently highlighted by keyboard
+     * navigation (arrows move it, Enter selects it). Use it to apply a highlight
+     * style so the user can see which item they're about to select.
+     * Omit to use the built-in avatar + name row.
+     *
+     * Use `renderDropdown` instead when you need a completely different structure.
+     *
+     * @example
+     * renderItem={(item, isActive) => (
+     *   <div style={{ background: isActive ? '#f0f0f0' : undefined }}>
+     *     {item.label}
+     *   </div>
+     * )}
+     */
+    renderItem?: (item: MentionItem, isActive: boolean) => React.ReactNode;
+    /**
+     * Render the entire dropdown yourself instead of individual rows.
+     * The editor still manages keyboard navigation — `activeIndex` tells you
+     * which row is highlighted, and `onSelect(item)` confirms the selection.
+     * Takes priority over `renderItem` when both are provided.
+     *
+     * @example
+     * renderDropdown={({ items, query, activeIndex, onSelect }) => (
+     *   <MyDropdown
+     *     items={items}
+     *     highlightedIndex={activeIndex}
+     *     onPick={onSelect}
+     *   />
+     * )}
+     */
+    renderDropdown?: (props: MentionDropdownRenderProps) => React.ReactNode;
+}
+/**
+ * Props passed to the `renderDropdown` function in `SlashCommandConfig`.
+ */
+export interface SlashCommandDropdownRenderProps {
+    items: SlashCommandItem[];
+    /** The text the user typed after `/`. */
+    query: string;
+    /** Index of the currently highlighted row. Use for visual highlighting. */
+    activeIndex: number;
+    /** Call this when the user selects an item. */
+    onSelect: (item: SlashCommandItem) => void;
+}
+/**
+ * Everything related to the `/` slash-command menu, in one place.
+ *
+ * @example
+ * slashCommands={{
+ *   items: [{ id: 'ai-reply', label: 'AI Reply', description: 'Generate a reply' }],
+ *   onSelect: (cmd) => triggerAI(cmd.id),
+ * }}
+ */
+export interface SlashCommandConfig {
+    /** The list of commands. Filtered client-side as the user types after `/`. */
+    items: SlashCommandItem[];
+    /** Called when the user selects a command. The `/` trigger is removed from the doc. */
+    onSelect?: (command: SlashCommandItem) => void;
+    /**
+     * Custom renderer for each row.
+     * `isActive` is `true` when that row is highlighted by keyboard navigation.
+     * Omit to use the built-in label + description row.
+     *
+     * Use `renderDropdown` instead when you need a completely different structure.
+     */
+    renderItem?: (item: SlashCommandItem, isActive: boolean) => React.ReactNode;
+    /**
+     * Render the entire slash-command dropdown yourself.
+     * The editor manages keyboard navigation — use `activeIndex` to highlight
+     * the active row and call `onSelect(item)` to confirm selection.
+     * Takes priority over `renderItem` when both are provided.
+     *
+     * @example
+     * renderDropdown={({ items, activeIndex, onSelect }) => (
+     *   <MyCmdPalette commands={items} active={activeIndex} onPick={onSelect} />
+     * )}
+     */
+    renderDropdown?: (props: SlashCommandDropdownRenderProps) => React.ReactNode;
+}
+/**
+ * Configuration for how hyperlinks behave in the editor.
+ *
+ * @example
+ * link={{ renderTooltip: ({ href, text, onOpen, onRemove }) => (
+ *   <MyLinkPopover href={href} onOpen={onOpen} onRemove={onRemove} />
+ * )}}
+ */
+export interface LinkConfig {
+    /**
+     * Custom tooltip rendered when the user clicks a link.
+     * Receives the href, display text, bounding rect (for positioning),
+     * and ready-to-call action handlers.
+     * Omit to use the minimal built-in tooltip.
+     */
+    renderTooltip?: (props: LinkTooltipProps) => React.ReactNode;
+}
+/**
+ * Snapshot of all active marks and block types at the current cursor or selection.
+ * Returned by onSelectionChange and ref.getActiveFormats().
+ *
+ * Keep this in component state and pass it to BikEditorToolbar (or your own toolbar)
+ * to keep button active-states in sync.
+ *
+ * @example
+ * const [formats, setFormats] = useState(DEFAULT_ACTIVE_FORMATS);
+ * <BikEditor onSelectionChange={setFormats} ... />
+ * <BikEditorToolbar activeFormats={formats} ... />
+ */
+export interface FormatState {
+    bold: boolean;
+    italic: boolean;
+    underline: boolean;
+    strike: boolean;
+    bulletList: boolean;
+    orderedList: boolean;
+    blockquote: boolean;
+    codeBlock: boolean;
+    /** Non-null when the cursor is inside (or selection spans) a hyperlink. */
+    link: {
+        href: string;
+    } | null;
+    textAlign: 'left' | 'center' | 'right' | 'justify' | null;
+    fontFamily: string | null;
+    fontSize: string | null;
+    /** Active text colour as a CSS colour string, or null if none. */
+    color: string | null;
+    /** Active highlight (background) colour, or null if none. */
+    highlight: string | null;
+    /** True when the cursor/selection is in a superscript. */
+    superscript: boolean;
+    /** True when the cursor/selection is in a subscript. */
+    subscript: boolean;
+}
+export declare const DEFAULT_FORMAT_STATE: FormatState;
+/**
+ * All formatting and insertion commands. Access via `editorRef.current.actions`.
+ *
+ * Every method focuses the editor internally — no need to call `.focus()` first.
+ *
+ * @example
+ * editorRef.current?.actions.toggleBold();
+ * editorRef.current?.actions.setLink('https://example.com', 'Visit example');
+ */
+export interface EditorActions {
+    toggleBold: () => void;
+    toggleItalic: () => void;
+    toggleUnderline: () => void;
+    toggleStrike: () => void;
+    toggleBulletList: () => void;
+    toggleOrderedList: () => void;
+    toggleBlockquote: () => void;
+    toggleCodeBlock: () => void;
+    setTextAlign: (align: 'left' | 'center' | 'right' | 'justify') => void;
+    /** Pass a CSS font-family value, e.g. `'Inter, sans-serif'`. Only works when richTypography is on. */
+    setFontFamily: (font: string) => void;
+    /** Pass a CSS size value, e.g. `'16px'` or `'1.25rem'`. Only works when richTypography is on. */
+    setFontSize: (size: string) => void;
+    /** Sets the text colour. Pass any CSS colour value, e.g. `'#e53e3e'`. */
+    setColor: (color: string) => void;
+    /** Sets the highlight (background) colour. */
+    setHighlight: (color: string) => void;
+    /** Removes the text colour mark from the current selection. */
+    unsetColor: () => void;
+    /** Removes the highlight mark from the current selection. */
+    unsetHighlight: () => void;
+    /**
+     * Applies a hyperlink to the current selection, or updates the link the
+     * cursor is already inside.
+     *
+     * @param href  The URL.
+     * @param text  Optional display text. When provided, the visible text of the
+     *              linked range is replaced atomically in the same undo step.
+     *
+     * @example
+     * actions.setLink('https://example.com');
+     * actions.setLink('https://example.com', 'Visit example');
+     */
+    setLink: (href: string, text?: string) => void;
+    /** Updates only the href of the link at the current cursor. */
+    updateLink: (href: string) => void;
+    /** Removes the link mark but keeps the visible text. */
+    removeLink: () => void;
+    /** Inserts an emoji character at the cursor. */
+    insertEmoji: (emoji: string) => void;
+    /**
+     * Inserts a `{{variableName}}` token at the cursor.
+     * The token renders with a distinct highlight inside the editor.
+     */
+    insertVariable: (variableName: string) => void;
+    /** Inserts arbitrary HTML at the current cursor position. */
+    insertHtml: (html: string) => void;
+    undo: () => void;
+    redo: () => void;
+    canUndo: () => boolean;
+    canRedo: () => boolean;
+    /** Toggles superscript on the selection. Only works when richTypography is on. */
+    toggleSuperscript: () => void;
+    /** Toggles subscript on the selection. Only works when richTypography is on. */
+    toggleSubscript: () => void;
+    /** Inserts an inline image at the cursor. Only works when richTypography is on. */
+    insertImage: (src: string) => void;
+}
+/** Props passed to your renderLinkTooltip render prop. */
+export interface LinkTooltipProps {
+    /** The href of the active link. */
+    href: string;
+    /** The display text of the link. */
+    text: string;
+    /** Bounding rect of the link element — use this to position your popover. */
+    rect: DOMRect;
+    /** Opens the link in a new tab. */
+    onOpen: () => void;
+    /** Removes the link mark but keeps the visible text. */
+    onRemove: () => void;
+    /** Hides the bubble menu. Call this before opening an edit modal so the tooltip doesn't linger. */
+    onHide: () => void;
+}
+/**
+ * Imperative handle exposed by BikEditor.
+ *
+ * Obtain via `useRef<BikEditorRef>()` and pass to `<BikEditor ref={...} />`.
+ * All methods are safe to call after the first render.
+ *
+ * @example
+ * const ref = useRef<BikEditorRef>(null);
+ * <BikEditor ref={ref} ... />
+ * ref.current?.clearContent();
+ * ref.current?.actions.toggleBold();
+ */
+export interface BikEditorRef {
+    /** Moves focus into the editor. */
+    focus: () => void;
+    /** Removes focus from the editor. */
+    blur: () => void;
+    /** Clears the entire document and fires onChange. */
+    clearContent: () => void;
+    /**
+     * Replaces the full document with the given HTML and fires onChange.
+     * Overwrites all sections. Use setSectionContent() / setBodyContent() to
+     * update a single section without touching the others.
+     */
+    setContent: (html: string) => void;
+    /** Inserts HTML at the current cursor position without replacing anything. */
+    insertContent: (html: string) => void;
+    /** Inserts HTML at the very start of the document. */
+    insertAtStart: (html: string) => void;
+    /** Inserts HTML at the very end of the document. */
+    insertAtEnd: (html: string) => void;
+    /**
+     * Appends HTML to the very end of the document without moving the cursor.
+     * Ideal for streaming — call repeatedly with each text chunk.
+     * Use `appendBodyContent` instead if the editor has named sections.
+     *
+     * @example
+     * for await (const chunk of stream) {
+     *   ref.current?.appendContent(chunk);
+     * }
+     */
+    appendContent: (html: string) => void;
+    /** Returns the full document as `{ html, text, isEmpty, characterCount }`. */
+    getContent: () => EditorSnapshot;
+    /**
+     * Returns the raw TipTap document as a plain JSON object.
+     * Useful for traversing node attributes (e.g. extracting mention IDs)
+     * without parsing the serialised HTML.
+     * Returns `null` when the editor is not yet mounted.
+     */
+    getJSON: () => Record<string, unknown> | null;
+    /**
+     * Returns the current cursor / selection position as a `{ from, to }` pair.
+     * When nothing is selected, `from === to` (a collapsed cursor).
+     * Pass the returned value to `insertAtPosition()` to insert at an exact spot.
+     *
+     * @example
+     * const { from } = ref.current?.getCursorPosition() ?? { from: 0, to: 0 };
+     * ref.current?.insertAtPosition(from, '<strong>inserted</strong>');
+     */
+    getCursorPosition: () => {
+        from: number;
+        to: number;
+    };
+    /**
+     * Inserts HTML at an explicit document position rather than at the current cursor.
+     * Use `getCursorPosition()` to get the position, or any value from
+     * `findSectionStartPos` / `findSectionEndPos` if you need section-relative insertion.
+     *
+     * @example
+     * const { from } = ref.current!.getCursorPosition();
+     * ref.current?.insertAtPosition(from, '<em>hello</em>');
+     */
+    insertAtPosition: (pos: number, html: string) => void;
+    /**
+     * Returns the currently selected plain text.
+     * When the cursor is inside a link with nothing selected, returns the full
+     * link text — useful for pre-filling a link modal's text field.
+     */
+    getSelectedText: () => string;
+    /**
+     * Returns the current character count and the configured limit (or null).
+     * Use this to render your own character counter anywhere you like.
+     *
+     * @example
+     * const { count, limit } = ref.current?.getCharacterCount() ?? { count: 0, limit: null };
+     * <span style={{ color: count >= (limit ?? Infinity) ? 'red' : 'inherit' }}>
+     *   {count}{limit != null ? ` / ${limit}` : ''}
+     * </span>
+     */
+    getCharacterCount: () => {
+        count: number;
+        limit: number | null;
+    };
+    /**
+     * Returns content for a named section.
+     * Use `'body'` to get the main content above all section dividers.
+     *
+     * @example
+     * const sig = ref.current?.getSectionContent('signature');
+     */
+    getSectionContent: (sectionId: string) => EditorSnapshot;
+    /**
+     * Replaces the content of a named section without touching other sections.
+     * If the section doesn't exist yet it is appended at the end.
+     *
+     * @example
+     * ref.current?.setSectionContent('signature', '<p>New signature</p>');
+     * ref.current?.setSectionContent('body', rephrased); // same as setBodyContent
+     */
+    setSectionContent: (sectionId: string, html: string) => void;
+    /**
+     * Moves the cursor to the start of a named section.
+     * Use `'body'` to focus the main content area.
+     */
+    focusSection: (sectionId: string) => void;
+    /** Clears all content in a named section (replaces with an empty paragraph). */
+    clearSection: (sectionId: string) => void;
+    /** Shorthand for `getSectionContent('body')`. */
+    getBodyContent: () => EditorSnapshot;
+    /** Shorthand for `setSectionContent('body', html)`. */
+    setBodyContent: (html: string) => void;
+    /**
+     * Atomically sets the body AND all sections in a single editor update.
+     * Sections are laid out in the exact order supplied — use this instead of
+     * multiple `setSectionContent()` calls whenever order matters (e.g. forward
+     * mail where signature must appear before the forwarded thread).
+     *
+     * @example
+     * ref.current?.setBodyAndSections('<p></p>', [
+     *   { id: 'signature', content: '<p>Alice</p>' },
+     *   { id: 'forwarded', content: '<p>--- Forwarded ---</p>' },
+     * ]);
+     */
+    setBodyAndSections: (body: string, sections: Array<{
+        id: string;
+        content: string;
+    }>) => void;
+    /**
+     * Appends HTML to the end of the body section without moving the cursor.
+     * Ideal for streaming AI-generated content — call repeatedly with each chunk.
+     * Does NOT clear existing content; call `setBodyContent('')` first if needed.
+     *
+     * @example
+     * // Stream AI response chunk-by-chunk
+     * ref.current?.setBodyContent('');
+     * for await (const chunk of aiStream) {
+     *   ref.current?.appendBodyContent(chunk);
+     * }
+     */
+    appendBodyContent: (html: string) => void;
+    /**
+     * Inserts HTML at the start of a named section (or `'body'`).
+     * Inserts at the very start of the document when `sectionId` is `'body'`.
+     */
+    insertAtSectionStart: (sectionId: string, html: string) => void;
+    /**
+     * Inserts HTML at the end of a named section (or `'body'`).
+     * For `'body'`, inserts just before the first section divider (or at end of doc).
+     */
+    insertAtSectionEnd: (sectionId: string, html: string) => void;
+    /** Returns a snapshot of all active marks at the current cursor or selection. */
+    getActiveFormats: () => FormatState;
+    /** All formatting and insertion commands. See EditorActions. */
+    actions: EditorActions;
+}
+/**
+ * Props for `<BikEditor />`. All props are optional.
+ */
+export interface BikEditorProps {
+    /**
+     * Opt in to specific editor capabilities. Both default to `false`.
+     *
+     * @example
+     * <BikEditor features={{ richPaste: true, richTypography: true }} />
+     */
+    features?: EditorFeatures;
+    /**
+     * HTML loaded on mount. Ignored after first render.
+     * Use `ref.setContent()` to change content imperatively later.
+     */
+    initialContent?: string;
+    /**
+     * Named sections placed below the main body.
+     * Each section is separated from the previous one by an invisible divider node.
+     * The array order determines the visual order in the document.
+     *
+     * These are only the INITIAL values — use `ref.setSectionContent()` to update
+     * a section after mount without re-mounting the editor.
+     *
+     * @example
+     * sections={[
+     *   { id: 'signature', content: '<p>Best regards, Alice</p>' },
+     *   { id: 'forwarded', content: '<p>--- Forwarded message ---</p>' },
+     * ]}
+     */
+    sections?: EditorSection[];
+    /** Placeholder text shown when the editor is empty. */
+    placeholder?: string;
+    /** Makes the editor read-only. The toolbar still renders but actions are no-ops. */
+    disabled?: boolean;
+    /**
+     * Hard character limit. The editor refuses to accept input beyond this point.
+     * The limit is enforced silently — no UI is rendered. Use
+     * `ref.getCharacterCount()` or `onChange.characterCount` to display it yourself.
+     */
+    maxCharacters?: number;
+    /**
+     * Custom keyboard shortcuts. BikEditor registers no shortcuts of its own —
+     * every shortcut must be explicitly listed here.
+     *
+     * @example
+     * shortcuts={[
+     *   { key: 'Enter', modifiers: ['mod'], handler: handleSend },
+     *   { key: 's', modifiers: ['mod', 'shift'], handler: handleDraft },
+     * ]}
+     */
+    shortcuts?: KeyboardShortcut[];
+    /**
+     * Shortcut key that fires `onSend`. No key is bound to `onSend` unless you
+     * set this explicitly. Requires `onSend` to also be provided.
+     *
+     * `'mod'` maps to Cmd on macOS and Ctrl on Windows/Linux.
+     *
+     * @example
+     * // Cmd+Enter / Ctrl+Enter to send
+     * sendShortcut={{ key: 'Enter', modifiers: ['mod'] }}
+     */
+    sendShortcut?: {
+        key: string;
+        modifiers?: Array<'mod' | 'ctrl' | 'shift' | 'alt'>;
+    };
+    /**
+     * Enables `@` (agent) and `#` (team) mention dropdowns.
+     * Bundle all mention-related config in one object so it's easy to find.
+     *
+     * @example
+     * mentions={{
+     *   agents: myAgents,
+     *   teams:  myTeams,
+     *   onSelect: (item, char) => track(char, item.id),
+     * }}
+     */
+    mentions?: MentionConfig;
+    /**
+     * Enables the `/` slash-command menu.
+     * Bundle all slash-command config in one object.
+     *
+     * @example
+     * slashCommands={{
+     *   items: MY_COMMANDS,
+     *   onSelect: (cmd) => handleCommand(cmd.id),
+     * }}
+     */
+    slashCommands?: SlashCommandConfig;
+    /**
+     * Link-related configuration — currently just the click tooltip.
+     *
+     * @example
+     * link={{ renderTooltip: ({ href, onOpen, onRemove }) => (
+     *   <MyTooltip href={href} onOpen={onOpen} onRemove={onRemove} />
+     * )}}
+     */
+    link?: LinkConfig;
+    /**
+     * Called once, immediately after the editor finishes initializing.
+     * Any imperative ref methods called before this fires are queued internally
+     * and executed automatically once the editor is ready — consumers do not
+     * need timers or readiness guards.
+     *
+     * @example
+     * <BikEditor
+     *   ref={editorRef}
+     *   onReady={() => editorRef.current?.setContent(savedDraft)}
+     * />
+     */
+    onReady?: () => void;
+    /** Called on every document change. */
+    onChange?: (content: EditorSnapshot) => void;
+    /**
+     * Called when the user presses Mod+Enter (Cmd on Mac, Ctrl on Win/Linux).
+     * Only fires when this prop is provided.
+     */
+    onSend?: (content: EditorSnapshot) => void;
+    /** Called when the editor gains focus. */
+    onFocus?: () => void;
+    /** Called when the editor loses focus. */
+    onBlur?: () => void;
+    /**
+     * Called on every paste event. Return `true` to fully suppress BikEditor's
+     * own paste handling (useful when you want to handle images or HTML yourself).
+     *
+     * @example
+     * onPaste={({ images }) => {
+     *   if (images.length) {
+     *     uploadImages(images).then(urls => {
+     *       urls.forEach(url => ref.current?.actions.insertHtml(`<img src="${url}" />`));
+     *     });
+     *     return true; // suppress default — don't embed the raw image data
+     *   }
+     * }}
+     */
+    onPaste?: (data: PasteData) => boolean | void;
+    /**
+     * Called on every cursor move or selection change with a snapshot of all
+     * active marks. Keep in state and pass to your toolbar to sync button states.
+     */
+    onSelectionChange?: (activeFormats: FormatState) => void;
+    /** Extra class name applied to the outer wrapper div. */
+    className?: string;
+    /** Inline styles applied to the outer wrapper div. */
+    style?: React.CSSProperties;
+    /** Extra class name applied to the content-editable area (`.ProseMirror` in TipTap). */
+    editorClassName?: string;
+    /** Inline styles applied to the content-editable area. */
+    editorStyle?: React.CSSProperties;
+    /** Minimum height of the editable area. CSS value, e.g. `'80px'`. */
+    minHeight?: string;
+    /** Maximum height. The editor scrolls internally when exceeded. CSS value, e.g. `'400px'`. */
+    maxHeight?: string;
+}