@spatika/editor 1.5.0

package/src/extensions/slash-command.ts

@@ -0,0 +1,197 @@
+import { Extension } from "@tiptap/core";
+import { PluginKey } from "@tiptap/pm/state";
+import Suggestion, { type SuggestionOptions } from "@tiptap/suggestion";
+import type { SlashCommandItem } from "../lib/types";
+
+export type SlashCommandStorage = {
+  items: SlashCommandItem[];
+  activeIndex: number;
+  query: string;
+  range: { from: number; to: number } | null;
+  filteredItems: SlashCommandItem[];
+  runCommand: ((item: SlashCommandItem) => void) | null;
+};
+
+export const SlashCommandPluginKey = new PluginKey("spatikaSlashCommand");
+
+export function createSlashCommandExtension(
+  items: SlashCommandItem[],
+  onUpdate?: (state: SlashCommandStorage) => void,
+) {
+  return Extension.create({
+    name: "slashCommand",
+
+    addStorage() {
+      return {
+        items,
+        activeIndex: 0,
+        query: "",
+        range: null,
+        filteredItems: items,
+        runCommand: null,
+      } satisfies SlashCommandStorage;
+    },
+
+    addProseMirrorPlugins() {
+      const editor = this.editor;
+      const storage = this.storage as SlashCommandStorage;
+
+      const suggestion: Partial<SuggestionOptions<SlashCommandItem>> = {
+        char: "/",
+        pluginKey: SlashCommandPluginKey,
+        allowSpaces: true,
+        items: ({ query }) => {
+          const needle = query.toLowerCase();
+          return items.filter((item) => {
+            if (!needle) return true;
+            const haystack = [item.title, item.description, ...(item.keywords ?? [])]
+              .filter(Boolean)
+              .join(" ")
+              .toLowerCase();
+            return haystack.includes(needle);
+          });
+        },
+        command: ({ editor: ed, range, props }) => {
+          ed.chain().focus().deleteRange(range).run();
+          props.command(editor);
+        },
+        render: () => ({
+          onStart: (props) => {
+            storage.query = props.query;
+            storage.activeIndex = 0;
+            storage.range = props.range;
+            storage.filteredItems = props.items;
+            storage.runCommand = (item) => props.command(item);
+            onUpdate?.({ ...storage });
+          },
+          onUpdate: (props) => {
+            storage.query = props.query;
+            storage.activeIndex = 0;
+            storage.range = props.range;
+            storage.filteredItems = props.items;
+            storage.runCommand = (item) => props.command(item);
+            onUpdate?.({ ...storage });
+          },
+          onKeyDown: (props) => {
+            if (props.event.key === "ArrowUp") {
+              storage.activeIndex = Math.max(0, storage.activeIndex - 1);
+              onUpdate?.({ ...storage });
+              return true;
+            }
+            if (props.event.key === "ArrowDown") {
+              const max = storage.filteredItems.length - 1;
+              storage.activeIndex = Math.min(max, storage.activeIndex + 1);
+              onUpdate?.({ ...storage });
+              return true;
+            }
+            if (props.event.key === "Enter") {
+              const item = storage.filteredItems[storage.activeIndex];
+              if (item) storage.runCommand?.(item);
+              return true;
+            }
+            if (props.event.key === "Escape") {
+              storage.query = "";
+              storage.range = null;
+              onUpdate?.({ ...storage });
+              return true;
+            }
+            return false;
+          },
+          onExit: () => {
+            storage.query = "";
+            storage.range = null;
+            storage.activeIndex = 0;
+            storage.filteredItems = items;
+            storage.runCommand = null;
+            onUpdate?.({ ...storage });
+          },
+        }),
+      };
+
+      return [Suggestion({ editor, ...suggestion })];
+    },
+  });
+}
+
+export function defaultSlashCommands(): SlashCommandItem[] {
+  return [
+    {
+      id: "paragraph",
+      title: "Text",
+      description: "Plain paragraph",
+      keywords: ["p", "text"],
+      command: (editor) => editor.chain().focus().setParagraph().run(),
+    },
+    {
+      id: "h1",
+      title: "Heading 1",
+      description: "Large section title",
+      keywords: ["heading", "title"],
+      command: (editor) => editor.chain().focus().toggleHeading({ level: 1 }).run(),
+    },
+    {
+      id: "h2",
+      title: "Heading 2",
+      description: "Medium section title",
+      keywords: ["heading", "subtitle"],
+      command: (editor) => editor.chain().focus().toggleHeading({ level: 2 }).run(),
+    },
+    {
+      id: "h3",
+      title: "Heading 3",
+      description: "Small section title",
+      keywords: ["heading"],
+      command: (editor) => editor.chain().focus().toggleHeading({ level: 3 }).run(),
+    },
+    {
+      id: "bullet",
+      title: "Bullet list",
+      description: "Unordered list",
+      keywords: ["ul", "list"],
+      command: (editor) => editor.chain().focus().toggleBulletList().run(),
+    },
+    {
+      id: "ordered",
+      title: "Numbered list",
+      description: "Ordered list",
+      keywords: ["ol", "list"],
+      command: (editor) => editor.chain().focus().toggleOrderedList().run(),
+    },
+    {
+      id: "task",
+      title: "Task list",
+      description: "Checklist with todos",
+      keywords: ["todo", "checkbox", "task"],
+      command: (editor) => editor.chain().focus().toggleTaskList().run(),
+    },
+    {
+      id: "code-block",
+      title: "Code block",
+      description: "Monospace code snippet",
+      keywords: ["code", "pre", "snippet"],
+      command: (editor) => editor.chain().focus().toggleCodeBlock().run(),
+    },
+    {
+      id: "quote",
+      title: "Quote",
+      description: "Block quotation",
+      keywords: ["blockquote"],
+      command: (editor) => editor.chain().focus().toggleBlockquote().run(),
+    },
+    {
+      id: "divider",
+      title: "Divider",
+      description: "Horizontal rule",
+      keywords: ["hr", "line"],
+      command: (editor) => editor.chain().focus().setHorizontalRule().run(),
+    },
+    {
+      id: "table",
+      title: "Table",
+      description: "3×3 table with header",
+      keywords: ["grid"],
+      command: (editor) =>
+        editor.chain().focus().insertTable({ rows: 3, cols: 3, withHeaderRow: true }).run(),
+    },
+  ];
+}

package/src/index.ts

@@ -0,0 +1,49 @@
+export { SpatikaEditor } from "./composites/SpatikaEditor";
+export { EditorToolbar } from "./composites/EditorToolbar";
+export { EditorBubbleMenu } from "./composites/EditorBubbleMenu";
+export { ImageBubbleMenu } from "./composites/ImageBubbleMenu";
+export { SlashCommandMenu } from "./composites/SlashCommandMenu";
+export { MentionMenu } from "./composites/MentionMenu";
+export { AiCommandMenu } from "./composites/AiCommandMenu";
+export { AiCommandDock } from "./composites/AiCommandDock";
+export { AiCommandPanel } from "./composites/AiCommandPanel";
+export type { AiCommandRunRequest } from "./composites/AiCommandMenu";
+export { AiOverlay } from "./composites/AiOverlay";
+export { ToolbarButton } from "./composites/ToolbarButton";
+
+export { useSpatikaEditor, buildSpatikaExtensions } from "./lib/use-spatika-editor";
+
+export {
+  DEFAULT_AI_ACTIONS,
+  DEFAULT_AI_COMMANDS,
+  resolveAiCommandActions,
+  resolveAiCommandPlacement,
+  resolveAiPromptConfig,
+  usesAiCommandMenu,
+} from "./lib/ai-command-menu";
+
+export { createSlashCommandExtension, defaultSlashCommands } from "./extensions/slash-command";
+export { createMentionExtension } from "./extensions/mention";
+export { ResizableImage } from "./extensions/resizable-image";
+export { createAiActionExtension } from "./extensions/ai-action";
+
+export type {
+  SpatikaEditorProps,
+  SpatikaEditorHandle,
+  SpatikaEditorToolbarConfig,
+  SlashCommandItem,
+  MentionContact,
+  AiActionDefinition,
+  AiCommandContext,
+  AiCommandMenuConfig,
+  AiCommandPromptConfig,
+  ImageInsertConfig,
+  PlaceholderConfig,
+  UseSpatikaEditorOptions,
+} from "./lib/types";
+
+export { AI_PROMPT_ACTION_ID } from "./lib/types";
+
+export type { SlashCommandStorage } from "./extensions/slash-command";
+export type { MentionStorage } from "./extensions/mention";
+export type { ImageAlign } from "./extensions/resizable-image";

package/src/lib/ai-command-menu.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+import {
+  DEFAULT_AI_COMMANDS,
+  resolveAiCommandActions,
+  resolveAiCommandPlacement,
+  resolveAiPromptConfig,
+  usesAiCommandMenu,
+} from "./ai-command-menu";
+
+describe("ai-command-menu helpers", () => {
+  it("uses menu actions when provided", () => {
+    const actions = resolveAiCommandActions(
+      { actions: [{ id: "tone", label: "Adjust tone" }] },
+      [{ id: "legacy", label: "Legacy" }],
+    );
+    expect(actions).toEqual([{ id: "tone", label: "Adjust tone" }]);
+  });
+
+  it("falls back to aiActions then defaults", () => {
+    expect(resolveAiCommandActions(undefined, [{ id: "legacy", label: "Legacy" }])).toEqual([
+      { id: "legacy", label: "Legacy" },
+    ]);
+    expect(resolveAiCommandActions(undefined, undefined)).toEqual(DEFAULT_AI_COMMANDS);
+  });
+
+  it("resolves prompt config", () => {
+    expect(resolveAiPromptConfig(false)).toEqual({
+      enabled: false,
+      placeholder: "",
+      submitLabel: "Send",
+    });
+    expect(resolveAiPromptConfig({ placeholder: "Ask AI…" })).toMatchObject({
+      enabled: true,
+      placeholder: "Ask AI…",
+    });
+  });
+
+  it("enables the command menu when a handler exists", () => {
+    expect(usesAiCommandMenu(undefined, true)).toBe(true);
+    expect(usesAiCommandMenu(false, true)).toBe(false);
+    expect(usesAiCommandMenu(undefined, false)).toBe(false);
+  });
+
+  it("defaults AI placement to dock", () => {
+    expect(resolveAiCommandPlacement(undefined)).toBe("dock");
+    expect(resolveAiCommandPlacement({ placement: "toolbar" })).toBe("toolbar");
+  });
+});

package/src/lib/ai-command-menu.ts

@@ -0,0 +1,57 @@
+import type { AiActionDefinition, AiCommandMenuConfig, AiCommandPromptConfig } from "./types";
+
+export const DEFAULT_AI_COMMANDS: AiActionDefinition[] = [
+  { id: "proofread", label: "Proofread selection", requiresSelection: true },
+  { id: "rewrite", label: "Rewrite selection", requiresSelection: true },
+  { id: "shorten", label: "Make it shorter", requiresSelection: true },
+  { id: "improve", label: "Improve writing", requiresSelection: true },
+  { id: "expand", label: "Expand", requiresSelection: true },
+  { id: "continue", label: "Write a new paragraph", requiresSelection: false },
+];
+
+/** Legacy three-action set for toolbar/bubble buttons when `aiCommandMenu` is false. */
+export const DEFAULT_AI_ACTIONS: AiActionDefinition[] = [
+  { id: "improve", label: "Improve writing", requiresSelection: true },
+  { id: "shorten", label: "Make shorter", requiresSelection: true },
+  { id: "expand", label: "Expand", requiresSelection: true },
+];
+
+export function resolveAiCommandActions(
+  menu?: AiCommandMenuConfig | false,
+  actions?: AiActionDefinition[],
+): AiActionDefinition[] {
+  if (menu && typeof menu === "object" && menu.actions?.length) {
+    return menu.actions;
+  }
+  if (actions?.length) return actions;
+  return DEFAULT_AI_COMMANDS;
+}
+
+export function resolveAiPromptConfig(
+  prompt: AiCommandMenuConfig["prompt"] | undefined,
+): Required<AiCommandPromptConfig> {
+  if (prompt === false) {
+    return { enabled: false, placeholder: "", submitLabel: "Send" };
+  }
+  const config = prompt === true || prompt === undefined ? {} : prompt;
+  return {
+    enabled: config.enabled ?? true,
+    placeholder: config.placeholder ?? "Ask about this document or request a change…",
+    submitLabel: config.submitLabel ?? "Send",
+  };
+}
+
+export function resolveAiCommandPlacement(
+  menu?: AiCommandMenuConfig | false,
+): "toolbar" | "dock" {
+  if (menu === false) return "toolbar";
+  return menu?.placement ?? "dock";
+}
+
+export function usesAiCommandMenu(
+  aiCommandMenu: AiCommandMenuConfig | false | undefined,
+  hasHandler: boolean,
+): boolean {
+  if (!hasHandler) return false;
+  return aiCommandMenu !== false;
+}

package/src/lib/cn.ts

@@ -0,0 +1,7 @@
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+/** Merge Tailwind class names without conflicts. */
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/src/lib/editor-format-colors.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from "vitest";
+import { EDITOR_HIGHLIGHT_COLORS, EDITOR_TEXT_COLORS } from "./editor-format-colors";
+
+describe("editor-format-colors", () => {
+  it("includes a default/unset swatch for text and highlight", () => {
+    expect(EDITOR_TEXT_COLORS[0]?.value).toBeNull();
+    expect(EDITOR_HIGHLIGHT_COLORS[0]?.value).toBeNull();
+  });
+
+  it("defines readable preset palettes", () => {
+    expect(EDITOR_TEXT_COLORS.length).toBeGreaterThan(5);
+    expect(EDITOR_HIGHLIGHT_COLORS.length).toBeGreaterThan(4);
+    expect(EDITOR_TEXT_COLORS.every((color) => color.label.length > 0)).toBe(true);
+  });
+});

package/src/lib/editor-format-colors.ts

@@ -0,0 +1,31 @@
+export type EditorColorSwatch = {
+  id: string;
+  label: string;
+  value: string | null;
+};
+
+/** Preset text colors for the formatting toolbar. */
+export const EDITOR_TEXT_COLORS: EditorColorSwatch[] = [
+  { id: "default", label: "Default text color", value: null },
+  { id: "red", label: "Red text", value: "#dc2626" },
+  { id: "orange", label: "Orange text", value: "#ea580c" },
+  { id: "amber", label: "Amber text", value: "#d97706" },
+  { id: "green", label: "Green text", value: "#16a34a" },
+  { id: "teal", label: "Teal text", value: "#0d9488" },
+  { id: "blue", label: "Blue text", value: "#2563eb" },
+  { id: "violet", label: "Violet text", value: "#7c3aed" },
+  { id: "pink", label: "Pink text", value: "#db2777" },
+  { id: "gray", label: "Gray text", value: "#64748b" },
+];
+
+/** Preset highlight colors for the formatting toolbar. */
+export const EDITOR_HIGHLIGHT_COLORS: EditorColorSwatch[] = [
+  { id: "none", label: "Remove highlight", value: null },
+  { id: "yellow", label: "Yellow highlight", value: "#fef08a" },
+  { id: "lime", label: "Lime highlight", value: "#d9f99d" },
+  { id: "cyan", label: "Cyan highlight", value: "#a5f3fc" },
+  { id: "blue", label: "Blue highlight", value: "#bfdbfe" },
+  { id: "violet", label: "Violet highlight", value: "#ddd6fe" },
+  { id: "pink", label: "Pink highlight", value: "#fbcfe8" },
+  { id: "orange", label: "Orange highlight", value: "#fed7aa" },
+];

package/src/lib/image-upload.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from "vitest";
+import { readImageFileAsDataUrl } from "./image-upload";
+
+describe("readImageFileAsDataUrl", () => {
+  it("rejects files over the size limit", async () => {
+    const file = new File(["hello"], "big.png", { type: "image/png" });
+    Object.defineProperty(file, "size", { value: 6 * 1024 * 1024 });
+    const result = await readImageFileAsDataUrl(file, { maxSizeBytes: 5 * 1024 * 1024 });
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error).toContain("5MB");
+  });
+
+  it("reads a small image as a data URL", async () => {
+    const file = new File(["hello"], "small.png", { type: "image/png" });
+    const result = await readImageFileAsDataUrl(file);
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.src.startsWith("data:image/png;base64,")).toBe(true);
+  });
+});

package/src/lib/image-upload.ts

@@ -0,0 +1,49 @@
+export type ImageUploadOptions = {
+  maxSizeBytes?: number;
+  accept?: string;
+};
+
+export type ImageUploadResult =
+  | { ok: true; src: string }
+  | { ok: false; error: string };
+
+const DEFAULT_MAX_SIZE = 5 * 1024 * 1024;
+
+export function readImageFileAsDataUrl(
+  file: File,
+  options: ImageUploadOptions = {},
+): Promise<ImageUploadResult> {
+  const maxSizeBytes = options.maxSizeBytes ?? DEFAULT_MAX_SIZE;
+  const accept = options.accept ?? "image/*";
+
+  if (!file.type.startsWith("image/") && !accept.includes("*")) {
+    return Promise.resolve({ ok: false, error: "Only image files are supported." });
+  }
+
+  if (file.size > maxSizeBytes) {
+    const limitMb = Math.round(maxSizeBytes / (1024 * 1024));
+    return Promise.resolve({ ok: false, error: `Maximum file size is ${limitMb}MB.` });
+  }
+
+  return new Promise((resolve) => {
+    const reader = new FileReader();
+    reader.onload = () => {
+      if (typeof reader.result === "string") {
+        resolve({ ok: true, src: reader.result });
+      } else {
+        resolve({ ok: false, error: "Could not read the image file." });
+      }
+    };
+    reader.onerror = () => resolve({ ok: false, error: "Could not read the image file." });
+    reader.readAsDataURL(file);
+  });
+}
+
+export function insertImagesFromFiles(
+  files: FileList | File[],
+  upload: (file: File) => Promise<ImageUploadResult>,
+  limit = 3,
+): Promise<ImageUploadResult[]> {
+  const list = Array.from(files).slice(0, limit);
+  return Promise.all(list.map((file) => upload(file)));
+}

package/src/lib/insert-editor-images.test.ts

@@ -0,0 +1,76 @@
+import type { Editor } from "@tiptap/core";
+import { describe, expect, it, vi } from "vitest";
+import { extractImageFiles, insertImageFilesIntoEditor } from "./insert-editor-images";
+
+function createEditor() {
+  const run = vi.fn();
+  const chain = {
+    focus: vi.fn().mockReturnThis(),
+    setImage: vi.fn().mockReturnThis(),
+    run,
+  };
+  return {
+    chain: vi.fn(() => chain),
+  } as unknown as Editor;
+}
+
+describe("extractImageFiles", () => {
+  it("returns an empty array when there is no data transfer", () => {
+    expect(extractImageFiles(null)).toEqual([]);
+    expect(extractImageFiles(undefined)).toEqual([]);
+  });
+
+  it("filters out non-image files", () => {
+    const dataTransfer = {
+      files: [
+        new File(["img"], "photo.png", { type: "image/png" }),
+        new File(["txt"], "notes.txt", { type: "text/plain" }),
+      ],
+    } as unknown as DataTransfer;
+
+    expect(extractImageFiles(dataTransfer)).toHaveLength(1);
+    expect(extractImageFiles(dataTransfer)[0]?.name).toBe("photo.png");
+  });
+});
+
+describe("insertImageFilesIntoEditor", () => {
+  it("inserts images through the editor chain", async () => {
+    const editor = createEditor();
+    const file = new File(["hello"], "photo.png", { type: "image/png" });
+
+    const inserted = await insertImageFilesIntoEditor(editor, [file]);
+
+    expect(inserted).toBe(true);
+    expect(editor.chain).toHaveBeenCalled();
+    const chain = editor.chain();
+    expect(chain.setImage).toHaveBeenCalledWith({
+      src: expect.stringContaining("data:image/png;base64,"),
+    });
+    expect(chain.run).toHaveBeenCalled();
+  });
+
+  it("uses the host upload handler when provided", async () => {
+    const editor = createEditor();
+    const onUpload = vi.fn(async () => "https://cdn.example.com/photo.png");
+    const file = new File(["hello"], "photo.png", { type: "image/png" });
+
+    const inserted = await insertImageFilesIntoEditor(editor, [file], { onUpload });
+
+    expect(inserted).toBe(true);
+    expect(onUpload).toHaveBeenCalledWith(file);
+    const chain = editor.chain();
+    expect(chain.setImage).toHaveBeenCalledWith({ src: "https://cdn.example.com/photo.png" });
+  });
+
+  it("returns false when every upload fails", async () => {
+    const editor = createEditor();
+    const file = new File(["hello"], "photo.png", { type: "image/png" });
+
+    const inserted = await insertImageFilesIntoEditor(editor, [file], {
+      onUpload: async () => "",
+    });
+
+    expect(inserted).toBe(false);
+    expect(editor.chain).not.toHaveBeenCalled();
+  });
+});

package/src/lib/insert-editor-images.ts

@@ -0,0 +1,44 @@
+import type { Editor } from "@tiptap/core";
+import type { ImageInsertConfig } from "./types";
+import { insertImagesFromFiles, readImageFileAsDataUrl, type ImageUploadResult } from "./image-upload";
+
+async function uploadImageFile(file: File, config?: ImageInsertConfig): Promise<ImageUploadResult> {
+  if (config?.onUpload) {
+    try {
+      const src = await config.onUpload(file);
+      return src ? { ok: true, src } : { ok: false, error: "Upload failed." };
+    } catch {
+      return { ok: false, error: "Upload failed." };
+    }
+  }
+  return readImageFileAsDataUrl(file, {
+    maxSizeBytes: config?.maxSizeBytes,
+    accept: config?.accept,
+  });
+}
+
+export async function insertImageFilesIntoEditor(
+  editor: Editor,
+  files: FileList | File[],
+  config?: ImageInsertConfig,
+) {
+  const maxFiles = config?.maxFiles ?? 3;
+  const results = await insertImagesFromFiles(
+    files,
+    (file) => uploadImageFile(file, config),
+    maxFiles,
+  );
+
+  const sources = results.flatMap((result) => (result.ok ? [result.src] : []));
+  if (!sources.length) return false;
+
+  sources.forEach((src) => {
+    editor.chain().focus().setImage({ src }).run();
+  });
+  return true;
+}
+
+export function extractImageFiles(dataTransfer: DataTransfer | null | undefined) {
+  if (!dataTransfer?.files?.length) return [];
+  return Array.from(dataTransfer.files).filter((file) => file.type.startsWith("image/"));
+}