@mappable-world/mappable-types 0.0.1

package/README.md

@@ -0,0 +1,25 @@
+# Types for mappable Maps JS API
+
+Type definitions for Mappable Maps JavaScript API (https://mappable.world).
+
+> Types are automatically generated based on source files.
+
+## Getting started
+
+```bash
+npm i @mappable/mappable-types -D
+```
+
+tsconfig.json
+
+```json
+{
+  "compilerOptions": {
+    "types": ["@mappable/mappable-types"]
+  }
+}
+```
+
+And you can use `mappable` global variable in your code.
+
+> Don't forget to connect the script with the Maps JS API: https://mappable.world

package/common/types/behavior.d.ts

@@ -0,0 +1 @@
+export type BehaviorType = 'drag' | 'pinchZoom' | 'scrollZoom' | 'dblClick' | 'magnifier' | 'oneFingerZoom' | 'mouseRotate' | 'mouseTilt' | 'pinchRotate' | 'panTilt';

package/common/types/bounds.d.ts

@@ -0,0 +1,17 @@
+import type { LngLat } from "./lng-lat";
+import type { WorldCoordinates } from "./coordinates";
+/**
+ * Generic for rectangle bounded by bottom-left and top-right coordinates
+ */
+export type GenericBounds<T> = [
+    T,
+    T
+];
+/**
+ * Rectangle bounded by bottom-left and top-right coordinates
+ */
+export type LngLatBounds = GenericBounds<LngLat>;
+/**
+ * Rectangle bounded by bottom-left and top-right world coordinates
+ */
+export type WorldBounds = GenericBounds<WorldCoordinates>;

package/common/types/camera.d.ts

@@ -0,0 +1,8 @@
+import type { WorldCoordinates } from "./coordinates";
+interface Camera {
+    readonly worldCenter: WorldCoordinates;
+    readonly zoom: number;
+    readonly azimuth: number;
+    readonly tilt: number;
+}
+export { Camera };

package/common/types/coordinates.d.ts

@@ -0,0 +1,30 @@
+import type { Vec2 } from "./vec2";
+/**
+ * Coordinates in [-1 ... +1].
+ * Left bottom is (-1; -1).
+ * Right top is (+1; +1).
+ * Center is (0; 0).
+ */
+interface WorldCoordinates extends Vec2 {
+    readonly type?: 'world';
+    z?: number;
+}
+/**
+ * Global pixel coordinates. World size depends on zoom.
+ * Left top is (0; 0).
+ * Right bottom is (2**(zoom + 8); 2**(zoom + 8)).
+ */
+interface PixelCoordinates extends Vec2 {
+    readonly type?: 'pixel';
+}
+/**
+ * Coordinate in Tile CS. Tile CS uses tile as unit. GlobalPixelCoordinate / tileSize.
+ * Left top is (0, 0).
+ * Right bottom is (2**(zoom + 8) / tileSize; 2**(zoom + 8) / tileSize).
+ * Left top of any tile is integers withou any fractional part. Aka tile number.
+ * Center of any tile is (smth.5, smth.5).
+ */
+interface TileCoordinates extends Vec2 {
+    readonly type?: 'tile';
+}
+export { WorldCoordinates, PixelCoordinates, TileCoordinates };

package/common/types/data-source-description.d.ts

@@ -0,0 +1,127 @@
+import type { WorldCoordinates } from "./coordinates";
+import type { GenericGeometry } from "./geojson";
+import type { PixelCoordinates } from "./coordinates";
+import type { HotspotFeature } from "./hotspot";
+type VectorCustomizationStyler = {
+    zoom?: number | [
+        number,
+        number
+    ];
+    visibility?: 'off';
+    hue?: string;
+    saturation?: number;
+    lightness?: number;
+    color?: string;
+    'secondary-color'?: string;
+    'tertiary-color'?: string;
+    opacity?: number;
+    scale?: number;
+};
+type VectorCustomizationTypes = 'point' | 'polyline' | 'polygon';
+type VectorCustomizationElements = 'geometry' | 'geometry.fill' | 'geometry.fill.pattern' | 'geometry.outline' | 'label' | 'label.icon' | 'label.text' | 'label.text.fill' | 'label.text.outline';
+type VectorCustomization = {
+    tags?: {
+        all?: string | string[];
+        any?: string | string[];
+        none?: string | string[];
+    } | string;
+    types?: VectorCustomizationTypes | VectorCustomizationTypes[];
+    elements?: VectorCustomizationElements | VectorCustomizationElements[];
+    stylers?: VectorCustomizationStyler | VectorCustomizationStyler[];
+}[];
+interface WorldHotspot {
+    readonly type: 'world';
+    readonly feature: HotspotFeature<unknown>;
+    readonly geometry: GenericGeometry<WorldCoordinates>;
+}
+interface RenderedHotspot {
+    readonly type: 'rendered';
+    readonly feature: HotspotFeature<unknown>;
+    readonly geometry: GenericGeometry<PixelCoordinates>;
+}
+type Hotspot = WorldHotspot | RenderedHotspot;
+interface FetchedTile {
+    image: HTMLImageElement | HTMLCanvasElement | ImageBitmap;
+}
+type FetchTileFunction = (x: number, y: number, z: number, scale: number, signal: AbortSignal) => Promise<FetchedTile>;
+type ComposeTileUrlFunction = (x: number, y: number, z: number, scale: number, signal: AbortSignal) => string;
+/**
+ * Provides hotspots for given tile coordinates and zoom.
+ * @param x Tile X
+ * @param y Tile Y
+ * @param z Tile Z
+ * @param signal is used to abort request in case if hotspots for given tile are no longer required
+ */
+type FetchHotspotsFunction = (x: number, y: number, z: number, signal: AbortSignal) => Promise<Hotspot[]>;
+interface RasterTileDataSourceDescription {
+    /**
+     * Either template tile url:
+     *   - {{x}} {{y}} {{z}} placeholders for tile coordinates
+     *   - {{scale}} placeholders for pixel scale (e.g. retina is 2)
+     * Or function that returns final url.
+     * Or function that fetches tile manually.
+     */
+    fetchTile: string | ComposeTileUrlFunction | FetchTileFunction;
+    /** Name of data provided by this data source. Should be referenced in layer. */
+    type: string;
+    /** Tile size in pixels. Default is 256. */
+    size?: number;
+    transparent?: boolean;
+    /**
+     * Returns promise that is going to be resolved by hotspots for tile, or rejected with {name: 'AbortError'}.
+     * Hotspots are expected to be sorted from bottom to top (aka far to near).
+     */
+    fetchHotspots?: FetchHotspotsFunction;
+    /**
+     * Defines maximum distance between tile and pointer, till which we keep alive unfinished requests
+     * for hotspots for that tile.
+     */
+    hotspotAbortRadius?: number;
+    /**
+     * Defines how far inside into tile hotspots from other tile can go.
+     * For example, tile may have a little part of POI from neightbour tile, but no hotspot for it in data.
+     */
+    hotspotInset?: number;
+    /**
+     * Defines how much pixels should be added to hotspot to increase its area.
+     * Moves each point of hotspot X pixels away from the center of the hotspots.
+     * NOTE: Currently works only on hotspots with Polygon geometry.
+     */
+    hotspotPadding?: number;
+}
+interface HotspotsOptions {
+    minZoom?: number;
+}
+type MapTheme = 'dark';
+type VectorTileSize = 'X1' | 'X4' | 'X16';
+type VectorDataSourcePriority = 'low' | 'medium' | 'high';
+type VectorObjectsCollisionPriority = 'low' | 'medium' | 'high' | 'ultra';
+interface VectorTileDataSourceDescription {
+    tileUrl: string;
+    imageUrl?: string;
+    meshUrl?: string;
+    glyphRangeUrl?: string;
+    indoorPlanUrl?: string;
+    tileRequestWithCredentials?: boolean;
+    imageRequestWithCredentials?: boolean;
+    meshRequestWithCredentials?: boolean;
+    glyphRequestWithCredentials?: boolean;
+    tileRequestHeaders?: Record<string, string>;
+    iconRequestHeaders?: Record<string, string>;
+    glyphRequestHeaders?: Record<string, string>;
+    meshRequestHeaders?: Record<string, string>;
+    priority: VectorDataSourcePriority;
+    collisionPriority?: VectorObjectsCollisionPriority;
+    requestTileSize?: VectorTileSize;
+    tileBeltSize?: number;
+    lowPrecisionBeltTiles?: boolean;
+    tileCacheSize?: number;
+    allObjectsInteractive?: boolean;
+    /** Forces tiles to wait for the icons, disables hiding icons by zoom diff */
+    iconsOnlyTiles?: boolean;
+    customization?: VectorCustomization;
+    theme?: MapTheme;
+    /** Defines how hotspots of type should be treated: enabled/disabled or use custom hotspots instead. */
+    hotspots?: Record<string, boolean | FetchHotspotsFunction | HotspotsOptions>;
+}
+export { VectorCustomization, RasterTileDataSourceDescription, FetchHotspotsFunction, VectorTileDataSourceDescription, VectorTileSize, VectorObjectsCollisionPriority, VectorDataSourcePriority, HotspotsOptions, FetchTileFunction, ComposeTileUrlFunction, Hotspot, WorldHotspot, RenderedHotspot, FetchedTile, MapTheme };

package/common/types/easing-function.d.ts

@@ -0,0 +1,9 @@
+import type { Vec2 } from "./vec2";
+type EasingBezierPreset = {
+    p1: Vec2;
+    p2: Vec2;
+};
+type EasingFunction = (x: number) => number;
+type EasingPresetName = 'linear' | 'ease' | 'ease-in' | 'ease-out' | 'ease-in-out';
+type EasingFunctionDescription = EasingPresetName | EasingBezierPreset | EasingFunction;
+export { EasingFunctionDescription, EasingPresetName, EasingBezierPreset, EasingFunction };

package/common/types/geojson.d.ts

@@ -0,0 +1,58 @@
+import type { LngLat } from "./lng-lat";
+interface GenericPolygonGeometry<TCoordinates> {
+    type: 'Polygon';
+    /**
+     * Polygon's rings.
+     *
+     * @remarks
+     * Inner rings may extend beyond outer ring.
+     * GeoJSON doesn't allow this, but there's a lot of data like this in this JS API.
+     */
+    coordinates: TCoordinates[][];
+}
+interface GenericMultiPolygonGeometry<TCoordinates> {
+    type: 'MultiPolygon';
+    /** Array of polygons. See {@link GenericPolygonGeometry}. */
+    coordinates: TCoordinates[][][];
+}
+interface GenericLineStringGeometry<TCoordinates> {
+    type: 'LineString';
+    coordinates: TCoordinates[];
+}
+interface GenericMultiLineStringGeometry<TCoordinates> {
+    type: 'MultiLineString';
+    coordinates: TCoordinates[][];
+}
+interface GenericPointGeometry<TCoordinates> {
+    type: 'Point';
+    coordinates: TCoordinates;
+}
+type GenericGeometry<TCoordinates> = GenericPolygonGeometry<TCoordinates> | GenericMultiPolygonGeometry<TCoordinates> | GenericLineStringGeometry<TCoordinates> | GenericMultiLineStringGeometry<TCoordinates> | GenericPointGeometry<TCoordinates>;
+interface GenericFeature<TCoordinates> {
+    type: 'Feature';
+    id: string;
+    geometry: GenericGeometry<TCoordinates>;
+    properties?: Record<string, unknown>;
+}
+interface GenericPointFeature<TCoordinates> extends GenericFeature<TCoordinates> {
+    geometry: GenericPointGeometry<TCoordinates>;
+}
+interface GenericMappableFeatureCollection<TCoordinates> {
+    type: 'FeatureCollection';
+    /**
+     * Could be collection of features or collection of feature collections.
+     * This is not defined by GEO JSON spec, but there is such cases in our data.
+     */
+    features: (GenericFeature<TCoordinates> | GenericMappableFeatureCollection<TCoordinates>)[];
+    properties?: Record<string, unknown>;
+}
+interface GenericFeatureCollection<TCoordinates> extends GenericMappableFeatureCollection<TCoordinates> {
+    id: string;
+    features: GenericFeature<TCoordinates>[];
+}
+type LineStringGeometry = GenericLineStringGeometry<LngLat>;
+type MultiLineStringGeometry = GenericMultiLineStringGeometry<LngLat>;
+type MultiPolygonGeometry = GenericMultiPolygonGeometry<LngLat>;
+type PointGeometry = GenericPointGeometry<LngLat>;
+type PolygonGeometry = GenericPolygonGeometry<LngLat>;
+export { GenericPolygonGeometry, GenericMultiPolygonGeometry, GenericLineStringGeometry, GenericMultiLineStringGeometry, GenericPointGeometry, GenericGeometry, GenericFeature, GenericPointFeature, GenericFeatureCollection, GenericMappableFeatureCollection, LineStringGeometry, MultiLineStringGeometry, MultiPolygonGeometry, PointGeometry, PolygonGeometry };

package/common/types/graphics.d.ts

@@ -0,0 +1,36 @@
+type FillRule = 'evenodd' | 'nonzero';
+interface PaletteEntry {
+    count: number;
+    color: string;
+}
+type Palette = PaletteEntry[];
+interface StrokeStyle {
+    width?: number;
+    opacity?: number;
+    color?: string;
+    palette?: Palette;
+    simplifyPalette?: boolean;
+    dash?: number[];
+}
+type Stroke = StrokeStyle[];
+interface DrawingStyleIcon {
+    readonly url: string;
+    readonly offset?: [
+        number,
+        number
+    ];
+    readonly scale?: number;
+}
+interface DrawingStyle {
+    zIndex?: number;
+    fill?: string;
+    fillOpacity?: number;
+    fillRule?: FillRule;
+    stroke?: Stroke;
+    cursor?: string;
+    interactive?: boolean;
+    simplificationRate?: number;
+    icon?: DrawingStyleIcon;
+    element?: HTMLElement;
+}
+export { DrawingStyle, Palette, StrokeStyle, Stroke, DrawingStyleIcon, FillRule };

package/common/types/hotspot.d.ts

@@ -0,0 +1,13 @@
+import type { GenericGeometry } from "./geojson";
+import type { LngLat } from "./lng-lat";
+interface HotspotFeature<TCoordinates> {
+    type: 'Feature';
+    id: string;
+    geometry?: GenericGeometry<TCoordinates>;
+    properties: Record<string, unknown>;
+}
+interface HotspotObject {
+    type: 'hotspot';
+    feature: HotspotFeature<LngLat>;
+}
+export { HotspotFeature, HotspotObject };

package/common/types/index.d.ts

@@ -0,0 +1,20 @@
+export * from "./coordinates";
+export * from "./lng-lat";
+export * from "./bounds";
+export * from "./behavior";
+export * from "./projection";
+export * from "./map";
+export * from "./margin";
+export * from "./zoom";
+export * from "./zoom-strategy";
+export * from "./geojson";
+export * from "./layer-description";
+export * from "./indoor";
+export * from "./vec2";
+export * from "./camera";
+export * from "./easing-function";
+export * from "./graphics";
+export * from "./hotspot";
+export * from "./utils";
+export * from "./world-options";
+export * from "./data-source-description";

package/common/types/indoor.d.ts

@@ -0,0 +1,29 @@
+interface IndoorLevel {
+    id: string;
+    name: string;
+    isUnderground?: boolean;
+}
+interface IndoorPlan {
+    source: string;
+    getId(): string;
+    /** Returns bounds of indoor plan in [[lng, lat], [lng, lat]]. */
+    getBounds(): [
+        [
+            number,
+            number
+        ],
+        [
+            number,
+            number
+        ]
+    ];
+    isVisible(): boolean;
+    setVisible(value: boolean): void;
+    getLevels(): IndoorLevel[];
+    getDefaultLevel(): IndoorLevel;
+    getActiveLevel(): IndoorLevel;
+    setActiveLevel(id: string): void;
+    getOpacity(): number;
+    setOpacity(value: number): void;
+}
+export { IndoorLevel, IndoorPlan };

package/common/types/layer-description.d.ts

@@ -0,0 +1,43 @@
+interface VectorObjectsInteractiveArea {
+    /** Additional interactive field around the icon, in px. */
+    field?: number;
+    /** Minimal size of the side of the icons interactive area. */
+    minSize?: number;
+}
+type RasterLayerOptions = Record<string, unknown> & {
+    opacity?: number;
+    /**
+     * Show all tiles simultaneously on a first display
+     * However if map state changed original logic is applied
+     */
+    awaitAllTilesOnFirstDisplay?: boolean;
+    /**
+     * Controls animation duration of the revealing newly downloaded tiles
+     * Values less than or equal to zero turn off animation
+     */
+    tileRevealDuration?: number;
+};
+type VectorLayerOptions = Record<string, unknown> & {
+    modelsAppearingAnimation?: {
+        transitionZoom: number;
+        duration: number;
+        limitByZoom: number;
+    };
+    iconsInteractiveArea?: VectorObjectsInteractiveArea;
+    transformLayers?: Record<string, {
+        color?: {
+            r: number;
+            g: number;
+            b: number;
+            a: number;
+        };
+        lightness?: number;
+        saturation?: number;
+        opacity?: number;
+    }>;
+    parentLayerId?: string;
+    opacity?: number;
+    /** Isolates colliding of the layer's objects, not colliding them with other layers' objects */
+    isolateObjectsColliding?: boolean;
+};
+export { RasterLayerOptions, VectorLayerOptions, VectorObjectsInteractiveArea };

package/common/types/lng-lat.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Tuple with geodesic coordinates in longitude latitude order.
+ * GeoJSON also uses this order https://tools.ietf.org/html/rfc7946#appendix-A.1
+ */
+type LngLat = [
+    lon: number,
+    lat: number,
+    alt?: number
+];
+/**
+ * Readonly version of {@link LngLat}
+ */
+type ReadonlyLngLat = Readonly<LngLat>;
+export { LngLat, ReadonlyLngLat };

package/common/types/map.d.ts

@@ -0,0 +1 @@
+export type MapMode = 'raster' | 'vector' | 'auto';

package/common/types/margin.d.ts

@@ -0,0 +1,8 @@
+/** Map margins in pixels. Order is top, right, bottom, left. */
+type Margin = [
+    number,
+    number,
+    number,
+    number
+];
+export { Margin };

package/common/types/projection.d.ts

@@ -0,0 +1,8 @@
+import type { LngLat } from "./lng-lat";
+import type { WorldCoordinates } from "./coordinates";
+interface GenericProjection<TSource> {
+    toWorldCoordinates(point: TSource): WorldCoordinates;
+    fromWorldCoordinates(coordinates: WorldCoordinates): TSource;
+}
+type Projection = GenericProjection<LngLat>;
+export { Projection, GenericProjection };

package/common/types/utils.d.ts

@@ -0,0 +1,15 @@
+type DeepReadonly<T> = T extends (infer R)[] ? DeepReadonlyArray<R> : T extends Function ? T : T extends object ? DeepReadonlyObject<T> : T;
+interface DeepReadonlyArray<T> extends ReadonlyArray<DeepReadonly<T>> {
+}
+type DeepReadonlyObject<T> = {
+    readonly [P in keyof T]: DeepReadonly<T[P]>;
+};
+type Nullable<T> = T | null;
+type Change<T> = {
+    old: T;
+    new: T;
+} | null;
+type Changes<T> = {
+    readonly [TKey in keyof T]: Change<T[TKey]>;
+};
+export { DeepReadonly, DeepReadonlyArray, DeepReadonlyObject, Nullable, Change, Changes };

package/common/types/vec2.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Axis-aligned bounding box in 2D space.
+ */
+interface BBox2 {
+    minX: number;
+    maxX: number;
+    minY: number;
+    maxY: number;
+}
+interface Vec2 {
+    x: number;
+    y: number;
+}
+export { BBox2, Vec2 };

package/common/types/world-options.d.ts

@@ -0,0 +1,4 @@
+interface WorldOptions {
+    readonly cycledX: boolean;
+}
+export { WorldOptions };

package/common/types/zoom-strategy.d.ts

@@ -0,0 +1 @@
+export type ZoomStrategy = 'zoomToCenter' | 'zoomToPointer';

package/common/types/zoom.d.ts

@@ -0,0 +1,11 @@
+interface ZoomRange {
+    min: number;
+    max: number;
+}
+/**
+ * Set rounding for zoom.
+ * If `auto` is selected, zoom will be `snap` for `raster` and `smooth` for `vector` `MapMode`.
+ * Default is `auto`.
+ */
+type ZoomRounding = 'snap' | 'smooth' | 'auto';
+export { ZoomRange, ZoomRounding };

package/imperative/DomContext.d.ts

@@ -0,0 +1,35 @@
+import { Context, GenericComplexEntity, GenericEntity } from "./Entities";
+import { MMapEntity, MMapGroupEntity } from "./MMapEnities";
+export type DomDetach = () => void;
+type DomContext = {
+    attach(entity: GenericEntity<unknown>, element: Element): DomDetach;
+};
+export declare const DomContext: Context<DomContext>;
+export type DomContextDestroy = () => void;
+/**
+ * @ignore
+ * Creates DomContext for specified container for entity.
+ * NB: Does not allow to change container element on the fly.
+ */
+export declare function createDomContext(containerEntity: GenericComplexEntity<unknown>, containerElement: Element, containerEndElement?: Element): [
+    DomContext,
+    DomContextDestroy
+];
+export declare function useDomContext(entity: GenericComplexEntity<unknown>, element: Element, container: Element | null): () => void;
+export declare abstract class DomEntity<TProps, TElement extends Element = HTMLElement, DefaultProps extends {} = {}> extends MMapGroupEntity<TProps, DefaultProps> {
+    protected _element?: TElement;
+    private _detachDom?;
+    private _destroyDomCtx?;
+    constructor(props: TProps, children?: MMapEntity<unknown>[]);
+    protected _onAttach(): void;
+    protected _onDetach(): void;
+    protected _onUpdate(props: Partial<TProps>): void;
+    protected abstract _createDom(): TElement | {
+        element: TElement;
+        container: Element;
+        containerEndElement?: Element;
+    };
+    protected abstract _updateDom(element: TElement, props: Partial<TProps>): void;
+    protected _destroyDom(_element: TElement): void;
+}
+export {};