# Button Component

A versatile, accessible button component with multiple styles, sizes, and states. Built with pure HTML, CSS, and JavaScript following best practices for accessibility and user experience.

## Features

- **Multiple Variants**: Primary and secondary button styles
- **Size Options**: Small, default, and large sizes
- **States**: Hover, active, focus, disabled, and loading states
- **Accessibility**: Full ARIA support and keyboard navigation
- **Responsive**: Mobile-first design with responsive sizing
- **Interactive**: Ripple effect animation on click
- **Dark Mode**: Automatic dark mode support
- **Icon Support**: Built-in icon button variants

## Usage

### Basic HTML Structure

```html

<button class="btn btn-primary" aria-label="Primary action">
    Primary Button
</button>


<button class="btn btn-secondary" aria-label="Secondary action">
    Secondary Button
</button>


<button class="btn btn-primary" disabled aria-disabled="true">
    Disabled Button
</button>
```

### Size Variants

```html

<button class="btn btn-primary btn-small">Small</button>


<button class="btn btn-primary">Default</button>


<button class="btn btn-primary btn-large">Large</button>


<button class="btn btn-primary btn-block">Full Width</button>
```

### Icon Buttons

```html

<button class="btn btn-primary btn-icon" aria-label="Download file">
    <svg class="btn-icon-svg"></svg>
    <span>Download</span>
</button>


<button class="btn btn-secondary btn-icon-only" aria-label="Settings">
    <svg class="btn-icon-svg"></svg>
</button>
```

### Loading State

```html

<button class="btn btn-primary btn-loading" aria-busy="true">
    <span class="btn-spinner"></span>
    <span>Loading...</span>
</button>
```

## JavaScript API

### Creating Buttons Programmatically

```javascript
// Create a button using the static method
const button = ButtonComponent.createButton({
    text: 'Click Me',
    type: 'primary',      // 'primary' or 'secondary'
    size: 'default',      // 'small', 'default', or 'large'
    disabled: false,
    loading: false,
    icon: null,           // HTML string for icon
    onClick: () => console.log('Button clicked'),
    ariaLabel: 'Custom action button'
});

// Append to container
document.body.appendChild(button);
```

### Managing Loading State

```javascript
const buttonComponent = new ButtonComponent();
const button = document.querySelector('.my-button');

// Set loading state
buttonComponent.setLoadingState(button, true);

// Remove loading state
setTimeout(() => {
    buttonComponent.setLoadingState(button, false);
}, 3000);
```

## CSS Variables

Customize the button appearance using CSS variables:

```css
:root {
    --btn-primary-bg: #3b82f6;
    --btn-primary-bg-hover: #2563eb;
    --btn-primary-bg-active: #1d4ed8;
    --btn-primary-text: #ffffff;

    --btn-secondary-bg: #e5e7eb;
    --btn-secondary-bg-hover: #d1d5db;
    --btn-secondary-bg-active: #9ca3af;
    --btn-secondary-text: #374151;

    --btn-disabled-bg: #e5e7eb;
    --btn-disabled-text: #9ca3af;

    --btn-focus-ring: rgba(59, 130, 246, 0.5);
    --btn-radius: 0.375rem;
    --btn-transition: all 0.2s ease;
}
```

## Accessibility

- **ARIA Labels**: All buttons include appropriate `aria-label` attributes
- **Keyboard Navigation**: Full support for Enter and Space key activation
- **Focus Management**: Clear focus indicators with customizable focus ring
- **Screen Reader Support**: Proper announcements for button states
- **Disabled State**: Uses both `disabled` attribute and `aria-disabled`
- **Loading State**: Uses `aria-busy` for loading announcements

## Browser Support

- Chrome/Edge 90+
- Firefox 88+
- Safari 14+
- Mobile browsers (iOS Safari, Chrome Mobile)

## Best Practices

1. **Always provide meaningful labels**: Use `aria-label` for icon-only buttons
2. **Indicate loading states**: Use `aria-busy` for asynchronous operations
3. **Maintain focus visibility**: Never remove focus indicators
4. **Use semantic HTML**: Prefer `<button>` over `<div>` with click handlers
5. **Provide feedback**: Use hover, active, and disabled states consistently
6. **Consider mobile**: Ensure touch targets are at least 44x44 pixels

## Examples

### Form Submit Button
```html
<form>
    <button type="submit" class="btn btn-primary btn-block">
        Submit Form
    </button>
</form>
```

### Async Action Button
```javascript
async function handleAsyncAction(button) {
    // Set loading state
    button.classList.add('btn-loading');
    button.setAttribute('aria-busy', 'true');
    button.disabled = true;

    try {
        await performAction();
        // Success handling
    } catch (error) {
        // Error handling
    } finally {
        // Remove loading state
        button.classList.remove('btn-loading');
        button.setAttribute('aria-busy', 'false');
        button.disabled = false;
    }
}
```

### Button Group
```html
<div role="group" aria-label="Text alignment">
    <button class="btn btn-secondary" aria-pressed="true">Left</button>
    <button class="btn btn-secondary" aria-pressed="false">Center</button>
    <button class="btn btn-secondary" aria-pressed="false">Right</button>
</div>
```

Accessible, responsive button component with multiple variants and states

button

Button Component

# Card Component

A flexible content container component with header, body, and footer sections. Supports various layouts, interactive states, and rich content including images, tags, and action buttons.

## Features

- **Multiple Layouts**: Vertical, horizontal, minimal, and image-based cards
- **Interactive States**: Hover effects, click handling, expandable content
- **Rich Content**: Images, badges, tags, meta information
- **Action Support**: Header actions, footer buttons, favorite toggles
- **Accessibility**: Semantic HTML, ARIA labels, keyboard navigation
- **Dark Mode**: Automatic dark mode support
- **Responsive**: Mobile-optimized grid layout

## Usage Examples

### Basic Card
```html
<article class="card">
  <header class="card-header">
    <h3 class="card-title">Card Title</h3>
  </header>
  <div class="card-body">
    <p class="card-text">Card content goes here.</p>
  </div>
  <footer class="card-footer">
    <button class="card-button">Action</button>
  </footer>
</article>
```

### Card with Image
```html
<article class="card card-with-image">
  <div class="card-image-wrapper">
    <img src="image.jpg" alt="Description" class="card-image">
  </div>
  <header class="card-header">
    <h3 class="card-title">Featured Content</h3>
  </header>
  
</article>
```

### Interactive Card
```javascript
// Listen for card clicks
document.addEventListener('card:click', (e) => {
  console.log('Card clicked:', e.detail.card);
});

// Filter cards by tag
document.dispatchEvent(new CustomEvent('card:filter', {
  detail: { tag: 'javascript' }
}));
```

### Programmatic Creation
```javascript
const newCard = cardComponent.createCard({
  title: 'Dynamic Card',
  text: 'Created programmatically',
  tags: ['new', 'featured'],
  image: 'https://example.com/image.jpg'
});
document.querySelector('.card-showcase').appendChild(newCard);
```

## Component Variants

### Default Card
Standard card with header, body, and footer sections.

### Image Card
Card with a featured image at the top, perfect for visual content.

### Horizontal Card
Side-by-side layout with image and content, ideal for lists.

### Interactive Card
Clickable card with hover effects and keyboard navigation.

### Minimal Card
Clean design with subtle borders, no shadows.

## Events

| Event | Description | Detail |
|-------|-------------|--------|
| `card:click` | Fired when interactive card is clicked | `{ card: HTMLElement }` |
| `card:action` | Fired when action button is clicked | `{ card, action, button }` |
| `card:edited` | Fired after inline editing | `{ card, title, text }` |
| `card:filter` | Filter cards by tag/category | `{ tag, category }` |
| `card:sort` | Sort cards | `{ sortBy }` |

## Accessibility Notes

- **Semantic Structure**: Uses `<article>` element with proper heading hierarchy
- **ARIA Labels**: All interactive elements have descriptive labels
- **Keyboard Navigation**: Full keyboard support with Tab and Enter/Space keys
- **Focus Indicators**: Clear visual focus states with 2px outline
- **Screen Reader Support**: Proper announcements for all states and actions
- **Color Contrast**: WCAG AA compliant color combinations
- **Responsive Touch Targets**: Minimum 44x44px for mobile devices

## CSS Variables

```css
/* Customize card appearance */
--card-bg: white;
--card-border: #e5e7eb;
--card-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
--card-radius: 0.75rem;
--card-padding: 1.25rem;
```

## Best Practices

1. Always include meaningful titles and alt text for images
2. Use semantic HTML structure (article, header, footer)
3. Provide keyboard navigation for interactive cards
4. Ensure sufficient color contrast for text
5. Use lazy loading for images in long lists
6. Keep card content concise and scannable
7. Group related actions in the card footer

Flexible content container with header, body, and footer sections supporting multiple layouts

card

Card Component

# Modal Component

A fully accessible modal dialog component with multiple variants, keyboard navigation, focus management, and animation support. Built with vanilla JavaScript and modern CSS.

## Features

- **Multiple Variants**: Basic, form, confirmation, fullscreen, scrollable
- **Accessibility**: ARIA attributes, focus trap, screen reader support
- **Keyboard Navigation**: Escape to close, Tab cycling within modal
- **Focus Management**: Auto-focus first element, restore focus on close
- **Animation**: Smooth open/close transitions
- **Backdrop**: Click-to-close with blur effect
- **Programmatic API**: Create modals dynamically
- **Form Support**: Unsaved changes warning
- **Responsive**: Mobile-optimized fullscreen on small screens

## Usage Examples

### Basic Modal
```html
<button data-modal="modal-basic">Open Modal</button>

<div id="modal-basic" class="modal" role="dialog">
  <div class="modal-backdrop"></div>
  <div class="modal-container">
    <div class="modal-content">
      
    </div>
  </div>
</div>
```

### Programmatic Modal
```javascript
// Create alert
modalComponent.alert('Operation completed successfully!', 'Success');

// Confirm dialog
const confirmed = await modalComponent.confirm('Delete this item?');
if (confirmed) {
  // Perform deletion
}

// Prompt for input
const name = await modalComponent.prompt('Enter your name:', 'Welcome');
```

### Custom Modal Creation
```javascript
const modal = modalComponent.createModal({
  title: 'Custom Modal',
  content: '<p>Custom content here</p>',
  size: 'wide',
  buttons: [
    { text: 'Cancel', variant: 'secondary', action: 'dismiss' },
    { text: 'Save', variant: 'primary', id: 'save-btn' }
  ]
});

modalComponent.openModal(modal.id);
```

### Event Handling
```javascript
// Listen for modal events
document.addEventListener('modal:opened', (e) => {
  console.log('Modal opened:', e.detail.modalId);
});

document.addEventListener('modal:closed', (e) => {
  console.log('Modal closed:', e.detail.modalId);
});

// Trigger via events
document.dispatchEvent(new CustomEvent('modal:open', {
  detail: { modalId: 'modal-basic' }
}));
```

## Modal Types

### Basic Modal
Standard modal with header, body, and footer sections.

### Form Modal
Modal containing form elements with validation support.

### Confirmation Modal
Alert-style modal for confirming actions with danger styling.

### Fullscreen Modal
Takes up entire viewport, ideal for complex content.

### Scrollable Modal
Fixed header/footer with scrollable body content.

## API Methods

| Method | Description | Parameters | Returns |
|--------|-------------|------------|---------|
| `openModal(id, options)` | Open modal by ID | `id: string, options: object` | `void` |
| `closeModal(id, options)` | Close modal | `id: string, options: object` | `void` |
| `toggleModal(id)` | Toggle modal state | `id: string` | `void` |
| `createModal(options)` | Create modal dynamically | `options: object` | `HTMLElement` |
| `alert(message, title)` | Show alert modal | `message: string, title: string` | `HTMLElement` |
| `confirm(message, title)` | Show confirmation | `message: string, title: string` | `Promise<boolean>` |
| `prompt(message, title, default)` | Show input prompt | `message: string, title: string, default: string` | `Promise<string|null>` |

## Events

| Event | Description | Detail |
|-------|-------------|--------|
| `modal:opened` | Fired when modal opens | `{ modalId, modal }` |
| `modal:closed` | Fired when modal closes | `{ modalId, modal }` |
| `modal:open` | Trigger modal open | `{ modalId, options }` |
| `modal:close` | Trigger modal close | `{ modalId, options }` |
| `modal:toggle` | Toggle modal state | `{ modalId }` |

## Accessibility Notes

- **Role & ARIA**: Proper `role="dialog"` with `aria-labelledby` and `aria-describedby`
- **Focus Management**: Automatic focus trap within modal, restores focus on close
- **Keyboard Navigation**:
  - `Escape` - Close modal
  - `Tab` - Cycle through focusable elements
  - `Shift+Tab` - Reverse cycle
- **Screen Reader**: Announces modal opening/closing with proper context
- **Backdrop**: Semi-transparent with blur for visual separation
- **Alert Dialogs**: Uses `role="alertdialog"` for critical confirmations
- **Form Labels**: All form inputs have associated labels

## CSS Variables

```css
/* Customize modal appearance */
--modal-bg: white;
--modal-backdrop: rgba(0, 0, 0, 0.5);
--modal-border-radius: 0.75rem;
--modal-shadow: 0 20px 25px rgba(0, 0, 0, 0.15);
--modal-max-width: 32rem;
--modal-z-index: 9999;
```

## Best Practices

1. Always provide meaningful titles and descriptions
2. Use appropriate modal size for content
3. Avoid nested modals
4. Provide clear action buttons
5. Handle unsaved form data before closing
6. Use confirmation modals for destructive actions
7. Ensure content is scrollable if needed
8. Test keyboard navigation thoroughly

Fully accessible modal dialog with keyboard navigation, focus management, and animation support

modal

Modal Component

# Toggle Switch Component

An iOS-style toggle switch component with smooth animations, async support, and full accessibility. Perfect for settings panels, forms, and preference controls.

## Features

- **iOS-Style Design**: Smooth animations and familiar interaction patterns
- **Async Support**: Loading states for server-side operations
- **Size Variants**: Small, default, and large sizes
- **Icon Support**: Optional icons for on/off states
- **Color Themes**: Default, colored (red/green), custom colors
- **State Labels**: Optional ON/OFF text labels
- **Group Behavior**: Settings panel with dependent toggles
- **Accessibility**: Full ARIA support, keyboard navigation
- **Loading States**: Built-in spinner for async operations
- **Feedback**: Success/error animations

## Usage Examples

### Basic Toggle
```html
<label class="toggle-wrapper" for="toggle-basic">
  <span class="toggle-label">Enable Feature</span>
  <input type="checkbox" id="toggle-basic" class="toggle-input" role="switch">
  <span class="toggle-switch"></span>
</label>
```

### Toggle with Description
```html
<label class="toggle-wrapper toggle-with-description">
  <div class="toggle-content">
    <span class="toggle-label">Notifications</span>
    <span class="toggle-description">Receive alerts</span>
  </div>
  <input type="checkbox" class="toggle-input" role="switch">
  <span class="toggle-switch"></span>
</label>
```

### Async Toggle
```javascript
// Listen for toggle events
document.addEventListener('toggle:beforeChange', async (e) => {
  const { toggleId, newState } = e.detail;

  // Validate or prevent change
  if (!canToggle) {
    e.preventDefault();
  }
});

document.addEventListener('toggle:change', (e) => {
  console.log('Toggle changed:', e.detail);
});
```

### Programmatic Control
```javascript
// Set toggle state
toggleSwitchComponent.setToggleState('toggle-wifi', true);

// Toggle state
toggleSwitchComponent.toggleState('toggle-bluetooth');

// Enable/disable
toggleSwitchComponent.setEnabled('toggle-airplane', false);

// Get state
const isEnabled = toggleSwitchComponent.getState('toggle-wifi');

// Get all states
const allStates = toggleSwitchComponent.getAllStates();
```

### Create Toggle Dynamically
```javascript
const toggle = toggleSwitchComponent.createToggle({
  label: 'Dark Mode',
  description: 'Use dark theme',
  checked: false,
  withIcons: true,
  async: true
});

document.querySelector('.settings').appendChild(toggle);
```

## Toggle Variants

### Basic Toggle
Standard on/off switch with label.

### Toggle with Icons
Shows sun/moon icons for theme switching.

### Colored Toggle
Red when off, green when on.

### Small/Large Sizes
Compact or prominent toggle sizes.

### Async Toggle
Loading spinner during server operations.

### Settings List
Group of toggles in a settings panel.

### State Labels
Shows ON/OFF text beside toggle.

## Events

| Event | Description | Detail |
|-------|-------------|--------|
| `toggle:change` | Fired when toggle changes | `{ toggleId, checked }` |
| `toggle:beforeChange` | Before async change (cancelable) | `{ toggleId, newState }` |
| `toggle:error` | Async operation failed | `{ toggleId, error }` |
| `toggle:reset` | Toggle reset to original | `{ toggleId }` |
| `toggle:set` | Set toggle state via API | `{ toggleId, checked }` |
| `toggle:toggle` | Toggle state via API | `{ toggleId }` |
| `toggle:enable` | Enable/disable via API | `{ toggleId, enabled }` |

## API Methods

| Method | Description | Parameters | Returns |
|--------|-------------|------------|---------|
| `setToggleState(id, checked)` | Set toggle state | `id: string, checked: boolean` | `void` |
| `toggleState(id)` | Toggle state | `id: string` | `void` |
| `setEnabled(id, enabled)` | Enable/disable toggle | `id: string, enabled: boolean` | `void` |
| `getState(id)` | Get toggle state | `id: string` | `boolean` |
| `getAllStates()` | Get all toggle states | - | `object` |
| `resetToggle(id)` | Reset to original state | `id: string` | `void` |
| `resetAll()` | Reset all toggles | - | `void` |
| `createToggle(options)` | Create toggle dynamically | `options: object` | `HTMLElement` |

## Accessibility Notes

- **Role & ARIA**: Uses `role="switch"` with `aria-checked` state
- **Keyboard Navigation**:
  - `Space` or `Enter` - Toggle state
  - `Tab` - Navigate between toggles
- **Screen Reader**: Announces state changes with proper labels
- **Focus Indicators**: Clear 2px outline on focus
- **Disabled State**: Properly conveyed with reduced opacity and cursor
- **Loading State**: Uses `aria-busy` during async operations
- **Labels**: All toggles have associated labels for context

## CSS Variables

```css
/* Customize toggle appearance */
--toggle-width: 44px;
--toggle-height: 24px;
--toggle-thumb-size: 20px;
--toggle-bg-off: #cbd5e1;
--toggle-bg-on: #3b82f6;
--toggle-transition: 0.2s ease-in-out;
```

## Keyboard Shortcuts

- **Space/Enter** - Toggle switch state
- **Tab** - Move to next toggle
- **Shift+Tab** - Move to previous toggle

## Best Practices

1. Always provide clear labels describing what the toggle controls
2. Use descriptions for complex settings
3. Group related toggles together
4. Provide feedback for async operations
5. Handle errors gracefully with visual feedback
6. Use appropriate size variants for context
7. Consider using state labels for clarity
8. Test keyboard navigation thoroughly
9. Ensure sufficient color contrast
10. Avoid using toggles for actions (use buttons instead)

iOS-style toggle switch with smooth animations, async support, and full accessibility

UI Components

Filter & Search

Components Library

Button Component

Card Component

Modal Component

Toggle Switch Component

Component Library Stats