@pubwave/editor 0.1.1-alpha.0

package/dist/index.d.ts

@@ -0,0 +1,1339 @@
+import { default as default_2 } from 'react';
+import { Editor } from '@tiptap/react';
+import { Editor as Editor_2 } from '@tiptap/core';
+import { Extension } from '@tiptap/core';
+import { ForwardRefExoticComponent } from 'react';
+import { JSONContent } from '@tiptap/core';
+import { Node as Node_2 } from '@tiptap/pm/model';
+import { Plugin as Plugin_2 } from '@tiptap/pm/state';
+import { PluginKey } from '@tiptap/pm/state';
+import { RefAttributes } from 'react';
+import { SuggestionKeyDownProps } from '@tiptap/suggestion';
+
+/**
+ * Action result for feedback
+ */
+export declare interface ActionResult {
+    success: boolean;
+    message?: string;
+}
+
+declare interface BlockExtensionsConfig {
+    /**
+     * Heading levels to support
+     * @default [1, 2, 3]
+     */
+    headingLevels?: (1 | 2 | 3 | 4 | 5 | 6)[];
+    /**
+     * Image upload configuration
+     */
+    imageUpload?: ImageUploadConfig;
+}
+
+/**
+ * BlockHandle Component - Notion-style block controls
+ */
+export declare function BlockHandle({ editor }: BlockHandleProps): default_2.ReactElement | null;
+
+export declare interface BlockHandleProps {
+    /** The Tiptap editor instance */
+    editor: Editor_2;
+}
+
+/**
+ * Supported block types in the editor
+ */
+export declare type BlockType = 'paragraph' | 'heading' | 'bulletList' | 'orderedList' | 'taskList' | 'blockquote' | 'codeBlock' | 'horizontalRule' | 'image';
+
+/**
+ * BubbleToolbar - Selection-driven floating toolbar
+ */
+export declare function BubbleToolbar({ editor, className, children, onVisibilityChange, }: BubbleToolbarProps): default_2.ReactElement | null;
+
+export declare interface BubbleToolbarProps {
+    /** The Tiptap editor instance */
+    editor: Editor_2;
+    /** Additional CSS class names */
+    className?: string;
+    /** Custom toolbar content (renders default if not provided) */
+    children?: default_2.ReactNode;
+    /** Callback when toolbar visibility changes */
+    onVisibilityChange?: (visible: boolean) => void;
+}
+
+/**
+ * Cancel a drag operation
+ */
+export declare function cancelDrag(editor: Editor_2): void;
+
+/**
+ * Check if DOM APIs are available
+ * Use this before accessing window, document, or other browser APIs
+ */
+export declare const canUseDOM: boolean;
+
+/**
+ * Clear all formatting from the selection
+ */
+export declare function clearFormatting(editor: Editor_2): boolean;
+
+/**
+ * Utility function to combine class names
+ * Filters out falsy values and joins with space
+ */
+export declare function cn(...classes: (string | boolean | undefined | null)[]): string;
+
+/**
+ * Action factory for creating toolbar action handlers
+ * Returns a function that can be used as onClick handler
+ */
+export declare function createActionHandler(editor: Editor_2, action: (editor: Editor_2) => ActionResult, onResult?: (result: ActionResult) => void): () => void;
+
+/**
+ * Auto-scroll Utility
+ *
+ * Enables automatic scrolling when dragging near viewport edges.
+ * Essential for long documents where blocks need to be moved across visible area.
+ *
+ * Key behaviors:
+ * - Smooth scrolling that accelerates near edges
+ * - Works with both window and container scrolling
+ * - Cleans up properly when drag ends
+ */
+/**
+ * Create an auto-scroll controller for drag operations
+ */
+export declare function createAutoScroller(scrollContainer?: HTMLElement | null): {
+    start: () => void;
+    update: (clientY: number) => void;
+    stop: () => void;
+};
+
+/**
+ * Create the DnD ProseMirror plugin
+ */
+export declare function createDndPlugin(editor?: Editor_2): Plugin_2<DndState>;
+
+/**
+ * Create a new editor instance
+ *
+ * This factory function creates a configured Tiptap editor with all necessary
+ * extensions and settings based on the provided configuration.
+ *
+ * @param config - Editor configuration options
+ * @returns A configured Tiptap Editor instance
+ * @throws Error if called in a non-browser environment without proper guards
+ */
+export declare function createEditor(config?: EditorConfig): Editor_2;
+
+/**
+ * Create the core extension set for the editor
+ *
+ * This composes all block, mark, and feature extensions into a single array.
+ */
+export declare function createExtensions(config?: ExtensionConfig): Extension[];
+
+/**
+ * Create a focus trap within the editor UI
+ *
+ * Useful for modals/dialogs that should trap focus
+ */
+export declare function createFocusTrap(container: HTMLElement): {
+    activate: () => void;
+    deactivate: () => void;
+};
+
+/**
+ * Create the Slash Commands Extension
+ */
+export declare function createSlashCommandsExtension(commands?: SlashCommand[], imageUploadConfig?: ImageUploadConfig, locale?: EditorLocale_2): Extension<any, any>;
+
+/**
+ * Create a toast ID
+ */
+export declare function createToastId(): string;
+
+/**
+ * Default slash commands (without image upload config, uses base64)
+ * Note: This is deprecated, use createDefaultSlashCommands with locale instead
+ */
+export declare const defaultSlashCommands: SlashCommand[];
+
+export declare const defaultTokens = "\n:root {\n  /* Colors - Light theme */\n  --pubwave-color-background: #ffffff;\n  --pubwave-color-surface: #ffffff;\n  --pubwave-color-text: #1a1a1a;\n  --pubwave-color-text-muted: #6b7280;\n  --pubwave-color-border: #e5e7eb;\n  --pubwave-color-border-light: #f3f4f6;\n  --pubwave-color-hover: rgba(0, 0, 0, 0.03);\n  --pubwave-color-focus: rgba(0, 0, 0, 0.05);\n  --pubwave-color-selection: #3b82f6;\n  --pubwave-color-selection-bg: rgba(59, 130, 246, 0.1);\n  --pubwave-color-primary: #3b82f6;\n  --pubwave-color-primary-faded: rgba(59, 130, 246, 0.1);\n  --pubwave-color-drop-indicator: #3b82f6;\n  --pubwave-color-drop-target: rgba(59, 130, 246, 0.05);\n  --pubwave-color-error: #ef4444;\n\n  /* Spacing */\n  --pubwave-spacing-xs: 0.25rem;\n  --pubwave-spacing-sm: 0.5rem;\n  --pubwave-spacing-md: 1rem;\n  --pubwave-spacing-lg: 1.5rem;\n  --pubwave-spacing-xl: 2rem;\n  --pubwave-block-padding-x: 0;\n  --pubwave-block-padding-y: 0.25rem;\n  --pubwave-block-margin-y: 0.25rem;\n  --pubwave-toolbar-gap: 0.25rem;\n\n  /* Typography */\n  --pubwave-font-family: inherit;\n  --pubwave-font-size-base: 1rem;\n  --pubwave-font-size-small: 0.875rem;\n  --pubwave-line-height-base: 1.625;\n  --pubwave-line-height-heading: 1.25;\n  --pubwave-font-weight-normal: 400;\n  --pubwave-font-weight-medium: 500;\n  --pubwave-font-weight-bold: 700;\n  --pubwave-font-weight-heading: 600;\n\n  /* Borders */\n  --pubwave-border-radius-sm: 0.25rem;\n  --pubwave-border-radius: 0.375rem;\n  --pubwave-border-radius-large: 0.5rem;\n\n  /* Shadows */\n  --pubwave-shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.05);\n  --pubwave-shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06);\n  --pubwave-shadow-toolbar: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06);\n  --pubwave-shadow-popup: 0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -2px rgba(0, 0, 0, 0.05);\n\n  /* Transitions */\n  --pubwave-transition-fast: 0.1s ease;\n  --pubwave-transition-normal: 0.15s ease;\n\n  /* Z-index layers */\n  --pubwave-z-drag-preview: 100;\n  --pubwave-z-toolbar: 50;\n  --pubwave-z-dropdown: 60;\n}\n\n/* Dark theme (if prefers-color-scheme is dark) */\n@media (prefers-color-scheme: dark) {\n  :root {\n    --pubwave-color-background: #1a1a1a;\n    --pubwave-color-surface: #262626;\n    --pubwave-color-text: #e5e7eb;\n    --pubwave-color-text-muted: #9ca3af;\n    --pubwave-color-border: #374151;\n    --pubwave-color-border-light: #4b5563;\n    --pubwave-color-hover: rgba(255, 255, 255, 0.05);\n    --pubwave-color-focus: rgba(255, 255, 255, 0.08);\n    --pubwave-color-selection: #60a5fa;\n    --pubwave-color-selection-bg: rgba(96, 165, 250, 0.15);\n    --pubwave-color-primary: #60a5fa;\n    --pubwave-color-primary-faded: rgba(96, 165, 250, 0.15);\n    --pubwave-color-drop-indicator: #60a5fa;\n    --pubwave-color-drop-target: rgba(96, 165, 250, 0.08);\n    --pubwave-color-error: #f87171;\n  }\n}\n";
+
+/**
+ * Default toolbar actions
+ */
+export declare const defaultToolbarActions: ToolbarActionDescriptor[];
+
+/**
+ * Destroy an editor instance and clean up resources
+ *
+ * @param editor - The editor instance to destroy
+ */
+export declare function destroyEditor(editor: Editor_2 | null): void;
+
+/**
+ * Plugin key for accessing DnD state
+ */
+export declare const dndPluginKey: PluginKey<any>;
+
+/**
+ * DnD state stored in plugin
+ */
+export declare interface DndState {
+    /** Block currently being dragged */
+    draggingBlockId: string | null;
+    /** Position of the block being dragged */
+    draggingBlockPos: number | null;
+    /** Target position for drop (null if no valid target) */
+    dropTargetPos: number | null;
+    /** Whether drop is before or after the target */
+    dropPosition: 'before' | 'after' | null;
+    /** Whether drag was cancelled */
+    cancelled: boolean;
+}
+
+/**
+ * DragHandle - Block drag affordance
+ */
+export declare function DragHandle({ blockId, isHovered, isDragging, onDragStart, onDragEnd, className, }: DragHandleProps): default_2.ReactElement;
+
+export declare interface DragHandleProps {
+    /** Block ID for drag identification */
+    blockId: string;
+    /** Whether the block is currently hovered */
+    isHovered: boolean;
+    /** Whether a drag is currently in progress */
+    isDragging?: boolean;
+    /** Callback when drag starts */
+    onDragStart?: (blockId: string, event: default_2.DragEvent) => void;
+    /** Callback when drag ends */
+    onDragEnd?: (blockId: string, event: default_2.DragEvent) => void;
+    /** Additional CSS class names */
+    className?: string;
+}
+
+/**
+ * DropIndicator - Visual drop target indicator
+ */
+export declare function DropIndicator({ visible, position, className, }: DropIndicatorProps): default_2.ReactElement;
+
+export declare interface DropIndicatorProps {
+    /** Whether the indicator is visible */
+    visible: boolean;
+    /** Position relative to target block */
+    position: 'before' | 'after';
+    /** Additional CSS class names */
+    className?: string;
+}
+
+/**
+ * Public API exposed by the editor
+ */
+export declare interface EditorAPI {
+    /**
+     * Get the current editor state
+     */
+    getState: () => EditorState;
+    /**
+     * Get the content as JSON
+     */
+    getJSON: () => JSONContent;
+    /**
+     * Get the content as HTML
+     */
+    getHTML: () => string;
+    /**
+     * Get the content as plain text
+     */
+    getText: () => string;
+    /**
+     * Set new content
+     */
+    setContent: (content: JSONContent) => void;
+    /**
+     * Clear all content
+     */
+    clearContent: () => void;
+    /**
+     * Set editable state
+     */
+    setEditable: (editable: boolean) => void;
+    /**
+     * Focus the editor
+     */
+    focus: (position?: 'start' | 'end') => void;
+    /**
+     * Blur the editor
+     */
+    blur: () => void;
+    /**
+     * Toggle bold mark
+     */
+    toggleBold: () => void;
+    /**
+     * Toggle italic mark
+     */
+    toggleItalic: () => void;
+    /**
+     * Set or remove a link
+     */
+    setLink: (href: string | null) => void;
+    /**
+     * Destroy the editor instance
+     */
+    destroy: () => void;
+    /**
+     * Access the underlying Tiptap editor instance
+     * Use with caution - this is an escape hatch
+     */
+    readonly tiptapEditor: Editor | null;
+}
+
+/**
+ * Configuration options for creating an editor instance
+ */
+export declare interface EditorConfig {
+    /**
+     * Initial content in Tiptap JSON format
+     */
+    content?: JSONContent;
+    /**
+     * Whether the editor is in read-only mode
+     * When true, all editing affordances are hidden
+     * @default false
+     */
+    editable?: boolean;
+    /**
+     * Placeholder text shown when the editor is empty
+     */
+    placeholder?: string;
+    /**
+     * Theme configuration for styling
+     */
+    theme?: EditorTheme;
+    /**
+     * Enable autofocus on mount
+     * - true: Focus at the end
+     * - 'start': Focus at the beginning
+     * - 'end': Focus at the end
+     * - false: No autofocus
+     * @default false
+     */
+    autofocus?: boolean | 'start' | 'end';
+    /**
+     * Image upload configuration
+     * If not provided, images will be converted to base64 by default
+     */
+    imageUpload?: ImageUploadConfig;
+    /**
+     * Callback fired when the editor content changes
+     */
+    onUpdate?: (props: {
+        editor: Editor;
+    }) => void;
+    /**
+     * Callback fired when the selection changes
+     */
+    onSelectionUpdate?: (props: {
+        editor: Editor;
+    }) => void;
+    /**
+     * Callback fired when the editor gains focus
+     */
+    onFocus?: (props: {
+        editor: Editor;
+    }) => void;
+    /**
+     * Callback fired when the editor loses focus
+     */
+    onBlur?: (props: {
+        editor: Editor;
+    }) => void;
+    /**
+     * Callback fired when the editor is ready
+     */
+    onCreate?: (props: {
+        editor: Editor;
+    }) => void;
+    /**
+     * Callback fired before the editor is destroyed
+     */
+    onDestroy?: () => void;
+}
+
+/**
+ * Theme configuration using CSS custom property tokens
+ * All colors must be CSS custom properties, never hard-coded values
+ */
+/**
+ * Locale for internationalization
+ * @default 'en'
+ */
+export declare type EditorLocale = 'en' | 'zh' | 'zh-CN' | 'ja' | 'ko' | 'fr' | 'de' | 'es' | 'pt';
+
+declare interface EditorLocale_2 {
+    slashMenu: {
+        groups: {
+            basic: string;
+            list: string;
+            media: string;
+            advanced: string;
+        };
+        commands: {
+            paragraph: {
+                title: string;
+                description: string;
+            };
+            heading1: {
+                title: string;
+                description: string;
+            };
+            heading2: {
+                title: string;
+                description: string;
+            };
+            heading3: {
+                title: string;
+                description: string;
+            };
+            bulletList: {
+                title: string;
+                description: string;
+            };
+            orderedList: {
+                title: string;
+                description: string;
+            };
+            taskList: {
+                title: string;
+                description: string;
+            };
+            image: {
+                title: string;
+                description: string;
+            };
+            blockquote: {
+                title: string;
+                description: string;
+            };
+            codeBlock: {
+                title: string;
+                description: string;
+            };
+            horizontalRule: {
+                title: string;
+                description: string;
+            };
+        };
+    };
+    toolbar: {
+        bold: string;
+        italic: string;
+        underline: string;
+        strike: string;
+        code: string;
+        link: string;
+        turnInto: string;
+        colorPicker: string;
+        textColor: string;
+        backgroundColor: string;
+        recentlyUsed: string;
+        openLink: string;
+        removeLink: string;
+        blockTypes: {
+            text: string;
+            heading1: string;
+            heading2: string;
+            heading3: string;
+            bulletedList: string;
+            numberedList: string;
+        };
+    };
+    aria: {
+        editor: string;
+        editorContent: string;
+        toolbar: string;
+        boldButton: string;
+        italicButton: string;
+        underlineButton: string;
+        strikeButton: string;
+        codeButton: string;
+        linkButton: string;
+        turnIntoButton: string;
+        colorPickerButton: string;
+        headingButton: string;
+        paragraphButton: string;
+        dragHandle: string;
+        dropIndicator: string;
+        blockMenu: string;
+        addBlock: string;
+        deleteBlock: string;
+        linkDialog: string;
+        linkUrlInput: string;
+        linkSaveButton: string;
+        linkRemoveButton: string;
+        linkCancelButton: string;
+        addBlockBelow: string;
+        dragToMove: string;
+        openLinkInNewTab: string;
+    };
+    placeholder: string;
+    linkPlaceholder: string;
+}
+
+/**
+ * Complete editor state exposed to consumers
+ */
+export declare interface EditorState {
+    /**
+     * Current selection state
+     */
+    selection: SelectionState;
+    /**
+     * Current mark state for the selection
+     */
+    marks: MarkState;
+    /**
+     * Whether the editor is currently focused
+     */
+    isFocused: boolean;
+    /**
+     * Whether the editor is in read-only mode
+     */
+    isEditable: boolean;
+    /**
+     * Whether the editor content is empty
+     */
+    isEmpty: boolean;
+    /**
+     * Current character count
+     */
+    characterCount: number;
+}
+
+export declare interface EditorTheme {
+    /**
+     * CSS class name prefix for styling hooks
+     * @default 'pubwave-editor'
+     */
+    classNamePrefix?: string;
+    /**
+     * Locale for internationalization
+     * @default 'en'
+     */
+    locale?: EditorLocale;
+    /**
+     * Additional CSS classes to apply to the editor container
+     */
+    containerClassName?: string;
+    /**
+     * Additional CSS classes to apply to the content area
+     */
+    contentClassName?: string;
+    /**
+     * Color theme configuration
+     * Colors will be applied as CSS custom properties to the editor container
+     * If not provided, default theme colors will be used
+     */
+    colors?: {
+        /**
+         * Editor background color
+         */
+        background?: string;
+        /**
+         * Primary text color
+         */
+        text?: string;
+        /**
+         * Muted/secondary text color (e.g., for placeholders)
+         */
+        textMuted?: string;
+        /**
+         * Border color
+         */
+        border?: string;
+        /**
+         * Primary color (for links, buttons, etc.)
+         */
+        primary?: string;
+        /**
+         * Link color (if not provided, will use primary color)
+         * Useful for dark themes where a brighter link color is needed for visibility
+         */
+        linkColor?: string;
+    };
+    /**
+     * Background image configuration
+     * Can be a URL string or CSS background-image value
+     * If provided, will be applied as the editor container background image
+     * Background image will be layered on top of background color
+     */
+    backgroundImage?: string;
+    /**
+     * Background image options
+     * Controls how the background image is displayed
+     */
+    backgroundImageOptions?: {
+        /**
+         * Background image repeat behavior
+         * @default 'no-repeat'
+         */
+        repeat?: 'repeat' | 'repeat-x' | 'repeat-y' | 'no-repeat';
+        /**
+         * Background image position
+         * @default 'center'
+         */
+        position?: string;
+        /**
+         * Background image size
+         * @default 'cover'
+         */
+        size?: 'cover' | 'contain' | string;
+        /**
+         * Background image attachment
+         * @default 'scroll'
+         */
+        attachment?: 'scroll' | 'fixed' | 'local';
+    };
+}
+
+/**
+ * Configuration for creating the extension set
+ */
+declare interface ExtensionConfig extends BlockExtensionsConfig, MarkExtensionsConfig {
+    /**
+     * Placeholder text for empty editor
+     */
+    placeholder?: string;
+    /**
+     * Undo/redo history depth
+     * @default 100
+     */
+    historyDepth?: number;
+    /**
+     * Enable slash commands menu
+     * @default true
+     */
+    enableSlashCommands?: boolean;
+    /**
+     * Custom slash commands (merged with defaults)
+     */
+    slashCommands?: SlashCommand[];
+    /**
+     * Image upload configuration
+     */
+    imageUpload?: ImageUploadConfig;
+    /**
+     * Locale for internationalization
+     */
+    locale?: EditorLocale;
+}
+
+/**
+ * Find top-level block node at a given document position
+ * Returns the direct child of doc that contains the position
+ */
+export declare function findBlockAtPos(doc: Node_2, pos: number): {
+    node: Node_2;
+    pos: number;
+} | null;
+
+/**
+ * Focus the editor after a click event
+ *
+ * Handles edge cases where clicking on toolbar/UI elements
+ * should restore focus to the editor
+ */
+export declare function focusAfterClick(editor: Editor_2, event: React.MouseEvent): void;
+
+/**
+ * Focus the editor at a specific position
+ */
+export declare function focusAt(editor: Editor_2, position: FocusPosition): void;
+
+/**
+ * Focus the editor
+ */
+export declare function focusEditor(editor: Editor_2, position?: 'start' | 'end' | 'all' | number): boolean;
+
+/**
+ * Focus position options
+ */
+export declare type FocusPosition = 'start' | 'end' | 'preserve' | number;
+
+/**
+ * Get the current link href if selection is inside a link
+ */
+export declare function getActiveLinkHref(editor: Editor_2): string | null;
+
+/**
+ * Get current marks at the selection
+ */
+export declare function getActiveMarks(editor: Editor_2): string[];
+
+/**
+ * Get the current DnD state from an editor
+ */
+export declare function getDndState(editor: Editor_2): DndState;
+
+/**
+ * Get selection coordinates for positioning UI elements (like toolbar)
+ * Returns the bounding box of the current selection
+ */
+export declare function getSelectionBounds(editor: Editor_2): {
+    top: number;
+    left: number;
+    right: number;
+    bottom: number;
+    width: number;
+    height: number;
+} | null;
+
+/**
+ * Get the current selection state from the editor
+ *
+ * This is the primary function for determining toolbar visibility.
+ * Per constitution: toolbar MUST NOT be visible when selection is empty.
+ */
+export declare function getSelectionState(editor: Editor_2): SelectionState_2;
+
+/**
+ * Handle focus for selection clear
+ *
+ * When selection is cleared (e.g., clicking in empty space),
+ * ensure cursor is placed at a sensible position
+ */
+export declare function handleSelectionClear(editor: Editor_2): void;
+
+/**
+ * Image upload configuration
+ */
+declare interface ImageUploadConfig {
+    /**
+     * Custom image upload handler
+     * If provided, images will be uploaded using this function
+     * If not provided, images will be converted to base64 (default)
+     */
+    handler?: ImageUploadHandler;
+    /**
+     * Maximum file size in bytes
+     * @default 10MB (10 * 1024 * 1024)
+     */
+    maxSize?: number;
+    /**
+     * Accepted file types
+     * @default ['image/*']
+     */
+    accept?: string[];
+}
+
+/**
+ * Image upload handler function
+ * Should return a Promise that resolves to the image URL
+ * If the function throws or rejects, the editor will fall back to base64
+ */
+declare type ImageUploadHandler = (file: File) => Promise<string>;
+
+/**
+ * Check if the editor is editable (inverse of read-only)
+ */
+export declare function isEditable(editor: Editor_2 | null): boolean;
+
+/**
+ * Check if an editor instance is in a valid state
+ *
+ * @param editor - The editor instance to check
+ * @returns true if the editor exists and is not destroyed
+ */
+export declare function isEditorValid(editor: Editor_2 | null): editor is Editor_2;
+
+/**
+ * Check if a mark is currently active
+ */
+export declare function isMarkActive(editor: Editor_2, markType: string): boolean;
+
+/**
+ * Check if a node type is currently active
+ */
+export declare function isNodeActive(editor: Editor_2, nodeType: string, attrs?: Record<string, unknown>): boolean;
+
+/**
+ * Check if the editor is in read-only mode
+ */
+export declare function isReadOnly(editor: Editor_2 | null): boolean;
+
+/**
+ * Check if the selection is empty (cursor only)
+ *
+ * This is the key check for toolbar visibility.
+ * Returns true when toolbar should be HIDDEN.
+ */
+export declare function isSelectionEmpty(editor: Editor_2): boolean;
+
+/**
+ * Check if code is running in a server-side environment
+ */
+export declare const isSSR: boolean;
+
+/**
+ * Keep focus within the editor
+ *
+ * Prevents focus from escaping during common operations
+ */
+export declare function maintainFocus(editor: Editor_2): () => void;
+
+declare interface MarkExtensionsConfig {
+    /**
+     * Whether links should open in a new tab
+     * @default true
+     */
+    linkOpenInNewTab?: boolean;
+    /**
+     * Whether to open links on click (within editor)
+     * @default true - links open on click
+     */
+    linkOpenOnClick?: boolean;
+}
+
+/**
+ * Mark state for the current selection
+ */
+export declare interface MarkState {
+    /**
+     * Whether bold is active at the current selection
+     */
+    isBold: boolean;
+    /**
+     * Whether italic is active at the current selection
+     */
+    isItalic: boolean;
+    /**
+     * Whether a link is active at the current selection
+     */
+    isLink: boolean;
+    /**
+     * The href of the active link, if any
+     */
+    linkHref?: string;
+}
+
+/**
+ * Supported mark types for inline formatting
+ */
+export declare type MarkType = 'bold' | 'italic' | 'underline' | 'strike' | 'code' | 'link';
+
+/**
+ * Move a block from one position to another
+ */
+export declare function moveBlock(editor: Editor_2, fromPos: number, toPos: number, position: 'before' | 'after'): boolean;
+
+/**
+ * PubwaveEditor Component
+ *
+ * A Notion-level block editor with:
+ * - Premium writing experience
+ * - Selection-only formatting toolbar
+ * - Block drag & drop
+ * - Full theme customization via CSS tokens
+ */
+export declare const PubwaveEditor: ForwardRefExoticComponent<PubwaveEditorProps & RefAttributes<EditorAPI | null>>;
+
+/**
+ * Props for the PubwaveEditor component
+ */
+declare interface PubwaveEditorProps {
+    /**
+     * Initial content in Tiptap JSON format
+     */
+    content?: JSONContent;
+    /**
+     * Whether the editor is in read-only mode
+     * @default false
+     */
+    editable?: boolean;
+    /**
+     * Placeholder text shown when the editor is empty
+     */
+    placeholder?: string;
+    /**
+     * Theme configuration
+     */
+    theme?: EditorTheme;
+    /**
+     * Enable autofocus on mount
+     * @default false
+     */
+    autofocus?: boolean | 'start' | 'end';
+    /**
+     * Callback when content changes
+     */
+    onChange?: (content: JSONContent) => void;
+    /**
+     * Callback when selection changes
+     */
+    onSelectionChange?: () => void;
+    /**
+     * Callback when editor gains focus
+     */
+    onFocus?: () => void;
+    /**
+     * Callback when editor loses focus
+     */
+    onBlur?: () => void;
+    /**
+     * Callback when editor is ready
+     */
+    onReady?: (api: EditorAPI) => void;
+    /**
+     * Image upload configuration
+     * If not provided, images will be converted to base64 by default
+     */
+    imageUpload?: ImageUploadConfig;
+    /**
+     * Additional CSS class for the container
+     */
+    className?: string;
+    /**
+     * Editor container width
+     * Can be a CSS value like '100%', '1200px', '90vw', etc.
+     * @default '100%'
+     */
+    width?: string;
+    /**
+     * Test ID for testing
+     */
+    'data-testid'?: string;
+}
+
+/**
+ * Redo the last undone action
+ */
+export declare function redo(editor: Editor_2): boolean;
+
+/**
+ * Restore focus after a DOM operation
+ *
+ * Use this after operations that might cause focus loss:
+ * - Modal/dialog interactions
+ * - Toolbar button clicks
+ * - Context menu actions
+ */
+export declare function restoreFocus(editor: Editor_2): void;
+
+export declare function restoreSelection(editor: Editor_2, savedSelection: SavedSelection | null): void;
+
+/**
+ * Save and restore selection state
+ *
+ * Useful for operations that need to temporarily change selection
+ * then restore it (e.g., inserting content at cursor)
+ */
+export declare interface SavedSelection {
+    from: number;
+    to: number;
+    empty: boolean;
+}
+
+export declare function saveSelection(editor: Editor_2): SavedSelection | null;
+
+/**
+ * Select all content
+ */
+export declare function selectAll(editor: Editor_2): boolean;
+
+/**
+ * Current selection state derived from the editor
+ */
+export declare interface SelectionState {
+    /**
+     * Whether there is a non-empty text selection
+     */
+    hasSelection: boolean;
+    /**
+     * Whether the selection spans multiple blocks
+     */
+    isMultiBlock: boolean;
+    /**
+     * Start position of the selection
+     */
+    from: number;
+    /**
+     * End position of the selection
+     */
+    to: number;
+    /**
+     * Whether the selection is empty (cursor only)
+     */
+    isEmpty: boolean;
+}
+
+/**
+ * Selection state information
+ */
+declare interface SelectionState_2 {
+    /**
+     * Whether there is any selection at all
+     */
+    hasSelection: boolean;
+    /**
+     * Whether the selection is empty (cursor only, no text selected)
+     */
+    isEmpty: boolean;
+    /**
+     * Whether the selection spans actual text content
+     */
+    hasTextContent: boolean;
+    /**
+     * Whether this is a node selection (e.g., selected image or block)
+     */
+    isNodeSelection: boolean;
+    /**
+     * The selected text, if any
+     */
+    selectedText: string;
+    /**
+     * Start position of the selection
+     */
+    from: number;
+    /**
+     * End position of the selection
+     */
+    to: number;
+    /**
+     * Whether bold mark is active in selection
+     */
+    isBold: boolean;
+    /**
+     * Whether italic mark is active in selection
+     */
+    isItalic: boolean;
+    /**
+     * Whether underline mark is active in selection
+     */
+    isUnderline: boolean;
+    /**
+     * Whether strike mark is active in selection
+     */
+    isStrike: boolean;
+    /**
+     * Whether code mark is active in selection
+     */
+    isCode: boolean;
+    /**
+     * Whether the selection has a link
+     */
+    hasLink: boolean;
+    /**
+     * Active link href if any
+     */
+    linkHref: string | null;
+}
+
+/**
+ * Set the current block to a heading
+ */
+export declare function setHeading(editor: Editor_2, level: 1 | 2 | 3 | 4 | 5 | 6): boolean;
+
+/**
+ * Set a link on the current selection
+ */
+export declare function setLink(editor: Editor_2, href: string): boolean;
+
+/**
+ * Set the current block to a paragraph
+ */
+export declare function setParagraph(editor: Editor_2): boolean;
+
+/**
+ * Guard function for any interactive element
+ * Returns true if interactive elements should be enabled
+ */
+export declare function shouldAllowInteraction(editor: Editor_2 | null): boolean;
+
+/**
+ * Guard function for toolbar visibility
+ * Returns true if toolbar should potentially be visible
+ * (Still depends on selection state)
+ */
+export declare function shouldAllowToolbar(editor: Editor_2 | null): boolean;
+
+/**
+ * Guard function for UI components
+ * Returns true if the component should be rendered (editable mode)
+ */
+export declare function shouldRenderEditUI(editor: Editor_2 | null): boolean;
+
+/**
+ * Guard function for drag handles
+ * Returns true if drag handles should be visible
+ */
+export declare function shouldShowDragHandle(editor: Editor_2 | null): boolean;
+
+/**
+ * Check if selection should trigger toolbar visibility
+ *
+ * Per constitution: toolbar appears ONLY on non-empty text selection.
+ * - Cursor only: NO toolbar
+ * - Text selected: YES toolbar
+ * - Node selected (image, etc.): Context-dependent
+ */
+export declare function shouldShowToolbar(editor: Editor_2): boolean;
+
+/**
+ * Command item definition
+ */
+export declare interface SlashCommand {
+    id: string;
+    title: string;
+    description: string;
+    icon: default_2.ReactNode;
+    aliases?: string[];
+    group: 'basic' | 'list' | 'media' | 'advanced';
+    action: (editor: Editor_2) => void;
+}
+
+/**
+ * Slash Menu List Component
+ */
+export declare const SlashMenuList: default_2.ForwardRefExoticComponent<SlashMenuListProps & default_2.RefAttributes<{
+    onKeyDown: (props: SuggestionKeyDownProps) => boolean;
+}>>;
+
+/**
+ * Slash Menu Component Props
+ */
+declare interface SlashMenuListProps {
+    items: SlashCommand[];
+    command: (item: SlashCommand) => void;
+    editor: Editor_2;
+    query?: string;
+    groupLabels?: Record<string, string>;
+}
+
+/**
+ * Start a drag operation
+ */
+export declare function startDrag(editor: Editor_2, blockId: string, pos: number): void;
+
+/**
+ * Supported block types
+ */
+export declare const SUPPORTED_BLOCKS: readonly BlockType[];
+
+/**
+ * Supported mark types
+ */
+export declare const SUPPORTED_MARKS: readonly MarkType[];
+
+/**
+ * Toast - Transient notification component
+ */
+export declare function Toast({ message, type, duration, onDismiss, className, }: ToastProps): default_2.ReactElement;
+
+export declare function ToastContainer({ toasts, onDismiss, }: ToastContainerProps): default_2.ReactElement;
+
+export declare interface ToastContainerProps {
+    toasts: ToastItem[];
+    onDismiss: (id: string) => void;
+}
+
+/**
+ * Toast container for managing multiple toasts
+ */
+export declare interface ToastItem {
+    id: string;
+    message: string;
+    type?: 'info' | 'success' | 'error' | 'warning';
+    duration?: number;
+}
+
+export declare interface ToastProps {
+    /** Toast message content */
+    message: string;
+    /** Toast type for styling */
+    type?: 'info' | 'success' | 'error' | 'warning';
+    /** Auto-dismiss duration in ms (0 = no auto-dismiss) */
+    duration?: number;
+    /** Callback when toast is dismissed */
+    onDismiss?: () => void;
+    /** Additional CSS class names */
+    className?: string;
+}
+
+/**
+ * Toggle bold formatting on the current selection
+ */
+export declare function toggleBold(editor: Editor_2): boolean;
+
+/**
+ * Toggle heading for the current block
+ */
+export declare function toggleHeading(editor: Editor_2, level: 1 | 2 | 3 | 4 | 5 | 6): boolean;
+
+/**
+ * Toggle italic formatting on the current selection
+ */
+export declare function toggleItalic(editor: Editor_2): boolean;
+
+/**
+ * CSS Token definitions
+ * These map to CSS custom properties that host applications can override.
+ */
+export declare const tokens: {
+    readonly colors: {
+        readonly background: "var(--pubwave-color-background)";
+        readonly surface: "var(--pubwave-color-surface)";
+        readonly text: "var(--pubwave-color-text)";
+        readonly textMuted: "var(--pubwave-color-text-muted)";
+        readonly border: "var(--pubwave-color-border)";
+        readonly borderLight: "var(--pubwave-color-border-light)";
+        readonly hover: "var(--pubwave-color-hover)";
+        readonly focus: "var(--pubwave-color-focus)";
+        readonly selection: "var(--pubwave-color-selection)";
+        readonly selectionBg: "var(--pubwave-color-selection-bg)";
+        readonly primary: "var(--pubwave-color-primary)";
+        readonly primaryFaded: "var(--pubwave-color-primary-faded)";
+        readonly dropIndicator: "var(--pubwave-color-drop-indicator)";
+        readonly dropTarget: "var(--pubwave-color-drop-target)";
+        readonly error: "var(--pubwave-color-error)";
+    };
+    readonly spacing: {
+        readonly xs: "var(--pubwave-spacing-xs)";
+        readonly sm: "var(--pubwave-spacing-sm)";
+        readonly md: "var(--pubwave-spacing-md)";
+        readonly lg: "var(--pubwave-spacing-lg)";
+        readonly xl: "var(--pubwave-spacing-xl)";
+        readonly blockPaddingX: "var(--pubwave-block-padding-x)";
+        readonly blockPaddingY: "var(--pubwave-block-padding-y)";
+        readonly blockMarginY: "var(--pubwave-block-margin-y)";
+        readonly toolbarGap: "var(--pubwave-toolbar-gap)";
+    };
+    readonly typography: {
+        readonly fontFamily: "var(--pubwave-font-family)";
+        readonly fontSizeBase: "var(--pubwave-font-size-base)";
+        readonly fontSizeSmall: "var(--pubwave-font-size-small)";
+        readonly lineHeightBase: "var(--pubwave-line-height-base)";
+        readonly lineHeightHeading: "var(--pubwave-line-height-heading)";
+        readonly fontWeightNormal: "var(--pubwave-font-weight-normal)";
+        readonly fontWeightMedium: "var(--pubwave-font-weight-medium)";
+        readonly fontWeightBold: "var(--pubwave-font-weight-bold)";
+        readonly fontWeightHeading: "var(--pubwave-font-weight-heading)";
+    };
+    readonly borderRadius: {
+        readonly sm: "var(--pubwave-border-radius-sm)";
+        readonly md: "var(--pubwave-border-radius)";
+        readonly lg: "var(--pubwave-border-radius-large)";
+    };
+    readonly shadow: {
+        readonly sm: "var(--pubwave-shadow-sm)";
+        readonly md: "var(--pubwave-shadow-md)";
+        readonly toolbar: "var(--pubwave-shadow-toolbar)";
+        readonly popup: "var(--pubwave-shadow-popup)";
+    };
+    readonly transition: {
+        readonly fast: "var(--pubwave-transition-fast)";
+        readonly normal: "var(--pubwave-transition-normal)";
+    };
+    readonly zIndex: {
+        readonly dragPreview: 100;
+        readonly dragHandle: 40;
+        readonly toolbar: 50;
+        readonly dropdown: 60;
+    };
+};
+
+/**
+ * Toolbar action descriptors for dynamic toolbar generation
+ */
+export declare interface ToolbarActionDescriptor {
+    id: string;
+    label: string;
+    shortcut?: string;
+    icon: string;
+    action: (editor: Editor_2) => ActionResult;
+    isActive: (editor: Editor_2) => boolean;
+    isDisabled?: (editor: Editor_2) => boolean;
+}
+
+/**
+ * Toolbar position calculated relative to viewport
+ */
+export declare interface ToolbarPosition {
+    top: number;
+    left: number;
+    visible: boolean;
+}
+
+/**
+ * Remove link from selection
+ */
+export declare function toolbarRemoveLink(editor: Editor_2): ActionResult;
+
+/**
+ * Set heading level
+ */
+export declare function toolbarSetHeading(editor: Editor_2, level: 1 | 2 | 3): ActionResult;
+
+/**
+ * Set a link on the selection
+ */
+export declare function toolbarSetLink(editor: Editor_2, href: string): ActionResult;
+
+/**
+ * Set paragraph (remove heading)
+ */
+export declare function toolbarSetParagraph(editor: Editor_2): ActionResult;
+
+/**
+ * Toggle bold mark on selection
+ */
+export declare function toolbarToggleBold(editor: Editor_2): ActionResult;
+
+/**
+ * Toggle italic mark on selection
+ */
+export declare function toolbarToggleItalic(editor: Editor_2): ActionResult;
+
+/**
+ * Toggle link - prompts for URL if adding, removes if already linked
+ */
+export declare function toolbarToggleLink(editor: Editor_2, promptFn?: (message: string) => string | null): ActionResult;
+
+/**
+ * Undo the last action
+ */
+export declare function undo(editor: Editor_2): boolean;
+
+/**
+ * Remove link from the current selection
+ */
+export declare function unsetLink(editor: Editor_2): boolean;
+
+/**
+ * React hook for auto-scroll during drag operations
+ */
+export declare function useAutoScroll(scrollContainer?: HTMLElement | null): {
+    startAutoScroll: () => void;
+    updateAutoScroll: (event: {
+        clientY: number;
+    }) => void;
+    stopAutoScroll: () => void;
+};
+
+export { }
+
+
+declare module '@tiptap/core' {
+    interface Commands<ReturnType> {
+        textColor: {
+            setColor: (color: string) => ReturnType;
+            unsetColor: () => ReturnType;
+        };
+        backgroundColor: {
+            setBackgroundColor: (backgroundColor: string) => ReturnType;
+            unsetBackgroundColor: () => ReturnType;
+        };
+    }
+}