/**
 * Type-safe context registry for sharing data across DOM ancestors/descendants.
 *
 * @remarks
 * Provides a unified system for registering and resolving typed context values
 * on DOM elements. Similar to React's Context or Vue's provide/inject but with
 * full type safety through branded context keys.
 *
 * @packageDocumentation
 */
/**
 * A branded context key that provides type safety for context values.
 *
 * @typeParam T - The type of value this context holds
 *
 * @remarks
 * The `__type` property is a phantom type - it doesn't exist at runtime
 * but provides compile-time type checking when registering and resolving.
 */
export interface ContextKey<T> {
    /** Unique identifier for this context */
    readonly id: symbol;
    /** Debug name for error messages */
    readonly name: string;
    /** Phantom type for TypeScript inference */
    readonly __type?: T;
}
/**
 * Create a typed context key.
 *
 * @typeParam T - The type of value this context will hold
 * @param name - Debug name for the context (used in error messages)
 * @returns A unique context key
 *
 * @example
 * ```ts
 * interface UserData {
 *   name: string;
 *   email: string;
 * }
 *
 * const UserContext = createContextKey<UserData>('User');
 *
 * // Register on an element
 * registerContext(el, UserContext, { name: 'Alice', email: 'alice@example.com' });
 *
 * // Resolve from a descendant - fully typed!
 * const user = resolveContext(childEl, UserContext);
 * // user is UserData | undefined
 * ```
 */
export declare function createContextKey<T>(name: string): ContextKey<T>;
/**
 * Register a context value on an element.
 *
 * @typeParam T - The context value type (inferred from key)
 * @param el - The element to register the context on
 * @param key - The context key
 * @param value - The value to store
 *
 * @remarks
 * Descendants can resolve this context using `resolveContext`.
 * If a context with the same key is already registered on this element,
 * it will be overwritten.
 *
 * @example
 * ```ts
 * const ThemeContext = createContextKey<{ mode: 'light' | 'dark' }>('Theme');
 *
 * registerContext(rootEl, ThemeContext, { mode: 'dark' });
 * ```
 */
export declare function registerContext<T>(el: Element, key: ContextKey<T>, value: T): void;
/**
 * Resolve a context value from an ancestor element.
 *
 * @typeParam T - The context value type (inferred from key)
 * @param el - The element to start searching from
 * @param key - The context key to look for
 * @param includeSelf - Whether to check the element itself (default: false)
 * @returns The context value, or undefined if not found
 *
 * @remarks
 * Walks up the DOM tree from the element's parent (or the element itself
 * if `includeSelf` is true), looking for an ancestor with the specified
 * context registered.
 *
 * @example
 * ```ts
 * const ThemeContext = createContextKey<{ mode: 'light' | 'dark' }>('Theme');
 *
 * // Somewhere up the tree, ThemeContext was registered
 * const theme = resolveContext(el, ThemeContext);
 * if (theme) {
 *   console.log(theme.mode); // 'light' or 'dark'
 * }
 * ```
 */
export declare function resolveContext<T>(el: Element, key: ContextKey<T>, includeSelf?: boolean): T | undefined;
/**
 * Resolve a context value, throwing if not found.
 *
 * @param el - The element to start searching from
 * @param key - The context key to look for
 * @param includeSelf - Whether to check `el` itself before walking ancestors
 * @returns The context value
 * @throws Error if the context is not found on any ancestor
 */
export declare function requireContext<T>(el: Element, key: ContextKey<T>, includeSelf?: boolean): T;
/**
 * Check if a context is registered on an element.
 *
 * @param el - The element to check
 * @param key - The context key
 * @returns True if the context is registered on this specific element
 *
 * @remarks
 * This only checks the element itself, not ancestors.
 * Use `resolveContext` to search up the tree.
 */
export declare function hasContext<T>(el: Element, key: ContextKey<T>): boolean;
/**
 * Remove a context from an element.
 *
 * @param el - The element to remove the context from
 * @param key - The context key to remove
 *
 * @remarks
 * Does nothing if the context wasn't registered.
 */
export declare function removeContext<T>(el: Element, key: ContextKey<T>): void;
/**
 * Clear all contexts from an element.
 *
 * @param el - The element to clear
 *
 * @remarks
 * Called during element cleanup/removal.
 */
export declare function clearContexts(el: Element): void;