Feedback

[jakearchibald]

Happy to break any of this out into specific issues if it would benefit from it. I've only really looked at part 1.

High level design feedback

Imagining a site like the following:

Page type	Side nav	Header	Footer	Chat widget	Content
Home page	-	A	A	-	Unique
Docs page (many)	A	B	A	A	Unique
Blog post (many)	B	B	A	A	Unique

What I'm trying to express here is that the home page does not have a side nav. All docs pages have the same side nav. All blog posts have the same side nav, but it's different to docs pages. All pages have the same footer etc etc.

Based on my understanding of the proposal, here are some observations:

• Unless developers are prepared to create specific patches from each page type to every other page type (which doesn't seem to be the intent of this proposal), each patch payload is going to contain the full destination page content, which may include content that's already being displayed.
• The home page will need to have elements ready to house the side nav and chat widget, even through it doesn't have them. Otherwise, the side nav will be missing when patching from home to other pages. I guess the easiest thing to do would be to create a single page shell for the whole site which contains all possible content containers.
• The home page will need to have empty <template patchfor>s to clear out the side nav and chat widget containers, else if you go from home to docs to home, the home page would have an unwanted side nav.
• Given that the footer is consistent across all pages, it wouldn't need to be expressed in a <template patchfor>, and therefore wouldn't update across same-doc navigations. Although this would need to be refactored if a single page has a different footer, or doesn't have a footer.
• When navigating between docs pages, the side nav would be fully replaced, because all pages would have a <template patchfor=nav> to handle navigations between the page types. This would be frustrating if the nav contained state, eg <details> elements that the user had interacted with.
• The same problem exists with the chat widget - it will be reinitiated between all navigations because it'd be replaced with a fresh <chat-widget> or whatever.

The benefit of modern frameworks is the developer can describe the destination state (eg in JSX), and the framework determines some DOM operations to get the current state to the new state, ideally preserving things which are common between both states. Both states may have a <ChatWidget>, but as long as a framework-specific set of rules determine it's the 'same' chat widget, it isn't reinitialised. It feels like this proposal doesn't have this feature.

Other questions/notes:

• What's the best practice if one page requires additional script. Eg, when moving from home to docs, how/when is the code for the chat widget loaded? Would this be a <script type=module src> in the <template patchfor>?
• How are overlapping patch* calls handled? As in, what happens with document.patch(response); document.patch(otherResponse);
• Why does the API need a Response and not just a text/byte stream?
• When handling page titles, I assume you'd have to do something like <title id="title">My page title</title><template patchfor="title">My page title</template>, because if you omit the content from title element, a bunch of simple parsers are going to miss it.
• There are a bunch of differences between regular document parsing, and innerHTML parsing, especially around scripts. Which model is used here?
• What happens if <template patchfor="foo"> contains a <template patchfor="foo">?
• The content of <template> flipping from success content to error content depending on the presence of patchsrc seems a bit weird.
• The behaviour of element.patchSelf seems self-contained, individually useful, and complex enough to treat as a first-to-ship part of this.

[noamr]

Happy to break any of this out into specific issues if it would benefit from it. I've only really looked at part 1.

Thanks for this initial feedback! I was waiting for it :)

High level design feedback

Imagining a site like the following:

Page type Side nav Header Footer Chat widget Content
Home page - A A - Unique
Docs page (many) A B A A Unique
Blog post (many) B B A A Unique
What I'm trying to express here is that the home page does not have a side nav. All docs pages have the same side nav. All blog posts have the same side nav, but it's different to docs pages. All pages have the same footer etc etc.

Based on my understanding of the proposal, here are some observations:

• Unless developers are prepared to create specific patches from each page type to every other page type (which doesn't seem to be the intent of this proposal), each patch payload is going to contain the full destination page content, which may include content that's already being displayed.

Or at least the parts of the content that are dynamic in any way.

• The home page will need to have elements ready to house the side nav and chat widget, even through it doesn't have them. Otherwise, the side nav will be missing when patching from home to other pages. I guess the easiest thing to do would be to create a single page shell for the whole site which contains all possible content containers.

Yea, I think the best practice here would be to keep the shell stable, changing its state using CSS (display?) and using patches to change the actual content.

• The home page will need to have empty <template patchfor>s to clear out the side nav and chat widget containers, else if you go from home to docs to home, the home page would have an unwanted side nav.
• Given that the footer is consistent across all pages, it wouldn't need to be expressed in a <template patchfor>, and therefore wouldn't update across same-doc navigations. Although this would need to be refactored if a single page has a different footer, or doesn't have a footer.
• When navigating between docs pages, the side nav would be fully replaced, because all pages would have a <template patchfor=nav> to handle navigations between the page types. This would be frustrating if the nav contained state, eg <details> elements that the user had interacted with.

• The same problem exists with the chat widget - it will be reinitiated between all navigations because it'd be replaced with a fresh <chat-widget> or whatever.

Probably replace only part of the nav or chat widgets in this case?
Also I think in the future we can introduce something that merges deeper based on IDs and moveBefore.

The benefit of modern frameworks is the developer can describe the destination state (eg in JSX), and the framework determines some DOM operations to get the current state to the new state, ideally preserving things which are common between both states. Both states may have a <ChatWidget>, but as long as a framework-specific set of rules determine it's the 'same' chat widget, it isn't reinitialised. It feels like this proposal doesn't have this feature.

Correct. Patches don't try to replace frameworks opinions about how to perform a model-to-view transformation. It is more of a lower level mechanism that can be used for delivery. For example, React SSR, SvelteKit or Nuxt can use this for their initial out-of-order streaming, and it can be used with all kinds of solutions like having React in a (service/dedicated) worker or on the server.

Other questions/notes:

• What's the best practice if one page requires additional script. Eg, when moving from home to docs, how/when is the code for the chat widget loaded? Would this be a <script type=module src> in the <template patchfor>?

Currently, no. Patches don't execute scripts they discover. The best (and only) practice should be to manage scripts separately from patches. A main reason for this is that scripts are not "unloadable".

• How are overlapping patch* calls handled? As in, what happens with document.patch(response); document.patch(otherResponse);

Currently, the first one is aborted and its promises are rejected.

• Why does the API need a Response and not just a text/byte stream?

It doesn't.... It only uses text/byte streams. I might have left something over in the explainer.

• When handling page titles, I assume you'd have to do something like <title id="title">My page title</title><template patchfor="title">My page title</template>, because if you omit the content from title element, a bunch of simple parsers are going to miss it.

Sure

• There are a bunch of differences between regular document parsing, and innerHTML parsing, especially around scripts. Which model is used here?

The model here is as follows when a <template patchfor> is discovered:

• We continue parsing the contents of the template in text mode, as if it was a <script> or <xmp> etc.
• We create a new fragment-mode parser, similar to what's used in innerHTML, with the target of the patch as the context.
• We feed the raw text from the original parser into this fragment parser.
• Unlike innerHTML, which first parses into a fragment and then inserts the fragment into the target, the parser streams the content directly into the target. This streaming is not available if "trusted types" are present as they currently only operate on full HTML strings. This is perhaps the main/only "core" change to the parser.
• Parser-invoked scripting is disabled for this fragment-mode parser.
• The template itself is not attached to the document (similar to how shadowrootmode works).

• What happens if <template patchfor="foo"> contains a <template patchfor="foo">?

Good question, not defined yet. most likely ignored.

• The content of <template> flipping from success content to error content depending on the presence of patchsrc seems a bit weird.
• The behaviour of element.patchSelf seems self-contained, individually useful, and complex enough to treat as a first-to-ship part of this.

Agreed! Though we wanted to have a clear vision of where this is going when designing the API.
It can probably be called patch() rather than patchSelf().

[jakearchibald]

• Unless developers are prepared to create specific patches from each page type to every other page type (which doesn't seem to be the intent of this proposal), each patch payload is going to contain the full destination page content, which may include content that's already being displayed.

Or at least the parts of the content that are dynamic in any way.

Only if the patch resources are different to the full page navigation resources. I assumed the design intends for these to be the same resource in most cases?

• The same problem exists with the chat widget - it will be reinitiated between all navigations because it'd be replaced with a fresh <chat-widget> or whatever.

Probably replace only part of the nav or chat widgets in this case?

How would you do this? Given that the chat widget & nav is absent on the home page. In some cases it needs to go from nothing to the whole thing.

The benefit of modern frameworks is the developer can describe the destination state (eg in JSX), and the framework determines some DOM operations to get the current state to the new state, ideally preserving things which are common between both states. Both states may have a <ChatWidget>, but as long as a framework-specific set of rules determine it's the 'same' chat widget, it isn't reinitialised. It feels like this proposal doesn't have this feature.

Correct. Patches don't try to replace frameworks opinions about how to perform a model-to-view transformation. It is more of a lower level mechanism that can be used for delivery. For example, React SSR, SvelteKit or Nuxt can use this for their initial out-of-order streaming, and it can be used with all kinds of solutions like having React in a (service/dedicated) worker or on the server.

That's fair. It's a good solution to that problem. I'm less sure about it being a solution for a manually coded blog. If that's an intended use-case, it would be interesting to create a scrappy polyfill, then take a decent web engineer unfamiliar with this proposal, and see how they'd build something like the home/docs/blog example with it.

Other questions/notes:

• What's the best practice if one page requires additional script. Eg, when moving from home to docs, how/when is the code for the chat widget loaded? Would this be a <script type=module src> in the <template patchfor>?

Currently, no. Patches don't execute scripts they discover. The best (and only) practice should be to manage scripts separately from patches. A main reason for this is that scripts are not "unloadable".

As an author it's pretty frustrating that the parser & innerHTML parse content differently. At least in this case it would be consistent. But missing script seems like an issue. Eg my blog posts have a lot of scripts for creating interactive examples. Right now I can put them right after the element I want to 'enhance', but in this model I'd need to do something more complicated, and add more code to handle/avoid layout shifts.

• How are overlapping patch* calls handled? As in, what happens with document.patch(response); document.patch(otherResponse);

Currently, the first one is aborted and its promises are rejected.

Seems reasonable.

• Why does the API need a Response and not just a text/byte stream?

It doesn't.... It only uses text/byte streams. I might have left something over in the explainer.

Oh, all the examples in the readme are passing Responses to patch.

• What happens if <template patchfor="foo"> contains a <template patchfor="foo">?

Good question, not defined yet. most likely ignored.

That seems inconsistent with the document.patch answer above. But yeah, the alternative seems messy.

• The content of <template> flipping from success content to error content depending on the presence of patchsrc seems a bit weird.
• The behaviour of element.patchSelf seems self-contained, individually useful, and complex enough to treat as a first-to-ship part of this.

Agreed! Though we wanted to have a clear vision of where this is going when designing the API. It can probably be called patch() rather than patchSelf().

It seems odd to have both element.patch and document.patch that behave so differently. It could just be element.createWritable(). Anyway, bikeshedding.

[noamr]

• What's the best practice if one page requires additional script. Eg, when moving from home to docs, how/when is the code for the chat widget loaded? Would this be a <script type=module src> in the <template patchfor>?

Currently, no. Patches don't execute scripts they discover. The best (and only) practice should be to manage scripts separately from patches. A main reason for this is that scripts are not "unloadable".

As an author it's pretty frustrating that the parser & innerHTML parse content differently. At least in this case it would be consistent. But missing script seems like an issue. Eg my blog posts have a lot of scripts for creating interactive examples. Right now I can put them right after the element I want to 'enhance', but in this model I'd need to do something more complicated, and add more code to handle/avoid layout shifts.

Probably put the script element directly after the <template patchfor> element in the simple case? Or call patch() and execute the script when it's done?

But we can flesh this out further. Disabling scripts seemed like the safest start.

• The content of <template> flipping from success content to error content depending on the presence of patchsrc seems a bit weird.

Yea, good point. This needs a bit more fleshing out.

It seems odd to have both element.patch and document.patch that behave so differently. It could just be element.createWritable(). Anyway, bikeshedding.

They shouldn't behave differently (sounds like my examples need a bit of a cleanup following the evolution of the API since it was first published).
There should be a patch and patchInterleaved or patchSelf and patchAll or some such.

[jakearchibald]

From what I understood, document.patch takes the response/stream and does nothing unless it contains some <template patchfor>s that it can work with. Whereas element.patch (patchSelf in the README) will clear the element's content and stream the HTML from the response into the element.

[noamr]

From what I understood, document.patch takes the response/stream and does nothing unless it contains some <template patchfor>s that it can work with. Whereas element.patch (patchSelf in the README) will clear the element's content and stream the HTML from the response into the element.

This was changed, to be parentNode.patchSelf and parentNode.patchAll. They both work on any parent node (element/document/shadow-root), one replacing all the children and one only applying <template patchfor> elements found in the stream.

[noamr]

btw I think in your main example, I wouldn't bother with an SPA navigation between the home and the other pages.
Have a separate document for the home, and then a separate document for the "app" containing the chat widget and nav etc. The other option would be to have an empty placeholder for the chat widget or nav and patch it to be empty when going home.

[jakearchibald]

The other option would be to have an empty placeholder for the chat widget or nav and patch it to be empty when going home.

But then the other pages will have to patch it to be a chat widget. And therefore going between those pages will patch the chat widget to be a new chat widget.

[noamr]

The other option would be to have an empty placeholder for the chat widget or nav and patch it to be empty when going home.

But then the other pages will have to patch it to be a chat widget. And therefore going between those pages will patch the chat widget to be a new chat widget.

True. I think that for things like having a chat widget that retains state and isn't there in all pages, the current patching mechanism doesn't suffice and we would need to extend it (in the future) with some sort of "merge" or "preserving" semantics, that e.g. preserves existing elements if they have the same ID+tagName and replaces their attributes/content. This would need work but doesn't have to be there from the get go IMO.

[jakearchibald]

At a high level, I'm worried this design doesn't work for anyone. There are significant challenges and gotchas in making it work for the simple three-page-types example I gave. I couldn't use it for my blog (which is basically one page type) due to how script is handled.

When I sketched out ideas for a pipe-html-into-an-element API in the past, I wanted to (as much as possible) minimise the differences between the page-loading parser and the piping-parser. I still think that's the right thing to do to allow people to enhance their MPAs into SPAs.

[jakearchibald]

Also, if this moves forward, I wonder if there's a more progressive-enhancement-friendly design. In the current design, <div id="blah"></div><template patchfor="blah">…content…</template> results in no content in current browsers. I guess you'd have to duplicate the content between the div and the template in order to be backwards compatible?

A pattern like:

<div id="blah" patchfor="blah">
  …content…
</div>

…might work? As in, the document parser would create & append the div, then 'patch' the contents into the div. Whereas the document.patch parser would just pipe the div content into an existing [id=blah].

Browsers without this feature would just render the content.

This also 'solves' the title issue, as you'd just do <title id="title" patchfor="title">Page title</title>. You could also say that patchfor without a value takes its value from the current element's ID, so it'd just be <title id="title" patchfor>Page title</title>.

[noamr]

Also, if this moves forward, I wonder if there's a more progressive-enhancement-friendly design. In the current design, <div id="blah"></div><template patchfor="blah">…content…</template> results in no content in current browsers. I guess you'd have to duplicate the content between the div and the template in order to be backwards compatible?

Or use a polyfill.

A pattern like:

…content…

…might work? As in, the document parser would create & append the div, then 'patch' the contents into the div. Whereas the `document.patch` parser would just pipe the div content into an existing `[id=blah]`.

Browsers without this feature would just render the content.

This also 'solves' the title issue, as you'd just do <title id="title" patchfor="title">Page title</title>. You could also say that patchfor without a value takes its value from the current element's ID, so it'd just be <title id="title" patchfor>Page title</title>.

Interesting. So having patchfor as an attribute that can go on anything and not just templates? I can get behind that.

At a high level, I'm worried this design doesn't work for anyone. There are significant challenges and gotchas in making it work for the simple three-page-types example I gave. I couldn't use it for my blog (which is basically one page type) due to how script is handled.

By anyone you mean everyone?
I think the "gotchas" are in elements that need to both be patched and preserve state. For these, we would need to introduce merge semantics at some point. We can consider doing that from the get go.

When I sketched out ideas for a pipe-html-into-an-element API in the past, I wanted to (as much as possible) minimise the differences between the page-loading parser and the piping-parser. I still think that's the right thing to do to allow people to enhance their MPAs into SPAs.

The main difference is not executing scripts.
The problem with executing scripts is that if you consider history navigations you execute the same script over and over as scripts are not unloadable. How would you address this issue?

[jakearchibald]

By anyone you mean everyone?

Unfortunately I meant 'anyone'. I haven't found a case where this system works without significant refactor, gotchas, and headache. I'm happy to be wrong here. It might be worth getting someone like Bramus to try and use the proposed system, and see where he struggles.

The problem with executing scripts is that if you consider history navigations you execute the same script over and over as scripts are not unloadable. How would you address this issue?

If I have a script in content (and therefore in a patchfor), I'd expect it to run over and over. If I only wanted it to run once, I could either do that in code (eg set a global var), or use <script type="module" src>.

[jakearchibald]

For context, see this post and its source.

I'd expect all these scripts to execute when they're added to the document, and I'd expect document.currentScript to do the right thing (maybe there are rough edges there).

In this other post, the demos are powered by a custom element. The script which contains the definition is included as a <script type="module" src> in the head. I'd need to move this into the patchfor for the content, but that seems reasonable. There's no repeated execution thanks to type="module".