# Form Group

`st-form-group` is a layout wrapper component that groups form components with consistent vertical spacing. It provides three gap variants to suit different layout densities and accessibility needs.

## Features

- **Three gap variants**: tight (6px), normal (12px), relaxed (16px)
- **CVA-based styling**: Class-variance-authority for efficient variant management
- **Custom class support**: Merge additional Tailwind classes with `cn()` utility
- **Flexible content projection**: Wrap any form items or custom content
- **Fully typed**: Complete TypeScript support with JSDoc annotations

## Usage

### Basic Usage (Default - Tight Gap)

```html
<st-form-group>
  <st-form-item>
    <st-input label="Email" [(value)]="email"></st-input>
  </st-form-item>
  <st-form-item>
    <st-input label="Password" type="password" [(value)]="password"></st-input>
  </st-form-item>
</st-form-group>
```

### Tight Gap (Compact Spacing - 6px)

Use for dense layouts or when space is limited.

```html
<st-form-group gap="tight">
  <st-form-item><st-input label="First" ...></st-input></st-form-item>
  <st-form-item><st-input label="Second" ...></st-input></st-form-item>
</st-form-group>
```

### Normal Gap (12px)

Use when you want more breathing room between fields.

```html
<st-form-group gap="normal">
  <!-- form items -->
</st-form-group>
```

Or simply omit the gap prop (defaults to "tight"):

```html
<st-form-group>
  <!-- form items -->
</st-form-group>
```

### Relaxed Gap (Spacious Spacing - 16px)

Best for accessibility-focused forms and improved readability.

```html
<st-form-group gap="relaxed">
  <st-form-item><st-input label="Email" ...></st-input></st-form-item>
  <st-form-item><st-input label="Phone" ...></st-input></st-form-item>
</st-form-group>
```

## With Custom Classes

Merge custom Tailwind classes with the gap variant:

```html
<st-form-group gap="tight" class="bg-base-200 border-primary rounded-lg border p-6">
  <!-- form items with tight spacing + custom styling -->
</st-form-group>
```

Responsive modifications:

```html
<st-form-group gap="tight" class="md:p-8 lg:gap-4">
  <!-- responsive padding and gap adjustments -->
</st-form-group>
```

## API

### Inputs

| Input   | Type                               | Default   | Description                                                               |
| ------- | ---------------------------------- | --------- | ------------------------------------------------------------------------- |
| `gap`   | `'tight' \| 'normal' \| 'relaxed'` | `'tight'` | Vertical spacing between form items. Tight=6px, Normal=12px, Relaxed=16px |
| `class` | `string`                           | `''`      | Additional custom Tailwind CSS classes                                    |

### Slot

| Slot      | Description                               |
| --------- | ----------------------------------------- |
| (default) | Any form items or custom content to group |

## Gap Variants Reference

| Variant     | Spacing        | Tailwind Class | Use Case                                                  |
| ----------- | -------------- | -------------- | --------------------------------------------------------- |
| **tight**   | 6px (0.375rem) | `gap-1.5`      | Compact forms, modal dialogs, dense layouts (default)     |
| **normal**  | 12px (0.75rem) | `gap-3`        | Standard forms, roomier layout                            |
| **relaxed** | 16px (1rem)    | `gap-4`        | Accessible forms, improved readability, touch-friendly UI |

## Notes

- Always place `st-form-errors` as a sibling inside `st-form-item`, not as a child of input components
- Combine with `st-form-item` for consistent field + error message layout
- Use `cn()` utility internally for proper Tailwind class precedence
- Fully compatible with Angular 19 signals and reactive forms