@elabs-ai/components-editor 4.0.0

package/src/markdown-editor/slash/monaco-slash-menu.test.tsx

@@ -0,0 +1,198 @@
+/**
+ * Unit tests for `MonacoSlashMenu`'s run-only command selection (#299) —
+ * `runInSource` appears alongside `snippet` in the source-pane menu, wins over
+ * `snippet` when both select paths fire (Enter/Tab AND click), strips the
+ * typed `/query` trigger first, and a snippet-only command is unaffected.
+ *
+ * Monaco can't render in jsdom, so `monaco-editor` is mocked (the
+ * `markdown-workspace.test.tsx` precedent) and a hand-built editor object
+ * stands in for `MonacoCodeEditor` (the `editor-content-access.test.ts`
+ * precedent) — `MonacoSlashMenu` only calls a handful of methods on it.
+ */
+import { fireEvent, render, screen } from "@testing-library/react";
+import type { IRange } from "monaco-editor";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("monaco-editor", () => ({
+  Selection: class {},
+  Range: class {},
+}));
+
+import { MonacoSlashMenu } from "./monaco-slash-menu";
+import type { SlashCommand } from "./brand-slash-commands";
+
+function makeEditor() {
+  const domNode = document.createElement("div");
+  return {
+    getPosition: vi.fn(() => ({ lineNumber: 1, column: 5 })),
+    getScrolledVisiblePosition: vi.fn(() => ({ top: 20, left: 10, height: 20 })),
+    getDomNode: vi.fn(() => domNode),
+    onDidScrollChange: vi.fn(() => ({ dispose: vi.fn() })),
+    onDidChangeCursorPosition: vi.fn(() => ({ dispose: vi.fn() })),
+    onDidBlurEditorText: vi.fn(() => ({ dispose: vi.fn() })),
+    executeEdits: vi.fn(),
+    getModel: vi.fn(() => ({ getValue: vi.fn(() => ""), getValueInRange: vi.fn(() => "") })),
+    getSelection: vi.fn(() => null),
+    focus: vi.fn(),
+    domNode,
+  };
+}
+
+const triggerRange: IRange = {
+  startLineNumber: 1,
+  startColumn: 1,
+  endLineNumber: 1,
+  endColumn: 2,
+};
+
+afterEach(() => {
+  vi.clearAllMocks();
+});
+
+describe("MonacoSlashMenu — run-only commands (#299)", () => {
+  it("renders a run-only command (no snippet) alongside snippet commands", () => {
+    const editor = makeEditor();
+    const runOnly: SlashCommand = {
+      id: "ask-ai",
+      label: "Ask AI",
+      run: () => {},
+      runInSource: vi.fn(),
+    };
+    render(
+      <MonacoSlashMenu
+        editor={editor as never}
+        commands={[runOnly]}
+        open
+        onOpenChange={vi.fn()}
+        triggerRange={triggerRange}
+      />,
+    );
+    expect(screen.getByText("Ask AI")).toBeInTheDocument();
+  });
+
+  it("Enter strips the typed trigger, calls runInSource with editor+range+content, closes, and refocuses", () => {
+    const editor = makeEditor();
+    const runInSource = vi.fn();
+    const runOnly: SlashCommand = { id: "ask-ai", label: "Ask AI", run: () => {}, runInSource };
+    const onOpenChange = vi.fn();
+    render(
+      <MonacoSlashMenu
+        editor={editor as never}
+        commands={[runOnly]}
+        open
+        onOpenChange={onOpenChange}
+        triggerRange={triggerRange}
+      />,
+    );
+
+    fireEvent.keyDown(editor.domNode, { key: "Enter" });
+
+    // The `/query` trigger is stripped BEFORE runInSource fires.
+    expect(editor.executeEdits).toHaveBeenCalledWith("brand-slash-typed", [
+      { range: triggerRange, text: "" },
+    ]);
+    expect(runInSource).toHaveBeenCalledTimes(1);
+    const ctx = runInSource.mock.calls[0]?.[0];
+    expect(ctx?.editor).toBe(editor);
+    expect(ctx?.range).toBe(triggerRange);
+    expect(typeof ctx?.content.getText).toBe("function");
+    expect(onOpenChange).toHaveBeenCalledWith(false);
+    expect(editor.focus).toHaveBeenCalledTimes(1);
+  });
+
+  it("clicking the option (the mouse path) calls runInSource identically to Enter", () => {
+    const editor = makeEditor();
+    const runInSource = vi.fn();
+    const runOnly: SlashCommand = { id: "ask-ai", label: "Ask AI", run: () => {}, runInSource };
+    render(
+      <MonacoSlashMenu
+        editor={editor as never}
+        commands={[runOnly]}
+        open
+        onOpenChange={vi.fn()}
+        triggerRange={triggerRange}
+      />,
+    );
+
+    fireEvent.mouseDown(screen.getByText("Ask AI"));
+
+    expect(editor.executeEdits).toHaveBeenCalledWith("brand-slash-typed", [
+      { range: triggerRange, text: "" },
+    ]);
+    expect(runInSource).toHaveBeenCalledTimes(1);
+  });
+
+  it("on the hotkey path (no triggerRange), runInSource still fires with range: null and nothing is stripped", () => {
+    const editor = makeEditor();
+    const runInSource = vi.fn();
+    const runOnly: SlashCommand = { id: "ask-ai", label: "Ask AI", run: () => {}, runInSource };
+    render(
+      <MonacoSlashMenu
+        editor={editor as never}
+        commands={[runOnly]}
+        open
+        onOpenChange={vi.fn()}
+        triggerRange={null}
+      />,
+    );
+
+    fireEvent.keyDown(editor.domNode, { key: "Enter" });
+
+    expect(editor.executeEdits).not.toHaveBeenCalled();
+    expect(runInSource).toHaveBeenCalledTimes(1);
+    expect(runInSource.mock.calls[0]?.[0]?.range).toBeNull();
+  });
+
+  it("a snippet-only command is unaffected — Enter still inserts the snippet via executeEdits", () => {
+    const editor = makeEditor();
+    const snippetOnly: SlashCommand = {
+      id: "brand-card",
+      label: "Card",
+      snippet: ":::card\ntext\n:::",
+      run: () => {},
+    };
+    render(
+      <MonacoSlashMenu
+        editor={editor as never}
+        commands={[snippetOnly]}
+        open
+        onOpenChange={vi.fn()}
+        triggerRange={triggerRange}
+      />,
+    );
+
+    fireEvent.keyDown(editor.domNode, { key: "Enter" });
+
+    expect(editor.executeEdits).toHaveBeenCalledWith("brand-slash-typed", [
+      { range: triggerRange, text: ":::card\ntext\n:::", forceMoveMarkers: true },
+    ]);
+  });
+
+  it("runInSource wins over snippet when a command carries both", () => {
+    const editor = makeEditor();
+    const runInSource = vi.fn();
+    const both: SlashCommand = {
+      id: "both",
+      label: "Both",
+      snippet: "should not be inserted",
+      run: () => {},
+      runInSource,
+    };
+    render(
+      <MonacoSlashMenu
+        editor={editor as never}
+        commands={[both]}
+        open
+        onOpenChange={vi.fn()}
+        triggerRange={triggerRange}
+      />,
+    );
+
+    fireEvent.keyDown(editor.domNode, { key: "Enter" });
+
+    expect(runInSource).toHaveBeenCalledTimes(1);
+    expect(editor.executeEdits).toHaveBeenCalledWith("brand-slash-typed", [
+      { range: triggerRange, text: "" },
+    ]);
+  });
+});

package/src/markdown-editor/slash/monaco-slash-menu.tsx

@@ -0,0 +1,356 @@
+"use client";
+
+/**
+ * MonacoSlashMenu — a caret-anchored slash command popup for the Monaco source
+ * pane (#271).
+ *
+ * The workspace owns the open/closed state (via a `CodeEditor` action keybinding
+ * registered through `CodeEditor.actions`). This component is the POSITIONING
+ * CONTROLLER + KEYBOARD HANDLER that wraps the shared `SlashMenu` body — it does
+ * NOT re-implement the listbox (no duplication, tokens only, same look as the
+ * WYSIWYG widget).
+ *
+ * a11y: the `SlashMenu` already provides `role="listbox"` / `role="option"` /
+ * `aria-selected`; this wrapper wires `aria-activedescendant` on the editor's
+ * textarea so AT can follow the active row. Esc closes and refocuses the editor.
+ */
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import type { IRange } from "monaco-editor";
+import { useEffect, useRef, useState } from "react";
+
+import type { MonacoCodeEditor } from "../../code-editor";
+import { monacoContentAccess } from "../../lib/editor-content-access";
+import { insertDirective } from "../../markdown-toolbar/markdown-commands";
+import { filterSlashCommands, type SlashCommand } from "./brand-slash-commands";
+import { SlashMenu, slashOptionId } from "./slash-menu";
+
+export interface MonacoSlashMenuProps {
+  /** The live Monaco editor instance (source pane). */
+  editor: MonacoCodeEditor;
+  /**
+   * Commands to show in the source pane — filtered by the workspace to
+   * `snippet != null || typeof runInSource === "function"` (#299): a command
+   * needs a text snippet, a source-pane handler, or both to appear here (a
+   * run-only WYSIWYG command with neither is Milkdown-only and stays excluded).
+   */
+  commands: SlashCommand[];
+  /** Controlled open state — the workspace toggles it via the Layer-1 action. */
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  /**
+   * Insert the selected snippet at the Monaco caret + refocus.
+   * Defaults to `insertDirective` from `markdown-commands.ts`.
+   */
+  onInsert?: (editor: MonacoCodeEditor, snippet: string) => void;
+  /**
+   * When the menu was opened by typing `/` (not the hotkey), the model range of
+   * that `/`. On select the `/` is REPLACED by the inserted block; on cancel
+   * (Escape / Backspace past the trigger) it is removed. `null`/omitted = the
+   * hotkey path, which inserts via `onInsert`/`insertDirective` and leaves the
+   * document otherwise untouched.
+   */
+  triggerRange?: IRange | null;
+  /** Merged onto the positioned popup container (the inline `position:fixed` anchor stays). */
+  className?: string;
+}
+
+const ID_PREFIX = "brand-monaco-slash";
+const LISTBOX_ID = `${ID_PREFIX}-listbox`;
+
+/** Fixed/absolute coords of the popup anchor. */
+interface Coords {
+  top: number;
+  left: number;
+}
+
+function getCaretCoords(editor: MonacoCodeEditor): Coords | null {
+  const pos = editor.getPosition();
+  if (!pos) return null;
+  const scrolled = editor.getScrolledVisiblePosition(pos);
+  if (!scrolled) return null;
+  const domNode = editor.getDomNode();
+  if (!domNode) return null;
+  const rect = domNode.getBoundingClientRect();
+  return {
+    top: rect.top + scrolled.top + (scrolled.height ?? 20),
+    left: rect.left + scrolled.left,
+  };
+}
+
+export function MonacoSlashMenu({
+  editor,
+  commands,
+  open,
+  onOpenChange,
+  onInsert,
+  triggerRange,
+  className,
+}: MonacoSlashMenuProps) {
+  const [query, setQuery] = useState("");
+  const [activeIndex, setActiveIndex] = useState(0);
+  const [coords, setCoords] = useState<Coords | null>(null);
+  const menuRef = useRef<HTMLDivElement>(null);
+
+  // Insert the chosen snippet. Typed-`/` mode REPLACES the `/` (triggerRange) with
+  // the block; hotkey mode inserts via insertDirective at the caret/line. Always
+  // refocus the editor and close.
+  const commitSnippet = (snippet: string) => {
+    if (triggerRange) {
+      editor.executeEdits("brand-slash-typed", [
+        { range: triggerRange, text: snippet, forceMoveMarkers: true },
+      ]);
+    } else {
+      (onInsert ?? insertDirective)(editor, snippet);
+    }
+    onOpenChange(false);
+    editor.focus();
+  };
+
+  // Run a source-pane handler (#299): strip the typed `/query` trigger FIRST
+  // (the same edit `cancel` uses, so the doc is clean whether the handler
+  // opens a dialog, schedules async work, or inserts nothing), then call it
+  // with the live editor + the (now-stale) trigger range + content access.
+  const commitRunInSource = (command: SlashCommand) => {
+    if (triggerRange) {
+      editor.executeEdits("brand-slash-typed", [{ range: triggerRange, text: "" }]);
+    }
+    command.runInSource?.({
+      editor,
+      range: triggerRange ?? null,
+      content: monacoContentAccess(editor),
+    });
+    onOpenChange(false);
+    editor.focus();
+  };
+
+  // Select a command: `runInSource` (when present) wins over `snippet` — it's
+  // the more capable handler and is the ONLY option for a run-only command.
+  const selectCommand = (command: SlashCommand) => {
+    if (typeof command.runInSource === "function") {
+      commitRunInSource(command);
+    } else if (command.snippet) {
+      commitSnippet(command.snippet);
+    }
+  };
+
+  // Dismiss without inserting. In typed-`/` mode the stray `/` is removed so the
+  // document is left exactly as it was before the trigger.
+  const cancel = () => {
+    if (triggerRange) {
+      editor.executeEdits("brand-slash-cancel", [{ range: triggerRange, text: "" }]);
+    }
+    onOpenChange(false);
+    editor.focus();
+  };
+
+  // Latest select/cancel via refs so the capture-phase keydown listener can stay
+  // attached across renders (its effect deps don't need these closures).
+  const selectRef = useRef(selectCommand);
+  selectRef.current = selectCommand;
+  const cancelRef = useRef(cancel);
+  cancelRef.current = cancel;
+
+  // Reset query + active index whenever the menu opens.
+  useEffect(() => {
+    if (open) {
+      setQuery("");
+      setActiveIndex(0);
+    }
+  }, [open]);
+
+  // Compute and track caret position.
+  useEffect(() => {
+    if (!open) return;
+
+    const update = () => {
+      setCoords(getCaretCoords(editor));
+    };
+
+    update();
+
+    const scrollSub = editor.onDidScrollChange(update);
+    const cursorSub = editor.onDidChangeCursorPosition(update);
+
+    const onResize = () => update();
+    window.addEventListener("resize", onResize);
+
+    return () => {
+      scrollSub.dispose();
+      cursorSub.dispose();
+      window.removeEventListener("resize", onResize);
+    };
+  }, [open, editor]);
+
+  // Close on editor blur.
+  useEffect(() => {
+    if (!open) return;
+    const blurSub = editor.onDidBlurEditorText(() => {
+      // Small delay — if focus moved to the menu itself (mousedown), don't close.
+      setTimeout(() => {
+        if (!menuRef.current?.contains(document.activeElement)) {
+          onOpenChange(false);
+        }
+      }, 100);
+    });
+    return () => blurSub.dispose();
+  }, [open, editor, onOpenChange]);
+
+  // Wire keyboard navigation into the editor while the menu is open.
+  useEffect(() => {
+    if (!open) return;
+
+    const keydown = (e: KeyboardEvent) => {
+      const filtered = filterSlashCommands(commands, query);
+
+      if (e.key === "Escape") {
+        e.preventDefault();
+        e.stopPropagation();
+        cancelRef.current();
+        return;
+      }
+      if (e.key === "ArrowDown") {
+        e.preventDefault();
+        e.stopPropagation();
+        setActiveIndex((i) => (i + 1) % Math.max(filtered.length, 1));
+        return;
+      }
+      if (e.key === "ArrowUp") {
+        e.preventDefault();
+        e.stopPropagation();
+        setActiveIndex(
+          (i) => (i - 1 + Math.max(filtered.length, 1)) % Math.max(filtered.length, 1),
+        );
+        return;
+      }
+      // Enter AND Tab select the active command (the cmdk / Notion command-menu
+      // convention) — kept identical to the WYSIWYG slash menu so the cross-pane
+      // shortcut behaves the same in both panes (the goal of #271). Tab does NOT
+      // move browser focus here by design; Esc dismisses without inserting.
+      if (e.key === "Enter" || e.key === "Tab") {
+        // Always swallow while the popup is open — even with no match — so the key
+        // never leaks a newline/tab into the document behind the popup.
+        e.preventDefault();
+        e.stopPropagation();
+        const command = filtered[Math.min(activeIndex, filtered.length - 1)];
+        if (command) selectRef.current(command);
+        return;
+      }
+      // Printable characters update the query — intercept so they filter the
+      // menu instead of being typed into the Monaco document (the menu was
+      // opened by shortcut, so there is no `/query` run in the doc to absorb them).
+      if (e.key.length === 1 && !e.ctrlKey && !e.metaKey && !e.altKey) {
+        e.preventDefault();
+        e.stopPropagation();
+        setQuery((q) => q + e.key);
+        setActiveIndex(0);
+        return;
+      }
+      // Backspace trims the query (and closes when empty) — intercept so it
+      // never deletes document text behind the popup.
+      if (e.key === "Backspace") {
+        e.preventDefault();
+        e.stopPropagation();
+        if (query.length === 0) {
+          // Backspacing past the trigger dismisses (and removes the typed `/`).
+          cancelRef.current();
+          return;
+        }
+        setQuery((q) => q.slice(0, -1));
+        setActiveIndex(0);
+      }
+    };
+
+    // Capture phase — intercept before Monaco's own key handlers.
+    const domNode = editor.getDomNode();
+    domNode?.addEventListener("keydown", keydown, true);
+    return () => domNode?.removeEventListener("keydown", keydown, true);
+  }, [open, editor, commands, query, activeIndex]);
+
+  // Keep the highlighted option scrolled into view as ↑/↓ moves it — the listbox
+  // is overflow-y-auto, so without this the active row can move off-screen while
+  // the keyboard selection advances (the same fix slash-widget.tsx applies).
+  useEffect(() => {
+    if (!open) return;
+    const filtered = filterSlashCommands(commands, query);
+    const active = filtered[Math.min(activeIndex, Math.max(filtered.length - 1, 0))];
+    if (!active) return;
+    const el = menuRef.current?.querySelector<HTMLElement>(
+      `#${CSS.escape(slashOptionId(ID_PREFIX, active.id))}`,
+    );
+    el?.scrollIntoView({ block: "nearest" });
+  }, [open, commands, query, activeIndex]);
+
+  // Mirror the listbox relationship onto the Monaco textbox while open, so AT is
+  // told a popup appeared (aria-expanded), where it is (aria-controls), and which
+  // option is active (aria-activedescendant) — the same wiring the WYSIWYG path
+  // applies in slash-widget.tsx. All three are cleaned up on close.
+  useEffect(() => {
+    if (!open) return;
+    const filtered = filterSlashCommands(commands, query);
+    const activeCommand = filtered[Math.min(activeIndex, Math.max(filtered.length - 1, 0))];
+    const textarea = editor.getDomNode()?.querySelector("textarea");
+    if (!textarea) return;
+    textarea.setAttribute("aria-expanded", "true");
+    textarea.setAttribute("aria-controls", LISTBOX_ID);
+    if (activeCommand) {
+      textarea.setAttribute("aria-activedescendant", slashOptionId(ID_PREFIX, activeCommand.id));
+    } else {
+      textarea.removeAttribute("aria-activedescendant");
+    }
+    return () => {
+      textarea.removeAttribute("aria-expanded");
+      textarea.removeAttribute("aria-controls");
+      textarea.removeAttribute("aria-activedescendant");
+    };
+  }, [open, editor, commands, query, activeIndex]);
+
+  if (!open || !coords) return null;
+
+  const filtered = filterSlashCommands(commands, query);
+  const activeCommand = filtered[Math.min(activeIndex, Math.max(filtered.length - 1, 0))];
+
+  const handleSelect = (command: SlashCommand) => {
+    selectCommand(command);
+  };
+
+  const resultCount = filtered.length;
+  const statusText =
+    resultCount === 0
+      ? "No matching blocks"
+      : query
+        ? `${resultCount} result${resultCount === 1 ? "" : "s"} for “${query}”`
+        : `${resultCount} block${resultCount === 1 ? "" : "s"}`;
+
+  return (
+    <div
+      ref={menuRef}
+      className={cn(className)}
+      // Fixed positioning so it overlays the editor regardless of scroll.
+      style={{ position: "fixed", top: coords.top, left: coords.left, zIndex: 50 }}
+      // Prevent the mousedown from stealing focus from the editor.
+      onMouseDown={(e) => e.preventDefault()}
+    >
+      {/* One polite live region — focus stays in the editor, so AT learns the
+          filter result count (and the empty state) only from here. The visual
+          chip below is aria-hidden to avoid a double announcement. */}
+      <span role="status" aria-live="polite" className="sr-only">
+        {statusText}
+      </span>
+      {query && (
+        <div
+          aria-hidden="true"
+          className="mb-0.5 rounded-sm border border-border bg-popover px-2 py-1 text-caption text-muted-foreground"
+        >
+          Filter: <span className="font-medium text-foreground">{query}</span>
+        </div>
+      )}
+      <SlashMenu
+        id={LISTBOX_ID}
+        commands={filtered}
+        activeId={activeCommand?.id}
+        onSelect={handleSelect}
+        idPrefix={ID_PREFIX}
+      />
+    </div>
+  );
+}

package/src/markdown-editor/slash/shortcut-monaco.ts

@@ -0,0 +1,69 @@
+/**
+ * Shortcut helpers for the cross-pane slash menu (#271) — the MONACO half.
+ *
+ * Converts a shortcut string (e.g. `"Mod-/"`) into a Monaco keybinding bitmask.
+ * This is the ONLY slash module that imports `monaco-editor`; it is imported only
+ * by the Monaco-side surfaces (the source pane action in `MarkdownWorkspace`), so
+ * the pure `./shortcut.ts` — imported by the Milkdown plugin — stays Monaco-free.
+ *
+ * INTERNAL — not exported from package barrels.
+ */
+import * as monaco from "monaco-editor";
+
+/** Supported letter key names (A-Z, case-insensitive in shortcut strings). */
+const LETTER_KEY_MAP: Record<string, number> = (() => {
+  const map: Record<string, number> = {};
+  const kc = monaco.KeyCode as unknown as Record<string, number>;
+  for (let i = 0; i < 26; i++) {
+    const letter = String.fromCharCode(65 + i); // "A".."Z"
+    const code = kc[`Key${letter}`];
+    if (code !== undefined) map[letter.toLowerCase()] = code;
+  }
+  return map;
+})();
+
+const NAMED_KEY_MAP: Record<string, number> = {
+  "/": monaco.KeyCode.Slash,
+  backspace: monaco.KeyCode.Backspace,
+  delete: monaco.KeyCode.Delete,
+  escape: monaco.KeyCode.Escape,
+  enter: monaco.KeyCode.Enter,
+  tab: monaco.KeyCode.Tab,
+  arrowup: monaco.KeyCode.UpArrow,
+  arrowdown: monaco.KeyCode.DownArrow,
+  arrowleft: monaco.KeyCode.LeftArrow,
+  arrowright: monaco.KeyCode.RightArrow,
+};
+
+/**
+ * Parse a shortcut string (e.g. `"Mod-/"`, `"Mod-Shift-K"`) into a Monaco
+ * keybinding bitmask. Supports `Mod` (CtrlCmd), `Shift`, `Alt` modifiers and
+ * a final key that is either a letter (A-Z) or one of the named keys in
+ * `NAMED_KEY_MAP`. Throws for unrecognized final keys.
+ *
+ * The shipped default is `"Mod-/"` → `KeyMod.CtrlCmd | KeyCode.Slash`.
+ */
+export function parseShortcut(shortcut: string): number {
+  const parts = shortcut.split("-");
+  let binding = 0;
+  const keyPart = parts[parts.length - 1] ?? "";
+  const modifiers = parts.slice(0, -1).map((m) => m.toLowerCase());
+
+  for (const mod of modifiers) {
+    if (mod === "mod") binding |= monaco.KeyMod.CtrlCmd;
+    else if (mod === "shift") binding |= monaco.KeyMod.Shift;
+    else if (mod === "alt") binding |= monaco.KeyMod.Alt;
+    // Ctrl/Meta can also be named explicitly
+    else if (mod === "ctrl") binding |= monaco.KeyMod.WinCtrl;
+  }
+
+  const key = keyPart.toLowerCase();
+  const keyCode =
+    NAMED_KEY_MAP[key] ??
+    LETTER_KEY_MAP[key] ??
+    (() => {
+      throw new Error(`[@elabs-ai/components-editor] parseShortcut: unrecognized key "${keyPart}"`);
+    })();
+
+  return binding | keyCode;
+}