@ryuzaki13/react-foundation-lib 1.4.1 → 1.4.2

package/src/range-output/README.mdx

@@ -0,0 +1,161 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="Foundation Lib/Data/Range Output" />
+
+# Подстановка открытых границ через `@ryuzaki13/react-foundation-lib/range-output`
+
+Модуль хранит в UI открытые границы диапазона как `null`, но позволяет подставить конкретные значения при внешнем выводе или сохранении.
+
+## Содержание
+
+- [Назначение](#назначение)
+- [Установка и импорт](#установка-и-импорт)
+- [Контракты](#контракты)
+- [`readRangeOutputValueFallback`](#readrangeoutputvaluefallback)
+- [`resolveRangeOutputValue`](#resolverangeoutputvalue)
+- [Правильная boundary](#правильная-boundary)
+- [API и ошибки](#api-и-ошибки)
+
+## Назначение
+
+```text
+UI range [null, 6]
+fallback { start: 0, end: 12 }
+              │
+              ▼
+external output [0, 6]
+```
+
+Исходное UI-значение не изменяется. `null` заменяется только при построении отдельного output tuple.
+
+## Установка и импорт
+
+```ts
+import { readRangeOutputValueFallback, resolveRangeOutputValue } from "@ryuzaki13/react-foundation-lib/range-output";
+
+import type { RangeOutputFallbackEndpointParser, RangeOutputValueFallback } from "@ryuzaki13/react-foundation-lib/range-output";
+```
+
+Модуль pure, не требует React/browser APIs.
+
+## Контракты
+
+```ts
+type RangeOutputValueFallback<TValue extends BaseType> = {
+	start?: TValue | null;
+	end?: TValue | null;
+};
+
+type RangeOutputFallbackEndpointParser<TValue extends BaseType> = (value: unknown) => TValue | null | undefined;
+```
+
+Смысл результата parser:
+
+| Результат parser | Что происходит                                  |
+| ---------------- | ----------------------------------------------- |
+| конкретное value | сохраняется как fallback                        |
+| `null`           | явная пустая fallback-граница                   |
+| `undefined`      | поле отсутствует/невалидно и не входит в result |
+
+## `readRangeOutputValueFallback`
+
+Функция читает только форму:
+
+```ts
+{
+	outputValueFallback: {
+		start: unknown,
+		end: unknown
+	}
+}
+```
+
+Пример числового parser:
+
+```ts
+function parseFiniteNumber(value: unknown): number | undefined {
+	const parsed = typeof value === "number" ? value : Number(value);
+	return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+const fallback = readRangeOutputValueFallback({ outputValueFallback: { start: "1", end: "bad" } }, parseFiniteNumber);
+
+console.log(fallback); // { start: 1 }.
+```
+
+Функция возвращает `undefined`, если:
+
+- верхний `props` не object-like record;
+- `outputValueFallback` не object-like record;
+- оба parser-result равны `undefined`.
+
+Parser вызывается отдельно для `start` и `end`, в том числе когда raw field отсутствует. Он не должен иметь side effects.
+
+`isRecord` здесь допускает не только plain object, но исключает arrays/null. Runtime schema конкретного значения полностью задаёт parser.
+
+## `resolveRangeOutputValue`
+
+```ts
+resolveRangeOutputValue([null, 6], { start: 0, end: 12 });
+// [0, 6].
+
+resolveRangeOutputValue([3, null], { start: 0, end: 12 });
+// [3, 12].
+```
+
+Правила для каждой позиции:
+
+1. Если UI endpoint не `null`, он возвращается буквально.
+2. Если endpoint равен `null`, используется соответствующий fallback.
+3. Если fallback отсутствует или равен `null`, output остаётся `null`.
+
+```ts
+resolveRangeOutputValue([null, null], { end: 12 });
+// [null, 12].
+
+resolveRangeOutputValue([null, null], undefined);
+// [null, null].
+```
+
+Всегда создаётся новый tuple. Вложенные ссылочные `Date` не клонируются.
+
+## Правильная boundary
+
+Helper специально отделяет UI draft и внешний snapshot:
+
+```ts
+const draftRange: readonly [number | null, number | null] = [null, 6];
+
+function getConfig() {
+	return {
+		range: resolveRangeOutputValue(draftRange, outputFallback)
+	};
+}
+```
+
+Не записывайте output обратно в draft:
+
+```text
+draft [null, 6] ───────────────► UI продолжает показывать открытую границу
+       │
+       └─ save boundary ───────► snapshot [0, 6]
+```
+
+Это output substitution, а не общая нормализация диапазона: порядок start/end, min/max и domain validation не проверяются.
+
+## API и ошибки
+
+| Export                              | Результат                       |
+| ----------------------------------- | ------------------------------- |
+| `RangeOutputValueFallback`          | Optional start/end fallback     |
+| `RangeOutputFallbackEndpointParser` | Parser одного endpoint          |
+| `readRangeOutputValueFallback`      | Parsed fallback или `undefined` |
+| `resolveRangeOutputValue`           | Новый output tuple              |
+
+Типичные ошибки:
+
+- Считать `0`, `false` или `""` отсутствующими: используется nullish logic, эти значения сохраняются.
+- Передавать `undefined` как UI endpoint при generic `TValue`, включающем undefined: заменяется только строго `null`.
+- Мутировать draft результатом output resolver.
+- Ожидать, что helper поменяет местами границы или проверит диапазон.
+- Делать parser через unsafe cast внешнего `unknown`.

package/src/seo/README.mdx

@@ -0,0 +1,279 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="Foundation Lib/HTTP/SEO" />
+
+# SEO
+
+Модуль `@ryuzaki13/react-foundation-lib/seo` собирает единый набор SEO-описаний страницы:
+
+- title и обычные meta tags;
+- Open Graph;
+- Twitter Card;
+- canonical link;
+- JSON-LD по Schema.org.
+
+Он не меняет `document.head` напрямую. Результат передаётся роутеру, SSR-фреймворку или собственному renderer head-тегов.
+
+## Импорт
+
+```ts
+import { createRouteHead, createSeoHead, type SeoContentType, type SeoHeadOptions } from "@ryuzaki13/react-foundation-lib/seo";
+```
+
+Функции синхронные и не требуют DOM, поэтому подходят для server rendering.
+
+## Быстрый старт
+
+```ts
+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"
+});
+```
+
+Результат имеет три массива:
+
+```ts
+{
+	meta: (Record < string, string > []);
+	links: (Record < string, string > []);
+	scripts: Array<{
+		type: "application/ld+json";
+		children: string;
+	}>;
+}
+```
+
+Форма совместима с распространённым route-head подходом, но конкретное подключение зависит от фреймворка.
+
+## `createSeoHead(options)`
+
+### Параметры
+
+```ts
+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;
+};
+```
+
+`caption` и `description` обязательны даже для пустой страницы. Библиотека не подставляет название сайта и не обрезает текст под лимиты поисковых систем.
+
+### Canonical URL
+
+Если `pathname` уже абсолютный URL, он нормализуется через `new URL()`.
+
+```ts
+createSeoHead({
+	pathname: "https://example.ru/catalog",
+	// baseUrl не нужен
+	caption: "Каталог",
+	description: "Каталог товаров",
+	type: "WebPage"
+});
+```
+
+Для относительного пути рекомендуется обязательно передавать абсолютный `baseUrl`:
+
+```ts
+pathname: "/catalog",
+baseUrl: "https://example.ru",
+// canonical: https://example.ru/catalog
+```
+
+Без `baseUrl` относительный путь сохраняется как есть. Это может быть приемлемо для некоторых head-renderer, но canonical URL по стандартной практике должен быть абсолютным.
+
+Неверный `baseUrl` вместе с относительным `pathname` приводит к исключению `new URL`. Проверяйте конфигурацию origin при старте приложения.
+
+### Meta tags
+
+Всегда создаются:
+
+- `{ title: caption }`;
+- description;
+- robots;
+- `og:type`, `og:title`, `og:description`, `og:url`, `og:locale`;
+- `twitter:card`, `twitter:title`, `twitter:description`.
+
+`Article` и `NewsArticle` получают Open Graph type `article`. `WebSite` и `WebPage` получают `website`.
+
+Локаль фиксирована как `ru_RU` для Open Graph и `ru-RU` для JSON-LD.
+
+Если есть изображение, Twitter Card становится `summary_large_image`; без изображения — `summary`.
+
+### Индексация
+
+```ts
+noIndex: true;
+// robots: "noindex, nofollow"
+```
+
+По умолчанию используется `index, follow`. `noIndex` формирует meta-инструкцию, но не заменяет серверные заголовки, robots.txt, авторизацию и запрет выдачи приватных страниц.
+
+### Keywords
+
+Непустой массив соединяется через `", "` и добавляется одновременно в обычный meta keywords и JSON-LD.
+
+```ts
+keywords: ["React", "TypeScript"];
+// "React, TypeScript"
+```
+
+Пустые строки внутри массива не удаляются автоматически.
+
+### Изображение
+
+Относительный `image.url` преобразуется с тем же `baseUrl`. Создаются `og:image` и `twitter:image`; при наличии `alt` дополнительно создаётся `og:image:alt`.
+
+В JSON-LD формируется `ImageObject`. Неуказанные `width`, `height` и `alt` остаются `undefined` либо `null` согласно исходным данным и поведению `JSON.stringify`.
+
+### Даты
+
+`publishedAt` и `modifiedAt` разбираются через стандартный `Date` и записываются в ISO UTC:
+
+```ts
+publishedAt: "2026-08-01T10:00:00+05:00";
+// datePublished: "2026-08-01T05:00:00.000Z"
+```
+
+Пустая или неверная дата молча не добавляется. Для предсказуемости передавайте ISO 8601 со временной зоной.
+
+## JSON-LD
+
+Каждый вызов создаёт один script descriptor:
+
+```ts
+{
+  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",
+  }),
+}
+```
+
+Библиотека возвращает строку, а не готовый React-элемент. Следуйте API head-renderer. Если вручную вставляете строку в HTML script, учитывайте XSS-границу: SEO-текст должен быть доверенным или безопасно экранированным renderer. Простого `JSON.stringify` недостаточно для произвольного пользовательского текста, содержащего последовательности вроде закрывающего `script`-тега.
+
+## `createRouteHead(type, path, params)`
+
+Упрощённый адаптер для данных route loader/CMS:
+
+```ts
+type SeoHeadParams = {
+	caption: string;
+	description: string;
+	previewImage: string | null;
+	previewImageAlt: string | null;
+	created: string;
+	updated: string;
+};
+```
+
+```ts
+const head = createRouteHead("NewsArticle", "/news/42", loaderData?.seo);
+```
+
+Адаптер:
+
+- передаёт `path` как `pathname`;
+- при `null`/`undefined` params подставляет пустые `caption` и `description`;
+- превращает `previewImage` в `image`;
+- сопоставляет `created` с `publishedAt`, `updated` с `modifiedAt`;
+- не передаёт `baseUrl`, keywords или `noIndex`.
+
+Поэтому URL результата останется относительным, если `path` относительный. Когда нужен абсолютный canonical, используйте полный `createSeoHead` либо передавайте абсолютный `path`.
+
+## Пример с TanStack Router
+
+```tsx
+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
+		})
+});
+```
+
+Проверьте точную форму `head` вашей версии роутера: библиотека возвращает структурные данные, но не связывается с router напрямую.
+
+## Проверка результата
+
+Для каждой важной страницы проверьте:
+
+1. canonical абсолютный и соответствует публичному URL;
+2. title и description не пусты;
+3. Open Graph image доступно без авторизации;
+4. JSON-LD проходит validator Schema.org/поисковой системы;
+5. preview SSR HTML содержит теги до выполнения JavaScript;
+6. приватные страницы имеют правильную политику индексации.
+
+## Частые ошибки
+
+### Передавать относительный путь без `baseUrl`
+
+Функция не знает публичный origin приложения и оставит URL относительным.
+
+### Считать `createRouteHead` полным аналогом `createSeoHead`
+
+Адаптер специально узкий и не принимает base URL, keywords, размеры image и `noIndex`.
+
+### Передавать локальную дату без timezone
+
+Результат стандартного `Date` может зависеть от окружения. Используйте полный ISO 8601.
+
+### Генерировать SEO только после client fetch
+
+Для надёжной индексации head должен появляться в SSR/pre-render HTML, если архитектура приложения это поддерживает.
+
+### Передавать недоверенный текст напрямую в JSON-LD script
+
+Используйте безопасный renderer и контролируйте источник SEO-полей.
+
+## Краткая карта API
+
+| Экспорт                               | Назначение                                     |
+| ------------------------------------- | ---------------------------------------------- |
+| `createSeoHead(options)`              | Собрать полный meta/link/JSON-LD набор         |
+| `createRouteHead(type, path, params)` | Адаптировать типичные route SEO-поля           |
+| `SeoContentType`                      | Допустимый Schema.org content type             |
+| `SeoHeadOptions`                      | Полная конфигурация страницы                   |
+| `SeoHeadParams`                       | Входные данные упрощённого route adapter       |
+| `SeoImage`                            | URL и описательные размеры preview-изображения |

package/src/session-storage/README.mdx

@@ -0,0 +1,125 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="Foundation Lib/Browser/Session Storage ID" />
+
+# Идентификатор вкладочной сессии через `@ryuzaki13/react-foundation-lib/session-storage`
+
+`getSessionStorageId` возвращает стабильный id в пределах одной browser-вкладки. При первом вызове id создаётся и сохраняется в `sessionStorage`, при следующих — читается по тому же ключу.
+
+## Установка и импорт
+
+```ts
+import { getSessionStorageId } from "@ryuzaki13/react-foundation-lib/session-storage";
+```
+
+Default generator — `uuidv4` из `/crypto`.
+
+## Базовый пример
+
+```ts
+const sessionId = getSessionStorageId("sales-app.error-report.session.v1");
+```
+
+Повторный вызов в той же вкладке:
+
+```ts
+const first = getSessionStorageId("sales-app.session.v1");
+const second = getSessionStorageId("sales-app.session.v1");
+
+console.log(first === second); // true, если storage доступен.
+```
+
+Другая вкладка имеет отдельный `sessionStorage` и обычно получит другой id.
+
+## Алгоритм
+
+```text
+sessionStorage недоступен ──► createId() без сохранения
+          │
+          ▼
+getItem(key)
+  ├─ непустая строка ──────► вернуть её
+  └─ нет значения ─────────► createId() → setItem → вернуть id
+
+ошибка getItem/setItem ─────► fallback createId()
+```
+
+```ts
+const id = getSessionStorageId("demo.session", () => "known-id");
+```
+
+Второй аргумент удобен для теста или другого генератора.
+
+## Граница стабильности
+
+Идентификатор стабилен только при успешном storage:
+
+- reload той же вкладки обычно сохраняет значение;
+- новая вкладка получает своё storage;
+- закрытие вкладки удаляет session storage по правилам браузера;
+- privacy policy, sandbox iframe или переполнение могут запретить доступ;
+- если storage недоступен, каждый вызов может создать новый fallback id.
+
+Функция ловит ошибки чтения/записи и не ломает основной пользовательский сценарий.
+
+Если `setItem` выбросил ошибку после первого вызова generator, fallback generator может быть вызван повторно. Не используйте `createId` с внешними необратимыми side effects.
+
+## Ключ storage
+
+Ключ полностью задаёт host. Рекомендуемый формат:
+
+```text
+<app-id>.<purpose>.v<schema-version>
+```
+
+Примеры:
+
+```text
+sales-app.error-report.session.v1
+warehouse.telemetry.tab-session.v2
+```
+
+Не используйте один ключ для несвязанных подсистем. При изменении семантики меняйте версию.
+
+## SSR и безопасность
+
+Вне browser `sessionStorage` отсутствует, поэтому функция просто возвращает новый id generator-а. Она не пытается создать server session.
+
+```ts
+const id = getSessionStorageId("demo", () => "server-fallback");
+```
+
+Идентификатор:
+
+- не является authentication token;
+- не подтверждает пользователя;
+- не должен давать доступ к данным;
+- не является cross-tab device id;
+- не должен включать персональные данные.
+
+Для долговременного client fingerprint используйте отдельный `/fingerprint`, понимая его privacy-границы.
+
+## Тестирование
+
+```ts
+sessionStorage.clear();
+
+const createId = vi.fn(() => "session-1");
+
+expect(getSessionStorageId("test.session", createId)).toBe("session-1");
+expect(getSessionStorageId("test.session", () => "session-2")).toBe("session-1");
+expect(createId).toHaveBeenCalledOnce();
+```
+
+Очищайте `sessionStorage` между тестами.
+
+## API и ошибки
+
+```ts
+function getSessionStorageId(key: string, createId?: () => string): string;
+```
+
+- Пустой сохранённый string считается отсутствующим и заменяется.
+- Ключ и результат generator не валидируются.
+- Исключение самого fallback generator может быть проброшено.
+- Функция ничего не удаляет из storage.

package/src/string-comparison/README.mdx

@@ -0,0 +1,96 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="Foundation Lib/Data/String Comparison" />
+
+# Сравнение строк через `@ryuzaki13/react-foundation-lib/string-comparison`
+
+`compareStrings` задаёт единый порядок строк для русскоязычных UI-списков, смешанной кириллицы/латиницы и числовых суффиксов.
+
+## Установка и импорт
+
+```ts
+import { compareStrings } from "@ryuzaki13/react-foundation-lib/string-comparison";
+```
+
+Модуль использует стандартный `Intl.Collator` и не зависит от React.
+
+## Использование
+
+```ts
+const names = ["item10", "item2", "item1"];
+const sorted = [...names].sort(compareStrings);
+
+console.log(sorted); // ["item1", "item2", "item10"].
+console.log(names); // Исходный массив не изменён из-за [...names].
+```
+
+Важно: сам `Array.prototype.sort` мутирует массив. `compareStrings` только comparator.
+
+```ts
+names.sort(compareStrings); // names изменится.
+```
+
+## Правила сравнения
+
+Основной collator настроен так:
+
+```ts
+new Intl.Collator("ru-RU", {
+	usage: "sort",
+	sensitivity: "base",
+	numeric: true
+});
+```
+
+Это означает:
+
+- locale фиксирован как `ru-RU`, а не зависит от системного языка;
+- числовые части сравниваются как числа: `item2` раньше `item10`;
+- основной проход не различает регистр и часть диакритики;
+- если collator считает разные строки равными, применяется строгий UTF-16 fallback;
+- результат нормализуется до `-1`, `0` или `1`.
+
+```ts
+["a", "A"].sort(compareStrings); // ["A", "a"].
+```
+
+UTF-16 fallback нужен для детерминированного порядка, а не для лингвистической оценки регистра.
+
+## Контракт comparator
+
+```ts
+function compareStrings(left: string, right: string): number;
+```
+
+| Результат | Значение                                        |
+| --------: | ----------------------------------------------- |
+|      `-1` | `left` должен находиться раньше `right`         |
+|       `0` | строки полностью равны для итогового comparator |
+|       `1` | `left` должен находиться позже `right`          |
+
+Подходящие места:
+
+- `array.sort` / `toSorted`;
+- сортировка labels справочника;
+- предсказуемый порядок смешанных технических и русских названий;
+- tie-breaker после бизнес-сортировки.
+
+## Ограничения
+
+- Аргументы должны быть strings; функция не приводит `null`/число.
+- Это UI-сортировка, а не database collation или backend `$orderby`.
+- Не используйте comparator для equality/identity: разные строки могут быть близки по основной collation.
+- Порядок не является Unicode normalization; при необходимости нормализуйте вход на явной boundary.
+- Для server-side таблицы сортировку полного набора должен выполнять backend, а не одна загруженная страница.
+- Runtime должен поддерживать `Intl.Collator` и locale data `ru-RU`.
+
+## Пример с объектами
+
+```ts
+type Option = { id: string; label: string };
+
+const sortedOptions = options.toSorted((left, right) => {
+	const byLabel = compareStrings(left.label, right.label);
+	return byLabel !== 0 ? byLabel : compareStrings(left.id, right.id);
+});
+```