@watermarkinsights/ripple 0.0.1 → 0.1.0-alpha.1

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

@@ -0,0 +1,114 @@
+### Pagination
+- **Element:** `<wm-pagination>`
+
+**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
+
+**Usage notes:**
+
+- `current-page`, `total-items`, and `items-per-page` are all required; a missing value
+  throws an error on load.
+- Listen to `wmPaginationPageClicked` and read `event.target.value` to get the selected
+  page number. `event.target.value` is a string -- wrap with `Number()` before storing.
+- The component does not manage data -- it only reports which page was selected.
+- When multiple pagination instances appear on the same page, give each a unique `label`
+  to disambiguate the `<nav>` landmark for screen readers, and drive each from independent state.
+
+**Props:**
+- `current-page` -- The currently active page number. Update this prop in response to
+`wmPaginationPageClicked` to keep the component in sync with your data. _(required; default: `1`)_
+- `items-per-page` -- Number of items displayed per page. Used with `total-items` to calculate
+the total page count. _(required)_
+- `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"`). _(default: `""`)_
+- `total-items` -- Total number of items across all pages. Used with `items-per-page` to
+calculate the total page count. _(required)_
+- `value` -- The page number selected by the most recent user interaction. Read
+`event.target.value` in the `wmPaginationPageClicked` handler to get the selected page. _(default: `1`)_
+
+**Events:**
+- `wmPaginationPageClicked` -- Fires when the user clicks a page number, previous, or next button.
+Read `event.target.value` to get the selected page number, then update `current-page`
+and re-render your data.
+
+**Required setup:**
+
+- Handle `wmPaginationPageClicked` by reading `event.target.value` -- a string, so convert it to
+  a number -- and writing it to `current-page`.
+- Set `total-items` and `items-per-page` from the data you are paging; together they determine the
+  page count.
+- Share one page state between paginations rendered above and below the same table.
+
+**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,75 @@
+### Progress Indicator
+- **Element:** `<wm-progress-indicator>`
+
+**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.
+
+**When to use:**
+
+- **Tracking binary completion** -- when each metric has exactly two states (done vs. not done) and the goal is to show how far along it is.
+- **Several completion metrics together** -- render one `wm-progress-indicator` per metric to show them as a related set that reflows responsively.
+
+**Do not use for:**
+
+- **More than two states** -- for three or more states (e.g., Not Started / In Progress / Complete) and a composition breakdown, use `wm-chart-stack` for a horizontal bar chart, or `wm-chart` for a doughnut chart.
+- **Comparing independent values across categories** -- use `wm-chart-bar` or `wm-chart-column`.
+- **Data changing over time** -- use `wm-line-chart`.
+
+**Variants / types:**
+
+- **Doughnut layout** -- indicators shown as doughnuts in a horizontal row above the breakpoint.
+- **Bar layout** -- indicators collapse to horizontal bars in a vertical stack below the breakpoint; `group-legend` is shown only in this mode.
+- **Single vs. multiple indicators** -- one or many `wm-progress-indicator` children.
+- **Custom breakpoint** -- control the doughnut/bar switch with a unit-less indicator count or an exact pixel value.
+
+> **Strict constraint:** each `wm-progress-indicator` must have exactly two `wm-progress-slice` children -- one for the "complete" state and one for the "incomplete" state.
+
+**Usage notes:**
+
+- 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. _(required)_
+- `print-mode` -- When true, slice values are included in the legend and keyboard interaction
+instructions are removed from the DOM -- suitable for printed output. _(default: `false`)_
+- `print-mode-format` -- Format for legend values when `print-mode` is enabled. _(type: `"amount" | "percentage"`; default: `"amount"`)_
+- `show-legend` -- Show or hide the legend. The legend is still read by screen readers
+regardless of this setting. _(default: `true`)_
+- `subinfo` -- Optional secondary text displayed beneath the label.
+
+**Related components:**
+
+- `<wm-progress-indicator>` -- required child; one per tracked metric.
+- `<wm-progress-slice>` -- required child of each indicator; exactly two per indicator.
+- `<wm-chart>` -- for three-or-more-state progress or composition in a doughnut chart.
+- `<wm-chart-stack>` -- for three-or-more-state progress or composition in a bar chart.
+
+**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,120 @@
+### Progress Monitor
+- **Element:** `<wm-progress-monitor>`
+
+**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.
+
+**When to use:**
+
+- **Tracking binary completion** -- when each metric has exactly two states (done vs. not done) and the goal is to show how far along it is.
+- **Several completion metrics together** -- render one `wm-progress-indicator` per metric to show them as a related set that reflows responsively.
+
+**Do not use for:**
+
+- **More than two states** -- for three or more states (e.g., Not Started / In Progress / Complete) and a composition breakdown, use `wm-chart-stack` for a horizontal bar chart, or `wm-chart` for a doughnut chart.
+- **Comparing independent values across categories** -- use `wm-chart-bar` or `wm-chart-column`.
+- **Data changing over time** -- use `wm-line-chart`.
+
+**Variants / types:**
+
+- **Doughnut layout** -- indicators shown as doughnuts in a horizontal row above the breakpoint.
+- **Bar layout** -- indicators collapse to horizontal bars in a vertical stack below the breakpoint; `group-legend` is shown only in this mode.
+- **Single vs. multiple indicators** -- one or many `wm-progress-indicator` children.
+- **Custom breakpoint** -- control the doughnut/bar switch with a unit-less indicator count or an exact pixel value.
+
+> **Strict constraint:** each `wm-progress-indicator` must have exactly two `wm-progress-slice` children -- one for the "complete" state and one for the "incomplete" state.
+
+**Usage notes:**
+
+- 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. _(type: `number | string`)_
+- `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` -- Fires once on load and again whenever the layout switches between `"doughnut"`
+and `"bar"` modes. Use this to synchronize external UI that depends on the current layout. Detail: ``"doughnut" | "bar"` -- the new layout mode.`
+
+**Related components:**
+
+- `<wm-progress-indicator>` -- required child; one per tracked metric.
+- `<wm-progress-slice>` -- required child of each indicator; exactly two per indicator.
+- `<wm-chart>` -- for three-or-more-state progress or composition in a doughnut chart.
+- `<wm-chart-stack>` -- for three-or-more-state progress or composition in a bar chart.
+
+**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,67 @@
+### Progress Slice
+- **Element:** `<wm-progress-slice>`
+
+**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.
+
+**When to use:**
+
+- **Tracking binary completion** -- when each metric has exactly two states (done vs. not done) and the goal is to show how far along it is.
+- **Several completion metrics together** -- render one `wm-progress-indicator` per metric to show them as a related set that reflows responsively.
+
+**Do not use for:**
+
+- **More than two states** -- for three or more states (e.g., Not Started / In Progress / Complete) and a composition breakdown, use `wm-chart-stack` for a horizontal bar chart, or `wm-chart` for a doughnut chart.
+- **Comparing independent values across categories** -- use `wm-chart-bar` or `wm-chart-column`.
+- **Data changing over time** -- use `wm-line-chart`.
+
+**Variants / types:**
+
+- **Doughnut layout** -- indicators shown as doughnuts in a horizontal row above the breakpoint.
+- **Bar layout** -- indicators collapse to horizontal bars in a vertical stack below the breakpoint; `group-legend` is shown only in this mode.
+- **Single vs. multiple indicators** -- one or many `wm-progress-indicator` children.
+- **Custom breakpoint** -- control the doughnut/bar switch with a unit-less indicator count or an exact pixel value.
+
+> **Strict constraint:** each `wm-progress-indicator` must have exactly two `wm-progress-slice` children -- one for the "complete" state and one for the "incomplete" state.
+
+**Usage notes:**
+
+- 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. _(required)_
+- `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.
+
+**Related components:**
+
+- `<wm-progress-indicator>` -- required child; one per tracked metric.
+- `<wm-progress-slice>` -- required child of each indicator; exactly two per indicator.
+- `<wm-chart>` -- for three-or-more-state progress or composition in a doughnut chart.
+- `<wm-chart-stack>` -- for three-or-more-state progress or composition in a bar chart.
+
+**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,180 @@
+### Search
+- **Element:** `<wm-search>`
+
+**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
+
+**Usage notes:**
+
+- Both `label` and `placeholder` are required; the component logs a console error on load
+  if either is missing.
+- Listen to the native `input` event for per-keystroke updates; `wmSearchValueChanged`
+  fires on blur only.
+- For the `find` variant, listen to `wmSearchBrowseResults` and update `highlighted-id`
+  and `highlighted-name` after scrolling/highlighting the result in your data.
+- The component does not perform filtering -- filtering logic must be implemented by the
+  application.
+
+**Props:**
+- `disabled` -- Disables the input, preventing all interaction. _(default: `false`)_
+- `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"`.; default: `""`)_
+- `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. _(type: `null | string`; conditionally required: Required when `search-type="find"`.; default: `null`)_
+- `label` -- Accessible label for the `<input>` element. Required even when not visually
+displayed. May match the placeholder text. _(required; default: `""`)_
+- `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. _(default: `0`)_
+- `placeholder` -- Placeholder text displayed inside the empty input. _(required; default: `""`)_
+- `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. _(type: `"basic" | "find"`; default: `"basic"`)_
+- `value` -- The current text typed by the user. Readable by the application at any time. _(default: `""`)_
+
+**Events:**
+- `wmSearchBrowseResults` -- Fires when the prev or next button is clicked in the `find` variant.
+Update `highlighted-id` and `highlighted-name` in response to highlight the result in
+your data. Detail: `{{ position: number }} position -- one-based index of the newly highlighted result.`
+- `wmSearchValueChanged` -- Fires on blur when the input value has changed since the last blur. Use the
+native `input` event for per-keystroke updates. Detail: `{{ value: string }} value -- the current input value at the time of blur.`
+
+**Methods:**
+- `updateValue(value: string) => Promise<void>`
+
+**Required setup:**
+
+- Filter your own data as the value changes and set `num-results`, which drives the
+  screen-reader result count.
+- Handle `wmSearchValueChanged` (`event.detail` is `{ value }`) for the committed value; it fires
+  on blur. For filter-as-you-type, listen for the native `input` event as well.
+- With `search-type="find"`, handle `wmSearchBrowseResults` (`event.detail` is `{ position }`,
+  one-based) and set `highlighted-id` and `highlighted-name` to the matching result.
+
+**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>
+))}
+```