@ryuzaki13/react-foundation-lib 1.4.1 → 1.4.2

package/src/validators/README.mdx

@@ -0,0 +1,239 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="Foundation Lib/Validation/Runtime Guards" />
+
+# Runtime guards и validators через `@ryuzaki13/react-foundation-lib/validators`
+
+Модуль содержит небольшие проверки для `unknown`, object-like значений, image extensions, positive integer, URL и Floating UI DOM reference.
+
+> Название функции не расширяет её контракт. Например, `isSafe` проверяет только отсутствие `null`/`undefined`, а `isRecord` допускает `Date` и `Map`. Ниже указано точное поведение каждой проверки.
+
+## Содержание
+
+- [Установка и импорт](#установка-и-импорт)
+- [Как работают type guards](#как-работают-type-guards)
+- [`isSafe`](#issafe)
+- [`isObject`, `isRecord`, `asRecord`](#isobject-isrecord-asrecord)
+- [`isPlainObject`](#isplainobject)
+- [`readPositiveInteger`](#readpositiveinteger)
+- [Image extensions](#image-extensions)
+- [`isDomReference`](#isdomreference)
+- [`validateUrl`](#validateurl)
+- [Security boundary](#security-boundary)
+- [Полный API](#полный-api)
+
+## Установка и импорт
+
+```ts
+import {
+	asRecord,
+	IMAGE_EXTENSIONS,
+	isDomReference,
+	isImageExtension,
+	isObject,
+	isPlainObject,
+	isRecord,
+	isSafe,
+	readPositiveInteger,
+	validateUrl
+} from "@ryuzaki13/react-foundation-lib/validators";
+```
+
+`isDomReference` использует type из `@floating-ui/react`; host entrypoint должен разрешить совместимую peer dependency. Остальные функции не требуют React.
+
+## Как работают type guards
+
+Type guard возвращает boolean и помогает TypeScript сузить значение:
+
+```ts
+function readCode(value: unknown): string | undefined {
+	if (!isRecord(value)) return undefined;
+	return typeof value.code === "string" ? value.code : undefined;
+}
+```
+
+Guard не преобразует значение и не гарантирует поля, которые сам не проверил.
+
+## `isSafe`
+
+```ts
+function isSafe<T>(value: T | null | undefined): value is T;
+```
+
+Возвращает `false` только для `null` и `undefined`:
+
+```ts
+[0, "", false, null, undefined, "ok"].filter(isSafe);
+// [0, "", false, "ok"].
+```
+
+`0`, пустая строка и `false` являются безопасными в смысле этой функции. `isSafe` не проверяет XSS, SQL, URL, число, object schema или authorization.
+
+## `isObject`, `isRecord`, `asRecord`
+
+Три функции используют одинаковую базовую проверку: значение truthy, `typeof === "object"`, не array.
+
+| Вход         | `isObject` / `isRecord` | `asRecord`                             |
+| ------------ | :---------------------: | -------------------------------------- |
+| `{}`         |         `true`          | тот же object                          |
+| `new Date()` |         `true`          | тот же Date, типизированный как record |
+| `new Map()`  |         `true`          | тот же Map                             |
+| DOM element  |         `true`          | тот же element                         |
+| `[]`         |         `false`         | `null`                                 |
+| `null`       |         `false`         | `null`                                 |
+| function     |         `false`         | `null`                                 |
+
+`isObject` сужает до `object`, `isRecord` — до `Record<string, unknown>`, `asRecord` возвращает record или `null`.
+
+Они не проверяют plain object и не гарантируют JSON-compatible данные.
+
+## `isPlainObject`
+
+Возвращает `true`, только если prototype равен `Object.prototype` или `null`:
+
+```ts
+isPlainObject({}); // true.
+isPlainObject(Object.create(null)); // true.
+isPlainObject(new Date()); // false.
+isPlainObject(new Map()); // false.
+```
+
+Сигнатура принимает `object`, поэтому сначала сузьте `unknown`:
+
+```ts
+if (isObject(value) && isPlainObject(value)) {
+	// Plain record-like object.
+}
+```
+
+Прямой runtime-вызов `isPlainObject(null as never)` приведёт к ошибке `Object.getPrototypeOf`. TypeScript contract запрещает такой аргумент.
+
+## `readPositiveInteger`
+
+```ts
+readPositiveInteger(12); // 12.
+readPositiveInteger("12"); // 12.
+readPositiveInteger(" 12 "); // 12.
+readPositiveInteger(0); // undefined.
+readPositiveInteger(-1); // undefined.
+readPositiveInteger(1.5); // undefined.
+readPositiveInteger("bad"); // undefined.
+```
+
+String преобразуется стандартным `Number(value)`, затем проверяются:
+
+- runtime type number;
+- `Number.isInteger`;
+- значение строго больше `0`.
+
+Следствия стандартного `Number`:
+
+```ts
+readPositiveInteger("1e2"); // 100.
+readPositiveInteger("0x10"); // 16.
+readPositiveInteger(""); // undefined, потому что Number("") = 0.
+```
+
+Если формат input должен быть только decimal digits, дополнительно проверьте строковую грамматику на своей boundary.
+
+## Image extensions
+
+```ts
+isImageExtension("PNG"); // true.
+isImageExtension("svg"); // true.
+isImageExtension("pdf"); // false.
+```
+
+Список:
+
+```ts
+["png", "jpg", "jpeg", "gif", "webp", "svg"];
+```
+
+Проверка регистронезависима через `toLowerCase`, но не делает trim и ожидает расширение без точки:
+
+```ts
+isImageExtension(".png"); // false.
+isImageExtension(" png "); // false.
+```
+
+`IMAGE_EXTENSIONS` экспортирован как изменяемый array по текущему типу. Рассматривайте его как библиотечную константу и не вызывайте `push/splice`.
+
+Расширение имени не доказывает MIME/type и безопасность содержимого. Для file/image boundary используйте `/file` и server-side validation.
+
+## `isDomReference`
+
+```ts
+if (isDomReference(floatingReference)) {
+	floatingReference.focus();
+}
+```
+
+Возвращает `true`, только если reference является browser `Element`. Virtual element Floating UI и `null` возвращают `false`.
+
+Функция выполняет `ref instanceof Element`. В server runtime без global `Element` её вызов может привести к `ReferenceError`; вызывайте только в browser boundary или после проверки DOM environment.
+
+## `validateUrl`
+
+```ts
+const result = validateUrl("https://example.com/path");
+
+if (!result.isValid) {
+	showError(result.error);
+}
+```
+
+Возможные результаты:
+
+```ts
+{ isValid: true, error: "" }
+{ isValid: false, error: "URL не может быть пустым" }
+{ isValid: false, error: "URL слишком длинный" }
+{ isValid: false, error: "URL содержит недопустимые символы" }
+{ isValid: false, error: "Некорректный формат URL" }
+```
+
+Алгоритм:
+
+1. Отклоняет пустую строку.
+2. Если строка не начинается с lowercase `http`, временно добавляет `https://` для `new URL`.
+3. Проверяет длину исходной строки не больше `2048`.
+4. Применяет консервативное регулярное выражение.
+
+Поддерживаемая грамматика намеренно узкая:
+
+- optional `http://` или `https://`;
+- domain с точкой;
+- lowercase TLD длиной 2–6 по regex;
+- простой path из ограниченного набора символов.
+
+Query string, hash, port, localhost, IP-адреса, internationalized domains, многие валидные Unicode/path characters и длинные современные TLD могут быть отклонены.
+
+## Security boundary
+
+`validateUrl` — UI-проверка формата, не security policy. Она не:
+
+- проверяет allowlist host/protocol;
+- делает DNS resolution;
+- защищает backend от SSRF;
+- гарантирует отсутствие redirect на опасный host;
+- проверяет доступность ресурса;
+- санитизирует HTML;
+- подтверждает, что URL ведёт на изображение.
+
+Для внешней навигации/запроса применяйте отдельную security policy владельца boundary.
+
+## Полный API
+
+| Export                | Точное назначение                       |
+| --------------------- | --------------------------------------- |
+| `isSafe`              | Исключает `null`/`undefined`            |
+| `isObject`            | Non-array truthy object                 |
+| `isRecord`            | Та же runtime-проверка с record type    |
+| `asRecord`            | Record или `null`                       |
+| `isPlainObject`       | Проверяет prototype                     |
+| `readPositiveInteger` | Positive integer number или `undefined` |
+| `IMAGE_EXTENSIONS`    | Список поддерживаемых extensions        |
+| `isImageExtension`    | Регистронезависимая проверка extension  |
+| `isDomReference`      | Floating reference является `Element`   |
+| `validateUrl`         | Консервативный UI URL result            |

package/src/virtualizer/README.mdx

@@ -0,0 +1,138 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="Foundation Lib/React/Virtualizer Pagination" />
+
+# Дозагрузка virtualized списка через `@ryuzaki13/react-foundation-lib/virtualizer`
+
+`useFetchNextPageEffect` вызывает `fetchNextPage`, когда последняя отрендеренная virtual item достигает конца уже загруженного списка.
+
+## Установка и импорт
+
+```bash
+npm install react @tanstack/react-virtual @ryuzaki13/react-foundation-lib
+```
+
+```ts
+import { useFetchNextPageEffect } from "@ryuzaki13/react-foundation-lib/virtualizer";
+```
+
+Host должен использовать совместимые peer dependencies React `>=19.2 <20` и `@tanstack/react-virtual >=3.14 <4`.
+
+## Назначение и границы
+
+```text
+virtualItems (видимый диапазон)
+currentItemsCount (сколько уже загружено)
+hasNextPage
+          │
+последний virtual index >= currentItemsCount - 1
+          │
+          ▼
+fetchNextPage() один раз до завершения Promise
+```
+
+Hook не создаёт virtualizer, не хранит backend data, не строит query key и не решает server pagination. TanStack Query должен оставаться владельцем server snapshot.
+
+## Сигнатура
+
+```ts
+useFetchNextPageEffect({
+	virtualItems,
+	currentItemsCount,
+	fetchNextPage,
+	hasNextPage
+});
+```
+
+| Поле                | Значение                             |
+| ------------------- | ------------------------------------ |
+| `virtualItems`      | Текущий массив `VirtualItem[]`       |
+| `currentItemsCount` | Число реально загруженных data items |
+| `hasNextPage`       | Есть ли следующая server page        |
+| `fetchNextPage`     | Stable функция, возвращающая Promise |
+
+Hook ничего не возвращает.
+
+## Пример с TanStack Query/Virtual
+
+```tsx
+const rows = query.data?.pages.flatMap((page) => page.rows) ?? [];
+const virtualItems = virtualizer.getVirtualItems();
+
+useFetchNextPageEffect({
+	virtualItems,
+	currentItemsCount: rows.length,
+	hasNextPage: query.hasNextPage,
+	fetchNextPage: async () => {
+		await query.fetchNextPage();
+	}
+});
+```
+
+Передавайте количество загруженных строк, а не virtual total с loader row, group headers или estimated backend count.
+
+## Точный trigger
+
+Fetch не запускается, если:
+
+- `virtualItems` пуст;
+- `currentItemsCount` равен `0`;
+- последняя virtual item ещё не достигла `currentItemsCount - 1`;
+- `hasNextPage === false`;
+- предыдущий вызов ещё не завершился.
+
+Trigger происходит строго на последнем загруженном индексе. Preload threshold «за N строк до конца» в API отсутствует.
+
+## Защита от параллельного fetch
+
+Внутренний `useRef(false)` устанавливается до вызова и сбрасывается в `.finally()`:
+
+```text
+idle ── trigger ──► fetchingRef=true
+                       │
+                 Promise pending
+                       │
+             resolve или reject
+                       ▼
+                 fetchingRef=false
+```
+
+Защита действует только внутри одного mounted hook instance. TanStack Query также должен владеть дедупликацией/network state.
+
+Если `fetchNextPage` отклоняет Promise, hook не добавляет `.catch`; rejection может стать unhandled. Передавайте функцию с принятой error policy или wrapper, который корректно обрабатывает ожидаемую ошибку.
+
+## Referential stability
+
+Effect зависит от `virtualItems`, `currentItemsCount`, `hasNextPage`, `fetchNextPage`.
+
+- Используйте значение virtualizer как предусмотрено его API.
+- Не создавайте лишний async callback с новой identity без причины.
+- React Compiler не отменяет необходимость stable external contract.
+- После увеличения `currentItemsCount` новый fetch произойдёт только когда virtual range достигнет нового конца.
+
+## Browser, SSR и lifecycle
+
+Сам hook не читает `window`, но является React effect и не выполняет fetch во время server render. В browser effect запускается после commit.
+
+При unmount Promise не отменяется. Abort/cancel должен быть реализован query/transport owner. `fetchingRef` больше не влияет после удаления hook instance.
+
+## Типичные ошибки
+
+- Передать total backend rows вместо количества загруженного массива.
+- Включить client-side sorting/filtering одной страницы при server-side модели.
+- Добавить фиктивный loader row в `currentItemsCount`.
+- Ожидать preload заранее — trigger находится на самом конце.
+- Передать rejecting Promise без error handling.
+- Выполнять fetch прямо в row render вместо effect.
+- Использовать изменяемый index как domain identity строки.
+
+## API
+
+```ts
+function useFetchNextPageEffect(args: {
+	virtualItems: VirtualItem[];
+	currentItemsCount: number;
+	hasNextPage: boolean;
+	fetchNextPage: () => Promise<unknown>;
+}): void;
+```

package/src/xml/README.mdx

@@ -0,0 +1,149 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="Foundation Lib/Data/XML" />
+
+# Простые XML helpers через `@ryuzaki13/react-foundation-lib/xml`
+
+Модуль экранирует XML-текст, строит последовательность простых полей и читает текст первого тега через `DOMParser`.
+
+## Содержание
+
+- [Назначение и границы](#назначение-и-границы)
+- [Установка и импорт](#установка-и-импорт)
+- [`escapeXmlValue`](#escapexmlvalue)
+- [`buildXmlFields`](#buildxmlfields)
+- [`getXmlTagText`](#getxmltagtext)
+- [Безопасность и ограничения](#безопасность-и-ограничения)
+- [API](#api)
+
+## Назначение и границы
+
+Подходит для небольших flat XML fragments:
+
+```xml
+<ORDER_ID>42</ORDER_ID><COMMENT>A&amp;B</COMMENT>
+```
+
+Модуль не является полноценным XML builder/parser:
+
+- не строит document/envelope;
+- не управляет namespaces и attributes;
+- не валидирует XSD;
+- не обрабатывает коллекции/вложенные объекты;
+- не проверяет parser errors;
+- не выполняет network request.
+
+## Установка и импорт
+
+```ts
+import { buildXmlFields, escapeXmlValue, getXmlTagText } from "@ryuzaki13/react-foundation-lib/xml";
+
+import type { XmlPrimitive } from "@ryuzaki13/react-foundation-lib/xml";
+```
+
+Builder-функции не требуют DOM. `getXmlTagText` требует global `DOMParser`, доступный в браузере/jsdom, но обычно отсутствующий в чистом Node.js.
+
+## `escapeXmlValue`
+
+```ts
+escapeXmlValue(`a&b<c>d"e'f`);
+// "a&amp;b&lt;c&gt;d&quot;e&apos;f"
+```
+
+Тип входа:
+
+```ts
+type XmlPrimitive = string | number | null | undefined;
+```
+
+Правила:
+
+| Символ | XML entity |
+| ------ | ---------- |
+| `&`    | `&amp;`    |
+| `<`    | `&lt;`     |
+| `>`    | `&gt;`     |
+| `"`    | `&quot;`   |
+| `'`    | `&apos;`   |
+
+`null` и `undefined` превращаются в пустую строку. Number сначала преобразуется через `String`.
+
+Функция предназначена для текстового содержимого. Для attribute value она экранирует основные символы, но сам attribute builder модуль не предоставляет.
+
+Не передавайте уже экранированную строку повторно:
+
+```ts
+escapeXmlValue("A&amp;B"); // "A&amp;amp;B".
+```
+
+## `buildXmlFields`
+
+```ts
+const xml = buildXmlFields({
+	ORDER_ID: 42,
+	COMMENT: "A&B",
+	OPTIONAL: null
+});
+
+// <ORDER_ID>42</ORDER_ID><COMMENT>A&amp;B</COMMENT><OPTIONAL></OPTIONAL>
+```
+
+Функция:
+
+- обходит `Object.entries` в стандартном порядке ключей;
+- строит для каждого поля `<NAME>escaped value</NAME>`;
+- не добавляет переносы строк;
+- сохраняет поля с `null`/`undefined` как пустые теги;
+- не изменяет исходный объект.
+
+Имя тега вставляется без валидации и escaping. Ключи должны быть доверенными валидными XML names из программного contract:
+
+```ts
+// Нельзя строить key из пользовательского ввода.
+buildXmlFields({ [userProvidedTagName]: value });
+```
+
+Для вложенной структуры передайте уже собранный fragment как часть внешнего builder-а; `buildXmlFields` сам воспринимает строку как текст и экранирует markup.
+
+## `getXmlTagText`
+
+```ts
+const message = getXmlTagText("<root><EX_MESSAGE>  Ошибка  </EX_MESSAGE></root>", "EX_MESSAGE");
+
+console.log(message); // "Ошибка".
+```
+
+Алгоритм:
+
+1. Парсит всю строку как `application/xml`.
+2. Вызывает `getElementsByTagName(tagName)`.
+3. Берёт только первый найденный element.
+4. Читает объединённый `textContent`.
+5. Обрезает пробелы.
+6. Возвращает `undefined`, если элемента/непустого текста нет.
+
+```ts
+getXmlTagText("<root />", "MESSAGE"); // undefined.
+getXmlTagText("<root><MESSAGE>   </MESSAGE></root>", "MESSAGE"); // undefined.
+```
+
+Для namespace-sensitive XML точное поведение `getElementsByTagName` зависит от переданного имени. Модуль не предоставляет `getElementsByTagNameNS`.
+
+## Безопасность и ограничения
+
+- Не вставляйте результат XML в HTML DOM через `innerHTML`.
+- Не используйте dynamic tag names из недоверенного ввода.
+- Parser не проверяется на `<parsererror>`; malformed XML обычно даёт `undefined` или parser-specific tree, а не явное исключение этого helper.
+- Читается только первое совпадение.
+- Большие documents лучше разбирать специализированным parser/streaming boundary.
+- Модуль не предотвращает XML signature wrapping и не предназначен для security validation.
+- `XmlPrimitive` number допускает `NaN`/`Infinity` на уровне TypeScript; они станут строками `"NaN"`/`"Infinity"`.
+
+## API
+
+| Export           | Результат                               |
+| ---------------- | --------------------------------------- |
+| `escapeXmlValue` | Экранированная строка                   |
+| `buildXmlFields` | Компактный XML fragment                 |
+| `getXmlTagText`  | `string \| undefined`                   |
+| `XmlPrimitive`   | `string \| number \| null \| undefined` |