@tileflow/react 0.1.0-alpha.30 → 0.1.0-alpha.31

package/README.md

@@ -124,6 +124,38 @@ a Tileflow map through its manifest; it has no renderer discriminator or direct-
 The obsolete source fields `kind` and `style` are rejected. For a completely unmanaged map, use
 `maplibre-gl` directly rather than a Tileflow component.
 
+## Color boundary areas from application data
+
+For a map that declares `boundaryAreas` and a `boundaryChoropleth()` overlay without `values`,
+`useBoundaryFeatureState` keeps its feature-state equal to your rows. Take the map from `onLoad`
+and memoize the values; each new object replaces the previous ones, and `null` clears them:
+
+<!-- docs:check -->
+
+```tsx
+import {useMemo, useState} from 'react';
+import type {Map as MapLibreMap} from 'maplibre-gl';
+import {Map, useBoundaryFeatureState} from '@tileflow/react';
+
+export function Unemployment({rates}: {rates: {ine: string; rate: number}[]}) {
+  const [map, setMap] = useState<MapLibreMap | null>(null);
+  const values = useMemo(
+    () => ({
+      joinBy: 'ref' as const,
+      rows: rates.map(({ine, rate}) => ({key: `ES:INE:${ine}`, value: rate})),
+    }),
+    [rates],
+  );
+  useBoundaryFeatureState(map, values);
+  return <Map source={{map: 'madrid-unemployment'}} onLoad={setMap} />;
+}
+```
+
+Rows join by `ref` here, so this map declares `boundaryAreas: {family: 'boundaries', promoteId:
+'ref'}`. Without `promoteId`, rows join by registry `id`. See
+[boundary areas and choropleths](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/boundary-areas-and-choropleths.md)
+for scales, joins and the lookup table.
+
 ## Add annotations and popups
 
 Install the contract package when importing its types directly:

package/dist/index.d.ts

@@ -1,10 +1,17 @@
+import { Map as Map$1, MapOptions } from 'maplibre-gl';
+import { TileflowBoundaryValues } from '@tileflow/core';
+import { CreateBoundaryFeatureStateOptions, TileflowBrowserThemeBlendSelection, TileflowThemeTransitionOptions, TileflowViewMode, TileflowThemeTransition } from '@tileflow/core/browser';
 import * as react from 'react';
 import { CSSProperties, ImgHTMLAttributes, ReactNode } from 'react';
-import { MapOptions, Map as Map$1 } from 'maplibre-gl';
-import { TileflowBrowserThemeBlendSelection, TileflowThemeTransitionOptions, TileflowViewMode, TileflowThemeTransition } from '@tileflow/core/browser';
 import { TileflowRuntimeSource, TileflowThemeSelection, TileflowTimeOfDay, TileflowAnalytics } from '@tileflow/core/runtime';
 import { TileflowAnnotation, TileflowInteractionState, TileflowAnnotationViewContext, TileflowInteractionBinding, TileflowInteractionViewContext, TileflowInteractionDiagnostic, TileflowInteractionEvent } from '@tileflow/interactions';
 
+/**
+ * Keep a map's Boundaries feature-state equal to `values`. Pass the map from `<Map onLoad>` and
+ * memoize `values`; each new object replaces the previous values. `null` clears them.
+ */
+declare function useBoundaryFeatureState(map: Map$1 | null | undefined, values: TileflowBoundaryValues | null | undefined, options?: CreateBoundaryFeatureStateOptions): void;
+
 type TileflowMapStyleSourceProps = {
     source: TileflowRuntimeSource;
     theme?: TileflowThemeSelection;
@@ -87,4 +94,4 @@ type TileflowMapLibreConfiguration = Readonly<{
 /** Configure the application-owned worker before mounting an interactive Tileflow map. */
 declare function configureTileflowMapLibre(configuration: TileflowMapLibreConfiguration): void;
 
-export { Map, type MapProps, type TileflowAnnotationRenderer, type TileflowInteractionRenderer, type TileflowMapLibreConfiguration, type TileflowMapOptions, type TileflowMapSource, configureTileflowMapLibre };
+export { Map, type MapProps, type TileflowAnnotationRenderer, type TileflowInteractionRenderer, type TileflowMapLibreConfiguration, type TileflowMapOptions, type TileflowMapSource, configureTileflowMapLibre, useBoundaryFeatureState };

package/dist/index.js

@@ -1,13 +1,41 @@
 'use client';
 
+// src/boundary-feature-state.ts
+import { useEffect, useState } from "react";
+import {
+  createBoundaryFeatureState
+} from "@tileflow/core/browser";
+function useBoundaryFeatureState(map, values, options = {}) {
+  const { family, labels, state } = options;
+  const [controller, setController] = useState(null);
+  useEffect(() => {
+    if (!map) return void 0;
+    const created = createBoundaryFeatureState(map, {
+      ...family === void 0 ? {} : { family },
+      ...labels === void 0 ? {} : { labels },
+      ...state === void 0 ? {} : { state }
+    });
+    setController(created);
+    return () => {
+      setController(null);
+      created.dispose();
+    };
+  }, [map, family, labels, state]);
+  useEffect(() => {
+    if (!controller) return;
+    if (values) controller.set(values);
+    else controller.clear();
+  }, [controller, values]);
+}
+
 // src/map.tsx
 import {
   useCallback,
-  useEffect,
+  useEffect as useEffect2,
   useLayoutEffect,
   useMemo,
   useRef,
-  useState
+  useState as useState2
 } from "react";
 import { createPortal } from "react-dom";
 import {
@@ -313,7 +341,7 @@ function Map2(props) {
   const vegetationRef = useRef(void 0);
   const vegetationInputsRef = useRef({ vegetation, viewMode });
   vegetationInputsRef.current = { vegetation, viewMode };
-  useEffect(() => {
+  useEffect2(() => {
     vegetationRef.current?.setVisible(vegetation);
     vegetationRef.current?.setViewMode(viewMode);
   }, [vegetation, viewMode]);
@@ -338,26 +366,26 @@ function Map2(props) {
   const renderPopupRef = useRef(renderPopup);
   const renderTooltipRef = useRef(renderTooltip);
   const reportedDeclarativeDiagnosticKeysRef = useRef(/* @__PURE__ */ new Set());
-  const [manifestResolution, setManifestResolution] = useState({
+  const [manifestResolution, setManifestResolution] = useState2({
     key: "",
     map: null,
     state: "loading"
   });
-  const [systemColorScheme, setSystemColorScheme] = useState("light");
-  const [imageSize, setImageSize] = useState(null);
-  const [captureState, setCaptureState] = useState("loading");
-  const [themeTransitionState, setThemeTransitionState] = useState(
+  const [systemColorScheme, setSystemColorScheme] = useState2("light");
+  const [imageSize, setImageSize] = useState2(null);
+  const [captureState, setCaptureState] = useState2("loading");
+  const [themeTransitionState, setThemeTransitionState] = useState2(
     "idle"
   );
-  const [activeRuntimeResource, setActiveRuntimeResource] = useState(void 0);
-  const [annotationRenderTargets, setAnnotationRenderTargets] = useState([]);
-  const [semanticRenderTargets, setSemanticRenderTargets] = useState([]);
-  const [annotationBridgeDiagnostic, setAnnotationBridgeDiagnostic] = useState();
-  const [semanticBridgeDiagnostic, setSemanticBridgeDiagnostic] = useState();
-  const [stateBridgeDiagnostic, setStateBridgeDiagnostic] = useState();
-  const [rendererBridgeDiagnostic, setRendererBridgeDiagnostic] = useState();
-  const [annotationDiagnostics, setAnnotationDiagnostics] = useState([]);
-  const [semanticDiagnostics, setSemanticDiagnostics] = useState([]);
+  const [activeRuntimeResource, setActiveRuntimeResource] = useState2(void 0);
+  const [annotationRenderTargets, setAnnotationRenderTargets] = useState2([]);
+  const [semanticRenderTargets, setSemanticRenderTargets] = useState2([]);
+  const [annotationBridgeDiagnostic, setAnnotationBridgeDiagnostic] = useState2();
+  const [semanticBridgeDiagnostic, setSemanticBridgeDiagnostic] = useState2();
+  const [stateBridgeDiagnostic, setStateBridgeDiagnostic] = useState2();
+  const [rendererBridgeDiagnostic, setRendererBridgeDiagnostic] = useState2();
+  const [annotationDiagnostics, setAnnotationDiagnostics] = useState2([]);
+  const [semanticDiagnostics, setSemanticDiagnostics] = useState2([]);
   const stableMapOptions = useStableMapOptions(mapOptions);
   const resolvedCaptureId = normalizeTileflowCaptureId(captureId);
   const resolvedMode = resolveTileflowMapMode({ mode });
@@ -484,12 +512,12 @@ function Map2(props) {
   renderPopupRef.current = renderPopup;
   renderTooltipRef.current = renderTooltip;
   onThemeChangeRef.current = props.onThemeChange;
-  useEffect(() => {
+  useEffect2(() => {
     if (theme !== "system") return;
     setSystemColorScheme(getTileflowSystemColorScheme());
     return subscribeTileflowSystemColorScheme(setSystemColorScheme);
   }, [theme]);
-  useEffect(() => {
+  useEffect2(() => {
     const previousKeys = reportedDeclarativeDiagnosticKeysRef.current;
     const nextKeys = /* @__PURE__ */ new Set();
     for (const diagnostic of declarativeInteractionDiagnostics) {
@@ -499,7 +527,7 @@ function Map2(props) {
     }
     reportedDeclarativeDiagnosticKeysRef.current = nextKeys;
   }, [declarativeInteractionDiagnostics]);
-  useEffect(() => {
+  useEffect2(() => {
     let cancelled = false;
     setManifestResolution({ key: manifestRequestKey, map: null, state: "loading" });
     loadTileflowManifest(manifestUrl).then((manifest) => {
@@ -556,7 +584,7 @@ function Map2(props) {
     () => mergeTileflowAnalytics(analytics, runtimeStyle?.analytics),
     [analytics, runtimeStyle]
   );
-  useEffect(() => {
+  useEffect2(() => {
     centerRef.current = resolvedCenter;
     zoomRef.current = resolvedZoom;
     bearingRef.current = resolvedBearing;
@@ -568,13 +596,13 @@ function Map2(props) {
       zoom: resolvedZoom
     });
   }, [resolvedBearing, resolvedCenter, resolvedPitch, resolvedZoom]);
-  useEffect(() => {
+  useEffect2(() => {
     onLoadRef.current = onLoad;
   }, [onLoad]);
-  useEffect(() => {
+  useEffect2(() => {
     mapNameRef.current = mapName;
   }, [mapName]);
-  useEffect(() => {
+  useEffect2(() => {
     resolvedAnalyticsRef.current = resolvedAnalytics;
   }, [resolvedAnalytics]);
   const runtimeImageUrl = useMemo(
@@ -610,7 +638,7 @@ function Map2(props) {
   })();
   const currentCaptureState = activeRuntimeResource === (isImageMode ? runtimeImageUrl : runtimeStyle) ? captureState : "loading";
   const effectiveCaptureState = currentCaptureState === "error" || interactionReadiness === "error" || runtimeResolutionState === "error" || themeTransitionState === "error" ? "error" : currentCaptureState === "idle" && interactionReadiness === "idle" && runtimeResolutionState === "idle" && themeTransitionState === "idle" ? "idle" : "loading";
-  useEffect(() => {
+  useEffect2(() => {
     if (!isImageMode || imageUrl || !containerRef.current) {
       setImageSize(null);
       return;
@@ -632,7 +660,7 @@ function Map2(props) {
       resizeObserver.disconnect();
     };
   }, [imageUrl, isImageMode]);
-  useEffect(() => {
+  useEffect2(() => {
     const runtime = interactionRuntimeRef.current;
     if (!runtime || !preparedAnnotations.ok) return;
     try {
@@ -647,7 +675,7 @@ function Map2(props) {
       onInteractionDiagnosticRef.current?.(diagnostic);
     }
   }, [preparedAnnotations]);
-  useEffect(() => {
+  useEffect2(() => {
     const runtime = semanticRuntimeRef.current;
     if (!runtime || !preparedInteractions.ok) return;
     try {
@@ -662,7 +690,7 @@ function Map2(props) {
       onInteractionDiagnosticRef.current?.(diagnostic);
     }
   }, [preparedInteractions]);
-  useEffect(() => {
+  useEffect2(() => {
     if (!preparedInteractionState.controlled || !preparedInteractionState.ok) return;
     try {
       setStateBridgeDiagnostic(void 0);
@@ -677,7 +705,7 @@ function Map2(props) {
       onInteractionDiagnosticRef.current?.(diagnostic);
     }
   }, [preparedInteractionState]);
-  useEffect(() => {
+  useEffect2(() => {
     const annotationRuntime = interactionRuntimeRef.current;
     const semanticRuntime = semanticRuntimeRef.current;
     if (!annotationRuntime && !semanticRuntime) return;
@@ -701,7 +729,7 @@ function Map2(props) {
       onInteractionDiagnosticRef.current?.(diagnostic);
     }
   }, [renderMarker, renderPopup, renderTooltip]);
-  useEffect(() => {
+  useEffect2(() => {
     setThemeTransitionState("idle");
     const initialRuntimeStyle = runtimeStyleRef.current;
     if (!containerRef.current || !initialRuntimeStyle) {
@@ -1038,7 +1066,7 @@ function Map2(props) {
       disposeMap?.();
     };
   }, [resolvedInteractive, runtimeMapIdentity, runtimeStyleReady, stableMapOptions]);
-  useEffect(() => {
+  useEffect2(() => {
     const controller = themeControllerRef.current;
     if (!controller || themeBlendKey) return;
     if (themeResolution.error) {
@@ -1054,7 +1082,7 @@ function Map2(props) {
       }
     });
   }, [runtimeStyle, themeBlendKey, themeResolution.error]);
-  useEffect(() => {
+  useEffect2(() => {
     const controller = themeControllerRef.current;
     if (!controller || !blendStyles || themeBlendPosition === void 0) return;
     if (runtimeStyle) setActiveRuntimeResource(runtimeStyle);
@@ -1278,11 +1306,11 @@ function useTileflowPortalReadiness(portalKeys) {
     expectedKeysRef.current = { keys: [...portalKeys].sort(), token };
   }
   const expectedKeys = expectedKeysRef.current.keys;
-  const [committed, setCommitted] = useState(() => ({
+  const [committed, setCommitted] = useState2(() => ({
     keys: /* @__PURE__ */ new Set(),
     token
   }));
-  const [readyToken, setReadyToken] = useState(token);
+  const [readyToken, setReadyToken] = useState2(token);
   const readinessRunRef = useRef(0);
   const markCommitted = useCallback((committedToken, portalKey) => {
     setCommitted((current) => {
@@ -1412,5 +1440,6 @@ function isPlainObject(value) {
 }
 export {
   Map2 as Map,
-  configureTileflowMapLibre
+  configureTileflowMapLibre,
+  useBoundaryFeatureState
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/react",
-  "version": "0.1.0-alpha.30",
+  "version": "0.1.0-alpha.31",
   "license": "Apache-2.0",
   "description": "React components for rendering Tileflow maps with MapLibre.",
   "type": "module",
@@ -43,7 +43,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@tileflow/core": ">=0.1.0-alpha.35 <0.1.0-beta.0",
+    "@tileflow/core": ">=0.1.0-alpha.36 <0.1.0-beta.0",
     "@tileflow/interactions": ">=0.1.0-alpha.5 <0.1.0-beta.0",
     "@tileflow/static": ">=0.1.0-alpha.28 <0.1.0-beta.0"
   },