@watermarkinsights/ripple 5.30.0 → 5.31.0-alpha.1

package/dist/docs/wm-navigation-hamburger.md

@@ -0,0 +1,91 @@
+# `wm-navigation-hamburger`
+
+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.
+
+## Props
+
+| Name | Attribute | Type | Default | Required | Description |
+| ---- | --------- | ---- | ------- | -------- | ----------- |
+| `navId` | `nav-id` | `string \| undefined` |  |  |  |
+
+## Events
+
+| Event | Detail | Bubbles | Description |
+| ----- | ------ | ------- | ----------- |
+| `wmNavigationHamburgerClicked` | `any` | ✓ |  |
+
+# wm-navigation
+
+## Purpose
+
+The primary site navigation component that renders a persistent vertical nav on wide screens and collapses into a hamburger-triggered panel on smaller viewports, providing consistent cross-page wayfinding across the product.
+
+---
+
+## When to Use
+
+- **Providing the main navigation structure for a product** -- when building the primary layout of a page that follows the Ripple design system's standard page layout, Navigation is the designated component for the top-level navigation links that persist across every page.
+- **Implementing a collapsible nav for responsive layouts** -- when the product needs navigation to collapse below the 1024px breakpoint, include wm-navigation-hamburger alongside wm-navigation to give users a toggle control; the component handles open/close behavior automatically at that breakpoint.
+
+---
+
+## Do Not Use For
+
+- **In-page section switching** -- Navigation is for moving between pages or top-level product areas, not for switching between sections within a single page; use wm-tabs for that purpose instead.
+
+---
+
+## Related Components
+
+- `<wm-tabs>` -- if the goal is switching between views or sections within a single page rather than navigating to different pages, use Tabs; Navigation is for top-level cross-page routing only.
+- `<wm-navigator>` -- if the navigation pattern involves the product's app bar or auth-integrated header rather than the side nav, use Navigator; Navigation is the side nav, not the top bar.
+- `<wm-pagination>` -- if the user is moving through pages of a dataset rather than product sections, use Pagination; Navigation is not a data paging mechanism.
+
+---
+
+## Accessibility
+
+- Marking the current active page in the nav: when rendering navigation items, use the active property on the wm-navigation-item matching the current page so the component communicates the user's current location both visually and to screen readers.
+- Placement outside its required markup structure: Navigation only works correctly in a specific page structure (body > header + div > wm-navigation + main); placing it arbitrarily in the markup will break its scroll behavior, z-index stacking, and responsive collapsing.
+- Implementing a skip-navigation link: any skip-navigation link must be implemented separately; Navigation does not handle this itself, and expecting it to is a common accessibility gap.
+
+---
+
+## Variants / Types
+
+_None documented_
+
+---
+
+## Props
+
+- wm-navigation props:
+- `open` -- controls whether the collapsible nav panel is expanded
+- wm-navigation-hamburger props:
+- `navId` -- the ID of the wm-navigation element this button controls
+- wm-navigation-item props:
+- `text` -- the visible label and accessible name for the navigation link
+- `href` -- the destination URL for the nav item
+- `active` -- marks this item as the current page
+
+---
+
+## Events
+
+- `wmNavigationStateChanged (on wm-navigation)` -- fires when the nav panel opens or closes
+- `wmNavigationHamburgerClicked (on wm-navigation-hamburger)` -- fires when the hamburger button is activated
+- `wmNavigationItemClicked (on wm-navigation-item)` -- fires when a nav item is activated
+
+---
+
+## Methods
+
+- _None exposed_
+
+---
+
+## Code Example
+
+*(to be filled in by developer)*

package/dist/docs/wm-navigation-item.md

@@ -0,0 +1,98 @@
+# `wm-navigation-item`
+
+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.
+
+## Props
+
+| Name | Attribute | Type | Default | Required | Description |
+| ---- | --------- | ---- | ------- | -------- | ----------- |
+| `active` | `active` | `boolean \| undefined` |  |  |  |
+| `href` | `href` | `string \| undefined` |  |  |  |
+| `text` | `text` | `string \| undefined` |  |  |  |
+
+## Events
+
+| Event | Detail | Bubbles | Description |
+| ----- | ------ | ------- | ----------- |
+| `wmNavigationItemClicked` | `any` | ✓ |  |
+
+## Slots
+
+| Name | Description |
+| ---- | ----------- |
+| _(default)_ | Optional icon element displayed before the link text. |
+
+# wm-navigation
+
+## Purpose
+
+The primary site navigation component that renders a persistent vertical nav on wide screens and collapses into a hamburger-triggered panel on smaller viewports, providing consistent cross-page wayfinding across the product.
+
+---
+
+## When to Use
+
+- **Providing the main navigation structure for a product** -- when building the primary layout of a page that follows the Ripple design system's standard page layout, Navigation is the designated component for the top-level navigation links that persist across every page.
+- **Implementing a collapsible nav for responsive layouts** -- when the product needs navigation to collapse below the 1024px breakpoint, include wm-navigation-hamburger alongside wm-navigation to give users a toggle control; the component handles open/close behavior automatically at that breakpoint.
+
+---
+
+## Do Not Use For
+
+- **In-page section switching** -- Navigation is for moving between pages or top-level product areas, not for switching between sections within a single page; use wm-tabs for that purpose instead.
+
+---
+
+## Related Components
+
+- `<wm-tabs>` -- if the goal is switching between views or sections within a single page rather than navigating to different pages, use Tabs; Navigation is for top-level cross-page routing only.
+- `<wm-navigator>` -- if the navigation pattern involves the product's app bar or auth-integrated header rather than the side nav, use Navigator; Navigation is the side nav, not the top bar.
+- `<wm-pagination>` -- if the user is moving through pages of a dataset rather than product sections, use Pagination; Navigation is not a data paging mechanism.
+
+---
+
+## Accessibility
+
+- Marking the current active page in the nav: when rendering navigation items, use the active property on the wm-navigation-item matching the current page so the component communicates the user's current location both visually and to screen readers.
+- Placement outside its required markup structure: Navigation only works correctly in a specific page structure (body > header + div > wm-navigation + main); placing it arbitrarily in the markup will break its scroll behavior, z-index stacking, and responsive collapsing.
+- Implementing a skip-navigation link: any skip-navigation link must be implemented separately; Navigation does not handle this itself, and expecting it to is a common accessibility gap.
+
+---
+
+## Variants / Types
+
+_None documented_
+
+---
+
+## Props
+
+- wm-navigation props:
+- `open` -- controls whether the collapsible nav panel is expanded
+- wm-navigation-hamburger props:
+- `navId` -- the ID of the wm-navigation element this button controls
+- wm-navigation-item props:
+- `text` -- the visible label and accessible name for the navigation link
+- `href` -- the destination URL for the nav item
+- `active` -- marks this item as the current page
+
+---
+
+## Events
+
+- `wmNavigationStateChanged (on wm-navigation)` -- fires when the nav panel opens or closes
+- `wmNavigationHamburgerClicked (on wm-navigation-hamburger)` -- fires when the hamburger button is activated
+- `wmNavigationItemClicked (on wm-navigation-item)` -- fires when a nav item is activated
+
+---
+
+## Methods
+
+- _None exposed_
+
+---
+
+## Code Example
+
+*(to be filled in by developer)*

package/dist/docs/wm-navigation.md

@@ -0,0 +1,101 @@
+# `wm-navigation`
+
+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>`.
+
+## Props
+
+| Name | Attribute | Type | Default | Required | Description |
+| ---- | --------- | ---- | ------- | -------- | ----------- |
+| `open` | `open` | `boolean` | `false` |  |  |
+
+## Events
+
+| Event | Detail | Bubbles | Description |
+| ----- | ------ | ------- | ----------- |
+| `wmNavigationStateChanged` | `any` | ✓ |  |
+
+## Slots
+
+| Name | Description |
+| ---- | ----------- |
+| _(default)_ | One or more wm-navigation-item elements. |
+
+## Depends On
+
+- `wm-button`
+
+# wm-navigation
+
+## Purpose
+
+The primary site navigation component that renders a persistent vertical nav on wide screens and collapses into a hamburger-triggered panel on smaller viewports, providing consistent cross-page wayfinding across the product.
+
+---
+
+## When to Use
+
+- **Providing the main navigation structure for a product** -- when building the primary layout of a page that follows the Ripple design system's standard page layout, Navigation is the designated component for the top-level navigation links that persist across every page.
+- **Implementing a collapsible nav for responsive layouts** -- when the product needs navigation to collapse below the 1024px breakpoint, include wm-navigation-hamburger alongside wm-navigation to give users a toggle control; the component handles open/close behavior automatically at that breakpoint.
+
+---
+
+## Do Not Use For
+
+- **In-page section switching** -- Navigation is for moving between pages or top-level product areas, not for switching between sections within a single page; use wm-tabs for that purpose instead.
+
+---
+
+## Related Components
+
+- `<wm-tabs>` -- if the goal is switching between views or sections within a single page rather than navigating to different pages, use Tabs; Navigation is for top-level cross-page routing only.
+- `<wm-navigator>` -- if the navigation pattern involves the product's app bar or auth-integrated header rather than the side nav, use Navigator; Navigation is the side nav, not the top bar.
+- `<wm-pagination>` -- if the user is moving through pages of a dataset rather than product sections, use Pagination; Navigation is not a data paging mechanism.
+
+---
+
+## Accessibility
+
+- Marking the current active page in the nav: when rendering navigation items, use the active property on the wm-navigation-item matching the current page so the component communicates the user's current location both visually and to screen readers.
+- Placement outside its required markup structure: Navigation only works correctly in a specific page structure (body > header + div > wm-navigation + main); placing it arbitrarily in the markup will break its scroll behavior, z-index stacking, and responsive collapsing.
+- Implementing a skip-navigation link: any skip-navigation link must be implemented separately; Navigation does not handle this itself, and expecting it to is a common accessibility gap.
+
+---
+
+## Variants / Types
+
+_None documented_
+
+---
+
+## Props
+
+- wm-navigation props:
+- `open` -- controls whether the collapsible nav panel is expanded
+- wm-navigation-hamburger props:
+- `navId` -- the ID of the wm-navigation element this button controls
+- wm-navigation-item props:
+- `text` -- the visible label and accessible name for the navigation link
+- `href` -- the destination URL for the nav item
+- `active` -- marks this item as the current page
+
+---
+
+## Events
+
+- `wmNavigationStateChanged (on wm-navigation)` -- fires when the nav panel opens or closes
+- `wmNavigationHamburgerClicked (on wm-navigation-hamburger)` -- fires when the hamburger button is activated
+- `wmNavigationItemClicked (on wm-navigation-item)` -- fires when a nav item is activated
+
+---
+
+## Methods
+
+- _None exposed_
+
+---
+
+## Code Example
+
+*(to be filled in by developer)*

package/dist/docs/wm-navigator.md

@@ -0,0 +1,99 @@
+# `wm-navigator`
+
+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.
+
+## Props
+
+| Name | Attribute | Type | Default | Required | Description |
+| ---- | --------- | ---- | ------- | -------- | ----------- |
+| `authType` | `auth-type` | `number` | `1` | when load-from-userinfo is false and products are provided |  |
+| `connectionName` | `connection-name` | `string \| undefined` |  |  |  |
+| `email` | `email` | `string \| undefined` |  | when load-from-userinfo is false |  |
+| `loadFromUserinfo` | `load-from-userinfo` | `boolean` | `false` |  |  |
+| `logoutUrl` | `logout-url` | `string \| undefined` |  |  |  |
+| `products` | `products` | `[] \| string \| undefined` |  |  |  |
+| `userName` | `user-name` | `string \| undefined` |  |  |  |
+
+## Events
+
+| Event | Detail | Bubbles | Description |
+| ----- | ------ | ------- | ----------- |
+| `wmNavigatorLogout` | `any` | ✓ |  |
+
+## Depends On
+
+- `priv-navigator-item`
+- `priv-navigator-button`
+
+# wm-navigator
+
+## Purpose
+
+A product-switching dropdown that lets authenticated Watermark users see and jump between the products they have access to, and log out, from a single persistent control in the product header.
+
+---
+
+## When to Use
+
+- **Providing cross-product switching in the product header** -- when building a Watermark product within the broader platform ecosystem, use Navigator to give users access to their other permitted products without navigating back to a separate launcher.
+
+---
+
+## Do Not Use For
+
+- **General navigation menus** -- Navigator is purpose-built for Watermark platform product-switching and logout; it is not a general-purpose navigation component. For within-product page navigation, use wm-navigation.
+- **Contexts outside the Watermark platform** -- this component is explicitly designed for Watermark's multi-product platform architecture and should not be used as a general product switcher or user menu in unrelated contexts.
+
+---
+
+## Related Components
+
+- `<wm-navigation>` -- if the goal is providing within-product page-level navigation, use Navigation; Navigator is strictly for switching between separate Watermark products and logging out, not for navigating between pages within a single product.
+- `<wm-action-menu>` -- if a general-purpose dropdown menu of actions is needed in a non-platform context, use Action Menu; Navigator's structure and data model are specific to Watermark's platform architecture.
+
+---
+
+## Accessibility
+
+- Loading product data automatically from the user info endpoint: when the platform's /platform/navigator/userinfo endpoint is available, use load-from-userinfo="true" to fetch product and permission data automatically; only user-name is required in this mode.
+- Passing product data manually as props: when the userinfo endpoint is not available or the product list needs to be controlled at the application level, pass the permitted products explicitly via the products property.
+- Handling logout within the application: when the application needs to control logout behavior (e.g., clearing local state), omit logout-url and listen to the wmNavigatorLogout event to handle it in a callback rather than letting the component redirect directly.
+- Omitting auth-type when SAML authentication is in use: auth-type determines whether the component redirects to link_url or saml_link_url for each product; leaving it unset when SAML is in use will route users to the wrong URL.
+
+---
+
+## Variants / Types
+
+_None documented_
+
+---
+
+## Props
+
+- `userName` -- the authenticated user's display name; required in load-from-userinfo mode
+- `email` -- the authenticated user's email address
+- `loadFromUserinfo` -- when true, fetches product and permission data automatically from the platform userinfo endpoint
+- `products` -- the list of products the user has access to; passed as an array or stringified JSON
+- `authType` -- determines whether product links use link_url or saml_link_url
+- `connectionName` -- the SAML connection name
+- `logoutUrl` -- the URL to redirect to after logout; omit and listen to wmNavigatorLogout instead if cleanup is needed
+
+---
+
+## Events
+
+- `wmNavigatorLogout` -- fires when the user activates the logout option
+
+---
+
+## Methods
+
+- _None exposed_
+
+---
+
+## Code Example
+
+*(to be filled in by developer)*

package/dist/docs/wm-nested-select.md

@@ -0,0 +1,107 @@
+# `wm-nested-select`
+
+Dropdown list of grouped options that allows single or multi-select. Like wm-select but
+options are organized into labeled categories via a two-level hierarchy. Composed of a
+parent wm-nested-select, one or more wm-optgroup children, and wm-option elements inside
+each group.
+
+## Props
+
+| Name | Attribute | Type | Default | Required | Description |
+| ---- | --------- | ---- | ------- | -------- | ----------- |
+| `allSelectedMessage` | `all-selected-message` | `string` | `selectMessages.allSelected` |  |  |
+| `disabled` | `disabled` | `boolean` | `false` |  |  |
+| `errorMessage` | `error-message` | `string \| undefined` |  |  |  |
+| `label` | `label` | `string \| undefined` |  |  |  |
+| `labelPosition` | `label-position` | `"left" \| "none" \| "top"` | `"top"` |  |  |
+| `maxHeight` | `max-height` | `string` | `"200px"` |  |  |
+| `multiple` | `multiple` | `boolean` | `false` |  |  |
+| `placeholder` | `placeholder` | `string` | `this.multiple ? selectMessages.multiPlaceholder : selectMessages.singlePlaceholder` |  |  |
+| `requiredField` | `required-field` | `boolean` | `false` |  |  |
+| `search` | `search` | `boolean` | `false` |  |  |
+| `searchPlaceholder` | `search-placeholder` | `string` | `selectMessages.searchPlaceholder` |  |  |
+| `selectAll` | `select-all` | `boolean` | `false` |  |  |
+
+## Events
+
+| Event | Detail | Bubbles | Description |
+| ----- | ------ | ------- | ----------- |
+| `wmNestedSelectBlurred` | `void` | ✓ |  |
+
+# wm-nested-select
+
+## Purpose
+
+A two-level dropdown that lets users select one or more options from a categorized list, first choosing a group and then picking from the options within it.
+
+---
+
+## When to Use
+
+- **Selecting from options that naturally belong to categories** -- when the option set has a clear parent-child structure (e.g., selecting a course within a department, or a metric within a reporting area), use Nested Select so users can orient by category before scanning a shorter list of relevant options.
+- **Reducing cognitive load on a large, mixed option set** -- when a flat list of options would be long and hard to scan, use Nested Select to break it into groups that users can navigate one level at a time.
+- **Allowing multi-selection within a categorized set** -- when users need to pick multiple values from a grouped list, use the multiple property, optionally combined with select-all per group to allow bulk selection within a category.
+- **Making a categorized list searchable** -- when the full option set is large enough that browsing groups still is not enough, use the search property to let users filter across all groups by typing.
+
+---
+
+## Do Not Use For
+
+- **Options that are not genuinely hierarchical** -- if the options are a single flat list, use wm-select instead; forcing a group wrapper onto non-hierarchical data adds a navigation step with no benefit.
+- **Triggering an action rather than setting a value** -- if selecting an option should immediately execute something rather than record a choice, use wm-action-menu with the selector type instead.
+- **Deeply nested data (more than two levels)** -- the component supports exactly one level of grouping; if the data has sub-groups within groups, Nested Select cannot model it and a different pattern is needed.
+
+---
+
+## Related Components
+
+- `<wm-select>` -- if the options are a single flat list with no categories, use Select; Nested Select is only warranted when options have a genuine two-level group structure.
+- `<wm-action-menu>` (selector type) -- if picking from the list triggers an action rather than sets a value, use Action Menu's selector type; Nested Select is for value selection only.
+
+---
+
+## Accessibility
+
+_Not documented_
+
+---
+
+## Variants / Types
+
+_None documented_
+
+---
+
+## Props
+
+- `label` -- required even when label-position="none"; screen readers use this as the accessible name
+- `labelPosition` -- "top", "left", or "none"
+- `multiple` -- enables multi-selection within the grouped list
+- `selectAll` -- adds a bulk-select control per group; intended for use with multiple
+- `search` -- adds a type-ahead search field to filter across all groups and options
+- `searchPlaceholder` -- placeholder text for the search input
+- `placeholder` -- placeholder text shown in the trigger when no value is selected
+- `allSelectedMessage` -- message shown in the trigger when all options are selected
+- `errorMessage` -- validation error text displayed below the control
+- `requiredField` -- marks the field as required
+- `disabled` -- disables the control and prevents interaction
+- `maxHeight` -- sets the max height of the open dropdown panel
+- `constrainedMaxHeight` -- constrains the max height in contexts with limited space
+
+---
+
+## Events
+
+- `wmNestedSelectBlurred` -- fires when the control loses focus
+
+---
+
+## Methods
+
+- _None exposed_
+
+---
+
+## Code Example
+
+*(to be filled in by developer)*

package/dist/docs/wm-optgroup.md

@@ -0,0 +1,28 @@
+# `wm-optgroup`
+
+Named group of wm-option elements used inside wm-nested-select. Renders as a slide-in
+panel that appears when the user selects the group from the top-level menu.
+
+## Props
+
+| Name | Attribute | Type | Default | Required | Description |
+| ---- | --------- | ---- | ------- | -------- | ----------- |
+| `disabled` | `disabled` | `boolean` | `false` |  |  |
+| `label` | `label` | `string` |  | ✓ |  |
+
+## Events
+
+| Event | Detail | Bubbles | Description |
+| ----- | ------ | ------- | ----------- |
+| `wmOptgroupAllDeselected` | `any` | ✓ |  |
+| `wmOptgroupAllSelected` | `any` | ✓ |  |
+
+## Methods
+
+### `emitDeselection() => Promise<void>`
+
+**Returns** `Promise<void>` -- `Promise<void>`
+
+## Depends On
+
+- `priv-option-list`

package/dist/docs/wm-option.md

@@ -0,0 +1,24 @@
+# `wm-option`
+
+Individual selectable item used inside wm-select, wm-nested-select (via wm-optgroup), and
+wm-optgroup. Renders as a listbox option with optional secondary text.
+
+## Props
+
+| Name | Attribute | Type | Default | Required | Description |
+| ---- | --------- | ---- | ------- | -------- | ----------- |
+| `disabled` | `disabled` | `boolean` | `false` |  |  |
+| `selected` | `selected` | `boolean` | `false` |  |  |
+| `subinfo` | `subinfo` | `string \| undefined` | `undefined` |  |  |
+| `value` | `value` | `null \| string \| undefined` |  |  |  |
+
+## Events
+
+| Event | Detail | Bubbles | Description |
+| ----- | ------ | ------- | ----------- |
+| `wmOptionDeselected` | `HTMLWmOptionElement` | ✓ |  |
+| `wmOptionSelected` | `HTMLWmOptionElement` | ✓ |  |
+
+## Used By
+
+- `priv-option-list`

package/dist/docs/wm-pagination.md

@@ -0,0 +1,94 @@
+# `wm-pagination`
+
+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.
+
+## Props
+
+| Name | Attribute | Type | Default | Required | Description |
+| ---- | --------- | ---- | ------- | -------- | ----------- |
+| `currentPage` | `current-page` | `number` | `1` |  |  |
+| `itemsPerPage` | `items-per-page` | `number \| undefined` | `undefined` |  |  |
+| `label` | `label` | `string` | `""` |  |  |
+| `totalItems` | `total-items` | `number \| undefined` | `undefined` |  |  |
+| `value` | `value` | `number` | `1` |  |  |
+
+## Events
+
+| Event | Detail | Bubbles | Description |
+| ----- | ------ | ------- | ----------- |
+| `wmPaginationPageClicked` | `string` | ✓ |  |
+
+# wm-pagination
+
+## Purpose
+
+A navigation control that lets users move through a large dataset split across discrete pages, emitting events the application uses to load and display the correct slice of data for the selected page.
+
+---
+
+## When to Use
+
+- **Breaking a large dataset into discrete pages** -- when a table, list, or grid contains too many items to display at once and the application loads them in chunks, use Pagination to give users explicit control over which page they're viewing.
+- **Displaying multiple independent paginated datasets on the same page** -- when a page contains more than one paginated section, use the label property on each Pagination instance to give each a distinct accessible name (e.g., "Students pagination" vs. "Courses pagination").
+
+---
+
+## Do Not Use For
+
+- **In-page section or tab switching** -- Pagination is for moving through chunks of a dataset, not for switching between views or content sections; use wm-tabs for tab-style content switching within a page.
+- **Small datasets that can be displayed in full** -- if all items can be reasonably displayed at once without performance or usability concerns, Pagination adds unnecessary navigation overhead; only paginate when the volume genuinely warrants it.
+- **Sequential multi-step workflows** -- if the user is progressing through ordered steps that must be completed in sequence, use a stepper pattern instead; Pagination implies unrestricted movement between any page in any order.
+
+---
+
+## Related Components
+
+- `<wm-tabs>` -- if the goal is switching between distinct content views or sections within a page rather than moving through pages of a dataset, use Tabs; Pagination is specifically for dataset paging, not view switching.
+- `<wm-search>` -- if the goal is reducing a large dataset by filtering rather than paging through it, use Search or other filter inputs; filtering reduces the set, paging navigates it.
+- Stepper pattern -- if users are progressing through ordered steps that must be completed sequentially, use a stepper rather than Pagination; Pagination implies unrestricted movement between any page in any order.
+
+---
+
+## Accessibility
+
+- Synchronizing the component with application state: because the component is stateless (it emits page-click events and reflects whatever current-page is passed to it), use it whenever the application controls paging state externally, updating current-page in response to wmPaginationPageClicked.
+- Not updating current-page in response to the event: the component is stateless and relies entirely on the application to update current-page after each click; failing to do so will leave the component out of sync with the displayed data.
+
+---
+
+## Variants / Types
+
+- `is-large-size="true"` -- larger display with more prominent page numbers
+- `is-large-size="false" (default)` -- compact display
+
+---
+
+## Props
+
+- `label` -- the accessible name for the pagination navigation landmark; defaults to "Pagination navigation". Customize when multiple Pagination instances appear on the same page.
+- `currentPage` -- the currently active page number; must be updated by the application in response to wmPaginationPageClicked
+- `value` -- alias for currentPage
+- `totalItems` -- the total number of items in the dataset
+- `itemsPerPage` -- the number of items displayed per page
+- `isLargeSize` -- when true, renders the larger display variant
+
+---
+
+## Events
+
+- `wmPaginationPageClicked` -- fires when the user clicks any page number or previous/next; detail is a string with the selected page number
+- `focusCurrentPage` -- fires to programmatically move focus to the current page button
+
+---
+
+## Methods
+
+- _None exposed_
+
+---
+
+## Code Example
+
+*(to be filled in by developer)*

package/dist/docs/wm-progress-indicator.md

@@ -0,0 +1,23 @@
+# `wm-progress-indicator`
+
+Single progress indicator used inside a wm-progress-monitor. Renders the binary completion
+data for one category as either a doughnut chart (wide layout) or a horizontal bar (narrow
+layout), switching automatically based on the parent monitor's breakpoint.
+
+Must contain EXACTLY TWO wm-progress-slice children -- one for the "complete" state and one
+for the "incomplete" state.
+
+## Props
+
+| Name | Attribute | Type | Default | Required | Description |
+| ---- | --------- | ---- | ------- | -------- | ----------- |
+| `completionMessage` | `completion-message` | `string \| undefined` |  |  |  |
+| `label` | `label` | `string \| undefined` |  |  |  |
+| `printMode` | `print-mode` | `boolean` | `false` |  |  |
+| `printModeFormat` | `print-mode-format` | `"amount" \| "percentage"` | `"amount"` |  |  |
+| `showLegend` | `show-legend` | `boolean` | `true` |  |  |
+| `subinfo` | `subinfo` | `string \| undefined` |  |  |  |
+
+## Depends On
+
+- `priv-chart-popover-old`