# Label: Руководства

## Паттерны

### Явная подпись и id поля ввода

Когда использовать:

- подпись и элемент управления рендерятся как отдельные соседние элементы

Заметки по композиции:

- задайте элементу управления стабильный `id`
- свяжите с ним `Label` через `htmlFor`

Компромиссы:

- понятно и явно
- требует управления `id`

```tsx
import { Label, TextField, TextFieldInput } from '@vega-ui/react';
import { useId } from 'react';

export default function FieldLabel() {
  const id = useId();

  return (
    <div style={{ display: 'grid', gap: 'var(--spacing-3)', width: '100%' }}>
      <Label htmlFor={id}>Company name</Label>
      <TextField>
        <TextFieldInput id={id} name='company' autoComplete='organization' />
      </TextField>
    </div>
  );
}
```

### Подпись, оборачивающая контрол

Когда использовать:

- подпись и контрол из одного элемента (`TextArea`, `Radio`) должны образовывать одну цель для клика без работы с id

Заметки по композиции:

- оберните контрол в `Label`; `htmlFor` и `id` не нужны
- не оборачивайте `TextField` (его корень — `<div>`) и `Checkbox`/`Switch` (их корни уже являются `<label>`)

Компромиссы:

- увеличивает область нажатия
- хуже подходит для сложных вложенных раскладок

```tsx
import { Label, Radio, TextArea } from '@vega-ui/react';

export default function WrappingLabel() {
  return (
    <div style={{ display: 'grid', gap: 'var(--spacing-8)', width: '100%' }}>
      <Label style={{ display: 'grid', gap: 'var(--spacing-3)' }}>
        Delivery instructions
        <TextArea name='instructions' rows={3} fullWidth placeholder='Gate code, floor, where to leave the parcel' />
      </Label>
      <div style={{ display: 'grid', gap: 'var(--spacing-3)' }}>
        <Label fontWeight={400} style={{ display: 'flex', alignItems: 'center', gap: 'var(--spacing-4)' }}>
          <Radio name='window' value='morning' defaultChecked />
          Morning, 8:00–12:00
        </Label>
        <Label fontWeight={400} style={{ display: 'flex', alignItems: 'center', gap: 'var(--spacing-4)' }}>
          <Radio name='window' value='evening' />
          Evening, 17:00–21:00
        </Label>
      </div>
    </div>
  );
}
```

### Подпись со вспомогательным текстом

Когда использовать:

- полю нужна видимая подпись и дополнительная подсказка

Заметки по композиции:

- держите саму подпись отдельно от вспомогательного текста
- размещайте вспомогательный текст под элементом управления или рядом с ним

Компромиссы:

- сохраняет понятную семантику
- требует дополнительного текстового элемента для подсказки

```tsx
import { Button, HelperText, Label, TextField, TextFieldInput } from '@vega-ui/react';
import { FormEvent, useId, useState } from 'react';

export default function RequiredFieldError() {
  const id = useId();
  const messageId = `${id}-message`;
  const [taxId, setTaxId] = useState('');
  const [submitted, setSubmitted] = useState(false);
  const invalid = submitted && taxId.trim() === '';

  const onSubmit = (event: FormEvent<HTMLFormElement>) => {
    event.preventDefault();
    setSubmitted(true);
  };

  return (
    <form noValidate onSubmit={onSubmit} style={{ display: 'grid', gap: 'var(--spacing-12)', width: '100%' }}>
      <div style={{ display: 'grid', gap: 'var(--spacing-3)' }}>
        <Label htmlFor={id}>
          VAT number <span aria-hidden style={{ color: 'var(--color-error)' }}>*</span>
        </Label>
        <TextField error={invalid}>
          <TextFieldInput
            id={id}
            name='vat'
            required
            value={taxId}
            aria-invalid={invalid}
            aria-describedby={messageId}
            onChange={(event) => setTaxId(event.currentTarget.value)}
          />
        </TextField>
        <HelperText id={messageId} error={invalid}>
          {invalid ? 'Enter the VAT number to issue tax invoices.' : 'Printed on every invoice, for example DE123456789.'}
        </HelperText>
      </div>
      <Button type='submit' style={{ justifySelf: 'start' }}>Save billing details</Button>
    </form>
  );
}
```

## Сравнение

### Быстрое правило выбора

Используйте `Label` для подписей элементов управления формы. Используйте `Text` или `Heading` для текста, который не является именем поля ввода.

### `Label` или `Text`

Используйте `Label`, когда:

- текст задаёт имя элемента управления формы

Используйте `Text`, когда:

- содержимое — основной текст, вспомогательный текст или статичное содержимое

### `Label` или `Heading`

Используйте `Label`, когда:

- текст задаёт имя одного элемента управления

Используйте `Heading`, когда:

- текст определяет структуру раздела или страницы

### `Label` или `FieldsetLegend`

Используйте `Label`, когда:

- одному полю нужна видимая семантическая подпись

Используйте `FieldsetLegend`, когда:

- группе связанных элементов управления нужна одна общая семантическая подпись

### Выбирайте этот компонент, когда

- одному полю нужна видимая семантическая подпись
- важно нативное поведение клика по подписи
- текст имени должен оставаться тесно связанным с одним элементом управления

### Не выбирайте этот компонент, когда

- содержимое — заголовок или абзац
- нужно подписать целую группу, а не один элемент управления

## Решение проблем

### Клик по подписи не фокусирует элемент управления

#### Симптом

Подпись отображается, но клик по ней не переводит фокус на нужное поле.

#### Вероятная причина

`htmlFor` не совпадает с `id` элемента управления, или элемент управления не обёрнут подписью.

#### Как проверить

- посмотрите отрендеренный атрибут `for`
- убедитесь, что у целевого элемента управления совпадающий `id`

#### Исправление

Используйте совпадающие `htmlFor` и `id` или оберните элемент управления непосредственно в `Label`.

### Подпись выглядит как вспомогательный текст

#### Симптом

Рядом с полем есть текст, но основная подпись визуально слишком слабая или неоднозначная.

#### Вероятная причина

Переопределения типографики сделали подпись похожей на второстепенный текст.

#### Как проверить

- сравните насыщенность и цвет подписи с соседним вспомогательным текстом
- убедитесь, что есть одна очевидная видимая подпись

#### Исправление

Сохраняйте визуальное отличие основной подписи, а второстепенные подсказки вынесите в отдельный вспомогательный текст.

### Одна подпись будто управляет несколькими полями

#### Симптом

Несколько полей выглядят сгруппированными под одной подписью, и поведение клика непоследовательно.

#### Вероятная причина

В одну подпись обёрнуто несколько несвязанных элементов управления.

#### Как проверить

- посмотрите содержимое подписи
- проверьте, нет ли в одной подписи больше одного независимого элемента управления

#### Исправление

Используйте один `Label` на элемент управления или переключитесь на `Fieldset` и `FieldsetLegend` для сгруппированных элементов управления.