@watermarkinsights/ripple 5.30.0 → 5.31.0-alpha.1

package/dist/types/components/charts/wm-line-chart/wm-line-chart.d.ts

@@ -1,4 +1,62 @@
 import { DataPointDetails, Line, LineChartData, SpotlightData } from "../../../global/interfaces";
+/**
+ * Visualizes how data changes over time. Ideal for trend analysis — tracking one or more
+ * metrics across chronological intervals such as semesters, academic years, or months.
+ * Supports up to 7 lines, each differentiated by both color and symbol. Data is set via the
+ * `line-data` prop (JSON string or object). Minimum width of 562 px; horizontally scrollable
+ * at smaller viewports.
+ *
+ * @keyboardInteraction
+ * - **Tab** (into chart): If `visibility-toggles` is enabled, focuses the first toggle button;
+ *   otherwise focuses the first data point.
+ * - **Tab** (on toggle button): Moves to the first data point of the first visible line.
+ * - **Shift+Tab** (on first data point, with toggles): Returns focus to the toggle buttons.
+ * - **Arrow Up / Down** (on data point): Moves focus vertically to the same x-interval on
+ *   the previous/next line.
+ * - **Arrow Left / Right** (on data point): Moves focus to the previous/next data point on
+ *   the same line.
+ * - **Arrow Left / Right** (on toggle button): Cycles between toggle buttons.
+ *
+ * @accessibility
+ * - `label`, `x-axis-label`, and `y-axis-label` are required for accessibility.
+ * - Each data point renders as `role="img"` with a detailed `aria-label` including the line
+ *   name, x-value, y-value, units, and (if `show-deltas`) the percentage change from the
+ *   previous point.
+ * - An `aria-live` region announces the line name and data point count when keyboard focus
+ *   moves to a new line.
+ * - The `description` prop is appended to the chart instructions read to screen readers —
+ *   use it to summarize the key takeaway.
+ *
+ * @usageNotes
+ * - `line-data` expects a JSON object where keys are line labels and values are objects mapping
+ *   x-axis values (strings) to y-axis values (numbers or `null` for missing data points).
+ *   In HTML, set it as a JSON string attribute; in JavaScript/React, set it as an object.
+ * - Up to 7 lines are supported — each is automatically assigned a color and symbol from
+ *   the built-in palette.
+ * - `spotlight-data` adds a single reference line spanning the whole chart. Provide an object
+ *   with a `label` key and one x-value key mapping to the y-value.
+ *
+ * @example {html} Basic line chart
+ * <wm-line-chart label="Enrollment trend" x-axis-label="Term" y-axis-label="Students"
+ *   line-data='{"Biology": {"Fall 2022": 310, "Fall 2023": 340}}'></wm-line-chart>
+ *
+ * @example {react} Basic line chart
+ * <WmLineChart label="Enrollment trend" xAxisLabel="Term" yAxisLabel="Students"
+ *   lineData={{ Biology: { "Fall 2022": 310, "Fall 2023": 340 } }} />
+ *
+ * @example {html} Multi-line with delta comparisons
+ * <wm-line-chart label="Retention rates" x-axis-label="Year" y-axis-label="Rate"
+ *   units="null,percent" show-deltas
+ *   line-data='{"Biology": {"2022": 85, "2023": 88}, "English": {"2022": 79, "2023": 82}}'>
+ * </wm-line-chart>
+ *
+ * @example {react} Multi-line with delta comparisons
+ * <WmLineChart label="Retention rates" xAxisLabel="Year" yAxisLabel="Rate"
+ *   units="null,percent" showDeltas={true}
+ *   lineData={{ Biology: { "2022": 85, "2023": 88 }, English: { "2022": 79, "2023": 82 } }} />
+ *
+ * @category Data Visualization
+ */
 export declare class LineChart {
     el: HTMLWmLineChartElement;
     private plotAreaEl;
@@ -6,21 +64,97 @@ export declare class LineChart {
     private popoverEl;
     private yIntervalsEl;
     private liveRegionEl;
+    /**
+     * @description Accessible label for the chart, used as the `aria-label` on the chart
+     * container. Required for accessibility.
+     * @required
+     */
     label: string;
+    /**
+     * @description Accessible description appended to the keyboard instructions read to screen
+     * readers. Recommended — use it to summarize the key takeaway of the chart.
+     * @default ""
+     */
     description: string;
+    /**
+     * @description Label for the x-axis (the time dimension, e.g. `"Term"`, `"Academic Year"`).
+     * Required for accessibility.
+     * @required
+     */
     xAxisLabel: string;
+    /**
+     * @description Label for the y-axis (the measured value, e.g. `"Enrollment"`, `"Score"`).
+     * Required for accessibility.
+     * @required
+     */
     yAxisLabel: string;
+    /**
+     * @description When true, renders horizontal and vertical grid lines.
+     * @default true
+     */
     showGrid: boolean;
+    /**
+     * @description Chart data. Each key is a line label (shown in the legend); each value is an
+     * object mapping x-axis values (strings) to y-axis values (numbers or `null` for missing
+     * data points). Can be set as a JSON string (HTML attribute) or as an object (JavaScript).
+     * Example: `{ "Biology": { "2022–23": 310, "2023–24": 420 } }`.
+     * @required
+     */
     lineData: string | LineChartData;
+    /**
+     * @description Two comma-separated unit labels for the x and y axes, shown in parentheses
+     * after axis labels and inside popovers. Use `null` for no unit.
+     * Example: `"null,students"` or `"semester,percent"`.
+     * @default "null,null"
+     */
     units: string;
+    /**
+     * @description CSS width of the y-axis interval label column.
+     * @default "120px"
+     */
     labelWidth: string;
+    /**
+     * @description Screen reader qualifier appended to the `aria-label` of data points that fall
+     * within a highlighted section (e.g. `"projected"`).
+     */
     highlightQualifier: string;
+    /**
+     * @description x-axis value where the highlighted background area begins. If used without
+     * `highlight-end`, the highlight extends to the right edge of the chart.
+     */
     highlightStart?: string;
+    /**
+     * @description x-axis value where the highlighted background area ends.
+     */
     highlightEnd?: string;
+    /**
+     * @description When true, renders hide/show toggle buttons in the legend, allowing users to
+     * hide individual lines.
+     * @default false
+     */
     visibilityToggles: boolean;
+    /**
+     * @description When true, a "Change since [previous x-value]" column appears in each data
+     * point's popover, showing the percentage change from the preceding data point.
+     * @default false
+     */
     showDeltas: boolean;
+    /**
+     * @description Comma-separated numbers that explicitly define the y-axis tick values.
+     * Overrides automatic range and interval calculation.
+     * Example: `"0,100,200,300"`.
+     */
     yRange?: string;
+    /**
+     * @description Adds a reference data point and a spanning horizontal line across the chart.
+     * Must include a `label` key and exactly one x-value key mapping to the y-value.
+     * Example: `{ label: "Target", "2024–25": 500 }`.
+     */
     spotlightData?: SpotlightData;
+    /**
+     * @description Number of decimal places for data point values and y-axis interval labels.
+     * If omitted, the component infers an appropriate number from the data.
+     */
     decimalPlaces?: number;
     parsedLineData: LineChartData;
     popoverIndex: number;

package/dist/types/components/charts/wm-progress-monitor/wm-progress-indicator.d.ts

@@ -1,12 +1,64 @@
 import { ChartDetails } from "../../../global/interfaces";
+/**
+ * Single progress indicator used inside a wm-progress-monitor. Renders the binary completion
+ * data for one category as either a doughnut chart (wide layout) or a horizontal bar (narrow
+ * layout), switching automatically based on the parent monitor's breakpoint.
+ *
+ * Must contain EXACTLY TWO wm-progress-slice children — one for the "complete" state and one
+ * for the "incomplete" state.
+ *
+ * @usageNotes
+ * - Always used as a direct child of wm-progress-monitor.
+ * - `label` is required for accessibility.
+ * - The optional `completion-message` is displayed inside the doughnut when the first slice
+ *   reaches 100%.
+ *
+ * @example {html} Progress indicator
+ * <wm-progress-indicator label="Biology completion">
+ *   <wm-progress-slice legend="Completed" amount="200"></wm-progress-slice>
+ *   <wm-progress-slice legend="Not Completed" amount="100"></wm-progress-slice>
+ * </wm-progress-indicator>
+ *
+ * @example {react} Progress indicator
+ * <WmProgressIndicator label="Biology completion">
+ *   <WmProgressSlice legend="Completed" amount="200" />
+ *   <WmProgressSlice legend="Not Completed" amount="100" />
+ * </WmProgressIndicator>
+ */
 export declare class ProgressIndicator {
     el: HTMLWmProgressIndicatorElement;
     private componentWrapperEl;
+    /**
+     * @description Accessible label for this indicator. Required for accessibility — used as the
+     * `aria-label` on the chart container and as the visual chart label.
+     * @required
+     */
     label?: string;
+    /**
+     * @description Optional secondary text displayed beneath the label.
+     */
     subinfo?: string;
+    /**
+     * @description Text displayed inside the doughnut ring when the completion slice reaches
+     * 100%.
+     */
     completionMessage?: string;
+    /**
+     * @description Show or hide the legend. The legend is still read by screen readers
+     * regardless of this setting.
+     * @default true
+     */
     showLegend: boolean;
+    /**
+     * @description When true, slice values are included in the legend and keyboard interaction
+     * instructions are removed from the DOM — suitable for printed output.
+     * @default false
+     */
     printMode: boolean;
+    /**
+     * @description Format for legend values when `print-mode` is enabled.
+     * @default "amount"
+     */
     printModeFormat: "amount" | "percentage";
     isTabbing: boolean;
     mode?: "doughnut" | "bar";

package/dist/types/components/charts/wm-progress-monitor/wm-progress-monitor.d.ts

@@ -1,9 +1,93 @@
 import { EventEmitter } from "../../../stencil-public-runtime";
+/**
+ * Container for one or more wm-progress-indicator elements, each showing binary completion
+ * progress (e.g. "Completed" vs "Not Completed"). Above the layout breakpoint, indicators
+ * render as doughnuts in a horizontal row; below it, they collapse into horizontal bars in a
+ * vertical stack.
+ *
+ * **Strict constraints:**
+ * 1. Each wm-progress-indicator must have EXACTLY TWO wm-progress-slice children — one for
+ *    the "complete" state and one for the "incomplete" state.
+ * 2. This component is ONLY suitable for binary completion tracking. For more than two states,
+ *    general comparisons, composition breakdowns, or distributions, use wm-chart,
+ *    wm-chart-bar, or wm-chart-column.
+ *
+ * @usageNotes
+ * - The `wmProgressMonitorModeChange` event fires once on load and again whenever the layout
+ *   switches between `"doughnut"` and `"bar"`. Listen to it to synchronize any external UI
+ *   that depends on the current layout mode.
+ * - `group-legend` is only shown in bar mode. Provide two comma-separated keys in
+ *   complete/incomplete order (e.g. `"Completed,Not Completed"`). Keys cannot contain commas.
+ *
+ * @example {html} Progress monitor
+ * <wm-progress-monitor group-legend="Completed,Not Completed">
+ *   <wm-progress-indicator label="Biology">
+ *     <wm-progress-slice legend="Completed" amount="200"
+ *       popover-title="200 students" popover-text="Completed all requirements"></wm-progress-slice>
+ *     <wm-progress-slice legend="Not Completed" amount="100"
+ *       popover-title="100 students" popover-text="Have not completed all requirements"></wm-progress-slice>
+ *   </wm-progress-indicator>
+ * </wm-progress-monitor>
+ *
+ * @example {react} Progress monitor
+ * // wmProgressMonitorModeChange fires on load and whenever the layout switches.
+ * // event.detail is "doughnut" | "bar".
+ * const [layoutMode, setLayoutMode] = useState("");
+ *
+ * <WmProgressMonitor
+ *   groupLegend="Completed,Not Completed"
+ *   onWmProgressMonitorModeChange={(e) => setLayoutMode(e.detail)}
+ * >
+ *   <WmProgressIndicator label="Biology">
+ *     <WmProgressSlice legend="Completed" amount="200"
+ *       popoverTitle="200 students" popoverText="Completed all requirements" />
+ *     <WmProgressSlice legend="Not Completed" amount="100"
+ *       popoverTitle="100 students" popoverText="Have not completed all requirements" />
+ *   </WmProgressIndicator>
+ *   <WmProgressIndicator label="English">
+ *     <WmProgressSlice legend="Completed" amount="160"
+ *       popoverTitle="160 students" popoverText="Completed all requirements" />
+ *     <WmProgressSlice legend="Not Completed" amount="40"
+ *       popoverTitle="40 students" popoverText="Have not completed all requirements" />
+ *   </WmProgressIndicator>
+ * </WmProgressMonitor>
+ *
+ * @example {html} Custom breakpoint
+ * <wm-progress-monitor breakpoint="600px" group-legend="Done,Pending">
+ *   <!-- indicators -->
+ * </wm-progress-monitor>
+ *
+ * @example {react} Custom breakpoint
+ * <WmProgressMonitor breakpoint="600px" groupLegend="Done,Pending">
+ *   {/* indicators *\/}
+ * </WmProgressMonitor>
+ *
+ * @category Data Visualization
+ */
 export declare class ProgressMonitor {
     el: HTMLWmProgressMonitorElement;
+    /**
+     * @description Controls when indicators switch between doughnut (horizontal row) and bar
+     * (vertical stack) layouts. Accepts a unit-less number (minimum number of indicators to
+     * show side-by-side — e.g. `4` → 1200 px) or an exact pixel value (e.g. `"900px"`).
+     * Defaults to the sum of all indicator widths — the component tries to fit all on one row
+     * and collapses to bars when it cannot.
+     */
     breakpoint?: number | string;
+    /**
+     * @description Two comma-separated legend keys in complete/incomplete order, displayed only
+     * in bar layout mode (e.g. `"Completed,Not Completed"`). Keys cannot contain commas.
+     */
     groupLegend?: string;
+    /**
+     * @description CSS width of the indicator labels when in bar layout mode (e.g. `"180px"`).
+     */
     barLabelsWidth?: string;
+    /**
+     * @description Fires once on load and again whenever the layout switches between `"doughnut"`
+     * and `"bar"` modes. Use this to synchronize external UI that depends on the current layout.
+     * @eventDetails `"doughnut" | "bar"` — the new layout mode.
+     */
     wmProgressMonitorModeChange: EventEmitter;
     private doughnutWidth;
     private prevMode?;

package/dist/types/components/charts/wm-progress-monitor/wm-progress-slice.d.ts

@@ -1,10 +1,54 @@
 import { EventEmitter } from "../../../stencil-public-runtime";
+/**
+ * Data slice for a wm-progress-indicator. Represents one state (complete or incomplete) in
+ * a binary progress chart. Always used as a direct child of wm-progress-indicator.
+ *
+ * Each wm-progress-indicator must contain EXACTLY TWO wm-progress-slice elements.
+ *
+ * @usageNotes
+ * - The first slice is treated as the "complete" state and the second as the "incomplete"
+ *   state for color and layout purposes.
+ * - Use `popover-title`, `popover-text`, and `popover-button-text` to surface additional
+ *   context when the segment is focused or clicked.
+ *
+ * @example {html} Complete/incomplete pair
+ * <wm-progress-slice legend="Completed" amount="200"
+ *   popover-title="200 students" popover-text="Completed all requirements"></wm-progress-slice>
+ * <wm-progress-slice legend="Not Completed" amount="100"></wm-progress-slice>
+ *
+ * @example {react} Complete/incomplete pair
+ * <WmProgressSlice legend="Completed" amount="200"
+ *   popoverTitle="200 students" popoverText="Completed all requirements" />
+ * <WmProgressSlice legend="Not Completed" amount="100" />
+ */
 export declare class ProgressSlice {
+    /**
+     * @description Label for this slice in the legend and popovers.
+     * @required
+     */
     legend?: string;
+    /**
+     * @description Numeric value for this slice as a string.
+     */
     amount?: string;
+    /**
+     * @description Title text shown in the data popover when this segment is focused or clicked.
+     */
     popoverTitle?: string;
+    /**
+     * @description Body text shown in the data popover when this segment is focused or clicked.
+     */
     popoverText?: string;
+    /**
+     * @description Label for the action button in the data popover. When set, fires
+     * `wmProgressIndicatorButtonTriggered` when clicked.
+     */
     popoverButtonText?: string;
+    /**
+     * @internal
+     * @description Internal signal notifying the parent wm-progress-indicator to re-read slice
+     * data after a prop update — not for application use.
+     */
     wmProgressSliceUpdated: EventEmitter<void>;
     componentDidUpdate(): void;
 }

package/dist/types/components/datepickers/priv-calendar/priv-calendar.d.ts

@@ -1,4 +1,8 @@
 import { EventEmitter } from "../../../stencil-public-runtime";
+/**
+ * @internal
+ * @description Internal calendar component for date pickers. Not to be used directly.
+ */
 export declare class PrivCalendar {
     el: HTMLPrivCalendarElement;
     private prevBtnEl;
@@ -6,7 +10,7 @@ export declare class PrivCalendar {
     private liveRegionEl;
     private today;
     disabled: boolean;
-    view: string;
+    view: "month" | "year";
     focusDate: string;
     startDate?: string;
     endDate?: string;
@@ -83,7 +87,7 @@ export declare class PrivCalendar {
     renderMonth(month: string, index: number): any;
     renderHeader(): any;
     renderToggleButton(): any;
-    renderDayView(): any;
     renderMonthView(): any;
+    renderYearView(): any;
     render(): any;
 }

package/dist/types/components/datepickers/wm-date-range.d.ts

@@ -1,5 +1,116 @@
 import { EventEmitter } from "../../stencil-public-runtime";
 import { PopoverPlacement } from "../../global/interfaces";
+/**
+ * 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 declare class DateRange {
     el: HTMLWmDateRangeElement;
     private wrapperEl;
@@ -11,19 +122,78 @@ export declare class DateRange {
     private toggleEl;
     private popupEl;
     private anchorEl;
+    /**
+     * @description The date format shown in the input placeholders and announced to screen readers.
+     * @default "mm/dd/yyyy"
+     */
     dateFormat: string;
+    /**
+     * @description Disables the entire date range component, preventing all interaction.
+     * @default false
+     */
     disabled: boolean;
+    /**
+     * @description Puts the component in an error state and displays this message below both
+     * inputs. Use with `invalid-start` and/or `invalid-end` to highlight specific fields.
+     */
     errorMessage?: string;
+    /**
+     * @description Puts the start date input in an error state (red border). Use with
+     * `error-message`.
+     * @default false
+     */
     invalidStart: boolean;
+    /**
+     * @description Puts the end date input in an error state (red border). Use with
+     * `error-message`.
+     * @default false
+     */
     invalidEnd: boolean;
+    /**
+     * @description Visible label for the start date input. Required for accessibility.
+     * @required
+     */
     labelStart: string;
+    /**
+     * @description Visible label for the end date input. Required for accessibility.
+     * @required
+     */
     labelEnd: string;
+    /**
+     * @description The ISO date (YYYY-MM-DD) the calendar popup opens to when first opened and
+     * no `value-start` is set. Falls back to today's date if omitted.
+     */
     preselected?: string;
+    /**
+     * @description Displays a required-field asterisk (*) next to each label.
+     * @default false
+     */
     requiredField: boolean;
+    /**
+     * @description The value of the start date input, in the format specified by `date-format`.
+     * Updated as the user types or picks from the calendar.
+     */
     valueStart?: string;
+    /**
+     * @description The value of the end date input, in the format specified by `date-format`.
+     * Updated as the user types or picks from the calendar.
+     */
     valueEnd?: string;
+    /**
+     * @description Fires when the user completes a range selection from the calendar popup.
+     * @eventDetails {{ startDate: { iso: string, us: string, int: string }, endDate: { iso: string, us: string, int: string } }}
+     * startDate and endDate — each formatted in ISO (YYYY-MM-DD), US (mm/dd/yyyy), and INT
+     * (dd/mm/yyyy). The dates are always returned in chronological order regardless of the order
+     * they were clicked.
+     */
     wmRangeSelection: EventEmitter;
+    /**
+     * @description Fires when the start date input loses focus.
+     */
     wmStartInputBlur: EventEmitter;
+    /**
+     * @description Fires when the end date input loses focus.
+     */
     wmEndInputBlur: EventEmitter;
     private date1?;
     private date2?;
@@ -65,8 +235,24 @@ export declare class DateRange {
     handleCellTriggered(ev: CustomEvent): void;
     handleOutOfCal(): void;
     handleCellHovered(ev: CustomEvent): void;
+    /**
+     * @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.
+     */
     reformatDate(inputFormat: string, outputFormat: string, date?: string): Promise<string>;
     _reformatDate(inputFormat: string, outputFormat: string, date?: string): string;
+    /**
+     * @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.
+     */
     isValidISO(input?: string): Promise<boolean>;
     _isValidISO(input?: string): boolean;
     componentWillLoad(): void;