From 58f8e52168540a048a9e3fccad5f85dc0c5f133c Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Fri, 8 Mar 2024 19:00:35 +0100 Subject: [PATCH] Modernize algorithms in "Algorithm" section The original main goal was to give a name to the existing algorithm that used to run in the "next animation frame task" so that it could be referenced in the upcoming WebDriver section, but "animation frame task" as a concept did not exist, and one thing led to another and the final change includes a better version of the original algorithms, but without any user-visible changes. This change borrows a lot of ideas from the Screen Orientation spec as of its 2023-08-09 Editor's Draft. Most important changes: - The "update the device posture information" algorithm was renamed to "calculate the device posture information" so that it returns a value instead of updating `[[CurrentPosture]]` directly -- that is done as task queued in the user interaction task source (more on this below). - Call the main algorithm "device posture change steps". - Merge the separate page visibility-related algorithm into the main one, and add the proper checks to it to ensure that documents whose visibility state is "hidden" are not updated and that calls to "update the device posture information" that result in the same value being stored do not fire any "change" events. - The "change" event is now queued to be fired in the user interaction task source so that the moment it is actually fired is more predictable (the "device posture change steps" are not running at any specific point of the HTML event loop). While here: the definition of the `onchange` attribute was updated to mention the current terms defined in the HTML spec, along with a proper `` for the event handler event type. The language and the references used in the text have also been updated: we no longer deal with browsing contexts, but with navigables; the PAGE-VISIBILITY spec is no longer treated as a separate specification, as it was merged into HTML a few years ago. Related to #104. Fixes #95. --- index.html | 144 +++++++++++++++++++++++------------------------------ 1 file changed, 61 insertions(+), 83 deletions(-) diff --git a/index.html b/index.html index 22e72b0..9b6ba6a 100644 --- a/index.html +++ b/index.html @@ -250,9 +250,10 @@

The onchange attribute: Handle posture changes

- The {{onchange}} attribute is an event - handler whose corresponding event handler - event type is "change". + The {{onchange}} attribute is an event handler IDL attribute + for the {{onchange}} [=event handler=], whose [=event handler event + type=] is "change".

@@ -378,8 +379,8 @@

{{Document/[[CurrentPosture]]}}, which should be initialized when the document is created, otherwise they MUST be initialized the first time they are accessed and before their value is read. The - user agent MUST update the device posture information of - the document to initialize it. + user agent MUST run the device posture change steps with + the document and true to initialize it.

For a given document, the current posture is derived from @@ -445,17 +446,18 @@

- Updating the device posture information + Calculating the device posture information

- The steps to update the device posture information of a - document are as follows: + The steps to calculate the device posture information of a + {{Document}} |document:Document| are as follows:

    -
  1. Update the document.{{Document/[[CurrentPosture]]}} given - current hinge angle value, current screen orientation, as well - as potential implementation-specific signals, according to posture - values table. +
  2. Return a {{DevicePostureType}} value determined in an + [=implementation-defined=] way based on the current hinge angle + value, [=current screen orientation=], as well as potential + implementation-specific signals, according to the [=posture values + table=].
@@ -464,74 +466,70 @@

Device Posture change

- Whenever the screen(s) fold angle, screen orientation or device - specific signals change, the user agent MUST run the following - steps as part of the next animation frame task: + When the user agent determines that the screen(s)' fold angle, + orientation or device-specific signals have changed for a [=top-level + traversable=], it MUST run the [=device posture change steps=] with + the [=top-level traversable=]'s [=navigable/active document=]. +

+

+ The device posture change steps for a {{Document}} + |document:Document| and an optional boolean |disallowRecursion| + (default false) are as follows:

    -
  1. Let |browsing contexts| be the list of the descendant browsing - contexts of the top-level browsing context's - document. +
  2. If |document|'s [=Document/visibility state=] is "hidden", then + abort these steps. +
    3. +
  3. Let |posture| be the result of invoking [=calculate the device + posture information=] with |document|.
    4. -
  4. [=list/for each=] |context:browsing context| in |browsing - contexts|, run the following sub-steps: +
  5. If |posture| is equal to + |document|.{{Document/[[CurrentPosture]]}}, abort these steps. +
    6. +
  6. [=Queue a global task=] on the [=user interaction task source=] + with |document|'s [=relevant global object=] to perform the following + steps:
      -
    1. Let |document| be the |context|'s [=navigable/active - document=]. -
      2. -
    2. If |document| is not visible per [[PAGE-VISIBILITY]], abort - these steps. + +
    3. Set |documet|.{{Document/[[CurrentPosture]]}} to |posture|.
      4. -
    4. - Update the device posture information of |document|. +
    5. [=Fire an event=] named "{{DevicePosture/change}}" at the + {{DevicePosture}} object associated with |document|'s [=relevant + global object=]'s associated {{Navigator}}.
      6. -
    6. - Fire an event named `change` at |document|'s - {{Window.navigator.devicePosture}} object. +
    +
    7. +
  7. If |disallowRecursion| is true, abort these steps. +
    8. +
  8. [=List/For each=] |descendantNavigable| of |document|'s + [=Document/descendant navigables=]: +
      + +
    1. Run the [=device posture change steps=] with + |descendantNavigable|'s [=navigable/active document=] and true.

- Whenever a document becomes visible per [[PAGE-VISIBILITY]], - in other words after the now visible algorithm is run, the - user agent MUST run the following substeps as part of the next - animation frame task: + This specification defines the following [=page visibility change + steps=] given |visibility state| and |document:Document|:

    -
  1. Let |document| be the document in question. -
    2. -
  2. Let |posture| be the |document|.{{Document/[[CurrentPosture]]}}. -
    3. -
  3. - Update the device posture information of the |document|. -
    4. -
  4. If |posture| is different from the - |document|.{{Document/[[CurrentPosture]]}}, run the following - sub-steps: -
      -
    1. - Fire an event named `change` at the |document|'s - {{Window.navigator.devicePosture}} object. -
      2. -
    +
  5. Run the [=device posture change steps=] on |document|.
-
+
-
- This section could be improved if the [[PAGE-VISIBILITY]] - specification had a hook for when the document becomes visible and - hidden. PR - 54. -
+ +
@@ -697,26 +695,6 @@

"MEDIAQ#mq-boolean-context">Evaluating Media Features in a Boolean Context.

-

- The following concepts and interfaces are defined in [[HTML]]: - list of - the descendant browsing contexts. -

-

- The following is defined in [[PAGE-VISIBILITY]]: now visible - algorithm. -

-

- The following is used but not defined in [[FULLSCREEN]]: animation frame - task. -

-
- This should now be updated since the animation frame task issue - is recently resolved and the timing is now defined. -