@ryuzaki13/react-foundation-ui 1.8.10 → 1.8.12

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

@@ -0,0 +1,264 @@
+import{n as e}from"./rolldown-runtime-DkW27tQK.js";import{n as t}from"./iframe-FSp_AjJa.js";import{i as n,r}from"./react-Bl2r1tuC.js";import{l as i,m as a}from"./blocks-B5YBxaaS.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/Infrastructure/PWA`}),`
+`,(0,c.jsx)(t.h1,{id:`pwa`,children:`PWA`}),`
+`,(0,c.jsx)(t.p,{children:`Модуль PWA состоит из двух публичных входов с разной ответственностью:`}),`
+`,(0,c.jsxs)(t.table,{children:[(0,c.jsx)(t.thead,{children:(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.th,{children:`Import path`}),(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:`@ryuzaki13/react-foundation-lib/pwa`})}),(0,c.jsx)(t.td,{children:`React-hook обновления Service Worker и все функции cache policy`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`@ryuzaki13/react-foundation-lib/pwa/sw-cache-policy`})}),(0,c.jsxs)(t.td,{children:[`Только чистый parser/builder политики `,(0,c.jsx)(t.code,{children:`x-sw-cache`}),`, без React update-flow`]})]})]})]}),`
+`,(0,c.jsxs)(t.p,{children:[`Используйте точный subpath. Внутренний файл `,(0,c.jsx)(t.code,{children:`serviceWorker`}),` не является самостоятельным публичным export, даже если отдельные функции используются самим hook.`]}),`
+`,(0,c.jsx)(t.h2,{id:`установка`,children:`Установка`}),`
+`,(0,c.jsxs)(t.p,{children:[`Для `,(0,c.jsx)(t.code,{children:`useServiceWorkerUpdate`}),` нужен React. Cache policy не имеет React-зависимости.`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-bash`,children:`npm install @ryuzaki13/react-foundation-lib react
+`})}),`
+`,(0,c.jsx)(t.h2,{id:`часть-1-обновление-service-worker`,children:`Часть 1. Обновление Service Worker`}),`
+`,(0,c.jsx)(t.h3,{id:`задача-hook`,children:`Задача hook`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import { useServiceWorkerUpdate } from "@ryuzaki13/react-foundation-lib/pwa";
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Hook:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsx)(t.li,{children:`регистрирует Service Worker в production;`}),`
+`,(0,c.jsx)(t.li,{children:`проверяет обновление сразу после запуска;`}),`
+`,(0,c.jsx)(t.li,{children:`затем повторяет проверку каждые 5 минут;`}),`
+`,(0,c.jsx)(t.li,{children:`автоматически применяет накопившееся обновление вскоре после обычного открытия или reload;`}),`
+`,(0,c.jsx)(t.li,{children:`для обновления, найденного во время активной сессии, сообщает UI о доступной версии;`}),`
+`,(0,c.jsx)(t.li,{children:`очищает interval, startup timeout и подписку при размонтировании.`}),`
+`]}),`
+`,(0,c.jsx)(t.h3,{id:`быстрый-старт`,children:`Быстрый старт`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-tsx`,children:`import { useServiceWorkerUpdate } from "@ryuzaki13/react-foundation-lib/pwa";
+
+export function ServiceWorkerUpdateBanner() {
+	const { hasUpdate, applyUpdate, dismiss } = useServiceWorkerUpdate();
+
+	if (!hasUpdate) {
+		return null;
+	}
+
+	return (
+		<aside role="status" aria-live="polite">
+			<p>Доступна новая версия приложения.</p>
+			<button type="button" onClick={applyUpdate}>
+				Обновить
+			</button>
+			<button type="button" onClick={dismiss}>
+				Позже
+			</button>
+		</aside>
+	);
+}
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Разместите этот компонент один раз в корневом client shell приложения. Несколько экземпляров создадут несколько периодических проверок.`}),`
+`,(0,c.jsx)(t.h3,{id:`возвращаемое-значение`,children:`Возвращаемое значение`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const {
+	hasUpdate, // boolean
+	applyUpdate, // () => boolean
+	dismiss // () => void
+} = useServiceWorkerUpdate();
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`hasUpdate`}),` становится `,(0,c.jsx)(t.code,{children:`true`}),`, когда найден registration с `,(0,c.jsx)(t.code,{children:`waiting`}),` worker.`]}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`applyUpdate()`}),`:`]}),`
+`,(0,c.jsxs)(t.ol,{children:[`
+`,(0,c.jsxs)(t.li,{children:[`отправляет waiting worker сообщение `,(0,c.jsx)(t.code,{children:`{ type: "SKIP_WAITING" }`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`запоминает reload в `,(0,c.jsx)(t.code,{children:`sessionStorage`}),`;`]}),`
+`,(0,c.jsx)(t.li,{children:`ожидает смену controller и перезагружает страницу;`}),`
+`,(0,c.jsxs)(t.li,{children:[`если другой клиент уже активировал worker и `,(0,c.jsx)(t.code,{children:`waiting`}),` исчез, выполняет fallback reload.`]}),`
+`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Возвращается `,(0,c.jsx)(t.code,{children:`true`}),`, если применение или fallback reload запущены, иначе `,(0,c.jsx)(t.code,{children:`false`}),`.`]}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`dismiss()`}),` только скрывает текущий баннер. Он не удаляет waiting worker, не отменяет обновление и не запрещает следующей проверке снова показать баннер.`]}),`
+`,(0,c.jsx)(t.h2,{id:`требования-к-service-worker-приложения`,children:`Требования к Service Worker приложения`}),`
+`,(0,c.jsx)(t.p,{children:`Библиотека управляет клиентской стороной, но сам файл worker принадлежит приложению. Для полного update-flow он должен выполнять два контракта.`}),`
+`,(0,c.jsxs)(t.h3,{id:`обработать-skip_waiting`,children:[`Обработать `,(0,c.jsx)(t.code,{children:`SKIP_WAITING`})]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`self.addEventListener("message", (event) => {
+	if (event.data?.type === "SKIP_WAITING") {
+		void self.skipWaiting();
+	}
+});
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Без этого нажатие «Обновить» не активирует ожидающий worker немедленно.`}),`
+`,(0,c.jsx)(t.h3,{id:`сообщить-вкладкам-об-активации`,children:`Сообщить вкладкам об активации`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`self.addEventListener("activate", (event) => {
+	event.waitUntil(
+		(async () => {
+			await self.clients.claim();
+			const clients = await self.clients.matchAll({ type: "window" });
+
+			for (const client of clients) {
+				client.postMessage({ type: "SW_ACTIVATED_BY_CLIENT" });
+			}
+		})()
+	);
+});
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Это сообщение помогает синхронно перезагрузить другие открытые вкладки. Конкретная стратегия `,(0,c.jsx)(t.code,{children:`claim`}),` и рассылки должна соответствовать архитектуре worker приложения.`]}),`
+`,(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 __SERVICE_WORKER_SCOPE__: string;
+declare const __SERVICE_WORKER_URL__: string;
+declare const __SERVICE_WORKER_UPDATE_RELOAD_COUNT_KEY__: string;
+declare const __SERVICE_WORKER_MAX_AUTO_UPDATE_RELOADS__: number;
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Пример для Vite:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import { defineConfig } from "vite";
+
+export default defineConfig(({ mode }) => ({
+	define: {
+		__DEV__: JSON.stringify(mode !== "production"),
+		__SERVICE_WORKER_SCOPE__: JSON.stringify("/app/"),
+		__SERVICE_WORKER_URL__: JSON.stringify("/app/sw.js"),
+		__SERVICE_WORKER_UPDATE_RELOAD_COUNT_KEY__: JSON.stringify("my-app:sw-update-reload-count"),
+		__SERVICE_WORKER_MAX_AUTO_UPDATE_RELOADS__: JSON.stringify(3)
+	}
+}));
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Значения должны быть литералами в собранном клиентском коде. Если сборщик не заменит идентификаторы, приложение получит `,(0,c.jsx)(t.code,{children:`ReferenceError`}),`.`]}),`
+`,(0,c.jsx)(t.h3,{id:`для-чего-нужен-предел-auto-reload`,children:`Для чего нужен предел auto reload`}),`
+`,(0,c.jsxs)(t.p,{children:[`После открытия/reload hook даёт обновлениям 30 секунд на автоматическое применение. Счётчик в sessionStorage ограничивает цепочку перезагрузок значением `,(0,c.jsx)(t.code,{children:`__SERVICE_WORKER_MAX_AUTO_UPDATE_RELOADS__`}),`.`]}),`
+`,(0,c.jsx)(t.p,{children:`Это защищает от бесконечного reload-loop при проблемном деплое. После 30-секундного startup-окна счётчик очищается, а дальнейшие обновления показываются через UI.`}),`
+`,(0,c.jsx)(t.h2,{id:`development-ssr-и-browser-boundary`,children:`Development, SSR и browser boundary`}),`
+`,(0,c.jsxs)(t.p,{children:[`В режиме `,(0,c.jsx)(t.code,{children:`__DEV__ === true`}),` effect сразу завершается: Service Worker не регистрируется и интервал не запускается.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Hook использует `,(0,c.jsx)(t.code,{children:`window`}),`, `,(0,c.jsx)(t.code,{children:`navigator`}),`, `,(0,c.jsx)(t.code,{children:`performance`}),`, `,(0,c.jsx)(t.code,{children:`sessionStorage`}),` и API Service Worker. Подключайте его только в браузерном React-дереве. Сам effect не выполняется при SSR, но compile-time константы всё равно должны быть доступны в bundle.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Ошибки регистрации и проверки логируются, а наружу не выбрасываются. Отсутствие поддержки `,(0,c.jsx)(t.code,{children:`navigator.serviceWorker`}),` приводит к спокойному `,(0,c.jsx)(t.code,{children:`hasUpdate: false`}),`.`]}),`
+`,(0,c.jsx)(t.h2,{id:`жизненный-цикл-обновления`,children:`Жизненный цикл обновления`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-text`,children:`mount
+  → register URL + scope
+  → проверить existing waiting worker
+  → вызвать registration.update()
+  → если update найден в первые 30 секунд после navigate/reload:
+       автоматически отправить SKIP_WAITING, пока не исчерпан лимит
+  → иначе установить hasUpdate = true
+  → пользователь выбирает applyUpdate или dismiss
+  → каждые 5 минут новая проверка
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Навигация считается startup-кандидатом только для `,(0,c.jsx)(t.code,{children:`PerformanceNavigationTiming.type`}),` со значением `,(0,c.jsx)(t.code,{children:`"navigate"`}),` или `,(0,c.jsx)(t.code,{children:`"reload"`}),`.`]}),`
+`,(0,c.jsx)(t.h2,{id:`часть-2-политика-sw-кэша`,children:`Часть 2. Политика SW-кэша`}),`
+`,(0,c.jsx)(t.p,{children:`Эта часть описывает компактное текстовое значение, которое transport и Service Worker могут использовать как согласованный cache profile.`}),`
+`,(0,c.jsx)(t.p,{children:`Для кода без React импортируйте узкий subpath:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import {
+	buildSwCachePolicyValue,
+	normalizeSwCacheName,
+	parseSwCachePolicy,
+	resolveSwCacheCacheNameByPolicy,
+	type SwCachePolicyDraft
+} from "@ryuzaki13/react-foundation-lib/pwa/sw-cache-policy";
+`})}),`
+`,(0,c.jsx)(t.h2,{id:`формат-политики`,children:`Формат политики`}),`
+`,(0,c.jsx)(t.p,{children:`Поддерживаются три режима:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-text`,children:`off
+ttl=<duration>[;max=<count>][;name=<name>]
+bust=<duration>[;max=<count>][;name=<name>]
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Примеры:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-text`,children:`off
+ttl=10m
+ttl=24h;max=200;name=references
+bust=7d;name=metadata
+ttl=forever;max=50
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Опции разрешено разделять `,(0,c.jsx)(t.code,{children:`;`}),` или `,(0,c.jsx)(t.code,{children:`,`}),`. Имена ключей и режимы разбираются без учёта регистра.`]}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`ttl`}),` и `,(0,c.jsx)(t.code,{children:`bust`}),` — метки профиля. Конкретное отличие их runtime-поведения реализует Service Worker/transport потребителя; parser только возвращает разобранный `,(0,c.jsx)(t.code,{children:`mode`}),`.`]}),`
+`,(0,c.jsx)(t.h2,{id:`единицы-времени`,children:`Единицы времени`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type SwCacheDurationUnit = "ms" | "s" | "m" | "h" | "d";
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Поддерживаются положительные целые и десятичные значения, например `,(0,c.jsx)(t.code,{children:`500ms`}),`, `,(0,c.jsx)(t.code,{children:`1.5h`}),`, `,(0,c.jsx)(t.code,{children:`7d`}),`. Максимальный конечный TTL — 365 дней. Специальное значение `,(0,c.jsx)(t.code,{children:`forever`}),` превращается в `,(0,c.jsx)(t.code,{children:`Infinity`}),`.`]}),`
+`,(0,c.jsx)(t.p,{children:`Ноль, отрицательное число, запись без единицы, scientific notation и срок больше 365 дней считаются неверными.`}),`
+`,(0,c.jsx)(t.h2,{id:`parseswcachepolicyvalue`,children:(0,c.jsx)(t.code,{children:`parseSwCachePolicy(value)`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const policy = parseSwCachePolicy("ttl=10m;max=200;name=UI Data");
+
+// {
+//   mode: "ttl",
+//   amount: 10,
+//   unit: "m",
+//   name: "ui-data",
+//   maxEntries: 200,
+//   resolvedMaxEntries: 200,
+//   ttlMs: 600000,
+//   cacheName: "odata-ui-data-10m-max200"
+// }
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Пустое или полностью неверное значение возвращает `,(0,c.jsx)(t.code,{children:`undefined`}),`. Строка `,(0,c.jsx)(t.code,{children:`off`}),` возвращает `,(0,c.jsx)(t.code,{children:`{ mode: "off" }`}),`.`]}),`
+`,(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:`Допустимые ключи`})]})}),(0,c.jsxs)(t.tbody,{children:[(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Максимум записей`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`maxEntries`}),`, `,(0,c.jsx)(t.code,{children:`max`}),`, `,(0,c.jsx)(t.code,{children:`entries`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Имя профиля`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`cacheName`}),`, `,(0,c.jsx)(t.code,{children:`cache`}),`, `,(0,c.jsx)(t.code,{children:`name`})]})]})]})]}),`
+`,(0,c.jsxs)(t.p,{children:[`Неизвестные опции игнорируются. Если одна опция повторяется, используется последнее значение из-за семантики `,(0,c.jsx)(t.code,{children:`Map`}),`.`]}),`
+`,(0,c.jsx)(t.h3,{id:`maxentries`,children:(0,c.jsx)(t.code,{children:`maxEntries`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Допустимо положительное целое число. Значение ограничивается максимумом `,(0,c.jsx)(t.code,{children:`5000`}),`. Неверное значение не делает всю политику неверной: оно просто отбрасывается.`]}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`resolvedMaxEntries`}),` всегда содержит фактический лимит для `,(0,c.jsx)(t.code,{children:`ttl`}),`/`,(0,c.jsx)(t.code,{children:`bust`}),`: переданный либо значение по умолчанию `,(0,c.jsx)(t.code,{children:`100`}),`.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`При этом cache name включает суффикс `,(0,c.jsx)(t.code,{children:`-maxN`}),` только для явно переданного валидного лимита. Дефолтные `,(0,c.jsx)(t.code,{children:`100`}),` в имени не записываются.`]}),`
+`,(0,c.jsx)(t.h2,{id:`normalizeswcachenamevalue`,children:(0,c.jsx)(t.code,{children:`normalizeSwCacheName(value)`})}),`
+`,(0,c.jsx)(t.p,{children:`Нормализует имя профиля:`}),`
+`,(0,c.jsxs)(t.ol,{children:[`
+`,(0,c.jsx)(t.li,{children:`удаляет пробелы по краям;`}),`
+`,(0,c.jsx)(t.li,{children:`переводит в нижний регистр;`}),`
+`,(0,c.jsxs)(t.li,{children:[`заменяет группы недопустимых символов на `,(0,c.jsx)(t.code,{children:`-`}),`;`]}),`
+`,(0,c.jsx)(t.li,{children:`удаляет крайние дефисы;`}),`
+`,(0,c.jsxs)(t.li,{children:[`возвращает `,(0,c.jsx)(t.code,{children:`undefined`}),`, если ничего не осталось.`]}),`
+`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Разрешены латинские буквы, цифры, `,(0,c.jsx)(t.code,{children:`_`}),` и `,(0,c.jsx)(t.code,{children:`-`}),`.`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`normalizeSwCacheName(" UI Data / Main "); // "ui-data-main"
+normalizeSwCacheName("---"); // undefined
+`})}),`
+`,(0,c.jsx)(t.h2,{id:`resolveswcachecachenamebypolicyvalue`,children:(0,c.jsx)(t.code,{children:`resolveSwCacheCacheNameByPolicy(value)`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Возвращает вычисленное имя cache только для валидных режимов `,(0,c.jsx)(t.code,{children:`ttl`}),` и `,(0,c.jsx)(t.code,{children:`bust`}),`.`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`resolveSwCacheCacheNameByPolicy("ttl=24h;name=ref");
+// "odata-ref-24h"
+
+resolveSwCacheCacheNameByPolicy("off"); // undefined
+resolveSwCacheCacheNameByPolicy("ttl=wrong"); // undefined
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Имя — устойчивый технический профиль, но формат может быть частью cache-versioning. Не собирайте его вручную.`}),`
+`,(0,c.jsx)(t.h2,{id:`buildswcachepolicyvaluedraft`,children:(0,c.jsx)(t.code,{children:`buildSwCachePolicyValue(draft)`})}),`
+`,(0,c.jsx)(t.p,{children:`Собирает каноническую строку из данных формы.`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const draft: SwCachePolicyDraft = {
+	mode: "ttl",
+	amount: 10,
+	unit: "m",
+	name: "UI Data",
+	maxEntries: 200
+};
+
+buildSwCachePolicyValue(draft);
+// "ttl=10m;max=200;name=ui-data"
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Правила builder:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[`для `,(0,c.jsx)(t.code,{children:`off`}),` всегда возвращает `,(0,c.jsx)(t.code,{children:`"off"`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`неверный `,(0,c.jsx)(t.code,{children:`amount`}),` заменяет на `,(0,c.jsx)(t.code,{children:`24`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`отсутствующую `,(0,c.jsx)(t.code,{children:`unit`}),` заменяет на `,(0,c.jsx)(t.code,{children:`h`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`неверный `,(0,c.jsx)(t.code,{children:`maxEntries`}),` отбрасывает, больше `,(0,c.jsx)(t.code,{children:`5000`}),` ограничивает;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`имя нормализует через `,(0,c.jsx)(t.code,{children:`normalizeSwCacheName`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`порядок опций всегда `,(0,c.jsx)(t.code,{children:`max`}),`, затем `,(0,c.jsx)(t.code,{children:`name`}),`.`]}),`
+`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Builder не ограничивает вычисленный срок 365 днями. Например, draft `,(0,c.jsx)(t.code,{children:`400d`}),` будет собран в строку, но parser затем вернёт `,(0,c.jsx)(t.code,{children:`undefined`}),`. Если данные приходят из свободной формы, проверьте результат повторным `,(0,c.jsx)(t.code,{children:`parseSwCachePolicy`}),` перед сохранением.`]}),`
+`,(0,c.jsx)(t.h2,{id:`пример-формы-настройки`,children:`Пример формы настройки`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`function savePolicy(draft: SwCachePolicyDraft) {
+	const value = buildSwCachePolicyValue(draft);
+	const parsed = parseSwCachePolicy(value);
+
+	if (!parsed) {
+		throw new Error("Не удалось собрать допустимую cache policy");
+	}
+
+	return value;
+}
+`})}),`
+`,(0,c.jsx)(t.h2,{id:`безопасность-кэша`,children:`Безопасность кэша`}),`
+`,(0,c.jsxs)(t.p,{children:[`Политика только описывает срок и профиль. Она не определяет, `,(0,c.jsx)(t.strong,{children:`что разрешено кэшировать`}),`.`]}),`
+`,(0,c.jsx)(t.p,{children:`Service Worker приложения обязан отдельно учитывать:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsx)(t.li,{children:`пользователя, tenant и authorization context;`}),`
+`,(0,c.jsx)(t.li,{children:`HTTP-метод: mutation-запросы обычно не кэшируются;`}),`
+`,(0,c.jsx)(t.li,{children:`чувствительные персональные данные;`}),`
+`,(0,c.jsx)(t.li,{children:`response status и content type;`}),`
+`,(0,c.jsx)(t.li,{children:`очистку cache при logout;`}),`
+`,(0,c.jsx)(t.li,{children:`версионирование схемы ответа.`}),`
+`]}),`
+`,(0,c.jsx)(t.p,{children:`Не используйте общий cache name для ответов разных пользователей, если ключ cache не содержит безопасно разделяющий контекст.`}),`
+`,(0,c.jsx)(t.h2,{id:`частые-ошибки`,children:`Частые ошибки`}),`
+`,(0,c.jsxs)(t.h3,{id:`импорт-внутреннего-serviceworkerts`,children:[`Импорт внутреннего `,(0,c.jsx)(t.code,{children:`serviceWorker.ts`})]}),`
+`,(0,c.jsxs)(t.p,{children:[`Он не объявлен в `,(0,c.jsx)(t.code,{children:`package.json#exports`}),`. Публичный update API — `,(0,c.jsx)(t.code,{children:`useServiceWorkerUpdate`}),` из `,(0,c.jsx)(t.code,{children:`/pwa`}),`.`]}),`
+`,(0,c.jsxs)(t.h3,{id:`ожидать-что-dismiss-отменит-update`,children:[`Ожидать, что `,(0,c.jsx)(t.code,{children:`dismiss()`}),` отменит update`]}),`
+`,(0,c.jsx)(t.p,{children:`Waiting worker остаётся установленным. Следующая проверка может снова показать UI.`}),`
+`,(0,c.jsxs)(t.h3,{id:`не-обработать-skip_waiting-в-worker`,children:[`Не обработать `,(0,c.jsx)(t.code,{children:`SKIP_WAITING`}),` в worker`]}),`
+`,(0,c.jsx)(t.p,{children:`Кнопка применения отправит сообщение, но worker не активируется до обычного lifecycle браузера.`}),`
+`,(0,c.jsx)(t.h3,{id:`путать-ttl-parser-с-cache-implementation`,children:`Путать TTL parser с cache implementation`}),`
+`,(0,c.jsx)(t.p,{children:`Функции policy не читают Cache Storage, не перехватывают fetch и не удаляют записи. Это обязанность Service Worker.`}),`
+`,(0,c.jsxs)(t.h3,{id:`считать-forever-безопасным-default`,children:[`Считать `,(0,c.jsx)(t.code,{children:`forever`}),` безопасным default`]}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`ttlMs: Infinity`}),` требует явной стратегии bust/invalidation. Без неё клиент может долго видеть устаревшие данные.`]}),`
+`,(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:`Публичный path`}),(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:`useServiceWorkerUpdate()`})}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`/pwa`})}),(0,c.jsx)(t.td,{children:`Регистрация, проверка и UI-состояние обновления SW`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`parseSwCachePolicy()`})}),(0,c.jsx)(t.td,{children:`оба`}),(0,c.jsx)(t.td,{children:`Разобрать текстовую политику`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`buildSwCachePolicyValue()`})}),(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:`normalizeSwCacheName()`})}),(0,c.jsx)(t.td,{children:`оба`}),(0,c.jsx)(t.td,{children:`Подготовить безопасную часть cache name`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`resolveSwCacheCacheNameByPolicy()`})}),(0,c.jsx)(t.td,{children:`оба`}),(0,c.jsx)(t.td,{children:`Получить имя cache из валидной политики`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`ParsedSwCachePolicy`})}),(0,c.jsx)(t.td,{children:`оба`}),(0,c.jsx)(t.td,{children:`Тип разобранного результата`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`SwCachePolicyDraft`})}),(0,c.jsx)(t.td,{children:`оба`}),(0,c.jsx)(t.td,{children:`Тип данных формы/builder`})]})]})]})]})}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-DJlxGqOL.js → README-DIbfpC-2.js}

@@ -1,4 +1,4 @@
-import{n as e}from"./rolldown-runtime-DkW27tQK.js";import{n as t}from"./iframe-BOu-P2xF.js";import{i as n,r}from"./react-Bl2r1tuC.js";import{l as i,m as a}from"./blocks-Ddv0ZNIG.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-FSp_AjJa.js";import{i as n,r}from"./react-Bl2r1tuC.js";import{l as i,m as a}from"./blocks-B5YBxaaS.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-D5VR4x0m.js → README-DJHVgrpj.js}

@@ -1,4 +1,4 @@
-import{n as e}from"./rolldown-runtime-DkW27tQK.js";import{n as t}from"./iframe-BOu-P2xF.js";import{i as n,r}from"./react-Bl2r1tuC.js";import{l as i,m as a}from"./blocks-Ddv0ZNIG.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/Pipeline`}),`
+import{n as e}from"./rolldown-runtime-DkW27tQK.js";import{n as t}from"./iframe-FSp_AjJa.js";import{i as n,r}from"./react-Bl2r1tuC.js";import{l as i,m as a}from"./blocks-B5YBxaaS.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/Pipeline`}),`
 `,(0,c.jsx)(t.h1,{id:`formatter-pipeline`,children:`Formatter pipeline`}),`
 `,(0,c.jsx)(t.p,{children:`Formatter pipeline — конфигурируемая последовательность преобразований значения ячейки. Она умеет:`}),`
 `,(0,c.jsxs)(t.ul,{children:[`

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

@@ -0,0 +1,124 @@
+import{n as e}from"./rolldown-runtime-DkW27tQK.js";import{n as t}from"./iframe-FSp_AjJa.js";import{i as n,r}from"./react-Bl2r1tuC.js";import{l as i,m as a}from"./blocks-B5YBxaaS.js";function o(e){let t={a:`a`,blockquote:`blockquote`,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 API/SAP/Transport Requests`}),`
+`,(0,c.jsxs)(t.h1,{id:`sap-transport-requests-через-ryuzaki13react-foundation-apitransport`,children:[`SAP transport requests через `,(0,c.jsx)(t.code,{children:`@ryuzaki13/react-foundation-api/transport`})]}),`
+`,(0,c.jsx)(t.p,{children:`Модуль получает transport requests текущего пользователя из SAP UI2 OData endpoints и нормализует workbench/customizing records.`}),`
+`,(0,c.jsxs)(t.blockquote,{children:[`
+`,(0,c.jsxs)(t.p,{children:[`Здесь слово `,(0,c.jsx)(t.code,{children:`transport`}),` означает SAP transport request. Это не generic HTTP transport. Для обычного HTTP используйте `,(0,c.jsx)(t.a,{href:`../http/README.mdx`,children:(0,c.jsx)(t.code,{children:`/http`})}),`, для SAP/OData transport infrastructure — `,(0,c.jsx)(t.a,{href:`../odata/README.mdx`,children:(0,c.jsx)(t.code,{children:`/odata`})}),`.`]}),`
+`]}),`
+`,(0,c.jsx)(t.h2,{id:`импорт`,children:`Импорт`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import {
+	fetchCustomizingTransportRequests,
+	fetchTransportRequests,
+	fetchUserTransportRequests,
+	fetchWorkbenchTransportRequests,
+	getTransportRequestKey,
+	normalizeTransportRequests,
+	transportRequestKeys
+} from "@ryuzaki13/react-foundation-api/transport";
+
+import type {
+	TransportRequest,
+	TransportRequestRaw,
+	TransportRequestScope,
+	TransportRequestType,
+	UserTransportRequests
+} from "@ryuzaki13/react-foundation-api/transport";
+`})}),`
+`,(0,c.jsx)(t.h2,{id:`быстрый-старт`,children:`Быстрый старт`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const requests = await fetchTransportRequests("workbench");
+
+for (const request of requests) {
+	console.log(request.id, request.text);
+}
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Scopes:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type TransportRequestType = "workbench" | "customizing";
+type TransportRequestScope = TransportRequestType | "all";
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Без аргумента загружается только `,(0,c.jsx)(t.code,{children:`workbench`}),`.`]}),`
+`,(0,c.jsx)(t.h2,{id:`fetch-functions`,children:`Fetch functions`}),`
+`,(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:`Endpoint`}),(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:`fetchWorkbenchTransportRequests`})}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`/TRANSPORT/WorkbenchRequests`})}),(0,c.jsx)(t.td,{children:`workbench array`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`fetchCustomizingTransportRequests`})}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`/TRANSPORT/CustomizingRequests`})}),(0,c.jsx)(t.td,{children:`customizing array`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`fetchUserTransportRequests`})}),(0,c.jsx)(t.td,{children:`Оба endpoint параллельно`}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`{ workbench, customizing, all }`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`fetchTransportRequests(scope)`})}),(0,c.jsx)(t.td,{children:`Endpoint по scope`}),(0,c.jsx)(t.td,{children:`единый array`})]})]})]}),`
+`,(0,c.jsxs)(t.p,{children:[`Используется base URL `,(0,c.jsx)(t.code,{children:`odataUi2`}),`: в dev/preview он направлен через настроенный DP0/UI2 proxy, в production — `,(0,c.jsx)(t.code,{children:`/sap/opu/odata/UI2`}),`.`]}),`
+`,(0,c.jsx)(t.p,{children:`Запросы наследуют policy OData transport:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`credentials: include`}),`;`]}),`
+`,(0,c.jsx)(t.li,{children:`SAP language/client headers;`}),`
+`,(0,c.jsx)(t.li,{children:`SSO detection/recovery;`}),`
+`,(0,c.jsx)(t.li,{children:`OData V2 envelope parsing;`}),`
+`,(0,c.jsx)(t.li,{children:`HTTP error handling.`}),`
+`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Если один из двух запросов `,(0,c.jsx)(t.code,{children:`fetchUserTransportRequests`}),` завершился ошибкой, `,(0,c.jsx)(t.code,{children:`Promise.all`}),` отклоняется и частичный object не возвращается.`]}),`
+`,(0,c.jsx)(t.h2,{id:`результат`,children:`Результат`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`interface TransportRequest {
+	id: string;
+	type: "workbench" | "customizing";
+	text: string;
+	isDefaultRequest: boolean;
+}
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`all`}),` формируется как workbench records, затем customizing records:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`interface UserTransportRequests {
+	workbench: TransportRequest[];
+	customizing: TransportRequest[];
+	all: TransportRequest[];
+}
+`})}),`
+`,(0,c.jsx)(t.h2,{id:`normalizetransportrequests`,children:(0,c.jsx)(t.code,{children:`normalizeTransportRequests`})}),`
+`,(0,c.jsx)(t.p,{children:`Функция полезна отдельно для тестов или custom transport:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const normalized = normalizeTransportRequests(
+	[
+		{ id: " DEVK900001 ", description: " Исправление ", isDefaultRequest: true },
+		{ id: "", description: "Без номера" },
+		{ id: "DEVK900001", description: "Дубликат" }
+	],
+	"workbench"
+);
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Результат содержит одну запись `,(0,c.jsx)(t.code,{children:`DEVK900001`}),`.`]}),`
+`,(0,c.jsx)(t.p,{children:`Алгоритм:`}),`
+`,(0,c.jsxs)(t.ol,{children:[`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`id`}),` нормализуется как text с trim.`]}),`
+`,(0,c.jsxs)(t.li,{children:[`Запись без непустого `,(0,c.jsx)(t.code,{children:`id`}),` удаляется.`]}),`
+`,(0,c.jsxs)(t.li,{children:[`Дубликаты `,(0,c.jsx)(t.code,{children:`id`}),` внутри одного input удаляются, сохраняется первый.`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`description`}),` нормализуется с trim; отсутствие превращается в пустую строку.`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`type`}),` берётся из второго аргумента для всех records.`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`isDefaultRequest`}),` равен `,(0,c.jsx)(t.code,{children:`true`}),` только при входном значении `,(0,c.jsx)(t.code,{children:`true`}),`.`]}),`
+`,(0,c.jsx)(t.li,{children:`Порядок первых уникальных records сохраняется.`}),`
+`]}),`
+`,(0,c.jsx)(t.p,{children:`Нормализация не изменяет исходный array/objects.`}),`
+`,(0,c.jsx)(t.h2,{id:`query-keys`,children:`Query keys`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`transportRequestKeys.all;
+// ["transportRequests"]
+
+transportRequestKeys.list();
+// ["transportRequests", "workbench"]
+
+transportRequestKeys.list("all");
+// ["transportRequests", "all"]
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Пример с TanStack Query:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-tsx`,children:`const scope: TransportRequestScope = "all";
+
+const query = useQuery({
+	queryKey: transportRequestKeys.list(scope),
+	queryFn: () => fetchTransportRequests(scope)
+});
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Factory ключей не создаёт query options и не передаёт AbortSignal; lifecycle запроса настраивает consumer.`}),`
+`,(0,c.jsx)(t.h2,{id:`stable-key-отдельной-записи`,children:`Stable key отдельной записи`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`getTransportRequestKey({ type: "workbench", id: "DEVK900001" });
+// "workbench:DEVK900001"
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Включение `,(0,c.jsx)(t.code,{children:`type`}),` предотвращает collision одинаковых ID из разных списков. Функция не escaping-ит `,(0,c.jsx)(t.code,{children:`:`}),`; SAP transport ID обычно не содержит этот символ.`]}),`
+`,(0,c.jsxs)(t.h2,{id:`отличие-от-adt`,children:[`Отличие от `,(0,c.jsx)(t.code,{children:`/adt`})]}),`
+`,(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.jsx)(t.code,{children:`/transport`})}),(0,c.jsx)(t.th,{children:(0,c.jsx)(t.code,{children:`/adt`})})]})}),(0,c.jsxs)(t.tbody,{children:[(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Backend`}),(0,c.jsx)(t.td,{children:`SAP UI2 OData`}),(0,c.jsx)(t.td,{children:`SAP ADT CTS`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Формат`}),(0,c.jsx)(t.td,{children:`JSON/OData envelope`}),(0,c.jsx)(t.td,{children:`XML`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Категории`}),(0,c.jsx)(t.td,{children:`workbench/customizing`}),(0,c.jsx)(t.td,{children:`Общие ADT headers`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Parser`}),(0,c.jsx)(t.td,{children:`OData transport`}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`fast-xml-parser`})})]})]})]}),`
+`,(0,c.jsx)(t.p,{children:`Не объединяйте records автоматически: контракты endpoint и значения полей различаются.`}),`
+`,(0,c.jsx)(t.h2,{id:`ошибки-и-ограничения`,children:`Ошибки и ограничения`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsx)(t.li,{children:`Модуль только читает requests; он не создаёт, не освобождает и не импортирует transport.`}),`
+`,(0,c.jsx)(t.li,{children:`Authorization определяется SAP backend.`}),`
+`,(0,c.jsxs)(t.li,{children:[`Пустой/falsy payload endpoint превращается в `,(0,c.jsx)(t.code,{children:`[]`}),`; HTTP/SSO errors пробрасываются.`]}),`
+`,(0,c.jsx)(t.li,{children:`Нет автоматической TanStack Query cache policy — используйте экспортированные keys.`}),`
+`,(0,c.jsx)(t.li,{children:`Runtime требует настроенного SAP proxy/base URLs и cookies.`}),`
+`]}),`
+`,(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:`Exports`})]})}),(0,c.jsxs)(t.tbody,{children:[(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Fetch`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`fetchWorkbenchTransportRequests`}),`, `,(0,c.jsx)(t.code,{children:`fetchCustomizingTransportRequests`}),`, `,(0,c.jsx)(t.code,{children:`fetchUserTransportRequests`}),`, `,(0,c.jsx)(t.code,{children:`fetchTransportRequests`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Normalize/key`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`normalizeTransportRequests`}),`, `,(0,c.jsx)(t.code,{children:`transportRequestKeys`}),`, `,(0,c.jsx)(t.code,{children:`getTransportRequestKey`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Types`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`TransportRequestType`}),`, `,(0,c.jsx)(t.code,{children:`TransportRequestScope`}),`, `,(0,c.jsx)(t.code,{children:`TransportRequest`}),`, `,(0,c.jsx)(t.code,{children:`TransportRequestRaw`}),`, `,(0,c.jsx)(t.code,{children:`UserTransportRequests`})]})]})]})]})]})}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-DNricOkt.js

@@ -0,0 +1,136 @@
+import{n as e}from"./rolldown-runtime-DkW27tQK.js";import{n as t}from"./iframe-FSp_AjJa.js";import{i as n,r}from"./react-Bl2r1tuC.js";import{l as i,m as a}from"./blocks-B5YBxaaS.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 API/Adapters/Server Function`}),`
+`,(0,c.jsxs)(t.h1,{id:`server-function-adapters-через-ryuzaki13react-foundation-apiserver-fn`,children:[`Server-function adapters через `,(0,c.jsx)(t.code,{children:`@ryuzaki13/react-foundation-api/server-fn`})]}),`
+`,(0,c.jsxs)(t.p,{children:[`Модуль адаптирует функцию с публичной формой `,(0,c.jsx)(t.code,{children:`serverFn({ data })`}),` к query/mutation operation из `,(0,c.jsx)(t.a,{href:`../resource/README.mdx`,children:(0,c.jsx)(t.code,{children:`/resource`})}),`. Сам пакет не импортирует TanStack Start и не запускает сервер.`]}),`
+`,(0,c.jsx)(t.h2,{id:`модель`,children:`Модель`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-text`,children:`scope + args/input
+        │ buildData
+        ▼
+     { data }
+        │ serverFn или custom executor
+        ▼
+     response
+        │ optional transform
+        ▼
+ resource operation result
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Подходит любая async-функция такого контракта:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type ServerFnTransport<TData, TResponse> = (
+	request: { data: TData }
+) => Promise<TResponse>;
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Название `,(0,c.jsx)(t.code,{children:`server-fn`}),` описывает типичный источник функции. Оно не гарантирует server-only выполнение и не создаёт security boundary.`]}),`
+`,(0,c.jsx)(t.h2,{id:`импорт`,children:`Импорт`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import {
+	createServerFnMutationOperation,
+	createServerFnQueryOperation
+} from "@ryuzaki13/react-foundation-api/server-fn";
+
+import type {
+	ServerFnTransport,
+	ServerFnTransportExecutor,
+	ServerFnTransportExecutorContext,
+	ServerFnTransportRequest
+} from "@ryuzaki13/react-foundation-api/server-fn";
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Нужен `,(0,c.jsx)(t.code,{children:`@tanstack/react-query`}),`; созданные operations обычно подключаются через `,(0,c.jsx)(t.code,{children:`/resource`}),` или `,(0,c.jsx)(t.code,{children:`/persisted`}),` descriptor.`]}),`
+`,(0,c.jsx)(t.h2,{id:`query-operation`,children:`Query operation`}),`
+`,(0,c.jsx)(t.p,{children:`Предположим, сгенерированная framework-функция принимает:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type LoadOrdersData = {
+	companyId: string;
+	search: string;
+};
+
+declare const loadOrdersServerFn: ServerFnTransport<
+	LoadOrdersData,
+	{ items: OrderDto[] }
+>;
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Adapter:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const searchOrdersOperation = createServerFnQueryOperation({
+	serverFn: loadOrdersServerFn,
+	buildData: (companyId: string, args: { search: string }) => ({
+		companyId,
+		search: args.search
+	}),
+	transform: (response) => response.items.map(mapOrderDto),
+	staleTime: 60_000,
+	gcTime: 5 * 60_000,
+	isEnabled: (companyId, args) => Boolean(companyId && args.search.trim())
+});
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`buildData`}),` получает валидный scope и query args. `,(0,c.jsx)(t.code,{children:`transform`}),` получает response и `,(0,c.jsx)(t.code,{children:`{ scope, args }`}),`; без transform result равен response.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Созданный объект соответствует `,(0,c.jsx)(t.code,{children:`ResourceQueryOperation`}),`:`]}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`execute({ scope, args, client, signal })`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`optional `,(0,c.jsx)(t.code,{children:`isEnabled`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`optional `,(0,c.jsx)(t.code,{children:`staleTime`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`optional `,(0,c.jsx)(t.code,{children:`gcTime`}),`.`]}),`
+`]}),`
+`,(0,c.jsx)(t.h2,{id:`mutation-operation`,children:`Mutation operation`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`declare const saveOrderServerFn: ServerFnTransport<
+	{ companyId: string; order: SaveOrderDto },
+	{ order: OrderDto }
+>;
+
+const saveOrderOperation = createServerFnMutationOperation({
+	serverFn: saveOrderServerFn,
+	buildData: (companyId: string, input: SaveOrderInput) => ({
+		companyId,
+		order: mapSaveOrder(input)
+	}),
+	transform: (response) => mapOrderDto(response.order),
+	cacheStrategy: createInvalidateResourceScopeCacheStrategy()
+});
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`transform`}),` получает `,(0,c.jsx)(t.code,{children:`{ scope, input }`}),`. `,(0,c.jsx)(t.code,{children:`cacheStrategy`}),` прикрепляется к operation и выполняется владельцем resource mutation после успешного ответа.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Mutation operation не имеет `,(0,c.jsx)(t.code,{children:`AbortSignal`}),` в generic resource contract. Custom executor получает `,(0,c.jsx)(t.code,{children:`{ client }`}),` без signal.`]}),`
+`,(0,c.jsx)(t.h2,{id:`подключение-к-resource-descriptor`,children:`Подключение к resource descriptor`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const ordersResource = createResourceDescriptor({
+	namespace: "sales",
+	resource: "orders",
+	operations: {
+		queries: { search: searchOrdersOperation },
+		mutations: { save: saveOrderOperation }
+	}
+});
+
+const query = useResourceQuery(
+	ordersResource,
+	"search",
+	companyId,
+	{ search }
+);
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`server-fn`}),` не экспортирует resource hooks повторно. Импортируйте их из `,(0,c.jsx)(t.code,{children:`@ryuzaki13/react-foundation-api/resource`}),`.`]}),`
+`,(0,c.jsx)(t.h2,{id:`custom-executor`,children:`Custom executor`}),`
+`,(0,c.jsx)(t.p,{children:`По умолчанию adapter вызывает только:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`serverFn({ data })
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`QueryClient`}),` и `,(0,c.jsx)(t.code,{children:`AbortSignal`}),` не передаются внутрь `,(0,c.jsx)(t.code,{children:`serverFn`}),`. Если transport/framework умеет использовать дополнительный context, задайте executor:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const executor: ServerFnTransportExecutor<Input, Output> = async (
+	serverFn,
+	request,
+	{ signal }
+) => {
+	if (signal?.aborted) throw signal.reason;
+	return serverFn(request);
+};
+
+const operation = createServerFnQueryOperation({
+	serverFn,
+	buildData,
+	executor
+});
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Executor получает саму функцию, нормализованный request `,(0,c.jsx)(t.code,{children:`{ data }`}),` и `,(0,c.jsx)(t.code,{children:`{ client, signal? }`}),`. Он полезен для tracing, тестов и framework adapter-а. Не используйте его для бизнес-логики конкретной entity.`]}),`
+`,(0,c.jsx)(t.h2,{id:`типичные-ошибки`,children:`Типичные ошибки`}),`
+`,(0,c.jsx)(t.h3,{id:`передавать-args-напрямую`,children:`Передавать args напрямую`}),`
+`,(0,c.jsxs)(t.p,{children:[`Неверно предполагать, что query args автоматически становятся data. Их явно преобразует `,(0,c.jsx)(t.code,{children:`buildData`}),`, потому что scope/args и transport DTO — разные контракты.`]}),`
+`,(0,c.jsx)(t.h3,{id:`ожидать-автоматическую-отмену`,children:`Ожидать автоматическую отмену`}),`
+`,(0,c.jsxs)(t.p,{children:[`Default executor не передаёт signal в функцию, поскольку её публичный contract содержит только `,(0,c.jsx)(t.code,{children:`{ data }`}),`. Отмена TanStack Query остановит дальнейшее использование результата на уровне query, но transport должен поддерживать abort отдельно.`]}),`
+`,(0,c.jsx)(t.h3,{id:`считать-функцию-доверенной`,children:`Считать функцию доверенной`}),`
+`,(0,c.jsx)(t.p,{children:`Если функция вызывается из browser bundle, её input контролирует пользователь. Backend обязан повторно проверить authentication, authorization и payload schema.`}),`
+`,(0,c.jsx)(t.h3,{id:`использовать-без-descriptor-а`,children:`Использовать без descriptor-а`}),`
+`,(0,c.jsxs)(t.p,{children:[`Factory возвращает operation, а не готовый React hook. Подключите её к resource/persisted descriptor или вызовите `,(0,c.jsx)(t.code,{children:`execute`}),` через корректный orchestration layer.`]}),`
+`,(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:`createServerFnQueryOperation`})}),(0,c.jsx)(t.td,{children:`Создаёт read operation, optional transform/lifetime/isEnabled`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`createServerFnMutationOperation`})}),(0,c.jsx)(t.td,{children:`Создаёт write operation, optional transform/cache strategy`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`ServerFnTransport`})}),(0,c.jsxs)(t.td,{children:[`Контракт функции `,(0,c.jsx)(t.code,{children:`(request) => Promise`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`ServerFnTransportRequest`})}),(0,c.jsxs)(t.td,{children:[`Обёртка `,(0,c.jsx)(t.code,{children:`{ data }`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`ServerFnTransportExecutor`})}),(0,c.jsx)(t.td,{children:`Контракт custom execution`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`ServerFnTransportExecutorContext`})}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`QueryClient`}),` и optional signal`]})]})]})]})]})}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};