@deck.gl-community/basemap-layers 9.3.0-beta.2

package/src/index.ts

@@ -0,0 +1,3 @@
+/** Runtime exports for `@deck.gl-community/basemap-layers`. */
+export {BasemapLayer} from './basemap-layer';
+export {getBasemapLayers, getGlobeBaseLayers, getGlobeTopLayers} from './globe-layers';

package/src/map-style-loader.ts

@@ -0,0 +1,52 @@
+import type {LoaderContext, LoaderOptions, LoaderWithParser} from '@loaders.gl/loader-utils';
+import {ResolvedBasemapStyleSchema} from './map-style-schema';
+import {resolveBasemapStyle} from './style-resolver';
+import type {BasemapLoadOptions, BasemapStyle, ResolvedBasemapStyle} from './style-resolver';
+
+// __VERSION__ is injected by babel-plugin-version-inline
+// @ts-ignore TS2304: Cannot find name '__VERSION__'.
+const VERSION = typeof __VERSION__ !== 'undefined' ? __VERSION__ : 'latest';
+
+/** Namespaced loaders.gl options for {@link MapStyleLoader}. */
+export type MapStyleLoaderOptions = LoaderOptions & {
+  mapStyle?: NonNullable<BasemapLoadOptions>;
+};
+
+function getMapStyleLoadOptions(
+  options?: MapStyleLoaderOptions,
+  context?: LoaderContext
+): NonNullable<BasemapLoadOptions> {
+  return {
+    ...options?.mapStyle,
+    baseUrl: options?.mapStyle?.baseUrl || context?.url || context?.baseUrl,
+    fetch: options?.mapStyle?.fetch || (context?.fetch as typeof fetch | undefined)
+  };
+}
+
+/** loaders.gl-compatible loader that resolves and validates map-style documents. */
+export const MapStyleLoader = {
+  dataType: null as unknown as ResolvedBasemapStyle,
+  batchType: null as never,
+
+  name: 'Map Style',
+  id: 'map-style',
+  module: 'basemap-layers',
+  version: VERSION,
+  worker: false,
+  extensions: ['json'],
+  mimeTypes: ['application/json', 'application/vnd.mapbox.style+json'],
+  text: true,
+  options: {
+    mapStyle: {}
+  },
+  parse: async (
+    data: ArrayBuffer | string,
+    options?: MapStyleLoaderOptions,
+    context?: LoaderContext
+  ) => {
+    const text = typeof data === 'string' ? data : new TextDecoder().decode(data);
+    const style = JSON.parse(text) as BasemapStyle;
+    const resolved = await resolveBasemapStyle(style, getMapStyleLoadOptions(options, context));
+    return ResolvedBasemapStyleSchema.parse(resolved);
+  }
+} as const satisfies LoaderWithParser<ResolvedBasemapStyle, never, MapStyleLoaderOptions>;

package/src/map-style-schema.ts

@@ -0,0 +1,54 @@
+import {z} from 'zod';
+import type {
+  BasemapSource,
+  BasemapStyle,
+  BasemapStyleLayer,
+  ResolvedBasemapStyle
+} from './style-resolver';
+
+/** Zod schema for a basemap source entry. */
+export const BasemapSourceSchema = z
+  .object({
+    type: z.string().optional(),
+    url: z.string().optional(),
+    tiles: z.array(z.string()).optional(),
+    minzoom: z.number().optional(),
+    maxzoom: z.number().optional(),
+    tileSize: z.number().optional()
+  })
+  .catchall(z.unknown()) satisfies z.ZodType<BasemapSource>;
+
+/** Zod schema for a basemap style layer entry. */
+export const BasemapStyleLayerSchema = z
+  .object({
+    id: z.string(),
+    type: z.string(),
+    source: z.string().optional(),
+    'source-layer': z.string().optional(),
+    minzoom: z.number().optional(),
+    maxzoom: z.number().optional(),
+    filter: z.array(z.unknown()).optional(),
+    paint: z.record(z.string(), z.unknown()).optional(),
+    layout: z.record(z.string(), z.unknown()).optional()
+  })
+  .catchall(z.unknown()) satisfies z.ZodType<BasemapStyleLayer>;
+
+/** Zod schema for a MapLibre / Mapbox style document. */
+export const BasemapStyleSchema = z
+  .object({
+    version: z.number().optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+    sources: z.record(z.string(), BasemapSourceSchema).optional(),
+    layers: z.array(BasemapStyleLayerSchema).optional()
+  })
+  .catchall(z.unknown()) satisfies z.ZodType<BasemapStyle>;
+
+/** Zod schema for a fully resolved basemap style document. */
+export const ResolvedBasemapStyleSchema = z
+  .object({
+    version: z.number().optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+    sources: z.record(z.string(), BasemapSourceSchema),
+    layers: z.array(BasemapStyleLayerSchema)
+  })
+  .catchall(z.unknown()) satisfies z.ZodType<ResolvedBasemapStyle>;

package/src/map-style.ts

@@ -0,0 +1,18 @@
+/** Map-style helpers exported from `@deck.gl-community/basemap-layers/map-style`. */
+export {filterFeatures, findFeaturesStyledByLayer, parseProperties} from './mapbox-style';
+export {
+  BasemapSourceSchema,
+  BasemapStyleLayerSchema,
+  BasemapStyleSchema,
+  ResolvedBasemapStyleSchema
+} from './map-style-schema';
+export {MapStyleLoader} from './map-style-loader';
+export type {MapStyleLoaderOptions} from './map-style-loader';
+export {
+  resolveBasemapStyle,
+  type BasemapLoadOptions,
+  type BasemapSource,
+  type BasemapStyle,
+  type BasemapStyleLayer,
+  type ResolvedBasemapStyle
+} from './style-resolver';

package/src/mapbox-style.ts

@@ -0,0 +1,196 @@
+import {Color, expression, featureFilter, latest as Reference} from '@mapbox/mapbox-gl-style-spec';
+
+type GlobalProperties = {
+  zoom?: number;
+  [key: string]: unknown;
+};
+
+type GeometryLike = {
+  type: string;
+};
+
+type FeatureLike = {
+  type?: number | string;
+  geometry?: GeometryLike;
+  properties?: Record<string, unknown>;
+};
+
+type FilterFeaturesOptions = {
+  features: FeatureLike[];
+  filter: unknown[];
+  globalProperties?: GlobalProperties;
+};
+
+type FindFeaturesStyledByLayerOptions = {
+  features: Record<string, Record<string, FeatureLike[]>>;
+  layer: {
+    source?: string;
+    'source-layer'?: string;
+    filter?: unknown[];
+  };
+  globalProperties?: GlobalProperties;
+};
+
+type PropertyReference = Record<string, unknown> | null;
+
+type VisitedProperty = {
+  layer: Record<string, any>;
+  path: string[];
+  key: string;
+  value: unknown;
+  reference: PropertyReference;
+  set: (value: unknown) => void;
+};
+
+type VisitOptions = {
+  paint?: boolean;
+  layout?: boolean;
+};
+
+const GEOM_TYPES: Record<string, number> = {
+  Point: 1,
+  MultiPoint: 1,
+  LineString: 2,
+  MultiLineString: 2,
+  Polygon: 3,
+  MultiPolygon: 3
+};
+
+/**
+ * Applies a Mapbox style-spec filter expression to a set of features.
+ */
+export function filterFeatures({
+  features,
+  filter,
+  globalProperties = {}
+}: FilterFeaturesOptions): FeatureLike[] {
+  if (!features || features.length === 0) {
+    return [];
+  }
+
+  const filterFn = featureFilter(filter).filter;
+
+  return features.filter((feature) => {
+    if (![1, 2, 3].includes(Number(feature.type))) {
+      feature.type = GEOM_TYPES[feature.geometry?.type || ''] ?? feature.type;
+    }
+
+    return filterFn(globalProperties, feature);
+  });
+}
+
+/**
+ * Finds the source-layer features that participate in a particular style layer
+ * and applies the layer's filter expression when present.
+ */
+export function findFeaturesStyledByLayer({
+  features,
+  layer,
+  globalProperties
+}: FindFeaturesStyledByLayerOptions): FeatureLike[] {
+  const sourceLayerFeatures = features[layer.source || '']?.[layer['source-layer'] || ''];
+  if (!sourceLayerFeatures) {
+    return [];
+  }
+
+  if (layer.filter && layer.filter.length > 0) {
+    return filterFeatures({
+      features: sourceLayerFeatures,
+      filter: layer.filter,
+      globalProperties
+    });
+  }
+
+  return [];
+}
+
+/**
+ * Evaluates paint properties for a style layer at the requested zoom.
+ */
+export function parseProperties(
+  layer: Record<string, any>,
+  globalProperties: GlobalProperties
+): Array<Record<string, unknown>> {
+  const layerProperties: Array<Record<string, unknown>> = [];
+  visitProperties(layer, {paint: true}, (property) => {
+    layerProperties.push(parseProperty(property, globalProperties));
+  });
+
+  return layerProperties;
+}
+
+/**
+ * Walks layout and paint properties for a style layer.
+ */
+function visitProperties(
+  layer: Record<string, any>,
+  options: VisitOptions,
+  callback: (property: VisitedProperty) => void
+): void {
+  function inner(targetLayer: Record<string, any>, propertyType: 'paint' | 'layout') {
+    const properties = targetLayer[propertyType];
+    if (!properties) {
+      return;
+    }
+
+    Object.keys(properties).forEach((key) => {
+      callback({
+        layer: targetLayer,
+        path: [targetLayer.id, propertyType, key],
+        key,
+        value: properties[key],
+        reference: getPropertyReference(key),
+        set(value) {
+          properties[key] = value;
+        }
+      });
+    });
+  }
+
+  if (options.paint) {
+    inner(layer, 'paint');
+  }
+  if (options.layout) {
+    inner(layer, 'layout');
+  }
+}
+
+/**
+ * Resolves the style-spec reference metadata for a property name.
+ */
+function getPropertyReference(propertyName: string): PropertyReference {
+  for (let i = 0; i < Reference.layout.length; i++) {
+    for (const key in Reference[Reference.layout[i]]) {
+      if (key === propertyName) {
+        return Reference[Reference.layout[i]][key] as PropertyReference;
+      }
+    }
+  }
+
+  for (let i = 0; i < Reference.paint.length; i++) {
+    for (const key in Reference[Reference.paint[i]]) {
+      if (key === propertyName) {
+        return Reference[Reference.paint[i]][key] as PropertyReference;
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Evaluates a single style property expression.
+ */
+function parseProperty(
+  property: VisitedProperty,
+  globalProperties: GlobalProperties
+): Record<string, unknown> {
+  const exp = expression.normalizePropertyExpression(property.value, property.reference as any);
+  const result = exp.evaluate(globalProperties);
+
+  if (result instanceof Color) {
+    return {[property.key]: result.toArray()};
+  }
+
+  return {[property.key]: result};
+}

package/src/mvt-label-layer.ts

@@ -0,0 +1,269 @@
+import {CompositeLayer} from '@deck.gl/core';
+import type {UpdateParameters} from '@deck.gl/core';
+import {CollisionFilterExtension} from '@deck.gl/extensions';
+import {GeoJsonLayer, TextLayer} from '@deck.gl/layers';
+
+type GeometryType = 'Point' | 'MultiPoint' | 'LineString' | 'MultiLineString' | string;
+
+type FeatureGeometry = {
+  type: GeometryType;
+  coordinates: any;
+};
+
+type FeatureLike = {
+  geometry: FeatureGeometry;
+  properties?: Record<string, any>;
+};
+
+type LabelRow = {
+  position: number[];
+};
+
+type StyleLayerLike = {
+  layout?: Record<string, any>;
+};
+
+type LabelConfig = {
+  labels?: boolean;
+};
+
+/**
+ * Props accepted by {@link MVTLabelLayer}.
+ */
+export type MVTLabelLayerProps = {
+  /** Decoded vector-tile features or a feature-collection-like object. */
+  data?: {features?: FeatureLike[]} | FeatureLike[];
+  /** Label rendering enablement for the current basemap mode. */
+  config: LabelConfig;
+  /** Style layer that contributes label rules. */
+  styleLayer?: StyleLayerLike;
+  /** Zoom level used to resolve stop-based style values. */
+  zoom?: number;
+  /** Text fill color. */
+  textColor?: number[];
+  /** Optional text halo/background color. */
+  labelBackground?: number[] | null;
+  /** Text size units forwarded to `TextLayer`. */
+  labelSizeUnits?: 'pixels' | 'meters' | 'common';
+  /** Font family used by `TextLayer`. */
+  fontFamily?: string;
+  /** Enables billboard rendering in the text sublayer. */
+  billboard?: boolean;
+  /** When `true`, renders the source geometries for debugging. */
+  renderGeometry?: boolean;
+  /** Additional extension instances passed through to the text sublayer. */
+  extensions?: any[];
+  /** Active basemap mode. */
+  mode?: 'map' | 'globe';
+};
+
+type MVTLabelLayerState = {
+  /** Flattened label rows generated from the current tile data. */
+  labelData?: LabelRow[];
+};
+
+/**
+ * Evaluates a style value that may contain stop definitions.
+ */
+function evaluateStyleValue(value: unknown, zoom: number): unknown {
+  if (typeof value === 'number' || typeof value === 'string') {
+    return value;
+  }
+
+  if (value && typeof value === 'object' && Array.isArray((value as {stops?: unknown[]}).stops)) {
+    let resolved = (value as {stops: [number, unknown][]}).stops[0]?.[1];
+    for (const stop of (value as {stops: [number, unknown][]}).stops) {
+      if (zoom >= stop[0]) {
+        resolved = stop[1];
+      }
+    }
+    return resolved;
+  }
+
+  return value;
+}
+
+/**
+ * Replaces style-spec token placeholders in a label template.
+ */
+function resolveTokenString(template: unknown, properties?: Record<string, any>): string | null {
+  if (typeof template !== 'string') {
+    return null;
+  }
+
+  return template.replace(/\{([^}]+)\}/g, (_, token) => {
+    const value = properties?.[token];
+    return value === null || value === undefined ? '' : String(value);
+  });
+}
+
+/**
+ * Returns a midpoint for a line geometry.
+ */
+function getLineMidpoint(coordinates: number[][]): number[] | null {
+  if (!Array.isArray(coordinates) || coordinates.length === 0) {
+    return null;
+  }
+
+  return coordinates[Math.floor(coordinates.length / 2)] || coordinates[0] || null;
+}
+
+/**
+ * Returns a coarse collision priority for a label feature.
+ */
+function getCollisionPriority(feature: FeatureLike): number {
+  const properties = feature?.properties || {};
+
+  if (properties.capital > 0 || properties.class === 'country') {
+    return 1000;
+  }
+  if (properties.class === 'state' || properties.class === 'city') {
+    return 750;
+  }
+  if (properties.layerName === 'water_name' || properties.layerName === 'waterway') {
+    return 400;
+  }
+
+  return 100;
+}
+
+/**
+ * Renders label text for decoded vector-tile features, with optional geometry
+ * passthrough for debugging.
+ */
+export class MVTLabelLayer extends CompositeLayer<MVTLabelLayerProps> {
+  /** Deck.gl layer name. */
+  static layerName = 'MVTLabelLayer';
+
+  /** Default props for {@link MVTLabelLayer}. */
+  static defaultProps = {
+    ...GeoJsonLayer.defaultProps,
+    billboard: true,
+    renderGeometry: false,
+    labelSizeUnits: 'pixels',
+    labelBackground: {type: 'color', value: null, optional: true},
+    fontFamily: 'Monaco, monospace'
+  };
+
+  /** Current label-row state. */
+  state: MVTLabelLayerState = undefined!;
+
+  /**
+   * Extracts the visible label text for a decoded feature.
+   */
+  getLabel(feature: FeatureLike): string | undefined {
+    const {styleLayer, zoom = 0} = this.props;
+    const textField = evaluateStyleValue(styleLayer?.layout?.['text-field'], zoom);
+    const label = resolveTokenString(textField, feature.properties)?.trim();
+    return label || undefined;
+  }
+
+  /**
+   * Returns the font size for a decoded feature label.
+   */
+  getLabelSize(_feature: FeatureLike): number {
+    const {styleLayer, zoom = 0} = this.props;
+    return Number(evaluateStyleValue(styleLayer?.layout?.['text-size'], zoom) || 14);
+  }
+
+  /**
+   * Returns the text color for a decoded feature label.
+   */
+  getLabelColor(_feature: FeatureLike): number[] {
+    return this.props.textColor || [255, 255, 255];
+  }
+
+  /**
+   * Extracts candidate label anchor positions from a feature geometry.
+   */
+  getLabelAnchors(feature: FeatureLike): number[][] {
+    const {type, coordinates} = feature.geometry;
+    switch (type) {
+      case 'Point':
+        return [coordinates];
+      case 'MultiPoint':
+        return coordinates;
+      case 'LineString': {
+        const midpoint = getLineMidpoint(coordinates);
+        return midpoint ? [midpoint] : [];
+      }
+      case 'MultiLineString': {
+        const midpoint = getLineMidpoint(coordinates[0]);
+        return midpoint ? [midpoint] : [];
+      }
+      default:
+        return [];
+    }
+  }
+
+  /**
+   * Recomputes label anchor rows when the source tile data changes.
+   */
+  updateState({changeFlags}: UpdateParameters<this>): void {
+    const {data} = this.props;
+    if (changeFlags.dataChanged && data) {
+      const features = Array.isArray(data) ? data : data.features || [];
+      const labelData = features.flatMap((feature, index) => {
+        const labelAnchors = this.getLabelAnchors(feature);
+        return labelAnchors.map((position) => this.getSubLayerRow({position}, feature, index));
+      });
+
+      this.setState({labelData});
+    }
+  }
+
+  /**
+   * Renders the optional debug geometry and the text labels.
+   */
+  renderLayers(): any {
+    const {config, labelSizeUnits, labelBackground, billboard, renderGeometry} = this.props;
+    const layers: any[] = [];
+
+    if (renderGeometry) {
+      layers.push(
+        new GeoJsonLayer({
+          ...this.props,
+          ...this.getSubLayerProps({id: 'geojson'}),
+          data: this.props.data
+        })
+      );
+    }
+
+    if (config.labels) {
+      const hasBackground = Array.isArray(labelBackground) && labelBackground.length >= 3;
+      layers.push(
+        new TextLayer({
+          ...this.getSubLayerProps({id: 'text'}),
+          data: this.state.labelData,
+          extensions: [...(this.props.extensions || []), new CollisionFilterExtension()],
+          parameters: {
+            depthTest: false
+          },
+          billboard,
+          characterSet: 'auto',
+          collisionEnabled: true,
+          collisionGroup: 'basemap-labels',
+          getCollisionPriority: this.getSubLayerAccessor((feature: FeatureLike) =>
+            getCollisionPriority(feature)
+          ) as any,
+          fontFamily: this.props.fontFamily,
+          sizeUnits: labelSizeUnits,
+          background: hasBackground,
+          getBackgroundColor: (hasBackground ? labelBackground : [0, 0, 0, 0]) as any,
+          getPosition: (d: LabelRow) => d.position,
+          getText: this.getSubLayerAccessor((feature: FeatureLike) =>
+            this.getLabel(feature)
+          ) as any,
+          getSize: this.getSubLayerAccessor((feature: FeatureLike) =>
+            this.getLabelSize(feature)
+          ) as any,
+          getColor: this.getSubLayerAccessor((feature: FeatureLike) =>
+            this.getLabelColor(feature)
+          ) as any
+        })
+      );
+    }
+
+    return layers;
+  }
+}