Place components

A library of Web Components for tasks related to addresses and planning permission in the UK built with Lit, Vite, and Ordnance Survey APIs.

Web map

<my-map /> is an OpenLayers-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.

Postcode search

<postcode-search /> is a GOV.UK-styled input that validates UK postcodes using these utility methods. When a postcode is validated, an event is dispatched containing the sanitized string.

Address autocomplete

<address-autocomplete /> fetches addresses in a given UK postcode using the OS Places API and displays them using GOV.UK's accessible-autocomplete component. An event is dispatched with the OS record when you select an address.

These web components can be used independently or together following GOV.UK's Address lookup design pattern.

Documentation & examples

• Interactive web component docs oslmap.netlify.app
• CodeSandbox (note: update the CDN script with a version number for new features)

Find these components in the wild, including what we're learning through public beta user-testing, at https://www.ripa.digital/.

Bring your own API keys

Different features rely on different APIs - namely from Ordnance Survey and Mapbox.

You can set keys directly as props (eg osApiKey) on the applicable web components or via environment variables (eg VITE_APP_OS_API_KEY) for local development.

Address autocomplete utilises the OS Places API.

For the map:

• The basemap prop defaults to "OSVectorTile" which requires the OS Vector Tiles API
  • Basemap "OSRaster" uses the OS Maps API
  • Basemap "MapboxSatellite" requires a Mapbox Access Token with with scope style:read
  • The "OSM" (OpenStreetMap) basemap is available for users without any keys, and as a fallback if any of the above basemaps fail to build
• clickFeatures requires the OS Features API

When using Ordnance Survey APIs:

• Update the osCopyright attribution prop with your license number
• Configure an optional osProxyEndpoint to avoid exposing your keys (set this instead of osApiKey)
  • ** We are not currently supporting a similar proxy for Mapbox because access tokens can be restricted to specific URLs via your account

Running locally

• Rename .env.example to .env.local and replace the values - or simply provide your API keys as props
• Install pnpm globally if you don't have it already npm i pnpm -g
• Install dependencies pnpm i
• Start development server pnpm dev

Tests

Unit tests are written with Vitest, Happy Dom, and @testing-library/user-event. Each component has a main.test.ts file.

• pnpm test starts vitest in watch mode
• pnpm test:ui opens Vitest's UI in the browser to interactively explore logs https://vitest.dev/guide/ui.html

Docs

We use Pitsby 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/

Deployments

We publish this package via NPM.

To create a new release:

1. Open a new PR against main which bumps the package.json "version" & creates a CHANGELOG.md entry, request code review & merge on approval
2. Run npm publish or npm publish --tag next if making a pre-release (requires permissions to OSL team in NPM & access to 2-factor auth method)
3. Draft a new release via GitHub web: tag should match version, automatically generate changenotes and link above PR, then "Publish" and set as latest version (or set as pre-release if you used --tag next in above command)

License

This repository is licensed under the Open Government License v3.