places-autocomplete-svelte 2.2.21 → 2.2.23

package/README.md

@@ -1,10 +1,11 @@
 # Places (New) Autocomplete Svelte
 
 [![npm version](https://badge.fury.io/js/places-autocomplete-svelte.svg)](https://badge.fury.io/js/places-autocomplete-svelte)
+[![npm downloads](https://img.shields.io/npm/dm/places-autocomplete-svelte.svg)](https://www.npmjs.com/package/places-autocomplete-svelte)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Google Maps Platform Awards 2025](https://img.shields.io/badge/Google%20Maps%20Platform-Awards%202025%20Winner-4285F4?style=flat&logo=google-maps&logoColor=white)](https://developers.google.com/maps)
+[![Google Maps Platform Awards 2025](https://img.shields.io/badge/Google%20Maps%20Platform-Awards%202025%20Winner-4285F4?style=flat&logo=google-maps&logoColor=white)](https://mapsplatform.google.com/awards/)
 
-A flexible, accessible, and secure [Svelte](https://kit.svelte.dev) component leveraging the [Google Maps Places Autocomplete API (New)](https://developers.google.com/maps/documentation/javascript/place-autocomplete-overview). **Winner of the Google Maps Platform Awards 2025**, recognising excellence in Google Maps Platform development.
+A flexible, accessible, and secure [Svelte 5](https://svelte.dev) component leveraging the [Google Maps Places Autocomplete API (New)](https://developers.google.com/maps/documentation/javascript/place-autocomplete-overview). **Winner of the Google Maps Platform Awards 2025**, recognising excellence in Google Maps Platform development.
 
 The component handles API loading, session tokens, debounced fetching, and accessibility, allowing you to focus on building your application. It intelligently manages the Google Maps API loader, creating a shared instance via Svelte's context that prevents conflicts with other map components on the same page.
 
@@ -22,17 +23,23 @@ The component handles API loading, session tokens, debounced fetching, and acces
 - [Usage](#usage)
   - [Basic Usage](#basic-usage-automatic-initialisation)
   - [Advanced Usage](#advanced-usage-manual-initialisation)
-- [Props](#props)
-- [Component Methods](#component-methods-imperative-api)
-- [Options](#options)
+- [API Reference](#api-reference)
+  - [Props](#props)
+  - [Component Methods](#component-methods-imperative-api)
+  - [Options](#options)
+  - [Events](#events)
 - [Styling](#styling)
-- [Events](#events)
 - [TypeScript](#typescript)
 - [Security](#security)
+  - [API Key Security](#api-key-security)
+  - [XSS Protection](#xss-protection)
 - [Accessibility](#accessibility)
 - [Google Places API & Billing](#google-places-api--billing)
+- [Browser Compatibility](#browser-compatibility)
+- [Troubleshooting](#troubleshooting)
 - [Standalone JavaScript Library](#standalone-javascript-library)
 - [Contributing](#contributing)
+- [Author](#author)
 - [License](#license)
 
 ## Features
@@ -60,31 +67,34 @@ The component handles API loading, session tokens, debounced fetching, and acces
 
 Explore live examples showcasing different features and use cases:
 
-**[🚀 Basic Example](https://places-autocomplete-demo.pages.dev/)** - Get started with the simplest implementation
+**[🚀 Basic Example](https://places-autocomplete-svelte.uk/examples/basic)** - Get started with the simplest implementation
 
-**[🔄 Reactive Parameters](https://places-autocomplete-demo.pages.dev/examples/reactive-parameters)** - Dynamically change search criteria based on user input, such as filtering by country or switching languages
+**[🔄 Reactive Parameters](https://places-autocomplete-svelte.uk/examples/reactive-parameters)** - Dynamically change search criteria based on user input, such as filtering by country or switching languages
 
-**[⚙️ Custom Request Parameters](https://places-autocomplete-demo.pages.dev/examples/customise-request-parameters)** - Configure advanced search options including language, region, location bias, and place types
+**[⚙️ Checkout Form](https://places-autocomplete-svelte.uk/examples/checkout-form)** - Capture the detailed address data from a user's selection and use it to automatically populate the fields of a checkout form.
 
-**[📝 Retain Input Value](https://places-autocomplete-demo.pages.dev/examples/retain-input-value)** - Keep the selected address visible in the input field after selection
+**[📝 Distance & Proximity Filter](https://places-autocomplete-svelte.uk/examples/proximity-filter)** - Restrict or bias search results to a specific area.
 
 <img src="places-autocomplete-svelte.gif" alt="A video demonstrating the Places Autocomplete Svelte component in action, showing address suggestions and selection.">
 
 ## Recognition
 
 ### 🏆 Google Maps Platform Awards 2025 Winner
+
 <p align="left">
-  <a href="https://developers.google.com/maps">
+  <a href="https://mapsplatform.google.com/awards/">
     <img src="badge.svg" alt="Google Maps Platform Awards 2025 Winner" width="200">
   </a>
 </p>
 
 This component has been recognised as a winner of the **Google Maps Platform Awards 2025** by the Google Developer Program. This award celebrates outstanding projects that demonstrate exceptional use of Google Maps Platform APIs, innovation, and contribution to the developer community.
 
-[Learn more about the Google Maps Platform Awards](https://developers.google.com/maps)
+[Learn more about the Google Maps Platform Awards →](https://mapsplatform.google.com/awards/)
 
 ## Requirements
 
+*   **Svelte 5+** - This component requires Svelte 5.0.0 or higher and uses Svelte 5 features including runes (`$state`, `$derived`, etc.)
+*   **Node.js 18+** - Required for development and building
 *   **Google Maps API Key** with the "Places API" enabled. Refer to [Use API Keys](https://developers.google.com/maps/documentation/javascript/get-api-key) for detailed instructions.
 
 ## Installation
@@ -93,6 +103,8 @@ This component has been recognised as a winner of the **Google Maps Platform Awa
 npm install places-autocomplete-svelte
 # or
 yarn add places-autocomplete-svelte
+# or
+pnpm add places-autocomplete-svelte
 ```
 
 ## Usage
@@ -212,6 +224,10 @@ For applications using multiple Google Maps libraries (e.g., `places`, `maps`, `
 - `initialiseGMapsNoContext(options)` - Initialises without context (for edge cases)
 - `importLibrary(library)` - Dynamically imports Google Maps libraries
 
+## API Reference
+
+The following sections detail the component's props, methods, options, and events.
+
 ## Security
 
 ### API Key Security
@@ -252,11 +268,12 @@ This component is built to be accessible and follows the [WAI-ARIA Authoring Pra
 
 Get a reference to the component instance using `bind:this` to call its methods directly.
 
-**Example:**
+**Example (Svelte 5 syntax):**
 
 ```javascript
 <script lang="ts">
     import PlaceAutocomplete from 'places-autocomplete-svelte';
+    // Note: Using Svelte 5 $state rune
     let autocompleteComponent: PlaceAutocomplete | undefined = $state(undefined);
 </script>
 
@@ -267,6 +284,9 @@ Get a reference to the component instance using `bind:this` to call its methods
 <button onclick={() => autocompleteComponent?.setRequestParams({ region: 'FR', language: 'fr' })}>
     Switch to French
 </button>
+<button onclick={() => autocompleteComponent?.setOptions({ placeholder: 'Search locations...', debounce: 300 })}>
+    Update Options
+</button>
 ```
 
 | Method | Signature | Description |
@@ -277,6 +297,8 @@ Get a reference to the component instance using `bind:this` to call its methods
 | `setRequestParams(params)` | `(params: Partial<RequestParams>) => void` | Dynamically updates request parameters. Useful for changing search criteria (region, language, location bias, etc.). Parameters are merged with existing ones. |
 | `setFetchFields(fields)` | `(fields: string[]) => void` | Dynamically updates the Place Data Fields to fetch when a place is selected. |
 | `getFetchFields()` | `() => string[]` | Returns the current array of Place Data Fields that will be requested. |
+| `setOptions(options)` | `(options: Partial<ComponentOptions>) => void` | Dynamically updates the component's configuration options. Merges the provided options with existing settings. |
+| `getOptions()` | `() => ComponentOptions` | Returns the current validated options used by the component. Useful for inspecting configuration settings. |
 
 ## Options
 
@@ -387,7 +409,7 @@ This component is fully written in TypeScript with comprehensive type definition
 
 **Component:**
 ```typescript
-import PlaceAutocomplete from 'places-autocomplete-svelte';
+import { PlaceAutocomplete } from 'places-autocomplete-svelte';
 ```
 
 **Types and Interfaces:**
@@ -416,7 +438,7 @@ import {
 } from 'places-autocomplete-svelte/gmaps';
 ```
 
-## Security
+## Google Places API & Billing
 
 *   This component uses the Google Maps JavaScript API (Places library). Usage is subject to Google's terms and pricing.
 *   **Session Tokens** are used automatically to group Autocomplete requests, which can reduce costs.

package/dist/PlaceAutocomplete.svelte

@@ -73,9 +73,9 @@
 	/**
 	 * Create validated derived values that react to prop changes
 	 */
-	const validatedOptions = $derived(validateOptions(options));
-	const validatedFetchFields = $derived(validateFetchFields(fetchFields));
-	const validatedRequestParams = $derived(validateRequestParams(requestParams));
+	let validatedOptions = $derived(validateOptions(options));
+	let validatedFetchFields = $derived(validateFetchFields(fetchFields));
+	let validatedRequestParams = $derived(validateRequestParams(requestParams));
 
 	/**
 	 * Local variables
@@ -164,7 +164,7 @@
 	 * @returns {RequestParams} The current request parameters object.
 	 */
 	export function getRequestParams() {
-		return request;
+		return validatedRequestParams;
 	}
 
 	/**
@@ -187,7 +187,7 @@
 	 * });
 	 */
 	export function setRequestParams(params: Partial<typeof requestParams>) {
-		requestParams = { ...requestParams, ...params };
+		validatedRequestParams = validateRequestParams({ ...requestParams, ...params });
 	}
 
 	/**
@@ -200,7 +200,7 @@
 	 * autocompleteComponent.setFetchFields(['displayName', 'types', 'location']);
 	 */
 	export function setFetchFields(fields: string[]) {
-		fetchFields = fields;
+		validatedFetchFields = validateFetchFields(fields);
 	}
 
 	/**
@@ -212,9 +212,40 @@
 	 * console.log('Current fields:', fields);
 	 */
 	export function getFetchFields(): string[] {
-		return fetchFields;
+		return validatedFetchFields;
 	}
 
+	/**
+	 * Dynamically updates the component's configuration options.
+	 * Merges the provided options with existing settings.
+	 * @public
+	 * @param options - Partial options object to update component behavior and appearance.
+	 * @example
+	 * // Update options to change placeholder and enable distance display
+	 * autocompleteComponent.setOptions({
+	 *   placeholder: 'Enter a location',
+	 *   showDistance: true
+	 * });
+	 */
+	export function setOptions(options: typeof validatedOptions){
+		validatedOptions = validateOptions(options);
+	}	
+
+
+	/**
+	 * Returns the current validated options used by the component.
+	 * Useful for inspecting configuration settings.
+	 * @public
+	 * @returns {typeof validatedOptions} The current validated options object.
+	 * @example
+	 * const options = autocompleteComponent.getOptions();
+	 * console.log('Current options:', options);
+	 */
+	export function getOptions(): typeof validatedOptions {
+		return validatedOptions;
+	}
+
+
 	/**
 	 * Extracts a specific address component from the place response.
 	 * @private
@@ -317,10 +348,10 @@
 
 	/**
 	 * Debounced version of makeAcRequest that delays API calls to reduce request frequency.
-	 * The debounce delay is reactive and updates when the options.debounce value changes.
+	 * The debounce delay is reactive and updates when the validatedOptions.debounce value changes.
 	 * @private
 	 */
-	const debouncedMakeAcRequest = $derived(debounce(makeAcRequest, options?.debounce ?? 100));
+	const debouncedMakeAcRequest = $derived(debounce(makeAcRequest, validatedOptions?.debounce ?? 100));
 
 	/**
 	 * Handles the selection of an autocomplete suggestion.
@@ -388,7 +419,7 @@
 			// If the parent has already finished, this resolves immediately.
 			// If the parent is still loading, this will wait.
 			if (typeof gmaps !== 'undefined' && gmaps) {
-				await gmaps?.initializationPromise;
+				await gmaps?.initialisationPromise;
 			} else {
 				// Check if the API key is provided
 				if (PUBLIC_GOOGLE_MAPS_API_KEY === '' || !PUBLIC_GOOGLE_MAPS_API_KEY) {

package/dist/PlaceAutocomplete.svelte.d.ts

@@ -2,10 +2,12 @@ import type { Props } from './interfaces.js';
 declare const PlaceAutocomplete: import("svelte").Component<Props, {
     clear: () => void;
     focus: () => void;
-    getRequestParams: () => any;
+    getRequestParams: () => import("./interfaces.js").RequestParams;
     setRequestParams: (params: Partial<import("./interfaces.js").RequestParams>) => void;
     setFetchFields: (fields: string[]) => void;
     getFetchFields: () => string[];
+    setOptions: (options: import("./interfaces.js").ComponentOptions) => void;
+    getOptions: () => import("./interfaces.js").ComponentOptions;
 }, "onResponse" | "onError">;
 type PlaceAutocomplete = ReturnType<typeof PlaceAutocomplete>;
 export default PlaceAutocomplete;

package/dist/interfaces.d.ts

@@ -64,7 +64,7 @@ export interface ComponentClasses {
  * Controls browser autofill behavior for the input field.
  * @type {"on" | "off"}
  */
-export type AutoFill = "on" | "off";
+export type AutoFill = "on" | "off" | string;
 /**
  * Distance measurement units for displaying place distances.
  * @type {"km" | "miles"}

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "places-autocomplete-svelte",
 	"license": "MIT",
-	"version": "2.2.21",
+	"version": "2.2.23",
 	"description": "A flexible, accessible, and secure Svelte component leveraging the Google Maps Places Autocomplete API (New). Winner of the Google Maps Platform Awards 2025, recognising excellence in Google Maps Platform development.",
 	"keywords": [
 		"svelte",
@@ -77,19 +77,19 @@
 	"devDependencies": {
 		"@sveltejs/adapter-auto": "^7.0.0",
 		"@sveltejs/adapter-cloudflare": "^7.2.4",
-		"@sveltejs/kit": "^2.49.2",
+		"@sveltejs/kit": "^2.49.4",
 		"@sveltejs/package": "^2.5.7",
-		"@sveltejs/vite-plugin-svelte": "^6.2.1",
+		"@sveltejs/vite-plugin-svelte": "^6.2.4",
 		"@tailwindcss/postcss": "^4.1.18",
 		"@tailwindcss/typography": "^0.5.19",
 		"@tailwindcss/vite": "^4.1.18",
 		"@types/eslint": "^9.6.1",
 		"@types/google.maps": "^3.58.1",
-		"@types/node": "^25.0.3",
+		"@types/node": "^25.0.6",
 		"autoprefixer": "^10.4.23",
 		"eslint": "^9.39.2",
 		"eslint-config-prettier": "^10.1.8",
-		"eslint-plugin-svelte": "^3.13.1",
+		"eslint-plugin-svelte": "^3.14.0",
 		"globals": "^17.0.0",
 		"postcss": "^8.5.6",
 		"prettier": "^3.7.4",
@@ -100,8 +100,8 @@
 		"tailwindcss": "^4.1.18",
 		"tslib": "^2.8.1",
 		"typescript": "^5.9.3",
-		"typescript-eslint": "^8.51.0",
-		"vite": "^7.3.0"
+		"typescript-eslint": "^8.52.0",
+		"vite": "^7.3.1"
 	},
 	"svelte": "./dist/index.js",
 	"types": "./dist/PlaceAutocomplete.svelte.d.ts",