GrSelect

const grSelectConfig: import("@feugene/granum/contract").GranumComponentDescriptor<"GrSelect">;

interface GrSelectConfigurableProps {
    size: GrSelectSize;
    variant: GrSelectVariant;
    underline: GrSelectUnderline;
    clearable: boolean;
    /** Форма рамки — см. `components/shared/controlShape.ts`. */
    shape: GrControlShape;
}

type GrSelectView = 'default' | 'link';

type GrSelectSize = GrComponentSize;

type GrSelectVariant = 'primary' | 'default' | 'muted' | 'danger';

type GrSelectUnderline = 'auto' | 'always' | 'none';

type GrSelectOptionsView = 'native' | 'panel';

type GrSelectState = GrControlState;

type GrSelectOption<TValue extends GrSelectValue = string> = {
    value: TValue;
    label: string;
    disabled?: boolean;
    /**
     * Тон чипа в режиме `tags` — перекрывает `tagTone` для этой опции.
     *
     * Цвет у каждого тега свой — обычная модель (метки, категории, статусы), и
     * без неё потребитель уходил в слот `#value` рисовать выбранное сам, теряя
     * ровно то, что в `tags` сделано правильно: чипы снаружи `role="combobox"`,
     * снятие крестиком, сворачивание в «+N» и клавиатуру.
     */
    tone?: GrChipTone;
    /** Плотная заливка чипа этой опции — перекрывает `tagDark`. */
    dark?: boolean;
};

type GrSelectOptionGroup<TValue extends GrSelectValue = string> = {
    label: string;
    options: GrSelectOption<TValue>[];
};

type GrSelectOptionOrGroup<TValue extends GrSelectValue = string> = GrSelectOption<TValue> | GrSelectOptionGroup<TValue>;

type GrSelectModelValue<TValue extends GrSelectValue = string> = TValue | TValue[];

interface GrSelectProps<TValue extends GrSelectValue = string> {
    /** Выбранное значение (`v-model`); в `multiple` — массив. */
    modelValue: GrSelectModelValue<TValue>;
    /** Список опций. Поддерживает плоский массив опций и группы опций (`{ label, options }`). */
    options?: GrSelectOptionOrGroup<TValue>[];
    /** Выключить поле целиком. Складывается с `disabled` у `GrFormField`. */
    disabled?: boolean;
    /** Только для чтения: значение видно и уходит в форму, но не меняется. */
    readonly?: boolean;
    /** Визуальное и ARIA-состояние ошибки. */
    invalid?: boolean;
    /**
     * Визуальный оттенок рамки: `default | success | warning | danger`. `invalid`
     * сильнее — ошибка перекрывает любую другую подсветку. В `view="link"` рамки
     * нет, и состояние туда не применяется.
     */
    state?: GrSelectState;
    /**
     * Имя поля-идентификатора, когда значения опций — объекты. Без него объекты
     * сравнивались бы по ссылке, и пришедшая снаружи копия с тем же `id` не
     * совпала бы ни с одной опцией.
     */
    valueKey?: string;
    /** Обязательное поле (`aria-required`). */
    required?: boolean;
    /** Доступное имя вне `GrFormField`. */
    ariaLabel?: string;
    /**
     * Форма рамки. `box` — скругление шкалы контролов, как было всегда; `pill` —
     * пилюля, как у `GrSegmented`. В `view="link"` не участвует: у ссылки рамки нет.
     */
    shape?: GrControlShape;
    /**
     * Вид триггера: `default` — поле с рамкой, `link` — строчная ссылка без рамки, как
     * `GrLink`. По умолчанию `default`.
     */
    view?: GrSelectView;
    /** Высота и кегль по шкале контролов. По умолчанию `md`; берётся из `GrConfigProvider`. */
    size?: GrSelectSize;
    /** Placeholder (показывается, когда значение не выбрано). */
    placeholder?: string;
    /** Multiple selection. */
    multiple?: boolean;
    /**
     * Вид чипов выбранных значений в режиме `multiple`. Чип — это `GrBadge`: своя
     * плашка на светлой теме почти не отличалась от фона поля.
     */
    tagTone?: GrBadgeTone;
    /** Плотная заливка чипов в режиме `tags`. Поле `dark` у опции сильнее. */
    tagDark?: boolean;
    /** Размер чипов по шкале `GrBadge`. По умолчанию `sm`. */
    tagSize?: GrBadgeSize;
    /** Скругление чипов: `square`, `semi` или `round`. По умолчанию `round`. */
    tagRadius?: GrBadgeRadius;
    /** Как отображать список опций: нативный `<select>` или кастомная панель. */
    optionsView?: GrSelectOptionsView;
    /** Разрешает ввод/выбор значения, которого нет в `options`. */
    allowCustomValue?: boolean;
    /**
     * Поиск/фильтрация опций по вводу (независимо от `allowCustomValue`). Показывает
     * поле поиска над списком и фильтрует опции. Работает только в `optionsView="panel"`
     * (при `native` панель форсится автоматически).
     */
    filterable?: boolean;
    /** Placeholder поля поиска (`filterable`). i18n: fallback `gr.select.searchPlaceholder`. */
    filterPlaceholder?: string;
    /**
     * Текст поиска как контролируемое значение (`v-model:search`). Без него
     * `loading` был декоративным: набранное пользователем наружу не выходило, и
     * сходить за опциями на сервер было не с чем.
     */
    search?: string;
    /**
     * Состояние загрузки: вместо списка опций панель показывает индикатор загрузки.
     * Полезно для удалённой подгрузки опций. Форсит `optionsView="panel"`.
     */
    loading?: boolean;
    /** Текст индикатора загрузки. i18n: fallback `gr.select.loading`. */
    loadingText?: string;
    /** Текст пустого результата фильтрации. i18n: fallback `gr.select.noResults`. */
    noResultsText?: string;
    /**
     * Режим тегов для `multiple`: выбранные значения показываются как удаляемые
     * chips в триггере (вместо строки «a, b, c»). Форсит `optionsView="panel"`.
     */
    tags?: boolean;
    /** Placeholder для инпута кастомного значения (только в `optionsView="panel"`). i18n-friendly: если не задан — берётся из адаптера перевода (`gr.select.customValuePlaceholder`), иначе — встроенный fallback. */
    customValuePlaceholder?: string;
    /** Максимальная высота панели (только в `optionsView="panel"`). */
    dropdownMaxHeight?: number;
    /**
     * Виртуализация панели: в DOM живёт только окно вокруг вьюпорта. Высоту окна
     * задаёт `dropdownMaxHeight`.
     *
     * Только для `optionsView="panel"`: у нативного `<select>` панели нет вовсе.
     * Несовместим с `view="link"` — там ширина панели равна ширине отрисованной
     * опции и прыгала бы при прокрутке.
     */
    virtual?: boolean;
    /** Закрывать панель после выбора (только в `optionsView="panel"`). */
    closeOnSelect?: boolean;
    /** Сколько chips показать до сворачивания в «+N» (только `tags`). */
    maxTagCount?: number;
    /** Разрешает очистку выбранного значения. */
    clearable?: boolean;
    /** i18n-label для кнопки очистки (`aria-label`). */
    clearLabel?: string;
    /**
     * Цвет/вариант ссылки для `view="link"` (аналогично `GrLink`).
     * В `view="default"` не используется.
     */
    variant?: GrSelectVariant;
    /**
     * Подчёркивание для `view="link"` (аналогично `GrLink`).
     * В `view="default"` не используется.
     */
    underline?: GrSelectUnderline;
    /**
     * Контролируемое состояние панели (`v-model:open`). Без пропа панель ведёт
     * себя сама (uncontrolled), с ним — слушайте `update:open` и меняйте проп.
     * Только для `optionsView="panel"`: у нативного `<select>` панель браузерная.
     */
    open?: boolean;
    /**
     * Имя для нативной формы: в native-режиме уходит на сам `<select>`, в
     * panel-режиме значения сериализуются hidden-инпутами (ключ — `keyOf`).
     */
    name?: string;
    /**
     * Ширины аддонов `prefix`/`suffix` — общий контракт контролов пакета
     * (`docs/form-controls.md`). Аддоны живут в панельном триггере: внутрь
     * нативного `<select>` разметку положить нельзя.
     */
    prefixMinWidth?: string;
    /** Максимальная ширина префикса: содержимое шире обрезается. */
    prefixMaxWidth?: string;
    /** Минимальная ширина суффикса. По умолчанию — по ступени размера. */
    suffixMinWidth?: string;
    /** Максимальная ширина суффикса: содержимое шире обрезается. */
    suffixMaxWidth?: string;
    /** Жёсткая ширина префикса: `prefixMaxWidth`, иначе `prefixMinWidth`, иначе по ступени размера. */
    prefixFixed?: boolean;
    /** Жёсткая ширина суффикса: `suffixMaxWidth`, иначе `suffixMinWidth`, иначе по ступени размера. */
    suffixFixed?: boolean;
}

interface GrSelectEmits<TValue extends GrSelectValue = string> {
    /** Новое значение (`v-model`): выбор опции, снятие чипа или очистка. */
    (e: 'update:modelValue', value: GrSelectModelValue<TValue>): void;
    /** Значение изменилось — тот же payload, что у `update:modelValue`. */
    (e: 'change', value: GrSelectModelValue<TValue>): void;
    /** Значение снято кнопкой очистки. */
    (e: 'clear'): void;
    /** Панель открылась/закрылась (`v-model:open`). */
    (e: 'update:open', value: boolean): void;
    /** Текст поиска как контролируемое значение (`v-model:search`). */
    (e: 'update:search', value: string): void;
    /** Фокус вошёл в контрол. Переход между полем и его панелью событием не считается. */
    (e: 'focus', event: FocusEvent): void;
    /** Фокус ушёл из контрола — из поля и из панели вместе. */
    (e: 'blur', event: FocusEvent): void;
    /** Пользователь набрал запрос — сигнал сходить за опциями. */
    (e: 'search', value: string): void;
}

const grSelectSafelist: string[];

type GrSelectInstance = ComponentExposed<typeof GrSelectComponent>;