@spatika/editor 1.5.0

package/src/composites/MentionMenu.test.tsx

@@ -0,0 +1,25 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import { MentionMenu } from "./MentionMenu";
+
+const contacts = [{ id: "1", label: "Asha Verma", subtitle: "Design" }];
+
+describe("MentionMenu", () => {
+  it("returns null when closed", () => {
+    const { container } = render(
+      <MentionMenu contacts={contacts} query="" activeIndex={0} open={false} onSelect={vi.fn()} />,
+    );
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it("selects a contact on option click", async () => {
+    const onSelect = vi.fn();
+    render(
+      <MentionMenu contacts={contacts} query="ash" activeIndex={0} open onSelect={onSelect} />,
+    );
+    expect(screen.getByRole("listbox", { name: "Mentions" })).toBeInTheDocument();
+    await userEvent.click(screen.getByRole("option", { name: /Asha Verma/i }));
+    expect(onSelect).toHaveBeenCalledWith(contacts[0]);
+  });
+});

package/src/composites/MentionMenu.tsx

@@ -0,0 +1,46 @@
+import type { MentionContact } from "../lib/types";
+import { cn } from "../lib/cn";
+
+type MentionMenuProps = {
+  contacts: MentionContact[];
+  query: string;
+  activeIndex: number;
+  open: boolean;
+  onSelect: (contact: MentionContact) => void;
+};
+
+export function MentionMenu({ contacts, query, activeIndex, open, onSelect }: MentionMenuProps) {
+  if (!open || contacts.length === 0) return null;
+
+  return (
+    <div className="spk-editor-suggestion" role="listbox" aria-label="Mentions">
+      <div className="spk-editor-suggestion-header">
+        {query ? `People matching “@${query}”` : "Mention someone"}
+      </div>
+      <ul className="spk-editor-suggestion-list">
+        {contacts.map((contact, index) => (
+          <li key={contact.id}>
+            <button
+              type="button"
+              role="option"
+              aria-selected={index === activeIndex}
+              className={cn(
+                "spk-editor-suggestion-item",
+                index === activeIndex && "spk-editor-suggestion-item--active",
+              )}
+              onMouseDown={(event) => {
+                event.preventDefault();
+                onSelect(contact);
+              }}
+            >
+              <span className="spk-editor-suggestion-title">{contact.label}</span>
+              {contact.subtitle ? (
+                <span className="spk-editor-suggestion-desc">{contact.subtitle}</span>
+              ) : null}
+            </button>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}

package/src/composites/SlashCommandMenu.test.tsx

@@ -0,0 +1,33 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import type { SlashCommandItem } from "../lib/types";
+import { SlashCommandMenu } from "./SlashCommandMenu";
+
+const items: SlashCommandItem[] = [
+  {
+    id: "h1",
+    title: "Heading 1",
+    description: "Large title",
+    command: vi.fn(),
+  },
+];
+
+describe("SlashCommandMenu", () => {
+  it("renders filtered slash commands", async () => {
+    const onSelect = vi.fn();
+    render(
+      <SlashCommandMenu
+        editor={null}
+        items={items}
+        query="head"
+        activeIndex={0}
+        open
+        onSelect={onSelect}
+      />,
+    );
+    expect(screen.getByRole("listbox", { name: "Slash commands" })).toBeInTheDocument();
+    await userEvent.click(screen.getByRole("option", { name: /Heading 1/i }));
+    expect(onSelect).toHaveBeenCalledWith(items[0]);
+  });
+});

package/src/composites/SlashCommandMenu.tsx

@@ -0,0 +1,54 @@
+import type { Editor } from "@tiptap/core";
+import type { SlashCommandItem } from "../lib/types";
+import { cn } from "../lib/cn";
+
+type SlashCommandMenuProps = {
+  editor: Editor | null;
+  items: SlashCommandItem[];
+  query: string;
+  activeIndex: number;
+  open: boolean;
+  onSelect: (item: SlashCommandItem) => void;
+};
+
+export function SlashCommandMenu({
+  items,
+  query,
+  activeIndex,
+  open,
+  onSelect,
+}: SlashCommandMenuProps) {
+  if (!open || items.length === 0) return null;
+
+  return (
+    <div className="spk-editor-suggestion" role="listbox" aria-label="Slash commands">
+      <div className="spk-editor-suggestion-header">
+        {query ? `Results for “/${query}”` : "Insert block"}
+      </div>
+      <ul className="spk-editor-suggestion-list">
+        {items.map((item, index) => (
+          <li key={item.id}>
+            <button
+              type="button"
+              role="option"
+              aria-selected={index === activeIndex}
+              className={cn(
+                "spk-editor-suggestion-item",
+                index === activeIndex && "spk-editor-suggestion-item--active",
+              )}
+              onMouseDown={(event) => {
+                event.preventDefault();
+                onSelect(item);
+              }}
+            >
+              <span className="spk-editor-suggestion-title">{item.title}</span>
+              {item.description ? (
+                <span className="spk-editor-suggestion-desc">{item.description}</span>
+              ) : null}
+            </button>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}

package/src/composites/SpatikaEditor.test.tsx

@@ -0,0 +1,167 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { useState } from "react";
+import { describe, expect, it, vi } from "vitest";
+import { defaultSlashCommands } from "../extensions/slash-command";
+import { buildSpatikaExtensions } from "../lib/use-spatika-editor";
+import { SpatikaEditor } from "./SpatikaEditor";
+
+function ControlledEditor(
+  props: Partial<React.ComponentProps<typeof SpatikaEditor>> & { initial?: string },
+) {
+  const [value, setValue] = useState(props.initial ?? "<p>Hello editor</p>");
+  return (
+    <SpatikaEditor
+      value={value}
+      onChange={setValue}
+      placeholder="Write here…"
+      toolbar={{ layout: "compact", ai: false }}
+      {...props}
+    />
+  );
+}
+
+describe("buildSpatikaExtensions", () => {
+  it("includes default slash commands and starter kit", () => {
+    const extensions = buildSpatikaExtensions({
+      value: "",
+      onChange: () => {},
+    });
+    expect(extensions.length).toBeGreaterThan(5);
+    expect(defaultSlashCommands().map((item) => item.id)).toContain("h1");
+  });
+});
+
+describe("SpatikaEditor", () => {
+  it("renders toolbar controls and editable surface", async () => {
+    render(<ControlledEditor />);
+    expect(await screen.findByRole("toolbar", { name: "Editor formatting" })).toBeInTheDocument();
+    expect(screen.getByRole("textbox", { name: "Rich text editor" })).toBeInTheDocument();
+    expect(screen.getByLabelText("Bold")).toBeInTheDocument();
+  });
+
+  it("calls onChange when block formatting is applied", async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+    render(<ControlledEditor onChange={onChange} initial="<p>Hello</p>" />);
+    const surface = await screen.findByRole("textbox", { name: "Rich text editor" });
+    await user.click(surface);
+    await user.click(screen.getByLabelText("Heading 1"));
+    await waitFor(() => {
+      expect(onChange).toHaveBeenCalled();
+      const last = onChange.mock.calls.at(-1)?.[0] as string;
+      expect(last).toContain("<h1");
+    });
+  });
+
+  it("shows slash command menu when typing /", async () => {
+    const user = userEvent.setup();
+    render(<ControlledEditor initial="<p></p>" />);
+    const surface = await screen.findByRole("textbox", { name: "Rich text editor" });
+    await user.click(surface);
+    await user.type(surface, "/heading");
+    await waitFor(
+      () => {
+        expect(screen.getByRole("listbox", { name: "Slash commands" })).toBeInTheDocument();
+      },
+      { timeout: 3000 },
+    );
+    expect(screen.getByRole("option", { name: /Heading 1/i })).toBeInTheDocument();
+  });
+
+  it("shows mention menu when mentions are provided", async () => {
+    const user = userEvent.setup();
+    render(
+      <ControlledEditor
+        initial="<p></p>"
+        mentions={[{ id: "1", label: "Asha Verma", subtitle: "Design" }]}
+      />,
+    );
+    const surface = await screen.findByRole("textbox", { name: "Rich text editor" });
+    await user.click(surface);
+    await user.keyboard("@ash");
+    expect(await screen.findByRole("listbox", { name: "Mentions" })).toBeInTheDocument();
+    expect(screen.getByText("Asha Verma")).toBeInTheDocument();
+  });
+
+  it("shows the AI dock when an AI handler is provided", async () => {
+    const user = userEvent.setup();
+    const { container } = render(
+      <ControlledEditor
+        onAiCommand={async () => "Rewritten text"}
+        aiCommandMenu={{ title: "AI Toolkit examples", placement: "dock" }}
+        toolbar={{ ai: true, layout: "compact", insert: false, alignment: false, lists: false, textStyle: false }}
+      />,
+    );
+    await screen.findByRole("textbox", { name: "Rich text editor" });
+    expect(
+      screen.getByPlaceholderText("Ask about this document or request a change…"),
+    ).toBeInTheDocument();
+    expect(screen.queryByLabelText("Proofread selection")).not.toBeInTheDocument();
+    expect(container.querySelector(".spk-editor-ai-dock-footer")).toBeInTheDocument();
+    expect(container.querySelector(".spk-editor-shell--with-ai-dock")).toBeInTheDocument();
+    await user.click(screen.getByRole("button", { name: "AI commands" }));
+    expect(screen.getByRole("dialog", { name: "AI Toolkit examples" })).toBeInTheDocument();
+  });
+
+  it("shows the toolbar AI menu when placement is toolbar", async () => {
+    const user = userEvent.setup();
+    render(
+      <ControlledEditor
+        onAiCommand={async () => "Rewritten text"}
+        aiCommandMenu={{ title: "AI Toolkit examples", placement: "toolbar" }}
+        toolbar={{ ai: true, layout: "compact", insert: false, alignment: false, lists: false, textStyle: false }}
+      />,
+    );
+    await screen.findByRole("textbox", { name: "Rich text editor" });
+    await user.click(screen.getByRole("button", { name: "AI commands" }));
+    expect(screen.getByRole("dialog", { name: "AI Toolkit examples" })).toBeInTheDocument();
+  });
+
+  it("expands to fullscreen on focus when mobileFullscreen is enabled", async () => {
+    vi.stubGlobal(
+      "matchMedia",
+      vi.fn().mockImplementation((query: string) => ({
+        matches: query.includes("max-width: 767px"),
+        media: query,
+        addEventListener: vi.fn(),
+        removeEventListener: vi.fn(),
+        addListener: vi.fn(),
+        removeListener: vi.fn(),
+        dispatchEvent: vi.fn(),
+      })),
+    );
+
+    const user = userEvent.setup();
+    render(
+      <ControlledEditor
+        mobileFullscreen
+        initial="<p>Mobile edit</p>"
+        toolbar={{ ai: false, layout: "compact" }}
+      />,
+    );
+    const surface = await screen.findByRole("textbox", { name: "Rich text editor" });
+    await user.click(surface);
+    await waitFor(() => {
+      expect(screen.getByRole("button", { name: "Done" })).toBeInTheDocument();
+    });
+
+    vi.unstubAllGlobals();
+  });
+
+  it("invokes onAiSelectionAction when text is selected", async () => {
+    const onAiSelectionAction = vi.fn(async () => "Rewritten text");
+    render(
+      <ControlledEditor
+        initial="<p>Selected text</p>"
+        onAiSelectionAction={onAiSelectionAction}
+        aiCommandMenu={false}
+        aiActions={[{ id: "improve", label: "Improve writing" }]}
+        toolbar={{ ai: true, layout: "compact", insert: false, alignment: false, lists: false, textStyle: false }}
+      />,
+    );
+    await screen.findByRole("textbox", { name: "Rich text editor" });
+    await screen.getByLabelText("Improve writing").click();
+    expect(onAiSelectionAction).not.toHaveBeenCalled();
+  });
+});

package/src/composites/SpatikaEditor.tsx

@@ -0,0 +1,302 @@
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { createPortal } from "react-dom";
+import { EditorContent } from "@tiptap/react";
+import type { MentionStorage } from "../extensions/mention";
+import type { SlashCommandStorage } from "../extensions/slash-command";
+import { defaultSlashCommands } from "../extensions/slash-command";
+import { cn } from "../lib/cn";
+import type { SpatikaEditorHandle, SpatikaEditorProps } from "../lib/types";
+import { DEFAULT_TOOLBAR } from "../lib/types";
+import {
+  DEFAULT_AI_ACTIONS,
+  resolveAiCommandActions,
+  resolveAiCommandPlacement,
+  usesAiCommandMenu,
+} from "../lib/ai-command-menu";
+import { useSpatikaEditor } from "../lib/use-spatika-editor";
+import { AiCommandDock } from "./AiCommandDock";
+import { AiOverlay } from "./AiOverlay";
+import { EditorBubbleMenu } from "./EditorBubbleMenu";
+import { EditorToolbar } from "./EditorToolbar";
+import { ImageBubbleMenu } from "./ImageBubbleMenu";
+import { MentionMenu } from "./MentionMenu";
+import { SlashCommandMenu } from "./SlashCommandMenu";
+
+const DEFAULT_AI_ACTIONS_LEGACY = DEFAULT_AI_ACTIONS;
+
+export const SpatikaEditor = forwardRef<SpatikaEditorHandle, SpatikaEditorProps>(
+  function SpatikaEditor(
+    {
+      value,
+      onChange,
+      placeholder,
+      disabled,
+      className,
+      heightClassName = "min-h-[400px]",
+      toolbar,
+      toolbarActions,
+      extensions,
+      starterKit,
+      slashCommands,
+      mentions,
+      onAiSelectionAction,
+      onAiCommand,
+      isAiProcessing,
+      aiActions = DEFAULT_AI_ACTIONS_LEGACY,
+      aiCommandMenu,
+      imageInsert,
+      onInsertImage,
+      resizableImages = true,
+      mobileFullscreen = false,
+    },
+    ref,
+  ) {
+    const shellRef = useRef<HTMLDivElement>(null);
+    const [fullscreen, setFullscreen] = useState(false);
+    const [slashState, setSlashState] = useState<SlashCommandStorage | null>(null);
+    const [mentionState, setMentionState] = useState<MentionStorage | null>(null);
+    const [aiBusyInternal, setAiBusyInternal] = useState(false);
+
+    const { editor, isReady } = useSpatikaEditor({
+      value,
+      onChange,
+      placeholder,
+      disabled,
+      extensions,
+      starterKit,
+      slashCommands,
+      mentions,
+      onAiSelectionAction,
+      onAiCommand,
+      resizableImages,
+      imageInsert,
+      onSlashUpdate: setSlashState,
+      onMentionUpdate: setMentionState,
+    });
+
+    useImperativeHandle(
+      ref,
+      () => ({
+        focus: () => editor?.commands.focus(),
+        setContent: (html: string) => editor?.commands.setContent(html),
+        getHTML: () => editor?.getHTML() ?? "",
+        getJSON: () => editor?.getJSON(),
+        expandFullscreen: () => setFullscreen(true),
+      }),
+      [editor],
+    );
+
+    const toolbarConfig = { ...DEFAULT_TOOLBAR, ...toolbar };
+    const allSlashCommands = useMemo(
+      () => [...defaultSlashCommands(), ...(slashCommands ?? [])],
+      [slashCommands],
+    );
+
+    const filteredSlashItems = useMemo(() => {
+      const query = slashState?.query?.toLowerCase() ?? "";
+      return allSlashCommands.filter((item) => {
+        if (!query) return true;
+        const haystack = [item.title, item.description, ...(item.keywords ?? [])]
+          .filter(Boolean)
+          .join(" ")
+          .toLowerCase();
+        return haystack.includes(query);
+      });
+    }, [allSlashCommands, slashState?.query]);
+
+    const filteredMentions = useMemo(() => {
+      const query = mentionState?.query?.toLowerCase() ?? "";
+      const contacts = mentions ?? [];
+      return contacts.filter((contact) => contact.label.toLowerCase().includes(query));
+    }, [mentions, mentionState?.query]);
+
+    const aiHandler = onAiCommand
+      ? onAiCommand
+      : onAiSelectionAction
+        ? async (context: import("../lib/types").AiCommandContext) =>
+            onAiSelectionAction(context.actionId, context.selectedText)
+        : undefined;
+
+    const commandMenuEnabled = usesAiCommandMenu(aiCommandMenu, Boolean(aiHandler));
+    const aiCommandPlacement = resolveAiCommandPlacement(aiCommandMenu);
+    const toolbarAiEnabled = commandMenuEnabled && aiCommandPlacement === "toolbar";
+    const dockAiEnabled = commandMenuEnabled && aiCommandPlacement === "dock";
+    const commandActions = resolveAiCommandActions(
+      aiCommandMenu === false ? undefined : aiCommandMenu,
+      aiActions,
+    );
+    const bubbleActionsEnabled =
+      Boolean(aiHandler) &&
+      (commandMenuEnabled
+        ? aiCommandMenu !== false && aiCommandMenu?.bubbleActions
+        : true);
+
+    const runAiCommand = useCallback(
+      async (request: { actionId: string; prompt?: string }) => {
+        if (!editor || !aiHandler) return;
+        const { from, to } = editor.state.selection;
+        const selectedText = from !== to ? editor.state.doc.textBetween(from, to, " ") : "";
+        editor.commands.setAiSelection?.(from !== to ? { from, to } : null);
+        editor.commands.setAiProcessing?.(true);
+        setAiBusyInternal(true);
+        try {
+          const result = await aiHandler({
+            actionId: request.actionId,
+            prompt: request.prompt,
+            selectedText,
+            documentText: editor.state.doc.textContent,
+            html: editor.getHTML(),
+            selection: from !== to ? { from, to } : null,
+          });
+          if (result) {
+            if (from !== to) {
+              editor.chain().focus().insertContentAt({ from, to }, result).run();
+            } else {
+              editor.chain().focus().insertContentAt(from, result).run();
+            }
+          }
+        } finally {
+          editor.commands.setAiProcessing?.(false);
+          editor.commands.setAiSelection?.(null);
+          setAiBusyInternal(false);
+        }
+      },
+      [editor, aiHandler],
+    );
+
+    const runLegacyAiAction = useCallback(
+      async (actionId: string) => {
+        if (!editor) return;
+        const { from, to } = editor.state.selection;
+        if (from === to) return;
+        await runAiCommand({ actionId });
+      },
+      [editor, runAiCommand],
+    );
+
+    useEffect(() => {
+      if (!mobileFullscreen || !editor) return;
+      const onFocus = () => {
+        if (window.matchMedia("(max-width: 767px)").matches) {
+          setFullscreen(true);
+        }
+      };
+      editor.on("focus", onFocus);
+      return () => {
+        editor.off("focus", onFocus);
+      };
+    }, [editor, mobileFullscreen]);
+
+    const shell = (
+      <div
+        ref={shellRef}
+        data-slot="spatika-editor"
+        className={cn(
+          "spk-editor-shell",
+          disabled && "spk-editor-shell--disabled",
+          fullscreen && "spk-editor-shell--fullscreen",
+          dockAiEnabled && "spk-editor-shell--with-ai-dock",
+          className,
+        )}
+      >
+        <EditorToolbar
+          editor={editor}
+          config={toolbarConfig}
+          toolbarActions={toolbarActions}
+          aiActions={
+            toolbarAiEnabled ? commandActions : !commandMenuEnabled ? aiActions : undefined
+          }
+          aiCommandMenu={aiCommandMenu === false ? false : aiCommandMenu}
+          useAiCommandMenu={toolbarAiEnabled}
+          onAiCommand={commandMenuEnabled ? runAiCommand : undefined}
+          onAiAction={!commandMenuEnabled ? runLegacyAiAction : undefined}
+          onInsertImage={onInsertImage}
+          imageInsert={imageInsert}
+        />
+        <div className="spk-editor-body">
+          <EditorContent
+            editor={editor}
+            className={cn("spk-editor-surface", heightClassName)}
+          />
+          <EditorBubbleMenu
+            editor={editor}
+            aiActions={bubbleActionsEnabled ? (commandMenuEnabled ? commandActions : aiActions) : undefined}
+            onAiAction={runLegacyAiAction}
+          />
+          <ImageBubbleMenu editor={editor} />
+          <SlashCommandMenu
+            editor={editor}
+            items={filteredSlashItems}
+            query={slashState?.query ?? ""}
+            activeIndex={slashState?.activeIndex ?? 0}
+            open={Boolean(slashState?.range)}
+            onSelect={(item) => {
+              if (!editor || !slashState?.range) return;
+              editor.chain().focus().deleteRange(slashState.range).run();
+              item.command(editor);
+              setSlashState(null);
+            }}
+          />
+          <MentionMenu
+            contacts={filteredMentions}
+            query={mentionState?.query ?? ""}
+            activeIndex={mentionState?.activeIndex ?? 0}
+            open={Boolean(mentionState?.range)}
+            onSelect={(contact) => {
+              if (!editor || !mentionState?.range) return;
+              editor
+                .chain()
+                .focus()
+                .insertContentAt(mentionState.range, [
+                  { type: "mention", attrs: { id: contact.id, label: contact.label } },
+                  { type: "text", text: " " },
+                ])
+                .run();
+              setMentionState(null);
+            }}
+          />
+          <AiOverlay visible={Boolean(isAiProcessing || aiBusyInternal)} />
+        </div>
+        {dockAiEnabled ? (
+          <div className="spk-editor-ai-dock-footer">
+            <AiCommandDock
+              editor={editor}
+              config={aiCommandMenu === false ? undefined : aiCommandMenu}
+              actions={commandActions}
+              onRun={runAiCommand}
+            />
+          </div>
+        ) : null}
+        {fullscreen ? (
+          <div className="spk-editor-fullscreen-bar">
+            <button type="button" className="spk-editor-fullscreen-close" onClick={() => setFullscreen(false)}>
+              Done
+            </button>
+          </div>
+        ) : null}
+      </div>
+    );
+
+    if (fullscreen && typeof document !== "undefined") {
+      return createPortal(shell, document.body);
+    }
+
+    if (!isReady) {
+      return (
+        <div className={cn("spk-editor-shell spk-editor-shell--loading", className)} aria-busy="true">
+          Loading editor…
+        </div>
+      );
+    }
+
+    return shell;
+  },
+);

package/src/composites/TableGridPicker.test.tsx

@@ -0,0 +1,26 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import { TableGridPicker } from "./TableGridPicker";
+
+describe("TableGridPicker", () => {
+  it("updates the preview label while hovering the grid", () => {
+    const onInsert = vi.fn();
+    render(<TableGridPicker onInsert={onInsert} />);
+
+    expect(screen.getByText("3 × 3")).toBeInTheDocument();
+
+    const cell = screen.getByRole("gridcell", { name: "5 by 4 table" });
+    fireEvent.mouseMove(cell);
+
+    expect(screen.getByText("5 × 4")).toBeInTheDocument();
+  });
+
+  it("inserts on grid click", async () => {
+    const onInsert = vi.fn();
+    render(<TableGridPicker onInsert={onInsert} />);
+
+    await userEvent.click(screen.getByRole("gridcell", { name: "5 by 4 table" }));
+    expect(onInsert).toHaveBeenCalledWith(4, 5, true);
+  });
+});