@vireocodedev/shell

export declare const OVERLAY_HISTORY_STATE_KEY = "__starterShellOverlayStack";

export type OverlayHistoryAction = {
    type: "idle";
} | {
    type: "push";
    stack: readonly OverlayHistoryEntryId[];
} | {
    type: "consume";
} | {
    type: "requestClose";
    id: OverlayHistoryEntryId;
};

export type OverlayHistoryEntry = {
    id: OverlayHistoryEntryId;
    requestClose: () => void;
};

export type OverlayHistoryEntryId = string;

export type OverlayHistoryRegistry = {
    register(entry: OverlayHistoryEntry): () => void;
    unregister(id: OverlayHistoryEntryId): void;
    getSnapshot(): readonly OverlayHistoryEntry[];
    subscribe(listener: () => void): () => void;
    clear(): void;
};

export type OverlayHistoryResolveInput = {
    desired: readonly OverlayHistoryEntryId[];
    actual: readonly OverlayHistoryEntryId[];
    previousActual: readonly OverlayHistoryEntryId[];
    navigationType: "POP" | "PUSH" | "REPLACE";
    locationChanged: boolean;
    urlChanged: boolean;
};

export type ResolvedShellRoute<TPermission extends ShellPermission = ShellPermission, TContext = unknown> = {
    key: string;
    kind: "page" | "section";
    pathPattern: string;
    parentKey?: string;
    redirectToPattern?: string;
    node: ShellRouteNode<TPermission, TContext>;
};

export type ShellAuthRedirectState = {
    from: string;
};

export type ShellConfig<TPermission extends ShellPermission = ShellPermission, TContext = unknown> = {
    mode: ShellMode;
    sitemap: ShellSitemap;
    entryPage: ShellPage<string, string, TPermission, TContext>;
    loginPage?: ShellPage<string, string, TPermission, TContext>;
    unauthorizedPage?: ShellPage<string, string, TPermission, TContext>;
    navigation?: {
        authenticated?: readonly ShellNavigationEntry<TPermission, TContext>[];
        public?: readonly ShellNavigationEntry<TPermission, TContext>[];
    };
};

export type ShellConfigValidationOptions<TPermission extends ShellPermission = ShellPermission> = {
    permissions?: ReadonlySet<TPermission> | readonly TPermission[] | Readonly<Record<TPermission, unknown>>;
};

export type ShellLabel<TContext = unknown> = string | ((context: TContext, params: ShellRouteParams) => string);

export type ShellLocationSnapshot = {
    pathname: string;
    search?: string;
    hash?: string;
};

export type ShellMode = z.infer<typeof ShellModeSchema>;

export declare const ShellModeSchema: z.ZodEnum<{
    dashboard: "dashboard";
    public: "public";
    bare: "bare";
}>;

export type ShellNavigationEntry<TPermission extends ShellPermission = ShellPermission, TContext = unknown> = {
    type: "item";
    page: ShellPage<string, string, TPermission, TContext>;
    label?: ShellLabel<TContext>;
    icon?: string;
    disabled?: boolean;
    disabledReason?: ShellLabel<TContext>;
    permission?: TPermission;
    permissionScope?: ShellPermissionScope;
} | {
    type: "heading";
    id: string;
    label: ShellLabel<TContext>;
} | {
    type: "action";
    id: string;
    label: ShellLabel<TContext>;
    icon?: string;
    permission?: TPermission;
} | {
    type: "divider";
};

export declare const ShellNavigationIdSchema: z.ZodString;

export type ShellPage<TKey extends string = string, TRoutePath extends string = string, TPermission extends ShellPermission = ShellPermission, TContext = unknown> = ShellPageDefinition<TPermission, TContext, TRoutePath> & {
    readonly kind: "page";
    readonly key: TKey;
};

export type ShellPageDefinition<TPermission extends ShellPermission = ShellPermission, TContext = unknown, TRoutePath extends string = string> = {
    routePath: TRoutePath;
    label: ShellLabel<TContext>;
    icon?: string;
    permission?: TPermission;
    permissionScope?: ShellPermissionScope;
    metadata?: ShellRouteMetadata;
};

export type ShellPathForPage<TNodes extends readonly ShellRouteTreeNode[], TPage extends ShellPage> = Extract<ShellRouteTreePageEntries<TNodes>, {
    page: TPage;
}> extends {
    path: infer TPath extends string;
} ? TPath : never;

export type ShellPermission = string;

export type ShellPermissionScope = Readonly<Record<string, unknown>>;

export declare const ShellRouteKeySchema: z.ZodString;

export type ShellRouteMetadata = Readonly<Record<string, unknown>>;

export type ShellRouteNode<TPermission extends ShellPermission = ShellPermission, TContext = unknown> = ShellPage<string, string, TPermission, TContext> | ShellSection<string, string, TPermission, TContext>;

export type ShellRouteParamValue = string | number;

export type ShellRouteParams = Readonly<Record<string, ShellRouteParamValue | undefined>>;

export declare const ShellRoutePathSchema: z.ZodString;

export type ShellRouteTreeNode<TPermission extends ShellPermission = ShellPermission, TContext = unknown> = ShellPage<string, string, TPermission, TContext> | {
    node: ShellRouteNode<TPermission, TContext>;
    redirectTo?: ShellPage<string, string, TPermission, TContext>;
    children?: readonly ShellRouteTreeNode<TPermission, TContext>[];
};

export type ShellRouteTreePageEntries<TNodes, TParentPath extends string = "", TDepth extends number = 8> = [
    TDepth
] extends [
    never
] ? never : TNodes extends readonly unknown[] ? RouteNodePageEntry<TNodes[number], TParentPath, TDepth> : never;

export type ShellSection<TKey extends string = string, TRoutePath extends string = string, TPermission extends ShellPermission = ShellPermission, TContext = unknown> = ShellSectionDefinition<TPermission, TContext, TRoutePath> & {
    readonly kind: "section";
    readonly key: TKey;
};

export type ShellSectionDefinition<TPermission extends ShellPermission = ShellPermission, TContext = unknown, TRoutePath extends string = string> = Omit<ShellPageDefinition<TPermission, TContext, TRoutePath>, "icon"> & {
    icon?: string;
};

export type ShellSitemap<TRoutes extends readonly ShellRouteTreeNode[] = readonly ShellRouteTreeNode[]> = {
    readonly routes: readonly ResolvedShellRoute[];
    getPath<TPage extends ShellRouteTreePageEntries<TRoutes>["page"]>(page: TPage, ...args: RoutePathParamArgs<ShellPathForPage<TRoutes, TPage>>): string;
    getPathPattern<TPage extends ShellRouteTreePageEntries<TRoutes>["page"]>(page: TPage): ShellPathForPage<TRoutes, TPage>;
    getRoute(key: string): ResolvedShellRoute | undefined;
};

export declare function createAuthRedirectState(location: ShellLocationSnapshot, loginPath: string): ShellAuthRedirectState | undefined;

export declare function createOverlayHistoryRegistry(): OverlayHistoryRegistry;

export declare function createShellSitemap<const TRoutes extends readonly ShellRouteTreeNode[]>(tree: TRoutes): ShellSitemap<TRoutes>;

export declare function defineShellConfig<TPermission extends ShellPermission = ShellPermission, TContext = unknown>(config: ShellConfig<TPermission, TContext>, options?: ShellConfigValidationOptions<TPermission>): ShellConfig<TPermission, TContext>;

export declare function defineShellPages<TPermission extends ShellPermission = ShellPermission, TContext = unknown, const TPages extends Record<string, ShellPageDefinition<TPermission, TContext>> = Record<string, ShellPageDefinition<TPermission, TContext>>>(pages: StrictConfigRecord<TPages, ShellPageDefinition<TPermission, TContext>>): ShellPageRecord<TPages, TPermission, TContext>;

export declare function defineShellSections<TPermission extends ShellPermission = ShellPermission, TContext = unknown, const TSections extends Record<string, ShellSectionDefinition<TPermission, TContext>> = Record<string, ShellSectionDefinition<TPermission, TContext>>>(sections: StrictConfigRecord<TSections, ShellSectionDefinition<TPermission, TContext>>): ShellSectionRecord<TSections, TPermission, TContext>;

export declare function generateShellPath(pattern: string, params?: ShellRouteParams): string;

export declare function getCommonOverlayPrefixLength(left: readonly OverlayHistoryEntryId[], right: readonly OverlayHistoryEntryId[]): number;

export declare function getRequiredRouteParamNames(pattern: string): string[];

export declare function isSafeInternalPath(path: string): boolean;

export declare function joinRoutePattern(parentPath: string, routePath: string): string;

export declare function normalizeRoutePath(path: string): string;

export declare function readOverlayStack(state: unknown): OverlayHistoryEntryId[];

export declare function resolveOverlayHistoryAction(input: OverlayHistoryResolveInput): OverlayHistoryAction;

export declare function resolvePostLoginPath(state: unknown, fallbackPath: string): string;

export declare const shellNavigation: {
    item<TPermission extends ShellPermission = string, TContext = unknown>(page: ShellPage<string, string, TPermission, TContext>, overrides?: Omit<ShellNavigationEntry<TPermission, TContext> & {
        type: "item";
    }, "page" | "type">): ShellNavigationEntry<TPermission, TContext>;
    heading<TContext = unknown>(id: string, label: ShellLabel<TContext>): ShellNavigationEntry<ShellPermission, TContext>;
    action<TPermission extends ShellPermission = string, TContext = unknown>(id: string, label: ShellLabel<TContext>, options?: {
        icon?: string;
        permission?: TPermission;
    }): ShellNavigationEntry<TPermission, TContext>;
    divider(): ShellNavigationEntry;
};

export declare function withOverlayStack(state: unknown, stack: readonly OverlayHistoryEntryId[]): Record<string, unknown>;