@watermarkinsights/ripple 0.0.1 → 0.1.0-alpha.1

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

@@ -0,0 +1,604 @@
+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.
+ *
+ * @category Form Inputs
+ *
+ * @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>
+ * ))}
+ *
+ * @requiredSetup
+ * - 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.
+ *
+ */
+export class Search {
+    constructor() {
+        this.linkEl = null;
+        this.searchType = "basic";
+        this.disabled = false;
+        this.placeholder = "";
+        this.label = "";
+        this.numResults = 0;
+        this.value = "";
+        this.isTabbing = false;
+        this.highlightedId = "";
+        this.highlightedName = null;
+        this.highlightedNum = 0;
+        this.previousBlurredValue = "";
+        this.parentModal = undefined;
+        this.announcement = "";
+    }
+    get isDisabled() {
+        // string "false" needs to be treated as bool False because react wrappers convert bool to string.
+        return toBool(this.disabled);
+    }
+    get resultCount() {
+        let message = "";
+        const basicMessage = intl.formatMessage({
+            id: "search.resultsFound",
+            defaultMessage: "{numResults, plural, =0 {No results} one {1 result} other {# results}} found",
+        }, { numResults: this.numResults });
+        const findMessage = intl.formatMessage({
+            id: "search.xOfYResults",
+            defaultMessage: "{numResults, plural, =0 {No results found} other {{current} of {numResults} results}}",
+        }, { numResults: this.numResults, current: this.highlightedNum });
+        if (this.searchType === "basic") {
+            message = basicMessage;
+        }
+        else if (this.searchType === "find") {
+            message = findMessage;
+        }
+        return message;
+    }
+    toggleTabbingOn() {
+        this.isTabbing = true;
+        this.linkEl && this.linkEl.classList.remove("sr-only");
+        this.linkEl && this.linkEl.classList.add("user-is-tabbing");
+    }
+    toggleTabbingOff() {
+        this.isTabbing = false;
+        this.linkEl && this.linkEl.classList.add("sr-only");
+        this.linkEl && this.linkEl.classList.remove("user-is-tabbing");
+    }
+    componentWillLoad() {
+        if (this.placeholder === "") {
+            console.error("You must set the placeholder property for the wm-search component.");
+        }
+        if (this.label === "") {
+            console.error("You must set the label property for the wm-search component.");
+        }
+        this.hookToModal();
+        handleDisabledAttribute(this.el, this.isDisabled);
+    }
+    hookToModal() {
+        // if the search is in a modal we want to clear the input when the modal closes
+        let el = this.el;
+        while (!!el) {
+            if (el.tagName === "WM-MODAL") {
+                this.parentModal = el;
+            }
+            el = el.parentElement;
+        }
+        if (this.parentModal) {
+            const events = ["wmModalCloseTriggered", "wmModalPrimaryTriggered", "wmModalSecondaryTriggered"];
+            events.map((event) => {
+                this.parentModal.addEventListener(event, () => {
+                    this.updateValue("");
+                });
+            });
+        }
+    }
+    // this undocumented method is needed in hookToModal (needs to be exposed so we can set the callback func)
+    async updateValue(value) {
+        this.value = value;
+        //For search-and-find, the results should always restart at "[1 or 0] of ..." after any new input.
+        //Reset the highlight count here just in case the new value doesn't end up changing the number of results.
+        this.resetHighlightCountToStart();
+        // Results should be announced at every input, even if no change in results occurred
+        this.announceResults();
+    }
+    handleNumResultsUpdate() {
+        this.resetHighlightCountToStart();
+        if (this.value) {
+            this.announceResults();
+        }
+    }
+    handleDisabledChange() {
+        handleDisabledAttribute(this.el, this.isDisabled);
+    }
+    resetHighlightCountToStart() {
+        if (this.searchType === "find") {
+            this.highlightedNum = this.numResults ? 1 : 0;
+        }
+    }
+    announce(message) {
+        if (this.resultsLiveRegion.textContent === message) {
+            message += "\u00A0";
+        }
+        this.announcement = message;
+    }
+    announceResults() {
+        window.requestAnimationFrame(() => {
+            // requestAnimationFrame to allow all changes to occur before announcing results
+            let messageToAnnounce = this.resultCount;
+            // if a result is found, also include it after the liveregion message
+            if (this.searchType === "find" && this.highlightedName) {
+                messageToAnnounce += `, ${this.highlightedName}`;
+            }
+            this.announce(messageToAnnounce);
+        });
+    }
+    changeHighlightedNum(newNum) {
+        if (this.numResults) {
+            if (newNum < 1) {
+                // we were on the first item, going down: go to last item
+                this.highlightedNum = this.numResults;
+            }
+            else if (newNum > this.numResults) {
+                // we were on the last item, going up: go to first item
+                this.highlightedNum = 1;
+            }
+            else {
+                this.highlightedNum = newNum;
+            }
+            this.wmSearchBrowseResults.emit({ position: this.highlightedNum });
+            this.announceResults();
+        }
+    }
+    handleBlur() {
+        if (this.previousBlurredValue !== this.value) {
+            this.wmSearchValueChanged.emit({ value: this.value });
+        }
+        this.previousBlurredValue = this.value;
+    }
+    /**
+     * Functions that return elements specifically for search-and-find.
+     */
+    renderResultsAndBrowseButtons() {
+        return (h("div", { class: "wm-find-elements" }, h("div", { id: "results-display", class: "results" }, !!this.value && this.resultCount), h("div", { class: "wm-button-collection" }, h("wm-button", { "button-type": "icononly", icon: "#move-up", tooltip: globalMessages.previous, "tooltip-position": "bottom", onClick: () => this.changeHighlightedNum(this.highlightedNum - 1), disabled: this.isDisabled || this.numResults < 2, "label-for-identical-buttons": intl.formatMessage({
+                id: "search.previousResult",
+                defaultMessage: "Press to hear previous matching result",
+            }) }), h("wm-button", { "button-type": "icononly", icon: "#move-down", tooltip: globalMessages.next, "tooltip-position": "bottom", onClick: () => this.changeHighlightedNum(this.highlightedNum + 1), disabled: this.isDisabled || this.numResults < 2, "label-for-identical-buttons": intl.formatMessage({
+                id: "search.nextResult",
+                defaultMessage: "Press to hear next matching result",
+            }) }))));
+    }
+    renderJumpToLink() {
+        if (this.numResults && this.highlightedId) {
+            return (h("a", { ref: (el) => (this.linkEl = el), href: `#${this.highlightedId}`, class: "jump-results sr-only" }, intl.formatMessage({
+                id: "search.jumpToResult",
+                defaultMessage: "Jump to search result in list",
+            })));
+        }
+        else {
+            return null;
+        }
+    }
+    /**
+     * End search and find render helpers
+     */
+    render() {
+        return (h(Host, { key: '17f77ed996d830b331078d35172485ddd1b3815a' }, h("div", { key: 'eaa5da92ed2154b3660fb0c888e43f0853f5bd0d', id: "wm-search-wrapper", class: `wm-search-wrapper ${this.searchType}` }, h("input", { key: '8c25d6adae20a36ce5ae73ae79d114555f608d8a', 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: 'bc41a6fe9a84996ebca49f2a6fc87d45703ef89c', class: "svg-icon svg-search" }), this.searchType === "find" && this.renderResultsAndBrowseButtons(), h("div", { key: '0c7f0fb0d7b887b3e9abd6a0eb06076e626aea28', 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"; }
+    static get delegatesFocus() { return true; }
+    static get originalStyleUrls() {
+        return {
+            "$": ["wm-search.scss"]
+        };
+    }
+    static get styleUrls() {
+        return {
+            "$": ["wm-search.css"]
+        };
+    }
+    static get properties() {
+        return {
+            "searchType": {
+                "type": "string",
+                "mutable": true,
+                "complexType": {
+                    "original": "\"basic\" | \"find\"",
+                    "resolved": "\"basic\" | \"find\"",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "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",
+                "reflect": false,
+                "defaultValue": "\"basic\""
+            },
+            "disabled": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Disables the input, preventing all interaction."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
+                    "text": ""
+                },
+                "attribute": "disabled",
+                "reflect": true,
+                "defaultValue": "false"
+            },
+            "placeholder": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Placeholder text displayed inside the empty input."
+                        }, {
+                            "name": "required",
+                            "text": undefined
+                        }],
+                    "text": ""
+                },
+                "attribute": "placeholder",
+                "reflect": false,
+                "defaultValue": "\"\""
+            },
+            "label": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "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",
+                "reflect": false,
+                "defaultValue": "\"\""
+            },
+            "numResults": {
+                "type": "number",
+                "mutable": true,
+                "complexType": {
+                    "original": "number",
+                    "resolved": "number",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "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",
+                "reflect": false,
+                "defaultValue": "0"
+            },
+            "value": {
+                "type": "string",
+                "mutable": true,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "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,
+                "defaultValue": "\"\""
+            },
+            "highlightedId": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "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,
+                "defaultValue": "\"\""
+            },
+            "highlightedName": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string | null",
+                    "resolved": "null | string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "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",
+                "reflect": false,
+                "defaultValue": "null"
+            }
+        };
+    }
+    static get states() {
+        return {
+            "isTabbing": {},
+            "highlightedNum": {},
+            "previousBlurredValue": {},
+            "parentModal": {},
+            "announcement": {}
+        };
+    }
+    static get events() {
+        return [{
+                "method": "wmSearchBrowseResults",
+                "name": "wmSearchBrowseResults",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "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 }",
+                    "resolved": "{ position: number; }",
+                    "references": {}
+                }
+            }, {
+                "method": "wmSearchValueChanged",
+                "name": "wmSearchValueChanged",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "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": {
+                    "original": "{ value: string }",
+                    "resolved": "{ value: string; }",
+                    "references": {}
+                }
+            }];
+    }
+    static get methods() {
+        return {
+            "updateValue": {
+                "complexType": {
+                    "signature": "(value: string) => Promise<void>",
+                    "parameters": [{
+                            "name": "value",
+                            "type": "string",
+                            "docs": ""
+                        }],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<void>"
+                },
+                "docs": {
+                    "text": "",
+                    "tags": []
+                }
+            }
+        };
+    }
+    static get elementRef() { return "el"; }
+    static get watchers() {
+        return [{
+                "propName": "numResults",
+                "methodName": "handleNumResultsUpdate"
+            }, {
+                "propName": "disabled",
+                "methodName": "handleDisabledChange"
+            }];
+    }
+    static get listeners() {
+        return [{
+                "name": "wmUserIsTabbing",
+                "method": "toggleTabbingOn",
+                "target": "window",
+                "capture": false,
+                "passive": false
+            }, {
+                "name": "wmUserIsNotTabbing",
+                "method": "toggleTabbingOff",
+                "target": "window",
+                "capture": false,
+                "passive": false
+            }];
+    }
+}