places-autocomplete-svelte 2.2.14 → 2.2.16

package/README.md

@@ -3,31 +3,28 @@
 [![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 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.
+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).
 
+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 that prevents conflicts with other map components on the same page. 
 
 ## 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)
 
-
 ## Features
 
-*   Integrates with the modern **"Google Maps Places Autocomplete API (New)**.
-*   Automatically handles **session tokens** for cost management per Google's guidelines.
+*   Integrates with the modern **Google Maps Places Autocomplete API (New)**.
+*   **Automatic Shared Loader:** Intelligently creates a single Google Maps loader instance and shares it via Svelte's context.
+*   **Highly Accessible:** Follows WAI-ARIA patterns for comboboxes, with full keyboard navigation and screen reader support.
+*   **Secure:** Safely renders suggestions to protect against XSS attacks.
+*   Automatically handles **session tokens** for cost management.
 *   **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.
+*   **Suggestion Highlighting:** Automatically highlights the portion of text matching the user's input.
+*   **Imperative API:** Exposes `clear()`, `focus()`, and `getRequestParams()` methods for direct control.
+*   **Customisable Styling:** Easily override default styles using the `options.classes` prop.
 *   **TypeScript Support:** Fully written in TypeScript with included type definitions.
 *   **Event Handling:** Provides `onResponse` and `onError` callbacks.
-*   **Configurable:** Control API parameters (`requestParams`), requested data fields (`fetchFields`), and component behavior/appearance (`options`).
-*   **Prop Validation:** Sensible defaults and validation for configuration props.
-
-
 
 ## Demo
 
@@ -38,21 +35,13 @@ 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.
-
+This example demonstrates how to configure the component to keep the selected address visible in the input field after a suggestion is chosen.
 
 <img src="places-autocomplete-svelte.gif" alt="A video demonstrating the Places Autocomplete Svelte component in action, showing address suggestions and selection.">
 
-
-
-
-
-
-
-
 ## Requirements
 
-- **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.
+*   **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
 
@@ -62,26 +51,22 @@ npm install places-autocomplete-svelte
 yarn add places-autocomplete-svelte
 ```
 
+## Usage
 
+Provide your Google Maps API key to the component. It will automatically handle loading the required `places` library.
 
-## Basic Usage
-
-1. Replace `'___YOUR_API_KEY___'` with your actual **Google Maps API Key**.
-2. Use the `onResponse` callback to **handle the response**.
-
-```svelte
-<script>
+```javascript
+<script lang="ts">
 import { PlaceAutocomplete } from 'places-autocomplete-svelte';
-import type { PlaceResult, ComponentOptions, RequestParams } from 'places-autocomplete-svelte/interfaces'; // Adjust path if needed
-
+import type { PlaceResult, ComponentOptions, RequestParams } from 'places-autocomplete-svelte/interfaces';
 
 // Get API Key securely (e.g., from environment variables)
 const PUBLIC_GOOGLE_MAPS_API_KEY = import.meta.env.VITE_PUBLIC_GOOGLE_MAPS_API_KEY;
+
+// --- Event Handlers ---
 let fullResponse: PlaceResult | null = $state(null);
 let placesError = $state('');
 
-
-// --- Event Handlers ---
 const handleResponse = (response: PlaceResult) => {
 	console.log('Place Selected:', response);
 	fullResponse = response;
@@ -95,31 +80,20 @@ const handleError = (error: string) => {
 };
 
 // --- Configuration (Optional) ---
-
-// Control API request parameters
 const requestParams: Partial<RequestParams> = $state({
-	region: 'GB', // Example: Bias results to Great Britain
+	region: 'GB',
 	language: 'en-GB',
-	// includedRegionCodes: ['GB'], // Example: Only show results in the specified regions,
-	// includedPrimaryTypes: ['address'], // Example: Only show addresses
 });
-
-// Control which data fields are fetched for Place Details (affects cost!)
 const fetchFields: string[] = $state(['formattedAddress', 'addressComponents', 'displayName']);
-
-// Control component appearance and behavior
 const options: Partial<ComponentOptions> = $state({
 	placeholder: 'Start typing your address...',
-	debounce: 200, // Debounce input by 200ms (default is 100ms)
-	distance: true, // Show distance if origin is provided in requestParams
+	debounce: 200,
 	classes: {
-		// Example: Override input styling and highlight class
 		input: 'my-custom-input-class border-blue-500',
-		highlight: 'bg-yellow-200 text-black', // Customize suggestion highlighting
+		highlight: 'bg-yellow-200 text-black',
 	},
-    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`
+    clear_input: false,
 });
-
 </script>
 
 {#if placesError}
@@ -143,12 +117,10 @@ const options: Partial<ComponentOptions> = $state({
 {/if}
 
 <style>
-    /* Example of styling an overridden class */
     :global(.my-custom-input-class) {
         padding: 0.75rem;
         border-radius: 0.25rem;
         width: 100%;
-        /* Add other styles */
     }
     .error-message {
         color: red;
@@ -156,131 +128,167 @@ const options: Partial<ComponentOptions> = $state({
     }
 </style>
 ```
-## Props
-| Prop                       | Type                            | Required | Default                                   | Description                                                                                                     |
-|----------------------------|---------------------------------|----------|-------------------------------------------|-----------------------------------------------------------------------------------------------------------------|
-| PUBLIC_GOOGLE_MAPS_API_KEY | string                          | Yes      | -                                         | Your Google Maps API Key with Places API enabled.                                                               |
-| fetchFields                | string[]                        | No       | ['formattedAddress', 'addressComponents'] | Array of Place Data Fields to request when a place is selected. Affects API cost.                               |
-| requestParams              | Partial<RequestParams>          | No       | { inputOffset: 3, ... }                   | Parameters for the Autocomplete request. See AutocompletionRequest options.                                     |
-| options                    | Partial<ComponentOptions>       | No       | { debounce: 100, ... }                    | Options to control component behavior and appearance. See details below.                                        |
-| 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)
-----------------------------------
+### Advanced: Using with other Google Maps Libraries
 
-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.
+You can reuse the shared Google Maps loader created by the `PlaceAutocomplete` component to load other libraries (like `maps`). Because the loader instance is shared, you can access it from any other component to load additional libraries without causing conflicts.
 
-**Example Setup:**
-
-```svelte
+The `PlaceAutocomplete` component only loads the `places` library by default. 
+```javascript
+// In a parent component, e.g., src/routes/+page.svelte
 <script lang="ts">
-    import PlaceAutocomplete from 'places-autocomplete-svelte';
-    let autocompleteComponent = $state(null); // This will hold the component instance
+	import { onMount } from 'svelte';
+	import { getGMapsLoader } from 'places-autocomplete-svelte/gmaps';
+	import PlaceAutocomplete from '$lib/PlaceAutocomplete.svelte';
+
+	const PUBLIC_GOOGLE_MAPS_API_KEY = import.meta.env.VITE_PUBLIC_GOOGLE_MAPS_API_KEY;
+
+	// Pre-initialise the loader with all libraries needed for this page.
+	onMount(async () => {
+		const loader = getGMapsLoader(PUBLIC_GOOGLE_MAPS_API_KEY);
+		const { Map } = await loader.importLibrary('maps');
+        ...
+	});
 </script>
 
-<PlaceAutocomplete bind:this={autocompleteComponent} ... />
+<!-- The component will now use the loader you created above -->
+<PlaceAutocomplete
+    {PUBLIC_GOOGLE_MAPS_API_KEY}
+    onResponse={...}
+    onError={...}
+/>
 
-<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>
+<!-- You can now use other Google Maps services, e.g., a map -->
+<div id="map"></div>
 ```
 
-**Available Methods:**
+## Security
 
-| 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. |
+### API Key Security
+
+Your Google Maps API Key is a sensitive credential. To prevent unauthorised use and unexpected charges, you **must** restrict it.
+
+1.  Go to the [Google Cloud Console](https://console.cloud.google.com/google/maps-apis/credentials).
+2.  Select your API key.
+3.  Under **Application restrictions**, select **HTTP referrers (web sites)** and add your application's domain(s) (e.g., `your-domain.com/*`).
+4.  Under **API restrictions**, select **Restrict key** and choose the APIs you are using (e.g., **Places API**, **Maps JavaScript API**).
+
+### XSS Protection
+
+This component is designed to be secure out-of-the-box. It safely renders user-input and API responses to prevent Cross-Site Scripting (XSS) vulnerabilities.
+
+## Accessibility
+
+This component is built to be accessible and follows the [WAI-ARIA Authoring Practices for a Combobox](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/).
+
+*   **Keyboard Navigation:** Users can navigate suggestions using `ArrowUp`, `ArrowDown`, select with `Enter`, and close the list with `Escape`.
+*   **Screen Reader Support:** Uses `role="combobox"`, `aria-autocomplete`, `aria-expanded`, and `aria-activedescendant` to provide a clear experience for screen reader users.
+*   **Focus Management:** Focus remains on the input field while navigating the suggestion list.
+
+## Props
 
-### Options
+| Prop | Type | Required | Default | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `PUBLIC_GOOGLE_MAPS_API_KEY` | `string` | Yes | - | Your restricted Google Maps API Key. |
+| `fetchFields` | `string[]` | No | `['formattedAddress', 'addressComponents']` | Place Data Fields to request. **Affects API cost.** |
+| `requestParams` | `Partial<RequestParams>` | No | `{ inputOffset: 3, ... }` | Parameters for the Autocomplete API request. |
+| `options` | `Partial<ComponentOptions>` | No | `{ debounce: 100, ... }` | Options to control component behavior and appearance. |
+| `onResponse` | `(response: PlaceResult) => void` | Yes | - | Callback triggered with the selected place details. |
+| `onError` | `(error: string) => void` | Yes | - | Callback triggered when an error occurs. |
 
+## Component Methods (Imperative API)
 
-| Option         | Type                      | Default | Description                                                                                                                     |
-|----------------|---------------------------|---------|---------------------------------------------------------------------------------------------------------------------------------|
-| placeholder    | string                    | ''      | Placeholder text for the input field.                                                                                           |
-| debounce       | number                    | 100     | Delay in milliseconds before triggering autocomplete API request after user stops typing. Set to 0 to disable debouncing. |
-| distance       | boolean                   | true    | Show distance from requestParams.origin in suggestions (if origin is provided).                                                 |
-| distance_units | 'km' \| 'miles'           | 'km'    | Units to display distance in.                                                                                                   |
-| 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 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.                                      |
+Get a reference to the component instance using `bind:this` to call its methods directly.
 
+**Example:**
 
+```javascript
+<script lang="ts">
+    import PlaceAutocomplete from 'places-autocomplete-svelte';
+    let autocompleteComponent: PlaceAutocomplete | undefined = $state(undefined);
+</script>
+
+<PlaceAutocomplete bind:this={autocompleteComponent} ... />
+
+<button onclick={() => autocompleteComponent?.clear()}>Clear</button>
+<button onclick={() => autocompleteComponent?.focus()}>Focus</button>
+```
+
+| Method | Signature | Description |
+| :--- | :--- | :--- |
+| `clear()` | `() => void` | Clears the input, removes suggestions, and resets the session token. |
+| `focus()` | `() => void` | Sets focus on the text input field. |
+| `getRequestParams()` | `() => RequestParams` | Returns the current internal `requestParams` object. |
 
+## Options
 
-### Styling (`options.classes`)
----------------------------
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `placeholder` | `string` | `''` | Placeholder text for the input field. |
+| `debounce` | `number` | `100` | Delay in ms before firing API request. Set to `0` to disable. |
+| `distance` | `boolean` | `true` | Show distance from `requestParams.origin` (if provided). |
+| `distance_units` | `'km' \| 'miles'` | `'km'` | Units for displaying distance. |
+| `label` | `string` | `''` | Optional label text displayed above the input. |
+| `autofocus` | `boolean` | `false` | Automatically focus the input on mount. |
+| `autocomplete` | `string` | `'off'` | The `autocomplete` attribute for the input field. |
+| `classes` | `Partial<ComponentClasses>` | `{}` | Object to override default CSS classes. See Styling section. |
+| `clear_input` | `boolean` | `true` | If `false`, retains the `formattedAddress` in the input after selection. |
 
-You can customize the appearance of the component by providing your own CSS classes via the `options.classes` prop. The component uses Tailwind CSS utility classes by default. Provide an object where keys are the component parts and values are the class strings you want to apply. See [styling](https://places-autocomplete-demo.pages.dev/examples/styling) for details.
+## Styling (`options.classes`)
 
+Customise the component by providing your own CSS classes via `options.classes`.
 
 **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.
--   `label`: The label element (if `options.label` is provided).
--   `input`: The main text input element.
--   `icon_container`: Container for the optional icon.
--   `icon`: SVG string for the icon.
--   `ul`: The `<ul>` element for the suggestions list.
--   `li`: Each `<li>` suggestion item.
--   `li_current`: Class added to the currently highlighted/selected `<li>` (keyboard/mouse).
--   `li_a`: The inner `<a>` or `<button>` element within each `<li>`.
--   `li_a_current`: Class added to the inner element when its `<li>` is current.
--   `li_div_container`: Container div within the `<a>`/`<button>`.
--   `li_div_one`: First inner div (usually contains the main text).
--   `li_div_one_p`: The `<p>` tag containing the main suggestion text (`@html` is used).
--   `li_div_two`: Second inner div (usually contains the distance).
--   `li_div_two_p`: The `<p>` tag containing the distance text.
--   `kbd_container`: Container for the keyboard hint keys (Esc, Up, Down).
--   `kbd_escape`: The `<kbd>` tag for the 'Esc' hint.
--   `kbd_up`: The `<kbd>` tag for the 'Up Arrow' hint.
--   `kbd_down`: The `<kbd>` tag for the 'Down Arrow' hint.
--   `highlight`: The class applied to the `<span>` wrapping the matched text within suggestions. Defaults to `'font-bold'`.
-
-### Example: 
+
+*   `section`: The main container `section`.
+*   `container`: The `div` containing the input and suggestions list.
+*   `label`: The `label` element.
+*   `input`: The main text `input` element.
+*   `icon_container`: Container for the optional icon.
+*   `icon`: SVG string for the icon.
+*   `ul`: The `<ul>` element for the suggestions list.
+*   `li`: Each `<li>` suggestion item.
+*   `li_current`: Class added to the currently highlighted `<li>`.
+*   `li_div_container`: Container `div` within each list item.
+*   `li_div_one`: First inner `div` (contains the main text).
+*   `li_div_one_p`: The `<p>` tag containing the main suggestion text.
+*   `li_div_two`: Second inner `div` (contains the distance).
+*   `li_div_two_p`: The `<p>` tag containing the distance text.
+*   `kbd_container`: Container for the keyboard hint keys.
+*   `kbd_escape`: The `<kbd>` tag for the 'Esc' hint.
+*   `kbd_up`: The `<kbd>` tag for the 'Up Arrow' hint.
+*   `kbd_down`: The `<kbd>` tag for the 'Down Arrow' hint.
+*   `highlight`: The class applied to the `<span>` wrapping the matched text. Defaults to `'font-bold'`.
+
+**Example:**
 
 ```javascript
 const options = {
   classes: {
-    input: 'form-input w-full rounded-md shadow-sm', // Replace default input style
-    ul: 'absolute bg-white shadow-lg rounded-md mt-1 w-full z-10', // Custom dropdown style
-    li_current: 'bg-blue-500 text-white', // Custom highlight style for selected item
-    highlight: 'text-blue-700 font-semibold' // Custom style for matched text
+    input: 'form-input w-full rounded-md shadow-sm',
+    ul: 'absolute bg-white shadow-lg rounded-md mt-1 w-full z-10',
+    li_current: 'bg-blue-500 text-white',
+    highlight: 'text-blue-700 font-semibold'
   }
 };
 ```
 
-Events
-------
-
--   **`onResponse`**: `(response: PlaceResult) => void`
-    -   Fired after a user selects a suggestion and the requested `fetchFields` have been successfully retrieved.
-    -   The `response` argument is an object containing the place details based on the `fetchFields` requested. Its structure mirrors the [PlaceResult](https://developers.google.com/maps/documentation/javascript/reference/places-service#PlaceResult) but includes only the requested fields.
--   **`onError`**: `(error: string) => void`
-    -   Fired if there's an error loading the Google Maps API, fetching autocomplete suggestions, or fetching place details.
-    -   The `error` argument is a string describing the error.
-
-
-TypeScript
-----------
+## Events
 
-This component is written in TypeScript and includes type definitions for props (`Props`, `ComponentOptions`, `RequestParams`, `ComponentClasses`) and the response (`PlaceResult`, `AddressComponent`). You can import these types from `places-autocomplete-svelte/interfaces` (adjust path if needed based on your setup).
+*   **`onResponse`**: `(response: PlaceResult) => void`
+    *   Fired after a user selects a suggestion and `fetchFields` are retrieved.
+*   **`onError`**: `(error: string) => void`
+    *   Fired on any error (API loading, fetching suggestions, etc.).
 
+## TypeScript
 
+This component is written in TypeScript. Import types from `places-autocomplete-svelte/interfaces` and helpers from `places-autocomplete-svelte/gmaps`.
 
-Google Places API & Billing
----------------------------
+## Google Places API & Billing
 
--   This component uses the Google Maps JavaScript API (specifically the Places library). Usage is subject to Google's terms and pricing.
--   An API key enabled for the "Places API" is required.
--   The component uses **Session Tokens** automatically to group Autocomplete requests, which can lead to significant cost savings compared to per-request billing. See [Google's Session Token Pricing](https://developers.google.com/maps/documentation/places/web-service/usage-and-billing#session-pricing).
--   Place Details requests (made via `fetchFields` when a suggestion is selected) are billed separately. Carefully select only the `fetchFields` you need to manage costs. See [Place Data Fields Pricing](https://developers.google.com/maps/documentation/javascript/usage-and-billing#data-pricing).
+*   This component uses the Google Maps JavaScript API (Places library). Usage is subject to Google's terms and pricing.
+*   It uses **Session Tokens** automatically to group Autocomplete requests, which can reduce costs.
+*   Place Details requests (via `fetchFields`) are billed separately. Only request the fields you need to manage costs.
 
 ## Contributing
 

package/dist/PlaceAutocomplete.svelte

@@ -1,14 +1,17 @@
 <script lang="ts">
 	import { onMount } from 'svelte';
-	import * as GMaps from '@googlemaps/js-api-loader';
 	import type { PlaceResult, Props } from './interfaces.js';
 	import {
 		validateOptions,
 		validateRequestParams,
 		formatDistance,
 		validateFetchFields,
+		createHighlightedSegments,
+		debounce
 	} from './helpers.js';
-	const { Loader } = GMaps;
+
+	import { getGMapsLoader, type GMapsLoaderType } from './gmaps.js';
+
 
 	let {
 		/**
@@ -33,14 +36,15 @@
 	fetchFields = validateFetchFields(fetchFields);
 	//console.log(fetchFields);
 
+
 	let kbdAction = $state(''); // 'up', 'down', or 'escape'
 
 	// Local variables
 	let inputRef: HTMLInputElement;
 	let currentSuggestion = $state(-1);
 	let results: any[] = $state([]);
-	let loader: GMaps.Loader;
 	let placesApi: { [key: string]: any } = {};
+	let loader: GMapsLoaderType;
 
 	//https://developers.google.com/maps/documentation/javascript/reference/autocomplete-data
 	// validate requestParams
@@ -102,28 +106,6 @@
 		return request;
 	}
 
-	/**
-	 * Debounce function to limit the rate at which a function can fire.
-	 * @param func
-	 * @param wait
-	 */
-	function debounce<T extends (...args: any[]) => any>(
-		func: T,
-		wait: number
-	): (...args: Parameters<T>) => void {
-		let timeout: ReturnType<typeof setTimeout> | null = null;
-		return function executedFunction(...args: Parameters<T>) {
-			const later = () => {
-				timeout = null;
-				func(...args);
-			};
-			if (timeout !== null) {
-				clearTimeout(timeout);
-			}
-			timeout = setTimeout(later, wait);
-		};
-	}
-
 	/**
 	 * Make request and get autocomplete suggestions.
 	 * @param event
@@ -164,30 +146,15 @@
 				const matches = predictionText.matches;
 
 				//Highlighting Logic
-				let highlightedText = '';
-				let lastIndex = 0;
+				let highlightedText: { text: string; highlighted: boolean }[] = [];
 
 				// Sort matches just in case they aren't ordered (though they usually are)
 				matches.sort(
 					(a: { startOffset: number }, b: { startOffset: number }) => a.startOffset - b.startOffset
 				);
-				for (const match of matches) {
-					// Append text before the current match
-					highlightedText += originalText.substring(lastIndex, match.startOffset);
-
-					// Append the highlighted match segment
-					// Choose your highlighting class (e.g., 'font-bold' or a custom one)
-					highlightedText += `<span class="${options.classes?.highlight ?? 'font-bold'}">`;
-					highlightedText += originalText.substring(match.startOffset, match.endOffset);
-					highlightedText += `</span>`;
-
-					// Update the last index processed
-					lastIndex = match.endOffset;
-				}
 
-				// Append any remaining text after the last match
-				highlightedText += originalText.substring(lastIndex);
-				// --- End Highlighting Logic ---
+				// Create highlighted segments
+				highlightedText = createHighlightedSegments(originalText, matches);
 
 				results.push({
 					place: suggestion.placePrediction.toPlace(),
@@ -256,25 +223,24 @@
 			inputRef.focus();
 		}
 
-		// load the Google Maps API
 		try {
-			loader = new Loader({
-				apiKey: PUBLIC_GOOGLE_MAPS_API_KEY,
-				version: 'weekly',
-				libraries: ['places']
-			});
+			loader = getGMapsLoader(PUBLIC_GOOGLE_MAPS_API_KEY);
+		} catch (e: any) {
+			onError(
+				(e.name || 'An error occurred') + ' - ' + (e.message || 'Error loading Google Maps API')
+			);
+		}
 
+		try {
 			const { AutocompleteSessionToken, AutocompleteSuggestion } =
 				await loader.importLibrary('places');
 
 			placesApi.AutocompleteSessionToken = AutocompleteSessionToken;
 			placesApi.AutocompleteSuggestion = AutocompleteSuggestion;
 
-			// const {Geocoder} = await loader.importLibrary("geocoding");
-			// placesApi.Geocoder = new Geocoder();
-
 			setSessionToken();
 		} catch (e: any) {
+			console.log(e);
 			onError(
 				(e.name || 'An error occurred') + ' - ' + (e.message || 'Error loading Google Maps API')
 			);
@@ -318,11 +284,19 @@
 	}
 </script>
 
-<svelte:window onkeydown={onKeyDown} onclick={handleClickOutside} />
-
-<section class={options.classes?.section}>
+<svelte:window onclick={handleClickOutside} />
+
+<section
+	class={options.classes?.section}
+	role="combobox"
+	aria-controls="autocomplete-listbox"
+	tabindex="0"
+	aria-haspopup="listbox"
+	aria-expanded={results.length > 0}
+	aria-owns="autocomplete-listbox"
+>
 	{#if options?.label ?? ''}
-		<label for="search" class={options.classes?.label ?? ''}>
+		<label for="places-autocomplete-input" class={options.classes?.label ?? ''}>
 			{options.label}
 		</label>
 	{/if}
@@ -334,6 +308,7 @@
 		{/if}
 
 		<input
+			id="places-autocomplete-input"
 			type="text"
 			name="search"
 			bind:this={inputRef}
@@ -346,7 +321,9 @@
 			aria-labelledby="search"
 			aria-label="Search"
 			aria-haspopup="listbox"
+			aria-activedescendant={currentSuggestion > -1 ? `option-${currentSuggestion + 1}` : undefined}
 			bind:value={request.input}
+			onkeydown={onKeyDown}
 			oninput={(event) => debouncedMakeAcRequest(event.currentTarget.value)}
 		/>
 		<!-- oninput={makeAcRequest} -->
@@ -362,7 +339,7 @@
 					>&dArr;</kbd
 				>
 			</div>
-			<ul class={options.classes?.ul ?? ''} id="options" role="listbox">
+			<ul class={options.classes?.ul ?? ''} id="autocomplete-listbox" role="listbox">
 				{#each results as p, i}
 					<li
 						role="option"
@@ -374,7 +351,6 @@
 						onmouseenter={() => (currentSuggestion = i)}
 						id="option-{i + 1}"
 					>
-						<!-- svelte-ignore a11y_invalid_attribute -->
 						<button
 							type="button"
 							class={[
@@ -396,8 +372,14 @@
 											options.classes?.li_div_one_p
 										]}
 									>
-										<!-- {p.text} -->
-										{@html p.text}
+										{#each p.text as segment}
+											{#if segment.highlighted}
+												<span class={options.classes?.highlight ?? 'font-bold'}>{segment.text}</span
+												>
+											{:else}
+												{segment.text}
+											{/if}
+										{/each}
 									</p>
 								</div>
 							</div>

package/dist/gmaps.d.ts

@@ -0,0 +1,11 @@
+import * as GMaps from '@googlemaps/js-api-loader';
+/**
+ * Defines the shape of the context object that will be shared.
+ * This can be expanded if you need to share more than just the loader.
+ */
+export type GMapsLoaderType = GMaps.Loader;
+/**
+ * Gets the Google Maps Loader instance from Svelte's context.
+ * @returns {typeof Loader}
+ */
+export declare const getGMapsLoader: (PUBLIC_GOOGLE_MAPS_API_KEY: string, version?: string | undefined) => GMaps.Loader;

package/dist/gmaps.js

@@ -0,0 +1,23 @@
+import { getContext, setContext, hasContext } from 'svelte';
+import * as GMaps from '@googlemaps/js-api-loader';
+const { Loader } = GMaps;
+/**
+ * A unique key for setting and getting the Google Maps Loader instance from Svelte's context.
+ * This allows multiple components to share a single loader instance.
+ */
+const gmapsContextKey = Symbol('pacgmaps');
+/**
+ * Gets the Google Maps Loader instance from Svelte's context.
+ * @returns {typeof Loader}
+ */
+export const getGMapsLoader = (PUBLIC_GOOGLE_MAPS_API_KEY, version) => {
+    version = version || 'weekly';
+    if (!hasContext(gmapsContextKey)) {
+        const loader = new Loader({
+            apiKey: PUBLIC_GOOGLE_MAPS_API_KEY,
+            version: version,
+        });
+        setContext(gmapsContextKey, loader);
+    }
+    return getContext(gmapsContextKey);
+};

package/dist/helpers.d.ts

@@ -41,3 +41,25 @@ export declare const validateOptions: (options: ComponentOptions | undefined) =>
  * @returns
  */
 export declare const formatDistance: (distance: number, units: DistanceUnits) => string | null;
+/**
+ * Create highlighted segments from the original text based on the provided matches.
+ * @param originalText The original text to segment.
+ * @param matches An array of match objects containing start and end offsets.
+ * @returns An array of text segments with highlighting information.
+ */
+export declare function createHighlightedSegments(originalText: string, matches: {
+    startOffset: number;
+    endOffset: number;
+}[]): {
+    text: string;
+    highlighted: boolean;
+}[];
+/**
+ * Debounce function that takes a function and a delay
+ * and returns a new function that will only execute
+ * after the delay has passed without any new calls.
+ * This version is generic and preserves the types of the original function.
+ * @param func The function to debounce.
+ * @param delay The debounce delay in milliseconds.
+ */
+export declare const debounce: <T extends (...args: any[]) => void>(func: T, delay: number) => (...args: Parameters<T>) => void;

package/dist/helpers.js

@@ -363,3 +363,49 @@ export const formatDistance = function (distance, units) {
         return `${(distance / 1609.34).toFixed(2)} miles`;
     }
 };
+/**
+ * Create highlighted segments from the original text based on the provided matches.
+ * @param originalText The original text to segment.
+ * @param matches An array of match objects containing start and end offsets.
+ * @returns An array of text segments with highlighting information.
+ */
+export function createHighlightedSegments(originalText, matches) {
+    const segments = [];
+    if (!originalText || !matches)
+        return segments;
+    let lastIndex = 0;
+    // Sort matches just in case they aren't ordered
+    matches.sort((a, b) => a.startOffset - b.startOffset);
+    for (const match of matches) {
+        // Add text before the match
+        if (match.startOffset > lastIndex) {
+            segments.push({ text: originalText.substring(lastIndex, match.startOffset), highlighted: false });
+        }
+        // Add the matched text
+        segments.push({ text: originalText.substring(match.startOffset, match.endOffset), highlighted: true });
+        lastIndex = match.endOffset;
+    }
+    // Add any remaining text after the last match
+    if (lastIndex < originalText.length) {
+        segments.push({ text: originalText.substring(lastIndex), highlighted: false });
+    }
+    return segments;
+}
+/**
+ * Debounce function that takes a function and a delay
+ * and returns a new function that will only execute
+ * after the delay has passed without any new calls.
+ * This version is generic and preserves the types of the original function.
+ * @param func The function to debounce.
+ * @param delay The debounce delay in milliseconds.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const debounce = (func, delay) => {
+    let timeout;
+    return (...args) => {
+        clearTimeout(timeout);
+        timeout = setTimeout(() => {
+            func(...args);
+        }, delay);
+    };
+};

package/dist/interfaces.d.ts

@@ -48,6 +48,11 @@ export interface PlaceResult {
         shortText: string;
         types: string[];
     }[];
+    location?: {
+        lat: number;
+        lng: number;
+    };
+    [key: string]: unknown;
 }
 export interface FormattedAddress {
     street_number: string;
@@ -61,6 +66,7 @@ export interface Props {
     PUBLIC_GOOGLE_MAPS_API_KEY: string;
     options?: ComponentOptions;
     fetchFields?: string[];
+    libraries?: string[];
     requestParams?: RequestParams;
     onResponse: (response: PlaceResult) => void;
     onError: (error: string) => void;

package/package.json

@@ -1,8 +1,8 @@
 {
 	"name": "places-autocomplete-svelte",
 	"license": "MIT",
-	"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.",
+	"version": "2.2.16",
+	"description": "A flexible, accessible, and secure Svelte component leveraging the Google Maps Places Autocomplete API (New) to provide a user-friendly way to search for and retrieve detailed address information.",
 	"keywords": [
 		"svelte",
 		"sveltekit",
@@ -52,6 +52,10 @@
 			"svelte": "./dist/interfaces.js",
 			"default": "./dist/interfaces.js"
 		},
+		"./gmaps": {
+			"types": "./dist/gmaps.d.ts",
+			"svelte": "./dist/gmaps.js"
+		},		
 		".": {
 			"types": "./dist/index.d.ts",
 			"svelte": "./dist/index.js",
@@ -71,36 +75,38 @@
 		"svelte": "^5.0.0"
 	},
 	"devDependencies": {
-		"@sveltejs/adapter-auto": "^6.0.1",
-		"@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.11",
+		"@sveltejs/adapter-auto": "^6.1.0",
+		"@sveltejs/adapter-cloudflare": "^7.2.2",
+		"@sveltejs/kit": "^2.36.1",
+		"@sveltejs/package": "^2.5.0",
+		"@sveltejs/vite-plugin-svelte": "^6.1.3",
+		"@tailwindcss/postcss": "^4.1.12",
 		"@tailwindcss/typography": "^0.5.16",
-		"@tailwindcss/vite": "^4.1.11",
+		"@tailwindcss/vite": "^4.1.12",
 		"@types/eslint": "^9.6.1",
+		"@types/google.maps": "^3.58.1",
+		"@types/node": "^24.3.0",
 		"autoprefixer": "^10.4.21",
-		"eslint": "^9.30.1",
-		"eslint-config-prettier": "^10.1.5",
-		"eslint-plugin-svelte": "^3.10.1",
+		"eslint": "^9.34.0",
+		"eslint-config-prettier": "^10.1.8",
+		"eslint-plugin-svelte": "^3.11.0",
 		"globals": "^16.3.0",
 		"postcss": "^8.5.6",
 		"prettier": "^3.6.2",
 		"prettier-plugin-svelte": "^3.4.0",
 		"publint": "^0.3.12",
-		"svelte": "^5.35.2",
-		"svelte-check": "^4.2.2",
-		"tailwindcss": "^4.1.11",
+		"svelte": "^5.38.2",
+		"svelte-check": "^4.3.1",
+		"tailwindcss": "^4.1.12",
 		"tslib": "^2.8.1",
-		"typescript": "^5.8.3",
-		"typescript-eslint": "^8.35.1",
-		"vite": "^6.3.5"
+		"typescript": "^5.9.2",
+		"typescript-eslint": "^8.40.0",
+		"vite": "^7.1.3"
 	},
 	"svelte": "./dist/index.js",
 	"types": "./dist/PlaceAutocomplete.svelte.d.ts",
 	"type": "module",
 	"dependencies": {
-		"@googlemaps/js-api-loader": "^1.16.8"
+		"@googlemaps/js-api-loader": "^1.16.10"
 	}
 }