@tileflow/dom 0.1.0-alpha.3 → 0.1.0-alpha.4

package/REFERENCE.md

@@ -30,6 +30,7 @@ Every option except `source` is optional and can change after mount through `upd
 | `views`                                          | `{marker?, popup?, tooltip?}` renderers that fill a plain element.                                        |
 | `renderTargets`                                  | `{marker?, popup?, tooltip?, onChange}` for a framework that draws views itself; replaces `views`.        |
 | `onLoad`, `onError`, `onThemeChange`             | The loaded MapLibre map; `{code, error}` failures (`console.error` without a handler); theme transitions. |
+| `onSceneLoad`                                    | The map's 3D scene, once its style declares buildings, trees or street lights and the scene has mounted.  |
 | `onInteractionEvent`, `onInteractionStateChange` | Pointer and popup events; requested popup state.                                                          |
 | `onInteractionDiagnostic`                        | Each distinct interaction diagnostic, once.                                                               |
 | `onStatusChange`                                 | Every change to the status `getStatus` returns.                                                           |
@@ -70,9 +71,16 @@ with no renderer keeps the default view.
 | `setInteractionState(state)`                             | Opens or closes a popup; on a controlled map the same as passing `interactionState`.                                                               |
 | `getStatus()`                                            | `{readiness, theme, diagnostics, imageUrl}`: `loading`, `idle` or `error`, the theme shown, interaction diagnostics and, in image mode, the image. |
 | `getMap()`, `getThemeController()`                       | The MapLibre map and theme controller, `null` until the map exists and after it is taken down.                                                     |
+| `getScene()`                                             | The mounted 3D scene (`TileflowMap3D`): `null` until the style declares one and it mounts, and after the map is taken down.                        |
 | `getInteractionState()`, `getRenderTargets()`            | The open popup; the view elements the map handed out.                                                                                              |
 | `destroy()`                                              | Takes the map down, removes the capture attributes and stops every listener. Later calls do nothing.                                               |
 
+The 3D scene loads only for a style that declares one, after the map. `viewMode` shows or hides it
+at once; `getScene()` or the scene passed to `onSceneLoad` gives its own controls, such as a rise
+or descent with a transition (`show` and `hide`), what it still waits for (`pending()`), and its
+buildings, trees and street lights. The style's `camera` policy sets its pitch cap and adaptive
+perspective.
+
 Use `getMap()` or the map passed to `onLoad` for application-owned MapLibre sources, layers,
 controls and events. Tileflow owns the style; theme changes may replace it, so reinstall your
 own layers on `style.load`, or use `dataSources` and `dataOverlays`. Calling the MapLibre map's

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as maplibre_gl from 'maplibre-gl';
 import { Map, MapOptions } from 'maplibre-gl';
 import { TileflowMapLibreOverlay, TileflowGeoJsonSource } from '@tileflow/core';
-import { TileflowThemeController, TileflowBounds, TileflowFitBoundsOptions, TileflowColorOverrides, TileflowEmphasis, TileflowBrowserThemeBlendSelection, TileflowThemeTransitionOptions, TileflowViewMode, TileflowNavigationControlInput, TileflowMapError, TileflowThemeTransition } from '@tileflow/core/browser';
+import { TileflowMap3D, TileflowThemeController, TileflowBounds, TileflowFitBoundsOptions, TileflowColorOverrides, TileflowEmphasis, TileflowBrowserThemeBlendSelection, TileflowThemeTransitionOptions, TileflowViewMode, TileflowNavigationControlInput, TileflowMapError, TileflowThemeTransition } from '@tileflow/core/browser';
 import { TileflowThemeSelection, TileflowRuntimeSource, TileflowTimeOfDay, TileflowAnalytics } from '@tileflow/core/runtime';
 import { TileflowAnnotation, TileflowAnnotationViewContext, TileflowInteractionViewContext, TileflowInteractionState, TileflowInteractionDiagnostic, TileflowInteractionBinding, TileflowInteractionEvent } from '@tileflow/interactions';
 import { TileflowMapLibreDomRenderTarget, TileflowMapLibreSemanticDomRenderTarget, TileflowAnnotationClusterOptions } from '@tileflow/interactions/maplibre';
@@ -119,6 +119,11 @@ type TileflowMapControllerOptions<TAnnotation extends TileflowAnnotation = Tilef
     renderTargets?: TileflowMapRenderTargetsOptions<TAnnotation>;
     onError?: (event: TileflowMapError) => void;
     onLoad?: (map: Map) => void;
+    /**
+     * Receives the map's 3D scene once its style declares buildings, trees or street lights and the
+     * renderers have mounted it. A style without 3D never mounts one.
+     */
+    onSceneLoad?: (scene: TileflowMap3D) => void;
     onThemeChange?: (transition: TileflowThemeTransition) => void;
     onInteractionDiagnostic?: (diagnostic: TileflowInteractionDiagnostic) => void;
     onInteractionEvent?: (event: TileflowInteractionEvent<TAnnotation>) => void;
@@ -150,6 +155,11 @@ type TileflowMapController<TAnnotation extends TileflowAnnotation = TileflowAnno
     /** The MapLibre map, or `null` before it is created and after it is taken down. */
     getMap(): Map | null;
     getRenderTargets(): TileflowMapRenderTargetList<TAnnotation>;
+    /**
+     * The map's mounted 3D scene, for its buildings, trees and street lights: `null` until the
+     * style declares one and its renderers have loaded, and after the map is taken down.
+     */
+    getScene(): TileflowMap3D | null;
     getStatus(): TileflowMapStatus;
     /** Changes theme, colours and emphasis; `null` until the map exists or when it has no themes. */
     getThemeController(): TileflowThemeController | null;

package/dist/index.js

@@ -1484,6 +1484,9 @@ function createTileflowMap(container, initialOptions, createOptions = {}) {
       onError: (error) => {
         if (scene === mapScene) reportError("scene", error);
       },
+      onLoad: (mountedScene) => {
+        if (scene === mapScene) options.onSceneLoad?.(mountedScene);
+      },
       // Direct tile readers use HTTP, not MapLibre's custom World protocol.
       transformRequest: createTileflowTransformRequest({
         getAnalytics: () => current.resolvedAnalytics,
@@ -1821,6 +1824,7 @@ function createTileflowMap(container, initialOptions, createOptions = {}) {
     getInteractionState: () => interactionCoordinator?.getInteractionState() ?? coordinatedInteractionState,
     getMap: () => map,
     getRenderTargets: () => lastRenderTargets,
+    getScene: () => map ? scene?.scene ?? null : null,
     getStatus: () => lastStatus ?? computeStatus(),
     getThemeController: () => map ? themeController ?? null : null,
     ready,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/dom",
-  "version": "0.1.0-alpha.3",
+  "version": "0.1.0-alpha.4",
   "license": "Apache-2.0",
   "description": "Mount a Tileflow map in any DOM element, without a framework.",
   "type": "module",
@@ -40,7 +40,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@tileflow/core": ">=0.1.0-alpha.53 <0.1.0-beta.0",
+    "@tileflow/core": ">=0.1.0-alpha.54 <0.1.0-beta.0",
     "@tileflow/interactions": ">=0.1.0-alpha.11 <0.1.0-beta.0"
   },
   "peerDependencies": {