@tuturuuu/ui 0.19.1 → 0.21.0

package/src/components/ui/text-editor/editor.tsx

@@ -59,6 +59,14 @@ function syncEditorContent(editor: Editor, nextContent: JSONContent | null) {
   }
 }
 
+/**
+ * Hides the formatting toolbar until focus lands inside the editor. Scoped to the
+ * `group` wrapper below so focus on a toolbar button keeps it visible — otherwise
+ * the toolbar would disappear on mousedown, before the click could land.
+ */
+export const REVEAL_TOOLBAR_ON_FOCUS_CLASS_NAME =
+  'pointer-events-none opacity-0 transition-opacity duration-200 group-focus-within:pointer-events-auto group-focus-within:opacity-100';
+
 function serializeEditorContent(content: JSONContent | null) {
   return JSON.stringify(content ?? { type: 'doc', content: [] });
 }
@@ -90,6 +98,14 @@ export interface RichTextEditorProps {
   queryClient?: QueryClient;
   onConvertToTask?: () => void | Promise<void>;
   allowCollaboration?: boolean;
+  /**
+   * Keep the formatting toolbar transparent until focus is somewhere inside the
+   * editor, so a read-first surface (like the task dialog) is not fronted by a
+   * row of controls. Focus-within — not editor focus — because clicking a
+   * toolbar button moves focus out of the text and would otherwise hide the
+   * toolbar mid-click.
+   */
+  revealToolbarOnFocus?: boolean;
   /** Translations for mention chip dialogs */
   mentionTranslations?: {
     delete_task?: string;
@@ -137,6 +153,7 @@ export function RichTextEditor({
   yjsProvider,
   collaborationUser,
   allowCollaboration = false,
+  revealToolbarOnFocus = false,
   mentionTranslations,
   renderTaskMention,
 }: RichTextEditorProps) {
@@ -158,6 +175,26 @@ export function RichTextEditor({
     []
   );
 
+  // Collaboration bindings decide which extensions the editor is built with, and
+  // `Editor.setOptions({ extensions })` does NOT rebuild the extension manager —
+  // it only refreshes editor props. So a binding change has to recreate the
+  // editor through `useEditor`'s dependency array. Without this, an editor first
+  // created while collaboration was still off (e.g. a task dialog opened from a
+  // deep link, which mounts before the task has hydrated) never gains the
+  // Collaboration extension, and content that lives only in the Yjs document can
+  // never render.
+  //
+  // ONLY the document binding belongs in that dependency array. The Yjs document
+  // is what the content lives in, so getting it wrong is a correctness bug worth
+  // a rebuild. The provider only feeds CollaborationCaret (remote cursor labels),
+  // which is cosmetic and normally already attached because the provider exists
+  // before this subtree mounts — rebuilding a live editor for it would tear down
+  // the ProseMirror view (losing selection and scroll position) and re-run the
+  // Yjs binding over the whole document mid-session, which on a large document is
+  // an expensive, user-visible hiccup for no content benefit.
+  const collaborationDoc = allowCollaboration ? yjsDoc : undefined;
+  const collaborationProvider = allowCollaboration ? yjsProvider : undefined;
+
   useEffect(() => {
     onImageUploadRef.current = onImageUpload;
     workspaceIdRef.current = workspaceId;
@@ -303,271 +340,234 @@ export function RichTextEditor({
     return baseClasses.join(' ');
   }, [className, readOnly]);
 
-  const editor = useEditor({
-    extensions: getEditorExtensions({
-      titlePlaceholder,
-      writePlaceholder,
-      doc: allowCollaboration ? yjsDoc : undefined,
-      provider: allowCollaboration ? yjsProvider : undefined,
-      collaborationUser: allowCollaboration ? collaborationUser : undefined,
-      onImageUpload,
-      onVideoUpload: onImageUpload,
-      getOnImageUpload: getDelegatedImageUpload,
-      getOnVideoUpload: getDelegatedImageUpload,
-      mentionTranslations,
-      renderTaskMention,
-      readOnly,
-    }),
-    // Migrate inline images to block-level for backward compatibility
-    content: allowCollaboration
-      ? undefined
-      : migrateInlineImagesToBlock(content),
-    editable: !readOnly,
-    immediatelyRender: false,
-    editorProps: {
-      attributes: {
-        class: getEditorClasses,
-      },
-      handleKeyDown: (view, event) => {
-        // Prevent Ctrl+Enter / Cmd+Enter from creating a new line
-        // Let the parent component handle the save action
-        if ((event.ctrlKey || event.metaKey) && event.key === 'Enter') {
-          event.preventDefault();
-          return true;
-        }
-
-        if (handlePlainEnterFallback(view, event)) {
-          return true;
-        }
-
-        const { state, dispatch } = view;
-        const { selection } = state;
-        const { $from } = selection;
+  const editor = useEditor(
+    {
+      extensions: getEditorExtensions({
+        titlePlaceholder,
+        writePlaceholder,
+        doc: collaborationDoc,
+        provider: collaborationProvider,
+        collaborationUser: allowCollaboration ? collaborationUser : undefined,
+        onImageUpload,
+        onVideoUpload: onImageUpload,
+        getOnImageUpload: getDelegatedImageUpload,
+        getOnVideoUpload: getDelegatedImageUpload,
+        mentionTranslations,
+        renderTaskMention,
+        readOnly,
+      }),
+      // Migrate inline images to block-level for backward compatibility
+      content: allowCollaboration
+        ? undefined
+        : migrateInlineImagesToBlock(content),
+      editable: !readOnly,
+      immediatelyRender: false,
+      editorProps: {
+        attributes: {
+          class: getEditorClasses,
+        },
+        handleKeyDown: (view, event) => {
+          // Prevent Ctrl+Enter / Cmd+Enter from creating a new line
+          // Let the parent component handle the save action
+          if ((event.ctrlKey || event.metaKey) && event.key === 'Enter') {
+            event.preventDefault();
+            return true;
+          }
 
-        // Handle Backspace
-        if (event.key === 'Backspace' && onArrowUpRef.current) {
-          // If there's a text selection, let default behavior handle deletion
-          if (!selection.empty) {
-            return false;
+          if (handlePlainEnterFallback(view, event)) {
+            return true;
           }
 
-          console.log('Backspace at pos:', $from.pos);
+          const { state, dispatch } = view;
+          const { selection } = state;
+          const { $from } = selection;
 
-          // Check if we're on the first line
-          const coordsAtCursor = view.coordsAtPos($from.pos);
-          const coordsAtStart = view.coordsAtPos(1);
-          const isOnFirstLine =
-            coordsAtCursor &&
-            coordsAtStart &&
-            Math.abs(coordsAtCursor.top - coordsAtStart.top) < 5;
+          // Handle Backspace
+          if (event.key === 'Backspace' && onArrowUpRef.current) {
+            // If there's a text selection, let default behavior handle deletion
+            if (!selection.empty) {
+              return false;
+            }
 
-          console.log('Is on first line:', isOnFirstLine);
+            console.log('Backspace at pos:', $from.pos);
 
-          if (isOnFirstLine) {
-            const firstChild = state.doc.firstChild;
-            console.log('First child:', {
-              type: firstChild?.type.name,
-              text: firstChild?.textContent,
-              isEmpty: firstChild?.textContent.trim() === '',
-              nodeSize: firstChild?.nodeSize,
-            });
+            // Check if we're on the first line
+            const coordsAtCursor = view.coordsAtPos($from.pos);
+            const coordsAtStart = view.coordsAtPos(1);
+            const isOnFirstLine =
+              coordsAtCursor &&
+              coordsAtStart &&
+              Math.abs(coordsAtCursor.top - coordsAtStart.top) < 5;
 
-            // If cursor is at the absolute start (position 1)
-            if ($from.pos === 1) {
-              const firstChild = state.doc.firstChild;
+            console.log('Is on first line:', isOnFirstLine);
 
-              // If first line is empty and there's a second line, delete the empty line
-              if (firstChild && firstChild.textContent.trim() === '') {
-                const secondChild = state.doc.maybeChild(1);
-                if (secondChild) {
-                  console.log(
-                    'Empty first line - manually deleting via commands'
-                  );
-                  event.preventDefault();
-
-                  // Use commands to delete the node
-                  const tr = state.tr;
-                  const nodeSize = firstChild.nodeSize;
-
-                  // Delete from position 0 to end of first child (including the node itself)
-                  tr.delete(0, nodeSize);
-
-                  // Dispatch and trigger onChange manually
-                  dispatch(tr);
-
-                  // Manually trigger onChange since we're in handleKeyDown
-                  if (!readOnly && onChangeRef.current) {
-                    const newJson = tr.doc.toJSON();
-                    onChangeRef.current(hasContent(newJson) ? newJson : null);
+            if (isOnFirstLine) {
+              const firstChild = state.doc.firstChild;
+              console.log('First child:', {
+                type: firstChild?.type.name,
+                text: firstChild?.textContent,
+                isEmpty: firstChild?.textContent.trim() === '',
+                nodeSize: firstChild?.nodeSize,
+              });
+
+              // If cursor is at the absolute start (position 1)
+              if ($from.pos === 1) {
+                const firstChild = state.doc.firstChild;
+
+                // If first line is empty and there's a second line, delete the empty line
+                if (firstChild && firstChild.textContent.trim() === '') {
+                  const secondChild = state.doc.maybeChild(1);
+                  if (secondChild) {
+                    console.log(
+                      'Empty first line - manually deleting via commands'
+                    );
+                    event.preventDefault();
+
+                    // Use commands to delete the node
+                    const tr = state.tr;
+                    const nodeSize = firstChild.nodeSize;
+
+                    // Delete from position 0 to end of first child (including the node itself)
+                    tr.delete(0, nodeSize);
+
+                    // Dispatch and trigger onChange manually
+                    dispatch(tr);
+
+                    // Manually trigger onChange since we're in handleKeyDown
+                    if (!readOnly && onChangeRef.current) {
+                      const newJson = tr.doc.toJSON();
+                      onChangeRef.current(hasContent(newJson) ? newJson : null);
+                    }
+
+                    return true;
                   }
-
-                  return true;
                 }
+
+                // If first line is NOT empty, go to title
+                console.log('Non-empty first line - going to title');
+                event.preventDefault();
+                onArrowUpRef.current();
+                return true;
               }
+            }
+          }
 
-              // If first line is NOT empty, go to title
-              console.log('Non-empty first line - going to title');
+          // Handle ArrowUp when on the first line
+          if (event.key === 'ArrowUp' && onArrowUpRef.current) {
+            // Try to resolve a position one line up by checking textBetween
+            // If we're at the very start of the document (pos 1), go to title
+            if ($from.pos === 1) {
               event.preventDefault();
-              onArrowUpRef.current();
+              onArrowUpRef.current(0); // At the start, offset is 0
               return true;
             }
-          }
-        }
-
-        // Handle ArrowUp when on the first line
-        if (event.key === 'ArrowUp' && onArrowUpRef.current) {
-          // Try to resolve a position one line up by checking textBetween
-          // If we're at the very start of the document (pos 1), go to title
-          if ($from.pos === 1) {
-            event.preventDefault();
-            onArrowUpRef.current(0); // At the start, offset is 0
-            return true;
-          }
 
-          // Check if we're in a position where up arrow won't move us
-          // This happens when we're on the first line of the first block
-          const coordsAtCursor = view.coordsAtPos($from.pos);
-          const coordsAtStart = view.coordsAtPos(1);
-
-          // If cursor is on the same line as the start, go to title
-          if (
-            coordsAtCursor &&
-            coordsAtStart &&
-            Math.abs(coordsAtCursor.top - coordsAtStart.top) < 5
-          ) {
-            event.preventDefault();
+            // Check if we're in a position where up arrow won't move us
+            // This happens when we're on the first line of the first block
+            const coordsAtCursor = view.coordsAtPos($from.pos);
+            const coordsAtStart = view.coordsAtPos(1);
+
+            // If cursor is on the same line as the start, go to title
+            if (
+              coordsAtCursor &&
+              coordsAtStart &&
+              Math.abs(coordsAtCursor.top - coordsAtStart.top) < 5
+            ) {
+              event.preventDefault();
 
-            // Calculate character offset from start of the first line
-            // Position 1 is the start of the document, $from.pos is current cursor
-            // Since we're on the first line, the offset is simply the distance from position 1
-            const offset = $from.pos - 1;
+              // Calculate character offset from start of the first line
+              // Position 1 is the start of the document, $from.pos is current cursor
+              // Since we're on the first line, the offset is simply the distance from position 1
+              const offset = $from.pos - 1;
 
-            onArrowUpRef.current(offset);
-            return true;
+              onArrowUpRef.current(offset);
+              return true;
+            }
           }
-        }
 
-        // Handle ArrowLeft when at the very start of the document
-        if (event.key === 'ArrowLeft' && onArrowLeftRef.current) {
-          // If we're at position 1 (start of document), go back to title
-          if ($from.pos === 1) {
-            event.preventDefault();
-            onArrowLeftRef.current();
-            return true;
+          // Handle ArrowLeft when at the very start of the document
+          if (event.key === 'ArrowLeft' && onArrowLeftRef.current) {
+            // If we're at position 1 (start of document), go back to title
+            if ($from.pos === 1) {
+              event.preventDefault();
+              onArrowLeftRef.current();
+              return true;
+            }
           }
-        }
 
-        // Handle Tab for list indentation while maintaining focus
-        if (event.key === 'Tab') {
-          // Always prevent default Tab behavior to avoid focus loss
-          event.preventDefault();
-          event.stopPropagation();
+          // Handle Tab for list indentation while maintaining focus
+          if (event.key === 'Tab') {
+            // Always prevent default Tab behavior to avoid focus loss
+            event.preventDefault();
+            event.stopPropagation();
+
+            const { $from } = selection;
+
+            // Check if we're in a regular list item (bullet or ordered)
+            const isInListItem =
+              $from.node(-1)?.type.name === 'listItem' ||
+              $from.node(-2)?.type.name === 'listItem';
+
+            // Check if we're in a task item (checkbox)
+            const isInTaskItem =
+              $from.node(-1)?.type.name === 'taskItem' ||
+              $from.node(-2)?.type.name === 'taskItem';
+
+            if (isInListItem) {
+              if (event.shiftKey) {
+                // Shift+Tab: Outdent (lift) the list item
+                editor?.chain().focus().liftListItem('listItem').run();
+              } else {
+                // Tab: Indent (sink) the list item
+                editor?.chain().focus().sinkListItem('listItem').run();
+              }
+            } else if (isInTaskItem) {
+              if (event.shiftKey) {
+                // Shift+Tab: Outdent (lift) the task item
+                editor?.chain().focus().liftListItem('taskItem').run();
+              } else {
+                // Tab: Indent (sink) the task item
+                editor?.chain().focus().sinkListItem('taskItem').run();
+              }
+            }
 
-          const { $from } = selection;
+            // Ensure focus stays in the editor
+            setTimeout(() => {
+              view.focus();
+            }, 0);
 
-          // Check if we're in a regular list item (bullet or ordered)
-          const isInListItem =
-            $from.node(-1)?.type.name === 'listItem' ||
-            $from.node(-2)?.type.name === 'listItem';
-
-          // Check if we're in a task item (checkbox)
-          const isInTaskItem =
-            $from.node(-1)?.type.name === 'taskItem' ||
-            $from.node(-2)?.type.name === 'taskItem';
-
-          if (isInListItem) {
-            if (event.shiftKey) {
-              // Shift+Tab: Outdent (lift) the list item
-              editor?.chain().focus().liftListItem('listItem').run();
-            } else {
-              // Tab: Indent (sink) the list item
-              editor?.chain().focus().sinkListItem('listItem').run();
-            }
-          } else if (isInTaskItem) {
-            if (event.shiftKey) {
-              // Shift+Tab: Outdent (lift) the task item
-              editor?.chain().focus().liftListItem('taskItem').run();
-            } else {
-              // Tab: Indent (sink) the task item
-              editor?.chain().focus().sinkListItem('taskItem').run();
-            }
+            return true; // We handled the event
           }
 
-          // Ensure focus stays in the editor
-          setTimeout(() => {
-            view.focus();
-          }, 0);
-
-          return true; // We handled the event
+          return false;
+        },
+      },
+      onCreate: ({ editor }) => {
+        if (externalEditorRef) {
+          externalEditorRef.current = editor;
         }
-
-        return false;
+        onEditorReady?.(editor);
       },
-    },
-    onCreate: ({ editor }) => {
-      if (externalEditorRef) {
-        externalEditorRef.current = editor;
-      }
-      onEditorReady?.(editor);
-    },
-    onUpdate: ({ editor }) => {
-      const currentJson = editor.getJSON();
-      const normalizedContent = hasContent(currentJson) ? currentJson : null;
+      onUpdate: ({ editor }) => {
+        const currentJson = editor.getJSON();
+        const normalizedContent = hasContent(currentJson) ? currentJson : null;
 
-      if (!readOnly) {
-        onImmediateChangeRef.current?.(normalizedContent);
-      }
+        if (!readOnly) {
+          onImmediateChangeRef.current?.(normalizedContent);
+        }
 
-      // Don't call onChange when using collaboration - Yjs doc is the source of truth
-      if (!readOnly && !allowCollaboration) {
-        debouncedOnChange(currentJson);
-      }
+        // Don't call onChange when using collaboration - Yjs doc is the source of truth
+        if (!readOnly && !allowCollaboration) {
+          debouncedOnChange(currentJson);
+        }
+      },
+      // Rebuild the editor when the Yjs document binding changes, so the
+      // Collaboration extension is attached at creation time. `yjsDoc` is
+      // identity-stable (memoized in useYjsCollaboration), so a plain
+      // non-collaborative editor never recreates.
     },
-  });
-
-  // Recreate editor when collaboration provider becomes available so the
-  // CollaborationCaret extension is included. The provider is null on first
-  // render because it's created asynchronously in useEffect; this dep
-  // ensures the editor re-initializes once the provider connects.
-  const prevProviderRef = useRef(yjsProvider);
-  useEffect(() => {
-    if (!editor) return;
-    if (prevProviderRef.current === yjsProvider) return;
-    prevProviderRef.current = yjsProvider;
-
-    // Provider transitioned from null → available: recreate with extensions
-    if (yjsProvider && allowCollaboration) {
-      editor.setOptions({
-        extensions: getEditorExtensions({
-          titlePlaceholder,
-          writePlaceholder,
-          doc: yjsDoc,
-          provider: yjsProvider,
-          collaborationUser: collaborationUser,
-          onImageUpload,
-          onVideoUpload: onImageUpload,
-          getOnImageUpload: getDelegatedImageUpload,
-          getOnVideoUpload: getDelegatedImageUpload,
-          mentionTranslations,
-          renderTaskMention,
-          readOnly,
-        }),
-      });
-    }
-  }, [
-    editor,
-    yjsProvider,
-    yjsDoc,
-    allowCollaboration,
-    collaborationUser,
-    onImageUpload,
-    titlePlaceholder,
-    writePlaceholder,
-    mentionTranslations,
-    renderTaskMention,
-    readOnly,
-    getDelegatedImageUpload,
-  ]);
+    [collaborationDoc]
+  );
 
   useEffect(() => {
     if (!editor || !allowCollaboration || !yjsProvider || !collaborationUser) {
@@ -721,6 +721,9 @@ export function RichTextEditor({
   // Track whether the fixed toolbar is visible in the viewport.
   // When it is, we suppress the floating BubbleMenu to avoid duplication.
   const fixedToolbarRef = useRef<HTMLDivElement>(null);
+  // Mirrors focus-within for the toolbar handlers below. A ref (not state)
+  // because the listeners are attached once and read it at event time.
+  const hasFocusWithinRef = useRef(false);
   const [fixedToolbarVisible, setFixedToolbarVisible] = useState(true);
 
   useEffect(() => {
@@ -739,10 +742,39 @@ export function RichTextEditor({
   }, []);
 
   return (
-    <div className="group relative h-full">
+    <div
+      className="group relative h-full"
+      onBlurCapture={(event) => {
+        if (!event.currentTarget.contains(event.relatedTarget as Node | null)) {
+          hasFocusWithinRef.current = false;
+        }
+      }}
+      onFocusCapture={() => {
+        hasFocusWithinRef.current = true;
+      }}
+      onMouseDown={(event) => {
+        // While the toolbar is hidden it is `pointer-events-none`, so it never
+        // shows a hover state or a tooltip — and a press in that strip lands
+        // here instead. Put the caret in the text rather than swallowing it, so
+        // reaching for a formatting control still gets you into the description.
+        if (!revealToolbarOnFocus || hasFocusWithinRef.current || !editor) {
+          return;
+        }
+
+        if (event.target !== event.currentTarget) return;
+
+        event.preventDefault();
+        editor.commands.focus();
+      }}
+    >
       {!readOnly && (
         <FixedToolbar
           ref={fixedToolbarRef}
+          className={
+            revealToolbarOnFocus
+              ? REVEAL_TOOLBAR_ON_FOCUS_CLASS_NAME
+              : undefined
+          }
           editor={editor}
           workspaceId={workspaceId}
           onImageUpload={onImageUpload}