ts-maps 0.3.2 → 0.3.3

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

@@ -0,0 +1,53 @@
+/** Fill `{fontstack}` and `{range}` in a glyphs template. */
+export declare function glyphUrl(template: string, fontstack: string, rangeStart: number): string;
+/** The 256-codepoint block a character falls in. */
+export declare function rangeStartFor(codePoint: number): number;
+/** Decode one `glyphs.proto` message. */
+export declare function decodeGlyphPbf(bytes: Uint8Array): GlyphRange;
+/** The border Mapbox bakes around each glyph's distance field. */
+export declare const GLYPH_BORDER: 3;
+/**
+ * Load a style's glyph ranges.
+ *
+ * A style points at glyphs with a template — `"glyphs":
+ * "https://example.com/fonts/{fontstack}/{range}.pbf"` — serving signed
+ * distance fields in 256-codepoint blocks. ts-maps rasterises text from system
+ * fonts, which is sharper on a 2D canvas and needs no network at all, so this
+ * is not how labels are drawn. What it is for is the case that cannot be
+ * served locally: a style whose typeface the viewer does not have installed.
+ *
+ * Ranges are fetched on demand and cached, because a stack is 65,536 code
+ * points and a map shows a handful of blocks.
+ *
+ * Wire format (Mapbox `glyphs.proto`):
+ *   1 fontstack { 1 name, 2 range, 3 glyph { 1 id, 2 bitmap, 3 width,
+ *                 4 height, 5 left, 6 top, 7 advance } }
+ */
+export declare interface Glyph {
+  id: number
+  bitmap?: Uint8Array
+  width: number
+  height: number
+  left: number
+  top: number
+  advance: number
+}
+export declare interface LoadGlyphsOptions {
+  signal?: AbortSignal
+  fetch?: typeof globalThis.fetch
+}
+export type GlyphRange = Map<number, Glyph>;
+/**
+ * Fetches glyph ranges and remembers them.
+ *
+ * One instance per map. A range in flight is shared rather than fetched twice,
+ * which matters when several tiles decode at once and all want the same block.
+ */
+export declare class GlyphSource {
+  constructor(template: string, options?: LoadGlyphsOptions);
+  get(fontstack: string, codePoint: number): Glyph | undefined;
+  has(fontstack: string, codePoint: number): boolean;
+  load(fontstack: string, codePoint: number, signal?: AbortSignal): Promise<GlyphRange>;
+  loadForText(fontstack: string, text: string, signal?: AbortSignal): Promise<void>;
+  get size(): number;
+}

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

@@ -0,0 +1,57 @@
+import type { IconAtlas } from './IconAtlas';
+/** `base` → `base@2x.png`, keeping any query string where it belongs. */
+export declare function spriteUrl(base: string, extension: 'json' | 'png', pixelRatio: number): string;
+/**
+ * Fetch the index and sheet for a sprite base URL.
+ *
+ * Falls back from `@2x` to 1x when the high-density sheet is missing, so a
+ * style that only publishes one density still works on a retina screen.
+ */
+export declare function loadSprite(base: string, options?: LoadSpriteOptions): Promise<LoadedSprite>;
+/**
+ * Push a loaded sprite's icons into an atlas.
+ *
+ * Entries carry their own `pixelRatio` in Mapbox's format; where one is
+ * missing the sheet's density stands in, so a `@2x` sheet does not render at
+ * double size.
+ *
+ * `prefix` namespaces the ids, for the multi-sheet form of `sprite`.
+ */
+export declare function addSpriteToAtlas(atlas: IconAtlas, sprite: LoadedSprite, prefix?: string): number;
+/**
+ * Load a style's sprite sheet.
+ *
+ * A style document points at a sprite with a base URL and no extension —
+ * `"sprite": "https://example.com/sprites/basic"` — from which two files are
+ * derived: a JSON index of named icons and a PNG holding their pixels. Until
+ * now `IconAtlas` required the caller to supply both by hand, which meant
+ * `icon-image` did nothing for any real-world style.
+ *
+ * Retina sheets follow the `@2x` convention. The higher-density sheet is
+ * preferred where the display can use it and quietly skipped where it cannot
+ * be fetched, because a style is not obliged to publish one.
+ */
+/** The shape of an entry in a sprite JSON index. */
+export declare interface SpriteIndexEntry {
+  x: number
+  y: number
+  width: number
+  height: number
+  pixelRatio?: number
+  sdf?: boolean
+  content?: [number, number, number, number]
+  stretchX?: Array<[number, number]>
+  stretchY?: Array<[number, number]>
+}
+export declare interface LoadSpriteOptions {
+  pixelRatio?: number
+  signal?: AbortSignal
+  fetch?: typeof globalThis.fetch
+  loadImage?: (url: string) => Promise<CanvasImageSource & { width: number, height: number }>
+}
+export declare interface LoadedSprite {
+  index: SpriteIndex
+  image: CanvasImageSource & { width: number, height: number }
+  pixelRatio: number
+}
+export type SpriteIndex = Record<string, SpriteIndexEntry>;

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

@@ -0,0 +1,67 @@
+/**
+ * Where the text box's top-left corner goes, relative to the anchor point.
+ *
+ * `text-anchor` names the part of the label that touches the anchor, so
+ * `'left'` puts the label's left edge on the point and the text runs to the
+ * right — the opposite of what the name suggests at first glance.
+ */
+export declare function anchorOffset(anchor: TextAnchor, width: number, height: number): Vec;
+/** Normalise `text-offset` (ems, [x, y]) into pixels at a given text size. */
+export declare function offsetPixels(offset: unknown, textSize: number): Vec;
+/**
+ * The axis-aligned box covering a rectangle rotated about a point.
+ *
+ * Collision uses axis-aligned boxes, so a rotated label needs the bounds of
+ * its rotated corners rather than its unrotated ones — otherwise a label at
+ * 45° reserves a box far smaller than the ink it actually lays down.
+ */
+export declare function rotatedBounds(x: number, y: number, width: number, height: number, angle: number, originX?: number, originY?: number): { minX: number, minY: number, maxX: number, maxY: number };
+/** Total length of a polyline. */
+export declare function lineLength(line: Vec[]): number;
+/** The point and tangent angle at a distance along a polyline, or null past its end. */
+export declare function pointAtDistance(line: Vec[], distance: number): (Vec & { angle: number }) | null;
+/**
+ * Lay glyphs along a line, one per advance, each rotated to the local tangent.
+ *
+ * Returns null when the label does not fit, or bends past `maxAngle` — both
+ * are "don't draw this here" answers, and the caller is expected to try the
+ * next candidate position rather than force it.
+ */
+export declare function placeGlyphsAlongLine(line: Vec[], options: LinePlacementOptions): PlacedGlyph[] | null;
+/**
+ * Distances along a line at which to attempt a repeated label.
+ *
+ * A long road gets its name several times rather than once in the middle,
+ * which is what makes a street findable when only part of it is on screen.
+ */
+export declare function repeatDistances(length: number, labelWidth: number, spacing: number): number[];
+export declare interface Vec {
+  x: number
+  y: number
+}
+export declare interface PlacedGlyph {
+  x: number
+  y: number
+  angle: number
+  index: number
+}
+export declare interface LinePlacementOptions {
+  advances: number[]
+  start: number
+  maxAngle?: number
+  keepUpright?: boolean
+}
+// Symbol placement geometry.
+//
+// Pure functions, deliberately: placement is the part of label rendering most
+// worth testing, and it is untestable if it only exists inside a canvas draw
+// call. Everything here works in whatever pixel space the caller hands it.
+export type TextAnchor = | 'center'
+    | 'left'
+    | 'right'
+    | 'top'
+    | 'bottom'
+    | 'top-left'
+    | 'top-right'
+    | 'bottom-left'
+    | 'bottom-right';

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

@@ -0,0 +1,37 @@
+/**
+ * Colour one distance field.
+ *
+ * `field` is RGBA, of which only alpha is read. The result is RGBA the same
+ * size, ready to hand to `putImageData`.
+ */
+export declare function renderSdfPixels(field: Uint8ClampedArray, width: number, height: number, options: SdfRenderOptions): Uint8ClampedArray;
+/** Hermite interpolation between two edges, as in the GLSL builtin. */
+export declare function smoothstep(edge0: number, edge1: number, x: number): number;
+/**
+ * A CSS colour as RGB.
+ *
+ * Hex and `rgb()`/`rgba()` cover what styles actually write and are parsed
+ * directly. Anything else — a named colour, `hsl()` — goes through a canvas,
+ * which knows every notation CSS does and saves shipping a colour parser to
+ * handle the long tail.
+ */
+export declare function parseColor(color: string): [number, number, number];
+// Resolving a signed-distance icon to pixels.
+//
+// An SDF sprite stores distance from the shape's edge in its alpha channel
+// rather than the icon's own colours, encoded so that 0.5 is the edge itself.
+// Two things follow from that, and they are the reason the format is worth
+// supporting: one grey shape can be drawn in any colour a style asks for, and
+// the edge is recovered by thresholding rather than resampled from pixels, so
+// it stays sharp however far the icon is scaled up.
+//
+// The work is kept here, apart from `IconAtlas`, because it is arithmetic over
+// a buffer and nothing more. The atlas reads pixels out of a canvas and writes
+// them back; that part needs a browser. This part can be tested against
+// hand-built fields, which is where the behaviour worth checking actually
+// lives.
+export declare interface SdfRenderOptions {
+  color: string
+  haloColor?: string
+  haloWidth?: number
+}

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

@@ -0,0 +1,32 @@
+import type { FormattedSection } from '../style-spec/expressions/formatted';
+import type { GlyphAtlas } from './GlyphAtlas';
+/**
+ * Measure a formatted label as one box.
+ *
+ * Height is the tallest section's, so a small section next to a large one does
+ * not shrink the label's footprint and let something else overlap it.
+ */
+export declare function measureSections(atlas: GlyphAtlas, sections: FormattedSection[], base: SectionBaseStyle): SectionLayout;
+/**
+ * Draw a formatted label from `x` along a shared baseline at `y`.
+ *
+ * Sections sit on the baseline rather than being centred on it, which is what
+ * keeps a size change reading as one line of text instead of two runs that
+ * happen to be adjacent.
+ */
+export declare function drawSections(ctx: CanvasRenderingContext2D, atlas: GlyphAtlas, sections: FormattedSection[], x: number, y: number, base: SectionBaseStyle): void;
+export declare interface SectionBaseStyle {
+  size: number
+  color: string
+  italic?: boolean
+  bold?: boolean
+  family?: string
+  haloColor?: string
+  haloWidth?: number
+}
+export declare interface SectionLayout {
+  width: number
+  height: number
+  ascent: number
+  descent: number
+}

package/dist/core-map/workers/WorkerPool.d.ts

@@ -0,0 +1,40 @@
+export declare function registerWorkerHandler<T, R>(type: string, fn: WorkerHandler<T, R>, options?: RegisterOptions): void;
+export declare function getWorkerHandler(type: string): WorkerHandler | undefined;
+export declare interface WorkerTask<T = unknown, _R = unknown> {
+  type: string
+  payload: T
+}
+export declare interface WorkerPoolOptions {
+  size?: number
+  scriptUrl?: string
+}
+declare interface PendingTask {
+  resolve: (value: unknown) => void
+  reject: (reason: unknown) => void
+}
+export declare interface RegisterOptions {
+  deps?: Array<(...args: any[]) => any>
+  transfer?: (result: any) => ArrayBuffer[]
+}
+// eslint-disable-next-line no-unused-vars
+export type WorkerHandler<T = unknown, R = unknown> = (task: WorkerTask<T, R>) => R | Promise<R>;
+// ---------------------------------------------------------------------------
+// Pool
+// ---------------------------------------------------------------------------
+export declare class WorkerPool {
+  _size: number;
+  _scriptUrl?: string;
+  _workers: Worker[];
+  _blobUrl?: string;
+  _nextId: number;
+  _pending: Map<number, PendingTask>;
+  _rr: number;
+  _usable: boolean;
+  constructor(opts?: WorkerPoolOptions);
+  size(): number;
+  _canUseWorkers(): boolean;
+  _spawn(): void;
+  _onMessage(e: MessageEvent): void;
+  run<T, R>(task: WorkerTask<T, R>): Promise<R>;
+  shutdown(): Promise<void>;
+}

package/dist/core-map/workers/decodeMvtFlat.d.ts

@@ -0,0 +1,52 @@
+/** Every ArrayBuffer in a decoded tile, for a `postMessage` transfer list. */
+export declare function flatTileBuffers(tile: FlatTile): ArrayBuffer[];
+/**
+ * Decode a `.pbf` tile into flat arrays.
+ *
+ * Self-contained by construction — see the note at the top of the file.
+ */
+export declare function decodeMvtFlat(bytes: Uint8Array): FlatTile;
+// decodeMvtFlat — an MVT decoder that answers in typed arrays.
+//
+// This is deliberately a second decoder rather than a reuse of `Pbf` +
+// `VectorTile`, for two reasons.
+//
+// **It has to survive being turned into a string.** WorkerPool ships its
+// handlers by stringifying them into an inline worker, so anything a handler
+// reaches for through an import is simply not there when it runs. This
+// function closes over nothing at all — no imports, no module constants, no
+// sibling helpers — which is a property the file is written to preserve, not
+// an accident. Adding an import here breaks decoding in the worker while
+// leaving every main-thread test passing, so don't.
+//
+// **It decodes to a different shape.** The output is flat typed arrays whose
+// buffers are transferred to the main thread rather than copied. That is the
+// entire point of the exercise: a tile decoded into `{x, y}` objects is
+// hundreds of thousands of allocations that structured-clone must then walk
+// and rebuild, which costs more than the decode it was meant to save. Moving
+// work to a worker only helps when what crosses the boundary is cheap.
+//
+// Geometry stays lazy on the far side. The layout below is the tile's own —
+// shared key and value tables, features as indices into them — so the main
+// thread materialises a feature's points and properties when something asks
+// for them, exactly as the Pbf path does.
+//
+// `test/mvt-flat.test.ts` decodes the same fixtures both ways and asserts the
+// results match, which is what keeps the duplication honest.
+export declare interface FlatLayer {
+  name: string
+  version: number
+  extent: number
+  keys: string[]
+  values: Array<string | number | boolean | null>
+  ids: Float64Array
+  types: Uint8Array
+  tagStart: Uint32Array
+  tags: Uint32Array
+  ringStart: Uint32Array
+  ringOffset: Uint32Array
+  coords: Int32Array
+}
+export declare interface FlatTile {
+  layers: FlatLayer[]
+}