From 8b6f5938dce2b2f46c9fa3b0507d0912d5dd81dd Mon Sep 17 00:00:00 2001
From: Tom Wilkinson <twilkinson@google.com>
Date: Wed, 26 Jul 2023 17:44:49 -0500
Subject: [PATCH] Add more syntax for declarative DOM

---
 proposals/DOM-Parts-Declarative-Template.md |  73 ------
 proposals/DOM-Parts-Declarative.md          | 128 +++++++++++
 proposals/DOM-Parts-Imperative.md           | 239 +++++++++++---------
 proposals/DOM-Parts.md                      |   2 +-
 4 files changed, 262 insertions(+), 180 deletions(-)
 delete mode 100644 proposals/DOM-Parts-Declarative-Template.md
 create mode 100644 proposals/DOM-Parts-Declarative.md

diff --git a/proposals/DOM-Parts-Declarative-Template.md b/proposals/DOM-Parts-Declarative-Template.md
deleted file mode 100644
index 2d6121f..0000000
--- a/proposals/DOM-Parts-Declarative-Template.md
+++ /dev/null
@@ -1,73 +0,0 @@
-# DOM Parts Declarative Template API
-
-This proposal covers the declarative API for creating a DOM part within a
-`<template>` element.
-
-## Proposal
-
-Double curly braces `{{}}` provide markers for DOM parts.
-
-In the most basic level, this proposal can produce the three DOM parts:
-`NodePart`, `AttributePart`, `ChildNodePart`.
-
-### Basic Examples
-
-Suppose we had the following template in some HTML extension template languages
-where `{name}` and `{email}` indicated locations of dynamic data insertion:
-
-```html
-<section>
-  <h1 id="name">{name}</h1>
-  Email: <a id="link" href="mailto:{email}">{email}</a>
-</section>
-```
-
-And the application has produce a template with the following content:
-
-```html
-<template>
-  <section>
-    <h1 id="name">{{}}</h1>
-    Email: <a id="link" href="{{}}">{{}}</a>
-  </section>
-</template>
-```
-
-This will create a `ChildNodePart` attached to `<h1>` with no content, a
-`NodePart` attached to `<a>`, and an `AttributePart` connected to `href`.
-
-A framework could fetch these parts use either a
-[`DocumentPart`](./DOM-Parts-Imperative.md#option-2-documentpartgroup) on the
-`DocumentFragment` produced by the template.
-
-## `PartialAttributePart`
-
-Allowing `{{}}` inside an attribute with some static content raises the same
-question as a
-[`PartialAttributePart`](./DOM-Parts-Imperative.md#partial-attribute-updates),
-but if the imperative questions are resolved so too could the declarative
-template syntax.
-
-## Metadata
-
-Templating systems may need to serialize data about the nodes they are marking
-into the processing instructions. Or at the very least parts could be named so
-that they are easier to fetch.
-
-```html
-<div>{{email data="foo"}}</div>
-```
-
-This could be exposed on the imperative API to be consumed in JavaScript by
-application logic.
-
-## Choice of marker
-
-The `{{}}` is a reasonable DOM part marker, but it could be something else, or
-it could even be something that is declared as the placeholder.
-
-## Compatability
-
-It may be challenging to implement `<template>` parsing of `{{}}` for
-compatability reasons, so there may need to be restrictions such as only
-allowing this template syntax in a new API like `createTemplateWithParts()`.
diff --git a/proposals/DOM-Parts-Declarative.md b/proposals/DOM-Parts-Declarative.md
new file mode 100644
index 0000000..ee77065
--- /dev/null
+++ b/proposals/DOM-Parts-Declarative.md
@@ -0,0 +1,128 @@
+# DOM Parts Declarative API
+
+This proposal covers the declarative API for creating a DOM part within a
+`<template>` element and main document HTML.
+
+## Proposal
+
+Double curly braces `{{}}` provide markers for DOM parts.
+
+In the most basic level, this proposal can produce the three DOM parts:
+`NodePart`, `AttributePart`, `ChildNodePart`.
+
+### Basic Examples
+
+Suppose we had the following template in some HTML extension template languages
+where `{name}` and `{email}` indicated locations of dynamic data insertion:
+
+```html
+<section>
+  <h1 id="name">{name}</h1>
+  Email: <a id="link" href="mailto:{email}">{email}</a>
+</section>
+```
+
+And the application has produced an HTML `<template>` with the following
+content:
+
+```html
+<template>
+  <section>
+    <h1 id="name">{{}}</h1>
+    Email: <a id="link" href="{{}}">{{}}</a>
+  </section>
+</template>
+```
+
+This will create a `ChildNodePart` attached to `<h1>` with no content, an
+`AttributePart` connected to `href`, and a `ChildNodePart` connected to `<a>`
+with no content.
+
+A framework could fetch these parts use either a
+[`DocumentPart`](./DOM-Parts-Imperative.md#option-2-documentpartgroup) on the
+`DocumentFragment` produced by the template.
+
+## Enablement in main `document`
+
+For the main document, a new `parseparts` attribute is introduced that indicates
+to the parser it should parse DOM part tags as DOM parts.
+
+```html
+<div parseparts></div>
+```
+
+Even for `innerHTML` use cases, only DOM nodes that are wrapped DOM with the
+`parseparts` attribute will use declarative parts.
+
+## Node parts
+
+For node parts, a `{{}}` tag could be provided as an attribute.
+
+```html
+<template>
+  <section {{}}></section>
+</template>
+```
+
+Would create a `NodePart` for `<section>`.
+
+## Partial attributes
+
+Allowing `{{}}` inside an attribute works the same as a
+[partial attribute update](./DOM-Parts-Imperative.md#partial-attribute-updates),
+in that it will create an `AttributePart` for the entire attribute, but it will
+have multi-valued `value` property.
+
+```html
+<template>
+  <section>
+    <h1 id="name">{{}}</h1>
+    Email: <a id="link" href="mailto:{{}}">{{}}</a>
+  </section>
+</template>
+```
+
+The `AttributePart` for `href` would have `value` equal to `['mailto:', '']`.
+Empty string values are provided for any markers without default content.
+
+## Default Values
+
+To provide default values for any part, a part can be split into a start `{{#}}`
+and finish `{{/}}` indicators.
+
+```html
+<template>
+  <section>
+    <h1 id="name">{{#}}Ryosuke Niwa{{/}}</h1>
+    Email:
+    <a id="link" href="mailto:{{#}}rniwa@apple.com{{/}}">
+      {{#}}rniwa@apple.com{{/}}
+    </a>
+  </section>
+</template>
+```
+
+## Names and Metadata
+
+Templating systems may need to serialize data about the nodes they are marking
+into the processing instructions. Or at the very least parts could be named so
+that they are easier to fetch.
+
+```html
+<div>{{email data="foo"}}</div>
+```
+
+This could be exposed on the imperative API to be consumed in JavaScript by
+application logic.
+
+## Choice of marker
+
+The `{{}}` and `{{#}}{{/}}` are reasonable DOM part markers, but it could be
+something else, or it could even be something that is declared as the
+placeholder.
+
+## Compatability
+
+It may be challenging to implement `<template>` parsing of `{{}}` for
+compatability reasons, so there may need to be restrictions such as only
+allowing this template syntax in a new API like `createTemplateWithParts()`.
diff --git a/proposals/DOM-Parts-Imperative.md b/proposals/DOM-Parts-Imperative.md
index 748d190..e898479 100644
--- a/proposals/DOM-Parts-Imperative.md
+++ b/proposals/DOM-Parts-Imperative.md
@@ -8,37 +8,59 @@ A DOM part is represented by the `Part` interface and its sub interfaces.
 
 ```webidl
 interface Part {
-    attribute any value;
-    readonly attribute Array<Part> parts;
-    void commit();
+  attribute any value;
+
+  readonly attribute PartRoot root;
+  readonly attribute FrozenArray<DOMString> metadata;
+  void commit();
+};
+
+dictionary PartInit {
+  FrozenArray<DOMString> metadata;
 };
 
 interface NodePart : Part {
-    constructor(Node node);
-    readonly attribute Node node;
+  constructor(PartRoot root, Node node, optional PartInit init = {});
+
+  readonly attribute Node node;
 };
 
 interface AttributePart : Part {
-    constructor(Element element, DOMString qualifiedName, DOMString? namespace);
-    readonly attribute DOMString prefix;
-    readonly attribute DOMString localName;
-    readonly attribute DOMString namespaceURI;
+  constructor(
+      PartRoot root,
+      Element element,
+      DOMString qualifiedName,
+      optional DOMString? namespace = null,
+      optional PartInit init = {});
+
+  readonly attribute DOMString prefix;
+  readonly attribute DOMString localName;
+  readonly attribute DOMString namespaceURI;
 };
 
 interface ChildNodePart : Part {
-    constructor(Node node, Node? previousSibling, Node? nextSibling);
-    readonly attribute Node? previousSibling;
-    readonly attribute Node? nextSibling;
+  constructor(
+      PartRoot root,
+      optional Node? previousSibling = null,
+      optional Node? nextSibling = null,
+      optional PartInit init = {});
+
+  readonly attribute Node? previousSibling;
+  readonly attribute Node? nextSibling;
+  readonly attribute FrozenArray<Node> children;
+};
+
+interface DocumentPartRoot {
 };
 ```
 
-The `Part` has one property named "value" of
-[_any_ type](https://heycam.github.io/webidl/#idl-any). It also has a readonly `parts` property that
-contains any contained parts, if applicable.
+`Part` points to a specific type of DOM, most commonly a `Node` or collection of
+sibling nodes. Depending on the type of `Part`, it has various properties that
+expose more information.
 
-When a new value is set or assigned to a DOM part, the change does not
-immediately reflect back to the corresponding
-[node](https://dom.spec.whatwg.org/#concept-node), its
+Each `Part` has a `value` that can be updated. When a new value is set or
+assigned to a DOM part, the change does not immediately reflect back to the
+corresponding [node](https://dom.spec.whatwg.org/#concept-node), its
 [attributes](https://dom.spec.whatwg.org/#concept-attribute), or its
 [properties](<(https://tc39.es/ecma262/#sec-object-type)>). Instead, the new
 value is staged to be later committed in a batch. This batching reduces the
@@ -46,7 +68,7 @@ runtime overhead of constantly returning control back from browser's
 implementation to JavaScript between each DOM mutation and allows browser
 engine's to avoid or batch certain sanity checks and housekeeping tasks.
 
-In the most basic level, this proposal consists of three DOM parts:
+In the most basic level, this proposal consists of four DOM parts:
 
 1. `NodePart` represents a single
    [node](https://dom.spec.whatwg.org/#concept-node).
@@ -56,8 +78,11 @@ In the most basic level, this proposal consists of three DOM parts:
    [child](https://dom.spec.whatwg.org/#concept-tree-child)
    [nodes](https://dom.spec.whatwg.org/#concept-node) of a node which can be
    [replaced](https://dom.spec.whatwg.org/#concept-node-replace).
+1. `DocumentPartRoot` represents a
+   [document](https://dom.spec.whatwg.org/#concept-document) or
+   [document fragment](https://dom.spec.whatwg.org/#interface-documentfragment).
 
-### Basic Examples
+### Basic examples
 
 Suppose we had the following template in some HTML extension template languages
 where `{name}` and `{email}` indicated locations of dynamic data insertion:
@@ -89,9 +114,13 @@ as follows:
 ```js
 const name = staticContent.getElementById("name");
 const link = staticContent.getElementById("link");
-const namePart = new ChildNodePart(name);
-const emailPart = new ChildNodePart(link);
-const emailAttributePart = new AttributePart(link, "href");
+const namePart = new ChildNodePart(document.getPartRoot(), name);
+const emailPart = new ChildNodePart(document.getPartRoot(), link);
+const emailAttributePart = new AttributePart(
+  document.getPartRoot(),
+  link,
+  "href"
+);
 ```
 
 Then assigning values as follows will update the DOM:
@@ -114,60 +143,66 @@ The resultant DOM will look like this:
 </section>
 ```
 
-## `DocumentPart`
+## Retrieving a `DocumentPartRoot`
 
-A dynamic list of parts is maintained at the document or document fragment level that would allow fetching all parts.
+For every document or document fragment, a new method `getPartRoot()` is added
+that returns a `DocumentPartRoot`.
 
 ```webidl
-interface DocumentPart : Part {
-}
-
 partial interface Document {
-  DocumentPart getPart();
+  DocumentPartRoot getPartRoot();
 }
 
 partial interface DocumentFragment {
-  DocumentPart getPart();
+  DocumentPartRoot getPartRoot();
 }
 ```
 
-The list of parts would be cached initially on render, and then invalidated for
-lazy recalculation for any new `Part` that was declaratively or imperatively
-added to the `document`.
+## Nested parts and cloning with `PartRoot`
 
-The `parts` array would be in DOM-order. The exact algorithm for how to keep the
-`parts` array up to date with the `document` is up to the user-agent, but is invalidated anytime
-the user-agent detects changes to the DOM that could invalidate the array.
+`DocumentPartRoot` and `ChildNodePart` both implement `PartRoot` and contain
+nested parts.
 
-## `ChildNodePart` `parts` array
+```
+interface mixin PartRootMixin {
+  FrozenArray<Part> getParts();
+  PartRoot clone();
+};
 
-Much like `DocumentPart`, any parts contained within a `ChildNodePart` are also contained within a
-cached `parts` array.
+ChildNodePart includes PartRootMixin;
+DocumentPartRoot includes PartRootMixin;
 
-### Open Cloning Questions
+typedef (DocumentPartRoot or ChildNodePart) PartRoot;
+```
 
-The precise specification of invalidation, caching, etc. is still yet to be described.
+### `getParts()`
 
-## Cloning Parts
+`getParts()` returns an array of parts that are contained within a `PartRoot`.
 
-Cloning parts along with the nodes they refer to is a major use case for DOM
-parts. Cloning is supported for `DocumentPart` and `ChildNodePart`, which returns a `NodeWithParts`
-object that contains a root node as well as a parts array with top-level parts.
+The array of parts would be cached initially on render, and then invalidated for
+lazy recalculation for any new `Part` that was declaratively or imperatively
+added to the `document` or for DOM node additions or removals.
 
-```webidl
-partial interface DocumentPart {
-    NodeWithParts clone();
-}
+The array of parts would be in DOM-order. The exact algorithm for how to keep
+the array up to date with the `document` is up to the user-agent, but is
+invalidated anytime the user-agent detects changes to the DOM that could
+invalidate the array.
 
-partial interface ChildNodePart {
-    NodeWithParts clone();
-}
-```
+#### Open nested part questions
+
+The precise specification of invalidation, caching, etc. is still yet to be
+described.
 
-### Open Cloning Questions
+### `clone()`
 
-There are some edge cases that are worth thinking about, like whether un-committed values of parts
-are cloned or whether invalid parts should be cloned.
+`clone()` deep clones the `PartRoot`, its nested parts, and the DOM nodes. It
+returns a new `PartRoot` of the same type as the callee.
+
+#### Open cloning questions
+
+There are some edge cases that are worth thinking about, like whether
+un-committed values of parts are cloned or whether invalid parts should be
+cloned.
 
 ## Partial Attribute Updates
 
@@ -177,21 +212,25 @@ had initially contained `mailto:` before `{email}` but we could not capture this
 prefix in the attribute value because `AttributePart` could only set the whole
 attribute value.
 
-Instead of `AttributePart` having a single string `value`, it could optionally take an `Array` that
-contains values that should be concatenated together. This allows updating individually parts of the
-attribute without needing to serialize the entire string.
+Instead of `AttributePart` having a single string `value`, it could optionally
+take an `Array` that contains values that should be concatenated together. This
+allows updating individually parts of the attribute without needing to serialize
+the entire string.
 
 ```js
 const part = AttributePart(element, "href");
 part.value = ["mailto: ", email];
 ```
 
-This API may be strengthened further to optionally take in a `TemplateStringsArray` and variables,
-which would allow the browser to determine which parts of the attribute were compile-time
-constants. This could allow using tagged template literals to pass static content to the browser.
+This API may be strengthened further to optionally take in a
+`TemplateStringsArray` and variables, which would allow the browser to determine
+which parts of the attribute were compile-time constants. This could allow using
+tagged template literals to pass static content to the browser.
 
 ```js
-const part = AttributePart(element, "href", {template: attribute`mailto: ${0}`});
+const part = AttributePart(element, "href", {
+  template: attribute`mailto: ${0}`,
+});
 part.value = [email];
 ```
 
@@ -200,57 +239,40 @@ part.value = [email];
 Like partial attribute updates, when there are multiple points of interests
 under a single [parent](https://dom.spec.whatwg.org/#concept-tree-parent)
 [node](https://dom.spec.whatwg.org/#concept-node), and they're next to each
-other, previous and next sibling does not adequately describe a specific location in the DOM when
-other parts [insert](https://dom.spec.whatwg.org/#concept-node-insert) or
+other, previous and next sibling does not adequately describe a specific
+location in the DOM when other parts
+[insert](https://dom.spec.whatwg.org/#concept-node-insert) or
 [remove](https://dom.spec.whatwg.org/#concept-node-remove)
 [children](https://dom.spec.whatwg.org/#concept-tree-child).
 
-### Option 1. Create Multiple `ChildNodePart`s Together
+### Option 1. Create multiple `ChildNodePart`s together
 
 In this approach, `ChildNodePart` gets a new static function which creates a
 list of `ChildNodePart`s which work together to set a value when the values are
 to be committed:
 
 ```js
-const [firstName, lastName] = ChildNodePart.create(element, null, null, [
+const [firstName, lastName] = ChildNodePart.create(
+  document.getPartRoot(),
+  element,
   null,
-  " ",
   null,
-]);
+  [null, " ", null]
+);
 ```
 
 - **Pros**: Simplicity.
 - **Cons**: Coming up with a nice syntax to create a sequence of `ChildNodePart`
   and string can be tricky.
 
-### Option 2. Introduce `ChildNodePartGroup`
-
-In this approach, we group multiple `ChildNodePart`s together by creating an
-explicit group:
-
-```js
-const firstName = new ChildNodePart();
-const lastName = new ChildNodePart();
-const group = ChildNodePartGroup(element, null, null);
-group.append(firstName, " ", lastName);
-```
-
-This is morally equivalent to option 1 except there is an explicit grouping
-step.
-
-- **Pros**: Nicer syntax by the virtue of individual "partial" `ChildNodePart`s
-  existence at the time of grouping. Code that sets new children to
-  `ChildNodePart`s only needs to know about `ChildNodePart`.
-- **Cons**: More objects / complexity. `ChildNodePart` will have two modes.
-
-### Option 3. Introduce `PartialChildNodePart`
+### Option 2. Introduce `PartialChildNodePart`
 
 This creates `PartialChildNodePart` from `ChildNodePart`:
 
 ```js
 const firstNamePartial = new PartialChildNodePart();
 const lastNamePartial = new PartialChildNodePart();
-const part = ChildNodePart(element, null, null);
+const part = ChildNodePart(document.getPartRoot(), element, null, null);
 part.values = [firstNamePartial, " ", lastNamePartial];
 ```
 
@@ -260,17 +282,22 @@ part.values = [firstNamePartial, " ", lastNamePartial];
   with two different kinds of objects: `PartialChildNodePart` and
   `ChildNodePart`.
 
-### Option 4. Allow `nextSibling` and `previousSibling` to point to another `ChildNodePart`
+### Option 3. Allow `nextSibling` and `previousSibling` to point to another `ChildNodePart`
 
-We would update `ChildNodPart` interface as follows and allow `previousSibling`
-and `nextSibling` to point to another `ChildNodePart` as well as `Node`:
+Update `ChildNodPart` interface as follows and allow `previousSibling` and
+`nextSibling` to point to another `ChildNodePart` as well as `Node`:
 
 ```webidl
 interface ChildNodePart : Part {
-    constructor(Node node, (Node or ChildNodePart)? previousSibling, (Node or ChildNodePart)? nextSibling);
-    readonly attribute Node parentNode;
-    readonly attribute (Node or ChildNodePart)? previousSibling;
-    readonly attribute (Node or ChildNodePart)? nextSibling;
+  constructor(
+      PartRoot root,
+      optional (Node or ChildNodePart)? previousSibling = null,
+      optional (Node or ChildNodePart)? nextSibling = null,
+      optional PartInit init = {});
+
+  readonly attribute (Node or ChildNodePart)? previousSibling;
+  readonly attribute (Node or ChildNodePart)? nextSibling;
+  readonly attribute FrozenArray<Node> children;
 };
 ```
 
@@ -278,8 +305,8 @@ Then we can insert two consecutive `ChildNodePart`s by relating them in the
 constructor as follows:
 
 ```js
-const firstName = new ChildNodePart(element);
-const lastName = new ChildNodePart(element, firstName);
+const firstName = new ChildNodePart(document.getPartRoot(), element);
+const lastName = new ChildNodePart(document.getPartRoot(), element, firstName);
 ```
 
 Note that `lastName` takes `firstName` as the previous sibling but `firstName`
@@ -290,8 +317,8 @@ of previous/next sibling of other parts in the constructor.
 An alternative is to add an explicit API to chain multiple parts togethers:
 
 ```js
-const firstName = new ChildNodePart(element);
-const lastName = new ChildNodePart(element);
+const firstName = new ChildNodePart(document.getPartRoot(), element);
+const lastName = new ChildNodePart(document.getpartRoot(), element);
 ChildNodePart.chain(firstName, lastName);
 ```
 
@@ -305,8 +332,8 @@ Instead of worrying about coordination, the imperative API could throw an
 `Error` if users constructed two `ChildNodePart`s that overlapped.
 
 ```js
-const firstName = new ChildNodePart(element);
-const lastName = new ChildNodePart(element); // throws an Error.
+const firstName = new ChildNodePart(document.getPartRoot(), element);
+const lastName = new ChildNodePart(document.getPartRoot(), element); // throws an Error.
 ```
 
 Like in option 4, new APIs like `chain` or an a `append` could be added that
@@ -352,8 +379,8 @@ always are scoped to a single `Node`'s children.
 
 These invisible markers would not be `Node`s and so would be backwards
 compatible. DOM mutations would follow shrinking `Range` semantics, meaning the
-`ChildNodePart` would remove any `Node` that is removed in between the markers,
-and would only add a `Node` if it is added in between the markers.
+`ChildNodePart` would remove any `Node` that is removed in between the
+markers,and would only add a `Node` if it is added in between the markers.
 
 ## `PropertyPart` and `CustomCallbackPart`
 
diff --git a/proposals/DOM-Parts.md b/proposals/DOM-Parts.md
index 94e9aeb..c987482 100644
--- a/proposals/DOM-Parts.md
+++ b/proposals/DOM-Parts.md
@@ -103,4 +103,4 @@ There are a few component pieces to this proposal, so it is easiest to split it
 into multiple documents.
 
 1. [Imperative API to construct DOM parts](./DOM-Parts-Imperative.md)
-1. [Declarative API to construct DOM parts in `<template>`](./DOM-Parts-Declarative-Template.md)
+1. [Declarative API to construct DOM parts](./DOM-Parts-Declarative.md)