places-autocomplete-svelte 2.2.11 → 2.2.13

package/README.md

@@ -3,7 +3,7 @@
 [![npm version](https://badge.fury.io/js/places-autocomplete-svelte.svg)](https://badge.fury.io/js/places-autocomplete-svelte)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A flexible and customizable [Svelte](https://kit.svelte.dev) component leveraging the [Google Maps Places (New) Autocomplete API](https://developers.google.com/maps/documentation/javascript/place-autocomplete-overview) to provide a user-friendly way to search for and retrieve detailed address information within your [SvelteKit](https://kit.svelte.dev) applications.
+A flexible and customizable [Svelte](https://kit.svelte.dev) component leveraging the [Google Maps Places Autocomplete API (New)](https://developers.google.com/maps/documentation/javascript/place-autocomplete-overview) to provide a user-friendly way to search for and retrieve detailed address information within your [SvelteKit](https://kit.svelte.dev) applications.
 
 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.
 
@@ -16,10 +16,11 @@ Need this functionality for a non-Svelte project? Check out our companion vanill
 
 ## Features
 
-*   Integrates with the modern **Google Places (New) Autocomplete API**.
+*   Integrates with the modern **"Google Maps Places Autocomplete API (New)**.
 *   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.
@@ -36,6 +37,9 @@ See a live demo of the component in action: [Basic Example](https://places-autoc
 
 [Customise request parameters](https://places-autocomplete-demo.pages.dev/examples/customise-request-parameters) - construct a `requestParams` object and control various aspects of the search, including language, region, and more.
 
+[Retain Input Value After Selection](https://places-autocomplete-demo.pages.dev/examples/retain-input-value) -
+This example demonstrates how to configure the Places (New) Autocomplete Svelte component to keep the selected address visible in the input field after a suggestion is chosen. It utilises the `options.clear_input = false` setting.
+
 
 <img src="places-autocomplete-svelte.gif" alt="A video demonstrating the Places Autocomplete Svelte component in action, showing address suggestions and selection.">
 
@@ -48,7 +52,7 @@ See a live demo of the component in action: [Basic Example](https://places-autoc
 
 ## Requirements
 
-- **Google Maps API Key** with the Places API (New) enabled. Refer to [Use API Keys](https://developers.google.com/maps/documentation/javascript/get-api-key) for detailed instructions.
+- **Google Maps API Key** with the Google Maps Places API (New) enabled. Refer to [Use API Keys](https://developers.google.com/maps/documentation/javascript/get-api-key) for detailed instructions.
 
 ## Installation
 
@@ -65,11 +69,12 @@ yarn add places-autocomplete-svelte
 1. Replace `'___YOUR_API_KEY___'` with your actual **Google Maps API Key**.
 2. Use the `onResponse` callback to **handle the response**.
 
-```js
+```svelte
 <script>
 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);
@@ -112,7 +117,7 @@ const options: Partial<ComponentOptions> = $state({
 		input: 'my-custom-input-class border-blue-500',
 		highlight: 'bg-yellow-200 text-black', // Customize suggestion highlighting
 	},
-    clear_input: false, // Keep the input value after selecting a suggestion. The value of the input will be the value of `formattedAddress`
+    clear_input: false, // Overriding the default value to keep the input value after selecting a suggestion. The value of the input will be the value of `formattedAddress`
 });
 
 </script>
@@ -151,7 +156,7 @@ const options: Partial<ComponentOptions> = $state({
     }
 </style>
 ```
-## Component Properties
+## Props
 | Prop                       | Type                            | Required | Default                                   | Description                                                                                                     |
 |----------------------------|---------------------------------|----------|-------------------------------------------|-----------------------------------------------------------------------------------------------------------------|
 | PUBLIC_GOOGLE_MAPS_API_KEY | string                          | Yes      | -                                         | Your Google Maps API Key with Places API enabled.                                                               |
@@ -161,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
 
@@ -175,7 +206,7 @@ const options: Partial<ComponentOptions> = $state({
 | label          | string                    | ''      | Optional label text displayed above the input field.                                                                            |
 | autofocus      | boolean                   | false   | Automatically focus the input field on mount.                                                                                   |
 | autocomplete   | string                    | 'off'   | Standard HTML autocomplete attribute for the input field.                                                                       |
-| classes        | Partial<ComponentClasses> | {}      | Object to override default CSS classes. See Styling section.                                                                    |                             |
+| classes        | Partial<ComponentClasses> | {}      | Object to override default CSS classes for various component parts. See Styling (options.classes) section for keys.                                                                |                             |
 | clear_input        | Boolean | true      | If `true` (default), clears the input field after a suggestion is selected. If `false`, the input field retains the `formattedAddress` of the selected place.                                      |
 
 
@@ -188,6 +219,7 @@ You can customize the appearance of the component by providing your own CSS clas
 
 
 **Available Class Keys:**
+The following keys can be used within the `options.classes object to target specific parts of the component:
 
 -   `section`: The main container section.
 -   `container`: The div containing the input and suggestions list.

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,27 +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
@@ -290,7 +318,7 @@
 	}
 </script>
 
-<svelte:window onkeydown={onKeyDown} onclick={handleClickOutside}/>
+<svelte:window onkeydown={onKeyDown} onclick={handleClickOutside} />
 
 <section class={options.classes?.section}>
 	{#if options?.label ?? ''}
@@ -325,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
@@ -388,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.11",
-	"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",
@@ -15,8 +15,7 @@
 		"address",
 		"address-input",
 		"input",
-		"search",
-		"new api"
+		"search"
 	],
 	"homepage": "https://places-autocomplete-demo.pages.dev",
 	"repository": {
@@ -69,33 +68,33 @@
 		"provenance": true
 	},
 	"peerDependencies": {
-		"svelte": "^5.1.4"
+		"svelte": "^5.0.0"
 	},
 	"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.14",
-		"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",