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

package/README.md

@@ -100,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.
@@ -199,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.35",
+  "version": "0.1.0-alpha.36",
   "license": "Apache-2.0",
   "description": "Svelte component for rendering Tileflow maps with MapLibre.",
   "type": "module",
@@ -44,8 +44,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@tileflow/core": ">=0.1.0-alpha.45 <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",

package/src/TileflowMap.svelte

@@ -71,9 +71,11 @@
     type TileflowInteractionViewContext,
   } from '@tileflow/interactions';
   import {
+    createTileflowMapLibreDataRuntime,
     createTileflowMapLibreDomRuntime,
     createTileflowMapLibreInteractionCoordinator,
     createTileflowMapLibreSemanticDomRuntime,
+    type TileflowMapLibreDataRuntime,
     type TileflowMapLibreDomRenderTarget,
     type TileflowMapLibreDomRuntime,
     type TileflowMapLibreInteractionCoordinator,
@@ -87,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;
@@ -126,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;
@@ -266,7 +272,10 @@
     defaultInteractionState,
   );
   $: hasInteractionConfiguration =
+    annotationClusters !== undefined ||
     annotations !== undefined ||
+    dataOverlays !== undefined ||
+    dataSources !== undefined ||
     interactions !== undefined ||
     interactionState !== undefined ||
     defaultInteractionState !== undefined ||
@@ -352,6 +361,14 @@
     syncAnnotations();
   }
 
+  $: if (mounted) {
+    annotationClusters;
+    annotationResolution;
+    dataOverlays;
+    dataSources;
+    syncDataLayers();
+  }
+
   $: if (mounted) {
     interactions;
     syncSemanticInteractions();
@@ -458,6 +475,8 @@
     readinessRunId += 1;
     const lifecycleAttachment = mapLifecycleAttachment;
     const fairUseNotice = mapFairUseNotice;
+    dataRuntime?.dispose();
+    dataRuntime = null;
     const annotationInteractionsForMap = annotationRuntime;
     const semanticInteractionsForMap = semanticRuntime;
     const detachAnnotationCoordinator = annotationRuntimeCoordinatorDetach;
@@ -738,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(
@@ -924,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;