# CheckboxCard: API

## API корня

| Проп | Тип | По умолчанию | Обязательный | Описание |
| --- | --- | --- | --- | --- |
| `orientation` | `CheckboxCardOrientation` | `'vertical'` | Нет | Определяет направление раскладки содержимого карточки. |
| `variant` | `CheckboxVariant` | `'primary'` | Нет | Вариант, управляющий визуальным стилем карточки-чекбокса. Обычно используется для переключения между брендовой и нейтральной темами. |
| `size` | `CardSize` | `'md'` | Нет | Задаёт размер карточки. Влияет на отступы, размер шрифта и, возможно, поведение раскладки. |
| `ref` | `Ref<HTMLElement>` | — | Нет | Ref, передаваемый на корневой элемент карточки (`<article>` или дочерний элемент при `asChild`). Полезен для измерений DOM, прокрутки или императивной логики. |
| `asChild` | `boolean` | — | Нет | Если true, рендерит триггер как дочерний элемент через `Slot`. Это позволяет собственным обёрткам (например, `<a>`, `<div>`) наследовать поведение. |

Также принимает все HTML-атрибуты.

## API дочерних частей

## `CheckboxCardContent`

Основная обёртка содержимого для заголовка и описания.

Также принимает все атрибуты `<div>`.

## `CheckboxCardTitle`

Короткая основная подпись.

| Проп | Тип | По умолчанию | Обязательный | Описание |
| --- | --- | --- | --- | --- |
| `as` | `HeadingAs` | — | Нет | HTML-тег заголовка для рендера (например, 'h1', 'h2'). Определяет семантическую структуру и уровень для доступности. |
| `size` | `HeadingSize` | — | Нет | Визуальный размер заголовка, независимый от тега `as`. Обычно соответствует типографической шкале дизайн-системы. Принимает значения от 1 (наименьший) до 11 (наибольший). |
| `fontWeight` | `400 \| 500 \| 600 \| 700 \| 900` | — | Нет | Насыщенность шрифта текста заголовка. 400: обычный; 500: средний; 600: полужирный; 700: жирный; 900: сверхжирный |
| `ref` | `Ref<HTMLHeadingElement>` | — | Нет | Ref на нативный HTML-элемент заголовка. Полезен для доступа к DOM или управления фокусом. |

Также принимает все атрибуты `<h1>–<h6>`.

## `CheckboxCardDescription`

Поясняющий текст под заголовком.

| Проп | Тип | По умолчанию | Обязательный | Описание |
| --- | --- | --- | --- | --- |
| `size` | `TextSize` | — | Нет | Визуальный размер текста, обычно соответствует типографической шкале дизайн-системы. |
| `asChild` | `boolean` | — | Нет | Если true, рендерит текст как дочерний компонент через `Slot`. Полезно для совместимости с нативными элементами или другими компонентами. |
| `fontWeight` | `400 \| 500 \| 600 \| 700 \| 900` | — | Нет | Насыщенность шрифта текста. Распространённые значения: 400: обычный; 500: средний; 600: полужирный; 700: жирный; 900: сверхжирный |
| `ref` | `Ref<HTMLSpanElement>` | — | Нет | Ref на нижележащий `<span>` или элемент в слоте. Полезен для измерений, фокуса или работы с DOM. |

Также принимает все атрибуты `<span>`.

## `CheckboxCardControl`

Визуальная область контрола для чекбокса.

| Проп | Тип | По умолчанию | Обязательный | Описание |
| --- | --- | --- | --- | --- |
| `variant` | `CheckboxVariant` | — | Нет | Визуальный вариант чекбокса для переключения темы или контекста. |
| `size` | `CheckboxSize` | — | Нет | Размер чекбокса и его визуального маркера. |
| `ref` | `Ref<HTMLLabelElement>` | — | Нет | Ref на нативный элемент label. |

Также принимает все атрибуты `<label>`.

## `CheckboxCardControlInput`

Нативный чекбокс. Отмеченное состояние задаётся здесь: `checked`, `defaultChecked`, `onChange`, `disabled` и `indeterminate`.

| Проп | Тип | По умолчанию | Обязательный | Описание |
| --- | --- | --- | --- | --- |
| `indeterminate` | `boolean` | — | Нет | Задаёт нативное свойство `indeterminate` поля. Часто используется, когда выбраны только некоторые вложенные элементы. У него нет HTML-атрибута, поэтому оно применяется императивно. |
| `ref` | `Ref<HTMLInputElement>` | — | Нет | Необязательный `ref` даёт прямой доступ к нижележащему элементу `<input type="checkbox">` для сложных сценариев, например управления фокусом или императивной проверки состояния. |

Также принимает все атрибуты `<input>`.

## `CheckboxCardControlCheckedIcon`

Иконка отмеченного состояния.

| Проп | Тип | По умолчанию | Обязательный | Описание |
| --- | --- | --- | --- | --- |
| `size` | `IconSize` | — | Нет | Предопределённый токен размера иконки. Может быть переопределён явными шириной и высотой. |
| `ref` | `Ref<SVGSVGElement>` | — | Нет | Ref на SVG-элемент |
| `strokeWidth` | `number` | — | Нет | Толщина обводки линий и фигур SVG (в px или pt). |
| `children` | `ReactNode` | — | Нет | Содержимое иконки (обязательно). Принимает: иконки из `~/icons`; собственный встроенный SVG; компоненты иконок сторонних библиотек (например, Lucide, Tabler) |

Также принимает все HTML-атрибуты.

## `CheckboxCardControlIndeterminateIcon`

Иконка неопределённого состояния.

| Проп | Тип | По умолчанию | Обязательный | Описание |
| --- | --- | --- | --- | --- |
| `size` | `IconSize` | — | Нет | Предопределённый токен размера иконки. Может быть переопределён явными шириной и высотой. |
| `ref` | `Ref<SVGSVGElement>` | — | Нет | Ref на SVG-элемент |
| `strokeWidth` | `number` | — | Нет | Толщина обводки линий и фигур SVG (в px или pt). |
| `children` | `ReactNode` | — | Нет | Содержимое иконки (обязательно). Принимает: иконки из `~/icons`; собственный встроенный SVG; компоненты иконок сторонних библиотек (например, Lucide, Tabler) |

Также принимает все HTML-атрибуты.

## Хуки

## `useCheckboxCardContext`

Продвинутый хук для собственных обёрток контрола карточки, которым нужны размер или вариант.

## Типы

| Тип | Определение | Примечания |
| --- | --- | --- |
| `CheckboxCardProps` | тип пропсов корня | Расширяет пропсы `Card`. |
| `CheckboxCardContentProps` | пропсы содержимого | Пропсы обёртки раскладки. |
| `CheckboxCardTitleProps` | пропсы заголовка | Пропсы текстового заголовка. |
| `CheckboxCardDescriptionProps` | пропсы описания | Пропсы вторичного текста. |
| `CheckboxCardControlProps` | пропсы контрола | Пропсы обёртки контрола. |

## Модель состояния

- Отмеченное состояние живёт на `CheckboxCardControlInput`, как у нативного чекбокса: неконтролируемое через `defaultChecked`, контролируемое через `checked` и `onChange`.
- `indeterminate` на `CheckboxCardControlInput` — визуальное и семантическое смешанное состояние поверх поведения чекбокса.
- Вариант и размер передаются через контекст карточки-чекбокса.

## Заметки по интеграции

- Задайте `CheckboxCardControlInput` атрибут `name`, если важна нативная отправка формы.
- Для групп с выбором одного варианта предпочитайте `Radio` или `SegmentedControl`.
- Оставляйте всю карточку подписанной областью клика, а не сужайте взаимодействие до крошечного контрола.