@opensystemslab/map

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

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/

License

This repository is licensed under the Open Government License v3.

Changelog

[0.8.3] - 2024-06-28

Fixed

• fix(a11y): adds a role to the map container div of either application if interactive or presentation if implemented in static mode (#454)

Changed

• deps: various dependency updates via Dependabot