@aurodesignsystem-dev/auro-formkit 0.0.0-pr1497.0 → 0.0.0-pr1497.1

package/components/dropdown/dist/registered.js

@@ -3243,7 +3243,7 @@ function applyKeyboardStrategy(component, strategy, options = {}) {
   });
 }
 
-var styleCss$2 = css`:host{position:fixed;z-index:var(--depth-tooltip, 400);display:none;isolation:isolate}:host dialog{width:auto;max-width:none;height:auto;max-height:none;padding:0;border:none;margin:0;outline:none;transform:translateZ(0)}:host dialog::backdrop{background:transparent}:host(:not([isfullscreen])) dialog{position:relative;inset:unset}:host(:not([isfullscreen])) .container.shape-box{border-radius:unset}:host(:not([isfullscreen])) .container[class*=shape-pill],:host(:not([isfullscreen])) .container[class*=shape-snowflake]{border-radius:30px}:host(:not([isfullscreen])) .container[class*=shape-rounded]{border-radius:16px}:host(:not([matchWidth])) .container{min-width:fit-content}:host([isfullscreen]){position:fixed;top:0;left:0}:host([isfullscreen]) .container{width:100dvw;max-width:none;height:100dvh;max-height:none;border-radius:unset;margin-top:0;box-shadow:unset;overscroll-behavior:contain}:host([isfullscreen]) .container::backdrop{background:var(--ds-color-background-primary, #fff)}:host(:popover-open){position:fixed;overflow:visible;padding:0;border:none;margin:0;background:transparent;inset:unset;outline:none}:host([data-show]){display:flex}:host([common]:not([isfullscreen])) .container,:host([rounded]:not([isfullscreen])) .container{border-radius:var(--ds-border-radius, 0.375rem)}:host([common][isfullscreen]) .container,:host([rounded][isfullscreen]) .container{border-radius:unset;box-shadow:unset}.container{display:inline-block;overflow:auto;box-sizing:border-box;border-radius:var(--ds-border-radius, 0.375rem);margin:var(--ds-size-50, 0.25rem) 0}.util_displayHiddenVisually{position:absolute;overflow:hidden;width:1px;height:1px;padding:0;border:0;margin:-1px;clip-path:inset(50%);white-space:nowrap}`;
+var styleCss$2 = css`:host{position:fixed;z-index:var(--depth-tooltip, 400);display:none;isolation:isolate}:host dialog{width:auto;max-width:none;height:auto;max-height:none;padding:0;border:none;margin:0;outline:none;transform:translateZ(0)}:host dialog::backdrop{background:transparent}:host(:not([isfullscreen])) dialog{position:relative;inset:unset}:host(:not([isfullscreen])) .container.shape-box{border-radius:unset}:host(:not([isfullscreen])) .container[class*=shape-pill],:host(:not([isfullscreen])) .container[class*=shape-snowflake]{border-radius:30px}:host(:not([isfullscreen])) .container[class*=shape-rounded]{border-radius:16px}:host([desktopmodal]:popover-open)::backdrop{background:transparent}:host(:not([matchWidth])) .container{min-width:fit-content}:host([isfullscreen]){position:fixed;top:0;left:0}:host([isfullscreen]) .container{width:100dvw;max-width:none;height:100dvh;max-height:none;border-radius:unset;margin-top:0;box-shadow:unset;overscroll-behavior:contain}:host([isfullscreen]) .container::backdrop{background:var(--ds-color-background-primary, #fff)}:host(:popover-open){position:fixed;overflow:visible;padding:0;border:none;margin:0;background:transparent;inset:unset;outline:none}:host([data-show]){display:flex}:host([common]:not([isfullscreen])) .container,:host([rounded]:not([isfullscreen])) .container{border-radius:var(--ds-border-radius, 0.375rem)}:host([common][isfullscreen]) .container,:host([rounded][isfullscreen]) .container{border-radius:unset;box-shadow:unset}.container{display:inline-block;overflow:auto;box-sizing:border-box;border-radius:var(--ds-border-radius, 0.375rem);margin:var(--ds-size-50, 0.25rem) 0}.util_displayHiddenVisually{position:absolute;overflow:hidden;width:1px;height:1px;padding:0;border:0;margin:-1px;clip-path:inset(50%);white-space:nowrap}`;
 
 var colorCss$2 = css`.container{background-color:var(--ds-auro-dropdownbib-container-color);box-shadow:var(--ds-auro-dropdownbib-boxshadow-color);color:var(--ds-auro-dropdownbib-text-color)}`;
 
@@ -3874,7 +3874,7 @@ class AuroHelpText extends LitElement {
   }
 }
 
-var formkitVersion = '202606081518';
+var formkitVersion = '202606081833';
 
 class AuroElement extends LitElement {
   static get properties() {
@@ -4054,6 +4054,7 @@ class AuroDropdown extends AuroElement {
   _intializeDefaults() {
     this.appearance = 'default';
     this.chevron = false;
+    this.desktopModal = false;
     this.disabled = false;
     this.disableKeyboardHandling = false;
     this.error = false;
@@ -4234,6 +4235,14 @@ class AuroDropdown extends AuroElement {
         reflect: true
       },
 
+      /**
+       * If declared, the dropdown will behave as a modal dialog when in a desktop viewport size.
+       */
+      desktopModal: {
+        type: Boolean,
+        reflect: true
+      },
+
       /**
        * If declared, the dropdown will only show by calling the API .show() public method.
        */
@@ -4521,6 +4530,15 @@ class AuroDropdown extends AuroElement {
 
   disconnectedCallback() {
     super.disconnectedCallback();
+    this._clearPageInert();
+    if (this._bibTabHandler) {
+      this.removeEventListener('keydown', this._bibTabHandler);
+      this._bibTabHandler = undefined;
+    }
+    if (this.focusTrap) {
+      this.focusTrap.disconnect();
+      this.focusTrap = undefined;
+    }
     if (this.floater) {
       this.floater.hideBib('disconnect');
       this.floater.disconnect();
@@ -4548,19 +4566,45 @@ class AuroDropdown extends AuroElement {
       if (this.isPopoverVisible) {
         // Fullscreen: use showModal() for native accessibility (inert outside, focus trap)
         // Desktop: use show() for Floating UI positioning + FocusTrap for focus management
-        const useModal = this.isBibFullscreen;
-        this.bibElement.value.open(useModal);
+        this.bibElement.value.open(this.isBibFullscreen);
+        this.updateFocusTrap();
+
+        // Desktop modal: make siblings inert so content outside is not interactive
+        if (this.desktopModal && !this.isBibFullscreen) {
+          this._setPageInert();
+        }
       } else {
         this.bibElement.value.close();
+        this._clearPageInert();
       }
     }
 
     // When fullscreen strategy changes while open, re-open dialog with correct mode
     // (e.g. resizing from desktop → mobile while dropdown is open)
     if (changedProperties.has('isBibFullscreen') && this.isPopoverVisible && this.bibElement.value) {
-      const useModal = this.isBibFullscreen;
       this.bibElement.value.close();
-      this.bibElement.value.open(useModal);
+      this.bibElement.value.open(this.isBibFullscreen);
+
+      // Re-initialize focus management for the new strategy
+      this.updateFocusTrap();
+
+      // Toggle inert: desktop modal needs it, fullscreen showModal() handles it natively
+      if (this.desktopModal && !this.isBibFullscreen) {
+        this._setPageInert();
+      } else {
+        this._clearPageInert();
+      }
+    }
+
+    // Handle desktopModal toggled while the dropdown is already open.
+    // Re-initialize focus trapping and page inert state to match the new mode.
+    if (changedProperties.has('desktopModal') && this.isPopoverVisible && !this.isBibFullscreen) {
+      this.updateFocusTrap();
+      if (this.desktopModal) {
+        this._setPageInert();
+      } else {
+        this._clearPageInert();
+      }
     }
   }
 
@@ -4570,8 +4614,14 @@ class AuroDropdown extends AuroElement {
    * @param {CustomEvent} event - The custom event that contains the dropdown toggle information.
    */
   handleDropdownToggle(event) {
-    this.updateFocusTrap();
     this.isPopoverVisible = event.detail.expanded;
+
+    // Tear down FocusTrap when closing. Creation happens in updated()
+    // after the dialog is open so getFocusableElements can find content.
+    if (!this.isPopoverVisible) {
+      this.updateFocusTrap();
+    }
+
     const eventType = event.detail.eventType || "unknown";
     if (!this.isPopoverVisible && this.hasFocus && eventType === "keydown") {
       this.trigger.focus();
@@ -4670,19 +4720,194 @@ class AuroDropdown extends AuroElement {
    * @private
    */
   updateFocusTrap() {
+    // Always clean up existing handlers/traps before setting up new ones
+    // to prevent duplicate listeners on repeated calls.
+    if (this._bibTabHandler) {
+      this.removeEventListener('keydown', this._bibTabHandler);
+      this._bibTabHandler = undefined;
+    }
+
+    if (this.focusTrap) {
+      this.focusTrap.disconnect();
+      this.focusTrap = undefined;
+    }
+
     if (this.isPopoverVisible) {
       if (!this.isBibFullscreen) {
-        // Desktop: show() doesn't trap focus, so use FocusTrap
-        this.focusTrap = new FocusTrap(this.bibContent);
-        this.focusTrap.focusFirstElement();
+        if (this.desktopModal) {
+          // Desktop modal: trap focus only within the bib content.
+          // Can't use FocusTrap on the bib element because keydown events
+          // from slotted content bubble through the dropdown host (light DOM),
+          // not through the bib (shadow projection target). Using FocusTrap
+          // on the dropdown would include the trigger in the tab cycle.
+          // Instead, listen for Tab on the dropdown and manually wrap focus
+          // within the bib's focusable elements.
+          this._bibTabHandler = (event) => {
+            if (event.key !== 'Tab') {
+              return;
+            }
+
+            // Collect focusable elements from the bib content.
+            const focusables = getFocusableElements(this.bibContent);
+
+            // Fallback: try from slotted content directly
+            if (!focusables.length) {
+              const slot = this.shadowRoot.querySelector('.slotContent slot');
+              const assignedNodes = slot ? slot.assignedNodes({ flatten: true }) : [];
+
+              for (const node of assignedNodes) {
+                if (node.nodeType === Node.ELEMENT_NODE) {
+                  focusables.push(...getFocusableElements(node));
+                }
+              }
+            }
+
+            if (!focusables.length) {
+              return;
+            }
+
+            event.preventDefault();
+
+            const direction = event.shiftKey ? -1 : 1; // eslint-disable-line no-magic-numbers
+
+            // Walk the active element chain through shadow roots
+            const actives = this._getActiveElements();
+
+            let idx = focusables.findIndex((el) => actives.includes(el));
+
+            if (idx === -1) { // eslint-disable-line no-magic-numbers
+              // Focus is not on a known element — move to first/last
+              idx = direction === 1 ? -1 : focusables.length; // eslint-disable-line no-magic-numbers
+            }
+
+            // Try each element in order, skipping any that can't receive focus
+            // (e.g. hidden elements, elements in collapsed sections)
+            for (let index = 0; index < focusables.length; index++) { // eslint-disable-line no-plusplus
+              let nextIdx = idx + direction;
+
+              // Wrap around
+              if (nextIdx < 0) {
+                nextIdx = focusables.length - 1;
+              } else if (nextIdx >= focusables.length) {
+                nextIdx = 0;
+              }
+
+              focusables[nextIdx].focus();
+
+              // Verify focus actually moved to the target
+              const newActives = this._getActiveElements();
+
+              if (newActives.includes(focusables[nextIdx])) {
+                return;
+              }
+
+              // Focus didn't stick — skip this element and try the next
+              idx = nextIdx;
+            }
+          };
+          this.addEventListener('keydown', this._bibTabHandler);
+
+          // Move initial focus into the bib content, matching FocusTrap behavior
+          requestAnimationFrame(() => {
+            const focusables = getFocusableElements(this.bibContent);
+            if (focusables.length) {
+              focusables[0].focus();
+            }
+          });
+        } else {
+          // Normal desktop: use FocusTrap on the bib element
+          this.focusTrap = new FocusTrap(this.bibContent);
+          this.focusTrap.focusFirstElement();
+        }
       }
       // Fullscreen: showModal() provides native focus trapping
+    }
+  }
+
+  /**
+   * Returns the chain of active (focused) elements through shadow roots.
+   * @private
+   * @returns {Array<HTMLElement>}
+   */
+  _getActiveElements() {
+    let { activeElement } = document;
+    const actives = [activeElement];
+
+    while (activeElement?.shadowRoot?.activeElement) {
+      activeElement = activeElement.shadowRoot.activeElement;
+      actives.push(activeElement);
+    }
+
+    return actives;
+  }
+
+  /**
+   * Sets `inert` on sibling elements of the dropdown's top-level host
+   * so that content outside the dropdown is not interactive while the modal is open.
+   * Walks up through shadow DOM boundaries to find the outermost host element
+   * in the light DOM, then sets `inert` on siblings at each ancestor level
+   * to ensure all page content outside the host subtree is inert.
+   * @private
+   */
+  _setPageInert() {
+    if (this._inertSiblings) {
       return;
     }
 
-    if (this.focusTrap) {
-      this.focusTrap.disconnect();
-      this.focusTrap = undefined;
+    this._inertSiblings = [];
+
+    // Walk up through shadow DOM boundaries to find the topmost host
+    // element in the light DOM. For example, if this dropdown is inside
+    // auro-datepicker's shadow DOM, we walk up to the datepicker element
+    // so we set inert on its siblings — not on the datepicker itself.
+    let host = this;
+    while (host.getRootNode() instanceof ShadowRoot) {
+      host = host.getRootNode().host;
+    }
+
+    // Walk up the ancestor chain, inerting siblings at each level
+    // to ensure the entire page outside the host subtree is inert.
+    // Uses a reference counter (data-auro-inert-count) so multiple
+    // simultaneous modal dropdowns share inert state safely.
+    let current = host;
+    while (current.parentElement) {
+      const parent = current.parentElement;
+      for (const sibling of parent.children) {
+        if (sibling !== current) {
+          const count = parseInt(sibling.dataset.auroInertCount || '0', 10);
+          if (count === 0) {
+            sibling.dataset.auroInertWas = sibling.inert ? 'true' : 'false';
+          }
+          sibling.dataset.auroInertCount = String(count + 1);
+          sibling.inert = true;
+          this._inertSiblings.push(sibling);
+        }
+      }
+      current = parent;
+    }
+  }
+
+  /**
+   * Restores `inert` state on siblings that were tracked by `_setPageInert`.
+   * Uses reference counting so inert is only cleared when the last modal
+   * dropdown releases a given element. Preserves the original inert state
+   * so externally-inerted elements are not inadvertently re-enabled.
+   * @private
+   */
+  _clearPageInert() {
+    if (this._inertSiblings) {
+      for (const sibling of this._inertSiblings) {
+        const count = parseInt(sibling.dataset.auroInertCount || '1', 10) - 1;
+        if (count <= 0) {
+          const wasInert = sibling.dataset.auroInertWas === 'true';
+          delete sibling.dataset.auroInertCount;
+          delete sibling.dataset.auroInertWas;
+          sibling.inert = wasInert;
+        } else {
+          sibling.dataset.auroInertCount = String(count);
+        }
+      }
+      this._inertSiblings = undefined;
     }
   }
 
@@ -4921,6 +5146,7 @@ class AuroDropdown extends AuroElement {
           shape="${this.shape}"
           ?data-show="${this.isPopoverVisible}"
           ?isfullscreen="${this.isBibFullscreen}"
+          ?desktopmodal="${this.desktopModal}"
           .dialogLabel="${this.bibDialogLabel}"
           ${ref(this.bibElement)}
           >

package/components/form/demo/css-only.html

@@ -0,0 +1,57 @@
+<!--
+  Copyright (c) Alaska Air. All right reserved. Licensed under the Apache-2.0 license
+  See LICENSE in the project root for license information.
+
+  HTML in this document is standardized and NOT to be edited.
+  All demo code should be added/edited in ./demo/css-only.md
+
+  With the exception of adding custom elements if needed for the demo.
+
+  ----------------------- DO NOT EDIT -----------------------------
+
+-->
+
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Auro Web Component Demo | auro-form | CSS only</title>
+
+    <!-- highlight.js Stylesheet -->
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.9.0/build/styles/github.min.css"/>
+
+    <!-- Legacy reference is still needed to support auro-form's use of legacy token values at this time -->
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/design-tokens@latest/dist/legacy/auro-classic/CSSCustomProperties.css"/>
+
+    <!-- Design Token Alaska Theme -->
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/design-tokens@latest/dist/themes/alaska/CSSCustomProperties--alaska.min.css"/>
+
+    <!-- Webcore Stylesheet Alaska Theme -->
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/webcorestylesheets@latest/dist/bundled/themes/alaska.global.min.css" />
+
+    <!-- Demo Specific Styles -->
+    <link rel="stylesheet" type="text/css" href="./styles.min.css" />
+    <style>
+      table {
+        --ds-color-container-secondary-default: transparent;
+      }
+
+      tr:not(:last-of-type) {
+        border-bottom: 1px solid var(--ds-color-border-tertiary-default);
+      }
+    </style>
+  </head>
+  <body class="auro-markdown">
+    <main></main>
+
+    <script type="module">
+      import { renderPage } from './demo-support.min.js';
+      await renderPage('./css-only.md');
+    </script>
+
+    <!-- If additional elements are needed for the demo, add them here. -->
+    <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-header@latest/+esm" type="module"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-hyperlink@latest/+esm" type="module"></script>
+  </body>
+</html>

package/components/form/demo/css-only.md

@@ -0,0 +1,156 @@
+<auro-header level="1">CSS only with native form</auro-header>
+<p>For situations where the <code>&lt;auro-form&gt;</code> web component cannot be used, a native HTML <code>&lt;form&gt;</code> element can be styled with the Auro Design System tokens to approximate the layout and spacing used by <code>auro-form</code>. Unlike <auro-hyperlink href="https://auro.alaskaair.com/components/auro/hyperlink/css-only" target="_blank">auro-hyperlink</auro-hyperlink>, <auro-hyperlink href="https://alaskaairlines.github.io/WebCoreStyleSheets/" target="_blank">Web Core Style Sheets</auro-hyperlink> does not provide a prebuilt <code>.form</code> class. The native <code>&lt;form&gt;</code> element provides the structural container and browser-native constraint validation, but it does not provide the cross-field coordination that <code>auro-form</code> adds.</p>
+<auro-header level="2">Styling a native form</auro-header>
+<p>The native form can be laid out using the Auro design tokens published by <auro-hyperlink href="https://alaskaairlines.github.io/WebCoreStyleSheets/" target="_blank">@aurodesignsystem/design-tokens</auro-hyperlink>. The pattern below replicates the spacing and rhythm used by <code>auro-form</code>.</p>
+<pre><code>@import "./node_modules/@aurodesignsystem/design-tokens/dist/tokens/CSSCustomProperties.css";
+​
+.form {
+  display: flex;
+  flex-direction: column;
+  gap: var(--ds-size-300, 1.5rem);
+  padding: var(--ds-size-400, 2rem);
+}
+​
+.form fieldset {
+  display: flex;
+  flex-direction: column;
+  gap: var(--ds-size-200, 1rem);
+  border: 0;
+  padding: 0;
+  margin: 0;
+}
+​
+.form legend {
+  padding: 0;
+  margin-bottom: var(--ds-size-100, 0.5rem);
+}
+​
+.form .actions {
+  display: flex;
+  gap: var(--ds-size-200, 1rem);
+  margin-top: var(--ds-size-200, 1rem);
+}</code></pre>
+<auro-header level="3">Basic form</auro-header>
+<p>Apply the <code>.form</code> class to a native <code>&lt;form&gt;</code> element and rely on the browser's built-in submit and reset behavior:</p>
+<pre><code>&lt;form class="form" action="/subscribe" method="post"&gt;
+  &lt;label&gt;
+    Email
+    &lt;input type="email" name="email" required /&gt;
+  &lt;/label&gt;
+  &lt;div class="actions"&gt;
+    &lt;button type="submit"&gt;Submit&lt;/button&gt;
+    &lt;button type="reset"&gt;Reset&lt;/button&gt;
+  &lt;/div&gt;
+&lt;/form&gt;</code></pre>
+<auro-header level="3">Form with grouped fields</auro-header>
+<p>Use a <code>&lt;fieldset&gt;</code> and <code>&lt;legend&gt;</code> to give grouped fields an accessible name:</p>
+<pre><code>&lt;form class="form"&gt;
+  &lt;fieldset&gt;
+    &lt;legend&gt;Contact information&lt;/legend&gt;
+    &lt;label&gt;First name &lt;input type="text" name="firstName" required /&gt;&lt;/label&gt;
+    &lt;label&gt;Last name &lt;input type="text" name="lastName" required /&gt;&lt;/label&gt;
+    &lt;label&gt;Email &lt;input type="email" name="email" required /&gt;&lt;/label&gt;
+  &lt;/fieldset&gt;
+  &lt;div class="actions"&gt;
+    &lt;button type="submit"&gt;Submit&lt;/button&gt;
+    &lt;button type="reset"&gt;Reset&lt;/button&gt;
+  &lt;/div&gt;
+&lt;/form&gt;</code></pre>
+<auro-header level="2">What you lose without auro-form</auro-header>
+<p>While the CSS above replicates the <strong>visual layout</strong> of <code>auro-form</code>, the following functionality built into the <code>auro-form</code> web component is <strong>not available</strong> when using a plain HTML <code>&lt;form&gt;</code>:</p>
+<auro-header level="3">Child element registration</auro-header>
+<p><code>auro-form</code> automatically discovers and registers its named Auro form-element children (<code>auro-input</code>, <code>auro-select</code>, <code>auro-datepicker</code>, <code>auro-combobox</code>, <code>auro-checkbox-group</code>, <code>auro-radio-group</code>, <code>auro-counter-group</code>) on slot change and via a <code>MutationObserver</code>, so dynamically added or removed fields are tracked without manual wiring. A native <code>&lt;form&gt;</code> only exposes built-in form-associated elements through <code>form.elements</code> — custom elements and dynamically inserted controls require custom registration logic.</p>
+<auro-header level="3">Aggregated value snapshot</auro-header>
+<p><code>auro-form</code> exposes a <code>value</code> getter that returns a single key-value object of every named child's current value, including array values from range datepickers and grouped controls. With a native <code>&lt;form&gt;</code>, you must either use <code>FormData</code> (which does not understand custom elements) or query each control individually and assemble the values yourself.</p>
+<auro-header level="3">Aggregated validity state</auro-header>
+<p><code>auro-form</code> exposes a single <code>validity</code> getter that returns <code>'valid'</code>, <code>'invalid'</code>, or <code>null</code> based on the validity of every required and interacted-with child. Native forms expose <code>form.checkValidity()</code> and <code>form.reportValidity()</code>, but those only consider built-in form-associated elements and do not include custom elements like <code>auro-input</code> or <code>auro-datepicker</code>.</p>
+<auro-header level="3">Initial-state tracking</auro-header>
+<p><code>auro-form</code> tracks an <code>isInitialState</code> flag that is <code>true</code> until any child has been interacted with or had its value changed. Native forms have no equivalent — you must implement change tracking yourself to know whether the form is in a pristine state.</p>
+<auro-header level="3">auroFormElement-validated event aggregation</auro-header>
+<p><code>auro-form</code> listens for <code>auroFormElement-validated</code> events from every registered child and updates its aggregated validity state in response. A native <code>&lt;form&gt;</code> does not listen to or interpret these events, so per-field validation reported by Auro components is not rolled up into a single form-level validity result.</p>
+<auro-header level="3">Submit coordination</auro-header>
+<p><code>auro-form</code> intercepts clicks on child submit buttons (<code>&lt;button type="submit"&gt;</code> or <code>&lt;auro-button type="submit"&gt;</code>), forces validation on every registered child, waits for validation to settle, and only then fires a <code>submit</code> event with <code>detail.value</code> containing the full form snapshot. A native <code>&lt;form&gt;</code> submit fires before custom-element validation can complete and does not surface a structured value object.</p>
+<auro-header level="3">Reset coordination</auro-header>
+<p><code>auro-form</code> intercepts clicks on child reset buttons, calls <code>reset()</code> on every registered child, reinitializes its state, and fires a <code>reset</code> event with <code>detail.previousValue</code> containing the values captured before the reset. A native <code>&lt;form&gt;</code> reset only restores default values on built-in form controls and does not call any custom reset method on web components.</p>
+<auro-header level="3">Submit and reset button disabling</auro-header>
+<p><code>auro-form</code> automatically disables submit buttons while the form is in its initial state or invalid, and disables reset buttons while the form is in its initial state. With a native <code>&lt;form&gt;</code>, you must wire up your own change listeners to toggle the <code>disabled</code> attribute on action buttons.</p>
+<auro-header level="3">Enter-to-submit handling</auro-header>
+<p><code>auro-form</code> listens for the Enter key on its registered children and triggers a coordinated submit, while skipping textarea-style fields so they can accept newlines. A native <code>&lt;form&gt;</code> submits on Enter only when the focused control is a form-associated element the browser recognizes, which excludes most custom elements.</p>
+<auro-header level="3">Mixed Auro and native child support</auro-header>
+<p><code>auro-form</code> recognizes its named Auro children and coordinates them as a single form, while still allowing native elements to live alongside them in markup. A native <code>&lt;form&gt;</code> treats Auro custom elements as opaque DOM nodes and provides no cross-field coordination between them.</p>
+<auro-header level="3">Multi-brand theming</auro-header>
+<p><code>auro-form</code> consumes Auro design tokens through its component logic, so it automatically picks up brand-specific theming when token packages are swapped. A CSS-only form is tied to whichever tokens were imported at author time and will not respond to runtime theme switching the way the web component does.</p>
+<auro-header level="2">Summary</auro-header>
+<table>
+<thead>
+<tr>
+<th>Feature</th>
+<th>Native <code>&lt;form&gt;</code> with Auro tokens</th>
+<th><code>auro-form</code></th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Design-system-aligned layout</td>
+<td>Manual (author-written CSS)</td>
+<td>Built-in</td>
+</tr>
+<tr>
+<td>Child element registration</td>
+<td>Built-ins only via <code>form.elements</code></td>
+<td>Automatic, including dynamic children</td>
+</tr>
+<tr>
+<td>Aggregated value snapshot</td>
+<td>Manual or <code>FormData</code> (no custom elements)</td>
+<td>Single <code>value</code> getter</td>
+</tr>
+<tr>
+<td>Aggregated validity state</td>
+<td>Built-ins only via <code>checkValidity()</code></td>
+<td>Single <code>validity</code> getter across all children</td>
+</tr>
+<tr>
+<td>Initial-state tracking</td>
+<td>Manual</td>
+<td><code>isInitialState</code> getter</td>
+</tr>
+<tr>
+<td><code>auroFormElement-validated</code> aggregation</td>
+<td>Not supported</td>
+<td>Built-in</td>
+</tr>
+<tr>
+<td>Submit coordination</td>
+<td>Native submit fires before custom-element validation</td>
+<td>Forces validation, then fires <code>submit</code> with full value</td>
+</tr>
+<tr>
+<td>Reset coordination</td>
+<td>Resets built-ins only</td>
+<td>Calls <code>reset()</code> on every child; emits previous value</td>
+</tr>
+<tr>
+<td>Submit/reset button disabling</td>
+<td>Manual</td>
+<td>Automatic based on state and validity</td>
+</tr>
+<tr>
+<td>Enter-to-submit on custom elements</td>
+<td>Not supported</td>
+<td>Built-in (skips textarea)</td>
+</tr>
+<tr>
+<td>Mixed Auro and native children</td>
+<td>Native treats Auro elements as opaque</td>
+<td>Coordinated as a single form</td>
+</tr>
+<tr>
+<td>Multi-brand theming</td>
+<td>Static (import-time tokens)</td>
+<td>Full (design tokens + component logic)</td>
+</tr>
+</tbody>
+</table>
+<auro-header level="2">Recommendation</auro-header>
+<p>Use <code>auro-form</code> whenever possible. Fall back to a CSS-styled native <code>&lt;form&gt;</code> only in environments where custom elements are not supported or when integrating with third-party systems that require plain HTML — and be prepared to reimplement child registration, aggregated value and validity, submit and reset coordination, and action-button state management yourself.</p>