lecodes-sdk 1.2.0 → 2.0.1

package/src/plugins/{geolocation.ts → gen/geolocation/sdk/geolocation.ts}

@@ -1,39 +1,18 @@
-// Geolocation — the device position as a typed service plugin (docs/service-channel-plan.md).
-// A wrapper over the host-registered "geolocation" service, exactly like QRScanner wraps the
-// "qrScanner" NativeView — except services have no UI surface, so there is nothing to present:
-// just `getCurrent()` and `watch()`.
+// GENERATED by scripts/vendor-plugins.ts from lecodes-plugins/plugins/geolocation/sdk/geolocation.ts — do not edit here.
+// Change it in the plugin repo and run `bun run vendor:plugins`; `bun run check:plugins` fails when this copy is stale.
+// Geolocation — the device position: `getCurrent()` and `watch()`.
 //
-// Host-OPTIONAL, like every plugin: it exists where the host registered a "geolocation" service
-// (web hosts do out of the box; Android via MainActivity) — gate on `Geolocation.isSupported`.
-// The OS permission prompt happens on the first call that needs it (host-side); denial is a
-// rejection. Both methods reject immediately on unsupported hosts, BEFORE any permission path.
+// Hand-written over the generated wire because the public API is not the wire's: the wire has ONE
+// watch per session (startWatch / stopWatch + the `position` event), the app gets `watch(callback)`
+// — any number of subscribers on that one watch, each with its own `stop()`.
 //
-// Service contract ("geolocation"): calls `getCurrent(options) → GeoPosition`,
-// `startWatch(options)` (resolves once watching), `stopWatch()`; event `position` → GeoPosition.
+// The OS permission prompt happens on the first call that needs it (host-side); a denial is a
+// rejection. Both methods reject on a host without the service BEFORE any permission path.
 
-import { ServiceClient } from "../runtime/service"
+import { GeolocationBase, NAME } from "./geolocation.gen"
+import type { GeoOptions, GeoPosition } from "../contract"
 
-export interface GeoPosition {
-  latitude: number
-  longitude: number
-  /** Horizontal accuracy radius, meters. */
-  accuracy: number
-  /** Meters above sea level, or null when the provider doesn't know. */
-  altitude: number | null
-  /** Direction of travel in degrees clockwise from north, or null when stationary/unknown. */
-  heading: number | null
-  /** Ground speed in m/s, or null when unknown. */
-  speed: number | null
-  /** When this fix was taken, ms epoch. */
-  timestamp: number
-}
-
-export interface GeoOptions {
-  /** Prefer the precise (GPS) provider — slower first fix, more battery. Default false. */
-  highAccuracy?: boolean
-  /** getCurrent only: reject with "timeout" if no fix arrives in this many ms. */
-  timeout?: number
-}
+export type { GeoOptions, GeoPosition }
 
 /** A live `Geolocation.watch()` subscription — `stop()` it when the screen goes away. */
 export interface GeoWatch {
@@ -44,7 +23,7 @@ export interface GeoWatch {
  * The device position. `Geolocation.isSupported` reports whether this host registered the
  * service — check it before offering location features.
  */
-// PURE IIFE so an app that never uses location tree-shakes the whole plugin away (see NativeView).
+// PURE IIFE so an app that never uses location tree-shakes the whole plugin away.
 export const Geolocation: {
   /** Whether this host registered a "geolocation" service. */
   readonly isSupported: boolean
@@ -56,18 +35,18 @@ export const Geolocation: {
    *  subscriber; the options of the watch that starts it win. Always `stop()` when done. */
   watch(callback: (position: GeoPosition) => void, options?: GeoOptions): Promise<GeoWatch>
 } = /*#__PURE__*/ (() => {
-  let client: ServiceClient | null = null
-  const service = (): ServiceClient => client ??= new ServiceClient("geolocation")
+  let client: GeolocationBase | null = null
+  const service = (): GeolocationBase => client ??= new GeolocationBase()
 
-  // Watch state: one host watch fans out to N subscribers (SDK-side), the last stop() releases it.
+  // Watch state: one host watch fans out to N subscribers, the last stop() releases it.
   const watchers: ((position: GeoPosition) => void)[] = []
   let positionHooked = false
   let startPromise: Promise<void> | null = null
 
   const assertSupported = (): void => {
     // Fail before the host is touched — a permission dialog for a feature that can't exist
-    // would be worse than the error (same ordering rule as QRScanner.open).
-    if (!ServiceClient.isSupported("geolocation")) {
+    // would be worse than the error.
+    if (!GeolocationBase.supports(NAME)) {
       throw new Error('Geolocation isn\'t available on this host — it needs a registered "geolocation" service.')
     }
   }
@@ -77,26 +56,26 @@ export const Geolocation: {
     if (i >= 0) watchers.splice(i, 1)
     if (watchers.length === 0 && startPromise !== null) {
       startPromise = null
-      service().call("stopWatch").catch(() => {})
+      service().stopWatch().catch(() => {})
     }
   }
 
   const geolocation = {
     async getCurrent(options?: GeoOptions): Promise<GeoPosition> {
       assertSupported()
-      return await service().call("getCurrent", options ?? {})
+      return await service().getCurrent(options ?? {})
     },
 
     async watch(callback: (position: GeoPosition) => void, options?: GeoOptions): Promise<GeoWatch> {
       assertSupported()
       if (!positionHooked) {
         positionHooked = true
-        service().on("position", (position?: GeoPosition) => {
+        service().on("position", position => {
           if (position) for (const cb of [...watchers]) cb(position)
         })
       }
       watchers.push(callback)
-      startPromise ??= service().call("startWatch", options ?? {})
+      startPromise ??= service().startWatch(options ?? {})
       try {
         await startPromise
       } catch (e) {
@@ -117,7 +96,7 @@ export const Geolocation: {
     },
   }
   Object.defineProperty(geolocation, "isSupported", {
-    get: (): boolean => ServiceClient.isSupported("geolocation"),
+    get: (): boolean => GeolocationBase.supports(NAME),
   })
   return geolocation as any
 })()

package/src/plugins/gen/map/contract.d.ts

@@ -0,0 +1,144 @@
+// GENERATED by scripts/vendor-plugins.ts from lecodes-plugins/plugins/map/contract.d.ts — do not edit here.
+// Change it in the plugin repo and run `bun run vendor:plugins`; `bun run check:plugins` fails when this copy is stale.
+// map — a vector map (maplibre-native on iOS / Android, maplibre-gl in the browser).
+// The wire is lower than the app-facing `MapView`: the wrapper in sdk/ resolves a style to a url or
+// to text, turns marker items into GeoJSON, queues calls until `ready` and re-applies the
+// style-lifetime state (layers, data, padding, the user puck) after every style load.
+//
+// The plugin never touches the location hardware: the user puck is fed by the app.
+
+import type { Json, View, f64 } from "../../../plugin"
+
+/** `[longitude, latitude]` — GeoJSON order. */
+export type LngLat = [f64, f64]
+
+export interface MapParams {
+  /** A style URL the map fetches itself. */
+  style?: string
+  /** A style as JSON text; wins over `style`. It has no base url: every url INSIDE it (sources,
+   *  sprite, glyphs) must be absolute. */
+  styleJson?: string
+  center?: LngLat
+  /** Default 12 with a center. */
+  zoom?: f64
+  minZoom?: f64
+  maxZoom?: f64
+  /** Degrees clockwise from north. */
+  bearing?: f64
+  /** Degrees from the vertical. */
+  pitch?: f64
+  /** The two-finger rotate gesture. Default true. */
+  rotate?: boolean
+  /** The two-finger tilt gesture. Default false. */
+  tilt?: boolean
+}
+
+export interface MapCamera {
+  center: LngLat
+  zoom: f64
+  bearing: f64
+  pitch: f64
+}
+
+/** A feature of a managed source under a tap. */
+export interface MapFeature {
+  /** The source's name — the layer's name in the app. */
+  source: string
+  id: string | f64 | null
+  properties: { [key: string]: Json }
+}
+
+export interface MapTap {
+  lngLat: LngLat
+  /** View-space point, logical px. */
+  point: [f64, f64]
+  /** Absent for a tap that hit no feature of a managed source. A tap on a CLUSTER zooms in and
+   *  sends no event. */
+  feature?: MapFeature
+}
+
+export interface MapEvents {
+  /** The style loaded and the map takes calls. Fires again after every style reload. */
+  ready: void
+  tap: MapTap
+  /** The camera settled after a gesture or an animation. */
+  moveEnd: MapCamera
+  /** A problem that is never fatal: a style that would not load, a source out of reach. */
+  error: { message: string }
+}
+
+export type MapLayerKind = "markers" | "line"
+
+/** The keys of both kinds; a half reads the ones of the kind it is asked for. */
+export interface MapLayerOptions {
+  /** markers: group nearby markers (a cluster tap zooms in). Default false. */
+  cluster?: boolean
+  /** markers: px. Default 50. */
+  clusterRadius?: f64
+  /** markers: the zoom at which clusters stop forming. */
+  clusterMaxZoom?: f64
+  /** line. */
+  color?: string
+  /** line: px. Default 4. */
+  width?: f64
+  /** line: 0–1. Default 1. */
+  opacity?: f64
+}
+
+export interface MapCameraMove {
+  zoom?: f64
+  bearing?: f64
+  pitch?: f64
+  /** flyTo only: ms. Default 600. */
+  duration?: f64
+}
+
+/** Px, or a share of the view's size as "NN%". */
+export type MapInset = f64 | string
+
+export interface MapPadding {
+  top?: MapInset
+  left?: MapInset
+  bottom?: MapInset
+  right?: MapInset
+}
+
+export interface MapFitOptions {
+  /** Around the points: px on every edge, or per edge. Added to the view padding. */
+  padding?: f64 | MapPadding
+  /** Default: 16 for one point, none otherwise. */
+  maxZoom?: f64
+  /** Default true. */
+  animate?: boolean
+}
+
+export interface MapUserLocationOptions {
+  /** Meters — the halo around the dot. */
+  accuracy?: f64 | null
+  /** Degrees clockwise from north — the direction wedge; null hides it. */
+  heading?: f64 | null
+}
+
+export interface MapView extends View<"map", MapParams, MapEvents> {
+  /** Make sure the GeoJSON source `source` exists. A source the style declares is used as is (its
+   *  layers draw, only data flows); otherwise the half creates it with the default layers of `kind`.
+   *  @rejects notReady */
+  ensureLayer(source: string, kind: MapLayerKind, options?: MapLayerOptions): Promise<void>
+  removeLayer(source: string): Promise<void>
+  /** Replace the data of a GeoJSON source: a Feature or a FeatureCollection.
+   *  @rejects notReady */
+  setData(source: string, geojson: Json): Promise<void>
+
+  flyTo(center: LngLat, options?: MapCameraMove): Promise<void>
+  jumpTo(center: LngLat, options?: MapCameraMove): Promise<void>
+  /** Fit the camera to the points.
+   *  @rejects noPoints */
+  fitPoints(points: LngLat[], options?: MapFitOptions): Promise<void>
+  /** The part of the view covered by the app's UI; camera moves center inside the rest. */
+  setPadding(padding: MapPadding): Promise<void>
+  /** @rejects notReady */
+  getCamera(): Promise<MapCamera>
+
+  /** Move the user puck; null hides it. */
+  setUserLocation(lngLat: LngLat | null, options?: MapUserLocationOptions): Promise<void>
+}

package/src/plugins/gen/map/sdk/map.gen.ts

@@ -0,0 +1,88 @@
+// GENERATED by scripts/vendor-plugins.ts from lecodes-plugins/plugins/map/sdk/map.gen.ts — do not edit here.
+// Change it in the plugin repo and run `bun run vendor:plugins`; `bun run check:plugins` fails when this copy is stale.
+// GENERATED by `lecodes plugin gen` from contract.d.ts — do not edit.
+// map: the view "map", contract version 1.
+
+import { ViewChannel, type Json } from "../../../../plugin"
+import type { LngLat, MapCamera, MapCameraMove, MapEvents, MapFitOptions, MapLayerKind, MapLayerOptions, MapPadding, MapParams, MapUserLocationOptions } from "../contract"
+
+/** What the halves register under. */
+export const NAME = "map"
+/** The contract's version: the highest `@since` of its members. */
+export const VERSION = 1
+
+// ---- the wire, call by call ----------------------------------------------------------------------
+
+/** Make sure the GeoJSON source `source` exists. A source the style declares is used as is (its
+ *  layers draw, only data flows); otherwise the half creates it with the default layers of `kind`.
+ *  Rejects with "notReady". */
+export const ensureLayer = (view: ViewChannel<MapEvents>, source: string, kind: MapLayerKind, options?: MapLayerOptions): Promise<void> =>
+  view._call("ensureLayer", [source, kind, options])
+
+export const removeLayer = (view: ViewChannel<MapEvents>, source: string): Promise<void> =>
+  view._call("removeLayer", [source])
+
+/** Replace the data of a GeoJSON source: a Feature or a FeatureCollection.
+ *  Rejects with "notReady". */
+export const setData = (view: ViewChannel<MapEvents>, source: string, geojson: Json): Promise<void> =>
+  view._call("setData", [source, geojson])
+
+export const flyTo = (view: ViewChannel<MapEvents>, center: LngLat, options?: MapCameraMove): Promise<void> =>
+  view._call("flyTo", [center, options])
+
+export const jumpTo = (view: ViewChannel<MapEvents>, center: LngLat, options?: MapCameraMove): Promise<void> =>
+  view._call("jumpTo", [center, options])
+
+/** Fit the camera to the points.
+ *  Rejects with "noPoints". */
+export const fitPoints = (view: ViewChannel<MapEvents>, points: LngLat[], options?: MapFitOptions): Promise<void> =>
+  view._call("fitPoints", [points, options])
+
+/** The part of the view covered by the app's UI; camera moves center inside the rest. */
+export const setPadding = (view: ViewChannel<MapEvents>, padding: MapPadding): Promise<void> =>
+  view._call("setPadding", [padding])
+
+/** Rejects with "notReady". */
+export const getCamera = (view: ViewChannel<MapEvents>): Promise<MapCamera> =>
+  view._call("getCamera", [])
+
+/** Move the user puck; null hides it. */
+export const setUserLocation = (view: ViewChannel<MapEvents>, lngLat: LngLat | null, options?: MapUserLocationOptions): Promise<void> =>
+  view._call("setUserLocation", [lngLat, options])
+
+// ---- what the host's half has --------------------------------------------------------------------
+
+/** A method of the contract. */
+export type Method = "ensureLayer" | "removeLayer" | "setData" | "flyTo" | "jumpTo" | "fitPoints" | "setPadding" | "getCamera" | "setUserLocation"
+
+/** Whether this host has the view "map" — and, given a method, a half new enough for it
+ *  (a method added after the first version of the contract is tagged `@since`). */
+export const supports = (method?: Method): boolean =>
+  ViewChannel.supports(NAME)   // every method is of version 1
+
+// ---- the element ----------------------------------------------------------------------------------
+
+/** The view "map" with the wire's methods as its own. */
+export class MapViewBase extends ViewChannel<MapEvents> {
+  constructor(params: MapParams = {}) { super("MapView", NAME, params) }
+
+  /** Make sure the GeoJSON source `source` exists. A source the style declares is used as is (its
+   *  layers draw, only data flows); otherwise the half creates it with the default layers of `kind`.
+   *  Rejects with "notReady". */
+  ensureLayer(source: string, kind: MapLayerKind, options?: MapLayerOptions): Promise<void> { return ensureLayer(this, source, kind, options) }
+  removeLayer(source: string): Promise<void> { return removeLayer(this, source) }
+  /** Replace the data of a GeoJSON source: a Feature or a FeatureCollection.
+   *  Rejects with "notReady". */
+  setData(source: string, geojson: Json): Promise<void> { return setData(this, source, geojson) }
+  flyTo(center: LngLat, options?: MapCameraMove): Promise<void> { return flyTo(this, center, options) }
+  jumpTo(center: LngLat, options?: MapCameraMove): Promise<void> { return jumpTo(this, center, options) }
+  /** Fit the camera to the points.
+   *  Rejects with "noPoints". */
+  fitPoints(points: LngLat[], options?: MapFitOptions): Promise<void> { return fitPoints(this, points, options) }
+  /** The part of the view covered by the app's UI; camera moves center inside the rest. */
+  setPadding(padding: MapPadding): Promise<void> { return setPadding(this, padding) }
+  /** Rejects with "notReady". */
+  getCamera(): Promise<MapCamera> { return getCamera(this) }
+  /** Move the user puck; null hides it. */
+  setUserLocation(lngLat: LngLat | null, options?: MapUserLocationOptions): Promise<void> { return setUserLocation(this, lngLat, options) }
+}