@ryuzaki13/react-foundation-lib 2.33.0 → 2.35.0

package/src/binary/README.mdx

@@ -4,7 +4,7 @@ import { Meta } from "@storybook/addon-docs/blocks";
 
 # Работа с бинарными данными
 
-Модуль `binary` преобразует строковое бинарное содержимое в браузерный `Blob`, определяет предполагаемый MIME-тип документа и предоставляет React hook для типового сценария «base64 → `{ blob, mime }`». Отдельная pure function `getBase64DecodedSize` проверяет стандартный Base64 payload и считает размер без декодирования в browser или server runtime.
+Модуль `binary` преобразует строковое бинарное содержимое в браузерный `Blob`, определяет предполагаемый MIME-тип документа и предоставляет React hook, результат которого показывает, удалось ли определить MIME. Отдельная pure function `getBase64DecodedSize` проверяет стандартный Base64 payload и считает размер без декодирования в browser или server runtime.
 
 Основной сценарий:
 
@@ -278,7 +278,7 @@ const raw = String.fromCharCode(65, 66, 67);
 | Превратить base64 data URL в `Blob`                    | `binaryToBlob`                                    |
 | Превратить raw binary string в `Blob`                  | `binaryToBlob(..., ..., false)`                   |
 | Предположить MIME по имени и данным                    | `detectMimeType`                                  |
-| В React получить `{ blob, mime }` из base64 prop/state | `useBinaryFile`                                   |
+| В React получить `Blob` и результат определения MIME   | `useBinaryFile`                                   |
 | Скачать готовый `Blob`                                 | `downloadFileFromBlob` из `/dom`                  |
 | Прочитать пользовательский `File`                      | `readFile` или `readImageFile` из `/file`         |
 | Использовать известные filename и MIME                 | Вызвать `detectMimeType`/`binaryToBlob` вручную   |
@@ -762,70 +762,41 @@ Fallback PDF является осознанным предметно-незав
 ### Сигнатура
 
 ```ts
-function useBinaryFile(bin: string | undefined): {
+type UseBinaryFileResult = {
 	data: {
 		blob: Blob;
 		mime: string;
+		isMimeDetected: boolean;
 	} | null;
 	error: string | null;
 };
-```
-
-Hook принимает только base64/base64 data URL. Он всегда вызывает:
 
-```ts
-const mime = detectMimeType(undefined, bin);
-const blob = binaryToBlob(bin, mime, true);
+function useBinaryFile(bin: string | undefined): UseBinaryFileResult;
 ```
 
-Filename передать нельзя, raw binary mode использовать нельзя.
+Hook принимает base64 или base64 data URL. Имя файла и MIME можно передать отдельно через `detectMimeType` и `binaryToBlob`.
 
 ### Возвращаемое состояние
 
-| Поле    | Значение         | Смысл                                |
-| ------- | ---------------- | ------------------------------------ |
-| `data`  | `{ blob, mime }` | Декодирование завершилось успешно    |
-| `data`  | `null`           | Нет результата либо произошла ошибка |
-| `error` | `string`         | Строковое представление ошибки       |
-| `error` | `null`           | Ошибки нет                           |
-
-### Lifecycle
-
-Преобразование выполняется после commit в React effect:
-
-1. первый render возвращает `{ data: null, error: null }`;
-2. после commit effect обрабатывает `bin`;
-3. успех записывает `{ blob, mime }` и очищает ошибку;
-4. ошибка очищает `data` и записывает `String(error)`;
-5. `undefined` или пустая строка очищают оба поля.
-
-Пример последовательности:
-
-| `bin`                 | Состояние после effect                                     |
-| --------------------- | ---------------------------------------------------------- |
-| `undefined`           | `{ data: null, error: null }`                              |
-| `""`                  | `{ data: null, error: null }`                              |
-| Корректный base64 PDF | `{ data: { blob, mime: "application/pdf" }, error: null }` |
-| Некорректный base64   | `{ data: null, error: "Error: ..." }`                      |
-| Строка из пробелов    | Ошибка после удаления пробелов                             |
-
-У hook нет отдельного `isLoading`/`isProcessing`. На первом render `data: null` и `error: null` может означать как отсутствие входа, так и ещё не выполненный effect.
-
-### Смена `bin`
+| Поле    | Значение                        | Смысл                                |
+| ------- | ------------------------------- | ------------------------------------ |
+| `data`  | `{ blob, mime, isMimeDetected }` | Декодирование завершилось успешно    |
+| `data`  | `null`                          | Нет результата либо произошла ошибка |
+| `error` | `string`                        | Строковое представление ошибки       |
+| `error` | `null`                          | Ошибки нет                           |
 
-При смене одного непустого `bin` на другой предыдущие `data`/`error` могут оставаться видимыми до выполнения следующего effect. Hook не очищает состояние синхронно во время render.
+### Результат при рендере
 
-Если нельзя кратковременно показать предыдущий документ:
+Хук синхронно декодирует текущий `bin` при рендере. При смене `bin` результат сразу относится к новому входу. Мемоизация позволяет повторно использовать `Blob` при рендере с тем же `bin`.
 
-- разместите hook в компоненте, который remount-ится по стабильному ID документа;
-- или выполните преобразование на явной границе загрузки;
-- или добавьте внешний state machine с identity результата.
-
-Не используйте саму большую base64-строку как React `key`. Используйте безопасный стабильный ID документа:
-
-```tsx
-<BinaryDocument key={document.id} bin={document.content} />
-```
+| `bin`                              | Результат                                                               |
+| ---------------------------------- | ----------------------------------------------------------------------- |
+| `undefined`                        | `{ data: null, error: null }`                                             |
+| `""`                               | `{ data: null, error: null }`                                             |
+| Корректный base64 PDF              | `data.mime === "application/pdf"`, `data.isMimeDetected === true`          |
+| Корректный base64 неизвестного типа | `data.mime === "application/octet-stream"`, `data.isMimeDetected === false` |
+| Некорректный base64                | `{ data: null, error: "Error: ..." }`                                     |
+| Строка из пробелов                 | Ошибка после удаления пробелов                                          |
 
 ### Определение MIME внутри hook
 
@@ -833,27 +804,22 @@ Hook не знает filename. Приоритет будет таким:
 
 1. MIME из data URL;
 2. сигнатура;
-3. fallback `application/pdf`.
+3. fallback `application/octet-stream`.
 
-Обычный base64 текста без data URL и известной сигнатуры станет `Blob` с `application/pdf`:
+Проверяйте `data.isMimeDetected` перед выбором просмотрщика. Значение `true` означает, что MIME взят из data URL или определён по сигнатуре. Значение `false` означает, что hook подставил нейтральный MIME и сохранил декодированные байты.
 
 ```tsx
 const { data } = useBinaryFile("SGVsbG8=");
 
-// После effect:
-// data?.mime === "application/pdf"
+// data?.mime === "application/octet-stream"
+// data?.isMimeDetected === false
 ```
 
 Если известны имя или MIME, вызывайте `detectMimeType` и `binaryToBlob` вручную.
 
 ### Ошибки и logging
 
-При ошибке hook:
-
-1. вызывает внутренний `logError(error)`;
-2. `logError` пишет ошибку в `console.error`;
-3. возвращает `error: String(error)`;
-4. очищает `data`.
+При ошибке хук возвращает `{ data: null, error: String(error) }` во время рендера. После commit эффект передаёт исходную ошибку в `logError`, который пишет её в `console.error`.
 
 Для обычного `Error` строка включает имя:
 
@@ -879,12 +845,12 @@ export function BinaryDocument(props: BinaryDocumentProps) {
 		return <p role="alert">Не удалось подготовить документ</p>;
 	}
 
-	if (!props.bin) {
+	if (!data) {
 		return <p>Документ не передан</p>;
 	}
 
-	if (!data) {
-		return <p>Подготовка документа…</p>;
+	if (!data.isMimeDetected) {
+		return <p>Формат файла не распознан</p>;
 	}
 
 	return <DocumentViewer blob={data.blob} mime={data.mime} />;
@@ -936,7 +902,7 @@ Effect синхронизирует React с внешним browser API и си
 Не используйте `useBinaryFile`, если:
 
 - код выполняется вне React;
-- MIME уже известен и не равен PDF fallback;
+- MIME передаётся отдельно от base64;
 - нужно учитывать filename;
 - данные являются raw binary string;
 - результат нужен немедленно в event handler;
@@ -1148,19 +1114,13 @@ const mime = detectMimeType(fileName, payload);
 const blob = binaryToBlob(payload, mime);
 ```
 
-### Hook определил текст как PDF
-
-Причина: `useBinaryFile` не получает filename, сигнатура текста неизвестна, поэтому применяется PDF fallback.
-
-Решения:
+### Hook вернул `isMimeDetected: false`
 
-- передать data URL с MIME;
-- вызвать функции вручную с известным MIME;
-- не использовать hook для этого контракта.
+Байты успешно декодированы. Их можно скачать как `application/octet-stream`. Если тип известен из метаданных, передайте его в data URL или вызовите `binaryToBlob` с этим MIME.
 
 ### MIME не совпал с содержимым
 
-Проверьте приоритет:
+Проверьте порядок определения MIME в `detectMimeType`:
 
 1. filename;
 2. data URL;
@@ -1185,7 +1145,7 @@ data:<mime>,<percent-encoded-payload>
 
 ### Ошибка появляется в `console.error`
 
-Это текущее поведение `useBinaryFile`: hook логирует пойманную ошибку перед записью `error` state. Для ручного `binaryToBlob` logging не выполняется.
+`useBinaryFile` логирует пойманную ошибку после commit. При прямом вызове `binaryToBlob` за журналирование отвечает вызывающий код.
 
 ### Object URL перестал работать
 
@@ -1260,7 +1220,7 @@ Base64 обычно примерно на треть больше исходно
 
 ### `detectMimeType` декодирует только начало
 
-Signature detection декодирует ограниченное начало base64, поэтому дешевле полного декодирования. При этом распознавание data URL выполняется регулярным выражением над входной строкой и может просканировать весь payload. Последующий `binaryToBlob` в любом случае обрабатывает полный payload.
+Для поиска сигнатуры декодируются первые 128 непробельных символов Base64. Распознавание data URL выполняется регулярным выражением над входной строкой и может просканировать весь payload. Последующий `binaryToBlob` обрабатывает полный payload.
 
 ### Рекомендации
 
@@ -1344,8 +1304,8 @@ import { binaryToBlob, detectMimeType, useBinaryFile } from "@ryuzaki13/react-fo
 | `binaryToBlob` MIME                | `application/octet-stream` |
 | `binaryToBlob` input mode          | base64                     |
 | `detectMimeType` fallback          | `application/pdf`          |
-| `useBinaryFile` initial `data`     | `null`                     |
-| `useBinaryFile` initial `error`    | `null`                     |
+| `useBinaryFile` fallback           | `application/octet-stream` |
+| `useBinaryFile` без входа          | `{ data: null, error: null }` |
 | `useBinaryFile` raw binary support | Нет                        |
 | Автоматическое создание object URL | Нет                        |
 

package/src/excel/README.mdx

@@ -379,6 +379,18 @@ decimals = 2 → #,##0.00
 
 Для OData integer по умолчанию выбирается preset `integer`, для других чисел — `decimal`. Неизвестное имя preset игнорируется и заменяется подходящим default.
 
+Preset с `style: "percent"` создаёт native процентную маску Excel по собственной точности. Встроенный `ratio-percent` использует два знака:
+
+```text
+decimals = 0 → #,##0%
+decimals = 2 → #,##0.00%
+decimals = 3 → #,##0.000%
+```
+
+В строке сохраняется исходная числовая доля: `0.2` с маской `#,##0.00%` Excel отображает как `20.00%`, а `1` — как `100.00%`. Разделитель при отображении зависит от локали Excel. Не умножайте значение заранее и не передавайте строку `"20%"`: масштабирование выполняет сама процентная маска.
+
+Имена пользовательских presets не задают семантику: любой preset с `style: "percent"` получает процентную маску, а `style: "decimal"` или отсутствие `style` сохраняют обычную числовую маску. В частности, существующий `percent` без `style` по-прежнему создаёт `#,##0.00`. Сочетание процентного style с `compact` отклоняется общим resolver числовых presets; Excel не вводит отдельные правила валидации.
+
 ### Форматы дат из presets
 
 По умолчанию:

package/src/formatters/number/README.mdx

@@ -74,6 +74,7 @@ const text = value === undefined ? "Некорректно" : formatNumber(value
 | `currency`               |              0 | Денежное число без символа валюты                          |
 | `price`                  |              0 | Цена без символа валюты                                    |
 | `percent`                |              2 | Процентное число без автоматического умножения и знака `%` |
+| `ratio-percent`          |              2 | Доля с процентным масштабированием и знаком `%`            |
 | `tonnage`                |              1 | Тоннаж                                                     |
 | `compact-currency`       |              0 | Компактное число, усечение                                 |
 | `compact-currency-round` |              0 | Компактное число, округление                               |
@@ -97,6 +98,38 @@ import { DEFAULT_NUMBER_PRESET_NAMES, formatNumber } from "@ryuzaki13/react-foun
 formatNumber(1234.5, DEFAULT_NUMBER_PRESET_NAMES.decimal2);
 ```
 
+## Числовой процент и доля
+
+`percent` и `formatNumberAsPercent` форматируют уже подготовленное число с двумя дробными знаками. `ratio-percent` принимает долю: числу `0.2` соответствует отображение `20,00%`. Передавать предварительно умноженное на 100 значение для этого preset не нужно.
+
+```ts
+import {
+	DEFAULT_NUMBER_PRESET_NAMES,
+	NUMBER_PRESET_NAME_RATIO_PERCENT,
+	formatNumber,
+	formatNumberAsPercent
+} from "@ryuzaki13/react-foundation-lib/formatters";
+
+formatNumber(0.2, "percent"); // "0,20"
+formatNumberAsPercent(0.2); // "0,20"
+formatNumber(0.2, NUMBER_PRESET_NAME_RATIO_PERCENT); // "20,00%"
+formatNumber(1, DEFAULT_NUMBER_PRESET_NAMES.ratioPercent); // "100,00%"
+formatNumber(0, "ratio-percent"); // "0,00%"
+```
+
+Число остаётся неизменным; процентное масштабирование относится только к представлению. Для formatter pipeline достаточно обычного `typedValueFormat` с `numberPresetName: "ratio-percent"`, в том числе у числовой колонки с целочисленным типом `int`. Смена preset не изменяет числовую семантику формул.
+
+Необязательное поле `NumberFormatPreset.style` задаёт способ представления: отсутствие поля или `"decimal"` сохраняет обычный числовой формат, `"percent"` отображает долю со знаком `%`. Встроенный `ratio-percent` использует два дробных знака, собственный preset использует свой `decimals`:
+
+```ts
+registerNumberPreset({ name: "ratio-3", style: "percent", decimals: 3 });
+formatNumber(0.12345, "ratio-3"); // "12,345%"
+```
+
+`style: "percent"` нельзя сочетать с `compact`: такая комбинация явно отклоняется. Существующие compact presets без marker сохраняют своё поведение.
+
+При экспорте через `createTableExcelColumn` из `/excel` этот style создаёт native percentage mask с точностью preset. В строку книги передаётся исходное число `0.2`, а Excel отображает процент. Готовую строку `"20%"` или число `20` вместо доли передавать не следует. Формат старого `percent` остаётся обычным числовым.
+
 ## `formatNumber(value, presetOrName)`
 
 ```ts
@@ -109,7 +142,7 @@ function formatNumber(value: unknown, presetOrName: string | NumberFormatPreset)
 2. вызывает `Number(value)`;
 3. для `NaN` и бесконечности возвращает `"0"`;
 4. находит preset по имени или использует переданный объект;
-5. округляет и форматирует число;
+5. округляет и форматирует число с учётом выбранного `style`;
 6. применяет compact-семантику, если она задана.
 
 ```ts
@@ -175,7 +208,7 @@ formatNumberAsCurrency(1250); // "1 250", без ₽
 formatNumberAsPercent(12.5); // "12,50", без %
 ```
 
-Если нужен суффикс, добавляйте его на UI-уровне или используйте специализированный модуль единиц измерения.
+Для доли со знаком `%` используйте `ratio-percent`. Другие суффиксы добавляйте на UI-уровне или используйте специализированный модуль единиц измерения.
 
 ## Wrappers `OrEmpty`
 
@@ -388,7 +421,7 @@ formatNumber(1234.5, "accounting-2"); // "1 234,50"
 
 Регистрация глобальна для текущего экземпляра модуля. Выполняйте её один раз при старте приложения до компиляции formatter pipeline.
 
-Имя не trim-ится и поля не валидируются. Передавайте непустое устойчивое имя, не меняйте встроенные presets без явной необходимости и проверяйте числовые параметры.
+Имя не trim-ится. Передавайте непустое устойчивое имя, не меняйте встроенные presets без явной необходимости и проверяйте числовые параметры. Сочетание `style: "percent"` с `compact` не поддерживается и отклоняется при регистрации или разрешении preset.
 
 ### `resetNumberPresets()`
 
@@ -426,7 +459,7 @@ formatNumber(1234567.89, {
 
 Такой объект не попадает в реестр. Он полезен для локального стабильного правила; переиспользуемый формат лучше зарегистрировать централизованно.
 
-Параметры не валидируются. Используйте:
+Числовые параметры автоматически не валидируются. Используйте:
 
 - `decimals` — целое неотрицательное число в диапазоне, допустимом `Intl.NumberFormat`;
 - `groupingSize` — положительное целое число;
@@ -450,7 +483,7 @@ truncateNumber(123.789, -1); // 120
 
 ## Кеш `Intl.NumberFormat`
 
-Модуль кеширует formatter по комбинации `decimals + grouping`, что важно для сотен ячеек таблицы.
+Модуль кеширует formatter по комбинации `style + decimals + grouping`, что важно для сотен ячеек таблицы. Числовой и процентный режимы не используют один formatter даже при одинаковой точности.
 
 ```ts
 clearFormatCache();
@@ -506,7 +539,7 @@ const text = parsed === undefined ? "—" : formatNumber(parsed, "decimal-2");
 
 ### Считать `percent` математическим процентом
 
-Preset не умножает `0.25` на 100 и не добавляет `%`. Он выведет `0,25`.
+Preset не умножает `0.25` на 100 и не добавляет `%`. Он выведет `0,25`. Для отображения доли как `25,00%` выбирайте `ratio-percent`.
 
 ### Ожидать валютный символ
 
@@ -529,7 +562,7 @@ Preset не умножает `0.25` на 100 и не добавляет `%`. О
 | Ноль как пустое              | все перечисленные wrappers с суффиксом `OrEmpty`                                                                                                                                                        |
 | Парсинг                      | `toFiniteNumber`, `parseNumber`, `isPositiveValue`, `toPositiveInteger`                                                                                                                                 |
 | Проверка нуля                | `isZeroValue`                                                                                                                                                                                           |
-| Presets                      | `DEFAULT_NUMBER_PRESET_NAMES`, `NUMBER_FORMAT_DEFAULTS`, `getNumberPreset`, `getNumberPresetNames`, `registerNumberPreset`, `resetNumberPresets`                                                        |
+| Presets                      | `DEFAULT_NUMBER_PRESET_NAMES`, `NUMBER_PRESET_NAME_RATIO_PERCENT`, `NUMBER_FORMAT_DEFAULTS`, `getNumberPreset`, `getNumberPresetNames`, `registerNumberPreset`, `resetNumberPresets`                    |
 | Низкоуровневое               | `truncateNumber`, `clearFormatCache`                                                                                                                                                                    |
 | Типы                         | `NumberFormatPreset`, `NumberFormatPresetConfig`, `NumberFormatCompactOptions`, `NumberFormatCompactUnit`, `NumberFormatCompactRoundingMode`                                                            |
 
@@ -540,3 +573,4 @@ Preset не умножает `0.25` на 100 и не добавляет `%`. О
 - [Обзор `formatters`](../README.mdx)
 - [Строковая нормализация](../strings/README.mdx)
 - [Formatter pipeline](../pipeline/README.mdx)
+- [Excel](../../excel/README.mdx)