@tileflow/react 0.1.0-alpha.14 → 0.1.0-alpha.16

package/README.md

@@ -55,4 +55,18 @@ the production image behavior locally.
 For full static scenes with bounds, overlays, and server-side precache, use
 `StaticMap` from `@tileflow/react/static` or helpers from `@tileflow/static`.
 
+## Headless capture readiness
+
+Use `captureId` to disambiguate multiple maps with the same configured name:
+
+```tsx
+<Map map="madrid" captureId="checkout-map" />
+```
+
+The root element exposes `data-tileflow-map`, optional `data-tileflow-capture-id`, and
+`data-tileflow-state="loading|idle|error"`. Interactive mode becomes idle after MapLibre is idle
+and two animation frames; style/data work returns it to loading. Image mode waits for decode or a
+successful load fallback, including cached hydration. `tileflow capture` uses these markers for
+application scenes and requires exactly one target.
+
 Docs: https://tileflow.dev/docs

package/dist/index.d.ts

@@ -6,6 +6,7 @@ import { TileflowConfig, MapLibreStyle, TileflowProjectThemes, TileflowMapMarker
 type MapMarker = TileflowMapMarker;
 type TileflowMapOptions = Omit<MapOptions, 'container' | 'style'>;
 type MapProps = {
+    captureId?: string;
     map?: string;
     mode?: 'interactive' | 'image';
     config?: TileflowConfig;
@@ -29,6 +30,6 @@ type MapProps = {
     analytics?: TileflowAnalytics;
     onLoad?: (map: Map$1) => void;
 };
-declare function Map({ map: mapName, mode, config, style, styleUrl, imageUrl, styleBaseUrl, tileBaseUrl, themes, manifestUrl, preferLocalDev, alt, center, zoom, className, height, imageLoading, interactive, mapOptions, markers, analytics, onLoad, }: MapProps): react.JSX.Element;
+declare function Map({ captureId, map: mapName, mode, config, style, styleUrl, imageUrl, styleBaseUrl, tileBaseUrl, themes, manifestUrl, preferLocalDev, alt, center, zoom, className, height, imageLoading, interactive, mapOptions, markers, analytics, onLoad, }: MapProps): react.JSX.Element;
 
 export { Map, type MapMarker, type MapProps, type TileflowMapOptions };

package/dist/index.js

@@ -3,6 +3,7 @@
 // src/map.tsx
 import {
   useEffect,
+  useLayoutEffect,
   useMemo,
   useRef,
   useState
@@ -13,6 +14,7 @@ import {
   defaultTileflowManifestUrl,
   loadTileflowManifest,
   mergeTileflowAnalytics,
+  normalizeTileflowCaptureId,
   normalizeTileflowStaticImageSize,
   resolveTileflowAnalyticsRequestUrl,
   resolveTileflowManifestMap,
@@ -26,6 +28,7 @@ import { jsx } from "react/jsx-runtime";
 var defaultCenter = [0, 20];
 var defaultMarkers = [];
 function Map({
+  captureId,
   map: mapName,
   mode = "interactive",
   config,
@@ -50,6 +53,7 @@ function Map({
   onLoad
 }) {
   const containerRef = useRef(null);
+  const imageRef = useRef(null);
   const mapRef = useRef(null);
   const markerInstancesRef = useRef([]);
   const stableMapOptions = useStableMapOptions(mapOptions);
@@ -65,9 +69,12 @@ function Map({
   const mapNameRef = useRef(mapName);
   const resolvedAnalyticsRef = useRef(void 0);
   const sessionStartsRef = useRef(/* @__PURE__ */ new Set());
+  const readinessRunRef = useRef(0);
   const sessionId = useMemo(() => createTileflowSessionId(), []);
   const [manifestMap, setManifestMap] = useState(null);
   const [imageSize, setImageSize] = useState(null);
+  const [captureState, setCaptureState] = useState("loading");
+  const resolvedCaptureId = normalizeTileflowCaptureId(captureId);
   const resolvedMode = resolveTileflowMapMode({ imageUrl, mode, preferLocalDev });
   const isImageMode = resolvedMode === "image";
   useEffect(() => {
@@ -192,6 +199,25 @@ function Map({
     if (!containerRef.current || !runtimeStyle) {
       return;
     }
+    const setLoading = () => {
+      readinessRunRef.current += 1;
+      setCaptureState("loading");
+    };
+    const setError = () => {
+      readinessRunRef.current += 1;
+      setCaptureState("error");
+    };
+    const setIdleAfterFrames = () => {
+      const run = ++readinessRunRef.current;
+      requestAnimationFrame(() => {
+        requestAnimationFrame(() => {
+          if (readinessRunRef.current === run && mapRef.current === map) {
+            setCaptureState("idle");
+          }
+        });
+      });
+    };
+    setLoading();
     const map = new maplibregl.Map({
       ...stableMapOptions,
       container: containerRef.current,
@@ -228,7 +254,12 @@ function Map({
         }
       }
     });
+    map.on("dataloading", setLoading);
+    map.on("styledataloading", setLoading);
+    map.on("idle", setIdleAfterFrames);
+    map.on("error", setError);
     return () => {
+      readinessRunRef.current += 1;
       resizeObserver.disconnect();
       clearMarkers(markerInstancesRef.current);
       markerInstancesRef.current = [];
@@ -236,6 +267,28 @@ function Map({
       mapRef.current = null;
     };
   }, [resolvedInteractive, runtimeStyle, sessionId, stableMapOptions, transformRequest]);
+  useLayoutEffect(() => {
+    if (!isImageMode) return;
+    readinessRunRef.current += 1;
+    setCaptureState("loading");
+    const image = imageRef.current;
+    if (image?.complete) {
+      if (image.naturalWidth === 0) setCaptureState("error");
+      else void markImageReady(image);
+    }
+  }, [isImageMode, runtimeImageUrl]);
+  async function markImageReady(image) {
+    const run = ++readinessRunRef.current;
+    try {
+      if (typeof image.decode === "function") await image.decode();
+    } catch {
+      if (!image.complete || image.naturalWidth === 0) {
+        if (readinessRunRef.current === run) setCaptureState("error");
+        return;
+      }
+    }
+    if (readinessRunRef.current === run) setCaptureState("idle");
+  }
   useEffect(() => {
     const map = mapRef.current;
     clearMarkers(markerInstancesRef.current);
@@ -263,23 +316,50 @@ function Map({
     width: "100%"
   };
   if (isImageMode) {
-    return /* @__PURE__ */ jsx("div", { className, ref: containerRef, style: frameStyle, children: runtimeImageUrl ? /* @__PURE__ */ jsx(
-      "img",
+    return /* @__PURE__ */ jsx(
+      "div",
       {
-        alt,
-        decoding: "async",
-        loading: imageLoading,
-        src: runtimeImageUrl,
-        style: {
-          display: "block",
-          height: "100%",
-          objectFit: "cover",
-          width: "100%"
-        }
+        className,
+        "data-tileflow-capture-id": resolvedCaptureId,
+        "data-tileflow-map": mapName,
+        "data-tileflow-state": captureState,
+        ref: containerRef,
+        style: frameStyle,
+        children: runtimeImageUrl ? /* @__PURE__ */ jsx(
+          "img",
+          {
+            alt,
+            decoding: "async",
+            loading: imageLoading,
+            onError: () => {
+              readinessRunRef.current += 1;
+              setCaptureState("error");
+            },
+            onLoad: (event) => void markImageReady(event.currentTarget),
+            ref: imageRef,
+            src: runtimeImageUrl,
+            style: {
+              display: "block",
+              height: "100%",
+              objectFit: "cover",
+              width: "100%"
+            }
+          }
+        ) : null
       }
-    ) : null });
+    );
   }
-  return /* @__PURE__ */ jsx("div", { className, ref: containerRef, style: frameStyle });
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      className,
+      "data-tileflow-capture-id": resolvedCaptureId,
+      "data-tileflow-map": mapName,
+      "data-tileflow-state": captureState,
+      ref: containerRef,
+      style: frameStyle
+    }
+  );
 }
 function createTransformRequest(getAnalytics, sessionId, userTransformRequest) {
   return (url, resourceType) => {

package/dist/static.d.ts

@@ -5,11 +5,12 @@ import { StaticSceneInput, StaticMapResult } from '@tileflow/static';
 type StaticMapBaseProps = StaticSceneInput & {
     alt?: string;
     className?: string;
+    captureId?: string;
     imageStyle?: CSSProperties;
     keepPreviousImage?: boolean;
-    loading?: ImgHTMLAttributes<HTMLImageElement>["loading"];
+    loading?: ImgHTMLAttributes<HTMLImageElement>['loading'];
     onError?: (error: Error) => void;
-    onImageLoad?: ImgHTMLAttributes<HTMLImageElement>["onLoad"];
+    onImageLoad?: ImgHTMLAttributes<HTMLImageElement>['onLoad'];
     onReady?: (result: StaticMapResult) => void;
     style?: CSSProperties;
 };
@@ -22,6 +23,6 @@ type StaticMapCreateProps = {
     imageUrl?: never;
 };
 type StaticMapProps = StaticMapBaseProps & (StaticMapCreateProps | StaticMapImageProps);
-declare function StaticMap({ alt, camera, className, createUrl, imageStyle, imageUrl, keepPreviousImage, loading, map, onError, onImageLoad, onReady, overlays, size, style, }: StaticMapProps): react.JSX.Element;
+declare function StaticMap({ alt, camera, className, captureId, createUrl, imageStyle, imageUrl, keepPreviousImage, loading, map, onError, onImageLoad, onReady, overlays, size, style, }: StaticMapProps): react.JSX.Element;
 
 export { StaticMap, type StaticMapProps };

package/dist/static.js

@@ -3,16 +3,19 @@
 // src/static-map.tsx
 import {
   useEffect,
+  useLayoutEffect,
   useMemo,
   useRef,
   useState
 } from "react";
+import { normalizeTileflowCaptureId } from "@tileflow/core";
 import { jsx } from "react/jsx-runtime";
 var inFlightRequests = /* @__PURE__ */ new Map();
 function StaticMap({
   alt = "",
   camera,
   className,
+  captureId,
   createUrl,
   imageStyle,
   imageUrl,
@@ -30,6 +33,10 @@ function StaticMap({
     imageUrl ? imageResult(imageUrl) : null
   );
   const [error, setError] = useState(null);
+  const [captureState, setCaptureState] = useState("loading");
+  const imageLoadRunRef = useRef(0);
+  const imageRef = useRef(null);
+  const resolvedCaptureId = normalizeTileflowCaptureId(captureId);
   const onErrorRef = useRef(onError);
   const onReadyRef = useRef(onReady);
   const sceneKey = useMemo(
@@ -37,6 +44,27 @@ function StaticMap({
     [camera, map, overlays, size]
   );
   const requestKey = imageUrl ? `image:${imageUrl}` : `create:${createUrl}:${sceneKey}`;
+  useLayoutEffect(() => {
+    imageLoadRunRef.current += 1;
+    setCaptureState("loading");
+    const image = imageRef.current;
+    if (image?.complete) {
+      if (image.naturalWidth === 0) setCaptureState("error");
+      else void markImageReady(image);
+    }
+  }, [requestKey]);
+  async function markImageReady(image) {
+    const runId = ++imageLoadRunRef.current;
+    try {
+      if (typeof image.decode === "function") await image.decode();
+    } catch {
+      if (!image.complete || image.naturalWidth === 0) {
+        if (runId === imageLoadRunRef.current) setCaptureState("error");
+        return;
+      }
+    }
+    if (runId === imageLoadRunRef.current) setCaptureState("idle");
+  }
   useEffect(() => {
     onErrorRef.current = onError;
     onReadyRef.current = onReady;
@@ -77,6 +105,8 @@ function StaticMap({
         setResult(null);
       }
       setError(normalizedError);
+      imageLoadRunRef.current += 1;
+      setCaptureState("error");
       onErrorRef.current?.(normalizedError);
     });
     return () => {
@@ -88,6 +118,9 @@ function StaticMap({
     {
       "aria-busy": !result && !error,
       className,
+      "data-tileflow-capture-id": resolvedCaptureId,
+      "data-tileflow-map": map,
+      "data-tileflow-state": captureState,
       style: {
         aspectRatio: `${size.width} / ${size.height}`,
         background: "#f4f4f2",
@@ -104,9 +137,15 @@ function StaticMap({
           onError: () => {
             const imageError = new Error("Static map image failed to load");
             setError(imageError);
+            imageLoadRunRef.current += 1;
+            setCaptureState("error");
             onErrorRef.current?.(imageError);
           },
-          onLoad: onImageLoad,
+          onLoad: (event) => {
+            onImageLoad?.(event);
+            void markImageReady(event.currentTarget);
+          },
+          ref: imageRef,
           src: result.imageUrl,
           style: {
             display: "block",

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@tileflow/react",
-  "version": "0.1.0-alpha.14",
+  "version": "0.1.0-alpha.16",
   "description": "React components for rendering Tileflow maps with MapLibre.",
   "type": "module",
   "sideEffects": false,
   "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/react"
   },
   "bugs": {
-    "url": "https://github.com/tileflow/tileflow/issues"
+    "url": "https://github.com/tileflow/tileflow-sdk/issues"
   },
   "keywords": [
     "tileflow",
@@ -41,8 +41,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@tileflow/core": "0.1.0-alpha.14",
-    "@tileflow/static": "0.1.0-alpha.14"
+    "@tileflow/core": "0.1.0-alpha.16",
+    "@tileflow/static": "0.1.0-alpha.16"
   },
   "peerDependencies": {
     "maplibre-gl": ">=5",