@ceedcv-maya/shared-editor-react 0.7.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ceedcv-maya/shared-editor-react",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/components/MayaEditor.tsx

@@ -1,8 +1,10 @@
-import { useEffect, useMemo, useRef, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { EditorContent, useEditor } from '@tiptap/react';
 import type { Editor } from '@tiptap/react';
 
 import { buildMayaEditorExtensions } from '../lib/editorExtensions';
+import { normalizeTiptapDocPayload } from '../lib/tiptapContentSemantics';
+import { isEditorReady } from '../lib/isEditorReady';
 import { useEditorContent, type EditorOutput } from '../hooks/useEditorContent';
 import { sanitizeEditorHtml } from '../lib/dompurifyConfig';
 import { markdownToHtml } from '../lib/markdownToHtml';
@@ -28,6 +30,11 @@ export interface MayaEditorProps {
   mode?: EditorMode;
   /** Debounced change callback (300ms). Payload depends on `output`. */
   onChange?: (payload: string | TiptapDoc) => void;
+  /**
+   * Llamado al perder el foco del editor, antes de HTML/Markdown o al destruir
+   * la instancia. El padre suele enlazarlo a `forceSave` del autoguardado.
+   */
+  onFlush?: () => void;
   /**
    * Output shape: `'html'` (default) emits a sanitisation-ready string;
    * `'json'` emits the full ProseMirror doc `{type:'doc', content:[…]}`,
@@ -94,6 +101,7 @@ export function MayaEditor({
   onCreateComment,
   onExportDocx,
   commentsById,
+  onFlush,
 }: MayaEditorProps) {
   const effectiveOutput: EditorOutput = output ?? (mode === 'full' ? 'json' : 'html');
   const [isFullscreen, setIsFullscreen] = useState(false);
@@ -115,6 +123,11 @@ export function MayaEditor({
   const [viewReady, setViewReady] = useState(false);
   const fileInputRef = useRef<HTMLInputElement | null>(null);
   const docxInputRef = useRef<HTMLInputElement | null>(null);
+  const wrapperRef = useRef<HTMLDivElement | null>(null);
+  const onChangeRef = useRef(onChange);
+  const onFlushRef = useRef(onFlush);
+  onChangeRef.current = onChange;
+  onFlushRef.current = onFlush;
 
   const extensions = useMemo(() => buildMayaEditorExtensions(mode), [mode]);
 
@@ -135,26 +148,67 @@ export function MayaEditor({
 
   useEditorContent(editor, onChange, { output: effectiveOutput });
 
+  const syncContentToParent = useCallback(() => {
+    if (!editor) return;
+    const handler = onChangeRef.current;
+    if (!handler) return;
+    const rawPayload =
+      effectiveOutput === 'json'
+        ? (editor.getJSON() as TiptapDoc)
+        : editor.getHTML();
+    const payload =
+      effectiveOutput === 'json'
+        ? normalizeTiptapDocPayload(rawPayload)
+        : rawPayload;
+    handler(payload);
+  }, [editor, effectiveOutput]);
+
+  const requestFlush = useCallback(() => {
+    syncContentToParent();
+    onFlushRef.current?.();
+  }, [syncContentToParent]);
+
   useEffect(() => {
     if (editor && onEditorReady) onEditorReady(editor);
   }, [editor, onEditorReady]);
 
   useEffect(() => {
+    if (!editor || !onFlush) return;
+    const onDestroy = () => requestFlush();
+    editor.on('destroy', onDestroy);
+    return () => {
+      editor.off('destroy', onDestroy);
+    };
+  }, [editor, onFlush, requestFlush]);
+
+  useEffect(() => {
+    setViewReady(false);
     if (!editor) return;
-    const bump = () => setSelectionVersion((v) => v + 1);
+
+    const bump = () => {
+      if (!isEditorReady(editor)) return;
+      setSelectionVersion((v) => v + 1);
+    };
     const markReady = () => setViewReady(true);
+    const markNotReady = () => setViewReady(false);
+
     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).
+    editor.on('destroy', markNotReady);
+
     try {
-      if (editor.view && editor.view.dom) setViewReady(true);
-    } catch { /* view not ready yet — markReady will fire it */ }
+      if (editor.view?.dom) setViewReady(true);
+    } catch {
+      /* view not ready yet — markReady will fire on create */
+    }
+
     return () => {
       editor.off('selectionUpdate', bump);
       editor.off('transaction', bump);
       editor.off('create', markReady);
+      editor.off('destroy', markNotReady);
+      setViewReady(false);
     };
   }, [editor]);
 
@@ -214,6 +268,8 @@ export function MayaEditor({
 
   if (!editor) return null;
 
+  const editorReady = viewReady && isEditorReady(editor);
+
   const handlePickImage = async (file: File) => {
     if (!uploadFile) return;
     try {
@@ -251,6 +307,7 @@ export function MayaEditor({
   };
 
   const enterSource = (target: 'html' | 'markdown') => {
+    requestFlush();
     const currentHtml = editor.getHTML();
     const text = target === 'html' ? currentHtml : htmlToMarkdown(currentHtml);
     setSourceText(text);
@@ -293,8 +350,16 @@ export function MayaEditor({
 
   return (
     <div
+      ref={wrapperRef}
       className={`maya-editor-wrapper${isFullscreen ? ' is-fullscreen' : ''}${isDark ? ' is-dark' : ''}`}
+      onBlur={(e) => {
+        if (!onFlush) return;
+        const next = e.relatedTarget as Node | null;
+        if (next && wrapperRef.current?.contains(next)) return;
+        requestFlush();
+      }}
     >
+      {editorReady && (
       <EditorToolbar
         editor={editor}
         mode={mode}
@@ -312,7 +377,8 @@ export function MayaEditor({
         onToggleFind={mode === 'full' ? () => setFindOpen((v) => !v) : undefined}
         labels={toolbarLabels}
       />
-      {mode === 'full' && (
+      )}
+      {mode === 'full' && editorReady && (
         <FindReplaceBar
           editor={editor}
           open={findOpen}

package/src/hooks/useEditorContent.ts

@@ -1,6 +1,11 @@
 import { useEffect, useRef } from 'react';
 import type { Editor } from '@tiptap/react';
 import type { TiptapDoc } from '../types';
+import {
+  canonicalTiptapContentJson,
+  isSemanticallyEmptyEditorHtml,
+  normalizeTiptapDocPayload,
+} from '../lib/tiptapContentSemantics';
 
 export type EditorOutput = 'html' | 'json';
 
@@ -24,16 +29,38 @@ export function useEditorContent(
   const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const handlerRef = useRef(onChange);
   handlerRef.current = onChange;
+  const lastEmittedRef = useRef<string | null>(null);
 
   useEffect(() => {
     if (!editor) return;
+    lastEmittedRef.current = null;
 
     const handleUpdate = () => {
       if (timeoutRef.current) clearTimeout(timeoutRef.current);
       timeoutRef.current = setTimeout(() => {
-        const payload = output === 'json'
+        const rawPayload = output === 'json'
           ? (editor.getJSON() as TiptapDoc)
           : editor.getHTML();
+        const payload = output === 'json'
+          ? normalizeTiptapDocPayload(rawPayload)
+          : rawPayload;
+
+        const fingerprint = output === 'json'
+          ? canonicalTiptapContentJson((payload as TiptapDoc).content)
+          : payload;
+
+        if (typeof fingerprint === 'string' && fingerprint === lastEmittedRef.current) {
+          return;
+        }
+
+        if (output === 'html' && typeof payload === 'string' && isSemanticallyEmptyEditorHtml(payload)) {
+          if (lastEmittedRef.current === '') return;
+          lastEmittedRef.current = '';
+          handlerRef.current?.(payload);
+          return;
+        }
+
+        lastEmittedRef.current = typeof fingerprint === 'string' ? fingerprint : null;
         handlerRef.current?.(payload);
       }, delayMs);
     };

package/src/index.ts

@@ -24,6 +24,17 @@ export { splitHtmlIntoBlocks } from './lib/splitHtmlIntoBlocks';
 export type { BlockChunk, BlockChunkType } from './lib/splitHtmlIntoBlocks';
 export { htmlToTiptapDoc } from './lib/htmlToTiptapDoc';
 export { buildMayaEditorExtensions } from './lib/editorExtensions';
+export { isEditorReady } from './lib/isEditorReady';
+export {
+  canonicalTiptapContentJson,
+  htmlVisibleTextLength,
+  isEmptyTiptapBlockNode,
+  isSemanticallyEmptyEditorHtml,
+  isSemanticallyEmptyTiptapContent,
+  normalizeTiptapContentForCompare,
+  normalizeTiptapDocPayload,
+  tiptapContentEquals,
+} from './lib/tiptapContentSemantics';
 export { docxToHtml, docxToHtmlResult } from './lib/docxToHtml';
 export type { DocxConversionMessage, DocxConversionResult } from './lib/docxToHtml';
 export { SourceInputDialog } from './components/SourceInputDialog';

package/src/lib/isEditorReady.ts

@@ -0,0 +1,13 @@
+import type { Editor } from '@tiptap/react';
+
+/**
+ * TipTap puede exponer una instancia con `commandManager === null` tras destroy
+ * o antes del evento `create`. Solo la UI que invoca comandos debe usar esto.
+ */
+export function isEditorReady(editor: Editor | null | undefined): editor is Editor {
+  if (!editor) {
+    return false;
+  }
+
+  return !editor.isDestroyed;
+}

package/src/lib/tiptapContentSemantics.test.ts

@@ -0,0 +1,36 @@
+import { describe, it, expect } from 'vitest';
+import {
+  canonicalTiptapContentJson,
+  isSemanticallyEmptyTiptapContent,
+  normalizeTiptapContentForCompare,
+  tiptapContentEquals,
+} from './tiptapContentSemantics';
+
+describe('tiptapContentSemantics', () => {
+  it('treats a lone empty paragraph as semantically empty', () => {
+    const empty = [{ type: 'paragraph', content: [] }];
+    expect(isSemanticallyEmptyTiptapContent(empty)).toBe(true);
+    expect(normalizeTiptapContentForCompare(empty)).toEqual([]);
+  });
+
+  it('strips trailing empty paragraph so phantom TipTap nodes do not differ', () => {
+    const withText = [{ type: 'paragraph', content: [{ type: 'text', text: 'Hola' }] }];
+    const withPhantom = [
+      ...withText,
+      { type: 'paragraph', content: [] },
+    ];
+    expect(tiptapContentEquals(withText, withPhantom)).toBe(true);
+    expect(canonicalTiptapContentJson(withPhantom)).toBe(canonicalTiptapContentJson(withText));
+  });
+
+  it('detects real edits after normalization', () => {
+    const a = [{ type: 'paragraph', content: [{ type: 'text', text: 'A' }] }];
+    const b = [{ type: 'paragraph', content: [{ type: 'text', text: 'B' }] }];
+    expect(tiptapContentEquals(a, b)).toBe(false);
+  });
+
+  it('keeps non-empty images as filled', () => {
+    const nodes = [{ type: 'image', attrs: { src: 'https://example.com/x.png' } }];
+    expect(isSemanticallyEmptyTiptapContent(nodes)).toBe(false);
+  });
+});

package/src/lib/tiptapContentSemantics.ts

@@ -0,0 +1,141 @@
+import type { TiptapDoc, TiptapNode } from '../types';
+
+const MEANINGFUL_BLOCK_TYPES = new Set([
+  'image',
+  'table',
+  'iframeBlock',
+  'alertBlock',
+  'horizontalRule',
+  'codeBlock',
+]);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function asNode(value: unknown): TiptapNode | null {
+  return isRecord(value) && typeof value.type === 'string' ? (value as TiptapNode) : null;
+}
+
+function inlineTextLength(nodes: unknown): number {
+  if (!Array.isArray(nodes)) return 0;
+
+  let length = 0;
+  for (const raw of nodes) {
+    const node = asNode(raw);
+    if (!node) continue;
+    if (node.type === 'text' && typeof node.text === 'string') {
+      length += node.text.replace(/\u00a0/g, ' ').trim().length;
+    } else if (node.type === 'hardBreak') {
+      continue;
+    } else if (Array.isArray(node.content)) {
+      length += inlineTextLength(node.content);
+    }
+  }
+
+  return length;
+}
+
+/** True for TipTap/BlockNote blocks with no visible text and no embedded media. */
+export function isEmptyTiptapBlockNode(node: unknown): boolean {
+  const n = asNode(node);
+  if (!n?.type) return true;
+
+  if (MEANINGFUL_BLOCK_TYPES.has(n.type)) {
+    if (n.type === 'horizontalRule') return false;
+    if (n.type === 'image') {
+      return !String(n.attrs?.src ?? '').trim();
+    }
+    if (n.type === 'codeBlock') {
+      return inlineTextLength(n.content ?? []) === 0;
+    }
+    return false;
+  }
+
+  if (n.type === 'bulletList' || n.type === 'orderedList' || n.type === 'taskList') {
+    const items = Array.isArray(n.content) ? n.content : [];
+    return items.length === 0 || items.every((item) => isEmptyTiptapBlockNode(item));
+  }
+
+  if (n.type === 'listItem' || n.type === 'taskItem') {
+    const inner = Array.isArray(n.content) ? n.content : [];
+    return inner.length === 0 || inner.every((child) => isEmptyTiptapBlockNode(child));
+  }
+
+  if (n.type === 'blockquote') {
+    const inner = Array.isArray(n.content) ? n.content : [];
+    return inner.length === 0 || inner.every((child) => isEmptyTiptapBlockNode(child));
+  }
+
+  // paragraph, heading, legacy BlockNote blocks, etc.
+  return inlineTextLength(n.content ?? []) === 0;
+}
+
+function toContentArray(value: unknown): unknown[] {
+  if (value == null) return [];
+  if (Array.isArray(value)) return value;
+  if (isRecord(value) && value.type === 'doc' && Array.isArray(value.content)) {
+    return value.content;
+  }
+  return [];
+}
+
+/**
+ * Strips trailing empty paragraphs TipTap adds for cursor placement.
+ * Returns a new array; does not mutate the input.
+ */
+export function normalizeTiptapContentForCompare(value: unknown): unknown[] {
+  const nodes = [...toContentArray(value)];
+  while (nodes.length > 0 && isEmptyTiptapBlockNode(nodes[nodes.length - 1])) {
+    nodes.pop();
+  }
+  return nodes;
+}
+
+/**
+ * True when content has no meaningful text or media (e.g. only `<p></p>` / `paragraph: []`).
+ */
+export function isSemanticallyEmptyTiptapContent(value: unknown): boolean {
+  const nodes = normalizeTiptapContentForCompare(value);
+  if (nodes.length === 0) return true;
+  return nodes.every((node) => isEmptyTiptapBlockNode(node));
+}
+
+export function canonicalTiptapContentJson(value: unknown): string {
+  try {
+    return JSON.stringify(normalizeTiptapContentForCompare(value));
+  } catch {
+    return '';
+  }
+}
+
+export function tiptapContentEquals(a: unknown, b: unknown): boolean {
+  return canonicalTiptapContentJson(a) === canonicalTiptapContentJson(b);
+}
+
+/**
+ * Visible character count of editor HTML (ignores tags). Matches logs comment validation.
+ */
+export function htmlVisibleTextLength(html: string): number {
+  const text = html
+    .replace(/<[^>]+>/g, '')
+    .replace(/&nbsp;/gi, ' ')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&amp;/g, '&')
+    .trim();
+  return text.length;
+}
+
+export function isSemanticallyEmptyEditorHtml(html: string): boolean {
+  return htmlVisibleTextLength(html) === 0;
+}
+
+/** Payload shape for MayaEditor `output="json"`. */
+export function normalizeTiptapDocPayload(payload: string | TiptapDoc): string | TiptapDoc {
+  if (typeof payload === 'string') return payload;
+  return {
+    ...payload,
+    content: normalizeTiptapContentForCompare(payload.content) as TiptapDoc['content'],
+  };
+}