@watermarkinsights/ripple 0.0.1 → 0.1.0-alpha.1

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

@@ -1,55 +1,236 @@
 import { EventEmitter } from "../../../stencil-public-runtime";
+/**
+ * Dropdown list of options that allows single or multi-select. Functionally similar to the
+ * native HTML `<select>` element but with Ripple styling and richer features including
+ * multiselect, search filtering, and a Select All control. Composed of a parent wm-select
+ * element and wm-option children.
+ *
+ * @category Basic Controls
+ *
+ * @keyboardInteraction
+ * - **Closed button**: Space / Enter / Arrow Down opens the dropdown and focuses the first
+ *   option; Arrow Up opens and focuses the last option.
+ * - **Open dropdown**: Arrow Up / Down navigate options; Home / End jump to first / last;
+ *   typing a letter jumps to the first matching option.
+ * - **Single-select**: Enter / Space / click selects and closes.
+ * - **Multi-select**: Enter / Space / click toggles selection; Tab or Escape closes.
+ * - **Shift+Tab** (from options): Closes and returns focus to the trigger button.
+ *
+ * @accessibility
+ * - `label` is required even when `label-position` is `"none"` — it is used as the dropdown's
+ *   ARIA accessible name.
+ * - The dropdown renders with `role="listbox"`. Each wm-option renders with `role="option"`.
+ * - `required-field` renders a visible asterisk; the ARIA required constraint is communicated
+ *   via the label rather than `aria-required` because the listbox is in a sub-component.
+ * - Validation errors are announced via an `aria-live` region when `error-message` changes.
+ *
+ * @usageNotes
+ * - Single-select: has no `placeholder` prop — a selection must always be present, and the
+ *   component warns in the console if no option is initially selected. Since there's no way
+ *   to distinguish "the user selected the first option" from "no selection was made," use a
+ *   null-value first option to represent the unselected state and keep the component
+ *   revertible to "no option chosen." That option must not be disabled, and for
+ *   accessibility/consistency its label should be limited to "None", "Select an option", or
+ *   "--".
+ * - Multi-select: all options deselected on load is valid; use `placeholder` for that state.
+ * - `search` is best with 50 or fewer options — it filters by visible label text only.
+ * - `select-all` requires `multiple` to be set.
+ * - 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-select). `event.detail` is the `HTMLWmOptionElement`; read `.value` or
+ *   `.textContent` to get the selected value.
+ *
+ * @example {html} Single-select
+ * <wm-select label="Program">
+ *   <wm-option selected>Select a program</wm-option>
+ *   <wm-option>Biology</wm-option>
+ *   <wm-option>English</wm-option>
+ * </wm-select>
+ *
+ * @example {react} Single-select
+ * const [program, setProgram] = useState('');
+ *
+ * // event.detail is the selected HTMLWmOptionElement
+ * const handleSelect = (event) => {
+ *   setProgram(event.detail.value ?? event.detail.textContent);
+ * };
+ *
+ * <WmSelect label="Program" onWmOptionSelected={handleSelect}>
+ *   <WmOption selected>Select a program</WmOption>
+ *   <WmOption value="bio">Biology</WmOption>
+ *   <WmOption value="eng">English</WmOption>
+ * </WmSelect>
+ *
+ * @example {html} Multi-select with search and Select All
+ * <wm-select label="Programs" multiple search select-all
+ *   placeholder="Select programs">
+ *   <wm-option value="bio">Biology</wm-option>
+ *   <wm-option value="eng">English</wm-option>
+ * </wm-select>
+ *
+ * @example {react} Multi-select with search and 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));
+ * };
+ *
+ * <WmSelect
+ *   label="Programs"
+ *   multiple={true}
+ *   search={true}
+ *   selectAll={true}
+ *   placeholder="Select programs"
+ *   onWmOptionSelected={handleSelect}
+ *   onWmOptionDeselected={handleDeselect}
+ * >
+ *   <WmOption value="bio">Biology</WmOption>
+ *   <WmOption value="eng">English</WmOption>
+ * </WmSelect>
+ *
+ */
 export declare class Select {
     el: HTMLWmSelectElement;
+    /**
+     * @description Disables the entire select component, preventing all interaction.
+     * @default false
+     */
     disabled: boolean;
+    /**
+     * @description Overrides the maximum height of the options list. Accepts any valid CSS
+     * length value (e.g. `"20rem"`, `"300px"`).
+     * @default "200px"
+     */
     maxHeight: string;
+    /**
+     * @description Accessible label for the dropdown. Required even when `label-position` is
+     * `"none"` — used as the ARIA accessible name.
+     * @required
+     */
     label?: string;
+    /**
+     * @description Position of the label relative to the dropdown button. `"none"` hides the
+     * label visually but keeps it accessible via ARIA.
+     * @default "top"
+     */
     labelPosition: "top" | "left" | "none";
+    /**
+     * @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 beneath the
+     * trigger button. Use for form validation feedback.
+     */
     errorMessage?: string;
+    /**
+     * @description Enables multiselect mode, allowing more than one option to be selected
+     * simultaneously.
+     * @default false
+     */
     multiple: boolean;
+    /**
+     * @description Adds a search input inside the dropdown that filters visible options by label
+     * text. Compatible with both single and multiselect modes. Best with 50 or fewer options.
+     * @default false
+     */
     search: boolean;
+    /**
+     * @description Adds a "Select All" / "Deselect All" toggle at the top of the dropdown.
+     * Has no effect unless `multiple` is also set.
+     * @default false
+     */
     selectAll: boolean;
+    /**
+     * @description Text displayed in the trigger button in multiselect mode when no options are
+     * selected. Not applicable in single-select mode — use a null-value first option instead.
+     */
     placeholder: string;
+    /**
+     * @description Placeholder text displayed inside the search input when `search` is enabled.
+     */
     searchPlaceholder: string;
+    /**
+     * @description Text displayed in the trigger button in multiselect mode when every option
+     * is selected.
+     */
     allSelectedMessage: string;
+    /**
+     * @description Informational hint text rendered beneath the dropdown button. Use for
+     * supporting instructions or constraints.
+     */
+    info?: string;
     isExpanded: boolean;
+    isHidden: boolean;
+    openUp: boolean;
     announcement: string;
+    /**
+     * @description Fires after the component has finished loading and is ready for interaction.
+     * Use this to read initial selection state or call methods.
+     */
     wmSelectDidLoad: EventEmitter<void>;
+    /**
+     * @description Fires when focus leaves the component entirely (not when moving between
+     * the trigger and an option within the dropdown).
+     */
     wmSelectBlurred: EventEmitter<void>;
+    /**
+     * @description Fires when the user clicks "Select All" in multiselect mode and all options
+     * become selected.
+     */
     wmSelectAllSelected: EventEmitter;
+    /**
+     * @description Fires when the user clicks "Deselect All" in multiselect mode and all
+     * options become deselected.
+     */
     wmSelectAllDeselected: EventEmitter;
     private buttonEl;
-    private labelEl;
     private dropdownEl;
     private optionListEl;
     private liveRegionEl;
     private measurementAreaEl;
-    private openUp;
+    private scrollableParents;
+    private elToFocus?;
+    private returnFocus;
+    private initialHtmlOverflowY?;
     get childOptions(): HTMLWmOptionElement[];
     get isDisabled(): boolean;
-    private overflowCount;
-    get selectedOptions(): HTMLWmOptionElement[];
+    private hasAnchor;
+    private overflowCount?;
+    private buttonText?;
     private displayedOptions;
+    get displayText(): string;
+    get selectedOptions(): HTMLWmOptionElement[];
     get allSelected(): boolean;
     handleOptionSelection(): void;
     handleChildEnter(): void;
-    closePopupOnEscape(): void;
-    handleOptionBlur(ev: CustomEvent): void;
-    handleClick(ev: MouseEvent): void;
-    handleButtonBlur(ev: FocusEvent): void;
+    closeDropdownOnEscape(): void;
+    handleToggle(ev: ToggleEvent): void;
+    dropdownPosition(): void;
+    onOpen(): void;
+    onClose(): void;
     handleKey(ev: KeyboardEvent): void;
+    debouncedReposition: (this: any) => void;
+    handleResize(): void;
+    handleScroll(): void;
     componentWillLoad(): void;
     handleChildChange(): void;
     componentDidLoad(): void;
-    open(optionToSelect?: "next" | "previous"): void;
-    close(returnFocus?: boolean): void;
     announceError(): void;
     handleDisabledChange(): void;
     handleComponentBlur(ev: FocusEvent): void;
-    setButtonText(): void;
+    handleLabelMouseEnter(ev: MouseEvent): void;
     announce(message: string): void;
-    renderButtonText(): any;
+    handleOverflow(): void;
+    setButtonText(): string | null;
     renderOverflowCount(): any;
     render(): any;
 }

package/dist/types/components/wm-action-menu/wm-action-menu.d.ts

@@ -1,24 +1,223 @@
 import { EventEmitter } from "../../stencil-public-runtime";
+/**
+ * Dropdown interface that displays a list of action items. When closed it shows a text
+ * button, icon button, or selector box depending on action-menu-type. Selecting an item
+ * executes an action and closes the menu. Composed of a parent wm-action-menu element and
+ * one or more wm-menuitem children.
+ *
+ * @category Basic Controls
+ *
+ * @slot - One or more wm-menuitem elements.
+ *
+ * @keyboardInteraction
+ * - **Trigger button (closed)**: Down Arrow / Space / Enter opens the menu and focuses the first item; Up Arrow opens and focuses the last item.
+ * - **Open menu**: Up/Down Arrow navigates items (wraps around); Home/End jumps to first/last; Enter activates the focused item and closes the menu; Escape closes the menu and returns focus to the trigger; Tab closes the menu; typing a character focuses the next item starting with that letter.
+ *
+ * @accessibility
+ * - For `icon` menus, `tooltip` is required and serves as the accessible name announced by screen readers.
+ * - When multiple action menus share identical tooltips or button text, use `label-for-identical-buttons` to give each a unique `aria-label`.
+ * - Focus returns automatically to the trigger button after an item is activated, unless the action removes the trigger from the DOM — in that case, manage focus explicitly in your action handler.
+ *
+ * @usageNotes
+ * - The default type is `icon` (three-dot "more options" button). Use `text` for a labelled trigger, `selector` or `selector-primary` for a select-box appearance.
+ * - `button-text` is required when `action-menu-type` is `text`, `selector`, or `selector-primary`.
+ * - `tooltip` is required when `action-menu-type` is `icon`.
+ * - `icon` is optional for `text`, `selector`, and `selector-primary` types, rendered alongside `button-text`. For `icon` type, `icon` overrides the default "more options" icon.
+ *
+ * @example {html} Icon action menu (default)
+ * <wm-action-menu tooltip="More options">
+ *   <wm-menuitem onclick="editRecord()">Edit</wm-menuitem>
+ *   <wm-menuitem onclick="deleteRecord()">Delete</wm-menuitem>
+ * </wm-action-menu>
+ *
+ * @example {react} Icon action menu
+ * <WmActionMenu tooltip="More options">
+ *   <WmMenuitem onClick={editRecord}>Edit</WmMenuitem>
+ *   <WmMenuitem onClick={deleteRecord}>Delete</WmMenuitem>
+ * </WmActionMenu>
+ *
+ * @example {html} Icon action menu with a custom icon
+ * <wm-action-menu icon="#filter" tooltip="Filter options">
+ *   <wm-menuitem>All</wm-menuitem>
+ *   <wm-menuitem>Unread</wm-menuitem>
+ * </wm-action-menu>
+ *
+ * @example {react} Icon action menu with a custom icon
+ * <WmActionMenu icon="#filter" tooltip="Filter options">
+ *   <WmMenuitem>All</WmMenuitem>
+ *   <WmMenuitem>Unread</WmMenuitem>
+ * </WmActionMenu>
+ *
+ * @example {html} Icon action menu with a rotated icon — reuse directional icons with icon-rotate.
+ * <wm-action-menu icon="#back" icon-rotate="180" tooltip="Forward options">
+ *   <wm-menuitem>Skip</wm-menuitem>
+ *   <wm-menuitem>Skip all</wm-menuitem>
+ * </wm-action-menu>
+ *
+ * @example {react} Icon action menu with a rotated icon
+ * <WmActionMenu icon="#back" iconRotate={180} tooltip="Forward options">
+ *   <WmMenuitem>Skip</WmMenuitem>
+ *   <WmMenuitem>Skip all</WmMenuitem>
+ * </WmActionMenu>
+ *
+ * @example {html} Text action menu
+ * <wm-action-menu action-menu-type="text" button-text="Actions">
+ *   <wm-menuitem onclick="editRecord()">Edit</wm-menuitem>
+ *   <wm-menuitem onclick="deleteRecord()">Delete</wm-menuitem>
+ * </wm-action-menu>
+ *
+ * @example {react} Text action menu
+ * <WmActionMenu actionMenuType="text" buttonText="Actions">
+ *   <WmMenuitem onClick={editRecord}>Edit</WmMenuitem>
+ *   <WmMenuitem onClick={deleteRecord}>Delete</WmMenuitem>
+ * </WmActionMenu>
+ *
+ * @example {html} Text action menu with an icon
+ * <wm-action-menu action-menu-type="text" button-text="Actions" icon="#edit">
+ *   <wm-menuitem>Edit</wm-menuitem>
+ *   <wm-menuitem>Delete</wm-menuitem>
+ * </wm-action-menu>
+ *
+ * @example {react} Text action menu with an icon
+ * <WmActionMenu actionMenuType="text" buttonText="Actions" icon="#edit">
+ *   <WmMenuitem>Edit</WmMenuitem>
+ *   <WmMenuitem>Delete</WmMenuitem>
+ * </WmActionMenu>
+ *
+ * @example {html} Selector action menu
+ * <wm-action-menu action-menu-type="selector" button-text="Sort by">
+ *   <wm-menuitem onclick="sortBy('name')">Name</wm-menuitem>
+ *   <wm-menuitem onclick="sortBy('date')">Date</wm-menuitem>
+ * </wm-action-menu>
+ *
+ * @example {react} Selector action menu
+ * <WmActionMenu actionMenuType="selector" buttonText="Sort by">
+ *   <WmMenuitem onClick={() => sortBy("name")}>Name</WmMenuitem>
+ *   <WmMenuitem onClick={() => sortBy("date")}>Date</WmMenuitem>
+ * </WmActionMenu>
+ *
+ * @example {html} Menu items with icons
+ * <wm-action-menu tooltip="File actions">
+ *   <wm-menuitem icon="#edit" onclick="editFile()">Edit</wm-menuitem>
+ *   <wm-menuitem icon="#delete" onclick="deleteFile()">Delete</wm-menuitem>
+ * </wm-action-menu>
+ *
+ * @example {react} Menu items with icons
+ * <WmActionMenu tooltip="File actions">
+ *   <WmMenuitem icon="#edit" onClick={editFile}>Edit</WmMenuitem>
+ *   <WmMenuitem icon="#delete" onClick={deleteFile}>Delete</WmMenuitem>
+ * </WmActionMenu>
+ *
+ * @example {html} Identical menus — disambiguate for screen readers with label-for-identical-buttons
+ * <wm-action-menu tooltip="Actions" label-for-identical-buttons="Actions for Introduction to Biology">
+ *   <wm-menuitem onclick="editCourse('bio-101')">Edit</wm-menuitem>
+ * </wm-action-menu>
+ * <wm-action-menu tooltip="Actions" label-for-identical-buttons="Actions for Advanced Chemistry">
+ *   <wm-menuitem onclick="editCourse('chem-301')">Edit</wm-menuitem>
+ * </wm-action-menu>
+ *
+ * @example {react} Identical menus
+ * <WmActionMenu tooltip="Actions" labelForIdenticalButtons="Actions for Introduction to Biology">
+ *   <WmMenuitem onClick={() => editCourse("bio-101")}>Edit</WmMenuitem>
+ * </WmActionMenu>
+ * <WmActionMenu tooltip="Actions" labelForIdenticalButtons="Actions for Advanced Chemistry">
+ *   <WmMenuitem onClick={() => editCourse("chem-301")}>Edit</WmMenuitem>
+ * </WmActionMenu>
+ *
+ * @requiredSetup
+ * - Wire each item's action: attach an `onclick` handler to each wm-menuitem.
+ * - Slot one wm-menuitem per action as a child.
+ *
+ */
 export declare class ActionMenu {
     el: HTMLWmActionMenuElement;
-    private wmButtonEl;
-    private itemsEl?;
+    private menubtnEl;
+    private dropdownEl;
     private openUp;
+    private initialHtmlOverflowY?;
+    private scrollableParents;
     get horizontalPosition(): "right" | "left";
     get childItems(): HTMLWmMenuitemElement[];
     get internalButtonType(): string;
+    get resolvedIcon(): string | undefined;
     isExpanded: boolean;
+    isTabbing: boolean;
+    isHidden: boolean;
+    private hasAnchor;
+    private elToFocus?;
+    /**
+     * @description Position of the tooltip relative to the trigger button. Repositions automatically when there is insufficient space at the specified position.
+     * @default "left"
+     */
     tooltipPosition?: "top" | "bottom" | "left" | "right" | "bottom-left" | "bottom-right" | "top-right" | "top-left";
+    /**
+     * @description Visual style of the trigger button. `'icon'` shows an icon-only button (requires `tooltip`). `'text'` shows a labelled button (requires `button-text`). `'selector'` shows a selector box that visually mimics a select control (requires `button-text`). `'selector-primary'` is a primary-styled variant of selector.
+     * @default "icon"
+     */
     actionMenuType: "icon" | "text" | "selector" | "selector-primary";
+    /**
+     * @description Label displayed on the trigger button.
+     * @conditionallyRequired when action-menu-type is 'text', 'selector', or 'selector-primary'
+     */
     buttonText?: string;
+    /**
+     * @description Icon to display alongside `button-text` for `text`, `selector`, and `selector-primary`
+     * types, or in place of the default "more options" icon for the `icon` type. Formats: `'#icon-name'`
+     * for a Ripple icon (e.g. `'#edit'`), or `'/path/to/file.svg#symbol-id'` for a local SVG sprite symbol.
+     * @default "#more-options" when action-menu-type is 'icon'; unset otherwise
+     */
+    icon?: string;
+    /**
+     * @description Change size of the icon to fine tune the visual rendering if it appears too large or small. Not
+     * intended for general sizing. Accepts any valid CSS size value, e.g. '22px' or '1.3rem'.
+     */
+    iconSize?: string;
+    /**
+     * @description Rotates the icon by the given number of degrees. For use with the icon property.
+     */
+    iconRotate?: number;
+    /**
+     * @description Flips the icon along the specified axis. For use with the icon property.
+     */
+    iconFlip?: "horizontal" | "vertical";
+    /**
+     * @description Disables the entire menu, preventing the trigger from being activated.
+     * @default false
+     */
     disabled: boolean;
+    /**
+     * @description Tooltip text shown on hover. For `icon` menus, also serves as the accessible name announced by screen readers.
+     * @conditionallyRequired when action-menu-type is 'icon'
+     */
     tooltip?: string;
+    /**
+     * @description Use only when multiple action menus on the same page share identical tooltips or button text. Set this to a more descriptive label for screen readers; the visible label stays unchanged. Sets aria-label to this value.
+     */
     labelForIdenticalButtons?: string;
+    /**
+     * @description Applies dark styling to `selector` and `selector-primary` variants. Has no effect on `icon` or `text` types.
+     * @default false
+     */
     darkMode?: boolean;
+    /**
+     * @description Maximum width of the dropdown. Accepts any valid CSS width value (e.g. "300px", "20rem", "50%"). The dropdown may still render narrower to fit its content or the space available.
+     * @default "25.875rem"
+     */
+    maxWidth: string;
+    /**
+     * @description Fires when the component finishes loading and child wm-menuitem elements are ready.
+     */
     wmActionMenuLoaded: EventEmitter;
+    /**
+     * @description Fires when the component finishes loading.
+     * @deprecated Use wmActionMenuLoaded instead.
+     */
     menuLoaded: EventEmitter;
     private keysSoFar;
     private searchIndex;
+    handleTabbingOn(): void;
+    handleTabbingOff(): void;
+    handleWindowScroll(): void;
     handleClickedItem(): void;
     handleKeyUp(ev: CustomEvent): void;
     handleKeyDown(ev: CustomEvent): void;
@@ -29,15 +228,21 @@ export declare class ActionMenu {
     handleKey(ev: KeyboardEvent): void;
     handleMenuitemBlur(ev: CustomEvent): void;
     handleButtonBlur(ev: FocusEvent): void;
+    handleScroll(): void;
+    componentWillLoad(): void;
     componentDidLoad(): void;
+    disconnectedCallback(): void;
     moveUp(el: HTMLWmMenuitemElement): void;
     moveDown(el: HTMLWmMenuitemElement): void;
     open(): void;
     close(returnFocus?: boolean): void;
+    positionDropdown(): void;
+    handleToggle(ev: ToggleEvent): void;
     focusFirstItem(): void;
     focusLastItem(): void;
     findAndFocusItem(ev: CustomEvent): void;
     debouncedClearKeysSoFar: (this: any) => void;
     findMatchInRange(list: HTMLWmMenuitemElement[], startIndex: number, endIndex: number): HTMLWmMenuitemElement | null;
+    renderIcon(): any;
     render(): any;
 }