@pgcorp/ui-kit 0.12.0 → 0.14.0

package/docs/resize.md

@@ -0,0 +1,129 @@
+# Изменение размеров панелей
+
+`SResizeHandle` владеет native `button` с `role="separator"`, pointer capture,
+клавиатурой, hitbox и interaction lease для cursor/selection. `SDockRegion`
+композирует этот leaf и определяет семантический результат dock gesture.
+Consumer хранит размер и его persistent preference; собственные pointer
+listeners и расчёт pointer delta не требуются.
+
+## Публичные типы
+
+```ts
+import type {
+  SResizeHandleCancel,
+  SResizeHandleCancelReason,
+  SResizeHandleCompletion,
+  SResizeHandleHitbox,
+  SDockRegionCollapse,
+} from '@pgcorp/ui-kit/layout/types'
+```
+
+Эти типы доступны также в корневом type export пакета. `SResizeHandle` сохраняет
+type exports через путь своего компонента.
+
+`hitbox` принимает `compact` (6 px), `standard` (12 px) или `spacious` (32 px).
+По умолчанию inline separator использует `compact`, overlay — `spacious`.
+`SDockRegion.hitbox` передаёт ту же семантическую ступень native владельцу.
+
+## Pointer transaction
+
+| Событие | Payload | Контракт |
+| --- | --- | --- |
+| `resize-start` | `PointerEvent` | Начало pointer preview |
+| `resize` | `number` | Preview, ограниченный текущим `min/max` |
+| `resize-end` | `number`, `SResizeHandleCompletion` | Принятие конечной координаты `pointerup` |
+| `resize-cancel` | `SResizeHandleCancel` | Отмена без `resize-end` |
+
+`SResizeHandleCompletion` содержит `source: 'pointer'`, `startValue` и
+`unclampedValue`. Логический intent вычисляется leaf-компонентом с axis,
+`valueDirection` и `pointerScale` gesture. Ограничение применяется по актуальному
+`min/max`; `pointerup` учитывается даже без предшествующего `pointermove`.
+
+`SResizeHandleCancel` содержит `initialValue`, последний ограниченный
+`latestValue` и точную `reason`: `pointercancel`, `lostpointercapture`,
+`window-blur`, `disabled`, `superseded` или `unmount`. Все listeners, capture и
+interaction lease освобождаются при завершении и отмене. Отмена соответствует
+[Pointer Events: pointercancel и lostpointercapture](https://www.w3.org/TR/pointerevents3/).
+
+Consumer применяет `resize` к preview. В `resize-end` он принимает размер и
+сохраняет preference. `initialValue` — отображаемый размер на старте, а не
+сохранённая preference: адаптивная рабочая область может ограничивать её своим
+диапазоном. В `resize-cancel` consumer восстанавливает отображаемый snapshot в
+актуальной host geometry; persistence preference восстанавливается из его
+собственного transaction snapshot, не из `initialValue`. Отменённый preview
+не сохраняется. На время pointer transaction persistent watcher должен быть
+отделён от preview state. Клавиатурные Arrow/Home/End являются
+дискретным `resize` без pointer transaction, `resize-end` или `resize-cancel`.
+
+```vue
+<SDockRegion
+  placement="left"
+  :visible="visible"
+  :size="size"
+  :min-size="200"
+  :max-size="maxSize"
+  hitbox="standard"
+  @resize-start="beginSizeTransaction"
+  @resize="previewSize"
+  @resize-end="commitSizeTransaction"
+  @resize-cancel="cancelSizeTransaction"
+>
+  <ProjectPanel />
+</SDockRegion>
+```
+
+Размер, min/max, step и pointerScale должны быть конечными числами; размер
+находится в min/max, `min <= max`, `step > 0` и `pointerScale > 0`. Consumer
+передаёт согласованный диапазон при изменении рабочей области. Некорректный
+диапазон отклоняется с `RangeError`; компонент не исправляет входные данные.
+
+## Сворачивание dock
+
+`SDockRegion.collapseThreshold` включает сворачивание только для committed
+pointer release. Порог — конечное число `0 <= collapseThreshold < minSize`.
+Preview остаётся ограниченным `minSize`; временно непригодная узкая панель не
+рендерится.
+
+Если конечный `unclampedValue` строго ниже порога, dock эмитит только
+`collapse({ preferredSize: startValue })`, без конкурирующего `resize-end`.
+В остальных случаях он передаёт `resize-end` и completion. Consumer закрывает
+панель по `collapse` и сохраняет `preferredSize` для повторного открытия.
+Pointer cancellation не вызывает `collapse`. Keyboard Home устанавливает
+`minSize` и не сворачивает панель.
+
+```vue
+<SDockRegion
+  placement="left"
+  :visible="visible"
+  :size="size"
+  :min-size="200"
+  :max-size="maxSize"
+  :collapse-threshold="80"
+  hitbox="standard"
+  @resize-start="beginSizeTransaction"
+  @resize="previewSize"
+  @resize-end="commitSizeTransaction"
+  @resize-cancel="cancelSizeTransaction"
+  @collapse="collapseSizeTransaction"
+>
+  <ProjectPanel />
+</SDockRegion>
+```
+
+Без `collapseThreshold` dock не сворачивается при перетаскивании. Для правой
+панели можно оставить `minSize=240`, динамический `maxSize` и отключённый порог.
+
+## Составные владельцы
+
+`SSidebarGroup` хранит pointer geometry preview локально. `update-sections`
+передаёт принятую controlled preference после commit, а не на каждом move.
+Отмена восстанавливает snapshot всей участвующей группы без persistence
+события. Удаление секции освобождает её активную transaction. Клавиатура
+передаёт дискретное изменение через `update-sections`.
+
+`SWorkbenchPanelShell` восстанавливает secondary size через тот же cancel
+payload; его диапазон принадлежит текущей рабочей области. Consumers используют
+эти owners, а не создают собственный drag engine.
+
+Storybook: `SResizeHandle/PointerTouchAndConcurrentLifecycle` и
+`SDockRegion/CompanionDocks`, `CompanionDocksDark`, `CompanionDocksNarrow`.