@aurodesignsystem-dev/auro-formkit 0.0.0-pr1488.2 → 0.0.0-pr1489.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/components/bibtemplate/dist/auro-bibtemplate.d.ts +7 -0
- package/components/bibtemplate/dist/index.js +9 -1
- package/components/bibtemplate/dist/registered.js +9 -1
- package/components/checkbox/demo/customize.min.js +1 -1
- package/components/checkbox/demo/getting-started.min.js +1 -1
- package/components/checkbox/demo/index.min.js +1 -1
- package/components/checkbox/demo/pages.json +1 -1
- package/components/checkbox/demo/why-checkbox.html +57 -0
- package/components/checkbox/demo/why-checkbox.md +86 -0
- package/components/checkbox/dist/index.js +1 -1
- package/components/checkbox/dist/registered.js +1 -1
- package/components/combobox/demo/customize.min.js +234 -16
- package/components/combobox/demo/getting-started.min.js +234 -16
- package/components/combobox/demo/index.min.js +234 -16
- package/components/combobox/demo/pages.json +1 -1
- package/components/combobox/demo/why-combobox.html +57 -0
- package/components/combobox/demo/why-combobox.md +113 -0
- package/components/combobox/dist/index.js +234 -16
- package/components/combobox/dist/registered.js +234 -16
- package/components/counter/demo/customize.min.js +233 -15
- package/components/counter/demo/index.min.js +233 -15
- package/components/counter/demo/keyboard-behavior.md +1 -0
- package/components/counter/demo/pages.json +1 -1
- package/components/counter/demo/why-counter.html +57 -0
- package/components/counter/demo/why-counter.md +108 -0
- package/components/counter/dist/index.js +10 -2
- package/components/counter/dist/registered.js +10 -2
- package/components/datepicker/demo/accessibility.md +51 -3
- package/components/datepicker/demo/api.md +11 -2
- package/components/datepicker/demo/customize.html +2 -0
- package/components/datepicker/demo/customize.js +19 -0
- package/components/datepicker/demo/customize.md +72 -8
- package/components/datepicker/demo/customize.min.js +26029 -0
- package/components/datepicker/demo/design.md +3 -1
- package/components/datepicker/demo/index.js +5 -1
- package/components/datepicker/demo/index.md +83 -2
- package/components/datepicker/demo/index.min.js +1564 -96
- package/components/datepicker/demo/keyboard-behavior.md +201 -2
- package/components/datepicker/demo/pages.json +1 -1
- package/components/datepicker/demo/voiceover.md +19 -12
- package/components/datepicker/demo/why-datepicker.html +57 -0
- package/components/datepicker/demo/why-datepicker.md +133 -0
- package/components/datepicker/dist/index.js +1489 -97
- package/components/datepicker/dist/registered.js +1489 -97
- package/components/datepicker/dist/src/auro-calendar-cell.d.ts +66 -1
- package/components/datepicker/dist/src/auro-calendar-month.d.ts +28 -0
- package/components/datepicker/dist/src/auro-calendar.d.ts +100 -0
- package/components/datepicker/dist/src/auro-datepicker.d.ts +88 -0
- package/components/datepicker/dist/src/datepickerKeyboardStrategy.d.ts +5 -3
- package/components/dropdown/demo/accessibility.md +11 -0
- package/components/dropdown/demo/api.md +1 -0
- package/components/dropdown/demo/customize.md +3 -0
- package/components/dropdown/demo/customize.min.js +223 -13
- package/components/dropdown/demo/getting-started.min.js +223 -13
- package/components/dropdown/demo/index.min.js +223 -13
- package/components/dropdown/demo/keyboard-behavior.md +1 -0
- package/components/dropdown/demo/pages.json +1 -1
- package/components/dropdown/demo/why-dropdown.html +57 -0
- package/components/dropdown/demo/why-dropdown.md +97 -0
- package/components/dropdown/dist/auro-dropdown.d.ts +33 -1
- package/components/dropdown/dist/index.js +223 -13
- package/components/dropdown/dist/registered.js +223 -13
- package/components/form/demo/customize.min.js +2191 -145
- package/components/form/demo/getting-started.min.js +2191 -145
- package/components/form/demo/index.min.js +2191 -145
- package/components/form/demo/pages.json +1 -1
- package/components/form/demo/registerDemoDeps.min.js +2191 -145
- package/components/form/demo/why-form.html +57 -0
- package/components/form/demo/why-form.md +101 -0
- package/components/input/demo/customize.min.js +1 -1
- package/components/input/demo/getting-started.min.js +1 -1
- package/components/input/demo/index.min.js +1 -1
- package/components/input/demo/pages.json +1 -1
- package/components/input/demo/why-input.html +57 -0
- package/components/input/demo/why-input.md +121 -0
- package/components/input/dist/index.js +1 -1
- package/components/input/dist/registered.js +1 -1
- package/components/menu/demo/pages.json +1 -1
- package/components/menu/demo/why-menu.html +57 -0
- package/components/menu/demo/why-menu.md +104 -0
- package/components/radio/demo/customize.min.js +2186 -0
- package/components/radio/demo/demo-support.min.js +55807 -0
- package/components/radio/demo/getting-started.js +1 -1
- package/components/radio/demo/getting-started.md +1 -1
- package/components/radio/demo/getting-started.min.js +2205 -0
- package/components/radio/demo/index.min.js +1 -1
- package/components/radio/demo/pages.json +1 -1
- package/components/radio/demo/why-radio.html +57 -0
- package/components/radio/demo/why-radio.md +92 -0
- package/components/radio/dist/index.js +1 -1
- package/components/radio/dist/registered.js +1 -1
- package/components/select/demo/customize.min.js +233 -15
- package/components/select/demo/getting-started.min.js +233 -15
- package/components/select/demo/index.min.js +233 -15
- package/components/select/demo/keyboard-behavior.md +1 -0
- package/components/select/demo/pages.json +1 -1
- package/components/select/demo/why-select.html +57 -0
- package/components/select/demo/why-select.md +128 -0
- package/components/select/dist/index.js +233 -15
- package/components/select/dist/registered.js +233 -15
- package/custom-elements.json +745 -28
- package/package.json +2 -2
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
<!--
|
|
2
|
+
Copyright (c) Alaska Air. All right reserved. Licensed under the Apache-2.0 license
|
|
3
|
+
See LICENSE in the project root for license information.
|
|
4
|
+
|
|
5
|
+
HTML in this document is standardized and NOT to be edited.
|
|
6
|
+
All demo code should be added/edited in ./demo/why-form.md
|
|
7
|
+
|
|
8
|
+
With the exception of adding custom elements if needed for the demo.
|
|
9
|
+
|
|
10
|
+
----------------------- DO NOT EDIT -----------------------------
|
|
11
|
+
|
|
12
|
+
-->
|
|
13
|
+
|
|
14
|
+
<!DOCTYPE html>
|
|
15
|
+
<html lang="en">
|
|
16
|
+
<head>
|
|
17
|
+
<meta charset="UTF-8" />
|
|
18
|
+
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
|
19
|
+
<title>Auro Web Component Demo | auro-form | Why auro-form</title>
|
|
20
|
+
|
|
21
|
+
<!-- highlight.js Stylesheet -->
|
|
22
|
+
<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.9.0/build/styles/github.min.css"/>
|
|
23
|
+
|
|
24
|
+
<!-- Legacy reference is still needed to support auro-form's use of legacy token values at this time -->
|
|
25
|
+
<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/design-tokens@latest/dist/legacy/auro-classic/CSSCustomProperties.css"/>
|
|
26
|
+
|
|
27
|
+
<!-- Design Token Alaska Theme -->
|
|
28
|
+
<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/design-tokens@latest/dist/themes/alaska/CSSCustomProperties--alaska.min.css"/>
|
|
29
|
+
|
|
30
|
+
<!-- Webcore Stylesheet Alaska Theme -->
|
|
31
|
+
<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/webcorestylesheets@latest/dist/bundled/themes/alaska.global.min.css" />
|
|
32
|
+
|
|
33
|
+
<!-- Demo Specific Styles -->
|
|
34
|
+
<link rel="stylesheet" type="text/css" href="./styles.min.css" />
|
|
35
|
+
<style>
|
|
36
|
+
table {
|
|
37
|
+
--ds-color-container-secondary-default: transparent;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
tr:not(:last-of-type) {
|
|
41
|
+
border-bottom: 1px solid var(--ds-color-border-tertiary-default);
|
|
42
|
+
}
|
|
43
|
+
</style>
|
|
44
|
+
</head>
|
|
45
|
+
<body class="auro-markdown">
|
|
46
|
+
<main></main>
|
|
47
|
+
|
|
48
|
+
<script type="module">
|
|
49
|
+
import { renderPage } from './demo-support.min.js';
|
|
50
|
+
await renderPage('./why-form.md');
|
|
51
|
+
</script>
|
|
52
|
+
|
|
53
|
+
<!-- If additional elements are needed for the demo, add them here. -->
|
|
54
|
+
<script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-header@latest/+esm" type="module"></script>
|
|
55
|
+
<script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-hyperlink@latest/+esm" type="module"></script>
|
|
56
|
+
</body>
|
|
57
|
+
</html>
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
<auro-header level="1" id="overview">Why auro-form?</auro-header>
|
|
2
|
+
<p>The native <code><form></code> element handles submission and reset for standard HTML inputs, but it has no awareness of web components, cannot orchestrate validation across custom elements, and provides no centralized state management. <code>auro-form</code> fills these gaps for applications built with Auro components.</p>
|
|
3
|
+
<auro-header level="2" id="customElementAwareness">Custom element awareness</auro-header>
|
|
4
|
+
<p>Native <code><form></code> relies on the browser's form association API, which web components must explicitly opt into via <code>ElementInternals</code>. Even when they do, coordinating validation state, required fields, and submission values across a mix of Auro components requires custom JavaScript.</p>
|
|
5
|
+
<p><code>auro-form</code> automatically discovers and manages:</p>
|
|
6
|
+
<ul>
|
|
7
|
+
<li><code>auro-input</code></li>
|
|
8
|
+
<li><code>auro-select</code></li>
|
|
9
|
+
<li><code>auro-datepicker</code></li>
|
|
10
|
+
<li><code>auro-combobox</code></li>
|
|
11
|
+
<li><code>auro-checkbox-group</code></li>
|
|
12
|
+
<li><code>auro-radio-group</code></li>
|
|
13
|
+
<li><code>auro-counter-group</code></li>
|
|
14
|
+
</ul>
|
|
15
|
+
<p>New elements added to the DOM are detected via <code>MutationObserver</code> and integrated automatically.</p>
|
|
16
|
+
<auro-header level="2" id="validationOrchestration">Validation orchestration</auro-header>
|
|
17
|
+
<p>Native forms validate each input independently. There is no built-in way to check "are all required fields valid?" without querying each element manually.</p>
|
|
18
|
+
<p><code>auro-form</code> provides:</p>
|
|
19
|
+
<ul>
|
|
20
|
+
<li>A single <code>validity</code> getter that returns <code>'valid'</code>, <code>'invalid'</code>, or <code>null</code> based on the aggregate state of all child form elements</li>
|
|
21
|
+
<li>Automatic validation of all elements on <code>submit()</code> — each element's <code>validate(true)</code> is called to force error display</li>
|
|
22
|
+
<li>Per-element validity tracking via an internal <code>formState</code> object</li>
|
|
23
|
+
<li>Listening for <code>auroFormElement-validated</code> events from child components to stay in sync</li>
|
|
24
|
+
</ul>
|
|
25
|
+
<auro-header level="2" id="centralizedState">Centralized state</auro-header>
|
|
26
|
+
<p>Native forms have no concept of "has the user touched anything?" or "what are all the current values?"</p>
|
|
27
|
+
<p><code>auro-form</code> tracks:</p>
|
|
28
|
+
<ul>
|
|
29
|
+
<li><strong><code>value</code></strong> — A key-value object of all form element values, keyed by element <code>name</code></li>
|
|
30
|
+
<li><strong><code>isInitialState</code></strong> — Whether any element has been modified since initialization</li>
|
|
31
|
+
<li><strong>Submit/reset button state</strong> — Submit and reset buttons are automatically disabled based on form state (e.g., reset is disabled when the form is in its initial state)</li>
|
|
32
|
+
</ul>
|
|
33
|
+
<auro-header level="2" id="submitAndReset">Submit and reset</auro-header>
|
|
34
|
+
<p>Native form submission navigates to a URL or requires <code>event.preventDefault()</code> and manual value extraction.</p>
|
|
35
|
+
<p><code>auro-form</code> simplifies this:</p>
|
|
36
|
+
<ul>
|
|
37
|
+
<li><strong><code>submit()</code></strong> — Validates all elements. If valid, dispatches a <code>submit</code> event with a <code>detail.value</code> object containing all form values. No page navigation.</li>
|
|
38
|
+
<li><strong><code>reset()</code></strong> — Resets all child elements to their initial state, dispatches a <code>reset</code> event with <code>detail.previousValue</code> containing the pre-reset values.</li>
|
|
39
|
+
<li><strong>Enter key</strong> — Pressing Enter on a form element triggers <code>submit()</code>, matching native form behavior. Textareas are excluded to allow newlines.</li>
|
|
40
|
+
</ul>
|
|
41
|
+
<auro-header level="2" id="eventNormalization">Event normalization</auro-header>
|
|
42
|
+
<p>Each Auro component dispatches its own events (<code>auroSelect-valueSet</code>, <code>auroDatePicker-valueSet</code>, etc.). Listening for all of these individually is error-prone.</p>
|
|
43
|
+
<p><code>auro-form</code> normalizes events:</p>
|
|
44
|
+
<ul>
|
|
45
|
+
<li><code>input</code> — Fired when any child element receives user input</li>
|
|
46
|
+
<li><code>change</code> — Fired when any child element's value changes, or when the form is initialized</li>
|
|
47
|
+
<li><code>submit</code> — Fired with aggregated form values on valid submission</li>
|
|
48
|
+
<li><code>reset</code> — Fired with previous values on reset</li>
|
|
49
|
+
</ul>
|
|
50
|
+
<auro-header level="2" id="summary">Summary</auro-header>
|
|
51
|
+
<table>
|
|
52
|
+
<thead>
|
|
53
|
+
<tr>
|
|
54
|
+
<th>Capability</th>
|
|
55
|
+
<th><code><form></code></th>
|
|
56
|
+
<th><code>auro-form</code></th>
|
|
57
|
+
</tr>
|
|
58
|
+
</thead>
|
|
59
|
+
<tbody>
|
|
60
|
+
<tr>
|
|
61
|
+
<td>Web component discovery</td>
|
|
62
|
+
<td>Manual</td>
|
|
63
|
+
<td>Automatic (MutationObserver)</td>
|
|
64
|
+
</tr>
|
|
65
|
+
<tr>
|
|
66
|
+
<td>Aggregate validity</td>
|
|
67
|
+
<td>Manual querying</td>
|
|
68
|
+
<td>Single <code>validity</code> getter</td>
|
|
69
|
+
</tr>
|
|
70
|
+
<tr>
|
|
71
|
+
<td>Centralized values</td>
|
|
72
|
+
<td><code>FormData</code> (native inputs only)</td>
|
|
73
|
+
<td><code>value</code> object (all Auro components)</td>
|
|
74
|
+
</tr>
|
|
75
|
+
<tr>
|
|
76
|
+
<td>Force validation on submit</td>
|
|
77
|
+
<td>Manual per-element</td>
|
|
78
|
+
<td>Automatic</td>
|
|
79
|
+
</tr>
|
|
80
|
+
<tr>
|
|
81
|
+
<td>Submit button auto-disable</td>
|
|
82
|
+
<td>No</td>
|
|
83
|
+
<td>Yes</td>
|
|
84
|
+
</tr>
|
|
85
|
+
<tr>
|
|
86
|
+
<td>Reset to initial state</td>
|
|
87
|
+
<td>Native inputs only</td>
|
|
88
|
+
<td>All Auro components</td>
|
|
89
|
+
</tr>
|
|
90
|
+
<tr>
|
|
91
|
+
<td>Enter key submit</td>
|
|
92
|
+
<td>Native inputs only</td>
|
|
93
|
+
<td>All Auro components</td>
|
|
94
|
+
</tr>
|
|
95
|
+
<tr>
|
|
96
|
+
<td>Event normalization</td>
|
|
97
|
+
<td>No</td>
|
|
98
|
+
<td>Unified input/change/submit/reset</td>
|
|
99
|
+
</tr>
|
|
100
|
+
</tbody>
|
|
101
|
+
</table>
|
|
@@ -1 +1 @@
|
|
|
1
|
-
["accessibility.md","api.md","customize.md","design.md","getting-started.md","index.md","keyboard-behavior.md","voiceover.md","readme.md"]
|
|
1
|
+
["accessibility.md","api.md","customize.md","design.md","getting-started.md","index.md","keyboard-behavior.md","voiceover.md","why-input.md","readme.md"]
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
<!--
|
|
2
|
+
Copyright (c) Alaska Air. All right reserved. Licensed under the Apache-2.0 license
|
|
3
|
+
See LICENSE in the project root for license information.
|
|
4
|
+
|
|
5
|
+
HTML in this document is standardized and NOT to be edited.
|
|
6
|
+
All demo code should be added/edited in ./demo/why-input.md
|
|
7
|
+
|
|
8
|
+
With the exception of adding custom elements if needed for the demo.
|
|
9
|
+
|
|
10
|
+
----------------------- DO NOT EDIT -----------------------------
|
|
11
|
+
|
|
12
|
+
-->
|
|
13
|
+
|
|
14
|
+
<!DOCTYPE html>
|
|
15
|
+
<html lang="en">
|
|
16
|
+
<head>
|
|
17
|
+
<meta charset="UTF-8" />
|
|
18
|
+
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
|
19
|
+
<title>Auro Web Component Demo | auro-input | Why auro-input</title>
|
|
20
|
+
|
|
21
|
+
<!-- highlight.js Stylesheet -->
|
|
22
|
+
<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.9.0/build/styles/github.min.css"/>
|
|
23
|
+
|
|
24
|
+
<!-- Legacy reference is still needed to support auro-input's use of legacy token values at this time -->
|
|
25
|
+
<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/design-tokens@latest/dist/legacy/auro-classic/CSSCustomProperties.css"/>
|
|
26
|
+
|
|
27
|
+
<!-- Design Token Alaska Theme -->
|
|
28
|
+
<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/design-tokens@latest/dist/themes/alaska/CSSCustomProperties--alaska.min.css"/>
|
|
29
|
+
|
|
30
|
+
<!-- Webcore Stylesheet Alaska Theme -->
|
|
31
|
+
<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/webcorestylesheets@latest/dist/bundled/themes/alaska.global.min.css" />
|
|
32
|
+
|
|
33
|
+
<!-- Demo Specific Styles -->
|
|
34
|
+
<link rel="stylesheet" type="text/css" href="./styles.min.css" />
|
|
35
|
+
<style>
|
|
36
|
+
table {
|
|
37
|
+
--ds-color-container-secondary-default: transparent;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
tr:not(:last-of-type) {
|
|
41
|
+
border-bottom: 1px solid var(--ds-color-border-tertiary-default);
|
|
42
|
+
}
|
|
43
|
+
</style>
|
|
44
|
+
</head>
|
|
45
|
+
<body class="auro-markdown">
|
|
46
|
+
<main></main>
|
|
47
|
+
|
|
48
|
+
<script type="module">
|
|
49
|
+
import { renderPage } from './demo-support.min.js';
|
|
50
|
+
await renderPage('./why-input.md');
|
|
51
|
+
</script>
|
|
52
|
+
|
|
53
|
+
<!-- If additional elements are needed for the demo, add them here. -->
|
|
54
|
+
<script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-header@latest/+esm" type="module"></script>
|
|
55
|
+
<script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-hyperlink@latest/+esm" type="module"></script>
|
|
56
|
+
</body>
|
|
57
|
+
</html>
|
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
<auro-header level="1" id="overview">Why auro-input?</auro-header>
|
|
2
|
+
<p>The native <code><input></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>
|
|
3
|
+
<auro-header level="2" id="accessibility">Accessibility</auro-header>
|
|
4
|
+
<p>Native inputs require manual <code><label></code> wiring, have no standard pattern for error announcements, and provide no built-in clear or show/hide password controls.</p>
|
|
5
|
+
<p><code>auro-input</code> provides:</p>
|
|
6
|
+
<ul>
|
|
7
|
+
<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>
|
|
8
|
+
<li><strong>Dynamic label positioning</strong> — Labels float above the input when focused or populated, providing context without consuming space.</li>
|
|
9
|
+
<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>
|
|
10
|
+
<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>
|
|
11
|
+
<li><strong>Validation announcements</strong> — Error messages display in help text with appropriate ARIA roles so screen readers announce validity changes.</li>
|
|
12
|
+
</ul>
|
|
13
|
+
<auro-header level="2" id="inputMaskingAndFormatting">Input masking and formatting</auro-header>
|
|
14
|
+
<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>
|
|
15
|
+
<p><code>auro-input</code> includes IMask integration:</p>
|
|
16
|
+
<ul>
|
|
17
|
+
<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>
|
|
18
|
+
<li><strong>Auto-formatting</strong> — Characters are formatted as the user types, with cursor position preserved.</li>
|
|
19
|
+
<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>
|
|
20
|
+
</ul>
|
|
21
|
+
<auro-header level="2" id="creditCardDetection">Credit card detection</auro-header>
|
|
22
|
+
<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>
|
|
23
|
+
<p><code>auro-input</code> with <code>type="credit-card"</code> provides:</p>
|
|
24
|
+
<ul>
|
|
25
|
+
<li><strong>Auto-detection</strong> — Identifies Visa, Mastercard, American Express, Discover, Diners Club, and Alaska Airlines cards from the first digits typed.</li>
|
|
26
|
+
<li><strong>Dynamic formatting</strong> — Applies the correct digit grouping (e.g., 4-4-4-4 for Visa, 4-6-5 for Amex).</li>
|
|
27
|
+
<li><strong>Card icon</strong> — Displays the detected card brand icon automatically.</li>
|
|
28
|
+
<li><strong>Luhn validation</strong> — Validates the card number using the Luhn algorithm.</li>
|
|
29
|
+
</ul>
|
|
30
|
+
<auro-header level="2" id="validation">Validation</auro-header>
|
|
31
|
+
<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>
|
|
32
|
+
<p><code>auro-input</code> provides:</p>
|
|
33
|
+
<ul>
|
|
34
|
+
<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>
|
|
35
|
+
<li>Type-specific validation (email format, credit card Luhn, phone format, date format)</li>
|
|
36
|
+
<li>Validation timing control: on blur (default), on every input (<code>validateOnInput</code>), or disabled (<code>noValidate</code>)</li>
|
|
37
|
+
<li>Programmatic vs. user input distinction — the component tracks whether a value change was user-initiated or programmatic</li>
|
|
38
|
+
</ul>
|
|
39
|
+
<auro-header level="2" id="displayValueMasking">Display value masking</auro-header>
|
|
40
|
+
<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>
|
|
41
|
+
<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>
|
|
42
|
+
<auro-header level="2" id="layoutOptions">Layout options</auro-header>
|
|
43
|
+
<p>Native inputs have a single visual presentation controlled by browser defaults.</p>
|
|
44
|
+
<p><code>auro-input</code> offers:</p>
|
|
45
|
+
<ul>
|
|
46
|
+
<li><strong>Three layouts</strong> — Classic (floating label), emphasized (prominent label), and snowflake (custom positioning)</li>
|
|
47
|
+
<li><strong>Shape variants</strong> — Box, pill, pill-left, pill-right for different visual contexts</li>
|
|
48
|
+
<li><strong>Nested mode</strong> — Removes borders and hides help/error text for embedding inside other components</li>
|
|
49
|
+
<li><strong>Simple mode</strong> — Borderless variant for inline use</li>
|
|
50
|
+
</ul>
|
|
51
|
+
<auro-header level="2" id="designSystemIntegration">Design system integration</auro-header>
|
|
52
|
+
<p>Native input styling varies across browsers and requires extensive CSS resets to normalize.</p>
|
|
53
|
+
<p><code>auro-input</code> is built with the Auro Design System:</p>
|
|
54
|
+
<ul>
|
|
55
|
+
<li>Consistent visual language across all browsers and platforms</li>
|
|
56
|
+
<li>Light and dark theme support (<code>appearance</code>)</li>
|
|
57
|
+
<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>
|
|
58
|
+
<li>Design token integration for colors, spacing, and typography</li>
|
|
59
|
+
</ul>
|
|
60
|
+
<auro-header level="2" id="summary">Summary</auro-header>
|
|
61
|
+
<table>
|
|
62
|
+
<thead>
|
|
63
|
+
<tr>
|
|
64
|
+
<th>Capability</th>
|
|
65
|
+
<th><code><input></code></th>
|
|
66
|
+
<th><code>auro-input</code></th>
|
|
67
|
+
</tr>
|
|
68
|
+
</thead>
|
|
69
|
+
<tbody>
|
|
70
|
+
<tr>
|
|
71
|
+
<td>Automatic label binding</td>
|
|
72
|
+
<td>No (<code>for</code>/<code>id</code> required)</td>
|
|
73
|
+
<td>Yes (slot-based)</td>
|
|
74
|
+
</tr>
|
|
75
|
+
<tr>
|
|
76
|
+
<td>Input masking</td>
|
|
77
|
+
<td>No</td>
|
|
78
|
+
<td>Built-in (IMask)</td>
|
|
79
|
+
</tr>
|
|
80
|
+
<tr>
|
|
81
|
+
<td>Credit card detection</td>
|
|
82
|
+
<td>No</td>
|
|
83
|
+
<td>Auto-detect with icon and formatting</td>
|
|
84
|
+
</tr>
|
|
85
|
+
<tr>
|
|
86
|
+
<td>Custom validation messages</td>
|
|
87
|
+
<td>Browser-controlled</td>
|
|
88
|
+
<td>Per-constraint custom messages</td>
|
|
89
|
+
</tr>
|
|
90
|
+
<tr>
|
|
91
|
+
<td>Clear button</td>
|
|
92
|
+
<td>No</td>
|
|
93
|
+
<td>Built-in with ARIA label</td>
|
|
94
|
+
</tr>
|
|
95
|
+
<tr>
|
|
96
|
+
<td>Password show/hide</td>
|
|
97
|
+
<td>No</td>
|
|
98
|
+
<td>Built-in toggle</td>
|
|
99
|
+
</tr>
|
|
100
|
+
<tr>
|
|
101
|
+
<td>Display value masking</td>
|
|
102
|
+
<td>No</td>
|
|
103
|
+
<td><code>displayValue</code> slot</td>
|
|
104
|
+
</tr>
|
|
105
|
+
<tr>
|
|
106
|
+
<td>Multiple layouts</td>
|
|
107
|
+
<td>No</td>
|
|
108
|
+
<td>Classic, emphasized, snowflake</td>
|
|
109
|
+
</tr>
|
|
110
|
+
<tr>
|
|
111
|
+
<td>Consistent cross-browser UI</td>
|
|
112
|
+
<td>No</td>
|
|
113
|
+
<td>Yes</td>
|
|
114
|
+
</tr>
|
|
115
|
+
<tr>
|
|
116
|
+
<td>Theming</td>
|
|
117
|
+
<td>Browser-dependent</td>
|
|
118
|
+
<td>Full design system integration</td>
|
|
119
|
+
</tr>
|
|
120
|
+
</tbody>
|
|
121
|
+
</table>
|
|
@@ -6614,7 +6614,7 @@ class AuroHelpText extends LitElement {
|
|
|
6614
6614
|
}
|
|
6615
6615
|
}
|
|
6616
6616
|
|
|
6617
|
-
var formkitVersion = '
|
|
6617
|
+
var formkitVersion = '202606011856';
|
|
6618
6618
|
|
|
6619
6619
|
// Copyright (c) 2025 Alaska Airlines. All right reserved. Licensed under the Apache-2.0 license
|
|
6620
6620
|
// See LICENSE in the project root for license information.
|
|
@@ -6614,7 +6614,7 @@ class AuroHelpText extends LitElement {
|
|
|
6614
6614
|
}
|
|
6615
6615
|
}
|
|
6616
6616
|
|
|
6617
|
-
var formkitVersion = '
|
|
6617
|
+
var formkitVersion = '202606011856';
|
|
6618
6618
|
|
|
6619
6619
|
// Copyright (c) 2025 Alaska Airlines. All right reserved. Licensed under the Apache-2.0 license
|
|
6620
6620
|
// See LICENSE in the project root for license information.
|
|
@@ -1 +1 @@
|
|
|
1
|
-
["accessibility.md","api.md","customize.md","design.md","getting-started.md","index.md","keyboard-behavior.md","voiceover.md","readme.md"]
|
|
1
|
+
["accessibility.md","api.md","customize.md","design.md","getting-started.md","index.md","keyboard-behavior.md","voiceover.md","why-menu.md","readme.md"]
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
<!--
|
|
2
|
+
Copyright (c) Alaska Air. All right reserved. Licensed under the Apache-2.0 license
|
|
3
|
+
See LICENSE in the project root for license information.
|
|
4
|
+
|
|
5
|
+
HTML in this document is standardized and NOT to be edited.
|
|
6
|
+
All demo code should be added/edited in ./demo/why-menu.md
|
|
7
|
+
|
|
8
|
+
With the exception of adding custom elements if needed for the demo.
|
|
9
|
+
|
|
10
|
+
----------------------- DO NOT EDIT -----------------------------
|
|
11
|
+
|
|
12
|
+
-->
|
|
13
|
+
|
|
14
|
+
<!DOCTYPE html>
|
|
15
|
+
<html lang="en">
|
|
16
|
+
<head>
|
|
17
|
+
<meta charset="UTF-8" />
|
|
18
|
+
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
|
19
|
+
<title>Auro Web Component Demo | auro-menu | Why auro-menu</title>
|
|
20
|
+
|
|
21
|
+
<!-- highlight.js Stylesheet -->
|
|
22
|
+
<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.9.0/build/styles/github.min.css"/>
|
|
23
|
+
|
|
24
|
+
<!-- Legacy reference is still needed to support auro-menu's use of legacy token values at this time -->
|
|
25
|
+
<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/design-tokens@latest/dist/legacy/auro-classic/CSSCustomProperties.css"/>
|
|
26
|
+
|
|
27
|
+
<!-- Design Token Alaska Theme -->
|
|
28
|
+
<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/design-tokens@latest/dist/themes/alaska/CSSCustomProperties--alaska.min.css"/>
|
|
29
|
+
|
|
30
|
+
<!-- Webcore Stylesheet Alaska Theme -->
|
|
31
|
+
<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/webcorestylesheets@latest/dist/bundled/themes/alaska.global.min.css" />
|
|
32
|
+
|
|
33
|
+
<!-- Demo Specific Styles -->
|
|
34
|
+
<link rel="stylesheet" type="text/css" href="./styles.min.css" />
|
|
35
|
+
<style>
|
|
36
|
+
table {
|
|
37
|
+
--ds-color-container-secondary-default: transparent;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
tr:not(:last-of-type) {
|
|
41
|
+
border-bottom: 1px solid var(--ds-color-border-tertiary-default);
|
|
42
|
+
}
|
|
43
|
+
</style>
|
|
44
|
+
</head>
|
|
45
|
+
<body class="auro-markdown">
|
|
46
|
+
<main></main>
|
|
47
|
+
|
|
48
|
+
<script type="module">
|
|
49
|
+
import { renderPage } from './demo-support.min.js';
|
|
50
|
+
await renderPage('./why-menu.md');
|
|
51
|
+
</script>
|
|
52
|
+
|
|
53
|
+
<!-- If additional elements are needed for the demo, add them here. -->
|
|
54
|
+
<script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-header@latest/+esm" type="module"></script>
|
|
55
|
+
<script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-hyperlink@latest/+esm" type="module"></script>
|
|
56
|
+
</body>
|
|
57
|
+
</html>
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
<auro-header level="1" id="overview">Why auro-menu?</auro-header>
|
|
2
|
+
<p>Native HTML has no dedicated menu component for selection lists. <code><select></code> only accepts <code><option></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>
|
|
3
|
+
<auro-header level="2" id="accessibility">Accessibility</auro-header>
|
|
4
|
+
<p>Custom list implementations often fail to provide correct ARIA semantics, keyboard navigation, or screen reader announcements.</p>
|
|
5
|
+
<p><code>auro-menu</code> provides:</p>
|
|
6
|
+
<ul>
|
|
7
|
+
<li><strong>Keyboard navigation</strong> — Arrow keys move between options, Enter selects, Escape cancels, Home/End jump to the first and last options.</li>
|
|
8
|
+
<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>
|
|
9
|
+
<li><strong>Multi-select semantics</strong> — When <code>multiSelect</code> is enabled, <code>aria-multiselectable</code> is set on the menu.</li>
|
|
10
|
+
<li><strong>Loading state</strong> — <code>aria-busy</code> is set during loading, with customizable loading icon and text slots.</li>
|
|
11
|
+
</ul>
|
|
12
|
+
<auro-header level="2" id="richOptionContent">Rich option content</auro-header>
|
|
13
|
+
<p><code><option></code> elements accept only plain text. There is no native way to add icons, descriptions, or nested structure to options.</p>
|
|
14
|
+
<p><code>auro-menu</code> options support:</p>
|
|
15
|
+
<ul>
|
|
16
|
+
<li>Full HTML content in each option</li>
|
|
17
|
+
<li>Icons alongside option text</li>
|
|
18
|
+
<li>Nested submenus for hierarchical navigation</li>
|
|
19
|
+
<li>Checkmark indicators for selected options (configurable via <code>noCheckmark</code>)</li>
|
|
20
|
+
</ul>
|
|
21
|
+
<auro-header level="2" id="multiselect">Multi-select</auro-header>
|
|
22
|
+
<p>Native <code><select multiple></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>
|
|
23
|
+
<p><code>auro-menu</code> provides:</p>
|
|
24
|
+
<ul>
|
|
25
|
+
<li>Checkmark indicators for each selected option</li>
|
|
26
|
+
<li>A <code>value</code> that returns a JSON-stringified array of selections</li>
|
|
27
|
+
<li><code>allowDeselect</code> to toggle selections off</li>
|
|
28
|
+
<li><code>selectAllMatchingOptions</code> for bulk selection operations</li>
|
|
29
|
+
<li><code>clearSelection()</code> and <code>reset()</code> methods for programmatic control</li>
|
|
30
|
+
</ul>
|
|
31
|
+
<auro-header level="2" id="searchAndFiltering">Search and filtering</auro-header>
|
|
32
|
+
<p>Native menus have no concept of filtering or highlighting matched text.</p>
|
|
33
|
+
<p><code>auro-menu</code> supports:</p>
|
|
34
|
+
<ul>
|
|
35
|
+
<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>
|
|
36
|
+
<li>Programmatic <code>navigateOptions(direction)</code> for keyboard-driven traversal</li>
|
|
37
|
+
</ul>
|
|
38
|
+
<auro-header level="2" id="loadingState">Loading state</auro-header>
|
|
39
|
+
<p>Native selects have no loading pattern. When options are fetched asynchronously, there is no standard way to communicate this to the user.</p>
|
|
40
|
+
<p><code>auro-menu</code> provides:</p>
|
|
41
|
+
<ul>
|
|
42
|
+
<li>A <code>loading</code> attribute that displays a loading indicator</li>
|
|
43
|
+
<li><code>loadingIcon</code> and <code>loadingText</code> slots for custom loading UI</li>
|
|
44
|
+
<li><code>auroMenu-loadingChange</code> event when the loading state changes</li>
|
|
45
|
+
</ul>
|
|
46
|
+
<auro-header level="2" id="composability">Composability</auro-header>
|
|
47
|
+
<p><code>auro-menu</code> is designed as a building block. It is the selection engine inside:</p>
|
|
48
|
+
<ul>
|
|
49
|
+
<li><strong><code>auro-select</code></strong> — Dropdown selection</li>
|
|
50
|
+
<li><strong><code>auro-combobox</code></strong> — Autocomplete with filtering</li>
|
|
51
|
+
</ul>
|
|
52
|
+
<p>This architecture means selection behavior, keyboard navigation, and ARIA semantics are consistent across all selection components.</p>
|
|
53
|
+
<auro-header level="2" id="summary">Summary</auro-header>
|
|
54
|
+
<table>
|
|
55
|
+
<thead>
|
|
56
|
+
<tr>
|
|
57
|
+
<th>Capability</th>
|
|
58
|
+
<th><code><select></code> / <code><option></code></th>
|
|
59
|
+
<th><code>auro-menu</code></th>
|
|
60
|
+
</tr>
|
|
61
|
+
</thead>
|
|
62
|
+
<tbody>
|
|
63
|
+
<tr>
|
|
64
|
+
<td>Rich HTML in options</td>
|
|
65
|
+
<td>Plain text only</td>
|
|
66
|
+
<td>Full HTML</td>
|
|
67
|
+
</tr>
|
|
68
|
+
<tr>
|
|
69
|
+
<td>Nested submenus</td>
|
|
70
|
+
<td>Not supported</td>
|
|
71
|
+
<td>Built-in</td>
|
|
72
|
+
</tr>
|
|
73
|
+
<tr>
|
|
74
|
+
<td>Multi-select with checkmarks</td>
|
|
75
|
+
<td>Ctrl+click list box</td>
|
|
76
|
+
<td>Checkmark toggle</td>
|
|
77
|
+
</tr>
|
|
78
|
+
<tr>
|
|
79
|
+
<td>Search/filter highlighting</td>
|
|
80
|
+
<td>No</td>
|
|
81
|
+
<td><code>matchWord</code> attribute</td>
|
|
82
|
+
</tr>
|
|
83
|
+
<tr>
|
|
84
|
+
<td>Loading state</td>
|
|
85
|
+
<td>No</td>
|
|
86
|
+
<td>Built-in with custom slots</td>
|
|
87
|
+
</tr>
|
|
88
|
+
<tr>
|
|
89
|
+
<td>Keyboard navigation</td>
|
|
90
|
+
<td>Browser-dependent</td>
|
|
91
|
+
<td>Full arrow/Enter/Escape/Home/End</td>
|
|
92
|
+
</tr>
|
|
93
|
+
<tr>
|
|
94
|
+
<td>Composable primitive</td>
|
|
95
|
+
<td>No</td>
|
|
96
|
+
<td>Foundation for select and combobox</td>
|
|
97
|
+
</tr>
|
|
98
|
+
<tr>
|
|
99
|
+
<td>Deselect support</td>
|
|
100
|
+
<td>No</td>
|
|
101
|
+
<td><code>allowDeselect</code> attribute</td>
|
|
102
|
+
</tr>
|
|
103
|
+
</tbody>
|
|
104
|
+
</table>
|