@vkma.dev/router 0.1.2 → 0.1.4

package/dist/preset/link.d.ts

@@ -0,0 +1,52 @@
+import { PanelPage } from "./navigator.js";
+import { CSSProperties, ComponentType, MouseEvent, ReactNode } from "react";
+//#region src/preset/link.d.ts
+/**
+ * Router-link props on top of a Page object — the typed counterpart of
+ * `navigator.push(page, params)`. The `page` is a panel definition/handle
+ * (its phantom `types.params` drives the `params` prop type).
+ */
+export interface VkLinkProps<TParams extends Record<string, string> = Record<string, string>> {
+  /** The typed page target: a panel definition/handle or a bare PanelPage. */
+  page: PanelPage<TParams>;
+  /** Path params — required for pages with `$param` segments. */
+  params?: TParams;
+  /**
+   * Route preload trigger. Default `"intent"` — hover/focus on desktop,
+   * touchstart on mobile: the chunk (and loader data) is fetched BEFORE
+   * the tap, so the arriving panel paints instantly.
+   */
+  preload?: false | "intent" | "render" | "viewport";
+  /** Replace the history entry instead of pushing (tab/tabbar switches). */
+  replace?: boolean;
+  children?: ReactNode;
+  className?: string;
+  style?: CSSProperties;
+  title?: string;
+  target?: string;
+  rel?: string;
+  disabled?: boolean;
+  "aria-label"?: string;
+  onClick?: (event: MouseEvent<HTMLAnchorElement>) => void;
+}
+/**
+ * Turn ANY component (a VKUI `CellButton`, `RichCell`, your own button)
+ * into a router link: client-side navigation plus route preloading on
+ * hover/focus/touchstart (`preload="intent"` by default — the chunk and
+ * loader data are fetched BEFORE the tap). Targets are the typed Page
+ * objects `navigator.push` accepts:
+ *
+ * ```tsx
+ * const CellButtonLink = createVkLink(CellButton);
+ *
+ * <CellButtonLink page={postPanel} params={{ id: "1" }}>Открыть</CellButtonLink>
+ * ```
+ *
+ * The host component receives the anchor `href` plus the navigation and
+ * preload handlers — VKUI buttons/cells spread unknown props onto their
+ * interactive element, so no extra wiring is needed. A custom `onClick`
+ * composes with the navigation handler (yours first, then navigate).
+ */
+export declare function createVkLink<TCompProps>(Comp: ComponentType<TCompProps>): <TParams extends Record<string, string>>(props: TCompProps & VkLinkProps<TParams>) => ReactNode;
+//#endregion
+//# sourceMappingURL=link.d.ts.map

package/dist/preset/link.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"link.d.ts","names":[],"sources":["../../src/preset/link.tsx"],"mappings":";;;;;;;;iBAeiB,YAAY,gBAAgB,yBAAyB;;EAErE,MAAM,UAAU;;EAEhB,SAAS;;;;;;EAMT;;EAEA;EACA,WAAW;EACX;EACA,QAAQ;EACR;EACA;EACA;EACA;EACA;EACA,WAAW,OAAO,WAAW;;;;;;;;;;;;;;;;;;;;wBAgDd,aAAa,YAC5B,MAAM,cAAc,eACjB,gBAAgB,wBAAwB,OAAO,aAAa,YAAY,aAAa"}

package/dist/preset/link.js

@@ -0,0 +1,49 @@
+import { useLinkProps } from "@tanstack/react-router";
+import { createElement } from "react";
+//#region src/preset/link.tsx
+/** `"index"` and an optional leading slash normalize to the router path (navigator parity). */
+function vkLinkTarget(page) {
+	return page.path === "index" ? "/" : `/${page.path.replace(/^\//, "")}`;
+}
+/**
+* Turn ANY component (a VKUI `CellButton`, `RichCell`, your own button)
+* into a router link: client-side navigation plus route preloading on
+* hover/focus/touchstart (`preload="intent"` by default — the chunk and
+* loader data are fetched BEFORE the tap). Targets are the typed Page
+* objects `navigator.push` accepts:
+*
+* ```tsx
+* const CellButtonLink = createVkLink(CellButton);
+*
+* <CellButtonLink page={postPanel} params={{ id: "1" }}>Открыть</CellButtonLink>
+* ```
+*
+* The host component receives the anchor `href` plus the navigation and
+* preload handlers — VKUI buttons/cells spread unknown props onto their
+* interactive element, so no extra wiring is needed. A custom `onClick`
+* composes with the navigation handler (yours first, then navigate).
+*/
+function createVkLink(Comp) {
+	return function VkLink(props) {
+		const { page, params, preload = "intent", replace, onClick, ...host } = props;
+		const options = {
+			to: vkLinkTarget(page),
+			params,
+			preload,
+			replace
+		};
+		const anchor = useLinkProps(options);
+		return createElement(Comp, {
+			...host,
+			...anchor,
+			onClick: (event) => {
+				onClick?.(event);
+				if (!event.defaultPrevented) anchor.onClick?.(event);
+			}
+		});
+	};
+}
+//#endregion
+export { createVkLink, vkLinkTarget };
+
+//# sourceMappingURL=link.js.map

package/dist/preset/link.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"link.js","names":[],"sources":["../../src/preset/link.tsx"],"sourcesContent":["import { useLinkProps, type UseLinkPropsOptions } from \"@tanstack/react-router\";\nimport {\n\tcreateElement,\n\ttype ComponentType,\n\ttype CSSProperties,\n\ttype MouseEvent,\n\ttype ReactNode,\n} from \"react\";\nimport { type PanelPage } from \"./navigator.ts\";\n\n/**\n * Router-link props on top of a Page object — the typed counterpart of\n * `navigator.push(page, params)`. The `page` is a panel definition/handle\n * (its phantom `types.params` drives the `params` prop type).\n */\nexport interface VkLinkProps<TParams extends Record<string, string> = Record<string, string>> {\n\t/** The typed page target: a panel definition/handle or a bare PanelPage. */\n\tpage: PanelPage<TParams>;\n\t/** Path params — required for pages with `$param` segments. */\n\tparams?: TParams;\n\t/**\n\t * Route preload trigger. Default `\"intent\"` — hover/focus on desktop,\n\t * touchstart on mobile: the chunk (and loader data) is fetched BEFORE\n\t * the tap, so the arriving panel paints instantly.\n\t */\n\tpreload?: false | \"intent\" | \"render\" | \"viewport\";\n\t/** Replace the history entry instead of pushing (tab/tabbar switches). */\n\treplace?: boolean;\n\tchildren?: ReactNode;\n\tclassName?: string;\n\tstyle?: CSSProperties;\n\ttitle?: string;\n\ttarget?: string;\n\trel?: string;\n\tdisabled?: boolean;\n\t\"aria-label\"?: string;\n\tonClick?: (event: MouseEvent<HTMLAnchorElement>) => void;\n}\n\n/** `\"index\"` and an optional leading slash normalize to the router path (navigator parity). */\nexport function vkLinkTarget(page: PanelPage): string {\n\treturn page.path === \"index\" ? \"/\" : `/${page.path.replace(/^\\//, \"\")}`;\n}\n\nexport interface SplitVkLinkProps {\n\tto: string;\n\tparams?: Record<string, string>;\n\tpreload: false | \"intent\" | \"render\" | \"viewport\";\n\treplace?: boolean;\n\thost: Record<string, unknown>;\n}\n\n/** Pure props slicing: router options vs what the host component receives. */\nexport function splitVkLinkProps<TParams extends Record<string, string>>(\n\tprops: VkLinkProps<TParams>,\n): SplitVkLinkProps {\n\tconst { page, params, preload = \"intent\", replace, ...host } = props;\n\treturn {\n\t\tto: vkLinkTarget(page),\n\t\tparams,\n\t\tpreload,\n\t\treplace,\n\t\thost: host as Record<string, unknown>,\n\t};\n}\n\n/**\n * Turn ANY component (a VKUI `CellButton`, `RichCell`, your own button)\n * into a router link: client-side navigation plus route preloading on\n * hover/focus/touchstart (`preload=\"intent\"` by default — the chunk and\n * loader data are fetched BEFORE the tap). Targets are the typed Page\n * objects `navigator.push` accepts:\n *\n * ```tsx\n * const CellButtonLink = createVkLink(CellButton);\n *\n * <CellButtonLink page={postPanel} params={{ id: \"1\" }}>Открыть</CellButtonLink>\n * ```\n *\n * The host component receives the anchor `href` plus the navigation and\n * preload handlers — VKUI buttons/cells spread unknown props onto their\n * interactive element, so no extra wiring is needed. A custom `onClick`\n * composes with the navigation handler (yours first, then navigate).\n */\nexport function createVkLink<TCompProps>(\n\tComp: ComponentType<TCompProps>,\n): <TParams extends Record<string, string>>(props: TCompProps & VkLinkProps<TParams>) => ReactNode {\n\treturn function VkLink<TParams extends Record<string, string>>(\n\t\tprops: TCompProps & VkLinkProps<TParams>,\n\t): ReactNode {\n\t\tconst { page, params, preload = \"intent\", replace, onClick, ...host } = props;\n\t\tconst options: UseLinkPropsOptions = {\n\t\t\tto: vkLinkTarget(page),\n\t\t\tparams,\n\t\t\tpreload,\n\t\t\treplace,\n\t\t} as UseLinkPropsOptions;\n\t\tconst anchor = useLinkProps(options);\n\t\treturn createElement(Comp, {\n\t\t\t...host,\n\t\t\t...anchor,\n\t\t\tonClick: (event: MouseEvent<HTMLAnchorElement>) => {\n\t\t\t\tonClick?.(event);\n\t\t\t\t// TanStack's handler preventDefaults and navigates client-side\n\t\t\t\tif (!event.defaultPrevented) {\n\t\t\t\t\tanchor.onClick?.(event);\n\t\t\t\t}\n\t\t\t},\n\t\t} as TCompProps);\n\t};\n}\n"],"mappings":";;;;AAwCA,SAAgB,aAAa,MAAyB;CACrD,OAAO,KAAK,SAAS,UAAU,MAAM,IAAI,KAAK,KAAK,QAAQ,OAAO,EAAE;AACrE;;;;;;;;;;;;;;;;;;;AA0CA,SAAgB,aACf,MACkG;CAClG,OAAO,SAAS,OACf,OACY;EACZ,MAAM,EAAE,MAAM,QAAQ,UAAU,UAAU,SAAS,SAAS,GAAG,SAAS;EACxE,MAAM,UAA+B;GACpC,IAAI,aAAa,IAAI;GACrB;GACA;GACA;EACD;EACA,MAAM,SAAS,aAAa,OAAO;EACnC,OAAO,cAAc,MAAM;GAC1B,GAAG;GACH,GAAG;GACH,UAAU,UAAyC;IAClD,UAAU,KAAK;IAEf,IAAI,CAAC,MAAM,kBACV,OAAO,UAAU,KAAK;GAExB;EACD,CAAe;CAChB;AACD"}

package/dist/preset.d.ts

@@ -8,10 +8,11 @@ import { PanelDefinition, definePanel, panelRouteId } from "./preset/define-pane
 import { ViewDefinition, defineView } from "./preset/define-view.js";
 import { AppHandle, AppOptions, ModalComponent, ModalDeclaration, ModalEntryComponent, PanelHandle, PanelHandlesOf, PanelOptions, TypedAppHandle, ViewOptions, createApp, panel } from "./preset/builders.js";
 import { AppRootShell, useActiveStory, useInflate } from "./preset/app.js";
+import { PanelPage, VkNavigator, useNavigator } from "./preset/navigator.js";
+import { VkLinkProps, createVkLink } from "./preset/link.js";
 import { deriveInflateChain } from "./preset/inflate.js";
-import { VkNavigator, useNavigator } from "./preset/navigator.js";
-import { VkView } from "./vkui/vk-view.js";
+import { DefaultPanelPendingComponent, VkView } from "./vkui/vk-view.js";
 import { NotFound } from "./vkui/not-found.js";
 import "./vkui.js";
 import { PanelRef, useEnableSwipeBack, useModalProps, usePanelLoaderData, usePanelParams, usePanelSearch, usePanelsHistory } from "./react/hooks.js";
-export { type AppHandle, type AppOptions, AppRootShell, ModalCardSurface, type ModalComponent, type ModalDeclaration, type ModalEntry, type ModalEntryComponent, ModalPageSurface, Modals, NotFound, type PanelDefinition, type PanelHandle, type PanelHandlesOf, type PanelOptions, type PanelRef, Popouts, type TypedAppHandle, type ViewDefinition, type ViewOptions, type VkBridgeLike, type VkNavigator, VkView, createApp, createBridgeSync, createSwipeBackManager, createVkHistory, definePanel, defineView, deriveInflateChain, normalizeBridgeEvent, panel, panelRouteId, useActiveStory, useEnableSwipeBack, useHidePopout, useInflate, useModalProps, useNavigator, usePanelLoaderData, usePanelParams, usePanelSearch, usePanelsHistory, usePopoutState, useShowPopout };
+export { type AppHandle, type AppOptions, AppRootShell, DefaultPanelPendingComponent, ModalCardSurface, type ModalComponent, type ModalDeclaration, type ModalEntry, type ModalEntryComponent, ModalPageSurface, Modals, NotFound, type PanelDefinition, type PanelHandle, type PanelHandlesOf, type PanelOptions, type PanelPage, type PanelRef, Popouts, type TypedAppHandle, type ViewDefinition, type ViewOptions, type VkBridgeLike, type VkLinkProps, type VkNavigator, VkView, createApp, createBridgeSync, createSwipeBackManager, createVkHistory, createVkLink, definePanel, defineView, deriveInflateChain, normalizeBridgeEvent, panel, panelRouteId, useActiveStory, useEnableSwipeBack, useHidePopout, useInflate, useModalProps, useNavigator, usePanelLoaderData, usePanelParams, usePanelSearch, usePanelsHistory, usePopoutState, useShowPopout };

package/dist/preset.js

@@ -3,7 +3,7 @@ import { normalizeBridgeEvent } from "./core/bridge-like.js";
 import { createBridgeSync } from "./core/bridge-sync.js";
 import { createSwipeBackManager } from "./core/swipe-back.js";
 import { useEnableSwipeBack, useModalProps, usePanelLoaderData, usePanelParams, usePanelSearch, usePanelsHistory } from "./react/hooks.js";
-import { VkView } from "./vkui/vk-view.js";
+import { DefaultPanelPendingComponent, VkView } from "./vkui/vk-view.js";
 import { ModalCardSurface, ModalPageSurface, Modals } from "./vkui/modals.js";
 import { Popouts, useHidePopout, usePopoutState, useShowPopout } from "./vkui/popouts.js";
 import { NotFound } from "./vkui/not-found.js";
@@ -12,5 +12,6 @@ import { AppRootShell, useActiveStory, useInflate } from "./preset/app.js";
 import { definePanel, panelRouteId } from "./preset/define-panel.js";
 import { defineView } from "./preset/define-view.js";
 import { createApp, panel } from "./preset/builders.js";
+import { createVkLink } from "./preset/link.js";
 import { useNavigator } from "./preset/navigator.js";
-export { AppRootShell, ModalCardSurface, ModalPageSurface, Modals, NotFound, Popouts, VkView, createApp, createBridgeSync, createSwipeBackManager, createVkHistory, definePanel, defineView, deriveInflateChain, normalizeBridgeEvent, panel, panelRouteId, useActiveStory, useEnableSwipeBack, useHidePopout, useInflate, useModalProps, useNavigator, usePanelLoaderData, usePanelParams, usePanelSearch, usePanelsHistory, usePopoutState, useShowPopout };
+export { AppRootShell, DefaultPanelPendingComponent, ModalCardSurface, ModalPageSurface, Modals, NotFound, Popouts, VkView, createApp, createBridgeSync, createSwipeBackManager, createVkHistory, createVkLink, definePanel, defineView, deriveInflateChain, normalizeBridgeEvent, panel, panelRouteId, useActiveStory, useEnableSwipeBack, useHidePopout, useInflate, useModalProps, useNavigator, usePanelLoaderData, usePanelParams, usePanelSearch, usePanelsHistory, usePopoutState, useShowPopout };

package/dist/vkui/vk-view.d.ts

@@ -23,11 +23,23 @@ export interface VkViewProps {
  * 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
+ * renders a spinner fallback until then — but only after a short grace
+ * delay: a fast chunk load must not flash a spinner for a frame or two,
+ * the panel just fills in seamlessly. 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 declare function VkView({ view, nav, onSwipeBack }: VkViewProps): import("react").JSX.Element;
+/**
+ * The canonical pending screen for a panel: a header stub keeps the layout
+ * structure while the lazy chunk is in flight, and PanelSpinner centers
+ * itself inside the panel (a bare Spinner floats at the top of a void).
+ *
+ * `VkView` renders this whenever a chunk is genuinely absent past the grace
+ * delay (see the pending branches in the render above); pass it as a
+ * panel's `pendingComponent` to opt out of the grace delay instead.
+ */
+export declare function DefaultPanelPendingComponent(): import("react").JSX.Element;
 //#endregion
 //# sourceMappingURL=vk-view.d.ts.map

package/dist/vkui/vk-view.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vk-view.d.ts","names":[],"sources":["../../src/vkui/vk-view.tsx"],"mappings":";;wBAUgB,UAAU,OAAO;;;;;;;wBA+BjB,WAAW;iBAKV;;EAEhB,MAAM;;EAEN;;EAEA;;;;;;;;;;;;;;wBAee,SAAS,MAAM,KAAK,eAAe,8BAAW,IAAA"}
+{"version":3,"file":"vk-view.d.ts","names":[],"sources":["../../src/vkui/vk-view.tsx"],"mappings":";;wBAUgB,UAAU,OAAO;;;;;;;wBA+BjB,WAAW;iBAKV;;EAEhB,MAAM;;EAEN;;EAEA;;;;;;;;;;;;;;;;wBAiBe,SAAS,MAAM,KAAK,eAAe,8BAAW,IAAA;;;;;;;;;;wBA8G9C,gDAA4B,IAAA"}

package/dist/vkui/vk-view.js

@@ -1,5 +1,6 @@
 import { usePanelsHistory } from "../react/hooks.js";
 import { useRouterState } from "@tanstack/react-router";
+import { useEffect, useState } from "react";
 import { Panel, PanelHeader, PanelSpinner, View } from "@vkontakte/vkui";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 //#region src/vkui/vk-view.tsx
@@ -34,7 +35,9 @@ function storyKeyOf(routeId) {
 * 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
+* renders a spinner fallback until then — but only after a short grace
+* delay: a fast chunk load must not flash a spinner for a frame or two,
+* the panel just fills in seamlessly. 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.
@@ -42,7 +45,7 @@ function storyKeyOf(routeId) {
 function VkView({ view, nav, onSwipeBack }) {
 	useMatchSummaries();
 	const matchedRouteIds = useRouterState({ select: (state) => state.matches.map((match) => match.routeId) });
-	const pendingRouteIds = useRouterState({ select: (state) => state.matches.filter((match) => match.status === "pending").map((match) => String(match.routeId)) });
+	const stalledRouteIds = useStalledIds(useRouterState({ select: (state) => state.matches.filter((match) => match.status === "pending").map((match) => String(match.routeId)) }), 200);
 	const notFoundRouteIds = useRouterState({ select: (state) => state.matches.filter((match) => match.status === "notFound").map((match) => String(match.routeId)) });
 	const activeRouteId = deepestPanelMatchId(view, matchedRouteIds);
 	const activeChild = view.children.find((child) => child.id === activeRouteId) ?? view.children[0];
@@ -57,19 +60,66 @@ function VkView({ view, nav, onSwipeBack }) {
 			const id = panelIdOf(child);
 			const Component = child.options.component;
 			const Pending = child.options.pendingComponent;
-			const isPending = pendingRouteIds.includes(String(child.id));
+			const isPending = stalledRouteIds.includes(String(child.id));
 			const isNotFound = notFoundRouteIds.includes(String(child.id));
+			let content;
+			if (isNotFound) content = null;
+			else if (Component !== void 0) content = /* @__PURE__ */ jsx(Component, {});
+			else if (isPending && Pending !== void 0) content = /* @__PURE__ */ jsx(Pending, {});
+			else if (isPending) content = /* @__PURE__ */ jsx(DefaultPanelPendingComponent, {});
+			else content = /* @__PURE__ */ jsx(PanelHeader, {});
 			return /* @__PURE__ */ jsx(Panel, {
 				nav: id,
-				children: isPending ? Pending !== void 0 ? /* @__PURE__ */ jsx(Pending, {}) : /* @__PURE__ */ jsx(PanelSpinnerFallback, {}) : isNotFound ? /* @__PURE__ */ jsx(PanelSpinnerFallback, {}) : Component ? /* @__PURE__ */ jsx(Component, {}) : /* @__PURE__ */ jsx(PanelSpinnerFallback, {})
+				children: content
 			}, id);
 		})
 	});
 }
-function PanelSpinnerFallback() {
+/**
+* The canonical pending screen for a panel: a header stub keeps the layout
+* structure while the lazy chunk is in flight, and PanelSpinner centers
+* itself inside the panel (a bare Spinner floats at the top of a void).
+*
+* `VkView` renders this whenever a chunk is genuinely absent past the grace
+* delay (see the pending branches in the render above); pass it as a
+* panel's `pendingComponent` to opt out of the grace delay instead.
+*/
+function DefaultPanelPendingComponent() {
 	return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(PanelHeader, {}), /* @__PURE__ */ jsx(PanelSpinner, { size: "l" })] });
 }
+/**
+* The delayed-spinner gate: mirrors `pendingIds` but only after they have
+* stayed pending for `delayMs` continuously; clears the moment the pending
+* set empties. `pendingRouteIds` comes from a structurally-stable
+* `useRouterState` select — the reference only changes when the pending set
+* actually changes, so the timer legitimately resets per navigation.
+*/
+/**
+* The delayed-spinner gate: mirrors `pendingIds` but only after they have
+* stayed pending for `delayMs` continuously; clears the moment the pending
+* set empties. The state is a STRING KEY, not the array — array-typed state
+* set from an effect re-triggers renders (a fresh reference every time)
+* and loops; a key string with the React bail-out (same value → no
+* re-render) cannot. `key` is stable across re-renders as long as the
+* pending SET is the same, even if TanStack hands out a fresh array
+* reference per render.
+*/
+function useStalledIds(pendingIds, delayMs) {
+	const key = pendingIds.join("|");
+	const [stalledKey, setStalledKey] = useState("");
+	useEffect(() => {
+		if (key === "") {
+			setStalledKey((prev) => prev === "" ? prev : "");
+			return;
+		}
+		const timer = setTimeout(() => setStalledKey(key), delayMs);
+		return () => {
+			clearTimeout(timer);
+		};
+	}, [key, delayMs]);
+	return stalledKey === key && key !== "" ? pendingIds : [];
+}
 //#endregion
-export { VkView, panelIdOf, storyKeyOf };
+export { DefaultPanelPendingComponent, VkView, panelIdOf, storyKeyOf };
 
 //# sourceMappingURL=vk-view.js.map

package/dist/vkui/vk-view.js.map

@@ -1 +1 @@
-{"version":3,"file":"vk-view.js","names":[],"sources":["../../src/vkui/vk-view.tsx"],"sourcesContent":["import type { AnyRoute } from \"@tanstack/react-router\";\nimport { useRouterState } from \"@tanstack/react-router\";\nimport { Panel, PanelHeader, PanelSpinner, View } from \"@vkontakte/vkui\";\nimport { type ComponentType } from \"react\";\nimport { usePanelsHistory } from \"../react/hooks.ts\";\n\nexport interface PanelStaticData {\n\tpanel: string;\n}\n\nexport function panelIdOf(route: AnyRoute): string {\n\treturn (route.options.staticData as PanelStaticData | undefined)?.panel ?? \"\";\n}\n\nfunction deepestPanelMatchId(view: AnyRoute, matchedRouteIds: string[]): string {\n\tconst panelIds = new Set(view.children.map((child: AnyRoute) => child.id));\n\tfor (let i = matchedRouteIds.length - 1; i >= 0; i--) {\n\t\tconst id = matchedRouteIds[i];\n\t\tif (id !== undefined && panelIds.has(id)) {\n\t\t\treturn id;\n\t\t}\n\t}\n\treturn view.children[0]?.id ?? \"\";\n}\n\nfunction useMatchSummaries(): string {\n\treturn useRouterState({\n\t\tselect: state =>\n\t\t\t// routeId + status: a lazy panel's chunk resolution flips the match\n\t\t\t// status, which must re-render the static children (the resolved\n\t\t\t// component merges into route.options at that point)\n\t\t\tstate.matches.map(match => `${match.routeId}#${match.status}`).join(\"|\"),\n\t});\n}\n\n/**\n * The VKUI nav key of a view route: \"/view:feed\" → \"feed\". Epic/Root match\n * children by getNavId, so the raw route id would leak the route-tree\n * convention into the UI layer. This is also the key the app author wrote\n * in `defineView(\"feed\")`.\n */\nexport function storyKeyOf(routeId: unknown): string {\n\tconst id = String(routeId);\n\treturn id.split(\":\")[1] ?? id;\n}\n\nexport interface VkViewProps {\n\t/** The pathless view layout route created by the preset. */\n\tview: AnyRoute;\n\t/** VKUI nav id of the View. Defaults to the story key (the defineView key). */\n\tnav?: string;\n\t/** Native swipe-back pop; defaults to `window.history.back()`. */\n\tonSwipeBack?: () => void;\n}\n\n/**\n * Static-children view: every panel route renders as an always-present JSX\n * child of VKUI <View>; the router only feeds `activePanel` (and `history`\n * for the iOS swipe-back). VKUI hides inactive panels itself and infers\n * the animation direction from the children order — a plain <Outlet>\n * breaks both. A lazy panel's `options.component` is undefined until its\n * chunk resolves (TanStack merges loaded options in place), so the panel\n * renders a spinner fallback until then. For the same reason TanStack's\n * Outlet-driven `pendingComponent` swap never happens on its own — while\n * the panel's match is pending (loader/beforeLoad), the route's\n * `pendingComponent` renders instead of the component.\n */\nexport function VkView({ view, nav, onSwipeBack }: VkViewProps) {\n\tuseMatchSummaries();\n\tconst matchedRouteIds = useRouterState({\n\t\tselect: state => state.matches.map(match => match.routeId),\n\t});\n\t// structurally-compared array — TanStack keeps the reference stable when\n\t// the selection is deep-equal. TanStack's Outlet would swap in the\n\t// route's pendingComponent itself, but static children render the\n\t// component directly, so the swap is ours to make while the loader runs\n\tconst pendingRouteIds = useRouterState({\n\t\tselect: state =>\n\t\t\tstate.matches\n\t\t\t\t.filter(match => (match as { status?: string }).status === \"pending\")\n\t\t\t\t.map(match => String(match.routeId)),\n\t});\n\t// a notFound match (notFound() from beforeLoad/validateSearch) must NOT\n\t// render its panel component: the component's data guards assume a valid\n\t// match, and the shell renders the NotFound screen for this navigation —\n\t// the panel itself stays invisible. Without the gate the component would\n\t// throw in a transient render and dirty the console on every cold 404\n\tconst notFoundRouteIds = useRouterState({\n\t\tselect: state =>\n\t\t\tstate.matches\n\t\t\t\t.filter(match => (match as { status?: string }).status === \"notFound\")\n\t\t\t\t.map(match => String(match.routeId)),\n\t});\n\tconst activeRouteId = deepestPanelMatchId(view, matchedRouteIds);\n\tconst activeChild =\n\t\tview.children.find((child: AnyRoute) => child.id === activeRouteId) ?? view.children[0];\n\tconst activePanel = activeChild ? panelIdOf(activeChild) : \"\";\n\n\tconst history = usePanelsHistory(activePanel);\n\n\treturn (\n\t\t<View\n\t\t\tnav={nav ?? storyKeyOf(view.id)}\n\t\t\tactivePanel={activePanel}\n\t\t\thistory={history}\n\t\t\tonSwipeBack={onSwipeBack ?? (() => window.history.back())}\n\t\t>\n\t\t\t{view.children.map((child: AnyRoute) => {\n\t\t\t\tconst id = panelIdOf(child);\n\t\t\t\tconst Component = child.options.component as ComponentType | undefined;\n\t\t\t\tconst Pending = child.options.pendingComponent as ComponentType | undefined;\n\t\t\t\tconst isPending = pendingRouteIds.includes(String(child.id));\n\t\t\t\tconst isNotFound = notFoundRouteIds.includes(String(child.id));\n\t\t\t\t// pending without a pendingComponent renders the FALLBACK, never\n\t\t\t\t// the component: a lazy chunk may have already merged its\n\t\t\t\t// component while the match is still pending (or parked on a\n\t\t\t\t// notFound boundary up the tree) — the component's data guards\n\t\t\t\t// assume a resolvable match and would throw in a hidden panel\n\t\t\t\treturn (\n\t\t\t\t\t<Panel key={id} nav={id}>\n\t\t\t\t\t\t{isPending ? (\n\t\t\t\t\t\t\tPending !== undefined ? (\n\t\t\t\t\t\t\t\t<Pending />\n\t\t\t\t\t\t\t) : (\n\t\t\t\t\t\t\t\t<PanelSpinnerFallback />\n\t\t\t\t\t\t\t)\n\t\t\t\t\t\t) : isNotFound ? (\n\t\t\t\t\t\t\t<PanelSpinnerFallback />\n\t\t\t\t\t\t) : Component ? (\n\t\t\t\t\t\t\t<Component />\n\t\t\t\t\t\t) : (\n\t\t\t\t\t\t\t<PanelSpinnerFallback />\n\t\t\t\t\t\t)}\n\t\t\t\t\t</Panel>\n\t\t\t\t);\n\t\t\t})}\n\t\t</View>\n\t);\n}\n\nfunction PanelSpinnerFallback() {\n\t// The canonical VKUI loading screen: a header stub keeps the layout\n\t// structure while the lazy chunk is in flight, and PanelSpinner centers\n\t// itself inside the panel (a bare Spinner floats at the top of a void).\n\treturn (\n\t\t<>\n\t\t\t<PanelHeader />\n\t\t\t<PanelSpinner size=\"l\" />\n\t\t</>\n\t);\n}\n"],"mappings":";;;;;AAUA,SAAgB,UAAU,OAAyB;CAClD,OAAQ,MAAM,QAAQ,YAA4C,SAAS;AAC5E;AAEA,SAAS,oBAAoB,MAAgB,iBAAmC;CAC/E,MAAM,WAAW,IAAI,IAAI,KAAK,SAAS,KAAK,UAAoB,MAAM,EAAE,CAAC;CACzE,KAAK,IAAI,IAAI,gBAAgB,SAAS,GAAG,KAAK,GAAG,KAAK;EACrD,MAAM,KAAK,gBAAgB;EAC3B,IAAI,OAAO,KAAA,KAAa,SAAS,IAAI,EAAE,GACtC,OAAO;CAET;CACA,OAAO,KAAK,SAAS,EAAE,EAAE,MAAM;AAChC;AAEA,SAAS,oBAA4B;CACpC,OAAO,eAAe,EACrB,SAAQ,UAIP,MAAM,QAAQ,KAAI,UAAS,GAAG,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,CAAC,KAAK,GAAG,EACzE,CAAC;AACF;;;;;;;AAQA,SAAgB,WAAW,SAA0B;CACpD,MAAM,KAAK,OAAO,OAAO;CACzB,OAAO,GAAG,MAAM,GAAG,CAAC,CAAC,MAAM;AAC5B;;;;;;;;;;;;;AAuBA,SAAgB,OAAO,EAAE,MAAM,KAAK,eAA4B;CAC/D,kBAAkB;CAClB,MAAM,kBAAkB,eAAe,EACtC,SAAQ,UAAS,MAAM,QAAQ,KAAI,UAAS,MAAM,OAAO,EAC1D,CAAC;CAKD,MAAM,kBAAkB,eAAe,EACtC,SAAQ,UACP,MAAM,QACJ,QAAO,UAAU,MAA8B,WAAW,SAAS,CAAC,CACpE,KAAI,UAAS,OAAO,MAAM,OAAO,CAAC,EACtC,CAAC;CAMD,MAAM,mBAAmB,eAAe,EACvC,SAAQ,UACP,MAAM,QACJ,QAAO,UAAU,MAA8B,WAAW,UAAU,CAAC,CACrE,KAAI,UAAS,OAAO,MAAM,OAAO,CAAC,EACtC,CAAC;CACD,MAAM,gBAAgB,oBAAoB,MAAM,eAAe;CAC/D,MAAM,cACL,KAAK,SAAS,MAAM,UAAoB,MAAM,OAAO,aAAa,KAAK,KAAK,SAAS;CACtF,MAAM,cAAc,cAAc,UAAU,WAAW,IAAI;CAE3D,MAAM,UAAU,iBAAiB,WAAW;CAE5C,OACC,oBAAC,MAAD;EACC,KAAK,OAAO,WAAW,KAAK,EAAE;EACjB;EACJ;EACT,aAAa,sBAAsB,OAAO,QAAQ,KAAK;EAEtD,UAAA,KAAK,SAAS,KAAK,UAAoB;GACvC,MAAM,KAAK,UAAU,KAAK;GAC1B,MAAM,YAAY,MAAM,QAAQ;GAChC,MAAM,UAAU,MAAM,QAAQ;GAC9B,MAAM,YAAY,gBAAgB,SAAS,OAAO,MAAM,EAAE,CAAC;GAC3D,MAAM,aAAa,iBAAiB,SAAS,OAAO,MAAM,EAAE,CAAC;GAM7D,OACC,oBAAC,OAAD;IAAgB,KAAK;IACnB,UAAA,YACA,YAAY,KAAA,IACX,oBAAC,SAAD,CAAU,CAAA,IAEV,oBAAC,sBAAD,CAAuB,CAAA,IAErB,aACH,oBAAC,sBAAD,CAAuB,CAAA,IACpB,YACH,oBAAC,WAAD,CAAY,CAAA,IAEZ,oBAAC,sBAAD,CAAuB,CAAA;GAElB,GAdK,EAcL;EAET,CAAC;CACI,CAAA;AAER;AAEA,SAAS,uBAAuB;CAI/B,OACC,qBAAA,UAAA,EAAA,UAAA,CACC,oBAAC,aAAD,CAAc,CAAA,GACd,oBAAC,cAAD,EAAc,MAAK,IAAK,CAAA,CACvB,EAAA,CAAA;AAEJ"}
+{"version":3,"file":"vk-view.js","names":[],"sources":["../../src/vkui/vk-view.tsx"],"sourcesContent":["import type { AnyRoute } from \"@tanstack/react-router\";\nimport { useRouterState } from \"@tanstack/react-router\";\nimport { Panel, PanelHeader, PanelSpinner, View } from \"@vkontakte/vkui\";\nimport { useEffect, useState, type ComponentType, type ReactNode } from \"react\";\nimport { usePanelsHistory } from \"../react/hooks.ts\";\n\nexport interface PanelStaticData {\n\tpanel: string;\n}\n\nexport function panelIdOf(route: AnyRoute): string {\n\treturn (route.options.staticData as PanelStaticData | undefined)?.panel ?? \"\";\n}\n\nfunction deepestPanelMatchId(view: AnyRoute, matchedRouteIds: string[]): string {\n\tconst panelIds = new Set(view.children.map((child: AnyRoute) => child.id));\n\tfor (let i = matchedRouteIds.length - 1; i >= 0; i--) {\n\t\tconst id = matchedRouteIds[i];\n\t\tif (id !== undefined && panelIds.has(id)) {\n\t\t\treturn id;\n\t\t}\n\t}\n\treturn view.children[0]?.id ?? \"\";\n}\n\nfunction useMatchSummaries(): string {\n\treturn useRouterState({\n\t\tselect: state =>\n\t\t\t// routeId + status: a lazy panel's chunk resolution flips the match\n\t\t\t// status, which must re-render the static children (the resolved\n\t\t\t// component merges into route.options at that point)\n\t\t\tstate.matches.map(match => `${match.routeId}#${match.status}`).join(\"|\"),\n\t});\n}\n\n/**\n * The VKUI nav key of a view route: \"/view:feed\" → \"feed\". Epic/Root match\n * children by getNavId, so the raw route id would leak the route-tree\n * convention into the UI layer. This is also the key the app author wrote\n * in `defineView(\"feed\")`.\n */\nexport function storyKeyOf(routeId: unknown): string {\n\tconst id = String(routeId);\n\treturn id.split(\":\")[1] ?? id;\n}\n\nexport interface VkViewProps {\n\t/** The pathless view layout route created by the preset. */\n\tview: AnyRoute;\n\t/** VKUI nav id of the View. Defaults to the story key (the defineView key). */\n\tnav?: string;\n\t/** Native swipe-back pop; defaults to `window.history.back()`. */\n\tonSwipeBack?: () => void;\n}\n\n/**\n * Static-children view: every panel route renders as an always-present JSX\n * child of VKUI <View>; the router only feeds `activePanel` (and `history`\n * for the iOS swipe-back). VKUI hides inactive panels itself and infers\n * the animation direction from the children order — a plain <Outlet>\n * breaks both. A lazy panel's `options.component` is undefined until its\n * chunk resolves (TanStack merges loaded options in place), so the panel\n * renders a spinner fallback until then — but only after a short grace\n * delay: a fast chunk load must not flash a spinner for a frame or two,\n * the panel just fills in seamlessly. For the same reason TanStack's\n * Outlet-driven `pendingComponent` swap never happens on its own — while\n * the panel's match is pending (loader/beforeLoad), the route's\n * `pendingComponent` renders instead of the component.\n */\nexport function VkView({ view, nav, onSwipeBack }: VkViewProps) {\n\tuseMatchSummaries();\n\tconst matchedRouteIds = useRouterState({\n\t\tselect: state => state.matches.map(match => match.routeId),\n\t});\n\t// structurally-compared array — TanStack keeps the reference stable when\n\t// the selection is deep-equal. TanStack's Outlet would swap in the\n\t// route's pendingComponent itself, but static children render the\n\t// component directly, so the swap is ours to make while the loader runs\n\tconst pendingRouteIds = useRouterState({\n\t\tselect: state =>\n\t\t\tstate.matches\n\t\t\t\t.filter(match => (match as { status?: string }).status === \"pending\")\n\t\t\t\t.map(match => String(match.routeId)),\n\t});\n\t// The grace delay: a pending match only earns the spinner fallback after\n\t// staying pending for this long. Fast lazy-chunk loads (a warm cache, a\n\t// small bundle) resolve within a frame or two — flashing a spinner for\n\t// that blink makes every navigation feel broken; showing nothing and\n\t// letting the panel fill in seamlessly looks instant. Real loaders\n\t// outlive the delay and still get the fallback.\n\tconst stalledRouteIds = useStalledIds(pendingRouteIds, 200);\n\t// a notFound match (notFound() from beforeLoad/validateSearch) must NOT\n\t// render its panel component: the component's data guards assume a valid\n\t// match, and the shell renders the NotFound screen for this navigation —\n\t// the panel itself stays invisible. Without the gate the component would\n\t// throw in a transient render and dirty the console on every cold 404\n\tconst notFoundRouteIds = useRouterState({\n\t\tselect: state =>\n\t\t\tstate.matches\n\t\t\t\t.filter(match => (match as { status?: string }).status === \"notFound\")\n\t\t\t\t.map(match => String(match.routeId)),\n\t});\n\tconst activeRouteId = deepestPanelMatchId(view, matchedRouteIds);\n\tconst activeChild =\n\t\tview.children.find((child: AnyRoute) => child.id === activeRouteId) ?? view.children[0];\n\tconst activePanel = activeChild ? panelIdOf(activeChild) : \"\";\n\n\tconst history = usePanelsHistory(activePanel);\n\n\treturn (\n\t\t<View\n\t\t\tnav={nav ?? storyKeyOf(view.id)}\n\t\t\tactivePanel={activePanel}\n\t\t\thistory={history}\n\t\t\tonSwipeBack={onSwipeBack ?? (() => window.history.back())}\n\t\t>\n\t\t\t{view.children.map((child: AnyRoute) => {\n\t\t\t\tconst id = panelIdOf(child);\n\t\t\t\tconst Component = child.options.component as ComponentType | undefined;\n\t\t\t\tconst Pending = child.options.pendingComponent as ComponentType | undefined;\n\t\t\t\t// the grace-gated pending set (useStalledIds): a fast chunk load\n\t\t\t\t// never shows a spinner, the panel just fills in seamlessly\n\t\t\t\tconst isPending = stalledRouteIds.includes(String(child.id));\n\t\t\t\tconst isNotFound = notFoundRouteIds.includes(String(child.id));\n\t\t\t\t// A LOADED COMPONENT ALWAYS WINS — even while its match is still\n\t\t\t\t// pending. The fallback may only appear when the component is\n\t\t\t\t// genuinely absent (chunk not merged yet): replacing rendered\n\t\t\t\t// content with a spinner after it already appeared reads as\n\t\t\t\t// broken. (Panels reading route data through the /react hooks\n\t\t\t\t// are safe to render in a transient pending render; raw\n\t\t\t\t// TanStack data hooks are not — see the AGENTS invariants.)\n\t\t\t\tlet content: ReactNode;\n\t\t\t\tif (isNotFound) {\n\t\t\t\t\t// parked on a notFound boundary up the tree — the component's\n\t\t\t\t\t// data guards assume a resolvable match and would throw in a\n\t\t\t\t\t// hidden panel; the shell renders the NotFound screen anyway\n\t\t\t\t\tcontent = null;\n\t\t\t\t} else if (Component !== undefined) {\n\t\t\t\t\t// A LOADED COMPONENT ALWAYS WINS — even while its match is\n\t\t\t\t\t// still pending. The fallback may only appear when the\n\t\t\t\t\t// component is genuinely absent (chunk not merged yet):\n\t\t\t\t\t// replacing rendered content with a spinner after it already\n\t\t\t\t\t// appeared reads as broken. (Panels reading route data\n\t\t\t\t\t// through the /react hooks are safe to render in a transient\n\t\t\t\t\t// pending render; raw TanStack data hooks are not — see the\n\t\t\t\t\t// AGENTS invariants.)\n\t\t\t\t\tcontent = <Component />;\n\t\t\t\t} else if (isPending && Pending !== undefined) {\n\t\t\t\t\t// an explicit pendingComponent is deliberate — no grace delay\n\t\t\t\t\tcontent = <Pending />;\n\t\t\t\t} else if (isPending) {\n\t\t\t\t\tcontent = <DefaultPanelPendingComponent />;\n\t\t\t\t} else {\n\t\t\t\t\t// chunk in flight, inside the grace window: a header stub beats\n\t\t\t\t\t// a spinner that would flash for a blink — and beats an empty\n\t\t\t\t\t// panel: every panel SEPARATES with its own <PanelHeader>, so\n\t\t\t\t\t// the stub paints the final layout slot and the arriving\n\t\t\t\t\t// content fills in under it, nothing jumps\n\t\t\t\t\tcontent = <PanelHeader />;\n\t\t\t\t}\n\t\t\t\treturn (\n\t\t\t\t\t<Panel key={id} nav={id}>\n\t\t\t\t\t\t{content}\n\t\t\t\t\t</Panel>\n\t\t\t\t);\n\t\t\t})}\n\t\t</View>\n\t);\n}\n\n/**\n * The canonical pending screen for a panel: a header stub keeps the layout\n * structure while the lazy chunk is in flight, and PanelSpinner centers\n * itself inside the panel (a bare Spinner floats at the top of a void).\n *\n * `VkView` renders this whenever a chunk is genuinely absent past the grace\n * delay (see the pending branches in the render above); pass it as a\n * panel's `pendingComponent` to opt out of the grace delay instead.\n */\nexport function DefaultPanelPendingComponent() {\n\treturn (\n\t\t<>\n\t\t\t<PanelHeader />\n\t\t\t<PanelSpinner size=\"l\" />\n\t\t</>\n\t);\n}\n\n/**\n * The delayed-spinner gate: mirrors `pendingIds` but only after they have\n * stayed pending for `delayMs` continuously; clears the moment the pending\n * set empties. `pendingRouteIds` comes from a structurally-stable\n * `useRouterState` select — the reference only changes when the pending set\n * actually changes, so the timer legitimately resets per navigation.\n */\n/**\n * The delayed-spinner gate: mirrors `pendingIds` but only after they have\n * stayed pending for `delayMs` continuously; clears the moment the pending\n * set empties. The state is a STRING KEY, not the array — array-typed state\n * set from an effect re-triggers renders (a fresh reference every time)\n * and loops; a key string with the React bail-out (same value → no\n * re-render) cannot. `key` is stable across re-renders as long as the\n * pending SET is the same, even if TanStack hands out a fresh array\n * reference per render.\n */\nfunction useStalledIds(pendingIds: string[], delayMs: number): string[] {\n\tconst key = pendingIds.join(\"|\");\n\tconst [stalledKey, setStalledKey] = useState(\"\");\n\tuseEffect(() => {\n\t\tif (key === \"\") {\n\t\t\tsetStalledKey(prev => (prev === \"\" ? prev : \"\"));\n\t\t\treturn;\n\t\t}\n\t\tconst timer = setTimeout(() => setStalledKey(key), delayMs);\n\t\treturn () => {\n\t\t\tclearTimeout(timer);\n\t\t};\n\t}, [key, delayMs]);\n\treturn stalledKey === key && key !== \"\" ? pendingIds : [];\n}\n"],"mappings":";;;;;;AAUA,SAAgB,UAAU,OAAyB;CAClD,OAAQ,MAAM,QAAQ,YAA4C,SAAS;AAC5E;AAEA,SAAS,oBAAoB,MAAgB,iBAAmC;CAC/E,MAAM,WAAW,IAAI,IAAI,KAAK,SAAS,KAAK,UAAoB,MAAM,EAAE,CAAC;CACzE,KAAK,IAAI,IAAI,gBAAgB,SAAS,GAAG,KAAK,GAAG,KAAK;EACrD,MAAM,KAAK,gBAAgB;EAC3B,IAAI,OAAO,KAAA,KAAa,SAAS,IAAI,EAAE,GACtC,OAAO;CAET;CACA,OAAO,KAAK,SAAS,EAAE,EAAE,MAAM;AAChC;AAEA,SAAS,oBAA4B;CACpC,OAAO,eAAe,EACrB,SAAQ,UAIP,MAAM,QAAQ,KAAI,UAAS,GAAG,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,CAAC,KAAK,GAAG,EACzE,CAAC;AACF;;;;;;;AAQA,SAAgB,WAAW,SAA0B;CACpD,MAAM,KAAK,OAAO,OAAO;CACzB,OAAO,GAAG,MAAM,GAAG,CAAC,CAAC,MAAM;AAC5B;;;;;;;;;;;;;;;AAyBA,SAAgB,OAAO,EAAE,MAAM,KAAK,eAA4B;CAC/D,kBAAkB;CAClB,MAAM,kBAAkB,eAAe,EACtC,SAAQ,UAAS,MAAM,QAAQ,KAAI,UAAS,MAAM,OAAO,EAC1D,CAAC;CAiBD,MAAM,kBAAkB,cAZA,eAAe,EACtC,SAAQ,UACP,MAAM,QACJ,QAAO,UAAU,MAA8B,WAAW,SAAS,CAAC,CACpE,KAAI,UAAS,OAAO,MAAM,OAAO,CAAC,EACtC,CAOoD,GAAG,GAAG;CAM1D,MAAM,mBAAmB,eAAe,EACvC,SAAQ,UACP,MAAM,QACJ,QAAO,UAAU,MAA8B,WAAW,UAAU,CAAC,CACrE,KAAI,UAAS,OAAO,MAAM,OAAO,CAAC,EACtC,CAAC;CACD,MAAM,gBAAgB,oBAAoB,MAAM,eAAe;CAC/D,MAAM,cACL,KAAK,SAAS,MAAM,UAAoB,MAAM,OAAO,aAAa,KAAK,KAAK,SAAS;CACtF,MAAM,cAAc,cAAc,UAAU,WAAW,IAAI;CAE3D,MAAM,UAAU,iBAAiB,WAAW;CAE5C,OACC,oBAAC,MAAD;EACC,KAAK,OAAO,WAAW,KAAK,EAAE;EACjB;EACJ;EACT,aAAa,sBAAsB,OAAO,QAAQ,KAAK;EAEtD,UAAA,KAAK,SAAS,KAAK,UAAoB;GACvC,MAAM,KAAK,UAAU,KAAK;GAC1B,MAAM,YAAY,MAAM,QAAQ;GAChC,MAAM,UAAU,MAAM,QAAQ;GAG9B,MAAM,YAAY,gBAAgB,SAAS,OAAO,MAAM,EAAE,CAAC;GAC3D,MAAM,aAAa,iBAAiB,SAAS,OAAO,MAAM,EAAE,CAAC;GAQ7D,IAAI;GACJ,IAAI,YAIH,UAAU;QACJ,IAAI,cAAc,KAAA,GASxB,UAAU,oBAAC,WAAD,CAAY,CAAA;QAChB,IAAI,aAAa,YAAY,KAAA,GAEnC,UAAU,oBAAC,SAAD,CAAU,CAAA;QACd,IAAI,WACV,UAAU,oBAAC,8BAAD,CAA+B,CAAA;QAOzC,UAAU,oBAAC,aAAD,CAAc,CAAA;GAEzB,OACC,oBAAC,OAAD;IAAgB,KAAK;IACnB,UAAA;GACK,GAFK,EAEL;EAET,CAAC;CACI,CAAA;AAER;;;;;;;;;;AAWA,SAAgB,+BAA+B;CAC9C,OACC,qBAAA,UAAA,EAAA,UAAA,CACC,oBAAC,aAAD,CAAc,CAAA,GACd,oBAAC,cAAD,EAAc,MAAK,IAAK,CAAA,CACvB,EAAA,CAAA;AAEJ;;;;;;;;;;;;;;;;;;AAmBA,SAAS,cAAc,YAAsB,SAA2B;CACvE,MAAM,MAAM,WAAW,KAAK,GAAG;CAC/B,MAAM,CAAC,YAAY,iBAAiB,SAAS,EAAE;CAC/C,gBAAgB;EACf,IAAI,QAAQ,IAAI;GACf,eAAc,SAAS,SAAS,KAAK,OAAO,EAAG;GAC/C;EACD;EACA,MAAM,QAAQ,iBAAiB,cAAc,GAAG,GAAG,OAAO;EAC1D,aAAa;GACZ,aAAa,KAAK;EACnB;CACD,GAAG,CAAC,KAAK,OAAO,CAAC;CACjB,OAAO,eAAe,OAAO,QAAQ,KAAK,aAAa,CAAC;AACzD"}

package/dist/vkui.d.ts

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

package/dist/vkui.js

@@ -1,5 +1,5 @@
-import { VkView, panelIdOf, storyKeyOf } from "./vkui/vk-view.js";
+import { DefaultPanelPendingComponent, VkView, panelIdOf, storyKeyOf } from "./vkui/vk-view.js";
 import { ModalCardSurface, ModalPageSurface, Modals } from "./vkui/modals.js";
 import { Popouts, useHidePopout, usePopoutState, useShowPopout } from "./vkui/popouts.js";
 import { NotFound } from "./vkui/not-found.js";
-export { ModalCardSurface, ModalPageSurface, Modals, NotFound, Popouts, VkView, panelIdOf, storyKeyOf, useHidePopout, usePopoutState, useShowPopout };
+export { DefaultPanelPendingComponent, ModalCardSurface, ModalPageSurface, Modals, NotFound, Popouts, VkView, panelIdOf, storyKeyOf, useHidePopout, usePopoutState, useShowPopout };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vkma.dev/router",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "VK Mini Apps router on top of TanStack Router — VKUI views/panels/modals/popouts, VK history and bridge sync",
   "type": "module",
   "license": "MIT",

package/src/preset/link.tsx

@@ -0,0 +1,111 @@
+import { useLinkProps, type UseLinkPropsOptions } from "@tanstack/react-router";
+import {
+	createElement,
+	type ComponentType,
+	type CSSProperties,
+	type MouseEvent,
+	type ReactNode,
+} from "react";
+import { type PanelPage } from "./navigator.ts";
+
+/**
+ * Router-link props on top of a Page object — the typed counterpart of
+ * `navigator.push(page, params)`. The `page` is a panel definition/handle
+ * (its phantom `types.params` drives the `params` prop type).
+ */
+export interface VkLinkProps<TParams extends Record<string, string> = Record<string, string>> {
+	/** The typed page target: a panel definition/handle or a bare PanelPage. */
+	page: PanelPage<TParams>;
+	/** Path params — required for pages with `$param` segments. */
+	params?: TParams;
+	/**
+	 * Route preload trigger. Default `"intent"` — hover/focus on desktop,
+	 * touchstart on mobile: the chunk (and loader data) is fetched BEFORE
+	 * the tap, so the arriving panel paints instantly.
+	 */
+	preload?: false | "intent" | "render" | "viewport";
+	/** Replace the history entry instead of pushing (tab/tabbar switches). */
+	replace?: boolean;
+	children?: ReactNode;
+	className?: string;
+	style?: CSSProperties;
+	title?: string;
+	target?: string;
+	rel?: string;
+	disabled?: boolean;
+	"aria-label"?: string;
+	onClick?: (event: MouseEvent<HTMLAnchorElement>) => void;
+}
+
+/** `"index"` and an optional leading slash normalize to the router path (navigator parity). */
+export function vkLinkTarget(page: PanelPage): string {
+	return page.path === "index" ? "/" : `/${page.path.replace(/^\//, "")}`;
+}
+
+export interface SplitVkLinkProps {
+	to: string;
+	params?: Record<string, string>;
+	preload: false | "intent" | "render" | "viewport";
+	replace?: boolean;
+	host: Record<string, unknown>;
+}
+
+/** Pure props slicing: router options vs what the host component receives. */
+export function splitVkLinkProps<TParams extends Record<string, string>>(
+	props: VkLinkProps<TParams>,
+): SplitVkLinkProps {
+	const { page, params, preload = "intent", replace, ...host } = props;
+	return {
+		to: vkLinkTarget(page),
+		params,
+		preload,
+		replace,
+		host: host as Record<string, unknown>,
+	};
+}
+
+/**
+ * Turn ANY component (a VKUI `CellButton`, `RichCell`, your own button)
+ * into a router link: client-side navigation plus route preloading on
+ * hover/focus/touchstart (`preload="intent"` by default — the chunk and
+ * loader data are fetched BEFORE the tap). Targets are the typed Page
+ * objects `navigator.push` accepts:
+ *
+ * ```tsx
+ * const CellButtonLink = createVkLink(CellButton);
+ *
+ * <CellButtonLink page={postPanel} params={{ id: "1" }}>Открыть</CellButtonLink>
+ * ```
+ *
+ * The host component receives the anchor `href` plus the navigation and
+ * preload handlers — VKUI buttons/cells spread unknown props onto their
+ * interactive element, so no extra wiring is needed. A custom `onClick`
+ * composes with the navigation handler (yours first, then navigate).
+ */
+export function createVkLink<TCompProps>(
+	Comp: ComponentType<TCompProps>,
+): <TParams extends Record<string, string>>(props: TCompProps & VkLinkProps<TParams>) => ReactNode {
+	return function VkLink<TParams extends Record<string, string>>(
+		props: TCompProps & VkLinkProps<TParams>,
+	): ReactNode {
+		const { page, params, preload = "intent", replace, onClick, ...host } = props;
+		const options: UseLinkPropsOptions = {
+			to: vkLinkTarget(page),
+			params,
+			preload,
+			replace,
+		} as UseLinkPropsOptions;
+		const anchor = useLinkProps(options);
+		return createElement(Comp, {
+			...host,
+			...anchor,
+			onClick: (event: MouseEvent<HTMLAnchorElement>) => {
+				onClick?.(event);
+				// TanStack's handler preventDefaults and navigates client-side
+				if (!event.defaultPrevented) {
+					anchor.onClick?.(event);
+				}
+			},
+		} as TCompProps);
+	};
+}

package/src/preset.ts

@@ -10,8 +10,9 @@ export {
 	type ViewOptions,
 } from "./preset/builders.tsx";
 export { AppRootShell, useActiveStory, useInflate } from "./preset/app.tsx";
+export { createVkLink, type VkLinkProps } from "./preset/link.tsx";
 export { deriveInflateChain } from "./preset/inflate.ts";
-export { useNavigator, type VkNavigator } from "./preset/navigator.ts";
+export { useNavigator, type PanelPage, type VkNavigator } from "./preset/navigator.ts";
 export { definePanel, panelRouteId, type PanelDefinition } from "./preset/define-panel.ts";
 export {
 	type ModalComponent,
@@ -35,6 +36,7 @@ export {
 	Popouts,
 	VkView,
 	NotFound,
+	DefaultPanelPendingComponent,
 	useShowPopout,
 	useHidePopout,
 	usePopoutState,

package/src/vkui/vk-view.tsx

@@ -1,7 +1,7 @@
 import type { AnyRoute } from "@tanstack/react-router";
 import { useRouterState } from "@tanstack/react-router";
 import { Panel, PanelHeader, PanelSpinner, View } from "@vkontakte/vkui";
-import { type ComponentType } from "react";
+import { useEffect, useState, type ComponentType, type ReactNode } from "react";
 import { usePanelsHistory } from "../react/hooks.ts";
 
 export interface PanelStaticData {
@@ -60,7 +60,9 @@ export interface VkViewProps {
  * 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
+ * renders a spinner fallback until then — but only after a short grace
+ * delay: a fast chunk load must not flash a spinner for a frame or two,
+ * the panel just fills in seamlessly. 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.
@@ -80,6 +82,13 @@ export function VkView({ view, nav, onSwipeBack }: VkViewProps) {
 				.filter(match => (match as { status?: string }).status === "pending")
 				.map(match => String(match.routeId)),
 	});
+	// The grace delay: a pending match only earns the spinner fallback after
+	// staying pending for this long. Fast lazy-chunk loads (a warm cache, a
+	// small bundle) resolve within a frame or two — flashing a spinner for
+	// that blink makes every navigation feel broken; showing nothing and
+	// letting the panel fill in seamlessly looks instant. Real loaders
+	// outlive the delay and still get the fallback.
+	const stalledRouteIds = useStalledIds(pendingRouteIds, 200);
 	// 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 —
@@ -109,28 +118,49 @@ export function VkView({ view, nav, onSwipeBack }: VkViewProps) {
 				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));
+				// the grace-gated pending set (useStalledIds): a fast chunk load
+				// never shows a spinner, the panel just fills in seamlessly
+				const isPending = stalledRouteIds.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
+				// A LOADED COMPONENT ALWAYS WINS — even while its match is still
+				// pending. The fallback may only appear when the component is
+				// genuinely absent (chunk not merged yet): replacing rendered
+				// content with a spinner after it already appeared reads as
+				// broken. (Panels reading route data through the /react hooks
+				// are safe to render in a transient pending render; raw
+				// TanStack data hooks are not — see the AGENTS invariants.)
+				let content: ReactNode;
+				if (isNotFound) {
+					// parked on a notFound boundary up the tree — the component's
+					// data guards assume a resolvable match and would throw in a
+					// hidden panel; the shell renders the NotFound screen anyway
+					content = null;
+				} else if (Component !== undefined) {
+					// A LOADED COMPONENT ALWAYS WINS — even while its match is
+					// still pending. The fallback may only appear when the
+					// component is genuinely absent (chunk not merged yet):
+					// replacing rendered content with a spinner after it already
+					// appeared reads as broken. (Panels reading route data
+					// through the /react hooks are safe to render in a transient
+					// pending render; raw TanStack data hooks are not — see the
+					// AGENTS invariants.)
+					content = <Component />;
+				} else if (isPending && Pending !== undefined) {
+					// an explicit pendingComponent is deliberate — no grace delay
+					content = <Pending />;
+				} else if (isPending) {
+					content = <DefaultPanelPendingComponent />;
+				} else {
+					// chunk in flight, inside the grace window: a header stub beats
+					// a spinner that would flash for a blink — and beats an empty
+					// panel: every panel SEPARATES with its own <PanelHeader>, so
+					// the stub paints the final layout slot and the arriving
+					// content fills in under it, nothing jumps
+					content = <PanelHeader />;
+				}
 				return (
 					<Panel key={id} nav={id}>
-						{isPending ? (
-							Pending !== undefined ? (
-								<Pending />
-							) : (
-								<PanelSpinnerFallback />
-							)
-						) : isNotFound ? (
-							<PanelSpinnerFallback />
-						) : Component ? (
-							<Component />
-						) : (
-							<PanelSpinnerFallback />
-						)}
+						{content}
 					</Panel>
 				);
 			})}
@@ -138,10 +168,16 @@ export function VkView({ view, nav, onSwipeBack }: VkViewProps) {
 	);
 }
 
-function PanelSpinnerFallback() {
-	// The canonical VKUI loading screen: a header stub keeps the layout
-	// structure while the lazy chunk is in flight, and PanelSpinner centers
-	// itself inside the panel (a bare Spinner floats at the top of a void).
+/**
+ * The canonical pending screen for a panel: a header stub keeps the layout
+ * structure while the lazy chunk is in flight, and PanelSpinner centers
+ * itself inside the panel (a bare Spinner floats at the top of a void).
+ *
+ * `VkView` renders this whenever a chunk is genuinely absent past the grace
+ * delay (see the pending branches in the render above); pass it as a
+ * panel's `pendingComponent` to opt out of the grace delay instead.
+ */
+export function DefaultPanelPendingComponent() {
 	return (
 		<>
 			<PanelHeader />
@@ -149,3 +185,36 @@ function PanelSpinnerFallback() {
 		</>
 	);
 }
+
+/**
+ * The delayed-spinner gate: mirrors `pendingIds` but only after they have
+ * stayed pending for `delayMs` continuously; clears the moment the pending
+ * set empties. `pendingRouteIds` comes from a structurally-stable
+ * `useRouterState` select — the reference only changes when the pending set
+ * actually changes, so the timer legitimately resets per navigation.
+ */
+/**
+ * The delayed-spinner gate: mirrors `pendingIds` but only after they have
+ * stayed pending for `delayMs` continuously; clears the moment the pending
+ * set empties. The state is a STRING KEY, not the array — array-typed state
+ * set from an effect re-triggers renders (a fresh reference every time)
+ * and loops; a key string with the React bail-out (same value → no
+ * re-render) cannot. `key` is stable across re-renders as long as the
+ * pending SET is the same, even if TanStack hands out a fresh array
+ * reference per render.
+ */
+function useStalledIds(pendingIds: string[], delayMs: number): string[] {
+	const key = pendingIds.join("|");
+	const [stalledKey, setStalledKey] = useState("");
+	useEffect(() => {
+		if (key === "") {
+			setStalledKey(prev => (prev === "" ? prev : ""));
+			return;
+		}
+		const timer = setTimeout(() => setStalledKey(key), delayMs);
+		return () => {
+			clearTimeout(timer);
+		};
+	}, [key, delayMs]);
+	return stalledKey === key && key !== "" ? pendingIds : [];
+}

package/src/vkui.ts

@@ -1,4 +1,10 @@
-export { VkView, panelIdOf, storyKeyOf, type VkViewProps } from "./vkui/vk-view.tsx";
+export {
+	VkView,
+	DefaultPanelPendingComponent,
+	panelIdOf,
+	storyKeyOf,
+	type VkViewProps,
+} from "./vkui/vk-view.tsx";
 export {
 	Modals,
 	ModalPageSurface,