Skip to content

[lexical][lexical-website] Documentation Update: SKIP_DOM_SELECTION_TAG is ignored during initial editor state#8636

Open
spokodev wants to merge 1 commit into
facebook:mainfrom
spokodev:fix/skip-dom-selection-initial-state-docs
Open

[lexical][lexical-website] Documentation Update: SKIP_DOM_SELECTION_TAG is ignored during initial editor state#8636
spokodev wants to merge 1 commit into
facebook:mainfrom
spokodev:fix/skip-dom-selection-initial-state-docs

Conversation

@spokodev

@spokodev spokodev commented Jun 4, 2026 •
edited
Loading

Copy link
Copy Markdown

Description

SKIP_DOM_SELECTION_TAG is intentionally a no-op during the initial editor state (whether passed via createEditor's editorState option or $initialEditorState on the root extension): tags only propagate through user-driven editor.update() calls, and the initial mount runs outside of any such update. That limitation was undocumented, which surfaced as confusion in #8610.

This PR documents it in two places, with no runtime behaviour changes:

  • JSDoc next to the SKIP_DOM_SELECTION_TAG constant in packages/lexical/src/LexicalUpdateTags.ts
  • The Focus section of the Selection page on the website (packages/lexical-website/docs/concepts/selection.md), including the $setSelection(null) workaround for suppressing the initial scroll/focus

Closes #8610

Test plan

Before

  • SKIP_DOM_SELECTION_TAG JSDoc gave no hint that the initial editor state ignores the tag.
  • The website's Focus section described the tag without the initial-mount caveat.

After

  • JSDoc states the tag is ignored during initial editor state setup and points to the workaround.
  • Website Focus section explains the limitation and shows the $setSelection(null) pattern.

Docs-only change — pnpm build is clean across the affected packages, and I read through the rendered JSDoc and the rebuilt website page.
@spokodev
Document that SKIP_DOM_SELECTION_TAG is ignored during initial editor…
a9d3971 
… state

The tag is applied through editor.update() and tags propagate via the
in-progress update, but the initial editor state setup runs outside of
any user-driven update cycle, so the SKIP_DOM_SELECTION_TAG check never
sees the tag and the DOM selection is set on first mount.

Document the workaround (`$setSelection(null)` inside the initial state
setup function) both in the JSDoc next to SKIP_DOM_SELECTION_TAG and at
the Focus section of the website's Selection page, where the tag is
already introduced. Per @etrepum's suggestion in the issue thread.

Refs facebook#8610
@meta-cla

meta-cla Bot commented Jun 4, 2026

Copy link
Copy Markdown

Hi @spokodev!

Thank you for your pull request and welcome to our community.

Action Required

In order to merge any pull request (code, docs, etc.), we require contributors to sign our Contributor License Agreement, and we don't seem to have one on file for you.

Process

In order for us to review and merge your suggested changes, please sign at https://code.facebook.com/cla. If you are contributing on behalf of someone else (eg your employer), the individual CLA may not be sufficient and your employer may need to sign the corporate CLA.

Once the CLA is signed, our tooling will perform checks and validations. Afterwards, the pull request will be tagged with CLA signed. The tagging process may take up to 1 hour after signing. Please give it that time before contacting us about it.

If you have received this in error or have any questions, please contact us at cla@meta.com. Thanks!
@vercel

vercel Bot commented Jun 4, 2026 •
edited
Loading

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
lexical Ready Ready Preview, Comment Jun 4, 2026 2:11pm
lexical-playground Ready Ready Preview, Comment Jun 4, 2026 2:11pm

Request Review
@meta-cla meta-cla Bot added the CLA Signed This label is managed by the Facebook bot. Authors need to sign the CLA before a PR can be reviewed. label Jun 4, 2026
@meta-cla

meta-cla Bot commented Jun 4, 2026

Copy link
Copy Markdown

Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Meta Open Source project. Thanks!
@etrepum

etrepum commented Jun 11, 2026

Copy link
Copy Markdown
Collaborator

Title and description doesn't match the pull request template
@spokodev spokodev changed the title Document that SKIP_DOM_SELECTION_TAG is ignored during initial editor state Jun 11, 2026
@spokodev spokodev marked this pull request as ready for review June 17, 2026 11:57
@spokodev

spokodev commented Jun 17, 2026

Copy link
Copy Markdown
Author

Thanks for the pointer, @etrepum — reworked the description to follow the template (Description → Closes #8610 → Test plan with Before/After) and marked the PR ready for review. The title already uses the [affected-packages] Documentation Update: … form.
potatowagon
potatowagon reviewed Jun 17, 2026
View reviewed changes

@potatowagon potatowagon left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed by Navi (Tater Thoughts Bobblehead) on behalf of @potatowagon.

LGTM ✅

What I checked:

  • Documentation accuracy: The note correctly documents real behavior — SKIP_DOM_SELECTION_TAG is indeed ignored during initial editor state setup because the initial reconcile path bypasses the tag-checking logic.
  • Workaround correctness: $setSelection(null) inside the initial state function is the correct approach — it prevents selection from being set, so there is nothing to scroll to or focus.
  • Code example: Well-formed, uses proper editor.update() pattern inside the editorState callback.
  • JSDoc comment update in LexicalUpdateTags.ts: Accurately documents the limitation and the recommended workaround.
  • No runtime code changes — purely docs + JSDoc, zero risk of regression.
  • www compat: No impact — no API changes, no removed/renamed exports.

Assessment: Pure documentation improvement that saves developers from a common gotcha. The SKIP_DOM_SELECTION_TAG limitation on initial state is a known sharp edge (I can see why users would expect it to work), and documenting both the limitation AND the workaround is the right call. CI all green (unit 22.x+24.x, browser, integrity, e2e canary chromium, CLA, Vercel). Ready to approve.
@levensta levensta mentioned this pull request Jun 24, 2026
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

CLA Signed This label is managed by the Facebook bot. Authors need to sign the CLA before a PR can be reviewed.

3 participants

@spokodev @etrepum @potatowagon