@tileflow/react 0.1.0-alpha.20 → 0.1.0-alpha.22

package/README.md

@@ -133,10 +133,9 @@ last valid runtime state active and reports structured diagnostics. `interaction
 `defaultInteractionState` are mutually exclusive. Annotation and semantic overlays share one popup
 state, so replacing either target closes the previous popup before opening the next.
 
-`MapProps` also rejects `annotations` together with legacy `markers`, and rejects controlled and
-default interaction state together. Its `mode="image"` branch excludes annotations, markers,
-semantic bindings, interaction state, renderers, and interaction callbacks. JavaScript callers and
-widened inputs still receive the corresponding runtime diagnostics.
+`MapProps` rejects controlled and default interaction state together. Its `mode="image"` branch
+excludes annotations, semantic bindings, interaction state, renderers, and interaction callbacks.
+JavaScript callers and widened inputs still receive the corresponding runtime diagnostics.
 
 `onInteractionDiagnostic` receives each newly reported structured runtime diagnostic. Changing any
 callback identity does not resubscribe the runtime or recreate MapLibre.
@@ -149,10 +148,10 @@ defaults. A `view` descriptor is a dispatch name for an application renderer; it
 serialized component tree. Tooltip content remains non-interactive, while popup content may contain
 normal React controls.
 
-The legacy `markers` prop remains available during the alpha migration and is normalized through the
-same keyed runtime. Its `label` keeps the existing marker `title`; do not pass `markers` and
-`annotations` together. `mode="image"` cannot render interaction configuration and shows an
-explicit `UNSUPPORTED_MODE` diagnostic without loading MapLibre.
+`annotations` is the only application-owned marker input. Its singular `coordinate`, required
+`ariaLabel`, and optional `marker` descriptor feed the keyed runtime directly. `mode="image"`
+cannot render interaction configuration and shows an explicit `UNSUPPORTED_MODE` diagnostic
+without loading MapLibre.
 
 `mapOptions` accepts native MapLibre options except `container` and `style`, which
 Tileflow resolves from `source`. Direct
@@ -231,9 +230,13 @@ export function Preview() {
     <StaticMap
       map="madrid"
       camera={{type: 'center', center: [-3.7038, 40.4168], zoom: 12}}
+      attribution={{mode: 'external'}}
       size={{width: 1200, height: 800}}
       createUrl="/api/static-maps"
       idempotencyKey={idempotencyKey}
+      onReady={(result) => {
+        if (result.resultVersion === 2) showAttribution(result.attribution.entries);
+      }}
     />
   );
 }
@@ -244,11 +247,19 @@ reuse it across retries and remounts. Concurrent React consumers share work only
 normalized scene, and idempotency key all identify the same operation; unmounting the final
 consumer aborts its in-flight request.
 
+`StaticMap` forwards `attribution` as part of the normalized scene and request identity. Omission
+uses embedded automatic placement. With `mode: 'external'`, the component still renders the image,
+but the application must render every structured `onReady` attribution entry beside it. Existing
+`imageUrl` mode has no operation result and cannot infer attribution from an immutable image URL.
+
 Hosted interactive maps automatically preflight a short-lived commercial session grant before
 eligible resources. Setting `analytics={{enabled: false}}` disables the optional beacon only; it
 does not remove hosted authorization or override a user `mapOptions.transformRequest` callback.
+Use `analytics={{surfaceId: 'store-locator'}}` when the same Map is embedded in several stable
+product locations. Missing or invalid Surface IDs become `default`; do not use URLs, branches,
+random instance IDs, or user IDs.
 Direct Tileflow World maps keep early `GRACE` silent, show a compact accessible owner-action pill
-when late `GRACE` is activated, and show a stronger banner in `CLAIM_REQUIRED`. Missing tiles and
+when late `GRACE` is activated, and show a stronger banner in `MANAGED_REQUIRED`. Missing tiles and
 MapLibre failures do not remove that recovery path.
 
 ## Headless capture readiness

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import * as react from 'react';
 import { CSSProperties, ImgHTMLAttributes, ReactNode } from 'react';
 import { MapOptions, Map as Map$1 } from 'maplibre-gl';
 import { TileflowThemeTransition } from '@tileflow/core/browser';
-import { TileflowRuntimeSource, TileflowThemeSelection, TileflowAnalytics, TileflowMapMarker } from '@tileflow/core/runtime';
+import { TileflowRuntimeSource, TileflowThemeSelection, TileflowAnalytics } from '@tileflow/core/runtime';
 import { TileflowAnnotation, TileflowInteractionState, TileflowAnnotationViewContext, TileflowInteractionBinding, TileflowInteractionViewContext, TileflowInteractionDiagnostic, TileflowInteractionEvent } from '@tileflow/interactions';
 
 type TileflowMapStyleSourceProps = {
@@ -10,7 +10,6 @@ type TileflowMapStyleSourceProps = {
     theme?: TileflowThemeSelection;
 };
 
-type MapMarker = TileflowMapMarker;
 type TileflowMapSource = TileflowRuntimeSource;
 type TileflowMapOptions = Omit<MapOptions, 'container' | 'style'>;
 type TileflowAnnotationRenderer<TAnnotation extends TileflowAnnotation = TileflowAnnotation> = (context: TileflowAnnotationViewContext<TAnnotation>) => ReactNode;
@@ -30,13 +29,6 @@ type MapSharedProps = {
     onLoad?: (map: Map$1) => void;
     onThemeChange?: (transition: TileflowThemeTransition) => void;
 };
-type TileflowAnnotationInputProps<TAnnotation extends TileflowAnnotation> = Readonly<{
-    annotations?: readonly TAnnotation[];
-    markers?: never;
-}> | Readonly<{
-    annotations?: never;
-    markers?: readonly MapMarker[];
-}>;
 type TileflowInteractionStateInputProps = Readonly<{
     defaultInteractionState?: never;
     interactionState?: TileflowInteractionState;
@@ -53,7 +45,8 @@ type TileflowInteractionRendererProps<TAnnotation extends TileflowAnnotation> =
     renderPopup?: TileflowInteractionRenderer<TAnnotation>;
     renderTooltip?: TileflowInteractionRenderer<TAnnotation>;
 }>;
-type MapInteractiveProps<TAnnotation extends TileflowAnnotation> = MapSharedProps & TileflowAnnotationInputProps<TAnnotation> & TileflowInteractionStateInputProps & TileflowInteractionRendererProps<TAnnotation> & {
+type MapInteractiveProps<TAnnotation extends TileflowAnnotation> = MapSharedProps & TileflowInteractionStateInputProps & TileflowInteractionRendererProps<TAnnotation> & {
+    annotations?: readonly TAnnotation[];
     mode?: 'interactive';
     onInteractionDiagnostic?: (diagnostic: TileflowInteractionDiagnostic) => void;
     onInteractionEvent?: (event: TileflowInteractionEvent<TAnnotation>) => void;
@@ -65,7 +58,6 @@ type MapImageProps = MapSharedProps & {
     defaultInteractionState?: never;
     interactionState?: never;
     interactions?: never;
-    markers?: never;
     mode: 'image';
     onInteractionDiagnostic?: never;
     onInteractionEvent?: never;
@@ -77,4 +69,4 @@ type MapImageProps = MapSharedProps & {
 type MapProps<TAnnotation extends TileflowAnnotation = TileflowAnnotation> = (MapInteractiveProps<TAnnotation> | MapImageProps) & TileflowMapStyleSourceProps;
 declare function Map<TAnnotation extends TileflowAnnotation = TileflowAnnotation>(props: MapProps<TAnnotation>): react.JSX.Element;
 
-export { Map, type MapMarker, type MapProps, type TileflowAnnotationRenderer, type TileflowInteractionRenderer, type TileflowMapOptions, type TileflowMapSource };
+export { Map, type MapProps, type TileflowAnnotationRenderer, type TileflowInteractionRenderer, type TileflowMapOptions, type TileflowMapSource };

package/dist/index.js

@@ -19,6 +19,7 @@ import {
   getTileflowSystemColorScheme,
   loadTileflowStyleFonts,
   registerTileflowContourProtocol,
+  registerTileflowPmtilesProtocol,
   registerTileflowWorldRequestBridge,
   subscribeTileflowSystemColorScheme
 } from "@tileflow/core/browser";
@@ -49,26 +50,9 @@ import {
 import {
   validateTileflowAnnotations
 } from "@tileflow/interactions";
-import { normalizeTileflowLegacyMarkers } from "@tileflow/interactions/maplibre";
-function prepareTileflowReactAnnotations(annotations, markers) {
-  if (annotations !== void 0 && markers !== void 0) {
-    return {
-      annotations: [],
-      diagnostics: [
-        {
-          code: "INVALID_DOCUMENT",
-          level: "error",
-          message: "Tileflow Map accepts annotations or legacy markers, not both.",
-          path: ""
-        }
-      ],
-      ok: false,
-      titles: /* @__PURE__ */ new Map()
-    };
-  }
-  const normalized = normalizeTileflowLegacyMarkers(markers ?? []);
-  const candidates = annotations ?? normalized.annotations;
-  const titles = annotations === void 0 ? normalized.titles : new Map(annotations.map((annotation) => [annotation.id, annotation.ariaLabel]));
+function prepareTileflowReactAnnotations(annotations) {
+  const candidates = annotations ?? [];
+  const titles = new Map(candidates.map((annotation) => [annotation.id, annotation.ariaLabel]));
   const validation = validateTileflowAnnotations(candidates);
   if (!validation.ok) {
     return {
@@ -237,7 +221,6 @@ function Map2(props) {
     imageLoading = "eager",
     interactive,
     mapOptions,
-    markers,
     analytics,
     theme,
     interactionState,
@@ -263,8 +246,8 @@ function Map2(props) {
   const mapName = runtimeSource.kind === "tileflow" ? runtimeSource.map : void 0;
   const manifestUrl = runtimeSource.kind === "tileflow" ? runtimeSource.manifestUrl ?? defaultTileflowManifestUrl : defaultTileflowManifestUrl;
   const preparedAnnotations = useMemo(
-    () => prepareTileflowReactAnnotations(annotations, markers),
-    [annotations, markers]
+    () => prepareTileflowReactAnnotations(annotations),
+    [annotations]
   );
   const preparedInteractions = useMemo(
     () => prepareTileflowReactInteractionBindings(interactions),
@@ -377,7 +360,7 @@ function Map2(props) {
   const mapNameRef = useRef(mapName);
   const resolvedAnalyticsRef = useRef(void 0);
   const readinessRunRef = useRef(0);
-  const hasAdditionalInteractionConfiguration = annotations !== void 0 || defaultInteractionState !== void 0 || interactionState !== void 0 || markers !== void 0 || onInteractionDiagnostic !== void 0 || onInteractionEvent !== void 0 || onInteractionStateChange !== void 0 || renderMarker !== void 0 || renderPopup !== void 0 || renderTooltip !== void 0 || props.interactions !== void 0;
+  const hasAdditionalInteractionConfiguration = annotations !== void 0 || defaultInteractionState !== void 0 || interactionState !== void 0 || onInteractionDiagnostic !== void 0 || onInteractionEvent !== void 0 || onInteractionStateChange !== void 0 || renderMarker !== void 0 || renderPopup !== void 0 || renderTooltip !== void 0 || props.interactions !== void 0;
   const modeDiagnostic = useMemo(
     () => isImageMode ? imageModeMapInteractionDiagnostic(
       preparedAnnotations.annotations.length,
@@ -706,6 +689,7 @@ function Map2(props) {
       const fairUseNotice = attachTileflowFairUseNotice(container);
       registerCleanup(() => fairUseNotice.dispose());
       registerTileflowContourProtocol({ addProtocol: maplibregl.addProtocol });
+      registerTileflowPmtilesProtocol({ addProtocol: maplibregl.addProtocol });
       const worldRequestBridge = registerTileflowWorldRequestBridge({
         addProtocol: maplibregl.addProtocol,
         onNotice: fairUseNotice.update

package/dist/static.d.ts

@@ -26,6 +26,6 @@ type StaticMapCreateProps = {
     imageUrl?: never;
 };
 type StaticMapProps = StaticMapBaseProps & (StaticMapCreateProps | StaticMapImageProps);
-declare function StaticMap({ alt, camera, className, captureId, createUrl, imageStyle, imageUrl, idempotencyKey, keepPreviousImage, loading, map, onError, onImageLoad, onReady, overlays, size, style, theme, }: StaticMapProps): react.JSX.Element;
+declare function StaticMap({ alt, attribution, camera, className, captureId, createUrl, format, imageStyle, imageUrl, idempotencyKey, keepPreviousImage, loading, map, onError, onImageLoad, onReady, overlays, size, style, theme, }: StaticMapProps): react.JSX.Element;
 
 export { StaticMap, type StaticMapProps };

package/dist/static.js

@@ -107,10 +107,12 @@ function abortReason(signal) {
 import { jsx } from "react/jsx-runtime";
 function StaticMap({
   alt = "",
+  attribution,
   camera,
   className,
   captureId,
   createUrl,
+  format,
   imageStyle,
   imageUrl,
   idempotencyKey,
@@ -135,10 +137,10 @@ function StaticMap({
   const resolvedCaptureId = normalizeTileflowCaptureId(captureId);
   const onErrorRef = useRef(onError);
   const onReadyRef = useRef(onReady);
-  const sceneInputKey = stableStringify2({ camera, map, overlays, size, theme });
+  const sceneInputKey = stableStringify2({ attribution, camera, format, map, overlays, size, theme });
   const preparedSceneCandidate = useMemo(
-    () => prepareSceneRequest({ camera, map, overlays, size, theme }),
-    [camera, map, overlays, size, theme]
+    () => prepareSceneRequest({ attribution, camera, format, map, overlays, size, theme }),
+    [attribution, camera, format, map, overlays, size, theme]
   );
   const preparedScene = useStablePreparedSceneRequest(preparedSceneCandidate);
   const sceneKey = preparedScene.ok ? preparedScene.request.sceneKey : `invalid:${sceneInputKey}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/react",
-  "version": "0.1.0-alpha.20",
+  "version": "0.1.0-alpha.22",
   "license": "Apache-2.0",
   "description": "React components for rendering Tileflow maps with MapLibre.",
   "type": "module",
@@ -46,9 +46,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@tileflow/core": ">=0.1.0-alpha.21 <0.1.0-beta.0",
-    "@tileflow/interactions": ">=0.1.0-alpha.0 <0.1.0-beta.0",
-    "@tileflow/static": ">=0.1.0-alpha.18 <0.1.0-beta.0"
+    "@tileflow/core": ">=0.1.0-alpha.23 <0.1.0-beta.0",
+    "@tileflow/interactions": ">=0.1.0-alpha.1 <0.1.0-beta.0",
+    "@tileflow/static": ">=0.1.0-alpha.22 <0.1.0-beta.0"
   },
   "peerDependencies": {
     "maplibre-gl": ">=5 <7",