@ahnseungchan/webviewkit 1.2.0 → 2.0.0

package/dist/index.d.ts

@@ -1,9 +1,451 @@
-export { STACK_TRANSITION_MS } from "./constants";
-export { Direction, HistoryAction } from "./type";
-export type { StackRouterProviderProps, VisiblePage, HistoryState, HistoryListener, DirectionType, } from "./type";
-export { history } from "./history";
-export { default as StackRouterProvider, useStackRouter, } from "./stack-router/stack-router-provider";
-export { default as BackRouter } from "./stack-router/_components/back-router";
-export { default as StackHeader } from "./stack-router/_components/header";
-export { StackDevRoadmap } from "./stack-dev/stack-dev-roadmap";
-//# sourceMappingURL=index.d.ts.map
+import * as _emotion_react_jsx_runtime from '@emotion/react/jsx-runtime';
+import React, { ReactNode } from 'react';
+
+declare const BRIDGE_ERROR_CODES: {
+    readonly TIMEOUT: "TIMEOUT";
+    readonly BRIDGE_UNAVAILABLE: "BRIDGE_UNAVAILABLE";
+    readonly INVALID_PAYLOAD: "INVALID_PAYLOAD";
+    readonly URL_NOT_ALLOWED: "URL_NOT_ALLOWED";
+    readonly UNKNOWN_METHOD: "UNKNOWN_METHOD";
+    readonly HANDLER_ERROR: "HANDLER_ERROR";
+};
+type BridgeErrorCode = (typeof BRIDGE_ERROR_CODES)[keyof typeof BRIDGE_ERROR_CODES];
+declare class BridgeError extends Error {
+    readonly code: BridgeErrorCode | string;
+    constructor(code: BridgeErrorCode | string, message: string, cause?: unknown);
+    toBody(): {
+        code: string;
+        message: string;
+    };
+}
+
+/** WebViewKit native bridge protocol (v1) */
+declare const BRIDGE_PROTOCOL_VERSION: 1;
+declare const BRIDGE_NAMESPACE: "webviewkit";
+type BridgeHostKind = "react-native" | "flutter" | "browser" | "unknown";
+/** Stack navigation — maps to common `stackPush` / `stackPop` WebView handlers */
+declare const STACK_BRIDGE_METHODS: {
+    readonly PUSH: "stack.push";
+    readonly REPLACE: "stack.replace";
+    readonly POP: "stack.pop";
+    readonly RESET: "stack.reset";
+    /** web → native: 웹 스택 깊이 변경 알림 */
+    readonly CHANGED: "stack.changed";
+};
+type StackBridgeMethod = (typeof STACK_BRIDGE_METHODS)[keyof typeof STACK_BRIDGE_METHODS];
+/** native → web: 하드웨어 back. 응답 payload `{ handled }` */
+declare const BACK_REQUEST_METHOD: "back.request";
+/** 요청에 대한 응답 envelope method (`replyTo` 필수) */
+declare const BRIDGE_RESPONSE_METHOD: "bridge.response";
+type StackMeta = Record<string, unknown> | null;
+type StackPushPayload = {
+    url: string;
+    meta?: StackMeta;
+};
+type StackReplacePayload = StackPushPayload;
+type StackResetPayload = {
+    url: string;
+    meta?: StackMeta;
+};
+type StackChangedPayload = {
+    depth: number;
+    path: string;
+};
+type BackRequestResult = {
+    handled: boolean;
+};
+type BridgeErrorBody = {
+    code: BridgeErrorCode | string;
+    message: string;
+};
+type BridgeEnvelope<TPayload = unknown> = {
+    v: typeof BRIDGE_PROTOCOL_VERSION;
+    ns: typeof BRIDGE_NAMESPACE;
+    id: string;
+    method: string;
+    payload?: TPayload;
+    error?: BridgeErrorBody;
+    /** 응답일 때 원 요청 id */
+    replyTo?: string;
+};
+declare function createBridgeId(): string;
+declare function createBridgeEnvelope<TPayload>(method: string, payload?: TPayload, id?: string): BridgeEnvelope<TPayload>;
+declare function createBridgeResponse<TPayload>(request: Pick<BridgeEnvelope, "id">, result: {
+    payload?: TPayload;
+    error?: BridgeErrorBody;
+}): BridgeEnvelope<TPayload>;
+declare function isBridgeEnvelope(value: unknown): value is BridgeEnvelope;
+declare function parseBridgeMessage(raw: string | unknown): BridgeEnvelope | null;
+declare function serializeBridgeMessage(msg: BridgeEnvelope): string;
+/** Flutter InAppWebView legacy handler names */
+declare const FLUTTER_LEGACY_STACK_HANDLERS: {
+    readonly push: "stackPush";
+    readonly replace: "stackReplace";
+    readonly pop: "stackPop";
+    readonly reset: "stackReset";
+};
+/** Unified handler name when native listens on one channel */
+declare const FLUTTER_UNIFIED_HANDLER = "webviewkitBridge";
+/** React Native receives messages via this global handler name suggestion */
+declare const RN_BRIDGE_HANDLER = "webviewkitBridge";
+
+/** flutter_inappwebview 가 JS 브릿지를 붙인 뒤 window 에 dispatch 하는 이벤트 */
+declare const FLUTTER_READY_EVENT = "flutterInAppWebViewPlatformReady";
+declare function detectBridgeHost(): BridgeHostKind;
+declare function isNativeBridgeHost(host: BridgeHostKind): boolean;
+interface WaitForBridgeHostOptions {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+/**
+ * 네이티브 브릿지가 늦게 주입되는 경우(Flutter platformReady 이전)를 기다린다.
+ * 즉시 감지되면 바로, 아니면 ready 이벤트·폴링으로 재감지. 타임아웃·abort 시 현재 판정값.
+ */
+declare function waitForBridgeHost({ timeoutMs, signal, }?: WaitForBridgeHostOptions): Promise<BridgeHostKind>;
+
+type BridgeTransportOptions = {
+    /** Flutter: use stackPush/stackPop handlers (default true) */
+    flutterLegacyHandlers?: boolean;
+};
+interface BridgeTransport {
+    readonly host: BridgeHostKind;
+    /** Flutter 는 callHandler 반환값, RN·browser 는 undefined */
+    send(envelope: BridgeEnvelope): Promise<unknown>;
+}
+declare function createBridgeTransport(host?: BridgeHostKind, options?: BridgeTransportOptions): BridgeTransport;
+
+type AllowUrl = (url: string) => boolean;
+/**
+ * 기본 정책: 같은 앱 안의 경로만 허용.
+ * - `/a/b?x=1` 같은 상대 경로 (`//host` 프로토콜 상대 URL 제외)
+ * - 현재 origin 과 같은 절대 http(s) URL
+ * `javascript:`, `data:`, 외부 도메인은 거부한다.
+ */
+declare function isSafeStackUrl(url: string): boolean;
+/** 같은 origin 절대 URL → 경로로 정규화. 그 밖(상대 경로·커스텀 스킴)은 그대로 */
+declare function toStackPath(url: string): string;
+/** payload 에서 url 을 꺼내 형식·정책 검증 후 경로로 반환. 실패 시 BridgeError */
+declare function assertStackUrl(payload: unknown, allowUrl?: AllowUrl): string;
+
+type WebViewBridgeClientOptions = BridgeTransportOptions & {
+    transport?: BridgeTransport;
+    /** outbound stack URL 검증 (기본 isSafeStackUrl) */
+    allowUrl?: AllowUrl;
+    /** 요청 기본 타임아웃 ms */
+    timeoutMs?: number;
+};
+interface BridgeRequestOptions {
+    timeoutMs?: number;
+    /**
+     * RN: 네이티브가 `bridge.response`(replyTo) 로 회신할 때까지 기다린다.
+     * 기본 false — 전송 즉시 resolve (1.x 네이티브 호환).
+     */
+    expectResponse?: boolean;
+}
+interface BridgeResult<TResult = unknown> {
+    /** 전송한 요청 envelope */
+    envelope: BridgeEnvelope;
+    /** Flutter callHandler 반환값 또는 RN 응답 payload */
+    result?: TResult;
+}
+declare class WebViewBridgeClient {
+    readonly host: ReturnType<typeof detectBridgeHost>;
+    private readonly transport;
+    private readonly allowUrl?;
+    private readonly timeoutMs;
+    constructor(options?: WebViewBridgeClientOptions);
+    /** 응답을 기다리지 않는 단방향 전송 */
+    send(envelope: BridgeEnvelope): Promise<unknown>;
+    request<TPayload = unknown, TResult = unknown>(method: string, payload?: TPayload, options?: BridgeRequestOptions): Promise<BridgeResult<TResult>>;
+    private stackRequest;
+    stackPush(url: string, meta?: StackMeta, options?: BridgeRequestOptions): Promise<BridgeResult<unknown>>;
+    stackReplace(url: string, meta?: StackMeta, options?: BridgeRequestOptions): Promise<BridgeResult<unknown>>;
+    stackPop(options?: BridgeRequestOptions): Promise<BridgeResult<unknown>>;
+    stackReset(url: string, meta?: StackMeta, options?: BridgeRequestOptions): Promise<BridgeResult<unknown>>;
+    /** web → native 웹 스택 변경 알림 (응답 없음) */
+    notifyStackChanged(payload: StackChangedPayload): Promise<unknown>;
+}
+declare function createWebViewBridgeClient(options?: WebViewBridgeClientOptions): WebViewBridgeClient;
+
+type StackRouterBridge = {
+    push: (url: string, meta?: StackMeta, options?: BridgeRequestOptions) => Promise<BridgeResult>;
+    replace: (url: string, meta?: StackMeta, options?: BridgeRequestOptions) => Promise<BridgeResult>;
+    pop: (options?: BridgeRequestOptions) => Promise<BridgeResult>;
+    reset: (url: string, meta?: StackMeta, options?: BridgeRequestOptions) => Promise<BridgeResult>;
+};
+type CreateStackRouterBridgeOptions = BridgeTransportOptions & {
+    allowUrl?: AllowUrl;
+    timeoutMs?: number;
+};
+/**
+ * Web → native stack navigation (Flutter `callHandler` / RN `postMessage`).
+ * Returns null in browser-only environments.
+ */
+declare function createStackRouterBridge(options?: CreateStackRouterBridgeOptions): StackRouterBridge | null;
+/** `window.stackRouterBridge` → 모듈 캐시 → 새로 생성 후 캐시 */
+declare function getStackRouterBridge(): StackRouterBridge | null;
+declare function installStackRouterBridge(options?: CreateStackRouterBridgeOptions): StackRouterBridge | null;
+/** 테스트·호스트 전환용 캐시 초기화 */
+declare function resetStackRouterBridgeCache(): void;
+
+type FlutterInAppWebViewBridge = {
+    callHandler: (handlerName: string, ...args: unknown[]) => Promise<unknown>;
+};
+declare global {
+    interface Window {
+        ReactNativeWebView?: {
+            postMessage: (message: string) => void;
+        };
+        flutter_inappwebview?: FlutterInAppWebViewBridge;
+        /** Native → web: unified protocol ingress */
+        webviewkitBridge?: {
+            postMessage: (message: string | unknown) => void;
+        };
+        /** Web → native stack */
+        stackRouterBridge?: StackRouterBridge;
+        /** Native → web stack */
+        stackPush?: (url: string, meta?: StackMeta) => Promise<boolean>;
+        stackReplace?: (url: string, meta?: StackMeta) => Promise<boolean>;
+        stackPop?: () => Promise<boolean>;
+        stackReset?: (url: string, meta?: StackMeta) => Promise<boolean>;
+    }
+}
+
+type HandlerResult = boolean | Promise<boolean>;
+type StackRouterHostHandlers = {
+    push: (url: string, meta?: StackMeta) => HandlerResult;
+    replace: (url: string, meta?: StackMeta) => HandlerResult;
+    pop: () => HandlerResult;
+    reset: (url: string, meta?: StackMeta) => HandlerResult;
+};
+type InstallBridgeHostOptions = {
+    /** Native → web stack navigation */
+    stack?: StackRouterHostHandlers;
+    /** Custom method handlers keyed by envelope `method` */
+    handlers?: Record<string, (payload: unknown, envelope: BridgeEnvelope) => HandlerResult>;
+    /** native → web `back.request` (하드웨어 back). true = 웹에서 처리함 */
+    onBackRequest?: () => HandlerResult;
+    /** Called for every valid envelope before routing */
+    onMessage?: (envelope: BridgeEnvelope) => void;
+    /** 검증 실패·핸들러 예외 (throw 대신 여기로 전달) */
+    onError?: (error: BridgeError, envelope?: BridgeEnvelope) => void;
+    /** inbound stack URL 검증 (기본 isSafeStackUrl) */
+    allowUrl?: AllowUrl;
+    /** 모든 inbound 요청에 `bridge.response` 회신 (back.request 는 항상 회신) */
+    replyToNative?: boolean;
+    /** 회신용 transport 옵션 */
+    transport?: BridgeTransportOptions;
+    /**
+     * `window.stackRouterBridge` 설치 (web → native).
+     * true 면 `createStackRouterBridge()` 로 생성한다.
+     */
+    exposeStackRouterBridge?: StackRouterBridge | boolean;
+    /** Register `window.stackPush` / `stackPop` for Flutter native→web (default true when `stack`) */
+    legacyInboundHandlers?: boolean;
+};
+/** inbound 메시지 처리. 절대 reject 하지 않는다 (실패는 false + onError) */
+declare function handleBridgeMessage(raw: string | unknown, options: InstallBridgeHostOptions): Promise<boolean>;
+type BridgeHostCleanup = () => void;
+declare function installBridgeHost(options: InstallBridgeHostOptions): BridgeHostCleanup;
+/** Emit a protocol envelope from web (e.g. for tests or custom native listeners) */
+declare function emitBridgeEnvelope(method: string, payload?: unknown): BridgeEnvelope;
+
+type WebViewBridgeProviderProps = {
+    children?: ReactNode;
+    /** Native → web stack handlers (e.g. Next.js `router.push`) */
+    stack?: StackRouterHostHandlers;
+    transport?: CreateStackRouterBridgeOptions;
+    /** Install `window.stackRouterBridge` for web → native */
+    enableOutboundBridge?: boolean;
+    hostOptions?: Omit<InstallBridgeHostOptions, "stack" | "exposeStackRouterBridge" | "legacyInboundHandlers">;
+};
+/**
+ * Mount once near the app root (Next.js `layout`, SPA `App`).
+ * Wires protocol ingress + optional legacy window stack handlers.
+ * `stack`·`hostOptions` 는 최신 값을 ref 로 읽으므로 인라인 객체여도 재설치하지 않는다.
+ */
+declare function WebViewBridgeProvider({ children, stack, transport, enableOutboundBridge, hostOptions, }: WebViewBridgeProviderProps): _emotion_react_jsx_runtime.JSX.Element;
+
+/** push/back 전환 기본 시간 (ms). `StackRouterProvider` `duration` 으로 조정 */
+declare const STACK_TRANSITION_MS = 300;
+/** `history.back()` 이 popstate 를 기다리는 최대 시간 */
+declare const BACK_TIMEOUT_MS = 1000;
+/** 브릿지 요청 응답 기본 타임아웃 */
+declare const BRIDGE_TIMEOUT_MS = 5000;
+
+interface StackBridgeSyncOptions {
+    allowUrl?: AllowUrl;
+    onError?: (error: BridgeError, envelope?: BridgeEnvelope) => void;
+    /** 웹 스택 변경 시 `stack.changed` 전송 (기본 true) */
+    emitStackChanged?: boolean;
+}
+
+interface Activity {
+    /** 정적 경로 또는 동적 세그먼트 패턴 (`/detail/:id`) */
+    path: string;
+    element: React.ReactNode;
+}
+type StackTransitionType = "slide" | "fade" | "none";
+type RestoreStackPolicy = "with-root" | "top-only";
+interface StackRouterProviderProps {
+    initialActivity: Activity;
+    Activities?: Activity[];
+    maxWidth?: string;
+    /** true면 상단에 `StackHeader` 렌더 */
+    isShowHeader?: boolean;
+    /** 개발 시 스택 로드맵 오버레이 (기본: NODE_ENV === "development") */
+    enableDevTools?: boolean;
+    transition?: StackTransitionType;
+    /** 전환 시간 ms (기본 STACK_TRANSITION_MS) */
+    duration?: number;
+    /** 새로고침·딥링크 진입 시 스택 복원 정책 (기본 "with-root") */
+    restoreStack?: RestoreStackPolicy;
+    /** env(safe-area-inset-*) padding 적용 */
+    safeArea?: boolean;
+    /** 루트에서 back 했을 때 (앱 종료·WebView 닫기 위임) */
+    onBackAtRoot?: () => void;
+    /** 등록되지 않은 경로로 이동하려 할 때 */
+    onNotFound?: (path: string) => void;
+    /** 네이티브 브릿지 연동 */
+    bridge?: boolean | StackBridgeSyncOptions;
+}
+interface VisiblePage {
+    path: string;
+    element: React.ReactNode;
+}
+declare enum Direction {
+    FORWARD = "forward",
+    BACKWARD = "backward"
+}
+type DirectionType = Direction.FORWARD | Direction.BACKWARD;
+declare enum HistoryAction {
+    PUSH = "PUSH",
+    POP = "POP",
+    REPLACE = "REPLACE"
+}
+interface HistoryState {
+    /** pathname + search */
+    path: string;
+    data?: unknown;
+    action?: HistoryAction;
+    /** 스택 엔트리 고유 key */
+    key?: string;
+    /** 스택 내 위치 (0 = root) */
+    index?: number;
+}
+type HistoryListener = (state: HistoryState) => void;
+
+type HistoryEntryState = Omit<HistoryState, "path" | "action">;
+/**
+ * `window.history` 래퍼.
+ * - 리스너는 브라우저 popstate(뒤로·앞으로·`go`)에서만 호출된다.
+ * - push/replace 는 동기 실행이며 리스너를 호출하지 않는다 (호출자가 상태를 직접 갱신).
+ * - popstate 구독은 첫 리스너 등록 시점에 건다 (import 부작용 없음).
+ */
+declare const history: {
+    push: (path: string, state?: HistoryEntryState) => void;
+    replace: (path: string, state?: HistoryEntryState) => void;
+    /** `history.go(delta)` 후 popstate 가 오면 true, BACK_TIMEOUT_MS 안에 오지 않으면 false */
+    travel: (delta: number) => Promise<boolean>;
+    back: () => Promise<boolean>;
+    forward: () => void;
+    go: (delta: number) => void;
+    getCurrentState: () => HistoryState;
+    addListener: (listener: HistoryListener) => () => boolean;
+};
+
+interface StackDevRoadmapProps {
+    /** 스택에 쌓인 페이지 경로 (아래 → 위 순) */
+    pages: {
+        path: string;
+    }[];
+    currentPath: string;
+    /** false면 렌더하지 않음 */
+    visible?: boolean;
+}
+/**
+ * 개발 환경에서 스택 깊이·경로를 눈으로 확인하는 로드맵 오버레이.
+ * StackRouterProvider `enableDevTools` 와 함께 사용합니다.
+ */
+declare function StackDevRoadmap({ pages, currentPath, visible, }: StackDevRoadmapProps): _emotion_react_jsx_runtime.JSX.Element | null;
+
+interface BackRouterProps {
+    /** 스크린리더 라벨 */
+    label?: string;
+}
+declare const BackRouter: ({ label }: BackRouterProps) => _emotion_react_jsx_runtime.JSX.Element;
+
+interface StackHeaderProps {
+    /** 기본: 현재 path */
+    title?: React.ReactNode;
+}
+declare const Header: ({ title }: StackHeaderProps) => _emotion_react_jsx_runtime.JSX.Element;
+
+interface ActivityContextValue {
+    key: string;
+    path: string;
+    pattern: string;
+    params: Record<string, string>;
+    query: Record<string, string>;
+    data?: unknown;
+    /** 스택 내 위치 (0 = root) */
+    index: number;
+    isTop: boolean;
+}
+/** 현재 페이지(Activity) 자신의 path·params·query·data */
+declare function useActivity(): ActivityContextValue;
+/** `/detail/:id` → `{ id }` */
+declare function useParams<TParams extends Record<string, string> = Record<string, string>>(): TParams;
+
+interface PathMatch {
+    params: Record<string, string>;
+    query: Record<string, string>;
+}
+declare function parseQuery(search: string): Record<string, string>;
+/**
+ * `pattern`(`/detail/:id`)과 `url`(`/detail/3?tab=a#x`)을 비교한다.
+ * 끝의 `/`와 `#hash`는 무시한다. 불일치면 null.
+ */
+declare function matchPath(pattern: string, url: string): PathMatch | null;
+/** 등록 순서대로 첫 매칭 Activity */
+declare function findActivity(activities: Activity[], url: string): {
+    activity: Activity;
+    match: PathMatch;
+} | null;
+
+interface StackEntry {
+    key: string;
+    /** 실제 URL (pathname + search) */
+    path: string;
+    /** 매칭된 Activity path 패턴 */
+    pattern: string;
+    params: Record<string, string>;
+    query: Record<string, string>;
+    data?: unknown;
+}
+
+interface StackRouterContextValue {
+    currentPath: string;
+    /** top 엔트리의 history state */
+    currentState: HistoryState;
+    depth: number;
+    canGoBack: boolean;
+    isTransitioning: boolean;
+    entries: StackEntry[];
+    /** 1.x 호환 */
+    visiblePages: VisiblePage[];
+    Activities: Activity[];
+    initialActivity: Activity;
+    push: (path: string, data?: unknown) => boolean;
+    replace: (path: string, data?: unknown) => boolean;
+    reset: (path: string, data?: unknown) => boolean;
+    back: () => boolean;
+    pop: (count?: number) => boolean;
+    popTo: (path: string) => boolean;
+    /** @deprecated 스택과 동기화되지 않는다. 브라우저 forward 는 popstate 로 처리된다 */
+    forward: () => void;
+}
+declare const useStackRouter: () => StackRouterContextValue;
+declare const StackRouterProvider: ({ initialActivity, Activities, maxWidth, isShowHeader, enableDevTools, transition, duration, restoreStack, safeArea, onBackAtRoot, onNotFound, bridge, }: StackRouterProviderProps) => _emotion_react_jsx_runtime.JSX.Element;
+
+export { type Activity, type ActivityContextValue, type AllowUrl, BACK_REQUEST_METHOD, BACK_TIMEOUT_MS, BRIDGE_ERROR_CODES, BRIDGE_NAMESPACE, BRIDGE_PROTOCOL_VERSION, BRIDGE_RESPONSE_METHOD, BRIDGE_TIMEOUT_MS, type BackRequestResult, BackRouter, type BridgeEnvelope, BridgeError, type BridgeErrorBody, type BridgeErrorCode, type BridgeHostCleanup, type BridgeHostKind, type BridgeRequestOptions, type BridgeResult, type BridgeTransport, type BridgeTransportOptions, type CreateStackRouterBridgeOptions, Direction, type DirectionType, FLUTTER_LEGACY_STACK_HANDLERS, FLUTTER_READY_EVENT, FLUTTER_UNIFIED_HANDLER, type FlutterInAppWebViewBridge, HistoryAction, type HistoryListener, type HistoryState, type InstallBridgeHostOptions, RN_BRIDGE_HANDLER, type RestoreStackPolicy, STACK_BRIDGE_METHODS, STACK_TRANSITION_MS, type StackBridgeMethod, type StackBridgeSyncOptions, type StackChangedPayload, StackDevRoadmap, type StackEntry, Header as StackHeader, type StackMeta, type StackPushPayload, type StackReplacePayload, type StackResetPayload, type StackRouterBridge, type StackRouterContextValue, type StackRouterHostHandlers, StackRouterProvider, type StackRouterProviderProps, type StackTransitionType, type VisiblePage, type WaitForBridgeHostOptions, WebViewBridgeClient, type WebViewBridgeClientOptions, WebViewBridgeProvider, type WebViewBridgeProviderProps, assertStackUrl, createBridgeEnvelope, createBridgeId, createBridgeResponse, createBridgeTransport, createStackRouterBridge, createWebViewBridgeClient, detectBridgeHost, emitBridgeEnvelope, findActivity, getStackRouterBridge, handleBridgeMessage, history, installBridgeHost, installStackRouterBridge, isBridgeEnvelope, isNativeBridgeHost, isSafeStackUrl, matchPath, parseBridgeMessage, parseQuery, resetStackRouterBridgeCache, serializeBridgeMessage, toStackPath, useActivity, useParams, useStackRouter, waitForBridgeHost };