feat: replace loading spinners with skeletons

docs/UI-PATTERN.md

@@ -6,6 +6,8 @@
 
 Запросные экраны без успешных данных выбирают состояние в порядке loading, error, empty, loaded. Если query уже содержит данные, они остаются видимыми при фоновом refetch и его ошибке: рядом показываются неблокирующий progress и локальное предупреждение с retry. Такое состояние называется Client Cached Snapshot; оно не заменяет доменное server-side stale/fallback состояние.
 
+Initial loading без доступного результата использует page-owned structural skeleton, повторяющий semantic regions экрана (heading, cards, filters, summaries или rows), а не `StateView` или отдельный spinner. Partial loading принадлежит section view и занимает только ещё не загруженный блок. Skeleton region имеет доступное busy-обозначение, но его декоративные shapes не содержат данных, не интерактивны и не получают фокус. Route fallback сохраняет доступный application shell и skeleton-изирует content area; до auth `ready` public и protected guards показывают neutral shell skeleton. Button `loading` для mutation и compact progress при Client Cached Snapshot остаются контекстными indicators и не заменяются skeleton.
+
 Для finance-экранов используется граница `container -> ViewModel -> view`.
 `*.tsx` без суффикса — container: он вызывает единственный page VM hook и
 выбирает top-level Loading/Error/Empty/Loaded view. `*.vm.ts` владеет data

src/app/routes/AppRoutes.tsx

@@ -1,6 +1,7 @@
-import { Loader } from "@mantine/core";
+import { Container, Group, Skeleton, Stack } from "@mantine/core";
 import type { FC, PropsWithChildren } from "react";
 import { lazy, Suspense } from "react";
+import { useTranslation } from "react-i18next";
 import { Navigate, Route, Routes, useLocation } from "react-router";
 import { useAuth } from "@/features/auth";
 
@@ -41,17 +42,77 @@ const ProtectedLayout = lazy(async () => {
 	return { default: ProtectedLayout };
 });
 
-const LazyPage: FC<PropsWithChildren> = (props) => {
-	const { children } = props;
+type RouteSkeletonVariant = "auth" | "content" | "shell";
 
-	return <Suspense fallback={<Loader />}>{children}</Suspense>;
+type LazyPageProps = PropsWithChildren<{
+	variant: RouteSkeletonVariant;
+}>;
+
+const RouteSkeleton: FC<{ variant: RouteSkeletonVariant }> = (props) => {
+	const { variant } = props;
+	const { t } = useTranslation();
+
+	if (variant === "auth")
+		return (
+			<Container size={420} py="xl">
+				<Stack
+					aria-busy="true"
+					aria-label={t("states.loadingTitle")}
+					role="status"
+				>
+					<Skeleton height={32} width="45%" />
+					<Skeleton height={48} radius="sm" />
+					<Skeleton height={48} radius="sm" />
+					<Skeleton height={36} radius="sm" />
+				</Stack>
+			</Container>
+		);
+
+	if (variant === "shell")
+		return (
+			<Stack
+				aria-busy="true"
+				aria-label={t("states.loadingTitle")}
+				gap={0}
+				role="status"
+			>
+				<Group justify="space-between" p="md">
+					<Skeleton height={28} width={160} />
+					<Skeleton height={28} width={96} />
+				</Group>
+				<Container fluid p="md">
+					<Skeleton height={20} width="30%" />
+					<Stack mt="lg">
+						<Skeleton height={32} width="30%" />
+						<Skeleton height={160} radius="md" />
+					</Stack>
+				</Container>
+			</Stack>
+		);
+
+	return (
+		<Stack aria-busy="true" aria-label={t("states.loadingTitle")} role="status">
+			<Skeleton height={32} width="30%" />
+			<Skeleton height={160} radius="md" />
+		</Stack>
+	);
+};
+
+const LazyPage: FC<LazyPageProps> = (props) => {
+	const { children, variant } = props;
+
+	return (
+		<Suspense fallback={<RouteSkeleton variant={variant} />}>
+			{children}
+		</Suspense>
+	);
 };
 
 const Protected: FC<PropsWithChildren> = (props) => {
 	const { children } = props;
 	const { user, ready } = useAuth();
 	const location = useLocation();
-	if (!ready) return null;
+	if (!ready) return <RouteSkeleton variant="shell" />;
 	return user ? (
 		children
 	) : (
@@ -66,7 +127,7 @@ const Protected: FC<PropsWithChildren> = (props) => {
 const Public: FC<PropsWithChildren> = (props) => {
 	const { children } = props;
 	const { user, ready } = useAuth();
-	if (!ready) return null;
+	if (!ready) return <RouteSkeleton variant="shell" />;
 	return user ? <Navigate to="/accounts" replace /> : children;
 };
 
@@ -78,7 +139,7 @@ const AppRoutes: FC = () => {
 				path="/login"
 				element={
 					<Public>
-						<LazyPage>
+						<LazyPage variant="auth">
 							<LoginPage />
 						</LazyPage>
 					</Public>
@@ -88,7 +149,7 @@ const AppRoutes: FC = () => {
 				path="/register"
 				element={
 					<Public>
-						<LazyPage>
+						<LazyPage variant="auth">
 							<RegisterPage />
 						</LazyPage>
 					</Public>
@@ -97,7 +158,7 @@ const AppRoutes: FC = () => {
 			<Route
 				element={
 					<Protected>
-						<LazyPage>
+						<LazyPage variant="shell">
 							<ProtectedLayout />
 						</LazyPage>
 					</Protected>
@@ -106,7 +167,7 @@ const AppRoutes: FC = () => {
 				<Route
 					path="/accounts"
 					element={
-						<LazyPage>
+						<LazyPage variant="content">
 							<AccountsPage />
 						</LazyPage>
 					}
@@ -114,7 +175,7 @@ const AppRoutes: FC = () => {
 				<Route
 					path="/accounts/:accountId"
 					element={
-						<LazyPage>
+						<LazyPage variant="content">
 							<AccountPage />
 						</LazyPage>
 					}
@@ -122,7 +183,7 @@ const AppRoutes: FC = () => {
 				<Route
 					path="/accounts/:accountId/events"
 					element={
-						<LazyPage>
+						<LazyPage variant="content">
 							<AccountEventsPage />
 						</LazyPage>
 					}
@@ -130,7 +191,7 @@ const AppRoutes: FC = () => {
 				<Route
 					path="/accounts/:accountId/operations"
 					element={
-						<LazyPage>
+						<LazyPage variant="content">
 							<AccountOperationsPage />
 						</LazyPage>
 					}
@@ -138,7 +199,7 @@ const AppRoutes: FC = () => {
 				<Route
 					path="/settings"
 					element={
-						<LazyPage>
+						<LazyPage variant="content">
 							<SettingsPage />
 						</LazyPage>
 					}
@@ -147,7 +208,7 @@ const AppRoutes: FC = () => {
 			<Route
 				path="*"
 				element={
-					<LazyPage>
+					<LazyPage variant="content">
 						<NotFoundPage />
 					</LazyPage>
 				}

src/features/tbank-connection/ui/TbankConnectionSection.view.test.tsx

@@ -14,7 +14,10 @@ describe("TbankConnectionSection state views", () => {
 				<TbankConnectionLoading />
 			</MantineProvider>,
 		);
-		expect(screen.getByText("Пожалуйста, подождите.")).toBeInTheDocument();
+		expect(screen.getByRole("status", { name: "Загрузка" })).toHaveAttribute(
+			"aria-busy",
+			"true",
+		);
 		rerender(
 			<MantineProvider>
 				<TbankConnectionError retry={retry} />

src/features/tbank-connection/ui/TbankConnectionSection.view.tsx

@@ -1,6 +1,7 @@
-import { Alert, Button, Text } from "@mantine/core";
+import { Alert, Button, Skeleton } from "@mantine/core";
 import type { FC } from "react";
 import { useTranslation } from "react-i18next";
+import { LoadingSkeleton } from "@/shared/ui";
 
 type TbankConnectionErrorProps = {
 	retry: () => void;
@@ -8,7 +9,13 @@ type TbankConnectionErrorProps = {
 
 const TbankConnectionLoading: FC = () => {
 	const { t } = useTranslation();
-	return <Text>{t("states.loadingText")}</Text>;
+
+	return (
+		<LoadingSkeleton label={t("states.loadingTitle")}>
+			<Skeleton height={20} width="45%" />
+			<Skeleton height={36} width={140} radius="sm" />
+		</LoadingSkeleton>
+	);
 };
 
 const TbankConnectionError: FC<TbankConnectionErrorProps> = (props) => {

src/pages/account-events/ui/AccountEventsPage.test.tsx

@@ -94,4 +94,19 @@ describe("AccountEventsPage", () => {
 		screen.getByRole("button", { name: "Повторить" }).click();
 		expect(refetch).toHaveBeenCalledOnce();
 	});
+
+	it("shows a structural busy state before events are available", () => {
+		query.mockReturnValue({
+			data: undefined,
+			isError: false,
+			isLoading: true,
+			refetch: vi.fn(),
+		} as never);
+
+		renderPage();
+
+		const status = screen.getByRole("status", { name: "Загрузка" });
+		expect(status).toHaveAttribute("aria-busy", "true");
+		expect(status.querySelector("button")).toBeNull();
+	});
 });

src/pages/account-events/ui/AccountEventsPage.tsx

@@ -1,4 +1,12 @@
-import { Button, Card, Group, Stack, Text, Title } from "@mantine/core";
+import {
+	Button,
+	Card,
+	Group,
+	Skeleton,
+	Stack,
+	Text,
+	Title,
+} from "@mantine/core";
 import type { FC } from "react";
 import { useTranslation } from "react-i18next";
 import { useParams } from "react-router";
@@ -7,7 +15,7 @@ import {
 	useBrokerageEvents,
 } from "@/entities/brokerage-event";
 import { formatMoney } from "@/entities/portfolio";
-import { StateView } from "@/shared/ui";
+import { LoadingSkeleton, StateView } from "@/shared/ui";
 
 type AccountEventsPageErrorProps = {
 	retry: () => void;
@@ -36,11 +44,13 @@ const AccountEventsPageLoading: FC = () => {
 	const { t } = useTranslation();
 
 	return (
-		<StateView
-			loading
-			title={t("states.loadingTitle")}
-			text={t("states.loadingText")}
-		/>
+		<LoadingSkeleton label={t("states.loadingTitle")}>
+			<Skeleton height={32} width="40%" />
+			<Skeleton height={18} width="70%" />
+			{[0, 1, 2, 3].map((index) => (
+				<Skeleton key={index} height={82} radius="md" />
+			))}
+		</LoadingSkeleton>
 	);
 };
 

src/pages/account-operations/ui/components/AccountOperationsPageLoading.view.tsx

@@ -1,16 +1,29 @@
+import { Group, Skeleton, Stack } from "@mantine/core";
 import type { FC } from "react";
 import { useTranslation } from "react-i18next";
-import { StateView } from "@/shared/ui";
+import { LoadingSkeleton } from "@/shared/ui";
 
 const AccountOperationsPageLoading: FC = () => {
 	const { t } = useTranslation();
 
 	return (
-		<StateView
-			loading
-			title={t("states.loadingTitle")}
-			text={t("states.loadingText")}
-		/>
+		<LoadingSkeleton label={t("states.loadingTitle")}>
+			<Skeleton height={32} width="40%" />
+			<Group grow>
+				<Skeleton height={48} radius="sm" />
+				<Skeleton height={48} radius="sm" />
+			</Group>
+			<Skeleton height={48} radius="sm" />
+			<Group>
+				<Skeleton height={36} width={110} radius="sm" />
+				<Skeleton height={36} width={110} radius="sm" />
+			</Group>
+			<Stack gap="xs">
+				{[0, 1, 2, 3].map((index) => (
+					<Skeleton key={index} height={64} radius="md" />
+				))}
+			</Stack>
+		</LoadingSkeleton>
 	);
 };
 

src/pages/account/ui/AccountPage.view.tsx

@@ -1,11 +1,11 @@
-import { Accordion, Alert, Button, Stack, Text } from "@mantine/core";
+import { Accordion, Alert, Button, Skeleton, Stack, Text } from "@mantine/core";
 import type { FC } from "react";
 import { useTranslation } from "react-i18next";
 import { Link } from "react-router";
 import type { BrokerageAccount } from "@/entities/brokerage-account";
 import type { Portfolio } from "@/entities/portfolio";
 import { formatSnapshotTime } from "@/entities/portfolio";
-import { StateView } from "@/shared/ui";
+import { LoadingSkeleton, StateView } from "@/shared/ui";
 import classes from "./AccountPage.module.css";
 import type {
 	AccountPagePositionSection,
@@ -51,11 +51,13 @@ const AccountPageLoading: FC = () => {
 	const { t } = useTranslation();
 
 	return (
-		<StateView
-			loading
-			title={t("states.loadingTitle")}
-			text={t("states.loadingText")}
-		/>
+		<LoadingSkeleton label={t("states.loadingTitle")}>
+			<Skeleton height={32} width="35%" />
+			<Skeleton height={120} radius="md" />
+			{[0, 1, 2].map((index) => (
+				<Skeleton key={index} height={52} radius="sm" />
+			))}
+		</LoadingSkeleton>
 	);
 };
 

src/pages/account/ui/components/RecentEvents.view.tsx

@@ -1,9 +1,10 @@
-import { Alert, Button, Paper, Stack, Text } from "@mantine/core";
+import { Alert, Button, Paper, Skeleton, Stack, Text } from "@mantine/core";
 import type { FC } from "react";
 import { useTranslation } from "react-i18next";
 import { Link } from "react-router";
 import type { BrokerageEvent } from "@/entities/brokerage-event";
 import { formatMoney } from "@/entities/portfolio";
+import { LoadingSkeleton } from "@/shared/ui";
 import classes from "../AccountPage.module.css";
 import type { AccountPageRecentEvents } from "../AccountPage.vm";
 
@@ -22,7 +23,11 @@ const RecentEvents: FC<RecentEventsProps> = (props) => {
 	return (
 		<Stack gap="sm">
 			{events.state === "loading" ? (
-				<Text c="dimmed">{t("events.recentLoading")}</Text>
+				<LoadingSkeleton label={t("events.recentLoading")}>
+					{[0, 1, 2].map((index) => (
+						<Skeleton key={index} height={48} radius="sm" />
+					))}
+				</LoadingSkeleton>
 			) : null}
 			{events.state === "error" ? (
 				<Alert color="red">{t("events.recentError")}</Alert>

src/pages/account/ui/components/RecentOperations.view.tsx

@@ -1,8 +1,9 @@
-import { Alert, Button, Stack, Text } from "@mantine/core";
+import { Alert, Button, Skeleton, Stack, Text } from "@mantine/core";
 import type { FC } from "react";
 import { useTranslation } from "react-i18next";
 import { Link } from "react-router";
 import { LedgerEntryRow } from "@/entities/broker-operation";
+import { LoadingSkeleton } from "@/shared/ui";
 import type { AccountPageRecentOperations } from "../AccountPage.vm";
 
 type RecentOperationsProps = {
@@ -16,7 +17,11 @@ const RecentOperations: FC<RecentOperationsProps> = (props) => {
 	return (
 		<Stack gap="sm">
 			{operations.state === "loading" ? (
-				<Text c="dimmed">{t("ledger.recentLoading")}</Text>
+				<LoadingSkeleton label={t("ledger.recentLoading")}>
+					{[0, 1, 2].map((index) => (
+						<Skeleton key={index} height={48} radius="sm" />
+					))}
+				</LoadingSkeleton>
 			) : null}
 			{operations.state === "error" ? (
 				<Alert color="red">{t("ledger.recentError")}</Alert>

src/pages/accounts/ui/AccountsPage.view.tsx

@@ -3,6 +3,7 @@ import {
 	Button,
 	Group,
 	Loader,
+	Skeleton,
 	Stack,
 	Text,
 	Title,
@@ -12,7 +13,7 @@ import { useTranslation } from "react-i18next";
 import { Link } from "react-router";
 import type { BrokerageAccountCard } from "@/entities/brokerage-account";
 import { BrokerageAccountList } from "@/entities/brokerage-account";
-import { StateView } from "@/shared/ui";
+import { LoadingSkeleton, StateView } from "@/shared/ui";
 
 type AccountsPageErrorProps = {
 	code?: string;
@@ -42,11 +43,12 @@ const AccountsPageLoading: FC = () => {
 	const { t } = useTranslation();
 
 	return (
-		<StateView
-			loading
-			title={t("states.loadingTitle")}
-			text={t("states.loadingText")}
-		/>
+		<LoadingSkeleton label={t("states.loadingTitle")}>
+			<Skeleton height={32} width="30%" />
+			{[0, 1, 2].map((index) => (
+				<Skeleton key={index} height={116} radius="md" />
+			))}
+		</LoadingSkeleton>
 	);
 };
 

src/shared/ui/LoadingSkeleton.tsx

@@ -0,0 +1,18 @@
+import { Stack } from "@mantine/core";
+import type { FC, PropsWithChildren } from "react";
+
+type LoadingSkeletonProps = PropsWithChildren<{
+	label: string;
+}>;
+
+const LoadingSkeleton: FC<LoadingSkeletonProps> = (props) => {
+	const { children, label } = props;
+
+	return (
+		<Stack aria-busy="true" aria-label={label} gap="md" role="status">
+			{children}
+		</Stack>
+	);
+};
+
+export { LoadingSkeleton };

src/shared/ui/StateView.test.tsx

@@ -1,21 +1,25 @@
 import { MantineProvider } from "@mantine/core";
 import { cleanup, render, screen } from "@testing-library/react";
 import { afterEach, describe, expect, it } from "vitest";
+import { LoadingSkeleton } from "./LoadingSkeleton";
 import { StateView } from "./StateView";
 
 describe("StateView", () => {
 	afterEach(cleanup);
 
-	it("renders an accessible loading state with a loader", () => {
+	it("renders an accessible structural loading region", () => {
 		render(
 			<MantineProvider>
-				<StateView loading text="Пожалуйста, подождите." title="Загрузка" />
+				<LoadingSkeleton label="Загрузка">
+					<div />
+				</LoadingSkeleton>
 			</MantineProvider>,
 		);
 
-		const status = screen.getByRole("status");
-		expect(status).toHaveTextContent("Загрузка");
-		expect(screen.getByLabelText("Загрузка")).toBeInTheDocument();
+		expect(screen.getByRole("status", { name: "Загрузка" })).toHaveAttribute(
+			"aria-busy",
+			"true",
+		);
 	});
 
 	it("renders an accessible error state", () => {

src/shared/ui/StateView.tsx

@@ -1,22 +1,20 @@
-import { Button, Loader, Paper, Stack, Text, Title } from "@mantine/core";
+import { Button, Paper, Stack, Text, Title } from "@mantine/core";
 import type { FC, ReactNode } from "react";
 
 type StateViewProps = {
 	title: string;
 	text: string;
 	action?: ReactNode;
-	loading?: boolean;
 	error?: boolean;
 };
 
 const StateView: FC<StateViewProps> = (props) => {
-	const { title, text, action, loading = false, error = false } = props;
-	const role = loading ? "status" : error ? "alert" : undefined;
+	const { title, text, action, error = false } = props;
+	const role = error ? "alert" : undefined;
 
 	return (
 		<Paper p="xl" radius="md" shadow="xs" withBorder role={role}>
 			<Stack align="flex-start" gap="sm">
-				{loading ? <Loader aria-label={title} size="sm" /> : null}
 				<Title order={2}>{title}</Title>
 				<Text c="dimmed">{text}</Text>
 				{action}

src/shared/ui/index.ts

@@ -1,2 +1,3 @@
 export { AppShell } from "./AppShell";
+export { LoadingSkeleton } from "./LoadingSkeleton";
 export { Button, StateView } from "./StateView";