import {
  Canvas,
  Controls,
  Meta,
  Subtitle,
  Title,
} from '@storybook/addon-docs/blocks'
import * as FieldStories from './Field.stories'
import { LifecycleTag } from '../../docs/components/LifecycleTag'

<Meta of={FieldStories} />

<Title>Field</Title>
<Subtitle>
  Accessibility wrapper that wires a label, helper text, and error message to a
  form control via shared IDs.
</Subtitle>
<LifecycleTag variant="Stable" />
**Component type:** Primitive

<Canvas of={FieldStories.WithEverything} layout="padded" sourceState="shown" />
<Controls of={FieldStories.WithEverything} />

## When to use

Use `Field` to wrap any form control (input, select, textarea, checkbox) that needs a label, helper text, or error message. `Field` generates a shared ID via `React.useId()` and wires `htmlFor`, `aria-describedby`, and `aria-invalid` automatically — no manual ID management needed.

## Import

```tsx
import {
  Field,
  FieldLabel,
  FieldControl,
  FieldHelper,
  FieldError,
} from '@chainlink/blocks'
```

## Anatomy

```tsx
<Field>
  <FieldLabel>Email address</FieldLabel>
  <FieldControl>
    <Input placeholder="you@example.com" />
  </FieldControl>
  <FieldHelper>We'll send a confirmation to this address.</FieldHelper>
  <FieldError>Enter a valid email address.</FieldError>
</Field>
```

## Subcomponents

- `Field`: Root container. Accepts `size` (`default` | `sm` | `xs`) — propagates to all children via context.
- `FieldLabel`: `<label>` automatically linked to the control via `htmlFor`. Use `asChild` when wrapping a Checkbox to suppress the `htmlFor` link and avoid double-activation.
- `FieldControl`: Slot wrapper that injects the field's `id`, `aria-describedby`, and `aria-invalid` into the child control. Wrap any `Input`, `Select`, or `Textarea` with this.
- `FieldHelper`: Helper text below the control. Linked to the control via `aria-describedby`.
- `FieldError`: Error message below the control. Linked via `aria-describedby`. Pass `error` to `FieldControl` to also set `aria-invalid` on the control.

## Examples

### With label

<Canvas of={FieldStories.WithLabel} layout="padded" sourceState="shown" />

### With helper and label

<Canvas
  of={FieldStories.WithHelperAndLabel}
  layout="padded"
  sourceState="shown"
/>

### With error message

<Canvas
  of={FieldStories.WithErrorMessage}
  layout="padded"
  sourceState="shown"
/>

### With checkbox

<Canvas of={FieldStories.WithCheckbox} layout="padded" sourceState="shown" />

### Small size

<Canvas
  of={FieldStories.WithEverythingSmall}
  layout="padded"
  sourceState="shown"
/>

### Small size with label

<Canvas of={FieldStories.SmallWithLabel} layout="padded" sourceState="shown" />

## Related components

- `Input` for the control placed inside `FieldControl`
- `FieldInput` for inputs that also need icons and validation state indicators
- `Select` / `SimpleSelect` as alternative controls inside `FieldControl`