@watermarkinsights/ripple 5.30.0 → 5.31.0-alpha.1

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

@@ -1,16 +1,144 @@
 import { EventEmitter } from "../../stencil-public-runtime";
+/**
+ * Search input for filtering data by query. Two variants: `'basic'` for simple text
+ * filtering, and `'find'` which adds prev/next result navigation buttons, a result count
+ * ("x of y results"), and a keyboard-accessible "jump to result" link. The component does
+ * not filter data itself — it exposes the user's query and result position via events and
+ * properties for the application to handle.
+ *
+ * @keyboardInteraction
+ * - **Tab**: Advances focus through the input and, in the `find` variant, the prev/next
+ *   buttons and the jump-to-result skip-link (visible only when tabbing with results present).
+ * - **Shift+Tab**: Moves focus backward through the same elements.
+ * - **Enter / Space**: Activates the focused prev/next buttons in the `find` variant.
+ *
+ * @accessibility
+ * - `label` sets the `aria-label` on the underlying `<input>` — it is required even when
+ *   the label text is not visually displayed.
+ * - An `aria-live` region announces the result count after each input change and after
+ *   prev/next navigation in the `find` variant.
+ * - In the `find` variant, `highlighted-id` is used as the `href` of the jump-to-result
+ *   skip-link that appears while the user is tabbing.
+ *
+ * @usageNotes
+ * - Both `label` and `placeholder` are required; the component logs a console error on load
+ *   if either is missing.
+ * - Listen to the native `input` event for per-keystroke updates; `wmSearchValueChanged`
+ *   fires on blur only.
+ * - For the `find` variant, listen to `wmSearchBrowseResults` and update `highlighted-id`
+ *   and `highlighted-name` after scrolling/highlighting the result in your data.
+ * - The component does not perform filtering — filtering logic must be implemented by the
+ *   application.
+ *
+ * @example {html} Basic search
+ * <wm-search label="Filter courses" placeholder="Search courses..."></wm-search>
+ *
+ * @example {react} Basic search
+ * // wmSearchValueChanged fires on blur only -- use a native input event listener via ref
+ * // for per-keystroke filtering. el.value reflects the current typed string.
+ * const basicRef = useRef(null);
+ * const [query, setQuery] = useState("");
+ *
+ * useEffect(() => {
+ *   const el = basicRef.current;
+ *   const handler = () => setQuery(el.value);
+ *   el.addEventListener("input", handler);
+ *   return () => el.removeEventListener("input", handler);
+ * }, []);
+ *
+ * const filtered = items.filter((c) => c.toLowerCase().includes(query.toLowerCase()));
+ *
+ * <WmSearch ref={basicRef} label="Filter courses" placeholder="Search courses..."
+ *   numResults={filtered.length} />
+ *
+ * @example {html} Search and find variant
+ * <wm-search
+ *   search-type="find"
+ *   label="Find in page"
+ *   placeholder="Find..."
+ *   num-results="5"
+ *   highlighted-id="result-1"
+ *   highlighted-name="First result">
+ * </wm-search>
+ *
+ * @example {react} Search and find variant
+ * // The find variant navigates through matched results only.
+ * // On input: filter items, set numResults, and highlight the first match.
+ * // On wmSearchBrowseResults: use e.detail.position (1-based) to index into the filtered list.
+ * // highlightedId must match the id of the corresponding DOM element.
+ * // The component does not filter -- filtering logic is entirely the application's responsibility.
+ * const findRef = useRef(null);
+ * const [highlightedId, setHighlightedId] = useState("");
+ * const [highlightedName, setHighlightedName] = useState("");
+ * const [numFindResults, setNumFindResults] = useState(0);
+ * const toId = (name) => name.toLowerCase().replace(/\s+/g, "-");
+ * const filterItems = (value) =>
+ *   !value ? [] : items.filter((c) => c.toLowerCase().includes(value.toLowerCase()));
+ *
+ * useEffect(() => {
+ *   const el = findRef.current;
+ *   const handler = () => {
+ *     const results = filterItems(el.value);
+ *     setNumFindResults(results.length);
+ *     if (results.length) { setHighlightedId(toId(results[0])); setHighlightedName(results[0]); }
+ *     else { setHighlightedId(""); setHighlightedName(""); }
+ *   };
+ *   el.addEventListener("input", handler);
+ *   return () => el.removeEventListener("input", handler);
+ * }, []);
+ *
+ * const handleBrowseResults = (e) => {
+ *   const results = filterItems(findRef.current.value);
+ *   const item = results[e.detail.position - 1];
+ *   if (item) { setHighlightedId(toId(item)); setHighlightedName(item); }
+ * };
+ *
+ * <WmSearch ref={findRef} searchType="find" label="Find result" placeholder="Find..."
+ *   numResults={numFindResults} highlightedId={highlightedId} highlightedName={highlightedName}
+ *   onWmSearchBrowseResults={handleBrowseResults} />
+ * {items.map((c) => (
+ *   <li key={c} id={toId(c)}
+ *     style={{ background: highlightedId === toId(c) ? "lightyellow" : "transparent" }}>
+ *     {c}
+ *   </li>
+ * ))}
+ *
+ * @category Form Inputs
+ */
 export declare class Search {
     el: HTMLWmSearchElement;
+    /**
+     * @description Selects the search variant. `'basic'` renders a simple text input with a
+     * result count. `'find'` adds prev/next navigation buttons and a jump-to-result skip-link.
+     * @default "basic"
+     */
     searchType: "basic" | "find";
+    /**
+     * @description Disables the input, preventing all interaction.
+     * @default false
+     */
     disabled: boolean;
     /**
-     * Props required for both variants.
+     * @description Placeholder text displayed inside the empty input.
+     * @required
      */
     placeholder: string;
+    /**
+     * @description Accessible label for the `<input>` element. Required even when not visually
+     * displayed. May match the placeholder text.
+     * @required
+     */
     label: string;
+    /**
+     * @description Number of results matching the current query. Update this prop after
+     * filtering to display "x of y results" (find variant) and announce the count to screen
+     * readers.
+     * @default 0
+     */
     numResults: number;
     /**
-     * This exposes the input's value on the host component so that the app can access it.
+     * @description The current text typed by the user. Readable by the application at any time.
+     * @default ""
      */
     value: string;
     /**
@@ -18,10 +146,17 @@ export declare class Search {
      */
     isTabbing: boolean;
     /**
-     * Prop specifically for the search and find variant. The id points to the id of the option currently highlighted,
-     * so that tabbing and screen reader users can jump to this option rather than tab through the list to find it.
+     * @description `id` of the currently highlighted result element. Used as the `href` of the
+     * jump-to-result skip-link. Required for the `find` variant for full accessibility.
+     * @conditionallyRequired Required when `search-type="find"`.
      */
     highlightedId: string;
+    /**
+     * @description Visible text of the currently highlighted result. Appended to the screen
+     * reader announcement after `wmSearchBrowseResults` fires. Required for the `find` variant
+     * for full accessibility.
+     * @conditionallyRequired Required when `search-type="find"`.
+     */
     highlightedName: string | null;
     /**
      * Indicates which of the search results is currently highlighted. It will be displayed as "[highlightedNum] of [numResults]" next to the input in the search and find variant.
@@ -37,11 +172,19 @@ export declare class Search {
     get isDisabled(): boolean;
     get resultCount(): string;
     /**
-     * Emitted when the buttons in the search-and-find variant are pressed.
+     * @description Fires when the prev or next button is clicked in the `find` variant.
+     * Update `highlighted-id` and `highlighted-name` in response to highlight the result in
+     * your data.
+     * @eventDetails {{ position: number }} position — one-based index of the newly highlighted result.
      */
     wmSearchBrowseResults: EventEmitter<{
         position: number;
     }>;
+    /**
+     * @description Fires on blur when the input value has changed since the last blur. Use the
+     * native `input` event for per-keystroke updates.
+     * @eventDetails {{ value: string }} value — the current input value at the time of blur.
+     */
     wmSearchValueChanged: EventEmitter<{
         value: string;
     }>;

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

@@ -1,7 +1,88 @@
 import { EventEmitter } from "../../stencil-public-runtime";
 import { Notification } from "../../global/interfaces";
+/**
+ * Toast notification stack that renders transient messages at the bottom of the page.
+ * Notifications auto-dismiss after 6 seconds unless they include a `link` or `action`, in
+ * which case they persist until explicitly dismissed or the user tabs past them.
+ *
+ * @keyboardInteraction
+ * - **Tab**: Moves focus from the action link/button to the close button; tabbing past the
+ *   close button dismisses the notification and returns focus to the previously active element.
+ * - **Shift+Tab**: Dismisses the notification from the action link and returns focus; moves
+ *   from the close button back to the action link.
+ * - **Enter**: Activates the focused close button or action link/button.
+ *
+ * @accessibility
+ * - Renders an `aria-live` region that announces new notification messages to screen readers.
+ * - When a notification includes a `link` or `action` and the user is navigating by keyboard,
+ *   focus moves automatically to the action element when the notification appears.
+ * - Focus returns to the previously active element when the notification is dismissed.
+ *
+ * @usageNotes
+ * - `notifications` is typed as a string — always pass `JSON.stringify(array)` in both HTML
+ *   and React. Passing an array directly causes a "[object Object] is not valid JSON" error.
+ * - Each notification object requires a unique `id` (string) and a `message` (string).
+ *   Optional fields: `link` (string, renders a navigation anchor), `action` (string, renders
+ *   a button), `newWindow` (boolean, adds an "opens in new window" indicator to the link).
+ * - Use `link` for navigation actions and `action` for in-page triggers such as "Undo" —
+ *   both emit `wmSnackbarActionTriggered` when clicked.
+ * - Listen to `wmSnackbarSnackFinished` and remove the matching notification from your array
+ *   to keep state in sync. The 6-second auto-dismiss timer is disabled for notifications
+ *   with a `link` or `action` — remove them manually after the action is handled.
+ * - `wmSnackbarSnackFinished` detail: `{ id: string }`.
+ * - `wmSnackbarActionTriggered` detail: `{ id: string, message: string, action?: string, link?: string }`.
+ *
+ * @example {html} Simple notification
+ * <wm-snackbar notifications='[{"id":"1","message":"Changes saved."}]'></wm-snackbar>
+ *
+ * @example {react} Notification stack with action and link variants
+ * // notifications is typed as string — always pass JSON.stringify(array), never the array directly.
+ * // wmSnackbarSnackFinished fires when a notification auto-dismisses or is closed.
+ * // wmSnackbarActionTriggered fires when the action button or link is clicked;
+ * // remove the notification manually after handling the action.
+ * let nextId = 1;
+ * const [notifications, setNotifications] = useState([]);
+ *
+ * const addNotification = (notification) =>
+ *   setNotifications((prev) => [...prev, { id: String(nextId++), ...notification }]);
+ *
+ * const removeNotification = (id) =>
+ *   setNotifications((prev) => prev.filter((n) => n.id !== id));
+ *
+ * const handleActionTriggered = (e) => {
+ *   const { id, action } = e.detail;
+ *   if (action === "Undo") { handleUndo(); }
+ *   removeNotification(id);
+ * };
+ *
+ * <WmButton buttonType="secondary" onClick={() => addNotification({ message: "Changes saved." })}>
+ *   Simple notification
+ * </WmButton>
+ * <WmButton buttonType="secondary" onClick={() => addNotification({ message: "Item deleted.", action: "Undo" })}>
+ *   With action
+ * </WmButton>
+ * <WmButton buttonType="secondary" onClick={() => addNotification({ message: "Report ready.", link: "#report" })}>
+ *   With link
+ * </WmButton>
+ *
+ * <WmSnackbar
+ *   notifications={JSON.stringify(notifications)}
+ *   onWmSnackbarSnackFinished={(e) => removeNotification(e.detail.id)}
+ *   onWmSnackbarActionTriggered={handleActionTriggered}
+ * />
+ *
+ * @category Communication
+ */
 export declare class Snackbar {
     el: HTMLElement;
+    /**
+     * @description JSON-encoded array of notification objects to display. Each object must
+     * include `id` (string) and `message` (string). Optional fields: `link` (string, renders
+     * a navigation anchor), `action` (string, renders a button), `newWindow` (boolean, adds an
+     * "opens in new window" indicator to the link). Always pass as `JSON.stringify(array)` —
+     * passing an array directly causes a "[object Object] is not valid JSON" error.
+     * @required
+     */
     notifications: string;
     private liveRegionEl;
     private snackAreaEl;
@@ -11,7 +92,20 @@ export declare class Snackbar {
     private timers;
     isTabbing: boolean;
     announcement: string;
+    /**
+     * @description Fires when a notification should be removed — after the 6-second
+     * auto-dismiss timer expires or when the user clicks the close button. The host application
+     * should remove the matching notification from its array. The timer is disabled for
+     * notifications with a `link` or `action`.
+     * @eventDetails {{ id: string, message: string, link?: string, newWindow?: boolean, action?: string }}
+     */
     wmSnackbarSnackFinished: EventEmitter<Object>;
+    /**
+     * @description Fires when the user clicks the `link` anchor or `action` button. The host
+     * application should remove the notification and navigate (for links) or execute the action
+     * (for buttons).
+     * @eventDetails {{ id: string, message: string, link?: string, newWindow?: boolean, action?: string }}
+     */
     wmSnackbarActionTriggered: EventEmitter<Object>;
     private closeSnackMessage;
     componentDidLoad(): void;

package/dist/types/components/wm-tabs/wm-tab-item/wm-tab-item.d.ts

@@ -1,29 +1,70 @@
 import { EventEmitter } from "../../../stencil-public-runtime";
+/**
+ * Individual tab button inside a wm-tab-list. Renders as a link with `role="tab"` and
+ * manages selection state. Always used as a direct child of wm-tab-list.
+ *
+ * @slot - The visible label text for the tab.
+ *
+ * @usageNotes
+ * - `tab-id` is required and must match the `tab-id` of the corresponding wm-tab-panel.
+ * - Listen to `wmTabSelected` and update the `selected-tab` prop on the parent wm-tab-list
+ *   to switch the active tab and show the associated panel.
+ *
+ * @example {html} Tab item
+ * <wm-tab-item tab-id="overview">Overview</wm-tab-item>
+ *
+ * @example {react} Tab item
+ * <WmTabItem tabId="overview">Overview</WmTabItem>
+ */
 export declare class TabItem {
     el: HTMLWmTabItemElement;
     private get parentTabList();
     /**
-     * Indicates whether the tab is currently active
+     * @description Whether this tab is currently active. Managed by the parent wm-tab-list —
+     * do not set manually.
+     * @default false
      */
     selected: boolean;
     /**
-     * The id of the tab, linked to a tab panel.
+     * @description Unique identifier linking this tab to its associated wm-tab-panel. Must
+     * match the `tab-id` on the corresponding wm-tab-panel.
+     * @required
      */
     tabId: string;
     /**
      * Reference to focusable link element
      */
     linkEl?: HTMLAnchorElement;
+    /**
+     * @description Fires when this tab is clicked or activated by keyboard. Listen to this
+     * event and update the `selected-tab` prop on the parent wm-tab-list to switch the active
+     * tab.
+     * @eventDetails {{ tabId: string }} tabId — the `tab-id` of the activated tab.
+     */
     wmTabSelected: EventEmitter<{
         tabId: string;
     }>;
+    /**
+     * @internal
+     * @description Internal signals consumed by wm-tab-list — not for application use.
+     */
     wmIntTabFocused: EventEmitter<{
         tabItem: HTMLWmTabItemElement;
     }>;
+    /**
+     * @internal
+     * @description Internal signals consumed by wm-tab-list — not for application use.
+     * @eventDetails {{ tabItem: HTMLWmTabItemElement, key: string }} tabItem — the tab item that was focused.
+     * key — the key that was pressed.
+     */
     keydownOnTabItem: EventEmitter<{
         tabItem: HTMLWmTabItemElement;
         key: string;
     }>;
+    /**
+     * @internal
+     * @description Internal signals consumed by wm-tab-list — not for application use.
+     */
     tabItemLoaded: EventEmitter<{
         tab: HTMLWmTabItemElement;
     }>;

package/dist/types/components/wm-tabs/wm-tab-list/wm-tab-list.d.ts

@@ -1,8 +1,101 @@
+/**
+ * Tab list container that manages a group of wm-tab-item children and their associated
+ * wm-tab-panel elements. Handles keyboard navigation, ARIA wiring between tabs and panels,
+ * horizontal scroll with arrow buttons on overflow, and optional dark theme.
+ *
+ * @slot - One or more wm-tab-item elements.
+ *
+ * @keyboardInteraction
+ * - **Arrow Left / Arrow Right**: Cycles focus to the previous/next tab item; wraps at both ends.
+ * - **Arrow Down**: Moves focus to the content area of the active tab panel.
+ * - **Enter / Space**: Activates the focused tab and shows its panel.
+ * - **Tab**: Moves focus from the selected tab to the first focusable element inside the
+ *   active panel.
+ * - **Shift+Tab**: Moves focus back to the selected tab item from within the panel.
+ *
+ * @accessibility
+ * - Sets `aria-controls` on each wm-tab-item link pointing to its associated wm-tab-panel.
+ * - Sets `aria-labelledby` on each wm-tab-panel pointing back to its wm-tab-item link.
+ * - ARIA attributes are updated dynamically when tab content is conditionally rendered in a
+ *   single shared panel.
+ *
+ * @usageNotes
+ * - Set the container's width to 100% in most cases.
+ * - Two usage patterns:
+ *   1. **Discrete panels** — each wm-tab-item has a paired wm-tab-panel with the same `tab-id`.
+ *   2. **Single panel** — one wm-tab-panel; content is rendered conditionally based on the
+ *      selected tab; ARIA attributes are updated automatically.
+ * - Listen to `wmTabSelected` on wm-tab-item (or on the wm-tab-list, as the event bubbles) and
+ *   update `selected-tab` to switch the active tab.
+ * - Use `selected-tab` to control which tab is initially active by its `tab-id`.
+ *
+ * @example {html} Basic tabs (discrete panels)
+ * <wm-tab-list>
+ *   <wm-tab-item tab-id="overview">Overview</wm-tab-item>
+ *   <wm-tab-item tab-id="details">Details</wm-tab-item>
+ *   <wm-tab-item tab-id="history">History</wm-tab-item>
+ * </wm-tab-list>
+ * <wm-tab-panel tab-id="overview"><p>Overview content</p></wm-tab-panel>
+ * <wm-tab-panel tab-id="details"><p>Details content</p></wm-tab-panel>
+ * <wm-tab-panel tab-id="history"><p>History content</p></wm-tab-panel>
+ *
+ * @example {react} Basic tabs (discrete panels)
+ * // wmTabSelected fires when a tab is clicked or activated via keyboard.
+ * // event.detail is { tabId: string } -- the tab-id of the newly selected tab.
+ * const [selectedTab, setSelectedTab] = useState("overview");
+ *
+ * <WmTabList selectedTab={selectedTab} onWmTabSelected={(e) => setSelectedTab(e.detail.tabId)}>
+ *   <WmTabItem tabId="overview">Overview</WmTabItem>
+ *   <WmTabItem tabId="details">Details</WmTabItem>
+ *   <WmTabItem tabId="history">History</WmTabItem>
+ * </WmTabList>
+ * <WmTabPanel tabId="overview"><p>Overview content</p></WmTabPanel>
+ * <WmTabPanel tabId="details"><p>Details content</p></WmTabPanel>
+ * <WmTabPanel tabId="history"><p>History content</p></WmTabPanel>
+ *
+ * @example {html} Single shared panel (content rendered conditionally)
+ * <wm-tab-list custom-background="dark">
+ *   <wm-tab-item tab-id="summary">Summary</wm-tab-item>
+ *   <wm-tab-item tab-id="activity">Activity</wm-tab-item>
+ * </wm-tab-list>
+ * <wm-tab-panel tab-id="summary">
+ *   <!-- app renders content here based on the active tab -->
+ * </wm-tab-panel>
+ *
+ * @example {react} Single shared panel (content rendered conditionally)
+ * // One wm-tab-panel shared by all tabs -- ARIA attributes update automatically.
+ * // Render content conditionally based on selectedTab.
+ * const [selectedTab, setSelectedTab] = useState("summary");
+ *
+ * <WmTabList
+ *   customBackground="dark"
+ *   selectedTab={selectedTab}
+ *   onWmTabSelected={(e) => setSelectedTab(e.detail.tabId)}
+ * >
+ *   <WmTabItem tabId="summary">Summary</WmTabItem>
+ *   <WmTabItem tabId="activity">Activity</WmTabItem>
+ * </WmTabList>
+ * <WmTabPanel tabId="summary">
+ *   {selectedTab === "summary" && <p>Summary content</p>}
+ *   {selectedTab === "activity" && <p>Activity content</p>}
+ * </WmTabPanel>
+ *
+ * @category Navigation
+ * @displayName Tabs
+ */
 export declare class TabList {
     el: any;
     private tabContainerEl;
     private liveRegionEl;
+    /**
+     * @description Sets the visual theme. Pass `"dark"` for the dark theme; omit for the
+     * default light theme.
+     */
     customBackground?: "dark" | "";
+    /**
+     * @description The `tab-id` of the currently active tab. Update this prop in response to
+     * `wmTabSelected` to switch tabs. Defaults to the first tab if not set.
+     */
     selectedTab?: string;
     announcement: string;
     containerFadeLeft: boolean;

package/dist/types/components/wm-tabs/wm-tab-panel/wm-tab-panel.d.ts

@@ -1,14 +1,40 @@
 import { EventEmitter } from "../../../stencil-public-runtime";
+/**
+ * Content panel associated with a wm-tab-item. Shows or hides based on whether its
+ * `tab-id` matches the selected tab in the parent wm-tab-list. Rendered with
+ * `role="tabpanel"`. Always used alongside a wm-tab-list.
+ *
+ * @slot - The panel content to display when this tab is active.
+ *
+ * @usageNotes
+ * - `tab-id` is required and must match the `tab-id` of the corresponding wm-tab-item.
+ * - For the single-panel conditional-content pattern, use one wm-tab-panel without a
+ *   `tab-id` — the parent wm-tab-list updates its ARIA attributes automatically.
+ *
+ * @example {html} Tab panel
+ * <wm-tab-panel tab-id="overview">Overview content here.</wm-tab-panel>
+ *
+ * @example {react} Tab panel
+ * <WmTabPanel tabId="overview">Overview content here.</WmTabPanel>
+ */
 export declare class TabPanel {
     el: HTMLWmTabPanelElement;
     /**
-     * Indicates whether the panel should be displayed or not.
+     * @description Whether this panel is currently visible. Managed by the parent wm-tab-list —
+     * do not set manually.
+     * @default false
      */
     active: boolean;
     /**
-     * The id of the panel, linked to a tabItem in the tablist.
+     * @description Unique identifier linking this panel to its associated wm-tab-item. Must
+     * match the `tab-id` on the corresponding wm-tab-item.
+     * @required
      */
     tabId: string;
+    /**
+     * @internal
+     * @description Internal signal consumed by wm-tab-list for ARIA wiring — not for application use.
+     */
     tabPanelLoaded: EventEmitter<{
         tabId: string;
     }>;