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

package/components/dropdown/demo/keyboardBehavior.md

@@ -0,0 +1,77 @@
+## Dropdown Keyboard Behavior
+
+### Tab Behavior
+
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/tabindex.md) -->
+<!-- The below content is automatically added from ./../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 -->
+
+### Key Events
+
+<!-- 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="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 -->
+
+## DEVELOPER NOTES / CODE ACTION ITEMS / TODO ITEMS
+1. Remove the bridge for keyboard event bubbling out of the bib
+1. Strip out event listeners not listed in this document (e.g. arrow keys)
+1. do not prevent any event bubbling beyond the focus trap of a fullscreen bib

package/components/dropdown/demo/readme.md

@@ -0,0 +1,160 @@
+<!--
+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`          |
+-->
+
+# Dropdown
+
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./docs/partials/description.md) -->
+<!-- The below content is automatically added from ./docs/partials/description.md -->
+The `auro-dropdown` component is a trigger and dropdown element combination intended to be used with dropdown content that is interactive. `auro-dropdown` is content agnostic and any valid HTML can be placed in either the trigger or the dropdown.
+
+_Note: if the dropdown content in your implementation is not interactive (e.g. a tooltip) [auro-popover](http://auro.alaskaair.com/components/auro/popover) may better serve your needs._
+<!-- 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 -->
+
+## Dropdown 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-dropdown` element should be used in situations where users may:
+
+* interact with an element to get clarification on content offering
+* provide definition to iconic imagery
+* when interactive help is required
+<!-- 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-dropdown/+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 { AuroDropdown } from '@aurodesignsystem/auro-formkit/auro-dropdown/class';
+
+// Register with a custom name if desired
+AuroDropdown.register('custom-dropdown');
+```
+
+This will create a new custom element `<custom-dropdown>` that behaves exactly like `<auro-dropdown>`, allowing both to coexist on the same page without interfering with each other.
+
+<div class="exampleWrapper exampleWrapper--flex">
+  <custom-dropdown id="customCommon" layout="classic" shape="classic" size="lg" aria-label="Label content for screen reader">
+    <div style="padding: var(--ds-size-150);">
+      Lorem ipsum solar
+      <br />
+      <auro-button id="customCommonButton">
+        Dismiss Dropdown
+      </auro-button>
+    </div>
+    <span slot="helpText">
+      Help text
+    </span>
+    <div slot="trigger">
+      Trigger
+    </div>
+  </custom-dropdown>
+</div>
+<auro-accordion alignRight>
+  <span slot="trigger">See code</span>
+
+```html
+  <custom-dropdown id="customCommon" layout="classic" shape="classic" size="lg" aria-label="Label content for screen reader">
+    <div style="padding: var(--ds-size-150);">
+      Lorem ipsum solar
+      <br />
+      <auro-button id="customCommonButton">
+        Dismiss Dropdown
+      </auro-button>
+    </div>
+    <span slot="helpText">
+      Help text
+    </span>
+    <div slot="trigger">
+      Trigger
+    </div>
+  </custom-dropdown>
+```
+</auro-accordion>
+<!-- AURO-GENERATED-CONTENT:END -->