# Fieldset: Руководства
## Паттерны
### Раздел настроек
Когда использовать:
- экран настроек содержит несколько связанных переключателей
- группа должна восприниматься как одна область настроек
Заметки о композиции:
- делайте `FieldsetLegend` короткой и неизменной
- используйте `FieldsetHeader` для дополнительных пояснений
- рендерите сами переключатели сразу после заголовка
Компромиссы:
- улучшает семантическую группировку и считываемость
- добавляет больше вертикальной структуры, чем свободный список элементов управления
```tsx
import {
Checkbox,
CheckboxCheckedIcon,
CheckboxIndicator,
CheckboxInput,
Fieldset,
FieldsetHeader,
FieldsetLegend,
Text,
} from '@vega-ui/react';
import { useId } from 'react';
const CHANNELS = [
{ value: 'email', label: 'Email', checked: true },
{ value: 'slack', label: 'Slack #billing-alerts', checked: true },
{ value: 'sms', label: 'SMS to the account owner', checked: false },
];
export default function NotificationChannels() {
const id = useId();
return (
);
}
```
### Прозрачная группа в существующей панели
Когда использовать:
- видимый контейнер уже даёт родительская раскладка
- не хватает только семантики группировки
Заметки о композиции:
- переключитесь на `appearance='transparent'`
- сохраняйте legend, даже когда рамка и отступы убраны
Компромиссы:
- сохраняет семантику без дублирования контейнеров
- граница группы зависит от окружающей раскладки
```tsx
import type { CSSProperties } from 'react';
import {
Button,
Dialog,
DialogClose,
DialogContent,
DialogTrigger,
Fieldset,
FieldsetLegend,
Heading,
Icon,
IconButton,
Label,
Switch,
SwitchIndicator,
SwitchInput,
} from '@vega-ui/react';
import { XIcon } from '@vega-ui/icons';
import { useId } from 'react';
const SETTINGS = [
{ name: 'showEmail', label: 'Show my email to teammates', checked: true },
{ name: 'showActivity', label: 'Show when I was last active', checked: false },
{ name: 'searchable', label: 'Let people find me by phone number', checked: false },
];
const rowStyle = { display: 'flex', alignItems: 'center', justifyContent: 'space-between', gap: 'var(--spacing-8)' };
export default function PrivacySettingsInDialog() {
const id = useId();
return (
);
}
```
### Текст валидации для группы
Когда использовать:
- несколько связанных элементов управления нарушают одно бизнес-правило
- ошибка относится к группе, а не к отдельному полю
Заметки о композиции:
- оставляйте legend неизменным названием группы
- поместите сообщение сразу после legend и укажите его в `aria-describedby` у fieldset
- дочерние элементы при необходимости по-прежнему могут показывать своё локальное состояние
Компромиссы:
- проясняет валидацию на уровне группы
- может стать шумным, если каждый дочерний элемент повторяет то же сообщение
```tsx
import {
Button,
Checkbox,
CheckboxCheckedIcon,
CheckboxIndicator,
CheckboxInput,
Fieldset,
FieldsetLegend,
HelperText,
} from '@vega-ui/react';
import { FormEvent, useId, useState } from 'react';
const CHANNELS = ['Email', 'Push', 'SMS'];
export default function AtLeastOneChannel() {
const id = useId();
const [selected, setSelected] = useState([]);
const [submitted, setSubmitted] = useState(false);
const invalid = submitted && selected.length === 0;
const toggle = (channel: string) => {
if (selected.includes(channel)) {
setSelected(selected.filter((item) => item !== channel));
return;
}
setSelected([...selected, channel]);
};
const onSubmit = (event: FormEvent) => {
event.preventDefault();
setSubmitted(true);
};
return (
);
}
```
### Заголовок с действием
Когда использовать:
- у группы есть действие для всех её полей, например автозаполнение или сброс
Заметки о композиции:
- держите `FieldsetLegend` первым дочерним элементом, чтобы она давала имя группе
- поместите пояснение и `Button` в `FieldsetHeader`, с `type='button'`, чтобы кнопка не отправляла форму
Компромиссы:
- действие находится рядом с полями, которые оно меняет
- отключённый fieldset отключает и действие
```tsx
import {
Button,
Fieldset,
FieldsetHeader,
FieldsetLegend,
Label,
Text,
TextField,
TextFieldInput,
} from '@vega-ui/react';
import { useId, useState } from 'react';
const BILLING = { street: 'Unter den Linden 21', city: 'Berlin', postalCode: '10117' };
export default function HeaderWithAction() {
const id = useId();
const [address, setAddress] = useState({ street: '', city: '', postalCode: '' });
const change = (field: keyof typeof address, value: string) => {
setAddress({ ...address, [field]: value });
};
return (
);
}
```
## Сравнение
### Быстрое правило выбора
Используйте `Fieldset`, когда нескольким связанным элементам управления нужна одна семантическая подпись группы. Используйте обычный `div` или `Card`, только если группировка чисто визуальная.
### `Fieldset` или `Card`
Используйте `Fieldset`, когда:
- группировка — это семантическая структура формы
Используйте `Card`, когда:
- контейнер нужен только для раскладки или отображения
### `Fieldset` или `Separator`
Используйте `Fieldset`, когда:
- поля относятся к одной именованной группе элементов управления
Используйте `Separator`, когда:
- нужно лишь визуальное разделение
### `Fieldset` или `Heading`
Используйте `FieldsetLegend`, когда:
- текст подписывает одну группу элементов управления
Используйте `Heading`, когда:
- текст — это структура документа или раздела, а не нативная семантика группы
### Выбирайте этот компонент, когда
- несколько элементов формы относятся к одному именованному понятию
- группе нужно нативное поведение `