# UI Components Documentation

This documentation provides comprehensive information about all UI components in the Agent C Starter Kit, including usage examples, props, and best practices.

## Table of Contents

- [Button](#button)
- [Input](#input)
- [Card](#card)
- [Modal](#modal)
- [Loading](#loading)

---

## Button

A versatile button component with multiple variants, sizes, and states.

### Usage

```tsx
import { Button } from '@agentc/starter-kit';

// Basic usage
<Button>Click me</Button>

// With variant and size
<Button variant="primary" size="lg">
  Large Primary Button
</Button>

// Loading state
<Button loading onClick={handleClick}>
  Submit
</Button>

// Disabled state
<Button disabled>
  Disabled Button
</Button>
```

### Props

| Prop        | Type                                                           | Default     | Description                     |
| ----------- | -------------------------------------------------------------- | ----------- | ------------------------------- |
| `variant`   | `'primary' \| 'secondary' \| 'outline' \| 'ghost' \| 'danger'` | `'primary'` | Visual style variant            |
| `size`      | `'sm' \| 'md' \| 'lg'`                                         | `'md'`      | Button size                     |
| `disabled`  | `boolean`                                                      | `false`     | Whether the button is disabled  |
| `loading`   | `boolean`                                                      | `false`     | Whether to show loading spinner |
| `type`      | `'button' \| 'submit' \| 'reset'`                              | `'button'`  | HTML button type                |
| `onClick`   | `(event: React.MouseEvent<HTMLButtonElement>) => void`         | -           | Click event handler             |
| `className` | `string`                                                       | `''`        | Additional CSS classes          |
| `children`  | `React.ReactNode`                                              | -           | Button content                  |

### Accessibility Props

| Prop              | Type      | Description                             |
| ----------------- | --------- | --------------------------------------- |
| `ariaLabel`       | `string`  | Accessible label for screen readers     |
| `ariaDescribedBy` | `string`  | ID of element that describes the button |
| `ariaExpanded`    | `boolean` | Whether associated content is expanded  |
| `ariaPressed`     | `boolean` | Pressed state for toggle buttons        |

### Variants

- **Primary**: Main call-to-action buttons
- **Secondary**: Secondary actions
- **Outline**: Outlined buttons for less emphasis
- **Ghost**: Minimal styling for subtle actions
- **Danger**: Destructive actions (delete, remove, etc.)

### Best Practices

- Use `primary` variant sparingly for main call-to-action
- Always provide meaningful button text or `ariaLabel`
- Use `loading` state for async operations
- Consider using `ghost` variant for icon-only buttons

---

## Input

A flexible input component with support for various types and states.

### Usage

```tsx
import { Input } from '@agentc/starter-kit';

// Basic usage
<Input placeholder="Enter your name" />

// With label and error
<Input
  label="Email"
  type="email"
  error="Please enter a valid email"
  required
/>

// Disabled state
<Input disabled placeholder="Disabled input" />
```

### Props

| Prop           | Type                                                   | Default  | Description                    |
| -------------- | ------------------------------------------------------ | -------- | ------------------------------ |
| `type`         | HTML input types                                       | `'text'` | Input type                     |
| `placeholder`  | `string`                                               | -        | Placeholder text               |
| `value`        | `string`                                               | -        | Controlled value               |
| `defaultValue` | `string`                                               | -        | Default value for uncontrolled |
| `onChange`     | `(event: React.ChangeEvent<HTMLInputElement>) => void` | -        | Change event handler           |
| `onBlur`       | `(event: React.FocusEvent<HTMLInputElement>) => void`  | -        | Blur event handler             |
| `onFocus`      | `(event: React.FocusEvent<HTMLInputElement>) => void`  | -        | Focus event handler            |
| `disabled`     | `boolean`                                              | `false`  | Whether input is disabled      |
| `required`     | `boolean`                                              | `false`  | Whether input is required      |
| `label`        | `string`                                               | -        | Input label                    |
| `error`        | `string`                                               | -        | Error message to display       |
| `className`    | `string`                                               | `''`     | Additional CSS classes         |

### Best Practices

- Always provide accessible labels
- Use appropriate input types (`email`, `tel`, `password`, etc.)
- Show clear error states with descriptive messages
- Consider using placeholder text as hints, not labels

---

## Card

A container component for grouping related content with optional header and footer.

### Usage

```tsx
import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from '@agentc/starter-kit';

// Basic usage
<Card>
  <CardContent>
    Simple card content
  </CardContent>
</Card>

// Full structure
<Card>
  <CardHeader>
    <CardTitle>Card Title</CardTitle>
    <CardDescription>Card description text</CardDescription>
  </CardHeader>
  <CardContent>
    Main card content goes here
  </CardContent>
  <CardFooter>
    <Button>Action</Button>
  </CardFooter>
</Card>
```

### Components

#### Card

Main container component.

| Prop        | Type              | Default | Description            |
| ----------- | ----------------- | ------- | ---------------------- |
| `className` | `string`          | `''`    | Additional CSS classes |
| `children`  | `React.ReactNode` | -       | Card content           |

#### CardHeader

Header section of the card.

#### CardTitle

Title text for the card header.

#### CardDescription

Description text for the card header.

#### CardContent

Main content area of the card.

#### CardFooter

Footer section for actions or additional info.

### Best Practices

- Use semantic structure with proper header/content/footer
- Keep card content focused and related
- Consider responsive design for different screen sizes

---

## Modal

A dialog component for displaying overlay content.

### Usage

```tsx
import {
  Modal,
  ModalHeader,
  ModalTitle,
  ModalDescription,
  ModalContent,
  ModalFooter,
} from "@agentc/starter-kit";

const [isOpen, setIsOpen] = useState(false);

<Modal open={isOpen} onOpenChange={setIsOpen}>
  <ModalHeader>
    <ModalTitle>Confirm Action</ModalTitle>
    <ModalDescription>Are you sure you want to proceed?</ModalDescription>
  </ModalHeader>
  <ModalContent>Additional content here</ModalContent>
  <ModalFooter>
    <Button variant="outline" onClick={() => setIsOpen(false)}>
      Cancel
    </Button>
    <Button onClick={handleConfirm}>Confirm</Button>
  </ModalFooter>
</Modal>;
```

### Props

#### Modal

| Prop                  | Type                      | Default | Description                       |
| --------------------- | ------------------------- | ------- | --------------------------------- |
| `open`                | `boolean`                 | `false` | Whether modal is open             |
| `onOpenChange`        | `(open: boolean) => void` | -       | Called when open state changes    |
| `closeOnOverlayClick` | `boolean`                 | `true`  | Close modal when clicking overlay |
| `closeOnEscape`       | `boolean`                 | `true`  | Close modal on Escape key         |
| `className`           | `string`                  | `''`    | Additional CSS classes            |
| `children`            | `React.ReactNode`         | -       | Modal content                     |

### Components

- **ModalHeader**: Header section with close button
- **ModalTitle**: Title for the modal
- **ModalDescription**: Description text
- **ModalContent**: Main content area
- **ModalFooter**: Footer for actions

### Best Practices

- Always provide a way to close the modal
- Use descriptive titles and descriptions
- Focus management for accessibility
- Consider mobile responsive design

---

## Loading

A loading indicator component with different variants.

### Usage

```tsx
import { Loading } from '@agentc/starter-kit';

// Basic spinner
<Loading />

// With text
<Loading text="Loading..." />

// Different sizes
<Loading size="sm" />
<Loading size="lg" />
```

### Props

| Prop        | Type                   | Default | Description            |
| ----------- | ---------------------- | ------- | ---------------------- |
| `size`      | `'sm' \| 'md' \| 'lg'` | `'md'`  | Loading indicator size |
| `text`      | `string`               | -       | Optional loading text  |
| `className` | `string`               | `''`    | Additional CSS classes |

### Best Practices

- Use appropriate size for the context
- Provide loading text for better user experience
- Consider using in buttons or overlays for async operations

---

## General Guidelines

### Accessibility

All components follow accessibility best practices:

- Proper ARIA attributes
- Keyboard navigation support
- Screen reader compatibility
- Focus management

### Styling

Components use Tailwind CSS with design tokens:

- Consistent spacing and sizing
- Theme-aware colors
- Responsive design patterns
- Dark mode support

### TypeScript

All components are fully typed:

- Props interfaces exported
- Generic support where applicable
- Strict type checking
- IntelliSense support

### Testing

Components should be tested with:

- Unit tests for functionality
- Accessibility tests
- Visual regression tests
- Integration tests