@ryuzaki13/react-foundation-ui 1.8.11 → 1.8.13

package/storybook-static/assets/README-iqQHdhZ4.js

@@ -0,0 +1,416 @@
+import{n as e}from"./rolldown-runtime-DkW27tQK.js";import{n as t}from"./iframe-o7sH2IXC.js";import{i as n,r}from"./react-Bl2r1tuC.js";import{l as i,m as a}from"./blocks-BY40djCc.js";function o(e){let t={code:`code`,h1:`h1`,h2:`h2`,h3:`h3`,li:`li`,ol:`ol`,p:`p`,pre:`pre`,strong:`strong`,table:`table`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,ul:`ul`,...n(),...e.components};return(0,c.jsxs)(c.Fragment,{children:[(0,c.jsx)(i,{title:`Foundation Lib/Errors/Error Report`}),`
+`,(0,c.jsx)(t.h1,{id:`error-report`,children:`Error Report`}),`
+`,(0,c.jsxs)(t.p,{children:[`Модуль `,(0,c.jsx)(t.code,{children:`@ryuzaki13/react-foundation-lib/error-report`}),` собирает клиентскую диагностику ошибки в структурированный draft и временно хранит последние drafts в `,(0,c.jsx)(t.code,{children:`sessionStorage`}),`.`]}),`
+`,(0,c.jsx)(t.p,{children:`Он умеет объединить:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsx)(t.li,{children:`нормализованную ошибку и stack trace;`}),`
+`,(0,c.jsx)(t.li,{children:`сведения о browser/build;`}),`
+`,(0,c.jsx)(t.li,{children:`URL и viewport;`}),`
+`,(0,c.jsx)(t.li,{children:`последние действия пользователя — breadcrumbs;`}),`
+`,(0,c.jsx)(t.li,{children:`состояние TanStack Query без полного query data;`}),`
+`,(0,c.jsx)(t.li,{children:`технические сведения о persisted queries;`}),`
+`,(0,c.jsx)(t.li,{children:`контекст React/runtime/transport;`}),`
+`,(0,c.jsxs)(t.li,{children:[`lifecycle доставки: `,(0,c.jsx)(t.code,{children:`pending`}),`, `,(0,c.jsx)(t.code,{children:`sending`}),`, `,(0,c.jsx)(t.code,{children:`sent`}),`, `,(0,c.jsx)(t.code,{children:`failed`}),`.`]}),`
+`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Важная граница: `,(0,c.jsx)(t.strong,{children:`lib-пакет не отправляет отчёт на сервер`}),`. Он формирует draft и предоставляет точки подключения. Авторизация, HTTP/API delivery, retry, пользовательское согласие и UI принадлежат приложению либо API-пакету.`]}),`
+`,(0,c.jsx)(t.h2,{id:`установка`,children:`Установка`}),`
+`,(0,c.jsx)(t.p,{children:`Модуль интегрируется с TanStack Query и query persistence.`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-bash`,children:`npm install @ryuzaki13/react-foundation-lib \\
+  @tanstack/react-query \\
+  @tanstack/query-persist-client-core
+`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import {
+	captureRuntimeErrorReport,
+	createErrorInfo,
+	installErrorReportBrowserBreadcrumbs,
+	setErrorReportRuntimeErrorReporter,
+	type ErrorReportDraft
+} from "@ryuzaki13/react-foundation-lib/error-report";
+`})}),`
+`,(0,c.jsx)(t.h2,{id:`ментальная-модель`,children:`Ментальная модель`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-text`,children:`исходная ошибка
+  → capture-функция
+  → нормализация + diagnostics + breadcrumbs
+  → ErrorReportDraft(status = pending)
+  → sessionStorage, максимум 10 drafts
+  → app/API delivery
+  → updateErrorReportDraft(status = sending/sent/failed)
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Сбор отчёта — дополнительный диагностический сценарий. Ошибка репортера не должна заменять исходную ошибку и ломать основной пользовательский поток.`}),`
+`,(0,c.jsx)(t.h2,{id:`когда-сбор-включён`,children:`Когда сбор включён`}),`
+`,(0,c.jsx)(t.h3,{id:`iserrorreportingenabledoptions`,children:(0,c.jsx)(t.code,{children:`isErrorReportingEnabled(options?)`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`isErrorReportingEnabled();
+isErrorReportingEnabled({ isDev: false });
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Возвращает `,(0,c.jsx)(t.code,{children:`true`}),` только в браузере и только вне dev-режима. По умолчанию режим читается из compile-time `,(0,c.jsx)(t.code,{children:`__DEV__`}),`.`]}),`
+`,(0,c.jsx)(t.p,{children:`Следствия:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsx)(t.li,{children:`при SSR draft не создаётся;`}),`
+`,(0,c.jsxs)(t.li,{children:[`в development capture-функции возвращают `,(0,c.jsx)(t.code,{children:`undefined`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`тест может явно передать `,(0,c.jsx)(t.code,{children:`{ isDev: false }`}),` только в эту функцию, но остальные capture-функции всё равно используют общий `,(0,c.jsx)(t.code,{children:`__DEV__`}),`.`]}),`
+`]}),`
+`,(0,c.jsx)(t.h2,{id:`compile-time-константы`,children:`Compile-time константы`}),`
+`,(0,c.jsx)(t.p,{children:`Потребитель должен определить:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`declare const __DEV__: boolean;
+declare const __APP_ID__: string;
+declare const __APP_BUILD_ID__: string;
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`__APP_ID__`}),` входит в ключи `,(0,c.jsx)(t.code,{children:`sessionStorage`}),`, а `,(0,c.jsx)(t.code,{children:`__APP_BUILD_ID__`}),` помогает связать ошибку с деплоем.`]}),`
+`,(0,c.jsx)(t.p,{children:`Пример Vite:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`define: {
+  __DEV__: JSON.stringify(mode !== "production"),
+  __APP_ID__: JSON.stringify("education-arm"),
+  __APP_BUILD_ID__: JSON.stringify(process.env.BUILD_ID ?? "local"),
+}
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Модуль persisted diagnostics использует инфраструктуру `,(0,c.jsx)(t.code,{children:`/query-client`}),`; её compile-time persistence-константы тоже должны быть настроены, если приложение включает соответствующую часть query persistence.`]}),`
+`,(0,c.jsx)(t.h2,{id:`быстрый-старт-для-runtime-ошибок`,children:`Быстрый старт для runtime-ошибок`}),`
+`,(0,c.jsx)(t.h3,{id:`прямой-capture`,children:`Прямой capture`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`try {
+	await runImport();
+} catch (error) {
+	const draft = await captureRuntimeErrorReport(error, {
+		source: "users-import",
+		detail: {
+			fileType: selectedFile.type,
+			step: "upload"
+		}
+	});
+
+	if (draft) {
+		await sendDraft(draft);
+	}
+
+	throw error;
+}
+`})}),`
+`,(0,c.jsx)(t.h3,{id:`через-независимый-runtime-facade`,children:`Через независимый runtime facade`}),`
+`,(0,c.jsx)(t.p,{children:`Общий код может не знать о QueryClient и delivery. Приложение один раз регистрирует reporter:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`setErrorReportRuntimeErrorReporter(async (error, context) => {
+	const draft = await captureRuntimeErrorReport(error, context, queryClient);
+
+	if (draft) {
+		await deliverErrorReport(draft);
+	}
+});
+`})}),`
+`,(0,c.jsx)(t.p,{children:`После этого любой нижний слой может безопасно вызвать:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`await reportRuntimeError(error, {
+	source: "document-download",
+	detail: { action: "download" }
+});
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`reportRuntimeError`}),` ничего не делает без зарегистрированного reporter и подавляет ошибки самого reporter. Для отключения:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`setErrorReportRuntimeErrorReporter(undefined);
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Одновременно хранится один runtime reporter. Новая регистрация заменяет предыдущую и очищает внутреннее окно runtime-дедупликации.`}),`
+`,(0,c.jsx)(t.h2,{id:`нормализация-ошибки`,children:`Нормализация ошибки`}),`
+`,(0,c.jsx)(t.h3,{id:`createerrorinfoerror`,children:(0,c.jsx)(t.code,{children:`createErrorInfo(error)`})}),`
+`,(0,c.jsx)(t.p,{children:`Любое брошенное значение преобразуется к форме:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type ErrorReportErrorInfo = {
+	name: string;
+	message: string;
+	code?: string;
+	stackTrace?: string;
+	httpStatus?: number;
+};
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Для обычного `,(0,c.jsx)(t.code,{children:`Error`}),` сохраняются `,(0,c.jsx)(t.code,{children:`name`}),`, непустой `,(0,c.jsx)(t.code,{children:`message`}),` и полный `,(0,c.jsx)(t.code,{children:`stack`}),`.`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`createErrorInfo(new Error("Не удалось сохранить"));
+// { name: "Error", message: "Не удалось сохранить", stackTrace: "..." }
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Пустое сообщение, пустая строка и строка из пробелов заменяются на «Неизвестная ошибка».`}),`
+`,(0,c.jsxs)(t.p,{children:[`Для plain object читаются `,(0,c.jsx)(t.code,{children:`name`}),`, `,(0,c.jsx)(t.code,{children:`message`}),`, `,(0,c.jsx)(t.code,{children:`stack`}),` и первый из числовых `,(0,c.jsx)(t.code,{children:`status`}),`, `,(0,c.jsx)(t.code,{children:`statusCode`}),`, `,(0,c.jsx)(t.code,{children:`httpStatus`}),`. Другие поля объекта автоматически не включаются.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Также распознаётся serverFn transport-форма с `,(0,c.jsx)(t.code,{children:`error.appError`}),`: она превращается в `,(0,c.jsx)(t.code,{children:`name: "AppError"`}),`, сохраняет `,(0,c.jsx)(t.code,{children:`message`}),`, `,(0,c.jsx)(t.code,{children:`code`}),` и status.`]}),`
+`,(0,c.jsx)(t.h2,{id:`безопасные-диагностические-значения`,children:`Безопасные диагностические значения`}),`
+`,(0,c.jsx)(t.h3,{id:`creatediagnosticvaluevalue-depth`,children:(0,c.jsx)(t.code,{children:`createDiagnosticValue(value, depth?)`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Преобразует произвольное значение в JSON-совместимое дерево `,(0,c.jsx)(t.code,{children:`ErrorReportSafeValue`}),`.`]}),`
+`,(0,c.jsx)(t.p,{children:`Правила ограничения:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsx)(t.li,{children:`максимальная глубина — 4;`}),`
+`,(0,c.jsx)(t.li,{children:`максимум 20 элементов массива;`}),`
+`,(0,c.jsx)(t.li,{children:`максимум 40 ключей объекта;`}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`undefined`}),`, function, symbol и усечённая ветка получают специальные объекты `,(0,c.jsx)(t.code,{children:`{ type: ... }`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`bigint`}),` превращается в строку;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`Date`}),` — в ISO-строку.`]}),`
+`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`createDiagnosticValue({ retry: 2, handler: () => undefined });
+// { retry: 2, handler: { type: "function" } }
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Критически важно: функция `,(0,c.jsx)(t.strong,{children:`не скрывает значения по имени ключа`}),`. Поля `,(0,c.jsx)(t.code,{children:`token`}),`, `,(0,c.jsx)(t.code,{children:`password`}),`, `,(0,c.jsx)(t.code,{children:`authorization`}),`, email и другие секреты сохранятся, если их передать. Это ограничитель размера и типа, а не security sanitizer.`]}),`
+`,(0,c.jsx)(t.h3,{id:`sanitizedetaildetail`,children:(0,c.jsx)(t.code,{children:`sanitizeDetail(detail)`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Применяет `,(0,c.jsx)(t.code,{children:`createDiagnosticValue`}),` к первым 40 полям объекта. Для `,(0,c.jsx)(t.code,{children:`undefined`}),` или пустого объекта возвращает `,(0,c.jsx)(t.code,{children:`undefined`}),`.`]}),`
+`,(0,c.jsx)(t.p,{children:`Передавайте только заранее отобранные технические данные:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`sanitizeDetail({
+	operation: "save-order",
+	entitySet: "Orders",
+	rowCount: rows.length
+});
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Не передавайте request body, access token, cookie, персональные поля и полные backend responses.`}),`
+`,(0,c.jsx)(t.h3,{id:`createdatashapevalue-depth`,children:(0,c.jsx)(t.code,{children:`createDataShape(value, depth?)`})}),`
+`,(0,c.jsx)(t.p,{children:`Описывает структуру данных без leaf-значений:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`createDataShape({ rows: [{ id: "42", amount: 100 }] });
+// объект с keys/shape, массивом length и shape первых трёх элементов
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Для массива сохраняются длина и формы первых трёх элементов. Для объекта — первые 40 ключей и их формы. Именно эта функция используется для query data, чтобы не копировать содержимое кэша.`}),`
+`,(0,c.jsx)(t.h2,{id:`breadcrumbs`,children:`Breadcrumbs`}),`
+`,(0,c.jsx)(t.p,{children:`Breadcrumb — короткая запись о событии перед ошибкой.`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type ErrorReportBreadcrumb = {
+	utc: string;
+	type: "route" | "click" | "visibility" | "query-error" | "mutation-error" | "runtime-error";
+	routeId?: string;
+	appId?: string;
+	viewId?: string;
+	target?: string;
+	detail?: Record<string, ErrorReportSafeValue>;
+};
+`})}),`
+`,(0,c.jsx)(t.h3,{id:`ручное-добавление`,children:`Ручное добавление`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`addErrorReportBreadcrumb({
+	type: "route",
+	routeId: "/orders/$id",
+	detail: sanitizeDetail({ orderId: "42" })
+});
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Если `,(0,c.jsx)(t.code,{children:`utc`}),` отсутствует, используется текущий ISO timestamp. В памяти остаются последние 80 breadcrumbs.`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`getErrorReportBreadcrumbs();
+clearErrorReportBreadcrumbs();
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Возвращаемый массив является текущим внутренним массивом, а не глубокой копией. Считайте его readonly и не меняйте элементы вручную.`}),`
+`,(0,c.jsx)(t.h3,{id:`автоматические-browser-breadcrumbs`,children:`Автоматические browser breadcrumbs`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const uninstallBreadcrumbs = installErrorReportBrowserBreadcrumbs();
+
+// При демонтаже client shell:
+uninstallBreadcrumbs();
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Установщик слушает:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsx)(t.li,{children:`click в capture phase;`}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`document.visibilitychange`}),`.`]}),`
+`]}),`
+`,(0,c.jsx)(t.p,{children:`Для click сохраняются координаты/модификаторы и ограниченное описание meaningful target: tag, стабильные атрибуты, короткий текст и цепочка родителей. Глубина DOM-цепочки ограничена 20, текст — 80 символами, атрибут — 120.`}),`
+`,(0,c.jsxs)(t.p,{children:[`Код не читает `,(0,c.jsx)(t.code,{children:`input.value`}),` и не копирует CSS class list, но текст/ARIA/title/data-атрибуты тоже могут содержать чувствительные данные. Не помещайте секреты в DOM-атрибуты и UI-текст.`]}),`
+`,(0,c.jsx)(t.p,{children:`На сервере установщик возвращает пустую cleanup-функцию.`}),`
+`,(0,c.jsx)(t.h2,{id:`диагностика-tanstack-query`,children:`Диагностика TanStack Query`}),`
+`,(0,c.jsx)(t.h3,{id:`collectquerydiagnosticsquery`,children:(0,c.jsx)(t.code,{children:`collectQueryDiagnostics(query)`})}),`
+`,(0,c.jsx)(t.p,{children:`Собирает:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`queryHash`}),` и диагностическое представление `,(0,c.jsx)(t.code,{children:`queryKey`}),`;`]}),`
+`,(0,c.jsx)(t.li,{children:`status/fetchStatus;`}),`
+`,(0,c.jsx)(t.li,{children:`timestamps обновления data/error;`}),`
+`,(0,c.jsx)(t.li,{children:`failure count, invalidation и observer count;`}),`
+`,(0,c.jsx)(t.li,{children:`meta;`}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`dataShape`}),` вместо data;`]}),`
+`,(0,c.jsx)(t.li,{children:`нормализованную query error.`}),`
+`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Значения `,(0,c.jsx)(t.code,{children:`queryKey`}),` и `,(0,c.jsx)(t.code,{children:`meta`}),` сохраняются. Если туда попал token или персональный идентификатор, он попадёт в отчёт. Проектируйте query keys как диагностически безопасный контракт.`]}),`
+`,(0,c.jsx)(t.h3,{id:`collectmutationdiagnosticsmutation`,children:(0,c.jsx)(t.code,{children:`collectMutationDiagnostics(mutation)`})}),`
+`,(0,c.jsx)(t.p,{children:`Собирает mutation key, status, failure count, submitted timestamp, meta и error. Mutation variables/data не копируются.`}),`
+`,(0,c.jsx)(t.h3,{id:`collectqueryclientdiagnosticsqueryclient`,children:(0,c.jsx)(t.code,{children:`collectQueryClientDiagnostics(queryClient)`})}),`
+`,(0,c.jsx)(t.p,{children:`Возвращает последние 40 query и последние 40 mutations из соответствующих cache. Это синхронный snapshot текущего QueryClient.`}),`
+`,(0,c.jsx)(t.h3,{id:`collectpersistedquerydiagnostics`,children:(0,c.jsx)(t.code,{children:`collectPersistedQueryDiagnostics()`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Асинхронно читает IndexedDB persistence из `,(0,c.jsx)(t.code,{children:`/query-client`}),` и возвращает максимум 40 записей.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Сохраняются storage key, buster, query hash/key, statuses, timestamps, failure count и error. `,(0,c.jsx)(t.code,{children:`state.data`}),` намеренно исключён полностью.`]}),`
+`,(0,c.jsx)(t.p,{children:`Если IndexedDB/persistence недоступны или чтение бросает ошибку, возвращается пустой массив — сбор отчёта не падает.`}),`
+`,(0,c.jsx)(t.h2,{id:`capture-query-ошибки`,children:`Capture query-ошибки`}),`
+`,(0,c.jsx)(t.h3,{id:`capturequeryerrorreporterror-query-queryclient-context`,children:(0,c.jsx)(t.code,{children:`captureQueryErrorReport(error, query, queryClient, context?)`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const draft = await captureQueryErrorReport(error, query, queryClient, {
+	source: "orders-list",
+	detail: { routeId: "/orders" }
+});
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Функция:`}),`
+`,(0,c.jsxs)(t.ol,{children:[`
+`,(0,c.jsxs)(t.li,{children:[`подавляет отложенный transport-report для того же экземпляра `,(0,c.jsx)(t.code,{children:`Error`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`добавляет breadcrumb `,(0,c.jsx)(t.code,{children:`query-error`}),`;`]}),`
+`,(0,c.jsx)(t.li,{children:`параллельно читает persisted diagnostics и QueryClient snapshot;`}),`
+`,(0,c.jsx)(t.li,{children:`собирает подробности конкретной query;`}),`
+`,(0,c.jsxs)(t.li,{children:[`создаёт draft категории `,(0,c.jsx)(t.code,{children:`query`}),`.`]}),`
+`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Возвращает `,(0,c.jsx)(t.code,{children:`ErrorReportDraft | undefined`}),`. В development/SSR будет `,(0,c.jsx)(t.code,{children:`undefined`}),`.`]}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`context.errorInfo`}),` позволяет передать уже нормализованную ошибку, `,(0,c.jsx)(t.code,{children:`context.queryKey`}),` — переопределить breadcrumb key, `,(0,c.jsx)(t.code,{children:`context.detail`}),` — добавить контролируемый context.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Параметр `,(0,c.jsx)(t.code,{children:`query`}),` — реальный объект TanStack Query cache, а не `,(0,c.jsx)(t.code,{children:`UseQueryResult`}),` и не query options.`]}),`
+`,(0,c.jsx)(t.h2,{id:`capture-mutation-ошибки`,children:`Capture mutation-ошибки`}),`
+`,(0,c.jsx)(t.h3,{id:`capturemutationerrorreporterror-mutation-queryclient-context`,children:(0,c.jsx)(t.code,{children:`captureMutationErrorReport(error, mutation, queryClient, context?)`})}),`
+`,(0,c.jsx)(t.p,{children:`Работает аналогично query capture: подавляет дублирующий transport-report, добавляет mutation breadcrumb и собирает QueryClient/persistence snapshot.`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const draft = await captureMutationErrorReport(error, mutation, queryClient, { source: "save-order", detail: { form: "order-edit" } });
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Текущая реализация включает `,(0,c.jsx)(t.code,{children:`detail`}),` в breadcrumb, но не переносит его в `,(0,c.jsx)(t.code,{children:`payload.context`}),` mutation draft. Если этот контекст критичен для доставки, добавьте безопасные данные в app-level envelope либо используйте явную согласованную модель до capture.`]}),`
+`,(0,c.jsx)(t.h2,{id:`capture-runtimereact-ошибки`,children:`Capture runtime/React-ошибки`}),`
+`,(0,c.jsx)(t.h3,{id:`captureruntimeerrorreporterror-context-queryclient`,children:(0,c.jsx)(t.code,{children:`captureRuntimeErrorReport(error, context?, queryClient?)`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const draft = await captureRuntimeErrorReport(
+	error,
+	{
+		category: "react",
+		source: "error-boundary",
+		componentStack: info.componentStack,
+		detail: { routeId }
+	},
+	queryClient
+);
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Без `,(0,c.jsx)(t.code,{children:`queryClient`}),` отчёт создаётся без query/persisted diagnostics. Это полезно для низкоуровневого runtime кода. С QueryClient добавляется общий snapshot.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`По умолчанию category/source — `,(0,c.jsx)(t.code,{children:`runtime`}),`. `,(0,c.jsx)(t.code,{children:`componentStack`}),` записывается в секцию `,(0,c.jsx)(t.code,{children:`react`}),`.`]}),`
+`,(0,c.jsx)(t.p,{children:`Одинаковые runtime/React capture в браузере объединяются примерно на 60 секунд по fingerprint ошибки, source, path, component stack и detail. Параллельные вызовы получают одну Promise/draft. Это защищает от лавины одинаковых отчётов. После отклонения capture внутренняя запись удаляется.`}),`
+`,(0,c.jsx)(t.h2,{id:`draft-и-payload`,children:`Draft и payload`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type ErrorReportStatus = "pending" | "sending" | "sent" | "failed";
+
+type ErrorReportDraft = {
+	reportId: string;
+	sessionId: string;
+	createdUtc: string;
+	category: ErrorReportCategory;
+	status: ErrorReportStatus;
+	sentUtc?: string;
+	failedReason?: string;
+	payload: ErrorReportPayload;
+};
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`reportId`}),` — UUID отдельного отчёта. `,(0,c.jsx)(t.code,{children:`sessionId`}),` стабилен в текущем `,(0,c.jsx)(t.code,{children:`sessionStorage`}),`. `,(0,c.jsx)(t.code,{children:`createdUtc`}),` формируется как OData datetime UTC.`]}),`
+`,(0,c.jsx)(t.p,{children:`Payload содержит category/source/error, build environment, client, location, viewport, breadcrumbs и optional секции query/mutation/react/context.`}),`
+`,(0,c.jsx)(t.h3,{id:`хранение`,children:`Хранение`}),`
+`,(0,c.jsxs)(t.p,{children:[`Drafts сохраняются под ключом `,(0,c.jsx)(t.code,{children:"${__APP_ID__}.errorReport.drafts.v1"}),`. В одной вкладке остаются последние 10 элементов. Старые удаляются с начала массива.`]}),`
+`,(0,c.jsx)(t.p,{children:`Storage errors и некорректный JSON подавляются. При переполнении sessionStorage текущее in-memory состояние обновится, но запись на диск может не сохраниться.`}),`
+`,(0,c.jsx)(t.p,{children:`Модуль загружает drafts при первом импорте. Это модульное состояние, общее для всех consumers одного bundle.`}),`
+`,(0,c.jsxs)(t.h2,{id:`низкоуровневый-captureerrorreportdraftargs`,children:[`Низкоуровневый `,(0,c.jsx)(t.code,{children:`captureErrorReportDraft(args)`})]}),`
+`,(0,c.jsx)(t.p,{children:`Используйте, когда все diagnostic sections уже подготовлены вручную:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const draft = captureErrorReportDraft({
+	category: "runtime",
+	source: "custom-engine",
+	error: createErrorInfo(error),
+	context: sanitizeDetail({ stage: "compile" })
+});
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Функция добавит report/session IDs, environment, client/location/viewport и текущие breadcrumbs. Она синхронная и не собирает QueryClient автоматически.`}),`
+`,(0,c.jsx)(t.h2,{id:`чтение-и-обновление-drafts`,children:`Чтение и обновление drafts`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const drafts = getErrorReportDrafts();
+const draft = getErrorReportDraft(reportId);
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Возвращаются ссылки из внутреннего массива. Считайте их readonly; для lifecycle используйте `,(0,c.jsx)(t.code,{children:`updateErrorReportDraft`}),`.`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`updateErrorReportDraft(reportId, { status: "sending" });
+
+try {
+	await api.sendErrorReport(draft.payload);
+	updateErrorReportDraft(reportId, {
+		status: "sent",
+		sentUtc: new Date().toISOString(),
+		failedReason: undefined
+	});
+} catch (error) {
+	updateErrorReportDraft(reportId, {
+		status: "failed",
+		failedReason: createErrorInfo(error).message
+	});
+}
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Для неизвестного ID update возвращает `,(0,c.jsx)(t.code,{children:`undefined`}),`. Обновление поверхностное и принимает `,(0,c.jsx)(t.code,{children:`Partial<ErrorReportDraft>`}),`: библиотека не проверяет разрешённые переходы статусов. App delivery обязан не менять `,(0,c.jsx)(t.code,{children:`reportId`}),`, payload и другие identity-поля без необходимости.`]}),`
+`,(0,c.jsx)(t.h2,{id:`environment-api`,children:`Environment API`}),`
+`,(0,c.jsx)(t.h3,{id:`geterrorreportenvironment`,children:(0,c.jsx)(t.code,{children:`getErrorReportEnvironment()`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Возвращает mode из `,(0,c.jsx)(t.code,{children:`__DEV__`}),` и build ID.`]}),`
+`,(0,c.jsx)(t.h3,{id:`geterrorreportclientenvironment`,children:(0,c.jsx)(t.code,{children:`getErrorReportClientEnvironment()`})}),`
+`,(0,c.jsxs)(t.p,{children:[`В браузере возвращает user agent, language и timezone. На сервере — `,(0,c.jsx)(t.code,{children:`undefined`}),`.`]}),`
+`,(0,c.jsx)(t.p,{children:`Эти поля могут считаться персональными/идентифицирующими данными в политике организации. Согласуйте срок хранения и доступ к отчётам.`}),`
+`,(0,c.jsx)(t.h2,{id:`transport-reporter`,children:`Transport reporter`}),`
+`,(0,c.jsx)(t.p,{children:`Transport-слой может сообщить об ошибке parsing/fetch, не зная о QueryClient и UI.`}),`
+`,(0,c.jsx)(t.h3,{id:`регистрация`,children:`Регистрация`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`setErrorReportTransportErrorReporter(async (error, context) => {
+	const draft = await captureRuntimeErrorReport(
+		error,
+		{
+			source: context.source,
+			detail: context
+		},
+		queryClient
+	);
+
+	if (draft) {
+		await deliverErrorReport(draft);
+	}
+});
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Для отключения передайте `,(0,c.jsx)(t.code,{children:`undefined`}),`. Регистрация очищает недавние transport keys.`]}),`
+`,(0,c.jsx)(t.h3,{id:`reporttransporterrorerror-context`,children:(0,c.jsx)(t.code,{children:`reportTransportError(error, context)`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Context имеет source `,(0,c.jsx)(t.code,{children:`fetch.parseResponse`}),` или `,(0,c.jsx)(t.code,{children:`fetch.buildHttpError`}),` и может содержать URL, method, SAP client, status/content type, redirect/response type и безопасное summary HTML-response.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Вызов планирует reporter через 250 мс. Задержка позволяет TanStack Query перехватить тот же `,(0,c.jsx)(t.code,{children:`Error`}),` и создать более полезный query/mutation report.`]}),`
+`,(0,c.jsx)(t.h3,{id:`подавление-дубля`,children:`Подавление дубля`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`isTransportErrorReportScheduled(error);
+suppressTransportErrorReport(error);
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Capture query/mutation вызывает suppression автоматически. Проверка работает только для того же экземпляра `,(0,c.jsx)(t.code,{children:`Error`}),`, потому что внутри используются WeakSet.`]}),`
+`,(0,c.jsx)(t.p,{children:`Transport reports дополнительно дедуплицируются на 60 секунд по source, method, status и URL. Хранится ограниченное число недавних ключей.`}),`
+`,(0,c.jsx)(t.p,{children:`Если reporter отсутствует, подавлен, недавно уже сработал или сам бросил ошибку, основной transport-сценарий не ломается.`}),`
+`,(0,c.jsx)(t.h2,{id:`рекомендуемая-app-level-интеграция`,children:`Рекомендуемая app-level интеграция`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`export function installErrorReporting(queryClient: QueryClient) {
+	const uninstallBreadcrumbs = installErrorReportBrowserBreadcrumbs();
+
+	setErrorReportRuntimeErrorReporter(async (error, context) => {
+		const draft = await captureRuntimeErrorReport(error, context, queryClient);
+		if (draft) await deliverDraft(draft);
+	});
+
+	setErrorReportTransportErrorReporter(async (error, context) => {
+		const draft = await captureRuntimeErrorReport(
+			error,
+			{ source: context.source, detail: pickSafeTransportFields(context) },
+			queryClient
+		);
+		if (draft) await deliverDraft(draft);
+	});
+
+	return () => {
+		uninstallBreadcrumbs();
+		setErrorReportRuntimeErrorReporter(undefined);
+		setErrorReportTransportErrorReporter(undefined);
+	};
+}
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Создавайте lifecycle один раз в client shell. Функция `,(0,c.jsx)(t.code,{children:`pickSafeTransportFields`}),` — ответственность приложения и должна явно разрешать поля, а не копировать произвольный объект.`]}),`
+`,(0,c.jsx)(t.h2,{id:`безопасность-и-приватность`,children:`Безопасность и приватность`}),`
+`,(0,c.jsx)(t.p,{children:`Перед включением production delivery обязательно определите data policy.`}),`
+`,(0,c.jsx)(t.h3,{id:`что-намеренно-не-сохраняется`,children:`Что намеренно не сохраняется`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[`полное `,(0,c.jsx)(t.code,{children:`query.state.data`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`persisted `,(0,c.jsx)(t.code,{children:`state.data`}),`;`]}),`
+`,(0,c.jsx)(t.li,{children:`mutation variables;`}),`
+`,(0,c.jsx)(t.li,{children:`значения input при автоматическом click breadcrumb;`}),`
+`,(0,c.jsx)(t.li,{children:`тела transport-запросов.`}),`
+`]}),`
+`,(0,c.jsx)(t.h3,{id:`что-всё-ещё-может-содержать-данные`,children:`Что всё ещё может содержать данные`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsx)(t.li,{children:`queryKey и mutationKey;`}),`
+`,(0,c.jsx)(t.li,{children:`query/mutation meta;`}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`context.detail`}),`;`]}),`
+`,(0,c.jsx)(t.li,{children:`URL и pathname;`}),`
+`,(0,c.jsx)(t.li,{children:`error message/stack;`}),`
+`,(0,c.jsx)(t.li,{children:`UI text, ARIA/title/data attributes breadcrumbs;`}),`
+`,(0,c.jsx)(t.li,{children:`user agent, language, timezone;`}),`
+`,(0,c.jsx)(t.li,{children:`имена persisted storage keys.`}),`
+`]}),`
+`,(0,c.jsx)(t.p,{children:`Поэтому:`}),`
+`,(0,c.jsxs)(t.ol,{children:[`
+`,(0,c.jsx)(t.li,{children:`не помещайте секреты в query keys/meta;`}),`
+`,(0,c.jsx)(t.li,{children:`собирайте detail по allow-list;`}),`
+`,(0,c.jsx)(t.li,{children:`очищайте URL от token/query secrets до передачи в custom context;`}),`
+`,(0,c.jsx)(t.li,{children:`защищайте endpoint доставки;`}),`
+`,(0,c.jsx)(t.li,{children:`задайте срок хранения и права доступа;`}),`
+`,(0,c.jsx)(t.li,{children:`при необходимости запрашивайте согласие пользователя;`}),`
+`,(0,c.jsx)(t.li,{children:`не показывайте необработанный stack trace всем пользователям.`}),`
+`]}),`
+`,(0,c.jsx)(t.h2,{id:`частые-ошибки`,children:`Частые ошибки`}),`
+`,(0,c.jsx)(t.h3,{id:`ожидать-автоматическую-отправку`,children:`Ожидать автоматическую отправку`}),`
+`,(0,c.jsx)(t.p,{children:`Capture только создаёт draft. Delivery нужно явно подключить.`}),`
+`,(0,c.jsxs)(t.h3,{id:`использовать-creatediagnosticvalue-как-redactor`,children:[`Использовать `,(0,c.jsx)(t.code,{children:`createDiagnosticValue`}),` как redactor`]}),`
+`,(0,c.jsx)(t.p,{children:`Он ограничивает размер, но сохраняет значения независимо от имени поля.`}),`
+`,(0,c.jsx)(t.h3,{id:`вызывать-production-capture-в-development-и-ждать-draft`,children:`Вызывать production capture в development и ждать draft`}),`
+`,(0,c.jsxs)(t.p,{children:[`По контракту вернётся `,(0,c.jsx)(t.code,{children:`undefined`}),`.`]}),`
+`,(0,c.jsx)(t.h3,{id:`не-очищать-глобальные-reporters`,children:`Не очищать глобальные reporters`}),`
+`,(0,c.jsx)(t.p,{children:`При hot reload, тестах или размонтировании shell снимайте bindings, чтобы старый QueryClient/delivery не оставался в closure.`}),`
+`,(0,c.jsxs)(t.h3,{id:`мутировать-результат-geterrorreportdrafts`,children:[`Мутировать результат `,(0,c.jsx)(t.code,{children:`getErrorReportDrafts()`})]}),`
+`,(0,c.jsxs)(t.p,{children:[`Используйте `,(0,c.jsx)(t.code,{children:`updateErrorReportDraft`}),`; прямое изменение обходит сохранение в sessionStorage.`]}),`
+`,(0,c.jsxs)(t.h3,{id:`передавать-usequeryresult-вместо-cache-query`,children:[`Передавать `,(0,c.jsx)(t.code,{children:`UseQueryResult`}),` вместо cache Query`]}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`captureQueryErrorReport`}),` нужен объект Query, обычно доступный внутри QueryCache callbacks/instrumentation.`]}),`
+`,(0,c.jsx)(t.h3,{id:`создать-цикл-отчётов`,children:`Создать цикл отчётов`}),`
+`,(0,c.jsx)(t.p,{children:`Ошибка endpoint доставки не должна снова проходить через тот же автоматический transport reporter. Пометьте/исключите delivery transport или используйте отдельный канал.`}),`
+`,(0,c.jsx)(t.h2,{id:`краткая-карта-api`,children:`Краткая карта API`}),`
+`,(0,c.jsxs)(t.table,{children:[(0,c.jsx)(t.thead,{children:(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.th,{children:`Группа`}),(0,c.jsx)(t.th,{children:`Экспорты`})]})}),(0,c.jsxs)(t.tbody,{children:[(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Capture`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`captureQueryErrorReport`}),`, `,(0,c.jsx)(t.code,{children:`captureMutationErrorReport`}),`, `,(0,c.jsx)(t.code,{children:`captureRuntimeErrorReport`}),`, `,(0,c.jsx)(t.code,{children:`captureErrorReportDraft`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Errors`}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`createErrorInfo`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Safe values`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`createDiagnosticValue`}),`, `,(0,c.jsx)(t.code,{children:`createDataShape`}),`, `,(0,c.jsx)(t.code,{children:`sanitizeDetail`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Breadcrumbs`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`addErrorReportBreadcrumb`}),`, `,(0,c.jsx)(t.code,{children:`getErrorReportBreadcrumbs`}),`, `,(0,c.jsx)(t.code,{children:`clearErrorReportBreadcrumbs`}),`, `,(0,c.jsx)(t.code,{children:`installErrorReportBrowserBreadcrumbs`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Diagnostics`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`collectQueryDiagnostics`}),`, `,(0,c.jsx)(t.code,{children:`collectMutationDiagnostics`}),`, `,(0,c.jsx)(t.code,{children:`collectQueryClientDiagnostics`}),`, `,(0,c.jsx)(t.code,{children:`collectPersistedQueryDiagnostics`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Drafts`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`getErrorReportDraft`}),`, `,(0,c.jsx)(t.code,{children:`getErrorReportDrafts`}),`, `,(0,c.jsx)(t.code,{children:`updateErrorReportDraft`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Environment`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`isErrorReportingEnabled`}),`, `,(0,c.jsx)(t.code,{children:`getErrorReportEnvironment`}),`, `,(0,c.jsx)(t.code,{children:`getErrorReportClientEnvironment`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Runtime facade`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`setErrorReportRuntimeErrorReporter`}),`, `,(0,c.jsx)(t.code,{children:`reportRuntimeError`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Transport facade`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`setErrorReportTransportErrorReporter`}),`, `,(0,c.jsx)(t.code,{children:`reportTransportError`}),`, `,(0,c.jsx)(t.code,{children:`isTransportErrorReportScheduled`}),`, `,(0,c.jsx)(t.code,{children:`suppressTransportErrorReport`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Contracts`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`ErrorReportDraft`}),`, `,(0,c.jsx)(t.code,{children:`ErrorReportPayload`}),`, contexts, diagnostics и transport types`]})]})]})]})]})}function s(e={}){let{wrapper:t}={...n(),...e.components};return t?(0,c.jsx)(t,{...e,children:(0,c.jsx)(o,{...e})}):o(e)}var c;function l(){return(l=e((()=>{c=t(),r(),a()})))()}l();export{s as default};

package/storybook-static/assets/{README-BdPlV5nA.js → README-llxZAtCj.js}

@@ -1,4 +1,4 @@
-import{n as e}from"./rolldown-runtime-DkW27tQK.js";import{n as t}from"./iframe-Sr0umHM6.js";import{i as n,r}from"./react-Bl2r1tuC.js";import{l as i,m as a}from"./blocks-DndFRxxW.js";function o(e){let t={a:`a`,code:`code`,h1:`h1`,h2:`h2`,h3:`h3`,li:`li`,ol:`ol`,p:`p`,pre:`pre`,table:`table`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,ul:`ul`,...n(),...e.components};return(0,c.jsxs)(c.Fragment,{children:[(0,c.jsx)(i,{title:`Foundation Lib/API/Formatters/Обзор`}),`
+import{n as e}from"./rolldown-runtime-DkW27tQK.js";import{n as t}from"./iframe-o7sH2IXC.js";import{i as n,r}from"./react-Bl2r1tuC.js";import{l as i,m as a}from"./blocks-BY40djCc.js";function o(e){let t={a:`a`,code:`code`,h1:`h1`,h2:`h2`,h3:`h3`,li:`li`,ol:`ol`,p:`p`,pre:`pre`,table:`table`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,ul:`ul`,...n(),...e.components};return(0,c.jsxs)(c.Fragment,{children:[(0,c.jsx)(i,{title:`Foundation Lib/API/Formatters/Обзор`}),`
 `,(0,c.jsx)(t.h1,{id:`ryuzaki13react-foundation-libformatters`,children:(0,c.jsx)(t.code,{children:`@ryuzaki13/react-foundation-lib/formatters`})}),`
 `,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`formatters`}),` — большой модуль подготовки значений для интерфейса и transport-контрактов. Он работает с датами, числами, строками, boolean/ABAP-флагами, ФИО, российскими телефонами, ведущими нулями и семантическими состояниями. Для таблиц модуль также предоставляет конфигурируемый formatter pipeline и row-based формулы.`]}),`
 `,(0,c.jsx)(t.p,{children:`Документация разделена по предметным областям, чтобы разработчику не приходилось читать один огромный файл. Этот README объясняет общие правила, помогает выбрать API и подробно описывает небольшие helpers верхнего уровня.`}),`

package/storybook-static/assets/README-wFnEIGl4.js

@@ -0,0 +1,95 @@
+import{n as e}from"./rolldown-runtime-DkW27tQK.js";import{n as t}from"./iframe-o7sH2IXC.js";import{i as n,r}from"./react-Bl2r1tuC.js";import{l as i,m as a}from"./blocks-BY40djCc.js";function o(e){let t={code:`code`,h1:`h1`,h2:`h2`,li:`li`,p:`p`,pre:`pre`,table:`table`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,ul:`ul`,...n(),...e.components};return(0,c.jsxs)(c.Fragment,{children:[(0,c.jsx)(i,{title:`Foundation Lib/Data/Presets`}),`
+`,(0,c.jsxs)(t.h1,{id:`общие-preset-helpers-через-ryuzaki13react-foundation-libpresets`,children:[`Общие preset helpers через `,(0,c.jsx)(t.code,{children:`@ryuzaki13/react-foundation-lib/presets`})]}),`
+`,(0,c.jsx)(t.p,{children:`Модуль проверяет восстановленные preset ids, сопоставляет их с option objects и ищет одну option по id.`}),`
+`,(0,c.jsx)(t.h2,{id:`установка-и-импорт`,children:`Установка и импорт`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import { getPresetOption, normalizePresetIds, resolvePresetOptionsByIds } from "@ryuzaki13/react-foundation-lib/presets";
+
+import type { PresetOption } from "@ryuzaki13/react-foundation-lib/presets";
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Модуль не зависит от React/browser APIs.`}),`
+`,(0,c.jsx)(t.h2,{id:`базовый-контракт`,children:`Базовый контракт`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type PresetOption<TId extends string = string> = {
+	id: TId;
+	label: string;
+};
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Ваш тип может добавлять поля:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type ReportPreset = PresetOption<"daily" | "monthly"> & {
+	icon: string;
+};
+`})}),`
+`,(0,c.jsx)(t.h2,{id:`normalizepresetids`,children:(0,c.jsx)(t.code,{children:`normalizePresetIds`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Функция предназначена для явной boundary восстановления сохранённого `,(0,c.jsx)(t.code,{children:`unknown`}),`:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type PresetId = "first" | "second" | "third";
+
+function isPresetId(value: unknown): value is PresetId {
+	return value === "first" || value === "second" || value === "third";
+}
+
+normalizePresetIds(["second", "unknown", "second", "first"], isPresetId);
+// ["second", "first"].
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Алгоритм:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[`если `,(0,c.jsx)(t.code,{children:`value`}),` не массив — возвращается копия `,(0,c.jsx)(t.code,{children:`fallbackIds`}),`;`]}),`
+`,(0,c.jsx)(t.li,{children:`если это массив — fallback не используется, даже для пустого массива;`}),`
+`,(0,c.jsx)(t.li,{children:`элементы проверяются переданным type guard;`}),`
+`,(0,c.jsx)(t.li,{children:`invalid ids пропускаются;`}),`
+`,(0,c.jsx)(t.li,{children:`дубликаты удаляются;`}),`
+`,(0,c.jsx)(t.li,{children:`сохраняется порядок первого допустимого вхождения.`}),`
+`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`normalizePresetIds(undefined, isPresetId, ["third"]); // ["third"].
+normalizePresetIds([], isPresetId, ["third"]); // [].
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Это normalizer сохранённого payload. Не вызывайте его внутри обычного input/store setter, если пользовательский draft должен храниться буквально.`}),`
+`,(0,c.jsx)(t.h2,{id:`resolvepresetoptionsbyids`,children:(0,c.jsx)(t.code,{children:`resolvePresetOptionsByIds`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const options = [
+	{ id: "first", label: "Первый" },
+	{ id: "second", label: "Второй" },
+	{ id: "third", label: "Третий" }
+] as const;
+
+const selected = resolvePresetOptionsByIds(["third", "first", "third", "missing"], options);
+// objects third, first.
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Правила:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[`порядок берётся из `,(0,c.jsx)(t.code,{children:`presetIds`}),`, а не из `,(0,c.jsx)(t.code,{children:`options`}),`;`]}),`
+`,(0,c.jsx)(t.li,{children:`повторные ids добавляются один раз;`}),`
+`,(0,c.jsxs)(t.li,{children:[`отсутствующие в `,(0,c.jsx)(t.code,{children:`options`}),` ids пропускаются;`]}),`
+`,(0,c.jsx)(t.li,{children:`возвращается новый массив;`}),`
+`,(0,c.jsx)(t.li,{children:`сами option objects не клонируются;`}),`
+`,(0,c.jsxs)(t.li,{children:[`если в `,(0,c.jsx)(t.code,{children:`options`}),` повторяется id, `,(0,c.jsx)(t.code,{children:`Map`}),` оставляет последнюю option с этим id.`]}),`
+`]}),`
+`,(0,c.jsx)(t.h2,{id:`getpresetoption`,children:(0,c.jsx)(t.code,{children:`getPresetOption`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`getPresetOption("second", options);
+// { id: "second", label: "Второй" }.
+
+getPresetOption("missing", options); // null.
+getPresetOption(undefined, options); // null.
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Функция использует первое совпадение `,(0,c.jsx)(t.code,{children:`options.find`}),`. Пустой id `,(0,c.jsx)(t.code,{children:`""`}),` считается отсутствующим и возвращает `,(0,c.jsx)(t.code,{children:`null`}),`.`]}),`
+`,(0,c.jsx)(t.h2,{id:`saverestore-recipe`,children:`Save/restore recipe`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`function restorePresetIds(value: unknown): PresetId[] {
+	return normalizePresetIds(value, isPresetId, ["daily"]);
+}
+
+function buildPresetView(ids: readonly PresetId[]) {
+	return resolvePresetOptionsByIds(ids, PRESET_OPTIONS);
+}
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Разделяйте:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-text`,children:`unknown persisted payload ── normalizePresetIds ──► canonical ids
+literal UI draft           ── clone only          ──► literal copy
+canonical ids              ── resolve...          ──► option objects for UI
+`})}),`
+`,(0,c.jsx)(t.h2,{id:`api-и-ошибки`,children:`API и ошибки`}),`
+`,(0,c.jsxs)(t.table,{children:[(0,c.jsx)(t.thead,{children:(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.th,{children:`Export`}),(0,c.jsx)(t.th,{children:`Результат`})]})}),(0,c.jsxs)(t.tbody,{children:[(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`PresetOption`})}),(0,c.jsxs)(t.td,{children:[`Минимальный `,(0,c.jsx)(t.code,{children:`{ id, label }`}),` contract`]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`normalizePresetIds`})}),(0,c.jsx)(t.td,{children:`Проверенные уникальные ids`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`resolvePresetOptionsByIds`})}),(0,c.jsx)(t.td,{children:`Options в порядке ids`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`getPresetOption`})}),(0,c.jsxs)(t.td,{children:[`Option или `,(0,c.jsx)(t.code,{children:`null`})]})]})]})]}),`
+`,(0,c.jsx)(t.p,{children:`Типичные ошибки:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsx)(t.li,{children:`Ожидать fallback для пустого массива.`}),`
+`,(0,c.jsx)(t.li,{children:`Считать result options глубокими копиями.`}),`
+`,(0,c.jsx)(t.li,{children:`Использовать normalizer во время пользовательского ввода.`}),`
+`,(0,c.jsx)(t.li,{children:`Передавать type guard, который делает unsafe cast вместо runtime-проверки.`}),`
+`,(0,c.jsx)(t.li,{children:`Ожидать, что неизвестный id будет создан автоматически.`}),`
+`]})]})}function s(e={}){let{wrapper:t}={...n(),...e.components};return t?(0,c.jsx)(t,{...e,children:(0,c.jsx)(o,{...e})}):o(e)}var c;function l(){return(l=e((()=>{c=t(),r(),a()})))()}l();export{s as default};

package/storybook-static/assets/{README-Dx3cpFMr.js → README-webB1yH0.js}

@@ -1,4 +1,4 @@
-import{n as e}from"./rolldown-runtime-DkW27tQK.js";import{n as t}from"./iframe-Sr0umHM6.js";import{i as n,r}from"./react-Bl2r1tuC.js";import{l as i,m as a}from"./blocks-DndFRxxW.js";function o(e){let t={a:`a`,code:`code`,h1:`h1`,h2:`h2`,h3:`h3`,li:`li`,p:`p`,pre:`pre`,table:`table`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,ul:`ul`,...n(),...e.components};return(0,c.jsxs)(c.Fragment,{children:[(0,c.jsx)(i,{title:`Foundation Lib/API/Formatters/Date`}),`
+import{n as e}from"./rolldown-runtime-DkW27tQK.js";import{n as t}from"./iframe-o7sH2IXC.js";import{i as n,r}from"./react-Bl2r1tuC.js";import{l as i,m as a}from"./blocks-BY40djCc.js";function o(e){let t={a:`a`,code:`code`,h1:`h1`,h2:`h2`,h3:`h3`,li:`li`,p:`p`,pre:`pre`,table:`table`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,ul:`ul`,...n(),...e.components};return(0,c.jsxs)(c.Fragment,{children:[(0,c.jsx)(i,{title:`Foundation Lib/API/Formatters/Date`}),`
 `,(0,c.jsx)(t.h1,{id:`даты-время-и-календарные-диапазоны`,children:`Даты, время и календарные диапазоны`}),`
 `,(0,c.jsx)(t.p,{children:`Модуль решает четыре связанные задачи:`}),`
 `,(0,c.jsxs)(t.ul,{children:[`