@tileflow/react 0.1.0-alpha.36 → 0.1.0-alpha.38

package/README.md

@@ -19,6 +19,12 @@ npm install --save-dev --save-exact tileflow@alpha
 The supported peer ranges are React/React DOM 18–19 and MapLibre GL JS `>=6.4.1 <7`. The worker
 must come from the same MapLibre installation as the main module.
 
+Prepared styles may retain relative asset URLs. The component loads them through Core's shared
+resource loader before creating the map and before changing or blending themes. Sprites, fonts,
+data and model resources resolve against their declaring documents. Pending document loads are
+cancelled when the map is replaced or unmounted; `mapOptions.transformRequest` also applies to
+style and HTTP TileJSON requests.
+
 ## Prepare a map
 
 Create `tileflow.config.ts` at the application root:
@@ -103,7 +109,7 @@ Add `timeOfDay="dusk"` beside `theme` to select a map's optional `day`, `dawn`,
 `night` preset. For Streets, `theme="light"` with this preset selects the existing `dusk` palette.
 Maps without this capability ignore the option; omitting it keeps the selected theme unchanged.
 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).
+[authoring contract](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/REFERENCE.md#style-with-themes-and-semantic-modules).
 
 Theme and `timeOfDay` changes cross-fade over 450 ms by default, respecting reduced motion.
 `themeTransition={{duration: 700}}` customizes the duration; use `duration: 0` for an immediate change.
@@ -239,6 +245,26 @@ annotation-only. See the
 Text/field content uses safe text defaults. A `view` is an application renderer name, not HTML.
 Keep tooltips non-interactive; put buttons, links, and forms in popups.
 
+## Cluster points and draw density
+
+Use `annotationClusters` for up to 1,000 annotations, or `dataSources` and `dataOverlays` for larger
+GeoJSON sets. Clicking a cluster zooms in and reports a `cluster` target through `onInteractionEvent`.
+
+<!-- docs:check -->
+
+```ts
+import {clusterOverlay, geojsonSource} from '@tileflow/core/runtime';
+
+export const dataSources = {stores: geojsonSource({cluster: true, clusterRadius: 50})};
+export const dataOverlays = {
+  stores: clusterOverlay({id: 'stores', placement: 'above-labels', source: 'stores'}),
+};
+```
+
+See the
+[interactions reference](https://github.com/tileflow/tileflow-sdk/blob/main/packages/interactions/REFERENCE.md)
+for heatmaps, events, and polygon drawing with Terra Draw.
+
 ## Display an image or create a render
 
 `<Map mode="image">` displays an explicit `imageUrl` or derives an image URL from the selected

package/dist/index.d.ts

@@ -1,10 +1,11 @@
 import { Map as Map$1, MapOptions } from 'maplibre-gl';
-import { TileflowBoundaryValues } from '@tileflow/core';
+import { TileflowBoundaryValues, TileflowMapLibreOverlay, TileflowGeoJsonSource } 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 { TileflowRuntimeSource, TileflowThemeSelection, TileflowTimeOfDay, TileflowAnalytics } from '@tileflow/core/runtime';
 import { TileflowAnnotation, TileflowInteractionState, TileflowAnnotationViewContext, TileflowInteractionBinding, TileflowInteractionViewContext, TileflowInteractionDiagnostic, TileflowInteractionEvent } from '@tileflow/interactions';
+import { TileflowAnnotationClusterOptions } from '@tileflow/interactions/maplibre';
 
 /**
  * Keep a map's Boundaries feature-state equal to `values`. Pass the map from `<Map onLoad>` and
@@ -65,7 +66,13 @@ type TileflowInteractionRendererProps<TAnnotation extends TileflowAnnotation> =
     renderTooltip?: TileflowInteractionRenderer<TAnnotation>;
 }>;
 type MapInteractiveProps<TAnnotation extends TileflowAnnotation> = MapSharedProps & TileflowInteractionStateInputProps & TileflowInteractionRendererProps<TAnnotation> & {
+    /** Group `annotations` into accessible cluster buttons. Up to 1,000 annotations. */
+    annotationClusters?: TileflowAnnotationClusterOptions;
     annotations?: readonly TAnnotation[];
+    /** Overlays drawn over `dataSources` or compiled sources, keyed as in `defineMap`. */
+    dataOverlays?: Readonly<Record<string, TileflowMapLibreOverlay>>;
+    /** Application GeoJSON, keyed as in `defineMap`. A compiled source of the same key is filled. */
+    dataSources?: Readonly<Record<string, TileflowGeoJsonSource>>;
     mode?: 'interactive';
     onInteractionDiagnostic?: (diagnostic: TileflowInteractionDiagnostic) => void;
     onInteractionEvent?: (event: TileflowInteractionEvent<TAnnotation>) => void;
@@ -73,7 +80,10 @@ type MapInteractiveProps<TAnnotation extends TileflowAnnotation> = MapSharedProp
     renderMarker?: TileflowAnnotationRenderer<TAnnotation>;
 };
 type MapImageProps = MapSharedProps & {
+    annotationClusters?: never;
     annotations?: never;
+    dataOverlays?: never;
+    dataSources?: never;
     defaultInteractionState?: never;
     interactionState?: never;
     interactions?: never;

package/dist/index.js

@@ -51,6 +51,7 @@ import {
   createTileflowThemeController,
   createTileflowTransformRequest,
   getTileflowSystemColorScheme,
+  loadTileflowRuntimeStyle,
   loadTileflowStyleFonts,
   registerTileflowContourProtocol,
   registerTileflowPathGroundProtocol,
@@ -79,6 +80,7 @@ import {
   resolveTileflowStaticImageUrl
 } from "@tileflow/core/runtime";
 import {
+  createTileflowMapLibreDataRuntime,
   createTileflowMapLibreDomRuntime,
   createTileflowMapLibreInteractionCoordinator,
   createTileflowMapLibreSemanticDomRuntime
@@ -284,7 +286,10 @@ var defaultInteractions = [];
 function Map2(props) {
   assertTileflowMapStyleInputs(props);
   const {
+    annotationClusters,
     annotations,
+    dataOverlays,
+    dataSources,
     captureId,
     defaultInteractionState,
     mode = "interactive",
@@ -361,6 +366,8 @@ function Map2(props) {
   const interactionCoordinatorRef = useRef(
     void 0
   );
+  const dataRuntimeRef = useRef(void 0);
+  const dataInputRef = useRef({});
   const annotationsRef = useRef(preparedAnnotations.annotations);
   const annotationTitlesRef = useRef(preparedAnnotations.titles);
   const preparedInteractionsRef = useRef(preparedInteractions);
@@ -455,7 +462,7 @@ function Map2(props) {
   const mapNameRef = useRef(mapName);
   const resolvedAnalyticsRef = useRef(void 0);
   const readinessRunRef = useRef(0);
-  const hasAdditionalInteractionConfiguration = annotations !== void 0 || defaultInteractionState !== void 0 || interactionState !== void 0 || onInteractionDiagnostic !== void 0 || onInteractionEvent !== void 0 || onInteractionStateChange !== void 0 || renderMarker !== void 0 || renderPopup !== void 0 || renderTooltip !== void 0 || props.interactions !== void 0;
+  const hasAdditionalInteractionConfiguration = annotationClusters !== void 0 || annotations !== void 0 || dataOverlays !== void 0 || dataSources !== void 0 || defaultInteractionState !== void 0 || interactionState !== void 0 || onInteractionDiagnostic !== void 0 || onInteractionEvent !== void 0 || onInteractionStateChange !== void 0 || renderMarker !== void 0 || renderPopup !== void 0 || renderTooltip !== void 0 || props.interactions !== void 0;
   const modeDiagnostic = useMemo(
     () => isImageMode ? imageModeMapInteractionDiagnostic(
       preparedAnnotations.annotations.length,
@@ -682,6 +689,15 @@ function Map2(props) {
       onInteractionDiagnosticRef.current?.(diagnostic);
     }
   }, [preparedAnnotations]);
+  dataInputRef.current = {
+    annotationClusters,
+    annotations: preparedAnnotations.annotations,
+    dataOverlays,
+    dataSources
+  };
+  useEffect2(() => {
+    dataRuntimeRef.current?.reconcile(dataInputRef.current);
+  }, [annotationClusters, dataOverlays, dataSources, preparedAnnotations]);
   useEffect2(() => {
     const runtime = semanticRuntimeRef.current;
     if (!runtime || !preparedInteractions.ok) return;
@@ -748,12 +764,28 @@ function Map2(props) {
     const container = containerRef.current;
     let cancelled = false;
     let disposeMap;
+    const resourceLifetime = new AbortController();
+    const session = createTileflowSessionController({ source: "react" });
+    const resourceTransform = createTileflowTransformRequest({
+      getAnalytics: () => resolvedAnalyticsRef.current,
+      sessionController: session,
+      sessionId: session.sessionId,
+      transformRequest: stableMapOptions?.transformRequest ?? void 0
+    });
+    const styleLoadOptions = {
+      signal: resourceLifetime.signal,
+      transformRequest: (url, type) => resourceTransform(
+        url,
+        type
+      )
+    };
     void Promise.all([
       loadTileflowMapLibre(),
-      loadTileflowStyleFonts(initialRuntimeStyle.style, {
-        fontFaces: initialRuntimeStyle.fontFaces
+      loadTileflowRuntimeStyle(initialRuntimeStyle, styleLoadOptions).then(async (prepared) => {
+        await loadTileflowStyleFonts(prepared.style, { fontFaces: prepared.fontFaces });
+        return prepared;
       })
-    ]).then(([maplibregl]) => {
+    ]).then(([maplibregl, prepared]) => {
       if (cancelled || containerRef.current !== container) {
         return;
       }
@@ -787,7 +819,6 @@ function Map2(props) {
           setRendererBridgeDiagnostic(void 0);
         }
       };
-      const session = createTileflowSessionController({ source: "react" });
       const sessionStarter = createTileflowSessionStarter({
         getSessionId: () => session.sessionId,
         sessionId: session.sessionId,
@@ -816,7 +847,7 @@ function Map2(props) {
           stableMapOptions?.canvasContextAttributes
         ),
         container,
-        style: initialRuntimeStyle.style,
+        style: prepared.style,
         bearing: bearingRef.current,
         center: centerRef.current,
         pitch: pitchRef.current,
@@ -839,7 +870,9 @@ function Map2(props) {
       registerCleanup(attachTileflowLabelPlacement(map));
       registerCleanup(attachTileflowHorizonQueries(map));
       const themeController = initialRuntimeStyle.theme === void 0 ? void 0 : createTileflowThemeController({
-        initial: initialRuntimeStyle,
+        initial: prepared.family ? prepared : initialRuntimeStyle,
+        initialStyle: prepared.style,
+        styleLoadOptions,
         map,
         onTransition(transition) {
           onThemeChangeRef.current?.(transition);
@@ -933,6 +966,23 @@ function Map2(props) {
       interactionRuntimeRef.current = interactionRuntime;
       setupResources.annotationRuntime = interactionRuntime;
       registerCleanup(() => interactionRuntime.dispose());
+      const dataRuntime = createTileflowMapLibreDataRuntime({
+        createMarker: ({ element }) => wrapMapLibrePositioned(new maplibregl.Marker({ element })),
+        document: container.ownerDocument,
+        map,
+        onDiagnostic(diagnostic) {
+          onInteractionDiagnosticRef.current?.(diagnostic);
+        },
+        onInteractionEvent(event) {
+          onInteractionEventRef.current?.(event);
+        },
+        setHiddenAnnotations: interactionRuntime.setHiddenAnnotations
+      });
+      dataRuntimeRef.current = dataRuntime;
+      registerCleanup(() => {
+        dataRuntime.dispose();
+        if (dataRuntimeRef.current === dataRuntime) dataRuntimeRef.current = void 0;
+      });
       const semanticRuntime = createTileflowMapLibreSemanticDomRuntime({
         cancelFrame: (frame) => browserWindow.cancelAnimationFrame(frame),
         createOverlay({ container: overlayContainer, kind }) {
@@ -1011,6 +1061,7 @@ function Map2(props) {
         setAnnotationBridgeDiagnostic(diagnostic);
         onInteractionDiagnosticRef.current?.(diagnostic);
       }
+      dataRuntime.reconcile(dataInputRef.current);
       const initialInteractions = preparedInteractionsRef.current;
       if (initialInteractions.ok) {
         try {
@@ -1070,6 +1121,7 @@ function Map2(props) {
         });
       }
     }).catch((error) => {
+      resourceLifetime.abort();
       try {
         disposeMap?.();
       } catch (cleanupError) {
@@ -1082,6 +1134,7 @@ function Map2(props) {
     });
     return () => {
       cancelled = true;
+      resourceLifetime.abort();
       readinessRunRef.current += 1;
       disposeMap?.();
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/react",
-  "version": "0.1.0-alpha.36",
+  "version": "0.1.0-alpha.38",
   "license": "Apache-2.0",
   "description": "React components for rendering Tileflow maps with MapLibre.",
   "type": "module",
@@ -43,9 +43,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@tileflow/core": ">=0.1.0-alpha.43 <0.1.0-beta.0",
-    "@tileflow/interactions": ">=0.1.0-alpha.7 <0.1.0-beta.0",
-    "@tileflow/static": ">=0.1.0-alpha.29 <0.1.0-beta.0"
+    "@tileflow/core": ">=0.1.0-alpha.48 <0.1.0-beta.0",
+    "@tileflow/interactions": ">=0.1.0-alpha.8 <0.1.0-beta.0",
+    "@tileflow/static": ">=0.1.0-alpha.30 <0.1.0-beta.0"
   },
   "peerDependencies": {
     "maplibre-gl": ">=6.4.1 <7",
@@ -55,7 +55,7 @@
   "devDependencies": {
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
-    "maplibre-gl": "6.13.0",
+    "maplibre-gl": "6.16.0",
     "react": "^19.3.0",
     "react-dom": "^19.3.0"
   },