@elabs-ai/components-editor 4.0.0

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

@@ -0,0 +1,157 @@
+/**
+ * Unit tests for the slash-menu shortcut helpers.
+ * Pure functions — no React, no DOM engine needed beyond vitest's node env.
+ */
+import { describe, expect, it, vi } from "vitest";
+
+// ---------------------------------------------------------------------------
+// Mock monaco-editor — the shortcut module reads KeyMod/KeyCode constants at
+// import time so we must hoist this before the import.
+// ---------------------------------------------------------------------------
+vi.mock("monaco-editor", () => {
+  // Use real-ish numeric values that don't collide so we can assert bitwise ops.
+  const KeyCode = {
+    Slash: 85,
+    Backspace: 1,
+    Delete: 2,
+    Escape: 9,
+    Enter: 3,
+    Tab: 2048,
+    UpArrow: 16,
+    DownArrow: 17,
+    LeftArrow: 15,
+    RightArrow: 18,
+    // Letters KeyA..KeyZ
+    KeyA: 31,
+    KeyB: 32,
+    KeyC: 33,
+    KeyD: 34,
+    KeyE: 35,
+    KeyF: 36,
+    KeyG: 37,
+    KeyH: 38,
+    KeyI: 39,
+    KeyJ: 40,
+    KeyK: 41,
+    KeyL: 42,
+    KeyM: 43,
+    KeyN: 44,
+    KeyO: 45,
+    KeyP: 46,
+    KeyQ: 47,
+    KeyR: 48,
+    KeyS: 49,
+    KeyT: 50,
+    KeyU: 51,
+    KeyV: 52,
+    KeyW: 53,
+    KeyX: 54,
+    KeyY: 55,
+    KeyZ: 56,
+  } as const;
+
+  const KeyMod = {
+    CtrlCmd: 2048,
+    Shift: 1024,
+    Alt: 512,
+    WinCtrl: 256,
+  } as const;
+
+  return { KeyCode, KeyMod };
+});
+
+import { DEFAULT_SLASH_SHORTCUT, matchesKeyboardEvent } from "./shortcut";
+// parseShortcut moved to the Monaco half (keeps ./shortcut Monaco-free); the
+// monaco mock above backs it.
+import { parseShortcut } from "./shortcut-monaco";
+
+// Pull the mocked constants for assertions.
+const { KeyCode, KeyMod } = await import("monaco-editor");
+
+describe("DEFAULT_SLASH_SHORTCUT", () => {
+  it("is Mod-Shift-O (NOT Mod-/, which collides with Monaco's Toggle Line Comment)", () => {
+    expect(DEFAULT_SLASH_SHORTCUT).toBe("Mod-Shift-O");
+  });
+});
+
+describe("parseShortcut", () => {
+  it('parses "Mod-/" → CtrlCmd | Slash', () => {
+    expect(parseShortcut("Mod-/")).toBe(KeyMod.CtrlCmd | KeyCode.Slash);
+  });
+
+  it('parses "Mod-Shift-K" → CtrlCmd | Shift | KeyK', () => {
+    expect(parseShortcut("Mod-Shift-K")).toBe(KeyMod.CtrlCmd | KeyMod.Shift | KeyCode.KeyK);
+  });
+
+  it("parses letter keys case-insensitively", () => {
+    expect(parseShortcut("Mod-k")).toBe(parseShortcut("Mod-K"));
+  });
+
+  it('parses "Alt-/" → Alt | Slash', () => {
+    expect(parseShortcut("Alt-/")).toBe(KeyMod.Alt | KeyCode.Slash);
+  });
+
+  it("throws for an unrecognized final key", () => {
+    expect(() => parseShortcut("Mod-~")).toThrow();
+  });
+});
+
+describe("matchesKeyboardEvent", () => {
+  const makeEvent = (overrides: Partial<KeyboardEvent>): KeyboardEvent =>
+    ({
+      metaKey: false,
+      ctrlKey: false,
+      shiftKey: false,
+      altKey: false,
+      key: "",
+      ...overrides,
+    }) as KeyboardEvent;
+
+  describe('shortcut "Mod-/"', () => {
+    it("matches when metaKey=true and key='/'", () => {
+      expect(matchesKeyboardEvent("Mod-/", makeEvent({ metaKey: true, key: "/" }))).toBe(true);
+    });
+
+    it("matches when ctrlKey=true and key='/'", () => {
+      expect(matchesKeyboardEvent("Mod-/", makeEvent({ ctrlKey: true, key: "/" }))).toBe(true);
+    });
+
+    it("does NOT match plain '/' (no modifier)", () => {
+      expect(matchesKeyboardEvent("Mod-/", makeEvent({ key: "/" }))).toBe(false);
+    });
+
+    it("does NOT match wrong modifier (altKey only)", () => {
+      expect(matchesKeyboardEvent("Mod-/", makeEvent({ altKey: true, key: "/" }))).toBe(false);
+    });
+
+    it("does NOT match wrong key with correct modifier", () => {
+      expect(matchesKeyboardEvent("Mod-/", makeEvent({ metaKey: true, key: "k" }))).toBe(false);
+    });
+
+    it("does NOT match when an unexpected extra modifier is pressed (shift)", () => {
+      expect(
+        matchesKeyboardEvent("Mod-/", makeEvent({ metaKey: true, shiftKey: true, key: "/" })),
+      ).toBe(false);
+    });
+  });
+
+  describe('shortcut "Mod-Shift-K"', () => {
+    it("matches Cmd+Shift+k (metaKey + shiftKey)", () => {
+      expect(
+        matchesKeyboardEvent("Mod-Shift-K", makeEvent({ metaKey: true, shiftKey: true, key: "k" })),
+      ).toBe(true);
+    });
+
+    it("matches case-insensitively for the key", () => {
+      expect(
+        matchesKeyboardEvent("Mod-Shift-K", makeEvent({ metaKey: true, shiftKey: true, key: "K" })),
+      ).toBe(true);
+    });
+
+    it("does NOT match without shift", () => {
+      expect(matchesKeyboardEvent("Mod-Shift-K", makeEvent({ metaKey: true, key: "k" }))).toBe(
+        false,
+      );
+    });
+  });
+});

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

@@ -0,0 +1,57 @@
+/**
+ * Shortcut helpers for the cross-pane slash menu (#271) — the PURE half.
+ *
+ * No React, no Milkdown, **no Monaco**. This module is imported by
+ * `brand-slash-plugin.ts` (and therefore by the Milkdown `MarkdownEditor` import
+ * graph), so it must NOT pull `monaco-editor` — doing so drags the Monaco runtime
+ * (and its jsdom-hostile clipboard module) into every WYSIWYG test. The
+ * Monaco-keybinding conversion lives in the sibling `./shortcut-monaco.ts`, which
+ * only the Monaco-side surfaces (the workspace) import.
+ *
+ * INTERNAL — not exported from package barrels.
+ */
+
+/**
+ * The default keyboard shortcut for the slash command menu.
+ * `Mod` = Cmd on macOS, Ctrl elsewhere (Monaco's `CtrlCmd`).
+ *
+ * NOTE: this is NOT `Mod-/` — Monaco binds `Mod-/` to "Toggle Line Comment" by
+ * default, which eats the keystroke before the slash action sees it (the source
+ * pane's primary trigger is typing `/`; this hotkey is the secondary path). `Mod-Shift-O`
+ * is free in Chrome/macOS; it DOES collide with the bookmarks shortcut in Firefox
+ * and on Windows/Linux Chrome, so consumers shipping cross-browser should override
+ * `slashMenu.shortcut`. The conflict-free trigger is typing `/`.
+ */
+export const DEFAULT_SLASH_SHORTCUT = "Mod-Shift-O";
+
+/**
+ * Returns `true` when a DOM `KeyboardEvent` matches a shortcut string.
+ *
+ * - `Mod` matches `event.metaKey` (macOS) OR `event.ctrlKey` (other platforms).
+ * - `Shift` / `Alt` match the corresponding event fields.
+ * - The final key matches `event.key` (case-insensitive); `"/"` matches
+ *   `event.key === "/"`.
+ *
+ * Used by the WYSIWYG plugin's `handleKeyDown` (which receives DOM events) to
+ * decide whether to open the menu — pure, so it never pulls the monaco namespace.
+ */
+export function matchesKeyboardEvent(shortcut: string, event: KeyboardEvent): boolean {
+  const parts = shortcut.split("-");
+  const keyPart = parts[parts.length - 1] ?? "";
+  const modifiers = new Set(parts.slice(0, -1).map((m) => m.toLowerCase()));
+
+  // Check modifier flags.
+  const wantsMod = modifiers.has("mod");
+  const wantsShift = modifiers.has("shift");
+  const wantsAlt = modifiers.has("alt");
+
+  if (wantsMod && !(event.metaKey || event.ctrlKey)) return false;
+  if (!wantsMod && (event.metaKey || event.ctrlKey)) return false;
+  if (wantsShift && !event.shiftKey) return false;
+  if (!wantsShift && event.shiftKey) return false;
+  if (wantsAlt && !event.altKey) return false;
+  if (!wantsAlt && event.altKey) return false;
+
+  // Check the key itself (case-insensitive).
+  return event.key.toLowerCase() === keyPart.toLowerCase();
+}

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

@@ -0,0 +1,139 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, within } from "storybook/test";
+import { useState } from "react";
+
+import { MarkdownEditor } from "../markdown-editor";
+import { BRAND_SLASH_COMMANDS, filterSlashCommands } from "./brand-slash-commands";
+import { SlashMenu } from "./slash-menu";
+
+/**
+ * The `/` command menu for the WYSIWYG markdown editor. Typing `/` at a block
+ * start (or after whitespace) opens a branded popup that inserts the brand `:::`
+ * directives (card / callout / metric / timeline) + basic blocks live at the
+ * caret. Opt in via the `slashMenu` prop on `MarkdownEditor` /
+ * `MarkdownWorkspace` (default `true`).
+ *
+ * The popup itself is rendered here standalone (the `SlashMenu` stories) so its
+ * branding + a11y can be verified directly across all three themes; the in-editor
+ * stories exercise the integration (mount + the `slashMenu={false}` no-op). The
+ * live keyboard/insert UX is best verified in a real browser — ProseMirror
+ * keystroke dispatch can't be fully simulated in jsdom.
+ */
+const meta = {
+  title: "Editor/MarkdownEditor/Slash menu",
+  component: SlashMenu,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Branded `/` command menu for the WYSIWYG editor. Inserts brand `:::` " +
+          "directives + basic blocks at the caret. Token-driven `listbox`/`option` " +
+          "list; the editor `textbox` owns `aria-activedescendant`.",
+      },
+    },
+  },
+} satisfies Meta<typeof SlashMenu>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** The popup standalone, with the first command highlighted (default state). */
+export const Default: Story = {
+  args: {
+    commands: BRAND_SLASH_COMMANDS,
+    activeId: BRAND_SLASH_COMMANDS[0]?.id,
+    onSelect: () => {},
+  },
+  render: (args) => (
+    <div className="p-6">
+      <SlashMenu {...args} />
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    // The popup is a labelled listbox of options grouped by section.
+    await expect(canvas.getByRole("listbox", { name: "Insert block" })).toBeVisible();
+    await expect(canvas.getByRole("option", { name: /Card/ })).toBeVisible();
+    // The first option is selected by default.
+    await expect(canvas.getByRole("option", { name: /Card/ })).toHaveAttribute(
+      "aria-selected",
+      "true",
+    );
+  },
+};
+
+/** Filtered to a query (`/ca`) — Card + Callout match by label, the Brand group leads. */
+export const Filtered: Story = {
+  args: {
+    commands: filterSlashCommands(BRAND_SLASH_COMMANDS, "ca"),
+    onSelect: () => {},
+  },
+  render: function FilteredStory(args) {
+    const [activeId, setActiveId] = useState(args.commands[0]?.id);
+    return (
+      <div className="p-6">
+        <SlashMenu {...args} activeId={activeId} onSelect={(c) => setActiveId(c.id)} />
+      </div>
+    );
+  },
+};
+
+/** The empty state when nothing matches the query. */
+export const Empty: Story = {
+  args: {
+    commands: [],
+    onSelect: () => {},
+  },
+  render: (args) => (
+    <div className="p-6">
+      <SlashMenu {...args} />
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByText("No matching blocks")).toBeVisible();
+  },
+};
+
+const SAMPLE = `# Release notes
+
+Type "/" on a new line to insert a brand block (card, callout, metric, timeline)
+or a basic block.
+`;
+
+/**
+ * The slash menu wired into the live editor. Place the caret on an empty line and
+ * type `/` to open the menu. (The play test only asserts the editor mounts — drive
+ * the keyboard/insert flow in a real browser.)
+ */
+export const InEditor: StoryObj<typeof MarkdownEditor> = {
+  name: "In editor (slashMenu enabled)",
+  render: () => (
+    <div className="mx-auto max-w-3xl p-6">
+      <MarkdownEditor defaultValue={SAMPLE} slashMenu />
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(
+      await canvas.findByRole("textbox", { name: "Markdown editor" }, { timeout: 8000 }),
+    ).toBeVisible();
+  },
+};
+
+/** `slashMenu={false}` disables the menu (the editor renders normally). */
+export const Disabled: StoryObj<typeof MarkdownEditor> = {
+  name: "In editor (slashMenu disabled)",
+  render: () => (
+    <div className="mx-auto max-w-3xl p-6">
+      <MarkdownEditor defaultValue={SAMPLE} slashMenu={false} />
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(
+      await canvas.findByRole("textbox", { name: "Markdown editor" }, { timeout: 8000 }),
+    ).toBeVisible();
+  },
+};

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

@@ -0,0 +1,115 @@
+"use client";
+
+/**
+ * SlashMenu — the branded popup the slash plugin renders at the caret.
+ *
+ * Presentational + controlled: the ProseMirror plugin owns the keyboard
+ * (↑/↓/Enter/Esc) and the open/query/active state, so this component just renders
+ * the filtered, grouped commands and exposes `onSelect`. It is a token-styled
+ * `listbox`/`option` list (NOT `@elabs-ai/components-ui` `Command`/cmdk): a cmdk instance would
+ * fight the editor for DOM focus and arrow-key handling, since the caret must stay
+ * in the ProseMirror `textbox` while the user types `/query`. The plugin keeps the
+ * active option in view and wires `aria-activedescendant` on the editor surface.
+ *
+ * Semantic tokens only; matches the `Command` popover look (bg-popover, accent
+ * selection, muted group headings).
+ */
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import { forwardRef, type HTMLAttributes } from "react";
+
+import { groupSlashCommands, type SlashCommand } from "./brand-slash-commands";
+
+export interface SlashMenuProps extends Omit<HTMLAttributes<HTMLDivElement>, "onSelect"> {
+  /** The (already filtered) commands to show. */
+  commands: SlashCommand[];
+  /** The id of the active (highlighted) command, for `aria-selected`. */
+  activeId?: string;
+  /** Called when a command is chosen (click or via the plugin's Enter). */
+  onSelect: (command: SlashCommand) => void;
+  /** DOM id prefix so each option id is stable + unique (matches `aria-activedescendant`). */
+  idPrefix?: string;
+  /** Shown when the query matches nothing. */
+  emptyLabel?: string;
+}
+
+/** Build the stable DOM id for a command's option element. */
+export function slashOptionId(idPrefix: string, commandId: string): string {
+  return `${idPrefix}-${commandId}`;
+}
+
+export const SlashMenu = forwardRef<HTMLDivElement, SlashMenuProps>(function SlashMenu(
+  {
+    commands,
+    activeId,
+    onSelect,
+    idPrefix = "brand-slash",
+    emptyLabel = "No matching blocks",
+    className,
+    ...props
+  },
+  ref,
+) {
+  const groups = groupSlashCommands(commands);
+
+  return (
+    <div
+      ref={ref}
+      // The editor surface carries `role="textbox"`; this list is its popup. The
+      // plugin sets `aria-controls`/`aria-activedescendant` on the textbox.
+      role="listbox"
+      aria-label="Insert block"
+      className={cn(
+        "max-h-[min(320px,60vh)] w-72 overflow-y-auto overflow-x-hidden rounded-md bg-popover p-1 text-popover-foreground shadow-ring-md",
+        className,
+      )}
+      {...props}
+    >
+      {commands.length === 0 ? (
+        <div className="px-2 py-6 text-center text-caption text-muted-foreground">{emptyLabel}</div>
+      ) : (
+        groups.map(({ group, commands: groupCommands }) => (
+          <div key={group} role="group" aria-label={group} className="overflow-hidden p-1">
+            <div className="px-2 py-1.5 text-meta font-medium text-muted-foreground">{group}</div>
+            {groupCommands.map((command) => {
+              const selected = command.id === activeId;
+              return (
+                <div
+                  key={command.id}
+                  id={slashOptionId(idPrefix, command.id)}
+                  role="option"
+                  aria-selected={selected}
+                  data-selected={selected ? "true" : undefined}
+                  // The editor keeps focus, so select on mousedown (before the
+                  // editor would steal focus back) and don't let the click move
+                  // the selection out of the document.
+                  onMouseDown={(e) => {
+                    e.preventDefault();
+                    onSelect(command);
+                  }}
+                  className={cn(
+                    "flex cursor-default select-none items-center gap-2 rounded-sm px-2 py-1.5 text-body outline-none transition-colors duration-fast",
+                    "data-[selected=true]:bg-accent data-[selected=true]:text-accent-foreground",
+                  )}
+                >
+                  {command.icon ? (
+                    <span className="flex size-5 shrink-0 items-center justify-center text-muted-foreground [&_svg]:size-4">
+                      {command.icon}
+                    </span>
+                  ) : null}
+                  <span className="flex min-w-0 flex-col">
+                    <span className="truncate">{command.label}</span>
+                    {command.description ? (
+                      <span className="truncate text-meta text-muted-foreground">
+                        {command.description}
+                      </span>
+                    ) : null}
+                  </span>
+                </div>
+              );
+            })}
+          </div>
+        ))
+      )}
+    </div>
+  );
+});

package/src/markdown-editor/slash/slash-scroll.test.tsx

@@ -0,0 +1,52 @@
+/**
+ * Locking tests for slash-menu scroll-to-active (A2). The scroll + aria wiring
+ * already ships (slash-widget.tsx), so these guard it from silent removal: the
+ * popup must be a capped, scrollable listbox whose options carry stable ids (the
+ * scroll / `aria-activedescendant` target), and the widget must scroll the active
+ * option into view as ↑/↓ moves it. The live keyboard UX is covered in the
+ * browser by slash-menu.stories.tsx.
+ */
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { render, screen } from "@testing-library/react";
+
+import { SlashMenu, slashOptionId } from "./slash-menu";
+import { BRAND_SLASH_COMMANDS } from "./brand-slash-commands";
+
+describe("slash menu scroll-to-active (A2)", () => {
+  it("renders a capped, scrollable listbox so the active row can scroll into view", () => {
+    render(<SlashMenu commands={BRAND_SLASH_COMMANDS} activeId="brand-card" onSelect={() => {}} />);
+    const list = screen.getByRole("listbox");
+    expect(list.className).toMatch(/overflow-y-auto/);
+    expect(list.className).toMatch(/max-h-/);
+  });
+
+  it("gives each option a stable id (the scroll + aria-activedescendant target)", () => {
+    render(
+      <SlashMenu
+        commands={BRAND_SLASH_COMMANDS}
+        activeId="brand-card"
+        onSelect={() => {}}
+        idPrefix="x"
+      />,
+    );
+    const opt = document.getElementById(slashOptionId("x", "brand-card"));
+    expect(opt).not.toBeNull();
+    expect(opt?.getAttribute("role")).toBe("option");
+    expect(opt?.getAttribute("aria-selected")).toBe("true");
+  });
+
+  it("the widget scrolls the active option into view and mirrors aria-activedescendant", () => {
+    // This behavior lives in the widget's layout effects, which need a live
+    // ProseMirror view to exercise — lock it at the source so it can't regress.
+    const src = readFileSync(
+      resolve(process.cwd(), "src/markdown-editor/slash/slash-widget.tsx"),
+      "utf8",
+    );
+    expect(src).toMatch(/scrollIntoView\(\{\s*block:\s*"nearest"\s*\}\)/);
+    expect(src).toMatch(/aria-activedescendant/);
+    // The scroll effect re-runs as ↑/↓ changes the active row.
+    expect(src).toMatch(/\[activeId\]/);
+  });
+});

package/src/markdown-editor/slash/slash-widget.tsx

@@ -0,0 +1,97 @@
+"use client";
+
+/**
+ * SlashWidget — the React widget the slash plugin mounts at the caret.
+ *
+ * The adapter renders this (no props) inside a ProseMirror widget decoration; it
+ * reads the live `EditorView` from `useWidgetViewContext()`, pulls the slash
+ * plugin state, and renders the branded `<SlashMenu>` floating just below the
+ * caret. Clicking an option runs the command through the shared
+ * {@link SlashController} (same path as the plugin's Enter handler), so the mouse
+ * and keyboard insert identically.
+ *
+ * Built via `createSlashWidget(controller)` so the component closes over the
+ * controller (commands + Milkdown `Ctx` getter) — no module-level mutable state,
+ * no circular import with the plugin.
+ */
+import type { ReactWidgetViewComponent } from "@prosemirror-adapter/react";
+import { useWidgetViewContext } from "@prosemirror-adapter/react";
+import { useLayoutEffect, useRef } from "react";
+
+import { filterSlashCommands, type SlashCommand } from "./brand-slash-commands";
+import { SlashMenu, slashOptionId } from "./slash-menu";
+import {
+  runSlashCommand,
+  slashPluginKey,
+  type SlashController,
+  type SlashPluginState,
+} from "./brand-slash-plugin";
+
+const ID_PREFIX = "brand-slash";
+
+/** Build the widget component bound to a controller. */
+export function createSlashWidget(controller: SlashController): ReactWidgetViewComponent {
+  function SlashWidget() {
+    const { view } = useWidgetViewContext();
+    const wrapperRef = useRef<HTMLSpanElement>(null);
+
+    const state = slashPluginKey.getState(view.state) as SlashPluginState | undefined;
+    const query = state?.query ?? "";
+    const filtered = filterSlashCommands(controller.commands, query);
+    const activeIndex = state ? Math.min(state.index, Math.max(0, filtered.length - 1)) : 0;
+    const active = filtered[activeIndex];
+    const activeId = active?.id;
+
+    // Mirror the active option onto the editor's `textbox` for AT
+    // (`aria-activedescendant` + `aria-controls`), then clean up on unmount.
+    useLayoutEffect(() => {
+      const dom = view.dom as HTMLElement;
+      const listEl = wrapperRef.current?.querySelector<HTMLElement>('[role="listbox"]');
+      if (listEl && !listEl.id) listEl.id = `${ID_PREFIX}-listbox`;
+      dom.setAttribute("aria-expanded", "true");
+      if (listEl) dom.setAttribute("aria-controls", listEl.id);
+      if (activeId) dom.setAttribute("aria-activedescendant", slashOptionId(ID_PREFIX, activeId));
+      else dom.removeAttribute("aria-activedescendant");
+      return () => {
+        dom.removeAttribute("aria-expanded");
+        dom.removeAttribute("aria-controls");
+        dom.removeAttribute("aria-activedescendant");
+      };
+    }, [view, activeId]);
+
+    // Keep the highlighted option scrolled into view as ↑/↓ moves it.
+    useLayoutEffect(() => {
+      if (!activeId) return;
+      const el = wrapperRef.current?.querySelector<HTMLElement>(
+        `#${CSS.escape(slashOptionId(ID_PREFIX, activeId))}`,
+      );
+      el?.scrollIntoView({ block: "nearest" });
+    }, [activeId]);
+
+    const onSelect = (command: SlashCommand) => {
+      if (!state) return;
+      runSlashCommand(view, controller, state, command);
+    };
+
+    return (
+      // The widget anchor is zero-width inline; the menu floats below the caret.
+      <span
+        ref={wrapperRef}
+        contentEditable={false}
+        // Keep the widget out of the accessibility tree as a node — the listbox
+        // inside carries the semantics, and the editor textbox owns the relationship.
+        className="brand-slash-anchor relative inline-block h-0 w-0 align-baseline"
+      >
+        <span className="absolute left-0 top-1 z-50 block">
+          <SlashMenu
+            commands={filtered}
+            activeId={activeId}
+            onSelect={onSelect}
+            idPrefix={ID_PREFIX}
+          />
+        </span>
+      </span>
+    );
+  }
+  return SlashWidget;
+}

package/src/markdown-editor/slash/source-slash-trigger.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from "vitest";
+
+import { slashTriggerRange } from "./source-slash-trigger";
+
+describe("slashTriggerRange", () => {
+  it("triggers at the start of a line (column 1)", () => {
+    expect(slashTriggerRange(3, "/", 1)).toEqual({
+      startLineNumber: 3,
+      startColumn: 1,
+      endLineNumber: 3,
+      endColumn: 2,
+    });
+  });
+
+  it("triggers right after whitespace", () => {
+    // "hello /" → the "/" is at column 7, preceded by a space.
+    expect(slashTriggerRange(1, "hello /", 7)).toEqual({
+      startLineNumber: 1,
+      startColumn: 7,
+      endLineNumber: 1,
+      endColumn: 8,
+    });
+  });
+
+  it("does NOT trigger inside a word", () => {
+    // "ab/" → the "/" is at column 3, preceded by "b".
+    expect(slashTriggerRange(1, "ab/", 3)).toBeNull();
+  });
+
+  it("does NOT trigger inside a path / URL", () => {
+    expect(slashTriggerRange(1, "http://", 6)).toBeNull(); // preceded by ":"
+    expect(slashTriggerRange(1, "a/b/", 4)).toBeNull(); // preceded by "b"
+  });
+
+  it("returns null when the column does not actually hold a slash", () => {
+    expect(slashTriggerRange(1, "hello", 3)).toBeNull();
+  });
+
+  it("treats a tab as whitespace", () => {
+    expect(slashTriggerRange(1, "\t/", 2)).not.toBeNull();
+  });
+});