@surrealdb/ui 1.1.1 → 1.2.1

package/tests/e2e/MarkdownEditor/link-placeholder.test.tsx

@@ -0,0 +1,67 @@
+import { EditorSelection } from "@codemirror/state";
+import { MantineProvider, Paper, v8CssVariablesResolver } from "@mantine/core";
+import { setMarkdownEditorFocused } from "@src/lib/markdown/editor/decorations/editor-focus";
+import { MarkdownEditor } from "@src/primitives/MarkdownEditor";
+import { MANTINE_THEME } from "@src/theme/mantine";
+import { describe, expect, it } from "vitest";
+import { getEditorView, mountStory, nextFrame } from "../../_setup/e2e-helpers";
+
+function shell(doc: string) {
+    return (
+        <MantineProvider
+            theme={MANTINE_THEME}
+            cssVariablesResolver={v8CssVariablesResolver}
+            forceColorScheme="dark"
+        >
+            <Paper p="md">
+                <MarkdownEditor
+                    mode="preview"
+                    document={doc}
+                    autoFocus={false}
+                />
+            </Paper>
+        </MantineProvider>
+    );
+}
+
+async function caretAt(doc: string, index: number) {
+    mountStory(shell(doc));
+    const view = await getEditorView();
+    view.focus();
+    view.dispatch({
+        selection: EditorSelection.cursor(index),
+        effects: setMarkdownEditorFocused.of(true),
+    });
+    await nextFrame();
+    await nextFrame();
+    return view;
+}
+
+describe("MarkdownEditor / link placeholders", () => {
+    it("shows an 'alt text' placeholder for an empty link label", async () => {
+        const doc = "[](https://surrealdb.com)";
+        await caretAt(doc, 1); // caret between the empty []
+        expect(document.querySelector(".cm-content")?.textContent).toContain("alt text");
+    });
+
+    it("shows a 'link' placeholder for an empty link destination", async () => {
+        const doc = "[label]()";
+        await caretAt(doc, doc.indexOf("(") + 1); // caret between the empty ()
+        const text = document.querySelector(".cm-content")?.textContent ?? "";
+        expect(text).toContain("link");
+    });
+
+    it("shows both placeholders for a fully empty link", async () => {
+        const doc = "[]()";
+        await caretAt(doc, 1);
+        const text = document.querySelector(".cm-content")?.textContent ?? "";
+        expect(text).toContain("alt text");
+        expect(text).toContain("link");
+    });
+
+    it("does not show placeholders once the sections have content", async () => {
+        const doc = "[label](https://surrealdb.com)";
+        await caretAt(doc, 3);
+        expect(document.querySelector(".cm-content")?.textContent).not.toContain("alt text");
+    });
+});

package/tests/e2e/MarkdownEditor/media-align.test.tsx

@@ -0,0 +1,57 @@
+import { EditorSelection } from "@codemirror/state";
+import { MantineProvider, Paper, v8CssVariablesResolver } from "@mantine/core";
+import { setMarkdownEditorFocused } from "@src/lib/markdown/editor/decorations/editor-focus";
+import { MarkdownEditor } from "@src/primitives/MarkdownEditor";
+import { MANTINE_THEME } from "@src/theme/mantine";
+import { describe, expect, it } from "vitest";
+import { getEditorView, mountStory, nextFrame, sleep } from "../../_setup/e2e-helpers";
+
+const DOC =
+    "Regular paragraph line.\n\n![Some alt text](https://surrealdb.com/static/logo/light.svg)\n\nAnother paragraph.\n";
+
+/** Left edge of a line's rendered text content (text nodes have no element box). */
+function textLeft(line: HTMLElement): number {
+    const range = document.createRange();
+    range.selectNodeContents(line);
+    return range.getBoundingClientRect().left;
+}
+
+describe("MarkdownEditor / media alignment", () => {
+    it("aligns the image preview's left edge with regular text", async () => {
+        mountStory(
+            <MantineProvider
+                theme={MANTINE_THEME}
+                cssVariablesResolver={v8CssVariablesResolver}
+                forceColorScheme="dark"
+            >
+                <Paper p="md">
+                    <MarkdownEditor
+                        mode="preview"
+                        document={DOC}
+                        autoFocus={false}
+                    />
+                </Paper>
+            </MantineProvider>,
+        );
+        const view = await getEditorView();
+        view.focus();
+        view.dispatch({
+            selection: EditorSelection.cursor(view.state.doc.length),
+            effects: setMarkdownEditorFocused.of(true),
+        });
+        await sleep(200);
+        await nextFrame();
+
+        const para = Array.from(document.querySelectorAll<HTMLElement>(".cm-line")).find((l) =>
+            (l.textContent ?? "").includes("Regular"),
+        );
+        const img = document.querySelector<HTMLElement>('[data-md-widget="ImageWidget"] img');
+        expect(para).toBeTruthy();
+        expect(img).toBeTruthy();
+
+        const paraLeft = textLeft(para as HTMLElement);
+        const imageLeft = (img as HTMLElement).getBoundingClientRect().left;
+        // Within a pixel of the text inset (previously 6px to the left).
+        expect(Math.abs(imageLeft - paraLeft)).toBeLessThanOrEqual(1.5);
+    });
+});

package/tests/e2e/MarkdownEditor/media-edit.test.tsx

@@ -0,0 +1,63 @@
+import { EditorSelection } from "@codemirror/state";
+import { MantineProvider, Paper, v8CssVariablesResolver } from "@mantine/core";
+import { setMarkdownEditorFocused } from "@src/lib/markdown/editor/decorations/editor-focus";
+import { MarkdownEditor } from "@src/primitives/MarkdownEditor";
+import { MANTINE_THEME } from "@src/theme/mantine";
+import { describe, expect, it } from "vitest";
+import { getEditorView, mountStory, nextFrame, sleep } from "../../_setup/e2e-helpers";
+
+const IMAGE_DOC = "![A logo](https://surrealdb.com/static/logo/light.svg)\n\nParagraph after.\n";
+
+function shell(doc: string) {
+    return (
+        <MantineProvider
+            theme={MANTINE_THEME}
+            cssVariablesResolver={v8CssVariablesResolver}
+            forceColorScheme="dark"
+        >
+            <Paper
+                p="md"
+                withBorder
+            >
+                <MarkdownEditor
+                    mode="preview"
+                    document={doc}
+                    autoFocus={false}
+                />
+            </Paper>
+        </MantineProvider>
+    );
+}
+
+describe("MarkdownEditor / media edit action", () => {
+    it("shows an image preview with an edit-source action that reveals the source", async () => {
+        mountStory(shell(IMAGE_DOC));
+        const view = await getEditorView();
+
+        // Focused, with the caret away from the image, so the image renders as a
+        // preview widget rather than raw source.
+        view.focus();
+        view.dispatch({
+            selection: EditorSelection.cursor(view.state.doc.length),
+            effects: setMarkdownEditorFocused.of(true),
+        });
+        await nextFrame();
+        await nextFrame();
+
+        expect(document.querySelector(".cm-content")?.textContent).not.toContain("![A logo]");
+        expect(document.querySelector("img")).not.toBeNull();
+
+        const action = document.querySelector<HTMLButtonElement>(
+            'button[aria-label="Edit source"]',
+        );
+        expect(action).not.toBeNull();
+
+        action?.dispatchEvent(new MouseEvent("mousedown", { bubbles: true, button: 0 }));
+        await sleep(120);
+        await nextFrame();
+
+        // The image markdown source becomes visible and is selected.
+        expect(document.querySelector(".cm-content")?.textContent).toContain("![A logo]");
+        expect(view.state.selection.main.empty).toBe(false);
+    });
+});

package/tests/e2e/MarkdownEditor/media-sizing.test.tsx

@@ -0,0 +1,123 @@
+import { EditorSelection } from "@codemirror/state";
+import { EditorView } from "@codemirror/view";
+import * as MarkdownStories from "@src/stories/playground/Markdown.stories";
+import { composeStories } from "@storybook/react-vite";
+import { describe, expect, it } from "vitest";
+import {
+    mountStory,
+    nextFrame,
+    preparePreviewEditor,
+    scrollEditorTo,
+} from "../../_setup/e2e-helpers";
+import { md, mdViewer } from "../../_setup/markdown-classes";
+
+const Stories = composeStories(MarkdownStories);
+
+function findLineStart(doc: string, prefix: string): number {
+    const idx = doc.indexOf(prefix);
+    if (idx < 0) throw new Error(`prefix not found in doc: ${prefix}`);
+    return idx;
+}
+
+describe("MarkdownEditor / media sizing", () => {
+    it("images and videos do not exceed the editor content width", async () => {
+        mountStory(<Stories.Editor />);
+        const view = await preparePreviewEditor();
+
+        const docStr = view.state.doc.toString();
+        const imageLine = findLineStart(docStr, "![SurrealDB logo]");
+        const videoLine = findLineStart(docStr, "![Product demo]");
+
+        // Caret away from media lines so replace widgets render.
+        view.dispatch({ selection: EditorSelection.cursor(0) });
+        await scrollEditorTo(view, imageLine);
+        await nextFrame();
+
+        const scroller = view.scrollDOM;
+        const scrollerWidth = scroller.clientWidth;
+        expect(scrollerWidth).toBeGreaterThan(0);
+
+        let imgs: NodeListOf<HTMLImageElement> = document.querySelectorAll(
+            `.cm-editor [data-md-widget="ImageWidget"] img, .cm-editor .${md.image}`,
+        );
+        for (let i = 0; i < 40 && imgs.length === 0; i++) {
+            await nextFrame();
+            imgs = document.querySelectorAll(
+                `.cm-editor [data-md-widget="ImageWidget"] img, .cm-editor .${md.image}`,
+            );
+        }
+
+        expect(imgs.length).toBeGreaterThan(0);
+        for (const img of Array.from(imgs)) {
+            const rect = img.getBoundingClientRect();
+            expect(
+                rect.width,
+                `image ${img.src} width ${rect.width} vs scroller ${scrollerWidth}`,
+            ).toBeLessThanOrEqual(scrollerWidth + 2);
+        }
+
+        await scrollEditorTo(view, videoLine);
+        await nextFrame();
+
+        let videos: NodeListOf<HTMLElement> = document.querySelectorAll(
+            `.cm-editor [data-md-widget="VideoWidget"] video, .cm-editor [data-md-widget="VideoWidget"] .${md.image}`,
+        );
+        for (let i = 0; i < 40 && videos.length === 0; i++) {
+            await nextFrame();
+            videos = document.querySelectorAll(
+                `.cm-editor [data-md-widget="VideoWidget"] video, .cm-editor [data-md-widget="VideoWidget"] .${md.image}`,
+            );
+        }
+
+        expect(videos.length).toBeGreaterThan(0);
+        for (const video of Array.from(videos)) {
+            const host =
+                video.closest("[data-md-widget='VideoWidget']") ?? video.closest(`.${md.image}`);
+            const rect = (host ?? video).getBoundingClientRect();
+            expect(
+                rect.width,
+                `video width ${rect.width} vs scroller ${scrollerWidth}`,
+            ).toBeLessThanOrEqual(scrollerWidth + 2);
+        }
+    });
+
+    it("matches MarkdownViewer image width in the split playground", async () => {
+        mountStory(<Stories.SideBySide />);
+        const view = await preparePreviewEditor();
+
+        const docStr = view.state.doc.toString();
+        const imagePos = findLineStart(docStr, "![SurrealDB logo]");
+        view.dispatch({
+            selection: EditorSelection.cursor(0),
+            effects: EditorView.scrollIntoView(imagePos, { y: "center" }),
+        });
+        await nextFrame();
+
+        let editorImg: HTMLImageElement | null = null;
+        let viewerImg: HTMLImageElement | null = null;
+        let editorW = 0;
+        let viewerW = 0;
+
+        for (let i = 0; i < 40; i++) {
+            editorImg = document.querySelector<HTMLImageElement>(
+                `.cm-editor [data-md-widget="ImageWidget"] img`,
+            );
+            viewerImg = document.querySelector<HTMLImageElement>(
+                `.${mdViewer.viewerRoot} img.${md.image}`,
+            );
+            if (editorImg && viewerImg) {
+                editorW = editorImg.getBoundingClientRect().width;
+                viewerW = viewerImg.getBoundingClientRect().width;
+                if (editorW > 0 && viewerW > 0 && Math.abs(editorW - viewerW) <= 12) {
+                    break;
+                }
+            }
+            await nextFrame();
+        }
+
+        expect(editorImg).not.toBeNull();
+        expect(viewerImg).not.toBeNull();
+        // Editor `.cm-line` uses 6px inline padding mirrored in viewer.module.scss.
+        expect(Math.abs(editorW - viewerW)).toBeLessThanOrEqual(12);
+    });
+});

package/tests/e2e/MarkdownEditor/modes.test.tsx

@@ -0,0 +1,93 @@
+import { EditorSelection } from "@codemirror/state";
+import * as MarkdownStories from "@src/stories/playground/Markdown.stories";
+import { composeStories } from "@storybook/react-vite";
+import { describe, expect, it } from "vitest";
+import {
+    getEditorView,
+    mountStory,
+    nextFrame,
+    page,
+    readDoc,
+    userEvent,
+} from "../../_setup/e2e-helpers";
+import { md, mdViewer } from "../../_setup/markdown-classes";
+
+const Stories = composeStories(MarkdownStories);
+
+async function getMode(): Promise<string | null> {
+    const editor = document.querySelector<HTMLElement>(".cm-editor");
+    return editor?.getAttribute("data-markdown-mode") ?? null;
+}
+
+describe("MarkdownEditor / modes", () => {
+    it("toggling the SegmentedControl swaps mode without remounting the editor", async () => {
+        mountStory(<Stories.Editor />);
+        await getEditorView();
+
+        const initialEditor = document.querySelector(".cm-editor");
+        expect(initialEditor).not.toBeNull();
+        expect(await getMode()).toBe("preview");
+
+        // Mantine's SegmentedControl hides the underlying radio inputs and
+        // styles a sibling label, so we click the visible label text.
+        await userEvent.click(page.getByText("Source", { exact: true }));
+        await nextFrame();
+        expect(await getMode()).toBe("source");
+        expect(document.querySelector(".cm-editor")).toBe(initialEditor);
+
+        await userEvent.click(page.getByText("Preview", { exact: true }));
+        await nextFrame();
+        expect(await getMode()).toBe("preview");
+        expect(document.querySelector(".cm-editor")).toBe(initialEditor);
+    });
+
+    it("standalone MarkdownViewer is not a CodeMirror surface", async () => {
+        mountStory(<Stories.Viewer />);
+        await nextFrame();
+        await nextFrame();
+
+        expect(document.querySelector(`.${mdViewer.viewerRoot}`)).not.toBeNull();
+        expect(document.querySelector(".cm-editor")).toBeNull();
+        expect(document.querySelector(".cm-content")).toBeNull();
+    });
+
+    it("source mode renders raw markdown markers (no hidden marks)", async () => {
+        mountStory(<Stories.Editor />);
+        await getEditorView();
+        await userEvent.click(page.getByText("Source", { exact: true }));
+        await nextFrame();
+        await getEditorView();
+
+        await nextFrame();
+        const hidden = document.querySelectorAll(`.${md.markHidden}`);
+        expect(hidden.length).toBe(0);
+
+        const text = document.querySelector(".cm-content")?.textContent ?? "";
+        expect(text).toContain("# Welcome to the live preview editor");
+        expect(text).toContain("**bold**");
+    });
+
+    it("keeps edits when cycling Source then Preview after a document change", async () => {
+        mountStory(<Stories.Editor />);
+        const view = await getEditorView();
+
+        const token = `\nuniq-e2e-${Date.now()}`;
+        view.dispatch({
+            selection: EditorSelection.cursor(view.state.doc.length),
+            changes: { from: view.state.doc.length, insert: token },
+        });
+        await nextFrame();
+
+        await userEvent.click(page.getByText("Source", { exact: true }));
+        await nextFrame();
+        expect((await readDoc()).includes(token.trim())).toBe(true);
+
+        await userEvent.click(page.getByText("Preview", { exact: true }));
+        await nextFrame();
+
+        expect((await readDoc()).includes(token.trim())).toBe(true);
+        expect(document.querySelector(".cm-content")?.getAttribute("aria-readonly")).not.toBe(
+            "true",
+        );
+    });
+});

package/tests/e2e/MarkdownEditor/regressions.test.tsx

@@ -0,0 +1,182 @@
+import { EditorSelection } from "@codemirror/state";
+import { MantineProvider, v8CssVariablesResolver } from "@mantine/core";
+import { MarkdownEditor } from "@src/primitives/MarkdownEditor";
+import * as MarkdownStories from "@src/stories/playground/Markdown.stories";
+import { MANTINE_THEME } from "@src/theme/mantine";
+import { composeStories } from "@storybook/react-vite";
+import { type ReactElement, useState } from "react";
+import { describe, expect, it } from "vitest";
+import {
+    mountStory,
+    nextFrame,
+    preparePreviewEditor,
+    scrollEditorTo,
+    userEvent,
+} from "../../_setup/e2e-helpers";
+
+const Stories = composeStories(MarkdownStories);
+
+function getCheckboxes(): HTMLElement[] {
+    return Array.from(document.querySelectorAll<HTMLElement>("[data-md-task-marker]"));
+}
+
+const SCROLL_FIXTURE = `# Scroll fixture
+
+${Array.from({ length: 80 }, (_, i) => `Line ${i + 1} of fixture content.`).join("\n")}
+`;
+
+function ScrollFixture(): ReactElement {
+    const [doc, setDoc] = useState(SCROLL_FIXTURE);
+    // Mounting the primitive directly here means we have to provide our own
+    // MantineProvider; portable-stories decorators do not apply to ad-hoc JSX.
+    return (
+        <MantineProvider
+            theme={MANTINE_THEME}
+            cssVariablesResolver={v8CssVariablesResolver}
+            forceColorScheme="dark"
+        >
+            <div style={{ height: 240, overflow: "hidden" }}>
+                <MarkdownEditor
+                    mode="preview"
+                    document={doc}
+                    onChangeDocument={setDoc}
+                    style={{ height: "100%" }}
+                />
+            </div>
+        </MantineProvider>
+    );
+}
+
+describe("MarkdownEditor / regressions", () => {
+    it("task checkbox toggles between checked and unchecked in the source document", async () => {
+        mountStory(<Stories.Editor />);
+        const view = await preparePreviewEditor();
+        const taskPos = view.state.doc.toString().indexOf("- [ ] Read the docs");
+
+        // Park caret outside the task list so checkbox widgets render for every item
+        // (preview mode only swaps to raw `[…]` when the selection hits the marker).
+        view.dispatch({ selection: EditorSelection.cursor(0) });
+        await scrollEditorTo(view, taskPos);
+        await nextFrame();
+
+        const initialDoc = view.state.doc.toString();
+        expect(initialDoc).toContain("- [ ] Read the docs");
+        expect(initialDoc).toContain("- [x] Star the repo");
+
+        let first: HTMLElement | undefined;
+        for (let i = 0; i < 40; i++) {
+            [first] = getCheckboxes();
+            if (first) break;
+            await nextFrame();
+        }
+        expect(first).toBeDefined();
+        if (!first) throw new Error("no task marker rendered");
+
+        await userEvent.click(first);
+        await nextFrame();
+        await nextFrame();
+
+        expect(view.state.doc.toString()).toContain("- [x] Read the docs");
+        expect(view.state.doc.toString()).not.toContain("- [ ] Read the docs");
+
+        // Toggle again — single mousedown handler, no double-toggle on click.
+        const [firstAgain] = getCheckboxes();
+        if (!firstAgain) throw new Error("task marker disappeared after toggle");
+        await userEvent.click(firstAgain);
+        await nextFrame();
+        await nextFrame();
+        expect(view.state.doc.toString()).toContain("- [ ] Read the docs");
+    });
+
+    it("repeated checkbox toggles do not duplicate or drift task markers", async () => {
+        mountStory(<Stories.Editor />);
+        const view = await preparePreviewEditor();
+        const taskPos = view.state.doc.toString().indexOf("- [ ] Read the docs");
+
+        view.dispatch({ selection: EditorSelection.cursor(0) });
+        await scrollEditorTo(view, taskPos);
+        await nextFrame();
+
+        const baselineCount = (view.state.doc.toString().match(/- \[[ x]\] /g) ?? []).length;
+        expect(baselineCount).toBeGreaterThanOrEqual(3);
+
+        let markers = getCheckboxes();
+        for (let i = 0; i < 40 && markers.length < 2; i++) {
+            await nextFrame();
+            markers = getCheckboxes();
+        }
+
+        for (let i = 0; i < 6; i++) {
+            markers = getCheckboxes();
+            const target = markers[1];
+            if (!target) throw new Error("task marker missing during loop");
+            await userEvent.click(target);
+            await nextFrame();
+            await nextFrame();
+        }
+
+        const finalDoc = view.state.doc.toString();
+        const finalCount = (finalDoc.match(/- \[[ x]\] /g) ?? []).length;
+        expect(finalCount).toBe(baselineCount);
+        // Star the repo started as `[x]`, so 6 toggles → still `[x]`.
+        expect(finalDoc).toContain("- [x] Star the repo");
+    });
+
+    it("toggle via checkbox preserves task marker widgets visible from the previous caret position", async () => {
+        mountStory(<Stories.Editor />);
+        const view = await preparePreviewEditor();
+        const taskPos = view.state.doc.toString().indexOf("- [ ] Read the docs");
+
+        view.dispatch({ selection: EditorSelection.cursor(0) });
+        await scrollEditorTo(view, taskPos);
+        view.contentDOM.blur();
+        await nextFrame();
+
+        let initialMarkers = 0;
+        for (let i = 0; i < 40; i++) {
+            initialMarkers = getCheckboxes().length;
+            if (initialMarkers >= 3) break;
+            await nextFrame();
+        }
+        expect(initialMarkers).toBeGreaterThanOrEqual(3);
+
+        const [marker] = getCheckboxes();
+        if (!marker) throw new Error("no task marker");
+        await userEvent.click(marker);
+        await nextFrame();
+        await nextFrame();
+
+        // If the click had dropped the checkbox widget for that line, the count
+        // would fall (caret would need to sit on the task marker for that).
+        const afterMarkers = getCheckboxes().length;
+        expect(afterMarkers).toBe(initialMarkers);
+    });
+
+    it("scroll position is preserved when an out-of-view edit is dispatched", async () => {
+        mountStory(<ScrollFixture />);
+        const view = await preparePreviewEditor();
+        const scroller = document.querySelector<HTMLElement>(".cm-scroller");
+        if (!scroller) throw new Error("no .cm-scroller in mounted story");
+
+        // Wait for layout to settle before measuring scroll height.
+        await nextFrame();
+        await nextFrame();
+        expect(scroller.scrollHeight).toBeGreaterThan(scroller.clientHeight);
+
+        scroller.scrollTop = 200;
+        await nextFrame();
+        const scrollBefore = scroller.scrollTop;
+        expect(scrollBefore).toBeGreaterThan(0);
+
+        // Insert at offset 5 (well above the current viewport) without
+        // moving the selection. The regression was: ANY content change
+        // reset `.cm-scroller` scrollTop to 0. The fix preserves scroll
+        // unless the dispatch explicitly requests a scrollIntoView.
+        view.dispatch({ changes: { from: 5, insert: "X" } });
+        await nextFrame();
+        await nextFrame();
+
+        expect(Math.abs(scroller.scrollTop - scrollBefore)).toBeLessThan(20);
+        expect(scroller.scrollTop).toBeGreaterThan(0);
+    });
+});

package/tests/e2e/MarkdownEditor/slash-commands.test.tsx

@@ -0,0 +1,99 @@
+import { EditorSelection } from "@codemirror/state";
+import * as MarkdownStories from "@src/stories/playground/Markdown.stories";
+import { composeStories } from "@storybook/react-vite";
+import { describe, expect, it } from "vitest";
+import {
+    focusAndType,
+    getEditorView,
+    mountStory,
+    nextFrame,
+    readDoc,
+    sleep,
+    typeText,
+} from "../../_setup/e2e-helpers";
+
+const Stories = composeStories(MarkdownStories);
+
+/** Query the visible slash menu's command items (rendered in a portal). */
+function menuItems(): HTMLElement[] {
+    return Array.from(document.querySelectorAll<HTMLElement>("[data-navigation-item-id]"));
+}
+
+/** Move the caret to a fresh empty line at the end of the document. */
+async function caretOnFreshLine() {
+    const view = await getEditorView();
+    view.focus();
+    const end = view.state.doc.length;
+    view.dispatch({
+        changes: { from: end, insert: "\n\n" },
+        selection: EditorSelection.cursor(end + 2),
+        scrollIntoView: true,
+    });
+    await nextFrame();
+    await nextFrame();
+    return view;
+}
+
+describe("MarkdownEditor / slash commands", () => {
+    it("opens a filtered, keyboard-navigable menu and inserts boilerplate on Enter", async () => {
+        mountStory(<Stories.Editor />);
+        await caretOnFreshLine();
+
+        await focusAndType("/head");
+        await sleep(50);
+
+        const items = menuItems();
+        expect(items.length).toBeGreaterThan(0);
+        // Filtering by "head" should only surface heading commands.
+        expect(items.every((el) => el.dataset.navigationItemId?.startsWith("heading"))).toBe(true);
+
+        // Navigate to the second heading and select it.
+        await typeText("{ArrowDown}");
+        await sleep(20);
+        await typeText("{Enter}");
+        await sleep(50);
+
+        const doc = await readDoc();
+        // The "/head" text is replaced by a heading prefix; no stray newline.
+        expect(doc).toContain("## ");
+        expect(doc).not.toContain("/head");
+        expect(menuItems().length).toBe(0);
+    });
+
+    it("dismisses on Escape and leaves the slash as literal text", async () => {
+        mountStory(<Stories.Editor />);
+        await caretOnFreshLine();
+
+        await focusAndType("/quote");
+        await sleep(50);
+        expect(menuItems().length).toBeGreaterThan(0);
+
+        await typeText("{Escape}");
+        await sleep(50);
+
+        expect(menuItems().length).toBe(0);
+        const doc = await readDoc();
+        expect(doc).toContain("/quote");
+    });
+
+    it("highlights the slash and shows an Enter command placeholder until text is typed", async () => {
+        mountStory(<Stories.Editor />);
+        await caretOnFreshLine();
+
+        await focusAndType("/");
+        await sleep(50);
+
+        const highlight = document.querySelector(".cm-md-slash-active");
+        expect(highlight).not.toBeNull();
+        const placeholder = document.querySelector(".cm-md-slash-placeholder");
+        expect(placeholder?.textContent).toBe("Type to search");
+
+        // Typing the query removes the placeholder but keeps the highlight.
+        await typeText("head");
+        await sleep(50);
+
+        expect(document.querySelector(".cm-md-slash-placeholder")).toBeNull();
+        const stillHighlighted = document.querySelector(".cm-md-slash-active");
+        expect(stillHighlighted?.textContent).toBe("/head");
+    });
+});