@spatika/editor 1.5.0

package/package.json

@@ -0,0 +1,101 @@
+{
+  "name": "@spatika/editor",
+  "version": "1.5.0",
+  "license": "MIT",
+  "description": "Spatika UI — Tiptap-powered rich text editor with glass theming, AI hooks, and extensible toolbar",
+  "homepage": "https://spatika.sweyam.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SreelalChalil/spatika.git",
+    "directory": "packages/editor"
+  },
+  "bugs": {
+    "url": "https://github.com/SreelalChalil/spatika/issues"
+  },
+  "author": "Sreelal Chalil",
+  "keywords": [
+    "spatika",
+    "editor",
+    "tiptap",
+    "rich-text",
+    "react",
+    "glass",
+    "design-system"
+  ],
+  "type": "module",
+  "sideEffects": [
+    "*.css"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./styles.css": "./dist/styles.css",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && cp src/styles/editor.css dist/styles.css",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": "^18.2.0 || ^19.0.0",
+    "react-dom": "^18.2.0 || ^19.0.0"
+  },
+  "dependencies": {
+    "@spatika/tokens": "1.5.0",
+    "@tiptap/core": "^3.28.0",
+    "@tiptap/extension-bubble-menu": "^3.28.0",
+    "@tiptap/extension-color": "^3.30.5",
+    "@tiptap/extension-highlight": "^3.30.5",
+    "@tiptap/extension-image": "^3.28.0",
+    "@tiptap/extension-link": "^3.28.0",
+    "@tiptap/extension-placeholder": "^3.28.0",
+    "@tiptap/extension-subscript": "^3.30.5",
+    "@tiptap/extension-superscript": "^3.30.5",
+    "@tiptap/extension-table": "^3.28.0",
+    "@tiptap/extension-table-cell": "^3.28.0",
+    "@tiptap/extension-table-header": "^3.28.0",
+    "@tiptap/extension-table-row": "^3.28.0",
+    "@tiptap/extension-task-item": "^3.30.5",
+    "@tiptap/extension-task-list": "^3.30.5",
+    "@tiptap/extension-text-align": "^3.28.0",
+    "@tiptap/extension-text-style": "^3.30.5",
+    "@tiptap/extension-underline": "^3.28.0",
+    "@tiptap/pm": "^3.28.0",
+    "@tiptap/react": "^3.28.0",
+    "@tiptap/starter-kit": "^3.28.0",
+    "@tiptap/suggestion": "^3.28.0",
+    "clsx": "^2.1.1",
+    "lucide-react": "^0.487.0",
+    "tailwind-merge": "^3.2.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitest/coverage-v8": "^4.1.10",
+    "jsdom": "^30.0.1",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "typescript": "~5.8.3",
+    "vitest": "^4.1.10"
+  }
+}

package/src/composites/AiCommandDock.test.tsx

@@ -0,0 +1,48 @@
+import type { Editor } from "@tiptap/core";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import { AI_PROMPT_ACTION_ID } from "../lib/types";
+import { AiCommandDock } from "./AiCommandDock";
+
+function createEditor(hasSelection = false) {
+  return {
+    state: {
+      selection: { empty: !hasSelection },
+    },
+  } as unknown as Editor;
+}
+
+describe("AiCommandDock", () => {
+  it("opens the Tiptap-style action panel from the dock", async () => {
+    render(
+      <AiCommandDock
+        editor={createEditor()}
+        config={{ title: "AI Toolkit examples" }}
+        onRun={vi.fn()}
+      />,
+    );
+
+    await userEvent.click(screen.getByRole("button", { name: "AI commands" }));
+    expect(screen.getByRole("dialog", { name: "AI Toolkit examples" })).toBeInTheDocument();
+    expect(
+      screen.getByPlaceholderText("Ask about this document or request a change…"),
+    ).toBeInTheDocument();
+  });
+
+  it("submits a prompt from the dock bar", async () => {
+    const onRun = vi.fn();
+    render(<AiCommandDock editor={createEditor()} onRun={onRun} />);
+
+    await userEvent.type(
+      screen.getByPlaceholderText("Ask about this document or request a change…"),
+      "Summarize this doc",
+    );
+    await userEvent.click(screen.getByRole("button", { name: "Send" }));
+
+    expect(onRun).toHaveBeenCalledWith({
+      actionId: AI_PROMPT_ACTION_ID,
+      prompt: "Summarize this doc",
+    });
+  });
+});

package/src/composites/AiCommandDock.tsx

@@ -0,0 +1,137 @@
+import type { Editor } from "@tiptap/core";
+import {
+  ArrowLeft,
+  ArrowUp,
+  MessageSquarePlus,
+  PenLine,
+  Plus,
+  Search,
+  Sparkles,
+  Table2,
+} from "lucide-react";
+import { useEffect, useId, useRef, useState } from "react";
+import {
+  resolveAiCommandActions,
+  resolveAiPromptConfig,
+} from "../lib/ai-command-menu";
+import type { AiActionDefinition, AiCommandMenuConfig } from "../lib/types";
+import { AI_PROMPT_ACTION_ID } from "../lib/types";
+import { cn } from "../lib/cn";
+import { AiCommandPanel } from "./AiCommandPanel";
+import type { AiCommandRunRequest } from "./AiCommandMenu";
+
+const DEFAULT_ACTION_ICONS: Record<string, AiActionDefinition["icon"]> = {
+  proofread: <Search className="size-4" />,
+  rewrite: <PenLine className="size-4" />,
+  shorten: <ArrowLeft className="size-4" />,
+  improve: <Sparkles className="size-4" />,
+  expand: <Plus className="size-4" />,
+  continue: <Plus className="size-4" />,
+  table: <Table2 className="size-4" />,
+  comment: <MessageSquarePlus className="size-4" />,
+};
+
+function withDefaultIcons(actions: AiActionDefinition[]) {
+  return actions.map((action) => ({
+    ...action,
+    icon: action.icon ?? DEFAULT_ACTION_ICONS[action.id],
+  }));
+}
+
+type AiCommandDockProps = {
+  editor: Editor | null;
+  config?: AiCommandMenuConfig;
+  actions?: AiActionDefinition[];
+  onRun: (request: AiCommandRunRequest) => void;
+  className?: string;
+};
+
+export function AiCommandDock({ editor, config, actions, onRun, className }: AiCommandDockProps) {
+  const [open, setOpen] = useState(false);
+  const [prompt, setPrompt] = useState("");
+  const rootRef = useRef<HTMLDivElement>(null);
+  const panelId = useId();
+
+  const title = config?.title ?? "AI Toolkit examples";
+  const commandActions = withDefaultIcons(resolveAiCommandActions(config, actions));
+  const promptConfig = resolveAiPromptConfig(config?.prompt);
+  const hasSelection = Boolean(editor?.state?.selection && !editor.state.selection.empty);
+
+  useEffect(() => {
+    if (!open) return;
+    const onPointerDown = (event: MouseEvent) => {
+      if (!rootRef.current?.contains(event.target as Node)) {
+        setOpen(false);
+      }
+    };
+    document.addEventListener("mousedown", onPointerDown);
+    return () => document.removeEventListener("mousedown", onPointerDown);
+  }, [open]);
+
+  const runAction = (actionId: string, userPrompt?: string) => {
+    onRun({ actionId, prompt: userPrompt });
+    setOpen(false);
+    setPrompt("");
+  };
+
+  const submitPrompt = () => {
+    const trimmed = prompt.trim();
+    if (!trimmed) return;
+    runAction(AI_PROMPT_ACTION_ID, trimmed);
+  };
+
+  if (!editor) return null;
+
+  return (
+    <div ref={rootRef} className={cn("spk-editor-ai-dock", className)}>
+      {open ? (
+        <AiCommandPanel
+          id={panelId}
+          title={title}
+          actions={commandActions}
+          hasSelection={hasSelection}
+          onSelect={(actionId) => runAction(actionId)}
+          className="spk-editor-ai-dock-panel"
+        />
+      ) : null}
+      {promptConfig.enabled ? (
+        <div className="spk-editor-ai-dock-bar" role="search">
+          <button
+            type="button"
+            className={cn("spk-editor-ai-dock-trigger", open && "spk-editor-ai-dock-trigger--active")}
+            aria-label="AI commands"
+            aria-expanded={open}
+            aria-controls={open ? panelId : undefined}
+            onClick={() => setOpen((value) => !value)}
+          >
+            <Sparkles className="size-4" />
+          </button>
+          <label className="spk-editor-ai-dock-field">
+            <span className="sr-only">{promptConfig.placeholder}</span>
+            <input
+              type="text"
+              className="spk-editor-ai-dock-input"
+              value={prompt}
+              placeholder={promptConfig.placeholder}
+              onFocus={() => setOpen(true)}
+              onChange={(event) => setPrompt(event.target.value)}
+              onKeyDown={(event) => {
+                if (event.key === "Enter") submitPrompt();
+                if (event.key === "Escape") setOpen(false);
+              }}
+            />
+          </label>
+          <button
+            type="button"
+            className="spk-editor-ai-dock-submit"
+            aria-label={promptConfig.submitLabel}
+            disabled={!prompt.trim()}
+            onClick={submitPrompt}
+          >
+            <ArrowUp className="size-4" />
+          </button>
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/src/composites/AiCommandMenu.test.tsx

@@ -0,0 +1,67 @@
+import type { Editor } from "@tiptap/core";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import { AI_PROMPT_ACTION_ID } from "../lib/types";
+import { AiCommandMenu } from "./AiCommandMenu";
+
+function createEditor(hasSelection = false) {
+  return {
+    state: {
+      selection: { empty: !hasSelection },
+    },
+  } as unknown as Editor;
+}
+
+describe("AiCommandMenu", () => {
+  it("opens the customizable command menu", async () => {
+    const onRun = vi.fn();
+    render(
+      <AiCommandMenu
+        editor={createEditor()}
+        config={{ title: "Journal AI" }}
+        onRun={onRun}
+      />,
+    );
+    await userEvent.click(screen.getByRole("button", { name: "AI commands" }));
+    expect(screen.getByRole("dialog", { name: "Journal AI" })).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "Proofread selection" })).toBeDisabled();
+  });
+
+  it("runs preset actions and prompt submissions", async () => {
+    const onRun = vi.fn();
+    render(
+      <AiCommandMenu
+        editor={createEditor(true)}
+        config={{
+          actions: [{ id: "rewrite", label: "Rewrite selection", requiresSelection: true }],
+          prompt: { placeholder: "Ask the doc…", submitLabel: "Run" },
+        }}
+        onRun={onRun}
+      />,
+    );
+    await userEvent.click(screen.getByRole("button", { name: "AI commands" }));
+    await userEvent.click(screen.getByRole("button", { name: "Rewrite selection" }));
+    expect(onRun).toHaveBeenCalledWith({ actionId: "rewrite", prompt: undefined });
+
+    await userEvent.click(screen.getByRole("button", { name: "AI commands" }));
+    await userEvent.type(screen.getByPlaceholderText("Ask the doc…"), "Add a summary");
+    await userEvent.click(screen.getByRole("button", { name: "Run" }));
+    expect(onRun).toHaveBeenLastCalledWith({
+      actionId: AI_PROMPT_ACTION_ID,
+      prompt: "Add a summary",
+    });
+  });
+
+  it("hides the prompt field when disabled", async () => {
+    render(
+      <AiCommandMenu
+        editor={createEditor()}
+        config={{ prompt: false }}
+        onRun={vi.fn()}
+      />,
+    );
+    await userEvent.click(screen.getByRole("button", { name: "AI commands" }));
+    expect(screen.queryByRole("button", { name: "Send" })).not.toBeInTheDocument();
+  });
+});

package/src/composites/AiCommandMenu.tsx

@@ -0,0 +1,120 @@
+import type { Editor } from "@tiptap/core";
+import { ArrowUp, Sparkles } from "lucide-react";
+import { useEffect, useId, useRef, useState } from "react";
+import {
+  resolveAiCommandActions,
+  resolveAiPromptConfig,
+} from "../lib/ai-command-menu";
+import type { AiActionDefinition, AiCommandMenuConfig } from "../lib/types";
+import { AI_PROMPT_ACTION_ID } from "../lib/types";
+import { cn } from "../lib/cn";
+import { AiCommandPanel } from "./AiCommandPanel";
+import { ToolbarButton } from "./ToolbarButton";
+
+export type AiCommandRunRequest = {
+  actionId: string;
+  prompt?: string;
+};
+
+type AiCommandMenuProps = {
+  editor: Editor | null;
+  config?: AiCommandMenuConfig;
+  actions?: AiActionDefinition[];
+  onRun: (request: AiCommandRunRequest) => void;
+  className?: string;
+};
+
+export function AiCommandMenu({ editor, config, actions, onRun, className }: AiCommandMenuProps) {
+  const [open, setOpen] = useState(false);
+  const [prompt, setPrompt] = useState("");
+  const rootRef = useRef<HTMLDivElement>(null);
+  const titleId = useId();
+
+  const title = config?.title ?? "AI Toolkit examples";
+  const commandActions = resolveAiCommandActions(config, actions);
+  const promptConfig = resolveAiPromptConfig(config?.prompt);
+  const hasSelection = Boolean(editor?.state?.selection && !editor.state.selection.empty);
+
+  useEffect(() => {
+    if (!open) return;
+    const onPointerDown = (event: MouseEvent) => {
+      if (!rootRef.current?.contains(event.target as Node)) {
+        setOpen(false);
+      }
+    };
+    document.addEventListener("mousedown", onPointerDown);
+    return () => document.removeEventListener("mousedown", onPointerDown);
+  }, [open]);
+
+  const close = () => {
+    setOpen(false);
+    setPrompt("");
+  };
+
+  const runAction = (actionId: string, userPrompt?: string) => {
+    onRun({ actionId, prompt: userPrompt });
+    close();
+  };
+
+  const submitPrompt = () => {
+    const trimmed = prompt.trim();
+    if (!trimmed) return;
+    runAction(AI_PROMPT_ACTION_ID, trimmed);
+  };
+
+  if (!editor) return null;
+
+  return (
+    <div ref={rootRef} className={cn("spk-editor-ai-menu", className)}>
+      <ToolbarButton
+        aria-label="AI commands"
+        aria-expanded={open}
+        aria-haspopup="dialog"
+        aria-controls={open ? titleId : undefined}
+        active={open}
+        onClick={() => setOpen((value) => !value)}
+      >
+        <Sparkles className="size-4" />
+      </ToolbarButton>
+      {open ? (
+        <div className="spk-editor-ai-menu-shell" onMouseDown={(event) => event.stopPropagation()}>
+          <AiCommandPanel
+            id={titleId}
+            title={title}
+            actions={commandActions}
+            hasSelection={hasSelection}
+            onSelect={(actionId) => runAction(actionId)}
+          />
+          {promptConfig.enabled ? (
+            <div className="spk-editor-ai-menu-prompt">
+              <label className="spk-editor-ai-menu-prompt-field">
+                <span className="sr-only">{promptConfig.placeholder}</span>
+                <input
+                  type="text"
+                  className="spk-editor-ai-menu-prompt-input"
+                  value={prompt}
+                  placeholder={promptConfig.placeholder}
+                  onChange={(event) => setPrompt(event.target.value)}
+                  onKeyDown={(event) => {
+                    if (event.key === "Enter") submitPrompt();
+                    if (event.key === "Escape") close();
+                  }}
+                  autoFocus
+                />
+              </label>
+              <button
+                type="button"
+                className="spk-editor-ai-menu-prompt-submit"
+                aria-label={promptConfig.submitLabel}
+                disabled={!prompt.trim()}
+                onClick={submitPrompt}
+              >
+                <ArrowUp className="size-4" />
+              </button>
+            </div>
+          ) : null}
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/src/composites/AiCommandPanel.test.tsx

@@ -0,0 +1,42 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import { AiCommandPanel } from "./AiCommandPanel";
+
+const actions = [
+  { id: "rewrite", label: "Rewrite selection", requiresSelection: true },
+  { id: "continue", label: "Write a new paragraph", description: "Draft below the cursor" },
+];
+
+describe("AiCommandPanel", () => {
+  it("renders the action list in a dialog", () => {
+    render(
+      <AiCommandPanel
+        title="AI Toolkit examples"
+        actions={actions}
+        hasSelection={false}
+        onSelect={vi.fn()}
+      />,
+    );
+
+    expect(screen.getByRole("dialog", { name: "AI Toolkit examples" })).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "Rewrite selection" })).toBeDisabled();
+    expect(screen.getByRole("button", { name: /Write a new paragraph/i })).toBeEnabled();
+    expect(screen.getByText("Draft below the cursor")).toBeInTheDocument();
+  });
+
+  it("calls onSelect for enabled actions", async () => {
+    const onSelect = vi.fn();
+    render(
+      <AiCommandPanel
+        title="AI Toolkit examples"
+        actions={actions}
+        hasSelection
+        onSelect={onSelect}
+      />,
+    );
+
+    await userEvent.click(screen.getByRole("button", { name: "Rewrite selection" }));
+    expect(onSelect).toHaveBeenCalledWith("rewrite");
+  });
+});

package/src/composites/AiCommandPanel.tsx

@@ -0,0 +1,56 @@
+import type { AiActionDefinition } from "../lib/types";
+import { Sparkles } from "lucide-react";
+import { cn } from "../lib/cn";
+
+type AiCommandPanelProps = {
+  title: string;
+  actions: AiActionDefinition[];
+  hasSelection: boolean;
+  onSelect: (actionId: string) => void;
+  className?: string;
+  id?: string;
+};
+
+function actionDisabled(action: AiActionDefinition, hasSelection: boolean) {
+  return Boolean(action.requiresSelection && !hasSelection);
+}
+
+export function AiCommandPanel({
+  title,
+  actions,
+  hasSelection,
+  onSelect,
+  className,
+  id,
+}: AiCommandPanelProps) {
+  return (
+    <div id={id} className={cn("spk-editor-ai-panel", className)} role="dialog" aria-label={title}>
+      <div className="spk-editor-ai-panel-title">{title}</div>
+      <ul className="spk-editor-ai-panel-list" aria-label={title}>
+        {actions.map((action) => {
+          const disabled = actionDisabled(action, hasSelection);
+          return (
+            <li key={action.id}>
+              <button
+                type="button"
+                className="spk-editor-ai-panel-item"
+                disabled={disabled}
+                onClick={() => onSelect(action.id)}
+              >
+                <span className="spk-editor-ai-panel-item-icon" aria-hidden="true">
+                  {action.icon ?? <Sparkles className="size-4" />}
+                </span>
+                <span className="spk-editor-ai-panel-item-copy">
+                  <span className="spk-editor-ai-panel-item-label">{action.label}</span>
+                  {action.description ? (
+                    <span className="spk-editor-ai-panel-item-desc">{action.description}</span>
+                  ) : null}
+                </span>
+              </button>
+            </li>
+          );
+        })}
+      </ul>
+    </div>
+  );
+}

package/src/composites/AiOverlay.test.tsx

@@ -0,0 +1,18 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { AiOverlay } from "./AiOverlay";
+
+describe("AiOverlay", () => {
+  it("renders nothing when not visible", () => {
+    const { container } = render(<AiOverlay visible={false} />);
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it("shows the AI working message when visible", () => {
+    render(<AiOverlay visible className="custom-overlay" />);
+    expect(screen.getByText("AI is working…")).toBeInTheDocument();
+    expect(screen.getByText("AI is working…").closest(".spk-editor-ai-overlay")).toHaveClass(
+      "custom-overlay",
+    );
+  });
+});

package/src/composites/AiOverlay.tsx

@@ -0,0 +1,18 @@
+import { Sparkles } from "lucide-react";
+import { cn } from "../lib/cn";
+
+type AiOverlayProps = {
+  visible: boolean;
+  className?: string;
+};
+
+export function AiOverlay({ visible, className }: AiOverlayProps) {
+  if (!visible) return null;
+
+  return (
+    <div className={cn("spk-editor-ai-overlay", className)} aria-hidden="true">
+      <Sparkles className="spk-editor-ai-overlay-icon size-5" />
+      <span>AI is working…</span>
+    </div>
+  );
+}

package/src/composites/EditorBubbleMenu.test.tsx

@@ -0,0 +1,49 @@
+import type { Editor } from "@tiptap/core";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import { EditorBubbleMenu } from "./EditorBubbleMenu";
+
+vi.mock("@tiptap/react/menus", () => ({
+  BubbleMenu: ({ children }: { children: React.ReactNode }) => (
+    <div role="group" aria-label="Bubble menu">
+      {children}
+    </div>
+  ),
+}));
+
+function createEditor() {
+  const run = vi.fn();
+  const chain = {
+    focus: vi.fn().mockReturnThis(),
+    toggleBold: vi.fn().mockReturnThis(),
+    toggleItalic: vi.fn().mockReturnThis(),
+    toggleUnderline: vi.fn().mockReturnThis(),
+    run,
+  };
+  return {
+    isActive: vi.fn().mockReturnValue(false),
+    chain: vi.fn(() => chain),
+  } as unknown as Editor;
+}
+
+describe("EditorBubbleMenu", () => {
+  it("returns null without an editor", () => {
+    const { container } = render(<EditorBubbleMenu editor={null} />);
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it("toggles bold from the bubble menu", async () => {
+    const editor = createEditor();
+    render(
+      <EditorBubbleMenu
+        editor={editor}
+        aiActions={[{ id: "improve", label: "Improve writing" }]}
+        onAiAction={vi.fn()}
+      />,
+    );
+    await userEvent.click(screen.getByRole("button", { name: "Bold" }));
+    expect(editor.chain).toHaveBeenCalled();
+    expect(screen.getByRole("button", { name: "Improve writing" })).toBeInTheDocument();
+  });
+});