What's the usage for history-merge tag?

[strdr4605]

https://github.com/facebook/lexical/search?q=history-merge

When we register editor.registerUpdateListener the first event is always with tag history-merge. What does this tag mean for us?

---

Use case

https://discord.com/channels/953974421008293909/954448527268921346/1050071460904972348

We show a loader while isInCollab is false.

/**
 * @param {boolean} shouldRegisterEvent - pass isCollab option from LexicalContext
 * @returns {boolean} true when lexical editor has content from the collaboration session
 */
export const useEditorIsInCollab = (shouldRegisterEvent: boolean): boolean => {
  const [editor] = useLexicalComposerContext();
  const [isInCollab, setIsInCollab] = useState(false);

  useEffect(() => {
    if (!shouldRegisterEvent || isInCollab) {
      return undefined;
    }
    return editor.registerUpdateListener(({ tags }) => {
      if (tags.has('collaboration')) {
        setIsInCollab(true);
      }
    });
  }, [editor, isInCollab, shouldRegisterEvent]);

  return isInCollab;
};

Now the problem is when we connect for the firs time and there is no doc in Yjs server.
This time 2 events appear one with history-merge tag and one with no tags.

The question is, for both use cases should we change the hook to:

    return editor.registerUpdateListener(({ tags }) => {
      if (tags.has('collaboration') || tags.size === 0) {
        setIsInCollab(true);
      }
    });

or should we rely on 'history-merge' tag (or any update event from editor) as the indicator that user and our code can interact with editor state and the state will be propagated to collaboration session?

    return editor.registerUpdateListener(({ tags }) => {
      if (tags.has('history-merge')) {
        setIsInCollab(true);
      }
    });
// or
return editor.registerUpdateListener(() => setIsInCollab(true));

[fantactuka]

The initial idea behind history-merge was to flag HistoryPlugin that current update can be merged with the previous history entry vs creating separate entry in history undo-redo stack. Here's an example:

• Initializing editor should use history-merge so that initial state wouldn't create new entry in undo-redo stack (otherwise you'd be able to undo initial state and end up with empty editor)
• Having decorator node where its decorate output mutates node data after insertion (e.g., imagine inserting ImageNode, where its react component updates width and height values in node right after insertion).

In other words, updates marked with history-merge are non-undoable. In comparison to history-push which is opposite: flagging to history plugin to create separate entry in undo-redo stack. E.g., some sort of replacement plugin (markdown) where you'd want replacements to be undoable.

That said I do agree that the fact it's used in OnChange plugin as an indicator of initialization is confusing, but it's mainly done due to possible race conditions with plugins that might affect initial state (#2706)

For collab "readiness" you might want to rely on your provider events. If you're using y-websocket then it emits synced [true] event that you can use to know when it's ready to use