@aurodesignsystem-dev/auro-formkit 0.0.0-pr1475.6 → 0.0.0-pr1477.1

package/components/input/demo/why-input.md

@@ -1,121 +0,0 @@
-<auro-header level="1" id="overview">Why auro-input?</auro-header>
-<p>The native <code>&lt;input&gt;</code> element is the workhorse of HTML forms, but it has significant limitations in styling, validation messaging, input formatting, and accessibility. <code>auro-input</code> addresses these while remaining a drop-in upgrade for common input types.</p>
-<auro-header level="2" id="accessibility">Accessibility</auro-header>
-<p>Native inputs require manual <code>&lt;label&gt;</code> wiring, have no standard pattern for error announcements, and provide no built-in clear or show/hide password controls.</p>
-<p><code>auro-input</code> provides:</p>
-<ul>
-<li><strong>Automatic label binding</strong> — The label slot is automatically associated with the input. No <code>for</code>/<code>id</code> wiring required.</li>
-<li><strong>Dynamic label positioning</strong> — Labels float above the input when focused or populated, providing context without consuming space.</li>
-<li><strong>Clear button</strong> — An accessible clear button appears when the input has a value, with a customizable ARIA label via the <code>ariaLabel.clear</code> slot.</li>
-<li><strong>Password toggle</strong> — For <code>type="password"</code>, a show/hide toggle is built in with customizable ARIA labels for both states (<code>ariaLabel.password.show</code>, <code>ariaLabel.password.hide</code>).</li>
-<li><strong>Validation announcements</strong> — Error messages display in help text with appropriate ARIA roles so screen readers announce validity changes.</li>
-</ul>
-<auro-header level="2" id="inputMaskingAndFormatting">Input masking and formatting</auro-header>
-<p>Native inputs have no concept of input masks. Building formatted input (phone numbers, dates, credit card numbers) requires third-party libraries and manual integration.</p>
-<p><code>auro-input</code> includes IMask integration:</p>
-<ul>
-<li><strong>Format attribute</strong> — Set <code>format="(###) ###-####"</code> for phone numbers, <code>format="mm/dd/yyyy"</code> for dates, or any custom pattern.</li>
-<li><strong>Auto-formatting</strong> — Characters are formatted as the user types, with cursor position preserved.</li>
-<li><strong>Date formats</strong> — Supports <code>mm/dd/yyyy</code>, <code>dd/mm/yyyy</code>, <code>yyyy-mm-dd</code> with automatic conversion.</li>
-</ul>
-<auro-header level="2" id="creditCardDetection">Credit card detection</auro-header>
-<p>There is no native way to detect a credit card type from input, apply the correct formatting mask, or display the appropriate card icon.</p>
-<p><code>auro-input</code> with <code>type="credit-card"</code> provides:</p>
-<ul>
-<li><strong>Auto-detection</strong> — Identifies Visa, Mastercard, American Express, Discover, Diners Club, and Alaska Airlines cards from the first digits typed.</li>
-<li><strong>Dynamic formatting</strong> — Applies the correct digit grouping (e.g., 4-4-4-4 for Visa, 4-6-5 for Amex).</li>
-<li><strong>Card icon</strong> — Displays the detected card brand icon automatically.</li>
-<li><strong>Luhn validation</strong> — Validates the card number using the Luhn algorithm.</li>
-</ul>
-<auro-header level="2" id="validation">Validation</auro-header>
-<p>Native input validation provides <code>required</code>, <code>min</code>, <code>max</code>, <code>minlength</code>, <code>maxlength</code>, and <code>pattern</code>, but error messages are browser-controlled and cannot be customized.</p>
-<p><code>auro-input</code> provides:</p>
-<ul>
-<li>Custom error messages for every validity state: <code>setCustomValidityValueMissing</code>, <code>setCustomValidityRangeOverflow</code>, <code>setCustomValidityRangeUnderflow</code>, <code>setCustomValidityTooLong</code>, <code>setCustomValidityTooShort</code>, <code>setCustomValidityBadInput</code>, <code>setCustomValidityCustomError</code>, <code>setCustomValidityForType</code></li>
-<li>Type-specific validation (email format, credit card Luhn, phone format, date format)</li>
-<li>Validation timing control: on blur (default), on every input (<code>validateOnInput</code>), or disabled (<code>noValidate</code>)</li>
-<li>Programmatic vs. user input distinction — the component tracks whether a value change was user-initiated or programmatic</li>
-</ul>
-<auro-header level="2" id="displayValueMasking">Display value masking</auro-header>
-<p>Native inputs show the raw value at all times. There is no way to display a formatted or alternative representation when the input is not focused.</p>
-<p><code>auro-input</code> supports a <code>displayValue</code> slot that shows custom HTML when the input is blurred, hiding the raw value. This is useful for displaying formatted currency, masked account numbers, or rich content while keeping the underlying value clean for submission.</p>
-<auro-header level="2" id="layoutOptions">Layout options</auro-header>
-<p>Native inputs have a single visual presentation controlled by browser defaults.</p>
-<p><code>auro-input</code> offers:</p>
-<ul>
-<li><strong>Three layouts</strong> — Classic (floating label), emphasized (prominent label), and snowflake (custom positioning)</li>
-<li><strong>Shape variants</strong> — Box, pill, pill-left, pill-right for different visual contexts</li>
-<li><strong>Nested mode</strong> — Removes borders and hides help/error text for embedding inside other components</li>
-<li><strong>Simple mode</strong> — Borderless variant for inline use</li>
-</ul>
-<auro-header level="2" id="designSystemIntegration">Design system integration</auro-header>
-<p>Native input styling varies across browsers and requires extensive CSS resets to normalize.</p>
-<p><code>auro-input</code> is built with the Auro Design System:</p>
-<ul>
-<li>Consistent visual language across all browsers and platforms</li>
-<li>Light and dark theme support (<code>appearance</code>)</li>
-<li>CSS <code>::part()</code> selectors for granular styling (<code>wrapper</code>, <code>label</code>, <code>input</code>, <code>helpText</code>, <code>accentIcon</code>, <code>iconContainer</code>, <code>displayValue</code>)</li>
-<li>Design token integration for colors, spacing, and typography</li>
-</ul>
-<auro-header level="2" id="summary">Summary</auro-header>
-<table>
-<thead>
-<tr>
-<th>Capability</th>
-<th><code>&lt;input&gt;</code></th>
-<th><code>auro-input</code></th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td>Automatic label binding</td>
-<td>No (<code>for</code>/<code>id</code> required)</td>
-<td>Yes (slot-based)</td>
-</tr>
-<tr>
-<td>Input masking</td>
-<td>No</td>
-<td>Built-in (IMask)</td>
-</tr>
-<tr>
-<td>Credit card detection</td>
-<td>No</td>
-<td>Auto-detect with icon and formatting</td>
-</tr>
-<tr>
-<td>Custom validation messages</td>
-<td>Browser-controlled</td>
-<td>Per-constraint custom messages</td>
-</tr>
-<tr>
-<td>Clear button</td>
-<td>No</td>
-<td>Built-in with ARIA label</td>
-</tr>
-<tr>
-<td>Password show/hide</td>
-<td>No</td>
-<td>Built-in toggle</td>
-</tr>
-<tr>
-<td>Display value masking</td>
-<td>No</td>
-<td><code>displayValue</code> slot</td>
-</tr>
-<tr>
-<td>Multiple layouts</td>
-<td>No</td>
-<td>Classic, emphasized, snowflake</td>
-</tr>
-<tr>
-<td>Consistent cross-browser UI</td>
-<td>No</td>
-<td>Yes</td>
-</tr>
-<tr>
-<td>Theming</td>
-<td>Browser-dependent</td>
-<td>Full design system integration</td>
-</tr>
-</tbody>
-</table>

package/components/menu/demo/why-menu.html

@@ -1,57 +0,0 @@
-<!--
-  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/why-menu.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-menu | Why auro-menu</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-menu'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('./why-menu.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/menu/demo/why-menu.md

@@ -1,104 +0,0 @@
-<auro-header level="1" id="overview">Why auro-menu?</auro-header>
-<p>Native HTML has no dedicated menu component for selection lists. <code>&lt;select&gt;</code> only accepts <code>&lt;option&gt;</code> elements with plain text. Building a rich, accessible, keyboard-navigable menu with nested groups, loading states, and multi-select support requires significant custom work. <code>auro-menu</code> provides this as a composable primitive.</p>
-<auro-header level="2" id="accessibility">Accessibility</auro-header>
-<p>Custom list implementations often fail to provide correct ARIA semantics, keyboard navigation, or screen reader announcements.</p>
-<p><code>auro-menu</code> provides:</p>
-<ul>
-<li><strong>Keyboard navigation</strong> — Arrow keys move between options, Enter selects, Escape cancels, Home/End jump to the first and last options.</li>
-<li><strong>Active option tracking</strong> — The currently highlighted option is tracked programmatically, enabling <code>aria-activedescendant</code> patterns in parent components like <code>auro-select</code> and <code>auro-combobox</code>.</li>
-<li><strong>Multi-select semantics</strong> — When <code>multiSelect</code> is enabled, <code>aria-multiselectable</code> is set on the menu.</li>
-<li><strong>Loading state</strong> — <code>aria-busy</code> is set during loading, with customizable loading icon and text slots.</li>
-</ul>
-<auro-header level="2" id="richOptionContent">Rich option content</auro-header>
-<p><code>&lt;option&gt;</code> elements accept only plain text. There is no native way to add icons, descriptions, or nested structure to options.</p>
-<p><code>auro-menu</code> options support:</p>
-<ul>
-<li>Full HTML content in each option</li>
-<li>Icons alongside option text</li>
-<li>Nested submenus for hierarchical navigation</li>
-<li>Checkmark indicators for selected options (configurable via <code>noCheckmark</code>)</li>
-</ul>
-<auro-header level="2" id="multiselect">Multi-select</auro-header>
-<p>Native <code>&lt;select multiple&gt;</code> renders a fixed-height list box that is widely considered a poor user experience. There is no checkmark feedback, and the interaction model (Ctrl+click) is unintuitive.</p>
-<p><code>auro-menu</code> provides:</p>
-<ul>
-<li>Checkmark indicators for each selected option</li>
-<li>A <code>value</code> that returns a JSON-stringified array of selections</li>
-<li><code>allowDeselect</code> to toggle selections off</li>
-<li><code>selectAllMatchingOptions</code> for bulk selection operations</li>
-<li><code>clearSelection()</code> and <code>reset()</code> methods for programmatic control</li>
-</ul>
-<auro-header level="2" id="searchAndFiltering">Search and filtering</auro-header>
-<p>Native menus have no concept of filtering or highlighting matched text.</p>
-<p><code>auro-menu</code> supports:</p>
-<ul>
-<li><code>matchWord</code> to highlight matching portions of option text as the user types (used by <code>auro-combobox</code> for real-time filtering)</li>
-<li>Programmatic <code>navigateOptions(direction)</code> for keyboard-driven traversal</li>
-</ul>
-<auro-header level="2" id="loadingState">Loading state</auro-header>
-<p>Native selects have no loading pattern. When options are fetched asynchronously, there is no standard way to communicate this to the user.</p>
-<p><code>auro-menu</code> provides:</p>
-<ul>
-<li>A <code>loading</code> attribute that displays a loading indicator</li>
-<li><code>loadingIcon</code> and <code>loadingText</code> slots for custom loading UI</li>
-<li><code>auroMenu-loadingChange</code> event when the loading state changes</li>
-</ul>
-<auro-header level="2" id="composability">Composability</auro-header>
-<p><code>auro-menu</code> is designed as a building block. It is the selection engine inside:</p>
-<ul>
-<li><strong><code>auro-select</code></strong> — Dropdown selection</li>
-<li><strong><code>auro-combobox</code></strong> — Autocomplete with filtering</li>
-</ul>
-<p>This architecture means selection behavior, keyboard navigation, and ARIA semantics are consistent across all selection components.</p>
-<auro-header level="2" id="summary">Summary</auro-header>
-<table>
-<thead>
-<tr>
-<th>Capability</th>
-<th><code>&lt;select&gt;</code> / <code>&lt;option&gt;</code></th>
-<th><code>auro-menu</code></th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td>Rich HTML in options</td>
-<td>Plain text only</td>
-<td>Full HTML</td>
-</tr>
-<tr>
-<td>Nested submenus</td>
-<td>Not supported</td>
-<td>Built-in</td>
-</tr>
-<tr>
-<td>Multi-select with checkmarks</td>
-<td>Ctrl+click list box</td>
-<td>Checkmark toggle</td>
-</tr>
-<tr>
-<td>Search/filter highlighting</td>
-<td>No</td>
-<td><code>matchWord</code> attribute</td>
-</tr>
-<tr>
-<td>Loading state</td>
-<td>No</td>
-<td>Built-in with custom slots</td>
-</tr>
-<tr>
-<td>Keyboard navigation</td>
-<td>Browser-dependent</td>
-<td>Full arrow/Enter/Escape/Home/End</td>
-</tr>
-<tr>
-<td>Composable primitive</td>
-<td>No</td>
-<td>Foundation for select and combobox</td>
-</tr>
-<tr>
-<td>Deselect support</td>
-<td>No</td>
-<td><code>allowDeselect</code> attribute</td>
-</tr>
-</tbody>
-</table>