@ryuzaki13/react-foundation-lib 1.2.5 → 1.2.7

package/src/docs/pureUtilities.mdx

@@ -0,0 +1,96 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="Foundation Lib/Чистые utilities и contracts" />
+
+# Чистые utilities и contracts
+
+Эти API не создают global state и обычно не требуют React. Они полезны в entity/feature code, если задача остаётся предметно-независимой. Не переносите в них доменные правила только ради повторного использования.
+
+## Коллекции, порядок и ограниченная история
+
+```ts
+import { arrayGroupBy, arrayUniqueBy, moveArrayItem } from "@ryuzaki13/react-foundation-lib/array";
+import { pushBoundedCopyStackItem } from "@ryuzaki13/react-foundation-lib/bounded-copy-stack";
+```
+
+| API                                                                    | Поведение                                                                                                  |
+| ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `arrayGroupBy`, `arrayGroupByToArray`, `arrayToMap`                    | Группируют/индексируют по полю объекта. `arrayToMap` оставляет первое значение ключа.                      |
+| `arrayUniqueBy`, `arrayDeduplicate`                                    | Immutable deduplication с сохранением первого встретившегося значения/порядка.                             |
+| `filterAndDeduplicateIds`, `appendMissingIds`, `pickExistingMapValues` | Helpers для stable id lists и ordered Map values.                                                          |
+| `arraysEqual`                                                          | Строго сравнивает длину, порядок и значения по `===`.                                                      |
+| `moveItem`, `moveArrayItem`, `moveArrayItemByIndex`                    | Возвращают новую переставленную коллекцию; invalid indices не мутируют input.                              |
+| `normalizeObjects`, `normalizeStringArray`, `addUnique`                | Explicit canonicalization для внешней/сохранённой структуры — не вызывайте её внутри literal draft setter. |
+
+`pushBoundedCopyStackItem(stack, input, options?)` добавляет/поднимает item по `fingerprint` и ограничивает размер (default `DEFAULT_BOUNDED_COPY_STACK_SIZE = 3`). `getBoundedCopyStackCandidates` фильтрует готовый stack predicate-ом. `BoundedCopyStackItem`, `BoundedCopyStackPushInput`, `BoundedCopyStackOptions` и `BoundedCopyStackPushResult` описывают его serializable contract.
+
+## Значения, шкалы и календарные сегменты
+
+```ts
+import { parseDateSegmentMask, indexedSegmentsToDate } from "@ryuzaki13/react-foundation-lib/date-segments";
+import { snapNumberScaleValue } from "@ryuzaki13/react-foundation-lib/number-scale";
+import { resolveRangeOutputValue } from "@ryuzaki13/react-foundation-lib/range-output";
+```
+
+| Entry point         | Основной API                                                                                                                                                                                                                                                                                                             |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `date-segments`     | `parseDateSegmentMask`, `isEditableDateSegment`, `dateToIndexedSegmentValues`, `areAllDateSegmentsEmpty`, `indexedSegmentsToDate`. `indexedSegmentsToDate` строго отвергает невозможную дату/время; `DateMaskSegment` описывает editable/literal segments.                                                               |
+| `number-scale`      | `resolveNumberScaleBounds`, `clampNumberScaleValue`, `normalizeNumberScaleStep`, `prepareNumberScaleMarks`, `snapNumberScaleValueToStep`, `snapNumberScaleValueToMarks`, `snapNumberScaleValue`, `valueToNumberScalePercent`, `percentToNumberScaleValue`, `percentToSnappedNumberScaleValue`, `offsetNumberScaleValue`. |
+| `currency`          | `resolveCurrencyModeFromODataParameters` и `resolveCurrencyAwareLabel`; это label policy по wrapped OData parameters, не currency formatter.                                                                                                                                                                             |
+| `range-output`      | `readRangeOutputValueFallback` и `resolveRangeOutputValue`; подставляет fallback только для `null` открытой границы и не меняет исходный UI range.                                                                                                                                                                       |
+| `presets`           | `normalizePresetIds`, `resolvePresetOptionsByIds`, `getPresetOption`, `PresetOption`; помогает на save/restore boundary для известного набора IDs.                                                                                                                                                                       |
+| `string-comparison` | `compareStrings(left, right)` использует fixed Russian numeric/case-insensitive collation с deterministic fallback.                                                                                                                                                                                                      |
+
+Для date/number UI formatting используйте `formatters`, а не `number-scale`/`currency`.
+
+## Clone, строки, keyboard и trees
+
+```ts
+import { cn, deepCloneWithoutFunctions, deepCopyWithoutFunctions, stableStringify } from "@ryuzaki13/react-foundation-lib/utils";
+```
+
+| API                                                                                                  | Контракт                                                                                                                                                            |
+| ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cn(...args)`                                                                                        | Собирает className из строк и conditional object. `classNames` — deprecated alias; новый код использует `cn`.                                                       |
+| `stableStringify(value)`                                                                             | JSON-like stable serialization с сортировкой object keys — для key/comparison, не как универсальный persistence format.                                             |
+| `deepCopyWithoutFunctions(value, options?)`                                                          | Копирует Date, arrays и plain objects, поддерживает cycles; функции пропускает. Unsupported object бросает `TypeError`. Предназначен для serializable plain config. |
+| `deepCloneWithoutFunctions(value, options?)`                                                         | Расширенный clone: Date, RegExp, Map, Set, cycles, sparse arrays и optional prototype. Функции пропускает.                                                          |
+| `createLazyComponent`, `childrenCount`                                                               | React-adjacent helpers для stable lazy component и correct children count.                                                                                          |
+| `keyboardActivationKeys`, `isKeyboardActivationKey`, `handleKeyboardActivation`                      | Keyboard activation contract для custom control.                                                                                                                    |
+| `getRovingFocusTargetIndex`, `findFirstEnabledIndex`, `findLastEnabledIndex`, `findNextEnabledIndex` | Pure navigation для listbox/select с disabled/wrap.                                                                                                                 |
+| `deepCopyNodes`, `deepCopyTree`                                                                      | Копирование tree nodes с standard/custom children field.                                                                                                            |
+| `toBase64`, `encodeBase64`, `logError`                                                               | Unicode-safe base64 и centralised error logging.                                                                                                                    |
+
+Clone не является нормализацией: он создаёт независимую структуру в пределах собственного contract и не должен применять trim, defaults, deduplication или reorder к пользовательскому draft. Для plain serializable config используйте `deepCopyWithoutFunctions`, а не `structuredClone`.
+
+## Runtime guards и базовые типы
+
+```ts
+import { asRecord, isRecord, isSafe, readPositiveInteger } from "@ryuzaki13/react-foundation-lib/validators";
+import type { BaseType, RangeType, RowRecord, State } from "@ryuzaki13/react-foundation-lib/types";
+```
+
+| API                                                 | Когда использовать                                                         |
+| --------------------------------------------------- | -------------------------------------------------------------------------- |
+| `isSafe`                                            | Убирает только `null`/`undefined` из union.                                |
+| `isObject`, `isRecord`, `asRecord`, `isPlainObject` | Narrow unknown external value до object/record; array не считается record. |
+| `readPositiveInteger`                               | Возвращает positive integer или `undefined` без unsafe cast.               |
+| `validateUrl`                                       | Возвращает validation result для строки URL.                               |
+| `IMAGE_EXTENSIONS`, `isImageExtension`              | Проверка расширения без учёта регистра; не MIME/security validation.       |
+| `isDomReference`                                    | Floating UI reference → DOM `Element` guard.                               |
+
+`State`, `AbapBoolean`, `Primitive`, `BaseType`, `ArrayType`, `ObjectType`, `InputType`, `RangeType`, `RowRecord`, `isBaseType` — общие low-level contracts. Не используйте `RowRecord` как модель конкретной доменной сущности.
+
+## Идентификаторы, HTTP, XML, SEO и form errors
+
+| Entry point       | API                                                                                                                                                                 |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `crypto`          | `hashString`, `hashString128`, `hashString128Base64Url`, `stringToElementId`, `uuidv4`. Hash служит для stable client key, не криптографической защиты.             |
+| `session-storage` | `getSessionStorageId(key, createId?)` — scoped browser-tab id; не authentication token.                                                                             |
+| `http`            | `createNoStoreHeaders(init?)` создаёт Headers с no-store; `createTextHttpResponse(options)` создаёт text `Response`.                                                |
+| `xml`             | `escapeXmlValue`, `buildXmlFields`, `getXmlTagText` для небольших XML fragments. Не применяйте regex helper как универсальный XML parser для untrusted complex XML. |
+| `seo`             | `createSeoHead(options)`, `createRouteHead(type, path, params)` создают `meta`, `links`, JSON-LD `scripts`; host router/head owner решает, как применить результат. |
+| `form`            | `readFirstFormError(errors?)` выбирает первое readable error message из unknown error array.                                                                        |
+| `error`           | `createMissingContextErrorMessage`, `createMissingContextError` формируют единообразную ошибку отсутствующего React Provider.                                       |
+
+`fingerprint` и `notifications` описаны на странице Runtime/state, потому что имеют browser/global lifecycle.

package/src/docs/runtimeAndState.mdx

@@ -0,0 +1,155 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="Foundation Lib/Runtime, state и diagnostics" />
+
+# Runtime, state и diagnostics
+
+Этот раздел содержит инфраструктурные API, которые создаются в composition root host-приложения. Они не должны подключаться из каждой feature: persistence, BroadcastChannel, notifications и error reporting имеют глобальный lifecycle и приватные данные.
+
+## `query-client`: TanStack Query инфраструктура
+
+```ts
+import {
+	configureQueryPersistenceProjectAdapter,
+	createQueryClient,
+	installReactQueryBroadcast,
+	installSessionScopedQueryReset,
+	persistedQueryMeta,
+	resetSessionScopedQueries,
+	sessionScopedQueryMeta
+} from "@ryuzaki13/react-foundation-lib/query-client";
+```
+
+### Composition root
+
+1. До создания `QueryClient` вызовите `configureQueryPersistenceProjectAdapter` при необходимости задать application-specific `persistenceBuster` и `resolveSystemIdentifier`.
+2. Создайте один `QueryClient` через `createQueryClient({ onQueryError?, onMutationError? })`.
+3. В browser bootstrap установите sync/reset channels и обязательно сохраните их `cleanup` для shutdown/tests.
+
+```ts
+configureQueryPersistenceProjectAdapter({
+	persistenceBuster: "host-v1",
+	resolveSystemIdentifier: () => "host-production"
+});
+
+const queryClient = createQueryClient({
+	onQueryError: (error, query) => reportQueryError(error, query)
+});
+
+const broadcast = installReactQueryBroadcast(queryClient, {
+	queriesChannel: "host-query-cache",
+	eventsChannel: "host-query-events"
+});
+const sessionReset = installSessionScopedQueryReset(queryClient, {
+	channelName: "host-session-reset"
+});
+
+// teardown: broadcast.cleanup(); sessionReset.cleanup();
+```
+
+### Persistence, session scope и broadcast
+
+| API                                                      | Когда использовать                                                                                                |
+| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `persistedQueryMeta`                                     | `meta` query только для публичных, serializable данных, которым разрешено переживать restart.                     |
+| `sessionScopedQueryMeta`                                 | `meta` query, чей результат зависит от текущей server session/role. Такой query никогда не сохраняется.           |
+| `shouldPersistQuery(query)`                              | Predicate persistence: true лишь для `persist: true` без `sessionScoped`.                                         |
+| `createIndexedDbQueryStorage(options?)`                  | Создаёт async IndexedDB storage либо `undefined`, если API недоступен.                                            |
+| `createReactQueryPersister()`                            | Создаёт TanStack persister с 90-дневным max age или `undefined`.                                                  |
+| `installReactQueryBroadcast(queryClient, channels)`      | Синхронизирует Query cache и explicit invalidate/set events между вкладками; возвращает `{ broadcast, cleanup }`. |
+| `broadcastCacheEvent(event)` / `setBroadcastFn(fn)`      | Imperative bridge для explicit cache event. Настраивается один раз в composition root.                            |
+| `resetSessionScopedQueries(queryClient, { broadcast? })` | Отменяет, очищает и refetches active session-scoped queries после логина, логаута или смены роли.                 |
+| `installSessionScopedQueryReset(...)`                    | Рассылает только команду reset, не query data; возвращает cleanup.                                                |
+
+Не отмечайте query обоими meta-флагами. Не кладите в persisted/broadcast cache tokens, персональные данные без принятой политики, DOM nodes, функции или class instances.
+
+### Оптимистичная мутация
+
+`onMutateOptimistic`, `onErrorOptimistic`, `onSuccessOptimistic`, `onSettledOptimistic` — low-level helpers для одного известного cache key. `onMutateOptimistic` сначала отменяет запросы, сохраняет `previous`, затем применяет patch. Контекст обязательно передаётся в `onError` для rollback.
+
+```ts
+useMutation({
+	mutationFn: updateTodo,
+	onMutate: (input) => onMutateOptimistic(queryClient, todoKey, (old) => patchTodo(old, input)),
+	onError: (_error, _input, context) => onErrorOptimistic(queryClient, todoKey, context),
+	onSettled: () => onSettledOptimistic(queryClient, todoKey, { refetchType: "active" })
+});
+```
+
+`OnSettledOptimisticOptions.refetchType` defaults to `"none"`. Не применяйте helper к непонятно широкому key: cache strategy должен владеть entity/feature, а не shared infrastructure.
+
+## `error-report`: безопасный diagnostic draft
+
+```ts
+import {
+	captureQueryErrorReport,
+	captureRuntimeErrorReport,
+	getErrorReportDrafts,
+	installErrorReportBrowserBreadcrumbs,
+	setErrorReportRuntimeErrorReporter,
+	setErrorReportTransportErrorReporter
+} from "@ryuzaki13/react-foundation-lib/error-report";
+```
+
+Пакет подготавливает, sanitizes и локально сохраняет diagnostic draft. Он **не** отправляет отчёт в backend сам: transport/delivery принадлежит соответствующему API-пакету или host integration.
+
+| Группа API       | Контракт                                                                                                                                                                                        |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Environment      | `isErrorReportingEnabled`, `getErrorReportEnvironment`, `getErrorReportClientEnvironment` дают browser/non-dev gate и минимальный runtime context.                                              |
+| Safe values      | `createDiagnosticValue`, `createDataShape`, `sanitizeDetail`, `createErrorInfo` превращают `unknown` в serializable diagnostic form. Не передавайте секреты даже в sanitizing API.              |
+| Breadcrumbs      | `addErrorReportBreadcrumb`, `getErrorReportBreadcrumbs`, `clearErrorReportBreadcrumbs`, `installErrorReportBrowserBreadcrumbs`. Установка browser listener возвращает cleanup.                  |
+| Capture          | `captureQueryErrorReport`, `captureMutationErrorReport`, `captureRuntimeErrorReport` создают `ErrorReportDraft` с query/mutation/runtime diagnostics.                                           |
+| Drafts           | `captureErrorReportDraft`, `getErrorReportDraft`, `getErrorReportDrafts`, `updateErrorReportDraft` управляют локальными draft.                                                                  |
+| Reporting bridge | `setErrorReportRuntimeErrorReporter` + `reportRuntimeError`; `setErrorReportTransportErrorReporter`, `reportTransportError`, `suppressTransportErrorReport`, `isTransportErrorReportScheduled`. |
+| Diagnostics      | `collectQueryDiagnostics`, `collectMutationDiagnostics`, `collectQueryClientDiagnostics`, `collectPersistedQueryDiagnostics`.                                                                   |
+
+### Подключение reporter-а
+
+```ts
+setErrorReportRuntimeErrorReporter(async (error, context) => {
+	const draft = captureRuntimeErrorReport(error, context, queryClient);
+	// Передайте draft в owner transport только после собственной privacy policy.
+	await deliverDiagnosticDraft(await draft);
+});
+```
+
+`ErrorReportPayload`, `ErrorReportDraft`, `ErrorReportBreadcrumb`, `ErrorReportErrorInfo`, `ErrorReportSafeValue` и context types — публичные contracts для typed delivery. Runtime capture в браузере coalesces одинаковые ошибки на коротком окне, чтобы flood не создавал много draft. Не дублируйте transport report: `capture*` корректно вызывает `suppressTransportErrorReport` для исходной ошибки.
+
+## `notifications`: global imperative facade
+
+```ts
+import { bindNotifications, createNotificationsStore, notify } from "@ryuzaki13/react-foundation-lib/notifications";
+```
+
+```ts
+const notificationsStore = createNotificationsStore();
+const unbind = bindNotifications(notificationsStore);
+
+notify.success("Сохранено");
+const progress = notify.progress("Загрузка…");
+progress.success("Готово");
+
+// teardown composition root: unbind();
+```
+
+| API                                       | Назначение                                                                                                     |
+| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `createNotificationsStore()`              | Создаёт Zustand store с max 6 items и timer cleanup. Вызов только в browser-compatible UI composition.         |
+| `bindNotifications(store)`                | Связывает единственный store с imperative `notify`; возвращает unbind. До bind любой `notify.*` бросает Error. |
+| `notify.push/upsert/update/dismiss/clear` | Imperative actions над `NotificationPushInput`/`NotificationUpdatePatch`.                                      |
+| `notify.success/info/warning/error`       | Удобные typed shortcuts.                                                                                       |
+| `notify.progress(message, opts?)`         | Возвращает `{ id, update, success, error, dismiss }` для долгой операции.                                      |
+
+`Notification`, `NotificationAction`, `NotificationType`, `NotificationTone`, `NotificationId` описывают данные, а не UI rendering. UI owner подписывается на `NotificationsStoreApi` и отвечает за accessibility/визуал.
+
+## OData collection preferences, session и fingerprint
+
+```ts
+import { odataCollectionConfig, useODataCollectionStore } from "@ryuzaki13/react-foundation-lib/odata";
+import { getSessionStorageId } from "@ryuzaki13/react-foundation-lib/session-storage";
+import { getClientFingerprint } from "@ryuzaki13/react-foundation-lib/fingerprint";
+```
+
+`odataCollectionConfig` даёт selectors для общих UI-defaults (`maxVisibleItems`, min search lengths, debounce); `useODataCollectionStore` даёт state и setters. Это клиентские предпочтения, не backend data и не metadata cache.
+
+`getSessionStorageId(key, createId?)` возвращает стабильный ID одной вкладки из `sessionStorage`; при storage failure всё равно вернёт новый ID. `getClientFingerprint()` асинхронно возвращает fingerprint или `null`, если библиотека/API недоступны. Не используйте fingerprint как authentication/authorization credential.

package/src/foundationLib.mdx

@@ -0,0 +1,105 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="Foundation Lib/Обзор" />
+
+# `@ryuzaki13/react-foundation-lib`
+
+Технический фундамент для host-приложений: чистые преобразования данных, browser/React hooks, сериализуемые runtime-контракты, OData metadata helpers и инфраструктура состояния. Пакет не знает домен приложения, UI-компоненты и transport конкретного backend.
+
+## Подключение
+
+```bash
+npm install @ryuzaki13/react-foundation-lib
+```
+
+Пакет ESM и намеренно **не имеет корневого импорта**. Подключайте ровно тот опубликованный subpath, который нужен сценарию:
+
+```ts
+import { formatDateAsDate } from "@ryuzaki13/react-foundation-lib/formatters";
+import { createQueryClient } from "@ryuzaki13/react-foundation-lib/query-client";
+import type { RowRecord } from "@ryuzaki13/react-foundation-lib/types";
+```
+
+```ts
+// Неверно: корневой entrypoint не опубликован.
+import { formatDateAsDate } from "@ryuzaki13/react-foundation-lib";
+```
+
+## Граница ответственности
+
+| Задача                                                     | Использовать                              | Не использовать вместо этого         |
+| ---------------------------------------------------------- | ----------------------------------------- | ------------------------------------ |
+| Чистые OData V2 metadata, path, filter и value helpers     | `odata-service`                           | HTTP/OData transport                 |
+| Вызовы SAP Gateway, SSO, X-CSRF и TanStack Query operation | `@ryuzaki13/react-foundation-api/odata`   | ручной `fetch` или этот пакет        |
+| UI primitives и дизайн-система                             | `@ryuzaki13/react-foundation-ui/<module>` | hooks/utilities из lib как компонент |
+| Доменный mapping и пользовательский сценарий               | host entity/feature                       | foundation-lib                       |
+
+`react-foundation-lib` не создаёт бизнес-правила, не хранит backend snapshot и не заменяет API- или UI-пакеты.
+
+## Среда выполнения и peer dependencies
+
+Большинство pure helpers не требуют React. Entry point с React hook, DOM, browser storage или Service Worker должен вызываться только в браузерном runtime и по правилам React hooks. Совместимые peer dependencies должны быть разрешены host-проектом для используемого entrypoint.
+
+| Возможность                                     | Когда нужна в host                                                           |
+| ----------------------------------------------- | ---------------------------------------------------------------------------- |
+| `react`                                         | `hooks`, `dom`, `copy`, `media`, `pwa`, `three-scene`, selection/table hooks |
+| `@tanstack/react-query`, persistence, broadcast | `query-client`, часть `error-report`                                         |
+| `@tanstack/react-table`                         | `table`                                                                      |
+| `@tanstack/react-virtual`                       | `virtualizer`                                                                |
+| `@tanstack/react-router`                        | search helpers из `hooks`                                                    |
+| `@floating-ui/react`                            | `useFloatingListbox`, DOM reference guards                                   |
+| `@dnd-kit/core`, `@dnd-kit/sortable`            | `useDndSortableSensors`                                                      |
+| `zustand`, `immer`                              | `notifications`, OData store                                                 |
+| `zod`                                           | `odata-service` schemas                                                      |
+| `write-excel-file`                              | `excel`                                                                      |
+
+## Выбор entrypoint
+
+| Сценарий                                             | Точный import                                         |
+| ---------------------------------------------------- | ----------------------------------------------------- |
+| Массивы, дедупликация, grouping, reorder             | `@ryuzaki13/react-foundation-lib/array`               |
+| Base64 и `Blob`                                      | `@ryuzaki13/react-foundation-lib/binary`              |
+| Ограниченный стек копий                              | `@ryuzaki13/react-foundation-lib/bounded-copy-stack`  |
+| Anchor и state контекстного меню                     | `@ryuzaki13/react-foundation-lib/context-menu`        |
+| Clipboard и feedback hooks                           | `@ryuzaki13/react-foundation-lib/copy`                |
+| Hash и UUID                                          | `@ryuzaki13/react-foundation-lib/crypto`              |
+| Валютные labels по OData-параметрам                  | `@ryuzaki13/react-foundation-lib/currency`            |
+| Сегменты маски даты                                  | `@ryuzaki13/react-foundation-lib/date-segments`       |
+| Portal, focus, observers, browser download           | `@ryuzaki13/react-foundation-lib/dom`                 |
+| Ошибка отсутствующего React context                  | `@ryuzaki13/react-foundation-lib/error`               |
+| Подготовка и диагностика error report                | `@ryuzaki13/react-foundation-lib/error-report`        |
+| Excel и экспорт таблиц                               | `@ryuzaki13/react-foundation-lib/excel`               |
+| `FileReader`, MIME, Content-Disposition, изображения | `@ryuzaki13/react-foundation-lib/file`                |
+| Client fingerprint                                   | `@ryuzaki13/react-foundation-lib/fingerprint`         |
+| Form errors и presets                                | `@ryuzaki13/react-foundation-lib/form`                |
+| Даты, числа, строки, pipeline и value state          | `@ryuzaki13/react-foundation-lib/formatters`          |
+| Реестр и выполнение клиентских формул таблицы        | `@ryuzaki13/react-foundation-lib/formulas`            |
+| Общие React hooks                                    | `@ryuzaki13/react-foundation-lib/hooks`               |
+| HTTP headers и text `Response`                       | `@ryuzaki13/react-foundation-lib/http`                |
+| Breakpoints и media-query hooks                      | `@ryuzaki13/react-foundation-lib/media`               |
+| Imperative notifications и store                     | `@ryuzaki13/react-foundation-lib/notifications`       |
+| Математика slider/scale                              | `@ryuzaki13/react-foundation-lib/number-scale`        |
+| OData code/text collections и store                  | `@ryuzaki13/react-foundation-lib/odata`               |
+| OData V2 metadata, builder, filters, formats         | `@ryuzaki13/react-foundation-lib/odata-service`       |
+| Нормализация сохранённых preset ids                  | `@ryuzaki13/react-foundation-lib/presets`             |
+| Service Worker update и cache policy                 | `@ryuzaki13/react-foundation-lib/pwa`                 |
+| Только cache policy                                  | `@ryuzaki13/react-foundation-lib/pwa/sw-cache-policy` |
+| QueryClient, persistence, broadcast                  | `@ryuzaki13/react-foundation-lib/query-client`        |
+| Вывод открытых границ диапазона                      | `@ryuzaki13/react-foundation-lib/range-output`        |
+| SEO/head metadata contracts                          | `@ryuzaki13/react-foundation-lib/seo`                 |
+| ID в `sessionStorage`                                | `@ryuzaki13/react-foundation-lib/session-storage`     |
+| Предсказуемое строковое сравнение                    | `@ryuzaki13/react-foundation-lib/string-comparison`   |
+| TanStack Table layout, selection и OData adapter     | `@ryuzaki13/react-foundation-lib/table`               |
+| Проверка доступности Three.js                        | `@ryuzaki13/react-foundation-lib/three-scene`         |
+| Построение tree-table rows                           | `@ryuzaki13/react-foundation-lib/tree-table`          |
+| Общие TypeScript contracts                           | `@ryuzaki13/react-foundation-lib/types`               |
+| Clone, className, keyboard, stable stringify, tree   | `@ryuzaki13/react-foundation-lib/utils`               |
+| Runtime guards и URL/image validation                | `@ryuzaki13/react-foundation-lib/validators`          |
+| Infinite-query подгрузка virtualizer                 | `@ryuzaki13/react-foundation-lib/virtualizer`         |
+| XML parse/build                                      | `@ryuzaki13/react-foundation-lib/xml`                 |
+
+## Как читать справочник
+
+Каждая последующая страница построена вокруг **published subpath**, а не каталога исходников. В ней указаны точный import, публичные contracts, обязательная инициализация, результат, lifecycle/cleanup и ограничения. Для pure helpers достаточно вызвать функцию; registry, browser и global-store API требуют отдельного раздела «Инициализация и side effects».
+
+Если API не описан как публичный на соответствующей странице, не импортируйте его глубоким путём из `src` или `dist`: это не часть стабильного consumer contract.

package/src/file/file.mdx

@@ -1,6 +0,0 @@
-import { Markdown, Meta } from "@storybook/addon-docs/blocks";
-import Readme from './README.md?raw';
-
-<Meta title="Документация/shared/lib/file" />
-
-<Markdown >{Readme}</Markdown>

package/src/formatters/date/date.mdx

@@ -1,6 +0,0 @@
-import { Markdown, Meta } from "@storybook/addon-docs/blocks";
-import Readme from './README.md?raw';
-
-<Meta title="Документация/shared/lib/formatters/date" />
-
-<Markdown >{Readme}</Markdown>

package/src/formatters/number/number.mdx

@@ -1,6 +0,0 @@
-import { Markdown, Meta } from "@storybook/addon-docs/blocks";
-import Readme from './README.md?raw';
-
-<Meta title="Документация/shared/lib/formatters/number" />
-
-<Markdown >{Readme}</Markdown>

package/src/formatters/valueState/valueState.mdx

@@ -1,6 +0,0 @@
-import { Markdown, Meta } from "@storybook/addon-docs/blocks";
-import Readme from './README.md?raw';
-
-<Meta title="Документация/shared/lib/formatters/valueState" />
-
-<Markdown >{Readme}</Markdown>

package/src/formulas/formulas.mdx

@@ -1,6 +0,0 @@
-import { Markdown, Meta } from "@storybook/addon-docs/blocks";
-import Readme from './README.md?raw';
-
-<Meta title="Документация/shared/lib/formulas" />
-
-<Markdown >{Readme}</Markdown>

package/src/pwa/pwa.mdx

@@ -1,6 +0,0 @@
-import { Markdown, Meta } from "@storybook/addon-docs/blocks";
-import Readme from './README.md?raw';
-
-<Meta title="Документация/shared/lib/pwa" />
-
-<Markdown >{Readme}</Markdown>

package/src/query-client/queryClient.mdx

@@ -1,6 +0,0 @@
-import { Markdown, Meta } from "@storybook/addon-docs/blocks";
-import Readme from './README.md?raw';
-
-<Meta title="Документация/shared/lib/queryClient" />
-
-<Markdown >{Readme}</Markdown>