@pushwoosh/dumb-components 1.1.148 → 1.1.150

package/Switch/ai-documentation.md

@@ -1,312 +0,0 @@
-# Switch Component - @pushwoosh/dumb-components
-
-## Overview
-
-- **Component Name**: Switch
-- **Import Path**: `@pushwoosh/dumb-components`
-- **Files**:
-  - `/src/Switch/Switch.tsx` - Main component implementation
-  - `/src/Switch/types.ts` - TypeScript type definitions
-  - `/src/Switch/styles.ts` - Styled components
-  - `/src/Switch/index.ts` - Component exports
-- **Type**: Form Control
-- **Description**: A toggle switch component that represents a boolean state. Features customizable label positioning, disabled state, and smooth visual transitions.
-
-## TypeScript Interfaces
-
-```typescript
-export interface SwitchProps {
-  labelPosition?: 'left' | 'right';
-  enabled?: boolean;
-  isDisabled?: boolean;
-  children?: ReactNode;
-  onChange: () => void;
-}
-
-export interface AlignProps {
-  labelPosition?: string;
-}
-
-export interface ComponentProps {
-  enabled: boolean;
-  isDisabled?: boolean;
-}
-```
-
-## Import & Usage
-
-```typescript
-import { Switch } from '@pushwoosh/dumb-components';
-
-// Basic usage
-function MyComponent() {
-  const [isEnabled, setIsEnabled] = useState(false);
-
-  return (
-    <Switch
-      enabled={isEnabled}
-      onChange={() => setIsEnabled(!isEnabled)}
-    >
-      Enable notifications
-    </Switch>
-  );
-}
-
-// Left-aligned label
-function LeftLabelSwitch() {
-  const [darkMode, setDarkMode] = useState(false);
-
-  return (
-    <Switch
-      enabled={darkMode}
-      labelPosition="left"
-      onChange={() => setDarkMode(!darkMode)}
-    >
-      Dark Mode
-    </Switch>
-  );
-}
-```
-
-## Advanced Examples
-
-```typescript
-// Switch without label
-function MinimalSwitch() {
-  const [enabled, setEnabled] = useState(false);
-
-  return (
-    <Switch
-      enabled={enabled}
-      onChange={() => setEnabled(!enabled)}
-    />
-  );
-}
-
-// Disabled switch
-function DisabledSwitch() {
-  return (
-    <Switch
-      enabled={true}
-      isDisabled={true}
-      onChange={() => {}}
-    >
-      Read-only Setting
-    </Switch>
-  );
-}
-
-// Form integration
-function SettingsForm() {
-  const [settings, setSettings] = useState({
-    notifications: false,
-    darkMode: false,
-    autoSave: true,
-  });
-
-  const updateSetting = (key: string) => {
-    setSettings(prev => ({
-      ...prev,
-      [key]: !prev[key as keyof typeof prev]
-    }));
-  };
-
-  return (
-    <div>
-      <h3>User Settings</h3>
-      
-      <Switch
-        enabled={settings.notifications}
-        labelPosition="left"
-        onChange={() => updateSetting('notifications')}
-      >
-        Email Notifications
-      </Switch>
-      
-      <Switch
-        enabled={settings.darkMode}
-        labelPosition="left"
-        onChange={() => updateSetting('darkMode')}
-      >
-        Dark Theme
-      </Switch>
-      
-      <Switch
-        enabled={settings.autoSave}
-        labelPosition="left"
-        onChange={() => updateSetting('autoSave')}
-      >
-        Auto-save Documents
-      </Switch>
-    </div>
-  );
-}
-
-// Permission toggle
-function PermissionToggle() {
-  const [permissions, setPermissions] = useState({
-    canEdit: false,
-    canDelete: false,
-    canShare: true,
-  });
-
-  return (
-    <div>
-      <h4>User Permissions</h4>
-      
-      <Switch
-        enabled={permissions.canEdit}
-        onChange={() => setPermissions(prev => ({ 
-          ...prev, 
-          canEdit: !prev.canEdit 
-        }))}
-      >
-        Can Edit Content
-      </Switch>
-      
-      <Switch
-        enabled={permissions.canDelete}
-        isDisabled={!permissions.canEdit} // Dependent permission
-        onChange={() => setPermissions(prev => ({ 
-          ...prev, 
-          canDelete: !prev.canDelete 
-        }))}
-      >
-        Can Delete Content
-      </Switch>
-      
-      <Switch
-        enabled={permissions.canShare}
-        onChange={() => setPermissions(prev => ({ 
-          ...prev, 
-          canShare: !prev.canShare 
-        }))}
-      >
-        Can Share Content
-      </Switch>
-    </div>
-  );
-}
-
-// Async state management
-function AsyncSwitch() {
-  const [enabled, setEnabled] = useState(false);
-  const [loading, setLoading] = useState(false);
-
-  const handleToggle = async () => {
-    setLoading(true);
-    try {
-      // Simulate API call
-      await new Promise(resolve => setTimeout(resolve, 1000));
-      setEnabled(!enabled);
-    } finally {
-      setLoading(false);
-    }
-  };
-
-  return (
-    <Switch
-      enabled={enabled}
-      isDisabled={loading}
-      onChange={handleToggle}
-    >
-      {loading ? 'Updating...' : 'Feature Toggle'}
-    </Switch>
-  );
-}
-```
-
-## Props Reference
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| `labelPosition` | `'left' \| 'right'` | `'right'` | No | Position of the label relative to the switch |
-| `enabled` | `boolean` | `false` | No | Whether the switch is in the enabled/on state |
-| `isDisabled` | `boolean` | `false` | No | Whether the switch is disabled and non-interactive |
-| `children` | `ReactNode` | `undefined` | No | Label content displayed next to the switch |
-| `onChange` | `() => void` | - | Yes | Callback fired when the switch is toggled |
-
-## AI Agent Guidelines
-
-### Recommended Patterns
-
-1. **State Management**: Use boolean state for switch values
-```typescript
-const [isEnabled, setIsEnabled] = useState(false);
-
-<Switch
-  enabled={isEnabled}
-  onChange={() => setIsEnabled(!isEnabled)}
->
-  Setting Name
-</Switch>
-```
-
-2. **Label Positioning**: Use consistent positioning within a form
-```typescript
-// Consistent left positioning for form layouts
-<Switch labelPosition="left" enabled={setting1} onChange={toggle1}>Setting 1</Switch>
-<Switch labelPosition="left" enabled={setting2} onChange={toggle2}>Setting 2</Switch>
-```
-
-3. **Form Integration**: Integrate with form state management
-```typescript
-const [formData, setFormData] = useState({ notifications: false });
-
-const toggleNotifications = () => {
-  setFormData(prev => ({ 
-    ...prev, 
-    notifications: !prev.notifications 
-  }));
-};
-```
-
-### Common Mistakes to Avoid
-
-1. **Missing onChange**: Always provide an `onChange` handler, even for disabled switches
-2. **Inconsistent State**: Don't mix controlled and uncontrolled patterns
-3. **Wrong Data Type**: The `enabled` prop expects a boolean, not a string
-4. **Accessibility**: Don't forget to provide meaningful labels via `children`
-
-### Integration Tips
-
-1. **Accessibility**: The component automatically handles ARIA attributes and keyboard navigation
-2. **Visual States**: The switch provides clear visual feedback for enabled/disabled states
-3. **Performance**: Use React.memo() for switches in large lists to prevent unnecessary re-renders
-4. **Form Libraries**: Works well with React Hook Form and Formik
-```typescript
-// React Hook Form integration
-const { watch, setValue } = useForm();
-const enabled = watch('featureEnabled');
-
-<Switch
-  enabled={enabled}
-  onChange={() => setValue('featureEnabled', !enabled)}
->
-  Feature Toggle
-</Switch>
-```
-
-5. **Async Operations**: Handle loading states by temporarily disabling the switch
-```typescript
-const [loading, setLoading] = useState(false);
-
-<Switch
-  enabled={enabled}
-  isDisabled={loading}
-  onChange={async () => {
-    setLoading(true);
-    await saveSettings();
-    setLoading(false);
-  }}
->
-  {loading ? 'Saving...' : 'Auto Save'}
-</Switch>
-```
-
-## Related Components
-
-- **Radio**: For mutually exclusive options
-- **Checkbox**: For multi-select scenarios
-- **Button**: For action-based toggles
-- **Select**: For multiple option selections