@orioncactuscorp/ui 1.17.0 → 1.18.0

package/docs/selector-contract.md

@@ -56,6 +56,8 @@
 }
 ```
 
+`BackgroundIconButton`의 키보드 포커스 링은 본체보다 바깥으로 확장된 배경 크기와 `--oc-background-icon-button-radius`를 따릅니다. 공통 `--oc-focus-ring-width`, `--oc-focus-ring-offset`, `--oc-color-theme-focus-ring` 토큰으로 조정할 수 있습니다. 링은 배경의 clipping이나 Interaction의 opacity에 영향을 받지 않는 독립적인 장식 레이어이며, 버튼의 레이아웃과 터치 영역은 바꾸지 않습니다.
+
 ## Interaction 프리미티브
 
 `Interaction`은 hover/press/focus 피드백을 그리는 시각 레이어입니다. 시각 pseudo는 passive이며 부모 컴포넌트가 자기 상태 selector로 Interaction의 opacity를 제어합니다. `self`가 아닌 Interaction은 자기 상태를 만들지 않지만, 선택적으로 확장된 투명 hit pseudo의 pointer event가 host로 버블링될 수 있습니다.
@@ -396,6 +398,8 @@ Modal의 기본 `initialFocus="auto"`는 `ModalHeader`의 visible title을 `tabI
 - `ModalContent`의 `className`은 motion layer, visual surface, bottom fill 세 레이어에 적용됩니다 — 공개 `--oc-modal-*` 변수 override가 layout 계산까지 도달하게 하기 위함입니다. `style`은 visual surface에 적용되며, `style`의 CSS custom property는 motion/bottom fill 레이어로도 전달됩니다.
 - `ModalHeader bottomContent`는 기본 header row 아래 `data-oc-part="header-bottom"`에 보조 chrome을 렌더링합니다. Modal은 이 slot을 header 높이에 포함하고 `--oc-modal-container-padding-block-start`를 현재 size의 `--oc-modal-container-padding-block`으로 자동 설정해 body와 scroll 시작 간격을 예약합니다. 명시적인 `ModalContent style` 변수는 이 기본값을 override할 수 있습니다.
 - `ModalHeader bottomContent`의 직계 `ProgressIndicator`는 edge-attached navigation chrome으로 취급해 `--oc-progress-indicator-radius: 0`을 자동 적용합니다. 별도 wrapper 없이 slot에 직접 배치하는 구성이 canonical usage입니다.
+- `ModalHeader handle`은 `data-oc-part="handle-area"` 안에 32×4px bar `data-oc-part="handle"`과 Interaction을 렌더링합니다. drag가 활성화되면(`drag='handle'` 또는 `drag='content'`) handle-area는 `data-oc-draggable="true"`가 되어 두 모드에서 공통 pointer hit 영역이 됩니다. fine pointer에서는 surface 좌우 끝까지 닿는 16px 상단 strip, coarse pointer에서는 중앙 72×44px pad입니다. fine pointer의 full-width strip은 header control과 겹치지 않도록 header content의 상단 padding을 strip 높이(16px) 이상으로 보정하며, coarse pointer의 중앙 pad에는 이 보정을 적용하지 않습니다. hover 가능 기기에서 strip에 hover하면 bar가 제자리에서 1.1배(35.2×4.4px)로 커지고 Interaction hover가 켜지며, 누르고 있는 동안에는 drag hook이 handle-area에 `data-oc-state="pressed"`를 내보내 확대, Interaction active, `grabbing` cursor를 release까지 유지합니다. release 시 pointer가 area 위에 남아 있으면 hook이 `data-oc-state="hover"`를 내보내 브라우저의 `:hover` 재평가가 늦어지는 동안(WebKit) 확대 상태를 이어 주고, pointer가 area를 실제로 벗어나면 지웁니다. 확대는 `expand` intent의 smooth spring이며 reduced-motion에서는 scale 없이 tint만 남습니다. `drag='content'`는 handle-area와 header 전체를 같은 chrome drag arbitration으로 처리하고, `drag='handle'`는 handle-area에서만 drag를 시작합니다. 시각 커스터마이즈는 bar 요소(`background-color`, 크기)를 대상으로 하세요. `ModalNavigationSection`의 handle은 navigation row 전체가 drag 영역이므로 handle-area 없이 bar만 렌더링합니다.
+- `ModalHeader`의 자체 영역(title, 빈 공간, handle-area)을 탭하면 body가 sheet 모션 spring으로 맨 위로 스크롤됩니다. iOS status bar 탭이 페이지를 맨 위로 보내는 것과 같은 보조 제스처로, 모달이 페이지 스크롤을 잠근 동안 그 역할을 이어받습니다. 제외 기준은 drag 시작을 막는 기준과 같습니다. 닫기·뒤로 가기 버튼, `trailingContent`/`bottomContent` 안의 컨트롤(button, link, input, `role="button"`·`option`·`radio` 등)과 `data-oc-modal-no-drag`로 표시한 콘텐츠(하위 요소 포함)에서 온 클릭은 제외되고, 소비자 `onClick`이 `preventDefault`하면 건너뜁니다. drag 뒤에 따라오는 click은 drag hook이 취소하므로 동작하지 않으며, body가 이미 맨 위면 아무 일도 하지 않습니다. reduced-motion에서는 즉시 이동합니다. 접근성 트리에는 아무 것도 추가하지 않습니다(header는 여전히 role 없는 chrome이며 스크롤 자체가 기본 수단입니다).
 - `data-starting-style`/`data-ending-style`은 Base UI가 motion layer에 방출합니다.
 - `data-oc-modal-backdrop="hidden"`으로 정착하면 backdrop 레이어는 렌더링되지 않습니다. 전환 중 잠시 남는 exiting backdrop 요소에 layout/hit-testing/커스터마이즈를 의존하지 마세요.
 - `backdropFrom` snap 임계 아래에 정착한 bottom sheet는 backdrop 레이어에 `data-oc-modal-backdrop-passthrough="true"`를 방출합니다. 이 상태는 non-modal이며 배경이 상호작용 가능합니다. attribute는 드래그 프레임 단위가 아니라 정착(rest) 시점에 바뀝니다.
@@ -406,7 +410,7 @@ Modal의 기본 `initialFocus="auto"`는 `ModalHeader`의 visible title을 `tabI
 - `ModalBody layout="fill"`은 header/footer/content padding 예약을 유지한 채 body content slot을 iframe·map·viewer 같은 embedded 표면용 fill container로 바꿉니다.
 - size별 공개 변수: `--oc-modal-small-width`/`--oc-modal-medium-width`/`--oc-modal-large-width`와 `--oc-modal-{size}-padding-*`이 내부 `--oc-modal-container-padding-*` 계약으로 매핑됩니다. header/body/footer padding은 기본적으로 container padding을 상속하며, `--oc-modal-header-padding-*`/`--oc-modal-footer-padding-*`로 slot별 예외를 둘 수 있습니다. edge 정렬 chrome control용으로 `--oc-modal-header-edge-offset-inline`이 있습니다.
 - 닫기 시도가 차단되어 피드백 중일 때 motion layer에 `data-oc-modal-feedback="reject"`가 방출됩니다. transform을 직접 덮지 말고 `--oc-modal-reject-distance` 같은 contract 변수를 사용하세요.
-- bottom placement에서 소프트 키보드 회피 세션이 활성일 때 viewport 레이어(`data-oc-part="viewport"`)에 `data-oc-modal-keyboard-avoiding="true"`가 방출됩니다. 키보드 geometry 추격 transition의 게이트로 쓰이는 내부 지향 상태이며, 소비자는 이 attribute의 방출 타이밍(세션 시작/해제 시점의 지연 포함)에 의존하지 않는 것이 좋습니다.
+- bottom placement에서 소프트 키보드 회피 세션이 활성일 때 viewport 레이어(`data-oc-part="viewport"`)에 `data-oc-modal-keyboard-avoiding="true"`가, 포커스가 떠나 키보드가 닫히는 동안에는 `data-oc-modal-keyboard-closing="true"`가 함께 방출됩니다. 키보드 geometry 추격 transition의 게이트로 쓰이는 내부 지향 상태이며, 소비자는 이 attribute의 방출 타이밍(세션 시작/해제 시점의 지연 포함)에 의존하지 않는 것이 좋습니다.
 - `ModalNavigationSection`은 body content가 아니라 Modal chrome입니다. 루트는 `data-oc-state="open|closed"`, toggle row는 `data-oc-component="modal-navigation"` + `data-oc-part="navigation"` + `aria-expanded`/`aria-controls`, indicator는 `data-oc-part="indicator"`/`indicator-frame`, panel은 `data-oc-component="modal-navigation-panel"`(collapsed 동안 `aria-hidden`/`inert`), panel content는 `data-oc-part="panel-inner"`를 노출합니다.
 
 ## ScrollArea scrollbar 계약

package/docs/spring.md

@@ -380,3 +380,7 @@ runtime animator의 핵심 contract는 velocity continuity입니다. gesture 도
 - gesture, drag, interrupt가 중요한 런타임 상호작용은 `createSpringAnimator` 사용
 - React state target을 따라가야 하면 `useSpringTarget` 사용
 - React component에서 spring 값을 직접 제어해야 하면 `useSpringValue` 사용
+
+## 자유 플링
+
+자유 팬의 단조 감속에는 [ocGesture](./gesture.md)의 마찰 적분을 사용합니다. spring은 초기 속도를 이어받지만 목표 거리와 설정에 따라 이후 가속할 수 있습니다. 예상 정지 위치로 spring 이동하는 것은 자유 감속과 다른 경로입니다. 두 API의 속도 단위는 px/s입니다.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orioncactuscorp/ui",
-  "version": "1.17.0",
+  "version": "1.18.0",
   "description": "orioncactus UI foundations and core primitives",
   "private": false,
   "type": "module",
@@ -69,6 +69,10 @@
     "./react/motion": {
       "types": "./dist/react/motion.d.ts",
       "import": "./dist/react/motion.js"
+    },
+    "./utils/gesture": {
+      "types": "./dist/utils/gesture.d.ts",
+      "import": "./dist/utils/gesture.js"
     }
   },
   "peerDependencies": {