import { type HTMLAttributes } from 'react';
import { type VariantProps } from 'class-variance-authority';
import { type Locale } from '../../i18n/locale-meta';
export declare const LOCALE_STORAGE_KEY = "alfadocs-ui.locale";
/**
 * Sentinel value (and Combobox-row key) for "follow the browser /
 * OS locale". Mirrors the ThemeToggle's `'system'` preference: the
 * picker doesn't store a concrete locale code; the runtime resolves
 * to `navigator.language` once per app lifecycle, or when selected.
 */
export declare const LOCALE_SYSTEM_DEFAULT: "system";
export type LocalePreference = Locale | typeof LOCALE_SYSTEM_DEFAULT;
/**
 * Reports a language change: the picked preference, and the concrete locale it
 * applied (the browser's for System default, which is what a site navigates to).
 */
export type LocaleChangeHandler = (next: LocalePreference, resolved: Locale) => void;
/** @internal Simulate a fresh app lifecycle after test components unmount. */
export declare function __resetLocalePreferenceForTests(): void;
/**
 * Calls `onLocaleChange` when a pick changed the language. Picking the language
 * already shown (or System default resolving to it) reports nothing.
 */
export declare function reportLocaleChange(onLocaleChange: LocaleChangeHandler | undefined, next: LocalePreference, previous: Locale): void;
/** Shared persistence for picker selections and HeaderSettings agent actions. */
export declare function persistLocalePreference(next: LocalePreference): void;
/**
 * Applies storage, optionally HTML lang, then the browser, once per app lifecycle.
 * With `followHtmlLang`, a supported HTML lang comes first, ahead of storage.
 * Every locale surface calls it on mount (the picker, and HeaderSettings,
 * whose search list only mounts when its flyout opens), so the page starts
 * in the right language and direction whichever one the host renders.
 * The first caller whose mount effect runs decides the option for all surfaces.
 * Pass the same option everywhere; later mounts or prop changes do not re-detect.
 */
export declare function useInitialLocale(initialLocaleFromHtmlLang?: boolean, followHtmlLang?: boolean): void;
declare const wrapperVariants: (props?: ({
    variant?: "icon" | "compact" | null | undefined;
} & import("class-variance-authority/types").ClassProp) | undefined) => string;
export type LocalePickerVariant = 'icon' | 'compact';
export interface LocalePickerProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'>, VariantProps<typeof wrapperVariants> {
    variant?: LocalePickerVariant;
    /**
     * Controlled escape hatch — when omitted the picker reads/writes
     * `useLocale()` directly so a bare `<LocalePicker />` works with no
     * wiring. Pass both to opt into controlled mode.
     */
    value?: Locale;
    onValueChange?: (next: LocalePreference) => void;
    /** Disable interaction (greys out the trigger). */
    disabled?: boolean;
    /** Mark as busy (kept open / focusable but read-only). */
    loading?: boolean;
    /**
     * With no saved choice, start from the page's HTML lang before falling back
     * to the browser. Defaults to false. The first locale surface's mount effect
     * decides for the app lifecycle; pass the same option to HeaderSettings.
     */
    initialLocaleFromHtmlLang?: boolean;
    /**
     * The page's HTML lang decides the starting locale, ahead of a saved
     * choice. For sites with one address per language, where the address
     * decides. Defaults to false. Pass the same option to HeaderSettings.
     */
    followHtmlLang?: boolean;
    /**
     * Called after the picker (or its agent handle) has applied a selection
     * that changed the language. Uncontrolled mode only: with `onValueChange`
     * it stays silent. A site with one address per language navigates to
     * `resolved` here. Not called for the starting language.
     */
    onLocaleChange?: LocaleChangeHandler;
    /**
     * Side the search popover opens onto, relative to the trigger.
     * Defaults to `bottom` (standard dropdown). Use `end` (inline-end —
     * right in LTR, left in RTL) when nesting the LocalePicker inside
     * another popover/menu so the search surface flies out to the side
     * rather than stacking below.
     */
    popoverSide?: 'top' | 'bottom' | 'start' | 'end';
}
/**
 * Curated imperative handle for agent / external automation. The
 * `setLocale` parameter is widened to `string` (rather than the
 * narrower `Locale`) so untyped agent inputs don't have to thread the
 * `LOCALES_WITH_BUNDLES` constraint at the call site — the
 * implementation validates internally and no-ops on an unsupported
 * tag.
 */
export interface LocalePickerHandle {
    setLocale: (next: string) => void;
    /** Resolved locale tag actually applied to the page (always concrete). */
    getLocale: () => string;
    /**
     * True when the resolved locale came from `navigator.language` rather
     * than HTML or an explicit user choice. Read-back for `set_locale`: the
     * resolved tag alone cannot tell "the user chose English" from
     * "we are following the browser, which happens to be English".
     */
    getIsSystemDefault: () => boolean;
}
export interface LocalePickerSearchListProps {
    /**
     * Active selection. Either a `Locale` code or the
     * `LOCALE_SYSTEM_DEFAULT` sentinel (when the user hasn't made an
     * explicit choice and the kit is following `navigator.language`).
     * Defaults to the shared store.
     */
    value?: LocalePreference;
    /**
     * Fires after a successful selection. Accepts a concrete `Locale`
     * or `LOCALE_SYSTEM_DEFAULT` (when the user picks the "System
     * Default" row at the top of the list).
     *
     * Defaults to the shared setter (delegates to useLocale, persists
     * or clears storage, updates document.dir/lang).
     */
    onValueChange?: (next: LocalePreference) => void;
    /**
     * Called after the shared setter has applied a selection that changed the
     * language (uncontrolled mode only; with `onValueChange` it stays silent).
     * A site with one address per language navigates to `resolved` here.
     */
    onLocaleChange?: LocaleChangeHandler;
    /** Optional id for the search input (axe `aria-labelledby` chain). */
    inputId?: string;
    /** Disable the input + list interactions. */
    disabled?: boolean;
    /** Mark as busy (read-only). */
    loading?: boolean;
    className?: string;
}
export declare const LocalePickerSearchList: import("react").ForwardRefExoticComponent<LocalePickerSearchListProps & import("react").RefAttributes<HTMLDivElement>>;
export declare const LocalePicker: import("react").ForwardRefExoticComponent<LocalePickerProps & import("react").RefAttributes<HTMLDivElement>> & {
    SearchList: import("react").ForwardRefExoticComponent<LocalePickerSearchListProps & import("react").RefAttributes<HTMLDivElement>>;
};
export {};
//# sourceMappingURL=locale-picker.d.ts.map