ts-maps 0.3.1 → 0.3.3

package/dist/core-map/style-spec/schema.d.ts

@@ -209,6 +209,47 @@ declare const symbolPaint: Record<string, PropertySchema>;
  * ```
  */
 declare const rasterPaint: Record<string, PropertySchema>;
+/**
+ * @defaultValue
+ * ```ts
+ * {
+ *   'hillshade-illumination-direction': { type: 'number', default: 335, minimum: 0, maximum: 359, sdk: 'gl' },
+ *   'hillshade-illumination-anchor': { type: 'enum', values: ['map', 'viewport'], default: 'viewport', sdk: 'gl' },
+ *   'hillshade-exaggeration': {
+ *     type: 'number',
+ *     default: 0.5,
+ *     minimum: 0,
+ *     maximum: 1,
+ *     transition: true,
+ *     sdk: 'gl'
+ *   },
+ *   'hillshade-shadow-color': { type: 'color', default: '#000000', transition: true, sdk: 'gl' },
+ *   'hillshade-highlight-color': { type: 'color', default: '#FFFFFF', transition: true, sdk: 'gl' },
+ *   'hillshade-accent-color': { type: 'color', default: '#000000', transition: true, sdk: 'gl' }
+ * }
+ * ```
+ */
+declare const hillshadePaint: Record<string, PropertySchema>;
+/**
+ * @defaultValue
+ * ```ts
+ * {
+ *   'heatmap-radius': { type: 'number', default: 30, minimum: 1, transition: true, sdk: 'gl' },
+ *   'heatmap-weight': { type: 'number', default: 1, minimum: 0, sdk: 'gl' },
+ *   'heatmap-intensity': { type: 'number', default: 1, minimum: 0, transition: true, sdk: 'gl' },
+ *   'heatmap-color': { type: 'color', sdk: 'gl' },
+ *   'heatmap-opacity': {
+ *     type: 'number',
+ *     default: 1,
+ *     minimum: 0,
+ *     maximum: 1,
+ *     transition: true,
+ *     sdk: 'gl'
+ *   }
+ * }
+ * ```
+ */
+declare const heatmapPaint: Record<string, PropertySchema>;
 export declare const paintPropertySchemas: Record<LayerType, Record<string, PropertySchema>>;
 // ---------- layout ----------
 declare const visibility: PropertySchema;
@@ -350,12 +391,11 @@ declare const circleLayout: Record<string, PropertySchema>;
  */
 declare const symbolLayout: Record<string, PropertySchema>;
 declare const rasterLayout: Record<string, PropertySchema>;
+declare const hillshadeLayout: Record<string, PropertySchema>;
+declare const heatmapLayout: Record<string, PropertySchema>;
 export declare const layoutPropertySchemas: Record<LayerType, Record<string, PropertySchema>>;
 // The set of known layer types — exported separately so the validator can
 // decide whether an unknown layer `type` is user error vs. an SDK mismatch.
-// `hillshade` and `heatmap` are intentionally excluded — their renderers
-// ship as standalone classes (`HillshadeLayer`, `HeatmapLayer`) rather
-// than through the style-spec path.
 export declare const layerTypes: readonly LayerType[];
 // Source types we currently recognise in the validator.
 export declare const sourceTypes: readonly string[];

package/dist/core-map/style-spec/types.d.ts

@@ -26,6 +26,7 @@ export declare interface VectorSourceSpecification {
   attribution?: string
   promoteId?: PromoteIdSpecification
   volatile?: boolean
+  offlineCache?: boolean
 }
 export declare interface RasterSourceSpecification {
   type: 'raster'
@@ -38,6 +39,7 @@ export declare interface RasterSourceSpecification {
   scheme?: 'xyz' | 'tms'
   attribution?: string
   volatile?: boolean
+  offlineCache?: boolean
 }
 export declare interface RasterDEMSourceSpecification {
   type: 'raster-dem'
@@ -308,6 +310,45 @@ export declare interface RasterLayerSpecification {
   layout?: RasterLayoutSpecification
   paint?: RasterPaintSpecification
 }
+// ---------- hillshade ----------
+export declare interface HillshadePaintSpecification {
+  'hillshade-illumination-direction'?: PropertyValueSpecification<number>
+  'hillshade-illumination-anchor'?: 'map' | 'viewport'
+  'hillshade-exaggeration'?: PropertyValueSpecification<number>
+  'hillshade-shadow-color'?: PropertyValueSpecification<string>
+  'hillshade-highlight-color'?: PropertyValueSpecification<string>
+  'hillshade-accent-color'?: PropertyValueSpecification<string>
+}
+export declare interface HillshadeLayerSpecification {
+  id: string
+  type: 'hillshade'
+  metadata?: Record<string, unknown>
+  source: string
+  minzoom?: number
+  maxzoom?: number
+  layout?: { visibility?: 'visible' | 'none' }
+  paint?: HillshadePaintSpecification
+}
+// ---------- heatmap ----------
+export declare interface HeatmapPaintSpecification {
+  'heatmap-radius'?: PropertyValueSpecification<number>
+  'heatmap-weight'?: PropertyValueSpecification<number>
+  'heatmap-intensity'?: PropertyValueSpecification<number>
+  'heatmap-color'?: unknown
+  'heatmap-opacity'?: PropertyValueSpecification<number>
+}
+export declare interface HeatmapLayerSpecification {
+  id: string
+  type: 'heatmap'
+  metadata?: Record<string, unknown>
+  source: string
+  'source-layer'?: string
+  minzoom?: number
+  maxzoom?: number
+  filter?: unknown
+  layout?: { visibility?: 'visible' | 'none' }
+  paint?: HeatmapPaintSpecification
+}
 // ---------- root style ----------
 export declare interface Style {
   version: 8
@@ -359,17 +400,16 @@ export type LayerType = | 'background'
   | 'line'
   | 'circle'
   | 'symbol'
-  | 'raster';
+  | 'raster'
+  | 'hillshade'
+  | 'heatmap';
 // ---------- layer union ----------
-//
-// Note: `hillshade` and `heatmap` Mapbox layer types are NOT part of the
-// style-spec union because the runtime doesn't render them through the
-// style-spec path. Use `HillshadeLayer` (`RasterDEMLayer`) and
-// `HeatmapLayer` as ordinary layer instances via `layer.addTo(map)`.
 export type LayerSpecification = | BackgroundLayerSpecification
   | FillLayerSpecification
   | FillExtrusionLayerSpecification
   | LineLayerSpecification
   | CircleLayerSpecification
   | SymbolLayerSpecification
-  | RasterLayerSpecification;
+  | RasterLayerSpecification
+  | HillshadeLayerSpecification
+  | HeatmapLayerSpecification;

package/dist/core-map/styles/basemap.d.ts

@@ -0,0 +1,41 @@
+import type { Palette } from './palette';
+import type { Style as StyleSpec } from '../style-spec/types';
+/** The dark basemap. Pair it with `theme: 'dark'` so the chrome matches. */
+export declare function dark(options: BasemapStyleOptions): StyleSpec;
+/** The light basemap. The default `theme: 'light'` chrome already matches. */
+export declare function light(options: BasemapStyleOptions): StyleSpec;
+/**
+ * Built-in basemap styles.
+ *
+ * These are functions rather than constants because ts-maps ships no tile
+ * service: a style is only meaningful once it is pointed at a source. Call
+ * `styles.dark({ tiles })` with a vector tile URL and you get a complete
+ * StyleSpec; the palette, layer order and zoom ramps are the parts worth not
+ * hand-writing.
+ *
+ * Layer names default to the OpenMapTiles schema, which is what the keyless
+ * public services publish (OpenFreeMap, MapTiler, a self-hosted Tileserver
+ * GL). A source using different names — Mapbox Streets, say — is accommodated
+ * by `sourceLayers` rather than by forking the style.
+ */
+export declare interface BasemapStyleOptions {
+  tiles: string | string[]
+  mode?: 'vector' | 'raster'
+  attribution?: string
+  minzoom?: number
+  maxzoom?: number
+  tileSize?: number
+  sourceLayers?: Partial<Record<SourceLayerKey, string>>
+  palette?: Partial<Palette>
+  name?: string
+  glyphs?: string
+  sprite?: string
+}
+export type SourceLayerKey = | 'water'
+    | 'landcover'
+    | 'landuse'
+    | 'building'
+    | 'transportation'
+    | 'transportationName'
+    | 'boundary'
+    | 'place';

package/dist/core-map/styles/index.d.ts

@@ -0,0 +1,5 @@
+export type { BasemapStyleOptions, SourceLayerKey } from './basemap';
+export type { Palette } from './palette';
+// Built-in basemap styles. See `basemap.ts` for why these are functions.
+export { dark, light } from './basemap';
+export { DARK, LIGHT } from './palette';

package/dist/core-map/styles/palette.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Dark palette, tuned for data on top.
+ *
+ * Roads sit close to the background rather than reading as bright lines: on a
+ * dark incident or fleet map the overlay is the subject, and a road network at
+ * high contrast competes with it. Water is desaturated navy rather than blue
+ * for the same reason — it should read as "not land" without pulling the eye.
+ */
+export declare const DARK: Palette;
+/** Light palette: a clean neutral street style, same skeleton. */
+export declare const LIGHT: Palette;
+// The two palettes the built-in styles are cut from.
+//
+// Light and dark share one layer skeleton (see `basemap.ts`) and differ only
+// in this table, so a colour added to one is a compile error until it exists
+// in the other. That is the whole point: the usual way a pair of themes drifts
+// is one of them quietly gaining a layer the other never got.
+export declare interface Palette {
+  background: string
+  land: string
+  green: string
+  water: string
+  roadMajor: string
+  roadMinor: string
+  roadCasing: string
+  buildings: string
+  boundary: string
+  label: string
+  labelHalo: string
+  labelMuted: string
+}

package/dist/core-map/symbols/CollisionIndex.d.ts

@@ -1,21 +1,38 @@
-// CollisionIndex — uniform grid collision detector for symbol placement.
-// Each inserted box is bucketed into every cell it overlaps; `tryInsert`
-// rejects when a colliding neighbour has priority >= the new box's.
+// CollisionIndex — sparse spatial hash for symbol placement.
+//
+// Boxes are bucketed into every cell they overlap; `tryInsert` rejects when a
+// colliding neighbour has priority >= the new box's.
+//
+// The grid is sparse and unbounded rather than a fixed cols×rows array, which
+// is what lets one index span the whole viewport instead of a single tile.
+// A per-tile index cannot see across a tile seam, so two halves of the same
+// street name, or two towns either side of an edge, would each place happily
+// and then overlap on screen. Callers now insert in world-pixel coordinates
+// and share one index across every tile at a zoom level.
+//
+// Because tiles are drawn, discarded on pan, and drawn again, every box may
+// carry an `owner` — the tile that placed it. `removeOwner` drops that tile's
+// boxes before it redraws, so a tile never collides with the ghosts of its own
+// previous placement.
 export declare interface CollisionBox {
   minX: number
   minY: number
   maxX: number
   maxY: number
   priority?: number
+  owner?: string
 }
 export declare interface CollisionIndexOptions {
-  width: number
-  height: number
   cellSize?: number
+  width?: number
+  height?: number
 }
 export declare class CollisionIndex {
   constructor(opts?: CollisionIndexOptions);
+  hits(box: CollisionBox): boolean;
   tryInsert(box: CollisionBox): boolean;
   insert(box: CollisionBox): void;
+  removeOwner(owner: string): void;
   clear(): void;
+  get size(): number;
 }

package/dist/core-map/symbols/GlyphAtlas.d.ts

@@ -25,7 +25,11 @@ export declare class GlyphAtlas {
   canvas: HTMLCanvasElement;
   constructor(opts?: GlyphAtlasOptions);
   getOrAddGlyph(codePoint: number, style?: { italic?: boolean, bold?: boolean }): GlyphMetrics;
-  measure(text: string, style?: { italic?: boolean, bold?: boolean }): { width: number, height: number };
+  measure(text: string, style?: { italic?: boolean, bold?: boolean, family?: string }): { width: number, height: number };
+  advances(text: string, size: number, style?: { italic?: boolean, bold?: boolean, family?: string }): Array<{ char: string, advance: number }>;
+  measureText(text: string, size: number, style?: { italic?: boolean, bold?: boolean, family?: string }): { width: number, height: number, ascent: number, descent: number };
+  fontString(size: number, style?: { italic?: boolean, bold?: boolean, family?: string }): string;
+  resolveFont(textFont: string | string[] | undefined): { family: string, bold: boolean, italic: boolean };
   drawText(ctx: CanvasRenderingContext2D, text: string, x: number, y: number, options: {
       color: string
       haloColor?: string
@@ -33,6 +37,7 @@ export declare class GlyphAtlas {
       size: number
       italic?: boolean
       bold?: boolean
+      family?: string
     }): void;
   _buildSDF(imageData: ImageData): ImageData;
 }

package/dist/core-map/symbols/GlyphProvider.d.ts

@@ -0,0 +1,21 @@
+import { GlyphBitmapCache } from './GlyphRenderer';
+import type { Glyph, GlyphSource } from './loadGlyphs';
+/**
+ * A font stack as the server names it.
+ *
+ * Glyph URLs take a comma-separated stack — `"Noto Sans Regular,Arial Unicode
+ * MS Regular"` — which is also a serviceable cache key.
+ */
+export declare function stackKey(fontStack: string | string[] | undefined): string;
+export declare interface GlyphProviderOptions {
+  source: GlyphSource
+  isFontAvailable: (fontStack: string | string[] | undefined) => boolean
+  onLoad: () => void
+}
+export declare class GlyphProvider {
+  cache: GlyphBitmapCache;
+  constructor(options: GlyphProviderOptions);
+  needsServer(fontStack: string | string[] | undefined): boolean;
+  glyphs(fontStack: string | string[] | undefined, text: string): Glyph[] | null;
+  invalidate(): void;
+}

package/dist/core-map/symbols/GlyphRenderer.d.ts

@@ -0,0 +1,48 @@
+import type { Glyph, GlyphRange } from './loadGlyphs';
+/**
+ * Look glyphs up for a run of text.
+ *
+ * Returns `null` if any character's range has not been loaded, because a label
+ * drawn with holes in it is worse than a label that appears a moment later.
+ * The caller's job on `null` is to request the ranges and redraw.
+ */
+export declare function glyphsFor(range: (codePoint: number) => Glyph | undefined, text: string): Glyph[] | null;
+/** Measure a run laid out from server glyphs. */
+export declare function measureGlyphs(glyphs: Glyph[], size: number): GlyphTextMetrics;
+/**
+ * Draw a run of server glyphs with `x` at its left edge and `y` on its
+ * baseline — the same contract as the canvas text path, so a caller does not
+ * have to know which one it got.
+ */
+export declare function drawGlyphs(ctx: CanvasRenderingContext2D, glyphs: Glyph[], x: number, y: number, options: GlyphDrawOptions, cache?: GlyphBitmapCache): void;
+/** Colour one glyph's field into a bitmap ready to blit. */
+export declare function renderGlyphBitmap(glyph: Glyph, options: GlyphDrawOptions): HTMLCanvasElement | null;
+/** A `GlyphRange` as the lookup `glyphsFor` wants. */
+export declare function rangeLookup(ranges: GlyphRange[]): (codePoint: number) => Glyph | undefined;
+/** The em size Mapbox's glyph generator rasterises at. */
+export declare const GLYPH_EM: 24;
+export declare interface GlyphDrawOptions {
+  size: number
+  color: string
+  haloColor?: string
+  haloWidth?: number
+}
+export declare interface GlyphTextMetrics {
+  width: number
+  height: number
+  ascent: number
+  descent: number
+}
+/**
+ * Coloured glyph bitmaps, keyed by glyph and appearance.
+ *
+ * A label is redrawn on every pan and zoom, and the same few hundred glyphs
+ * recur across every tile on screen; colouring each field per frame would be
+ * the most expensive thing the renderer does.
+ */
+export declare class GlyphBitmapCache {
+  constructor(limit?: number);
+  get(glyph: Glyph, options: GlyphDrawOptions): HTMLCanvasElement | null;
+  clear(): void;
+  get size(): number;
+}

package/dist/core-map/symbols/IconAtlas.d.ts

@@ -8,11 +8,20 @@ export declare interface SpriteEntry {
   width: number
   height: number
   pixelRatio?: number
+  sdf?: boolean
+}
+export declare interface DrawIconOptions {
+  size?: number
+  rotation?: number
+  color?: string
+  opacity?: number
+  haloColor?: string
+  haloWidth?: number
 }
 export declare class IconAtlas {
   canvas: HTMLCanvasElement;
   constructor();
   addSprite(entry: SpriteEntry, source: HTMLImageElement | HTMLCanvasElement | ImageData): void;
   get(id: string): SpriteEntry | undefined;
-  drawIcon(ctx: CanvasRenderingContext2D, id: string, dx: number, dy: number, opts?: { size?: number, rotation?: number }): void;
+  drawIcon(ctx: CanvasRenderingContext2D, id: string, dx: number, dy: number, opts?: DrawIconOptions): void;
 }

package/dist/core-map/symbols/SymbolOverlay.d.ts

@@ -0,0 +1,47 @@
+import type { CollisionIndex } from './CollisionIndex';
+/**
+ * The canvas labels are drawn on, above the tiles rather than inside them.
+ *
+ * Symbols used to be painted into each tile's own canvas, which had three
+ * consequences worth undoing:
+ *
+ *   - **WebGL tiles had no labels at all.** A canvas bound to a WebGL context
+ *     cannot also hand out a 2D context, so the symbol pass was skipped
+ *     entirely — you opted into the faster renderer and silently lost every
+ *     piece of text on the map.
+ *   - **Rotation was baked in.** Placement happened once, when the tile was
+ *     drawn, so turning the map carried the labels round with it: text upside
+ *     down at a bearing of 180, and collision boxes still computed for north.
+ *   - **Labels stopped at tile edges**, because a tile can only draw inside
+ *     itself however wide the collision index's view is.
+ *
+ * One viewport-sized canvas fixes all three. It lives in the map's own
+ * `symbolPane`, which sits above the tiles and below markers and popups — a
+ * marker should never end up behind a street name — and which the map
+ * counter-rotates, so placement is done in screen space and glyphs stay
+ * upright however the map is turned.
+ *
+ * Redrawing happens at settled moments: the end of a pan, a zoom, a rotation,
+ * or when tiles arrive. In between the pane carries the canvas along with the
+ * map, so labels stay stuck to the ground without re-placing hundreds of them
+ * every frame.
+ */
+export declare interface SymbolOverlayHost {
+  drawSymbols: (ctx: CanvasRenderingContext2D, collision: CollisionIndex) => void
+  createCollisionIndex: () => CollisionIndex
+}
+export declare class SymbolOverlay {
+  canvas: HTMLCanvasElement | null;
+  _map: any;
+  _host: SymbolOverlayHost;
+  _ratio: number;
+  _frame: number | null;
+  constructor(map: any, host: SymbolOverlayHost);
+  _attach(): void;
+  _pixelRatio(): number;
+  _resize(): void;
+  _position(): void;
+  schedule(): void;
+  redraw(): void;
+  remove(): void;
+}

package/dist/core-map/symbols/index.d.ts

@@ -1,6 +1,10 @@
 export type { CollisionBox, CollisionIndexOptions } from './CollisionIndex';
 export type { GlyphAtlasOptions, GlyphMetrics } from './GlyphAtlas';
 export type { SpriteEntry } from './IconAtlas';
+export type { Glyph, GlyphRange, LoadGlyphsOptions } from './loadGlyphs';
+export type { LoadedSprite, LoadSpriteOptions, SpriteIndex, SpriteIndexEntry } from './loadSprite';
 export { CollisionIndex } from './CollisionIndex';
 export { GlyphAtlas } from './GlyphAtlas';
 export { IconAtlas } from './IconAtlas';
+export { decodeGlyphPbf, GLYPH_BORDER, GlyphSource, glyphUrl, rangeStartFor } from './loadGlyphs';
+export { addSpriteToAtlas, loadSprite, spriteUrl } from './loadSprite';