@aurodesignsystem-dev/auro-formkit 0.0.0-pr1480.9 → 0.0.0-pr1482.0

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>

package/components/menu/dist/auro-menu.context.d.ts

@@ -1,238 +0,0 @@
-export class MenuService {
-    /**
-     * CONSTRUCTOR
-     */
-    /**
-     * Creates a new MenuService instance.
-     * @param {Object} options - The options object.
-     *   @param {AuroMenu} options.host - The host element that this service will control. Required.
-     * @throws {Error} If the host is not provided.
-     */
-    constructor({ host }?: {
-        host: AuroMenu;
-    });
-    /**
-     * PROPERTIES AND GETTERS
-     */
-    /**
-     * Gets the list of registered menu options.
-     * @returns {AuroMenuOption[]}
-     */
-    get menuOptions(): AuroMenuOption[];
-    /**
-     * Gets the currently highlighted option.
-     * @returns {AuroMenuOption|null}
-     */
-    get highlightedOption(): AuroMenuOption | null;
-    /**
-     * Gets the current value(s) of the selected option(s).
-     * @returns {string|string[]|undefined}
-     */
-    get currentValue(): string | string[] | undefined;
-    /**
-     * Gets the label(s) of the currently selected option(s).
-     * @returns {string}
-     */
-    get currentLabel(): string;
-    /**
-     * Gets the string representation of the current value(s).
-     * For multi-select, this is a JSON stringified array.
-     * @returns {string|undefined}
-     */
-    get stringValue(): string | undefined;
-    /**
-     * Gets the key(s) of the currently selected option(s).
-     * @returns {string|string[]|undefined}
-     */
-    get currentKeys(): string | string[] | undefined;
-    host: any;
-    size: any;
-    shape: any;
-    noCheckmark: any;
-    disabled: any;
-    matchWord: any;
-    multiSelect: any;
-    allowDeselect: any;
-    selectAllMatchingOptions: any;
-    highlightedIndex: number;
-    _menuOptions: any[];
-    _subscribers: any[];
-    internalUpdateInProgress: boolean;
-    selectedOptions: any[];
-    _pendingValue: string | number | (string | number)[] | null;
-    _pendingRetryScheduled: boolean;
-    _pendingRetryCount: number;
-    /**
-     * PROPERTY SYNCING
-     */
-    /**
-     * Handles host updates.
-     * This is a lit reactive lifecycle method.
-     * This comes from the Lit controller interface provided by adding this service as a controller to the host.
-     * See constructor for `this.host.addController(this)`
-     * You can read more about Lit reactive controllers here: https://lit.dev/docs/composition/controllers/
-     */
-    hostUpdated(): void;
-    /**
-     * Handles host disconnection and memory cleanup.
-     */
-    hostDisconnected(): void;
-    /**
-     * Sets a property value if it exists on the instance and the value has changed.
-     * @param {string} property
-     * @param {any} value
-     */
-    setProperty(property: string, value: any): void;
-    /**
-     * Sets multiple properties on the instance.
-     * @param {Object} properties - Key-value pairs of properties to set.
-     */
-    setProperties(properties: Object): void;
-    /**
-     * MENU OPTION HIGHLIGHTING
-     */
-    /**
-     * Highlights the next active option in the menu.
-     */
-    highlightNext(): void;
-    /**
-     * Highlights the previous active option in the menu.
-     */
-    highlightPrevious(): void;
-    /**
-     * Moves the highlighted option in the specified direction.
-     * @param {string} direction - The direction to move the highlight ("next" or "previous").
-     */
-    moveHighlightedOption(direction: string): void;
-    /**
-     * Sets the highlighted index to the specified option.
-     * @param {AuroMenuOption} option - The option to highlight.
-     */
-    setHighlightedOption(option: AuroMenuOption): void;
-    /**
-     * Sets the highlighted option to the option at the specified index if it exists.
-     * @param {number} index
-     */
-    setHighlightedIndex(index: number): void;
-    /**
-     * Selects the currently highlighted option.
-     */
-    selectHighlightedOption(): void;
-    /**
-     * SELECTION AND DESELECTION METHODS
-     */
-    /**
-     * Selects one or more options in a batch operation
-     * @param {AuroMenuOption|AuroMenuOption[]} options - Single option or array of options to select
-     */
-    selectOptions(options: AuroMenuOption | AuroMenuOption[]): void;
-    /**
-     * Deselects one or more options in a batch operation
-     * @param {AuroMenuOption|AuroMenuOption[]} options - Single option or array of options to deselect
-     */
-    deselectOptions(options: AuroMenuOption | AuroMenuOption[]): void;
-    /**
-     * Selects a single option.
-     * @param {AuroMenuOption} option
-     */
-    selectOption(option: AuroMenuOption): void;
-    /**
-     * Deselects a single option.
-     * @param {AuroMenuOption} option
-     */
-    deselectOption(option: AuroMenuOption): void;
-    /**
-     * Toggles the selection state of a single option.
-     * @param {AuroMenuOption} option
-     */
-    toggleOption(option: AuroMenuOption): void;
-    /**
-     * Selects options based on their value(s) when compared to a passed value or values.
-     * Value or values are normalized to an array of strings that can be matched to option keys.
-     * @param {string|number|Array<string|number>} value - The value(s) to select.
-     */
-    selectByValue(value: string | number | Array<string | number>): void;
-    /**
-     * Queues a pending value and schedules a bounded retry.
-     * @param {string|number|Array<string|number>} value - The value to retry.
-     */
-    queuePendingValue(value: string | number | Array<string | number>): void;
-    /**
-     * Clears pending retry state.
-     */
-    clearPendingValue(): void;
-    /**
-     * Resets the selected options to an empty array.
-     */
-    reset(): void;
-    /**
-     * SUBSCRIPTION, NOTIFICATION AND EVENT DISPATCH METHODS
-     */
-    /**
-     * Subscribes a callback to menu service events.
-     * @param {Function} callback - The callback to invoke on events.
-     */
-    subscribe(callback: Function): void;
-    /**
-     * Remove a previously subscribed callback from menu service events.
-     * @param {Function} callback
-     */
-    unsubscribe(callback: Function): void;
-    /**
-     * Stages an update to notify subscribers of state and value changes.
-     */
-    stageUpdate(meta?: {}): void;
-    /**
-     * Notifies subscribers of a menu service event.
-     * All notifications are sent to all subscribers.
-     * @param {string} event - The event to send to subscribers.
-     */
-    notify(event: string): void;
-    /**
-     * Notifies subscribers of a state change (selected options has changed).
-     */
-    notifyStateChange(meta?: {}): void;
-    /**
-     * Notifies subscribers of a value change (current value has changed).
-     */
-    notifyValueChange(meta?: {}): void;
-    /**
-     * Dispatches a custom event from the host element.
-     * @param {string} eventName
-     * @param {any} detail
-     */
-    dispatchChangeEvent(eventName: string, detail: any): void;
-    /**
-     * MENU OPTION MANAGEMENT METHODS
-     */
-    /**
-     * Adds a menu option to the service's list.
-     * @param {AuroMenuOption} option - the option to track
-     */
-    addMenuOption(option: AuroMenuOption): void;
-    /**
-     * Removes a menu option from the service's list.
-     * @param {AuroMenuOption} option - the option to remove
-     */
-    removeMenuOption(option: AuroMenuOption): void;
-    /**
-     * UTILITIES
-     */
-    /**
-     * Normalizes a value or array of values into an array of strings for option selection.
-     * This function ensures that input values are consistently formatted for matching menu options.
-     *
-     * @param {string|number|Array<string|number>} value - The value(s) to normalize.
-     * @returns {Array<string>} An array of string values suitable for option matching.
-     * @throws {Error} If any value is not a string or number.
-     */
-    _getNormalizedValues(value: string | number | Array<string | number>): Array<string>;
-    /**
-     * Returns whether two arrays of options contain the same elements.
-     * @param {AuroMenuOption[]} arr1 - First array of options.
-     * @param {AuroMenuOption[]} arr2 - Second array of options.
-     * @returns {boolean} True if arrays match, false otherwise.
-     */
-    optionsArraysMatch(arr1: AuroMenuOption[], arr2: AuroMenuOption[]): boolean;
-}
-export const MenuContext: import("@lit/context").Context<"menu-context", any>;