review edits: declarative dialog popover control (#806)

* apply updates to guide

* wip update demo expectations

Author: dvdherron

guides/user-experience/declarative-dialog-popover-control/demo.html

@@ -1,15 +1,14 @@
-- The document contains a button with the `commandfor` attribute targeting the ID of a popover element.
-- A button used to toggle a popover has a `command` attribute set to `toggle-popover`.
-- A button used to explicitly open a popover has a `command` attribute set to `show-popover`.
-- A button used to explicitly close a popover has a `command` attribute set to `hide-popover`.
-- The target element for the popover has the `popover` attribute.
-- The document contains a button with the `commandfor` attribute targeting the ID of a `<dialog>` element.
-- The button targeting the dialog has a `command` attribute set to `show-modal`.
-- The target element for the dialog is a `<dialog>` element.
-- There is a button, typically inside the `<dialog>` element, with the `commandfor` attribute targeting the dialog's ID.
-- The button to close the dialog has a `command` attribute set to `close`.
-- The document includes a fallback script that conditionally loads the `invokers-polyfill`.
-- The `invokers-polyfill` is only loaded if `'commandForElement' in HTMLButtonElement.prototype` is false.
-- The document includes a fallback script that conditionally loads a `popover` polyfill.
-- The `popover` polyfill is only loaded if `'popover' in HTMLElement.prototype` is false.
-- If the open state of a popover is styled, `:popover-open` is not used by itself, combined with the polyfill class `.\:popover-open` via `:is()` or `:where()`
+- The document uses buttons with `commandfor` and `command` attributes to declaratively control UI elements.
+- A button used to toggle a popover has `command="toggle-popover"` and an initial `aria-expanded="false"` attribute.
+- Buttons for explicit popover control use `command="show-popover"` and `command="hide-popover"`.
+- The target element for popover commands has the `popover` attribute.
+- A button used to open a modal dialog has `command="show-modal"` and targets a `<dialog>` element.
+- A button used to close a dialog has `command="close"`.
+- The fallback strategy MUST feature detect support by checking for `commandForElement` in `HTMLButtonElement.prototype` and `popover` in `HTMLElement.prototype`.
+- Polyfills MUST be loaded via dynamic `import()` only when native support is missing (or forced for testing).
+- The `invokers-polyfill` is dynamically imported from a CDN (e.g., `https://esm.run/invokers-polyfill`).
+- The `@oddbird/popover-polyfill` is dynamically imported and its `apply()` method is called.
+- CSS styling for the open state of a popover uses `:is()` or `:where()` to combine `:popover-open` with the polyfill class `.\:popover-open`.
+- The target element for explicit popover control (show/hide) has the `popover="manual"` attribute.
+- A `command` event listener is attached directly to each target element (not delegated via bubbling) when using the polyfill.
+- The `command` event listener identifies the command name via `event.command` (native) or `event.detail.command` (polyfill).

guides/user-experience/declarative-dialog-popover-control/expectations.md

@@ -44,7 +44,7 @@ If you need to control opening and closing with separate buttons, you can use th
   Show Popover
 </button>
 
-<div id="my-explicit-popover" popover>
+<div id="my-explicit-popover" popover="manual">
   <p>This popover is explicitly opened and closed by separate buttons.</p>
 
   <!-- MANDATORY: Use 'hide-popover' to explicitly close the targeted popover. -->
@@ -85,9 +85,10 @@ Because Invoker Commands and Popovers are not yet universally supported, you MUS
 ### Polyfilling Invoker Commands
 
 MANDATORY: Feature detect support by checking for the `commandForElement` property on the `HTMLButtonElement` prototype. Do NOT check the window or document object. You MUST dynamically import the polyfill only when the native feature is missing. DO NOT unconditionally load the polyfill.
+Mandatory: Listen for the 'command' event directly on the target element because the native 'command' event does not bubble.
 
-**Option 1: Using a package manager (e.g., npm)**
-Install the polyfill in your project (`npm install invokers-polyfill`).
+**Option 1: Using a bundler**
+Install the polyfill via npm (`npm install invokers-polyfill`). This approach is for projects using a bundler (like Vite or Webpack) or import maps. For all other setups, use the CDN option below.
 
 ```javascript
 // MANDATORY: Feature detect 'commandForElement' on HTMLButtonElement.prototype.
@@ -97,32 +98,32 @@ if (!('commandForElement' in HTMLButtonElement.prototype)) {
 }
 ```
 
-**Option 2: Manual installation without npm**
-If you are not using a package manager, dynamically import the polyfill directly from a CDN (such as unpkg) inside a `<script type="module">`.
+**Option 2: Using a CDN**
+For projects without a bundler, dynamically import the polyfill directly from a CDN inside a `<script type="module">`.
 
 ```html
 <script type="module">
   // MANDATORY: Feature detect 'commandForElement' on HTMLButtonElement.prototype.
   // Conditionally load the invokers-polyfill from a CDN only in browsers lacking native support.
   if (!('commandForElement' in HTMLButtonElement.prototype)) {
-    import('https://unpkg.com/invokers-polyfill@latest/invoker.min.js');
+    import('https://esm.run/invokers-polyfill');
   }
 </script>
 ```
 
 **Invokers Polyfill Limitations**
-Unlike the native Invoker Commands API, `invokers-polyfill` does not automatically handle ARIA attributes (such as `aria-expanded`) on the command button.
+MANDATORY: This polyfill does not handle the ARIA states (e.g., `aria-expanded`) of the command button the way native browsers do. You are strongly encouraged to handle these states yourself to ensure your site is fully accessible.
 
-MANDATORY: You MUST manually manage these ARIA states to ensure your site remains fully accessible to screen readers in browsers relying on the polyfill.
+{{ INCLUDE("../declarative-button-actions/guide.md#fallback-strategies") }}
 
 ### Polyfilling the Popover Attribute
 
 To support the `popover` attribute in older browsers, use the `@oddbird/popover-polyfill`.
 
 MANDATORY: Feature detect popover support by checking for the `popover` property on the `HTMLElement` prototype. Conditionally initialize the polyfill only if native support is missing.
 
-**Option 1: Using a package manager**
-Install the package (`npm install @oddbird/popover-polyfill`).
+**Option 1: Using a bundler**
+Install the package via npm (`npm install @oddbird/popover-polyfill`). This method requires a bundler or import maps to resolve the module path.
 
 ```javascript
 // MANDATORY: Feature detect 'popover' on HTMLElement.prototype.
@@ -133,8 +134,8 @@ if (!('popover' in HTMLElement.prototype)) {
 }
 ```
 
-**Option 2: Manual installation without npm**
-If you are not using a package manager, dynamically import the polyfill directly from a CDN (such as unpkg) inside a `<script type="module">`.
+**Option 2: Using a CDN**
+For projects without a bundler, dynamically import the polyfill directly from a CDN inside a `<script type="module">`.
 
 ```html
 <script type="module">