@12-apps/ui 1.0.0

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

@@ -0,0 +1,56 @@
+export interface MapMarker {
+  position: { lat: number; lng: number };
+  title?: string;
+  description?: string;
+  icon?: string;
+  onClick?: () => void;
+}
+
+export interface HeatmapPoint {
+  lat: number;
+  lng: number;
+  weight: number;
+}
+
+export interface MapPreviewProps {
+  /** Map center coordinates */
+  center?: { lat: number; lng: number };
+  /** Legacy coordinates prop (use center instead) */
+  coordinates?: { lat: number; lng: number };
+  /** Array of markers to display */
+  markers?: MapMarker[];
+  /** Single marker (use markers array instead) */
+  marker?: boolean;
+  /** Map height */
+  height?: string;
+  /** Enable user interaction */
+  interactive?: boolean;
+  /** Initial zoom level */
+  zoom?: number;
+  /** Google Maps API key */
+  googleMapsApiKey?: string;
+  /** Map display type */
+  mapType?: 'roadmap' | 'satellite' | 'hybrid' | 'terrain';
+  /** Map style variant */
+  variant?: 'default' | 'glass' | 'satellite' | 'dark';
+  /** Show map controls */
+  showControls?: boolean;
+  /** Show search functionality */
+  showSearch?: boolean;
+  /** Search placeholder text */
+  searchPlaceholder?: string;
+  /** Enable route display */
+  showRoute?: boolean;
+  /** Route line color */
+  routeColor?: string;
+  /** Heatmap data points */
+  heatmapData?: HeatmapPoint[];
+  /** Show heatmap overlay */
+  showHeatmap?: boolean;
+  /** Enable smooth animations */
+  animated?: boolean;
+  /** Callback when marker is dragged */
+  onMarkerDrag?: (coords: { lat: number; lng: number }) => void;
+  /** Callback when map is clicked */
+  onMapClick?: (lat: number, lng: number) => void;
+}

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

@@ -0,0 +1,2 @@
+export { MapPreview } from './MapPreview';
+export type { HeatmapPoint,MapMarker, MapPreviewProps } from './MapPreview.types';

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

@@ -0,0 +1,245 @@
+# Popover
+
+A flexible popover component built on top of Material-UI's Popover, providing enhanced styling variants and interactive effects.
+
+## Props
+
+### `variant` (optional)
+
+- **Type:** `'default' | 'glass' | 'arrow'`
+- **Default:** `'default'`
+- **Description:** The visual variant of the popover
+  - `default`: Standard popover with solid background and shadow
+  - `glass`: Glassmorphism effect with backdrop blur and transparency
+  - `arrow`: Enhanced popover with stronger shadows (intended for arrow variants)
+
+### `glow` (optional)
+
+- **Type:** `boolean`
+- **Default:** `false`
+- **Description:** Whether the popover should have a glowing effect using the primary theme color
+
+### `pulse` (optional)
+
+- **Type:** `boolean`
+- **Default:** `false`
+- **Description:** Whether the popover should have a subtle pulse animation effect
+
+### `arrow` (optional)
+
+- **Type:** `boolean`
+- **Default:** `false`
+- **Description:** Whether to show an arrow pointing to the anchor (currently defined in types but not implemented in component)
+
+### `maxWidth` (optional)
+
+- **Type:** `number`
+- **Default:** `400`
+- **Description:** Maximum width of the popover in pixels
+
+### Inherited Props
+
+All other props from Material-UI's `PopoverProps` are supported, including:
+
+- `open`: Controls whether the popover is open
+- `anchorEl`: The element the popover is anchored to
+- `onClose`: Callback fired when the popover requests to be closed
+- `anchorOrigin`: The anchor point on the anchor element
+- `transformOrigin`: The transform origin point on the popover
+
+## Usage Examples
+
+### Basic Popover
+
+```tsx
+<Popover open={open} anchorEl={anchorEl} onClose={handleClose}>
+  <Typography sx={{ p: 2 }}>Basic popover content</Typography>
+</Popover>
+```
+
+### Glass Effect Popover
+
+```tsx
+<Popover variant="glass" open={open} anchorEl={anchorEl} onClose={handleClose}>
+  <Typography sx={{ p: 2 }}>Glass effect popover</Typography>
+</Popover>
+```
+
+### Popover with Glow Effect
+
+```tsx
+<Popover glow open={open} anchorEl={anchorEl} onClose={handleClose}>
+  <Typography sx={{ p: 2 }}>Glowing popover</Typography>
+</Popover>
+```
+
+### Animated Popover
+
+```tsx
+<Popover pulse open={open} anchorEl={anchorEl} onClose={handleClose}>
+  <Typography sx={{ p: 2 }}>Pulsing popover</Typography>
+</Popover>
+```
+
+## Accessibility Notes
+
+- The component inherits all accessibility features from Material-UI's Popover
+- Proper focus management is handled automatically
+- Escape key closes the popover by default
+- Screen readers can navigate the content properly
+- ARIA attributes are applied automatically
+
+## Best Practices
+
+1. **Positioning**: Use appropriate `anchorOrigin` and `transformOrigin` props to ensure the popover appears in the optimal location
+2. **Content**: Keep popover content concise and focused on the primary action or information
+3. **Interactive Elements**: Ensure interactive elements within the popover are keyboard accessible
+4. **Mobile**: Consider the mobile experience - popovers should adapt well to smaller screens
+5. **Performance**: Use the `glow` and `pulse` effects sparingly as they involve CSS animations and filters
+
+## Testing
+
+The Popover component includes test IDs for reliable testing. Use the `dataTestId` prop to provide custom test identifiers.
+
+### Test IDs
+
+| Element | Test ID Pattern | Default Test ID |
+|---------|----------------|-----------------|
+| Popover container | `{dataTestId}` or default | `popover-content` |
+
+### Testing Best Practices
+
+1. **Visibility Testing**: Always verify the popover is visible before interacting with its content
+2. **Anchor Testing**: Test that the popover is properly positioned relative to its anchor element
+3. **Close Behavior**: Test that clicking outside, pressing Escape, and any close buttons properly close the popover
+4. **Accessibility**: Verify focus management and keyboard navigation work correctly
+5. **Content Testing**: Test all interactive elements within the popover content
+
+### Common Test Scenarios
+
+#### Testing Popover Visibility
+
+```tsx
+import { render, screen } from '@testing-library/react';
+import { Popover } from './Popover';
+
+test('shows popover when open', () => {
+  const anchorEl = document.createElement('div');
+  render(
+    <Popover open={true} anchorEl={anchorEl} dataTestId="user-popover">
+      <div>Popover content</div>
+    </Popover>
+  );
+
+  expect(screen.getByTestId('user-popover')).toBeInTheDocument();
+  expect(screen.getByText('Popover content')).toBeVisible();
+});
+```
+
+#### Testing Popover Close Behavior
+
+```tsx
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { Popover } from './Popover';
+
+test('closes popover when clicking outside', async () => {
+  const user = userEvent.setup();
+  const handleClose = jest.fn();
+  const anchorEl = document.createElement('div');
+
+  render(
+    <Popover open={true} anchorEl={anchorEl} onClose={handleClose} dataTestId="info-popover">
+      <div>Information</div>
+    </Popover>
+  );
+
+  // Click outside the popover
+  await user.click(document.body);
+
+  expect(handleClose).toHaveBeenCalled();
+});
+```
+
+#### Testing Popover Variants
+
+```tsx
+import { render, screen } from '@testing-library/react';
+import { Popover } from './Popover';
+
+test('applies glass variant styling', () => {
+  const anchorEl = document.createElement('div');
+  render(
+    <Popover open={true} anchorEl={anchorEl} variant="glass" dataTestId="glass-popover">
+      <div>Content</div>
+    </Popover>
+  );
+
+  const popover = screen.getByTestId('glass-popover');
+  expect(popover).toBeInTheDocument();
+  // Additional style assertions can be added
+});
+```
+
+#### Testing Popover with Custom Content
+
+```tsx
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { Popover } from './Popover';
+
+test('interacts with popover content', async () => {
+  const user = userEvent.setup();
+  const handleAction = jest.fn();
+  const anchorEl = document.createElement('div');
+
+  render(
+    <Popover open={true} anchorEl={anchorEl} dataTestId="action-popover">
+      <button onClick={handleAction}>Action Button</button>
+    </Popover>
+  );
+
+  const button = screen.getByRole('button', { name: 'Action Button' });
+  await user.click(button);
+
+  expect(handleAction).toHaveBeenCalled();
+});
+```
+
+#### Testing Popover Effects
+
+```tsx
+import { render, screen } from '@testing-library/react';
+import { Popover } from './Popover';
+
+test('applies glow effect', () => {
+  const anchorEl = document.createElement('div');
+  render(
+    <Popover open={true} anchorEl={anchorEl} glow dataTestId="glow-popover">
+      <div>Glowing content</div>
+    </Popover>
+  );
+
+  expect(screen.getByTestId('glow-popover')).toBeInTheDocument();
+});
+
+test('applies pulse animation', () => {
+  const anchorEl = document.createElement('div');
+  render(
+    <Popover open={true} anchorEl={anchorEl} pulse dataTestId="pulse-popover">
+      <div>Pulsing content</div>
+    </Popover>
+  );
+
+  expect(screen.getByTestId('pulse-popover')).toBeInTheDocument();
+});
+```
+
+### Integration Testing Notes
+
+When testing components that use Popover:
+
+1. **Mock Anchor Elements**: Always provide valid anchor elements for testing
+2. **Portal Testing**: Remember that popovers render in a portal, so use appropriate queries
+3. **Async Behavior**: Account for any transition/animation delays when testing visibility
+4. **Cleanup**: Ensure popovers are properly cleaned up between tests to avoid state leakage

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

@@ -0,0 +1,295 @@
+import { Button, List, ListItem, ListItemText,Stack, Typography } from '@mui/material';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import React from 'react';
+
+import { Popover } from './Popover';
+
+const meta: Meta<typeof Popover> = {
+  title: 'DataDisplay/Popover',
+  component: Popover,
+  parameters: {
+    layout: 'centered',
+  },
+  tags: ['autodocs', 'component:Popover'],
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// Wrapper for interactive stories
+const PopoverDemo = ({
+  children,
+  ...props
+}: {
+  children?: React.ReactNode;
+  [key: string]: unknown;
+}) => {
+  const [anchorEl, setAnchorEl] = React.useState<HTMLButtonElement | null>(null);
+  const open = Boolean(anchorEl);
+
+  const handleClick = (event: React.MouseEvent<HTMLButtonElement>) => {
+    setAnchorEl(event.currentTarget);
+  };
+
+  const handleClose = () => {
+    setAnchorEl(null);
+  };
+
+  return (
+    <>
+      <Button variant="contained" onClick={handleClick}>
+        Open Popover
+      </Button>
+      <Popover
+        open={open}
+        anchorEl={anchorEl}
+        onClose={handleClose}
+        anchorOrigin={{
+          vertical: 'bottom',
+          horizontal: 'left',
+        }}
+        {...props}
+      >
+        {children}
+      </Popover>
+    </>
+  );
+};
+
+export const Default: Story = {
+  render: () => (
+    <PopoverDemo>
+      <Typography sx={{ p: 2 }}>This is a basic popover content.</Typography>
+    </PopoverDemo>
+  ),
+};
+
+export const Variants: Story = {
+  render: () => (
+    <Stack direction="row" spacing={2}>
+      <PopoverDemo variant="default">
+        <Typography sx={{ p: 2 }}>Default variant</Typography>
+      </PopoverDemo>
+      <PopoverDemo variant="glass">
+        <Typography sx={{ p: 2 }}>Glass variant</Typography>
+      </PopoverDemo>
+      <PopoverDemo variant="arrow">
+        <Typography sx={{ p: 2 }}>Arrow variant</Typography>
+      </PopoverDemo>
+    </Stack>
+  ),
+};
+
+export const WithEffects: Story = {
+  render: () => (
+    <Stack direction="row" spacing={2}>
+      <PopoverDemo glow>
+        <Typography sx={{ p: 2 }}>Glow effect</Typography>
+      </PopoverDemo>
+      <PopoverDemo pulse>
+        <Typography sx={{ p: 2 }}>Pulse effect</Typography>
+      </PopoverDemo>
+    </Stack>
+  ),
+};
+
+export const ComplexContent: Story = {
+  render: () => (
+    <PopoverDemo variant="glass" maxWidth={300}>
+      <div style={{ padding: 16 }}>
+        <Typography variant="h6" gutterBottom>
+          Menu Options
+        </Typography>
+        <List dense>
+          <ListItem button>
+            <ListItemText primary="Profile Settings" />
+          </ListItem>
+          <ListItem button>
+            <ListItemText primary="Account Security" />
+          </ListItem>
+          <ListItem button>
+            <ListItemText primary="Notifications" />
+          </ListItem>
+          <ListItem button>
+            <ListItemText primary="Sign Out" />
+          </ListItem>
+        </List>
+      </div>
+    </PopoverDemo>
+  ),
+};
+
+export const GlassEffect: Story = {
+  render: () => (
+    <PopoverDemo variant="glass" glow>
+      <Typography sx={{ p: 3 }}>Glass morphism with glow effect</Typography>
+    </PopoverDemo>
+  ),
+};
+
+export const WithArrow: Story = {
+  render: () => (
+    <PopoverDemo variant="arrow">
+      <Typography sx={{ p: 2 }}>Popover with arrow pointing to anchor</Typography>
+    </PopoverDemo>
+  ),
+};
+
+export const DifferentSizes: Story = {
+  render: () => (
+    <Stack direction="row" spacing={2}>
+      <PopoverDemo maxWidth={200}>
+        <Typography sx={{ p: 2 }}>Small popover (200px max)</Typography>
+      </PopoverDemo>
+      <PopoverDemo maxWidth={400}>
+        <Typography sx={{ p: 2 }}>Medium popover (400px max)</Typography>
+      </PopoverDemo>
+      <PopoverDemo maxWidth={600}>
+        <Typography sx={{ p: 2 }}>Large popover (600px max)</Typography>
+      </PopoverDemo>
+    </Stack>
+  ),
+};
+
+export const CombinedEffects: Story = {
+  render: () => (
+    <PopoverDemo variant="glass" glow pulse>
+      <Typography sx={{ p: 3 }}>Combined glass, glow, and pulse effects</Typography>
+    </PopoverDemo>
+  ),
+};
+
+export const EmptyState: Story = {
+  render: () => (
+    <PopoverDemo>
+      <div style={{ padding: 24, textAlign: 'center' }}>
+        <Typography color="text.secondary">No content available</Typography>
+      </div>
+    </PopoverDemo>
+  ),
+};
+
+export const LoadingState: Story = {
+  render: () => (
+    <PopoverDemo>
+      <div style={{ padding: 24, textAlign: 'center' }}>
+        <Typography>Loading...</Typography>
+      </div>
+    </PopoverDemo>
+  ),
+};
+
+export const ErrorState: Story = {
+  render: () => (
+    <PopoverDemo>
+      <div style={{ padding: 24, textAlign: 'center' }}>
+        <Typography color="error">Error loading content</Typography>
+      </div>
+    </PopoverDemo>
+  ),
+};
+
+// Required story exports for validation
+export const AllVariants: Story = {
+  render: () => (
+    <Stack direction="column" spacing={4} alignItems="center">
+      <PopoverDemo variant="default">
+        <Typography sx={{ p: 2 }}>Default variant</Typography>
+      </PopoverDemo>
+      <PopoverDemo variant="glass">
+        <Typography sx={{ p: 2 }}>Glass variant with translucent effect</Typography>
+      </PopoverDemo>
+      <PopoverDemo variant="arrow">
+        <Typography sx={{ p: 2 }}>Arrow variant pointing to anchor</Typography>
+      </PopoverDemo>
+    </Stack>
+  ),
+};
+
+export const AllSizes: Story = {
+  render: () => (
+    <Stack direction="column" spacing={4} alignItems="center">
+      <PopoverDemo maxWidth={150}>
+        <Typography sx={{ p: 2 }}>Extra small (150px)</Typography>
+      </PopoverDemo>
+      <PopoverDemo maxWidth={250}>
+        <Typography sx={{ p: 2 }}>Small (250px)</Typography>
+      </PopoverDemo>
+      <PopoverDemo maxWidth={400}>
+        <Typography sx={{ p: 2 }}>Medium (400px)</Typography>
+      </PopoverDemo>
+      <PopoverDemo maxWidth={600}>
+        <Typography sx={{ p: 3 }}>Large (600px)</Typography>
+      </PopoverDemo>
+      <PopoverDemo maxWidth={800}>
+        <Typography sx={{ p: 4 }}>Extra large (800px)</Typography>
+      </PopoverDemo>
+    </Stack>
+  ),
+};
+
+export const AllStates: Story = {
+  render: () => (
+    <Stack direction="column" spacing={4} alignItems="center">
+      <PopoverDemo>
+        <Typography sx={{ p: 2 }}>Normal state</Typography>
+      </PopoverDemo>
+      <PopoverDemo>
+        <div style={{ padding: 24, textAlign: 'center' }}>
+          <Typography>Loading...</Typography>
+        </div>
+      </PopoverDemo>
+      <PopoverDemo>
+        <div style={{ padding: 24, textAlign: 'center' }}>
+          <Typography color="error">Error state</Typography>
+        </div>
+      </PopoverDemo>
+      <PopoverDemo>
+        <div style={{ padding: 24, textAlign: 'center' }}>
+          <Typography color="text.secondary">Empty state</Typography>
+        </div>
+      </PopoverDemo>
+    </Stack>
+  ),
+};
+
+export const InteractiveStates: Story = {
+  render: () => (
+    <Stack direction="row" spacing={4} alignItems="center">
+      <PopoverDemo>
+        <Typography sx={{ p: 2 }}>Hover over me</Typography>
+      </PopoverDemo>
+      <PopoverDemo variant="glass" glow>
+        <Typography sx={{ p: 2 }}>Glass with glow on hover</Typography>
+      </PopoverDemo>
+      <PopoverDemo variant="arrow" pulse>
+        <Typography sx={{ p: 2 }}>Arrow with pulse effect</Typography>
+      </PopoverDemo>
+    </Stack>
+  ),
+};
+
+export const Responsive: Story = {
+  parameters: {
+    viewport: {
+      viewports: {
+        mobile: { name: 'Mobile', styles: { width: '375px', height: '667px' } },
+        tablet: { name: 'Tablet', styles: { width: '768px', height: '1024px' } },
+        desktop: { name: 'Desktop', styles: { width: '1280px', height: '720px' } },
+      },
+    },
+  },
+  render: () => (
+    <PopoverDemo variant="glass" glow>
+      <div style={{ padding: 24 }}>
+        <Typography variant="h6" gutterBottom>
+          Responsive Popover
+        </Typography>
+        <Typography paragraph>This popover adapts to different screen sizes.</Typography>
+        <Typography variant="body2" color="text.secondary">
+          Try switching viewport sizes to see responsive behavior.
+        </Typography>
+      </div>
+    </PopoverDemo>
+  ),
+};