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

package/README.md

@@ -90,12 +90,25 @@ 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.
 
+Add `timeOfDay="dusk"` beside `theme` to select a map's optional `day`, `dawn`, `dusk`, or
+`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).
+
 `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).
 
+Interactive maps automatically render the map's vegetation. `vegetation` overrides visibility
+(omitting it uses the map default); false hides models and flat artwork alike. `viewMode` is `2d`
+by default and may be `3d`: only maps with `vegetation.mode: 'auto'` switch representation.
+Streets uses model trees in either view. Changing either prop updates the existing map immediately.
+These props do not change camera pitch, buildings or lighting and do not apply in image mode. See
+[vegetation controls](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/trees-3d.md#visibility-and-representation).
+
 `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.27",
+  "version": "0.1.0-alpha.29",
   "license": "Apache-2.0",
   "description": "Svelte component for rendering Tileflow maps with MapLibre.",
   "type": "module",
@@ -44,16 +44,16 @@
     "access": "public"
   },
   "dependencies": {
-    "@tileflow/core": ">=0.1.0-alpha.30 <0.1.0-beta.0",
-    "@tileflow/interactions": ">=0.1.0-alpha.4 <0.1.0-beta.0"
+    "@tileflow/core": ">=0.1.0-alpha.35 <0.1.0-beta.0",
+    "@tileflow/interactions": ">=0.1.0-alpha.5 <0.1.0-beta.0"
   },
   "peerDependencies": {
     "maplibre-gl": ">=6.4.1 <7",
     "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

@@ -34,6 +34,8 @@
     attachTileflowMapLifecycle,
     createTileflowSessionStarter,
     createTileflowThemeController,
+    createTileflowVegetation,
+    type TileflowVegetationController,
     createTileflowTransformRequest,
     getTileflowSystemColorScheme,
     loadTileflowStyleFonts,
@@ -71,7 +73,7 @@
     type TileflowMapLibreSemanticDomRenderTarget,
     type TileflowMapLibreSemanticDomRuntime,
   } from '@tileflow/interactions/maplibre';
-  import type {TileflowMapProps} from './index.js';
+  import type {TileflowMapOptions, TileflowMapProps} from './index.js';
   import {loadTileflowMapLibre} from './maplibre.js';
   import {assertTileflowMapStyleInputs} from './style-source.js';
 
@@ -99,7 +101,10 @@
   export let popup: TileflowMapProps['popup'] = undefined;
   export let source: TileflowMapProps['source'];
   export let theme: TileflowMapProps['theme'] = undefined;
+  export let timeOfDay: TileflowMapProps['timeOfDay'] = undefined;
   export let themeBlend: TileflowMapProps['themeBlend'] = undefined;
+  export let vegetation: TileflowMapProps['vegetation'] = undefined;
+  export let viewMode: NonNullable<TileflowMapProps['viewMode']> = '2d';
   export let themeTransition: TileflowMapProps['themeTransition'] = undefined;
   export let tooltip: TileflowMapProps['tooltip'] = undefined;
   export let zoom: TileflowMapProps['zoom'] = undefined;
@@ -142,6 +147,9 @@
   let interactionRuntimesDisposing = false;
   let mapResizeObserver: ResizeObserver | null = null;
   let mapWorldRequestBridge: TileflowWorldRequestBridge | null = null;
+  let vegetationController: TileflowVegetationController | null = null;
+  $: vegetationController?.setVisible(vegetation);
+  $: vegetationController?.setViewMode(viewMode);
   let themeController: TileflowThemeController | null = null;
   let systemColorScheme: 'dark' | 'light' = 'light';
   let unsubscribeSystemColorScheme: (() => void) | null = null;
@@ -172,7 +180,7 @@
         : {defaultInteractionState: initialInteractionState}),
     });
   $: resolvedMode = resolveTileflowMapMode({mode});
-  $: assertTileflowMapStyleInputs({source, theme, themeBlend, themeTransition});
+  $: assertTileflowMapStyleInputs({source, theme, timeOfDay, themeBlend, themeTransition});
   $: resolvedCaptureId = normalizeTileflowCaptureId(captureId);
   $: isImageMode = resolvedMode === 'image';
   $: mapName = source.map;
@@ -188,10 +196,12 @@
     colorScheme: systemColorScheme,
     manifestMap,
     theme,
+    timeOfDay,
     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);
@@ -307,6 +317,7 @@
   $: if (mounted) {
     blendStyles;
     themeBlendPosition;
+    themeBlendHold;
     void switchBlend();
   }
 
@@ -448,6 +459,8 @@
     const unsubscribeSemanticTargets = semanticRuntimeTargetsUnsubscribe;
     const currentMap = mapInstance;
     const currentThemeController = themeController;
+    const currentVegetationController = vegetationController;
+    vegetationController = null;
     const worldRequestBridge = mapWorldRequestBridge;
     interactionRuntimesDisposing = true;
     mapFairUseNotice = null;
@@ -490,6 +503,7 @@
       () => semanticInteractionsForMap?.dispose(),
       () => annotationInteractionsForMap?.dispose(),
       () => lifecycleAttachment?.dispose(),
+      () => currentVegetationController?.dispose(),
       () => currentThemeController?.dispose(),
       () => worldRequestBridge?.dispose(),
       () => fairUseNotice?.dispose(),
@@ -579,8 +593,6 @@
       pitch: resolvedPitch,
       style: runtime.style as StyleSpecification | string,
       transformRequest: createTileflowTransformRequest({
-        always: true,
-        asyncAnalyticsTiming: 'request',
         getAnalytics: () => resolvedAnalytics,
         sessionController: session,
         sessionId: session.sessionId,
@@ -610,6 +622,23 @@
             },
           });
 
+    vegetationController = createTileflowVegetation({
+      map: maplibreMap,
+      ...(themeController ? {controller: themeController} : {}),
+      visible: vegetation,
+      viewMode,
+      transformRequest: createTileflowTransformRequest({
+        getAnalytics: () => resolvedAnalytics,
+        sessionController: session,
+        sessionId: session.sessionId,
+        transformRequest: (url) =>
+          mapOptions?.transformRequest?.(
+            url,
+            'Tile' as Parameters<NonNullable<TileflowMapOptions['transformRequest']>>[1],
+          ),
+      }),
+    });
+
     setBridgeInteractionDiagnostic('annotation-runtime', null);
     try {
       const annotationInteractionsForMap = createTileflowMapLibreDomRuntime<
@@ -784,7 +813,7 @@
     if (!themeController || !blendStyles || position === undefined) return;
     if (runtimeStyle) activeRuntimeResource = runtimeStyle;
     const result = await themeController.setBlend(
-      {position, themes: blendStyles},
+      {hold: themeBlendHold, position, themes: blendStyles},
       {transition: themeTransition},
     );
     if (result.status === 'failed') {
@@ -1035,11 +1064,7 @@
   }
 
   type BridgeInteractionDiagnosticSource =
-    | 'annotation-runtime'
-    | 'portal'
-    | 'renderers'
-    | 'semantic-runtime'
-    | 'state';
+    'annotation-runtime' | 'portal' | 'renderers' | 'semantic-runtime' | 'state';
 
   function setBridgeInteractionDiagnostic(
     source: BridgeInteractionDiagnosticSource,
@@ -1242,6 +1267,7 @@
     colorScheme: 'dark' | 'light';
     manifestMap: TileflowRuntimeManifestMap | null;
     theme: TileflowMapProps['theme'];
+    timeOfDay: TileflowMapProps['timeOfDay'];
     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.
@@ -1259,7 +1285,12 @@
       }
       return {
         error: false,
-        name: resolveTileflowRuntimeTheme(input.manifestMap, selection, input.colorScheme).name,
+        name: resolveTileflowRuntimeTheme(
+          input.manifestMap,
+          selection,
+          input.colorScheme,
+          input.themeBlend ? undefined : input.timeOfDay,
+        ).name,
       };
     } catch {
       return {error: true, name: undefined};

package/src/index.d.ts

@@ -1,10 +1,15 @@
+import type {TileflowTimeOfDay} from '@tileflow/core/runtime';
 import type {Map as MapLibreMap, MapOptions as MapLibreMapOptions} from 'maplibre-gl';
 import type {Snippet, SvelteComponentTyped} from 'svelte';
-import type {TileflowThemeTransition, TileflowThemeTransitionOptions} from '@tileflow/core/browser';
+import type {
+  TileflowBrowserThemeBlendSelection,
+  TileflowThemeTransition,
+  TileflowViewMode,
+  TileflowThemeTransitionOptions,
+} from '@tileflow/core/browser';
 import type {
   TileflowAnalytics,
   TileflowRuntimeSource,
-  TileflowThemeBlendSelection,
   TileflowThemeSelection,
 } from '@tileflow/core/runtime';
 import type {
@@ -34,6 +39,8 @@ export type TileflowMapInteractionSnippet<
 > = Snippet<[context: TileflowInteractionViewContext<TAnnotation>]>;
 
 type TileflowMapBaseProps = {
+  vegetation?: boolean;
+  viewMode?: TileflowViewMode;
   alt?: string;
   analytics?: TileflowAnalytics;
   center?: [number, number];
@@ -46,11 +53,13 @@ type TileflowMapBaseProps = {
   mapOptions?: TileflowMapOptions;
   onThemeChange?: (transition: TileflowThemeTransition) => void;
   theme?: TileflowThemeSelection;
+  timeOfDay?: TileflowTimeOfDay;
   /**
    * 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.
+   * 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?: TileflowThemeBlendSelection;
+  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,7 @@
 type TileflowMapStyleInput = {
   source?: unknown;
   theme?: unknown;
+  timeOfDay?: unknown;
   themeBlend?: unknown;
   themeTransition?: unknown;
 };

package/src/style-source.js

@@ -1,11 +1,12 @@
+import {validateTileflowBrowserThemeBlendSelection} from '@tileflow/core/browser';
 import {
+  isTileflowTimeOfDay,
   validateTileflowRuntimeSource,
-  validateTileflowThemeBlendSelection,
   validateTileflowThemeSelection,
 } from '@tileflow/core/runtime';
 
 /**
- * @typedef {{source?: unknown, theme?: unknown, themeBlend?: unknown, themeTransition?: unknown}}
+ * @typedef {{source?: unknown, theme?: unknown, timeOfDay?: unknown, themeBlend?: unknown, themeTransition?: unknown}}
  *   TileflowMapStyleInput
  */
 /** @typedef {{ok: true} | {error: string; ok: false}} TileflowMapStyleInputValidation */
@@ -20,10 +21,16 @@ 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 && !validateTileflowThemeBlendSelection(input.themeBlend)) {
+  if (input.timeOfDay !== undefined && !isTileflowTimeOfDay(input.timeOfDay)) {
+    return {error: 'timeOfDay must be day, dawn, dusk, or night', ok: false};
+  }
+  if (
+    input.themeBlend !== undefined &&
+    !validateTileflowBrowserThemeBlendSelection(input.themeBlend)
+  ) {
     return {
       error:
-        'themeBlend must name two to eight concrete themes and a position from 0 to themes.length - 1',
+        'themeBlend must name two to eight concrete themes, a position from 0 to themes.length - 1, and an optional boolean hold',
       ok: false,
     };
   }