# FieldGroup

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs --> - field-group.variants — `fieldGroupVariants` is the……
- [field-group.variants](./field-group.variants.md) — `fieldGroupVariants` is the cva (class-variance-authority) configuration powering every `<FieldGroup>` render. It is sp…
- field-group.variants — `fieldGroupVariants` is the……

- [field-group.variants](./field-group.variants.md) — `fieldGroupVariants` is the cva (class-variance-authority) configuration powering every `<FieldGroup>` render. It is sp…

- field-group.variants — `fieldGroupVariants` is the……

- [field-group.variants](./field-group.variants.md) — `fieldGroupVariants` is the cva (class-variance-authority) configuration powering every `<FieldGroup>` render. It is sp…

- field-group.variants — `fieldGroupVariants` is the…

- [field-group.variants](./field-group.variants.md) — `fieldGroupVariants` is the cva (class-variance-authority) configuration powering every `<FieldGroup>` render. It is sp…
- [field-group.variants](./field-group.variants.md) — `fieldGroupVariants` is the cva (class-variance-authority) configuration powering every `<FieldGroup>` render. It is sp…

## Purpose

`<FieldGroup>` is the chassis vertical-stack container for `<Field>` instances. It renders a `<div>` with `flex flex-col gap-*` so siblings flow in document order regardless of writing direction (RTL / LTR). Per the shadcn skill rule the chassis NEVER uses `space-y-*` because it collapses cross-axis margin in unpredictable ways under RTL.

Per the cross-cutting reconciliation note (#1), shadcn ships `field-group` as a separate registry item from `field`; this package mirrors that split so each primitive evolves independently. `<FieldGroup>` is the typical container for CRUD forms — multiple `<Field>` instances stacked with a uniform gap.

The `gap` axis lets consumers tune spacing without reaching for arbitrary Tailwind classes: `sm` (8px) for dense settings panes, `default` (16px) for typical CRUD forms, `lg` (24px) for sectioned profile pages.

## Features

- Three gap sizes (`sm` → `gap-2`, `default` → `gap-4`, `lg` → `gap-6`).
- `flex flex-col` layout so siblings stack in document order under both LTR and RTL.
- Native HTML attributes forwarded — consumers drop `role="group" aria-labelledby="…"` for accessible grouping.
- Refs forwarded to the underlying `<div>`.
- Theme-driven variant overrides via `useThemedVariants("FieldGroup", fieldGroupVariants)`.
- NEVER uses `space-y-*` per the shadcn skill rule.

## Usage: Basic Example

```tsx
import { FieldGroup, Field, FieldLabel, Input } from "@suaveplan/react-ui";

export function ContactForm() {
    return (
        <FieldGroup>
            <Field>
                <FieldLabel htmlFor="email">Email</FieldLabel>
                <Input id="email" type="email" />
            </Field>
            <Field>
                <FieldLabel htmlFor="phone">Phone</FieldLabel>
                <Input id="phone" type="tel" />
            </Field>
        </FieldGroup>
    );
}
```

## Usage: Advanced Example

```tsx
import {
    FieldGroup,
    Field,
    FieldLabel,
    FieldDescription,
    Input,
} from "@suaveplan/react-ui";

export function ProfileSection() {
    return (
        <section aria-labelledby="profile-h">
            <h2 id="profile-h">Profile</h2>
            <FieldGroup gap="lg" role="group" aria-labelledby="profile-h">
                <Field>
                    <FieldLabel htmlFor="display-name">Display name</FieldLabel>
                    <Input id="display-name" />
                    <FieldDescription>Visible to other users.</FieldDescription>
                </Field>
                <Field>
                    <FieldLabel htmlFor="bio">Biography</FieldLabel>
                    <Input id="bio" />
                </Field>
                <Field>
                    <FieldLabel htmlFor="website">Website</FieldLabel>
                    <Input id="website" type="url" />
                </Field>
            </FieldGroup>
        </section>
    );
}
```

## API Reference

### `<FieldGroup>`

`forwardRef<HTMLDivElement, FieldGroupProps>` — renders a `<div>` container.

#### `FieldGroupProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `gap` | `"sm" \| "default" \| "lg"` | `"default"` | Spacing between sibling `<Field>` instances. |
| _all native_ `HTMLAttributes<HTMLDivElement>` | _native_ | _native_ | Forwarded as-is. |

#### `fieldGroupVariants`

The bare cva resolver. Exported so external consumers can re-use the variants directly.

## Implementation Notes

- The container is intentionally minimal — layout (`flex flex-col`), gap, and forwarded native attrs only. Consumers that need an explicit ARIA grouping role pass `role="group"` + `aria-labelledby` themselves.
- Per the shadcn skill rule, the cva NEVER uses `space-y-*` — `gap-*` flows the same in RTL and consumer-applied flex utilities stack predictably.
- Per the cross-cutting reconciliation note (#1), this is a separate registry item from `field`. Keeping them split lets a consumer eject only `field` if they want to compose their own group container.
- Refs target the `<div>` — consumers can measure or scroll-into-view the group programmatically.
- The `gap` axis maps directly to Tailwind's gap scale; consumers wanting an arbitrary gap pass `className="gap-3"` (Tailwind class merging via `tailwind-merge` resolves the conflict against the cva default).