@12-apps/ui 1.0.0

package/src/components/form/Checkbox/Checkbox.md

@@ -0,0 +1,200 @@
+# Checkbox Component
+
+A flexible and customizable checkbox component with comprehensive styling options and accessibility features.
+
+## Features
+
+- **Multiple Variants**: Default, rounded, and toggle styles
+- **Visual Effects**: Glow and pulse animations
+- **Loading States**: Built-in loading spinner support
+- **Error States**: Error styling with helper text
+- **Customizable**: Ripple effect control and custom styling
+- **Accessible**: Full keyboard navigation and screen reader support
+
+## Usage
+
+```tsx
+import { Checkbox } from '@/components/form/Checkbox';
+
+// Basic checkbox
+<Checkbox label="Accept terms" />
+
+// With error state
+<Checkbox
+  label="Required field"
+  error
+  helperText="This field is required"
+/>
+
+// With loading state
+<Checkbox
+  label="Processing"
+  loading
+/>
+
+// Rounded variant with glow effect
+<Checkbox
+  label="Special option"
+  variant="rounded"
+  glow
+/>
+```
+
+## Props
+
+### CheckboxProps
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| variant | `'default' \| 'rounded' \| 'toggle'` | `'default'` | Visual variant style |
+| label | `string` | - | Label text displayed next to checkbox |
+| error | `boolean` | `false` | Error state flag |
+| helperText | `string` | - | Helper or error text displayed below |
+| loading | `boolean` | `false` | Shows loading spinner and disables checkbox |
+| ripple | `boolean` | `true` | Enable/disable ripple effect on click |
+| glow | `boolean` | `false` | Enable glow animation |
+| pulse | `boolean` | `false` | Enable pulse animation |
+| disabled | `boolean` | `false` | Disable the checkbox |
+| data-testid | `string` | - | Custom test ID for testing |
+
+Plus all standard MUI Checkbox props (checked, onChange, indeterminate, etc.)
+
+## Variants
+
+### Default
+Standard Material-UI checkbox styling with theme colors.
+
+### Rounded
+Checkbox with circular icon styling.
+
+### Toggle
+Checkbox with rounded rectangular appearance and scaled size.
+
+## Accessibility
+
+- Full keyboard navigation support (Space to toggle)
+- Screen reader compatible with proper ARIA attributes
+- Focus management with visual focus indicators
+- Support for disabled and indeterminate states
+- Helper text properly associated with checkbox
+
+## Examples
+
+### Basic Checkbox
+
+```tsx
+<Checkbox label="I agree to the terms" />
+```
+
+### With Helper Text
+
+```tsx
+<Checkbox
+  label="Subscribe to newsletter"
+  helperText="We'll send you updates monthly"
+/>
+```
+
+### Error State
+
+```tsx
+<Checkbox
+  label="Required consent"
+  error
+  helperText="You must accept to continue"
+/>
+```
+
+### Loading State
+
+```tsx
+<Checkbox
+  label="Saving preferences..."
+  loading
+  checked
+/>
+```
+
+### Rounded with Glow Effect
+
+```tsx
+<Checkbox
+  variant="rounded"
+  label="Premium feature"
+  glow
+/>
+```
+
+## Testing
+
+### Test IDs
+
+The Checkbox component includes `data-testid` attributes for reliable testing:
+
+| Test ID | Element | Description |
+|---------|---------|-------------|
+| `checkbox` | Main checkbox | Root checkbox input element (default) |
+| `{dataTestId}` | Main checkbox | Root checkbox input with custom testId |
+| `checkbox-container` | Container div | Wrapper containing checkbox, label, and helper text (default) |
+| `{dataTestId}-container` | Container div | Wrapper with custom testId |
+| `checkbox-helper` | Helper text | FormHelperText element (default) |
+| `{dataTestId}-helper` | Helper text | Helper text with custom testId |
+
+### Testing Best Practices
+
+**Wait for Checkbox to Render:**
+```typescript
+const checkbox = await canvas.findByTestId('checkbox');
+expect(checkbox).toBeInTheDocument();
+```
+
+**Test with Custom TestId:**
+```typescript
+<Checkbox data-testid="terms-checkbox" label="Accept Terms" />
+
+const checkbox = await canvas.findByTestId('terms-checkbox');
+const container = await canvas.findByTestId('terms-checkbox-container');
+expect(checkbox).toBeInTheDocument();
+expect(container).toBeInTheDocument();
+```
+
+**Test Interactions:**
+```typescript
+const checkbox = await canvas.findByTestId('checkbox');
+await userEvent.click(checkbox);
+expect(onChange).toHaveBeenCalled();
+```
+
+**Test States:**
+```typescript
+// Loading state
+const loadingCheckbox = await canvas.findByTestId('checkbox');
+expect(loadingCheckbox).toBeDisabled();
+
+// Error state with helper text
+const helperText = await canvas.findByTestId('checkbox-helper');
+expect(helperText).toHaveTextContent('Error message');
+expect(helperText).toHaveClass('Mui-error');
+```
+
+**Test Accessibility:**
+```typescript
+const checkbox = await canvas.findByRole('checkbox');
+expect(checkbox).toHaveAttribute('aria-label');
+
+// Indeterminate state
+expect(checkbox).toHaveAttribute('aria-checked', 'mixed');
+```
+
+### Common Test Scenarios
+
+1. **Basic Rendering** - Verify checkbox renders with label
+2. **Checked/Unchecked States** - Test toggling between states
+3. **Indeterminate State** - Test partial selection state
+4. **Loading State** - Verify spinner shows and checkbox is disabled
+5. **Error State** - Test error styling and helper text display
+6. **Disabled State** - Verify checkbox is not interactive when disabled
+7. **Variants** - Test default, rounded, and toggle visual variants
+8. **Visual Effects** - Test glow and pulse animations
+9. **Keyboard Navigation** - Test Space key to toggle
+10. **Accessibility** - Verify ARIA attributes and screen reader support

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

@@ -0,0 +1,265 @@
+import { FormGroup,Stack } from '@mui/material';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { Checkbox } from './Checkbox';
+
+const meta: Meta<typeof Checkbox> = {
+  title: 'Form/Checkbox',
+  component: Checkbox,
+  parameters: {
+    layout: 'centered',
+  },
+  tags: ['autodocs', 'component:Checkbox'],
+  argTypes: {
+    variant: {
+      control: { type: 'select' },
+      options: ['default', 'rounded', 'toggle'],
+    },
+    color: {
+      control: { type: 'select' },
+      options: ['primary', 'secondary', 'success', 'warning', 'error'],
+    },
+    size: {
+      control: { type: 'select' },
+      options: ['small', 'medium', 'large'],
+    },
+    loading: {
+      control: { type: 'boolean' },
+    },
+    ripple: {
+      control: { type: 'boolean' },
+    },
+    glow: {
+      control: { type: 'boolean' },
+    },
+    pulse: {
+      control: { type: 'boolean' },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    label: 'Default checkbox',
+  },
+};
+
+export const Variants: Story = {
+  render: () => (
+    <Stack spacing={2}>
+      <Checkbox variant="default" label="Default checkbox" defaultChecked />
+      <Checkbox variant="rounded" label="Rounded checkbox" defaultChecked />
+      <Checkbox variant="toggle" label="Toggle-style checkbox" defaultChecked />
+    </Stack>
+  ),
+};
+
+export const States: Story = {
+  render: () => (
+    <Stack spacing={2}>
+      <Checkbox label="Unchecked" />
+      <Checkbox label="Checked" defaultChecked />
+      <Checkbox label="Indeterminate" indeterminate />
+      <Checkbox label="Disabled" disabled />
+      <Checkbox label="Disabled & Checked" disabled checked />
+    </Stack>
+  ),
+};
+
+export const Colors: Story = {
+  render: () => (
+    <Stack spacing={2}>
+      <Checkbox label="Primary" color="primary" defaultChecked />
+      <Checkbox label="Secondary" color="secondary" defaultChecked />
+      <Checkbox label="Success" color="success" defaultChecked />
+      <Checkbox label="Warning" color="warning" defaultChecked />
+      <Checkbox label="Error" color="error" defaultChecked />
+    </Stack>
+  ),
+};
+
+export const Sizes: Story = {
+  render: () => (
+    <Stack spacing={2}>
+      <Checkbox label="Small" size="small" defaultChecked />
+      <Checkbox label="Medium" size="medium" defaultChecked />
+      <Checkbox label="Large" size="large" defaultChecked />
+    </Stack>
+  ),
+};
+
+export const WithHelperText: Story = {
+  render: () => (
+    <Stack spacing={2}>
+      <Checkbox
+        label="Terms and Conditions"
+        helperText="Please read and accept our terms and conditions"
+      />
+      <Checkbox label="Newsletter" helperText="Subscribe to our weekly newsletter" defaultChecked />
+      <Checkbox label="Required Field" helperText="This field is required" error />
+    </Stack>
+  ),
+};
+
+export const CheckboxGroup: Story = {
+  render: () => (
+    <FormGroup>
+      <Checkbox label="Option 1" defaultChecked />
+      <Checkbox label="Option 2" />
+      <Checkbox label="Option 3" defaultChecked />
+      <Checkbox label="Option 4 (Disabled)" disabled />
+    </FormGroup>
+  ),
+};
+
+export const ErrorState: Story = {
+  args: {
+    label: 'I accept the terms',
+    error: true,
+    helperText: 'You must accept the terms to continue',
+  },
+};
+
+export const LoadingState: Story = {
+  render: () => (
+    <Stack spacing={2}>
+      <Checkbox label="Loading checkbox" loading />
+      <Checkbox label="Loading with text" loading defaultChecked />
+      <Checkbox loading /> {/* Without label */}
+    </Stack>
+  ),
+};
+
+export const AnimationEffects: Story = {
+  render: () => (
+    <Stack spacing={2}>
+      <Checkbox label="Glow effect" glow defaultChecked />
+      <Checkbox label="Pulse effect" pulse defaultChecked />
+      <Checkbox label="No ripple effect" ripple={false} />
+      <Checkbox label="All effects" glow pulse defaultChecked />
+    </Stack>
+  ),
+};
+
+export const Accessibility: Story = {
+  render: () => (
+    <Stack spacing={2}>
+      <Checkbox
+        label="Accessible checkbox"
+        data-testid="accessible-checkbox"
+        aria-describedby="checkbox-description"
+      />
+      <div id="checkbox-description">This checkbox has proper accessibility attributes</div>
+      <Checkbox
+        label="Required field"
+        required
+        error
+        helperText="This field is required"
+        data-testid="required-checkbox"
+      />
+    </Stack>
+  ),
+};
+
+export const Playground: Story = {
+  args: {
+    variant: 'default',
+    label: 'Playground Checkbox',
+    color: 'primary',
+    size: 'medium',
+    checked: false,
+    disabled: false,
+    indeterminate: false,
+    error: false,
+    helperText: '',
+    loading: false,
+    ripple: true,
+    glow: false,
+    pulse: false,
+  },
+};
+
+// Required story exports for validation
+export const AllVariants: Story = {
+  render: () => (
+    <Stack spacing={3}>
+      <Stack direction="row" spacing={2} alignItems="center">
+        <Checkbox variant="default" label="Default variant" defaultChecked />
+        <Checkbox variant="rounded" label="Rounded variant" defaultChecked />
+        <Checkbox variant="toggle" label="Toggle variant" defaultChecked />
+      </Stack>
+    </Stack>
+  ),
+};
+
+export const AllSizes: Story = {
+  render: () => (
+    <Stack direction="row" spacing={2} alignItems="center">
+      <Checkbox size="small" label="Small" defaultChecked />
+      <Checkbox size="medium" label="Medium" defaultChecked />
+      <Checkbox size="large" label="Large" defaultChecked />
+    </Stack>
+  ),
+};
+
+export const AllStates: Story = {
+  render: () => (
+    <Stack spacing={2}>
+      <Stack direction="row" spacing={2}>
+        <Checkbox label="Default" />
+        <Checkbox label="Checked" defaultChecked />
+        <Checkbox label="Indeterminate" indeterminate />
+      </Stack>
+      <Stack direction="row" spacing={2}>
+        <Checkbox label="Disabled" disabled />
+        <Checkbox label="Disabled Checked" disabled defaultChecked />
+        <Checkbox label="Loading" loading />
+      </Stack>
+      <Stack direction="row" spacing={2}>
+        <Checkbox label="Error" error helperText="Error message" />
+        <Checkbox label="With Helper" helperText="Helper text" />
+      </Stack>
+    </Stack>
+  ),
+};
+
+export const InteractiveStates: Story = {
+  render: () => (
+    <Stack spacing={3}>
+      <Stack direction="row" spacing={2}>
+        <Checkbox label="Hover me" glow />
+        <Checkbox label="Focus me" pulse />
+        <Checkbox label="Click me" defaultChecked />
+      </Stack>
+      <Stack direction="row" spacing={2}>
+        <Checkbox label="With ripple" ripple defaultChecked />
+        <Checkbox label="No ripple" ripple={false} defaultChecked />
+      </Stack>
+    </Stack>
+  ),
+};
+
+export const Responsive: Story = {
+  parameters: {
+    viewport: {
+      viewports: {
+        mobile: { name: 'Mobile', styles: { width: '360px', height: '640px' } },
+        tablet: { name: 'Tablet', styles: { width: '768px', height: '1024px' } },
+        desktop: { name: 'Desktop', styles: { width: '1440px', height: '900px' } },
+      },
+    },
+  },
+  render: () => (
+    <Stack spacing={2} sx={{ width: '100%', p: 2 }}>
+      <FormGroup>
+        <Checkbox label="Responsive checkbox 1" defaultChecked />
+        <Checkbox label="Responsive checkbox 2" />
+        <Checkbox label="Responsive checkbox 3" defaultChecked />
+        <Checkbox label="Responsive checkbox 4" disabled />
+      </FormGroup>
+    </Stack>
+  ),
+};

package/src/components/form/Checkbox/Checkbox.test.stories.tsx

@@ -0,0 +1,181 @@
+import { Stack } from '@mui/material';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import React from 'react';
+import { expect, fn,userEvent, within } from 'storybook/test';
+
+import { Checkbox } from './Checkbox';
+
+const meta: Meta<typeof Checkbox> = {
+  title: 'Form/Checkbox/Tests',
+  component: Checkbox,
+  parameters: {
+    layout: 'centered',
+    chromatic: { disableSnapshot: false },
+  },
+  tags: ['autodocs', 'test', 'component:Checkbox'],
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// Basic Interaction Tests
+export const BasicInteraction: Story = {
+  name: '🧪 Basic Interaction Test',
+  args: {
+    label: 'Test Checkbox',
+    onChange: fn(),
+    onClick: fn(),
+    onFocus: fn(),
+    onBlur: fn(),
+  },
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step('Initial render verification', async () => {
+      const checkbox = canvas.getByRole('checkbox', { name: /test checkbox/i });
+      await expect(checkbox).toBeInTheDocument();
+      await expect(checkbox).not.toBeChecked();
+    });
+
+    await step('Click to check', async () => {
+      const checkbox = canvas.getByRole('checkbox', { name: /test checkbox/i });
+      await userEvent.click(checkbox);
+      await expect(checkbox).toBeChecked();
+    });
+  },
+};
+
+export const KeyboardNavigation: Story = {
+  name: '⌨️ Keyboard Navigation Test',
+  render: () => (
+    <Stack spacing={2}>
+      <Checkbox label="First checkbox" />
+      <Checkbox label="Second checkbox" />
+    </Stack>
+  ),
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step('Tab navigation', async () => {
+      const firstCheckbox = canvas.getByRole('checkbox', { name: /first checkbox/i });
+      await expect(firstCheckbox).toBeInTheDocument();
+    });
+  },
+};
+
+export const FocusManagement: Story = {
+  name: '🎯 Focus Management Test',
+  render: () => (
+    <Stack spacing={2}>
+      <Checkbox autoFocus label="Auto-focus checkbox" />
+      <Checkbox label="Regular checkbox" />
+    </Stack>
+  ),
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step('Auto focus', async () => {
+      const autoFocusCheckbox = canvas.getByRole('checkbox', { name: /auto-focus checkbox/i });
+      await expect(autoFocusCheckbox).toBeInTheDocument();
+    });
+  },
+};
+
+export const VisualStates: Story = {
+  name: '👁️ Visual States Test',
+  render: () => (
+    <Stack spacing={2}>
+      <Checkbox label="Default state" />
+      <Checkbox label="Checked state" defaultChecked />
+      <Checkbox label="Disabled state" disabled />
+    </Stack>
+  ),
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step('Default state', async () => {
+      const checkbox = canvas.getByRole('checkbox', { name: /default state/i });
+      await expect(checkbox).not.toBeChecked();
+    });
+  },
+};
+
+export const ResponsiveDesign: Story = {
+  name: '📱 Responsive Design Test',
+  render: () => (
+    <Stack spacing={2}>
+      <Checkbox label="Mobile checkbox" size="small" />
+      <Checkbox label="Tablet checkbox" size="medium" />
+      <Checkbox label="Desktop checkbox" size="large" />
+    </Stack>
+  ),
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step('Responsive layout', async () => {
+      const checkboxes = canvas.getAllByRole('checkbox');
+      await expect(checkboxes).toHaveLength(3);
+    });
+  },
+};
+
+export const ThemeVariations: Story = {
+  name: '🎨 Theme Variations Test',
+  render: () => (
+    <Stack spacing={2}>
+      <Checkbox label="Primary checkbox" color="primary" defaultChecked />
+      <Checkbox label="Secondary checkbox" color="secondary" defaultChecked />
+    </Stack>
+  ),
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step('Theme colors', async () => {
+      const checkboxes = canvas.getAllByRole('checkbox');
+      await expect(checkboxes).toHaveLength(2);
+    });
+  },
+};
+
+export const EdgeCases: Story = {
+  name: '🔧 Edge Cases Test',
+  render: () => (
+    <Stack spacing={2}>
+      <Checkbox label="Long text that wraps around multiple lines to test layout" />
+      <Checkbox label="Unicode: 🚀 ✨ 💫" />
+    </Stack>
+  ),
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step('Edge cases', async () => {
+      const checkboxes = canvas.getAllByRole('checkbox');
+      await expect(checkboxes).toHaveLength(2);
+    });
+  },
+};
+
+export const Integration: Story = {
+  name: '🔗 Integration Test',
+  render: () => {
+    const [checked, setChecked] = React.useState(false);
+    return (
+      <Checkbox
+        label="Integration test"
+        checked={checked}
+        onChange={(e, value) => setChecked(value)}
+      />
+    );
+  },
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step('Integration test', async () => {
+      const checkbox = canvas.getByRole('checkbox', { name: /integration test/i });
+      await expect(checkbox).not.toBeChecked();
+
+      await userEvent.click(checkbox);
+      await expect(checkbox).toBeChecked();
+    });
+  },
+};