@12-apps/ui 1.0.0

package/src/components/form/Toggle/Toggle.tsx

@@ -0,0 +1,265 @@
+import type { Theme} from '@mui/material';
+import { alpha, keyframes,ToggleButton } from '@mui/material';
+import { styled } from '@mui/material/styles';
+import React, { forwardRef } from 'react';
+
+import type { ToggleProps } from './Toggle.types';
+
+const glowAnimation = keyframes`
+  0% { box-shadow: 0 0 5px currentColor; }
+  50% { box-shadow: 0 0 15px currentColor, 0 0 25px currentColor; }
+  100% { box-shadow: 0 0 5px currentColor; }
+`;
+
+// Ripple animation - reserved for future use
+// const rippleAnimation = keyframes`
+//   0% {
+//     transform: scale(0);
+//     opacity: 1;
+//   }
+//   100% {
+//     transform: scale(4);
+//     opacity: 0;
+//   }
+// `;
+
+const floatAnimation = keyframes`
+  0%, 100% { transform: translateY(0px); }
+  50% { transform: translateY(-2px); }
+`;
+
+const getColorFromTheme = (theme: Theme, color: string) => {
+  if (color === 'neutral') {
+    return {
+      main: theme.palette.grey?.[700] || '#616161',
+      dark: theme.palette.grey?.[800] || '#424242',
+      light: theme.palette.grey?.[500] || '#9e9e9e',
+      contrastText: '#fff',
+    };
+  }
+
+  const colorMap: Record<string, typeof theme.palette.primary> = {
+    primary: theme.palette.primary,
+    secondary: theme.palette.secondary,
+    success: theme.palette.success,
+    warning: theme.palette.warning,
+    danger: theme.palette.error,
+  };
+
+  const palette = colorMap[color] || theme.palette.primary;
+
+  // Ensure palette has required properties
+  return {
+    main: palette?.main || theme.palette.primary.main,
+    dark: palette?.dark || palette?.main || theme.palette.primary.dark,
+    light: palette?.light || palette?.main || theme.palette.primary.light,
+    contrastText: palette?.contrastText || '#fff',
+  };
+};
+
+const StyledToggle = styled(ToggleButton, {
+  shouldForwardProp: (prop) =>
+    !['customVariant', 'customColor', 'customSize', 'glow', 'glass', 'gradient'].includes(
+      prop as string,
+    ),
+})<{
+  customVariant?: string;
+  customColor?: string;
+  customSize?: string;
+  glow?: boolean;
+  glass?: boolean;
+  gradient?: boolean;
+}>(({
+  theme,
+  customVariant,
+  customColor = 'primary',
+  customSize = 'md',
+  glow,
+  glass,
+  gradient,
+}) => {
+  const colorPalette = getColorFromTheme(theme, customColor);
+
+  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' },
+  };
+
+  const baseStyles = {
+    textTransform: 'none' as const,
+    fontWeight: 500,
+    borderRadius: theme.spacing(1),
+    transition: 'all 0.3s cubic-bezier(0.4, 0, 0.2, 1)',
+    border: `2px solid ${alpha(theme.palette.divider, 0.3)}`,
+    color: theme.palette.text.primary,
+    backgroundColor: 'transparent',
+    position: 'relative' as const,
+    overflow: 'hidden' as const,
+
+    '&::before': {
+      content: '""',
+      position: 'absolute',
+      top: '50%',
+      left: '50%',
+      width: 0,
+      height: 0,
+      borderRadius: '50%',
+      backgroundColor: alpha(colorPalette.main, 0.2),
+      transform: 'translate(-50%, -50%)',
+      transition: 'width 0.4s, height 0.4s',
+    },
+
+    '&:hover': {
+      backgroundColor: alpha(colorPalette.main, 0.08),
+      borderColor: colorPalette.main,
+      transform: 'translateY(-1px)',
+      boxShadow: `0 4px 8px ${alpha(colorPalette.main, 0.15)}`,
+      animation: `${floatAnimation} 2s ease-in-out infinite`,
+
+      '&::before': {
+        width: '100%',
+        height: '100%',
+      },
+    },
+
+    '&:active': {
+      transform: 'scale(0.98)',
+    },
+
+    '&.Mui-selected': {
+      backgroundColor: colorPalette.main,
+      color: colorPalette.contrastText || '#fff',
+      borderColor: colorPalette.main,
+      boxShadow: `0 2px 8px ${alpha(colorPalette.main, 0.3)}`,
+
+      '&::after': {
+        content: '""',
+        position: 'absolute',
+        top: 0,
+        left: 0,
+        right: 0,
+        bottom: 0,
+        background: `linear-gradient(135deg, transparent, ${alpha('#fff', 0.1)})`,
+        pointerEvents: 'none',
+      },
+
+      '&:hover': {
+        backgroundColor: colorPalette.dark,
+        transform: 'translateY(-2px) scale(1.02)',
+        boxShadow: `0 6px 20px ${alpha(colorPalette.main, 0.4)}`,
+      },
+    },
+
+    ...sizeMap[customSize as keyof typeof sizeMap],
+  };
+
+  const variantStyles = {
+    ...(customVariant === 'outline' && {
+      backgroundColor: 'transparent',
+      border: `2px solid ${colorPalette.main}`,
+      color: colorPalette.main,
+
+      '&.Mui-selected': {
+        backgroundColor: colorPalette.main,
+        color: colorPalette.contrastText || '#fff',
+      },
+    }),
+
+    ...(customVariant === 'soft' && {
+      backgroundColor: alpha(colorPalette.main, 0.1),
+      border: 'none',
+      color: colorPalette.main,
+
+      '&.Mui-selected': {
+        backgroundColor: alpha(colorPalette.main, 0.2),
+        color: colorPalette.main,
+      },
+    }),
+  };
+
+  const effectStyles = {
+    ...(glass && {
+      backgroundColor: alpha(theme.palette.background.paper, 0.1),
+      backdropFilter: 'blur(20px)',
+      border: `1px solid ${alpha(theme.palette.divider, 0.2)}`,
+    }),
+
+    ...(gradient && {
+      '&.Mui-selected': {
+        background: `linear-gradient(135deg, ${colorPalette.light}, ${colorPalette.main}, ${colorPalette.dark})`,
+        backgroundSize: '200% 200%',
+        animation: `${floatAnimation} 3s ease-in-out infinite`,
+        border: 'none',
+
+        '&:hover': {
+          backgroundPosition: '100% 100%',
+        },
+      },
+    }),
+
+    ...(glow && {
+      '&.Mui-selected': {
+        animation: `${glowAnimation} 2s ease-in-out infinite`,
+        boxShadow: `0 0 15px ${alpha(colorPalette.main, 0.6)}`,
+      },
+    }),
+  };
+
+  return {
+    ...baseStyles,
+    ...variantStyles,
+    ...effectStyles,
+  };
+});
+
+export const Toggle = forwardRef<HTMLButtonElement, ToggleProps>(
+  (
+    {
+      variant = 'default',
+      color = 'primary',
+      size = 'md',
+      icon,
+      glow = false,
+      glass = false,
+      gradient = false,
+      dataTestId,
+      children,
+      ...props
+    },
+    ref,
+  ) => {
+    const testIds = {
+      container: dataTestId,
+      icon: dataTestId ? `${dataTestId}-icon` : undefined,
+    };
+
+    return (
+      <StyledToggle
+        ref={ref}
+        customVariant={variant}
+        customColor={color}
+        customSize={size}
+        glow={glow}
+        glass={glass}
+        gradient={gradient}
+        data-testid={testIds.container}
+        {...props}
+      >
+        {icon && (
+          <span
+            style={{ marginRight: children ? '8px' : '0' }}
+            data-testid={testIds.icon}
+          >
+            {icon}
+          </span>
+        )}
+        {children}
+      </StyledToggle>
+    );
+  },
+);
+
+Toggle.displayName = 'Toggle';

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

@@ -0,0 +1,79 @@
+import type { ToggleButtonProps } from '@mui/material';
+import type React from 'react';
+
+export interface ToggleProps extends Omit<ToggleButtonProps, 'color' | 'size'> {
+  /**
+   * The variant of the toggle
+   */
+  variant?: 'default' | 'outline' | 'soft';
+  
+  /**
+   * The color theme of the toggle
+   */
+  color?: 'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'neutral';
+  
+  /**
+   * The size of the toggle
+   */
+  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+  
+  /**
+   * Icon for the toggle
+   */
+  icon?: React.ReactNode;
+  
+  /**
+   * Whether the toggle should have a glow effect
+   */
+  glow?: boolean;
+  
+  /**
+   * Whether the toggle should have glass morphism effect
+   */
+  glass?: boolean;
+  
+  /**
+   * Whether the toggle should have gradient effects
+   */
+  gradient?: boolean;
+  
+  /**
+   * Whether the toggle is in loading state
+   */
+  loading?: boolean;
+  
+  /**
+   * Whether to show ripple effect
+   */
+  ripple?: boolean;
+  
+  /**
+   * Whether the toggle should have pulse animation
+   */
+  pulse?: boolean;
+  
+  /**
+   * Click handler
+   */
+  onClick?: (event: React.MouseEvent<HTMLElement>, value: string | number | undefined) => void;
+  
+  /**
+   * Focus handler
+   */
+  onFocus?: React.FocusEventHandler<HTMLButtonElement>;
+  
+  /**
+   * Blur handler
+   */
+  onBlur?: React.FocusEventHandler<HTMLButtonElement>;
+  
+  /**
+   * Change handler
+   */
+  onChange?: (event: React.MouseEvent<HTMLElement>, value: string | number | undefined) => void;
+
+  /**
+   * Test ID for the toggle button (applied via data-testid)
+   */
+  dataTestId?: string;
+}

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

@@ -0,0 +1,2 @@
+export { Toggle } from './Toggle';
+export type { ToggleProps } from './Toggle.types';

package/src/components/form/ToggleGroup/ToggleGroup.md

@@ -0,0 +1,329 @@
+# ToggleGroup Component
+
+A flexible toggle button group component that allows single or multiple selection from a set of options. Built on top of MUI's ToggleButtonGroup with enhanced styling and additional features.
+
+## Purpose
+
+The ToggleGroup component is ideal for:
+
+- Allowing users to select from mutually exclusive options (single selection)
+- Enabling multiple selections from a group of related options
+- Creating tool bars with toggle functionality (text formatting, alignment, etc.)
+- Building interface controls that require on/off states for multiple items
+
+## Features
+
+- **Multiple Selection Modes**: Single, multiple, or exclusive selection
+- **Rich Options**: Support for icons, labels, and disabled states
+- **Visual Effects**: Glass morphism, gradient, and glow effects
+- **Responsive Sizing**: Five size variants (xs, sm, md, lg, xl)
+- **Theme Integration**: Six color themes with consistent styling
+- **Accessibility**: Full keyboard navigation and screen reader support
+
+## Props
+
+### Core Props
+
+| Prop      | Type                                                                          | Default     | Description                        |
+| --------- | ----------------------------------------------------------------------------- | ----------- | ---------------------------------- |
+| `options` | `ToggleOption[]`                                                              | -           | Array of toggle options to display |
+| `variant` | `'single' \| 'multiple' \| 'exclusive'`                                       | `'single'`  | Selection behavior mode            |
+| `color`   | `'primary' \| 'secondary' \| 'success' \| 'warning' \| 'danger' \| 'neutral'` | `'primary'` | Color theme                        |
+| `size`    | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`                                        | `'md'`      | Component size                     |
+
+### Visual Enhancement Props
+
+| Prop       | Type      | Default | Description                         |
+| ---------- | --------- | ------- | ----------------------------------- |
+| `glow`     | `boolean` | `false` | Adds subtle glow effect             |
+| `glass`    | `boolean` | `false` | Applies glass morphism styling      |
+| `gradient` | `boolean` | `false` | Enables gradient background effects |
+
+### ToggleOption Interface
+
+```typescript
+interface ToggleOption {
+  value: string; // Unique identifier for the option
+  label: string; // Display text for the option
+  icon?: ReactNode; // Optional icon to display
+  disabled?: boolean; // Whether the option is disabled
+}
+```
+
+## Usage Examples
+
+### Basic Usage
+
+```tsx
+import { ToggleGroup } from '@procurement/ui';
+
+const alignOptions = [
+  { value: 'left', label: 'Left' },
+  { value: 'center', label: 'Center' },
+  { value: 'right', label: 'Right' },
+];
+
+function BasicExample() {
+  const [value, setValue] = useState('');
+
+  return (
+    <ToggleGroup
+      options={alignOptions}
+      value={value}
+      onChange={(event, newValue) => setValue(newValue || '')}
+    />
+  );
+}
+```
+
+### Multiple Selection
+
+```tsx
+const formatOptions = [
+  { value: 'bold', label: 'Bold', icon: <Bold size={16} /> },
+  { value: 'italic', label: 'Italic', icon: <Italic size={16} /> },
+  { value: 'underline', label: 'Underline', icon: <Underline size={16} /> },
+];
+
+function MultipleExample() {
+  const [values, setValues] = useState(['bold']);
+
+  return (
+    <ToggleGroup
+      variant="multiple"
+      options={formatOptions}
+      value={values}
+      onChange={(event, newValues) => setValues(newValues || [])}
+      color="secondary"
+    />
+  );
+}
+```
+
+### With Visual Effects
+
+```tsx
+function StyledExample() {
+  const [theme, setTheme] = useState('light');
+
+  return (
+    <ToggleGroup
+      glass
+      gradient
+      glow
+      options={themeOptions}
+      value={theme}
+      onChange={(event, newTheme) => setTheme(newTheme || 'light')}
+      color="success"
+      size="lg"
+    />
+  );
+}
+```
+
+## Selection Modes
+
+### Single Selection
+
+- Default behavior
+- Only one option can be selected at a time
+- Clicking selected option deselects it
+- Value type: `string | null`
+
+### Multiple Selection
+
+- Multiple options can be selected simultaneously
+- Clicking toggles individual options on/off
+- Value type: `string[]`
+
+### Exclusive Selection
+
+- Exactly one option must always be selected
+- Clicking selected option does not deselect it
+- Useful for required choices like themes or modes
+- Value type: `string`
+
+## Accessibility
+
+The ToggleGroup component follows WCAG guidelines:
+
+- **Keyboard Navigation**: Full keyboard support with Tab, Space, and Enter keys
+- **Screen Readers**: Proper ARIA attributes for group role and state announcements
+- **Focus Management**: Clear focus indicators and logical tab order
+- **High Contrast**: Respects system high contrast preferences
+- **Touch Targets**: Minimum 44px touch targets for mobile accessibility
+
+## Best Practices
+
+1. **Option Labels**: Use clear, concise labels that describe the action or state
+2. **Icon Usage**: Combine icons with labels for better usability, use icons alone only for universally recognized actions
+3. **Group Size**: Limit to 2-8 options for optimal usability
+4. **Disabled States**: Provide clear visual feedback for disabled options
+5. **Loading States**: Handle loading scenarios gracefully with appropriate feedback
+6. **Responsive Design**: Test across different screen sizes and orientations
+
+## Testing
+
+The ToggleGroup component includes comprehensive test support with data-testid attributes for reliable automated testing.
+
+### TestId Structure
+
+The component uses a consistent pattern for testIds:
+
+- **Container**: Uses the `dataTestId` prop value (default: `toggle-group`)
+- **Toggle Items**: Format: `${dataTestId}-item-${option.value}`
+
+### Default TestIds
+
+```tsx
+<ToggleGroup
+  options={[
+    { value: 'left', label: 'Left' },
+    { value: 'center', label: 'Center' },
+    { value: 'right', label: 'Right' },
+  ]}
+/>
+```
+
+Generated testIds:
+- Container: `toggle-group`
+- Items: `toggle-group-item-left`, `toggle-group-item-center`, `toggle-group-item-right`
+
+### Custom TestIds
+
+```tsx
+<ToggleGroup
+  options={alignOptions}
+  dataTestId="text-alignment"
+/>
+```
+
+Generated testIds:
+- Container: `text-alignment`
+- Items: `text-alignment-item-left`, `text-alignment-item-center`, `text-alignment-item-right`
+
+### Testing with React Testing Library
+
+```tsx
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+test('should allow selection via testId', async () => {
+  const user = userEvent.setup();
+  const handleChange = vi.fn();
+
+  render(
+    <ToggleGroup
+      options={options}
+      onChange={handleChange}
+      dataTestId="my-toggle"
+    />
+  );
+
+  // Find container
+  const container = screen.getByTestId('my-toggle');
+  expect(container).toBeInTheDocument();
+
+  // Find and interact with specific item
+  const item = screen.getByTestId('my-toggle-item-left');
+  await user.click(item);
+
+  expect(handleChange).toHaveBeenCalled();
+});
+```
+
+### Testing with Playwright
+
+```typescript
+test('toggle selection', async ({ page }) => {
+  // Navigate to page with toggle group
+  await page.goto('/my-page');
+
+  // Find container
+  const toggleGroup = page.getByTestId('toggle-group');
+  await expect(toggleGroup).toBeVisible();
+
+  // Click specific toggle item
+  await page.getByTestId('toggle-group-item-center').click();
+
+  // Verify selection state
+  await expect(page.getByTestId('toggle-group-item-center')).toHaveAttribute('aria-pressed', 'true');
+});
+```
+
+### Testing Multiple States
+
+```tsx
+test('should handle multiple selection mode', async () => {
+  const user = userEvent.setup();
+
+  render(
+    <ToggleGroup
+      variant="multiple"
+      options={formatOptions}
+      dataTestId="format-toggle"
+    />
+  );
+
+  // Select multiple items
+  await user.click(screen.getByTestId('format-toggle-item-bold'));
+  await user.click(screen.getByTestId('format-toggle-item-italic'));
+
+  // Both should be selected
+  expect(screen.getByTestId('format-toggle-item-bold')).toHaveAttribute('aria-pressed', 'true');
+  expect(screen.getByTestId('format-toggle-item-italic')).toHaveAttribute('aria-pressed', 'true');
+});
+```
+
+### Testing Disabled States
+
+```tsx
+test('should respect disabled state', async () => {
+  const user = userEvent.setup();
+
+  render(
+    <ToggleGroup
+      options={[
+        { value: 'enabled', label: 'Enabled' },
+        { value: 'disabled', label: 'Disabled', disabled: true },
+      ]}
+      dataTestId="mixed-toggle"
+    />
+  );
+
+  const disabledItem = screen.getByTestId('mixed-toggle-item-disabled');
+  expect(disabledItem).toBeDisabled();
+
+  // Attempt to click disabled item
+  await user.click(disabledItem);
+
+  // Should remain unselected
+  expect(disabledItem).toHaveAttribute('aria-pressed', 'false');
+});
+```
+
+### Best Practices for Testing
+
+1. **Use descriptive testIds**: Choose testIds that clearly identify the component's purpose
+2. **Test user interactions**: Verify click events, keyboard navigation, and state changes
+3. **Check accessibility**: Ensure proper ARIA attributes are present
+4. **Test edge cases**: Include tests for disabled states, empty options, and special characters
+5. **Verify visual states**: Test glass, gradient, and glow effects when applicable
+
+## Common Patterns
+
+### Toolbar Controls
+
+Perfect for text editor toolbars, media controls, or any interface requiring multiple toggle states.
+
+### Settings Panels
+
+Use exclusive mode for required settings like theme selection or display modes.
+
+### Filtering Interfaces
+
+Multiple selection mode works well for filter controls where users can select multiple criteria.
+
+### Form Controls
+
+Integration with form libraries for controlled form state management.