@ranamaps/maps-js 0.0.0-stage → 0.4.0-beta.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,35 @@
1
+ import { type LocationRouteOptions, type LocationRouteStatus } from "./location-route.js";
2
+ import type { LocationFix } from "./location.js";
3
+ import type { LocationActivity } from "./settings.js";
4
+ import type { LatLng } from "./types.js";
5
+ export interface MotionFrame {
6
+ point: LatLng;
7
+ heading?: number;
8
+ routeProgress?: number;
9
+ }
10
+ /** Renderer-independent, bounded interpolation. All animation times are monotonic seconds. */
11
+ export declare class LocationMotionState {
12
+ private route?;
13
+ private routeFrom?;
14
+ private routeTo?;
15
+ private routeVehicle;
16
+ private routeHoldHeading?;
17
+ get routeStatus(): LocationRouteStatus;
18
+ setRoute(path: readonly LatLng[] | null, options?: LocationRouteOptions): void;
19
+ private fix?;
20
+ private from?;
21
+ private target?;
22
+ private start;
23
+ private duration;
24
+ private fromHeading?;
25
+ private heading?;
26
+ private headingStart;
27
+ private headingDuration;
28
+ private headingTimestamp;
29
+ reset(): void;
30
+ sample(now: number): MotionFrame | undefined;
31
+ active(now: number): boolean;
32
+ private turn;
33
+ deviceHeading(heading: number, timestamp: number, accuracy: number | undefined, now: number, smooth: boolean): boolean;
34
+ push(fix: LocationFix, now: number, smooth: boolean, activity: LocationActivity, allowRoute?: boolean): boolean;
35
+ }
@@ -0,0 +1,30 @@
1
+ import type { LatLng } from "./types.js";
2
+ import type { LocationFix } from "./location.js";
3
+ import type { LocationActivity } from "./settings.js";
4
+ export interface LocationRouteOptions {
5
+ maxSnapDistanceMetres?: number;
6
+ maxAccuracyMetres?: number;
7
+ headingLookAheadMetres?: number;
8
+ }
9
+ export type LocationRouteState = "none" | "matched" | "uncertain" | "off-route";
10
+ /** Progress is the last confidently matched fix's distance along the supplied route, not animated progress. */
11
+ export interface LocationRouteStatus {
12
+ readonly state: LocationRouteState;
13
+ readonly distanceFromRouteMetres?: number;
14
+ readonly progressMetres?: number;
15
+ }
16
+ export declare function routeDistance(a: LatLng, b: LatLng): number;
17
+ /** Local matching against host-supplied ordered geometry; no requests or road-network inference. */
18
+ export declare class LocationRoute {
19
+ readonly options: Required<LocationRouteOptions>;
20
+ private segments;
21
+ private last?;
22
+ private value;
23
+ get status(): LocationRouteStatus;
24
+ constructor(path: readonly LatLng[], options?: LocationRouteOptions);
25
+ reset(): void;
26
+ uncertain(): void;
27
+ pointAt(progress: number): LatLng;
28
+ headingAt(progress: number): number;
29
+ match(fix: LocationFix, activity: LocationActivity): number | undefined;
30
+ }
@@ -0,0 +1,38 @@
1
+ import type { LatLng } from "./types.js";
2
+ import { RanaError } from "./errors.js";
3
+ export interface LocationFix {
4
+ point: LatLng;
5
+ accuracyMetres?: number;
6
+ heading?: number;
7
+ timestampMs?: number;
8
+ speedMetresPerSecond?: number;
9
+ courseAccuracyDegrees?: number;
10
+ }
11
+ export interface HeadingFix {
12
+ heading: number;
13
+ accuracyDegrees?: number;
14
+ timestampMs?: number;
15
+ }
16
+ /** Optional separate compass stream. Heading is the screen's forward direction, clockwise from north. */
17
+ export interface HeadingProvider {
18
+ startHeading(onHeading: (fix: HeadingFix) => void): void;
19
+ stopHeading(): void;
20
+ }
21
+ /** One subscription per instance; callbacks run on the browser event loop. */
22
+ export interface LocationProvider {
23
+ start(onLocation: (fix: LocationFix) => void, onError: (error: RanaError) => void): void;
24
+ stop(): void;
25
+ }
26
+ /** Starts only when connected by the host. The browser controls its own permission prompt; requires a secure context. */
27
+ export declare class BrowserLocationProvider implements LocationProvider, HeadingProvider {
28
+ #private;
29
+ private readonly options;
30
+ private readonly headingDeclinationDegrees;
31
+ constructor(options?: PositionOptions, headingDeclinationDegrees?: number);
32
+ start(onLocation: (fix: LocationFix) => void, onError: (error: RanaError) => void): void;
33
+ /** Call from a user gesture when enabling walking on browsers that require orientation permission. */
34
+ requestHeadingPermission(): Promise<boolean>;
35
+ startHeading(onHeading: (fix: HeadingFix) => void): void;
36
+ stopHeading(): void;
37
+ stop(): void;
38
+ }
package/dist/map.d.ts ADDED
@@ -0,0 +1,356 @@
1
+ import type { JourneyTraceRecorder } from "./journey-trace.js";
2
+ import { type ReroutingOptions, type ReroutingProvider, type ReroutingStatus } from "./rerouting.js";
3
+ import type { LocationRouteOptions, LocationRouteStatus } from "./location-route.js";
4
+ import type { HeadingFix } from "./location.js";
5
+ import type { LatLng, Line } from "./types.js";
6
+ import { type LocationProvider, type LocationFix } from "./location.js";
7
+ import { type MapSettings, type CameraOptions, type CameraState, type MapPadding, type AttributionOptions, type LocationTracking, type DataLayerOptions, type GeoJsonSource, type StyleLayer, type RenderedFeature } from "./settings.js";
8
+ import { VehicleAppearance, type TravellerAppearance, type VehicleState } from "./vehicle.js";
9
+ import { type LinePreset } from "./kit-render.js";
10
+ export type { LinePreset } from "./kit-render.js";
11
+ export declare const ATTRIBUTION = "\u00A9 Rana Maps \u00A9 OpenStreetMap";
12
+ export declare const STYLE_URLS: {
13
+ readonly day: "https://assets.ranamaps.com/style/maps-day";
14
+ readonly night: "https://assets.ranamaps.com/style/maps-night";
15
+ };
16
+ export type MapStyle = "day" | "night" | string;
17
+ export type MapEvent = "load" | "click" | "moveend" | "error" | "move" | "idle" | "styleload" | "longpress" | "trackingchange";
18
+ export interface MapClick {
19
+ lat: number;
20
+ lng: number;
21
+ }
22
+ export type ControlCorner = "top-left" | "top-right" | "bottom-left" | "bottom-right";
23
+ export type ControlSetting = boolean | ControlCorner;
24
+ export interface MapControls {
25
+ compass?: ControlSetting;
26
+ zoom?: ControlSetting;
27
+ locate?: ControlSetting;
28
+ scale?: ControlSetting;
29
+ fullscreen?: ControlSetting;
30
+ }
31
+ export interface MapOptions {
32
+ /** A public key (pk_live_…) limited to this site's origin. */
33
+ key: string;
34
+ container: string | HTMLElement;
35
+ /** "day" (default), "night", a published style code from Rana Studio, or a style URL on ranamaps.com. */
36
+ style?: MapStyle;
37
+ center?: LatLng;
38
+ zoom?: number;
39
+ minZoom?: number;
40
+ maxZoom?: number;
41
+ /** Allow panning and zooming. Default true. */
42
+ interactive?: boolean;
43
+ /** Health events (map started, style loaded, tile errors). Default true. Never location or viewport. */
44
+ telemetry?: boolean;
45
+ /** Base of the web services, for telemetry. Default https://maps-api.ranamaps.com. */
46
+ apiBase?: string;
47
+ /** Rana controls. Phones default to compass, locate and scale; wider maps also show zoom and fullscreen. */
48
+ controls?: MapControls;
49
+ settings?: MapSettings;
50
+ padding?: MapPadding;
51
+ attribution?: AttributionOptions;
52
+ bearing?: number;
53
+ pitch?: number;
54
+ }
55
+ export type PinGlyph = "dot" | "none" | "home" | "work" | "star" | "food" | "flag";
56
+ export type MarkerState = "rest" | "selected" | "disabled";
57
+ export type MarkerSize = "S" | "M" | "L";
58
+ export type RouteStopRole = "start" | "waypoint" | "destination";
59
+ export type MarkerAnchor = "center" | "top" | "bottom" | "left" | "right" | "top-left" | "top-right" | "bottom-left" | "bottom-right";
60
+ /**
61
+ * What a marker shows: one member per Rana Kit marker family, plus your own image or element.
62
+ * Kit families are drawn from Rana Kit in any colour; "image" and "view" keep your own artwork.
63
+ */
64
+ export type MarkerContent =
65
+ /** `label` (up to 3 characters: a stop letter, a number) replaces the glyph. */
66
+ /** `drop: true` is the kit's "pick a spot" pin: a white head ringed in the colour, lifted off the ground. */
67
+ {
68
+ kind: "pin";
69
+ glyph?: PinGlyph;
70
+ label?: string;
71
+ size?: MarkerSize;
72
+ drop?: boolean;
73
+ } | {
74
+ kind: "badge";
75
+ text: string;
76
+ icon?: PinGlyph;
77
+ }
78
+ /** `live: true` adds the kit's green presence dot. */
79
+ | {
80
+ kind: "avatar";
81
+ name: string;
82
+ live?: boolean;
83
+ } | {
84
+ kind: "dot";
85
+ }
86
+ /** A pin whose head is your photo, clipped to the kit's head shape; the stem keeps the marker colour. */
87
+ | {
88
+ kind: "photo";
89
+ image: HTMLImageElement;
90
+ }
91
+ /**
92
+ * A route stop: the start ring, a lettered stop or the destination flag, drawn in Night unless you give a colour.
93
+ * `label` (up to 3 characters) is the stop's letter or number.
94
+ */
95
+ | {
96
+ kind: "stop";
97
+ role: RouteStopRole;
98
+ label?: string;
99
+ } | {
100
+ kind: "image";
101
+ image: HTMLImageElement;
102
+ width?: number;
103
+ anchor?: MarkerAnchor;
104
+ } | {
105
+ kind: "view";
106
+ element: HTMLElement;
107
+ anchor?: MarkerAnchor;
108
+ };
109
+ /** Builders for each marker family, e.g. `addMarker(p, MarkerContent.badge("₦2,500"))`. */
110
+ export declare const MarkerContent: {
111
+ pin: (glyph?: PinGlyph, size?: MarkerSize) => MarkerContent;
112
+ labelledPin: (label: string, size?: MarkerSize) => MarkerContent;
113
+ badge: (text: string, icon?: PinGlyph) => MarkerContent;
114
+ /** The "pick a spot" pin shown while a user chooses a place. */
115
+ dropPin: (glyph?: PinGlyph) => MarkerContent;
116
+ avatar: (name: string, live?: boolean) => MarkerContent;
117
+ dot: () => MarkerContent;
118
+ photo: (image: HTMLImageElement) => MarkerContent;
119
+ routeStart: () => MarkerContent;
120
+ routeStop: (label?: string) => MarkerContent;
121
+ routeDestination: () => MarkerContent;
122
+ image: (image: HTMLImageElement, width?: number, anchor?: MarkerAnchor) => MarkerContent;
123
+ view: (element: HTMLElement, anchor?: MarkerAnchor) => MarkerContent;
124
+ };
125
+ /** How any marker is drawn and behaves, whatever its content. */
126
+ export interface MarkerStyle {
127
+ /** #RGB or #RRGGBB. Kit families only; your own images and elements keep their artwork. Default Sun (route stops: Night). */
128
+ color?: string;
129
+ state?: MarkerState;
130
+ /** Higher keys draw above lower ones and win collisions. */
131
+ sortKey?: number;
132
+ rotation?: number;
133
+ offsetX?: number;
134
+ offsetY?: number;
135
+ draggable?: boolean;
136
+ /** Read by screen readers; defaults to the badge text or avatar name. */
137
+ accessibilityLabel?: string;
138
+ }
139
+ /** One callout button. */
140
+ export interface CalloutAction {
141
+ label: string;
142
+ onPress: () => void;
143
+ }
144
+ /**
145
+ * The Rana Kit callout: a name, one line of facts and up to two actions, opened above a marker. Its layout is fixed
146
+ * by the kit (260 wide, 48 px buttons) and follows the map's day or night theme.
147
+ */
148
+ export interface Callout {
149
+ title: string;
150
+ detail?: string;
151
+ primary?: CalloutAction;
152
+ secondary?: CalloutAction;
153
+ }
154
+ export interface Marker {
155
+ readonly content: MarkerContent;
156
+ readonly style: Readonly<MarkerStyle>;
157
+ setPosition(point: LatLng): void;
158
+ /** Replaces what the marker shows, keeping its position, style and handlers. */
159
+ setContent(content: MarkerContent): void;
160
+ /** Changes the given style fields only. */
161
+ setStyle(style: Partial<MarkerStyle>): void;
162
+ setVisible(visible: boolean): void;
163
+ onClick(handler: (event: MouseEvent) => void): this;
164
+ /** Gives the marker a callout that opens when the marker is tapped; null removes it. */
165
+ setCallout(callout: Callout | null): this;
166
+ /** Opens the marker's callout now (one callout is open per map at a time). */
167
+ showCallout(): void;
168
+ hideCallout(): void;
169
+ remove(): void;
170
+ }
171
+ export interface PointsOptions {
172
+ color?: string;
173
+ cluster?: boolean;
174
+ }
175
+ export interface PointsOverlay {
176
+ remove(): void;
177
+ }
178
+ /** Where and how a vehicle starts; its look is its `VehicleAppearance`. */
179
+ export interface VehicleOptions {
180
+ /** Degrees clockwise from north. */
181
+ heading?: number;
182
+ /** Drawn size in px (at least the kit's 36). Default 48; an image or animation's own `size` when it has one. */
183
+ size?: number;
184
+ state?: VehicleState;
185
+ /** What a screen reader says, such as "Tunde's okada, 3 min away". Default: the kit kind and state. */
186
+ accessibilityLabel?: string;
187
+ }
188
+ export interface Vehicle {
189
+ readonly appearance: VehicleAppearance;
190
+ onClick(handler: (event: MouseEvent) => void): this;
191
+ update(point: LatLng, heading: number, durationMs?: number): void;
192
+ setState(state: VehicleState): void;
193
+ /** Swaps the look in place (a rider picks a new bike), keeping position, heading, state and taps. */
194
+ setAppearance(appearance: VehicleAppearance): void;
195
+ remove(): void;
196
+ }
197
+ /** Traffic on a stretch of a route, by the path's vertex indices `from`..`to` (inclusive). */
198
+ export interface LineSegment {
199
+ from: number;
200
+ to: number;
201
+ traffic: "moving" | "slow" | "goSlow" | "closed";
202
+ }
203
+ export interface PolylineOptions {
204
+ preset?: LinePreset;
205
+ /** The part already travelled. Default: the kit's travelled grey for day or night. */
206
+ travelledColor?: string;
207
+ /** Traffic over stretches of the line, in the kit's traffic colours; `closed` is the kit's red dashed road. */
208
+ segments?: LineSegment[];
209
+ /** A wide soft glow under the line (the kit's 14 px at 50%), in the line's colour unless you give one. */
210
+ glow?: boolean | {
211
+ color?: string;
212
+ width?: number;
213
+ opacity?: number;
214
+ };
215
+ /** Draws the whole line under this style layer (for example, place labels). Ignored if the layer is absent. */
216
+ belowLayerId?: string;
217
+ color?: string;
218
+ width?: number;
219
+ outline?: {
220
+ color: string;
221
+ width: number;
222
+ } | "none" | null;
223
+ dash?: "solid" | "dashed" | "dotted";
224
+ cap?: "round" | "butt" | "square";
225
+ arrows?: boolean;
226
+ opacity?: number;
227
+ progress?: number;
228
+ }
229
+ export interface RouteOptions extends PolylineOptions {
230
+ mode?: LinePreset | "bicycle";
231
+ stops?: boolean;
232
+ }
233
+ export interface RouteLine {
234
+ setProgress(progress: number): void;
235
+ /** Restyles the line in place (a tapped alternative becomes the chosen route). Fields left out keep their value. */
236
+ setOptions(options: PolylineOptions): void;
237
+ /** Called when the line is tapped, with a generous touch area. Use it to let people pick an alternative. */
238
+ onClick(handler: (event: MapClick) => void): this;
239
+ remove(): void;
240
+ }
241
+ export interface PolygonOptions {
242
+ color?: string;
243
+ style?: "area" | "avoid";
244
+ selected?: boolean;
245
+ }
246
+ export interface CircleOptions {
247
+ color?: string;
248
+ label?: string;
249
+ }
250
+ export interface Shape {
251
+ remove(): void;
252
+ }
253
+ export interface UserLocationOptions {
254
+ accuracyMetres?: number;
255
+ heading?: number;
256
+ appearance?: TravellerAppearance;
257
+ stale?: boolean;
258
+ }
259
+ /** The style URL for a style option. Style codes are 8 characters from Rana Studio. */
260
+ export declare function styleUrl(style: string | undefined): string;
261
+ export declare const isRanaHost: (host: string) => boolean;
262
+ /** Adds the key to Rana map requests only (as ?key=, so tiles stay cacheable and need no preflight). */
263
+ export declare function transformRequest(key: string): (url: string) => {
264
+ url: string;
265
+ };
266
+ export declare class RanaMap {
267
+ #private;
268
+ /** Replacing/detaching stops the old recorder and drops unsent fixes. */
269
+ setJourneyTraceRecorder(recorder: JourneyTraceRecorder | null): this;
270
+ /** @param engineClass for tests only. */
271
+ constructor(options: MapOptions, engineClass?: new (options: any) => any);
272
+ on(event: "click" | "longpress", handler: (point: MapClick) => void): this;
273
+ on(event: "load" | "moveend" | "styleload", handler: () => void): this;
274
+ on(event: "move" | "idle", handler: (camera: CameraState) => void): this;
275
+ on(event: "trackingchange", handler: (tracking: LocationTracking) => void): this;
276
+ on(event: "error", handler: (error: Error) => void): this;
277
+ off(event: MapEvent, handler: Function): this;
278
+ getCameraState(): CameraState;
279
+ get padding(): Readonly<Required<MapPadding>>;
280
+ get locationTracking(): LocationTracking;
281
+ /** Full configuration replacement. For a moving sheet, use setPadding to preserve every other setting. */
282
+ applySettings(options: MapSettings): this;
283
+ setCamera(options: CameraOptions, animated?: boolean, durationMs?: number, completion?: (finished: boolean) => void): this;
284
+ setPadding(padding: MapPadding): this;
285
+ setAttribution(options: AttributionOptions): this;
286
+ setControls(controls: MapControls): this;
287
+ setTracking(mode: LocationTracking): this;
288
+ setLocationProvider(provider?: LocationProvider | null): this;
289
+ /** Supplies ordered route coordinates for this traveller. Null disables local route matching. */
290
+ setLocationRoute(path: readonly LatLng[] | null, options?: LocationRouteOptions): this;
291
+ /** Opt-in directions requests. Set a location route first; null disables and cancels this trip's session. */
292
+ setAutomaticRerouting(options: ReroutingOptions | null, provider?: ReroutingProvider): this;
293
+ get reroutingStatus(): ReroutingStatus;
294
+ get locationRouteStatus(): LocationRouteStatus;
295
+ /** Supplies a timestamped fix, including optional speed and course accuracy, without a provider. */
296
+ updateLocation(fix: LocationFix): void;
297
+ /** True-north screen heading. Walking uses this independently of location/course updates. */
298
+ updateDeviceHeading(fix: HeadingFix): void;
299
+ setLocateState(state: "off" | "following" | "heading" | "finding" | "off-permission"): this;
300
+ get layerIds(): string[];
301
+ addGeoJsonSource(id: string, data: string | object): GeoJsonSource;
302
+ addLayer(id: string, sourceId: string, options: DataLayerOptions): StyleLayer;
303
+ setLayerVisibility(id: string, visible: boolean): this;
304
+ setLayerColor(id: string, hex: string): this;
305
+ queryFeatures(at: LatLng, layerIds?: string[]): RenderedFeature[];
306
+ getCenter(): LatLng;
307
+ getZoom(): number;
308
+ setCenter(point: LatLng): this;
309
+ setZoom(zoom: number): this;
310
+ /** Moves smoothly to a point and zoom. */
311
+ flyTo(target: CameraOptions): this;
312
+ /** Shows every point, with a margin in pixels. */
313
+ fitPoints(points: LatLng[], padding?: number): this;
314
+ /** "day", "night" or a Studio style code. SDK overlays stay on the map. */
315
+ setStyle(style: MapStyle): this;
316
+ /**
317
+ * Runs `block` and returns its value. On the web each change is already drawn once per frame, so this only keeps
318
+ * code shared with the native SDKs (where `batch` saves a redraw per change) the same.
319
+ */
320
+ batch<T>(block: () => T): T;
321
+ /** Adds many markers, returning their handles in the same order. */
322
+ addMarkers(entries: ReadonlyArray<{
323
+ point: LatLng;
324
+ content?: MarkerContent;
325
+ style?: MarkerStyle;
326
+ }>): Marker[];
327
+ /** Adds a marker: any Rana Kit family (`MarkerContent.pin()`, `.badge()`, `.avatar()`, `.dot()`) or your own image or element. */
328
+ addMarker(point: LatLng, content?: MarkerContent, markerStyle?: MarkerStyle): Marker;
329
+ /** Adds points through a clustered GeoJSON source. A tapped cluster zooms to its next level. */
330
+ addPoints(points: LatLng[], options?: PointsOptions): PointsOverlay;
331
+ /**
332
+ * A vehicle that glides between updates: a Rana Kit vehicle (`VehicleAppearance.kit("okada")`) or your own image,
333
+ * animation or element. Position and heading interpolate with requestAnimationFrame.
334
+ */
335
+ addVehicle(point: LatLng, appearance?: VehicleAppearance, options?: VehicleOptions): Vehicle;
336
+ /** Adds a kit line with an outline, optional travel progress and directional arrows. */
337
+ addPolyline(path: Line | LatLng[], options?: PolylineOptions): RouteLine;
338
+ /** Alias for addPolyline. Existing color and width options remain supported. */
339
+ showRoute(line: Line | LatLng[], options?: RouteOptions): RouteLine;
340
+ /** Adds an area or per-request avoid polygon. It does not change the routing graph. */
341
+ addPolygon(rings: LatLng[][], options?: PolygonOptions): Shape;
342
+ /** Draws a geodesic 64 point circle as a polygon. */
343
+ addCircle(center: LatLng, radiusMetres: number, options?: CircleOptions): Shape;
344
+ /** Shows the user's own position from Rana Kit. */
345
+ showUserLocation(point: LatLng, options?: UserLocationOptions): void;
346
+ hideUserLocation(): void;
347
+ /** The key this map uses. */
348
+ get key(): string;
349
+ /** Removes the map, custom controls and any waiting health events. */
350
+ remove(): void;
351
+ }
352
+ /**
353
+ * Raises a pin SVG by the kit's drag lift: the pin floats above a ground dot with a wider, fainter shadow. The ground
354
+ * (and so the marker's anchor) stays where it was; the SVG grows upwards to fit.
355
+ */
356
+ export declare function liftPin(svg: string, size: number): string;
@@ -0,0 +1,3 @@
1
+ import type { LatLng } from "./types.js";
2
+ /** Decodes an encoded polyline (precision 6 on /v1). */
3
+ export declare function decodePolyline(value: string, precision?: number): LatLng[];