@watermarkinsights/ripple 0.0.1 → 0.1.0-alpha.1

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

@@ -1,14 +1,21 @@
 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;
+    private nextBtnEl;
+    private liveRegionEl;
     private today;
     disabled: boolean;
-    view: string;
+    view: "month" | "year";
     focusDate: string;
     startDate?: string;
     endDate?: string;
     hoverDate?: string;
+    announcement: string;
     cellTriggered: EventEmitter<{
         cal: HTMLPrivCalendarElement;
         cell: HTMLElement;
@@ -22,6 +29,11 @@ export declare class PrivCalendar {
     private calType;
     private calName;
     private calInstructions;
+    private previousMonthButtonLabel;
+    private previousYearButtonLabel;
+    private nextMonthButtonLabel;
+    private nextYearButtonLabel;
+    private uid;
     setCalName(): void;
     setCalType(): void;
     componentWillLoad(): void;
@@ -69,9 +81,13 @@ export declare class PrivCalendar {
     focusLastFocusable(): Promise<void>;
     focusCell(): Promise<void>;
     toggleBusyAttribute(state: string): void;
-    renderCalendarDate: (date: string, index: number, eitherStart?: string, eitherEnd?: string) => any;
+    announce(message: string): void;
+    announceMonthYear(): void;
+    renderCalendarDate: (date: string, eitherStart?: string, eitherEnd?: string) => any;
     renderMonth(month: string, index: number): any;
-    renderDayView(): any;
+    renderHeader(): any;
+    renderToggleButton(): any;
     renderMonthView(): any;
+    renderYearView(): any;
     render(): any;
 }

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

@@ -1,4 +1,117 @@
 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.
+ *
+ * @category Form Inputs
+ *
+ * @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} />
+ *
+ */
 export declare class DateRange {
     el: HTMLWmDateRangeElement;
     private wrapperEl;
@@ -7,33 +120,97 @@ export declare class DateRange {
     private endInputEl;
     private startCalEl;
     private endCalEl;
-    private labelEl;
     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?;
     private oldFocusVal?;
-    private openUp;
-    private calWidth;
-    availSpace: number;
-    private hiddenOverflowParent?;
-    private popupClicked;
-    private toggleButtonClicked;
+    private readonly calWidth;
     isExpanded: boolean;
+    canOpen: boolean;
+    private hasAnchor;
+    private readonly popupMaxHeight;
+    private fit;
+    private debouncedCheckCanOpen;
+    private pf_repositionRAF;
+    pf_reposition(): void;
+    findScrollable(neededScroll: number): HTMLElement | null;
+    measureFit(): PopoverPlacement | null;
+    checkCanOpen(): void;
     private formats;
     get _disabled(): boolean;
     get focusDates(): string[];
@@ -44,30 +221,44 @@ export declare class DateRange {
     updateValueStart(): void;
     updateValueEnd(): void;
     handleErrorMessage(): void;
-    togglePopup(): void;
+    pf_positionDropdown(): void;
+    handleToggle(ev: ToggleEvent): void;
     closePopup(returnFocus?: boolean): void;
-    openPopup(): void;
     handleFocus(): void;
     handleBlur(): void;
     handleStartInputBlur(): void;
     handleEndInputBlur(): void;
     handleStartInput(ev: Event): void;
     handleEndInput(ev: Event): void;
-    handleKey(ev: KeyboardEvent): void;
-    blurHandler(): void;
-    handleBlurOnWindow(): void;
     handleDateFocus(ev: CustomEvent): void;
     handlePopupBlurred(ev: CustomEvent): void;
+    handleKeydown(ev: KeyboardEvent): void;
     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;
-    setAvailSpace(): void;
     componentWillLoad(): void;
+    componentDidLoad(): void;
+    disconnectedCallback(): void;
     announce(message: string): void;
-    renderCalendars(): any;
     render(): any;
 }

package/dist/types/components/datepickers/wm-datepicker.d.ts

@@ -1,49 +1,227 @@
 import { EventEmitter } from "../../stencil-public-runtime";
+import { PopoverPlacement } from "../../global/interfaces";
+/**
+ * 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">`.
+ *
+ * @category Form Inputs
+ *
+ * @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} />
+ *
+ */
 export declare class DatePicker {
     el: HTMLWmDatepickerElement;
     private liveRegionEl;
     private dpWrapperEl;
-    private labelWrapperEl;
     private inputEl;
     private calEl;
     private toggleEl;
     private popupEl;
+    private anchorEl;
+    /**
+     * @description 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.
+     */
     value?: string;
+    /**
+     * @description Disables the datepicker, preventing all interaction.
+     * @default false
+     */
     disabled: boolean;
+    /**
+     * @description The expected date format. Shown in the input placeholder and announced to screen reader users.
+     * @default "mm/dd/yyyy"
+     */
     dateFormat: string;
+    /**
+     * @description Puts the component in an error state and displays this message below the input.
+     */
     errorMessage?: string;
+    /**
+     * @description Position of the label relative to the input. `'none'` hides the label visually but keeps it accessible via `aria-label`.
+     * @default "top"
+     */
     labelPosition: "top" | "left" | "none";
+    /**
+     * @description Visible label for the input. Required even when `label-position` is `'none'` — used as the ARIA accessible name.
+     * @required
+     */
     label: string;
+    /**
+     * @description Displays a required-field asterisk (*) next to the label.
+     * @default false
+     */
     requiredField: boolean;
+    /**
+     * @description 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.
+     */
     preselected?: string;
+    /**
+     * @description Fires when the user selects a date from the calendar popup.
+     * @eventDetails {{ date: string }} date — the selected date in ISO format (YYYY-MM-DD).
+     */
     wmDatepickerDateSelected: EventEmitter;
+    /**
+     * @description Fires when the text input loses focus.
+     */
     wmDatepickerInputBlurred: EventEmitter;
-    private openUp;
-    private popupClicked;
-    private toggleButtonClicked;
     isExpanded: boolean;
+    canOpen: boolean;
+    private readonly calWidth;
+    private readonly popupMaxHeight;
+    private hasAnchor;
+    private fit;
+    private debouncedCheckCanOpen;
+    private pf_repositionRAF;
+    pf_reposition(): void;
+    findScrollable(neededScroll: number): HTMLElement | null;
+    measureFit(): PopoverPlacement | null;
+    checkCanOpen(): void;
     get isDisabled(): boolean;
     get calendarDate(): string;
     handleDisabledChange(): void;
     updateValue(): void;
     announceError(): void;
-    togglePopup(): void;
+    pf_positionDropdown(): void;
+    handleToggle(ev: ToggleEvent): void;
     closePopup(returnFocus?: boolean): void;
-    openPopup(): void;
     handleInput(ev: Event): void;
     handleInputBlur(): void;
     handleInputFocus(): void;
     handleInputChange(): void;
-    handleKey(ev: KeyboardEvent): void;
-    blurHandler(): void;
-    handleBlurOnWindow(): void;
+    handleLabelMouseEnter(ev: MouseEvent): void;
+    handleKeydown(ev: KeyboardEvent): void;
     handleCellTriggered(ev: CustomEvent): void;
-    reformatDate(inputFormat: string, outputFormat: string, date?: string): Promise<string>;
-    reformatDateInternal(inputFormat: string, outputFormat: string, date?: string): string;
+    /**
+     * @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"
+     */
+    reformatDate(inputFormat: "US" | "INT" | "ISO", outputFormat: "US" | "INT" | "ISO", date?: string): Promise<string>;
+    reformatDateInternal(inputFormat: "US" | "INT" | "ISO", outputFormat: "US" | "INT" | "ISO", 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.
+     * @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)
+     */
     isValidIso(input?: string): Promise<boolean>;
     isValidIsoInternal(input?: string): boolean;
     componentWillLoad(): void;
     componentDidLoad(): void;
+    disconnectedCallback(): void;
     announce(message: string): void;
     render(): any;
 }

package/dist/types/components/selects/priv-option-list/priv-option-list.d.ts

@@ -1,4 +1,10 @@
 import { EventEmitter } from "../../../stencil-public-runtime";
+/**
+ * @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 declare class PrivOptionList {
     el: HTMLPrivOptionListElement;
     private searchFieldWrapperEl;