@opensystemslab/map 0.5.5 → 0.5.8
Sign up to get free protection for your applications and to get access to all the features.
- package/README.md +28 -133
- package/dist/component-lib.es.js +26876 -12345
- package/dist/component-lib.umd.js +127 -12688
- package/dist/style.css +1 -1
- package/package.json +27 -8
- package/types/components/address-autocomplete/main.test.d.ts +6 -0
- package/types/components/my-map/index.d.ts +10 -0
- package/types/components/my-map/main.test.d.ts +6 -0
- package/types/components/my-map/os-features.d.ts +1 -1
- package/types/components/my-map/projections.d.ts +3 -0
- package/types/components/postcode-search/main.test.d.ts +6 -0
- package/types/test-utils.d.ts +2 -0
package/README.md
CHANGED
|
@@ -1,159 +1,54 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Place components
|
|
2
2
|
|
|
3
3
|
[](http://npm.im/@opensystemslab/map)
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
A library of [Web Components](https://developer.mozilla.org/en-US/docs/Web/Web_Components) for tasks related to addresses and planning permission in the UK built with [Lit](https://lit.dev/), [Vite](https://vitejs.dev/), and [Ordnance Survey APIs](https://developer.ordnancesurvey.co.uk/).
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
***Web map***
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
`<my-map />` is an [OpenLayers](https://openlayers.org/)-powered map to support drawing and modifying red-line boundaries. Other supported modes include: highlighting an OS Feature that intersects with a given address point; clicking to select and merge multiple OS Features into a single boundary; and displaying static point or polygon data. Events are dispatched with the calculated area and geojson representation when you change your drawing.
|
|
10
10
|
|
|
11
|
-
[
|
|
11
|
+
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
***Postcode search***
|
|
14
14
|
|
|
15
|
-
|
|
16
|
-
<my-map osVectorTilesApiKey="secret" />
|
|
17
|
-
```
|
|
15
|
+
`<postcode-search />` is a [GOV.UK-styled](https://frontend.design-system.service.gov.uk/) input that validates UK postcodes using these [utility methods](https://www.npmjs.com/package/postcode). When a postcode is validated, an event is dispatched containing the sanitized string.
|
|
18
16
|
|
|
19
|
-
|
|
17
|
+
***Address autocomplete***
|
|
20
18
|
|
|
21
|
-
|
|
22
|
-
```js
|
|
23
|
-
@property({ type: Boolean })
|
|
24
|
-
disableVectorTiles = false;
|
|
19
|
+
`<address-autocomplete />` fetches addresses in a given UK postcode using the [OS Places API](https://developer.ordnancesurvey.co.uk/os-places-api) and displays them using GOV.UK's [accessible-autocomplete](https://github.com/alphagov/accessible-autocomplete) component. An event is dispatched with the OS record when you select an address.
|
|
25
20
|
|
|
26
|
-
|
|
27
|
-
osVectorTilesApiKey = "";
|
|
28
|
-
```
|
|
21
|
+
These web components can be used independently or together following GOV.UK's [Address lookup](https://design-system.service.gov.uk/patterns/addresses/) design pattern.
|
|
29
22
|
|
|
30
|
-
|
|
23
|
+
|
|
31
24
|
|
|
32
|
-
|
|
25
|
+
## Documentation & examples
|
|
33
26
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
<my-map geojsonBuffer="10" hideResetControl staticMode />
|
|
37
|
-
<script>
|
|
38
|
-
const map = document.querySelector("my-map");
|
|
39
|
-
map.geojsonData = { ... }
|
|
40
|
-
</script>
|
|
41
|
-
</body>
|
|
42
|
-
```
|
|
27
|
+
- Interactive web component docs [oslmap.netlify.app](https://oslmap.netlify.app)
|
|
28
|
+
- [CodeSandbox](https://codesandbox.io/s/confident-benz-rr0s9?file=/index.html) (note: update the CDN script with a version number for new features)
|
|
43
29
|
|
|
44
|
-
|
|
45
|
-
```js
|
|
46
|
-
@property({ type: Object })
|
|
47
|
-
geojsonData = {
|
|
48
|
-
type: "FeatureCollection",
|
|
49
|
-
features: [],
|
|
50
|
-
};
|
|
30
|
+
Find these components in the wild, including what we're learning through public beta user-testing, at [https://www.ripa.digital/](https://www.ripa.digital/).
|
|
51
31
|
|
|
52
|
-
|
|
53
|
-
geojsonColor = "#ff0000";
|
|
32
|
+
## Running locally
|
|
54
33
|
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
hideResetControl = false;
|
|
60
|
-
|
|
61
|
-
@property({ type: Boolean })
|
|
62
|
-
staticMode = false;
|
|
63
|
-
```
|
|
64
|
-
|
|
65
|
-
`geojsonData` is required, and should be of type "FeatureCollection" or "Feature". The default is an empty geojson object so that we can initialize a VectorLayer & VectorSource regardless. This is currently optimized for geojson containing a single polygon feature.
|
|
66
|
-
|
|
67
|
-
`geojsonColor` & `geojsonBuffer` are optional style properties. Color sets the stroke of the displayed data and buffer is used to fit the map view to the extent of the geojson features. `geojsonBuffer` corresponds to "value" param in OL documentation [here](https://openlayers.org/en/latest/apidoc/module-ol_extent.html#.buffer).
|
|
68
|
-
|
|
69
|
-
`hideResetControl` hides the `↻` button, which when clicked would re-center your map if you've zoomed or panned away from the default view. `staticMode` additionally hides the `+/-` buttons, and disables mouse and keyboard zoom and pan/drag interactions.
|
|
70
|
-
|
|
71
|
-
#### Example: draw a custom polygon & calculate its area
|
|
72
|
-
|
|
73
|
-
```html
|
|
74
|
-
<body>
|
|
75
|
-
<my-map drawMode zoom="18" areaUnit="ha" />
|
|
76
|
-
<script>
|
|
77
|
-
const map = document.querySelector("my-map");
|
|
78
|
-
map.addEventListener("areaChange", ({ detail: area }) => {
|
|
79
|
-
console.debug({ area });
|
|
80
|
-
});
|
|
81
|
-
</script>
|
|
82
|
-
</body>
|
|
83
|
-
```
|
|
84
|
-
|
|
85
|
-
Available properties & their default values:
|
|
86
|
-
```js
|
|
87
|
-
@property({ type: Boolean })
|
|
88
|
-
drawMode = false;
|
|
89
|
-
|
|
90
|
-
@property({ type: Number })
|
|
91
|
-
latitude = 51.507351;
|
|
92
|
-
|
|
93
|
-
@property({ type: Number })
|
|
94
|
-
longitude = -0.127758;
|
|
95
|
-
|
|
96
|
-
@property({ type: Number })
|
|
97
|
-
zoom = 10;
|
|
98
|
-
|
|
99
|
-
@property({ type: String })
|
|
100
|
-
areaUnit = "m2"
|
|
101
|
-
```
|
|
102
|
-
|
|
103
|
-
Set `drawMode` to true. `latitude`, `longitude`, and `zoom` are used to set the initial map view. Drawing style is red by default, consistent with site plan standards in the UK.
|
|
104
|
-
|
|
105
|
-
We currently limit drawing to a single polygon. After you close your polygon, you can modify it by clicking on an edge and dragging. The `↻` button will clear your drawing and recenter the map. Add an optional event listener to calculate the total area of the drawing. `areaUnit` defaults to "m2" for square metres, but can also be configured to "ha" for hectares.
|
|
106
|
-
|
|
107
|
-
#### Example: highlight features that intersect with a given coordinate
|
|
108
|
-
|
|
109
|
-
```html
|
|
110
|
-
<my-map showFeaturesAtPoint osFeaturesApiKey="secret" latitude="51.4858363" longitude="-0.0761246" featureColor="#8a2be2" />
|
|
111
|
-
```
|
|
112
|
-
|
|
113
|
-
Requires access to the Ordnance Survey Features API. Sign up for a key here https://osdatahub.os.uk/plans.
|
|
114
|
-
|
|
115
|
-
Available properties & their default values:
|
|
116
|
-
```js
|
|
117
|
-
@property({ type: Boolean })
|
|
118
|
-
showFeaturesAtPoint = false;
|
|
119
|
-
|
|
120
|
-
@property({ type: String })
|
|
121
|
-
osFeaturesApiKey = "";
|
|
122
|
-
|
|
123
|
-
@property({ type: Number })
|
|
124
|
-
latitude = 51.507351;
|
|
125
|
-
|
|
126
|
-
@property({ type: Number })
|
|
127
|
-
longitude = -0.127758;
|
|
128
|
-
|
|
129
|
-
@property({ type: String })
|
|
130
|
-
featureColor = "#0000ff";
|
|
131
|
-
|
|
132
|
-
@property({ type: Number })
|
|
133
|
-
featureBuffer = 40;
|
|
134
|
-
```
|
|
135
|
-
|
|
136
|
-
Set `showFeaturesAtPoint` to true. `osFeaturesApiKey`, `latitude`, and `longitude` are each required to query the OS Features API for features that contain this point.
|
|
137
|
-
|
|
138
|
-
`featureColor` & `featureBuffer` are optional style properties. Color sets the stroke of the displayed data and buffer is used to fit the map view to the extent of the features. `featureBuffer` corresponds to "value" param in OL documentation [here](https://openlayers.org/en/latest/apidoc/module-ol_extent.html#.buffer).
|
|
34
|
+
- Rename `.env.example` to `.env.local` and replace the values - or simply provide your API keys as props
|
|
35
|
+
- Install [pnpm](https://pnpm.io) globally if you don't have it already `npm i pnpm -g`
|
|
36
|
+
- Install dependencies `pnpm i`
|
|
37
|
+
- Start development server `pnpm dev`
|
|
139
38
|
|
|
140
|
-
|
|
39
|
+
### Tests
|
|
141
40
|
|
|
142
|
-
|
|
41
|
+
Unit tests are written with [Vitest](https://vitest.dev/), [Happy Dom](https://www.npmjs.com/package/happy-dom), and [@testing-library/user-event](https://testing-library.com/docs/user-event/intro/). Each component has a `main.test.ts` file.
|
|
143
42
|
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
```
|
|
43
|
+
- `pnpm test` starts `vitest` in watch mode
|
|
44
|
+
- `pnpm test:ui` opens Vitest's UI in the browser to interactively explore logs https://vitest.dev/guide/ui.html
|
|
147
45
|
|
|
148
|
-
|
|
46
|
+
### Docs
|
|
149
47
|
|
|
150
|
-
|
|
48
|
+
We use [Pitsby](https://pitsby.com/) for documenting our web components. It's simple to configure (`pitsby.config.js` plus a `*.doc.js` per component), has good support for vanilla web components, and an interactive playground.
|
|
151
49
|
|
|
152
|
-
-
|
|
153
|
-
-
|
|
154
|
-
- Install dependencies `pnpm i`
|
|
155
|
-
- Start dev server `pnpm dev`
|
|
156
|
-
- Open http://localhost:3000
|
|
50
|
+
- `pnpm run docs` starts Pitsby in watch mode for local development
|
|
51
|
+
- `pnpm run docsPublish` builds the site so Netlify can serve it from `pitsby/`
|
|
157
52
|
|
|
158
53
|
## License
|
|
159
54
|
|