@elabs-ai/components-editor 4.0.0

package/src/markdown-editor/exit-keymap.test.ts

@@ -0,0 +1,88 @@
+/**
+ * Unit tests for the code-block exit command (A3). We boot a HEADLESS Milkdown
+ * editor with the real commonmark + gfm schema (so the `code_block` node — and
+ * the ```calc fence, which is just a code block — is the genuine one), position
+ * the caret inside a code block, run {@link exitCodeBlock} exactly as the
+ * `handleKeyDown` binding does, and assert the caret escapes to a paragraph. The
+ * live Tab keypress UX is exercised in the browser via the editor stories.
+ */
+import { Editor, defaultValueCtx, rootCtx, editorViewCtx } from "@milkdown/kit/core";
+import { commonmark } from "@milkdown/kit/preset/commonmark";
+import { gfm } from "@milkdown/kit/preset/gfm";
+import { Selection, TextSelection } from "@milkdown/kit/prose/state";
+import type { EditorView } from "@milkdown/kit/prose/view";
+import type { Node as ProseNode } from "@milkdown/kit/prose/model";
+import { afterEach, describe, expect, test } from "vitest";
+
+import { exitCodeBlock } from "./exit-keymap";
+
+const roots: HTMLElement[] = [];
+
+async function makeEditor(initial: string): Promise<Editor> {
+  const root = document.createElement("div");
+  document.body.appendChild(root);
+  roots.push(root);
+  return Editor.make()
+    .config((ctx) => {
+      ctx.set(rootCtx, root);
+      ctx.set(defaultValueCtx, initial);
+    })
+    .use(commonmark)
+    .use(gfm)
+    .create();
+}
+
+afterEach(() => {
+  for (const r of roots.splice(0)) r.remove();
+});
+
+const getView = (editor: Editor): EditorView => editor.action((ctx) => ctx.get(editorViewCtx));
+
+/** Position just inside the first code block's content (or -1 if none). */
+function firstCodeBlockContentPos(doc: ProseNode): number {
+  let pos = -1;
+  doc.descendants((node, p) => {
+    if (pos === -1 && node.type.spec.code) pos = p + 1;
+    return pos === -1;
+  });
+  return pos;
+}
+
+describe("exitCodeBlock", () => {
+  test("from a trailing code block, inserts a following paragraph and lands the caret in it", async () => {
+    const editor = await makeEditor("Intro\n\n```\nx = 1\n```\n");
+    const v = getView(editor);
+    // Caret at the very end of the doc = inside the trailing code block.
+    v.dispatch(v.state.tr.setSelection(Selection.atEnd(v.state.doc)));
+    expect(v.state.selection.$head.parent.type.spec.code).toBe(true);
+
+    const handled = exitCodeBlock(v.state, v.dispatch);
+    expect(handled).toBe(true);
+    expect(v.state.selection.$head.parent.type.name).toBe("paragraph");
+    expect(v.state.doc.lastChild?.type.name).toBe("paragraph");
+  });
+
+  test("steps into an existing following paragraph without inserting a new one", async () => {
+    const editor = await makeEditor("```\nx = 1\n```\n\nAfter\n");
+    const v = getView(editor);
+    v.dispatch(
+      v.state.tr.setSelection(
+        TextSelection.create(v.state.doc, firstCodeBlockContentPos(v.state.doc)),
+      ),
+    );
+    const before = v.state.doc.childCount;
+
+    const handled = exitCodeBlock(v.state, v.dispatch);
+    expect(handled).toBe(true);
+    expect(v.state.doc.childCount).toBe(before);
+    expect(v.state.selection.$head.parent.type.name).toBe("paragraph");
+    expect(v.state.selection.$head.parent.textContent).toBe("After");
+  });
+
+  test("returns false when the caret is not inside a code block", async () => {
+    const editor = await makeEditor("Just a paragraph.\n");
+    const v = getView(editor);
+    v.dispatch(v.state.tr.setSelection(Selection.atStart(v.state.doc)));
+    expect(exitCodeBlock(v.state, v.dispatch)).toBe(false);
+  });
+});

package/src/markdown-editor/exit-keymap.ts

@@ -0,0 +1,87 @@
+"use client";
+
+/**
+ * Exit-block keymap — let the caret escape a fenced code block (incl. the
+ * ```calc fence) to the block that follows it.
+ *
+ * Inside a `code_block` there is otherwise no keyboard way out: Tab is swallowed
+ * (indent) or blurs the editor, and a code block that is the document's LAST
+ * child traps the caret entirely — there is no following line to arrow into.
+ * This binds Tab and Mod-Enter (collapsed selection, inside a code block) to move
+ * the caret to the block AFTER the code block, inserting a trailing empty
+ * paragraph first when the code block is the document's last child.
+ *
+ * Why `props.handleKeyDown` and not a `keymap` plugin: `handleKeyDown` props run
+ * BEFORE keymap plugins, so this reliably beats any commonmark Tab→indent
+ * binding. It only acts inside a code block, so Tab in a GFM table (`tableKeymap`
+ * → next cell) and Tab elsewhere are untouched, and the slash menu (which never
+ * opens inside a code block) is unaffected.
+ */
+import type { MilkdownPlugin } from "@milkdown/kit/ctx";
+import { $prose } from "@milkdown/kit/utils";
+import type { Command, Transaction } from "@milkdown/kit/prose/state";
+import { Plugin, TextSelection } from "@milkdown/kit/prose/state";
+
+/**
+ * ProseMirror command: if the collapsed selection sits inside a `code_block`,
+ * move the caret to the block after it — creating a trailing empty paragraph when
+ * the code block is the document's last child. Returns `false` otherwise so other
+ * handlers still run. Exported standalone so it can be unit-tested against the
+ * real editor schema without a live keyboard event.
+ */
+export const exitCodeBlock: Command = (state, dispatch) => {
+  const { selection } = state;
+  if (!selection.empty) return false;
+  const { $head } = selection;
+  // `spec.code` is set on code-block node types (commonmark's `code_block`,
+  // including the ```calc fence) — the same check the slash plugin uses.
+  if (!$head.parent.type.spec.code) return false;
+
+  const paragraph = state.schema.nodes.paragraph;
+  if (!paragraph) return false;
+
+  // Position directly after the code-block node (its sibling boundary).
+  const after = $head.after($head.depth);
+
+  if (dispatch) {
+    const nodeAfter = state.doc.resolve(after).nodeAfter;
+    let tr: Transaction = state.tr;
+    if (nodeAfter && nodeAfter.isTextblock) {
+      // A textblock already follows — step the caret into its content start.
+      tr = tr.setSelection(TextSelection.create(tr.doc, after + 1));
+    } else {
+      // Nothing usable follows (the code block is the last child, or a leaf
+      // follows) — insert a fresh empty paragraph and land the caret inside it.
+      const para = paragraph.createAndFill();
+      if (!para) return false;
+      tr = tr.insert(after, para);
+      tr = tr.setSelection(TextSelection.create(tr.doc, after + 1));
+    }
+    dispatch(tr.scrollIntoView());
+  }
+  return true;
+};
+
+/**
+ * The Milkdown plugin array to `.use()` on the editor chain. Binds Tab and
+ * Mod-Enter to {@link exitCodeBlock} via `handleKeyDown`.
+ */
+export function exitKeymapPlugins(): MilkdownPlugin[] {
+  return [
+    $prose(
+      () =>
+        new Plugin({
+          props: {
+            handleKeyDown: (view, event) => {
+              const isTab = event.key === "Tab" && !event.shiftKey;
+              const isModEnter = event.key === "Enter" && (event.metaKey || event.ctrlKey);
+              if (!isTab && !isModEnter) return false;
+              const handled = exitCodeBlock(view.state, view.dispatch);
+              if (handled) event.preventDefault();
+              return handled;
+            },
+          },
+        }),
+    ) as unknown as MilkdownPlugin,
+  ];
+}

package/src/markdown-editor/index.ts

@@ -0,0 +1,6 @@
+export {
+  MarkdownEditor,
+  type MarkdownEditorProps,
+  type MarkdownEditorHandle,
+  type EmbedAssetFn,
+} from "./markdown-editor";

package/src/markdown-editor/markdown-editor.css

@@ -0,0 +1,250 @@
+/**
+ * Token-driven theme for the Milkdown (ProseMirror) WYSIWYG surface.
+ *
+ * Milkdown core ships ZERO styles (headless), so this is where brand-ui owns the
+ * look. Every value is a semantic design token (var(--foreground), --border,
+ * --radius, …) — NO raw colors — so the editor matches all three themes
+ * (light/dark) for free. Every rule
+ * is scoped under `.milkdown-host` so nothing leaks globally.
+ */
+
+.milkdown-host .ProseMirror {
+  outline: none;
+  padding: 1rem 1.1rem;
+  min-height: 9rem;
+  color: var(--foreground);
+  font-size: 0.875rem;
+  line-height: 1.65;
+  caret-color: var(--primary);
+  word-break: break-word;
+  /* Same reading measure as the preview (max-w-3xl). Driven by the shared scale
+     (--md-measure, set via markdownScaleVars) so editor + preview match (#18). */
+  max-width: var(--md-measure, 48rem);
+  margin-inline: auto;
+}
+
+.milkdown-host .ProseMirror:focus {
+  outline: none;
+}
+
+/* ----------------------------------------------------------------------------
+ * Fill height — the editable grows to fill a definite-height parent.
+ *
+ * Milkdown's host box is otherwise content-sized (the `.ProseMirror` floor below
+ * is `min-height: 9rem`), so inside a tall pane a short document leaves a large
+ * dead area below the editable AND the caret-anchored `/` slash menu clips inside
+ * the short box near the bottom edge. Making `.milkdown-host` a column flex that
+ * fills its parent — and letting the intermediate Milkdown wrapper + the
+ * ProseMirror surface grow inside it — means the editable fills the pane
+ * (clickable everywhere) and the slash menu has room to open / flip.
+ *
+ * `min-height: 100%` only resolves against a parent with a DEFINITE height (the
+ * workspace's `h-full` wysiwyg pane, or any sized container). In an
+ * indefinite-height parent it resolves to `auto`, so the standalone / short
+ * editor still sizes to its content above the 9rem floor — no regression for the
+ * autodocs / inline cases. (elabs-components: editor-fill-height)
+ * ------------------------------------------------------------------------- */
+.milkdown-host {
+  display: flex;
+  flex-direction: column;
+  min-height: 100%;
+}
+.milkdown-host > div,
+.milkdown-host .milkdown {
+  display: flex;
+  min-height: 0;
+  flex: 1 1 auto;
+  flex-direction: column;
+}
+.milkdown-host .ProseMirror.editor {
+  flex: 1 1 auto;
+}
+
+.milkdown-host .ProseMirror > * + * {
+  margin-top: 0.7em;
+}
+
+/* Headings — sizes/weight/tracking come from the SHARED markdown scale
+   (markdown-scale.ts → --md-* vars on .milkdown-host), so the editor matches the
+   prose `Heading` exactly and can't drift on the next edit to either side (#18).
+   Fallbacks equal the canonical scale for use without the vars (e.g. clipboard). */
+.milkdown-host .ProseMirror h1,
+.milkdown-host .ProseMirror h2,
+.milkdown-host .ProseMirror h3,
+.milkdown-host .ProseMirror h4,
+.milkdown-host .ProseMirror h5,
+.milkdown-host .ProseMirror h6 {
+  font-weight: var(--md-heading-weight, 600);
+  letter-spacing: var(--md-heading-tracking, -0.025em);
+  line-height: 1.25;
+  color: var(--foreground);
+  margin-top: 1.1em;
+}
+.milkdown-host .ProseMirror h1 {
+  font-size: var(--md-h1, 1.5rem);
+}
+.milkdown-host .ProseMirror h2 {
+  font-size: var(--md-h2, 1.25rem);
+}
+.milkdown-host .ProseMirror h3 {
+  font-size: var(--md-h3, 1.125rem);
+}
+.milkdown-host .ProseMirror h4 {
+  font-size: var(--md-h4, 1rem);
+}
+.milkdown-host .ProseMirror h5 {
+  font-size: var(--md-h5, 0.875rem);
+}
+.milkdown-host .ProseMirror h6 {
+  font-size: var(--md-h6, 0.875rem);
+  color: var(--muted-foreground);
+}
+
+/* Inline */
+.milkdown-host .ProseMirror a {
+  color: var(--primary);
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+.milkdown-host .ProseMirror strong {
+  font-weight: 650;
+}
+.milkdown-host .ProseMirror code {
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 0.85em;
+  background: var(--muted);
+  color: var(--foreground);
+  padding: 0.12em 0.36em;
+  border-radius: calc(var(--radius) - 4px);
+}
+
+/* Blocks */
+.milkdown-host .ProseMirror blockquote {
+  border-left: 2px solid var(--border);
+  padding-left: 1rem;
+  color: var(--muted-foreground);
+}
+.milkdown-host .ProseMirror pre {
+  background: var(--surface-muted);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  padding: 0.85rem 1rem;
+  overflow: auto;
+}
+.milkdown-host .ProseMirror pre code {
+  background: transparent;
+  padding: 0;
+  font-size: 0.82rem;
+}
+.milkdown-host .ProseMirror hr {
+  border: none;
+  border-top: 1px solid var(--border);
+  margin: 1.25em 0;
+}
+
+/* Lists */
+.milkdown-host .ProseMirror ul,
+.milkdown-host .ProseMirror ol {
+  padding-left: 1.4rem;
+}
+.milkdown-host .ProseMirror ul {
+  list-style: disc;
+}
+.milkdown-host .ProseMirror ol {
+  list-style: decimal;
+}
+.milkdown-host .ProseMirror li > * + * {
+  margin-top: 0.35em;
+}
+
+/* Tables (GFM) */
+.milkdown-host .ProseMirror table {
+  border-collapse: collapse;
+  width: 100%;
+  font-size: 0.85rem;
+}
+.milkdown-host .ProseMirror th,
+.milkdown-host .ProseMirror td {
+  border: 1px solid var(--border);
+  padding: 0.4rem 0.6rem;
+  text-align: left;
+}
+.milkdown-host .ProseMirror th {
+  background: var(--surface-muted);
+  font-weight: 600;
+}
+
+/* Task lists (GFM) */
+.milkdown-host .ProseMirror ul[data-item-type="task"] {
+  list-style: none;
+  padding-left: 0.25rem;
+}
+
+/* Read-only mode dims the caret affordance */
+.milkdown-host .ProseMirror[contenteditable="false"] {
+  caret-color: transparent;
+}
+
+/* ---- Brand `:::` directives ----------------------------------------------------
+ * These now render as LIVE @brand React components via @prosemirror-adapter/react
+ * (see directive-views.tsx), so the box-model chrome (card/callout/metric borders,
+ * fills, type accents) comes from the components themselves — NOT from here. This
+ * section only owns what the editor adds on top: outer spacing, the editable-body
+ * rhythm, the timeline frame (an editable list, not a derived <Timeline>), and the
+ * inline-edit affordance for editable attributes (card/callout title, metric
+ * label/value). The `toDOM` defs in directive-nodes.ts keep their own marker classes
+ * for clipboard serialization but are not visually rendered while node-views are on.
+ */
+.milkdown-host .brand-directive {
+  margin: 0.85em 0;
+}
+.milkdown-host .brand-directive__body > * + * {
+  margin-top: 0.6em;
+}
+/* The first/last editable block inside a card/callout shouldn't add stray margin
+ * on top of the component's own padding. */
+.milkdown-host .brand-directive__body > :first-child {
+  margin-top: 0;
+}
+
+/* timeline → keep the list editable inside a subtle frame */
+.milkdown-host .brand-directive--timeline {
+  border-left: 2px solid var(--border);
+  padding-left: 1rem;
+}
+
+/* Inline-editable directive attribute (seamless, caret-friendly). */
+.milkdown-host .brand-inline-edit {
+  cursor: text;
+  min-width: 1ch;
+  /* inherit the surrounding component's type (CardTitle, MetricBlock label/value) */
+  font: inherit;
+  color: inherit;
+  letter-spacing: inherit;
+}
+.milkdown-host .brand-inline-edit:empty::before {
+  content: attr(data-placeholder);
+  color: var(--muted-foreground);
+  opacity: 0.65;
+  pointer-events: none;
+}
+
+/* ------------------------------------------------------------------------- */
+/* Focus writing (Ulysses Phase A): under a `[data-focus-writing]` ancestor   */
+/* (the workspace's wysiwyg pane), every top-level block dims except the one  */
+/* owning the selection (`.wb-fw-active`, set by the workspace) — paragraph   */
+/* focus. Hover un-dims for mouse repositioning. Token-driven, motion-safe.   */
+/* ------------------------------------------------------------------------- */
+[data-focus-writing] .milkdown-host .ProseMirror > * {
+  opacity: 0.35;
+  transition: opacity var(--t-base, 200ms) var(--ease-standard, ease);
+}
+[data-focus-writing] .milkdown-host .ProseMirror > .wb-fw-active,
+[data-focus-writing] .milkdown-host .ProseMirror > *:hover {
+  opacity: 1;
+}
+@media (prefers-reduced-motion: reduce) {
+  [data-focus-writing] .milkdown-host .ProseMirror > * {
+    transition: none;
+  }
+}

package/src/markdown-editor/markdown-editor.directives.test.tsx

@@ -0,0 +1,105 @@
+import { createRef } from "react";
+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { afterEach, expect, test } from "vitest";
+
+import { MarkdownEditor, type MarkdownEditorHandle } from "./markdown-editor";
+
+afterEach(cleanup);
+
+const DOC = `# Heading
+
+:::card{title="Objective"}
+
+card body text
+
+:::
+
+::metric{label="Scope" value="1,245" description="reports"}
+`;
+
+test("parses :::card + ::metric into branded editor chrome", async () => {
+  const { container } = render(<MarkdownEditor defaultValue={DOC} />);
+  await waitFor(() => {
+    expect(container.querySelector(".brand-directive--card")).toBeTruthy();
+    expect(container.querySelector(".brand-directive--metric")).toBeTruthy();
+  });
+});
+
+test("round-trips directives back to markdown (parse → serialize)", async () => {
+  const ref = createRef<MarkdownEditorHandle>();
+  const { container } = render(<MarkdownEditor ref={ref} defaultValue={DOC} />);
+  // Wait until the editor has mounted + rendered the directive node.
+  await waitFor(() => expect(container.querySelector(".brand-directive--card")).toBeTruthy());
+
+  const md = ref.current!.getMarkdown();
+  expect(md).toContain(":::card");
+  expect(md).toContain("card body text");
+  expect(md).toContain("::metric");
+  expect(md).toContain("Scope");
+});
+
+test("renders directives as live @brand components with inline-editable attributes", async () => {
+  render(<MarkdownEditor defaultValue={DOC} />);
+  // The node-views expose the directive title + metric label/value as editable
+  // textboxes — an affordance the old toDOM chrome did not have.
+  await waitFor(() => expect(screen.getByRole("textbox", { name: "Card title" })).toBeTruthy());
+  expect(screen.getByRole("textbox", { name: "Metric label" })).toBeTruthy();
+
+  const value = screen.getByRole("textbox", { name: "Metric value" });
+  expect(value).toBeTruthy();
+  expect(value.textContent).toBe("1,245");
+});
+
+test("committing an inline edit writes through to the markdown attributes", async () => {
+  const ref = createRef<MarkdownEditorHandle>();
+  render(<MarkdownEditor ref={ref} defaultValue={DOC} />);
+
+  const value = await screen.findByRole("textbox", { name: "Metric value" });
+
+  // Edit the metric value inline, then commit on blur.
+  value.focus();
+  value.textContent = "9,999";
+  fireEvent.blur(value);
+
+  await waitFor(() => expect(ref.current!.getMarkdown()).toContain('value="9,999"'));
+  // The untouched attributes survive the write-through.
+  const md = ref.current!.getMarkdown();
+  expect(md).toContain('label="Scope"');
+  expect(md).not.toContain('value="1,245"');
+});
+
+test("#21 — the editable surface has an accessible name (default + override)", async () => {
+  const { unmount } = render(<MarkdownEditor defaultValue={DOC} />);
+  await waitFor(() =>
+    expect(screen.getByRole("textbox", { name: "Markdown editor" })).toBeTruthy(),
+  );
+  unmount();
+
+  render(<MarkdownEditor defaultValue={DOC} ariaLabel="Notes" />);
+  await waitFor(() => expect(screen.getByRole("textbox", { name: "Notes" })).toBeTruthy());
+});
+
+test("#37 — inline-edit textboxes declare single-line (aria-multiline=false)", async () => {
+  render(<MarkdownEditor defaultValue={DOC} />);
+  const label = await screen.findByRole("textbox", { name: "Metric label" });
+  expect(label).toHaveAttribute("aria-multiline", "false");
+});
+
+test("#21/#37 — a :::callout title is NOT a heading inside the WYSIWYG flow", async () => {
+  const { container } = render(
+    <MarkdownEditor
+      defaultValue={`# Doc\n\n:::callout{type="warning" title="Heads up"}\n\nbody\n\n:::`}
+    />,
+  );
+  await waitFor(() => expect(container.querySelector(".brand-directive--callout")).toBeTruthy());
+  // The callout title is present as an editable textbox, but not a heading.
+  expect(screen.getByRole("textbox", { name: "Callout title" })).toBeTruthy();
+  expect(screen.queryByRole("heading", { name: "Heads up" })).toBeNull();
+});
+
+test("#37 — an unknown container directive is role=note, not an assertive alert", async () => {
+  render(<MarkdownEditor defaultValue={`:::mystery\n\nbody\n\n:::`} />);
+  await waitFor(() => expect(screen.getByRole("note")).toBeTruthy());
+  // It must NOT be an assertive live region (role=alert) that re-announces on re-parse.
+  expect(screen.queryByRole("alert")).toBeNull();
+});

package/src/markdown-editor/markdown-editor.fill.test.ts

@@ -0,0 +1,34 @@
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+// Read the stylesheet as text. The repo runs vitest per-package (turbo /
+// `--filter`), so cwd is the package root — `src/...` resolves deterministically.
+const css = readFileSync(resolve(process.cwd(), "src/markdown-editor/markdown-editor.css"), "utf8");
+
+/**
+ * The editor's fill-height behavior lives in CSS (`markdown-editor.css`), which
+ * jsdom does not lay out — so a render test can't observe it. Lock the rules
+ * deterministically instead: assert the stylesheet still declares the flex-fill
+ * chain that makes the editable grow to fill a definite-height parent. The
+ * regression this guards is the editable staying content-sized (`min-height:
+ * 9rem`) inside a tall pane, which also clips the caret-anchored `/` slash menu.
+ * The real visual proof is the `FillsContainer` Storybook story.
+ * (elabs-components: editor-fill-height)
+ */
+
+describe("editor fill-height CSS (regression)", () => {
+  it("makes .milkdown-host a column flex that fills its parent", () => {
+    expect(css).toMatch(/\.milkdown-host\s*\{[^}]*display:\s*flex/);
+    expect(css).toMatch(/\.milkdown-host\s*\{[^}]*flex-direction:\s*column/);
+    expect(css).toMatch(/\.milkdown-host\s*\{[^}]*min-height:\s*100%/);
+  });
+
+  it("lets the Milkdown wrapper grow inside the host", () => {
+    expect(css).toMatch(/\.milkdown-host\s+\.milkdown[^{]*\{[^}]*flex:\s*1 1 auto/);
+  });
+
+  it("lets the ProseMirror editing surface grow", () => {
+    expect(css).toMatch(/\.milkdown-host\s+\.ProseMirror\.editor\s*\{[^}]*flex:\s*1 1 auto/);
+  });
+});