/**
 * @file Selector.tsx
 * @input Uses React, StyleX, usePopover, useTooltip, Icon, InputGroupContext,
 *   and Selector positioning hooks
 * @output Exports Selector component
 * @position Core implementation; consumed by index.ts
 *
 * SYNC: When modified, update:
 * - /packages/core/src/Selector/Selector.doc.mjs
 * - /packages/core/src/Selector/Selector.test.tsx
 * - /packages/core/src/Selector/index.ts
 * - /apps/storybook/stories/InputGroup.stories.tsx
 * - /packages/cli/assets/templates/blocks/components/Selector/ (showcase blocks)
 */
import React, { type ReactNode } from 'react';
import { type IconType } from '../Icon';
import type { IndicatorPosition } from '../Indicator';
import { type FieldStatusVariant } from '../Field';
import type { LayerPlacement } from '../Layer/useLayer';
import type { SelectorOptionType, SelectorOptionData } from './types';
import type { BaseProps } from '../BaseProps';
import type { SizeValue } from '../utils/types';
export type SelectorSize = 'sm' | 'md' | 'lg';
export type SelectorVariant = 'input' | 'ghost';
export type SelectorStatusType = 'warning' | 'error' | 'success';
export interface SelectorStatus {
    /**
     * The type of status to display.
     */
    type: SelectorStatusType;
    /**
     * Optional message to display below the input.
     */
    message?: string;
}
interface SelectorPropsBase<T extends SelectorOptionType = SelectorOptionType> extends Omit<BaseProps, 'onChange' | 'defaultValue'> {
    /**
     * Label text for the selector (always rendered for accessibility).
     */
    label: string;
    /**
     * Whether to visually hide the label (still accessible to screen readers).
     * @default false
     */
    isLabelHidden?: boolean;
    /**
     * Description text displayed between the label and selector.
     */
    description?: string;
    /**
     * Whether the field is optional. Mutually exclusive with isRequired.
     * @default false
     */
    isOptional?: boolean;
    /**
     * Whether the field is required. Mutually exclusive with isOptional.
     * @default false
     */
    isRequired?: boolean;
    /**
     * Whether the selector is disabled.
     * @default false
     */
    isDisabled?: boolean;
    /**
     * Explains why the selector is disabled. When set together with
     * `isDisabled`, the selector shows a tooltip with this text on hover and
     * keyboard focus, and the trigger stays focusable (via `aria-disabled`)
     * so the reason is discoverable by keyboard and assistive technology.
     * Activation stays blocked.
     *
     * Use this instead of wrapping a disabled selector in `Tooltip` — disabled
     * controls don't emit the pointer events an external tooltip needs.
     *
     * @example
     * ```
     * <Selector
     *   label="Owner"
     *   options={owners}
     *   isDisabled
     *   disabledMessage="You need the Editor role to change this"
     * />
     * ```
     */
    disabledMessage?: string;
    /**
     * The options to display in the selector.
     * Can be strings, objects, dividers, or sections.
     */
    options: T[];
    /**
     * Whether the selector is in a loading state.
     * @default false
     */
    isLoading?: boolean;
    /**
     * Placeholder text when no value is selected.
     * @default 'Select...'
     */
    placeholder?: string;
    /**
     * The size of the selector.
     * - 'sm': Compact size
     * - 'md': Default size
     * @default 'md'
     */
    size?: SelectorSize;
    /**
     * Visual style of the selector trigger.
     * - 'input': bordered input-style trigger for forms
     * - 'ghost': borderless trigger matching ghost buttons, for toolbars
     * @default 'input'
     */
    variant?: SelectorVariant;
    /**
     * Status indicator for the selector.
     * When set, displays a colored border and status icon.
     * If message is provided, displays a message box below the selector.
     */
    status?: SelectorStatus;
    /**
     * How the status message is placed relative to the input.
     * - 'attached': message overlaps directly below the bordered input (input variant only)
     * - 'detached': message floats below as a separate element with spacing
     * - 'tooltip': message is exposed from the on-field status icon
     * @default 'attached' for input selectors; 'detached' for ghost selectors
     */
    statusVariant?: FieldStatusVariant;
    /**
     * Width of the field. Numbers are treated as pixels, strings are used as-is
     * (e.g. `'100%'`). Sizes the whole field (label, control, and status) so they
     * stay aligned, unlike setting width via `xstyle`/`className`/`style`.
     */
    width?: SizeValue;
    /**
     * Tooltip text to display in an info icon at the end of the label.
     */
    labelTooltip?: string;
    /**
     * Icon displayed at the start of the selector trigger. Takes precedence over
     * the selected option's own `icon`, which the trigger otherwise renders.
     */
    startIcon?: ReactNode | IconType;
    /**
     * Custom render function for options.
     * Only called for selectable options (not dividers/sections).
     */
    renderOption?: (option: SelectorOptionData) => ReactNode;
    /**
     * Custom render function for the selected option inside the closed trigger.
     * Only called when something is selected; the placeholder is unaffected.
     *
     * Passing this does not change the trigger's height — what it draws does. A
     * one-line value measures exactly the `size` token, so the control still
     * lines up with the Buttons and inputs beside it; each further line of
     * content adds one text line. Inside an `InputGroup` the group owns the row
     * height: the trigger clamps its value box to that row, so a `SelectorOption`
     * folds onto one line and ellipsizes, and anything taller than the row is cut
     * off at it rather than bleeding over the rows above and below.
     *
     * @example
     * ```
     * renderValue={option => (
     *   <SelectorOption
     *     icon={option.icon}
     *     label={option.label}
     *     description={option.description}
     *   />
     * )}
     * ```
     */
    renderValue?: (option: SelectorOptionData) => ReactNode;
    /**
     * Which edge of the option row carries the selected mark. `start` reserves a
     * mark column ahead of every label so they stay aligned, the way a native
     * menu does; `end` is the house convention shared with Typeahead and
     * CommandPalette.
     *
     * @default 'end'
     */
    indicatorPosition?: IndicatorPosition;
    /**
     * Whether to show a search input for filtering options.
     * @default false
     */
    hasSearch?: boolean;
    /**
     * Placeholder text for the search input.
     * @default 'Search...'
     */
    searchPlaceholder?: string;
    /**
     * Position placement relative to the trigger.
     *
     * Omit to use the selector's default selected-item overlay behavior: the
     * selected item is positioned over the trigger and clamped to the viewport.
     * Set a placement to opt into explicit layer positioning (for example,
     * `placement="above"` for bottom-fixed toolbars).
     */
    placement?: LayerPlacement;
    /**
     * Whether the dropdown starts open on mount.
     * Useful for showcases and previews.
     * @default false
     */
    isDefaultOpen?: boolean;
    /**
     * The HTML name attribute for form submissions. When set, a hidden input
     * carries the selected value under this name, matching how a native
     * select serializes.
     */
    htmlName?: string;
    /**
     * Test ID for testing frameworks.
     */
    'data-testid'?: string;
}
/**
 * Without `hasClear`, the selector always has a string value (or undefined for placeholder).
 * With `hasClear`, the value can be `null` and onChange receives `null` on clear.
 */
type SelectorPropsNonClearable<T extends SelectorOptionType = SelectorOptionType> = SelectorPropsBase<T> & {
    hasClear?: false;
    value?: string;
    onChange?: (value: string) => void;
    changeAction?: (value: string) => void | Promise<void>;
};
type SelectorPropsClearable<T extends SelectorOptionType = SelectorOptionType> = SelectorPropsBase<T> & {
    /**
     * Whether to show a clear button when a value is selected.
     * When clicked, resets the value to `null` and returns focus to the trigger.
     *
     * When enabled, `value` and `onChange` widen to include `null`.
     */
    hasClear: true;
    value: string | null;
    onChange?: (value: string | null) => void;
    changeAction?: (value: string | null) => void | Promise<void>;
};
export type SelectorProps<T extends SelectorOptionType = SelectorOptionType> = SelectorPropsNonClearable<T> | SelectorPropsClearable<T>;
/**
 * A selector/dropdown component for choosing from a list of options.
 *
 * @example
 * ```
 * <Selector
 *   label="Fruit"
 *   options={['Apple', 'Banana', 'Orange']}
 *   value={fruit}
 *   onChange={setFruit}
 *   placeholder="Select a fruit..."
 * />
 * ```
 */
export declare function Selector<T extends SelectorOptionType>(props: SelectorProps<T>): React.JSX.Element;
export declare namespace Selector {
    var displayName: string;
}
export {};
//# sourceMappingURL=Selector.d.ts.map