@nexus-cross/design-system 2.0.3 → 2.0.5

package/claude-rules/nexus/CLAUDE.md

@@ -32,6 +32,11 @@
 
 5. **새 UI 작업 전, 항상 컴포넌트 매핑부터.** native HTML이나 Tailwind 프리미티브로 구현하기 전, `ui-components.md`에 동일 기능이 있는지 먼저 확인.
 
+6. **모달 콘텐츠 컴포넌트 작성 시:**
+   - props 타입은 **반드시 `ModalPropsType<T>` 를 확장**할 것 (`close`, `resolve`, `className`, `layout` 시그니처가 시스템에서 자동 주입됨)
+   - `<ModalTemplate>` 에는 시스템 주입 **`className` 과 `layout` 을 그대로 전달**할 것 (둘 중 하나라도 누락하면 wrap 스타일 / 모바일 bottom-sheet 자동 전환이 동작하지 않음)
+   - 자세한 패턴은 아래 "Modal Writing Rules" 섹션 참조
+
 ---
 
 ## Quick Install (단일 패키지)
@@ -167,6 +172,110 @@ export default function App() {
 
 ---
 
+## Modal Writing Rules
+
+모달 콘텐츠 컴포넌트는 다음 3가지 규칙을 **반드시** 지켜야 합니다.
+
+### Rule 1. props 타입은 반드시 `ModalPropsType<T>` 를 확장하라
+
+`modal()` / `useModal()` 로 모달이 mount 될 때 시스템이 다음 4개 prop 을 자동 주입합니다.
+
+| 주입 prop | 타입 | 의미 |
+|---|---|---|
+| `close` | `(isAnimation?: boolean) => void` | 모달을 닫음 |
+| `resolve` | `(value: T, useClose?: boolean) => void` | 호출자에게 결과 전달 (T 는 사용자가 정함) |
+| `className` | `string` | 모달 wrap layer (full-screen 중앙 정렬 컨테이너) 에 들어가야 하는 시스템 클래스 |
+| `layout` | `ModalLayout` | 시스템이 결정한 layout. 모바일 viewport 에서는 자동으로 `bottom-sheet` 등으로 변환됨 |
+
+이 4개 prop 을 직접 손으로 타이핑하지 말고 **`ModalPropsType<T>` 를 확장하세요.** 손으로 정의하면 시스템 시그니처 변경 시 모달이 동작하지 않게 됩니다.
+
+```tsx
+// CORRECT — ModalPropsType 확장
+import type { ModalPropsType } from '@nexus-cross/design-system';
+
+// ModalPropsType<T> 의 T 는 resolve(value) 의 value 타입
+type Props = ModalPropsType<boolean> & {
+  title: string;
+};
+
+function ConfirmModal({ className, layout, close, resolve, title }: Props) {
+  // ...
+}
+```
+
+```tsx
+// WRONG — 시스템 주입 prop 을 직접 손으로 정의
+function ConfirmModal({
+  close,
+  resolve,
+  title,
+}: {
+  close: () => void;
+  resolve: (v: boolean) => void;
+  title: string;
+}) {
+  // className, layout 누락 → wrap 스타일 / 모바일 bottom-sheet 자동 전환 동작 X
+}
+```
+
+### Rule 2. `<ModalTemplate>` 에는 시스템 주입 `className` 과 `layout` 을 그대로 전달하라
+
+`className` 은 모달 **wrap layer** (full-screen `position: fixed; inset: 0` 중앙 정렬 컨테이너) 에 적용되는 시스템 클래스, `layout` 은 layout 별 분기(애니메이션, bottom-sheet 드래그, slide-left/right 등) 의 단일 source of truth 입니다. **둘 중 하나라도 누락하면 위치, dim, 애니메이션, 모바일 bottom-sheet 동작이 깨집니다.**
+
+```tsx
+// CORRECT — className / layout 그대로 통과
+function ConfirmModal({ className, layout, close, resolve, title }: Props) {
+  return (
+    <ModalTemplate
+      className={className}
+      layout={layout}
+      title={title}
+      close={close}
+      footer={<Button onClick={() => resolve(true)}>확인</Button>}
+    >
+      <p className="text-text-secondary">정말 진행하시겠습니까?</p>
+    </ModalTemplate>
+  );
+}
+```
+
+```tsx
+// WRONG — 시스템 className / layout 누락
+function ConfirmModal({ close, resolve, title }: Props) {
+  return (
+    // className, layout 안 넘김 → wrap 스타일 유실, 모바일 bottom-sheet 미적용
+    <ModalTemplate title={title} close={close}>
+      ...
+    </ModalTemplate>
+  );
+}
+
+// WRONG — 시스템 className 을 자체 className 으로 덮어씀
+function BadModal({ className, layout, close }: Props) {
+  return (
+    // className 자리에 자체 클래스만 넣음 → 시스템 className 유실
+    <ModalTemplate className="bg-bg-default" layout={layout} close={close} title="…">
+      ...
+    </ModalTemplate>
+  );
+}
+```
+
+> 자체 클래스를 wrap 에 추가하고 싶다면 `cn(className, '내 클래스')` 형태로 결합. **wrap 에는 sizing utility (`w-*`, `max-w-*`, `h-*`) 금지** — sizing 은 `innerClassName` 으로.
+
+### Rule 3. 모달 wrapper 는 직접 만들지 말 것
+
+모달 콘텐츠는 **반드시 `ModalTemplate` 안에** 들어가야 합니다. 일반 `<div>` 로 만들면 focus trap / ESC handling / scroll lock / 애니메이션 / dim / a11y 가 모두 사라집니다.
+
+### Self-check (모달 작성 후 출력 직전 검증)
+
+- [ ] props 타입이 `ModalPropsType<T>` 를 확장하고 있는가?
+- [ ] `<ModalTemplate>` 에 `className={className}` 와 `layout={layout}` 을 그대로 넘겼는가?
+- [ ] `<ModalTemplate>` 외부에 별도 wrapper `<div>` 를 두지 않았는가?
+- [ ] 자체 wrap 클래스를 추가했다면 `cn(className, '...')` 으로 시스템 className 을 보존했는가?
+
+---
+
 ## Token Path Convention
 
 모든 디자인 토큰은 5-segment 형식: `color.semantic.{namespace}.{slot}.{state}`

package/cursor-rules/CLAUDE.md

@@ -25,6 +25,11 @@
 
 4. **`className` 오버라이드 시 `!important` 금지.** `cn()` 유틸이 프리픽스 충돌 자동 해소.
 
+5. **모달 콘텐츠 컴포넌트 작성 시 두 가지 필수.**
+   - props 타입은 **반드시 `ModalPropsType<T>` 를 확장** (`close`, `resolve`, `className`, `layout` 시그니처가 시스템에서 자동 주입)
+   - `<ModalTemplate>` 에 시스템 주입 **`className` 과 `layout` 을 그대로 전달** (둘 중 하나라도 누락하면 wrap 스타일 / 모바일 bottom-sheet 자동 전환 동작 X)
+   - 자세한 패턴: `.cursor/rules/nexus-project-setup.mdc` 의 "Modal Writing Rules" 섹션
+
 ## 설치 (단일 패키지)
 
 v2.0부터 `@nexus-cross/design-system` 1개 install로 토큰까지 모두 사용 가능합니다.

package/cursor-rules/nexus-project-setup.mdc

@@ -292,27 +292,120 @@ import { getPredictionTheme } from '@nexus-cross/design-system/tokens-domains';
 
 ## Modal Writing Rules
 
-Modal components **MUST be wrapped with `ModalTemplate`.** Do NOT create modals with plain `<div>`.
+모달 콘텐츠 컴포넌트는 다음 3가지 규칙을 **반드시** 지켜야 합니다.
+
+### Rule 1. props 타입은 반드시 `ModalPropsType<T>` 를 확장하라
+
+`modal()` / `useModal()` 로 모달이 mount 될 때 시스템이 다음 4개 prop 을 자동 주입합니다.
+
+| 주입 prop | 타입 | 의미 |
+|---|---|---|
+| `close` | `(isAnimation?: boolean) => void` | 모달을 닫음 |
+| `resolve` | `(value: T, useClose?: boolean) => void` | 호출자에게 결과 전달 (T 는 사용자가 정함) |
+| `className` | `string` | 모달 wrap layer (full-screen 중앙 정렬 컨테이너) 에 들어가야 하는 시스템 클래스 |
+| `layout` | `ModalLayout` | 시스템이 결정한 layout. 모바일 viewport 에서는 자동으로 `bottom-sheet` 등으로 변환됨 |
+
+이 4개 prop 을 직접 손으로 타이핑하지 말고 **`ModalPropsType<T>` 를 확장하세요.** 손으로 정의하면 시스템 주입 시그니처가 바뀔 때 모달이 동작하지 않게 됩니다.
 
 ```tsx
-// CORRECT modal
+// CORRECT — ModalPropsType 확장
+import type { ModalPropsType } from '@nexus-cross/design-system';
+
+// ModalPropsType<T> 의 T 는 resolve(value) 의 value 타입
+type Props = ModalPropsType<boolean> & {
+  title: string;
+};
+
+function ConfirmModal({ className, layout, close, resolve, title }: Props) {
+  // ...
+}
+```
+
+```tsx
+// WRONG — 시스템 주입 prop 을 직접 손으로 정의
+function ConfirmModal({
+  close,
+  resolve,
+  title,
+}: {
+  close: () => void;
+  resolve: (v: boolean) => void;
+  title: string;
+}) {
+  // className, layout 누락 → wrap 스타일 / 모바일 bottom-sheet 자동 전환 동작 X
+}
+```
+
+### Rule 2. `<ModalTemplate>` 에는 시스템 주입 `className` 과 `layout` 을 그대로 전달하라
+
+`className` 은 모달 **wrap layer** (full-screen `position: fixed; inset: 0` 중앙 정렬 컨테이너) 에 적용되는 시스템 클래스, `layout` 은 layout 별 분기(애니메이션, bottom-sheet 드래그, slide-left/right 등) 의 단일 source of truth 입니다. **둘 중 하나라도 누락하면 위치, dim, 애니메이션, 모바일 bottom-sheet 동작이 깨집니다.**
+
+```tsx
+// CORRECT — className / layout 그대로 통과
+function ConfirmModal({ className, layout, close, resolve, title }: Props) {
+  return (
+    <ModalTemplate
+      className={className}
+      layout={layout}
+      title={title}
+      close={close}
+      footer={<Button onClick={() => resolve(true)}>확인</Button>}
+    >
+      <p className="text-text-secondary">정말 진행하시겠습니까?</p>
+    </ModalTemplate>
+  );
+}
+```
+
+```tsx
+// WRONG — 시스템 className / layout 누락
+function ConfirmModal({ close, resolve, title }: Props) {
+  return (
+    // className, layout 안 넘김 → wrap 스타일 유실, 모바일 bottom-sheet 미적용
+    <ModalTemplate title={title} close={close}>
+      ...
+    </ModalTemplate>
+  );
+}
+
+// WRONG — 시스템 className 을 자체 className 으로 덮어씀
+function BadModal({ className, layout, close }: Props) {
+  return (
+    // className 자리에 자체 클래스만 넣음 → 시스템 className 유실
+    <ModalTemplate className="bg-bg-default" layout={layout} close={close} title="…">
+      ...
+    </ModalTemplate>
+  );
+}
+```
+
+> 자체 클래스를 wrap 에 추가하고 싶다면 `cn(className, '내 클래스')` 형태로 결합. **wrap 에는 sizing utility (`w-*`, `max-w-*`, `h-*`) 금지** — sizing 은 `innerClassName` 으로.
+
+### Rule 3. 모달 wrapper 는 직접 만들지 말 것
+
+모달 콘텐츠는 **반드시 `ModalTemplate` 안에** 들어가야 합니다. 일반 `<div>` 로 만들면 focus trap / ESC handling / scroll lock / 애니메이션 / dim / a11y 가 모두 사라집니다.
+
+```tsx
+// CORRECT
 import { ModalTemplate } from '@nexus-cross/design-system/modal';
+import type { ModalPropsType } from '@nexus-cross/design-system';
+
+type Props = ModalPropsType<{ confirmed: boolean }>;
 
-function MyModal({ close, resolve }: { close: () => void; resolve: (value: any) => void }) {
+function MyModal({ className, layout, close, resolve }: Props) {
   return (
-    <ModalTemplate title="Title" close={close}>
+    <ModalTemplate className={className} layout={layout} title="Title" close={close}>
       <p className="text-text-secondary">Content</p>
       <Button onClick={() => resolve({ confirmed: true })}>Confirm</Button>
     </ModalTemplate>
   );
 }
 
-// Call
 const result = await modal({ component: MyModal });
 ```
 
 ```tsx
-// WRONG modal — using div without ModalTemplate
+// WRONG — div 로 모달을 직접 만든 경우
 function MyModal({ close }: { close: () => void }) {
   return (
     <div className="p-6 bg-white rounded-lg">
@@ -323,6 +416,13 @@ function MyModal({ close }: { close: () => void }) {
 }
 ```
 
+### Self-check (모달 작성 후 출력 직전 검증)
+
+- [ ] props 타입이 `ModalPropsType<T>` 를 확장하고 있는가?
+- [ ] `<ModalTemplate>` 에 `className={className}` 와 `layout={layout}` 을 그대로 넘겼는가?
+- [ ] `<ModalTemplate>` 외부에 별도 wrapper `<div>` 를 두지 않았는가?
+- [ ] 자체 wrap 클래스를 추가했다면 `cn(className, '...')` 으로 시스템 className 을 보존했는가?
+
 ## Toast Usage Rules
 
 ```tsx

package/cursor-rules/nexus-ui-api.mdc

@@ -985,11 +985,19 @@ WHEN TO USE:
 
 PREFERRED API: use modal() / useModal() imperative API rather than mounting <ModalTemplate> directly. modal() handles stacking, focus return, ESC, and background scroll automatically.
 
+SIZING (must read — most common AI mistake):
+  • The modal has TWO layers:
+      1. wrap   = full-screen `position: fixed; inset: 0` flex container → controlled by `className`
+      2. panel  = the actual dialog box rendered at the center → controlled by `innerClassName`
+  • Sizing utilities (`w-*`, `max-w-*`, `min-w-*`, `h-*`, `max-h-*`) MUST go on `innerClassName`.
+  • Putting `w-[400px] max-w-[92vw]` on `className` shrinks the wrap (the centering layer), NOT the panel — the panel keeps its default width and the modal looks broken.
+
 ANTI-PATTERNS:
   ✗ Custom <div className="fixed inset-0"> → modal() (loses focus trap, a11y)
   ✗ Direct <ModalTemplate> mount in render tree → wrap with modal()
   ✗ Modal with no title for screen readers → always pass title prop
   ✗ Multiple modals stacking confusingly → use isAlone:true to close prior modals
+  ✗ <ModalTemplate className="w-[400px] max-w-[92vw]"> → put sizing on `innerClassName` instead
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -1000,15 +1008,16 @@ ANTI-PATTERNS:
 | `dimClose` | `boolean` | `true` | Close on dim click |
 | `hideHeader` | `boolean` | `false` | Hide header |
 | `hideFooter` | `boolean` | `true` | Hide footer |
+| `hideCloseBtn` | `boolean` | `false` | Hide the X close button in the header |
 | `footer` | `ReactNode` | - | Custom footer (ReactElement) |
 | `animation` | `object` | - | Modal animation |
 | `enableDrag` | `boolean` | `true` | Enable drag (bottom-sheet/draggable layouts) |
 | `dragPersistKey` | `string` | - | Drag position persistence key |
 | `close` | `ReactNode` | - | Modal close function (isAnimation?: boolean) => void (auto-injected) |
 | `children` | `ReactNode` | - | Modal body (ReactNode, required) |
-| `className` | `string` | - | Root wrapper style |
-| `innerClassName` | `string` | - | Modal body style |
-| `bodyClassName` | `string` | - | Body area style |
+| `className` | `string` | - | Root wrapper style — applied to the full-screen `position: fixed; inset: 0` flex container that centers the modal. NOTE: width / max-width / height utilities (`w-[400px]`, `max-w-[92vw]`, `h-*`) MUST NOT go here — they will resize the wrap layer, not the panel. Put sizing on `innerClassName` instead. |
+| `innerClassName` | `string` | - | Modal panel (the actual dialog box) style — apply ALL sizing utilities here: `w-[400px]`, `max-w-[92vw]`, `min-h-*`, `max-h-[80vh]`, `rounded-*`, panel background, etc. This is the most common override point. |
+| `bodyClassName` | `string` | - | Body area style (inside the panel, between header and footer) |
 | `footerClassName` | `string` | - | Footer area style |
 | `dimClassName` | `string` | - | Dim overlay style |
 | `headerClassName` | `string` | - | Header area style |
@@ -1056,6 +1065,53 @@ function MyModal({ close, resolve }: { close: () => void; resolve: (value: any)
 }
 ```
 
+### Sizing the modal (`className` vs `innerClassName`)
+
+ModalTemplate has **two layers**:
+
+| Prop | DOM target | Use for |
+|---|---|---|
+| `className` | full-screen wrap (`position: fixed; inset: 0` flex centering layer) | dim/centering overrides only |
+| `innerClassName` | the actual modal panel (the visible dialog box) | **all sizing**: `w-*`, `max-w-*`, `min-w-*`, `h-*`, `max-h-*`, panel `rounded-*`, panel padding |
+
+Putting `w-[400px] max-w-[92vw]` on `className` shrinks the centering wrap, **not** the panel — the panel keeps its default width and the modal renders incorrectly. This is the single most common Modal mistake AI assistants make. **Always put sizing utilities on `innerClassName`.**
+
+```tsx
+// ❌ WRONG — sizing on the wrap layer (panel size unchanged, layout breaks)
+<ModalTemplate
+  title="Title"
+  close={close}
+  className="w-[400px] max-w-[92vw]"
+>
+  ...
+</ModalTemplate>
+
+// ✅ CORRECT — sizing on the panel
+<ModalTemplate
+  title="Title"
+  close={close}
+  innerClassName="w-[400px] max-w-[92vw]"
+>
+  ...
+</ModalTemplate>
+
+// ✅ Larger modal with constrained height + scrollable body
+<ModalTemplate
+  title="Long form"
+  close={close}
+  innerClassName="w-[640px] max-w-[92vw] max-h-[80vh]"
+  bodyClassName="overflow-y-auto"
+>
+  ...
+</ModalTemplate>
+
+// ✅ Same applies when calling via modal() — pass through props
+modal({
+  component: MyModal,
+  props: { innerClassName: 'w-[480px] max-w-[92vw]' },
+});
+```
+
 ### Calling a Modal
 
 ```tsx
@@ -1086,6 +1142,7 @@ openModal({
 - Do NOT create modal components without ModalTemplate (using plain `<div>`)
 - Do NOT define the `close` prop manually (the system injects it automatically)
 - Do NOT implement a separate dim/overlay inside the modal
+- Do NOT put sizing utilities (`w-*`, `max-w-*`, `min-w-*`, `h-*`, `max-h-*`) on `className` — they belong on `innerClassName` (the panel). `className` only styles the full-screen wrap.
 
 ---
 

package/dist/chunks/{chunk-3VFBPFZF.mjs → chunk-7WWQ5DS3.mjs}

@@ -1,9 +1,9 @@
-import { useDraggableBottomSheet } from './chunk-U56AGSLE.mjs';
+import { useDraggableBottomSheet } from './chunk-WBCXHGRL.mjs';
 import { useDraggableWindow } from './chunk-4J3GCZ7W.mjs';
 import { scrollRelease, scrollFreeze } from './chunk-54IA2P2Z.mjs';
-import { useCheckDevice_default } from './chunk-YEWKPWK3.mjs';
+import { useCheckDevice_default } from './chunk-U6OEUBIF.mjs';
 import { useClickOutside_default } from './chunk-OTGS6BDQ.mjs';
-import { Modal_default } from './chunk-6H7V2I3X.mjs';
+import { Modal_default, defaultBreakPoints } from './chunk-FY2N42XN.mjs';
 import { cn } from './chunk-MCKOWMLS.mjs';
 import React, { forwardRef, useState, useMemo, useCallback, useEffect, useImperativeHandle, useRef, Suspense } from 'react';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
@@ -184,7 +184,11 @@ var ModalPortal = ({ children, selector }) => {
   return mounted && element && children ? createPortal(children, element) : null;
 };
 var ModalPortal_default = ModalPortal;
-var ModalContainer = ({ className = "", breakPoints, ...defaultOption }) => {
+var ModalContainer = ({
+  className = "",
+  breakPoints = defaultBreakPoints,
+  ...defaultOption
+}) => {
   const [modals, setModals] = useState(Modal_default.modalList);
   const setModalClose = useCallback((params) => {
     if (!params) return;
@@ -408,6 +412,7 @@ var ModalTemplate = forwardRef(
     desc,
     hideHeader = false,
     hideFooter = true,
+    hideCloseBtn = false,
     dimClose,
     footer,
     close,
@@ -562,7 +567,7 @@ var ModalTemplate = forwardRef(
                       ref: modalHeaderRef,
                       onMouseDown: isDraggable && enableDrag ? windowDrag.handleMouseDown : void 0,
                       children: [
-                        /* @__PURE__ */ jsx(
+                        !hideCloseBtn && /* @__PURE__ */ jsx(
                           "button",
                           {
                             type: "button",

package/dist/chunks/{chunk-HHXDOKXY.js → chunk-F24AY3HI.js}

@@ -25,9 +25,9 @@ function useDraggableBottomSheet({
       if (!enabled) return;
       const touch = e.touches[0];
       const target = e.currentTarget;
-      const modalInner = target.querySelector(".modal-inner");
+      const modalInner = target.querySelector(".nexus-modal-inner");
       if (!modalInner) return;
-      const scrollableElement = e.target.closest(".modal-body");
+      const scrollableElement = e.target.closest(".nexus-modal-body");
       if (scrollableElement && scrollableElement.scrollTop > 0) return;
       dragStateRef.current = {
         isDragging: true,

package/dist/chunks/{chunk-6H7V2I3X.mjs → chunk-FY2N42XN.mjs}

@@ -8,6 +8,11 @@ var defaultModalOption = {
   animation: { name: "pop-fade", duration: 300 },
   dimCloseEnable: true
 };
+var defaultBreakPoints = {
+  isDesktop: "(min-width: 1280px)",
+  isTablet: "screen and (min-width: 768px) and (max-width: 1279px)",
+  isMobile: "(max-width: 767px)"
+};
 
 // src/modal/Modal.ts
 var Modal = class {
@@ -267,4 +272,4 @@ function useModal() {
   };
 }
 
-export { Modal_default, useModal };
+export { Modal_default, defaultBreakPoints, useModal };