@ryuzaki13/react-foundation-ui 1.8.11 → 1.8.13

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

@@ -0,0 +1,264 @@
+import{n as e}from"./rolldown-runtime-DkW27tQK.js";import{n as t}from"./iframe-o7sH2IXC.js";import{i as n,r}from"./react-Bl2r1tuC.js";import{l as i,m as a}from"./blocks-BY40djCc.js";function o(e){let t={code:`code`,h1:`h1`,h2:`h2`,h3:`h3`,li:`li`,ol:`ol`,p:`p`,pre:`pre`,strong:`strong`,table:`table`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,ul:`ul`,...n(),...e.components};return(0,c.jsxs)(c.Fragment,{children:[(0,c.jsx)(i,{title:`Foundation Lib/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};