@ryuzaki13/react-foundation-lib 1.4.0 → 1.4.2

package/src/docs/browserAndReact.mdx

@@ -1,150 +0,0 @@
-import { Meta } from "@storybook/addon-docs/blocks";
-
-<Meta title="Foundation Lib/Browser и React API" />
-
-# Browser и React API
-
-Эти entrypoint работают только после монтирования в браузере. Вызывайте hooks на верхнем уровне React-компонента или custom hook, а императивные действия (скачивание, clipboard, открытие меню) — из event handler. Они не заменяют UI primitives из `@ryuzaki13/react-foundation-ui`.
-
-## Общие hooks
-
-```ts
-import {
-	useDebounce,
-	useDebouncedCallback,
-	useDndSortableSensors,
-	useFloatingListbox,
-	useSearchLink,
-	useSearchParams,
-	useThrottledCallback
-} from "@ryuzaki13/react-foundation-lib/hooks";
-```
-
-| API                                                             | Назначение и lifecycle                                                                                                                 |
-| --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
-| `useDebounce(value, delay)`                                     | Возвращает отложенное значение. Не запускает network запрос сам — используйте результат в owner Query/UI flow.                         |
-| `useDebouncedCallback(callback, delay, { flushOnUnmount? })`    | Возвращает debounced callback. Опция `flushOnUnmount` нужна только когда финальный вызов действительно обязателен.                     |
-| `useThrottledCallback(callback, interval, { flushOnUnmount? })` | Возвращает `{ call, flush, cancel }`; стратегия last-write-wins. Вызывайте `flush` на границе сохранения, `cancel` при смене identity. |
-| `useDndSortableSensors(distanceOrOptions?)`                     | Готовые Pointer/Keyboard sensors для `@dnd-kit/sortable`; default distance — 6 px.                                                     |
-| `useLazyComponent(loader, ...)`                                 | Используйте для lazy UI по устойчивому loader/cache key, а не вызывайте dynamic import во время render.                                |
-| `useReferenceTrace(name, value)`                                | Development diagnostic для отслеживания смены ссылок; не часть бизнес-логики.                                                          |
-| `useBlockBrowserZoom(enabled)`                                  | Подписывается на browser events для блокировки zoom. Используйте только в явном специализированном UX, не как default.                 |
-
-### Search и floating listbox
-
-`useSearchParams<K>(allowedKeys?)` и `useSearchLink<K>()` требуют `@tanstack/react-router`. Первый возвращает `{ params, filteredParams, setParams }` и выполняет navigation с `replace: true`; второй возвращает `buildLink(params)`. Оба работают с URL state, а не с произвольным Zustand/local store.
-
-`useFloatingListbox<T>(options)` требует `@floating-ui/react` и объединяет ref, ARIA-interactions, keyboard navigation и placement. Передавайте:
-
-- `options`, `selectedIndex`, `getOptionDisabled` — данные и доступность опций;
-- optional controlled `open` + `onOpenChange`;
-- `onSelect`, `closeOnSelect`, `focusFloatingOnOpen`, `restoreFocusOnClose` — interaction policy;
-- `placement` и `placementStrategy: "flip" | "auto"` — placement;
-- `resolveFloatingSize(context)` — только layout/CSS size policy.
-
-Hook возвращает Floating UI props/refs и их нужно распространять на reference, floating element и options строго по его контракту. Не заменяйте эти props самодельными keyboard handlers: это нарушит `aria-activedescendant`, focus restore и cleanup `autoUpdate`.
-
-## DOM и overlay helpers
-
-```ts
-import {
-	downloadFileFromBlob,
-	getOrCreatePortalRoot,
-	useClickOutside,
-	useEscapeDismiss,
-	useFocusTrap,
-	useIntersectionObserver,
-	useOverlayFocus
-} from "@ryuzaki13/react-foundation-lib/dom";
-```
-
-| API                                              | Контракт                                                                                                      |
-| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
-| `downloadFileFromObjectURL(filename, objectUrl)` | Инициирует download по готовому object URL; не владеет временем `URL.revokeObjectURL`.                        |
-| `downloadFileFromBlob(filename, blob)`           | Создаёт временный object URL и инициирует download.                                                           |
-| `downloadFileFromJson(filename, payload)`        | Сериализует payload в JSON blob и скачивает.                                                                  |
-| `getOrCreatePortalRoot(id)`                      | Возвращает/создаёт DOM root или `null`, если `document` недоступен.                                           |
-| `useClickOutside(refOrRefs, handler)`            | Вызывает handler при внешнем pointer interaction; передавайте стабильные refs.                                |
-| `useEscapeDismiss(options)`                      | Dismiss только для active/enabled overlay; поддерживает container и целевой document.                         |
-| `useFocusTrap(isOpen)`                           | Возвращает ref для trapping focus внутри открытого overlay.                                                   |
-| `useOverlayFocus(options)`                       | Управляет initial focus и restore для overlay; применяйте вместе с accessible dialog/menu.                    |
-| `useElementHeightObserver(ref)`                  | Следит за высотой через `ResizeObserver`; результат используйте для layout, не для копирования props в state. |
-| `useIntersectionObserver(ref, options?)`         | Возвращает intersection state DOM element.                                                                    |
-| `useIsTouchDevice()`                             | Реактивно сообщает touch-capability браузера.                                                                 |
-
-Hooks сами подписываются и очищают observers/listeners при unmount. Не вызывайте `getOrCreatePortalRoot` или browser API в server render; hook-проверки не делают UI SSR-safe автоматически.
-
-## Clipboard, media и context menu
-
-```ts
-import { useCopyText, useCopyElementTextWithFeedback } from "@ryuzaki13/react-foundation-lib/copy";
-import { useMediaQuery, useMatchMedia, resolveResponsiveValue } from "@ryuzaki13/react-foundation-lib/media";
-import { createVirtualAnchor, openMenu } from "@ryuzaki13/react-foundation-lib/context-menu";
-```
-
-### `copy`
-
-| API                                   | Результат                                                         |
-| ------------------------------------- | ----------------------------------------------------------------- |
-| `useCopyText()`                       | Возвращает copy action для строки через Clipboard API с fallback. |
-| `useElementText(ref)`                 | Читает текст из DOM element.                                      |
-| `useCopyElementText(ref)`             | Комбинирует чтение элемента и copy.                               |
-| `useCopyFeedback()`                   | Локальное временное состояние feedback после успешного copy.      |
-| `useCopyElementTextWithFeedback(ref)` | Удобная композиция copy element + feedback.                       |
-
-Copy может быть отклонён browser permissions; показывайте ожидаемую UI-ошибку, но не считайте clipboard источником истины для сохранения данных.
-
-### `media`
-
-`BREAKPOINTS_EM` и `Breakpoint` задают стандартные breakpoints; `useMatchMedia()` возвращает `MediaMatches`. Для конкретного media query используйте `useMediaQuery(query, { ssrFallback? })`; `ssrFallback` определяет значение только до browser hydration/в окружении без `matchMedia`.
-
-`ResponsiveValue<T>`, `isResponsiveMap`, `resolveResponsiveValue` и `resolveProps` — pure helpers для responsive props. `getCurrentFontSize`, `getCurrentLineHeight`, `getControlHeight`, `pxToEm` читают layout/DOM: не вызывайте их в render, если результат влияет на state без external synchronization.
-
-### `context-menu`
-
-`MenuAnchor`, `MenuState`, `MenuPoint`, `OpenMenuPayload` — serializable contracts состояния меню. `openMenu(payload)`, `closeMenu(state)` и `toggleMenu(state, payload)` — pure reducers; их можно держать в local/store owner.
-
-Для pointer menu используйте `getMenuPointFromEvent(event)` и `createVirtualAnchor(point, contextElement?)`. Для keyboard anchor используйте `getMenuPointFromRect(rect)`. API лишь описывает состояние/anchor; отображение и accessibility menu остаются у UI-компонента.
-
-## Virtualizer, PWA и Three.js
-
-### Infinite virtualizer
-
-```ts
-import { useFetchNextPageEffect } from "@ryuzaki13/react-foundation-lib/virtualizer";
-```
-
-Hook принимает `{ virtualItems, currentItemsCount, hasNextPage, fetchNextPage }`; при достижении последней виртуальной строки запускает один следующий fetch и не создаёт параллельные запросы. `fetchNextPage` должен быть стабильным Query action. Не передавайте raw `fetch` и не подменяйте backend state локальным массивом.
-
-### Service Worker
-
-```ts
-import { parseSwCachePolicy, buildSwCachePolicyValue, useServiceWorkerUpdate } from "@ryuzaki13/react-foundation-lib/pwa";
-```
-
-`useServiceWorkerUpdate()` возвращает `{ hasUpdate, applyUpdate, dismiss }`. Его задача — UI-поверхность для уже настроенного приложения с Service Worker; hook не публикует и не настраивает private registration API.
-
-`pwa/sw-cache-policy` — отдельный точечный import того же pure policy API:
-
-| API                                      | Контракт                                                                                             |
-| ---------------------------------------- | ---------------------------------------------------------------------------------------------------- |
-| `parseSwCachePolicy(value)`              | Парсит `off`, `ttl=<duration>` или `bust=<duration>` с `max`/`name`; invalid input даёт `undefined`. |
-| `buildSwCachePolicyValue(draft)`         | Нормализует `SwCachePolicyDraft` в canonical transport string.                                       |
-| `normalizeSwCacheName(value)`            | Делает безопасное lower-case cache name или `undefined`.                                             |
-| `resolveSwCacheCacheNameByPolicy(value)` | Возвращает вычисленное имя cache только для `ttl`/`bust`.                                            |
-
-Пример: `ttl=24h;max=200;name=reference`. Это policy для transport/Service Worker, а не замена TanStack Query cache. Не включайте в SW cache auth-sensitive responses без отдельной security policy.
-
-### Доступность Three.js
-
-```ts
-import { useThreeSceneAvailability, disableThreeSceneForSession } from "@ryuzaki13/react-foundation-lib/three-scene";
-```
-
-| API                                                                         | Назначение                                                                                                                    |
-| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| `isThreeSceneSupported(options?)`                                           | Проверяет browser WebGL/WebGL2 support.                                                                                       |
-| `isThreeSceneDisabledForSession(key?)`, `disableThreeSceneForSession(key?)` | Читают/устанавливают opt-out текущей tab session.                                                                             |
-| `useThreeSceneAvailability(options?)`                                       | React state с `pending`/`available`/`unavailable` и причиной (`sessionDisabled`, `reducedMotion`, `webglUnsupported`, `ssr`). |
-
-Проверка support не заменяет обработку ошибки renderer. При `unavailable` всегда рендерите семантический non-Three fallback.

package/src/docs/filesAndExcel.mdx

@@ -1,163 +0,0 @@
-import { Meta } from "@storybook/addon-docs/blocks";
-
-<Meta title="Foundation Lib/Файлы и Excel" />
-
-# Файлы, бинарные данные и Excel
-
-Эта страница описывает browser-only API для чтения пользовательских файлов, преобразования base64 и формирования `.xlsx`. Подготовка бизнес-полей, проверка прав доступа и отправка файла на сервер остаются ответственностью host-приложения.
-
-## `file`: чтение файлов и HTTP-заголовки
-
-```ts
-import {
-	createContentDispositionHeader,
-	readFile,
-	readImageFile,
-	resolveMimeTypeByExtension,
-	type ReadFileError,
-	type ReadImageError
-} from "@ryuzaki13/react-foundation-lib/file";
-```
-
-### Когда использовать
-
-- `readFile` — получить `dataUrl` для preview или `ArrayBuffer` для дальнейшей обработки;
-- `readImageFile` — то же для изображений с проверкой image MIME и размером изображения;
-- helpers Content-Disposition — сформировать безопасный заголовок в browser-compatible/edge runtime коде;
-- `resolveMimeTypeByExtension` — определить MIME по расширению, если содержимого для sniffing нет.
-
-### `readFile`
-
-```ts
-readFile(file, options?): Promise<ReadFileResult>
-```
-
-| Опция                             | Назначение                                        |
-| --------------------------------- | ------------------------------------------------- |
-| `mode?: "data-url"`               | Режим по умолчанию. Результат содержит `dataUrl`. |
-| `mode: "array-buffer"`            | Результат содержит `buffer`.                      |
-| `allowedMime?: readonly string[]` | Точный список разрешённых MIME.                   |
-| `maxBytes?: number`               | Максимальный размер файла в байтах.               |
-| `signal?: AbortSignal`            | Отменяет чтение через `FileReader.abort()`.       |
-
-Возвращаемый discriminated union всегда содержит `file` и `meta` (`name`, `mime`, `size`, `lastModified`). После проверки `result.mode` TypeScript раскрывает либо `dataUrl`, либо `buffer`.
-
-```ts
-const result = await readFile(file, {
-	mode: "data-url",
-	allowedMime: ["application/pdf"],
-	maxBytes: 10 * 1024 * 1024,
-	signal
-});
-
-if (result.mode === "data-url") {
-	previewUrl = result.dataUrl;
-}
-```
-
-`ReadFileError` имеет предсказуемый `code`: `NO_FILE`, `MIME_NOT_ALLOWED`, `FILE_TOO_LARGE`, `READ_ABORTED` или `READ_FAILED`. Обрабатывайте его как ожидаемую ошибку выбора файла, а остальные ошибки не скрывайте.
-
-### `readImageFile`
-
-```ts
-readImageFile(image, options?): Promise<ReadImageResult>
-```
-
-Поддерживаемые `ImageMime`: `image/png`, `image/jpeg`, `image/webp`, `image/gif`, `image/svg+xml`, `image/avif`. В режиме `data-url` результат дополнительно включает `dimensions` (`width`, `height`). В режиме `array-buffer` декодирование изображения не выполняется.
-
-`ReadImageError` расширяет коды `ReadFileError` значениями `NOT_AN_IMAGE` и `IMAGE_DECODE_FAILED`.
-
-### Дополнительный API `file`
-
-| API                                             | Контракт                                                                                                              |
-| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| `buildMeta(file)`                               | Возвращает serializable метаданные `FileMeta`.                                                                        |
-| `attachAbort(signal, reader)`                   | Привязывает отмену к `FileReader`; возвращённую функцию cleanup вызывают только custom consumers низкоуровневого API. |
-| `assertNotAborted(signal?)`                     | Бросает `ReadFileError("READ_ABORTED")`, если сигнал уже отменён.                                                     |
-| `assertValidAllowedMime`, `assertValidAccept`   | Проверяют конфигурацию accept/MIME до чтения.                                                                         |
-| `sanitizeFileName(value, fallback?)`            | Удаляет unsafe символы из имени.                                                                                      |
-| `encodeFilenameRFC5987(value)`                  | Кодирует Unicode filename для HTTP header.                                                                            |
-| `createAsciiFilenameFallback(value, fallback?)` | Создаёт ASCII fallback для старых consumers заголовка.                                                                |
-| `createContentDispositionHeader(options)`       | Создаёт `inline`/`attachment` Content-Disposition с `filename` и `filename*`.                                         |
-
-## `binary`: base64 → `Blob`
-
-```ts
-import { binaryToBlob, detectMimeType, useBinaryFile } from "@ryuzaki13/react-foundation-lib/binary";
-```
-
-| API                                              | Вход и результат                                                                                                                  |
-| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
-| `binaryToBlob(binaryData, mimeType?, isBase64?)` | Создаёт `Blob` из base64/data URL (по умолчанию) или raw binary string (`false`). Пустые или некорректные данные бросают `Error`. |
-| `detectMimeType(fileName?, binaryData?)`         | Ищет MIME по расширению, data URL, затем сигнатуре base64. Неопределённый документ трактует как `application/pdf`.                |
-| `useBinaryFile(bin)`                             | React hook, возвращает `{ data: { blob, mime } \| null, error: string \| null }`.                                                 |
-
-```ts
-const mime = detectMimeType("report.pdf", base64);
-const blob = binaryToBlob(base64, mime);
-const objectUrl = URL.createObjectURL(blob);
-
-// Владелец UI обязан освободить URL при смене файла/размонтировании.
-URL.revokeObjectURL(objectUrl);
-```
-
-`useBinaryFile` не создаёт object URL и не освобождает его: это lifecycle конкретного preview-компонента. Hook использует `Blob` и `atob`, поэтому не вызывайте его в SSR или worker без совместимого polyfill.
-
-## `excel`: скачивание `.xlsx`
-
-```ts
-import {
-	buildExcelAutoFilterRef,
-	buildExcelSheetData,
-	createTableExcelColumn,
-	downloadExcelFile,
-	downloadExcelWorkbook,
-	downloadResolvedExcelTable,
-	downloadResolvedExcelWorkbook,
-	resolveExcelCellStyleFromState,
-	resolveExcelSheetNames
-} from "@ryuzaki13/react-foundation-lib/excel";
-```
-
-### Базовый экспорт
-
-`downloadExcelFile({ fileName, columns, rows, autoFilter?, getCellStyle? })` создаёт один лист; `downloadExcelWorkbook({ fileName, sheets })` — книгу из нескольких листов. Это asynchronous browser API, который инициирует скачивание через `write-excel-file`.
-
-```ts
-await downloadExcelFile({
-	fileName: "users.xlsx",
-	columns: [
-		{ id: "name", header: "Имя", type: String, width: 28 },
-		{ id: "createdAt", header: "Дата", type: Date, format: "dd.mm.yyyy" }
-	],
-	rows: [{ name: "Анна", createdAt: new Date("2026-07-30") }],
-	autoFilter: true
-});
-```
-
-| Public type/API                             | Назначение                                                                                                           |
-| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| `ExcelColumn`, `ExcelRow`, `ExcelCellStyle` | Контракты столбца, строки и стиля ячейки. `type` передаёт в файл истинные `Number`/`Date`/`Boolean`, а не UI-строку. |
-| `buildExcelSheetData(args)`                 | Строит данные листа без запуска download; подходит для тестируемой подготовки.                                       |
-| `buildExcelAutoFilterRef(columns, rows)`    | Даёт Excel-диапазон или `undefined` для пустой сетки.                                                                |
-| `resolveExcelSheetNames(names)`             | Нормализует ограничения Excel (31 символ, forbidden chars) и делает имена уникальными.                               |
-| `resolveExcelCellStyleFromState(state)`     | Преобразует `State` в базовый цвет текста Excel.                                                                     |
-
-### Экспорт подготовленной таблицы
-
-`TableExcelColumnDescriptor` связывает generic Excel column с OData type/role и необязательным `formattersPipeline`. Используйте `createTableExcelColumn(descriptor)` для получения типизированного столбца, затем передавайте значения строк без предварительного UI-форматирования.
-
-| API                                                            | Назначение                                                                        |
-| -------------------------------------------------------------- | --------------------------------------------------------------------------------- |
-| `resolveTableExcelColumnType(descriptor)`                      | Выбирает `String`/`Number`/`Date`/`Boolean` по OData metadata и роли.             |
-| `createTableExcelColumn(descriptor)`                           | Создаёт `ExcelColumn` с Excel-маской числа/даты из published formatter contracts. |
-| `downloadResolvedExcelTable({ fileName, table, autoFilter? })` | Скачивает одну уже подготовленную таблицу.                                        |
-| `downloadResolvedExcelWorkbook({ fileName, sheets })`          | Скачивает несколько `ResolvedExcelTable` как листы книги.                         |
-
-Не передавайте в `rows` отформатированные через `Intl` строки для числовых и date-столбцов: Excel потеряет сортировку, формулы и формат. Строки создавайте только для действительно текстовых значений.
-
-## Ограничения
-
-- Все три entrypoint ориентированы на DOM/browser; не вызывайте их в server-only коде.
-- MIME по имени/сигнатуре не является проверкой безопасности содержимого. Сервер обязан валидировать загружаемые файлы повторно.
-- `download*` имеет пользовательский side effect. Вызывайте его из event handler, а не из render/effect при монтировании.