@opensystemslab/map 0.5.5 → 0.5.8
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 +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
|
|