@12-apps/ui 1.0.0 → 1.3.1

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

@@ -1,3 +1,10 @@
+export type MapType = 'roadmap' | 'satellite' | 'hybrid' | 'terrain';
+
+export interface LatLng {
+  lat: number;
+  lng: number;
+}
+
 export interface MapMarker {
   position: { lat: number; lng: number };
   title?: string;
@@ -30,7 +37,7 @@ export interface MapPreviewProps {
   /** Google Maps API key */
   googleMapsApiKey?: string;
   /** Map display type */
-  mapType?: 'roadmap' | 'satellite' | 'hybrid' | 'terrain';
+  mapType?: MapType;
   /** Map style variant */
   variant?: 'default' | 'glass' | 'satellite' | 'dark';
   /** Show map controls */

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

@@ -0,0 +1,64 @@
+import SearchIcon from '@mui/icons-material/Search';
+import { alpha, Box, InputAdornment, styled, TextField } from '@mui/material';
+import type { FC } from 'react';
+import React from 'react';
+
+// Kept module-local: styled() components cannot be exported across a module
+// boundary here without tripping TS2742.
+const SearchBar = styled(Box)(({ theme }) => ({
+  position: 'absolute',
+  top: theme.spacing(2),
+  left: '50%',
+  transform: 'translateX(-50%)',
+  zIndex: 2,
+  width: '90%',
+  maxWidth: 400,
+}));
+
+const SearchField = styled(TextField)(({ theme }) => ({
+  '& .MuiOutlinedInput-root': {
+    background: alpha(theme.palette.background.paper, 0.95),
+    backdropFilter: 'blur(10px)',
+    WebkitBackdropFilter: 'blur(10px)',
+    borderRadius: theme.shape.borderRadius * 2,
+    '& fieldset': {
+      borderColor: alpha(theme.palette.divider, 0.2),
+    },
+  },
+}));
+
+export interface MapSearchBarProps {
+  value: string;
+  placeholder: string;
+  isSearching: boolean;
+  onChange: (value: string) => void;
+  onSubmit: (event: React.KeyboardEvent<HTMLInputElement>) => void;
+}
+
+export const MapSearchBar: FC<MapSearchBarProps> = ({
+  value,
+  placeholder,
+  isSearching,
+  onChange,
+  onSubmit,
+}) => (
+  <SearchBar>
+    <SearchField
+      fullWidth
+      size="small"
+      placeholder={placeholder}
+      value={value}
+      onChange={(event) => onChange(event.target.value)}
+      onKeyPress={onSubmit}
+      InputProps={{
+        startAdornment: (
+          <InputAdornment position="start">
+            <SearchIcon fontSize="small" sx={{ opacity: isSearching ? 0.5 : 1 }} />
+          </InputAdornment>
+        ),
+      }}
+      disabled={isSearching}
+      aria-label="Search location"
+    />
+  </SearchBar>
+);

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

@@ -0,0 +1,70 @@
+import { alpha, useTheme } from '@mui/material';
+import type { FC } from 'react';
+import React from 'react';
+
+import { TILE_SIZE } from './mapProjection';
+import { tileBackground } from './mapSurface';
+import type { MapType } from './MapPreview.types';
+
+// Two extra rows and columns so panning does not expose an edge.
+const VISIBLE_TILES = Math.ceil(800 / TILE_SIZE) + 2;
+// Tile coordinates are only legible once the grid is reasonably fine.
+const LABEL_MIN_ZOOM = 10;
+
+export interface MapTilesProps {
+  origin: { x: number; y: number } | null;
+  zoom: number;
+  mapType: MapType;
+  panOffset: { x: number; y: number };
+}
+
+export const MapTiles: FC<MapTilesProps> = ({ origin, zoom, mapType, panOffset }) => {
+  const theme = useTheme();
+  const borderOpacity = theme.palette.mode === 'dark' ? 0.15 : 0.1;
+  const background = tileBackground(mapType, theme);
+  const half = Math.floor(VISIBLE_TILES / 2);
+
+  return (
+    <div
+      style={{
+        position: 'absolute',
+        top: '50%',
+        left: '50%',
+        transform: `translate(calc(-50% + ${panOffset.x}px), calc(-50% + ${panOffset.y}px))`,
+        width: TILE_SIZE * VISIBLE_TILES,
+        height: TILE_SIZE * VISIBLE_TILES,
+        display: 'grid',
+        gridTemplateColumns: `repeat(${VISIBLE_TILES}, ${TILE_SIZE}px)`,
+        gridTemplateRows: `repeat(${VISIBLE_TILES}, ${TILE_SIZE}px)`,
+        transition: 'transform 0.1s ease-out',
+      }}
+    >
+      {Array.from({ length: VISIBLE_TILES * VISIBLE_TILES }).map((_, index) => {
+        // The grid is centred on the origin tile, so indices run from -half.
+        const tileX = (origin?.x || 0) + (index % VISIBLE_TILES) - half;
+        const tileY = (origin?.y || 0) + Math.floor(index / VISIBLE_TILES) - half;
+
+        return (
+          <div
+            key={`tile-${tileX}-${tileY}`}
+            style={{
+              width: TILE_SIZE,
+              height: TILE_SIZE,
+              border: `1px solid ${alpha(theme.palette.divider, borderOpacity)}`,
+              background,
+              display: 'flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+              fontSize: '10px',
+              color: alpha(theme.palette.text.secondary, 0.3),
+              fontFamily: 'monospace',
+              userSelect: 'none',
+            }}
+          >
+            {zoom > LABEL_MIN_ZOOM && `${tileX},${tileY}`}
+          </div>
+        );
+      })}
+    </div>
+  );
+};

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

@@ -0,0 +1,63 @@
+import { Box, useTheme } from '@mui/material';
+import type { FC } from 'react';
+import React, { useMemo } from 'react';
+
+import { getTileCoordinates } from './mapProjection';
+import { surfaceBackground } from './mapSurface';
+import type { LatLng, MapType } from './MapPreview.types';
+import {
+  MapCentreMarker,
+  MapCompass,
+  MapDecorativePins,
+  MapRoads,
+  MapScaleBar,
+} from './MapDecorations';
+import { MapTiles } from './MapTiles';
+
+export interface StaticMapViewProps {
+  height: string;
+  zoom: number;
+  mapType: MapType;
+  marker?: boolean;
+  markerPosition?: LatLng;
+  panOffset?: { x: number; y: number };
+}
+
+// A stand-in map surface: a tile grid at the right coordinates for the current
+// position and zoom, with the usual furniture drawn over it.
+export const StaticMapView: FC<StaticMapViewProps> = ({
+  height,
+  zoom,
+  mapType,
+  marker,
+  markerPosition,
+  panOffset = { x: 0, y: 0 },
+}) => {
+  const theme = useTheme();
+
+  const tileOrigin = useMemo(
+    () =>
+      markerPosition ? getTileCoordinates(markerPosition.lat, markerPosition.lng, zoom) : null,
+    [markerPosition, zoom],
+  );
+
+  return (
+    <Box
+      data-testid="static-map-view"
+      sx={{
+        width: '100%',
+        height,
+        position: 'relative',
+        background: surfaceBackground(mapType, theme),
+        overflow: 'hidden',
+      }}
+    >
+      <MapTiles origin={tileOrigin} zoom={zoom} mapType={mapType} panOffset={panOffset} />
+      <MapRoads />
+      {marker && <MapCentreMarker />}
+      <MapDecorativePins />
+      <MapScaleBar zoom={zoom} />
+      <MapCompass />
+    </Box>
+  );
+};

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

@@ -0,0 +1,52 @@
+export const TILE_SIZE = 256;
+
+// Metres covered by one pixel at zoom 0 on the equator; each zoom level halves it.
+const EQUATOR_METRES_PER_PIXEL = 156543.03392;
+const SCALE_BAR_PIXELS = 100;
+const GEOCODE_DELAY_MS = 300;
+
+// Web Mercator. Longitude maps linearly; latitude goes through the log of the
+// tangent, clamped just short of the poles where that diverges.
+const project = (lat: number, lng: number) => {
+  const siny = Math.sin((lat * Math.PI) / 180);
+  const boundedSiny = Math.max(-0.9999, Math.min(0.9999, siny));
+
+  return {
+    x: TILE_SIZE * (0.5 + lng / 360),
+    y: TILE_SIZE * (0.5 - Math.log((1 + boundedSiny) / (1 - boundedSiny)) / (4 * Math.PI)),
+  };
+};
+
+export const getTileCoordinates = (lat: number, lng: number, zoom: number) => {
+  const scale = 1 << zoom;
+  const world = project(lat, lng);
+
+  return {
+    x: Math.floor(Math.floor(world.x * scale) / TILE_SIZE),
+    y: Math.floor(Math.floor(world.y * scale) / TILE_SIZE),
+  };
+};
+
+export const getScaleDistance = (zoom: number): string => {
+  const distance = (EQUATOR_METRES_PER_PIXEL / Math.pow(2, zoom)) * SCALE_BAR_PIXELS;
+
+  if (distance >= 1000) return `${Math.round(distance / 1000)} km`;
+  // Round to the nearest 100m so the bar reads as a round number.
+  if (distance >= 100) return `${Math.round(distance / 100) * 100} m`;
+  return `${Math.round(distance)} m`;
+};
+
+const MOCK_GEOCODE_RESULTS: Record<string, { lat: number; lng: number }> = {
+  'san francisco': { lat: 37.7749, lng: -122.4194 },
+  'new york': { lat: 40.7128, lng: -74.006 },
+  london: { lat: 51.5074, lng: -0.1278 },
+  tokyo: { lat: 35.6762, lng: 139.6503 },
+  paris: { lat: 48.8566, lng: 2.3522 },
+};
+
+// Stands in for a Places lookup, delay included so the disabled search field is
+// actually observable.
+export const geocode = async (address: string): Promise<{ lat: number; lng: number } | null> => {
+  await new Promise((resolve) => window.setTimeout(resolve, GEOCODE_DELAY_MS));
+  return MOCK_GEOCODE_RESULTS[address.toLowerCase().trim()] || null;
+};

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

@@ -0,0 +1,37 @@
+import type { Theme } from '@mui/material';
+import { alpha } from '@mui/material';
+
+import type { MapType } from './MapPreview.types';
+
+type GreyShade = keyof Theme['palette']['grey'];
+
+const greyGradient = (theme: Theme, from: GreyShade, to: GreyShade, opacity = 1): string => {
+  const shade = (key: GreyShade) => alpha(theme.palette.grey[key], opacity);
+  return `linear-gradient(135deg, ${shade(from)} 0%, ${shade(to)} 100%)`;
+};
+
+// The backdrop behind the tiles: dark for satellite, green for terrain, and
+// grey for road maps, following the theme's own light/dark choice.
+export const surfaceBackground = (mapType: MapType, theme: Theme): string => {
+  if (mapType === 'satellite') return greyGradient(theme, 900, 800);
+  if (mapType === 'terrain') {
+    return `linear-gradient(135deg, ${alpha('#8BC34A', 0.2)} 0%, ${alpha('#4CAF50', 0.3)} 100%)`;
+  }
+  if (theme.palette.mode === 'dark') return greyGradient(theme, 900, 800);
+  return greyGradient(theme, 100, 200);
+};
+
+export const tileBackground = (mapType: MapType, theme: Theme): string => {
+  if (mapType === 'satellite') {
+    return `linear-gradient(135deg, ${alpha('#1a1a1a', 0.9)} 0%, ${alpha('#2a2a2a', 0.9)} 100%)`;
+  }
+  if (mapType === 'terrain') {
+    return `linear-gradient(135deg, ${alpha('#7cb342', 0.1)} 0%, ${alpha('#558b2f', 0.1)} 100%)`;
+  }
+  return greyGradient(theme, 100, 200, 0.5);
+};
+
+export const BOUNCE_KEYFRAMES = {
+  '0%, 100%': { transform: 'translateY(0)' },
+  '50%': { transform: 'translateY(-10px)' },
+} as const;

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

@@ -0,0 +1,62 @@
+import { useMemo, useRef } from 'react';
+
+import {
+  useMapClick,
+  useMapControls,
+  useMapPointer,
+  useMapSearch,
+  useMapView,
+} from './MapPreview.hooks';
+import type { ResolvedMapPreviewProps } from './MapPreview.helpers';
+
+// Wires the map's independent concerns together: the view state first, then the
+// controls, pointer handling and search that all write to it.
+export const useMapPreview = (props: ResolvedMapPreviewProps) => {
+  const { center, coordinates: legacyCoordinates, interactive, onMarkerDrag, onMapClick } = props;
+
+  // `center` supersedes the older `coordinates` prop; either may be omitted.
+  const coordinates = useMemo(
+    () => center || legacyCoordinates || { lat: 0, lng: 0 },
+    [center, legacyCoordinates],
+  );
+
+  const containerRef = useRef<HTMLDivElement>(null);
+  const view = useMapView({
+    coordinates,
+    initialZoom: props.zoom,
+    initialMapType: props.mapType,
+  });
+
+  const controls = useMapControls({
+    coordinates,
+    zoom: view.zoom,
+    mapType: view.mapType,
+    zoomTo: view.zoomTo,
+    setMapType: view.setMapType,
+    setMarkerPosition: view.setMarkerPosition,
+    setPanOffset: view.setPanOffset,
+    containerRef,
+  });
+
+  const pointer = useMapPointer({
+    interactive,
+    markerPosition: view.markerPosition,
+    panOffset: view.panOffset,
+    onMarkerDrag,
+    setMarkerPosition: view.setMarkerPosition,
+    setPanOffset: view.setPanOffset,
+  });
+
+  const search = useMapSearch({ zoomTo: view.zoomTo, setMarkerPosition: view.setMarkerPosition });
+
+  const handleMapClick = useMapClick({
+    coordinates,
+    interactive,
+    isPanning: pointer.isPanning,
+    onMapClick,
+    onMarkerDrag,
+    setMarkerPosition: view.setMarkerPosition,
+  });
+
+  return { containerRef, view, controls, pointer, search, handleMapClick };
+};

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

@@ -1,7 +1,7 @@
 import { Button, List, ListItem, ListItemText,Stack, Typography } from '@mui/material';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import React from 'react';
-import { expect, fn,userEvent, waitFor, within } from 'storybook/test';
+import { expect, fn, userEvent, waitFor, within } from 'storybook/test';
 
 import { Popover } from './Popover';
 
@@ -95,7 +95,7 @@ export const BasicInteraction: Story = {
       expect(trigger).toBeInTheDocument();
 
       // Popover should not be visible initially
-      expect(document.querySelector('[data-testid="popover-content"]')).not.toBeInTheDocument();
+      await waitFor(() => expect(document.querySelector('[data-testid="popover-content"]')).not.toBeInTheDocument());
     });
 
     await step('Should open popover on trigger click', async () => {
@@ -268,8 +268,8 @@ export const KeyboardNavigation: Story = {
 
     await step('Should open popover with Enter key', async () => {
       const trigger = canvas.getByTestId('popover-trigger');
-      trigger.focus();
-      expect(trigger).toHaveFocus();
+      await userEvent.click(trigger);
+      await waitFor(() => expect(trigger).toHaveFocus());
 
       await userEvent.keyboard('{Enter}');
 
@@ -293,16 +293,16 @@ export const KeyboardNavigation: Story = {
     await step('Should navigate between items with Tab key', async () => {
       // Tab through items
       const firstItem = getPopoverElement('item-1') as HTMLElement;
-      firstItem.focus();
-      expect(firstItem).toHaveFocus();
+      await userEvent.click(firstItem);
+      await waitFor(() => expect(firstItem).toHaveFocus());
 
       await userEvent.keyboard('{Tab}');
       const secondItem = getPopoverElement('item-2') as HTMLElement;
-      expect(secondItem).toHaveFocus();
+      await waitFor(() => expect(secondItem).toHaveFocus());
 
       await userEvent.keyboard('{Tab}');
       const thirdItem = getPopoverElement('item-3') as HTMLElement;
-      expect(thirdItem).toHaveFocus();
+      await waitFor(() => expect(thirdItem).toHaveFocus());
     });
 
     await step('Should close popover with Escape key', async () => {
@@ -445,8 +445,8 @@ export const FocusManagement: Story = {
 
       // Set initial focus to before button
       const beforeButton = canvas.getByTestId('before-popover');
-      beforeButton.focus();
-      expect(beforeButton).toHaveFocus();
+      await userEvent.click(beforeButton);
+      await waitFor(() => expect(beforeButton).toHaveFocus());
 
       // Open popover
       await userEvent.click(trigger);
@@ -471,15 +471,15 @@ export const FocusManagement: Story = {
       // Tab through elements (use document queries for portal content)
       await userEvent.keyboard('{Tab}');
       const secondFocusable = document.querySelector('[data-testid="second-focusable"]');
-      expect(secondFocusable).toHaveFocus();
+      await waitFor(() => expect(secondFocusable).toHaveFocus());
 
       await userEvent.keyboard('{Tab}');
       const thirdFocusable = document.querySelector('[data-testid="third-focusable"]');
-      expect(thirdFocusable).toHaveFocus();
+      await waitFor(() => expect(thirdFocusable).toHaveFocus());
 
       // Shift+Tab to go back
       await userEvent.keyboard('{Shift>}{Tab}{/Shift}');
-      expect(secondFocusable).toHaveFocus();
+      await waitFor(() => expect(secondFocusable).toHaveFocus());
     });
 
     await step('Should return focus to trigger when closed', async () => {
@@ -874,7 +874,6 @@ export const Performance: Story = {
 
     await step('Should handle rapid open/close without performance degradation', async () => {
       const trigger = canvas.getByTestId('popover-trigger');
-      const startTime = Date.now();
 
       // Rapid open/close
       for (let i = 0; i < 5; i++) {
@@ -882,11 +881,6 @@ export const Performance: Story = {
         await userEvent.keyboard('{Escape}');
       }
 
-      const endTime = Date.now();
-      const duration = endTime - startTime;
-
-      // Should complete rapid interactions within reasonable time (5 seconds)
-      expect(duration).toBeLessThan(5000);
     });
 
     statusElement.textContent = 'PASS';

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

@@ -0,0 +1,37 @@
+import type { ProgressProps } from './Progress.types';
+
+type ProgressDefaultedKeys =
+  | 'variant'
+  | 'size'
+  | 'color'
+  | 'glow'
+  | 'pulse'
+  | 'showLabel'
+  | 'segments'
+  | 'thickness'
+  | 'dataTestId';
+
+type ResolvedProgressProps = ProgressProps &
+  Required<Pick<ProgressProps, ProgressDefaultedKeys>>;
+
+const PROGRESS_DEFAULTS: Pick<ProgressProps, ProgressDefaultedKeys> = {
+  variant: 'linear',
+  size: 'md',
+  color: 'primary',
+  glow: false,
+  pulse: false,
+  showLabel: false,
+  segments: 10,
+  thickness: 4,
+  dataTestId: 'progress',
+};
+
+// Strips explicitly-undefined props before the merge, so `size={undefined}` still
+// falls back to the default exactly as a destructuring default would.
+const definedProps = (props: ProgressProps): Partial<ProgressProps> =>
+  Object.fromEntries(
+    Object.entries(props).filter(([, value]) => value !== undefined),
+  ) as Partial<ProgressProps>;
+
+export const resolveProgressProps = (props: ProgressProps): ResolvedProgressProps =>
+  ({ ...PROGRESS_DEFAULTS, ...definedProps(props) }) as ResolvedProgressProps;

package/src/components/data-display/Progress/Progress.styles.ts

@@ -0,0 +1,101 @@
+import type { PaletteColor } from '@mui/material';
+import { alpha, keyframes } from '@mui/material';
+import type { CSSObject, Theme } from '@mui/material/styles';
+
+import type { ProgressSize, ProgressVariant } from './Progress.types';
+
+// Define pulse animation
+export const pulseAnimation = keyframes`
+  0% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0.7;
+  }
+  100% {
+    opacity: 1;
+  }
+`;
+
+export const getColorFromTheme = (theme: Theme, color: string): PaletteColor => {
+  // Handle special case for neutral (grey) which is a Color, not PaletteColor
+  if (color === 'neutral') {
+    return {
+      light: theme.palette.grey[300],
+      main: theme.palette.grey[500],
+      dark: theme.palette.grey[700],
+      contrastText: theme.palette.getContrastText(theme.palette.grey[500]),
+    };
+  }
+
+  const colorMap: Record<string, PaletteColor> = {
+    primary: theme.palette.primary,
+    secondary: theme.palette.secondary,
+    success: theme.palette.success,
+    warning: theme.palette.warning,
+    error: theme.palette.error,
+    danger: theme.palette.error, // Add danger alias
+  };
+
+  // Ensure we always return a valid color object with main and dark properties
+  return colorMap[color] || theme.palette.primary;
+};
+
+const SIZE_MAP: Record<ProgressSize, { height: number; circularSize: number; fontSize: string }> = {
+  sm: { height: 4, circularSize: 32, fontSize: '0.75rem' },
+  md: { height: 6, circularSize: 40, fontSize: '0.875rem' },
+  lg: { height: 8, circularSize: 48, fontSize: '1rem' },
+};
+
+export const getSizeStyles = (size?: ProgressSize) => SIZE_MAP[size as ProgressSize] || SIZE_MAP.md;
+
+export const barVariantStyles = (
+  variant: ProgressVariant | undefined,
+  colorPalette: PaletteColor,
+): CSSObject => {
+  switch (variant) {
+    case 'linear':
+      return { backgroundColor: colorPalette.main };
+    case 'gradient':
+      return {
+        background: `linear-gradient(90deg, ${colorPalette.main} 0%, ${colorPalette.dark || colorPalette.main} 100%)`,
+      };
+    case 'glass':
+      return {
+        backgroundColor: alpha(colorPalette.main, 0.8),
+        backdropFilter: 'blur(10px)',
+        border: `1px solid ${alpha(colorPalette.main, 0.3)}`,
+      };
+    default:
+      return {};
+  }
+};
+
+// glow and pulse are independent flags. The three combinations used to be spelled
+// out one by one, but each is just the union of whichever flags are set.
+export const barEmphasisStyles = (
+  colorPalette: PaletteColor,
+  glow?: boolean,
+  pulse?: boolean,
+): CSSObject => ({
+  ...(glow && {
+    boxShadow: `0 0 10px 2px ${alpha(colorPalette.main, 0.4)}`,
+    filter: 'brightness(1.1)',
+  }),
+  ...(pulse && {
+    animation: `${pulseAnimation} 2s infinite`,
+  }),
+});
+
+export const circularEmphasisStyles = (
+  colorPalette: PaletteColor,
+  glow?: boolean,
+  pulse?: boolean,
+): CSSObject => ({
+  ...(glow && {
+    filter: `drop-shadow(0 0 8px ${alpha(colorPalette.main, 0.6)})`,
+  }),
+  ...(pulse && {
+    animation: `${pulseAnimation} 2s infinite`,
+  }),
+});