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

package/components/select/demo/keyboardBehavior.md

@@ -0,0 +1,245 @@
+<auro-header level="1" id="overview">Select - Keyboard Behavior</auro-header>
+<div class="contentWrapper">
+  <div class="mainContent">
+    <div class="scrollWrapper">
+      <auro-header level="2" id="tabBehavior">Tab Behavior</auro-header>
+      <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../../dropdown/docs/partials/tabindex.md) -->
+      <!-- The below content is automatically added from ./../../dropdown/docs/partials/tabindex.md -->
+      <p>The trigger is a focusable element and participates in the standard tab order, responding to <code>Tab</code> and <code>Shift+Tab</code> key events per <auro-hyperlink href="https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex">native browser behavior, i.e., these keys step through the browser tabindex sequence.</auro-hyperlink></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>When the bib is collapsed, the bib content is excluded from the tab sequence. When <strong>expanded</strong>, focusable elements within the bib content are included in the natural tab order. In fullscreen mode, focus is trapped within the bib, and the tab sequence cycles through the bib content focusable elements until the bib is closed or the viewport no longer meets the fullscreen condition and is rendered as a popover.</p>
+      <!-- AURO-GENERATED-CONTENT:END -->
+      <p>There are no focusable elements inside the component's bib content.</p>
+      <div class="note">
+        <p><strong>Note:</strong> The following HTML5 select element 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>
+        <p>This additional <code>multiSelect</code> functionality is not supported at this time.</p>
+        <ul>
+          <li><strong>Extending selection (Shift+Arrow)</strong></li>
+          <li><strong>Select all (Cmd+A):</strong> Select all options</li>
+        </ul>
+      </div>
+      <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 -->
+      <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</td>
+            <td>Trigger element</td>
+            <td>Opens the bib.</td>
+          </tr>
+          <tr>
+            <td>Expanded</td>
+            <td>Trigger element</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</td>
+            <td>Trigger element</td>
+            <td>Opens the bib.</td>
+          </tr>
+          <tr>
+            <td>Expanded</td>
+            <td>Trigger element</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</td>
+            <td>Trigger element</td>
+            <td>Opens the bib.</td>
+          </tr>
+          <tr>
+            <td>Expanded</td>
+            <td>Trigger element</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</td>
+            <td>Trigger element</td>
+            <td>Opens the bib.</td>
+          </tr>
+          <tr>
+            <td>Expanded</td>
+            <td>Trigger element</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</td>
+            <td>Trigger element</td>
+            <td>Opens the bib.</td>
+          </tr>
+          <tr>
+            <td>Expanded</td>
+            <td>Trigger element</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</td>
+            <td>Trigger element</td>
+            <td>Opens the bib.</td>
+          </tr>
+          <tr>
+            <td>Expanded</td>
+            <td>Trigger element</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>Trigger element</td>
+            <td>
+              Advances the <code>focused</code> option to the last enabled option in the list.
+            </td>
+          </tr>
+          <tr>
+            <td rowspan="2">Enter</td>
+            <td rowspan="2">-</td>
+            <td>
+              Expanded, without <code>multiSelect</code>
+            </td>
+            <td>Trigger element</td>
+            <td>
+              The current <code>focused</code> option is selected, closes the bib.
+            </td>
+          </tr>
+          <tr>
+            <td>
+              Expanded, with <code>multiSelect</code>
+            </td>
+            <td>Trigger element</td>
+            <td>
+              The current <code>focused</code> option is toggled, does not close the bib.
+            </td>
+          </tr>
+          <tr>
+            <td>Home</td>
+            <td>-</td>
+            <td>Expanded</td>
+            <td>Trigger element</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>Trigger element</td>
+            <td>
+              The current <code>focused</code> option is selected.
+              <div class="note">
+                <strong>Note:</strong> the page will also navigate to the next focusable element in the tabindex sequence.
+              </div>
+            </td>
+          </tr>
+          <tr>
+            <td>Shift</td>
+            <td>Expanded</td>
+            <td>Trigger element</td>
+            <td>
+              The current <code>focused</code> option is selected.
+              <div class="note">
+                <strong>Note:</strong> the page will also navigate to the previous focusable element in the tabindex sequence.
+              </div>
+            </td>
+          </tr>
+        </tbody>
+      </table>
+      <!-- AURO-GENERATED-CONTENT:END -->
+      <auro-header level="3" id="keyEventsDropdown">Key Events inherited from Auro-Dropdown</auro-header>
+      <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../../dropdown/docs/partials/keyEvents.md) -->
+      <!-- The below content is automatically added from ./../../dropdown/docs/partials/keyEvents.md -->
+      <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="2">Enter</td>
+            <td>-</td>
+            <td>Collapsed</td>
+            <td>
+              Trigger or any <strong>focusable</strong> element within the trigger.
+            </td>
+            <td>Opens the bib.</td>
+          </tr>
+          <tr>
+            <td>-</td>
+            <td>Expanded</td>
+            <td>
+              Trigger or any <strong>focusable</strong> element within the trigger.
+            </td>
+            <td>Closes the bib.</td>
+          </tr>
+          <tr>
+            <td>Escape</td>
+            <td>-</td>
+            <td>Expanded</td>
+            <td>
+              Component <code>:host</code> or any <strong>focusable</strong> element within the component.
+            </td>
+            <td>Closes the bib.</td>
+          </tr>
+          <tr>
+            <td rowspan="2">Space</td>
+            <td>-</td>
+            <td>Collapsed</td>
+            <td>
+              Trigger or any <strong>focusable</strong> element within the trigger.
+            </td>
+            <td>Opens the bib.</td>
+          </tr>
+          <tr>
+            <td>-</td>
+            <td>Expanded</td>
+            <td>
+              Trigger or any <strong>focusable</strong> element within the trigger.
+            </td>
+            <td>Closes the bib.</td>
+          </tr>
+        </tbody>
+      </table>
+      <!-- AURO-GENERATED-CONTENT:END -->
+    </div>
+  </div>
+</div>

package/components/select/demo/readme.md

@@ -0,0 +1,148 @@
+<!--
+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`          |
+-->
+
+# Select
+
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./docs/partials/description.md) -->
+<!-- The below content is automatically added from ./docs/partials/description.md -->
+`<auro-select>` is a combination <auro-hyperlink href="https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements">HTML custom element</auro-hyperlink> that consists of a pre-defined trigger element, `<auro-menu>` for the panel content. The `<auro-select>` element presents a menu of options. The options within the menu are represented by `<auro-menu>` and `<auro-menuoption>` elements. You can pre-select options for the user with the `selected` attribute as part of the `<auro-menuoption>` API.
+<!-- 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 -->
+
+## Select Use Cases
+
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./docs/partials/useCases.md) -->
+<!-- The below content is automatically added from ./docs/partials/useCases.md -->
+See description.
+<!-- 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-select/+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 { AuroSelect } from '@aurodesignsystem/auro-formkit/auro-select/class';
+
+// Register with a custom name if desired
+AuroSelect.register('custom-select');
+```
+
+This will create a new custom element `<custom-select>` that behaves exactly like `<auro-select>`, allowing both to coexist on the same page without interfering with each other.
+
+<div class="exampleWrapper exampleWrapper--flex">
+  <custom-select placeholder="Placeholder Text">
+    <span slot="bib.fullscreen.headline">Bib Headline</span>
+    <span slot="label">Label</span>
+    <auro-menu>
+      <auro-menuoption value="stops">Stops</auro-menuoption>
+      <auro-menuoption value="price">Price</auro-menuoption>
+      <auro-menuoption value="duration">Duration</auro-menuoption>
+      <auro-menuoption value="departure">Departure</auro-menuoption>
+      <auro-menuoption value="arrival">Arrival</auro-menuoption>
+      <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
+    </auro-menu>
+  </custom-select>
+</div>
+<auro-accordion alignRight>
+  <span slot="trigger">See code</span>
+
+```html
+  <custom-select placeholder="Placeholder Text">
+    <span slot="bib.fullscreen.headline">Bib Headline</span>
+    <span slot="label">Label</span>
+    <auro-menu>
+      <auro-menuoption value="stops">Stops</auro-menuoption>
+      <auro-menuoption value="price">Price</auro-menuoption>
+      <auro-menuoption value="duration">Duration</auro-menuoption>
+      <auro-menuoption value="departure">Departure</auro-menuoption>
+      <auro-menuoption value="arrival">Arrival</auro-menuoption>
+      <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
+    </auro-menu>
+  </custom-select>
+```
+</auro-accordion>
+<!-- AURO-GENERATED-CONTENT:END -->