@ryuzaki13/react-foundation-lib 2.19.0 → 2.21.0

package/src/analytical-table/README.mdx

@@ -0,0 +1,169 @@
+# Analytical Table: чистая модель полного снимка
+
+Модуль `@ryuzaki13/react-foundation-lib/analytical-table` предоставляет вычислительный
+слой аналитической таблицы. Он подходит для SSR и браузера, не использует React hooks,
+QueryClient, serverFn, OData-запросы, SAP metadata, DOM или browser storage. Загрузкой, ошибками,
+отменой и авторизацией владеет транспорт приложения. Результат запроса передаётся
+как неизменяемый `AnalyticalSnapshot`; дополнительных запросов при группировке,
+сортировке или раскрытии нет.
+
+## Контракт и владельцы состояния
+
+`AnalyticalSnapshot<T>` содержит `rows`. Каждая `AnalyticalDataRow<T>` содержит
+стабильный `id`, необязательный `parentId`, значения `values`, исходную запись
+`original` и необязательный предметный `kind`. Нельзя использовать номер позиции
+строки как идентификатор: сортировка и обновление снимка должны сохранять выбор и
+раскрытие. Runtime не изменяет исходные строки и не копирует предметные DTO
+рекурсивно: `original` остаётся ссылкой на неизменяемую запись потребителя.
+
+`AnalyticalColumn<T>` задаёт идентификатор, подпись, тип значения, необязательные
+сравнение, фильтр, агрегацию и вычисление. В столбцах должны присутствовать также
+скрытые зависимости формул. Ключи и отображаемые поля группировки могут ссылаться
+прямо на поля values, не создавая технических столбцов интерфейса. Видимость, ширина,
+закрепление и порядок столбцов относятся к UI и не должны пересчитывать модель.
+Форматирование значений выполняется существующим `/formatters` на границе UI или
+экспорта; runtime сохраняет числа числами.
+
+`AnalyticalViewState` содержит группировки, сортировку, фильтры и идентификаторы
+раскрытых строк. Оно сериализуемо, но не является загружаемыми данными.
+`AnalyticalTableModel` содержит дерево `rows`, все строки `flatRows`, видимые строки
+`visibleRows`, индекс `rowById`, общие итоги `grandTotals` и диагностику иерархии.
+`Map` результата вычисляется локально: передавать его через serverFn не требуется.
+
+```ts
+import {
+	buildAnalyticalTableModel,
+	projectAnalyticalTableExpansion,
+	type AnalyticalSnapshot
+} from "@ryuzaki13/react-foundation-lib/analytical-table";
+
+const snapshot: AnalyticalSnapshot = {
+	rows: [
+		{ id: "order:1", values: { customer: "Компания А", amount: 100 } },
+		{ id: "line:1", parentId: "order:1", values: { amount: 100 } }
+	]
+};
+const model = buildAnalyticalTableModel({
+	snapshot,
+	columns: [
+		{ id: "customer", kind: "dimension" },
+		{ id: "amount", kind: "measure", aggregate: "sum" }
+	],
+	state: {
+		grouping: [{ id: "customer", keyColumnIds: ["customer"] }],
+		sorting: [{ id: "amount", desc: true }]
+	}
+});
+const expanded = projectAnalyticalTableExpansion(model, "all");
+```
+
+## Иерархия и группировки
+
+Построение исходной иерархии использует `/tree-table`. Повторяющиеся идентификаторы,
+сироты и циклы диагностируются по правилам этого модуля. Идентификатор строки не
+может быть пустым. Дополнительная группировка объединяет только корневые ветви:
+исходные дети остаются под своими родителями. Это позволяет сохранять обязательный
+предметный уровень и одновременно группировать его по нескольким признакам.
+
+`AnalyticalGroupingLevel` задаёт `id`, составной `keyColumnIds` и отдельные
+`displayColumnIds`. Идентификатор группы зависит от всего пути ключей и типов
+значений, а не от подписи или порядка строк. Число, строка, null и undefined
+различаются. Отображаемые поля берутся из первой строки группы: потребитель обязан
+обеспечить, что они однозначно определяются ключом. Уровень не может иметь пустой
+список ключей. Повторяющиеся уровни отклоняются; сортировка и фильтры требуют
+известных дескрипторов столбцов.
+
+Сортировка применяется между соседними узлами на каждом уровне; она не отделяет
+детей от родителей. При равенстве сохраняется исходный порядок. Строковое сравнение
+использует `/string-comparison`, календарные значения — `/formatters`. Для иной
+семантики столбец задаёт `compare`.
+
+Фильтры поддерживают equals, notEquals, contains, startsWith, in, between, gt, gte,
+lt, lte, empty и notEmpty; текстовый поиск не зависит от регистра. Условия разных
+столбцов объединяются через AND. Фильтрация работает над исходными вычисленными
+строками **до** дополнительных группировок: совпавший родитель сохраняет ветвь
+целиком, совпавший ребёнок сохраняет путь к нему. Для предметной семантики есть
+`column.filter`.
+
+## Итоги и зернистость
+
+По умолчанию агрегируются только исходные корневые строки. Дочерняя детализация не
+удваивает их меры. `isAggregateRow` позволяет явно выбрать другую зернистость.
+`column.aggregate` поддерживает sum, min, max, avg, count и callback. Числовые
+агрегации принимают только конечные числа; строковое преобразование внешних DTO
+выполняется в адаптере источника. Пустое числовое множество возвращает null;
+count считает непустые значения и возвращает 0 для пустого множества.
+
+`aggregate(context)` возвращает значения групповых/общих итогов и может переопределить
+результаты стандартных агрегаций. Контекст содержит `scope`, `groupingPath` и только
+исходные строки выбранной зернистости. Например, доля должна вычисляться как
+отношение сумм числителя и знаменателя, если предметный учёт требует взвешенного
+результата. Библиотека не усредняет проценты вместо этого правила.
+
+`grandTotalsScope: "filtered"` (по умолчанию) учитывает оставшиеся ветви, `"all"`
+сохраняет общие итоги полного снимка при визуальной фильтрации. `grandTotals: false`
+отключает их вычисление. Раскрытие и выбор строк общие итоги не меняют.
+
+## Формулы и зависимые вычисления
+
+`createAnalyticalCalculationPlan(columns, requiredColumnIds?)` проверяет уникальность
+столбцов, зависимости и циклы, затем строит топологический порядок. `formula`
+содержит `formulaId` и упорядоченные `dependencies`: исполнение использует уже
+существующий реестр `/formulas`, который настраивает composition root приложения.
+`calculate` содержит зависимости и чистый `compute(values)` для вычислений,
+не представленных реестром. Одновременно задать formula и calculate нельзя.
+
+`calculateAnalyticalValues` возвращает отдельные значения. План компилируется один
+раз при построении модели и применяется к данным, затем к рассчитанным итогам.
+Явная агрегация колонки, результат `aggregate(context)` и значения пути группировки
+имеют приоритет над построчной формулой этой колонки. Зависимые формулы читают
+готовые итоги: сумма произведений сохраняется, а отношение сумм вычисляется заново.
+Вычисление должно учитывать отсутствующие значения в итоговой строке. Ошибки
+конфигурации и выполнения формул не скрываются успешным нулём.
+
+## Динамические календарные столбцы
+
+`createAnalyticalDateColumnsPlan` строит day/week/month/quarter/year buckets с
+включительными `from`/`to`; неделя начинается в понедельник. Идентификатор содержит
+гранулярность и календарное начало bucket, а крайние интервалы обрезаются диапазоном.
+По умолчанию допустимо не более 366 столбцов; превышение лимита приводит к ошибке.
+
+Границы диапазона и поле даты каждого факта имеют контракт **YYYY-MM-DD**.
+`Date`, числа и ISO timestamp с временем не принимаются как календарные факты.
+Их приведение с явной timezone-политикой выполняет адаптер до передачи в runtime.
+Неверные границы — ошибка; неверные факты и факты вне диапазона пропускаются.
+
+`projectAnalyticalDateFacts({ rows, facts, plan })` сопоставляет факты по составному
+`identityColumnIds`, добавляя ячейки к копиям значений. Не меняются количество,
+порядок и идентичность исходных строк. Факты с отсутствующей частью ключа
+пропускаются. Без фактов ячейка равна null; существующее одноимённое поле не
+перезаписывается молча. Это отдельная проекция уже загруженных данных, не схема
+дополнительной загрузки.
+
+`aggregateAnalyticalDateFacts` считает общие значения по исходным фактам. Особенно
+важно использовать его для avg: среднее от средних разных строк обычно неверно.
+Групповые итоги для таких данных следует считать тем же способом по соответствующему
+набору исходных фактов через aggregate callback. Факты с неполным ключом исключаются
+и из строк, и из итогов. Область переданного набора фактов определяет потребитель.
+
+## Экспорт и производительность
+
+`projectAnalyticalTableExport` принимает модель, упорядоченные столбцы с необязательным
+`format(value, row)`, область all/visible/selected, `includeGroups` и
+`includeGrandTotals`. Результат содержит заголовки и массивы значений; дальнейшее
+создание XLSX или документа принадлежит `/excel` или `/table-document`. По умолчанию
+экспортируются все строки отфильтрованной модели, включая свёрнутые ветви.
+Предметные строки-родители не считаются синтетическими группами. Общие итоги
+форматируются отдельным `formatTotal(value)`: у них нет исходной строки `original`.
+Без него итоги сохраняют исходные значения, даже если форматтер строк задан отдельно.
+
+Для React следует мемоизировать базовую модель по `snapshot.rows`, колонкам,
+группировкам, сортировке, фильтрам и правилам итогов. Время последнего запроса не
+является зависимостью, когда данные структурно не изменились. Затем отдельно
+вызывается `projectAnalyticalTableExpansion(model, expandedRowIds)`; раскрытие не
+повторяет формулы, группировки и агрегации. Selection и layout остаются в UI.
+
+Полный снимок не требует LRU страниц, sparse placeholders, remote paging или
+второго кэша персональных данных. Если отдельный источник позднее потребует
+постраничную серверную агрегацию, она оформляется отдельной транспортной
+возможностью без изменения предметных правил существующего снимка.

package/src/error-report/README.mdx

@@ -4,7 +4,7 @@ import { Meta } from "@storybook/addon-docs/blocks";
 
 # Error Report
 
-Модуль `@ryuzaki13/react-foundation-lib/error-report` собирает клиентскую диагностику ошибки в versioned bounded draft, временно хранит последние drafts в `sessionStorage` и предоставляет durable IndexedDB queue для отложенной доставки.
+Модуль `@ryuzaki13/react-foundation-lib/error-report` собирает клиентскую диагностику ошибки в versioned bounded draft, по умолчанию временно хранит последние drafts в `sessionStorage` и предоставляет durable IndexedDB queue для отложенной доставки. Browser bootstrap может односторонне перевести capture/drafts в память документа.
 
 Он умеет объединить:
 
@@ -36,6 +36,7 @@ import {
 	captureRuntimeErrorReport,
 	createErrorReportQueue,
 	createErrorInfo,
+	disableErrorReportBrowserStorage,
 	installErrorReportBrowserBreadcrumbs,
 	setErrorReportRuntimeErrorReporter,
 	setErrorReportCaptureOptions,
@@ -76,6 +77,44 @@ isErrorReportingEnabled({ isDev: false });
 - в development capture-функции возвращают `undefined`;
 - тест может явно передать `{ isDev: false }` только в эту функцию, но остальные capture-функции всё равно используют общий `__DEV__`.
 
+## Документ без browser persistence
+
+### `disableErrorReportBrowserStorage(): void`
+
+```ts
+// Browser bootstrap: до первого capture и запуска UI/error-report lifecycle.
+disableErrorReportBrowserStorage();
+```
+
+Вызов односторонне переводит **capture, drafts и persisted-query diagnostics**
+текущего документа в память. Повторный вызов ничего не сбрасывает. Обратного
+включения нет: документ с другим режимом приложение открывает заново.
+`setErrorReportCaptureOptions`, регистрация reporter и их cleanup не меняют
+эту политику. В SSR вызов ничего не делает и не переключает общий process state.
+
+Сам импорт `/error-report` не читает browser storage. В обычном режиме первый
+`getErrorReportDrafts`, `getErrorReportDraft`, `updateErrorReportDraft` или capture
+лениво загружает прежние drafts; дальнейшие чтение и сохранение остаются прежними.
+В memory-режиме последние 10 drafts и отдельный стабильный session ID живут
+только в памяти документа. Уже загруженные обычные drafts не копируются туда,
+а существующие записи в browser storage не удаляются.
+
+Memory capture сохраняет прежний контракт: runtime/query/mutation возвращают
+`Promise<ErrorReportDraft | undefined>`, прямой draft capture —
+`ErrorReportDraft | undefined`. В production создаётся обычный draft в памяти;
+SSR/dev по-прежнему не создают draft. Поэтому UI boundary может продолжать
+использовать `.then` и report ID. Сбор QueryClient diagnostics из памяти остаётся
+доступным; `collectPersistedQueryDiagnostics()` возвращает `[]` без открытия IDB.
+
+Вызов не отменяет native I/O, начатый ранее. Однако его поздний persisted result
+не попадёт в memory draft, а после отключения drafts больше не пишутся в browser
+storage. Для строгого отсутствия чтений выбирать режим нужно в bootstrap.
+
+**Durable queue независима.** `createErrorReportQueue()` — явный storage API;
+эта функция его не переключает. Приложение отдельно исключает создание очереди,
+enqueue и запуск delivery в документе без persistence. Вызов также не меняет
+Query persistence, Service Worker, пользовательские черновики или transport.
+
 ## Compile-time константы
 
 Потребитель должен определить:
@@ -430,7 +469,7 @@ type ErrorReportDraft = {
 };
 ```
 
-`reportId` — UUID отдельного отчёта. `sessionId` стабилен в текущем `sessionStorage`. `createdUtc` формируется как OData datetime UTC.
+`reportId` — UUID отдельного отчёта. По умолчанию `sessionId` стабилен в текущем `sessionStorage`; после browser opt-out используется отдельный ID только в памяти документа. `createdUtc` формируется как OData datetime UTC.
 
 Payload содержит category/source/error, build environment, client, location, viewport, breadcrumbs и optional секции query/mutation/react/context.
 
@@ -452,11 +491,11 @@ parseErrorReportDrafts(value);
 
 ### Хранение
 
-Versioned drafts сохраняются под ключом `${__APP_ID__}.errorReport.drafts.v2`. В одной вкладке остаются последние 10 элементов. Старые удаляются с начала массива. Предыдущая unversioned storage-форма не загружается.
+По умолчанию versioned drafts сохраняются под ключом `${__APP_ID__}.errorReport.drafts.v2`. В одной вкладке остаются последние 10 элементов. Старые удаляются с начала массива. Предыдущая unversioned storage-форма не загружается. После browser opt-out тот же лимит применяется к отдельному memory store без чтения или удаления browser records.
 
 Storage errors и некорректный JSON подавляются. При переполнении sessionStorage текущее in-memory состояние обновится, но запись на диск может не сохраниться.
 
-Модуль загружает drafts при первом импорте. Это модульное состояние, общее для всех consumers одного bundle.
+Импорт не загружает drafts. В обычном режиме они читаются лениво при первом обращении к draft API, после чего модульное состояние разделяют consumers одного bundle. В memory-режиме чтения browser drafts нет.
 
 ## Durable IndexedDB queue
 
@@ -708,7 +747,7 @@ Foundation удаляет известные secret-like keys и email, но н
 
 ### Мутировать результат `getErrorReportDrafts()`
 
-Используйте `updateErrorReportDraft`; прямое изменение обходит сохранение в sessionStorage.
+Используйте `updateErrorReportDraft`; прямое изменение обходит валидацию lifecycle и выбранное хранилище drafts.
 
 ### Передавать `UseQueryResult` вместо cache Query