@quark-fw/plugin-react 0.1.16 → 0.1.17

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@quark-fw/plugin-react",
-	"version": "0.1.16",
+	"version": "0.1.17",
 	"main": "src/index.ts",
 	"types": "src/index.ts",
 	"type": "module",
@@ -22,8 +22,8 @@
 		"access": "public"
 	},
 	"dependencies": {
-		"@quark-fw/atom": "0.1.16",
-		"@quark-fw/plugin": "0.1.16",
+		"@quark-fw/atom": "0.1.17",
+		"@quark-fw/plugin": "0.1.17",
 		"@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.16",
-		"@quark-fw/store": "0.1.16",
+		"@quark-fw/core": "0.1.17",
+		"@quark-fw/store": "0.1.17",
 		"@vitejs/plugin-react": "^5.1.0",
 		"react": "^19.2.4",
 		"react-dom": "^19.2.4",

package/src/Router/PageComponentRenderer.tsx

@@ -3,19 +3,26 @@ import { memo, ReactNode, type ComponentType } from "react";
 function PageComponentRenderer({
 	children,
 	Component,
+	// служебный ключ сравнения — странице не нужен
+	breadCrumbsKey: _breadCrumbsKey,
 	...restProps
 }: {
 	children?: ReactNode;
 	Component: ComponentType<Record<string, unknown>>;
-	// остальное — пропсы страницы, их состав задаёт приложение
+	breadCrumbsKey?: string;
+	// остальное — пропсы страницы, их состав задаёт роутер (UglyPageProps)
 	[key: string]: unknown;
 }) {
 	return <Component {...restProps}>{children}</Component>;
 }
 
+// Крошки сравниваются по ключу, а не по элементу: элемент новый на каждый
+// рендер, и сравнение по нему отключило бы мемоизацию целиком; без ключа
+// крошки, пришедшие после клиентского резолва меты, не дорисовались бы.
 export const MemoPageComponentRenderer = memo(
 	PageComponentRenderer,
 	(prevProps, nextProps) =>
 		prevProps.pathname === nextProps.pathname &&
-		JSON.stringify(prevProps.params) === JSON.stringify(nextProps.params),
+		JSON.stringify(prevProps.params) === JSON.stringify(nextProps.params) &&
+		prevProps.breadCrumbsKey === nextProps.breadCrumbsKey,
 );

package/src/Router/UglyModuleRenderer.tsx

@@ -2,6 +2,8 @@ import { memo, ReactNode, Suspense } from "react";
 import { matchPath } from "react-router-dom";
 import { Loader } from "@mantine/core";
 import { ErrorHandler } from "../frontend/ErrorHandler.js";
+import { useSeo } from "../seo/SeoContext.js";
+import { BreadCrumbs } from "../seo/BreadCrumbs.js";
 import { MemoPageComponentRenderer } from "./PageComponentRenderer.js";
 import { UglyModule } from "./UglyModule.js";
 import type { ViteModulesEager } from "./types.js";
@@ -20,6 +22,9 @@ function UglyModuleRenderer({
 	children: ReactNode;
 }) {
 	const uglyModule = renderPath[depth]!;
+	// крошки из меты текущей страницы (на SSR — сразу, на клиенте — после
+	// резолва меты в SeoProvider)
+	const { breadcrumbs } = useSeo();
 
 	if (!uglyModule) return children;
 	const PageComponent = uglyModule?.getWrappedPromise()?.default;
@@ -44,6 +49,12 @@ function UglyModuleRenderer({
 					Component={PageComponent}
 					pathname={pathname}
 					params={routeProps?.params}
+					breadCrumbs={
+						breadcrumbs?.length ? (
+							<BreadCrumbs items={breadcrumbs} />
+						) : null
+					}
+					breadCrumbsKey={JSON.stringify(breadcrumbs ?? null)}
 				>
 					<ErrorHandler>
 						<Suspense fallback={<Loader />}>

package/src/frontend/HTML/index.tsx

@@ -3,7 +3,10 @@ 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";
+import {
+	breadcrumbsJsonLd,
+	type ResolvedSeo,
+} from "../../seo/createPageMeta.js";
 
 export type HTMLAlternate = { hreflang: string; href: string };
 
@@ -21,6 +24,8 @@ export type HTMLProps = {
 	origin?: string;
 	/** hreflang-кластер страницы (приложения с префиксами локалей) */
 	alternates?: HTMLAlternate[];
+	/** origin + basename роутера — абсолютные @id в BreadcrumbList */
+	linkBase?: string;
 };
 
 function HTML({
@@ -32,6 +37,7 @@ function HTML({
 	favicon,
 	origin,
 	alternates,
+	linkBase,
 }: HTMLProps) {
 	const path = removeSearchParamsFromUrl(pathname!);
 	// без origin остаётся относительный URL — как было до появления поля
@@ -93,6 +99,16 @@ function HTML({
 						) : null}
 					</>
 				) : null}
+				{seo?.breadcrumbs?.length ? (
+					<script
+						type="application/ld+json"
+						dangerouslySetInnerHTML={{
+							__html: serializeForScript(
+								breadcrumbsJsonLd(seo.breadcrumbs, linkBase),
+							),
+						}}
+					/>
+				) : null}
 				{seo?.jsonLD?.map((node, index) => (
 					<script
 						key={index}

package/src/frontend/entry-server.tsx

@@ -104,6 +104,7 @@ export class Renderer {
 				favicon={favicon}
 				origin={origin}
 				alternates={alternates}
+				linkBase={(origin ?? "") + (this.basename ?? "")}
 			/>,
 		);
 	}

package/src/seo/BreadCrumbs.tsx

@@ -0,0 +1,28 @@
+import { Anchor, Breadcrumbs } from "@mantine/core";
+import { Link } from "react-router-dom";
+import type { PageMetaBreadcrumb } from "./createPageMeta.js";
+
+/** Крошки из меты страницы — роутер передаёт их компоненту пропсом breadCrumbs. */
+export function BreadCrumbs({ items }: { items: PageMetaBreadcrumb[] }) {
+	return (
+		<Breadcrumbs styles={{ root: { flexWrap: "wrap", rowGap: 4 } }}>
+			{items.map(({ label, to }, index) => (
+				<Anchor
+					key={index}
+					component={Link}
+					to={to}
+					// длинные хвостовые подписи (имена объявлений) не должны
+					// разваливать узкие экраны
+					style={{
+						maxWidth: 240,
+						overflow: "hidden",
+						textOverflow: "ellipsis",
+						whiteSpace: "nowrap",
+					}}
+				>
+					{label}
+				</Anchor>
+			))}
+		</Breadcrumbs>
+	);
+}

package/src/seo/createPageMeta.test.ts

@@ -1,5 +1,5 @@
 import { expect, test } from "vitest";
-import { resolveMeta } from "./createPageMeta.js";
+import { breadcrumbsJsonLd, resolveMeta } from "./createPageMeta.js";
 
 test("resolveMeta передаёт locale и origin в функции меты и резолвит jsonLD", async () => {
 	const ctx = {
@@ -22,3 +22,32 @@ test("resolveMeta передаёт locale и origin в функции меты
 	]);
 	expect(seo.og?.locale).toBe("ru_RU");
 });
+
+test("breadcrumbsJsonLd строит BreadcrumbList с абсолютными @id", () => {
+	const node = breadcrumbsJsonLd(
+		[
+			{ label: "Главная", to: "/" },
+			{ label: "Тбилиси", to: "/tbilisi" },
+		],
+		"https://bina.rent/ru",
+	);
+	expect(node).toEqual({
+		"@context": "https://schema.org",
+		"@type": "BreadcrumbList",
+		itemListElement: [
+			{
+				"@type": "ListItem",
+				position: 1,
+				item: { "@id": "https://bina.rent/ru/", name: "Главная" },
+			},
+			{
+				"@type": "ListItem",
+				position: 2,
+				item: {
+					"@id": "https://bina.rent/ru/tbilisi",
+					name: "Тбилиси",
+				},
+			},
+		],
+	});
+});

package/src/seo/createPageMeta.ts

@@ -31,6 +31,9 @@ export type PageMetaOG = {
 /** узел JSON-LD; форма задаётся schema.org, здесь — только объект */
 export type JsonLd = Record<string, unknown>;
 
+/** крошка навигации: подпись и путь относительно basename роутера */
+export type PageMetaBreadcrumb = { label: string; to: string };
+
 export type PageMeta = {
 	title?: MetaValue<string>;
 	description?: MetaValue<string>;
@@ -39,6 +42,11 @@ export type PageMeta = {
 	og?: MetaValue<PageMetaOG | undefined>;
 	/** структурированные данные: по <script type="application/ld+json"> на узел */
 	jsonLD?: MetaValue<JsonLd[] | undefined>;
+	/**
+	 * Крошки страницы: роутер отдаёт их компоненту пропсом breadCrumbs
+	 * (готовая разметка), а <head> — узлом BreadcrumbList JSON-LD.
+	 */
+	breadcrumbs?: MetaValue<PageMetaBreadcrumb[] | undefined>;
 	/** HTTP-статус ответа (например 404 для «не найдено») */
 	status?: MetaValue<number>;
 };
@@ -49,6 +57,7 @@ export type ResolvedSeo = {
 	robots?: string;
 	og?: PageMetaOG;
 	jsonLD?: JsonLd[];
+	breadcrumbs?: PageMetaBreadcrumb[];
 	status?: number;
 };
 
@@ -73,13 +82,31 @@ export async function resolveMeta(
 	ctx: PageMetaContext,
 ): Promise<ResolvedSeo> {
 	if (!meta) return {};
-	const [title, description, robots, og, jsonLD, status] = await Promise.all([
-		resolveValue(meta.title, ctx),
-		resolveValue(meta.description, ctx),
-		resolveValue(meta.robots, ctx),
-		resolveValue(meta.og, ctx),
-		resolveValue(meta.jsonLD, ctx),
-		resolveValue(meta.status, ctx),
-	]);
-	return { title, description, robots, og, jsonLD, status };
+	const [title, description, robots, og, jsonLD, breadcrumbs, status] =
+		await Promise.all([
+			resolveValue(meta.title, ctx),
+			resolveValue(meta.description, ctx),
+			resolveValue(meta.robots, ctx),
+			resolveValue(meta.og, ctx),
+			resolveValue(meta.jsonLD, ctx),
+			resolveValue(meta.breadcrumbs, ctx),
+			resolveValue(meta.status, ctx),
+		]);
+	return { title, description, robots, og, jsonLD, breadcrumbs, status };
+}
+
+/** Узел BreadcrumbList для <head>; linkBase — origin + basename роутера. */
+export function breadcrumbsJsonLd(
+	breadcrumbs: PageMetaBreadcrumb[],
+	linkBase = "",
+): JsonLd {
+	return {
+		"@context": "https://schema.org",
+		"@type": "BreadcrumbList",
+		itemListElement: breadcrumbs.map(({ label, to }, index) => ({
+			"@type": "ListItem",
+			position: index + 1,
+			item: { "@id": linkBase + to, name: label },
+		})),
+	};
 }