@ryuzaki13/react-foundation-lib 1.4.1 → 1.4.3

package/src/excel/README.mdx

@@ -0,0 +1,449 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="Foundation Lib/Data/Excel" />
+
+# Excel
+
+Модуль `@ryuzaki13/react-foundation-lib/excel` формирует и скачивает `.xlsx`-файлы в браузере. Он поддерживает:
+
+- одну или несколько таблиц-листов;
+- типизированные ячейки `String`, `Number`, `Date`, `Boolean`;
+- Excel number/date formats;
+- ширину колонок;
+- стили отдельных ячеек;
+- auto-filter;
+- адаптацию OData/table-описаний к Excel.
+
+Модуль строится поверх `write-excel-file/browser` и не предназначен для Node.js/SSR-скачивания.
+
+## Установка
+
+```bash
+npm install @ryuzaki13/react-foundation-lib write-excel-file
+```
+
+Версия `write-excel-file` должна соответствовать peer dependency пакета.
+
+```ts
+import {
+	buildExcelSheetData,
+	downloadExcelFile,
+	downloadExcelWorkbook,
+	type ExcelColumn,
+	type ExcelRow
+} from "@ryuzaki13/react-foundation-lib/excel";
+```
+
+## Самый простой экспорт
+
+```ts
+await downloadExcelFile({
+	fileName: "orders.xlsx",
+	columns: [
+		{ id: "ID", header: "Номер", type: String, width: 18 },
+		{
+			id: "AMOUNT",
+			header: "Сумма",
+			type: Number,
+			format: "#,##0.00",
+			width: 14
+		},
+		{
+			id: "CREATED_AT",
+			header: "Создан",
+			type: Date,
+			format: "dd.mm.yyyy hh:mm",
+			width: 20
+		}
+	],
+	rows: [
+		{
+			ID: "A-100",
+			AMOUNT: 1250.5,
+			CREATED_AT: "2026-08-21T09:30:00+05:00"
+		}
+	],
+	autoFilter: true
+});
+```
+
+Браузер скачает книгу с единственным листом `Sheet1`.
+
+## Базовая модель
+
+```ts
+type ExcelColumn = {
+	id: string;
+	header: string;
+	width?: number;
+	type?: StringConstructor | NumberConstructor | DateConstructor | BooleanConstructor;
+	format?: string;
+};
+
+type ExcelRow = Record<string, unknown>;
+```
+
+`column.id` — ключ, по которому значение читается из строки. Если в row такого ключа нет, ячейка будет пустой.
+
+`header` попадает в первую строку. Заголовок автоматически получает жирный шрифт и тонкую серую нижнюю границу.
+
+`width` передаётся writer как ширина Excel-колонки. Единица соответствует API `write-excel-file`, а не CSS-пикселям.
+
+`format` — маска Excel, например `#,##0.00`, `dd.mm.yyyy`, `hh:mm:ss`. Это не `Intl`-формат и не строковый formatter: Excel применяет маску к настоящему числу или дате.
+
+## Почему тип ячейки важен
+
+Неправильно передавать заранее отформатированную сумму:
+
+```ts
+{
+	AMOUNT: "1 250,50 ₽";
+}
+```
+
+Excel увидит текст и не сможет корректно суммировать, сортировать и применять числовую маску.
+
+Правильно:
+
+```ts
+columns: [{ id: "AMOUNT", header: "Сумма", type: Number, format: "#,##0.00" }],
+rows: [{ AMOUNT: 1250.5 }],
+```
+
+## Нормализация значений
+
+`buildExcelSheetData` приводит данные согласно `column.type`.
+
+### Пустые значения
+
+`null`, `undefined` и пустая строка `""` становятся пустой ячейкой. Строка из пробелов не считается пустой.
+
+### `Number`
+
+Число сохраняется как есть. Другое значение проходит через `Number(value)` и принимается только при конечном результате.
+
+```ts
+"125.5"; // 125.5
+""; // пустая ячейка
+"not a number"; // пустая ячейка
+Infinity; // пустая ячейка
+```
+
+Учитывайте стандартные правила JavaScript: строки `"0x10"` и `"1e2"` преобразуются в `16` и `100`.
+
+### `String`
+
+Используется `String(value)`. Объект без собственного осмысленного `toString` станет строкой `"[object Object]"`, поэтому сложные данные подготавливайте заранее.
+
+### `Boolean`
+
+Используется `Boolean(value)`. Непустая строка `"false"` является `true`. Если backend присылает строковые флаги, сначала преобразуйте их в реальный boolean.
+
+### `Date`
+
+Готовый `Date` используется напрямую. Остальное разбирается общим `parseDate` из formatters. Нераспознанное значение становится пустым.
+
+Для предсказуемого времени используйте ISO/OData-формат с явной временной зоной. Excel хранит дату как значение, а отображение дополнительно зависит от format и настроек программы пользователя.
+
+### Без `type`
+
+Значение передаётся writer почти без преобразования. Этот режим требует, чтобы вызывающий код уже подготовил тип, поддерживаемый `write-excel-file`.
+
+## `buildExcelSheetData(args)`
+
+Создаёт `SheetData` без скачивания файла. Полезно для тестов и собственного вызова writer.
+
+```ts
+const data = buildExcelSheetData({
+	columns,
+	rows,
+	getCellStyle: ({ row, column, rowIndex, columnIndex }) => {
+		if (column.id === "AMOUNT" && Number(row.AMOUNT) < 0) {
+			return { textColor: "#C50F1F", fontWeight: "bold" };
+		}
+
+		return undefined;
+	}
+});
+```
+
+Первая строка результата — header, затем строки данных. `rowIndex` и `columnIndex` в callback начинаются с нуля **для данных**, не включая header.
+
+Стиль объединяется после `value`, `type` и `format`. Тип `ExcelCellStyle` специально исключает эти три поля, поэтому callback предназначен только для визуальных параметров writer.
+
+## Стили по value state
+
+### `resolveExcelCellStyleFromState(state)`
+
+Преобразует общий `State` в цвет текста:
+
+| State         | Цвет      |
+| ------------- | --------- |
+| `information` | `#2563EB` |
+| `success`     | `#107C10` |
+| `warning`     | `#B7791F` |
+| `error`       | `#C50F1F` |
+
+Для `none`, пустой строки и `undefined` возвращается `undefined`.
+
+```ts
+getCellStyle: ({ row }) =>
+  resolveExcelCellStyleFromState(row.STATE as State),
+```
+
+Helper задаёт только `textColor`. При необходимости объедините результат со своим стилем.
+
+## Auto-filter
+
+```ts
+autoFilter: true;
+```
+
+Фильтр охватывает header и все строки данных. Он добавляется через низкоуровневую OpenXML transform-feature, потому что используемый writer не предоставляет отдельной высокоуровневой опции.
+
+### `buildExcelAutoFilterRef(columnCount, rowCount)`
+
+```ts
+buildExcelAutoFilterRef(1, 2); // "A1:A2"
+buildExcelAutoFilterRef(28, 10); // "A1:AB10"
+buildExcelAutoFilterRef(0, 10); // undefined
+```
+
+`rowCount` должен включать строку header. `downloadExcelFile` и workbook API вычисляют его автоматически.
+
+## Несколько листов
+
+### `downloadExcelWorkbook(args)`
+
+```ts
+await downloadExcelWorkbook({
+	fileName: "report.xlsx",
+	sheets: [
+		{
+			name: "Заказы",
+			columns: orderColumns,
+			rows: orders,
+			autoFilter: true
+		},
+		{
+			name: "Справочник статусов",
+			columns: statusColumns,
+			rows: statuses,
+			autoFilter: false
+		}
+	]
+});
+```
+
+Каждый лист имеет собственные колонки, ширины, строки, стили и filter. Порядок массива — порядок вкладок Excel.
+
+Пустой массив `sheets` приводит к ошибке: «Для формирования Excel-книги нужен минимум один лист».
+
+`fileName` передаётся browser writer. Рекомендуется явно добавлять расширение `.xlsx` и заранее очищать пользовательский ввод от нежелательных символов имени файла.
+
+## Имена листов
+
+### `resolveExcelSheetNames(names)`
+
+Excel ограничивает имя листа 31 символом и запрещает управляющие символы, `[ ] / \ : * ?`. Helper:
+
+- заменяет запрещённые группы пробелом;
+- схлопывает пробелы;
+- удаляет апострофы по краям;
+- использует `Лист N` для пустого результата;
+- обрезает до 31 символа;
+- делает имена уникальными без учёта регистра через суффиксы ` (2)`, ` (3)`.
+
+```ts
+resolveExcelSheetNames(["Продажи/Россия", "продажи россия", ""]);
+
+// ["Продажи Россия", "продажи россия (2)", "Лист 3"]
+```
+
+Функция возвращает новый массив и не меняет входные строки.
+
+## Table/OData-адаптер
+
+Вторая часть модуля помогает экспортировать таблицу, описание колонок которой использует `ColumnRole`, `ODataMetaType` и formatter pipeline.
+
+### `TableExcelColumnDescriptor`
+
+```ts
+type TableExcelColumnDescriptor = {
+	id: string;
+	header: string;
+	width?: number;
+	role?: ColumnRole;
+	odataType?: ODataMetaType;
+	clientOnly?: boolean;
+	formattersPipeline?: FormattersPipelineConfig;
+};
+```
+
+### `resolveTableExcelColumnType(descriptor)`
+
+Тип определяется в следующем порядке:
+
+1. `clientOnly: true` → `Number`;
+2. OData date/time type → `Date`;
+3. OData boolean type → `Boolean`;
+4. OData numeric type → `Number`;
+5. `role: "measure"` → `Number`;
+6. иначе → `String`.
+
+`clientOnly` здесь предполагает вычисляемую числовую колонку. Если приложение создаёт client-only текст, generic descriptor не сможет вывести его автоматически — сформируйте `ExcelColumn` вручную.
+
+### `createTableExcelColumn(descriptor)`
+
+Создаёт `ExcelColumn`, включая тип и format.
+
+```ts
+const column = createTableExcelColumn({
+	id: "NET_AMOUNT",
+	header: "Сумма",
+	odataType: "decimal",
+	role: "measure",
+	width: 16,
+	formattersPipeline: {
+		steps: [
+			{
+				type: "typedValueFormat",
+				config: { numberPresetName: "currency" }
+			}
+		]
+	}
+});
+```
+
+Точная структура pipeline описана в документации `/formatters`. Excel использует первый валидированный step `typedValueFormat`.
+
+### Числовые форматы из presets
+
+Если pipeline содержит существующий `numberPresetName`, число получает столько десятичных нулей, сколько указано в preset:
+
+```text
+decimals = 0 → #,##0
+decimals = 2 → #,##0.00
+```
+
+Для OData integer по умолчанию выбирается preset `integer`, для других чисел — `decimal`. Неизвестное имя preset игнорируется и заменяется подходящим default.
+
+### Форматы дат из presets
+
+По умолчанию:
+
+- OData `time` → time preset;
+- `datetime`/`datetimeOffset` → datetime preset;
+- остальные date types → date preset.
+
+Встроенные presets переводятся в Excel-маски, включая варианты `dd.mm`, `d mmm`, `mmm yyyy`, `hh:mm` и форматы с секундами.
+
+Для пользовательского date pattern токены нормализуются для Excel: `H` заменяется на `h`, `M` — на `m`. Если `datePresetName` не найден в registry, он исторически трактуется как ручной pattern.
+
+Форматы даты в JavaScript formatter и Excel не полностью взаимозаменяемы. Всегда проверяйте пользовательские patterns в реальном Excel/LibreOffice.
+
+## Подготовленная таблица
+
+```ts
+type ResolvedExcelTable = {
+	columns: ExcelColumn[];
+	rows: ExcelRow[];
+	cellStyles?: ReadonlyArray<Readonly<Record<string, ExcelCellStyle | undefined>>>;
+};
+```
+
+`cellStyles[rowIndex][columnId]` задаёт стиль конкретной ячейки. Индекс соответствует массиву `rows`.
+
+### `downloadResolvedExcelTable(args)`
+
+```ts
+await downloadResolvedExcelTable({
+	fileName: "table.xlsx",
+	table: {
+		columns,
+		rows,
+		cellStyles: [{ AMOUNT: { textColor: "#107C10" } }, { AMOUNT: { textColor: "#C50F1F" } }]
+	}
+});
+```
+
+`autoFilter` по умолчанию `true`.
+
+### `downloadResolvedExcelWorkbook(args)`
+
+```ts
+await downloadResolvedExcelWorkbook({
+	fileName: "analytics.xlsx",
+	sheets: [
+		{ name: "План", table: planTable },
+		{ name: "Факт", table: factTable, autoFilter: false }
+	]
+});
+```
+
+Для каждого resolved sheet auto-filter тоже включён по умолчанию.
+
+## Browser boundary и обработка ошибок
+
+`downloadExcelFile`, `downloadExcelWorkbook` и resolved download-функции используют browser bundle writer и инициируют сохранение файла. Вызывайте их из пользовательского действия в клиентском коде.
+
+```ts
+async function onExportClick() {
+	setExporting(true);
+
+	try {
+		await downloadExcelFile(args);
+	} catch (error) {
+		showExportError(error);
+	} finally {
+		setExporting(false);
+	}
+}
+```
+
+Promise завершается после `toFile`. Ошибки writer, нехватка памяти и запрет скачивания браузером не подавляются.
+
+Для больших таблиц построение всей книги происходит в памяти главного потока и может временно заблокировать UI. Модуль не реализует streaming, worker и серверную генерацию.
+
+## Частые ошибки
+
+### Передавать display-строки вместо typed values
+
+Excel теряет возможность вычислять и сортировать данные. Передавайте настоящие `number`, `boolean` и `Date`.
+
+### Ожидать JavaScript-формат в поле `format`
+
+Это маска Excel. `Intl.DateTimeFormat` options и formatter preset напрямую туда не подходят.
+
+### Экспортировать `"false"` как Boolean
+
+Непустая строка истинна. Нормализуйте transport-значение до `false`.
+
+### Использовать API на сервере
+
+Импорт идёт из `write-excel-file/browser`. Для server-side Excel нужен другой owner/адаптер.
+
+### Передавать пустой workbook
+
+Многолистовая книга требует минимум один sheet. Пустой лист с header допустим, если есть columns.
+
+### Полагаться на исходные имена листов
+
+Они нормализуются и могут получить суффикс. Если имя нужно показывать пользователю заранее, вызовите `resolveExcelSheetNames` до download.
+
+## Краткая карта API
+
+| Экспорт                                     | Назначение                                     |
+| ------------------------------------------- | ---------------------------------------------- |
+| `buildExcelSheetData`                       | Собрать типизированные ячейки без скачивания   |
+| `downloadExcelFile`                         | Скачать книгу с одним листом `Sheet1`          |
+| `downloadExcelWorkbook`                     | Скачать книгу из нескольких независимых листов |
+| `buildExcelAutoFilterRef`                   | Построить Excel-диапазон фильтра               |
+| `resolveExcelSheetNames`                    | Нормализовать и дедуплицировать имена листов   |
+| `resolveExcelCellStyleFromState`            | Получить цвет текста из общего value state     |
+| `resolveTableExcelColumnType`               | Вывести Excel type из OData/table descriptor   |
+| `createTableExcelColumn`                    | Создать колонку с type и format                |
+| `downloadResolvedExcelTable`                | Скачать заранее подготовленную таблицу         |
+| `downloadResolvedExcelWorkbook`             | Скачать несколько подготовленных таблиц        |
+| `ExcelColumn`, `ExcelRow`, `ExcelCellStyle` | Базовые generic-типы                           |
+| `ResolvedExcelTable`                        | Таблица с optional map стилей                  |

package/src/fingerprint/README.mdx

@@ -0,0 +1,100 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="Foundation Lib/Browser/Client Fingerprint" />
+
+# Client fingerprint через `@ryuzaki13/react-foundation-lib/fingerprint`
+
+`getClientFingerprint` лениво загружает FingerprintJS, получает `visitorId` и кеширует Promise на всё время жизни JavaScript-модуля.
+
+## Установка и импорт
+
+```bash
+npm install @ryuzaki13/react-foundation-lib @fingerprintjs/fingerprintjs
+```
+
+```ts
+import { getClientFingerprint } from "@ryuzaki13/react-foundation-lib/fingerprint";
+```
+
+Host должен разрешить peer dependency `@fingerprintjs/fingerprintjs >=5 <6`.
+
+## Использование
+
+```ts
+const fingerprint = await getClientFingerprint();
+
+if (fingerprint) {
+	attachAnonymousDiagnosticId(fingerprint);
+}
+```
+
+Результат `Promise<string | null>`:
+
+- непустой trimmed `visitorId`, если библиотека успешно отработала;
+- `null` вне browser;
+- `null`, если load/get завершились ошибкой;
+- `null`, если visitorId пустой после trim.
+
+## Кеширование
+
+Первый browser-вызов создаёт одну Promise:
+
+```text
+первый вызов ──► load FingerprintJS ──► fp.get() ──► string/null
+     │
+следующие вызовы ─────────────────────► та же Promise
+```
+
+Преимущества:
+
+- параллельные consumers не запускают повторное вычисление;
+- после успеха возвращается то же значение;
+- после ошибки `null` также кешируется и автоматического retry нет.
+
+Публичного reset/retry API нет. Reload страницы создаёт новый module runtime.
+
+SSR-вызов возвращает `null` сразу и не заполняет browser promise cache. Поэтому последующий client runtime может выполнить настоящее вычисление.
+
+## Правильная React boundary
+
+Не вызывайте async функцию во время render:
+
+```tsx
+useEffect(() => {
+	let active = true;
+
+	void getClientFingerprint().then((value) => {
+		if (active) setFingerprint(value);
+	});
+
+	return () => {
+		active = false;
+	};
+}, []);
+```
+
+Если fingerprint нужен backend request, предпочтительнее интегрировать его в app/API boundary, а не дублировать state по компонентам.
+
+## Privacy и security
+
+Fingerprint:
+
+- не является authentication token;
+- не доказывает личность пользователя;
+- может меняться после обновления browser/device/settings;
+- может совпасть у разных клиентов;
+- не заменяет server session;
+- требует правового/продуктового решения о consent и retention;
+- не должен использоваться для скрытого tracking вопреки пользовательской политике.
+
+Не помещайте fingerprint в публичный URL, DOM или logs без необходимости. При передаче на backend используйте HTTPS и установленную privacy policy.
+
+## Ошибки и тестирование
+
+Функция намеренно поглощает ошибки FingerprintJS и возвращает `null`. Это graceful optional capability; если fingerprint обязателен для business flow, host должен явно обработать `null`.
+
+Module-level cache усложняет повторные тесты. Используйте module reset (`vi.resetModules`) перед сценарием, которому нужен чистый первый вызов.
+
+```ts
+function getClientFingerprint(): Promise<string | null>;
+```

package/src/form/README.mdx

@@ -0,0 +1,101 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="Foundation Lib/Forms/Form Errors" />
+
+# Чтение первой ошибки формы через `@ryuzaki13/react-foundation-lib/form`
+
+Модуль содержит одну функцию `readFirstFormError`. Она получает неоднородный массив ошибок и возвращает первое найденное текстовое сообщение.
+
+## Установка и импорт
+
+```ts
+import { readFirstFormError } from "@ryuzaki13/react-foundation-lib/form";
+```
+
+Модуль ESM, не зависит от React и не привязан к конкретной form library.
+
+## Поддерживаемые формы ошибки
+
+Функция понимает:
+
+1. Строку.
+2. Объект с непустым строковым полем `message`.
+3. Вложенный массив таких значений.
+
+```ts
+readFirstFormError([undefined, { message: "Поле обязательно" }]);
+// "Поле обязательно".
+
+readFirstFormError([[null, "Неверный формат"], "Другая ошибка"]);
+// "Неверный формат".
+```
+
+Обычный `Error` также подходит, потому что имеет строковое поле `message`:
+
+```ts
+readFirstFormError([new Error("Ошибка проверки")]);
+// "Ошибка проверки".
+```
+
+## Алгоритм
+
+```text
+errors отсутствует ──► undefined
+        │
+        ▼
+обход слева направо
+        │
+        ├─ string ─────────► вернуть строку
+        ├─ array ──────────► рекурсивно найти первую строку
+        ├─ { message } ────► вернуть непустой string message
+        └─ другое ─────────► пропустить
+```
+
+```ts
+const message = readFirstFormError(errors);
+
+if (message) {
+	showFieldError(message);
+}
+```
+
+## Точные правила
+
+- `undefined` вместо массива возвращает `undefined`.
+- Пустой массив возвращает `undefined`.
+- Поиск идёт в исходном порядке.
+- Пустая строка не является результатом и поиск продолжается.
+- Строка из пробелов считается непустой и возвращается буквально.
+- Числа, boolean, functions, `null` и объекты без string `message` пропускаются.
+- Массивы обходятся рекурсивно без ограничения глубины.
+- Входные массивы и objects не изменяются.
+
+## Пример в React
+
+```tsx
+type FieldErrorProps = {
+	errors?: readonly unknown[];
+};
+
+export function FieldError({ errors }: FieldErrorProps) {
+	const message = readFirstFormError(errors);
+
+	return message ? <p role="alert">{message}</p> : null;
+}
+```
+
+Для нескольких ошибок, summary списка, локализации и сопоставления ошибки конкретному field нужен отдельный form-layer host-приложения.
+
+## Ограничения и ошибки
+
+- Функция не выполняет trim или перевод сообщений.
+- Она не проверяет schema form-library.
+- Возвращается только первое сообщение; остальные теряются для этого вызова.
+- Циклический массив приведёт к бесконечной рекурсии/ошибке call stack.
+- Не передавайте backend payload напрямую без runtime-проверки и безопасного отображения.
+
+## API
+
+```ts
+function readFirstFormError(errors: readonly unknown[] | undefined): string | undefined;
+```