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

package/README.md

@@ -16,6 +16,12 @@ npm install @tileflow/svelte@alpha @tileflow/core@alpha @tileflow/maps@alpha "ma
 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:
@@ -94,7 +100,7 @@ Add `timeOfDay="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 `timeOfDay` changes cross-fade over 450 ms by default, respecting reduced motion.
 `themeTransition={{duration: 700}}` customizes the duration; use `duration: 0` for an immediate change.
@@ -193,6 +199,26 @@ snippets reconciles existing runtimes rather than recreating MapLibre.
 Text/field descriptors render as text. A `view` names an application snippet; it is not serialized
 HTML. Keep tooltips non-interactive and put buttons, links, and forms in popups.
 
+## 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 `onInteractionEvent`.
+
+<!-- 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'}),
+};
+```
+
+Pass plain data: `$state` proxies cannot reach MapLibre's worker, so use `$state.raw`. 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"` displays an explicit `imageUrl` or derives an image URL from the selected manifest

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/svelte",
-  "version": "0.1.0-alpha.34",
+  "version": "0.1.0-alpha.36",
   "license": "Apache-2.0",
   "description": "Svelte component for rendering Tileflow maps with MapLibre.",
   "type": "module",
@@ -44,15 +44,15 @@
     "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",
     "svelte": ">=5 <6"
   },
   "devDependencies": {
-    "maplibre-gl": "6.13.0",
+    "maplibre-gl": "6.16.0",
     "svelte": "^5.57.2",
     "svelte-check": "^4.7.7"
   },

package/src/TileflowMap.svelte

@@ -42,6 +42,7 @@
     type TileflowMap3DAttachment,
     createTileflowTransformRequest,
     getTileflowSystemColorScheme,
+    loadTileflowRuntimeStyle,
     loadTileflowStyleFonts,
     registerTileflowContourProtocol,
     registerTileflowPathGroundProtocol,
@@ -70,9 +71,11 @@
     type TileflowInteractionViewContext,
   } from '@tileflow/interactions';
   import {
+    createTileflowMapLibreDataRuntime,
     createTileflowMapLibreDomRuntime,
     createTileflowMapLibreInteractionCoordinator,
     createTileflowMapLibreSemanticDomRuntime,
+    type TileflowMapLibreDataRuntime,
     type TileflowMapLibreDomRenderTarget,
     type TileflowMapLibreDomRuntime,
     type TileflowMapLibreInteractionCoordinator,
@@ -86,7 +89,10 @@
 
   export let alt: NonNullable<TileflowMapProps['alt']> = '';
   export let analytics: TileflowMapProps['analytics'] = undefined;
+  export let annotationClusters: TileflowMapProps['annotationClusters'] = undefined;
   export let annotations: TileflowMapProps['annotations'] = undefined;
+  export let dataOverlays: TileflowMapProps['dataOverlays'] = undefined;
+  export let dataSources: TileflowMapProps['dataSources'] = undefined;
 
   export let center: TileflowMapProps['center'] = undefined;
   export let captureId: TileflowMapProps['captureId'] = undefined;
@@ -125,6 +131,7 @@
   let mapFairUseNotice: TileflowFairUseNoticeController | null = null;
   let mapLifecycleAttachment: TileflowMapLifecycleAttachment | null = null;
   let annotationRuntime: TileflowMapLibreDomRuntime<TileflowAnnotation> | null = null;
+  let dataRuntime: TileflowMapLibreDataRuntime<TileflowAnnotation> | null = null;
   let annotationRuntimeDiagnosticsUnsubscribe: (() => void) | null = null;
   let annotationRuntimeEventsUnsubscribe: (() => void) | null = null;
   let annotationRuntimeTargetsUnsubscribe: (() => void) | null = null;
@@ -166,6 +173,7 @@
   let manifestResolutionKey = '';
   let manifestResolutionState: 'error' | 'loading' | 'ready' = 'loading';
   let mapLoadId = 0;
+  let resourceLifetime: AbortController | undefined;
   let mounted = false;
   let refreshRunId = 0;
   let readinessRunId = 0;
@@ -264,7 +272,10 @@
     defaultInteractionState,
   );
   $: hasInteractionConfiguration =
+    annotationClusters !== undefined ||
     annotations !== undefined ||
+    dataOverlays !== undefined ||
+    dataSources !== undefined ||
     interactions !== undefined ||
     interactionState !== undefined ||
     defaultInteractionState !== undefined ||
@@ -350,6 +361,14 @@
     syncAnnotations();
   }
 
+  $: if (mounted) {
+    annotationClusters;
+    annotationResolution;
+    dataOverlays;
+    dataSources;
+    syncDataLayers();
+  }
+
   $: if (mounted) {
     interactions;
     syncSemanticInteractions();
@@ -451,9 +470,13 @@
 
   function destroyMap() {
     mapLoadId += 1;
+    resourceLifetime?.abort();
+    resourceLifetime = undefined;
     readinessRunId += 1;
     const lifecycleAttachment = mapLifecycleAttachment;
     const fairUseNotice = mapFairUseNotice;
+    dataRuntime?.dispose();
+    dataRuntime = null;
     const annotationInteractionsForMap = annotationRuntime;
     const semanticInteractionsForMap = semanticRuntime;
     const detachAnnotationCoordinator = annotationRuntimeCoordinatorDetach;
@@ -552,15 +575,36 @@
     const loadId = mapLoadId;
     const targetContainer = container;
     const runtime = runtimeStyle;
+    const session = createTileflowSessionController({source: 'svelte'});
+    const lifetime = new AbortController();
+    resourceLifetime = lifetime;
+    const resourceTransform = createTileflowTransformRequest({
+      getAnalytics: () => resolvedAnalytics,
+      sessionController: session,
+      sessionId: session.sessionId,
+      transformRequest: mapOptions?.transformRequest ?? undefined,
+    });
+    const styleLoadOptions = {
+      signal: lifetime.signal,
+      transformRequest: (url: string, type: 'Style' | 'Source') =>
+        resourceTransform(
+          url,
+          type as Parameters<NonNullable<TileflowMapOptions['transformRequest']>>[1],
+        ),
+    };
     let maplibregl: Awaited<ReturnType<typeof loadTileflowMapLibre>>;
-
+    let prepared: Awaited<ReturnType<typeof loadTileflowRuntimeStyle>>;
     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 (mounted && runId === refreshRunId && loadId === mapLoadId) {
+        lifetime.abort();
         console.error('Failed to load the Tileflow map runtime', error);
         mapCaptureState = 'error';
       }
@@ -577,7 +621,6 @@
       return;
     }
 
-    const session = createTileflowSessionController({source: 'svelte'});
     const sessionStarter = createTileflowSessionStarter({
       getSessionId: () => session.sessionId,
       sessionId: session.sessionId,
@@ -603,7 +646,7 @@
       container: targetContainer,
       interactive: resolvedInteractive,
       pitch: resolvedPitch,
-      style: runtime.style as StyleSpecification | string,
+      style: prepared.style as StyleSpecification,
       transformRequest: createTileflowTransformRequest({
         getAnalytics: () => resolvedAnalytics,
         sessionController: session,
@@ -625,7 +668,9 @@
       runtime.theme === undefined
         ? null
         : createTileflowThemeController({
-            initial: runtime,
+            initial: prepared.family ? prepared : runtime,
+            initialStyle: prepared.style,
+            styleLoadOptions,
             map: maplibreMap,
             onTransition(transition) {
               onThemeChange?.(transition);
@@ -712,6 +757,22 @@
       annotationRuntimeDiagnostics = annotationInteractionsForMap.getDiagnostics();
       syncAnnotationRenderTargets(annotationInteractionsForMap.getRenderTargets());
       syncAnnotations();
+      // Created ahead of semantic POIs: a click on a cluster belongs to the cluster.
+      dataRuntime = createTileflowMapLibreDataRuntime<
+        MapLibreMap,
+        MapLibreMarker,
+        TileflowAnnotation
+      >({
+        createMarker: ({element}) => new maplibregl.Marker({element}),
+        document: targetContainer.ownerDocument,
+        map: maplibreMap,
+        onDiagnostic: (diagnostic) => onInteractionDiagnostic?.(diagnostic),
+        onInteractionEvent(event) {
+          if (!interactionRuntimesDisposing) onInteractionEvent?.(event);
+        },
+        setHiddenAnnotations: annotationInteractionsForMap.setHiddenAnnotations,
+      });
+      syncDataLayers();
     } catch (error) {
       console.error('Failed to initialize Tileflow annotations', error);
       setBridgeInteractionDiagnostic(
@@ -898,6 +959,15 @@
     }
   }
 
+  function syncDataLayers() {
+    dataRuntime?.reconcile({
+      annotationClusters,
+      annotations: annotationResolution.ok && !isImageMode ? annotationResolution.annotations : [],
+      dataOverlays,
+      dataSources,
+    });
+  }
+
   function syncSemanticInteractions() {
     const bindings =
       interactionBindingResolution.ok && !isImageMode ? interactionBindingResolution.bindings : [];

package/src/index.d.ts

@@ -1,4 +1,6 @@
+import type {TileflowGeoJsonSource, TileflowMapLibreOverlay} from '@tileflow/core';
 import type {TileflowTimeOfDay} from '@tileflow/core/runtime';
+import type {TileflowAnnotationClusterOptions} from '@tileflow/interactions/maplibre';
 import type {Map as MapLibreMap, MapOptions as MapLibreMapOptions} from 'maplibre-gl';
 import type {Snippet, SvelteComponentTyped} from 'svelte';
 import type {
@@ -68,9 +70,18 @@ type TileflowMapBaseProps = {
 export type TileflowMapAnnotationProps<
   TAnnotation extends TileflowAnnotation = TileflowAnnotation,
 > = {
+  /** Group `annotations` into accessible cluster buttons. Up to 1,000 annotations. */
+  annotationClusters?: TileflowAnnotationClusterOptions;
   annotations?: readonly TAnnotation[];
 };
 
+export type TileflowMapDataProps = {
+  /** 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>>;
+};
+
 export type TileflowMapInteractionStateProps =
   | {
       defaultInteractionState?: TileflowInteractionState;
@@ -87,6 +98,7 @@ type TileflowMapStyleSourceProps = {
 
 type TileflowMapInteractiveProps<TAnnotation extends TileflowAnnotation> =
   TileflowMapAnnotationProps<TAnnotation> &
+    TileflowMapDataProps &
     TileflowMapInteractionStateProps & {
       interactions?: readonly TileflowInteractionBinding[];
       marker?: TileflowMapAnnotationSnippet<TAnnotation>;
@@ -99,7 +111,10 @@ type TileflowMapInteractiveProps<TAnnotation extends TileflowAnnotation> =
     };
 
 type TileflowMapImageProps = {
+  annotationClusters?: never;
   annotations?: never;
+  dataOverlays?: never;
+  dataSources?: never;
   defaultInteractionState?: never;
   interactions?: never;
   interactionState?: never;