@quark-fw/plugin-react 0.1.2

package/package.json

@@ -0,0 +1,50 @@
+{
+	"name": "@quark-fw/plugin-react",
+	"version": "0.1.2",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"type": "module",
+	"scripts": {
+		"dev": "tsx watch src/index.ts",
+		"build": "echo raw-src package, no build"
+	},
+	"files": [
+		"src"
+	],
+	"keywords": [
+		"quark"
+	],
+	"author": "",
+	"license": "ISC",
+	"description": "React SSR frontend plugin for the Quark framework (published as raw TS sources; consumers run tsx + vite)",
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"@mantine/core": "^8.3.18",
+		"@quark-fw/atom": "0.1.2",
+		"@quark-fw/plugin": "0.1.2",
+		"@quark-fw/store": "0.1.2",
+		"@trpc/client": "^11.0.0",
+		"@mantine/dates": "^8.3.18",
+		"@mantine/modals": "^8.3.18",
+		"@mantine/notifications": "^8.3.18",
+		"@types/react-dom": "^19.2.3",
+		"@vitejs/plugin-react": "^5.1.4",
+		"express": "^5.2.1",
+		"react": "^19.2.4",
+		"react-dom": "^19.2.4",
+		"react-router-dom": "^7.13.2",
+		"vite": "^7.3.1",
+		"vite-css-modules": "^1.13.0",
+		"vite-plugin-svgr": "^4.5.0",
+		"vite-tsconfig-paths": "^6.1.1"
+	},
+	"peerDependencies": {
+		"@quark-fw/core": "0.1.2"
+	},
+	"devDependencies": {
+		"@types/express": "^5.0.6",
+		"@types/react": "^19.2.14"
+	}
+}

package/src/Router/ErrorPage.tsx

@@ -0,0 +1,18 @@
+type ErrorPageProps = {
+	code?: number;
+	description?: string;
+};
+function ErrorPage({ code = 404, description }: ErrorPageProps) {
+	return (
+		<div>
+			<div>
+				<h1>{code}</h1>
+			</div>
+			<div>
+				<span>{description}</span>
+			</div>
+		</div>
+	);
+}
+
+export default ErrorPage;

package/src/Router/Router.tsx

@@ -0,0 +1,178 @@
+import {
+	memo,
+	ReactNode,
+	startTransition,
+	Suspense,
+	useEffect,
+	useMemo,
+	useState,
+	type ComponentType,
+} from "react";
+import { matchPath, useLocation } from "react-router-dom";
+import ErrorPage from "./ErrorPage.js";
+import { getRenderPath } from "./getRenderPath.js";
+import { ErrorHandler } from "../frontend/ErrorHandler.js";
+import { UglyModule, ViteModulesEager } from "./gatherPages.js";
+import { Loader } from "@mantine/core";
+
+export type UglyPageProps = {
+	pathname: string;
+	params: Record<string, string>;
+	breadCrumbs: ReactNode | null;
+};
+
+export type UglyLayoutProps = UglyPageProps & {
+	children: ReactNode;
+};
+
+function PageComponentRenderer({
+	children,
+	Component,
+	...restProps
+}: {
+	children?: ReactNode;
+	Component: ComponentType<Record<string, unknown>>;
+	// остальное — пропсы страницы, их состав задаёт приложение
+	[key: string]: unknown;
+}) {
+	return <Component {...restProps}>{children}</Component>;
+}
+
+const MemoPageComponentRenderer = memo(
+	PageComponentRenderer,
+	(prevProps, nextProps) =>
+		prevProps.pathname === nextProps.pathname &&
+		JSON.stringify(prevProps.params) === JSON.stringify(nextProps.params),
+);
+
+function UglyModuleRenderer({
+	viteModules,
+	renderPath,
+	depth,
+	pathname,
+	children,
+}: {
+	renderPath: UglyModule[];
+	depth: number;
+	pathname: string;
+	viteModules?: ViteModulesEager;
+	children: ReactNode;
+}) {
+	const uglyModule = renderPath[depth]!;
+
+	if (!uglyModule) return children;
+	const PageComponent = uglyModule?.getWrappedPromise()?.default;
+
+	if (!PageComponent) return children;
+
+	const routeProps = matchPath(
+		{
+			path: uglyModule!.urlPath
+				.replace("layoutreset/", "")
+				.replace("layout/", ""),
+			end: false,
+			caseSensitive: false,
+		},
+		pathname,
+	);
+
+	return (
+		<ErrorHandler>
+			<Suspense fallback={<Loader />}>
+				<MemoPageComponentRenderer
+					Component={PageComponent}
+					pathname={pathname}
+					params={routeProps?.params}
+				>
+					<ErrorHandler>
+						<Suspense fallback={<Loader />}>
+							<MemoUglyModuleRenderer
+								pathname={pathname}
+								viteModules={viteModules}
+								renderPath={renderPath}
+								depth={depth + 1}
+							>
+								<ErrorHandler>{children}</ErrorHandler>
+							</MemoUglyModuleRenderer>
+						</Suspense>
+					</ErrorHandler>
+				</MemoPageComponentRenderer>
+			</Suspense>
+		</ErrorHandler>
+	);
+}
+
+const MemoUglyModuleRenderer = memo(
+	UglyModuleRenderer,
+	(prevProps, nextProps) => prevProps.pathname === nextProps.pathname,
+);
+
+function PageNotFound() {
+	const Component = ErrorPage;
+	return <Component code={404} />;
+}
+
+function UglyRouter({
+	viteModules,
+	registerModule,
+}: {
+	viteModules?: ViteModulesEager;
+	registerModule: (module: UglyModule) => void;
+}) {
+	const { pathname } = useLocation();
+
+	const [newRenderPath, newRenderPathKey] = useMemo(() => {
+		const { path, hasPage: _hasPage } = getRenderPath(pathname);
+		path.forEach(registerModule);
+		return [
+			path,
+			`${pathname};${path.map((p) => p.urlPath).join(";")}`,
+			_hasPage,
+		];
+		// registerModule приходит пропсом и пересоздаётся на каждый рендер
+		// родителя: с ним путь пересобирался бы вхолостую на каждый рендер
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [pathname]);
+
+	const [renderPath, setRenderPath] = useState(newRenderPath);
+	const [currentPathname, setCurrentPathname] = useState(pathname);
+
+	useEffect(() => {
+		const loadPathModules = async () => {
+			if (newRenderPath !== renderPath) {
+				await Promise.all(
+					newRenderPath.map(async (uglyModule) => uglyModule.load()),
+				);
+				startTransition(() => {
+					setRenderPath(newRenderPath);
+					setCurrentPathname(pathname);
+					if (pathname !== currentPathname) {
+						window.scrollTo({ top: 0 /*, behavior: 'smooth'*/ });
+					}
+				});
+			}
+		};
+
+		void loadPathModules();
+		// Эффект намеренно завязан на КЛЮЧ пути, а не на сами значения:
+		// newRenderPath — новый массив на каждый рендер, а renderPath и
+		// currentPathname этот же эффект и меняет. С ними он перезапускал бы
+		// сам себя.
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [newRenderPathKey]);
+
+	return (
+		<ErrorHandler>
+			<MemoUglyModuleRenderer
+				viteModules={viteModules}
+				renderPath={renderPath}
+				depth={0}
+				pathname={currentPathname}
+			>
+				<PageNotFound />
+			</MemoUglyModuleRenderer>
+		</ErrorHandler>
+	);
+}
+
+export { UglyRouter };

package/src/Router/gatherPages.ts

@@ -0,0 +1,165 @@
+/// <reference types="vite/client" />
+import React from "react";
+import { usePromise } from "../utils/usePromise.js";
+
+/*
+ * usePromise вызывается из класса-загрузчика, а не из компонента: чтение
+ * модуля происходит в теле рендера страницы, поэтому порядок вызовов совпадает
+ * с порядком рендеров. Ответственность за это на роутере, который читает
+ * страницу безусловно.
+ */
+/* eslint-disable react-hooks/rules-of-hooks */
+
+/**
+ * Модуль страницы. Пропсы страниц описывает роутер (UglyPageProps), но
+ * загрузчик их не разбирает — ему важно лишь, что это компонент.
+ */
+export type TPageModule = {
+	default: React.ComponentType<Record<string, unknown>>;
+};
+
+type TUrlPath = string;
+type TModulePath = string;
+type TFilePath = string;
+
+export type ViteModules = {
+	[key: TModulePath]: () => Promise<TPageModule>;
+};
+
+export type ViteModulesEager = {
+	[key: TModulePath]: TPageModule;
+};
+
+const pages: ViteModules = import.meta.glob<TPageModule>("/Pages/**/Page.*");
+const layouts: ViteModules = import.meta.glob<TPageModule>(
+	"/Pages/**/Layout.*",
+);
+const resetLayouts: ViteModules = import.meta.glob<TPageModule>(
+	"/Pages/**/LayoutReset.*",
+);
+
+const getMeta = (modulePath: TModulePath): [TFilePath, TUrlPath] => {
+	const filePath = modulePath.replace(/^\/Pages/, "").replace(/(\.tsx)$/, "");
+	let urlPath = (
+		filePath.endsWith("/Page")
+			? filePath.replace(/Page$/, "")
+			: `${filePath}/`
+	)
+		.replace(/\[\.{3}.+\]/, "*")
+		.replaceAll(/\[(.[^[]+)\]/g, ":$1")
+		.toLowerCase();
+
+	urlPath = urlPath === "/main/" ? "/" : urlPath;
+
+	return [filePath, urlPath];
+};
+
+export class UglyModule {
+	modulePath: string;
+
+	moduleImport: () => Promise<TPageModule>;
+
+	module?: TPageModule;
+
+	loadingPromise?: Promise<TPageModule>;
+
+	wrappedPromise?: () => TPageModule;
+
+	filePath: string;
+
+	urlPath: string;
+
+	constructor({
+		moduleImport,
+		modulePath,
+		module,
+	}: {
+		moduleImport: () => Promise<TPageModule>;
+		modulePath: TModulePath;
+		module?: TPageModule;
+	}) {
+		this.modulePath = modulePath;
+		this.moduleImport = moduleImport;
+		this.module = module;
+		// this.loadingPromise;
+		const [filePath, urlPath] = getMeta(modulePath);
+		this.filePath = filePath;
+		this.urlPath = urlPath;
+	}
+
+	getWrappedPromise(force?: TPageModule) {
+		if (!this.module && !force) {
+			if (!this.wrappedPromise) {
+				if (!this.loadingPromise) {
+					this.loadingPromise = new Promise((resolve) => {
+						try {
+							this.moduleImport().then((module) =>
+								resolve(module),
+							);
+						} catch (e) {
+							console.error(e);
+						}
+					});
+				}
+				this.wrappedPromise = usePromise(this.loadingPromise);
+			}
+
+			return this.wrappedPromise();
+		}
+		this.wrappedPromise = usePromise(
+			new Promise((resolve) => {
+				resolve(this.module! || force);
+			}),
+		);
+		return this.module;
+	}
+
+	async load() {
+		if (!this.module) {
+			if (!this.loadingPromise) {
+				this.loadingPromise = new Promise((resolve) => {
+					try {
+						this.moduleImport().then((module) => resolve(module));
+					} catch (e) {
+						console.error(e);
+					}
+				});
+			}
+		}
+
+		this.module = await this.loadingPromise;
+
+		return this.module;
+	}
+}
+
+export const createUglyModules = (modules: ViteModules | ViteModulesEager) =>
+	Object.keys(modules).reduce(
+		(acc, modulePath) => {
+			const moduleImport = modules[modulePath];
+			if (typeof moduleImport === "object") {
+				acc[modulePath] = new UglyModule({
+					modulePath,
+					module: moduleImport,
+					moduleImport: () =>
+						new Promise<TPageModule>((resolve) =>
+							resolve(moduleImport),
+						),
+				});
+			} else {
+				acc[modulePath] = new UglyModule({
+					modulePath,
+					moduleImport: moduleImport!,
+				});
+			}
+
+			return acc;
+		},
+		{} as Record<TModulePath, UglyModule>,
+	);
+
+const uglyPages = createUglyModules(pages);
+const uglyLayouts = createUglyModules(layouts);
+const uglyResetLayouts = createUglyModules(resetLayouts);
+
+export { uglyPages, uglyLayouts, uglyResetLayouts };

package/src/Router/getMatchedRoute.ts

@@ -0,0 +1,24 @@
+import { matchPath } from "react-router-dom";
+import { uglyPages, UglyModule } from "./gatherPages.js";
+
+export function getMatchedRoute(
+	url: string,
+	uglyModules = uglyPages,
+): UglyModule | undefined {
+	let exactRoute;
+
+	Object.keys(uglyModules).find((modulePath) => {
+		const uglyPage = uglyModules[modulePath]!;
+
+		const isMatched = matchPath(uglyPage.urlPath, url);
+
+		if (isMatched) {
+			exactRoute = uglyPage;
+			return true;
+		}
+
+		return false;
+	});
+
+	return exactRoute;
+}

package/src/Router/getRenderPath.ts

@@ -0,0 +1,32 @@
+import { UglyModule, uglyLayouts, uglyResetLayouts } from "./gatherPages.js";
+import { getMatchedRoute } from "./getMatchedRoute.js";
+
+export const getRenderPath = (pathname: string) => {
+	const parts = pathname.split("/");
+
+	const getLayouts = (depth: number): UglyModule[] => {
+		if (depth === parts.length) return [];
+		const currPath = parts.slice(0, parts.length - depth);
+		const joined = currPath.join("/");
+		const _layout = getMatchedRoute(`${joined}/layout`, uglyLayouts);
+		const _resetLayout = getMatchedRoute(
+			`${joined}/layoutReset`,
+			uglyResetLayouts,
+		);
+		if (_resetLayout) {
+			return [_resetLayout, _layout].filter(Boolean) as UglyModule[];
+		}
+
+		return [...getLayouts(depth + 1), _layout].filter(
+			Boolean,
+		) as UglyModule[];
+	};
+
+	const layouts = getLayouts(0);
+	const page = getMatchedRoute(pathname);
+
+	return {
+		path: [...layouts, page].filter(Boolean) as UglyModule[],
+		hasPage: !!page,
+	};
+};

package/src/build.ts

@@ -0,0 +1,64 @@
+import { build } from "vite";
+import fs from "node:fs";
+import path from "node:path";
+import {
+	appFrontendRoot,
+	buildPaths,
+	clientEntry,
+	createViteConfig,
+	serverEntry,
+} from "./utils/viteConfig.js";
+
+/**
+ * Прод-сборка приложения: клиентский бандл (с manifest) и SSR-бандл.
+ * Бэкенд не компилируется — он запускается тем же tsx, что и в dev
+ * (`NODE_ENV=production tsx src/index.ts`), а прод-ветка react-плагина
+ * отдаёт статику из build/client и рендерит через build/server.
+ */
+export async function buildApp({ cwd = process.cwd() } = {}) {
+	const root = appFrontendRoot(cwd);
+	const paths = buildPaths(cwd);
+
+	fs.rmSync(paths.root, { recursive: true, force: true });
+
+	console.log("[build] client bundle…");
+	await build(
+		createViteConfig({
+			root,
+			build: {
+				outDir: paths.client,
+				emptyOutDir: true,
+				manifest: true,
+				rollupOptions: {
+					input: clientEntry,
+				},
+			},
+		}),
+	);
+
+	console.log("[build] ssr bundle…");
+	await build(
+		createViteConfig({
+			root,
+			build: {
+				outDir: paths.server,
+				emptyOutDir: true,
+				ssr: serverEntry,
+				rollupOptions: {
+					output: { entryFileNames: "entry-server.js" },
+				},
+			},
+		}),
+	);
+
+	// статика приложения (favicon и прочее), если есть
+	const staticDir = path.join(cwd, "static");
+	if (fs.existsSync(staticDir)) {
+		fs.cpSync(staticDir, path.join(paths.root, "static"), {
+			recursive: true,
+		});
+	}
+
+	console.log(`[build] готово → ${paths.root}`);
+	return paths;
+}

package/src/frontend/App.tsx

@@ -0,0 +1,99 @@
+import "vite/modulepreload-polyfill";
+// ВСЕ стили Mantine — только layered-варианты. Смешение layered ядра с
+// не-layered пакетами меняет приоритеты правил, и в прод-сборке (где CSS
+// склеивается в другом порядке) filled-кнопки теряли фон.
+import "@mantine/core/styles.layer.css";
+import "@mantine/notifications/styles.layer.css";
+import "@mantine/dates/styles.layer.css";
+import { ModalsProvider } from "@mantine/modals";
+
+import { Notifications } from "@mantine/notifications";
+import { MantineProvider } from "@mantine/core";
+
+import { UglyModule, ViteModulesEager } from "../Router/gatherPages.js";
+import { ErrorHandler } from "./ErrorHandler.js";
+import { UglyRouter } from "../Router/Router.js";
+import Store, {
+	StoreContext,
+	TRPCContext,
+	type TRPCClient,
+} from "@quark-fw/store";
+// регистрирует показ ошибок через notifications (side-effect импорт)
+import "./displayError.js";
+import { SeoProvider, type SeoMap } from "../seo/SeoContext.js";
+import { I18nProvider, type EagerLocaleModules } from "../i18n/I18nContext.js";
+import type { I18nConfig } from "../i18n/config.js";
+// @ts-expect-error virtual file
+import { appTheme } from "/theme.ts";
+
+interface AppProps {
+	viteModules?: ViteModulesEager;
+	registerModule: (module: UglyModule) => void;
+	colorScheme: "light" | "dark" | undefined;
+	store: Store;
+	trpcClient: TRPCClient;
+	seoObject?: SeoMap;
+	locale?: string;
+	eagerLocaleModules?: EagerLocaleModules;
+}
+
+// i18n опционален: без /i18n.ts в приложении провайдер не рендерится,
+// а useI18n() отдаёт дефолт, в котором $(key) возвращает сам ключ
+const i18nModules: Record<string, { i18nConfig?: I18nConfig }> =
+	import.meta.glob("/i18n.ts", { eager: true });
+const i18nConfig = Object.values(i18nModules)[0]?.i18nConfig;
+
+export default function App({
+	viteModules,
+	registerModule,
+	colorScheme: defaultColorScheme,
+	store,
+	trpcClient,
+	seoObject,
+	locale,
+	eagerLocaleModules,
+}: AppProps) {
+	const tree = (
+		<>
+			<Notifications position="top-right" />
+
+			<ErrorHandler>
+				<UglyRouter
+					registerModule={registerModule}
+					viteModules={viteModules}
+				/>
+			</ErrorHandler>
+		</>
+	);
+	return (
+		<ErrorHandler>
+			<MantineProvider
+				defaultColorScheme={defaultColorScheme || "auto"}
+				withGlobalClasses={false}
+				theme={appTheme}
+			>
+				<ModalsProvider>
+					<TRPCContext value={trpcClient}>
+						<StoreContext value={store}>
+							<SeoProvider seoObject={seoObject}>
+								{i18nConfig ? (
+									<I18nProvider
+										locale={
+											locale || i18nConfig.defaultLocale
+										}
+										config={i18nConfig}
+										eagerLocaleModules={eagerLocaleModules}
+									>
+										{tree}
+									</I18nProvider>
+								) : (
+									tree
+								)}
+							</SeoProvider>
+						</StoreContext>
+					</TRPCContext>
+				</ModalsProvider>
+			</MantineProvider>
+		</ErrorHandler>
+	);
+}

package/src/frontend/ErrorHandler.tsx

@@ -0,0 +1,58 @@
+import { Component, type ErrorInfo, type ReactNode } from "react";
+
+type ErrorHandlerProps = {
+	children?: ReactNode;
+	/** подпись, по которой видно, какой участок дерева упал */
+	label?: string;
+};
+
+type ErrorHandlerState = {
+	hasError: boolean;
+	error: unknown;
+};
+
+class ErrorHandler extends Component<ErrorHandlerProps, ErrorHandlerState> {
+	constructor(props: ErrorHandlerProps) {
+		super(props);
+		this.state = { hasError: false, error: "" };
+	}
+
+	static getDerivedStateFromError(error: unknown) {
+		return { hasError: true, error };
+	}
+
+	componentDidCatch(error: unknown, errorInfo: ErrorInfo) {
+		console.error(error, errorInfo);
+	}
+
+	/**
+	 * Сброс ошибки при смене поддерева.
+	 *
+	 * Раньше первый аргумент назывался prevState, хотя React передаёт сюда
+	 * prevProps — из-за этого условие читало поле, которого у пропсов нет, и
+	 * граница не сбрасывалась никогда. Сбрасываем именно на смену children:
+	 * сброс на каждый рендер зациклил бы падающего потомка (ошибка → сброс →
+	 * ошибка).
+	 */
+	componentDidUpdate(prevProps: ErrorHandlerProps) {
+		if (this.state.hasError && prevProps.children !== this.props.children) {
+			this.setState({ hasError: false, error: "" });
+		}
+	}
+
+	render() {
+		if (this.state.hasError) {
+			return (
+				<div>
+					{this.props.label ? <code>{this.props.label}</code> : null}
+					Error :(
+					<pre>{String(this.state.error)}</pre>
+				</div>
+			);
+		}
+
+		return this.props.children;
+	}
+}
+
+export { ErrorHandler };