@ryuzaki13/react-foundation-lib 1.4.0 → 1.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,110 +0,0 @@
1
- # `shared/lib/binary`
2
-
3
- Модуль содержит небольшие утилиты для работы с бинарным содержимым, которое приходит в приложение строкой. Основной сценарий — получить из SAP/OData/REST-ответа base64-документ, определить его MIME-тип и передать дальше как `Blob` в просмотрщик, ссылку скачивания или API браузера.
4
-
5
- Модуль находится в `shared`, поэтому не содержит бизнес-знаний о типах документов конкретного приложения. Например, `detectMimeType` не использует коды вроде `documentType`: MIME определяется только по имени файла, data URL или сигнатуре самих данных.
6
-
7
- ## Публичный API
8
-
9
- ```ts
10
- import { binaryToBlob, detectMimeType, useBinaryFile } from "@/shared/lib";
11
- ```
12
-
13
- Также модуль реэкспортируется через общий `@/shared/lib`.
14
-
15
- ### `binaryToBlob`
16
-
17
- ```ts
18
- binaryToBlob(binaryData: string, mimeType?: string, isBase64?: boolean): Blob
19
- ```
20
-
21
- Преобразует строковое бинарное содержимое в `Blob`.
22
-
23
- Параметры:
24
-
25
- - `binaryData` — исходные данные. По умолчанию ожидается base64-строка.
26
- - `mimeType` — MIME-тип создаваемого Blob. Если передана пустая строка, используется `application/octet-stream`.
27
- - `isBase64` — признак формата входных данных. По умолчанию `true`. Если передать `false`, строка будет обработана как raw binary string.
28
-
29
- Поддерживаются:
30
-
31
- - обычный base64;
32
- - base64 с пробелами и переносами строк;
33
- - URL-safe base64 с символами `-` и `_`;
34
- - data URL вида `data:application/pdf;base64,...`.
35
-
36
- Функция возвращает именно `Blob`. Object URL нужно создавать отдельно через `URL.createObjectURL(blob)` и освобождать через `URL.revokeObjectURL(url)` на стороне вызывающего кода.
37
-
38
- Пример:
39
-
40
- ```ts
41
- const mime = detectMimeType(fileName, fileContent);
42
- const blob = binaryToBlob(fileContent, mime);
43
- const url = URL.createObjectURL(blob);
44
- ```
45
-
46
- ### `detectMimeType`
47
-
48
- ```ts
49
- detectMimeType(fileName?: string, binaryData?: string): string
50
- ```
51
-
52
- Определяет MIME-тип без привязки к бизнес-типу документа.
53
-
54
- Порядок определения:
55
-
56
- 1. По расширению `fileName`.
57
- 2. По MIME-типу из data URL.
58
- 3. По сигнатуре первых байтов base64-данных.
59
- 4. Fallback `application/pdf`.
60
-
61
- Поддерживаемые расширения включают распространённые документы и изображения: `pdf`, `jpg`, `jpeg`, `png`, `gif`, `webp`, `svg`, `bmp`, `tif`, `tiff`, `xml`, `txt`, `csv`, `json`, `doc`, `docx`, `xls`, `xlsx`, `ppt`, `pptx`, `zip`.
62
-
63
- По сигнатуре определяются:
64
-
65
- - PDF;
66
- - JPEG;
67
- - PNG;
68
- - GIF;
69
- - WEBP;
70
- - ZIP;
71
- - XML-подобные текстовые данные.
72
-
73
- Fallback `application/pdf` сохранён намеренно: большинство документов в текущем контуре отображаются как PDF, а неизвестный тип чаще должен открыться в документном просмотрщике, чем стать произвольным `application/octet-stream`.
74
-
75
- ### `useBinaryFile`
76
-
77
- ```ts
78
- useBinaryFile(bin: string | undefined): {
79
- data: { blob: Blob; mime: string } | null;
80
- error: string | null;
81
- }
82
- ```
83
-
84
- React-хук для компонентов, которым нужно получить готовую пару `Blob + MIME` из base64-строки.
85
-
86
- Поведение:
87
-
88
- - при наличии `bin` определяет MIME через `detectMimeType`;
89
- - создаёт `Blob` через `binaryToBlob`;
90
- - пишет ошибку в `error`, если данные некорректны;
91
- - очищает `data` и `error`, когда `bin` становится пустым.
92
-
93
- Хук не создаёт object URL и не управляет его жизненным циклом. Это должно оставаться в компоненте, потому что именно компонент знает, когда URL больше не нужен.
94
-
95
- ## Ограничения
96
-
97
- - Модуль рассчитан на браузерное окружение и использует `Blob` и `atob`.
98
- - MIME по сигнатуре определяется только для ограниченного набора популярных форматов.
99
- - Функции не валидируют содержимое файла полностью. Проверяется только формат base64 и несколько первых байтов для MIME-detection.
100
- - Модуль не должен импортировать сущности, фичи, виджеты или приложения. Если нужен бизнес-маппинг кодов документов, его нужно держать в соответствующем доменном слое и передавать результат в этот модуль уже как MIME-строку.
101
-
102
- ## Проверки
103
-
104
- Поведение покрыто тестами в `binaryToBlob.test.ts`.
105
-
106
- Релевантный узкий запуск:
107
-
108
- ```bash
109
- npm run test -- run src/shared/lib/binary/binaryToBlob.test.ts
110
- ```
@@ -1,150 +0,0 @@
1
- import { Meta } from "@storybook/addon-docs/blocks";
2
-
3
- <Meta title="Foundation Lib/Browser и React API" />
4
-
5
- # Browser и React API
6
-
7
- Эти entrypoint работают только после монтирования в браузере. Вызывайте hooks на верхнем уровне React-компонента или custom hook, а императивные действия (скачивание, clipboard, открытие меню) — из event handler. Они не заменяют UI primitives из `@ryuzaki13/react-foundation-ui`.
8
-
9
- ## Общие hooks
10
-
11
- ```ts
12
- import {
13
- useDebounce,
14
- useDebouncedCallback,
15
- useDndSortableSensors,
16
- useFloatingListbox,
17
- useSearchLink,
18
- useSearchParams,
19
- useThrottledCallback
20
- } from "@ryuzaki13/react-foundation-lib/hooks";
21
- ```
22
-
23
- | API | Назначение и lifecycle |
24
- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
25
- | `useDebounce(value, delay)` | Возвращает отложенное значение. Не запускает network запрос сам — используйте результат в owner Query/UI flow. |
26
- | `useDebouncedCallback(callback, delay, { flushOnUnmount? })` | Возвращает debounced callback. Опция `flushOnUnmount` нужна только когда финальный вызов действительно обязателен. |
27
- | `useThrottledCallback(callback, interval, { flushOnUnmount? })` | Возвращает `{ call, flush, cancel }`; стратегия last-write-wins. Вызывайте `flush` на границе сохранения, `cancel` при смене identity. |
28
- | `useDndSortableSensors(distanceOrOptions?)` | Готовые Pointer/Keyboard sensors для `@dnd-kit/sortable`; default distance — 6 px. |
29
- | `useLazyComponent(loader, ...)` | Используйте для lazy UI по устойчивому loader/cache key, а не вызывайте dynamic import во время render. |
30
- | `useReferenceTrace(name, value)` | Development diagnostic для отслеживания смены ссылок; не часть бизнес-логики. |
31
- | `useBlockBrowserZoom(enabled)` | Подписывается на browser events для блокировки zoom. Используйте только в явном специализированном UX, не как default. |
32
-
33
- ### Search и floating listbox
34
-
35
- `useSearchParams<K>(allowedKeys?)` и `useSearchLink<K>()` требуют `@tanstack/react-router`. Первый возвращает `{ params, filteredParams, setParams }` и выполняет navigation с `replace: true`; второй возвращает `buildLink(params)`. Оба работают с URL state, а не с произвольным Zustand/local store.
36
-
37
- `useFloatingListbox<T>(options)` требует `@floating-ui/react` и объединяет ref, ARIA-interactions, keyboard navigation и placement. Передавайте:
38
-
39
- - `options`, `selectedIndex`, `getOptionDisabled` — данные и доступность опций;
40
- - optional controlled `open` + `onOpenChange`;
41
- - `onSelect`, `closeOnSelect`, `focusFloatingOnOpen`, `restoreFocusOnClose` — interaction policy;
42
- - `placement` и `placementStrategy: "flip" | "auto"` — placement;
43
- - `resolveFloatingSize(context)` — только layout/CSS size policy.
44
-
45
- Hook возвращает Floating UI props/refs и их нужно распространять на reference, floating element и options строго по его контракту. Не заменяйте эти props самодельными keyboard handlers: это нарушит `aria-activedescendant`, focus restore и cleanup `autoUpdate`.
46
-
47
- ## DOM и overlay helpers
48
-
49
- ```ts
50
- import {
51
- downloadFileFromBlob,
52
- getOrCreatePortalRoot,
53
- useClickOutside,
54
- useEscapeDismiss,
55
- useFocusTrap,
56
- useIntersectionObserver,
57
- useOverlayFocus
58
- } from "@ryuzaki13/react-foundation-lib/dom";
59
- ```
60
-
61
- | API | Контракт |
62
- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
63
- | `downloadFileFromObjectURL(filename, objectUrl)` | Инициирует download по готовому object URL; не владеет временем `URL.revokeObjectURL`. |
64
- | `downloadFileFromBlob(filename, blob)` | Создаёт временный object URL и инициирует download. |
65
- | `downloadFileFromJson(filename, payload)` | Сериализует payload в JSON blob и скачивает. |
66
- | `getOrCreatePortalRoot(id)` | Возвращает/создаёт DOM root или `null`, если `document` недоступен. |
67
- | `useClickOutside(refOrRefs, handler)` | Вызывает handler при внешнем pointer interaction; передавайте стабильные refs. |
68
- | `useEscapeDismiss(options)` | Dismiss только для active/enabled overlay; поддерживает container и целевой document. |
69
- | `useFocusTrap(isOpen)` | Возвращает ref для trapping focus внутри открытого overlay. |
70
- | `useOverlayFocus(options)` | Управляет initial focus и restore для overlay; применяйте вместе с accessible dialog/menu. |
71
- | `useElementHeightObserver(ref)` | Следит за высотой через `ResizeObserver`; результат используйте для layout, не для копирования props в state. |
72
- | `useIntersectionObserver(ref, options?)` | Возвращает intersection state DOM element. |
73
- | `useIsTouchDevice()` | Реактивно сообщает touch-capability браузера. |
74
-
75
- Hooks сами подписываются и очищают observers/listeners при unmount. Не вызывайте `getOrCreatePortalRoot` или browser API в server render; hook-проверки не делают UI SSR-safe автоматически.
76
-
77
- ## Clipboard, media и context menu
78
-
79
- ```ts
80
- import { useCopyText, useCopyElementTextWithFeedback } from "@ryuzaki13/react-foundation-lib/copy";
81
- import { useMediaQuery, useMatchMedia, resolveResponsiveValue } from "@ryuzaki13/react-foundation-lib/media";
82
- import { createVirtualAnchor, openMenu } from "@ryuzaki13/react-foundation-lib/context-menu";
83
- ```
84
-
85
- ### `copy`
86
-
87
- | API | Результат |
88
- | ------------------------------------- | ----------------------------------------------------------------- |
89
- | `useCopyText()` | Возвращает copy action для строки через Clipboard API с fallback. |
90
- | `useElementText(ref)` | Читает текст из DOM element. |
91
- | `useCopyElementText(ref)` | Комбинирует чтение элемента и copy. |
92
- | `useCopyFeedback()` | Локальное временное состояние feedback после успешного copy. |
93
- | `useCopyElementTextWithFeedback(ref)` | Удобная композиция copy element + feedback. |
94
-
95
- Copy может быть отклонён browser permissions; показывайте ожидаемую UI-ошибку, но не считайте clipboard источником истины для сохранения данных.
96
-
97
- ### `media`
98
-
99
- `BREAKPOINTS_EM` и `Breakpoint` задают стандартные breakpoints; `useMatchMedia()` возвращает `MediaMatches`. Для конкретного media query используйте `useMediaQuery(query, { ssrFallback? })`; `ssrFallback` определяет значение только до browser hydration/в окружении без `matchMedia`.
100
-
101
- `ResponsiveValue<T>`, `isResponsiveMap`, `resolveResponsiveValue` и `resolveProps` — pure helpers для responsive props. `getCurrentFontSize`, `getCurrentLineHeight`, `getControlHeight`, `pxToEm` читают layout/DOM: не вызывайте их в render, если результат влияет на state без external synchronization.
102
-
103
- ### `context-menu`
104
-
105
- `MenuAnchor`, `MenuState`, `MenuPoint`, `OpenMenuPayload` — serializable contracts состояния меню. `openMenu(payload)`, `closeMenu(state)` и `toggleMenu(state, payload)` — pure reducers; их можно держать в local/store owner.
106
-
107
- Для pointer menu используйте `getMenuPointFromEvent(event)` и `createVirtualAnchor(point, contextElement?)`. Для keyboard anchor используйте `getMenuPointFromRect(rect)`. API лишь описывает состояние/anchor; отображение и accessibility menu остаются у UI-компонента.
108
-
109
- ## Virtualizer, PWA и Three.js
110
-
111
- ### Infinite virtualizer
112
-
113
- ```ts
114
- import { useFetchNextPageEffect } from "@ryuzaki13/react-foundation-lib/virtualizer";
115
- ```
116
-
117
- Hook принимает `{ virtualItems, currentItemsCount, hasNextPage, fetchNextPage }`; при достижении последней виртуальной строки запускает один следующий fetch и не создаёт параллельные запросы. `fetchNextPage` должен быть стабильным Query action. Не передавайте raw `fetch` и не подменяйте backend state локальным массивом.
118
-
119
- ### Service Worker
120
-
121
- ```ts
122
- import { parseSwCachePolicy, buildSwCachePolicyValue, useServiceWorkerUpdate } from "@ryuzaki13/react-foundation-lib/pwa";
123
- ```
124
-
125
- `useServiceWorkerUpdate()` возвращает `{ hasUpdate, applyUpdate, dismiss }`. Его задача — UI-поверхность для уже настроенного приложения с Service Worker; hook не публикует и не настраивает private registration API.
126
-
127
- `pwa/sw-cache-policy` — отдельный точечный import того же pure policy API:
128
-
129
- | API | Контракт |
130
- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------- |
131
- | `parseSwCachePolicy(value)` | Парсит `off`, `ttl=<duration>` или `bust=<duration>` с `max`/`name`; invalid input даёт `undefined`. |
132
- | `buildSwCachePolicyValue(draft)` | Нормализует `SwCachePolicyDraft` в canonical transport string. |
133
- | `normalizeSwCacheName(value)` | Делает безопасное lower-case cache name или `undefined`. |
134
- | `resolveSwCacheCacheNameByPolicy(value)` | Возвращает вычисленное имя cache только для `ttl`/`bust`. |
135
-
136
- Пример: `ttl=24h;max=200;name=reference`. Это policy для transport/Service Worker, а не замена TanStack Query cache. Не включайте в SW cache auth-sensitive responses без отдельной security policy.
137
-
138
- ### Доступность Three.js
139
-
140
- ```ts
141
- import { useThreeSceneAvailability, disableThreeSceneForSession } from "@ryuzaki13/react-foundation-lib/three-scene";
142
- ```
143
-
144
- | API | Назначение |
145
- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
146
- | `isThreeSceneSupported(options?)` | Проверяет browser WebGL/WebGL2 support. |
147
- | `isThreeSceneDisabledForSession(key?)`, `disableThreeSceneForSession(key?)` | Читают/устанавливают opt-out текущей tab session. |
148
- | `useThreeSceneAvailability(options?)` | React state с `pending`/`available`/`unavailable` и причиной (`sessionDisabled`, `reducedMotion`, `webglUnsupported`, `ssr`). |
149
-
150
- Проверка support не заменяет обработку ошибки renderer. При `unavailable` всегда рендерите семантический non-Three fallback.
@@ -1,163 +0,0 @@
1
- import { Meta } from "@storybook/addon-docs/blocks";
2
-
3
- <Meta title="Foundation Lib/Файлы и Excel" />
4
-
5
- # Файлы, бинарные данные и Excel
6
-
7
- Эта страница описывает browser-only API для чтения пользовательских файлов, преобразования base64 и формирования `.xlsx`. Подготовка бизнес-полей, проверка прав доступа и отправка файла на сервер остаются ответственностью host-приложения.
8
-
9
- ## `file`: чтение файлов и HTTP-заголовки
10
-
11
- ```ts
12
- import {
13
- createContentDispositionHeader,
14
- readFile,
15
- readImageFile,
16
- resolveMimeTypeByExtension,
17
- type ReadFileError,
18
- type ReadImageError
19
- } from "@ryuzaki13/react-foundation-lib/file";
20
- ```
21
-
22
- ### Когда использовать
23
-
24
- - `readFile` — получить `dataUrl` для preview или `ArrayBuffer` для дальнейшей обработки;
25
- - `readImageFile` — то же для изображений с проверкой image MIME и размером изображения;
26
- - helpers Content-Disposition — сформировать безопасный заголовок в browser-compatible/edge runtime коде;
27
- - `resolveMimeTypeByExtension` — определить MIME по расширению, если содержимого для sniffing нет.
28
-
29
- ### `readFile`
30
-
31
- ```ts
32
- readFile(file, options?): Promise<ReadFileResult>
33
- ```
34
-
35
- | Опция | Назначение |
36
- | --------------------------------- | ------------------------------------------------- |
37
- | `mode?: "data-url"` | Режим по умолчанию. Результат содержит `dataUrl`. |
38
- | `mode: "array-buffer"` | Результат содержит `buffer`. |
39
- | `allowedMime?: readonly string[]` | Точный список разрешённых MIME. |
40
- | `maxBytes?: number` | Максимальный размер файла в байтах. |
41
- | `signal?: AbortSignal` | Отменяет чтение через `FileReader.abort()`. |
42
-
43
- Возвращаемый discriminated union всегда содержит `file` и `meta` (`name`, `mime`, `size`, `lastModified`). После проверки `result.mode` TypeScript раскрывает либо `dataUrl`, либо `buffer`.
44
-
45
- ```ts
46
- const result = await readFile(file, {
47
- mode: "data-url",
48
- allowedMime: ["application/pdf"],
49
- maxBytes: 10 * 1024 * 1024,
50
- signal
51
- });
52
-
53
- if (result.mode === "data-url") {
54
- previewUrl = result.dataUrl;
55
- }
56
- ```
57
-
58
- `ReadFileError` имеет предсказуемый `code`: `NO_FILE`, `MIME_NOT_ALLOWED`, `FILE_TOO_LARGE`, `READ_ABORTED` или `READ_FAILED`. Обрабатывайте его как ожидаемую ошибку выбора файла, а остальные ошибки не скрывайте.
59
-
60
- ### `readImageFile`
61
-
62
- ```ts
63
- readImageFile(image, options?): Promise<ReadImageResult>
64
- ```
65
-
66
- Поддерживаемые `ImageMime`: `image/png`, `image/jpeg`, `image/webp`, `image/gif`, `image/svg+xml`, `image/avif`. В режиме `data-url` результат дополнительно включает `dimensions` (`width`, `height`). В режиме `array-buffer` декодирование изображения не выполняется.
67
-
68
- `ReadImageError` расширяет коды `ReadFileError` значениями `NOT_AN_IMAGE` и `IMAGE_DECODE_FAILED`.
69
-
70
- ### Дополнительный API `file`
71
-
72
- | API | Контракт |
73
- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
74
- | `buildMeta(file)` | Возвращает serializable метаданные `FileMeta`. |
75
- | `attachAbort(signal, reader)` | Привязывает отмену к `FileReader`; возвращённую функцию cleanup вызывают только custom consumers низкоуровневого API. |
76
- | `assertNotAborted(signal?)` | Бросает `ReadFileError("READ_ABORTED")`, если сигнал уже отменён. |
77
- | `assertValidAllowedMime`, `assertValidAccept` | Проверяют конфигурацию accept/MIME до чтения. |
78
- | `sanitizeFileName(value, fallback?)` | Удаляет unsafe символы из имени. |
79
- | `encodeFilenameRFC5987(value)` | Кодирует Unicode filename для HTTP header. |
80
- | `createAsciiFilenameFallback(value, fallback?)` | Создаёт ASCII fallback для старых consumers заголовка. |
81
- | `createContentDispositionHeader(options)` | Создаёт `inline`/`attachment` Content-Disposition с `filename` и `filename*`. |
82
-
83
- ## `binary`: base64 → `Blob`
84
-
85
- ```ts
86
- import { binaryToBlob, detectMimeType, useBinaryFile } from "@ryuzaki13/react-foundation-lib/binary";
87
- ```
88
-
89
- | API | Вход и результат |
90
- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
91
- | `binaryToBlob(binaryData, mimeType?, isBase64?)` | Создаёт `Blob` из base64/data URL (по умолчанию) или raw binary string (`false`). Пустые или некорректные данные бросают `Error`. |
92
- | `detectMimeType(fileName?, binaryData?)` | Ищет MIME по расширению, data URL, затем сигнатуре base64. Неопределённый документ трактует как `application/pdf`. |
93
- | `useBinaryFile(bin)` | React hook, возвращает `{ data: { blob, mime } \| null, error: string \| null }`. |
94
-
95
- ```ts
96
- const mime = detectMimeType("report.pdf", base64);
97
- const blob = binaryToBlob(base64, mime);
98
- const objectUrl = URL.createObjectURL(blob);
99
-
100
- // Владелец UI обязан освободить URL при смене файла/размонтировании.
101
- URL.revokeObjectURL(objectUrl);
102
- ```
103
-
104
- `useBinaryFile` не создаёт object URL и не освобождает его: это lifecycle конкретного preview-компонента. Hook использует `Blob` и `atob`, поэтому не вызывайте его в SSR или worker без совместимого polyfill.
105
-
106
- ## `excel`: скачивание `.xlsx`
107
-
108
- ```ts
109
- import {
110
- buildExcelAutoFilterRef,
111
- buildExcelSheetData,
112
- createTableExcelColumn,
113
- downloadExcelFile,
114
- downloadExcelWorkbook,
115
- downloadResolvedExcelTable,
116
- downloadResolvedExcelWorkbook,
117
- resolveExcelCellStyleFromState,
118
- resolveExcelSheetNames
119
- } from "@ryuzaki13/react-foundation-lib/excel";
120
- ```
121
-
122
- ### Базовый экспорт
123
-
124
- `downloadExcelFile({ fileName, columns, rows, autoFilter?, getCellStyle? })` создаёт один лист; `downloadExcelWorkbook({ fileName, sheets })` — книгу из нескольких листов. Это asynchronous browser API, который инициирует скачивание через `write-excel-file`.
125
-
126
- ```ts
127
- await downloadExcelFile({
128
- fileName: "users.xlsx",
129
- columns: [
130
- { id: "name", header: "Имя", type: String, width: 28 },
131
- { id: "createdAt", header: "Дата", type: Date, format: "dd.mm.yyyy" }
132
- ],
133
- rows: [{ name: "Анна", createdAt: new Date("2026-07-30") }],
134
- autoFilter: true
135
- });
136
- ```
137
-
138
- | Public type/API | Назначение |
139
- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
140
- | `ExcelColumn`, `ExcelRow`, `ExcelCellStyle` | Контракты столбца, строки и стиля ячейки. `type` передаёт в файл истинные `Number`/`Date`/`Boolean`, а не UI-строку. |
141
- | `buildExcelSheetData(args)` | Строит данные листа без запуска download; подходит для тестируемой подготовки. |
142
- | `buildExcelAutoFilterRef(columns, rows)` | Даёт Excel-диапазон или `undefined` для пустой сетки. |
143
- | `resolveExcelSheetNames(names)` | Нормализует ограничения Excel (31 символ, forbidden chars) и делает имена уникальными. |
144
- | `resolveExcelCellStyleFromState(state)` | Преобразует `State` в базовый цвет текста Excel. |
145
-
146
- ### Экспорт подготовленной таблицы
147
-
148
- `TableExcelColumnDescriptor` связывает generic Excel column с OData type/role и необязательным `formattersPipeline`. Используйте `createTableExcelColumn(descriptor)` для получения типизированного столбца, затем передавайте значения строк без предварительного UI-форматирования.
149
-
150
- | API | Назначение |
151
- | -------------------------------------------------------------- | --------------------------------------------------------------------------------- |
152
- | `resolveTableExcelColumnType(descriptor)` | Выбирает `String`/`Number`/`Date`/`Boolean` по OData metadata и роли. |
153
- | `createTableExcelColumn(descriptor)` | Создаёт `ExcelColumn` с Excel-маской числа/даты из published formatter contracts. |
154
- | `downloadResolvedExcelTable({ fileName, table, autoFilter? })` | Скачивает одну уже подготовленную таблицу. |
155
- | `downloadResolvedExcelWorkbook({ fileName, sheets })` | Скачивает несколько `ResolvedExcelTable` как листы книги. |
156
-
157
- Не передавайте в `rows` отформатированные через `Intl` строки для числовых и date-столбцов: Excel потеряет сортировку, формулы и формат. Строки создавайте только для действительно текстовых значений.
158
-
159
- ## Ограничения
160
-
161
- - Все три entrypoint ориентированы на DOM/browser; не вызывайте их в server-only коде.
162
- - MIME по имени/сигнатуре не является проверкой безопасности содержимого. Сервер обязан валидировать загружаемые файлы повторно.
163
- - `download*` имеет пользовательский side effect. Вызывайте его из event handler, а не из render/effect при монтировании.