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

package/components/combobox/dist/registered.js

@@ -4158,7 +4158,7 @@ function applyKeyboardStrategy(component, strategy, options = {}) {
   });
 }
 
-var styleCss$2$1 = 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$1 = 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$1 = 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)}`;
 
@@ -4789,7 +4789,7 @@ let AuroHelpText$2 = class AuroHelpText extends LitElement {
   }
 };
 
-var formkitVersion$2 = '202606081518';
+var formkitVersion$2 = '202606081833';
 
 let AuroElement$2 = class AuroElement extends LitElement {
   static get properties() {
@@ -4969,6 +4969,7 @@ class AuroDropdown extends AuroElement$2 {
   _intializeDefaults() {
     this.appearance = 'default';
     this.chevron = false;
+    this.desktopModal = false;
     this.disabled = false;
     this.disableKeyboardHandling = false;
     this.error = false;
@@ -5149,6 +5150,14 @@ class AuroDropdown extends AuroElement$2 {
         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.
        */
@@ -5436,6 +5445,15 @@ class AuroDropdown extends AuroElement$2 {
 
   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();
@@ -5463,19 +5481,45 @@ class AuroDropdown extends AuroElement$2 {
       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();
+      }
     }
   }
 
@@ -5485,8 +5529,14 @@ class AuroDropdown extends AuroElement$2 {
    * @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();
@@ -5585,19 +5635,194 @@ class AuroDropdown extends AuroElement$2 {
    * @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;
     }
   }
 
@@ -5836,6 +6061,7 @@ class AuroDropdown extends AuroElement$2 {
           shape="${this.shape}"
           ?data-show="${this.isPopoverVisible}"
           ?isfullscreen="${this.isBibFullscreen}"
+          ?desktopmodal="${this.desktopModal}"
           .dialogLabel="${this.bibDialogLabel}"
           ${ref(this.bibElement)}
           >
@@ -18040,7 +18266,7 @@ let AuroHelpText$1 = class AuroHelpText extends LitElement {
   }
 };
 
-var formkitVersion$1 = '202606081518';
+var formkitVersion$1 = '202606081833';
 
 // Copyright (c) 2025 Alaska Airlines. All right reserved. Licensed under the Apache-2.0 license
 // See LICENSE in the project root for license information.
@@ -19046,6 +19272,14 @@ class AuroBibtemplate extends LitElement {
       large: {
         type: Boolean,
         reflect: true
+      },
+
+      /**
+       * If declared, the footer slot will be rendered even when not in fullscreen mode.
+       */
+      showFooter: {
+        type: Boolean,
+        reflect: true
       }
     };
   }
@@ -19148,7 +19382,7 @@ class AuroBibtemplate extends LitElement {
           <slot></slot>
         </div>
 
-      ${this.isFullscreen ? html`
+      ${this.isFullscreen || this.showFooter ? html`
         <div id="footerContainer">
           <slot name="footer"></slot>
         </div>` : null}
@@ -19157,7 +19391,7 @@ class AuroBibtemplate extends LitElement {
   }
 }
 
-var formkitVersion = '202606081518';
+var formkitVersion = '202606081833';
 
 var styleCss$1 = css`.util_displayInline{display:inline}.util_displayInlineBlock{display:inline-block}.util_displayBlock{display:block}.util_displayFlex{display:flex}.util_displayHidden{display:none}.util_displayHiddenVisually{position:absolute;overflow:hidden;clip:rect(1px, 1px, 1px, 1px);width:1px;height:1px;padding:0;border:0}:host{display:block;text-align:left}:host [auro-dropdown]{--ds-auro-dropdown-trigger-background-color: transparent}:host #inputInBib::part(wrapper){box-shadow:none}:host #inputInBib::part(accent-left){display:none}:host([layout*=classic]) [auro-input]{width:100%}:host([layout*=classic]) [auro-input]::part(helpText){display:none}:host([layout*=classic]) #slotHolder{display:none}`;
 

package/components/counter/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-counter | 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-counter'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/counter/demo/css-only.md

@@ -0,0 +1,184 @@
+<auro-header level="1">CSS only with native number input</auro-header>
+<p>For situations where the <code>&lt;auro-counter&gt;</code> web component cannot be used, a native HTML <code>&lt;input type="number"&gt;</code> element — optionally paired with <code>&lt;button&gt;</code> increment and decrement controls — can be styled with the Auro Design System tokens to approximate the visual appearance of <code>auro-counter</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>.counter</code> class, so the styling must be authored manually using Auro design tokens.</p>
+<auro-header level="2">Styling a native number input</auro-header>
+<p>The native number input and its associated increment/decrement buttons can be restyled with 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 layout, button shape, and value typography used by <code>auro-counter</code>.</p>
+<pre><code>@import "./node_modules/@aurodesignsystem/design-tokens/dist/tokens/CSSCustomProperties.css";
+​
+.counter {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--ds-size-200, 1rem);
+  font-family: var(--ds-font-family-default, sans-serif);
+}
+​
+.counter__button {
+  appearance: none;
+  -webkit-appearance: none;
+  width: var(--ds-size-400, 2rem);
+  height: var(--ds-size-400, 2rem);
+  border: 1px solid var(--ds-color-border-ui-default, #6e767f);
+  border-radius: 50%;
+  background-color: var(--ds-color-container-primary-default, #ffffff);
+  color: var(--ds-color-text-primary-default, #00467f);
+  font-size: var(--ds-size-300, 1.5rem);
+  line-height: 1;
+  cursor: pointer;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+}
+​
+.counter__button:focus-visible {
+  outline: 2px solid var(--ds-color-border-active-default, #01426a);
+  outline-offset: 2px;
+}
+​
+.counter__button:disabled {
+  cursor: not-allowed;
+  opacity: 0.5;
+}
+​
+.counter__value {
+  appearance: textfield;
+  -moz-appearance: textfield;
+  width: var(--ds-size-500, 2.5rem);
+  border: none;
+  background: transparent;
+  text-align: center;
+  font-size: var(--ds-size-300, 1.5rem);
+  color: var(--ds-color-text-primary-default, #2a2a2a);
+}
+​
+.counter__value::-webkit-outer-spin-button,
+.counter__value::-webkit-inner-spin-button {
+  -webkit-appearance: none;
+  margin: 0;
+}</code></pre>
+<auro-header level="3">Basic counter</auro-header>
+<p>Wrap a native <code>&lt;input type="number"&gt;</code> with two <code>&lt;button&gt;</code> elements and a <code>&lt;label&gt;</code> for an accessible name:</p>
+<pre><code>&lt;div class="counter"&gt;
+  &lt;label for="passengers"&gt;Passengers&lt;/label&gt;
+  &lt;button type="button" class="counter__button" aria-label="Decrease passengers"&gt;&minus;&lt;/button&gt;
+  &lt;input id="passengers" class="counter__value" type="number" min="0" max="9" step="1" value="0" /&gt;
+  &lt;button type="button" class="counter__button" aria-label="Increase passengers"&gt;+&lt;/button&gt;
+&lt;/div&gt;</code></pre>
+<auro-header level="3">Group of counters</auro-header>
+<p>Use a <code>&lt;fieldset&gt;</code> and <code>&lt;legend&gt;</code> to give the group an accessible name. The buttons require custom JavaScript to update each input's value:</p>
+<pre><code>&lt;fieldset&gt;
+  &lt;legend&gt;Travelers&lt;/legend&gt;
+  &lt;div class="counter"&gt;
+    &lt;label for="adults"&gt;Adults&lt;/label&gt;
+    &lt;button type="button" class="counter__button" aria-label="Decrease adults"&gt;&minus;&lt;/button&gt;
+    &lt;input id="adults" class="counter__value" type="number" min="1" max="9" step="1" value="1" /&gt;
+    &lt;button type="button" class="counter__button" aria-label="Increase adults"&gt;+&lt;/button&gt;
+  &lt;/div&gt;
+  &lt;div class="counter"&gt;
+    &lt;label for="children"&gt;Children&lt;/label&gt;
+    &lt;button type="button" class="counter__button" aria-label="Decrease children"&gt;&minus;&lt;/button&gt;
+    &lt;input id="children" class="counter__value" type="number" min="0" max="8" step="1" value="0" /&gt;
+    &lt;button type="button" class="counter__button" aria-label="Increase children"&gt;+&lt;/button&gt;
+  &lt;/div&gt;
+&lt;/fieldset&gt;</code></pre>
+<auro-header level="2">What you lose without auro-counter</auro-header>
+<p>While the CSS above replicates the <strong>visual styling</strong> of <code>auro-counter</code>, the following functionality built into the <code>auro-counter</code> and <code>auro-counter-group</code> web components is <strong>not available</strong> when using plain HTML:</p>
+<auro-header level="3">Increment and decrement button wiring</auro-header>
+<p><code>auro-counter</code> exposes <code>increment()</code> and <code>decrement()</code> methods and handles all click wiring between its buttons and the displayed value. With native HTML, the <code>&lt;button&gt;</code> controls have no inherent relationship to the <code>&lt;input type="number"&gt;</code> — you must write JavaScript click handlers that read the input, apply the step, clamp to <code>min</code>/<code>max</code>, and write the new value back.</p>
+<auro-header level="3">Automatic min/max button disabling</auro-header>
+<p><code>auro-counter</code> automatically disables the decrement button when the value is at <code>min</code> and the increment button when the value is at <code>max</code>, providing a clear visual signal that further changes are not allowed. Native HTML <code>min</code> and <code>max</code> only constrain validation — the surrounding <code>&lt;button&gt;</code> controls will not disable themselves at the boundaries unless you wire that behavior yourself.</p>
+<auro-header level="3">Group-level min/max coordination</auro-header>
+<p><code>auro-counter-group</code> supports <code>min</code> and <code>max</code> properties that apply to the <em>total</em> of all child counters. When the aggregate total reaches the group maximum, every child counter's increment button is disabled; when it reaches the minimum, every decrement button is disabled. Native HTML has no equivalent — you must write JavaScript to sum each input, compare against a group total, and toggle every button accordingly.</p>
+<auro-header level="3">Coordinated value object and total</auro-header>
+<p><code>auro-counter-group</code> exposes a single <code>value</code> property as an object keyed by each counter's <code>name</code>, along with a separate <code>total</code> property for the aggregate sum. With native HTML, you must query each input individually, build the value object yourself, and recompute the total on every change.</p>
+<auro-header level="3">Spinbutton ARIA semantics</auro-header>
+<p><code>auro-counter</code> renders a <code>role="spinbutton"</code> element with <code>aria-valuemin</code>, <code>aria-valuemax</code>, <code>aria-valuenow</code>, <code>aria-valuetext</code>, and <code>aria-labelledby</code> so assistive technology announces the value as a spinbutton — the role most screen readers expect for stepper controls. A native <code>&lt;input type="number"&gt;</code> is announced as an editable text field, not a spinbutton, and there is no built-in way to relabel the surrounding +/− buttons through ARIA slots.</p>
+<auro-header level="3">Validation and error messaging</auro-header>
+<p><code>auro-counter</code> integrates with <code>@aurodesignsystem/form-validation</code> to expose a <code>validity</code> property, an <code>error</code> attribute, and a help text region that switches to an alert with <code>role="alert"</code> and <code>aria-live="assertive"</code> when invalid. Native number inputs surface browser-controlled validation tooltips that are not announced inline and cannot be styled or customized beyond <code>setCustomValidity()</code>.</p>
+<auro-header level="3">Keyboard strategy</auro-header>
+<p><code>auro-counter</code> and <code>auro-counter-group</code> install dedicated keyboard strategies that handle Arrow keys, Home/End, and tab order across the +/− buttons and the spinbutton, including ordered traversal of every counter inside a group. Native HTML gives you only the default browser behavior — Arrow keys step the number input by one, but they will not move focus between counters or coordinate Home/End across a group without custom code.</p>
+<auro-header level="3">Disabled state and propagation</auro-header>
+<p><code>auro-counter</code> exposes a single <code>disabled</code> attribute that disables both buttons and removes the spinbutton from the tab order, and <code>auro-counter-group</code> propagates appearance and theming to all child counters. With native HTML, you must apply <code>disabled</code> to each <code>&lt;input&gt;</code> and each <code>&lt;button&gt;</code> individually, or wrap them in a <code>&lt;fieldset disabled&gt;</code> with the side effects that entails.</p>
+<auro-header level="3">Dropdown layout</auro-header>
+<p><code>auro-counter-group</code> supports an <code>isDropdown</code> mode that renders the group inside an Auro dropdown with a trigger, value text, fullscreen breakpoint behavior, and configurable placement. There is no native HTML equivalent — reproducing this requires building the popover, focus management, and fullscreen transitions yourself.</p>
+<auro-header level="3">Form integration events</auro-header>
+<p><code>auro-counter</code> dispatches <code>input</code> events with a structured <code>detail.value</code>, and <code>auro-counter-group</code> dispatches <code>input</code> events carrying both <code>detail.total</code> and <code>detail.value</code> plus <code>auroFormElement-validated</code> events so a parent <code>auro-form</code> can coordinate validation. Native inputs emit only the standard <code>input</code> and <code>change</code> events without the structured payloads the Auro form system expects.</p>
+<auro-header level="3">Multi-brand theming</auro-header>
+<p><code>auro-counter</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 counter 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;input type="number"&gt;</code> with Auro tokens</th>
+<th><code>auro-counter</code></th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Design-system-aligned styling</td>
+<td>Manual (author-written CSS)</td>
+<td>Built-in</td>
+</tr>
+<tr>
+<td>Dark background support</td>
+<td>Manual</td>
+<td>Yes (<code>appearance="inverse"</code>)</td>
+</tr>
+<tr>
+<td>Increment/decrement button wiring</td>
+<td>Manual JavaScript</td>
+<td>Built-in <code>increment()</code>/<code>decrement()</code></td>
+</tr>
+<tr>
+<td>Auto-disable at min/max</td>
+<td>Manual</td>
+<td>Automatic per counter</td>
+</tr>
+<tr>
+<td>Group-level min/max total</td>
+<td>Not supported</td>
+<td>Built-in via <code>auro-counter-group</code></td>
+</tr>
+<tr>
+<td>Coordinated value object and total</td>
+<td>Manual aggregation</td>
+<td>Single <code>value</code> and <code>total</code></td>
+</tr>
+<tr>
+<td>Spinbutton ARIA semantics</td>
+<td>Not supported</td>
+<td><code>role="spinbutton"</code> with full ARIA</td>
+</tr>
+<tr>
+<td>Validation messages</td>
+<td>Limited to <code>setCustomValidity()</code></td>
+<td>Inline live-region error help text</td>
+</tr>
+<tr>
+<td>Keyboard strategy across group</td>
+<td>Browser default only</td>
+<td>Coordinated arrow/Home/End handling</td>
+</tr>
+<tr>
+<td>Disabled propagation</td>
+<td>Per-input and per-button</td>
+<td>Single attribute on counter or group</td>
+</tr>
+<tr>
+<td>Dropdown layout</td>
+<td>Not supported</td>
+<td><code>isDropdown</code> with fullscreen breakpoints</td>
+</tr>
+<tr>
+<td>Form validation events</td>
+<td>Not supported</td>
+<td><code>auroFormElement-validated</code></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-counter</code> and <code>auro-counter-group</code> whenever possible. Fall back to a CSS-styled native number input 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 button wiring, min/max disabling, group totals, spinbutton ARIA, and keyboard coordination yourself.</p>