@watermarkinsights/ripple 5.30.0 → 5.31.0-alpha.1

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

@@ -0,0 +1,68 @@
+### Option
+- **Element:** `<wm-option>`
+- **Status:** stable
+
+**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.
+
+**Variants / types:**
+
+- 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.
+- `selected` -- Marks this option as currently selected.
+- `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.
+
+**Events:**
+- `wmOptionDeselected`
+- `wmOptionSelected`
+
+**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>
+```

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

@@ -0,0 +1,95 @@
+### Pagination
+- **Element:** `<wm-pagination>`
+- **Status:** stable
+
+**Purpose:** 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.
+
+**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.
+
+**Variants / types:**
+
+- `is-large-size="true"` -- larger display with more prominent page numbers
+- `is-large-size="false" (default)` -- compact display
+
+**Props:**
+- `current-page` -- The currently active page number. Update this prop in response to
+`wmPaginationPageClicked` to keep the component in sync with your data.
+- `items-per-page` -- Number of items displayed per page. Used with `total-items` to calculate
+the total page count.
+- `label` -- Accessible label for the `<nav>` element. Defaults to `"Pagination navigation"`.
+Override when multiple pagination instances appear on the same page (e.g. `"Search results"`).
+- `total-items` -- Total number of items across all pages. Used with `items-per-page` to
+calculate the total page count.
+- `value` -- The page number selected by the most recent user interaction. Read
+`event.target.value` in the `wmPaginationPageClicked` handler to get the selected page.
+
+**Events:**
+- `wmPaginationPageClicked`
+
+**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"`.
+
+**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.
+
+**Code example:**
+
+_Basic pagination_
+
+```html
+<wm-pagination current-page="1" total-items="150" items-per-page="25"></wm-pagination>
+```
+
+_Basic pagination_
+
+```react
+// 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))} />
+```
+
+_With accessible label_
+
+```html
+<wm-pagination label="Search results" current-page="1" total-items="80" items-per-page="10">
+</wm-pagination>
+```
+
+_Multiple instances with independent state_
+
+```react
+// 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))} />
+```

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

@@ -0,0 +1,49 @@
+### Progress Indicator
+- **Element:** `<wm-progress-indicator>`
+- **Status:** stable
+
+**Purpose:** 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.
+
+**Variants / types:**
+
+- Always used as a direct child of wm-progress-monitor.
+- `label` is required for accessibility.
+- The optional `completion-message` is displayed inside the doughnut when the first slice
+  reaches 100%.
+
+**Props:**
+- `completion-message` -- Text displayed inside the doughnut ring when the completion slice reaches
+100%.
+- `label` -- Accessible label for this indicator. Required for accessibility -- used as the
+`aria-label` on the chart container and as the visual chart label.
+- `print-mode` -- When true, slice values are included in the legend and keyboard interaction
+instructions are removed from the DOM -- suitable for printed output.
+- `print-mode-format` -- Format for legend values when `print-mode` is enabled.
+- `show-legend` -- Show or hide the legend. The legend is still read by screen readers
+regardless of this setting.
+- `subinfo` -- Optional secondary text displayed beneath the label.
+
+**Code example:**
+
+_Progress indicator_
+
+```html
+<wm-progress-indicator label="Biology completion">
+<wm-progress-slice legend="Completed" amount="200"></wm-progress-slice>
+<wm-progress-slice legend="Not Completed" amount="100"></wm-progress-slice>
+</wm-progress-indicator>
+```
+
+_Progress indicator_
+
+```react
+<WmProgressIndicator label="Biology completion">
+<WmProgressSlice legend="Completed" amount="200" />
+<WmProgressSlice legend="Not Completed" amount="100" />
+</WmProgressIndicator>
+```

package/dist/docs/skill/wm-progress-monitor.md

@@ -0,0 +1,93 @@
+### Progress Monitor
+- **Element:** `<wm-progress-monitor>`
+- **Status:** stable
+
+**Purpose:** Container for one or more wm-progress-indicator elements, each showing binary completion
+progress (e.g. "Completed" vs "Not Completed"). Above the layout breakpoint, indicators
+render as doughnuts in a horizontal row; below it, they collapse into horizontal bars in a
+vertical stack.
+
+**Strict constraints:**
+1. Each wm-progress-indicator must have EXACTLY TWO wm-progress-slice children -- one for
+   the "complete" state and one for the "incomplete" state.
+2. This component is ONLY suitable for binary completion tracking. For more than two states,
+   general comparisons, composition breakdowns, or distributions, use wm-chart,
+   wm-chart-bar, or wm-chart-column.
+
+**Variants / types:**
+
+- The `wmProgressMonitorModeChange` event fires once on load and again whenever the layout
+  switches between `"doughnut"` and `"bar"`. Listen to it to synchronize any external UI
+  that depends on the current layout mode.
+- `group-legend` is only shown in bar mode. Provide two comma-separated keys in
+  complete/incomplete order (e.g. `"Completed,Not Completed"`). Keys cannot contain commas.
+
+**Props:**
+- `bar-labels-width` -- CSS width of the indicator labels when in bar layout mode (e.g. `"180px"`).
+- `breakpoint` -- Controls when indicators switch between doughnut (horizontal row) and bar
+(vertical stack) layouts. Accepts a unit-less number (minimum number of indicators to
+show side-by-side -- e.g. `4` -> 1200 px) or an exact pixel value (e.g. `"900px"`).
+Defaults to the sum of all indicator widths -- the component tries to fit all on one row
+and collapses to bars when it cannot.
+- `group-legend` -- Two comma-separated legend keys in complete/incomplete order, displayed only
+in bar layout mode (e.g. `"Completed,Not Completed"`). Keys cannot contain commas.
+
+**Events:**
+- `wmProgressMonitorModeChange`
+
+**Code example:**
+
+_Progress monitor_
+
+```html
+<wm-progress-monitor group-legend="Completed,Not Completed">
+<wm-progress-indicator label="Biology">
+<wm-progress-slice legend="Completed" amount="200"
+popover-title="200 students" popover-text="Completed all requirements"></wm-progress-slice>
+<wm-progress-slice legend="Not Completed" amount="100"
+popover-title="100 students" popover-text="Have not completed all requirements"></wm-progress-slice>
+</wm-progress-indicator>
+</wm-progress-monitor>
+```
+
+_Progress monitor_
+
+```react
+// wmProgressMonitorModeChange fires on load and whenever the layout switches.
+// event.detail is "doughnut" | "bar".
+const [layoutMode, setLayoutMode] = useState("");
+
+<WmProgressMonitor
+groupLegend="Completed,Not Completed"
+onWmProgressMonitorModeChange={(e) => setLayoutMode(e.detail)}
+>
+<WmProgressIndicator label="Biology">
+<WmProgressSlice legend="Completed" amount="200"
+popoverTitle="200 students" popoverText="Completed all requirements" />
+<WmProgressSlice legend="Not Completed" amount="100"
+popoverTitle="100 students" popoverText="Have not completed all requirements" />
+</WmProgressIndicator>
+<WmProgressIndicator label="English">
+<WmProgressSlice legend="Completed" amount="160"
+popoverTitle="160 students" popoverText="Completed all requirements" />
+<WmProgressSlice legend="Not Completed" amount="40"
+popoverTitle="40 students" popoverText="Have not completed all requirements" />
+</WmProgressIndicator>
+</WmProgressMonitor>
+```
+
+_Custom breakpoint_
+
+```html
+<wm-progress-monitor breakpoint="600px" group-legend="Done,Pending">
+<!-- indicators -->
+</wm-progress-monitor>
+```
+
+_Custom breakpoint_
+
+```react
+<WmProgressMonitor breakpoint="600px" groupLegend="Done,Pending">
+{/* indicators *\/}
+</WmProgressMonitor>
+```

package/dist/docs/skill/wm-progress-slice.md

@@ -0,0 +1,41 @@
+### Progress Slice
+- **Element:** `<wm-progress-slice>`
+- **Status:** stable
+
+**Purpose:** Data slice for a wm-progress-indicator. Represents one state (complete or incomplete) in
+a binary progress chart. Always used as a direct child of wm-progress-indicator.
+
+Each wm-progress-indicator must contain EXACTLY TWO wm-progress-slice elements.
+
+**Variants / types:**
+
+- The first slice is treated as the "complete" state and the second as the "incomplete"
+  state for color and layout purposes.
+- Use `popover-title`, `popover-text`, and `popover-button-text` to surface additional
+  context when the segment is focused or clicked.
+
+**Props:**
+- `amount` -- Numeric value for this slice as a string.
+- `legend` -- Label for this slice in the legend and popovers.
+- `popover-button-text` -- Label for the action button in the data popover. When set, fires
+`wmProgressIndicatorButtonTriggered` when clicked.
+- `popover-text` -- Body text shown in the data popover when this segment is focused or clicked.
+- `popover-title` -- Title text shown in the data popover when this segment is focused or clicked.
+
+**Code example:**
+
+_Complete/incomplete pair_
+
+```html
+<wm-progress-slice legend="Completed" amount="200"
+popover-title="200 students" popover-text="Completed all requirements"></wm-progress-slice>
+<wm-progress-slice legend="Not Completed" amount="100"></wm-progress-slice>
+```
+
+_Complete/incomplete pair_
+
+```react
+<WmProgressSlice legend="Completed" amount="200"
+popoverTitle="200 students" popoverText="Completed all requirements" />
+<WmProgressSlice legend="Not Completed" amount="100" />
+```

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

@@ -0,0 +1,157 @@
+### Search
+- **Element:** `<wm-search>`
+- **Status:** stable
+
+**Purpose:** Search input for filtering data by query. Two variants: `'basic'` for simple text
+filtering, and `'find'` which adds prev/next result navigation buttons, a result count
+("x of y results"), and a keyboard-accessible "jump to result" link. The component does
+not filter data itself -- it exposes the user's query and result position via events and
+properties for the application to handle.
+
+**When to use:**
+
+- **Instantly filtering a visible dataset as the user types** -- use the basic variant when the user is narrowing down a list, table, or set of cards and expects the content to respond immediately to their query. Ideal for smaller datasets where results update without performance concerns.
+- **Locating and stepping through matches within a page or document** -- when the user needs to jump between individual matches (like a browser's find function), use the find variant, which provides previous/next navigation and an "x of y results" count.
+- **Including search as part of a filter toolbar** -- Search is a valid data input for toolbar and side panel filter patterns when users have a clear idea of what they're looking for and the dataset is large enough that browsing alone is not practical.
+- **Combining search with other filter inputs** -- Search pairs naturally with dropdowns, date pickers, and tag inputs in a toolbar or side panel; it narrows by text while other inputs narrow by category, date, or attribute simultaneously.
+
+**Do not use for:**
+
+- **Collecting a stored form value** -- Search is not a form input; it filters or locates content dynamically. If the user is typing a value to be saved as data (a name, identifier, or description), use wm-input instead.
+- **Very large datasets with the basic variant without considering performance** -- instant filtering for large datasets may cause performance issues; consider a batch-apply approach with an explicit apply action instead.
+- **Exploratory filtering where users do not have a specific target** -- Search is best when the user has a clear idea of what they want; for browsing by category or attribute, dropdowns and selects are more appropriate.
+
+**Variants / types:**
+
+- `search-type="basic"` -- simple filter that updates results in real time as the user types
+- `search-type="find"` -- search-and-find with previous/next result navigation and a result count display; requires num-results, highlighted-id, and highlighted-name to be kept in sync
+
+**Props:**
+- `disabled` -- Disables the input, preventing all interaction.
+- `highlighted-id` -- `id` of the currently highlighted result element. Used as the `href` of the
+jump-to-result skip-link. Required for the `find` variant for full accessibility. _(conditionally required: Required when `search-type="find"`.)_
+- `highlighted-name` -- Visible text of the currently highlighted result. Appended to the screen
+reader announcement after `wmSearchBrowseResults` fires. Required for the `find` variant
+for full accessibility. _(conditionally required: Required when `search-type="find"`.)_
+- `label` -- Accessible label for the `<input>` element. Required even when not visually
+displayed. May match the placeholder text.
+- `num-results` -- Number of results matching the current query. Update this prop after
+filtering to display "x of y results" (find variant) and announce the count to screen
+readers.
+- `placeholder` -- Placeholder text displayed inside the empty input.
+- `search-type` -- Selects the search variant. `'basic'` renders a simple text input with a
+result count. `'find'` adds prev/next navigation buttons and a jump-to-result skip-link.
+- `value` -- The current text typed by the user. Readable by the application at any time.
+
+**Events:**
+- `wmSearchBrowseResults`
+- `wmSearchValueChanged`
+
+**Methods:**
+- `updateValue(value: string) => Promise<void>`
+
+**Accessibility:**
+
+- `label` sets the `aria-label` on the underlying `<input>` -- it is required even when
+  the label text is not visually displayed.
+- An `aria-live` region announces the result count after each input change and after
+  prev/next navigation in the `find` variant.
+- In the `find` variant, `highlighted-id` is used as the `href` of the jump-to-result
+  skip-link that appears while the user is tabbing.
+- **Keyboard:** - **Tab**: Advances focus through the input and, in the `find` variant, the prev/next
+  buttons and the jump-to-result skip-link (visible only when tabbing with results present).
+- **Shift+Tab**: Moves focus backward through the same elements.
+- **Enter / Space**: Activates the focused prev/next buttons in the `find` variant.
+
+**Related components:**
+
+- `<wm-input>` -- if the user is typing a value to store as form data rather than to filter visible content, use Input; Search has no form submission semantics.
+- `<wm-select>` with search property -- if the user is searching within a bounded dropdown list of options to make a selection, use Select's built-in search; `<wm-search>` is for filtering page-level content, not for narrowing selectable options.
+- `<wm-tag-input>` -- if the user needs to search and then commit multiple selected values as discrete tags, Tag Input combines search-style filtering with multi-value selection; `<wm-search>` alone has no concept of committed selected values.
+
+**Code example:**
+
+_Basic search_
+
+```html
+<wm-search label="Filter courses" placeholder="Search courses..."></wm-search>
+```
+
+_Basic search_
+
+```react
+// wmSearchValueChanged fires on blur only -- use a native input event listener via ref
+// for per-keystroke filtering. el.value reflects the current typed string.
+const basicRef = useRef(null);
+const [query, setQuery] = useState("");
+
+useEffect(() => {
+const el = basicRef.current;
+const handler = () => setQuery(el.value);
+el.addEventListener("input", handler);
+return () => el.removeEventListener("input", handler);
+}, []);
+
+const filtered = items.filter((c) => c.toLowerCase().includes(query.toLowerCase()));
+
+<WmSearch ref={basicRef} label="Filter courses" placeholder="Search courses..."
+numResults={filtered.length} />
+```
+
+_Search and find variant_
+
+```html
+<wm-search
+search-type="find"
+label="Find in page"
+placeholder="Find..."
+num-results="5"
+highlighted-id="result-1"
+highlighted-name="First result">
+</wm-search>
+```
+
+_Search and find variant_
+
+```react
+// The find variant navigates through matched results only.
+// On input: filter items, set numResults, and highlight the first match.
+// On wmSearchBrowseResults: use e.detail.position (1-based) to index into the filtered list.
+// highlightedId must match the id of the corresponding DOM element.
+// The component does not filter -- filtering logic is entirely the application's responsibility.
+const findRef = useRef(null);
+const [highlightedId, setHighlightedId] = useState("");
+const [highlightedName, setHighlightedName] = useState("");
+const [numFindResults, setNumFindResults] = useState(0);
+const toId = (name) => name.toLowerCase().replace(/\s+/g, "-");
+const filterItems = (value) =>
+!value ? [] : items.filter((c) => c.toLowerCase().includes(value.toLowerCase()));
+
+useEffect(() => {
+const el = findRef.current;
+const handler = () => {
+const results = filterItems(el.value);
+setNumFindResults(results.length);
+if (results.length) { setHighlightedId(toId(results[0])); setHighlightedName(results[0]); }
+else { setHighlightedId(""); setHighlightedName(""); }
+};
+el.addEventListener("input", handler);
+return () => el.removeEventListener("input", handler);
+}, []);
+
+const handleBrowseResults = (e) => {
+const results = filterItems(findRef.current.value);
+const item = results[e.detail.position - 1];
+if (item) { setHighlightedId(toId(item)); setHighlightedName(item); }
+};
+
+<WmSearch ref={findRef} searchType="find" label="Find result" placeholder="Find..."
+numResults={numFindResults} highlightedId={highlightedId} highlightedName={highlightedName}
+onWmSearchBrowseResults={handleBrowseResults} />
+{items.map((c) => (
+<li key={c} id={toId(c)}
+style={{ background: highlightedId === toId(c) ? "lightyellow" : "transparent" }}>
+{c}
+</li>
+))}
+```

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

@@ -0,0 +1,148 @@
+### Select
+- **Element:** `<wm-select>`
+- **Status:** stable
+
+**Purpose:** Dropdown list of options that allows single or multi-select. Functionally similar to the
+native HTML `<select>` element but with Ripple styling and richer features including
+multiselect, search filtering, and a Select All control. Composed of a parent wm-select
+element and wm-option children.
+
+**When to use:**
+
+- **Choosing a single value from a known, bounded list** -- when a user needs to pick exactly one option from a fixed set (e.g., selecting a term, role, or status), use the default single-select variant to record that choice as a form value.
+- **Selecting multiple values from a flat list** -- when a user can choose more than one option from an unstructured set, use the multiple property, optionally with select-all for bulk selection convenience.
+- **Filtering a manageable option set by typing** -- when the list has up to 50 options and scanning is impractical, use the search property to let users narrow options by typing rather than scrolling.
+- **Displaying supplementary context alongside options** -- when each option benefits from a short secondary label (e.g., a code, count, or category hint), use the subinfo property on wm-option to show italicized supporting text inline.
+
+**Do not use for:**
+
+- **Categorized options** -- if the option set has a meaningful group structure, use wm-nested-select instead; Select only supports a single flat list.
+- **Selecting an option that triggers an action** -- if selecting an item should immediately execute something, use wm-action-menu's selector variant, not Select.
+- **More than 50 options in search mode** -- the search variant is intended for 50 or fewer options; beyond that, it creates usability and potential performance problems.
+- **Single Select with no pre-selected option** -- single Select must always have a selected value; if no default exists, the first option must explicitly represent a null state using only approved language ("None", "Select an option", or "--").
+
+**Variants / types:**
+
+_None documented_
+
+**Props:**
+- `all-selected-message` -- Text displayed in the trigger button in multiselect mode when every option
+is selected.
+- `disabled` -- Disables the entire select component, preventing all interaction.
+- `error-message` -- Puts the component in an error state and displays this message beneath the
+trigger button. Use for form validation feedback.
+- `info` -- Informational hint text rendered beneath the dropdown button. Use for
+supporting instructions or constraints.
+- `label` -- Accessible label for the dropdown. Required even when `label-position` is
+`"none"` -- used as the ARIA accessible name.
+- `label-position` -- Position of the label relative to the dropdown button. `"none"` hides the
+label visually but keeps it accessible via ARIA.
+- `max-height` -- Overrides the maximum height of the options list. Accepts any valid CSS
+length value (e.g. `"20rem"`, `"300px"`).
+- `multiple` -- Enables multiselect mode, allowing more than one option to be selected
+simultaneously.
+- `placeholder` -- Text displayed in the trigger button in multiselect mode when no options are
+selected. Not applicable in single-select mode -- use a null-value first option instead.
+- `required-field` -- Displays a required-field asterisk (*) next to the label.
+- `search` -- Adds a search input inside the dropdown that filters visible options by label
+text. Compatible with both single and multiselect modes. Best with 50 or fewer options.
+- `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 the dropdown.
+Has no effect unless `multiple` is also set.
+
+**Events:**
+- `wmSelectAllDeselected`
+- `wmSelectAllSelected`
+- `wmSelectBlurred`
+- `wmSelectDidLoad`
+
+**Accessibility:**
+
+- `label` is required even when `label-position` is `"none"` -- it is used as the dropdown's
+  ARIA accessible name.
+- The dropdown renders with `role="listbox"`. Each wm-option renders with `role="option"`.
+- `required-field` renders a visible asterisk; the ARIA required constraint is communicated
+  via the label rather than `aria-required` because the listbox is in a sub-component.
+- 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
+  option; Arrow Up opens and focuses the last option.
+- **Open dropdown**: Arrow Up / Down navigate options; Home / End jump to first / last;
+  typing a letter jumps to the first matching option.
+- **Single-select**: Enter / Space / click selects and closes.
+- **Multi-select**: Enter / Space / click toggles selection; Tab or Escape closes.
+- **Shift+Tab** (from options): Closes and returns focus to the trigger button.
+
+**Related components:**
+
+- `<wm-nested-select>` -- if the options have a two-level category structure, use Nested Select; if they are a single flat list, use Select.
+- `<wm-action-menu>` (selector type) -- if picking an option should immediately execute an action rather than record a value, use Action Menu's selector type, not Select.
+- `<wm-tag-input>` -- if the user needs to select or create values displayed as removable tags (e.g., adding people or labels), Tag Input is likely the better fit over multi-select Select.
+
+**Code example:**
+
+_Single-select_
+
+```html
+<wm-select label="Program">
+<wm-option selected>Select a program</wm-option>
+<wm-option>Biology</wm-option>
+<wm-option>English</wm-option>
+</wm-select>
+```
+
+_Single-select_
+
+```react
+const [program, setProgram] = useState('');
+
+// event.detail is the selected HTMLWmOptionElement
+const handleSelect = (event) => {
+setProgram(event.detail.value ?? event.detail.textContent);
+};
+
+<WmSelect label="Program" onWmOptionSelected={handleSelect}>
+<WmOption selected>Select a program</WmOption>
+<WmOption value="bio">Biology</WmOption>
+<WmOption value="eng">English</WmOption>
+</WmSelect>
+```
+
+_Multi-select with search and Select All_
+
+```html
+<wm-select label="Programs" multiple search select-all
+placeholder="Select programs">
+<wm-option value="bio">Biology</wm-option>
+<wm-option value="eng">English</wm-option>
+</wm-select>
+```
+
+_Multi-select with search and 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));
+};
+
+<WmSelect
+label="Programs"
+multiple={true}
+search={true}
+selectAll={true}
+placeholder="Select programs"
+onWmOptionSelected={handleSelect}
+onWmOptionDeselected={handleDeselect}
+>
+<WmOption value="bio">Biology</WmOption>
+<WmOption value="eng">English</WmOption>
+</WmSelect>
+```