places-autocomplete-svelte 2.2.20 → 2.2.21

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -2,7 +2,10 @@ import type { Props } from './interfaces.js';
2
2
  declare const PlaceAutocomplete: import("svelte").Component<Props, {
3
3
  clear: () => void;
4
4
  focus: () => void;
5
- getRequestParams: () => import("./interfaces.js").RequestParams;
5
+ getRequestParams: () => any;
6
+ setRequestParams: (params: Partial<import("./interfaces.js").RequestParams>) => void;
7
+ setFetchFields: (fields: string[]) => void;
8
+ getFetchFields: () => string[];
6
9
  }, "onResponse" | "onError">;
7
10
  type PlaceAutocomplete = ReturnType<typeof PlaceAutocomplete>;
8
11
  export default PlaceAutocomplete;
package/dist/gmaps.d.ts CHANGED
@@ -1,34 +1,82 @@
1
1
  import { type Writable } from 'svelte/store';
2
2
  import { importLibrary, type APIOptions } from "@googlemaps/js-api-loader";
3
+ /**
4
+ * Context object for managing Google Maps API initialisation state across components.
5
+ * Provides reactive stores for initialisation status and error handling, plus a shared promise
6
+ * to prevent duplicate API loading attempts.
7
+ * @interface GMapsContext
8
+ */
3
9
  interface GMapsContext {
4
- isInitialized: Writable<boolean>;
10
+ /** Reactive store tracking whether the Google Maps API has been successfully initialised. */
11
+ isInitialised: Writable<boolean>;
12
+ /** Reactive store containing any error that occurred during API initialisation. */
5
13
  error: Writable<Error | null>;
6
- initializationPromise: Promise<void> | null;
14
+ /** Shared promise for API initialisation, ensuring only one load attempt occurs across all components. */
15
+ initialisationPromise: Promise<void> | null;
7
16
  }
17
+ /**
18
+ * Re-exported types for external use.
19
+ * @public
20
+ */
8
21
  export type { GMapsContext, APIOptions };
9
22
  /**
10
- * Creates and sets the Google Maps context with writable stores.
11
- * This is synchronous and should be called once in a top-level component's script.
23
+ * Creates and initialises the Google Maps context with reactive stores.
24
+ * This function should be called once in a top-level parent component (e.g., +layout.svelte)
25
+ * before any child components attempt to use the Google Maps API.
26
+ * The function is idempotent - calling it multiple times has no effect after the first call.
27
+ * @public
28
+ * @returns {void}
29
+ * @example
30
+ * // In +layout.svelte
31
+ * <script>
32
+ * import { setGMapsContext } from './gmaps';
33
+ * setGMapsContext();
34
+ * </script>
12
35
  */
13
36
  export declare function setGMapsContext(): void;
14
37
  /**
15
- * Retrieves the shared Google Maps context.
16
- * @returns {GMapsContext} The stores for initialization status and errors.
38
+ * Retrieves the shared Google Maps context from Svelte's context API.
39
+ * Must be called after setGMapsContext() has been invoked in a parent component.
40
+ * @public
41
+ * @returns {GMapsContext} The context object containing initialisation stores and promise.
42
+ * @throws {Error} If the context has not been set by a parent component.
17
43
  */
18
44
  export declare function getGMapsContext(): GMapsContext;
45
+ /**
46
+ * Checks whether the Google Maps context has been set in the component tree.
47
+ * Use this to conditionally handle scenarios where context may or may not be available.
48
+ * @public
49
+ * @returns {boolean} True if the context exists, false otherwise.
50
+ */
19
51
  export declare function hasGMapsContext(): boolean;
20
52
  /**
21
- * Asynchronously initializes the Google Maps loader using the provided context.
22
- * This function is idempotent and safe to be called multiple times.
23
- * @param context - The GMapsContext object.
24
- * @param options - The options for the JS API loader, including your API key.
25
- * @returns {Promise<void>}
53
+ * Asynchronously initialises the Google Maps JavaScript API using the shared context.
54
+ * This function is idempotent and safe to call multiple times - subsequent calls will
55
+ * return the same initialisation promise, preventing duplicate API loading.
56
+ * @public
57
+ * @param {APIOptions} options - Configuration options for the Google Maps API loader, including API key.
58
+ * @returns {Promise<void>} A promise that resolves when the API is fully initialised.
59
+ * @throws {Error} If API initialisation fails (e.g., invalid API key, network issues).
60
+ * @example
61
+ * await initialiseGMaps({ key: 'YOUR_API_KEY', v: 'weekly' });
26
62
  */
27
63
  export declare function initialiseGMaps(options: APIOptions): Promise<void>;
28
64
  /**
29
- * Initializes the Google Maps API without using the context.
30
- * @param options The options for the JS API loader, including your API key.
31
- * @returns A promise that resolves when the API is initialized.
65
+ * Initialises the Google Maps JavaScript API without using the Svelte context system.
66
+ * Use this when you need standalone initialisation without sharing state across components,
67
+ * such as in the PlaceAutocomplete component when no parent context provider is available.
68
+ * @public
69
+ * @param {APIOptions} options - Configuration options for the Google Maps API loader, including API key.
70
+ * @returns {Promise<void>} A promise that resolves when the API is initialised.
71
+ * @throws {Error} If API initialisation fails.
72
+ * @example
73
+ * await initialiseGMapsNoContext({ key: 'YOUR_API_KEY', v: 'weekly' });
32
74
  */
33
75
  export declare function initialiseGMapsNoContext(options: APIOptions): Promise<void>;
76
+ /**
77
+ * Re-exported from @googlemaps/js-api-loader for convenient access.
78
+ * Dynamically imports a specific Google Maps library (e.g., 'places', 'maps', 'marker').
79
+ * @public
80
+ * @see https://developers.google.com/maps/documentation/javascript/importing-libraries
81
+ */
34
82
  export { importLibrary };
package/dist/gmaps.js CHANGED
@@ -1,24 +1,42 @@
1
1
  import { getContext, setContext } from 'svelte';
2
2
  import { writable, get } from 'svelte/store';
3
3
  import { setOptions, importLibrary } from "@googlemaps/js-api-loader";
4
+ /**
5
+ * Unique symbol key for storing the Google Maps context in Svelte's context API.
6
+ * Using a Symbol ensures the key cannot be accidentally overwritten by other components.
7
+ * @private
8
+ */
4
9
  const LOADER_CONTEXT_KEY = Symbol('gmaps-loader');
5
10
  /**
6
- * Creates and sets the Google Maps context with writable stores.
7
- * This is synchronous and should be called once in a top-level component's script.
11
+ * Creates and initialises the Google Maps context with reactive stores.
12
+ * This function should be called once in a top-level parent component (e.g., +layout.svelte)
13
+ * before any child components attempt to use the Google Maps API.
14
+ * The function is idempotent - calling it multiple times has no effect after the first call.
15
+ * @public
16
+ * @returns {void}
17
+ * @example
18
+ * // In +layout.svelte
19
+ * <script>
20
+ * import { setGMapsContext } from './gmaps';
21
+ * setGMapsContext();
22
+ * </script>
8
23
  */
9
24
  export function setGMapsContext() {
10
25
  // Only set the context if it doesn't already exist.
11
26
  if (getContext(LOADER_CONTEXT_KEY))
12
27
  return;
13
28
  setContext(LOADER_CONTEXT_KEY, {
14
- isInitialized: writable(false),
29
+ isInitialised: writable(false),
15
30
  error: writable(null),
16
- initializationPromise: null, // Will be set by the loader function
31
+ initialisationPromise: null, // Will be set by the loader function
17
32
  });
18
33
  }
19
34
  /**
20
- * Retrieves the shared Google Maps context.
21
- * @returns {GMapsContext} The stores for initialization status and errors.
35
+ * Retrieves the shared Google Maps context from Svelte's context API.
36
+ * Must be called after setGMapsContext() has been invoked in a parent component.
37
+ * @public
38
+ * @returns {GMapsContext} The context object containing initialisation stores and promise.
39
+ * @throws {Error} If the context has not been set by a parent component.
22
40
  */
23
41
  export function getGMapsContext() {
24
42
  const context = getContext(LOADER_CONTEXT_KEY);
@@ -27,33 +45,43 @@ export function getGMapsContext() {
27
45
  }
28
46
  return context;
29
47
  }
48
+ /**
49
+ * Checks whether the Google Maps context has been set in the component tree.
50
+ * Use this to conditionally handle scenarios where context may or may not be available.
51
+ * @public
52
+ * @returns {boolean} True if the context exists, false otherwise.
53
+ */
30
54
  export function hasGMapsContext() {
31
55
  const context = getContext(LOADER_CONTEXT_KEY);
32
56
  return !!context;
33
57
  }
34
58
  /**
35
- * Asynchronously initializes the Google Maps loader using the provided context.
36
- * This function is idempotent and safe to be called multiple times.
37
- * @param context - The GMapsContext object.
38
- * @param options - The options for the JS API loader, including your API key.
39
- * @returns {Promise<void>}
59
+ * Asynchronously initialises the Google Maps JavaScript API using the shared context.
60
+ * This function is idempotent and safe to call multiple times - subsequent calls will
61
+ * return the same initialisation promise, preventing duplicate API loading.
62
+ * @public
63
+ * @param {APIOptions} options - Configuration options for the Google Maps API loader, including API key.
64
+ * @returns {Promise<void>} A promise that resolves when the API is fully initialised.
65
+ * @throws {Error} If API initialisation fails (e.g., invalid API key, network issues).
66
+ * @example
67
+ * await initialiseGMaps({ key: 'YOUR_API_KEY', v: 'weekly' });
40
68
  */
41
69
  export async function initialiseGMaps(options) {
42
70
  // Get the context internally
43
71
  const context = getGMapsContext();
44
- // If the promise already exists, just await it. Don't re-initialize.
45
- if (context.initializationPromise) {
46
- return context.initializationPromise;
72
+ // If initialisation is already in progress or completed, return the existing promise
73
+ if (context.initialisationPromise) {
74
+ return context.initialisationPromise;
47
75
  }
48
- // If it's already marked as initialized (e.g., from a previous page navigation), resolve immediately.
49
- if (get(context.isInitialized)) {
76
+ // If already initialised (e.g., from browser navigation or hot reload), resolve immediately
77
+ if (get(context.isInitialised)) {
50
78
  return Promise.resolve();
51
79
  }
52
- // Create the promise and store it in the context object.
53
- context.initializationPromise = new Promise((resolve, reject) => {
80
+ // Create a new initialisation promise and store it in the context to prevent duplicate loads
81
+ context.initialisationPromise = new Promise((resolve, reject) => {
54
82
  try {
55
- setOptions(options); // Await the setOptions which returns a promise
56
- context.isInitialized.set(true);
83
+ setOptions(options); // Configure the Google Maps API loader with provided options
84
+ context.isInitialised.set(true);
57
85
  resolve();
58
86
  }
59
87
  catch (e) {
@@ -63,12 +91,18 @@ export async function initialiseGMaps(options) {
63
91
  reject(error);
64
92
  }
65
93
  });
66
- return context.initializationPromise;
94
+ return context.initialisationPromise;
67
95
  }
68
96
  /**
69
- * Initializes the Google Maps API without using the context.
70
- * @param options The options for the JS API loader, including your API key.
71
- * @returns A promise that resolves when the API is initialized.
97
+ * Initialises the Google Maps JavaScript API without using the Svelte context system.
98
+ * Use this when you need standalone initialisation without sharing state across components,
99
+ * such as in the PlaceAutocomplete component when no parent context provider is available.
100
+ * @public
101
+ * @param {APIOptions} options - Configuration options for the Google Maps API loader, including API key.
102
+ * @returns {Promise<void>} A promise that resolves when the API is initialised.
103
+ * @throws {Error} If API initialisation fails.
104
+ * @example
105
+ * await initialiseGMapsNoContext({ key: 'YOUR_API_KEY', v: 'weekly' });
72
106
  */
73
107
  export function initialiseGMapsNoContext(options) {
74
108
  return new Promise((resolve, reject) => {
@@ -83,5 +117,10 @@ export function initialiseGMapsNoContext(options) {
83
117
  }
84
118
  });
85
119
  }
86
- // Re-export importLibrary for components to use.
120
+ /**
121
+ * Re-exported from @googlemaps/js-api-loader for convenient access.
122
+ * Dynamically imports a specific Google Maps library (e.g., 'places', 'maps', 'marker').
123
+ * @public
124
+ * @see https://developers.google.com/maps/documentation/javascript/importing-libraries
125
+ */
87
126
  export { importLibrary };
package/dist/helpers.js CHANGED
@@ -290,30 +290,33 @@ export const validateFetchFields = (fetchFields) => {
290
290
  * Default component classes
291
291
  */
292
292
  export const componentClasses = {
293
- section: '',
294
- container: 'relative z-10 transform rounded-xl mt-4',
295
- icon_container: 'pointer-events-none absolute inset-y-0 left-0 flex items-center pl-3',
296
- icon: '<svg xmlns="http://www.w3.org/2000/svg" class="w-5 h-5" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" /></svg>',
297
- input: 'border-1 w-full rounded-md border-0 shadow-sm bg-gray-100 px-4 py-2.5 pl-10 pr-20 text-gray-900 ring-1 ring-inset ring-gray-300 focus:ring-2 sm:text-sm',
298
- kbd_container: 'absolute inset-y-0 right-0 flex py-1.5 pr-1.5',
299
- kbd_escape: 'inline-flex items-center rounded border border-gray-300 px-1 font-sans text-xs text-gray-500 w-8 mr-1',
300
- kbd_up: 'inline-flex items-center justify-center rounded border border-gray-300 px-1 font-sans text-xs text-gray-500 w-6',
301
- kbd_down: 'inline-flex items-center rounded border border-gray-400 px-1 font-sans text-xs text-gray-500 justify-center w-6',
302
- kbd_active: 'bg-indigo-500 text-white',
303
- ul: 'absolute z-50 -mb-2 mt-1 max-h-60 w-full overflow-auto rounded-md bg-white py-1 text-base shadow-lg ring-1 ring-black ring-opacity-5 focus:outline-none sm:text-sm divide-y divide-gray-100',
304
- li: 'z-50 cursor-default select-none py-2 px-2 lg:px-4 text-gray-900 hover:bg-indigo-500 hover:text-white',
305
- li_current: 'bg-indigo-500 text-white',
306
- li_a: 'block w-full flex justify-between',
307
- li_a_current: 'text-white',
308
- li_div_container: 'flex min-w-0 gap-x-4',
309
- li_div_one: 'min-w-0 flex-auto flex gap-x-4 justify-center items-center',
310
- li_div_p_container: 'min-w-0 flex-auto',
311
- li_div_one_p: 'text-sm/6 text-left',
293
+ section: 'pac-section',
294
+ container: 'pac-container', //'relative z-10 transform rounded-xl mt-4',
295
+ icon_container: 'pac-icon-container', //'pointer-events-none absolute inset-y-0 left-0 flex items-center pl-3',
296
+ icon: '<svg xmlns="http://www.w3.org/2000/svg" style="width: 1.25rem; height: 1.25rem;" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" /></svg>',
297
+ input: 'pac-input',
298
+ //'border-1 w-full rounded-md border-0 shadow-sm bg-gray-100 px-4 py-2.5 pl-10 pr-20 text-gray-900 ring-1 ring-inset ring-gray-300 focus:ring-2 sm:text-sm',
299
+ kbd_container: 'pac-kbd-container', //'absolute inset-y-0 right-0 flex py-1.5 pr-1.5',
300
+ kbd_escape: 'pac-kbd-escape', //'inline-flex items-center rounded border border-gray-300 px-1 font-sans text-xs text-gray-500 w-8 mr-1',
301
+ kbd_up: 'pac-kbd-up',
302
+ //'inline-flex items-center justify-center rounded border border-gray-300 px-1 font-sans text-xs text-gray-500 w-6',
303
+ kbd_down: 'pac-kbd-down',
304
+ //'inline-flex items-center rounded border border-gray-400 px-1 font-sans text-xs text-gray-500 justify-center w-6',
305
+ kbd_active: 'pac-kbd-active', //'bg-indigo-500 text-white',
306
+ ul: 'pac-ul', //'absolute z-50 -mb-2 mt-1 max-h-60 w-full overflow-auto rounded-md bg-white py-1 text-base shadow-lg ring-1 ring-black ring-opacity-5 focus:outline-none sm:text-sm divide-y divide-gray-100',
307
+ li: 'pac-li', //'z-50 cursor-default select-none py-2 px-2 lg:px-4 text-gray-900 hover:bg-indigo-500 hover:text-white',
308
+ li_current: 'pac-li-current', //'bg-indigo-500 text-white',
309
+ li_button: 'pac-li-button', //'block w-full flex justify-between',
310
+ li_button_current: 'pac-li-button-current', //'text-white',
311
+ li_div_container: 'pac-li-div-container', //'flex min-w-0 gap-x-4',
312
+ li_div_one: 'pac-li-div-one', //'min-w-0 flex-auto flex gap-x-4 justify-center items-center',
313
+ li_div_p_container: 'pac-li-div-p-container', //'min-w-0 flex-auto',
314
+ li_div_one_p: 'pac-li-div-one-p', //'text-sm/6 text-left',
315
+ li_div_one_p_secondaryText: 'pac-li-div-one-p-secondaryText', //'text-xs text-left leading-2',
316
+ li_div_two: 'pac-li-div-two', //'shrink-0 flex flex-col items-end min-w-16',
317
+ li_div_two_p: 'pac-li-div-two-p', //'mt-1 text-xs/5',
318
+ highlight: 'pac-highlight', //'font-bold',
312
319
  map_pin_icon: '<path d="M20 10c0 4.993-5.539 10.193-7.399 11.799a1 1 0 0 1-1.202 0C9.539 20.193 4 14.993 4 10a8 8 0 0 1 16 0"/><circle cx="12" cy="10" r="3"/>',
313
- li_div_one_p_secondaryText: 'text-xs text-left leading-2',
314
- li_div_two: 'shrink-0 flex flex-col items-end min-w-16',
315
- li_div_two_p: 'mt-1 text-xs/5',
316
- highlight: 'font-bold',
317
320
  };
318
321
  /**
319
322
  * Default component options
@@ -1,73 +1,179 @@
1
1
  /**
2
+ * Configuration parameters for Google Places Autocomplete API requests.
2
3
  * @interface RequestParams
3
- * https://developers.google.com/maps/documentation/javascript/reference/autocomplete-data
4
+ * @see https://developers.google.com/maps/documentation/javascript/reference/autocomplete-data
4
5
  */
5
6
  export interface RequestParams {
7
+ /** The user's search input string. Automatically managed by the component. */
6
8
  input?: string;
9
+ /** Array of place types to include in results (e.g., ['restaurant', 'cafe']). */
7
10
  includedPrimaryTypes?: string[];
11
+ /** Array of region codes (CLDR format) to restrict results (e.g., ['US', 'CA']). */
8
12
  includedRegionCodes?: string[];
13
+ /** Zero-based character position in the input string where the service should start matching. */
9
14
  inputOffset?: number;
15
+ /** Language code for search results (e.g., 'en', 'fr', 'es'). */
10
16
  language?: string;
17
+ /**
18
+ * Location bias to prefer results near a specific location.
19
+ * Accepts LatLng, LatLngLiteral, LatLngBounds, LatLngBoundsLiteral, Circle, CircleLiteral, or string.
20
+ */
11
21
  locationBias?: {
12
22
  lat: number;
13
23
  lng: number;
14
24
  };
25
+ /**
26
+ * Location restriction to return only results within a specific area.
27
+ * Defines a rectangular boundary using geographic coordinates.
28
+ */
15
29
  locationRestriction?: {
16
30
  west: number;
17
31
  south: number;
18
32
  east: number;
19
33
  north: number;
20
34
  };
35
+ /**
36
+ * Origin point for calculating distance in results.
37
+ * Accepts LatLng or LatLngLiteral.
38
+ */
21
39
  origin?: {
22
40
  lat: number;
23
41
  lng: number;
24
42
  };
43
+ /** IANA region code (e.g., 'us', 'gb') to bias results. */
25
44
  region?: string;
45
+ /** Autocomplete session token for billing optimization. Automatically managed by the component. */
26
46
  sessionToken?: string;
27
47
  }
48
+ /**
49
+ * CSS class names for styling component elements.
50
+ * Map of component element identifiers to custom CSS class strings.
51
+ * @interface ComponentClasses
52
+ * @example
53
+ * {
54
+ * input: 'my-custom-input',
55
+ * ul: 'my-dropdown-list',
56
+ * li: 'my-list-item'
57
+ * }
58
+ */
28
59
  export interface ComponentClasses {
29
60
  [key: string]: string;
30
61
  }
62
+ /**
63
+ * HTML autocomplete attribute values.
64
+ * Controls browser autofill behavior for the input field.
65
+ * @type {"on" | "off"}
66
+ */
31
67
  export type AutoFill = "on" | "off";
68
+ /**
69
+ * Distance measurement units for displaying place distances.
70
+ * @type {"km" | "miles"}
71
+ */
32
72
  export type DistanceUnits = "km" | "miles";
73
+ /**
74
+ * Configuration options for customizing the PlaceAutocomplete component behavior and appearance.
75
+ * @interface ComponentOptions
76
+ */
33
77
  export interface ComponentOptions {
78
+ /** Automatically focus the input field when the component mounts. @default false */
34
79
  autofocus?: boolean;
80
+ /** Browser autocomplete/autofill behavior for the input field. @default "off" */
35
81
  autocomplete?: AutoFill;
82
+ /** Custom CSS classes for component elements (input, ul, li, etc.). */
36
83
  classes?: ComponentClasses;
84
+ /** Placeholder text displayed in the input field. @default "Search for a place..." */
37
85
  placeholder?: string;
86
+ /** Display distance from origin in autocomplete suggestions. @default false */
38
87
  distance?: boolean;
88
+ /** Unit of measurement for distance display. @default "km" */
39
89
  distance_units?: DistanceUnits;
90
+ /** Label text displayed above the input field. */
40
91
  label?: string;
92
+ /** Debounce delay in milliseconds for API requests. @default 100 */
41
93
  debounce?: number;
94
+ /** Clear the input field after selecting a place. @default true */
42
95
  clear_input?: boolean;
43
96
  }
97
+ /**
98
+ * Detailed information about a selected place returned by the Google Places API.
99
+ * Contains formatted address, address components, location coordinates, and additional place data
100
+ * depending on the requested fetch fields.
101
+ * @interface PlaceResult
102
+ * @see https://developers.google.com/maps/documentation/javascript/place-data-fields
103
+ */
44
104
  export interface PlaceResult {
105
+ /** Human-readable address of the place (e.g., "1600 Amphitheatre Parkway, Mountain View, CA"). */
45
106
  formattedAddress: string;
107
+ /**
108
+ * Array of address components (street, city, state, country, postal code, etc.).
109
+ * Each component includes long text, short text, and type identifiers.
110
+ */
46
111
  addressComponents: {
112
+ /** Full text representation of the address component (e.g., "California"). */
47
113
  longText: string;
114
+ /** Abbreviated representation of the address component (e.g., "CA"). */
48
115
  shortText: string;
116
+ /** Array of types describing the component (e.g., ["administrative_area_level_1", "political"]). */
49
117
  types: string[];
50
118
  }[];
119
+ /** Geographic coordinates (latitude and longitude) of the place. */
51
120
  location?: {
52
121
  lat: number;
53
122
  lng: number;
54
123
  };
124
+ /** Additional place data fields as requested via fetchFields prop (e.g., displayName, types, photos). */
55
125
  [key: string]: unknown;
56
126
  }
127
+ /**
128
+ * Standardized address format with commonly used components extracted from PlaceResult.
129
+ * Provides a consistent structure for address data across different regions.
130
+ * @interface FormattedAddress
131
+ */
57
132
  export interface FormattedAddress {
133
+ /** Street number (e.g., "1600"). */
58
134
  street_number: string;
135
+ /** Street name (e.g., "Amphitheatre Parkway"). */
59
136
  street: string;
137
+ /** City or locality name (e.g., "Mountain View"). */
60
138
  town: string;
139
+ /** County or administrative area (e.g., "Santa Clara County"). */
61
140
  county: string;
141
+ /** Two-letter ISO country code (e.g., "US", "GB", "FR"). */
62
142
  country_iso2: string;
143
+ /** Postal/ZIP code (e.g., "94043"). */
63
144
  postcode: string;
64
145
  }
146
+ /**
147
+ * Component props for the PlaceAutocomplete Svelte component.
148
+ * @interface Props
149
+ */
65
150
  export interface Props {
151
+ /**
152
+ * Google Maps API key for Places API authentication.
153
+ * Required if not using a parent GMapsProvider component.
154
+ * @see https://developers.google.com/maps/documentation/javascript/get-api-key
155
+ */
66
156
  PUBLIC_GOOGLE_MAPS_API_KEY?: string;
157
+ /** Configuration options for component behavior and styling. */
67
158
  options?: ComponentOptions;
159
+ /**
160
+ * Array of Place Data Fields to fetch when a place is selected.
161
+ * @default ['addressComponents', 'formattedAddress']
162
+ * @see https://developers.google.com/maps/documentation/javascript/place-data-fields
163
+ */
68
164
  fetchFields?: string[];
165
+ /** Google Maps libraries to load (managed internally, reserved for future use). */
69
166
  libraries?: string[];
167
+ /** Additional parameters for Places Autocomplete API requests. */
70
168
  requestParams?: RequestParams;
169
+ /**
170
+ * Callback function invoked when a place is successfully selected.
171
+ * Receives the complete PlaceResult object with requested fields.
172
+ */
71
173
  onResponse: (response: PlaceResult) => void;
174
+ /**
175
+ * Callback function invoked when an error occurs during API calls.
176
+ * Receives an error message string describing the issue.
177
+ */
72
178
  onError: (error: string) => void;
73
179
  }
package/package.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "name": "places-autocomplete-svelte",
3
3
  "license": "MIT",
4
- "version": "2.2.20",
5
- "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.",
4
+ "version": "2.2.21",
5
+ "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.",
6
6
  "keywords": [
7
7
  "svelte",
8
8
  "sveltekit",
@@ -17,7 +17,7 @@
17
17
  "input",
18
18
  "search"
19
19
  ],
20
- "homepage": "https://places-autocomplete-demo.pages.dev",
20
+ "homepage": "https://places-autocomplete-svelte.uk",
21
21
  "repository": {
22
22
  "type": "git",
23
23
  "url": "git+https://github.com/alexpechkarev/places-autocomplete-svelte.git"
@@ -77,31 +77,31 @@
77
77
  "devDependencies": {
78
78
  "@sveltejs/adapter-auto": "^7.0.0",
79
79
  "@sveltejs/adapter-cloudflare": "^7.2.4",
80
- "@sveltejs/kit": "^2.49.1",
80
+ "@sveltejs/kit": "^2.49.2",
81
81
  "@sveltejs/package": "^2.5.7",
82
82
  "@sveltejs/vite-plugin-svelte": "^6.2.1",
83
- "@tailwindcss/postcss": "^4.1.17",
83
+ "@tailwindcss/postcss": "^4.1.18",
84
84
  "@tailwindcss/typography": "^0.5.19",
85
- "@tailwindcss/vite": "^4.1.17",
85
+ "@tailwindcss/vite": "^4.1.18",
86
86
  "@types/eslint": "^9.6.1",
87
87
  "@types/google.maps": "^3.58.1",
88
- "@types/node": "^24.10.1",
89
- "autoprefixer": "^10.4.22",
90
- "eslint": "^9.39.1",
88
+ "@types/node": "^25.0.3",
89
+ "autoprefixer": "^10.4.23",
90
+ "eslint": "^9.39.2",
91
91
  "eslint-config-prettier": "^10.1.8",
92
92
  "eslint-plugin-svelte": "^3.13.1",
93
- "globals": "^16.5.0",
93
+ "globals": "^17.0.0",
94
94
  "postcss": "^8.5.6",
95
95
  "prettier": "^3.7.4",
96
- "prettier-plugin-svelte": "^3.4.0",
97
- "publint": "^0.3.15",
98
- "svelte": "^5.45.6",
99
- "svelte-check": "^4.3.4",
100
- "tailwindcss": "^4.1.17",
96
+ "prettier-plugin-svelte": "^3.4.1",
97
+ "publint": "^0.3.16",
98
+ "svelte": "^5.46.1",
99
+ "svelte-check": "^4.3.5",
100
+ "tailwindcss": "^4.1.18",
101
101
  "tslib": "^2.8.1",
102
102
  "typescript": "^5.9.3",
103
- "typescript-eslint": "^8.48.1",
104
- "vite": "^7.2.6"
103
+ "typescript-eslint": "^8.51.0",
104
+ "vite": "^7.3.0"
105
105
  },
106
106
  "svelte": "./dist/index.js",
107
107
  "types": "./dist/PlaceAutocomplete.svelte.d.ts",