mardora 1.2.0

package/dist/mardora-DCwjomil.d.cts

@@ -0,0 +1,640 @@
+import * as _codemirror_state from '@codemirror/state';
+import { Range, Extension } from '@codemirror/state';
+import { EditorView, Decoration, KeyBinding, ViewUpdate } from '@codemirror/view';
+import { MarkdownConfig } from '@lezer/markdown';
+import * as _lezer_highlight from '@lezer/highlight';
+import { SyntaxNode } from '@lezer/common';
+import { StyleSpec } from 'style-mod';
+
+/**
+ * Deep merge two objects
+ * @param a - First object
+ * @param b - Second object
+ * @returns Merged object
+ */
+declare function deepMerge<T>(a: T, b?: T): T;
+/**
+ * Theme style
+ */
+type ThemeStyle = {
+    [selector: string]: StyleSpec;
+};
+/**
+ * Theme Enum
+ */
+declare enum ThemeEnum {
+    DARK = "dark",
+    LIGHT = "light",
+    AUTO = "auto"
+}
+/**
+ * Function to create the themes
+ *
+ * @param defaultTheme - Default theme -- Always applied
+ * @param darkTheme - Dark theme -- Applied when theme is "dark" or "auto" and system is dark
+ * @param lightTheme - Light theme -- Applied when theme is "light" or "auto" and system is light
+ * @returns Theme function
+ */
+declare function createTheme({ default: defaultTheme, dark: darkTheme, light: lightTheme, }: {
+    default: ThemeStyle;
+    dark?: ThemeStyle;
+    light?: ThemeStyle;
+}): (theme: ThemeEnum) => ThemeStyle;
+declare function flattenThemeStyles(themeStyles: ThemeStyle, parentSelector?: string): ThemeStyle;
+declare function fixSelector(selector: string): string;
+/**
+ * Check if cursor is within the given range
+ */
+declare function cursorInRange(view: EditorView, from: number, to: number): boolean;
+/**
+ * Check if any selection overlaps with the given range
+ */
+declare function selectionOverlapsRange(view: EditorView, from: number, to: number): boolean;
+/**
+ * Toggle markdown style on selection or insert markers at cursor
+ * @param marker - The markdown marker (e.g., "**" for bold, "*" for italic)
+ * @returns Command function for EditorView
+ */
+declare function toggleMarkdownStyle(marker: string): (view: EditorView) => boolean;
+
+/**
+ * Context passed to plugin lifecycle methods
+ */
+interface PluginContext {
+    /** Current configuration */
+    readonly config: MardoraConfig;
+}
+/**
+ * Plugin configuration schema
+ */
+interface PluginConfig {
+    [key: string]: unknown;
+}
+/**
+ * Decoration context passed to plugin decoration builders
+ * Provides access to view state and decoration collection
+ */
+interface DecorationContext {
+    /** The EditorView instance (readonly) */
+    readonly view: EditorView;
+    /** Array to push decorations into (will be sorted automatically) */
+    readonly decorations: Range<Decoration>[];
+    /** Check if selection overlaps with a range (to show raw markdown) */
+    selectionOverlapsRange(from: number, to: number): boolean;
+    /** Check if cursor is within a range */
+    cursorInRange(from: number, to: number): boolean;
+}
+/**
+ * Abstract base class for all mardora plugins
+ *
+ * Implements OOP principles:
+ * - Abstraction: abstract name/version must be implemented by subclasses
+ * - Encapsulation: private _config, protected _context
+ * - Inheritance: specialized plugin classes can extend this
+ */
+declare abstract class MardoraPlugin {
+    /** Unique plugin identifier (abstract - must be implemented) */
+    abstract readonly name: string;
+    /** Plugin version (abstract - must be implemented) */
+    abstract readonly version: string;
+    /** Decoration priority (higher = applied later) */
+    readonly decorationPriority: number;
+    /** Plugin dependencies - names of required plugins */
+    readonly dependencies: string[];
+    /** Node types this plugin handles for decorations and preview rendering */
+    readonly requiredNodes: readonly string[];
+    /** Private configuration storage */
+    private _config;
+    /** Protected context - accessible to subclasses */
+    protected _context: PluginContext | null;
+    /** Get plugin configuration */
+    get config(): PluginConfig;
+    /** Set plugin configuration */
+    set config(value: PluginConfig);
+    /** Get plugin context */
+    get context(): PluginContext | null;
+    /** Plugin theme */
+    get theme(): (theme: ThemeEnum) => ThemeStyle;
+    /**
+     * Return CodeMirror extensions for this plugin
+     * Override to provide custom extensions
+     */
+    getExtensions(): Extension[];
+    /**
+     * Return markdown parser extensions
+     * Override to extend markdown parsing
+     */
+    getMarkdownConfig(): MarkdownConfig | null;
+    /**
+     * Return keybindings for this plugin
+     * Override to add custom keyboard shortcuts
+     */
+    getKeymap(): KeyBinding[];
+    /**
+     * Build decorations for the current view state
+     * Override to contribute decorations to the editor
+     *
+     * @param ctx - Decoration context with view and decoration array
+     */
+    buildDecorations(_ctx: DecorationContext): void;
+    /**
+     * Called when plugin is registered with mardora
+     * Override to perform initialization
+     *
+     * @param context - Plugin context with configuration
+     */
+    onRegister(context: PluginContext): void | Promise<void>;
+    /**
+     * Called when plugin is unregistered
+     * Override to perform cleanup
+     */
+    onUnregister(): void;
+    /**
+     * Called when EditorView is created and ready
+     * Override to perform view-specific initialization
+     *
+     * @param view - The EditorView instance
+     */
+    onViewReady(_view: EditorView): void;
+    /**
+     * Called on view updates (document changes, selection changes, etc.)
+     * Override to react to editor changes
+     *
+     * @param update - The ViewUpdate with change information
+     */
+    onViewUpdate(_update: ViewUpdate): void;
+    /**
+     * Helper to get current editor state
+     * @param view - The EditorView instance
+     */
+    protected getState(view: EditorView): _codemirror_state.EditorState;
+    /**
+     * Helper to get current document
+     * @param view - The EditorView instance
+     */
+    protected getDocument(view: EditorView): _codemirror_state.Text;
+    /**
+     * Render a syntax node to HTML for preview mode
+     * Override to provide custom HTML rendering for specific node types
+     *
+     * @param node - The syntax node to render
+     * @param children - Pre-rendered children HTML
+     * @param ctx - Preview context with document and utilities
+     * @returns HTML string to use, or null to use default rendering
+     */
+    renderToHTML?(node: SyntaxNode, children: string, ctx: {
+        doc: string;
+        sliceDoc(from: number, to: number): string;
+        sanitize(html: string): string;
+        syntaxHighlighters?: readonly _lezer_highlight.Highlighter[];
+    }): string | null | Promise<string | null>;
+    /**
+     * Return the document position consumed by preview rendering.
+     * Plugins can use this when a rendered node owns trailing syntax that is
+     * outside the Lezer node range, such as image attributes.
+     */
+    getPreviewConsumedTo?(node: SyntaxNode, ctx: {
+        doc: string;
+        sliceDoc(from: number, to: number): string;
+    }): number | null;
+    /**
+     * Get CSS styles for preview mode
+     * Override to provide custom CSS for preview rendering
+     *
+     * @param theme - Current theme enum
+     * @returns CSS string for preview styles
+     */
+    getPreviewStyles(theme: ThemeEnum, wrapperClass: string): string;
+    /**
+     * Transform ThemeStyle object to CSS string for preview
+     * Uses cssClassMap to convert CM selectors to semantic selectors
+     */
+    protected transformToCss(themeStyles: ThemeStyle, wrapperClass: string): string;
+}
+/**
+ * Base class for plugins that primarily contribute decorations
+ * Extends MardoraPlugin with decoration-focused defaults
+ */
+declare abstract class DecorationPlugin extends MardoraPlugin {
+    /**
+     * Decoration priority - lower than default for decoration plugins
+     * Override to customize
+     */
+    decorationPriority: number;
+    /**
+     * Subclasses must implement this to provide decorations
+     * @param ctx - Decoration context
+     */
+    abstract buildDecorations(ctx: DecorationContext): void;
+}
+/**
+ * Base class for plugins that add syntax/parser extensions
+ * Extends MardoraPlugin with syntax-focused requirements
+ */
+declare abstract class SyntaxPlugin extends MardoraPlugin {
+    /**
+     * Subclasses must implement this to provide markdown config
+     */
+    abstract getMarkdownConfig(): MarkdownConfig;
+}
+
+type MardoraAttachmentKind = "image" | "video" | "audio" | "file";
+type MardoraAttachmentUploadSource = "slash" | "paste" | "drop" | "api";
+type MardoraAttachmentUploadContext = {
+    kind: MardoraAttachmentKind;
+    source: MardoraAttachmentUploadSource;
+    documentText: string;
+    selection: {
+        from: number;
+        to: number;
+    };
+};
+type MardoraAttachmentUploadResult = {
+    url: string;
+    name?: string;
+    title?: string;
+    mimeType?: string;
+};
+type MardoraAttachmentUploader = (file: File, context: MardoraAttachmentUploadContext) => Promise<MardoraAttachmentUploadResult>;
+type MardoraAttachmentAccept = Partial<Record<MardoraAttachmentKind, string[]>>;
+type MardoraAttachmentsConfig = {
+    enabled?: boolean;
+    uploader?: MardoraAttachmentUploader;
+    accept?: MardoraAttachmentAccept;
+    enablePaste?: boolean;
+    enableDrop?: boolean;
+};
+type MardoraFileLike = {
+    name: string;
+    type: string;
+};
+
+type MardoraLocale = "zh-CN" | "en-US";
+type MardoraI18nConfig = {
+    locale?: MardoraLocale;
+};
+declare const defaultMardoraLocale: MardoraLocale;
+declare function resolveMardoraLocale(locale?: MardoraLocale): MardoraLocale;
+
+type MardoraSlashCommandGroup = "basic" | "media";
+type MardoraSlashMessages = {
+    groups: Record<MardoraSlashCommandGroup, string>;
+    empty: string;
+    close: string;
+    closeHint: string;
+};
+type MardoraSlashCommandContext = {
+    view: EditorView;
+    queryRange: {
+        from: number;
+        to: number;
+    };
+    requestAttachment?: (kind: MardoraAttachmentKind, context: MardoraSlashCommandContext) => boolean;
+};
+type MardoraSlashCommand = {
+    id: string;
+    group: MardoraSlashCommandGroup;
+    title: string;
+    aliases: string[];
+    icon: string;
+    hint: string;
+    run: (context: MardoraSlashCommandContext) => boolean;
+};
+type MardoraSlashQuery = {
+    from: number;
+    to: number;
+    query: string;
+};
+type MardoraSlashCommandsConfig = {
+    enabled?: boolean;
+    locale?: MardoraLocale;
+    commands?: MardoraSlashCommand[];
+};
+
+type MardoraIconName = "arrow-down" | "arrow-down-to-line" | "arrow-left" | "arrow-left-to-line" | "arrow-right" | "arrow-right-to-line" | "arrow-up" | "arrow-up-to-line" | "badge-alert" | "baseline" | "bold" | "code" | "code-xml" | "copy" | "external-link" | "file" | "heading-1" | "heading-2" | "heading-3" | "heading-4" | "heading-5" | "heading-6" | "highlighter" | "image" | "info" | "italic" | "link" | "lightbulb" | "list" | "list-ordered" | "list-todo" | "maximize-2" | "minus" | "music-2" | "octagon-alert" | "play" | "rotate-ccw" | "strikethrough" | "table" | "table-delete" | "table-of-contents" | "text-align-start" | "text-quote" | "trash-2" | "triangle-alert" | "underline" | "type" | "x";
+declare function hasMardoraIcon(name: string): name is MardoraIconName;
+declare function createMardoraIcon(name: string): SVGSVGElement | null;
+
+type SelectionToolbarMessages = {
+    buttons: {
+        blockType: string;
+        bold: string;
+        italic: string;
+        strike: string;
+        underline: string;
+        code: string;
+        highlight: string;
+        color: string;
+        link: string;
+        orderedList: string;
+        unorderedList: string;
+        taskList: string;
+    };
+    panels: {
+        textColor: string;
+        highlightColor: string;
+    };
+    link: {
+        title: string;
+        url: string;
+        copy: string;
+        copied: string;
+        open: string;
+        remove: string;
+        invalid: string;
+    };
+    blockTypes: Record<SelectionToolbarBlockType, string>;
+    colors: {
+        defaultText: string;
+        gray: string;
+        red: string;
+        orange: string;
+        yellow: string;
+        green: string;
+        blue: string;
+        purple: string;
+        defaultHighlight: string;
+        yellowHighlight: string;
+        greenHighlight: string;
+        blueHighlight: string;
+        pinkHighlight: string;
+        purpleHighlight: string;
+    };
+};
+declare function getSelectionToolbarMessages(locale: MardoraLocale): SelectionToolbarMessages;
+
+type MardoraSelectionToolbarConfig = {
+    enabled?: boolean;
+    locale?: MardoraLocale;
+};
+type SelectionToolbarPlacement = "top" | "bottom";
+type SelectionToolbarAnchorRect = {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+};
+type SelectionToolbarViewport = {
+    width: number;
+    height: number;
+};
+type SelectionToolbarFloatingSize = {
+    width: number;
+    height: number;
+};
+type SelectionToolbarBoundary = {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+};
+type SelectionToolbarLayoutInput = {
+    anchor: SelectionToolbarAnchorRect;
+    viewport: SelectionToolbarViewport;
+    boundary?: SelectionToolbarBoundary;
+    floating: SelectionToolbarFloatingSize;
+};
+type SelectionToolbarLayout = {
+    placement: SelectionToolbarPlacement;
+    left: number;
+    top: number;
+    maxHeight: number;
+};
+type SelectionToolbarActionId = "block-type" | "bold" | "italic" | "strike" | "underline" | "code" | "highlight" | "color" | "link" | "ordered-list" | "unordered-list" | "task-list";
+type SelectionToolbarButton = {
+    id: SelectionToolbarActionId;
+    label: string;
+    icon: MardoraIconName;
+    text?: string;
+    active?: boolean;
+};
+type TextChange = {
+    from: number;
+    to: number;
+    insert: string;
+};
+type TextSelection = {
+    anchor: number;
+    head?: number;
+};
+type TextCommandResult = {
+    changes: TextChange | TextChange[];
+    selection?: TextSelection;
+};
+type InlineFormatInput = {
+    doc: string;
+    from: number;
+    to: number;
+    marker?: string;
+    htmlTag?: "u";
+    spanStyle?: {
+        property: "color" | "background-color";
+        value: string;
+    };
+    clear?: boolean;
+};
+type ParsedSelectionLink = {
+    kind: "markdown-link";
+    title: string;
+    url: string;
+} | {
+    kind: "url";
+    title: string;
+    url: string;
+} | {
+    kind: "text";
+    title: string;
+    url: string;
+};
+type LinkChangeInput = {
+    from: number;
+    to: number;
+    title: string;
+    url: string;
+    remove?: boolean;
+};
+type SelectionToolbarListKind = "ordered" | "unordered" | "task";
+type SelectionToolbarBlockType = "text" | "heading-1" | "heading-2" | "heading-3" | "heading-4" | "heading-5" | "heading-6";
+type SelectionToolbarPanel = "toolbar" | "link" | "color" | "highlight" | "block-type";
+type SelectionToolbarPaletteItem = {
+    id: string;
+    label: string;
+    value: string | null;
+};
+type SelectionToolbarLinkState = {
+    title: string;
+    url: string;
+    canRemove: boolean;
+    error?: string;
+    copied?: boolean;
+};
+type SelectionToolbarMenuState = {
+    panel: SelectionToolbarPanel;
+    buttons: SelectionToolbarButton[];
+    blockType: SelectionToolbarBlockType;
+    blockTypes: Array<{
+        type: SelectionToolbarBlockType;
+        label: string;
+        icon: MardoraIconName;
+    }>;
+    textColors: SelectionToolbarPaletteItem[];
+    highlightColors: SelectionToolbarPaletteItem[];
+    link: SelectionToolbarLinkState;
+    messages: SelectionToolbarMessages;
+};
+type SelectionToolbarMenuCallbacks = {
+    onAction: (id: SelectionToolbarActionId) => void;
+    onBlockType: (type: SelectionToolbarBlockType) => void;
+    onColor: (value: string | null) => void;
+    onHighlight: (value: string | null) => void;
+    onLinkInput: (field: "title" | "url", value: string) => void;
+    onLinkSubmit: () => void;
+    onLinkCopy: () => void;
+    onLinkOpen: () => void;
+    onLinkRemove: () => void;
+    onCancelPanel: () => void;
+};
+
+type MardoraTocLevel = 2 | 3 | 4 | 5 | 6;
+interface MardoraTocItem {
+    id: string;
+    level: MardoraTocLevel;
+    text: string;
+    from?: number;
+    to?: number;
+    active: boolean;
+}
+interface MardoraTocConfig {
+    enabled?: boolean;
+    onTocChange?: (items: MardoraTocItem[]) => void;
+    minLevel?: MardoraTocLevel;
+    maxLevel?: MardoraTocLevel;
+    defaultExpanded?: boolean;
+    defaultWidth?: number;
+    minWidth?: number;
+    maxWidth?: number;
+    storageKey?: string;
+}
+interface ResolvedMardoraTocConfig {
+    enabled: boolean;
+    onTocChange?: (items: MardoraTocItem[]) => void;
+    minLevel: MardoraTocLevel;
+    maxLevel: MardoraTocLevel;
+    defaultExpanded: boolean;
+    defaultWidth: number;
+    minWidth: number;
+    maxWidth: number;
+    storageKey?: string;
+}
+interface TocPanelState {
+    expanded: boolean;
+    width: number;
+}
+interface TocStorageAdapter {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): unknown;
+}
+
+type MardoraHeadingFoldLevel = 2 | 3 | 4 | 5;
+interface MardoraHeadingFoldConfig {
+    enabled?: boolean;
+    minLevel?: MardoraHeadingFoldLevel;
+    maxLevel?: MardoraHeadingFoldLevel;
+}
+interface ResolvedMardoraHeadingFoldConfig {
+    enabled: boolean;
+    minLevel: MardoraHeadingFoldLevel;
+    maxLevel: MardoraHeadingFoldLevel;
+}
+interface MardoraHeadingFoldRange {
+    level: MardoraHeadingFoldLevel;
+    text: string;
+    headingFrom: number;
+    headingTo: number;
+    headingLineFrom: number;
+    headingLineTo: number;
+    foldFrom: number;
+    foldTo: number;
+}
+
+/**
+ * MardoraNode: represents a node in the markdown tree
+ *
+ * Useful for debugging and development
+ */
+type MardoraNode = {
+    from: number;
+    to: number;
+    name: string;
+    children: MardoraNode[];
+    isSelected: boolean;
+};
+/**
+ * Configuration options for the mardora editor
+ */
+interface MardoraConfig {
+    /** Theme */
+    theme?: ThemeEnum;
+    /** Editor UI locale. Defaults to Simplified Chinese. */
+    locale?: MardoraLocale;
+    /** Internationalization configuration for editor-owned UI text */
+    i18n?: MardoraI18nConfig;
+    /** Weather to load base styles */
+    baseStyles?: boolean;
+    /** Plugins to load */
+    plugins?: MardoraPlugin[];
+    /** Additional markdown extensions for the parser */
+    markdown?: MarkdownConfig[];
+    /** Additional CodeMirror extensions */
+    extensions?: Extension[];
+    /** Additional keybindings */
+    keymap?: KeyBinding[];
+    /** Disable the built-in view plugin (for raw markdown mode) */
+    disableViewPlugin?: boolean;
+    /** Enable default keybindings */
+    defaultKeybindings?: boolean;
+    /** Enable history */
+    history?: boolean;
+    /** Enable indent with tab */
+    indentWithTab?: boolean;
+    /** Highlight active line */
+    highlightActiveLine?: boolean;
+    /** Line wrapping in raw markdown mode */
+    lineWrapping?: boolean;
+    /** Callback to receive the nodes on every update */
+    onNodesChange?: (nodes: MardoraNode[]) => void;
+    /** Slash command menu configuration */
+    slashCommands?: MardoraSlashCommandsConfig;
+    /** Browser attachment upload configuration */
+    attachments?: MardoraAttachmentsConfig;
+    /** Selected text floating toolbar configuration */
+    selectionToolbar?: MardoraSelectionToolbarConfig;
+    /** Table of contents configuration */
+    toc?: MardoraTocConfig;
+    /** Heading section folding configuration */
+    headingFold?: MardoraHeadingFoldConfig;
+}
+/**
+ * Creates a mardora editor extension bundle for CodeMirror 6
+ *
+ * @param config - Configuration options for the editor
+ * @returns CodeMirror Extension that can be added to EditorState
+ *
+ * @example
+ * ```ts
+ * import { EditorView } from '@codemirror/view';
+ * import { EditorState } from '@codemirror/state';
+ * import { mardora } from 'mardora';
+ *
+ * const view = new EditorView({
+ *   state: EditorState.create({
+ *     doc: '# Hello mardora',
+ *     extensions: [mardora()]
+ *   }),
+ *   parent: document.getElementById('editor')
+ * });
+ * ```
+ */
+declare function mardora(config?: MardoraConfig): Extension[];
+
+export { SyntaxPlugin as $, type MardoraTocLevel as A, type PluginConfig as B, type PluginContext as C, type DecorationContext as D, type ResolvedMardoraTocConfig as E, type SelectionToolbarAnchorRect as F, type SelectionToolbarBlockType as G, type SelectionToolbarBoundary as H, type InlineFormatInput as I, type SelectionToolbarButton as J, type SelectionToolbarFloatingSize as K, type LinkChangeInput as L, type MardoraAttachmentAccept as M, type SelectionToolbarLayout as N, type SelectionToolbarLayoutInput as O, type ParsedSelectionLink as P, type SelectionToolbarLinkState as Q, type ResolvedMardoraHeadingFoldConfig as R, type SelectionToolbarActionId as S, type SelectionToolbarListKind as T, type SelectionToolbarMenuCallbacks as U, type SelectionToolbarMenuState as V, type SelectionToolbarMessages as W, type SelectionToolbarPaletteItem as X, type SelectionToolbarPanel as Y, type SelectionToolbarPlacement as Z, type SelectionToolbarViewport as _, DecorationPlugin as a, type TextChange as a0, type TextCommandResult as a1, type TextSelection as a2, ThemeEnum as a3, type ThemeStyle as a4, type TocPanelState as a5, type TocStorageAdapter as a6, createMardoraIcon as a7, createTheme as a8, cursorInRange as a9, deepMerge as aa, defaultMardoraLocale as ab, fixSelector as ac, flattenThemeStyles as ad, getSelectionToolbarMessages as ae, hasMardoraIcon as af, mardora as ag, resolveMardoraLocale as ah, selectionOverlapsRange as ai, toggleMarkdownStyle as aj, type MardoraAttachmentKind as b, type MardoraAttachmentUploadContext as c, type MardoraAttachmentUploadResult as d, type MardoraAttachmentUploadSource as e, type MardoraAttachmentUploader as f, type MardoraAttachmentsConfig as g, type MardoraConfig as h, type MardoraFileLike as i, type MardoraHeadingFoldConfig as j, type MardoraHeadingFoldLevel as k, type MardoraHeadingFoldRange as l, type MardoraI18nConfig as m, type MardoraIconName as n, type MardoraLocale as o, type MardoraNode as p, MardoraPlugin as q, type MardoraSelectionToolbarConfig as r, type MardoraSlashCommand as s, type MardoraSlashCommandContext as t, type MardoraSlashCommandGroup as u, type MardoraSlashCommandsConfig as v, type MardoraSlashMessages as w, type MardoraSlashQuery as x, type MardoraTocConfig as y, type MardoraTocItem as z };