@tileflow/react-native 0.1.0-alpha.5 → 0.1.0-alpha.7

package/README.md

@@ -93,19 +93,48 @@ Maps without this capability ignore the option; omitting it keeps the selected t
 Changing it uses the existing theme transition. `themeBlend` takes precedence. See the
 [authoring contract](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/README.md#style-with-themes-and-semantic-modules).
 
-`themeTransition={{duration: 450}}` cross-fades theme changes: a snapshot of the drawn map covers it, follows the camera and fades out once the new theme is drawn. `themeBlend={{themes: ['night', 'dusk', 'day'], position}}` shows a continuous blend of the map's themes instead of `theme`; position 0 is the first theme and 1.5 is halfway from the second to the third:
+Theme and `timeOfDay` changes cross-fade over 450 ms by default: a snapshot of the drawn map covers it, follows the camera and fades out once the new theme is drawn. Use `themeTransition={{duration: 700}}` to customize the duration, or `duration: 0` for an immediate change. `themeBlend={{themes: ['night', 'dusk', 'day'], position}}` shows a continuous blend of the map's themes instead of `theme`; position 0 is the first theme and 1.5 is halfway from the second to the third:
 
 ```tsx
-<Map
-  source={source}
-  themeTransition={{duration: 450}}
-  themeBlend={{themes: ['night', 'dusk', 'day'], position}}
-  style={{flex: 1}}
-/>
+<Map source={source} themeBlend={{themes: ['night', 'dusk', 'day'], position}} style={{flex: 1}} />
 ```
 
 The first blend of a set of themes prepares every theme's style and replaces the native style once; moving `position` later changes the map without loading. Removing `themeBlend` returns to `theme`. Both keep the same native Map, context and session, and `ready` events wait for the fade. The device's reduce-motion setting changes at once. See [theme transitions and blends](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/theme-transitions-and-blends.md#react-native) for what follows the position on native maps.
 
+## Boundary choropleths
+
+A map that declares `boundaryAreas` and a `boundaryChoropleth()` without compiled `values` reads
+its colors from feature-state. `boundaryFeatureState` sets that state from the application, with
+the same rows and options as `useBoundaryFeatureState` on the web: rows keyed by the source's
+feature ID (`id`, or `ref` when the map promotes it), `labels` and `state`:
+
+<!-- docs:check -->
+
+```tsx
+import {Map, type MapSource} from '@tileflow/react-native';
+import {useMemo} from 'react';
+
+export function UnemploymentMap({
+  source,
+  rates,
+}: {
+  source: MapSource;
+  rates: ReadonlyMap<number, number>;
+}) {
+  // Memoize the values: each new object replaces the previous ones.
+  const values = useMemo(
+    () => ({joinBy: 'id' as const, rows: [...rates].map(([key, value]) => ({key, value}))}),
+    [rates],
+  );
+  return <Map source={source} boundaryFeatureState={{values}} style={{flex: 1}} />;
+}
+```
+
+Values survive theme changes: they are set again once the new style has loaded. `values: null`
+removes them. Rows keyed by codes the polygons do not carry are joined before they reach the app,
+on a server or at build time; see
+[boundary areas and choropleths](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/boundary-areas-and-choropleths.md#join-by-codes-the-polygons-do-not-carry).
+
 ## Camera
 
 The existing mount-stable camera contract is preserved. Use either an initial camera seed or complete controlled camera ownership for the lifetime of one mounted Map:
@@ -174,10 +203,39 @@ The public lifecycle surface remains:
 - `onReadinessChange`;
 - `onThemeChange`;
 - controlled `onViewChange`;
-- `ref.getSourceState()`.
+- `ref.getSourceState()`;
+- `ref.retry()`.
 
 `getSourceState()` returns only the last safe projected source snapshot. Errors use existing bounded codes/fields/kinds. No URL, response body, native event, credential, grant, session object, native handle or raw cause enters public callbacks, refs or serializable state.
 
+`onError` reports `source-error`, `renderer-error` and, for Hosted session delivery, `session-error`. A `session-error` means Tileflow refused the session: the mobile credential was rejected (`NATIVE_SESSION_CREDENTIAL_REJECTED`), it does not authorize the Map (`NATIVE_SESSION_MAP_MISMATCH`), the Map was not found (`NATIVE_SESSION_MAP_NOT_FOUND`) or its view or spending limit was reached (`NATIVE_SESSION_QUOTA_EXCEEDED`). It can arrive after the first load, when a renewal is refused. The map keeps what it has drawn but loads nothing new until you call `ref.retry()` or change the source:
+
+```tsx
+import {Map, type MapRef} from '@tileflow/react-native';
+import {useRef} from 'react';
+
+export function StoreMap() {
+  const map = useRef<MapRef>(null);
+  return (
+    <Map
+      ref={map}
+      source={{map: 'stores', manifestUrl: 'https://maps.example.com/tileflow/manifest.json'}}
+      onError={(event) => {
+        if (
+          event.type === 'session-error' &&
+          event.error.code === 'NATIVE_SESSION_QUOTA_EXCEEDED'
+        ) {
+          // Show your own notice; call map.current?.retry() once the limit is raised.
+        }
+      }}
+      style={{flex: 1}}
+    />
+  );
+}
+```
+
+Service outages, timeouts and rate limiting are not session errors. The map keeps using its current grant while it is valid and requests another after an increasing delay, from one second up to one minute, or after the `Retry-After` the service sends. A first load that failed this way prepares again on its own. `ref.retry()` also loads again after a source or renderer error, and changes nothing while the map is shown.
+
 ## Native integration
 
 Autolinking registers the private Android/iOS modules used by the mounted lifecycle. Android depends on the exact MapLibre React Native project and MapLibre Native 13.6.1. iOS uses the existing MapLibre React Native CocoaPod plus the exact MapLibre Native 6.31.0 Swift Package Manager product.

package/android/src/main/java/dev/tileflow/reactnative/AdmissionBootstrap.kt

@@ -6,7 +6,10 @@ internal object AdmissionBootstrapLimits {
 	const val QUEUE = 32
 	const val REQUEST_BYTES = 2048
 	const val RESPONSE_BYTES = 65536
-	const val TIMEOUT_MS = 30000L
+	const val RETRY_AFTER_CHARACTERS = 64
+	// Well inside the 30 s ticket and batch deadlines, so a stalled renewal fails its batch
+	// instead of letting the context retire under it.
+	const val TIMEOUT_MS = 10000L
 }
 
 internal class AdmissionBootstrapRequest(
@@ -18,7 +21,7 @@ internal class AdmissionBootstrapRequest(
 	override fun toString() = "AdmissionBootstrapRequest(redacted)"
 }
 
-internal class AdmissionBootstrapReply(val status: Int, val cacheControl: String, val body: ByteArray) {
+internal class AdmissionBootstrapReply(val status: Int, val cacheControl: String, val body: ByteArray, val retryAfter: String = "") {
 	override fun toString() = "AdmissionBootstrapReply(redacted)"
 }
 
@@ -86,7 +89,8 @@ internal class AdmissionBootstrap(
 			work.network = network.start(AdmissionBootstrapRequest(url, credential, body) { mayStart(work) }) { reply ->
 				scheduler.dispatch {
 					val valid = mayStart(work) && reply != null && reply.status in 100..599 &&
-						reply.cacheControl.length <= 1024 && reply.body.size <= AdmissionBootstrapLimits.RESPONSE_BYTES
+						reply.cacheControl.length <= 1024 && reply.retryAfter.length <= AdmissionBootstrapLimits.RETRY_AFTER_CHARACTERS &&
+						reply.body.size <= AdmissionBootstrapLimits.RESPONSE_BYTES
 					finish(work, if (valid) reply else null)
 				}
 			}

package/android/src/main/java/dev/tileflow/reactnative/AdmissionBootstrapOkHttpNetwork.kt

@@ -55,6 +55,8 @@ internal class AdmissionBootstrapOkHttpNetwork : AdmissionBootstrapNetwork {
 					val reply = try {
 						response.use {
 							val cacheControl = it.header("cache-control") ?: ""
+							// An oversized Retry-After is ignored rather than failing the reply.
+							val retryAfter = (it.header("retry-after") ?: "").takeIf { value -> value.length <= AdmissionBootstrapLimits.RETRY_AFTER_CHARACTERS } ?: ""
 							val body = it.body
 							if (cacheControl.length > 1024 || body == null || body.contentLength() > AdmissionBootstrapLimits.RESPONSE_BYTES) throw IOException("Invalid bootstrap response")
 							val bytes = ByteArrayOutputStream()
@@ -67,7 +69,7 @@ internal class AdmissionBootstrapOkHttpNetwork : AdmissionBootstrapNetwork {
 									bytes.write(buffer, 0, count)
 								}
 							}
-							AdmissionBootstrapReply(it.code, cacheControl, bytes.toByteArray())
+							AdmissionBootstrapReply(it.code, cacheControl, bytes.toByteArray(), retryAfter)
 						}
 					} catch (_: Exception) { null }
 					complete(reply)

package/android/src/main/java/dev/tileflow/reactnative/AdmissionEngine.kt

@@ -155,8 +155,10 @@ internal class AdmissionEngine(
 			work = item
 			context.work[item.id] = item
 			item.timer = scheduler.after(AdmissionLimits.WAIT_MS) {
-				if (context.batch?.tickets?.contains(item.id) == true) retire(context.id)
-				else fail(item)
+				// A slow renewal fails only this request. JavaScript still answers its batch, and the
+				// batch deadline alone retires a context whose JavaScript stopped answering.
+				if (context.batch?.tickets?.contains(item.id) == true) event(context, "cancel", mapOf("tickets" to listOf(item.id)))
+				fail(item)
 			}
 			scheduler.dispatch { drain(context) }
 		}

package/android/src/main/java/dev/tileflow/reactnative/TileflowNativeAdmissionModule.kt

@@ -125,7 +125,7 @@ class TileflowNativeAdmissionModule(context: ReactApplicationContext) : ReactCon
 				(bootstrapRequests ?: invalid()).start(context, request, url, credential, body) { reply ->
 					if (reply == null) reject(promise)
 					else promise.resolve(Arguments.makeNativeMap(mapOf(
-						"status" to reply.status, "cacheControl" to reply.cacheControl,
+						"status" to reply.status, "cacheControl" to reply.cacheControl, "retryAfter" to reply.retryAfter,
 						"bodyBase64" to Base64.encodeToString(reply.body, Base64.NO_WRAP))))
 				}
 			} catch (_: Exception) { reject(promise) }

package/dist/{contract-Bp-Im7tj.d.ts → contract-BaK24QZD.d.ts}

@@ -1,7 +1,7 @@
 import { MapProps as MapProps$1 } from '@maplibre/maplibre-react-native';
 import { ReactElement, ReactNode, Ref } from 'react';
 import { ViewProps } from 'react-native';
-import { TileflowNativeInitialView, TileflowNativeInitialViewOptions, TileflowNativeSource, TileflowNativeSourceOptions, TileflowNativeSourceState, TileflowNativeSourceError } from '@tileflow/core/native';
+import { TileflowNativeInitialView, TileflowNativeInitialViewOptions, TileflowNativeSource, TileflowNativeSourceOptions, TileflowBoundaryValues, TileflowBoundaryFamily, TileflowNativeSourceState, TileflowNativeSourceError } from '@tileflow/core/native';
 import { TileflowAnnotation, TileflowInteractionBinding, TileflowInteractionEvent, TileflowResolvedAnnotationTarget, TileflowResolvedPoiFeatureTarget, TileflowInteractionDiagnostic, TileflowAnnotationViewContext } from '@tileflow/interactions';
 
 /** Marker composition only. Selection presentation and native handles are not part of this context. */
@@ -28,12 +28,12 @@ type MapView = TileflowNativeInitialView;
 /** Portable composition inputs, independent from source acquisition. */
 type MapInitialViewInputs = TileflowNativeInitialViewOptions;
 /**
- * How a theme change appears. With a `duration`, a snapshot of the current frame covers the map,
+ * How a theme change appears. By default, a snapshot of the current frame covers the map,
  * follows the camera, and fades out once the new theme is drawn. The device's reduce-motion
  * setting changes at once.
  */
 type MapThemeTransition = Readonly<{
-    /** Cross-fade length in milliseconds, from 0 (the default, an immediate change) to 5000. */
+    /** Cross-fade length in milliseconds, from 0 (immediate) to 5000. Defaults to 450. */
     duration?: number;
 }>;
 /**
@@ -58,6 +58,22 @@ type MapSourceProps = Readonly<{
      */
     themeBlend?: MapThemeBlend;
 }>;
+/**
+ * Application values on the map's Boundaries areas, for a choropleth that reads them with
+ * `feature-state`. The same rows and options as `useBoundaryFeatureState` on the web: rows keyed by
+ * the source's feature ID (`id`, or `ref` when the map promotes it), joined with
+ * `joinBoundaryRows` when the data carries other codes. Values survive theme changes; `null`
+ * removes them.
+ */
+type MapBoundaryFeatureState = Readonly<{
+    values: TileflowBoundaryValues | null;
+    /** Defaults to `boundaries`. */
+    family?: TileflowBoundaryFamily;
+    /** Also set the values on `boundary_label` points, for labels styled by value. */
+    labels?: boolean;
+    /** Feature-state key; it must match the choropleth's `state`. Defaults to `value`. */
+    state?: string;
+}>;
 type AllowedMapOptions = 'dragPan' | 'touchZoom' | 'doubleTapZoom' | 'doubleTapHoldZoom' | 'touchRotate' | 'touchPitch' | 'compass' | 'compassHiddenFacingNorth' | 'scaleBar';
 type OwnedMapOptions = Exclude<keyof MapProps$1, AllowedMapOptions> | 'container' | 'styleURL' | 'styleUrl' | 'transformRequest' | 'requestTransform' | 'requestHeaders';
 /** A positive allowlist. Style, interception, view and lifecycle remain adapter-owned. */
@@ -69,6 +85,7 @@ type MapPresentationProps = Readonly<{
     style?: ViewProps['style'];
     testID?: ViewProps['testID'];
     mapOptions?: MapOptions;
+    boundaryFeatureState?: MapBoundaryFeatureState;
 }>;
 type TileflowReady = Extract<TileflowNativeSourceState, {
     status: 'ready';
@@ -92,9 +109,23 @@ type MapSourceState = Readonly<{
     generation: number;
     error: MapSourceError;
 }>;
-/** A synchronous read of the last source snapshot. Does not trigger loading or native commands. */
+/**
+ * The Hosted session stopped: its credential, Map or quota was rejected. The map keeps what it has
+ * drawn and loads nothing new until `ref.retry()` or another source. Service outages and rate
+ * limits retry on their own and are not reported.
+ */
+type MapSessionError = Readonly<{
+    code: 'NATIVE_SESSION_CREDENTIAL_REJECTED' | 'NATIVE_SESSION_MAP_MISMATCH' | 'NATIVE_SESSION_MAP_NOT_FOUND' | 'NATIVE_SESSION_QUOTA_EXCEEDED' | 'NATIVE_SESSION_INPUT_INVALID';
+    kind: 'terminal';
+}>;
 type MapRef = Readonly<{
+    /** A synchronous read of the last source snapshot. Does not trigger loading or native commands. */
     getSourceState(): MapSourceState | undefined;
+    /**
+     * Loads again a map that stopped: after a `session-error` once its cause is resolved, for
+     * example a raised quota, or after a source or renderer error. A shown map is unaffected.
+     */
+    retry(): void;
 }>;
 /** The current style was accepted by the renderer; this alone does not establish a rendered frame. */
 type MapLoadEvent = Readonly<{
@@ -110,6 +141,10 @@ type MapErrorEvent = Readonly<{
 }> | Readonly<{
     type: 'renderer-error';
     generation: number;
+}> | Readonly<{
+    type: 'session-error';
+    generation: number;
+    error: MapSessionError;
 }>;
 /** The renderer owner must confirm readiness; a ready manifest alone is insufficient. */
 type MapReadinessChangeEvent = Readonly<{
@@ -168,4 +203,4 @@ type MapCameraProps = Readonly<{
 /** Complete Tileflow source, presentation, mount-stable camera and portable interaction inputs. */
 type MapProps<TAnnotation extends TileflowAnnotation = TileflowAnnotation> = MapBaseProps & MapCameraProps & MapInteractionProps<TAnnotation>;
 
-export type { MapThemeTransition as A, MapView as M, MapViewChangeEvent as a, MapInitialViewInputs as b, MapCameraProps as c, MapProps as d, MapBaseProps as e, MapColorScheme as f, MapErrorEvent as g, MapEventHandlers as h, MapInteractionEvent as i, MapInteractionProps as j, MapLoadEvent as k, MapMarkerRenderContext as l, MapMarkerRenderer as m, MapOptions as n, MapPresentationProps as o, MapReadinessChangeEvent as p, MapRef as q, MapSelection as r, MapSource as s, MapSourceError as t, MapSourceProps as u, MapSourceState as v, MapTheme as w, MapThemeBlend as x, MapThemeChangeEvent as y, MapThemeSelection as z };
+export type { MapThemeChangeEvent as A, MapThemeSelection as B, MapThemeTransition as C, MapView as M, MapViewChangeEvent as a, MapInitialViewInputs as b, MapCameraProps as c, MapProps as d, MapBaseProps as e, MapBoundaryFeatureState as f, MapColorScheme as g, MapErrorEvent as h, MapEventHandlers as i, MapInteractionEvent as j, MapInteractionProps as k, MapLoadEvent as l, MapMarkerRenderContext as m, MapMarkerRenderer as n, MapOptions as o, MapPresentationProps as p, MapReadinessChangeEvent as q, MapRef as r, MapSelection as s, MapSessionError as t, MapSource as u, MapSourceError as v, MapSourceProps as w, MapSourceState as x, MapTheme as y, MapThemeBlend as z };

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import { ReactElement } from 'react';
 import { TileflowAnnotation } from '@tileflow/interactions';
 export { TileflowAnnotation, TileflowInteractionBinding, TileflowInteractionCoordinate, TileflowInteractionDiagnostic, TileflowPoiCategory, TileflowResolvedAnnotationTarget, TileflowResolvedPoiFeatureTarget } from '@tileflow/interactions';
-import { d as MapProps } from './contract-Bp-Im7tj.js';
-export { e as MapBaseProps, c as MapCameraProps, f as MapColorScheme, g as MapErrorEvent, h as MapEventHandlers, b as MapInitialViewInputs, i as MapInteractionEvent, j as MapInteractionProps, k as MapLoadEvent, l as MapMarkerRenderContext, m as MapMarkerRenderer, n as MapOptions, o as MapPresentationProps, p as MapReadinessChangeEvent, q as MapRef, r as MapSelection, s as MapSource, t as MapSourceError, u as MapSourceProps, v as MapSourceState, w as MapTheme, x as MapThemeBlend, y as MapThemeChangeEvent, z as MapThemeSelection, A as MapThemeTransition, M as MapView, a as MapViewChangeEvent } from './contract-Bp-Im7tj.js';
+import { d as MapProps } from './contract-BaK24QZD.js';
+export { e as MapBaseProps, f as MapBoundaryFeatureState, c as MapCameraProps, g as MapColorScheme, h as MapErrorEvent, i as MapEventHandlers, b as MapInitialViewInputs, j as MapInteractionEvent, k as MapInteractionProps, l as MapLoadEvent, m as MapMarkerRenderContext, n as MapMarkerRenderer, o as MapOptions, p as MapPresentationProps, q as MapReadinessChangeEvent, r as MapRef, s as MapSelection, t as MapSessionError, u as MapSource, v as MapSourceError, w as MapSourceProps, x as MapSourceState, y as MapTheme, z as MapThemeBlend, A as MapThemeChangeEvent, B as MapThemeSelection, C as MapThemeTransition, M as MapView, a as MapViewChangeEvent } from './contract-BaK24QZD.js';
 import '@maplibre/maplibre-react-native';
 import 'react-native';
 import '@tileflow/core/native';