MapView

1import { YeriaApp } from '@numerum-tech/yeriasdk';
2
3const yeriaApp = new YeriaApp({ appId: 'my-app' });
4
5// `addMarker` is a convenience method — under the hood it appends to a
6// default markers layer, creating it on first call. The wire payload that
7// reaches the renderer is always shaped as `{ layers: [...] }`.
8const map = yeriaApp.createMapView('stores-map', 'Partner Stores')
9  .setIntro('Find our partner stores')
10  .setViewport({ center: { lat: 48.8566, lon: 2.3522 }, zoom: 12 })
11  .setControls({ zoom: true, userLocation: true, layerToggle: true })
12  .addMarker({
13    id: 'paris',
14    location: { lat: 48.8566, lon: 2.3522 },
15    title: 'Paris Centre',
16    description: 'Open 9–19',
17    icon: 'store',
18    action: { method: 'GET', url: '/api/stores/paris' }
19  });
20
21return yeriaApp.serve(map);

1interface MapView {
2  id: string;
3  type: 'Map';
4  content: MapContent;
5  metadata?: ViewMetadata;
6  process?: ProcessContext;
7}
8
9interface MapContent {
10  // Header
11  title: string;
12  intro?: string;
13
14  // Camera
15  viewport?: MapViewport;
16  basemap?: 'streets' | 'satellite' | 'terrain' | 'dark' | 'auto'; // default 'auto'
17
18  // Data — always layered
19  layers: MapLayer[];
20
21  // UI
22  controls?: MapControls;
23  emptyMessage?: string;      // shown if no layer ends up drawable
24
25  // Input mode (location picker)
26  mode?: 'view' | 'pick';     // default 'view'
27  pick?: MapPickConfig;       // required when mode === 'pick'
28}

1interface GeoPoint {
2  lat: number;       // -90 to 90
3  lon: number;       // -180 to 180
4  altitude?: number; // meters above sea level
5  precision?: number;// horizontal accuracy in meters (sensor data)
6}

1interface MapMarker {
2  id: string;
3  location: GeoPoint;
4
5  // Display
6  title?: string;
7  description?: string;
8  icon?: string;          // catalog name OR full URL OR data: URI
9  color?: string;         // hex string, e.g. '#1A73E8'; falls back to renderer default
10  size?: 'sm' | 'md' | 'lg'; // default 'md'
11  selected?: boolean;     // renderer should highlight; default false
12
13  // Interaction
14  action?: ActionRef;     // see "Actions"
15  popup?: MarkerPopup;    // overrides the default title+description popup
16
17  // Free-form
18  meta?: Record<string, unknown>;
19}
20
21interface MarkerPopup {
22  title?: string;         // defaults to marker.title
23  body?: string;          // markdown allowed
24  image?: string;         // URL
25  actions?: ActionRef[];  // buttons inside the popup
26}

1type MapShape = PolygonShape | CircleShape | PolylineShape | RectangleShape;
2
3interface ShapeBase {
4  id: string;
5  config?: ShapeStyle;
6  action?: ActionRef;     // optional click handler
7  meta?: Record<string, unknown>;
8}
9
10interface PolygonShape extends ShapeBase {
11  type: 'Polygon';
12  points: GeoPoint[];     // 3+ points; the polygon auto-closes
13}
14
15interface CircleShape extends ShapeBase {
16  type: 'Circle';
17  center: GeoPoint;
18  radius: number;         // meters
19}
20
21interface PolylineShape extends ShapeBase {
22  type: 'Polyline';
23  points: GeoPoint[];     // 2+ points
24}
25
26interface RectangleShape extends ShapeBase {
27  type: 'Rectangle';
28  sw: GeoPoint;           // south-west corner
29  ne: GeoPoint;           // north-east corner
30}
31
32interface ShapeStyle {
33  fillColor?: string;
34  fillOpacity?: number;   // 0–1
35  strokeColor?: string;
36  strokeOpacity?: number; // 0–1
37  strokeWidth?: number;   // px
38  dashed?: boolean;
39}

1interface MapViewport {
2  // Pick ONE of (center+zoom) or (bounds) or (fitMarkers)
3  center?: GeoPoint;
4  zoom?: number;          // typical 0–22
5  bounds?: { sw: GeoPoint; ne: GeoPoint };
6  fitMarkers?: boolean;   // if true, renderer fits viewport to all visible markers + shapes; takes precedence
7
8  // Constraints
9  minZoom?: number;
10  maxZoom?: number;
11
12  // 3D — renderer may ignore if unsupported (must NOT throw)
13  bearing?: number;       // 0–360, default 0
14  pitch?: number;         // 0–60, default 0
15}

1interface MapControls {
2  zoom?: boolean;            // zoom +/- buttons; default true
3  compass?: boolean;         // shown when bearing != 0; default true
4  userLocation?: boolean;    // "locate me" button; default false
5  layerToggle?: boolean;     // legend / show-hide panel; default true if any layer is `toggleable`
6  scale?: boolean;           // distance scale; default false
7  fullscreen?: boolean;      // default false
8  attribution?: string;      // override; renderer must always show some attribution
9}

1type MapLayer =
2  | MarkersLayer
3  | ShapesLayer
4  | HeatmapLayer
5  | TilesLayer
6  | GeoJsonLayer;
7
8interface LayerBase {
9  id: string;                // stable id; clients persist toggle state by id
10  name?: string;             // shown in legend / toggle UI
11  legendIcon?: string;       // icon shown next to `name`
12  visible?: boolean;         // default true
13  toggleable?: boolean;      // user can show/hide; default true
14  zIndex?: number;           // higher = on top; default by insertion order
15  minZoom?: number;          // hide below this zoom
16  maxZoom?: number;          // hide above this zoom
17}
18
19interface MarkersLayer extends LayerBase {
20  type: 'markers';
21  markers: MapMarker[];
22  cluster?: boolean;         // default true when markers.length > 50
23  clusterRadius?: number;    // px; default 50
24}
25
26interface ShapesLayer extends LayerBase {
27  type: 'shapes';
28  shapes: MapShape[];
29}
30
31interface HeatmapLayer extends LayerBase {
32  type: 'heatmap';
33  points: Array<{ lat: number; lon: number; intensity?: number }>;
34  radius?: number;           // px; default 25
35  intensityMax?: number;     // default 1
36  colorRamp?: string[];      // hex stops, low-to-high; renderer default if omitted
37}
38
39interface TilesLayer extends LayerBase {
40  type: 'tiles';
41  url: string;               // {z}/{x}/{y} template
42  attribution: string;       // required by most providers
43  maxNativeZoom?: number;
44  opacity?: number;          // 0–1
45}
46
47interface GeoJsonLayer extends LayerBase {
48  type: 'geojson';
49  data: object;              // RFC 7946 FeatureCollection | Feature | Geometry
50  // Defaults applied to features that lack `properties.style`:
51  defaultMarkerIcon?: string;
52  defaultShapeStyle?: ShapeStyle;
53}

1// Simple case — no layer ceremony
2map.addMarker({ id: 'home', location: { lat: 6.13, lon: 1.22 } });
3//  → goes into _default_markers (auto-created)
4
5// Multi-layer case — declare, then target
6map
7  .addLayer({ id: 'stores', type: 'markers', name: 'Boutiques', cluster: true })
8  .addLayer({ id: 'events', type: 'markers', name: 'Événements' });
9
10map.addMarker({ id: 'paris', location: { lat: 48.85, lon: 2.35 } }, 'stores');
11map.addMarker({ id: 'fest',  location: { lat: 43.60, lon: 1.44 } }, 'events');

1interface MapPickConfig {
2  prompt?: string;                 // helper text above the map; e.g. "Tap to choose your delivery point"
3  initialLocation?: GeoPoint;
4  submitUrl: string;               // URL the picked location is POSTed to
5  submitMethod?: 'POST' | 'PUT';   // default POST
6  submitLabel?: string;            // confirm button label; default "Confirm"
7  payloadKey?: string;             // key under which the location is sent; default 'location'
8  bounds?: { sw: GeoPoint; ne: GeoPoint }; // restrict pickable area
9  snapToMarkers?: boolean;         // default false; if true, picking snaps to the nearest existing marker
10}

1interface ActionRef {
2  url: string;
3  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'; // default GET
4  body?: Record<string, unknown>;
5  confirm?: { title: string; message: string; submitLabel?: string };
6}

1{
2  "id": "logistics",
3  "type": "Map",
4  "content": {
5    "title": "Logistique – Région du Centre",
6    "intro": "Aperçu en temps réel des points de livraison et zones de couverture.",
7    "basemap": "auto",
8    "viewport": { "fitMarkers": true, "minZoom": 6, "maxZoom": 18 },
9    "controls": {
10      "zoom": true, "compass": true, "userLocation": true,
11      "layerToggle": true, "scale": true
12    },
13    "layers": [
14      {
15        "id": "stores",
16        "type": "markers",
17        "name": "Boutiques",
18        "legendIcon": "store",
19        "cluster": true,
20        "markers": [
21          {
22            "id": "store-lome",
23            "location": { "lat": 6.1319, "lon": 1.2228 },
24            "title": "Boutique Lomé Centre",
25            "description": "Ouvert 8h–20h",
26            "icon": "store",
27            "color": "#1A73E8",
28            "action": { "method": "GET", "url": "/api/stores/lome" }
29          }
30        ]
31      },
32      {
33        "id": "coverage",
34        "type": "shapes",
35        "name": "Zone de livraison",
36        "visible": true,
37        "toggleable": true,
38        "zIndex": -1,
39        "shapes": [
40          {
41            "id": "delivery-zone",
42            "type": "Polygon",
43            "points": [
44              { "lat": 6.20, "lon": 1.18 },
45              { "lat": 6.20, "lon": 1.30 },
46              { "lat": 6.05, "lon": 1.30 },
47              { "lat": 6.05, "lon": 1.18 }
48            ],
49            "config": { "fillColor": "#34A853", "fillOpacity": 0.15, "strokeColor": "#34A853", "strokeWidth": 2 }
50          }
51        ]
52      },
53      {
54        "id": "traffic",
55        "type": "heatmap",
56        "name": "Trafic",
57        "visible": false,
58        "points": [
59          { "lat": 6.13, "lon": 1.22, "intensity": 0.9 },
60          { "lat": 6.14, "lon": 1.23, "intensity": 0.6 }
61        ]
62      }
63    ]
64  },
65  "metadata": { "version": "2.0.0", "createdAt": "2026-04-26T08:00:00.000Z" }
66}