@spatika/editor 1.5.0

package/src/lib/types.ts

@@ -0,0 +1,149 @@
+import type { Editor, Extensions } from "@tiptap/core";
+import type { StarterKitOptions } from "@tiptap/starter-kit";
+import type { ReactNode } from "react";
+
+export type SpatikaEditorToolbarConfig = {
+  /** Show text style group (paragraph, headings). Default true. */
+  textStyle?: boolean;
+  /** Show inline formatting (bold, italic, underline, strike, code, sub/sup, colors, blockquote). Default true. */
+  inlineFormat?: boolean;
+  /** Show list controls (bullet, numbered, task). Default true. */
+  lists?: boolean;
+  /** Show text alignment (left, center, right, justify). Default true. */
+  alignment?: boolean;
+  /** Show insert controls (link, divider, table, image). Default true. */
+  insert?: boolean;
+  /** Show AI actions. Default true. */
+  ai?: boolean;
+  /** Show undo/redo controls. Default true. */
+  history?: boolean;
+  /** Toolbar layout. Default "ribbon". */
+  layout?: "ribbon" | "compact";
+};
+
+export type ImageInsertConfig = {
+  /** Maximum files per drop or picker action. Default 3. */
+  maxFiles?: number;
+  /** Maximum bytes per file. Default 5MB. */
+  maxSizeBytes?: number;
+  /** Accepted MIME types for uploads. Default `image/*`. */
+  accept?: string;
+  /** Host-owned upload handler. Defaults to inline base64 data URLs. */
+  onUpload?: (file: File) => Promise<string>;
+};
+
+export type SlashCommandItem = {
+  id: string;
+  title: string;
+  description?: string;
+  icon?: ReactNode;
+  keywords?: string[];
+  command: (editor: Editor) => void;
+};
+
+export type MentionContact = {
+  id: string;
+  label: string;
+  avatarUrl?: string;
+  subtitle?: string;
+};
+
+export type AiActionDefinition = {
+  id: string;
+  label: string;
+  description?: string;
+  icon?: ReactNode;
+  /** When true the action stays disabled until the user selects text. */
+  requiresSelection?: boolean;
+};
+
+export type AiCommandPromptConfig = {
+  enabled?: boolean;
+  placeholder?: string;
+  submitLabel?: string;
+};
+
+export type AiCommandMenuConfig = {
+  /** Panel heading. Default "AI commands". */
+  title?: string;
+  /** Preset actions shown in the menu. Falls back to `aiActions` then defaults. */
+  actions?: AiActionDefinition[];
+  /** Free-form prompt field. Default enabled. Pass `false` to hide it. */
+  prompt?: boolean | AiCommandPromptConfig;
+  /** Mirror preset actions in the selection bubble menu. Default false. */
+  bubbleActions?: boolean;
+  /** Where the AI command UI renders. Default `dock` (Tiptap-style prompt bar). */
+  placement?: "toolbar" | "dock";
+};
+
+/** Sent to `onAiCommand` when the user runs a preset action or submits a prompt. */
+export type AiCommandContext = {
+  /** Preset action id, or `"prompt"` for a free-form request. */
+  actionId: string;
+  /** User text from the prompt field when `actionId` is `"prompt"`. */
+  prompt?: string;
+  selectedText: string;
+  documentText: string;
+  html: string;
+  selection: { from: number; to: number } | null;
+};
+
+export const AI_PROMPT_ACTION_ID = "prompt";
+
+export type SpatikaEditorHandle = {
+  focus: () => void;
+  setContent: (html: string) => void;
+  getHTML: () => string;
+  getJSON: () => unknown;
+  expandFullscreen: () => void;
+};
+
+export type PlaceholderConfig =
+  | string
+  | ((node: { type: string; level?: number; pos: number }) => string);
+
+export type UseSpatikaEditorOptions = {
+  value: string;
+  onChange: (html: string) => void;
+  placeholder?: PlaceholderConfig;
+  disabled?: boolean;
+  extensions?: Extensions;
+  starterKit?: Partial<StarterKitOptions>;
+  slashCommands?: SlashCommandItem[];
+  mentions?: MentionContact[];
+  /** @deprecated Prefer `onAiCommand` for preset actions and free-form prompts. */
+  onAiSelectionAction?: (action: string, selectedText: string) => Promise<string | null>;
+  onAiCommand?: (context: AiCommandContext) => Promise<string | null>;
+  resizableImages?: boolean;
+  onSlashUpdate?: (state: import("../extensions/slash-command").SlashCommandStorage) => void;
+  onMentionUpdate?: (state: import("../extensions/mention").MentionStorage) => void;
+  imageInsert?: ImageInsertConfig;
+};
+
+export type SpatikaEditorProps = UseSpatikaEditorOptions & {
+  className?: string;
+  heightClassName?: string;
+  toolbar?: SpatikaEditorToolbarConfig;
+  toolbarActions?: ReactNode;
+  isAiProcessing?: boolean;
+  /** Preset AI actions for legacy toolbar/bubble buttons when `aiCommandMenu` is false. */
+  aiActions?: AiActionDefinition[];
+  /** Tiptap-style AI command menu. Default on when an AI handler is provided. Pass `false` for legacy buttons. */
+  aiCommandMenu?: AiCommandMenuConfig | false;
+  imageInsert?: ImageInsertConfig;
+  onInsertImage?: () => void;
+  mobileFullscreen?: boolean;
+};
+
+export const DEFAULT_TOOLBAR: Required<SpatikaEditorToolbarConfig> = {
+  textStyle: true,
+  inlineFormat: true,
+  lists: true,
+  alignment: true,
+  insert: true,
+  ai: true,
+  history: true,
+  layout: "ribbon",
+};
+
+export const DEFAULT_SLASH_COMMANDS: SlashCommandItem[] = [];

package/src/lib/use-spatika-editor.test.tsx

@@ -0,0 +1,56 @@
+import { renderHook, waitFor } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { buildSpatikaExtensions, useSpatikaEditor } from "./use-spatika-editor";
+
+describe("buildSpatikaExtensions", () => {
+  it("adds mention and AI extensions when configured", () => {
+    const extensions = buildSpatikaExtensions({
+      value: "",
+      onChange: () => {},
+      mentions: [{ id: "1", label: "Asha" }],
+      onAiCommand: async () => null,
+    });
+    const names = extensions.map((ext) => ext.name);
+    expect(names).toContain("mention");
+    expect(names).toContain("aiAction");
+  });
+
+  it("includes extended formatting extensions by default", () => {
+    const extensions = buildSpatikaExtensions({
+      value: "",
+      onChange: () => {},
+    });
+    const names = extensions.map((ext) => ext.name);
+    expect(names).toContain("taskList");
+    expect(names).toContain("taskItem");
+    expect(names).toContain("highlight");
+    expect(names).toContain("textStyle");
+    expect(names).toContain("subscript");
+    expect(names).toContain("superscript");
+  });
+});
+
+describe("useSpatikaEditor", () => {
+  it("returns a ready editor and emits onChange updates", async () => {
+    const onChange = vi.fn();
+    const { result } = renderHook(() =>
+      useSpatikaEditor({
+        value: "<p>Hello</p>",
+        onChange,
+        placeholder: "Write here…",
+      }),
+    );
+
+    await waitFor(() => {
+      expect(result.current.isReady).toBe(true);
+    });
+
+    result.current.editor?.commands.setContent("<p>Updated</p>");
+    await waitFor(() => {
+      expect(onChange).toHaveBeenCalled();
+      expect(onChange.mock.calls.at(-1)?.[0]).toContain("Updated");
+    });
+
+    result.current.editor?.destroy();
+  });
+});

package/src/lib/use-spatika-editor.ts

@@ -0,0 +1,191 @@
+import { useEffect, useMemo, useRef } from "react";
+import type { Extensions } from "@tiptap/core";
+import Color from "@tiptap/extension-color";
+import Highlight from "@tiptap/extension-highlight";
+import Image from "@tiptap/extension-image";
+import Link from "@tiptap/extension-link";
+import Placeholder from "@tiptap/extension-placeholder";
+import Subscript from "@tiptap/extension-subscript";
+import Superscript from "@tiptap/extension-superscript";
+import { Table } from "@tiptap/extension-table";
+import TableCell from "@tiptap/extension-table-cell";
+import TableHeader from "@tiptap/extension-table-header";
+import TableRow from "@tiptap/extension-table-row";
+import TaskItem from "@tiptap/extension-task-item";
+import TaskList from "@tiptap/extension-task-list";
+import TextAlign from "@tiptap/extension-text-align";
+import { TextStyle } from "@tiptap/extension-text-style";
+import Underline from "@tiptap/extension-underline";
+import { useEditor } from "@tiptap/react";
+import { TextSelection } from "@tiptap/pm/state";
+import StarterKit from "@tiptap/starter-kit";
+import { createAiActionExtension } from "../extensions/ai-action";
+import { createMentionExtension } from "../extensions/mention";
+import { ResizableImage } from "../extensions/resizable-image";
+import {
+  createSlashCommandExtension,
+  defaultSlashCommands,
+} from "../extensions/slash-command";
+import type { PlaceholderConfig, UseSpatikaEditorOptions } from "./types";
+import { extractImageFiles, insertImageFilesIntoEditor } from "./insert-editor-images";
+
+function resolvePlaceholder(placeholder?: PlaceholderConfig) {
+  if (!placeholder) return "Start writing…";
+  if (typeof placeholder === "string") return placeholder;
+  return (props: { node: { type: { name: string }; attrs: { level?: number } }; pos: number }) =>
+    placeholder({
+      type: props.node.type.name,
+      level: props.node.attrs.level,
+      pos: props.pos,
+    });
+}
+
+export function buildSpatikaExtensions(
+  options: UseSpatikaEditorOptions & {
+    onSlashUpdate?: Parameters<typeof createSlashCommandExtension>[1];
+    onMentionUpdate?: Parameters<typeof createMentionExtension>[1];
+  },
+): Extensions {
+  const imageExtension = options.resizableImages ? ResizableImage : Image;
+  const slashItems = [
+    ...defaultSlashCommands(),
+    ...(options.slashCommands ?? []),
+  ];
+
+  const extensions: Extensions = [
+    StarterKit.configure({
+      heading: { levels: [1, 2, 3] },
+      link: false,
+      underline: false,
+      ...options.starterKit,
+    }),
+    TextStyle,
+    Color,
+    Highlight.configure({ multicolor: true }),
+    Subscript,
+    Superscript,
+    Underline,
+    Link.configure({
+      openOnClick: false,
+      HTMLAttributes: { class: "spk-editor-link" },
+    }),
+    Placeholder.configure({
+      placeholder: resolvePlaceholder(options.placeholder),
+    }),
+    TextAlign.configure({ types: ["heading", "paragraph"] }),
+    TaskList,
+    TaskItem.configure({ nested: true }),
+    Table.configure({ resizable: true }),
+    TableRow,
+    TableHeader,
+    TableCell,
+    imageExtension.configure({ inline: false, allowBase64: true }),
+    createSlashCommandExtension(slashItems, options.onSlashUpdate),
+    ...(options.onAiSelectionAction || options.onAiCommand ? [createAiActionExtension()] : []),
+    ...(options.extensions ?? []),
+  ];
+
+  if (options.mentions?.length) {
+    extensions.push(...createMentionExtension(options.mentions, options.onMentionUpdate));
+  }
+
+  return extensions;
+}
+
+export function useSpatikaEditor(options: UseSpatikaEditorOptions) {
+  const onChangeRef = useRef(options.onChange);
+  onChangeRef.current = options.onChange;
+  const slashUpdateRef = useRef(options.onSlashUpdate);
+  slashUpdateRef.current = options.onSlashUpdate;
+  const mentionUpdateRef = useRef(options.onMentionUpdate);
+  mentionUpdateRef.current = options.onMentionUpdate;
+  const imageInsertRef = useRef(options.imageInsert);
+  imageInsertRef.current = options.imageInsert;
+  const editorRef = useRef<ReturnType<typeof useEditor>>(null);
+
+  const extensions = useMemo(
+    () =>
+      buildSpatikaExtensions({
+        ...options,
+        onSlashUpdate: (state) => slashUpdateRef.current?.(state),
+        onMentionUpdate: (state) => mentionUpdateRef.current?.(state),
+      }),
+    [
+      options.placeholder,
+      options.resizableImages,
+      options.slashCommands,
+      options.mentions,
+      options.extensions,
+      options.starterKit,
+      options.onAiSelectionAction,
+      options.onAiCommand,
+    ],
+  );
+
+  const editor = useEditor({
+    immediatelyRender: true,
+    extensions,
+    content: options.value,
+    editable: !options.disabled,
+    onUpdate: ({ editor: ed }) => {
+      onChangeRef.current(ed.getHTML());
+    },
+    editorProps: {
+      attributes: {
+        class: "spk-editor-content ProseMirror",
+        role: "textbox",
+        "aria-multiline": "true",
+        "aria-label": "Rich text editor",
+      },
+      handleDrop(view, event) {
+        const files = extractImageFiles(event.dataTransfer);
+        if (!files.length) return false;
+        event.preventDefault();
+        const coords = view.posAtCoords({ left: event.clientX, top: event.clientY });
+        if (coords) {
+          view.dispatch(
+            view.state.tr.setSelection(TextSelection.near(view.state.doc.resolve(coords.pos))),
+          );
+        }
+        const ed = editorRef.current;
+        if (ed) void insertImageFilesIntoEditor(ed, files, imageInsertRef.current);
+        return true;
+      },
+      handlePaste(_view, event) {
+        const items = event.clipboardData?.items;
+        if (!items) return false;
+        const files = Array.from(items)
+          .filter((item) => item.type.startsWith("image/"))
+          .map((item) => item.getAsFile())
+          .filter((file): file is File => Boolean(file));
+        if (!files.length) return false;
+        event.preventDefault();
+        const ed = editorRef.current;
+        if (ed) void insertImageFilesIntoEditor(ed, files, imageInsertRef.current);
+        return true;
+      },
+    },
+  });
+
+  useEffect(() => {
+    editorRef.current = editor;
+  }, [editor]);
+
+  useEffect(() => {
+    if (!editor) return;
+    editor.setEditable(!options.disabled);
+  }, [editor, options.disabled]);
+
+  useEffect(() => {
+    if (!editor) return;
+    const current = editor.getHTML();
+    if (options.value !== current) {
+      editor.commands.setContent(options.value, { emitUpdate: false });
+    }
+  }, [editor, options.value]);
+
+  return {
+    editor,
+    isReady: Boolean(editor),
+  };
+}