@tileflow/svelte 0.1.0-alpha.26 → 0.1.0-alpha.28

package/README.md

@@ -90,6 +90,12 @@ Omitting `theme` uses `defaultTheme`. `system` needs an explicit light/dark mapp
 supplies. Theme changes keep 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 props win over
 those options, then the manifest view, then shared defaults. `TileflowMap` always selects a Tileflow
 map through its manifest; it has no renderer discriminator or direct-style mode. The obsolete

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/svelte",
-  "version": "0.1.0-alpha.26",
+  "version": "0.1.0-alpha.28",
   "license": "Apache-2.0",
   "description": "Svelte component for rendering Tileflow maps with MapLibre.",
   "type": "module",
@@ -44,7 +44,7 @@
     "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"
   },
   "peerDependencies": {
@@ -52,8 +52,8 @@
     "svelte": ">=5 <6"
   },
   "devDependencies": {
-    "maplibre-gl": "6.9.0",
-    "svelte": "^5.43.17",
+    "maplibre-gl": "6.13.0",
+    "svelte": "^5.57.2",
     "svelte-check": "^4.3.4"
   },
   "scripts": {

package/src/TileflowMap.svelte

@@ -15,15 +15,18 @@
     defaultTileflowRuntimeView,
     loadTileflowManifest,
     mergeTileflowAnalytics,
+    nearestTileflowBlendTheme,
     normalizeTileflowRuntimeCenter,
     normalizeTileflowStaticImageSize,
     resolveTileflowManifestMap,
     resolveTileflowMapMode,
     resolveTileflowRuntimeStyle,
     resolveTileflowRuntimeTheme,
+    resolveTileflowRuntimeThemeBlend,
     resolveTileflowRuntimeView,
     resolveTileflowStaticImageUrl,
     type TileflowRuntimeManifestMap,
+    type TileflowRuntimeStyle,
   } from '@tileflow/core/runtime';
   import {
     attachTileflowAtmosphere,
@@ -96,6 +99,8 @@
   export let popup: TileflowMapProps['popup'] = undefined;
   export let source: TileflowMapProps['source'];
   export let theme: TileflowMapProps['theme'] = undefined;
+  export let themeBlend: TileflowMapProps['themeBlend'] = undefined;
+  export let themeTransition: TileflowMapProps['themeTransition'] = undefined;
   export let tooltip: TileflowMapProps['tooltip'] = undefined;
   export let zoom: TileflowMapProps['zoom'] = undefined;
 
@@ -167,7 +172,7 @@
         : {defaultInteractionState: initialInteractionState}),
     });
   $: resolvedMode = resolveTileflowMapMode({mode});
-  $: assertTileflowMapStyleInputs({source, theme});
+  $: assertTileflowMapStyleInputs({source, theme, themeBlend, themeTransition});
   $: resolvedCaptureId = normalizeTileflowCaptureId(captureId);
   $: isImageMode = resolvedMode === 'image';
   $: mapName = source.map;
@@ -183,7 +188,11 @@
     colorScheme: systemColorScheme,
     manifestMap,
     theme,
+    themeBlend,
   });
+  $: themeBlendKey = themeBlend ? JSON.stringify(themeBlend.themes) : undefined;
+  $: themeBlendPosition = themeBlend?.position;
+  $: themeBlendHold = themeBlend?.hold === true;
   $: resolvedThemeName = themeResolution.name;
   $: manifestView = resolveTileflowRuntimeView({manifestMap});
   $: manifestCenter = normalizeTileflowRuntimeCenter(manifestView.center);
@@ -204,6 +213,7 @@
           source,
           theme: themeResolution.name,
         });
+  $: blendStyles = resolveBlendStyles({isImageMode, key: themeBlendKey, manifestMap, source});
   $: resolvedAnalytics = mergeTileflowAnalytics(analytics, runtimeStyle?.analytics);
   $: runtimeImageUrl =
     imageUrl ??
@@ -295,8 +305,16 @@
     syncSystemColorSchemeSubscription();
   }
 
+  $: if (mounted) {
+    blendStyles;
+    themeBlendPosition;
+    themeBlendHold;
+    void switchBlend();
+  }
+
   $: if (mounted) {
     runtimeStyle;
+    themeBlendKey;
     void switchTheme();
   }
 
@@ -563,8 +581,6 @@
       pitch: resolvedPitch,
       style: runtime.style as StyleSpecification | string,
       transformRequest: createTileflowTransformRequest({
-        always: true,
-        asyncAnalyticsTiming: 'request',
         getAnalytics: () => resolvedAnalytics,
         sessionController: session,
         sessionId: session.sessionId,
@@ -755,14 +771,34 @@
         return () => subscription.unsubscribe();
       },
     });
-    if (themeController && runtimeStyle && runtimeStyle !== runtime) {
+    if (themeController && blendStyles && themeBlend) {
+      void switchBlend();
+    } else if (themeController && runtimeStyle && runtimeStyle !== runtime) {
       activeRuntimeResource = runtimeStyle;
-      void themeController.setTheme(runtimeStyle);
+      void themeController.setTheme(runtimeStyle, {transition: themeTransition});
+    }
+  }
+
+  async function switchBlend() {
+    const position = themeBlendPosition;
+    if (!themeController || !blendStyles || position === undefined) return;
+    if (runtimeStyle) activeRuntimeResource = runtimeStyle;
+    const result = await themeController.setBlend(
+      {hold: themeBlendHold, position, themes: blendStyles},
+      {transition: themeTransition},
+    );
+    if (result.status === 'failed') {
+      console.error('Failed to blend the Tileflow map themes', result.error);
     }
   }
 
   async function switchTheme() {
     if (!themeController) return;
+    if (themeBlend) {
+      // The blend names its nearest theme; the blend itself is applied by switchBlend.
+      if (runtimeStyle) activeRuntimeResource = runtimeStyle;
+      return;
+    }
     if (themeResolution.error) {
       await themeController.setTheme(themeController.getCurrent());
       return;
@@ -770,7 +806,7 @@
     const next = runtimeStyle;
     if (!next) return;
     activeRuntimeResource = next;
-    const result = await themeController.setTheme(next);
+    const result = await themeController.setTheme(next, {transition: themeTransition});
     if (result.status === 'failed') {
       console.error('Failed to change the Tileflow map theme', result.error);
     }
@@ -999,11 +1035,7 @@
   }
 
   type BridgeInteractionDiagnosticSource =
-    | 'annotation-runtime'
-    | 'portal'
-    | 'renderers'
-    | 'semantic-runtime'
-    | 'state';
+    'annotation-runtime' | 'portal' | 'renderers' | 'semantic-runtime' | 'state';
 
   function setBridgeInteractionDiagnostic(
     source: BridgeInteractionDiagnosticSource,
@@ -1206,24 +1238,48 @@
     colorScheme: 'dark' | 'light';
     manifestMap: TileflowRuntimeManifestMap | null;
     theme: TileflowMapProps['theme'];
+    themeBlend: TileflowMapProps['themeBlend'];
   }): Readonly<{error: boolean; name: string | undefined}> {
+    // A blend shows its nearest theme until the blend style is ready, and names it while blending.
+    const selection = input.themeBlend ? nearestTileflowBlendTheme(input.themeBlend) : input.theme;
     if (!input.manifestMap) {
       return {
         error: false,
-        name: input.theme && input.theme !== 'system' ? input.theme : undefined,
+        name: selection && selection !== 'system' ? selection : undefined,
       };
     }
 
     try {
+      for (const name of input.themeBlend?.themes ?? []) {
+        resolveTileflowRuntimeTheme(input.manifestMap, name);
+      }
       return {
         error: false,
-        name: resolveTileflowRuntimeTheme(input.manifestMap, input.theme, input.colorScheme).name,
+        name: resolveTileflowRuntimeTheme(input.manifestMap, selection, input.colorScheme).name,
       };
     } catch {
       return {error: true, name: undefined};
     }
   }
 
+  function resolveBlendStyles(input: {
+    isImageMode: boolean;
+    key: string | undefined;
+    manifestMap: TileflowRuntimeManifestMap | null;
+    source: TileflowMapProps['source'];
+  }): TileflowRuntimeStyle[] | null {
+    if (input.isImageMode || !input.manifestMap || !input.key) return null;
+    try {
+      return resolveTileflowRuntimeThemeBlend({
+        blend: {position: 0, themes: JSON.parse(input.key) as string[]},
+        manifestMap: input.manifestMap,
+        source: input.source,
+      });
+    } catch {
+      return null;
+    }
+  }
+
   function resolveRuntimeResolutionState(input: {
     currentManifestResolutionState: 'error' | 'loading' | 'ready';
     imageSize: {height: number; width: number} | null;

package/src/index.d.ts

@@ -1,6 +1,10 @@
 import type {Map as MapLibreMap, MapOptions as MapLibreMapOptions} from 'maplibre-gl';
 import type {Snippet, SvelteComponentTyped} from 'svelte';
-import type {TileflowThemeTransition} from '@tileflow/core/browser';
+import type {
+  TileflowBrowserThemeBlendSelection,
+  TileflowThemeTransition,
+  TileflowThemeTransitionOptions,
+} from '@tileflow/core/browser';
 import type {
   TileflowAnalytics,
   TileflowRuntimeSource,
@@ -45,6 +49,14 @@ type TileflowMapBaseProps = {
   mapOptions?: TileflowMapOptions;
   onThemeChange?: (transition: TileflowThemeTransition) => void;
   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;
   zoom?: number;
 };
 

package/src/style-source.d.ts

@@ -1,6 +1,8 @@
 type TileflowMapStyleInput = {
   source?: unknown;
   theme?: unknown;
+  themeBlend?: unknown;
+  themeTransition?: unknown;
 };
 
 type TileflowMapStyleInputValidation =

package/src/style-source.js

@@ -1,9 +1,13 @@
+import {validateTileflowBrowserThemeBlendSelection} from '@tileflow/core/browser';
 import {
   validateTileflowRuntimeSource,
   validateTileflowThemeSelection,
 } from '@tileflow/core/runtime';
 
-/** @typedef {{source?: unknown, theme?: unknown}} TileflowMapStyleInput */
+/**
+ * @typedef {{source?: unknown, theme?: unknown, themeBlend?: unknown, themeTransition?: unknown}}
+ *   TileflowMapStyleInput
+ */
 /** @typedef {{ok: true} | {error: string; ok: false}} TileflowMapStyleInputValidation */
 
 /**
@@ -16,9 +20,38 @@ export function validateTileflowMapStyleInputs(input) {
   if (input.theme !== undefined && !validateTileflowThemeSelection(input.theme)) {
     return {error: 'theme must be a concrete portable theme name or "system"', ok: false};
   }
+  if (
+    input.themeBlend !== undefined &&
+    !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 !== undefined && !isThemeTransition(input.themeTransition)) {
+    return {
+      error: 'themeTransition.duration must be a number of milliseconds from 0 to 5000',
+      ok: false,
+    };
+  }
   return {ok: true};
 }
 
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isThemeTransition(value) {
+  if (!value || typeof value !== 'object') return false;
+  const {duration} = /** @type {{duration?: unknown}} */ (value);
+  return (
+    duration === undefined ||
+    (typeof duration === 'number' && Number.isFinite(duration) && duration >= 0 && duration <= 5000)
+  );
+}
+
 /** @param {TileflowMapStyleInput} input */
 export function assertTileflowMapStyleInputs(input) {
   const validation = validateTileflowMapStyleInputs(input);