@watermarkinsights/ripple 5.30.0 → 5.31.0-alpha.1

package/dist/collection/components/datepickers/wm-datepicker.js

@@ -1,5 +1,116 @@
 import { h, Host } from "@stencil/core";
 import { intl, toBool, handleDisabledAttribute, dateToISO, showTooltip, hideTooltip, debounce, findAllScrollableParents, findPositioningBoundary, } from "../../global/functions";
+/**
+ * Date input that lets users type a date or pick one from a calendar popup. Supports
+ * configurable date formats, pre-selection, validation, and full keyboard navigation of the calendar.
+ * Use instead of native `<input type="date">`.
+ *
+ * @keyboardInteraction
+ * - **Input field**: Tab moves focus to the calendar toggle button.
+ * - **Calendar toggle**: Space / Enter / Down Arrow opens the calendar; Shift+Tab returns to the input.
+ * - **Day grid**: Arrow keys navigate dates; Enter selects; Escape closes and returns focus to the toggle;
+ *   Home/End jump to the first/last day of the month; Tab cycles through calendar controls.
+ * - **Month/year selectors**: Arrow keys cycle values; Tab/Shift+Tab move focus clockwise/counter-clockwise.
+ *
+ * @accessibility
+ * - `label` is required even when `label-position` is `"none"` — it becomes the input's `aria-label`.
+ * - The calendar toggle button announces "Select date" to screen readers and reflects `aria-expanded`.
+ * - Validation errors are announced via an `aria-live` region when `error-message` changes.
+ * - When the input value cannot be parsed as a valid date, the calendar opens to the current date.
+ *
+ * @usageNotes
+ * - Set `value` in the same format as `date-format` (default `mm/dd/yyyy`). For programmatic date
+ *   setting, prefer ISO format via `preselected` and convert with the `reformatDate` method.
+ * - The calendar popup hides its toggle automatically when there is no room to display it; always
+ *   allow users to type a date directly in the input as a fallback.
+ *
+ * @example {html} Basic datepicker
+ * <wm-datepicker label="Start date"></wm-datepicker>
+ *
+ * @example {react} Basic datepicker
+ * // The component does not update its own value after a calendar selection --
+ * // the app must call reformatDate and set value/errorMessage imperatively via a ref.
+ * const ref = useRef(null);
+ *
+ * function getFormatName(format) {
+ *   const map = { 'mm/dd/yyyy': 'US', 'dd/mm/yyyy': 'INT', 'yyyy/mm/dd': 'ISO' };
+ *   return format ? map[format] : 'US';
+ * }
+ *
+ * // event.detail is { date: string } -- ISO 8601 (YYYY-MM-DD)
+ * const handleDateSelected = async (event) => {
+ *   const dp = ref.current;
+ *   const fmt = getFormatName(dp.getAttribute('date-format'));
+ *   dp.value = await dp.reformatDate('ISO', fmt, event.detail.date);
+ *   dp.errorMessage = '';
+ * };
+ *
+ * const handleInputBlurred = async () => {
+ *   const dp = ref.current;
+ *   const fmt = getFormatName(dp.getAttribute('date-format'));
+ *   if (dp.value) {
+ *     const iso = await dp.reformatDate(fmt, 'ISO', dp.value);
+ *     if (await dp.isValidIso(iso)) {
+ *       dp.value = await dp.reformatDate('ISO', fmt, iso);
+ *       dp.errorMessage = '';
+ *     } else {
+ *       dp.errorMessage = `Please enter a valid date in the format ${dp.getAttribute('date-format') ?? 'mm/dd/yyyy'}`;
+ *     }
+ *   }
+ * };
+ *
+ * const handleBlur = () => {
+ *   const dp = ref.current;
+ *   if (dp.requiredField && dp.value === '') dp.errorMessage = 'A date is required';
+ * };
+ *
+ * <WmDatepicker
+ *   ref={ref}
+ *   label="Start date"
+ *   onWmDatepickerDateSelected={handleDateSelected}
+ *   onWmDatepickerInputBlurred={handleInputBlurred}
+ *   onBlur={handleBlur}
+ * />
+ *
+ * @example {html} Required field with validation
+ * <wm-datepicker label="Date of birth" required-field></wm-datepicker>
+ *
+ * @example {react} Required field with validation
+ * <WmDatepicker
+ *   ref={ref}
+ *   label="Date of birth"
+ *   requiredField={true}
+ *   onWmDatepickerDateSelected={handleDateSelected}
+ *   onWmDatepickerInputBlurred={handleInputBlurred}
+ *   onBlur={handleBlur}
+ * />
+ *
+ * @example {html} With validation error
+ * <wm-datepicker label="Start date" required-field error-message="Please enter a valid start date"></wm-datepicker>
+ *
+ * @example {react} With validation error
+ * <WmDatepicker label="Start date" requiredField={true} errorMessage="Please enter a valid start date" />
+ *
+ * @example {html} Pre-opened to a specific date
+ * <wm-datepicker label="Enrollment date" preselected="2025-09-01"></wm-datepicker>
+ *
+ * @example {react} Pre-opened to a specific date
+ * <WmDatepicker label="Enrollment date" preselected="2025-09-01" />
+ *
+ * @example {html} International date format
+ * <wm-datepicker label="Graduation date" date-format="dd/mm/yyyy"></wm-datepicker>
+ *
+ * @example {react} International date format
+ * <WmDatepicker label="Graduation date" dateFormat="dd/mm/yyyy" />
+ *
+ * @example {html} Disabled
+ * <wm-datepicker label="Locked date" value="05/15/2024" disabled></wm-datepicker>
+ *
+ * @example {react} Disabled
+ * <WmDatepicker label="Locked date" value="05/15/2024" disabled={true} />
+ *
+ * @category Form Inputs
+ */
 export class DatePicker {
     constructor() {
         this.calWidth = 336;
@@ -99,12 +210,17 @@ export class DatePicker {
     }
     get calendarDate() {
         let calendarDate = dateToISO(new Date());
-        const dateFormatUnits = { "mm/dd/yyyy": "US", "dd/mm/yyyy": "INT", "yyyy/mm/dd": "ISO" };
+        const dateFormatUnits = {
+            "mm/dd/yyyy": "US",
+            "dd/mm/yyyy": "INT",
+            "yyyy/mm/dd": "ISO",
+        };
+        const inputFormat = dateFormatUnits[this.dateFormat];
         if (this.value &&
-            dateFormatUnits[this.dateFormat] &&
-            this.isValidIsoInternal(this.reformatDateInternal(dateFormatUnits[this.dateFormat], "ISO", this.value))) {
+            inputFormat &&
+            this.isValidIsoInternal(this.reformatDateInternal(inputFormat, "ISO", this.value))) {
             // if component has value, and value can be parsed to valid ISO
-            calendarDate = this.reformatDateInternal(dateFormatUnits[this.dateFormat], "ISO", this.value);
+            calendarDate = this.reformatDateInternal(inputFormat, "ISO", this.value);
         }
         else if (this.preselected) {
             calendarDate = this.preselected;
@@ -191,7 +307,7 @@ export class DatePicker {
             }
             this.fit = null;
             this.isExpanded = false;
-            this.calEl.view = "day";
+            this.calEl.view = "month";
         }
     }
     closePopup(returnFocus = false) {
@@ -245,6 +361,18 @@ export class DatePicker {
         this.el.dispatchEvent(changeEvent);
         this.closePopup(true);
     }
+    /**
+     * @description Converts a date string between the supported format tokens: `"US"` (mm/dd/yyyy),
+     * `"INT"` (dd/mm/yyyy), and `"ISO"` (YYYY-MM-DD). Direct US ↔ INT conversion is not supported —
+     * route through ISO as an intermediate step.
+     * @param inputFormat - Format of the input date string.
+     * @param outputFormat - Desired output format.
+     * @param date - The date string to reformat.
+     * @returns The reformatted date string, an empty string if `date` is omitted or falsy, or the
+     * original string unchanged if it cannot be parsed.
+     * @example reformatDate("US", "ISO", "06/20/1969") // → "1969-06-20"
+     * @example reformatDate("ISO", "US", "1969-06-20") // → "06/20/1969"
+     */
     async reformatDate(inputFormat, outputFormat, date) {
         return this.reformatDateInternal(inputFormat, outputFormat, date);
     }
@@ -280,6 +408,15 @@ export class DatePicker {
             }
         }
     }
+    /**
+     * @description Validates whether a string is a well-formed, calendar-correct ISO date
+     * (YYYY-MM-DD). Accounts for invalid day-of-month values and leap years.
+     * @param input - The string to validate.
+     * @returns `true` if the string is a valid ISO date, `false` otherwise.
+     * @example isValidIso("1969-06-20") // → true
+     * @example isValidIso("1969-06-33") // → false (day 33 does not exist)
+     * @example isValidIso("2023-02-29") // → false (2023 is not a leap year)
+     */
     async isValidIso(input) {
         return this.isValidIsoInternal(input);
     }
@@ -329,25 +466,25 @@ export class DatePicker {
     }
     render() {
         var _a, _b, _c, _d;
-        return (h(Host, { key: '1ae084fab8bf53b87d769a314f7e6173492d35bc', "aria-busy": "false", class: `${this.errorMessage ? "invalid" : ""}` }, h("div", { key: 'ff4180135e424dfdf985819781117277925cfd4e', ref: (d) => (this.dpWrapperEl = d), class: `wrapper label-${this.labelPosition} ${this.errorMessage ? "invalid" : ""}` }, h("div", { key: '62df8d9f5634d50508a7a0f47d3d9d6f3d0ad16f', class: "label-wrapper" }, this.labelPosition !== "none" && (h("label", { key: '3430b1340a0ba7355d4dc22a5bd02a800ffafa5f', id: "datepickerLabel", htmlFor: "date-input", class: "label", onMouseEnter: (ev) => this.handleLabelMouseEnter(ev), onMouseLeave: () => hideTooltip() }, this.label)), this.labelPosition !== "none" && this.requiredField && (h("div", { key: '625126eee314eb1ac24f82e2a7bc0e48abe8ad5d', "aria-hidden": "true", class: "required" }, "*"))), h("div", { key: '39a8bc38fa6aad0a5cafd5fb3af8880229918384' }, h("div", { key: '861923fb1569879e5d8a2f593c6023f295d57e5e', class: "single-wrapper input", ref: (el) => (this.anchorEl = el) }, h("input", { key: 'aa8bf537a6c1e1d50157107a0392b90e984e6ca6', disabled: this.isDisabled, type: "text", id: "single-date-input", class: "date-input", name: "date", placeholder: this.dateFormat, value: this.value, onFocus: () => this.handleInputFocus(), onInput: (ev) => this.handleInput(ev), onBlur: () => this.handleInputBlur(), onChange: () => this.handleInputChange(), ref: (input) => (this.inputEl = input), "aria-describedby": "date-format-hint error", "aria-label": this.label, "aria-required": this.requiredField ? "true" : null }), h("div", { key: '7c26eb7e1a11ea1ee314ccbe9e1855f5cdd3b5ec', class: "container", id: "wm-container" }, this.canOpen && (h("button", { key: '734718b3ee64ab44fcf44f0ff34f2985f57ccf66', disabled: this.disabled, "aria-label": intl.formatMessage({
+        return (h(Host, { key: 'ec737a3904688317e61939e4ed997c0e4d6fa49d', "aria-busy": "false", class: `${this.errorMessage ? "invalid" : ""}` }, h("div", { key: 'ba2baa4d174b1fdb229169cd80ee8f60c308254e', ref: (d) => (this.dpWrapperEl = d), class: `wrapper label-${this.labelPosition} ${this.errorMessage ? "invalid" : ""}` }, h("div", { key: '4e196f3d7e9dc1ebc0fdd8d63cd4f9bb2888c3ed', class: "label-wrapper" }, this.labelPosition !== "none" && (h("label", { key: 'ad751fc53a81f7ea7edc88ded9a632cab9fabac1', id: "datepickerLabel", htmlFor: "date-input", class: "label", onMouseEnter: (ev) => this.handleLabelMouseEnter(ev), onMouseLeave: () => hideTooltip() }, this.label)), this.labelPosition !== "none" && this.requiredField && (h("div", { key: '4226a64b138aa35272fffce46265f82503afc25d', "aria-hidden": "true", class: "required" }, "*"))), h("div", { key: '175045b72db00588c9b8031cfbf22a2f77759e77' }, h("div", { key: '126b7c096ec657766deedb6bab0107f067c8cdd9', class: "single-wrapper input", ref: (el) => (this.anchorEl = el) }, h("input", { key: '36560f575003ffc14e2e363c24e682f8e5805f41', disabled: this.isDisabled, type: "text", id: "single-date-input", class: "date-input", name: "date", placeholder: this.dateFormat, value: this.value, onFocus: () => this.handleInputFocus(), onInput: (ev) => this.handleInput(ev), onBlur: () => this.handleInputBlur(), onChange: () => this.handleInputChange(), ref: (input) => (this.inputEl = input), "aria-describedby": "date-format-hint error", "aria-label": this.label, "aria-required": this.requiredField ? "true" : null }), h("div", { key: '097142daa1f08d9a135d2ed25c1161434448e3d7', class: "container", id: "wm-container" }, this.canOpen && (h("button", { key: 'ad64f7af5d81e3035b791808e9c9c35a537a86a9', disabled: this.disabled, "aria-label": intl.formatMessage({
                 id: "date.selectDate",
                 defaultMessage: "Select date",
                 description: "Button text for screen readers.",
-            }), "aria-describedby": "single-date-input", ref: (el) => (this.toggleEl = el), "aria-expanded": `${this.isExpanded}`, class: "toggle", id: "toggle", popoverTarget: "popup-wrapper", popoverTargetAction: "toggle" }, h("span", { key: 'eea61f1c8f02f89cca36f8d51f1028f1bb1f5801', class: "svg-icon svg-date" }), h("span", { key: '7910f167d9343f53b8d1df37845179d3580483f1', class: "calendar", title: intl.formatMessage({
+            }), "aria-describedby": "single-date-input", ref: (el) => (this.toggleEl = el), "aria-expanded": `${this.isExpanded}`, class: "toggle", id: "toggle", popoverTarget: "popup-wrapper", popoverTargetAction: "toggle" }, h("span", { key: 'f4860dc16c96322e45dd6f425c1b132bec93edd8', class: "svg-icon svg-date" }), h("span", { key: 'b771ffa73b5995cfb5a5a2d15902e8e57a1e9ad6', class: "calendar", title: intl.formatMessage({
                 id: "date.calendarView",
                 defaultMessage: "Calendar View",
                 description: "Calendar button",
-            }) }))), h("div", { key: '9c82f780494e23aefa7e188e060c8243ef9d6e01', class: `popup-wrapper ${this.calEl && this.calEl.view}-view ${this.isExpanded ? "is-open" : ""} ${!this.hasAnchor && !this.isExpanded ? "hidden" : ""} ${(_b = (_a = this.fit) === null || _a === void 0 ? void 0 : _a.vertical) !== null && _b !== void 0 ? _b : ""} ${(_d = (_c = this.fit) === null || _c === void 0 ? void 0 : _c.horizontal) !== null && _d !== void 0 ? _d : ""}`, id: "popup-wrapper", ref: (el) => (this.popupEl = el), popover: "auto",
+            }) }))), h("div", { key: '27823fcfcb377eea7adf0f725031b67407b8886c', class: `popup-wrapper ${this.calEl && this.calEl.view}-view ${this.isExpanded ? "is-open" : ""} ${!this.hasAnchor && !this.isExpanded ? "hidden" : ""} ${(_b = (_a = this.fit) === null || _a === void 0 ? void 0 : _a.vertical) !== null && _b !== void 0 ? _b : ""} ${(_d = (_c = this.fit) === null || _c === void 0 ? void 0 : _c.horizontal) !== null && _d !== void 0 ? _d : ""}`, id: "popup-wrapper", ref: (el) => (this.popupEl = el), popover: "auto",
             // @ts-ignore -- onToggle is a valid ToggleEvent listener for popover elements
-            onToggle: (ev) => this.handleToggle(ev) }, h("div", { key: 'dbdff9693acf1c80fc815d9ad734b009120d634e', tabIndex: 0, onFocus: () => this.calEl.focusLastFocusable() }), h("priv-calendar", { key: '6db36aebafb43d5a9fef8a108921b0a7baa5ae6b', ref: (el) => (this.calEl = el), startDate: this.calendarDate, focusDate: this.calendarDate, class: "inside" }), h("div", { key: '8b373c91819aedd18bd23086d286ba8409daa932', tabIndex: 0, onFocus: () => this.calEl.focusFirstFocusable() })), h("div", { key: 'f77269cd2e7bce953622c574e9541eded807f708', id: "live-region", "aria-live": "polite", "aria-relevant": "text", class: "sr-only" }), h("div", { key: '0d5de891b42a3d0b4ac38efa02eb6323719d86a3', id: "month-title", class: "sr-only" }, intl.formatMessage({
+            onToggle: (ev) => this.handleToggle(ev) }, h("div", { key: '42fb801ee8861ee9d69fd634b01961ca1e751d3b', tabIndex: 0, onFocus: () => this.calEl.focusLastFocusable() }), h("priv-calendar", { key: 'f6d60feb67ceb253069e3d81f1bc348a58a7c9e0', ref: (el) => (this.calEl = el), startDate: this.calendarDate, focusDate: this.calendarDate, class: "inside" }), h("div", { key: 'a8931fe7482dc487dc19cefd0eac43a6bcb5d2d4', tabIndex: 0, onFocus: () => this.calEl.focusFirstFocusable() })), h("div", { key: '7f934d9c1260c7660f9dd819c5a8c235c703e6cd', id: "live-region", "aria-live": "polite", "aria-relevant": "text", class: "sr-only" }), h("div", { key: '0db580e9920000ee2438d0a1a3d55c670dca029f', id: "month-title", class: "sr-only" }, intl.formatMessage({
             id: "date.selectMonth",
             defaultMessage: "Activate to select a month.",
             description: "Calendar button",
-        })), h("div", { key: '8044eaab6e1ed7b14164ecbab8adccd9cf10a8e1', id: "year-title", class: "sr-only" }, intl.formatMessage({
+        })), h("div", { key: 'aedeb3b51f4d5178022beb80feb69350019a94e6', id: "year-title", class: "sr-only" }, intl.formatMessage({
             id: "date.selectYear",
             defaultMessage: "Activate to select a year.",
             description: "Calendar button",
-        })))), h("div", { key: '84e8a07316eb505d1efb41426681c1c50fc57d84', id: "error", class: "error" }, this.errorMessage), h("span", { key: 'eaadadc2b5f4d7665573feff2cce7509e306b07d', id: "date-format-hint", class: "sr-only" }, this.dateFormat), h("div", { key: 'dd22ed0f5451379701210d29c460d832c388ac0d', ref: (el) => (this.liveRegionEl = el), class: "sr-only", "aria-live": "polite", "aria-atomic": "true" })))));
+        })))), h("div", { key: 'd9b334efcd6a1a8732996af354ebb3732984a9da', id: "error", class: "error" }, this.errorMessage), h("span", { key: 'ef309d1f21a4e414bb6230bb29a6e2477faf092b', id: "date-format-hint", class: "sr-only" }, this.dateFormat), h("div", { key: 'f5487f9e59eb400483ef96362a549dc52e512404', ref: (el) => (this.liveRegionEl = el), class: "sr-only", "aria-live": "polite", "aria-atomic": "true" })))));
     }
     static get is() { return "wm-datepicker"; }
     static get encapsulation() { return "shadow"; }
@@ -375,7 +512,10 @@ export class DatePicker {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "The date displayed in the input field, in the format specified by `date-format`. Updated as the user types. Can also be set programmatically by the application."
+                        }],
                     "text": ""
                 },
                 "attribute": "value",
@@ -393,7 +533,13 @@ export class DatePicker {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Disables the datepicker, preventing all interaction."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
                     "text": ""
                 },
                 "attribute": "disabled",
@@ -411,7 +557,13 @@ export class DatePicker {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "The expected date format. Shown in the input placeholder and announced to screen reader users."
+                        }, {
+                            "name": "default",
+                            "text": "\"mm/dd/yyyy\""
+                        }],
                     "text": ""
                 },
                 "attribute": "date-format",
@@ -429,7 +581,10 @@ export class DatePicker {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Puts the component in an error state and displays this message below the input."
+                        }],
                     "text": ""
                 },
                 "attribute": "error-message",
@@ -446,7 +601,13 @@ export class DatePicker {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Position of the label relative to the input. `'none'` hides the label visually but keeps it accessible via `aria-label`."
+                        }, {
+                            "name": "default",
+                            "text": "\"top\""
+                        }],
                     "text": ""
                 },
                 "attribute": "label-position",
@@ -464,7 +625,13 @@ export class DatePicker {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Visible label for the input. Required even when `label-position` is `'none'` \u2014 used as the ARIA accessible name."
+                        }, {
+                            "name": "required",
+                            "text": undefined
+                        }],
                     "text": ""
                 },
                 "attribute": "label",
@@ -482,7 +649,13 @@ export class DatePicker {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Displays a required-field asterisk (*) next to the label."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
                     "text": ""
                 },
                 "attribute": "required-field",
@@ -500,7 +673,10 @@ export class DatePicker {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "The date the calendar popup focuses when first opened, in ISO format (YYYY-MM-DD). Falls back to the parsed `value`, then the current date if neither can be parsed."
+                        }],
                     "text": ""
                 },
                 "attribute": "preselected",
@@ -522,7 +698,13 @@ export class DatePicker {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires when the user selects a date from the calendar popup."
+                        }, {
+                            "name": "eventDetails",
+                            "text": "{{ date: string }} date \u2014 the selected date in ISO format (YYYY-MM-DD)."
+                        }],
                     "text": ""
                 },
                 "complexType": {
@@ -537,7 +719,10 @@ export class DatePicker {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires when the text input loses focus."
+                        }],
                     "text": ""
                 },
                 "complexType": {
@@ -551,19 +736,19 @@ export class DatePicker {
         return {
             "reformatDate": {
                 "complexType": {
-                    "signature": "(inputFormat: string, outputFormat: string, date?: string) => Promise<string>",
+                    "signature": "(inputFormat: \"US\" | \"INT\" | \"ISO\", outputFormat: \"US\" | \"INT\" | \"ISO\", date?: string) => Promise<string>",
                     "parameters": [{
                             "name": "inputFormat",
-                            "type": "string",
-                            "docs": ""
+                            "type": "\"US\" | \"INT\" | \"ISO\"",
+                            "docs": "- Format of the input date string."
                         }, {
                             "name": "outputFormat",
-                            "type": "string",
-                            "docs": ""
+                            "type": "\"US\" | \"INT\" | \"ISO\"",
+                            "docs": "- Desired output format."
                         }, {
                             "name": "date",
                             "type": "string | undefined",
-                            "docs": ""
+                            "docs": "- The date string to reformat."
                         }],
                     "references": {
                         "Promise": {
@@ -575,7 +760,28 @@ export class DatePicker {
                 },
                 "docs": {
                     "text": "",
-                    "tags": []
+                    "tags": [{
+                            "name": "description",
+                            "text": "Converts a date string between the supported format tokens: `\"US\"` (mm/dd/yyyy),\n`\"INT\"` (dd/mm/yyyy), and `\"ISO\"` (YYYY-MM-DD). Direct US \u2194 INT conversion is not supported \u2014\nroute through ISO as an intermediate step."
+                        }, {
+                            "name": "param",
+                            "text": "inputFormat - Format of the input date string."
+                        }, {
+                            "name": "param",
+                            "text": "outputFormat - Desired output format."
+                        }, {
+                            "name": "param",
+                            "text": "date - The date string to reformat."
+                        }, {
+                            "name": "returns",
+                            "text": "The reformatted date string, an empty string if `date` is omitted or falsy, or the\noriginal string unchanged if it cannot be parsed."
+                        }, {
+                            "name": "example",
+                            "text": "reformatDate(\"US\", \"ISO\", \"06/20/1969\") // \u2192 \"1969-06-20\""
+                        }, {
+                            "name": "example",
+                            "text": "reformatDate(\"ISO\", \"US\", \"1969-06-20\") // \u2192 \"06/20/1969\""
+                        }]
                 }
             },
             "isValidIso": {
@@ -584,7 +790,7 @@ export class DatePicker {
                     "parameters": [{
                             "name": "input",
                             "type": "string | undefined",
-                            "docs": ""
+                            "docs": "- The string to validate."
                         }],
                     "references": {
                         "Promise": {
@@ -596,7 +802,25 @@ export class DatePicker {
                 },
                 "docs": {
                     "text": "",
-                    "tags": []
+                    "tags": [{
+                            "name": "description",
+                            "text": "Validates whether a string is a well-formed, calendar-correct ISO date\n(YYYY-MM-DD). Accounts for invalid day-of-month values and leap years."
+                        }, {
+                            "name": "param",
+                            "text": "input - The string to validate."
+                        }, {
+                            "name": "returns",
+                            "text": "`true` if the string is a valid ISO date, `false` otherwise."
+                        }, {
+                            "name": "example",
+                            "text": "isValidIso(\"1969-06-20\") // \u2192 true"
+                        }, {
+                            "name": "example",
+                            "text": "isValidIso(\"1969-06-33\") // \u2192 false (day 33 does not exist)"
+                        }, {
+                            "name": "example",
+                            "text": "isValidIso(\"2023-02-29\") // \u2192 false (2023 is not a leap year)"
+                        }]
                 }
             }
         };

package/dist/collection/components/selects/priv-option-list/priv-option-list.js

@@ -1,6 +1,12 @@
 import { h, forceUpdate } from "@stencil/core";
 import { debounce, isElOrChild } from "../../../global/functions";
 import { selectMessages } from "../../../global/intl";
+/**
+ * @internal
+ * @description Internal listbox, search field, and Select All button used by wm-select,
+ * wm-nested-select, and wm-optgroup. Manages keyboard navigation, option filtering, and
+ * clone options for multiselect. Not for direct application use.
+ */
 export class PrivOptionList {
     constructor() {
         this.searchIndex = 0;
@@ -367,7 +373,7 @@ export class PrivOptionList {
         return (h("div", { class: "non-options-wrapper" }, this.isInNestedSelect && this.renderReturnBtn(), this.search && this.renderSearchField(), this.visibleSelectAllButton && this.renderSelectAllButton()));
     }
     render() {
-        return (h("div", { key: 'd1dc259bbc48591f82a0e44017349513b7e22f60', class: "list-wrapper" }, (this.isInNestedSelect || this.search || this.visibleSelectAllButton) && this.renderNonOptions(), h("div", { key: '5ef4cd1533f03e47175ed6112996ba73a138aacd', id: "list", class: "options-wrapper", tabindex: -1, role: "listbox", "aria-multiselectable": this.multiple ? "true" : null, "aria-label": this.optgroupLabel, ref: (el) => (this.listboxEl = el), style: { "--max-height": this.effectiveMaxHeight } }, this.searchTerm && this.filteredOptions.length === 0 && this.renderSearchFailedMessage(), this.multiple && this.renderCloneOptions(), h("slot", { key: '53014694e7dc51fbfc4fe6da9abbf0749764b4a1' })), h("div", { key: 'f3e1bb6596bd0e656eb045c5a62dad39ee266985', id: "optionlist-announcement", "aria-live": "polite", "aria-atomic": "true", class: "sr-only", ref: (el) => (this.liveRegionEl = el) }, this.announcement)));
+        return (h("div", { key: 'edfca7bcea21613113e9498ce7f9aa5fc7546ce2', class: "list-wrapper" }, (this.isInNestedSelect || this.search || this.visibleSelectAllButton) && this.renderNonOptions(), h("div", { key: '443fbc27fa3f25984f5eaada522a990b6941a5dd', id: "list", class: "options-wrapper", tabindex: -1, role: "listbox", "aria-multiselectable": this.multiple ? "true" : null, "aria-label": this.optgroupLabel, ref: (el) => (this.listboxEl = el), style: { "--max-height": this.effectiveMaxHeight } }, this.searchTerm && this.filteredOptions.length === 0 && this.renderSearchFailedMessage(), this.multiple && this.renderCloneOptions(), h("slot", { key: '7f6fb3e4667fcd951e98b7e5466416de817a8e55' })), h("div", { key: '8753468e7a2dd5bd17bd1cfdf72d7eac0b4faf6e', id: "optionlist-announcement", "aria-live": "polite", "aria-atomic": "true", class: "sr-only", ref: (el) => (this.liveRegionEl = el) }, this.announcement)));
     }
     static get is() { return "priv-option-list"; }
     static get originalStyleUrls() {