@12-apps/ui 1.0.0 → 1.3.1

package/src/components/data-display/MapPreview/MapOverlays.tsx

@@ -0,0 +1,68 @@
+import { useTheme } from '@mui/material';
+import type { CSSProperties, FC } from 'react';
+import React from 'react';
+
+import type { HeatmapPoint } from './MapPreview.types';
+
+const OVERLAY_STYLE: CSSProperties = {
+  position: 'absolute',
+  top: 0,
+  left: 0,
+  width: '100%',
+  height: '100%',
+  pointerEvents: 'none',
+  zIndex: 1,
+};
+
+const MAX_HEAT_RADIUS = 30;
+const MAX_HEAT_OPACITY = 0.3;
+const DEGREES_TO_PIXELS = 10;
+
+export interface HeatmapOverlayProps {
+  points: HeatmapPoint[];
+  width: number;
+  height: number;
+}
+
+// Each point's weight drives both its radius and its opacity, so denser areas
+// read hotter where circles overlap.
+export const HeatmapOverlay: FC<HeatmapOverlayProps> = ({ points, width, height }) => {
+  const theme = useTheme();
+
+  if (points.length === 0) return null;
+
+  return (
+    <svg style={OVERLAY_STYLE} viewBox={`0 0 ${width} ${height}`}>
+      {points.map((point, index) => (
+        <circle
+          key={`${point.lat}-${point.lng}-${index}`}
+          cx={width / 2 + point.lng * DEGREES_TO_PIXELS}
+          cy={height / 2 - point.lat * DEGREES_TO_PIXELS}
+          r={MAX_HEAT_RADIUS * point.weight}
+          fill={theme.palette.error.main}
+          opacity={MAX_HEAT_OPACITY * point.weight}
+        />
+      ))}
+    </svg>
+  );
+};
+
+export const RouteOverlay: FC<{ color: string }> = ({ color }) => {
+  const theme = useTheme();
+
+  return (
+    <svg style={OVERLAY_STYLE} viewBox="0 0 100 100">
+      <path
+        d="M 20,20 Q 40,10 50,30 T 80,80"
+        stroke={color || theme.palette.primary.main}
+        strokeWidth="3"
+        fill="none"
+        strokeDasharray="5,5"
+        opacity="0.8"
+      >
+        {/* Marching-ants dashes to suggest direction of travel. */}
+        <animate attributeName="stroke-dashoffset" values="0;10" dur="1s" repeatCount="indefinite" />
+      </path>
+    </svg>
+  );
+};

package/src/components/data-display/MapPreview/MapPreview.constants.ts

@@ -0,0 +1,19 @@
+import type { MapType } from './MapPreview.types';
+
+export const MIN_ZOOM = 1;
+export const MAX_ZOOM = 20;
+export const DEFAULT_ZOOM = 15;
+export const CITY_ZOOM = 12;
+
+// The order the map-type button cycles through.
+export const MAP_TYPES: MapType[] = ['roadmap', 'satellite', 'hybrid', 'terrain'];
+
+// Degrees of movement per pixel dragged — small enough that a drag reads as a
+// nudge rather than a jump.
+export const DRAG_DEGREES_PER_PIXEL = 0.0001;
+
+// Spread of the simulated coordinate change a map click produces.
+export const CLICK_JITTER_DEGREES = 0.001;
+
+export const MARKER_PIXELS_PER_DEGREE = 100;
+export const HEATMAP_VIEWBOX = { width: 800, height: 400 };

package/src/components/data-display/MapPreview/MapPreview.helpers.ts

@@ -0,0 +1,63 @@
+import type { Theme } from '@mui/material';
+import { alpha } from '@mui/material';
+
+import { DEFAULT_ZOOM } from './MapPreview.constants';
+import type { MapPreviewProps } from './MapPreview.types';
+
+type MapDefaultedKeys =
+  | 'markers'
+  | 'marker'
+  | 'height'
+  | 'interactive'
+  | 'zoom'
+  | 'mapType'
+  | 'variant'
+  | 'showControls'
+  | 'showSearch'
+  | 'searchPlaceholder'
+  | 'showRoute'
+  | 'heatmapData'
+  | 'showHeatmap'
+  | 'animated';
+
+export type ResolvedMapPreviewProps = MapPreviewProps &
+  Required<Pick<MapPreviewProps, MapDefaultedKeys>>;
+
+const MAP_PREVIEW_DEFAULTS: Pick<MapPreviewProps, MapDefaultedKeys> = {
+  markers: [],
+  marker: true,
+  height: '400px',
+  interactive: false,
+  zoom: DEFAULT_ZOOM,
+  mapType: 'roadmap',
+  variant: 'default',
+  showControls: true,
+  showSearch: false,
+  searchPlaceholder: 'Search location...',
+  showRoute: false,
+  heatmapData: [],
+  showHeatmap: false,
+  animated: true,
+};
+
+// Strips explicitly-undefined props before the merge, so `prop={undefined}` still
+// falls back to the default exactly as a destructuring default would.
+const definedProps = (props: MapPreviewProps): Partial<MapPreviewProps> =>
+  Object.fromEntries(
+    Object.entries(props).filter(([, value]) => value !== undefined),
+  ) as Partial<MapPreviewProps>;
+
+// Applied as a merge rather than destructuring defaults, which would otherwise
+// put fourteen branches into the component's own complexity budget.
+export const resolveMapPreviewProps = (props: MapPreviewProps): ResolvedMapPreviewProps =>
+  ({ ...MAP_PREVIEW_DEFAULTS, ...definedProps(props) }) as ResolvedMapPreviewProps;
+
+export const glassStyles = (variant: MapPreviewProps['variant'], theme: Theme) =>
+  variant === 'glass'
+    ? {
+        background: alpha(theme.palette.background.paper, 0.7),
+        backdropFilter: 'blur(20px)',
+        WebkitBackdropFilter: 'blur(20px)',
+        border: `1px solid ${alpha(theme.palette.divider, 0.1)}`,
+      }
+    : {};

package/src/components/data-display/MapPreview/MapPreview.hooks.ts

@@ -0,0 +1,265 @@
+import type React from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import { geocode } from './mapProjection';
+import {
+  CITY_ZOOM,
+  CLICK_JITTER_DEGREES,
+  DRAG_DEGREES_PER_PIXEL,
+  MAP_TYPES,
+  MAX_ZOOM,
+  MIN_ZOOM,
+} from './MapPreview.constants';
+import type { LatLng, MapType } from './MapPreview.types';
+
+const ORIGIN = { x: 0, y: 0 };
+
+export const useMapView = ({
+  coordinates,
+  initialZoom,
+  initialMapType,
+}: {
+  coordinates: LatLng;
+  initialZoom: number;
+  initialMapType: MapType;
+}) => {
+  const [zoom, setZoom] = useState(initialZoom);
+  const [mapType, setMapType] = useState<MapType>(initialMapType);
+  const [markerPosition, setMarkerPosition] = useState(coordinates);
+  const [panOffset, setPanOffset] = useState(ORIGIN);
+
+  useEffect(() => {
+    setMarkerPosition(coordinates);
+  }, [coordinates]);
+
+  // Panning is relative to the tile grid, so a zoom change invalidates it.
+  const zoomTo = useCallback((next: number) => {
+    setZoom(next);
+    setPanOffset(ORIGIN);
+  }, []);
+
+  return {
+    zoom,
+    zoomTo,
+    mapType,
+    setMapType,
+    markerPosition,
+    setMarkerPosition,
+    panOffset,
+    setPanOffset,
+  };
+};
+
+export const useMapControls = ({
+  coordinates,
+  zoom,
+  mapType,
+  zoomTo,
+  setMapType,
+  setMarkerPosition,
+  setPanOffset,
+  containerRef,
+}: {
+  coordinates: LatLng;
+  zoom: number;
+  mapType: MapType;
+  zoomTo: (zoom: number) => void;
+  setMapType: (type: MapType) => void;
+  setMarkerPosition: (position: LatLng) => void;
+  setPanOffset: (offset: { x: number; y: number }) => void;
+  containerRef: React.RefObject<HTMLDivElement | null>;
+}) => {
+  const [isFullscreen, setIsFullscreen] = useState(false);
+
+  const handleZoomIn = useCallback(() => zoomTo(Math.min(zoom + 1, MAX_ZOOM)), [zoom, zoomTo]);
+  const handleZoomOut = useCallback(() => zoomTo(Math.max(zoom - 1, MIN_ZOOM)), [zoom, zoomTo]);
+
+  const handleCenter = useCallback(() => {
+    setMarkerPosition({ ...coordinates });
+    setPanOffset(ORIGIN);
+  }, [coordinates, setMarkerPosition, setPanOffset]);
+
+  const handleToggleMapType = useCallback(() => {
+    const nextIndex = (MAP_TYPES.indexOf(mapType) + 1) % MAP_TYPES.length;
+    setMapType(MAP_TYPES[nextIndex] as MapType);
+  }, [mapType, setMapType]);
+
+  const handleToggleFullscreen = useCallback(() => {
+    if (!isFullscreen && containerRef.current) {
+      containerRef.current.requestFullscreen?.();
+    } else if (document.fullscreenElement) {
+      document.exitFullscreen?.();
+    }
+    setIsFullscreen((prev) => !prev);
+  }, [isFullscreen, containerRef]);
+
+  return {
+    isFullscreen,
+    handleZoomIn,
+    handleZoomOut,
+    handleCenter,
+    handleToggleMapType,
+    handleToggleFullscreen,
+  };
+};
+
+interface DragStart {
+  x: number;
+  y: number;
+  lat: number;
+  lng: number;
+}
+
+interface PanStart {
+  x: number;
+  y: number;
+  offsetX: number;
+  offsetY: number;
+}
+
+const isOnMapSurface = (target: HTMLElement): boolean =>
+  target.dataset.testid === 'static-map-view' ||
+  Boolean(target.closest('[data-testid="static-map-view"]'));
+
+const panTo = (event: React.MouseEvent, start: PanStart) => ({
+  x: start.offsetX + (event.clientX - start.x),
+  y: start.offsetY + (event.clientY - start.y),
+});
+
+const dragTo = (event: React.MouseEvent, start: DragStart): LatLng => ({
+  lat: start.lat + (event.clientY - start.y) * DRAG_DEGREES_PER_PIXEL,
+  lng: start.lng + (event.clientX - start.x) * DRAG_DEGREES_PER_PIXEL,
+});
+
+// Shift-drag pans the surface; a plain drag moves the marker.
+export const useMapPointer = ({
+  interactive,
+  markerPosition,
+  panOffset,
+  onMarkerDrag,
+  setMarkerPosition,
+  setPanOffset,
+}: {
+  interactive: boolean;
+  markerPosition: LatLng;
+  panOffset: { x: number; y: number };
+  onMarkerDrag?: (coords: LatLng) => void;
+  setMarkerPosition: (position: LatLng) => void;
+  setPanOffset: (offset: { x: number; y: number }) => void;
+}) => {
+  const [isDragging, setIsDragging] = useState(false);
+  const [isPanning, setIsPanning] = useState(false);
+  const dragStartRef = useRef<DragStart | null>(null);
+  const panStartRef = useRef<PanStart | null>(null);
+
+  const handleMouseDown = useCallback(
+    (event: React.MouseEvent<HTMLDivElement>) => {
+      if (!interactive) return;
+      const { clientX: x, clientY: y } = event;
+
+      if (isOnMapSurface(event.target as HTMLElement) && event.shiftKey) {
+        setIsPanning(true);
+        panStartRef.current = { x, y, offsetX: panOffset.x, offsetY: panOffset.y };
+        return;
+      }
+
+      setIsDragging(true);
+      dragStartRef.current = { x, y, lat: markerPosition.lat, lng: markerPosition.lng };
+    },
+    [interactive, markerPosition, panOffset],
+  );
+
+  const handleMouseMove = useCallback(
+    (event: React.MouseEvent<HTMLDivElement>) => {
+      const panStart = panStartRef.current;
+      if (isPanning && panStart) {
+        setPanOffset(panTo(event, panStart));
+        return;
+      }
+
+      const dragStart = dragStartRef.current;
+      if (!isDragging || !dragStart) return;
+
+      const position = dragTo(event, dragStart);
+      setMarkerPosition(position);
+      onMarkerDrag?.(position);
+    },
+    [isDragging, isPanning, onMarkerDrag, setMarkerPosition, setPanOffset],
+  );
+
+  const handleMouseUp = useCallback(() => {
+    setIsDragging(false);
+    setIsPanning(false);
+    dragStartRef.current = null;
+    panStartRef.current = null;
+  }, []);
+
+  return { isDragging, isPanning, handleMouseDown, handleMouseMove, handleMouseUp };
+};
+
+export const useMapSearch = ({
+  zoomTo,
+  setMarkerPosition,
+}: {
+  zoomTo: (zoom: number) => void;
+  setMarkerPosition: (position: LatLng) => void;
+}) => {
+  const [searchValue, setSearchValue] = useState('');
+  const [isSearching, setIsSearching] = useState(false);
+
+  const handleSearch = useCallback(
+    async (event: React.KeyboardEvent<HTMLInputElement>) => {
+      if (event.key !== 'Enter' || !searchValue) return;
+
+      setIsSearching(true);
+      try {
+        const result = await geocode(searchValue);
+        // An unknown place leaves the map where it is; a production build would
+        // surface an error here.
+        if (!result) return;
+
+        setMarkerPosition({ ...result });
+        zoomTo(CITY_ZOOM);
+      } finally {
+        setIsSearching(false);
+      }
+    },
+    [searchValue, zoomTo, setMarkerPosition],
+  );
+
+  return { searchValue, setSearchValue, isSearching, handleSearch };
+};
+
+export const useMapClick = ({
+  coordinates,
+  interactive,
+  isPanning,
+  onMapClick,
+  onMarkerDrag,
+  setMarkerPosition,
+}: {
+  coordinates: LatLng;
+  interactive: boolean;
+  isPanning: boolean;
+  onMapClick?: (lat: number, lng: number) => void;
+  onMarkerDrag?: (coords: LatLng) => void;
+  setMarkerPosition: (position: LatLng) => void;
+}) =>
+  useCallback(() => {
+    // A pan ends with a click event; that should not also drop a marker.
+    if (isPanning) return;
+
+    // Without a real projection there is nothing to convert a click position
+    // into, so the mock jitters around the centre instead.
+    const coords = {
+      lat: coordinates.lat + (Math.random() - 0.5) * CLICK_JITTER_DEGREES,
+      lng: coordinates.lng + (Math.random() - 0.5) * CLICK_JITTER_DEGREES,
+    };
+
+    onMapClick?.(coords.lat, coords.lng);
+
+    if (interactive && onMarkerDrag) {
+      setMarkerPosition(coords);
+      onMarkerDrag(coords);
+    }
+  }, [coordinates, interactive, isPanning, onMapClick, onMarkerDrag, setMarkerPosition]);

package/src/components/data-display/MapPreview/MapPreview.test.stories.tsx

@@ -1,6 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import React from 'react';
-import { expect, fn, waitFor, within } from 'storybook/test';
+import { expect, fn, userEvent, waitFor, within } from 'storybook/test';
 
 import { MapPreview } from './MapPreview';
 import type { HeatmapPoint,MapMarker } from './MapPreview.types';
@@ -43,7 +43,7 @@ export const BasicInteraction: Story = {
     const canvas = within(canvasElement);
 
     // Wait for map container to render with extended timeout
-    const _mapContainer = await waitFor(
+    await waitFor(
       async () => {
         const container = await canvas.findByTestId('map-preview-container');
         expect(container).toBeInTheDocument();
@@ -93,7 +93,7 @@ export const MarkerInteraction: Story = {
     );
 
     // Test marker renders with extended wait
-    const _marker = await waitFor(
+    await waitFor(
       async () => {
         const markerElement = await canvas.findByTestId('map-marker-0');
         expect(markerElement).toBeInTheDocument();
@@ -117,7 +117,7 @@ export const KeyboardNavigation: Story = {
     const canvas = within(canvasElement);
 
     // Wait for map to render and test container is focusable
-    const _mapContainer = await waitFor(
+    await waitFor(
       async () => {
         const container = await canvas.findByTestId('map-preview-container');
         expect(container).toBeInTheDocument();
@@ -142,7 +142,7 @@ export const ScreenReader: Story = {
     const canvas = within(canvasElement);
 
     // Wait for map and test ARIA labels
-    const _mapContainer = await waitFor(
+    await waitFor(
       async () => {
         const container = await canvas.findByTestId('map-preview-container');
         expect(container).toBeInTheDocument();
@@ -168,7 +168,7 @@ export const FocusManagement: Story = {
     const canvas = within(canvasElement);
 
     // Wait for map and test initial focus
-    const _mapContainer = await waitFor(
+    const mapContainer = await waitFor(
       async () => {
         const container = await canvas.findByTestId('map-preview-container');
         expect(container).toBeInTheDocument();
@@ -177,8 +177,9 @@ export const FocusManagement: Story = {
       { timeout: 10000 }
     );
 
-    mapContainer.focus();
-    expect(mapContainer).toBeInTheDocument();
+    // The container carries tabIndex={0}, so clicking it should focus it.
+    await userEvent.click(mapContainer);
+    await waitFor(() => expect(mapContainer).toHaveFocus());
 
     // Mark test as passed
     const statusElement = document.createElement('div');
@@ -270,10 +271,13 @@ export const Performance: Story = {
   render: () => (
     <MapPreview
       center={defaultCenter}
+      // Spread deterministically around the centre. These were random offsets,
+      // which meant the marker layout — and any snapshot of it — differed on
+      // every run.
       markers={Array.from({ length: 5 }, (_, i) => ({
         position: {
-          lat: defaultCenter.lat + (Math.random() - 0.5) * 0.1,
-          lng: defaultCenter.lng + (Math.random() - 0.5) * 0.1,
+          lat: defaultCenter.lat + (i - 2) * 0.02,
+          lng: defaultCenter.lng + (2 - i) * 0.02,
         },
         title: `Marker ${i + 1}`,
       }))}