@domternal/extension-markdown 0.12.0

package/dist/index.d.ts

@@ -0,0 +1,201 @@
+import { CommandSpec, SetContentOptions, Extension, Editor } from '@domternal/core';
+import { Node, Schema, Mark, NodeType, MarkType, Attrs } from '@domternal/pm/model';
+import { Plugin, PluginKey } from '@domternal/pm/state';
+
+interface MarkdownParser {
+    /** Parse a Markdown string into a document node of the schema. */
+    parse(markdown: string): Node;
+}
+declare function createMarkdownParser(schema: Schema): MarkdownParser;
+/** One-shot convenience wrapper around {@link createMarkdownParser}. */
+declare function parseMarkdown(markdown: string, schema: Schema): Node;
+
+type MarkdownWarningCode = 'unsupported-node' | 'unsupported-mark' | 'lossy-attribute' | 'lossy-structure';
+/** A non-fatal fidelity loss that happened during conversion. */
+interface MarkdownWarning {
+    code: MarkdownWarningCode;
+    message: string;
+    /** The node or mark type the warning originates from, when known. */
+    nodeType?: string;
+}
+/** The serialized document plus everything that did not survive at full fidelity. */
+interface SerializeMarkdownResult {
+    markdown: string;
+    warnings: MarkdownWarning[];
+}
+
+/**
+ * Markdown serializer state machine. Same output semantics as
+ * prosemirror-markdown's serializer (delimiter stacking, tight lists, mark
+ * mixing, enclosing-whitespace expelling) but built on `@domternal/pm` so the
+ * package never pulls in a second prosemirror-model instance.
+ */
+
+type MarkdownNodeSerializer = (state: MarkdownSerializerState, node: Node, parent: Node, index: number) => void;
+type MarkDelimiter = string | ((state: MarkdownSerializerState, mark: Mark, parent: Node, index: number) => string);
+interface MarkdownMarkSpec {
+    open: MarkDelimiter;
+    close: MarkDelimiter;
+    /** Marks that can be reordered against other mixable marks to minimize delimiters. */
+    mixable?: boolean;
+    /** Move leading/trailing whitespace outside the delimiters (`**a ** b` is invalid emphasis). */
+    expelEnclosingWhitespace?: boolean;
+    /** Set false when the mark content is raw (inline code). */
+    escape?: boolean;
+}
+interface MarkdownSerializerSpecs {
+    nodes: Record<string, MarkdownNodeSerializer>;
+    marks: Record<string, MarkdownMarkSpec>;
+}
+interface MarkdownSerializerOptions {
+    /**
+     * Render lists without blank lines between items.
+     * @default true
+     */
+    tightLists?: boolean;
+}
+/** Longest backtick run inside inline code decides the fence length around it. */
+declare function backticksFor(node: Node, side: -1 | 1): string;
+declare class MarkdownSerializerState {
+    readonly nodes: Record<string, MarkdownNodeSerializer>;
+    readonly marks: Record<string, MarkdownMarkSpec>;
+    readonly warnings: MarkdownWarning[];
+    readonly tightLists: boolean;
+    private delim;
+    private out;
+    private closed;
+    private inTightList;
+    private atBlockStart;
+    constructor(specs: MarkdownSerializerSpecs, options?: MarkdownSerializerOptions);
+    warn(code: MarkdownWarningCode, message: string, nodeType?: string): void;
+    private flushClose;
+    /**
+     * Render a block wrapped in a line prefix: `firstDelim` on its first line,
+     * `delim` on every following line (blockquote `> `, list item indent).
+     */
+    wrapBlock(delim: string, firstDelim: string | null, node: Node, f: () => void): void;
+    atBlank(): boolean;
+    ensureNewLine(): void;
+    write(content?: string): void;
+    /** Close the block: the next write emits the separating blank line. */
+    closeBlock(node: Node): void;
+    text(text: string, escape?: boolean): void;
+    render(node: Node, parent: Node, index: number): void;
+    renderContent(parent: Node): void;
+    renderInline(parent: Node, fromBlockStart?: boolean): void;
+    renderList(node: Node, delim: string, firstDelim: (index: number) => string): void;
+    /**
+     * Escape Markdown syntax in plain text. Beyond the CommonMark set this
+     * also escapes `|` (table cells), `$` (this package's own math rules), and
+     * `<` plus entity-like `&` (raw-HTML/autolink/entity ambiguity on external
+     * renderers): all render as the literal character everywhere.
+     */
+    esc(str: string, startOfLine?: boolean): string;
+    markString(mark: Mark, open: boolean, parent: Node, index: number): string;
+    /** The accumulated output; call once after rendering the document. */
+    finish(): string;
+}
+
+interface MarkdownSerializerSpecOverrides {
+    /** Extra or replacement node serializers, merged over the defaults. */
+    nodes?: Record<string, MarkdownNodeSerializer>;
+    /** Extra or replacement mark specs, merged over the defaults. */
+    marks?: Record<string, MarkdownMarkSpec>;
+}
+interface MarkdownSerializer {
+    /** Serialize a document (or any block node) to Markdown. */
+    serialize(node: Node): SerializeMarkdownResult;
+}
+declare function createMarkdownSerializer(specs?: MarkdownSerializerSpecOverrides, options?: MarkdownSerializerOptions): MarkdownSerializer;
+interface SerializeMarkdownOptions extends MarkdownSerializerOptions {
+    specs?: MarkdownSerializerSpecOverrides;
+}
+/** One-shot convenience wrapper around {@link createMarkdownSerializer}. */
+declare function serializeMarkdown(node: Node, options?: SerializeMarkdownOptions): SerializeMarkdownResult;
+
+/**
+ * Markdown extension: bidirectional Markdown for the editor. Parsing and
+ * serialization are also available headlessly through createMarkdownParser
+ * and createMarkdownSerializer; the extension wires them to commands, paste,
+ * and a shared storage other packages can reuse.
+ */
+
+declare module '@domternal/core' {
+    interface RawCommands {
+        insertMarkdown: CommandSpec<[markdown: string]>;
+        setMarkdownContent: CommandSpec<[markdown: string, options?: SetContentOptions]>;
+    }
+}
+interface MarkdownOptions {
+    /**
+     * Convert Markdown-looking plain-text pastes into rich content. Pastes
+     * that carry an HTML flavor, plain prose, and pastes into code blocks are
+     * never touched.
+     * @default true
+     */
+    paste: boolean;
+    /**
+     * Serialize lists without blank lines between items.
+     * @default true
+     */
+    tightLists: boolean;
+    /**
+     * Extra or replacement Markdown mappings for custom nodes and marks,
+     * merged over the built-in ones.
+     * @default null
+     */
+    specs: MarkdownSerializerSpecOverrides | null;
+}
+interface MarkdownStorage {
+    /** Shared parser instance; built on editor create, reusable by other packages. */
+    parser: MarkdownParser | null;
+    /** Shared serializer instance; built on editor create, reusable by other packages. */
+    serializer: MarkdownSerializer | null;
+}
+/** Serialize the editor's current document to Markdown. */
+declare function getMarkdown(editor: Editor): SerializeMarkdownResult;
+declare const Markdown: Extension<MarkdownOptions, MarkdownStorage>;
+
+/**
+ * Serialize the document and hand it to the browser as a .md download.
+ * Returns the serialization result so callers can surface the warnings.
+ */
+declare function downloadMarkdown(editor: Editor, fileName?: string): SerializeMarkdownResult;
+
+declare const markdownPastePluginKey: PluginKey<any>;
+declare function looksLikeMarkdown(text: string): boolean;
+declare function markdownPastePlugin(getParser: () => MarkdownParser): Plugin;
+
+/**
+ * Markdown parse state: token stream in, ProseMirror nodes out. Same shape as
+ * prosemirror-markdown's parse state, built on `@domternal/pm` types.
+ */
+
+declare class MarkdownParseState {
+    readonly schema: Schema;
+    private readonly stack;
+    private marks;
+    constructor(schema: Schema);
+    private top;
+    /** The node type currently being built (for split decisions). */
+    topType(): NodeType;
+    push(node: Node): void;
+    addText(text: string): void;
+    openMark(mark: Mark): void;
+    closeMark(type: MarkType): void;
+    addNode(type: NodeType, attrs: Attrs | null, content?: Node[]): Node | null;
+    openNode(type: NodeType, attrs?: Attrs | null, discardWhenEmpty?: boolean): void;
+    closeNode(): Node | null;
+    /**
+     * Close the innermost frame and reopen the same type after inserting
+     * `node` as a sibling: how a block-level image escapes its paragraph.
+     */
+    splitAround(node: Node): void;
+    /** Build the final document; called once after all tokens are consumed. */
+    finish(): Node;
+}
+
+declare const defaultNodeSerializers: Record<string, MarkdownNodeSerializer>;
+declare const defaultMarkSpecs: Record<string, MarkdownMarkSpec>;
+
+export { Markdown, type MarkdownMarkSpec, type MarkdownNodeSerializer, type MarkdownOptions, MarkdownParseState, type MarkdownParser, type MarkdownSerializer, type MarkdownSerializerOptions, type MarkdownSerializerSpecOverrides, type MarkdownSerializerSpecs, MarkdownSerializerState, type MarkdownStorage, type MarkdownWarning, type MarkdownWarningCode, type SerializeMarkdownOptions, type SerializeMarkdownResult, backticksFor, createMarkdownParser, createMarkdownSerializer, Markdown as default, defaultMarkSpecs, defaultNodeSerializers, downloadMarkdown, getMarkdown, looksLikeMarkdown, markdownPastePlugin, markdownPastePluginKey, parseMarkdown, serializeMarkdown };