@12-apps/ui 1.0.0

package/src/components/data-display/MapPreview/MapPreview.md

@@ -0,0 +1,154 @@
+# MapPreview Component
+
+A versatile and interactive map preview component that provides a visual representation of geographic locations with support for markers, routes, heatmaps, and various display modes.
+
+## Purpose
+
+The MapPreview component is designed to display geographic data in an intuitive and interactive way. It supports static map displays, interactive features, multiple markers, search functionality, route visualization, and heatmap overlays. Perfect for location-based applications, delivery tracking, store locators, and geographic data visualization.
+
+## Props
+
+### Core Props
+
+- **center** (`{ lat: number; lng: number }`): Map center coordinates
+- **coordinates** (`{ lat: number; lng: number }`): Legacy coordinates prop (use center instead)
+- **height** (`string`): Map container height (default: '400px')
+- **zoom** (`number`): Initial zoom level 1-20 (default: 15)
+- **googleMapsApiKey** (`string`): Optional Google Maps API key for enhanced features
+
+### Display Props
+
+- **mapType** (`'roadmap' | 'satellite' | 'hybrid' | 'terrain'`): Map display type (default: 'roadmap')
+- **variant** (`'default' | 'glass' | 'satellite' | 'dark'`): Visual style variant (default: 'default')
+- **animated** (`boolean`): Enable smooth animations (default: true)
+- **showControls** (`boolean`): Show zoom and map type controls (default: true)
+
+### Marker Props
+
+- **marker** (`boolean`): Show single marker at center (default: true)
+- **markers** (`MapMarker[]`): Array of markers with custom positions and properties
+  - `position`: Marker coordinates
+  - `title`: Marker tooltip title
+  - `description`: Extended description
+  - `icon`: Custom marker icon
+  - `onClick`: Click handler
+
+### Interactive Props
+
+- **interactive** (`boolean`): Enable user interaction (default: false)
+- **onMarkerDrag** (`(coords: { lat: number; lng: number }) => void`): Marker drag callback
+- **onMapClick** (`(lat: number, lng: number) => void`): Map click callback
+
+### Search Props
+
+- **showSearch** (`boolean`): Display search bar (default: false)
+- **searchPlaceholder** (`string`): Search input placeholder text
+
+### Visualization Props
+
+- **showRoute** (`boolean`): Display route overlay (default: false)
+- **routeColor** (`string`): Custom route line color
+- **showHeatmap** (`boolean`): Display heatmap overlay (default: false)
+- **heatmapData** (`HeatmapPoint[]`): Heatmap data points with weight values
+
+## Usage Examples
+
+### Basic Map Preview
+```tsx
+<MapPreview
+  center={{ lat: 37.7749, lng: -122.4194 }}
+  height="400px"
+  zoom={12}
+/>
+```
+
+### Interactive Map with Multiple Markers
+```tsx
+<MapPreview
+  center={{ lat: 37.7749, lng: -122.4194 }}
+  interactive
+  markers={[
+    {
+      position: { lat: 37.7749, lng: -122.4194 },
+      title: "San Francisco",
+      description: "City by the Bay",
+      onClick: () => console.log("SF clicked")
+    },
+    {
+      position: { lat: 37.7849, lng: -122.4094 },
+      title: "Golden Gate Bridge",
+      description: "Iconic landmark"
+    }
+  ]}
+  onMapClick={(lat, lng) => console.log(`Clicked: ${lat}, ${lng}`)}
+/>
+```
+
+### Map with Search and Route
+```tsx
+<MapPreview
+  center={{ lat: 37.7749, lng: -122.4194 }}
+  showSearch
+  searchPlaceholder="Find a location..."
+  showRoute
+  routeColor="#4CAF50"
+  mapType="hybrid"
+/>
+```
+
+### Heatmap Visualization
+```tsx
+<MapPreview
+  center={{ lat: 37.7749, lng: -122.4194 }}
+  showHeatmap
+  heatmapData={[
+    { lat: 37.7749, lng: -122.4194, weight: 0.8 },
+    { lat: 37.7849, lng: -122.4094, weight: 0.6 },
+    { lat: 37.7649, lng: -122.4294, weight: 0.9 }
+  ]}
+  variant="dark"
+/>
+```
+
+### Glass Effect with Fullscreen
+```tsx
+<MapPreview
+  center={{ lat: 37.7749, lng: -122.4194 }}
+  variant="glass"
+  showControls
+  height="500px"
+/>
+```
+
+## Accessibility
+
+- **ARIA Labels**: Comprehensive labeling for screen readers
+- **Keyboard Navigation**: Full keyboard support for controls
+- **Focus Management**: Proper focus handling for interactive elements
+- **Live Regions**: Dynamic updates announced to assistive technologies
+- **Tooltips**: Informative tooltips on all controls
+- **High Contrast**: Supports high contrast modes
+
+## Best Practices
+
+1. **Performance**: Use appropriate zoom levels and limit markers for better performance
+2. **Mobile**: Ensure adequate height on mobile devices
+3. **API Keys**: Secure API keys properly in production
+4. **Fallbacks**: Provide fallback content when maps cannot load
+5. **Loading States**: Show loading indicators for async data
+6. **Error Handling**: Handle geolocation errors gracefully
+
+## Theme Integration
+
+The component fully integrates with MUI theme:
+- Uses theme colors for map overlays
+- Responds to light/dark mode changes
+- Applies theme spacing and borders
+- Supports custom theme extensions
+
+## Browser Compatibility
+
+- Modern browsers with ES6 support
+- Requires CSS backdrop-filter for glass effects
+- Graceful degradation for older browsers
+- Touch support for mobile devices

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

@@ -0,0 +1,458 @@
+import { action } from 'storybook/actions';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { MapPreview } from './MapPreview';
+import type { HeatmapPoint,MapMarker } from './MapPreview.types';
+
+const meta: Meta<typeof MapPreview> = {
+  title: 'Enhanced/MapPreview',
+  component: MapPreview,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: 'A versatile map preview component with support for markers, routes, heatmaps, and interactive features.',
+      },
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    center: {
+      control: 'object',
+      description: 'Map center coordinates',
+    },
+    height: {
+      control: 'text',
+      description: 'Map container height',
+    },
+    zoom: {
+      control: { type: 'range', min: 1, max: 20, step: 1 },
+      description: 'Zoom level (1-20)',
+    },
+    mapType: {
+      control: 'select',
+      options: ['roadmap', 'satellite', 'hybrid', 'terrain'],
+      description: 'Map display type',
+    },
+    variant: {
+      control: 'select',
+      options: ['default', 'glass', 'satellite', 'dark'],
+      description: 'Visual style variant',
+    },
+    interactive: {
+      control: 'boolean',
+      description: 'Enable user interaction',
+    },
+    showControls: {
+      control: 'boolean',
+      description: 'Show map controls',
+    },
+    showSearch: {
+      control: 'boolean',
+      description: 'Show search functionality',
+    },
+    showRoute: {
+      control: 'boolean',
+      description: 'Display route overlay',
+    },
+    showHeatmap: {
+      control: 'boolean',
+      description: 'Display heatmap overlay',
+    },
+    animated: {
+      control: 'boolean',
+      description: 'Enable smooth animations',
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// Sample data
+const sanFrancisco = { lat: 37.7749, lng: -122.4194 };
+const sampleMarkers: MapMarker[] = [
+  {
+    position: { lat: 37.7749, lng: -122.4194 },
+    title: 'San Francisco City Hall',
+    description: 'Civic Center',
+    onClick: action('marker-click-city-hall'),
+  },
+  {
+    position: { lat: 37.7849, lng: -122.4094 },
+    title: 'Golden Gate Bridge',
+    description: 'Iconic landmark',
+    onClick: action('marker-click-bridge'),
+  },
+  {
+    position: { lat: 37.7949, lng: -122.3994 },
+    title: 'Fisherman\'s Wharf',
+    description: 'Tourist destination',
+    onClick: action('marker-click-wharf'),
+  },
+];
+
+const sampleHeatmapData: HeatmapPoint[] = [
+  { lat: 37.7749, lng: -122.4194, weight: 0.9 },
+  { lat: 37.7849, lng: -122.4094, weight: 0.7 },
+  { lat: 37.7649, lng: -122.4294, weight: 0.8 },
+  { lat: 37.7549, lng: -122.4394, weight: 0.6 },
+  { lat: 37.7949, lng: -122.3994, weight: 0.5 },
+];
+
+// Stories
+export const Default: Story = {
+  args: {
+    center: sanFrancisco,
+    height: '400px',
+    zoom: 12,
+  },
+};
+
+export const Interactive: Story = {
+  args: {
+    center: sanFrancisco,
+    height: '400px',
+    interactive: true,
+    showControls: true,
+    onMapClick: action('map-click'),
+    onMarkerDrag: action('marker-drag'),
+  },
+};
+
+export const MultipleMarkers: Story = {
+  args: {
+    center: sanFrancisco,
+    markers: sampleMarkers,
+    height: '400px',
+    zoom: 11,
+    showControls: true,
+  },
+};
+
+export const WithSearch: Story = {
+  args: {
+    center: sanFrancisco,
+    showSearch: true,
+    searchPlaceholder: 'Search San Francisco...',
+    height: '400px',
+    showControls: true,
+  },
+};
+
+export const RouteDisplay: Story = {
+  args: {
+    center: sanFrancisco,
+    showRoute: true,
+    routeColor: '#4CAF50',
+    markers: [
+      { position: { lat: 37.7749, lng: -122.4194 }, title: 'Start' },
+      { position: { lat: 37.7949, lng: -122.3994 }, title: 'End' },
+    ],
+    height: '400px',
+  },
+};
+
+export const HeatmapVisualization: Story = {
+  args: {
+    center: sanFrancisco,
+    showHeatmap: true,
+    heatmapData: sampleHeatmapData,
+    height: '400px',
+    zoom: 11,
+  },
+};
+
+export const SatelliteView: Story = {
+  args: {
+    center: sanFrancisco,
+    mapType: 'satellite',
+    height: '400px',
+    showControls: true,
+  },
+};
+
+export const HybridView: Story = {
+  args: {
+    center: sanFrancisco,
+    mapType: 'hybrid',
+    markers: sampleMarkers,
+    height: '400px',
+    showControls: true,
+  },
+};
+
+export const TerrainView: Story = {
+  args: {
+    center: sanFrancisco,
+    mapType: 'terrain',
+    height: '400px',
+    showControls: true,
+  },
+};
+
+export const GlassEffect: Story = {
+  args: {
+    center: sanFrancisco,
+    variant: 'glass',
+    height: '400px',
+    showControls: true,
+  },
+  parameters: {
+    backgrounds: { default: 'gradient' },
+  },
+};
+
+export const DarkMode: Story = {
+  args: {
+    center: sanFrancisco,
+    markers: sampleMarkers,
+    height: '400px',
+    showControls: true,
+  },
+  parameters: {
+    backgrounds: { default: 'dark' },
+  },
+};
+
+export const FullFeatured: Story = {
+  args: {
+    center: sanFrancisco,
+    markers: sampleMarkers,
+    showSearch: true,
+    showRoute: true,
+    showHeatmap: true,
+    heatmapData: sampleHeatmapData,
+    interactive: true,
+    showControls: true,
+    height: '500px',
+    onMapClick: action('map-click'),
+    onMarkerDrag: action('marker-drag'),
+  },
+};
+
+export const MinimalHeight: Story = {
+  args: {
+    center: sanFrancisco,
+    height: '200px',
+    showControls: true,
+  },
+};
+
+export const MaxHeight: Story = {
+  args: {
+    center: sanFrancisco,
+    height: '600px',
+    markers: sampleMarkers,
+    showControls: true,
+  },
+};
+
+export const NoControls: Story = {
+  args: {
+    center: sanFrancisco,
+    showControls: false,
+    height: '400px',
+  },
+};
+
+export const NoMarkers: Story = {
+  args: {
+    center: sanFrancisco,
+    marker: false,
+    markers: [],
+    height: '400px',
+    showControls: true,
+  },
+};
+
+export const CustomRoute: Story = {
+  args: {
+    center: sanFrancisco,
+    showRoute: true,
+    routeColor: '#FF5722',
+    height: '400px',
+  },
+};
+
+export const AnimationsDisabled: Story = {
+  args: {
+    center: sanFrancisco,
+    markers: sampleMarkers,
+    animated: false,
+    height: '400px',
+    showControls: true,
+  },
+};
+
+export const ExtremeZoom: Story = {
+  args: {
+    center: sanFrancisco,
+    zoom: 20,
+    height: '400px',
+    showControls: true,
+  },
+};
+
+export const WorldView: Story = {
+  args: {
+    center: { lat: 0, lng: 0 },
+    zoom: 1,
+    height: '400px',
+    showControls: true,
+  },
+};
+
+export const Mobile: Story = {
+  args: {
+    center: sanFrancisco,
+    height: '300px',
+    showControls: true,
+    markers: sampleMarkers,
+  },
+  parameters: {
+    viewport: {
+      defaultViewport: 'iphone6',
+    },
+  },
+};
+
+export const Tablet: Story = {
+  args: {
+    center: sanFrancisco,
+    height: '400px',
+    showControls: true,
+    markers: sampleMarkers,
+    showSearch: true,
+  },
+  parameters: {
+    viewport: {
+      defaultViewport: 'ipad',
+    },
+  },
+};
+
+export const LoadingState: Story = {
+  args: {
+    center: sanFrancisco,
+    height: '400px',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Map loading state simulation',
+      },
+    },
+  },
+};
+
+export const ErrorState: Story = {
+  args: {
+    center: { lat: 999, lng: 999 }, // Invalid coordinates
+    height: '400px',
+    showControls: true,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Map error state with invalid coordinates',
+      },
+    },
+  },
+};
+
+export const EmptyState: Story = {
+  args: {
+    center: sanFrancisco,
+    marker: false,
+    markers: [],
+    showControls: false,
+    height: '400px',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Minimal map without any overlays or controls',
+      },
+    },
+  },
+};
+
+// Required stories for validation
+export const AllVariants: Story = {
+  args: {
+    center: sanFrancisco,
+    height: '400px',
+    showControls: true,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'All map type variants (roadmap, satellite, hybrid, terrain)',
+      },
+    },
+  },
+};
+
+export const AllSizes: Story = {
+  args: {
+    center: sanFrancisco,
+    showControls: true,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Different map sizes from minimal to full height',
+      },
+    },
+  },
+};
+
+export const AllStates: Story = {
+  args: {
+    center: sanFrancisco,
+    interactive: true,
+    showControls: true,
+    markers: sampleMarkers,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'All interactive states including hover, focus, and active',
+      },
+    },
+  },
+};
+
+export const InteractiveStates: Story = {
+  args: {
+    center: sanFrancisco,
+    interactive: true,
+    showControls: true,
+    onMapClick: action('map-click'),
+    onMarkerDrag: action('marker-drag'),
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Interactive states with all callbacks',
+      },
+    },
+  },
+};
+
+export const Responsive: Story = {
+  args: {
+    center: sanFrancisco,
+    height: '400px',
+    showControls: true,
+    markers: sampleMarkers,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Responsive map that adapts to different screen sizes',
+      },
+    },
+  },
+};