# @arbor-ds/components

React components for the Arbor Design System.

## Installation

```bash
npm install @arbor-ds/components @arbor-ds/tokens
```

**Peer Dependencies:**
- React >= 18.0.0
- React DOM >= 18.0.0

## Usage

### Import Components

```tsx
import { Button, Card, Input } from '@arbor-ds/components';
```

### Import CSS Variables (Optional)

For design tokens to be available as CSS variables:

```tsx
import '@arbor-ds/tokens/css';
```

## Components

### Button

A versatile button component with multiple variants and sizes.

```tsx
<Button variant="primary" size="md" onClick={() => console.log('Clicked')}>
  Click me
</Button>
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `variant` | `'primary' \| 'secondary' \| 'ghost'` | `'primary'` | Visual style variant |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Button size |
| `asChild` | `boolean` | `false` | Render as child component |
| `disabled` | `boolean` | `false` | Disabled state |
| `children` | `ReactNode` | - | Button content |

#### Examples

```tsx
// Primary button
<Button variant="primary">Submit</Button>

// Secondary button
<Button variant="secondary">Cancel</Button>

// Ghost button
<Button variant="ghost">Learn more</Button>

// Small size
<Button size="sm">Small button</Button>

// Large size
<Button size="lg">Large button</Button>

// Disabled
<Button disabled>Disabled button</Button>

// As child (renders as link)
<Button asChild>
  <a href="/home">Go home</a>
</Button>
```

---

### Card

A container component with consistent styling and flexible padding.

```tsx
<Card padding="md">
  <h2>Card Title</h2>
  <p>Card content goes here</p>
</Card>
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `padding` | `'none' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Internal padding |
| `children` | `ReactNode` | - | Card content |

#### Examples

```tsx
// Standard card
<Card>
  <h3>Default padding</h3>
</Card>

// No padding
<Card padding="none">
  <img src="/banner.jpg" alt="Banner" />
</Card>

// Small padding
<Card padding="sm">Compact content</Card>

// Large padding
<Card padding="lg">
  <h1>Spacious content</h1>
</Card>
```

---

### Input

A text input component with label, validation states, and helper text.

```tsx
<Input
  label="Email"
  type="email"
  placeholder="you@example.com"
  helperText="We'll never share your email"
/>
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `label` | `string` | - | Input label |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Input size |
| `state` | `'default' \| 'error' \| 'success'` | `'default'` | Validation state |
| `error` | `string` | - | Error message to display |
| `helperText` | `string` | - | Helper text below input |
| `type` | `string` | `'text'` | HTML input type |
| `placeholder` | `string` | - | Placeholder text |
| `disabled` | `boolean` | `false` | Disabled state |

#### Examples

```tsx
// Basic input
<Input placeholder="Enter your name" />

// With label
<Input label="Email" type="email" />

// With helper text
<Input
  label="Password"
  type="password"
  helperText="Must be at least 8 characters"
/>

// Error state
<Input
  label="Username"
  error="This username is already taken"
/>

// Success state
<Input
  label="Email"
  state="success"
  value="valid@email.com"
/>

// Different sizes
<Input size="sm" placeholder="Small" />
<Input size="md" placeholder="Medium" />
<Input size="lg" placeholder="Large" />

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

---

## Composition Example

```tsx
import { Button, Card, Input } from '@arbor-ds/components';

function LoginForm() {
  return (
    <Card padding="lg">
      <h2>Sign In</h2>

      <Input
        label="Email"
        type="email"
        placeholder="you@example.com"
      />

      <Input
        label="Password"
        type="password"
        placeholder="••••••••"
      />

      <Button variant="primary" size="md">
        Sign In
      </Button>

      <Button variant="ghost" size="sm">
        Forgot password?
      </Button>
    </Card>
  );
}
```

## Accessibility

All components are built with accessibility in mind:

- **Button**: Proper focus states, keyboard navigation
- **Card**: Semantic HTML structure
- **Input**: Associated labels, ARIA attributes, error announcements

## Customization

Components accept standard HTML attributes and can be customized via:

1. **className**: Add custom CSS classes
2. **style**: Inline styles (merged with component styles)
3. **Design tokens**: Modify tokens to change global appearance

Example:

```tsx
<Button className="my-custom-button" style={{ marginTop: '1rem' }}>
  Custom styled button
</Button>
```

## TypeScript

Full TypeScript support with exported types:

```tsx
import type { ButtonProps, CardProps, InputProps } from '@arbor-ds/components';
```

## Development

### Build

```bash
npm run build
```

### Watch Mode

```bash
npm run dev
```

### Tests

```bash
npm test
```

## License

MIT