From c989a4c47381266c372b7c77a859b251c45a45fd Mon Sep 17 00:00:00 2001 From: Keith Cirkel Date: Fri, 31 Jan 2025 12:23:19 +0000 Subject: [PATCH] Editorial: reorganise dialog algorithms to end of section --- source | 446 ++++++++++++++++++++++++++++----------------------------- 1 file changed, 222 insertions(+), 224 deletions(-) diff --git a/source b/source index 61f30552fe3..813a9319d5a 100644 --- a/source +++ b/source @@ -61878,46 +61878,6 @@ interface HTMLDialogElement : HTMLElement {
-

To queue a dialog toggle event task given a dialog element - element, a string oldState, and a string newState: - -

    -
  1. -

    If element's dialog toggle task tracker is not null, then:

    - -
      -

    1. Set oldState to element's dialog toggle task - tracker's old state.

      2. - -

    2. Remove element's dialog toggle task tracker's task from its task queue.

      3. - -

    3. Set element's dialog toggle task tracker to null.

      4. -
    -
    2. - -
  2. -

    Queue an element task given the DOM manipulation task source and - element to run the following steps:

    - -
      -

    1. Fire an event named toggle at element, using ToggleEvent, with - the oldState attribute initialized to - oldState and the newState attribute - initialized to newState.

      2. - -

    2. Set element's dialog toggle task tracker to null.

      3. -
    -
    3. - -

  3. Set element's dialog toggle task tracker to a struct with task set to the just-queued task and old state set - to oldState.

    4. -
- -

The show() method steps are:

@@ -61980,6 +61940,150 @@ interface HTMLDialogElement : HTMLElement { data-x="dom-dialog-showModal">showModal() method steps are to show a modal dialog given this.

+

The close(returnValue) method steps are: + +

    +

  1. If returnValue is not given, then set it to null.

    2. + +

  2. Close the dialog this with returnValue.

    3. +
+ +

The requestClose(returnValue) method steps + are:

+ +
    +

  1. If this does not have an open + attribute, then return.

    2. + +

  2. Assert: this's close + watcher is not null.

    3. + +

  3. Set dialog's enable close watcher for requestClose() to true.

    4. + +

  4. If returnValue is not given, then set it to null.

    5. + +

  5. Set this's request close return value to + returnValue.

    6. + +

  6. Request to close dialog's + close watcher with false.

    7. + +

  7. Set dialog's enable close watcher for requestClose() to false.

    8. +
+ +
+

We use show/close as the verbs for dialog elements, as opposed to verb pairs that + are more commonly thought of as antonyms such as show/hide or open/close, due to the following + constraints:

+ +
    +

  • Hiding a dialog is different from closing one. Closing a dialog gives it a return value, + fires an event, unblocks the page for other dialogs, and so on. Whereas hiding a dialog is a + purely visual property, and is something you can already do with the hidden attribute or by removing the open attribute. (See also the note above about removing the open attribute, and how hiding the dialog in that way is + generally not desired.)

    • + +

  • Showing a dialog is different from opening one. Opening a dialog consists of creating + and showing that dialog (similar to how window.open() both + creates and shows a new window). Whereas showing the dialog is the process of taking a + dialog element that is already in the DOM, and making it interactive and visible + to the user.

    • + +

  • If we were to have a dialog.open() method despite the above, it + would conflict with the dialog.open property.

    • +
+ +

Furthermore, a survey + of many other UI frameworks contemporary to the original design of the dialog + element made it clear that the show/close verb pair was reasonably common.

+ +

In summary, it turns out that the implications of certain verbs, and how they are used in + technology contexts, mean that paired actions such as showing and closing a dialog are not + always expressible as antonyms.

+
+ +
+ +

The returnValue IDL attribute, on getting, must return + the last value to which it was set. On setting, it must be set to the new value. When the element + is created, it must be set to the empty string.

+ +

The closedBy IDL attribute must reflect the + closedby content attribute, limited to only + known values.

+ +

The open IDL + attribute must reflect the open content + attribute.

+ +
+ +

Each Document has a dialog pointerdown target, which is an HTML dialog element or null, initially null.

+ +

Each HTML element has a previously focused + element which is null or an element, and it is initially null. When showModal() and show() + are called, this element is set to the currently focused element before running the + dialog focusing steps. Elements with the popover + attribute set this element to the currently focused element during the show popover algorithm.

+ +

Each dialog element has a dialog toggle task tracker, which is a + toggle task tracker or null, initially null.

+ +

Each dialog element has a close watcher, + which is a close watcher or null, initially null.

+ +

Each dialog element has a request close return value, which is a + string, initially null.

+ +

Each dialog element has an enable close watcher for requestClose() boolean, initially false.

+ +

Each dialog element has an is modal boolean, initially false.

+ +
+ +
+ +

The dialog HTML element removing steps, given removedNode + and oldParent, are:

+ +
    +
  1. +

    If removedNode's close watcher is not + null, then:

    + +
      +

    1. Destroy removedNode's close watcher.

      2. + +

    2. Set removedNode's close watcher to + null.

      3. +
    +
    2. + +

  2. If removedNode's node document's top layer contains removedNode, then remove an element from + the top layer immediately given removedNode.

    3. + +

  3. Set is modal of removedNode to false.

    4. + +

  4. Remove removedNode from + removedNode's node document's open dialogs list.

    5. +
+

To show a modal dialog given a dialog element subject:

    @@ -62070,42 +62174,6 @@ interface HTMLDialogElement : HTMLElement {

  1. Run the dialog focusing steps given subject.

-

The close(returnValue) method steps are: - -

    -

  1. If returnValue is not given, then set it to null.

    2. - -

  2. Close the dialog this with returnValue.

    3. -
- -

The requestClose(returnValue) method steps - are:

- -
    -

  1. If this does not have an open - attribute, then return.

    2. - -

  2. Assert: this's close - watcher is not null.

    3. - -

  3. Set dialog's enable close watcher for requestClose() to true.

    4. - -

  4. If returnValue is not given, then set it to null.

    5. - -

  5. Set this's request close return value to - returnValue.

    6. - -

  6. Request to close dialog's - close watcher with false.

    7. - -

  7. Set dialog's enable close watcher for requestClose() to false.

    8. -
- -

To set the dialog close watcher, given a dialog element dialog:

@@ -62136,92 +62204,6 @@ interface HTMLDialogElement : HTMLElement { -

To retrieve a dialog's computed closed-by state, given a dialog - dialog: - -

    -
  1. -

    If the state of dialog's closedby - attribute is Auto:

    - -
      -

    1. If dialog's is modal is true, then return Close Request.

      2. - -

    2. Return None.

      3. -
    -
    2. - -

  2. Return the state of dialog's closedby attribute.

    3. -
- -

The dialog focusing steps, given a dialog element subject, - are as follows:

- -
    -

  1. Let control be null.

    2. - -

  2. If subject has the autofocus - attribute, then set control to subject.

    3. - -

  3. If control is null, then set control to the focus - delegate of subject.

    4. - -

  4. If control is null, then set control to subject.

    5. - -
  5. -

    Run the focusing steps for control.

    - -

    If control is not focusable, this will do nothing. This - would only happen if subject had no focus delegate, and the user agent decided that - dialog elements were not generally focusable. In that case, any earlier modifications to the focused area of the - document will apply.

    -
    6. - -

  6. Let topDocument be control's node navigable's top-level traversable's active - document.

    7. - -

  7. If control's node document's origin is not the same - as the origin of topDocument, then - return.

    8. - -

  8. Empty topDocument's - autofocus candidates.

    9. - -

  9. Set topDocument's autofocus processed flag to true.

    10. -
- -

The dialog HTML element removing steps, given removedNode - and oldParent, are:

- -
    -
  1. -

    If removedNode's close watcher is not - null, then:

    - -
      -

    1. Destroy removedNode's close watcher.

      2. - -

    2. Set removedNode's close watcher to - null.

      3. -
    -
    2. - -

  2. If removedNode's node document's top layer contains removedNode, then remove an element from - the top layer immediately given removedNode.

    3. - -

  3. Set is modal of removedNode to false.

    4. - -

  4. Remove removedNode from - removedNode's node document's open dialogs list.

    5. -
-

When a dialog element subject is to be closed, with null or a string result, run these steps:

@@ -62297,87 +62279,103 @@ interface HTMLDialogElement : HTMLElement {
-
-

We use show/close as the verbs for dialog elements, as opposed to verb pairs that - are more commonly thought of as antonyms such as show/hide or open/close, due to the following - constraints:

+

To queue a dialog toggle event task given a dialog element + element, a string oldState, and a string newState: -

+

  • Remove element's dialog toggle task tracker's task from its task queue.

    • -

    Furthermore, a survey - of many other UI frameworks contemporary to the original design of the dialog - element made it clear that the show/close verb pair was reasonably common.

    +

  • Set element's dialog toggle task tracker to null.

    • + + -

    In summary, it turns out that the implications of certain verbs, and how they are used in - technology contexts, mean that paired actions such as showing and closing a dialog are not - always expressible as antonyms.

    -
    +
  • +

    Queue an element task given the DOM manipulation task source and + element to run the following steps:

    -
    +
      +

    1. Fire an event named toggle at element, using ToggleEvent, with + the oldState attribute initialized to + oldState and the newState attribute + initialized to newState.

      2. -

      The returnValue IDL attribute, on getting, must return - the last value to which it was set. On setting, it must be set to the new value. When the element - is created, it must be set to the empty string.

      +

    2. Set element's dialog toggle task tracker to null.

      3. +
    +
    • -

    The closedBy IDL attribute must reflect the - closedby content attribute, limited to only - known values.

    +

  • Set element's dialog toggle task tracker to a struct with task set to the just-queued task and old state set + to oldState.

    • + -

    The open IDL - attribute must reflect the open content - attribute.

    +

    To retrieve a dialog's computed closed-by state, given a dialog + dialog: -

    +
      +
    1. +

      If the state of dialog's closedby + attribute is Auto:

      -

      Each Document has a dialog pointerdown target, which is an HTML dialog element or null, initially null.

      +
        +

      1. If dialog's is modal is true, then return Close Request.

        2. -

        Each HTML element has a previously focused - element which is null or an element, and it is initially null. When showModal() and show() - are called, this element is set to the currently focused element before running the - dialog focusing steps. Elements with the popover - attribute set this element to the currently focused element during the show popover algorithm.

        +

      2. Return None.

        3. +
      +
      2. -

      Each dialog element has a dialog toggle task tracker, which is a - toggle task tracker or null, initially null.

      +

    2. Return the state of dialog's closedby attribute.

      3. +
    -

    Each dialog element has a close watcher, - which is a close watcher or null, initially null.

    +

    The dialog focusing steps, given a dialog element subject, + are as follows:

    -

    Each dialog element has a request close return value, which is a - string, initially null.

    +
      +

    1. Let control be null.

      2. -

      Each dialog element has an enable close watcher for requestClose() boolean, initially false.

      +

    2. If subject has the autofocus + attribute, then set control to subject.

      3. -

      Each dialog element has an is modal boolean, initially false.

      +

    3. If control is null, then set control to the focus + delegate of subject.

      4. -
      +

    4. If control is null, then set control to subject.

      5. - +
    5. +

      Run the focusing steps for control.

      + +

      If control is not focusable, this will do nothing. This + would only happen if subject had no focus delegate, and the user agent decided that + dialog elements were not generally focusable. In that case, any earlier modifications to the focused area of the + document will apply.

      +
      6. + +

    6. Let topDocument be control's node navigable's top-level traversable's active + document.

      7. + +

    7. If control's node document's origin is not the same + as the origin of topDocument, then + return.

      8. + +

    8. Empty topDocument's + autofocus candidates.

      9. + +

    9. Set topDocument's autofocus processed flag to true.

      10. +

    Dialog light dismiss