@getforma/router

declare function createBrowserAdapter(): RouteAdapter;

declare function createHtmlAdapter(options: HtmlAdapterOptions): RouteAdapter;

declare function createNativeAdapter(bootstrap: NavigationBootstrap): RouteAdapter;

declare function createRouter(input: RouterOptions): Router;

declare function defineRoutes(input: readonly RouteDefinition[]): readonly RouteDefinition[];

declare function Link(props: LinkProps): HTMLAnchorElement;

declare function matchRoutes(routes: readonly RouteDefinition[], pathname: string): readonly Match[] | null;

declare class NavigationError extends Error {
    readonly code: string;
    readonly documentRecovery: boolean;
    readonly revoke: boolean;
    constructor(code: string, documentRecovery?: boolean, revoke?: boolean);
}

declare function Outlet(props: {
    outlet: HTMLElement;
}): HTMLElement;

type Accessor<T> = () => T;

interface ActionOutcome {
    readonly outcome: 'success' | 'validation' | 'error' | 'redirect';
    readonly status: number;
    readonly data: Readonly<Record<string, unknown>>;
}

interface AdapterSession {
    initialize?(context: NavigationContext): Promise<void>;
    prepare(context: NavigationContext): Promise<PreparedView | Redirect>;
    allowsAction?(url: URL): boolean;
    admitAction?(data: unknown, response: Response, url: URL): ActionOutcome;
    invalidate?(): void;
    dispose(): void;
}

interface HtmlAdapterOptions {
    readonly head: string;
    readonly pages: readonly HtmlPage[];
}

interface HtmlPage {
    readonly path: string;
    readonly sha256: string;
    readonly title: string;
    readonly head: string;
}

interface LinkProps {
    href: string | URL;
    children?: string | Node | readonly (string | Node)[];
    target?: string;
    download?: string;
    class?: string;
    native?: boolean;
    document?: Document;
}

interface LocationState {
    readonly url: URL;
    readonly key: string;
    readonly matches: readonly {
        readonly id: string;
        readonly params: Readonly<Record<string, string>>;
    }[];
}

interface Match {
    readonly id: string;
    readonly params: Readonly<Record<string, string>>;
    readonly definition: RouteDefinition;
}

interface NavigationBootstrap {
    readonly registrations: Readonly<Record<string, (element: HTMLElement, props: Record<string, unknown> | null) => unknown>>;
    readonly app: string;
    readonly build: string;
    readonly group: string;
    readonly owners: readonly string[];
}

interface NavigationContext {
    readonly url: URL;
    readonly matches: readonly Match[];
    readonly signal: AbortSignal;
    readonly revalidate: boolean;
    readonly location: Accessor<LocationState>;
}

type NavigationResult = {
    kind: 'committed';
    location: LocationState;
    ready: Promise<void>;
} | {
    kind: 'cancelled';
    reason: 'superseded' | 'unchanged' | 'disposed';
} | {
    kind: 'blocked';
} | {
    kind: 'document-navigation';
    reason: string;
} | {
    kind: 'failed';
    code: string;
};

interface PreparedView {
    readonly title?: string;
    readonly status?: number;
    readonly focus?: HTMLElement;
    validate(): void;
    commit(): void;
    activate(): Promise<void>;
    dispose(): void;
}

interface Redirect {
    readonly redirect: string;
}

interface RenderContext {
    readonly url: URL;
    readonly location: Accessor<LocationState>;
    readonly params: Readonly<Record<string, string>>;
    readonly outlet: HTMLElement;
    readonly signal: AbortSignal;
}

interface RouteAdapter {
    readonly kind: 'browser' | 'html' | 'native';
    connect(root: HTMLElement): AdapterSession;
}

interface RouteDefinition {
    readonly id: string;
    readonly path?: string;
    readonly index?: true;
    readonly children?: readonly RouteDefinition[];
    readonly adapter?: RouteAdapter;
    readonly render?: (context: RenderContext) => Element;
    readonly reuseKey?: (context: Match) => string;
}

interface Router {
    readonly location: Accessor<LocationState>;
    readonly pending: Accessor<URL | undefined>;
    readonly mutation: Accessor<'idle' | 'submitting' | 'revalidating' | 'uncertain'>;
    readonly ready: Promise<void>;
    navigate(to: string | URL, options?: {
        replace?: boolean;
    }): Promise<NavigationResult>;
    revalidate(): Promise<NavigationResult>;
    prefetch(to: string | URL): Promise<'completed' | 'skipped' | 'cancelled'>;
    submit(form: HTMLFormElement, submitter?: HTMLElement): Promise<SubmissionResult>;
    beforeLeave(check: (next: URL, signal: AbortSignal) => boolean | Promise<boolean>): () => void;
    invalidateContext(): void;
    resolveUncertain(check: (signal: AbortSignal) => Promise<boolean>): Promise<boolean>;
    dispose(): void;
}

interface RouterOptions {
    readonly routes: readonly RouteDefinition[];
    readonly root: HTMLElement;
    readonly adapter: RouteAdapter;
    readonly base?: string;
    readonly statusRegion?: HTMLElement;
    readonly title?: (location: LocationState) => string;
    readonly onError?: (code: string) => void;
    readonly onAction?: (outcome: ActionOutcome, form: HTMLFormElement) => void;
    readonly checkContext?: (signal: AbortSignal) => Promise<boolean>;
    readonly contextChannel?: string;
    readonly recoveryKey?: string;
    readonly canPrefetch?: (url: URL) => boolean;
}

type SubmissionResult = {
    kind: 'success';
} | {
    kind: 'validation' | 'error';
    status: number;
    data: Readonly<Record<string, unknown>>;
} | {
    kind: 'busy' | 'unsupported' | 'uncertain' | 'disposed';
};