@osm-editor-kit/street-imagery-react 0.1.0-alpha.3 → 0.1.0-alpha.5

package/dist/panels/MapillaryPanel.d.ts

@@ -1,11 +1,23 @@
 import type { NormalizedPhoto } from '@osm-editor-kit/street-imagery';
 import 'mapillary-js/dist/mapillary.css';
 import type { StreetImageryPhotoSelection } from '../types';
+import { type MapillaryLookAt, type MapillaryViewerOutline } from './mapillaryLookAt';
 type MapillaryPanelProps = {
     photo: NormalizedPhoto;
     groupPhotos: NormalizedPhoto[];
     onPhotoSelected: (selection: StreetImageryPhotoSelection) => void;
     onEaseMapToPoint: (lng: number, lat: number) => void;
+    /** Full photo data for each image the viewer shows (incl. native prev/next navigation). */
+    onViewerPhoto?: (photo: NormalizedPhoto) => void;
+    /** 360° photos: turn the view to this map bearing when `photo` opens (e.g. a suggested view). */
+    lookAtBearing?: number | null;
+    /**
+     * Turn (and zoom) the view to a place when `photo` opens: a sign, a traffic light, a junction.
+     * Works for 360° and flat photos; wins over `lookAtBearing`.
+     */
+    lookAt?: MapillaryLookAt | null;
+    /** Outlines to draw in the shown image, e.g. the detections you care about. */
+    outlines?: MapillaryViewerOutline[];
 };
-export declare const MapillaryPanel: ({ photo, onPhotoSelected, onEaseMapToPoint, }: MapillaryPanelProps) => import("react").JSX.Element;
+export declare const MapillaryPanel: ({ photo, onPhotoSelected, onEaseMapToPoint, onViewerPhoto, lookAtBearing, lookAt, outlines, }: MapillaryPanelProps) => import("react").JSX.Element;
 export {};

package/dist/panels/mapillaryLookAt.d.ts

@@ -0,0 +1,41 @@
+import { type LngLat, type TargetShape, type ViewTarget } from '@osm-editor-kit/street-imagery';
+import { type Image, type Viewer } from 'mapillary-js';
+/** A place the Mapillary viewer should turn to: a sign, a traffic light, a junction … */
+export type MapillaryLookAt = {
+    lngLat: LngLat;
+    /** Size and height of the target; decides zoom and vertical position. Default: a traffic sign. */
+    shape?: TargetShape;
+    /** The target's outline in the shown image, if known; it is more exact than the location. */
+    outline?: [number, number][];
+    /**
+     * Mapillary value of the target (`regulatory--bicycles-only--g1`). Without an `outline`, the
+     * image's own detection of this value is used: Mapillary links a map feature to few of its
+     * images, but almost every image has a detection of it. With several, the one nearest to the
+     * computed position wins (the computed position alone can be far off in 360° images).
+     */
+    value?: string;
+    /** Label for the outline drawn around the target. */
+    label?: string;
+};
+export type MapillaryViewerOutline = {
+    id: string;
+    /** Image ("basic") coordinates, `[0, 0]` top left to `[1, 1]` bottom right. */
+    outline: [number, number][];
+    label?: string;
+    /** CSS color number, e.g. `0xffff00`. Default yellow. */
+    color?: number;
+};
+/**
+ * Where the target is in the image: from its outline, else computed from the locations
+ * (360°: the viewer's own projection; flat: a pinhole model). `undefined` when a flat image does
+ * not show the target.
+ */
+export declare const mapillaryViewFor: (viewer: Viewer, image: Image, { lngLat, shape, outline }: MapillaryLookAt) => Promise<ViewTarget | undefined>;
+/**
+ * Turns the viewer to the target. Returns the outline it aimed at (given, or the image's own
+ * detection of `value`), or `null` when it aimed by location; `false` when the shown (flat) image
+ * does not show the target.
+ */
+export declare const turnMapillaryViewerTo: (viewer: Viewer, image: Image, lookAt: MapillaryLookAt) => Promise<MapillaryViewerOutline | null | false>;
+/** Replaces the outlines drawn in the viewer (needs the viewer's `tag` component). */
+export declare const setMapillaryViewerOutlines: (viewer: Viewer, outlines: readonly MapillaryViewerOutline[]) => void;

package/dist/viewpoints/FloatingPhotoViewer.d.ts

@@ -0,0 +1,31 @@
+import type { ViewSuggestion } from '@osm-editor-kit/street-imagery';
+import { type ReactNode } from 'react';
+export type FloatingPhotoViewerProps = {
+    title: ReactNode;
+    /** Suggested views (viewpoint × direction); shown as chips. Empty hides the strip. */
+    suggestions: ViewSuggestion[];
+    activeDirectionKey: string | null;
+    onSelectSuggestion: (suggestion: ViewSuggestion) => void;
+    canGoBack: boolean;
+    canGoForward: boolean;
+    onBack: () => void;
+    onForward: () => void;
+    onClose: () => void;
+    /** Short status line, e.g. "Loading…" or "No photos from the last 2 years". */
+    status?: ReactNode;
+    /** Viewer body (provider panel). */
+    children?: ReactNode;
+    footer?: ReactNode;
+    /** Collapsible list below the footer, e.g. other photos near the click. */
+    drawer?: {
+        label: ReactNode;
+        content: ReactNode;
+    };
+    /** localStorage key for position, width and minimized state. */
+    storageKey?: string;
+};
+/**
+ * Photo viewer box floating over the map. Render inside a positioned (relative) map container.
+ * Drag the header to move, drag the left edge to resize. Keys: Esc closes, [ and ] step history.
+ */
+export declare const FloatingPhotoViewer: ({ title, suggestions, activeDirectionKey, onSelectSuggestion, canGoBack, canGoForward, onBack, onForward, onClose, status, children, footer, drawer, storageKey, }: FloatingPhotoViewerProps) => import("react").JSX.Element;

package/dist/viewpoints/ViewpointLayer.d.ts

@@ -0,0 +1,17 @@
+import { type LngLat, type ViewSuggestion, type Viewpoint } from '@osm-editor-kit/street-imagery';
+import type { MapGeoJSONFeature } from 'maplibre-gl';
+/** Add to `interactiveLayerIds` to make view directions clickable; see `viewDirectionKeyFromFeatures`. */
+export declare const VIEWPOINT_DIRECTION_LAYER_ID = "viewpoint-direction-fill";
+export declare const VIEWPOINT_DEFAULT_COLOR = "#c026d3";
+export type ViewpointLayerProps = {
+    viewpoints: Viewpoint[];
+    suggestions: ViewSuggestion[];
+    activeDirectionKey: string | null;
+    zoom: number;
+    /** Clicked line, drawn below the viewpoints. */
+    line?: LngLat[] | null;
+    color?: string;
+};
+export declare const ViewpointLayer: ({ viewpoints, suggestions, activeDirectionKey, zoom, line, color, }: ViewpointLayerProps) => import("react").JSX.Element;
+/** Direction key of the top-most clicked view direction, if any. */
+export declare const viewDirectionKeyFromFeatures: (features: MapGeoJSONFeature[] | undefined) => string | null;

package/dist/viewpoints/useViewSuggestions.d.ts

@@ -0,0 +1,23 @@
+import { type NormalizedPhoto, type PhotoTypeFilter, type ViewSuggestion, type ViewpointPhotoSource, type Viewpoint } from '@osm-editor-kit/street-imagery';
+export type ViewSuggestionsOptions = {
+    /** Only photos from the last N years. */
+    maxAgeYears?: number;
+    photoTypes?: PhotoTypeFilter[];
+    /** Candidates kept per direction. */
+    limit?: number;
+    /** Extra app filter (e.g. date range), applied before ranking. */
+    filterPhoto?: (photo: NormalizedPhoto) => boolean;
+    /**
+     * Where photos come from; default Mapillary. Pass several to rank across providers, e.g.
+     * `[mapillaryPhotoSource, streetViewPhotoSource]` or your own (Infra3D).
+     */
+    sources?: ViewpointPhotoSource[];
+    enabled?: boolean;
+};
+export type ViewSuggestionsResult = {
+    suggestions: ViewSuggestion[];
+    isLoading: boolean;
+    isError: boolean;
+};
+/** Photos near each viewpoint from all `sources`, ranked per view direction. */
+export declare const useViewSuggestions: (viewpoints: Viewpoint[], { maxAgeYears, photoTypes, limit, filterPhoto, sources, enabled, }?: ViewSuggestionsOptions) => ViewSuggestionsResult;

package/dist/viewpoints/useViewpointSessionStore.d.ts

@@ -0,0 +1,39 @@
+import type { LngLat, NormalizedPhoto, Viewpoint } from '@osm-editor-kit/street-imagery';
+export type ViewpointHistoryEntry = {
+    photo: NormalizedPhoto;
+    /** Suggested view the photo came from; `null` for photos picked by hand. */
+    directionKey: string | null;
+};
+type OpenInput = {
+    viewpoints: Viewpoint[];
+    /** Clicked line, drawn as context on the map. */
+    line?: LngLat[] | null;
+};
+export declare const useViewpointSessionId: () => number;
+export declare const useViewpoints: () => Viewpoint[];
+export declare const useViewpointLine: () => LngLat[] | null;
+export declare const useActiveDirectionKey: () => string | null;
+export declare const useCurrentHistoryEntry: () => ViewpointHistoryEntry;
+export declare const useCanGoBack: () => boolean;
+export declare const useCanGoForward: () => boolean;
+export declare const useViewpointSessionActions: () => {
+    open: (input: OpenInput) => void;
+    /** Show a photo; truncates forward history. No-op when it is already the current photo. */
+    showPhoto: (entry: ViewpointHistoryEntry) => void;
+    back: () => ViewpointHistoryEntry | null;
+    forward: () => ViewpointHistoryEntry | null;
+    close: () => void;
+};
+/** Actions + current entry outside React (event handlers, tests). */
+export declare const getViewpointSession: () => {
+    actions: {
+        open: (input: OpenInput) => void;
+        /** Show a photo; truncates forward history. No-op when it is already the current photo. */
+        showPhoto: (entry: ViewpointHistoryEntry) => void;
+        back: () => ViewpointHistoryEntry | null;
+        forward: () => ViewpointHistoryEntry | null;
+        close: () => void;
+    };
+    current: ViewpointHistoryEntry;
+};
+export {};

package/dist/viewpoints/viewDirectionLabels.d.ts

@@ -0,0 +1,4 @@
+import type { ViewSuggestion, ViewpointRole } from '@osm-editor-kit/street-imagery';
+export declare const viewpointRoleLabel: (role: ViewpointRole) => string;
+/** Short human label, e.g. "Start → forward", "Here · N", "Junction · in". */
+export declare const viewSuggestionLabel: ({ viewpoint, direction }: ViewSuggestion) => string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osm-editor-kit/street-imagery-react",
-  "version": "0.1.0-alpha.3",
+  "version": "0.1.0-alpha.5",
   "description": "React MapLibre layers and photo viewers for street-level imagery providers.",
   "homepage": "https://github.com/osmberlin/street-space-editor/tree/main/packages/street-imagery-react",
   "license": "MIT",
@@ -45,13 +45,13 @@
     "maplibre-gl": "^6.7.0",
     "react": "^19.1.1",
     "react-dom": "^19.1.1",
-    "react-map-gl": "^8.0.4",
+    "react-map-gl": "^8.1.3",
     "tsup": "^8.5.1",
     "typescript": "^7.0.0",
     "zustand": "^5.0.7"
   },
   "peerDependencies": {
-    "@osm-editor-kit/street-imagery": "^0.1.0-alpha.2",
+    "@osm-editor-kit/street-imagery": "^0.1.0-alpha.4",
     "@panoramax/web-viewer": "^5",
     "@tanstack/react-query": "^5",
     "mapillary-js": "^4",

package/dist/MapillaryPanel-QX6NESX7.js

@@ -1,2 +0,0 @@
-export { MapillaryPanel } from './chunk-BS6LPDMY.js';
-import './chunk-25UGGXIE.js';

package/dist/chunk-BS6LPDMY.js

@@ -1,143 +0,0 @@
-import { useViewerActions } from './chunk-25UGGXIE.js';
-import { getStreetImageryConfig } from '@osm-editor-kit/street-imagery';
-import 'mapillary-js/dist/mapillary.css';
-import { Viewer } from 'mapillary-js';
-import { useRef, useEffect } from 'react';
-import { jsx } from 'react/jsx-runtime';
-
-var MapillaryPanel = ({
-  photo,
-  onPhotoSelected,
-  onEaseMapToPoint
-}) => {
-  const containerRef = useRef(null);
-  const viewerRef = useRef(null);
-  const navigableRef = useRef(false);
-  const pendingImageIdRef = useRef(null);
-  const lastViewerPhotoIdRef = useRef(null);
-  const bearingRafRef = useRef(null);
-  const pendingBearingRef = useRef(null);
-  const actions = useViewerActions();
-  const initialPhotoIdRef = useRef(photo.photoId);
-  useEffect(
-    function resetViewerStoreOnProviderChange() {
-      return () => {
-        actions.reset();
-      };
-    },
-    [actions, photo.providerId]
-  );
-  useEffect(
-    function mountMapillaryViewer() {
-      const container = containerRef.current;
-      if (!container) {
-        return;
-      }
-      const viewer = new Viewer({
-        accessToken: getStreetImageryConfig().mapillaryToken,
-        container,
-        imageId: initialPhotoIdRef.current,
-        component: {
-          cover: false,
-          sequence: { visible: true }
-        }
-      });
-      viewerRef.current = viewer;
-      lastViewerPhotoIdRef.current = initialPhotoIdRef.current;
-      const flushPendingMove = () => {
-        const pendingId = pendingImageIdRef.current;
-        if (!pendingId) {
-          return;
-        }
-        pendingImageIdRef.current = null;
-        void viewer.moveTo(pendingId).catch(() => {
-        });
-      };
-      const onNavigable = (event) => {
-        navigableRef.current = event.navigable;
-        if (event.navigable) {
-          flushPendingMove();
-        }
-      };
-      const onImage = (event) => {
-        const { image } = event;
-        lastViewerPhotoIdRef.current = image.id;
-        onPhotoSelected({
-          provider: "mapillary",
-          sequenceId: image.sequenceId,
-          photoId: image.id
-        });
-        const position = image.lngLat ?? image.originalLngLat;
-        if (!position) {
-          return;
-        }
-        actions.setPov({ lngLat: [position.lng, position.lat] });
-        onEaseMapToPoint(position.lng, position.lat);
-      };
-      const flushBearing = () => {
-        bearingRafRef.current = null;
-        if (pendingBearingRef.current != null) {
-          actions.setPov({ bearing: pendingBearingRef.current });
-          pendingBearingRef.current = null;
-        }
-        void viewer.getFieldOfView().then((fov) => {
-          actions.setPov({ hfov: fov });
-        }).catch(() => {
-        });
-      };
-      const onBearing = (event) => {
-        pendingBearingRef.current = event.bearing;
-        if (bearingRafRef.current == null) {
-          bearingRafRef.current = requestAnimationFrame(flushBearing);
-        }
-      };
-      viewer.on("navigable", onNavigable);
-      viewer.on("image", onImage);
-      viewer.on("bearing", onBearing);
-      const resizeObserver = new ResizeObserver(() => {
-        viewer.resize();
-      });
-      resizeObserver.observe(container);
-      return () => {
-        if (bearingRafRef.current != null) {
-          cancelAnimationFrame(bearingRafRef.current);
-          bearingRafRef.current = null;
-        }
-        resizeObserver.disconnect();
-        viewer.off("navigable", onNavigable);
-        viewer.off("image", onImage);
-        viewer.off("bearing", onBearing);
-        viewer.remove();
-        viewerRef.current = null;
-      };
-    },
-    [actions, onEaseMapToPoint, onPhotoSelected]
-  );
-  useEffect(
-    function syncExternalPhotoSelection() {
-      const viewer = viewerRef.current;
-      if (!viewer || photo.photoId === lastViewerPhotoIdRef.current) {
-        return;
-      }
-      actions.reset();
-      lastViewerPhotoIdRef.current = photo.photoId;
-      if (navigableRef.current) {
-        void viewer.moveTo(photo.photoId).catch(() => {
-        });
-      } else {
-        pendingImageIdRef.current = photo.photoId;
-      }
-    },
-    [actions, photo.photoId]
-  );
-  return /* @__PURE__ */ jsx(
-    "div",
-    {
-      ref: containerRef,
-      className: "min-h-48 overflow-hidden rounded-lg border border-slate-200 bg-slate-900",
-      style: { aspectRatio: "4 / 3" }
-    }
-  );
-};
-
-export { MapillaryPanel };