# Label

Renders accessible labels for native form controls and provides the wrapper-label pattern for checkbox, radio, and switch rows where the entire copy block should toggle the control.

Use `Label` when a lightweight visible label is enough. For richer form-field layouts with descriptions, grouped sections, and generated id wiring, use the `form` entrypoint and `label[FormLabel]` instead.

## Import

```ts
import { LabelComponent } from '@edsis/component/label';
```

## Composition

The label primitive supports three common structures:

```text
Label[for] + native control[id]
label[Label] + native control[id]
label[Label]
├── Checkbox | Radio | Switch
└── descriptive copy
```

For full form-field composition, map the shadcn `Field` guidance to `FormField`, `label[FormLabel]`, and `[FormControl]` from `@edsis/component/form`.

## Basic usage

Use `for` when the target control exposes a stable native `id`, such as an input or textarea.

```html
<div class="grid gap-2">
  <label for="email">Email address</label>
  <input Input id="email" type="email" placeholder="you@example.com" />
</div>
```

You can also decorate a native label host when that fits the surrounding markup more naturally.

```html
<label Label for="email">Email address</label>
<input Input id="email" type="email" placeholder="you@example.com" />
```

## Common patterns

### Checkbox, radio, and switch rows

When the entire row should toggle the control, wrap the control and copy in `label[Label]`. This is the closest Angular equivalent to the upstream shadcn checkbox-plus-label preview.

```html
<label Label class="inline-flex max-w-md items-start gap-3 rounded-xl border border-border p-4">
  <Checkbox class="mt-0.5" />
  <span class="grid gap-1 leading-none">
    <span>Email me product updates</span>
    <span class="text-sm font-normal leading-5 text-muted-foreground">
      Wrap checkbox, radio, and switch rows in label[Label] when the whole row should toggle the
      control.
    </span>
  </span>
</label>
```

### Label in Field

The shadcn docs route richer field composition to `Field`. In this library, use the `form` entrypoint instead.

```html
<FormField class="max-w-md">
  <label FormLabel>Email address</label>
  <input Input FormControl type="email" placeholder="you@example.com" />
  <p FormDescription>We will only use this address for account updates.</p>
</FormField>
```

`label[FormLabel]` automatically targets the generated control id from `[FormControl]`, so helper text and invalid state remain synchronized without manual `for` wiring.

### RTL

The label primitive is direction-agnostic. Apply `dir="rtl"` on a wrapper and reverse the row layout when the label and control should read from right to left.

```html
<div dir="rtl" lang="ar" class="max-w-md text-right">
  <label Label class="flex flex-row-reverse items-start gap-3">
    <Checkbox class="mt-0.5" />
    <span class="grid gap-1 leading-none">
      <span>قبول الشروط والأحكام</span>
      <span class="text-sm font-normal leading-5 text-muted-foreground">
        يظل نمط التسمية نفسه، فقط ضع الصف داخل حاوية تدعم الاتجاه من اليمين إلى اليسار.
      </span>
    </span>
  </label>
</div>
```

## API reference

### `LabelComponent`

| Input   | Type             | Default |
| ------- | ---------------- | ------- |
| `for`   | `string \| null` | `null`  |
| `class` | `string`         | `''`    |

Selectors: `Label`, `label[Label]`

Related mapping: for shadcn `FieldLabel`, use `label[FormLabel]` from `@edsis/component/form`.

## Styling and theming

Base classes: `text-sm font-medium leading-none text-foreground`.

- Pass `class` to tune spacing, layout, or typography for a specific label row.
- `peer-disabled:cursor-not-allowed peer-disabled:opacity-70` dims the label when a peer-marked control is disabled.
- Standard library theme tokens such as `text-foreground`, `text-muted-foreground`, `border-border`, and spacing utilities compose cleanly with the label host.

## Accessibility

- Set `for` only when the target control exposes a real native id.
- Wrap checkbox, radio, and switch rows in `label[Label]` instead of relying on `for` to reach an internal input element.
- Inside `FormField`, prefer `label[FormLabel]` so helper text and invalid state stay synchronized with `[FormControl]`.
- Keep label text specific so screen readers and voice-control software announce useful control names.

## Keyboard interactions

- Labels themselves are not the main keyboard target; focus moves to the associated control in normal tab order.
- Once the control has focus, keyboard behavior belongs to that control, such as `Space` toggling a checkbox.

## Angular notes

- Use `Label` or `label[Label]` for lightweight labeling only.
- Use the `form` entrypoint when the surface also needs descriptions, errors, grouped sections, or generated `for` wiring.
- The checkbox, radio, and switch families work best with wrapper labels because those controls own their internal focusable element.

## Source parity

This Angular slice keeps the shadcn Label guidance around installation, usage, field composition, RTL behavior, and API shape while mapping the upstream `Field` recommendation to the local `form` entrypoint and expressing checkbox-like examples with a wrapper-label pattern that fits the existing Angular primitives.