@watermarkinsights/ripple 0.0.1 → 0.1.0-alpha.1

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

@@ -1,17 +1,162 @@
 import { EventEmitter } from "../../stencil-public-runtime";
+/**
+ * Modal dialog that overlays the page. Renders as a full-bleed `modal` (default) or a
+ * smaller centered `dialog`. Content is provided through wm-modal-header, wm-modal-footer,
+ * and arbitrary slotted children.
+ *
+ * @category Communication
+ * @displayName Modal & Dialog
+ *
+ * @slot - Modal content: wm-modal-header, body content, and wm-modal-footer.
+ *
+ * @keyboardInteraction
+ * - **Tab**: Advances focus through focusable elements; wraps from the last element back to the first.
+ * - **Shift+Tab**: Moves focus backward; wraps from the first element to the last.
+ * - **Escape**: Fires `wmModalCloseTriggered` (the host application must set `open = false` on the element ref in response).
+ * - **Enter / Space**: Activates the focused button.
+ *
+ * @accessibility
+ * - Rendered as a `<dialog>` element with `aria-labelledby` pointing to the heading.
+ * - When footer buttons receive initial focus (`element-to-focus="primary"` or `"secondary"`),
+ *   the element `id` on `<wm-modal>` is required — it is used to construct `aria-describedby`
+ *   relationships between the heading, content, and footer.
+ * - The content wrapper must have `id="content-[id of wm-modal]"` for the aria-describedby association.
+ * - Focus returns automatically to the element that was active when the modal opened.
+ *
+ * @usageNotes
+ * - Always render the component and toggle `open` — do not conditionally mount/unmount it.
+ *   Conditional rendering breaks the `aria-live` region detection and can cause body-scroll issues.
+ * - In React, set `open` imperatively via a ref (`ref.current.open = true/false`) rather than
+ *   passing it as a prop. Using the prop triggers a React re-render that interferes with the
+ *   native `<dialog>` focus-return mechanism and causes `:focus-visible` styles to appear on
+ *   the trigger element after close.
+ * - For scrollable modal content, set `overflow: auto` on the content wrapper and reset
+ *   `scrollTop` when reopening a previously scrolled modal.
+ * - On mobile (<768px) with `modal-type="dialog"`, `element-to-focus` targeting a footer button
+ *   is overridden to the close button to avoid disorienting scroll behavior.
+ *
+ * @example {html} Basic modal
+ * <wm-modal id="confirm-modal" open>
+ *   <wm-modal-header heading="Confirm action"></wm-modal-header>
+ *   <div id="content-confirm-modal">Are you sure you want to continue?</div>
+ *   <wm-modal-footer primary-text="Confirm" secondary-text="Cancel"></wm-modal-footer>
+ * </wm-modal>
+ *
+ * @example {react} Basic modal
+ * // Set open imperatively via ref -- do not use open={} as a React prop.
+ * // This preserves the native <dialog> focus-return without triggering :focus-visible.
+ * const modalRef = useRef(null);
+ *
+ * const openModal = () => { modalRef.current.open = true; };
+ * const closeModal = () => { modalRef.current.open = false; };
+ *
+ * <WmButton onClick={openModal}>Open modal</WmButton>
+ *
+ * <WmModal
+ *   ref={modalRef}
+ *   id="confirm-modal"
+ *   onWmModalCloseTriggered={closeModal}
+ *   onWmModalPrimaryTriggered={closeModal}
+ *   onWmModalSecondaryTriggered={closeModal}
+ * >
+ *   <WmModalHeader heading="Confirm action" />
+ *   <div id="content-confirm-modal">Are you sure you want to continue?</div>
+ *   <WmModalFooter primaryText="Confirm" secondaryText="Cancel" />
+ * </WmModal>
+ *
+ * @example {html} Dialog type (smaller, centered)
+ * <wm-modal id="info-dialog" modal-type="dialog" open>
+ *   <wm-modal-header heading="Information"></wm-modal-header>
+ *   <div id="content-info-dialog">This is additional context.</div>
+ *   <wm-modal-footer primary-text="Got it"></wm-modal-footer>
+ * </wm-modal>
+ *
+ * @example {react} Dialog type
+ * const dialogRef = useRef(null);
+ *
+ * const openDialog = () => { dialogRef.current.open = true; };
+ * const closeDialog = () => { dialogRef.current.open = false; };
+ *
+ * <WmButton onClick={openDialog}>Open dialog</WmButton>
+ *
+ * <WmModal
+ *   ref={dialogRef}
+ *   id="info-dialog"
+ *   modalType="dialog"
+ *   onWmModalCloseTriggered={closeDialog}
+ *   onWmModalPrimaryTriggered={closeDialog}
+ * >
+ *   <WmModalHeader heading="Information" />
+ *   <div id="content-info-dialog">This is additional context.</div>
+ *   <WmModalFooter primaryText="Got it" />
+ * </WmModal>
+ *
+ * @requiredSetup
+ * - Drive `open` from your own state: true to show the modal, false to hide it. In React set it
+ *   through a ref (`ref.current.open = true`) rather than as a prop, which breaks the native dialog
+ *   focus-return.
+ * - Handle `wmModalCloseTriggered` -- the close button and Escape -- by setting `open = false`. It
+ *   does not bubble, so attach the listener to the element itself.
+ * - Handle `wmModalPrimaryTriggered` and `wmModalSecondaryTriggered` for whichever wm-modal-footer
+ *   buttons you render, setting `open = false` to dismiss.
+ * - Reset the content wrapper's `scrollTop` to 0 when reopening, if the body content scrolls.
+ *
+ */
 export declare class Modal {
     el: HTMLWmModalElement;
     private dialogEl;
+    /**
+     * @description Controls the open/closed state of the modal. Always render the component and
+     * toggle this prop — do not conditionally mount/unmount.
+     * @default false
+     */
     open: boolean;
+    /**
+     * @description Element to focus when the modal opens. Pass `"primary"` or `"secondary"` to
+     * focus the corresponding wm-modal-footer button, or an element `id` to focus a specific
+     * element in the modal body. Defaults to the close button. Requires `id` to be set on
+     * `<wm-modal>` when targeting footer buttons.
+     * @default ""
+     */
     elementToFocus: "primary" | "secondary" | string;
+    /**
+     * @description Visual presentation style. `'modal'` renders a full-bleed overlay; `'dialog'`
+     * renders a smaller centered panel.
+     * @default "modal"
+     */
     modalType: "modal" | "dialog";
+    /**
+     * @description Unique identifier used internally to wire `aria-labelledby` and
+     * `aria-describedby` relationships. Set automatically from the element's `id` attribute or
+     * generated if absent — do not set this prop manually.
+     */
     uid: string;
     returnFocusEl: HTMLElement;
+    /**
+     * @internal
+     * @description Internal tab-trap signals — not for application use.
+     */
     focusLastElement: EventEmitter;
+    /**
+     * @internal
+     * @description Internal tab-trap signals — not for application use.
+     */
     focusFirstElement: EventEmitter;
+    /**
+     * @description Fires when the close button is clicked or Escape is pressed. Does not bubble,
+     * preventing nested modals from closing simultaneously. The host application must set `open`
+     * to false in response.
+     */
     wmModalCloseTriggered: EventEmitter;
+    /**
+     * @description Fires when the wm-modal-footer primary button is clicked.
+     */
     wmModalPrimaryTriggered: EventEmitter;
+    /**
+     * @description Fires when the wm-modal-footer secondary button is clicked.
+     */
     wmModalSecondaryTriggered: EventEmitter;
+    private initialBodyOverflow?;
     get closeButtonEl(): HTMLElement;
     get focusOnOpenEl(): HTMLElement | null;
     get hasBrowserPopoverSupport(): boolean;
@@ -21,8 +166,23 @@ export declare class Modal {
     hideModal(): void;
     componentWillLoad(): void;
     componentDidLoad(): void;
+    /**
+     * @description Programmatically fires `wmModalCloseTriggered`. Use when you need to trigger
+     * a close from outside the modal without simulating a button click.
+     * @returns A promise that resolves once the event has been emitted.
+     */
     emitCloseEvent(): Promise<void>;
+    /**
+     * @description Programmatically fires `wmModalPrimaryTriggered`. Use when you need to trigger
+     * the primary action from outside the modal.
+     * @returns A promise that resolves once the event has been emitted.
+     */
     emitPrimaryEvent(): Promise<void>;
+    /**
+     * @description Programmatically fires `wmModalSecondaryTriggered`. Use when you need to trigger
+     * the secondary action from outside the modal.
+     * @returns A promise that resolves once the event has been emitted.
+     */
     emitSecondaryEvent(): Promise<void>;
     handleKeyDown(ev: KeyboardEvent): void;
     setAriaDescribedbyOnModal(): void;

package/dist/types/components/wm-modal-pss/wm-modal-pss-footer.d.ts

@@ -1,3 +1,7 @@
+/**
+ * @internal
+ * @description Footer section for a wm-modal-pss. Not to be used outside of PSS.
+ */
 export declare class ModalPssFooter {
     el: HTMLElement;
     secondaryText?: string;

package/dist/types/components/wm-modal-pss/wm-modal-pss-header.d.ts

@@ -1,3 +1,7 @@
+/**
+ * @internal
+ * @description Header section for a wm-modal-pss. Not to be used outside of PSS.
+ */
 export declare class ModalPssHeader {
     el: HTMLElement;
     private closeButtonEl;

package/dist/types/components/wm-modal-pss/wm-modal-pss.d.ts

@@ -1,4 +1,8 @@
 import { EventEmitter } from "../../stencil-public-runtime";
+/**
+ * @internal
+ * @description Modal component created specifically for Planning and Self Studies. Not to be used outside of PSS.
+ */
 export declare class ModalPss {
     el: HTMLWmModalPssElement;
     open: boolean;
@@ -8,6 +12,8 @@ export declare class ModalPss {
     private focusOnCloseEl;
     private overlayEl;
     private bodyFocusListener;
+    private initialBodyOverflow?;
+    private initialBodyTabIndex?;
     focusLastElement: EventEmitter;
     focusFirstElement: EventEmitter;
     wmModalCloseTriggered: EventEmitter;

package/dist/types/components/wm-navigation/wm-navigation-hamburger.d.ts

@@ -1,10 +1,44 @@
 import { EventEmitter } from "../../stencil-public-runtime";
+/**
+ * Toggle button for the collapsible wm-navigation sidebar. Renders a hamburger/menu icon
+ * button that communicates with wm-navigation via window events. Place immediately before
+ * the associated wm-navigation element in the DOM.
+ *
+ * @keyboardInteraction
+ * - **Enter / Space**: Toggles the navigation open/closed.
+ *
+ * @accessibility
+ * - Rendered as a `<button>` with `aria-expanded` reflecting the navigation's open state.
+ * - Keeps `aria-expanded` in sync by listening to `wmNavigationStateChanged` from the
+ *   associated wm-navigation element.
+ *
+ * @usageNotes
+ * - `nav-id` is required; it must match the `id` on the associated wm-navigation element.
+ * - Place this component immediately before the wm-navigation element in the DOM.
+ *
+ * @example {html} Basic hamburger
+ * <wm-navigation-hamburger nav-id="main-nav"></wm-navigation-hamburger>
+ * <wm-navigation id="main-nav">...</wm-navigation>
+ *
+ * @example {react} Basic hamburger
+ * <WmNavigationHamburger navId="main-nav" />
+ * <WmNavigation id="main-nav">...</WmNavigation>
+ */
 export declare class NavigationHamburger {
     el: HTMLWmNavigationHamburgerElement;
     nav: HTMLWmNavigationElement;
+    /**
+     * @description The `id` of the associated wm-navigation element. Required for semantic
+     * linking and for keeping `aria-expanded` in sync with the navigation's open state.
+     * @required
+     */
     navId?: string;
     isTabbing?: boolean;
     open: boolean;
+    /**
+     * @description Fires when the button is clicked. Consumed by the associated wm-navigation
+     * to toggle its `open` state — not intended for direct application use.
+     */
     wmNavigationHamburgerClicked: EventEmitter;
     showNavMessage: string;
     toggleTabbingOn(): void;

package/dist/types/components/wm-navigation/wm-navigation-item.d.ts

@@ -1,9 +1,50 @@
 import { EventEmitter } from "../../stencil-public-runtime";
+/**
+ * A single navigation link inside a wm-navigation. Renders as an anchor element with an
+ * optional icon slot. Always used as a direct child of wm-navigation.
+ *
+ * @slot - Optional icon element displayed before the link text.
+ *
+ * @usageNotes
+ * - Set `active` on the item that corresponds to the current route.
+ * - Clicking an item emits `wmNavigationItemClicked`, which the parent wm-navigation listens
+ *   to in order to close the collapsible menu on narrow viewports.
+ *
+ * @example {html} Basic navigation item
+ * <wm-navigation-item href="/dashboard" text="Dashboard" active></wm-navigation-item>
+ *
+ * @example {react} Basic navigation item
+ * <WmNavigationItem href="/dashboard" text="Dashboard" active={true} />
+ *
+ * @example {html} Navigation item with icon
+ * <wm-navigation-item href="/reports" text="Reports">
+ *   <span class="svg-icon svg-chart"></span>
+ * </wm-navigation-item>
+ *
+ * @example {react} Navigation item with icon
+ * <WmNavigationItem href="/reports" text="Reports">
+ *   <span className="svg-icon svg-chart" />
+ * </WmNavigationItem>
+ */
 export declare class NavigationItem {
     el: HTMLWmNavigationItemElement;
+    /**
+     * @description URL the link navigates to.
+     */
     href?: string;
+    /**
+     * @description The visible label text for the navigation link.
+     */
     text?: string;
+    /**
+     * @description Marks this item as the currently active route, applying active styling.
+     * @default false
+     */
     active?: boolean;
+    /**
+     * @description Fires when the link is clicked. Consumed by the parent wm-navigation to
+     * close the collapsible menu on narrow viewports.
+     */
     wmNavigationItemClicked: EventEmitter;
     render(): any;
 }

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

@@ -1,9 +1,66 @@
 import { EventEmitter } from "../../stencil-public-runtime";
+/**
+ * Sidebar navigation that collapses into a hamburger menu on viewports narrower than 1024px.
+ * Contains wm-navigation-item children and works alongside an external wm-navigation-hamburger
+ * toggle. Must be placed in the DOM after `<header>` and before `<main>`.
+ *
+ * @category Navigation
+ *
+ * @slot - One or more wm-navigation-item elements.
+ *
+ * @keyboardInteraction
+ * - **Escape**: Collapses the navigation when in collapsible mode.
+ * - **Tab / Shift+Tab**: Cycles through navigation items; focus is trapped within the component
+ *   while the collapsible menu is open.
+ * - **Enter / Space**: Activates the close button when focused (collapses the menu).
+ *
+ * @accessibility
+ * - Rendered with `role="navigation"` and an `aria-label` of "Main".
+ * - `aria-expanded` is set on the host element in collapsible mode only; omitted on wider viewports.
+ * - When the collapsible menu is open, focus is trapped and redirected back from the browser
+ *   address bar via a `focus` listener on `document.body`.
+ *
+ * @usageNotes
+ * - Use `wm-navigation-hamburger` (a separate component) as the external toggle; it communicates
+ *   with wm-navigation via the `wmNavigationHamburgerClicked` window event.
+ * - `open` can be set initially to `true` to start the navigation expanded.
+ * - Navigation and main content scroll independently — no additional overflow handling is needed.
+ *
+ * Required host setup:
+ * - Never set `display: none` or `visibility: hidden` on the host element or its wrapper
+ *   container. The component manages its own visibility internally, and hiding the container
+ *   from the outside blocks the overlay from appearing when the hamburger is triggered.
+ *
+ * @example {html} Basic navigation
+ * <wm-navigation-hamburger nav-id="main-nav"></wm-navigation-hamburger>
+ * <wm-navigation id="main-nav">
+ *   <wm-navigation-item href="/dashboard" text="Dashboard" active></wm-navigation-item>
+ *   <wm-navigation-item href="/reports" text="Reports"></wm-navigation-item>
+ * </wm-navigation>
+ *
+ * @example {react} Basic navigation
+ * <WmNavigationHamburger navId="main-nav" />
+ * <WmNavigation id="main-nav">
+ *   <WmNavigationItem href="/dashboard" text="Dashboard" active={true} />
+ *   <WmNavigationItem href="/reports" text="Reports" />
+ * </WmNavigation>
+ *
+ */
 export declare class Navigation {
     el: HTMLWmNavigationElement;
     toggleEl: HTMLWmButtonElement;
+    /**
+     * @description Controls the open/closed state of the collapsible navigation. Has no effect
+     * on viewports wider than 1024px where the navigation is always visible.
+     * @default false
+     */
     open: boolean;
+    /**
+     * @description Fires when the collapsible navigation opens or closes. Consumed by
+     * wm-navigation-hamburger to keep its `aria-expanded` state in sync.
+     */
     wmNavigationStateChanged: EventEmitter;
+    private initialBodyTabIndex?;
     private mainNavigationMessage;
     get isCollapsible(): boolean;
     get ariaExpanded(): string | undefined;

package/dist/types/components/wm-navigator/priv-navigator-button/priv-navigator-button.d.ts

@@ -1,4 +1,8 @@
 import { EventEmitter } from "../../../stencil-public-runtime";
+/**
+ * @internal
+ * @description Internal navigator button component for use with the Navigation component. Not to be used directly.
+ */
 export declare class PrivNavigatorButton {
     el: any;
     expanded: boolean;

package/dist/types/components/wm-navigator/priv-navigator-item/priv-navigator-item.d.ts

@@ -1,4 +1,8 @@
 import { EventEmitter } from "../../../stencil-public-runtime";
+/**
+ * @internal
+ * @description Internal navigator item component for use with the Navigation component. Not to be used directly.
+ */
 export declare class PrivNavigatorItem {
     el: any;
     selected: boolean;

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

@@ -1,20 +1,104 @@
 import { EventEmitter } from "../../stencil-public-runtime";
 import { Product } from "../../global/interfaces";
+/**
+ * User account menu that displays the logged-in user's name, email, and a product switcher
+ * for navigating between Watermark applications. Renders as a button that opens a dropdown
+ * listing available products and a logout option.
+ *
+ * @category Navigation
+ *
+ * @keyboardInteraction
+ * - **Down Arrow / Up Arrow**: Opens the menu and navigates between product options.
+ * - **Enter / Space**: Activates the focused option or opens the menu.
+ * - **Escape**: Closes the menu.
+ * - **Tab**: Closes the menu.
+ *
+ * @accessibility
+ * - User info (name and email) is grouped with an `aria-label` for screen readers.
+ * - Product options are rendered in a `role="listbox"` with `role="option"` items and
+ *   `aria-selected` reflecting the current product.
+ *
+ * @usageNotes
+ * - Two data modes: **prop mode** (pass `user-name`, `email`, `products`, `auth-type` as props)
+ *   and **endpoint mode** (set `load-from-userinfo="true"` to fetch from `/platform/navigator/userinfo`).
+ * - In prop mode, set `auth-type` to match your authentication method: `1` (no redirect), `2`
+ *   (username/password or SSO — uses `link_url`), or `3` (SAML — uses `saml_link_url`).
+ * - Always handle `wmNavigatorLogout` to run app-specific cleanup (e.g. clearing local storage)
+ *   before the logout redirect.
+ * - Set `logout-url` to redirect after logout; omit it to handle navigation entirely in the
+ *   `wmNavigatorLogout` event handler.
+ * - URLs in product data are validated against a Watermark domain whitelist; invalid URLs are
+ *   rejected with a console error.
+ *
+ * @example {html} Prop mode
+ * <wm-navigator
+ *   user-name="Maria Garcia"
+ *   email="m.garcia@example.com"
+ *   auth-type="2"
+ *   logout-url="https://app.watermarkinsights.com/logout"
+ *   products='[{"id":"app1","name":"Insights","icon_url":"/icons/insights.svg","link_url":"https://insights.watermarkinsights.com"}]'>
+ * </wm-navigator>
+ *
+ * @example {react} Prop mode
+ * <WmNavigator
+ *   userName="Maria Garcia"
+ *   email="m.garcia@example.com"
+ *   authType={2}
+ *   logoutUrl="https://app.watermarkinsights.com/logout"
+ *   products={JSON.stringify(products)}
+ *   onWmNavigatorLogout={handleLogout} />
+ *
+ * @example {html} Endpoint mode (fetches user info automatically)
+ * <wm-navigator user-name="Maria Garcia" load-from-userinfo="true"></wm-navigator>
+ *
+ * @example {react} Endpoint mode
+ * <WmNavigator userName="Maria Garcia" loadFromUserinfo={true} onWmNavigatorLogout={handleLogout} />
+ *
+ */
 export declare class Navigator {
     el: any;
     private wrapperEl?;
+    /**
+     * @description The display name of the logged-in user, shown in the menu header.
+     * @required
+     */
     userName?: string;
+    /**
+     * @description The email address of the logged-in user, shown in the menu header.
+     * @conditionallyRequired when load-from-userinfo is false
+     */
     email?: string;
+    /**
+     * @description Authentication method, determining how product link redirects are handled.
+     * `1` — no redirect; `2` — username/password or SSO (uses `link_url`); `3` — SAML (uses `saml_link_url`).
+     * @default 1
+     * @conditionallyRequired when load-from-userinfo is false and products are provided
+     */
     authType: number;
+    /**
+     * @description SAML connection name appended as a query parameter to product redirect URLs.
+     * Only used when `auth-type` is `3`.
+     */
     connectionName?: string;
+    /**
+     * @description URL to redirect to after logout. If omitted, no redirect occurs — handle
+     * navigation entirely in the `wmNavigatorLogout` event handler.
+     */
     logoutUrl?: string;
+    /**
+     * @description The user's accessible Watermark products, as a JSON string or array of objects.
+     * Each object must include `id`, `name`, `icon_url`, and either `link_url` (auth-type 2) or
+     * `saml_link_url` (auth-type 3). Not needed when `load-from-userinfo` is true.
+     */
     products?: string | [];
+    /**
+     * @description When true, fetches user info and products automatically from the
+     * `/platform/navigator/userinfo` endpoint instead of using props.
+     * @default false
+     */
     loadFromUserinfo: boolean;
     private retrievedInfo;
     parsedProducts: Array<Product>;
-    /**
-     * Event emitted from child wm-navigator-button updates the state, which is then passed down as a prop by wm-navigator.
-     */
     isOpen: boolean;
     private openRight;
     /**
@@ -23,6 +107,11 @@ export declare class Navigator {
      * State resets to the index of the current product when the dropdown closes.
      */
     itemIndexToFocus: number;
+    /**
+     * @description Fires when the user clicks the logout option. Always handle this event to
+     * run app-specific cleanup (e.g. clearing local storage or session state) before any logout
+     * redirect. If `logout-url` is set, the component will navigate there after this event fires.
+     */
     wmNavigatorLogout: EventEmitter;
     private currentProductId;
     isSafeUrl(url?: string): boolean;
@@ -39,7 +128,7 @@ export declare class Navigator {
     handleButtonClick(): void;
     openMenu(): void;
     closeMenu(returnFocus?: boolean): void;
-    focusItem(): void;
+    focusItem(delayMs?: number): void;
     unfocusItem(index: number): void;
     buttonFocusHandler(): void;
     /**

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

@@ -1,16 +1,115 @@
 import { EventEmitter } from "../../stencil-public-runtime";
+/**
+ * Pagination controls for navigating large data sets. Renders a full page-number strip on
+ * wider viewports and a minimal prev/next/first/last layout on narrow viewports. Does not
+ * render at all when the total item count fits on a single page.
+ *
+ * @category Navigation
+ *
+ * @accessibility
+ * - Rendered as a `<nav>` element with an `aria-label` that includes the current page and
+ *   visible item range, announced to screen readers on load.
+ * - An `aria-live` region announces the new current page when navigation occurs.
+ * - Disabled previous/next buttons shift focus to the nearest enabled button automatically.
+ * - Current page button carries `aria-current="page"`.
+ *
+ * @usageNotes
+ * - `current-page`, `total-items`, and `items-per-page` are all required; a missing value
+ *   throws an error on load.
+ * - Listen to `wmPaginationPageClicked` and read `event.target.value` to get the selected
+ *   page number. `event.target.value` is a string — wrap with `Number()` before storing.
+ * - The component does not manage data — it only reports which page was selected.
+ * - When multiple pagination instances appear on the same page, give each a unique `label`
+ *   to disambiguate the `<nav>` landmark for screen readers, and drive each from independent state.
+ *
+ * @example {html} Basic pagination
+ * <wm-pagination current-page="1" total-items="150" items-per-page="25"></wm-pagination>
+ *
+ * @example {react} Basic pagination
+ * // event.target.value is a string — use Number() when storing as a number.
+ * const [currentPage, setCurrentPage] = useState(1);
+ *
+ * <WmPagination
+ *   currentPage={currentPage}
+ *   totalItems={150}
+ *   itemsPerPage={25}
+ *   onWmPaginationPageClicked={(e) => setCurrentPage(Number(e.target.value))} />
+ *
+ * @example {html} With accessible label
+ * <wm-pagination label="Search results" current-page="1" total-items="80" items-per-page="10">
+ * </wm-pagination>
+ *
+ * @example {react} Multiple instances with independent state
+ * // Give each instance a unique label to disambiguate the nav landmark for screen readers.
+ * // Drive each from its own state variable so they page independently.
+ * const [page1, setPage1] = useState(1);
+ * const [page2, setPage2] = useState(1);
+ *
+ * <WmPagination currentPage={page1} totalItems={150} itemsPerPage={10}
+ *   onWmPaginationPageClicked={(e) => setPage1(Number(e.target.value))} />
+ *
+ * <WmPagination label="Search results" currentPage={page2} totalItems={80} itemsPerPage={10}
+ *   onWmPaginationPageClicked={(e) => setPage2(Number(e.target.value))} />
+ *
+ * @requiredSetup
+ * - Handle `wmPaginationPageClicked` by reading `event.target.value` -- a string, so convert it to
+ *   a number -- and writing it to `current-page`.
+ * - Set `total-items` and `items-per-page` from the data you are paging; together they determine the
+ *   page count.
+ * - Share one page state between paginations rendered above and below the same table.
+ *
+ */
 export declare class Pagination {
     el: any;
+    /**
+     * @description Accessible label for the `<nav>` element. Defaults to `"Pagination navigation"`.
+     * Override when multiple pagination instances appear on the same page (e.g. `"Search results"`).
+     */
+    label: string;
+    /**
+     * @description The currently active page number. Update this prop in response to
+     * `wmPaginationPageClicked` to keep the component in sync with your data.
+     * @default 1
+     * @required
+     */
     currentPage: number;
+    /**
+     * @description Total number of items across all pages. Used with `items-per-page` to
+     * calculate the total page count.
+     * @required
+     */
     totalItems?: number;
+    /**
+     * @description Number of items displayed per page. Used with `total-items` to calculate
+     * the total page count.
+     * @required
+     */
     itemsPerPage?: number;
+    /**
+     * @description The page number selected by the most recent user interaction. Read
+     * `event.target.value` in the `wmPaginationPageClicked` handler to get the selected page.
+     * @default 1
+     */
     value: number;
+    /**
+     * @internal
+     * @description Internal responsive state — updated by ResizeObserver; not intended for external use.
+     */
     isLargeSize: boolean;
     srAnnouncement: string;
     private totalPages;
+    /**
+     * @description Fires when the user clicks a page number, previous, or next button.
+     * Read `event.target.value` to get the selected page number, then update `current-page`
+     * and re-render your data.
+     */
     wmPaginationPageClicked: EventEmitter<string>;
+    /**
+     * @internal
+     * @description Internal event used to restore focus to the current page button after re-render.
+     */
     focusCurrentPage: EventEmitter;
-    private navigationLabel;
+    private defaultLabel;
     private nextPageButtonLabel;
     private previousPageButtonLabel;
     private pageButtonLabel;