@orioncactuscorp/ui 1.0.0 → 1.1.0

package/README.md

@@ -2,15 +2,42 @@
 
 orioncactus 디자인 시스템의 React 19+ UI package입니다.
 
-## Install
+## 요구사항
+
+- React 19+, React DOM 19+
+- Node 22+
+- CSS Modules와 CSS `@layer`를 처리하는 bundler
+- package manager: npm-compatible package manager
+
+## 설치
+
+##### bun
 
 ```bash
 bun add @orioncactuscorp/ui @orioncactuscorp/icons
 ```
 
+##### npm
+
+```bash
+npm install @orioncactuscorp/ui @orioncactuscorp/icons
+```
+
+##### yarn
+
+```bash
+yarn add @orioncactuscorp/ui @orioncactuscorp/icons
+```
+
+##### pnpm
+
+```bash
+pnpm add @orioncactuscorp/ui @orioncactuscorp/icons
+```
+
 앱 코드에서 아이콘을 직접 import한다면 `@orioncactuscorp/icons`를 consumer repository의 direct dependency로 함께 설치하세요. `@orioncactuscorp/ui` 컴포넌트 내부 indicator만 사용한다면 별도 작업은 필요 없습니다.
 
-## Usage
+## 사용
 
 ```tsx
 import '@orioncactuscorp/ui/foundations.css';
@@ -64,6 +91,117 @@ export default function Example() {
 - `@orioncactuscorp/ui/react/spring`
 - `@orioncactuscorp/ui/react/motion`
 
+## React Server Components
+
+`@orioncactuscorp/ui`는 root barrel 전체를 client boundary로 승격하지 않고, 실제 client-only component/module entry에만 `'use client'` directive를 보존합니다. Next App Router Server Component에서 root barrel로 `Button` 같은 interactive component를 import해도 leaf boundary가 유지되도록 package build에서 검증합니다.
+
+Client Component에 전달하는 prop은 React Server Components의 serializable prop 제약을 따릅니다. Server Component에서 `onClick` 같은 function prop을 직접 넘겨야 하는 경우에는 해당 사용 지점을 Client Component로 분리하세요.
+
+## Foundation
+
+일반적인 사용은 prebuilt CSS를 앱 root에서 한 번 import합니다.
+
+```tsx
+import '@orioncactuscorp/ui/foundations.css';
+import '@orioncactuscorp/ui/styles.css';
+```
+
+브랜드 색처럼 CSS token 값만 바꾸는 경우에는 import 이후 로드되는 CSS에서 필요한 theme selector의 `--oc-*` 값을 override합니다.
+
+```scss
+:root,
+[data-theme='light'],
+[data-theme='dark'] {
+  --oc-color-theme-primary-normal: #ff5800;
+}
+```
+
+Foundation별 커스텀 방식은 아래 기준으로 나눕니다.
+
+| 대상   | 기본 방식                                                 | SCSS source compile 필요 여부                    |
+| ------ | --------------------------------------------------------- | ------------------------------------------------ |
+| color  | `--oc-color-theme-*` override                             | theme 출력 범위나 system preference 설정 변경 시 |
+| typo   | `$oc-typo-size-overrides`, `$oc-typo-height-overrides`    | 필요                                             |
+| space  | `$oc-space-overrides`                                     | 필요                                             |
+| atomic | radius, width, blur, shadow 같은 `--oc-atomic-*` override | 보통 불필요                                      |
+
+`--oc-typo-scale`은 특정 요소나 section 안의 typography를 함께 키우거나 줄일 때 쓰는 runtime multiplier입니다. 예를 들어 article 영역의 읽기 크기를 전반적으로 키워야 할 때 해당 scope에 `--oc-typo-scale: 1.1`처럼 지정할 수 있습니다.
+
+Typography나 spacing token의 responsive 출력 방식까지 바꿔야 하는 경우에는 `foundations.css` 대신 SCSS foundation source를 직접 compile할 수 있습니다. 이때 `foundations.css`를 대체하므로 reset은 별도로 import합니다.
+
+```tsx
+import '@orioncactuscorp/ui/reset.css';
+import './styles/foundations.scss';
+import '@orioncactuscorp/ui/styles.css';
+```
+
+### SCSS Profile
+
+`responsive.config`는 `typo`와 `space`의 responsive 출력 mode를 정합니다. `$oc-responsive-mode`는 공통으로 적용하고, active stop range는 foundation별로 따로 지정할 수 있습니다. `space`는 stepped mode에서 base/media point별 target stop도 지정할 수 있습니다.
+
+`$oc-responsive-mode`는 아래 값을 사용합니다.
+
+- `fluid`: 기본값. stop 사이를 `clamp()` 기반 fluid value로 보간합니다.
+- `stepped`: stop 값을 breakpoint에서 계단식으로 전환합니다.
+- `static`: 선택한 stop 하나를 전체 viewport에 고정합니다.
+
+```scss
+@use '@orioncactuscorp/ui/scss/foundations/responsive.config' with (
+  $oc-responsive-mode: stepped,
+  $oc-responsive-typo-stops: (
+    sm,
+  ),
+  $oc-responsive-space-stops: (
+    md,
+    lg,
+    xl,
+  ),
+  $oc-responsive-space-profile: (
+    type: stepped-points,
+    points: (
+      base: md,
+      min-md: max-active-defined,
+    ),
+  )
+);
+
+@use '@orioncactuscorp/ui/scss/foundations/color.global' as *;
+@use '@orioncactuscorp/ui/scss/foundations/color.theme.light' as *;
+@use '@orioncactuscorp/ui/scss/foundations/color.theme.dark' as *;
+@use '@orioncactuscorp/ui/scss/foundations/breakpoint' as *;
+@use '@orioncactuscorp/ui/scss/foundations/typo' as * with (
+  $oc-typo-size-overrides: (
+    title1: (
+      sm: 36,
+    ),
+  ),
+  $oc-typo-height-overrides: (
+    title1: (
+      sm: 48,
+    ),
+  )
+);
+@use '@orioncactuscorp/ui/scss/foundations/space' as * with (
+  $oc-space-overrides: (
+    section-padding-viewport-x: (
+      md: 20,
+      xl: 32,
+    ),
+  )
+);
+@use '@orioncactuscorp/ui/scss/foundations/atomic' as *;
+@use '@orioncactuscorp/ui/scss/foundations/motion' as *;
+@use '@orioncactuscorp/ui/scss/foundations/zindex' as *;
+
+:root,
+[data-theme='light'],
+[data-theme='dark'] {
+  --oc-color-theme-primary-normal: #ff5800;
+}
+```
+
+SCSS foundation profile은 compile-time 설정입니다. Prebuilt `foundations.css` 또는 `styles.css` import에는 적용되지 않습니다.
+
 ## Icons
 
 `@orioncactuscorp/ui`는 `@orioncactuscorp/icons`를 dependency로 사용합니다. `Checkbox`, `Radio`, `Select`, `Accordion`, `ModalClose` 같은 컴포넌트 내부 indicator를 별도 설정 없이 렌더링합니다.
@@ -78,9 +216,13 @@ import { IconClose, IconDefault } from '@orioncactuscorp/icons';
 
 아이콘 세트를 나중에 교체할 계획이 있으면, 컴포넌트마다 직접 import하지 말고 앱 내부 icon registry를 거쳐 import하세요.
 
-## Semantic Motion
+## Motion
+
+Motion은 duration/easing 숫자를 직접 고르는 대신 `feedback`, `reveal`, `move` 같은 intent 기준으로 작성합니다. `oc-motion`은 intent, phase, pace를 기반으로 duration token, spring profile, reduced-motion 정책을 함께 적용합니다.
 
-SCSS consumer는 `oc-motion`으로 transition을 intent 기준으로 작성합니다. `feedback`, `reveal`, `move` 같은 의미를 선택하면 `oc-motion`이 duration token, spring profile, reduced-motion 정책을 함께 적용합니다.
+```scss
+@include oc-motion($properties, $intent, $phase: change, $pace: normal);
+```
 
 ```scss
 @use '@orioncactuscorp/ui/scss/mixins/motion' as *;
@@ -94,15 +236,52 @@ SCSS consumer는 `oc-motion`으로 transition을 intent 기준으로 작성합
 }
 ```
 
-일반 컴포넌트와 consumer SCSS에서는 `oc-motion`을 우선 사용하고, 직접 spring parameter를 설계해야 하는 고급 케이스에서만 `oc-spring`을 사용합니다. intent, phase, pace, reduced-motion policy, token override 기준은 [docs/oc-motion.md](https://github.com/orioncactuscorp/orioncactus-ui/blob/main/docs/oc-motion.md)를 참고하세요.
+일반 컴포넌트와 consumer SCSS에서는 `oc-motion`을 우선 사용하고, 직접 spring parameter를 설계해야 하는 고급 케이스에서만 `oc-spring`을 사용합니다.
+
+### Motion Scale
 
-## Spring Motion
+Motion scale은 transform scale, 이동 거리, duration의 전역 강도를 조정하는 runtime token입니다. 기본값보다 작으면 효과가 약해지거나 짧아지고, 크면 효과가 강해지거나 길어집니다. 전체 tone은 parent token으로 먼저 맞추고, 특정 intent만 달라야 할 때 child token을 override합니다.
+
+| Token                                 | 기본값                            | 비고                                   |
+| ------------------------------------- | --------------------------------- | -------------------------------------- |
+| `--oc-motion-scale`                   | `1`                               | 전체 transform scale amplitude         |
+| `--oc-motion-scale-feedback`          | `var(--oc-motion-scale)`          | press, hover, selected                 |
+| `--oc-motion-scale-reveal`            | `var(--oc-motion-scale)`          | menu, tooltip, modal                   |
+| `--oc-motion-distance-scale`          | `1`                               | 전체 translate/reject 거리             |
+| `--oc-motion-distance-scale-reject`   | `var(--oc-motion-distance-scale)` | reject shake                           |
+| `--oc-motion-distance-scale-reveal`   | `var(--oc-motion-distance-scale)` | reveal, move                           |
+| `--oc-motion-duration-scale`          | `1`                               | 전체 duration. 작으면 빠르고 크면 느림 |
+| `--oc-motion-duration-scale-reduced`  | `0.75`                            | reduced-motion fade/feedback           |
+| `--oc-motion-duration-scale-preserve` | `1`                               | reduced-motion preserve                |
+| `--oc-motion-pace-quick`              | `0.75`                            | `quick` pace duration multiplier       |
+| `--oc-motion-pace-normal`             | `1`                               | `normal` pace duration multiplier      |
+| `--oc-motion-pace-slow`               | `1.35`                            | `slow` pace duration multiplier        |
+
+### Runtime Motion
+
+React에서 height/reveal처럼 CSS transition만으로 안정적으로 다루기 어려운 motion은 `@orioncactuscorp/ui/react/motion` subpath를 사용합니다. `MotionReveal`은 같은 `intent`, `phase`, `pace`, `reduced` vocabulary로 layout size를 JS spring animation에 연결합니다.
+
+```tsx
+import { MotionReveal } from '@orioncactuscorp/ui/react/motion';
+
+export function Panel({ open, children }) {
+  return (
+    <MotionReveal open={open} forceMount intent='reveal' pace='normal'>
+      {children}
+    </MotionReveal>
+  );
+}
+```
+
+## Spring
 
 SCSS에서는 iOS spring의 perceptual duration 기준으로 low-level transition을 작성할 수 있습니다. helper는 실제 CSS duration을 감쇠 settling duration으로 출력합니다.
 
 ```scss
-@use '@orioncactuscorp/ui/scss/spring' as *;
+transition: oc-spring($property, $duration, $preset: smooth, $extra-bounce: 0);
+```
 
+```scss
 .box {
   transition: oc-spring(transform, 0.5s, snappy);
 }
@@ -128,7 +307,7 @@ SCSS에서는 iOS spring의 perceptual duration 기준으로 low-level transitio
 }
 ```
 
-property별 tuple은 `(duration, preset, extra-bounce, delay, samples)` 순서입니다. physical spring과 고급 옵션은 named map을 사용합니다. 자세한 사용법과 Sass named argument 주의점은 [docs/spring.md](https://github.com/orioncactuscorp/orioncactus-ui/blob/main/docs/spring.md)를 참고하세요.
+property별 tuple은 `(duration, preset, extra-bounce, delay, samples)` 순서입니다. physical spring과 고급 옵션은 named map을 사용합니다.
 
 TS 런타임에서는 subpath util을 사용합니다.
 
@@ -183,38 +362,6 @@ export function Follower() {
 }
 ```
 
-runtime reveal이나 height motion이 필요한 React component에서는 `react/motion` subpath를 사용합니다. 이 layer는 `utils/motion`의 intent/phase/pace/reduced-motion 정책을 해석한 뒤 low-level `ocSpring` animator에 연결합니다.
-
-```tsx
-import { MotionReveal } from '@orioncactuscorp/ui/react/motion';
-import { ocMotion } from '@orioncactuscorp/ui/utils/motion';
-
-const motion = ocMotion.resolve({
-  intent: 'reveal',
-  phase: 'enter',
-  pace: 'normal',
-});
-
-export function Panel({ open, children }) {
-  return (
-    <MotionReveal open={open} forceMount>
-      {children}
-    </MotionReveal>
-  );
-}
-```
-
-## Responsive Foundation Profile
-
-`@orioncactuscorp/ui/scss/foundations/responsive.config`는 SCSS consumer가 `typo`와 `space` responsive token 출력 방식을 선택할 때 사용합니다. mode는 공통으로 적용하고, `$oc-responsive-typo-stops`와 `$oc-responsive-space-stops`로 foundation별 active stop range를 따로 지정할 수 있습니다. `space`는 `$oc-responsive-space-profile`로 stepped 출력 profile도 바꿀 수 있습니다.
-
-- `fluid`: 기본 `fluidClamp()` 출력
-- `stepped`: active stop별 고정 token 값 출력
-- `static`: 명시 stop 또는 각 foundation의 첫 active stop으로 고정
-- `space profile`: `$oc-responsive-mode: stepped`에서 `stepped-points`로 base/media point별 target stop 출력
-
-이 설정은 compile-time SCSS profile입니다. Prebuilt `foundations.css` 또는 `styles.css` import에는 적용되지 않습니다. 예시는 [docs/responsive-foundation-profile.md](../../docs/responsive-foundation-profile.md)를 참고하세요.
-
 ## VS Code CSS Variable Autocomplete
 
 package는 VS Code CSS variable autocomplete 확장이 읽을 수 있는 foundation token index를 함께 배포합니다.
@@ -235,39 +382,10 @@ consumer repository에서 `phoenisx.cssvar` 확장을 사용할 경우 `.vscode/
 
 이 파일은 `foundations.css`에서 생성되므로 설치된 `@orioncactuscorp/ui` package 버전의 `--oc-*` foundation token과 자동완성 목록이 함께 움직입니다. 자동완성 전용 index이므로 runtime stylesheet로 import하지 않습니다.
 
-## Agent Setup
-
-package에는 내부 Agent instruction artifact를 포함하지 않습니다. consumer repository에서 oc-ui 사용 지침을 세팅할 때는 아래 public-safe prompt를 Agent에게 붙여넣으세요.
-
-```text
-This repository uses @orioncactuscorp/ui.
-
-Set up or update this repository's agent instructions for oc-ui usage.
-
-Use the installed package and public package docs as the source of truth:
-- package.json
-- node_modules/@orioncactuscorp/ui/package.json
-- node_modules/@orioncactuscorp/ui/README.md
-- node_modules/@orioncactuscorp/icons/package.json
-- node_modules/@orioncactuscorp/icons/README.md
-
-Inspect this repository's AGENTS.md and CLAUDE.md files if they exist.
-Preserve repository-local rules.
-Do not overwrite existing project conventions.
-Report conflicts before editing instructions.
-
-Document:
-- where @orioncactuscorp/ui/foundations.css and @orioncactuscorp/ui/styles.css are imported
-- whether this repository uses prebuilt CSS or SCSS source customization
-- whether icons are imported directly from @orioncactuscorp/icons
-- which local components should prefer oc-ui primitives
-
-Do not assume access to private orioncactus agent documents.
-Do not use the latest upstream main branch as the convention source unless I explicitly ask for that comparison.
-```
+## 참고
 
-긴 초기 세팅 가이드는 repository 문서의 `docs/agent-setup.md`를 기준으로 관리합니다.
+- [wanteddev/montage-web](https://github.com/wanteddev/montage-web): foundation, component state, slot, accessibility, interaction 설계 참고
 
-## License
+## 라이선스
 
 MIT

package/dist/components/ActionArea/ActionArea.css

@@ -1 +1 @@
-.oc-ActionArea-module__actionArea__jnxep{position:relative;display:flex;flex-direction:column;inline-size:100%;padding:var(--oc-action-area-padding-y) var(--oc-action-area-padding-x) var(--oc-action-area-padding-bottom);--oc-action-area-padding-x: var(--oc-space-section-padding-viewport-x);--oc-action-area-padding-y: var(--oc-space-section-padding-viewport-y);--oc-action-area-padding-bottom: var(--oc-action-area-padding-y);--oc-action-area-gap: var(--oc-space-item-gap-small);--oc-action-area-actions-gap: var(--oc-space-item-gap-small);--oc-action-area-background-color: var(--oc-color-theme-background-elevated-normal)}.oc-ActionArea-module__actionArea__jnxep:before{position:absolute;inset:0;z-index:0;background:linear-gradient(to bottom,transparent,var(--oc-action-area-background-color) 45%);opacity:0;content:"";pointer-events:none}.oc-ActionArea-module__actionArea__jnxep>*{position:relative;z-index:1}.oc-ActionArea-module__actionArea__jnxep[data-oc-background=true]:before{opacity:1}.oc-ActionArea-module__actionArea__jnxep[data-oc-has-extra=true]{border-block-start:1px solid var(--oc-color-theme-line-normal-neutral);background-color:var(--oc-action-area-background-color)}.oc-ActionArea-module__actionArea__jnxep [data-oc-part=extra-slot]{display:flex;flex-direction:column;align-items:center;margin-block-end:calc(var(--oc-action-area-gap) + var(--oc-action-area-padding-y))}.oc-ActionArea-module__actionArea__jnxep [data-oc-part=caption]{font-size:calc(var(--oc-typo-size-label2) * var(--oc-typo-scale, 1));line-height:calc(var(--oc-typo-height-label2) * var(--oc-typo-scale, 1));letter-spacing:var(--oc-typo-spacing-label2);font-weight:var(--oc-typo-weight-label2-normal);margin:0 0 var(--oc-space-item-gap-medium);color:var(--oc-color-theme-label-alternative);text-align:center}.oc-ActionArea-module__actionArea__jnxep [data-oc-part=actions]{display:flex;gap:var(--oc-action-area-actions-gap);min-width:0}.oc-ActionArea-module__actionArea__jnxep[data-oc-variant=strong] [data-oc-part=actions],.oc-ActionArea-module__actionArea__jnxep[data-oc-variant=cancel] [data-oc-part=actions]{flex-direction:column}.oc-ActionArea-module__actionArea__jnxep[data-oc-variant=neutral] [data-oc-part=actions]{flex-direction:row}.oc-ActionArea-module__actionArea__jnxep[data-oc-variant=neutral] [data-oc-part=actions]>[data-oc-action-area-button=true]{flex:1 1 0}.oc-ActionArea-module__actionArea__jnxep[data-oc-variant=neutral] [data-oc-part=actions]>[data-oc-action-area-button-variant=sub][data-oc-icon-only=true]{flex:0 0 auto}.oc-ActionArea-module__actionArea__jnxep[data-oc-variant=compact] [data-oc-part=actions]{flex-direction:row;justify-content:flex-end}.oc-ActionArea-module__actionArea__jnxep[data-oc-variant=compact] [data-oc-part=actions]:has(>[data-oc-action-area-button-variant=sub][data-oc-icon-only=true]){justify-content:space-between;inline-size:100%}.oc-ActionArea-module__actionArea__jnxep[data-oc-variant=compact] [data-oc-part=compact-row]{display:flex;align-items:center;justify-content:space-between;gap:var(--oc-space-item-gap-medium);min-width:0}.oc-ActionArea-module__actionArea__jnxep[data-oc-variant=compact] [data-oc-part=compact-slot]{display:flex;align-items:center;flex:1 1 auto;min-width:0}.oc-ActionArea-module__actionButton__fKHJQ{min-width:0}.oc-ActionArea-module__actionButton__fKHJQ[data-oc-component=text-button]{flex:0 0 auto;inline-size:fit-content;align-self:center}
+.oc-ActionArea-module__actionArea__jnxep{position:relative;isolation:isolate;display:flex;flex-direction:column;inline-size:100%;padding:var(--oc-action-area-padding-y) var(--oc-action-area-padding-x) var(--oc-action-area-padding-bottom);--oc-action-area-padding-x: var(--oc-space-section-padding-viewport-x);--oc-action-area-padding-y: var(--oc-space-section-padding-viewport-y);--oc-action-area-padding-bottom: var(--oc-action-area-padding-y);--oc-action-area-gap: var(--oc-space-item-gap-small);--oc-action-area-actions-gap: var(--oc-space-item-gap-small);--oc-action-area-background-color: var(--oc-color-theme-background-elevated-normal)}.oc-ActionArea-module__actionArea__jnxep:before{position:absolute;inset:0;z-index:0;background:linear-gradient(to bottom,transparent,var(--oc-action-area-background-color) 45%);opacity:0;content:"";pointer-events:none}.oc-ActionArea-module__actionArea__jnxep>*{position:relative;z-index:1}.oc-ActionArea-module__actionArea__jnxep[data-oc-background=true]:before{opacity:1}.oc-ActionArea-module__actionArea__jnxep[data-oc-has-extra=true]{border-block-start:1px solid var(--oc-color-theme-line-normal-neutral);background-color:var(--oc-action-area-background-color)}.oc-ActionArea-module__actionArea__jnxep [data-oc-part=extra-slot]{display:flex;flex-direction:column;align-items:center;margin-block-end:calc(var(--oc-action-area-gap) + var(--oc-action-area-padding-y))}.oc-ActionArea-module__actionArea__jnxep [data-oc-part=caption]{font-size:calc(var(--oc-typo-size-label2) * var(--oc-typo-scale, 1));line-height:calc(var(--oc-typo-height-label2) * var(--oc-typo-scale, 1));letter-spacing:var(--oc-typo-spacing-label2);font-weight:var(--oc-typo-weight-label2-normal);margin:0 0 var(--oc-space-item-gap-medium);color:var(--oc-color-theme-label-alternative);text-align:center}.oc-ActionArea-module__actionArea__jnxep [data-oc-part=actions]{display:flex;gap:var(--oc-action-area-actions-gap);min-width:0}.oc-ActionArea-module__actionArea__jnxep[data-oc-variant=strong] [data-oc-part=actions],.oc-ActionArea-module__actionArea__jnxep[data-oc-variant=cancel] [data-oc-part=actions]{flex-direction:column}.oc-ActionArea-module__actionArea__jnxep[data-oc-variant=neutral] [data-oc-part=actions]{flex-direction:row}.oc-ActionArea-module__actionArea__jnxep[data-oc-variant=neutral] [data-oc-part=actions]>[data-oc-action-area-button=true]{flex:1 1 0}.oc-ActionArea-module__actionArea__jnxep[data-oc-variant=neutral] [data-oc-part=actions]>[data-oc-action-area-button-variant=sub][data-oc-icon-only=true]{flex:0 0 auto}.oc-ActionArea-module__actionArea__jnxep[data-oc-variant=compact] [data-oc-part=actions]{flex-direction:row;justify-content:flex-end}.oc-ActionArea-module__actionArea__jnxep[data-oc-variant=compact] [data-oc-part=actions]:has(>[data-oc-action-area-button-variant=sub][data-oc-icon-only=true]){justify-content:space-between;inline-size:100%}.oc-ActionArea-module__actionArea__jnxep[data-oc-variant=compact] [data-oc-part=compact-row]{display:flex;align-items:center;justify-content:space-between;gap:var(--oc-space-item-gap-medium);min-width:0}.oc-ActionArea-module__actionArea__jnxep[data-oc-variant=compact] [data-oc-part=compact-slot]{display:flex;align-items:center;flex:1 1 auto;min-width:0}.oc-ActionArea-module__actionButton__fKHJQ{min-width:0}.oc-ActionArea-module__actionButton__fKHJQ[data-oc-component=text-button]{flex:0 0 auto;inline-size:fit-content;align-self:center}

package/dist/components/ActionArea/ActionArea.js

@@ -1,3 +1,4 @@
+'use client';
 import { jsx as e, jsxs as v } from "react/jsx-runtime";
 import { useContext as P, createContext as V, Children as E, isValidElement as j, Fragment as O } from "react";
 import z from "../Button/Button.js";