[lexical][lexical-website] Feature: Document and export common update tags#7441
Conversation
- Create LexicalUpdateTags.ts to export common update tags - Add tag validation to in LexicalUtils.ts - Export update tags in main index.ts - Add comprehensive test suite in LexicalUpdateTags.test.ts - Create updates.md with detailed documentation The changes improve developer experience by: - Providing type-safe exports for common update tags - Adding validation to catch typos in tag names - Adding clear documentation and examples - Adding tests to verify behavior Fixes facebook#5992
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
| @@ -0,0 +1,86 @@ | |||
| # Updates | |||
|
|
|||
| Updates in Lexical are the way you can mutate the editor state. All updates are run asynchronously and batched by default. This means that if you have multiple updates back-to-back, they'll be batched together and run in a single update. This is done for performance reasons, as it means we can avoid unnecessary re-renders and DOM updates. | |||
There was a problem hiding this comment.
This isn't accurate, updates are synchronous (except in nested update scenarios which should be deprecated) but the reconciliation (DOM updates) is batched for performance
| }); | ||
| ``` | ||
|
|
||
| Note: Update tags are cleared after each update. If you need to check for tags, make sure to do it within the same update callback where they were added. |
There was a problem hiding this comment.
Typically update tags are checked in update and mutation listeners with the tags and updateTags properties in their respective payloads (as demonstrated below), it's less common to read update tags from inside the same update batch
| ```js | ||
| editor.update(() => { | ||
| // Will warn if "unknown-tag" is not a known tag | ||
| $addUpdateTag('unknown-tag', true); |
There was a problem hiding this comment.
I think a better approach here would be to recommend that people use the exported constants rather than string literals to avoid typos (e.g. HISTORIC_TAG instead of 'historic').
| /** | ||
| * A set of all known update tags for validation purposes | ||
| */ | ||
| export const KNOWN_UPDATE_TAGS = new Set([ | ||
| HISTORIC_TAG, | ||
| HISTORY_PUSH_TAG, | ||
| HISTORY_MERGE_TAG, | ||
| PASTE_TAG, | ||
| COLLABORATION_TAG, | ||
| SKIP_COLLAB_TAG, | ||
| SKIP_SCROLL_INTO_VIEW_TAG, | ||
| SKIP_DOM_SELECTION_TAG, | ||
| ]); |
There was a problem hiding this comment.
I don't think we need this
| COLLABORATION_TAG, | ||
| HISTORIC_TAG, | ||
| HISTORY_MERGE_TAG, | ||
| HISTORY_PUSH_TAG, | ||
| KNOWN_UPDATE_TAGS, | ||
| PASTE_TAG, | ||
| SKIP_COLLAB_TAG, | ||
| SKIP_DOM_SELECTION_TAG, | ||
| SKIP_SCROLL_INTO_VIEW_TAG, |
There was a problem hiding this comment.
This is the useful part for preventing typos
Updates in Lexical are synchronous operations (except in nested update scenarios which should be deprecated). Only the DOM reconciliation process is batched for performance optimization. Co-authored-by: Bob Ippolito <bob@ippoli.to>
Update the documentation to clarify that update tags are typically accessed through listener payloads (tags and updateTags properties) rather than within the same update batch. Add examples demonstrating the recommended usage patterns in update and mutation listeners. Co-authored-by: Bob Ippolito <bob@ippoli.to>
Replace string literals with exported constants (e.g. HISTORIC_TAG instead of 'historic') in all documentation examples to promote type safety and prevent typos. Add imports from lexical package and update guidance to recommend using constants for both built-in and custom tags. Co-authored-by: Bob Ippolito <bob@ippoli.to>
… constants - Remove KNOWN_UPDATE_TAGS Set and runtime validation from LexicalUpdateTags.ts - Simplify by removing validateTag parameter from LexicalUtils.ts - Update documentation in updates.md to emphasize using exported constants - Remove validation-related exports from index.ts - Update tests to use exported tag constants instead of validation This change moves away from runtime validation of update tags in favor of TypeScript's type system and exported constants, providing better type safety and developer experience. Co-authored-by: Bob Ippolito <bob@ippoli.to>
Restore the errorOnReadOnly() check that was accidentally removed while removing the runtime tag validation. This check is important to prevent update tag modifications in read-only mode.
|
Thanks for the thorough review @etrepum! I apologize for the confusion in the documentation. I had misunderstood how updates worked, incorrectly assuming they were asynchronous. Thanks for the clarification! I've addressed all your feedback:
Please take another look when you have a chance. Let me know if anything needs further adjustment! |
etrepum
left a comment
There was a problem hiding this comment.
I think this looks great other than the missing sidebar reference. Perhaps we should create a follow-up issue to have the existing code use these new constants to match the recommendation from the new docs?
| @@ -0,0 +1,132 @@ | |||
| # Updates | |||
There was a problem hiding this comment.
This new file needs to be referenced in packages/lexical-website/sidebars.js so you can find it in the documentation. I think this is also why the preview isn't rendered with a sidebar
existing page in that section:
https://lexical-git-fork-bgwebagency-feat-5992-docu-7750e0-fbopensource.vercel.app/docs/concepts/nodes
Add 'concepts/updates' to the Concepts section in sidebars.js to make the updates documentation discoverable in the navigation. Co-authored-by: Bob Ippolito <bob@ippoli.to>
Thanks for the review! I've fixed the missing sidebar reference and created a follow-up issue to migrate the existing code to use the new constants at #7446. Let me know if there's anything else you'd like me to change or improve in this PR! |
… tags (#7441) Co-authored-by: Bob Ippolito <bob@ippoli.to>
Description
Current behavior:
Changes being added:
LexicalUpdateTags.tsto export common update tags as constants$addUpdateTagto catch typosupdates.mdabout:Closes #5992
Test plan
Before
After
Added comprehensive test suite in
LexicalUpdateTags.test.tsthat verifies:KNOWN_UPDATE_TAGS$addUpdateTagand$hasUpdateTagfunctionalityAll tests are passing and validate the documented behavior.