Merge pull request #56 from WICG/noamr-patch-3

Update patching-explainer.md

Author: noamr

patching-explainer.md

@@ -1,4 +1,4 @@
-# Patching (Partial, interleaved HTML streaming)
+# Interleaved HTML streaming (patching)
 
 ## Motivation
 Streaming of HTML existed from the early days of the web, serving an important purpose for perceieved performance when loading long articles etc.
@@ -20,62 +20,74 @@ A patch can be streamed directly into that position using JavaScript, and multip
 ## Anatomy of a patch
 
 A patch is a [stream](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API) that targets a [parent node](https://developer.mozilla.org/en-US/docs/Web/API/Node) (usually an element, but potentially a shadow root).
-It can handle strings or bytes. When it receives bytes, it decodes them using the node's document's charset. Anything other than strings or bytes is stringified.
+It can handle strings, bytes, or `TrustedHTMLString`. When it receives bytes, it decodes them using UTF8.
+Anything other than strings or bytes is stringified.
 
 When a patch is active, it is essentially a [WritableStream](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) that feeds a [fragment-mode parser](https://html.spec.whatwg.org/multipage/parsing.html#html-fragment-parsing-algorithm) with strings from that stream.
+Unlike the usual fragment parser, nodes are inserted directly into the target and not buffered into the fragment first. The fragment parser is only used to set up the parser context.
 It is similar to calling `document.write()`, scoped to an node.
 
 ## One-off patching
 
 The most atomic form of patching is opening a container node for writing, creating a `WritableStream` for it.
 This can be done with an API as such:
 ```js
-const writable = elementOrShadowRoot.patch();
+const writable = elementOrShadowRoot.streamHTML();
 byteOrTextStream.pipeTo(writable);
 ```
 
 A few details about one-off patching:
 - Trying to patch an element that is currently being patched would abort the original stream.
-- It is unclear whether patching should execute `<script>` elements found in the patch. It would potentially be an opt-in. See https://github.com/WICG/declarative-partial-updates/issues/40.
 - Replacing the contents of an existing script would only execute the script if the original contents were empty (equivalent to `innerHTML` behavior).
 
-
 To account for HTML sanitation, this API would have an "Unsafe" version and would accept a sanitizer in its option, like [`setHTML`](https://developer.mozilla.org/en-US/docs/Web/API/Element/setHTML):
 ```js
-byteOrTextStream.pipeTo(elementOrShadowRoot.patch({santizer}));
-byteOrTextStream.pipeTo(elementOrShadowRoot.patchUnsafe({santizer}));
+byteOrTextStream.pipeTo(elementOrShadowRoot.streamHTML({santizer}));
+byteOrTextStream.pipeTo(elementOrShadowRoot.streamHTMLUnsafe({santizer}));
 ```
 
-The API shape and naming is open to discussion. See https://github.com/WICG/declarative-partial-updates/issues/42.
+Also see detailed discussion at https://github.com/whatwg/html/issues/11669, will amend this explainer once that's settled.
 
 ## Interleaved patching
 
-In addition to invoking streaming using script, this proposal includes patching interleaved inside HTML content. An element such as `<script>` or `<template>` would have a special attribute that
+In addition to invoking streaming using script, this proposal includes patching interleaved inside HTML content. A `<template>` would have a special attribute that
 parses its content as raw text, finds the target element using attributes, and reroutes the raw text content to the target element:
 
 ```html
-<option patchid=gallery>Loading...</section>
+<section contentname=gallery>Loading...</section>
 
 <!-- later -->
-<template patchfor=gallery>Actual gallery content</template>
+<template contentfor=gallery>Actual gallery content</template>
 ```
 
-* Note: there is an ongoing discussion whether this should be a `<script>` element instead. See https://github.com/whatwg/html/issues/11542.
-
 A few details about interleaved patching:
-- If a target is not found, the patching element remains in the DOM.
-- The first patch for a target in the document stream replaces its content, and the next ones append. This allows interleaved streaming into the same target.
-- If the patching element is not a direct child of `<body>`, the target element has to have a common ancestor with the patching element's parent.
-- The patching element reference is tree scoped.
+- If an outlet (an element with `contentname`) is not found, the patch template remains in the DOM.
+- If the patching element is not a direct child of `<body>`, the outlet has to have a common ancestor with the patching element's parent.
+- The patch template has to be in the same tree scope as the outlet.
+- By default, the first patch in the stream replaces the entire contents of the outlet, like `replaceChildren`, and the next ones behave like `append`. 
+
+## Manipulating without replacing: `contentcommand`
+
+To allow the patch to manipulate the DOM without replacing all the children, A `contentcommand` attribute
+(values `replaceChildren`, `replaceWith`, `append`, `prepend`, `before`, `after`) can control where the contents of the patch are positioned.
+
+An empty string means the default behavior (`replaceChildren` at start, then `append`).
+
+Those behave with the same semantics as the equivalent DOM manipulation methods, and specifically as defined in https://github.com/whatwg/html/issues/11669.
+
+## Avoiding overwriting with identical content
+
+Some content might need to remain unchanged in certain conditions. For example, displaying a chat widget in all pages but the home, but not reloading it between pages.
+For this, both the outlet and the patch can have a `contentrevision` attribute. If those match, the content is not applied.
 
 ## Reflection
 
-Besides invoking a patch, there should be a few ways to reflect about the current status of patching and receive events/callbacks when a patch is underway.
+Besides applying a patch, there should be a few ways to reflect about the current status of patching and receive events/callbacks when a patch is underway.
 
 ### CSS reflection
 See https://github.com/w3c/csswg-drafts/issues/12579 and https://github.com/w3c/csswg-drafts/issues/12578.
 
-Suggesting to add a couple of pseudo-classes: `:patching` and `:patch-pending`, that reflect the patching status of an element, in addition to a pseudo-class that reflects that an element's parser state is open (regardless of patching).
+Suggesting to add a couple of pseudo-classes: `:updating` and `:pending`, that reflect the patching status of an element, in addition to a pseudo-class that reflects that an element's parser state is open (regardless of patching).
 
 ### JS status
 
@@ -90,10 +102,6 @@ Note that the HTML sanitizer works closely with the HTML parser, so it shouldn't
 
 In addition, [Trusted types](https://developer.mozilla.org/en-US/docs/Web/API/Trusted_Types_API) would need streaming support in its policy, potentially by injecting a `TransformStream` into the patch. See https://github.com/w3c/trusted-types/issues/594.
 
-## Enhancement - replace range instead of whole contents
-Some use cases for out of order streaming require replacing parts of the element's children but not other parts, e.g. adding `<meta>` tags to the `<head>` or replacing only some `<option>`s in a `<select>`.
-To achive that, the script and HTML APIs would receive an optional children range to replace, e.g. by having `patchstartafter` and `patchendbefore` attributes, and also allow similar options in the various JS APIs.
-
 ## Enhancement - JS API for interleaved patching
 In addition to invoking interleaved patching as part of the main response, allow parsing an HTML stream and extracting patches from it into an existing element:
 ```js
@@ -106,7 +114,7 @@ When calling `patchInterleaved`, discovered patches are applied to the target co
 ## Potential enhancement - patch contents from URL
 
 In addition to patching from a stream or interleaved in HTML, there are use-cases for patching by fetching a URL.
-This can be done with a `patchsrc` attribute, or by reusing the `src` attribute if we go with the `<script>` element.
+This can be done with a `patchsrc` attribute.
 
 Enabling remote fetching of patch content would act as a script in terms of CSP, with a CORS-only request, and would be sanitized with the same HTML/trusted-types restrictions as patching using script.