@watermarkinsights/ripple 5.30.0 → 5.31.0-alpha.1

package/dist/docs/skill/wm-modal.md

@@ -0,0 +1,137 @@
+### Modal
+- **Element:** `<wm-modal>`
+- **Status:** stable
+
+**Purpose:** 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.
+
+**When to use:**
+
+- **Collecting or editing a focused set of information** -- when a user needs to fill out a short form or make a confined set of edits that must be completed or explicitly dismissed before anything else can happen, Modal creates the necessary interruption and focus.
+- **Confirming a consequential or destructive action** -- when the user has initiated something that warrants deliberate confirmation (such as permanently deleting a record), use Modal with deleteStyle on the footer to signal danger and require an explicit choice before proceeding.
+- **Running a short sequential workflow** -- when a task can be broken into a small number of steps using a stepper, Modal can host that progression, provided the workflow is compact enough that a full-page view is not warranted.
+- **Triggering a secondary confirmation from a primary action** -- a Modal's primary action can open an additional Modal, so a two-stage confirmation (e.g., submit then confirm submission) is a supported and appropriate use.
+
+**Do not use for:**
+
+- **Content that is too large for a centered overlay** -- if there is too much content to display comfortably, use a Flyout or light immersive view instead; Modal is not designed to host expansive content.
+- **More than one primary action** -- if more than one distinct action can be taken, break the workflow into separate Modals or reconsider the pattern entirely.
+- **Launching a Flyout or side panel from within a Modal** -- stacking containers at this level breaks user orientation and focus management.
+
+**Variants / types:**
+
+- `modal-type="modal"` -- full overlay for task completion with forms and richer content
+- `modal-type="dialog"` -- lighter variant for simpler, message-style interactions
+
+**Props:**
+- `element-to-focus` -- 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.
+- `modal-type` -- Visual presentation style. `'modal'` renders a full-bleed overlay; `'dialog'`
+renders a smaller centered panel.
+- `open` -- Controls the open/closed state of the modal. Always render the component and
+toggle this prop -- do not conditionally mount/unmount.
+- `uid` -- 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. _(required)_
+
+**Events:**
+- `wmModalCloseTriggered`
+- `wmModalPrimaryTriggered`
+- `wmModalSecondaryTriggered`
+
+**Methods:**
+- `emitCloseEvent() => Promise<void>`
+- `emitPrimaryEvent() => Promise<void>`
+- `emitSecondaryEvent() => Promise<void>`
+
+**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.
+- **Keyboard:** - **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.
+
+**Related components:**
+
+- Dialog (modal-type="dialog") -- Dialog is the lighter variant of the same component, intended for simpler message-style interactions; Modal is for task completion with forms and richer content.
+- `<wm-flyout>` -- if the task is longer, benefits from more horizontal space, or should coexist alongside the underlying page rather than block it entirely, use Flyout; Modal is for short, blocking, self-contained tasks.
+- Light Immersive Layout -- if the workflow is too complex or content-heavy for a Modal, escalate to a light immersive view; Modal is not suited to multi-faceted or lengthy workflows.
+
+**Code example:**
+
+_Basic modal_
+
+```html
+<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>
+```
+
+_Basic modal_
+
+```react
+// 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 onWmButtonClicked={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>
+```
+
+_Dialog type (smaller, centered)_
+
+```html
+<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>
+```
+
+_Dialog type_
+
+```react
+const dialogRef = useRef(null);
+
+const openDialog = () => { dialogRef.current.open = true; };
+const closeDialog = () => { dialogRef.current.open = false; };
+
+<WmButton onWmButtonClicked={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>
+```

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

@@ -0,0 +1,56 @@
+### Navigation Hamburger
+- **Element:** `<wm-navigation-hamburger>`
+- **Status:** stable
+
+**Purpose:** 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.
+
+**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.
+
+**Variants / types:**
+
+_None documented_
+
+**Props:**
+- `nav-id` -- 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.
+
+**Events:**
+- `wmNavigationHamburgerClicked`
+
+**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.
+- **Keyboard:** - **Enter / Space**: Toggles the navigation open/closed.
+
+**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.
+
+**Code example:**
+
+_Basic hamburger_
+
+```html
+<wm-navigation-hamburger nav-id="main-nav"></wm-navigation-hamburger>
+<wm-navigation id="main-nav">...</wm-navigation>
+```
+
+_Basic hamburger_
+
+```react
+<WmNavigationHamburger navId="main-nav" />
+<WmNavigation id="main-nav">...</WmNavigation>
+```

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

@@ -0,0 +1,69 @@
+### Navigation Item
+- **Element:** `<wm-navigation-item>`
+- **Status:** stable
+
+**Purpose:** 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.
+
+**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.
+
+**Variants / types:**
+
+_None documented_
+
+**Props:**
+- `active` -- Marks this item as the currently active route, applying active styling.
+- `href` -- URL the link navigates to.
+- `text` -- The visible label text for the navigation link.
+
+**Events:**
+- `wmNavigationItemClicked`
+
+**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.
+
+**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.
+
+**Code example:**
+
+_Basic navigation item_
+
+```html
+<wm-navigation-item href="/dashboard" text="Dashboard" active></wm-navigation-item>
+```
+
+_Basic navigation item_
+
+```react
+<WmNavigationItem href="/dashboard" text="Dashboard" active={true} />
+```
+
+_Navigation item with icon_
+
+```html
+<wm-navigation-item href="/reports" text="Reports">
+<span class="svg-icon svg-chart"></span>
+</wm-navigation-item>
+```
+
+_Navigation item with icon_
+
+```react
+<WmNavigationItem href="/reports" text="Reports">
+<span className="svg-icon svg-chart" />
+</WmNavigationItem>
+```

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

@@ -0,0 +1,66 @@
+### Navigation
+- **Element:** `<wm-navigation>`
+- **Status:** stable
+
+**Purpose:** 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>`.
+
+**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.
+
+**Variants / types:**
+
+_None documented_
+
+**Props:**
+- `open` -- Controls the open/closed state of the collapsible navigation. Has no effect
+on viewports wider than 1024px where the navigation is always visible.
+
+**Events:**
+- `wmNavigationStateChanged`
+
+**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`.
+- **Keyboard:** - **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).
+
+**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.
+
+**Code example:**
+
+_Basic navigation_
+
+```html
+<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>
+```
+
+_Basic navigation_
+
+```react
+<WmNavigationHamburger navId="main-nav" />
+<WmNavigation id="main-nav">
+<WmNavigationItem href="/dashboard" text="Dashboard" active={true} />
+<WmNavigationItem href="/reports" text="Reports" />
+</WmNavigation>
+```

package/dist/docs/skill/wm-navigator.md

@@ -0,0 +1,91 @@
+### Navigator
+- **Element:** `<wm-navigator>`
+- **Status:** stable
+
+**Purpose:** 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.
+
+**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.
+
+**Variants / types:**
+
+_None documented_
+
+**Props:**
+- `auth-type` -- 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`). _(conditionally required: when load-from-userinfo is false and products are provided)_
+- `connection-name` -- SAML connection name appended as a query parameter to product redirect URLs.
+Only used when `auth-type` is `3`.
+- `email` -- The email address of the logged-in user, shown in the menu header. _(conditionally required: when load-from-userinfo is false)_
+- `load-from-userinfo` -- When true, fetches user info and products automatically from the
+`/platform/navigator/userinfo` endpoint instead of using props.
+- `logout-url` -- URL to redirect to after logout. If omitted, no redirect occurs -- handle
+navigation entirely in the `wmNavigatorLogout` event handler.
+- `products` -- 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.
+- `user-name` -- The display name of the logged-in user, shown in the menu header.
+
+**Events:**
+- `wmNavigatorLogout`
+
+**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.
+- **Keyboard:** - **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.
+
+**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.
+
+**Code example:**
+
+_Prop mode_
+
+```html
+<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>
+```
+
+_Prop mode_
+
+```react
+<WmNavigator
+userName="Maria Garcia"
+email="m.garcia@example.com"
+authType={2}
+logoutUrl="https://app.watermarkinsights.com/logout"
+products={JSON.stringify(products)}
+onWmNavigatorLogout={handleLogout} />
+```
+
+_Endpoint mode (fetches user info automatically)_
+
+```html
+<wm-navigator user-name="Maria Garcia" load-from-userinfo="true"></wm-navigator>
+```
+
+_Endpoint mode_
+
+```react
+<WmNavigator userName="Maria Garcia" loadFromUserinfo={true} onWmNavigatorLogout={handleLogout} />
+```

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

@@ -0,0 +1,149 @@
+### Nested Select
+- **Element:** `<wm-nested-select>`
+- **Status:** stable
+
+**Purpose:** 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.
+
+**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.
+
+**Variants / types:**
+
+_None documented_
+
+**Props:**
+- `all-selected-message` -- Text displayed in the trigger button when all options across all groups are
+selected (multiselect mode).
+- `disabled` -- Disables the entire nested select component, preventing any interaction.
+- `error-message` -- Displays the component in an error state with the provided message shown
+beneath the button.
+- `label` -- Accessible label describing the dropdown's purpose. Required even when
+`label-position` is `"none"` -- it is used as the ARIA accessible name for the button.
+- `label-position` -- Controls where the label is rendered relative to the dropdown button.
+`"none"` hides the label visually but keeps it accessible.
+- `max-height` -- Overrides the maximum height of the options dropdown. Accepts any valid CSS
+length value (e.g. `"300px"`).
+- `multiple` -- Enables multiselect mode, allowing more than one option to be selected at
+a time.
+- `placeholder` -- Text displayed in the trigger button when no options are selected.
+- `required-field` -- Renders a required-field asterisk (*) next to the label.
+- `search` -- Adds a search input that filters visible options within the currently open
+group.
+- `search-placeholder` -- Placeholder text displayed inside the search input when `search` is enabled.
+- `select-all` -- Adds a "Select All / Deselect All" toggle at the top of each group. Requires
+`multiple` to be set.
+
+**Events:**
+- `wmNestedSelectBlurred`
+
+**Accessibility:**
+
+- `label` is required even when `label-position` is `"none"` -- it is used as the dropdown's
+  ARIA accessible name.
+- Group buttons render with `role="menuitem"` inside a `role="menu"`. The option level
+  renders as a `role="listbox"` with `role="option"` items.
+- Validation errors are announced via an `aria-live` region when `error-message` changes.
+- **Keyboard:** - **Closed button**: Space / Enter / Arrow Down opens the dropdown and focuses the first
+  group; Arrow Up opens and focuses the last group.
+- **Group level**: Arrow Up / Down navigate group buttons; Arrow Right / Enter enters the
+  group; Escape closes the dropdown.
+- **Option level (inside a group)**: Arrow Up / Down navigate options; Arrow Left returns
+  to the group list; Home / End jump to first / last option; typing a letter jumps to the
+  first matching option.
+- **Tab** (anywhere in dropdown): Closes the dropdown.
+
+**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.
+
+**Code example:**
+
+_Single-select nested select_
+
+```html
+<wm-nested-select label="Department">
+<wm-optgroup label="Sciences">
+<wm-option selected>Select a department</wm-option>
+<wm-option>Biology</wm-option>
+</wm-optgroup>
+<wm-optgroup label="Humanities">
+<wm-option>English</wm-option>
+</wm-optgroup>
+</wm-nested-select>
+```
+
+_Single-select nested select_
+
+```react
+const [department, setDepartment] = useState('');
+
+// event.detail is the selected HTMLWmOptionElement
+const handleSelect = (event) => {
+setDepartment(event.detail.value ?? event.detail.textContent);
+};
+
+<WmNestedSelect label="Department" onWmOptionSelected={handleSelect}>
+<WmOptgroup label="Sciences">
+<WmOption selected>Select a department</WmOption>
+<WmOption value="bio">Biology</WmOption>
+</WmOptgroup>
+<WmOptgroup label="Humanities">
+<WmOption value="eng">English</WmOption>
+</WmOptgroup>
+</WmNestedSelect>
+```
+
+_Multi-select with Select All_
+
+```html
+<wm-nested-select label="Programs" multiple select-all>
+<wm-optgroup label="Sciences">
+<wm-option value="bio">Biology</wm-option>
+<wm-option value="chem">Chemistry</wm-option>
+</wm-optgroup>
+</wm-nested-select>
+```
+
+_Multi-select with Select All_
+
+```react
+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));
+};
+
+<WmNestedSelect
+label="Programs"
+multiple={true}
+selectAll={true}
+onWmOptionSelected={handleSelect}
+onWmOptionDeselected={handleDeselect}
+>
+<WmOptgroup label="Sciences">
+<WmOption value="bio">Biology</WmOption>
+<WmOption value="chem">Chemistry</WmOption>
+</WmOptgroup>
+</WmNestedSelect>
+```

package/dist/docs/skill/wm-optgroup.md

@@ -0,0 +1,71 @@
+### Optgroup
+- **Element:** `<wm-optgroup>`
+- **Status:** stable
+
+**Purpose:** 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.
+
+**Variants / types:**
+
+- Always used as a direct child of wm-nested-select.
+- `label` is required -- it is shown as the group heading in the dropdown menu.
+- The `disabled` prop prevents the group button from being clicked, hiding all its options.
+- `wmOptgroupAllSelected` and `wmOptgroupAllDeselected` are fired when the "Select All /
+  Deselect All" button inside the group is activated; they bubble to wm-nested-select.
+
+**Props:**
+- `disabled` -- Disables this group, preventing the user from opening it or selecting any
+of its options.
+- `label` -- Display name for this group, shown as the group button text in the
+dropdown menu. _(required)_
+
+**Events:**
+- `wmOptgroupAllDeselected`
+- `wmOptgroupAllSelected`
+
+**Methods:**
+- `emitDeselection() => Promise<void>`
+
+**Code example:**
+
+_Optgroup inside nested select_
+
+```html
+<wm-nested-select label="Department">
+<wm-optgroup label="Sciences">
+<wm-option selected>Select a department</wm-option>
+<wm-option>Biology</wm-option>
+</wm-optgroup>
+</wm-nested-select>
+```
+
+_Optgroup inside nested select_
+
+```react
+<WmNestedSelect label="Department">
+<WmOptgroup label="Sciences">
+<WmOption selected={true}>Select a department</WmOption>
+<WmOption>Biology</WmOption>
+</WmOptgroup>
+</WmNestedSelect>
+```
+
+_Disabled optgroup_
+
+```html
+<wm-nested-select label="Program">
+<wm-optgroup label="Sciences" disabled>
+<wm-option>Biology</wm-option>
+</wm-optgroup>
+</wm-nested-select>
+```
+
+_Disabled optgroup_
+
+```react
+<WmNestedSelect label="Program">
+<WmOptgroup label="Sciences" disabled={true}>
+<WmOption>Biology</WmOption>
+</WmOptgroup>
+</WmNestedSelect>
+```