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

package/README.md

@@ -40,6 +40,8 @@ const bbox = useMapViewportBbox('main', map)
     selectedPhoto,
     photoCircleColor: '#3b82f6',
     mapFeatureCircleColor: '#94a3b8',
+    beforeId: 'road-label', // optional: draw everything below this layer of your style
+    minZoom: 10, // optional: below this zoom nothing is requested or drawn
   }}
 />
 
@@ -50,9 +52,11 @@ const hits = queryStreetImageryFeatures(event)
   onPhotoSelected={setSelection} onEaseMapToPoint={(lng, lat) => map.easeTo({ center: [lng, lat] })} />
 ```
 
+**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.
 
-Also: `useAllProviderPhotos`, `useProviderPhotos` / `useProviderSequences` / `useProviderMapFeatures`, `usePhotoThumbnails`, `resolveSelectedSequence`, `StreetLevelImageryViewCone`, `useViewerBearing` / `useViewerActions`, `MapillaryPanel`, `PanoramaxPanel`.
+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.
 
 ## Viewpoints and floating viewer
 
@@ -117,9 +121,48 @@ const { data: detections } = useMapillaryImageDetections(photo.photoId, {
 <StreetLevelImageryViewer photo={photo} outlines={detections?.map((d) => ({ id: d.id, outline: d.outline }))} … />
 ```
 
-- Map layers: `filter.mapFeatureValue` limits which signs/objects are drawn (`matchesAnyGroup(SIGN_GROUPS)`).
+- Map layers: `filter.mapFeatureValue` limits which signs/objects are drawn: `signGroupFilter(['parking', 'bike'])` for sign groups, or `matchesAnyGroup(…)`.
 - Suggested views: `useViewSuggestions(viewpoints, { sources: [mapillaryPhotoSource, streetViewPhotoSource] })`.
-- `turnMapillaryViewerTo` / `setMapillaryViewerOutlines` work on a mapillary-js `Viewer` you own.
+- `turnMapillaryViewerTo` / `setMapillaryViewerOutlines` (from `@osm-editor-kit/street-imagery-react/viewer-panels`) work on a mapillary-js `Viewer` you own.
+
+## A selected sign: viewer, bar and map highlight
+
+Keep the selected sign (`featureId`) and its shown photo in your own state or URL:
+
+```tsx
+const { data, shownImage, firstImage } = useSelectedMapillaryFeature({
+  featureId,
+  shownPhotoId, // the photo the viewer shows now
+  minCapturedAt: fromMs, // optional: open the best photo from this time on
+})
+// Open `firstImage` first: showPhoto(targetImageToPhoto(firstImage))
+<MapillaryFeatureBar data={data} shownImage={shownImage} onShow={(image) => showPhoto(targetImageToPhoto(image))} />
+<StreetLevelImageryViewer lookAt={{ lngLat: data.feature.lngLat, outline: shownImage?.outline, value: data.feature.value }} … />
+// On the map, after StreetLevelImagerySourcesAndLayers: the sign's halo and a line from the camera
+<SelectedMapFeatureLayer data={data} shownImage={shownImage} providers={providers} bbox={bbox} zoom={zoom} />
+```
+
+A click on a sign dot: `queryStreetImageryFeatures(event).find((hit) => hit.kind === 'mapFeature')?.featureId`.
+
+## Date filter with a slider
+
+`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
+const { photos } = useAllProviderPhotos(providers, bbox, zoom) // no date: all photos in view
+
+<PhotoDateRangeFilter
+  value={date}
+  onChange={setDate} // on release of a handle, not while dragging
+  capturedAt={photos.map((photo) => photo.capturedAt)} // marks: where photos are
+  yearLines={[1, 2, 3, 4]} // lines with a label; a click shows the last N years
+  recommendedMaxAgeYears={2} // this line is red
+  markers={[{ date: '2024-04-01', label: 'Survey start' }]} // dashed lines for fixed dates
+  dateInputs="collapsed" // exact days: 'collapsed' (default), 'open' or 'none'
+/>
+```
+
+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`.
 
 ## Pick a place on the map to open elsewhere
 

package/dist/MapillaryPanel-FAXVZH37.js

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

package/dist/PanoramaxPanel-BTHEMKYY.js

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

package/dist/StreetLevelImagerySelectionOverlay.d.ts

@@ -15,12 +15,14 @@ export type StreetLevelImagerySelectionOverlayProps = {
     cameraLngLat?: [number, number] | null;
     /** Layer to draw the sequence line below, so photo dots stay on top of it. */
     sequenceBeforeId?: string;
+    /** Id of a layer of the host's style to draw the whole overlay below. */
+    beforeId?: string;
 };
 /**
  * The shown photo on the map, bottom to top: its sequence line (only passed when the provider's
  * own layers are off; else that layer marks it), a filled marker on its photo dot, and — when the camera position differs from the
  * dot — a dashed connector and a pin at the camera position.
  */
-export declare const StreetLevelImagerySelectionOverlay: ({ selectedPhoto, selectedSequence, cameraLngLat, sequenceBeforeId, }: StreetLevelImagerySelectionOverlayProps) => import("react").JSX.Element | null;
+export declare const StreetLevelImagerySelectionOverlay: ({ selectedPhoto, selectedSequence, cameraLngLat, sequenceBeforeId, beforeId, }: StreetLevelImagerySelectionOverlayProps) => import("react").JSX.Element | null;
 /** Resolve sequence geometry for highlight when only photo + fetched sequences are available. */
 export declare const resolveSelectedSequence: (selectedPhoto: NormalizedPhoto | null | undefined, sequences: NormalizedSequence[], sequenceId: string | null | undefined) => NormalizedSequence | null;

package/dist/StreetLevelImagerySourcesAndLayers.d.ts

@@ -41,6 +41,16 @@ export type StreetLevelImagerySourcesAndLayersProps = {
         /** Length of the shown photo's view cone, as a multiple of the per-photo shapes. Default 2.5. */
         viewConeScale?: number;
         mapFeatureCircleColor: DataDrivenPropertyValueSpecification<string>;
+        /**
+         * Id of a layer of the host's style: all layers are drawn below it (e.g. below road names).
+         * The layer must exist when this component mounts. Default: on top of the style.
+         */
+        beforeId?: string;
+        /**
+         * Below this map zoom nothing is requested or drawn. Each provider also has its own minimum
+         * zooms (photos, lines); the higher one counts. Default: only the providers' own.
+         */
+        minZoom?: number;
     };
 };
 export declare const StreetLevelImagerySourcesAndLayers: ({ providers, filter, bbox, zoom, options, }: StreetLevelImagerySourcesAndLayersProps) => import("react").JSX.Element;

package/dist/StreetLevelImageryViewCone.d.ts

@@ -17,5 +17,7 @@ export type StreetLevelImageryViewConeProps = {
     color?: DataDrivenPropertyValueSpecification<string>;
     /** Cone length as a multiple of the per-photo view-direction shapes. Default 2.5. */
     scale?: number;
+    /** Id of a layer of the host's style to draw the cone below. */
+    beforeId?: string;
 };
-export declare const StreetLevelImageryViewCone: ({ selectedPhoto, zoom, viewerPov, color, scale, }: StreetLevelImageryViewConeProps) => import("react").JSX.Element | null;
+export declare const StreetLevelImageryViewCone: ({ selectedPhoto, zoom, viewerPov, color, scale, beforeId, }: StreetLevelImageryViewConeProps) => import("react").JSX.Element | null;

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

@@ -18,6 +18,21 @@ var en = {
     nextPhotoOfView: (label) => `${label} \u2014 click for the next photo`
   },
   unknownDate: "Unknown date",
+  dateFilter: {
+    allDates: "All dates",
+    since: (date) => `Since ${date}`,
+    until: (date) => `Until ${date}`,
+    between: (from, to) => `${from} \u2013 ${to}`,
+    yearsShort: (years) => `${years} y`,
+    lastYears: (years) => years === 1 ? "Show the last year" : `Show the last ${years} years`,
+    recommendedMaxAge: (years) => `Recommended: photos of the last ${years === 1 ? "year" : `${years} years`}`,
+    fromHandle: "Oldest photos to show",
+    toHandle: "Newest photos to show",
+    exactDates: "Exact dates",
+    from: "From",
+    to: "To",
+    photoCount: (count) => count === 1 ? "1 photo" : `${count.toLocaleString("en")} photos`
+  },
   viewpointRole: {
     here: "Here",
     "line-start": "Start",
@@ -59,6 +74,21 @@ var de = {
     nextPhotoOfView: (label) => `${label} \u2014 klicken f\xFCr das n\xE4chste Foto`
   },
   unknownDate: "Datum unbekannt",
+  dateFilter: {
+    allDates: "Alle Daten",
+    since: (date) => `Seit ${date}`,
+    until: (date) => `Bis ${date}`,
+    between: (from, to) => `${from} \u2013 ${to}`,
+    yearsShort: (years) => `${years} J.`,
+    lastYears: (years) => years === 1 ? "Das letzte Jahr zeigen" : `Die letzten ${years} Jahre zeigen`,
+    recommendedMaxAge: (years) => `Empfohlen: Fotos ${years === 1 ? "des letzten Jahres" : `der letzten ${years} Jahre`}`,
+    fromHandle: "\xC4lteste Fotos, die gezeigt werden",
+    toHandle: "Neueste Fotos, die gezeigt werden",
+    exactDates: "Genaue Daten",
+    from: "Von",
+    to: "Bis",
+    photoCount: (count) => count === 1 ? "1 Foto" : `${count.toLocaleString("de")} Fotos`
+  },
   viewpointRole: {
     here: "Hier",
     "line-start": "Anfang",
@@ -95,6 +125,7 @@ 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 },
   compass: overrides.compass?.length === 8 ? overrides.compass : base.compass,

package/dist/{chunk-EQ2JKLGT.js → chunk-KZTMKQT5.js}

@@ -299,6 +299,7 @@ var PanoramaxPanel = ({
             className: "block h-full w-full",
             endpoint: panoramaxApiEndpoint(),
             "url-parameters": "false",
+            widgets: hideLegend ? "false" : void 0,
             picture: photo.photoId,
             sequence: photo.sequenceId ?? void 0
           }

package/dist/{chunk-53RA4OSJ.js → chunk-SGIB7AVC.js}

@@ -211,7 +211,12 @@ var MapillaryPanel = ({
           lngLat: [position.lng, position.lat],
           ...image.creatorUsername ? { creatorName: image.creatorUsername } : {}
         });
-        actions.setPov({ lngLat: [position.lng, position.lat] });
+        const isFlat = image.cameraType !== "spherical" && image.cameraType !== "equirectangular";
+        const compass = image.computedCompassAngle ?? image.compassAngle;
+        actions.setPov({
+          lngLat: [position.lng, position.lat],
+          ...isFlat && compass != null ? { bearing: compass } : {}
+        });
         emitEaseMapToPoint(position.lng, position.lat);
       };
       const flushBearing = () => {

package/dist/filters/PhotoDateRangeFilter.d.ts

@@ -0,0 +1,46 @@
+import { type DateRange } from '@osm-editor-kit/street-imagery';
+/** A fixed date to show in the chart, e.g. the start of a project or of a survey. */
+export type PhotoDateMarker = {
+    /** A day as `YYYY-MM-DD`, or a time (ms). */
+    date: string | number;
+    label: string;
+    /** CSS color of line and label. Default red. */
+    color?: string;
+};
+export type PhotoDateRangeFilterProps = {
+    /** The chosen range, days as `YYYY-MM-DD`. No `from` and no `to`: all dates. */
+    value: DateRange;
+    /** Called when a handle is released, a year label is clicked or a date input changes. */
+    onChange: (range: DateRange) => void;
+    /**
+     * Capture times (ms) of the photos to show as marks above the slider, usually all photos in
+     * view before the date filter. Without it there are no marks.
+     */
+    capturedAt?: Iterable<number | null | undefined>;
+    /** Lines with a label at these ages in years; a click on a label shows that many years. */
+    yearLines?: readonly number[];
+    /** Its line is red; added to `yearLines` when it is not one of them. */
+    recommendedMaxAgeYears?: number;
+    markers?: readonly PhotoDateMarker[];
+    /** Years the slider spans. Default 10. */
+    maxYears?: number;
+    /** Reference time (ms). Default: the time of the first render. */
+    now?: number;
+    /**
+     * The two date inputs for exact days, in sync with the slider: folded away (default), open,
+     * or left out.
+     */
+    dateInputs?: 'collapsed' | 'open' | 'none';
+    /**
+     * The "All dates" action next to the chosen range, which removes both limits. Default true;
+     * without it the user moves both handles to the ends.
+     */
+    allDatesAction?: boolean;
+    className?: string;
+};
+/**
+ * Date filter for photos after iD's photo age slider: one slider with two handles on a scale that
+ * gives recent years more room, marks that show how many photos there are at each time, lines at
+ * whole years, and optional fixed markers. Controlled: `value` in, `onChange` out.
+ */
+export declare const PhotoDateRangeFilter: ({ value, onChange, capturedAt, yearLines, recommendedMaxAgeYears, markers, maxYears, now: nowProp, dateInputs, className, allDatesAction, }: PhotoDateRangeFilterProps) => import("react").JSX.Element;

package/dist/hooks/useProviderData.d.ts

@@ -1,5 +1,10 @@
 import type { Bbox } from '@osm-editor-kit/street-imagery';
 import { type ProviderId } from '@osm-editor-kit/street-imagery';
-export declare const useProviderPhotos: (providerId: ProviderId, bbox: Bbox | null, zoom: number) => import("@tanstack/react-query").UseQueryResult<NoInfer<import("@osm-editor-kit/street-imagery").NormalizedPhoto[]>, Error>;
-export declare const useProviderSequences: (providerId: ProviderId, bbox: Bbox | null, zoom: number) => import("@tanstack/react-query").UseQueryResult<NoInfer<import("@osm-editor-kit/street-imagery").NormalizedSequence[]>, Error>;
-export declare const useProviderMapFeatures: (providerId: ProviderId, bbox: Bbox | null, zoom: number) => import("@tanstack/react-query").UseQueryResult<NoInfer<import("@osm-editor-kit/street-imagery").NormalizedMapFeature[]>, Error>;
+/** Host limit on top of the provider's own minimum zooms: below it nothing is requested. */
+type ProviderDataOptions = {
+    minZoom?: number;
+};
+export declare const useProviderPhotos: (providerId: ProviderId, bbox: Bbox | null, zoom: number, { minZoom }?: ProviderDataOptions) => import("@tanstack/react-query").UseQueryResult<NoInfer<import("@osm-editor-kit/street-imagery").NormalizedPhoto[]>, Error>;
+export declare const useProviderSequences: (providerId: ProviderId, bbox: Bbox | null, zoom: number, { minZoom }?: ProviderDataOptions) => import("@tanstack/react-query").UseQueryResult<NoInfer<import("@osm-editor-kit/street-imagery").NormalizedSequence[]>, Error>;
+export declare const useProviderMapFeatures: (providerId: ProviderId, bbox: Bbox | null, zoom: number, { minZoom }?: ProviderDataOptions) => import("@tanstack/react-query").UseQueryResult<NoInfer<import("@osm-editor-kit/street-imagery").NormalizedMapFeature[]>, Error>;
+export {};

package/dist/i18n/messages.d.ts

@@ -21,6 +21,24 @@ export type StreetImageryMessages = {
     /** Eight compass points, clockwise from north: N, NE, E, SE, S, SW, W, NW. */
     compass: readonly string[];
     unknownDate: string;
+    dateFilter: {
+        allDates: string;
+        /** e.g. "Since 5 Oct 2024". */
+        since: (date: string) => string;
+        until: (date: string) => string;
+        between: (from: string, to: string) => string;
+        /** Short label below a year line, e.g. "2 y". */
+        yearsShort: (years: number) => string;
+        /** Tooltip of a year label; a click shows the photos of the last `years` years. */
+        lastYears: (years: number) => string;
+        recommendedMaxAge: (years: number) => string;
+        fromHandle: string;
+        toHandle: string;
+        exactDates: string;
+        from: string;
+        to: string;
+        photoCount: (count: number) => string;
+    };
     /** e.g. "Start, looking along the street"; `role` is the viewpoint's label. */
     viewDirection: (role: string, kind: ViewDirection['kind']) => string;
 };

package/dist/index.d.ts

@@ -9,21 +9,21 @@ export * from './hooks/useAllProviderPhotos';
 export * from './hooks/useMapViewportBbox';
 export * from './hooks/useProviderData';
 export * from './hooks/usePhotoThumbnails';
-export { MapillaryPanel } from './panels/MapillaryPanel';
-export { PanoramaxPanel } from './panels/PanoramaxPanel';
 export * from './useViewerStore';
 export { FloatingPhotoViewer, FloatingViewerInfoButton, type FloatingPhotoViewerProps, } from './viewpoints/FloatingPhotoViewer';
 export { VIEWPOINT_DEFAULT_COLOR, VIEWPOINT_DIRECTION_LAYER_ID, ViewpointLayer, viewDirectionKeyFromFeatures, type ViewpointLayerProps, } from './viewpoints/ViewpointLayer';
 export { viewSuggestionLabel } from './viewpoints/viewDirectionLabels';
 export * from './viewpoints/useViewpointSessionStore';
 export * from './viewpoints/useViewSuggestions';
-export { mapillaryViewFor, setMapillaryViewerOutlines, turnMapillaryViewerTo, type MapillaryLookAt, type MapillaryViewerOutline, } from './panels/mapillaryLookAt';
+export type { MapillaryLookAt, MapillaryViewerOutline } from './panels/mapillaryLookAt';
 export * from './mapillary/useMapillaryFeatures';
 export { LocationPickOnMap, type LocationPickOnMapProps } from './openers/LocationPickOnMap';
 export * from './openers/useLocationPickStore';
+export { SelectedMapFeatureLayer, type SelectedMapFeatureLayerProps, } from './mapillary/SelectedMapFeatureLayer';
 export { MapillaryFeatureBar, type MapillaryFeatureBarProps } from './mapillary/MapillaryFeatureBar';
 export { MAPILLARY_FEATURE_BAR_LABELS, type MapillaryFeatureBarLabels, } from './mapillary/featureBarLabels';
 export { STREET_IMAGERY_MESSAGES, type StreetImageryMessages } from './i18n/messages';
 export { StreetImageryLocaleProvider, useStreetImageryI18n, type StreetImageryMessageOverrides, } from './i18n/StreetImageryLocaleProvider';
+export { PhotoDateRangeFilter, type PhotoDateMarker, type PhotoDateRangeFilterProps, } from './filters/PhotoDateRangeFilter';
 export { PhotoDate } from './i18n/PhotoDate';
 export { PhotoCount } from './i18n/PhotoCount';