@delightui/components 0.1.104 → 0.1.106

package/docs/components/atoms/CustomToggle.md

@@ -0,0 +1,270 @@
+# CustomToggle
+
+A highly customizable toggle component that allows you to define custom content for both the on and off states. This component provides a flexible alternative to the standard Toggle component by letting you specify what content appears in each state, making it perfect for scenarios where you need more than just basic on/off visual states.
+
+## Aliases
+
+- CustomToggle
+- CustomSwitch
+- ContentToggle
+
+## Props Breakdown
+
+**Extends:** `ControlledFormComponentProps<boolean>`
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `offContent` | `ReactNode` | `undefined` | No | Content to show when toggle is off |
+| `onContent` | `ReactNode` | `undefined` | No | Content to show when toggle is on |
+| `className` | `string` | `undefined` | No | Additional className for the toggle |
+| `initialValue` | `boolean` | `undefined` | No | The initial value for the field |
+| `checked` | `boolean` | `undefined` | No | The initial value for the field |
+| `value` | `boolean` | `undefined` | No | The current value of the form field |
+| `onValueChange` | `(value: boolean) => void` | `undefined` | No | Callback function that is called when the field value changes |
+| `disabled` | `boolean` | `false` | No | Whether the form field is disabled and cannot be interacted with |
+| `required` | `boolean` | `false` | No | Whether the form field must have a value |
+| `invalid` | `boolean` | `false` | No | Whether the form field's current value is invalid |
+| `id` | `string` | `undefined` | No | Id for the form field |
+
+## Examples
+
+### Basic Custom Toggle
+
+```tsx
+import { CustomToggle } from '@delightui/components';
+
+function BasicCustomToggleExample() {
+  const [isEnabled, setIsEnabled] = useState(false);
+
+  return (
+    <CustomToggle
+      value={isEnabled}
+      onValueChange={setIsEnabled}
+      offContent="Disabled"
+      onContent="Enabled"
+    />
+  );
+}
+```
+
+### Custom Toggle with Icons
+
+```tsx
+import { CustomToggle, Icon } from '@delightui/components';
+
+function IconCustomToggleExample() {
+  const [isVisible, setIsVisible] = useState(false);
+
+  return (
+    <CustomToggle
+      value={isVisible}
+      onValueChange={setIsVisible}
+      offContent={<Icon name="VisibilityOffFilled" />}
+      onContent={<Icon name="VisibilityOnFilled" />}
+    />
+  );
+}
+```
+
+### Custom Toggle with Rich Content
+
+```tsx
+import { CustomToggle, Text } from '@delightui/components';
+
+function RichContentToggleExample() {
+  const [isActive, setIsActive] = useState(false);
+
+  return (
+    <CustomToggle
+      value={isActive}
+      onValueChange={setIsActive}
+      offContent={
+        <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
+          <Text size="small" color="error">OFF</Text>
+          <span>🔴</span>
+        </div>
+      }
+      onContent={
+        <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
+          <Text size="small" color="success">ON</Text>
+          <span>🟢</span>
+        </div>
+      }
+    />
+  );
+}
+```
+
+### Form Integration
+
+```tsx
+import { Form, FormField, CustomToggle, Button } from '@delightui/components';
+
+function FormIntegrationExample() {
+  const handleSubmit = (data: any) => {
+    console.log('Form submitted:', data);
+  };
+
+  return (
+    <Form onSubmit={handleSubmit}>
+      <FormField
+        name="notifications"
+        label="Email Notifications"
+        required
+      >
+        <CustomToggle
+          offContent="Notifications Off"
+          onContent="Notifications On"
+        />
+      </FormField>
+
+      <FormField
+        name="darkMode"
+        label="Dark Mode"
+      >
+        <CustomToggle
+          offContent="☀️ Light"
+          onContent="🌙 Dark"
+        />
+      </FormField>
+
+      <Button type="submit">
+        Save Settings
+      </Button>
+    </Form>
+  );
+}
+```
+
+### Disabled State
+
+```tsx
+import { CustomToggle } from '@delightui/components';
+
+function DisabledCustomToggleExample() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
+      <CustomToggle
+        disabled
+        value={false}
+        offContent="Cannot Enable"
+        onContent="Enabled"
+      />
+      
+      <CustomToggle
+        disabled
+        value={true}
+        offContent="Disabled"
+        onContent="Cannot Disable"
+      />
+    </div>
+  );
+}
+```
+
+### Custom Styling
+
+```tsx
+import { CustomToggle } from '@delightui/components';
+
+function StyledCustomToggleExample() {
+  const [isOn, setIsOn] = useState(false);
+
+  return (
+    <CustomToggle
+      value={isOn}
+      onValueChange={setIsOn}
+      className="custom-toggle-styles"
+      offContent="Start"
+      onContent="Stop"
+    />
+  );
+}
+```
+
+### Multiple Custom Toggles
+
+```tsx
+import { CustomToggle } from '@delightui/components';
+
+function MultipleCustomTogglesExample() {
+  const [settings, setSettings] = useState({
+    sound: false,
+    vibration: false,
+    bluetooth: false
+  });
+
+  const updateSetting = (key: string, value: boolean) => {
+    setSettings(prev => ({ ...prev, [key]: value }));
+  };
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
+      <div style={{ display: 'flex', alignItems: 'center', gap: '12px' }}>
+        <span>Sound:</span>
+        <CustomToggle
+          value={settings.sound}
+          onValueChange={(value) => updateSetting('sound', value)}
+          offContent="🔇 Muted"
+          onContent="🔊 On"
+        />
+      </div>
+
+      <div style={{ display: 'flex', alignItems: 'center', gap: '12px' }}>
+        <span>Vibration:</span>
+        <CustomToggle
+          value={settings.vibration}
+          onValueChange={(value) => updateSetting('vibration', value)}
+          offContent="📱 Off"
+          onContent="📳 On"
+        />
+      </div>
+
+      <div style={{ display: 'flex', alignItems: 'center', gap: '12px' }}>
+        <span>Bluetooth:</span>
+        <CustomToggle
+          value={settings.bluetooth}
+          onValueChange={(value) => updateSetting('bluetooth', value)}
+          offContent="Disconnected"
+          onContent="Connected"
+        />
+      </div>
+    </div>
+  );
+}
+```
+
+### Controlled vs Uncontrolled
+
+```tsx
+import { CustomToggle } from '@delightui/components';
+
+function ControlledVsUncontrolledExample() {
+  const [controlledValue, setControlledValue] = useState(false);
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
+      {/* Controlled */}
+      <div>
+        <h4>Controlled CustomToggle</h4>
+        <CustomToggle
+          value={controlledValue}
+          onValueChange={setControlledValue}
+          offContent="Controlled Off"
+          onContent="Controlled On"
+        />
+      </div>
+
+      {/* Uncontrolled with initial value */}
+      <div>
+        <h4>Uncontrolled CustomToggle</h4>
+        <CustomToggle
+          initialValue={true}
+          offContent="Uncontrolled Off"
+          onContent="Uncontrolled On"
+        />
+      </div>
+    </div>
+  );
+}
+```

package/docs/components/atoms/Icon.md

@@ -0,0 +1,365 @@
+# Icon
+
+## Description
+
+SVG icon component with dynamic imports that supports multiple icon styles and sizes. Provides a consistent way to display icons throughout the application with automatic SVG loading.
+
+## Aliases
+
+- SVG Icon
+- Vector Icon
+- Glyph
+- Symbol
+
+## Props Breakdown
+
+**Extends:** Standalone interface (no HTML element inheritance)
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `icon` | `string` | - | Yes | Name of the icon to be displayed |
+| `style` | `'Outlined' \| 'Filled' \| 'Round'` | `'Filled'` | No | Visual style variant of the icon |
+| `size` | `'Small' \| 'Medium' \| 'Large'` | `'Medium'` | No | Size variant of the icon |
+| `className` | `string` | - | No | Additional CSS class names |
+
+## How Icon Loading Works
+
+The Icon component uses a dynamic SVG import system that combines the `icon` and `style` props to load the appropriate SVG file. Here's how the variant props work together:
+
+### File Naming Convention
+The component constructs the SVG filename by concatenating the `icon` name with the `style` variant:
+```
+{icon}{style}.svg
+```
+
+**Examples:**
+- `icon="Add"` + `style="Filled"` → loads `/icons/AddFilled.svg`
+- `icon="Search"` + `style="Outlined"` → loads `/icons/SearchOutlined.svg`
+- `icon="Close"` + `style="Round"` → loads `/icons/CloseRound.svg`
+
+### Dynamic Loading Process
+1. **Filename Construction**: Combines `icon` + `style` props (e.g., "AddFilled")
+2. **Cache Check**: First checks if the SVG is already cached in memory
+3. **Deduplication**: Prevents duplicate requests if the same icon is requested multiple times
+4. **Network Fetch**: Downloads the SVG from `/icons/{iconName}{style}.svg`
+5. **Caching**: Stores the SVG content in memory for future use
+6. **Rendering**: Injects the SVG content using `dangerouslySetInnerHTML`
+
+### Loading States
+The component handles three states during the loading process:
+- **Loading**: Shows an empty div with appropriate size classes
+- **Error**: Shows an empty div if the SVG file cannot be loaded
+- **Success**: Renders the SVG content within a properly sized container
+
+### Performance Optimizations
+- **Memory Caching**: Downloaded SVGs are cached to avoid re-fetching
+- **Request Deduplication**: Multiple components requesting the same icon share a single network request
+- **Lazy Loading**: Icons are only loaded when the component is mounted and rendered
+
+### File Structure Requirements
+For the Icon component to work properly, SVG files must be organized in the public directory:
+```
+public/
+  icons/
+    AddFilled.svg
+    AddOutlined.svg
+    AddRound.svg
+    SearchFilled.svg
+    SearchOutlined.svg
+    SearchRound.svg
+    ...
+```
+
+## Examples
+
+### Basic Usage
+```tsx
+import { Icon } from '@delightui/components';
+
+function BasicExample() {
+  return (
+    <div className="icon-examples">
+      <Icon icon="Add" />
+      <Icon icon="Search" />
+      <Icon icon="Close" />
+    </div>
+  );
+}
+```
+
+### Icon Styles
+```tsx
+function StylesExample() {
+  return (
+    <div className="icon-styles">
+      <Icon icon="Add" style="Outlined" />
+      <Icon icon="Add" style="Filled" />
+      <Icon icon="Add" style="Round" />
+    </div>
+  );
+}
+```
+
+### Icon Sizes
+```tsx
+function SizesExample() {
+  return (
+    <div className="icon-sizes">
+      <Icon icon="Search" size="Small" />
+      <Icon icon="Search" size="Medium" />
+      <Icon icon="Search" size="Large" />
+    </div>
+  );
+}
+```
+
+### Common Icons
+```tsx
+function CommonIconsExample() {
+  const commonIcons = [
+    'Add', 'Search', 'Close', 'Check', 'ArrowForward',
+    'ExpandMore', 'Info', 'Error', 'Visibility', 'Edit'
+  ];
+
+  return (
+    <div className="common-icons">
+      {commonIcons.map(iconName => (
+        <div key={iconName} className="icon-item">
+          <Icon icon={iconName} />
+          <span>{iconName}</span>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+### In Buttons
+```tsx
+import { Icon, Button } from '@delightui/components';
+
+function ButtonIconsExample() {
+  return (
+    <div className="button-icons">
+      <Button leadingIcon={<Icon icon="Add" />}>
+        Add Item
+      </Button>
+      
+      <Button trailingIcon={<Icon icon="ArrowForward" />}>
+        Continue
+      </Button>
+      
+      <Button 
+        leadingIcon={<Icon icon="Search" />}
+        trailingIcon={<Icon icon="ExpandMore" />}
+      >
+        Search Options
+      </Button>
+    </div>
+  );
+}
+```
+
+### Navigation Icons
+```tsx
+import { NavLink, Text } from '@delightui/components';
+
+function NavigationExample() {
+  const navigationItems = [
+    { icon: 'Home', label: 'Dashboard' },
+    { icon: 'Person', label: 'Profile' },
+    { icon: 'Settings', label: 'Settings' },
+    { icon: 'Notifications', label: 'Notifications' },
+    { icon: 'Help', label: 'Help' }
+  ];
+
+  return (
+    <nav className="navigation">
+      {navigationItems.map(item => (
+        <NavLink key={item.label} href="#" className="nav-item">
+          <Icon icon={item.icon} size="Medium" />
+          <Text>{item.label}</Text>
+        </NavLink>
+      ))}
+    </nav>
+  );
+}
+```
+
+### Status Icons
+```tsx
+import { Text } from '@delightui/components';
+
+function StatusIconsExample() {
+  const statusItems = [
+    { status: 'success', icon: 'Check', color: 'green' },
+    { status: 'error', icon: 'Error', color: 'red' },
+    { status: 'warning', icon: 'Warning', color: 'orange' },
+    { status: 'info', icon: 'Info', color: 'blue' }
+  ];
+
+  return (
+    <div className="status-icons">
+      {statusItems.map(item => (
+        <div key={item.status} className={`status-item status-${item.status}`}>
+          <Icon 
+            icon={item.icon} 
+            style="Filled"
+            className={`icon-${item.color}`}
+          />
+          <Text>{item.status}</Text>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+### Interactive Icons
+```tsx
+import { Text } from '@delightui/components';
+
+function InteractiveIconsExample() {
+  const [favorites, setFavorites] = useState([]);
+  const [visibility, setVisibility] = useState({});
+
+  const toggleFavorite = (itemId) => {
+    setFavorites(prev => 
+      prev.includes(itemId)
+        ? prev.filter(id => id !== itemId)
+        : [...prev, itemId]
+    );
+  };
+
+  const toggleVisibility = (itemId) => {
+    setVisibility(prev => ({
+      ...prev,
+      [itemId]: !prev[itemId]
+    }));
+  };
+
+  return (
+    <div className="interactive-icons">
+      <div className="item">
+        <Text>Favorite this item</Text>
+        <Icon 
+          icon={favorites.includes(1) ? 'FavoriteFilled' : 'FavoriteOutlined'}
+          style={favorites.includes(1) ? 'Filled' : 'Outlined'}
+          className="clickable-icon"
+          onClick={() => toggleFavorite(1)}
+        />
+      </div>
+
+      <div className="item">
+        <Text>Toggle visibility</Text>
+        <Icon 
+          icon={visibility[1] ? 'VisibilityOff' : 'Visibility'}
+          style="Filled"
+          className="clickable-icon"
+          onClick={() => toggleVisibility(1)}
+        />
+      </div>
+    </div>
+  );
+}
+```
+
+### Form Field Icons
+```tsx
+import { Icon, Input, FormField } from '@delightui/components';
+
+function FormIconsExample() {
+  return (
+    <div className="form-icons">
+      <FormField name="email" label="Email">
+        <Input 
+          inputType="Email"
+          leadingIcon={<Icon icon="Email" />}
+          placeholder="Enter your email"
+        />
+      </FormField>
+
+      <FormField name="password" label="Password">
+        <Input 
+          inputType="Password"
+          leadingIcon={<Icon icon="Lock" />}
+          trailingIcon={<Icon icon="Visibility" />}
+          placeholder="Enter password"
+        />
+      </FormField>
+
+      <FormField name="search" label="Search">
+        <Input 
+          leadingIcon={<Icon icon="Search" />}
+          trailingIcon={<Icon icon="Close" />}
+          placeholder="Search..."
+        />
+      </FormField>
+    </div>
+  );
+}
+```
+
+### Icon Grid
+```tsx
+import { Text } from '@delightui/components';
+
+function IconGridExample() {
+  const allIcons = [
+    { name: 'Add', styles: ['Outlined', 'Filled', 'Round'] },
+    { name: 'Search', styles: ['Outlined', 'Filled', 'Round'] },
+    { name: 'Close', styles: ['Outlined', 'Filled', 'Round'] },
+    { name: 'Check', styles: ['Outlined', 'Filled', 'Round'] },
+    { name: 'ArrowForward', styles: ['Outlined', 'Filled', 'Round'] }
+  ];
+
+  return (
+    <div className="icon-grid">
+      {allIcons.map(iconGroup => (
+        <div key={iconGroup.name} className="icon-group">
+          <Text type="Heading4">{iconGroup.name}</Text>
+          <div className="icon-variants">
+            {iconGroup.styles.map(style => (
+              <div key={style} className="icon-variant">
+                <Icon 
+                  icon={iconGroup.name} 
+                  style={style}
+                  size="Large"
+                />
+                <Text type="BodySmall">{style}</Text>
+              </div>
+            ))}
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+### Custom Styling
+```tsx
+function CustomStylingExample() {
+  return (
+    <div className="custom-icon-styling">
+      <Icon 
+        icon="Star" 
+        className="icon-primary"
+        size="Large"
+      />
+      
+      <Icon 
+        icon="Heart" 
+        className="icon-danger animated-icon"
+        size="Medium"
+      />
+      
+      <Icon 
+        icon="Thumb_up" 
+        className="icon-success rotating-icon"
+        size="Small"
+      />
+    </div>
+  );
+}
+```