PhoneField

PhoneField — составной компонент, который объединяет поле телефона с маской и вложенный Select для кода страны.

API корня

PhoneField владеет полем телефона и моделью форматирования по стране.

Проп	Тип	По умолчанию
`value`	`string`	—
Контролируемый номер телефона в виде текста поля.
`defaultValue`	`string`	`''`
Начальный номер телефона для неконтролируемого использования. По умолчанию `''`. Его страна выбирается, если не задан `code`.
`onChangeValue`	`(value: string) => void`	—
Вызывается с номером телефона при его изменении.
`code`	`CountryCode`	—
Код страны ISO 3166-1 alpha-2, по которому определяется формат маски телефона. Пример: 'US', 'RU', 'FR'.
`defaultCode`	`CountryCode`	`''`
Код страны ISO 3166-1 alpha-2, по которому определяется формат маски телефона. Пример: 'US', 'RU', 'FR'.
`onChangeCode`	`(code: CountryCode) => void`	—
Код страны ISO 3166-1 alpha-2, по которому определяется формат маски телефона. Пример: 'US', 'RU', 'FR'.
`strictMask`	`boolean`	`true`
Если true, маска телефона применяется строго — допускаются только корректные символы на своих позициях.
`size`	`TextFieldSize`	—
Визуальный размер текстового поля. Влияет на отступы, размер шрифта и общую высоту. 'sm': компактное поле; 'md': по умолчанию; 'lg': просторная раскладка
`ref`	`Ref<HTMLDivElement>`	—
Ref, передаваемый на элемент-обёртку. Полезен для программного управления, фокуса или интеграции.
`error`	`boolean`	—
Показывает поле ввода в состоянии ошибки.

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

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

`PhoneFieldInput`

Видимое текстовое поле для номера телефона.

Проп	Тип	По умолчанию
`ref`	`Ref<HTMLInputElement>`	—
Ref, передаваемый на нижележащий нативный элемент `<input>`.

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

`PhoneFieldSelect*`

Вложенное семейство выбора страны, построенное вокруг того же состояния поля.

PhoneFieldSelect
PhoneFieldSelectHiddenSelect
PhoneFieldSelectCombobox
PhoneFieldSelectValue
PhoneFieldSelectIcon
PhoneFieldSelectListbox
PhoneFieldSelectOption

`PhoneFieldSelect`

Проп	Тип	По умолчанию
`size`	`SelectSize`	—
Визуальный размер элемента выбора.
`variant`	`SelectVariant`	—
Вариант визуального стиля элемента выбора.
`disabled`	`boolean`	—
Отключён ли select. Запрещает взаимодействие и применяет стиль отключённого состояния.
`onChangeValue`	`(value: V \| undefined) => void`	—
Колбэк, вызываемый при выборе варианта.
`ref`	`Ref<HTMLDivElement>`	—
Ref на корневой элемент.
`readOnly`	`boolean`	—
Если true, значение select нельзя изменить, но он остаётся фокусируемым.
`typeahead`	`boolean`	`true`
Включает переход к варианту при наборе начала его подписи.
`open`	`boolean`	—
Управляет состоянием открытия выпадающего списка Select. Если задан, Select становится контролируемым компонентом и по этому значению определяет, открыт список или закрыт.
`onChangeOpen`	`(open: boolean) => void`	—
Колбэк, вызываемый при изменении состояния открытия. Вызывается со следующим состоянием открытия (`true` или `false`) каждый раз, когда пользователь открывает или закрывает Select. Полезен для синхронизации состояния Select с внешней логикой.
`defaultOpen`	`boolean`	—
Задаёт начальное состояние открытия Select в неконтролируемом режиме. Применяется только при первом рендере и дальше игнорируется.

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

`PhoneFieldSelectHiddenSelect`

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

`PhoneFieldSelectCombobox`

Проп	Тип	По умолчанию
`ref`	`Ref<HTMLButtonElement>`	—
Ref на нижележащий элемент `<button>`. Полезен для управления фокусом, позиционирования и императивного доступа.

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

`PhoneFieldSelectValue`

Проп	Тип	По умолчанию
`placeholder`	`string`	—
Текст-заполнитель, который показывается, когда не выбран ни один вариант. Отображается, когда значение select пустое или undefined. После выбора значения заполнитель заменяется содержимым выбранного варианта.
`ref`	`Ref<HTMLSpanElement>`	—
Ref, передаваемый на корневой элемент span.

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

`PhoneFieldSelectIcon`

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

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

`PhoneFieldSelectOption`

Проп	Тип	По умолчанию
`value`обязательный	`CountryCode`	—
Значение этого варианта, которое передаётся в колбэк изменения при его выборе.
`label`	`string`	—
Простой текст варианта для поиска при наборе; используется вместо текста его содержимого.
`children`	`ReactNode`	—
Содержимое, отображаемое для этого варианта. Может включать текст, иконки или сложную разметку.
`size`	`OptionSize`	—
Размер варианта для визуальной стилизации.
`disabled`	`boolean`	—
Отключает весь Option.
`ref`	`Ref<HTMLDivElement>`	—
Ref, передаваемый на корневой div варианта.

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

`PhoneFieldSelectListbox`

Проп	Тип	По умолчанию
`ref`	`Ref<HTMLDivElement>`	—
Ref на элемент-контейнер списка. Можно использовать для императивного доступа, например для измерений.

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

Хуки

`usePhoneFieldContext`

Продвинутый хук для собственных обёрток и интеграций.

Типы

Тип	Определение	Примечания
`PhoneFieldProps`	Тип пропсов корня	Основная поверхность интеграции поля.
`PhoneFieldInputProps`	Тип пропсов поля ввода	Поведение ввода номера.
`PhoneFieldSelectProps`	Тип пропсов корня select	Поверхность вложенного выбора страны.

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

Состояние корня согласует страну и форматирование поля.
Строгая и нестрогая маска влияют на терпимость ввода.
Вложенную композицию select всё равно нужно рассматривать как одно семейство поля.

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

Валидируйте и нормализуйте каноническое значение вне слоя представления.
Перепроверяйте вставку и автозаполнение, а не только посимвольный набор.
Держите смену страны и логику валидации синхронизированными.