---

## FormField
Layout wrapper for composite form fields that need a label,
helper text, and error message but cannot rely on the built-in slots of
primitives like `InputProps` or `SelectProps`. Examples:
a custom file picker, a slider/number-input pair, a media uploader.

The `id` is auto-generated and forwarded to the slot via the `for`
snippet parameter so the rendered control can wire `aria-describedby`
and `aria-invalid` correctly.

**Import:** `import { FormField } from '@urbicon-ui/blocks';`

### Examples
```svelte
<FormField label="Document" required error={fileError} helper="PDF, JPG, PNG — max 10 MB">
  {#snippet children({ id, describedBy, invalid })}
    <FileUpload {id} aria-describedby={describedBy} aria-invalid={invalid || undefined} bind:files />
  {/snippet}
</FormField>
```

### Variants
- required: true (default: false)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| children | `Snippet<[FormFieldSlotContext]>` | yes |  | Snippet receiving wiring metadata (`id`, `describedBy`, `invalid`, `required`, `disabled`). The wrapped control should spread or apply these to itself for accessibility. |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| class | `string` | no |  | Extra classes merged onto the wrapper element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. |
| disabled | `boolean` | no | false | Handed to the `children` snippet as `disabled`; FormField renders nothing differently itself. The wrapped control has to apply it. |
| error | `string` | no |  | Error message shown below the control. Replaces the helper text and propagates `invalid: true` to the slot for ARIA wiring. |
| helper | `string` | no |  | Helper text shown below the control. Hidden when `error` is present. Named `helper` to match the built-in helper prop of the form primitives (Input, Select, Toggle, …) — one vocabulary across the API seam. |
| id | `string` | no |  | Explicit HTML `id` for the control. Auto-generated when omitted, then forwarded to the slot. Caller may use it to attach external `<label for>`. |
| label | `string` | no |  | Label rendered above the control. Auto-linked to the slot via the generated `id`. |
| required | `boolean` | no | false | Adds a required asterisk to the label and propagates `required: true` to the slot. Does **not** apply the native `required` attribute — the slot's control is responsible for that. |
| slotClasses | `Partial<Record<FormFieldSlots, string>>` | no |  | Per-slot class overrides. Slots: wrapper (what `class` also targets) | label | requiredMark | message | helper. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. |

Inherited from:
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

### Types
```ts
interface FormFieldSlotContext {
/** Auto-generated or caller-provided HTML id. Set on the control. */
  id: string;
  /** Space-separated list of message ids; assign to `aria-describedby`. */
  describedBy: string | undefined;
  /**
   * Whether the field is in an error state. Assign as `aria-invalid={invalid || undefined}`:
   * a plain `false` renders `aria-invalid="false"` on every valid control.
   */
  invalid: boolean;
  /** Mirrors {@link FormFieldProps.required}. */
  required: boolean;
  /** Mirrors {@link FormFieldProps.disabled}. */
  disabled: boolean;
}
```

```ts
type SlotNames = keyof ReturnType<T> & string
```

### Slots (slotClasses keys)
`wrapper`, `label`, `requiredMark`, `message`, `helper`