/**
 * @file ComplexSelector.tsx
 * @input Uses React, StyleX, Field, Icon slots, Layer positioning, and usePopover
 * @output Exports a rich-selector shell with exact token-sized input and ghost triggers, plus an imperative open/close handle
 * @position Core implementation; consumed by index.ts
 *
 * SYNC: When modified, update:
 * - /packages/core/src/ComplexSelector/ComplexSelector.doc.mjs
 * - /packages/core/src/ComplexSelector/ComplexSelector.test.tsx
 * - /packages/core/src/ComplexSelector/index.ts
 * - /apps/storybook/stories/ComplexSelector.stories.tsx
 * - /packages/cli/assets/templates/blocks/components/ComplexSelector/ (showcase blocks)
 */
import React, { type ReactNode } from 'react';
import type { StyleXStyles } from '@stylexjs/stylex';
import type { BaseProps } from '../BaseProps';
import { type FieldStatusVariant } from '../Field';
import { type IconType } from '../Icon';
import type { LayerAlignment, LayerPlacement } from '../Layer/useLayer';
import type { SizeValue } from '../utils/types';
export type ComplexSelectorVariant = 'input' | 'ghost';
export type ComplexSelectorSize = 'sm' | 'md' | 'lg';
export interface ComplexSelectorRenderState {
    /** Whether the selector surface is open. */
    isOpen: boolean;
    /** Whether changeAction/isLoading is pending. */
    isBusy: boolean;
    /** ID of the trigger button. */
    triggerId: string;
    /** ID of the popup content container. */
    contentId: string;
}
/**
 * Imperative control surface for ComplexSelector, accessed via the `handleRef`
 * prop. Methods drive the same popover machinery as the built-in trigger, so
 * they respect focus restoration, light dismiss, and Escape. Prefer these
 * callbacks over mirroring open state in the parent — the selector owns its
 * visibility, and imperative calls avoid the focus-management pitfalls of
 * syncing an external `isOpen` prop.
 */
export interface ComplexSelectorHandle {
    /** Open the selector surface. No-op when disabled or already open. */
    open(): void;
    /** Close the selector surface. Restores focus to the trigger. */
    close(): void;
    /** Toggle the selector surface open or closed. */
    toggle(): void;
    /** Whether the selector surface is currently open. Reads live state. */
    isOpen(): boolean;
}
export interface ComplexSelectorStatus {
    type: 'warning' | 'error' | 'success';
    message?: string;
}
export interface ComplexSelectorProps<Value> extends Omit<BaseProps<HTMLDivElement>, 'children' | 'onChange'> {
    /** Label text for accessibility and the field label. */
    label: string;
    /** Current controlled value. */
    value: Value;
    /** Called when custom content commits a new value. */
    onChange?: (value: Value) => void;
    /** Optional async action after onChange; drives optimistic UI. */
    changeAction?: (value: Value) => void | Promise<void>;
    /** Custom selector surface content rendered inside a dialog popover. */
    children: (value: Value, onChange: (value: Value) => void, close: () => void, state: ComplexSelectorRenderState) => ReactNode;
    /** Label/content shown in the closed trigger. */
    triggerLabel?: ReactNode;
    /** Placeholder shown when triggerLabel is omitted. */
    placeholder?: ReactNode;
    /** Whether to visually hide the field label. */
    isLabelHidden?: boolean;
    /** Helper text displayed below the label. */
    description?: string;
    /** Marks the field optional. */
    isOptional?: boolean;
    /** Marks the field required. */
    isRequired?: boolean;
    /** Disables the selector. */
    isDisabled?: boolean;
    /** Shows loading state on the trigger. */
    isLoading?: boolean;
    /** Validation status. */
    status?: ComplexSelectorStatus;
    /** Status placement. */
    statusVariant?: FieldStatusVariant;
    /** Tooltip text displayed next to the label. */
    labelTooltip?: string;
    /** Trigger and field size. */
    size?: ComplexSelectorSize;
    /** Visual trigger style. Ghost matches toolbar buttons. */
    variant?: ComplexSelectorVariant;
    /** Icon displayed at the start of the trigger. */
    startIcon?: ReactNode | IconType;
    /** Width of the field. */
    width?: SizeValue;
    /** Popup placement. */
    placement?: LayerPlacement;
    /** Popup alignment along the placement axis. */
    alignment?: LayerAlignment;
    /**
     * Imperative handle for programmatic open/close control. Exposes open,
     * close, toggle, and the isOpen query. Use this instead of mirroring open
     * state in the parent — the selector owns its visibility.
     */
    handleRef?: React.Ref<ComplexSelectorHandle>;
    /** StyleX styles for the popup content container. */
    contentXstyle?: StyleXStyles;
    /** Test ID for the trigger container. */
    'data-testid'?: string;
}
/**
 * A selector shell for rich, custom selection surfaces.
 *
 * ComplexSelector owns the field, trigger, popover, focus restore, and async
 * change action flow. Consumers provide the dialog content as a render function,
 * using the supplied `value`, `onChange`, and `close` helpers to compose the
 * right accessible structure for the custom selector.
 *
 * @example
 * ```
 * <ComplexSelector
 *   label="Fruit"
 *   value={value}
 *   onChange={setValue}
 *   triggerLabel={`${value.fruit} ${value.ripeness}`}>
 *   {(value, onChange, close) => (
 *     <FruitGrid
 *       value={value}
 *       onChange={nextValue => {
 *         onChange(nextValue);
 *         close();
 *       }}
 *     />
 *   )}
 * </ComplexSelector>
 * ```
 */
export declare function ComplexSelector<Value>({ label, value, onChange, changeAction, children, triggerLabel, placeholder: placeholderFromProps, isLabelHidden, description, isOptional, isRequired, isDisabled, isLoading, status, statusVariant, labelTooltip, size, variant, startIcon, width, placement, alignment, handleRef, contentXstyle, xstyle, className, style, 'data-testid': testId, onClick: onClickProp, ...props }: ComplexSelectorProps<Value>): React.JSX.Element;
export declare namespace ComplexSelector {
    var displayName: string;
}
//# sourceMappingURL=ComplexSelector.d.ts.map