@12-apps/ui 1.0.0

package/src/components/form/Form/Form.tsx

@@ -0,0 +1,136 @@
+import { Box, Stack, styled } from '@mui/material';
+import React from 'react';
+
+import type {
+  FormControlProps,
+  FormFieldProps,
+  FormLabelProps,
+  FormMessageProps,
+  FormProps,
+} from './Form.types';
+
+const StyledForm = styled('form', {
+  shouldForwardProp: (prop) => prop !== 'variant',
+})<{ variant?: FormProps['variant'] }>(({ theme, variant }) => ({
+  width: '100%',
+  ...(variant === 'inline' && {
+    display: 'flex',
+    gap: theme.spacing(2),
+    alignItems: 'flex-start',
+  }),
+}));
+
+const spacingMap = {
+  xs: 1,
+  sm: 2,
+  md: 3,
+  lg: 4,
+  xl: 5,
+};
+
+const maxWidthMap = {
+  sm: '600px',
+  md: '900px',
+  lg: '1200px',
+  xl: '1536px',
+  full: '100%',
+};
+
+export const Form = React.forwardRef<HTMLFormElement, FormProps>(
+  ({ variant = 'vertical', maxWidth = 'full', spacing = 'md', children, dataTestId, ...props }, ref) => (
+      <StyledForm ref={ref} variant={variant} role="form" data-testid={dataTestId} {...props}>
+        <Box sx={{ maxWidth: maxWidthMap[maxWidth], width: '100%' }}>
+          {variant === 'inline' ? (
+            children
+          ) : (
+            <Stack spacing={spacingMap[spacing]}>{children}</Stack>
+          )}
+        </Box>
+      </StyledForm>
+    ),
+);
+
+Form.displayName = 'Form';
+
+const StyledFormField = styled(Box, {
+  shouldForwardProp: (prop) => prop !== 'variant',
+})<{ variant?: 'vertical' | 'horizontal' }>(
+  ({ theme, variant }) => ({
+    display: variant === 'horizontal' ? 'grid' : 'flex',
+    flexDirection: variant === 'horizontal' ? undefined : 'column',
+    gridTemplateColumns: variant === 'horizontal' ? '200px 1fr' : undefined,
+    gap: theme.spacing(1),
+    alignItems: variant === 'horizontal' ? 'center' : undefined,
+  }),
+);
+
+export const FormField: React.FC<FormFieldProps> = ({
+  name,
+  label,
+  required,
+  error,
+  helperText,
+  children,
+  dataTestId,
+}) => (
+    <StyledFormField data-testid={dataTestId}>
+      {label && (
+        <FormLabel required={required} error={!!error} htmlFor={name} dataTestId={dataTestId ? `${dataTestId}-label` : undefined}>
+          {label}
+        </FormLabel>
+      )}
+      <FormControl fullWidth dataTestId={dataTestId ? `${dataTestId}-control` : undefined}>
+        {children}
+        {(error || helperText) && <FormMessage error={!!error} dataTestId={dataTestId ? `${dataTestId}-message` : undefined}>{error || helperText}</FormMessage>}
+      </FormControl>
+    </StyledFormField>
+  );
+
+const StyledFormLabel = styled('label', {
+  shouldForwardProp: (prop) => prop !== 'error',
+})<{ error?: boolean }>(({ theme, error }) => ({
+  fontSize: '0.875rem',
+  fontWeight: 500,
+  color: error ? theme.palette.error.main : theme.palette.text.primary,
+  marginBottom: theme.spacing(0.5),
+  display: 'block',
+  '&::after': {
+    content: '" *"',
+    color: theme.palette.error.main,
+    display: 'var(--required-display, none)',
+  },
+}));
+
+export const FormLabel: React.FC<FormLabelProps> = ({ required, error, children, htmlFor, dataTestId }) => (
+    <StyledFormLabel
+      error={error}
+      htmlFor={htmlFor}
+      data-testid={dataTestId}
+      style={{ '--required-display': required ? 'inline' : 'none' } as React.CSSProperties}
+    >
+      {children}
+    </StyledFormLabel>
+  );
+
+const StyledFormControl = styled(Box, {
+  shouldForwardProp: (prop) => prop !== 'fullWidth',
+})<{ fullWidth?: boolean }>(({ fullWidth }) => ({
+  width: fullWidth ? '100%' : 'auto',
+  position: 'relative',
+}));
+
+export const FormControl: React.FC<FormControlProps> = ({ fullWidth = true, children, dataTestId }) =>
+  // Don't pass error prop to the DOM element
+   <StyledFormControl fullWidth={fullWidth} data-testid={dataTestId}>{children}</StyledFormControl>
+;
+
+const StyledFormMessage = styled('span', {
+  shouldForwardProp: (prop) => prop !== 'error',
+})<{ error?: boolean }>(({ theme, error }) => ({
+  fontSize: '0.75rem',
+  marginTop: theme.spacing(0.5),
+  color: error ? theme.palette.error.main : theme.palette.text.secondary,
+  display: 'block',
+}));
+
+export const FormMessage: React.FC<FormMessageProps> = ({ error, children, dataTestId }) => <StyledFormMessage error={error} data-testid={dataTestId}>{children}</StyledFormMessage>;

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

@@ -0,0 +1,42 @@
+import type { FormHTMLAttributes } from 'react';
+
+export type FormVariant = 'vertical' | 'horizontal' | 'inline' | 'stepped';
+
+export interface FormProps extends FormHTMLAttributes<HTMLFormElement> {
+  variant?: FormVariant;
+  maxWidth?: 'sm' | 'md' | 'lg' | 'xl' | 'full';
+  spacing?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+  children: React.ReactNode;
+  dataTestId?: string;
+}
+
+export interface FormFieldProps {
+  name: string;
+  label?: string;
+  required?: boolean;
+  error?: string;
+  helperText?: string;
+  children: React.ReactNode;
+  dataTestId?: string;
+}
+
+export interface FormLabelProps {
+  required?: boolean;
+  error?: boolean;
+  children: React.ReactNode;
+  htmlFor?: string;
+  dataTestId?: string;
+}
+
+export interface FormControlProps {
+  error?: boolean;
+  fullWidth?: boolean;
+  children: React.ReactNode;
+  dataTestId?: string;
+}
+
+export interface FormMessageProps {
+  error?: boolean;
+  children: React.ReactNode;
+  dataTestId?: string;
+}

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

@@ -0,0 +1,8 @@
+export { Form, FormControl, FormField, FormLabel, FormMessage } from './Form';
+export type {
+  FormControlProps,
+  FormFieldProps,
+  FormLabelProps,
+  FormMessageProps,
+  FormProps,
+} from './Form.types';

package/src/components/form/Input/Input.md

@@ -0,0 +1,252 @@
+# Input Component
+
+## Purpose
+The Input component provides a flexible text input field with comprehensive validation, styling options, and accessibility features. It supports various input types, states, and integration with form libraries.
+
+## Features
+- Multiple visual variants (outlined, filled, glass, underline, gradient)
+- Three size options (sm, md, lg)
+- Support for different input types (text, email, password, number, tel, url)
+- Loading states with spinner indicator
+- Error states with helper text
+- Floating label animations
+- Visual effects (glow, pulse)
+- Start and end adornments for icons
+- Full keyboard navigation support
+- Screen reader compatibility
+- Responsive design
+
+## Props Documentation
+
+### Core Props
+- `variant`: Visual variant of the input ('outlined' | 'filled' | 'glass' | 'underline' | 'gradient')
+- `size`: Size of the input ('sm' | 'md' | 'lg')
+- `label`: Label text for the input
+- `placeholder`: Placeholder text
+- `value`: Controlled input value
+- `defaultValue`: Uncontrolled default value
+- `onChange`: Change event handler
+
+### State Props
+- `disabled`: Disables the input
+- `readOnly`: Makes input read-only
+- `required`: Marks input as required
+- `error`: Error state flag
+- `helperText`: Helper or error text displayed below input
+- `loading`: Shows loading spinner and disables input
+
+### Visual Props
+- `fullWidth`: Makes input take full container width (default: true)
+- `floating`: Enables floating label animation
+- `glow`: Adds glow effect on focus
+- `pulse`: Adds pulse animation
+
+### Adornment Props
+- `startAdornment`: Content to display at the start of the input
+- `endAdornment`: Content to display at the end of the input
+
+## Usage Examples
+
+### Basic Input
+```tsx
+<Input
+  label="Name"
+  placeholder="Enter your name"
+  onChange={(e) => console.log(e.target.value)}
+/>
+```
+
+### With Validation
+```tsx
+<Input
+  label="Email"
+  type="email"
+  error={!isValidEmail}
+  helperText={!isValidEmail ? "Please enter a valid email" : ""}
+  required
+/>
+```
+
+### With Icons
+```tsx
+<Input
+  label="Search"
+  placeholder="Search..."
+  startAdornment={<SearchIcon />}
+  endAdornment={
+    <IconButton onClick={handleClear}>
+      <ClearIcon />
+    </IconButton>
+  }
+/>
+```
+
+### Password Input with Toggle
+```tsx
+<Input
+  label="Password"
+  type={showPassword ? 'text' : 'password'}
+  startAdornment={<LockIcon />}
+  endAdornment={
+    <IconButton onClick={() => setShowPassword(!showPassword)}>
+      {showPassword ? <VisibilityOff /> : <Visibility />}
+    </IconButton>
+  }
+/>
+```
+
+### Glass Morphism Style
+```tsx
+<Input
+  variant="glass"
+  label="Glass Input"
+  glow
+  floating
+  placeholder="Modern glass effect"
+/>
+```
+
+### Loading State
+```tsx
+<Input
+  label="Processing"
+  loading
+  placeholder="Please wait..."
+/>
+```
+
+## Accessibility
+
+### ARIA Attributes
+- Proper label association with `aria-label` or `aria-labelledby`
+- `aria-invalid` for error states
+- `aria-required` for required fields
+- `aria-describedby` for helper text association
+
+### Keyboard Navigation
+- Tab/Shift+Tab for focus navigation
+- Standard text editing keyboard shortcuts
+- Enter key support for form submission
+
+### Screen Reader Support
+- Clear label announcements
+- Error state announcements
+- Helper text announcements
+- Loading state announcements
+
+## Best Practices
+
+1. **Always provide labels**: Use the `label` prop for accessibility
+2. **Error handling**: Provide clear error messages in `helperText`
+3. **Loading states**: Use `loading` prop during async operations
+4. **Icon usage**: Use meaningful icons that enhance UX
+5. **Validation**: Validate on blur rather than on every keystroke
+6. **Required fields**: Mark required fields clearly
+7. **Placeholder text**: Use placeholders as hints, not labels
+8. **Size consistency**: Use consistent sizes across forms
+
+## Performance Considerations
+
+- The component uses React.forwardRef for proper ref forwarding
+- Styled components are memoized to prevent unnecessary re-renders
+- Event handlers are optimized to prevent excessive updates
+- Loading state properly disables interactions
+
+## Browser Support
+- All modern browsers (Chrome, Firefox, Safari, Edge)
+- Mobile browsers (iOS Safari, Chrome Mobile)
+- Responsive design for all screen sizes
+- Touch-friendly interaction areas
+
+## Testing
+
+### Test IDs
+
+The Input component includes `data-testid` attributes for reliable testing:
+
+| Test ID | Element | Description |
+|---------|---------|-------------|
+| `{dataTestId}` | Input field | The actual input element (passed via inputProps) |
+
+**Note:** The `data-testid` is applied to the `<input>` element itself, not the TextField wrapper. When querying, use `findByTestId` to target the input element directly.
+
+### Testing Best Practices
+
+**Wait for Input to Render:**
+```typescript
+const input = await canvas.findByTestId('email-input');
+expect(input).toBeInTheDocument();
+```
+
+**Test User Input:**
+```typescript
+const input = await canvas.findByTestId('name-input');
+await userEvent.type(input, 'John Doe');
+expect(input).toHaveValue('John Doe');
+```
+
+**Test Disabled State:**
+```typescript
+const input = await canvas.findByTestId('disabled-input');
+expect(input).toBeDisabled();
+```
+
+**Test Loading State:**
+```typescript
+// Input is disabled when loading
+const loadingInput = await canvas.findByTestId('loading-input');
+expect(loadingInput).toBeDisabled();
+
+// Loading spinner appears
+const spinner = canvasElement.querySelector('.MuiCircularProgress-root');
+expect(spinner).toBeInTheDocument();
+```
+
+**Test Error State:**
+```typescript
+const input = await canvas.findByTestId('error-input');
+const container = input.closest('.MuiFormControl-root');
+
+// Check error styling
+expect(container?.querySelector('.Mui-error')).toBeInTheDocument();
+
+// Verify helper text
+const helperText = container?.querySelector('.MuiFormHelperText-root');
+expect(helperText).toHaveTextContent('Error message');
+```
+
+**Test with Adornments:**
+```typescript
+// Input with start/end adornments
+const input = await canvas.findByTestId('search-input');
+const container = input.closest('.MuiFormControl-root');
+
+const startAdornment = container?.querySelector('.MuiInputAdornment-positionStart');
+const endAdornment = container?.querySelector('.MuiInputAdornment-positionEnd');
+
+expect(startAdornment).toBeInTheDocument();
+expect(endAdornment).toBeInTheDocument();
+```
+
+**Test Form Integration:**
+```typescript
+const input = await canvas.findByTestId('form-input');
+await userEvent.type(input, 'test@example.com');
+await userEvent.keyboard('{Enter}');
+expect(onSubmit).toHaveBeenCalled();
+```
+
+### Common Test Scenarios
+
+1. **Basic Rendering** - Verify input renders with label and placeholder
+2. **User Input** - Test typing and value changes
+3. **Variants** - Test outlined, filled, glass, underline, gradient styles
+4. **Sizes** - Test sm, md, lg sizing
+5. **States** - Test disabled, error, loading, readonly states
+6. **Adornments** - Test start/end icons and buttons
+7. **Validation** - Test error states and helper text
+8. **Floating Labels** - Test label animation on focus/blur
+9. **Visual Effects** - Test glow and pulse animations
+10. **Keyboard Navigation** - Test Tab navigation and Enter key
+11. **Accessibility** - Verify ARIA attributes and screen reader support
+12. **Form Integration** - Test with form libraries like React Hook Form

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

@@ -0,0 +1,256 @@
+import { Email, Lock, Search, Visibility, VisibilityOff } from '@mui/icons-material';
+import { IconButton } from '@mui/material';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { useState } from 'react';
+
+import { Input } from './Input';
+
+const meta: Meta<typeof Input> = {
+  title: 'Form/Input',
+  component: Input,
+  parameters: {
+    layout: 'centered',
+  },
+  tags: ['autodocs', 'component:Input'],
+  argTypes: {
+    variant: {
+      control: { type: 'select' },
+      options: ['outlined', 'filled', 'glass', 'underline', 'gradient'],
+    },
+    size: {
+      control: { type: 'select' },
+      options: ['sm', 'md', 'lg'],
+    },
+    type: {
+      control: { type: 'select' },
+      options: ['text', 'email', 'password', 'number', 'tel', 'url'],
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    placeholder: 'Enter text...',
+  },
+};
+
+export const WithLabel: Story = {
+  args: {
+    label: 'Full Name',
+    placeholder: 'John Doe',
+  },
+};
+
+// Required story export: AllVariants
+export const AllVariants: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px', width: '300px' }}>
+      <Input variant="outlined" label="Outlined" placeholder="Outlined input" />
+      <Input variant="filled" label="Filled" placeholder="Filled input" />
+      <Input variant="glass" label="Glass" placeholder="Glass morphism input" />
+      <Input variant="underline" label="Underline" placeholder="Underline input" />
+      <Input variant="gradient" label="Gradient" placeholder="Gradient border input" />
+    </div>
+  ),
+};
+
+// Backward compatibility alias
+export const Variants = AllVariants;
+
+// Required story export: AllSizes
+export const AllSizes: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px', width: '300px' }}>
+      <Input size="sm" label="Small" placeholder="Small input" />
+      <Input size="md" label="Medium" placeholder="Medium input" />
+      <Input size="lg" label="Large" placeholder="Large input" />
+    </div>
+  ),
+};
+
+// Backward compatibility alias
+export const Sizes = AllSizes;
+
+export const WithAdornments: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px', width: '300px' }}>
+      <Input label="Search" placeholder="Search..." startAdornment={<Search />} />
+      <Input label="Email" type="email" placeholder="john@example.com" startAdornment={<Email />} />
+      <PasswordInput />
+    </div>
+  ),
+};
+
+// Password input with visibility toggle
+function PasswordInput() {
+  const [showPassword, setShowPassword] = useState(false);
+
+  return (
+    <Input
+      label="Password"
+      type={showPassword ? 'text' : 'password'}
+      placeholder="Enter password"
+      startAdornment={<Lock />}
+      endAdornment={
+        <IconButton onClick={() => setShowPassword(!showPassword)} edge="end">
+          {showPassword ? <VisibilityOff /> : <Visibility />}
+        </IconButton>
+      }
+    />
+  );
+}
+
+export const FloatingLabels: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px', width: '300px' }}>
+      <Input floating label="Floating Label" placeholder="Type here..." />
+      <Input floating variant="glass" label="Glass with Float" />
+      <Input floating variant="filled" label="Filled with Float" />
+    </div>
+  ),
+};
+
+export const ErrorStates: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px', width: '300px' }}>
+      <Input
+        label="Email"
+        error
+        helperText="Please enter a valid email address"
+        defaultValue="invalid-email"
+      />
+      <Input variant="glass" label="Required Field" error helperText="This field is required" />
+    </div>
+  ),
+};
+
+// Enhanced Visual Effects Stories
+export const VisualEffects: Story = {
+  render: () => (
+    <div
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        gap: '24px',
+        width: '300px',
+        backgroundColor: '#f5f5f5',
+        padding: '24px',
+        borderRadius: '8px',
+      }}
+    >
+      <Input variant="glass" label="Glow Effect" placeholder="Focus me!" glow />
+      <Input variant="outlined" label="Pulse Animation" placeholder="Watch me pulse" pulse />
+      <Input variant="gradient" label="Loading State" placeholder="Processing..." loading />
+      <Input variant="glass" label="Combined Effects" placeholder="Glow + Float" glow floating />
+    </div>
+  ),
+};
+
+// Required story export: AllStates
+export const AllStates: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px', width: '300px' }}>
+      <Input label="Default State" placeholder="Type here..." />
+      <Input label="Focused State" placeholder="Focus me" autoFocus />
+      <Input label="Hover State" placeholder="Hover over me" />
+      <Input label="Disabled State" placeholder="Cannot type" disabled />
+      <Input label="Readonly State" placeholder="Read only" value="Cannot change this" readOnly />
+      <Input
+        label="Error State"
+        placeholder="Has error"
+        error
+        helperText="This field has an error"
+      />
+      <Input label="Required Field" placeholder="This is required" required />
+      <Input label="Loading State" placeholder="Loading..." loading />
+    </div>
+  ),
+};
+
+// Backward compatibility alias
+export const InteractiveStates = AllStates;
+
+// Different Input Types
+export const InputTypes: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px', width: '300px' }}>
+      <Input type="text" label="Text Input" placeholder="Enter text" />
+      <Input type="email" label="Email Input" placeholder="email@example.com" />
+      <Input type="password" label="Password Input" placeholder="Enter password" />
+      <Input type="number" label="Number Input" placeholder="123" />
+      <Input type="tel" label="Phone Input" placeholder="+1 (555) 123-4567" />
+      <Input type="url" label="URL Input" placeholder="https://example.com" />
+    </div>
+  ),
+};
+
+// Edge Cases
+export const EdgeCases: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px', width: '300px' }}>
+      <Input
+        label="Long Text Overflow"
+        defaultValue="This is a very long text that should show how the input handles overflow and long content gracefully"
+      />
+      <Input label="Empty with Floating" floating placeholder="Floating label behavior" />
+      <Input label="No Full Width" fullWidth={false} placeholder="Not full width" />
+      <Input
+        variant="glass"
+        label="Glass + All Props"
+        placeholder="Kitchen sink example"
+        glow
+        pulse
+        floating
+        helperText="This has all visual effects enabled"
+      />
+    </div>
+  ),
+};
+
+// Required story export: Responsive
+export const Responsive: Story = {
+  render: () => (
+    <div
+      style={{
+        display: 'grid',
+        gridTemplateColumns: 'repeat(auto-fit, minmax(250px, 1fr))',
+        gap: '16px',
+      }}
+    >
+      <Input variant="outlined" label="Responsive 1" placeholder="Resize window" />
+      <Input variant="glass" label="Responsive 2" placeholder="Watch layout" />
+      <Input variant="gradient" label="Responsive 3" placeholder="Adapt to screen" />
+    </div>
+  ),
+  parameters: {
+    viewport: {
+      viewports: {
+        mobile: { name: 'Mobile', styles: { width: '375px', height: '667px' } },
+        tablet: { name: 'Tablet', styles: { width: '768px', height: '1024px' } },
+        desktop: { name: 'Desktop', styles: { width: '1200px', height: '800px' } },
+      },
+    },
+  },
+};
+
+// Backward compatibility alias
+export const ResponsiveDemo = Responsive;
+
+export const Playground: Story = {
+  args: {
+    variant: 'outlined',
+    size: 'md',
+    label: 'Playground Input',
+    placeholder: 'Type something...',
+    fullWidth: true,
+    floating: false,
+    glow: false,
+    pulse: false,
+    loading: false,
+    error: false,
+    helperText: 'This is helper text',
+  },
+};