@12-apps/ui 1.0.0 → 1.3.0

package/src/components/data-display/LoadingState/LoadingState.tsx

@@ -3,100 +3,130 @@ import React from 'react';
 
 import { Skeleton } from '../../layout/Skeleton/Skeleton';
 
+import {
+  makeTestIds,
+  resolveLoadingStateProps,
+  SIZE_MAP,
+  SKELETON_ROW_HEIGHT,
+} from './LoadingState.helpers';
 import type { LoadingStateProps, LoadingStateSize } from './LoadingState.types';
 
-const sizeMap: Record<LoadingStateSize, { spinner: number; text: 'body2' | 'body1' | 'h6' }> = {
-  sm: { spinner: 24, text: 'body2' },
-  md: { spinner: 40, text: 'body1' },
-  lg: { spinner: 56, text: 'h6' },
+interface ViewProps {
+  message?: string;
+  size: LoadingStateSize;
+  skeletonRows: number;
+  className?: string;
+  testIds: ReturnType<typeof makeTestIds>;
+}
+
+const LoadingMessage: React.FC<{
+  message?: string;
+  size: LoadingStateSize;
+  testIds: ViewProps['testIds'];
+  sx?: object;
+}> = ({ message, size, testIds, sx }) =>
+  message ? (
+    <Typography
+      variant={SIZE_MAP[size].text}
+      color="text.secondary"
+      sx={sx}
+      data-testid={testIds.named('message')}
+    >
+      {message}
+    </Typography>
+  ) : null;
+
+const SkeletonView: React.FC<ViewProps> = ({
+  message,
+  size,
+  skeletonRows,
+  className,
+  testIds,
+}) => {
+  const theme = useTheme();
+
+  return (
+    <Box
+      role="status"
+      aria-busy="true"
+      aria-label={message || 'Loading content'}
+      className={className}
+      data-testid={testIds.base}
+      sx={{
+        width: '100%',
+        padding: theme.spacing(3),
+      }}
+    >
+      <Stack spacing={2}>
+        {Array.from({ length: skeletonRows }).map((_, index) => (
+          <Skeleton
+            key={`skeleton-row-${index}`}
+            variant="rectangular"
+            animation="wave"
+            height={SKELETON_ROW_HEIGHT[size]}
+            // The last row is short, so the block reads as a paragraph of text.
+            width={index === skeletonRows - 1 ? '60%' : '100%'}
+            borderRadius={4}
+            data-testid={testIds.optional(`skeleton-${index}`)}
+          />
+        ))}
+      </Stack>
+      <LoadingMessage
+        message={message}
+        size={size}
+        testIds={testIds}
+        sx={{ mt: 2, textAlign: 'center' }}
+      />
+    </Box>
+  );
 };
 
-export const LoadingState: React.FC<LoadingStateProps> = React.memo(
-  ({
-    variant = 'spinner',
+const SpinnerView: React.FC<ViewProps> = ({ message, size, className, testIds }) => {
+  const theme = useTheme();
+
+  return (
+    <Box
+      role="status"
+      aria-busy="true"
+      aria-label={message || 'Loading'}
+      className={className}
+      data-testid={testIds.base}
+      sx={{
+        display: 'flex',
+        flexDirection: 'column',
+        alignItems: 'center',
+        justifyContent: 'center',
+        padding: theme.spacing(6),
+        minHeight: 200,
+        gap: theme.spacing(2),
+      }}
+    >
+      <CircularProgress
+        size={SIZE_MAP[size].spinner}
+        data-testid={testIds.named('spinner')}
+      />
+      <LoadingMessage message={message} size={size} testIds={testIds} />
+    </Box>
+  );
+};
+
+export const LoadingState: React.FC<LoadingStateProps> = React.memo((rawProps) => {
+  const { variant, message, size, skeletonRows, className, dataTestId } =
+    resolveLoadingStateProps(rawProps);
+  const viewProps: ViewProps = {
     message,
-    size = 'md',
-    skeletonRows = 3,
+    size,
+    skeletonRows,
     className,
-    dataTestId,
-  }) => {
-    const theme = useTheme();
-    const sizeConfig = sizeMap[size];
-
-    if (variant === 'skeleton') {
-      return (
-        <Box
-          role="status"
-          aria-busy="true"
-          aria-label={message || 'Loading content'}
-          className={className}
-          data-testid={dataTestId || 'loading-state'}
-          sx={{
-            width: '100%',
-            padding: theme.spacing(3),
-          }}
-        >
-          <Stack spacing={2}>
-            {Array.from({ length: skeletonRows }).map((_, index) => (
-              <Skeleton
-                key={`skeleton-row-${index}`}
-                variant="rectangular"
-                animation="wave"
-                height={size === 'sm' ? 20 : size === 'md' ? 28 : 36}
-                width={index === skeletonRows - 1 ? '60%' : '100%'}
-                borderRadius={4}
-                data-testid={dataTestId ? `${dataTestId}-skeleton-${index}` : undefined}
-              />
-            ))}
-          </Stack>
-          {message && (
-            <Typography
-              variant={sizeConfig.text}
-              color="text.secondary"
-              sx={{ mt: 2, textAlign: 'center' }}
-              data-testid={dataTestId ? `${dataTestId}-message` : 'loading-state-message'}
-            >
-              {message}
-            </Typography>
-          )}
-        </Box>
-      );
-    }
+    testIds: makeTestIds(dataTestId),
+  };
 
-    return (
-      <Box
-        role="status"
-        aria-busy="true"
-        aria-label={message || 'Loading'}
-        className={className}
-        data-testid={dataTestId || 'loading-state'}
-        sx={{
-          display: 'flex',
-          flexDirection: 'column',
-          alignItems: 'center',
-          justifyContent: 'center',
-          padding: theme.spacing(6),
-          minHeight: 200,
-          gap: theme.spacing(2),
-        }}
-      >
-        <CircularProgress
-          size={sizeConfig.spinner}
-          data-testid={dataTestId ? `${dataTestId}-spinner` : 'loading-state-spinner'}
-        />
-        {message && (
-          <Typography
-            variant={sizeConfig.text}
-            color="text.secondary"
-            data-testid={dataTestId ? `${dataTestId}-message` : 'loading-state-message'}
-          >
-            {message}
-          </Typography>
-        )}
-      </Box>
-    );
-  },
-);
+  return variant === 'skeleton' ? (
+    <SkeletonView {...viewProps} />
+  ) : (
+    <SpinnerView {...viewProps} />
+  );
+});
 
 LoadingState.displayName = 'LoadingState';
 

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

@@ -0,0 +1,116 @@
+import FullscreenIcon from '@mui/icons-material/Fullscreen';
+import LayersIcon from '@mui/icons-material/Layers';
+import CenterIcon from '@mui/icons-material/MyLocation';
+import ZoomInIcon from '@mui/icons-material/ZoomIn';
+import ZoomOutIcon from '@mui/icons-material/ZoomOut';
+import { alpha, Box, IconButton, styled, Tooltip } from '@mui/material';
+import type { FC } from 'react';
+import React from 'react';
+
+import { MAX_ZOOM, MIN_ZOOM } from './MapPreview.constants';
+import type { MapType } from './MapPreview.types';
+
+// Kept module-local: the inferred type of a styled() component cannot be named
+// across a module boundary here (TS2742).
+const MapControls = styled(Box)(({ theme }) => ({
+  position: 'absolute',
+  top: theme.spacing(2),
+  right: theme.spacing(2),
+  zIndex: 1,
+  display: 'flex',
+  flexDirection: 'column',
+  gap: theme.spacing(1),
+}));
+
+const ControlButton = styled(IconButton)(({ theme }) => ({
+  background: alpha(theme.palette.background.paper, 0.95),
+  backdropFilter: 'blur(10px)',
+  WebkitBackdropFilter: 'blur(10px)',
+  border: `1px solid ${alpha(theme.palette.divider, 0.2)}`,
+  boxShadow: theme.shadows[2],
+  // Kept clickable while disabled so hover tooltips still work at the limits.
+  pointerEvents: 'auto',
+  '&:hover': {
+    background: theme.palette.background.paper,
+    transform: 'scale(1.05)',
+  },
+  '&:disabled': {
+    opacity: 0.5,
+    pointerEvents: 'auto',
+  },
+}));
+
+export interface MapControlBarProps {
+  zoom: number;
+  mapType: MapType;
+  onZoomIn: () => void;
+  onZoomOut: () => void;
+  onCenter: () => void;
+  onToggleMapType: () => void;
+  onToggleFullscreen: () => void;
+}
+
+export const MapControlBar: FC<MapControlBarProps> = ({
+  zoom,
+  mapType,
+  onZoomIn,
+  onZoomOut,
+  onCenter,
+  onToggleMapType,
+  onToggleFullscreen,
+}) => (
+  <MapControls data-testid="map-controls">
+    <Tooltip title="Zoom in" placement="left">
+      <ControlButton
+        size="small"
+        onClick={onZoomIn}
+        aria-label="Zoom in"
+        data-testid="zoom-in-button"
+        disabled={zoom >= MAX_ZOOM}
+      >
+        <ZoomInIcon fontSize="small" />
+      </ControlButton>
+    </Tooltip>
+    <Tooltip title="Zoom out" placement="left">
+      <ControlButton
+        size="small"
+        onClick={onZoomOut}
+        aria-label="Zoom out"
+        data-testid="zoom-out-button"
+        disabled={zoom <= MIN_ZOOM}
+      >
+        <ZoomOutIcon fontSize="small" />
+      </ControlButton>
+    </Tooltip>
+    <Tooltip title="Center map" placement="left">
+      <ControlButton
+        size="small"
+        onClick={onCenter}
+        aria-label="Center map"
+        data-testid="center-button"
+      >
+        <CenterIcon fontSize="small" />
+      </ControlButton>
+    </Tooltip>
+    <Tooltip title={`Map type: ${mapType}`} placement="left">
+      <ControlButton
+        size="small"
+        onClick={onToggleMapType}
+        aria-label="Change map type"
+        data-testid="map-type-button"
+      >
+        <LayersIcon fontSize="small" />
+      </ControlButton>
+    </Tooltip>
+    <Tooltip title="Toggle fullscreen" placement="left">
+      <ControlButton
+        size="small"
+        onClick={onToggleFullscreen}
+        aria-label="Toggle fullscreen"
+        data-testid="fullscreen-button"
+      >
+        <FullscreenIcon fontSize="small" />
+      </ControlButton>
+    </Tooltip>
+  </MapControls>
+);

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

@@ -0,0 +1,155 @@
+import LocationIcon from '@mui/icons-material/LocationOn';
+import NavigationIcon from '@mui/icons-material/Navigation';
+import PlaceIcon from '@mui/icons-material/Place';
+import { alpha, Box, Typography, useTheme } from '@mui/material';
+import type { FC } from 'react';
+import React from 'react';
+
+import { getScaleDistance } from './mapProjection';
+import { BOUNCE_KEYFRAMES } from './mapSurface';
+
+// Decorative only: these give the mock surface something to look like without
+// standing in for real map data.
+export const MapRoads: FC = () => {
+  const theme = useTheme();
+
+  return (
+    <Box sx={{ position: 'absolute', top: '20%', left: '15%', width: '70%', height: '60%', opacity: 0.2 }}>
+      <svg width="100%" height="100%" style={{ position: 'absolute' }}>
+        <path
+          d="M 10,50 Q 30,30 50,50 T 90,50"
+          stroke={theme.palette.text.secondary}
+          strokeWidth="2"
+          fill="none"
+          opacity="0.3"
+        />
+        <path
+          d="M 50,10 L 50,90"
+          stroke={theme.palette.text.secondary}
+          strokeWidth="1.5"
+          fill="none"
+          opacity="0.3"
+        />
+        <path
+          d="M 20,30 L 80,70"
+          stroke={theme.palette.text.secondary}
+          strokeWidth="1"
+          fill="none"
+          opacity="0.2"
+        />
+      </svg>
+    </Box>
+  );
+};
+
+const DecorativePin: FC<{ top: string; left: string }> = ({ top, left }) => {
+  const theme = useTheme();
+
+  return (
+    <Box sx={{ position: 'absolute', top, left, opacity: 0.6 }}>
+      <PlaceIcon sx={{ fontSize: 20, color: theme.palette.primary.main }} />
+    </Box>
+  );
+};
+
+export const MapDecorativePins: FC = () => (
+  <>
+    <DecorativePin top="30%" left="25%" />
+    <DecorativePin top="65%" left="70%" />
+  </>
+);
+
+export const MapCentreMarker: FC = () => {
+  const theme = useTheme();
+
+  return (
+    <Box
+      data-testid="map-marker"
+      sx={{
+        position: 'absolute',
+        top: '50%',
+        left: '50%',
+        transform: 'translate(-50%, -100%)',
+        zIndex: 2,
+        filter: 'drop-shadow(0 2px 4px rgba(0,0,0,0.3))',
+      }}
+    >
+      <LocationIcon
+        sx={{
+          fontSize: 36,
+          color: theme.palette.error.main,
+          animation: 'bounce 2s infinite',
+          '@keyframes bounce': BOUNCE_KEYFRAMES,
+        }}
+      />
+    </Box>
+  );
+};
+
+export const MapScaleBar: FC<{ zoom: number }> = ({ zoom }) => {
+  const theme = useTheme();
+
+  return (
+    <Box
+      sx={{
+        position: 'absolute',
+        bottom: theme.spacing(2),
+        right: theme.spacing(2),
+        display: 'flex',
+        alignItems: 'center',
+        gap: 0.5,
+        padding: theme.spacing(0.5, 1),
+        background: alpha(theme.palette.background.paper, 0.9),
+        borderRadius: theme.shape.borderRadius,
+        fontSize: '0.75rem',
+        color: theme.palette.text.secondary,
+      }}
+    >
+      <Box
+        sx={{
+          width: 40,
+          height: 2,
+          background: theme.palette.text.secondary,
+          position: 'relative',
+          // The end caps that make the bar read as a measurement.
+          '&::before, &::after': {
+            content: '""',
+            position: 'absolute',
+            width: 2,
+            height: 6,
+            background: theme.palette.text.secondary,
+          },
+          '&::before': { left: 0, top: -2 },
+          '&::after': { right: 0, top: -2 },
+        }}
+      />
+      <Typography variant="caption">{getScaleDistance(zoom)}</Typography>
+    </Box>
+  );
+};
+
+export const MapCompass: FC = () => {
+  const theme = useTheme();
+
+  return (
+    <Box
+      sx={{
+        position: 'absolute',
+        top: theme.spacing(2),
+        left: theme.spacing(2),
+        width: 40,
+        height: 40,
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        background: alpha(theme.palette.background.paper, 0.9),
+        borderRadius: '50%',
+        boxShadow: theme.shadows[2],
+      }}
+    >
+      <NavigationIcon
+        sx={{ fontSize: 24, color: theme.palette.primary.main, transform: 'rotate(-45deg)' }}
+      />
+    </Box>
+  );
+};

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

@@ -0,0 +1,70 @@
+import { useTheme } from '@mui/material';
+import type { FC } from 'react';
+import React from 'react';
+
+import { HEATMAP_VIEWBOX } from './MapPreview.constants';
+import type { ResolvedMapPreviewProps } from './MapPreview.helpers';
+import type { MapType } from './MapPreview.types';
+import { MapControlBar } from './MapControlBar';
+import { HeatmapOverlay, RouteOverlay } from './MapOverlays';
+import { MapSearchBar } from './MapSearchBar';
+
+export interface MapLayersProps {
+  settings: ResolvedMapPreviewProps;
+  zoom: number;
+  mapType: MapType;
+  search: {
+    searchValue: string;
+    isSearching: boolean;
+    setSearchValue: (value: string) => void;
+    handleSearch: (event: React.KeyboardEvent<HTMLInputElement>) => void;
+  };
+  controls: {
+    handleZoomIn: () => void;
+    handleZoomOut: () => void;
+    handleCenter: () => void;
+    handleToggleMapType: () => void;
+    handleToggleFullscreen: () => void;
+  };
+}
+
+// Everything drawn over the map surface that is switched on by a prop.
+export const MapLayers: FC<MapLayersProps> = ({ settings, zoom, mapType, search, controls }) => {
+  const theme = useTheme();
+
+  return (
+    <>
+      {settings.showHeatmap && settings.heatmapData.length > 0 && (
+        <HeatmapOverlay
+          points={settings.heatmapData}
+          width={HEATMAP_VIEWBOX.width}
+          height={HEATMAP_VIEWBOX.height}
+        />
+      )}
+
+      {settings.showRoute && <RouteOverlay color={settings.routeColor || theme.palette.primary.main} />}
+
+      {settings.showSearch && (
+        <MapSearchBar
+          value={search.searchValue}
+          placeholder={settings.searchPlaceholder}
+          isSearching={search.isSearching}
+          onChange={search.setSearchValue}
+          onSubmit={search.handleSearch}
+        />
+      )}
+
+      {settings.showControls && (
+        <MapControlBar
+          zoom={zoom}
+          mapType={mapType}
+          onZoomIn={controls.handleZoomIn}
+          onZoomOut={controls.handleZoomOut}
+          onCenter={controls.handleCenter}
+          onToggleMapType={controls.handleToggleMapType}
+          onToggleFullscreen={controls.handleToggleFullscreen}
+        />
+      )}
+    </>
+  );
+};

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

@@ -0,0 +1,84 @@
+import LocationIcon from '@mui/icons-material/LocationOn';
+import { alpha, Box, styled, Tooltip, Typography, useTheme } from '@mui/material';
+import type { FC } from 'react';
+import React from 'react';
+
+import { MARKER_PIXELS_PER_DEGREE } from './MapPreview.constants';
+import type { LatLng, MapMarker } from './MapPreview.types';
+import { BOUNCE_KEYFRAMES } from './mapSurface';
+
+// Kept module-local: styled() components cannot be exported across a module
+// boundary here without tripping TS2742.
+const CoordinatesDisplay = styled(Box)(({ theme }) => ({
+  position: 'absolute',
+  bottom: theme.spacing(2),
+  left: theme.spacing(2),
+  padding: theme.spacing(1, 1.5),
+  background: alpha(theme.palette.background.paper, 0.95),
+  backdropFilter: 'blur(10px)',
+  WebkitBackdropFilter: 'blur(10px)',
+  border: `1px solid ${alpha(theme.palette.divider, 0.2)}`,
+  borderRadius: theme.shape.borderRadius,
+  zIndex: 1,
+}));
+
+export interface MapMarkersProps {
+  markers: MapMarker[];
+  centre: LatLng;
+  animated: boolean;
+}
+
+// Markers are placed relative to the current centre, so panning moves them with
+// the surface.
+export const MapMarkers: FC<MapMarkersProps> = ({ markers, centre, animated }) => {
+  const theme = useTheme();
+
+  return (
+    <>
+      {markers.map((markerItem, index) => (
+        <Box
+          key={`${markerItem.position.lat}-${markerItem.position.lng}-${index}`}
+          data-testid={`map-marker-${index}`}
+          sx={{
+            position: 'absolute',
+            top: '50%',
+            left: '50%',
+            transform: `translate(
+              ${(markerItem.position.lng - centre.lng) * MARKER_PIXELS_PER_DEGREE}px,
+              ${-(markerItem.position.lat - centre.lat) * MARKER_PIXELS_PER_DEGREE}px
+            )`,
+            zIndex: 3,
+            cursor: markerItem.onClick ? 'pointer' : 'default',
+          }}
+          onClick={markerItem.onClick}
+          title={markerItem.title}
+        >
+          <Tooltip title={markerItem.description || markerItem.title || ''}>
+            <LocationIcon
+              sx={{
+                fontSize: 32,
+                color: theme.palette.error.main,
+                filter: 'drop-shadow(0 2px 4px rgba(0,0,0,0.3))',
+                animation: animated ? 'bounce 2s infinite' : 'none',
+                '@keyframes bounce': BOUNCE_KEYFRAMES,
+              }}
+            />
+          </Tooltip>
+        </Box>
+      ))}
+    </>
+  );
+};
+
+export const MapCoordinates: FC<{ position: LatLng; zoom: number }> = ({ position, zoom }) => (
+  <CoordinatesDisplay data-testid="coordinates-display">
+    <Typography variant="caption" sx={{ fontFamily: 'monospace' }}>
+      Lat: {position.lat.toFixed(6)}, Lng: {position.lng.toFixed(6)}
+    </Typography>
+    {zoom > 0 && (
+      <Typography variant="caption" sx={{ fontFamily: 'monospace', display: 'block' }}>
+        Zoom: {zoom}
+      </Typography>
+    )}
+  </CoordinatesDisplay>
+);