@ryuzaki13/react-foundation-ui 1.8.11 → 1.8.13

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

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