@ryuzaki13/react-foundation-ui 1.8.11 → 1.8.13

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

@@ -0,0 +1,95 @@
+import{n as e}from"./rolldown-runtime-DkW27tQK.js";import{n as t}from"./iframe-o7sH2IXC.js";import{i as n,r}from"./react-Bl2r1tuC.js";import{l as i,m as a}from"./blocks-BY40djCc.js";function o(e){let t={code:`code`,h1:`h1`,h2:`h2`,li:`li`,p:`p`,pre:`pre`,table:`table`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,ul:`ul`,...n(),...e.components};return(0,c.jsxs)(c.Fragment,{children:[(0,c.jsx)(i,{title:`Foundation Lib/React/Virtualizer Pagination`}),`
+`,(0,c.jsxs)(t.h1,{id:`дозагрузка-virtualized-списка-через-ryuzaki13react-foundation-libvirtualizer`,children:[`Дозагрузка virtualized списка через `,(0,c.jsx)(t.code,{children:`@ryuzaki13/react-foundation-lib/virtualizer`})]}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`useFetchNextPageEffect`}),` вызывает `,(0,c.jsx)(t.code,{children:`fetchNextPage`}),`, когда последняя отрендеренная virtual item достигает конца уже загруженного списка.`]}),`
+`,(0,c.jsx)(t.h2,{id:`установка-и-импорт`,children:`Установка и импорт`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-bash`,children:`npm install react @tanstack/react-virtual @ryuzaki13/react-foundation-lib
+`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import { useFetchNextPageEffect } from "@ryuzaki13/react-foundation-lib/virtualizer";
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Host должен использовать совместимые peer dependencies React `,(0,c.jsx)(t.code,{children:`>=19.2 <20`}),` и `,(0,c.jsx)(t.code,{children:`@tanstack/react-virtual >=3.14 <4`}),`.`]}),`
+`,(0,c.jsx)(t.h2,{id:`назначение-и-границы`,children:`Назначение и границы`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-text`,children:`virtualItems (видимый диапазон)
+currentItemsCount (сколько уже загружено)
+hasNextPage
+          │
+последний virtual index >= currentItemsCount - 1
+          │
+          ▼
+fetchNextPage() один раз до завершения Promise
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Hook не создаёт virtualizer, не хранит backend data, не строит query key и не решает server pagination. TanStack Query должен оставаться владельцем server snapshot.`}),`
+`,(0,c.jsx)(t.h2,{id:`сигнатура`,children:`Сигнатура`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`useFetchNextPageEffect({
+	virtualItems,
+	currentItemsCount,
+	fetchNextPage,
+	hasNextPage
+});
+`})}),`
+`,(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.jsx)(t.code,{children:`virtualItems`})}),(0,c.jsxs)(t.td,{children:[`Текущий массив `,(0,c.jsx)(t.code,{children:`VirtualItem[]`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`currentItemsCount`})}),(0,c.jsx)(t.td,{children:`Число реально загруженных data items`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`hasNextPage`})}),(0,c.jsx)(t.td,{children:`Есть ли следующая server page`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`fetchNextPage`})}),(0,c.jsx)(t.td,{children:`Stable функция, возвращающая Promise`})]})]})]}),`
+`,(0,c.jsx)(t.p,{children:`Hook ничего не возвращает.`}),`
+`,(0,c.jsx)(t.h2,{id:`пример-с-tanstack-queryvirtual`,children:`Пример с TanStack Query/Virtual`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-tsx`,children:`const rows = query.data?.pages.flatMap((page) => page.rows) ?? [];
+const virtualItems = virtualizer.getVirtualItems();
+
+useFetchNextPageEffect({
+	virtualItems,
+	currentItemsCount: rows.length,
+	hasNextPage: query.hasNextPage,
+	fetchNextPage: async () => {
+		await query.fetchNextPage();
+	}
+});
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Передавайте количество загруженных строк, а не virtual total с loader row, group headers или estimated backend count.`}),`
+`,(0,c.jsx)(t.h2,{id:`точный-trigger`,children:`Точный trigger`}),`
+`,(0,c.jsx)(t.p,{children:`Fetch не запускается, если:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`virtualItems`}),` пуст;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`currentItemsCount`}),` равен `,(0,c.jsx)(t.code,{children:`0`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`последняя virtual item ещё не достигла `,(0,c.jsx)(t.code,{children:`currentItemsCount - 1`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`hasNextPage === false`}),`;`]}),`
+`,(0,c.jsx)(t.li,{children:`предыдущий вызов ещё не завершился.`}),`
+`]}),`
+`,(0,c.jsx)(t.p,{children:`Trigger происходит строго на последнем загруженном индексе. Preload threshold «за N строк до конца» в API отсутствует.`}),`
+`,(0,c.jsx)(t.h2,{id:`защита-от-параллельного-fetch`,children:`Защита от параллельного fetch`}),`
+`,(0,c.jsxs)(t.p,{children:[`Внутренний `,(0,c.jsx)(t.code,{children:`useRef(false)`}),` устанавливается до вызова и сбрасывается в `,(0,c.jsx)(t.code,{children:`.finally()`}),`:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-text`,children:`idle ── trigger ──► fetchingRef=true
+                       │
+                 Promise pending
+                       │
+             resolve или reject
+                       ▼
+                 fetchingRef=false
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Защита действует только внутри одного mounted hook instance. TanStack Query также должен владеть дедупликацией/network state.`}),`
+`,(0,c.jsxs)(t.p,{children:[`Если `,(0,c.jsx)(t.code,{children:`fetchNextPage`}),` отклоняет Promise, hook не добавляет `,(0,c.jsx)(t.code,{children:`.catch`}),`; rejection может стать unhandled. Передавайте функцию с принятой error policy или wrapper, который корректно обрабатывает ожидаемую ошибку.`]}),`
+`,(0,c.jsx)(t.h2,{id:`referential-stability`,children:`Referential stability`}),`
+`,(0,c.jsxs)(t.p,{children:[`Effect зависит от `,(0,c.jsx)(t.code,{children:`virtualItems`}),`, `,(0,c.jsx)(t.code,{children:`currentItemsCount`}),`, `,(0,c.jsx)(t.code,{children:`hasNextPage`}),`, `,(0,c.jsx)(t.code,{children:`fetchNextPage`}),`.`]}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsx)(t.li,{children:`Используйте значение virtualizer как предусмотрено его API.`}),`
+`,(0,c.jsx)(t.li,{children:`Не создавайте лишний async callback с новой identity без причины.`}),`
+`,(0,c.jsx)(t.li,{children:`React Compiler не отменяет необходимость stable external contract.`}),`
+`,(0,c.jsxs)(t.li,{children:[`После увеличения `,(0,c.jsx)(t.code,{children:`currentItemsCount`}),` новый fetch произойдёт только когда virtual range достигнет нового конца.`]}),`
+`]}),`
+`,(0,c.jsx)(t.h2,{id:`browser-ssr-и-lifecycle`,children:`Browser, SSR и lifecycle`}),`
+`,(0,c.jsxs)(t.p,{children:[`Сам hook не читает `,(0,c.jsx)(t.code,{children:`window`}),`, но является React effect и не выполняет fetch во время server render. В browser effect запускается после commit.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`При unmount Promise не отменяется. Abort/cancel должен быть реализован query/transport owner. `,(0,c.jsx)(t.code,{children:`fetchingRef`}),` больше не влияет после удаления hook instance.`]}),`
+`,(0,c.jsx)(t.h2,{id:`типичные-ошибки`,children:`Типичные ошибки`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsx)(t.li,{children:`Передать total backend rows вместо количества загруженного массива.`}),`
+`,(0,c.jsx)(t.li,{children:`Включить client-side sorting/filtering одной страницы при server-side модели.`}),`
+`,(0,c.jsxs)(t.li,{children:[`Добавить фиктивный loader row в `,(0,c.jsx)(t.code,{children:`currentItemsCount`}),`.`]}),`
+`,(0,c.jsx)(t.li,{children:`Ожидать preload заранее — trigger находится на самом конце.`}),`
+`,(0,c.jsx)(t.li,{children:`Передать rejecting Promise без error handling.`}),`
+`,(0,c.jsx)(t.li,{children:`Выполнять fetch прямо в row render вместо effect.`}),`
+`,(0,c.jsx)(t.li,{children:`Использовать изменяемый index как domain identity строки.`}),`
+`]}),`
+`,(0,c.jsx)(t.h2,{id:`api`,children:`API`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`function useFetchNextPageEffect(args: {
+	virtualItems: VirtualItem[];
+	currentItemsCount: number;
+	hasNextPage: boolean;
+	fetchNextPage: () => Promise<unknown>;
+}): void;
+`})})]})}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-Cb_q420B.js

@@ -0,0 +1,90 @@
+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`,blockquote:`blockquote`,code:`code`,h1:`h1`,h2:`h2`,li:`li`,p:`p`,pre:`pre`,table:`table`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,ul:`ul`,...n(),...e.components};return(0,c.jsxs)(c.Fragment,{children:[(0,c.jsx)(i,{title:`Foundation Lib/HTTP/Headers and Text Response`}),`
+`,(0,c.jsxs)(t.h1,{id:`http-headers-и-текстовые-ответы-через-ryuzaki13react-foundation-libhttp`,children:[`HTTP headers и текстовые ответы через `,(0,c.jsx)(t.code,{children:`@ryuzaki13/react-foundation-lib/http`})]}),`
+`,(0,c.jsxs)(t.p,{children:[`Модуль создаёт стандартный набор HTTP-заголовков запрета кеширования и обычный `,(0,c.jsx)(t.code,{children:`Response`}),` с UTF-8 plain text.`]}),`
+`,(0,c.jsx)(t.h2,{id:`содержание`,children:`Содержание`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsx)(t.li,{children:(0,c.jsx)(t.a,{href:`#%D0%BD%D0%B0%D0%B7%D0%BD%D0%B0%D1%87%D0%B5%D0%BD%D0%B8%D0%B5-%D0%B8-%D0%B3%D1%80%D0%B0%D0%BD%D0%B8%D1%86%D1%8B`,children:`Назначение и границы`})}),`
+`,(0,c.jsx)(t.li,{children:(0,c.jsx)(t.a,{href:`#%D1%83%D1%81%D1%82%D0%B0%D0%BD%D0%BE%D0%B2%D0%BA%D0%B0-%D0%B8-%D0%B8%D0%BC%D0%BF%D0%BE%D1%80%D1%82`,children:`Установка и импорт`})}),`
+`,(0,c.jsx)(t.li,{children:(0,c.jsx)(t.a,{href:`#createnostoreheaders`,children:(0,c.jsx)(t.code,{children:`createNoStoreHeaders`})})}),`
+`,(0,c.jsx)(t.li,{children:(0,c.jsx)(t.a,{href:`#createtexthttpresponse`,children:(0,c.jsx)(t.code,{children:`createTextHttpResponse`})})}),`
+`,(0,c.jsx)(t.li,{children:(0,c.jsx)(t.a,{href:`#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:`#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:`HeadersInit + text + status
+             │
+             ▼
+Headers с no-store + Response(text/plain; charset=UTF-8)
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Модуль не выполняет `,(0,c.jsx)(t.code,{children:`fetch`}),`, не сериализует JSON, не задаёт CORS, CSP, cookies или authorization и не превращает ошибки transport в response автоматически.`]}),`
+`,(0,c.jsx)(t.h2,{id:`установка-и-импорт`,children:`Установка и импорт`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import { createNoStoreHeaders, createTextHttpResponse } from "@ryuzaki13/react-foundation-lib/http";
+
+import type { NoStoreHeadersInit, TextHttpResponseOptions } from "@ryuzaki13/react-foundation-lib/http";
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Нужны стандартные Web API `,(0,c.jsx)(t.code,{children:`Headers`}),` и `,(0,c.jsx)(t.code,{children:`Response`}),`. Они есть в браузерах, Service Worker и современных server runtimes, но могут отсутствовать в старом Node.js без polyfill.`]}),`
+`,(0,c.jsx)(t.h2,{id:`createnostoreheaders`,children:(0,c.jsx)(t.code,{children:`createNoStoreHeaders`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const headers = createNoStoreHeaders({
+	"X-Request-Id": "request-1"
+});
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Функция создаёт новый `,(0,c.jsx)(t.code,{children:`Headers`}),` и устанавливает:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-text`,children:`Cache-Control: no-store, no-cache, must-revalidate, proxy-revalidate
+Pragma: no-cache
+Expires: 0
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Поддерживаются все стандартные формы `,(0,c.jsx)(t.code,{children:`HeadersInit`}),`:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`createNoStoreHeaders();
+createNoStoreHeaders(new Headers({ "X-Test": "1" }));
+createNoStoreHeaders({ "X-Test": "1" });
+createNoStoreHeaders([["X-Test", "1"]]);
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Исходный `,(0,c.jsx)(t.code,{children:`Headers`}),` не изменяется: constructor создаёт новую коллекцию.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Если `,(0,c.jsx)(t.code,{children:`init`}),` уже содержит `,(0,c.jsx)(t.code,{children:`Cache-Control`}),`, `,(0,c.jsx)(t.code,{children:`Pragma`}),` или `,(0,c.jsx)(t.code,{children:`Expires`}),`, библиотечное значение перезаписывает его.`]}),`
+`,(0,c.jsxs)(t.blockquote,{children:[`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`no-store`}),` — инструкция кешам, а не гарантия уничтожения уже сохранённых данных. Не помещайте секреты в response только потому, что добавлены эти headers.`]}),`
+`]}),`
+`,(0,c.jsx)(t.h2,{id:`createtexthttpresponse`,children:(0,c.jsx)(t.code,{children:`createTextHttpResponse`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const response = createTextHttpResponse({
+	status: 400,
+	text: "Некорректный запрос",
+	headers: {
+		"X-Request-Id": "request-1"
+	}
+});
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Результат:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[`обычный экземпляр `,(0,c.jsx)(t.code,{children:`Response`}),`;`]}),`
+`,(0,c.jsx)(t.li,{children:`переданный HTTP status;`}),`
+`,(0,c.jsx)(t.li,{children:`body с исходной строкой;`}),`
+`,(0,c.jsx)(t.li,{children:`no-store headers;`}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`Content-Type: text/plain; charset=UTF-8`}),`.`]}),`
+`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`console.log(response.status); // 400.
+console.log(await response.text()); // "Некорректный запрос".
+console.log(response.headers.get("Content-Type"));
+// "text/plain; charset=UTF-8".
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Переданный `,(0,c.jsx)(t.code,{children:`Content-Type`}),` перезаписывается. Для JSON, HTML, XML, file stream или redirect создайте специализированный response соответствующего владельца.`]}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`Response`}),` сам проверяет допустимость status. Например, некорректное значение может привести к исключению конструктора; helper его не перехватывает.`]}),`
+`,(0,c.jsx)(t.h2,{id:`runtime-и-безопасность`,children:`Runtime и безопасность`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[`Функции синхронны; чтение body через `,(0,c.jsx)(t.code,{children:`response.text()`}),` асинхронно по стандарту Web API.`]}),`
+`,(0,c.jsx)(t.li,{children:`Модуль подходит browser, worker и server runtime с Web Fetch API.`}),`
+`,(0,c.jsx)(t.li,{children:`Текст вставляется как plain text, а не HTML.`}),`
+`,(0,c.jsx)(t.li,{children:`CORS-заголовки не добавляются.`}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`Cache-Control`}),` не заменяет authorization и redaction.`]}),`
+`,(0,c.jsx)(t.li,{children:`Не возвращайте пользователю stack trace, tokens или внутренний transport payload.`}),`
+`,(0,c.jsx)(t.li,{children:`В Service Worker учитывайте общую cache policy: no-store response не должен вручную помещаться в Cache Storage.`}),`
+`]}),`
+`,(0,c.jsx)(t.h2,{id:`api`,children:`API`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type NoStoreHeadersInit = HeadersInit | undefined;
+
+type TextHttpResponseOptions = {
+	readonly status: number;
+	readonly text: string;
+	readonly headers?: HeadersInit;
+};
+`})}),`
+`,(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:`createNoStoreHeaders`})}),(0,c.jsxs)(t.td,{children:[`Новый `,(0,c.jsx)(t.code,{children:`Headers`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`createTextHttpResponse`})}),(0,c.jsxs)(t.td,{children:[`Новый `,(0,c.jsx)(t.code,{children:`Response`})]})]})]})]})]})}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-CtIDPNJ3.js

@@ -0,0 +1,186 @@
+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/Data/Bounded Copy Stack`}),`
+`,(0,c.jsxs)(t.h1,{id:`ограниченный-стек-копий-через-ryuzaki13react-foundation-libbounded-copy-stack`,children:[`Ограниченный стек копий через `,(0,c.jsx)(t.code,{children:`@ryuzaki13/react-foundation-lib/bounded-copy-stack`})]}),`
+`,(0,c.jsxs)(t.p,{children:[`Модуль хранит небольшой список последних скопированных сущностей. Новый элемент помещается в начало, повтор по `,(0,c.jsx)(t.code,{children:`fingerprint`}),` обновляет существующую запись, а старые записи удаляются при превышении лимита.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Документ рассчитан на разработчика без доступа к исходникам пакета. Ниже объясняются структура элемента, различие `,(0,c.jsx)(t.code,{children:`id`}),` и `,(0,c.jsx)(t.code,{children:`fingerprint`}),`, порядок записей, ссылки на payload и все граничные случаи.`]}),`
+`,(0,c.jsx)(t.h2,{id:`содержание`,children:`Содержание`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsx)(t.li,{children:(0,c.jsx)(t.a,{href:`#%D0%BD%D0%B0%D0%B7%D0%BD%D0%B0%D1%87%D0%B5%D0%BD%D0%B8%D0%B5-%D0%B8-%D0%B3%D1%80%D0%B0%D0%BD%D0%B8%D1%86%D1%8B`,children:`Назначение и границы`})}),`
+`,(0,c.jsx)(t.li,{children:(0,c.jsx)(t.a,{href:`#%D1%83%D1%81%D1%82%D0%B0%D0%BD%D0%BE%D0%B2%D0%BA%D0%B0-%D0%B8-%D0%B8%D0%BC%D0%BF%D0%BE%D1%80%D1%82`,children:`Установка и импорт`})}),`
+`,(0,c.jsx)(t.li,{children:(0,c.jsx)(t.a,{href:`#%D0%BE%D1%81%D0%BD%D0%BE%D0%B2%D0%BD%D1%8B%D0%B5-%D0%BF%D0%BE%D0%BD%D1%8F%D1%82%D0%B8%D1%8F`,children:`Основные понятия`})}),`
+`,(0,c.jsx)(t.li,{children:(0,c.jsx)(t.a,{href:`#%D0%B1%D1%8B%D1%81%D1%82%D1%80%D1%8B%D0%B9-%D1%81%D1%82%D0%B0%D1%80%D1%82`,children:`Быстрый старт`})}),`
+`,(0,c.jsx)(t.li,{children:(0,c.jsx)(t.a,{href:`#pushboundedcopystackitem`,children:(0,c.jsx)(t.code,{children:`pushBoundedCopyStackItem`})})}),`
+`,(0,c.jsx)(t.li,{children:(0,c.jsx)(t.a,{href:`#getboundedcopystackcandidates`,children:(0,c.jsx)(t.code,{children:`getBoundedCopyStackCandidates`})})}),`
+`,(0,c.jsx)(t.li,{children:(0,c.jsx)(t.a,{href:`#%D1%81%D1%81%D1%8B%D0%BB%D0%BA%D0%B8-%D1%85%D1%80%D0%B0%D0%BD%D0%B5%D0%BD%D0%B8%D0%B5-%D0%B8-%D1%81%D0%B5%D1%80%D0%B8%D0%B0%D0%BB%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D1%8F`,children:`Ссылки, хранение и сериализация`})}),`
+`,(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.li,{children:(0,c.jsx)(t.a,{href:`#%D1%82%D0%B8%D0%BF%D0%B8%D1%87%D0%BD%D1%8B%D0%B5-%D0%BE%D1%88%D0%B8%D0%B1%D0%BA%D0%B8`,children:`Типичные ошибки`})}),`
+`]}),`
+`,(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:`копирование A ──► [A]
+копирование B ──► [B, A]
+повтор A       ──► [новая A, B]
+копирование C  ──► [C, новая A, B]
+копирование D  ──► [D, C, новая A]  при maxSize = 3
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Модуль:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsx)(t.li,{children:`не использует системный clipboard;`}),`
+`,(0,c.jsx)(t.li,{children:`не сохраняет список в storage;`}),`
+`,(0,c.jsx)(t.li,{children:`не создаёт React state или Zustand store;`}),`
+`,(0,c.jsxs)(t.li,{children:[`не клонирует `,(0,c.jsx)(t.code,{children:`payload`}),` и `,(0,c.jsx)(t.code,{children:`meta`}),`;`]}),`
+`,(0,c.jsx)(t.li,{children:`не сравнивает payload глубоко;`}),`
+`,(0,c.jsx)(t.li,{children:`не нормализует данные;`}),`
+`,(0,c.jsx)(t.li,{children:`не выполняет вставку выбранного кандидата.`}),`
+`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Clipboard helpers находятся в `,(0,c.jsx)(t.code,{children:`@ryuzaki13/react-foundation-lib/copy`}),`. Владелец state/storage находится в host-приложении.`]}),`
+`,(0,c.jsx)(t.h2,{id:`установка-и-импорт`,children:`Установка и импорт`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-bash`,children:`npm install @ryuzaki13/react-foundation-lib
+`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import {
+	DEFAULT_BOUNDED_COPY_STACK_SIZE,
+	getBoundedCopyStackCandidates,
+	pushBoundedCopyStackItem
+} from "@ryuzaki13/react-foundation-lib/bounded-copy-stack";
+
+import type {
+	BoundedCopyStackItem,
+	BoundedCopyStackOptions,
+	BoundedCopyStackPushInput,
+	BoundedCopyStackPushResult
+} from "@ryuzaki13/react-foundation-lib/bounded-copy-stack";
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Корневой и глубокий импорты не поддерживаются. Модуль ESM, не зависит от React и browser APIs.`}),`
+`,(0,c.jsx)(t.h2,{id:`основные-понятия`,children:`Основные понятия`}),`
+`,(0,c.jsx)(t.h3,{id:`элемент-стека`,children:`Элемент стека`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type BoundedCopyStackItem<TPayload, TMeta = undefined> = {
+	id: string;
+	fingerprint: string;
+	payload: TPayload;
+	meta: TMeta;
+	copiedAt: number;
+};
+`})}),`
+`,(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.jsx)(t.code,{children:`id`})}),(0,c.jsx)(t.td,{children:`Идентификатор конкретной записи/операции копирования`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`fingerprint`})}),(0,c.jsx)(t.td,{children:`Идентичность содержимого для удаления повторов`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`payload`})}),(0,c.jsx)(t.td,{children:`Данные, которые host затем сможет вставить`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`meta`})}),(0,c.jsx)(t.td,{children:`Подпись, тип, источник или другая информация для UI`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`copiedAt`})}),(0,c.jsx)(t.td,{children:`Время копирования в миллисекундах Unix; функция не сортирует по этому полю`})]})]})]}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`id`}),` и `,(0,c.jsx)(t.code,{children:`fingerprint`}),` решают разные задачи. При повторном копировании содержимого `,(0,c.jsx)(t.code,{children:`fingerprint`}),` остаётся прежним, а `,(0,c.jsx)(t.code,{children:`id`}),`, `,(0,c.jsx)(t.code,{children:`payload`}),`, `,(0,c.jsx)(t.code,{children:`meta`}),` и `,(0,c.jsx)(t.code,{children:`copiedAt`}),` могут стать новыми.`]}),`
+`,(0,c.jsx)(t.h3,{id:`порядок`,children:`Порядок`}),`
+`,(0,c.jsxs)(t.p,{children:[`Индекс `,(0,c.jsx)(t.code,{children:`0`}),` всегда содержит элемент последней операции `,(0,c.jsx)(t.code,{children:`push`}),`. Функция доверяет входному порядку и не сортирует список по `,(0,c.jsx)(t.code,{children:`copiedAt`}),`.`]}),`
+`,(0,c.jsx)(t.h2,{id:`быстрый-старт`,children:`Быстрый старт`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type ColumnCopy = {
+	columnId: string;
+	width: number;
+};
+
+type ColumnCopyMeta = {
+	label: string;
+};
+
+let stack: BoundedCopyStackItem<ColumnCopy, ColumnCopyMeta>[] = [];
+
+const result = pushBoundedCopyStackItem(stack, {
+	id: crypto.randomUUID(),
+	fingerprint: "column:amount:width:120",
+	payload: { columnId: "amount", width: 120 },
+	meta: { label: "Сумма — ширина 120" }
+});
+
+stack = result.items;
+console.log(result.updatedExisting); // false.
+console.log(result.addedItem.copiedAt); // Date.now() на момент вызова.
+`})}),`
+`,(0,c.jsx)(t.h2,{id:`pushboundedcopystackitem`,children:(0,c.jsx)(t.code,{children:`pushBoundedCopyStackItem`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const result = pushBoundedCopyStackItem(items, input, { maxSize: 3 });
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Алгоритм:`}),`
+`,(0,c.jsxs)(t.ol,{children:[`
+`,(0,c.jsxs)(t.li,{children:[`Создаёт новый элемент из `,(0,c.jsx)(t.code,{children:`input`}),`.`]}),`
+`,(0,c.jsxs)(t.li,{children:[`Если `,(0,c.jsx)(t.code,{children:`copiedAt`}),` отсутствует, подставляет `,(0,c.jsx)(t.code,{children:`Date.now()`}),`.`]}),`
+`,(0,c.jsxs)(t.li,{children:[`Ищет любой элемент с точно равным `,(0,c.jsx)(t.code,{children:`fingerprint`}),`.`]}),`
+`,(0,c.jsx)(t.li,{children:`Удаляет из старого списка все элементы с таким fingerprint.`}),`
+`,(0,c.jsx)(t.li,{children:`Помещает новый элемент в начало.`}),`
+`,(0,c.jsxs)(t.li,{children:[`Обрезает результат до `,(0,c.jsx)(t.code,{children:`maxSize`}),`.`]}),`
+`]}),`
+`,(0,c.jsx)(t.p,{children:`Входной массив не изменяется. Возвращается новый массив.`}),`
+`,(0,c.jsx)(t.h3,{id:`повторный-fingerprint`,children:`Повторный fingerprint`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const oldItems = [
+	{
+		id: "old",
+		fingerprint: "same-content",
+		payload: { value: 1 },
+		meta: undefined,
+		copiedAt: 1
+	}
+];
+
+const result = pushBoundedCopyStackItem(oldItems, {
+	id: "new",
+	fingerprint: "same-content",
+	payload: { value: 2 },
+	meta: undefined,
+	copiedAt: 2
+});
+
+console.log(result.items.length); // 1.
+console.log(result.items[0].id); // "new".
+console.log(result.updatedExisting); // true.
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Сравнение fingerprint регистрозависимое и использует `,(0,c.jsx)(t.code,{children:`===`}),`. Строки `,(0,c.jsx)(t.code,{children:`"A"`}),` и `,(0,c.jsx)(t.code,{children:`"a"`}),` различны.`]}),`
+`,(0,c.jsxs)(t.h3,{id:`нормализация-maxsize`,children:[`Нормализация `,(0,c.jsx)(t.code,{children:`maxSize`})]}),`
+`,(0,c.jsxs)(t.p,{children:[`Default `,(0,c.jsx)(t.code,{children:`DEFAULT_BOUNDED_COPY_STACK_SIZE`}),` равен `,(0,c.jsx)(t.code,{children:`3`}),`.`]}),`
+`,(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,{style:{textAlign:`right`},children:`Фактический лимит`})]})}),(0,c.jsxs)(t.tbody,{children:[(0,c.jsxs)(t.tr,{children:[(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`undefined`}),`, `,(0,c.jsx)(t.code,{children:`NaN`}),`, `,(0,c.jsx)(t.code,{children:`Infinity`})]}),(0,c.jsx)(t.td,{style:{textAlign:`right`},children:`3`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`5.9`})}),(0,c.jsx)(t.td,{style:{textAlign:`right`},children:`5`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`1`})}),(0,c.jsx)(t.td,{style:{textAlign:`right`},children:`1`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`0`}),`, отрицательное конечное значение`]}),(0,c.jsx)(t.td,{style:{textAlign:`right`},children:`1`})]})]})]}),`
+`,(0,c.jsxs)(t.p,{children:[`Полностью отключить хранение через `,(0,c.jsx)(t.code,{children:`maxSize: 0`}),` нельзя. Если список не нужен, host должен не вызывать push или хранить пустой state самостоятельно.`]}),`
+`,(0,c.jsx)(t.h3,{id:`результат`,children:`Результат`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type BoundedCopyStackPushResult<TPayload, TMeta> = {
+	items: BoundedCopyStackItem<TPayload, TMeta>[];
+	addedItem: BoundedCopyStackItem<TPayload, TMeta>;
+	updatedExisting: boolean;
+};
+`})}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`items`}),` — итоговый ограниченный список;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`addedItem`}),` — созданная запись, даже если из-за будущей логики host её не сохранит;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`updatedExisting`}),` — был ли во входном списке такой fingerprint.`]}),`
+`]}),`
+`,(0,c.jsx)(t.h2,{id:`getboundedcopystackcandidates`,children:(0,c.jsx)(t.code,{children:`getBoundedCopyStackCandidates`})}),`
+`,(0,c.jsx)(t.p,{children:`Функция фильтрует записи предикатом и сохраняет исходный порядок:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const tableCandidates = getBoundedCopyStackCandidates(stack, (item) => item.meta.kind === "table-column");
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Она эквивалентна типизированному `,(0,c.jsx)(t.code,{children:`items.filter(predicate)`}),`:`]}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsx)(t.li,{children:`возвращает новый массив;`}),`
+`,(0,c.jsx)(t.li,{children:`не клонирует элементы;`}),`
+`,(0,c.jsx)(t.li,{children:`не изменяет исходный массив;`}),`
+`,(0,c.jsx)(t.li,{children:`не ограничивает количество дополнительно;`}),`
+`,(0,c.jsx)(t.li,{children:`исключение из predicate пробрасывается вызывающему коду.`}),`
+`]}),`
+`,(0,c.jsx)(t.h2,{id:`ссылки-хранение-и-сериализация`,children:`Ссылки, хранение и сериализация`}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`payload`}),` и `,(0,c.jsx)(t.code,{children:`meta`}),` переносятся по ссылке:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const payload = { nested: { value: 1 } };
+const result = pushBoundedCopyStackItem([], {
+	id: "1",
+	fingerprint: "one",
+	payload,
+	meta: undefined
+});
+
+console.log(result.addedItem.payload === payload); // true.
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Если нужна независимая data-only копия, создайте её через `,(0,c.jsx)(t.code,{children:`deepCopyWithoutFunctions`}),` из `,(0,c.jsx)(t.code,{children:`/utils`}),` до push. Clone не должен нормализовать данные.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Для `,(0,c.jsx)(t.code,{children:`localStorage`}),`/`,(0,c.jsx)(t.code,{children:`sessionStorage`}),` host самостоятельно отвечает за:`]}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsx)(t.li,{children:`JSON-compatible payload/meta;`}),`
+`,(0,c.jsx)(t.li,{children:`версию persisted schema;`}),`
+`,(0,c.jsx)(t.li,{children:`runtime-проверку восстановленных данных;`}),`
+`,(0,c.jsx)(t.li,{children:`удаление устаревших записей;`}),`
+`,(0,c.jsx)(t.li,{children:`отсутствие секретов и персональных данных.`}),`
+`]}),`
+`,(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:`DEFAULT_BOUNDED_COPY_STACK_SIZE`})}),(0,c.jsxs)(t.td,{children:[`Default-лимит `,(0,c.jsx)(t.code,{children:`3`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`pushBoundedCopyStackItem`})}),(0,c.jsx)(t.td,{children:`Добавляет/обновляет запись и ограничивает список`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`getBoundedCopyStackCandidates`})}),(0,c.jsx)(t.td,{children:`Фильтрует кандидатов`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`BoundedCopyStackItem`})}),(0,c.jsx)(t.td,{children:`Полная сохранённая запись`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`BoundedCopyStackPushInput`})}),(0,c.jsxs)(t.td,{children:[`Вход push; `,(0,c.jsx)(t.code,{children:`copiedAt`}),` optional`]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`BoundedCopyStackOptions`})}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`{ maxSize?: number }`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`BoundedCopyStackPushResult`})}),(0,c.jsx)(t.td,{children:`Итоговый список и сведения об операции`})]})]})]}),`
+`,(0,c.jsx)(t.h2,{id:`типичные-ошибки`,children:`Типичные ошибки`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[`Использовать уникальный `,(0,c.jsx)(t.code,{children:`id`}),` как fingerprint: дубликаты содержимого никогда не объединятся.`]}),`
+`,(0,c.jsxs)(t.li,{children:[`Ожидать сортировку по `,(0,c.jsx)(t.code,{children:`copiedAt`}),`: порядок определяется вызовами push.`]}),`
+`,(0,c.jsxs)(t.li,{children:[`Мутировать `,(0,c.jsx)(t.code,{children:`payload`}),` после push и ожидать snapshot: ссылка общая.`]}),`
+`,(0,c.jsxs)(t.li,{children:[`Передавать `,(0,c.jsx)(t.code,{children:`maxSize: 0`}),` для отключения: получится лимит `,(0,c.jsx)(t.code,{children:`1`}),`.`]}),`
+`,(0,c.jsx)(t.li,{children:`Хранить callback/DOM node в persisted stack: модуль не делает данные сериализуемыми.`}),`
+`,(0,c.jsx)(t.li,{children:`Вызывать helper вместо clipboard API: стек ничего не копирует в ОС.`}),`
+`]})]})}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-CzO3Dchr.js

@@ -0,0 +1,64 @@
+import{n as e}from"./rolldown-runtime-DkW27tQK.js";import{n as t}from"./iframe-o7sH2IXC.js";import{i as n,r}from"./react-Bl2r1tuC.js";import{l as i,m as a}from"./blocks-BY40djCc.js";function o(e){let t={code:`code`,h1:`h1`,h2:`h2`,li:`li`,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/Errors/Missing Context`}),`
+`,(0,c.jsxs)(t.h1,{id:`ошибка-отсутствующего-react-context-через-ryuzaki13react-foundation-liberror`,children:[`Ошибка отсутствующего React context через `,(0,c.jsx)(t.code,{children:`@ryuzaki13/react-foundation-lib/error`})]}),`
+`,(0,c.jsx)(t.p,{children:`Модуль создаёт единообразное диагностическое сообщение, когда custom hook вызван вне нужного Provider.`}),`
+`,(0,c.jsx)(t.h2,{id:`установка-и-импорт`,children:`Установка и импорт`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import { createMissingContextError, createMissingContextErrorMessage } from "@ryuzaki13/react-foundation-lib/error";
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Модуль не импортирует React и может использоваться в любом TypeScript runtime. Типы объектов options выводятся из аргумента и отдельно не экспортируются.`}),`
+`,(0,c.jsx)(t.h2,{id:`когда-использовать`,children:`Когда использовать`}),`
+`,(0,c.jsx)(t.p,{children:`Обычная схема context hook:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-tsx`,children:`const DemoContext = createContext<DemoValue | null>(null);
+
+export function useDemo() {
+	const value = useContext(DemoContext);
+
+	if (value === null) {
+		throw createMissingContextError({
+			hookName: "useDemo",
+			providerName: "DemoProvider",
+			contextName: "DemoContext"
+		});
+	}
+
+	return value;
+}
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Ошибка должна выбрасываться при нарушении обязательного structural contract. Если отсутствие Provider является допустимым состоянием, возвращайте optional result по собственному явно названному API.`}),`
+`,(0,c.jsx)(t.h2,{id:`createmissingcontexterrormessage`,children:(0,c.jsx)(t.code,{children:`createMissingContextErrorMessage`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const message = createMissingContextErrorMessage({
+	hookName: "useDemo",
+	providerName: "DemoProvider",
+	contextName: "DemoContext"
+});
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Результат состоит из трёх предложений:`}),`
+`,(0,c.jsxs)(t.ol,{children:[`
+`,(0,c.jsx)(t.li,{children:`Где разрешено использовать hook.`}),`
+`,(0,c.jsxs)(t.li,{children:[`Какой context оказался `,(0,c.jsx)(t.code,{children:`null`}),`.`]}),`
+`,(0,c.jsx)(t.li,{children:`Что Provider должен находиться выше вызывающего компонента.`}),`
+`]}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`contextName`}),` optional. Без него сообщение остаётся корректным, но менее конкретным.`]}),`
+`,(0,c.jsx)(t.p,{children:`Поля вставляются буквально: функция не добавляет backticks, не проверяет имена и не локализует их.`}),`
+`,(0,c.jsx)(t.h2,{id:`createmissingcontexterror`,children:(0,c.jsx)(t.code,{children:`createMissingContextError`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Возвращает обычный `,(0,c.jsx)(t.code,{children:`Error`}),` с тем же сообщением:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const error = createMissingContextError({
+	hookName: "useDemo",
+	providerName: "DemoProvider"
+});
+
+console.log(error.name); // "Error".
+console.log(error.message); // Подробное русское сообщение.
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Функция сама не делает `,(0,c.jsx)(t.code,{children:`throw`}),`:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`throw createMissingContextError(options);
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Stack trace создаётся стандартным конструктором `,(0,c.jsx)(t.code,{children:`Error`}),` в месте вызова.`]}),`
+`,(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:`createMissingContextErrorMessage`})}),(0,c.jsx)(t.td,{children:`Возвращает только строку`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`createMissingContextError`})}),(0,c.jsxs)(t.td,{children:[`Возвращает экземпляр `,(0,c.jsx)(t.code,{children:`Error`})]})]})]})]}),`
+`,(0,c.jsx)(t.h2,{id:`типичные-ошибки`,children:`Типичные ошибки`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsx)(t.li,{children:`Возвращать fallback-object после ошибки и скрывать неправильное дерево Provider.`}),`
+`,(0,c.jsxs)(t.li,{children:[`Выбрасывать ошибку прямо в Provider вместо hook, который обнаружил `,(0,c.jsx)(t.code,{children:`null`}),`.`]}),`
+`,(0,c.jsx)(t.li,{children:`Передавать пустые имена: helper не валидирует строки.`}),`
+`,(0,c.jsx)(t.li,{children:`Использовать этот модуль для сетевых/validation ошибок: он предназначен только для missing context contract.`}),`
+`]})]})}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};