@shohojdhara/atomix 0.3.13 → 0.3.15

package/src/components/Toggle/Toggle.stories.tsx

@@ -1,5 +1,6 @@
 import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
+import { fn } from '@storybook/test';
 import { Toggle } from './Toggle';
 
 const meta = {
@@ -9,26 +10,101 @@ const meta = {
     layout: 'centered',
     docs: {
       description: {
-        component:
-          'The Toggle component provides an on/off switch control for binary choices. It offers a more visually distinct alternative to checkboxes for settings, preferences, or feature toggles. Toggles support disabled states and can include glass morphism effects.',
+        component: `
+# Toggle
+
+## Overview
+
+Toggle provides an on/off switch control for binary choices. It offers a more visually distinct alternative to checkboxes for settings, preferences, or feature toggles. Toggles support disabled states and can include glass morphism effects.
+
+## Features
+
+- On/off state control
+- Uncontrolled and controlled usage
+- Disabled state
+- Glass morphism effect
+- Accessible design
+- Responsive behavior
+
+## Accessibility
+
+- Keyboard support: Toggle with Space or Enter key
+- Screen reader: State changes announced appropriately
+- ARIA support: Proper roles and properties for toggle components
+- Focus management: Visible focus indicators maintained
+
+## Usage Examples
+
+### Basic Usage
+
+\`\`\`tsx
+<Toggle 
+  defaultChecked={false} 
+  onChange={(checked) => console.log(checked)} 
+/>
+\`\`\`
+
+### Controlled Usage
+
+\`\`\`tsx
+<Toggle 
+  checked={isEnabled} 
+  onChange={setEnabled} 
+/>
+\`\`\`
+
+## API Reference
+
+### Props
+
+| Prop | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| defaultChecked | boolean | false | Whether the toggle is initially on (uncontrolled) |
+| checked | boolean | - | Whether the toggle is on (controlled) |
+| onChange | (checked: boolean) => void | - | Callback when the toggle state changes |
+| disabled | boolean | false | Whether the toggle is disabled |
+| glass | boolean | false | Enable glass morphism effect |
+        `,
       },
     },
   },
   tags: ['autodocs'],
   argTypes: {
-    initialOn: {
+    defaultChecked: {
       control: { type: 'boolean' },
-      description: 'Whether the toggle is initially on',
-      defaultValue: false,
+      description: 'Whether the toggle is initially on (uncontrolled)',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: false },
+      },
+    },
+    checked: {
+      control: { type: 'boolean' },
+      description: 'Whether the toggle is on (controlled)',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: '-' },
+      },
+    },
+    onChange: {
+      action: 'changed',
+      description: 'Callback when the toggle state changes',
     },
     disabled: {
       control: { type: 'boolean' },
       description: 'Whether the toggle is disabled',
-      defaultValue: false,
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: false },
+      },
     },
     glass: {
       control: 'boolean',
       description: 'Enable glass morphism effect',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: false },
+      },
     },
   },
 } satisfies Meta<typeof Toggle>;
@@ -36,16 +112,42 @@ const meta = {
 export default meta;
 type Story = StoryObj<typeof meta>;
 
-export const Default: Story = {
+export const BasicUsage: Story = {
   render: args => (
     <div style={{ display: 'flex', justifyContent: 'center', padding: '30px' }}>
       <Toggle {...args} />
     </div>
   ),
   args: {
-    initialOn: false,
+    defaultChecked: false,
     disabled: false,
   },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Basic toggle with default settings.',
+      },
+    },
+  },
+};
+
+export const Controlled: Story = {
+  render: () => {
+    const [isChecked, setIsChecked] = React.useState(false);
+    return (
+      <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: '1rem' }}>
+        <p>Checked: {isChecked ? 'Yes' : 'No'}</p>
+        <Toggle checked={isChecked} onChange={setIsChecked} />
+      </div>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Controlled toggle using checked and onChange.',
+      },
+    },
+  },
 };
 
 export const InitiallyOn: Story = {
@@ -55,61 +157,69 @@ export const InitiallyOn: Story = {
     </div>
   ),
   args: {
-    initialOn: true,
+    defaultChecked: true,
     disabled: false,
   },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Toggle that starts in the "on" position.',
+      },
+    },
+  },
 };
 
-export const Disabled: Story = {
-  render: args => (
-    <div style={{ display: 'flex', justifyContent: 'center', padding: '30px' }}>
-      <Toggle {...args} />
+export const DisabledStates: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: '2rem', padding: '30px' }}>
+      <div style={{ display: 'flex', alignItems: 'center', gap: '1rem' }}>
+        <Toggle disabled={true} checked={false} />
+        <span>Disabled Off</span>
+      </div>
+      <div style={{ display: 'flex', alignItems: 'center', gap: '1rem' }}>
+        <Toggle disabled={true} checked={true} />
+        <span>Disabled On</span>
+      </div>
     </div>
   ),
-  args: {
-    initialOn: false,
-    disabled: true,
+  parameters: {
+    docs: {
+      description: {
+        story: 'Toggle in both disabled states (off and on).',
+      },
+    },
   },
 };
 
-export const DisabledOn: Story = {
+export const WithGlassEffect: Story = {
   render: args => (
-    <div style={{ display: 'flex', justifyContent: 'center', padding: '30px' }}>
+    <div style={{ 
+      display: 'flex', 
+      justifyContent: 'center', 
+      padding: '30px',
+      background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
+      minHeight: '200px'
+    }}>
       <Toggle {...args} />
     </div>
   ),
   args: {
-    initialOn: true,
-    disabled: true,
-  },
-};
-
-export const Glass: Story = {
-  args: {
-    initialOn: false,
+    defaultChecked: false,
     disabled: false,
     glass: true,
   },
-  render: (args: any) => (
-    <div
-      style={{
-        background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
-        padding: '3rem',
-        borderRadius: '12px',
-        minHeight: '200px',
-        display: 'flex',
-        alignItems: 'center',
-        justifyContent: 'center',
-      }}
-    >
-      <Toggle {...args} />
-    </div>
-  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Toggle with glass morphism effect applied.',
+      },
+    },
+  },
 };
 
 export const GlassOn: Story = {
   args: {
-    initialOn: true,
+    defaultChecked: true,
     disabled: false,
     glass: true,
   },
@@ -135,7 +245,7 @@ export const GlassOn: Story = {
 
 export const GlassCustom: Story = {
   args: {
-    initialOn: false,
+    defaultChecked: false,
     disabled: false,
     glass: {
       displacementScale: 80,

package/src/components/Toggle/Toggle.test.tsx

@@ -0,0 +1,91 @@
+import { render, screen, fireEvent } from '@testing-library/react';
+import { describe, it, expect, vi } from 'vitest';
+import { Toggle } from './Toggle';
+import React from 'react';
+
+describe('Toggle Component', () => {
+    it('renders correctly', () => {
+        render(<Toggle />);
+        const toggle = screen.getByRole('switch');
+        expect(toggle).toBeInTheDocument();
+        expect(toggle).toHaveAttribute('aria-checked', 'false');
+    });
+
+    it('handles defaultChecked (uncontrolled)', () => {
+        render(<Toggle defaultChecked={true} />);
+        const toggle = screen.getByRole('switch');
+        expect(toggle).toHaveAttribute('aria-checked', 'true');
+    });
+
+    it('toggles state when clicked (uncontrolled)', () => {
+        const handleChange = vi.fn();
+        render(<Toggle onChange={handleChange} />);
+        const toggle = screen.getByRole('switch');
+
+        fireEvent.click(toggle);
+        expect(toggle).toHaveAttribute('aria-checked', 'true');
+        expect(handleChange).toHaveBeenCalledWith(true);
+
+        fireEvent.click(toggle);
+        expect(toggle).toHaveAttribute('aria-checked', 'false');
+        expect(handleChange).toHaveBeenCalledWith(false);
+    });
+
+    it('handles checked (controlled)', () => {
+        const { rerender } = render(<Toggle checked={true} />);
+        const toggle = screen.getByRole('switch');
+        expect(toggle).toHaveAttribute('aria-checked', 'true');
+
+        rerender(<Toggle checked={false} />);
+        expect(toggle).toHaveAttribute('aria-checked', 'false');
+    });
+
+    it('calls onChange but does not toggle internally when controlled', () => {
+        const handleChange = vi.fn();
+        render(<Toggle checked={false} onChange={handleChange} />);
+        const toggle = screen.getByRole('switch');
+
+        fireEvent.click(toggle);
+        expect(handleChange).toHaveBeenCalledWith(true);
+        // Should still be false because it's controlled and we haven't rerendered with checked={true}
+        expect(toggle).toHaveAttribute('aria-checked', 'false');
+    });
+
+    it('does not toggle when disabled', () => {
+        const handleChange = vi.fn();
+        render(<Toggle disabled onChange={handleChange} />);
+        const toggle = screen.getByRole('switch');
+
+        fireEvent.click(toggle);
+        expect(handleChange).not.toHaveBeenCalled();
+        expect(toggle).toHaveAttribute('aria-checked', 'false');
+        expect(toggle).toHaveAttribute('aria-disabled', 'true');
+        expect(toggle).toHaveAttribute('tabindex', '-1');
+    });
+
+    it('handles keyboard interaction', () => {
+        const handleChange = vi.fn();
+        render(<Toggle onChange={handleChange} />);
+        const toggle = screen.getByRole('switch');
+
+        fireEvent.keyDown(toggle, { key: 'Enter' });
+        expect(toggle).toHaveAttribute('aria-checked', 'true');
+        expect(handleChange).toHaveBeenCalledWith(true);
+
+        fireEvent.keyDown(toggle, { key: ' ' });
+        expect(toggle).toHaveAttribute('aria-checked', 'false');
+        expect(handleChange).toHaveBeenCalledWith(false);
+    });
+
+    it('applies accessibility attributes', () => {
+        render(
+            <Toggle
+                aria-label="Accessible Toggle"
+                aria-describedby="description-id"
+            />
+        );
+        const toggle = screen.getByRole('switch');
+        expect(toggle).toHaveAttribute('aria-label', 'Accessible Toggle');
+        expect(toggle).toHaveAttribute('aria-describedby', 'description-id');
+    });
+});

package/src/components/Toggle/Toggle.tsx

@@ -1,23 +1,24 @@
-import React, { useState } from 'react';
+import React, { useState, useCallback, useEffect } from 'react';
 import { TOGGLE } from '../../lib/constants/components';
 import { AtomixGlass } from '../AtomixGlass/AtomixGlass';
-import { AtomixGlassProps } from '../../lib/types/components';
+import { AtomixGlassProps, BaseComponentProps } from '../../lib/types/components';
 
-export interface ToggleProps {
+export interface ToggleProps extends BaseComponentProps {
   /**
-   * Whether the toggle is initially on
+   * Whether the toggle is checked (controlled)
    */
-  initialOn?: boolean;
+  checked?: boolean;
 
   /**
-   * Callback when the toggle is turned on
+   * Whether the toggle is initially checked (uncontrolled)
+   * @default false
    */
-  onToggleOn?: () => void;
+  defaultChecked?: boolean;
 
   /**
-   * Callback when the toggle is turned off
+   * Callback when the toggle state changes
    */
-  onToggleOff?: () => void;
+  onChange?: (checked: boolean) => void;
 
   /**
    * Whether the toggle is disabled
@@ -25,14 +26,14 @@ export interface ToggleProps {
   disabled?: boolean;
 
   /**
-   * Additional CSS class for the toggle
+   * Accessibility label
    */
-  className?: string;
+  'aria-label'?: string;
 
   /**
-   * Inline style for the component
+   * Accessibility description
    */
-  style?: React.CSSProperties;
+  'aria-describedby'?: string;
 
   /**
    * Glass morphism effect for the toggle
@@ -45,29 +46,36 @@ export interface ToggleProps {
  * Toggle component for switching between two states
  */
 export const Toggle: React.FC<ToggleProps> = ({
-  initialOn = false,
-  onToggleOn,
-  onToggleOff,
+  checked: controlledChecked,
+  defaultChecked = false,
+  onChange,
   disabled = false,
   className = '',
   style,
   glass,
+  'aria-label': ariaLabel,
+  'aria-describedby': ariaDescribedBy,
 }) => {
-  const [isOn, setIsOn] = useState(initialOn);
+  const isControlled = controlledChecked !== undefined;
+  const [internalChecked, setInternalChecked] = useState(defaultChecked);
+  const isChecked = isControlled ? controlledChecked : internalChecked;
+
+  // Sync internal state with defaultChecked if it changes (standard uncontrolled behavior)
+  // Actually, standard behavior is only using defaultChecked on mount, but sometimes syncing is needed.
+  // For now, let's keep it simple.
 
   // Handle toggle click
-  const handleClick = () => {
+  const handleClick = useCallback(() => {
     if (disabled) return;
 
-    const newState = !isOn;
-    setIsOn(newState);
+    const nextChecked = !isChecked;
 
-    if (newState) {
-      if (onToggleOn) onToggleOn();
-    } else {
-      if (onToggleOff) onToggleOff();
+    if (!isControlled) {
+      setInternalChecked(nextChecked);
     }
-  };
+
+    onChange?.(nextChecked);
+  }, [disabled, isChecked, isControlled, onChange]);
 
   // Handle key down events
   const handleKeyDown = (e: React.KeyboardEvent) => {
@@ -79,16 +87,25 @@ export const Toggle: React.FC<ToggleProps> = ({
     }
   };
 
+  const toggleClass = [
+    'c-toggle',
+    isChecked && TOGGLE.CLASSES.IS_ON,
+    disabled && 'is-disabled',
+    className,
+  ].filter(Boolean).join(' ');
+
   const toggleContent = (
     <div
-      className={`c-toggle ${isOn ? TOGGLE.CLASSES.IS_ON : ''} ${disabled ? 'is-disabled' : ''} ${className}`}
+      className={toggleClass}
       style={style}
       onClick={handleClick}
       onKeyDown={handleKeyDown}
       role="switch"
-      aria-checked={isOn}
+      aria-checked={isChecked}
       tabIndex={disabled ? -1 : 0}
       aria-disabled={disabled}
+      aria-label={ariaLabel}
+      aria-describedby={ariaDescribedBy}
     >
       <div className="c-toggle__switch"></div>
     </div>