Maps

Tome maps layer — a neutral map seam: the provider and geocoder contract, a registry, MapLibre, Google and Mapbox providers (SDKs stay optional peers), deferred loading until a visitor asks for the map, a fallback for a failed or blocked map, and the pin, cluster and framing helpers a legend needs.

Layer: domain (per ARCHITECTURE.md § The Layer Model). It owns no collection and no Payload code; it sits in the domain layer so the directory layer can import its types. Tier: free, foundation family.

A map is an enhancement. A "Directions" link works with no map, no script and no third party, so a failed or blocked map falls back to links, and a site can hold the map until a visitor asks for it. That matters most on a health or clinic site, where a third-party request before consent is a decision the site owner wants to make.

Peer ranges, copied from package.json:

None of the three SDKs is a hard dependency. Each provider loads its SDK with a dynamic import() inside a client-only effect, so a site pays only for the one it uses, and nothing is requested until a map actually mounts.

60-second quickstart

'use client'

import '@wabbit/tome-maps/maplibre' // self-registers the provider; no key needed
import { getMapProvider } from '@wabbit/tome-maps'
import type { MapPin } from '@wabbit/tome-maps'

const pins: MapPin[] = [{ id: 'main', lat: 39.0997, lng: -94.5786, label: 'Main office' }]

export function OfficeMap() {
  const provider = getMapProvider('maplibre')!
  const { MapView } = provider
  return (
    <MapView
      pins={pins}
      theme="light"
      loadOn="interaction"
      fallback={<a href={provider.directionsUrl({ lat: 39.0997, lng: -94.5786, label: 'Main office' })}>Get directions</a>}
    />
  )
}

With loadOn="interaction" the page requests nothing from any map host until the visitor presses "Show map". Until then the fallback and the button render in place of the map.

Server and client posture

The package root (@wabbit/tome-maps) and ./types are browser-safe and server-safe: types, the registry, and the pin, cluster and framing helpers. They import no map SDK. The provider entries ./maplibre, ./google and ./mapbox are client modules ('use client'); import them from a frontend entry point, not from payload.config.ts or other server-only code. ./google/server and ./mapbox/server are server modules (server-only) that read a server key to geocode. ./shared is internal.

API surface

Pins

MapPin needs an id, the coordinates and a label. slug, href and an open meta bag are optional; providers never read meta, so a consumer can hang its own record on a pin and look it up by id in onPinSelect. A pin drawn with no extra fields is an ordinary pin: natural size, no status badge, labelled with its name alone, and clusters of such pins show a count with no open-share arc.

A consumer with richer pins (a directory's listings) extends MapPin and adds drawing fields. Providers read sponsored, openState ('open' | 'closing' | 'closed') and tier off a pin when they are present and draw the sponsored size, the status badge and the closed fade accordingly. Nothing else on a pin is read.

Loading and failure

loadOn controls when a map starts to load. 'visible' (the default) loads as soon as the map renders; it does not wait for the map to scroll into view. 'interaction' renders the fallback and a "Show map" button (relabel it with showMapLabel) and requests no script and no tiles until the button is pressed.

fallback renders when the SDK cannot load (a blocked script host, an uninstalled optional peer), when no key is configured for a keyed provider, and when the map style cannot be fetched before the first render. A single missing tile after the first render leaves the map in place. Without a fallback the frame is left as it is, which is how the providers behaved before fallback existed.

Guard

Every provider takes an optional guard prop: a function of the view props that must return exactly true for the map to render and load its SDK. Anything else, including a throw, blocks the map entirely: nothing renders, not even the fallback, and the SDK is never imported. mountMaplibreMap, mountGoogleMap and mountMapboxMap check it again before they touch the loader, so a map blocked by its guard cannot reach the dynamic import by any route.

This package applies no guard by default and has no notion of what a guard checks. A consumer that must fail closed injects its own on every map it renders. @wabbit/tome-blocks-directory-pack does exactly that for its age gate: it wraps each provider and always passes its guard, and keeps its own registry so a directory block can only ever look up a guarded provider.

Configuration

import { configureMaplibreProvider, configureNominatimGeocoder } from '@wabbit/tome-maps/maplibre'

configureMaplibreProvider({
  styleUrl: { light: 'https://tiles.example.com/styles/light', dark: 'https://tiles.example.com/styles/dark' },
  attributionText: 'Tiles by Example',
})

configureNominatimGeocoder({ userAgent: 'your-site/1.0 (+https://your-site.example)', email: 'ops@your-site.example' })

The default MapLibre style comes from OpenFreeMap: free, no key, commercial use allowed, attribution required (the provider renders it). It carries no uptime promise and may stop at any time, so the style URL is configuration, and pointing it at a self-hosted style is a one-line change. The Nominatim geocoder is throttled to one request per second and needs an identifying user agent. Google and Mapbox keys come from boot-time config or the public NEXT_PUBLIC_DIRECTORY_GOOGLE_MAPS_BROWSER_KEY and NEXT_PUBLIC_DIRECTORY_MAPBOX_ACCESS_TOKEN variables (names kept from the directory so existing sites need no change); server keys (DIRECTORY_GOOGLE_MAPS_SERVER_KEY, DIRECTORY_MAPBOX_ACCESS_TOKEN) are read only by the /server entries and never reach the browser bundle.

Links

• CHANGELOG