ts-maps 0.3.1 → 0.3.3

package/dist/core-map/control/FullscreenControl.d.ts

@@ -0,0 +1,39 @@
+import { Control } from './Control';
+/**
+ * Expand the map to fill the screen.
+ *
+ * Two mechanisms, because one of them is unavailable more often than it
+ * looks: the Fullscreen API is blocked in cross-origin iframes without an
+ * `allowfullscreen` attribute, and on iPhone Safari it does not exist at all —
+ * both being exactly the places a map is most likely to be embedded. When it
+ * is unavailable the control falls back to a fixed, full-viewport class, which
+ * is not true fullscreen (browser chrome stays) but does the thing the user
+ * pressed the button for.
+ *
+ * Either way the map is told to re-measure: the container changes size without
+ * a window resize event in the API case.
+ */
+export declare interface FullscreenControlOptions {
+  position?: string
+  container?: HTMLElement
+  title?: string
+  titleCancel?: string
+}
+export declare class FullscreenControl extends Control {
+  _button?: HTMLAnchorElement;
+  _pseudo?: boolean;
+  _onDocumentChange?: () => void;
+  onAdd(_map: any): HTMLElement;
+  onRemove(_map: any): void;
+  isFullscreen(): boolean;
+  toggle(): this;
+  request(): this;
+  exit(): this;
+  _target(): HTMLElement;
+  _documentElement(): Element | null;
+  _enterPseudo(): void;
+  _exitPseudo(): void;
+  _syncFromDocument(): void;
+  _onChanged(active: boolean): void;
+  _updateButton(active: boolean): void;
+}

package/dist/core-map/control/GeocoderControl.d.ts

@@ -0,0 +1,61 @@
+import { Control } from './Control';
+import { Marker } from '../layer/marker/Marker';
+import type { GeocoderProvider, GeocodingResult } from '../services/types';
+/**
+ * A place search box, sitting on top of the geocoder providers in
+ * `services/`.
+ *
+ * The adapters have always been there; what was missing was the control that
+ * makes them usable without hand-rolling an input, a debounce, a result list
+ * and keyboard handling on every map. The default provider is Nominatim, which
+ * needs no key — so `control.geocoder().addTo(map)` searches out of the box.
+ *
+ * Requests are debounced and the in-flight one is aborted on every keystroke.
+ * That is politeness towards a public endpoint as much as it is correctness:
+ * without the abort, a slow early response can land after a fast later one and
+ * repopulate the list with results for a query the user has already moved past.
+ */
+export declare interface GeocoderControlOptions {
+  position?: string
+  provider?: GeocoderProvider
+  placeholder?: string
+  title?: string
+  limit?: number
+  debounce?: number
+  minLength?: number
+  collapsed?: boolean
+  flyTo?: boolean
+  zoom?: number
+  marker?: boolean
+  proximity?: boolean
+  language?: string
+  countries?: string[]
+  bbox?: [number, number, number, number]
+  errorText?: string
+  noResultsText?: string
+}
+export declare class GeocoderControl extends Control {
+  _input?: HTMLInputElement;
+  _list?: HTMLUListElement;
+  _toggle?: HTMLAnchorElement;
+  _results: GeocodingResult[];
+  _selected: number;
+  _timer?: ReturnType<typeof setTimeout>;
+  _abort?: AbortController;
+  _marker?: Marker;
+  _expanded?: boolean;
+  onAdd(_map: any): HTMLElement;
+  onRemove(_map: any): void;
+  setQuery(query: string): this;
+  clear(): this;
+  _onToggle(): void;
+  _setExpanded(expanded: boolean): void;
+  _onInput(): void;
+  _search(query: string): void;
+  _request(query: string): void;
+  _renderList(): void;
+  _onKeyDown(event: KeyboardEvent): void;
+  _move(delta: number): void;
+  select(index: number): this;
+  _cancelPending(): void;
+}

package/dist/core-map/control/LocateControl.d.ts

@@ -0,0 +1,56 @@
+import { Circle } from '../layer/vector/Circle';
+import { Control } from './Control';
+import { Marker } from '../layer/marker/Marker';
+/**
+ * "Where am I" — the crosshair button every map is expected to have.
+ *
+ * Centres the map on the device's own position and, unless told otherwise,
+ * keeps following it as the position updates. The button carries its own state
+ * so the user is never left wondering whether anything happened:
+ *
+ *   idle      the outline crosshair
+ *   locating  pulsing, while the first fix is being acquired
+ *   active    filled, while the map is following the device
+ *   denied    struck through, when permission was refused or the fix failed
+ *
+ * Geolocation is requested on CLICK and never on load. A permission prompt
+ * that appears unasked is the fastest way to be denied for the rest of the
+ * session, and a denied permission cannot be re-requested without the user
+ * going into browser settings.
+ *
+ * Following stops the moment the user pans, drags, or zooms by hand: a map
+ * that yanks itself back under a finger is worse than one that does nothing.
+ */
+export declare interface LocateControlOptions {
+  position?: string
+  zoom?: number | null
+  follow?: boolean
+  enableHighAccuracy?: boolean
+  timeout?: number
+  maximumAge?: number
+  title?: string
+  titleLocating?: string
+  titleActive?: string
+  titleDenied?: string
+  showMarker?: boolean
+}
+export declare class LocateControl extends Control {
+  _button?: HTMLAnchorElement;
+  _watchId?: number;
+  _following?: boolean;
+  _selfMoving?: boolean;
+  _marker?: Marker;
+  _accuracyCircle?: Circle;
+  onAdd(map: any): HTMLElement;
+  onRemove(map: any): void;
+  start(): this;
+  stop(): this;
+  _onClick(): void;
+  _locate(): void;
+  _onPosition(position: GeolocationPosition, recenter: boolean): void;
+  _updateMarker(latlng: [number, number], accuracy: number): void;
+  _clearMarker(): void;
+  _stopFollowing(): void;
+  _clearWatch(): void;
+  _setState(state: 'idle' | 'locating' | 'active' | 'denied'): void;
+}

package/dist/core-map/control/NavigationControl.d.ts

@@ -0,0 +1,39 @@
+import { Control } from './Control';
+/**
+ * Zoom buttons plus a compass, in one stack — Mapbox's `NavigationControl`.
+ *
+ * The compass is the part `ZoomControl` cannot grow into: once a map can be
+ * rotated and pitched (it can — see `TwoFingerRotate` and `TwoFingerPitch`),
+ * there has to be a way back to north that does not involve wrestling two
+ * fingers into alignment. The needle doubles as the only always-visible
+ * indication that the map is rotated at all.
+ *
+ * It composes rather than extends ZoomControl: the two are separate controls
+ * with separate positions, and inheritance would tie their DOM together for
+ * the sake of sharing one small button helper.
+ */
+export declare interface NavigationControlOptions {
+  position?: string
+  showZoom?: boolean
+  showCompass?: boolean
+  visualizePitch?: boolean
+  resetDuration?: number
+  zoomInTitle?: string
+  zoomOutTitle?: string
+  compassTitle?: string
+}
+export declare class NavigationControl extends Control {
+  _zoomInButton?: HTMLAnchorElement;
+  _zoomOutButton?: HTMLAnchorElement;
+  _compassButton?: HTMLAnchorElement;
+  _needle?: HTMLElement;
+  onAdd(map: any): HTMLElement;
+  onRemove(map: any): void;
+  _zoomIn(event: any): void;
+  _zoomOut(event: any): void;
+  _resetNorth(): void;
+  _reducedMotion(): boolean;
+  _updateCompass(): void;
+  _updateDisabled(): void;
+  _createButton(className: string, title: string, html: string, container: HTMLElement, fn: (event: any) => void): HTMLAnchorElement;
+}

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

@@ -1,5 +1,13 @@
+export type { FullscreenControlOptions } from './FullscreenControl';
+export type { GeocoderControlOptions } from './GeocoderControl';
+export type { LocateControlOptions } from './LocateControl';
+export type { NavigationControlOptions } from './NavigationControl';
 export { AttributionControl } from './AttributionControl';
 export { Control } from './Control';
+export { FullscreenControl } from './FullscreenControl';
+export { GeocoderControl } from './GeocoderControl';
 export { LayersControl } from './LayersControl';
+export { LocateControl } from './LocateControl';
+export { NavigationControl } from './NavigationControl';
 export { ScaleControl } from './ScaleControl';
 export { ZoomControl } from './ZoomControl';

package/dist/core-map/game/TerritoryLog.d.ts

@@ -0,0 +1,66 @@
+import { Evented } from '../core/Events';
+import type { CaptureResult, TerritoryStore, TerritoryStoreOptions } from './TerritoryStore';
+import type { MultiPolygon, Ring } from '../geo/polygonClip';
+/**
+ * The agreed order: server sequence, then timestamp, then id.
+ *
+ * Every participant computes this the same way from the event alone, which is
+ * what makes the fold converge. The id tiebreak is not a formality — phone
+ * clocks disagree, so identical timestamps are common enough that without it
+ * two clients would order the same pair differently and diverge.
+ */
+export declare function compareEvents(a: CaptureEvent, b: CaptureEvent): number;
+export declare interface CaptureEvent {
+  id: string
+  owner: string
+  ring: Ring
+  at: number
+  seq?: number
+}
+export declare interface AppliedCapture {
+  event: CaptureEvent
+  result?: CaptureResult
+  duplicate: boolean
+  replayed: boolean
+}
+export declare interface TerritoryLogOptions {
+  maxEvents?: number
+  store?: TerritoryStoreOptions
+}
+/**
+ * An ordered log of captures, and the territory they add up to.
+ *
+ * ```ts
+ * const log = new TerritoryLog()
+ *
+ * // Local: apply at once, send to the server.
+ * const applied = log.apply({ id: uuid(), owner: 'me', ring, at: Date.now() })
+ * socket.send(applied.event)
+ *
+ * // Remote: apply whatever arrives, in whatever order.
+ * socket.on('capture', event => log.apply(event))
+ * ```
+ */
+export declare class TerritoryLog extends Evented {
+  _log: CaptureEvent[];
+  _seen: Set<string>;
+  _store: TerritoryStore;
+  _baseline: Map<string, MultiPolygon>;
+  _options: Required<Omit<TerritoryLogOptions, 'store'>> & { store?: TerritoryStoreOptions };
+  initialize(options?: TerritoryLogOptions): void;
+  get store(): TerritoryStore;
+  get events(): readonly CaptureEvent[];
+  apply(event: CaptureEvent): AppliedCapture;
+  applyAll(events: CaptureEvent[]): AppliedCapture[];
+  has(id: string): boolean;
+  confirm(id: string, seq: number): boolean;
+  compact(keep?: number): number;
+  snapshot(): {
+    baseline: Array<{ owner: string, territory: MultiPolygon }>
+    events: CaptureEvent[]
+  };
+  restore(snapshot: { baseline?: Array<{ owner: string, territory: MultiPolygon }>, events?: CaptureEvent[] }): this;
+  clear(): this;
+  _newStore(): TerritoryStore;
+  _rebuild(): void;
+}

package/dist/core-map/game/TerritoryStore.d.ts

@@ -0,0 +1,59 @@
+import { Evented } from '../core/Events';
+import type { MultiPolygon, Position, Ring } from '../geo/polygonClip';
+export declare interface TerritoryStoreOptions {
+  steal?: boolean
+  minFragmentArea?: number
+}
+export declare interface StolenFrom {
+  owner: string
+  area: number
+}
+export declare interface CaptureResult {
+  owner: string
+  ring: Ring
+  areaClaimed: number
+  areaGained: number
+  stolen: StolenFrom[]
+  territory: MultiPolygon
+  totalArea: number
+}
+export declare interface LeaderboardEntry {
+  owner: string
+  area: number
+  pieces: number
+}
+/**
+ * Territories by owner.
+ *
+ * ```ts
+ * const territories = new TerritoryStore()
+ * territories.on('capture', ({ owner, areaGained, stolen }) => {
+ *   toast(`${owner} claimed ${formatArea(areaGained)}`)
+ * })
+ * territories.capture('sam', loop.ring)
+ * ```
+ */
+export declare class TerritoryStore extends Evented {
+  _byOwner: Map<string, MultiPolygon>;
+  _options: Required<TerritoryStoreOptions>;
+  initialize(options?: TerritoryStoreOptions): void;
+  capture(owner: string, ring: Ring): CaptureResult;
+  get(owner: string): MultiPolygon;
+  set(owner: string, territory: MultiPolygon): this;
+  areaOf(owner: string): number;
+  owners(): string[];
+  leaderboard(): LeaderboardEntry[];
+  ownerAt(position: Position): string | null;
+  preview(owner: string, ring: Ring): { areaGained: number, stolen: StolenFrom[] };
+  toGeoJSON(): {
+    type: 'FeatureCollection'
+    features: Array<{
+      type: 'Feature'
+      properties: { owner: string, area: number }
+      geometry: { type: 'MultiPolygon', coordinates: MultiPolygon }
+    }>
+  };
+  loadGeoJSON(collection: { features?: Array<any> }): this;
+  clear(): this;
+  _prune(territory: MultiPolygon): MultiPolygon;
+}

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

@@ -0,0 +1,11 @@
+export type { AppliedCapture, CaptureEvent, TerritoryLogOptions } from './TerritoryLog';
+export type { DetectedLoop, LoopDetectorOptions, LoopOptions } from './loop';
+export type {
+  CaptureResult,
+  LeaderboardEntry,
+  StolenFrom,
+  TerritoryStoreOptions,
+} from './TerritoryStore';
+export { compareEvents, TerritoryLog } from './TerritoryLog';
+export { detectLoop, LoopDetector, simplifyTrack } from './loop';
+export { TerritoryStore } from './TerritoryStore';

package/dist/core-map/game/loop.d.ts

@@ -0,0 +1,61 @@
+import type { Position } from '../geo/area';
+/**
+ * Find the first loop a track closes, or null.
+ *
+ * The loop returned is the earliest one that closes, not the largest — a
+ * runner who laps a park and keeps going has earned the park at the moment
+ * they closed it, and waiting to see whether a bigger shape appears later
+ * would mean the game reacting to a run several minutes after it happened.
+ */
+export declare function detectLoop(track: Position[], options?: LoopOptions): DetectedLoop | null;
+/**
+ * Reduce a track to its shape, dropping points that say nothing new.
+ *
+ * A GPS logging at 1 Hz produces a great many points that lie on the line
+ * between their neighbours. Keeping them costs area calculations, boolean
+ * operations and every redraw, and they change none of the answers.
+ *
+ * `tolerance` is in metres: the furthest a dropped point may lie from the line
+ * that replaces it.
+ */
+export declare function simplifyTrack(track: Position[], tolerance?: number): Position[];
+export declare interface LoopOptions {
+  snapDistance?: number
+  minArea?: number
+  minLoopLength?: number
+  minPoints?: number
+}
+export declare interface DetectedLoop {
+  ring: Position[]
+  area: number
+  perimeter: number
+  startIndex: number
+  endIndex: number
+  closure: 'crossing' | 'proximity'
+}
+export declare interface LoopDetectorOptions extends LoopOptions {
+  carryOver?: number
+}
+/**
+ * Feed it GPS points; it tells you when a loop closes.
+ *
+ * A live run calls this on every position update, so it does the work
+ * incrementally rather than re-scanning the whole track each time: only the
+ * newest segment is tested, against the ones already recorded.
+ *
+ * ```ts
+ * const detector = new LoopDetector({ snapDistance: 25 })
+ * watchPosition((position) => {
+ *   const loop = detector.push([position.coords.longitude, position.coords.latitude])
+ *   if (loop)
+ *     territories.capture('me', loop.ring)
+ * })
+ * ```
+ */
+export declare class LoopDetector {
+  constructor(options?: LoopDetectorOptions);
+  get track(): Position[];
+  get length(): number;
+  push(point: Position): DetectedLoop | null;
+  reset(): void;
+}

package/dist/core-map/geo/area.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Signed area of one ring in square metres, positive when it winds
+ * counter-clockwise.
+ *
+ * Signed rather than absolute because the sign is what distinguishes a hole
+ * from an outer ring, and a territory with a lake in it is a shape this has to
+ * measure correctly.
+ *
+ * Coordinates are `[longitude, latitude]`, the order GeoJSON uses.
+ */
+export declare function ringArea(ring: Ring): number;
+/**
+ * Area of a polygon in square metres: its outer ring less its holes.
+ *
+ * Ring winding is not trusted — a track recorded by a runner going clockwise
+ * is as valid as one going the other way, and GeoJSON from the wild is
+ * inconsistent about it. The first ring is taken as the outer one and the rest
+ * as holes, which is what the GeoJSON specification says they are.
+ */
+export declare function polygonArea(polygon: Polygon): number;
+/** Area of a multipolygon in square metres. */
+export declare function multiPolygonArea(multi: MultiPolygon): number;
+/**
+ * Perimeter of a ring in metres.
+ *
+ * Useful next to the area: two territories of the same size but very different
+ * perimeters were earned by quite different runs.
+ */
+export declare function ringPerimeter(ring: Ring, closed?: boolean): number;
+/** Great-circle distance between two `[lng, lat]` positions, in metres. */
+export declare function haversine(a: Position, b: Position): number;
+/**
+ * Square metres as something to put on a screen.
+ *
+ * The unit is chosen for the magnitude, because a territory game spans four
+ * orders of it: a small block is a few thousand square metres, a good long run
+ * encloses a couple of square kilometres, and "0.004 km²" tells a player
+ * nothing they can feel.
+ */
+export declare function formatArea(squareMetres: number, options?: FormatAreaOptions): string;
+/** Metres as something to put on a screen. */
+export declare function formatDistance(metres: number, options?: FormatAreaOptions): string;
+/** Mean Earth radius in metres, as WGS 84 defines it. */
+export declare const EARTH_RADIUS: 6371008.8;
+export declare interface FormatAreaOptions {
+  units?: 'metric' | 'imperial'
+  locale?: string
+}
+export type Position = [number, number] | number[];
+export type Ring = Position[];
+export type Polygon = Ring[];
+export type MultiPolygon = Polygon[];

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

@@ -4,6 +4,16 @@ export type { LatLngBoundsLike } from './LatLngBounds';
 export type { DEMEncoding } from './elevation';
 export type { TerrainMesh, TerrainMeshOptions } from './terrainMesh';
 export type { TerrainSourceOptions, TileCoord } from './TerrainSource';
+export type { FormatAreaOptions } from './area';
+// Renamed on the way out: `Polygon` and `Position` are already taken at the
+// package root by the vector layer and the screen-space point, and a game's
+// coordinate arrays are not either of those.
+export type {
+  MultiPolygon as MultiPolygonCoordinates,
+  Polygon as PolygonCoordinates,
+  Position as LngLat,
+  Ring as LinearRing,
+} from './area';
 export { LatLng, toLatLng } from './LatLng';
 export { LatLngBounds, toLatLngBounds } from './LatLngBounds';
 export { decodeElevationGrid, decodeMapboxRGB, decodeTerrariumRGB, getElevationDecoder, sampleElevationBilinear } from './elevation';
@@ -11,3 +21,23 @@ export { buildTerrainMesh } from './terrainMesh';
 export { TerrainSource } from './TerrainSource';
 export { Projection };
 export * from './crs/index';
+export {
+  EARTH_RADIUS,
+  formatArea,
+  formatDistance,
+  haversine,
+  multiPolygonArea,
+  polygonArea,
+  ringArea,
+  ringPerimeter,
+} from './area';
+export { contains, difference, intersects, intersection, union, xor } from './polygonClip';
+export {
+  InvalidGeometryError,
+  prepareClaim,
+  resolveSelfIntersections,
+  selfIntersects,
+  splitSelfIntersecting,
+  unwrapRing,
+  validateRing,
+} from './validate';