@superrouteca/smap-react-native 0.0.0-stage → 1.0.0

package/src/SMap.tsx

@@ -0,0 +1,226 @@
+import * as React from 'react';
+import {
+  createContext,
+  forwardRef,
+  useCallback,
+  useContext,
+  useEffect,
+  useImperativeHandle,
+  useRef,
+  useState,
+} from 'react';
+import { StyleSheet, View } from 'react-native';
+import type { NativeSyntheticEvent, StyleProp, ViewProps, ViewStyle } from 'react-native';
+import NativeSMapView, { Commands } from './SMapNativeViewNativeComponent';
+import { cameraJson, toFeatureCollection, toLatLng, type LayerData, type LngLatLike } from './geojson';
+
+export type StyleFlavor = 'light' | 'white' | 'grayscale' | 'dark' | 'black';
+export const styles: StyleFlavor[] = ['light', 'white', 'grayscale', 'dark', 'black'];
+
+export type LayerKind = 'points' | 'lines' | 'polygons';
+
+/** Called with the tapped feature's properties and its position. */
+export type TapHandler = (properties: Record<string, unknown>, position: { lat: number; lng: number }) => void;
+
+/** The map, as the ref of `<SMap>` and `useSMap()` give it once it is ready. */
+export interface SMapHandle {
+  addPoints(id: string, data: LayerData, options?: Record<string, unknown>): void;
+  addLines(id: string, data: LayerData, options?: Record<string, unknown>): void;
+  addPolygons(id: string, data: LayerData, options?: Record<string, unknown>): void;
+  /** Replaces a layer's data and keeps its look. */
+  setData(id: string, data: LayerData): void;
+  setVisible(id: string, visible: boolean): void;
+  removeLayer(id: string): void;
+  /** Layer ids in draw order, bottom first. */
+  layers(): string[];
+  /** Moves the camera to show a layer's data; padding in points (40), maxZoom 15. */
+  fitLayer(id: string, options?: { padding?: number; maxZoom?: number }): void;
+  flyTo(center: LngLatLike, zoom?: number): void;
+  /** Calls `handler` when a feature of layer `id` is tapped (null removes it). */
+  onTap(id: string, handler: TapHandler | null): void;
+  setStyle(style: StyleFlavor): void;
+  setLanguage(language: string): void;
+  setBuildings3D(on: boolean): void;
+}
+
+const MapContext = createContext<SMapHandle | null>(null);
+
+/** The map of the nearest `<SMap>` above, once it is ready (null before). */
+export function useSMap(): SMapHandle | null {
+  return useContext(MapContext);
+}
+
+export interface SMapProps extends Omit<ViewProps, 'style'> {
+  /** A map key (`smk_…`) whose allowlist names this app. Read when the map is created. */
+  apiKey?: string;
+  /** A map token. Read when the map is created; changing it creates the map again (use `getToken` to renew). */
+  token?: string;
+  /** Called at start when no token is given and again two minutes before each token expires. */
+  getToken?: () => string | Promise<string>;
+  /** The colour scheme (layers are kept on a change). A style object here is taken as `containerStyle`. */
+  style?: StyleFlavor | StyleProp<ViewStyle>;
+  /** Label language (`en`, `fr`, `zh-Hans`, …); the device language by default. Layers are kept on a change. */
+  language?: string;
+  /** [longitude, latitude] or `{lng, lat}`; the camera follows a change. */
+  center?: LngLatLike;
+  zoom?: number;
+  bearing?: number;
+  pitch?: number;
+  /** Node URLs known in advance, used while `baseUrl` is down. */
+  nodes?: string[];
+  /** The map service, `https://tile.srsr.ca` by default. */
+  baseUrl?: string;
+  /** Read from the nearest service node (default true). */
+  nearest?: boolean;
+  /** Buildings in 3D. */
+  buildings3D?: boolean;
+  /** Called once the first style has loaded. */
+  onReady?: (map: SMapHandle) => void;
+  /** Errors from the map (a failed token, a style that could not load). */
+  onError?: (error: Error) => void;
+  /** The layout of the map view. */
+  containerStyle?: StyleProp<ViewStyle>;
+  children?: React.ReactNode;
+}
+
+type NativeRef = React.ElementRef<typeof NativeSMapView>;
+
+/**
+ * A map view. The ref is the map (`SMapHandle`) once the first style has loaded, null before.
+ */
+export const SMap = forwardRef<SMapHandle | null, SMapProps>(function SMap(props, ref) {
+  const {
+    apiKey, token, getToken, style, language, center, zoom, bearing, pitch, nodes, baseUrl, nearest, buildings3D,
+    onReady, onError, containerStyle, children, ...viewProps
+  } = props;
+  const flavorProp = typeof style === 'string' ? style : undefined;
+  const layoutStyle = typeof style === 'string' ? containerStyle : [containerStyle, style as StyleProp<ViewStyle>];
+
+  const native = useRef<NativeRef | null>(null);
+  const latest = useRef(props);
+  latest.current = props;
+  const [handle, setHandle] = useState<SMapHandle | null>(null);
+  const [flavor, setFlavor] = useState<string>(flavorProp || 'light');
+  const [lang, setLang] = useState<string>(language || '');
+  const [buildings, setBuildings] = useState<boolean>(!!buildings3D);
+  useEffect(() => { if (flavorProp) { setFlavor(flavorProp); } }, [flavorProp]);
+  useEffect(() => { if (language !== undefined) { setLang(language); } }, [language]);
+  useEffect(() => { setBuildings(!!buildings3D); }, [buildings3D]);
+
+  // Read when the native map is created; a change creates it again (the native view gets a new key).
+  const config = JSON.stringify({
+    baseUrl: baseUrl || null,
+    nodes: nodes || [],
+    apiKey: apiKey || null,
+    token: token || null,
+    nearest: nearest !== false,
+    getToken: !!getToken,
+  });
+  const camera = cameraJson({ center, zoom, bearing, pitch });
+
+  // The layers of this map, in the order the native SDKs keep them (zIndex, then the order added).
+  const layers = useRef<{ id: string; zIndex: number }[]>([]);
+  const taps = useRef<Record<string, TapHandler>>({});
+  // A handle works only for the native view it was made for; a new view (new config) makes the old handle inert.
+  const generation = useRef(0);
+  useEffect(() => {
+    generation.current += 1;
+    layers.current = [];
+    taps.current = {};
+    setHandle(null);
+  }, [config]);
+
+  const makeHandle = useCallback((): SMapHandle => {
+    const mine = generation.current;
+    const live = () => generation.current === mine && native.current !== null;
+    const view = () => native.current as NativeRef;
+    const add = (kind: LayerKind, id: string, data: LayerData, options: Record<string, unknown> = {}) => {
+      if (!live()) { return; }
+      const zIndex = typeof options.zIndex === 'number' ? options.zIndex : 0;
+      const rest = layers.current.filter((l) => l.id !== id);
+      rest.push({ id, zIndex });
+      // A stable sort: equal zIndex keeps the order added.
+      layers.current = rest.map((l, i) => ({ l, i })).sort((a, b) => a.l.zIndex - b.l.zIndex || a.i - b.i).map((x) => x.l);
+      Commands.addLayer(view(), kind, id, JSON.stringify(toFeatureCollection(data)), JSON.stringify(options));
+    };
+    return {
+      addPoints: (id, data, options) => add('points', id, data, options),
+      addLines: (id, data, options) => add('lines', id, data, options),
+      addPolygons: (id, data, options) => add('polygons', id, data, options),
+      setData: (id, data) => { if (live()) { Commands.setData(view(), id, JSON.stringify(toFeatureCollection(data))); } },
+      setVisible: (id, visible) => { if (live()) { Commands.setVisible(view(), id, visible); } },
+      removeLayer: (id) => {
+        if (!live()) { return; }
+        layers.current = layers.current.filter((l) => l.id !== id);
+        delete taps.current[id];
+        Commands.removeLayer(view(), id);
+      },
+      layers: () => (live() ? layers.current.map((l) => l.id) : []),
+      fitLayer: (id, options = {}) => { if (live()) { Commands.fitLayer(view(), id, options.padding ?? 40, options.maxZoom ?? 15); } },
+      flyTo: (c, z) => {
+        if (!live()) { return; }
+        const p = toLatLng(c);
+        Commands.flyTo(view(), p.lat, p.lng, typeof z === 'number' ? z : -1);
+      },
+      onTap: (id, handler) => {
+        if (!live()) { return; }
+        if (handler) { taps.current[id] = handler; } else { delete taps.current[id]; }
+      },
+      setStyle: (s) => setFlavor(s),
+      setLanguage: (l) => setLang(l),
+      setBuildings3D: (on) => setBuildings(on),
+    };
+  }, []);
+
+  useImperativeHandle(ref, () => handle as SMapHandle, [handle]);
+
+  const handleReady = useCallback(() => {
+    const h = makeHandle();
+    setHandle(h);
+    latest.current.onReady?.(h);
+  }, [makeHandle]);
+
+  const handleError = useCallback((e: NativeSyntheticEvent<{ message: string }>) => {
+    latest.current.onError?.(new Error(e.nativeEvent.message));
+  }, []);
+
+  const handleTap = useCallback((e: NativeSyntheticEvent<{ layerId: string; properties: string; lat: number; lng: number }>) => {
+    const { layerId, properties, lat, lng } = e.nativeEvent;
+    const handler = taps.current[layerId];
+    if (!handler) { return; }
+    let parsed: Record<string, unknown> = {};
+    try { parsed = JSON.parse(properties || '{}'); } catch { parsed = {}; }
+    handler(parsed, { lat, lng });
+  }, []);
+
+  const handleTokenRequest = useCallback((e: NativeSyntheticEvent<{ requestId: number }>) => {
+    const id = e.nativeEvent.requestId;
+    const answer = (t: string, err: string) => { if (native.current) { Commands.resolveToken(native.current, id, t, err); } };
+    const ask = latest.current.getToken;
+    if (!ask) { answer('', 'sMap: no getToken'); return; }
+    Promise.resolve()
+      .then(() => ask())
+      .then((t) => answer(String(t || ''), t ? '' : 'sMap: getToken gave no token'),
+        (err: unknown) => answer('', 'sMap: ' + (err instanceof Error ? err.message : String(err))));
+  }, []);
+
+  return (
+    <View {...viewProps} style={[{ flex: 1 }, layoutStyle]}>
+      <NativeSMapView
+        key={config}
+        ref={native}
+        style={StyleSheet.absoluteFill}
+        config={config}
+        mapStyle={flavor}
+        language={lang}
+        camera={camera}
+        buildings3D={buildings}
+        onMapReady={handleReady}
+        onMapError={handleError}
+        onLayerTap={handleTap}
+        onTokenRequest={handleTokenRequest}
+      />
+      <MapContext.Provider value={handle}>{children}</MapContext.Provider>
+    </View>
+  );
+});

package/src/SMapNativeViewNativeComponent.ts

@@ -0,0 +1,47 @@
+// The native map view (Fabric component), generated for Android and iOS from this file by the codegen.
+// Values that change shape (options, data, the camera) cross as JSON text.
+import type * as React from 'react';
+import { codegenNativeCommands, codegenNativeComponent } from 'react-native';
+import type { CodegenTypes, HostComponent, ViewProps } from 'react-native';
+
+type ReadyEvent = Readonly<{ node: string }>;
+type ErrorEvent = Readonly<{ message: string }>;
+type TapEvent = Readonly<{ layerId: string; properties: string; lat: CodegenTypes.Double; lng: CodegenTypes.Double }>;
+type TokenRequestEvent = Readonly<{ requestId: CodegenTypes.Int32 }>;
+
+export interface NativeProps extends ViewProps {
+  /** JSON {baseUrl, nodes, apiKey, token, nearest, getToken}: read once, when the native map is created. */
+  config: string;
+  /** The colour scheme. */
+  mapStyle?: string;
+  /** Label language; empty = the device language. */
+  language?: string;
+  /** JSON {lat, lng, zoom, bearing, pitch}: the starting camera, and where it moves when the value changes. */
+  camera?: string;
+  buildings3D?: boolean;
+  onMapReady?: CodegenTypes.DirectEventHandler<ReadyEvent>;
+  onMapError?: CodegenTypes.DirectEventHandler<ErrorEvent>;
+  onLayerTap?: CodegenTypes.DirectEventHandler<TapEvent>;
+  onTokenRequest?: CodegenTypes.DirectEventHandler<TokenRequestEvent>;
+}
+
+export type SMapNativeViewType = HostComponent<NativeProps>;
+
+interface NativeCommands {
+  /** kind: points | lines | polygons; data: GeoJSON FeatureCollection; options: JSON. */
+  addLayer: (view: React.ElementRef<SMapNativeViewType>, kind: string, id: string, data: string, options: string) => void;
+  setData: (view: React.ElementRef<SMapNativeViewType>, id: string, data: string) => void;
+  setVisible: (view: React.ElementRef<SMapNativeViewType>, id: string, visible: boolean) => void;
+  removeLayer: (view: React.ElementRef<SMapNativeViewType>, id: string) => void;
+  fitLayer: (view: React.ElementRef<SMapNativeViewType>, id: string, padding: CodegenTypes.Double, maxZoom: CodegenTypes.Double) => void;
+  /** zoom below 0 keeps the zoom. */
+  flyTo: (view: React.ElementRef<SMapNativeViewType>, lat: CodegenTypes.Double, lng: CodegenTypes.Double, zoom: CodegenTypes.Double) => void;
+  /** The answer to onTokenRequest: a token, or an error message (token empty). */
+  resolveToken: (view: React.ElementRef<SMapNativeViewType>, requestId: CodegenTypes.Int32, token: string, error: string) => void;
+}
+
+export const Commands: NativeCommands = codegenNativeCommands<NativeCommands>({
+  supportedCommands: ['addLayer', 'setData', 'setVisible', 'removeLayer', 'fitLayer', 'flyTo', 'resolveToken'],
+});
+
+export default codegenNativeComponent<NativeProps>('SMapNativeView') as SMapNativeViewType;

package/src/geojson.ts

@@ -0,0 +1,66 @@
+// Layer data and the camera in the shapes the native SDKs read. Same rules as the Web SDK: GeoJSON as given, a
+// Feature wrapped in a collection, an array of points `{lng, lat, …properties}` turned into point features.
+
+export type GeoJSONGeometry = { type: string; coordinates?: unknown; geometries?: unknown[] };
+export interface GeoJSONFeature<P = Record<string, unknown>> {
+  type: 'Feature';
+  id?: string | number;
+  properties: P | null;
+  geometry: GeoJSONGeometry;
+}
+export interface GeoJSONFeatureCollection<P = Record<string, unknown>> {
+  type: 'FeatureCollection';
+  features: GeoJSONFeature<P>[];
+}
+export interface PointInput {
+  lat?: number;
+  lng?: number;
+  lon?: number;
+  latitude?: number;
+  longitude?: number;
+  coordinates?: [number, number];
+  id?: string | number;
+  [property: string]: unknown;
+}
+export type LayerData = GeoJSONFeatureCollection | GeoJSONFeature | Array<PointInput | GeoJSONFeature> | null | undefined;
+
+/** [longitude, latitude] or `{lng, lat}` (`lon` accepted). */
+export type LngLatLike = [number, number] | { lng: number; lat: number } | { lon: number; lat: number };
+
+export function toFeatureCollection(data: LayerData): GeoJSONFeatureCollection {
+  if (!data) { return { type: 'FeatureCollection', features: [] }; }
+  if (Array.isArray(data)) {
+    return {
+      type: 'FeatureCollection',
+      features: data.map((p) => {
+        if (p && (p as GeoJSONFeature).type === 'Feature') { return p as GeoJSONFeature; }
+        const q = p as PointInput;
+        let lng = q.lng !== undefined ? q.lng : q.lon !== undefined ? q.lon : q.longitude;
+        let lat = q.lat !== undefined ? q.lat : q.latitude;
+        if (q.coordinates) { lng = q.coordinates[0]; lat = q.coordinates[1]; }
+        const f: GeoJSONFeature = { type: 'Feature', properties: q as Record<string, unknown>, geometry: { type: 'Point', coordinates: [lng, lat] } };
+        if (q.id !== undefined) { f.id = q.id; }
+        return f;
+      }),
+    };
+  }
+  if (data.type === 'FeatureCollection') { return data; }
+  if (data.type === 'Feature') { return { type: 'FeatureCollection', features: [data] }; }
+  return { type: 'FeatureCollection', features: [] };
+}
+
+export function toLatLng(c: LngLatLike): { lat: number; lng: number } {
+  if (Array.isArray(c)) { return { lng: c[0], lat: c[1] }; }
+  const o = c as { lng?: number; lon?: number; lat: number };
+  return { lng: (o.lng !== undefined ? o.lng : o.lon) as number, lat: o.lat };
+}
+
+/** The camera as JSON, with only the values given. */
+export function cameraJson(camera: { center?: LngLatLike; zoom?: number; bearing?: number; pitch?: number }): string {
+  const out: Record<string, number> = {};
+  if (camera.center) { const p = toLatLng(camera.center); out.lat = p.lat; out.lng = p.lng; }
+  for (const k of ['zoom', 'bearing', 'pitch'] as const) {
+    if (typeof camera[k] === 'number') { out[k] = camera[k] as number; }
+  }
+  return JSON.stringify(out);
+}

package/src/index.tsx

@@ -0,0 +1,6 @@
+export { SMap, useSMap, styles } from './SMap';
+export type { SMapHandle, SMapProps, StyleFlavor, TapHandler, LayerKind } from './SMap';
+export { Points, Lines, Polygons } from './layers';
+export type { LayerProps, PointsProps, LinesProps, PolygonsProps, PointOptions, LineOptions, PolygonOptions } from './layers';
+export type { LayerData, LngLatLike, GeoJSONFeature, GeoJSONFeatureCollection, PointInput } from './geojson';
+export { toFeatureCollection } from './geojson';

package/src/layers.tsx

@@ -0,0 +1,114 @@
+import { useEffect, useRef } from 'react';
+import type { LayerData } from './geojson';
+import { useSMap, type SMapHandle, type TapHandler } from './SMap';
+
+interface ZoomRange {
+  minZoom?: number;
+  maxZoom?: number;
+  /** Higher draws on top; equal values keep the order added. */
+  zIndex?: number;
+}
+
+export interface PointOptions extends ZoomRange {
+  /** Groups nearby points into circles sized by their count; a tap zooms in to split them. */
+  cluster?: boolean | { radius?: number; maxZoom?: number };
+  color?: string;
+  radius?: number;
+  strokeColor?: string;
+  /** The name of an image registered with the native map; drawn instead of a circle. */
+  icon?: string;
+  iconSize?: number;
+  /** The property written under each point. */
+  label?: string;
+}
+
+export interface LineOptions extends ZoomRange {
+  color?: string;
+  width?: number;
+  /** Dash and gap lengths in line widths. */
+  dash?: number[];
+  opacity?: number;
+}
+
+export interface PolygonOptions extends ZoomRange {
+  fill?: string;
+  opacity?: number;
+  outline?: string;
+  outlineWidth?: number;
+  /** Draws the areas in 3D: a height and a base in metres, each a number or the name of a property. */
+  extrude?: { height?: number | string; base?: number | string };
+}
+
+export interface LayerProps<O> {
+  /** The layer id, unique on the map. */
+  id: string;
+  /** GeoJSON, or an array of points `{lng, lat, …properties}`. A new value replaces the data and keeps the look. */
+  data: LayerData;
+  /** How the layer is drawn; a change draws the layer again. */
+  options?: O;
+  /** Called with the tapped feature's properties and position. */
+  onTap?: TapHandler;
+  /** Shows or hides the layer (default true). */
+  visible?: boolean;
+}
+
+export type PointsProps = LayerProps<PointOptions>;
+export type LinesProps = LayerProps<LineOptions>;
+export type PolygonsProps = LayerProps<PolygonOptions>;
+
+type Method = 'addPoints' | 'addLines' | 'addPolygons';
+
+function useLayer(method: Method, props: LayerProps<object>): null {
+  const map = useSMap();
+  const { id, data, options, onTap, visible = true } = props;
+  const latest = useRef(props);
+  latest.current = props;
+  const shown = useRef<{ map: SMapHandle; data: LayerData; visible: boolean } | null>(null);
+  const looks = JSON.stringify(options ?? {});
+  const hasTap = !!onTap;
+
+  useEffect(() => {
+    if (!map) { return undefined; }
+    const p = latest.current;
+    map[method](id, p.data, (p.options ?? {}) as Record<string, unknown>);
+    const v = p.visible !== false;
+    if (!v) { map.setVisible(id, false); }
+    if (hasTap) { map.onTap(id, (properties, position) => latest.current.onTap?.(properties, position)); }
+    shown.current = { map, data: p.data, visible: v };
+    return () => {
+      shown.current = null;
+      map.removeLayer(id);
+    };
+  }, [map, id, looks, hasTap, method]);
+
+  useEffect(() => {
+    const s = shown.current;
+    if (!map || !s || s.map !== map || s.data === data) { return; }
+    s.data = data;
+    map.setData(id, data);
+  }, [map, id, data]);
+
+  useEffect(() => {
+    const s = shown.current;
+    if (!map || !s || s.map !== map || s.visible === visible) { return; }
+    s.visible = visible;
+    map.setVisible(id, visible);
+  }, [map, id, visible]);
+
+  return null;
+}
+
+/** Points at any scale, clustered or not. Must be inside `<SMap>`. */
+export function Points(props: PointsProps): null {
+  return useLayer('addPoints', props);
+}
+
+/** Lines (routes, tracks). Must be inside `<SMap>`. */
+export function Lines(props: LinesProps): null {
+  return useLayer('addLines', props);
+}
+
+/** Areas, flat or in 3D (`options.extrude`). Must be inside `<SMap>`. */
+export function Polygons(props: PolygonsProps): null {
+  return useLayer('addPolygons', props);
+}