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

package/src/autocomplete.ts

@@ -1,6 +1,6 @@
 import { RadarAutocompleteContainerNotFound } from './errors';
 import type { RadarAutocompleteUIOptions, RadarAutocompleteConfig } from './types';
-import type { RadarAutocompleteParams, Location, RadarPluginContext } from 'radar-sdk-js';
+import type { RadarAutocompleteAddress, RadarAutocompleteParams, Location, RadarPluginContext } from 'radar-sdk-js';
 
 const CLASSNAMES = {
   WRAPPER: 'radar-autocomplete-wrapper',
@@ -66,13 +66,14 @@ const getMarkerIcon = (color: string = "#ACBDC8") => {
 };
 
 
+/** address autocomplete UI widget with keyboard navigation and result display */
 class AutocompleteUI {
   private ctx: RadarPluginContext;
   config: RadarAutocompleteConfig;
   isOpen: boolean;
-  results: any[];
+  results: RadarAutocompleteAddress[];
   highlightedIndex: number;
-  debouncedFetchResults: (...args: any[]) => Promise<any>;
+  debouncedFetchResults: (query: string) => Promise<RadarAutocompleteAddress[]>;
   near?: string;
 
   // DOM elements
@@ -89,7 +90,7 @@ class AutocompleteUI {
 
     // 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;
 
@@ -141,7 +142,7 @@ class AutocompleteUI {
 
       // append to dom
       this.wrapper.appendChild(this.resultsList);
-      (containerEL.parentNode as any).appendChild(this.wrapper);
+      containerEL.parentNode?.appendChild(this.wrapper);
 
     } else {
       // if container is not an input, create new input and append to container
@@ -185,6 +186,7 @@ class AutocompleteUI {
     Logger.debug('AutocompleteUI initialized with options', this.config);
   }
 
+  /** handle input field changes and trigger debounced search */
   public handleInput() {
     const { Logger } = this.ctx;
 
@@ -195,14 +197,14 @@ class AutocompleteUI {
     }
 
     this.debouncedFetchResults(query)
-      .then((results: any[]) => {
+      .then((results) => {
         const onResults = this.config.onResults;
         if (onResults) {
           onResults(results);
         }
         this.displayResults(results);
       })
-      .catch((error) => {
+      .catch((error: Error) => {
         Logger.warn(`Autocomplete ui error: ${error.message}`);
         const onError = this.config.onError;
         if (onError) {
@@ -211,39 +213,39 @@ class AutocompleteUI {
       });
   }
 
-  public debounce(fn: Function, delay: number) {
-    let timeoutId: any;
-    let resolveFn: any;
-    let rejectFn: any;
+  public debounce<TArgs extends unknown[], TReturn>(
+    fn: (...args: TArgs) => Promise<TReturn>,
+    delay: number,
+  ): (...args: TArgs) => Promise<TReturn> {
+    let timeoutId: ReturnType<typeof setTimeout>;
+    let resolveFn: ((value: TReturn) => void) | null = null;
+    let rejectFn: ((reason: unknown) => void) | null = null;
 
-    return (...args: any[]) => {
+    return (...args: TArgs) => {
       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) => {
+      return new Promise<TReturn>((resolve, reject) => {
         resolveFn = resolve;
         rejectFn = reject;
       });
     };
   }
 
+  /**
+   * fetch autocomplete results from the Radar API
+   * @param query - the search query string
+   * @returns matching addresses
+   */
   public async fetchResults(query: string) {
     const { apis } = this.ctx;
     const { limit, layers, countryCode, expandUnits, mailable, lang, postalCode, onRequest } = this.config;
@@ -271,7 +273,11 @@ class AutocompleteUI {
     return addresses;
   }
 
-  public displayResults(results: any[]) {
+  /**
+   * render autocomplete results in the dropdown
+   * @param results - array of address results to display
+   */
+  public displayResults(results: RadarAutocompleteAddress[]) {
     // Clear the previous results
     this.clearResultsList();
     this.results = results;
@@ -292,7 +298,7 @@ class AutocompleteUI {
 
       // 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>');
@@ -346,6 +352,7 @@ class AutocompleteUI {
     }
   }
 
+  /** open the results dropdown */
   public open() {
     if (this.isOpen) {
       return;
@@ -356,6 +363,7 @@ class AutocompleteUI {
     this.isOpen = true;
   }
 
+  /** close the results dropdown and clear highlighted state */
   public close(e?: FocusEvent) {
     if (!this.isOpen) {
       return;
@@ -374,6 +382,10 @@ class AutocompleteUI {
     }, linkClick ? 100 : 0);
   }
 
+  /**
+   * highlight a result by index with wrap-around navigation
+   * @param index - the result index to highlight
+   */
   public goTo(index: number) {
     if (!this.isOpen || !this.results.length) {
       return;
@@ -441,6 +453,10 @@ class AutocompleteUI {
     }
   }
 
+  /**
+   * select a result by index and populate the input field
+   * @param index - the result index to select
+   */
   public select(index: number) {
     const { Logger } = this.ctx;
     const result = this.results[index];
@@ -450,7 +466,7 @@ class AutocompleteUI {
     }
 
     let inputValue;
-    if (result.formattedAddress.includes(result.addressLabel)) {
+    if (result.formattedAddress?.includes(result.addressLabel!)) {
       inputValue = result.formattedAddress;
     } else {
       const label = result.placeLabel || result.addressLabel;
@@ -467,12 +483,13 @@ class AutocompleteUI {
     this.close();
   }
 
+  /** clear the results list DOM and reset results array */
   public clearResultsList() {
     this.resultsList.innerHTML = '';
     this.results = [];
   }
 
-  // remove elements from DOM
+  /** remove the autocomplete widget from the DOM */
   public remove() {
     const { Logger } = this.ctx;
     Logger.debug('AutocompleteUI removed.');
@@ -481,6 +498,11 @@ class AutocompleteUI {
     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
+   */
   public setNear(near: string | Location | undefined | null) {
     if (near === undefined || near === null) {
       this.near = undefined;
@@ -492,24 +514,44 @@ class AutocompleteUI {
     return this;
   }
 
+  /**
+   * set the input placeholder text
+   * @param placeholder - new placeholder string
+   * @returns this instance for chaining
+   */
   public setPlaceholder(placeholder: string) {
     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
+   */
   public setDisabled(disabled: boolean) {
     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
+   */
   public setResponsive(responsive: boolean) {
     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
+   */
   public setWidth(width: number | string | null) {
     if (width === null) {
       this.config.width = undefined;
@@ -520,6 +562,11 @@ class AutocompleteUI {
     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
+   */
   public setMaxHeight(height: number | string | null) {
     if (height === null) {
       this.config.maxHeight = undefined;
@@ -530,17 +577,32 @@ class AutocompleteUI {
     return this;
   }
 
+  /**
+   * set the minimum character count to trigger autocomplete
+   * @param minCharacters - character threshold
+   * @returns this instance for chaining
+   */
   public setMinCharacters(minCharacters: number) {
     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
+   */
   public setLimit(limit: number) {
     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
+   */
   public setLang(lang: string | null) {
     if (lang === null) {
       this.config.lang = undefined;
@@ -550,6 +612,11 @@ class AutocompleteUI {
     return this;
   }
 
+  /**
+   * set a postal code bias for autocomplete requests
+   * @param postalCode - postal code string or null to clear
+   * @returns this instance for chaining
+   */
   public setPostalCode(postalCode: string | null) {
     if (postalCode === null) {
       this.config.postalCode = undefined;
@@ -559,6 +626,11 @@ class AutocompleteUI {
     return this;
   }
 
+  /**
+   * toggle marker icons in result items
+   * @param showMarkers - whether to show markers
+   * @returns this instance for chaining
+   */
   public setShowMarkers(showMarkers: boolean) {
     this.config.showMarkers = showMarkers;
     if (showMarkers) {
@@ -584,6 +656,11 @@ class AutocompleteUI {
     return this;
   }
 
+  /**
+   * set the color of marker icons in result items
+   * @param color - CSS color string
+   * @returns this instance for chaining
+   */
   public setMarkerColor(color: string) {
     this.config.markerColor = color;
     const marker = this.resultsList.getElementsByClassName(CLASSNAMES.RESULTS_MARKER);
@@ -593,6 +670,11 @@ class AutocompleteUI {
     return this;
   }
 
+  /**
+   * toggle hiding results when input loses focus
+   * @param hideResultsOnBlur - whether to hide on blur
+   * @returns this instance for chaining
+   */
   public setHideResultsOnBlur(hideResultsOnBlur: boolean) {
     this.config.hideResultsOnBlur = hideResultsOnBlur;
     if (hideResultsOnBlur) {

package/src/errors.ts

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

package/src/index.ts

@@ -17,6 +17,17 @@ declare module 'radar-sdk-js' {
   }
 }
 
+/**
+ * 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 function createAutocompletePlugin(): RadarPlugin {
   return {
     name: 'autocomplete',

package/src/types.ts

@@ -1,30 +1,57 @@
-import type { RadarAutocompleteParams } from 'radar-sdk-js';
+import type { RadarAutocompleteAddress, RadarAutocompleteParams } from 'radar-sdk-js';
 
+/** configuration options for the autocomplete UI widget */
 export interface RadarAutocompleteUIOptions extends Omit<RadarAutocompleteParams, 'query'> {
+  /** element ID or HTMLElement to mount the widget into */
   container: string | HTMLElement;
-  debounceMS?: number, // Debounce time in milliseconds
-  /** @deprecated use minCharacters instead */
+  /** debounce delay in milliseconds before fetching results */
+  debounceMS?: number,
+  /**
+   * @deprecated use minCharacters instead
+   */
   threshold?: number,
-  minCharacters?: number, // Minimum number of characters to trigger autocomplete
-  placeholder?: string, // Placeholder text for the input field
-  onSelection?: (selection: any) => void,
+  /** minimum number of characters to trigger autocomplete */
+  minCharacters?: number,
+  /** placeholder text for the input field */
+  placeholder?: string,
+  /** callback invoked when a result is selected */
+  onSelection?: (selection: RadarAutocompleteAddress) => void,
+  /** callback invoked before each autocomplete request */
   onRequest?: (params: RadarAutocompleteParams) => void,
-  onResults?: (results: any[]) => void,
-  onError?: (error: any) => void,
+  /** callback invoked when results are returned */
+  onResults?: (results: RadarAutocompleteAddress[]) => void,
+  /** callback invoked on autocomplete errors */
+  onError?: (error: Error) => void,
+  /** whether the input is disabled */
   disabled?: boolean,
+  /** whether to use responsive width (100% with optional max-width) */
   responsive?: boolean;
+  /** fixed width or max-width (px number or CSS string) */
   width?: string | number;
+  /** max height of the results dropdown (px number or CSS string) */
   maxHeight?: string | number;
+  /** whether to show marker icons in results */
   showMarkers?: boolean;
+  /** color for marker icons in results */
   markerColor?: string;
+  /** whether to hide results when the input loses focus */
   hideResultsOnBlur?: boolean;
 }
 
+/** resolved configuration with required defaults */
 export interface RadarAutocompleteConfig extends RadarAutocompleteUIOptions {
-  debounceMS: number, // Debounce time in milliseconds
-  threshold: number, // DEPRECATED(use minCharacters instead)
-  minCharacters: number, // Minimum number of characters to trigger autocomplete
-  limit: number, // Maximum number of autocomplete results
-  placeholder: string, // Placeholder text for the input field
+  /** debounce delay in milliseconds */
+  debounceMS: number,
+  /**
+   * @deprecated use minCharacters instead
+   */
+  threshold: number,
+  /** minimum characters to trigger autocomplete */
+  minCharacters: number,
+  /** maximum number of autocomplete results */
+  limit: number,
+  /** placeholder text for the input field */
+  placeholder: string,
+  /** whether the input is disabled */
   disabled: boolean,
 }

package/src/version.ts

@@ -1 +1 @@
-export default '5.0.0-beta.5';
+export default '5.0.0-beta.6';