@vkma.dev/router 0.0.0-stage → 0.1.1

package/src/vkui/choreography.ts

@@ -0,0 +1,105 @@
+/**
+ * Modal choreography state machine — pure, React-free; the `<Modals>` host
+ * in `modals.tsx` drives it and completes exits from the surface's
+ * `onClosed`. One step per reconcile: every close is an animated exit whose
+ * completion triggers the next step. Route ids are hierarchical
+ * (`/view:feed/post/$id/comments`), so the nested/sibling relation is a
+ * string prefix check.
+ *
+ * - a SIBLING retarget (comments → share) closes the displayed sheet first
+ *   and opens the new one only after the exit completes — never two sibling
+ *   sheets at once (the user-reported bug from the first spike);
+ * - a NESTED open (the target is a child route of the displayed modal)
+ *   keeps the displayed sheet open and stacks the child ON TOP of it — two
+ *   open sheets by design; back unwinds the stack one level per entry;
+ * - back to the parent modal closes the top and reveals the parent.
+ *
+ * While an exit is in flight:
+ * - retargeting BACK to the exiting sheet CANCELS the exit — VKUI reverses
+ *   the transition mid-flight (`open` flips back to `true`), so there is no
+ *   close-then-reopen bounce;
+ * - any OTHER target is QUEUED: the state's `target` carries the LATEST
+ *   router request and the exit's completion re-reconciles toward it.
+ *   Dropping it would leave the host showing a modal the router no longer
+ *   matches, desynced until the next navigation.
+ */
+
+interface ChoreographyEntry {
+	/** Modal id — also the VKUI `nav`. */
+	id: string;
+	/** Full route id of the modal route. */
+	routeId: string;
+}
+
+export interface ChoreographyState<T extends ChoreographyEntry> {
+	/** the modal route that should be open on top right now */
+	target: T | null;
+	/** open entries, bottom → top (nested modals stack) */
+	stack: T[];
+	/** the entry animating out (mounted with open=false) */
+	exiting: T | null;
+	/** the exiting id whose `onClosed` completes the transition */
+	awaitingExitId: string | null;
+}
+
+export const idleChoreography = <T extends ChoreographyEntry>(): ChoreographyState<T> => ({
+	target: null,
+	stack: [],
+	exiting: null,
+	awaitingExitId: null,
+});
+
+export function reconcile<T extends ChoreographyEntry>(
+	previous: ChoreographyState<T>,
+	target: T | null,
+): ChoreographyState<T> {
+	if (previous.awaitingExitId !== null) {
+		const exiting = previous.exiting;
+		if (exiting !== null && target?.id === exiting.id) {
+			// retargeting the exiting sheet: CANCEL the exit and restore it
+			return {
+				...previous,
+				target,
+				stack: [...previous.stack, exiting],
+				exiting: null,
+				awaitingExitId: null,
+			};
+		}
+		// any other target mid-exit: queue it — the exit's completion
+		// (handleClosed) re-reconciles toward this latest request
+		return { ...previous, target };
+	}
+	const top = previous.stack[previous.stack.length - 1] ?? null;
+	if (top === null) {
+		return target === null
+			? { ...previous, target: null }
+			: { ...previous, target, stack: [target] };
+	}
+	if (target !== null && target.id === top.id) {
+		return { ...previous, target }; // already on top — settle
+	}
+	if (target !== null && target.routeId.startsWith(`${top.routeId}/`)) {
+		// NESTED open: the target is a child route of the displayed modal —
+		// keep it open and stack the child on top
+		return { ...previous, target, stack: [...previous.stack, target] };
+	}
+	if (target !== null && top.routeId.startsWith(`${target.routeId}/`)) {
+		// back to an ANCESTOR modal: close the top, the parent stays open
+		return {
+			...previous,
+			target,
+			stack: previous.stack.slice(0, -1),
+			exiting: top,
+			awaitingExitId: top.id,
+		};
+	}
+	// sibling/unrelated modal or close-everything: close the top first —
+	// the target opens when the exit completes
+	return {
+		...previous,
+		target,
+		stack: previous.stack.slice(0, -1),
+		exiting: top,
+		awaitingExitId: top.id,
+	};
+}

package/src/vkui/modals.tsx

@@ -0,0 +1,216 @@
+import { useRouterState } from "@tanstack/react-router";
+import { ModalCard, ModalPage, type ModalCardProps, type ModalPageProps } from "@vkontakte/vkui";
+import {
+	type ComponentType,
+	createContext,
+	type LazyExoticComponent,
+	Suspense,
+	useContext,
+	useEffect,
+	useState,
+} from "react";
+import { idleChoreography, reconcile, type ChoreographyState } from "./choreography.ts";
+
+/**
+ * Modal choreography host. The state machine lives in `choreography.ts`
+ * (pure — sibling closes first, nested stacks on top, back reveals the
+ * parent, retarget-during-exit cancels or queues). This host binds it to
+ * VKUI: exit completion is EVENT-DRIVEN — VKUI fires `onClosed` at the
+ * transition end and backs it with an internal timer computed from the
+ * element's real `transitionDuration` (adapts to platform/theme/reduced-
+ * motion — more accurate than any host-side constant). The host
+ * `exitDuration` is only a WATCHDOG for the one case VKUI cannot report:
+ * the modal unmounting before the exit finishes (its entry vanished from
+ * `entries`).
+ */
+
+/** A renderable modal entry component — plain or React.lazy. */
+export type ModalEntryComponent = ComponentType | LazyExoticComponent<ComponentType>;
+
+export interface ModalEntry {
+	/** Full route id of the modal route (e.g. `/item/$id/details`). */
+	routeId: string;
+	/** Modal id — also the VKUI `nav`. */
+	id: string;
+	/**
+	 * The modal content. Its root must be a ModalPageSurface or
+	 * ModalCardSurface — the host binds nav/open/close choreography to it
+	 * through context; the component owns every other prop at runtime.
+	 */
+	Component: ModalEntryComponent;
+}
+
+export interface ModalsProps {
+	entries: ModalEntry[];
+	/**
+	 * Watchdog bound for an exit whose `onClosed` never arrives (the modal
+	 * unmounted mid-animation), ms. Default 420 — well past any VKUI modal
+	 * exit animation; a healthy `onClosed` lands long before it fires.
+	 */
+	exitDuration?: number;
+}
+
+/** Host-bound surface controls, provided to every mounted modal entry. */
+interface ModalSurfaceApi {
+	nav: string;
+	open: boolean;
+	/** Another modal is stacked on top of this one — suppress the focus trap. */
+	stacked: boolean;
+	onClose: () => void;
+	onClosed: () => void;
+}
+
+const ModalSurfaceContext = createContext<ModalSurfaceApi | null>(null);
+
+function useModalSurface(): ModalSurfaceApi {
+	const api = useContext(ModalSurfaceContext);
+	if (api === null) {
+		throw new Error(
+			"[vkma-router] ModalPageSurface/ModalCardSurface must be the root of a modal entry rendered by <Modals>",
+		);
+	}
+	return api;
+}
+
+/**
+ * The host-owned keys VKUI actually accepts. Everything else in the api
+ * (`stacked` today, future host keys tomorrow) must NOT reach the spread —
+ * VKUI forwards unknown props to the DOM and React warns on booleans
+ * ("Received `false` for a non-boolean attribute `stacked`").
+ */
+export function hostProps(api: ModalSurfaceApi): {
+	nav: string;
+	open: boolean;
+	onClose: () => void;
+	onClosed: () => void;
+} {
+	const { nav, open, onClose, onClosed } = api;
+	return { nav, open, onClose, onClosed };
+}
+
+/** ModalPage surface for a modal entry — the host owns nav/open/close choreography. */
+export function ModalPageSurface({
+	children,
+	...surface
+}: Omit<ModalPageProps, "nav" | "open" | "onClose" | "onClosed" | "keepMounted">) {
+	const api = useModalSurface();
+	return (
+		<ModalPage
+			{...hostProps(api)}
+			keepMounted
+			disableFocusTrap={api.stacked || undefined}
+			{...surface}
+		>
+			{children}
+		</ModalPage>
+	);
+}
+
+/**
+ * ModalCard surface for a modal entry — same contract as
+ * ModalPageSurface, with the card's icon/title/description/actions as
+ * ordinary runtime props.
+ */
+export function ModalCardSurface({
+	children,
+	...surface
+}: Omit<ModalCardProps, "nav" | "open" | "onClose" | "onClosed" | "keepMounted">) {
+	const api = useModalSurface();
+	return (
+		<ModalCard
+			{...hostProps(api)}
+			keepMounted
+			disableFocusTrap={api.stacked || undefined}
+			{...surface}
+		>
+			{children}
+		</ModalCard>
+	);
+}
+
+export function Modals({ entries, exitDuration = 420 }: ModalsProps) {
+	const routeIds = new Set(entries.map(entry => entry.routeId));
+	const matchedModalEntry = useRouterState({
+		select: state => {
+			for (let i = state.matches.length - 1; i >= 0; i--) {
+				const routeId = state.matches[i]?.routeId;
+				if (routeId !== undefined && routeIds.has(routeId)) {
+					return entries.find(entry => entry.routeId === routeId) ?? null;
+				}
+			}
+			return null;
+		},
+	});
+	const globalModalId = useRouterState({
+		select: state => (state.location.search as { modal?: string } | undefined)?.modal ?? null,
+	});
+	const globalEntry =
+		globalModalId !== null ? (entries.find(entry => entry.id === globalModalId) ?? null) : null;
+	const target = matchedModalEntry ?? globalEntry;
+
+	const [state, setState] = useState<ChoreographyState<ModalEntry>>(() =>
+		reconcile(idleChoreography<ModalEntry>(), target),
+	);
+
+	// choreograph target changes (see reconcile)
+	useEffect(() => {
+		setState(previous => reconcile(previous, target));
+	}, [target]);
+
+	const handleClosed = (closedId: string): void => {
+		setState(previous => {
+			if (previous.awaitingExitId !== closedId) {
+				return previous; // stale or unexpected callback
+			}
+			const settled: ChoreographyState<ModalEntry> = {
+				...previous,
+				exiting: null,
+				awaitingExitId: null,
+			};
+			return reconcile(settled, settled.target);
+		});
+	};
+
+	// watchdog for the lost-onClosed case (unmount mid-exit); the dep set
+	// re-arms it on every new exit and cleans up on completion/unmount
+	useEffect(() => {
+		if (state.awaitingExitId === null) {
+			return;
+		}
+		const watchdog = setTimeout(
+			() => handleClosed(state.awaitingExitId as string),
+			exitDuration * 2,
+		);
+		return () => clearTimeout(watchdog);
+	}, [state.awaitingExitId, exitDuration]);
+
+	// render the open stack (bottom → top) plus the exiting sheet
+	const rendered: Array<{ entry: ModalEntry; open: boolean; stacked: boolean }> = [];
+	state.stack.forEach((entry, index) => {
+		rendered.push({ entry, open: true, stacked: index < state.stack.length - 1 });
+	});
+	if (state.exiting !== null && !state.stack.some(entry => entry.id === state.exiting?.id)) {
+		rendered.push({ entry: state.exiting, open: false, stacked: false });
+	}
+
+	return (
+		<>
+			{rendered.map(({ entry, open, stacked }) => (
+				<ModalSurfaceContext.Provider
+					key={entry.id}
+					value={{
+						nav: entry.id,
+						open,
+						stacked,
+						onClose: () => window.history.back(),
+						onClosed: () => handleClosed(entry.id),
+					}}
+				>
+					<Suspense fallback={null}>
+						<entry.Component />
+					</Suspense>
+				</ModalSurfaceContext.Provider>
+			))}
+		</>
+	);
+}

package/src/vkui/not-found.tsx

@@ -0,0 +1,21 @@
+import { Button, Placeholder } from "@vkontakte/vkui";
+
+/**
+ * Default 404 screen (parity with the old router's DefaultNotFound): wire it
+ * as `defaultNotFoundComponent` in `createRouter` — TanStack otherwise
+ * renders a bare `<p>Not Found</p>` and warns.
+ */
+export function NotFound(): React.ReactNode {
+	return (
+		<Placeholder
+			title="Страница не найдена"
+			action={
+				<Button size="l" onClick={() => window.history.back()}>
+					Назад
+				</Button>
+			}
+		>
+			Такой страницы не существует.
+		</Placeholder>
+	);
+}

package/src/vkui/popouts.tsx

@@ -0,0 +1,106 @@
+import { useRouter, useRouterState } from "@tanstack/react-router";
+import { type ComponentType } from "react";
+import { looseRouteOf } from "../core/loose-route.ts";
+import { POPOUT_STATE_KEY, readPopoutState } from "../core/state-keys.ts";
+
+/**
+ * Popouts are transient overlays, not routes: `history.state` holds
+ * `{ popout: id, props }`, so the native/system back closes them, and
+ * back/forward restores both the id and the props. Components come from
+ * the registry (per-panel and/or global — see the preset builders);
+ * `onClose` is injected by the host.
+ */
+
+export interface PopoutEntry {
+	id: string;
+	Component: ComponentType<{ onClose: () => void }>;
+	/**
+	 * The owning panel key (`${view}/${panel}`) for a panel-local popout —
+	 * it resolves only while that panel is the deepest matched one.
+	 * Undefined = global (resolves from any panel).
+	 */
+	panel?: string;
+}
+
+export function usePopoutState(): { id: string; props?: Record<string, unknown> } | undefined {
+	return useRouterState({ select: state => readPopoutState(state.location.state) });
+}
+
+/** `showPopout(id, props)` — pushes a popout entry; replaces if one is open. */
+export function useShowPopout(): (id: string, props?: Record<string, unknown>) => void {
+	const router = useRouter();
+	const isOpen = usePopoutState() !== undefined;
+	return (id, props) => {
+		void router.navigate({
+			href: router.state.location.href,
+			state: (previous: unknown) =>
+				({
+					...((previous ?? {}) as Record<string, unknown>),
+					[POPOUT_STATE_KEY]: { id, props },
+				}) as never,
+			replace: isOpen,
+		});
+	};
+}
+
+/** `hidePopout()` — unwinds the popout entry; on the first entry, strips in place. */
+export function useHidePopout(): () => void {
+	const router = useRouter();
+	return () => {
+		if (router.history.canGoBack()) {
+			router.history.back();
+			return;
+		}
+		const state = {
+			...(router.state.location.state as unknown as Record<string, unknown>),
+		};
+		delete state[POPOUT_STATE_KEY];
+		void router.navigate({
+			href: router.state.location.href,
+			replace: true,
+			state,
+		});
+	};
+}
+
+/** The deepest matched panel's registry key (`${view}/${panel}`), or null. */
+function useActivePanelKey(): 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;
+				}
+				const panel = looseRouteOf(router, routeId)?.options.staticData?.panel;
+				if (panel !== undefined) {
+					return panel;
+				}
+			}
+			return null;
+		},
+	});
+}
+
+export function Popouts({ entries }: { entries: PopoutEntry[] }) {
+	const popout = usePopoutState();
+	const hide = useHidePopout();
+	const activePanelKey = useActivePanelKey();
+	if (popout === undefined) {
+		return null;
+	}
+	// resolution local → global: the current panel's own popouts shadow the
+	// global registry
+	const entry =
+		entries.find(
+			candidate =>
+				candidate.panel !== undefined &&
+				candidate.panel === activePanelKey &&
+				candidate.id === popout.id,
+		) ?? entries.find(candidate => candidate.panel === undefined && candidate.id === popout.id);
+	if (!entry) {
+		return null;
+	}
+	return <entry.Component onClose={hide} />;
+}

package/src/vkui/vk-view.tsx

@@ -0,0 +1,147 @@
+import type { AnyRoute } from "@tanstack/react-router";
+import { useRouterState } from "@tanstack/react-router";
+import { Panel, Spinner, View } from "@vkontakte/vkui";
+import { type ComponentType } from "react";
+import { usePanelsHistory } from "../react/hooks.ts";
+
+export interface PanelStaticData {
+	panel: string;
+}
+
+export function panelIdOf(route: AnyRoute): string {
+	return (route.options.staticData as PanelStaticData | undefined)?.panel ?? "";
+}
+
+function deepestPanelMatchId(view: AnyRoute, matchedRouteIds: string[]): string {
+	const panelIds = new Set(view.children.map((child: AnyRoute) => child.id));
+	for (let i = matchedRouteIds.length - 1; i >= 0; i--) {
+		const id = matchedRouteIds[i];
+		if (id !== undefined && panelIds.has(id)) {
+			return id;
+		}
+	}
+	return view.children[0]?.id ?? "";
+}
+
+function useMatchSummaries(): string {
+	return useRouterState({
+		select: state =>
+			// routeId + status: a lazy panel's chunk resolution flips the match
+			// status, which must re-render the static children (the resolved
+			// component merges into route.options at that point)
+			state.matches.map(match => `${match.routeId}#${match.status}`).join("|"),
+	});
+}
+
+/**
+ * The VKUI nav key of a view route: "/view:feed" → "feed". Epic/Root match
+ * children by getNavId, so the raw route id would leak the route-tree
+ * convention into the UI layer. This is also the key the app author wrote
+ * in `defineView("feed")`.
+ */
+export function storyKeyOf(routeId: unknown): string {
+	const id = String(routeId);
+	return id.split(":")[1] ?? id;
+}
+
+export interface VkViewProps {
+	/** The pathless view layout route created by the preset. */
+	view: AnyRoute;
+	/** VKUI nav id of the View. Defaults to the story key (the defineView key). */
+	nav?: string;
+	/** Native swipe-back pop; defaults to `window.history.back()`. */
+	onSwipeBack?: () => void;
+}
+
+/**
+ * Static-children view: every panel route renders as an always-present JSX
+ * child of VKUI <View>; the router only feeds `activePanel` (and `history`
+ * for the iOS swipe-back). VKUI hides inactive panels itself and infers
+ * the animation direction from the children order — a plain <Outlet>
+ * breaks both. A lazy panel's `options.component` is undefined until its
+ * chunk resolves (TanStack merges loaded options in place), so the panel
+ * renders a spinner fallback until then. For the same reason TanStack's
+ * Outlet-driven `pendingComponent` swap never happens on its own — while
+ * the panel's match is pending (loader/beforeLoad), the route's
+ * `pendingComponent` renders instead of the component.
+ */
+export function VkView({ view, nav, onSwipeBack }: VkViewProps) {
+	useMatchSummaries();
+	const matchedRouteIds = useRouterState({
+		select: state => state.matches.map(match => match.routeId),
+	});
+	// structurally-compared array — TanStack keeps the reference stable when
+	// the selection is deep-equal. TanStack's Outlet would swap in the
+	// route's pendingComponent itself, but static children render the
+	// component directly, so the swap is ours to make while the loader runs
+	const pendingRouteIds = useRouterState({
+		select: state =>
+			state.matches
+				.filter(match => (match as { status?: string }).status === "pending")
+				.map(match => String(match.routeId)),
+	});
+	// a notFound match (notFound() from beforeLoad/validateSearch) must NOT
+	// render its panel component: the component's data guards assume a valid
+	// match, and the shell renders the NotFound screen for this navigation —
+	// the panel itself stays invisible. Without the gate the component would
+	// throw in a transient render and dirty the console on every cold 404
+	const notFoundRouteIds = useRouterState({
+		select: state =>
+			state.matches
+				.filter(match => (match as { status?: string }).status === "notFound")
+				.map(match => String(match.routeId)),
+	});
+	const activeRouteId = deepestPanelMatchId(view, matchedRouteIds);
+	const activeChild =
+		view.children.find((child: AnyRoute) => child.id === activeRouteId) ?? view.children[0];
+	const activePanel = activeChild ? panelIdOf(activeChild) : "";
+
+	const history = usePanelsHistory(activePanel);
+
+	return (
+		<View
+			nav={nav ?? storyKeyOf(view.id)}
+			activePanel={activePanel}
+			history={history}
+			onSwipeBack={onSwipeBack ?? (() => window.history.back())}
+		>
+			{view.children.map((child: AnyRoute) => {
+				const id = panelIdOf(child);
+				const Component = child.options.component as ComponentType | undefined;
+				const Pending = child.options.pendingComponent as ComponentType | undefined;
+				const isPending = pendingRouteIds.includes(String(child.id));
+				const isNotFound = notFoundRouteIds.includes(String(child.id));
+				// pending without a pendingComponent renders the FALLBACK, never
+				// the component: a lazy chunk may have already merged its
+				// component while the match is still pending (or parked on a
+				// notFound boundary up the tree) — the component's data guards
+				// assume a resolvable match and would throw in a hidden panel
+				return (
+					<Panel key={id} nav={id}>
+						{isPending ? (
+							Pending !== undefined ? (
+								<Pending />
+							) : (
+								<PanelSpinnerFallback />
+							)
+						) : isNotFound ? (
+							<PanelSpinnerFallback />
+						) : Component ? (
+							<Component />
+						) : (
+							<PanelSpinnerFallback />
+						)}
+					</Panel>
+				);
+			})}
+		</View>
+	);
+}
+
+function PanelSpinnerFallback() {
+	return (
+		<div style={{ paddingTop: 64, textAlign: "center" }}>
+			<Spinner size="l" />
+		</div>
+	);
+}

package/src/vkui.ts

@@ -0,0 +1,17 @@
+export { VkView, panelIdOf, type VkViewProps } from "./vkui/vk-view.tsx";
+export {
+	Modals,
+	ModalPageSurface,
+	ModalCardSurface,
+	type ModalEntry,
+	type ModalEntryComponent,
+	type ModalsProps,
+} from "./vkui/modals.tsx";
+export {
+	Popouts,
+	usePopoutState,
+	useShowPopout,
+	useHidePopout,
+	type PopoutEntry,
+} from "./vkui/popouts.tsx";
+export { NotFound } from "./vkui/not-found.tsx";

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.