Dialog processing model has gotten disorganized

[domenic]

What is the issue with the HTML Standard?

https://html.spec.whatwg.org/#the-dialog-element has grown organically over time and has gotten a bit disorganized. This issue proposes rearranging some of its content, with no additions or removals, to make the structure clearer.

Current structure:

• Discussion of dialogs and some examples
• Definition of content attributes
• domintro block for API
• Concept: dialog toggle task tracker
• Algorithm: queue a dialog toggle even ttask
• Methods: show() and showModal()
• Algorithms: set the dialog close watcher, computed closed-by state, dialog focusing steps
• HTML element removing steps (plus, after Fix dialog closedby and requestClose() #10954, attribute changed steps)
• Methods: close(), requestClose()
• Algorithm: close
• Property: returnValue
• Note discussing the show/close verbs
• Concepts: dialog pointerdown target, close watcher, request close return value, enable close watcher for requestClose(), is modal, previously focused element
• Properties: closedBy, open
• Example of using the dialog element with strong

Suggested reordering:

• Discussion of dialogs and some examples
  • Move the bottom "example of using the dialog element with strong" to here
• <hr>?
• Definition of content attributes, and things related to them like conformance requirements and the note about about open="" misuse
• <hr>
• domintro block for API
• Methods: show(), showModal(), close(), requestClose()
• Note discussing the show/close verbs
• Properties: returnValue, closedBy, open
• <hr>
• Concepts: all of them go here. Arrange them by the object that owns them (e.g. Document vs. dialog element vs. all HTML elements)
• <hr>?
• Algorithms: all algorithms go here. Consider putting "more important" algorithms earlier.