import { ZodType } from 'zod';
import { StepLabelPropsType } from '@drincs/pixi-vn';
import { q as PixiVNJsonLabelStep, P as PixiVNJsonOperation } from './PixiVNJsonLabelStep-Bce6KGwp.js';
import './PixiVNJsonIfElse-CgOnelja.js';
import '@drincs/pixi-vn/motion';
import 'pixi.js';

/**
 * A handler function invoked for each `[key]` token found in the text that passes the
 * {@link ReplaceHandlerOptions.validation} check.
 *
 * @param key The content found inside the square brackets (without the brackets themselves).
 *   For example, for the token `[john]` the key is `"john"`.
 * @returns The string to substitute in place of `[key]`, or `undefined` to leave the token unchanged.
 */
type ReplaceHandler = (
/**
 * The key to be replaced
 */
key: string) => string | undefined;
/**
 * Configuration options for a text-replacement handler registered via {@link TextReplaces.add}.
 */
type ReplaceHandlerOptions = {
    /**
     * A unique name that identifies this handler.
     * Used for documentation and debugging purposes.
     */
    name: string;
    /**
     * An optional human-readable description of what this handler does.
     * Used for documentation purposes.
     */
    description?: string;
    /**
     * Determines whether this handler should be invoked for a given `[key]` token.
     *
     * - `"all"` – the handler is always invoked for every token found.
     * - `"characterId"` – the handler is invoked only when the key matches a registered character ID
     *   (i.e. the character is present in `RegisteredCharacters`).
     * - `RegExp` – the key string is tested against the regular expression. The handler is invoked
     *   only if the regex matches.
     * - `ZodType<string>` – the key string is validated with `schema.safeParse(key)`. The handler
     *   is invoked only if validation succeeds.
     *
     * @example
     * ```ts
     * // RegExp: only replace keys that look like lowercase identifiers
     * validation: /^[a-z_]+$/
     *
     * // Zod: only replace keys that are one of a fixed set of values
     * import { z } from "zod"
     * validation: z.enum(["player", "npc", "enemy"])
     * ```
     */
    validation: RegExp | "characterId" | "all" | ZodType<string>;
    /**
     * When this handler should be invoked relative to the translation step.
     *
     * - `"before-translation"` – the handler runs **before** {@link onInkTranslate} is called.
     *   Useful for pre-processing tokens, e.g. converting `[key]` into `{{key}}` for i18next.
     * - `"after-translation"` – the handler runs **after** {@link onInkTranslate} is called.
     *   Useful for substituting values that depend on the translated text.
     *
     * @default "after-translation"
     */
    type?: "after-translation" | "before-translation";
    /**
     * When `true`, the **first** occurrence of a matched `[key]` token is converted to the i18n
     * double-brace format `{{[key]}}` (exactly once). Any subsequent occurrences of `[key]` in
     * the same text are then replaced with the handler's return value as usual.
     *
     * The transformation sequence for a matched key is:
     * - first occurrence: `[key]` → `{{[key]}}`
     * - remaining occurrences: `[key]` → handler return value
     *
     * When `false` or omitted, the handler's return value directly replaces all occurrences of `[key]`.
     *
     * **Recommended i18n configuration:** when this option is enabled, configure
     * `missingInterpolationHandler` in your i18n instance so that keys with no matching
     * translation are left intact rather than replaced with an empty string:
     *
     * ```ts title="lib/i18n.ts"
     * i18n.init({
     *     // ...
     *     missingInterpolationHandler(_text, value, _options) {
     *         return value[1];
     *     },
     * });
     * ```
     *
     * @default false
     */
    i18nInterpolation?: boolean;
};

/**
 * Manages text replacement handlers that process content enclosed in square brackets (`[key]`).
 *
 * Handlers are called in the order they were added. For each handler, the current text is scanned
 * for all `[key]` patterns. If the handler's `validation` matches a key, the handler is
 * invoked with that key. If the handler returns a string, all occurrences of `[key]` are replaced
 * with the returned value. After a handler finishes processing the text, the next handler starts
 * on the updated text.
 *
 * Each handler specifies whether it runs before or after translation via the `type` field in its
 * options (defaults to `"after-translation"`).
 *
 * @example
 * ```ts title="content/text-replaces.ts"
 * import { TextReplaces } from 'pixi-vn-ink'
 * import { getCharacterById } from "@drincs/pixi-vn";
 *
 * // Replace [characterId] with the character's display name
 * TextReplaces.add(
 *     (key) => {
 *         const character = getCharacterById(key)
 *         return character?.name
 *     },
 *     {
 *         name: "character-name",
 *         description: "Replaces character IDs with their display names",
 *         validation: /^[a-z_]+$/,
 *         type: "after-translation",
 *     }
 * )
 * // "Hello [john], meet [jane]!" -> "Hello John, meet Jane!"
 * ```
 */
declare namespace TextReplaces {
    /**
     * Configuration options for the `TextReplaces` system.
     */
    const options: {
        /**
         * The regex used to find replacement tokens in the text (e.g. `[key]`).
         * @default /\[([^\]]+)\]/
         */
        replaceRegex: RegExp;
    };
    /**
     * Registers a new replacement handler.
     *
     * Handlers are executed in the order they are added. The first handler added runs first.
     *
     * The {@link TranslatorManager} translation pipeline automatically calls
     * {@link TextReplaces.replace} for both phases (`"before-translation"` and
     * `"after-translation"`), so no additional setup is required after calling `add`.
     *
     * @param fn The handler function. Receives the key found inside `[...]` and should return
     *   the replacement string, or `undefined` to leave that token unchanged.
     * @param handlerOptions Configuration for this handler, including its name, optional
     *   description, validation regex, and execution phase.
     * @example
     * ```ts title="content/text-replaces.ts"
     * import { TextReplaces } from 'pixi-vn-ink'
     *
     * TextReplaces.add(
     *     (key) => key === "player" ? "Mario" : undefined,
     *     {
     *         name: "player-name",
     *         validation: /^player$/,
     *     }
     * )
     * ```
     */
    function add(fn: ReplaceHandler, handlerOptions: ReplaceHandlerOptions): void;
    /**
     * Removes a previously registered handler function.
     *
     * Only the first registration matching `fn` is removed. If the same function was added
     * multiple times, subsequent registrations remain.
     *
     * @param fn The handler function to remove.
     */
    function remove(fn: ReplaceHandler): void;
    /**
     * Returns metadata for all registered handlers, in registration order.
     *
     * @returns An array of {@link ReplaceHandlerOptions} for each registered handler.
     */
    function info(): ReplaceHandlerOptions[];
    /**
     * Applica tutti gli handler registrati del tipo specificato al testo dato.
     *
     * Questa funzione NON esegue più la pre-elaborazione i18n automaticamente.
     * Se vuoi applicare la pre-elaborazione i18n, usa prima {@link runI18nPreStep} sul testo.
     *
     * @param text Il testo sorgente da processare.
     * @param replaceOptions Specifica quale fase di handler eseguire.
     * @returns Il testo dopo che tutti gli handler sono stati applicati.
     *
     * @example
     * // Solo handler di tipo "before-translation"
     * TextReplaces.replace("Ciao [name]", { type: "before-translation" })
     *
     * // Con pre-elaborazione i18n:
     * let t = TextReplaces.runI18nPreStep("Ciao [name]");
     * t = TextReplaces.replace(t, { type: "before-translation" });
     */
    function replace(text: string, replaceOptions: {
        /** Quale fase di handler eseguire. */
        type: "after-translation" | "before-translation";
    }): string;
    /**
     * Esegue la pre-elaborazione i18n su tutti gli handler registrati con `i18nInterpolation: true`.
     *
     * Per ogni handler con questa opzione, la prima occorrenza di ogni `[key]` valida viene sostituita con `{{[key]}}`.
     *
     * @param text Il testo da processare.
     * @returns Il testo dopo la pre-elaborazione i18n.
     *
     * @example
     * // Pre-elabora tutte le variabili i18n:
     * const pre = TextReplaces.runI18nPreStep("Ciao [name]");
     */
    function runI18nPreStep(text: string): string;
}

/**
 * Manages the translation pipeline for all text displayed by pixi-vn-json.
 *
 * The pipeline applies three optional hooks in order:
 * 1. `beforeToTranslate` – pre-processes the key before translation.
 * 2. `translate` – the main translation function (identity by default).
 * 3. `afterToTranslate` – post-processes the translated string.
 *
 * Use {@link TranslatorManager.t} to translate a key or array of keys.
 */
declare namespace TranslatorManager {
    /**
     * @deprecated
     * Optional hook that runs **before** the built-in {@link TextReplaces} before-translation
     * replace pass. Useful for key normalization (e.g. trimming, lowercasing).
     *
     * Prefer {@link TextReplaces.add} with `type: "before-translation"` instead.
     */
    let beforeToTranslate: ((key: string) => string) | undefined;
    /**
     * @deprecated
     * Optional hook that runs **after** the built-in {@link TextReplaces} after-translation
     * replace pass. Useful for post-processing translated strings.
     *
     * Prefer {@link TextReplaces.add} with `type: "after-translation"` instead.
     */
    let afterToTranslate: ((key: string) => string) | undefined;
    /**
     * Translates a single key or an array of keys using the registered pipeline.
     * Returns the same type (`string` or `string[]`) as the input.
     *
     * @param key - The string key or array of string keys to translate.
     * @returns The translated string(s).
     */
    function t<T = string | string[]>(key: T): T;
    /**
     * Runs the composed translation pipeline:
     * 1. optional `beforeToTranslate` hook (deprecated)
     * 2. {@link TextReplaces.replace} – before-translation phase
     * 3. main `translate` function
     * 4. optional `afterToTranslate` hook (deprecated)
     * 5. {@link TextReplaces.replace} – after-translation phase
     */
    function translate(key: string): string;
    /**
     * Sets the main translation function.
     * Defaults to an identity function (returns the key unchanged).
     *
     * @example
     * ```ts
     * setTranslate((key) => i18n.t(key));
     * ```
     */
    function setTranslate(value: (key: string) => string): void;
    /**
     * Generates a JSON translation object from the provided labels.
     * @param labels The labels to translate.
     * @param json The JSON object to populate with translations.
     * @param options Options for translation, including default value handling.
     * @returns The populated JSON object with translations.
     */
    function generateJsonTranslation(labels: PixiVNJsonLabelStep[], json?: object, options?: {
        /**
         * Default value to use when a key is not found.
         * - "empty_string": Use an empty string as the default value.
         * - "copy_key": Use the key itself as the default value.
         * @default "copy_key"
         */
        defaultValue?: "empty_string" | "copy_key";
        operationStringConvert?: (value: string, step: PixiVNJsonLabelStep, props: StepLabelPropsType | {}) => Promise<PixiVNJsonOperation | undefined>;
    }): Promise<object>;
}

export { type ReplaceHandler, type ReplaceHandlerOptions, TextReplaces, TranslatorManager as translator };