Initial Commit

packages/ui/react/react-ui/src/components/field-group/field-group.md

@@ -0,0 +1,116 @@
+# 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).