/**
 * Core types for gonia.
 *
 * @packageDocumentation
 */
import type { ContextKey } from './context-registry.js';
/**
 * Execution mode for the framework.
 */
export declare enum Mode {
    /** Server-side rendering */
    SERVER = "server",
    /** Client-side hydration/runtime */
    CLIENT = "client"
}
declare const __brand: unique symbol;
/**
 * A branded string type for expressions.
 *
 * @remarks
 * This prevents arbitrary strings from being passed as expressions,
 * reducing the risk of eval injection. Only the framework's parser
 * should create Expression values.
 */
export type Expression = string & {
    [__brand]: 'expression';
};
/**
 * Function to evaluate an expression against state.
 */
export type EvalFn = <T = unknown>(expr: Expression) => T;
/**
 * Registry of framework-provided injectables.
 *
 * @remarks
 * For provider contexts, use the second type parameter of `Directive` instead:
 *
 * ```ts
 * const themed: Directive<['$element', 'theme'], {theme: ThemeContext}> = ($el, theme) => {
 *   // theme is typed as ThemeContext
 * };
 * ```
 */
export interface InjectableRegistry {
    /** The expression string from the directive attribute */
    $expr: Expression;
    /** The target DOM element */
    $element: Element;
    /** Function to evaluate expressions against state */
    $eval: EvalFn;
    /** Local reactive state object (isolated per element) */
    $scope: Record<string, unknown>;
    /** Root reactive state object (shared across all elements) */
    $rootState: Record<string, unknown>;
    /** Template registry for g-template directive */
    $templates: {
        get(name: string): Promise<string>;
    };
    /** Current execution mode (server or client) */
    $mode: Mode;
    /** Force fallback rendering from within an async directive (throws FallbackSignal) */
    $fallback: () => never;
}
/**
 * Options for server-side rendering of async directives.
 */
export interface RenderOptions {
    /** Global timeout in ms for async operations (await mode) */
    timeout?: number;
    /** Max nesting depth for await mode (default: 10) */
    maxDepth?: number;
}
/**
 * Extract the value type from a ContextKey.
 */
type ContextKeyValue<K> = K extends ContextKey<infer V> ? V : never;
/**
 * Maps a tuple of injectable names or context keys to their corresponding types.
 *
 * @typeParam K - Tuple of injectable names (strings) or ContextKey objects
 * @typeParam T - Type map (defaults to InjectableRegistry)
 *
 * @example
 * ```ts
 * type Args = MapInjectables<['$element', '$scope']>;
 * // => [Element, Record<string, unknown>]
 *
 * // With typed scope override
 * type Args2 = MapInjectables<['$scope'], { $scope: { count: number } }>;
 * // => [{ count: number }]
 *
 * // With context keys
 * const MyContext = createContextKey<{ value: number }>('MyContext');
 * type Args3 = MapInjectables<['$element', typeof MyContext]>;
 * // => [Element, { value: number }]
 * ```
 */
type MergedRegistry<T> = {
    [K in keyof InjectableRegistry]: K extends keyof T ? T[K] : InjectableRegistry[K];
} & Omit<T, keyof InjectableRegistry>;
export type MapInjectables<K extends readonly (string | ContextKey<unknown>)[], T extends Record<string, unknown> = {}> = {
    [I in keyof K]: K[I] extends ContextKey<unknown> ? ContextKeyValue<K[I]> : K[I] extends keyof MergedRegistry<T> ? MergedRegistry<T>[K[I]] : unknown;
};
/**
 * Evaluation context passed to directives.
 */
export interface Context {
    /** Current execution mode */
    readonly mode: Mode;
    /**
     * Evaluate an expression against the current state.
     *
     * @typeParam T - Expected return type
     * @param expr - The expression to evaluate
     * @returns The evaluated result
     */
    eval<T = unknown>(expr: Expression): T;
    /**
     * Get a value from the context by key.
     *
     * @param key - The key to look up
     * @returns The value, or undefined
     */
    get<T = unknown>(key: string): T | undefined;
    /**
     * Create a child context with additional values.
     *
     * @param additions - Values to add to the child context
     * @returns A new child context
     */
    child(additions: Record<string, unknown>): Context;
}
/**
 * Directive priority levels.
 *
 * @remarks
 * Higher priority directives run first. Structural directives
 * (like g-if, g-for) need to run before behavioral ones.
 */
export declare enum DirectivePriority {
    /** Conditional structural directives (g-if) — runs before iterative ones */
    STRUCTURAL_CONDITIONAL = 1100,
    /** Iterative structural directives (g-for) */
    STRUCTURAL = 1000,
    /** Template/transclusion directives */
    TEMPLATE = 500,
    /** Normal behavioral directives */
    NORMAL = 0
}
/**
 * Static metadata for a directive.
 *
 * @remarks
 * Declared on the directive function before registration.
 * Used to determine processing order and behavior.
 *
 * @typeParam T - Type map for injectable dependencies
 */
export interface DirectiveMeta<T = InjectableRegistry> {
    /**
     * Whether this directive transcludes content.
     *
     * @remarks
     * If true, children are saved before the directive runs.
     */
    transclude?: boolean;
    /**
     * Dependencies to inject into the directive.
     *
     * @remarks
     * Available injectables:
     * - `$expr`: The expression string from the attribute
     * - `$element`: The target DOM element
     * - `$eval`: Function to evaluate expressions: `(expr) => value`
     * - `$scope`: Local reactive state object (isolated per element)
     * - Any registered service names
     * - Any `ContextKey` for typed context resolution
     * - Any names provided by ancestor directives via `$context`
     *
     * @example
     * ```ts
     * myDirective.$inject = ['$element', '$scope'];
     * ```
     *
     * For typed context keys, use the `using` option on directive registration:
     * ```ts
     * directive('my-directive', myDirective, { using: [SlotContentContext] });
     * ```
     */
    $inject?: readonly string[];
    /**
     * Names this directive exposes as context to descendants.
     *
     * @remarks
     * When a directive declares `$context`, its `$scope` becomes
     * available to descendant directives under those names.
     * Useful for passing state through isolate scope boundaries.
     *
     * @example
     * ```ts
     * const themeProvider: Directive = ($scope) => {
     *   $scope.mode = 'dark';
     * };
     * themeProvider.$inject = ['$scope'];
     * themeProvider.$context = ['theme'];
     *
     * // Descendants can inject 'theme'
     * const button: Directive = ($element, theme) => {
     *   console.log(theme.mode);
     * };
     * button.$inject = ['$element', 'theme'];
     * ```
     */
    $context?: string[];
    /**
     * Processing priority. Higher runs first.
     *
     * @defaultValue DirectivePriority.NORMAL
     */
    priority?: number;
}
/**
 * A directive function with typed parameters based on injectable keys.
 *
 * @remarks
 * Use this type annotation to get contextual typing for directive parameters.
 * The tuple of keys maps to parameter types from InjectableRegistry or ContextKey types.
 *
 * @typeParam K - Tuple of injectable key names or ContextKey objects
 * @typeParam T - Optional custom type map to extend InjectableRegistry
 *
 * @example
 * ```ts
 * // Basic usage - $element is typed as Element
 * const myDirective: Directive<['$element']> = ($element) => {
 *   $element.textContent = 'hello';
 * };
 *
 * // Multiple injectables
 * const text: Directive<['$expr', '$element', '$eval']> = ($expr, $element, $eval) => {
 *   $element.textContent = String($eval($expr) ?? '');
 * };
 *
 * // With typed context keys
 * const slot: Directive<['$element', typeof SlotContentContext]> = ($element, content) => {
 *   // content is typed as SlotContent
 *   console.log(content.slots);
 * };
 *
 * // With custom types (extend InjectableRegistry first)
 * declare module 'gonia' {
 *   interface InjectableRegistry {
 *     myService: { doThing(): void };
 *   }
 * }
 * const custom: Directive<['$element', 'myService']> = ($el, svc) => {
 *   svc.doThing();
 * };
 * ```
 */
export type Directive<K extends readonly (string | ContextKey<unknown>)[] = readonly (string & keyof InjectableRegistry)[], T extends Record<string, unknown> = {}> = ((...args: MapInjectables<K, T>) => void | (() => void) | Promise<void | (() => void)>) & DirectiveMeta<T>;
/**
 * Convenience type for directives with a typed scope.
 *
 * @typeParam K - Tuple of injectable names
 * @typeParam S - The scope shape
 *
 * @example
 * ```ts
 * const counter: ScopedDirective<['$element', '$scope'], { count: number }> = ($el, $scope) => {
 *   $scope.count = 0;
 *   $el.addEventListener('click', () => $scope.count++);
 * };
 * ```
 */
export type ScopedDirective<K extends readonly (string | ContextKey<unknown>)[], S extends Record<string, unknown>> = Directive<K, {
    $scope: S;
}>;
/**
 * Attributes passed to template functions.
 */
export interface TemplateAttrs {
    /** The element's innerHTML before transformation */
    children: string;
    /** All attributes from the element */
    [attr: string]: string;
}
/**
 * Template can be a string or a function that receives element attributes and the element.
 */
export type TemplateOption = string | ((attrs: TemplateAttrs, el: Element) => string | Promise<string>);
/**
 * Fallback content shown while an async directive is loading.
 * Same shape as TemplateOption.
 */
export type FallbackOption = string | ((attrs: TemplateAttrs, el: Element) => string | Promise<string>);
/**
 * Options for directive registration.
 */
export interface DirectiveOptions {
    /**
     * Whether to create a new scope for this directive.
     *
     * @remarks
     * When true, the directive creates a new scope that inherits
     * from the parent scope via prototype chain.
     *
     * @defaultValue false
     */
    scope?: boolean;
    /**
     * Template for the directive's content.
     *
     * @remarks
     * Can be a string or a function that receives the element's
     * attributes and children, returning HTML.
     *
     * @example
     * ```ts
     * // Static template
     * directive('my-modal', handler, {
     *   template: '<div class="modal"><slot></slot></div>'
     * });
     *
     * // Dynamic template with props
     * directive('fancy-heading', null, {
     *   template: ({ level, children }) => `<h${level}>${children}</h${level}>`
     * });
     *
     * // Async template (e.g., dynamic import)
     * directive('lazy-component', handler, {
     *   template: () => import('./template.html?raw').then(m => m.default)
     * });
     * ```
     */
    template?: TemplateOption;
    /**
     * DI provider overrides for descendants.
     *
     * @remarks
     * Maps injectable names to values. Descendants requesting these
     * names via `$inject` will receive the provided values instead
     * of global services.
     *
     * Useful for testing (mock services) or scoping services to a subtree.
     *
     * @example
     * ```ts
     * // Test harness with mock services
     * directive('test-harness', null, {
     *   scope: true,
     *   provide: {
     *     '$http': mockHttpClient,
     *     'apiUrl': 'http://localhost:3000/test'
     *   }
     * });
     *
     * // Descendants get mock values
     * directive('api-consumer', ($http, apiUrl) => {
     *   $http.get(apiUrl + '/users');
     * });
     * ```
     */
    provide?: Record<string, unknown>;
    /**
     * Context keys this directive uses.
     *
     * @remarks
     * Declares which contexts the directive depends on. The resolved
     * context values are appended to the directive function parameters
     * in the order they appear in this array.
     *
     * This enables:
     * - Static analysis of context dependencies
     * - Automatic `$inject` generation by the Vite plugin
     * - Type-safe context access without manual `resolveContext` calls
     *
     * @example
     * ```ts
     * const ThemeContext = createContextKey<{ mode: 'light' | 'dark' }>('Theme');
     * const UserContext = createContextKey<{ name: string }>('User');
     *
     * directive('themed-greeting', ($element, $scope, theme, user) => {
     *   // theme and user are resolved from the using array
     *   $element.textContent = `Hello ${user.name}!`;
     *   $element.className = theme.mode;
     * }, {
     *   using: [ThemeContext, UserContext]
     * });
     * ```
     */
    using?: ContextKey<unknown>[];
    /**
     * Fallback content shown while an async directive is loading.
     *
     * @remarks
     * Only meaningful when the directive function is async.
     * Rendered immediately on the server in fallback/stream modes,
     * and on the client while the async function resolves.
     *
     * @example
     * ```ts
     * directive('heavy-widget', async ($scope) => {
     *   const mod = await import('./heavy-widget.js');
     *   mod.setup($scope);
     * }, {
     *   scope: true,
     *   template: '<div class="widget">...</div>',
     *   fallback: '<div class="spinner">Loading...</div>',
     * });
     * ```
     */
    fallback?: FallbackOption;
    /**
     * Server-side rendering mode for async directives.
     *
     * @remarks
     * - `'await'` (default): Run the async fn on the server, wait for it,
     *   render the template. Includes depth and timeout safety.
     * - `'fallback'`: Render fallback immediately on the server without
     *   running the async fn. Client loads and swaps.
     * - `'stream'`: Render fallback with a unique ID, then stream a
     *   replacement `<script>` when the fn resolves.
     *
     * @defaultValue 'await'
     */
    ssr?: 'await' | 'fallback' | 'stream';
    /**
     * Values to assign to the directive's scope.
     *
     * @remarks
     * Requires `scope: true`. Assigns the provided values to the
     * directive's scope, making them available in expressions.
     *
     * Useful for injecting external values (like styles) that should
     * be accessible in templates without manual `$scope` assignment.
     *
     * @example
     * ```ts
     * import styles from './button.css';
     *
     * directive('my-button', handler, {
     *   scope: true,
     *   assign: { $styles: styles }
     * });
     *
     * // In template:
     * // <div g-class="$styles.container">...</div>
     * ```
     */
    assign?: Record<string, unknown>;
    /**
     * Index signature for custom options.
     *
     * @remarks
     * Allows libraries to pass additional options that gonia
     * doesn't process directly. Libraries can create typed
     * wrapper functions around `directive()` for type safety.
     */
    [key: string]: unknown;
}
/** Registered directive with options */
export interface DirectiveRegistration {
    fn: Directive<any> | null;
    options: DirectiveOptions;
}
/**
 * Register a directive by name.
 *
 * @remarks
 * Directives are functions with `$inject` set to declare dependencies.
 * If the name contains a hyphen and scope is true, it's also registered
 * as a custom element.
 *
 * The function can be `null` for pure template directives that have no
 * runtime behavior.
 *
 * @param name - The directive name (e.g., 'g-text' or 'todo-app')
 * @param fn - The directive function, or null for template-only directives
 * @param options - Registration options
 *
 * @example
 * ```ts
 * // Directive with behavior
 * directive('todo-app', ($element, $scope) => {
 *   $scope.todos = [];
 * }, { scope: true });
 *
 * // Template-only directive
 * directive('fancy-heading', null, {
 *   template: ({ level, children }) => `<h${level}>${children}</h${level}>`
 * });
 * ```
 */
export declare function directive(name: string, fn: Directive<any> | null, options?: DirectiveOptions): void;
/**
 * Get a directive registration by name.
 *
 * @param name - The directive name
 * @returns The directive registration (fn and options), or undefined if not found
 */
export declare function getDirective(name: string): DirectiveRegistration | undefined;
/**
 * Get a directive function by name.
 *
 * @param name - The directive name
 * @returns The directive function, null for template-only directives, or undefined if not found
 */
export declare function getDirectiveFn(name: string): Directive<any> | null | undefined;
/**
 * Get all registered directive names.
 *
 * @returns Array of directive names
 */
export declare function getDirectiveNames(): string[];
/**
 * Clear all registered directives.
 *
 * @remarks
 * Primarily useful for testing.
 */
export declare function clearDirectives(): void;
/**
 * Remove a single directive by name.
 *
 * @remarks
 * Primarily useful for testing, to clean up a directive without
 * clearing the entire registry.
 *
 * @param name - The directive attribute name (e.g., 'g-custom')
 */
export declare function removeDirective(name: string): void;
/**
 * Configure options for an existing directive.
 *
 * @remarks
 * Merges the provided options with any existing options for the directive.
 * If the directive hasn't been registered yet, stores the options to be
 * applied when it is registered.
 *
 * This is useful for configuring built-in or third-party directives
 * without needing access to the directive function.
 *
 * @param name - The directive name
 * @param options - Options to merge
 *
 * @example
 * ```ts
 * // Add scope to a built-in directive
 * configureDirective('g-text', { scope: true });
 *
 * // Add template to a custom element
 * configureDirective('app-header', {
 *   template: '<header><slot></slot></header>'
 * });
 * ```
 */
export declare function configureDirective(name: string, options: Partial<DirectiveOptions>): void;
export {};