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

package/dist/diff.js

@@ -0,0 +1,136 @@
+/**
+ * Change review — the DiffTree rendered as an editor view
+ * (plans/ide-change-review.md; plans/tree-diff-rendering.md names "the IDE's
+ * change review" as one of the views over ONE transform).
+ *
+ * `@dogsbay/tree-diff`'s `diffTrees(old, new)` yields a DiffTree: a TreeNode
+ * union tree carrying `diff` / `diffInline` / `diffPeer` / `diffMovedFrom`
+ * marks. Here it becomes a plain TreeNode tree the existing bridge already
+ * understands — block marks move to `meta.diff` (carried as `dogsbayProps`),
+ * changed prose becomes text runs flagged `diffOp: 'ins'|'del'` (two marks),
+ * a changed code/table-row pair renders peer (removed) then node — and the
+ * `DiffMarks` extension decorates the resulting ProseMirror nodes with
+ * `data-diff="…"`, exactly the vocabulary the comparison site's CSS uses. A
+ * tree with no marks renders identically to `treeToPmDoc`.
+ *
+ * Read-only by contract: the review pane never serializes back.
+ */
+import { Extension, Mark } from "@tiptap/core";
+import { Plugin, PluginKey } from "@tiptap/pm/state";
+import { Decoration, DecorationSet } from "@tiptap/pm/view";
+import { treeToPmDoc } from "./bridge.js";
+import { extensions } from "./schema.js";
+const segmentsToInline = (segments) => segments
+    .filter((s) => s.text !== "")
+    .map((s) => ({ type: "text", text: s.text, ...(s.op === "eq" ? {} : { diffOp: s.op }) }));
+const withMeta = (node, meta) => ({ ...node, meta: { ...(node.meta ?? {}), ...meta } });
+/** The inline run shapes with their text removed: differ ⇒ an attribute changed (href, src, code/link structure). */
+const inlineShape = (inline) => JSON.stringify(inline, (key, value) => (key === "text" ? undefined : value));
+/** DiffTree → plain TreeNode tree with diff meta (the bridge carries meta verbatim). */
+export function diffTreeToTree(nodes) {
+    const out = [];
+    for (const raw of nodes) {
+        const { diff, diffInline, diffPeer, diffMovedFrom, ...rest } = raw;
+        let node = rest;
+        const meta = {};
+        if (diff)
+            meta.diff = diff;
+        if (diffMovedFrom)
+            meta.diffMovedFrom = diffMovedFrom;
+        // word-level runs only when the visible text actually differs; a prose node
+        // whose text is identical but whose ATTRIBUTES changed (a link retargeted by
+        // rename-file, an image src) would otherwise look untouched — for those the
+        // old side is rendered as a peer instead, like a changed code block
+        const visibleChange = Boolean(diffInline?.some((s) => s.op !== "eq"));
+        if (visibleChange && Array.isArray(node.inline)) {
+            // tree-diff word-diffs nodeText(node), which INCLUDES nested children (a list
+            // item's sub-list) — so the runs already carry the children's text; keep the
+            // children too and the review shows it twice. Site parity: the runs replace
+            // the whole item (format-astro/src/diff-decoration.ts renders one <p>).
+            node = { ...node, inline: segmentsToInline(diffInline), children: undefined };
+        }
+        else if (node.children) {
+            node = { ...node, children: diffTreeToTree(node.children) };
+        }
+        if (Object.keys(meta).length)
+            node = withMeta(node, meta);
+        // Old side rendered as a "before" peer when the reader could not otherwise see
+        // what changed: a changed code/table-row pair, prose whose visible text is
+        // identical (attribute-only), or prose whose text AND an attribute changed
+        // (the runs show the words but not the retargeted link/image).
+        const attrChange = diffPeer !== undefined &&
+            Array.isArray(node.inline) &&
+            inlineShape(diffPeer.inline) !== inlineShape(raw.inline);
+        if (diffPeer && diff === "changed" && (!visibleChange || attrChange))
+            out.push(withMeta(diffPeer, { diff: "removed", diffPeerOf: "changed" }));
+        out.push(node);
+    }
+    return out;
+}
+export function diffTreeToPmDoc(nodes) {
+    return treeToPmDoc(diffTreeToTree(nodes));
+}
+/* ─────────────────────────── extension ─────────────────────────── */
+export const DiffIns = Mark.create({
+    name: "diffIns",
+    parseHTML: () => [{ tag: "ins" }],
+    renderHTML: () => ["ins", { class: "dogsbay-diff-ins", "data-diff-inline": "ins" }, 0],
+});
+export const DiffDel = Mark.create({
+    name: "diffDel",
+    parseHTML: () => [{ tag: "del" }],
+    renderHTML: () => ["del", { class: "dogsbay-diff-del", "data-diff-inline": "del" }, 0],
+});
+const diffMetaOf = (node) => {
+    const carried = node.attrs?.dogsbayProps;
+    if (carried?.meta && (carried.meta.diff || carried.meta.diffMovedFrom))
+        return carried.meta;
+    // unmodelled blocks ride as verbatim JSON atoms; their meta is inside
+    if (node.type.name === "dogsbayBlock" && typeof node.attrs?.json === "string") {
+        try {
+            const parsed = JSON.parse(node.attrs.json);
+            if (parsed.meta?.diff)
+                return parsed.meta;
+        }
+        catch {
+            /* not ours */
+        }
+    }
+    return undefined;
+};
+const diffDecorations = (doc) => {
+    const decorations = [];
+    doc.descendants((node, pos) => {
+        const meta = diffMetaOf(node);
+        if (!meta?.diff)
+            return true;
+        const attrs = { "data-diff": meta.diff };
+        if (meta.diffPeerOf)
+            attrs["data-diff-peer"] = meta.diffPeerOf;
+        if (meta.diffMovedFrom)
+            attrs.title = `moved from ${meta.diffMovedFrom.join(" › ")}`;
+        decorations.push(Decoration.node(pos, pos + node.nodeSize, attrs));
+        // children of an added/removed subtree are implied by the root mark
+        return meta.diff === "changed" || meta.diff === "moved";
+    });
+    return DecorationSet.create(doc, decorations);
+};
+const diffMarksKey = new PluginKey("dogsbayDiffMarks");
+/** Node decorations from `meta.diff` (data-diff="added|removed|changed|moved"). */
+export const DiffMarks = Extension.create({
+    name: "dogsbayDiffMarks",
+    addProseMirrorPlugins() {
+        return [
+            new Plugin({
+                key: diffMarksKey,
+                state: {
+                    init: (_config, state) => diffDecorations(state.doc),
+                    apply: (tr, old) => (tr.docChanged ? diffDecorations(tr.doc) : old),
+                },
+                props: { decorations: (state) => diffMarksKey.getState(state) },
+            }),
+        ];
+    },
+});
+/** The read-only review schema: the editing extensions + the two diff marks + the decorator. */
+export const diffExtensions = [...extensions, DiffIns, DiffDel, DiffMarks];

package/dist/directive-context.d.ts

@@ -0,0 +1,16 @@
+import type { PMNode } from "./bridge.js";
+export type PreviewVars = Record<string, unknown>;
+/** Evaluate a conditional's `test` under `vars`; `undefined` when it cannot be evaluated. */
+export declare function evaluateTest(test: string, vars: PreviewVars): boolean | undefined;
+/** Resolve a `{{ expr }}` under `vars`; `undefined` when unset or unevaluable. */
+export declare function resolveExpr(expr: string, vars: PreviewVars): unknown;
+/** Format a resolved value the way minja prints it (`String(value)`; never throws). */
+export declare function formatValue(value: unknown): string;
+/**
+ * The document's own `{% set name = value %}` definitions, in document
+ * order, evaluated as minja literals/expressions over the vars defined so
+ * far (a later `set` may reference an earlier one). Only TOP-LEVEL
+ * varDefs count — a `set` inside a conditional region is itself
+ * conditional and the preview must not pretend otherwise.
+ */
+export declare function collectDocVarDefs(doc: PMNode, base?: PreviewVars): PreviewVars;

package/dist/directive-context.js

@@ -0,0 +1,87 @@
+/**
+ * Directive preview evaluation (directive-model Phase 5b).
+ *
+ * The editor never RESOLVES directives — preserve mode keeps them as
+ * nodes and the publish pipeline evaluates them. It may PREVIEW them:
+ * given a variable context (a deliverable's attributes + the document's
+ * own `{% set %}` lines), which conditional regions are live and what a
+ * `{{ expr }}` chip would print. Evaluation goes through minja's own
+ * expression evaluator so the preview cannot disagree with the build.
+ *
+ * Every helper is total: a malformed expression yields `undefined`
+ * (shown as "unknown"), never a throw into a node view.
+ */
+import { Context, evaluateExpression, parseExpression } from "@dogsbay/minja/browser";
+function contextFor(vars) {
+    // hyphenToUnderscore normalizes the LOOKUP, not the stored keys, so a
+    // supplied `product-title` would never match — same alias rule as the
+    // build's preprocess (cli/src/site-build/preprocess.ts)
+    // build's preprocess); an EXPLICIT underscored key wins over the alias
+    const ctx = new Context(undefined, { hyphenToUnderscore: true });
+    for (const [k, v] of Object.entries(vars))
+        ctx.set(k, v);
+    for (const [k, v] of Object.entries(vars)) {
+        if (!k.includes("-"))
+            continue;
+        const u = k.replace(/-/g, "_");
+        if (!(u in vars))
+            ctx.set(u, v);
+    }
+    return ctx;
+}
+/** Evaluate a conditional's `test` under `vars`; `undefined` when it cannot be evaluated. */
+export function evaluateTest(test, vars) {
+    try {
+        const value = evaluateExpression(parseExpression(test), contextFor(vars));
+        return isTruthy(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Resolve a `{{ expr }}` under `vars`; `undefined` when unset or unevaluable. */
+export function resolveExpr(expr, vars) {
+    try {
+        return evaluateExpression(parseExpression(expr), contextFor(vars));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Format a resolved value the way minja prints it (`String(value)`; never throws). */
+export function formatValue(value) {
+    if (value === undefined || value === null)
+        return "";
+    try {
+        return String(value);
+    }
+    catch {
+        return "";
+    }
+}
+/** minja's rule (renderer.ts isTruthy): only undefined/null/false/0/'' are falsy — `[]` and `{}` are truthy. */
+function isTruthy(v) {
+    return !(v === undefined || v === null || v === false || v === 0 || v === "");
+}
+/**
+ * The document's own `{% set name = value %}` definitions, in document
+ * order, evaluated as minja literals/expressions over the vars defined so
+ * far (a later `set` may reference an earlier one). Only TOP-LEVEL
+ * varDefs count — a `set` inside a conditional region is itself
+ * conditional and the preview must not pretend otherwise.
+ */
+export function collectDocVarDefs(doc, base = {}) {
+    const vars = { ...base };
+    for (const node of doc.content ?? []) {
+        if (node.type !== "varDef")
+            continue;
+        const name = String(node.attrs?.name ?? "").trim();
+        if (!name)
+            continue;
+        // minja's `set` stores whatever the expression evaluates to — including
+        // undefined for an unset name; inventing the raw text here would make a
+        // later `{% if name %}` preview LIVE where the build renders nothing
+        vars[name] = resolveExpr(String(node.attrs?.value ?? ""), vars);
+    }
+    return vars;
+}

package/dist/directive-fields.d.ts

@@ -0,0 +1,8 @@
+export type DirectiveField = "expr" | "test" | "src" | "name" | "value";
+/** Delimiters that would open/close a tag inside a tag. */
+export declare const DIRECTIVE_MARKERS: readonly ["{%", "%}", "{{", "}}", "{#", "#}"];
+/**
+ * Returns an error message for a value the chip must refuse, or null when
+ * the (trimmed) value is acceptable. Callers trim before storing.
+ */
+export declare function validateDirectiveField(field: DirectiveField, raw: string): string | null;

package/dist/directive-fields.js

@@ -0,0 +1,60 @@
+/**
+ * Validation for directive chip fields (directive-model 5b).
+ *
+ * The serializer interpolates a directive node's attributes VERBATIM into
+ * `{{ expr }}` / `{% if test %}` / `{% include "src" %}` / `{% set name =
+ * value %}` — minja has no escape syntax for these, so a value that
+ * contains a tag delimiter cannot be emitted safely: `a %} b` as a test
+ * produces `{% if a %} b %}` and the region's body is no longer guarded
+ * (and a `{% raw %}` typed anywhere swallows the page to the next
+ * `{% endraw %}` on reparse). The chips therefore REFUSE such values, and
+ * the serializer throws on them as a second line (a programmatic
+ * updateAttributes cannot bypass the editor form).
+ */
+import { parseExpression } from "@dogsbay/minja/browser";
+/** Delimiters that would open/close a tag inside a tag. */
+export const DIRECTIVE_MARKERS = ["{%", "%}", "{{", "}}", "{#", "#}"];
+/** minja `set` names (and what directive-preserve recognises as a set). */
+const SET_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * Returns an error message for a value the chip must refuse, or null when
+ * the (trimmed) value is acceptable. Callers trim before storing.
+ */
+export function validateDirectiveField(field, raw) {
+    const v = raw.trim();
+    const marker = DIRECTIVE_MARKERS.find((m) => v.includes(m));
+    if (marker)
+        return `must not contain "${marker}"`;
+    if (/[\r\n]/.test(v))
+        return "must be a single line";
+    switch (field) {
+        case "expr":
+            if (!v)
+                return "expression is required";
+            return null;
+        case "test":
+            if (!v)
+                return "condition is required";
+            return null;
+        case "src":
+            if (!v)
+                return "include path is required";
+            if (/["']/.test(v))
+                return "path must not contain quotes";
+            return null;
+        case "name":
+            if (!SET_NAME.test(v))
+                return "name must be a valid identifier (letters, digits, _)";
+            return null;
+        case "value":
+            if (!v)
+                return "value is required";
+            try {
+                parseExpression(v);
+            }
+            catch {
+                return 'not a valid expression — quote strings ("…")';
+            }
+            return null;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @dogsbay/editor — TipTap/ProseMirror editor layer for the TreeNode
+ * vocabulary.
+ *
+ * Two React-free surfaces:
+ *   - schema: TipTap extensions (StarterKit + Callout + Variable +
+ *     dogsbayBlock/dogsbayInline verbatim-passthrough atoms)
+ *   - bridge: pure-JSON TreeNode[] ⇄ ProseMirror-doc conversion with the
+ *     "never drop what you can't model" escape hatch
+ *
+ * Consumers bring their own view layer (@tiptap/react etc.). The dev
+ * harness in main.tsx / index.html is not part of the published surface.
+ */
+export { extensions, Callout, Variable, Conditional, Include, VarDef, DirectiveRaw, ConditionalSpan, DirectiveRawInline, DogsbayBlock, DogsbayInline, DogsbayProps, } from "./schema.js";
+export { treeToPmDoc, pmDocToTree, treeToPmBlocks } from "./bridge.js";
+export type { PMNode, PMMark } from "./bridge.js";
+export { diffTreeToTree, diffTreeToPmDoc, diffExtensions, DiffMarks, DiffIns, DiffDel, type DiffMeta, type DiffKind, } from "./diff.js";
+export { evaluateTest, resolveExpr, formatValue, collectDocVarDefs, type PreviewVars, } from "./directive-context.js";
+export { validateDirectiveField, DIRECTIVE_MARKERS, type DirectiveField } from "./directive-fields.js";

package/dist/index.js

@@ -0,0 +1,18 @@
+/**
+ * @dogsbay/editor — TipTap/ProseMirror editor layer for the TreeNode
+ * vocabulary.
+ *
+ * Two React-free surfaces:
+ *   - schema: TipTap extensions (StarterKit + Callout + Variable +
+ *     dogsbayBlock/dogsbayInline verbatim-passthrough atoms)
+ *   - bridge: pure-JSON TreeNode[] ⇄ ProseMirror-doc conversion with the
+ *     "never drop what you can't model" escape hatch
+ *
+ * Consumers bring their own view layer (@tiptap/react etc.). The dev
+ * harness in main.tsx / index.html is not part of the published surface.
+ */
+export { extensions, Callout, Variable, Conditional, Include, VarDef, DirectiveRaw, ConditionalSpan, DirectiveRawInline, DogsbayBlock, DogsbayInline, DogsbayProps, } from "./schema.js";
+export { treeToPmDoc, pmDocToTree, treeToPmBlocks } from "./bridge.js";
+export { diffTreeToTree, diffTreeToPmDoc, diffExtensions, DiffMarks, DiffIns, DiffDel, } from "./diff.js";
+export { evaluateTest, resolveExpr, formatValue, collectDocVarDefs, } from "./directive-context.js";
+export { validateDirectiveField, DIRECTIVE_MARKERS } from "./directive-fields.js";

package/dist/schema.d.ts

@@ -0,0 +1,54 @@
+/**
+ * TipTap schema for the TreeNode vocabulary: StarterKit (paragraph,
+ * heading, lists, blockquote, codeBlock, horizontalRule, hardBreak,
+ * bold/italic/strike/code/link marks) plus the custom pieces:
+ *   - callout      — a block container
+ *   - variable     — an inline atom (the directive-chip mechanism)
+ *   - dogsbayBlock — a block atom carrying verbatim TreeNode JSON (lossless
+ *                    passthrough for tables and anything unmodeled)
+ *   - dogsbayInline — the inline equivalent
+ *   - DogsbayProps — a hidden global attribute on every modeled block that
+ *                    carries the original TreeNode props/meta verbatim, so
+ *                    fields the editor doesn't model (code title/highlights,
+ *                    heading {#id .class}, ordered-list start, …) survive
+ *                    the round trip. ProseMirror drops undeclared attrs, so
+ *                    this MUST be a declared attribute.
+ *
+ * Underline is disabled: InlineText has no underline flag (markdown cannot
+ * express it), so anything underlined in the editor would be silently
+ * stripped on serialize — better not to offer it.
+ */
+import { Extension, Node } from "@tiptap/core";
+export declare const DogsbayProps: Extension<any, any>;
+/**
+ * `tableRole` is a prosemirror-tables NodeSpec field, not a TipTap one, so
+ * it is declared on NodeConfig here and copied into the schema spec by
+ * `TableEditing.extendNodeSchema` below (the same mechanism TipTap's own
+ * table extension uses).
+ */
+declare module "@tiptap/core" {
+    interface NodeConfig<Options = any, Storage = any> {
+        tableRole?: string | ((this: {
+            name: string;
+            options: Options;
+            storage: Storage;
+        }) => string);
+    }
+}
+export declare const Table: Node<any, any>;
+export declare const TableRow: Node<any, any>;
+export declare const TableHeader: Node<any, any>;
+export declare const TableCell: Node<any, any>;
+/** prosemirror-tables' editing plugin + cell navigation (Tab / Shift-Tab). */
+export declare const TableEditing: Extension<any, any>;
+export declare const Callout: Node<any, any>;
+export declare const Variable: Node<any, any>;
+export declare const Conditional: Node<any, any>;
+export declare const Include: Node<any, any>;
+export declare const VarDef: Node<any, any>;
+export declare const DirectiveRaw: Node<any, any>;
+export declare const ConditionalSpan: Node<any, any>;
+export declare const DirectiveRawInline: Node<any, any>;
+export declare const DogsbayBlock: Node<any, any>;
+export declare const DogsbayInline: Node<any, any>;
+export declare const extensions: (Node<any, any> | Extension<any, any> | Extension<import("@tiptap/starter-kit").StarterKitOptions, any>)[];