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

package/package.json

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

package/src/components/MayaEditor.tsx

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState, type MutableRefObject } from 'react';
 import { EditorContent, useEditor } from '@tiptap/react';
 import type { Editor } from '@tiptap/react';
 
@@ -31,10 +31,15 @@ export interface MayaEditorProps {
   /** 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.
+   * Llamado tras sincronizar el contenido (blur, cambio de bloque, destroy).
+   * Recibe el payload ya leído del editor; el padre suele enlazarlo a `forceSave`.
    */
-  onFlush?: () => void;
+  onFlush?: (payload?: string | TiptapDoc) => void | Promise<void>;
+  /**
+   * Ref opcional para invocar flush+sync desde fuera (p. ej. antes de cambiar de bloque),
+   * evitando perder el último keystroke por el debounce de `onChange`.
+   */
+  editorFlushRef?: MutableRefObject<(() => void | Promise<void>) | null>;
   /**
    * Output shape: `'html'` (default) emits a sanitisation-ready string;
    * `'json'` emits the full ProseMirror doc `{type:'doc', content:[…]}`,
@@ -102,6 +107,7 @@ export function MayaEditor({
   onExportDocx,
   commentsById,
   onFlush,
+  editorFlushRef,
 }: MayaEditorProps) {
   const effectiveOutput: EditorOutput = output ?? (mode === 'full' ? 'json' : 'html');
   const [isFullscreen, setIsFullscreen] = useState(false);
@@ -126,8 +132,12 @@ export function MayaEditor({
   const wrapperRef = useRef<HTMLDivElement | null>(null);
   const onChangeRef = useRef(onChange);
   const onFlushRef = useRef(onFlush);
+  const viewModeRef = useRef(viewMode);
+  const sourceTextRef = useRef(sourceText);
   onChangeRef.current = onChange;
   onFlushRef.current = onFlush;
+  viewModeRef.current = viewMode;
+  sourceTextRef.current = sourceText;
 
   const extensions = useMemo(() => buildMayaEditorExtensions(mode), [mode]);
 
@@ -148,25 +158,49 @@ export function MayaEditor({
 
   useEditorContent(editor, onChange, { output: effectiveOutput });
 
-  const syncContentToParent = useCallback(() => {
-    if (!editor) return;
-    const handler = onChangeRef.current;
-    if (!handler) return;
+  const readPayloadFromEditor = useCallback((): string | TiptapDoc | undefined => {
+    if (!editor) return undefined;
     const rawPayload =
       effectiveOutput === 'json'
         ? (editor.getJSON() as TiptapDoc)
         : editor.getHTML();
-    const payload =
-      effectiveOutput === 'json'
-        ? normalizeTiptapDocPayload(rawPayload)
-        : rawPayload;
-    handler(payload);
+    return effectiveOutput === 'json'
+      ? normalizeTiptapDocPayload(rawPayload)
+      : rawPayload;
   }, [editor, effectiveOutput]);
 
-  const requestFlush = useCallback(() => {
-    syncContentToParent();
-    onFlushRef.current?.();
-  }, [syncContentToParent]);
+  const syncContentToParent = useCallback((): string | TiptapDoc | undefined => {
+    const payload = readPayloadFromEditor();
+    if (payload === undefined) return undefined;
+    onChangeRef.current?.(payload);
+    return payload;
+  }, [readPayloadFromEditor]);
+
+  const requestFlush = useCallback(async () => {
+    if (!editor) return;
+
+    const mode = viewModeRef.current;
+    if (mode !== 'wysiwyg') {
+      const rawHtml =
+        mode === 'markdown'
+          ? markdownToHtml(sourceTextRef.current)
+          : sourceTextRef.current;
+      const html = sanitizeEditorHtml(normalizeTableHtml(rawHtml));
+      editor.commands.setContent(html, { emitUpdate: false });
+      setViewMode('wysiwyg');
+    }
+
+    const payload = syncContentToParent();
+    await onFlushRef.current?.(payload);
+  }, [editor, syncContentToParent]);
+
+  useEffect(() => {
+    if (!editorFlushRef) return;
+    editorFlushRef.current = requestFlush;
+    return () => {
+      editorFlushRef.current = null;
+    };
+  }, [editorFlushRef, requestFlush]);
 
   useEffect(() => {
     if (editor && onEditorReady) onEditorReady(editor);
@@ -174,7 +208,9 @@ export function MayaEditor({
 
   useEffect(() => {
     if (!editor || !onFlush) return;
-    const onDestroy = () => requestFlush();
+    const onDestroy = () => {
+      void requestFlush();
+    };
     editor.on('destroy', onDestroy);
     return () => {
       editor.off('destroy', onDestroy);
@@ -306,8 +342,8 @@ export function MayaEditor({
       .run();
   };
 
-  const enterSource = (target: 'html' | 'markdown') => {
-    requestFlush();
+  const enterSource = async (target: 'html' | 'markdown') => {
+    syncContentToParent();
     const currentHtml = editor.getHTML();
     const text = target === 'html' ? currentHtml : htmlToMarkdown(currentHtml);
     setSourceText(text);
@@ -336,7 +372,7 @@ export function MayaEditor({
       const html = sanitizeEditorHtml(markdownToHtml(sourceText));
       setSourceText(html);
       setViewMode('html');
-    } else enterSource('html');
+    } else void enterSource('html');
   };
 
   const toggleMarkdown = () => {
@@ -345,7 +381,7 @@ export function MayaEditor({
       const md = htmlToMarkdown(sourceText);
       setSourceText(md);
       setViewMode('markdown');
-    } else enterSource('markdown');
+    } else void enterSource('markdown');
   };
 
   return (
@@ -356,7 +392,7 @@ export function MayaEditor({
         if (!onFlush) return;
         const next = e.relatedTarget as Node | null;
         if (next && wrapperRef.current?.contains(next)) return;
-        requestFlush();
+        void requestFlush();
       }}
     >
       {editorReady && (

package/src/index.ts

@@ -32,6 +32,7 @@ export {
   isSemanticallyEmptyEditorHtml,
   isSemanticallyEmptyTiptapContent,
   normalizeTiptapContentForCompare,
+  normalizeTiptapContentForPersistence,
   normalizeTiptapDocPayload,
   tiptapContentEquals,
 } from './lib/tiptapContentSemantics';

package/src/lib/tiptapContentSemantics.test.ts

@@ -3,6 +3,7 @@ import {
   canonicalTiptapContentJson,
   isSemanticallyEmptyTiptapContent,
   normalizeTiptapContentForCompare,
+  normalizeTiptapContentForPersistence,
   tiptapContentEquals,
 } from './tiptapContentSemantics';
 
@@ -33,4 +34,183 @@ describe('tiptapContentSemantics', () => {
     const nodes = [{ type: 'image', attrs: { src: 'https://example.com/x.png' } }];
     expect(isSemanticallyEmptyTiptapContent(nodes)).toBe(false);
   });
+
+  it('ignores table colwidth attrs added by the editor on open', () => {
+    const fromTemplate = [
+      {
+        type: 'table',
+        content: [
+          {
+            type: 'tableRow',
+            content: [
+              {
+                type: 'tableCell',
+                content: [{ type: 'paragraph', content: [{ type: 'text', text: 'A' }] }],
+              },
+            ],
+          },
+        ],
+      },
+    ];
+    const afterEditor = [
+      {
+        type: 'table',
+        content: [
+          {
+            type: 'tableRow',
+            content: [
+              {
+                type: 'tableCell',
+                attrs: { colwidth: [120] },
+                content: [{ type: 'paragraph', content: [{ type: 'text', text: 'A' }] }],
+              },
+            ],
+          },
+        ],
+      },
+    ];
+    expect(tiptapContentEquals(fromTemplate, afterEditor)).toBe(true);
+  });
+
+  it('ignores volatile image attrs added by the editor on open', () => {
+    const fromTemplate = [{ type: 'image', attrs: { src: 'https://example.com/x.png', alt: 'Logo' } }];
+    const afterEditor = [{
+      type: 'image',
+      attrs: {
+        src: 'https://example.com/x.png',
+        alt: 'Logo',
+        width: 400,
+        height: 200,
+        class: 'ProseMirror-selectednode',
+      },
+    }];
+    expect(tiptapContentEquals(fromTemplate, afterEditor)).toBe(true);
+  });
+
+  it('treats tableHeader cells as tableCell for template parity', () => {
+    const fromTemplate = [{
+      type: 'table',
+      content: [{
+        type: 'tableRow',
+        content: [{
+          type: 'tableCell',
+          content: [{ type: 'paragraph', content: [{ type: 'text', text: 'A' }] }],
+        }],
+      }],
+    }];
+    const afterEditor = [{
+      type: 'table',
+      content: [{
+        type: 'tableRow',
+        content: [{
+          type: 'tableHeader',
+          attrs: { colwidth: [90] },
+          content: [{ type: 'paragraph', content: [{ type: 'text', text: 'A' }] }],
+        }],
+      }],
+    }];
+    expect(tiptapContentEquals(fromTemplate, afterEditor)).toBe(true);
+  });
+
+  it('does not treat paragraph with nested image as semantically empty', () => {
+    const nodes = [{
+      type: 'paragraph',
+      content: [{ type: 'image', attrs: { src: 'https://example.com/x.png' } }],
+    }];
+    expect(isSemanticallyEmptyTiptapContent(nodes)).toBe(false);
+  });
+
+  it('preserves heading level and text for persistence', () => {
+    const heading = [{
+      type: 'heading',
+      attrs: { level: 1 },
+      content: [{ type: 'text', text: 'Título H1' }],
+    }];
+    expect(normalizeTiptapContentForPersistence(heading)).toEqual(heading);
+  });
+
+  it('compare normalization keeps text on inline nodes', () => {
+    const nodes = [{
+      type: 'heading',
+      attrs: { level: 1 },
+      content: [{ type: 'text', text: 'Hola' }],
+    }];
+    expect(normalizeTiptapContentForCompare(nodes)).toEqual(nodes);
+  });
+
+  it('ignores phantom empty paragraphs inside table cells', () => {
+    const template = [{
+      type: 'table',
+      content: [{
+        type: 'tableRow',
+        content: [{
+          type: 'tableCell',
+          content: [{ type: 'paragraph', content: [{ type: 'text', text: 'c' }] }],
+        }],
+      }],
+    }];
+    const afterEditor = [{
+      type: 'table',
+      content: [{
+        type: 'tableRow',
+        content: [{
+          type: 'tableCell',
+          attrs: { colwidth: [100] },
+          content: [
+            { type: 'paragraph', content: [{ type: 'text', text: 'c' }] },
+            { type: 'paragraph', content: [] },
+          ],
+        }],
+      }],
+    }];
+    expect(tiptapContentEquals(template, afterEditor)).toBe(true);
+  });
+
+  it('ignores empty list items added by pressing Enter without content', () => {
+    const template = [{
+      type: 'bulletList',
+      content: [{
+        type: 'listItem',
+        content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Uno' }] }],
+      }],
+    }];
+    const afterEditor = [{
+      type: 'bulletList',
+      content: [
+        {
+          type: 'listItem',
+          content: [{ type: 'paragraph', content: [] }],
+        },
+        {
+          type: 'listItem',
+          content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Uno' }] }],
+        },
+      ],
+    }];
+    expect(tiptapContentEquals(template, afterEditor)).toBe(true);
+  });
+
+  it('ignores trailing empty list item at end of list', () => {
+    const template = [{
+      type: 'bulletList',
+      content: [{
+        type: 'listItem',
+        content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Uno' }] }],
+      }],
+    }];
+    const afterEditor = [{
+      type: 'bulletList',
+      content: [
+        {
+          type: 'listItem',
+          content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Uno' }] }],
+        },
+        {
+          type: 'listItem',
+          content: [{ type: 'paragraph', content: [] }],
+        },
+      ],
+    }];
+    expect(tiptapContentEquals(template, afterEditor)).toBe(true);
+  });
 });

package/src/lib/tiptapContentSemantics.ts

@@ -36,6 +36,29 @@ function inlineTextLength(nodes: unknown): number {
   return length;
 }
 
+/** True when inline/block children carry text or non-empty media (e.g. image in paragraph). */
+function blockChildrenHaveMeaningfulContent(nodes: unknown): boolean {
+  if (!Array.isArray(nodes)) return false;
+
+  for (const raw of nodes) {
+    const node = asNode(raw);
+    if (!node) continue;
+    if (node.type === 'text' && typeof node.text === 'string') {
+      if (node.text.replace(/\u00a0/g, ' ').trim().length > 0) return true;
+      continue;
+    }
+    if (node.type === 'hardBreak') continue;
+    if (MEANINGFUL_BLOCK_TYPES.has(node.type) && !isEmptyTiptapBlockNode(node)) {
+      return true;
+    }
+    if (Array.isArray(node.content) && blockChildrenHaveMeaningfulContent(node.content)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
 /** True for TipTap/BlockNote blocks with no visible text and no embedded media. */
 export function isEmptyTiptapBlockNode(node: unknown): boolean {
   const n = asNode(node);
@@ -68,7 +91,7 @@ export function isEmptyTiptapBlockNode(node: unknown): boolean {
   }
 
   // paragraph, heading, legacy BlockNote blocks, etc.
-  return inlineTextLength(n.content ?? []) === 0;
+  return !blockChildrenHaveMeaningfulContent(n.content ?? []);
 }
 
 function toContentArray(value: unknown): unknown[] {
@@ -80,11 +103,101 @@ function toContentArray(value: unknown): unknown[] {
   return [];
 }
 
+/** Atributos que TipTap añade al abrir/guardar y no representan edición del usuario. */
+const VOLATILE_NODE_ATTR_KEYS = new Set([
+  'colwidth',
+  'columnSizing',
+  'data-colwidth',
+  'width',
+  'height',
+  'style',
+  'class',
+  'title',
+]);
+
+const IMAGE_COMPARE_ATTR_KEYS = ['src', 'alt'] as const;
+
+function stripTrailingEmptyBlocks(nodes: unknown[]): unknown[] {
+  const out = JSON.parse(JSON.stringify(nodes));
+
+  return out;
+}
+
+function canonicalizeNodeAttrs(type: string, rawAttrs: unknown): Record<string, unknown> | undefined {
+  if (!isRecord(rawAttrs)) return undefined;
+
+  let attrs: Record<string, unknown> = { ...rawAttrs };
+  if (type === 'image') {
+    const picked: Record<string, unknown> = {};
+    for (const key of IMAGE_COMPARE_ATTR_KEYS) {
+      const value = attrs[key];
+      if (value != null && String(value).trim() !== '') {
+        picked[key] = value;
+      }
+    }
+    return Object.keys(picked).length > 0 ? picked : undefined;
+  }
+
+  for (const key of VOLATILE_NODE_ATTR_KEYS) {
+    delete attrs[key];
+  }
+  if (type === 'tableCell' && attrs.colspan === 1) delete attrs.colspan;
+  if (type === 'tableCell' && attrs.rowspan === 1) delete attrs.rowspan;
+
+  return Object.keys(attrs).length > 0 ? attrs : undefined;
+}
+
+/** Canonicalize and drop phantom empty nodes at every depth (cells, list items, etc.). */
+function canonicalizeNodeForCompare(node: unknown): unknown | null {
+  const n = asNode(node);
+  if (!n?.type) return null;
+
+  if (n.type === 'text') {
+    const text = typeof n.text === 'string' ? n.text : '';
+    const hasMarks = Array.isArray(n.marks) && n.marks.length > 0;
+    if (text.replace(/\u00a0/g, ' ').trim() === '' && !hasMarks) {
+      return null;
+    }
+    return {
+      type: 'text',
+      ...(typeof n.text === 'string' ? { text: n.text } : {}),
+      ...(hasMarks ? { marks: n.marks } : {}),
+    };
+  }
+
+  // TipTap may emit tableHeader where the template stored tableCell.
+  const rawType = n.type;
+  const type = rawType === 'tableHeader' ? 'tableCell' : rawType;
+  const attrs = canonicalizeNodeAttrs(type, n.attrs);
+
+  let content: unknown[] | undefined;
+  if (Array.isArray(n.content)) {
+    let children = n.content
+      .map((child) => canonicalizeNodeForCompare(child))
+      .filter((child): child is unknown => child != null);
+
+    if (rawType === 'bulletList' || rawType === 'orderedList' || rawType === 'taskList') {
+      children = children.filter((child) => !isEmptyTiptapBlockNode(child));
+    }
+      
+    children = stripTrailingEmptyBlocks(children);
+    content = children.length > 0 ? children : undefined;
+  }
+
+  const out = {
+    type,
+    ...(attrs ? { attrs } : {}),
+    ...(content !== undefined ? { content } : {}),
+  };
+
+  return isEmptyTiptapBlockNode(out) ? null : out;
+}
+
 /**
  * Strips trailing empty paragraphs TipTap adds for cursor placement.
- * Returns a new array; does not mutate the input.
+ * Preserves the full node tree (text, marks, heading levels) for persistence.
  */
-export function normalizeTiptapContentForCompare(value: unknown): unknown[] {
+export function normalizeTiptapContentForPersistence(value: unknown): unknown[] {
   const nodes = [...toContentArray(value)];
   while (nodes.length > 0 && isEmptyTiptapBlockNode(nodes[nodes.length - 1])) {
     nodes.pop();
@@ -92,6 +205,18 @@ export function normalizeTiptapContentForCompare(value: unknown): unknown[] {
   return nodes;
 }
 
+/**
+ * Canonical form for semantic diff/compare (strips volatile attrs, trailing empties).
+ * Returns a new array; does not mutate the input.
+ */
+export function normalizeTiptapContentForCompare(value: unknown): unknown[] {
+  const nodes = toContentArray(value)
+    .map((node) => canonicalizeNodeForCompare(node))
+    .filter((node): node is unknown => node != null);
+
+  return stripTrailingEmptyBlocks(nodes);
+}
+
 /**
  * True when content has no meaningful text or media (e.g. only `<p></p>` / `paragraph: []`).
  */
@@ -136,6 +261,6 @@ export function normalizeTiptapDocPayload(payload: string | TiptapDoc): string |
   if (typeof payload === 'string') return payload;
   return {
     ...payload,
-    content: normalizeTiptapContentForCompare(payload.content) as TiptapDoc['content'],
+    content: normalizeTiptapContentForPersistence(payload.content) as TiptapDoc['content'],
   };
 }