@agent-native/toolkit 0.5.1 → 0.7.0

package/src/editor/SharedRichEditor.tsx

@@ -0,0 +1,321 @@
+import type { Extension, Node, Mark } from "@tiptap/core";
+import { EditorContent, useEditor } from "@tiptap/react";
+import { useEffect, useMemo, useRef } from "react";
+import type { Awareness } from "y-protocols/awareness";
+import type { Doc as YDoc } from "yjs";
+
+import { cn } from "../utils.js";
+import { BubbleToolbar, type BubbleToolbarItem } from "./BubbleToolbar.js";
+import {
+  createSharedEditorExtensions,
+  type RichMarkdownDialect,
+  type RichMarkdownEditorPreset,
+  type RichMarkdownCollabUser,
+  type SharedEditorFeatures,
+} from "./extensions.js";
+import type { ImageUploadFn } from "./ImageExtension.js";
+import { SlashCommandMenu, type SlashCommandItem } from "./SlashCommandMenu.js";
+import {
+  useCollabReconcile,
+  getEditorMarkdown,
+  type UseCollabReconcileResult,
+  type UseCollabReconcileOptions,
+} from "./useCollabReconcile.js";
+
+export interface SharedRichEditorProps {
+  value: string;
+  onChange: (markdown: string) => void;
+  onBlur?: () => void;
+  contentUpdatedAt?: string | null;
+  editable?: boolean;
+  dialect?: RichMarkdownDialect;
+  preset?: RichMarkdownEditorPreset;
+  /** Toggle individual base extensions (tables/tasks/link/codeBlock/image). */
+  features?: SharedEditorFeatures;
+  /**
+   * Injectable image uploader for the shared image block. Used only when
+   * `features.image` is on. Pass `uploadEditorImage` (the framework
+   * `upload-image` action) for a real uploading image block.
+   */
+  onImageUpload?: ImageUploadFn | null;
+  /**
+   * App-specific extensions (Notion nodes, media, drag handles, comment
+   * anchors, …) appended after the shared base schema.
+   */
+  extraExtensions?: Array<Extension | Node | Mark>;
+  placeholder?: string;
+  className?: string;
+  editorClassName?: string;
+  ariaLabel?: string;
+  interactive?: boolean;
+  /**
+   * Yjs document for real-time multi-user editing. When provided, prose is
+   * authored against the shared Y.Doc and mirrored back to `value` as markdown
+   * (still the source of truth). When omitted, the editor is a plain controlled
+   * `value`/`onChange` editor — the existing, non-collaborative behavior.
+   */
+  ydoc?: YDoc | null;
+  /** True after the collab provider has loaded persisted Y.Doc state. */
+  collabSynced?: boolean;
+  /** Shared awareness instance for live cursors/presence. */
+  awareness?: Awareness | null;
+  /** Current user info for the collaborative cursor label. */
+  user?: RichMarkdownCollabUser | null;
+  /**
+   * Disable StarterKit's built-in undo/redo for a controlled (non-collab)
+   * editor whose host owns its own undo authority (see
+   * {@link CreateSharedEditorExtensionsOptions.disableHistory}). Ignored when a
+   * `ydoc` is present (Yjs always owns history then). Default `false`, so every
+   * existing embedder is unchanged.
+   */
+  disableHistory?: boolean;
+  /** Override the slash-menu block command list. */
+  slashItems?: SlashCommandItem[];
+  /** Override the bubble-toolbar item builder. */
+  buildBubbleItems?: (
+    editor: import("@tiptap/react").Editor,
+    toggleLink: () => void,
+  ) => BubbleToolbarItem[];
+  /**
+   * Override how the editor's content is read into the canonical `value`.
+   * Defaults to the tiptap-markdown storage reader. Apps with a custom on-disk
+   * format (Content's NFM, the plan's `blocks[]` JSON) pass their serializer so
+   * seed/reconcile/onChange all speak the same value space.
+   */
+  getMarkdown?: (editor: import("@tiptap/react").Editor) => string;
+  /** Override how the canonical `value` is applied into the editor (seed + reconcile). */
+  setContent?: (
+    editor: import("@tiptap/react").Editor,
+    value: string,
+    options: { emitUpdate?: boolean; addToHistory?: boolean },
+  ) => void;
+  /**
+   * Optional parser for surgical reconcile. Custom value formats that already
+   * handle surgical writes inside `setContent` can pass `false` so the default
+   * markdown parser never treats their source bytes as literal markdown.
+   */
+  parseValue?: UseCollabReconcileOptions["parseValue"];
+  /** Canonicalize `value` for the echo / already-in-sync equality checks. */
+  normalizeValue?: (value: string) => string;
+  /** Override the empty-doc seed predicate (see {@link useCollabReconcile}). */
+  shouldSeed?: (info: {
+    value: string;
+    currentMarkdown: string;
+    fragmentLength: number;
+  }) => boolean;
+  /** Initial "applied" watermark (see {@link useCollabReconcile}). */
+  initialAppliedUpdatedAt?: string | null;
+  /** Extra class on the editor wrapper (e.g. a drag-handle `wrapperSelector` hook). */
+  wrapperClassName?: string;
+  /**
+   * Fires once the editor instance exists. Lets a host capture the root
+   * `editor.view` — e.g. to repaint the WHOLE document after a structural block
+   * move (a column emptied and its container dissolved) that a surgical
+   * per-region patch can't express, since the change is in the root doc itself.
+   */
+  onEditorReady?: (editor: import("@tiptap/react").Editor) => void;
+}
+
+/**
+ * The single shared rich markdown editor surface. Combines
+ * {@link createSharedEditorExtensions} (schema + dialect-keyed markdown +
+ * optional collab + app extras), {@link useCollabReconcile} (seed / reconcile /
+ * lead-client logic), and the shared {@link SlashCommandMenu} +
+ * {@link BubbleToolbar}.
+ *
+ * With no `ydoc` it is a controlled `value`/`onChange` single-user editor.
+ * With a `ydoc` it binds the framework collaboration stack; markdown stays the
+ * canonical saved representation while the Y.Doc is transient live state.
+ */
+export function SharedRichEditor({
+  value,
+  onChange,
+  onBlur,
+  contentUpdatedAt,
+  editable = true,
+  dialect = "gfm",
+  preset = "plan",
+  features,
+  onImageUpload = null,
+  extraExtensions,
+  placeholder = "Type '/' for commands...",
+  className,
+  editorClassName,
+  ariaLabel,
+  interactive = editable,
+  ydoc = null,
+  collabSynced = true,
+  awareness = null,
+  user = null,
+  disableHistory = false,
+  slashItems,
+  buildBubbleItems,
+  getMarkdown,
+  setContent,
+  parseValue,
+  normalizeValue,
+  shouldSeed,
+  initialAppliedUpdatedAt,
+  wrapperClassName,
+  onEditorReady,
+}: SharedRichEditorProps) {
+  const readMarkdown = getMarkdown ?? getEditorMarkdown;
+  const onChangeRef = useRef(onChange);
+  const onBlurRef = useRef(onBlur);
+  onChangeRef.current = onChange;
+  onBlurRef.current = onBlur;
+
+  const extensions = useMemo(
+    () =>
+      createSharedEditorExtensions({
+        dialect,
+        preset,
+        placeholder,
+        features,
+        extraExtensions,
+        onImageUpload,
+        collab: ydoc ? { ydoc, awareness, user } : null,
+        disableHistory,
+      }),
+    // `preset` is retained in the dependency list so future preset-specific
+    // schema branches re-create the editor; it is currently schema-neutral. The
+    // collab inputs are identity-stable per block (one Y.Doc per docId), so they
+    // only change on a genuine doc switch — exactly when the editor must
+    // re-create to rebind Collaboration.
+    [
+      dialect,
+      placeholder,
+      preset,
+      features,
+      extraExtensions,
+      onImageUpload,
+      ydoc,
+      awareness,
+      user?.name,
+      user?.email,
+      user?.color,
+      disableHistory,
+    ],
+  );
+
+  const collab = !!ydoc;
+
+  // The collab hook needs the editor, but useEditor's `onUpdate` needs the
+  // hook's guards. Break the cycle with a ref: `onUpdate` reads the guards
+  // through `guardsRef`, which is populated right after the hook runs below.
+  // `onUpdate` only ever fires after the editor exists, by which point the ref
+  // holds the real guards.
+  const guardsRef = useRef<UseCollabReconcileResult | null>(null);
+
+  const editor = useEditor(
+    {
+      extensions,
+      // With Collaboration active the prose is owned by the shared Y.XmlFragment.
+      // Seeding `content` here too would make the editor initialize from BOTH the
+      // prop and the Y.Doc, firing a spurious initial update that could autosave a
+      // stale value over newer SQL. The lead-client seed effect populates an empty
+      // doc instead. Non-collab editors keep initializing from `value`.
+      // With Collaboration the Y.Doc owns the prose (seeded by the lead client).
+      // With a custom `setContent` the reconcile seeds the editor too (the raw
+      // `value` is not directly settable content — e.g. the plan's blocks JSON),
+      // so only the plain markdown path seeds from `value` here.
+      content: collab || setContent ? null : value,
+      editable,
+      editorProps: {
+        attributes: {
+          class: cn("an-rich-md-prose", editorClassName),
+          ...(ariaLabel ? { role: "textbox", "aria-label": ariaLabel } : {}),
+        },
+      },
+      onUpdate: ({ editor, transaction }) => {
+        const guards = guardsRef.current;
+        if (!guards || guards.shouldIgnoreUpdate(transaction)) return;
+        try {
+          const markdown = readMarkdown(editor);
+          if (!guards.registerEmitted(markdown)) return;
+          queueMicrotask(() => onChangeRef.current(markdown));
+        } catch (error) {
+          console.error("Markdown serialization error:", error);
+        }
+      },
+      onBlur: () => {
+        onBlurRef.current?.();
+      },
+      // Recreate the editor when the shared Y.Doc identity changes — including
+      // null → doc. Extensions are baked in at creation, so a ydoc that arrives
+      // AFTER the first mount (fresh page load: the session/user resolves after
+      // the editor mounts) would otherwise never bind Collaboration: the editor
+      // looks fine but produces no Yjs updates and never receives peers' edits.
+    },
+    [ydoc],
+  );
+
+  const collabState = useCollabReconcile({
+    editor,
+    ydoc,
+    collabSynced,
+    awareness,
+    value,
+    contentUpdatedAt,
+    editable,
+    getMarkdown: readMarkdown,
+    setContent,
+    parseValue,
+    normalizeValue,
+    shouldSeed,
+    initialAppliedUpdatedAt,
+  });
+  guardsRef.current = collabState;
+
+  useEffect(() => {
+    if (!editor || editor.isDestroyed) return;
+    editor.setEditable(editable);
+  }, [editable, editor]);
+
+  useEffect(() => {
+    if (editor) onEditorReady?.(editor);
+  }, [editor, onEditorReady]);
+
+  useEffect(() => () => editor?.destroy(), [editor]);
+
+  const handleWrapperClick = (event: React.MouseEvent<HTMLDivElement>) => {
+    if (!editable || !editor || editor.isDestroyed) return;
+    const target = event.target as HTMLElement;
+    if (
+      target.classList.contains("an-rich-md-wrapper") ||
+      target.classList.contains("an-rich-md-clickable")
+    ) {
+      editor.chain().focus("end").run();
+    }
+  };
+
+  if (!editor) {
+    return (
+      <div
+        className={cn("an-rich-md-wrapper an-rich-md-loading", className)}
+        data-plan-interactive={interactive ? true : undefined}
+      />
+    );
+  }
+
+  return (
+    <div
+      className={cn(
+        "an-rich-md-wrapper an-rich-md-clickable",
+        !editable && "an-rich-md-wrapper--readonly",
+        wrapperClassName,
+        className,
+      )}
+      onClick={handleWrapperClick}
+      data-plan-interactive={interactive ? true : undefined}
+    >
+      {editable ? (
+        <BubbleToolbar editor={editor} buildItems={buildBubbleItems} />
+      ) : null}
+      {editable ? (
+        <SlashCommandMenu editor={editor} items={slashItems} />
+      ) : null}
+      <EditorContent editor={editor} />
+    </div>
+  );
+}

package/src/editor/SlashCommandMenu.tsx

@@ -0,0 +1,310 @@
+import type { Editor } from "@tiptap/react";
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type CSSProperties,
+} from "react";
+
+import { cn } from "../utils.js";
+import { pickAndInsertImage, type ImageUploadFn } from "./ImageExtension.js";
+
+/** A single slash-menu block command. Apps can extend the default list. */
+export interface SlashCommandItem {
+  title: string;
+  description: string;
+  /**
+   * Optional hidden search text. Use this for raw block types and aliases that
+   * should match slash queries without making the visible description verbose.
+   */
+  searchText?: string;
+  /** Short text glyph shown in the menu (T, H1, tbl, …). */
+  icon: string;
+  action: (editor: Editor) => void;
+}
+
+/**
+ * The default block commands — Plan's current set. Apps pass their own `items`
+ * (typically `[...DEFAULT_SLASH_COMMANDS, ...extra]`) to extend it.
+ */
+export const DEFAULT_SLASH_COMMANDS: SlashCommandItem[] = [
+  {
+    title: "Text",
+    description: "Plain text block",
+    icon: "T",
+    action: (editor) => editor.chain().focus().setParagraph().run(),
+  },
+  {
+    title: "Heading 1",
+    description: "Large heading",
+    icon: "H1",
+    action: (editor) =>
+      editor.chain().focus().toggleHeading({ level: 1 }).run(),
+  },
+  {
+    title: "Heading 2",
+    description: "Section heading",
+    icon: "H2",
+    action: (editor) =>
+      editor.chain().focus().toggleHeading({ level: 2 }).run(),
+  },
+  {
+    title: "Heading 3",
+    description: "Subheading",
+    icon: "H3",
+    action: (editor) =>
+      editor.chain().focus().toggleHeading({ level: 3 }).run(),
+  },
+  {
+    title: "Bulleted list",
+    description: "Unordered list",
+    icon: "-",
+    action: (editor) => editor.chain().focus().toggleBulletList().run(),
+  },
+  {
+    title: "Numbered list",
+    description: "Ordered list",
+    icon: "1.",
+    action: (editor) => editor.chain().focus().toggleOrderedList().run(),
+  },
+  {
+    title: "To-do list",
+    description: "Checklist items",
+    icon: "[]",
+    action: (editor) => editor.chain().focus().toggleTaskList().run(),
+  },
+  {
+    title: "Quote",
+    description: "Block quote",
+    icon: '"',
+    action: (editor) => editor.chain().focus().toggleBlockquote().run(),
+  },
+  {
+    title: "Code block",
+    description: "Code snippet",
+    icon: "<>",
+    action: (editor) => editor.chain().focus().toggleCodeBlock().run(),
+  },
+  {
+    title: "Divider",
+    description: "Horizontal rule",
+    icon: "-",
+    action: (editor) => editor.chain().focus().setHorizontalRule().run(),
+  },
+  {
+    title: "Table",
+    description: "Three by three table",
+    icon: "tbl",
+    action: (editor) =>
+      editor
+        .chain()
+        .focus()
+        .insertTable({ rows: 3, cols: 3, withHeaderRow: true })
+        .run(),
+  },
+];
+
+/**
+ * Build the `/image` slash command for the shared image block. Requires the
+ * editor to mount the shared image extension (`features.image`) and an
+ * {@link ImageUploadFn}; the command opens a native file picker and uploads +
+ * inserts the chosen image(s). Add it to the list an app passes to
+ * {@link SlashCommandMenu} (e.g. `[...DEFAULT_SLASH_COMMANDS, createImageSlashCommand(upload)]`).
+ */
+export function createImageSlashCommand(
+  upload: ImageUploadFn,
+): SlashCommandItem {
+  return {
+    title: "Image",
+    description: "Upload an image",
+    icon: "img",
+    action: (editor) => pickAndInsertImage(editor.view, upload),
+  };
+}
+
+export interface SlashCommandMenuProps {
+  editor: Editor;
+  /** Block command list. Defaults to {@link DEFAULT_SLASH_COMMANDS}. */
+  items?: SlashCommandItem[];
+}
+
+/**
+ * The shared "/" block-insert menu. Detects a `/query` at the caret, filters the
+ * provided command list, and renders a fixed-position picker with keyboard
+ * navigation. Extracted from the inline plan menu so apps share one
+ * implementation and only swap the command list.
+ */
+export function SlashCommandMenu({
+  editor,
+  items = DEFAULT_SLASH_COMMANDS,
+}: SlashCommandMenuProps) {
+  const [isOpen, setIsOpen] = useState(false);
+  const [query, setQuery] = useState("");
+  const [selectedIndex, setSelectedIndex] = useState(0);
+  const [position, setPosition] = useState<{
+    top: number;
+    left: number;
+    flipUp: boolean;
+  } | null>(null);
+  const menuRef = useRef<HTMLDivElement>(null);
+  const selectedItemRef = useRef<HTMLButtonElement>(null);
+  const slashPosRef = useRef<number | null>(null);
+
+  const filteredCommands = useMemo(() => {
+    const normalizedQuery = query.toLowerCase();
+    return items.filter(
+      (cmd) =>
+        cmd.title.toLowerCase().includes(normalizedQuery) ||
+        cmd.description.toLowerCase().includes(normalizedQuery) ||
+        cmd.searchText?.toLowerCase().includes(normalizedQuery),
+    );
+  }, [items, query]);
+
+  const close = useCallback(() => {
+    setIsOpen(false);
+    setQuery("");
+    slashPosRef.current = null;
+  }, []);
+
+  const executeCommand = useCallback(
+    (command: SlashCommandItem) => {
+      if (slashPosRef.current !== null) {
+        const { from } = editor.state.selection;
+        editor
+          .chain()
+          .focus()
+          .deleteRange({ from: slashPosRef.current, to: from })
+          .run();
+      }
+      command.action(editor);
+      close();
+    },
+    [close, editor],
+  );
+
+  useEffect(() => {
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (!isOpen) return;
+      if (event.key === "ArrowDown") {
+        event.preventDefault();
+        if (filteredCommands.length === 0) return;
+        setSelectedIndex((index) => (index + 1) % filteredCommands.length);
+      } else if (event.key === "ArrowUp") {
+        event.preventDefault();
+        if (filteredCommands.length === 0) return;
+        setSelectedIndex(
+          (index) =>
+            (index - 1 + filteredCommands.length) % filteredCommands.length,
+        );
+      } else if (event.key === "Enter") {
+        event.preventDefault();
+        const command = filteredCommands[selectedIndex];
+        if (command) executeCommand(command);
+      } else if (event.key === "Escape") {
+        close();
+      }
+    };
+    document.addEventListener("keydown", handleKeyDown, true);
+    return () => document.removeEventListener("keydown", handleKeyDown, true);
+  }, [close, executeCommand, filteredCommands, isOpen, selectedIndex]);
+
+  useEffect(() => {
+    if (!isOpen) return;
+    const menu = menuRef.current;
+    const item = selectedItemRef.current;
+    if (!menu || !item) return;
+
+    const itemTop = item.offsetTop;
+    const itemBottom = itemTop + item.offsetHeight;
+    const visibleTop = menu.scrollTop;
+    const visibleBottom = visibleTop + menu.clientHeight;
+
+    if (itemTop < visibleTop) {
+      menu.scrollTop = itemTop;
+    } else if (itemBottom > visibleBottom) {
+      menu.scrollTop = itemBottom - menu.clientHeight;
+    }
+  }, [filteredCommands.length, isOpen, selectedIndex]);
+
+  useEffect(() => {
+    const handleTransaction = () => {
+      const { state } = editor;
+      const { from } = state.selection;
+      const textBefore = state.doc.textBetween(
+        Math.max(0, from - 32),
+        from,
+        "\n",
+      );
+      const slashMatch = textBefore.match(/\/([a-zA-Z0-9 ]*)$/);
+      if (!slashMatch) {
+        if (isOpen) close();
+        return;
+      }
+
+      const slashStart = from - slashMatch[0].length;
+      slashPosRef.current = slashStart;
+      setQuery(slashMatch[1]);
+      setSelectedIndex(0);
+      const coords = editor.view.coordsAtPos(from);
+      const menuHeight = 320;
+      const spaceBelow = window.innerHeight - coords.bottom;
+      const flipUp = spaceBelow < menuHeight && coords.top > menuHeight;
+      setPosition({
+        top: flipUp ? coords.top : coords.bottom + 4,
+        left: Math.min(coords.left, window.innerWidth - 250),
+        flipUp,
+      });
+      setIsOpen(true);
+    };
+
+    editor.on("transaction", handleTransaction);
+    return () => {
+      editor.off("transaction", handleTransaction);
+    };
+  }, [close, editor, isOpen]);
+
+  if (!isOpen || !position || filteredCommands.length === 0) return null;
+
+  return (
+    <div
+      ref={menuRef}
+      className="an-rich-md-slash-menu"
+      style={
+        {
+          position: "fixed",
+          ...(position.flipUp
+            ? { bottom: window.innerHeight - position.top + 4 }
+            : { top: position.top }),
+          left: position.left,
+        } as CSSProperties
+      }
+      data-plan-interactive
+    >
+      <div className="an-rich-md-slash-heading">Blocks</div>
+      {filteredCommands.map((command, index) => (
+        <button
+          key={command.title}
+          ref={index === selectedIndex ? selectedItemRef : undefined}
+          type="button"
+          className={cn(
+            "an-rich-md-slash-item",
+            index === selectedIndex && "an-rich-md-slash-item--active",
+          )}
+          onMouseEnter={() => setSelectedIndex(index)}
+          onMouseDown={(event) => event.preventDefault()}
+          onClick={() => executeCommand(command)}
+        >
+          <span className="an-rich-md-slash-icon">{command.icon}</span>
+          <span className="an-rich-md-slash-copy">
+            <span className="an-rich-md-slash-title">{command.title}</span>
+            <span className="an-rich-md-slash-description">
+              {command.description}
+            </span>
+          </span>
+        </button>
+      ))}
+    </div>
+  );
+}