@tileflow/vue 0.1.0-alpha.10

package/README.md

@@ -0,0 +1,31 @@
+# @tileflow/vue
+
+Vue component for rendering Tileflow maps with MapLibre.
+
+Install `maplibre-gl` alongside the package and import its CSS once in your app.
+
+```vue
+<script setup lang="ts">
+import 'maplibre-gl/dist/maplibre-gl.css';
+import {TileflowMap} from '@tileflow/vue';
+</script>
+
+<template>
+  <TileflowMap
+    map="madrid"
+    :center="[-3.7038, 40.4168]"
+    :zoom="12"
+    :map-options="{
+      cooperativeGestures: true,
+      maxZoom: 18,
+    }"
+  />
+</template>
+```
+
+`mapOptions` accepts native MapLibre options except `container` and `style`, which
+Tileflow resolves from the map name, manifest, or explicit style props. Direct
+Tileflow props such as `center`, `zoom`, and `interactive` take priority when
+provided.
+
+Docs: https://tileflow.dev/docs

package/dist/index.d.ts

@@ -0,0 +1,140 @@
+import * as vue from 'vue';
+import { PropType } from 'vue';
+import maplibregl, { MapOptions, Map } from 'maplibre-gl';
+import { TileflowAnalytics, TileflowConfig, MapLibreStyle, TileflowMapMarker, TileflowProjectThemes } from '@tileflow/core';
+
+type TileflowMapMode = 'interactive' | 'image';
+type TileflowMapOptions = Omit<MapOptions, 'container' | 'style'>;
+type TileflowMapProps = {
+    alt?: string;
+    analytics?: TileflowAnalytics;
+    center?: [number, number];
+    className?: string;
+    config?: TileflowConfig;
+    height?: number | string;
+    imageLoading?: HTMLImageElement['loading'];
+    imageUrl?: string;
+    interactive?: boolean;
+    manifestUrl?: string;
+    map?: string;
+    mapOptions?: TileflowMapOptions;
+    mapStyle?: MapLibreStyle;
+    markers?: TileflowMapMarker[];
+    mode?: TileflowMapMode;
+    preferLocalDev?: boolean;
+    styleBaseUrl?: string;
+    styleUrl?: string;
+    themes?: TileflowProjectThemes;
+    tileBaseUrl?: string;
+    zoom?: number;
+};
+declare const TileflowMap: vue.DefineComponent<vue.ExtractPropTypes<{
+    alt: {
+        default: string;
+        type: StringConstructor;
+    };
+    analytics: PropType<TileflowAnalytics>;
+    center: PropType<[number, number]>;
+    className: StringConstructor;
+    config: PropType<TileflowConfig>;
+    height: {
+        default: number;
+        type: PropType<number | string>;
+    };
+    imageLoading: {
+        default: string;
+        type: PropType<HTMLImageElement["loading"]>;
+    };
+    imageUrl: StringConstructor;
+    interactive: {
+        default: undefined;
+        type: PropType<boolean | undefined>;
+    };
+    manifestUrl: {
+        default: string;
+        type: StringConstructor;
+    };
+    map: StringConstructor;
+    mapOptions: PropType<TileflowMapOptions>;
+    mapStyle: PropType<MapLibreStyle>;
+    markers: {
+        default: () => never[];
+        type: PropType<TileflowMapMarker[]>;
+    };
+    mode: {
+        default: string;
+        type: PropType<TileflowMapMode>;
+    };
+    preferLocalDev: {
+        default: boolean;
+        type: BooleanConstructor;
+    };
+    styleBaseUrl: StringConstructor;
+    styleUrl: StringConstructor;
+    themes: PropType<TileflowProjectThemes>;
+    tileBaseUrl: StringConstructor;
+    zoom: NumberConstructor;
+}>, () => vue.VNode<vue.RendererNode, vue.RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {
+    load: (_map: Map) => true;
+}, string, vue.PublicProps, Readonly<vue.ExtractPropTypes<{
+    alt: {
+        default: string;
+        type: StringConstructor;
+    };
+    analytics: PropType<TileflowAnalytics>;
+    center: PropType<[number, number]>;
+    className: StringConstructor;
+    config: PropType<TileflowConfig>;
+    height: {
+        default: number;
+        type: PropType<number | string>;
+    };
+    imageLoading: {
+        default: string;
+        type: PropType<HTMLImageElement["loading"]>;
+    };
+    imageUrl: StringConstructor;
+    interactive: {
+        default: undefined;
+        type: PropType<boolean | undefined>;
+    };
+    manifestUrl: {
+        default: string;
+        type: StringConstructor;
+    };
+    map: StringConstructor;
+    mapOptions: PropType<TileflowMapOptions>;
+    mapStyle: PropType<MapLibreStyle>;
+    markers: {
+        default: () => never[];
+        type: PropType<TileflowMapMarker[]>;
+    };
+    mode: {
+        default: string;
+        type: PropType<TileflowMapMode>;
+    };
+    preferLocalDev: {
+        default: boolean;
+        type: BooleanConstructor;
+    };
+    styleBaseUrl: StringConstructor;
+    styleUrl: StringConstructor;
+    themes: PropType<TileflowProjectThemes>;
+    tileBaseUrl: StringConstructor;
+    zoom: NumberConstructor;
+}>> & Readonly<{
+    onLoad?: ((_map: maplibregl.Map) => any) | undefined;
+}>, {
+    interactive: boolean | undefined;
+    alt: string;
+    height: string | number;
+    imageLoading: "eager" | "lazy";
+    manifestUrl: string;
+    markers: TileflowMapMarker[];
+    mode: TileflowMapMode;
+    preferLocalDev: boolean;
+}, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
+
+export { TileflowMap, type TileflowMapMode, type TileflowMapOptions, type TileflowMapProps, TileflowMap as default };

package/dist/index.js

@@ -0,0 +1,389 @@
+// src/index.ts
+import maplibregl from "maplibre-gl";
+import {
+  computed,
+  defineComponent,
+  h,
+  onBeforeUnmount,
+  onMounted,
+  ref,
+  shallowRef,
+  watch
+} from "vue";
+import {
+  createTileflowSessionId,
+  defaultTileflowManifestUrl,
+  loadTileflowManifest,
+  mergeTileflowAnalytics,
+  normalizeTileflowStaticImageSize,
+  resolveTileflowAnalyticsRequestUrl,
+  resolveTileflowManifestMap,
+  resolveTileflowMapMode,
+  resolveTileflowRuntimeStyle,
+  resolveTileflowStaticImageUrl,
+  shouldLoadTileflowManifest,
+  startTileflowSession
+} from "@tileflow/core";
+var defaultCenter = [0, 20];
+var defaultZoom = 2;
+var TileflowMap = defineComponent({
+  name: "TileflowMap",
+  inheritAttrs: false,
+  props: {
+    alt: {
+      default: "",
+      type: String
+    },
+    analytics: Object,
+    center: Array,
+    className: String,
+    config: Object,
+    height: {
+      default: 420,
+      type: [Number, String]
+    },
+    imageLoading: {
+      default: "eager",
+      type: String
+    },
+    imageUrl: String,
+    interactive: {
+      default: void 0,
+      type: Boolean
+    },
+    manifestUrl: {
+      default: defaultTileflowManifestUrl,
+      type: String
+    },
+    map: String,
+    mapOptions: Object,
+    mapStyle: Object,
+    markers: {
+      default: () => [],
+      type: Array
+    },
+    mode: {
+      default: "interactive",
+      type: String
+    },
+    preferLocalDev: {
+      default: true,
+      type: Boolean
+    },
+    styleBaseUrl: String,
+    styleUrl: String,
+    themes: Object,
+    tileBaseUrl: String,
+    zoom: Number
+  },
+  emits: {
+    load: (_map) => true
+  },
+  setup(props, { attrs, emit }) {
+    const containerRef = ref(null);
+    const manifestMap = shallowRef(null);
+    const imageSize = shallowRef(null);
+    const mapRef = shallowRef(null);
+    const sessionId = createTileflowSessionId();
+    const markerInstances = [];
+    const sessionStarts = /* @__PURE__ */ new Set();
+    let imageResizeObserver = null;
+    let mapResizeObserver = null;
+    let manifestLoadId = 0;
+    const resolvedMode = computed(
+      () => resolveTileflowMapMode({
+        imageUrl: props.imageUrl,
+        mode: props.mode,
+        preferLocalDev: props.preferLocalDev
+      })
+    );
+    const isImageMode = computed(() => resolvedMode.value === "image");
+    const imageCenter = computed(() => props.center ?? defaultCenter);
+    const imageZoom = computed(() => props.zoom ?? defaultZoom);
+    const resolvedCenter = computed(
+      () => props.center ?? props.mapOptions?.center ?? defaultCenter
+    );
+    const resolvedZoom = computed(() => props.zoom ?? props.mapOptions?.zoom ?? defaultZoom);
+    const resolvedInteractive = computed(
+      () => props.interactive ?? props.mapOptions?.interactive ?? true
+    );
+    const runtimeStyle = computed(
+      () => isImageMode.value ? null : resolveTileflowRuntimeStyle({
+        config: props.config,
+        manifestMap: manifestMap.value,
+        map: props.map,
+        preferLocalDev: props.preferLocalDev,
+        style: props.mapStyle,
+        styleBaseUrl: props.styleBaseUrl,
+        styleUrl: props.styleUrl,
+        themes: props.themes,
+        tileBaseUrl: props.tileBaseUrl
+      })
+    );
+    const resolvedAnalytics = computed(
+      () => mergeTileflowAnalytics(props.analytics, runtimeStyle.value?.analytics)
+    );
+    const runtimeImageUrl = computed(
+      () => props.imageUrl ?? (isImageMode.value ? resolveTileflowStaticImageUrl({
+        center: imageCenter.value,
+        imageSize: imageSize.value,
+        manifestMap: manifestMap.value,
+        zoom: imageZoom.value
+      }) : void 0)
+    );
+    const frameStyle = computed(() => ({
+      height: formatHeight(props.height),
+      minHeight: "240px",
+      overflow: "hidden",
+      position: "relative",
+      width: "100%"
+    }));
+    const refreshManifest = async () => {
+      const shouldLoad = shouldLoadTileflowManifest({
+        config: props.config,
+        imageMode: isImageMode.value,
+        imageUrl: props.imageUrl,
+        map: props.map,
+        style: props.mapStyle,
+        styleBaseUrl: props.styleBaseUrl,
+        styleUrl: props.styleUrl
+      });
+      if (!shouldLoad) {
+        manifestMap.value = null;
+        return;
+      }
+      const loadId = ++manifestLoadId;
+      manifestMap.value = null;
+      try {
+        const manifest = await loadTileflowManifest(props.manifestUrl);
+        if (loadId === manifestLoadId) {
+          manifestMap.value = manifest && props.map ? resolveTileflowManifestMap(manifest, props.map) : null;
+        }
+      } catch (error) {
+        if (loadId === manifestLoadId) {
+          console.error("Failed to load Tileflow manifest", error);
+          manifestMap.value = null;
+        }
+      }
+    };
+    const updateImageResizeObserver = () => {
+      imageResizeObserver?.disconnect();
+      imageResizeObserver = null;
+      imageSize.value = null;
+      if (!isImageMode.value || props.imageUrl || !containerRef.value) {
+        return;
+      }
+      const element = containerRef.value;
+      const updateImageSize = () => {
+        const nextSize = normalizeTileflowStaticImageSize({
+          height: element.clientHeight,
+          width: element.clientWidth
+        });
+        imageSize.value = imageSize.value?.height === nextSize.height && imageSize.value.width === nextSize.width ? imageSize.value : nextSize;
+      };
+      imageResizeObserver = new ResizeObserver(updateImageSize);
+      imageResizeObserver.observe(element);
+      updateImageSize();
+    };
+    const destroyMap = () => {
+      mapResizeObserver?.disconnect();
+      mapResizeObserver = null;
+      clearMarkers(markerInstances);
+      mapRef.value?.remove();
+      mapRef.value = null;
+    };
+    const recreateMap = () => {
+      destroyMap();
+      if (!containerRef.value || !runtimeStyle.value || isImageMode.value) {
+        return;
+      }
+      const runtime = runtimeStyle.value;
+      const map = new maplibregl.Map({
+        ...props.mapOptions,
+        attributionControl: props.mapOptions?.attributionControl ?? { compact: true },
+        center: resolvedCenter.value,
+        container: containerRef.value,
+        interactive: resolvedInteractive.value,
+        style: runtime.style,
+        transformRequest: createTransformRequest(
+          resolvedAnalytics.value,
+          sessionId,
+          props.mapOptions?.transformRequest
+        ),
+        zoom: resolvedZoom.value
+      });
+      mapRef.value = map;
+      if (resolvedInteractive.value) {
+        map.addControl(new maplibregl.NavigationControl(), "top-right");
+      }
+      mapResizeObserver = new ResizeObserver(() => {
+        map.resize();
+      });
+      mapResizeObserver.observe(containerRef.value);
+      map.on("load", () => {
+        const analyticsForLoad = resolvedAnalytics.value;
+        const styleId = analyticsForLoad?.styleId ?? (typeof runtime.style === "string" ? runtime.style : props.map);
+        emit("load", map);
+        if (analyticsForLoad?.mapId) {
+          const sessionKey = `${sessionId}:${analyticsForLoad.mapId}:${styleId ?? ""}`;
+          if (!sessionStarts.has(sessionKey)) {
+            sessionStarts.add(sessionKey);
+            startTileflowSession(analyticsForLoad, {
+              mapId: analyticsForLoad.mapId,
+              sessionId,
+              source: "vue",
+              styleId
+            });
+          }
+        }
+      });
+      syncMarkers();
+    };
+    const syncView = () => {
+      mapRef.value?.jumpTo({
+        center: resolvedCenter.value,
+        zoom: resolvedZoom.value
+      });
+    };
+    const syncMarkers = () => {
+      const map = mapRef.value;
+      clearMarkers(markerInstances);
+      if (!map) {
+        return;
+      }
+      for (const marker of props.markers) {
+        const markerInstance = new maplibregl.Marker({
+          color: marker.color ?? "#C6A15B"
+        }).setLngLat(marker.coordinates).addTo(map);
+        markerInstance.getElement().title = marker.label ?? marker.id;
+        markerInstances.push(markerInstance);
+      }
+    };
+    onMounted(() => {
+      void refreshManifest();
+      updateImageResizeObserver();
+      recreateMap();
+    });
+    onBeforeUnmount(() => {
+      imageResizeObserver?.disconnect();
+      destroyMap();
+    });
+    watch(
+      () => [
+        props.config,
+        props.imageUrl,
+        props.manifestUrl,
+        props.map,
+        props.mapStyle,
+        props.mode,
+        props.preferLocalDev,
+        props.styleBaseUrl,
+        props.styleUrl
+      ],
+      () => {
+        void refreshManifest();
+      }
+    );
+    watch(
+      () => [props.imageUrl, props.mode, props.preferLocalDev],
+      () => updateImageResizeObserver(),
+      { flush: "post" }
+    );
+    watch(
+      () => [
+        props.config,
+        props.analytics,
+        props.interactive,
+        props.map,
+        props.mapOptions,
+        props.mapStyle,
+        props.mode,
+        props.preferLocalDev,
+        props.styleBaseUrl,
+        props.styleUrl,
+        props.themes,
+        props.tileBaseUrl,
+        manifestMap.value
+      ],
+      () => recreateMap(),
+      { flush: "post" }
+    );
+    watch(
+      () => [props.center, props.zoom, props.mapOptions?.center, props.mapOptions?.zoom],
+      () => syncView(),
+      { flush: "post" }
+    );
+    watch(
+      () => props.markers,
+      () => syncMarkers(),
+      { flush: "post" }
+    );
+    return () => {
+      const rootAttrs = { ...attrs };
+      const classValue = [attrs.class, props.className];
+      const styleValue = [attrs.style, frameStyle.value];
+      delete rootAttrs.class;
+      delete rootAttrs.style;
+      return h(
+        "div",
+        {
+          ...rootAttrs,
+          class: classValue,
+          ref: containerRef,
+          style: styleValue
+        },
+        isImageMode.value && runtimeImageUrl.value ? h("img", {
+          alt: props.alt,
+          decoding: "async",
+          loading: props.imageLoading,
+          src: runtimeImageUrl.value,
+          style: {
+            display: "block",
+            height: "100%",
+            objectFit: "cover",
+            width: "100%"
+          }
+        }) : void 0
+      );
+    };
+  }
+});
+var index_default = TileflowMap;
+function createTransformRequest(analytics, sessionId, userTransformRequest) {
+  if ((!analytics || analytics.enabled === false) && !userTransformRequest) {
+    return void 0;
+  }
+  return (url, resourceType) => {
+    const request = userTransformRequest?.(url, resourceType);
+    if (isPromiseLike(request)) {
+      return request.then(
+        (resolvedRequest) => applyTileflowAnalyticsRequest(url, resolvedRequest, analytics, sessionId) ?? resolvedRequest
+      );
+    }
+    return applyTileflowAnalyticsRequest(url, request, analytics, sessionId);
+  };
+}
+function applyTileflowAnalyticsRequest(url, request, analytics, sessionId) {
+  const requestUrl = request?.url ?? url;
+  const nextUrl = resolveTileflowAnalyticsRequestUrl(requestUrl, analytics, sessionId);
+  if (!nextUrl) {
+    return request;
+  }
+  return request ? { ...request, url: nextUrl } : { url: nextUrl };
+}
+function isPromiseLike(value) {
+  return Boolean(value && typeof value.then === "function");
+}
+function formatHeight(height) {
+  return typeof height === "number" ? `${height}px` : height;
+}
+function clearMarkers(markerInstances) {
+  for (const marker of markerInstances) {
+    marker.remove();
+  }
+  markerInstances.splice(0);
+}
+export {
+  TileflowMap,
+  index_default as default
+};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@tileflow/vue",
+  "version": "0.1.0-alpha.10",
+  "description": "Vue component 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",
+    "directory": "packages/vue"
+  },
+  "bugs": {
+    "url": "https://github.com/tileflow/tileflow/issues"
+  },
+  "keywords": [
+    "tileflow",
+    "vue",
+    "maps",
+    "maplibre",
+    "tiles"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@tileflow/core": "0.1.0-alpha.10"
+  },
+  "peerDependencies": {
+    "maplibre-gl": ">=5",
+    "vue": ">=3.3"
+  },
+  "devDependencies": {
+    "maplibre-gl": "^5.24.0",
+    "vue": "^3.5.26"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean --external vue --external maplibre-gl",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "tsc -p tsconfig.json --noEmit"
+  }
+}