@orioncactuscorp/ui 1.12.2 → 1.14.0

package/dist/utils/motion.js

@@ -1,5 +1,5 @@
-import { ocSpring as A } from "./spring.js";
-const f = [
+import { ocSpring as U } from "./spring.js";
+const g = [
   "feedback",
   "fade",
   "reject",
@@ -11,13 +11,13 @@ const f = [
   "gesture",
   "ambient",
   "continuous"
-], w = [
+], S = [
   "change",
   "enter",
   "exit",
   "release",
   "loop"
-], R = ["quick", "normal", "slow"], S = [
+], O = ["quick", "normal", "slow"], T = [
   "auto",
   "preserve",
   "fade",
@@ -94,7 +94,7 @@ const f = [
       release: "cubic-bezier(0.32, 0.72, 0, 1)"
     }
   }
-}, C = o, L = {
+}, Y = o, z = {
   feedback: "feedback",
   fade: "fade",
   reject: "feedback",
@@ -106,7 +106,7 @@ const f = [
   gesture: "feedback",
   ambient: "static",
   continuous: "static"
-}, V = /* @__PURE__ */ new Set([
+}, G = /* @__PURE__ */ new Set([
   "opacity",
   "color",
   "background-color",
@@ -115,13 +115,13 @@ const f = [
   "outline-color",
   "fill",
   "stroke"
-]), Y = {
+]), K = {
   disclosure: { preset: "smooth" },
   surface: { preset: "smooth" },
   sheet: { preset: "smooth" },
   expand: { preset: "smooth" },
   move: { preset: "smooth" }
-}, z = {
+}, H = {
   reject: {
     change: { preset: "smooth" },
     enter: { preset: "smooth" }
@@ -142,39 +142,58 @@ const f = [
     },
     exit: null
   }
-}, U = z, $ = (t, e) => e.includes(t), l = (t, e, r) => {
-  if (!$(e, r))
+}, J = H, Q = (t, e) => e.includes(t), p = (t, e, r) => {
+  if (!Q(e, r))
     throw new Error(`Unknown oc-motion ${t}: ${e}.`);
   return e;
-}, G = (t) => {
+}, W = (t) => {
   if (!Number.isFinite(t) || t < 0)
     throw new Error("oc-motion durationFactor must be a non-negative number.");
   return t;
-}, H = (t) => {
+}, X = (t) => {
   if (t !== void 0) {
     if (!Number.isFinite(t))
       throw new Error("oc-motion extraBounce must be a finite number.");
     return t;
   }
-}, d = (t, e) => {
-  const r = Number.parseFloat(t.trim());
-  return Number.isFinite(r) ? r : e;
-}, i = (t, e) => {
-  const a = t.trim().match(/^(-?\d*\.?\d+)(ms|s)?$/);
-  if (!a) return e;
-  const s = Number.parseFloat(a[1]);
-  return !Number.isFinite(s) || s < 0 ? e : a[2] === "ms" ? s / 1e3 : s;
-}, n = (t, e) => typeof t?.getPropertyValue == "function" ? t.getPropertyValue(e).trim() : "", E = (t, e) => {
+}, l = (t, e) => {
+  if (!Number.isFinite(e) || e < 0)
+    throw new Error(`oc-motion ${t} must be a non-negative finite number.`);
+  return e;
+}, Z = /^\+?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?$/i, d = (t, e, r) => {
+  const i = e.trim();
+  if (!i) return r;
+  if (!Z.test(i))
+    throw new Error(
+      `oc-motion CSS token ${t} must be a non-negative unitless number.`
+    );
+  const a = Number(i);
+  return l(`CSS token ${t}`, a);
+}, R = (t, e) => {
+  const i = t.trim().match(/^(-?\d*\.?\d+)(ms|s)?$/);
+  if (!i) return e;
+  const a = Number.parseFloat(i[1]);
+  return !Number.isFinite(a) || a < 0 ? e : i[2] === "ms" ? a / 1e3 : a;
+}, n = (t, e) => typeof t?.getPropertyValue == "function" ? t.getPropertyValue(e).trim() : "", s = (t, e, r) => {
+  const i = n(t, e);
+  if (!i) return r;
+  const a = R(i, Number.NaN);
+  if (!Number.isFinite(a) || a < 0)
+    throw new Error(
+      `oc-motion CSS token ${e} must be a non-negative finite duration in seconds or milliseconds.`
+    );
+  return a;
+}, w = (t, e) => {
   const r = { ...t };
-  for (const a of f) {
-    const s = e?.[a];
-    s && (r[a] = {
-      ...t[a],
-      ...s
+  for (const i of g) {
+    const a = e?.[i];
+    a && (r[i] = {
+      ...t[i],
+      ...a
     });
   }
   return r;
-}, K = (t) => ({
+}, ee = (t) => ({
   durationFactor: t?.durationFactor ?? o.durationFactor,
   durationFactorReduced: t?.durationFactorReduced ?? o.durationFactorReduced,
   durationFactorPreserve: t?.durationFactorPreserve ?? o.durationFactorPreserve,
@@ -186,7 +205,7 @@ const f = [
     ...o.durationByIntent,
     ...t?.durationByIntent
   },
-  durationByPhase: E(
+  durationByPhase: w(
     o.durationByPhase,
     t?.durationByPhase
   ),
@@ -194,118 +213,141 @@ const f = [
     ...o.timingByIntent,
     ...t?.timingByIntent
   },
-  timingByPhase: E(
+  timingByPhase: w(
     o.timingByPhase,
     t?.timingByPhase
   )
 });
-function N(t) {
+function _(t) {
   const e = t && typeof getComputedStyle == "function" ? getComputedStyle(t) : null;
   return {
     durationFactor: d(
+      "--oc-motion-duration-factor",
       n(e, "--oc-motion-duration-factor"),
       o.durationFactor
     ),
     durationFactorReduced: d(
+      "--oc-motion-duration-factor-reduced",
       n(e, "--oc-motion-duration-factor-reduced"),
       o.durationFactorReduced
     ),
     durationFactorPreserve: d(
+      "--oc-motion-duration-factor-preserve",
       n(e, "--oc-motion-duration-factor-preserve"),
       o.durationFactorPreserve
     ),
     paceFactor: {
       quick: d(
+        "--oc-motion-pace-quick",
         n(e, "--oc-motion-pace-quick"),
         o.paceFactor.quick
       ),
       normal: d(
+        "--oc-motion-pace-normal",
         n(e, "--oc-motion-pace-normal"),
         o.paceFactor.normal
       ),
       slow: d(
+        "--oc-motion-pace-slow",
         n(e, "--oc-motion-pace-slow"),
         o.paceFactor.slow
       )
     },
     durationByIntent: {
-      feedback: i(
-        n(e, "--oc-motion-duration-feedback"),
+      feedback: s(
+        e,
+        "--oc-motion-duration-feedback",
         o.durationByIntent.feedback
       ),
-      fade: i(
-        n(e, "--oc-motion-duration-fade"),
+      fade: s(
+        e,
+        "--oc-motion-duration-fade",
         o.durationByIntent.fade
       ),
-      reject: i(
-        n(e, "--oc-motion-duration-reject"),
+      reject: s(
+        e,
+        "--oc-motion-duration-reject",
         o.durationByIntent.reject
       ),
-      disclosure: i(
-        n(e, "--oc-motion-duration-disclosure"),
+      disclosure: s(
+        e,
+        "--oc-motion-duration-disclosure",
         o.durationByIntent.disclosure
       ),
-      surface: i(
-        n(e, "--oc-motion-duration-surface"),
+      surface: s(
+        e,
+        "--oc-motion-duration-surface",
         o.durationByIntent.surface
       ),
-      sheet: i(
-        n(e, "--oc-motion-duration-sheet"),
+      sheet: s(
+        e,
+        "--oc-motion-duration-sheet",
         o.durationByIntent.sheet
       ),
-      expand: i(
-        n(e, "--oc-motion-duration-expand"),
+      expand: s(
+        e,
+        "--oc-motion-duration-expand",
         o.durationByIntent.expand
       ),
-      move: i(
-        n(e, "--oc-motion-duration-move"),
+      move: s(
+        e,
+        "--oc-motion-duration-move",
         o.durationByIntent.move
       ),
-      gesture: i(
-        n(e, "--oc-motion-duration-gesture"),
+      gesture: s(
+        e,
+        "--oc-motion-duration-gesture",
         o.durationByIntent.gesture
       ),
-      ambient: i(
-        n(e, "--oc-motion-duration-ambient"),
+      ambient: s(
+        e,
+        "--oc-motion-duration-ambient",
         o.durationByIntent.ambient
       ),
-      continuous: i(
-        n(e, "--oc-motion-duration-continuous"),
+      continuous: s(
+        e,
+        "--oc-motion-duration-continuous",
         o.durationByIntent.continuous
       )
     },
     durationByPhase: {
       disclosure: {
-        exit: i(
-          n(e, "--oc-motion-duration-disclosure-exit"),
+        exit: s(
+          e,
+          "--oc-motion-duration-disclosure-exit",
           o.durationByPhase.disclosure?.exit ?? o.durationByIntent.disclosure
         )
       },
       surface: {
-        exit: i(
-          n(e, "--oc-motion-duration-surface-exit"),
+        exit: s(
+          e,
+          "--oc-motion-duration-surface-exit",
           o.durationByPhase.surface?.exit ?? o.durationByIntent.surface
         )
       },
       sheet: {
-        exit: i(
-          n(e, "--oc-motion-duration-sheet-exit"),
+        exit: s(
+          e,
+          "--oc-motion-duration-sheet-exit",
           o.durationByPhase.sheet?.exit ?? o.durationByIntent.sheet
         ),
-        release: i(
-          n(e, "--oc-motion-duration-sheet-release"),
+        release: s(
+          e,
+          "--oc-motion-duration-sheet-release",
           o.durationByPhase.sheet?.release ?? o.durationByIntent.sheet
         )
       },
       expand: {
-        exit: i(
-          n(e, "--oc-motion-duration-expand-exit"),
+        exit: s(
+          e,
+          "--oc-motion-duration-expand-exit",
           o.durationByPhase.expand?.exit ?? o.durationByIntent.expand
         )
       },
       gesture: {
-        release: i(
-          n(e, "--oc-motion-duration-gesture-release"),
+        release: s(
+          e,
+          "--oc-motion-duration-gesture-release",
           o.durationByPhase.gesture?.release ?? o.durationByIntent.gesture
         )
       }
@@ -343,115 +385,132 @@ function N(t) {
     }
   };
 }
-function T(t, e = "auto") {
-  return l("intent", t, f), l("reduced policy", e, S), e === "auto" ? L[t] : e;
+function D(t, e = "auto") {
+  return p("intent", t, g), p("reduced policy", e, T), e === "auto" ? z[t] : e;
 }
-function _(t) {
-  return V.has(t);
+function j(t) {
+  return G.has(t);
 }
-function j({
+function M({
   property: t,
   reducedMotion: e,
   reducedPolicy: r
 }) {
-  return !e || r === "preserve" ? !0 : r === "static" || t === void 0 ? !1 : _(t);
+  return !e || r === "preserve" ? !0 : r === "static" || t === void 0 ? !1 : j(t);
 }
-const O = (t, e, r, a) => t[e]?.[r] ?? a, J = (t, e, r, a) => {
-  const s = U[t], m = s !== void 0 && Object.prototype.hasOwnProperty.call(s, e) ? s[e] : void 0;
+const x = (t, e, r, i) => t[e]?.[r] ?? i, te = (t, e, r, i) => {
+  const a = J[t], m = a !== void 0 && Object.prototype.hasOwnProperty.call(a, e) ? a[e] : void 0;
   if (m === null) return null;
-  const c = m ?? Y[t];
+  const c = m ?? K[t];
   if (c === void 0) return null;
-  const p = r === void 0 ? void 0 : c.propertyExtraBounce?.[r];
+  const f = r === void 0 ? void 0 : c.propertyExtraBounce?.[r];
   return {
     preset: (r === void 0 ? void 0 : c.propertyPreset?.[r]) ?? c.preset,
-    extraBounce: a ?? p ?? c.extraBounce
+    extraBounce: i ?? f ?? c.extraBounce
   };
 };
-function Q({
+function oe({
   intent: t,
   phase: e = "change",
   pace: r = "normal",
-  durationFactor: a = 1,
-  extraBounce: s,
+  durationFactor: i = 1,
+  extraBounce: a,
   reduced: m = "auto",
   reducedMotion: c = !1,
-  property: p,
-  element: h,
-  tokens: D
+  property: f,
+  element: b,
+  tokens: q
 }) {
-  l("intent", t, f), l("phase", e, w), l("pace", r, R);
-  const x = G(a), P = H(s), u = K(
-    D ?? N(h)
-  ), y = T(t, m), b = j({
-    property: p,
+  p("intent", t, g), p("phase", e, S), p("pace", r, O);
+  const I = W(i), F = X(a), u = ee(
+    q ?? _(b)
+  ), B = D(t, m), v = M({
+    property: f,
     reducedMotion: c,
-    reducedPolicy: y
-  }), I = c && y === "preserve" ? u.durationFactorPreserve : c ? u.durationFactorReduced : u.durationFactor, F = O(
-    u.durationByPhase,
-    t,
-    e,
-    u.durationByIntent[t]
-  ), v = u.paceFactor[r], g = b ? F * I * v * x : 0, M = O(
+    reducedPolicy: B
+  }), k = l(
+    "duration factor token",
+    c && B === "preserve" ? u.durationFactorPreserve : c ? u.durationFactorReduced : u.durationFactor
+  ), h = l(
+    "duration token",
+    x(
+      u.durationByPhase,
+      t,
+      e,
+      u.durationByIntent[t]
+    )
+  ), E = l(
+    "pace factor token",
+    u.paceFactor[r]
+  ), A = v ? h * k * E * I : 0, y = l(
+    "effective duration",
+    A
+  ), C = v && y > 0, $ = x(
     u.timingByPhase,
     t,
     e,
     u.timingByIntent[t]
-  ), B = J(
+  ), P = te(
     t,
     e,
-    p,
-    P
-  ), k = B !== null;
-  if (!k && P !== void 0)
+    f,
+    F
+  ), N = P !== null;
+  if (!N && F !== void 0)
     throw new Error(
       "oc-motion extraBounce is only supported for spring-backed motion."
     );
-  const q = g > 0 ? g : F;
+  const V = x(
+    o.durationByPhase,
+    t,
+    e,
+    o.durationByIntent[t]
+  ), L = y > 0 ? y : h > 0 ? h : V;
   return {
     intent: t,
     phase: e,
     pace: r,
     reduced: m,
-    reducedPolicy: y,
+    reducedPolicy: B,
     reducedMotion: c,
-    property: p,
-    durationFactor: x,
-    durationFactorToken: I,
-    paceFactor: v,
-    durationSeconds: g,
-    timingFunction: M,
-    animate: b,
-    springBacked: k,
-    spring: A[B?.preset ?? "smooth"]({
-      duration: q,
-      extraBounce: B?.extraBounce
+    property: f,
+    durationFactor: I,
+    durationFactorToken: k,
+    paceFactor: E,
+    durationSeconds: y,
+    timingFunction: $,
+    animate: C,
+    springBacked: N,
+    spring: U[P?.preset ?? "smooth"]({
+      duration: L,
+      extraBounce: P?.extraBounce
     })
   };
 }
-const X = {
-  intents: f,
-  phases: w,
-  paces: R,
-  reducedPolicies: S,
-  defaultTokens: C,
-  parseDuration: i,
-  readTokens: N,
-  resolve: Q,
-  resolveReducedPolicy: T,
-  isFeedbackSafeProperty: _,
-  shouldAnimateProperty: j
+const re = {
+  intents: g,
+  phases: S,
+  paces: O,
+  reducedPolicies: T,
+  defaultTokens: Y,
+  parseDuration: R,
+  readTokens: _,
+  resolve: oe,
+  resolveReducedPolicy: D,
+  isFeedbackSafeProperty: j,
+  shouldAnimateProperty: M
 };
 export {
-  _ as isOcMotionFeedbackSafeProperty,
-  X as ocMotion,
-  C as ocMotionDefaultTokens,
-  f as ocMotionIntents,
-  R as ocMotionPaces,
-  w as ocMotionPhases,
-  S as ocMotionReducedPolicies,
-  i as parseOcMotionDuration,
-  N as readOcMotionTokens,
-  Q as resolveOcMotion,
-  T as resolveOcMotionReducedPolicy,
-  j as shouldAnimateOcMotionProperty
+  j as isOcMotionFeedbackSafeProperty,
+  re as ocMotion,
+  Y as ocMotionDefaultTokens,
+  g as ocMotionIntents,
+  O as ocMotionPaces,
+  S as ocMotionPhases,
+  T as ocMotionReducedPolicies,
+  R as parseOcMotionDuration,
+  _ as readOcMotionTokens,
+  oe as resolveOcMotion,
+  D as resolveOcMotionReducedPolicy,
+  M as shouldAnimateOcMotionProperty
 };

package/docs/api-conventions.md

@@ -83,8 +83,5 @@ named preset이 아니라 외부 문맥이나 직접 지정한 치수로 크기
 직접·custom·상속 크기가 필요한 경우에는 해당 예외의 목적을 컴포넌트 API에
 문서화합니다.
 
-## 현재 호환성 예외: Badge `tiny`
-
-`Badge`의 `size='tiny'`는 표준 named size 밖에 있는 현행 호환성 예외입니다.
-현재 public API는 유지하며, 다음 major 릴리스에서 `xsmall`로 정규화할
-예정입니다. 변경 시 migration note로 안내합니다.
+`Badge`의 작은 preset도 `size='xsmall'`을 사용하므로 모든 named size가 이
+표준 순서를 따릅니다.

package/docs/motion.md

@@ -17,6 +17,10 @@ oc-motion($properties, $intent, $phase, $pace)
 
 React runtime에서 height/expand처럼 CSS transition만으로 안정적으로 다루기 어려운 motion은 `@orioncactuscorp/ui/utils/motion`과 `@orioncactuscorp/ui/react/motion` subpath를 사용합니다. 이 runtime layer도 같은 intent, phase, pace, reduced-motion policy, `--oc-motion-duration-factor*` token vocabulary를 공유하고, 실제 프레임 계산은 low-level `ocSpring` engine에 위임합니다.
 
+Runtime motion도 CSS helper와 동일하게 최종 계산 duration이 `0`이면 spring을 시작하지 않고 최종 상태로 즉시 완료합니다. instance factor, global factor token, intent duration, phase duration 중 어느 값으로 `0`이 만들어져도 같은 계약을 적용합니다. `resolveOcMotion`을 직접 사용하는 consumer는 `animate`가 `true`일 때만 반환된 `spring`을 scheduler에 전달해야 합니다.
+
+Runtime duration, duration factor, pace factor는 모두 `0` 이상의 유한한 값이어야 합니다. CSS의 factor/pace token은 표준 CSS `<number>` 형태의 단위 없는 숫자만 허용하므로 `+1.2`, `5e-1` 같은 표기는 유효하지만, `1s`, `0px`, 숫자 뒤 임의 문자열처럼 CSS 계산과 runtime 해석이 달라질 수 있는 값은 설정 오류로 처리합니다. 여러 multiplier를 곱한 최종 duration이 overflow로 비유한 값이 되는 경우(예: 매우 큰 programmatic factor 조합)도 오류입니다.
+
 ## 빠른 시작
 
 ```scss

package/docs/selector-contract.md

@@ -54,6 +54,15 @@
 
 variant(`light`/`normal`/`strong`)는 `--oc-interaction-opacity-*` 토큰 값만 바꿉니다.
 
+## Badge 계약
+
+| Component | Root selector               | Visual selectors                                                                                          | Stable parts |
+| --------- | --------------------------- | --------------------------------------------------------------------------------------------------------- | ------------ |
+| `Badge`   | `data-oc-component="badge"` | `data-oc-variant="normal\|accent\|overlay"`, `data-oc-size="xsmall\|small"`, `data-oc-interactive="true"` | `content`    |
+
+`Badge`의 작은 named size는 `data-oc-size="xsmall"`을 사용합니다. 이전
+`data-oc-size="tiny"` 값은 major 변경으로 제거됐습니다.
+
 ## Field 레이아웃 계약
 
 `Field`는 label/control/message compound 구조를 유지한 채 vertical/horizontal orientation을 노출합니다.
@@ -198,6 +207,53 @@ Tab content는 inline padding 없이 배치되고 배경색이 transparent인 se
 - `data-oc-scrollable="true"`는 body에 보이는 scrollport 밖 overflow가 있다는 뜻입니다. 이 상태에서 직속 footer `ActionArea`는 block-end padding을 유지하고 `--oc-action-area-padding-block-start: 0`을 받으며, 대응하는 block-start 간격은 body에 예약됩니다.
 - `ActionAreaLayout.ActionArea background="auto"`는 scroll 상태를 자식 `ActionArea`의 background 계약에 매핑합니다: body가 스크롤 가능하고 바닥에 닿지 않은 동안만 `data-oc-background="true"`가 방출됩니다. `data-oc-background`는 시각 gradient/background 상태이며 body 예약의 근거로 사용하지 마세요.
 
+## FloatingWindow 계약
+
+FloatingWindow는 anchor 기반 geometry와 dialog 시맨틱을 Modal 기본 surface presentation에 결합합니다. 기본 `FloatingWindowRoot`는 modeless이고 `ModalWindowRoot`는 modal focus 정책, 배경 입력을 차단하는 backdrop, Modal popup scale/fade motion을 적용합니다. ModalWindow backdrop은 기본적으로 렌더링하며 필요한 경우 `backdrop="hidden"`으로 시각적 dimmer만 숨길 수 있습니다.
+
+| Layer/slot  | Selector                                                                   | 책임                                         |
+| ----------- | -------------------------------------------------------------------------- | -------------------------------------------- |
+| Backdrop    | `data-oc-component="floating-window-backdrop"` + `data-oc-part="backdrop"` | ModalWindow 기본 dimmer와 배경 pointer 차단  |
+| Positioner  | `data-oc-component="floating-window-positioner"`                           | fixed positioning과 manager 주입 stack level |
+| Window      | `data-oc-component="floating-window"` + `data-oc-part="window"`            | dialog 시맨틱과 anchor/free 좌표             |
+| Drag handle | `data-oc-part="drag-handle"` + `data-oc-draggable="true\|false"`           | 명시적인 pointer drag 시작 영역              |
+| Surface     | `data-oc-part="surface-motion"` + `data-oc-part="surface"`                 | Modal popup presentation과 `data-oc-resize`  |
+| Header      | `data-oc-component="modal-header"`                                         | Modal 기본 header slot                       |
+| Navigation  | `data-oc-component="modal-navigation-section"`                             | Modal 기본 disclosure navigation             |
+| Body        | `data-oc-component="modal-body"`                                           | Modal 기본 scrollable body                   |
+| Footer      | `data-oc-component="modal-footer"`                                         | Modal 기본 footer slot                       |
+| Close       | `data-oc-component="modal-close"`                                          | dialog close action                          |
+
+Window은 `data-oc-positioned="true\|false"`, `data-oc-window-positioning="anchored\|free"`, `data-oc-window-presentation="floating\|modal"`, `data-oc-window-modality="modeless\|trap-focus\|modal"`, `data-oc-side`, `data-oc-alignment`를 노출합니다. presentation은 사용한 Root 구성을 구분하는 호환 메타데이터이며 모든 presentation은 동일한 Modal popup surface motion을 사용합니다. modality는 focus와 background interaction 계약을 나타냅니다. pointer drag 중에는 `data-oc-window-dragging="true"`가 설정됩니다. `data-oc-side`는 collision flip 뒤 실제 side이고, `data-oc-alignment`는 alignment flip 뒤의 semantic alignment입니다. alignment shift는 같은 alignment 의도를 유지한 채 좌표만 boundary 안으로 보정합니다.
+
+Drag handle 내부의 `button`, `a`, form control, `contenteditable` 요소는 drag를 시작하지 않습니다. 그 밖의 custom interactive target은 `data-oc-window-no-drag`로 같은 동작을 선언할 수 있습니다. 이 attribute는 drag gesture의 opt-out 계약이며 시각 selector가 아닙니다.
+
+Manager는 일반 pointer와 focus intent를 window activation으로 해석하지만 `data-oc-part="close"` intent는 activation에서 제외합니다. 따라서 클릭 가능한 비활성 modeless window의 Close는 stack 순서를 바꾸지 않고 해당 위치에서 종료 모션을 실행합니다. modal backdrop과 inert 영역 뒤의 window는 이 예외와 관계없이 상호작용할 수 없습니다.
+
+`FloatingWindowHeader`와 `FloatingWindowNavigationSection`은 surface 최상단을 소유하는 대체 관계의 chrome입니다. 기본 조합에서는 둘을 함께 렌더링하지 않습니다. `FloatingWindowNavigationSection`은 기본적으로 title을 dialog title로 등록하며, 별도의 custom title owner를 제공할 때만 `titleAsDialogTitle={false}`를 사용합니다.
+
+modeless `FloatingWindowRoot`는 열릴 때 현재 focus를 유지합니다. `ModalWindowRoot`는 Modal과 같은 초기 focus resolver를 사용해 등록된 visible title을 우선하고, title이 없으면 첫 tabbable 요소로 fallback합니다. 이 정책은 DOM상 close button이 먼저 있다는 이유만으로 닫기 동작을 자동 강조하지 않기 위한 dialog interaction 계약입니다.
+
+FloatingWindow surface 크기·radius·padding은 Modal의 `--oc-modal-*` popup 계약을 사용합니다. `resize="fixed"`는 Modal fixed surface와 같은 내부 body scroll contract를 활성화하며, surface의 `data-oc-scrollable`, Header의 `data-oc-sticky`, Footer의 `data-oc-background`를 실제 scroll state에 맞춰 갱신합니다. Footer의 ActionArea 조합은 Modal과 같은 direct-child selector 계약을 사용합니다.
+
+`FloatingWindowManager` 안의 window는 고유한 `windowId`로 등록되며 다음 managed state를 노출합니다.
+
+| Selector                            | 의미                                         |
+| ----------------------------------- | -------------------------------------------- |
+| `[data-oc-window-active='true']`    | 현재 manager stack의 활성 window             |
+| `[data-oc-window-active='false']`   | 열려 있지만 비활성인 managed window          |
+| `--oc-floating-window-stack-offset` | manager가 정규화한 backdrop/window 쌍 offset |
+
+Manager는 modeless window보다 modal과 `trap-focus` window를 위에 유지합니다. 동일 modality tier에서는 open, pointer, focus 활성화 순서가 stack을 결정하며 Escape와 outside dismissal은 활성 window 하나에만 허용됩니다. Manager 밖에서는 `data-oc-window-active`를 출력하지 않습니다.
+
+여러 focus-owning window가 열려도 Base UI modal/inert ownership은 활성 window 하나에만 부여됩니다. 비활성 modal과 `trap-focus` window는 요청 modality와 stack tier를 보존하지만 아래에 있는 동안 document inert를 중복 적용하지 않습니다.
+
+| Variable                            | Default                                              | Scope                         |
+| ----------------------------------- | ---------------------------------------------------- | ----------------------------- |
+| `--oc-floating-window-stack-offset` | `0`; `stackLevel` prop이 manager-owned offset을 주입 | backdrop/window stacking pair |
+
+`--oc-floating-window-x`, `--oc-floating-window-y`는 geometry runtime이 소유하는 live 좌표이므로 consumer style override 대상으로 사용하지 않습니다.
+
 ## Modal 레이어 계약
 
 Modal은 transition motion과 시각 clipping을 분리합니다.
@@ -216,6 +272,8 @@ Modal은 transition motion과 시각 clipping을 분리합니다.
 
 시각 커스터마이즈는 `data-oc-part="surface"` 또는 component contract 변수를 대상으로 하세요. `surface-motion`은 transition/placement/drag 동작을 의도적으로 바꿀 때만 대상입니다.
 
+Modal의 기본 `initialFocus="auto"`는 `ModalHeader`의 visible title을 `tabIndex={-1}`인 정적 문맥 시작점으로 사용합니다. title이 없으면 첫 tabbable 요소로 fallback합니다. `first-interactive`, `title`, ref/function으로 업무 의미에 맞는 대상을 명시할 수 있으며, 되돌리기 어려운 확인 dialog는 가장 덜 파괴적인 action을 지정하는 것이 권장됩니다. title focus는 일반 Tab 순서에 추가되지 않으며 첫 Tab부터 기존 control 순환이 시작됩니다.
+
 - `ModalContent`의 `className`은 motion layer, visual surface, bottom fill 세 레이어에 적용됩니다 — 공개 `--oc-modal-*` 변수 override가 layout 계산까지 도달하게 하기 위함입니다. `style`은 visual surface에 적용되며, `style`의 CSS custom property는 motion/bottom fill 레이어로도 전달됩니다.
 - `data-starting-style`/`data-ending-style`은 Base UI가 motion layer에 방출합니다.
 - `data-oc-modal-backdrop="hidden"`으로 정착하면 backdrop 레이어는 렌더링되지 않습니다. 전환 중 잠시 남는 exiting backdrop 요소에 layout/hit-testing/커스터마이즈를 의존하지 마세요.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orioncactuscorp/ui",
-  "version": "1.12.2",
+  "version": "1.14.0",
   "description": "orioncactus UI foundations and core primitives",
   "private": false,
   "type": "module",
@@ -126,7 +126,7 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "@orioncactuscorp/icons": "^1.12.2",
+    "@orioncactuscorp/icons": "^1.13.0",
     "@base-ui-components/react": "^1.0.0-rc.0"
   }
 }