@tileflow/react 0.1.0-alpha.27 → 0.1.0-alpha.29

package/README.md

@@ -99,6 +99,12 @@ for assets.
 explicit light/dark mapping, which Streets supplies. Theme changes preserve the MapLibre instance,
 camera, and interactions, and roll back on failure. `onThemeChange` reports transitions.
 
+`themeTransition={{duration: 450}}` cross-fades theme changes over that many milliseconds.
+`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. Moving the position updates the map at once. See
+[theme transitions and blends](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/theme-transitions-and-blends.md).
+
 `mapOptions` accepts native MapLibre options except `container` and `style`. Direct camera props
 take priority over `mapOptions`, then the manifest view, then shared defaults. `Map` always selects
 a Tileflow map through its manifest; it has no renderer discriminator or direct-style mode.
@@ -202,7 +208,7 @@ Tileflow credentials on that server, not in React props or a browser bundle.
 ```tsx
 import {useState} from 'react';
 import {StaticMap} from '@tileflow/react/static';
-import type {StaticMapAttributionEntry} from '@tileflow/static';
+import type {StaticMapAttributionEntry} from '@tileflow/static/client';
 
 export function StaticPreview({idempotencyKey}: {idempotencyKey: string}) {
   const [entries, setEntries] = useState<readonly StaticMapAttributionEntry[]>([]);

package/dist/index.d.ts

@@ -1,13 +1,21 @@
 import * as react from 'react';
 import { CSSProperties, ImgHTMLAttributes, ReactNode } from 'react';
 import { MapOptions, Map as Map$1 } from 'maplibre-gl';
-import { TileflowThemeTransition } from '@tileflow/core/browser';
+import { TileflowBrowserThemeBlendSelection, TileflowThemeTransitionOptions, TileflowThemeTransition } from '@tileflow/core/browser';
 import { TileflowRuntimeSource, TileflowThemeSelection, TileflowAnalytics } from '@tileflow/core/runtime';
 import { TileflowAnnotation, TileflowInteractionState, TileflowAnnotationViewContext, TileflowInteractionBinding, TileflowInteractionViewContext, TileflowInteractionDiagnostic, TileflowInteractionEvent } from '@tileflow/interactions';
 
 type TileflowMapStyleSourceProps = {
     source: TileflowRuntimeSource;
     theme?: TileflowThemeSelection;
+    /**
+     * Shows a continuous blend of the map's themes instead of `theme`. Moving `position` changes the
+     * map at once; changing `themes` prepares a new blend. `hold` keeps labels, icons, and mixed
+     * artwork back during a camera move; clearing it brings them in at once.
+     */
+    themeBlend?: TileflowBrowserThemeBlendSelection;
+    /** Cross-fades theme changes, including entering and leaving a blend. */
+    themeTransition?: TileflowThemeTransitionOptions;
 };
 
 type TileflowMapSource = TileflowRuntimeSource;

package/dist/index.js

@@ -31,12 +31,14 @@ import {
   defaultTileflowRuntimeView,
   loadTileflowManifest,
   mergeTileflowAnalytics,
+  nearestTileflowBlendTheme,
   normalizeTileflowRuntimeCenter,
   normalizeTileflowStaticImageSize,
   resolveTileflowManifestMap,
   resolveTileflowMapMode,
   resolveTileflowRuntimeStyle,
   resolveTileflowRuntimeTheme,
+  resolveTileflowRuntimeThemeBlend,
   resolveTileflowRuntimeView,
   resolveTileflowStaticImageUrl
 } from "@tileflow/core/runtime";
@@ -165,6 +167,9 @@ function prepareTileflowReactInteractionState(interactionState, defaultInteracti
 }
 
 // src/map-style-inputs.ts
+import {
+  validateTileflowBrowserThemeBlendSelection
+} from "@tileflow/core/browser";
 import {
   validateTileflowRuntimeSource,
   validateTileflowThemeSelection
@@ -175,8 +180,25 @@ function validateTileflowMapStyleInputs(input) {
   if (input.theme !== void 0 && !validateTileflowThemeSelection(input.theme)) {
     return { error: 'theme must be a concrete portable theme name or "system"', ok: false };
   }
+  if (input.themeBlend !== void 0 && !validateTileflowBrowserThemeBlendSelection(input.themeBlend)) {
+    return {
+      error: "themeBlend must name two to eight concrete themes, a position from 0 to themes.length - 1, and an optional boolean hold",
+      ok: false
+    };
+  }
+  if (input.themeTransition !== void 0 && !isThemeTransition(input.themeTransition)) {
+    return {
+      error: "themeTransition.duration must be a number of milliseconds from 0 to 5000",
+      ok: false
+    };
+  }
   return { ok: true };
 }
+function isThemeTransition(value) {
+  if (!value || typeof value !== "object") return false;
+  const { duration } = value;
+  return duration === void 0 || typeof duration === "number" && Number.isFinite(duration) && duration >= 0 && duration <= 5e3;
+}
 function assertTileflowMapStyleInputs(input) {
   const validation = validateTileflowMapStyleInputs(input);
   if (!validation.ok) {
@@ -238,6 +260,8 @@ function Map2(props) {
     mapOptions,
     analytics,
     theme,
+    themeBlend,
+    themeTransition,
     interactionState,
     interactions = defaultInteractions,
     onInteractionDiagnostic,
@@ -326,19 +350,32 @@ function Map2(props) {
   const manifestRequestKey = JSON.stringify([manifestUrl, mapName]);
   const currentManifestResolution = manifestResolution.key === manifestRequestKey ? manifestResolution : { key: manifestRequestKey, map: null, state: "loading" };
   const manifestMap = currentManifestResolution.state === "ready" ? currentManifestResolution.map : null;
+  const themeBlendKey = themeBlend ? JSON.stringify(themeBlend.themes) : void 0;
+  const themeBlendPosition = themeBlend?.position;
+  const themeBlendHold = themeBlend?.hold === true;
+  const blendThemeName = themeBlend ? nearestTileflowBlendTheme(themeBlend) : void 0;
   const themeResolution = useMemo(() => {
+    const selection = blendThemeName ?? theme;
     if (!manifestMap) {
-      return { error: false, name: theme && theme !== "system" ? theme : void 0 };
+      return {
+        error: false,
+        name: selection && selection !== "system" ? selection : void 0
+      };
     }
     try {
+      if (themeBlendKey) {
+        for (const name of JSON.parse(themeBlendKey)) {
+          resolveTileflowRuntimeTheme(manifestMap, name);
+        }
+      }
       return {
         error: false,
-        name: resolveTileflowRuntimeTheme(manifestMap, theme, systemColorScheme).name
+        name: resolveTileflowRuntimeTheme(manifestMap, selection, systemColorScheme).name
       };
     } catch {
       return { error: true, name: void 0 };
     }
-  }, [manifestMap, systemColorScheme, theme]);
+  }, [blendThemeName, manifestMap, systemColorScheme, theme, themeBlendKey]);
   const resolvedThemeName = themeResolution.name;
   const manifestView = resolveTileflowRuntimeView({ manifestMap });
   const manifestCenter = useStableMapOptionValue(
@@ -477,6 +514,22 @@ function Map2(props) {
     });
   }, [isImageMode, manifestMap, runtimeSource, systemColorScheme, themeResolution]);
   runtimeStyleRef.current = runtimeStyle;
+  const blendStyles = useMemo(() => {
+    if (isImageMode || !manifestMap || !themeBlendKey) return null;
+    try {
+      return resolveTileflowRuntimeThemeBlend({
+        blend: { position: 0, themes: JSON.parse(themeBlendKey) },
+        manifestMap,
+        source: runtimeSource
+      });
+    } catch {
+      return null;
+    }
+  }, [isImageMode, manifestMap, runtimeSource, themeBlendKey]);
+  const blendRequestRef = useRef(null);
+  blendRequestRef.current = blendStyles && themeBlendPosition !== void 0 ? { hold: themeBlendHold, position: themeBlendPosition, themes: blendStyles } : null;
+  const themeTransitionRef = useRef(themeTransition);
+  themeTransitionRef.current = themeTransition;
   const runtimeMapIdentity = `${manifestUrl}\0${runtimeSource.map}`;
   const runtimeStyleReady = runtimeStyle !== null || themeResolution.error && mapRef.current !== null;
   const resolvedAnalytics = useMemo(
@@ -695,8 +748,6 @@ function Map2(props) {
       });
       registerCleanup(() => worldRequestBridge.dispose());
       const transformRequest = createTileflowTransformRequest({
-        always: true,
-        asyncAnalyticsTiming: "resolution",
         getAnalytics: () => resolvedAnalyticsRef.current,
         sessionController: session,
         sessionId: session.sessionId,
@@ -919,9 +970,15 @@ function Map2(props) {
       });
       registerCleanup(() => lifecycle.dispose());
       const latestRuntimeStyle = runtimeStyleRef.current;
-      if (themeController && latestRuntimeStyle && latestRuntimeStyle !== initialRuntimeStyle) {
+      const latestBlend = blendRequestRef.current;
+      if (themeController && latestBlend) {
+        if (latestRuntimeStyle) setActiveRuntimeResource(latestRuntimeStyle);
+        void themeController.setBlend(latestBlend, { transition: themeTransitionRef.current });
+      } else if (themeController && latestRuntimeStyle && latestRuntimeStyle !== initialRuntimeStyle) {
         setActiveRuntimeResource(latestRuntimeStyle);
-        void themeController.setTheme(latestRuntimeStyle);
+        void themeController.setTheme(latestRuntimeStyle, {
+          transition: themeTransitionRef.current
+        });
       }
     }).catch((error) => {
       try {
@@ -942,19 +999,33 @@ function Map2(props) {
   }, [resolvedInteractive, runtimeMapIdentity, runtimeStyleReady, stableMapOptions]);
   useEffect(() => {
     const controller = themeControllerRef.current;
-    if (!controller) return;
+    if (!controller || themeBlendKey) return;
     if (themeResolution.error) {
       void controller.setTheme(controller.getCurrent());
       return;
     }
-    if (!runtimeStyle || controller.getCurrent() === runtimeStyle) return;
+    if (!runtimeStyle || controller.getCurrent() === runtimeStyle && !controller.getBlend())
+      return;
     setActiveRuntimeResource(runtimeStyle);
-    void controller.setTheme(runtimeStyle).then((result) => {
+    void controller.setTheme(runtimeStyle, { transition: themeTransitionRef.current }).then((result) => {
       if (result.status === "failed") {
         console.error("Failed to change the Tileflow map theme", result.error);
       }
     });
-  }, [runtimeStyle, themeResolution.error]);
+  }, [runtimeStyle, themeBlendKey, themeResolution.error]);
+  useEffect(() => {
+    const controller = themeControllerRef.current;
+    if (!controller || !blendStyles || themeBlendPosition === void 0) return;
+    if (runtimeStyle) setActiveRuntimeResource(runtimeStyle);
+    void controller.setBlend(
+      { hold: themeBlendHold, position: themeBlendPosition, themes: blendStyles },
+      { transition: themeTransitionRef.current }
+    ).then((result) => {
+      if (result.status === "failed") {
+        console.error("Failed to blend the Tileflow map themes", result.error);
+      }
+    });
+  }, [blendStyles, runtimeStyle, themeBlendHold, themeBlendPosition]);
   useLayoutEffect(() => {
     if (!isImageMode) return;
     readinessRunRef.current += 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/react",
-  "version": "0.1.0-alpha.27",
+  "version": "0.1.0-alpha.29",
   "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.29 <0.1.0-beta.0",
+    "@tileflow/core": ">=0.1.0-alpha.32 <0.1.0-beta.0",
     "@tileflow/interactions": ">=0.1.0-alpha.4 <0.1.0-beta.0",
-    "@tileflow/static": ">=0.1.0-alpha.27 <0.1.0-beta.0"
+    "@tileflow/static": ">=0.1.0-alpha.28 <0.1.0-beta.0"
   },
   "peerDependencies": {
     "maplibre-gl": ">=6.4.1 <7",
@@ -53,11 +53,11 @@
     "react-dom": ">=18 <20"
   },
   "devDependencies": {
-    "@types/react": "^19.2.17",
-    "@types/react-dom": "^19.2.3",
-    "maplibre-gl": "6.9.0",
-    "react": "^19.2.7",
-    "react-dom": "^19.2.7"
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "maplibre-gl": "6.13.0",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0"
   },
   "scripts": {
     "build": "tsup",