@aurodesignsystem-dev/auro-formkit 0.0.0-pr1492.5 → 0.0.0-pr1493.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.
Files changed (153) hide show
  1. package/components/bibtemplate/dist/auro-bibtemplate.d.ts +7 -0
  2. package/components/bibtemplate/dist/index.js +9 -1
  3. package/components/bibtemplate/dist/registered.js +9 -1
  4. package/components/checkbox/demo/css-only.html +57 -0
  5. package/components/checkbox/demo/css-only.md +146 -0
  6. package/components/checkbox/demo/customize.min.js +2 -2
  7. package/components/checkbox/demo/getting-started.min.js +2 -2
  8. package/components/checkbox/demo/index.min.js +2 -2
  9. package/components/checkbox/demo/pages.json +1 -1
  10. package/components/checkbox/demo/styles.min.css +1 -1
  11. package/components/checkbox/demo/why-checkbox.html +57 -0
  12. package/components/checkbox/demo/why-checkbox.md +86 -0
  13. package/components/checkbox/dist/index.js +2 -2
  14. package/components/checkbox/dist/registered.js +2 -2
  15. package/components/combobox/demo/css-only.html +57 -0
  16. package/components/combobox/demo/css-only.md +209 -0
  17. package/components/combobox/demo/customize.md +7 -3
  18. package/components/combobox/demo/customize.min.js +1846 -1804
  19. package/components/combobox/demo/getting-started.min.js +1846 -1804
  20. package/components/combobox/demo/index.min.js +1846 -1804
  21. package/components/combobox/demo/pages.json +1 -1
  22. package/components/combobox/demo/styles.min.css +1 -1
  23. package/components/combobox/demo/why-combobox.html +57 -0
  24. package/components/combobox/demo/why-combobox.md +113 -0
  25. package/components/combobox/dist/auro-combobox.d.ts +5 -0
  26. package/components/combobox/dist/index.js +796 -179
  27. package/components/combobox/dist/registered.js +796 -179
  28. package/components/counter/demo/css-only.html +57 -0
  29. package/components/counter/demo/css-only.md +184 -0
  30. package/components/counter/demo/customize.min.js +276 -16
  31. package/components/counter/demo/index.min.js +276 -16
  32. package/components/counter/demo/keyboard-behavior.md +1 -0
  33. package/components/counter/demo/pages.json +1 -1
  34. package/components/counter/demo/styles.min.css +1 -1
  35. package/components/counter/demo/why-counter.html +57 -0
  36. package/components/counter/demo/why-counter.md +108 -0
  37. package/components/counter/dist/index.js +5457 -193
  38. package/components/counter/dist/registered.js +5457 -193
  39. package/components/datepicker/demo/accessibility.md +54 -3
  40. package/components/datepicker/demo/api.md +65 -55
  41. package/components/datepicker/demo/css-only.html +57 -0
  42. package/components/datepicker/demo/css-only.md +151 -0
  43. package/components/datepicker/demo/customize.html +2 -0
  44. package/components/datepicker/demo/customize.js +19 -0
  45. package/components/datepicker/demo/customize.md +474 -298
  46. package/components/datepicker/demo/customize.min.js +36243 -0
  47. package/components/datepicker/demo/design.md +5 -3
  48. package/components/datepicker/demo/getting-started.md +6 -6
  49. package/components/datepicker/demo/index.js +5 -1
  50. package/components/datepicker/demo/index.md +113 -16
  51. package/components/datepicker/demo/index.min.js +2735 -396
  52. package/components/datepicker/demo/keyboard-behavior.md +201 -2
  53. package/components/datepicker/demo/pages.json +1 -1
  54. package/components/datepicker/demo/styles.min.css +1 -1
  55. package/components/datepicker/demo/voiceover.md +21 -12
  56. package/components/datepicker/demo/why-datepicker.html +57 -0
  57. package/components/datepicker/demo/why-datepicker.md +133 -0
  58. package/components/datepicker/dist/index.js +2649 -397
  59. package/components/datepicker/dist/registered.js +2649 -397
  60. package/components/datepicker/dist/src/auro-calendar-cell.d.ts +116 -14
  61. package/components/datepicker/dist/src/auro-calendar-month.d.ts +54 -1
  62. package/components/datepicker/dist/src/auro-calendar.d.ts +264 -0
  63. package/components/datepicker/dist/src/auro-datepicker.d.ts +189 -53
  64. package/components/datepicker/dist/src/datepickerKeyboardStrategy.d.ts +5 -3
  65. package/components/datepicker/dist/src/utilities.d.ts +0 -14
  66. package/components/dropdown/demo/accessibility.md +11 -0
  67. package/components/dropdown/demo/api.md +1 -0
  68. package/components/dropdown/demo/css-only.html +57 -0
  69. package/components/dropdown/demo/css-only.md +219 -0
  70. package/components/dropdown/demo/customize.md +3 -0
  71. package/components/dropdown/demo/customize.min.js +265 -13
  72. package/components/dropdown/demo/getting-started.min.js +265 -13
  73. package/components/dropdown/demo/index.min.js +265 -13
  74. package/components/dropdown/demo/keyboard-behavior.md +1 -0
  75. package/components/dropdown/demo/pages.json +1 -1
  76. package/components/dropdown/demo/styles.min.css +1 -1
  77. package/components/dropdown/demo/why-dropdown.html +57 -0
  78. package/components/dropdown/demo/why-dropdown.md +97 -0
  79. package/components/dropdown/dist/auro-dropdown.d.ts +36 -1
  80. package/components/dropdown/dist/index.js +265 -13
  81. package/components/dropdown/dist/registered.js +265 -13
  82. package/components/form/demo/css-only.html +57 -0
  83. package/components/form/demo/css-only.md +156 -0
  84. package/components/form/demo/customize.min.js +11084 -8072
  85. package/components/form/demo/getting-started.min.js +11084 -8072
  86. package/components/form/demo/index.min.js +11084 -8072
  87. package/components/form/demo/pages.json +1 -1
  88. package/components/form/demo/registerDemoDeps.min.js +11083 -8071
  89. package/components/form/demo/styles.min.css +1 -1
  90. package/components/form/demo/why-form.html +57 -0
  91. package/components/form/demo/why-form.md +101 -0
  92. package/components/input/demo/css-only.html +57 -0
  93. package/components/input/demo/css-only.md +199 -0
  94. package/components/input/demo/customize.md +625 -636
  95. package/components/input/demo/customize.min.js +150 -75
  96. package/components/input/demo/getting-started.md +16 -6
  97. package/components/input/demo/getting-started.min.js +150 -75
  98. package/components/input/demo/index.min.js +150 -75
  99. package/components/input/demo/pages.json +1 -1
  100. package/components/input/demo/styles.min.css +1 -1
  101. package/components/input/demo/why-input.html +57 -0
  102. package/components/input/demo/why-input.md +121 -0
  103. package/components/input/dist/auro-input-util.d.ts +1 -1
  104. package/components/input/dist/base-input.d.ts +16 -0
  105. package/components/input/dist/index.js +150 -75
  106. package/components/input/dist/registered.js +150 -75
  107. package/components/input/dist/utilities.d.ts +1 -2
  108. package/components/menu/demo/api.md +41 -45
  109. package/components/menu/demo/css-only.html +57 -0
  110. package/components/menu/demo/css-only.md +166 -0
  111. package/components/menu/demo/customize.md +0 -28
  112. package/components/menu/demo/index.min.js +779 -1354
  113. package/components/menu/demo/pages.json +1 -1
  114. package/components/menu/demo/styles.min.css +1 -1
  115. package/components/menu/demo/why-menu.html +57 -0
  116. package/components/menu/demo/why-menu.md +104 -0
  117. package/components/menu/dist/auro-menu.d.ts +95 -110
  118. package/components/menu/dist/auro-menuoption.d.ts +32 -138
  119. package/components/menu/dist/index.js +753 -1308
  120. package/components/menu/dist/registered.js +765 -1308
  121. package/components/radio/demo/css-only.html +57 -0
  122. package/components/radio/demo/css-only.md +151 -0
  123. package/components/radio/demo/customize.min.js +1764 -0
  124. package/components/radio/demo/demo-support.min.js +55807 -0
  125. package/components/radio/demo/getting-started.js +1 -1
  126. package/components/radio/demo/getting-started.md +1 -1
  127. package/components/radio/demo/getting-started.min.js +1783 -0
  128. package/components/radio/demo/index.min.js +2 -2
  129. package/components/radio/demo/pages.json +1 -1
  130. package/components/radio/demo/styles.min.css +1 -1
  131. package/components/radio/demo/why-radio.html +57 -0
  132. package/components/radio/demo/why-radio.md +92 -0
  133. package/components/radio/dist/index.js +2 -2
  134. package/components/radio/dist/registered.js +2 -2
  135. package/components/select/demo/api.md +1 -0
  136. package/components/select/demo/css-only.html +57 -0
  137. package/components/select/demo/css-only.md +203 -0
  138. package/components/select/demo/customize.md +78 -3
  139. package/components/select/demo/customize.min.js +1341 -1533
  140. package/components/select/demo/getting-started.min.js +1341 -1533
  141. package/components/select/demo/index.min.js +1341 -1533
  142. package/components/select/demo/keyboard-behavior.md +19 -0
  143. package/components/select/demo/pages.json +1 -1
  144. package/components/select/demo/styles.min.css +1 -1
  145. package/components/select/demo/why-select.html +57 -0
  146. package/components/select/demo/why-select.md +128 -0
  147. package/components/select/dist/auro-select.d.ts +38 -2
  148. package/components/select/dist/index.js +435 -52
  149. package/components/select/dist/registered.js +435 -52
  150. package/components/select/dist/selectUtils.d.ts +12 -0
  151. package/custom-elements.json +4206 -3708
  152. package/package.json +8 -8
  153. package/components/menu/dist/auro-menu.context.d.ts +0 -238
package/components/combobox/demo/css-only.html ADDED
@@ -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/css-only.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-combobox | CSS only</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-combobox'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('./css-only.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>
package/components/combobox/demo/css-only.md ADDED
@@ -0,0 +1,209 @@
1
+ <auro-header level="1">CSS only with native input and datalist</auro-header>
2
+ <p>For situations where the <code>&lt;auro-combobox&gt;</code> web component cannot be used, a native HTML <code>&lt;input type="text"&gt;</code> paired with a <code>&lt;datalist&gt;</code> element can be styled with the Auro Design System tokens to approximate the visual appearance of <code>auro-combobox</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>.combobox</code> class, so the styling must be authored manually using Auro design tokens.</p>
3
+ <auro-header level="2">Styling a native input with datalist</auro-header>
4
+ <p>The native input 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 size, border, and focus-state colors used by the <code>auro-combobox</code> trigger input.</p>
5
+ <pre><code>@import "./node_modules/@aurodesignsystem/design-tokens/dist/tokens/CSSCustomProperties.css";
6
+ ​
7
+ .combobox {
8
+ display: inline-block;
9
+ position: relative;
10
+ width: 100%;
11
+ }
12
+ ​
13
+ .combobox-label {
14
+ display: block;
15
+ font-size: var(--ds-size-150, 0.75rem);
16
+ color: var(--ds-color-text-secondary-default, #6e767f);
17
+ margin-bottom: var(--ds-size-50, 0.25rem);
18
+ }
19
+ ​
20
+ .combobox-input {
21
+ appearance: none;
22
+ -webkit-appearance: none;
23
+ width: 100%;
24
+ height: var(--ds-size-600, 3rem);
25
+ padding: 0 var(--ds-size-200, 1rem);
26
+ font-size: var(--ds-size-200, 1rem);
27
+ color: var(--ds-color-text-primary-default, #00256c);
28
+ background-color: var(--ds-color-container-primary-default, #ffffff);
29
+ border: 1px solid var(--ds-color-border-ui-default, #6e767f);
30
+ border-radius: var(--ds-border-radius, 4px);
31
+ box-sizing: border-box;
32
+ }
33
+ ​
34
+ .combobox-input:focus-visible {
35
+ outline: 2px solid var(--ds-color-border-active-default, #01426a);
36
+ outline-offset: 2px;
37
+ border-color: var(--ds-color-border-active-default, #01426a);
38
+ }
39
+ ​
40
+ .combobox-input:disabled {
41
+ cursor: not-allowed;
42
+ opacity: 0.5;
43
+ background-color: var(--ds-color-container-disabled-default, #f2f3f5);
44
+ }
45
+ ​
46
+ .combobox-input[aria-invalid="true"] {
47
+ border-color: var(--ds-color-border-error-default, #d23153);
48
+ }</code></pre>
49
+ <auro-header level="3">Basic combobox</auro-header>
50
+ <p>Apply the <code>.combobox-input</code> class to a native <code>&lt;input type="text"&gt;</code> element and reference a <code>&lt;datalist&gt;</code> via the <code>list</code> attribute:</p>
51
+ <pre><code>&lt;label class="combobox"&gt;
52
+ &lt;span class="combobox-label"&gt;Departure airport&lt;/span&gt;
53
+ &lt;input
54
+ type="text"
55
+ class="combobox-input"
56
+ name="departure"
57
+ list="airport-options"
58
+ autocomplete="off" /&gt;
59
+ &lt;datalist id="airport-options"&gt;
60
+ &lt;option value="Seattle (SEA)"&gt;&lt;/option&gt;
61
+ &lt;option value="Portland (PDX)"&gt;&lt;/option&gt;
62
+ &lt;option value="San Francisco (SFO)"&gt;&lt;/option&gt;
63
+ &lt;option value="Los Angeles (LAX)"&gt;&lt;/option&gt;
64
+ &lt;/datalist&gt;
65
+ &lt;/label&gt;</code></pre>
66
+ <auro-header level="3">Required combobox in a form</auro-header>
67
+ <p>Use the native <code>required</code> attribute to enforce that a value is entered before form submission:</p>
68
+ <pre><code>&lt;form&gt;
69
+ &lt;label class="combobox"&gt;
70
+ &lt;span class="combobox-label"&gt;Destination&lt;/span&gt;
71
+ &lt;input
72
+ type="text"
73
+ class="combobox-input"
74
+ name="destination"
75
+ list="destination-options"
76
+ required
77
+ autocomplete="off" /&gt;
78
+ &lt;datalist id="destination-options"&gt;
79
+ &lt;option value="Anchorage (ANC)"&gt;&lt;/option&gt;
80
+ &lt;option value="Fairbanks (FAI)"&gt;&lt;/option&gt;
81
+ &lt;option value="Juneau (JNU)"&gt;&lt;/option&gt;
82
+ &lt;/datalist&gt;
83
+ &lt;/label&gt;
84
+ &lt;button type="submit"&gt;Search&lt;/button&gt;
85
+ &lt;/form&gt;</code></pre>
86
+ <auro-header level="2">What you lose without auro-combobox</auro-header>
87
+ <p>While the CSS above replicates the <strong>visual styling</strong> of the <code>auro-combobox</code> trigger, the following functionality built into the <code>auro-combobox</code> web component is <strong>not available</strong> when using plain HTML with a <code>&lt;datalist&gt;</code>:</p>
88
+ <auro-header level="3">Filter vs. suggestion behavior</auro-header>
89
+ <p><code>auro-combobox</code> exposes a <code>behavior</code> attribute (<code>"filter"</code> or <code>"suggestion"</code>) that controls whether the user must select a menu option or may submit a freeform typed value. Native <code>&lt;datalist&gt;</code> always behaves like suggestion mode — there is no way to require the user to choose from the list without writing custom JavaScript to compare the input value against the option set.</p>
90
+ <auro-header level="3">Custom filtering and matching</auro-header>
91
+ <p><code>auro-combobox</code> filters options against the typed value and supports a <code>suggest</code> attribute on each menu option for additional matching keywords, plus <code>persistent</code>, <code>static</code>, and <code>nomatch</code> options that change how the list reacts to input. <code>&lt;datalist&gt;</code> matching is browser-controlled, varies across browsers, and cannot be extended with synonyms, persistent items, or a "no match" placeholder.</p>
92
+ <auro-header level="3">Highlighted match text</auro-header>
93
+ <p><code>auro-combobox</code> passes the typed value to <code>auro-menu</code> as a <code>matchWord</code> so the matching substring is visually highlighted in each option. Native <code>&lt;datalist&gt;</code> renders options using the browser's default UI with no control over typography, highlight color, or layout of the option content.</p>
94
+ <auro-header level="3">Custom validation messages</auro-header>
95
+ <p><code>auro-combobox</code> exposes <code>setCustomValidity</code>, <code>setCustomValidityCustomError</code>, <code>setCustomValidityValueMissing</code>, and <code>setCustomValidityValueMissingFilter</code> for fully customizable error messages per validity state, including a distinct message for "did not pick a value from the list" when <code>behavior="filter"</code>. Native inputs surface browser-controlled validation messages that cannot be customized beyond a single <code>setCustomValidity()</code> string.</p>
96
+ <auro-header level="3">Touched-state tracking</auro-header>
97
+ <p><code>auro-combobox</code> tracks a <code>touched</code> state so validation errors only appear after the user has interacted with the field. Native inputs have no built-in touched concept — you must implement focus/blur tracking yourself to avoid showing errors on initial render.</p>
98
+ <auro-header level="3">Keyboard navigation and ARIA</auro-header>
99
+ <p><code>auro-combobox</code> implements the WAI-ARIA combobox pattern: <code>role="combobox"</code> on the input, <code>aria-expanded</code>, <code>aria-controls</code>, <code>aria-activedescendant</code>, and <code>aria-setsize</code>/<code>aria-posinset</code> on each option, plus arrow-key navigation, Home/End, Escape to close, and Enter to select. <code>&lt;datalist&gt;</code> exposes none of these hooks — keyboard behavior is whatever the browser provides, and the experience differs substantially between Chrome, Safari, and Firefox.</p>
100
+ <auro-header level="3">Screen reader announcements</auro-header>
101
+ <p><code>auro-combobox</code> dispatches live-region announcements when an option becomes active ("Seattle, not selected, 1 of 5") and when an option is selected, including special handling for fullscreen dialog mode where the trigger is inert. <code>&lt;datalist&gt;</code> announcements depend entirely on the assistive technology and browser combination.</p>
102
+ <auro-header level="3">Mobile fullscreen presentation</auro-header>
103
+ <p><code>auro-combobox</code> automatically switches to a fullscreen dialog at a configurable <code>fullscreenBreakpoint</code> for mobile-friendly input, including iOS virtual keyboard retention logic so the keyboard stays visible across the trigger-to-dialog transition. Native <code>&lt;datalist&gt;</code> renders an inline dropdown on every device with no fullscreen mode.</p>
104
+ <auro-header level="3">Rich option content and display value</auro-header>
105
+ <p><code>auro-combobox</code> works with <code>auro-menuoption</code> elements that can contain markup, icons, and a <code>displayValue</code> slot that lets the visible trigger content differ from the underlying value (paired with <code>persistInput</code> for advanced filter UIs). <code>&lt;datalist&gt;</code> options are plain strings — no markup, no icons, and the visible value always equals the submitted value.</p>
106
+ <auro-header level="3">Coordinated value and option-selected state</auro-header>
107
+ <p><code>auro-combobox</code> exposes both <code>value</code> (the selected option's value) and <code>optionSelected</code> (a reference to the chosen <code>auro-menuoption</code> element), and fires <code>input</code> and <code>inputValue</code> events with structured detail. With native HTML, you only get the input's string value — there is no concept of which datalist option the user picked because the browser does not report it.</p>
108
+ <auro-header level="3">Form integration events</auro-header>
109
+ <p><code>auro-combobox</code> dispatches <code>auroFormElement-validated</code> events so parent <code>auro-form</code> elements can coordinate validation across all child fields. Native inputs participate in form submission but do not emit the structured validation events that the Auro form system expects.</p>
110
+ <auro-header level="3">Reset behavior</auro-header>
111
+ <p><code>auro-combobox</code> provides <code>reset()</code> and <code>clear()</code> methods that clear the input, menu selection, validation state, and touched flag in one call. With native HTML, you must clear the input value and separately reset any custom validation state you are tracking.</p>
112
+ <auro-header level="3">Layouts, shapes, and sizes</auro-header>
113
+ <p><code>auro-combobox</code> supports <code>layout</code> (<code>classic</code>, <code>emphasized</code>, <code>snowflake</code>), <code>shape</code>, and <code>size</code> attributes that coordinate the appearance of the trigger, dropdown, and menu options together. With native HTML, every variant must be authored from scratch and the dropdown UI cannot be restyled at all.</p>
114
+ <auro-header level="3">Multi-brand theming</auro-header>
115
+ <p><code>auro-combobox</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 input is tied to whichever tokens were imported at author time and will not respond to runtime theme switching the way the web component does. The browser-rendered <code>&lt;datalist&gt;</code> popup cannot be themed at all.</p>
116
+ <auro-header level="2">Summary</auro-header>
117
+ <table>
118
+ <thead>
119
+ <tr>
120
+ <th>Feature</th>
121
+ <th>Native <code>&lt;input list&gt;</code> + <code>&lt;datalist&gt;</code> with Auro tokens</th>
122
+ <th><code>auro-combobox</code></th>
123
+ </tr>
124
+ </thead>
125
+ <tbody>
126
+ <tr>
127
+ <td>Design-system-aligned trigger styling</td>
128
+ <td>Manual (author-written CSS)</td>
129
+ <td>Built-in</td>
130
+ </tr>
131
+ <tr>
132
+ <td>Styled dropdown / option list</td>
133
+ <td>Browser-controlled, not styleable</td>
134
+ <td>Fully themed via <code>auro-menu</code></td>
135
+ </tr>
136
+ <tr>
137
+ <td>Filter vs. suggestion behavior</td>
138
+ <td>Suggestion only</td>
139
+ <td><code>behavior="filter" | "suggestion"</code></td>
140
+ </tr>
141
+ <tr>
142
+ <td>Custom match keywords / persistent / nomatch options</td>
143
+ <td>Not supported</td>
144
+ <td>Built-in option attributes</td>
145
+ </tr>
146
+ <tr>
147
+ <td>Highlighted match text</td>
148
+ <td>Not supported</td>
149
+ <td>Built-in via <code>matchWord</code></td>
150
+ </tr>
151
+ <tr>
152
+ <td>Custom validation messages</td>
153
+ <td>Limited to <code>setCustomValidity()</code></td>
154
+ <td>Per-constraint custom messages</td>
155
+ </tr>
156
+ <tr>
157
+ <td>Touched-state tracking</td>
158
+ <td>Manual</td>
159
+ <td>Automatic</td>
160
+ </tr>
161
+ <tr>
162
+ <td>ARIA combobox pattern</td>
163
+ <td>Inconsistent across browsers</td>
164
+ <td>Full WAI-ARIA combobox implementation</td>
165
+ </tr>
166
+ <tr>
167
+ <td>Screen reader option announcements</td>
168
+ <td>Browser-dependent</td>
169
+ <td>Live-region announcements</td>
170
+ </tr>
171
+ <tr>
172
+ <td>Mobile fullscreen mode</td>
173
+ <td>Not supported</td>
174
+ <td><code>fullscreenBreakpoint</code> attribute</td>
175
+ </tr>
176
+ <tr>
177
+ <td>Rich option content / display value</td>
178
+ <td>Plain strings only</td>
179
+ <td><code>auro-menuoption</code> + <code>displayValue</code> slot</td>
180
+ </tr>
181
+ <tr>
182
+ <td><code>optionSelected</code> reference</td>
183
+ <td>Not available</td>
184
+ <td>Exposed as a property</td>
185
+ </tr>
186
+ <tr>
187
+ <td>Form validation events</td>
188
+ <td>Not supported</td>
189
+ <td><code>auroFormElement-validated</code></td>
190
+ </tr>
191
+ <tr>
192
+ <td>Reset / clear</td>
193
+ <td>Manual</td>
194
+ <td><code>reset()</code> and <code>clear()</code> methods</td>
195
+ </tr>
196
+ <tr>
197
+ <td>Layout, shape, size variants</td>
198
+ <td>Manual CSS</td>
199
+ <td><code>layout</code>, <code>shape</code>, <code>size</code> attributes</td>
200
+ </tr>
201
+ <tr>
202
+ <td>Multi-brand theming</td>
203
+ <td>Static (import-time tokens)</td>
204
+ <td>Full (design tokens + component logic)</td>
205
+ </tr>
206
+ </tbody>
207
+ </table>
208
+ <auro-header level="2">Recommendation</auro-header>
209
+ <p>Use <code>auro-combobox</code> whenever possible. Fall back to a CSS-styled native <code>&lt;input list&gt;</code> with a <code>&lt;datalist&gt;</code> only in environments where custom elements are not supported or when integrating with third-party systems that require plain HTML — and be prepared to accept browser-controlled dropdown styling, inconsistent keyboard and screen reader behavior, and the loss of filter-mode validation, match highlighting, fullscreen presentation, and structured form integration.</p>
package/components/combobox/demo/customize.md CHANGED
@@ -556,9 +556,11 @@
556
556
  <auro-combobox class="css-parts-demo">
557
557
  <span slot="label">CSS Parts Example</span>
558
558
  <span slot="helpText">This combobox has custom styles applied via CSS Shadow Parts.</span>
559
+ <auro-menu>
559
560
  <auro-menuoption value="one">Option One</auro-menuoption>
560
561
  <auro-menuoption value="two">Option Two</auro-menuoption>
561
562
  <auro-menuoption value="three">Option Three</auro-menuoption>
563
+ </auro-menu>
562
564
  </auro-combobox>
563
565
  <!-- AURO-GENERATED-CONTENT:END -->
564
566
  </div>
@@ -584,9 +586,11 @@
584
586
  &lt;auro-combobox class="css-parts-demo"&gt;
585
587
  &lt;span slot="label"&gt;CSS Parts Example&lt;/span&gt;
586
588
  &lt;span slot="helpText"&gt;This combobox has custom styles applied via CSS Shadow Parts.&lt;/span&gt;
587
- &lt;auro-menuoption value="one"&gt;Option One&lt;/auro-menuoption&gt;
588
- &lt;auro-menuoption value="two"&gt;Option Two&lt;/auro-menuoption&gt;
589
- &lt;auro-menuoption value="three"&gt;Option Three&lt;/auro-menuoption&gt;
589
+ &lt;auro-menu&gt;
590
+ &lt;auro-menuoption value="one"&gt;Option One&lt;/auro-menuoption&gt;
591
+ &lt;auro-menuoption value="two"&gt;Option Two&lt;/auro-menuoption&gt;
592
+ &lt;auro-menuoption value="three"&gt;Option Three&lt;/auro-menuoption&gt;
593
+ &lt;/auro-menu&gt;
590
594
  &lt;/auro-combobox&gt;</code></pre>
591
595
  <!-- AURO-GENERATED-CONTENT:END -->
592
596
  </auro-accordion>