places-autocomplete-svelte 2.2.16 → 2.2.17

package/README.md

@@ -53,110 +53,69 @@ yarn add places-autocomplete-svelte
 
 ## Usage
 
-Provide your Google Maps API key to the component. It will automatically handle loading the required `places` library.
+The `PlaceAutocomplete` component is designed for simplicity. Here’s the minimum required to get it working:
 
-```javascript
-<script lang="ts">
-import { PlaceAutocomplete } from 'places-autocomplete-svelte';
-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;
+```javascript
+// In your +page.svelte or a parent component
 
-// --- Event Handlers ---
-let fullResponse: PlaceResult | null = $state(null);
-let placesError = $state('');
+<script lang="ts">
+    import { PlaceAutocomplete } from 'places-autocomplete-svelte';
+    import type { PlaceResult } from 'places-autocomplete-svelte/interfaces';
 
-const handleResponse = (response: PlaceResult) => {
-	console.log('Place Selected:', response);
-	fullResponse = response;
-	placesError = ''; // Clear previous errors
-};
+    // Get API Key securely (e.g., from environment variables)
+    const PUBLIC_GOOGLE_MAPS_API_KEY = import.meta.env.VITE_PUBLIC_GOOGLE_MAPS_API_KEY;    
 
-const handleError = (error: string) => {
-	console.error('Places Autocomplete Error:', error);
-	placesError = error;
-	fullResponse = null; // Clear previous results
-};
+    // --- Handle Component Response ---
+    const handleResponse = (response: PlaceResult) => {
+        console.log('Place Selected:', response.formattedAddress);
+    };
 
-// --- Configuration (Optional) ---
-const requestParams: Partial<RequestParams> = $state({
-	region: 'GB',
-	language: 'en-GB',
-});
-const fetchFields: string[] = $state(['formattedAddress', 'addressComponents', 'displayName']);
-const options: Partial<ComponentOptions> = $state({
-	placeholder: 'Start typing your address...',
-	debounce: 200,
-	classes: {
-		input: 'my-custom-input-class border-blue-500',
-		highlight: 'bg-yellow-200 text-black',
-	},
-    clear_input: false,
-});
+    // --- Handle Component Errors ---
+    const handleError = (error: string) => {
+        console.error('Error:', error);
+    };
 </script>
 
-{#if placesError}
-    <div class="error-message" role="alert">
-        Error: {placesError}
-    </div>
-{/if}
-
-<PlaceAutocomplete
-    {PUBLIC_GOOGLE_MAPS_API_KEY}
-    {requestParams}
-    {fetchFields}
-    {options}
-    onResponse={handleResponse}
-    onError={handleError}
-/>
-
-{#if fullResponse}
-    <h2>Selected Place Details:</h2>
-    <pre>{JSON.stringify(fullResponse, null, 2)}</pre>
-{/if}
-
-<style>
-    :global(.my-custom-input-class) {
-        padding: 0.75rem;
-        border-radius: 0.25rem;
-        width: 100%;
-    }
-    .error-message {
-        color: red;
-        margin-bottom: 1rem;
-    }
-</style>
+<!-- Add the component to your page -->
+<PlaceAutocomplete {onResponse} {onError} {PUBLIC_GOOGLE_MAPS_API_KEY} />
 ```
 
 ### Advanced: Using with other Google Maps Libraries
 
-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.
+The `PlaceAutocomplete` component intelligently manages the Google Maps loader. For simple use cases, it handles loading automatically. However, if you need to use other Google Maps libraries (like `maps` or `marker`) on the same page, you should initialise the loader once in a parent component (`+page.svelte` or `+layout.svelte`). This prevents conflicts and ensures all libraries are loaded efficiently.
+
+The component provides helper functions (`setGMapsContext`, `getGMapsContext`, `initialiseGMaps`) to manage this.
+
+Here is how you would set it up in your `+page.svelte`:
 
-The `PlaceAutocomplete` component only loads the `places` library by default. 
 ```javascript
-// In a parent component, e.g., src/routes/+page.svelte
+// src/routes/+page.svelte
 <script lang="ts">
-	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');
-        ...
-	});
+    import { onMount } from 'svelte';
+    import { browser } from '$app/environment';
+    import { PlaceAutocomplete } from 'places-autocomplete-svelte';
+    import { initialiseGMaps, setGMapsContext, getGMapsContext } from 'places-autocomplete-svelte/gmaps';
+
+    // 1. Set the context for Google Maps. This should be done in the script's top-level scope.
+    setGMapsContext();
+
+    // 2. If we are in the browser, trigger the asynchronous loading process.
+    if (browser) {
+        initialiseGMaps({
+			key: import.meta.env.VITE_PUBLIC_GOOGLE_MAPS_API_KEY,
+			v: 'weekly' 
+		}).catch((error: any) => {
+			// ... handle error (already logged in initialiseGMaps)
+        });
+    }
+
+    // ... rest of your component logic
 </script>
 
-<!-- The component will now use the loader you created above -->
-<PlaceAutocomplete
-    {PUBLIC_GOOGLE_MAPS_API_KEY}
-    onResponse={...}
-    onError={...}
-/>
+<!-- The PlaceAutocomplete component will automatically use the context -->
+<!-- You do NOT need to pass the `PUBLIC_GOOGLE_MAPS_API_KEY` prop to the component if you initialise the loader in a parent component.-->
+<PlaceAutocomplete onResponse={...} onError={...} />
 
 <!-- You can now use other Google Maps services, e.g., a map -->
 <div id="map"></div>
@@ -189,7 +148,7 @@ This component is built to be accessible and follows the [WAI-ARIA Authoring Pra
 
 | Prop | Type | Required | Default | Description |
 | :--- | :--- | :--- | :--- | :--- |
-| `PUBLIC_GOOGLE_MAPS_API_KEY` | `string` | Yes | - | Your restricted Google Maps API Key. |
+| `PUBLIC_GOOGLE_MAPS_API_KEY` | `string` | Yes | - | Your restricted Google Maps API Key. Not required if the loader has been initialised in a parent component. |
 | `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. |

package/dist/PlaceAutocomplete.svelte

@@ -1,6 +1,7 @@
 <script lang="ts">
 	import { onMount } from 'svelte';
 	import type { PlaceResult, Props } from './interfaces.js';
+	import { getGMapsContext, hasGMapsContext, importLibrary, initialiseGMapsNoContext, type GMapsContext } from './gmaps.js';
 	import {
 		validateOptions,
 		validateRequestParams,
@@ -10,7 +11,13 @@
 		debounce
 	} from './helpers.js';
 
-	import { getGMapsLoader, type GMapsLoaderType } from './gmaps.js';
+
+	let gmaps: GMapsContext | undefined;
+	// Get the context synchronously. This is safe.
+	if (hasGMapsContext()) {
+		gmaps = getGMapsContext();
+	}
+	
 
 
 	let {
@@ -18,7 +25,7 @@
 		 * By default using SKU: Place Detals (Location Only) - 0.005 USD per each
 		 * @see https://developers.google.com/maps/documentation/javascript/usage-and-billing#location-placedetails
 		 */
-		PUBLIC_GOOGLE_MAPS_API_KEY,
+		PUBLIC_GOOGLE_MAPS_API_KEY='',
 		fetchFields,
 		options,
 		onResponse = $bindable((response: PlaceResult) => {}),
@@ -36,7 +43,6 @@
 	fetchFields = validateFetchFields(fetchFields);
 	//console.log(fetchFields);
 
-
 	let kbdAction = $state(''); // 'up', 'down', or 'escape'
 
 	// Local variables
@@ -44,7 +50,6 @@
 	let currentSuggestion = $state(-1);
 	let results: any[] = $state([]);
 	let placesApi: { [key: string]: any } = {};
-	let loader: GMapsLoaderType;
 
 	//https://developers.google.com/maps/documentation/javascript/reference/autocomplete-data
 	// validate requestParams
@@ -213,6 +218,8 @@
 	 * 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.'
@@ -224,16 +231,26 @@
 		}
 
 		try {
-			loader = getGMapsLoader(PUBLIC_GOOGLE_MAPS_API_KEY);
-		} catch (e: any) {
-			onError(
-				(e.name || 'An error occurred') + ' - ' + (e.message || 'Error loading Google Maps API')
-			);
-		}
+       		// Await the promise that was stored in the context by the parent.
+            // 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;
+			}else{
+
+				// Check if the API key is provided
+				if(PUBLIC_GOOGLE_MAPS_API_KEY === '' || !PUBLIC_GOOGLE_MAPS_API_KEY) {
+					throw new Error('Google Maps API key is required. Please provide a valid API key.');
+				}
+
+				// No context available, initialize without context
+				// This will load the Google Maps script
+				// and set up the necessary objects
+				// for places API usage.
+				await initialiseGMapsNoContext({key: PUBLIC_GOOGLE_MAPS_API_KEY, 'v': 'weekly'});
+			}
 
-		try {
-			const { AutocompleteSessionToken, AutocompleteSuggestion } =
-				await loader.importLibrary('places');
+			const { AutocompleteSessionToken, AutocompleteSuggestion } = await importLibrary('places');
 
 			placesApi.AutocompleteSessionToken = AutocompleteSessionToken;
 			placesApi.AutocompleteSuggestion = AutocompleteSuggestion;

package/dist/gmaps.d.ts

@@ -1,11 +1,34 @@
-import * as GMaps from '@googlemaps/js-api-loader';
+import { type Writable } from 'svelte/store';
+import { importLibrary, type APIOptions } from "@googlemaps/js-api-loader";
+interface GMapsContext {
+    isInitialized: Writable<boolean>;
+    error: Writable<Error | null>;
+    initializationPromise: Promise<void> | null;
+}
+export type { GMapsContext, APIOptions };
 /**
- * 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.
+ * Creates and sets the Google Maps context with writable stores.
+ * This is synchronous and should be called once in a top-level component's script.
  */
-export type GMapsLoaderType = GMaps.Loader;
+export declare function setGMapsContext(): void;
 /**
- * Gets the Google Maps Loader instance from Svelte's context.
- * @returns {typeof Loader}
+ * Retrieves the shared Google Maps context.
+ * @returns {GMapsContext} The stores for initialization status and errors.
  */
-export declare const getGMapsLoader: (PUBLIC_GOOGLE_MAPS_API_KEY: string, version?: string | undefined) => GMaps.Loader;
+export declare function getGMapsContext(): GMapsContext;
+export declare function hasGMapsContext(): boolean;
+/**
+ * Asynchronously initializes the Google Maps loader using the provided context.
+ * This function is idempotent and safe to be called multiple times.
+ * @param context - The GMapsContext object.
+ * @param options - The options for the JS API loader, including your API key.
+ * @returns {Promise<void>}
+ */
+export declare function initialiseGMaps(options: APIOptions): Promise<void>;
+/**
+ * Initializes the Google Maps API without using the context.
+ * @param options The options for the JS API loader, including your API key.
+ * @returns A promise that resolves when the API is initialized.
+ */
+export declare function initialiseGMapsNoContext(options: APIOptions): Promise<void>;
+export { importLibrary };

package/dist/gmaps.js

@@ -1,23 +1,87 @@
-import { getContext, setContext, hasContext } from 'svelte';
-import * as GMaps from '@googlemaps/js-api-loader';
-const { Loader } = GMaps;
+import { getContext, setContext } from 'svelte';
+import { writable, get } from 'svelte/store';
+import { setOptions, importLibrary } from "@googlemaps/js-api-loader";
+const LOADER_CONTEXT_KEY = Symbol('gmaps-loader');
 /**
- * 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.
+ * Creates and sets the Google Maps context with writable stores.
+ * This is synchronous and should be called once in a top-level component's script.
  */
-const gmapsContextKey = Symbol('pacgmaps');
+export function setGMapsContext() {
+    // Only set the context if it doesn't already exist.
+    if (getContext(LOADER_CONTEXT_KEY))
+        return;
+    setContext(LOADER_CONTEXT_KEY, {
+        isInitialized: writable(false),
+        error: writable(null),
+        initializationPromise: null, // Will be set by the loader function
+    });
+}
 /**
- * Gets the Google Maps Loader instance from Svelte's context.
- * @returns {typeof Loader}
+ * Retrieves the shared Google Maps context.
+ * @returns {GMapsContext} The stores for initialization status and errors.
  */
-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);
+export function getGMapsContext() {
+    const context = getContext(LOADER_CONTEXT_KEY);
+    if (!context) {
+        throw new Error('Google Maps context not found. Call setGMapsContext in a parent component.');
     }
-    return getContext(gmapsContextKey);
-};
+    return context;
+}
+export function hasGMapsContext() {
+    const context = getContext(LOADER_CONTEXT_KEY);
+    return !!context;
+}
+/**
+ * Asynchronously initializes the Google Maps loader using the provided context.
+ * This function is idempotent and safe to be called multiple times.
+ * @param context - The GMapsContext object.
+ * @param options - The options for the JS API loader, including your API key.
+ * @returns {Promise<void>}
+ */
+export async function initialiseGMaps(options) {
+    // Get the context internally
+    const context = getGMapsContext();
+    // If the promise already exists, just await it. Don't re-initialize.
+    if (context.initializationPromise) {
+        return context.initializationPromise;
+    }
+    // If it's already marked as initialized (e.g., from a previous page navigation), resolve immediately.
+    if (get(context.isInitialized)) {
+        return Promise.resolve();
+    }
+    // Create the promise and store it in the context object.
+    context.initializationPromise = new Promise((resolve, reject) => {
+        try {
+            setOptions(options); // Await the setOptions which returns a promise
+            context.isInitialized.set(true);
+            resolve();
+        }
+        catch (e) {
+            const error = e instanceof Error ? e : new Error(String(e));
+            context.error.set(error);
+            console.error("Failed to set Google Maps API options.", error);
+            reject(error);
+        }
+    });
+    return context.initializationPromise;
+}
+/**
+ * Initializes the Google Maps API without using the context.
+ * @param options The options for the JS API loader, including your API key.
+ * @returns A promise that resolves when the API is initialized.
+ */
+export function initialiseGMapsNoContext(options) {
+    return new Promise((resolve, reject) => {
+        try {
+            setOptions(options);
+            resolve();
+        }
+        catch (e) {
+            const error = e instanceof Error ? e : new Error(String(e));
+            console.error("Failed to set Google Maps API options.", error);
+            reject(error);
+        }
+    });
+}
+// Re-export importLibrary for components to use.
+export { importLibrary };

package/dist/interfaces.d.ts

@@ -63,7 +63,7 @@ export interface FormattedAddress {
     postcode: string;
 }
 export interface Props {
-    PUBLIC_GOOGLE_MAPS_API_KEY: string;
+    PUBLIC_GOOGLE_MAPS_API_KEY?: string;
     options?: ComponentOptions;
     fetchFields?: string[];
     libraries?: string[];

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "places-autocomplete-svelte",
 	"license": "MIT",
-	"version": "2.2.16",
+	"version": "2.2.17",
 	"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",
@@ -55,7 +55,7 @@
 		"./gmaps": {
 			"types": "./dist/gmaps.d.ts",
 			"svelte": "./dist/gmaps.js"
-		},		
+		},
 		".": {
 			"types": "./dist/index.d.ts",
 			"svelte": "./dist/index.js",
@@ -75,38 +75,38 @@
 		"svelte": "^5.0.0"
 	},
 	"devDependencies": {
-		"@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.12",
+		"@sveltejs/adapter-auto": "^6.1.1",
+		"@sveltejs/adapter-cloudflare": "^7.2.4",
+		"@sveltejs/kit": "^2.46.4",
+		"@sveltejs/package": "^2.5.4",
+		"@sveltejs/vite-plugin-svelte": "^6.2.1",
+		"@tailwindcss/postcss": "^4.1.14",
+		"@tailwindcss/typography": "^0.5.19",
+		"@tailwindcss/vite": "^4.1.14",
 		"@types/eslint": "^9.6.1",
 		"@types/google.maps": "^3.58.1",
-		"@types/node": "^24.3.0",
+		"@types/node": "^24.7.1",
 		"autoprefixer": "^10.4.21",
-		"eslint": "^9.34.0",
+		"eslint": "^9.37.0",
 		"eslint-config-prettier": "^10.1.8",
-		"eslint-plugin-svelte": "^3.11.0",
-		"globals": "^16.3.0",
+		"eslint-plugin-svelte": "^3.12.4",
+		"globals": "^16.4.0",
 		"postcss": "^8.5.6",
 		"prettier": "^3.6.2",
 		"prettier-plugin-svelte": "^3.4.0",
-		"publint": "^0.3.12",
-		"svelte": "^5.38.2",
-		"svelte-check": "^4.3.1",
-		"tailwindcss": "^4.1.12",
+		"publint": "^0.3.14",
+		"svelte": "^5.39.11",
+		"svelte-check": "^4.3.3",
+		"tailwindcss": "^4.1.14",
 		"tslib": "^2.8.1",
-		"typescript": "^5.9.2",
-		"typescript-eslint": "^8.40.0",
-		"vite": "^7.1.3"
+		"typescript": "^5.9.3",
+		"typescript-eslint": "^8.46.0",
+		"vite": "^7.1.9"
 	},
 	"svelte": "./dist/index.js",
 	"types": "./dist/PlaceAutocomplete.svelte.d.ts",
 	"type": "module",
 	"dependencies": {
-		"@googlemaps/js-api-loader": "^1.16.10"
+		"@googlemaps/js-api-loader": "^2.0.1"
 	}
 }