docs: document the component lifecycle and pin the attribute contract#7656
Open
AKnassa wants to merge 1 commit into
Open
docs: document the component lifecycle and pin the attribute contract#7656AKnassa wants to merge 1 commit into
AKnassa wants to merge 1 commit into
Conversation
Adds a component lifecycle guide, and grows the attribute tests into an executable specification of what actually happens during initialization: the first oldValue is undefined rather than null, and a changed callback can fire zero, one or two times depending on defaults and markup. Fixes microsoft#7516
|
Azure Pipelines: There may be pipelines that require an authorized user to comment /azp run to run. |
|
Azure Pipelines: There may be pipelines that require an authorized user to comment /azp run to run. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this does
Adds a component lifecycle guide, and turns the surprising parts of element initialization into tests that will fail if the behavior ever changes.
Why
The lifecycle docs were a bare table of callback names with no guidance about how to actually use them. Meanwhile the genuinely surprising parts of initialization were both undocumented and untested:
oldValuean@attrchanged callback receives isundefined, notnull. Everyone expectsnull, because that is what the nativeattributeChangedCallbackgives you. People writeif (oldValue !== null)guards against a value that never arrives.Nobody had written this down, and nothing pinned it, so it could drift silently.
What changed
sites/website/src/docs/3.x/advanced/component-lifecycle.md, linked from the existing lifecycle section.components/attributes.pw.spec.tsgrows from two tests into an executable specification of the initialization contract — theundefinedfirstoldValue, the zero/one/two firing counts, and the ordering of the constructor againstconnectedCallback.Two corrections
The issue body contains two claims that are not true, and writing them down would have shipped an authoritative but wrong document. Both are corrected in the guide, and both are now pinned by tests:
connectedCallbackmay fire while the constructor is still executing" — it does not. A synchronous constructor body always completes first. The real behaviors worth knowing are that asynchronous work started in a constructor settles afterconnectedCallback, and thatthis.isConnectedis alreadytrueinside the constructor when upgrading an element that is already in the page.null→ value" — they goundefined→ value.The guide uses "default value" throughout rather than "initial value", following the terminology already agreed on the issue thread.
Deliberately left open
The issue also raises a design question — should an observed property skip its changed callback on the first run? That is a maintainer's call, and this PR does not decide it.
How to see it
Run the
fast-elementtest suite; the new tests incomponents/attributes.pw.spec.tsfail if you "correct" the firstoldValuetonullor change the firing counts. Then preview the docs site: Advanced → Component lifecycle.Fixes #7516