@fieldia/map 0.17.0 → 0.19.0

package/src/lib/providers.d.mts

@@ -1,8 +1,9 @@
 import type { Locale } from '@fieldia/core';
 import { type Fetch } from './answers.mjs';
+import type { AddressParts } from './address-parts.mjs';
 import type { Bounds, LatLng } from './geo.mjs';
 /**
- * Where a map's images, credits, address search and routes come from. Every map in
+ * Where a map's images, live traffic, credits, address search and routes come from. Every map in
  * the package draws through one of these, so an app changes provider in one
  * place and nothing else moves. Keys never live in Fieldia: the app passes
  * them, or a function that fetches a short-lived token from its own server.
@@ -13,6 +14,10 @@ export interface TileSpec {
     /** With `{z}`, `{x}` and `{y}` where the tile's numbers go. */
     url: string;
     maxZoom: number;
+    /** The zoom they start at, when not the world's. */
+    minZoom?: number;
+    /** Seconds after which they are out of date, as live traffic's are: drawn again then, each address with `&t=` and the time. */
+    fresh?: number;
     tileSize?: number;
     zoomOffset?: number;
     /** Headers each image is fetched with: a token that must not sit in an address. */
@@ -38,7 +43,10 @@ export interface PlaceFound {
         lat: number;
         lng: number;
         address?: string;
+        parts?: AddressParts;
     }>;
+    /** Its address in its parts, when the search asked for them (`parts`); for Google's, `locate` gives them. */
+    parts?: AddressParts;
 }
 export interface SearchRequest {
     text: string;
@@ -48,6 +56,10 @@ export interface SearchRequest {
     zoom?: number;
     locale: Locale;
     signal?: AbortSignal;
+    /** Only places in these countries, by their ISO codes ("EG"). */
+    countries?: string[];
+    /** Each place's address in its parts too, for an address field to fill. */
+    parts?: boolean;
 }
 export type AddressSearch = (request: SearchRequest) => Promise<PlaceFound[]>;
 export type ReverseSearch = (at: LatLng & {
@@ -85,8 +97,10 @@ export interface MapProvider {
     readonly id: string;
     /** The map images of a kind, or null when the provider has none of it. */
     tiles(kind: BaseMap, locale: Locale): Promise<TileSpec | null>;
-    /** What must be credited under the map, for what is in view. */
-    credits(kind: BaseMap, view: MapView, locale: Locale): Promise<Credit[]>;
+    /** What must be credited under the map, for what is in view: its images', and its traffic's while that is drawn. */
+    credits(kind: BaseMap | 'traffic', view: MapView, locale: Locale): Promise<Credit[]>;
+    /** Live traffic, drawn over its map images of a kind; a provider with none has no Traffic button. */
+    traffic?(kind: BaseMap, locale: Locale): Promise<TileSpec | null>;
     /** The provider's mark, which its terms ask for in the map's corner. */
     readonly logo?: {
         text: string;
@@ -99,6 +113,8 @@ export interface MapProvider {
     readonly searchAsYouType?: boolean;
     /** Free for trying things out, not for an app in use: a warning says so once. */
     readonly demoOnly?: boolean;
+    /** What its terms ask to be said under its suggestions where no map of its own shows them; its mark (`logo`) says it for Google and Mapbox. */
+    readonly searchCredit?: Credit;
     /** A route along the roads, for a map's routes. */
     readonly route?: RouteFinder;
     /** The area within some minutes of a place, for a map's reachable area. */
@@ -135,7 +151,7 @@ export interface AzureMapsOptions {
     clientId?: string;
     fetch?: Fetch;
 }
-/** Microsoft Azure Maps: road, dark and satellite map images, credits for the view, and address search. */
+/** Microsoft Azure Maps: road, dark and satellite map images, live traffic, credits for the view, and address search. */
 export declare function azureMaps(options: AzureMapsOptions): MapProvider;
 export interface GoogleMapsOptions {
     key: string;
@@ -148,7 +164,8 @@ export interface GoogleMapsOptions {
 /**
  * Google's map images through its Map Tiles API (a session for each kind and
  * language, credits for the view, Google's mark in the corner its terms
- * name), its Places API's suggestions as people type, and its Geocoding API
+ * name; its traffic, a layer of its own over them), its Places API's
+ * suggestions as people type, and its Geocoding API
  * to name a point. The key needs those three APIs enabled, and should be
  * restricted to the app's sites.
  */
@@ -159,6 +176,13 @@ export interface MapboxOptions {
     style?: string;
     darkStyle?: string;
     satelliteStyle?: string;
+    /**
+     * A style of the app's own that draws Mapbox Traffic's lines and nothing
+     * else (no background), for the Traffic button: Mapbox's traffic is a
+     * vector tileset its styles draw, and it has no such style of its own.
+     * Without one, no Traffic button.
+     */
+    trafficStyle?: string;
     /** Mapbox's wordmark, as an image the app serves; its name is shown until one is given. */
     logo?: string;
     /**
@@ -176,6 +200,8 @@ export interface TilesOptions {
     url: string;
     darkUrl?: string;
     satelliteUrl?: string;
+    /** The app's own live traffic, drawn over the map: with it, a Traffic button. */
+    trafficUrl?: string;
     credit: Credit | Credit[];
     maxZoom?: number;
     tileSize?: number;

package/src/lib/providers.d.ts

@@ -1,8 +1,9 @@
 import type { Locale } from '@fieldia/core';
 import { type Fetch } from './answers';
+import type { AddressParts } from './address-parts';
 import type { Bounds, LatLng } from './geo';
 /**
- * Where a map's images, credits, address search and routes come from. Every map in
+ * Where a map's images, live traffic, credits, address search and routes come from. Every map in
  * the package draws through one of these, so an app changes provider in one
  * place and nothing else moves. Keys never live in Fieldia: the app passes
  * them, or a function that fetches a short-lived token from its own server.
@@ -13,6 +14,10 @@ export interface TileSpec {
     /** With `{z}`, `{x}` and `{y}` where the tile's numbers go. */
     url: string;
     maxZoom: number;
+    /** The zoom they start at, when not the world's. */
+    minZoom?: number;
+    /** Seconds after which they are out of date, as live traffic's are: drawn again then, each address with `&t=` and the time. */
+    fresh?: number;
     tileSize?: number;
     zoomOffset?: number;
     /** Headers each image is fetched with: a token that must not sit in an address. */
@@ -38,7 +43,10 @@ export interface PlaceFound {
         lat: number;
         lng: number;
         address?: string;
+        parts?: AddressParts;
     }>;
+    /** Its address in its parts, when the search asked for them (`parts`); for Google's, `locate` gives them. */
+    parts?: AddressParts;
 }
 export interface SearchRequest {
     text: string;
@@ -48,6 +56,10 @@ export interface SearchRequest {
     zoom?: number;
     locale: Locale;
     signal?: AbortSignal;
+    /** Only places in these countries, by their ISO codes ("EG"). */
+    countries?: string[];
+    /** Each place's address in its parts too, for an address field to fill. */
+    parts?: boolean;
 }
 export type AddressSearch = (request: SearchRequest) => Promise<PlaceFound[]>;
 export type ReverseSearch = (at: LatLng & {
@@ -85,8 +97,10 @@ export interface MapProvider {
     readonly id: string;
     /** The map images of a kind, or null when the provider has none of it. */
     tiles(kind: BaseMap, locale: Locale): Promise<TileSpec | null>;
-    /** What must be credited under the map, for what is in view. */
-    credits(kind: BaseMap, view: MapView, locale: Locale): Promise<Credit[]>;
+    /** What must be credited under the map, for what is in view: its images', and its traffic's while that is drawn. */
+    credits(kind: BaseMap | 'traffic', view: MapView, locale: Locale): Promise<Credit[]>;
+    /** Live traffic, drawn over its map images of a kind; a provider with none has no Traffic button. */
+    traffic?(kind: BaseMap, locale: Locale): Promise<TileSpec | null>;
     /** The provider's mark, which its terms ask for in the map's corner. */
     readonly logo?: {
         text: string;
@@ -99,6 +113,8 @@ export interface MapProvider {
     readonly searchAsYouType?: boolean;
     /** Free for trying things out, not for an app in use: a warning says so once. */
     readonly demoOnly?: boolean;
+    /** What its terms ask to be said under its suggestions where no map of its own shows them; its mark (`logo`) says it for Google and Mapbox. */
+    readonly searchCredit?: Credit;
     /** A route along the roads, for a map's routes. */
     readonly route?: RouteFinder;
     /** The area within some minutes of a place, for a map's reachable area. */
@@ -135,7 +151,7 @@ export interface AzureMapsOptions {
     clientId?: string;
     fetch?: Fetch;
 }
-/** Microsoft Azure Maps: road, dark and satellite map images, credits for the view, and address search. */
+/** Microsoft Azure Maps: road, dark and satellite map images, live traffic, credits for the view, and address search. */
 export declare function azureMaps(options: AzureMapsOptions): MapProvider;
 export interface GoogleMapsOptions {
     key: string;
@@ -148,7 +164,8 @@ export interface GoogleMapsOptions {
 /**
  * Google's map images through its Map Tiles API (a session for each kind and
  * language, credits for the view, Google's mark in the corner its terms
- * name), its Places API's suggestions as people type, and its Geocoding API
+ * name; its traffic, a layer of its own over them), its Places API's
+ * suggestions as people type, and its Geocoding API
  * to name a point. The key needs those three APIs enabled, and should be
  * restricted to the app's sites.
  */
@@ -159,6 +176,13 @@ export interface MapboxOptions {
     style?: string;
     darkStyle?: string;
     satelliteStyle?: string;
+    /**
+     * A style of the app's own that draws Mapbox Traffic's lines and nothing
+     * else (no background), for the Traffic button: Mapbox's traffic is a
+     * vector tileset its styles draw, and it has no such style of its own.
+     * Without one, no Traffic button.
+     */
+    trafficStyle?: string;
     /** Mapbox's wordmark, as an image the app serves; its name is shown until one is given. */
     logo?: string;
     /**
@@ -176,6 +200,8 @@ export interface TilesOptions {
     url: string;
     darkUrl?: string;
     satelliteUrl?: string;
+    /** The app's own live traffic, drawn over the map: with it, a Traffic button. */
+    trafficUrl?: string;
     credit: Credit | Credit[];
     maxZoom?: number;
     tileSize?: number;

package/src/lib/providers.js

@@ -6,8 +6,11 @@ exports.googleMaps = googleMaps;
 exports.mapbox = mapbox;
 exports.tiles = tiles;
 const answers_1 = require("./answers");
+const address_line_1 = require("./address-line");
 /** The providers' routes, loaded the first time one is asked for: a form with only a place or an area never carries them. */
 const routes = () => Promise.resolve().then(() => require('./routes'));
+/** How each provider's addresses read in their parts, loaded the first time a search asks for parts or countries (an address field's): a place's search never carries it. */
+const partsReader = (parts, countries) => (parts || countries?.length ? Promise.resolve().then(() => require('./address-parts')) : undefined);
 const query = (params) => Object.entries(params)
     .filter(([, value]) => value !== undefined)
     .map(([key, value]) => `${key}=${encodeURIComponent(String(value))}`)
@@ -20,16 +23,8 @@ const textOfHtml = (html) => html
     .replace(/<[^>]*>/g, '')
     .replace(/&(#x[0-9a-f]+|#[0-9]+|[a-z]+);/gi, (all, name) => name[0] === '#' ? String.fromCodePoint(parseInt(name.slice(name[1] === 'x' || name[1] === 'X' ? 2 : 1), name[1] === 'x' || name[1] === 'X' ? 16 : 10)) : (ENTITIES[name.toLowerCase()] ?? all))
     .trim();
-/** The words of a list that are there, once each, joined: "Downtown, Cairo, Egypt". */
-const joined = (...parts) => {
-    const seen = [];
-    for (const part of parts)
-        if (typeof part === 'string' && part.trim() && !seen.includes(part.trim()))
-            seen.push(part.trim());
-    return seen.join(', ');
-};
-/** Places from a GeoJSON FeatureCollection: each named by the first of `labels` it has, with the line under it from `detail`. */
-function placesFrom(collection, labels, detail) {
+/** Places from a GeoJSON FeatureCollection: each named by the first of `labels` it has, with the line under it from `detail`, and its parts from `parts`. */
+function placesFrom(collection, labels, detail, parts) {
     const features = (0, answers_1.pathOf)(collection, 'features');
     if (!Array.isArray(features))
         return [];
@@ -39,13 +34,14 @@ function placesFrom(collection, labels, detail) {
         if (typeof lat !== 'number' || typeof lng !== 'number' || typeof label !== 'string')
             return [];
         const under = detail?.((0, answers_1.pathOf)(feature, 'properties'));
-        return [{ label, ...(under && under !== label ? { detail: under } : {}), lat, lng }];
+        const found = parts?.((0, answers_1.pathOf)(feature, 'properties'));
+        return [{ label, ...(under && under !== label ? { detail: under } : {}), lat, lng, ...(found ? { parts: found } : {}) }];
     });
 }
 /** Languages Photon names places in; in any other it gives the places' own names. */
 const PHOTON_LANGUAGES = new Set(['en', 'de', 'fr']);
-/** Photon's places: each one's name (or its street and number) on one line, where it is on the next. */
-function photonPlaces(found) {
+/** Photon's places: each one's name (or its street and number) on one line, where it is on the next; their parts when asked. */
+function photonPlaces(found, locale, parts) {
     const features = (0, answers_1.pathOf)(found, 'features');
     if (!Array.isArray(features))
         return [];
@@ -57,8 +53,9 @@ function photonPlaces(found) {
         if (typeof lat !== 'number' || typeof lng !== 'number' || !label)
             return [];
         // Under a named place, its street when it has one; then its district, city and country.
-        const detail = joined(label === streetOf(p) ? '' : streetOf(p), (0, answers_1.pathOf)(p, 'district'), (0, answers_1.pathOf)(p, 'city'), (0, answers_1.pathOf)(p, 'state'), (0, answers_1.pathOf)(p, 'country'));
-        return [{ label, ...(detail ? { detail } : {}), lat, lng }];
+        const detail = (0, address_line_1.addressLine)([label === streetOf(p) ? '' : streetOf(p), (0, answers_1.pathOf)(p, 'district'), (0, answers_1.pathOf)(p, 'city'), (0, answers_1.pathOf)(p, 'state'), (0, answers_1.pathOf)(p, 'country')], locale);
+        const own = parts?.(p);
+        return [{ label, ...(detail ? { detail } : {}), lat, lng, ...(own ? { parts: own } : {}) }];
     });
 }
 /**
@@ -73,6 +70,7 @@ function openStreetMap(options = {}) {
     const base = {
         id: 'openstreetmap',
         demoOnly: true,
+        searchCredit: { text: '© OpenStreetMap contributors', href: 'https://www.openstreetmap.org/copyright' },
         async route(request) {
             return (await routes()).osrmRoute(fetchWith, osrm, request);
         },
@@ -87,8 +85,9 @@ function openStreetMap(options = {}) {
         return {
             ...base,
             searchAsYouType: false,
-            async search({ text, locale, signal }) {
-                const found = await (0, answers_1.getJson)(fetchWith, `https://nominatim.openstreetmap.org/search?${query({ format: 'jsonv2', limit: 5, q: text, 'accept-language': locale })}`, { signal });
+            async search({ text, locale, signal, countries, parts }) {
+                const found = await (0, answers_1.getJson)(fetchWith, `https://nominatim.openstreetmap.org/search?${query({ format: 'jsonv2', limit: 5, q: text, 'accept-language': locale, countrycodes: countries?.join(',').toLowerCase() || undefined, addressdetails: parts ? 1 : undefined })}`, { signal });
+                const read = await partsReader(parts);
                 return Array.isArray(found)
                     ? found.flatMap((place) => {
                         const lat = Number((0, answers_1.pathOf)(place, 'lat'));
@@ -99,14 +98,15 @@ function openStreetMap(options = {}) {
                         const name = (0, answers_1.pathOf)(place, 'name');
                         const label = typeof name === 'string' && name.trim() ? name : whole.split(',')[0];
                         const rest = whole.split(',').map((part) => part.trim()).filter((part, i) => !(i === 0 && part === label));
-                        return [{ label, ...(rest.length ? { detail: rest.join(', ') } : {}), lat, lng }];
+                        const own = read?.nominatimParts((0, answers_1.pathOf)(place, 'address'));
+                        const detail = (0, address_line_1.addressLine)(rest, locale);
+                        return [{ label, ...(detail ? { detail } : {}), lat, lng, ...(own ? { parts: own } : {}) }];
                     })
                     : [];
             },
             async reverse({ lat, lng, locale, signal }) {
                 const found = await (0, answers_1.getJson)(fetchWith, `https://nominatim.openstreetmap.org/reverse?${query({ format: 'jsonv2', lat, lon: lng, 'accept-language': locale })}`, { signal });
-                const label = (0, answers_1.pathOf)(found, 'display_name');
-                return typeof label === 'string' ? label : null;
+                return (0, address_line_1.addressLine)([(0, answers_1.pathOf)(found, 'display_name')], locale) || null;
             },
         };
     }
@@ -114,14 +114,16 @@ function openStreetMap(options = {}) {
     return {
         ...base,
         searchAsYouType: true,
-        async search({ text, near, zoom, locale, signal }) {
+        async search({ text, near, zoom, locale, signal, countries, parts }) {
             const found = await (0, answers_1.getJson)(fetchWith, `${photon}/api?${query({ q: text, limit: 6, lang: lang(locale), lat: near?.lat, lon: near?.lng, zoom: near && zoom !== undefined ? Math.round(zoom) : undefined })}`, { signal });
-            return photonPlaces(found);
+            // Photon cannot be asked to keep to some countries: those outside them are left out here.
+            const read = await partsReader(parts, countries);
+            return read ? read.inCountries(photonPlaces(found, locale, read.photonParts), countries) : photonPlaces(found, locale);
         },
         async reverse({ lat, lng, locale, signal }) {
             const found = await (0, answers_1.getJson)(fetchWith, `${photon}/reverse?${query({ lat, lon: lng, limit: 1, lang: lang(locale) })}`, { signal });
-            const [place] = photonPlaces(found);
-            return place ? joined(place.label, place.detail) : null;
+            const [place] = photonPlaces(found, locale);
+            return place ? (0, address_line_1.addressLine)([place.label, place.detail], locale) : null;
         },
     };
 }
@@ -133,8 +135,8 @@ function streetOf(properties) {
 }
 /** Azure lists the languages it draws; it refuses any other tag, `ar-001` among them. */
 const AZURE_LANGUAGE = { en: 'en-US', ar: 'ar', fr: 'fr-FR', de: 'de-DE' };
-const AZURE_TILESET = { road: 'microsoft.base.road', dark: 'microsoft.base.darkgrey', satellite: 'microsoft.imagery' };
-/** Microsoft Azure Maps: road, dark and satellite map images, credits for the view, and address search. */
+const AZURE_TILESET = { road: 'microsoft.base.road', dark: 'microsoft.base.darkgrey', satellite: 'microsoft.imagery', traffic: 'microsoft.traffic.relative.main' };
+/** Microsoft Azure Maps: road, dark and satellite map images, live traffic, credits for the view, and address search. */
 function azureMaps(options) {
     if (!options.key && !options.token)
         throw new Error('azureMaps needs a key or a token');
@@ -145,12 +147,16 @@ function azureMaps(options) {
         signal,
         headers: { ...(await headers()), ...(locale ? { 'Accept-Language': AZURE_LANGUAGE[locale] } : {}) },
     });
+    const tile = (tileset, locale) => `https://atlas.microsoft.com/map/tile?api-version=2024-04-01&tilesetId=${tileset}&zoom={z}&x={x}&y={y}&tileSize=256&language=${AZURE_LANGUAGE[locale]}&view=Auto${auth}`;
     return {
         id: 'azure-maps',
         searchAsYouType: true,
         async tiles(kind, locale) {
-            const url = `https://atlas.microsoft.com/map/tile?api-version=2024-04-01&tilesetId=${AZURE_TILESET[kind]}&zoom={z}&x={x}&y={y}&tileSize=256&language=${AZURE_LANGUAGE[locale]}&view=Auto${auth}`;
-            return { url, maxZoom: kind === 'satellite' ? 19 : 22, ...(options.key ? {} : { headers }) };
+            return { url: tile(AZURE_TILESET[kind], locale), maxZoom: kind === 'satellite' ? 19 : 22, ...(options.key ? {} : { headers }) };
+        },
+        // How each road flows against its free flow, in its own colours over the dark map; zooms 6 to 21 (it answers none outside them), out of date in four minutes (its cache-control's max-age).
+        async traffic(kind, locale) {
+            return { url: tile(kind === 'dark' ? 'microsoft.traffic.relative.dark' : AZURE_TILESET.traffic, locale), minZoom: 6, maxZoom: 21, fresh: 240, ...(options.key ? {} : { headers }) };
         },
         async credits(kind, { zoom, bounds }) {
             try {
@@ -164,15 +170,17 @@ function azureMaps(options) {
             }
             return [{ text: '© Microsoft' }];
         },
-        async search({ text, near, locale, signal }) {
+        async search({ text, near, locale, signal, countries, parts }) {
             const coordinates = near ? `${near.lng},${near.lat}` : undefined;
             // Its autocomplete reads a word half typed, as geocoding does not; its suggestions carry no place, so a picked one is geocoded then.
             const found = await ask('geocode:autocomplete', { 'api-version': '2026-01-01', top: 5, query: text, coordinates }, locale, signal);
-            return azurePlaces(found).map((place) => ({
+            // Its parts come with each suggestion; those outside the countries asked for are left out here.
+            const read = await partsReader(parts, countries);
+            return (read ? read.inCountries(azurePlaces(found, locale, read.azureParts), countries) : azurePlaces(found, locale)).map((place) => ({
                 ...place,
                 locate: async () => {
-                    const address = [place.label, place.detail].filter(Boolean).join(', ');
-                    const [hit] = azurePlaces(await ask('geocode', { 'api-version': '2023-06-01', top: 1, query: place.whole ?? address, coordinates }, locale));
+                    const address = (0, address_line_1.addressLine)([place.label, place.detail], locale);
+                    const [hit] = azurePlaces(await ask('geocode', { 'api-version': '2023-06-01', top: 1, query: place.whole ?? address, coordinates }, locale), locale);
                     if (hit?.lat === undefined || hit.lng === undefined)
                         throw new Error('Azure Maps found no place');
                     // The address as its two lines read: with its town, which Azure's own may leave out.
@@ -184,7 +192,7 @@ function azureMaps(options) {
             const found = await ask('reverseGeocode', { 'api-version': '2023-06-01', coordinates: `${lng},${lat}` }, locale, signal);
             const features = (0, answers_1.pathOf)(found, 'features');
             const formatted = Array.isArray(features) ? clean((0, answers_1.pathOf)(features[0], 'properties', 'address', 'formattedAddress')) : '';
-            return formatted || null;
+            return (0, address_line_1.addressLine)([formatted], locale) || null;
         },
         async route(request) {
             return (await routes()).azureRoute({ fetchWith, auth, headers }, request);
@@ -200,7 +208,7 @@ function azureMaps(options) {
  * says (geocoding does, autocomplete does not); and the whole address as Azure
  * wrote it, to geocode a suggestion by.
  */
-function azurePlaces(found) {
+function azurePlaces(found, locale, partsOf) {
     const features = (0, answers_1.pathOf)(found, 'features');
     if (!Array.isArray(features))
         return [];
@@ -220,14 +228,17 @@ function azurePlaces(found) {
         if (town && !rest.includes(town))
             rest = [town, ...rest];
         const at = typeof lat === 'number' && typeof lng === 'number' ? { lat, lng } : {};
-        return [{ label, ...(rest.length ? { detail: rest.join(', ') } : {}), ...at, ...(whole ? { whole } : {}) }];
+        const own = partsOf?.(address);
+        const detail = (0, address_line_1.addressLine)(rest, locale);
+        return [{ label, ...(detail ? { detail } : {}), ...at, ...(whole ? { whole } : {}), ...(own ? { parts: own } : {}) }];
     });
 }
-const GOOGLE_MAP_TYPE = { road: 'roadmap', satellite: 'satellite' };
+const GOOGLE_MAP_TYPE = { road: 'roadmap', satellite: 'satellite', traffic: 'roadmap' };
 /**
  * Google's map images through its Map Tiles API (a session for each kind and
  * language, credits for the view, Google's mark in the corner its terms
- * name), its Places API's suggestions as people type, and its Geocoding API
+ * name; its traffic, a layer of its own over them), its Places API's
+ * suggestions as people type, and its Geocoding API
  * to name a point. The key needs those three APIs enabled, and should be
  * restricted to the app's sites.
  */
@@ -237,14 +248,15 @@ function googleMaps(options) {
     const sessions = new Map();
     function session(kind, locale) {
         const mapType = GOOGLE_MAP_TYPE[kind];
-        const id = `${mapType}:${locale}`;
+        const id = `${kind}:${locale}`;
         const known = sessions.get(id);
         return known ?? open();
         function open() {
             const opening = (0, answers_1.getJson)(fetchWith, `https://tile.googleapis.com/v1/createSession?key=${key}`, {
                 method: 'POST',
                 headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify({ mapType, language: locale, region: options.region ?? 'US' }),
+                // Traffic alone, without the map under it: an overlay.
+                body: JSON.stringify({ mapType, language: locale, region: options.region ?? 'US', ...(kind === 'traffic' ? { layerTypes: ['layerTraffic'], overlay: true } : {}) }),
             }).then((answer) => {
                 const value = (0, answers_1.pathOf)(answer, 'session');
                 if (typeof value !== 'string')
@@ -266,13 +278,19 @@ function googleMaps(options) {
     /** One session from the first letter typed to the place picked: Google charges the suggestions of a session that ends in a pick as the pick. */
     let searching;
     const newSession = () => (globalThis.crypto?.randomUUID?.() ?? 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => ((Math.random() * 16) | (c === 'x' ? 0 : 8)).toString(16).slice(0, 1)));
+    async function tilesOf(kind, locale) {
+        if (!GOOGLE_MAP_TYPE[kind])
+            return null;
+        const { session: id } = await session(kind, locale);
+        return { url: `https://tile.googleapis.com/v1/2dtiles/{z}/{x}/{y}?session=${id}&key=${key}`, maxZoom: 22 };
+    }
     /** How far "near" reaches at a zoom: about what the map shows, within Google's bounds. */
     const radiusAt = (zoom) => Math.round(Math.min(50_000, Math.max(100, 40_075_016 / 2 ** (zoom ?? 12))));
     return {
         id: 'google',
         logo: { text: 'Google Maps', ...(options.logo ? { image: options.logo } : {}) },
         searchAsYouType: true,
-        async search({ text, near, zoom, locale, signal }) {
+        async search({ text, near, zoom, locale, signal, countries, parts }) {
             searching ??= newSession();
             const token = searching;
             const answer = await (0, answers_1.getJson)(fetchWith, 'https://places.googleapis.com/v1/places:autocomplete', {
@@ -283,6 +301,7 @@ function googleMaps(options) {
                     input: text,
                     languageCode: locale,
                     ...(options.region ? { regionCode: options.region } : {}),
+                    ...(countries?.length ? { includedRegionCodes: countries.map((code) => code.toLowerCase()) } : {}),
                     sessionToken: token,
                     ...(near ? { locationBias: { circle: { center: { latitude: near.lat, longitude: near.lng }, radius: radiusAt(zoom) } } } : {}),
                 }),
@@ -296,14 +315,15 @@ function googleMaps(options) {
                 const label = clean((0, answers_1.pathOf)(prediction, 'structuredFormat', 'mainText', 'text')) || clean((0, answers_1.pathOf)(prediction, 'text', 'text'));
                 if (typeof placeId !== 'string' || !label)
                     return [];
-                const detail = clean((0, answers_1.pathOf)(prediction, 'structuredFormat', 'secondaryText', 'text'));
+                const detail = (0, address_line_1.addressLine)([(0, answers_1.pathOf)(prediction, 'structuredFormat', 'secondaryText', 'text')], locale);
                 return [
                     {
                         label,
                         ...(detail ? { detail } : {}),
                         locate: async () => {
                             const place = await (0, answers_1.getJson)(fetchWith, `https://places.googleapis.com/v1/places/${encodeURIComponent(placeId)}?${query({ languageCode: locale, sessionToken: token })}`, {
-                                headers: { 'X-Goog-Api-Key': options.key, 'X-Goog-FieldMask': 'location,formattedAddress' },
+                                // Its parts, when asked for, at the same price as the rest (Place Details Essentials).
+                                headers: { 'X-Goog-Api-Key': options.key, 'X-Goog-FieldMask': `location,formattedAddress${parts ? ',addressComponents' : ''}` },
                             });
                             // Picked: the session is over, the next letter typed opens another.
                             if (searching === token)
@@ -312,8 +332,9 @@ function googleMaps(options) {
                             const longitude = (0, answers_1.pathOf)(place, 'location', 'longitude');
                             if (typeof latitude !== 'number' || typeof longitude !== 'number')
                                 throw new Error('Google gave no place');
-                            const address = clean((0, answers_1.pathOf)(place, 'formattedAddress'));
-                            return { lat: latitude, lng: longitude, ...(address ? { address } : {}) };
+                            const address = (0, address_line_1.addressLine)([(0, answers_1.pathOf)(place, 'formattedAddress')], locale);
+                            const own = (await partsReader(parts))?.googleParts((0, answers_1.pathOf)(place, 'addressComponents'));
+                            return { lat: latitude, lng: longitude, ...(address ? { address } : {}), ...(own ? { parts: own } : {}) };
                         },
                     },
                 ];
@@ -326,18 +347,14 @@ function googleMaps(options) {
             if (typeof status === 'string' && status !== 'OK' && status !== 'ZERO_RESULTS')
                 throw new Error(`Google's Geocoding API answered ${status}: ${String((0, answers_1.pathOf)(answer, 'error_message') ?? '')}`);
             const results = (0, answers_1.pathOf)(answer, 'results');
-            const named = Array.isArray(results) ? clean((0, answers_1.pathOf)(results[0], 'formatted_address')) : '';
+            const named = Array.isArray(results) ? (0, address_line_1.addressLine)([(0, answers_1.pathOf)(results[0], 'formatted_address')], locale) : '';
             return named || null;
         },
         async route(request) {
             return (await routes()).googleRoute({ fetchWith, key: options.key }, request);
         },
-        async tiles(kind, locale) {
-            if (!GOOGLE_MAP_TYPE[kind])
-                return null;
-            const { session: id } = await session(kind, locale);
-            return { url: `https://tile.googleapis.com/v1/2dtiles/{z}/{x}/{y}?session=${id}&key=${key}`, maxZoom: 22 };
-        },
+        tiles: (kind, locale) => tilesOf(kind, locale),
+        traffic: (_kind, locale) => tilesOf('traffic', locale),
         async credits(kind, { zoom, bounds }, locale) {
             try {
                 const { session: id } = await session(kind === 'dark' ? 'road' : kind, locale);
@@ -362,6 +379,8 @@ function mapbox(options) {
         dark: options.darkStyle ?? 'mapbox/dark-v11',
         satellite: options.satelliteStyle ?? 'mapbox/satellite-streets-v12',
     };
+    const styleTiles = (style) => ({ url: `https://api.mapbox.com/styles/v1/${style}/tiles/512/{z}/{x}/{y}@2x?access_token=${token}`, maxZoom: 22, tileSize: 512, zoomOffset: -1 });
+    const traffic = options.trafficStyle;
     const permanent = options.permanent ?? true;
     const ask = async (path, params, signal) => (0, answers_1.getJson)(fetchWith, `https://api.mapbox.com/search/geocode/v6/${path}?${query({ ...params, permanent: String(permanent) })}&access_token=${token}`, { signal });
     return {
@@ -369,8 +388,9 @@ function mapbox(options) {
         searchAsYouType: true,
         logo: { text: 'mapbox', ...(options.logo ? { image: options.logo } : {}), href: 'https://www.mapbox.com/' },
         async tiles(kind) {
-            return { url: `https://api.mapbox.com/styles/v1/${styles[kind]}/tiles/512/{z}/{x}/{y}@2x?access_token=${token}`, maxZoom: 22, tileSize: 512, zoomOffset: -1 };
+            return styleTiles(styles[kind]);
         },
+        ...(traffic ? { traffic: async () => styleTiles(traffic) } : {}),
         async credits() {
             return [
                 { text: '© Mapbox', href: 'https://www.mapbox.com/about/maps/' },
@@ -378,11 +398,12 @@ function mapbox(options) {
                 { text: 'Improve this map', href: 'https://www.mapbox.com/map-feedback/' },
             ];
         },
-        async search({ text, near, locale, signal }) {
-            return placesFrom(await ask('forward', { q: text, limit: 5, language: locale, proximity: near ? `${near.lng},${near.lat}` : undefined }, signal), [['properties', 'name'], ['properties', 'full_address']], (p) => joined((0, answers_1.pathOf)(p, 'place_formatted')));
+        async search({ text, near, locale, signal, countries, parts }) {
+            return placesFrom(await ask('forward', { q: text, limit: 5, language: locale, proximity: near ? `${near.lng},${near.lat}` : undefined, country: countries?.join(',').toLowerCase() || undefined }, signal), [['properties', 'name'], ['properties', 'full_address']], (p) => (0, address_line_1.addressLine)([(0, answers_1.pathOf)(p, 'place_formatted')], locale), (await partsReader(parts))?.mapboxParts);
         },
         async reverse({ lat, lng, locale, signal }) {
-            return placesFrom(await ask('reverse', { longitude: lng, latitude: lat, language: locale, limit: 1 }, signal), [['properties', 'full_address'], ['properties', 'name']])[0]?.label ?? null;
+            const [named] = placesFrom(await ask('reverse', { longitude: lng, latitude: lat, language: locale, limit: 1 }, signal), [['properties', 'full_address'], ['properties', 'name']]);
+            return named ? (0, address_line_1.addressLine)([named.label], locale) : null;
         },
         async route(request) {
             return (await routes()).mapboxRoute({ fetchWith, token }, request);
@@ -396,6 +417,8 @@ function mapbox(options) {
 function tiles(options) {
     const urls = { road: options.url, dark: options.darkUrl, satellite: options.satelliteUrl };
     const credits = Array.isArray(options.credit) ? options.credit : [options.credit];
+    const spec = (url) => ({ url, maxZoom: options.maxZoom ?? 19, ...(options.tileSize ? { tileSize: options.tileSize } : {}), ...(options.zoomOffset ? { zoomOffset: options.zoomOffset } : {}) });
+    const traffic = options.trafficUrl;
     return {
         id: 'tiles',
         search: options.search,
@@ -405,10 +428,9 @@ function tiles(options) {
         searchAsYouType: options.searchAsYouType ?? !!options.search,
         async tiles(kind) {
             const url = urls[kind];
-            if (!url)
-                return null;
-            return { url, maxZoom: options.maxZoom ?? 19, ...(options.tileSize ? { tileSize: options.tileSize } : {}), ...(options.zoomOffset ? { zoomOffset: options.zoomOffset } : {}) };
+            return url ? spec(url) : null;
         },
+        ...(traffic ? { traffic: async () => spec(traffic) } : {}),
         async credits() {
             return credits;
         },