/**
 * Locale Resolution Utilities
 *
 * Provides a cascade system for resolving locale/language preferences:
 * 1. Component's explicit `locale` attribute (highest priority)
 * 2. Closest ancestor's `lang` attribute
 * 3. Document root's `lang` attribute
 * 4. Browser's language preference
 * 5. 'en-US' fallback (lowest priority)
 *
 * This allows developers to set locale at any level:
 * - Per-component: <ty-input locale="fr-FR">
 * - Per-section: <div lang="de-DE"><ty-input></ty-input></div>
 * - Per-page: <html lang="es-ES">
 * - Browser default: Uses navigator.language
 *
 * @example
 * ```typescript
 * // In a component
 * class TyInput extends HTMLElement {
 *   get locale(): string {
 *     return getEffectiveLocale(this, this.getAttribute('locale'));
 *   }
 * }
 * ```
 */
/**
 * Get the effective locale for an element using the resolution cascade.
 *
 * Resolution order:
 * 1. Explicit locale attribute on the element
 * 2. Closest ancestor element with a `lang` attribute
 * 3. Document root element's `lang` attribute
 * 4. Browser's navigator.language
 * 5. Fallback to 'en-US'
 *
 * @param element - The element to get locale for
 * @param explicitLocale - Optional explicit locale value (from component's locale attribute)
 * @returns The resolved locale string (e.g., 'en-US', 'fr-FR')
 *
 * @example
 * ```html
 * <html lang="en-US">
 *   <div lang="fr-FR">
 *     <ty-input></ty-input>              <!-- Uses 'fr-FR' -->
 *     <ty-input locale="de-DE"></ty-input>  <!-- Uses 'de-DE' -->
 *   </div>
 *   <ty-input></ty-input>                <!-- Uses 'en-US' -->
 * </html>
 * ```
 */
export declare function getEffectiveLocale(element: HTMLElement, explicitLocale?: string | null): string;
/**
 * Normalize a locale string to BCP 47 format.
 * Handles common variations and ensures consistency.
 *
 * @param locale - The locale string to normalize
 * @returns Normalized locale string
 *
 * @example
 * ```typescript
 * normalizeLocale('en')       // 'en'
 * normalizeLocale('en_US')    // 'en-US'
 * normalizeLocale('EN-us')    // 'en-US'
 * ```
 */
export declare function normalizeLocale(locale: string): string;
/**
 * Check if a locale string is valid BCP 47 format.
 *
 * @param locale - The locale string to validate
 * @returns true if valid, false otherwise
 *
 * @example
 * ```typescript
 * isValidLocale('en-US')    // true
 * isValidLocale('fr')       // true
 * isValidLocale('invalid!') // false
 * ```
 */
export declare function isValidLocale(locale: string): boolean;
/**
 * Get the language code from a locale (e.g., 'en' from 'en-US').
 *
 * @param locale - The locale string
 * @returns The language code
 *
 * @example
 * ```typescript
 * getLanguageCode('en-US')  // 'en'
 * getLanguageCode('fr-FR')  // 'fr'
 * getLanguageCode('de')     // 'de'
 * ```
 */
export declare function getLanguageCode(locale: string): string;
/**
 * Get the region/country code from a locale (e.g., 'US' from 'en-US').
 *
 * @param locale - The locale string
 * @returns The region code, or undefined if not present
 *
 * @example
 * ```typescript
 * getRegionCode('en-US')  // 'US'
 * getRegionCode('fr-FR')  // 'FR'
 * getRegionCode('de')     // undefined
 * ```
 */
export declare function getRegionCode(locale: string): string | undefined;
/**
 * Create a MutationObserver to watch for lang attribute changes.
 * Useful for components that need to react to dynamic locale changes.
 *
 * @param element - The element to observe
 * @param callback - Function to call when lang changes
 * @returns Cleanup function to disconnect the observer
 *
 * @example
 * ```typescript
 * class TyInput extends HTMLElement {
 *   private _localeObserver?: () => void;
 *
 *   connectedCallback() {
 *     this._localeObserver = observeLocaleChanges(this, () => {
 *       this.render(); // Re-render when locale changes
 *     });
 *   }
 *
 *   disconnectedCallback() {
 *     this._localeObserver?.();
 *   }
 * }
 * ```
 */
export declare function observeLocaleChanges(element: HTMLElement, callback: (newLocale: string) => void): () => void;
//# sourceMappingURL=locale.d.ts.map