import { type StructuredAddress, type RawAddressComponent } from './parse-address';
export type { StructuredAddress, RawAddressComponent };
/**
 * A single address suggestion surfaced in the listbox.
 *
 * `placeId` keys the row and (in real Google mode) is used to fetch full
 * details on selection. In MOCK mode the suggestion carries a pre-parsed
 * `address` so selection resolves without any network call.
 */
export interface AddressSuggestion {
    /** Stable id — the Google place id, or any unique string in mock mode. */
    placeId: string;
    /** Primary line shown in the row (e.g. "Via Roma 12"). */
    primaryText: string;
    /** Secondary line shown muted under the primary (e.g. "Milan, Italy"). */
    secondaryText?: string;
    /**
     * Pre-parsed structured address. Required in MOCK mode (so selection can
     * resolve without Google). In real Google mode this is omitted and the
     * details are fetched on selection.
     */
    address?: StructuredAddress;
}
/**
 * Test/story injector. Given the current query it returns the suggestions
 * to show. Each returned suggestion MUST carry a pre-parsed `address` so
 * selection resolves without a real Google call.
 */
export type GetSuggestions = (query: string) => AddressSuggestion[] | Promise<AddressSuggestion[]>;
export interface AddressAutocompleteHandle {
    /** Current free-text value of the input. */
    getValue: () => string;
    /** Current query (same as the input value) used to drive suggestions. */
    getQuery: () => string;
    /** True when the suggestion listbox is visible. */
    getIsOpen: () => boolean;
    /** Set the input text programmatically (also drives a suggestion fetch). */
    setValue: (value: string) => void;
    /** Set the query text — alias of `setValue`. */
    setQuery: (query: string) => void;
    /** Clear the typed text and dismiss the listbox. */
    clear: () => void;
    /** Open the suggestion listbox. */
    open: () => void;
    /** Close the suggestion listbox. */
    close: () => void;
}
export interface AddressAutocompleteProps {
    /**
     * Google Maps JS API key. Consumer-owned; never cached by the kit. When
     * absent (and no `getSuggestions` injector is given) the field degrades
     * to a plain free-text input with no suggestions.
     */
    apiKey?: string;
    /** Controlled text value of the input. */
    value?: string;
    /** Fires on every keystroke with the new input text. */
    onValueChange?: (value: string) => void;
    /** Uncontrolled initial text. Ignored once `value` is set. */
    defaultValue?: string;
    /**
     * Fires when the user picks a suggestion, with the parsed structured
     * address. In real Google mode the details are fetched first, so this
     * is async relative to the click.
     */
    onSelect?: (address: StructuredAddress) => void;
    /**
     * Test-only / mock injector. When provided, the listbox is driven from
     * its return value instead of a real Google call — even when `apiKey` is
     * also set (the injector wins, so stories/tests are deterministic).
     */
    getSuggestions?: GetSuggestions;
    /**
     * Restrict predictions to these CLDR region codes (e.g. `['it']`).
     * Real-Google mode only.
     */
    regionCodes?: string[];
    /** Visible label is owned by a wrapping FormField; this is a fallback name. */
    'aria-label'?: string;
    /** Placeholder text. Falls back to the translated default. */
    placeholder?: string;
    /** Debounce before firing a suggestion fetch. Default 250ms. */
    debounceMs?: number;
    disabled?: boolean;
    required?: boolean;
    readOnly?: boolean;
    name?: string;
    /** Field id. Falls back to FormField context id. */
    id?: string;
    size?: 'sm' | 'md' | 'lg';
    tone?: 'default' | 'error';
    className?: string;
}
export declare const AddressAutocomplete: import("react").ForwardRefExoticComponent<AddressAutocompleteProps & import("react").RefAttributes<HTMLInputElement>>;
//# sourceMappingURL=address-autocomplete.d.ts.map