@watermarkinsights/ripple 0.0.1 → 0.1.0-alpha.1

package/dist/types/components/wm-tag-input/wm-tag-input.d.ts

@@ -1,4 +1,121 @@
 import { EventEmitter } from "../../stencil-public-runtime";
+/**
+ * Input for selecting or creating a list of tags. Two variants: `'dropdown'` (options in a
+ * filterable list, supports creating new tags) and `'table'` (options in a filterable
+ * multi-column table). Options are defined as wm-tag-option children. Selected options appear
+ * as removable tags above the search field.
+ *
+ * @category Form Inputs
+ *
+ * @slot - One or more wm-tag-option children.
+ *
+ * @keyboardInteraction
+ * **Tag area (when tags are present):**
+ * - **Arrow Left / Arrow Right**: Cycle focus between selected tags.
+ * - **Backspace / Delete**: Remove the focused tag.
+ *
+ * **Search field:**
+ * - **Arrow Down / Arrow Up**: Open the dropdown or navigate within it.
+ * - **Enter**: Add a new tag from typed value (dropdown, `add-new` enabled) or select the
+ *   focused option.
+ * - **Comma**: Add a new tag immediately (dropdown, `add-new` enabled).
+ * - **Escape**: Close the dropdown.
+ * - **Backspace** (empty field): Move focus to the last selected tag.
+ *
+ * @accessibility
+ * - `label` is the accessible name for the search input and dropdown/table; required even
+ *   when `label-position="none"`.
+ * - An `aria-live` region announces tag additions, removals, result counts, and errors.
+ * - Two tab stops: the tag area (when tags are present) and the search field.
+ *
+ * @usageNotes
+ * - `label` is required and must always be provided.
+ * - `col-headers` is required for the `table` variant; `label-position="left"` is not
+ *   supported in the `table` variant.
+ * - `max-tags` displays a counter but does not prevent selection beyond the limit — enforce
+ *   the limit in your `wmTagOptionSelected` or `wmTagInputTagAdded` handler.
+ * - The `add-new` feature (dropdown only) detects and announces duplicate entries.
+ * - In React, `wmTagOptionSelected` and `wmTagOptionDeselected` bubble from `wm-tag-option`
+ *   to `wm-tag-input` for the dropdown variant (listen on `WmTagInput`). For the table
+ *   variant, put the handlers directly on each `WmTagOption` instead. In both cases, you
+ *   must set `event.target.selected = true/false` imperatively — the component does not do
+ *   this automatically.
+ * - For the `add-new` dropdown variant, create and append a new `wm-tag-option` element with
+ *   `selected = true` in the `wmTagInputTagAdded` handler — the component does not create
+ *   the option element automatically.
+ *
+ * @example {html} Dropdown with add-new
+ * <wm-tag-input label="Skills" add-new="true">
+ *   <wm-tag-option>JavaScript</wm-tag-option>
+ *   <wm-tag-option>TypeScript</wm-tag-option>
+ *   <wm-tag-option>React</wm-tag-option>
+ * </wm-tag-input>
+ *
+ * @example {react} Dropdown with add-new
+ * // wmTagOptionSelected/Deselected bubble to WmTagInput for the dropdown variant.
+ * // You must set event.target.selected imperatively in each handler.
+ * // wmTagInputTagAdded fires when a new tag is created; event.detail is the tag string.
+ * // You must create and append a wm-tag-option DOM element with selected=true.
+ * const handleOptionSelected = (event) => {
+ *   event.target.selected = true;
+ *   setTags((prev) => [...prev, event.target.textContent.trim()]);
+ * };
+ * const handleOptionDeselected = (event) => {
+ *   const isUserAdded = event.target.getAttribute('user-added');
+ *   isUserAdded ? event.target.remove() : (event.target.selected = false);
+ *   setTags((prev) => prev.filter((t) => t !== event.target.textContent.trim()));
+ * };
+ * const handleTagAdded = (event) => {
+ *   const taginput = event.currentTarget;
+ *   const newTagName = event.detail;
+ *   const existingNames = Array.from(taginput.querySelectorAll('wm-tag-option'))
+ *     .map((o) => o.textContent.toLowerCase().trim());
+ *   if (!existingNames.includes(newTagName.toLowerCase().trim())) {
+ *     const newOption = document.createElement('wm-tag-option');
+ *     newOption.textContent = newTagName;
+ *     newOption.id = 'tag' + Math.random().toString(36).substr(2, 6);
+ *     newOption.selected = true;
+ *     newOption.setAttribute('user-added', 'true');
+ *     taginput.appendChild(newOption);
+ *     setTags((prev) => [...prev, newTagName]);
+ *   }
+ * };
+ *
+ * <WmTagInput label="Skills" addNew={true}
+ *   onWmTagOptionSelected={handleOptionSelected}
+ *   onWmTagOptionDeselected={handleOptionDeselected}
+ *   onWmTagInputTagAdded={handleTagAdded}>
+ *   <WmTagOption>JavaScript</WmTagOption>
+ *   <WmTagOption>TypeScript</WmTagOption>
+ *   <WmTagOption>React</WmTagOption>
+ * </WmTagInput>
+ *
+ * @example {html} Table variant
+ * <wm-tag-input label="Assign people" tag-input-type="table" col-headers="Name,Department">
+ *   <wm-tag-option col1="Smith, John" col2="Engineering"></wm-tag-option>
+ *   <wm-tag-option col1="Doe, Jane" col2="Design"></wm-tag-option>
+ * </wm-tag-input>
+ *
+ * @example {react} Table variant
+ * // For the table variant, put handlers on each WmTagOption rather than on WmTagInput.
+ * // event.target.col1 is the first column value, used as the tag label.
+ * const makeHandlers = (col1Value) => ({
+ *   onWmTagOptionSelected: (event) => {
+ *     event.target.selected = true;
+ *     setSelected((prev) => [...prev, col1Value]);
+ *   },
+ *   onWmTagOptionDeselected: (event) => {
+ *     event.target.selected = false;
+ *     setSelected((prev) => prev.filter((p) => p !== col1Value));
+ *   },
+ * });
+ *
+ * <WmTagInput label="Assign people" tagInputType="table" colHeaders="Name,Department">
+ *   <WmTagOption col1="Smith, John" col2="Engineering" {...makeHandlers('Smith, John')} />
+ *   <WmTagOption col1="Doe, Jane" col2="Design" {...makeHandlers('Doe, Jane')} />
+ * </WmTagInput>
+ *
+ */
 export declare class TagInput {
     el: HTMLWmTagInputElement;
     private inputEl;
@@ -7,19 +124,81 @@ export declare class TagInput {
     private fieldWrapperEl;
     private dropdownEl?;
     private addNewButton?;
+    /**
+     * @description Accessible name for the search input and dropdown/table. Required even when
+     * `label-position="none"`.
+     * @required
+     */
     label: string;
+    /**
+     * @description Puts the component in an error state and displays this message below the
+     * field.
+     */
     errorMessage?: string;
+    /**
+     * @description Hint text displayed below the component.
+     */
     info?: string;
+    /**
+     * @description Controls label placement. `'none'` hides the label visually but keeps it
+     * accessible. `'left'` is not supported in the `table` variant.
+     * @default "top"
+     */
     labelPosition: "top" | "left" | "none";
+    /**
+     * @description Maximum number of tags allowed. Displays a "Tags added: x/y" counter but
+     * does not prevent selection beyond the limit — enforce the limit in your
+     * `wmTagOptionSelected` or `wmTagInputTagAdded` handler.
+     */
     maxTags?: number;
+    /**
+     * @description Placeholder text in the search field. Defaults to a generated string based
+     * on `add-new` and available options.
+     */
     placeholder?: string;
+    /**
+     * @description Displays a required-field asterisk next to the label.
+     * @default false
+     */
     requiredField: boolean;
+    /**
+     * @description Selects the component variant. `'dropdown'` shows a filterable list;
+     * `'table'` shows a filterable multi-column table.
+     * @default "dropdown"
+     */
     tagInputType: "dropdown" | "table";
+    /**
+     * @description Overrides the default instructional help text shown at the top of the
+     * dropdown (dropdown variant) or below the input when `max-tags` is set (table variant).
+     */
     helpText?: string;
+    /**
+     * @description Dropdown variant only. When true, the user can type a new value and add it
+     * as a tag by pressing Enter or comma.
+     * @default true
+     */
     addNew: boolean;
+    /**
+     * @description Dropdown variant only. Maximum character limit enforced on the search field.
+     * @default 50
+     */
     characterLimit: number;
+    /**
+     * @description Table variant only. Comma-separated list of column header labels. The number
+     * of headers determines the number of columns.
+     * @conditionallyRequired Required when `tag-input-type="table"`.
+     */
     colHeaders: string;
+    /**
+     * @description Table variant only. Comma-separated column widths. Blank values fill
+     * remaining space.
+     */
     colWidths?: string;
+    /**
+     * @description Table variant only. Comma-separated text-wrapping rules per column — `'wrap'`
+     * or `'trunc'` (truncate with tooltip).
+     * @default "wrap" for all columns
+     */
     colWrap?: string;
     addNewHelpText: string;
     selectionHelpText: string;
@@ -28,9 +207,15 @@ export declare class TagInput {
     tagsAddedMessage: string;
     noResultsMessage: string;
     addNewTagMessage(newTagName: string): string;
+    /**
+     * @description Fires when the user adds a new tag by typing and pressing Enter or comma
+     * (dropdown variant, `add-new` enabled). The event detail is the text string of the new
+     * tag. Not fired when selecting an existing wm-tag-option — listen to `wmTagOptionSelected`
+     * on the wm-tag-option for that.
+     * @eventDetails string — the text of the newly created tag.
+     */
     wmTagInputTagAdded: EventEmitter;
     private openUp;
-    private inModal;
     isKeying: boolean;
     isExpanded: boolean;
     liveRegionMessage: string;
@@ -46,12 +231,14 @@ export declare class TagInput {
     get tooltipVisible(): boolean;
     get optionEls(): HTMLWmTagOptionElement[];
     get filteredOptionEls(): HTMLWmTagOptionElement[];
+    get filteredOptionRowEls(): (HTMLTableRowElement | HTMLLIElement)[];
     get taggedOptions(): HTMLWmTagOptionElement[];
     get _tagEls(): HTMLLIElement[];
     get focusedTag(): HTMLLIElement | undefined;
+    optionById(id: string): HTMLWmTagOptionElement | undefined;
     tagOptionFromEl(el: HTMLTableRowElement | HTMLLIElement): HTMLWmTagOptionElement | undefined;
-    tagOptionFromTag(el: HTMLLIElement): HTMLWmTagOptionElement;
-    elFromTagOption(el: HTMLWmTagOptionElement): HTMLTableRowElement | HTMLLIElement;
+    tagOptionFromTag(el: HTMLLIElement): HTMLWmTagOptionElement | undefined;
+    elFromTagOption(el: HTMLWmTagOptionElement): HTMLTableRowElement | HTMLLIElement | undefined;
     get _focusedOption(): HTMLTableRowElement | HTMLLIElement | undefined;
     get _focusedCell(): HTMLTableCellElement | undefined;
     get inputActiveDescendantId(): string | null;
@@ -64,20 +251,22 @@ export declare class TagInput {
     tagAlreadyAddedMessage(tag: string): string;
     tagLockedMessage(tag: string): string;
     isElOrChild(el: HTMLElement): boolean;
+    assignOptionIds(): void;
     componentWillLoad(): void;
     componentDidLoad(): void;
     handleChangeAnnouncement(mutationRecord: MutationRecord): void;
     handleOptionListChange(record: MutationRecord): void;
     handleTagOptionSelected(ev: Event): void;
     handleTagOptionDeselected(ev: Event): void;
+    handleTagsListChange(): void;
     handleTagListChange(mutationRecord: MutationRecord): void;
-    componentDidRender(): void;
+    handleLayoutChange(): void;
     createPlaceholderDefault(addNew: boolean, hasOptions: boolean): string;
     handleClick(ev: MouseEvent): void;
     announceError(): void;
     handleOptionClick(ev: MouseEvent): void;
     dismissTooltip(): void;
-    debouncedUpdate: (this: any) => void;
+    debouncedLayoutChange: (this: any) => void;
     handleInputKeyDown(ev: KeyboardEvent): void;
     handleInputFocus(): void;
     handleInputChanged(ev: Event): void;
@@ -87,7 +276,10 @@ export declare class TagInput {
     handleInputBackspace(): void;
     handleTagAreaKeyDown(ev: KeyboardEvent): void;
     handleBlur(ev: FocusEvent): void;
+    handleLabelMouseEnter(ev: MouseEvent): void;
     handleTagAreaFocus(ev: FocusEvent): void;
+    handleTableFocus(): void;
+    handleTableWrapperKeyDown(ev: KeyboardEvent): void;
     focusPrevCell(): void;
     focusNextCell(): void;
     focusOption(optionToFocus: HTMLLIElement | HTMLTableRowElement): void;
@@ -103,6 +295,8 @@ export declare class TagInput {
     generateCharacterLimitWarning(charCount: number, charLimit: number): string;
     positionInput(): void;
     handleTagMouseEnter(ev: MouseEvent): void;
+    renderDropdownInput(): any;
+    renderTableInput(): any;
     renderDropdown(): any;
     renderHelpText(): string;
     renderAddNewButton(): any;

package/dist/types/components/wm-tag-input/wm-tag-option/wm-tag-option.d.ts

@@ -1,17 +1,85 @@
 import { EventEmitter } from "../../../stencil-public-runtime";
+/**
+ * Option element for wm-tag-input. Represents a selectable tag in the dropdown list or
+ * table. Always used as a direct child of wm-tag-input. For the dropdown variant, slotted
+ * text content is the tag label; for the table variant, use `col1`–`col4` props.
+ *
+ * @usageNotes
+ * - Pre-select an option on load by setting `selected`; lock it from removal by setting
+ *   `locked`.
+ * - Listen to `wmTagOptionSelected` and `wmTagOptionDeselected` to react to selection
+ *   changes.
+ *
+ * @example {html} Dropdown option
+ * <wm-tag-option>JavaScript</wm-tag-option>
+ *
+ * @example {react} Dropdown option
+ * <WmTagOption onWmTagOptionSelected={handleSelect}>JavaScript</WmTagOption>
+ *
+ * @example {html} Pre-selected option
+ * <wm-tag-option selected>TypeScript</wm-tag-option>
+ *
+ * @example {react} Table option (col1–col4)
+ * <WmTagOption col1="Smith, John" col2="Engineering" />
+ */
 export declare class TagOption {
     el: HTMLWmTagOptionElement;
+    /**
+     * @description Whether this option is currently selected (appears as a tag). Setting this
+     * on load pre-selects the option.
+     * @default false
+     */
     selected: boolean;
+    /**
+     * @description When true, the option is permanently selected and cannot be removed by the
+     * user.
+     * @default false
+     */
     locked: boolean;
+    /**
+     * @description First column value for the `table` variant. Also used as the tag label when
+     * this option is selected.
+     */
     col1?: string;
+    /**
+     * @description Second column value for the `table` variant.
+     */
     col2?: string;
+    /**
+     * @description Third column value for the `table` variant.
+     */
     col3?: string;
+    /**
+     * @description Fourth column value for the `table` variant.
+     */
     col4?: string;
+    /**
+     * @internal
+     * @description Internal signal consumed by wm-tag-input to update the tag list — not for application use.
+     */
     privTagOptionSelected: EventEmitter<void>;
+    /**
+     * @internal
+     * @description Internal signal consumed by wm-tag-input to update the tag list — not for application use.
+     */
     privTagOptionDeselected: EventEmitter<void>;
+    /**
+     * @description Fires when this option is selected as a tag.
+     */
     wmTagOptionSelected: EventEmitter;
+    /**
+     * @description Fires when this option's tag is removed.
+     */
     wmTagOptionDeselected: EventEmitter;
+    /**
+     * @description Programmatically selects this option, adding it as a tag.
+     * @returns A promise that resolves once the event has been emitted.
+     */
     emitSelectedEvent(): Promise<void>;
+    /**
+     * @description Programmatically deselects this option, removing it as a tag.
+     * @returns A promise that resolves once the event has been emitted.
+     */
     emitDeselectedEvent(): Promise<void>;
     componentWillLoad(): void;
     handleSelected(): void;

package/dist/types/components/wm-textarea/wm-textarea.d.ts

@@ -1,20 +1,118 @@
 import { EventEmitter } from "../../stencil-public-runtime";
+/**
+ * Multi-line plain-text editing control with a drag handle for vertical resizing. Shares
+ * most functionality with wm-input. Use instead of native `<textarea>` in all Watermark UI.
+ *
+ * @category Form Inputs
+ *
+ * @accessibility
+ * - `label` sets the accessible label for the textarea; required even when
+ *   `label-position="none"`.
+ * - When `character-limit` is set, a counter below the field turns red when exceeded; the
+ *   count is announced via `aria-live` when within 5 characters of the limit or exceeded.
+ * - Error messages are announced via an `aria-live` region.
+ * - `info` text is associated via `aria-describedby` and read by screen readers on focus.
+ *
+ * @usageNotes
+ * - In HTML, set the initial value via text content: `<wm-textarea>initial value</wm-textarea>`.
+ *   In React, use the `value` prop for controlled usage.
+ * - `wmTextareaValueChanged` fires on blur only when the value has changed; use the native
+ *   `input` event for per-keystroke updates.
+ * - `event.detail.value` is the current string value.
+ *
+ * @example {html} Basic textarea
+ * <wm-textarea label="Notes" placeholder="Enter notes here..."></wm-textarea>
+ *
+ * @example {react} Basic textarea
+ * // value + onWmTextareaValueChanged is the standard controlled pattern.
+ * const [notes, setNotes] = useState("");
+ *
+ * <WmTextarea
+ *   label="Notes"
+ *   placeholder="Enter notes here..."
+ *   value={notes}
+ *   onWmTextareaValueChanged={(e) => setNotes(e.detail.value)} />
+ *
+ * @example {html} With character limit
+ * <wm-textarea label="Summary" character-limit="500"></wm-textarea>
+ *
+ * @example {react} With character limit
+ * <WmTextarea label="Summary" characterLimit={500} />
+ *
+ */
 export declare class Textarea {
     el: HTMLWmTextareaElement;
     private liveRegionEl;
+    /**
+     * @description Fires on blur when the value has changed since load or the last blur. Use
+     * the native `input` event for per-keystroke updates.
+     * @eventDetails {{ value: string }} value — the current textarea value at the time of blur.
+     */
     wmTextareaValueChanged: EventEmitter<{
         value: string;
     }>;
+    /**
+     * @description Accessible label for the textarea. Required even when
+     * `label-position="none"`.
+     * @required
+     */
     label: string;
+    /**
+     * @description Controls label placement. `'none'` hides the label visually but keeps it
+     * accessible.
+     * @default "top"
+     */
     labelPosition: "top" | "left" | "none";
+    /**
+     * @description The current value typed by the user. Line breaks are represented as `\n`.
+     * To set an initial value, use the element's text content instead:
+     * `<wm-textarea>initial value</wm-textarea>`.
+     * @default ""
+     */
     value: string;
+    /**
+     * @description Disables the component, preventing all interaction.
+     * @default false
+     */
     disabled: boolean;
+    /**
+     * @description Hint text displayed below the textarea. Read by screen readers on focus via
+     * `aria-describedby`.
+     */
     info?: string;
+    /**
+     * @description Placeholder text shown inside the empty textarea.
+     * @default ""
+     */
     placeholder: string;
+    /**
+     * @description Displays a required-field asterisk next to the label.
+     * @default false
+     */
     requiredField: boolean;
+    /**
+     * @description Puts the component in an error state and displays this message below the
+     * textarea.
+     */
     errorMessage?: string;
+    /**
+     * @description Maximum number of characters allowed. Displays a live counter below the
+     * field. Does not prevent typing beyond the limit (to allow pasting and editing) but the
+     * counter turns red when exceeded. Disabled when unset.
+     */
     characterLimit?: number;
+    /**
+     * @description CSS width value for the textarea element itself, independent of the overall
+     * component width. Useful when the label or error message should extend wider than the
+     * field.
+     * @default ""
+     */
     inputWidth: string;
+    /**
+     * @description CSS height value for the initial height of the textarea. The user can resize
+     * it with the drag handle.
+     * @default "" (approximately 3 lines)
+     */
     inputHeight: string;
     announcement: string;
     private previousValue;
@@ -25,6 +123,7 @@ export declare class Textarea {
     announceError(): void;
     handleInput(ev: Event): void;
     handleBlur(): void;
+    handleLabelMouseEnter(ev: MouseEvent): void;
     announce(message: string): void;
     render(): any;
 }

package/dist/types/components/wm-timepicker/wm-timepicker.d.ts

@@ -1,5 +1,102 @@
 import { EventEmitter } from "../../stencil-public-runtime";
 import { TimeFormat12, TimeFormat24 } from "../../global/interfaces";
+/**
+ * Time input that lets users type a time or pick one from a dropdown list of 15-minute
+ * intervals. Supports 12-hour and 24-hour display and provides `reformatTime` and
+ * `isValidTime` utility methods. Use instead of native `<input type="time">`.
+ *
+ * @category Form Inputs
+ *
+ * @keyboardInteraction
+ * **Input field:**
+ * - **Arrow Down / Arrow Up**: Open the dropdown focused on the nearest time interval.
+ *
+ * **Dropdown button:**
+ * - **Enter / Space**: Open the dropdown.
+ *
+ * **Dropdown list:**
+ * - **Arrow Down / Arrow Up**: Move focus to the next/previous option; wraps at both ends.
+ * - **Home / End**: Move focus to the first/last option.
+ * - **Enter / Space**: Select the focused time and close the dropdown.
+ * - **Tab**: Close the dropdown and advance focus (without selecting).
+ * - **Escape**: Close the dropdown without selecting.
+ *
+ * @accessibility
+ * - `label` sets the accessible name on the input; required even when `label-position="none"`.
+ * - Error messages are announced via an `aria-live` region.
+ *
+ * @usageNotes
+ * - The dropdown displays 15-minute intervals (00:00–23:45) in 12-hour format; typed input
+ *   is accepted in both 12-hour and 24-hour formats.
+ * - `wmTimepickerTimeSelected` emits `{ time: string }` in 24-hour `hh:mm` format. Always
+ *   call `reformatTime("12", ...)` on the result and write it back to `value` so the input
+ *   displays the formatted string.
+ * - Use `reformatTime` and `isValidTime` via an imperative ref — they are async component
+ *   methods, not props.
+ * - When writing a curried event-handler factory, the outer function must NOT be async;
+ *   only the inner handler should be async, otherwise the factory returns a Promise instead
+ *   of a function.
+ *
+ * @example {html} Basic timepicker
+ * <wm-timepicker label="Start time"></wm-timepicker>
+ *
+ * @example {react} Basic timepicker
+ * // wmTimepickerTimeSelected emits { time } in 24hr format.
+ * // Call reformatTime and write back to value so the input displays the result.
+ * // handleInputBlur validates free-form typed input on blur using isValidTime.
+ * // NOTE: the outer factory function must NOT be async — only the inner handler should be.
+ * const startRef = useRef(null);
+ * const [startValue, setStartValue] = useState("");
+ * const [startError, setStartError] = useState("");
+ *
+ * const handleTimeSelected = (ref, setValue, setError) => async (e) => {
+ *   const time12 = await ref.current.reformatTime("12", e.detail.time);
+ *   setError("");
+ *   setValue(time12);
+ * };
+ *
+ * const handleInputBlur = (ref, value, setValue, setError) => async () => {
+ *   if (!value) return;
+ *   const valid = await ref.current.isValidTime(value);
+ *   if (valid) {
+ *     const time12 = await ref.current.reformatTime("12", value);
+ *     setError("");
+ *     setValue(time12);
+ *   } else {
+ *     setError("Please enter a valid time.");
+ *   }
+ * };
+ *
+ * <WmTimepicker
+ *   ref={startRef}
+ *   label="Start time"
+ *   value={startValue}
+ *   errorMessage={startError}
+ *   onWmTimepickerTimeSelected={handleTimeSelected(startRef, setStartValue, setStartError)}
+ *   onWmTimepickerInputBlurred={handleInputBlur(startRef, startValue, setStartValue, setStartError)}
+ * />
+ *
+ * @example {html} With pre-selected time
+ * <wm-timepicker label="Meeting time" preselected="14:30" value="2:30 PM"></wm-timepicker>
+ *
+ * @example {react} With pre-selected time
+ * // preselected (24hr) controls where the dropdown focuses on open.
+ * // value sets the initial display string in the input.
+ * const meetingRef = useRef(null);
+ * const [meetingValue, setMeetingValue] = useState("2:30 PM");
+ * const [meetingError, setMeetingError] = useState("");
+ *
+ * <WmTimepicker
+ *   ref={meetingRef}
+ *   label="Meeting time"
+ *   preselected="14:30"
+ *   value={meetingValue}
+ *   errorMessage={meetingError}
+ *   onWmTimepickerTimeSelected={handleTimeSelected(meetingRef, setMeetingValue, setMeetingError)}
+ *   onWmTimepickerInputBlurred={handleInputBlur(meetingRef, meetingValue, setMeetingValue, setMeetingError)}
+ * />
+ *
+ */
 export declare class Timepicker {
     el: HTMLWmTimepickerElement;
     private inputEl;
@@ -7,15 +104,52 @@ export declare class Timepicker {
     private tpWrapper;
     private buttonEl;
     private liveRegionEl;
+    /**
+     * @description Disables the timepicker, preventing all interaction.
+     * @default false
+     */
     disabled: boolean;
+    /**
+     * @description The time displayed in the input field. Updated as the user types. Can also
+     * be set programmatically by the application.
+     * @default ""
+     */
     value: string;
+    /**
+     * @description Puts the component in an error state and displays this message below the
+     * input.
+     */
     errorMessage?: string;
+    /**
+     * @description Accessible label for the input. Required even when `label-position="none"`.
+     * @required
+     */
     label: string;
+    /**
+     * @description Controls label placement. `'none'` hides the label visually but keeps it
+     * accessible.
+     * @default "top"
+     */
     labelPosition: "top" | "left" | "none";
+    /**
+     * @description Displays a required-field asterisk next to the label.
+     * @default false
+     */
     requiredField: boolean;
+    /**
+     * @description The time the dropdown scrolls to and focuses when opened, in 24-hour format
+     * (e.g. `'14:30'`). Falls back to parsing `value`; defaults to `'09:00'` if unparseable.
+     */
     preselected?: string;
     isExpanded: boolean;
+    /**
+     * @description Fires when the input field loses focus.
+     */
     wmTimepickerInputBlurred: EventEmitter;
+    /**
+     * @description Fires when the user selects a time from the dropdown list.
+     * @eventDetails {{ time: string }} time — the selected time in 24-hour `hh:mm` format.
+     */
     wmTimepickerTimeSelected: EventEmitter;
     private twelveHrValid;
     private twentyFourHrValid;
@@ -26,8 +160,20 @@ export declare class Timepicker {
     get selectedOption(): HTMLLIElement;
     get optionsList(): HTMLLIElement[];
     get isDisabled(): boolean;
+    /**
+     * @description Validates a time string against both 12-hour and 24-hour formats.
+     * @param input The time string to validate.
+     * @returns `true` if the string is a valid time, `false` otherwise.
+     */
     isValidTime(input: string): Promise<boolean>;
     isValidTimeInternal(input: string): boolean;
+    /**
+     * @description Converts a time string between 12-hour and 24-hour formats.
+     * @param format The target format: `"12"` for 12-hour (e.g. `"02:30 PM"`), `"24"` for
+     *   24-hour (e.g. `"14:30"`).
+     * @param time The time string to convert. Accepts both 12-hour and 24-hour input.
+     * @returns The reformatted time string.
+     */
     reformatTime(format: "12" | "24", time: TimeFormat12 | TimeFormat24): Promise<string>;
     announce(message: string): void;
     reformatTimeInternal(format: "12" | "24", time: TimeFormat12 | TimeFormat24): string;
@@ -39,6 +185,7 @@ export declare class Timepicker {
     componentDidLoad(): void;
     handleOptionClick(time: TimeFormat24): void;
     handleInputBlur(): void;
+    handleLabelMouseEnter(ev: MouseEvent): void;
     generateTimeIntervals(): TimeFormat24[];
     splitTime(time: TimeFormat12 | TimeFormat24): [number, string, string?];
     open(itemToSelect?: "next" | "previous"): void;