@tileflow/svelte 0.1.0-alpha.14 → 0.1.0-alpha.17

package/README.md

@@ -26,4 +26,17 @@ Tileflow resolves from the map name, manifest, or explicit style props. Direct
 Tileflow props such as `center`, `zoom`, and `interactive` take priority when
 provided.
 
+## Headless capture readiness
+
+Use `captureId` to disambiguate repeated named maps:
+
+```svelte
+<TileflowMap map="madrid" captureId="checkout-map" />
+```
+
+The root exposes `data-tileflow-map`, optional `data-tileflow-capture-id`, and
+`data-tileflow-state="loading|idle|error"`. It becomes idle only after MapLibre idle plus two
+animation frames (or image decode/load in image mode), returns to loading for new style/data work,
+and marks terminal load errors. Application capture selects exactly one ready target.
+
 Docs: https://tileflow.dev/docs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/svelte",
-  "version": "0.1.0-alpha.14",
+  "version": "0.1.0-alpha.17",
   "description": "Svelte component for rendering Tileflow maps with MapLibre.",
   "type": "module",
   "sideEffects": false,
@@ -8,11 +8,11 @@
   "homepage": "https://tileflow.dev",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/tileflow/tileflow.git",
+    "url": "git+https://github.com/tileflow/tileflow-sdk.git",
     "directory": "packages/svelte"
   },
   "bugs": {
-    "url": "https://github.com/tileflow/tileflow/issues"
+    "url": "https://github.com/tileflow/tileflow-sdk/issues"
   },
   "keywords": [
     "tileflow",
@@ -42,7 +42,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@tileflow/core": "0.1.0-alpha.14"
+    "@tileflow/core": ">=0.1.0-alpha.17 <0.1.0-beta.0"
   },
   "peerDependencies": {
     "maplibre-gl": ">=5",
@@ -55,6 +55,8 @@
   },
   "scripts": {
     "build": "svelte-check --tsconfig ./tsconfig.json",
+    "test": "node --test test/*.test.js",
+    "verify": "pnpm run build && pnpm run test",
     "typecheck": "svelte-check --tsconfig ./tsconfig.json",
     "lint": "svelte-check --tsconfig ./tsconfig.json"
   }

package/src/TileflowMap.svelte

@@ -3,24 +3,21 @@
     type LngLatLike,
     type Map as MapLibreMap,
     type MapOptions as MapLibreMapOptions,
-    type RequestParameters,
-    type RequestTransformFunction,
     type StyleSpecification,
   } from 'maplibre-gl';
-  import {createEventDispatcher, onMount} from 'svelte';
+  import {createEventDispatcher, onMount, tick} from 'svelte';
   import {
     createTileflowSessionId,
     defaultTileflowManifestUrl,
     loadTileflowManifest,
     mergeTileflowAnalytics,
+    normalizeTileflowCaptureId,
     normalizeTileflowStaticImageSize,
-    resolveTileflowAnalyticsRequestUrl,
     resolveTileflowManifestMap,
     resolveTileflowMapMode,
     resolveTileflowRuntimeStyle,
     resolveTileflowStaticImageUrl,
     shouldLoadTileflowManifest,
-    startTileflowSession,
     type MapLibreStyle,
     type TileflowAnalytics,
     type TileflowConfig,
@@ -28,6 +25,13 @@
     type TileflowProjectThemes,
     type TileflowRuntimeManifestMap,
   } from '@tileflow/core';
+  import {
+    attachTileflowMapLifecycle,
+    createTileflowMarkerController,
+    createTileflowSessionStarter,
+    createTileflowTransformRequest,
+    type TileflowMapLifecycleAttachment,
+  } from '@tileflow/core/browser';
 
   export let alt = '';
   export let analytics: TileflowAnalytics | undefined = undefined;
@@ -37,6 +41,7 @@
   const defaultZoom = 2;
 
   export let center: [number, number] | undefined = undefined;
+  export let captureId: string | undefined = undefined;
   export let className = '';
   export let config: TileflowConfig | undefined = undefined;
   export let height: number | string = 420;
@@ -57,21 +62,39 @@
   export let zoom: number | undefined = undefined;
 
   let container: HTMLDivElement;
+  let captureState: 'error' | 'idle' | 'loading' = 'loading';
   let imageSize: {height: number; width: number} | null = null;
   let imageResizeObserver: ResizeObserver | null = null;
   let mapInstance: MapLibreMap | null = null;
-  let markerInstances: maplibregl.Marker[] = [];
+  let mapLifecycleAttachment: TileflowMapLifecycleAttachment | null = null;
   let mapResizeObserver: ResizeObserver | null = null;
   let manifestMap: TileflowRuntimeManifestMap | null = null;
   let manifestLoadId = 0;
   let mounted = false;
   let refreshRunId = 0;
+  let readinessRunId = 0;
 
   const dispatch = createEventDispatcher<{load: MapLibreMap}>();
   const sessionId = createTileflowSessionId();
-  const sessionStarts = new Set<string>();
+  const sessionStarter = createTileflowSessionStarter({sessionId, source: 'svelte'});
+  const markerController = createTileflowMarkerController<
+    MapLibreMap,
+    TileflowMapMarker,
+    maplibregl.Marker
+  >({
+    attach(markerInstance, targetMap, definition) {
+      markerInstance.setLngLat(definition.coordinates).addTo(targetMap);
+      markerInstance.getElement().title = definition.label ?? definition.id;
+    },
+    create: (definition) =>
+      new maplibregl.Marker({
+        color: definition.color ?? '#C6A15B',
+      }),
+    remove: (markerInstance) => markerInstance.remove(),
+  });
 
   $: resolvedMode = resolveTileflowMapMode({imageUrl, mode, preferLocalDev});
+  $: resolvedCaptureId = normalizeTileflowCaptureId(captureId);
   $: isImageMode = resolvedMode === 'image';
   $: imageCenter = center ?? defaultCenter;
   $: imageZoom = zoom ?? defaultZoom;
@@ -134,6 +157,11 @@
     syncMarkers();
   }
 
+  $: if (mounted && isImageMode) {
+    runtimeImageUrl;
+    void markImageLoading();
+  }
+
   onMount(() => {
     mounted = true;
 
@@ -214,15 +242,28 @@
   }
 
   function destroyMap() {
+    readinessRunId += 1;
+    const lifecycleAttachment = mapLifecycleAttachment;
+    const currentMap = mapInstance;
+    mapLifecycleAttachment = null;
+    mapInstance = null;
     mapResizeObserver?.disconnect();
     mapResizeObserver = null;
-    clearMarkers();
-    mapInstance?.remove();
-    mapInstance = null;
+
+    try {
+      lifecycleAttachment?.dispose();
+    } finally {
+      try {
+        markerController.dispose();
+      } finally {
+        currentMap?.remove();
+      }
+    }
   }
 
   function recreateMap() {
     destroyMap();
+    captureState = 'loading';
 
     if (!container || !runtimeStyle || isImageMode) {
       return;
@@ -236,11 +277,13 @@
       container,
       interactive: resolvedInteractive,
       style: runtime.style as StyleSpecification | string,
-      transformRequest: createTransformRequest(
-        () => resolvedAnalytics,
+      transformRequest: createTileflowTransformRequest({
+        always: true,
+        asyncAnalyticsTiming: 'request',
+        getAnalytics: () => resolvedAnalytics,
         sessionId,
-        mapOptions?.transformRequest,
-      ),
+        transformRequest: mapOptions?.transformRequest ?? undefined,
+      }),
       zoom: resolvedZoom,
     });
 
@@ -255,25 +298,29 @@
     });
     mapResizeObserver.observe(container);
 
-    maplibreMap.on('load', () => {
-      dispatch('load', maplibreMap);
-      const analyticsForLoad = resolvedAnalytics;
-      const styleId =
-        analyticsForLoad?.styleId ?? (typeof runtime.style === 'string' ? runtime.style : map);
-
-      if (analyticsForLoad?.mapId) {
-        const sessionKey = `${sessionId}:${analyticsForLoad.mapId}:${styleId ?? ''}`;
-
-        if (!sessionStarts.has(sessionKey)) {
-          sessionStarts.add(sessionKey);
-          startTileflowSession(analyticsForLoad, {
-            mapId: analyticsForLoad.mapId,
-            sessionId,
-            source: 'svelte',
-            styleId,
-          });
-        }
-      }
+    mapLifecycleAttachment = attachTileflowMapLifecycle<MapLibreMap, number>({
+      getSession: () => {
+        const analyticsForLoad = resolvedAnalytics;
+        return {
+          analytics: analyticsForLoad,
+          styleId:
+            analyticsForLoad?.styleId ?? (typeof runtime.style === 'string' ? runtime.style : map),
+        };
+      },
+      map: maplibreMap,
+      onLoad: () => dispatch('load', maplibreMap),
+      scheduler: {
+        cancelFrame: (frame) => cancelAnimationFrame(frame),
+        requestFrame: (callback) => requestAnimationFrame(callback),
+      },
+      sessionStarter,
+      setState: (state) => {
+        captureState = state;
+      },
+      subscribe: (targetMap, event, listener) => {
+        const subscription = targetMap.on(event, listener);
+        return () => subscription.unsubscribe();
+      },
     });
 
     syncMarkers();
@@ -287,70 +334,48 @@
   }
 
   function syncMarkers() {
-    clearMarkers();
-
     if (!mapInstance) {
+      markerController.clear();
       return;
     }
 
-    markerInstances = markers.map((marker) => {
-      const markerInstance = new maplibregl.Marker({
-        color: marker.color ?? '#C6A15B',
-      })
-        .setLngLat(marker.coordinates)
-        .addTo(mapInstance!);
-
-      markerInstance.getElement().title = marker.label ?? marker.id;
-      return markerInstance;
-    });
+    markerController.replace(mapInstance, markers);
   }
 
-  function clearMarkers() {
-    for (const marker of markerInstances) {
-      marker.remove();
-    }
-
-    markerInstances = [];
+  async function handleImageLoad(event: Event) {
+    await markImageReady(event.currentTarget as HTMLImageElement);
   }
 
-  function createTransformRequest(
-    getAnalytics: () => TileflowAnalytics | undefined,
-    session: string,
-    userTransformRequest?: TileflowMapOptions['transformRequest'],
-  ): RequestTransformFunction | undefined {
-    return (url, resourceType) => {
-      const request = userTransformRequest?.(url, resourceType);
-      const analyticsInput = getAnalytics();
-
-      if (isPromiseLike(request)) {
-        return request.then((resolvedRequest) =>
-          applyTileflowAnalyticsRequest(url, resolvedRequest, analyticsInput, session) ??
-          resolvedRequest,
-        );
+  async function markImageReady(image: HTMLImageElement) {
+    const runId = ++readinessRunId;
+    try {
+      if (typeof image.decode === 'function') await image.decode();
+    } catch {
+      if (!image.complete || image.naturalWidth === 0) {
+        if (runId === readinessRunId) captureState = 'error';
+        return;
       }
-
-      return applyTileflowAnalyticsRequest(url, request, analyticsInput, session);
-    };
+    }
+    if (runId === readinessRunId) captureState = 'idle';
   }
 
-  function applyTileflowAnalyticsRequest(
-    url: string,
-    request: RequestParameters | undefined,
-    analyticsInput: TileflowAnalytics | undefined,
-    session: string,
-  ): RequestParameters | undefined {
-    const requestUrl = request?.url ?? url;
-    const nextUrl = resolveTileflowAnalyticsRequestUrl(requestUrl, analyticsInput, session);
-
-    if (!nextUrl) {
-      return request;
+  async function markImageLoading() {
+    const runId = ++readinessRunId;
+    captureState = 'loading';
+    await tick();
+    if (!mounted || runId !== readinessRunId) return;
+    const image = container?.querySelector('img');
+    if (!image?.complete) return;
+    if (image.naturalWidth === 0) {
+      captureState = 'error';
+      return;
     }
-
-    return request ? {...request, url: nextUrl} : {url: nextUrl};
+    await markImageReady(image);
   }
 
-  function isPromiseLike<T>(value: T | Promise<T> | undefined): value is Promise<T> {
-    return Boolean(value && typeof (value as Promise<T>).then === 'function');
+  function handleImageError() {
+    readinessRunId += 1;
+    captureState = 'error';
   }
 
   function formatHeight(value: number | string): string {
@@ -358,12 +383,21 @@
   }
 </script>
 
-<div bind:this={container} class={className} style={frameStyle}>
+<div
+  bind:this={container}
+  class={className}
+  data-tileflow-capture-id={resolvedCaptureId}
+  data-tileflow-map={map}
+  data-tileflow-state={captureState}
+  style={frameStyle}
+>
   {#if isImageMode && runtimeImageUrl}
     <img
       {alt}
       decoding="async"
       loading={imageLoading}
+      on:error={handleImageError}
+      on:load={handleImageLoad}
       src={runtimeImageUrl}
       style="display: block; height: 100%; object-fit: cover; width: 100%;"
     />

package/src/TileflowMap.svelte.d.ts

@@ -1,5 +1,5 @@
-import type {SvelteComponentTyped} from 'svelte';
 import type {Map as MapLibreMap} from 'maplibre-gl';
+import type {SvelteComponentTyped} from 'svelte';
 import type {TileflowMapProps} from './index';
 
 export default class TileflowMap extends SvelteComponentTyped<

package/src/index.d.ts

@@ -15,6 +15,7 @@ export type TileflowMapProps = {
   alt?: string;
   analytics?: TileflowAnalytics;
   center?: [number, number];
+  captureId?: string;
   className?: string;
   config?: TileflowConfig;
   height?: number | string;