Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: interactive docs using Pitsby #61

Merged
merged 16 commits into from
Aug 11, 2022
Merged

feat: interactive docs using Pitsby #61

Show file tree
Hide file tree
Changes from 12 commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
490083a
first go
jessicamcinchak Sep 26, 2021
0236935
add all properties
jessicamcinchak Sep 27, 2021
c7d0601
all examples
jessicamcinchak Sep 28, 2021
3169d1d
rebase, stub out new components
jessicamcinchak Mar 24, 2022
4c0e1aa
Merge branch 'main' of github.com:theopensystemslab/map into jess/doc…
jessicamcinchak Mar 24, 2022
6342bef
split up map docs by mode
jessicamcinchak Mar 24, 2022
7c4f072
Merge branch 'main' of github.com:theopensystemslab/map into jess/doc…
jessicamcinchak Mar 30, 2022
3529ebf
fix netlify build type error
jessicamcinchak Mar 30, 2022
20cc45b
sync lock file
jessicamcinchak Mar 30, 2022
2ee265d
rebase to main, fix conflicts
jessicamcinchak Aug 4, 2022
122c2e6
update config & docs
jessicamcinchak Aug 5, 2022
cabedf2
bump pitsby to latest version
jessicamcinchak Aug 5, 2022
e1daa9e
add pitsby build to gitignore
jessicamcinchak Aug 11, 2022
982d683
specify port which doesn't clash with planx dev env
jessicamcinchak Aug 11, 2022
3c329f1
remove pitsby/
jessicamcinchak Aug 11, 2022
5758eb1
cleanup tsconfig
jessicamcinchak Aug 11, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
147 changes: 9 additions & 138 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,144 +8,8 @@ An [OpenLayers](https://openlayers.org/)-powered [Web Component](https://develop

## Demo

[CodeSandbox](https://codesandbox.io/s/confident-benz-rr0s9?file=/index.html)

#### Example: render the Ordnance Survey vector tile basemap

```html
<my-map osVectorTilesApiKey="secret" />
```

Requires access to the Ordnance Survey Vector Tiles API. Sign up for a key here https://osdatahub.os.uk/plans.

Available properties & their default values:
```js
@property({ type: Boolean })
disableVectorTiles = false;

@property({ type: String })
osVectorTilesApiKey = "";
```

We want to use the most detailed base map possible, so `disableVectorTiles` is false by default. If you configure it to true & you provide an API key, we'll render the OS raster base map. If there is no API key, regardless of the value of `disableVectorTiles`, we'll fallback to the OpenStreetMap tile server.

#### Example: load geojson on a static map

```html
<body>
<my-map geojsonBuffer="10" hideResetControl staticMode />
<script>
const map = document.querySelector("my-map");
map.geojsonData = { ... }
</script>
</body>
```

Available properties & their default values:
```js
@property({ type: Object })
geojsonData = {
type: "FeatureCollection",
features: [],
};

@property({ type: String })
geojsonColor = "#ff0000";

@property({ type: Number })
geojsonBuffer = 15;

@property({ type: Boolean })
hideResetControl = false;

@property({ type: Boolean })
staticMode = false;
```

`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.

`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).

`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.

#### Example: draw a custom polygon & calculate its area

```html
<body>
<my-map drawMode zoom="18" areaUnit="ha" />
<script>
const map = document.querySelector("my-map");
map.addEventListener("areaChange", ({ detail: area }) => {
console.debug({ area });
});
</script>
</body>
```

Available properties & their default values:
```js
@property({ type: Boolean })
drawMode = false;

@property({ type: Number })
latitude = 51.507351;

@property({ type: Number })
longitude = -0.127758;

@property({ type: Number })
zoom = 10;

@property({ type: String })
areaUnit = "m2"
```

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.

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.

#### Example: highlight features that intersect with a given coordinate

```html
<my-map showFeaturesAtPoint osFeaturesApiKey="secret" latitude="51.4858363" longitude="-0.0761246" featureColor="#8a2be2" />
```

Requires access to the Ordnance Survey Features API. Sign up for a key here https://osdatahub.os.uk/plans.

Available properties & their default values:
```js
@property({ type: Boolean })
showFeaturesAtPoint = false;

@property({ type: String })
osFeaturesApiKey = "";

@property({ type: Number })
latitude = 51.507351;

@property({ type: Number })
longitude = -0.127758;

@property({ type: String })
featureColor = "#0000ff";

@property({ type: Number })
featureBuffer = 40;
```

Set `showFeaturesAtPoint` to true. `osFeaturesApiKey`, `latitude`, and `longitude` are each required to query the OS Features API for features that contain this point.

`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).

#### Example: click to expand or deselect the highlighted feature

Extends prior example by making the map interactive and listening for single click events. Currently only possible when `showFeaturesAtPoint` is also enabled.

```html
<my-map showFeaturesAtPoint clickFeatures ... />
```

Set `clickFeatures` to true, this will begin listening for single click events. New features will be highlighted or de-selected as you click. If the selected features share borders, the highlight border will appear as a merged single feature.
- Interactive docs [oslmap.netlify.app](https://oslmap.netlify.app)
- [CodeSandbox](https://codesandbox.io/s/confident-benz-rr0s9?file=/index.html) (note: update the CDN script with a version number for new features)

## Running Locally

Expand All @@ -155,6 +19,13 @@ Set `clickFeatures` to true, this will begin listening for single click events.
- Start dev server `pnpm dev`
- Open http://localhost:3000

### Docs

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.

- `pnpm run docs` starts Pitsby in watch mode for local development
- `pnpm run docsPublish` builds the site so Netlify can serve it from `./pitsby`

## License

This repository is licensed under the [Open Government License v3](http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/).
5 changes: 4 additions & 1 deletion package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,9 @@
"dev": "vite",
"build": "rm -rf dist types && tsc && vite build && sed 's/src=\".*\"/src=\"component-lib.es.js\"/' index.html > dist/index.html",
"prepublishOnly": "npm run build",
"prepare": "husky install"
"prepare": "husky install",
"docs": "NODE_ENV=development pitsby build --watch",
jessicamcinchak marked this conversation as resolved.
Show resolved Hide resolved
"docsPublish": "pitsby build"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍

},
"dependencies": {
"@turf/union": "^6.5.0",
Expand All @@ -32,6 +34,7 @@
"rambda": "^7.0.1"
},
"devDependencies": {
"@glorious/pitsby": "^1.30.16",
"@types/node": "^18.0.1",
"husky": "^8.0.1",
"lint-staged": "^13.0.3",
Expand Down
14 changes: 14 additions & 0 deletions pitsby.config.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
// https://pitsby.com/documentation#config
module.exports = {
projects: [
{
engine: "vanilla",
collectDocsFrom: "./src/components/",
},
],
styles: ["./dist/style.css"],
scripts: ["./dist/component-lib.es.js", "./dist/component-lib.umd.js"],
custom: {
windowTitle: 'Docs - Place Components',
},
};
1 change: 1 addition & 0 deletions pitsby/data/components-vanilla.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
[{"name":"AddressAutocomplete","description":"AddressAutocomplete is a Lit wrapper for the Gov.UK accessible-autocomplete component that fetches & displays addresses in a given postcode using the Ordnance Survey Places API.","properties":[{"name":"postcode","type":"String","values":"SE5 0HU (default), any UK postcode","required":true},{"name":"initialAddress","type":"String","values":"\"\" (default)"},{"name":"label","type":"String","values":"Select an address (default)"},{"name":"arrowStyle","type":"String","values":"default (default), light"},{"name":"labelStyle","type":"String","values":"responsive (default), static"},{"name":"id","type":"String","values":"autocomplete (default)"},{"name":"osPlacesApiKey","type":"String","values":"https://osdatahub.os.uk/plans","required":true}],"methods":[{"name":"ready","params":[{"name":"ready","type":"Event Listener","values":"detail","description":"Dispatches the number of addresses fetched from the OS Places API for a given `postcode` when the component is connected to the DOM, before initial render"}]},{"name":"addressSelection","params":[{"name":"addressSelection","type":"Event Listener","values":"detail","description":"Dispatches the OS Places API record for an individual address when it's selected from the dropdown"}]}],"examples":[{"title":"Select an address in postcode SE19 1NT","description":"Standard case","template":"<address-autocomplete postcode=\"SE19 1NT\" osPlacesApiKey=undefined />","controller":"function (document) {\n const autocomplete = document.querySelector(\"address-autocomplete\");\n\n autocomplete.addEventListener(\"ready\", ({ detail: data }) => {\n console.debug(\"autocomplete ready\", { data });\n });\n \n autocomplete.addEventListener(\"addressSelection\", ({ detail: address }) => {\n console.debug({ detail: address });\n });\n }"}],"id":"addressautocomplete"},{"name":"MyMap - Basic","description":"MyMap is an OpenLayers-powered Lit web component map for tasks related to planning permission in the UK. These examples cover the foundational properties used to render and style the map.","properties":[{"name":"latitude","type":"Number (EPSG:4326)","values":"51.507351 (default)","required":true},{"name":"longitude","type":"Number (EPSG:4326)","values":"-0.127758 (default)","required":true},{"name":"zoom","type":"Number","values":"10 (default)","required":true},{"name":"minZoom","type":"Number","values":"7 (default)"},{"name":"maxZoom","type":"Number","values":"22 (default)"},{"name":"hideResetControl","type":"Boolean","values":"false (default)"},{"name":"staticMode","type":"Boolean","values":"false (default)"},{"name":"showScale","type":"Boolean","values":"false (default)"},{"name":"useScaleBarStyle","type":"Boolean","values":"false (default)"},{"name":"id","type":"String","values":"map (default)"},{"name":"ariaLabel","type":"String","values":"An interactive map (default)"},{"name":"disableVectorTiles","type":"Boolean","values":"false (default)"},{"name":"osCopyright","type":"String","values":"© Crown copyright and database rights 2022 OS (0)100024857 (default)"},{"name":"osVectorTileApiKey","type":"String","values":"https://osdatahub.os.uk/plans"}],"examples":[{"title":"Basemap: Ordnance Survey vector tiles","description":"Requires access to the Ordnance Survey Vector Tiles API, fallsback to OpenStreetMap basemap if no key is provided.","template":"<my-map zoom=\"18\" osVectorTilesApiKey=\"\" />"},{"title":"Basemap: Ordnance Survey raster tiles","description":"Requires access to the Ordnance Survey Maps API, fallsback to OpenStreetMap basemap if no key provided.","template":"<my-map zoom=\"18\" osVectorTilesApiKey=\"\" disableVectorTiles />"},{"title":"Display a static map","description":"Disable zooming, panning, and other map interactions. Hide the reset control button.","template":"\n <my-map\n zoom=\"20\"\n staticMode\n hideResetControl\n osVectorTilesApiKey=\"\" />"},{"title":"Display a scale bar on the map","description":"Display a scale bar on the map for orientation, choose between the default or \"bar\" styles offered by OpenLayers","template":"\n <my-map\n zoom=\"20\"\n showScale\n useScaleBarStyle\n osVectorTilesApiKey=\"\" />"}],"id":"mymap---basic"},{"name":"MyMap - Drawing","description":"Drawing mode enables drawing and modifying a shape on the map. Snapping points display for guidance at zoom level 20+ when the vector tile basemap is enabled. One polygon can be drawn at a time. The reset control button will erase your drawing and re-center the map view.","properties":[{"name":"drawMode","type":"Boolean","values":"false (default)"},{"name":"drawPointer","type":"String","values":"crosshair (default), dot"},{"name":"drawGeojsonData","type":"GeoJSON Feature","values":"\n {\n type: \"Feature\",\n geometry: {},\n } \n (default)"},{"name":"drawGeojsonBuffer","type":"Number","values":"100 (default)"},{"name":"areaUnits","type":"String","values":"m2 (default), ha"},{"name":"osVectorTileApiKey","type":"String","values":"https://osdatahub.os.uk/plans"}],"examples":[{"title":"Draw mode","description":"Draw and modify a site plan boundary with a red line. Start at zoom 20 so snaps are visible on initial load.","template":"\n <my-map \n id=\"draw-mode\"\n zoom=\"20\" \n maxZoom=\"23\" \n drawMode \n drawPointer=\"dot\"\n osVectorTilesApiKey=\"\" />"},{"title":"Load an initial shape onto the drawing canvas","description":"Load a polygon with the ability to continue modifying it. Click 'reset' to erase and draw fresh.","controller":"function (element) {\n const map = element.querySelector(\"my-map\");\n map.drawGeojsonData = {\n type: \"Feature\",\n properties: {},\n geometry: {\n type: \"Polygon\",\n coordinates: [\n [\n [-0.07666435775970835, 51.48432362355473],\n [-0.07670012065571297, 51.48419742371502],\n [-0.07630374962243747, 51.484158450222964],\n [-0.07627692753228853, 51.484288361835524],\n [-0.07666435775970835, 51.48432362355473],\n ],\n ],\n },\n };\n }","template":"\n <my-map \n id=\"draw-mode-1\"\n zoom=\"20\" \n maxZoom=\"23\" \n drawMode \n drawPointer=\"dot\"\n osVectorTilesApiKey=\"\" />"},{"title":"Calculate the area of the drawn polygon","description":"Listen for an event when the drawn polygon is closed or modified. Specify if you want to calculate area in square metres or hectares.","controller":"function (element) {\n const map = element.querySelector(\"my-map\");\n map.addEventListener(\"areaChange\", ({ detail: area }) => {\n console.debug({ area });\n });\n }","template":"\n <my-map \n id=\"draw-mode-2\"\n zoom=\"19\" \n maxZoom=\"23\" \n drawMode \n areaUnits=\"ha\" \n osVectorTilesApiKey=\"\" />"},{"title":"Get the GeoJSON representation of the drawn polygon","description":"Listen for an event when the drawn polygon is closed or modified.","controller":"function (element) {\n const map = element.querySelector(\"my-map\");\n map.addEventListener(\"geojsonChange\", ({ detail: geojson }) => {\n console.debug({ geojson });\n });\n }","template":"\n <my-map \n id=\"draw-mode-3\"\n zoom=\"19\" \n maxZoom=\"23\" \n drawMode \n osVectorTilesApiKey=\"\" />"}],"id":"mymap---drawing"},{"name":"MyMap - Features","description":"Features mode queries the Ordnance Survey Features API for any features that intersect the center point of the map. Should be used with the vector tiles basemap.","properties":[{"name":"showFeaturesAtPoint","type":"Boolean","values":"false (default)"},{"name":"clickFeatures","type":"Boolean","values":"false (default)"},{"name":"featureColor","type":"String","values":""},{"name":"featureFill","type":"Boolean","values":"false (default)"},{"name":"featureBuffer","type":"Number","values":"40"},{"name":"osFeaturesApiKey","type":"String","values":"https://osdatahub.os.uk/plans"},{"name":"osVectorTileApiKey","type":"String","values":"https://osdatahub.os.uk/plans"}],"examples":[{"title":"Show features at point","description":"Show the Ordnance Survey Feature(s) that intersects with a given point.","template":"\n <my-map\n showFeaturesAtPoint\n latitude=\"51.4858363\"\n longitude=\"-0.0761246\"\n featureColor=\"#8a2be2\" \n osFeaturesApiKey=\"\" \n osVectorTilesApiKey=\"\" />"},{"title":"Click to select and merge features","description":"Show features at point plus ability to click to select or deselect additional features to create a more accurate full site boundary.","template":"\n <my-map\n showFeaturesAtPoint\n clickFeatures\n latitude=\"51.4854329\"\n longitude=\"-0.0761992\"\n featureColor=\"Magenta\" \n osFeaturesApiKey=\"\" \n osVectorTilesApiKey=\"\" />"}],"id":"mymap---features"},{"name":"MyMap - GeoJSON","description":"GeoJSON mode displays a static polygon on the map. The map view will center on the shape, overriding the latitude, longitude, and zoom properties. Use the geojsonBuffer property to control the padding between the shape and edge of the map view.","properties":[{"name":"geojsonData","type":"GeoJSON FeatureCollection or Feature","values":"\n {\n type: \"FeatureCollection\",\n features: [],\n }\n (default)\n "},{"name":"geojsonColor","type":"String","values":"#ff0000 (default)"},{"name":"geojsonFill","type":"Boolean","values":"false (default)"},{"name":"geojsonBuffer","type":"Number","values":"12"}],"examples":[{"title":"Show a GeoJSON polygon on a static map","description":"Show a custom GeoJSON polygon on an OS basemap. Hide the zoom & reset control buttons.","controller":"function (element) {\n const map = element.querySelector(\"my-map\");\n map.geojsonData = {\n type: \"Feature\",\n properties: {},\n geometry: {\n type: \"Polygon\",\n coordinates: [\n [\n [-0.11562466621398924, 51.50746034612789],\n [-0.11449813842773436, 51.50617151942102],\n [-0.11359691619873047, 51.50653212745768],\n [-0.11348962783813477, 51.50645199258505],\n [-0.1127493381500244, 51.50665900738443],\n [-0.11383295059204103, 51.507907754128546],\n [-0.11562466621398924, 51.50746034612789],\n ],\n ],\n },\n };\n }","template":"\n <my-map\n geojsonColor=\"#ff0000\"\n geojsonBuffer=\"10\"\n hideResetControl\n staticMode \n osVectorTilesApiKey=\"\" />"}],"id":"mymap---geojson"},{"name":"PostcodeSearch","description":"PostcodeSearch is a Lit-wrapped, Gov.UK-styled text input that formats and validates UK postcodes using the npm package 'postcode'.","properties":[{"name":"label","type":"String","values":"Postcode (default)"},{"name":"hintText","type":"String","values":"\"\" (default)"},{"name":"errorMessage","type":"String","values":"Enter a valid UK postcode (default)"},{"name":"onlyQuestionOnPage","type":"Boolean","values":"false (default), true if the label should be an <h1>"},{"name":"id","type":"String","values":"postcode (default)"},{"name":"errorId","type":"String","values":"postcode-error (default)"}],"methods":[{"name":"postcodeChange","params":[{"name":"postcodeChange","type":"Event Listener","values":"detail","description":"Dispatches on input change; returns the formatted input string and `true` if the input is a valid postcode"}]}],"examples":[{"title":"Enter a UK postcode","description":"Standard case","template":"<postcode-search />","controller":"function (document) {\n const input = document.querySelector(\"postcode-search\");\n \n input.addEventListener(\"postcodeChange\", ({ detail }) => {\n console.debug({ detail });\n });\n }"}],"id":"postcodesearch"}]
5 changes: 5 additions & 0 deletions pitsby/data/metrics-ids.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
module.exports = {
get(){
return {};
}
};
1 change: 1 addition & 0 deletions pitsby/data/projects.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
[{"engine":"vanilla"}]
Loading