@aws/address-form-sdk-js 1.1.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.
- package/README.md +82 -85
- package/dist/lib/address-form-sdk.cjs.js +1 -1
- package/dist/lib/components/AddressFormReact/AddressForm.d.ts +9 -10
- package/dist/lib/components/AddressFormReact/AddressFormProvider.d.ts +2 -0
- package/dist/lib/components/AddressFormReact/index.d.ts +1 -1
- package/dist/lib/components/AddressFormReact/render.d.ts +4 -6
- package/dist/lib/components/Typeahead/index.d.ts +2 -0
- package/dist/lib/main.d.ts +1 -1
- package/dist/standalone/address-form-sdk.css +1 -1
- package/dist/standalone/address-form-sdk.umd.js +35 -35
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -30,19 +30,19 @@ 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
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
|
-
...
|
|
45
|
+
...
|
|
46
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
|
...
|
|
@@ -50,12 +50,12 @@ Include the following in your HTML code the CSS and JavaScript for the SDK
|
|
|
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.
|
|
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
|
|
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={(
|
|
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,29 +79,11 @@ export default function App() {
|
|
|
78
79
|
name="addressLineOne"
|
|
79
80
|
placeholder="Enter address"
|
|
80
81
|
/>
|
|
81
|
-
<input
|
|
82
|
-
|
|
83
|
-
|
|
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
88
|
<button data-type="address-form" type="submit">
|
|
106
89
|
Submit
|
|
@@ -110,12 +93,7 @@ export default function App() {
|
|
|
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" />
|
|
@@ -136,10 +114,7 @@ export default function App() {
|
|
|
136
114
|
/>
|
|
137
115
|
</head>
|
|
138
116
|
<body>
|
|
139
|
-
<form
|
|
140
|
-
id="amazon-location-address-form"
|
|
141
|
-
class="aws-address-form aws-flex-row aws-flex-1"
|
|
142
|
-
>
|
|
117
|
+
<form id="amazon-location-address-form" class="aws-address-form aws-flex-row aws-flex-1">
|
|
143
118
|
<div class="aws-flex-column">
|
|
144
119
|
<input
|
|
145
120
|
data-type="address-form"
|
|
@@ -166,7 +141,13 @@ export default function App() {
|
|
|
166
141
|
apiKey: "AMAZON_LOCATION_API_KEY",
|
|
167
142
|
region: "AMAZON_LOCATION_REGION",
|
|
168
143
|
showCurrentCountryResultsOnly: true,
|
|
169
|
-
onSubmit: (
|
|
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>
|
|
@@ -204,33 +185,47 @@ Other countries are in Preview, where the `addressLineOne` field displays the co
|
|
|
204
185
|
|
|
205
186
|
#### Props
|
|
206
187
|
|
|
207
|
-
| Property | Type | Required | Default | Description
|
|
208
|
-
| ------------------------------- | ------------------------------- | -------- | ------- |
|
|
209
|
-
| `apiKey` | `string` | Yes | - | The Amazon Location Service API key used to authenticate requests
|
|
210
|
-
| `region` | `string` | Yes | - | The AWS region where Amazon Location Service is called (e.g., "us-east-1")
|
|
211
|
-
| `
|
|
212
|
-
| `
|
|
213
|
-
| `
|
|
214
|
-
| `
|
|
215
|
-
| `
|
|
216
|
-
| `
|
|
217
|
-
| `
|
|
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 |
|
|
218
200
|
|
|
219
201
|
#### Form Submission Data
|
|
220
202
|
|
|
221
|
-
When the form is submitted, the `onSubmit` callback receives a
|
|
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).
|
|
222
214
|
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
|
226
|
-
|
|
|
227
|
-
| `
|
|
228
|
-
| `
|
|
229
|
-
| `
|
|
230
|
-
| `
|
|
231
|
-
| `
|
|
232
|
-
| `
|
|
233
|
-
| `
|
|
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) |
|
|
234
229
|
|
|
235
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.
|
|
236
231
|
|
|
@@ -250,12 +245,12 @@ All input fields use the `data-type="address-form"` attribute along with a `name
|
|
|
250
245
|
|
|
251
246
|
Primary address input with autofill functionality. See [Supported Countries](#supported-countries) for information about address field parsing behavior in different countries.
|
|
252
247
|
|
|
253
|
-
| Property | Type | Default | Description
|
|
254
|
-
| ---------------------------- | -------- | --------------- |
|
|
255
|
-
| `label` | `string` | "Address" | Label for the field
|
|
256
|
-
| `placeholder` | `string` | "Enter address" | Placeholder text
|
|
257
|
-
| `data-api-name` | `string` | "
|
|
258
|
-
| `data-show-current-location` | `string` | "true" |
|
|
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 |
|
|
259
254
|
|
|
260
255
|
#### Other Input Fields
|
|
261
256
|
|
|
@@ -299,16 +294,18 @@ Map component for displaying and adjusting address location.
|
|
|
299
294
|
|
|
300
295
|
#### Map Style Options
|
|
301
296
|
|
|
302
|
-
|
|
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"` |
|
|
303
307
|
|
|
304
|
-
|
|
305
|
-
| ------------------------- | -------------------- |
|
|
306
|
-
| `['Standard', 'Light']` | `"Standard,Light"` |
|
|
307
|
-
| `['Standard', 'Dark']` | `"Standard,Dark"` |
|
|
308
|
-
| `['Monochrome', 'Light']` | `"Monochrome,Light"` |
|
|
309
|
-
| `['Monochrome', 'Dark']` | `"Monochrome,Dark"` |
|
|
310
|
-
| `['Hybrid']` | `"Hybrid"` |
|
|
311
|
-
| `['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).
|
|
312
309
|
|
|
313
310
|
## Contributing
|
|
314
311
|
|