@ryuzaki13/react-foundation-ui 1.8.11 → 1.8.13

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

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

@@ -0,0 +1,324 @@
+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`,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 API/Errors/Error Report Delivery`}),`
+`,(0,c.jsxs)(t.h1,{id:`доставка-error-reports-через-ryuzaki13react-foundation-apierror-report`,children:[`Доставка error reports через `,(0,c.jsx)(t.code,{children:`@ryuzaki13/react-foundation-api/error-report`})]}),`
+`,(0,c.jsxs)(t.p,{children:[`Модуль превращает сохранённый черновик отчёта из `,(0,c.jsx)(t.code,{children:`foundation-lib`}),` в delivery body, вызывает adapter приложения и обновляет статус черновика.`]}),`
+`,(0,c.jsx)(t.h2,{id:`граница-ответственности`,children:`Граница ответственности`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-text`,children:`foundation-lib/error-report        foundation-api/error-report       host backend adapter
+collect + sanitize + draft store ──► lifecycle + delivery body ─────► HTTP/OData/serverFn
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Модуль не собирает browser diagnostics, не выбирает endpoint и не отправляет запрос самостоятельно. Transport явно передаёт приложение через `,(0,c.jsx)(t.code,{children:`adapter`}),`.`]}),`
+`,(0,c.jsx)(t.h2,{id:`установка-и-импорт`,children:`Установка и импорт`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import {
+	createErrorReportDeliveryBody,
+	sendErrorReport
+} from "@ryuzaki13/react-foundation-api/error-report";
+
+import type {
+	ErrorReportDeliveryAdapter,
+	ErrorReportDeliveryBody,
+	ErrorReportDeliveryContext,
+	SendErrorReportOptions
+} from "@ryuzaki13/react-foundation-api/error-report";
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Нужны `,(0,c.jsx)(t.code,{children:`@ryuzaki13/react-foundation-lib`}),` и `,(0,c.jsx)(t.code,{children:`@tanstack/react-query`}),`.`]}),`
+`,(0,c.jsx)(t.h2,{id:`полный-сценарий`,children:`Полный сценарий`}),`
+`,(0,c.jsxs)(t.p,{children:[`Сначала другой слой создаёт и сохраняет draft средствами `,(0,c.jsx)(t.code,{children:`@ryuzaki13/react-foundation-lib/error-report`}),`. Затем API-слой получает только его `,(0,c.jsx)(t.code,{children:`reportId`}),`:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import { httpFetchPayload } from "@ryuzaki13/react-foundation-api/http";
+import { sendErrorReport } from "@ryuzaki13/react-foundation-api/error-report";
+import type { ErrorReportDeliveryAdapter } from "@ryuzaki13/react-foundation-api/error-report";
+
+const deliveryAdapter: ErrorReportDeliveryAdapter = async (body) => {
+	await httpFetchPayload("/api/error-reports", {
+		init: {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify(body)
+		}
+	});
+};
+
+await sendErrorReport(reportId, {
+	adapter: deliveryAdapter,
+	queryClient
+});
+`})}),`
+`,(0,c.jsx)(t.h2,{id:`createerrorreportdeliverybody`,children:(0,c.jsx)(t.code,{children:`createErrorReportDeliveryBody`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const body = createErrorReportDeliveryBody(draft);
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Результат:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type ErrorReportDeliveryBody = {
+	reportId: string;
+	sessionId: string;
+	createdUtc: string;
+	category: ErrorReportCategory;
+	errorClass: string;
+	errorMessage: string;
+	stackTrace?: string;
+	payload: string;
+};
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`payload`}),` — JSON string всего payload черновика, а не вложенный object. Это важно для backend contract.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Если `,(0,c.jsx)(t.code,{children:`draft.payload.error.message`}),` пуст, обязательные `,(0,c.jsx)(t.code,{children:`errorMessage`}),` и message внутри сериализованного payload получают значение `,(0,c.jsx)(t.code,{children:`"Неизвестная ошибка"`}),`. Остальной draft не нормализуется.`]}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`JSON.stringify`}),` может выбросить ошибку при циклических или неподдерживаемых данных. Draft должен соответствовать сериализуемому контракту `,(0,c.jsx)(t.code,{children:`foundation-lib`}),`.`]}),`
+`,(0,c.jsx)(t.h3,{id:`что-такое-draft-и-delivery-body`,children:`Что такое draft и delivery body`}),`
+`,(0,c.jsx)(t.p,{children:`Для начинающего разработчика важно не смешивать две формы:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-text`,children:`ErrorReportDraft
+├── локальный lifecycle status
+├── retry information
+├── collected/sanitized payload
+└── identifiers
+
+ErrorReportDeliveryBody
+├── плоские обязательные backend fields
+└── payload: JSON string
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Draft принадлежит локальному хранилищу `,(0,c.jsx)(t.code,{children:`foundation-lib`}),`. Delivery body — одноразовый snapshot для transport adapter-а.`]}),`
+`,(0,c.jsx)(t.p,{children:`Нельзя отправлять draft целиком только потому, что он уже похож на body: backend contract намеренно отделён от local store contract.`}),`
+`,(0,c.jsx)(t.h3,{id:`соответствие-полей`,children:`Соответствие полей`}),`
+`,(0,c.jsxs)(t.table,{children:[(0,c.jsx)(t.thead,{children:(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.th,{children:`Delivery field`}),(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:`reportId`})}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`draft.reportId`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`sessionId`})}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`draft.sessionId`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`createdUtc`})}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`draft.createdUtc`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`category`})}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`draft.category`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`errorClass`})}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`draft.payload.error.name`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`errorMessage`})}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`draft.payload.error.message`}),` или fallback`]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`stackTrace`})}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`draft.payload.error.stackTrace`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`payload`})}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`JSON.stringify(normalized payload)`})})]})]})]}),`
+`,(0,c.jsx)(t.p,{children:`Если message содержит непустой текст с пробелами по краям, проверка считает его валидным, но в delivery сохраняется исходная строка. Функция не выполняет общий trim draft-а.`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`draft.payload.error.message = "  Ошибка сохранения  ";
+
+const body = createErrorReportDeliveryBody(draft);
+body.errorMessage;
+// "  Ошибка сохранения  "
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Если message пустой или whitespace-only:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`draft.payload.error.message = "   ";
+
+const body = createErrorReportDeliveryBody(draft);
+body.errorMessage;
+// "Неизвестная ошибка"
+
+JSON.parse(body.payload).error.message;
+// "Неизвестная ошибка"
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Функция создаёт новые wrapper objects и не записывает fallback обратно в draft.`}),`
+`,(0,c.jsx)(t.h2,{id:`senderrorreport`,children:(0,c.jsx)(t.code,{children:`sendErrorReport`})}),`
+`,(0,c.jsx)(t.p,{children:`Lifecycle:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-text`,children:`draft отсутствует ─────────► undefined
+status sent/sending ───────► текущий draft, adapter не вызывается
+остальной draft ───────────► sending
+                               │
+                    adapter success / error
+                       │              │
+                       ▼              ▼
+                     sent           failed + failedReason
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Пошагово функция:`}),`
+`,(0,c.jsxs)(t.ol,{children:[`
+`,(0,c.jsxs)(t.li,{children:[`Ищет draft по `,(0,c.jsx)(t.code,{children:`reportId`}),` в store из `,(0,c.jsx)(t.code,{children:`foundation-lib`}),`.`]}),`
+`,(0,c.jsxs)(t.li,{children:[`Возвращает `,(0,c.jsx)(t.code,{children:`undefined`}),`, если draft не найден.`]}),`
+`,(0,c.jsxs)(t.li,{children:[`Не отправляет повторно draft со статусом `,(0,c.jsx)(t.code,{children:`sent`}),` или `,(0,c.jsx)(t.code,{children:`sending`}),`.`]}),`
+`,(0,c.jsxs)(t.li,{children:[`Устанавливает `,(0,c.jsx)(t.code,{children:`status: "sending"`}),` и очищает `,(0,c.jsx)(t.code,{children:`failedReason`}),`.`]}),`
+`,(0,c.jsx)(t.li,{children:`Создаёт delivery body.`}),`
+`,(0,c.jsxs)(t.li,{children:[`Вызывает `,(0,c.jsx)(t.code,{children:`adapter(body, { draft, queryClient })`}),`.`]}),`
+`,(0,c.jsxs)(t.li,{children:[`При успехе устанавливает `,(0,c.jsx)(t.code,{children:`status: "sent"`}),` и `,(0,c.jsx)(t.code,{children:`sentUtc`}),`.`]}),`
+`,(0,c.jsxs)(t.li,{children:[`При ошибке устанавливает `,(0,c.jsx)(t.code,{children:`status: "failed"`}),`, сохраняет нормализованное сообщение и повторно бросает исходную ошибку.`]}),`
+`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Adapter получает исходный snapshot `,(0,c.jsx)(t.code,{children:`draft`}),`, прочитанный до перевода store в `,(0,c.jsx)(t.code,{children:`sending`}),`. Используйте `,(0,c.jsx)(t.code,{children:`body`}),` как delivery payload, а context — для query invalidation или transport, которому нужен `,(0,c.jsx)(t.code,{children:`QueryClient`}),`.`]}),`
+`,(0,c.jsx)(t.h3,{id:`status-table`,children:`Status table`}),`
+`,(0,c.jsxs)(t.table,{children:[(0,c.jsx)(t.thead,{children:(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.th,{children:`Status draft до вызова`}),(0,c.jsx)(t.th,{children:`Вызывается adapter`}),(0,c.jsx)(t.th,{children:`Результат`})]})}),(0,c.jsxs)(t.tbody,{children:[(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`draft отсутствует`}),(0,c.jsx)(t.td,{children:`нет`}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`undefined`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`sent`})}),(0,c.jsx)(t.td,{children:`нет`}),(0,c.jsx)(t.td,{children:`текущий draft`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`sending`})}),(0,c.jsx)(t.td,{children:`нет`}),(0,c.jsx)(t.td,{children:`текущий draft`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`pending`}),` или эквивалентный начальный`]}),(0,c.jsx)(t.td,{children:`да`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`sent`}),` либо exception + `,(0,c.jsx)(t.code,{children:`failed`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`failed`})}),(0,c.jsx)(t.td,{children:`да`}),(0,c.jsx)(t.td,{children:`повторная попытка`})]})]})]}),`
+`,(0,c.jsxs)(t.p,{children:[`Функция не создаёт draft. Если `,(0,c.jsx)(t.code,{children:`reportId`}),` ошибочный, это не exception: result равен `,(0,c.jsx)(t.code,{children:`undefined`}),`.`]}),`
+`,(0,c.jsx)(t.h3,{id:`время-отправки`,children:`Время отправки`}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`sentUtc`}),` создаётся на client после успешного завершения adapter-а:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`new Date().toISOString()
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Это client timestamp, а не server acknowledgement time. Для аудита используйте server time из backend record.`}),`
+`,(0,c.jsx)(t.h3,{id:`ошибка-построения-body`,children:`Ошибка построения body`}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`createErrorReportDeliveryBody`}),` вызывается внутри `,(0,c.jsx)(t.code,{children:`try`}),`. Если `,(0,c.jsx)(t.code,{children:`JSON.stringify`}),` выбросил error:`]}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsx)(t.li,{children:`adapter не вызывается;`}),`
+`,(0,c.jsxs)(t.li,{children:[`draft становится `,(0,c.jsx)(t.code,{children:`failed`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`failedReason`}),` формируется через `,(0,c.jsx)(t.code,{children:`createErrorInfo`}),`;`]}),`
+`,(0,c.jsx)(t.li,{children:`исходный error снова выбрасывается caller-у.`}),`
+`]}),`
+`,(0,c.jsx)(t.h3,{id:`ui-flow`,children:`UI flow`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-tsx`,children:`import { useState } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+import { sendErrorReport } from "@ryuzaki13/react-foundation-api/error-report";
+
+function SendReportButton({ reportId }: { reportId: string }) {
+	const queryClient = useQueryClient();
+	const [isSending, setIsSending] = useState(false);
+	const [errorMessage, setErrorMessage] = useState<string>();
+
+	const handleSend = async () => {
+		setIsSending(true);
+		setErrorMessage(undefined);
+
+		try {
+			const result = await sendErrorReport(reportId, {
+				adapter: deliveryAdapter,
+				queryClient
+			});
+
+			if (!result) {
+				setErrorMessage("Черновик отчёта не найден");
+			}
+		} catch (error) {
+			setErrorMessage(
+				error instanceof Error ? error.message : "Не удалось отправить отчёт"
+			);
+		} finally {
+			setIsSending(false);
+		}
+	};
+
+	return (
+		<>
+			<button type="button" disabled={isSending} onClick={handleSend}>
+				{isSending ? "Отправка…" : "Отправить отчёт"}
+			</button>
+			{errorMessage ? <p role="alert">{errorMessage}</p> : null}
+		</>
+	);
+}
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Local `,(0,c.jsx)(t.code,{children:`isSending`}),` нужен UI для немедленной блокировки повторного click. Draft status остаётся источником долгоживущего lifecycle, но component может не быть подписан на store.`]}),`
+`,(0,c.jsx)(t.h2,{id:`варианты-delivery-adapter-а`,children:`Варианты delivery adapter-а`}),`
+`,(0,c.jsx)(t.h3,{id:`обычный-http`,children:`Обычный HTTP`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import { httpFetchPayload } from "@ryuzaki13/react-foundation-api/http";
+import type { ErrorReportDeliveryAdapter } from "@ryuzaki13/react-foundation-api/error-report";
+
+export const deliveryAdapter: ErrorReportDeliveryAdapter = async (body) => {
+	await httpFetchPayload("/api/error-reports", {
+		init: {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify(body)
+		}
+	});
+};
+`})}),`
+`,(0,c.jsx)(t.h3,{id:`odata-functionimport`,children:`OData FunctionImport`}),`
+`,(0,c.jsx)(t.p,{children:`Если backend contract опубликован как FunctionImport, operation определяется metadata:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import { odataFunctionImportFn } from "@ryuzaki13/react-foundation-api/odata";
+import { wrapODataParams } from "@ryuzaki13/react-foundation-lib/odata-service";
+
+const deliveryAdapter: ErrorReportDeliveryAdapter = async (body, { queryClient }) => {
+	await odataFunctionImportFn({
+		odata: {
+			service: "ZERROR_REPORT_SRV",
+			target: "SendErrorReport"
+		},
+		params: wrapODataParams({
+			ReportId: body.reportId,
+			Payload: body.payload
+		})
+	})({ client: queryClient });
+};
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Это только пример mapping: точные parameter names должны соответствовать metadata вашего сервиса.`}),`
+`,(0,c.jsx)(t.h3,{id:`server-function`,children:`Server function`}),`
+`,(0,c.jsxs)(t.p,{children:[`Adapter может вызвать client-safe serverFn operation. Модуль error-report не знает о transport и не ограничивает его, пока adapter возвращает `,(0,c.jsx)(t.code,{children:`Promise<void>`}),`.`]}),`
+`,(0,c.jsx)(t.h3,{id:`почему-adapter-ничего-не-возвращает`,children:`Почему adapter ничего не возвращает`}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`sendErrorReport`}),` управляет local draft lifecycle, а не server entity. Если backend вернул receipt, adapter может обработать его внутри: сохранить в отдельный Query cache, telemetry или domain store. Public delivery contract считает успехом fulfilled promise.`]}),`
+`,(0,c.jsx)(t.h2,{id:`adapter-с-cache-invalidation`,children:`Adapter с cache invalidation`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const adapter: ErrorReportDeliveryAdapter = async (body, { queryClient }) => {
+	await postReport(body);
+	await queryClient.invalidateQueries({ queryKey: ["error-reports"] });
+};
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Если invalidation бросит ошибку, вся доставка считается неуспешной и draft станет `,(0,c.jsx)(t.code,{children:`failed`}),`, даже если backend уже принял отчёт. Для non-critical cache update обработайте ошибку внутри adapter-а.`]}),`
+`,(0,c.jsx)(t.p,{children:`Безопасный вариант для необязательного refresh:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const adapter: ErrorReportDeliveryAdapter = async (body, { queryClient }) => {
+	await postReport(body);
+
+	try {
+		await queryClient.invalidateQueries({ queryKey: ["error-reports"] });
+	} catch (error) {
+		console.warn("Отчёт отправлен, но cache не обновлён", error);
+	}
+};
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Решение зависит от contract: если fresh cache является частью успешной операции, не поглощайте ошибку.`}),`
+`,(0,c.jsx)(t.h2,{id:`повторная-отправка-и-concurrency`,children:`Повторная отправка и concurrency`}),`
+`,(0,c.jsxs)(t.p,{children:[`После `,(0,c.jsx)(t.code,{children:`failed`}),` функцию можно вызвать повторно. Проверка `,(0,c.jsx)(t.code,{children:`sending`}),` защищает от обычного повторного нажатия, но это не распределённая блокировка: два практически одновременных вызова могут успеть прочитать старый статус до его обновления. Backend желательно сделать идемпотентным по `,(0,c.jsx)(t.code,{children:`reportId`}),`.`]}),`
+`,(0,c.jsx)(t.h3,{id:`idempotency-backend-а`,children:`Idempotency backend-а`}),`
+`,(0,c.jsx)(t.p,{children:`Рекомендуемый server contract:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-text`,children:`UNIQUE(reportId)
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Повтор с тем же `,(0,c.jsx)(t.code,{children:`reportId`}),` должен либо вернуть прежний успешный result, либо завершиться предсказуемым «already accepted», которое adapter считает успехом.`]}),`
+`,(0,c.jsx)(t.p,{children:`Это защищает сценарий:`}),`
+`,(0,c.jsxs)(t.ol,{children:[`
+`,(0,c.jsx)(t.li,{children:`Backend принял report.`}),`
+`,(0,c.jsx)(t.li,{children:`Network response потерялся.`}),`
+`,(0,c.jsxs)(t.li,{children:[`Client пометил draft как `,(0,c.jsx)(t.code,{children:`failed`}),`.`]}),`
+`,(0,c.jsx)(t.li,{children:`Пользователь повторил отправку.`}),`
+`]}),`
+`,(0,c.jsx)(t.p,{children:`Без idempotency server создаст duplicate.`}),`
+`,(0,c.jsx)(t.h3,{id:`несколько-tabs`,children:`Несколько tabs`}),`
+`,(0,c.jsxs)(t.p,{children:[`Status `,(0,c.jsx)(t.code,{children:`sending`}),` в local store не является cross-tab distributed lock, если storage implementation явно не гарантирует это. Idempotency по `,(0,c.jsx)(t.code,{children:`reportId`}),` остаётся обязательной защитой.`]}),`
+`,(0,c.jsx)(t.h2,{id:`тестирование`,children:`Тестирование`}),`
+`,(0,c.jsx)(t.h3,{id:`body-builder`,children:`Body builder`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import { expect, it } from "vitest";
+
+it("подставляет fallback message в оба места", () => {
+	const body = createErrorReportDeliveryBody({
+		...draftFixture,
+		payload: {
+			...draftFixture.payload,
+			error: {
+				...draftFixture.payload.error,
+				message: " "
+			}
+		}
+	});
+
+	expect(body.errorMessage).toBe("Неизвестная ошибка");
+	expect(JSON.parse(body.payload).error.message).toBe("Неизвестная ошибка");
+});
+`})}),`
+`,(0,c.jsx)(t.h3,{id:`delivery-lifecycle`,children:`Delivery lifecycle`}),`
+`,(0,c.jsx)(t.p,{children:`В package/feature test проверяйте:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsx)(t.li,{children:`отсутствующий id не вызывает adapter;`}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`sent`}),` не отправляется повторно;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`sending`}),` не отправляется повторно;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`success переводит status в `,(0,c.jsx)(t.code,{children:`sent`}),` и задаёт ISO `,(0,c.jsx)(t.code,{children:`sentUtc`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`adapter error переводит status в `,(0,c.jsx)(t.code,{children:`failed`}),`;`]}),`
+`,(0,c.jsx)(t.li,{children:`исходный error сохраняет identity и выбрасывается повторно;`}),`
+`,(0,c.jsxs)(t.li,{children:[`retry после `,(0,c.jsx)(t.code,{children:`failed`}),` снова вызывает adapter.`]}),`
+`]}),`
+`,(0,c.jsx)(t.p,{children:`Adapter удобно делать mock-функцией:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const adapter = vi.fn<ErrorReportDeliveryAdapter>().mockResolvedValue(undefined);
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Не помещайте реальные stack traces, cookies, tokens или пользовательские данные в test snapshots.`}),`
+`,(0,c.jsx)(t.h2,{id:`частые-ошибки`,children:`Частые ошибки`}),`
+`,(0,c.jsx)(t.h3,{id:`передавать-draft-вместо-body`,children:`Передавать draft вместо body`}),`
+`,(0,c.jsxs)(t.p,{children:[`Adapter contract уже получает подготовленный `,(0,c.jsx)(t.code,{children:`body`}),`. Не сериализуйте `,(0,c.jsx)(t.code,{children:`context.draft`}),` вместо него.`]}),`
+`,(0,c.jsxs)(t.h3,{id:`дважды-сериализовать-payload`,children:[`Дважды сериализовать `,(0,c.jsx)(t.code,{children:`payload`})]}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`body.payload`}),` уже string:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`JSON.stringify(body)
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`правильно сериализует outer HTTP body. Не делайте `,(0,c.jsx)(t.code,{children:`body.payload = JSON.stringify(body.payload)`}),`.`]}),`
+`,(0,c.jsxs)(t.h3,{id:`считать-sending-надёжной-блокировкой`,children:[`Считать `,(0,c.jsx)(t.code,{children:`sending`}),` надёжной блокировкой`]}),`
+`,(0,c.jsx)(t.p,{children:`Это local lifecycle guard. Server idempotency всё равно нужна.`}),`
+`,(0,c.jsx)(t.h3,{id:`поглощать-adapter-error-в-ui`,children:`Поглощать adapter error в UI`}),`
+`,(0,c.jsx)(t.p,{children:`Функция намеренно rethrow-ит error. Покажите feedback и оставьте возможность retry.`}),`
+`,(0,c.jsx)(t.h3,{id:`добавлять-transport-в-shared-delivery-module`,children:`Добавлять transport в shared delivery module`}),`
+`,(0,c.jsx)(t.p,{children:`Endpoint и auth policy специфичны проекту. Они должны оставаться adapter-ом host application.`}),`
+`,(0,c.jsx)(t.h2,{id:`ошибки-и-безопасность`,children:`Ошибки и безопасность`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsx)(t.li,{children:`Ошибка adapter-а не поглощается: вызывающий код обязан её обработать.`}),`
+`,(0,c.jsx)(t.li,{children:`Не добавляйте secrets в draft. Delivery layer не выполняет дополнительную redaction всего payload.`}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`queryClient`}),` передаётся adapter-у, но модуль сам не инвалидирует queries.`]}),`
+`,(0,c.jsx)(t.li,{children:`Функция управляет локальным draft store; не вызывайте её в среде без подходящего storage/runtime, если draft store там недоступен.`}),`
+`,(0,c.jsxs)(t.li,{children:[`Статус `,(0,c.jsx)(t.code,{children:`sent`}),` означает успешное завершение adapter-а, а не обязательное подтверждение бизнес-обработки backend-ом.`]}),`
+`,(0,c.jsx)(t.li,{children:`Delivery body содержит stack trace и diagnostic payload: передавайте его только по защищённому каналу авторизованному endpoint.`}),`
+`,(0,c.jsxs)(t.li,{children:[`Не логируйте `,(0,c.jsx)(t.code,{children:`body.payload`}),` целиком в production.`]}),`
+`,(0,c.jsxs)(t.li,{children:[`Redaction должна происходить при сборе draft в `,(0,c.jsx)(t.code,{children:`foundation-lib`}),`; delivery boundary не может безопасно угадать все domain secrets.`]}),`
+`]}),`
+`,(0,c.jsx)(t.h2,{id:`faq`,children:`FAQ`}),`
+`,(0,c.jsxs)(t.h3,{id:`почему-функции-нужен-queryclient-даже-если-adapter-его-не-использует`,children:[`Почему функции нужен `,(0,c.jsx)(t.code,{children:`QueryClient`}),`, даже если adapter его не использует?`]}),`
+`,(0,c.jsx)(t.p,{children:`Это единый adapter context. Он позволяет OData operations и cache synchronization без глобального QueryClient.`}),`
+`,(0,c.jsx)(t.h3,{id:`можно-ли-отправить-report-которого-нет-в-store`,children:`Можно ли отправить report, которого нет в store?`}),`
+`,(0,c.jsxs)(t.p,{children:[`Нет. `,(0,c.jsx)(t.code,{children:`sendErrorReport`}),` принимает id существующего draft и вернёт `,(0,c.jsx)(t.code,{children:`undefined`}),`.`]}),`
+`,(0,c.jsx)(t.h3,{id:`можно-ли-изменить-body-перед-отправкой`,children:`Можно ли изменить body перед отправкой?`}),`
+`,(0,c.jsx)(t.p,{children:`Да, внутри project adapter можно построить backend-specific envelope. Не мутируйте входной body; создайте новый object.`}),`
+`,(0,c.jsx)(t.h3,{id:`когда-разрешён-retry`,children:`Когда разрешён retry?`}),`
+`,(0,c.jsxs)(t.p,{children:[`После status `,(0,c.jsx)(t.code,{children:`failed`}),`. `,(0,c.jsx)(t.code,{children:`sent`}),` и `,(0,c.jsx)(t.code,{children:`sending`}),` являются no-op states.`]}),`
+`,(0,c.jsx)(t.h3,{id:`кто-отвечает-за-offline-queue`,children:`Кто отвечает за offline queue?`}),`
+`,(0,c.jsx)(t.p,{children:`Не этот модуль. Он хранит lifecycle одного draft и вызывает adapter. Background sync/retry scheduler должен быть отдельной явно спроектированной инфраструктурой.`}),`
+`,(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:`createErrorReportDeliveryBody`})}),(0,c.jsx)(t.td,{children:`Строит сериализуемый backend body`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`sendErrorReport`})}),(0,c.jsx)(t.td,{children:`Управляет status и вызывает adapter`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`ErrorReportDeliveryBody`})}),(0,c.jsx)(t.td,{children:`Поля delivery payload`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`ErrorReportDeliveryContext`})}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`draft`}),` и `,(0,c.jsx)(t.code,{children:`queryClient`}),` для adapter-а`]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`ErrorReportDeliveryAdapter`})}),(0,c.jsx)(t.td,{children:`Контракт функции доставки`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`SendErrorReportOptions`})}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`adapter`}),` и `,(0,c.jsx)(t.code,{children:`queryClient`})]})]})]})]})]})}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-Byi1FFpw.js

@@ -0,0 +1,98 @@
+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`,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/Data/XML`}),`
+`,(0,c.jsxs)(t.h1,{id:`простые-xml-helpers-через-ryuzaki13react-foundation-libxml`,children:[`Простые XML helpers через `,(0,c.jsx)(t.code,{children:`@ryuzaki13/react-foundation-lib/xml`})]}),`
+`,(0,c.jsxs)(t.p,{children:[`Модуль экранирует XML-текст, строит последовательность простых полей и читает текст первого тега через `,(0,c.jsx)(t.code,{children:`DOMParser`}),`.`]}),`
+`,(0,c.jsx)(t.h2,{id:`содержание`,children:`Содержание`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsx)(t.li,{children:(0,c.jsx)(t.a,{href:`#%D0%BD%D0%B0%D0%B7%D0%BD%D0%B0%D1%87%D0%B5%D0%BD%D0%B8%D0%B5-%D0%B8-%D0%B3%D1%80%D0%B0%D0%BD%D0%B8%D1%86%D1%8B`,children:`Назначение и границы`})}),`
+`,(0,c.jsx)(t.li,{children:(0,c.jsx)(t.a,{href:`#%D1%83%D1%81%D1%82%D0%B0%D0%BD%D0%BE%D0%B2%D0%BA%D0%B0-%D0%B8-%D0%B8%D0%BC%D0%BF%D0%BE%D1%80%D1%82`,children:`Установка и импорт`})}),`
+`,(0,c.jsx)(t.li,{children:(0,c.jsx)(t.a,{href:`#escapexmlvalue`,children:(0,c.jsx)(t.code,{children:`escapeXmlValue`})})}),`
+`,(0,c.jsx)(t.li,{children:(0,c.jsx)(t.a,{href:`#buildxmlfields`,children:(0,c.jsx)(t.code,{children:`buildXmlFields`})})}),`
+`,(0,c.jsx)(t.li,{children:(0,c.jsx)(t.a,{href:`#getxmltagtext`,children:(0,c.jsx)(t.code,{children:`getXmlTagText`})})}),`
+`,(0,c.jsx)(t.li,{children:(0,c.jsx)(t.a,{href:`#%D0%B1%D0%B5%D0%B7%D0%BE%D0%BF%D0%B0%D1%81%D0%BD%D0%BE%D1%81%D1%82%D1%8C-%D0%B8-%D0%BE%D0%B3%D1%80%D0%B0%D0%BD%D0%B8%D1%87%D0%B5%D0%BD%D0%B8%D1%8F`,children:`Безопасность и ограничения`})}),`
+`,(0,c.jsx)(t.li,{children:(0,c.jsx)(t.a,{href:`#api`,children:`API`})}),`
+`]}),`
+`,(0,c.jsx)(t.h2,{id:`назначение-и-границы`,children:`Назначение и границы`}),`
+`,(0,c.jsx)(t.p,{children:`Подходит для небольших flat XML fragments:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-xml`,children:`<ORDER_ID>42</ORDER_ID><COMMENT>A&amp;B</COMMENT>
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Модуль не является полноценным XML builder/parser:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsx)(t.li,{children:`не строит document/envelope;`}),`
+`,(0,c.jsx)(t.li,{children:`не управляет namespaces и attributes;`}),`
+`,(0,c.jsx)(t.li,{children:`не валидирует XSD;`}),`
+`,(0,c.jsx)(t.li,{children:`не обрабатывает коллекции/вложенные объекты;`}),`
+`,(0,c.jsx)(t.li,{children:`не проверяет parser errors;`}),`
+`,(0,c.jsx)(t.li,{children:`не выполняет network request.`}),`
+`]}),`
+`,(0,c.jsx)(t.h2,{id:`установка-и-импорт`,children:`Установка и импорт`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import { buildXmlFields, escapeXmlValue, getXmlTagText } from "@ryuzaki13/react-foundation-lib/xml";
+
+import type { XmlPrimitive } from "@ryuzaki13/react-foundation-lib/xml";
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Builder-функции не требуют DOM. `,(0,c.jsx)(t.code,{children:`getXmlTagText`}),` требует global `,(0,c.jsx)(t.code,{children:`DOMParser`}),`, доступный в браузере/jsdom, но обычно отсутствующий в чистом Node.js.`]}),`
+`,(0,c.jsx)(t.h2,{id:`escapexmlvalue`,children:(0,c.jsx)(t.code,{children:`escapeXmlValue`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`escapeXmlValue(\`a&b<c>d"e'f\`);
+// "a&amp;b&lt;c&gt;d&quot;e&apos;f"
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Тип входа:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type XmlPrimitive = string | number | null | undefined;
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Правила:`}),`
+`,(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:`XML entity`})]})}),(0,c.jsxs)(t.tbody,{children:[(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`&`})}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`&amp;`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`<`})}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`&lt;`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`>`})}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`&gt;`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`"`})}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`&quot;`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`'`})}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`&apos;`})})]})]})]}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`null`}),` и `,(0,c.jsx)(t.code,{children:`undefined`}),` превращаются в пустую строку. Number сначала преобразуется через `,(0,c.jsx)(t.code,{children:`String`}),`.`]}),`
+`,(0,c.jsx)(t.p,{children:`Функция предназначена для текстового содержимого. Для attribute value она экранирует основные символы, но сам attribute builder модуль не предоставляет.`}),`
+`,(0,c.jsx)(t.p,{children:`Не передавайте уже экранированную строку повторно:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`escapeXmlValue("A&amp;B"); // "A&amp;amp;B".
+`})}),`
+`,(0,c.jsx)(t.h2,{id:`buildxmlfields`,children:(0,c.jsx)(t.code,{children:`buildXmlFields`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const xml = buildXmlFields({
+	ORDER_ID: 42,
+	COMMENT: "A&B",
+	OPTIONAL: null
+});
+
+// <ORDER_ID>42</ORDER_ID><COMMENT>A&amp;B</COMMENT><OPTIONAL></OPTIONAL>
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Функция:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[`обходит `,(0,c.jsx)(t.code,{children:`Object.entries`}),` в стандартном порядке ключей;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`строит для каждого поля `,(0,c.jsx)(t.code,{children:`<NAME>escaped value</NAME>`}),`;`]}),`
+`,(0,c.jsx)(t.li,{children:`не добавляет переносы строк;`}),`
+`,(0,c.jsxs)(t.li,{children:[`сохраняет поля с `,(0,c.jsx)(t.code,{children:`null`}),`/`,(0,c.jsx)(t.code,{children:`undefined`}),` как пустые теги;`]}),`
+`,(0,c.jsx)(t.li,{children:`не изменяет исходный объект.`}),`
+`]}),`
+`,(0,c.jsx)(t.p,{children:`Имя тега вставляется без валидации и escaping. Ключи должны быть доверенными валидными XML names из программного contract:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`// Нельзя строить key из пользовательского ввода.
+buildXmlFields({ [userProvidedTagName]: value });
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Для вложенной структуры передайте уже собранный fragment как часть внешнего builder-а; `,(0,c.jsx)(t.code,{children:`buildXmlFields`}),` сам воспринимает строку как текст и экранирует markup.`]}),`
+`,(0,c.jsx)(t.h2,{id:`getxmltagtext`,children:(0,c.jsx)(t.code,{children:`getXmlTagText`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const message = getXmlTagText("<root><EX_MESSAGE>  Ошибка  </EX_MESSAGE></root>", "EX_MESSAGE");
+
+console.log(message); // "Ошибка".
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Алгоритм:`}),`
+`,(0,c.jsxs)(t.ol,{children:[`
+`,(0,c.jsxs)(t.li,{children:[`Парсит всю строку как `,(0,c.jsx)(t.code,{children:`application/xml`}),`.`]}),`
+`,(0,c.jsxs)(t.li,{children:[`Вызывает `,(0,c.jsx)(t.code,{children:`getElementsByTagName(tagName)`}),`.`]}),`
+`,(0,c.jsx)(t.li,{children:`Берёт только первый найденный element.`}),`
+`,(0,c.jsxs)(t.li,{children:[`Читает объединённый `,(0,c.jsx)(t.code,{children:`textContent`}),`.`]}),`
+`,(0,c.jsx)(t.li,{children:`Обрезает пробелы.`}),`
+`,(0,c.jsxs)(t.li,{children:[`Возвращает `,(0,c.jsx)(t.code,{children:`undefined`}),`, если элемента/непустого текста нет.`]}),`
+`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`getXmlTagText("<root />", "MESSAGE"); // undefined.
+getXmlTagText("<root><MESSAGE>   </MESSAGE></root>", "MESSAGE"); // undefined.
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Для namespace-sensitive XML точное поведение `,(0,c.jsx)(t.code,{children:`getElementsByTagName`}),` зависит от переданного имени. Модуль не предоставляет `,(0,c.jsx)(t.code,{children:`getElementsByTagNameNS`}),`.`]}),`
+`,(0,c.jsx)(t.h2,{id:`безопасность-и-ограничения`,children:`Безопасность и ограничения`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[`Не вставляйте результат XML в HTML DOM через `,(0,c.jsx)(t.code,{children:`innerHTML`}),`.`]}),`
+`,(0,c.jsx)(t.li,{children:`Не используйте dynamic tag names из недоверенного ввода.`}),`
+`,(0,c.jsxs)(t.li,{children:[`Parser не проверяется на `,(0,c.jsx)(t.code,{children:`<parsererror>`}),`; malformed XML обычно даёт `,(0,c.jsx)(t.code,{children:`undefined`}),` или parser-specific tree, а не явное исключение этого helper.`]}),`
+`,(0,c.jsx)(t.li,{children:`Читается только первое совпадение.`}),`
+`,(0,c.jsx)(t.li,{children:`Большие documents лучше разбирать специализированным parser/streaming boundary.`}),`
+`,(0,c.jsx)(t.li,{children:`Модуль не предотвращает XML signature wrapping и не предназначен для security validation.`}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`XmlPrimitive`}),` number допускает `,(0,c.jsx)(t.code,{children:`NaN`}),`/`,(0,c.jsx)(t.code,{children:`Infinity`}),` на уровне TypeScript; они станут строками `,(0,c.jsx)(t.code,{children:`"NaN"`}),`/`,(0,c.jsx)(t.code,{children:`"Infinity"`}),`.`]}),`
+`]}),`
+`,(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:`escapeXmlValue`})}),(0,c.jsx)(t.td,{children:`Экранированная строка`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`buildXmlFields`})}),(0,c.jsx)(t.td,{children:`Компактный XML fragment`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`getXmlTagText`})}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`string | undefined`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`XmlPrimitive`})}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`string | number | null | undefined`})})]})]})]})]})}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};