import { HTMLAttributes } from 'vue';
/**
 * Selected value shape used by `UiSelect`.
 *
 * - Single-select mode uses a string value.
 * - Multi-select mode uses an array of string values.
 *
 * This type represents an actual selection payload, so it intentionally does
 * not include `undefined`. Optional props such as `modelValue` and
 * `defaultValue` become `undefined` through the optional property itself.
 */
export type UiSelectValue = string | string[];
/**
 * Optional selected value accepted by internal normalization helpers.
 *
 * Use this when code needs to handle the absence of a select value explicitly,
 * for example while forwarding optional `modelValue` or `defaultValue` props
 * to the underlying select primitive.
 */
export type UiSelectOptionalValue = UiSelectValue | undefined;
/**
 * A dropdown select for choosing from a list of options. Use for
 * form fields where users must pick one value from many.
 * @category Form Inputs
 * @useCases dropdown selection, form picker, option list, country selector
 * @keywords select, dropdown, picker, option, choice, combobox, form
 * @related UiDropdownMenu, UiRadioGroup
 */
export type UiSelectProps = {
    /**
     * The controlled value of the select.
     * - In single-select (default): a `string`.
     * - In multi-select (`multiple: true`): a `string[]`.
     */
    modelValue?: UiSelectValue;
    /** The value when initially rendered (uncontrolled). Same shape as `modelValue`. */
    defaultValue?: UiSelectValue;
    /** Whether the select is open by default. */
    defaultOpen?: boolean;
    /** Controlled open state. */
    open?: boolean;
    /** Whether the select is disabled. */
    disabled?: boolean;
    /**
     * Whether the select is required in a form.
     * - Single-select: forwarded to the underlying native select primitive.
     * - Multi-select: enforced via a visually-hidden focusable `<input required>`
     *   that participates in native form validation when no items are selected.
     */
    required?: boolean;
    /**
     * The name for form submission.
     * - Single-select: forwarded to the underlying native select primitive.
     * - Multi-select: rendered as one `<input type="hidden" name="<name>">`
     *   per selected value, mirroring how `<select multiple name="...">`
     *   contributes one form entry per selected option.
     */
    name?: string;
    /** Reading direction. */
    dir?: 'ltr' | 'rtl';
    /**
     * When true, allows selecting multiple items. The dropdown stays open on
     * click and the trigger renders the selected values as a comma-separated
     * list. `modelValue` becomes a `string[]`.
     */
    multiple?: boolean;
};
/**
 * Emits for the UiSelect root component.
 */
export type UiSelectEmits = {
    /**
     * Emitted when the selected value changes.
     * Payload is `string` in single-select and `string[]` in multi-select.
     */
    'update:modelValue': [value: UiSelectValue];
    /** Emitted when the open state changes. */
    'update:open': [value: boolean];
};
/**
 * Props for the UiSelectTrigger component.
 */
export type UiSelectTriggerProps = {
    /** Accessible label for icon-only triggers. */
    ariaLabel?: string;
    /** Whether the trigger is disabled. */
    disabled?: boolean;
};
/**
 * Props for the UiSelectContent component.
 */
export type UiSelectContentProps = {
    /** Additional classes for the floating content. */
    class?: HTMLAttributes['class'];
    /** Preferred side of the trigger. */
    side?: 'top' | 'right' | 'bottom' | 'left';
    /** Distance from the trigger in pixels. */
    sideOffset?: number;
    /** Alignment against the trigger. */
    align?: 'start' | 'center' | 'end';
    /** Positioning mode. */
    position?: 'item-aligned' | 'popper';
};
/**
 * Emits for the UiSelectContent component.
 */
export type UiSelectContentEmits = {
    /** Emitted when the Escape key is pressed. */
    (e: 'escapeKeyDown', event: KeyboardEvent): void;
    /** Emitted when a pointer down event occurs outside the content. */
    (e: 'pointerDownOutside', event: Event): void;
};
/**
 * Props for the UiSelectItem component.
 */
export type UiSelectItemProps = {
    /** Unique value of the item (required). */
    value: string;
    /** Whether the item is disabled. */
    disabled?: boolean;
    /** Text for typeahead purposes. */
    textValue?: string;
};
/**
 * Props for the UiSelectValue component.
 */
export type UiSelectValueProps = {
    /** Placeholder when no value is selected. */
    placeholder?: string;
};
