@tileflow/vue 0.1.0-alpha.34 → 0.1.0-alpha.36

package/README.md

@@ -16,6 +16,12 @@ npm install @tileflow/vue@alpha @tileflow/core@alpha @tileflow/maps@alpha "mapli
 npm install --save-dev --save-exact tileflow@alpha
 ```
 
+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:
@@ -92,7 +98,7 @@ Add `time-of-day="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 `time-of-day` changes cross-fade over 450 ms by default, respecting reduced motion.
 `:theme-transition="{duration: 700}"` customizes the duration; use `duration: 0` for an immediate change.
@@ -185,6 +191,26 @@ reconcile without recreating MapLibre. Text/field descriptors render as text; `v
 an application slot and never evaluates HTML. Tooltips must remain non-interactive; use a popup for
 links, buttons, or forms.
 
+## 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 `@interaction-event`.
+
+<!-- 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 existing image
 
 `mode="image"` renders an explicit `imageUrl` or derives an image URL from the selected manifest

package/dist/index.d.ts

@@ -1,8 +1,10 @@
 import { MapOptions, Map } from 'maplibre-gl';
 import { DefineComponent, VNodeChild } from 'vue';
+import { TileflowMapLibreOverlay, TileflowGeoJsonSource } from '@tileflow/core';
 import { TileflowBrowserThemeBlendSelection, TileflowThemeTransitionOptions, TileflowViewMode, TileflowThemeTransition } from '@tileflow/core/browser';
 import { TileflowRuntimeSource, TileflowThemeSelection, TileflowTimeOfDay, TileflowAnalytics } from '@tileflow/core/runtime';
 import { TileflowAnnotation, TileflowInteractionJsonValue, TileflowInteractionState, TileflowInteractionBinding, TileflowInteractionDiagnostic, TileflowInteractionEvent, TileflowAnnotationViewContext, TileflowInteractionViewContext } from '@tileflow/interactions';
+import { TileflowAnnotationClusterOptions } from '@tileflow/interactions/maplibre';
 
 type TileflowMapStyleSourceProps = {
     source: TileflowRuntimeSource;
@@ -57,13 +59,22 @@ type TileflowMapStateInput = {
     interactionState?: never;
 };
 type TileflowMapInteractiveProps<TAnnotation extends TileflowAnnotation> = TileflowMapSharedProps & TileflowMapStateInput & {
+    /** 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>>;
     interactions?: readonly TileflowInteractionBinding[];
     interactive?: boolean;
     mode?: 'interactive';
 };
 type TileflowMapImageProps = TileflowMapSharedProps & {
+    annotationClusters?: never;
     annotations?: never;
+    dataOverlays?: never;
+    dataSources?: never;
     defaultInteractionState?: never;
     interactionState?: never;
     interactions?: never;
@@ -73,7 +84,10 @@ type TileflowMapImageProps = TileflowMapSharedProps & {
 type TileflowMapProps<TAnnotation extends TileflowAnnotation = TileflowAnnotation> = (TileflowMapInteractiveProps<TAnnotation> | TileflowMapImageProps) & TileflowMapStyleSourceProps;
 type RuntimeTileflowAnnotation = TileflowAnnotation<TileflowInteractionJsonValue>;
 type RuntimeTileflowMapProps = TileflowMapSharedProps & TileflowMapStyleSourceProps & {
+    annotationClusters?: TileflowAnnotationClusterOptions;
     annotations?: readonly RuntimeTileflowAnnotation[];
+    dataOverlays?: Readonly<Record<string, TileflowMapLibreOverlay>>;
+    dataSources?: Readonly<Record<string, TileflowGeoJsonSource>>;
     defaultInteractionState?: TileflowInteractionState;
     interactionState?: TileflowInteractionState;
     interactions?: readonly TileflowInteractionBinding[];

package/dist/index.js

@@ -10,6 +10,7 @@ import {
   ref,
   shallowRef,
   Teleport,
+  toRaw,
   watch,
   watchEffect
 } from "vue";
@@ -26,6 +27,7 @@ import {
   createTileflowThemeController,
   createTileflowTransformRequest,
   getTileflowSystemColorScheme,
+  loadTileflowRuntimeStyle,
   loadTileflowStyleFonts,
   registerTileflowContourProtocol,
   registerTileflowPathGroundProtocol,
@@ -57,6 +59,7 @@ import {
   initialTileflowInteractionState
 } from "@tileflow/interactions";
 import {
+  createTileflowMapLibreDataRuntime,
   createTileflowMapLibreDomRuntime,
   createTileflowMapLibreInteractionCoordinator,
   createTileflowMapLibreSemanticDomRuntime
@@ -221,10 +224,13 @@ var TileflowMap = defineComponent({
       type: String
     },
     analytics: Object,
+    annotationClusters: Object,
     annotations: Array,
     center: Array,
     captureId: String,
     className: String,
+    dataOverlays: Object,
+    dataSources: Object,
     defaultInteractionState: Object,
     height: {
       default: 420,
@@ -283,6 +289,7 @@ var TileflowMap = defineComponent({
     );
     const controlledInteractionOwnership = props.interactionState !== void 0;
     let annotationRuntime = null;
+    let dataRuntime = null;
     let semanticRuntime = null;
     let interactionRuntimesDisposing = false;
     let initializeSemanticRuntime = null;
@@ -307,6 +314,7 @@ var TileflowMap = defineComponent({
     let themeController = null;
     let unsubscribeSystemColorScheme = null;
     let mapLoadId = 0;
+    let resourceLifetime;
     let manifestLoadId = 0;
     let readinessRunId = 0;
     let interactionReadinessRunId = 0;
@@ -341,7 +349,7 @@ var TileflowMap = defineComponent({
       return diagnostics;
     });
     const hasInteractionConfiguration = computed(
-      () => props.annotations !== void 0 || props.interactions !== void 0 || props.interactionState !== void 0 || props.defaultInteractionState !== void 0 || slots.marker !== void 0 || slots.popup !== void 0 || slots.tooltip !== void 0
+      () => props.annotationClusters !== void 0 || props.annotations !== void 0 || props.dataOverlays !== void 0 || props.dataSources !== void 0 || props.interactions !== void 0 || props.interactionState !== void 0 || props.defaultInteractionState !== void 0 || slots.marker !== void 0 || slots.popup !== void 0 || slots.tooltip !== void 0
     );
     const interactionInputDiagnostics = computed(() => {
       const diagnostics = [
@@ -643,6 +651,8 @@ var TileflowMap = defineComponent({
     );
     const destroyMap = () => {
       mapLoadId += 1;
+      resourceLifetime?.abort();
+      resourceLifetime = void 0;
       readinessRunId += 1;
       invalidateInteractionReadiness();
       const lifecycle = mapLifecycle;
@@ -652,6 +662,8 @@ var TileflowMap = defineComponent({
       const controller = themeController;
       const scene = sceneAttachment;
       sceneAttachment = null;
+      dataRuntime?.dispose();
+      dataRuntime = null;
       const annotationInteractionsForMap = annotationRuntime;
       const semanticInteractionsForMap = semanticRuntime;
       const worldRequestBridge = mapWorldRequestBridge;
@@ -724,6 +736,24 @@ var TileflowMap = defineComponent({
         reportOverlayFailure("Unable to reconcile the Tileflow annotation runtime.");
       }
     };
+    const syncDataRuntime = () => {
+      const resolution = annotationResolution.value;
+      if (!dataRuntime) return;
+      try {
+        dataRuntime.reconcile({
+          annotationClusters: props.annotationClusters,
+          annotations: resolution.ok && !isImageMode.value ? resolution.annotations : [],
+          dataOverlays: props.dataOverlays,
+          dataSources: props.dataSources && Object.fromEntries(
+            Object.entries(toRaw(props.dataSources)).map(
+              ([id, source]) => [id, { ...toRaw(source), data: toRaw(source.data) }]
+            )
+          )
+        });
+      } catch {
+        reportOverlayFailure("Unable to reconcile the Tileflow data layers.");
+      }
+    };
     const syncSemanticRuntime = () => {
       const resolution = interactionBindingResolution.value;
       const bindings = resolution.ok && !isImageMode.value ? resolution.bindings : [];
@@ -767,16 +797,35 @@ var TileflowMap = defineComponent({
       const loadId = mapLoadId;
       const container = containerRef.value;
       const runtime = runtimeStyle.value;
+      const session = createTileflowSessionController({ source: "vue" });
+      const lifetime = new AbortController();
+      resourceLifetime = lifetime;
+      const resourceTransform = createTileflowTransformRequest({
+        getAnalytics: () => resolvedAnalytics.value,
+        sessionController: session,
+        sessionId: session.sessionId,
+        transformRequest: props.mapOptions?.transformRequest ?? void 0
+      });
+      const styleLoadOptions = {
+        signal: lifetime.signal,
+        transformRequest: (url, type) => resourceTransform(
+          url,
+          type
+        )
+      };
       let maplibregl;
+      let prepared;
       try {
-        [maplibregl] = await Promise.all([
+        [maplibregl, prepared] = await Promise.all([
           loadTileflowMapLibre(),
-          loadTileflowStyleFonts(runtime.style, {
-            fontFaces: runtime.fontFaces
+          loadTileflowRuntimeStyle(runtime, styleLoadOptions).then(async (loaded) => {
+            await loadTileflowStyleFonts(loaded.style, { fontFaces: loaded.fontFaces });
+            return loaded;
           })
         ]);
       } catch (error) {
         if (loadId === mapLoadId) {
+          lifetime.abort();
           console.error("Failed to load the Tileflow map runtime", error);
           mapCaptureState.value = "error";
         }
@@ -785,7 +834,6 @@ var TileflowMap = defineComponent({
       if (loadId !== mapLoadId || containerRef.value !== container || isImageMode.value) {
         return;
       }
-      const session = createTileflowSessionController({ source: "vue" });
       const sessionStarter = createTileflowSessionStarter({
         getSessionId: () => session.sessionId,
         sessionId: session.sessionId,
@@ -815,7 +863,7 @@ var TileflowMap = defineComponent({
         container,
         interactive: resolvedInteractive.value,
         pitch: resolvedPitch.value,
-        style: runtime.style,
+        style: prepared.style,
         transformRequest: createTileflowTransformRequest({
           getAnalytics: () => resolvedAnalytics.value,
           sessionController: session,
@@ -832,7 +880,9 @@ var TileflowMap = defineComponent({
       attachTileflowLabelPlacement(map);
       attachTileflowHorizonQueries(map);
       themeController = runtime.theme === void 0 ? null : createTileflowThemeController({
-        initial: runtime,
+        initial: prepared.family ? prepared : runtime,
+        initialStyle: prepared.style,
+        styleLoadOptions,
         map,
         onTransition(transition) {
           emit("themeChange", transition);
@@ -907,6 +957,17 @@ var TileflowMap = defineComponent({
         annotationRenderTargets.value = mapInteractions.getRenderTargets();
         syncInteractionRenderTargetReadiness();
         syncAnnotationRuntime();
+        dataRuntime = createTileflowMapLibreDataRuntime({
+          createMarker: ({ element }) => new maplibregl.Marker({ element }),
+          document: container.ownerDocument,
+          map,
+          onDiagnostic: (diagnostic) => emit("interactionDiagnostic", diagnostic),
+          onInteractionEvent(event) {
+            if (!interactionRuntimesDisposing) emit("interactionEvent", event);
+          },
+          setHiddenAnnotations: mapInteractions.setHiddenAnnotations
+        });
+        syncDataRuntime();
       } catch {
         reportOverlayFailure("Unable to initialize the Tileflow annotation runtime.");
       }
@@ -1144,9 +1205,17 @@ var TileflowMap = defineComponent({
     );
     watch(
       () => props.annotations,
-      () => syncAnnotationRuntime(),
+      () => {
+        syncAnnotationRuntime();
+        syncDataRuntime();
+      },
       { deep: true, flush: "post" }
     );
+    watch(
+      () => [props.annotationClusters, props.dataOverlays, props.dataSources],
+      () => syncDataRuntime(),
+      { flush: "post" }
+    );
     watch(
       () => props.interactions,
       () => syncSemanticRuntime(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/vue",
-  "version": "0.1.0-alpha.34",
+  "version": "0.1.0-alpha.36",
   "license": "Apache-2.0",
   "description": "Vue component for rendering Tileflow maps with MapLibre.",
   "type": "module",
@@ -38,8 +38,8 @@
     "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/core": ">=0.1.0-alpha.48 <0.1.0-beta.0",
+    "@tileflow/interactions": ">=0.1.0-alpha.8 <0.1.0-beta.0"
   },
   "peerDependencies": {
     "maplibre-gl": ">=6.4.1 <7",
@@ -47,7 +47,7 @@
   },
   "devDependencies": {
     "@vue/server-renderer": "3.5.43",
-    "maplibre-gl": "6.13.0",
+    "maplibre-gl": "6.16.0",
     "tsx": "^4.23.15",
     "vue": "^3.5.43"
   },