@12-apps/ui 1.0.0

package/src/components/form/ToggleGroup/ToggleGroup.tsx

@@ -0,0 +1,129 @@
+import { alpha, Box, ToggleButton, ToggleButtonGroup, useTheme } from '@mui/material';
+import type { Theme } from '@mui/material/styles';
+import { styled } from '@mui/material/styles';
+import React, { forwardRef } from 'react';
+
+import type { ToggleGroupProps } from './ToggleGroup.types';
+
+const getColorFromTheme = (theme: Theme, color: string) => {
+  if (color === 'neutral') {
+    return {
+      main: theme.palette.grey[700],
+      dark: theme.palette.grey[800],
+      light: theme.palette.grey[500],
+      contrastText: theme.palette.getContrastText(theme.palette.grey[700]),
+    };
+  }
+
+  const colorMap = {
+    primary: theme.palette.primary,
+    secondary: theme.palette.secondary,
+    success: theme.palette.success,
+    warning: theme.palette.warning,
+    danger: theme.palette.error,
+  };
+
+  const palette = colorMap[color as keyof typeof colorMap] || theme.palette.primary;
+
+  // Ensure palette has required properties
+  return {
+    main: palette.main,
+    dark: palette.dark || palette.main,
+    light: palette.light || palette.main,
+    contrastText: palette.contrastText || theme.palette.getContrastText(palette.main),
+  };
+};
+
+const StyledToggleGroup = styled(ToggleButtonGroup, {
+  shouldForwardProp: (prop) => !['customColor', 'customSize', 'glass'].includes(prop as string),
+})<{
+  customColor?: string;
+  customSize?: string;
+  glass?: boolean;
+}>(({ theme, glass }) => ({
+  backgroundColor: glass ? alpha(theme.palette.background.paper, 0.1) : 'transparent',
+  backdropFilter: glass ? 'blur(20px)' : 'none',
+  borderRadius: theme.spacing(1),
+  padding: glass ? 4 : 0,
+  border: glass ? `1px solid ${alpha(theme.palette.divider, 0.2)}` : 'none',
+
+  '& .MuiToggleButtonGroup-grouped': {
+    margin: theme.spacing(0.5),
+    border: 0,
+    borderRadius: `${theme.shape.borderRadius}px !important`,
+  },
+}));
+
+export const ToggleGroup = forwardRef<HTMLDivElement, ToggleGroupProps>(
+  (
+    {
+      variant = 'single',
+      color = 'primary',
+      size = 'md',
+      options,
+      glass = false,
+      gradient = false,
+      value,
+      onChange,
+      dataTestId = 'toggle-group',
+      ...props
+    },
+    ref,
+  ) => {
+    const theme = useTheme();
+    const colorPalette = getColorFromTheme(theme, color);
+
+    const sizeMap = {
+      xs: { padding: '4px 8px', fontSize: '0.75rem' },
+      sm: { padding: '6px 12px', fontSize: '0.875rem' },
+      md: { padding: '8px 16px', fontSize: '1rem' },
+      lg: { padding: '10px 20px', fontSize: '1.125rem' },
+      xl: { padding: '12px 24px', fontSize: '1.25rem' },
+    };
+
+    return (
+      <StyledToggleGroup
+        ref={ref}
+        customColor={color}
+        customSize={size}
+        glass={glass}
+        value={value}
+        onChange={onChange}
+        exclusive={variant === 'exclusive' || variant === 'single'}
+        data-testid={dataTestId}
+        {...props}
+      >
+        {options.map((option) => (
+          <ToggleButton
+            key={option.value}
+            value={option.value}
+            disabled={option.disabled}
+            data-testid={`${dataTestId}-item-${option.value}`}
+            sx={{
+              textTransform: 'none',
+              fontWeight: 500,
+              transition: 'all 0.3s ease',
+              ...sizeMap[size as keyof typeof sizeMap],
+
+              '&.Mui-selected': {
+                backgroundColor: colorPalette.main,
+                color: colorPalette.contrastText,
+
+                ...(gradient && {
+                  background: `linear-gradient(135deg, ${colorPalette.main}, ${colorPalette.dark})`,
+                }),
+              },
+            }}
+          >
+            <Box sx={{ display: 'flex', alignItems: 'center', gap: 1 }}>
+              {option.icon}
+              {option.label}
+            </Box>
+          </ToggleButton>
+        ))}
+      </StyledToggleGroup>
+    );
+  },
+);
+
+ToggleGroup.displayName = 'ToggleGroup';

package/src/components/form/ToggleGroup/ToggleGroup.types.ts

@@ -0,0 +1,53 @@
+import type { ToggleButtonGroupProps } from '@mui/material';
+import type React from 'react';
+
+export interface ToggleOption {
+  value: string;
+  label: string;
+  icon?: React.ReactNode;
+  disabled?: boolean;
+}
+
+export interface ToggleGroupProps extends Omit<ToggleButtonGroupProps, 'color' | 'size'> {
+  /**
+   * The variant of the toggle group
+   */
+  variant?: 'single' | 'multiple' | 'exclusive';
+
+  /**
+   * The color theme of the toggle group
+   */
+  color?: 'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'neutral';
+
+  /**
+   * The size of the toggle group
+   */
+  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
+  /**
+   * Array of toggle options
+   */
+  options: ToggleOption[];
+
+  /**
+   * Whether the toggle group should have a glow effect
+   */
+  glow?: boolean;
+
+  /**
+   * Whether the toggle group should have glass morphism effect
+   */
+  glass?: boolean;
+
+  /**
+   * Whether the toggle group should have gradient effects
+   */
+  gradient?: boolean;
+
+  /**
+   * Custom data-testid attribute for the toggle group container
+   * Individual toggle items will receive testIds in the format: `${dataTestId}-item-${option.value}`
+   * @default 'toggle-group'
+   */
+  dataTestId?: string;
+}

package/src/components/form/ToggleGroup/index.ts

@@ -0,0 +1,2 @@
+export { ToggleGroup } from './ToggleGroup';
+export type { ToggleGroupProps, ToggleOption } from './ToggleGroup.types';

package/src/components/form/UploadButton/UploadButton.md

@@ -0,0 +1,44 @@
+# UploadButton Component
+
+**Purpose:** Single-file selection (and optional upload) with variants for plain button, outlined, ghost, and a compact **dropzone** surface for drag-and-drop (still single file).
+
+```ts
+interface UploadButtonProps {
+  variant?: 'default' | 'outline' | 'ghost' | 'dropzone';
+  label?: string; // Button text
+  accept?: string; // e.g. "image/*,.pdf"
+  capture?: 'user' | 'environment'; // mobile camera hints
+  disabled?: boolean;
+
+  // Selection & upload
+  onSelect: (file: File) => void;
+  onUpload?: (file: File) => Promise<void>; // optional built-in upload
+  uploading?: boolean; // external control of spinner/progress
+  progress?: number; // 0–100 (if showing progress)
+
+  // Constraints
+  maxSizeMB?: number;
+  validate?: (file: File) => string | null; // return error message to block
+
+  // UI hooks
+  helperText?: string;
+  errorText?: string;
+  icon?: React.ReactNode;
+  className?: string;
+}
+```
+
+**Features**
+
+- Click to choose or drag-and-drop (dropzone variant).
+- Optional built-in async `onUpload` with progress; or use external upload.
+- Size/type validation with friendly error messaging.
+
+**A11y**
+
+- Use `<input type="file">` with `aria-describedby` for helper/error.
+- In dropzone, announce drag enter/leave via `aria-live="polite"`.
+
+**Stories / Tests**
+
+- Default, Outline, Ghost, Dropzone; Accept filter; Max size error; Uploading + Progress; Keyboard focus.

package/src/components/form/UploadButton/UploadButton.stories.tsx

@@ -0,0 +1,366 @@
+import { CloudUploadOutlined,PhotoCameraOutlined } from '@mui/icons-material';
+import { Box } from '@mui/material';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { action } from 'storybook/actions';
+
+import { UploadButton } from './UploadButton';
+
+const meta: Meta<typeof UploadButton> = {
+  title: 'Form/UploadButton',
+  component: UploadButton,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: 'Single-file upload component with variants for plain button, outlined, ghost, and dropzone interface. Supports drag-and-drop, built-in async upload with progress tracking, file validation, and comprehensive accessibility features.'
+      }
+    }
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ['default', 'outline', 'ghost', 'dropzone'],
+      description: 'Button variant style'
+    },
+    label: {
+      control: 'text',
+      description: 'Button text label'
+    },
+    accept: {
+      control: 'text',
+      description: 'File type restrictions (e.g., "image/*,.pdf")'
+    },
+    capture: {
+      control: 'select',
+      options: ['user', 'environment'],
+      description: 'Mobile camera capture hint'
+    },
+    disabled: {
+      control: 'boolean',
+      description: 'Disable file selection'
+    },
+    uploading: {
+      control: 'boolean',
+      description: 'External upload state control'
+    },
+    progress: {
+      control: { type: 'range', min: 0, max: 100, step: 1 },
+      description: 'Upload progress (0-100)'
+    },
+    maxSizeMB: {
+      control: 'number',
+      description: 'Maximum file size in MB'
+    },
+    helperText: {
+      control: 'text',
+      description: 'Helper text'
+    },
+    errorText: {
+      control: 'text',
+      description: 'Error message'
+    },
+    className: {
+      control: 'text',
+      description: 'Additional CSS classes'
+    },
+    onSelect: {
+      action: 'file-selected',
+      description: 'File selection callback (required)'
+    },
+    onUpload: {
+      action: 'file-uploaded',
+      description: 'Optional built-in upload handler with progress'
+    },
+    validate: {
+      description: 'Custom file validation function'
+    },
+    icon: {
+      description: 'Custom icon'
+    }
+  }
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// Basic stories
+export const Default: Story = {
+  args: {
+    onSelect: action('file-selected')
+  }
+};
+
+export const Outline: Story = {
+  args: {
+    variant: 'outline',
+    onSelect: action('file-selected')
+  }
+};
+
+export const Ghost: Story = {
+  args: {
+    variant: 'ghost',
+    onSelect: action('file-selected')
+  }
+};
+
+export const Dropzone: Story = {
+  args: {
+    variant: 'dropzone',
+    onSelect: action('file-selected')
+  }
+};
+
+// File type restrictions
+export const ImageOnly: Story = {
+  args: {
+    accept: 'image/*',
+    label: 'Upload Image',
+    icon: <PhotoCameraOutlined />,
+    helperText: 'Only image files are allowed',
+    onSelect: action('image-selected')
+  }
+};
+
+export const PDFOnly: Story = {
+  args: {
+    accept: '.pdf',
+    label: 'Upload PDF',
+    helperText: 'Only PDF files are allowed',
+    onSelect: action('pdf-selected')
+  }
+};
+
+// States
+export const Disabled: Story = {
+  args: {
+    disabled: true,
+    onSelect: action('file-selected')
+  }
+};
+
+export const WithHelperText: Story = {
+  args: {
+    helperText: 'Select a file to upload (max 5MB)',
+    onSelect: action('file-selected')
+  }
+};
+
+export const WithError: Story = {
+  args: {
+    errorText: 'File size exceeds 5MB limit',
+    onSelect: action('file-selected')
+  }
+};
+
+// Upload states
+export const Uploading: Story = {
+  args: {
+    uploading: true,
+    progress: 45,
+    onSelect: action('file-selected')
+  }
+};
+
+export const UploadComplete: Story = {
+  args: {
+    uploading: false,
+    progress: 100,
+    onSelect: action('file-selected')
+  }
+};
+
+// Size validation
+export const WithSizeLimit: Story = {
+  args: {
+    maxSizeMB: 5,
+    helperText: 'Maximum file size: 5MB',
+    onSelect: action('file-selected')
+  }
+};
+
+// Custom validation
+export const WithCustomValidation: Story = {
+  args: {
+    validate: (file: globalThis.File) => {
+      if (!file.name.includes('document')) {
+        return 'File name must contain "document"';
+      }
+      return null;
+    },
+    helperText: 'File name must contain "document"',
+    onSelect: action('file-selected')
+  }
+};
+
+// Built-in upload
+export const WithBuiltInUpload: Story = {
+  args: {
+    onSelect: action('file-selected'),
+    onUpload: async (file: globalThis.File) => {
+      action('upload-started')(file);
+      // Simulate upload delay
+      await new Promise(resolve => globalThis.setTimeout(resolve, 2000));
+      action('upload-completed')(file);
+    }
+  }
+};
+
+// Custom icons
+export const WithCustomIcon: Story = {
+  args: {
+    icon: <CloudUploadOutlined />,
+    onSelect: action('file-selected')
+  }
+};
+
+// Dropzone variants
+export const DropzoneDisabled: Story = {
+  args: {
+    variant: 'dropzone',
+    disabled: true,
+    onSelect: action('file-selected')
+  }
+};
+
+export const DropzoneUploading: Story = {
+  args: {
+    variant: 'dropzone',
+    uploading: true,
+    progress: 65,
+    onSelect: action('file-selected')
+  }
+};
+
+export const DropzoneWithError: Story = {
+  args: {
+    variant: 'dropzone',
+    errorText: 'Upload failed. Please try again.',
+    onSelect: action('file-selected')
+  }
+};
+
+// Mobile camera capture
+export const CameraCapture: Story = {
+  args: {
+    accept: 'image/*',
+    capture: 'environment',
+    label: 'Take Photo',
+    icon: <PhotoCameraOutlined />,
+    helperText: 'Use camera to take a photo',
+    onSelect: action('photo-captured')
+  }
+};
+
+export const FrontCamera: Story = {
+  args: {
+    accept: 'image/*',
+    capture: 'user',
+    label: 'Take Selfie',
+    icon: <PhotoCameraOutlined />,
+    helperText: 'Use front camera for selfie',
+    onSelect: action('selfie-captured')
+  }
+};
+
+// Layout variations
+export const AllVariants: Story = {
+  render: () => (
+    <Box sx={{ display: 'flex', flexDirection: 'column', gap: 3, width: '100%', maxWidth: 800 }}>
+      <Box sx={{ display: 'flex', gap: 2, flexWrap: 'wrap' }}>
+        <UploadButton onSelect={action('default-selected')} />
+        <UploadButton variant="outline" onSelect={action('outline-selected')} />
+        <UploadButton variant="ghost" onSelect={action('ghost-selected')} />
+      </Box>
+      <Box sx={{ width: '100%', maxWidth: 400 }}>
+        <UploadButton 
+          variant="dropzone" 
+          onSelect={action('dropzone-selected')}
+        />
+      </Box>
+    </Box>
+  )
+};
+
+export const AllSizes: Story = {
+  render: () => (
+    <Box sx={{ display: 'flex', flexDirection: 'column', gap: 2, alignItems: 'flex-start' }}>
+      <UploadButton 
+        label="Small"
+        onSelect={action('small-selected')}
+        sx={{ fontSize: '0.75rem', padding: '4px 8px' }}
+      />
+      <UploadButton 
+        label="Medium" 
+        onSelect={action('medium-selected')}
+      />
+      <UploadButton 
+        label="Large"
+        onSelect={action('large-selected')}
+        sx={{ fontSize: '1.125rem', padding: '12px 24px' }}
+      />
+    </Box>
+  )
+};
+
+export const AllStates: Story = {
+  render: () => (
+    <Box sx={{ display: 'flex', flexDirection: 'column', gap: 2, alignItems: 'flex-start' }}>
+      <UploadButton label="Default" onSelect={action('default-selected')} />
+      <UploadButton label="Disabled" disabled onSelect={action('disabled-selected')} />
+      <UploadButton label="Uploading" uploading progress={50} onSelect={action('uploading-selected')} />
+      <UploadButton label="With Error" errorText="Upload failed" onSelect={action('error-selected')} />
+      <UploadButton label="With Helper" helperText="Select a file to upload" onSelect={action('helper-selected')} />
+    </Box>
+  )
+};
+
+export const InteractiveStates: Story = {
+  render: () => (
+    <Box sx={{ display: 'flex', flexDirection: 'column', gap: 2, alignItems: 'flex-start' }}>
+      <UploadButton 
+        label="Hover Me" 
+        onSelect={action('hover-selected')}
+        sx={{ 
+          '&:hover': { 
+            transform: 'translateY(-2px)',
+            transition: 'transform 0.2s'
+          }
+        }}
+      />
+      <UploadButton 
+        label="Focus Me" 
+        onSelect={action('focus-selected')}
+        sx={{
+          '&:focus-visible': {
+            outline: '2px solid',
+            outlineColor: 'primary.main',
+            outlineOffset: 2
+          }
+        }}
+      />
+    </Box>
+  )
+};
+
+export const Responsive: Story = {
+  render: () => (
+    <Box sx={{ display: 'flex', flexDirection: { xs: 'column', md: 'row' }, gap: 2, width: '100%' }}>
+      <Box sx={{ flex: 1 }}>
+        <UploadButton 
+          label="Mobile First"
+          onSelect={action('mobile-selected')}
+          sx={{ width: '100%' }}
+        />
+      </Box>
+      <Box sx={{ flex: 1 }}>
+        <UploadButton 
+          variant="dropzone"
+          label="Desktop Dropzone"
+          onSelect={action('desktop-selected')}
+        />
+      </Box>
+    </Box>
+  )
+};