From 21b8a2c916a39d76ce433b93addd47461a8e1b73 Mon Sep 17 00:00:00 2001
From: Joey Arhar <jarhar@chromium.org>
Date: Wed, 18 Sep 2024 13:30:18 -0700
Subject: [PATCH] Define the `<selectedoption>` element

The `<selectedoption>` element is part of the customizable `<select>`
proposal: https://github.com/whatwg/html/issues/9799

It allows authors to declaratively clone the contents of the currently
selected `<option>` of a `<select>` and style it independently for use
in a base appearance `<select>`'s button.

The timing of cloning has been discussed here:
https://github.com/whatwg/html/issues/10520

The selectedoption element has been discussed generally here:
https://github.com/w3c/csswg-drafts/issues/10242
---
 source | 181 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 181 insertions(+)

diff --git a/source b/source
index de407dd6dc0..200d049fc6e 100644
--- a/source
+++ b/source
@@ -1794,6 +1794,9 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
    <span>stack of open elements</span> of an <span>HTML parser</span>, then
    <span>process internal resource links</span> given <var>insertedNode</var>'s
    <span>node document</span>.</p></li>
+
+   <li><p>Run <span>maybe clone option into selectedoption</span> given
+   <var>insertedNode</var>.</p></li>
   </ol>
 
   <p>The <span data-x="concept-node-remove-ext">removing steps</span> for the HTML Standard, given
@@ -1838,6 +1841,9 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
    <li><p>If <var>removedNode</var>'s <code data-x="attr-popover">popover</code> attribute is not in
    the <span data-x="attr-popover-none-state">no popover state</span>, then run the <span>hide
    popover algorithm</span> given <var>removedNode</var>, false, false, and false.</p></li>
+
+   <li><p>Run <span>maybe clone option into selectedoption</span> given
+   <var>oldParent</var>.</p></li>
   </ol>
 
   <p>A <dfn id="insert-an-element-into-a-document" data-x="node is inserted into a document"
@@ -3201,6 +3207,7 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
      <li><dfn data-x="dom-Element-id" data-x-href="https://dom.spec.whatwg.org/#dom-element-id"><code>id</code></dfn> attribute</li>
      <li><dfn data-x="dom-Element-setAttribute" data-x-href="https://dom.spec.whatwg.org/#dom-element-setattribute"><code>setAttribute()</code></dfn> method</li>
      <li><dfn data-x-href="https://dom.spec.whatwg.org/#dom-node-textcontent"><code>textContent</code></dfn> attribute</li>
+     <li><dfn data-x="dom-parentnode-replacechildren" data-x-href="https://dom.spec.whatwg.org/#dom-parentnode-replacechildren"><code>replaceChildren()</code></dfn> method</li>
 
      <li>The <dfn data-x-href="https://dom.spec.whatwg.org/#concept-tree">tree</dfn>, <dfn data-x-href="https://dom.spec.whatwg.org/#concept-shadow-tree">shadow tree</dfn>, and <dfn data-x-href="https://dom.spec.whatwg.org/#concept-node-tree">node tree</dfn> concepts</li>
      <li>The <dfn data-x-href="https://dom.spec.whatwg.org/#concept-tree-order">tree order</dfn> and <dfn data-x-href="https://dom.spec.whatwg.org/#concept-shadow-including-tree-order">shadow-including tree order</dfn> concepts</li>
@@ -3208,6 +3215,7 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
      <li>The <dfn data-x-href="https://dom.spec.whatwg.org/#concept-tree-child" data-x="concept-tree-child">child</dfn> concept</li>
      <li>The <dfn data-x-href="https://dom.spec.whatwg.org/#concept-tree-root">root</dfn> and <dfn data-x-href="https://dom.spec.whatwg.org/#concept-shadow-including-root">shadow-including root</dfn> concepts</li>
      <li>The <dfn data-x-href="https://dom.spec.whatwg.org/#concept-tree-inclusive-ancestor">inclusive ancestor</dfn>,
+             <dfn data-x-href="https://dom.spec.whatwg.org/#concept-tree-ancestor">ancestor</dfn>,
              <dfn data-x-href="https://dom.spec.whatwg.org/#concept-tree-descendant">descendant</dfn>,
              <dfn data-x="concept-shadow-including-ancestor" data-x-href="https://dom.spec.whatwg.org/#concept-shadow-including-ancestor">shadow-including ancestor</dfn>,
              <dfn data-x-href="https://dom.spec.whatwg.org/#concept-shadow-including-descendant">shadow-including descendant</dfn>,
@@ -53304,6 +53312,9 @@ interface <dfn interface>HTMLSelectElement</dfn> : <span>HTMLElement</span> {
   element, and all the <code>option</code> element children of all the <code>optgroup</code> element
   children of the <code>select</code> element, in <span>tree order</span>.</p>
 
+  <p>Every <code>select</code> element has <dfn>select descendant selectedoption elements</dfn>,
+  which is a <span>list</span> of <code>selectedoption</code> elements, initially « ».</p>
+
   <p>The <dfn element-attr for="select"><code data-x="attr-select-required">required</code></dfn>
   attribute is a <span>boolean attribute</span>. When specified, the user will be required to select
   a value before submitting the form.</p>
@@ -54156,6 +54167,61 @@ interface <dfn interface>HTMLOptionElement</dfn> : <span>HTMLElement</span> {
 
   </div>
 
+  <p>To get the <dfn>option element ancestor select</dfn> given an <code>option</code>
+  <var>option</var>:</p>
+
+  <ol>
+   <li>
+    <p>For each <var>ancestor</var> of <var>option</var>'s <span
+    data-x="ancestor">ancestors</span>:</p>
+
+    <ol>
+     <li><p>If <var>ancestor</var> is a <code>select</code>, then return
+     <var>ancestor</var>.</p></li>
+    </ol>
+   </li>
+
+   <li><p>Return null.</p></li>
+  </ol>
+
+  <p>To <dfn>maybe clone option into selectedoption</dfn>, given an <code>Element</code>
+  <var>element</var>:</p>
+
+  <ol>
+   <li>
+    <p>For each <var>ancestor</var> of <var>element</var>'s <span
+    data-x="ancestor">ancestors</span>:</p>
+
+    <ol>
+     <li>
+      <p>If all of the following conditions are true:</p>
+
+      <ul>
+       <li><p><var>ancestor</var> is an <code>option</code> element;</p></li>
+
+       <li><p><var>ancestor</var> has a non-null <span>option element ancestor
+       select</span>;</p></li>
+
+       <li><p><var>ancestor</var>'s <span>option element ancestor select</span> is rendered as a
+       <span>drop-down box</span>;</p></li>
+
+       <li><p><var>ancestor</var>'s <span data-x="concept-option-selectedness">selectedness</span>
+       is true,</p></li>
+      </ul>
+
+      <p>then for each <var>selectedoption</var> of <var>ancestor</var>'s <span>option element
+      ancestor select</span>'s <span>select descendant selectedoption elements</span>, run
+      <span>clone an option into a selectedoption</span> given <var>ancestor</var> and
+      <var>selectedoption</var>.</p>
+     </li>
+    </ol>
+   </li>
+  </ol>
+
+  <p>Whenever an <code>option</code> <var>option</var>'s <span
+  data-x="concept-option-selectedness">selectedness</span> is set to true, run <span>maybe clone
+  option into selectedoption</span> given <var>option</var>.</p>
+
   <dl class="domintro">
    <dt><code data-x=""><var>option</var>.<span subdfn data-x="dom-option-selected">selected</span></code></dt>
 
@@ -55816,6 +55882,121 @@ interface <dfn interface>HTMLLegendElement</dfn> : <span>HTMLElement</span> {
 
   </div>
 
+  <h4>The <dfn element><code>selectedoption</code></dfn> element</h4>
+
+  <p>The <code>selectedoption</code> element reflects the contents of a <code>select</code>
+  element's currently selected <code>option</code> element. <code>selectedoption</code> elements can
+  be used to declaratively show the selected <code>option</code> element's contents in a different
+  part of the document, such as the <code>select</code> element's invoker button, with alternate
+  rendering based on different selectors in the author's stylesheet.</p>
+
+  <p>Every time the selected <code>option</code> of a <code>select</code> switches from one option
+  to another, or the currently selected <code>option</code>'s descendant DOM structure mutates, the
+  <code>selectedoption</code> element removes all of its children and replaces them with a new
+  cloned copy of the DOM structure of the <code>select</code>'s selected <code>option</code>
+  element.</p>
+
+  <p><code>selectedoption</code> elements become associated with <code>select</code> elements when
+  the <code>selectedoption</code> is a <span>descendant</span> of the <code>select</code>.</p>
+
+  <p>To <dfn>clone an option into a selectedoption</dfn>, given an <code>option</code> element
+  <var>option</var> and a <code>selectedoption</code> element <var>selectedOption</var>:</p>
+
+  <ol>
+   <li><p>Let <var>nodes</var> be « ».</p></li>
+
+   <li>
+    <p>If <var>option</var> is not null, then for each <var>child</var> of <var>option</var>'s <span
+    data-x="concept-tree-child">children</span>:</p>
+
+    <ol>
+     <li><p>Let <var>childClone</var> be the result of running <span
+     data-x="concept-node-clone">clone</span> given <var>child</var>, null, true.</p></li>
+
+     <li><p><span data-x="list append">Append</span> <var>childClone</var> to
+     <var>nodes</var>.</p></li>
+    </ol>
+   </li>
+
+   <li><p>Run <span data-x="dom-parentnode-replacechildren">replaceChildren</span> on
+   <var>selectedOption</var> given <var>nodes</var>.</p></li>
+  </ol>
+
+  <p>The <code>selectedoption</code> <span>HTML element insertion steps</span>, given
+  <var>selectedoption</var>, are:</p>
+
+  <ol>
+   <li><p>Let <var>firstAncestorSelect</var> be null.</p></li>
+
+   <li><p>Let <var>ancestor</var> be <var>selectedoption</var>'s <span>parent</span>.</p></li>
+
+   <li>
+    <p><span>While</span> <var>firstAncestorSelect</var> is null and <var>ancestor</var> is not
+    null:</p>
+
+    <ol>
+     <li><p>If <var>ancestor</var> is a <code>select</code> element, then set
+     <var>firstAncestorSelect</var> to <var>ancestor</var>.</p></li>
+
+     <li><p>Set <var>ancestor</var> to <var>ancestor</var>'s <span>parent</span>.</p></li>
+    </ol>
+   </li>
+
+   <li><p>If <var>firstAncestorSelect</var> is null, then return.</p></li>
+
+   <li><p><span data-x="list append">Append</span> <var>selectedoption</var> to
+   <var>firstAncestorSelect</var>'s <span>select descendant selectedoption elements</span>.</p></li>
+
+   <li><p>Run <span>clone an option into a selectedoption</span> given the first <code>option</code>
+   in <var>firstAncestorSelect</var>'s <span data-x="concept-select-option-list">list of
+   options</span> whose <span data-x="concept-option-selectedness">selectedness</span> is true and
+   <var>insertedNode</var>.</p></li>
+  </ol>
+
+  <p>The <code>selectedoption</code> <span>HTML element removing steps</span>, given
+  <var>selectedoption</var> and <var>oldParent</var>, are:</p>
+
+  <ol>
+   <li>
+    <p>For each <var>ancestor</var> of <var>selectedoption</var>'s <span
+    data-x="ancestor">ancestors</span>:</p>
+
+    <ol>
+     <li><p>If <var>ancestor</var> is a <code>select</code> element, then return.</p></li>
+    </ol>
+   </li>
+
+   <li>
+    <p>For each <var>ancestor</var> of <var>oldParent</var>'s <span data-x="inclusive
+    ancestor">inclusive ancestors</span>:</p>
+
+    <ol>
+     <li>
+      <p>If <var>ancestor</var> is a <code>select</code> element, then:</p>
+
+      <ol>
+       <li><p><span data-x="list remove">remove</span> <var>selectedoption</var> from
+       <var>ancestor</var>'s <span>select descendant selectedoption elements</span>.</p></li>
+
+       <li><p>Run <span>clone an option into a selectedoption</span> given null and
+       <var>selectedoption</var>.</p></li>
+
+       <li><p>Return.</p></li>
+      </ol>
+     </li>
+    </ol>
+   </li>
+  </ol>
+
+  <p>The following <span data-x="concept-element-attributes-change-ext">attribute change
+  steps</span>, given <var>element</var>, <var>localName</var>, <var>oldValue</var>,
+  <var>value</var>, and <var>namespace</var> are used for all <span>HTML elements</span> in order to
+  support <code>selectedoption</code> elements:</p>
+
+  <ol>
+   <li><p>Run <span>maybe clone option into selectedoption</span> given <var>element</var>.</p></li>
+  </ol>
+
 
 
   <h4 split-filename="form-control-infrastructure">Form control infrastructure</h4>