@superrouteca/smap 1.0.2 → 1.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superrouteca/smap",
-  "version": "1.0.2",
+  "version": "1.0.6",
   "description": "sMap for the web: maps from Superroute's sMap service, the Web SDK (map view) and the JS client (tokens, nearest node, styles, tiles).",
   "license": "MIT",
   "author": "Goodneo Solutions",

package/types/smap.d.cts

@@ -30,8 +30,38 @@ export interface PointInput {
   [property: string]: unknown;
 }
 
-/** Layer data: GeoJSON (a FeatureCollection or a Feature) or an array of points or features. */
-export type LayerData = GeoJSONFeatureCollection | GeoJSONFeature | Array<PointInput | GeoJSONFeature> | null | undefined;
+/** Layer data: GeoJSON (a FeatureCollection, a Feature or a bare geometry) or an array of points or features. */
+export type LayerData = GeoJSONFeatureCollection | GeoJSONFeature | GeoJSONGeometry | Array<PointInput | GeoJSONFeature> | null | undefined;
+
+/**
+ * What a popup shows: an HTML string (inserted as it is and never sanitized, so it must be trusted: escape any feature
+ * data you put in it, or use `popupTemplate`), a DOM node, or a promise of either (the loading state shows meanwhile;
+ * a rejection closes the popup and is reported as the map's `error` event). Nothing (null, undefined, false, '')
+ * opens no popup.
+ */
+export type PopupContent = string | Node | null | undefined | false;
+
+/** How a popup looks and behaves. Layer options are merged over the map's `popup` defaults. */
+export interface PopupOptions {
+  /** Classes added to the popup's element, beside `smap-popup`. */
+  className?: string;
+  /** Largest width: pixels or a CSS length (default 240px). */
+  maxWidth?: number | string;
+  /** Smallest width: pixels or a CSS length. */
+  minWidth?: number | string;
+  /** Distance from the anchor in pixels, or per anchor (default 12). */
+  offset?: number | [number, number] | Record<string, [number, number]>;
+  /** Which side of the popup points at the position; chosen to fit by default. */
+  anchor?: 'center' | 'top' | 'bottom' | 'left' | 'right' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+  /** A close button in the corner (default true). */
+  closeButton?: boolean;
+  /** A click on the map closes it (default true). */
+  closeOnClick?: boolean;
+  /** Focus moves into the popup when it opens (default true). */
+  focusAfterOpen?: boolean;
+  /** Pan the map so the popup is fully visible (default true). */
+  autoPan?: boolean;
+}
 
 /** The event of a click on a layer's feature (the engine's map mouse event). */
 export interface LayerClickEvent {
@@ -50,14 +80,68 @@ interface CommonLayerOptions {
   /** A feature property used as the feature id. */
   idProperty?: string;
   /**
-   * A popup opened on click, from the clicked feature's properties: an HTML string, inserted as it is and never
-   * sanitized (so it must be trusted; escape any feature data you put in it), or a DOM node.
+   * The popup opened when the top feature at a click is this layer's; called only then. A point's popup opens at the
+   * point, a line's or area's where it was clicked. `popupTemplate('<b>{name}</b>')` gives a fast, escaped one.
    */
-  popup?: (properties: Record<string, unknown>, feature: GeoJSONFeature) => string | Node | null | undefined | false;
+  popup?: (properties: Record<string, unknown>, feature: GeoJSONFeature) => PopupContent | Promise<PopupContent>;
+  /** This layer's popup options, over the map's `popup` defaults. */
+  popupOptions?: PopupOptions;
+  /** Shown while this layer's popup content is a pending promise (HTML string or DOM node; default pulsing dots). */
+  popupLoading?: string | Node;
+  /** Auto Zoom: a click on pins piled up zooms in around it, or lists them close up (default true). */
+  autoZoom?: boolean;
+  /** In 3D, W / S tilt and A / D turn the view while the map has focus (default true). */
+  keyboard3D?: boolean;
   onClick?: (feature: GeoJSONFeature, event: LayerClickEvent) => void;
 }
 
+/**
+ * A value drawn per feature: a constant (`'#e6194b'`, `3`), a feature property (`{ property: 'status_color' }`, with
+ * `default` for features without it), or an engine expression (an array, e.g. `['get', 'color']`).
+ */
+export type StyleValue<T = string> = T | { property: string; default?: T } | unknown[];
+
+/** Pins like Superroute's route map, drawn on the GPU (one image per colour pair, made when first shown). */
+export interface MarkerOptions {
+  /** `pin` (default: a teardrop whose tip is at the position) or `circle` (centred on it). */
+  shape?: 'pin' | 'circle' | 'vehicle';
+  /** Inside colour (default white). */
+  fill?: StyleValue;
+  /** Border colour (default the layer's `color`). */
+  border?: StyleValue;
+  /** Border width in pixels (default 3). */
+  borderWidth?: number;
+  /** Width of the pin in pixels (default 32). */
+  size?: number;
+  /** The text in the pin, e.g. the stop number; none when empty. */
+  text?: StyleValue<string | number>;
+  /** Text colour (default white). */
+  textColor?: StyleValue;
+  /** A red count badge at the pin's upper right, shown when the value is more than 1. */
+  badge?: StyleValue<number>;
+  /** Numbers from this zoom on (pins without numbers below it, so a crowded overview stays readable). */
+  /** Size factor of the pin, its number and its badge together: a number or an engine expression, e.g. of the zoom. Default 1. */
+  scale?: number | unknown[];
+  /** The pin under the pointer comes to the front (default true). */
+  hoverRaise?: boolean;
+  /** From this zoom on (default 13) the number is drawn into the pin, so an upper pin covers a lower one completely; false keeps it a separate layer. */
+  bakeZoom?: number | false;
+  /**
+   * Pins piled up under a click (default on): with `threshold` (4) or more within `radius` (12 px) the map zooms in by
+   * `zoomBy` (2) up to `maxZoom` (17); close up, or for pins at one spot, a chooser lists them (`label(properties)`).
+   * `false` turns it off.
+   */
+  overlap?: false | { threshold?: number; radius?: number; zoomBy?: number; maxZoom?: number; label?: (properties: Record<string, unknown>, feature: GeoJSONFeature) => string };
+  /** Opacity of the pin, its number and its badge (default 1). */
+  opacity?: StyleValue<number>;
+  textMinzoom?: number;
+  /** Badges from this zoom on. */
+  badgeMinzoom?: number;
+}
+
 export interface PointOptions extends CommonLayerOptions {
+  /** Route-map pins instead of circles or an icon. */
+  marker?: MarkerOptions;
   /** Groups nearby points into circles sized by their count; a click zooms in to split them. */
   cluster?: boolean | { radius?: number; maxZoom?: number };
   clusterColor?: string;
@@ -71,14 +155,23 @@ export interface PointOptions extends CommonLayerOptions {
   iconAnchor?: string;
   /** The property written under each point. */
   label?: string;
+  /** Where the label sits: below the point (default) or 'right' of it. */
+  labelPosition?: 'below' | 'right';
 }
 
 export interface LineOptions extends CommonLayerOptions {
-  color?: string;
+  /** A colour, or one per feature (`{ property: 'color' }` or an expression): one layer for many routes. */
+  color?: StyleValue;
   width?: number;
   /** Dash and gap lengths in line widths, e.g. [2, 2]. */
   dash?: number[];
   opacity?: number;
+  /** A wider line under the line (true: white, 9 px). */
+  casing?: boolean | { color?: StyleValue; width?: number; opacity?: number };
+  /** A shadow line between the casing and the line (true: black, 7 px, opacity 0.3). */
+  shadow?: boolean | { color?: StyleValue; width?: number; opacity?: number };
+  /** Arrowheads along the line in its direction (true: every 80 px, 14 px, the line's colour, opacity 0.8). */
+  arrows?: boolean | { spacing?: number; size?: number; color?: StyleValue; opacity?: number };
 }
 
 export interface PolygonOptions extends CommonLayerOptions {
@@ -122,6 +215,10 @@ export interface MapOptions {
   pitch?: number;
   minZoom?: number;
   maxZoom?: number;
+  /** Default popup options of every layer and of `openPopup`. */
+  popup?: PopupOptions;
+  /** Shown while a popup's content is a pending promise (HTML string or DOM node; default pulsing dots). */
+  popupLoading?: string | Node;
   /** Every other option goes to the rendering engine. */
   [engineOption: string]: unknown;
 }
@@ -163,6 +260,12 @@ export declare class Map {
   layers(): string[];
   fitLayer(id: string, options?: FitOptions): this;
   flyTo(options: FlyToOptions): this;
+  /** Opens the map's popup at a position, closing the one open before (one popup per map). */
+  openPopup(lngLat: LngLatLike, content: PopupContent | Promise<PopupContent>, options?: PopupOptions & { loading?: string | Node }): this;
+  /** Closes the map's popup, if one is open. */
+  closePopup(): this;
+  setAutoZoom(on: boolean): this;
+  autoZoom(): boolean;
   on(type: string, ...args: any[]): this;
   off(type: string, ...args: any[]): this;
   once(type: string, ...args: any[]): any;
@@ -175,11 +278,17 @@ export declare const version: string;
 export declare const styles: StyleFlavor[];
 /** The bundled rendering engine, for anything the SDK does not wrap (loaded on the first call). */
 export declare function getEngine(): any;
+/**
+ * A popup function from a template: every `{name}` becomes the feature's property of that name, HTML-escaped (empty
+ * when missing). The template itself is trusted HTML. Compiled once; it runs only when a popup opens.
+ */
+export declare function popupTemplate(template: string): (properties: Record<string, unknown> | null | undefined, feature?: GeoJSONFeature) => string;
 
 declare const sMap: {
   Map: typeof Map;
   version: string;
   styles: StyleFlavor[];
   getEngine: typeof getEngine;
+  popupTemplate: typeof popupTemplate;
 };
 export default sMap;

package/types/smap.d.mts

@@ -30,8 +30,38 @@ export interface PointInput {
   [property: string]: unknown;
 }
 
-/** Layer data: GeoJSON (a FeatureCollection or a Feature) or an array of points or features. */
-export type LayerData = GeoJSONFeatureCollection | GeoJSONFeature | Array<PointInput | GeoJSONFeature> | null | undefined;
+/** Layer data: GeoJSON (a FeatureCollection, a Feature or a bare geometry) or an array of points or features. */
+export type LayerData = GeoJSONFeatureCollection | GeoJSONFeature | GeoJSONGeometry | Array<PointInput | GeoJSONFeature> | null | undefined;
+
+/**
+ * What a popup shows: an HTML string (inserted as it is and never sanitized, so it must be trusted: escape any feature
+ * data you put in it, or use `popupTemplate`), a DOM node, or a promise of either (the loading state shows meanwhile;
+ * a rejection closes the popup and is reported as the map's `error` event). Nothing (null, undefined, false, '')
+ * opens no popup.
+ */
+export type PopupContent = string | Node | null | undefined | false;
+
+/** How a popup looks and behaves. Layer options are merged over the map's `popup` defaults. */
+export interface PopupOptions {
+  /** Classes added to the popup's element, beside `smap-popup`. */
+  className?: string;
+  /** Largest width: pixels or a CSS length (default 240px). */
+  maxWidth?: number | string;
+  /** Smallest width: pixels or a CSS length. */
+  minWidth?: number | string;
+  /** Distance from the anchor in pixels, or per anchor (default 12). */
+  offset?: number | [number, number] | Record<string, [number, number]>;
+  /** Which side of the popup points at the position; chosen to fit by default. */
+  anchor?: 'center' | 'top' | 'bottom' | 'left' | 'right' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+  /** A close button in the corner (default true). */
+  closeButton?: boolean;
+  /** A click on the map closes it (default true). */
+  closeOnClick?: boolean;
+  /** Focus moves into the popup when it opens (default true). */
+  focusAfterOpen?: boolean;
+  /** Pan the map so the popup is fully visible (default true). */
+  autoPan?: boolean;
+}
 
 /** The event of a click on a layer's feature (the engine's map mouse event). */
 export interface LayerClickEvent {
@@ -50,14 +80,68 @@ interface CommonLayerOptions {
   /** A feature property used as the feature id. */
   idProperty?: string;
   /**
-   * A popup opened on click, from the clicked feature's properties: an HTML string, inserted as it is and never
-   * sanitized (so it must be trusted; escape any feature data you put in it), or a DOM node.
+   * The popup opened when the top feature at a click is this layer's; called only then. A point's popup opens at the
+   * point, a line's or area's where it was clicked. `popupTemplate('<b>{name}</b>')` gives a fast, escaped one.
    */
-  popup?: (properties: Record<string, unknown>, feature: GeoJSONFeature) => string | Node | null | undefined | false;
+  popup?: (properties: Record<string, unknown>, feature: GeoJSONFeature) => PopupContent | Promise<PopupContent>;
+  /** This layer's popup options, over the map's `popup` defaults. */
+  popupOptions?: PopupOptions;
+  /** Shown while this layer's popup content is a pending promise (HTML string or DOM node; default pulsing dots). */
+  popupLoading?: string | Node;
+  /** Auto Zoom: a click on pins piled up zooms in around it, or lists them close up (default true). */
+  autoZoom?: boolean;
+  /** In 3D, W / S tilt and A / D turn the view while the map has focus (default true). */
+  keyboard3D?: boolean;
   onClick?: (feature: GeoJSONFeature, event: LayerClickEvent) => void;
 }
 
+/**
+ * A value drawn per feature: a constant (`'#e6194b'`, `3`), a feature property (`{ property: 'status_color' }`, with
+ * `default` for features without it), or an engine expression (an array, e.g. `['get', 'color']`).
+ */
+export type StyleValue<T = string> = T | { property: string; default?: T } | unknown[];
+
+/** Pins like Superroute's route map, drawn on the GPU (one image per colour pair, made when first shown). */
+export interface MarkerOptions {
+  /** `pin` (default: a teardrop whose tip is at the position) or `circle` (centred on it). */
+  shape?: 'pin' | 'circle' | 'vehicle';
+  /** Inside colour (default white). */
+  fill?: StyleValue;
+  /** Border colour (default the layer's `color`). */
+  border?: StyleValue;
+  /** Border width in pixels (default 3). */
+  borderWidth?: number;
+  /** Width of the pin in pixels (default 32). */
+  size?: number;
+  /** The text in the pin, e.g. the stop number; none when empty. */
+  text?: StyleValue<string | number>;
+  /** Text colour (default white). */
+  textColor?: StyleValue;
+  /** A red count badge at the pin's upper right, shown when the value is more than 1. */
+  badge?: StyleValue<number>;
+  /** Numbers from this zoom on (pins without numbers below it, so a crowded overview stays readable). */
+  /** Size factor of the pin, its number and its badge together: a number or an engine expression, e.g. of the zoom. Default 1. */
+  scale?: number | unknown[];
+  /** The pin under the pointer comes to the front (default true). */
+  hoverRaise?: boolean;
+  /** From this zoom on (default 13) the number is drawn into the pin, so an upper pin covers a lower one completely; false keeps it a separate layer. */
+  bakeZoom?: number | false;
+  /**
+   * Pins piled up under a click (default on): with `threshold` (4) or more within `radius` (12 px) the map zooms in by
+   * `zoomBy` (2) up to `maxZoom` (17); close up, or for pins at one spot, a chooser lists them (`label(properties)`).
+   * `false` turns it off.
+   */
+  overlap?: false | { threshold?: number; radius?: number; zoomBy?: number; maxZoom?: number; label?: (properties: Record<string, unknown>, feature: GeoJSONFeature) => string };
+  /** Opacity of the pin, its number and its badge (default 1). */
+  opacity?: StyleValue<number>;
+  textMinzoom?: number;
+  /** Badges from this zoom on. */
+  badgeMinzoom?: number;
+}
+
 export interface PointOptions extends CommonLayerOptions {
+  /** Route-map pins instead of circles or an icon. */
+  marker?: MarkerOptions;
   /** Groups nearby points into circles sized by their count; a click zooms in to split them. */
   cluster?: boolean | { radius?: number; maxZoom?: number };
   clusterColor?: string;
@@ -71,14 +155,23 @@ export interface PointOptions extends CommonLayerOptions {
   iconAnchor?: string;
   /** The property written under each point. */
   label?: string;
+  /** Where the label sits: below the point (default) or 'right' of it. */
+  labelPosition?: 'below' | 'right';
 }
 
 export interface LineOptions extends CommonLayerOptions {
-  color?: string;
+  /** A colour, or one per feature (`{ property: 'color' }` or an expression): one layer for many routes. */
+  color?: StyleValue;
   width?: number;
   /** Dash and gap lengths in line widths, e.g. [2, 2]. */
   dash?: number[];
   opacity?: number;
+  /** A wider line under the line (true: white, 9 px). */
+  casing?: boolean | { color?: StyleValue; width?: number; opacity?: number };
+  /** A shadow line between the casing and the line (true: black, 7 px, opacity 0.3). */
+  shadow?: boolean | { color?: StyleValue; width?: number; opacity?: number };
+  /** Arrowheads along the line in its direction (true: every 80 px, 14 px, the line's colour, opacity 0.8). */
+  arrows?: boolean | { spacing?: number; size?: number; color?: StyleValue; opacity?: number };
 }
 
 export interface PolygonOptions extends CommonLayerOptions {
@@ -122,6 +215,10 @@ export interface MapOptions {
   pitch?: number;
   minZoom?: number;
   maxZoom?: number;
+  /** Default popup options of every layer and of `openPopup`. */
+  popup?: PopupOptions;
+  /** Shown while a popup's content is a pending promise (HTML string or DOM node; default pulsing dots). */
+  popupLoading?: string | Node;
   /** Every other option goes to the rendering engine. */
   [engineOption: string]: unknown;
 }
@@ -163,6 +260,12 @@ export declare class Map {
   layers(): string[];
   fitLayer(id: string, options?: FitOptions): this;
   flyTo(options: FlyToOptions): this;
+  /** Opens the map's popup at a position, closing the one open before (one popup per map). */
+  openPopup(lngLat: LngLatLike, content: PopupContent | Promise<PopupContent>, options?: PopupOptions & { loading?: string | Node }): this;
+  /** Closes the map's popup, if one is open. */
+  closePopup(): this;
+  setAutoZoom(on: boolean): this;
+  autoZoom(): boolean;
   on(type: string, ...args: any[]): this;
   off(type: string, ...args: any[]): this;
   once(type: string, ...args: any[]): any;
@@ -175,11 +278,17 @@ export declare const version: string;
 export declare const styles: StyleFlavor[];
 /** The bundled rendering engine, for anything the SDK does not wrap (loaded on the first call). */
 export declare function getEngine(): any;
+/**
+ * A popup function from a template: every `{name}` becomes the feature's property of that name, HTML-escaped (empty
+ * when missing). The template itself is trusted HTML. Compiled once; it runs only when a popup opens.
+ */
+export declare function popupTemplate(template: string): (properties: Record<string, unknown> | null | undefined, feature?: GeoJSONFeature) => string;
 
 declare const sMap: {
   Map: typeof Map;
   version: string;
   styles: StyleFlavor[];
   getEngine: typeof getEngine;
+  popupTemplate: typeof popupTemplate;
 };
 export default sMap;