@aurodesignsystem-dev/auro-formkit 0.0.0-pr1456.1 → 0.0.0-pr1457.0

package/components/datepicker/README.md

@@ -21,7 +21,7 @@ The following sections are editable by making changes to the following files:
 
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./docs/partials/description.md) -->
 <!-- The below content is automatically added from ./docs/partials/description.md -->
-The `<auro-datepicker>` element allows users to select a date, or a pair of dates identifying a range, either with text input or by making a section in a calendar. The `<auro-datepicker>` element is the combination of [auro-dropdown](http://auro.alaskaair.com/components/auro/dropdown), [auro-input](http://auro.alaskaair.com/components/auro/input), and Auro's extension of [wc-range-datepicker](https://www.npmjs.com/package/wc-range-datepicker).
+The <code>&lt;auro-datepicker&gt;</code> element allows users to select a date, or a pair of dates identifying a range, either with text input or by making a section in a calendar. The <code>&lt;auro-datepicker&gt;</code> element is the combination of <auro-hyperlink href="http://auro.alaskaair.com/components/auro/dropdown">auro-dropdown</auro-hyperlink>, <auro-hyperlink href="http://auro.alaskaair.com/components/auro/input">auro-input</auro-hyperlink>, and Auro's extension of <auro-hyperlink href="https://www.npmjs.com/package/wc-range-datepicker" target="_blank">wc-range-datepicker</auro-hyperlink>.
 <!-- 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 -->
@@ -32,7 +32,7 @@ The `<auro-datepicker>` element allows users to select a date, or a pair of date
 
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./docs/partials/useCases.md) -->
 <!-- The below content is automatically added from ./docs/partials/useCases.md -->
-The `<auro-datepicker>` element should be used in situations where users may:
+The <code>&lt;auro-datepicker&gt;</code> element should be used in situations where users may:
 
 * select a single date
 * select a pair of dates which identify a calendar range
@@ -43,11 +43,7 @@ The `<auro-datepicker>` element should be used in situations where users may:
 <!-- 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
-```
+<pre class="language-shell"><code class="language-shell">$ npm i @aurodesignsystem/</code></pre>
 <!-- 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 -->
@@ -56,13 +52,11 @@ $ npm i @aurodesignsystem/auro-formkit
 
 When using TypeScript set `moduleResolution` to `bundler`, add the following to your `tsconfig.json`:
 
-```json
-{
+<pre class="language-json"><code class="language-json">{
     "compilerOptions": {
         "moduleResolution": "bundler"
     }
-}
-```
+}</code></pre>
 
 This configuration enables proper module resolution for the component's TypeScript files.
 <!-- AURO-GENERATED-CONTENT:END -->
@@ -73,9 +67,7 @@ This configuration enables proper module resolution for the component's TypeScri
 <!-- 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-datepicker/+esm"></script>
-```
+<pre class="language-html"><code class="language-html">&lt;script type="module" src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/@latest/auro-datepicker/+esm"&gt;&lt;/script&gt;</code></pre>
 <!-- AURO-GENERATED-CONTENT:END -->
 
 ## Formkit Development
@@ -89,49 +81,29 @@ Running the `dev` command will open a `localhost` development server for all com
 
 To only develop a single component, use the `--filter` flag:
 
-```shell
-npx turbo dev --filter=@aurodesignsystem/auro-input
-```
+<pre class="language-shell"><code class="language-shell">npx turbo dev --filter=@aurodesignsystem/auro-input</code></pre>
 <!-- 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 -->
+<!-- The below content is automatically added from ./docs/partials/customRegistration.md -->
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../../../docs/partials/customRegistrationDescription.md) -->
+<!-- The below content is automatically added from ./../../../docs/partials/customRegistrationDescription.md -->
+<p>Every Auro component consists of a JavaScript <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes">class</a> and a <a href="https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/define">custom element registration</a>. The class defines the component's behavior, and the registration maps it to an HTML tag name so it can be used in markup.</p>
+<p>The default import (shown above) handles both steps automatically, registering the component under its standard tag name.</p>
+<p>If you need multiple versions of the same component on a single page — for example, when two projects depend on different versions — you can register the class under a custom tag name to avoid conflicts.</p>
+<p>To do this, import the component class directly and call its <code>register(name)</code> method with a unique name:</p>
+<!-- AURO-GENERATED-CONTENT:END -->
 
-## 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
+<pre class="language-js"><code class="language-js">// Import the class only
 import { AuroDatepicker } from '@aurodesignsystem/auro-formkit/auro-datepicker/class';
-
+​
 // Register with a custom name if desired
-AuroDatepicker.register('custom-datepicker');
-```
+AuroDatepicker.register('custom-datepicker');</code></pre>
 
 This will create a new custom element `<custom-datepicker>` that behaves exactly like `<auro-datepicker>`, allowing both to coexist on the same page without interfering with each other.
 
-<div class="exampleWrapper exampleWrapper--flex">
-  <custom-datepicker>
-    <span slot="bib.fullscreen.headline">custom-datepicker Example</span>
-    <span slot="fromLabel">Choose a date</span>
-    <span slot="bib.fullscreen.dateLabel">Choose a date</span>
-  </custom-datepicker>
-</div>
-<auro-accordion alignRight>
-  <span slot="trigger">See code</span>
-
-```html
-  <custom-datepicker>
-    <span slot="bib.fullscreen.headline">custom-datepicker Example</span>
-    <span slot="fromLabel">Choose a date</span>
-    <span slot="bib.fullscreen.dateLabel">Choose a date</span>
-  </custom-datepicker>
-```
-</auro-accordion>
+<pre class="language-html"><code class="language-html">&lt;custom-datepicker&gt;
+  &lt;span slot="bib.fullscreen.headline"&gt;custom-datepicker Example&lt;/span&gt;
+  &lt;span slot="fromLabel"&gt;Choose a date&lt;/span&gt;
+  &lt;span slot="bib.fullscreen.dateLabel"&gt;Choose a date&lt;/span&gt;
+&lt;/custom-datepicker&gt;</code></pre>
 <!-- AURO-GENERATED-CONTENT:END -->

package/components/datepicker/demo/accessibility.html

@@ -0,0 +1,50 @@
+<!--
+  Copyright (c) Alaska Air. All right reserved. Licensed under the Apache-2.0 license
+  See LICENSE in the project root for license information.
+
+  HTML in this document is standardized and NOT to be edited.
+  All demo code should be added/edited in ./demo/accessibility.md
+
+  With the exception of adding custom elements if needed for the demo.
+
+  ----------------------- DO NOT EDIT -----------------------------
+
+-->
+
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Auro Web Component Demo | auro-datepicker | Accessibility</title>
+
+    <!-- highlight.js Stylesheet -->
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.9.0/build/styles/github.min.css"/>
+
+    <!-- Legacy reference is still needed to support auro-datepicker's use of legacy token values at this time -->
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/design-tokens@latest/dist/legacy/auro-classic/CSSCustomProperties.css"/>
+
+    <!-- Design Token Alaska Theme -->
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/design-tokens@latest/dist/themes/alaska/CSSCustomProperties--alaska.min.css"/>
+
+    <!-- Webcore Stylesheet Alaska Theme -->
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/webcorestylesheets@latest/dist/bundled/themes/alaska.global.min.css" />
+
+    <!-- Demo Specific Styles -->
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/webcorestylesheets@latest/dist/demoWrapper.css" />
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/webcorestylesheets@latest/dist/elementDemoStyles.css" />
+    <link rel="stylesheet" type="text/css" href="./styles.css" />
+  </head>
+  <body class="auro-markdown">
+    <main></main>
+
+    <script type="module">
+      import { renderPage } from './demo-support.js';
+      await renderPage('./accessibility.md');
+    </script>
+
+    <!-- If additional elements are needed for the demo, add them here. -->
+    <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-header@latest/+esm" type="module"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-hyperlink@latest/+esm" type="module"></script>
+  </body>
+</html>

package/components/datepicker/demo/accessibility.md

@@ -0,0 +1,64 @@
+<auro-header level="1" id="overview">Datepicker - Accessibility</auro-header>
+<div class="contentWrapper">
+<div class="mainContent">
+<div class="scrollWrapper">
+The `auro-datepicker` component is built on top of `auro-dropdown` and `auro-input`, combining their accessibility features with a calendar interface. This page documents the ARIA semantics, screen reader announcements, and other accessibility behaviors built into the component.
+
+For keyboard interaction details, see the <a href="./keyboard-behavior.html">Keyboard Behavior</a> page.
+
+<auro-header level="2" id="ariaRolesAndAttributes">ARIA Roles and Attributes</auro-header>
+<auro-header level="3" id="trigger">Trigger Input</auro-header>
+The trigger contains one or two `<auro-input>` elements (depending on whether `range` is set). Each input exposes standard ARIA attributes:
+
+| Attribute | Value | Description |
+|---|---|---|
+| `aria-label` | slot text | The input receives its accessible name from the `fromLabel` or `toLabel` slot content. |
+| `aria-invalid` | `true` / `false` | Reflects whether the current value fails validation. |
+
+<auro-header level="3" id="clearButton">Clear Button</auro-header>
+The clear button (shown when the input has a value) exposes:
+
+| Attribute | Value | Description |
+|---|---|---|
+| `aria-label` | slot text or i18n default | Receives its accessible name from the `ariaLabel.input.clear` slot, falling back to a localized default. |
+
+<auro-header level="3" id="helpTextAndErrors">Help Text and Errors</auro-header>
+- Help text is associated with the component so screen readers can announce contextual guidance.
+- When validation fails, the error message is rendered with `role="alert"` and `aria-live="assertive"` to ensure it is announced immediately.
+
+<auro-header level="2" id="focusManagement">Focus Management</auro-header>
+The component uses `delegatesFocus: true` on its shadow root, meaning focus is automatically delegated to the first focusable element inside the component (the date input).
+
+When the calendar bib opens on small viewports as a fullscreen modal dialog, focus is moved to the dialog's close button, giving screen reader users an immediate action to dismiss it.
+
+<auro-header level="2" id="screenReaderAnnouncements">Screen Reader Announcements</auro-header>
+- **Validation errors** — When a validation error occurs, the error message is rendered with `role="alert"` and `aria-live="assertive"`, causing it to be announced immediately without requiring focus.
+- **Help text** — The help text content is associated with the input so that screen readers announce it as part of the element description when focused.
+
+<auro-header level="2" id="accessibleLabels">Accessible Labels</auro-header>
+- The `fromLabel` slot content is used as the accessible name for the first date input.
+- When `range` is set, the `toLabel` slot content provides the accessible name for the second date input.
+- The `label` slot is used as the main label when `layout="snowflake"`.
+- A label is required. Without it, assistive technology users will not have context for what the datepicker controls.
+
+<auro-header level="2" id="fullscreenBehavior">Fullscreen (Modal) Behavior</auro-header>
+On smaller viewports, the calendar bib opens as a fullscreen modal dialog:
+
+- The dialog is opened with `showModal()`, which provides **native focus trapping** — only elements inside the dialog are reachable via Tab.
+- Content outside the dialog is automatically made **inert** by the browser, preventing interaction with the page behind it.
+- A close button inside the dialog is focused when the modal opens, giving screen reader users an immediate action to dismiss it.
+- Touch scrolling on the page behind the dialog is blocked to prevent the background from scrolling into view.
+
+<auro-header level="2" id="reducedMotion">Reduced Motion</auro-header>
+The component respects the `prefers-reduced-motion` media query. When the user has requested reduced motion, scroll animations use instant scrolling instead of smooth scrolling.
+
+<auro-header level="2" id="formParticipation">Form Participation</auro-header>
+The datepicker integrates with HTML forms through its internal `<auro-input>` elements, which render hidden native `<input>` elements with `aria-hidden="true"`. These elements:
+
+- Participate in HTML form submissions, ensuring the selected date value(s) are included in form data.
+- Support the `required` and `disabled` attributes.
+- Are invisible and unreachable by assistive technology — all user interaction goes through the custom component.
+
+</div>
+</div>
+</div>