@nways/maps 0.0.0-stage → 1.0.0

package/style.js

@@ -0,0 +1,228 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 N-WAYS LIMITED
+// The N-Ways Maps SDK's styles: the address of N-Ways' hosted style, and a
+// built-in compact light or dark street map drawn from N-Ways' vector tiles
+// (the base PMTiles archive) and fonts, with the partner's API key on every
+// request. Pure data, no MapLibre needed, so it can be tested and served on
+// its own.
+//
+// The N-Ways app draws a much richer style (src/lib/map/style.ts: 3D bridges,
+// traffic, place icons). This one keeps to what any partner map needs and
+// takes the same colours.
+
+/** Where the tiles and fonts are served. */
+export const NWAYS_ORIGIN = 'https://nways.ng'
+
+/** The tile archives a partner map may use. */
+export const TILESETS = { base: 'nigeria.pmtiles' }
+
+/** Data credits every N-Ways map must show (OpenStreetMap's licence, the ODbL, requires it). */
+export const ATTRIBUTION =
+  '<a href="https://nways.ng/developers/terms#attribution">N-Ways</a> · © <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors · <a href="https://protomaps.com">Protomaps</a>'
+
+const FONT = { regular: ['Inter-Regular'], medium: ['Inter-Medium'], semibold: ['Inter-SemiBold'], italic: ['Inter-Italic'] }
+
+/** Colours, from the app's palettes (src/lib/map/style.ts, roadLook.ts). */
+export const THEMES = {
+  light: {
+    earth: '#bcd59c',
+    park: '#86b663',
+    forest: '#8fbb6c',
+    water: '#74b3dc',
+    waterLabel: '#3f7795',
+    building: '#cec4b4',
+    buildingOutline: '#b8ad9c',
+    minor: '#fbfaf7',
+    minorCasing: '#94a985',
+    major: '#fbfcf6',
+    majorCasing: '#7f9d70',
+    highway: '#e9f1df',
+    highwayCasing: '#4f7a4a',
+    path: '#a3b98a',
+    boundary: '#7d8a76',
+    label: '#25302b',
+    labelMinor: '#5d6761',
+    halo: '#e7f0da',
+  },
+  dark: {
+    earth: '#283140',
+    park: '#1d5249',
+    forest: '#1f4a45',
+    water: '#1a3550',
+    waterLabel: '#7fa8c9',
+    building: '#333c4b',
+    buildingOutline: '#3b4555',
+    minor: '#737b8d',
+    minorCasing: '#1b2029',
+    major: '#7a958a',
+    majorCasing: '#1f2b27',
+    highway: '#3d7d59',
+    highwayCasing: '#1d4430',
+    path: '#4f5768',
+    boundary: '#8a93a3',
+    label: '#e3e8ef',
+    labelMinor: '#a4aebb',
+    halo: '#283140',
+  },
+}
+
+/** N-Ways' hosted styles, by theme (served at /maps/v1/styles/<id>.json). */
+export const STYLE_IDS = { light: 'streets-light', dark: 'streets-dark' }
+
+/**
+ * The address of N-Ways' hosted style for a theme and language, with the key:
+ * `{ key, theme: 'light' | 'dark', lang: 'en' | 'fr', origin }`. The hosted style
+ * is kept up to date by N-Ways (new layers, fixes) without a new SDK release.
+ */
+export function styleUrl(options = {}) {
+  const { key = '', theme = 'light', origin = NWAYS_ORIGIN, lang = 'en' } = options
+  const id = STYLE_IDS[theme]
+  if (!id) throw new Error(`N-Ways: unknown theme "${theme}" (light or dark)`)
+  const url = `${origin}/maps/v1/styles/${id}.json` + (lang === 'fr' ? '?lang=fr' : '')
+  return withKey(url, key, origin)
+}
+
+/** Adds the API key to an N-Ways address (and only to N-Ways addresses), once. */
+export function withKey(url, key, origin = NWAYS_ORIGIN) {
+  if (!key || !url.startsWith(origin + '/')) return url
+  const [path, hash] = url.split('#')
+  if (/[?&]key=/.test(path)) return url // already has one
+  return path + (path.includes('?') ? '&' : '?') + 'key=' + encodeURIComponent(key) + (hash !== undefined ? '#' + hash : '')
+}
+
+const zoomWidth = (stops) => ['interpolate', ['exponential', 1.6], ['zoom'], ...stops.flat()]
+const kindIs = (...kinds) => ['in', ['get', 'kind'], ['literal', kinds]]
+
+/**
+ * The style for a map: `{ key, theme: 'light' | 'dark', origin, lang: 'en' | 'fr' }`.
+ * Labels use the local name (`name`); French maps prefer `name:fr` where there is one.
+ */
+export function buildStyle(options = {}) {
+  const { key = '', theme = 'light', origin = NWAYS_ORIGIN, lang = 'en' } = options
+  const c = THEMES[theme]
+  if (!c) throw new Error(`N-Ways: unknown theme "${theme}" (light or dark)`)
+  const name = lang === 'fr' ? ['coalesce', ['get', 'name:fr'], ['get', 'name']] : ['get', 'name']
+  const archive = `${origin}/tiles/${TILESETS.base}`
+  const road = (id, kinds, colour, casing, widths, minzoom = 0) => [
+    {
+      id: `${id}-casing`,
+      type: 'line',
+      source: 'nways',
+      'source-layer': 'roads',
+      minzoom,
+      filter: kindIs(...kinds),
+      layout: { 'line-cap': 'round', 'line-join': 'round' },
+      paint: { 'line-color': casing, 'line-width': zoomWidth(widths.map(([z, w]) => [z, w + 1.5])) },
+    },
+    {
+      id,
+      type: 'line',
+      source: 'nways',
+      'source-layer': 'roads',
+      minzoom,
+      filter: kindIs(...kinds),
+      layout: { 'line-cap': 'round', 'line-join': 'round' },
+      paint: { 'line-color': colour, 'line-width': zoomWidth(widths) },
+    },
+  ]
+  return {
+    version: 8,
+    name: `N-Ways ${theme}`,
+    glyphs: withKey(`${origin}/fonts/{fontstack}/{range}.pbf`, key, origin),
+    sources: {
+      nways: {
+        type: 'vector',
+        // PMTiles: one archive read with range requests (the pmtiles protocol, registered by createMap).
+        url: `pmtiles://${withKey(archive, key, origin)}`,
+        attribution: ATTRIBUTION,
+      },
+    },
+    layers: [
+      { id: 'background', type: 'background', paint: { 'background-color': c.earth } },
+      {
+        id: 'landuse-green',
+        type: 'fill',
+        source: 'nways',
+        'source-layer': 'landuse',
+        filter: kindIs('park', 'forest', 'wood', 'nature_reserve', 'grass', 'garden', 'golf_course', 'cemetery'),
+        paint: { 'fill-color': ['match', ['get', 'kind'], ['forest', 'wood', 'nature_reserve'], c.forest, c.park], 'fill-opacity': 0.7 },
+      },
+      { id: 'water', type: 'fill', source: 'nways', 'source-layer': 'water', paint: { 'fill-color': c.water } },
+      {
+        id: 'buildings',
+        type: 'fill',
+        source: 'nways',
+        'source-layer': 'buildings',
+        minzoom: 14,
+        paint: { 'fill-color': c.building, 'fill-outline-color': c.buildingOutline },
+      },
+      {
+        id: 'paths',
+        type: 'line',
+        source: 'nways',
+        'source-layer': 'roads',
+        minzoom: 14,
+        filter: kindIs('path'),
+        paint: { 'line-color': c.path, 'line-width': 1, 'line-dasharray': [2, 1.5] },
+      },
+      ...road('roads-minor', ['minor_road', 'other'], c.minor, c.minorCasing, [[12, 0.5], [15, 3], [18, 12]], 11),
+      ...road('roads-major', ['major_road', 'medium_road'], c.major, c.majorCasing, [[8, 0.6], [12, 1.6], [15, 5], [18, 16]], 7),
+      ...road('roads-highway', ['highway'], c.highway, c.highwayCasing, [[5, 0.6], [10, 1.8], [14, 5], [18, 20]]),
+      {
+        id: 'boundaries',
+        type: 'line',
+        source: 'nways',
+        'source-layer': 'boundaries',
+        filter: kindIs('country', 'region'),
+        layout: { 'line-join': 'round' },
+        paint: { 'line-color': c.boundary, 'line-width': ['match', ['get', 'kind'], 'country', 1.4, 0.8], 'line-dasharray': [3, 2] },
+      },
+      {
+        id: 'water-labels',
+        type: 'symbol',
+        source: 'nways',
+        'source-layer': 'water',
+        minzoom: 10,
+        filter: ['has', 'name'],
+        layout: { 'text-field': name, 'text-font': FONT.italic, 'text-size': 12 },
+        paint: { 'text-color': c.waterLabel, 'text-halo-color': c.halo, 'text-halo-width': 1 },
+      },
+      {
+        id: 'road-labels',
+        type: 'symbol',
+        source: 'nways',
+        'source-layer': 'roads',
+        minzoom: 13,
+        filter: ['has', 'name'],
+        layout: {
+          'symbol-placement': 'line',
+          'text-field': name,
+          'text-font': FONT.medium,
+          'text-size': ['interpolate', ['linear'], ['zoom'], 13, 10, 18, 14],
+        },
+        paint: { 'text-color': c.labelMinor, 'text-halo-color': c.halo, 'text-halo-width': 1.5 },
+      },
+      {
+        id: 'place-labels',
+        type: 'symbol',
+        source: 'nways',
+        'source-layer': 'places',
+        // Each place from the zoom the tiles suggest, so towns don't crowd out cities.
+        filter: ['all', kindIs('locality', 'neighbourhood', 'region', 'country'), ['<=', ['to-number', ['get', 'min_zoom'], 0], ['+', ['zoom'], 1]]],
+        layout: {
+          'text-field': name,
+          'text-font': ['match', ['get', 'kind'], ['country', 'region'], ['literal', FONT.semibold], ['literal', FONT.medium]],
+          'text-size': ['match', ['get', 'kind'], 'country', 15, 'region', 13, 'neighbourhood', 11, 13],
+          'text-transform': ['match', ['get', 'kind'], ['country', 'region'], 'uppercase', 'none'],
+          'text-letter-spacing': ['match', ['get', 'kind'], ['country', 'region'], 0.08, 0],
+          'text-max-width': 8,
+        },
+        paint: {
+          'text-color': ['match', ['get', 'kind'], 'neighbourhood', c.labelMinor, c.label],
+          'text-halo-color': c.halo,
+          'text-halo-width': 1.5,
+        },
+      },
+    ],
+  }
+}