@aurodesignsystem-dev/auro-formkit 0.0.0-pr1492.4 → 0.0.0-pr1493.0

package/components/datepicker/demo/design.md

@@ -35,13 +35,15 @@
 </li>
 </ul>
 <auro-header level="4" id="calendar">Calendar</auro-header>
-<p>The calendar displays one or more months in a grid layout. Users interact with the calendar by clicking on individual date cells. The calendar supports:</p>
+<p>The calendar displays one or more months in a grid layout. Users interact with the calendar by clicking, tapping, or using arrow keys to navigate date cells and Enter/Space to select. The calendar supports:</p>
 <ul>
 <li>Navigating between months using previous/next arrows.</li>
+<li>Arrow-key navigation between date cells with automatic cross-month boundary handling.</li>
 <li>Date range highlighting when <code>range</code> is set.</li>
 <li>Disabled dates outside the <code>minDate</code>/<code>maxDate</code> bounds.</li>
-<li>Custom cell content via the <code>date_MM_DD_YYYY</code> slot.</li>
-<li>Cell popovers via the <code>popover_MM_DD_YYYY</code> slot.</li>
+<li>Blackout dates that are focusable but not selectable.</li>
+<li>Custom cell content via the <code>date_YYYY_MM_DD</code> slot.</li>
+<li>Cell popovers via the <code>popover_YYYY_MM_DD</code> slot.</li>
 </ul>
 <auro-header level="4" id="helpText">Help Text</auro-header>
 <p>Help text is not required. However, consideration should be given to how users will understand the full context of the component instance, particularly users reliant on accessibility tools like screen readers.</p>

package/components/datepicker/demo/getting-started.md

@@ -22,8 +22,8 @@
 <auro-anchorlink fluid href="#slot-bib-fullscreen-headline" class="level2 body-xs">bib.fullscreen.headline</auro-anchorlink>
 <auro-anchorlink fluid href="#slot-bib-fullscreen-fromLabel" class="level2 body-xs">bib.fullscreen.fromLabel</auro-anchorlink>
 <auro-anchorlink fluid href="#slot-bib-fullscreen-toLabel" class="level2 body-xs">bib.fullscreen.toLabel</auro-anchorlink>
-<auro-anchorlink fluid href="#slot-date" class="level2 body-xs">date_MM_DD_YYYY</auro-anchorlink>
-<auro-anchorlink fluid href="#slot-popover" class="level2 body-xs">popover_MM_DD_YYYY</auro-anchorlink>
+<auro-anchorlink fluid href="#slot-date" class="level2 body-xs">date_YYYY_MM_DD</auro-anchorlink>
+<auro-anchorlink fluid href="#slot-popover" class="level2 body-xs">popover_YYYY_MM_DD</auro-anchorlink>
 <auro-anchorlink fluid href="#stateManagement">State Management</auro-anchorlink>
 <auro-anchorlink fluid href="#validity" class="level2 body-xs">Validity</auro-anchorlink>
 <auro-anchorlink fluid href="#value" class="level2 body-xs">Value</auro-anchorlink>
@@ -203,10 +203,10 @@ The `<auro-datepicker>` custom element is compatible with Svelte. See the auro-f
 <p>Defines the content to display above the first date input in the fullscreen (mobile) layout.</p>
 <auro-header level="3" id="slot-bib-fullscreen-toLabel">bib.fullscreen.toLabel</auro-header>
 <p>Defines the content to display above the second date input in the fullscreen (mobile) layout when <code>range</code> is true.</p>
-<auro-header level="3" id="slot-date">date_MM_DD_YYYY</auro-header>
-<p>Defines the content to display in the <code>auro-calendar-cell</code> for the specified date. The date format in the slot name should match <code>MM_DD_YYYY</code> (e.g. <code>slot="date_01_15_2026"</code>). Colored using the success state token when the <code>highlight</code> attribute is applied.</p>
-<auro-header level="3" id="slot-popover">popover_MM_DD_YYYY</auro-header>
-<p>Defines the content to display in the <code>auro-calendar-cell</code> popover for the specified date. The date format in the slot name should match <code>MM_DD_YYYY</code> (e.g. <code>slot="popover_01_15_2026"</code>).</p>
+<auro-header level="3" id="slot-date">date_YYYY_MM_DD</auro-header>
+<p>Defines the content to display in the <code>auro-calendar-cell</code> for the specified date. The date format in the slot name should match <code_YYYY>MM_DD</code> (e.g. <code>slot="date_2026_01_15"</code>). Colored using the success state token when the <code>highlight</code> attribute is applied.</p>
+<auro-header level="3" id="slot-popover">popover_YYYY_MM_DD</auro-header>
+<p>Defines the content to display in the <code>auro-calendar-cell</code> popover for the specified date. The date format in the slot name should match <code>YYYY_MM_DD</code> (e.g. <code>slot="popover_2026_01_15"</code>).</p>
 <!-- AURO-GENERATED-CONTENT:END -->
 </section>
 <section>

package/components/datepicker/demo/index.js

@@ -1,4 +1,5 @@
 import { AuroDatePicker } from '../src/auro-datepicker.js';
+import { blackoutLabelExample } from '../apiExamples/blackout-label.js';
 
 AuroDatePicker.register(); // registering to auro-datepicker
 AuroDatePicker.register('custom-datepicker');
@@ -7,7 +8,10 @@ export function initExamples(initCount) {
   initCount = initCount || 0;
 
   try {
-    // example();
+    // Only run when the demo element exists on the current page
+    if (document.querySelector('#blackoutLabelExample')) {
+      blackoutLabelExample();
+    }
   } catch {
     if (initCount <= 20) {
       // setTimeout handles issue where content is sometimes loaded after the functions get called

package/components/datepicker/demo/index.md

@@ -10,7 +10,9 @@
 <auro-anchorlink fluid href="#selectRange" class="level2 body-xs">Select a Range</auro-anchorlink>
 <auro-anchorlink fluid href="#presetValue" class="level2 body-xs">Preset Value</auro-anchorlink>
 <auro-anchorlink fluid href="#skipSelection" class="level2 body-xs">Skip Selection</auro-anchorlink>
-<auro-anchorlink fluid href="#regionalDateFormat" class="level2 body-xs">Regional Date</auro-anchorlink>
+<auro-anchorlink fluid href="#popoverSlot" class="level2 body-xs">Date Popover</auro-anchorlink>
+<auro-anchorlink fluid href="#blackoutDates" class="level2 body-xs">Blackout Dates</auro-anchorlink>
+<auro-anchorlink fluid href="#referenceDates" class="level2 body-xs">Reference Dates</auro-anchorlink>
 <auro-anchorlink fluid href="#viewportSize" class="level2 body-xs">Viewport Size</auro-anchorlink>
 </auro-nav>
 </nav>
@@ -39,15 +41,21 @@
             Click the input or press <kbd>Enter</kbd> / <kbd>Space</kbd> to open the calendar
 <div class="note">
 <p>
-                The calendar bib opens and displays the current month. Focus moves into the calendar on the current date or, if a <code>calendarFocusDate</code> is set, on that date.
+                The calendar bib opens and displays the current month. The focused cell is determined in the following priority order:
 </p>
+<ol>
+<li>The currently selected date (if one exists and is within the valid min/max range).</li>
+<li>Today's date (if it is enabled — within the min/max range).</li>
+<li>The first future enabled date.</li>
+<li>The first past enabled date.</li>
+</ol>
 </div>
 </li>
 <li>
             Select a date by clicking a calendar cell or by typing a date directly into the input
 <div class="note">
 <p>
-                When a valid date is selected, the <code>value</code> property is updated and the calendar closes (on desktop). If the user types a date, it must match the configured <code>format</code> (default <code>mm/dd/yyyy</code>).
+                When a valid date is selected, the <code>value</code> property is updated. The calendar remains open so additional dates can be reviewed. Close the calendar by pressing Escape or activating the Done button. If the user types a date, it must match the configured <code>format</code> (default <code>mm/dd/yyyy</code>).
 </p>
 </div>
 </li>
@@ -168,25 +176,114 @@
 <auro-header level="3" id="skipSelection">Skip selection</auro-header>
 <p>The datepicker does not force the user to select a date. If no selection is made and the field is not <code>required</code>, the user can move past the datepicker without entering a value.</p>
 <p>If the field is <code>required</code>, moving focus away without selecting a date triggers validation and renders the <code>valueMissing</code> error state.</p>
-<auro-header level="3" id="regionalDateFormat">Regional date format support</auro-header>
-<p>People around the world write dates differently. A traveler in the United States expects to see <strong>12/25/2025</strong>, while someone in Germany expects <strong>25.12.2025</strong>, and someone in Japan expects <strong>2025/12/25</strong>. Showing the wrong format causes confusion and mistakes.</p>
-<p>When the datepicker knows the user's region via the <code>locale</code> attribute, it automatically displays dates in the format that looks natural to them — no extra setup required.</p>
+<auro-header level="3" id="popoverSlot">Popover slot</auro-header>
+<p>Use the <code>popover_YYYY_MM_DD</code> slot to display additional information when the user hovers over a calendar cell. This is useful for showing pricing, availability, or other contextual details for specific dates.</p>
+<div class="exampleWrapper">
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/popover-slot.html) -->
+<!-- The below content is automatically added from ./../apiExamples/popover-slot.html -->
+<auro-datepicker centralDate="2023-12-03" calendarStartDate="2023-12-01" calendarEndDate="2023-12-31" minDate="2023-12-02" maxDate="2023-12-09">
+<span slot="bib.fullscreen.headline">Popover Slot Example</span>
+<span slot="fromLabel">Choose a date</span>
+<span slot="bib.fullscreen.fromLabel">Choose a date</span>
+<span slot="popover_2023_12_03">Tickets for this day are sold out</span>
+<span slot="date_2023_12_03">$560</span>
+<span slot="popover_2023_12_04">34 seats available</span>
+<span slot="date_2023_12_04">$245</span>
+<span slot="popover_2023_12_05">18 seats available</span>
+<span slot="date_2023_12_05">$312</span>
+<span slot="popover_2023_12_06">Tickets for this day are sold out</span>
+<span slot="date_2023_12_06">$489</span>
+<span slot="popover_2023_12_07">52 seats available</span>
+<span slot="date_2023_12_07">$198</span>
+<span slot="popover_2023_12_08">7 seats available</span>
+<span slot="date_2023_12_08">$375</span>
+<span slot="popover_2023_12_09">41 seats available</span>
+<span slot="date_2023_12_09">$220</span>
+</auro-datepicker>
+<!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion alignRight>
+<span slot="trigger">See code</span>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/popover-slot.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/popover-slot.html -->
+<pre class="language-html"><code class="language-html">&lt;auro-datepicker centralDate="2023-12-03" calendarStartDate="2023-12-01" calendarEndDate="2023-12-31" minDate="2023-12-02" maxDate="2023-12-09"&gt;
+  &lt;span slot="bib.fullscreen.headline"&gt;Popover Slot Example&lt;/span&gt;
+  &lt;span slot="fromLabel"&gt;Choose a date&lt;/span&gt;
+  &lt;span slot="bib.fullscreen.fromLabel"&gt;Choose a date&lt;/span&gt;
+  &lt;span slot="popover_2023_12_03"&gt;Tickets for this day are sold out&lt;/span&gt;
+  &lt;span slot="date_2023_12_03"&gt;$560&lt;/span&gt;
+  &lt;span slot="popover_2023_12_04"&gt;34 seats available&lt;/span&gt;
+  &lt;span slot="date_2023_12_04"&gt;$245&lt;/span&gt;
+  &lt;span slot="popover_2023_12_05"&gt;18 seats available&lt;/span&gt;
+  &lt;span slot="date_2023_12_05"&gt;$312&lt;/span&gt;
+  &lt;span slot="popover_2023_12_06"&gt;Tickets for this day are sold out&lt;/span&gt;
+  &lt;span slot="date_2023_12_06"&gt;$489&lt;/span&gt;
+  &lt;span slot="popover_2023_12_07"&gt;52 seats available&lt;/span&gt;
+  &lt;span slot="date_2023_12_07"&gt;$198&lt;/span&gt;
+  &lt;span slot="popover_2023_12_08"&gt;7 seats available&lt;/span&gt;
+  &lt;span slot="date_2023_12_08"&gt;$375&lt;/span&gt;
+  &lt;span slot="popover_2023_12_09"&gt;41 seats available&lt;/span&gt;
+  &lt;span slot="date_2023_12_09"&gt;$220&lt;/span&gt;
+&lt;/auro-datepicker&gt;</code></pre>
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+<auro-header level="3" id="blackoutDates">Blackout dates with custom label</auro-header>
+<p>Use the <code>blackoutLabel</code> attribute to customize the screen reader announcement for blackout (disabled but in-range) dates. The default label is <code>"unavailable"</code>. This is useful when you want to provide more context about why a date cannot be selected, such as <code>"sold out"</code>.</p>
+<p>When a user types a blackout date into the input, the datepicker validates the entry and displays a <code>customError</code> message. The default message is <code>"Selected date is unavailable"</code>. Use the <code>setCustomValidityCustomError</code> attribute to provide a custom error message, for example <code>setCustomValidityCustomError="That date is sold out"</code>.</p>
+<div class="exampleWrapper">
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/blackout-label.html) -->
+<!-- The below content is automatically added from ./../apiExamples/blackout-label.html -->
+<auro-datepicker id="blackoutLabelExample" range blackoutLabel="sold out">
+<span slot="fromLabel">Choose a start date</span>
+<span slot="toLabel">Choose an end date</span>
+<span slot="bib.fullscreen.fromLabel">Choose a date</span>
+<span slot="bib.fullscreen.toLabel">Choose an end date</span>
+</auro-datepicker>
+<!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion alignRight>
+<span slot="trigger">See code</span>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/blackout-label.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/blackout-label.html -->
+<pre class="language-html"><code class="language-html">&lt;auro-datepicker id="blackoutLabelExample" range blackoutLabel="sold out"&gt;
+  &lt;span slot="fromLabel"&gt;Choose a start date&lt;/span&gt;
+  &lt;span slot="toLabel"&gt;Choose an end date&lt;/span&gt;
+  &lt;span slot="bib.fullscreen.fromLabel"&gt;Choose a date&lt;/span&gt;
+  &lt;span slot="bib.fullscreen.toLabel"&gt;Choose an end date&lt;/span&gt;
+&lt;/auro-datepicker&gt;</code></pre>
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+<auro-header level="3" id="referenceDates">Reference dates</auro-header>
+<p>Use the <code>referenceDates</code> attribute to highlight specific dates on the calendar. Reference dates are displayed with a distinct visual treatment to draw attention to dates of interest, such as the cheapest travel dates or dates with special availability.</p>
+<p class="note"><strong>NOTE:</strong> it is recommended to provide popover slot content for reference dates to give context for why the date is marked <code>reference</code>.</p>
 <div class="exampleWrapper">
-<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/locale-single.html) -->
-<!-- The below content is automatically added from ./../apiExamples/locale-single.html -->
-<auro-datepicker locale="zh-CN">
-<span slot="fromLabel">zh-CN Date</span>
-<span slot="helpText">Help Text</span>
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/reference-dates.html) -->
+<!-- The below content is automatically added from ./../apiExamples/reference-dates.html -->
+<auro-datepicker referenceDates='["2025-10-05", "2025-10-15", "2025-10-20", "2025-10-22"]' minDate="2025-10-12" range>
+<span slot="ariaLabel.bib.close">Close Calendar</span>
+<span slot="bib.fullscreen.headline">Datepicker Headline</span>
+<span slot="fromLabel">Choose a date</span>
+<span slot="bib.fullscreen.fromLabel">Choose a date</span>
+<span slot="popover_2025_10_05">Explanation for why this is a reference date.</span>
+<span slot="popover_2025_10_15">Explanation for why this is a reference date.</span>
+<span slot="popover_2025_10_20">Explanation for why this is a reference date.</span>
+<span slot="popover_2025_10_22">Explanation for why this is a reference date.</span>
 </auro-datepicker>
 <!-- AURO-GENERATED-CONTENT:END -->
 </div>
 <auro-accordion alignRight>
 <span slot="trigger">See code</span>
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/locale-single.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/locale-single.html -->
-<pre class="language-html"><code class="language-html">&lt;auro-datepicker locale="zh-CN"&gt;
-  &lt;span slot="fromLabel"&gt;zh-CN Date&lt;/span&gt;
-  &lt;span slot="helpText"&gt;Help Text&lt;/span&gt;
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/reference-dates.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/reference-dates.html -->
+<pre class="language-html"><code class="language-html">&lt;auro-datepicker referenceDates='["2025-10-05", "2025-10-15", "2025-10-20", "2025-10-22"]' minDate="2025-10-12" range&gt;
+  &lt;span slot="ariaLabel.bib.close"&gt;Close Calendar&lt;/span&gt;
+  &lt;span slot="bib.fullscreen.headline"&gt;Datepicker Headline&lt;/span&gt;
+  &lt;span slot="fromLabel"&gt;Choose a date&lt;/span&gt;
+  &lt;span slot="bib.fullscreen.fromLabel"&gt;Choose a date&lt;/span&gt;
+  &lt;span slot="popover_2025_10_05"&gt;Explanation for why this is a reference date.&lt;/span&gt;
+  &lt;span slot="popover_2025_10_15"&gt;Explanation for why this is a reference date.&lt;/span&gt;
+  &lt;span slot="popover_2025_10_20"&gt;Explanation for why this is a reference date.&lt;/span&gt;
+  &lt;span slot="popover_2025_10_22"&gt;Explanation for why this is a reference date.&lt;/span&gt;
 &lt;/auro-datepicker&gt;</code></pre>
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>