@12-apps/ui 1.0.0

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

@@ -0,0 +1,2 @@
+export { default as Lightbox } from './Lightbox';
+export type { AutoplayConfig,LightboxItem, LightboxProps, LightboxRef } from './Lightbox.types';

package/src/components/data-display/Lightbox/lightbox.md

@@ -0,0 +1,298 @@
+Got it — I’ll merge those **advanced features** directly into the master description so your AI has a single, complete spec for building the `Lightbox` component.
+
+---
+
+# Lightbox Component – AI Implementation Description (Extended)
+
+## Purpose
+
+A **Lightbox** is a modal overlay to showcase media (images, videos, or custom content) in a distraction-free way. It emphasizes the active item, dims the background, and provides intuitive navigation and controls.
+
+---
+
+## Core Features
+
+1. **Overlay & Focus**
+   - Semi-transparent backdrop covering viewport.
+   - Content centered with scroll lock while active.
+
+2. **Media Support**
+   - Images, videos, and arbitrary children.
+   - Mixed galleries (image + video).
+
+3. **Navigation**
+   - Previous/Next controls.
+   - Keyboard (`←`, `→`, `Esc`) and swipe support.
+   - Optional loop at edges.
+
+4. **Controls**
+   - Always-visible close button.
+   - Optional captions, share, and download.
+   - Configurable via props.
+
+5. **Accessibility**
+   - Focus trap, `aria-modal="true"`, `role="dialog"`.
+   - Screen reader announcement of current item (“Image 2 of 5”).
+   - Escape closes by default.
+
+---
+
+## Advanced Features
+
+- **Thumbnails / Filmstrip**: optional preview strip for quick navigation.
+- **Zoom & Pan**: pinch/scroll zoom, drag pan, double-tap reset.
+- **Slideshow / Autoplay**: auto-advance with start/stop.
+- **Lazy Load & Preload**: load current, preload prev/next.
+- **Multi-Item Layout**: switch between single and grid view.
+- **Gestures**: swipe left/right to change, swipe down to close (mobile).
+- **Share & Download**: Web Share API, link copy, download with watermark support.
+- **Animations**: morph from thumbnail to fullscreen, crossfade or slide transitions.
+- **Multiple Instances**: independent galleries on one page.
+- **Programmatic API**: expose `open(index)`, `close()`, `next()`, `prev()`.
+
+---
+
+## Props
+
+- `isOpen: boolean` – controls visibility.
+- `onClose: () => void` – close handler.
+- `items?: Array<{ src: string; alt?: string; caption?: string; type?: "image" | "video" }>` – gallery items.
+- `startIndex?: number` – initial item index.
+- `showControls?: boolean` – toggle controls.
+- `showCaptions?: boolean` – toggle captions.
+- `loop?: boolean` – loop gallery navigation.
+- `autoplay?: boolean` – enable auto slideshow.
+- `thumbnails?: boolean` – show filmstrip navigation.
+- `zoomable?: boolean` – enable zoom/pan.
+- `className?: string` – extend styling.
+
+---
+
+## Visual & Motion Guidelines
+
+- **Backdrop:** 60–80% black opacity.
+- **Animation:** fade backdrop, scale/slide media (200–300ms).
+- **Transitions:** configurable easing/duration.
+
+---
+
+## Variants
+
+- **Default:** Image viewer with captions.
+- **Minimal:** Only close button.
+- **Media-Rich:** Mixed gallery.
+- **Fullscreen:** 100% viewport expansion.
+- **Filmstrip Mode:** with thumbnails.
+
+---
+
+## Testing
+
+### Test IDs
+
+The Lightbox component provides comprehensive test IDs for automated testing. All test IDs can be customized via the `dataTestId` prop.
+
+| Element | Default Test ID | Custom Test ID Pattern |
+|---------|----------------|----------------------|
+| Overlay/Dialog | `lightbox` | `{dataTestId}` |
+| Close Button | `lightbox-close` | `{dataTestId}-close` |
+| Previous Button | `lightbox-prev` | `{dataTestId}-prev` |
+| Next Button | `lightbox-next` | `{dataTestId}-next` |
+| Zoom Controls Container | `lightbox-zoom-controls` | `{dataTestId}-zoom-controls` |
+| Zoom In Button | `lightbox-zoom-in` | `{dataTestId}-zoom-in` |
+| Zoom Out Button | `lightbox-zoom-out` | `{dataTestId}-zoom-out` |
+| Zoom Reset Button | `lightbox-zoom-reset` | `{dataTestId}-zoom-reset` |
+| Autoplay Button | `lightbox-autoplay` | `{dataTestId}-autoplay` |
+| Content Container | `lightbox-content` | `{dataTestId}-content` |
+| Image Container | `lightbox-image-container` | `{dataTestId}-image-container` |
+| Image Element | `lightbox-image` | `{dataTestId}-image` |
+| Video Element | `lightbox-video` | `{dataTestId}-video` |
+| Loading Indicator | `lightbox-loading` | `{dataTestId}-loading` |
+| Caption | `lightbox-caption` | `{dataTestId}-caption` |
+| Item Counter | `lightbox-counter` | `{dataTestId}-counter` |
+| Thumbnails Container | `lightbox-thumbnails` | `{dataTestId}-thumbnails` |
+| Individual Thumbnail | `lightbox-thumbnail-{index}` | `{dataTestId}-thumbnail-{index}` |
+
+### Testing Best Practices
+
+1. **Custom Test IDs**: Always provide a `dataTestId` prop when testing multiple lightbox instances on the same page.
+
+```tsx
+<Lightbox dataTestId="product-gallery" isOpen={isOpen} onClose={handleClose} items={items} />
+```
+
+2. **Wait for Visibility**: Use proper waiting strategies for the overlay to appear/disappear.
+
+```tsx
+await waitFor(() => {
+  expect(screen.getByTestId('lightbox')).toBeInTheDocument();
+});
+```
+
+3. **Test User Interactions**: Verify all interactive elements respond correctly.
+
+```tsx
+const closeButton = screen.getByTestId('lightbox-close');
+await userEvent.click(closeButton);
+expect(onCloseMock).toHaveBeenCalled();
+```
+
+4. **Test Keyboard Navigation**: Ensure keyboard controls work as expected.
+
+```tsx
+await userEvent.keyboard('{Escape}');
+expect(onCloseMock).toHaveBeenCalled();
+
+await userEvent.keyboard('{ArrowRight}');
+// Verify next image is displayed
+```
+
+5. **Accessibility Testing**: Validate ARIA attributes and focus management.
+
+```tsx
+const dialog = screen.getByRole('dialog');
+expect(dialog).toHaveAttribute('aria-modal', 'true');
+expect(dialog).toHaveAttribute('aria-labelledby', 'lightbox-title');
+```
+
+### Common Test Scenarios
+
+#### 1. Opening and Closing
+- Click close button
+- Click backdrop (if enabled)
+- Press Escape key
+- Swipe down on mobile
+
+#### 2. Navigation
+- Click previous/next buttons
+- Use keyboard arrows (←, →)
+- Swipe left/right on mobile
+- Click thumbnails to navigate
+- Verify disabled state at boundaries (when loop is off)
+
+#### 3. Loop Behavior
+- Test navigation wraps at edges when `loop={true}`
+- Test navigation stops at edges when `loop={false}`
+
+#### 4. Zoom and Pan
+- Mouse wheel zoom
+- Double-click to zoom in
+- Double-click to zoom out (when zoomed)
+- Drag to pan when zoomed
+- Zoom controls (+, -, reset)
+- Verify zoom only works on images, not videos
+
+#### 5. Autoplay
+- Start/stop slideshow
+- Verify auto-advance timing
+- Pause on hover/focus (if implemented)
+- Spacebar toggle (if enabled)
+
+#### 6. Media Loading
+- Loading indicator appears for slow images
+- Loading indicator disappears when image loads
+- Video controls are visible
+- Mixed image/video galleries work correctly
+
+#### 7. Captions
+- Caption displays when `showCaptions={true}`
+- Caption is hidden when `showCaptions={false}`
+- Caption content matches item caption
+
+#### 8. Thumbnails
+- Thumbnail strip appears when `thumbnails={true}`
+- Current thumbnail is highlighted
+- Clicking thumbnail navigates to that item
+- Video thumbnails show play icon
+
+#### 9. Accessibility
+- Focus trap keeps focus within lightbox
+- Screen reader announces current item ("Image 2 of 5")
+- All interactive elements have aria-labels
+- Dialog has proper ARIA roles and attributes
+
+#### 10. Responsiveness
+- Test at viewport widths: 320px, 768px, 1200px, 3200px
+- Touch gestures work on mobile devices
+- Controls are properly positioned at all sizes
+
+### Example Test Suite
+
+```tsx
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { Lightbox } from './Lightbox';
+
+describe('Lightbox', () => {
+  const mockItems = [
+    { src: '/image1.jpg', alt: 'Image 1', caption: 'First image' },
+    { src: '/image2.jpg', alt: 'Image 2', caption: 'Second image' },
+    { src: '/video1.mp4', alt: 'Video 1', type: 'video' as const },
+  ];
+
+  it('should open and display the lightbox', async () => {
+    const onClose = vi.fn();
+    render(<Lightbox isOpen={true} onClose={onClose} items={mockItems} />);
+
+    await waitFor(() => {
+      expect(screen.getByTestId('lightbox')).toBeInTheDocument();
+    });
+
+    expect(screen.getByTestId('lightbox-image')).toHaveAttribute('src', '/image1.jpg');
+  });
+
+  it('should navigate to next item', async () => {
+    const onClose = vi.fn();
+    render(<Lightbox isOpen={true} onClose={onClose} items={mockItems} showControls={true} />);
+
+    const nextButton = screen.getByTestId('lightbox-next');
+    await userEvent.click(nextButton);
+
+    await waitFor(() => {
+      expect(screen.getByTestId('lightbox-image')).toHaveAttribute('src', '/image2.jpg');
+    });
+  });
+
+  it('should close on Escape key', async () => {
+    const onClose = vi.fn();
+    render(<Lightbox isOpen={true} onClose={onClose} items={mockItems} />);
+
+    await userEvent.keyboard('{Escape}');
+
+    expect(onClose).toHaveBeenCalled();
+  });
+
+  it('should display thumbnails when enabled', async () => {
+    const onClose = vi.fn();
+    render(<Lightbox isOpen={true} onClose={onClose} items={mockItems} thumbnails={true} />);
+
+    await waitFor(() => {
+      expect(screen.getByTestId('lightbox-thumbnails')).toBeInTheDocument();
+    });
+
+    expect(screen.getByTestId('lightbox-thumbnail-0')).toBeInTheDocument();
+    expect(screen.getByTestId('lightbox-thumbnail-1')).toBeInTheDocument();
+  });
+
+  it('should zoom in and out', async () => {
+    const onClose = vi.fn();
+    render(<Lightbox isOpen={true} onClose={onClose} items={mockItems} zoomable={true} />);
+
+    const zoomInButton = screen.getByTestId('lightbox-zoom-in');
+    const zoomOutButton = screen.getByTestId('lightbox-zoom-out');
+
+    await userEvent.click(zoomInButton);
+    // Verify zoom level increased
+
+    await userEvent.click(zoomOutButton);
+    // Verify zoom level decreased
+  });
+});
+```
+
+### Storybook Tests
+
+- **Visual regression**: Overlay appearance, transitions, zoom states
+- **Interaction**: Navigation buttons, keyboard controls, autoplay, gestures
+- **Accessibility**: Roles, ARIA attributes, focus management, announcements
+- **Responsive**: Layout at various viewport sizes

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

@@ -0,0 +1,124 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { LoadingState } from './LoadingState';
+
+const meta: Meta<typeof LoadingState> = {
+  title: 'DataDisplay/AsyncStates/LoadingState',
+  component: LoadingState,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'A loading state component that displays a spinner or skeleton placeholder while content is being loaded.',
+      },
+    },
+  },
+  tags: ['autodocs', 'component:LoadingState'],
+  argTypes: {
+    variant: {
+      control: 'radio',
+      options: ['spinner', 'skeleton'],
+      description: 'The visual style of the loading indicator',
+    },
+    size: {
+      control: 'radio',
+      options: ['sm', 'md', 'lg'],
+      description: 'Size of the loading indicator',
+    },
+    message: {
+      control: 'text',
+      description: 'Optional message to display below the loading indicator',
+    },
+    skeletonRows: {
+      control: { type: 'number', min: 1, max: 10 },
+      description: 'Number of skeleton rows (only for skeleton variant)',
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {},
+};
+
+export const SpinnerSmall: Story = {
+  name: 'Spinner - Small',
+  args: {
+    variant: 'spinner',
+    size: 'sm',
+  },
+};
+
+export const SpinnerMedium: Story = {
+  name: 'Spinner - Medium',
+  args: {
+    variant: 'spinner',
+    size: 'md',
+  },
+};
+
+export const SpinnerLarge: Story = {
+  name: 'Spinner - Large',
+  args: {
+    variant: 'spinner',
+    size: 'lg',
+  },
+};
+
+export const SpinnerWithMessage: Story = {
+  name: 'Spinner with Message',
+  args: {
+    variant: 'spinner',
+    size: 'md',
+    message: 'Loading your data...',
+  },
+};
+
+export const SkeletonDefault: Story = {
+  name: 'Skeleton - Default',
+  args: {
+    variant: 'skeleton',
+  },
+  parameters: {
+    layout: 'padded',
+  },
+};
+
+export const SkeletonWithMessage: Story = {
+  name: 'Skeleton with Message',
+  args: {
+    variant: 'skeleton',
+    message: 'Preparing content...',
+    skeletonRows: 4,
+  },
+  parameters: {
+    layout: 'padded',
+  },
+};
+
+export const SkeletonSmall: Story = {
+  name: 'Skeleton - Small',
+  args: {
+    variant: 'skeleton',
+    size: 'sm',
+    skeletonRows: 5,
+  },
+  parameters: {
+    layout: 'padded',
+  },
+};
+
+export const SkeletonLarge: Story = {
+  name: 'Skeleton - Large',
+  args: {
+    variant: 'skeleton',
+    size: 'lg',
+    skeletonRows: 3,
+  },
+  parameters: {
+    layout: 'padded',
+  },
+};

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

@@ -0,0 +1,99 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, within } from 'storybook/test';
+
+import { LoadingState } from './LoadingState';
+
+const meta: Meta<typeof LoadingState> = {
+  title: 'DataDisplay/AsyncStates/LoadingState/Tests',
+  component: LoadingState,
+  parameters: {
+    layout: 'padded',
+    chromatic: { disableSnapshot: false },
+  },
+  tags: ['autodocs', 'test', 'component:LoadingState'],
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const SpinnerAccessibility: Story = {
+  name: '🧪 Spinner Accessibility',
+  args: {
+    variant: 'spinner',
+    message: 'Loading data...',
+  },
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step('Verify loading state container exists', async () => {
+      const container = canvas.getByTestId('loading-state');
+      await expect(container).toBeInTheDocument();
+    });
+
+    await step('Verify ARIA attributes', async () => {
+      const container = canvas.getByTestId('loading-state');
+      await expect(container).toHaveAttribute('role', 'status');
+      await expect(container).toHaveAttribute('aria-busy', 'true');
+    });
+
+    await step('Verify message is displayed', async () => {
+      const message = canvas.getByTestId('loading-state-message');
+      await expect(message).toHaveTextContent('Loading data...');
+    });
+
+    await step('Verify spinner is present', async () => {
+      const spinner = canvas.getByTestId('loading-state-spinner');
+      await expect(spinner).toBeInTheDocument();
+    });
+  },
+};
+
+export const SkeletonAccessibility: Story = {
+  name: '🧪 Skeleton Accessibility',
+  args: {
+    variant: 'skeleton',
+    skeletonRows: 3,
+    dataTestId: 'skeleton-test',
+  },
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step('Verify loading state container exists', async () => {
+      const container = canvas.getByTestId('skeleton-test');
+      await expect(container).toBeInTheDocument();
+    });
+
+    await step('Verify ARIA attributes', async () => {
+      const container = canvas.getByTestId('skeleton-test');
+      await expect(container).toHaveAttribute('role', 'status');
+      await expect(container).toHaveAttribute('aria-busy', 'true');
+    });
+
+    await step('Verify skeleton rows are rendered', async () => {
+      const skeletons = canvasElement.querySelectorAll('[class*="MuiSkeleton"]');
+      await expect(skeletons.length).toBeGreaterThanOrEqual(3);
+    });
+  },
+};
+
+export const SizeVariations: Story = {
+  name: '🧪 Size Variations',
+  args: {
+    variant: 'spinner',
+    size: 'lg',
+    message: 'Large spinner',
+  },
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step('Verify large spinner renders', async () => {
+      const spinner = canvas.getByTestId('loading-state-spinner');
+      await expect(spinner).toBeInTheDocument();
+    });
+
+    await step('Verify message with correct typography', async () => {
+      const message = canvas.getByTestId('loading-state-message');
+      await expect(message).toBeInTheDocument();
+    });
+  },
+};

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

@@ -0,0 +1,103 @@
+import { Box, CircularProgress, Stack, Typography, useTheme } from '@mui/material';
+import React from 'react';
+
+import { Skeleton } from '../../layout/Skeleton/Skeleton';
+
+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' },
+};
+
+export const LoadingState: React.FC<LoadingStateProps> = React.memo(
+  ({
+    variant = 'spinner',
+    message,
+    size = 'md',
+    skeletonRows = 3,
+    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>
+      );
+    }
+
+    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>
+    );
+  },
+);
+
+LoadingState.displayName = 'LoadingState';
+
+export default LoadingState;

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

@@ -0,0 +1,37 @@
+export type LoadingStateVariant = 'spinner' | 'skeleton';
+export type LoadingStateSize = 'sm' | 'md' | 'lg';
+
+export interface LoadingStateProps {
+  /**
+   * The visual style of the loading indicator
+   * @default 'spinner'
+   */
+  variant?: LoadingStateVariant;
+
+  /**
+   * Optional message to display below the loading indicator
+   */
+  message?: string;
+
+  /**
+   * Size of the loading indicator
+   * @default 'md'
+   */
+  size?: LoadingStateSize;
+
+  /**
+   * Number of skeleton rows to display (only for skeleton variant)
+   * @default 3
+   */
+  skeletonRows?: number;
+
+  /**
+   * Custom className for the container
+   */
+  className?: string;
+
+  /**
+   * Test ID for component testing
+   */
+  dataTestId?: string;
+}

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

@@ -0,0 +1,2 @@
+export { LoadingState } from './LoadingState';
+export type { LoadingStateProps, LoadingStateSize, LoadingStateVariant } from './LoadingState.types';