@road-labs/map-sdk 0.0.18 → 0.0.19-rc.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 +57 -14
- package/dist/index.js +15 -15
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +1288 -1234
- package/dist/index.mjs.map +1 -1
- package/dist/types.d.ts +2 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -28,33 +28,43 @@ The `App` component accepts the following props:
|
|
|
28
28
|
|
|
29
29
|
| Field Name | Required | Version(s) | Context | Description | Default Value |
|
|
30
30
|
| :-------------------------- | :------- | :--------- | :------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------- |
|
|
31
|
+
| `height` | Yes | Both | Both | Height of the map container in pixels. | `-` |
|
|
32
|
+
| `gestureHandling` | Yes | Both | Both | Google Maps SDK parameter controlling how gestures (scroll, pinch, etc.) interact with the map. Allowed values: `greedy`, `cooperative`, `none`, `auto`. We suggest a default value of `greedy`. | `-` |
|
|
33
|
+
| `authorization` | Yes | v2 | Both | The public authorization key to search for locations. | `-` |
|
|
34
|
+
| `context` | Yes | Both | Both | Context type for the map. Allowed values: `"cpo"` or `"msp"`. | `-` |
|
|
31
35
|
| `version` | No | Both | Both | Which version of the map SDK do you wish to use. | `v1` |
|
|
32
|
-
| `
|
|
33
|
-
| `
|
|
34
|
-
| `
|
|
36
|
+
| `language` | No | Both | Both | Language of the widget. Supported values: `en`. If nothing is set, it will use the browser language. | Browser language |
|
|
37
|
+
| `position {lat,lng}` | No | Both | Both | Initial latitude/longitude to center the map on load. If not provided, defaults to visitor's IP-based location. | Visitor IP location |
|
|
38
|
+
| `useBrowserLocation` | No | Both | Both | Use the browser location to center the map. | `false` |
|
|
35
39
|
| `enableZoomControls` | No | Both | Both | Whether to display zoom (+/-) controls in the bottom-right corner. | `false` |
|
|
36
40
|
| `enableSidebar` | No | Both | Both | Enables sidebar with location/cluster information when selected. | `false` |
|
|
37
41
|
| `enablePlacesSearch` | No | Both | Both | Enables address search input at the top of the map. | `true` |
|
|
38
|
-
| `provider` | Yes | Both | Both | Provider reference within the Road platform. | `-` |
|
|
39
42
|
| `locationId` | No | Both | Both | If provided, the map will zoom to the given `locationId` and open its sidebar (if enabled). Overrides `position`. | `-` |
|
|
40
|
-
| `
|
|
41
|
-
| `
|
|
42
|
-
| `
|
|
43
|
-
| `
|
|
44
|
-
| `
|
|
45
|
-
| `
|
|
46
|
-
| `
|
|
47
|
-
|
|
48
|
-
|
|
43
|
+
| `locationBaseUrl` | No | Both | Both | Base URL for location data. | `-` |
|
|
44
|
+
| `apiRoot` | No | Both | Both | The root URL of the API. | `-` |
|
|
45
|
+
| `googleApiKey` | No | Both | Both | Google Maps API key. If not provided, you can set your own Google API key. | `-` |
|
|
46
|
+
| `theming {}` | No | Both | Both | Controls widget look and feel with keys: `brandColor`, `backgroundColor`, `textColor`, `borderColor`, `fontFamily`. Accepts HEX values (e.g. `#ff3d00`). If `backgroundColor` is provided without `shadowRoot`, a shadow root will be automatically created. | `-` |
|
|
47
|
+
| `shadowRoot` | No | Both | Both | Shadow DOM root element. If not provided but `theming.backgroundColor` is set, a shadow root will be automatically created. See [Theming with Shadow DOM](#theming-with-shadow-dom) section below. | `-` |
|
|
48
|
+
| `sdkRoot` | No | Both | Both | Root URL for SDK CSS file. Required when using automatic shadow root creation with theming (when `theming` is provided without `shadowRoot`). The stylesheet will be loaded from `sdkRoot + "/styles.css"`. | `-` |
|
|
49
|
+
| `limitToLocationIds` | No | v2 | Both | Constrains the map to only show the locations with the configured IDs. Provided that they exist in the dataset. | All available locations |
|
|
50
|
+
| `preferredOperators` | No | v2 | Both | Array of operator names. Ensures that the selected operators appear at the top of the operator selector dropdown. | `[]` |
|
|
51
|
+
| `operators` | No | v2 | Both | Array of available operators. | `-` |
|
|
52
|
+
| `publishingMode` | No | v2 | Both | Array of available publishing modes. Allowed values: `"PUBLISHING_MODE_PUBLIC"`, `"PUBLISHING_MODE_PRIVATE"`. | `-` |
|
|
53
|
+
| `showNoAdditionalFeeFilter` | No | v2 | msp | Used to configure whether we enable the user to filter out stations that come with additional fees. | `false` |
|
|
54
|
+
| `showPublishingModeFilter` | No | v2 | cpo | Used to configure whether we enable the user to filter out public or private stations. | `false` |
|
|
55
|
+
| `showOperatorOnly` | No | v2 | both | String value representing the operator name. Include a quick filter option to find a specific operator. | `-` |
|
|
56
|
+
| `onMarkerClicked` | No | Both | Both | Callback function that is called when a marker is clicked. Receives an object with `ids` property containing the location IDs. | `-` |
|
|
49
57
|
|
|
50
58
|
### Example
|
|
51
59
|
|
|
60
|
+
Here's a complete example showing the SDK with automatic shadow root creation and theming:
|
|
61
|
+
|
|
52
62
|
```typescript
|
|
53
63
|
import React from 'react';
|
|
54
64
|
import { App } from '@road-labs/map-sdk';
|
|
55
65
|
import '@road-labs/map-sdk/dist/index.css';
|
|
56
66
|
|
|
57
|
-
function
|
|
67
|
+
function MyMap() {
|
|
58
68
|
return (
|
|
59
69
|
<App
|
|
60
70
|
height={600}
|
|
@@ -64,6 +74,7 @@ function MyComponent() {
|
|
|
64
74
|
apiRoot="https://api.road.io"
|
|
65
75
|
googleApiKey="your-google-maps-api-key"
|
|
66
76
|
language="en"
|
|
77
|
+
sdkRoot="https://mapsdk.road.io"
|
|
67
78
|
preferredOperators={["operator1", "operator2"]}
|
|
68
79
|
onMarkerClicked={({ ids }) => {
|
|
69
80
|
console.log('Marker clicked:', ids);
|
|
@@ -72,3 +83,35 @@ function MyComponent() {
|
|
|
72
83
|
);
|
|
73
84
|
}
|
|
74
85
|
```
|
|
86
|
+
|
|
87
|
+
**Note**: The `height`, `gestureHandling`, `authorization`, and `context` props are required. All other props are optional.
|
|
88
|
+
|
|
89
|
+
### Theming with Shadow DOM
|
|
90
|
+
|
|
91
|
+
The theming options (`brandColor`, `backgroundColor`, `textColor`, `borderColor`, `fontFamily`) require the SDK to be rendered within a Shadow DOM context. This provides style encapsulation, preventing the map's styles from conflicting with your application's styles and vice versa.
|
|
92
|
+
|
|
93
|
+
N.B. If you provide `theming` options without a `shadowRoot` prop, the SDK will automatically create a shadow root for you.
|
|
94
|
+
|
|
95
|
+
#### Important Notes
|
|
96
|
+
|
|
97
|
+
1. **CSS Import**:
|
|
98
|
+
- With automatic shadow root: The SDK loads the stylesheet from `sdkRoot + "/styles.css"`.
|
|
99
|
+
- With manual shadow root (or without theming options): You need to link the stylesheet directly in the shadow root (as shown above), or use a bundler that supports injecting styles into shadow DOM.
|
|
100
|
+
|
|
101
|
+
2. **Container Height**: Make sure your container element and the react root div have explicit heights set, otherwise the map may not display correctly.
|
|
102
|
+
|
|
103
|
+
#### Without Shadow DOM
|
|
104
|
+
|
|
105
|
+
If you don't need custom theming, you can use the SDK without Shadow DOM (simply omit both `theming` and `shadowRoot` props). The SDK will use its default theme values in this case.
|
|
106
|
+
|
|
107
|
+
```typescript
|
|
108
|
+
// Simple usage without shadow DOM (default theme only)
|
|
109
|
+
<App
|
|
110
|
+
height={600}
|
|
111
|
+
authorization="your-authorization-key"
|
|
112
|
+
context="cpo"
|
|
113
|
+
gestureHandling="greedy"
|
|
114
|
+
apiRoot="https://api.road.io"
|
|
115
|
+
// ... other props
|
|
116
|
+
/>
|
|
117
|
+
```
|