import { FC } from 'preact/compat';
import { FunctionComponent } from 'preact';
import { IdVerificationConfig } from '@incodetech/core/id-verification';
import { IdVerificationManager } from '@incodetech/core/id-verification';
import { SVGProps } from 'preact/compat';

/**
 * Allowlisted keys for overridable Lottie animations
 */
declare type AnimationKey = 'id.tutorial.front' | 'id.tutorial.back' | 'id.tutorial.passport' | 'id.flip' | 'id.processing' | 'selfie.tutorial' | 'loader.spinner';

/**
 * A customer-supplied replacement for a built-in Lottie animation.
 *
 * - `LottieAnimationData` — a parsed Lottie JSON object.
 * - `{ url }` — fetched and cached at runtime.
 * - `{ animationData }` — explicit object form.
 */
declare type AnimationOverride = LottieAnimationData | {
    url: string;
} | {
    animationData: LottieAnimationData;
};

declare type AnimationOverrides = Partial<Record<AnimationKey, AnimationOverride>>;

/**
 * Allowlisted keys for overridable branded SVG illustrations
 */
declare type AssetKey = 'faceMatch.success' | 'faceMatch.fail' | 'documentCapture.tutorial' | 'id.uploadScreen' | 'id.ageVerification.dob' | 'id.ageVerification.scan' | 'id.ageVerification.privacy' | 'videoSelfie.success' | 'videoSelfie.fail' | 'videoSelfie.tutorial.permission' | 'videoSelfie.tutorial.selfie' | 'videoSelfie.tutorial.frontId' | 'videoSelfie.tutorial.backId' | 'videoSelfie.tutorial.poa' | 'videoSelfie.tutorial.questions' | 'videoSelfie.tutorial.speech' | 'loader.spinner';

/**
 * A customer-supplied replacement for a built-in SVG illustration.
 *
 * - `string` — a URL, or raw `<svg …>` markup (detected by a leading `<`).
 * - `{ url }` — fetched and rendered via `<img>`; no script execution.
 * - `{ raw }` — inline markup; sanitized before injection.
 * - `{ svg }` — a precompiled component, for build-time integrations.
 */
declare type AssetOverride = string | {
    url: string;
} | {
    raw: string;
} | {
    svg: SvgComponent;
};

declare type AssetOverrides = Partial<Record<AssetKey, AssetOverride>>;

/**
 * A module `config` intersected with the per-instance override maps. Typed at
 * the UI boundary so core config types (e.g. `IdCaptureConfig`) stay untouched;
 * `FlowConfig` also declares the maps directly.
 */
declare type ConfigWithOverrides<TConfig> = TConfig & InstanceOverrides;

export declare const IdVerification: FC<IdVerificationProps>;

declare type IdVerificationProps = IncodeModuleProps<IdVerificationConfig, void, IdVerificationManager>;

/**
 * Extra context passed to `onFinish` alongside the result. Lets a host decide
 * how to react to the terminal state without inspecting the DOM. Only the
 * workflow module sets these fields today.
 */
declare type IncodeFinishMeta = {
    /**
     * True when the SDK owns the terminal screen — it has already rendered its
     * own finish UI (today, the workflow's `showFinishScreenBySessionStatus`
     * screen), so the host should not render its own completion screen on top.
     * `onFinish` still fires so the host can run side effects (e.g. notify an
     * OAuth parent).
     *
     * Advisory only: the SDK cannot stop a host from rendering. This works solely
     * because the host reads this flag — a host that ignores it will still
     * replace the SDK screen. Not a guarantee.
     */
    sdkOwnsTerminalScreen?: boolean;
};

declare type IncodeModuleProps<TConfig, TResult = void, TManager = unknown, TConfigInput = ConfigWithOverrides<TConfig>> = {
    /**
     * Module configuration required to render the flow.
     * For Web Components, this is typically assigned via `element.config = ...`.
     *
     * Also carries optional per-instance `assets`/`animations` override maps;
     * they override the global `setup({ uiConfig })` values for this
     * element only and are ignored by the core manager.
     */
    config?: TConfigInput;
    /**
     * Optional pre-built manager. When provided, the module does not create or manage the manager lifecycle.
     */
    manager?: TManager;
    /**
     * Callback invoked when the module completes successfully.
     * @param result - Optional result data from the module completion
     * @param meta - Optional context about how the module resolved (e.g. whether
     *   the SDK rendered its own terminal finish screen). See {@link IncodeFinishMeta}.
     */
    onFinish?: (result?: TResult, meta?: IncodeFinishMeta) => void;
    /**
     * Callback invoked when a fatal module error occurs.
     *
     * @param error - Human-readable error message.
     * @param errorCode - Optional numeric code (e.g. HTTP status). Populated by
     *   the workflow and flow modules on QR validation failures —
     *   `4026` (`expiredUUID`), `4081` (`invalidQRuuid`) or `4083` (`onboardingUrlAlreadyUsed`).
     * @param moduleErrorCode - Optional machine-readable error code (e.g. a
     *   `FaceErrorCode` such as `NONEXISTENT_CUSTOMER`). Lets an orchestrator
     *   branch on the specific terminal error without parsing the message string.
     */
    onError?: (error: string | undefined, errorCode?: number, moduleErrorCode?: string) => void;
};

/**
 * Per-instance overrides for a single mounted SDK module.
 *
 * These ride on the module's `config` prop and are published once at the
 * module root by `registerIncodeModuleElement`, so a deep `<Asset>`/`<AnimatedAsset>`
 * or `<TransitionSpinner>` reads them via {@link useInstanceOverrides} without
 * any prop drilling.
 */
declare type InstanceOverrides = {
    assets?: AssetOverrides;
    animations?: AnimationOverrides;
    spinner?: SpinnerPresentation;
};

declare type LottieAnimationData = {
    fr: number;
    v: string;
    ip: number;
    op: number;
    w: number;
    h: number;
};

/**
 * Host-facing loader presentation, settable globally via
 * `setup({ uiConfig: { spinner } })` or per element via `config.spinner`.
 *
 * Copy is deliberately absent. Loader text comes from i18n (`loadingCircle.*`),
 * which keeps it localizable — a literal string here would freeze in whatever
 * language the host typed it in when the user switches language mid-flow — and
 * leaves one source of truth for user-facing strings.
 */
declare type SpinnerPresentation = {
    renderMode?: SpinnerRenderMode;
    size?: SpinnerSize;
};

/**
 * Which parts of a loader render.
 *
 * An enum rather than a pair of booleans so the meaningless fourth state —
 * neither icon nor text, i.e. a blank screen — is unrepresentable.
 */
declare type SpinnerRenderMode = 'spinnerAndText' | 'spinnerOnly' | 'textOnly';

declare type SpinnerSize = 'small' | 'medium' | 'large';

/** An SVG imported as a Preact component (the `?react` import shape). */
declare type SvgComponent = FunctionComponent<SVGProps<SVGSVGElement>>;

export { }

declare global {
    interface HTMLElementTagNameMap {
        'incode-id-verification': HTMLElement & IncodeModuleProps<IdVerificationConfig,
  void,
  IdVerificationManager>;
    }
}