styled-map-package-api 5.0.0-pre.3 → 5.0.0-pre.4

package/lib/utils/style.js

@@ -0,0 +1,206 @@
+import { expressions, validateStyleMin } from '@maplibre/maplibre-gl-style-spec'
+
+/** @import {StyleSpecification, ExpressionSpecification, ValidationError} from '@maplibre/maplibre-gl-style-spec' */
+
+/**
+ * For a given style, replace all font stacks (`text-field` properties) with the
+ * provided fonts. If no matching font is found, the first font in the stack is
+ * used.
+ *
+ * *Modifies the input style object*
+ *
+ * @param {StyleSpecification} style
+ * @param {string[]} fonts
+ */
+export function replaceFontStacks(style, fonts) {
+  const mappedLayers = mapFontStacks(style.layers, (fontStack) => {
+    let match
+    for (const font of fontStack) {
+      if (fonts.includes(font)) {
+        match = font
+        break
+      }
+    }
+    return [match || fonts[0]]
+  })
+  style.layers = mappedLayers
+  return style
+}
+
+/**
+ * From given style layers, create a new style by calling the provided callback
+ * function on every font stack defined in the style.
+ *
+ * @param {StyleSpecification['layers']} layers
+ * @param {(fontStack: string[]) => string[]} callbackFn
+ * @returns {StyleSpecification['layers']}
+ */
+export function mapFontStacks(layers, callbackFn) {
+  return layers.map((layer) => {
+    if (layer.type !== 'symbol' || !layer.layout || !layer.layout['text-font'])
+      return layer
+    const textFont = layer.layout['text-font']
+    let mappedValue
+    if (isExpression(textFont)) {
+      mappedValue = mapArrayExpressionValue(textFont, callbackFn)
+    } else if (Array.isArray(textFont)) {
+      mappedValue = callbackFn(textFont)
+    } else {
+      // Deprecated property function, unsupported, but within this module
+      // functions will have been migrated to expressions anyway.
+      console.warn(
+        'Deprecated function definitions are not supported, font stack has not been transformed.',
+      )
+      console.dir(textFont, { depth: null })
+      return layer
+    }
+    return {
+      ...layer,
+      layout: {
+        ...layer.layout,
+        'text-font': mappedValue,
+      },
+    }
+  })
+}
+
+/**
+ * See https://github.com/maplibre/maplibre-style-spec/blob/c2f01dbaa6c5fb8409126258b9464b450018e939/src/expression/index.ts#L128
+ *
+ * @param {unknown} value
+ * @returns {value is ExpressionSpecification}
+ */
+function isExpression(value) {
+  return (
+    Array.isArray(value) &&
+    value.length > 0 &&
+    typeof value[0] === 'string' &&
+    value[0] in expressions
+  )
+}
+
+/**
+ * For an expression whose value is an array, map the array to a new array using
+ * the given callbackFn.
+ *
+ * @param {ExpressionSpecification} expression
+ * @param {(value: string[]) => string[]} callbackFn
+ * @returns {ExpressionSpecification}
+ */
+function mapArrayExpressionValue(expression, callbackFn) {
+  // This only works for properties whose value is an array, because it relies
+  // on the style specification that array values must be declared with the
+  // `literal` expression.
+  if (expression[0] === 'literal' && Array.isArray(expression[1])) {
+    return ['literal', callbackFn(expression[1])]
+  } else {
+    // @ts-ignore
+    return [
+      expression[0],
+      ...expression.slice(1).map(
+        // @ts-ignore
+        (x) => {
+          if (isExpression(x)) {
+            return mapArrayExpressionValue(x, callbackFn)
+          } else {
+            return x
+          }
+        },
+      ),
+    ]
+  }
+}
+
+/**
+ * PBF glyph ranges rendered client-side by MapLibre GL via
+ * `localIdeographFontFamily` (enabled by default as 'sans-serif'). SMP files
+ * do not need to include glyph data for these ranges. Each entry is a
+ * half-open interval [start, end) of PBF range start codepoints.
+ *
+ * Based on `codePointUsesLocalIdeographFontFamily()` in MapLibre GL JS.
+ * Only ranges where the ENTIRE 256-codepoint PBF range is locally rendered
+ * are listed here; partially-local ranges are conservatively kept as required.
+ */
+export const LOCAL_GLYPH_RANGES = [
+  [0x3000, 0x3400], // CJK Symbols, Hiragana, Katakana, Bopomofo, CJK Strokes, Enclosed CJK, CJK Compat
+  [0x3400, 0x4e00], // CJK Unified Ideographs Extension A
+  [0x4e00, 0xa000], // CJK Unified Ideographs
+  [0xa000, 0xa400], // Yi Syllables + Yi Radicals
+  [0xac00, 0xd800], // Hangul Syllables + Hangul Jamo Extended-B
+  [0xf900, 0xfb00], // CJK Compatibility Ideographs
+  [0xff00, 0x10000], // Halfwidth and Fullwidth Forms
+]
+
+/**
+ * Check whether a PBF glyph range (identified by its start codepoint) is
+ * rendered client-side by MapLibre GL and does not need a server-side PBF file.
+ * @param {number} rangeStart
+ * @returns {boolean}
+ */
+export function isLocallyRenderedRange(rangeStart) {
+  return LOCAL_GLYPH_RANGES.some(
+    ([start, end]) => rangeStart >= start && rangeStart < end,
+  )
+}
+
+/**
+ * @typedef {object} TileJSONPartial
+ * @property {string[]} tiles
+ * @property {string} [description]
+ * @property {string} [attribution]
+ * @property {object[]} [vector_layers]
+ * @property {import('./geo.js').BBox} [bounds]
+ * @property {number} [maxzoom]
+ * @property {number} [minzoom]
+ */
+
+/**
+ *
+ * @param {unknown} tilejson
+ * @returns {asserts tilejson is TileJSONPartial}
+ */
+export function assertTileJSON(tilejson) {
+  if (typeof tilejson !== 'object' || tilejson === null) {
+    throw new Error('Invalid TileJSON')
+  }
+  if (
+    !('tiles' in tilejson) ||
+    !Array.isArray(tilejson.tiles) ||
+    tilejson.tiles.length === 0 ||
+    tilejson.tiles.some((tile) => typeof tile !== 'string')
+  ) {
+    throw new Error('Invalid TileJSON: missing or invalid tiles property')
+  }
+}
+
+export const validateStyle =
+  /** @type {{ (style: unknown): style is StyleSpecification, errors: ValidationError[] }} */ (
+    (style) => {
+      validateStyle.errors = validateStyleMin(
+        /** @type {StyleSpecification} */ (style),
+      )
+      if (validateStyle.errors.length) return false
+      return true
+    }
+  )
+
+/**
+ * Check whether a source is already inlined (e.g. does not reference a TileJSON or GeoJSON url)
+ *
+ * @param {import('@maplibre/maplibre-gl-style-spec').SourceSpecification} source
+ * @returns {source is import('../types.js').InlinedSource}
+ */
+export function isInlinedSource(source) {
+  if (source.type === 'geojson') {
+    return typeof source.data === 'object'
+  } else if (
+    source.type === 'vector' ||
+    source.type === 'raster' ||
+    source.type === 'raster-dem'
+  ) {
+    return 'tiles' in source
+  } else {
+    // Video and image sources are not strictly "inlined", but we treat them as such.
+    return true
+  }
+}

package/lib/utils/templates.js

@@ -0,0 +1,165 @@
+export const URI_SCHEME = 'smp' // "Styled Map Package"
+export const URI_BASE = URI_SCHEME + '://maps.v1/'
+
+// These constants determine the file format structure
+export const VERSION_FILE = 'VERSION'
+export const FORMAT_VERSION = '1.0'
+export const STYLE_FILE = 'style.json'
+export const SOURCES_FOLDER = 's'
+const SPRITES_FOLDER = 'sprites'
+export const FONTS_FOLDER = 'fonts'
+
+// This must include placeholders `{z}`, `{x}`, `{y}`, since these are used to
+// define the tile URL, and this is a TileJSON standard.
+// The folder here is just `s` to minimize bytes used for filenames, which are
+// included in the header of every tile in the zip file.
+const TILE_FILE = SOURCES_FOLDER + '/{sourceId}/{z}/{x}/{y}{ext}'
+// The pixel ratio and ext placeholders must be at the end of the string with no
+// data between them, because this is the format defined in the MapLibre style spec.
+const SPRITE_FILE = SPRITES_FOLDER + '/{id}/sprite{pixelRatio}{ext}'
+// This must include placeholders `{fontstack}` and `{range}`, since these are
+// part of the MapLibre style spec.
+const GLYPH_FILE = FONTS_FOLDER + '/{fontstack}/{range}.pbf.gz'
+export const GLYPH_URI = URI_BASE + GLYPH_FILE
+
+const pathToResouceType = /** @type {const} */ ({
+  [TILE_FILE.split('/')[0] + '/']: 'tile',
+  [SPRITE_FILE.split('/')[0] + '/']: 'sprite',
+  [GLYPH_FILE.split('/')[0] + '/']: 'glyph',
+})
+
+/**
+ * @param {string} path
+ * @returns
+ */
+export function getResourceType(path) {
+  if (path === 'style.json') return 'style'
+  for (const [prefix, type] of Object.entries(pathToResouceType)) {
+    if (path.startsWith(prefix)) return type
+  }
+  throw new Error(`Unknown resource type for path: ${path}`)
+}
+
+/**
+ * Determine the content type of a file based on its extension.
+ *
+ * @param {string} path
+ */
+export function getContentType(path) {
+  if (path.endsWith('.json') || path.endsWith('.geojson'))
+    return 'application/json; charset=utf-8'
+  if (path.endsWith('.pbf.gz') || path.endsWith('.pbf'))
+    return 'application/x-protobuf'
+  if (path.endsWith('.png')) return 'image/png'
+  if (path.endsWith('.jpg')) return 'image/jpeg'
+  if (path.endsWith('.webp')) return 'image/webp'
+  if (path.endsWith('.mvt.gz') || path.endsWith('.mvt'))
+    return 'application/vnd.mapbox-vector-tile'
+  throw new Error(`Unknown content type for path: ${path}`)
+}
+
+/**
+ * Get the filename for a tile, given the TileInfo
+ *
+ * @param {import("type-fest").SetRequired<import("../writer.js").TileInfo, 'format'>} tileInfo
+ * @returns
+ */
+export function getTileFilename({ sourceId, z, x, y, format }) {
+  const ext = '.' + format + (format === 'mvt' ? '.gz' : '')
+  return replaceVariables(TILE_FILE, { sourceId, z, x, y, ext })
+}
+
+/**
+ * Get a filename for a sprite file, given the sprite id, pixel ratio and extension
+ *
+ * @param {{ id: string, pixelRatio: number, ext: '.json' | '.png'}} spriteInfo
+ */
+export function getSpriteFilename({ id, pixelRatio, ext }) {
+  return replaceVariables(SPRITE_FILE, {
+    id,
+    pixelRatio: getPixelRatioString(pixelRatio),
+    ext,
+  })
+}
+
+/**
+ * Get the filename for a glyph file, given the fontstack and range
+ *
+ * @param {object} options
+ * @param {string} options.fontstack
+ * @param {import("../writer.js").GlyphRange} options.range
+ */
+export function getGlyphFilename({ fontstack, range }) {
+  return replaceVariables(GLYPH_FILE, { fontstack, range })
+}
+
+/**
+ * Get the URI template for the sprites in the style
+ */
+export function getSpriteUri(id = 'default') {
+  return (
+    URI_BASE + replaceVariables(SPRITE_FILE, { id, pixelRatio: '', ext: '' })
+  )
+}
+
+/**
+ * Get the URI template for tiles in the style
+ *
+ * @param {object} opts
+ * @param {string} opts.sourceId
+ * @param {import("../writer.js").TileFormat} opts.format
+ * @returns
+ */
+export function getTileUri({ sourceId, format }) {
+  const ext = '.' + format + (format === 'mvt' ? '.gz' : '')
+  return (
+    URI_BASE + TILE_FILE.replace('{sourceId}', sourceId).replace('{ext}', ext)
+  )
+}
+
+/**
+ * @param {number} pixelRatio
+ */
+function getPixelRatioString(pixelRatio) {
+  return pixelRatio === 1 ? '' : `@${pixelRatio}x`
+}
+
+/**
+ * Replaces variables in a string with values provided in an object. Variables
+ * in the string are denoted by curly braces, e.g., {variableName}.
+ *
+ * @param {string} template - The string containing variables wrapped in curly braces.
+ * @param {Record<string, string | number>} variables - An object where the keys correspond to variable names and values correspond to the replacement values.
+ * @returns {string} The string with the variables replaced by their corresponding values.
+ */
+export function replaceVariables(template, variables) {
+  return template.replace(/{(.*?)}/g, (match, varName) => {
+    return varName in variables ? String(variables[varName]) : match
+  })
+}
+
+/**
+ * Inverse of {@link replaceVariables}. Converts a template string into a RegExp
+ * that captures the placeholder values. Only placeholders present in the
+ * `placeholders` map become named capture groups; unknown placeholders are
+ * treated as literal text and escaped.
+ *
+ * @param {string} template - The template string with `{name}` placeholders.
+ * @param {Record<string, string>} placeholders - Map of placeholder
+ *   name → regex pattern (e.g. `{ z: '\\d+' }`).
+ * @returns {RegExp} A RegExp with named capture groups for each known placeholder.
+ */
+export function templateToRegex(template, placeholders) {
+  const parts = template.split(/\{(\w+)\}/)
+  let pattern = ''
+  for (let i = 0; i < parts.length; i++) {
+    if (i % 2 === 0) {
+      pattern += parts[i].replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    } else if (parts[i] in placeholders) {
+      pattern += `(?<${parts[i]}>${placeholders[parts[i]]})`
+    } else {
+      pattern += `\\{${parts[i]}\\}`
+    }
+  }
+  return new RegExp(`^${pattern}$`)
+}