@orioncactuscorp/ui 1.15.1 → 1.17.0

package/docs/selector-contract.md

@@ -18,7 +18,7 @@
 /* 예: invalid 상태의 TextInput content 표면 커스터마이즈 */
 [data-oc-component='text-input'][data-oc-invalid='true']
   [data-oc-part='content'] {
-  --oc-text-input-border-color: var(--oc-color-theme-status-negative);
+  --oc-field-control-stroke-color: var(--oc-color-theme-status-negative);
 }
 ```
 
@@ -30,7 +30,8 @@
 
 ## Override가 동작하는 방식
 
-- 컴포넌트 소스는 루트 modifier selector를 `:where(...)`로 낮은 specificity로 유지합니다. 나중에 로드되는 consumer 클래스 하나로 루트 레벨 `--oc-*` component contract 변수를 덮을 수 있습니다.
+- 공개 component contract 변수는 property fallback 또는 `--_-{component}-*` internal default를 통해 기본값을 제공합니다. 따라서 per-component CSS chunk가 consumer CSS보다 나중에 로드되어도 consumer host class의 값이 유지됩니다.
+- 컴포넌트 소스는 루트 modifier selector를 `:where(...)`로 낮은 specificity로 유지합니다. consumer 클래스 하나로 루트 레벨의 공개 `--oc-*` component contract 변수를 덮을 수 있습니다.
 - 스타일 override는 paint property를 직접 재선언하기보다 컴포넌트가 노출하는 contract 변수(`--oc-{component}-*`)를 덮는 방식을 우선하세요. 상태 전이·모션과의 일관성이 유지됩니다.
 - 방향성 계약(`--oc-*` 변수, `data-oc-*` 값, prop)은 물리 방향(top/right/bottom/left)이 아니라 논리 방향(`block-start`, `inline-end`, `start`, `end` 등)을 사용합니다. RTL에서 자동으로 뒤집힙니다.
 
@@ -45,6 +46,8 @@
 | `Switch`               | `--oc-switch-background-color`                 | `--oc-switch-color`                 | checked track, thumb            |
 | `BackgroundIconButton` | `--oc-background-icon-button-background-color` | `--oc-background-icon-button-color` | 모든 variant의 background, icon |
 
+`BackgroundIconButton`의 disabled 상태는 불투명한 fill 레이어를 컴포넌트 루트 위에 덮어 그립니다. blend mode와 backdrop-filter가 비선형으로 합성되기 때문에, 장식 레이어를 그대로 둔 채 이 레이어의 `opacity`만 올려야 전환이 두 끝 상태의 선형 보간이 되어 중간에 튀지 않습니다. 이 fill 색은 `--oc-background-icon-button-disabled-background-color`로 재정의할 수 있고, 기본값은 `--oc-color-theme-interaction-disable`입니다. disabled에서는 이 레이어가 배경을 덮으므로 `--oc-background-icon-button-background-color` 값은 보이지 않습니다.
+
 ```css
 .darkPrimaryControl {
   --oc-radio-background-color: var(--oc-color-theme-label-strong);
@@ -55,7 +58,7 @@
 
 ## Interaction 프리미티브
 
-`Interaction`은 hover/press/focus 피드백을 그리는 passive 시각 레이어입니다. `pointer-events: none`이고 자기 상태를 갖지 않으며, 부모 컴포넌트가 자기 상태 selector로 자식 Interaction의 opacity를 제어합니다.
+`Interaction`은 hover/press/focus 피드백을 그리는 시각 레이어입니다. 시각 pseudo는 passive이며 부모 컴포넌트가 자기 상태 selector로 Interaction의 opacity를 제어합니다. `self`가 아닌 Interaction은 자기 상태를 만들지 않지만, 선택적으로 확장된 투명 hit pseudo의 pointer event가 host로 버블링될 수 있습니다.
 
 ```scss
 .myControl {
@@ -103,17 +106,59 @@
 | `--oc-interaction-opacity-hover`                      | `--oc-color-global-opacity-5 × resolved factor`  | Interaction이 제공하는 hover 출력값       |
 | `--oc-interaction-opacity-focus`                      | `--oc-color-global-opacity-8 × resolved factor`  | Interaction이 제공하는 focus 출력값       |
 | `--oc-interaction-opacity-active`                     | `--oc-color-global-opacity-12 × resolved factor` | Interaction이 제공하는 active 출력값      |
+| `--oc-interaction-touch-target-min`                   | component별 opt-in, foundation은 `44px`          | host 범위의 최소 pointer hit area         |
 
 `--oc-interaction-opacity-*`는 custom host가 상태 selector에서 읽는 resolved output 계약입니다. 임의 강도를 지정할 때는 이 출력값을 자식 selector로 덮지 말고 host에서 `--oc-interaction-opacity-factor`를 설정하세요.
 
+터치 대상 최소 크기는 foundation `--oc-touch-target-min`의 기본값 `44px`을 사용합니다. Button, button/anchor TextButton, IconButton, BackgroundIconButton, interactive Badge, CheckMark, Checkbox, Radio, Switch는 이 값을 internal default로 선택합니다. 실제 component host에서 `--oc-interaction-touch-target-min`을 지정하면 CSS 로딩 순서와 무관하게 해당 값이 우선하며, `0px`은 Interaction의 기존 geometry 바깥으로 hit area를 확장하지 않습니다. 시각 Interaction의 inset, color, radius, opacity, motion geometry는 터치 영역과 분리되어 유지됩니다.
+
+저수준 custom host는 `<Interaction touchTarget />`으로 hit layer를 opt-in합니다. 이때 `data-oc-touch-target="true"`가 렌더링되며, prop을 생략한 기존 `<Interaction />`은 passive visual layer와 기존 pointer geometry를 그대로 유지합니다.
+
+`button`, `a`, `label`, `summary` 또는 interactive ARIA role host가 `<Interaction touchTarget />`을 직계 자식으로 사용하면 iOS Safari의 native tap highlight와 accidental text selection은 비활성화되고 Interaction feedback이 이를 대체합니다. 링크의 long-press context menu와 브라우저 gesture는 유지하므로 `-webkit-touch-callout`과 `touch-action`은 변경하지 않습니다. Interaction이 더 깊게 중첩되는 custom composition은 실제 interactive host에 `-webkit-tap-highlight-color: transparent`, `user-select: none`, `-webkit-user-select: none`을 직접 선언해야 합니다. 선택 가능한 control label이 필요한 예외는 host class에서 `user-select: text`를 다시 선언할 수 있습니다.
+
+```scss
+.compactAction {
+  --oc-interaction-touch-target-min: 32px;
+}
+
+.largeTouchAction {
+  --oc-interaction-touch-target-min: 48px;
+}
+```
+
+확장 영역은 layout 공간을 만들지 않습니다. oc-ui가 소유한 복합 layout은 형제 hit area가 겹치지 않게 자체 spacing 계약을 사용하며, consumer가 작은 control을 조밀하게 배치할 때는 layout gap을 확보하거나 host별 최소 크기를 조정해야 합니다. host 바깥 hit testing을 위해 기본 적용 대상은 Interaction ancestor에서 overflow clipping을 사용하지 않으며, 시각 radius는 passive visual layer에서 유지합니다. disabled host는 확장 hit area도 비활성화합니다. Tabs는 기존 `--oc-tabs-tab-interaction-margin-inline`과 list gap 계약을, ScrollArea scrollbar는 데스크톱 drag geometry를 우선하므로 44px 기본 확장을 선택하지 않습니다.
+
 ## 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`    |
+| Component | Root selector               | Visual selectors                                                                                                   | Stable parts                                                                 |
+| --------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
+| `Badge`   | `data-oc-component="badge"` | `data-oc-variant="default\|normal\|accent\|overlay"`, `data-oc-size="xsmall\|small"`, `data-oc-interactive="true"` | `content`, `surface`, `surface-default`, `surface-normal`, `surface-overlay` |
 
 `Badge`의 작은 named size는 `data-oc-size="xsmall"`을 사용합니다. 이전
 `data-oc-size="tiny"` 값은 major 변경으로 제거됐습니다.
+`default`가 canonical 기본 variant이며, `normal`은 기존 소비자를 위한 호환
+선택지입니다. variant를 생략하면 `data-oc-variant="default"`가 출력됩니다.
+`default`는 `label-strong` 배경과 `background-normal-normal` 라벨 색을 사용하고,
+`normal`은 기존 `label-alternative` 라벨과 `fill-normal` 배경을 유지합니다.
+
+Badge의 `surface` part는 배경 레이어를 담당하며, `accent` 배경이 사라지고
+`default` 또는 `overlay` 배경이 나타나는 전환을 별도 opacity 레이어로 처리합니다.
+border는 다음 component contract 변수로 조정할 수 있습니다.
+
+| Contract variable         | Default       | 용도              |
+| ------------------------- | ------------- | ----------------- |
+| `--oc-badge-border-width` | `1px`         | inset border 두께 |
+| `--oc-badge-border-color` | `transparent` | inset border 색상 |
+
+border는 Badge의 기존 radius를 따르며 `oc-border` 기반의 고정 all/inset stroke로
+그려집니다. 색상만 지정하면 기본 1px border가 표시되고, width를 함께 override할
+수 있습니다. 예를 들어 다음처럼 색상만 지정할 수 있습니다.
+
+```scss
+.badgeWithBorder {
+  --oc-badge-border-color: var(--oc-color-theme-line-normal-normal);
+}
+```
 
 ## Field 레이아웃 계약
 
@@ -269,15 +314,17 @@ Tab content는 inline padding 없이 배치되고 배경색이 transparent인 se
 
 `ActionAreaLayout`은 스크롤 가능한 body와 고정 footer slot 사이의 scroll 경계를 소유합니다.
 
-| Component                 | Root selector                                   | Visual selectors                               | Stable parts                                                      |
-| ------------------------- | ----------------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------- |
-| `ActionArea`              | `data-oc-component="action-area"`               | `data-oc-variant`, `data-oc-background="true"` | `actions`, `caption`, `extra-slot`, `compact-row`, `compact-slot` |
-| `ActionAreaLayout`        | `data-oc-component="action-area-layout"`        | `data-oc-scrollable="true\|false"`             | -                                                                 |
-| `ActionAreaLayout.Body`   | `data-oc-component="action-area-layout-body"`   | -                                              | `body`                                                            |
-| `ActionAreaLayout.Footer` | `data-oc-component="action-area-layout-footer"` | -                                              | `footer`                                                          |
+| Component                 | Root selector                                   | Visual selectors                                                       | Stable parts                                                      |
+| ------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| `ActionArea`              | `data-oc-component="action-area"`               | `data-oc-variant`, `data-oc-background="true"`, `data-oc-empty="true"` | `actions`, `caption`, `extra-slot`, `compact-row`, `compact-slot` |
+| `ActionAreaLayout`        | `data-oc-component="action-area-layout"`        | `data-oc-scrollable="true\|false"`                                     | -                                                                 |
+| `ActionAreaLayout.Body`   | `data-oc-component="action-area-layout-body"`   | -                                                                      | `body`                                                            |
+| `ActionAreaLayout.Footer` | `data-oc-component="action-area-layout-footer"` | -                                                                      | `footer`                                                          |
 
 - `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 예약의 근거로 사용하지 마세요.
+- 렌더링할 액션, caption, extraContent가 없는 `ActionArea`는 `data-oc-empty="true"`를 방출하고 자체 padding과 background를 접습니다. `ModalFooter`나 `FloatingWindowFooter`의 직속 빈 `ActionArea`는 footer 예약을 `0`으로 만들어 body는 기본 하단 여백만 유지합니다. depth navigation처럼 root에서는 액션이 없고 다음 depth부터 버튼이 생기는 구성에서 Footer를 계속 마운트해 둘 때 사용합니다. 여백이 필요하면 빈 `ActionArea` 대신 명시적 spacer를 두세요.
+- `ModalBody` 또는 같은 presentation frame을 사용하는 `FloatingWindowBody`의 마지막 직속 자식이 `ActionArea`이면 owner surface가 inline padding과 block-end padding을 `0`, desktop action group의 max width를 `none`으로 자동 보정합니다. 본문 padding과 중복되지 않도록 하기 위한 기본값이며, `ActionArea`에 명시한 `--oc-action-area-*` 변수는 이 보정보다 우선합니다. bottom placement의 safe-area 및 footer 예약은 Modal surface/body가 계속 소유합니다.
 
 ## FloatingWindow 계약
 
@@ -362,6 +409,10 @@ Modal의 기본 `initialFocus="auto"`는 `ModalHeader`의 visible title을 `tabI
 - bottom placement에서 소프트 키보드 회피 세션이 활성일 때 viewport 레이어(`data-oc-part="viewport"`)에 `data-oc-modal-keyboard-avoiding="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 계약
+
+`ScrollArea`는 현재 scrollbar 렌더링 경로를 `data-oc-scrollbar-mode="custom | native"`, 공개 표시 정책을 `data-oc-scrollbar-visibility="auto | hidden | hidden-on-touch"`로 제공합니다. `native` 모드에서는 운영체제 scrollbar와 네이티브 스크롤 물리를 유지합니다. `hidden`은 모든 환경에서, `hidden-on-touch`는 터치 환경에서만 스크롤 가능성을 유지한 채 시각적 indicator를 숨깁니다.
+
 ## Provider 소유 예외
 
 다음 non-`data-oc-*` attribute는 컴포넌트 소유 계약이 아니라 외부 provider/foundation 소유입니다.

package/docs/tokens.md

@@ -479,6 +479,12 @@ responsive mode(fluid/stepped/static)에 따라 viewport별 출력이 달라집
 - `--oc-focus-ring-offset`
 - `--oc-focus-ring-width`
 
+## Touch target
+
+레이아웃 크기를 바꾸지 않고 pointer hit area를 확보할 때 사용하는 최소 크기입니다. Interaction host의 `--oc-interaction-touch-target-min` 계약이 이 foundation 기본값을 선택적으로 사용합니다.
+
+- `--oc-touch-target-min`
+
 ## Motion
 
 duration/scale/distance factor는 unitless multiplier입니다. 자세한 정책은 [Semantic Motion](./motion.md)을 참조하세요.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orioncactuscorp/ui",
-  "version": "1.15.1",
+  "version": "1.17.0",
   "description": "orioncactus UI foundations and core primitives",
   "private": false,
   "type": "module",

package/src/scss/foundations/touch.scss

@@ -0,0 +1,3 @@
+:root {
+  --oc-touch-target-min: 44px;
+}

package/src/scss/foundations/touch.test.ts

@@ -0,0 +1,37 @@
+import { compileString } from 'sass';
+import { describe, expect, it } from 'vitest';
+
+describe('touch foundation', () => {
+  it('exposes the minimum touch target token', () => {
+    const result = compileString("@use 'foundations/touch' as *;", {
+      loadPaths: ['src/scss'],
+    });
+
+    expect(result.css).toContain('--oc-touch-target-min: 44px;');
+  });
+
+  it('keeps touch tokens in the full foundation rebuild composition', () => {
+    const result = compileString(
+      `
+      @use 'foundations/responsive.config' with (
+        $oc-responsive-mode: static,
+        $oc-responsive-static-stop: md
+      );
+      @use 'foundations/color.global' as *;
+      @use 'foundations/color.theme.light' as *;
+      @use 'foundations/color.theme.dark' as *;
+      @use 'foundations/breakpoint' as *;
+      @use 'foundations/typo' as *;
+      @use 'foundations/space' as *;
+      @use 'foundations/atomic' as *;
+      @use 'foundations/focus' as *;
+      @use 'foundations/touch' as *;
+      @use 'foundations/motion' as *;
+      @use 'foundations/zindex' as *;
+      `,
+      { loadPaths: ['src/scss'] },
+    );
+
+    expect(result.css).toContain('--oc-touch-target-min: 44px;');
+  });
+});

package/src/scss/foundations/typo.scss

@@ -358,7 +358,7 @@ $oc-typo-responsive-segments: (
 );
 
 /**
- * fluidClamp basis 375px = iPhone standard viewport (iOS HIG body 17pt 호환).
+ * Fluid basis 375px = iPhone standard viewport (iOS HIG body 17pt 호환).
  * iOS 네이티브 앱이 375+ 환경에서 body 17pt를 쓰는 것과 웹의 16px default 간극을
  * vw=375에서 17px 도달로 맞춰 시각적 이질감을 해소한다.
  */

package/src/scss/index.scss

@@ -6,6 +6,7 @@
 @forward './foundations/space';
 @forward './foundations/atomic';
 @forward './foundations/focus';
+@forward './foundations/touch';
 @forward './foundations/motion';
 @forward './foundations/zindex';
 @forward './foundations/reset';

package/src/scss/mixins/_fluid.test.ts

@@ -69,19 +69,3 @@ describe('oc-fluid function', () => {
     ).toThrow("oc-fluid() anchor must be 'from' or 'to'.");
   });
 });
-
-describe('fluidClamp compatibility function', () => {
-  it('preserves the legacy argument order', () => {
-    const css = compileScss(`
-      @use 'utils' as *;
-
-      .legacy {
-        font-size: fluidClamp(toRem(16), 375px, to, toRem(20));
-      }
-    `);
-
-    expect(css).toContain(
-      '.legacy{font-size:clamp(1rem,20/375*100vw,1.25rem)}',
-    );
-  });
-});

package/src/scss/mixins/_utils.scss

@@ -1,7 +1 @@
-@use './fluid' as *;
-
 @forward './units';
-
-@function fluidClamp($from, $bp, $anchor: to, $to) {
-  @return oc-fluid($from, $to, $bp, $anchor);
-}

package/dist/components/Modal/useElementSize.js

@@ -1,23 +0,0 @@
-import { useState as o, useCallback as c, useLayoutEffect as a } from "react";
-function m() {
-  const [e, s] = o(null), [u, r] = o(0), t = c((n) => {
-    if (!n) {
-      r(0);
-      return;
-    }
-    r(n.getBoundingClientRect().height);
-  }, []);
-  return a(() => {
-    if (!e) return;
-    const n = window.requestAnimationFrame(() => t(e));
-    if (typeof ResizeObserver > "u")
-      return () => window.cancelAnimationFrame(n);
-    const i = new ResizeObserver(() => t(e));
-    return i.observe(e), () => {
-      window.cancelAnimationFrame(n), i.disconnect();
-    };
-  }, [t, e]), { node: e, setNode: s, height: u };
-}
-export {
-  m as useMeasuredElement
-};

package/dist/ui/src/components/Modal/useElementSize.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"useElementSize.d.ts","sourceRoot":"","sources":["../../../../../src/components/Modal/useElementSize.ts"],"names":[],"mappings":"AAEA,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,WAAW;;;;EAgCvD"}