@sigx/lynx-markdown 0.4.7 → 0.4.9

package/dist/editor/convert/docToMd.js

@@ -0,0 +1,224 @@
+/**
+ * {@link RichDoc} → markdown — the serializer (inverse of `mdToDoc`).
+ *
+ * Segments the flat text by `blocks[]` (raw chunks verbatim, heading lines
+ * prefixed, remaining lines as paragraphs), then serializes inline spans per
+ * segment via elementary runs + a close/reopen delimiter stack (valid nesting
+ * from arbitrarily overlapping spans).
+ *
+ * Round-trip contract: `mdToDoc(docToMd(doc))` is structurally equal to a
+ * *normalized* `doc` — emphasis markers, hard breaks (→ paragraph breaks), and
+ * blank lines normalize; `raw` blocks round-trip byte-for-byte.
+ */
+import { computeRuns, markPriority } from './overlap.js';
+export function docToMd(doc, options) {
+    const parts = [];
+    const serializers = options?.serializers;
+    // Plugin-owned spans, prefiltered once for the whole doc — the per-run
+    // lookup searches only these (typically zero or a handful).
+    const pluginSpans = serializers ? doc.spans.filter((s) => serializers.has(s.type)) : [];
+    for (const seg of segmentize(doc)) {
+        if (seg.type === 'raw') {
+            parts.push(doc.text.slice(seg.start, seg.end));
+            continue;
+        }
+        const inline = serializeInline(doc, seg.start, seg.end, seg.type === 'paragraph', serializers, pluginSpans);
+        if (seg.type === 'heading') {
+            const level = Math.min(6, Math.max(1, seg.level ?? 1));
+            parts.push(`${'#'.repeat(level)} ${inline}`);
+        }
+        else if (inline !== '') {
+            parts.push(inline);
+        }
+        // Empty paragraph lines are visual spacing only — they normalize away.
+    }
+    return parts.join('\n\n');
+}
+/** Cover the text with block segments; uncovered regions split per line into paragraphs. */
+function segmentize(doc) {
+    const segments = [];
+    const text = doc.text;
+    const blocks = [...doc.blocks]
+        .map((b) => ({
+        ...b,
+        start: Math.max(0, Math.min(b.start, text.length)),
+        end: Math.max(0, Math.min(b.end, text.length)),
+    }))
+        .filter((b) => b.end >= b.start)
+        .sort((a, b) => a.start - b.start);
+    /**
+     * Split an uncovered region `[from, to)` into per-line paragraph segments.
+     * A `\n` ends the line before it; a region ending exactly on a separator
+     * `\n` emits no phantom trailing line.
+     */
+    const emitLines = (from, to) => {
+        let lineStart = from;
+        for (let i = from; i < to; i++) {
+            if (text[i] === '\n') {
+                segments.push({ start: lineStart, end: i, type: 'paragraph' });
+                lineStart = i + 1;
+            }
+        }
+        if (lineStart < to)
+            segments.push({ start: lineStart, end: to, type: 'paragraph' });
+    };
+    let cursor = 0;
+    for (const block of blocks) {
+        const start = Math.max(cursor, block.start);
+        if (start > cursor)
+            emitLines(cursor, start);
+        const end = Math.max(start, block.end);
+        // Block ranges include their trailing newline (paragraphRange
+        // semantics) — content excludes it.
+        const contentEnd = end > start && text[end - 1] === '\n' ? end - 1 : end;
+        if (block.type === 'heading') {
+            segments.push({ start, end: contentEnd, type: 'heading', level: block.level });
+        }
+        else if (block.type === 'raw') {
+            segments.push({ start, end: contentEnd, type: 'raw' });
+        }
+        else {
+            // Unknown/unstyled block types degrade to paragraphs (per line).
+            emitLines(start, contentEnd);
+        }
+        cursor = end;
+    }
+    if (cursor < text.length)
+        emitLines(cursor, text.length);
+    return segments;
+}
+/** Serialize one segment's text + spans into markdown inline syntax. */
+function serializeInline(doc, start, end, escapeLineStart, serializers, pluginSpans = []) {
+    const runs = computeRuns(doc.spans, start, end);
+    if (runs.length === 0) {
+        return escapeText(doc.text.slice(start, end), escapeLineStart);
+    }
+    // Extent-aware nesting (the ProseMirror-serializer trick): per run, order
+    // marks so the one that stays active the LONGEST sits outermost. A shorter
+    // mark is closed-and-reopened inside it, which avoids the unserializable
+    // adjacent-delimiter runs (`***`) that naive close/reopen produces.
+    const contEnd = [];
+    for (let i = runs.length - 1; i >= 0; i--) {
+        const map = new Map();
+        for (const mark of runs[i].active) {
+            const next = i + 1 < runs.length ? contEnd[i + 1].get(mark.key) : undefined;
+            map.set(mark.key, next !== undefined && runs[i + 1].start === runs[i].end ? next : runs[i].end);
+        }
+        contEnd[i] = map;
+    }
+    let out = '';
+    const open = [];
+    let first = true;
+    for (let i = 0; i < runs.length; i++) {
+        const run = runs[i];
+        // A plugin-owned mark serializes atomically: its serializer output
+        // replaces the covered text, and the mark never enters the
+        // close/reopen stack (other marks may still wrap it). Atomic emission
+        // only applies when exactly ONE plugin mark covers the run —
+        // overlapping plugin spans are ambiguous, so the run degrades to its
+        // plain text (content preserved, no plugin syntax emitted).
+        const pluginMarks = serializers ? run.active.filter((m) => serializers.has(m.type)) : [];
+        const pluginMark = pluginMarks.length === 1 ? pluginMarks[0] : undefined;
+        const active = pluginMarks.length ? run.active.filter((m) => !serializers.has(m.type)) : run.active;
+        const desired = [...active].sort((a, b) => {
+            const ea = contEnd[i].get(a.key) ?? run.end;
+            const eb = contEnd[i].get(b.key) ?? run.end;
+            return eb - ea || markPriority(a) - markPriority(b);
+        });
+        // Keep the common open-stack prefix; close the rest (innermost first).
+        let keep = 0;
+        while (keep < open.length && keep < desired.length && open[keep].key === desired[keep].key)
+            keep++;
+        for (let j = open.length - 1; j >= keep; j--)
+            out += delimiter(open[j], doc, 'close');
+        open.length = keep;
+        for (let j = keep; j < desired.length; j++) {
+            out += delimiter(desired[j], doc, 'open');
+            open.push(desired[j]);
+        }
+        if (pluginMark) {
+            // Emit the serialized form once — on the span's first run within
+            // this segment — and suppress the covered text everywhere.
+            const span = pluginSpans.find((s) => s.type === pluginMark.type && s.start <= run.start && s.end >= run.end);
+            if (span && run.start === Math.max(span.start, start)) {
+                out += serializers.get(pluginMark.type)(span, doc.text.slice(span.start, span.end));
+            }
+            first = false;
+            continue;
+        }
+        const slice = doc.text.slice(run.start, run.end);
+        out += open.some((m) => m.type === 'code')
+            ? slice
+            : escapeText(slice, escapeLineStart && first && open.length === 0);
+        first = false;
+    }
+    for (let j = open.length - 1; j >= 0; j--)
+        out += delimiter(open[j], doc, 'close');
+    return out;
+}
+function delimiter(mark, doc, side) {
+    switch (mark.type) {
+        case 'bold':
+            return '**';
+        case 'italic':
+            // `_` (not `*`) so a bold/italic split never emits an ambiguous
+            // `***` delimiter run (`**a*b***c*` parses wrong; `**a_b_**_c_`
+            // can't collide). Trade-off: mid-word italic won't re-parse
+            // (intraword `_` rule) — documented normalization.
+            return '_';
+        case 'strike':
+            return '~~';
+        case 'code': {
+            // Widen the fence beyond any backtick run in the content.
+            const fence = '`'.repeat(maxBacktickRun(doc.text) + 1);
+            return fence.length > 1 ? fence : '`';
+        }
+        case 'link':
+            return side === 'open' ? '[' : `](${escapeLinkDest(String(mark.attrs?.href ?? ''))})`;
+        case 'mention':
+            // P3 — until the mention plugin lands, serialize as plain label.
+            return '';
+        default:
+            return '';
+    }
+}
+/**
+ * Escape a link destination so it re-parses to the same href (mirrors
+ * `scanLinkDest`'s two accepted forms):
+ *
+ * - bare form: backslash-escape `\`, `(`, `)`, `<` (a leading `<` would
+ *   otherwise flip the parser into the angle branch) — valid as long as
+ *   the destination has no whitespace;
+ * - whitespace anywhere → angle form `<…>`, whose only terminators are `>`
+ *   and newline; those get percent-encoded (they're invalid raw in URLs
+ *   anyway, so this is normalization, not loss).
+ */
+function escapeLinkDest(href) {
+    if (/\s/.test(href)) {
+        return `<${href.replace(/>/g, '%3E').replace(/\n/g, '%0A')}>`;
+    }
+    return href.replace(/[\\()<]/g, (c) => `\\${c}`);
+}
+function maxBacktickRun(text) {
+    let max = 0;
+    let run = 0;
+    for (const ch of text) {
+        run = ch === '`' ? run + 1 : 0;
+        if (run > max)
+            max = run;
+    }
+    return max;
+}
+/** Escape markdown-significant characters in literal text. */
+function escapeText(text, atLineStart) {
+    let out = text.replace(/([\\`*_~[\]])/g, '\\$1');
+    if (atLineStart) {
+        // Constructs that only bind at the start of a line.
+        out = out
+            .replace(/^(#{1,6})(\s)/, '\\$1$2')
+            .replace(/^>/, '\\>')
+            .replace(/^([-+])(\s)/, '\\$1$2')
+            .replace(/^(\d+)([.)])(\s)/, '$1\\$2$3');
+    }
+    return out;
+}

package/dist/editor/convert/mdToDoc.d.ts

@@ -0,0 +1,32 @@
+/**
+ * markdown → {@link RichDoc} — flatten the parsed AST into the rich-text
+ * element's flat text+spans+blocks model.
+ *
+ * v1 models paragraphs, headings, and the inline set
+ * (bold/italic/strike/code/link). Everything else — lists, blockquotes, code
+ * blocks, tables, thematic breaks, and any paragraph containing an
+ * unrepresentable inline (images) — becomes a **`raw` block**: the original
+ * markdown source verbatim, edited as source and serialized back
+ * byte-for-byte. That's the lossless escape hatch that makes the round trip
+ * safe long before every node type is WYSIWYG-editable.
+ *
+ * Line convention (chat-style): every `\n` in `doc.text` is a paragraph
+ * boundary. Markdown hard breaks split into separate doc lines; `docToMd`
+ * serializes doc lines back as blank-line-separated paragraphs (hard breaks
+ * normalize to paragraph breaks — documented).
+ */
+import type { InlineSpan, RichDoc } from '@sigx/lynx-richtext';
+import type { ParserInlineExtension } from '../../parser/extensions.js';
+import type { InlineExtension } from '../../ast.js';
+/** AST extension node → editor span (a plugin's `docMapping.toSpan`). Must be pure. */
+export type ExtensionSpanMapper = (node: InlineExtension) => {
+    text: string;
+    span: Omit<InlineSpan, 'start' | 'end'>;
+} | null;
+export interface MdToDocOptions {
+    /** Inline extensions to parse with (plugin `inline.syntax`). */
+    extensions?: readonly ParserInlineExtension[];
+    /** Span mappers keyed by extension name (plugin `docMapping.toSpan`). */
+    spanMappers?: Record<string, ExtensionSpanMapper>;
+}
+export declare function mdToDoc(markdown: string, v?: number, options?: MdToDocOptions): RichDoc;

package/dist/editor/convert/mdToDoc.js

@@ -0,0 +1,221 @@
+/**
+ * markdown → {@link RichDoc} — flatten the parsed AST into the rich-text
+ * element's flat text+spans+blocks model.
+ *
+ * v1 models paragraphs, headings, and the inline set
+ * (bold/italic/strike/code/link). Everything else — lists, blockquotes, code
+ * blocks, tables, thematic breaks, and any paragraph containing an
+ * unrepresentable inline (images) — becomes a **`raw` block**: the original
+ * markdown source verbatim, edited as source and serialized back
+ * byte-for-byte. That's the lossless escape hatch that makes the round trip
+ * safe long before every node type is WYSIWYG-editable.
+ *
+ * Line convention (chat-style): every `\n` in `doc.text` is a paragraph
+ * boundary. Markdown hard breaks split into separate doc lines; `docToMd`
+ * serializes doc lines back as blank-line-separated paragraphs (hard breaks
+ * normalize to paragraph breaks — documented).
+ */
+import { parseBlocks } from '../../parser/blocks.js';
+export function mdToDoc(markdown, v = 0, options) {
+    const ast = parseBlocks(markdown ?? '', undefined, options?.extensions);
+    const mappers = options?.spanMappers;
+    let text = '';
+    const spans = [];
+    const blocks = [];
+    /** Append one doc line (or multi-line raw chunk) plus its block attr. */
+    const push = (chunk, attr) => {
+        // Raw chunks may carry trailing blank lines consumed by the block
+        // parser (loose lists) — the inter-block separator is reconstructed
+        // by the serializer's join, so strip them here for stable round trips.
+        if (attr?.type === 'raw')
+            chunk = chunk.replace(/\n+$/, '');
+        const start = text.length;
+        text += chunk;
+        if (attr) {
+            // Range includes the trailing newline once it exists — matching how
+            // native paragraph ranges read back (paragraphRange semantics).
+            blocks.push({ start, end: text.length + 1, ...attr });
+        }
+        text += '\n';
+    };
+    for (const block of ast) {
+        switch (block.type) {
+            case 'paragraph': {
+                if (!inlineRepresentable(block.children, mappers)) {
+                    push(block.raw, { type: 'raw' });
+                    break;
+                }
+                for (const line of splitOnBreaks(block.children)) {
+                    const flat = flattenInline(line, text.length, mappers);
+                    spans.push(...flat.spans);
+                    push(flat.text);
+                }
+                break;
+            }
+            case 'heading': {
+                if (!inlineRepresentable(block.children, mappers)) {
+                    push(block.raw, { type: 'raw' });
+                    break;
+                }
+                const flat = flattenInline(block.children, text.length, mappers);
+                spans.push(...flat.spans);
+                push(flat.text, { type: 'heading', level: block.level });
+                break;
+            }
+            default:
+                push(block.raw, { type: 'raw' });
+        }
+    }
+    // Drop the final separator newline; clamp any block range that reached
+    // past it (the "+1 for trailing newline" of the last block).
+    if (text.endsWith('\n'))
+        text = text.slice(0, -1);
+    for (const b of blocks) {
+        if (b.end > text.length)
+            b.end = text.length;
+    }
+    return { text, spans, blocks, v };
+}
+/** Inline node types the editor can model in-field. */
+function inlineRepresentable(nodes, mappers) {
+    for (const node of nodes) {
+        switch (node.type) {
+            case 'text':
+            case 'br':
+            case 'codeSpan':
+            case 'autolink':
+                break;
+            case 'strong':
+            case 'em':
+            case 'del':
+                if (!inlineRepresentable(node.children, mappers))
+                    return false;
+                break;
+            case 'link':
+                if (!inlineRepresentable(node.children, mappers))
+                    return false;
+                break;
+            case 'extension':
+                // Representable only when a plugin maps it to an editor span
+                // (toSpan is pure, so probing here and mapping later agree).
+                // A throwing mapper means "not representable" — the block
+                // degrades to raw instead of crashing the conversion.
+                if (!tryMap(mappers, node))
+                    return false;
+                break;
+            default:
+                return false; // image, unmapped extension nodes
+        }
+    }
+    return true;
+}
+/** Run a plugin mapper defensively: a throwing mapper counts as no mapping. */
+function tryMap(mappers, node) {
+    try {
+        return mappers?.[node.name]?.(node) ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Split a paragraph's inline children into visual lines at top-level hard breaks. */
+function splitOnBreaks(nodes) {
+    const lines = [];
+    let current = [];
+    for (const node of nodes) {
+        if (node.type === 'br') {
+            lines.push(current);
+            current = [];
+        }
+        else {
+            current.push(node);
+        }
+    }
+    lines.push(current);
+    return lines;
+}
+/** Depth-first flatten of an inline tree into text + overlapping spans. */
+function flattenInline(nodes, base, mappers) {
+    let text = '';
+    const spans = [];
+    const walk = (list) => {
+        for (const node of list) {
+            switch (node.type) {
+                case 'text':
+                    text += node.value;
+                    break;
+                case 'br':
+                    // Nested hard break (inside emphasis) — degrade to a space.
+                    text += ' ';
+                    break;
+                case 'codeSpan': {
+                    const start = base + text.length;
+                    text += node.value;
+                    spans.push({ start, end: base + text.length, type: 'code' });
+                    break;
+                }
+                case 'strong': {
+                    const start = base + text.length;
+                    walk(node.children);
+                    spans.push({ start, end: base + text.length, type: 'bold' });
+                    break;
+                }
+                case 'em': {
+                    const start = base + text.length;
+                    walk(node.children);
+                    spans.push({ start, end: base + text.length, type: 'italic' });
+                    break;
+                }
+                case 'del': {
+                    const start = base + text.length;
+                    walk(node.children);
+                    spans.push({ start, end: base + text.length, type: 'strike' });
+                    break;
+                }
+                case 'link': {
+                    const start = base + text.length;
+                    walk(node.children);
+                    spans.push({
+                        start,
+                        end: base + text.length,
+                        type: 'link',
+                        attrs: { href: node.href },
+                    });
+                    break;
+                }
+                case 'autolink': {
+                    const start = base + text.length;
+                    text += node.value;
+                    spans.push({
+                        start,
+                        end: base + text.length,
+                        type: 'link',
+                        attrs: { href: node.href },
+                    });
+                    break;
+                }
+                case 'extension': {
+                    const mapped = tryMap(mappers, node);
+                    if (!mapped) {
+                        // Defense in depth: if the mapper disagrees with the
+                        // earlier representability probe (impure/buggy), keep
+                        // the source text rather than silently dropping it.
+                        text += node.raw;
+                        break;
+                    }
+                    const start = base + text.length;
+                    text += mapped.text;
+                    // Plugin fields first — the converter always controls the
+                    // final range, even if a mapper sneaks in start/end.
+                    spans.push({ ...mapped.span, start, end: base + text.length });
+                    break;
+                }
+                default:
+                    break; // unreachable — filtered by inlineRepresentable
+            }
+        }
+    };
+    walk(nodes);
+    // Zero-length spans (empty emphasis) carry no information — drop them.
+    return { text, spans: spans.filter((s) => s.end > s.start) };
+}

package/dist/editor/convert/overlap.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Elementary-run computation for inline serialization.
+ *
+ * The doc model permits arbitrarily overlapping spans; markdown needs properly
+ * nested delimiters. Step one of the serializer is to slice a text range into
+ * **elementary runs** — maximal intervals over which the set of active marks
+ * is constant. The emitter (docToMd) then walks the runs with a close/reopen
+ * stack, which is guaranteed to produce valid nesting.
+ */
+import type { InlineSpan, InlineSpanType } from '@sigx/lynx-richtext';
+export interface ActiveMark {
+    type: InlineSpanType;
+    /** Identity key — distinguishes links by href so adjacent different links don't merge. */
+    key: string;
+    attrs?: Record<string, string>;
+}
+export interface Run {
+    start: number;
+    end: number;
+    /** Marks active over the whole run. */
+    active: ActiveMark[];
+}
+export declare function markPriority(mark: ActiveMark): number;
+/**
+ * Slice `[start, end)` into elementary runs for the given spans.
+ *
+ * `code` is terminal: within a code span every other mark except an enclosing
+ * `link` is suppressed (markdown cannot style inside code spans, but
+ * `[`code`](href)` is valid).
+ */
+export declare function computeRuns(spans: InlineSpan[], start: number, end: number): Run[];

package/dist/editor/convert/overlap.js

@@ -0,0 +1,70 @@
+/**
+ * Elementary-run computation for inline serialization.
+ *
+ * The doc model permits arbitrarily overlapping spans; markdown needs properly
+ * nested delimiters. Step one of the serializer is to slice a text range into
+ * **elementary runs** — maximal intervals over which the set of active marks
+ * is constant. The emitter (docToMd) then walks the runs with a close/reopen
+ * stack, which is guaranteed to produce valid nesting.
+ */
+/** Outer-to-inner nesting priority (lower index opens first / sits outermost). */
+const PRIORITY = { link: 0, code: 1, bold: 2, italic: 3, strike: 4 };
+export function markPriority(mark) {
+    return PRIORITY[mark.type] ?? 99;
+}
+/**
+ * Slice `[start, end)` into elementary runs for the given spans.
+ *
+ * `code` is terminal: within a code span every other mark except an enclosing
+ * `link` is suppressed (markdown cannot style inside code spans, but
+ * `[`code`](href)` is valid).
+ */
+export function computeRuns(spans, start, end) {
+    if (end <= start)
+        return [];
+    const relevant = spans
+        .filter((s) => s.end > start && s.start < end && s.end > s.start)
+        .map((s) => ({
+        start: Math.max(s.start, start),
+        end: Math.min(s.end, end),
+        mark: toMark(s),
+    }));
+    const boundaries = new Set([start, end]);
+    for (const s of relevant) {
+        boundaries.add(s.start);
+        boundaries.add(s.end);
+    }
+    const points = [...boundaries].sort((a, b) => a - b);
+    const runs = [];
+    for (let i = 0; i < points.length - 1; i++) {
+        const a = points[i];
+        const b = points[i + 1];
+        if (b <= a)
+            continue;
+        let active = relevant
+            .filter((s) => s.start <= a && s.end >= b)
+            .map((s) => s.mark);
+        active = dedupe(active);
+        if (active.some((m) => m.type === 'code')) {
+            active = active.filter((m) => m.type === 'code' || m.type === 'link');
+        }
+        active.sort((x, y) => markPriority(x) - markPriority(y) || x.key.localeCompare(y.key));
+        runs.push({ start: a, end: b, active });
+    }
+    return runs;
+}
+function toMark(span) {
+    const key = span.type === 'link' ? `link:${span.attrs?.href ?? ''}` : span.type;
+    return { type: span.type, key, ...(span.attrs ? { attrs: span.attrs } : {}) };
+}
+function dedupe(marks) {
+    const seen = new Set();
+    const out = [];
+    for (const m of marks) {
+        if (!seen.has(m.key)) {
+            seen.add(m.key);
+            out.push(m);
+        }
+    }
+    return out;
+}