@matops/editor 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1140 @@
+import { ClassValue } from 'clsx';
+import { DecorationSet } from '@tiptap/pm/view';
+import { default as default_2 } from 'react';
+import { Dispatch } from 'react';
+import { Doc } from 'yjs';
+import { Editor as Editor_2 } from '@tiptap/core';
+import { Extension } from '@tiptap/core';
+import { Extensions } from '@tiptap/core';
+import { JSONContent } from '@tiptap/core';
+import { JSX as JSX_2 } from 'react/jsx-runtime';
+import { Node as Node_2 } from '@tiptap/core';
+import { PluginKey } from '@tiptap/pm/state';
+import { ReactNode } from 'react';
+import { RefObject } from 'react';
+import { SetStateAction } from 'react';
+
+export declare interface AttachmentItem {
+    id: string;
+    name: string;
+    size: number;
+    mimeType: string;
+    url: string;
+}
+
+export declare interface AttachmentsAttrs {
+    items: string;
+}
+
+export declare interface AttachmentsDocAttr {
+    items: string;
+}
+
+/**
+ * AttachmentsGuard — stub extension for the `"attachments"` feature.
+ * Previously guarded the attachments content node; now a no-op since
+ * attachments data lives in doc.attrs and is rendered as a React panel.
+ */
+export declare const AttachmentsGuard: Extension<any, any>;
+
+export declare const AttachmentsNode: Node_2<any, any>;
+
+/**
+ * AttachmentsPanel — React panel (Panel 3) for document attachments.
+ *
+ * Reads from `editor.state.doc.attrs.attachments` (an AttachmentsDocAttr or null).
+ * Writes via `editor.commands.setAttachmentsAttr(items)`.
+ *
+ * Structure (mirrors the old AttachmentsSectionView layout exactly):
+ *   ────── [separator-icon mirror] ──────   ← static, reads from doc.attrs.separatorIcon
+ *   📎 Attachments  [+ Add attachment]
+ *   [ file list ]
+ *
+ * No ProseMirror NodeView — this is pure React rendered below <EditorContent>.
+ *
+ * All drag events call e.stopPropagation() so files dropped here don't also
+ * get picked up by the editor's useImageUpload handler.
+ */
+export declare function AttachmentsPanel(): JSX_2.Element | null;
+
+/**
+ * BlockFloatingMenu
+ *
+ * A compact "+" trigger button on empty lines.
+ * Click to expand into an icon-only pill of available commands.
+ * Hover each icon to see the label as a tooltip.
+ */
+export declare function BlockFloatingMenu(): JSX_2.Element | null;
+
+/**
+ * CharacterCountBar
+ *
+ * A slim footer bar rendered below the editor content area.
+ * Shows: words, characters, paragraphs, and estimated reading time.
+ *
+ * IMPORTANT: useEditorUpdate() is called so this component re-renders on
+ * every editor transaction — without it, stats would only refresh on
+ * React prop changes (i.e. never, since the editor ref is stable).
+ */
+export declare function CharacterCountBar({ wordLimit, charLimit, }: CharacterCountBarProps): JSX_2.Element | null;
+
+declare interface CharacterCountBarProps {
+    /** Optional word limit — shows a progress indicator when set */
+    wordLimit?: number;
+    /** Optional character limit */
+    charLimit?: number;
+}
+
+/**
+ * Merge Tailwind CSS classes safely.
+ * Combines clsx (conditional classes) with tailwind-merge (deduplication).
+ *
+ * @example
+ * cn("p-4", isActive && "bg-blue-500", "p-2")
+ * // → "bg-blue-500 p-2"  (p-4 deduplicated by tailwind-merge)
+ */
+export declare function cn(...inputs: ClassValue[]): string;
+
+export declare interface CollaborationProvider {
+    document: Doc;
+    user?: CollaborationUser;
+}
+
+export declare interface CollaborationUser {
+    name: string;
+    color: string;
+    avatar?: string;
+}
+
+export declare function computeCropStyle(crop: CropRect, objectPosition?: string): React.CSSProperties;
+
+export declare function computeCropStyleStr(crop: CropRect, objectPosition?: string): string;
+
+/**
+ * Registers (or re-registers) the "tables" feature with the given options.
+ *
+ * Calling this function multiple times is intentional when you need custom
+ * configuration — the registry warns on overwrite, which is expected.
+ *
+ * @param options - Partial options to override TABLE_DEFAULTS.
+ */
+export declare function configureTablesFeature(options?: TableFeatureOptions): void;
+
+export declare type ContentWidth = (typeof ContentWidths)[keyof typeof ContentWidths];
+
+export declare const ContentWidths: {
+    readonly full: "full";
+    readonly normal: "normal";
+    readonly compact: "compact";
+};
+
+export declare interface CoverImageAttrs {
+    src: string | null;
+    alt: string;
+    objectPosition: string;
+    cropX: number;
+    cropY: number;
+    cropWidth: number;
+    cropHeight: number;
+}
+
+export declare interface CoverImageDocAttr {
+    src: string | null;
+    alt: string;
+    objectPosition: string;
+    cropX: number;
+    cropY: number;
+    cropWidth: number;
+    cropHeight: number;
+}
+
+/**
+ * CoverImageGuard — stub extension for the `"cover-image"` feature.
+ * Previously guarded the cover-image content node; now a no-op since
+ * cover-image data lives in doc.attrs.
+ */
+export declare const CoverImageGuard: Extension<any, any>;
+
+export declare const CoverImageNode: Node_2<any, any>;
+
+/**
+ * CoverImagePanel — React panel (Panel 1) for the cover/banner image.
+ *
+ * Reads from `editor.state.doc.attrs.coverImage` (a CoverImageDocAttr or null).
+ * Writes via `editor.commands.setCoverImageAttr(...)`.
+ *
+ * No ProseMirror NodeView — this is pure React rendered above <EditorContent>.
+ *
+ * Crop coordinates are percentages (0–100) stored in doc.attrs.coverImage.
+ */
+export declare function CoverImagePanel(): JSX_2.Element | null;
+
+/** @deprecated Use `createDocContent()` instead. */
+export declare function createAttachmentsNode(items?: AttachmentItem[]): JSONContent;
+
+/**
+ * @deprecated Use `createDocContent()` instead.
+ * Returns a `cover-image` content node for internal Tiptap use.
+ */
+export declare function createCoverImageNode(src: string, options?: Partial<Omit<CoverImageAttrs, "src">>): JSONContent;
+
+/**
+ * Build a complete Tiptap document JSONContent in **external format**.
+ *
+ * Structural metadata (cover image, title, separator icon, attachments) is
+ * stored in `doc.attrs`.  Only body content goes in `content[]`.
+ *
+ * Pass the result as `initialContent` to `<Editor>` — it reads doc.attrs and
+ * injects the appropriate content nodes internally.
+ *
+ * @example
+ * createDocContent({
+ *   coverSrc: "https://cdn.example.com/cover.jpg",
+ *   title: "Getting Started",
+ *   body: [{ type: "paragraph", content: [{ type: "text", text: "Hello!" }] }],
+ * })
+ */
+export declare function createDocContent(options?: DocContentOptions): JSONContent;
+
+/** @deprecated Use `createDocContent()` instead. */
+export declare function createEmptyCoverImageNode(): JSONContent;
+
+/** @deprecated Use `createDocContent()` instead. */
+export declare function createEmptySeparatorIconNode(): JSONContent;
+
+/** @deprecated Use `createDocContent()` instead. */
+export declare function createSeparatorIconNode(src: string, options?: Partial<Omit<SeparatorIconAttrs, "src">>): JSONContent;
+
+/** @deprecated Use `createDocContent()` instead. */
+export declare function createTitleNode(text?: string, options?: Partial<TitleAttrs>): JSONContent;
+
+export declare function CropModal({ src, initialCrop, aspectRatio, onConfirm, onCancel, }: CropModalProps): default_2.ReactPortal;
+
+declare interface CropModalProps {
+    src: string;
+    initialCrop?: CropRect;
+    aspectRatio?: number;
+    onConfirm: (crop: CropRect) => void;
+    onCancel: () => void;
+}
+
+export declare interface CropRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+
+export declare function cropToAttrs(crop: CropRect): {
+    cropX: number;
+    cropY: number;
+    cropWidth: number;
+    cropHeight: number;
+};
+
+export declare const DEFAULT_CONTENT_WIDTH: ContentWidth;
+
+export declare const DEFAULT_CROP: CropRect;
+
+/**
+ * DefaultSeparatorIcon — the quill SVG used as the fallback badge icon
+ * in TitleSeparator, SeparatorIconView, and EditorViewer.
+ * Single source of truth — no more duplication across three files.
+ */
+export declare const DefaultSeparatorIcon: ({ size }: IconProps) => JSX_2.Element;
+
+export declare interface DocAttrs {
+    contentWidth?: ContentWidth;
+    coverImage?: CoverImageDocAttr | null;
+    title?: TitleDocAttr | null;
+    separatorIcon?: SeparatorIconDocAttr | null;
+    attachments?: AttachmentsDocAttr | null;
+}
+
+export declare interface DocContentOptions {
+    /** Cover image URL. Omit to skip the `coverImage` attr entirely. */
+    coverSrc?: string;
+    coverOptions?: Partial<Omit<CoverImageDocAttr, "src">>;
+    /**
+     * Document title text. Pass `""` to include the title with no text
+     * (shows placeholder in the editor). Omit to skip entirely.
+     */
+    title?: string;
+    titleOptions?: Partial<TitleDocAttr>;
+    /**
+     * Separator icon URL. Only applied when `title` is also present.
+     */
+    separatorIconSrc?: string;
+    /** Body content nodes. Defaults to a single empty paragraph. */
+    body?: JSONContent[];
+    /**
+     * Attachments section.
+     * - `true` → empty section
+     * - `AttachmentItem[]` → pre-populated
+     * - omit / `false` → disabled
+     */
+    attachments?: boolean | AttachmentItem[];
+    layout?: DocLayout;
+}
+
+export declare interface DocLayout {
+    contentWidth?: ContentWidth;
+}
+
+export declare interface DropdownPosition {
+    top: number;
+    left: number;
+}
+
+declare interface EditorContextValue {
+    editor: Editor_2 | null;
+    features: EditorFeature[];
+    featureSet: Set<EditorFeature>;
+    theme: EditorTheme;
+    editable: boolean;
+    onFileUploaded?: (file: File) => Promise<string>;
+    separatorIcon?: ReactNode;
+}
+
+export declare type EditorFeature = (typeof EditorFeatures)[keyof typeof EditorFeatures];
+
+export declare const EditorFeatures: {
+    readonly formatting: "formatting";
+    readonly code: "code";
+    readonly media: "media";
+    readonly tables: "tables";
+    readonly taskList: "task-list";
+    readonly layout: "layout";
+    readonly collaboration: "collaboration";
+    readonly history: "history";
+    readonly slashCommand: "slash-command";
+    readonly placeholder: "placeholder";
+    readonly characterCount: "character-count";
+    readonly findReplace: "find-replace";
+    readonly coverImage: "cover-image";
+    readonly pageHeader: "page-header";
+    readonly attachments: "attachments";
+};
+
+export declare interface EditorProps {
+    features?: EditorFeature[];
+    initialContent?: JSONContent;
+    theme?: EditorTheme;
+    editable?: boolean;
+    placeholder?: string;
+    collaborationProvider?: CollaborationProvider;
+    className?: string;
+    onChange?: (json: JSONContent) => void;
+    onContentChange?: (html: string, json: JSONContent) => void;
+    onPublish?: (content: JSONContent) => void;
+    onFileUploaded?: (file: File) => Promise<string>;
+    onEditorReady?: (editor: Editor_2) => void;
+    separatorIcon?: ReactNode;
+}
+
+export declare function EditorProvider({ children, editor, features, theme, editable, onFileUploaded, separatorIcon, }: EditorProviderProps): JSX_2.Element;
+
+declare interface EditorProviderProps {
+    children: ReactNode;
+    editor: Editor_2 | null;
+    features: EditorFeature[];
+    theme: EditorTheme;
+    editable: boolean;
+    onFileUploaded?: (file: File) => Promise<string>;
+    separatorIcon?: ReactNode;
+}
+
+export declare type EditorTheme = (typeof EditorThemes)[keyof typeof EditorThemes];
+
+export declare const EditorThemes: {
+    readonly light: "light";
+    readonly dark: "dark";
+};
+
+export declare function EditorToolbar(): JSX_2.Element | null;
+
+export declare function EditorToolbarWithActions({ onOpenFind, onOpenExport, onOpenShortcuts, previewMode, onTogglePreview, }?: EditorToolbarWithActionsProps): JSX_2.Element | null;
+
+declare interface EditorToolbarWithActionsProps {
+    onOpenFind?: () => void;
+    onOpenExport?: () => void;
+    onOpenShortcuts?: () => void;
+    /** Whether preview (read-only viewer) mode is currently active */
+    previewMode?: boolean;
+    /** Called when the user clicks the preview toggle pill */
+    onTogglePreview?: () => void;
+}
+
+declare interface EditorViewerProps {
+    content: JSONContent;
+    theme?: EditorTheme;
+    className?: string;
+    features?: EditorFeature[];
+    separatorIcon?: ReactNode;
+    showStats?: boolean;
+}
+export { EditorViewerProps }
+export { EditorViewerProps as MatopsViewerProps }
+
+export declare function ExportPanel({ open, onClose }: ExportPanelProps): JSX_2.Element | null;
+
+declare interface ExportPanelProps {
+    open: boolean;
+    onClose: () => void;
+}
+
+/**
+ * Extract the attachment list. Reads `doc.attrs.attachments.items` first,
+ * then falls back to the legacy `attachments` content node.
+ */
+export declare function extractAttachments(doc: JSONContent): AttachmentItem[];
+
+/**
+ * Extract `contentWidth`. Returns `DEFAULT_CONTENT_WIDTH` if absent or invalid.
+ */
+export declare function extractContentWidth(doc: JSONContent): ContentWidth;
+
+/**
+ * Extract the full cover-image attr object.
+ * Returns `null` if no cover image attr is present.
+ */
+export declare function extractCoverImageAttr(doc: JSONContent): CoverImageDocAttr | null;
+
+/**
+ * Extract the cover image src. Reads `doc.attrs.coverImage.src` first,
+ * then falls back to the legacy `cover-image` content node.
+ */
+export declare function extractCoverSrc(doc: JSONContent): string | null;
+
+/**
+ * Extract the separator icon src. Reads `doc.attrs.separatorIcon.src` first,
+ * then falls back to the legacy `separator-icon` content node.
+ */
+export declare function extractSeparatorIconSrc(doc: JSONContent): string | null;
+
+/**
+ * Extract the title text. Reads `doc.attrs.title.text` first,
+ * then falls back to the legacy `title` content node.
+ */
+export declare function extractTitle(doc: JSONContent): string;
+
+/**
+ * Extract the full title attr object.
+ * Returns `null` if no title attr is present.
+ */
+export declare function extractTitleAttr(doc: JSONContent): TitleDocAttr | null;
+
+export declare interface FeatureDefinition {
+    name: EditorFeature;
+    extensions: Extensions;
+    dependencies?: EditorFeature[];
+    enabled?: (activeFeatures: EditorFeature[]) => boolean;
+}
+
+declare class FeatureRegistry {
+    private readonly registry;
+    register(definition: FeatureDefinition): void;
+    resolve(requestedFeatures: EditorFeature[]): ResolvedEditorConfig;
+    has(name: EditorFeature): boolean;
+    get(name: EditorFeature): FeatureDefinition | undefined;
+    list(): EditorFeature[];
+    get size(): number;
+    unregister(name: EditorFeature): void;
+    clear(): void;
+    private resolveDependencies;
+    private filterEnabled;
+    private collectExtensions;
+}
+
+export declare const featureRegistry: FeatureRegistry;
+
+/**
+ * FindReplacePanel
+ *
+ * UI for the find-and-replace feature. Works with SearchExtension
+ * (extensions/plugins/searchPlugin.ts) which manages all ProseMirror
+ * decoration state.
+ *
+ * Optimisation notes vs original:
+ *  - Search (query + caseSensitive) and navigation (currentIndex) are
+ *    dispatched separately so changing the active match doesn't re-run the
+ *    full text search.
+ *  - Plugin state is read immediately after each dispatch (synchronous in
+ *    ProseMirror) so results are always consistent.
+ */
+export declare function FindReplacePanel({ open, onClose }: FindReplacePanelProps): JSX_2.Element | null;
+
+declare interface FindReplacePanelProps {
+    open: boolean;
+    onClose: () => void;
+}
+
+export declare function FormattingBubbleMenu(): JSX_2.Element | null;
+
+/**
+ * Returns the `attachments` attr from a live editor's document.
+ * Returns `null` if the attr is absent or null.
+ */
+export declare function getAttachmentsAttr(editor: Editor_2 | null): AttachmentsDocAttr | null;
+
+/**
+ * Returns the `contentWidth` stored in a live Tiptap editor's document,
+ * falling back to `DEFAULT_CONTENT_WIDTH` if the attr is missing or invalid.
+ *
+ * @example
+ * const width = getContentWidth(editor);
+ * // → "normal" | "compact" | "full"
+ */
+export declare function getContentWidth(editor: Editor_2 | null): ContentWidth;
+
+/**
+ * Returns the `coverImage` attr from a live editor's document.
+ * Returns `null` if the attr is absent or null.
+ */
+export declare function getCoverImageAttr(editor: Editor_2 | null): CoverImageDocAttr | null;
+
+/**
+ * Returns the `separatorIcon` attr from a live editor's document.
+ * Returns `null` if the attr is absent or null.
+ */
+export declare function getSeparatorIconAttr(editor: Editor_2 | null): SeparatorIconDocAttr | null;
+
+/**
+ * Returns the `title` attr from a live editor's document.
+ * Returns `null` if the attr is absent or null.
+ */
+export declare function getTitleAttr(editor: Editor_2 | null): TitleDocAttr | null;
+
+/**
+ * @matops/editor — Icon Library
+ *
+ * Single source of truth for all inline SVG icons used across the editor UI.
+ * No external icon library dependency — keeps bundle lean and icons consistent.
+ *
+ * Naming convention: <PurposeName>Icon
+ * All icons default to 14×14 unless a specific size is needed by their context.
+ */
+declare interface IconProps {
+    size?: number;
+}
+
+/**
+ * ImageBubbleMenu
+ *
+ * Appears when an image is selected. Provides:
+ *  - Text alignment (left / center / right)
+ *  - Alt text editing via prompt
+ *  - Delete image
+ *
+ * Uses `pluginKey="imageMenu"` to coexist with text + link bubble menus.
+ */
+export declare function ImageBubbleMenu(): JSX_2.Element | null;
+
+export declare function isDefaultCrop(crop: CropRect): boolean;
+
+/**
+ * KeyboardShortcutsModal
+ *
+ * Feature-aware keyboard shortcut reference.
+ * Only shows shortcuts whose `feature` is currently active.
+ * Closes on Escape or overlay click.
+ *
+ * Triggered by: `?` key (via useShortcutsModal) or toolbar Help button.
+ */
+export declare function KeyboardShortcutsModal({ open, onClose, }: KeyboardShortcutsModalProps): JSX_2.Element | null;
+
+declare interface KeyboardShortcutsModalProps {
+    open: boolean;
+    onClose: () => void;
+}
+
+/**
+ * LinkPopover
+ *
+ * Appears when the cursor is inside a link node.
+ * Two modes:
+ *  - Preview: shows URL with edit / open / unlink buttons
+ *  - Edit:    inline input field to change the URL
+ *
+ * Uses `pluginKey="linkMenu"` to coexist with the text formatting BubbleMenu.
+ */
+export declare function LinkPopover(): JSX_2.Element | null;
+
+export declare const MatopsDocument: Node_2<any, any>;
+
+declare function MatopsEditor(props: EditorProps): JSX_2.Element;
+export { MatopsEditor as Editor }
+export { MatopsEditor }
+export default MatopsEditor;
+
+declare function MatopsViewer({ content, theme, className, separatorIcon, showStats, }: EditorViewerProps): JSX_2.Element;
+export { MatopsViewer as EditorViewer }
+export { MatopsViewer }
+
+export declare function MenuButton({ onClick, isActive, isDisabled, isDanger, title, className, children, }: MenuButtonProps): JSX_2.Element;
+
+/**
+ * MenuButton — shared button primitive for all floating menus.
+ *
+ * Uses `onMouseDown` + `e.preventDefault()` to prevent the editor from
+ * losing focus when a menu button is pressed.
+ */
+declare interface MenuButtonProps {
+    onClick: () => void;
+    isActive?: boolean;
+    isDisabled?: boolean;
+    isDanger?: boolean;
+    title: string;
+    className?: string;
+    children: default_2.ReactNode;
+}
+
+export declare function MenuDivider(): JSX_2.Element;
+
+/**
+ * Migrate a **legacy** document (structural nodes in `content[]`) to the
+ * **external** format (structural metadata in `doc.attrs`).
+ *
+ * Safe to call on already-migrated documents — returns them unchanged.
+ * Alias of `toExternalFormat`.
+ */
+export declare const migrateToDocAttrs: typeof toExternalFormat;
+
+export declare function ModalDialog({ children, className, label, }: {
+    children: default_2.ReactNode;
+    className?: string;
+    label?: string;
+}): JSX_2.Element;
+
+export declare function ModalHeader({ title, onClose, }: {
+    title: string;
+    onClose: () => void;
+}): JSX_2.Element;
+
+export declare function ModalOverlay({ onClose, children, }: {
+    onClose: () => void;
+    children: default_2.ReactNode;
+}): default_2.ReactPortal;
+
+/**
+ * PageHeaderGuard — stub extension for the `"page-header"` feature.
+ * Previously guarded title + separator-icon content nodes; now a no-op since
+ * those sections live in doc.attrs and are rendered as React panels.
+ */
+export declare const PageHeaderGuard: Extension<any, any>;
+
+export declare function parseAttachments(raw: string | null | undefined): AttachmentItem[];
+
+export declare function readCropFromAttrs(attrs: unknown): CropRect;
+
+/**
+ * Rebuild a Tiptap document in **internal format** (structural nodes in `content[]`)
+ * from any input format: external (doc.attrs), legacy (structural content nodes),
+ * or internal (already has content nodes).
+ *
+ * Called by `Editor.tsx` when features change so that Tiptap always receives a
+ * document whose `content[]` contains the correct set of structural nodes for the
+ * active feature set.
+ *
+ * @param current         - Latest live document JSON (any format).
+ * @param hasCoverImage   - Whether `"cover-image"` feature is active.
+ * @param hasPageHeader   - Whether `"page-header"` feature is active.
+ * @param hasAttachments  - Whether `"attachments"` feature is active.
+ * @param fallbackContent - Used as a secondary source when structural data is
+ *                          absent from `current`. Defaults to `current`.
+ */
+export declare function rebuildContent(current: JSONContent, hasCoverImage: boolean, hasPageHeader: boolean, hasAttachments: boolean, fallbackContent?: JSONContent): JSONContent;
+
+export declare function registerFeature(definition: FeatureDefinition): void;
+
+declare interface ResolvedEditorConfig {
+    resolvedFeatures: EditorFeature[];
+    extensions: Extensions;
+}
+
+export declare const SearchExtension: Extension<any, any>;
+
+export declare interface SearchMatch {
+    from: number;
+    to: number;
+}
+
+export declare const searchPluginKey: PluginKey<SearchPluginState>;
+
+declare interface SearchPluginState {
+    query: string;
+    caseSensitive: boolean;
+    decorations: DecorationSet;
+    results: SearchMatch[];
+    currentIndex: number;
+}
+
+export declare interface SeparatorIconAttrs {
+    src: string | null;
+    alt: string;
+    cropX: number;
+    cropY: number;
+    cropWidth: number;
+    cropHeight: number;
+}
+
+export declare interface SeparatorIconDocAttr {
+    src: string | null;
+    alt: string;
+    cropX: number;
+    cropY: number;
+    cropWidth: number;
+    cropHeight: number;
+}
+
+export declare const SeparatorIconNode: Node_2<any, any>;
+
+/**
+ * SeparatorIconPanel — React panel (Panel 1) for the title/body separator.
+ *
+ * Reads from `editor.state.doc.attrs.separatorIcon` (a SeparatorIconDocAttr or null).
+ * Writes via `editor.commands.setSeparatorIconAttr(...)`.
+ *
+ * Renders:   ────── [badge] ──────
+ *
+ * Icon resolution priority:
+ *   1. doc.attrs.separatorIcon.src + crop → uploaded image, cropped
+ *   2. separatorIcon prop (ReactNode from EditorProvider)
+ *   3. Default quill SVG
+ *
+ * No ProseMirror NodeView — this is pure React rendered above <EditorContent>.
+ */
+export declare function SeparatorIconPanel(): JSX_2.Element | null;
+
+export declare function serializeAttachments(items: AttachmentItem[]): string;
+
+export declare function SlashMenu(): JSX_2.Element | null;
+
+/**
+ * Live defaults consumed by the table insert command in commandRegistry.ts
+ * and by the toolbar / slash-menu integrations.
+ *
+ * Do NOT mutate this object directly — use configureTablesFeature() instead
+ * so that the feature registration is re-run with the updated options.
+ */
+export declare const TABLE_DEFAULTS: Required<TableFeatureOptions>;
+
+/**
+ * TableContextMenu
+ *
+ * A BubbleMenu that appears whenever the cursor is inside a table.
+ * Uses `pluginKey="tableMenu"` to coexist with other BubbleMenus —
+ * FormattingBubbleMenu suppresses itself when `e.isActive("table")` so
+ * these two menus never overlap.
+ *
+ * Sections (always): Row | Column | Cell | Table
+ * Section (conditional): Format — shown only when text is selected inside
+ * a cell (from !== to), giving users bold/italic/etc. without needing to
+ * dismiss the table menu first.
+ *
+ * v3: imports from @tiptap/react/menus, uses `options` (not `tippyOptions`).
+ */
+export declare function TableContextMenu(): JSX_2.Element | null;
+
+/**
+ * @feature tables
+ *
+ * Provides rich table support built on top of @tiptap/extension-table's
+ * TableKit bundle (Table + TableRow + TableHeader + TableCell).
+ *
+ * ── What this feature provides ────────────────────────────────────────
+ *
+ *  Extensions (Tiptap)
+ *    • Table              — the table node with column-resize handles
+ *    • TableRow           — <tr> node
+ *    • TableHeader        — <th> node with default header styling
+ *    • TableCell          — <td> node
+ *
+ *  UI (activated automatically when this feature is resolved)
+ *    • Toolbar button     — "Insert Table" icon in the toolbar block strip
+ *    • Slash command      — /table inserts a default-sized table
+ *    • TableContextMenu   — BubbleMenu that appears inside a table with
+ *                           Row / Column / Cell / Table action sections
+ *
+ *  Keyboard shortcuts (built into Tiptap table extensions)
+ *    • Tab                — move to next cell (creates new row at end)
+ *    • Shift+Tab          — move to previous cell
+ *
+ * ── Enabled vs disabled ───────────────────────────────────────────────
+ *
+ *  Enabled  → TableKit is loaded. All of the above are active. The toolbar
+ *             table button and /table slash command both insert a table with
+ *             TABLE_DEFAULTS rows, cols, and withHeaderRow settings.
+ *
+ *  Disabled → No table schema. Existing table nodes in a document will not
+ *             parse correctly and content may be lost. If you need read-only
+ *             table rendering without the editing UI, keep this feature on
+ *             and set `editable={false}` on the editor instead.
+ *
+ * ── Custom configuration ──────────────────────────────────────────────
+ *
+ *  Call configureTablesFeature(options) BEFORE featureBootstrap runs to
+ *  override the defaults. Typically done in your app entry point:
+ *
+ *    import { configureTablesFeature } from "@matops/editor/extensions/features/tablesFeature";
+ *
+ *    configureTablesFeature({
+ *      resizable:       true,
+ *      cellMinWidth:    80,
+ *      defaultRows:     4,
+ *      defaultCols:     4,
+ *      withHeaderRow:   true,
+ *    });
+ *
+ *  featureBootstrap.ts still re-imports this file — the registration is
+ *  idempotent (it warns and overwrites on duplicate) so calling
+ *  configureTablesFeature() first is safe and the correct approach.
+ *
+ * ── Dependencies ─────────────────────────────────────────────────────
+ *  Requires "formatting" because TableCell content is paragraph-based and
+ *  needs the paragraph + text extensions already registered.
+ */
+/**
+ * Options for the "tables" feature.
+ *
+ * All fields are optional — unset fields fall back to TABLE_DEFAULTS.
+ */
+export declare interface TableFeatureOptions {
+    /**
+     * Allow column widths to be dragged to resize.
+     * @default true
+     */
+    resizable?: boolean;
+    /**
+     * Minimum width in pixels for every table cell.
+     * Prevents columns from collapsing to zero when resizing.
+     * @default 100
+     */
+    cellMinWidth?: number;
+    /**
+     * Whether the last column can be resized.
+     * Set false when the table fills the full content width and the last
+     * column should stretch to absorb any remaining space.
+     * @default true
+     */
+    lastColumnResizable?: boolean;
+    /**
+     * Number of rows inserted when a new table is created via the toolbar
+     * button or the /table slash command.
+     * @default 3
+     */
+    defaultRows?: number;
+    /**
+     * Number of columns inserted when a new table is created.
+     * @default 3
+     */
+    defaultCols?: number;
+    /**
+     * Whether newly inserted tables include a styled header row.
+     * @default true
+     */
+    withHeaderRow?: boolean;
+}
+
+export declare interface TitleAttrs {
+    placeholder: string;
+}
+
+export declare interface TitleDocAttr {
+    text: string;
+    placeholder: string;
+}
+
+export declare const TitleNode: Node_2<any, any>;
+
+/**
+ * TitlePanel — React panel (Panel 1) for the document title.
+ *
+ * Reads from `editor.state.doc.attrs.title` (a TitleDocAttr or null).
+ * Writes via `editor.commands.setTitleAttr({ text })`.
+ *
+ * Uses a contentEditable div so the user gets native text-editing behaviour
+ * (cursor, selection, copy/paste). The doc.attrs.title.text is the source of
+ * truth; the div is kept in sync via a ref and only triggers a command when
+ * the user actually changes the text (avoids re-render loops).
+ *
+ * No ProseMirror NodeView — this is pure React rendered above <EditorContent>.
+ */
+export declare function TitlePanel(): JSX_2.Element | null;
+
+export declare function TitleSeparator({ icon, hasImageIcon }: TitleSeparatorProps): JSX_2.Element;
+
+declare interface TitleSeparatorProps {
+    /** Custom icon to render in the centre badge. Defaults to the quill SVG. */
+    icon?: ReactNode;
+    /**
+     * Set to true when the icon is an uploaded image that may use position:absolute
+     * crop styles. Adds `overflow:hidden` + `position:relative` to the badge span
+     * so the cropped image is clipped correctly.
+     */
+    hasImageIcon?: boolean;
+}
+
+/**
+ * Convert a Tiptap **internal** document (structural nodes in `content[]`) to
+ * **external** format (structural metadata in `doc.attrs`, body-only `content[]`).
+ *
+ * This is called inside `useEditorInstance` before firing `onChange` so that
+ * consumers always receive the canonical external format regardless of how
+ * Tiptap stores the document internally.
+ *
+ * Safe to call on documents already in external format — returns them unchanged.
+ */
+export declare function toExternalFormat(doc: JSONContent): JSONContent;
+
+/**
+ * Convert a Tiptap JSONContent node tree to Markdown.
+ *
+ * Supports all standard nodes plus the page-header nodes:
+ *  - `cover-image` → HTML img tag (no native Markdown equivalent)
+ *  - `title`       → # heading (H1)
+ *
+ * @param node  - The JSONContent node to serialize
+ * @param depth - Indentation depth for nested lists (internal)
+ */
+export declare function toMarkdown(node: JSONContent, depth?: number): string;
+
+export declare const UploadIcon: ({ size }: IconProps) => JSX_2.Element;
+
+/**
+ * useDropdown
+ *
+ * Shared hook for portal-based dropdown menus used in EditorToolbar and
+ * FormattingBubbleMenu. Handles:
+ *   - Open / close state
+ *   - Post-render position measurement (via useLayoutEffect)
+ *   - Viewport clamping so the menu never overflows the screen
+ *   - Close on outside click and scroll
+ *
+ * The menu is initially rendered off-screen (left: -9999) and becomes
+ * visible only after its real dimensions are measured.
+ *
+ * @example
+ * const { open, visible, dropPos, triggerRef, menuRef, toggle, close } =
+ *   useDropdown({ offset: 6 });
+ */
+export declare function useDropdown({ offset }?: UseDropdownOptions): UseDropdownResult;
+
+declare interface UseDropdownOptions {
+    /** Extra vertical gap between trigger and menu (px). Default 4. */
+    offset?: number;
+}
+
+declare interface UseDropdownResult {
+    open: boolean;
+    visible: boolean;
+    dropPos: DropdownPosition;
+    triggerRef: RefObject<HTMLButtonElement>;
+    menuRef: RefObject<HTMLDivElement>;
+    toggle: () => void;
+    close: () => void;
+}
+
+/**
+ * Returns the live Tiptap editor instance, or null while initializing.
+ */
+export declare const useEditor: () => Editor_2 | null;
+
+/**
+ * Returns the raw EditorContext value.
+ * Use the focused hooks in editorHooks.ts for most cases — this is
+ * only needed when accessing onFileUploaded or separatorIcon directly.
+ */
+export declare function useEditorContext(): EditorContextValue;
+
+/**
+ * useEditorInstance
+ *
+ * Manages the full Tiptap editor lifecycle for the <Editor> component.
+ *
+ * Design decisions:
+ *  - `buildEditorConfig` is called once on mount and stored in a ref. The
+ *    feature list and placeholder are intentionally not reactive — changing
+ *    them after mount would require destroying and recreating the entire editor.
+ *  - Callback props (onChange, onContentChange, onEditorReady) are stored in
+ *    refs so they can be updated without recreating the editor instance.
+ *  - `editable` is the only prop synced reactively via editor.setEditable().
+ */
+export declare function useEditorInstance({ features, initialContent, editable, placeholder, collaborationProvider, onChange, onContentChange, onEditorReady, }: UseEditorInstanceOptions): UseEditorInstanceResult;
+
+/**
+ * Subset of EditorProps consumed by this hook.
+ * Uses Pick so adding a prop to EditorProps automatically makes it available here.
+ *
+ * NOTE: "placeholder" is intentionally included even though the Placeholder
+ * extension is configured at build time (not Tiptap's internal placeholder).
+ * It must flow through here → buildEditorConfig → Placeholder.configure().
+ */
+declare type UseEditorInstanceOptions = Pick<EditorProps, "features" | "initialContent" | "editable" | "placeholder" | "collaborationProvider" | "onChange" | "onContentChange" | "onEditorReady">;
+
+declare interface UseEditorInstanceResult {
+    editor: Editor_2 | null;
+    resolvedFeatures: EditorFeature[];
+}
+
+/**
+ * useEditorKeyboard
+ *
+ * Central hub for all global keyboard shortcuts that live outside the
+ * Tiptap extension system. Tiptap handles its own shortcuts (bold, italic, etc.)
+ * internally — this hook only manages shortcuts that need React state or that
+ * trigger UI panels/modals.
+ *
+ * Shortcuts managed here:
+ *  - Ctrl/Cmd + Shift + P  →  onPublish (save/publish document)
+ *  - Ctrl/Cmd + F          →  open Find & Replace panel
+ *
+ * To add a new shortcut:
+ *  1. Add its handler inside the `handler` function below
+ *  2. Add it to KeyboardShortcutsModal.tsx SHORTCUTS data array
+ *
+ * Shortcuts NOT managed here:
+ *  - `?` → KeyboardShortcutsModal (managed by useShortcutsModal)
+ *  - Formatting shortcuts (Bold, Italic…) → handled by Tiptap extensions
+ *  - Table navigation (Tab) → handled by Tiptap table extension
+ *  - Slash command (/) → handled by SlashMenu
+ *  - Escape → handled locally in each panel/modal component
+ */
+export declare function useEditorKeyboard({ editor, editable, resolvedFeatures, onPublish, onOpenFind, }: UseEditorKeyboardOptions): void;
+
+declare interface UseEditorKeyboardOptions {
+    editor: Editor_2 | null;
+    editable: boolean;
+    resolvedFeatures: EditorFeature[];
+    onPublish?: (content: JSONContent) => void;
+    onOpenFind?: () => void;
+}
+
+/**
+ * Subscribes to a derived slice of editor state.
+ * Re-renders only when the selected value changes (by reference equality).
+ *
+ * @example
+ * const isBold = useEditorState(ed => ed?.isActive("bold") ?? false);
+ */
+export declare function useEditorState<T>(selector: (editor: Editor_2 | null) => T): T;
+
+/**
+ * Returns the current editor theme.
+ */
+export declare function useEditorTheme(): EditorTheme;
+
+/**
+ * Forces a re-render on every editor transaction.
+ * Use when you need UI to stay in sync with every state change.
+ */
+export declare function useEditorUpdate(): void;
+
+/**
+ * Returns true if a single feature is active in the current editor instance.
+ */
+export declare function useFeature(feature: EditorFeature): boolean;
+
+/**
+ * Returns a map of all feature flags as named booleans.
+ * Prefer this over multiple `useFeature` calls in the same component.
+ */
+export declare function useFeatures(): {
+    hasFormatting: boolean;
+    hasCode: boolean;
+    hasMedia: boolean;
+    hasTables: boolean;
+    hasTaskList: boolean;
+    hasCollaboration: boolean;
+    hasHistory: boolean;
+    hasPlaceholder: boolean;
+    hasCharCount: boolean;
+    hasFindReplace: boolean;
+    hasCoverImage: boolean;
+    hasPageHeader: boolean;
+    hasAttachments: boolean;
+};
+
+export declare function useImageUpload({ editor, editable, onFileUploaded, containerRef, }: UseImageUploadOptions): void;
+
+declare interface UseImageUploadOptions {
+    editor: Editor_2 | null;
+    editable: boolean;
+    onFileUploaded?: (file: File) => Promise<string>;
+    containerRef?: React.RefObject<HTMLElement>;
+}
+
+/**
+ * useShortcutsModal
+ *
+ * Manages open/close state for the KeyboardShortcutsModal.
+ * Binds the `?` key globally to toggle the modal, but only when
+ * the active element is not a text input or textarea (to avoid
+ * interfering with typing "?" in form fields or in the editor itself).
+ *
+ * Usage in parent:
+ * ```ts
+ * const { open, onClose, setOpen } = useShortcutsModal();
+ * <KeyboardShortcutsModal open={open} onClose={onClose} />
+ * ```
+ */
+export declare function useShortcutsModal(): {
+    open: boolean;
+    setOpen: Dispatch<SetStateAction<boolean>>;
+    onClose: () => void;
+};
+
+export { }
+
+
+/** Augment Tiptap's Commands interface so TypeScript knows about all doc-attr setters. */
+declare module "@tiptap/core" {
+    interface Commands<ReturnType> {
+        matopsDocument: {
+            /**
+             * Update the document-level `contentWidth` layout attribute.
+             *
+             * @example
+             * editor.commands.setContentWidth("compact")
+             */
+            setContentWidth: (width: MatopsContentWidth) => ReturnType;
+            /**
+             * Set or clear the cover-image doc attr.
+             *
+             * Pass a partial `CoverImageDocAttr` to merge into the existing value,
+             * or `null` to remove the cover image (keeps the attr key with null value
+             * so the feature knows the slot exists).
+             *
+             * @example
+             * editor.commands.setCoverImageAttr({ src: "https://cdn.example.com/banner.jpg" })
+             * editor.commands.setCoverImageAttr(null)   // clear image
+             */
+            setCoverImageAttr: (value: Partial<CoverImageDocAttr> | null) => ReturnType;
+            /**
+             * Update the title text and/or placeholder stored in the doc attr.
+             *
+             * @example
+             * editor.commands.setTitleAttr({ text: "My Document" })
+             * editor.commands.setTitleAttr({ text: "Draft", placeholder: "Untitled" })
+             */
+            setTitleAttr: (value: Partial<TitleDocAttr> | null) => ReturnType;
+            /**
+             * Set or clear the separator-icon doc attr.
+             *
+             * @example
+             * editor.commands.setSeparatorIconAttr({ src: "https://cdn.example.com/logo.png" })
+             * editor.commands.setSeparatorIconAttr(null)  // revert to default icon
+             */
+            setSeparatorIconAttr: (value: Partial<SeparatorIconDocAttr> | null) => ReturnType;
+            /**
+             * Replace the attachments list stored in the doc attr.
+             *
+             * @example
+             * editor.commands.setAttachmentsAttr([
+             *   { id: "a1", name: "brief.pdf", size: 51200, mimeType: "application/pdf", url: "https://…" }
+             * ])
+             */
+            setAttachmentsAttr: (items: AttachmentItem[]) => ReturnType;
+        };
+    }
+}