@ryuzaki13/react-foundation-ui 1.8.11 → 1.8.13

package/storybook-static/assets/README-eg1emlll.js

@@ -0,0 +1,192 @@
+import{n as e}from"./rolldown-runtime-DkW27tQK.js";import{n as t}from"./iframe-o7sH2IXC.js";import{i as n,r}from"./react-Bl2r1tuC.js";import{l as i,m as a}from"./blocks-BY40djCc.js";function o(e){let t={code:`code`,h1:`h1`,h2:`h2`,h3:`h3`,li:`li`,ol:`ol`,p:`p`,pre:`pre`,table:`table`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,ul:`ul`,...n(),...e.components};return(0,c.jsxs)(c.Fragment,{children:[(0,c.jsx)(i,{title:`Foundation Lib/HTTP/SEO`}),`
+`,(0,c.jsx)(t.h1,{id:`seo`,children:`SEO`}),`
+`,(0,c.jsxs)(t.p,{children:[`Модуль `,(0,c.jsx)(t.code,{children:`@ryuzaki13/react-foundation-lib/seo`}),` собирает единый набор SEO-описаний страницы:`]}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsx)(t.li,{children:`title и обычные meta tags;`}),`
+`,(0,c.jsx)(t.li,{children:`Open Graph;`}),`
+`,(0,c.jsx)(t.li,{children:`Twitter Card;`}),`
+`,(0,c.jsx)(t.li,{children:`canonical link;`}),`
+`,(0,c.jsx)(t.li,{children:`JSON-LD по Schema.org.`}),`
+`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Он не меняет `,(0,c.jsx)(t.code,{children:`document.head`}),` напрямую. Результат передаётся роутеру, SSR-фреймворку или собственному renderer head-тегов.`]}),`
+`,(0,c.jsx)(t.h2,{id:`импорт`,children:`Импорт`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import { createRouteHead, createSeoHead, type SeoContentType, type SeoHeadOptions } from "@ryuzaki13/react-foundation-lib/seo";
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Функции синхронные и не требуют DOM, поэтому подходят для server rendering.`}),`
+`,(0,c.jsx)(t.h2,{id:`быстрый-старт`,children:`Быстрый старт`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const head = createSeoHead({
+	pathname: "/articles/odata-guide",
+	baseUrl: "https://example.ru",
+	caption: "Практический гайд по OData",
+	description: "Разбираем фильтры, сортировку и пагинацию OData.",
+	type: "Article",
+	keywords: ["OData", "TypeScript", "SAP"],
+	image: {
+		url: "/images/odata-guide.webp",
+		alt: "Схема OData-запроса",
+		width: 1200,
+		height: 630
+	},
+	publishedAt: "2026-08-01T10:00:00+05:00",
+	modifiedAt: "2026-08-20T12:30:00+05:00"
+});
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Результат имеет три массива:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`{
+	meta: (Record < string, string > []);
+	links: (Record < string, string > []);
+	scripts: Array<{
+		type: "application/ld+json";
+		children: string;
+	}>;
+}
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Форма совместима с распространённым route-head подходом, но конкретное подключение зависит от фреймворка.`}),`
+`,(0,c.jsx)(t.h2,{id:`createseoheadoptions`,children:(0,c.jsx)(t.code,{children:`createSeoHead(options)`})}),`
+`,(0,c.jsx)(t.h3,{id:`параметры`,children:`Параметры`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type SeoContentType = "WebSite" | "WebPage" | "Article" | "NewsArticle";
+
+type SeoHeadOptions = {
+	pathname: string;
+	caption: string;
+	description: string;
+	type: SeoContentType;
+	baseUrl?: string;
+	keywords?: string[];
+	image?: {
+		url: string;
+		alt?: string | null;
+		width?: number | null;
+		height?: number | null;
+	};
+	publishedAt?: string;
+	modifiedAt?: string;
+	noIndex?: boolean;
+};
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`caption`}),` и `,(0,c.jsx)(t.code,{children:`description`}),` обязательны даже для пустой страницы. Библиотека не подставляет название сайта и не обрезает текст под лимиты поисковых систем.`]}),`
+`,(0,c.jsx)(t.h3,{id:`canonical-url`,children:`Canonical URL`}),`
+`,(0,c.jsxs)(t.p,{children:[`Если `,(0,c.jsx)(t.code,{children:`pathname`}),` уже абсолютный URL, он нормализуется через `,(0,c.jsx)(t.code,{children:`new URL()`}),`.`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`createSeoHead({
+	pathname: "https://example.ru/catalog",
+	// baseUrl не нужен
+	caption: "Каталог",
+	description: "Каталог товаров",
+	type: "WebPage"
+});
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Для относительного пути рекомендуется обязательно передавать абсолютный `,(0,c.jsx)(t.code,{children:`baseUrl`}),`:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`pathname: "/catalog",
+baseUrl: "https://example.ru",
+// canonical: https://example.ru/catalog
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Без `,(0,c.jsx)(t.code,{children:`baseUrl`}),` относительный путь сохраняется как есть. Это может быть приемлемо для некоторых head-renderer, но canonical URL по стандартной практике должен быть абсолютным.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Неверный `,(0,c.jsx)(t.code,{children:`baseUrl`}),` вместе с относительным `,(0,c.jsx)(t.code,{children:`pathname`}),` приводит к исключению `,(0,c.jsx)(t.code,{children:`new URL`}),`. Проверяйте конфигурацию origin при старте приложения.`]}),`
+`,(0,c.jsx)(t.h3,{id:`meta-tags`,children:`Meta tags`}),`
+`,(0,c.jsx)(t.p,{children:`Всегда создаются:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`{ title: caption }`}),`;`]}),`
+`,(0,c.jsx)(t.li,{children:`description;`}),`
+`,(0,c.jsx)(t.li,{children:`robots;`}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`og:type`}),`, `,(0,c.jsx)(t.code,{children:`og:title`}),`, `,(0,c.jsx)(t.code,{children:`og:description`}),`, `,(0,c.jsx)(t.code,{children:`og:url`}),`, `,(0,c.jsx)(t.code,{children:`og:locale`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`twitter:card`}),`, `,(0,c.jsx)(t.code,{children:`twitter:title`}),`, `,(0,c.jsx)(t.code,{children:`twitter:description`}),`.`]}),`
+`]}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`Article`}),` и `,(0,c.jsx)(t.code,{children:`NewsArticle`}),` получают Open Graph type `,(0,c.jsx)(t.code,{children:`article`}),`. `,(0,c.jsx)(t.code,{children:`WebSite`}),` и `,(0,c.jsx)(t.code,{children:`WebPage`}),` получают `,(0,c.jsx)(t.code,{children:`website`}),`.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Локаль фиксирована как `,(0,c.jsx)(t.code,{children:`ru_RU`}),` для Open Graph и `,(0,c.jsx)(t.code,{children:`ru-RU`}),` для JSON-LD.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Если есть изображение, Twitter Card становится `,(0,c.jsx)(t.code,{children:`summary_large_image`}),`; без изображения — `,(0,c.jsx)(t.code,{children:`summary`}),`.`]}),`
+`,(0,c.jsx)(t.h3,{id:`индексация`,children:`Индексация`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`noIndex: true;
+// robots: "noindex, nofollow"
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`По умолчанию используется `,(0,c.jsx)(t.code,{children:`index, follow`}),`. `,(0,c.jsx)(t.code,{children:`noIndex`}),` формирует meta-инструкцию, но не заменяет серверные заголовки, robots.txt, авторизацию и запрет выдачи приватных страниц.`]}),`
+`,(0,c.jsx)(t.h3,{id:`keywords`,children:`Keywords`}),`
+`,(0,c.jsxs)(t.p,{children:[`Непустой массив соединяется через `,(0,c.jsx)(t.code,{children:`", "`}),` и добавляется одновременно в обычный meta keywords и JSON-LD.`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`keywords: ["React", "TypeScript"];
+// "React, TypeScript"
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Пустые строки внутри массива не удаляются автоматически.`}),`
+`,(0,c.jsx)(t.h3,{id:`изображение`,children:`Изображение`}),`
+`,(0,c.jsxs)(t.p,{children:[`Относительный `,(0,c.jsx)(t.code,{children:`image.url`}),` преобразуется с тем же `,(0,c.jsx)(t.code,{children:`baseUrl`}),`. Создаются `,(0,c.jsx)(t.code,{children:`og:image`}),` и `,(0,c.jsx)(t.code,{children:`twitter:image`}),`; при наличии `,(0,c.jsx)(t.code,{children:`alt`}),` дополнительно создаётся `,(0,c.jsx)(t.code,{children:`og:image:alt`}),`.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`В JSON-LD формируется `,(0,c.jsx)(t.code,{children:`ImageObject`}),`. Неуказанные `,(0,c.jsx)(t.code,{children:`width`}),`, `,(0,c.jsx)(t.code,{children:`height`}),` и `,(0,c.jsx)(t.code,{children:`alt`}),` остаются `,(0,c.jsx)(t.code,{children:`undefined`}),` либо `,(0,c.jsx)(t.code,{children:`null`}),` согласно исходным данным и поведению `,(0,c.jsx)(t.code,{children:`JSON.stringify`}),`.`]}),`
+`,(0,c.jsx)(t.h3,{id:`даты`,children:`Даты`}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`publishedAt`}),` и `,(0,c.jsx)(t.code,{children:`modifiedAt`}),` разбираются через стандартный `,(0,c.jsx)(t.code,{children:`Date`}),` и записываются в ISO UTC:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`publishedAt: "2026-08-01T10:00:00+05:00";
+// datePublished: "2026-08-01T05:00:00.000Z"
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Пустая или неверная дата молча не добавляется. Для предсказуемости передавайте ISO 8601 со временной зоной.`}),`
+`,(0,c.jsx)(t.h2,{id:`json-ld`,children:`JSON-LD`}),`
+`,(0,c.jsx)(t.p,{children:`Каждый вызов создаёт один script descriptor:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`{
+  type: "application/ld+json",
+  children: JSON.stringify({
+    "@context": "https://schema.org",
+    "@type": type,
+    mainEntityOfPage: { "@type": "WebPage", "@id": canonicalUrl },
+    headline: caption,
+    description,
+    url: canonicalUrl,
+    inLanguage: "ru-RU",
+  }),
+}
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Библиотека возвращает строку, а не готовый React-элемент. Следуйте API head-renderer. Если вручную вставляете строку в HTML script, учитывайте XSS-границу: SEO-текст должен быть доверенным или безопасно экранированным renderer. Простого `,(0,c.jsx)(t.code,{children:`JSON.stringify`}),` недостаточно для произвольного пользовательского текста, содержащего последовательности вроде закрывающего `,(0,c.jsx)(t.code,{children:`script`}),`-тега.`]}),`
+`,(0,c.jsx)(t.h2,{id:`createrouteheadtype-path-params`,children:(0,c.jsx)(t.code,{children:`createRouteHead(type, path, params)`})}),`
+`,(0,c.jsx)(t.p,{children:`Упрощённый адаптер для данных route loader/CMS:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type SeoHeadParams = {
+	caption: string;
+	description: string;
+	previewImage: string | null;
+	previewImageAlt: string | null;
+	created: string;
+	updated: string;
+};
+`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const head = createRouteHead("NewsArticle", "/news/42", loaderData?.seo);
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Адаптер:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[`передаёт `,(0,c.jsx)(t.code,{children:`path`}),` как `,(0,c.jsx)(t.code,{children:`pathname`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`при `,(0,c.jsx)(t.code,{children:`null`}),`/`,(0,c.jsx)(t.code,{children:`undefined`}),` params подставляет пустые `,(0,c.jsx)(t.code,{children:`caption`}),` и `,(0,c.jsx)(t.code,{children:`description`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`превращает `,(0,c.jsx)(t.code,{children:`previewImage`}),` в `,(0,c.jsx)(t.code,{children:`image`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`сопоставляет `,(0,c.jsx)(t.code,{children:`created`}),` с `,(0,c.jsx)(t.code,{children:`publishedAt`}),`, `,(0,c.jsx)(t.code,{children:`updated`}),` с `,(0,c.jsx)(t.code,{children:`modifiedAt`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`не передаёт `,(0,c.jsx)(t.code,{children:`baseUrl`}),`, keywords или `,(0,c.jsx)(t.code,{children:`noIndex`}),`.`]}),`
+`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Поэтому URL результата останется относительным, если `,(0,c.jsx)(t.code,{children:`path`}),` относительный. Когда нужен абсолютный canonical, используйте полный `,(0,c.jsx)(t.code,{children:`createSeoHead`}),` либо передавайте абсолютный `,(0,c.jsx)(t.code,{children:`path`}),`.`]}),`
+`,(0,c.jsx)(t.h2,{id:`пример-с-tanstack-router`,children:`Пример с TanStack Router`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-tsx`,children:`export const Route = createFileRoute("/articles/$slug")({
+	loader: loadArticle,
+	head: ({ loaderData, params }) =>
+		createSeoHead({
+			pathname: \`/articles/\${params.slug}\`,
+			baseUrl: "https://example.ru",
+			caption: loaderData.title,
+			description: loaderData.description,
+			type: "Article",
+			image: loaderData.image ? { url: loaderData.image, alt: loaderData.title } : undefined
+		})
+});
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Проверьте точную форму `,(0,c.jsx)(t.code,{children:`head`}),` вашей версии роутера: библиотека возвращает структурные данные, но не связывается с router напрямую.`]}),`
+`,(0,c.jsx)(t.h2,{id:`проверка-результата`,children:`Проверка результата`}),`
+`,(0,c.jsx)(t.p,{children:`Для каждой важной страницы проверьте:`}),`
+`,(0,c.jsxs)(t.ol,{children:[`
+`,(0,c.jsx)(t.li,{children:`canonical абсолютный и соответствует публичному URL;`}),`
+`,(0,c.jsx)(t.li,{children:`title и description не пусты;`}),`
+`,(0,c.jsx)(t.li,{children:`Open Graph image доступно без авторизации;`}),`
+`,(0,c.jsx)(t.li,{children:`JSON-LD проходит validator Schema.org/поисковой системы;`}),`
+`,(0,c.jsx)(t.li,{children:`preview SSR HTML содержит теги до выполнения JavaScript;`}),`
+`,(0,c.jsx)(t.li,{children:`приватные страницы имеют правильную политику индексации.`}),`
+`]}),`
+`,(0,c.jsx)(t.h2,{id:`частые-ошибки`,children:`Частые ошибки`}),`
+`,(0,c.jsxs)(t.h3,{id:`передавать-относительный-путь-без-baseurl`,children:[`Передавать относительный путь без `,(0,c.jsx)(t.code,{children:`baseUrl`})]}),`
+`,(0,c.jsx)(t.p,{children:`Функция не знает публичный origin приложения и оставит URL относительным.`}),`
+`,(0,c.jsxs)(t.h3,{id:`считать-createroutehead-полным-аналогом-createseohead`,children:[`Считать `,(0,c.jsx)(t.code,{children:`createRouteHead`}),` полным аналогом `,(0,c.jsx)(t.code,{children:`createSeoHead`})]}),`
+`,(0,c.jsxs)(t.p,{children:[`Адаптер специально узкий и не принимает base URL, keywords, размеры image и `,(0,c.jsx)(t.code,{children:`noIndex`}),`.`]}),`
+`,(0,c.jsx)(t.h3,{id:`передавать-локальную-дату-без-timezone`,children:`Передавать локальную дату без timezone`}),`
+`,(0,c.jsxs)(t.p,{children:[`Результат стандартного `,(0,c.jsx)(t.code,{children:`Date`}),` может зависеть от окружения. Используйте полный ISO 8601.`]}),`
+`,(0,c.jsx)(t.h3,{id:`генерировать-seo-только-после-client-fetch`,children:`Генерировать SEO только после client fetch`}),`
+`,(0,c.jsx)(t.p,{children:`Для надёжной индексации head должен появляться в SSR/pre-render HTML, если архитектура приложения это поддерживает.`}),`
+`,(0,c.jsx)(t.h3,{id:`передавать-недоверенный-текст-напрямую-в-json-ld-script`,children:`Передавать недоверенный текст напрямую в JSON-LD script`}),`
+`,(0,c.jsx)(t.p,{children:`Используйте безопасный renderer и контролируйте источник SEO-полей.`}),`
+`,(0,c.jsx)(t.h2,{id:`краткая-карта-api`,children:`Краткая карта API`}),`
+`,(0,c.jsxs)(t.table,{children:[(0,c.jsx)(t.thead,{children:(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.th,{children:`Экспорт`}),(0,c.jsx)(t.th,{children:`Назначение`})]})}),(0,c.jsxs)(t.tbody,{children:[(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`createSeoHead(options)`})}),(0,c.jsx)(t.td,{children:`Собрать полный meta/link/JSON-LD набор`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`createRouteHead(type, path, params)`})}),(0,c.jsx)(t.td,{children:`Адаптировать типичные route SEO-поля`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`SeoContentType`})}),(0,c.jsx)(t.td,{children:`Допустимый Schema.org content type`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`SeoHeadOptions`})}),(0,c.jsx)(t.td,{children:`Полная конфигурация страницы`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`SeoHeadParams`})}),(0,c.jsx)(t.td,{children:`Входные данные упрощённого route adapter`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`SeoImage`})}),(0,c.jsx)(t.td,{children:`URL и описательные размеры preview-изображения`})]})]})]})]})}function s(e={}){let{wrapper:t}={...n(),...e.components};return t?(0,c.jsx)(t,{...e,children:(0,c.jsx)(o,{...e})}):o(e)}var c;function l(){return(l=e((()=>{c=t(),r(),a()})))()}l();export{s as default};