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

package/components/datepicker/demo/design.md

@@ -35,11 +35,13 @@
 </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>Blackout dates that are focusable but not selectable.</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>
 </ul>

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,6 +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="#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="#regionalDateFormat" class="level2 body-xs">Regional Date</auro-anchorlink>
 <auro-anchorlink fluid href="#viewportSize" class="level2 body-xs">Viewport Size</auro-anchorlink>
 </auro-nav>
@@ -39,15 +42,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 +177,105 @@
 <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_MM_DD_YYYY</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_12_03_2023">Tickets for this day are sold out</span>
+<span slot="date_12_03_2023">$560</span>
+<span slot="popover_12_04_2023">34 seats available</span>
+<span slot="date_12_04_2023">$245</span>
+<span slot="popover_12_05_2023">18 seats available</span>
+<span slot="date_12_05_2023">$312</span>
+<span slot="popover_12_06_2023">Tickets for this day are sold out</span>
+<span slot="date_12_06_2023">$489</span>
+<span slot="popover_12_07_2023">52 seats available</span>
+<span slot="date_12_07_2023">$198</span>
+<span slot="popover_12_08_2023">7 seats available</span>
+<span slot="date_12_08_2023">$375</span>
+<span slot="popover_12_09_2023">41 seats available</span>
+<span slot="date_12_09_2023">$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_12_03_2023"&gt;Tickets for this day are sold out&lt;/span&gt;
+  &lt;span slot="date_12_03_2023"&gt;$560&lt;/span&gt;
+  &lt;span slot="popover_12_04_2023"&gt;34 seats available&lt;/span&gt;
+  &lt;span slot="date_12_04_2023"&gt;$245&lt;/span&gt;
+  &lt;span slot="popover_12_05_2023"&gt;18 seats available&lt;/span&gt;
+  &lt;span slot="date_12_05_2023"&gt;$312&lt;/span&gt;
+  &lt;span slot="popover_12_06_2023"&gt;Tickets for this day are sold out&lt;/span&gt;
+  &lt;span slot="date_12_06_2023"&gt;$489&lt;/span&gt;
+  &lt;span slot="popover_12_07_2023"&gt;52 seats available&lt;/span&gt;
+  &lt;span slot="date_12_07_2023"&gt;$198&lt;/span&gt;
+  &lt;span slot="popover_12_08_2023"&gt;7 seats available&lt;/span&gt;
+  &lt;span slot="date_12_08_2023"&gt;$375&lt;/span&gt;
+  &lt;span slot="popover_12_09_2023"&gt;41 seats available&lt;/span&gt;
+  &lt;span slot="date_12_09_2023"&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>
 <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>
 </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;/auro-datepicker&gt;</code></pre>
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>