@vkma.dev/router 0.0.0-stage → 0.1.1

package/src/preset/define-view.ts

@@ -0,0 +1,73 @@
+import type { LooseRouteOptions, PanelLazy, PanelOptions } from "./builders.ts";
+import { definePanel, type PanelDefinition } from "./define-panel.ts";
+
+/** Brand distinguishing a {@link ViewDefinition} from raw view options. */
+export const VIEW_DEFINITION = "__vkmaView" as const;
+
+/**
+ * A view hub: the ONE place a view key is written. Created by
+ * {@link defineView}; its `panel()` method is the view-scoped
+ * `definePanel` — it creates the definition and registers it into the
+ * view's registry in call order (the order is what VKUI View children get,
+ * i.e. the push/pop animation direction).
+ */
+export interface ViewDefinition<V extends string = string> {
+	readonly [VIEW_DEFINITION]: true;
+	/** The view (story) namespace and route id segment (`view:${view}`). */
+	readonly view: V;
+	/** Definitions registered by `panel()`, keyed by panel path. */
+	readonly panels: Record<string, PanelDefinition>;
+	/** Optional view-level route options passthrough (the view is a pathless layout). */
+	readonly options?: LooseRouteOptions;
+}
+
+export interface ViewScope<V extends string = string> {
+	/** View-scoped `definePanel` — the view argument is pre-bound. */
+	panel<const P extends string, O extends PanelOptions = PanelOptions>(
+		path: P,
+		options: O,
+		lazy?: PanelLazy,
+	): PanelDefinition<V, P, O>;
+}
+
+/**
+ * Declare a view hub and its panel factory:
+ *
+ * ```ts
+ * export const feedView = defineView("feed");
+ *
+ * export const feedPanel = feedView.panel("feed", { loader: ... }, () => import("./feed.ui"));
+ * export const postPanel = feedView.panel("post/$id", { ... }, () => import("./post.ui"));
+ * ```
+ *
+ * The view key is written exactly once; `createApp` accepts the hub
+ * directly (`views: [feedView, ...]`). Duplicate view keys are a dev-time
+ * console error — a view must not sprawl across files.
+ */
+export function defineView<const V extends string>(
+	view: V,
+	options?: LooseRouteOptions,
+): ViewDefinition<V> & ViewScope<V> {
+	const usedPanelPaths = new Set<string>();
+	const panels: Record<string, PanelDefinition> = {};
+	const definition: ViewDefinition<V> = {
+		[VIEW_DEFINITION]: true,
+		view,
+		panels,
+		...(options !== undefined ? { options } : {}),
+	};
+	const scope: ViewScope<V> = {
+		panel(path, panelOptions, lazy) {
+			if (usedPanelPaths.has(path)) {
+				console.error(
+					`[vkma-router] duplicate panel path "${path}" in view "${view}"; panels within a view must have distinct paths`,
+				);
+			}
+			usedPanelPaths.add(path);
+			const declared = definePanel(view, path, panelOptions, lazy);
+			panels[path] = declared;
+			return declared;
+		},
+	};
+	return { ...definition, ...scope };
+}

package/src/preset/inflate.ts

@@ -0,0 +1,57 @@
+/**
+ * Inflate: a synthetic parent chain after a deep link. Deep-linked to the
+ * 4th panel? Back should walk the natural flow (panel 1 → 2 → 3 → 4)
+ * instead of closing the app. The chain is auto-derived from the view's
+ * panel declaration order (declaration order IS the navigation flow — the
+ * same convention VKUI animations rely on), replacing the old router's
+ * manual `hierarchy` config.
+ */
+
+import type { PanelHandle } from "../preset/builders.tsx";
+
+/**
+ * Build the chain of hrefs to replay BEFORE the target location.
+ *
+ * @param orderedPanels panels of the target's view, in declaration order
+ * @param targetRouteId route id of the deep-linked panel
+ * @param params params of the deep-linked location (fill intermediate
+ *              panels' path params; a panel whose params cannot be filled
+ *              is skipped from the chain)
+ * @returns hrefs excluding the target (the target is already the current
+ *          history entry — replay replaces the first chain entry, pushes
+ *          the rest, then re-pushes the target href)
+ */
+export function deriveInflateChain(
+	orderedPanels: PanelHandle[],
+	targetRouteId: string,
+	params: Record<string, string>,
+): string[] {
+	const targetIndex = orderedPanels.findIndex(panel => panel.routeId === targetRouteId);
+	if (targetIndex <= 0) {
+		return []; // first panel of the view (or unknown) — nothing to inflate
+	}
+	const chain: string[] = [];
+	for (const panel of orderedPanels.slice(0, targetIndex)) {
+		const interpolated = interpolatePath(panel.path, params);
+		if (interpolated !== null) {
+			chain.push(interpolated); // a required param cannot be derived — skip the step
+		}
+	}
+	return chain;
+}
+
+/**
+ * Fill a route path's `$param` segments from the deep link's params.
+ * Returns null when a required param cannot be derived (the step is
+ * unrepresentable as a URL and must be skipped).
+ */
+export function interpolatePath(path: string, params: Record<string, string>): string | null {
+	const interpolated = path.replace(/\$([A-Za-z0-9_]+)/g, (segment, key: string) => {
+		const value = params[key];
+		return value !== undefined ? value : segment;
+	});
+	if (interpolated.includes("$")) {
+		return null;
+	}
+	return interpolated.startsWith("/") ? interpolated : `/${interpolated}`;
+}

package/src/preset/navigator.ts

@@ -0,0 +1,250 @@
+import {
+	useNavigate,
+	useRouter,
+	useRouterState,
+	type NavigateOptions,
+} from "@tanstack/react-router";
+import { looseRouteOf } from "../core/loose-route.ts";
+import { MODAL_STATE_KEY } from "../core/state-keys.ts";
+import { useHidePopout, useShowPopout } from "../vkui/popouts.tsx";
+
+/**
+ * The parity navigator over TanStack primitives: push/replace/back/
+ * backToFirst/showModal/hideModal/showPopout/hidePopout. Modal→modal
+ * navigation REPLACES the entry (the host closes one modal before opening
+ * the next — there is no modal stack); back from a modal returns to its
+ * panel. `push`/`replace`/`showModal` accept full TanStack NavigateOptions
+ * — typed by the registered route tree.
+ */
+
+export interface VkNavigator {
+	push<TParams extends Record<string, string>>(
+		page: PanelPage<TParams>,
+		params: TParams,
+		options?: Omit<NavigateOptions, "to" | "params">,
+	): Promise<void>;
+	push(options: NavigateOptions): Promise<void>;
+	replace<TParams extends Record<string, string>>(
+		page: PanelPage<TParams>,
+		params: TParams,
+		options?: Omit<NavigateOptions, "to" | "params">,
+	): Promise<void>;
+	replace(options: NavigateOptions): Promise<void>;
+	back(): void;
+	/** Pop all the way to the first history entry. */
+	backToFirst(): void;
+	/** Open a modal route; replaces the entry if another modal is open.
+	 * `props` (serializable) land in history.state and are read by
+	 * `useModalProps()` inside the modal component. */
+	showModal(options: NavigateOptions & { props?: unknown }): Promise<void>;
+	/** Close the current modal (back, or replace to the panel on first entry). */
+	hideModal(): void;
+	/**
+	 * Open a global (`?modal=<id>`) modal from any panel, masking the URL so
+	 * the visible path stays at the panel. Back closes it.
+	 */
+	showGlobalModal(
+		id: string,
+		options?: { state?: Record<string, unknown>; props?: unknown },
+	): Promise<void>;
+	showPopout(id: string, props?: Record<string, unknown>): void;
+	hidePopout(): void;
+	/**
+	 * Block navigation while `onLeave` returns true (old router's
+	 * `RouteNavigator.block`). The callback receives the current and the
+	 * next location plus the action — PUSH/REPLACE as-is, back/forward/go
+	 * mapped to POP (old-router `BlockerFunction` parity). Returns the
+	 * unblock function.
+	 */
+	block(onLeave: (args: BlockerArgs) => boolean): () => void;
+}
+
+function isModalRouteId(router: ReturnType<typeof useRouter>, routeId: string): boolean {
+	return looseRouteOf(router, routeId)?.options.staticData?.modal !== undefined;
+}
+
+export interface BlockerArgs {
+	/** The location the navigation starts from (TanStack history location). */
+	currentLocation: { href: string; pathname: string };
+	/** The location the navigation is heading to. */
+	nextLocation: { href: string; pathname: string };
+	/** PUSH/REPLACE as-is; back, forward and go are one POP (old-router parity). */
+	action: "PUSH" | "REPLACE" | "POP";
+}
+
+/**
+ * A typed page object — a panel definition (`defineView().panel(...)`) or
+ * a panel handle (`app.panels[...]`). The params type flows from the
+ * definition's phantom `types`, so `navigator.push(postPanel, { id })`
+ * type-checks the params (old-router `Page`/`PageWithParams` parity,
+ * without the `hasParams` discriminator quirk).
+ */
+export interface PanelPage<TParams = Record<string, string>> {
+	path: string;
+	types?: { params: TParams };
+}
+
+export function useNavigator(): VkNavigator {
+	const router = useRouter();
+	const navigate = useNavigate();
+	const location = useRouterState({ select: state => state.location });
+	const modalOpen = useRouterState({
+		select: state => state.matches.some(match => isModalRouteId(router, match.routeId)),
+	});
+	const showPopout = useShowPopout();
+	const hidePopout = useHidePopout();
+
+	/** `"index"` and an optional leading slash normalize to the full path. */
+	const pageTo = (page: PanelPage): string =>
+		page.path === "index" ? "/" : `/${page.path.replace(/^\//, "")}`;
+
+	return {
+		push: ((
+			pageOrOptions: NavigateOptions | PanelPage,
+			params?: Record<string, string>,
+			rest?: Omit<NavigateOptions, "to" | "params">,
+		) =>
+			params === undefined
+				? navigate({
+						...(pageOrOptions as NavigateOptions),
+						replace: false,
+					})
+				: navigate({
+						to: pageTo(pageOrOptions as PanelPage),
+						params,
+						replace: false,
+						...rest,
+					})) as VkNavigator["push"],
+		replace: ((
+			pageOrOptions: NavigateOptions | PanelPage,
+			params?: Record<string, string>,
+			rest?: Omit<NavigateOptions, "to" | "params">,
+		) =>
+			params === undefined
+				? navigate({
+						...(pageOrOptions as NavigateOptions),
+						replace: true,
+					})
+				: navigate({
+						to: pageTo(pageOrOptions as PanelPage),
+						params,
+						replace: true,
+						...rest,
+					})) as VkNavigator["replace"],
+		back: () => {
+			router.history.back();
+		},
+		backToFirst: () => {
+			const index =
+				(location.state as { __TSR_index?: number } | undefined)?.__TSR_index ?? 0;
+			if (index > 0) {
+				router.history.go(-index);
+			}
+		},
+		showModal: ({ props, ...options }) => {
+			// nested modal: the target route is a CHILD of the currently open
+			// modal — PUSH (back unwinds the stack); sibling modals keep the
+			// old-router replace parity
+			let nested = false;
+			if (modalOpen && typeof options.to === "string") {
+				for (let i = router.state.matches.length - 1; i >= 0; i--) {
+					const matchRouteId = router.state.matches[i]?.routeId;
+					if (matchRouteId === undefined) {
+						continue;
+					}
+					const route = looseRouteOf(router, matchRouteId);
+					if (route?.options.staticData?.modal === undefined) {
+						continue;
+					}
+					nested =
+						route.fullPath !== undefined && options.to.startsWith(`${route.fullPath}/`);
+					break;
+				}
+			}
+			// TanStack types history state as its own updater shape — arbitrary
+			// serializable keys go through a cast (same as the popout state)
+			const withProps =
+				props !== undefined
+					? {
+							state: {
+								...(options.state as Record<string, unknown> | undefined),
+								[MODAL_STATE_KEY]: { props },
+							} as never,
+						}
+					: {};
+			return navigate({
+				...options,
+				// a modal open never changes the panel behind it — carry the
+				// panel's search (?tab=…) onto the modal entry, or the covered
+				// panel would snap to its default search for the whole time the
+				// modal is open (and snap back on close). An explicit `search`
+				// from the caller always wins.
+				search: options.search ?? true,
+				replace: nested ? false : modalOpen,
+				...withProps,
+			});
+		},
+		hideModal: () => {
+			if (router.history.canGoBack()) {
+				router.history.back();
+				return;
+			}
+			// deep-linked modal on the first entry: replace down to the panel
+			const parentPath = location.pathname.replace(/\/[^/]+$/, "") || "/";
+			void router.navigate({ href: parentPath, replace: true });
+		},
+		showPopout: (id, props) => {
+			showPopout(id, props);
+		},
+		hidePopout: () => {
+			hidePopout();
+		},
+		showGlobalModal: (id, { state, props, ...rest } = {}) => {
+			const { pathname, searchStr, hash } = router.state.location;
+			const params = new URLSearchParams(searchStr.replace(/^\?/, ""));
+			const already = params.get("modal") === id;
+			params.set("modal", id);
+			const href = `${pathname}?${params.toString()}${hash}`;
+			// the mask keeps the visible URL at the panel path while the modal
+			// is open (the modal param rides in history.state)
+			const maskParams = new URLSearchParams(params);
+			maskParams.delete("modal");
+			const maskQuery = maskParams.toString();
+			const maskHref = `${pathname}${maskQuery !== "" ? `?${maskQuery}` : ""}${hash}`;
+			const nextState =
+				state !== undefined || props !== undefined
+					? {
+							state: {
+								...state,
+								...(props !== undefined ? { [MODAL_STATE_KEY]: { props } } : {}),
+							} as never,
+						}
+					: {};
+			return navigate({
+				href,
+				mask: { to: maskHref },
+				replace: already || modalOpen,
+				...rest,
+				...nextState,
+			});
+		},
+		block: onLeave => {
+			const unblock = router.history.block({
+				// args infer as TanStack's BlockerFnArgs (HistoryLocation × 2 +
+				// action) — assignable to our structural BlockerArgs
+				blockerFn: args =>
+					onLeave({
+						currentLocation: args.currentLocation,
+						nextLocation: args.nextLocation,
+						// TanStack distinguishes BACK/FORWARD/GO; the old router's
+						// BlockerFunction saw one POP — keep the parity
+						action:
+							args.action === "PUSH" || args.action === "REPLACE"
+								? args.action
+								: "POP",
+					}),
+			});
+			return unblock;
+		},
+	};
+}

package/src/preset.ts

@@ -0,0 +1,51 @@
+export {
+	createApp,
+	panel,
+	type AppHandle,
+	type AppOptions,
+	type PanelHandle,
+	type PanelOptions,
+	type PanelHandlesOf,
+	type TypedAppHandle,
+	type ViewOptions,
+} from "./preset/builders.tsx";
+export { AppRootShell, useActiveStory, useInflate } from "./preset/app.tsx";
+export { deriveInflateChain } from "./preset/inflate.ts";
+export { useNavigator, type VkNavigator } from "./preset/navigator.ts";
+export { definePanel, panelRouteId, type PanelDefinition } from "./preset/define-panel.ts";
+export {
+	type ModalComponent,
+	type ModalDeclaration,
+	type ModalEntryComponent,
+} from "./preset/builders.tsx";
+export { defineView, type ViewDefinition } from "./preset/define-view.ts";
+
+// the batteries a mini app almost always needs, one import away
+export {
+	createVkHistory,
+	createBridgeSync,
+	createSwipeBackManager,
+	normalizeBridgeEvent,
+	type VkBridgeLike,
+} from "./index.ts";
+export {
+	Modals,
+	ModalPageSurface,
+	ModalCardSurface,
+	Popouts,
+	VkView,
+	NotFound,
+	useShowPopout,
+	useHidePopout,
+	usePopoutState,
+	type ModalEntry,
+} from "./vkui.ts";
+export {
+	usePanelParams,
+	usePanelSearch,
+	usePanelLoaderData,
+	useModalProps,
+	usePanelsHistory,
+	useEnableSwipeBack,
+	type PanelRef,
+} from "./react.ts";

package/src/react/hooks.ts

@@ -0,0 +1,168 @@
+import { useMatch, useRouter, useRouterState } from "@tanstack/react-router";
+import { useEffect, useRef } from "react";
+import { looseRouteOf } from "../core/loose-route.ts";
+import {
+	applyLocation,
+	initialPanelsStack,
+	type PanelsStackState,
+	panelsHistoryOf,
+} from "../core/panels-stack.ts";
+import { readModalState } from "../core/state-keys.ts";
+import { setSwipeBackOverride } from "../core/swipe-back.ts";
+
+/**
+ * The departing-panel freeze (spike 1): raw TanStack data hooks throw
+ * `Invariant failed: Could not find an active match` when the panel's
+ * route stops matching while VKUI still keeps the panel mounted during the
+ * back animation — the error flies past the router's error boundary and
+ * remounts the whole tree. These hooks never throw and retain the last
+ * resolved value while the panel is mounted but unmatched.
+ *
+ * Pass the TYPED panel handle (`app.panels["feed/post/$id"]`) — params /
+ * search / loaderData are derived from the panel's declared options
+ * (validateSearch return, loader return, $param path segments). A plain
+ * route-id string also works, with loose types.
+ */
+
+/**
+ * Structural twin of the preset's `PanelHandle` — the phantom `types`
+ * member carries the panel's data types without coupling this layer to
+ * the preset.
+ */
+export interface PanelRef<
+	TParams = Record<string, string>,
+	TSearch = Record<string, unknown>,
+	TLoaderData = unknown,
+> {
+	readonly routeId: string;
+	readonly types?: { params: TParams; search: TSearch; loaderData: TLoaderData };
+}
+
+export function useLastWhileUndefined<T>(value: T | undefined): T | undefined {
+	const ref = useRef(value);
+	if (value !== undefined) {
+		ref.current = value;
+	}
+	return value === undefined ? ref.current : value;
+}
+
+/** Shared body of the panel data hooks — they differ only in the match field. */
+function usePanelMatchField(
+	refOrFrom: PanelRef | string,
+	field: "params" | "search" | "loaderData",
+): unknown {
+	const routeId = typeof refOrFrom === "string" ? refOrFrom : refOrFrom.routeId;
+	const match = useMatch({ from: routeId, shouldThrow: false } as never);
+	return useLastWhileUndefined(
+		(match as unknown as Record<string, unknown> | undefined)?.[field],
+	);
+}
+
+export function usePanelParams<P extends Record<string, string>>(
+	ref: PanelRef<P | undefined, any, any>,
+): P;
+export function usePanelParams(from: string): Record<string, string>;
+export function usePanelParams(refOrFrom: PanelRef | string): unknown {
+	return usePanelMatchField(refOrFrom, "params") ?? {};
+}
+
+export function usePanelSearch<S>(ref: PanelRef<any, S | undefined, any>): S | undefined;
+export function usePanelSearch(from: string): Record<string, unknown>;
+export function usePanelSearch(refOrFrom: PanelRef | string): unknown {
+	return usePanelMatchField(refOrFrom, "search");
+}
+
+export function usePanelLoaderData<D>(ref: PanelRef<any, any, D | undefined>): D | undefined;
+export function usePanelLoaderData(from: string): unknown;
+export function usePanelLoaderData(refOrFrom: PanelRef | string): unknown {
+	return usePanelMatchField(refOrFrom, "loaderData");
+}
+
+/**
+ * Runtime props of the open modal — `showModal({ to, params, props })` /
+ * `showGlobalModal(id, { props })` stash them in `history.state` (so they
+ * survive reload and back/forward) and the modal entry component reads them
+ * here. Serializable values only (structured clone); same freeze semantics
+ * as the panel hooks — the departing modal keeps its last props while it
+ * animates out.
+ */
+export function useModalProps<T = unknown>(): T | undefined {
+	const modal = useRouterState({ select: state => readModalState(state.location.state) });
+	return useLastWhileUndefined(modal?.props) as T | undefined;
+}
+
+/**
+ * Mirror of the history stack in panel ids, driven by `__TSR_index`.
+ * Applies only when the router is idle — between the location commit and
+ * the match resolution there is an intermediate render with a stale
+ * activePanel (spike 1: `[home, home]` flash, self-healed by the
+ * replace-on-same-index rule).
+ */
+export function usePanelsStack(activePanel: string): PanelsStackState {
+	const snapshot = useRouterState({
+		select: state => ({
+			status: state.status,
+			index:
+				(state.location.state as { __TSR_index?: number } | undefined)?.__TSR_index ?? null,
+		}),
+	});
+	const ref = useRef<PanelsStackState>(initialPanelsStack());
+
+	if (snapshot.status === "idle") {
+		ref.current = applyLocation(ref.current, snapshot.index, activePanel);
+	}
+
+	return ref.current;
+}
+
+/** VKUI `View.history` prop: panels in open order. */
+export function usePanelsHistory(activePanel: string): string[] {
+	return panelsHistoryOf(usePanelsStack(activePanel));
+}
+
+/**
+ * The deepest matched panel's route id — what "the active panel" means
+ * when every panel is a permanently mounted static child.
+ */
+function useActivePanelRouteId(): string | null {
+	const router = useRouter();
+	return useRouterState({
+		select: (state): string | null => {
+			for (let i = state.matches.length - 1; i >= 0; i--) {
+				const routeId = state.matches[i]?.routeId;
+				if (routeId === undefined) {
+					continue;
+				}
+				if (looseRouteOf(router, routeId)?.options.staticData?.panel !== undefined) {
+					return routeId;
+				}
+			}
+			return null;
+		},
+	});
+}
+
+/**
+ * The old router's `useEnableSwipeBack`: override the automatic
+ * swipe-back decision while it applies. Panels are permanently mounted
+ * static children here, so pass the panel ref — the override applies only
+ * while that panel is the deepest matched one and is released when the
+ * user navigates away. Without a ref the override is app-global.
+ *
+ * `false` turns the native gesture off (drawing pads, drag surfaces);
+ * `true` forces it on even on the first entry (the system back then
+ * closes the app — you asked for it). `createSwipeBackManager({
+ * enabled: false })` is the hard opt-out that wins over this hook.
+ */
+export function useEnableSwipeBack(enabled: boolean, ref?: PanelRef | string): void {
+	const activeRouteId = useActivePanelRouteId();
+	const routeId = typeof ref === "string" ? ref : ref?.routeId;
+	const applies = ref === undefined ? true : routeId !== undefined && routeId === activeRouteId;
+	useEffect(() => {
+		if (!applies) {
+			return;
+		}
+		setSwipeBackOverride(enabled);
+		return () => setSwipeBackOverride(null);
+	}, [applies, enabled]);
+}

package/src/react.ts

@@ -0,0 +1,11 @@
+export {
+	useLastWhileUndefined,
+	usePanelParams,
+	usePanelSearch,
+	usePanelLoaderData,
+	useModalProps,
+	usePanelsStack,
+	usePanelsHistory,
+	useEnableSwipeBack,
+	type PanelRef,
+} from "./react/hooks.ts";