@ceedcv-maya/shared-editor-react 0.6.0

package/src/components/MayaEditor.tsx

@@ -0,0 +1,379 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { EditorContent, useEditor } from '@tiptap/react';
+import type { Editor } from '@tiptap/react';
+
+import { buildMayaEditorExtensions } from '../lib/editorExtensions';
+import { useEditorContent, type EditorOutput } from '../hooks/useEditorContent';
+import { sanitizeEditorHtml } from '../lib/dompurifyConfig';
+import { markdownToHtml } from '../lib/markdownToHtml';
+import { htmlToMarkdown } from '../lib/htmlToMarkdown';
+import { normalizeTableHtml } from '../lib/normalizeTableHtml';
+import { docxToHtml } from '../lib/docxToHtml';
+import type { EditorMode, TiptapDoc } from '../types';
+import { EditorToolbar, type ToolbarLabels } from './EditorToolbar';
+import { FindReplaceBar } from './FindReplaceBar';
+import { CommentHoverPopover, type CommentHoverData } from './CommentHoverPopover';
+import '../styles/maya-editor.css';
+
+type ViewMode = 'wysiwyg' | 'html' | 'markdown';
+
+export interface MayaEditorProps {
+  /** Initial HTML content (preferred) or a ProseMirror JSON doc. */
+  initialContent?: string | object;
+  /** When false, the editor is read-only. Defaults to true. */
+  editable?: boolean;
+  /** Toggle dark-mode CSS class on the editor wrapper. */
+  isDark?: boolean;
+  /** Editor mode: 'lite' (minimal toolbar) | 'full' (BlockNote parity). */
+  mode?: EditorMode;
+  /** Debounced change callback (300ms). Payload depends on `output`. */
+  onChange?: (payload: string | TiptapDoc) => void;
+  /**
+   * Output shape: `'html'` (default) emits a sanitisation-ready string;
+   * `'json'` emits the full ProseMirror doc `{type:'doc', content:[…]}`,
+   * structurally equivalent to BlockNote's legacy block array and a
+   * better fit for backends that still validate as JSON object/array.
+   */
+  output?: EditorOutput;
+  /** Fullscreen toggle callback (only meaningful in 'full' mode). */
+  onFullscreenChange?: (isFullscreen: boolean) => void;
+  /** Optional file uploader; returns the URL to embed. */
+  uploadFile?: (file: File) => Promise<string>;
+  /** Optional toolbar labels override (i18n). */
+  toolbarLabels?: ToolbarLabels;
+  /** Optional placeholder text. */
+  placeholder?: string;
+  /** Forwarded onEditorReady callback to access the underlying editor. */
+  onEditorReady?: (editor: Editor) => void;
+  /**
+   * Called when the user clicks "Comment selection". Receives the current
+   * text range. The consumer should persist the comment, then return the
+   * commentId — the editor wraps the selection with a `CommentMark`
+   * carrying that id. Returning `null`/`undefined` cancels.
+   */
+  onCreateComment?: (range: {
+    from: number;
+    to: number;
+    text: string;
+  }) => Promise<string | number | null | undefined> | string | number | null | undefined;
+  /** Called when the user clicks "Export .docx". Consumer triggers the download. */
+  onExportDocx?: () => void;
+  /**
+   * Lookup table for anchored-comment hover previews. The package itself
+   * doesn't know how comments are fetched — the consumer passes a dict
+   * keyed by `commentId` so the editor can render a `data-comment-id`
+   * span's contents in a portal popover on hover. Missing keys → no
+   * popover (silent).
+   */
+  commentsById?: Record<string, CommentHoverData>;
+}
+
+/**
+ * Unified TipTap editor for the Maya ecosystem.
+ *
+ * Two visual modes via the `mode` prop — the underlying ProseMirror
+ * schema and extensions are shared, so a `mode=lite` instance can be
+ * upgraded to `mode=full` without re-parsing content.
+ *
+ * Intended replacements:
+ *   - `mode='lite'`  → 4 textareas in maya_logs + maya_dashboard
+ *   - `mode='full'`  → BlockNoteEditorPanel in maya_dms (templates/documents)
+ */
+export function MayaEditor({
+  initialContent,
+  editable = true,
+  isDark = false,
+  mode = 'lite',
+  onChange,
+  onFullscreenChange,
+  uploadFile,
+  toolbarLabels,
+  placeholder,
+  onEditorReady,
+  output,
+  onCreateComment,
+  onExportDocx,
+  commentsById,
+}: MayaEditorProps) {
+  const effectiveOutput: EditorOutput = output ?? (mode === 'full' ? 'json' : 'html');
+  const [isFullscreen, setIsFullscreen] = useState(false);
+  const [viewMode, setViewMode] = useState<ViewMode>('wysiwyg');
+  const [sourceText, setSourceText] = useState('');
+  const [findOpen, setFindOpen] = useState(false);
+  // selectionVersion bumps on every selectionUpdate so toolbar predicates
+  // that read `editor.state.selection` (e.g. the comment button's disabled
+  // state) re-evaluate on cursor moves. TipTap v3's `useEditor` re-renders
+  // on transactions but not selection-only changes.
+  const [, setSelectionVersion] = useState(0);
+  const [hoveredComment, setHoveredComment] = useState<{
+    id: string;
+    rect: DOMRect;
+  } | null>(null);
+  // viewReady flips to true after TipTap's `create` event fires, which is
+  // when `editor.view` becomes safely accessible. Used to defer effects
+  // that touch the view DOM until it's actually mounted.
+  const [viewReady, setViewReady] = useState(false);
+  const fileInputRef = useRef<HTMLInputElement | null>(null);
+  const docxInputRef = useRef<HTMLInputElement | null>(null);
+
+  const extensions = useMemo(() => buildMayaEditorExtensions(mode), [mode]);
+
+  const editor = useEditor({
+    extensions,
+    content: initialContent ?? '',
+    editable,
+    editorProps: {
+      attributes: {
+        class: `maya-editor maya-editor--${mode}${isDark ? ' is-dark' : ''}`,
+        ...(placeholder ? { 'data-placeholder': placeholder } : {}),
+      },
+      // Reshape pasted HTML so complex tables (caption/tfoot/colgroup)
+      // survive TipTap's parser. See `normalizeTableHtml` for details.
+      transformPastedHTML: (html) => normalizeTableHtml(html),
+    },
+  });
+
+  useEditorContent(editor, onChange, { output: effectiveOutput });
+
+  useEffect(() => {
+    if (editor && onEditorReady) onEditorReady(editor);
+  }, [editor, onEditorReady]);
+
+  useEffect(() => {
+    if (!editor) return;
+    const bump = () => setSelectionVersion((v) => v + 1);
+    const markReady = () => setViewReady(true);
+    editor.on('selectionUpdate', bump);
+    editor.on('transaction', bump);
+    editor.on('create', markReady);
+    // The editor may have already fired `create` before we got here
+    // (useEditor sometimes returns an instance that's already mounted).
+    try {
+      if (editor.view && editor.view.dom) setViewReady(true);
+    } catch { /* view not ready yet — markReady will fire it */ }
+    return () => {
+      editor.off('selectionUpdate', bump);
+      editor.off('transaction', bump);
+      editor.off('create', markReady);
+    };
+  }, [editor]);
+
+  // Hover detection on CommentMark spans (`data-comment-id`).
+  // Listens on the editor view DOM so we don't pay for delegated mouse
+  // events outside the editor surface. Closes when the pointer leaves
+  // the comment span and there's no replacement inside the same hover.
+  // Gated on `viewReady` because `editor.view` is a getter that throws
+  // until TipTap fires the `create` event.
+  useEffect(() => {
+    if (!editor || !commentsById || !viewReady) return;
+    let root: HTMLElement;
+    try {
+      root = editor.view.dom as HTMLElement;
+    } catch {
+      return;
+    }
+    if (!root) return;
+    let hideTimer: ReturnType<typeof setTimeout> | null = null;
+
+    const handleEnter = (e: MouseEvent) => {
+      const target = e.target as HTMLElement | null;
+      const span = target?.closest?.('[data-comment-id]') as HTMLElement | null;
+      if (!span) return;
+      const id = span.getAttribute('data-comment-id');
+      if (!id || !commentsById[id]) return;
+      if (hideTimer) {
+        clearTimeout(hideTimer);
+        hideTimer = null;
+      }
+      setHoveredComment({ id, rect: span.getBoundingClientRect() });
+    };
+    const handleLeave = (e: MouseEvent) => {
+      const target = e.relatedTarget as HTMLElement | null;
+      if (target && target.closest?.('[data-comment-id]')) return;
+      if (target && target.closest?.('.maya-comment-popover')) return;
+      hideTimer = setTimeout(() => setHoveredComment(null), 80);
+    };
+
+    root.addEventListener('mouseover', handleEnter);
+    root.addEventListener('mouseout', handleLeave);
+    return () => {
+      root.removeEventListener('mouseover', handleEnter);
+      root.removeEventListener('mouseout', handleLeave);
+      if (hideTimer) clearTimeout(hideTimer);
+    };
+  }, [editor, commentsById, viewReady]);
+
+  useEffect(() => {
+    if (editor) editor.setEditable(editable);
+  }, [editor, editable]);
+
+  useEffect(() => {
+    if (!onFullscreenChange) return;
+    onFullscreenChange(isFullscreen);
+  }, [isFullscreen, onFullscreenChange]);
+
+  if (!editor) return null;
+
+  const handlePickImage = async (file: File) => {
+    if (!uploadFile) return;
+    try {
+      const url = await uploadFile(file);
+      if (url) editor.chain().focus().setImage({ src: url, alt: file.name }).run();
+    } catch (e) {
+      // Surface as console only — the upstream uploader is expected to
+      // show its own toast/error UI.
+      console.error('[MayaEditor] image upload failed', e);
+    }
+  };
+
+  const handlePickDocx = async (file: File) => {
+    try {
+      const html = await docxToHtml(file);
+      editor.commands.setContent(html, { emitUpdate: true });
+    } catch (e) {
+      console.error('[MayaEditor] docx import failed', e);
+    }
+  };
+
+  const handleCommentSelection = async () => {
+    if (!onCreateComment) return;
+    const { from, to } = editor.state.selection;
+    if (to <= from) return;
+    const text = editor.state.doc.textBetween(from, to, ' ');
+    const id = await Promise.resolve(onCreateComment({ from, to, text }));
+    if (id == null) return;
+    editor
+      .chain()
+      .focus()
+      .setTextSelection({ from, to })
+      .setComment(id)
+      .run();
+  };
+
+  const enterSource = (target: 'html' | 'markdown') => {
+    const currentHtml = editor.getHTML();
+    const text = target === 'html' ? currentHtml : htmlToMarkdown(currentHtml);
+    setSourceText(text);
+    setViewMode(target);
+  };
+
+  const exitSource = () => {
+    const rawHtml =
+      viewMode === 'markdown'
+        ? markdownToHtml(sourceText)
+        : sourceText;
+    // Normalise complex tables (caption/tfoot/colgroup) before sanitising
+    // — DOMPurify only strips disallowed tags, it doesn't reshape the
+    // tree to match TipTap's schema.
+    const html = sanitizeEditorHtml(normalizeTableHtml(rawHtml));
+    if (editor && html != null) {
+      editor.commands.setContent(html, { emitUpdate: true });
+    }
+    setViewMode('wysiwyg');
+  };
+
+  const toggleHtml = () => {
+    if (viewMode === 'html') exitSource();
+    else if (viewMode === 'markdown') {
+      // markdown → html (switch source flavour without round-tripping the editor)
+      const html = sanitizeEditorHtml(markdownToHtml(sourceText));
+      setSourceText(html);
+      setViewMode('html');
+    } else enterSource('html');
+  };
+
+  const toggleMarkdown = () => {
+    if (viewMode === 'markdown') exitSource();
+    else if (viewMode === 'html') {
+      const md = htmlToMarkdown(sourceText);
+      setSourceText(md);
+      setViewMode('markdown');
+    } else enterSource('markdown');
+  };
+
+  return (
+    <div
+      className={`maya-editor-wrapper${isFullscreen ? ' is-fullscreen' : ''}${isDark ? ' is-dark' : ''}`}
+    >
+      <EditorToolbar
+        editor={editor}
+        mode={mode}
+        isFullscreen={isFullscreen}
+        onToggleFullscreen={
+          mode === 'full' ? () => setIsFullscreen((v) => !v) : undefined
+        }
+        onInsertHtml={mode === 'full' ? toggleHtml : undefined}
+        onInsertMarkdown={mode === 'full' ? toggleMarkdown : undefined}
+        viewMode={viewMode}
+        onImage={mode === 'full' && uploadFile ? () => fileInputRef.current?.click() : undefined}
+        onImportDocx={mode === 'full' ? () => docxInputRef.current?.click() : undefined}
+        onExportDocx={mode === 'full' && onExportDocx ? onExportDocx : undefined}
+        onAddComment={mode === 'full' && onCreateComment ? handleCommentSelection : undefined}
+        onToggleFind={mode === 'full' ? () => setFindOpen((v) => !v) : undefined}
+        labels={toolbarLabels}
+      />
+      {mode === 'full' && (
+        <FindReplaceBar
+          editor={editor}
+          open={findOpen}
+          onClose={() => setFindOpen(false)}
+          labels={{
+            findPlaceholder: toolbarLabels?.findPlaceholder ?? 'Find',
+            replacePlaceholder: toolbarLabels?.replacePlaceholder ?? 'Replace with',
+            findNext: toolbarLabels?.findNext ?? 'Next match',
+            findPrev: toolbarLabels?.findPrev ?? 'Previous match',
+            replace: toolbarLabels?.replace ?? 'Replace',
+            replaceAll: toolbarLabels?.replaceAll ?? 'Replace all',
+            close: toolbarLabels?.findClose ?? 'Close',
+            caseSensitive: toolbarLabels?.caseSensitive ?? 'Match case',
+            count: (a, b) => `${a}/${b}`,
+            none: toolbarLabels?.findNone ?? 'No matches',
+            replacedCount: (n) => `${n} replaced`,
+          }}
+        />
+      )}
+      <input
+        ref={fileInputRef}
+        type="file"
+        accept="image/*"
+        className="maya-editor-hidden-input"
+        onChange={(e) => {
+          const f = e.target.files?.[0];
+          if (f) handlePickImage(f);
+          e.target.value = '';
+        }}
+      />
+      <input
+        ref={docxInputRef}
+        type="file"
+        accept=".docx,application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+        className="maya-editor-hidden-input"
+        onChange={(e) => {
+          const f = e.target.files?.[0];
+          if (f) handlePickDocx(f);
+          e.target.value = '';
+        }}
+      />
+      <CommentHoverPopover
+        comment={hoveredComment && commentsById ? commentsById[hoveredComment.id] ?? null : null}
+        anchorRect={hoveredComment?.rect ?? null}
+        isDark={isDark}
+      />
+      {viewMode === 'wysiwyg' ? (
+        <EditorContent editor={editor} className="maya-editor-content" />
+      ) : (
+        <textarea
+          className="maya-editor-source"
+          value={sourceText}
+          onChange={(e) => setSourceText(e.target.value)}
+          spellCheck={false}
+          aria-label={
+            viewMode === 'html'
+              ? (toolbarLabels?.insertHtml ?? 'HTML source')
+              : (toolbarLabels?.insertMarkdown ?? 'Markdown source')
+          }
+        />
+      )}
+    </div>
+  );
+}

package/src/components/SourceInputDialog.tsx

@@ -0,0 +1,120 @@
+import { useEffect, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+
+interface SourceInputDialogProps {
+  open: boolean;
+  title: string;
+  description?: string;
+  placeholder?: string;
+  initialValue?: string;
+  confirmLabel: string;
+  cancelLabel: string;
+  onConfirm: (value: string) => void;
+  onCancel: () => void;
+}
+
+/**
+ * Lightweight modal used by the "Insert HTML" and "Insert Markdown"
+ * toolbar actions. Renders a sticky overlay with a textarea so power
+ * users can paste/edit source instead of clicking through the toolbar.
+ *
+ * Intentionally dependency-free: no portal, no headless-ui — the
+ * package targets multiple consumers (DMS, logs, dashboard) with
+ * different UI kits and shouldn't pull a modal lib transitively.
+ */
+export function SourceInputDialog({
+  open,
+  title,
+  description,
+  placeholder,
+  initialValue = '',
+  confirmLabel,
+  cancelLabel,
+  onConfirm,
+  onCancel,
+}: SourceInputDialogProps) {
+  const [value, setValue] = useState(initialValue);
+  const textareaRef = useRef<HTMLTextAreaElement | null>(null);
+
+  useEffect(() => {
+    if (open) {
+      setValue(initialValue);
+      // Defer focus to next tick — React mounts the textarea after the open prop flips.
+      const t = setTimeout(() => textareaRef.current?.focus(), 0);
+      return () => clearTimeout(t);
+    }
+  }, [open, initialValue]);
+
+  useEffect(() => {
+    if (!open) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        e.preventDefault();
+        onCancel();
+      }
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [open, onCancel]);
+
+  if (!open || typeof document === 'undefined') return null;
+
+  // Portal to <body> so the dialog escapes any ancestor with `overflow:
+  // hidden`, `transform`, `will-change` or `filter` (which would otherwise
+  // turn `position: fixed` into a containing-block-relative position and
+  // clip / restack the overlay behind sibling UI).
+  return createPortal(
+    <div
+      className="maya-editor-dialog-overlay"
+      role="dialog"
+      aria-modal="true"
+      aria-label={title}
+      onMouseDown={(e) => {
+        // Click on the backdrop (not on the dialog itself) cancels.
+        if (e.target === e.currentTarget) onCancel();
+      }}
+    >
+      <div className="maya-editor-dialog" onMouseDown={(e) => e.stopPropagation()}>
+        <header className="maya-editor-dialog__header">
+          <h3 className="maya-editor-dialog__title">{title}</h3>
+          <button
+            type="button"
+            className="maya-editor-dialog__close"
+            aria-label={cancelLabel}
+            onClick={onCancel}
+          >
+            ✕
+          </button>
+        </header>
+        {description && <p className="maya-editor-dialog__description">{description}</p>}
+        <textarea
+          ref={textareaRef}
+          className="maya-editor-dialog__textarea"
+          value={value}
+          placeholder={placeholder}
+          onChange={(e) => setValue(e.target.value)}
+          rows={12}
+          spellCheck={false}
+        />
+        <footer className="maya-editor-dialog__footer">
+          <button
+            type="button"
+            className="maya-editor-dialog__btn maya-editor-dialog__btn--ghost"
+            onClick={onCancel}
+          >
+            {cancelLabel}
+          </button>
+          <button
+            type="button"
+            className="maya-editor-dialog__btn maya-editor-dialog__btn--primary"
+            onClick={() => onConfirm(value)}
+            disabled={value.trim() === ''}
+          >
+            {confirmLabel}
+          </button>
+        </footer>
+      </div>
+    </div>,
+    document.body,
+  );
+}

package/src/extensions/AlertBlock.ts

@@ -0,0 +1,59 @@
+import { Node, mergeAttributes } from '@tiptap/core';
+
+export type AlertVariant = 'info' | 'warning' | 'success' | 'danger';
+
+const VARIANTS: AlertVariant[] = ['info', 'warning', 'success', 'danger'];
+
+declare module '@tiptap/core' {
+  interface Commands<ReturnType> {
+    alert: {
+      setAlert: (variant: AlertVariant) => ReturnType;
+      toggleAlert: (variant: AlertVariant) => ReturnType;
+    };
+  }
+}
+
+export const AlertBlock = Node.create({
+  name: 'alert',
+  group: 'block',
+  content: 'block+',
+  defining: true,
+
+  addAttributes() {
+    return {
+      variant: {
+        default: 'info',
+        parseHTML: (el) => {
+          const v = (el as HTMLElement).getAttribute('data-variant') ?? 'info';
+          return VARIANTS.includes(v as AlertVariant) ? v : 'info';
+        },
+        renderHTML: (attrs) => ({
+          'data-variant': attrs.variant,
+          class: `alert alert-${attrs.variant}`,
+          role: 'note',
+        }),
+      },
+    };
+  },
+
+  parseHTML() {
+    return [{ tag: 'aside[data-variant]' }, { tag: 'aside.alert' }];
+  },
+
+  renderHTML({ HTMLAttributes }) {
+    return ['aside', mergeAttributes(HTMLAttributes), 0];
+  },
+
+  addCommands() {
+    return {
+      setAlert:
+        (variant) =>
+        ({ commands }) =>
+          commands.setNode(this.name, { variant }),
+      toggleAlert:
+        (variant) =>
+        ({ commands }) =>
+          commands.toggleWrap(this.name, { variant }),
+    };
+  },
+});

package/src/extensions/CommentMark.ts

@@ -0,0 +1,57 @@
+import { Mark, mergeAttributes } from '@tiptap/core';
+
+declare module '@tiptap/core' {
+  interface Commands<ReturnType> {
+    comment: {
+      setComment: (commentId: string | number) => ReturnType;
+      unsetComment: () => ReturnType;
+    };
+  }
+}
+
+/**
+ * Mark applied to a text range that has an anchored comment.
+ *
+ * Persistence: the `commentId` attribute references `anchored_comments.id`
+ * (server-side). Rebasement on edits is handled by `CommentAnchor.rebase`
+ * via ProseMirror's `Transaction.mapping`.
+ */
+export const CommentMark = Mark.create({
+  name: 'comment',
+  inclusive: false,
+  excludes: '',
+
+  addAttributes() {
+    return {
+      commentId: {
+        default: null,
+        parseHTML: (el) => (el as HTMLElement).getAttribute('data-comment-id'),
+        renderHTML: (attrs) =>
+          attrs.commentId == null
+            ? {}
+            : { 'data-comment-id': String(attrs.commentId), class: 'maya-anchored-comment' },
+      },
+    };
+  },
+
+  parseHTML() {
+    return [{ tag: 'span[data-comment-id]' }];
+  },
+
+  renderHTML({ HTMLAttributes }) {
+    return ['span', mergeAttributes(HTMLAttributes), 0];
+  },
+
+  addCommands() {
+    return {
+      setComment:
+        (commentId) =>
+        ({ commands }) =>
+          commands.setMark(this.name, { commentId: String(commentId) }),
+      unsetComment:
+        () =>
+        ({ commands }) =>
+          commands.unsetMark(this.name),
+    };
+  },
+});

package/src/extensions/IframeBlock.ts

@@ -0,0 +1,76 @@
+import { Node, mergeAttributes } from '@tiptap/core';
+
+export interface IframeOptions {
+  HTMLAttributes: Record<string, unknown>;
+  allowedDomains: string[] | null;
+}
+
+declare module '@tiptap/core' {
+  interface Commands<ReturnType> {
+    iframe: {
+      setIframe: (options: { src: string; title?: string }) => ReturnType;
+    };
+  }
+}
+
+/**
+ * Custom iframe block — replaces the legacy `createIframeBlock.ts`
+ * BlockNote-specific component.
+ */
+export const IframeBlock = Node.create<IframeOptions>({
+  name: 'iframe',
+  group: 'block',
+  atom: true,
+  selectable: true,
+  draggable: true,
+
+  addOptions() {
+    return {
+      HTMLAttributes: {
+        sandbox: 'allow-scripts allow-same-origin',
+        loading: 'lazy',
+      },
+      allowedDomains: null,
+    };
+  },
+
+  addAttributes() {
+    return {
+      src: { default: null },
+      title: { default: null },
+      width: { default: '100%' },
+      height: { default: '400' },
+    };
+  },
+
+  parseHTML() {
+    return [{ tag: 'iframe' }];
+  },
+
+  renderHTML({ HTMLAttributes }) {
+    return ['iframe', mergeAttributes(this.options.HTMLAttributes, HTMLAttributes)];
+  },
+
+  addCommands() {
+    return {
+      setIframe:
+        (options) =>
+        ({ commands }) => {
+          if (!options.src) return false;
+          if (this.options.allowedDomains) {
+            try {
+              const url = new URL(options.src);
+              const allowed = this.options.allowedDomains.some((d) => url.host.endsWith(d));
+              if (!allowed) return false;
+            } catch {
+              return false;
+            }
+          }
+          return commands.insertContent({
+            type: this.name,
+            attrs: options,
+          });
+        },
+    };
+  },
+});