@dogsbay/editor 0.0.0-stage → 0.2.0-beta.174

package/README.md

@@ -1,3 +1,79 @@
-# Temporary Holding Version
+# @dogsbay/editor
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A TipTap/ProseMirror editor for Dogsbay Markdown: the schema, a lossless bridge between Dogsbay's
+block tree (`TreeNode[]`, from `@dogsbay/format-dogsbay-md`) and ProseMirror documents, and the
+editor on one block of a page. MIT.
+
+## Edit one block of a page
+
+For a host that shows the real rendered page and edits a block in place. The host gives the
+block's source lines (from the page's `data-line` / `data-end-line`), and splices what comes back
+over those lines. Nothing else in the file is touched, so a commit holds only the edited block.
+
+```ts
+// Where the Markdown parser already is (the host's own page):
+import { openBlock } from "@dogsbay/editor/block";
+
+const block = openBlock(lines, { style: project.style, page });   // style: dogsbay.config.yml's `style:`
+if (!block.editable) openAsMarkdown(block.reason);
+block.doc;       // the block as a ProseMirror document (JSON)
+block.verbatim;  // parts the editor shows verbatim (unmodelled blocks, raw directives)
+block.exact;     // false: saving an edit will also restyle this block's untouched lines
+
+// In the page the block is shown in (TipTap, no Markdown parser):
+import { mountBlock } from "@dogsbay/editor/block-view";
+
+const view = mountBlock(element, block.doc, { onUpdate: ({ changed }) => markDirty(changed) });
+// …the host adds its toolbar, keys and paste…
+const { doc } = view.read();
+view.destroy();
+
+// Back where the parser is:
+const { text, changed } = block.close(doc);   // splice `text` over the block's lines
+```
+
+- **No change, no bytes changed.** A block opened and closed without a change (or with every change
+  undone) gives back its lines exactly; the edited tree is compared with the opened one rather than
+  re-serialized. Checked on every block of the Dogsbay Markdown feature examples, through a real
+  editor.
+- **A changed block** is written by format-dogsbay-md's serializer in the host's style, with the
+  block's indentation, the blank lines around it as written, and its line ends. An edit that
+  writes the same text (an empty paragraph added and dropped) is no change either.
+- **`editable` is false**, with a `reason`, when a block cannot be taken apart safely: lines not
+  indented alike (a lazy continuation line, tabs on one line and spaces on another), a footnote
+  reference (its definition is elsewhere on the page), or a reference link when the host did not
+  pass `page`. With `page`, reference links are resolved from the page's definitions and an edited
+  block writes them as inline links.
+- **`exact` is false** when the serializer would not write the block as it is written now, so an
+  edit restyles its other lines too. The common case: the parser reads a soft line break as a
+  space, so an edited paragraph wrapped over several lines comes back on one line.
+- **Templating, includes and conditions** are parsed in preserve mode: they stay as written, as
+  first-class nodes or verbatim parts. A host may open a block with `verbatim > 0` as Markdown
+  instead.
+- The two entries are split so that each side loads only what it needs; the documents pass
+  between them as JSON (`postMessage` into a sandboxed frame works). Gzipped, `./block-view` is
+  about 136 KB (TipTap and ProseMirror) and `./block` about 163 KB, nearly all of it the
+  format-dogsbay-md parser and serializer a host already has. Neither imports the change-review
+  view or `@dogsbay/tree-diff`.
+
+## The whole document
+
+```ts
+import { extensions, treeToPmDoc, pmDocToTree } from "@dogsbay/editor";
+import { dogsbayMdToTree } from "@dogsbay/format-dogsbay-md/browser";
+
+const doc = treeToPmDoc(dogsbayMdToTree(markdown, { directives: "preserve" }).tree);
+// new Editor({ extensions, content: doc }) … pmDocToTree(editor.getJSON())
+```
+
+The bridge is total over the schema, and never drops what it cannot model: tree content without a
+first-class editor node rides a verbatim atom, and props the editor does not edit ride a declared
+attribute. The main entry also has the change-review marks (`diffTreeToPmDoc`, over
+`@dogsbay/tree-diff`) and the directive preview helpers (`evaluateTest`, `validateDirectiveField`).
+
+The package has no view layer of its own: bring `@tiptap/react` or plain `@tiptap/core`.
+`@tiptap/core`, `@tiptap/pm` and `@tiptap/starter-kit` are peer dependencies, so the host and this
+package share one copy of ProseMirror. ESM only.
+
+What Markdown cannot hold, the bridge does not carry back: bold on inline code, a link's `target`
+or `rel`, a table column's width. An edit that only changes these is no change.

package/dist/block-view.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `@dogsbay/editor/block-view`: the editor on one block's document (from `./block`'s `openBlock`),
+ * for the page the block is shown in. TipTap and the schema, no Markdown parser: the host opens
+ * and closes the block's text with `./block` where its parser already is, and passes the document
+ * here and back as JSON.
+ */
+import { Editor } from "@tiptap/core";
+import { type PMNode } from "./bridge.js";
+export interface MountedBlock {
+    /** The TipTap editor; the host adds its own toolbar and keys. */
+    editor: Editor;
+    /** The document now, and whether it differs from the one mounted (an undone edit does not). */
+    read(): {
+        doc: PMNode;
+        changed: boolean;
+    };
+    destroy(): void;
+}
+/** Mount the editor on `element` for a block's document (`openBlock(text).doc`). */
+export declare function mountBlock(element: HTMLElement, doc: PMNode, options?: {
+    onUpdate?: (block: {
+        doc: PMNode;
+        changed: boolean;
+    }) => void;
+}): MountedBlock;

package/dist/block-view.js

@@ -0,0 +1,28 @@
+/**
+ * `@dogsbay/editor/block-view`: the editor on one block's document (from `./block`'s `openBlock`),
+ * for the page the block is shown in. TipTap and the schema, no Markdown parser: the host opens
+ * and closes the block's text with `./block` where its parser already is, and passes the document
+ * here and back as JSON.
+ */
+import { Editor } from "@tiptap/core";
+import { extensions } from "./schema.js";
+import { pmDocToTree } from "./bridge.js";
+/** JSON with sorted keys, so two readings of one tree compare equal. */
+const stable = (value) => JSON.stringify(value, (_key, v) => v && typeof v === "object" && !Array.isArray(v)
+    ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, v[k]]))
+    : v);
+/** Mount the editor on `element` for a block's document (`openBlock(text).doc`). */
+export function mountBlock(element, doc, options = {}) {
+    const editor = new Editor({ element, extensions, content: doc });
+    // The editor's own reading of the document (default attributes filled in) is what "unchanged" means
+    const opened = stable(pmDocToTree(editor.getJSON()));
+    const read = () => {
+        const now = editor.getJSON();
+        return { doc: now, changed: stable(pmDocToTree(now)) !== opened };
+    };
+    if (options.onUpdate) {
+        const onUpdate = options.onUpdate;
+        editor.on("update", () => onUpdate(read()));
+    }
+    return { editor, read, destroy: () => editor.destroy() };
+}

package/dist/block.d.ts

@@ -0,0 +1,69 @@
+/**
+ * `@dogsbay/editor/block`: the editor on ONE block of a page, for a host that shows the real
+ * rendered page and edits a block in place (the playground's preview).
+ *
+ * The host gives the block's source lines (a `data-line`–`data-end-line` range of the page), the
+ * editor works on them, and the host splices what comes back over those lines. Nothing else in the
+ * file is read or written, so git sees only the block that was edited.
+ *
+ * Opened and closed with no change, a block gives back its lines byte for byte: the edited tree is
+ * compared with the opened one, and an equal tree returns the original text, not a re-serialization
+ * (undoing every change counts as no change). A changed block is written by format-dogsbay-md's
+ * serializer in the host's style, re-indented and with the original line ends; `exact` says
+ * beforehand whether that serializer gives back this block as written (when not, saving an edit
+ * also restyles the block's untouched lines). One such case is common: the parser reads a soft
+ * line break as a space, so an edited paragraph that was wrapped over several lines comes back
+ * on one line.
+ *
+ * Some blocks cannot be edited this way, and `editable` is false with the reason: indentation that
+ * does not start every line the same (a lazy continuation line, tabs on one line and spaces on the
+ * next — taking it apart would turn the block into code), a footnote reference (its definition is
+ * elsewhere on the page), or a block the parser makes nothing of. Reference links are resolved with
+ * the page's definitions when the host passes the page (`page`), and written back as inline links.
+ *
+ * Directives are parsed in preserve mode: templating, includes and conditions stay first-class
+ * nodes or ride verbatim atoms; `verbatim` counts the atoms, which a host may prefer to open as
+ * Markdown instead.
+ *
+ * Two entries, so each side loads only what it needs: this one (`openBlock`: text in, document
+ * out, document in, text back) needs the Markdown parser and no DOM, and runs where the host's
+ * source editor already has the parser; `./block-view` (`mountBlock`) is the editor on that
+ * document, with TipTap and no parser, for the page the block is shown in (the host passes the
+ * document between them as JSON). Neither imports the change-review view (`diff.ts`,
+ * `@dogsbay/tree-diff`).
+ */
+import { type MarkdownStyle, type SerializeOptions } from "@dogsbay/format-dogsbay-md/browser";
+import { type PMNode } from "./bridge.js";
+export interface BlockOptions {
+    /** The project's `style:` (dogsbay.config.yml), used when a changed block is written. */
+    style?: MarkdownStyle;
+    /** Other serializer options (callout form, nested indentation). */
+    serialize?: Omit<SerializeOptions, keyof MarkdownStyle>;
+    /**
+     * The whole page, for its reference-link definitions (`[name]: url`): without them a block's
+     * `[text][name]` reads as plain text, and an edit would write it back escaped. Without `page`, a
+     * block using a reference link is not editable.
+     */
+    page?: string;
+}
+export interface ClosedBlock {
+    /** The block's new lines; the original text, byte for byte, when nothing changed. */
+    text: string;
+    /** False when the text is the original's, byte for byte (an edit undone, or one that writes the same). */
+    changed: boolean;
+}
+export interface OpenedBlock {
+    /** The block as a ProseMirror document (JSON) for `@dogsbay/editor`'s schema. */
+    doc: PMNode;
+    /** Whether the block can be edited here; when false, open it as Markdown (`reason` says why). */
+    editable: boolean;
+    reason?: string;
+    /** Nodes the editor shows verbatim (unmodelled blocks, raw directives). */
+    verbatim: number;
+    /** Whether the serializer writes this block exactly as it is written now. */
+    exact: boolean;
+    /** The block's text for an edited document (the opened `doc` when none is given). */
+    close(doc?: PMNode): ClosedBlock;
+}
+/** Open a block's source lines for editing (no DOM: the document, and how to write it back). */
+export declare function openBlock(text: string, options?: BlockOptions): OpenedBlock;

package/dist/block.js

@@ -0,0 +1,114 @@
+/**
+ * `@dogsbay/editor/block`: the editor on ONE block of a page, for a host that shows the real
+ * rendered page and edits a block in place (the playground's preview).
+ *
+ * The host gives the block's source lines (a `data-line`–`data-end-line` range of the page), the
+ * editor works on them, and the host splices what comes back over those lines. Nothing else in the
+ * file is read or written, so git sees only the block that was edited.
+ *
+ * Opened and closed with no change, a block gives back its lines byte for byte: the edited tree is
+ * compared with the opened one, and an equal tree returns the original text, not a re-serialization
+ * (undoing every change counts as no change). A changed block is written by format-dogsbay-md's
+ * serializer in the host's style, re-indented and with the original line ends; `exact` says
+ * beforehand whether that serializer gives back this block as written (when not, saving an edit
+ * also restyles the block's untouched lines). One such case is common: the parser reads a soft
+ * line break as a space, so an edited paragraph that was wrapped over several lines comes back
+ * on one line.
+ *
+ * Some blocks cannot be edited this way, and `editable` is false with the reason: indentation that
+ * does not start every line the same (a lazy continuation line, tabs on one line and spaces on the
+ * next — taking it apart would turn the block into code), a footnote reference (its definition is
+ * elsewhere on the page), or a block the parser makes nothing of. Reference links are resolved with
+ * the page's definitions when the host passes the page (`page`), and written back as inline links.
+ *
+ * Directives are parsed in preserve mode: templating, includes and conditions stay first-class
+ * nodes or ride verbatim atoms; `verbatim` counts the atoms, which a host may prefer to open as
+ * Markdown instead.
+ *
+ * Two entries, so each side loads only what it needs: this one (`openBlock`: text in, document
+ * out, document in, text back) needs the Markdown parser and no DOM, and runs where the host's
+ * source editor already has the parser; `./block-view` (`mountBlock`) is the editor on that
+ * document, with TipTap and no parser, for the page the block is shown in (the host passes the
+ * document between them as JSON). Neither imports the change-review view (`diff.ts`,
+ * `@dogsbay/tree-diff`).
+ */
+import { dogsbayMdToTree, treeToDogsbayMd } from "@dogsbay/format-dogsbay-md/browser";
+import { pmDocToTree, treeToPmDoc } from "./bridge.js";
+const VERBATIM = new Set(["dogsbayBlock", "dogsbayInline", "directiveRaw", "directiveRawInline"]);
+function countVerbatim(node) {
+    return (VERBATIM.has(node.type) ? 1 : 0) + (node.content ?? []).reduce((n, c) => n + countVerbatim(c), 0);
+}
+/** JSON with sorted keys: two trees built by different paths compare by content. */
+function stable(value) {
+    return JSON.stringify(value, (_key, v) => v && typeof v === "object" && !Array.isArray(v)
+        ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, v[k]]))
+        : v);
+}
+/** A blank line as CommonMark has it: spaces and tabs only (a no-break space is text). */
+const BLANK = /^[ \t]*$/;
+function layout(text) {
+    const bom = text.startsWith("\uFEFF") ? "\uFEFF" : "";
+    const rest = text.slice(bom.length);
+    const parts = rest.match(/[^\r\n]*(?:\r\n|\r|\n|$)/g).filter((p, i, all) => p !== "" || i < all.length - 1);
+    const line = (p) => p.replace(/(?:\r\n|\r|\n)$/, "");
+    let first = 0;
+    while (first < parts.length && BLANK.test(line(parts[first])))
+        first++;
+    let last = parts.length - 1;
+    while (last >= first && BLANK.test(line(parts[last])))
+        last--;
+    if (first > last)
+        return { lead: bom + rest, tail: "", eol: "\n", indent: "", inner: "" };
+    const middle = parts.slice(first, last + 1);
+    const lead = bom + parts.slice(0, first).join("");
+    const lastEnd = /(?:\r\n|\r|\n)$/.exec(middle[middle.length - 1])?.[0] ?? "";
+    const tail = lastEnd + parts.slice(last + 1).join("");
+    const eol = /\r\n|\r|\n/.exec(rest)?.[0] ?? "\n";
+    const lines = middle.map(line);
+    const indents = lines.filter((l) => !BLANK.test(l)).map((l) => /^[ \t]*/.exec(l)[0]);
+    let indent = indents[0];
+    for (const i of indents)
+        while (!i.startsWith(indent))
+            indent = indent.slice(0, -1);
+    const uneven = indent !== indents[0]
+        ? "its lines are not indented alike (a lazy continuation line, or tabs and spaces mixed)"
+        : undefined;
+    const inner = lines.map((l) => (l.startsWith(indent) ? l.slice(indent.length) : l.replace(/^[ \t]*/, ""))).join("\n");
+    return { lead, tail, eol, indent, inner, ...(uneven ? { uneven } : {}) };
+}
+function assemble(md, l) {
+    const lines = md.replace(/\n+$/, "").split("\n").map((line) => (line === "" ? "" : l.indent + line));
+    return l.lead + lines.join(l.eol) + l.tail;
+}
+/** `[name]: destination` lines of a page (reference-link definitions; not footnotes). */
+function definitions(page) {
+    return (page.match(/^ {0,3}\[(?!\^)(?:[^\]\\]|\\.)+\]:[ \t]*\S.*$/gm) ?? []).join("\n");
+}
+/** Open a block's source lines for editing (no DOM: the document, and how to write it back). */
+export function openBlock(text, options = {}) {
+    const l = layout(text);
+    // A leading line end: a block starting `---` is a rule, never front matter
+    const defs = options.page !== undefined ? definitions(options.page) : "";
+    const tree = dogsbayMdToTree(`\n${l.inner}${defs ? `\n\n${defs}\n` : ""}`, { directives: "preserve" }).tree;
+    const opts = { ...options.serialize, ...options.style };
+    const doc = treeToPmDoc(tree);
+    const opened = stable(pmDocToTree(doc));
+    const reason = l.uneven ??
+        (/\[\^[^\]]+\]/.test(l.inner) ? "it has a footnote reference, whose definition is elsewhere on the page" : undefined) ??
+        (options.page === undefined && /\]\[|\]:/.test(l.inner) ? "it may use the page's reference links: pass `page`" : undefined) ??
+        (l.inner.trim() && !tree.length ? "the parser makes no block of it" : undefined);
+    return {
+        doc,
+        editable: !reason,
+        ...(reason ? { reason } : {}),
+        verbatim: countVerbatim(doc),
+        exact: treeToDogsbayMd(tree, opts).replace(/\n+$/, "") === l.inner,
+        close(edited = doc) {
+            const now = pmDocToTree(edited);
+            if (stable(now) === opened)
+                return { text, changed: false };
+            const written = assemble(treeToDogsbayMd(now, opts), l);
+            return { text: written === text ? text : written, changed: written !== text };
+        },
+    };
+}

package/dist/bridge.d.ts

@@ -0,0 +1,37 @@
+/**
+ * TreeNode ⇄ TipTap(ProseMirror) JSON bridge.
+ *
+ * Pure functions over plain JSON (no editor runtime), so the round-trip is
+ * unit-testable without a browser. Two invariants:
+ *
+ *  1. TOTALITY over the schema — pmBlockToTree/pmInlineToTree handle every
+ *     node and mark the schema in schema.ts can produce (including
+ *     StarterKit's blockquote, horizontalRule, hardBreak and link input
+ *     rules). The throwing default exists only to catch future schema
+ *     additions loudly instead of corrupting documents silently.
+ *  2. "Never drop what you can't model" — TreeNode content the editor has
+ *     no first-class node for rides a `dogsbayBlock`/`dogsbayInline` atom
+ *     carrying the original JSON verbatim, and TreeNode props/meta the
+ *     editor doesn't edit ride the declared `dogsbayProps` attribute
+ *     (ProseMirror drops undeclared attrs — see schema.ts).
+ *
+ * Known vocabulary limit (matches the parser, not an editor regression):
+ * InlineCode carries no formatting flags, so `code` combined with other
+ * marks keeps only the code — same as parsing `**` + backtick markdown.
+ */
+import type { TreeNode } from "@dogsbay/types";
+export interface PMMark {
+    type: string;
+    attrs?: Record<string, unknown>;
+}
+export interface PMNode {
+    type: string;
+    attrs?: Record<string, unknown>;
+    content?: PMNode[];
+    text?: string;
+    marks?: PMMark[];
+}
+export declare function treeToPmDoc(tree: TreeNode[]): PMNode;
+/** Block-level mapping without the doc wrapper — for replacing ONE block with what a snippet parses to. */
+export declare function treeToPmBlocks(tree: TreeNode[]): PMNode[];
+export declare function pmDocToTree(doc: PMNode): TreeNode[];