@osm-editor-kit/street-imagery-react 0.1.0-alpha.9 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tobias Jordans / OSM Editor Kit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,18 +1,27 @@
 # `@osm-editor-kit/street-imagery-react`
 
+React and MapLibre layers, hooks and photo viewers for street-level imagery (Mapillary, Panoramax), on top of `@osm-editor-kit/street-imagery`. For apps that show photos on a `react-map-gl` map.
+
 > [!NOTE]
-> This package is an **alpha** release and still under active development. APIs may change; install with the npm `alpha` dist-tag.
+> Claude Opus 5.5 wrote and reviewed the code of this package. [@tordans](https://github.com/tordans) specified what it should do and tested and verified its user-facing behavior.
 
-## What it does
+## Install
+
+```bash
+npm install @osm-editor-kit/street-imagery-react
+```
+
+Peer dependencies to install as well: `@osm-editor-kit/street-imagery`, `react`, `react-dom`, `maplibre-gl`, `react-map-gl`, `@tanstack/react-query`, `zustand`, `mapillary-js`. `@panoramax/web-viewer` is optional (see below). Wrap your app in a TanStack `QueryClientProvider`; the hooks use it.
 
-React + MapLibre UI on top of `@osm-editor-kit/street-imagery`:
+## What it does
 
 - Map sources and layers for photos, sequences, and viewfields
 - Click handling and interactive layer ids
 - TanStack Query hooks to load provider data for the viewport
-- Lazy Mapillary and Panoramax viewer panels
+- Lazy viewer panels: Mapillary and Panoramax photos in one viewer (`mapillary-js`)
 - Helpers for selection, thumbnails, and easing the map to a photo
 - Viewpoints + floating photo viewer: suggested views per direction, history, map layer
+- Date range slider, photo details dialog, look at a place and outline detections, texts in English and German
 
 ## Usage
 
@@ -26,7 +35,8 @@ import {
 } from '@osm-editor-kit/street-imagery-react'
 import { createStreetImageryConfig } from '@osm-editor-kit/street-imagery'
 
-const bbox = useMapViewportBbox('main', map)
+// Inside <Map id="main">: the bbox follows the map
+const bbox = useMapViewportBbox('main')
 
 <StreetLevelImagerySourcesAndLayers
   providers={['mapillary', 'panoramax']}
@@ -54,9 +64,28 @@ const hits = queryStreetImageryFeatures(event)
 
 **Before photos are loaded:** where a provider has own vector tiles with its track lines (Mapillary: zoom 6 to 15), MapLibre reads those itself. Same colours and filters; the lines are not clickable. Zoomed far out these tiles are several MB each in dense areas; set `options.minZoom` to skip them.
 
-**Mapillary:** `createStreetImageryConfig({ mapillaryToken })` or `setStreetImageryConfig` at boot (`@osm-editor-kit/street-imagery`). **Panoramax + Vite:** see `app/vite.config.ts` for the consuming-app setup.
+**Mapillary:** `createStreetImageryConfig({ mapillaryToken })` or `setStreetImageryConfig` at boot (`@osm-editor-kit/street-imagery`). **Panoramax:** nothing to set up, the Mapillary viewer shows its pictures too (see below).
+
+Also: `useAllProviderPhotos`, `useProviderPhotos` / `useProviderSequences` / `useProviderMapFeatures`, `usePhotoThumbnail` / `usePhotoFullUrl`, `resolveSelectedSequence`, `StreetLevelImageryViewCone`, `useViewerBearing` / `useViewerActions`. The panels themselves (`MapillaryPanel`, `PanoramaxPanel`) are in `@osm-editor-kit/street-imagery-react/viewer-panels`; `StreetLevelImageryViewer` loads them on demand, so `mapillary-js` is only loaded when a photo is shown.
+
+### Panoramax in the Mapillary viewer
+
+`PanoramaxPanel` is a `mapillary-js` viewer with a `PanoramaxDataProvider`, which reads the Panoramax API. One viewer engine for both providers: the same arrows, the same view cone on the map, no second engine to load and no build setup.
+
+- A picture opens with its `sd` file (2048 px wide). When you zoom in, the original file is loaded once and the sharp parts are cut from it in the browser.
+- Steps along the sequence work (previous, next, play). The arrows to pictures nearby do not: they need Mapillary's 3D reconstruction.
+- The panel shows creator and licence in a line at the bottom; `hideAttribution` removes it.
+- `PanoramaxDataProvider` is exported from `viewer-panels` for a `mapillary-js` `Viewer` you own: `new Viewer({ container, dataProvider: new PanoramaxDataProvider({ endpoint }), imageId })`.
+
+**Panoramax's own viewer** (`@panoramax/web-viewer`) is still there as an option:
 
-Also: `useAllProviderPhotos`, `useProviderPhotos` / `useProviderSequences` / `useProviderMapFeatures`, `usePhotoThumbnails`, `resolveSelectedSequence`, `StreetLevelImageryViewCone`, `useViewerBearing` / `useViewerActions`. The panels themselves (`MapillaryPanel`, `PanoramaxPanel`) are in `@osm-editor-kit/street-imagery-react/viewer-panels`; `StreetLevelImageryViewer` loads them on demand, so `mapillary-js` and `@panoramax/web-viewer` are only loaded when a photo is shown.
+```tsx
+import { PanoramaxWebViewerPanel } from '@osm-editor-kit/street-imagery-react/panoramax-web-viewer'
+
+<StreetLevelImageryViewer panoramaxPanel={PanoramaxWebViewerPanel} … />
+```
+
+Only then you need `@panoramax/web-viewer` (an optional peer dependency) and its Vite setup: see [`vite.config.ts` of the preview](https://github.com/osm-editor-kit/street-imagery/blob/main/apps/preview/vite.config.ts).
 
 ## Viewpoints and floating viewer
 
@@ -87,6 +116,60 @@ const { suggestions } = useViewSuggestions(viewpoints, { maxAgeYears: 2 })
 Render `FloatingPhotoViewer` inside a positioned map container. Photos from suggestions open in
 `StreetLevelImageryViewer` with `lookAtBearing={suggestion.direction.bearing}`.
 
+A host without suggested views leaves out `suggestions`, `activeDirectionKey` and `onSelectSuggestion`; the chips are then not shown. Its own buttons and links go in `titleActions`. They keep their size next to a long title and do not start a drag.
+
+For a free window over the whole page, use the viewport as container and let the box leave it until a share of it shows:
+
+```tsx
+<FloatingPhotoViewer position="fixed" minVisibleShare={0.2} onClose={close} title="Photo">
+  {viewer}
+</FloatingPhotoViewer>
+```
+
+`position="fixed"` (default `absolute`) needs an ancestor without `transform` or `filter`, and a stacking order that puts the box above the page. `minVisibleShare` (0–1) never lets the box go over the top edge, because the header is what moves it. The limit also holds when the box or the container changes size, and a minimized viewer stays within reach. Without `minVisibleShare` the box keeps 8px from the right and bottom edge.
+
+To ask "who sees this spot" instead of "what looks north here", use `usePhotosLookingAt`: flat photos within `maxDistanceMeters` (50) whose heading points at the place within `maxFlatAngleDeg` (35), and 360° photos within the distance, best first. Each candidate has `bearingToPlace`.
+
+```tsx
+const [place, setPlace] = useState<LngLat | null>(null) // set on map click
+const [index, setIndex] = useState(0)
+const { candidates } = usePhotosLookingAt(place, { maxAgeYears: 2, enabled: place != null })
+const candidate = candidates[index]
+
+{candidate ? (
+  <FloatingPhotoViewer
+    title="Photos of this place"
+    onClose={() => setPlace(null)}
+    step={{
+      onPrevious: index > 0 ? () => setIndex(index - 1) : undefined,
+      onNext: index < candidates.length - 1 ? () => setIndex(index + 1) : undefined,
+      previousLabel: 'Previous photo',
+      nextLabel: 'Next photo',
+    }}
+  >
+    <StreetLevelImageryViewer
+      photo={candidate.photo}
+      lookAtBearing={candidate.bearingToPlace}
+      … />
+  </FloatingPhotoViewer>
+) : null}
+```
+
+The list needs no chips: `step` gives the `<` `>` buttons and Alt + arrow keys. `lookAtBearing` turns Mapillary 360° photos only. The pure ranking is `rankPhotosLookingAt(place, photos, options)` in the core package.
+
+For a link that opens the same photo with the same zoom and pan, keep the view the viewer reports and pass it to `providerExternalLink`:
+
+```tsx
+const [view, setView] = useState<PhotoView | null>(null)
+
+<StreetLevelImageryViewer onViewerView={setView} … />
+<a href={providerExternalLink(photo, view)}>Open on Mapillary</a>
+```
+
+`onViewerView` runs when the view has stopped moving and when the photo changes, not during a drag, for Mapillary (`x`, `y`, `zoom`) and Panoramax (`heading`, `pitch`, `zoom`). A view of another photo is ignored by the link. What a link shows also depends on the size of the window it opens in. Panoramax in the default panel: the viewers differ, so direction and height of the view carry over, not every pixel.
+
+**Styles:** the viewer panels import the CSS of `mapillary-js`, so your bundler must handle CSS imports.
+
 **Tailwind:** components use Tailwind classes. Tailwind does not scan `node_modules`, so add to your CSS:
 
 ```css
@@ -130,6 +213,13 @@ const { data: detections } = useMapillaryImageDetections(photo.photoId, {
 Keep the selected sign (`featureId`) and its shown photo in your own state or URL:
 
 ```tsx
+import { targetImageToPhoto } from '@osm-editor-kit/street-imagery'
+import {
+  MapillaryFeatureBar,
+  SelectedMapFeatureLayer,
+  useSelectedMapillaryFeature,
+} from '@osm-editor-kit/street-imagery-react'
+
 const { data, shownImage, firstImage } = useSelectedMapillaryFeature({
   featureId,
   shownPhotoId, // the photo the viewer shows now
@@ -149,6 +239,8 @@ A click on a sign dot: `queryStreetImageryFeatures(event).find((hit) => hit.kind
 `PhotoDateRangeFilter` is the date filter of iD's photo panel as a controlled component: one slider with two handles on a scale that gives recent years more room. It works on plain `{ from?, to? }` days (`YYYY-MM-DD`), the same `DateRange` the layers take as `filter.date`.
 
 ```tsx
+import { PhotoDateRangeFilter, useAllProviderPhotos } from '@osm-editor-kit/street-imagery-react'
+
 const { photos } = useAllProviderPhotos(providers, bbox, zoom) // no date: all photos in view
 
 <PhotoDateRangeFilter
@@ -162,13 +254,22 @@ const { photos } = useAllProviderPhotos(providers, bbox, zoom) // no date: all p
 />
 ```
 
-A handle at its end means no limit, so the left end also shows photos older than the slider spans (`maxYears`, default 10). The scale itself is in the core package (`dateSliderPosition`, `dateSliderBins`, …) for a host that draws its own chart. The texts are in `messages.dateFilter`.
+A click or tap on the chart moves the nearer handle to that exact place, and a press on the chart can go on as a drag. Handles on the same spot come apart in the direction of the drag. Handles stay separate targets for mouse and touch, at least 44px high and wide, and a vertical swipe on a phone scrolls the page. A handle at its end means no limit, so the left end also shows photos older than the slider spans (`maxYears`, default 10). The scale itself is in the core package (`dateSliderPosition`, `dateSliderBins`, …) for a host that draws its own chart. The texts are in `messages.dateFilter`.
+
+## Language
+
+Texts and dates are English by default. `StreetImageryLocaleProvider` sets `locale` (`'en'` or `'de'`) and can replace single texts with `messages`.
+
+```tsx
+<StreetImageryLocaleProvider locale="de">{children}</StreetImageryLocaleProvider>
+```
 
 ## Pick a place on the map to open elsewhere
 
 A button arms a location opener (see `@osm-editor-kit/street-imagery`), the next map click opens the clicked place in that service and disarms; Escape cancels.
 
 ```tsx
+import { getLocationOpeners } from '@osm-editor-kit/street-imagery'
 import {
   LocationPickOnMap,
   useArmedLocationOpenerId,
@@ -208,3 +309,7 @@ import { PHOTO_DETAILS_LABELS, PhotoDetailsDialog } from '@osm-editor-kit/street
 ```
 
 `viewerPhoto` is what `onViewerPhoto` of the viewer gives (Mapillary, Panoramax).
+
+## License
+
+MIT

package/dist/MapillaryPanel-SOHGB7JA.js

@@ -0,0 +1,3 @@
+export { MapillaryPanel } from './chunk-LZR5SZDS.js';
+import './chunk-XLBFXACK.js';
+import './chunk-GYUS2JVV.js';

package/dist/PanoramaxPanel-5P5LWMRY.js

@@ -0,0 +1,3 @@
+export { PanoramaxPanel } from './chunk-R6BDVYWM.js';
+import './chunk-XLBFXACK.js';
+import './chunk-GYUS2JVV.js';

package/dist/StreetLevelImageryViewer.d.ts

@@ -1,5 +1,7 @@
-import type { NormalizedPhoto } from '@osm-editor-kit/street-imagery';
+import type { NormalizedPhoto, PhotoView } from '@osm-editor-kit/street-imagery';
+import { type ComponentType } from 'react';
 import type { MapillaryLookAt, MapillaryViewerOutline } from './panels/mapillaryLookAt';
+import type { PanoramaxPanelProps } from './panels/PanoramaxPanel';
 import type { StreetImageryPhotoSelection } from './types';
 type StreetLevelImageryViewerProps = {
     photo: NormalizedPhoto;
@@ -8,6 +10,12 @@ type StreetLevelImageryViewerProps = {
     onEaseMapToPoint: (lng: number, lat: number) => void;
     /** Mapillary, Panoramax: full photo data (creator, licence …) for each image the viewer shows. */
     onViewerPhoto?: (photo: NormalizedPhoto) => void;
+    /**
+     * Mapillary, Panoramax: the view inside the shown photo (pan and zoom), after it has stopped
+     * moving and when the photo changes. Pass it to `providerExternalLink` for a link that opens the
+     * same view on the provider's site.
+     */
+    onViewerView?: (view: PhotoView) => void;
     /** Mapillary 360° photos: initial view bearing (e.g. a suggested view direction). */
     lookAtBearing?: number | null;
     /** Mapillary: turn and zoom to a place (sign, traffic light, junction); wins over `lookAtBearing`. */
@@ -15,10 +23,16 @@ type StreetLevelImageryViewerProps = {
     /** Mapillary: outlines to draw in the shown image. */
     outlines?: MapillaryViewerOutline[];
     /**
-     * Hide the viewer's own attribution (Mapillary) or legend (Panoramax); the host must then show
-     * creator and licence itself, from `onViewerPhoto`.
+     * Hide the viewer's own attribution; the host must then show creator and licence itself, from
+     * `onViewerPhoto`.
      */
     hideAttribution?: boolean;
+    /**
+     * Another panel for Panoramax pictures, e.g. `PanoramaxWebViewerPanel` of the
+     * `panoramax-web-viewer` entry (Panoramax's own viewer). Default: the Mapillary viewer shows
+     * them too.
+     */
+    panoramaxPanel?: ComponentType<PanoramaxPanelProps>;
 };
-export declare const StreetLevelImageryViewer: ({ photo, groupPhotos, onPhotoSelected, onEaseMapToPoint, onViewerPhoto, lookAtBearing, lookAt, outlines, hideAttribution, }: StreetLevelImageryViewerProps) => import("react").JSX.Element | null;
+export declare const StreetLevelImageryViewer: ({ photo, groupPhotos, onPhotoSelected, onEaseMapToPoint, onViewerPhoto, onViewerView, lookAtBearing, lookAt, outlines, hideAttribution, panoramaxPanel: PanoramaxPanelOverride, }: StreetLevelImageryViewerProps) => import("react").JSX.Element | null;
 export {};

package/dist/{chunk-6EMFFIL2.js → chunk-3DFVM6VK.js}

@@ -1,3 +1,4 @@
+import { c } from 'react/compiler-runtime';
 import { DEFAULT_STREET_IMAGERY_LOCALE } from '@osm-editor-kit/street-imagery';
 import { createContext, use } from 'react';
 import { jsx } from 'react/jsx-runtime';
@@ -58,7 +59,12 @@ var en = {
     }
   }
 };
-var COMPASS_DE = { N: "Norden", E: "Osten", S: "S\xFCden", W: "Westen" };
+var COMPASS_DE = {
+  N: "Norden",
+  E: "Osten",
+  S: "S\xFCden",
+  W: "Westen"
+};
 var de = {
   viewer: {
     regionLabel: "Fotoansicht",
@@ -125,23 +131,61 @@ var DEFAULT_I18N = {
 var I18nContext = createContext(DEFAULT_I18N);
 var mergeMessages = (base, overrides) => overrides ? {
   unknownDate: overrides.unknownDate ?? base.unknownDate,
-  dateFilter: { ...base.dateFilter, ...overrides.dateFilter },
-  viewer: { ...base.viewer, ...overrides.viewer },
-  viewpointRole: { ...base.viewpointRole, ...overrides.viewpointRole },
+  dateFilter: {
+    ...base.dateFilter,
+    ...overrides.dateFilter
+  },
+  viewer: {
+    ...base.viewer,
+    ...overrides.viewer
+  },
+  viewpointRole: {
+    ...base.viewpointRole,
+    ...overrides.viewpointRole
+  },
   compass: overrides.compass?.length === 8 ? overrides.compass : base.compass,
   viewDirection: overrides.viewDirection ?? base.viewDirection
 } : base;
-var StreetImageryLocaleProvider = ({
-  locale,
-  messages,
-  children
-}) => /* @__PURE__ */ jsx(
-  I18nContext,
-  {
-    value: { locale, messages: mergeMessages(STREET_IMAGERY_MESSAGES[locale], messages) },
+var StreetImageryLocaleProvider = (t0) => {
+  const $ = c(9);
+  const {
+    locale,
+    messages,
     children
+  } = t0;
+  const t1 = STREET_IMAGERY_MESSAGES[locale];
+  let t2;
+  if ($[0] !== messages || $[1] !== t1) {
+    t2 = mergeMessages(t1, messages);
+    $[0] = messages;
+    $[1] = t1;
+    $[2] = t2;
+  } else {
+    t2 = $[2];
+  }
+  let t3;
+  if ($[3] !== locale || $[4] !== t2) {
+    t3 = {
+      locale,
+      messages: t2
+    };
+    $[3] = locale;
+    $[4] = t2;
+    $[5] = t3;
+  } else {
+    t3 = $[5];
   }
-);
+  let t4;
+  if ($[6] !== children || $[7] !== t3) {
+    t4 = /* @__PURE__ */ jsx(I18nContext, { value: t3, children });
+    $[6] = children;
+    $[7] = t3;
+    $[8] = t4;
+  } else {
+    t4 = $[8];
+  }
+  return t4;
+};
 var useStreetImageryI18n = () => use(I18nContext);
 
 export { STREET_IMAGERY_MESSAGES, StreetImageryLocaleProvider, useStreetImageryI18n };

package/dist/{chunk-25UGGXIE.js → chunk-GYUS2JVV.js}

@@ -17,9 +17,29 @@ var useViewerStore = create()((set) => ({
     reset: () => set(initialState)
   }
 }));
-var useViewerBearing = () => useViewerStore((state) => state.bearing);
-var useViewerHfov = () => useViewerStore((state) => state.hfov);
-var useViewerLngLat = () => useViewerStore((state) => state.lngLat);
-var useViewerActions = () => useViewerStore((state) => state.actions);
+var useViewerBearing = () => {
+  return useViewerStore(_temp);
+};
+var useViewerHfov = () => {
+  return useViewerStore(_temp2);
+};
+var useViewerLngLat = () => {
+  return useViewerStore(_temp3);
+};
+var useViewerActions = () => {
+  return useViewerStore(_temp4);
+};
+function _temp(state) {
+  return state.bearing;
+}
+function _temp2(state) {
+  return state.hfov;
+}
+function _temp3(state) {
+  return state.lngLat;
+}
+function _temp4(state) {
+  return state.actions;
+}
 
 export { useViewerActions, useViewerBearing, useViewerHfov, useViewerLngLat };