From 4a2bc22484a615bf318ed7e549c6fd0ba0764cda Mon Sep 17 00:00:00 2001
From: Domenic Denicola <d@domenic.me>
Date: Mon, 1 Nov 2021 13:40:50 -0400
Subject: [PATCH] Clarify that form state restoration does not fire events

(But, it does fire formStateRestoreCallback, since that is explicitly used for synchronizing the custom element's internal state.)

Closes #6853.
---
 source | 29 ++++++++++++++++++++---------
 1 file changed, 20 insertions(+), 9 deletions(-)

diff --git a/source b/source
index aaefc9551b6..c3d28328e1d 100644
--- a/source
+++ b/source
@@ -50251,6 +50251,10 @@ You cannot submit this form when the field is incorrect.</samp></pre>
   to the user manipulating the controls, without having to then filter out the script's own changes
   to avoid an infinite loop.)</p>
 
+  <p class="note">These events are also not fired when the browser changes the values of form
+  controls as part of <span data-x="restore persisted state">state restoration during
+  navigation</span>.</p>
+
   </div>
 
 
@@ -68811,9 +68815,10 @@ customElements.define("x-foo", class extends HTMLElement {
    argument.</p></li>
 
    <li><p>When user agent updates a <span>form-associated custom element</span>'s value on behalf of
-   a user, its <code data-x="">formStateRestoreCallback</code> is called, given the new value and a
-   string indicating a reason, "<code data-x="">restore</code>" or "<code
-   data-x="">autocomplete</code>", as arguments.</p></li>
+   a user or <span data-x="restore persisted state">as part of navigation</span>, its <code
+   data-x="">formStateRestoreCallback</code> is called, given the new value and a string indicating
+   a reason, "<code data-x="">autocomplete</code>" or "<code data-x="">restore</code>", as
+   arguments.</p></li>
   </ul>
 
   <p>We call these reactions collectively <dfn data-x="concept-custom-element-reaction">custom
@@ -69298,17 +69303,18 @@ dictionary <dfn dictionary>ValidityStateFlags</dfn> {
   agent.</p>
 
   <p>When the user agent believes it is a good idea to restore a <span>form-associated custom
-  element</span>'s <span data-x="face-state">state</span>, for example after navigation or
-  restarting the user agent, they may <span>enqueue a custom element callback reaction</span> with
-  that element, callback name "<code data-x="">formStateRestoreCallback</code>", and an argument
-  list containing the state to be restored, and <code data-x="">"restore"</code>.</p>
+  element</span>'s <span data-x="face-state">state</span>, for example <span data-x="restore
+  persisted state">after navigation</span> or restarting the user agent, they may <span>enqueue a
+  custom element callback reaction</span> with that element, callback name "<code
+  data-x="">formStateRestoreCallback</code>", an argument list containing the state to be
+  restored, and "<code data-x="">restore</code>".</p>
 
   <p>If the user agent has a form-filling assist feature, then when the feature is invoked,
   it may <span>enqueue a custom element callback reaction</span> with
   a <span>form-associated custom element</span>, callback name
-  "<code data-x="">formStateRestoreCallback</code>", and an argument list containing the state value
+  "<code data-x="">formStateRestoreCallback</code>", an argument list containing the state value
   determined by history of state value and some heuristics, and
-  <code data-x="">"autocomplete"</code>.</p>
+  "<code data-x="">autocomplete</code>".</p>
 
   <p>In general, the <span data-x="face-state">state</span> is information specified by a user, and
   the <span data-x="face-submission-value">submission value</span> is a value after canonicalization
@@ -88837,6 +88843,11 @@ new PaymentRequest(&hellip;); // Allowed to use
     data-x="attr-input-type-text">Text</span> state or the <span
     data-x="attr-input-type-search">Search</span> state, if the persisted state includes the
     directionality of user input in such controls.</p>
+
+    <p class="note">Restoring the value of form controls as part of this process does not fire any
+    <code data-x="event-input">input</code> or <code data-x="event-change">change</code> events, but
+    can trigger the <code data-x="">formStateRestoreCallback</code> of <span data-x="form-associated
+    custom element">form-associated custom elements</span>.</p>
    </li>
   </ol>