Repository navigation
[css-view-transitions-1] domUpdated isn't the right term #8144
Description
Apart from a couple of events that are prefixed with DOM*, we don't really expose DOM as a term to web content and I think we should keep it that way.
Either keep this somewhat more abstract or go with nodeTreeChanged or some such.
Activity
jakearchibald commentedon Nov 29, 2022
The developer provides a callback that updates the state of the page in some way that forms the 'after' state of a transition.
domUpdatedrelates to the success/failure of that update.It doesn't need to be a tree change. It can be a class name changing, an inline style, a CSSOM change etc etc.
Some other name ideas:
stateUpdatedviewUpdatedupdateHandledchangeHandledI'll try and think up more options.
Although, I think
domUpdatedworks pretty well. The developer updates the DOM, therefore the DOM is updated.annevk commentedon Nov 30, 2022
It sounds like you and I have a different understanding of what DOM means. If the overall feature is called view transitions, viewUpdated makes some sense to me.
[-]domUpdated isn't the right term[/-][+][css-view-transitions-1] domUpdated isn't the right term[/+]jakearchibald commentedon Nov 30, 2022
The problem with
viewUpdated, is… what the user sees isn't updated yet.Here's a diagram I've been working on to go in the spec that tries to explain the phases of a view transition.
out.mp4
The three promises map to those phases:
domUpdated- once "developer updates DOM"ready- once "transition layer populated"finished- once "transition layer cleared"I had assumed that a change to styling counted as a DOM change, as text content of a style would have changed, or a rule in CSSOM would have changed etc etc. My assumption is that CSSOM was a subset of the DOM, since it's properties that hang off nodes that are part of the document.
viewUpdatedseems wrong, because the user may not see it yet. It's the document model that's updated.annevk commentedon Nov 30, 2022
How about something like
stateChanged?I think there's quite distinct ideas about the scope of the term DOM and as such I'd rather also not have it as a term-of-art in APIs or even prose.
jakearchibald commentedon Nov 30, 2022
I thought you were saying 'state' was problematic in #8143?
jakearchibald commentedon Nov 30, 2022
Ah, ok, I think I understand what you mean in #8143 now.
stateChangedis vague, and clashes with state updates in frameworks (which happen before DOM updates). I'll have a think.jakearchibald commentedon Dec 1, 2022
@vmpstr suggested the name should reflect that it's linked to the callback passed to
startViewTransition.So:
callbackDoneupdateCallbackDoneI prefer the latter, in case we add other callbacks in future.
tbondwilkinson commentedon Dec 5, 2022
From an API perspective:
There's nothing about the API shape right now that implies a name for the callback parameter passed to
startViewTransition. The spec does call it aUpdateDOMCallback, but that doesn't appear in the API. If Anne has an issue with DOM appearing in the API, perhaps the spec should also be changed to a more neutral name?You could consider using "render," as I believe that's a term unrelated to DOM but reflects that the operation is to change the rendered content.
renderViewCallback, perhaps.jakearchibald commentedon Dec 5, 2022
There might in future, if the API changes to a dictionary to allow for options, and perhaps other callbacks.
Yep, it will be, to reflect the name we decide here. But the developer-facing name is more important.
See the video in #8144 (comment). I don't think "render" is a good choice because the change is not rendered visually.
tbondwilkinson commentedon Dec 5, 2022
updateCallbackDonejust feels so generic. :( Is there really no verb commonly used for the modification of HTML elements on the page?annevk commentedon Dec 5, 2022
Mutations (see
MutationObserver), but those exclude changes to style sheets.jakearchibald commentedon Dec 5, 2022
The nice thing about
updateCallbackDoneis it's clear it's related to whatever you did in the callback.If you mutate the DOM, change a style, and then (for whatever reason) await something unrelated in the callback, a name like
domUpdated,viewUpdated,mutatedetc etc might suggest that the promise is related to a subset of things you did in the callback, but it isn't.khushalsagar commentedon Jan 5, 2023
I'm good with updateCallbackDone as well. This promise is tightly coupled with the execution of the developer provided callback in startViewTransition so the name makes that obvious.
1 remaining item
khushalsagar commentedon Jan 6, 2023
Posting a summary of all the options brought up on the issue so folks can quickly skim through and pick the one they most agree with.
Option 1 builds on
domUpdated: "Updated" is the verb to indicate state has changed and "dom" is the noun to refer to this state.For the prefix we want something which encompasses any update to the DOM (node state, tree state, computed style, loading state, canvas update etc). The options are:
stateUpdated: state can be a bit generic.viewUpdated: We landed on "view" transitions with the idea that the transition is between the user visible "views" of the page. Since the callback doesn't change visuals for the user, view can be ambiguous.renderingUpdated: Similar to above, rendering hasn't been updated when this promise resolves.nodeTreeUpdated: Doesn't encompass all the ways in which the page state can change.targetUpdated: Follows the nomenclature of source and target views to refer to new page state as "target". Not great since the spec has settled on old and new views for this.There are a few other options for the suffix too:
domReady: We already have a "ready" promise to indicate the pseudo-DOM has been generated.domChangeddomMutateddomUpdateHandled: Don't see the advantage of this vs domUpdated, its just longer.domChangeHandled: Same as above.Option 2 is to tie the promise to the callback passed by the developer in startViewTransition. The callback is currently named
UpdateDOMCallbackand the promise willupdateDOMCallbackDoneorupdateDOMCallbackHandled. So it seems like we still need a noun + verb combination as the options above.A related options is to skip the noun. So you'd just have
updateCallback(see verb options for update above) and the promise will be callback name + "done/handled", likeupdateCallbackDoneorupdateCallbackHandled.Please add in case I missed something.
My take is that the pattern for nounVerbCallback for the callback and nounVerb for the promise is good. And
updateis fine for the verb. The discussion started with avoiding the use of "dom" as the noun. And from the options above, I'd go with state. It's generic but intentionally so since we want to encompass a broad type of updates. So,updateStateCallbackandstateUpdated.If we can't agree on a noun then next best option is to drop it and go with
updateCallbackandupdateCallbackDone.khushalsagar commentedon Jan 10, 2023
Conclusion from a discussion just now, we've got 2 proposals that we'd like the group's feedback on:
updateStateCallbackfor the callback andstateUpdatedfor the corresponding promise.updateCallbackfor the callback andupdateCallbackDonefor the corresponding promise.No strong preference on either of the options above.
ydaniv commentedon Jan 10, 2023
I'd prefer 2.
To me "state" sounds very vague. I do however understand that the callback argument is the "update callback".
css-meeting-bot commentedon Jan 18, 2023
The CSS Working Group just discussed
[css-view-transitions-1] domUpdated isn't the right term, and agreed to the following:RESOLVED: adopt suggested change to rename to `updateCallbackDoneThe full IRC log of that discussion
<JakeA> View transitions wraps a state change - we attempt generate a transition from that state change<JakeA> The developer provides a callback where they do that change, usually by modifying the DOM in some way. It can be async.
<JakeA> Sometimes you just want to know when the state change is complete
<JakeA> We provided a promise for that,`domUpdated`, which fulfills when the promise returned by the callback fulfills
<JakeA> Anne said "we don't really expose DOM as a term to web content", so the name is bad
<JakeA> So, we need a new name
<JakeA> Couple of options: `stateUpdated` - avoids using DOM, but a bit vague, might be confusing due to frameworks use of 'state'.
<JakeA> Vlad suggested that, since the promise resolves along with the callback, we name it `updateCallbackDone`.
<JakeA> I like that, since if the developer does stuff other than DOM updating in the callback, the promise name still makes sense.
<JakeA> Anne is happy with that.
<bramus> JakeA: I can take up this one. posted a bunch of messages above
<TabAtkins> +1 to suggested name change, it's clear and tied directly to what's actually happening, and I think will make sense for an author.
<masonf> `DOMContentLoaded` ?
<bramus> JakeA: I guess we are saying: any objections?
<bramus> astearns: not knowing what the callback is named that seems vague. what is it?
<bramus> JakeA: it does not have an developer visible name. authors pass it in as argument
<bramus> JakeA: `updateCallback` and then `updateCallbackDone`
<florian> have not followed deeply, but seems reasonable
<bramus> TabAtkins: I like it. makes sense and matches spec language
<bramus> bramus: +1
<bramus> astearns: proposed resolution: adopt suggested change to rename to `updateCallbackDone `
<bramus> RESOLVED: adopt suggested change to rename to `updateCallbackDone
VT: Rename domUpdated to updateCallbackDone
VT: Rename domUpdated to updateCallbackDone
VT: Rename domUpdated to updateCallbackDone
VT: Rename domUpdated to updateCallbackDone
VT: Rename domUpdated to updateCallbackDone
Bug 1811097 [wpt PR 38045] - VT: Rename domUpdated to updateCallbackD…
Bug 1811097 [wpt PR 38045] - VT: Rename domUpdated to updateCallbackD…