@watermarkinsights/ripple 5.30.0 → 5.31.0-alpha.1

package/dist/collection/components/datepickers/wm-date-range.js

@@ -1,5 +1,116 @@
 import { h, Host, } from "@stencil/core";
 import { intl, dateFind, toBool, handleDisabledAttribute, dateToISO, calendar_months, debounce, findAllScrollableParents, findPositioningBoundary, } from "../../global/functions";
+/**
+ * Two linked date inputs (start and end) with a shared calendar popup for selecting a date
+ * range. Users can type or click to set each date. Provides separate error states for start
+ * and end, and emits distinct blur events for each input. Use instead of two native
+ * `<input type="date">` elements when a range is required.
+ *
+ * @keyboardInteraction
+ * - **Input fields**: Tab moves focus between start input, end input, and the calendar toggle.
+ * - **Calendar toggle**: Space / Enter opens the calendar; Escape closes it and returns focus.
+ * - **Day grid**: Arrow keys navigate dates; Enter selects. After selecting the first date,
+ *   the calendar resets for a second selection. Selecting a date earlier than the first date
+ *   automatically swaps start and end.
+ * - **Month/year selectors**: Arrow keys cycle values; Tab/Shift+Tab move focus through controls.
+ *
+ * @accessibility
+ * - `label-start` and `label-end` are required for accessibility — always provide both even if
+ *   visually implied by context.
+ * - The calendar toggle announces "Select range" to screen readers and reflects `aria-expanded`.
+ * - Validation errors are announced via an `aria-live` region when `error-message` changes.
+ * - The calendar popup hides its toggle when there is no room to display it; users can still
+ *   type dates directly into the inputs.
+ *
+ * @usageNotes
+ * - Set `value-start` and `value-end` in the format specified by `date-format` (default
+ *   `mm/dd/yyyy`). For programmatic pre-population, prefer ISO format via `preselected` and
+ *   convert with the `reformatDate` method.
+ * - `wmRangeSelection` emits a detail object with `startDate` and `endDate`, each in ISO, US,
+ *   and INT formats.
+ * - The same-date re-selection rule: clicking the same date as `date1` a second time resets the
+ *   range selection so the user can pick a new `date1`.
+ *
+ * @example {html} Basic date range
+ * <wm-date-range label-start="Start date" label-end="End date"></wm-date-range>
+ *
+ * @example {react} Basic date range
+ * // The component does not update its own values after a calendar selection --
+ * // the app must call reformatDate and set valueStart/valueEnd 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 { startDate: { iso, us, int }, endDate: { iso, us, int } }
+ * const handleRangeSelection = async (event) => {
+ *   const dr = ref.current;
+ *   const fmt = getFormatName(dr.getAttribute('date-format'));
+ *   dr.valueStart = await dr.reformatDate('ISO', fmt, event.detail.startDate.iso);
+ *   dr.valueEnd = await dr.reformatDate('ISO', fmt, event.detail.endDate.iso);
+ *   dr.errorMessage = '';
+ * };
+ *
+ * const handleInputBlurred = async (field) => {
+ *   const dr = ref.current;
+ *   const fmt = getFormatName(dr.getAttribute('date-format'));
+ *   const value = field === 'start' ? dr.valueStart : dr.valueEnd;
+ *   if (value) {
+ *     const iso = await dr.reformatDate(fmt, 'ISO', value);
+ *     if (await dr.isValidISO(iso)) {
+ *       const display = await dr.reformatDate('ISO', fmt, iso);
+ *       if (field === 'start') dr.valueStart = display;
+ *       else dr.valueEnd = display;
+ *       dr.errorMessage = '';
+ *       dr.invalidStart = false;
+ *       dr.invalidEnd = false;
+ *     } else {
+ *       dr.errorMessage = `Please enter a valid date in the format ${dr.getAttribute('date-format') ?? 'mm/dd/yyyy'}`;
+ *       if (field === 'start') dr.invalidStart = true;
+ *       else dr.invalidEnd = true;
+ *     }
+ *   }
+ * };
+ *
+ * <WmDateRange
+ *   ref={ref}
+ *   labelStart="Start date"
+ *   labelEnd="End date"
+ *   onWmRangeSelection={handleRangeSelection}
+ *   onWmStartInputBlur={() => handleInputBlurred('start')}
+ *   onWmEndInputBlur={() => handleInputBlurred('end')}
+ * />
+ *
+ * @example {html} Required fields with validation
+ * <wm-date-range label-start="From" label-end="To" required-field></wm-date-range>
+ *
+ * @example {react} Required fields with validation
+ * <WmDateRange
+ *   ref={ref}
+ *   labelStart="From"
+ *   labelEnd="To"
+ *   requiredField={true}
+ *   onWmRangeSelection={handleRangeSelection}
+ *   onWmStartInputBlur={() => handleInputBlurred('start')}
+ *   onWmEndInputBlur={() => handleInputBlurred('end')}
+ * />
+ *
+ * @example {html} International date format
+ * <wm-date-range label-start="Start" label-end="End" date-format="dd/mm/yyyy"></wm-date-range>
+ *
+ * @example {react} International date format
+ * <WmDateRange labelStart="Start" labelEnd="End" dateFormat="dd/mm/yyyy" />
+ *
+ * @example {html} Disabled
+ * <wm-date-range label-start="Start" label-end="End" disabled></wm-date-range>
+ *
+ * @example {react} Disabled
+ * <WmDateRange labelStart="Start" labelEnd="End" disabled={true} />
+ *
+ * @category Form Inputs
+ */
 export class DateRange {
     constructor() {
         this.calWidth = 681; // 673 + 8px of room
@@ -276,8 +387,8 @@ export class DateRange {
             this.endCalEl.startDate = undefined;
             this.endCalEl.endDate = undefined;
             this.endCalEl.hoverDate = undefined;
-            this.startCalEl.view = "day";
-            this.endCalEl.view = "day";
+            this.startCalEl.view = "month";
+            this.endCalEl.view = "month";
             this.isExpanded = false;
         }
     }
@@ -330,7 +441,7 @@ export class DateRange {
             const oldYear = dateFind.year.asInt(this.oldFocusVal);
             const newMonth = dateFind.month.asInt(newFocusVal);
             const oldMonth = dateFind.month.asInt(this.oldFocusVal);
-            if (cal.view === "day") {
+            if (cal.view === "month") {
                 if (newYear != oldYear || newMonth != oldMonth) {
                     this.liveRegionEl.innerHTML = intl.formatMessage({
                         id: "date.viewingMonth",
@@ -443,6 +554,16 @@ export class DateRange {
         this.startCalEl.hoverDate = this.startCalEl.startDate === ev.detail ? undefined : ev.detail;
         this.endCalEl.hoverDate = this.endCalEl.startDate === ev.detail ? undefined : ev.detail;
     }
+    /**
+     * @description Converts a date string between `"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 (`"US"`, `"INT"`, or `"ISO"`).
+     * @param outputFormat - Desired output format (`"US"`, `"INT"`, or `"ISO"`).
+     * @param date - The date string to reformat.
+     * @returns The reformatted date string, an empty string if `date` is omitted, or the original
+     * string unchanged if it cannot be parsed.
+     */
     async reformatDate(inputFormat, outputFormat, date) {
         return this._reformatDate(inputFormat, outputFormat, date);
     }
@@ -480,6 +601,12 @@ export class DateRange {
             }
         }
     }
+    /**
+     * @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.
+     */
     async isValidISO(input) {
         return this._isValidISO(input);
     }
@@ -529,25 +656,25 @@ export class DateRange {
     }
     render() {
         var _a, _b, _c, _d;
-        return (h(Host, { key: '9840d0cb5b3aff858d939fbe2d67dc1d51535c05', "aria-busy": "false" }, h("div", { key: '71e3eb8f71812140abc538cbfec3111c2e2b9cba', ref: (d) => (this.wrapperEl = d), class: "wrapper" }, h("div", { key: '094295f1471f1ba0eaea5c65617447efc5dca770', class: "range-wrapper cal", ref: (el) => (this.anchorEl = el) }, h("div", { key: '00bcfac555be41fe8b2f885e2a0335c8d41efd28', class: "label-wrapper", id: "start-label-wrapper" }, h("label", { key: '1f23a2bb3163e550f9929be4dbd6335bf5bf6579', id: "startlabel", htmlFor: "start-date-input", class: "label" }, this.labelStart, this.requiredField && (h("span", { key: '40dc9394b28b616e1dbfdb028f504474e8576fce', "aria-hidden": "true", class: "required" }, "*")))), h("div", { key: '75addeddb3c54576c90fb9c6c662e525934f6166', class: "label-wrapper", id: "end-label-wrapper" }, h("label", { key: '3015302e413b2bd033dffb9edacc1ecb7c06fb68', id: "endlabel", htmlFor: "end-date-input", class: "label" }, this.labelEnd, this.requiredField && (h("span", { key: '6f27560f7730e1efc19c8f9f7b1845f7a4fc5489', "aria-hidden": "true", class: "required" }, "*")))), h("input", { key: 'a350aea0fa321f076f7b0258e6717b349f551813', disabled: this._disabled, type: "text", id: "start-date-input", class: `date-input input ${this.invalidStart ? "invalid" : ""}`, name: "start-date", placeholder: this.dateFormat, value: this.valueStart, onFocus: () => this.handleFocus(), onInput: (ev) => this.handleStartInput(ev), onBlur: () => this.handleStartInputBlur(), ref: (input) => (this.startInputEl = input), "aria-describedby": "date-format-hint error", "aria-label": this.labelStart, "aria-required": this.requiredField ? "true" : null }), h("div", { key: 'f3d74eae497160213ac05d99467ab254d30167b1', id: "hyphen" }, "\u00A0-\u00A0"), h("input", { key: '4e77331018a0ce06846adae9ce01f0acd556dcd8', disabled: this._disabled, type: "text", id: "end-date-input", class: `date-input input ${this.invalidEnd ? "invalid" : ""}`, name: "end-date", placeholder: this.dateFormat, value: this.valueEnd, onFocus: () => this.handleFocus(), onInput: (ev) => this.handleEndInput(ev), onBlur: () => this.handleEndInputBlur(), ref: (input) => (this.endInputEl = input), "aria-describedby": "date-format-hint error", "aria-label": this.labelEnd, "aria-required": this.requiredField ? "true" : null }), h("div", { key: '47f502431bd898d5baab11e483990585e49b648e', class: "toggle-wrapper", id: "toggle-wrapper" }, this.canOpen && (h("button", { key: 'b7dc42e4733418c6da7ecb5eae5a896ad0d92f4d', disabled: this.disabled, "aria-describedby": "start-date-input end-date-input", "aria-label": intl.formatMessage({
+        return (h(Host, { key: '576f553f284eef57b1b80d2770ebaaaa486b2a65', "aria-busy": "false" }, h("div", { key: 'd1b8749f84940f811277ea0d4cbdf6548f552a21', ref: (d) => (this.wrapperEl = d), class: "wrapper" }, h("div", { key: '4879d908500055bbcf9435445a3c3352e08c8239', class: "range-wrapper cal", ref: (el) => (this.anchorEl = el) }, h("div", { key: '7659bcc76e110904961a006f57148c8eaf8ad81e', class: "label-wrapper", id: "start-label-wrapper" }, h("label", { key: '824d8f9ec6bd3ea6ec29e2670f30b4c2d83955a3', id: "startlabel", htmlFor: "start-date-input", class: "label" }, this.labelStart, this.requiredField && (h("span", { key: '8553c682f6a1be43f6a76a97d22ba67447c90c6d', "aria-hidden": "true", class: "required" }, "*")))), h("div", { key: 'f8d28e4e6759cb11622d9386873d6419f4de3fdc', class: "label-wrapper", id: "end-label-wrapper" }, h("label", { key: '4c3d0bbf5a58a4a0c567041fe51002f897f29592', id: "endlabel", htmlFor: "end-date-input", class: "label" }, this.labelEnd, this.requiredField && (h("span", { key: 'aabf372102b5cb425108c3b95caeebe35a7e890d', "aria-hidden": "true", class: "required" }, "*")))), h("input", { key: 'e0f084896c043648d79cae89a1aa192395bf61de', disabled: this._disabled, type: "text", id: "start-date-input", class: `date-input input ${this.invalidStart ? "invalid" : ""}`, name: "start-date", placeholder: this.dateFormat, value: this.valueStart, onFocus: () => this.handleFocus(), onInput: (ev) => this.handleStartInput(ev), onBlur: () => this.handleStartInputBlur(), ref: (input) => (this.startInputEl = input), "aria-describedby": "date-format-hint error", "aria-label": this.labelStart, "aria-required": this.requiredField ? "true" : null }), h("div", { key: '8dc7e190cfe901e308d2a665f93d7d89f2fea731', id: "hyphen" }, "\u00A0-\u00A0"), h("input", { key: 'e354bfaa40907bd99b6d0e152869f170b5f90f4f', disabled: this._disabled, type: "text", id: "end-date-input", class: `date-input input ${this.invalidEnd ? "invalid" : ""}`, name: "end-date", placeholder: this.dateFormat, value: this.valueEnd, onFocus: () => this.handleFocus(), onInput: (ev) => this.handleEndInput(ev), onBlur: () => this.handleEndInputBlur(), ref: (input) => (this.endInputEl = input), "aria-describedby": "date-format-hint error", "aria-label": this.labelEnd, "aria-required": this.requiredField ? "true" : null }), h("div", { key: '75e537ec719c5aaabff86531fa5abf8b72a2d3ef', class: "toggle-wrapper", id: "toggle-wrapper" }, this.canOpen && (h("button", { key: '5b65696c08716602b4db77a21c329e5b1b53adf9', disabled: this.disabled, "aria-describedby": "start-date-input end-date-input", "aria-label": intl.formatMessage({
                 id: "date.selectRange",
                 defaultMessage: "Select range",
                 description: "Button text for screen readers.",
-            }), ref: (el) => (this.toggleEl = el), "aria-expanded": `${this.isExpanded}`, class: "toggle", id: "toggle", popoverTarget: "popup-wrapper", popoverTargetAction: "toggle" }, h("span", { key: '8fcd8c7cbaff39440838c15354de40ea79230dfd', class: "svg-icon svg-date" }), h("span", { key: '392288ecb5e6617395b306d9e7993ef41c9f27d2', class: "calendar", title: intl.formatMessage({
+            }), ref: (el) => (this.toggleEl = el), "aria-expanded": `${this.isExpanded}`, class: "toggle", id: "toggle", popoverTarget: "popup-wrapper", popoverTargetAction: "toggle" }, h("span", { key: '0cc4cbf6dfd6da128d9a33a72e3e89dab812c72a', class: "svg-icon svg-date" }), h("span", { key: '9fe596dc14752fa2f505aa6c1ab893ffa1f14b1b', class: "calendar", title: intl.formatMessage({
                 id: "date.calendarView",
                 defaultMessage: "Calendar View",
                 description: "Calendar button",
-            }) })))), h("div", { key: 'a88e17a38bbee302551a7abc458f9a387afe1d89', class: `popup-wrapper popup-range ${this.startCalEl && this.startCalEl.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: '1b7934722e2b0187ae6424141cc1e08cb5dda8d0', class: `popup-wrapper popup-range ${this.startCalEl && this.startCalEl.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: '968c8f59c78dc1358295d5f5a7db69952f31da35', class: "trapfocus", tabIndex: this.isExpanded ? 0 : undefined, onFocus: () => this.endCalEl.focusLastFocusable() }), h("priv-calendar", { key: '73c5f5df127cb560aeaf7131ce4ba6e167857693', ref: (el) => (this.startCalEl = el), onDateFocus: (ev) => this.handleDateFocus(ev) }), h("priv-calendar", { key: 'f3177d31c0bcf97d010e16ee4f8ee43568fd28b2', ref: (el) => (this.endCalEl = el), onDateFocus: (ev) => this.handleDateFocus(ev) }), h("div", { key: '278ae43445deae7239390b01f0a01c16f3fc0f17', class: "trapfocus", tabIndex: this.isExpanded ? 0 : undefined, onFocus: () => this.startCalEl.focusFirstFocusable() }))), h("div", { key: '2528c193f264b94886be679235595c69d081800c' }, h("div", { key: '4e9a81c12822d560cb0b949b2da38b6f26204c32', id: "live-region", "aria-live": "polite", "aria-relevant": "text", class: "sr-only" }), h("div", { key: '82603d1a7ed918904df6649f76549a41a644d2ed', id: "month-title", class: "sr-only" }, intl.formatMessage({
+            onToggle: (ev) => this.handleToggle(ev) }, h("div", { key: 'cde40c3cdaee6e1641f7062debb2c301850d8967', class: "trapfocus", tabIndex: this.isExpanded ? 0 : undefined, onFocus: () => this.endCalEl.focusLastFocusable() }), h("priv-calendar", { key: 'c2f18d3d19fd9fded7c3bda37a521843870aae91', ref: (el) => (this.startCalEl = el), onDateFocus: (ev) => this.handleDateFocus(ev) }), h("priv-calendar", { key: '2f99a6e4dadfe42b53fe207871af112bf2780c56', ref: (el) => (this.endCalEl = el), onDateFocus: (ev) => this.handleDateFocus(ev) }), h("div", { key: 'df0c41dd0779a7586e666f5b530d7f7d449a54bb', class: "trapfocus", tabIndex: this.isExpanded ? 0 : undefined, onFocus: () => this.startCalEl.focusFirstFocusable() }))), h("div", { key: '7f3971b1af72d54ccc07f52531c1d17fecb6d7ab' }, h("div", { key: '0bed6cb1cf5f5ada1c926623d8b6dacb5dc34287', id: "live-region", "aria-live": "polite", "aria-relevant": "text", class: "sr-only" }), h("div", { key: '237bf9699d0305031f0f0bd04c9d8027c84dc1ed', id: "month-title", class: "sr-only" }, intl.formatMessage({
             id: "date.selectMonth",
             defaultMessage: "Activate to select a month.",
             description: "Calendar button",
-        })), h("div", { key: '0c98b239ffa8a8f6f27a9eee4e302f8daddc4c89', id: "year-title", class: "sr-only" }, intl.formatMessage({
+        })), h("div", { key: 'ce586f8192676950d0221ce709b79dba29a956c8', id: "year-title", class: "sr-only" }, intl.formatMessage({
             id: "date.selectYear",
             defaultMessage: "Activate to select a year.",
             description: "Calendar button",
-        }))), h("div", { key: '13e1dc0b81ffedda3b7f6316ee07d2dc9a8712b9', id: "error", class: "error" }, this.errorMessage), h("span", { key: '5b8d811a975b5dec9e0e9e2c81bd56d5360f178a', id: "date-format-hint", class: "sr-only" }, this.dateFormat), h("div", { key: '0746adc5f997c314567c5f942de26216a449ce57', ref: (el) => (this.liveRegionEl = el), class: "sr-only", "aria-live": "polite", "aria-atomic": "true" }))));
+        }))), h("div", { key: '913aaac21cc36b8172a1b28b45d9d2c9432e623f', id: "error", class: "error" }, this.errorMessage), h("span", { key: '066481609119ee85db50856e30b7c2f188bab078', id: "date-format-hint", class: "sr-only" }, this.dateFormat), h("div", { key: '77f64053567c3c2a4e2038205a9787a1cfa846b8', ref: (el) => (this.liveRegionEl = el), class: "sr-only", "aria-live": "polite", "aria-atomic": "true" }))));
     }
     static get is() { return "wm-date-range"; }
     static get encapsulation() { return "shadow"; }
@@ -575,7 +702,13 @@ export class DateRange {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "The date format shown in the input placeholders and announced to screen readers."
+                        }, {
+                            "name": "default",
+                            "text": "\"mm/dd/yyyy\""
+                        }],
                     "text": ""
                 },
                 "attribute": "date-format",
@@ -593,7 +726,13 @@ export class DateRange {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Disables the entire date range component, preventing all interaction."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
                     "text": ""
                 },
                 "attribute": "disabled",
@@ -611,7 +750,10 @@ export class DateRange {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Puts the component in an error state and displays this message below both\ninputs. Use with `invalid-start` and/or `invalid-end` to highlight specific fields."
+                        }],
                     "text": ""
                 },
                 "attribute": "error-message",
@@ -628,7 +770,13 @@ export class DateRange {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Puts the start date input in an error state (red border). Use with\n`error-message`."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
                     "text": ""
                 },
                 "attribute": "invalid-start",
@@ -646,7 +794,13 @@ export class DateRange {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Puts the end date input in an error state (red border). Use with\n`error-message`."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
                     "text": ""
                 },
                 "attribute": "invalid-end",
@@ -664,7 +818,13 @@ export class DateRange {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Visible label for the start date input. Required for accessibility."
+                        }, {
+                            "name": "required",
+                            "text": undefined
+                        }],
                     "text": ""
                 },
                 "attribute": "label-start",
@@ -682,7 +842,13 @@ export class DateRange {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Visible label for the end date input. Required for accessibility."
+                        }, {
+                            "name": "required",
+                            "text": undefined
+                        }],
                     "text": ""
                 },
                 "attribute": "label-end",
@@ -700,7 +866,10 @@ export class DateRange {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "The ISO date (YYYY-MM-DD) the calendar popup opens to when first opened and\nno `value-start` is set. Falls back to today's date if omitted."
+                        }],
                     "text": ""
                 },
                 "attribute": "preselected",
@@ -717,7 +886,13 @@ export class DateRange {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Displays a required-field asterisk (*) next to each label."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
                     "text": ""
                 },
                 "attribute": "required-field",
@@ -735,7 +910,10 @@ export class DateRange {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "The value of the start date input, in the format specified by `date-format`.\nUpdated as the user types or picks from the calendar."
+                        }],
                     "text": ""
                 },
                 "attribute": "value-start",
@@ -753,7 +931,10 @@ export class DateRange {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "The value of the end date input, in the format specified by `date-format`.\nUpdated as the user types or picks from the calendar."
+                        }],
                     "text": ""
                 },
                 "attribute": "value-end",
@@ -776,7 +957,13 @@ export class DateRange {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires when the user completes a range selection from the calendar popup."
+                        }, {
+                            "name": "eventDetails",
+                            "text": "{{ startDate: { iso: string, us: string, int: string }, endDate: { iso: string, us: string, int: string } }}\nstartDate and endDate \u2014 each formatted in ISO (YYYY-MM-DD), US (mm/dd/yyyy), and INT\n(dd/mm/yyyy). The dates are always returned in chronological order regardless of the order\nthey were clicked."
+                        }],
                     "text": ""
                 },
                 "complexType": {
@@ -791,7 +978,10 @@ export class DateRange {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires when the start date input loses focus."
+                        }],
                     "text": ""
                 },
                 "complexType": {
@@ -806,7 +996,10 @@ export class DateRange {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires when the end date input loses focus."
+                        }],
                     "text": ""
                 },
                 "complexType": {
@@ -824,15 +1017,15 @@ export class DateRange {
                     "parameters": [{
                             "name": "inputFormat",
                             "type": "string",
-                            "docs": ""
+                            "docs": "- Format of the input date string (`\"US\"`, `\"INT\"`, or `\"ISO\"`)."
                         }, {
                             "name": "outputFormat",
                             "type": "string",
-                            "docs": ""
+                            "docs": "- Desired output format (`\"US\"`, `\"INT\"`, or `\"ISO\"`)."
                         }, {
                             "name": "date",
                             "type": "string | undefined",
-                            "docs": ""
+                            "docs": "- The date string to reformat."
                         }],
                     "references": {
                         "Promise": {
@@ -844,7 +1037,22 @@ export class DateRange {
                 },
                 "docs": {
                     "text": "",
-                    "tags": []
+                    "tags": [{
+                            "name": "description",
+                            "text": "Converts a date string between `\"US\"` (mm/dd/yyyy), `\"INT\"` (dd/mm/yyyy),\nand `\"ISO\"` (YYYY-MM-DD). Direct US \u2194 INT conversion is not supported \u2014 route through\nISO as an intermediate step."
+                        }, {
+                            "name": "param",
+                            "text": "inputFormat - Format of the input date string (`\"US\"`, `\"INT\"`, or `\"ISO\"`)."
+                        }, {
+                            "name": "param",
+                            "text": "outputFormat - Desired output format (`\"US\"`, `\"INT\"`, or `\"ISO\"`)."
+                        }, {
+                            "name": "param",
+                            "text": "date - The date string to reformat."
+                        }, {
+                            "name": "returns",
+                            "text": "The reformatted date string, an empty string if `date` is omitted, or the original\nstring unchanged if it cannot be parsed."
+                        }]
                 }
             },
             "isValidISO": {
@@ -853,7 +1061,7 @@ export class DateRange {
                     "parameters": [{
                             "name": "input",
                             "type": "string | undefined",
-                            "docs": ""
+                            "docs": "- The string to validate."
                         }],
                     "references": {
                         "Promise": {
@@ -865,7 +1073,16 @@ export class DateRange {
                 },
                 "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."
+                        }]
                 }
             }
         };