@elabs-ai/components-editor 4.0.0

package/src/markdown-editor/slash/insert-directive.test.ts

@@ -0,0 +1,263 @@
+/**
+ * Unit tests for the load-bearing slash-menu logic: the pure ProseMirror
+ * insertion commands. We boot a HEADLESS Milkdown editor (no React, no widget —
+ * jsdom can't render the popup) with the real directive schemas + serializer, run
+ * the insertion through `resolveBrandInsert` / `resolveBasicInsert` exactly as the
+ * plugin does, and assert the document serializes to the correct `:::` / `::`
+ * markdown (the lossless round-trip the preview already understands).
+ *
+ * The live popup + keyboard UX (the React widget) is verified separately via
+ * Storybook / a browser — see slash-menu.stories.tsx.
+ */
+import { Editor, defaultValueCtx, rootCtx, editorViewCtx } from "@milkdown/kit/core";
+import { commonmark } from "@milkdown/kit/preset/commonmark";
+import { gfm } from "@milkdown/kit/preset/gfm";
+import { getMarkdown } from "@milkdown/kit/utils";
+import { Selection } from "@milkdown/kit/prose/state";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+
+import { directivePlugins } from "../directive-nodes";
+import {
+  __DIRECTIVE_DEFAULTS,
+  CALC_FENCE_SEED,
+  isContainerDirective,
+  isLeafDirective,
+  resolveBasicInsert,
+  resolveBrandInsert,
+  resolveCalcInsert,
+  resolveGuidedIterationInsert,
+  type InsertableDirective,
+} from "./insert-directive";
+
+/** Boot a headless Milkdown editor with the brand directive pipeline. */
+async function makeEditor(initial = ""): Promise<Editor> {
+  const root = document.createElement("div");
+  document.body.appendChild(root);
+  const editor = await Editor.make()
+    .config((ctx) => {
+      ctx.set(rootCtx, root);
+      ctx.set(defaultValueCtx, initial);
+    })
+    .use(commonmark)
+    .use(gfm)
+    .use(directivePlugins)
+    .create();
+  return editor;
+}
+
+/** Serialize the editor's current doc to markdown. */
+function serialize(editor: Editor): string {
+  return editor.action(getMarkdown());
+}
+
+/** Move the caret to the end of the document. */
+function caretToEnd(editor: Editor): void {
+  editor.action((ctx) => {
+    const view = ctx.get(editorViewCtx);
+    const tr = view.state.tr.setSelection(Selection.atEnd(view.state.doc));
+    view.dispatch(tr);
+  });
+}
+
+/**
+ * Place the caret at the end of the document, then run a brand insert there
+ * (range=null → insert at the cursor). Returns the resulting markdown.
+ */
+function insertBrandAtEnd(editor: Editor, name: InsertableDirective): string {
+  caretToEnd(editor);
+  editor.action((ctx) => resolveBrandInsert(ctx, name, null));
+  return serialize(editor);
+}
+
+let editor: Editor;
+
+beforeEach(async () => {
+  editor = await makeEditor("Intro paragraph.\n");
+});
+
+afterEach(async () => {
+  await editor.destroy();
+  document.body.innerHTML = "";
+});
+
+describe("resolveBrandInsert — container directives round-trip", () => {
+  test(":::card inserts and serializes to a card directive with the default title", () => {
+    const md = insertBrandAtEnd(editor, "card");
+    expect(md).toContain(":::card");
+    expect(md).toContain('title="Title"');
+    // The opening + closing fence are both present (a valid container directive).
+    expect(md.match(/:::/g)?.length ?? 0).toBeGreaterThanOrEqual(2);
+  });
+
+  test(":::callout inserts with the default type + title", () => {
+    const md = insertBrandAtEnd(editor, "callout");
+    expect(md).toContain(":::callout");
+    expect(md).toContain('type="info"');
+    expect(md).toContain('title="Note"');
+  });
+
+  test(":::timeline inserts with seeded status steps", () => {
+    const md = insertBrandAtEnd(editor, "timeline");
+    expect(md).toContain(":::timeline");
+    expect(md).toContain("Step one");
+    expect(md).toContain("(active) Step two");
+  });
+
+  test(":::iterate inserts with default attrs + a seeded {{token}} template body", () => {
+    const md = insertBrandAtEnd(editor, "iterate");
+    expect(md).toContain(":::iterate");
+    expect(md).toContain('as="item"');
+    expect(md).toContain('layout="stacked"');
+    expect(md).toContain("{{item.name}}");
+  });
+
+  test(":::pivot inserts with the matrix layout + a seeded template body", () => {
+    const md = insertBrandAtEnd(editor, "pivot");
+    expect(md).toContain(":::pivot");
+    expect(md).toContain('layout="matrix"');
+    expect(md).toContain("{{cell}}");
+  });
+});
+
+describe("resolveBrandInsert — leaf directives round-trip", () => {
+  test("::metric inserts and serializes to a leaf directive with default attrs", () => {
+    const md = insertBrandAtEnd(editor, "metric");
+    // A leaf directive uses a single colon-pair and carries the metric attrs.
+    expect(md).toContain("::metric");
+    expect(md).toContain('label="Label"');
+    expect(md).toContain('value="0"');
+    // It is NOT a container (no fenced :::metric block).
+    expect(md).not.toContain(":::metric");
+  });
+});
+
+describe("resolveBasicInsert — native blocks", () => {
+  test("heading inserts a markdown heading", () => {
+    caretToEnd(editor);
+    editor.action((ctx) => resolveBasicInsert(ctx, "heading", null));
+    const md = serialize(editor);
+    expect(md).toMatch(/^##\s/m);
+  });
+
+  test("divider inserts a horizontal rule", () => {
+    caretToEnd(editor);
+    editor.action((ctx) => resolveBasicInsert(ctx, "divider", null));
+    const md = serialize(editor);
+    expect(md).toMatch(/^(---|\*\*\*|___)\s*$/m);
+  });
+
+  test("quote inserts a blockquote", () => {
+    caretToEnd(editor);
+    editor.action((ctx) => resolveBasicInsert(ctx, "quote", null));
+    const md = serialize(editor);
+    expect(md).toMatch(/^>\s?/m);
+  });
+});
+
+describe("resolveCalcInsert — calc fence (#220)", () => {
+  test("inserts a ```calc fence seeded with the example ledger", () => {
+    caretToEnd(editor);
+    editor.action((ctx) => resolveCalcInsert(ctx, null));
+    const md = serialize(editor);
+    // A fenced code block with the `calc` info string, carrying the seed.
+    expect(md).toMatch(/```calc/);
+    expect(md).toContain("items = 3");
+    expect(md).toContain("total = items * price");
+    expect(CALC_FENCE_SEED).toContain("items = 3");
+  });
+});
+
+describe("range replacement (the /query is consumed)", () => {
+  test("inserting over a range replaces that range (the typed /card text)", () => {
+    // Simulate: user typed "/card" at the end; insert with that range so it's removed.
+    const md = editor.action((ctx) => {
+      const view = ctx.get(editorViewCtx);
+      // Append "/card" to the intro paragraph.
+      const docEnd = view.state.doc.content.size;
+      const insertTr = view.state.tr.insertText("/card", docEnd - 1);
+      view.dispatch(insertTr);
+      return null;
+    });
+    void md;
+    // Now compute the range covering "/card" and insert a card over it.
+    editor.action((ctx) => {
+      const view = ctx.get(editorViewCtx);
+      const text = view.state.doc.textContent;
+      const slashIndex = text.lastIndexOf("/card");
+      // Map text index → doc position inside the single paragraph (offset by 1
+      // for the paragraph open token).
+      const from = slashIndex + 1;
+      const to = from + "/card".length;
+      return resolveBrandInsert(ctx, "card", { from, to });
+    });
+    const out = serialize(editor);
+    expect(out).toContain(":::card");
+    // The literal "/card" trigger text must be gone (consumed by the insert).
+    expect(out).not.toContain("/card");
+  });
+});
+
+describe("resolveGuidedIterationInsert — the GUIDED /iterate /pivot insert path (#223)", () => {
+  test("emits a request seeded blank (no values) — the guided builder's onSaveData inserts the fully-bound directive", () => {
+    caretToEnd(editor);
+    editor.action((ctx) =>
+      resolveGuidedIterationInsert(ctx, "iterate", null, (request) => {
+        expect(request.kind).toBe("iterate");
+        expect(request.attributes).toEqual({});
+        expect(request.template).toBe("{{item.name}}");
+        request.onSaveData!({
+          attributes: { as: "item", layout: "grid", values: "Alice, Bob" },
+          template: "{{item.name}}",
+        });
+      }),
+    );
+    const md = serialize(editor);
+    expect(md).toContain(":::iterate");
+    expect(md).toContain('layout="grid"');
+    expect(md).toContain('values="Alice, Bob"');
+  });
+
+  test("the template-only provider's onSave inserts a directive with default (empty) attrs + the edited template", () => {
+    caretToEnd(editor);
+    editor.action((ctx) =>
+      resolveGuidedIterationInsert(ctx, "pivot", null, (request) => {
+        request.onSave("{{row}} → {{col}}");
+      }),
+    );
+    const md = serialize(editor);
+    expect(md).toContain(":::pivot");
+    expect(md).toContain("{{row}} → {{col}}");
+  });
+
+  test("nothing is inserted until the handler actually saves (Cancel leaves the doc untouched)", () => {
+    const before = serialize(editor);
+    caretToEnd(editor);
+    editor.action((ctx) =>
+      resolveGuidedIterationInsert(ctx, "iterate", null, () => {
+        // Simulate Cancel: the handler never calls onSave/onSaveData.
+      }),
+    );
+    expect(serialize(editor)).toBe(before);
+  });
+});
+
+describe("directive classification helpers", () => {
+  test("container vs leaf split is correct", () => {
+    expect(isContainerDirective("card")).toBe(true);
+    expect(isContainerDirective("callout")).toBe(true);
+    expect(isContainerDirective("timeline")).toBe(true);
+    expect(isContainerDirective("metric")).toBe(false);
+    expect(isLeafDirective("metric")).toBe(true);
+    expect(isLeafDirective("card")).toBe(false);
+  });
+
+  test("default attrs mirror the toolbar snippet shapes", () => {
+    expect(__DIRECTIVE_DEFAULTS.card).toEqual({ title: "Title" });
+    expect(__DIRECTIVE_DEFAULTS.callout).toEqual({ type: "info", title: "Note" });
+    expect(__DIRECTIVE_DEFAULTS.metric).toEqual({
+      label: "Label",
+      value: "0",
+      description: "detail",
+    });
+  });
+});

package/src/markdown-editor/slash/insert-directive.ts

@@ -0,0 +1,345 @@
+/**
+ * Pure ProseMirror insertion commands for the slash menu.
+ *
+ * The load-bearing logic of the slash menu lives here, deliberately decoupled
+ * from Milkdown's context and from React: an `insertBrandDirective` factory that
+ * builds the right `brand_container_directive` / `brand_leaf_directive` node (from
+ * the schemas in `directive-nodes.ts`) with sensible default attrs + a placeholder
+ * body, replaces the active slash range (or inserts at the cursor), and drops the
+ * caret into the first editable field. Because it takes the NodeTypes/Schema as
+ * arguments (not a Milkdown `Ctx`), it is unit-testable against a hand-built
+ * ProseMirror state and its output round-trips losslessly through the editor's
+ * existing `toMarkdown` runners (asserted in insert-directive.test.ts).
+ *
+ * `resolveBrandInsert` is the thin Milkdown-aware adapter: it reads the NodeTypes
+ * from the editor `Ctx` and returns the same pure command — so the slash plugin
+ * and any direct caller share one implementation.
+ */
+import type { Ctx } from "@milkdown/kit/ctx";
+import { editorViewCtx, parserCtx } from "@milkdown/kit/core";
+import type { Node as ProseNode, NodeType, Schema } from "@milkdown/kit/prose/model";
+import { Fragment } from "@milkdown/kit/prose/model";
+import type { Command, Transaction } from "@milkdown/kit/prose/state";
+import { TextSelection } from "@milkdown/kit/prose/state";
+
+import type { IterationEditHandler } from "../../markdown-iteration/edit-context";
+import {
+  builderValueFromParts,
+  emptyBuilderValue,
+  serializeIterationDirective,
+} from "../../markdown-iteration/iteration-builder";
+import { containerDirectiveSchema, leafDirectiveSchema } from "../directive-nodes";
+import type { BasicBlockId } from "./brand-slash-commands";
+
+/** A `[from, to)` document range to replace (the typed `/query`), or `null`. */
+export interface SlashRange {
+  from: number;
+  to: number;
+}
+
+/** Default attributes per brand directive — mirror the toolbar snippet shapes. */
+const DIRECTIVE_DEFAULTS: Record<string, Record<string, string>> = {
+  card: { title: "Title" },
+  callout: { type: "info", title: "Note" },
+  timeline: {},
+  metric: { label: "Label", value: "0", description: "detail" },
+  iterate: { as: "item", layout: "stacked" },
+  pivot: { layout: "matrix" },
+};
+
+/** Per-directive seed body text (the editable template for iterate/pivot). */
+const DIRECTIVE_BODY_SEED: Record<string, string> = {
+  iterate: "{{item.name}}",
+  pivot: "{{cell}}",
+};
+
+/** Brand container directives (`:::name`, editable body). */
+const CONTAINER_DIRECTIVES = new Set(["card", "callout", "timeline", "iterate", "pivot"]);
+/** Brand leaf directives (`::name`, atomic). */
+const LEAF_DIRECTIVES = new Set(["metric"]);
+
+/** The directive names the slash menu can insert as brand blocks. */
+export type InsertableDirective = "card" | "callout" | "timeline" | "metric" | "iterate" | "pivot";
+
+/**
+ * Build the default body content for a container directive: a single paragraph
+ * (the `content: "block+"` schema requires at least one block) carrying a short
+ * placeholder so the inserted block is never empty. Timeline seeds a 3-step
+ * bullet list (matching the toolbar snippet) when the schema has `bullet_list`.
+ */
+function containerBody(schema: Schema, name: string): Fragment {
+  const paragraph = schema.nodes.paragraph;
+  if (name === "timeline") {
+    const bulletList = schema.nodes.bullet_list;
+    const listItem = schema.nodes.list_item;
+    if (bulletList && listItem && paragraph) {
+      const steps = ["(done) Step one", "(active) Step two", "(pending) Step three"];
+      const items = steps.map((text) =>
+        listItem.create(null, paragraph.create(null, schema.text(text))),
+      );
+      return Fragment.from(bulletList.create(null, items));
+    }
+  }
+  // iterate / pivot: seed the editable TEMPLATE body with a token placeholder so
+  // the inserted block renders something the moment data is wired.
+  const seed = DIRECTIVE_BODY_SEED[name];
+  if (seed && paragraph) return Fragment.from(paragraph.create(null, schema.text(seed)));
+
+  // card / callout (and timeline fallback): one empty placeholder paragraph
+  // (the `content: "block+"` schema requires at least one block; the user types
+  // the body). If the schema somehow lacks a paragraph, return an empty fragment
+  // and let the schema fill its required content.
+  if (!paragraph) return Fragment.empty;
+  return Fragment.from(paragraph.create());
+}
+
+/**
+ * The pure insertion command. Builds the directive node from the given
+ * NodeTypes + schema and replaces `range` (or the current selection when
+ * `range` is null), then positions the caret in the first editable field
+ * (the body's start for containers; just after the atomic leaf for metric).
+ *
+ * Returns a ProseMirror `Command` `(state, dispatch?) => boolean`.
+ */
+export function insertBrandDirective(
+  name: InsertableDirective,
+  containerType: NodeType,
+  leafType: NodeType,
+  schema: Schema,
+  range: SlashRange | null,
+): Command {
+  return (state, dispatch) => {
+    const isContainer = CONTAINER_DIRECTIVES.has(name);
+    const isLeaf = LEAF_DIRECTIVES.has(name);
+    if (!isContainer && !isLeaf) return false;
+
+    const attributes = { ...(DIRECTIVE_DEFAULTS[name] ?? {}) };
+    const node = isContainer
+      ? containerType.create({ name, attributes }, containerBody(schema, name))
+      : leafType.create({ name, attributes });
+    if (!node) return false;
+
+    if (!dispatch) return true;
+
+    const { from, to } = range ?? { from: state.selection.from, to: state.selection.to };
+    const tr: Transaction = state.tr.replaceRangeWith(from, to, node);
+
+    // Place the caret: containers → first text position inside the body
+    // (from + 1 enters the node, +1 more enters its first child block);
+    // leaf (atomic) → just after the inserted node.
+    const caret = isContainer
+      ? Math.min(from + 2, tr.doc.content.size)
+      : Math.min(from + node.nodeSize, tr.doc.content.size);
+    const sel = TextSelection.near(tr.doc.resolve(caret), 1);
+    tr.setSelection(sel).scrollIntoView();
+
+    dispatch(tr);
+    return true;
+  };
+}
+
+/** Map a basic-block id to a ProseMirror command that inserts the native node. */
+export function insertBasicBlock(
+  id: BasicBlockId,
+  schema: Schema,
+  range: SlashRange | null,
+): Command {
+  return (state, dispatch) => {
+    const n = schema.nodes;
+    const { from, to } = range ?? { from: state.selection.from, to: state.selection.to };
+    const tr = state.tr;
+
+    const replaceWith = (node: ReturnType<NodeType["create"]> | null, caretOffset: number) => {
+      if (!node) return false;
+      if (!dispatch) return true;
+      tr.replaceRangeWith(from, to, node);
+      const caret = Math.min(from + caretOffset, tr.doc.content.size);
+      tr.setSelection(TextSelection.near(tr.doc.resolve(caret), 1)).scrollIntoView();
+      dispatch(tr);
+      return true;
+    };
+
+    switch (id) {
+      case "heading":
+        return replaceWith(n.heading?.create({ level: 2 }) ?? null, 1);
+      case "bullet-list": {
+        const li = n.list_item?.create(null, n.paragraph?.create());
+        return replaceWith(li ? (n.bullet_list?.create(null, li) ?? null) : null, 2);
+      }
+      case "ordered-list": {
+        const li = n.list_item?.create(null, n.paragraph?.create());
+        return replaceWith(li ? (n.ordered_list?.create(null, li) ?? null) : null, 2);
+      }
+      case "quote":
+        return replaceWith(n.blockquote?.create(null, n.paragraph?.create()) ?? null, 2);
+      case "code":
+        return replaceWith(n.code_block?.create() ?? null, 1);
+      case "divider": {
+        const hr = n.hr ?? n.horizontal_rule;
+        if (!hr) return false;
+        if (!dispatch) return true;
+        // A divider is atomic: insert it, then add a trailing empty paragraph so
+        // the caret has somewhere to land below the rule.
+        const node = hr.create();
+        tr.replaceRangeWith(from, to, node);
+        const para = n.paragraph?.create();
+        if (para) tr.insert(from + node.nodeSize, para);
+        const caret = Math.min(from + node.nodeSize + 1, tr.doc.content.size);
+        tr.setSelection(TextSelection.near(tr.doc.resolve(caret), 1)).scrollIntoView();
+        dispatch(tr);
+        return true;
+      }
+      default:
+        return false;
+    }
+  };
+}
+
+/** Seed body for a fresh ```calc fence — a tiny ledger so highlight + inlays show at once. */
+export const CALC_FENCE_SEED = ["items = 3", "price = 4.50", "total = items * price"].join("\n");
+
+/**
+ * Insert a ```calc fence (a `code_block` with `language: "calc"`) seeded with a
+ * short example, then drop the caret into the body. The editor's calc layer
+ * (`calc-editor-prose`) highlights + adds result inlays once `calc` hooks are wired;
+ * with none it is just a fenced code block (and renders as a `CalcBlock` in preview
+ * when `evaluate` is supplied) — so inserting one is always safe.
+ */
+export function insertCalcFence(
+  schema: Schema,
+  range: SlashRange | null,
+  seed: string = CALC_FENCE_SEED,
+): Command {
+  return (state, dispatch) => {
+    const codeBlock = schema.nodes.code_block;
+    if (!codeBlock) return false;
+    const node = seed
+      ? codeBlock.create({ language: "calc" }, schema.text(seed))
+      : codeBlock.create({ language: "calc" });
+    if (!node) return false;
+    if (!dispatch) return true;
+
+    const { from, to } = range ?? { from: state.selection.from, to: state.selection.to };
+    const tr = state.tr.replaceRangeWith(from, to, node);
+    // Caret at the body start (from + 1 enters the code block's text).
+    const caret = Math.min(from + 1, tr.doc.content.size);
+    tr.setSelection(TextSelection.near(tr.doc.resolve(caret), 1)).scrollIntoView();
+    dispatch(tr);
+    return true;
+  };
+}
+
+/** Milkdown-aware adapter for {@link insertCalcFence}. */
+export function resolveCalcInsert(ctx: Ctx, range: SlashRange | null): boolean {
+  const view = ctx.get(editorViewCtx);
+  const command = insertCalcFence(view.state.schema, range);
+  return command(view.state, view.dispatch.bind(view));
+}
+
+/**
+ * Milkdown-aware adapter: resolve the directive NodeTypes from the editor `Ctx`
+ * and run {@link insertBrandDirective} against the live view. Used by the slash
+ * plugin's command runners.
+ */
+export function resolveBrandInsert(
+  ctx: Ctx,
+  name: InsertableDirective,
+  range: SlashRange | null,
+): boolean {
+  const view = ctx.get(editorViewCtx);
+  const containerType = containerDirectiveSchema.type(ctx);
+  const leafType = leafDirectiveSchema.type(ctx);
+  const schema = view.state.schema;
+  const command = insertBrandDirective(name, containerType, leafType, schema, range);
+  return command(view.state, view.dispatch.bind(view));
+}
+
+/** Milkdown-aware adapter for the basic native blocks. */
+export function resolveBasicInsert(ctx: Ctx, id: BasicBlockId, range: SlashRange | null): boolean {
+  const view = ctx.get(editorViewCtx);
+  const command = insertBasicBlock(id, view.state.schema, range);
+  return command(view.state, view.dispatch.bind(view));
+}
+
+/**
+ * Parse a FULLY-BOUND directive markdown string (e.g. from
+ * `serializeIterationDirective`) and insert it at `range` (or the caret when
+ * `range` is null) — the insertion counterpart to the node-view's
+ * `writeBodyMarkdown` edit-in-place. Used by {@link resolveGuidedIterationInsert}
+ * (#223). Never throws; returns `false` when the markdown fails to parse.
+ */
+export function insertParsedMarkdown(
+  ctx: Ctx,
+  markdown: string,
+  range: SlashRange | null,
+): boolean {
+  try {
+    const view = ctx.get(editorViewCtx);
+    const parse = (ctx as { get: (t: unknown) => (md: string) => ProseNode | null }).get(parserCtx);
+    const parsed = parse(markdown);
+    if (!parsed) return false;
+
+    const { from, to } = range ?? { from: view.state.selection.from, to: view.state.selection.to };
+    const tr = view.state.tr.replaceWith(from, to, parsed.content);
+    const caret = Math.min(from + 2, tr.doc.content.size);
+    tr.setSelection(TextSelection.near(tr.doc.resolve(caret), 1)).scrollIntoView();
+    view.dispatch(tr);
+    return true;
+  } catch {
+    // Parser unavailable / stale range — leave the document untouched.
+    return false;
+  }
+}
+
+/**
+ * The GUIDED `/iterate` `/pivot` insert path (#223): instead of inserting a
+ * bare directive immediately, emit an edit REQUEST — seeded blank
+ * (`emptyBuilderValue`) — through the consumer's `IterationEditContext`
+ * handler, opening whichever modal it wires up (the node-view `⋯` re-edit's
+ * exact mechanism, reused for a fresh insert). BOTH writers are supplied so
+ * this works with either provider:
+ *   - `onSaveData` (the guided `IterationBuilderProvider`) — inserts the
+ *     fully-bound directive (value lists + layout + template).
+ *   - `onSave` (the template-only `IterationTemplateProvider`) — inserts a
+ *     directive built from DEFAULT (empty) attributes + the edited template.
+ * Nothing is INSERTED until the modal actually saves, so Cancel leaves no
+ * directive behind — unlike the direct-insert fallback, which always drops a
+ * placeholder template immediately. The typed `/query` trigger text itself is
+ * consumed up front by the caller (`runSlashCommand` in `brand-slash-plugin.ts`,
+ * BEFORE this resolver runs) — that's why `range` arrives as `null` here: by
+ * the time this fires, the range has already been deleted and the caret sits
+ * where the query used to start, so a save inserts there and a Cancel leaves a
+ * clean caret rather than the literal `/query` text.
+ */
+export function resolveGuidedIterationInsert(
+  ctx: Ctx,
+  kind: "iterate" | "pivot",
+  range: SlashRange | null,
+  handler: IterationEditHandler,
+): void {
+  const seed = emptyBuilderValue(kind);
+  handler({
+    kind,
+    template: seed.template,
+    attributes: {},
+    onSave: (template) => {
+      const value = builderValueFromParts(kind, {}, template);
+      insertParsedMarkdown(ctx, serializeIterationDirective(value), range);
+    },
+    onSaveData: ({ attributes, template }) => {
+      const value = builderValueFromParts(kind, attributes, template);
+      insertParsedMarkdown(ctx, serializeIterationDirective(value), range);
+    },
+  });
+}
+
+/** Exported for the unit test: the per-directive default attributes. */
+export const __DIRECTIVE_DEFAULTS = DIRECTIVE_DEFAULTS;
+
+/** Re-export for callers that need to know which names are containers vs leaves. */
+export function isContainerDirective(name: string): boolean {
+  return CONTAINER_DIRECTIVES.has(name);
+}
+export function isLeafDirective(name: string): boolean {
+  return LEAF_DIRECTIVES.has(name);
+}