@ryuzaki13/react-foundation-ui 1.8.11 → 1.8.13

package/storybook-static/assets/{README-B4zYJg6u.js → README-Kfawetke.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/Crypto`}),`
+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/Crypto`}),`
 `,(0,c.jsxs)(t.h1,{id:`идентификаторы-и-строковые-hash-через-ryuzaki13react-foundation-libcrypto`,children:[`Идентификаторы и строковые hash через `,(0,c.jsx)(t.code,{children:`@ryuzaki13/react-foundation-lib/crypto`})]}),`
 `,(0,c.jsxs)(t.p,{children:[`Модуль `,(0,c.jsx)(t.code,{children:`crypto`}),` предоставляет небольшие функции для двух разных задач:`]}),`
 `,(0,c.jsxs)(t.ul,{children:[`

package/storybook-static/assets/{README-BzVHwvgo.js → README-UDBM7ZMT.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/Value State`}),`
+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/Value State`}),`
 `,(0,c.jsx)(t.h1,{id:`value-state`,children:`Value state`}),`
 `,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`valueState`}),` преобразует обычное значение в семантическое состояние интерфейса:`]}),`
 `,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type State = "" | "none" | "information" | "success" | "warning" | "error";

package/storybook-static/assets/{README-D-XjRtAE.js → README-VTWQxLm_.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/Copy`}),`
+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/Copy`}),`
 `,(0,c.jsxs)(t.h1,{id:`копирование-текста-через-ryuzaki13react-foundation-libcopy`,children:[`Копирование текста через `,(0,c.jsx)(t.code,{children:`@ryuzaki13/react-foundation-lib/copy`})]}),`
 `,(0,c.jsxs)(t.p,{children:[`Модуль `,(0,c.jsx)(t.code,{children:`copy`}),` содержит React hooks для копирования текста в системный буфер обмена, чтения текста из DOM-элемента и показа короткого состояния «скопировано».`]}),`
 `,(0,c.jsx)(t.p,{children:`Основные сценарии:`}),`

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

@@ -0,0 +1,400 @@
+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 API/Transport/HTTP`}),`
+`,(0,c.jsxs)(t.h1,{id:`обычный-http-через-ryuzaki13react-foundation-apihttp`,children:[`Обычный HTTP через `,(0,c.jsx)(t.code,{children:`@ryuzaki13/react-foundation-api/http`})]}),`
+`,(0,c.jsxs)(t.p,{children:[`Модуль выполняет нейтральные HTTP/REST запросы и создаёт функции, совместимые с TanStack Query. Внешний payload остаётся `,(0,c.jsx)(t.code,{children:`unknown`}),`, пока consumer явно не проверит его через `,(0,c.jsx)(t.code,{children:`parse`}),`.`]}),`
+`,(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%BA%D0%BE%D0%B3%D0%B4%D0%B0-%D0%B8%D1%81%D0%BF%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D1%82%D1%8C`,children:`Когда использовать`})}),`
+`,(0,c.jsx)(t.li,{children:(0,c.jsx)(t.a,{href:`#%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:`#httpfetch`,children:(0,c.jsx)(t.code,{children:`httpFetch`})})}),`
+`,(0,c.jsx)(t.li,{children:(0,c.jsx)(t.a,{href:`#httpfetchpayload`,children:(0,c.jsx)(t.code,{children:`httpFetchPayload`})})}),`
+`,(0,c.jsx)(t.li,{children:(0,c.jsx)(t.a,{href:`#httpjsonqueryfn`,children:(0,c.jsx)(t.code,{children:`httpJsonQueryFn`})})}),`
+`,(0,c.jsx)(t.li,{children:(0,c.jsx)(t.a,{href:`#httpjsonmutationfn`,children:(0,c.jsx)(t.code,{children:`httpJsonMutationFn`})})}),`
+`,(0,c.jsx)(t.li,{children:(0,c.jsx)(t.a,{href:`#routeerror`,children:(0,c.jsx)(t.code,{children:`RouteError`})})}),`
+`,(0,c.jsx)(t.li,{children:(0,c.jsx)(t.a,{href:`#%D0%BE%D1%88%D0%B8%D0%B1%D0%BA%D0%B8-runtime-%D0%B8-%D0%B1%D0%B5%D0%B7%D0%BE%D0%BF%D0%B0%D1%81%D0%BD%D0%BE%D1%81%D1%82%D1%8C`,children:`Ошибки, runtime и безопасность`})}),`
+`,(0,c.jsx)(t.li,{children:(0,c.jsx)(t.a,{href:`#%D0%BF%D0%BE%D0%BB%D0%BD%D1%8B%D0%B9-api`,children:`Полный API`})}),`
+`]}),`
+`,(0,c.jsx)(t.h2,{id:`когда-использовать`,children:`Когда использовать`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-text`,children:`обычный REST/HTTP ──► /http
+SAP Gateway/OData ──► /odata
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`http`}),` не добавляет SAP headers, `,(0,c.jsx)(t.code,{children:`credentials: include`}),`, X-CSRF token, SSO recovery, OData V2 headers и не снимает envelope `,(0,c.jsx)(t.code,{children:`{ d: { results } }`}),`. Для SAP/OData используйте `,(0,c.jsx)(t.a,{href:`../odata/README.mdx`,children:(0,c.jsx)(t.code,{children:`/odata`})}),`.`]}),`
+`,(0,c.jsx)(t.p,{children:`Модуль намеренно остаётся небольшим. Он не пытается быть REST framework: выполняет request, проверяет HTTP status, разбирает базовый payload и требует от consumer-а runtime parser.`}),`
+`,(0,c.jsx)(t.h2,{id:`импорт`,children:`Импорт`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import {
+	httpFetch,
+	httpFetchPayload,
+	httpJsonMutationFn,
+	httpJsonQueryFn,
+	RouteError
+} from "@ryuzaki13/react-foundation-api/http";
+
+import type {
+	HttpMutationFnOptions,
+	HttpQueryFnOptions,
+	HttpRequestOptions
+} from "@ryuzaki13/react-foundation-api/http";
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Нужны глобальные Web Fetch API: `,(0,c.jsx)(t.code,{children:`fetch`}),`, `,(0,c.jsx)(t.code,{children:`Request`}),`, `,(0,c.jsx)(t.code,{children:`Response`}),`, `,(0,c.jsx)(t.code,{children:`Headers`}),`, `,(0,c.jsx)(t.code,{children:`URL`}),`.`]}),`
+`,(0,c.jsx)(t.h2,{id:`httpfetch`,children:(0,c.jsx)(t.code,{children:`httpFetch`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const response = await httpFetch("/health", {
+	baseUrl: "https://api.example.com",
+	init: {
+		method: "GET",
+		headers: { Accept: "text/plain" }
+	}
+});
+
+console.log(await response.text());
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Функция возвращает исходный `,(0,c.jsx)(t.code,{children:`Response`}),`, если `,(0,c.jsx)(t.code,{children:`response.ok === true`}),`. Body ещё не прочитан.`]}),`
+`,(0,c.jsx)(t.p,{children:`Для string input URL строится простой конкатенацией:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-text`,children:`baseUrl + input
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Helper не исправляет slash:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`// Правильно.
+{ baseUrl: "https://api.example.com", input: "/users" }
+
+// Получится https://api.example.comusers — неверно.
+{ baseUrl: "https://api.example.com", input: "users" }
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Если input является `,(0,c.jsx)(t.code,{children:`Request`}),` или `,(0,c.jsx)(t.code,{children:`URL`}),`, `,(0,c.jsx)(t.code,{children:`baseUrl`}),` игнорируется. Это не proxy/url resolver.`]}),`
+`,(0,c.jsx)(t.h3,{id:`полные-request-options`,children:`Полные request options`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type HttpRequestOptions = {
+	readonly baseUrl?: string;
+	readonly init?: RequestInit;
+};
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Caller самостоятельно задаёт method, headers, cookies и signal:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const controller = new AbortController();
+
+const request = httpFetch("/profile", {
+	baseUrl: "/api",
+	init: {
+		method: "GET",
+		headers: {
+			Accept: "application/json",
+			Authorization: \`Bearer \${token}\`
+		},
+		credentials: "include",
+		signal: controller.signal
+	}
+});
+
+controller.abort();
+await request;
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Отмена пробрасывается как native fetch error. Модуль не превращает её в специальный класс.`}),`
+`,(0,c.jsxs)(t.h3,{id:`зачем-возвращать-response`,children:[`Зачем возвращать `,(0,c.jsx)(t.code,{children:`Response`})]}),`
+`,(0,c.jsxs)(t.p,{children:[`Используйте `,(0,c.jsx)(t.code,{children:`httpFetch`}),`, а не `,(0,c.jsx)(t.code,{children:`httpFetchPayload`}),`, когда нужны headers, Blob, stream или custom parser:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const response = await httpFetch("/reports/export.xlsx", {
+	baseUrl: "/api"
+});
+
+const file = await response.blob();
+const disposition = response.headers.get("Content-Disposition");
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Response body читается один раз. После `,(0,c.jsx)(t.code,{children:`blob()`}),` нельзя повторно вызвать `,(0,c.jsx)(t.code,{children:`json()`}),` без предварительного `,(0,c.jsx)(t.code,{children:`response.clone()`}),`.`]}),`
+`,(0,c.jsx)(t.h2,{id:`httpfetchpayload`,children:(0,c.jsx)(t.code,{children:`httpFetchPayload`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const payload: unknown = await httpFetchPayload("/api/profile");
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Правила parser-а:`}),`
+`,(0,c.jsxs)(t.table,{children:[(0,c.jsx)(t.thead,{children:(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.th,{children:`Response`}),(0,c.jsx)(t.th,{children:`Результат`})]})}),(0,c.jsxs)(t.tbody,{children:[(0,c.jsxs)(t.tr,{children:[(0,c.jsxs)(t.td,{children:[`status `,(0,c.jsx)(t.code,{children:`204`}),` или `,(0,c.jsx)(t.code,{children:`205`})]}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`null`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`Content-Type`}),` содержит `,(0,c.jsx)(t.code,{children:`application/json`})]}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`response.json()`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`любой другой content type`}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`response.text()`})})]})]})]}),`
+`,(0,c.jsxs)(t.p,{children:[`Результат намеренно `,(0,c.jsx)(t.code,{children:`unknown`}),`. Generic type не может проверить данные, пришедшие по сети:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`function parseProfile(value: unknown): Profile {
+	if (!isProfile(value)) throw new Error("Некорректный Profile payload");
+	return value;
+}
+
+const profile = parseProfile(await httpFetchPayload("/api/profile"));
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Если сервер отдаёт JSON без корректного `,(0,c.jsx)(t.code,{children:`Content-Type`}),`, модуль вернёт JSON как string. Исправьте backend или разберите string на своей boundary.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Content-Type приводится к lowercase, но распознаётся только media type, содержащий literal `,(0,c.jsx)(t.code,{children:`application/json`}),`. Например, `,(0,c.jsx)(t.code,{children:`application/problem+json`}),` будет прочитан как text. Для такого endpoint используйте `,(0,c.jsx)(t.code,{children:`httpFetch`}),` с custom parsing либо расширьте общий package contract.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Invalid JSON с header `,(0,c.jsx)(t.code,{children:`application/json`}),` приводит к native parsing error. Он не заменяется на `,(0,c.jsx)(t.code,{children:`null`}),` или text.`]}),`
+`,(0,c.jsx)(t.h2,{id:`httpjsonqueryfn`,children:(0,c.jsx)(t.code,{children:`httpJsonQueryFn`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Factory возвращает async-функцию с формой TanStack Query `,(0,c.jsx)(t.code,{children:`queryFn`}),`:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const loadProfile = httpJsonQueryFn("/api/profile", {
+	baseUrl: "https://api.example.com",
+	parse: parseProfile,
+	swCache: "ttl=10m;name=profile"
+});
+
+const profile = await loadProfile({ signal });
+`})}),`
+`,(0,c.jsx)(t.p,{children:`С React Query:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-tsx`,children:`const profileQuery = useQuery({
+	queryKey: ["profile", userId],
+	queryFn: httpJsonQueryFn(\`/api/users/\${userId}\`, {
+		parse: parseProfile
+	})
+});
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Factory:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[`использует `,(0,c.jsx)(t.code,{children:`init.signal`}),`, если он задан явно;`]}),`
+`,(0,c.jsx)(t.li,{children:`иначе подставляет signal, переданный TanStack Query;`}),`
+`,(0,c.jsxs)(t.li,{children:[`добавляет `,(0,c.jsx)(t.code,{children:`x-sw-cache`}),`, только если `,(0,c.jsx)(t.code,{children:`swCache`}),` truthy;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`вызывает обязательный `,(0,c.jsx)(t.code,{children:`parse(payload)`}),` после успешного запроса.`]}),`
+`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Header `,(0,c.jsx)(t.code,{children:`x-sw-cache`}),` — только protocol с Service Worker. Без соответствующего SW он не создаёт cache.`]}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`parse`}),` может вернуть преобразованную domain model, но обычно лучше ограничиться runtime validation и вынести бизнес-mapping владельцу entity.`]}),`
+`,(0,c.jsxs)(t.h3,{id:`почему-parse-обязателен`,children:[`Почему `,(0,c.jsx)(t.code,{children:`parse`}),` обязателен`]}),`
+`,(0,c.jsx)(t.p,{children:`TypeScript generic исчезает из runtime:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`// Аннотация User не проверяет network.
+const unsafe = httpJsonQueryFn<User>("/api/user", {
+	parse: (payload) => payload as User
+});
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Минимальный parser:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`function parseUser(payload: unknown): User {
+	if (!payload || typeof payload !== "object") {
+		throw new Error("User response должен быть object");
+	}
+
+	const record = payload as Record<string, unknown>;
+	if (typeof record.id !== "string" || typeof record.name !== "string") {
+		throw new Error("User response содержит неверные поля");
+	}
+
+	return { id: record.id, name: record.name };
+}
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Для сложной формы используйте project-approved runtime schema validator.`}),`
+`,(0,c.jsx)(t.h3,{id:`stable-query-options`,children:`Stable query options`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import { queryOptions } from "@tanstack/react-query";
+
+const userKeys = {
+	all: ["users"] as const,
+	detail: (id: string) => [...userKeys.all, "detail", id] as const
+};
+
+export const userQueryOptions = (id: string) =>
+	queryOptions({
+		queryKey: userKeys.detail(id),
+		queryFn: httpJsonQueryFn(
+			\`/api/users/\${encodeURIComponent(id)}\`,
+			{
+				parse: parseUser,
+				swCache: "off"
+			}
+		),
+		enabled: id.length > 0
+	});
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Все inputs, меняющие response, должны быть в query key. URL encoding остаётся обязанностью caller-а.`}),`
+`,(0,c.jsx)(t.h3,{id:`abortsignal-priority`,children:`AbortSignal priority`}),`
+`,(0,c.jsxs)(t.p,{children:[`Если `,(0,c.jsx)(t.code,{children:`options.init.signal`}),` отсутствует, factory подставляет signal TanStack Query. Если explicit signal уже задан, он имеет приоритет и QueryClient cancellation его не заменит.`]}),`
+`,(0,c.jsx)(t.h3,{id:`service-worker-header`,children:`Service Worker header`}),`
+`,(0,c.jsxs)(t.p,{children:[`Factory создаёт новый `,(0,c.jsx)(t.code,{children:`Headers`}),` object и выставляет `,(0,c.jsx)(t.code,{children:`x-sw-cache`}),`, когда `,(0,c.jsx)(t.code,{children:`swCache`}),` truthy. Если такой header уже был в `,(0,c.jsx)(t.code,{children:`init.headers`}),`, option `,(0,c.jsx)(t.code,{children:`swCache`}),` перезапишет его.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Сам header ничего не кэширует без Service Worker, который реализует protocol. Для auth-sensitive responses используйте `,(0,c.jsx)(t.code,{children:`off`}),`, пока isolation users/sessions явно не доказана.`]}),`
+`,(0,c.jsx)(t.h2,{id:`httpjsonmutationfn`,children:(0,c.jsx)(t.code,{children:`httpJsonMutationFn`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type CreateUserInput = { name: string };
+
+const createUser = httpJsonMutationFn<CreateUserInput, User>("/api/users", {
+	method: "POST",
+	mapBody: (input) => ({ displayName: input.name }),
+	parse: parseUser
+});
+
+const user = await createUser({ name: "Анна" });
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`С `,(0,c.jsx)(t.code,{children:`useMutation`}),`:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-tsx`,children:`const mutation = useMutation({ mutationFn: createUser });
+mutation.mutate({ name: "Анна" });
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Поведение:`}),`
+`,(0,c.jsxs)(t.ol,{children:[`
+`,(0,c.jsxs)(t.li,{children:[`Вычисляет body через `,(0,c.jsx)(t.code,{children:`mapBody(input)`}),` или использует input.`]}),`
+`,(0,c.jsxs)(t.li,{children:[`Сериализует body через `,(0,c.jsx)(t.code,{children:`JSON.stringify`}),`.`]}),`
+`,(0,c.jsxs)(t.li,{children:[`Использует method `,(0,c.jsx)(t.code,{children:`POST`}),` по умолчанию; поддерживаются `,(0,c.jsx)(t.code,{children:`POST`}),`, `,(0,c.jsx)(t.code,{children:`PUT`}),`, `,(0,c.jsx)(t.code,{children:`PATCH`}),`, `,(0,c.jsx)(t.code,{children:`DELETE`}),`.`]}),`
+`,(0,c.jsxs)(t.li,{children:[`Добавляет `,(0,c.jsx)(t.code,{children:`Content-Type: application/json`}),`, только если header ещё не задан.`]}),`
+`,(0,c.jsxs)(t.li,{children:[`Выполняет запрос и передаёт payload в обязательный `,(0,c.jsx)(t.code,{children:`parse`}),`.`]}),`
+`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Сигнатура mutation function также допускает второй `,(0,c.jsx)(t.code,{children:`AbortSignal`}),` при ручном вызове. Стандартный `,(0,c.jsx)(t.code,{children:`useMutation`}),` TanStack Query не передаёт signal автоматически. Если `,(0,c.jsx)(t.code,{children:`options.init.signal`}),` уже задан, второй signal не заменит его.`]}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`JSON.stringify`}),` может бросить ошибку для `,(0,c.jsx)(t.code,{children:`BigInt`}),`/циклического объекта. `,(0,c.jsx)(t.code,{children:`undefined`}),` body сериализуется в `,(0,c.jsx)(t.code,{children:`undefined`}),`; убедитесь, что это соответствует endpoint.`]}),`
+`,(0,c.jsx)(t.h3,{id:`полные-mutation-options`,children:`Полные mutation options`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type HttpMutationFnOptions<TInput, TResult> = HttpRequestOptions & {
+	readonly method?: "POST" | "PUT" | "PATCH" | "DELETE";
+	readonly mapBody?: (input: TInput) => unknown;
+	readonly parse: (data: unknown) => TResult;
+};
+`})}),`
+`,(0,c.jsx)(t.h3,{id:`mapping-input-в-body`,children:`Mapping input в body`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type UpdateProfileInput = {
+	userId: string;
+	draft: {
+		name: string;
+		email: string;
+	};
+};
+
+const updateProfile = httpJsonMutationFn<UpdateProfileInput, User>(
+	"/api/profile",
+	{
+		method: "PATCH",
+		mapBody: ({ draft }) => ({
+			displayName: draft.name,
+			emailAddress: draft.email
+		}),
+		parse: parseUser
+	}
+);
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`URL factory фиксирован при создании. Если path зависит от input, создайте feature wrapper, который внутри строит подходящий mutation function или вызывает `,(0,c.jsx)(t.code,{children:`httpFetchPayload`}),`.`]}),`
+`,(0,c.jsx)(t.h3,{id:`особенность-nullish-body-mapper`,children:`Особенность nullish body mapper`}),`
+`,(0,c.jsx)(t.p,{children:`Implementation выбирает body так:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const body = options.mapBody?.(input) ?? input;
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Если `,(0,c.jsx)(t.code,{children:`mapBody`}),` вернул `,(0,c.jsx)(t.code,{children:`null`}),` или `,(0,c.jsx)(t.code,{children:`undefined`}),`, будет сериализован исходный input. Mapper не может этим способом создать body `,(0,c.jsx)(t.code,{children:`null`}),` или пустой body.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Для endpoint, которому действительно нужен `,(0,c.jsx)(t.code,{children:`null`}),`, передайте `,(0,c.jsx)(t.code,{children:`null`}),` как input без mapper-а. Для запроса без body используйте `,(0,c.jsx)(t.code,{children:`httpFetchPayload`}),`.`]}),`
+`,(0,c.jsx)(t.h3,{id:`content-type`,children:`Content-Type`}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`application/json`}),` добавляется только при отсутствии header. Custom media type сохраняется:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const patchResource = httpJsonMutationFn("/api/resource", {
+	method: "PATCH",
+	init: {
+		headers: {
+			"Content-Type": "application/merge-patch+json"
+		}
+	},
+	parse: parseResource
+});
+`})}),`
+`,(0,c.jsx)(t.h3,{id:`cache-после-mutation`,children:`Cache после mutation`}),`
+`,(0,c.jsx)(t.p,{children:`Factory не знает query keys и ничего не инвалидирует:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-tsx`,children:`const queryClient = useQueryClient();
+
+const mutation = useMutation({
+	mutationFn: updateProfile,
+	onSuccess: (updated) => {
+		queryClient.setQueryData(userKeys.detail(updated.id), updated);
+		void queryClient.invalidateQueries({ queryKey: userKeys.all });
+	}
+});
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Query cache хранит server snapshot. Не используйте object из cache как mutable form draft.`}),`
+`,(0,c.jsx)(t.h3,{id:`manual-abort-mutation`,children:`Manual abort mutation`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const controller = new AbortController();
+const promise = updateProfile(input, controller.signal);
+controller.abort();
+await promise;
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`useMutation`}),` сам не передаёт AbortSignal. Не переиспользуйте уже aborted controller.`]}),`
+`,(0,c.jsx)(t.h2,{id:`http-errors`,children:`HTTP errors`}),`
+`,(0,c.jsxs)(t.p,{children:[`Для `,(0,c.jsx)(t.code,{children:`response.ok === false`}),` обе низкоуровневые функции бросают обычный `,(0,c.jsx)(t.code,{children:`Error`}),`:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-text`,children:`HTTP error: <message>
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Если error body — непустой text, он становится message. Для JSON error object поля `,(0,c.jsx)(t.code,{children:`message`}),`, `,(0,c.jsx)(t.code,{children:`error`}),` и `,(0,c.jsx)(t.code,{children:`details`}),` не извлекаются; fallback — `,(0,c.jsx)(t.code,{children:`<status> <statusText>`}),`.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Network error/CORS/abort от глобального `,(0,c.jsx)(t.code,{children:`fetch`}),` пробрасывается без обёртки.`]}),`
+`,(0,c.jsx)(t.p,{children:`При non-2xx transport читает error body, чтобы построить message. Consumer уже не получает этот Response.`}),`
+`,(0,c.jsx)(t.p,{children:`Для JSON error object поля не анализируются:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-json`,children:`{
+	"message": "Нет доступа"
+}
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`При status `,(0,c.jsx)(t.code,{children:`403`}),` message будет fallback `,(0,c.jsx)(t.code,{children:`HTTP error: 403 Forbidden`}),`, потому что parsed payload является object, а не string.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Модуль не повторяет request. Retry policy принадлежит TanStack Query или caller. Обычный `,(0,c.jsx)(t.code,{children:`Error`}),` из `,(0,c.jsx)(t.code,{children:`httpFetch`}),` не содержит числовой status, поэтому status-aware retry требует отдельного project error contract.`]}),`
+`,(0,c.jsx)(t.h2,{id:`routeerror`,children:(0,c.jsx)(t.code,{children:`RouteError`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`throw new RouteError(404);
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Это маленький `,(0,c.jsx)(t.code,{children:`Error`}),` с числовым полем `,(0,c.jsx)(t.code,{children:`status`}),` и пустым message. `,(0,c.jsx)(t.code,{children:`httpFetch`}),` сам его не создаёт. Класс нужен для routing/error-boundary policy приложения, если оно договорилось понимать такой error.`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`async function profileLoader() {
+	const profile = await loadProfile();
+	if (!profile) throw new RouteError(404);
+	return profile;
+}
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`Object.setPrototypeOf`}),` внутри class обеспечивает надёжный `,(0,c.jsx)(t.code,{children:`instanceof RouteError`}),`. Класс не содержит response body, headers или `,(0,c.jsx)(t.code,{children:`cause`}),` и не заменяет полноценную structured transport error.`]}),`
+`,(0,c.jsx)(t.h2,{id:`тестирование`,children:`Тестирование`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import { afterEach, expect, it, vi } from "vitest";
+import {
+	httpFetchPayload,
+	httpJsonQueryFn
+} from "@ryuzaki13/react-foundation-api/http";
+
+afterEach(() => vi.unstubAllGlobals());
+
+it("разбирает JSON payload", async () => {
+	vi.stubGlobal(
+		"fetch",
+		vi.fn().mockResolvedValue(
+			new Response(JSON.stringify({ id: "u-1", name: "Анна" }), {
+				status: 200,
+				headers: { "Content-Type": "application/json" }
+			})
+		)
+	);
+
+	await expect(httpFetchPayload("/api/user")).resolves.toEqual({
+		id: "u-1",
+		name: "Анна"
+	});
+});
+
+it("отклоняет неверный runtime shape", async () => {
+	vi.stubGlobal(
+		"fetch",
+		vi.fn().mockResolvedValue(
+			new Response(JSON.stringify({ id: 10 }), {
+				status: 200,
+				headers: { "Content-Type": "application/json" }
+			})
+		)
+	);
+
+	const queryFn = httpJsonQueryFn("/api/user", { parse: parseUser });
+	await expect(queryFn()).rejects.toThrow(
+		"User response содержит неверные поля"
+	);
+});
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Проверяйте минимум:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[`string `,(0,c.jsx)(t.code,{children:`baseUrl + path`}),`;`]}),`
+`,(0,c.jsx)(t.li,{children:`Request/URL input игнорирует baseUrl;`}),`
+`,(0,c.jsxs)(t.li,{children:[`204/205 возвращает `,(0,c.jsx)(t.code,{children:`null`}),`;`]}),`
+`,(0,c.jsx)(t.li,{children:`JSON и text parsing;`}),`
+`,(0,c.jsx)(t.li,{children:`invalid JSON;`}),`
+`,(0,c.jsx)(t.li,{children:`non-2xx error message;`}),`
+`,(0,c.jsx)(t.li,{children:`explicit signal priority;`}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`x-sw-cache`}),` header;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`mapBody`}),` и JSON serialization;`]}),`
+`,(0,c.jsx)(t.li,{children:`custom Content-Type;`}),`
+`,(0,c.jsx)(t.li,{children:`feature cache strategy после mutation.`}),`
+`]}),`
+`,(0,c.jsx)(t.h2,{id:`частые-ошибки`,children:`Частые ошибки`}),`
+`,(0,c.jsx)(t.h3,{id:`generic-вместо-runtime-parser`,children:`Generic вместо runtime parser`}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`payload as User`}),` только заставляет TypeScript поверить разработчику.`]}),`
+`,(0,c.jsx)(t.h3,{id:`неверные-slashes`,children:`Неверные slashes`}),`
+`,(0,c.jsx)(t.p,{children:`URL соединяется простой конкатенацией. Придерживайтесь одной convention.`}),`
+`,(0,c.jsx)(t.h3,{id:`ожидать-sap-side-effects`,children:`Ожидать SAP side effects`}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`/http`}),` не добавляет CSRF, SSO, SAP client или OData envelope parser.`]}),`
+`,(0,c.jsxs)(t.h3,{id:`вернуть-null-из-mapbody`,children:[`Вернуть `,(0,c.jsx)(t.code,{children:`null`}),` из `,(0,c.jsx)(t.code,{children:`mapBody`})]}),`
+`,(0,c.jsxs)(t.p,{children:[`Из-за `,(0,c.jsx)(t.code,{children:`?? input`}),` будет отправлен исходный input.`]}),`
+`,(0,c.jsx)(t.h3,{id:`ожидать-automatic-invalidation`,children:`Ожидать automatic invalidation`}),`
+`,(0,c.jsx)(t.p,{children:`Mutation factory не знает query keys. Стратегию cache задаёт owner ресурса.`}),`
+`,(0,c.jsx)(t.h3,{id:`отправлять-formdata-через-json-factory`,children:`Отправлять FormData через JSON factory`}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`httpJsonMutationFn`}),` всегда вызывает `,(0,c.jsx)(t.code,{children:`JSON.stringify`}),`. Для FormData используйте `,(0,c.jsx)(t.code,{children:`httpFetch`}),`.`]}),`
+`,(0,c.jsx)(t.h2,{id:`ошибки-runtime-и-безопасность`,children:`Ошибки, runtime и безопасность`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[`TypeScript generic не валидирует сеть; используйте `,(0,c.jsx)(t.code,{children:`parse`}),`/schema guard.`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`baseUrl`}),` и path не нормализуются и не кодируются.`]}),`
+`,(0,c.jsxs)(t.li,{children:[`Authorization, cookies, CORS и retry задаёт consumer через `,(0,c.jsx)(t.code,{children:`init`}),` или внешний слой.`]}),`
+`,(0,c.jsxs)(t.li,{children:[`Модуль не делает timeout. Для него используйте `,(0,c.jsx)(t.code,{children:`AbortController`}),`.`]}),`
+`,(0,c.jsx)(t.li,{children:`Не помещайте token/secret в query string и cache key.`}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`x-sw-cache`}),` для персональных данных требует изолированной cache policy.`]}),`
+`,(0,c.jsx)(t.li,{children:`На SSR абсолютный/относительный URL и cookies должны быть настроены server runtime-ом.`}),`
+`]}),`
+`,(0,c.jsx)(t.h2,{id:`faq`,children:`FAQ`}),`
+`,(0,c.jsxs)(t.h3,{id:`чем-httpfetchpayload-отличается-от-fetchjson`,children:[`Чем `,(0,c.jsx)(t.code,{children:`httpFetchPayload`}),` отличается от `,(0,c.jsx)(t.code,{children:`fetch(...).json()`}),`?`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Он проверяет `,(0,c.jsx)(t.code,{children:`response.ok`}),`, понимает 204/205 и выбирает JSON/text по Content-Type.`]}),`
+`,(0,c.jsx)(t.h3,{id:`можно-ли-скачать-blob`,children:`Можно ли скачать Blob?`}),`
+`,(0,c.jsxs)(t.p,{children:[`Да: `,(0,c.jsx)(t.code,{children:`httpFetch`}),`, затем `,(0,c.jsx)(t.code,{children:`response.blob()`}),`.`]}),`
+`,(0,c.jsx)(t.h3,{id:`можно-ли-отправить-formdata`,children:`Можно ли отправить FormData?`}),`
+`,(0,c.jsxs)(t.p,{children:[`Да через `,(0,c.jsx)(t.code,{children:`httpFetch`}),`. JSON mutation factory для этого не подходит.`]}),`
+`,(0,c.jsx)(t.h3,{id:`как-задать-timeout`,children:`Как задать timeout?`}),`
+`,(0,c.jsxs)(t.p,{children:[`Передайте signal от `,(0,c.jsx)(t.code,{children:`AbortSignal.timeout(...)`}),` в поддерживаемой среде или используйте `,(0,c.jsx)(t.code,{children:`AbortController`}),`.`]}),`
+`,(0,c.jsx)(t.h3,{id:`почему-json-query-может-получить-textnull`,children:`Почему JSON query может получить text/null?`}),`
+`,(0,c.jsxs)(t.p,{children:[`Low-level parser допускает эти shapes, а обязательный `,(0,c.jsx)(t.code,{children:`parse`}),` определяет валидный result endpoint-а.`]}),`
+`,(0,c.jsx)(t.h3,{id:`где-хранить-query-keys`,children:`Где хранить query keys?`}),`
+`,(0,c.jsxs)(t.p,{children:[`Рядом с public API entity/feature либо в `,(0,c.jsx)(t.code,{children:`/resource`}),`, если нужен generic descriptor.`]}),`
+`,(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:`httpFetch`})}),(0,c.jsxs)(t.td,{children:[`Успешный `,(0,c.jsx)(t.code,{children:`Response`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`httpFetchPayload`})}),(0,c.jsxs)(t.td,{children:[`JSON/text/`,(0,c.jsx)(t.code,{children:`null`}),` как `,(0,c.jsx)(t.code,{children:`unknown`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`httpJsonQueryFn`})}),(0,c.jsx)(t.td,{children:`Query-compatible async function`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`httpJsonMutationFn`})}),(0,c.jsx)(t.td,{children:`Mutation-compatible async function`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`RouteError`})}),(0,c.jsxs)(t.td,{children:[`Error с `,(0,c.jsx)(t.code,{children:`status`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`HttpRequestOptions`})}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`baseUrl`}),` и `,(0,c.jsx)(t.code,{children:`init`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`HttpQueryFnOptions`})}),(0,c.jsxs)(t.td,{children:[`Request options + `,(0,c.jsx)(t.code,{children:`swCache`}),` + `,(0,c.jsx)(t.code,{children:`parse`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`HttpMutationFnOptions`})}),(0,c.jsx)(t.td,{children:`Request options + method/body mapper/parse`})]})]})]})]})}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};