@craft-native/ts-maps

Craft SDK bindings for the ts-maps interactive map runtime.

This package is the TypeScript side of MapProvider.ts_maps in Craft's Zig core. Its MapView owns a DOM container and renders ts-maps inside a browser or WebView, with zero API keys. It is not the STX native Map component.

For a fully native STX screen, use Map, MapMarker, and MapPolyline. Craft renders them with MapKit on iOS and the configured native Android map provider. Android's mapProvider: 'maplibre' selects a key-free native GL view; it does not mount this package's DOM adapter.

Install

bun add @craft-native/ts-maps

Quick start

import { createMapView, defaultMapConfiguration, tsMapsProvider } from '@craft-native/ts-maps'

const view = createMapView({
  configuration: { ...defaultMapConfiguration, provider: tsMapsProvider },
  initialCamera: {
    center: { latitude: 37.7749, longitude: -122.4194 },
    zoom: 12,
    pitch: 0,
    heading: 0,
  },
  markers: [
    {
      id: 1,
      coordinate: { latitude: 37.7749, longitude: -122.4194 },
      title: 'San Francisco',
      subtitle: null,
      color: 'red',
      is_draggable: false,
      is_selected: false,
      custom_icon: null,
      anchor_x: 0.5,
      anchor_y: 1,
    },
  ],
  onTap: (coord) => console.log('tapped', coord),
  onMarkerTap: (id, coord) => console.log('marker', id, coord),
})

document.body.appendChild(view.container)

API overview

| Export | What it is | | --- | --- | | createMapView(props) | Factory returning a MapViewInstance with id, container, map, and imperative methods (setCamera, addMarker, fitToMarkers, …). | | MapViewProps / MapViewInstance | Types for the component. | | Coordinate, MapRegion, MapCamera, MapMarker, … | TypeScript mirrors of the structs in packages/zig/src/maps.zig. Field names match exactly so JSON round-trips are free. | | craftCoordToLatLng, latLngToCraftCoord, craftRegionToBounds, craftCameraToOptions, craftMarkerToMarker, … | Pure adapter functions between Craft and ts-maps types. | | tsMapsProvider | Constant 'ts_maps' that matches the Zig enum tag. | | Everything from ts-maps | TsMap, LatLng, Marker, Polyline, marker(), tileLayer(), etc. are re-exported so you only need one import. |

Bridge protocol

When running inside a Craft WebView, createMapView registers itself with getBridge() and listens for the methods declared in ./bridge-protocol:

• setCamera, setRegion, addMarker, removeMarker, addPolyline, addPolygon, addCircle, fitToMarkers, selectMarker, deselectAll, setConfiguration.

It emits these events back:

• map:tap, map:markerTap, map:regionChanged, map:cameraChanged.

If no bridge is available (browser-only, tests, etc.) the component silently falls back to local-only behavior — event callbacks passed via props still fire.

Development

bun run typecheck
bun test
bunx --bun pickier .