@quark-fw/plugin-react 0.1.2

package/src/frontend/HTML/index.tsx

@@ -0,0 +1,155 @@
+import { ReactNode } from "react";
+import { ColorSchemeScript } from "@mantine/core";
+import { Manifest } from "vite";
+import removeSearchParamsFromUrl from "../../utils/removeSearchParamsFromUrl.js";
+import serializeForScript from "../../utils/serializeForScript.js";
+import type { ResolvedSeo } from "../../seo/createPageMeta.js";
+
+export type HTMLProps = {
+	children?: ReactNode;
+	colorScheme: "dark" | "light" | undefined;
+	manifest: Manifest;
+	pathname?: string;
+	/** путь БЕЗ префикса локали — по нему клиентский SeoProvider ищет мету */
+	seoPathname?: string;
+	seo?: ResolvedSeo;
+	/** иконка вкладки; приложение задаёт её атомом quark.react.favicon */
+	favicon?: string;
+};
+
+function HTML({
+	colorScheme,
+	manifest,
+	pathname,
+	seoPathname,
+	seo,
+	favicon,
+}: HTMLProps) {
+	const canonical = removeSearchParamsFromUrl(pathname!);
+	const og = seo?.og;
+	return (
+		<>
+			<head>
+				<title>{seo?.title ?? "App"}</title>
+				<link rel="canonical" href={canonical} />
+				{favicon ? <link rel="icon" href={favicon} /> : null}
+				{seo?.description ? (
+					<meta name="description" content={seo.description} />
+				) : null}
+				{seo?.robots ? (
+					<meta name="robots" content={seo.robots} />
+				) : null}
+				{og || seo?.title ? (
+					<>
+						<meta
+							property="og:title"
+							content={og?.title ?? seo?.title ?? ""}
+						/>
+						<meta property="og:url" content={canonical} />
+						<meta
+							property="og:type"
+							content={og?.type ?? "website"}
+						/>
+						{(og?.description ?? seo?.description) ? (
+							<meta
+								property="og:description"
+								content={
+									og?.description ?? seo?.description ?? ""
+								}
+							/>
+						) : null}
+						{og?.image ? (
+							<meta property="og:image" content={og.image} />
+						) : null}
+						{og?.siteName ? (
+							<meta
+								property="og:site_name"
+								content={og.siteName}
+							/>
+						) : null}
+					</>
+				) : null}
+				{/* мета для клиентской навигации (SeoProvider) */}
+				<script
+					dangerouslySetInnerHTML={{
+						// ключ — путь, который увидит useLocation() на клиенте
+						// (basename роутера уже срезан), иначе SeoProvider
+						// промахнётся и перезапросит мету заново
+						__html: `window.seo=${serializeForScript({
+							[seoPathname ?? canonical]: seo ?? {},
+						})}`,
+					}}
+				/>
+				<ColorSchemeScript
+					defaultColorScheme={colorScheme || "light"}
+				/>
+				<meta charSet="utf-8" />
+				<meta
+					name="viewport"
+					content="width=device-width, initial-scale=1, maximum-scale=1"
+				/>
+				<script
+					dangerouslySetInnerHTML={{
+						__html: "window.cache = window.cache || {}",
+					}}
+				/>
+
+				{/* ключ манифеста — путь ИСХОДНИКА (…/entry-client.tsx),
+				    поэтому ищем по имени без расширения */}
+				{Object.entries(manifest)
+					.find(([e]) => e.includes("entry-client"))?.[1]
+					?.css?.map((e) => (
+						<link rel="stylesheet" href={`/${e}`} key={e} />
+					))}
+				{process.env.NODE_ENV !== "production" ? (
+					<script
+						async
+						type="module"
+						dangerouslySetInnerHTML={{
+							__html: `
+import RefreshRuntime from "/@react-refresh"
+RefreshRuntime.injectIntoGlobalHook(window)
+window.$RefreshReg$ = () => {}
+window.$RefreshSig$ = () => (type) => type
+window.__vite_plugin_react_preamble_installed__ = true
+				`,
+						}}
+					/>
+				) : null}
+				<script
+					dangerouslySetInnerHTML={{
+						// необходимо для коректной работы UgliestImage
+						__html: `
+function refreshImg (id) {
+if (id) {
+	function elementIsDrawn(element, callback) {
+		function checkIfDrawn() {
+			if (element.offsetWidth && element.offsetHeight) {
+				callback(element);
+			} else {
+				requestAnimationFrame(checkIfDrawn);
+			}
+		}
+
+		checkIfDrawn();
+	}
+
+	elementIsDrawn(document.querySelector(\`[id="$\{id}"]\`), (el) => {
+		const img = el.querySelector('img');
+		const width = el.offsetWidth * window.devicePixelRatio;
+		const height = el.offsetHeight * window.devicePixelRatio;
+		if (width && height) {
+			img.src = (img.getAttribute('_src') + '').replace('_w_', width).replace('_h_', height);
+		}
+	})
+
+}
+}`,
+					}}
+				/>
+			</head>
+		</>
+	);
+}
+
+export default HTML;

package/src/frontend/displayError.ts

@@ -0,0 +1,16 @@
+import { notifications } from "@mantine/notifications";
+import { errorMessage, setErrorHandler } from "@quark-fw/store/src/errors.js";
+
+// На клиенте ошибки библиотек (например откат оптимистичного обновления)
+// показываем всплывающим уведомлением. На сервере оставляем console.error:
+// notifications требуют смонтированного провайдера.
+if (typeof window !== "undefined") {
+	setErrorHandler((error, context) => {
+		console.error(context ? `[${context}]` : "[quark]", error);
+		notifications.show({
+			color: "red",
+			title: context ?? "Ошибка",
+			message: errorMessage(error),
+		});
+	});
+}

package/src/frontend/entry-client.tsx

@@ -0,0 +1,74 @@
+import { hydrateRoot } from "react-dom/client";
+import { BrowserRouter } from "react-router-dom";
+import { startTransition } from "react";
+import Store, { trpcClient } from "@quark-fw/store";
+import { getRenderPath } from "../Router/getRenderPath.js";
+import { parseLocalePath, type I18nConfig } from "../i18n/config.js";
+import App from "./App.js";
+
+/** то, что SSR кладёт в window для гидратации */
+type HydrationWindow = typeof window & {
+	cache?: Record<string, unknown>;
+	store?: Store;
+	seo?: Record<string, unknown>;
+};
+
+const hydrationWindow = window as HydrationWindow;
+hydrationWindow.cache = hydrationWindow.cache || {};
+const store = new Store({ trpcClient, values: hydrationWindow.cache });
+hydrationWindow.store = store;
+
+// i18n опционален: без /i18n.ts glob вернёт пустой объект
+const i18nModules: Record<string, { i18nConfig?: I18nConfig }> =
+	import.meta.glob("/i18n.ts", { eager: true });
+const i18nConfig = Object.values(i18nModules)[0]?.i18nConfig;
+
+const rootEl = document.getElementById("root");
+if (rootEl) {
+	const { locale, strippedPathname, basename } = parseLocalePath(
+		window.location.pathname,
+		i18nConfig,
+	);
+	const { path } = getRenderPath(strippedPathname);
+
+	void Promise.all(path.map((e) => e.load()));
+
+	const parsedProps = Object.keys(rootEl.dataset).reduce(
+		(acc, key) => {
+			let parsed;
+
+			const data = rootEl.dataset[key]!;
+
+			try {
+				parsed = JSON.parse(data);
+			} catch {
+				// не JSON — значит в атрибуте лежала обычная строка
+				parsed = data;
+			}
+
+			return {
+				...acc,
+				[key]: parsed,
+			};
+		},
+		{} as Record<string, unknown>,
+	);
+
+	startTransition(() => {
+		hydrateRoot(
+			rootEl,
+			<BrowserRouter basename={basename}>
+				<App
+					registerModule={() => {}}
+					colorScheme={
+						parsedProps.colorScheme as "dark" | "light" | undefined
+					}
+					store={store}
+					trpcClient={trpcClient}
+					seoObject={hydrationWindow.seo ?? {}}
+					locale={locale}
+				/>
+			</BrowserRouter>,
+		);
+	});
+}

package/src/frontend/entry-server.tsx

@@ -0,0 +1,131 @@
+import type Store from "@quark-fw/store";
+import type { TRPCClient } from "@quark-fw/store";
+import ReactDOMServer, {
+	RenderToPipeableStreamOptions,
+} from "react-dom/server";
+import { StaticRouter } from "react-router-dom";
+import type { Request } from "express";
+import type { Manifest } from "vite";
+import { getMatchedRoute } from "../Router/getMatchedRoute.js";
+import {
+	createUglyModules,
+	UglyModule,
+	ViteModulesEager,
+} from "../Router/gatherPages.js";
+import HTML from "./HTML/index.js";
+import App from "./App.js";
+import type { ResolvedSeo } from "../seo/createPageMeta.js";
+import type { I18nConfig } from "../i18n/config.js";
+import type { EagerLocaleModules } from "../i18n/I18nContext.js";
+
+// i18n опционален: если у приложения нет /i18n.ts — glob вернёт пустой объект
+const i18nModules: Record<string, { i18nConfig?: I18nConfig }> =
+	import.meta.glob("/i18n.ts", { eager: true });
+export const i18nConfig = Object.values(i18nModules)[0]?.i18nConfig;
+
+const localeModules: EagerLocaleModules = import.meta.glob("/locales/*/*.ts", {
+	eager: true,
+});
+
+const pages: ViteModulesEager = import.meta.glob("/Pages/**/Page.*", {
+	eager: true,
+});
+const layouts: ViteModulesEager = import.meta.glob("/Pages/**/Layout.*", {
+	eager: true,
+});
+const resetLayouts: ViteModulesEager = import.meta.glob(
+	"/Pages/**/LayoutReset.*",
+	{ eager: true },
+);
+
+const uglyPages = createUglyModules(pages);
+
+export interface RendererPipeParams {
+	req: Request;
+	options: RenderToPipeableStreamOptions;
+	registerModule: (module: UglyModule) => void;
+	colorScheme?: "light" | "dark";
+	store: Store;
+	trpcClient: TRPCClient;
+	seo?: ResolvedSeo;
+	seoObject?: Record<string, ResolvedSeo>;
+	/** иконка вкладки из атома приложения */
+	favicon?: string;
+}
+
+export const hasUglyPage = (url: string) => getMatchedRoute(url, uglyPages);
+
+export class Renderer {
+	url: string;
+	manifest: Manifest;
+	locale?: string;
+	basename?: string;
+	strippedPathname?: string;
+
+	constructor({
+		url,
+		manifest,
+		locale,
+		basename,
+		strippedPathname,
+	}: {
+		url: string;
+		manifest: Manifest;
+		locale?: string;
+		basename?: string;
+		strippedPathname?: string;
+	}) {
+		this.url = url;
+		this.manifest = manifest;
+		this.locale = locale;
+		this.basename = basename;
+		this.strippedPathname = strippedPathname;
+	}
+
+	head({
+		colorScheme,
+		req,
+		seo,
+		favicon,
+	}: Omit<RendererPipeParams, "options">) {
+		return ReactDOMServer.renderToString(
+			<HTML
+				pathname={req.originalUrl}
+				seoPathname={this.strippedPathname}
+				colorScheme={colorScheme}
+				manifest={this.manifest}
+				seo={seo}
+				favicon={favicon}
+			/>,
+		);
+	}
+
+	pipe({
+		options,
+		registerModule,
+		colorScheme,
+		store,
+		trpcClient,
+		seoObject,
+	}: RendererPipeParams) {
+		return ReactDOMServer.renderToPipeableStream(
+			<StaticRouter location={this.url} basename={this.basename || ""}>
+				<App
+					colorScheme={colorScheme}
+					registerModule={registerModule}
+					store={store}
+					trpcClient={trpcClient}
+					seoObject={seoObject}
+					locale={this.locale}
+					eagerLocaleModules={localeModules}
+					viteModules={{
+						...pages,
+						...layouts,
+						...resetLayouts,
+					}}
+				/>
+			</StaticRouter>,
+			options,
+		);
+	}
+}

package/src/global.d.ts

@@ -0,0 +1,19 @@
+import "@quark-fw/core/src/global.d.ts";
+import { Atom } from "@quark-fw/atom";
+
+export {};
+
+declare global {
+	interface Quark {
+		react: {
+			port: Atom<number>;
+			/** значение <html lang> для приложений без i18n */
+			lang: Atom<string>;
+			/**
+			 * Иконка вкладки: путь или data-URI. Пустая строка — не выводить
+			 * ссылку вовсе.
+			 */
+			favicon: Atom<string>;
+		};
+	}
+}

package/src/i18n/I18nContext.tsx

@@ -0,0 +1,217 @@
+/// <reference types="vite/client" />
+import { createContext, ReactNode, useContext, useMemo } from "react";
+import { useStore } from "@quark-fw/store";
+import { usePromise } from "@quark-fw/store/src/usePromise.js";
+import {
+	buildLocalePath,
+	usesLocalePrefix,
+	type I18nConfig,
+} from "./config.js";
+import { getLocaleImporter, type LocaleModule } from "./gatherLocales.js";
+
+export type Translate = (
+	key: string,
+	params?: Record<string, string | number>,
+) => string;
+
+export type I18nContextValue = {
+	locale: string;
+	locales: readonly string[];
+	defaultLocale: string;
+	$: Translate;
+	setLocale: (locale: string) => void;
+};
+
+// дефолт для приложений без i18n: $ возвращает ключ, а не падает
+const I18nContext = createContext<I18nContextValue>({
+	locale: "",
+	locales: [],
+	defaultLocale: "",
+	$: (key: string) => key,
+	setLocale: () => {},
+});
+
+export const useI18n = () => useContext(I18nContext);
+
+export type EagerLocaleModules = Record<string, LocaleModule>;
+
+const deepMerge = (base: unknown, override: unknown): unknown => {
+	if (
+		typeof base !== "object" ||
+		base === null ||
+		typeof override !== "object" ||
+		override === null
+	) {
+		return typeof override === "undefined" ? base : override;
+	}
+	const source = base as Record<string, unknown>;
+	const patch = override as Record<string, unknown>;
+	const out: Record<string, unknown> = { ...source };
+	for (const key of Object.keys(patch)) {
+		out[key] = deepMerge(source[key], patch[key]);
+	}
+	return out;
+};
+
+const interpolate = (
+	template: string,
+	params?: Record<string, string | number>,
+) =>
+	params
+		? template.replace(/\{(\w+)\}/g, (match, name) =>
+				name in params ? String(params[name]) : match,
+			)
+		: template;
+
+export function I18nProvider({
+	locale,
+	config,
+	eagerLocaleModules,
+	children,
+}: {
+	locale: string;
+	config: I18nConfig;
+	/** передаётся только на сервере (eager-glob из entry-server) */
+	eagerLocaleModules?: EagerLocaleModules;
+	children: ReactNode;
+}) {
+	const store = useStore();
+
+	const value: I18nContextValue = useMemo(() => {
+		const defaultLocale = config?.defaultLocale || locale;
+		let pluralRules: Intl.PluralRules;
+		try {
+			pluralRules = new Intl.PluralRules(locale || undefined);
+		} catch {
+			pluralRules = new Intl.PluralRules();
+		}
+
+		/*
+		 * usePromise ниже — хук, вызванный не из компонента: словарь читается в
+		 * теле рендера потребителя ($), поэтому порядок вызовов совпадает с
+		 * порядком чтений. Кэш стора при этом заполняется намеренно — это его
+		 * назначение, а не мутация чужого состояния.
+		 */
+		/* eslint-disable react-hooks/rules-of-hooks, react-hooks/immutability */
+		const loadNamespace = (ns: string, cacheKey: string): unknown => {
+			if (eagerLocaleModules) {
+				// SSR: синхронно склеиваем словари и стримим их клиенту
+				const def =
+					eagerLocaleModules[`/locales/${defaultLocale}/${ns}.ts`]
+						?.default;
+				const cur =
+					locale === defaultLocale
+						? undefined
+						: eagerLocaleModules[`/locales/${locale}/${ns}.ts`]
+								?.default;
+				const data = deepMerge(def ?? {}, cur ?? {});
+				store.values[cacheKey] = data;
+				store.callback?.(cacheKey, data);
+				return data;
+			}
+
+			// клиент: подвешиваемся на ленивые чанки vite
+			const { reactPromises } = store;
+			if (!reactPromises[cacheKey]) {
+				const importDefault = getLocaleImporter(defaultLocale, ns);
+				const importCurrent =
+					locale === defaultLocale
+						? undefined
+						: getLocaleImporter(locale, ns);
+				if (!importDefault && !importCurrent) {
+					store.values[cacheKey] = {};
+					return store.values[cacheKey];
+				}
+				reactPromises[cacheKey] = usePromise(
+					Promise.all([importDefault?.(), importCurrent?.()]).then(
+						([def, cur]) => {
+							const merged = deepMerge(
+								def?.default ?? {},
+								cur?.default ?? {},
+							);
+							store.values[cacheKey] = merged;
+							return merged;
+						},
+					),
+				);
+			}
+			return reactPromises[cacheKey]();
+		};
+
+		const $: Translate = (key, params) => {
+			const dot = key.indexOf(".");
+			const ns = dot === -1 ? key : key.slice(0, dot);
+			const rest = dot === -1 ? "" : key.slice(dot + 1);
+			const cacheKey = `i18n:${locale}:${ns}`;
+
+			let data = store.values[cacheKey];
+			if (typeof data === "undefined") data = loadNamespace(ns, cacheKey);
+
+			// по словарю идём как по дереву неизвестной формы
+			const asDict = (value: unknown) =>
+				value && typeof value === "object"
+					? (value as Record<string, unknown>)
+					: undefined;
+
+			let node: unknown = data;
+			for (const part of rest ? rest.split(".") : []) {
+				node = asDict(node)?.[part];
+			}
+
+			if (typeof node === "string") return interpolate(node, params);
+
+			// плюрализация: { one: "…", few: "…", other: "…" } + params.count
+			const forms = asDict(node);
+			if (forms && typeof forms.other === "string") {
+				const count = Number(params?.count);
+				const category = Number.isFinite(count)
+					? pluralRules.select(count)
+					: "other";
+				const form = forms[category];
+				return interpolate(
+					typeof form === "string" ? form : forms.other,
+					params,
+				);
+			}
+
+			return key;
+		};
+
+		const setLocale = (next: string) => {
+			if (
+				!config?.locales.includes(next) ||
+				typeof window === "undefined"
+			)
+				return;
+			document.cookie = `locale=${next};path=/;max-age=31536000`;
+			if (!usesLocalePrefix(config)) {
+				window.location.reload();
+				return;
+			}
+			const { pathname, search, hash } = window.location;
+			const stripped = pathname.startsWith(`/${locale}`)
+				? pathname.slice(locale.length + 1) || "/"
+				: pathname;
+			window.location.href =
+				buildLocalePath(next, stripped) + search + hash;
+		};
+
+		return {
+			locale,
+			locales: config?.locales ?? [],
+			defaultLocale,
+			$,
+			setLocale,
+		};
+		// config и eagerLocaleModules приходят из модулей приложения (/i18n.ts
+		// и glob по /locales) и за время жизни страницы не меняются —
+		// пересобирать контекст на их идентичность незачем
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [locale, store]);
+
+	return (
+		<I18nContext.Provider value={value}>{children}</I18nContext.Provider>
+	);
+}
+
+export default I18nContext;