@radarlabs/plugin-autocomplete 5.0.0-beta.5 → 5.0.0-beta.6

package/cdn/radar-autocomplete.js

@@ -1,6 +1,7 @@
 (function (Radar) {
     'use strict';
 
+    /** error thrown when the autocomplete container element is not found in the DOM */
     class RadarAutocompleteContainerNotFound extends Radar.RadarError {
         constructor(message) {
             super(message);
@@ -65,6 +66,7 @@
   </svg>`.trim();
         return `data:image/svg+xml;charset=utf-8,${svg}`;
     };
+    /** address autocomplete UI widget with keyboard navigation and result display */
     class AutocompleteUI {
         constructor(options, ctx) {
             this.ctx = ctx;
@@ -72,7 +74,7 @@
             this.config = Object.assign({}, defaultAutocompleteOptions, options);
             // setup state
             this.isOpen = false;
-            this.debouncedFetchResults = this.debounce(this.fetchResults, this.config.debounceMS);
+            this.debouncedFetchResults = this.debounce(this.fetchResults.bind(this), this.config.debounceMS);
             this.results = [];
             this.highlightedIndex = -1;
             // set threshold alias
@@ -119,7 +121,7 @@
                 this.inputField = containerEL;
                 // append to dom
                 this.wrapper.appendChild(this.resultsList);
-                containerEL.parentNode.appendChild(this.wrapper);
+                containerEL.parentNode?.appendChild(this.wrapper);
             }
             else {
                 // if container is not an input, create new input and append to container
@@ -155,6 +157,7 @@
             }
             Logger.debug('AutocompleteUI initialized with options', this.config);
         }
+        /** handle input field changes and trigger debounced search */
         handleInput() {
             const { Logger } = this.ctx;
             // Fetch autocomplete results and display them
@@ -180,25 +183,18 @@
         }
         debounce(fn, delay) {
             let timeoutId;
-            let resolveFn;
-            let rejectFn;
+            let resolveFn = null;
+            let rejectFn = null;
             return (...args) => {
                 clearTimeout(timeoutId);
                 timeoutId = setTimeout(() => {
-                    const result = fn.apply(this, args);
-                    if (result instanceof Promise) {
-                        result
-                            .then((value) => {
-                            if (resolveFn) {
-                                resolveFn(value);
-                            }
-                        })
-                            .catch((error) => {
-                            if (rejectFn) {
-                                rejectFn(error);
-                            }
-                        });
-                    }
+                    fn(...args)
+                        .then((value) => {
+                        resolveFn?.(value);
+                    })
+                        .catch((error) => {
+                        rejectFn?.(error);
+                    });
                 }, delay);
                 return new Promise((resolve, reject) => {
                     resolveFn = resolve;
@@ -206,6 +202,11 @@
                 });
             };
         }
+        /**
+         * fetch autocomplete results from the Radar API
+         * @param query - the search query string
+         * @returns matching addresses
+         */
         async fetchResults(query) {
             const { apis } = this.ctx;
             const { limit, layers, countryCode, expandUnits, mailable, lang, postalCode, onRequest } = this.config;
@@ -228,6 +229,10 @@
             const { addresses } = await apis.Search.autocomplete(params, 'autocomplete-ui');
             return addresses;
         }
+        /**
+         * render autocomplete results in the dropdown
+         * @param results - array of address results to display
+         */
         displayResults(results) {
             // Clear the previous results
             this.clearResultsList();
@@ -246,7 +251,7 @@
                 li.setAttribute('id', `${CLASSNAMES.RESULTS_ITEM}}-${index}`);
                 // construct result with bolded label
                 let listContent;
-                if (result.formattedAddress.includes(result.addressLabel) && result.layer !== 'postalCode') {
+                if (result.formattedAddress?.includes(result.addressLabel) && result.layer !== 'postalCode') {
                     // if addressLabel is contained in the formatted address, bold the address label
                     const regex = new RegExp(`(${result.addressLabel}),?`);
                     listContent = result.formattedAddress.replace(regex, '<b>$1</b>');
@@ -292,6 +297,7 @@
                 this.resultsList.appendChild(noResultsText);
             }
         }
+        /** open the results dropdown */
         open() {
             if (this.isOpen) {
                 return;
@@ -300,6 +306,7 @@
             this.resultsList.removeAttribute('hidden');
             this.isOpen = true;
         }
+        /** close the results dropdown and clear highlighted state */
         close(e) {
             if (!this.isOpen) {
                 return;
@@ -316,6 +323,10 @@
                 this.clearResultsList();
             }, linkClick ? 100 : 0);
         }
+        /**
+         * highlight a result by index with wrap-around navigation
+         * @param index - the result index to highlight
+         */
         goTo(index) {
             if (!this.isOpen || !this.results.length) {
                 return;
@@ -370,6 +381,10 @@
                     break;
             }
         }
+        /**
+         * select a result by index and populate the input field
+         * @param index - the result index to select
+         */
         select(index) {
             const { Logger } = this.ctx;
             const result = this.results[index];
@@ -378,7 +393,7 @@
                 return;
             }
             let inputValue;
-            if (result.formattedAddress.includes(result.addressLabel)) {
+            if (result.formattedAddress?.includes(result.addressLabel)) {
                 inputValue = result.formattedAddress;
             }
             else {
@@ -393,11 +408,12 @@
             // clear results list
             this.close();
         }
+        /** clear the results list DOM and reset results array */
         clearResultsList() {
             this.resultsList.innerHTML = '';
             this.results = [];
         }
-        // remove elements from DOM
+        /** remove the autocomplete widget from the DOM */
         remove() {
             const { Logger } = this.ctx;
             Logger.debug('AutocompleteUI removed.');
@@ -405,6 +421,11 @@
             this.resultsList.remove();
             this.wrapper.remove();
         }
+        /**
+         * set the `near` location bias for autocomplete requests
+         * @param near - location string, Location object, or null to clear
+         * @returns this instance for chaining
+         */
         setNear(near) {
             if (near === undefined || near === null) {
                 this.near = undefined;
@@ -417,21 +438,41 @@
             }
             return this;
         }
+        /**
+         * set the input placeholder text
+         * @param placeholder - new placeholder string
+         * @returns this instance for chaining
+         */
         setPlaceholder(placeholder) {
             this.config.placeholder = placeholder;
             this.inputField.placeholder = placeholder;
             return this;
         }
+        /**
+         * set the disabled state of the input
+         * @param disabled - whether to disable the input
+         * @returns this instance for chaining
+         */
         setDisabled(disabled) {
             this.config.disabled = disabled;
             this.inputField.disabled = disabled;
             return this;
         }
+        /**
+         * toggle responsive width mode
+         * @param responsive - whether to use responsive layout
+         * @returns this instance for chaining
+         */
         setResponsive(responsive) {
             this.config.responsive = responsive;
             setWidth(this.wrapper, this.config);
             return this;
         }
+        /**
+         * set the widget width
+         * @param width - width in px, CSS string, or null to reset
+         * @returns this instance for chaining
+         */
         setWidth(width) {
             if (width === null) {
                 this.config.width = undefined;
@@ -442,6 +483,11 @@
             setWidth(this.wrapper, this.config);
             return this;
         }
+        /**
+         * set the max height of the results dropdown
+         * @param height - height in px, CSS string, or null to reset
+         * @returns this instance for chaining
+         */
         setMaxHeight(height) {
             if (height === null) {
                 this.config.maxHeight = undefined;
@@ -452,15 +498,30 @@
             setHeight(this.resultsList, this.config);
             return this;
         }
+        /**
+         * set the minimum character count to trigger autocomplete
+         * @param minCharacters - character threshold
+         * @returns this instance for chaining
+         */
         setMinCharacters(minCharacters) {
             this.config.minCharacters = minCharacters;
             this.config.threshold = minCharacters;
             return this;
         }
+        /**
+         * set the maximum number of results
+         * @param limit - result count limit
+         * @returns this instance for chaining
+         */
         setLimit(limit) {
             this.config.limit = limit;
             return this;
         }
+        /**
+         * set the language for autocomplete results
+         * @param lang - language code or null to clear
+         * @returns this instance for chaining
+         */
         setLang(lang) {
             if (lang === null) {
                 this.config.lang = undefined;
@@ -470,6 +531,11 @@
             }
             return this;
         }
+        /**
+         * set a postal code bias for autocomplete requests
+         * @param postalCode - postal code string or null to clear
+         * @returns this instance for chaining
+         */
         setPostalCode(postalCode) {
             if (postalCode === null) {
                 this.config.postalCode = undefined;
@@ -479,6 +545,11 @@
             }
             return this;
         }
+        /**
+         * toggle marker icons in result items
+         * @param showMarkers - whether to show markers
+         * @returns this instance for chaining
+         */
         setShowMarkers(showMarkers) {
             this.config.showMarkers = showMarkers;
             if (showMarkers) {
@@ -504,6 +575,11 @@
             }
             return this;
         }
+        /**
+         * set the color of marker icons in result items
+         * @param color - CSS color string
+         * @returns this instance for chaining
+         */
         setMarkerColor(color) {
             this.config.markerColor = color;
             const marker = this.resultsList.getElementsByClassName(CLASSNAMES.RESULTS_MARKER);
@@ -512,6 +588,11 @@
             }
             return this;
         }
+        /**
+         * toggle hiding results when input loses focus
+         * @param hideResultsOnBlur - whether to hide on blur
+         * @returns this instance for chaining
+         */
         setHideResultsOnBlur(hideResultsOnBlur) {
             this.config.hideResultsOnBlur = hideResultsOnBlur;
             if (hideResultsOnBlur) {
@@ -524,8 +605,19 @@
         }
     }
 
-    var version = '5.0.0-beta.5';
+    var version = '5.0.0-beta.6';
 
+    /**
+     * create the Radar autocomplete plugin
+     *
+     * @returns a plugin that adds `Radar.ui.autocomplete()` method
+     *
+     * @example
+     * ```ts
+     * import { createAutocompletePlugin } from '@radarlabs/plugin-autocomplete';
+     * Radar.registerPlugin(createAutocompletePlugin());
+     * ```
+     */
     function createAutocompletePlugin() {
         return {
             name: 'autocomplete',

package/cdn/radar-autocomplete.min.js

@@ -1 +1 @@
-!function(t){"use strict";class e extends t.RadarError{constructor(t){super(t),this.name="RadarAutocompleteContainerNotFound",this.status="CONTAINER_NOT_FOUND"}}const s="radar-autocomplete-wrapper",i="radar-autocomplete-input",r="radar-autocomplete-search-icon",n="radar-autocomplete-results-list",a="radar-autocomplete-results-item",l="radar-autocomplete-results-marker",o="radar-autocomplete-results-item-selected",h="radar-powered",d="radar-no-results",c={container:"autocomplete",debounceMS:200,minCharacters:3,limit:8,placeholder:"Search address",responsive:!0,disabled:!1,showMarkers:!0,hideResultsOnBlur:!0},u=t=>"number"==typeof t?`${t}px`:t,p=(t,e)=>{if(e.responsive)return t.style.width="100%",void(e.width&&(t.style.maxWidth=u(e.width)));t.style.width=u(e.width||400),t.style.removeProperty("max-width")},g=(t,e)=>{e.maxHeight&&(t.style.maxHeight=u(e.maxHeight),t.style.overflowY="auto")},m=(t="#ACBDC8")=>`data:image/svg+xml;charset=utf-8,${`<svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">\n    <path d="M12.5704 6.57036C12.5704 4.11632 10.6342 2.11257 8.21016 2C8.14262 2 8.06757 2 8.00003 2C7.93249 2 7.85744 2 7.7899 2C5.35838 2.11257 3.42967 4.11632 3.42967 6.57036C3.42967 6.60037 3.42967 6.6379 3.42967 6.66792C3.42967 6.69794 3.42967 6.73546 3.42967 6.76548C3.42967 9.46717 7.09196 13.3621 7.4672 13.7598C7.61729 13.9174 7.84994 14 8.00003 14C8.15012 14 8.38277 13.9174 8.53286 13.7598C8.9156 13.3621 12.5704 9.46717 12.5704 6.76548C12.5704 6.72795 12.5704 6.69794 12.5704 6.66792C12.5704 6.6379 12.5704 6.60037 12.5704 6.57036ZM7.99252 8.28893C7.04693 8.28893 6.27395 7.52345 6.27395 6.57036C6.27395 5.61726 7.03943 4.85178 7.99252 4.85178C8.94562 4.85178 9.7111 5.61726 9.7111 6.57036C9.7111 7.52345 8.94562 8.28893 7.99252 8.28893Z" fill="${t.replace("#","%23")}"/>\n  </svg>`.trim()}`;class f{constructor(t,a){this.ctx=a;const{Logger:l}=this.ctx;let o;if(this.config=Object.assign({},c,t),this.isOpen=!1,this.debouncedFetchResults=this.debounce(this.fetchResults,this.config.debounceMS),this.results=[],this.highlightedIndex=-1,void 0!==this.config.threshold&&(this.config.minCharacters=this.config.threshold,l.warn('AutocompleteUI option "threshold" is deprecated, use "minCharacters" instead.')),t.near&&("string"==typeof t.near?this.near=t.near:this.near=`${t.near.latitude},${t.near.longitude}`),o="string"==typeof this.config.container?document.getElementById(this.config.container):this.config.container,!o)throw new e(`Could not find container element: ${this.config.container}`);if(this.container=o,this.wrapper=document.createElement("div"),this.wrapper.classList.add(s),this.wrapper.style.display=this.config.responsive?"block":"inline-block",p(this.wrapper,this.config),this.resultsList=document.createElement("ul"),this.resultsList.classList.add(n),this.resultsList.setAttribute("id",n),this.resultsList.setAttribute("role","listbox"),this.resultsList.setAttribute("aria-live","polite"),this.resultsList.setAttribute("aria-label","Search results"),g(this.resultsList,this.config),"INPUT"===o.nodeName)this.inputField=o,this.wrapper.appendChild(this.resultsList),o.parentNode.appendChild(this.wrapper);else{this.inputField=document.createElement("input"),this.inputField.classList.add(i),this.inputField.placeholder=this.config.placeholder,this.inputField.type="text",this.inputField.disabled=this.config.disabled;const t=document.createElement("div");t.classList.add(r),this.wrapper.appendChild(this.inputField),this.wrapper.appendChild(this.resultsList),this.wrapper.appendChild(t),this.container.appendChild(this.wrapper)}this.inputField.setAttribute("autocomplete","off"),this.inputField.setAttribute("role","combobox"),this.inputField.setAttribute("aria-controls",n),this.inputField.setAttribute("aria-expanded","false"),this.inputField.setAttribute("aria-haspopup","listbox"),this.inputField.setAttribute("aria-autocomplete","list"),this.inputField.setAttribute("aria-activedescendant",""),this.inputField.addEventListener("input",this.handleInput.bind(this)),this.inputField.addEventListener("keydown",this.handleKeyboardNavigation.bind(this)),this.config.hideResultsOnBlur&&this.inputField.addEventListener("blur",this.close.bind(this),!0),l.debug("AutocompleteUI initialized with options",this.config)}handleInput(){const{Logger:t}=this.ctx,e=this.inputField.value;e.length<this.config.minCharacters||this.debouncedFetchResults(e).then((t=>{const e=this.config.onResults;e&&e(t),this.displayResults(t)})).catch((e=>{t.warn(`Autocomplete ui error: ${e.message}`);const s=this.config.onError;s&&s(e)}))}debounce(t,e){let s,i,r;return(...n)=>(clearTimeout(s),s=setTimeout((()=>{const e=t.apply(this,n);e instanceof Promise&&e.then((t=>{i&&i(t)})).catch((t=>{r&&r(t)}))}),e),new Promise(((t,e)=>{i=t,r=e})))}async fetchResults(t){const{apis:e}=this.ctx,{limit:s,layers:i,countryCode:r,expandUnits:n,mailable:a,lang:l,postalCode:o,onRequest:h}=this.config,d={query:t,limit:s,layers:i,countryCode:r,expandUnits:n,mailable:a,lang:l,postalCode:o};this.near&&(d.near=this.near),h&&h(d);const{addresses:c}=await e.Search.autocomplete(d,"autocomplete-ui");return c}displayResults(t){let e;if(this.clearResultsList(),this.results=t,this.config.showMarkers&&(e=document.createElement("img"),e.classList.add(l),e.setAttribute("src",m(this.config.markerColor))),t.forEach(((t,s)=>{const i=document.createElement("li");let r;if(i.classList.add(a),i.setAttribute("role","option"),i.setAttribute("id",`${a}}-${s}`),t.formattedAddress.includes(t.addressLabel)&&"postalCode"!==t.layer){const e=new RegExp(`(${t.addressLabel}),?`);r=t.formattedAddress.replace(e,"<b>$1</b>")}else{r=`<b>${t.placeLabel||t.addressLabel}</b> ${t.formattedAddress}`}i.innerHTML=r,e&&i.prepend(e.cloneNode()),i.addEventListener("mousedown",(()=>{this.select(s)})),this.resultsList.appendChild(i)})),this.open(),t.length>0){const t=document.createElement("a");t.href="https://radar.com?ref=powered_by_radar",t.target="_blank",this.poweredByLink=t;const e=document.createElement("span");e.textContent="Powered by",t.appendChild(e);const s=document.createElement("span");s.id="radar-powered-logo",s.textContent="Radar",t.appendChild(s);const i=document.createElement("div");i.classList.add(h),i.appendChild(t),this.resultsList.appendChild(i)}else{const t=document.createElement("div");t.classList.add(d),t.textContent="No results",this.resultsList.appendChild(t)}}open(){this.isOpen||(this.inputField.setAttribute("aria-expanded","true"),this.resultsList.removeAttribute("hidden"),this.isOpen=!0)}close(t){if(!this.isOpen)return;const e=t&&t.relatedTarget===this.poweredByLink;setTimeout((()=>{this.inputField.setAttribute("aria-expanded","false"),this.inputField.setAttribute("aria-activedescendant",""),this.resultsList.setAttribute("hidden",""),this.highlightedIndex=-1,this.isOpen=!1,this.clearResultsList()}),e?100:0)}goTo(t){if(!this.isOpen||!this.results.length)return;t<0?t=this.results.length-1:t>=this.results.length&&(t=0);const e=this.resultsList.getElementsByTagName("li");this.highlightedIndex>-1&&e[this.highlightedIndex].classList.remove(o),e[t].classList.add(o),this.inputField.setAttribute("aria-activedescendant",`${a}-${t}`),this.highlightedIndex=t}handleKeyboardNavigation(t){let e=t.key;if(this.isOpen)switch("Tab"===e&&t.shiftKey&&(e="ArrowUp"),e){case"Tab":case"ArrowDown":t.preventDefault(),this.goTo(this.highlightedIndex+1);break;case"ArrowUp":t.preventDefault(),this.goTo(this.highlightedIndex-1);break;case"Enter":this.select(this.highlightedIndex);break;case"Esc":this.close()}}select(t){const{Logger:e}=this.ctx,s=this.results[t];if(!s)return void e.warn(`No autocomplete result found at index: ${t}`);let i;if(s.formattedAddress.includes(s.addressLabel))i=s.formattedAddress;else{i=`${s.placeLabel||s.addressLabel}, ${s.formattedAddress}`}this.inputField.value=i;const r=this.config.onSelection;r&&r(s),this.close()}clearResultsList(){this.resultsList.innerHTML="",this.results=[]}remove(){const{Logger:t}=this.ctx;t.debug("AutocompleteUI removed."),this.inputField.remove(),this.resultsList.remove(),this.wrapper.remove()}setNear(t){return this.near=null==t?void 0:"string"==typeof t?t:`${t.latitude},${t.longitude}`,this}setPlaceholder(t){return this.config.placeholder=t,this.inputField.placeholder=t,this}setDisabled(t){return this.config.disabled=t,this.inputField.disabled=t,this}setResponsive(t){return this.config.responsive=t,p(this.wrapper,this.config),this}setWidth(t){return null===t?this.config.width=void 0:"string"!=typeof t&&"number"!=typeof t||(this.config.width=t),p(this.wrapper,this.config),this}setMaxHeight(t){return null===t?this.config.maxHeight=void 0:"string"!=typeof t&&"number"!=typeof t||(this.config.maxHeight=t),g(this.resultsList,this.config),this}setMinCharacters(t){return this.config.minCharacters=t,this.config.threshold=t,this}setLimit(t){return this.config.limit=t,this}setLang(t){return null===t?this.config.lang=void 0:"string"==typeof t&&(this.config.lang=t),this}setPostalCode(t){return null===t?this.config.postalCode=void 0:"string"==typeof t&&(this.config.postalCode=t),this}setShowMarkers(t){if(this.config.showMarkers=t,t){const t=document.createElement("img");t.classList.add(l),t.setAttribute("src",m(this.config.markerColor));const e=this.resultsList.getElementsByTagName("li");for(let s=0;s<e.length;s++){e[s].getElementsByClassName(l)[0]||e[s].prepend(t.cloneNode())}}else{const t=this.resultsList.getElementsByTagName("li");for(let e=0;e<t.length;e++){const s=t[e].getElementsByClassName(l)[0];s&&s.remove()}}return this}setMarkerColor(t){this.config.markerColor=t;const e=this.resultsList.getElementsByClassName(l);for(let s=0;s<e.length;s++)e[s].setAttribute("src",m(t));return this}setHideResultsOnBlur(t){return this.config.hideResultsOnBlur=t,t?this.inputField.addEventListener("blur",this.close.bind(this),!0):this.inputField.removeEventListener("blur",this.close.bind(this),!0),this}}t.registerPlugin({name:"autocomplete",version:"5.0.0-beta.5",install(t){const e=t.Radar.ui||{};t.Radar.ui={...e,autocomplete:e=>new f(e,t)}}})}(Radar);
+!function(t){"use strict";class e extends t.RadarError{constructor(t){super(t),this.name="RadarAutocompleteContainerNotFound",this.status="CONTAINER_NOT_FOUND"}}const s="radar-autocomplete-wrapper",i="radar-autocomplete-input",r="radar-autocomplete-search-icon",n="radar-autocomplete-results-list",a="radar-autocomplete-results-item",l="radar-autocomplete-results-marker",o="radar-autocomplete-results-item-selected",h="radar-powered",d="radar-no-results",c={container:"autocomplete",debounceMS:200,minCharacters:3,limit:8,placeholder:"Search address",responsive:!0,disabled:!1,showMarkers:!0,hideResultsOnBlur:!0},u=t=>"number"==typeof t?`${t}px`:t,p=(t,e)=>{if(e.responsive)return t.style.width="100%",void(e.width&&(t.style.maxWidth=u(e.width)));t.style.width=u(e.width||400),t.style.removeProperty("max-width")},g=(t,e)=>{e.maxHeight&&(t.style.maxHeight=u(e.maxHeight),t.style.overflowY="auto")},m=(t="#ACBDC8")=>`data:image/svg+xml;charset=utf-8,${`<svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">\n    <path d="M12.5704 6.57036C12.5704 4.11632 10.6342 2.11257 8.21016 2C8.14262 2 8.06757 2 8.00003 2C7.93249 2 7.85744 2 7.7899 2C5.35838 2.11257 3.42967 4.11632 3.42967 6.57036C3.42967 6.60037 3.42967 6.6379 3.42967 6.66792C3.42967 6.69794 3.42967 6.73546 3.42967 6.76548C3.42967 9.46717 7.09196 13.3621 7.4672 13.7598C7.61729 13.9174 7.84994 14 8.00003 14C8.15012 14 8.38277 13.9174 8.53286 13.7598C8.9156 13.3621 12.5704 9.46717 12.5704 6.76548C12.5704 6.72795 12.5704 6.69794 12.5704 6.66792C12.5704 6.6379 12.5704 6.60037 12.5704 6.57036ZM7.99252 8.28893C7.04693 8.28893 6.27395 7.52345 6.27395 6.57036C6.27395 5.61726 7.03943 4.85178 7.99252 4.85178C8.94562 4.85178 9.7111 5.61726 9.7111 6.57036C9.7111 7.52345 8.94562 8.28893 7.99252 8.28893Z" fill="${t.replace("#","%23")}"/>\n  </svg>`.trim()}`;class f{constructor(t,a){this.ctx=a;const{Logger:l}=this.ctx;let o;if(this.config=Object.assign({},c,t),this.isOpen=!1,this.debouncedFetchResults=this.debounce(this.fetchResults.bind(this),this.config.debounceMS),this.results=[],this.highlightedIndex=-1,void 0!==this.config.threshold&&(this.config.minCharacters=this.config.threshold,l.warn('AutocompleteUI option "threshold" is deprecated, use "minCharacters" instead.')),t.near&&("string"==typeof t.near?this.near=t.near:this.near=`${t.near.latitude},${t.near.longitude}`),o="string"==typeof this.config.container?document.getElementById(this.config.container):this.config.container,!o)throw new e(`Could not find container element: ${this.config.container}`);if(this.container=o,this.wrapper=document.createElement("div"),this.wrapper.classList.add(s),this.wrapper.style.display=this.config.responsive?"block":"inline-block",p(this.wrapper,this.config),this.resultsList=document.createElement("ul"),this.resultsList.classList.add(n),this.resultsList.setAttribute("id",n),this.resultsList.setAttribute("role","listbox"),this.resultsList.setAttribute("aria-live","polite"),this.resultsList.setAttribute("aria-label","Search results"),g(this.resultsList,this.config),"INPUT"===o.nodeName)this.inputField=o,this.wrapper.appendChild(this.resultsList),o.parentNode?.appendChild(this.wrapper);else{this.inputField=document.createElement("input"),this.inputField.classList.add(i),this.inputField.placeholder=this.config.placeholder,this.inputField.type="text",this.inputField.disabled=this.config.disabled;const t=document.createElement("div");t.classList.add(r),this.wrapper.appendChild(this.inputField),this.wrapper.appendChild(this.resultsList),this.wrapper.appendChild(t),this.container.appendChild(this.wrapper)}this.inputField.setAttribute("autocomplete","off"),this.inputField.setAttribute("role","combobox"),this.inputField.setAttribute("aria-controls",n),this.inputField.setAttribute("aria-expanded","false"),this.inputField.setAttribute("aria-haspopup","listbox"),this.inputField.setAttribute("aria-autocomplete","list"),this.inputField.setAttribute("aria-activedescendant",""),this.inputField.addEventListener("input",this.handleInput.bind(this)),this.inputField.addEventListener("keydown",this.handleKeyboardNavigation.bind(this)),this.config.hideResultsOnBlur&&this.inputField.addEventListener("blur",this.close.bind(this),!0),l.debug("AutocompleteUI initialized with options",this.config)}handleInput(){const{Logger:t}=this.ctx,e=this.inputField.value;e.length<this.config.minCharacters||this.debouncedFetchResults(e).then((t=>{const e=this.config.onResults;e&&e(t),this.displayResults(t)})).catch((e=>{t.warn(`Autocomplete ui error: ${e.message}`);const s=this.config.onError;s&&s(e)}))}debounce(t,e){let s,i=null,r=null;return(...n)=>(clearTimeout(s),s=setTimeout((()=>{t(...n).then((t=>{i?.(t)})).catch((t=>{r?.(t)}))}),e),new Promise(((t,e)=>{i=t,r=e})))}async fetchResults(t){const{apis:e}=this.ctx,{limit:s,layers:i,countryCode:r,expandUnits:n,mailable:a,lang:l,postalCode:o,onRequest:h}=this.config,d={query:t,limit:s,layers:i,countryCode:r,expandUnits:n,mailable:a,lang:l,postalCode:o};this.near&&(d.near=this.near),h&&h(d);const{addresses:c}=await e.Search.autocomplete(d,"autocomplete-ui");return c}displayResults(t){let e;if(this.clearResultsList(),this.results=t,this.config.showMarkers&&(e=document.createElement("img"),e.classList.add(l),e.setAttribute("src",m(this.config.markerColor))),t.forEach(((t,s)=>{const i=document.createElement("li");let r;if(i.classList.add(a),i.setAttribute("role","option"),i.setAttribute("id",`${a}}-${s}`),t.formattedAddress?.includes(t.addressLabel)&&"postalCode"!==t.layer){const e=new RegExp(`(${t.addressLabel}),?`);r=t.formattedAddress.replace(e,"<b>$1</b>")}else{r=`<b>${t.placeLabel||t.addressLabel}</b> ${t.formattedAddress}`}i.innerHTML=r,e&&i.prepend(e.cloneNode()),i.addEventListener("mousedown",(()=>{this.select(s)})),this.resultsList.appendChild(i)})),this.open(),t.length>0){const t=document.createElement("a");t.href="https://radar.com?ref=powered_by_radar",t.target="_blank",this.poweredByLink=t;const e=document.createElement("span");e.textContent="Powered by",t.appendChild(e);const s=document.createElement("span");s.id="radar-powered-logo",s.textContent="Radar",t.appendChild(s);const i=document.createElement("div");i.classList.add(h),i.appendChild(t),this.resultsList.appendChild(i)}else{const t=document.createElement("div");t.classList.add(d),t.textContent="No results",this.resultsList.appendChild(t)}}open(){this.isOpen||(this.inputField.setAttribute("aria-expanded","true"),this.resultsList.removeAttribute("hidden"),this.isOpen=!0)}close(t){if(!this.isOpen)return;const e=t&&t.relatedTarget===this.poweredByLink;setTimeout((()=>{this.inputField.setAttribute("aria-expanded","false"),this.inputField.setAttribute("aria-activedescendant",""),this.resultsList.setAttribute("hidden",""),this.highlightedIndex=-1,this.isOpen=!1,this.clearResultsList()}),e?100:0)}goTo(t){if(!this.isOpen||!this.results.length)return;t<0?t=this.results.length-1:t>=this.results.length&&(t=0);const e=this.resultsList.getElementsByTagName("li");this.highlightedIndex>-1&&e[this.highlightedIndex].classList.remove(o),e[t].classList.add(o),this.inputField.setAttribute("aria-activedescendant",`${a}-${t}`),this.highlightedIndex=t}handleKeyboardNavigation(t){let e=t.key;if(this.isOpen)switch("Tab"===e&&t.shiftKey&&(e="ArrowUp"),e){case"Tab":case"ArrowDown":t.preventDefault(),this.goTo(this.highlightedIndex+1);break;case"ArrowUp":t.preventDefault(),this.goTo(this.highlightedIndex-1);break;case"Enter":this.select(this.highlightedIndex);break;case"Esc":this.close()}}select(t){const{Logger:e}=this.ctx,s=this.results[t];if(!s)return void e.warn(`No autocomplete result found at index: ${t}`);let i;if(s.formattedAddress?.includes(s.addressLabel))i=s.formattedAddress;else{i=`${s.placeLabel||s.addressLabel}, ${s.formattedAddress}`}this.inputField.value=i;const r=this.config.onSelection;r&&r(s),this.close()}clearResultsList(){this.resultsList.innerHTML="",this.results=[]}remove(){const{Logger:t}=this.ctx;t.debug("AutocompleteUI removed."),this.inputField.remove(),this.resultsList.remove(),this.wrapper.remove()}setNear(t){return this.near=null==t?void 0:"string"==typeof t?t:`${t.latitude},${t.longitude}`,this}setPlaceholder(t){return this.config.placeholder=t,this.inputField.placeholder=t,this}setDisabled(t){return this.config.disabled=t,this.inputField.disabled=t,this}setResponsive(t){return this.config.responsive=t,p(this.wrapper,this.config),this}setWidth(t){return null===t?this.config.width=void 0:"string"!=typeof t&&"number"!=typeof t||(this.config.width=t),p(this.wrapper,this.config),this}setMaxHeight(t){return null===t?this.config.maxHeight=void 0:"string"!=typeof t&&"number"!=typeof t||(this.config.maxHeight=t),g(this.resultsList,this.config),this}setMinCharacters(t){return this.config.minCharacters=t,this.config.threshold=t,this}setLimit(t){return this.config.limit=t,this}setLang(t){return null===t?this.config.lang=void 0:"string"==typeof t&&(this.config.lang=t),this}setPostalCode(t){return null===t?this.config.postalCode=void 0:"string"==typeof t&&(this.config.postalCode=t),this}setShowMarkers(t){if(this.config.showMarkers=t,t){const t=document.createElement("img");t.classList.add(l),t.setAttribute("src",m(this.config.markerColor));const e=this.resultsList.getElementsByTagName("li");for(let s=0;s<e.length;s++){e[s].getElementsByClassName(l)[0]||e[s].prepend(t.cloneNode())}}else{const t=this.resultsList.getElementsByTagName("li");for(let e=0;e<t.length;e++){const s=t[e].getElementsByClassName(l)[0];s&&s.remove()}}return this}setMarkerColor(t){this.config.markerColor=t;const e=this.resultsList.getElementsByClassName(l);for(let s=0;s<e.length;s++)e[s].setAttribute("src",m(t));return this}setHideResultsOnBlur(t){return this.config.hideResultsOnBlur=t,t?this.inputField.addEventListener("blur",this.close.bind(this),!0):this.inputField.removeEventListener("blur",this.close.bind(this),!0),this}}t.registerPlugin({name:"autocomplete",version:"5.0.0-beta.6",install(t){const e=t.Radar.ui||{};t.Radar.ui={...e,autocomplete:e=>new f(e,t)}}})}(Radar);

package/dist/autocomplete.d.ts

@@ -1,12 +1,13 @@
 import type { RadarAutocompleteUIOptions, RadarAutocompleteConfig } from './types';
-import type { Location, RadarPluginContext } from 'radar-sdk-js';
+import type { RadarAutocompleteAddress, Location, RadarPluginContext } from 'radar-sdk-js';
+/** address autocomplete UI widget with keyboard navigation and result display */
 declare class AutocompleteUI {
     private ctx;
     config: RadarAutocompleteConfig;
     isOpen: boolean;
-    results: any[];
+    results: RadarAutocompleteAddress[];
     highlightedIndex: number;
-    debouncedFetchResults: (...args: any[]) => Promise<any>;
+    debouncedFetchResults: (query: string) => Promise<RadarAutocompleteAddress[]>;
     near?: string;
     container: HTMLElement;
     inputField: HTMLInputElement;
@@ -14,29 +15,116 @@ declare class AutocompleteUI {
     wrapper: HTMLElement;
     poweredByLink?: HTMLElement;
     constructor(options: Partial<RadarAutocompleteUIOptions>, ctx: RadarPluginContext);
+    /** handle input field changes and trigger debounced search */
     handleInput(): void;
-    debounce(fn: Function, delay: number): (...args: any[]) => Promise<unknown>;
-    fetchResults(query: string): Promise<import("radar-sdk-js").RadarAutocompleteAddress[]>;
-    displayResults(results: any[]): void;
+    debounce<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => Promise<TReturn>, delay: number): (...args: TArgs) => Promise<TReturn>;
+    /**
+     * fetch autocomplete results from the Radar API
+     * @param query - the search query string
+     * @returns matching addresses
+     */
+    fetchResults(query: string): Promise<RadarAutocompleteAddress[]>;
+    /**
+     * render autocomplete results in the dropdown
+     * @param results - array of address results to display
+     */
+    displayResults(results: RadarAutocompleteAddress[]): void;
+    /** open the results dropdown */
     open(): void;
+    /** close the results dropdown and clear highlighted state */
     close(e?: FocusEvent): void;
+    /**
+     * highlight a result by index with wrap-around navigation
+     * @param index - the result index to highlight
+     */
     goTo(index: number): void;
     handleKeyboardNavigation(event: KeyboardEvent): void;
+    /**
+     * select a result by index and populate the input field
+     * @param index - the result index to select
+     */
     select(index: number): void;
+    /** clear the results list DOM and reset results array */
     clearResultsList(): void;
+    /** remove the autocomplete widget from the DOM */
     remove(): void;
+    /**
+     * set the `near` location bias for autocomplete requests
+     * @param near - location string, Location object, or null to clear
+     * @returns this instance for chaining
+     */
     setNear(near: string | Location | undefined | null): this;
+    /**
+     * set the input placeholder text
+     * @param placeholder - new placeholder string
+     * @returns this instance for chaining
+     */
     setPlaceholder(placeholder: string): this;
+    /**
+     * set the disabled state of the input
+     * @param disabled - whether to disable the input
+     * @returns this instance for chaining
+     */
     setDisabled(disabled: boolean): this;
+    /**
+     * toggle responsive width mode
+     * @param responsive - whether to use responsive layout
+     * @returns this instance for chaining
+     */
     setResponsive(responsive: boolean): this;
+    /**
+     * set the widget width
+     * @param width - width in px, CSS string, or null to reset
+     * @returns this instance for chaining
+     */
     setWidth(width: number | string | null): this;
+    /**
+     * set the max height of the results dropdown
+     * @param height - height in px, CSS string, or null to reset
+     * @returns this instance for chaining
+     */
     setMaxHeight(height: number | string | null): this;
+    /**
+     * set the minimum character count to trigger autocomplete
+     * @param minCharacters - character threshold
+     * @returns this instance for chaining
+     */
     setMinCharacters(minCharacters: number): this;
+    /**
+     * set the maximum number of results
+     * @param limit - result count limit
+     * @returns this instance for chaining
+     */
     setLimit(limit: number): this;
+    /**
+     * set the language for autocomplete results
+     * @param lang - language code or null to clear
+     * @returns this instance for chaining
+     */
     setLang(lang: string | null): this;
+    /**
+     * set a postal code bias for autocomplete requests
+     * @param postalCode - postal code string or null to clear
+     * @returns this instance for chaining
+     */
     setPostalCode(postalCode: string | null): this;
+    /**
+     * toggle marker icons in result items
+     * @param showMarkers - whether to show markers
+     * @returns this instance for chaining
+     */
     setShowMarkers(showMarkers: boolean): this;
+    /**
+     * set the color of marker icons in result items
+     * @param color - CSS color string
+     * @returns this instance for chaining
+     */
     setMarkerColor(color: string): this;
+    /**
+     * toggle hiding results when input loses focus
+     * @param hideResultsOnBlur - whether to hide on blur
+     * @returns this instance for chaining
+     */
     setHideResultsOnBlur(hideResultsOnBlur: boolean): this;
 }
 export default AutocompleteUI;

package/dist/errors.d.ts

@@ -1,4 +1,5 @@
 import { RadarError } from 'radar-sdk-js';
+/** error thrown when the autocomplete container element is not found in the DOM */
 export declare class RadarAutocompleteContainerNotFound extends RadarError {
     constructor(message: string);
 }

package/dist/index.d.ts

@@ -11,4 +11,15 @@ declare module 'radar-sdk-js' {
         let ui: RadarUI;
     }
 }
+/**
+ * create the Radar autocomplete plugin
+ *
+ * @returns a plugin that adds `Radar.ui.autocomplete()` method
+ *
+ * @example
+ * ```ts
+ * import { createAutocompletePlugin } from '@radarlabs/plugin-autocomplete';
+ * Radar.registerPlugin(createAutocompletePlugin());
+ * ```
+ */
 export declare function createAutocompletePlugin(): RadarPlugin;