@12-apps/ui 1.0.0

package/src/components/form/Input/Input.tsx

@@ -0,0 +1,263 @@
+import {
+  alpha,
+  CircularProgress,
+  InputAdornment,
+  keyframes,
+  styled,
+  TextField,
+} from '@mui/material';
+import React from 'react';
+
+import type { InputProps } from './Input.types';
+
+// Define pulse animation
+const pulseAnimation = keyframes`
+  0% {
+    box-shadow: 0 0 0 0 currentColor;
+    opacity: 1;
+  }
+  70% {
+    box-shadow: 0 0 0 10px currentColor;
+    opacity: 0;
+  }
+  100% {
+    box-shadow: 0 0 0 0 currentColor;
+    opacity: 0;
+  }
+`;
+
+const StyledTextField = styled(TextField, {
+  shouldForwardProp: (prop) =>
+    !['customVariant', 'floating', 'glow', 'pulse', 'loading'].includes(prop as string),
+})<{
+  customVariant?: InputProps['variant'];
+  floating?: boolean;
+  glow?: boolean;
+  pulse?: boolean;
+  loading?: boolean;
+}>(({ theme, customVariant, floating, glow, pulse, loading }) => ({
+  position: 'relative',
+  opacity: loading ? 0.7 : 1,
+
+  // Glow effect
+  ...(glow && {
+    '& .MuiInputBase-root': {
+      boxShadow: `0 0 15px ${alpha(theme.palette.primary.main, 0.3)}`,
+      '&.Mui-focused': {
+        boxShadow: `0 0 20px ${alpha(theme.palette.primary.main, 0.5)}`,
+      },
+    },
+  }),
+
+  // Pulse animation
+  ...(pulse && {
+    '&::after': {
+      content: '""',
+      position: 'absolute',
+      top: '50%',
+      left: '0',
+      right: '0',
+      height: '56px',
+      transform: 'translateY(-50%)',
+      borderRadius: theme.spacing(0.5),
+      backgroundColor: theme.palette.primary.main,
+      opacity: 0.3,
+      animation: `${pulseAnimation} 2s infinite`,
+      pointerEvents: 'none',
+      zIndex: -1,
+    },
+  }),
+
+  '& .MuiInputBase-root': {
+    transition: 'all 0.3s ease',
+
+    ...(customVariant === 'glass' && {
+      backgroundColor: alpha(theme.palette.background.paper, 0.1),
+      backdropFilter: 'blur(20px)',
+      border: `1px solid ${alpha(theme.palette.divider, 0.2)}`,
+      '&:hover': {
+        backgroundColor: alpha(theme.palette.background.paper, 0.15),
+        borderColor: alpha(theme.palette.primary.main, 0.3),
+      },
+      '&.Mui-focused': {
+        backgroundColor: alpha(theme.palette.background.paper, 0.2),
+        borderColor: theme.palette.primary.main,
+        boxShadow: `0 0 0 2px ${alpha(theme.palette.primary.main, 0.1)}`,
+      },
+    }),
+
+    ...(customVariant === 'underline' && {
+      '&:before': {
+        borderBottomColor: alpha(theme.palette.divider, 0.42),
+      },
+      '&:hover:not(.Mui-disabled):before': {
+        borderBottomColor: theme.palette.primary.main,
+      },
+      '&:after': {
+        borderBottomColor: theme.palette.primary.main,
+      },
+    }),
+
+    ...(customVariant === 'gradient' && {
+      background: `linear-gradient(135deg, ${alpha(theme.palette.primary.main, 0.1)}, ${alpha(theme.palette.secondary.main, 0.1)})`,
+      border: `2px solid transparent`,
+      backgroundOrigin: 'border-box',
+      backgroundClip: 'padding-box, border-box',
+      position: 'relative',
+      '&::before': {
+        content: '""',
+        position: 'absolute',
+        top: 0,
+        left: 0,
+        right: 0,
+        bottom: 0,
+        borderRadius: 'inherit',
+        background: `linear-gradient(135deg, ${theme.palette.primary.main}, ${theme.palette.secondary.main})`,
+        mask: 'linear-gradient(#fff 0 0) content-box, linear-gradient(#fff 0 0)',
+        maskComposite: 'exclude',
+        padding: '2px',
+        zIndex: -1,
+      },
+      '&:hover': {
+        background: `linear-gradient(135deg, ${alpha(theme.palette.primary.main, 0.15)}, ${alpha(theme.palette.secondary.main, 0.15)})`,
+      },
+      '&.Mui-focused': {
+        background: `linear-gradient(135deg, ${alpha(theme.palette.primary.main, 0.2)}, ${alpha(theme.palette.secondary.main, 0.2)})`,
+        '&::before': {
+          background: `linear-gradient(135deg, ${theme.palette.primary.dark}, ${theme.palette.secondary.dark})`,
+        },
+      },
+    }),
+  },
+
+  ...(floating && {
+    '& .MuiInputLabel-root': {
+      transform: 'translate(14px, 16px) scale(1)',
+      '&.MuiInputLabel-shrink': {
+        transform: 'translate(14px, -9px) scale(0.75)',
+        backgroundColor: theme.palette.background.paper,
+        padding: '0 4px',
+      },
+    },
+  }),
+
+  '& .MuiOutlinedInput-root': {
+    '& fieldset': {
+      borderColor: alpha(theme.palette.divider, 0.23),
+    },
+    '&:hover fieldset': {
+      borderColor: theme.palette.primary.main,
+    },
+    '&.Mui-focused fieldset': {
+      borderColor: theme.palette.primary.main,
+      borderWidth: 2,
+    },
+    '&.Mui-error fieldset': {
+      borderColor: theme.palette.error.main,
+    },
+  },
+
+  '& .MuiFilledInput-root': {
+    backgroundColor: alpha(theme.palette.action.hover, 0.04),
+    '&:hover': {
+      backgroundColor: alpha(theme.palette.action.hover, 0.08),
+    },
+    '&.Mui-focused': {
+      backgroundColor: alpha(theme.palette.action.hover, 0.12),
+    },
+  },
+}));
+
+const sizeMap = {
+  sm: { size: 'small' as const },
+  md: { size: 'medium' as const },
+  lg: { size: 'medium' as const, sx: { '& .MuiInputBase-input': { padding: '16px 14px' } } },
+};
+
+export const Input = React.forwardRef<HTMLInputElement, InputProps>(
+  (
+    {
+      variant = 'outlined',
+      size = 'md',
+      label,
+      error,
+      helperText,
+      startAdornment,
+      endAdornment,
+      fullWidth = true,
+      floating = false,
+      glow = false,
+      pulse = false,
+      loading = false,
+      onClick,
+      onFocus,
+      onBlur,
+      'data-testid': dataTestId,
+      ...props
+    },
+    ref,
+  ) => {
+    const handleFocus = (e: React.FocusEvent<HTMLInputElement>) => {
+      onFocus?.(e);
+    };
+
+    const handleBlur = (e: React.FocusEvent<HTMLInputElement>) => {
+      onBlur?.(e);
+    };
+
+    const muiVariant =
+      variant === 'glass'
+        ? 'outlined'
+        : variant === 'underline'
+          ? 'standard'
+          : variant === 'gradient'
+            ? 'outlined'
+            : variant;
+
+    const sizeProps = sizeMap[size];
+
+    return (
+      <StyledTextField
+        ref={ref}
+        variant={muiVariant as 'outlined' | 'filled' | 'standard'}
+        customVariant={variant}
+        floating={floating}
+        glow={glow}
+        pulse={pulse}
+        loading={loading}
+        label={label}
+        error={error}
+        helperText={helperText}
+        fullWidth={fullWidth}
+        disabled={loading || props.disabled}
+        onClick={!loading ? onClick : undefined}
+        onFocus={handleFocus}
+        onBlur={handleBlur}
+        inputProps={{
+          'data-testid': dataTestId,
+        }}
+        InputProps={{
+          startAdornment: startAdornment && (
+            <InputAdornment position="start">{startAdornment}</InputAdornment>
+          ),
+          endAdornment: (
+            <>
+              {loading && (
+                <InputAdornment position="end">
+                  <CircularProgress size={20} />
+                </InputAdornment>
+              )}
+              {!loading && endAdornment && (
+                <InputAdornment position="end">{endAdornment}</InputAdornment>
+              )}
+            </>
+          ),
+        }}
+        {...sizeProps}
+        {...props}
+      />
+    );
+  },
+);
+
+Input.displayName = 'Input';

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

@@ -0,0 +1,24 @@
+import type { InputHTMLAttributes, ReactNode } from 'react';
+import type React from 'react';
+
+export type InputVariant = 'outlined' | 'filled' | 'glass' | 'underline' | 'gradient';
+export type InputSize = 'sm' | 'md' | 'lg';
+
+export interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size' | 'color'> {
+  variant?: InputVariant;
+  size?: InputSize;
+  label?: string;
+  error?: boolean;
+  helperText?: string;
+  startAdornment?: ReactNode;
+  endAdornment?: ReactNode;
+  fullWidth?: boolean;
+  floating?: boolean;
+  glow?: boolean;
+  pulse?: boolean;
+  loading?: boolean;
+  onClick?: React.MouseEventHandler<HTMLInputElement>;
+  onFocus?: React.FocusEventHandler<HTMLInputElement>;
+  onBlur?: React.FocusEventHandler<HTMLInputElement>;
+  'data-testid'?: string;
+}

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

@@ -0,0 +1,2 @@
+export { Input } from './Input';
+export type { InputProps, InputSize,InputVariant } from './Input.types';

package/src/components/form/InputOTP/InputOTP.md

@@ -0,0 +1,419 @@
+# InputOTP Component
+
+## Overview
+
+The InputOTP component provides a specialized input field for one-time passwords and verification codes. It splits the input into individual digit boxes with automatic focus management, making it ideal for SMS verification codes, two-factor authentication, and other security-related inputs.
+
+## Features
+
+- **Multiple Input Variants**: Supports numeric-only, alphanumeric, and masked input modes
+- **Auto-Focus Management**: Automatically advances focus to the next input as users type
+- **Keyboard Navigation**: Full support for arrow keys, backspace, and tab navigation
+- **Paste Support**: Users can paste complete codes for quick entry
+- **Visual Effects**: Optional glass morphism and gradient effects for modern UI design
+- **Flexible Sizing**: Five size variants from extra-small to extra-large
+- **Theme Integration**: Six color themes matching your design system
+- **Accessibility**: WCAG compliant with proper ARIA attributes and keyboard support
+- **Responsive Design**: Adapts to different screen sizes and touch interfaces
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `'numeric' \| 'alphanumeric' \| 'masked'` | `'numeric'` | Input validation type |
+| `length` | `number` | `6` | Number of input digits |
+| `value` | `string` | `''` | Current OTP value |
+| `onChange` | `(value: string) => void` | - | Callback when value changes |
+| `onComplete` | `(value: string) => void` | - | Callback when all digits are filled |
+| `color` | `'primary' \| 'secondary' \| 'success' \| 'warning' \| 'danger' \| 'neutral'` | `'primary'` | Theme color |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Input size |
+| `autoFocus` | `boolean` | `false` | Auto-focus first input on mount |
+| `disabled` | `boolean` | `false` | Disable all inputs |
+| `error` | `boolean` | `false` | Show error state |
+| `glass` | `boolean` | `false` | Apply glass morphism effect |
+| `gradient` | `boolean` | `false` | Apply gradient focus effect |
+| `className` | `string` | - | Additional CSS classes |
+| `aria-label` | `string` | - | Accessibility label |
+
+## Usage Examples
+
+### Basic Usage
+
+```tsx
+import { InputOTP } from '@procurement/ui';
+
+function VerificationForm() {
+  const [code, setCode] = useState('');
+
+  const handleComplete = (value: string) => {
+    console.log('Verification code:', value);
+    // Submit verification code
+  };
+
+  return (
+    <InputOTP
+      value={code}
+      onChange={setCode}
+      onComplete={handleComplete}
+      autoFocus
+    />
+  );
+}
+```
+
+### SMS Verification
+
+```tsx
+<InputOTP
+  variant="numeric"
+  length={4}
+  color="primary"
+  size="lg"
+  autoFocus
+  onComplete={(code) => verifySMSCode(code)}
+  aria-label="Enter SMS verification code"
+/>
+```
+
+### Two-Factor Authentication
+
+```tsx
+<InputOTP
+  variant="numeric"
+  length={6}
+  color="success"
+  glass
+  onComplete={(code) => verify2FA(code)}
+  aria-label="Enter 6-digit authenticator code"
+/>
+```
+
+### Masked Security PIN
+
+```tsx
+<InputOTP
+  variant="masked"
+  length={4}
+  color="warning"
+  onComplete={(pin) => validatePIN(pin)}
+  aria-label="Enter your security PIN"
+/>
+```
+
+### Alphanumeric Code
+
+```tsx
+<InputOTP
+  variant="alphanumeric"
+  length={8}
+  color="secondary"
+  gradient
+  onComplete={(code) => validateCode(code)}
+  aria-label="Enter product activation code"
+/>
+```
+
+### Error State Handling
+
+```tsx
+function CodeVerification() {
+  const [code, setCode] = useState('');
+  const [hasError, setHasError] = useState(false);
+
+  const handleComplete = async (value: string) => {
+    const isValid = await verifyCode(value);
+    setHasError(!isValid);
+    
+    if (isValid) {
+      // Proceed with success
+    }
+  };
+
+  return (
+    <>
+      <InputOTP
+        value={code}
+        onChange={setCode}
+        onComplete={handleComplete}
+        error={hasError}
+        color={hasError ? 'danger' : 'primary'}
+      />
+      {hasError && (
+        <Typography color="error" variant="caption">
+          Invalid verification code. Please try again.
+        </Typography>
+      )}
+    </>
+  );
+}
+```
+
+## Keyboard Shortcuts
+
+- **Arrow Left/Right**: Navigate between input fields
+- **Backspace**: Delete current digit and move to previous field
+- **Tab**: Move to next field
+- **Shift+Tab**: Move to previous field
+- **Delete**: Clear current field
+- **Paste (Ctrl/Cmd+V)**: Paste complete code
+
+## Accessibility
+
+The InputOTP component is designed with accessibility in mind:
+
+- **ARIA Labels**: Each input field has proper ARIA attributes
+- **Keyboard Navigation**: Full keyboard support for all interactions
+- **Focus Management**: Clear focus indicators and logical tab order
+- **Screen Reader Support**: Announces field positions and values
+- **Error States**: Clear visual and semantic error indicators
+
+### Best Practices
+
+1. **Always provide an aria-label** describing what code is being entered
+2. **Use appropriate variants** - numeric for numbers only, masked for PINs
+3. **Provide clear error messages** when verification fails
+4. **Consider mobile users** - use larger sizes on touch devices
+5. **Test with keyboard navigation** to ensure accessibility
+
+## Styling
+
+The component supports various visual customizations:
+
+### Size Variants
+- `xs`: Extra small (compact forms)
+- `sm`: Small (mobile interfaces)
+- `md`: Medium (default desktop)
+- `lg`: Large (prominent forms)
+- `xl`: Extra large (accessibility focus)
+
+### Color Themes
+- `primary`: Main brand color
+- `secondary`: Alternative brand color
+- `success`: Positive feedback
+- `warning`: Caution state
+- `danger`: Error or critical state
+- `neutral`: Subtle appearance
+
+### Visual Effects
+- **Glass Morphism**: Modern frosted glass effect
+- **Gradient**: Dynamic gradient on focus
+- **Combined**: Both effects for premium feel
+
+## Performance Considerations
+
+- **Controlled Component**: Use React.memo if parent re-renders frequently
+- **Debounced Callbacks**: onChange fires on every keystroke, consider debouncing
+- **Paste Handling**: Efficiently processes pasted content without blocking UI
+- **Focus Management**: Uses refs to avoid unnecessary re-renders
+
+## Common Use Cases
+
+1. **SMS Verification**: 4-6 digit codes for phone number verification
+2. **Email Verification**: 6-8 character codes for email confirmation
+3. **Two-Factor Auth**: 6-digit TOTP codes from authenticator apps
+4. **Security PINs**: 4-digit masked inputs for banking/security
+5. **Product Keys**: 8-16 character alphanumeric activation codes
+6. **Coupon Codes**: Variable length promotional codes
+7. **Access Codes**: Meeting or session join codes
+
+## Migration Guide
+
+If migrating from a text input to InputOTP:
+
+```tsx
+// Before
+<TextField
+  value={code}
+  onChange={(e) => setCode(e.target.value)}
+  maxLength={6}
+/>
+
+// After
+<InputOTP
+  value={code}
+  onChange={setCode}
+  length={6}
+  onComplete={handleVerification}
+/>
+```
+
+## Testing
+
+The InputOTP component supports automated testing through the `dataTestId` prop. When provided, it generates consistent test identifiers for both the container and individual input slots.
+
+### Test ID Structure
+
+- **Container**: Uses the `dataTestId` value directly
+- **Individual Slots**: Appends `-slot-{index}` to the `dataTestId` value (zero-indexed)
+
+### Usage in Tests
+
+```tsx
+// Component usage with testId
+<InputOTP
+  length={6}
+  dataTestId="verification-code"
+  onChange={handleChange}
+  onComplete={handleComplete}
+/>
+
+// Test implementation examples
+
+// Using Testing Library
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+test('should allow entering verification code', async () => {
+  const handleComplete = jest.fn();
+
+  render(
+    <InputOTP
+      length={6}
+      dataTestId="verification-code"
+      onComplete={handleComplete}
+    />
+  );
+
+  // Access container
+  const container = screen.getByTestId('verification-code');
+  expect(container).toBeInTheDocument();
+
+  // Access individual slots
+  const firstSlot = screen.getByTestId('verification-code-slot-0');
+  const secondSlot = screen.getByTestId('verification-code-slot-1');
+
+  // Interact with slots
+  await userEvent.type(firstSlot, '1');
+  await userEvent.type(secondSlot, '2');
+
+  expect(firstSlot).toHaveValue('1');
+  expect(secondSlot).toHaveValue('2');
+});
+
+// Using Playwright
+test('OTP input interaction', async ({ page }) => {
+  await page.goto('/verification');
+
+  // Access container
+  const otpContainer = page.getByTestId('verification-code');
+  await expect(otpContainer).toBeVisible();
+
+  // Access and interact with individual slots
+  await page.getByTestId('verification-code-slot-0').fill('1');
+  await page.getByTestId('verification-code-slot-1').fill('2');
+  await page.getByTestId('verification-code-slot-2').fill('3');
+  await page.getByTestId('verification-code-slot-3').fill('4');
+  await page.getByTestId('verification-code-slot-4').fill('5');
+  await page.getByTestId('verification-code-slot-5').fill('6');
+
+  // Verify completion
+  await expect(page.getByText('Code verified')).toBeVisible();
+});
+
+// Using Cypress
+describe('InputOTP', () => {
+  it('should complete OTP entry', () => {
+    cy.visit('/verification');
+
+    // Verify container exists
+    cy.getByTestId('verification-code').should('be.visible');
+
+    // Enter OTP code
+    cy.getByTestId('verification-code-slot-0').type('1');
+    cy.getByTestId('verification-code-slot-1').type('2');
+    cy.getByTestId('verification-code-slot-2').type('3');
+    cy.getByTestId('verification-code-slot-3').type('4');
+    cy.getByTestId('verification-code-slot-4').type('5');
+    cy.getByTestId('verification-code-slot-5').type('6');
+
+    // Verify all slots filled
+    cy.getByTestId('verification-code-slot-0').should('have.value', '1');
+    cy.getByTestId('verification-code-slot-5').should('have.value', '6');
+  });
+});
+```
+
+### Testing Best Practices
+
+1. **Always provide dataTestId in test scenarios** to ensure stable selectors
+2. **Use semantic test IDs** that describe the purpose (e.g., `sms-verification`, `2fa-code`)
+3. **Test both container and individual slots** to verify complete functionality
+4. **Verify slot indexing** is zero-based (first slot is `-slot-0`)
+5. **Test dynamic lengths** by verifying the correct number of slots exist
+6. **Test without dataTestId** to ensure component works when prop is omitted
+
+### Testing Different Configurations
+
+```tsx
+// Short OTP (4 digits)
+<InputOTP
+  length={4}
+  dataTestId="short-code"
+/>
+// Access slots: short-code-slot-0 through short-code-slot-3
+
+// Long OTP (8 characters)
+<InputOTP
+  length={8}
+  variant="alphanumeric"
+  dataTestId="activation-key"
+/>
+// Access slots: activation-key-slot-0 through activation-key-slot-7
+
+// Masked PIN
+<InputOTP
+  length={4}
+  variant="masked"
+  dataTestId="security-pin"
+/>
+// Access slots: security-pin-slot-0 through security-pin-slot-3
+```
+
+### Accessibility Testing
+
+The component maintains accessibility compliance when using testIds:
+
+```tsx
+test('should be accessible with testIds', () => {
+  const { container } = render(
+    <InputOTP
+      length={6}
+      dataTestId="accessible-otp"
+      aria-label="Enter verification code"
+    />
+  );
+
+  // Run accessibility checks
+  const results = await axe(container);
+  expect(results).toHaveNoViolations();
+
+  // Verify ARIA attributes are preserved
+  const firstSlot = screen.getByTestId('accessible-otp-slot-0');
+  expect(firstSlot).toHaveAttribute('maxLength', '1');
+});
+```
+
+### Visual Regression Testing
+
+When using visual regression tools like Chromatic or Percy:
+
+```tsx
+// Storybook story with testIds for visual testing
+export const VisualTest: Story = {
+  args: {
+    length: 6,
+    dataTestId: 'visual-otp',
+    value: '123456',
+  },
+  parameters: {
+    chromatic: { disableSnapshot: false },
+  },
+};
+```
+
+## Related Components
+
+- `TextField`: For general text input needs
+- `PasswordStrength`: For password creation with strength indicators
+- `PhoneInput`: For international phone number input
+- `Form`: For complete form management