@ryuzaki13/react-foundation-lib 1.4.0 → 1.4.2

package/src/bounded-copy-stack/README.mdx

@@ -0,0 +1,257 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="Foundation Lib/Data/Bounded Copy Stack" />
+
+# Ограниченный стек копий через `@ryuzaki13/react-foundation-lib/bounded-copy-stack`
+
+Модуль хранит небольшой список последних скопированных сущностей. Новый элемент помещается в начало, повтор по `fingerprint` обновляет существующую запись, а старые записи удаляются при превышении лимита.
+
+Документ рассчитан на разработчика без доступа к исходникам пакета. Ниже объясняются структура элемента, различие `id` и `fingerprint`, порядок записей, ссылки на payload и все граничные случаи.
+
+## Содержание
+
+- [Назначение и границы](#назначение-и-границы)
+- [Установка и импорт](#установка-и-импорт)
+- [Основные понятия](#основные-понятия)
+- [Быстрый старт](#быстрый-старт)
+- [`pushBoundedCopyStackItem`](#pushboundedcopystackitem)
+- [`getBoundedCopyStackCandidates`](#getboundedcopystackcandidates)
+- [Ссылки, хранение и сериализация](#ссылки-хранение-и-сериализация)
+- [Полный API](#полный-api)
+- [Типичные ошибки](#типичные-ошибки)
+
+## Назначение и границы
+
+Типичный сценарий — показать пользователю несколько последних вариантов для повторной вставки:
+
+```text
+копирование A ──► [A]
+копирование B ──► [B, A]
+повтор A       ──► [новая A, B]
+копирование C  ──► [C, новая A, B]
+копирование D  ──► [D, C, новая A]  при maxSize = 3
+```
+
+Модуль:
+
+- не использует системный clipboard;
+- не сохраняет список в storage;
+- не создаёт React state или Zustand store;
+- не клонирует `payload` и `meta`;
+- не сравнивает payload глубоко;
+- не нормализует данные;
+- не выполняет вставку выбранного кандидата.
+
+Clipboard helpers находятся в `@ryuzaki13/react-foundation-lib/copy`. Владелец state/storage находится в host-приложении.
+
+## Установка и импорт
+
+```bash
+npm install @ryuzaki13/react-foundation-lib
+```
+
+```ts
+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";
+```
+
+Корневой и глубокий импорты не поддерживаются. Модуль ESM, не зависит от React и browser APIs.
+
+## Основные понятия
+
+### Элемент стека
+
+```ts
+type BoundedCopyStackItem<TPayload, TMeta = undefined> = {
+	id: string;
+	fingerprint: string;
+	payload: TPayload;
+	meta: TMeta;
+	copiedAt: number;
+};
+```
+
+| Поле          | Назначение                                                                 |
+| ------------- | -------------------------------------------------------------------------- |
+| `id`          | Идентификатор конкретной записи/операции копирования                       |
+| `fingerprint` | Идентичность содержимого для удаления повторов                             |
+| `payload`     | Данные, которые host затем сможет вставить                                 |
+| `meta`        | Подпись, тип, источник или другая информация для UI                        |
+| `copiedAt`    | Время копирования в миллисекундах Unix; функция не сортирует по этому полю |
+
+`id` и `fingerprint` решают разные задачи. При повторном копировании содержимого `fingerprint` остаётся прежним, а `id`, `payload`, `meta` и `copiedAt` могут стать новыми.
+
+### Порядок
+
+Индекс `0` всегда содержит элемент последней операции `push`. Функция доверяет входному порядку и не сортирует список по `copiedAt`.
+
+## Быстрый старт
+
+```ts
+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() на момент вызова.
+```
+
+## `pushBoundedCopyStackItem`
+
+```ts
+const result = pushBoundedCopyStackItem(items, input, { maxSize: 3 });
+```
+
+Алгоритм:
+
+1. Создаёт новый элемент из `input`.
+2. Если `copiedAt` отсутствует, подставляет `Date.now()`.
+3. Ищет любой элемент с точно равным `fingerprint`.
+4. Удаляет из старого списка все элементы с таким fingerprint.
+5. Помещает новый элемент в начало.
+6. Обрезает результат до `maxSize`.
+
+Входной массив не изменяется. Возвращается новый массив.
+
+### Повторный fingerprint
+
+```ts
+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.
+```
+
+Сравнение fingerprint регистрозависимое и использует `===`. Строки `"A"` и `"a"` различны.
+
+### Нормализация `maxSize`
+
+Default `DEFAULT_BOUNDED_COPY_STACK_SIZE` равен `3`.
+
+| Переданное значение                  | Фактический лимит |
+| ------------------------------------ | ----------------: |
+| `undefined`, `NaN`, `Infinity`       |                 3 |
+| `5.9`                                |                 5 |
+| `1`                                  |                 1 |
+| `0`, отрицательное конечное значение |                 1 |
+
+Полностью отключить хранение через `maxSize: 0` нельзя. Если список не нужен, host должен не вызывать push или хранить пустой state самостоятельно.
+
+### Результат
+
+```ts
+type BoundedCopyStackPushResult<TPayload, TMeta> = {
+	items: BoundedCopyStackItem<TPayload, TMeta>[];
+	addedItem: BoundedCopyStackItem<TPayload, TMeta>;
+	updatedExisting: boolean;
+};
+```
+
+- `items` — итоговый ограниченный список;
+- `addedItem` — созданная запись, даже если из-за будущей логики host её не сохранит;
+- `updatedExisting` — был ли во входном списке такой fingerprint.
+
+## `getBoundedCopyStackCandidates`
+
+Функция фильтрует записи предикатом и сохраняет исходный порядок:
+
+```ts
+const tableCandidates = getBoundedCopyStackCandidates(stack, (item) => item.meta.kind === "table-column");
+```
+
+Она эквивалентна типизированному `items.filter(predicate)`:
+
+- возвращает новый массив;
+- не клонирует элементы;
+- не изменяет исходный массив;
+- не ограничивает количество дополнительно;
+- исключение из predicate пробрасывается вызывающему коду.
+
+## Ссылки, хранение и сериализация
+
+`payload` и `meta` переносятся по ссылке:
+
+```ts
+const payload = { nested: { value: 1 } };
+const result = pushBoundedCopyStackItem([], {
+	id: "1",
+	fingerprint: "one",
+	payload,
+	meta: undefined
+});
+
+console.log(result.addedItem.payload === payload); // true.
+```
+
+Если нужна независимая data-only копия, создайте её через `deepCopyWithoutFunctions` из `/utils` до push. Clone не должен нормализовать данные.
+
+Для `localStorage`/`sessionStorage` host самостоятельно отвечает за:
+
+- JSON-compatible payload/meta;
+- версию persisted schema;
+- runtime-проверку восстановленных данных;
+- удаление устаревших записей;
+- отсутствие секретов и персональных данных.
+
+## Полный API
+
+| Export                            | Назначение                                       |
+| --------------------------------- | ------------------------------------------------ |
+| `DEFAULT_BOUNDED_COPY_STACK_SIZE` | Default-лимит `3`                                |
+| `pushBoundedCopyStackItem`        | Добавляет/обновляет запись и ограничивает список |
+| `getBoundedCopyStackCandidates`   | Фильтрует кандидатов                             |
+| `BoundedCopyStackItem`            | Полная сохранённая запись                        |
+| `BoundedCopyStackPushInput`       | Вход push; `copiedAt` optional                   |
+| `BoundedCopyStackOptions`         | `{ maxSize?: number }`                           |
+| `BoundedCopyStackPushResult`      | Итоговый список и сведения об операции           |
+
+## Типичные ошибки
+
+- Использовать уникальный `id` как fingerprint: дубликаты содержимого никогда не объединятся.
+- Ожидать сортировку по `copiedAt`: порядок определяется вызовами push.
+- Мутировать `payload` после push и ожидать snapshot: ссылка общая.
+- Передавать `maxSize: 0` для отключения: получится лимит `1`.
+- Хранить callback/DOM node в persisted stack: модуль не делает данные сериализуемыми.
+- Вызывать helper вместо clipboard API: стек ничего не копирует в ОС.

package/src/context-menu/README.mdx

@@ -0,0 +1,326 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="Foundation Lib/Interaction/Context Menu State" />
+
+# Состояние и anchors контекстного меню через `@ryuzaki13/react-foundation-lib/context-menu`
+
+Модуль описывает открытое/закрытое состояние контекстного меню, источник открытия и два вида anchor: DOM element или экранная точка. Также он создаёт virtual anchor для Floating UI.
+
+Модуль не содержит React hook и не рисует меню.
+
+## Содержание
+
+- [Назначение и границы](#назначение-и-границы)
+- [Установка и импорт](#установка-и-импорт)
+- [Модель данных](#модель-данных)
+- [Получение точки](#получение-точки)
+- [`createVirtualAnchor`](#createvirtualanchor)
+- [State helpers](#state-helpers)
+- [React reducer recipe](#react-reducer-recipe)
+- [Floating UI recipe](#floating-ui-recipe)
+- [Доступность](#доступность)
+- [Полный API и ошибки](#полный-api-и-ошибки)
+
+## Назначение и границы
+
+```text
+click/contextmenu/keyboard
+          │
+          ├─ element anchor
+          └─ point {x,y}
+                 │
+                 ▼
+             MenuState
+                 │
+                 ▼
+host React/Floating UI/menu component
+```
+
+Модуль:
+
+- не добавляет event listeners;
+- не вызывает `preventDefault`;
+- не хранит global state;
+- не позиционирует floating element;
+- не закрывает меню по Escape/outside click;
+- не управляет focus/ARIA;
+- не клонирует DOM elements.
+
+Готовый visual primitive находится в `@ryuzaki13/react-foundation-ui/context-menu`.
+
+## Установка и импорт
+
+```ts
+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";
+```
+
+Functions pure, но types/anchors используют DOM `Element`/`HTMLElement`. Публичный subpath не импортирует Floating UI runtime.
+
+## Модель данных
+
+### Point
+
+```ts
+interface MenuPoint {
+	x: number;
+	y: number;
+}
+```
+
+Координаты соответствуют viewport/client coordinates, а не page scroll coordinates.
+
+### Источник открытия
+
+```ts
+type MenuOpenSource = "click" | "contextmenu" | "keyboard" | "programmatic";
+```
+
+Source помогает UI выбирать focus/animation/recovery, но helpers сами не меняют поведение по source.
+
+### Anchors
+
+```ts
+type ElementMenuAnchor = {
+	type: "element";
+	element: HTMLElement;
+};
+
+type PointMenuAnchor = {
+	type: "point";
+	point: MenuPoint;
+	contextElement?: Element | null;
+};
+
+type MenuAnchor = ElementMenuAnchor | PointMenuAnchor;
+```
+
+`contextElement` помогает Floating UI определить document/layout context для virtual element.
+
+### State
+
+```ts
+interface MenuState {
+	open: boolean;
+	source: MenuOpenSource | null;
+	anchor: MenuAnchor | null;
+}
+```
+
+Нормальное закрытое состояние:
+
+```ts
+{
+	open: false,
+	source: null,
+	anchor: null
+}
+```
+
+## Получение точки
+
+### `getMenuPointFromEvent`
+
+```ts
+function onContextMenu(event: React.MouseEvent<HTMLElement>) {
+	event.preventDefault();
+
+	const point = getMenuPointFromEvent(event);
+	// { x: event.clientX, y: event.clientY }.
+}
+```
+
+Функции нужен только structural object с `clientX`/`clientY`, поэтому подходят native и React mouse events.
+
+Она не вызывает `preventDefault` и не проверяет finite coordinates.
+
+### `getMenuPointFromRect`
+
+Возвращает геометрический центр rect:
+
+```ts
+const point = getMenuPointFromRect({
+	left: 10,
+	top: 20,
+	width: 80,
+	height: 40
+});
+// { x: 50, y: 40 }.
+```
+
+Подходит для keyboard opening от центра `element.getBoundingClientRect()`:
+
+```ts
+const point = getMenuPointFromRect(button.getBoundingClientRect());
+```
+
+## `createVirtualAnchor`
+
+Создаёт object с `getBoundingClientRect`, представляющий точку нулевого размера:
+
+```ts
+const virtualAnchor = createVirtualAnchor({ x: 120, y: 240 }, triggerElement);
+```
+
+Возвращаемый rect:
+
+```ts
+{
+	x: 120,
+	y: 240,
+	top: 240,
+	left: 120,
+	bottom: 240,
+	right: 120,
+	width: 0,
+	height: 0,
+	toJSON: () => undefined
+}
+```
+
+Если `contextElement` равен `null`/`undefined`, в результате поле становится `undefined`.
+
+Point object читается при каждом `getBoundingClientRect`. Не мутируйте его; создайте новый anchor при изменении координат.
+
+## State helpers
+
+### `initialMenuState`
+
+Экспортируется один module-level object. Рассматривайте его как readonly-константу и не мутируйте:
+
+```ts
+const [state, setState] = useState<MenuState>(initialMenuState);
+```
+
+### `openMenu`
+
+```ts
+const state = openMenu({
+	source: "contextmenu",
+	anchor: {
+		type: "point",
+		point: { x: 100, y: 200 }
+	}
+});
+```
+
+Всегда возвращает новый state `{ open: true, source, anchor }`. Anchor/element переносятся по ссылке.
+
+### `closeMenu`
+
+```ts
+const closed = closeMenu(opened);
+```
+
+Открытое состояние превращается в canonical closed state. Если `state.open === false` и `state.anchor === null`, возвращается исходная ссылка `state`, что удобно для reducer no-op.
+
+Передавайте согласованное состояние. Если вручную создать `{ open:false, source:"click", anchor:null }`, `closeMenu` вернёт его без очистки source.
+
+### `toggleMenu`
+
+```ts
+const next = toggleMenu(current, payload);
+```
+
+- если `current.open === true`, закрывает меню и игнорирует payload;
+- если меню закрыто, вызывает `openMenu(payload)`.
+
+Toggle подходит для click button. Для `contextmenu` чаще нужен явный `openMenu`, чтобы повторный right-click перемещал anchor, а не закрывал меню.
+
+## React reducer recipe
+
+```tsx
+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));
+}
+```
+
+Не сохраняйте `MenuState` в JSON/localStorage: он может содержать `HTMLElement`.
+
+## Floating UI recipe
+
+```ts
+const reference =
+	menu.anchor?.type === "element"
+		? menu.anchor.element
+		: menu.anchor?.type === "point"
+			? createVirtualAnchor(menu.anchor.point, menu.anchor.contextElement)
+			: null;
+```
+
+Передайте `reference` в public API выбранного Floating UI wrapper. Не импортируйте private package files.
+
+## Доступность
+
+Host обязан реализовать:
+
+- открытие клавишей Context Menu/Shift+F10 или принятой командой;
+- focus первого/выбранного item;
+- Arrow/Home/End navigation;
+- закрытие по Escape и возврат focus;
+- `role="menu"`/`menuitem` только если semantics действительно menu;
+- disabled items;
+- outside click и focus dismissal;
+- сохранение trigger element для keyboard recovery.
+
+Для keyboard source element anchor обычно лучше point без pointer coordinates.
+
+## Полный API и ошибки
+
+| Export                  | Назначение                  |
+| ----------------------- | --------------------------- |
+| `getMenuPointFromEvent` | Читает client coordinates   |
+| `getMenuPointFromRect`  | Центр rect                  |
+| `createVirtualAnchor`   | Point-like DOMRect provider |
+| `initialMenuState`      | Canonical closed state      |
+| `openMenu`              | Новый opened state          |
+| `closeMenu`             | Закрывает/очищает state     |
+| `toggleMenu`            | Toggle по `open`            |
+| `MenuPoint`             | `{ x, y }`                  |
+| `MenuOpenSource`        | Источник открытия           |
+| `MenuAnchor`            | Element/point union         |
+| `MenuState`             | Полное state                |
+| `OpenMenuPayload`       | `{ source, anchor }`        |
+
+Типичные ошибки:
+
+- Использовать `pageX/pageY` вместо client coordinates.
+- Вызывать toggle при каждом `contextmenu` и неожиданно закрывать открытое меню.
+- Мутировать `initialMenuState`.
+- Persist DOM element.
+- Считать virtual anchor готовым positioner-ом.
+- Не возвращать focus после keyboard menu.