dbf-mirador 4.3.0-testing3 → 4.3.0-testing4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dbf-mirador",
-  "version": "4.3.0-testing3",
+  "version": "4.3.0-testing4",
   "description": "An open-source, web-based 'multi-up' viewer that supports zoom-pan-rotate functionality, ability to display/compare simple images, and images with annotations.",
   "type": "module",
   "main": "./dist/mirador.min.js",
@@ -85,6 +85,7 @@
     "uuid": "^8.1.0 || ^9.0.0 || ^10.0.0 || ^11.0.0"
   },
   "devDependencies": {
+    "@ckeditor/ckeditor5-react": "~11.0.1",
     "@emotion/react": "^11.10.6",
     "@emotion/styled": "^11.10.6",
     "@eslint/compat": "^2.0.3",
@@ -100,6 +101,8 @@
     "@vitest/coverage-v8": "^4.1.2",
     "@vitest/ui": "^4.1.2",
     "chalk": "^5.3.0",
+    "ckeditor5": "~47.6.1",
+    "dbf-mirador": "file:.",
     "eslint": "^10.0.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-import": "^2.32.0",
@@ -125,7 +128,8 @@
     "vitest-fetch-mock": "^0.4.2"
   },
   "overrides": {
-    "brace-expansion@1": "^1.1.16"
+    "brace-expansion@1": "^1.1.16",
+    "dbf-mirador": "file:."
   },
   "peerDependencies": {
     "@emotion/react": "^11.10.6",

package/src/assets/icons/poi-marker.svg

@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="utf-8"?><!-- Uploaded to: SVG Repo, www.svgrepo.com, Generator: SVG Repo Mixer Tools -->
+<svg width="800px" height="800px" viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="iconify iconify--gis" preserveAspectRatio="xMidYMid meet"><path d="M50.002 0C30.763 0 15 15.718 15 34.902c0 7.432 2.374 14.34 6.392 20.019L45.73 96.994c3.409 4.453 5.675 3.607 8.51-.235l26.843-45.683c.542-.981.967-2.026 1.338-3.092A34.446 34.446 0 0 0 85 34.902C85 15.718 69.24 0 50.002 0zm0 16.354c10.359 0 18.597 8.218 18.597 18.548c0 10.33-8.238 18.544-18.597 18.544c-10.36 0-18.601-8.215-18.601-18.544c0-10.33 8.241-18.548 18.6-18.548z" fill="#000000"></path></svg>

package/src/components/AnnotationsOverlay.jsx

@@ -2,11 +2,12 @@ import { useRef, useEffect, useCallback, useMemo } from 'react';
 import ReactDOM from 'react-dom';
 import PropTypes from 'prop-types';
 import { useDebouncedCallback } from 'use-debounce';
+import partition from 'lodash/partition';
 import sortBy from 'lodash/sortBy';
 import xor from 'lodash/xor';
 import OpenSeadragonCanvasOverlay from '../lib/OpenSeadragonCanvasOverlay';
 import CanvasWorld from '../lib/CanvasWorld';
-import CanvasAnnotationDisplay, { POI_ICON_HEIGHT_PX } from '../lib/CanvasAnnotationDisplay';
+import CanvasAnnotationDisplay, { poiHitTarget } from '../lib/CanvasAnnotationDisplay';
 import { buildPath2D } from '../lib/svgShapesToPath';
 
 /** @private */
@@ -30,10 +31,10 @@ function isAnnotationAtPoint({ canvasWorld, osdCanvasOverlay, viewer }, resource
     // CanvasAnnotationDisplay#pointContext), so its clickable footprint must counter-scale the
     // same way, or the hit region would shrink/grow with the image instead of the icon.
     const zoomRatio = viewportCanvas.viewportToImageZoom(viewer.viewport.getZoom(true));
-    const hitRadius = POI_ICON_HEIGHT_PX / 2 / zoomRatio;
-    const dx = relativeX - x;
-    const dy = relativeY - y;
-    return dx * dx + dy * dy <= hitRadius * hitRadius;
+    const hitTarget = poiHitTarget(x, y, zoomRatio);
+    const dx = relativeX - hitTarget.x;
+    const dy = relativeY - hitTarget.y;
+    return dx * dx + dy * dy <= hitTarget.radius * hitTarget.radius;
   }
 
   if (resource.fragmentSelector) {
@@ -97,30 +98,36 @@ export function AnnotationsOverlay({
   const annotationsToContext = useCallback(
     (renderedAnnotations, currentPalette) => {
       const context = osdCanvasOverlay.context2d;
-      renderedAnnotations.forEach((annotation) => {
-        annotation.resources.forEach((resource) => {
-          const osdCanvasIndex = canvasWorld.canvases.findIndex((canvas) => canvas.id === resource.targetId);
-          if (osdCanvasIndex === -1) return;
-          const viewportCanvas = viewer.world.getItemAt(osdCanvasIndex);
-          if (!viewportCanvas) return;
-          const offset = canvasWorld.offsetByCanvas(resource.targetId);
-          const zoomRatio = viewportCanvas.viewportToImageZoom(viewer.viewport.getZoom(true));
-          const canvasAnnotationDisplay = new CanvasAnnotationDisplay({
-            hovered: hoveredAnnotationIds.includes(resource.id),
-            offset,
-            palette: {
-              ...currentPalette,
-              default: {
-                ...currentPalette.default,
-                ...(!highlightAllAnnotations && currentPalette.hidden),
-              },
+      const resources = renderedAnnotations.flatMap((annotation) => annotation.resources);
+
+      // POI pins always draw last, on top of every other annotation shape on the same canvas -
+      // notably including a Journey's own annotation target (an svg/fragment selector, not a
+      // pointSelector), which would otherwise draw in plain store order and can end up covering
+      // - and stealing clicks from - a POI pin it happens to overlap on screen.
+      const [otherResources, poiResources] = partition(resources, (resource) => !resource.pointSelector);
+
+      [...otherResources, ...poiResources].forEach((resource) => {
+        const osdCanvasIndex = canvasWorld.canvases.findIndex((canvas) => canvas.id === resource.targetId);
+        if (osdCanvasIndex === -1) return;
+        const viewportCanvas = viewer.world.getItemAt(osdCanvasIndex);
+        if (!viewportCanvas) return;
+        const offset = canvasWorld.offsetByCanvas(resource.targetId);
+        const zoomRatio = viewportCanvas.viewportToImageZoom(viewer.viewport.getZoom(true));
+        const canvasAnnotationDisplay = new CanvasAnnotationDisplay({
+          hovered: hoveredAnnotationIds.includes(resource.id),
+          offset,
+          palette: {
+            ...currentPalette,
+            default: {
+              ...currentPalette.default,
+              ...(!highlightAllAnnotations && currentPalette.hidden),
             },
-            resource,
-            selected: selectedAnnotationId === resource.id,
-            zoomRatio,
-          });
-          canvasAnnotationDisplay.toContext(context);
+          },
+          resource,
+          selected: selectedAnnotationId === resource.id,
+          zoomRatio,
         });
+        canvasAnnotationDisplay.toContext(context);
       });
     },
     [osdCanvasOverlay, viewer, canvasWorld, highlightAllAnnotations, hoveredAnnotationIds, selectedAnnotationId],

package/src/components/MapViewer.jsx

@@ -0,0 +1,80 @@
+import { useEffect, useId, useRef } from 'react';
+import PropTypes from 'prop-types';
+import { viewer } from '../init';
+import { poiPreviewPlugins } from '../plugins/poiPreviewPlugin.tsx';
+
+// Hides Mirador's generic multi-window IIIF-viewer chrome (top bar, workspace controls,
+// canvas panel) so a manifest reads as a single interactive map rather than a document
+// viewer, and opens straight onto the annotation sidebar since that's where a map's
+// POIs/journeys live. Exported so callers who need Mirador's raw `viewer()`/`Mirador.viewer()`
+// API (e.g. the integration demo config) can build on the same preset instead of copying it.
+export const defaultMapViewerConfig = {
+  theme: {
+    components: {
+      WindowTopBar: {
+        styleOverrides: {
+          root: {
+            display: 'none',
+          },
+        },
+      },
+    },
+  },
+  window: {
+    defaultSideBarPanel: 'annotations',
+    // Closed by default (issue #410): the left sidebar (annotation list, table of
+    // contents, etc.) is Mirador's own document-viewer chrome, not part of the map UI -
+    // POIs/journeys are opened through the canvas or the poiPreview companion window
+    // instead. `highlightAllAnnotations` still draws markers on the canvas regardless.
+    sideBarOpenByDefault: false,
+    highlightAllAnnotations: true,
+    panels: {
+      canvas: false,
+    },
+  },
+  workspaceControlPanel: {
+    enabled: false,
+  },
+};
+
+/**
+ * Drop-in map renderer: give it a IIIF manifest URL, get Mirador pre-configured to look
+ * and behave like a map instead of a generic multi-window viewer. Wraps `viewer()` so
+ * callers don't need to know Mirador's own instantiation/config API.
+ */
+export function MapViewer({ manifestId }) {
+  const baseId = useId().replace(/:/g, '');
+  const wrapperRef = useRef(null);
+
+  useEffect(() => {
+    const wrapper = wrapperRef.current;
+    if (!wrapper) return undefined;
+
+    const container = document.createElement('div');
+    container.id = `mirador-map-viewer-${baseId}`;
+    container.style.position = 'absolute';
+    container.style.inset = 0;
+    wrapper.appendChild(container);
+
+    const instance = viewer(
+      {
+        ...defaultMapViewerConfig,
+        id: container.id,
+        windows: [{ manifestId }],
+      },
+      poiPreviewPlugins,
+    );
+
+    return () => {
+      instance.unmount();
+      container.remove();
+    };
+  }, [baseId, manifestId]);
+
+  return <div ref={wrapperRef} style={{ height: '100%', position: 'relative', width: '100%' }} />;
+}
+
+MapViewer.propTypes = {
+  /** URL of the IIIF manifest to render as a map. */
+  manifestId: PropTypes.string.isRequired,
+};

package/src/components/index.js

@@ -41,6 +41,7 @@ export * from './ManifestInfo';
 export * from './ManifestListItem';
 export * from './ManifestListItemError';
 export * from './ManifestRelatedLinks';
+export * from './MapViewer';
 export * from './MinimalWindow';
 export * from './MiradorMenuButton';
 export * from './MosaicRenderPreview';

package/src/lib/CanvasAnnotationDisplay.js

@@ -13,13 +13,41 @@ import { buildPath2D } from '../lib/svgShapesToPath';
 const POI_ICON_PATH_D =
   'M50.002 0C30.763 0 15 15.718 15 34.902c0 7.432 2.374 14.34 6.392 20.019L45.73 96.994c3.409 4.453 5.675 3.607 8.51-.235l26.843-45.683c.542-.981.967-2.026 1.338-3.092A34.446 34.446 0 0 0 85 34.902C85 15.718 69.24 0 50.002 0zm0 16.354c10.359 0 18.597 8.218 18.597 18.548c0 10.33-8.238 18.544-18.597 18.544c-10.36 0-18.601-8.215-18.601-18.544c0-10.33 8.241-18.548 18.6-18.548z';
 const POI_ICON_VIEWBOX_SIZE = 100;
-/** The icon's own point (its pin tip), in viewBox units - this is what gets placed exactly on the annotated coordinate, not the icon's bounding-box center. */
-const POI_ICON_TIP = { x: 50, y: 97 };
+/** The icon's own point (its pin tip), in viewBox units - this is what gets placed exactly on the annotated coordinate, not the icon's bounding-box center. Derived from the path's actual lowest point (~50, 100), not just its nearby `L` command endpoint. */
+const POI_ICON_TIP = { x: 50, y: 100 };
 /** Center/radius of the icon's circular head, in viewBox units - where a journey-order badge is drawn, overlapping the icon like a numbered pin. */
 const POI_ICON_HEAD = { x: 50, y: 34.9, radius: 18.6 };
+/** Font size of the journey-order number, relative to POI_ICON_HEAD.radius, so it's bigger than the badge circle would otherwise imply while the circle itself stays the same size. */
+const POI_ICON_HEAD_FONT_SCALE = 1.6;
 const POI_ICON_DEFAULT_FILL = '#1e88e5';
 /** Constant on-screen height (CSS px) for the POI icon, regardless of zoom - counter-scaled the same way this class already counter-scales stroke width (see `lineWidth /= zoomRatio` in svgContext). */
-export const POI_ICON_HEIGHT_PX = 32;
+export const POI_ICON_HEIGHT_PX = 44;
+/**
+ * On-screen radius (CSS px, before counter-scaling by zoomRatio) of a POI marker's
+ * clickable/tappable hit target - deliberately independent of, and larger than, the icon's
+ * visual size (POI_ICON_HEIGHT_PX). The icon tapers to a fine point at its anchor, which is
+ * hard to hit precisely with a mouse and well under the ~44-48px minimum touch target size
+ * recommended for mobile (Apple HIG / Material Design), so the tappable area is deliberately
+ * generous rather than matching the icon's own footprint.
+ */
+export const POI_ICON_HIT_RADIUS_PX = 32;
+
+/**
+ * The on-screen hit-test circle (already counter-scaled by zoomRatio, in the same coordinate
+ * space as a resource's `pointSelector`) for a POI marker anchored at (x, y). Centered on the
+ * icon's round head rather than its pin tip: the tip is the anchor point used for rendering
+ * (see pointContext/POI_ICON_TIP), but it's the least visually prominent, hardest-to-aim-for
+ * part of the icon, so hit-testing there instead of at the head would make the marker harder,
+ * not easier, to hit.
+ */
+export function poiHitTarget(x, y, zoomRatio) {
+  const iconScale = POI_ICON_HEIGHT_PX / zoomRatio / POI_ICON_VIEWBOX_SIZE;
+  return {
+    radius: POI_ICON_HIT_RADIUS_PX / zoomRatio,
+    x: x + (POI_ICON_HEAD.x - POI_ICON_TIP.x) * iconScale,
+    y: y + (POI_ICON_HEAD.y - POI_ICON_TIP.y) * iconScale,
+  };
+}
 
 export default class CanvasAnnotationDisplay {
   /** */
@@ -95,7 +123,7 @@ export default class CanvasAnnotationDisplay {
     this.context.fill();
 
     this.context.fillStyle = this.currentPalette().fillStyle || POI_ICON_DEFAULT_FILL;
-    this.context.font = `bold ${POI_ICON_HEAD.radius}px sans-serif`;
+    this.context.font = `bold ${POI_ICON_HEAD.radius * POI_ICON_HEAD_FONT_SCALE}px sans-serif`;
     this.context.textAlign = 'center';
     this.context.textBaseline = 'middle';
     this.context.fillText(String(order), POI_ICON_HEAD.x, POI_ICON_HEAD.y);

package/src/plugins/poiPreviewPlugin.tsx

@@ -0,0 +1,357 @@
+import { useState, type ComponentType } from 'react';
+import useMediaQuery from '@mui/material/useMediaQuery';
+import { useTheme } from '@mui/material/styles';
+import {
+  ConnectedCompanionWindow as CompanionWindow,
+  addCompanionWindow,
+  getAnnotations,
+  getCompanionWindow,
+  getCompanionWindows,
+  getVisibleCanvases,
+  updateCompanionWindow,
+  // Relative, not `from 'dbf-mirador'`: this file lives inside the dbf-mirador package
+  // itself (unlike its copy in the Strapi maps plugin, a real external consumer), and
+  // there's no self-referencing node_modules link or dist build for the package name to
+  // resolve against during local dev.
+} from '../index';
+
+// A "dumb" way to preview a POI/journey (issue #375): a Mirador companion window plugin,
+// registered alongside dbf-mirador-annotation-editor's own (see MiradorMaeViewer.tsx) via
+// Mirador's `companionWindowKey` mechanism - no core patch needed, just adding this plugin
+// to the same `plugins` array. The actual "Preview" button lives per-row in
+// dbf-mirador-annotation-editor's own CanvasListItem.jsx, right next to Edit/Delete
+// (see that package's own PR for issue #375) - it opens this companion window passing the
+// specific row's id as `annotationid`, the same convention MAE's own 'annotationCreation'
+// companion window already uses for its own Edit button.
+//
+// Journeys (issue #378) get a richer path here: instead of the "dumb" dual-locale dump
+// below, a Journey renders its ordered stops as numbered cards with a single active
+// locale (toggle EN/AR), closer to how the public site will eventually present it. Two
+// pieces of the Figma design are intentionally NOT built here, per the issue author's own
+// follow-up comment saying they "wait more precision": numbered pins drawn on the map
+// canvas itself, and an SVG line joining those pins in journey order.
+
+const POI_PREVIEW_CONTENT_ID = 'mapsPoiPreview';
+
+type TextualAnnotationBody = {
+  purpose: 'identifying' | 'describing';
+  type: 'TextualBody';
+  language: string;
+  value: string;
+};
+
+// Mirrors the maps plugin's `Annotation['dbf:mediaEn']`/`Annotation['dbf:mediaAr']`
+// (issue #377) - one media selection per language, unlike the single, language-agnostic
+// `dbf:media` extension issue #391 briefly introduced.
+type DbfMedia = {
+  source: 'upload' | 'iiif-image' | 'media-item';
+  id: string;
+  title: string | null;
+  mediaType?: string | null;
+  thumbnailUrl: string | null;
+};
+
+type RawAnnotation = {
+  id: string;
+  'dbf:kind'?: 'POI' | 'Journey';
+  'dbf:mediaEn'?: DbfMedia | null;
+  'dbf:mediaAr'?: DbfMedia | null;
+  // A POI's membership in a journey and its position within it - a Journey never lists
+  // its own POIs, membership is always POI -> Journey (see mirador-annotation-editor's
+  // annotationListGrouping.js, which this plugin can't import directly since grouping
+  // isn't part of that package's public API - so the same filter+sort is redone below).
+  'dbf:journey'?: { id: string; order: number } | null;
+  body?: TextualAnnotationBody[];
+};
+
+// Both locales, side by side - see the module comment above: the point of a "dumb" preview
+// is to see everything a poi/journey holds, not to render it the way the public site
+// eventually will for one active language.
+const LOCALES = ['en', 'ar'] as const;
+
+const textBody = (
+  annotation: RawAnnotation,
+  language: string,
+  purpose: 'identifying' | 'describing'
+): string =>
+  annotation.body?.find(
+    (item): item is TextualAnnotationBody =>
+      item.type === 'TextualBody' && item.purpose === purpose && item.language === language
+  )?.value ?? '';
+
+const mediaForLocale = (annotation: RawAnnotation, locale: (typeof LOCALES)[number]): DbfMedia | null | undefined =>
+  locale === 'en' ? annotation['dbf:mediaEn'] : annotation['dbf:mediaAr'];
+
+// A journey's ordered stops, derived the same way the rest of the codebase does: every
+// POI whose `dbf:journey.id` points at this journey, sorted by `dbf:journey.order`.
+export const getOrderedJourneyPois = (items: RawAnnotation[], journeyId: string): RawAnnotation[] =>
+  items
+    .filter(
+      (item): item is RawAnnotation & { 'dbf:journey': { id: string; order: number } } =>
+        item['dbf:kind'] === 'POI' && item['dbf:journey']?.id === journeyId
+    )
+    .sort((a, b) => a['dbf:journey'].order - b['dbf:journey'].order);
+
+const JOURNEY_PREVIEW_LOCALES = ['en', 'ar'] as const;
+type JourneyPreviewLocale = (typeof JOURNEY_PREVIEW_LOCALES)[number];
+
+// Arabic is the only RTL locale this project handles today (mirrors the same check in
+// mirador-annotation-editor's POITemplate.jsx/JourneyTemplate.jsx).
+const isRtlLocale = (locale: string) => locale.toLowerCase().startsWith('ar');
+
+interface JourneyPreviewContentProps {
+  id: string;
+  journey: RawAnnotation;
+  pois: RawAnnotation[];
+  windowId: string;
+}
+
+const JourneyPreviewContent = ({ id, journey, pois, windowId }: JourneyPreviewContentProps) => {
+  const [locale, setLocale] = useState<JourneyPreviewLocale>('en');
+  const journeyTitle = textBody(journey, locale, 'identifying');
+
+  return (
+    <CompanionWindow id={id} title={journeyTitle || 'Journey'} windowId={windowId}>
+      <div dir={isRtlLocale(locale) ? 'rtl' : 'ltr'} style={{ padding: 16 }}>
+        <div style={{ display: 'flex', justifyContent: 'flex-end', gap: 4, marginBottom: 16 }}>
+          {JOURNEY_PREVIEW_LOCALES.map((code) => (
+            <button
+              aria-pressed={locale === code}
+              key={code}
+              onClick={() => setLocale(code)}
+              style={{
+                background: locale === code ? '#333' : 'transparent',
+                border: '1px solid #333',
+                borderRadius: 4,
+                color: locale === code ? '#fff' : '#333',
+                cursor: 'pointer',
+                padding: '4px 12px',
+              }}
+              type="button"
+            >
+              {code.toUpperCase()}
+            </button>
+          ))}
+        </div>
+        {pois.length === 0 && <p>This journey has no stops yet.</p>}
+        {pois.map((poi, index) => {
+          const poiTitle = textBody(poi, locale, 'identifying');
+          const description = textBody(poi, locale, 'describing');
+          const media = mediaForLocale(poi, locale);
+          const isLast = index === pois.length - 1;
+          return (
+            <div key={poi.id} style={{ display: 'flex' }}>
+              <div
+                style={{
+                  alignItems: 'center',
+                  display: 'flex',
+                  flexDirection: 'column',
+                  marginInlineEnd: 16,
+                }}
+              >
+                <span
+                  style={{
+                    alignItems: 'center',
+                    background: '#000',
+                    borderRadius: '50%',
+                    color: '#fff',
+                    display: 'flex',
+                    flexShrink: 0,
+                    fontWeight: 'bold',
+                    height: 28,
+                    justifyContent: 'center',
+                    width: 28,
+                  }}
+                >
+                  {index + 1}
+                </span>
+                {/* A plain vertical stepper line standing in for the map's own dashed
+                    connector line, which is out of scope here - see the module comment. */}
+                {!isLast && <div style={{ background: '#ccc', flex: 1, margin: '4px 0', width: 2 }} />}
+              </div>
+              <div style={{ flex: 1, paddingBottom: isLast ? 0 : 24 }}>
+                <h3 style={{ margin: '0 0 8px' }}>{poiTitle || '—'}</h3>
+                {media?.thumbnailUrl && (
+                  <img
+                    alt={media.title ?? ''}
+                    src={media.thumbnailUrl}
+                    style={{ borderRadius: 8, marginBottom: 8, maxWidth: '100%' }}
+                  />
+                )}
+                {description && (
+                  // eslint-disable-next-line react/no-danger -- description is CKEditor HTML, the same content the public site will eventually render
+                  <div dangerouslySetInnerHTML={{ __html: description }} />
+                )}
+              </div>
+            </div>
+          );
+        })}
+      </div>
+    </CompanionWindow>
+  );
+};
+
+interface PoiPreviewContentProps {
+  annotation: RawAnnotation | null;
+  id: string;
+  windowId: string;
+}
+
+const PoiPreviewContent = ({ annotation, id, windowId }: PoiPreviewContentProps) => (
+  <CompanionWindow id={id} title={annotation?.['dbf:kind'] ?? 'Preview'} windowId={windowId}>
+    <div style={{ padding: 16 }}>
+      {!annotation && <p>This annotation could not be found - it may have been deleted.</p>}
+      {annotation &&
+        LOCALES.map((locale) => {
+          const title = textBody(annotation, locale, 'identifying');
+          const description = textBody(annotation, locale, 'describing');
+          const media = mediaForLocale(annotation, locale);
+          return (
+            <section key={locale} style={{ marginBottom: 24 }}>
+              <h3 style={{ textTransform: 'uppercase' }}>{locale}</h3>
+              <p>
+                <strong>{title || '—'}</strong>
+              </p>
+              {description && (
+                // eslint-disable-next-line react/no-danger -- descriptionEn/Ar is CKEditor HTML, the same content the public site will eventually render
+                <div dangerouslySetInnerHTML={{ __html: description }} />
+              )}
+              {media &&
+                (media.thumbnailUrl ? (
+                  <img alt={media.title ?? ''} src={media.thumbnailUrl} style={{ maxWidth: '100%' }} />
+                ) : (
+                  <p>
+                    {media.title}
+                    {media.mediaType ? ` (${media.mediaType})` : ''}
+                  </p>
+                ))}
+            </section>
+          );
+        })}
+    </div>
+  </CompanionWindow>
+);
+
+interface PreviewContentProps {
+  annotation: RawAnnotation | null;
+  id: string;
+  journeyPois: RawAnnotation[];
+  windowId: string;
+}
+
+const PreviewContent = ({ annotation, id, journeyPois, windowId }: PreviewContentProps) => {
+  if (annotation && annotation['dbf:kind'] === 'Journey') {
+    return <JourneyPreviewContent id={id} journey={annotation} pois={journeyPois} windowId={windowId} />;
+  }
+  return <PoiPreviewContent annotation={annotation} id={id} windowId={windowId} />;
+};
+
+const poiPreviewCompanionWindowPlugin = {
+  component: PreviewContent,
+  companionWindowKey: POI_PREVIEW_CONTENT_ID,
+  mapStateToProps: (state: unknown, { id, windowId }: { id: string; windowId: string }) => {
+    const annotationId = getCompanionWindow(state, { companionWindowId: id })?.annotationid as
+      | string
+      | undefined;
+    const canvasId = getVisibleCanvases(state, { windowId })[0]?.id;
+    const pages: Record<string, { json?: { items?: unknown[] } }> | undefined = canvasId
+      ? getAnnotations(state)[canvasId]
+      : undefined;
+    const items = (pages ? Object.values(pages) : []).flatMap(
+      (page) => (page.json?.items ?? []) as RawAnnotation[]
+    );
+    const annotation = items.find((item) => item.id === annotationId) ?? null;
+    return {
+      annotation,
+      journeyPois:
+        annotation && annotation['dbf:kind'] === 'Journey' ? getOrderedJourneyPois(items, annotation.id) : [],
+    };
+  },
+};
+
+// A canvas annotation resource, as AnnotationsOverlay's own `annotations`/`searchAnnotations`
+// props carry it (see AnnotationItem#pointSelector/#svgSelector) - a POI marker is any resource
+// with a pointSelector (CanvasAnnotationDisplay#pointContext), a Journey's own canvas target is
+// one with an svgSelector (AnnotationsOverlay#isAnnotationAtPoint's own svgSelector branch).
+type AnnotationResourceLike = { id: string; pointSelector?: unknown; svgSelector?: unknown };
+type AnnotationListItem = { resources?: AnnotationResourceLike[] };
+
+interface AnnotationsOverlayTargetProps {
+  annotations?: AnnotationListItem[];
+  searchAnnotations?: AnnotationListItem[];
+  selectAnnotation?: (windowId: string, annotationId: string) => void;
+  windowId: string;
+  [key: string]: unknown;
+}
+
+interface AnnotationsOverlayPoiClickWrapperProps {
+  TargetComponent: ComponentType<Record<string, unknown>>;
+  targetProps: AnnotationsOverlayTargetProps;
+  addCompanionWindow: typeof addCompanionWindow;
+  updateCompanionWindow: typeof updateCompanionWindow;
+  existingPreviewCompanionWindowId?: string;
+}
+
+// Wraps AnnotationsOverlay (the component that owns the OSD canvas-click handler and the
+// select/deselect-annotation dispatch, see AnnotationsOverlay#toggleAnnotation) so that
+// clicking a POI marker OR a Journey's own path on the canvas - not just a row in a list
+// somewhere - opens this same preview companion window a "Preview" button would (issue #375's
+// own follow-up: pins on the map itself; issue #378 extends this to journeys). Re-uses an
+// already-open preview window instead of stacking a new one per click.
+const AnnotationsOverlayPoiClickWrapper = ({
+  TargetComponent,
+  targetProps,
+  addCompanionWindow: dispatchAddCompanionWindow,
+  updateCompanionWindow: dispatchUpdateCompanionWindow,
+  existingPreviewCompanionWindowId,
+}: AnnotationsOverlayPoiClickWrapperProps) => {
+  const { annotations = [], searchAnnotations = [], selectAnnotation } = targetProps;
+
+  const theme = useTheme();
+  // Issue #410: on a phone-width viewport there's no room for a right-hand rail next to
+  // the map, so the POI/journey preview opens as a bottom sheet instead.
+  const isMobile = useMediaQuery(theme.breakpoints.down('sm'));
+  const previewPosition = isMobile ? 'bottom' : 'right';
+
+  const selectAnnotationAndMaybePreview = (clickedWindowId: string, annotationId: string) => {
+    selectAnnotation?.(clickedWindowId, annotationId);
+
+    const resource = [...annotations, ...searchAnnotations]
+      .flatMap((item) => item.resources ?? [])
+      .find((item) => item.id === annotationId);
+
+    // pointSelector => POI pin, svgSelector => a Journey's own canvas target (its path/stops
+    // line) - anything else (e.g. a fragmentSelector) has no preview content, skip it.
+    if (!resource?.pointSelector && !resource?.svgSelector) return;
+
+    if (existingPreviewCompanionWindowId) {
+      dispatchUpdateCompanionWindow(clickedWindowId, existingPreviewCompanionWindowId, {
+        annotationid: annotationId,
+        position: previewPosition,
+      });
+    } else {
+      dispatchAddCompanionWindow(clickedWindowId, {
+        annotationid: annotationId,
+        content: POI_PREVIEW_CONTENT_ID,
+        position: previewPosition,
+      });
+    }
+  };
+
+  return <TargetComponent {...targetProps} selectAnnotation={selectAnnotationAndMaybePreview} />;
+};
+
+const poiPreviewClickPlugin = {
+  target: 'AnnotationsOverlay',
+  mode: 'wrap',
+  component: AnnotationsOverlayPoiClickWrapper,
+  mapStateToProps: (state: unknown, { windowId }: { windowId: string }) => {
+    const existing = Object.values(getCompanionWindows(state) as Record<string, { id: string; windowId: string; content: string | null }>).find(
+      (cw) => cw.windowId === windowId && cw.content === POI_PREVIEW_CONTENT_ID,
+    );
+    return { existingPreviewCompanionWindowId: existing?.id };
+  },
+  mapDispatchToProps: { addCompanionWindow, updateCompanionWindow },
+};
+
+export const poiPreviewPlugins = [poiPreviewCompanionWindowPlugin, poiPreviewClickPlugin];