@watermarkinsights/ripple 5.30.0 → 5.31.0-alpha.1

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

@@ -1,5 +1,116 @@
 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">`.
+ *
+ * @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 declare class DatePicker {
     el: HTMLWmDatepickerElement;
     private liveRegionEl;
@@ -9,15 +120,51 @@ export declare class DatePicker {
     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;
     isExpanded: boolean;
     canOpen: boolean;
@@ -46,8 +193,29 @@ export declare class DatePicker {
     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;

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;

package/dist/types/components/selects/wm-nested-select/wm-nested-select.d.ts

@@ -1,4 +1,102 @@
 import { EventEmitter } from "../../../stencil-public-runtime";
+/**
+ * Dropdown list of grouped options that allows single or multi-select. Like wm-select but
+ * options are organized into labeled categories via a two-level hierarchy. Composed of a
+ * parent wm-nested-select, one or more wm-optgroup children, and wm-option elements inside
+ * each group.
+ *
+ * @keyboardInteraction
+ * - **Closed button**: Space / Enter / Arrow Down opens the dropdown and focuses the first
+ *   group; Arrow Up opens and focuses the last group.
+ * - **Group level**: Arrow Up / Down navigate group buttons; Arrow Right / Enter enters the
+ *   group; Escape closes the dropdown.
+ * - **Option level (inside a group)**: Arrow Up / Down navigate options; Arrow Left returns
+ *   to the group list; Home / End jump to first / last option; typing a letter jumps to the
+ *   first matching option.
+ * - **Tab** (anywhere in dropdown): Closes the dropdown.
+ *
+ * @accessibility
+ * - `label` is required even when `label-position` is `"none"` — it is used as the dropdown's
+ *   ARIA accessible name.
+ * - Group buttons render with `role="menuitem"` inside a `role="menu"`. The option level
+ *   renders as a `role="listbox"` with `role="option"` items.
+ * - Validation errors are announced via an `aria-live` region when `error-message` changes.
+ *
+ * @usageNotes
+ * - Selection state is maintained via the `selected` prop on each wm-option child.
+ * - To respond to selection changes, listen for `wmOptionSelected` (declared on wm-option but
+ *   bubbles to wm-nested-select). `event.detail` is the `HTMLWmOptionElement`; read `.value`
+ *   or `.textContent` to get the selected value.
+ * - `select-all` adds a "Select All / Deselect All" toggle at the top of each group; it
+ *   requires `multiple` to be set.
+ * - `search` filters options within the currently open group only.
+ *
+ * @example {html} Single-select nested select
+ * <wm-nested-select label="Department">
+ *   <wm-optgroup label="Sciences">
+ *     <wm-option selected>Select a department</wm-option>
+ *     <wm-option>Biology</wm-option>
+ *   </wm-optgroup>
+ *   <wm-optgroup label="Humanities">
+ *     <wm-option>English</wm-option>
+ *   </wm-optgroup>
+ * </wm-nested-select>
+ *
+ * @example {react} Single-select nested select
+ * const [department, setDepartment] = useState('');
+ *
+ * // event.detail is the selected HTMLWmOptionElement
+ * const handleSelect = (event) => {
+ *   setDepartment(event.detail.value ?? event.detail.textContent);
+ * };
+ *
+ * <WmNestedSelect label="Department" onWmOptionSelected={handleSelect}>
+ *   <WmOptgroup label="Sciences">
+ *     <WmOption selected>Select a department</WmOption>
+ *     <WmOption value="bio">Biology</WmOption>
+ *   </WmOptgroup>
+ *   <WmOptgroup label="Humanities">
+ *     <WmOption value="eng">English</WmOption>
+ *   </WmOptgroup>
+ * </WmNestedSelect>
+ *
+ * @example {html} Multi-select with Select All
+ * <wm-nested-select label="Programs" multiple select-all>
+ *   <wm-optgroup label="Sciences">
+ *     <wm-option value="bio">Biology</wm-option>
+ *     <wm-option value="chem">Chemistry</wm-option>
+ *   </wm-optgroup>
+ * </wm-nested-select>
+ *
+ * @example {react} Multi-select with Select All
+ * const [selected, setSelected] = useState([]);
+ *
+ * // event.detail is the HTMLWmOptionElement that was selected or deselected
+ * const handleSelect = (event) => {
+ *   const value = event.detail.value ?? event.detail.textContent;
+ *   setSelected((prev) => [...prev, value]);
+ * };
+ *
+ * const handleDeselect = (event) => {
+ *   const value = event.detail.value ?? event.detail.textContent;
+ *   setSelected((prev) => prev.filter((v) => v !== value));
+ * };
+ *
+ * <WmNestedSelect
+ *   label="Programs"
+ *   multiple={true}
+ *   selectAll={true}
+ *   onWmOptionSelected={handleSelect}
+ *   onWmOptionDeselected={handleDeselect}
+ * >
+ *   <WmOptgroup label="Sciences">
+ *     <WmOption value="bio">Biology</WmOption>
+ *     <WmOption value="chem">Chemistry</WmOption>
+ *   </WmOptgroup>
+ * </WmNestedSelect>
+ *
+ * @category Basic Controls
+ */
 export declare class NestedSelect {
     el: HTMLWmNestedSelectElement;
     private buttonEl;
@@ -6,24 +104,88 @@ export declare class NestedSelect {
     private menuEl;
     private measurementAreaEl;
     private liveRegionEl;
+    /**
+     * @description Fires when focus leaves the component entirely (not when moving between
+     * internal elements such as options or group buttons).
+     */
     wmNestedSelectBlurred: EventEmitter<void>;
+    /**
+     * @description Disables the entire nested select component, preventing any interaction.
+     * @default false
+     */
     disabled: boolean;
+    /**
+     * @description Overrides the maximum height of the options dropdown. Accepts any valid CSS
+     * length value (e.g. `"300px"`).
+     * @default "200px"
+     */
     maxHeight: string;
+    /**
+     * @description Accessible label describing the dropdown's purpose. Required even when
+     * `label-position` is `"none"` — it is used as the ARIA accessible name for the button.
+     * @required
+     */
     label?: string;
+    /**
+     * @description Controls where the label is rendered relative to the dropdown button.
+     * `"none"` hides the label visually but keeps it accessible.
+     * @default "top"
+     */
     labelPosition: "top" | "left" | "none";
+    /**
+     * @description Renders a required-field asterisk (*) next to the label.
+     * @default false
+     */
     requiredField: boolean;
+    /**
+     * @description Displays the component in an error state with the provided message shown
+     * beneath the button.
+     */
     errorMessage?: string;
+    /**
+     * @description Enables multiselect mode, allowing more than one option to be selected at
+     * a time.
+     * @default false
+     */
     multiple: boolean;
+    /**
+     * @description Adds a search input that filters visible options within the currently open
+     * group.
+     * @default false
+     */
     search: boolean;
+    /**
+     * @description Adds a "Select All / Deselect All" toggle at the top of each group. Requires
+     * `multiple` to be set.
+     * @default false
+     */
     selectAll: boolean;
+    /**
+     * @description Text displayed in the trigger button when no options are selected.
+     * @default Locale-specific placeholder string
+     */
     placeholder: string;
+    /**
+     * @description Placeholder text displayed inside the search input when `search` is enabled.
+     * @default Locale-specific search placeholder string
+     */
     searchPlaceholder: string;
+    /**
+     * @description Text displayed in the trigger button when all options across all groups are
+     * selected (multiselect mode).
+     * @default Locale-specific "all selected" string
+     */
     allSelectedMessage: string;
     isExpanded: boolean;
     isGroupExpanded: boolean;
     showClearSelectionButton: boolean;
     announcement: string;
     private openUp;
+    /**
+     * @internal
+     * @description Constrains the dropdown height when it opens upward and available space above
+     * is less than maxHeight. Set programmatically — not for application use.
+     */
     constrainedMaxHeight: string;
     get isDisabled(): boolean;
     get childOptions(): HTMLWmOptionElement[];

package/dist/types/components/selects/wm-optgroup/wm-optgroup.d.ts

@@ -1,19 +1,106 @@
 import { EventEmitter } from "../../../stencil-public-runtime";
+/**
+ * Named group of wm-option elements used inside wm-nested-select. Renders as a slide-in
+ * panel that appears when the user selects the group from the top-level menu.
+ *
+ * @usageNotes
+ * - Always used as a direct child of wm-nested-select.
+ * - `label` is required — it is shown as the group heading in the dropdown menu.
+ * - The `disabled` prop prevents the group button from being clicked, hiding all its options.
+ * - `wmOptgroupAllSelected` and `wmOptgroupAllDeselected` are fired when the "Select All /
+ *   Deselect All" button inside the group is activated; they bubble to wm-nested-select.
+ *
+ * @example {html} Optgroup inside nested select
+ * <wm-nested-select label="Department">
+ *   <wm-optgroup label="Sciences">
+ *     <wm-option selected>Select a department</wm-option>
+ *     <wm-option>Biology</wm-option>
+ *   </wm-optgroup>
+ * </wm-nested-select>
+ *
+ * @example {react} Optgroup inside nested select
+ * <WmNestedSelect label="Department">
+ *   <WmOptgroup label="Sciences">
+ *     <WmOption selected={true}>Select a department</WmOption>
+ *     <WmOption>Biology</WmOption>
+ *   </WmOptgroup>
+ * </WmNestedSelect>
+ *
+ * @example {html} Disabled optgroup
+ * <wm-nested-select label="Program">
+ *   <wm-optgroup label="Sciences" disabled>
+ *     <wm-option>Biology</wm-option>
+ *   </wm-optgroup>
+ * </wm-nested-select>
+ *
+ * @example {react} Disabled optgroup
+ * <WmNestedSelect label="Program">
+ *   <WmOptgroup label="Sciences" disabled={true}>
+ *     <WmOption>Biology</WmOption>
+ *   </WmOptgroup>
+ * </WmNestedSelect>
+ */
 export declare class Optgroup {
     el: HTMLWmOptgroupElement;
     private optionListEl;
+    /**
+     * @description Display name for this group, shown as the group button text in the
+     * dropdown menu.
+     * @required
+     */
     label: string;
+    /**
+     * @internal
+     * @description Controls whether this group's option panel is currently visible. Managed
+     * by the parent wm-nested-select — not for application use.
+     */
     isExpanded: boolean;
+    /**
+     * @internal
+     * @description Propagated from the parent wm-nested-select to configure the internal
+     * option list — not for application use.
+     */
     multiple: boolean;
+    /**
+     * @description Disables this group, preventing the user from opening it or selecting any
+     * of its options.
+     * @default false
+     */
     disabled: boolean;
+    /**
+     * @description Fires when the "Select All" button inside this group is activated.
+     */
     wmOptgroupAllSelected: EventEmitter;
+    /**
+     * @description Fires when the "Deselect All" button inside this group is activated.
+     */
     wmOptgroupAllDeselected: EventEmitter;
+    /**
+     * @internal
+     * @description Signals the parent wm-nested-select that this group's panel has opened —
+     * not for application use.
+     */
     optgroupExpanded: EventEmitter;
+    /**
+     * @internal
+     * @description Signals the parent wm-nested-select that this group's panel has closed,
+     * carrying the group label so the parent can restore focus — not for application use.
+     */
     optgroupHidden: EventEmitter;
     get parentNestedSelect(): HTMLWmNestedSelectElement;
     get isDisabled(): boolean;
     isExpandedChanged(): void;
+    /**
+     * @description Programmatically deselects all options in this group by emitting
+     * `wmOptgroupAllDeselected`.
+     * @returns `Promise<void>`
+     */
     emitDeselection(): Promise<void>;
+    /**
+     * @internal
+     * @description Notifies the internal option list that child options have changed so it can
+     * refresh clone state — not for application use.
+     */
     handleChildChange(): Promise<void>;
     handleOptionKeyLeft(): void;
     componentWillLoad(): void;

package/dist/types/components/selects/wm-option/wm-option.d.ts

@@ -1,25 +1,142 @@
 import { EventEmitter } from "../../../stencil-public-runtime";
+/**
+ * Individual selectable item used inside wm-select, wm-nested-select (via wm-optgroup), and
+ * wm-optgroup. Renders as a listbox option with optional secondary text.
+ *
+ * @usageNotes
+ * - Text content is supplied as the element's text node (slot content). Do not nest other
+ *   elements inside wm-option.
+ * - Set the `selected` attribute/prop to pre-select an option on load.
+ * - In single-select mode, exactly one wm-option should be pre-selected (typically a
+ *   placeholder). In multi-select mode, zero or more options may be pre-selected.
+ * - The `value` prop is a pass-through convenience for application code to attach an
+ *   identifier; the component itself never reads or mutates it.
+ *
+ * @example {html} Basic option usage
+ * <wm-select label="Status">
+ *   <wm-option selected>Select a status</wm-option>
+ *   <wm-option value="active">Active</wm-option>
+ *   <wm-option value="inactive">Inactive</wm-option>
+ * </wm-select>
+ *
+ * @example {react} Basic option usage
+ * <WmSelect label="Status">
+ *   <WmOption selected={true}>Select a status</WmOption>
+ *   <WmOption value="active">Active</WmOption>
+ *   <WmOption value="inactive">Inactive</WmOption>
+ * </WmSelect>
+ *
+ * @example {html} Option with subinfo
+ * <wm-select label="User" multiple>
+ *   <wm-option subinfo="Biology dept">Alice</wm-option>
+ *   <wm-option subinfo="Chemistry dept">Bob</wm-option>
+ * </wm-select>
+ *
+ * @example {react} Option with subinfo
+ * <WmSelect label="User" multiple={true}>
+ *   <WmOption subinfo="Biology dept">Alice</WmOption>
+ *   <WmOption subinfo="Chemistry dept">Bob</WmOption>
+ * </WmSelect>
+ */
 export declare class Option {
     el: HTMLElement;
+    /**
+     * @description Application-defined identifier for this option. The component never reads
+     * or modifies this value — it is purely a pass-through for application code to attach an ID
+     * or key.
+     */
     value?: string | null;
+    /**
+     * @description Secondary text displayed beneath the option label.
+     */
     subinfo?: string;
+    /**
+     * @description Prevents the option from being selected.
+     * @default false
+     */
     disabled: boolean;
+    /**
+     * @description Marks this option as currently selected.
+     * @default false
+     */
     selected: boolean;
+    /**
+     * @internal
+     * @description Programmatically focuses this option element when set to true. Managed by
+     * the parent priv-option-list — not for application use.
+     */
     focused: boolean;
+    /**
+     * @description Fires when this option is selected by the user.
+     * @eventDetails `HTMLWmOptionElement` — the option element that was selected.
+     */
     wmOptionSelected: EventEmitter<HTMLWmOptionElement>;
+    /**
+     * @description Fires when this option is deselected by the user (multiselect mode only).
+     * @eventDetails `HTMLWmOptionElement` — the option element that was deselected.
+     */
     wmOptionDeselected: EventEmitter<HTMLWmOptionElement>;
+    /**
+     * @internal
+     * @description Fires when a clone option is clicked so the parent can relay the selection
+     * to the original wm-option — not for application use.
+     */
     intCloneClicked: EventEmitter<HTMLWmOptionElement>;
+    /**
+     * @internal
+     * @description Signals Arrow Up keydown to the parent option list for focus management —
+     * not for application use.
+     */
     wmKeyUpPressed: EventEmitter<HTMLWmOptionElement>;
+    /**
+     * @internal
+     * @description Signals Arrow Down keydown to the parent option list for focus management —
+     * not for application use.
+     */
     wmKeyDownPressed: EventEmitter<HTMLWmOptionElement>;
+    /**
+     * @internal
+     * @description Signals Arrow Left keydown to the parent wm-nested-select to navigate back
+     * to the group list — not for application use.
+     */
     wmKeyLeftPressed: EventEmitter;
+    /**
+     * @internal
+     * @description Signals Escape keydown to close the parent dropdown — not for application use.
+     */
     wmEscKeyPressed: EventEmitter<HTMLWmOptionElement>;
+    /**
+     * @internal
+     * @description Signals Home keydown to the parent option list to jump to the first option —
+     * not for application use.
+     */
     wmHomeKeyPressed: EventEmitter<HTMLWmOptionElement>;
+    /**
+     * @internal
+     * @description Signals End keydown to the parent option list to jump to the last option —
+     * not for application use.
+     */
     wmEndKeyPressed: EventEmitter<HTMLWmOptionElement>;
+    /**
+     * @internal
+     * @description Signals Enter keydown for single-select close-on-confirm — not for
+     * application use.
+     */
     wmEnterKeyPressed: EventEmitter<HTMLWmOptionElement>;
+    /**
+     * @internal
+     * @description Signals a printable-character keydown to the parent option list for
+     * jump-to-match navigation — not for application use.
+     */
     wmLetterPressed: EventEmitter<{
         optionEl: HTMLElement;
         letter: string;
     }>;
+    /**
+     * @internal
+     * @description Fires on blur so the parent can determine whether focus left the dropdown
+     * entirely — not for application use.
+     */
     wmOptionBlurred: EventEmitter<{
         relatedTarget: EventTarget | null;
     }>;