@aws/address-form-sdk-js 1.0.0 → 1.2.0

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.
Files changed (24) hide show
  1. package/README.md +128 -96
  2. package/dist/lib/address-form-sdk-js.css +1 -1
  3. package/dist/lib/address-form-sdk.cjs.js +1 -1
  4. package/dist/lib/components/AddressForm/index.d.ts +3 -1
  5. package/dist/lib/components/AddressFormReact/AddressForm.d.ts +20 -11
  6. package/dist/lib/components/AddressFormReact/AddressFormAddressField.d.ts +2 -2
  7. package/dist/lib/components/AddressFormReact/AddressFormAutofillHandler.d.ts +5 -0
  8. package/dist/lib/components/AddressFormReact/AddressFormContext.d.ts +7 -1
  9. package/dist/lib/components/AddressFormReact/AddressFormCountryField.d.ts +2 -2
  10. package/dist/lib/components/AddressFormReact/AddressFormFields.d.ts +2 -2
  11. package/dist/lib/components/AddressFormReact/AddressFormProvider.d.ts +4 -1
  12. package/dist/lib/components/AddressFormReact/AddressFormTextField.d.ts +2 -2
  13. package/dist/lib/components/AddressFormReact/index.d.ts +1 -1
  14. package/dist/lib/components/AddressFormReact/render.d.ts +4 -6
  15. package/dist/lib/components/AddressFormReact/utils.d.ts +1 -0
  16. package/dist/lib/components/MapMarker/AdjustButton/index.d.ts +3 -0
  17. package/dist/lib/components/MapMarker/index.d.ts +3 -1
  18. package/dist/lib/components/Typeahead/index.d.ts +3 -0
  19. package/dist/lib/data/countries.d.ts +1 -0
  20. package/dist/lib/main.d.ts +8 -9
  21. package/dist/lib/utils/detect-autofill.d.ts +24 -0
  22. package/dist/standalone/address-form-sdk.css +1 -1
  23. package/dist/standalone/address-form-sdk.umd.js +56 -56
  24. package/package.json +1 -1
package/README.md CHANGED
@@ -30,32 +30,32 @@ Install the SDK in your React app by running: `npm install @aws/address-form-sdk
30
30
 
31
31
  Include the following in your HTML code the CSS and JavaScript for the SDK
32
32
 
33
- ```
33
+ ```html
34
34
  ...
35
35
  <head>
36
- ...
36
+ ...
37
37
  <link
38
38
  rel="stylesheet"
39
- href="https://cdn.jsdelivr.net/npm/@aws/address-form-sdk-js/address-form-sdk.css"
39
+ href="https://cdn.jsdelivr.net/npm/@aws/address-form-sdk-js/dist/standalone/address-form-sdk.css"
40
40
  />
41
- ...
41
+ ...
42
42
  </head>
43
43
  ...
44
44
  <body>
45
- ...
46
- <script src="https://cdn.jsdelivr.net/npm/@aws/address-form-sdk-js"></script>
45
+ ...
46
+ <script src="https://cdn.jsdelivr.net/npm/@aws/address-form-sdk-js/dist/standalone/address-form-sdk.umd.js"></script>
47
47
  </body>
48
48
  ...
49
49
  ```
50
50
 
51
51
  ### Use SDK
52
52
 
53
- Implement the following code into your React app. Replace the `AMAZON_LOCATION_API_KEY` value with your API key and `AMAZON_LOCATION_REGION` with the region of the API key. The data returned when the form is submitted is returned from `onSubmit`
53
+ Implement the following code into your React app. Replace the `AMAZON_LOCATION_API_KEY` value with your API key and `AMAZON_LOCATION_REGION` with the region of the API key.
54
54
 
55
55
  #### React
56
56
 
57
- ```
58
- import React from 'react';
57
+ ```jsx
58
+ import React from "react";
59
59
  import { AddressForm, Flex } from "@aws/address-form-sdk-js";
60
60
 
61
61
  export default function App() {
@@ -63,14 +63,15 @@ export default function App() {
63
63
  <AddressForm
64
64
  apiKey="AMAZON_LOCATION_API_KEY"
65
65
  region="AMAZON_LOCATION_REGION"
66
- onSubmit={(data) => {
66
+ onSubmit={async (getData) => {
67
+ // Get form data with intendedUse parameter
68
+ // Use "SingleUse" for one-time display only
69
+ // Use "Storage" if you plan to store/cache the results - makes an extra API call to grant storage rights
70
+ const data = await getData({ intendedUse: "SingleUse" });
67
71
  console.log(data);
68
72
  }}
69
73
  >
70
- <Flex
71
- direction="row"
72
- flex
73
- >
74
+ <Flex direction="row" flex>
74
75
  <Flex direction="column">
75
76
  <input
76
77
  data-api-name="autocomplete"
@@ -78,44 +79,21 @@ export default function App() {
78
79
  name="addressLineOne"
79
80
  placeholder="Enter address"
80
81
  />
81
- <input
82
- data-type="address-form"
83
- name="addressLineTwo"
84
- />
85
- <input
86
- data-type="address-form"
87
- name="city"
88
- placeholder="City"
89
- />
90
- <input
91
- data-type="address-form"
92
- name="province"
93
- placeholder="State/Province"
94
- />
95
- <input
96
- data-type="address-form"
97
- name="postalCode"
98
- />
99
- <input
100
- data-type="address-form"
101
- name="country"
102
- placeholder="Country"
103
- />
82
+ <input data-type="address-form" name="addressLineTwo" />
83
+ <input data-type="address-form" name="city" placeholder="City" />
84
+ <input data-type="address-form" name="province" placeholder="State/Province" />
85
+ <input data-type="address-form" name="postalCode" />
86
+ <input data-type="address-form" name="country" placeholder="Country" />
104
87
  <Flex direction="row">
105
- <button address-form="submit">
88
+ <button data-type="address-form" type="submit">
106
89
  Submit
107
90
  </button>
108
- <button address-form="reset">
91
+ <button data-type="address-form" type="reset">
109
92
  Reset
110
93
  </button>
111
94
  </Flex>
112
95
  </Flex>
113
- <AddressFormMap
114
- mapStyle={[
115
- 'Standard',
116
- 'Light'
117
- ]}
118
- />
96
+ <AddressFormMap mapStyle={["Standard", "Light"]} />
119
97
  </Flex>
120
98
  </AddressForm>
121
99
  );
@@ -124,7 +102,7 @@ export default function App() {
124
102
 
125
103
  #### HTML/JavaScript
126
104
 
127
- ```
105
+ ```html
128
106
  <html lang="en">
129
107
  <head>
130
108
  <meta charset="UTF-8" />
@@ -132,41 +110,44 @@ export default function App() {
132
110
  <title>Address Form</title>
133
111
  <link
134
112
  rel="stylesheet"
135
- href="https://cdn.jsdelivr.net/npm/@aws/address-form-sdk-js/address-form-sdk.css"
113
+ href="https://cdn.jsdelivr.net/npm/@aws/address-form-sdk-js/dist/standalone/address-form-sdk.css"
136
114
  />
137
115
  </head>
138
116
  <body>
139
- <form id="amazon-location-address-form" data-type="address-form">
140
- <div data-type="address-form">
117
+ <form id="amazon-location-address-form" class="aws-address-form aws-flex-row aws-flex-1">
118
+ <div class="aws-flex-column">
141
119
  <input
142
120
  data-type="address-form"
143
121
  name="addressLineOne"
144
- placeholder="Enter address"
145
- data-api-name="autocomplete"
122
+ data-api-name="suggest"
123
+ data-show-current-location="true"
146
124
  />
147
125
  <input data-type="address-form" name="addressLineTwo" />
148
- <input data-type="address-form" name="city" placeholder="City" />
149
- <input
150
- data-type="address-form"
151
- name="province"
152
- placeholder="State/Province"
153
- />
126
+ <input data-type="address-form" name="city" />
127
+ <input data-type="address-form" name="province" />
154
128
  <input data-type="address-form" name="postalCode" />
155
- <input data-type="address-form" name="country" placeholder="Country" />
156
- <div data-type="address-form">
129
+ <input data-type="address-form" name="country" />
130
+ <div class="aws-flex-row">
157
131
  <button data-type="address-form" type="submit">Submit</button>
158
132
  <button data-type="address-form" type="reset">Reset</button>
159
133
  </div>
160
134
  </div>
161
- <div data-type="address-form-map" data-map-style="Standard,Light"></div>
135
+ <div data-type="address-form" data-map-style="Standard,Light"></div>
162
136
  </form>
163
- <script src="https://cdn.jsdelivr.net/npm/@aws/address-form-sdk-js"></script>
137
+ <script src="https://cdn.jsdelivr.net/npm/@aws/address-form-sdk-js/dist/standalone/address-form-sdk.umd.js"></script>
164
138
  <script>
165
- AddressForm.render({
139
+ AddressFormSDK.render({
166
140
  root: "#amazon-location-address-form",
167
- apiKey: AMAZON_LOCATION_API_KEY,
168
- region: AMAZON_LOCATION_REGION,
169
- onSubmit: (data) => console.log(data),
141
+ apiKey: "AMAZON_LOCATION_API_KEY",
142
+ region: "AMAZON_LOCATION_REGION",
143
+ showCurrentCountryResultsOnly: true,
144
+ onSubmit: async (getData) => {
145
+ // Get form data with intendedUse parameter
146
+ // Use "SingleUse" for one-time display only
147
+ // Use "Storage" if you plan to store/cache the results - makes an extra API call to grant storage rights
148
+ const data = await getData({ intendedUse: "SingleUse" });
149
+ console.log(data);
150
+ },
170
151
  });
171
152
  </script>
172
153
  </body>
@@ -177,6 +158,23 @@ export default function App() {
177
158
 
178
159
  The form is fully customizable - add, remove, or rearrange elements as needed for your use case. Replace the `Flex` component with your own CSS framework or custom styling. You can control other functionalities of the address form through the component props/attributes. See the [API Reference](#api-reference) for complete customization options.
179
160
 
161
+ ### Supported Countries
162
+
163
+ The Address Form SDK supports address autofill worldwide through Amazon Location Service. The following countries have full support with address field parsing, where each address component is populated into its respective field:
164
+
165
+ - Australia
166
+ - Canada
167
+ - France
168
+ - Hong Kong
169
+ - Ireland
170
+ - New Zealand
171
+ - Philippines
172
+ - Singapore
173
+ - United Kingdom
174
+ - United States
175
+
176
+ Other countries are in Preview, where the `addressLineOne` field displays the complete address instead of just the street address portion. Future releases will improve this behavior.
177
+
180
178
  ## API Reference
181
179
 
182
180
  ### AddressForm
@@ -187,17 +185,49 @@ The form is fully customizable - add, remove, or rearrange elements as needed fo
187
185
 
188
186
  #### Props
189
187
 
190
- | Property | Type | Required | Default | Description |
191
- | ------------------------------- | ------------------------------- | -------- | ------- | -------------------------------------------------------------------------- |
192
- | `apiKey` | `string` | Yes | - | The Amazon Location Service API key used to authenticate requests |
193
- | `region` | `string` | Yes | - | The AWS region where Amazon Location Service is called (e.g., "us-east-1") |
194
- | `preventDefaultOnSubmit` | `boolean` | No | `false` | Prevents the default form submission behavior when set to true |
195
- | `language` | `string` | No | - | Language code for localized address suggestions (e.g., "en", "es") |
196
- | `politicalView` | `string` | No | - | Political view for address results, affecting disputed territories display |
197
- | `showCurrentCountryResultsOnly` | `boolean` | No | `false` | Limits autocomplete results to the currently selected country only |
198
- | `allowedCountries` | `string[]` | No | - | Array of ISO country codes to restrict address suggestions |
199
- | `placeTypes` | `AutocompleteFilterPlaceType[]` | No | - | Array of place types to filter results (e.g., "Locality", "PostalCode") |
200
- | `onSubmit` | `(data) => void` | No | - | Callback function triggered on form submission |
188
+ | Property | Type | Required | Default | Description |
189
+ | ------------------------------- | ------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
190
+ | `apiKey` | `string` | Yes | - | The Amazon Location Service API key used to authenticate requests |
191
+ | `region` | `string` | Yes | - | The AWS region where Amazon Location Service is called (e.g., "us-east-1") |
192
+ | `language` | `string` | No | - | [Language code](https://en.wikipedia.org/wiki/IETF_language_tag#List_of_common_primary_language_subtags) for localized address suggestions (e.g., "en", "es") |
193
+ | `politicalView` | `string` | No | - | Political view for address results, affecting disputed territories display |
194
+ | `showCurrentCountryResultsOnly` | `boolean` | No | `false` | Limits autofill suggestions to the country selected in the `Country` field |
195
+ | `allowedCountries` | `string[]` | No | - | Array of ISO country codes (alpha-2 or alpha-3) to restrict address suggestions. See [countries.ts](lib/data/countries.ts) for alpha-2 reference |
196
+ | `placeTypes` | `AutocompleteFilterPlaceType[]` | No | - | Array of [place types](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_AutocompleteFilter.html#location-Type-geoplaces_AutocompleteFilter-IncludePlaceTypes) to filter results (e.g., "Locality", "PostalCode") |
197
+ | `initialMapCenter` | `[number, number]` | No | - | Initial map center as [longitude, latitude] coordinates. If not provided and a single country is specified in `allowedCountries`, the map centers on that country's capital |
198
+ | `initialMapZoom` | `number` | No | Varies | Initial map zoom level. Defaults: 10 when `initialMapCenter` is provided, 5 when centering on a single allowed country, 1 otherwise |
199
+ | `onSubmit` | `(getData) => void` | No | - | Callback function that receives a `getData` async function for retrieving [form data](https://github.com/aws-geospatial/address-form-sdk-js/blob/30fd74fcad353249ad54cc69c4bc5dd39fda7680/README.md?plain=1#L219) with intendedUse parameter |
200
+
201
+ #### Form Submission Data
202
+
203
+ When the form is submitted, the `onSubmit` callback receives a `getData` async function. Call this function with an `intendedUse` parameter to retrieve the form data:
204
+
205
+ ```javascript
206
+ onSubmit: async (getData) => {
207
+ const data = await getData({
208
+ intendedUse: "SingleUse", // or "Storage"
209
+ });
210
+ };
211
+ ```
212
+
213
+ **Important:** Use `"Storage"` if you plan to store or cache the results. This ensures compliance with Amazon Location Service [intended use requirements](https://docs.aws.amazon.com/location/latest/developerguide/places-intended-use.html).
214
+
215
+ The returned data object contains the following properties:
216
+
217
+ | Property | Type | Description |
218
+ | ------------------ | --------- | -------------------------------------------------------------------------------------------------------------- |
219
+ | `placeId` | `string` | Place ID from Amazon Location Service (only present when address was selected from typeahead or locate button) |
220
+ | `addressLineOne` | `string` | Primary address line (street address) |
221
+ | `addressLineTwo` | `string` | Secondary address line (apartment, suite, etc.) |
222
+ | `city` | `string` | City name |
223
+ | `province` | `string` | State or province |
224
+ | `postalCode` | `string` | Postal or ZIP code |
225
+ | `country` | `string` | Country code (ISO 3166-1 alpha-2) |
226
+ | `originalPosition` | `string` | Original coordinates from API response (longitude,latitude) |
227
+ | `adjustedPosition` | `string` | User-adjusted coordinates if map pin was moved (longitude,latitude) |
228
+ | `addressDetails` | `Address` | Complete address object from Amazon Location Service API (GetPlace/ReverseGeocode response) |
229
+
230
+ **Note:** The `addressDetails` property contains the full API response from Amazon Location Service and is only present when the address was populated through our APIs (typeahead selection or locate button). Addresses entered manually by users will not contain this property.
201
231
 
202
232
  ### Form Input Fields
203
233
 
@@ -213,14 +243,14 @@ All input fields use the `data-type="address-form"` attribute along with a `name
213
243
 
214
244
  #### Address Line One (`name="addressLineOne"`)
215
245
 
216
- Primary address input with autocomplete functionality.
246
+ Primary address input with autofill functionality. See [Supported Countries](#supported-countries) for information about address field parsing behavior in different countries.
217
247
 
218
- | Property | Type | Default | Description |
219
- | ---------------------------- | -------- | --------------- | ------------------------------------- |
220
- | `label` | `string` | "Address" | Label for the field |
221
- | `placeholder` | `string` | "Enter address" | Placeholder text |
222
- | `data-api-name` | `string` | "autocomplete" | API type: "autocomplete" or "suggest" |
223
- | `data-show-current-location` | `string` | "true" | Enable current location functionality |
248
+ | Property | Type | Default | Description |
249
+ | ---------------------------- | -------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
250
+ | `label` | `string` | "Address" | Label for the field |
251
+ | `placeholder` | `string` | "Enter address" | Placeholder text |
252
+ | `data-api-name` | `string` | "suggest" | API type: `autocomplete` or `suggest`. Use `suggest` to return both POI and address suggestions, and `autocomplete` to return address-only suggestions |
253
+ | `data-show-current-location` | `string` | "true" | Enables current location functionality using the browser’s Geolocation API. This will prompt the user for permission to access their location |
224
254
 
225
255
  #### Other Input Fields
226
256
 
@@ -235,22 +265,22 @@ Primary address input with autocomplete functionality.
235
265
  #### Submit Button
236
266
 
237
267
  ```html
238
- <button address-form="submit">Submit</button>
268
+ <button data-type="address-form" type="submit">Submit</button>
239
269
  ```
240
270
 
241
271
  #### Reset Button
242
272
 
243
273
  ```html
244
- <button address-form="reset">Reset</button>
274
+ <button data-type="address-form" type="reset">Reset</button>
245
275
  ```
246
276
 
247
277
  ### AddressFormMap
248
278
 
249
279
  Map component for displaying and adjusting address location.
250
280
 
251
- **React:** Map component for displaying and adjusting address location. `<AddressFormMap>`
281
+ **React:** Map component for displaying and adjusting address location. `<AddressFormMap mapStyle={...}>`
252
282
 
253
- **HTML/JavaScript:** Map element for displaying and adjusting address location.`<div data-type="address-form-map">`
283
+ **HTML/JavaScript:** Map element for displaying and adjusting address location.`<div data-type="address-form" data-map-style="...">`
254
284
 
255
285
  #### Props
256
286
 
@@ -264,16 +294,18 @@ Map component for displaying and adjusting address location.
264
294
 
265
295
  #### Map Style Options
266
296
 
267
- #### Map Style Options
297
+ Map styles consist of two parts: the **map style name** and the **color scheme**. The map style name determines the visual theme (Standard, Monochrome, Hybrid, or Satellite), while the color scheme specifies the brightness variant (Light or Dark) where applicable.
298
+
299
+ | React Implementation (Array Format) | HTML/JavaScript Implementation (String Format) |
300
+ | ----------------------------------- | ---------------------------------------------- |
301
+ | `['Standard', 'Light']` | `"Standard,Light"` |
302
+ | `['Standard', 'Dark']` | `"Standard,Dark"` |
303
+ | `['Monochrome', 'Light']` | `"Monochrome,Light"` |
304
+ | `['Monochrome', 'Dark']` | `"Monochrome,Dark"` |
305
+ | `['Hybrid']` | `"Hybrid"` |
306
+ | `['Satellite']` | `"Satellite"` |
268
307
 
269
- | React | HTML/JavaScript |
270
- | ------------------------- | -------------------- |
271
- | `['Standard', 'Light']` | `"Standard,Light"` |
272
- | `['Standard', 'Dark']` | `"Standard,Dark"` |
273
- | `['Monochrome', 'Light']` | `"Monochrome,Light"` |
274
- | `['Monochrome', 'Dark']` | `"Monochrome,Dark"` |
275
- | `['Hybrid']` | `"Hybrid"` |
276
- | `['Satellite']` | `"Satellite"` |
308
+ For detailed descriptions of each map style and color scheme, see [AWS map styles and customization](https://docs.aws.amazon.com/location/latest/developerguide/map-styles.html).
277
309
 
278
310
  ## Contributing
279
311