places-autocomplete-svelte 2.2.12 → 2.2.13

package/README.md

@@ -20,6 +20,7 @@ Need this functionality for a non-Svelte project? Check out our companion vanill
 *   Automatically handles **session tokens** for cost management per Google's guidelines.
 *   **Debounced Input:** Limits API calls while the user is typing (configurable).
 *   **Suggestion Highlighting:** Automatically highlights the portion of text matching the user's input in the suggestions list.
+*   **Imperative API:** Exposes `clear()`, `focus()`, and `getRequestParams()` methods for direct control over the component.
 *   **Customizable Styling:** Easily override default styles or apply your own using the `options.classes` prop. Built with [Tailwind CSS](https://tailwindcss.com/) utility classes by default.
 *   **TypeScript Support:** Fully written in TypeScript with included type definitions.
 *   **Event Handling:** Provides `onResponse` and `onError` callbacks.
@@ -73,6 +74,7 @@ yarn add places-autocomplete-svelte
 import { PlaceAutocomplete } from 'places-autocomplete-svelte';
 import type { PlaceResult, ComponentOptions, RequestParams } from 'places-autocomplete-svelte/interfaces'; // Adjust path if needed
 
+
 // Get API Key securely (e.g., from environment variables)
 const PUBLIC_GOOGLE_MAPS_API_KEY = import.meta.env.VITE_PUBLIC_GOOGLE_MAPS_API_KEY;
 let fullResponse: PlaceResult | null = $state(null);
@@ -164,7 +166,33 @@ const options: Partial<ComponentOptions> = $state({
 | onResponse                 | (response: PlaceResult) => void | Yes      | -                                         | Callback function triggered with the selected place details (PlaceResult object) after fetchFields is complete. |
 | onError                    | (error: string) => void         | Yes      | -                                         | Callback function triggered when an error occurs (API loading, fetching suggestions, fetching details).         |
 
+Component Methods (Imperative API)
+----------------------------------
+
+For advanced use cases, you can get a reference to the component instance using `bind:this` and call its methods directly. This is useful for controlling the component from a parent, such as clearing the input from an external button.
+
+**Example Setup:**
+
+```svelte
+<script lang="ts">
+    import PlaceAutocomplete from 'places-autocomplete-svelte';
+    let autocompleteComponent = $state(null); // This will hold the component instance
+</script>
+
+<PlaceAutocomplete bind:this={autocompleteComponent} ... />
+
+<button onclick={() => autocompleteComponent.clear()}>Clear</button>
+<button onclick={() => autocompleteComponent.focus()}>Focus Input</button>
+<button onclick={() => console.log(JSON.stringify(autocompleteComponent.getRequestParams()))}>Get Request Params</button>
+```
+
+**vailable Methods:**
 
+| Method | Signature | Description |
+| :-- | :-- | :-- |
+| `clear()` | `() => void` | Clears the input field, removes all suggestions, and resets the Google Places session token. |
+| `focus()` | `() => void` | Programmatically sets focus on the text input field. |
+| `getRequestParams()` | `() => RequestParams` | Returns the component's current internal `requestParams` object. Useful for debugging or state inspection. |
 
 ### Options
 

package/dist/PlaceAutocomplete.svelte

@@ -7,7 +7,6 @@
 		validateRequestParams,
 		formatDistance,
 		validateFetchFields,
-		componentOptions
 	} from './helpers.js';
 	const { Loader } = GMaps;
 
@@ -24,6 +23,8 @@
 		requestParams = {}
 	}: Props = $props();
 
+	const isDefaultOnResponse = onResponse.toString() === ((response: PlaceResult) => {}).toString();
+
 	// validate options
 	options = validateOptions(options);
 	//console.log(options);
@@ -32,13 +33,7 @@
 	fetchFields = validateFetchFields(fetchFields);
 	//console.log(fetchFields);
 
-	// set classes as state
-	let cl = $state(options.classes ?? {});
-	// reset keyboard classes
-	const resetKbdClasses = () => {
-		cl.kbd_down = options.classes?.kbd_down ?? componentOptions.classes?.kbd_down ?? '';
-		cl.kbd_up = options.classes?.kbd_up ?? componentOptions.classes?.kbd_up ?? '';
-	};
+	let kbdAction = $state(''); // 'up', 'down', or 'escape'
 
 	// Local variables
 	let inputRef: HTMLInputElement;
@@ -64,12 +59,12 @@
 	 */
 	const reset = (placeData?: PlaceResult) => {
 		currentSuggestion = -1;
-		if(options?.clear_input == false){
+		if (options?.clear_input == false) {
 			if (placeData && placeData.formattedAddress) {
 				// set input to formatted address
 				request.input = placeData.formattedAddress;
 			}
-		}else{
+		} else {
 			request.input = '';
 		}
 		results = [];
@@ -77,6 +72,36 @@
 		//console.log('reset completed', results);
 	};
 
+	/**
+	 * Clears the autocomplete input field and suggestions list.
+	 * Refreshes the Google Places session token for a new session.
+	 * Can be called imperatively on the component instance.
+	 * @example
+	 * let autocompleteComponent;
+	 * autocompleteComponent.clear();
+	 */
+	export function clear() {
+		reset(); // The existing reset function already handles this
+	}
+
+	/**
+	 * Programmatically focuses the input element.
+	 * @example
+	 * autocompleteComponent.focus();
+	 */
+	export function focus() {
+		inputRef?.focus();
+	}
+
+	/**
+	 * Returns the current internal request parameters.
+	 * Useful for debugging or inspecting the component's state.
+	 * @returns {RequestParams}
+	 */
+	export function getRequestParams() {
+		return request;
+	}
+
 	/**
 	 * Debounce function to limit the rate at which a function can fire.
 	 * @param func
@@ -204,8 +229,6 @@
 				(e.name || 'An error occurred') + ' - ' + (e.message || 'error fetching place details')
 			);
 		}
-
-		
 	};
 
 	/**
@@ -223,6 +246,11 @@
 	 * Initialize the Google Maps JavaScript API Loader.
 	 */
 	onMount(async (): Promise<void> => {
+		if (isDefaultOnResponse) {
+			console.warn(
+				'PlaceAutocomplete: The `onResponse` callback has not been provided. Selected place data will not be handled. See documentation for usage.'
+			);
+		}
 		if (options.autofocus) {
 			// focus on the input
 			inputRef.focus();
@@ -236,7 +264,7 @@
 				libraries: ['places']
 			});
 
-			const { AutocompleteSessionToken, AutocompleteSuggestion} =
+			const { AutocompleteSessionToken, AutocompleteSuggestion } =
 				await loader.importLibrary('places');
 
 			placesApi.AutocompleteSessionToken = AutocompleteSessionToken;
@@ -258,28 +286,27 @@
 	function onKeyDown(e: KeyboardEvent) {
 		if (e.key === 'ArrowDown') {
 			currentSuggestion = Math.min(currentSuggestion + 1, results.length - 1);
-			resetKbdClasses();
-			cl.kbd_down += ' ' + (cl?.kbd_active ?? 'bg-indigo-500 text-white');
+			kbdAction = 'down';
 		} else if (e.key === 'ArrowUp') {
 			currentSuggestion = Math.max(currentSuggestion - 1, 0);
-			resetKbdClasses();
-			cl.kbd_up += ' ' + (cl?.kbd_active ?? 'bg-indigo-500 text-white');
+			kbdAction = 'up';
 		} else if (e.key === 'Enter') {
 			e.preventDefault();
 			if (currentSuggestion >= 0) {
 				onPlaceSelected(results[currentSuggestion].place);
 			}
 		} else if (e.key === 'Escape') {
-			// reset srarch input and results
+			kbdAction = 'escape';
 			request.input = '';
 			reset();
 		}
 		// Optional: Scroll suggestion into view
 		const selectedElement = document.getElementById(`option-${currentSuggestion + 1}`);
 		selectedElement?.scrollIntoView({ block: 'nearest' });
+		// Reset the action state after a short delay to allow CSS transition to finish
 		setTimeout(() => {
-			resetKbdClasses();
-		}, 300);
+			kbdAction = '';
+		}, 200);
 	}
 
 	// Handle click outside the input
@@ -291,7 +318,7 @@
 	}
 </script>
 
-<svelte:window onkeydown={onKeyDown} onclick={handleClickOutside}/>
+<svelte:window onkeydown={onKeyDown} onclick={handleClickOutside} />
 
 <section class={options.classes?.section}>
 	{#if options?.label ?? ''}
@@ -326,11 +353,15 @@
 
 		{#if results.length > 0}
 			<div class={options.classes?.kbd_container ?? ''}>
-				<kbd class={options.classes?.kbd_escape ?? ''}>Esc</kbd>
-				<kbd class={cl.kbd_up}>&uArr;</kbd>
-				<kbd class={cl.kbd_down}>&dArr;</kbd>
+				<kbd class={options.classes?.kbd_escape ?? ''} class:kbd-active={kbdAction === 'escape'}
+					>Esc</kbd
+				>
+				<kbd class={options.classes?.kbd_up ?? ''} class:kbd-active={kbdAction === 'up'}>&uArr;</kbd
+				>
+				<kbd class={options.classes?.kbd_down ?? ''} class:kbd-active={kbdAction === 'down'}
+					>&dArr;</kbd
+				>
 			</div>
-
 			<ul class={options.classes?.ul ?? ''} id="options" role="listbox">
 				{#each results as p, i}
 					<li
@@ -389,3 +420,15 @@
 		{/if}
 	</div>
 </section>
+
+<style>
+	/* Combining Tailwind CSS classes bg-indigo-500 text-white */
+	.kbd-active {
+		/* Use the active class from options if available, or a default */
+		background-color: var(--kbd-active-bg, #4f46e5); /* Indigo 500 */
+		color: var(--kbd-active-color, white);
+		transition:
+			background-color 0.1s ease-in-out,
+			color 0.1s ease-in-out;
+	}
+</style>

package/dist/PlaceAutocomplete.svelte.d.ts

@@ -1,4 +1,8 @@
 import type { Props } from './interfaces.js';
-declare const PlaceAutocomplete: import("svelte").Component<Props, {}, "onResponse" | "onError">;
+declare const PlaceAutocomplete: import("svelte").Component<Props, {
+    clear: () => void;
+    focus: () => void;
+    getRequestParams: () => import("./interfaces.js").RequestParams;
+}, "onResponse" | "onError">;
 type PlaceAutocomplete = ReturnType<typeof PlaceAutocomplete>;
 export default PlaceAutocomplete;

package/dist/helpers.js

@@ -331,56 +331,20 @@ export const componentOptions = {
  * @param options
  */
 export const validateOptions = (options) => {
-    const validatedOptions = { ...componentOptions };
-    if (options && typeof options === 'object') {
-        for (const key in validatedOptions) {
-            if (key in options) {
-                switch (key) {
-                    case 'autofocus':
-                        validatedOptions.autofocus = Boolean(options.autofocus);
-                        break;
-                    case 'autocomplete':
-                        validatedOptions.autocomplete = String(options.autocomplete);
-                        break;
-                    case 'placeholder':
-                        validatedOptions.placeholder = String(options.placeholder);
-                        break;
-                    case 'distance':
-                        validatedOptions.distance = Boolean(options.distance);
-                        break;
-                    case 'label':
-                        validatedOptions.label = String(options.label);
-                        break;
-                    case 'distance_units':
-                        validatedOptions.distance_units = String(options.distance_units);
-                        break;
-                    case 'classes':
-                        if (options.classes && typeof options.classes === 'object') {
-                            validatedOptions.classes = {
-                                ...componentOptions.classes,
-                                ...options.classes ?? {}
-                            };
-                        }
-                        break;
-                    case 'debounce':
-                        {
-                            const debounceValue = Number(options.debounce);
-                            if (!isNaN(debounceValue) && debounceValue >= 0) { // Allow 0 for debounce
-                                validatedOptions.debounce = debounceValue;
-                            }
-                            break;
-                        }
-                    case 'clear_input':
-                        validatedOptions.clear_input = Boolean(options.clear_input);
-                        break;
-                    default:
-                        // Ignore any other keys that are not in the default options
-                        break;
-                }
-            }
-        }
+    if (!options) {
+        return componentOptions;
     }
-    return validatedOptions;
+    // Perform a deep merge for the 'classes' object, inspired by the JS library
+    const mergedClasses = {
+        ...componentOptions.classes,
+        ...(options.classes ?? {})
+    };
+    const validated = {
+        ...componentOptions, // Start with all defaults
+        ...options, // Override with user-provided options
+        classes: mergedClasses // Apply the specifically merged classes
+    };
+    return validated;
 };
 /**
  * Display distance in km or miles

package/package.json

@@ -1,8 +1,8 @@
 {
 	"name": "places-autocomplete-svelte",
 	"license": "MIT",
-	"version": "2.2.12",
-	"description": "A flexible and customizable Svelte component leveraging the Google Maps Places (New) Autocomplete API to provide a user-friendly way to search for and retrieve detailed address information within your SvelteKit applications.",
+	"version": "2.2.13",
+	"description": "A flexible and customisable Svelte component leveraging the Google Maps Places (New) Autocomplete API to provide a user-friendly way to search for and retrieve detailed address information within your SvelteKit applications.",
 	"keywords": [
 		"svelte",
 		"sveltekit",
@@ -72,29 +72,29 @@
 	},
 	"devDependencies": {
 		"@sveltejs/adapter-auto": "^6.0.1",
-		"@sveltejs/adapter-cloudflare": "^7.0.3",
-		"@sveltejs/kit": "^2.21.2",
-		"@sveltejs/package": "^2.3.11",
+		"@sveltejs/adapter-cloudflare": "^7.0.4",
+		"@sveltejs/kit": "^2.22.2",
+		"@sveltejs/package": "^2.3.12",
 		"@sveltejs/vite-plugin-svelte": "^5.1.0",
-		"@tailwindcss/postcss": "^4.1.8",
+		"@tailwindcss/postcss": "^4.1.11",
 		"@tailwindcss/typography": "^0.5.16",
-		"@tailwindcss/vite": "^4.1.8",
+		"@tailwindcss/vite": "^4.1.11",
 		"@types/eslint": "^9.6.1",
 		"autoprefixer": "^10.4.21",
-		"eslint": "^9.28.0",
+		"eslint": "^9.30.1",
 		"eslint-config-prettier": "^10.1.5",
-		"eslint-plugin-svelte": "^3.9.1",
-		"globals": "^16.2.0",
-		"postcss": "^8.5.4",
-		"prettier": "^3.5.3",
+		"eslint-plugin-svelte": "^3.10.1",
+		"globals": "^16.3.0",
+		"postcss": "^8.5.6",
+		"prettier": "^3.6.2",
 		"prettier-plugin-svelte": "^3.4.0",
 		"publint": "^0.3.12",
-		"svelte": "^5.33.16",
-		"svelte-check": "^4.2.1",
-		"tailwindcss": "^4.1.8",
+		"svelte": "^5.35.2",
+		"svelte-check": "^4.2.2",
+		"tailwindcss": "^4.1.11",
 		"tslib": "^2.8.1",
 		"typescript": "^5.8.3",
-		"typescript-eslint": "^8.33.1",
+		"typescript-eslint": "^8.35.1",
 		"vite": "^6.3.5"
 	},
 	"svelte": "./dist/index.js",