@aurodesignsystem-dev/auro-formkit 0.0.0-pr1422.0 → 0.0.0-pr1422.2

package/components/combobox/demo/keyboardBehavior.md

@@ -0,0 +1,281 @@
+<auro-header level="1" id="overview">Combobox - Keyboard Behavior</auro-header>
+<div class="contentWrapper">
+  <div class="mainContent">
+    <div class="scrollWrapper">
+      <auro-header level="2" id="tabBehavior">Tab Behavior</auro-header>
+      <p>The component trigger contains an <code>&lt;auro-input&gt;</code> which has two elements:</p>
+      <ol>
+        <li><strong>Input</strong></li>
+        <li><strong>Clear button:</strong> only shown when the input has a value.</li>
+      </ol>
+      <p>Each focusable element <em>(when shown)</em> participates in the browser window's default <code>tabindex</code> sequence.</p>
+      <p>When the component is <code>disabled</code> it is removed from the <code>tabindex</code> sequence. VoiceOver's virtual cursor <em>(swipe navigation)</em> can still encounter the component, but standard keyboard <code>Tab</code> navigation skips it.</p>
+      <p>On <strong>large viewport devices</strong> (e.g., desktop browser, tablet) there is no focusable content inside the component bib.</p>
+      <p>On <strong>small viewport devices</strong> (e.g., phone) the bib opens a modal dialog with a focusable <strong>input</strong> and <strong>clear button</strong> which can receive <strong>Click</strong> and <strong>Tap</strong> events.</p>
+      <auro-header level="2" id="keyEvents">Key Events</auro-header>
+      <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/keyEvents.md) -->
+      <!-- The below content is automatically added from ./../docs/partials/keyEvents.md -->
+      <div class="note">
+        <p><strong>Static vs Dynamic Option List:</strong> The <strong>expanded</strong> state can never be applied without list options rendered into the DOM. Since the component supports dynamic option lists generated <em>after</em> a value is typed into the <strong>input</strong>, certain key events (as noted in the <strong>Current State</strong> column of the table below) only function with the option list rendered into the DOM.</p>
+      </div>
+      <table>
+        <thead>
+          <tr>
+            <th>Key</th>
+            <th>Modifier</th>
+            <th>Current State</th>
+            <th>Focus Element</th>
+            <th>Behavior</th>
+          </tr>
+        </thead>
+        <tbody>
+          <tr>
+            <td rowspan="6">ArrowDown</td>
+            <td rowspan="2">-</td>
+            <td>Collapsed, list options have been populated</td>
+            <td>
+              Trigger input element, <strong>NOT</strong> the trigger input clear button
+            </td>
+            <td>Opens the bib.</td>
+          </tr>
+          <tr>
+            <td>Expanded</td>
+            <td>
+              Input element, <strong>NOT</strong> the input clear button
+              <div class="note">
+                <strong>Note:</strong> Includes both trigger and bib content inputs depending on viewport size.
+              </div>
+            </td>
+            <td>
+              Advances the <code>focused</code> option to the next enabled option in the list. If the current <code>focused</code> option is the last enabled option, selection wraps to the first enabled option.
+            </td>
+          </tr>
+          <tr>
+            <td rowspan="2">Command</td>
+            <td>Collapsed, list options have been populated</td>
+            <td>
+              Trigger input element, <strong>NOT</strong> the trigger input clear button
+            </td>
+            <td>Opens the bib.</td>
+          </tr>
+          <tr>
+            <td>Expanded</td>
+            <td>
+              Input element, <strong>NOT</strong> the input clear button
+              <div class="note">
+                <strong>Note:</strong> Includes both trigger and bib content inputs.
+              </div>
+            </td>
+            <td>
+              Advances the <code>focused</code> option to the last enabled option in the list.
+            </td>
+          </tr>
+          <tr>
+            <td rowspan="2">Option</td>
+            <td>Collapsed, list options have been populated</td>
+            <td>
+              Trigger input element, <strong>NOT</strong> the trigger input clear button
+            </td>
+            <td>Opens the bib.</td>
+          </tr>
+          <tr>
+            <td>Expanded</td>
+            <td>
+              Input element, <strong>NOT</strong> the input clear button
+              <div class="note">
+                <strong>Note:</strong> Includes both trigger and bib content inputs.
+              </div>
+            </td>
+            <td>
+              Advances the <code>focused</code> option to the last enabled option in the list.
+            </td>
+          </tr>
+          <tr>
+            <td rowspan="6">ArrowUp</td>
+            <td rowspan="2">-</td>
+            <td>Collapsed, list options have been populated</td>
+            <td>
+              Trigger input element, <strong>NOT</strong> the trigger input clear button
+            </td>
+            <td>Opens the bib.</td>
+          </tr>
+          <tr>
+            <td>Expanded</td>
+            <td>
+              Input element, <strong>NOT</strong> the input clear button
+              <div class="note">
+                <strong>Note:</strong> Includes both trigger and bib content inputs.
+              </div>
+            </td>
+            <td>
+              Advances the <code>focused</code> option to the previous enabled option in the list. If the current <code>focused</code> option is the first enabled option, selection wraps to the last enabled option.
+            </td>
+          </tr>
+          <tr>
+            <td rowspan="2">Command</td>
+            <td>Collapsed, list options have been populated</td>
+            <td>
+              Trigger input element, <strong>NOT</strong> the trigger input clear button
+            </td>
+            <td>Opens the bib.</td>
+          </tr>
+          <tr>
+            <td>Expanded</td>
+            <td>
+              Input element, <strong>NOT</strong> the input clear button
+              <div class="note">
+                <strong>Note:</strong> Includes both trigger and bib content inputs.
+              </div>
+            </td>
+            <td>
+              Advances the <code>focused</code> option to the first enabled option in the list.
+            </td>
+          </tr>
+          <tr>
+            <td rowspan="2">Option</td>
+            <td>Collapsed, list options have been populated</td>
+            <td>
+              Input element, <strong>NOT</strong> the input clear button
+            </td>
+            <td>Opens the bib.</td>
+          </tr>
+          <tr>
+            <td>Expanded</td>
+            <td>
+              Input element, <strong>NOT</strong> the input clear button
+              <div class="note">
+                <strong>Note:</strong> Includes both trigger and bib content inputs.
+              </div>
+            </td>
+            <td>
+              Advances the <code>focused</code> option to the first enabled option in the list.
+            </td>
+          </tr>
+          <tr>
+            <td>End</td>
+            <td>-</td>
+            <td>Expanded</td>
+            <td>
+              Input element, <strong>NOT</strong> the input clear button
+              <div class="note">
+                <strong>Note:</strong> Includes both trigger and bib content inputs.
+              </div>
+            </td>
+            <td>
+              Advances the <code>focused</code> option to the last enabled option in the list.
+            </td>
+          </tr>
+          <tr>
+            <td rowspan="4">Enter</td>
+            <td rowspan="4">-</td>
+            <td>Collapsed, list options have been populated</td>
+            <td>
+              Trigger input, <strong>NOT</strong> the input clear button
+            </td>
+            <td>
+             The bib is opened.
+            </td>
+          </tr>
+          <tr>
+            <td>Collapsed</td>
+            <td>
+              Input clear button, <strong>NOT</strong> the input element
+            </td>
+            <td>
+              The <strong>input</strong> value is cleared, <strong>focus</strong> moves to the trigger input element.
+            </td>
+          </tr>
+          <tr>
+            <td>Expanded, large viewport device</td>
+            <td>
+              Trigger input element, <strong>NOT</strong> the trigger input clear button
+            </td>
+            <td>
+              The current <code>focused</code> option is selected, closes the bib and <strong>focus</strong> is returned to the trigger input element.
+            </td>
+          </tr>
+          <tr>
+            <td>Expanded, small viewport device</td>
+            <td>
+              Dialog input element, <strong>NOT</strong> the dialog input clear button
+            </td>
+            <td>
+              The current <code>focused</code> option is selected, closes the bib and <strong>focus</strong> is returned to the trigger input element.
+            </td>
+          </tr>
+          <tr>
+            <td>Escape</td>
+            <td>-</td>
+            <td>Expanded</td>
+            <td>
+              Input element, <strong>NOT</strong> the input clear button
+              <div class="note">
+                <strong>Note:</strong> Includes both trigger and bib content inputs.
+              </div>
+            </td>
+            <td>
+              Closes the bib, moves <strong>focus</strong> to the trigger input element.
+            </td>
+          </tr>
+          <tr>
+            <td>Home</td>
+            <td>-</td>
+            <td>Expanded</td>
+            <td>
+              Input element, <strong>NOT</strong> the input clear button
+              <div class="note">
+                <strong>Note:</strong> Includes both trigger and bib content inputs.
+              </div>
+            </td>
+            <td>
+              Advances the <code>focused</code> option to the first enabled option in the list.
+            </td>
+          </tr>
+          <tr>
+            <td rowspan="2">Tab</td>
+            <td>-</td>
+            <td>Expanded</td>
+            <td>
+              Input element, <strong>NOT</strong> the input clear button
+              <div class="note">
+                <strong>Note:</strong> Includes both trigger and bib content inputs.
+              </div>
+            </td>
+            <td>
+              The current <code>focused</code> option is selected, the bib is closed and <strong>focus</strong> is moved to the <strong>clear button</strong> in the component trigger.
+            </td>
+          </tr>
+          <tr>
+            <td>Shift</td>
+            <td>Expanded</td>
+            <td>
+              Input element, <strong>NOT</strong> the input clear button
+              <div class="note">
+                <strong>Note:</strong> Includes both trigger and bib content inputs.
+              </div>
+            </td>
+            <td>
+              Advances the <code>focused</code> option to the first enabled option in the list.
+              <div class="note">
+                <strong>Note:</strong> the bib will <strong>NOT</strong> close and the page will <strong>NOT</strong> navigate to the previous focusable element in the tabindex order.
+              </div>
+            </td>
+          </tr>
+        </tbody>
+      </table>
+      <!-- AURO-GENERATED-CONTENT:END -->
+      <div class="note">
+        <p><strong>Note:</strong> The following keyboard behavior is unsupported at this time:</p>
+        <ul>
+          <li><strong>PageUp:</strong> The browser moves the <code>focused</code> option up by approximately one <strong>page</strong> of visible options (typically equal to the number of rendered rows). The scroll position updates in tandem so that the newly focused option is brought into view, usually aligning near the top of the visible list.</li>
+          <li><strong>PageDown:</strong> The browser advances the <code>focused</code> option down by approximately one <strong>page</strong> of visible items (typically equal to the number of rendered rows). The scroll position updates accordingly so the newly focused option is brought into view, often aligning near the bottom of the visible list.</li>
+        </ul>
+      </div>
+    </div>
+  </div>
+</div>
+
+## DEVELOPER NOTES / CODE ACTION ITEMS / TODO ITEMS
+1. Remove the bridge for keyboard event bubbling out of the bib
+1. Prevent auro-dropdown `Enter` and `Space` key behavior for opening and closing the bib.
+1. Strip out key event listeners not listed in this document

package/components/combobox/demo/readme.md

@@ -0,0 +1,158 @@
+<!--
+The README.md file is a compiled document. No edits should be made directly to this file.
+
+README.md is created by running `npm run build:docs`.
+
+This file is generated based on a template fetched from
+`../../docs/templates/componentReadmeTemplate.md`
+and copied to `./componentDocs/README.md` each time the docs are compiled.
+
+The following sections are editable by making changes to the following files:
+
+| SECTION                | DESCRIPTION                                       | FILE LOCATION                       |
+|------------------------|---------------------------------------------------|-------------------------------------|
+| Description            | Description of the component                      | `./docs/partials/description.md`    |
+| Use Cases              | Examples for when to use this component           | `./docs/partials/useCases.md`       |
+| Additional Information | For use to add any component specific information | `./docs/partials/readmeAddlInfo.md` |
+| Component Example Code | HTML sample code of the components use            | `./apiExamples/basic.html`          |
+-->
+
+# Combobox
+
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./docs/partials/description.md) -->
+<!-- The below content is automatically added from ./docs/partials/description.md -->
+`<auro-combobox>` is the combination of [dropdown](http://auro.alaskaair.com/components/auro/dropdown), [input](http://auro.alaskaair.com/components/auro/input), and [menu](http://auro.alaskaair.com/components/auro/menu) and allows users to filter search results from a predefined list as they type. When the user starts typing in the text input, a dropdown of a menu shows up to display options that match the user’s search.
+
+By default, `auro-combobox` behaves as a suggestion list. This means any value may be typed into the combobox and the menu list presented effectively provides sample or suggestion options. With the use of the `persistInput` attribute the `auro-combobox` behaves as a filter of menu options. In this mode. typing into the input field will execute the filter but will not set the `value` of the combobox. The combobox value is set by selecting a menu option. Clicking the `X` clear button in the input will remove the current value of the HTML5 input causing the menu filter to reset as well as remove the current value of the combobox.
+<!-- AURO-GENERATED-CONTENT:END -->
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./docs/partials/readmeAddlInfo.md) -->
+<!-- The below content is automatically added from ./docs/partials/readmeAddlInfo.md -->
+<!-- AURO-GENERATED-CONTENT This file is to be used for any additional content that should be included in the README.md which is specific to this component. -->
+<!-- AURO-GENERATED-CONTENT:END -->
+
+## Combobox Use Cases
+
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./docs/partials/useCases.md) -->
+<!-- The below content is automatically added from ./docs/partials/useCases.md -->
+The `<auro-combobox>` element should be used in situations where users may:
+
+* Search
+  * Airports: user looks for a specific airport by searching for the city name or airport code
+  * Site wide: user searches for a topic site wide and combobox makes suggestions on searchable results
+* Filter
+  * Options: user chooses filters for their search by using combobox
+* Select
+  * Quantity: user types a quantity to select an option within a range (for example, the user may be limited to 2-34)
+<!-- AURO-GENERATED-CONTENT:END -->
+
+## Getting Started
+
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=../../docs/templates/componentInstall.md) -->
+<!-- The below content is automatically added from ../../docs/templates/componentInstall.md -->
+
+#### NPM Installation
+
+```shell
+$ npm i @aurodesignsystem/auro-formkit
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=../../docs/templates/gettingStarted.md) -->
+<!-- The below content is automatically added from ../../docs/templates/gettingStarted.md -->
+
+### TypeScript Module Resolution
+
+When using TypeScript set `moduleResolution` to `bundler`, add the following to your `tsconfig.json`:
+
+```json
+{
+    "compilerOptions": {
+        "moduleResolution": "bundler"
+    }
+}
+```
+
+This configuration enables proper module resolution for the component's TypeScript files.
+<!-- AURO-GENERATED-CONTENT:END -->
+
+## Install from CDN
+
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=../../docs/templates/bundleInstallDescription.md) -->
+<!-- The below content is automatically added from ../../docs/templates/bundleInstallDescription.md -->
+In cases where the project is not able to process JS assets, there are pre-processed assets available for use. Legacy browsers such as IE11 are no longer supported.
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-formkit@latest/auro-combobox/+esm"></script>
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+
+## Formkit Development
+
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=../../docs/partials/developmentDescription.md) -->
+<!-- The below content is automatically added from ../../docs/partials/developmentDescription.md -->
+
+### Filtering
+
+Running the `dev` command will open a `localhost` development server for all components in the monorepo at once.
+
+To only develop a single component, use the `--filter` flag:
+
+```shell
+npx turbo dev --filter=@aurodesignsystem/auro-input
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./docs/partials/customRegistration.md) -->
+<!-- The below content is automatically added from ./docs/partials/customRegistration.md -->
+
+## Custom Component Registration for Version Management
+
+There are two key parts to every Auro component: the <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes">class</a> and the custom element definition. The class defines the component’s behavior, while the custom element registers it under a specific name so it can be used in HTML.
+
+When you install the component as described on the `Install` page, the class is imported automatically, and the component is registered globally for you.
+
+However, if you need to load multiple versions of the same component on a single page (for example, when two projects depend on different versions), you can manually register the class under a custom element name to avoid conflicts.
+
+You can do this by importing only the component class and using the `register(name)` method with a unique name:
+
+```js
+// Import the class only
+import { AuroCombobox } from '@aurodesignsystem/auro-formkit/auro-combobox/class';
+
+// Register with a custom name if desired
+AuroCombobox.register('custom-combobox');
+```
+
+This will create a new custom element `<custom-combobox>` that behaves exactly like `<auro-combobox>`, allowing both to coexist on the same page without interfering with each other.
+
+<div class="exampleWrapper exampleWrapper--flex">
+  <custom-combobox>
+    <span slot="bib.fullscreen.headline">Bib Header</span>
+    <span slot="label">Name</span>
+    <auro-menu>
+      <auro-menuoption value="Apples" id="option-0">Apples</auro-menuoption>
+      <auro-menuoption value="Oranges" id="option-1">Oranges</auro-menuoption>
+      <auro-menuoption value="Peaches" id="option-2">Peaches</auro-menuoption>
+      <auro-menuoption value="Grapes" id="option-3">Grapes</auro-menuoption>
+      <auro-menuoption value="Cherries" id="option-4">Cherries</auro-menuoption>
+      <auro-menuoption static nomatch>No matching option</auro-menuoption>
+    </auro-menu>
+  </custom-combobox>
+</div>
+<auro-accordion alignRight>
+  <span slot="trigger">See code</span>
+
+```html
+  <custom-combobox>
+    <span slot="bib.fullscreen.headline">Bib Header</span>
+    <span slot="label">Name</span>
+    <auro-menu>
+      <auro-menuoption value="Apples" id="option-0">Apples</auro-menuoption>
+      <auro-menuoption value="Oranges" id="option-1">Oranges</auro-menuoption>
+      <auro-menuoption value="Peaches" id="option-2">Peaches</auro-menuoption>
+      <auro-menuoption value="Grapes" id="option-3">Grapes</auro-menuoption>
+      <auro-menuoption value="Cherries" id="option-4">Cherries</auro-menuoption>
+      <auro-menuoption static nomatch>No matching option</auro-menuoption>
+    </auro-menu>
+  </custom-combobox>
+```
+</auro-accordion>
+<!-- AURO-GENERATED-CONTENT:END -->