# ButtonGroup

## Description

A container component that groups related buttons together with consistent spacing and styling. Supports horizontal and vertical layouts with different visual treatments to create cohesive button collections for actions, navigation, and selection interfaces.

## Aliases

- ButtonGroup
- ActionGroup
- ButtonSet
- ToolbarGroup
- ButtonCluster

## Props Breakdown

**Extends:** Standalone interface (no HTML element inheritance)

| Prop | Type | Default | Required | Description |
|------|------|---------|----------|-------------|
| `children` | `ReactNode \| ReactNode[]` | - | Yes | Button components to group together |
| `align` | `'Horizontal' \| 'Vertical'` | `'Horizontal'` | No | Layout direction for the button group |
| `type` | `'Outlined' \| 'Ghost'` | `'Filled'` | No | Visual style variant for the group |
| `className` | `string` | - | No | Additional CSS class names |

## Examples

### Basic Usage
```tsx
import { ButtonGroup, Button } from '@delightui/components';

function BasicExample() {
  return (
    <ButtonGroup>
      <Button>First</Button>
      <Button>Second</Button>
      <Button>Third</Button>
    </ButtonGroup>
  );
}
```

### Horizontal vs Vertical Layout
```tsx
function LayoutExample() {
  return (
    <div className="layout-examples">
      <div className="horizontal-group">
        <Text type="Heading6">Horizontal Group</Text>
        <ButtonGroup align="Horizontal">
          <Button>Save</Button>
          <Button type="Outlined">Cancel</Button>
          <Button style="Destructive">Delete</Button>
        </ButtonGroup>
      </div>
      
      <div className="vertical-group">
        <Text type="Heading6">Vertical Group</Text>
        <ButtonGroup align="Vertical">
          <Button>Edit Profile</Button>
          <Button>Change Password</Button>
          <Button>Privacy Settings</Button>
          <Button style="Destructive">Delete Account</Button>
        </ButtonGroup>
      </div>
    </div>
  );
}
```

### Button Group Types
```tsx
function TypesExample() {
  return (
    <div className="button-group-types">
      <ButtonGroup type="Outlined">
        <Button>Option A</Button>
        <Button>Option B</Button>
        <Button>Option C</Button>
      </ButtonGroup>
      
      <ButtonGroup type="Ghost">
        <Button>Home</Button>
        <Button>About</Button>
        <Button>Contact</Button>
      </ButtonGroup>
    </div>
  );
}
```

### Action Groups
```tsx
function ActionGroupExample() {
  const [selectedAction, setSelectedAction] = useState('edit');

  return (
    <div className="action-groups">
      <ButtonGroup>
        <Button 
          type={selectedAction === 'edit' ? 'Filled' : 'Outlined'}
          onClick={() => setSelectedAction('edit')}
          leadingIcon={<Icon icon="Edit" />}
        >
          Edit
        </Button>
        <Button 
          type={selectedAction === 'copy' ? 'Filled' : 'Outlined'}
          onClick={() => setSelectedAction('copy')}
          leadingIcon={<Icon icon="Copy" />}
        >
          Copy
        </Button>
        <Button 
          type={selectedAction === 'delete' ? 'Filled' : 'Outlined'}
          onClick={() => setSelectedAction('delete')}
          leadingIcon={<Icon icon="Delete" />}
          style="Destructive"
        >
          Delete
        </Button>
      </ButtonGroup>
    </div>
  );
}
```

### Navigation Group
```tsx
function NavigationGroupExample() {
  const [currentPage, setCurrentPage] = useState('dashboard');

  const navItems = [
    { id: 'dashboard', label: 'Dashboard', icon: 'Dashboard' },
    { id: 'projects', label: 'Projects', icon: 'Folder' },
    { id: 'team', label: 'Team', icon: 'People' },
    { id: 'settings', label: 'Settings', icon: 'Settings' }
  ];

  return (
    <ButtonGroup align="Vertical" type="Ghost">
      <List
        data={navItems}
        component={({ id, label, icon }) => (
          <Button 
            type={currentPage === id ? 'Filled' : 'Ghost'}
            onClick={() => setCurrentPage(id)}
            leadingIcon={<Icon icon={icon} />}
          >
            {label}
          </Button>
        )}
        keyExtractor={(item) => item.id}
      />
    </ButtonGroup>
  );
}
```

### Toggle Group
```tsx
function ToggleGroupExample() {
  const [selectedOptions, setSelectedOptions] = useState(['bold']);

  const toggleOption = (option) => {
    setSelectedOptions(prev => 
      prev.includes(option)
        ? prev.filter(o => o !== option)
        : [...prev, option]
    );
  };

  return (
    <div className="toggle-groups">
      <Text type="Heading6">Text Formatting</Text>
      <ButtonGroup type="Outlined">
        <Button 
          type={selectedOptions.includes('bold') ? 'Filled' : 'Outlined'}
          onClick={() => toggleOption('bold')}
          leadingIcon={<Icon icon="FormatBold" />}
        >
          Bold
        </Button>
        <Button 
          type={selectedOptions.includes('italic') ? 'Filled' : 'Outlined'}
          onClick={() => toggleOption('italic')}
          leadingIcon={<Icon icon="FormatItalic" />}
        >
          Italic
        </Button>
        <Button 
          type={selectedOptions.includes('underline') ? 'Filled' : 'Outlined'}
          onClick={() => toggleOption('underline')}
          leadingIcon={<Icon icon="FormatUnderline" />}
        >
          Underline
        </Button>
      </ButtonGroup>
    </div>
  );
}
```

### Form Button Groups
```tsx
function FormButtonGroupExample() {
  const handleSave = () => {
    console.log('Saving...');
  };

  const handleCancel = () => {
    console.log('Cancelling...');
  };

  const handleReset = () => {
    console.log('Resetting...');
  };

  return (
    <Form>
      <FormField name="title" label="Title" required>
        <Input placeholder="Enter title" />
      </FormField>
      
      <FormField name="description" label="Description">
        <TextArea placeholder="Enter description" rows={4} />
      </FormField>
      
      <ButtonGroup>
        <Button onClick={handleSave}>Save</Button>
        <Button type="Outlined" onClick={handleCancel}>Cancel</Button>
        <Button type="Ghost" onClick={handleReset}>Reset</Button>
      </ButtonGroup>
    </Form>
  );
}
```

### Icon Button Groups
```tsx
function IconButtonGroupExample() {
  const [view, setView] = useState('grid');

  return (
    <div className="icon-button-groups">
      <Text type="Heading6">View Options</Text>
      <ButtonGroup type="Outlined">
        <Button 
          type={view === 'list' ? 'Filled' : 'Outlined'}
          onClick={() => setView('list')}
          aria-label="List view"
        >
          <Icon icon="List" />
        </Button>
        <Button 
          type={view === 'grid' ? 'Filled' : 'Outlined'}
          onClick={() => setView('grid')}
          aria-label="Grid view"
        >
          <Icon icon="Grid" />
        </Button>
        <Button 
          type={view === 'card' ? 'Filled' : 'Outlined'}
          onClick={() => setView('card')}
          aria-label="Card view"
        >
          <Icon icon="Card" />
        </Button>
      </ButtonGroup>
    </div>
  );
}
```

### Loading States
```tsx
function LoadingStatesExample() {
  const [loadingStates, setLoadingStates] = useState({
    save: false,
    publish: false,
    delete: false
  });

  const handleAction = async (action) => {
    setLoadingStates(prev => ({ ...prev, [action]: true }));
    
    // Simulate async operation
    await new Promise(resolve => setTimeout(resolve, 2000));
    
    setLoadingStates(prev => ({ ...prev, [action]: false }));
  };

  return (
    <ButtonGroup>
      <Button 
        loading={loadingStates.save}
        onClick={() => handleAction('save')}
        disabled={Object.values(loadingStates).some(Boolean)}
      >
        Save Draft
      </Button>
      <Button 
        loading={loadingStates.publish}
        onClick={() => handleAction('publish')}
        disabled={Object.values(loadingStates).some(Boolean)}
      >
        Publish
      </Button>
      <Button 
        style="Destructive"
        loading={loadingStates.delete}
        onClick={() => handleAction('delete')}
        disabled={Object.values(loadingStates).some(Boolean)}
      >
        Delete
      </Button>
    </ButtonGroup>
  );
}
```

### Responsive Button Groups
```tsx
function ResponsiveButtonGroupExample() {
  const [isMobile, setIsMobile] = useState(false);

  useEffect(() => {
    const checkScreenSize = () => {
      setIsMobile(window.innerWidth < 768);
    };

    checkScreenSize();
    window.addEventListener('resize', checkScreenSize);
    return () => window.removeEventListener('resize', checkScreenSize);
  }, []);

  return (
    <ButtonGroup align={isMobile ? 'Vertical' : 'Horizontal'}>
      <Button>Action 1</Button>
      <Button>Action 2</Button>
      <Button>Action 3</Button>
    </ButtonGroup>
  );
}
```

### Button Group with Dropdowns
```tsx
function DropdownButtonGroupExample() {
  const [showDropdown, setShowDropdown] = useState(false);

  return (
    <div className="dropdown-button-group">
      <ButtonGroup>
        <Button onClick={() => console.log('Primary action')}>
          Save
        </Button>
        <Button 
          type="Outlined"
          onClick={() => setShowDropdown(!showDropdown)}
          trailingIcon={<Icon icon="ExpandMore" />}
        >
          Options
        </Button>
      </ButtonGroup>
      
      {showDropdown && (
        <div className="dropdown-menu">
          <Button type="Ghost" onClick={() => console.log('Save as...')}>
            Save as...
          </Button>
          <Button type="Ghost" onClick={() => console.log('Save and publish')}>
            Save and Publish
          </Button>
          <Button type="Ghost" onClick={() => console.log('Save template')}>
            Save as Template
          </Button>
        </div>
      )}
    </div>
  );
}
```