@watermarkinsights/ripple 5.30.0 → 5.31.0-alpha.1

package/dist/collection/components/wm-navigator/priv-navigator-item/priv-navigator-item.js

@@ -1,4 +1,8 @@
 import { h } from "@stencil/core";
+/**
+ * @internal
+ * @description Internal navigator item component for use with the Navigation component. Not to be used directly.
+ */
 export class PrivNavigatorItem {
     constructor() {
         this.selected = false;
@@ -16,7 +20,7 @@ export class PrivNavigatorItem {
     render() {
         const selectedClass = this.selected ? "selected" : "";
         const focusedClass = this.focused ? "focused" : "";
-        return (h("div", { key: 'b79461e5967f3e75c8bb4d4c5e9e66d6b870c84b', class: `navoption ${selectedClass} ${focusedClass}` }, h("slot", { key: '35f83b67f08a1d8fdc3aeaeba1acdef45e85fca1' })));
+        return (h("div", { key: '427929b24dd60459f8269a3d3ee746ac876ff31f', class: `navoption ${selectedClass} ${focusedClass}` }, h("slot", { key: '9c67b8bd2282efc3ca77d8805dd3278d3e0b3c4a' })));
     }
     static get is() { return "priv-navigator-item"; }
     static get encapsulation() { return "shadow"; }

package/dist/collection/components/wm-navigator/wm-navigator.js

@@ -2,6 +2,60 @@ import { h, Host } from "@stencil/core";
 import { getWmMode } from "../../global/interfaces";
 import { intl, snakeCaseToCamelCase, getNewIndexToFocus } from "../../global/functions";
 import { getRequest } from "../../global/services/http-service";
+/**
+ * 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.
+ *
+ * @keyboardInteraction
+ * - **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.
+ *
+ * @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.
+ *
+ * @usageNotes
+ * - 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.
+ *
+ * @example {html} Prop mode
+ * <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>
+ *
+ * @example {react} Prop mode
+ * <WmNavigator
+ *   userName="Maria Garcia"
+ *   email="m.garcia@example.com"
+ *   authType={2}
+ *   logoutUrl="https://app.watermarkinsights.com/logout"
+ *   products={JSON.stringify(products)}
+ *   onWmNavigatorLogout={handleLogout} />
+ *
+ * @example {html} Endpoint mode (fetches user info automatically)
+ * <wm-navigator user-name="Maria Garcia" load-from-userinfo="true"></wm-navigator>
+ *
+ * @example {react} Endpoint mode
+ * <WmNavigator userName="Maria Garcia" loadFromUserinfo={true} onWmNavigatorLogout={handleLogout} />
+ *
+ * @category Navigation
+ */
 export class Navigator {
     constructor() {
         // comp can check whether the info was successfully retrieved with:
@@ -237,7 +291,7 @@ export class Navigator {
             name = product.name;
             icon = product.iconUrl;
             clickRedirect = this.setProductOnClick(product.id);
-            if (!!name && !!icon) {
+            if (!!name && !!icon && this.isSafeUrl(icon)) {
                 isSelected = this.currentProductId === product.id;
                 return (h("priv-navigator-item", { selected: isSelected, id: product.id, onClick: () => {
                         isSelected ? this.closeMenu() : clickRedirect();
@@ -330,7 +384,13 @@ export class Navigator {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "The display name of the logged-in user, shown in the menu header."
+                        }, {
+                            "name": "required",
+                            "text": undefined
+                        }],
                     "text": ""
                 },
                 "attribute": "user-name",
@@ -347,7 +407,13 @@ export class Navigator {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "The email address of the logged-in user, shown in the menu header."
+                        }, {
+                            "name": "conditionallyRequired",
+                            "text": "when load-from-userinfo is false"
+                        }],
                     "text": ""
                 },
                 "attribute": "email",
@@ -364,7 +430,16 @@ export class Navigator {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Authentication method, determining how product link redirects are handled.\n`1` \u2014 no redirect; `2` \u2014 username/password or SSO (uses `link_url`); `3` \u2014 SAML (uses `saml_link_url`)."
+                        }, {
+                            "name": "default",
+                            "text": "1"
+                        }, {
+                            "name": "conditionallyRequired",
+                            "text": "when load-from-userinfo is false and products are provided"
+                        }],
                     "text": ""
                 },
                 "attribute": "auth-type",
@@ -382,7 +457,10 @@ export class Navigator {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "SAML connection name appended as a query parameter to product redirect URLs.\nOnly used when `auth-type` is `3`."
+                        }],
                     "text": ""
                 },
                 "attribute": "connection-name",
@@ -399,7 +477,10 @@ export class Navigator {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "URL to redirect to after logout. If omitted, no redirect occurs \u2014 handle\nnavigation entirely in the `wmNavigatorLogout` event handler."
+                        }],
                     "text": ""
                 },
                 "attribute": "logout-url",
@@ -416,7 +497,10 @@ export class Navigator {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "The user's accessible Watermark products, as a JSON string or array of objects.\nEach object must include `id`, `name`, `icon_url`, and either `link_url` (auth-type 2) or\n`saml_link_url` (auth-type 3). Not needed when `load-from-userinfo` is true."
+                        }],
                     "text": ""
                 },
                 "attribute": "products",
@@ -433,7 +517,13 @@ export class Navigator {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "When true, fetches user info and products automatically from the\n`/platform/navigator/userinfo` endpoint instead of using props."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
                     "text": ""
                 },
                 "attribute": "load-from-userinfo",
@@ -456,7 +546,10 @@ export class Navigator {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires when the user clicks the logout option. Always handle this event to\nrun app-specific cleanup (e.g. clearing local storage or session state) before any logout\nredirect. If `logout-url` is set, the component will navigate there after this event fires."
+                        }],
                     "text": ""
                 },
                 "complexType": {

package/dist/collection/components/wm-pagination/wm-pagination.js

@@ -1,6 +1,58 @@
 import { h } from "@stencil/core";
 import { debounce, intl } from "../../global/functions";
 import { globalMessages } from "../../global/intl";
+/**
+ * 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.
+ *
+ * @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"`.
+ *
+ * @usageNotes
+ * - `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.
+ *
+ * @example {html} Basic pagination
+ * <wm-pagination current-page="1" total-items="150" items-per-page="25"></wm-pagination>
+ *
+ * @example {react} Basic pagination
+ * // 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))} />
+ *
+ * @example {html} With accessible label
+ * <wm-pagination label="Search results" current-page="1" total-items="80" items-per-page="10">
+ * </wm-pagination>
+ *
+ * @example {react} Multiple instances with independent state
+ * // 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))} />
+ *
+ * @category Navigation
+ */
 export class Pagination {
     constructor() {
         this.totalPages = 0;
@@ -204,7 +256,7 @@ export class Pagination {
     render() {
         return (
         // do not render the component if there's only one page
-        this.totalItems > this.itemsPerPage && (h("nav", { key: '535581d117f47eb9bf29853901e80554e3f29ea9', "aria-label": `${this.label || this.defaultLabel}. ${this.getCurrentPagesInView()}. ${this.currentPageAnnouncement(this.currentPage)}` }, this.isLargeSize ? this.renderLarge() : this.renderSmall(), h("div", { key: '571b1089d6fe9775168f48c69b489305b1142a77', id: "status", class: "sr-only", "aria-live": "polite", "aria-relevant": "text", "aria-atomic": "true" }, this.srAnnouncement))));
+        this.totalItems > this.itemsPerPage && (h("nav", { key: '8c094b7e649c43b8203b39f2a6afdd8f1cf727c1', "aria-label": `${this.label || this.defaultLabel}. ${this.getCurrentPagesInView()}. ${this.currentPageAnnouncement(this.currentPage)}` }, this.isLargeSize ? this.renderLarge() : this.renderSmall(), h("div", { key: '23aee5fba033dfb71cc355d3dfcf8ebf5086a166', id: "status", class: "sr-only", "aria-live": "polite", "aria-relevant": "text", "aria-atomic": "true" }, this.srAnnouncement))));
     }
     static get is() { return "wm-pagination"; }
     static get encapsulation() { return "shadow"; }
@@ -232,7 +284,10 @@ export class Pagination {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Accessible label for the `<nav>` element. Defaults to `\"Pagination navigation\"`.\nOverride when multiple pagination instances appear on the same page (e.g. `\"Search results\"`)."
+                        }],
                     "text": ""
                 },
                 "attribute": "label",
@@ -250,7 +305,16 @@ export class Pagination {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "The currently active page number. Update this prop in response to\n`wmPaginationPageClicked` to keep the component in sync with your data."
+                        }, {
+                            "name": "default",
+                            "text": "1"
+                        }, {
+                            "name": "required",
+                            "text": undefined
+                        }],
                     "text": ""
                 },
                 "attribute": "current-page",
@@ -268,7 +332,13 @@ export class Pagination {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Total number of items across all pages. Used with `items-per-page` to\ncalculate the total page count."
+                        }, {
+                            "name": "required",
+                            "text": undefined
+                        }],
                     "text": ""
                 },
                 "attribute": "total-items",
@@ -286,7 +356,13 @@ export class Pagination {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Number of items displayed per page. Used with `total-items` to calculate\nthe total page count."
+                        }, {
+                            "name": "required",
+                            "text": undefined
+                        }],
                     "text": ""
                 },
                 "attribute": "items-per-page",
@@ -304,7 +380,13 @@ export class Pagination {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "The page number selected by the most recent user interaction. Read\n`event.target.value` in the `wmPaginationPageClicked` handler to get the selected page."
+                        }, {
+                            "name": "default",
+                            "text": "1"
+                        }],
                     "text": ""
                 },
                 "attribute": "value",
@@ -322,7 +404,13 @@ export class Pagination {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "internal",
+                            "text": undefined
+                        }, {
+                            "name": "description",
+                            "text": "Internal responsive state \u2014 updated by ResizeObserver; not intended for external use."
+                        }],
                     "text": ""
                 },
                 "attribute": "is-large-size",
@@ -344,7 +432,10 @@ export class Pagination {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires when the user clicks a page number, previous, or next button.\nRead `event.target.value` to get the selected page number, then update `current-page`\nand re-render your data."
+                        }],
                     "text": ""
                 },
                 "complexType": {
@@ -359,7 +450,13 @@ export class Pagination {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "internal",
+                            "text": undefined
+                        }, {
+                            "name": "description",
+                            "text": "Internal event used to restore focus to the current page button after re-render."
+                        }],
                     "text": ""
                 },
                 "complexType": {

package/dist/collection/components/wm-search/wm-search.js

@@ -1,6 +1,112 @@
 import { h, Host } from "@stencil/core";
 import { intl, handleDisabledAttribute, toBool } from "../../global/functions";
 import { globalMessages } from "../../global/intl";
+/**
+ * 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.
+ *
+ * @keyboardInteraction
+ * - **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.
+ *
+ * @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.
+ *
+ * @usageNotes
+ * - 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.
+ *
+ * @example {html} Basic search
+ * <wm-search label="Filter courses" placeholder="Search courses..."></wm-search>
+ *
+ * @example {react} Basic search
+ * // 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} />
+ *
+ * @example {html} Search and find variant
+ * <wm-search
+ *   search-type="find"
+ *   label="Find in page"
+ *   placeholder="Find..."
+ *   num-results="5"
+ *   highlighted-id="result-1"
+ *   highlighted-name="First result">
+ * </wm-search>
+ *
+ * @example {react} Search and find variant
+ * // 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>
+ * ))}
+ *
+ * @category Form Inputs
+ */
 export class Search {
     constructor() {
         this.linkEl = null;
@@ -168,10 +274,10 @@ export class Search {
      * End search and find render helpers
      */
     render() {
-        return (h(Host, { key: '7bfd505862c5bef72dc333bc22fb99c04c513b3f' }, h("div", { key: '9d7f4cf04c5655df0bf4d9697622182f1eb717c8', id: "wm-search-wrapper", class: `wm-search-wrapper ${this.searchType}` }, h("input", { key: '88da025659c4c5f35ac3b4c7207ad734a115a85a', disabled: this.isDisabled, id: "wm-search-input", placeholder: this.placeholder, "aria-label": `${this.label ? this.label + ". " : ""}${intl.formatMessage({
+        return (h(Host, { key: 'f6ad1575d3d98598c53acdab13501e852938847b' }, h("div", { key: 'f5cf56ed765036dfd6ffa7b89a306beb5d26bfe3', id: "wm-search-wrapper", class: `wm-search-wrapper ${this.searchType}` }, h("input", { key: 'bef933845ee4ab06e444c010d6fb27521115d377', disabled: this.isDisabled, id: "wm-search-input", placeholder: this.placeholder, "aria-label": `${this.label ? this.label + ". " : ""}${intl.formatMessage({
                 id: "search.typeToFilterResults",
                 defaultMessage: "Type to filter the results",
-            })}`, onInput: (ev) => this.updateValue(ev.target.value), onBlur: () => this.handleBlur(), "aria-autocomplete": "none", autocomplete: "off", value: this.value }), h("span", { key: 'c5834f5cc58a1fd6d7c6637604cbbb5a610e2476', class: "svg-icon svg-search" }), this.searchType === "find" && this.renderResultsAndBrowseButtons(), h("div", { key: '243438ee1d91d8875ec3014f6b17532a283e7cdf', id: "wm-search-live", class: "sr-only", "aria-live": "polite", "aria-atomic": "true", ref: (el) => (this.resultsLiveRegion = el) }, this.announcement)), this.searchType === "find" && this.renderJumpToLink()));
+            })}`, onInput: (ev) => this.updateValue(ev.target.value), onBlur: () => this.handleBlur(), "aria-autocomplete": "none", autocomplete: "off", value: this.value }), h("span", { key: '80042b82d4a2d0552a25c4049bf2e07b53c382aa', class: "svg-icon svg-search" }), this.searchType === "find" && this.renderResultsAndBrowseButtons(), h("div", { key: 'fd741eb70958ae07089b0aa962580c6eee95a832', id: "wm-search-live", class: "sr-only", "aria-live": "polite", "aria-atomic": "true", ref: (el) => (this.resultsLiveRegion = el) }, this.announcement)), this.searchType === "find" && this.renderJumpToLink()));
     }
     static get is() { return "wm-search"; }
     static get encapsulation() { return "shadow"; }
@@ -199,7 +305,13 @@ export class Search {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Selects the search variant. `'basic'` renders a simple text input with a\nresult count. `'find'` adds prev/next navigation buttons and a jump-to-result skip-link."
+                        }, {
+                            "name": "default",
+                            "text": "\"basic\""
+                        }],
                     "text": ""
                 },
                 "attribute": "search-type",
@@ -217,7 +329,13 @@ export class Search {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Disables the input, preventing all interaction."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
                     "text": ""
                 },
                 "attribute": "disabled",
@@ -235,8 +353,14 @@ export class Search {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Props required for both variants."
+                    "tags": [{
+                            "name": "description",
+                            "text": "Placeholder text displayed inside the empty input."
+                        }, {
+                            "name": "required",
+                            "text": undefined
+                        }],
+                    "text": ""
                 },
                 "attribute": "placeholder",
                 "reflect": false,
@@ -253,7 +377,13 @@ export class Search {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Accessible label for the `<input>` element. Required even when not visually\ndisplayed. May match the placeholder text."
+                        }, {
+                            "name": "required",
+                            "text": undefined
+                        }],
                     "text": ""
                 },
                 "attribute": "label",
@@ -271,7 +401,13 @@ export class Search {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Number of results matching the current query. Update this prop after\nfiltering to display \"x of y results\" (find variant) and announce the count to screen\nreaders."
+                        }, {
+                            "name": "default",
+                            "text": "0"
+                        }],
                     "text": ""
                 },
                 "attribute": "num-results",
@@ -289,8 +425,14 @@ export class Search {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "This exposes the input's value on the host component so that the app can access it."
+                    "tags": [{
+                            "name": "description",
+                            "text": "The current text typed by the user. Readable by the application at any time."
+                        }, {
+                            "name": "default",
+                            "text": "\"\""
+                        }],
+                    "text": ""
                 },
                 "attribute": "value",
                 "reflect": true,
@@ -307,8 +449,14 @@ export class Search {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Prop specifically for the search and find variant. The id points to the id of the option currently highlighted,\nso that tabbing and screen reader users can jump to this option rather than tab through the list to find it."
+                    "tags": [{
+                            "name": "description",
+                            "text": "`id` of the currently highlighted result element. Used as the `href` of the\njump-to-result skip-link. Required for the `find` variant for full accessibility."
+                        }, {
+                            "name": "conditionallyRequired",
+                            "text": "Required when `search-type=\"find\"`."
+                        }],
+                    "text": ""
                 },
                 "attribute": "highlighted-id",
                 "reflect": false,
@@ -325,7 +473,13 @@ export class Search {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Visible text of the currently highlighted result. Appended to the screen\nreader announcement after `wmSearchBrowseResults` fires. Required for the `find` variant\nfor full accessibility."
+                        }, {
+                            "name": "conditionallyRequired",
+                            "text": "Required when `search-type=\"find\"`."
+                        }],
                     "text": ""
                 },
                 "attribute": "highlighted-name",
@@ -351,8 +505,14 @@ export class Search {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
-                    "text": "Emitted when the buttons in the search-and-find variant are pressed."
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires when the prev or next button is clicked in the `find` variant.\nUpdate `highlighted-id` and `highlighted-name` in response to highlight the result in\nyour data."
+                        }, {
+                            "name": "eventDetails",
+                            "text": "{{ position: number }} position \u2014 one-based index of the newly highlighted result."
+                        }],
+                    "text": ""
                 },
                 "complexType": {
                     "original": "{ position: number }",
@@ -366,7 +526,13 @@ export class Search {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires on blur when the input value has changed since the last blur. Use the\nnative `input` event for per-keystroke updates."
+                        }, {
+                            "name": "eventDetails",
+                            "text": "{{ value: string }} value \u2014 the current input value at the time of blur."
+                        }],
                     "text": ""
                 },
                 "complexType": {