@watermarkinsights/ripple 0.0.1 → 0.1.0-alpha.1

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

@@ -0,0 +1,61 @@
+### Navigation Hamburger
+- **Element:** `<wm-navigation-hamburger>`
+
+**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_
+
+**Usage notes:**
+
+- `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.
+
+**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. _(required)_
+
+**Events:**
+- `wmNavigationHamburgerClicked` -- Fires when the button is clicked. Consumed by the associated wm-navigation
+to toggle its `open` state -- not intended for direct application use.
+
+**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,78 @@
+### Navigation Item
+- **Element:** `<wm-navigation-item>`
+
+**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_
+
+**Usage notes:**
+
+- 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.
+
+**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.
+
+**Slots:**
+- _(default)_ -- Optional icon element displayed before the link text.
+
+**Events:**
+- `wmNavigationItemClicked` -- Fires when the link is clicked. Consumed by the parent wm-navigation to
+close the collapsible menu on narrow viewports.
+
+**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,82 @@
+### Navigation
+- **Element:** `<wm-navigation>`
+
+**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_
+
+**Usage notes:**
+
+- 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.
+
+**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. _(default: `false`)_
+
+**Slots:**
+- _(default)_ -- One or more wm-navigation-item elements.
+
+**Events:**
+- `wmNavigationStateChanged` -- Fires when the collapsible navigation opens or closes. Consumed by
+wm-navigation-hamburger to keep its `aria-expanded` state in sync.
+
+**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,106 @@
+### Navigator
+- **Element:** `<wm-navigator>`
+
+**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_
+
+**Usage notes:**
+
+- 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.
+
+**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; default: `1`)_
+- `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. _(default: `false`)_
+- `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. _(type: `[] | string`)_
+- `user-name` -- The display name of the logged-in user, shown in the menu header. _(required)_
+
+**Events:**
+- `wmNavigatorLogout` -- 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.
+
+**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,160 @@
+### Nested Select
+- **Element:** `<wm-nested-select>`
+
+**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_
+
+**Usage notes:**
+
+- Selection state is maintained via the `selected` prop on each wm-option child.
+- To respond to selection changes, listen for `wmOptionSelected` (declared on wm-option but
+  bubbles to wm-nested-select). `event.detail` is the `HTMLWmOptionElement`; read `.value`
+  or `.textContent` to get the selected value.
+- `select-all` adds a "Select All / Deselect All" toggle at the top of each group; it
+  requires `multiple` to be set.
+- `search` filters options within the currently open group only.
+
+**Props:**
+- `all-selected-message` -- Text displayed in the trigger button when all options across all groups are
+selected (multiselect mode). _(default: `selectMessages.allSelected`)_
+- `disabled` -- Disables the entire nested select component, preventing any interaction. _(default: `false`)_
+- `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. _(required)_
+- `label-position` -- Controls where the label is rendered relative to the dropdown button.
+`"none"` hides the label visually but keeps it accessible. _(type: `"left" | "none" | "top"`; default: `"top"`)_
+- `max-height` -- Overrides the maximum height of the options dropdown. Accepts any valid CSS
+length value (e.g. `"300px"`). _(default: `"200px"`)_
+- `multiple` -- Enables multiselect mode, allowing more than one option to be selected at
+a time. _(default: `false`)_
+- `placeholder` -- Text displayed in the trigger button when no options are selected. _(default: `this.multiple ? selectMessages.multiPlaceholder : selectMessages.singlePlaceholder`)_
+- `required-field` -- Renders a required-field asterisk (*) next to the label. _(default: `false`)_
+- `search` -- Adds a search input that filters visible options within the currently open
+group. _(default: `false`)_
+- `search-placeholder` -- Placeholder text displayed inside the search input when `search` is enabled. _(default: `selectMessages.searchPlaceholder`)_
+- `select-all` -- Adds a "Select All / Deselect All" toggle at the top of each group. Requires
+`multiple` to be set. _(default: `false`)_
+
+**Events:**
+- `wmNestedSelectBlurred` -- Fires when focus leaves the component entirely (not when moving between
+internal elements such as options or group buttons).
+
+**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,72 @@
+### Optgroup
+- **Element:** `<wm-optgroup>`
+
+**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.
+
+**Usage notes:**
+
+- 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. _(default: `false`)_
+- `label` -- Display name for this group, shown as the group button text in the
+dropdown menu. _(required)_
+
+**Events:**
+- `wmOptgroupAllDeselected` -- Fires when the "Deselect All" button inside this group is activated.
+- `wmOptgroupAllSelected` -- Fires when the "Select All" button inside this group is activated.
+
+**Methods:**
+- `emitDeselection() => Promise<void>` -- Programmatically deselects all options in this group by emitting
+`wmOptgroupAllDeselected`.
+  - **Returns:** `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>
+```

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

@@ -0,0 +1,67 @@
+### Option
+- **Element:** `<wm-option>`
+
+**Purpose:** 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.
+
+**Usage notes:**
+
+- Text content is supplied as the element's text node (slot content). Do not nest other
+  elements inside wm-option.
+- Set the `selected` attribute/prop to pre-select an option on load.
+- In single-select mode, exactly one wm-option should be pre-selected (typically a
+  placeholder). In multi-select mode, zero or more options may be pre-selected.
+- The `value` prop is a pass-through convenience for application code to attach an
+  identifier; the component itself never reads or mutates it.
+
+**Props:**
+- `disabled` -- Prevents the option from being selected. _(default: `false`)_
+- `selected` -- Marks this option as currently selected. _(default: `false`)_
+- `subinfo` -- Secondary text displayed beneath the option label.
+- `value` -- Application-defined identifier for this option. The component never reads
+or modifies this value -- it is purely a pass-through for application code to attach an ID
+or key. _(type: `null | string`)_
+
+**Events:**
+- `wmOptionDeselected` -- Fires when this option is deselected by the user (multiselect mode only). Detail: ``HTMLWmOptionElement` -- the option element that was deselected.`
+- `wmOptionSelected` -- Fires when this option is selected by the user. Detail: ``HTMLWmOptionElement` -- the option element that was selected.`
+
+**Code example:**
+
+_Basic option usage_
+
+```html
+<wm-select label="Status">
+<wm-option selected>Select a status</wm-option>
+<wm-option value="active">Active</wm-option>
+<wm-option value="inactive">Inactive</wm-option>
+</wm-select>
+```
+
+_Basic option usage_
+
+```react
+<WmSelect label="Status">
+<WmOption selected={true}>Select a status</WmOption>
+<WmOption value="active">Active</WmOption>
+<WmOption value="inactive">Inactive</WmOption>
+</WmSelect>
+```
+
+_Option with subinfo_
+
+```html
+<wm-select label="User" multiple>
+<wm-option subinfo="Biology dept">Alice</wm-option>
+<wm-option subinfo="Chemistry dept">Bob</wm-option>
+</wm-select>
+```
+
+_Option with subinfo_
+
+```react
+<WmSelect label="User" multiple={true}>
+<WmOption subinfo="Biology dept">Alice</WmOption>
+<WmOption subinfo="Chemistry dept">Bob</WmOption>
+</WmSelect>
+```