places-autocomplete-svelte 2.2.12 → 2.2.14

package/README.md

@@ -8,7 +8,7 @@ A flexible and customizable [Svelte](https://kit.svelte.dev) component leveragin
 This component handles API loading, session tokens, fetching suggestions, and requesting place details, allowing you to focus on integrating the results into your application. Includes features like debounced input, highlighting of matched suggestions, extensive customization via CSS classes, and full TypeScript support.
 
 
-## Also Available: Standalone JavaScript Library
+## Available: Standalone JavaScript Library
 
 Need this functionality for a non-Svelte project? Check out our companion vanilla JavaScript library, `places-autocomplete-js`, which offers the same core Google Places (New) Autocomplete features.
 [View `places-autocomplete-js` on GitHub](https://github.com/alexpechkarev/places-autocomplete-js)
@@ -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>
+```
+
+**Available 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.14",
+	"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",