@quark-fw/plugin-react 0.1.22 → 0.1.24

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@quark-fw/plugin-react",
-	"version": "0.1.22",
+	"version": "0.1.24",
 	"main": "src/index.ts",
 	"types": "src/index.ts",
 	"type": "module",
@@ -22,8 +22,8 @@
 		"access": "public"
 	},
 	"dependencies": {
-		"@quark-fw/atom": "0.1.22",
-		"@quark-fw/plugin": "0.1.22",
+		"@quark-fw/atom": "0.1.24",
+		"@quark-fw/plugin": "0.1.24",
 		"@trpc/client": "^11.0.0",
 		"@types/react-dom": "^19.2.3",
 		"express": "^5.2.1",
@@ -36,8 +36,8 @@
 		"@mantine/dates": "^9.0.0",
 		"@mantine/modals": "^9.0.0",
 		"@mantine/notifications": "^9.0.0",
-		"@quark-fw/core": "0.1.22",
-		"@quark-fw/store": "0.1.22",
+		"@quark-fw/core": "0.1.24",
+		"@quark-fw/store": "0.1.24",
 		"@vitejs/plugin-react": "^5.1.0",
 		"react": "^19.2.4",
 		"react-dom": "^19.2.4",

package/src/frontend/HTML/index.tsx

@@ -15,7 +15,7 @@ export type HTMLProps = {
 	colorScheme: "dark" | "light" | undefined;
 	manifest: Manifest;
 	pathname?: string;
-	/** путь БЕЗ префикса локали — по нему клиентский SeoProvider ищет мету */
+	/** путь БЕЗ префикса локали + search — ключ, по которому SeoProvider ищет мету */
 	seoPathname?: string;
 	seo?: ResolvedSeo;
 	/** иконка вкладки; приложение задаёт её атомом quark.react.favicon */
@@ -40,8 +40,16 @@ function HTML({
 	linkBase,
 }: HTMLProps) {
 	const path = removeSearchParamsFromUrl(pathname!);
-	// без origin остаётся относительный URL — как было до появления поля
-	const canonical = origin ? origin + path : path;
+	// canonical из меты: относительный (от basename) дополняется linkBase,
+	// абсолютный берётся как есть; без меты — путь без query. Без origin
+	// остаётся относительный URL — как было до появления поля
+	const canonical = seo?.canonical
+		? seo.canonical.startsWith("/")
+			? (linkBase ?? "") + seo.canonical
+			: seo.canonical
+		: origin
+			? origin + path
+			: path;
 	// относительная картинка og:image без origin бесполезна для соцсетей
 	const abs = (url?: string) =>
 		url && url.startsWith("/") && origin ? origin + url : url;
@@ -86,7 +94,17 @@ function HTML({
 							/>
 						) : null}
 						{og?.image ? (
-							<meta property="og:image" content={abs(og.image)} />
+							<>
+								<meta
+									property="og:image"
+									content={abs(og.image)}
+								/>
+								{/* Twitter/X не читает og:image без twitter:card */}
+								<meta
+									name="twitter:card"
+									content="summary_large_image"
+								/>
+							</>
 						) : null}
 						{og?.siteName ? (
 							<meta

package/src/frontend/entry-server.tsx

@@ -65,6 +65,8 @@ export class Renderer {
 	locale?: string;
 	basename?: string;
 	strippedPathname?: string;
+	/** нормализованный search запроса ("" или "?a=1") — часть ключа SEO-карты */
+	search: string;
 
 	constructor({
 		url,
@@ -72,18 +74,21 @@ export class Renderer {
 		locale,
 		basename,
 		strippedPathname,
+		search = "",
 	}: {
 		url: string;
 		manifest: Manifest;
 		locale?: string;
 		basename?: string;
 		strippedPathname?: string;
+		search?: string;
 	}) {
 		this.url = url;
 		this.manifest = manifest;
 		this.locale = locale;
 		this.basename = basename;
 		this.strippedPathname = strippedPathname;
+		this.search = search;
 	}
 
 	head({
@@ -97,7 +102,11 @@ export class Renderer {
 		return ReactDOMServer.renderToString(
 			<HTML
 				pathname={req.originalUrl}
-				seoPathname={this.strippedPathname}
+				seoPathname={
+					this.strippedPathname === undefined
+						? undefined
+						: this.strippedPathname + this.search
+				}
 				colorScheme={colorScheme}
 				manifest={this.manifest}
 				seo={seo}

package/src/seo/SeoProvider.tsx

@@ -5,6 +5,7 @@ import { matchPath } from "react-router-dom";
 import { getMatchedRoute } from "../Router/getMatchedRoute.js";
 import type { PageMeta } from "./createPageMeta.js";
 import SeoContext, { type SeoContextValue, type SeoMap } from "./SeoContext.js";
+import { parseSearch, seoKey } from "../utils/parseSearch.js";
 
 export function SeoProvider({
 	children,
@@ -17,11 +18,13 @@ export function SeoProvider({
 	locale?: string;
 }) {
 	const [seoObject, setSeoObject] = useState<SeoMap>(initial ?? {});
-	const { pathname } = useLocation();
+	const { pathname, search } = useLocation();
 	const navigate = useNavigate();
 	const store = useStore();
 
-	const current = seoObject[pathname];
+	// ключ с search: ?page=2 — другая мета (title, canonical), чем страница 1
+	const key = seoKey(pathname, search);
+	const current = seoObject[key];
 
 	// редирект из меты при клиентской навигации (на SSR его сделала мидлвара)
 	useEffect(() => {
@@ -56,9 +59,10 @@ export function SeoProvider({
 					typeof window === "undefined"
 						? undefined
 						: window.location.origin,
+				query: parseSearch(search).query,
 			});
 			if (!cancelled) {
-				setSeoObject((prev) => ({ ...prev, [pathname]: resolved }));
+				setSeoObject((prev) => ({ ...prev, [key]: resolved }));
 			}
 		})();
 		return () => {
@@ -68,7 +72,7 @@ export function SeoProvider({
 		// добавление в зависимости ничего бы не изменило; locale меняется
 		// только полной перезагрузкой (setLocale)
 		// eslint-disable-next-line react-hooks/exhaustive-deps
-	}, [pathname, current]);
+	}, [key, current]);
 
 	// заголовок вкладки при клиентской навигации
 	useEffect(() => {

package/src/seo/createPageMeta.test.ts

@@ -23,6 +23,24 @@ test("resolveMeta передаёт locale и origin в функции меты
 	expect(seo.og?.locale).toBe("ru_RU");
 });
 
+test("resolveMeta передаёт query и резолвит canonical", async () => {
+	const seo = await resolveMeta(
+		{
+			canonical: ({ query }) =>
+				Number(query?.["page"]) > 1
+					? `/tbilisi?page=${query!["page"]}`
+					: undefined,
+		},
+		{ store: {} as never, params: {}, query: { page: "2" } },
+	);
+	expect(seo.canonical).toBe("/tbilisi?page=2");
+	const first = await resolveMeta(
+		{ canonical: ({ query }) => (query?.["page"] ? "/x" : undefined) },
+		{ store: {} as never, params: {} },
+	);
+	expect(first.canonical).toBeUndefined();
+});
+
 test("breadcrumbsJsonLd строит BreadcrumbList с абсолютными @id", () => {
 	const node = breadcrumbsJsonLd(
 		[

package/src/seo/createPageMeta.ts

@@ -14,6 +14,11 @@ export type PageMetaContext = {
 	 * на клиенте — из window.location.
 	 */
 	origin?: string;
+	/**
+	 * Query-параметры URL (первое значение каждого). Для страниц, чья мета
+	 * зависит от запроса — например пагинация каталога (?page=N).
+	 */
+	query?: Record<string, string>;
 };
 
 export type MetaValue<T> = T | ((ctx: PageMetaContext) => T | Promise<T>);
@@ -58,6 +63,12 @@ export type PageMeta = {
 	 * смена slug), чтобы не отдавать 404 по проиндексированным адресам.
 	 */
 	redirect?: MetaValue<PageMetaRedirect | undefined>;
+	/**
+	 * Canonical страницы: путь относительно basename (может содержать query,
+	 * например `/tbilisi?page=2`) или абсолютный URL. По умолчанию — путь
+	 * страницы без query. hreflang-кластер и og:url следуют за canonical.
+	 */
+	canonical?: MetaValue<string | undefined>;
 };
 
 export type ResolvedSeo = {
@@ -69,6 +80,7 @@ export type ResolvedSeo = {
 	breadcrumbs?: PageMetaBreadcrumb[];
 	status?: number;
 	redirect?: PageMetaRedirect;
+	canonical?: string;
 };
 
 export function createPageMeta(meta: PageMeta): PageMeta {
@@ -101,6 +113,7 @@ export async function resolveMeta(
 		breadcrumbs,
 		status,
 		redirect,
+		canonical,
 	] = await Promise.all([
 		resolveValue(meta.title, ctx),
 		resolveValue(meta.description, ctx),
@@ -110,6 +123,7 @@ export async function resolveMeta(
 		resolveValue(meta.breadcrumbs, ctx),
 		resolveValue(meta.status, ctx),
 		resolveValue(meta.redirect, ctx),
+		resolveValue(meta.canonical, ctx),
 	]);
 	return {
 		title,
@@ -120,6 +134,7 @@ export async function resolveMeta(
 		breadcrumbs,
 		status,
 		redirect,
+		canonical,
 	};
 }
 

package/src/ssr/getRenderMiddleware.ts

@@ -3,6 +3,7 @@ import { Request, Response } from "express";
 import { matchPath } from "react-router-dom";
 import { UglyModule } from "../Router/UglyModule.js";
 import removeSearchParamsFromUrl from "../utils/removeSearchParamsFromUrl.js";
+import { parseSearch } from "../utils/parseSearch.js";
 import { resolveMeta, type PageMeta } from "../seo/createPageMeta.js";
 import {
 	buildLocalePath,
@@ -62,12 +63,16 @@ export default function getRenderMiddleware({ vite }: GetRenderMiddlewareArgs) {
 				return;
 			}
 
+			// query нужен мете (пагинация) и ключу SEO-карты: одна и та же
+			// страница с разными ?page — разные title/canonical
+			const { search, query } = parseSearch(req.originalUrl);
 			const renderer = new rendererModule.Renderer({
 				url: req.originalUrl,
 				manifest,
 				locale,
 				basename,
 				strippedPathname,
+				search,
 			});
 
 			const page = rendererModule.hasUglyPage(strippedPathname) as
@@ -108,6 +113,7 @@ export default function getRenderMiddleware({ vite }: GetRenderMiddlewareArgs) {
 				params: (routeProps?.params ?? {}) as Record<string, string>,
 				locale: locale || undefined,
 				origin,
+				query,
 			});
 
 			// редирект из меты: страница переехала или схлопнута — отвечаем
@@ -122,13 +128,21 @@ export default function getRenderMiddleware({ vite }: GetRenderMiddlewareArgs) {
 
 			res.status(seo.status ?? (page ? 200 : 404));
 
-			// hreflang-кластер: каждая локаль + x-default на дефолтную
+			// hreflang-кластер: каждая локаль + x-default на дефолтную.
+			// Относительный canonical (например /tbilisi?page=2) задаёт путь
+			// кластера — иначе страница 2 ссылалась бы на страницу 1 других
+			// локалей и кластер переставал быть взаимным
+			const alternatePath =
+				seo.canonical && seo.canonical.startsWith("/")
+					? seo.canonical
+					: pathname;
 			const alternates =
 				i18nConfig && usesLocalePrefix(i18nConfig)
 					? [
 							...i18nConfig.locales.map((l) => ({
 								hreflang: l,
-								href: origin + buildLocalePath(l, pathname),
+								href:
+									origin + buildLocalePath(l, alternatePath),
 							})),
 							{
 								hreflang: "x-default",
@@ -136,7 +150,7 @@ export default function getRenderMiddleware({ vite }: GetRenderMiddlewareArgs) {
 									origin +
 									buildLocalePath(
 										i18nConfig.defaultLocale,
-										pathname,
+										alternatePath,
 									),
 							},
 						]
@@ -148,7 +162,8 @@ export default function getRenderMiddleware({ vite }: GetRenderMiddlewareArgs) {
 				store,
 				trpcClient,
 				seo,
-				seoObject: { [pathname]: seo },
+				// ключ — путь + search, как его увидит SeoProvider через useLocation()
+				seoObject: { [pathname + search]: seo },
 				favicon: reactAtoms?.favicon?.value,
 				origin,
 				alternates,

package/src/utils/parseSearch.test.ts

@@ -0,0 +1,20 @@
+import { expect, test } from "vitest";
+import { parseSearch, seoKey } from "./parseSearch.js";
+
+test("parseSearch: первое значение параметра, нормализованный search", () => {
+	expect(parseSearch("/ru/tbilisi?page=2&rooms=3&rooms=4#top")).toEqual({
+		search: "?page=2&rooms=3&rooms=4",
+		query: { page: "2", rooms: "3" },
+	});
+});
+
+test("parseSearch: пустой и одиночный ? дают пустой search", () => {
+	expect(parseSearch("/ru/tbilisi")).toEqual({ search: "", query: {} });
+	expect(parseSearch("?")).toEqual({ search: "", query: {} });
+});
+
+test("seoKey совпадает для SSR-URL и useLocation()", () => {
+	expect(seoKey("/tbilisi", "?page=2")).toBe("/tbilisi?page=2");
+	expect(seoKey("/tbilisi", "")).toBe("/tbilisi");
+	expect(seoKey("/tbilisi", "?")).toBe("/tbilisi");
+});

package/src/utils/parseSearch.ts

@@ -0,0 +1,27 @@
+// Разбор query-строки URL для меты и ключа SEO-карты. Без Node-зависимостей:
+// модуль нужен и SSR-мидлваре, и SeoProvider в браузере.
+
+export type ParsedSearch = {
+	/** нормализованный search: "?a=1" или "" (одиночный "?" — тоже "") */
+	search: string;
+	/** первое значение каждого параметра */
+	query: Record<string, string>;
+};
+
+export function parseSearch(urlOrSearch: string): ParsedSearch {
+	const index = urlOrSearch.indexOf("?");
+	const raw = index === -1 ? "" : urlOrSearch.slice(index + 1);
+	// hash в URL не относится к запросу
+	const withoutHash = raw.split("#")[0] ?? "";
+	const params = new URLSearchParams(withoutHash);
+	const query: Record<string, string> = {};
+	for (const [key, value] of params) {
+		if (!(key in query)) query[key] = value;
+	}
+	const search = params.toString();
+	return { search: search ? `?${search}` : "", query };
+}
+
+/** Ключ SEO-карты: путь без basename + нормализованный search. */
+export const seoKey = (pathname: string, search: string) =>
+	pathname + parseSearch(search).search;