@ryuzaki13/react-foundation-ui 1.8.10 → 1.8.12

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

@@ -0,0 +1,322 @@
+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 API/Query/Persisted Records`}),`
+`,(0,c.jsxs)(t.h1,{id:`сохранённые-записи-через-ryuzaki13react-foundation-apipersisted`,children:[`Сохранённые записи через `,(0,c.jsx)(t.code,{children:`@ryuzaki13/react-foundation-api/persisted`})]}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`persisted`}),` — специализированный слой поверх TanStack Query для данных, которые пользователь сохраняет и позднее восстанавливает: presets, variants, view configs и другие versioned records.`]}),`
+`,(0,c.jsx)(t.h2,{id:`ментальная-модель`,children:`Ментальная модель`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-text`,children:`PersistedResourceDescriptor
+  ├─ identity: namespace + resource + normalized scope
+  ├─ read capability: list | latest | history
+  ├─ write capability: save | create | delete
+  ├─ transport operation: REST | OData | server-fn | custom
+  └─ cache strategy после успешной mutation
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Capability optional: resource не обязан поддерживать все шесть операций. TypeScript разрешит соответствующий hook только когда operation присутствует в descriptor; runtime также выдаёт понятную ошибку при неправильном объекте.`}),`
+`,(0,c.jsxs)(t.h2,{id:`persisted-или-resource`,children:[(0,c.jsx)(t.code,{children:`persisted`}),` или `,(0,c.jsx)(t.code,{children:`resource`})]}),`
+`,(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:`Фиксированные сохранённые records: list/latest/history/save/create/delete`}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`/persisted`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Произвольные названия и semantics операций`}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.a,{href:`../resource/README.mdx`,children:(0,c.jsx)(t.code,{children:`/resource`})})})]})]})]}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`persisted`}),` построен на тех же принципах keys/cache, но намеренно не является универсальным CRUD.`]}),`
+`,(0,c.jsx)(t.h2,{id:`установка-и-provider`,children:`Установка и provider`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-bash`,children:`npm install @ryuzaki13/react-foundation-api @ryuzaki13/react-foundation-lib @tanstack/react-query react
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Hooks требуют `,(0,c.jsx)(t.code,{children:`QueryClientProvider`}),`. Descriptor и operations создавайте на module level, чтобы ссылки были стабильными.`]}),`
+`,(0,c.jsx)(t.h2,{id:`импорт`,children:`Импорт`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import {
+	applyPersistedCacheStrategy,
+	composePersistedCacheStrategies,
+	createInvalidatePersistedScopeCacheStrategy,
+	createPersistedJsonCodec,
+	createPersistedODataMutationOperation,
+	createPersistedODataQueryOperation,
+	createPersistedODataReadOperation,
+	createPersistedRecordKeys,
+	createPersistedResourceDescriptor,
+	createPersistedRestMutationOperation,
+	createPersistedRestQueryOperation,
+	createSetPersistedQueryDataCacheStrategy,
+	getPersistedHistoryData,
+	getPersistedLatestData,
+	getPersistedListData,
+	parsePersistedJson,
+	stringifyPersistedJson,
+	usePersistedCreateMutation,
+	usePersistedDeleteMutation,
+	usePersistedHistoryQuery,
+	usePersistedLatestQuery,
+	usePersistedListQuery,
+	usePersistedSaveMutation
+} from "@ryuzaki13/react-foundation-api/persisted";
+`})}),`
+`,(0,c.jsx)(t.h2,{id:`пошаговый-rest-пример`,children:`Пошаговый REST пример`}),`
+`,(0,c.jsx)(t.h3,{id:`1-контракты`,children:`1. Контракты`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type ViewScope = {
+	userId: string;
+	viewId: string;
+};
+
+type ViewConfig = {
+	columns: string[];
+	compact: boolean;
+};
+
+type SavedViewRecord = {
+	id: string;
+	createdUtc: string;
+	payload: string;
+};
+
+type SaveViewInput = {
+	payload: ViewConfig;
+};
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Внешний record и распарсенный config — разные типы. TypeScript не проверяет network payload автоматически.`}),`
+`,(0,c.jsx)(t.h3,{id:`2-runtime-parsers`,children:`2. Runtime parsers`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`function parseRecord(value: unknown): SavedViewRecord {
+	if (!isSavedViewRecord(value)) {
+		throw new Error("Некорректный SavedViewRecord payload");
+	}
+
+	return value;
+}
+
+function parseRecordList(value: unknown): SavedViewRecord[] {
+	if (!Array.isArray(value)) throw new Error("Ожидался массив records");
+	return value.map(parseRecord);
+}
+`})}),`
+`,(0,c.jsx)(t.h3,{id:`3-operations`,children:`3. Operations`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const listOperation = createPersistedRestQueryOperation<
+	ViewScope,
+	void,
+	SavedViewRecord[]
+>({
+	buildUrl: (scope) =>
+		\`/api/users/\${encodeURIComponent(scope.userId)}/views/\${encodeURIComponent(scope.viewId)}\`,
+	parseResponse: parseRecordList,
+	staleTime: 60_000
+});
+
+const latestOperation = createPersistedRestQueryOperation<
+	ViewScope,
+	void,
+	SavedViewRecord,
+	ViewConfig | null
+>({
+	buildUrl: (scope) =>
+		\`/api/users/\${encodeURIComponent(scope.userId)}/views/\${encodeURIComponent(scope.viewId)}/latest\`,
+	parseResponse: parseRecord,
+	transform: (record) => parsePersistedJson<ViewConfig>(record.payload)
+});
+
+const saveOperation = createPersistedRestMutationOperation<
+	ViewScope,
+	SaveViewInput,
+	SavedViewRecord
+>({
+	buildUrl: (scope) =>
+		\`/api/users/\${encodeURIComponent(scope.userId)}/views/\${encodeURIComponent(scope.viewId)}\`,
+	method: "PUT",
+	bodyMapper: (_scope, input) => ({
+		payload: stringifyPersistedJson(input.payload)
+	}),
+	parseResponse: parseRecord,
+	cacheStrategy: createInvalidatePersistedScopeCacheStrategy()
+});
+`})}),`
+`,(0,c.jsx)(t.h3,{id:`4-descriptor`,children:`4. Descriptor`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const viewResource = createPersistedResourceDescriptor({
+	namespace: "view-config",
+	resource: "view",
+	normalizeScope: (scope: ViewScope | null | undefined) => ({
+		userId: scope?.userId.trim() ?? "",
+		viewId: scope?.viewId.trim() ?? ""
+	}),
+	isEnabled: (scope) => Boolean(scope?.userId && scope?.viewId),
+	getScopeError: () => "Не определён пользователь или представление",
+	transport: {
+		list: listOperation,
+		latest: latestOperation,
+		save: saveOperation
+	}
+});
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`normalizeScope`}),` изменяет только cache identity. В `,(0,c.jsx)(t.code,{children:`buildUrl`}),`/`,(0,c.jsx)(t.code,{children:`execute`}),` передаётся исходный scope.`]}),`
+`,(0,c.jsx)(t.h3,{id:`5-hooks`,children:`5. Hooks`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-tsx`,children:`const scope = { userId, viewId };
+const latestQuery = usePersistedLatestQuery(viewResource, scope);
+const listQuery = usePersistedListQuery(viewResource, scope);
+const saveMutation = usePersistedSaveMutation(viewResource, scope);
+
+saveMutation.mutate({
+	payload: { columns: ["name", "status"], compact: true }
+});
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Нельзя вызвать `,(0,c.jsx)(t.code,{children:`usePersistedHistoryQuery`}),` для этого descriptor, пока capability `,(0,c.jsx)(t.code,{children:`history`}),` не добавлена.`]}),`
+`,(0,c.jsx)(t.h2,{id:`read-capabilities`,children:`Read capabilities`}),`
+`,(0,c.jsxs)(t.table,{children:[(0,c.jsx)(t.thead,{children:(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.th,{children:`Capability`}),(0,c.jsx)(t.th,{children:`Hook`}),(0,c.jsx)(t.th,{children:`Imperative helper`}),(0,c.jsx)(t.th,{children:`Args`})]})}),(0,c.jsxs)(t.tbody,{children:[(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`list`})}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`usePersistedListQuery`})}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`getPersistedListData`})}),(0,c.jsxs)(t.td,{children:[`нет (`,(0,c.jsx)(t.code,{children:`void`}),`)`]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`latest`})}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`usePersistedLatestQuery`})}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`getPersistedLatestData`})}),(0,c.jsxs)(t.td,{children:[`нет (`,(0,c.jsx)(t.code,{children:`void`}),`)`]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`history`})}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`usePersistedHistoryQuery`})}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`getPersistedHistoryData`})}),(0,c.jsx)(t.td,{children:`обязательный generic args`})]})]})]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const page = await getPersistedHistoryData(
+	resourceWithHistory,
+	scope,
+	{ cursor: "next", limit: 20 },
+	queryClient
+);
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Query operation получает `,(0,c.jsx)(t.code,{children:`{ scope, args, client, signal }`}),`. `,(0,c.jsx)(t.code,{children:`isEnabled`}),` operation и descriptor определяют автоматический запуск React observer; `,(0,c.jsx)(t.code,{children:`staleTime`}),`, `,(0,c.jsx)(t.code,{children:`gcTime`}),`, `,(0,c.jsx)(t.code,{children:`meta`}),` переходят в TanStack Query options.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Imperative helpers используют `,(0,c.jsx)(t.code,{children:`queryClient.fetchQuery`}),`. Передавайте валидный scope; disabled policy в первую очередь управляет observer, а фактическая query function всё равно проверяет scope.`]}),`
+`,(0,c.jsx)(t.h2,{id:`write-capabilities`,children:`Write capabilities`}),`
+`,(0,c.jsxs)(t.table,{children:[(0,c.jsx)(t.thead,{children:(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.th,{children:`Capability`}),(0,c.jsx)(t.th,{children:`Hook`}),(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:`save`})}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`usePersistedSaveMutation`})}),(0,c.jsx)(t.td,{children:`Сохранить/обновить snapshot`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`create`})}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`usePersistedCreateMutation`})}),(0,c.jsx)(t.td,{children:`Создать новую именованную запись`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`delete`})}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`usePersistedDeleteMutation`})}),(0,c.jsx)(t.td,{children:`Удалить запись`})]})]})]}),`
+`,(0,c.jsxs)(t.p,{children:[`Mutation operation получает `,(0,c.jsx)(t.code,{children:`{ scope, input, client }`}),`. Generic persisted contract не передаёт `,(0,c.jsx)(t.code,{children:`AbortSignal`}),` для mutation.`]}),`
+`,(0,c.jsx)(t.p,{children:`После успешного transport:`}),`
+`,(0,c.jsxs)(t.ol,{children:[`
+`,(0,c.jsx)(t.li,{children:`выбирается cache strategy;`}),`
+`,(0,c.jsx)(t.li,{children:`strategy выполняется и awaited;`}),`
+`,(0,c.jsxs)(t.li,{children:[`вызывается optional hook `,(0,c.jsx)(t.code,{children:`onSuccess(result, input)`}),`.`]}),`
+`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`usePersistedSaveMutation(resource, scope, {
+	cacheStrategy: null, // Отключить operation strategy.
+	onSuccess(result) {
+		showSuccess(\`Сохранено \${result.id}\`);
+	}
+});
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`cacheStrategy: undefined`}),` использует strategy операции; `,(0,c.jsx)(t.code,{children:`null`}),` отключает; объект заменяет исходную strategy. Для дополнения применяйте композицию.`]}),`
+`,(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:`const keys = createPersistedRecordKeys<ViewScope>({
+	namespace: "view-config",
+	resource: "view",
+	normalizeScope: (scope) => ({
+		userId: scope?.userId ?? "",
+		viewId: scope?.viewId ?? ""
+	})
+});
+
+keys.all;
+keys.scope(scope);
+keys.list(scope);
+keys.latest(scope);
+keys.history(scope, { limit: 20 });
+keys.save(scope);
+keys.create(scope);
+keys.delete(scope);
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Форма:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-text`,children:`[namespace, resource, normalizedScope, operation, optionalArgs]
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Используется нормализация `,(0,c.jsx)(t.code,{children:`/resource`}),`: strings trim, object keys сортируются, `,(0,c.jsx)(t.code,{children:`undefined`}),` становится `,(0,c.jsx)(t.code,{children:`null`}),`. Date/Map/cyclic object требуют явного нормализатора.`]}),`
+`,(0,c.jsx)(t.h2,{id:`json-payload-codec`,children:`JSON payload codec`}),`
+`,(0,c.jsx)(t.h3,{id:`parse`,children:`Parse`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`parsePersistedJson<ViewConfig>(null); // null.
+parsePersistedJson<ViewConfig>(""); // null.
+parsePersistedJson<ViewConfig>("broken"); // null.
+parsePersistedJson<ViewConfig>('{"compact":true,"columns":[]}');
+// Object, но без runtime validation.
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`parsePersistedJson<T>`}),` только вызывает `,(0,c.jsx)(t.code,{children:`JSON.parse`}),` и делает TypeScript cast. Он не проверяет schema. После parse примените domain validator/normalizer на явной restore boundary.`]}),`
+`,(0,c.jsx)(t.h3,{id:`stringify`,children:`Stringify`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const payload = stringifyPersistedJson({ compact: false, columns: [] });
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Ошибки `,(0,c.jsx)(t.code,{children:`JSON.stringify`}),` пробрасываются. Передавайте только JSON-compatible данные. В частности:`]}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[`cyclic object и `,(0,c.jsx)(t.code,{children:`BigInt`}),` приводят к ошибке;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`Date`}),` превращается в ISO string;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`undefined`}),` в object-поле удаляется;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`вызов с корневым `,(0,c.jsx)(t.code,{children:`undefined`}),` фактически может вернуть `,(0,c.jsx)(t.code,{children:`undefined`}),`, несмотря на заявленный string contract — не передавайте его.`]}),`
+`]}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`createPersistedJsonCodec<T>()`}),` возвращает `,(0,c.jsx)(t.code,{children:`{ parse, stringify }`}),` для передачи единым контрактом.`]}),`
+`,(0,c.jsx)(t.h2,{id:`rest-adapters`,children:`REST adapters`}),`
+`,(0,c.jsx)(t.h3,{id:`query`,children:`Query`}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`createPersistedRestQueryOperation`}),` принимает:`]}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`buildUrl(scope, args)`}),` — относительный или абсолютный URL;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`optional `,(0,c.jsx)(t.code,{children:`baseUrl`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`optional `,(0,c.jsx)(t.code,{children:`buildInit(scope, args)`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`parseResponse(unknown)`}),` или custom `,(0,c.jsx)(t.code,{children:`executor`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`optional `,(0,c.jsx)(t.code,{children:`transform`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`staleTime`}),`, `,(0,c.jsx)(t.code,{children:`gcTime`}),`, `,(0,c.jsx)(t.code,{children:`isEnabled`}),`.`]}),`
+`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Если нет ни `,(0,c.jsx)(t.code,{children:`executor`}),`, ни `,(0,c.jsx)(t.code,{children:`parseResponse`}),`, operation бросит `,(0,c.jsx)(t.code,{children:`REST persisted operation requires executor or parseResponse.`})]}),`
+`,(0,c.jsxs)(t.p,{children:[`Read signal всегда записывается поверх `,(0,c.jsx)(t.code,{children:`buildInit.signal`}),`, чтобы текущая TanStack Query отменяла именно свой запрос.`]}),`
+`,(0,c.jsx)(t.h3,{id:`mutation`,children:`Mutation`}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`createPersistedRestMutationOperation`}),` поддерживает method `,(0,c.jsx)(t.code,{children:`POST`}),`, `,(0,c.jsx)(t.code,{children:`PUT`}),`, `,(0,c.jsx)(t.code,{children:`DELETE`}),`.`]}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`bodyMapper(scope, input)`}),` создаёт JSON body;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`если mapper отсутствует/вернул `,(0,c.jsx)(t.code,{children:`undefined`}),`, body и default Content-Type не задаются;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`иначе body сериализуется и default header равен `,(0,c.jsx)(t.code,{children:`application/json`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`buildInit`}),` применяется после default headers и может полностью заменить headers;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`response обязательно проходит `,(0,c.jsx)(t.code,{children:`parseResponse`}),` или custom executor;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`optional `,(0,c.jsx)(t.code,{children:`transform`}),` строит domain result;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`optional `,(0,c.jsx)(t.code,{children:`cacheStrategy`}),` прикрепляется к operation.`]}),`
+`]}),`
+`,(0,c.jsxs)(t.p,{children:[`REST adapter использует нейтральный `,(0,c.jsx)(t.code,{children:`/http`}),`: SAP SSO/X-CSRF policy здесь нет.`]}),`
+`,(0,c.jsx)(t.h2,{id:`odata-adapters`,children:`OData adapters`}),`
+`,(0,c.jsxs)(t.p,{children:[`OData operations используют metadata-aware transport из `,(0,c.jsx)(t.a,{href:`../odata/README.mdx`,children:(0,c.jsx)(t.code,{children:`/odata`})}),`.`]}),`
+`,(0,c.jsx)(t.h3,{id:`query-collection`,children:`Query collection`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const list = createPersistedODataQueryOperation<
+	ViewScope,
+	void,
+	SavedViewRecord[]
+>({
+	odata: { service: "Z_VIEW_CONFIG_SRV", target: "ViewSet" },
+	buildOptions: (scope) => ({
+		expression: createFilterEqual("UserId", scope.userId)
+	}),
+	transform: (rows) => rows
+});
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Доступные options factory: `,(0,c.jsx)(t.code,{children:`odata`}),`, optional `,(0,c.jsx)(t.code,{children:`baseUrl`}),`, `,(0,c.jsx)(t.code,{children:`buildParams`}),`, `,(0,c.jsx)(t.code,{children:`buildOptions`}),`, `,(0,c.jsx)(t.code,{children:`buildInit`}),`, `,(0,c.jsx)(t.code,{children:`transform`}),`, `,(0,c.jsx)(t.code,{children:`executor`}),`, `,(0,c.jsx)(t.code,{children:`staleTime`}),`, `,(0,c.jsx)(t.code,{children:`gcTime`}),`, `,(0,c.jsx)(t.code,{children:`meta`}),`, `,(0,c.jsx)(t.code,{children:`isEnabled`}),`.`]}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`createPersistedODataQueryOperation`}),` использует semantic method `,(0,c.jsx)(t.code,{children:`query`}),` и возвращает collection response data. `,(0,c.jsx)(t.code,{children:`createPersistedODataReadOperation`}),` использует `,(0,c.jsx)(t.code,{children:`read`}),` для одной entity по key parameters:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const latest = createPersistedODataReadOperation({
+	odata: { service: "Z_VIEW_CONFIG_SRV", target: "ViewSet" },
+	buildParams: (scope: ViewScope) => wrapODataParams({
+		UserId: scope.userId,
+		ViewId: scope.viewId
+	}),
+	transform: (record: SavedViewRecord) =>
+		parsePersistedJson<ViewConfig>(record.payload)
+});
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`buildParams`}),` должен возвращать wrapped OData parameters из `,(0,c.jsx)(t.code,{children:`foundation-lib/odata-service`}),`.`]}),`
+`,(0,c.jsx)(t.h3,{id:`mutation-1`,children:`Mutation`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const save = createPersistedODataMutationOperation({
+	odata: { service: "Z_VIEW_CONFIG_SRV", target: "ViewSet" },
+	method: "update",
+	buildParams: (scope: ViewScope) => wrapODataParams({
+		UserId: scope.userId,
+		ViewId: scope.viewId
+	}),
+	bodyMapper: (_scope, input: SaveViewInput) => ({
+		Payload: stringifyPersistedJson(input.payload)
+	}),
+	cacheStrategy: createInvalidatePersistedScopeCacheStrategy()
+});
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Semantic methods:`}),`
+`,(0,c.jsxs)(t.table,{children:[(0,c.jsx)(t.thead,{children:(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.th,{children:`Method`}),(0,c.jsx)(t.th,{children:`Params`}),(0,c.jsx)(t.th,{children:`Body`})]})}),(0,c.jsxs)(t.tbody,{children:[(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`create`})}),(0,c.jsx)(t.td,{children:`запрещены`}),(0,c.jsxs)(t.td,{children:[`обязательный `,(0,c.jsx)(t.code,{children:`bodyMapper`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`update`})}),(0,c.jsxs)(t.td,{children:[`обязательный `,(0,c.jsx)(t.code,{children:`buildParams`})]}),(0,c.jsxs)(t.td,{children:[`обязательный `,(0,c.jsx)(t.code,{children:`bodyMapper`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`delete`})}),(0,c.jsxs)(t.td,{children:[`обязательный `,(0,c.jsx)(t.code,{children:`buildParams`})]}),(0,c.jsx)(t.td,{children:`запрещён`})]})]})]}),`
+`,(0,c.jsxs)(t.p,{children:[`Это OData operation names, а не raw HTTP strings. Не передавайте `,(0,c.jsx)(t.code,{children:`"PUT"`}),`/`,(0,c.jsx)(t.code,{children:`"POST"`}),`.`]}),`
+`,(0,c.jsx)(t.p,{children:`OData adapter наследует metadata validation, SAP cookies, SSO recovery и X-CSRF lifecycle. Query/read получают AbortSignal; mutations — нет в generic contract.`}),`
+`,(0,c.jsx)(t.h2,{id:`custom-и-server-function-operations`,children:`Custom и server-function operations`}),`
+`,(0,c.jsxs)(t.p,{children:[`Descriptor принимает любой object, соответствующий `,(0,c.jsx)(t.code,{children:`PersistedQueryOperation`}),`/`,(0,c.jsx)(t.code,{children:`PersistedMutationOperation`}),`. Server-function factories из `,(0,c.jsx)(t.a,{href:`../server-fn/README.mdx`,children:(0,c.jsx)(t.code,{children:`/server-fn`})}),` возвращают совместимые resource operations и могут быть использованы как capabilities, если их generic contract совпадает.`]}),`
+`,(0,c.jsx)(t.h2,{id:`cache-strategies`,children:`Cache strategies`}),`
+`,(0,c.jsx)(t.h3,{id:`инвалидация-всего-scope`,children:`Инвалидация всего scope`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const invalidate = createInvalidatePersistedScopeCacheStrategy();
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Инвалидирует prefix `,(0,c.jsx)(t.code,{children:`descriptor.keys.scope(scope)`}),`, поэтому затрагивает list/latest/history данного scope.`]}),`
+`,(0,c.jsx)(t.h3,{id:`точечное-обновление`,children:`Точечное обновление`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const setLatest = createSetPersistedQueryDataCacheStrategy({
+	getQueryKey: ({ descriptor, scope }) => descriptor.keys.latest(scope),
+	update: (_current, { result }) => result
+});
+`})}),`
+`,(0,c.jsx)(t.h3,{id:`композиция`,children:`Композиция`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const combined = composePersistedCacheStrategies(setLatest, invalidate);
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Порядок последовательный. Если strategy бросила ошибку, следующие steps и hook `,(0,c.jsx)(t.code,{children:`onSuccess`}),` не выполняются, хотя backend mutation уже могла завершиться.`]}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`applyPersistedCacheStrategy`}),` — низкоуровневый helper для ручного вызова optional strategy.`]}),`
+`,(0,c.jsx)(t.h2,{id:`ошибки-и-безопасность`,children:`Ошибки и безопасность`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[`Scope `,(0,c.jsx)(t.code,{children:`null`}),`/`,(0,c.jsx)(t.code,{children:`undefined`}),` или rejected `,(0,c.jsx)(t.code,{children:`isEnabled`}),` блокирует query и вызывает ошибку при фактическом execution.`]}),`
+`,(0,c.jsxs)(t.li,{children:[`Network payload валидируйте в `,(0,c.jsx)(t.code,{children:`parseResponse`}),`/`,(0,c.jsx)(t.code,{children:`transform`}),`; TypeScript generic не является validator-ом.`]}),`
+`,(0,c.jsx)(t.li,{children:`Не храните secrets в payload/query keys/client persistence.`}),`
+`,(0,c.jsx)(t.li,{children:`Save/create должны быть идемпотентны настолько, насколько это возможно для retry policy.`}),`
+`,(0,c.jsx)(t.li,{children:`Cache update — локальная проекция, backend остаётся source of truth.`}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`parsePersistedJson`}),` подавляет syntax error и возвращает `,(0,c.jsx)(t.code,{children:`null`}),`; различайте «нет payload» и «повреждён payload» на уровне продукта, если это важно.`]}),`
+`]}),`
+`,(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:`Descriptor/keys`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`createPersistedResourceDescriptor`}),`, `,(0,c.jsx)(t.code,{children:`createPersistedRecordKeys`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`React reads`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`usePersistedListQuery`}),`, `,(0,c.jsx)(t.code,{children:`usePersistedLatestQuery`}),`, `,(0,c.jsx)(t.code,{children:`usePersistedHistoryQuery`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Imperative reads`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`getPersistedListData`}),`, `,(0,c.jsx)(t.code,{children:`getPersistedLatestData`}),`, `,(0,c.jsx)(t.code,{children:`getPersistedHistoryData`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Mutations`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`usePersistedSaveMutation`}),`, `,(0,c.jsx)(t.code,{children:`usePersistedCreateMutation`}),`, `,(0,c.jsx)(t.code,{children:`usePersistedDeleteMutation`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Payload`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`parsePersistedJson`}),`, `,(0,c.jsx)(t.code,{children:`stringifyPersistedJson`}),`, `,(0,c.jsx)(t.code,{children:`createPersistedJsonCodec`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`REST adapters`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`createPersistedRestQueryOperation`}),`, `,(0,c.jsx)(t.code,{children:`createPersistedRestMutationOperation`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`OData adapters`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`createPersistedODataQueryOperation`}),`, `,(0,c.jsx)(t.code,{children:`createPersistedODataReadOperation`}),`, `,(0,c.jsx)(t.code,{children:`createPersistedODataMutationOperation`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Cache`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`applyPersistedCacheStrategy`}),`, `,(0,c.jsx)(t.code,{children:`createInvalidatePersistedScopeCacheStrategy`}),`, `,(0,c.jsx)(t.code,{children:`createSetPersistedQueryDataCacheStrategy`}),`, `,(0,c.jsx)(t.code,{children:`composePersistedCacheStrategies`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Names/types`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`PersistedReadOperationName`}),`, `,(0,c.jsx)(t.code,{children:`PersistedWriteOperationName`}),`, `,(0,c.jsx)(t.code,{children:`PersistedOperationName`}),`, `,(0,c.jsx)(t.code,{children:`PersistedPayloadCodec`}),`, `,(0,c.jsx)(t.code,{children:`PersistedRecordKeys`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Operation contracts`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`PersistedQueryOperationContext`}),`, `,(0,c.jsx)(t.code,{children:`PersistedMutationOperationContext`}),`, `,(0,c.jsx)(t.code,{children:`PersistedQueryOperation`}),`, `,(0,c.jsx)(t.code,{children:`PersistedMutationOperation`}),`, `,(0,c.jsx)(t.code,{children:`PersistedOperationCapabilities`}),`, `,(0,c.jsx)(t.code,{children:`PersistedTransportAdapter`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Descriptor/cache contracts`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`PersistedResourceDescriptor`}),`, `,(0,c.jsx)(t.code,{children:`CreatePersistedResourceDescriptorOptions`}),`, `,(0,c.jsx)(t.code,{children:`PersistedCacheStrategyContext`}),`, `,(0,c.jsx)(t.code,{children:`PersistedCacheStrategy`}),`, `,(0,c.jsx)(t.code,{children:`PersistedSetQueryDataStrategyOptions`})]})]})]})]})]})}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-C8E1O7DQ.js

@@ -0,0 +1,230 @@
+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 Lib/Interaction/Context Menu State`}),`
+`,(0,c.jsxs)(t.h1,{id:`состояние-и-anchors-контекстного-меню-через-ryuzaki13react-foundation-libcontext-menu`,children:[`Состояние и anchors контекстного меню через `,(0,c.jsx)(t.code,{children:`@ryuzaki13/react-foundation-lib/context-menu`})]}),`
+`,(0,c.jsx)(t.p,{children:`Модуль описывает открытое/закрытое состояние контекстного меню, источник открытия и два вида anchor: DOM element или экранная точка. Также он создаёт virtual anchor для Floating UI.`}),`
+`,(0,c.jsx)(t.p,{children:`Модуль не содержит React hook и не рисует меню.`}),`
+`,(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%BC%D0%BE%D0%B4%D0%B5%D0%BB%D1%8C-%D0%B4%D0%B0%D0%BD%D0%BD%D1%8B%D1%85`,children:`Модель данных`})}),`
+`,(0,c.jsx)(t.li,{children:(0,c.jsx)(t.a,{href:`#%D0%BF%D0%BE%D0%BB%D1%83%D1%87%D0%B5%D0%BD%D0%B8%D0%B5-%D1%82%D0%BE%D1%87%D0%BA%D0%B8`,children:`Получение точки`})}),`
+`,(0,c.jsx)(t.li,{children:(0,c.jsx)(t.a,{href:`#createvirtualanchor`,children:(0,c.jsx)(t.code,{children:`createVirtualAnchor`})})}),`
+`,(0,c.jsx)(t.li,{children:(0,c.jsx)(t.a,{href:`#state-helpers`,children:`State helpers`})}),`
+`,(0,c.jsx)(t.li,{children:(0,c.jsx)(t.a,{href:`#react-reducer-recipe`,children:`React reducer recipe`})}),`
+`,(0,c.jsx)(t.li,{children:(0,c.jsx)(t.a,{href:`#floating-ui-recipe`,children:`Floating UI recipe`})}),`
+`,(0,c.jsx)(t.li,{children:(0,c.jsx)(t.a,{href:`#%D0%B4%D0%BE%D1%81%D1%82%D1%83%D0%BF%D0%BD%D0%BE%D1%81%D1%82%D1%8C`,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-%D0%B8-%D0%BE%D1%88%D0%B8%D0%B1%D0%BA%D0%B8`,children:`Полный API и ошибки`})}),`
+`]}),`
+`,(0,c.jsx)(t.h2,{id:`назначение-и-границы`,children:`Назначение и границы`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-text`,children:`click/contextmenu/keyboard
+          │
+          ├─ element anchor
+          └─ point {x,y}
+                 │
+                 ▼
+             MenuState
+                 │
+                 ▼
+host React/Floating UI/menu component
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Модуль:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsx)(t.li,{children:`не добавляет event listeners;`}),`
+`,(0,c.jsxs)(t.li,{children:[`не вызывает `,(0,c.jsx)(t.code,{children:`preventDefault`}),`;`]}),`
+`,(0,c.jsx)(t.li,{children:`не хранит global state;`}),`
+`,(0,c.jsx)(t.li,{children:`не позиционирует floating element;`}),`
+`,(0,c.jsx)(t.li,{children:`не закрывает меню по Escape/outside click;`}),`
+`,(0,c.jsx)(t.li,{children:`не управляет focus/ARIA;`}),`
+`,(0,c.jsx)(t.li,{children:`не клонирует DOM elements.`}),`
+`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Готовый visual primitive находится в `,(0,c.jsx)(t.code,{children:`@ryuzaki13/react-foundation-ui/context-menu`}),`.`]}),`
+`,(0,c.jsx)(t.h2,{id:`установка-и-импорт`,children:`Установка и импорт`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import {
+	closeMenu,
+	createVirtualAnchor,
+	getMenuPointFromEvent,
+	getMenuPointFromRect,
+	initialMenuState,
+	openMenu,
+	toggleMenu
+} from "@ryuzaki13/react-foundation-lib/context-menu";
+
+import type {
+	ElementMenuAnchor,
+	MenuAnchor,
+	MenuOpenSource,
+	MenuPoint,
+	MenuState,
+	OpenMenuPayload,
+	PointMenuAnchor
+} from "@ryuzaki13/react-foundation-lib/context-menu";
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Functions pure, но types/anchors используют DOM `,(0,c.jsx)(t.code,{children:`Element`}),`/`,(0,c.jsx)(t.code,{children:`HTMLElement`}),`. Публичный subpath не импортирует Floating UI runtime.`]}),`
+`,(0,c.jsx)(t.h2,{id:`модель-данных`,children:`Модель данных`}),`
+`,(0,c.jsx)(t.h3,{id:`point`,children:`Point`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`interface MenuPoint {
+	x: number;
+	y: number;
+}
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Координаты соответствуют viewport/client coordinates, а не page scroll coordinates.`}),`
+`,(0,c.jsx)(t.h3,{id:`источник-открытия`,children:`Источник открытия`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type MenuOpenSource = "click" | "contextmenu" | "keyboard" | "programmatic";
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Source помогает UI выбирать focus/animation/recovery, но helpers сами не меняют поведение по source.`}),`
+`,(0,c.jsx)(t.h3,{id:`anchors`,children:`Anchors`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type ElementMenuAnchor = {
+	type: "element";
+	element: HTMLElement;
+};
+
+type PointMenuAnchor = {
+	type: "point";
+	point: MenuPoint;
+	contextElement?: Element | null;
+};
+
+type MenuAnchor = ElementMenuAnchor | PointMenuAnchor;
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`contextElement`}),` помогает Floating UI определить document/layout context для virtual element.`]}),`
+`,(0,c.jsx)(t.h3,{id:`state`,children:`State`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`interface MenuState {
+	open: boolean;
+	source: MenuOpenSource | null;
+	anchor: MenuAnchor | null;
+}
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Нормальное закрытое состояние:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`{
+	open: false,
+	source: null,
+	anchor: null
+}
+`})}),`
+`,(0,c.jsx)(t.h2,{id:`получение-точки`,children:`Получение точки`}),`
+`,(0,c.jsx)(t.h3,{id:`getmenupointfromevent`,children:(0,c.jsx)(t.code,{children:`getMenuPointFromEvent`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`function onContextMenu(event: React.MouseEvent<HTMLElement>) {
+	event.preventDefault();
+
+	const point = getMenuPointFromEvent(event);
+	// { x: event.clientX, y: event.clientY }.
+}
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Функции нужен только structural object с `,(0,c.jsx)(t.code,{children:`clientX`}),`/`,(0,c.jsx)(t.code,{children:`clientY`}),`, поэтому подходят native и React mouse events.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Она не вызывает `,(0,c.jsx)(t.code,{children:`preventDefault`}),` и не проверяет finite coordinates.`]}),`
+`,(0,c.jsx)(t.h3,{id:`getmenupointfromrect`,children:(0,c.jsx)(t.code,{children:`getMenuPointFromRect`})}),`
+`,(0,c.jsx)(t.p,{children:`Возвращает геометрический центр rect:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const point = getMenuPointFromRect({
+	left: 10,
+	top: 20,
+	width: 80,
+	height: 40
+});
+// { x: 50, y: 40 }.
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Подходит для keyboard opening от центра `,(0,c.jsx)(t.code,{children:`element.getBoundingClientRect()`}),`:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const point = getMenuPointFromRect(button.getBoundingClientRect());
+`})}),`
+`,(0,c.jsx)(t.h2,{id:`createvirtualanchor`,children:(0,c.jsx)(t.code,{children:`createVirtualAnchor`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Создаёт object с `,(0,c.jsx)(t.code,{children:`getBoundingClientRect`}),`, представляющий точку нулевого размера:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const virtualAnchor = createVirtualAnchor({ x: 120, y: 240 }, triggerElement);
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Возвращаемый rect:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`{
+	x: 120,
+	y: 240,
+	top: 240,
+	left: 120,
+	bottom: 240,
+	right: 120,
+	width: 0,
+	height: 0,
+	toJSON: () => undefined
+}
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Если `,(0,c.jsx)(t.code,{children:`contextElement`}),` равен `,(0,c.jsx)(t.code,{children:`null`}),`/`,(0,c.jsx)(t.code,{children:`undefined`}),`, в результате поле становится `,(0,c.jsx)(t.code,{children:`undefined`}),`.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Point object читается при каждом `,(0,c.jsx)(t.code,{children:`getBoundingClientRect`}),`. Не мутируйте его; создайте новый anchor при изменении координат.`]}),`
+`,(0,c.jsx)(t.h2,{id:`state-helpers`,children:`State helpers`}),`
+`,(0,c.jsx)(t.h3,{id:`initialmenustate`,children:(0,c.jsx)(t.code,{children:`initialMenuState`})}),`
+`,(0,c.jsx)(t.p,{children:`Экспортируется один module-level object. Рассматривайте его как readonly-константу и не мутируйте:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const [state, setState] = useState<MenuState>(initialMenuState);
+`})}),`
+`,(0,c.jsx)(t.h3,{id:`openmenu`,children:(0,c.jsx)(t.code,{children:`openMenu`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const state = openMenu({
+	source: "contextmenu",
+	anchor: {
+		type: "point",
+		point: { x: 100, y: 200 }
+	}
+});
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Всегда возвращает новый state `,(0,c.jsx)(t.code,{children:`{ open: true, source, anchor }`}),`. Anchor/element переносятся по ссылке.`]}),`
+`,(0,c.jsx)(t.h3,{id:`closemenu`,children:(0,c.jsx)(t.code,{children:`closeMenu`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const closed = closeMenu(opened);
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Открытое состояние превращается в canonical closed state. Если `,(0,c.jsx)(t.code,{children:`state.open === false`}),` и `,(0,c.jsx)(t.code,{children:`state.anchor === null`}),`, возвращается исходная ссылка `,(0,c.jsx)(t.code,{children:`state`}),`, что удобно для reducer no-op.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Передавайте согласованное состояние. Если вручную создать `,(0,c.jsx)(t.code,{children:`{ open:false, source:"click", anchor:null }`}),`, `,(0,c.jsx)(t.code,{children:`closeMenu`}),` вернёт его без очистки source.`]}),`
+`,(0,c.jsx)(t.h3,{id:`togglemenu`,children:(0,c.jsx)(t.code,{children:`toggleMenu`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const next = toggleMenu(current, payload);
+`})}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[`если `,(0,c.jsx)(t.code,{children:`current.open === true`}),`, закрывает меню и игнорирует payload;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`если меню закрыто, вызывает `,(0,c.jsx)(t.code,{children:`openMenu(payload)`}),`.`]}),`
+`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Toggle подходит для click button. Для `,(0,c.jsx)(t.code,{children:`contextmenu`}),` чаще нужен явный `,(0,c.jsx)(t.code,{children:`openMenu`}),`, чтобы повторный right-click перемещал anchor, а не закрывал меню.`]}),`
+`,(0,c.jsx)(t.h2,{id:`react-reducer-recipe`,children:`React reducer recipe`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-tsx`,children:`const [menu, setMenu] = useState<MenuState>(initialMenuState);
+
+function handleContextMenu(event: React.MouseEvent<HTMLElement>) {
+	event.preventDefault();
+
+	setMenu(
+		openMenu({
+			source: "contextmenu",
+			anchor: {
+				type: "point",
+				point: getMenuPointFromEvent(event),
+				contextElement: event.currentTarget
+			}
+		})
+	);
+}
+
+function handleClose() {
+	setMenu((current) => closeMenu(current));
+}
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Не сохраняйте `,(0,c.jsx)(t.code,{children:`MenuState`}),` в JSON/localStorage: он может содержать `,(0,c.jsx)(t.code,{children:`HTMLElement`}),`.`]}),`
+`,(0,c.jsx)(t.h2,{id:`floating-ui-recipe`,children:`Floating UI recipe`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const reference =
+	menu.anchor?.type === "element"
+		? menu.anchor.element
+		: menu.anchor?.type === "point"
+			? createVirtualAnchor(menu.anchor.point, menu.anchor.contextElement)
+			: null;
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Передайте `,(0,c.jsx)(t.code,{children:`reference`}),` в public API выбранного Floating UI wrapper. Не импортируйте private package files.`]}),`
+`,(0,c.jsx)(t.h2,{id:`доступность`,children:`Доступность`}),`
+`,(0,c.jsx)(t.p,{children:`Host обязан реализовать:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsx)(t.li,{children:`открытие клавишей Context Menu/Shift+F10 или принятой командой;`}),`
+`,(0,c.jsx)(t.li,{children:`focus первого/выбранного item;`}),`
+`,(0,c.jsx)(t.li,{children:`Arrow/Home/End navigation;`}),`
+`,(0,c.jsx)(t.li,{children:`закрытие по Escape и возврат focus;`}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`role="menu"`}),`/`,(0,c.jsx)(t.code,{children:`menuitem`}),` только если semantics действительно menu;`]}),`
+`,(0,c.jsx)(t.li,{children:`disabled items;`}),`
+`,(0,c.jsx)(t.li,{children:`outside click и focus dismissal;`}),`
+`,(0,c.jsx)(t.li,{children:`сохранение trigger element для keyboard recovery.`}),`
+`]}),`
+`,(0,c.jsx)(t.p,{children:`Для keyboard source element anchor обычно лучше point без pointer coordinates.`}),`
+`,(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:`getMenuPointFromEvent`})}),(0,c.jsx)(t.td,{children:`Читает client coordinates`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`getMenuPointFromRect`})}),(0,c.jsx)(t.td,{children:`Центр rect`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`createVirtualAnchor`})}),(0,c.jsx)(t.td,{children:`Point-like DOMRect provider`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`initialMenuState`})}),(0,c.jsx)(t.td,{children:`Canonical closed state`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`openMenu`})}),(0,c.jsx)(t.td,{children:`Новый opened state`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`closeMenu`})}),(0,c.jsx)(t.td,{children:`Закрывает/очищает state`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`toggleMenu`})}),(0,c.jsxs)(t.td,{children:[`Toggle по `,(0,c.jsx)(t.code,{children:`open`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`MenuPoint`})}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`{ x, y }`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`MenuOpenSource`})}),(0,c.jsx)(t.td,{children:`Источник открытия`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`MenuAnchor`})}),(0,c.jsx)(t.td,{children:`Element/point union`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`MenuState`})}),(0,c.jsx)(t.td,{children:`Полное state`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`OpenMenuPayload`})}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`{ source, anchor }`})})]})]})]}),`
+`,(0,c.jsx)(t.p,{children:`Типичные ошибки:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[`Использовать `,(0,c.jsx)(t.code,{children:`pageX/pageY`}),` вместо client coordinates.`]}),`
+`,(0,c.jsxs)(t.li,{children:[`Вызывать toggle при каждом `,(0,c.jsx)(t.code,{children:`contextmenu`}),` и неожиданно закрывать открытое меню.`]}),`
+`,(0,c.jsxs)(t.li,{children:[`Мутировать `,(0,c.jsx)(t.code,{children:`initialMenuState`}),`.`]}),`
+`,(0,c.jsx)(t.li,{children:`Persist DOM element.`}),`
+`,(0,c.jsx)(t.li,{children:`Считать virtual anchor готовым positioner-ом.`}),`
+`,(0,c.jsx)(t.li,{children:`Не возвращать focus после keyboard menu.`}),`
+`]})]})}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};