@cashdoc/cashdoc-cms-design-system 2.6.1 → 2.7.0

package/dist/src/components/Modal/Modal.d.ts

@@ -3,8 +3,27 @@ import { default as React } from 'react';
 export type ModalProps = {
     open: boolean;
     onOpenChange: (open: boolean) => void;
+    /**
+     * Radix Dialog의 `modal` 동작을 제어합니다. 기본값 `true`는 배경
+     * 상호작용을 차단하는 표준 모달 동작입니다. `false`로 두면 배경
+     * `pointer-events` 차단이 사라집니다.
+     *
+     * 모달 내부의 `TimePicker`/`DatePicker`/`Dropdown` 등 Popover 계열
+     * 컴포넌트는 기본값(`true`)에서도 자동으로 모달 내부에 portal되어
+     * 정상 동작하므로, 이 prop을 바꿀 필요는 일반적으로 없습니다.
+     */
+    modal?: boolean;
     icon?: React.ReactNode;
     title?: React.ReactNode;
+    /**
+     * 스크린리더에 전달할 모달 설명 텍스트입니다. 지정하면 시각적으로는
+     * 숨겨진 채 `aria-describedby`로 연결됩니다.
+     *
+     * `children`은 `<div>` 컨테이너에 렌더되어 block 요소(픽커, 폼 등)를
+     * 안전하게 담을 수 있으므로, 접근성 설명이 필요하면 이 prop을 사용하세요.
+     * 지정하지 않으면 Radix의 설명 연결이 생략됩니다(시각/동작 영향 없음).
+     */
+    description?: React.ReactNode;
     children: React.ReactNode;
     footer?: React.ReactNode;
     className?: string;
@@ -97,7 +116,8 @@ export type ModalProps = {
  * - **스크린 리더**:
  *   - `role="dialog"`: 대화상자임을 인식
  *   - `aria-labelledby`: title이 모달의 레이블로 연결됨
- *   - `aria-describedby`: children 콘텐츠가 설명으로 연결됨
+ *   - `aria-describedby`: `description` prop이 있으면 시각적으로 숨긴 설명으로
+ *     연결됨. `children`은 `<div>` 컨테이너에 렌더되어 block 요소도 안전함.
  *
  * - **포커스 트랩**: 모달이 열려있는 동안 포커스가 모달 내부에서만 순환합니다
  * - **배경 스크롤 방지**: 모달이 열리면 body 스크롤이 자동으로 비활성화됩니다

package/dist/src/components/Popover/Popover.d.ts

@@ -2,7 +2,14 @@ import { ComponentPropsWithoutRef } from 'react';
 import * as PopoverPrimitive from "@radix-ui/react-popover";
 export type PopoverProps = ComponentPropsWithoutRef<typeof PopoverPrimitive.Root>;
 export type PopoverTriggerProps = ComponentPropsWithoutRef<typeof PopoverPrimitive.Trigger>;
-export type PopoverContentProps = ComponentPropsWithoutRef<typeof PopoverPrimitive.Content>;
+export type PopoverContentProps = ComponentPropsWithoutRef<typeof PopoverPrimitive.Content> & {
+    /**
+     * 팝오버가 렌더될 portal container를 직접 지정합니다. 지정하지 않으면
+     * 상위 Modal 내부에서는 자동으로 모달 콘텐츠에, 그 밖에서는 `body`에
+     * 렌더됩니다. 일반적으로 지정할 필요가 없습니다.
+     */
+    container?: HTMLElement | null;
+};
 /**
  * 특정 요소 근처에 부가적인 정보나 컨트롤을 표시하는 플로팅 컴포넌트입니다.
  *
@@ -35,7 +42,7 @@ export type PopoverContentProps = ComponentPropsWithoutRef<typeof PopoverPrimiti
  * ### ✅ Do (권장 사항)
  *
  * - **명확한 트리거**: 사용자가 무엇을 클릭하면 팝오버가 열릴지 명확히 인지할 수 있는 버튼이나 아이콘을 사용하세요.
- * - **적절한 배치**: `align` 속성을 조절하여 팝오버가 화면 밖으로 나가지 않도록 관리하세요. (기본값: 'end')
+ * - **적절한 배치**: `align` 속성을 조절하여 팝오버가 화면 밖으로 나가지 않도록 관리하세요. (기본값: 'start' — 팝오버 왼쪽 보더가 트리거 왼쪽 선에 정렬)
  *
  * ### 🚫 Don't (주의/금지 사항)
  *
@@ -78,5 +85,12 @@ export type PopoverContentProps = ComponentPropsWithoutRef<typeof PopoverPrimiti
  */
 declare const Popover: import('react').FC<PopoverPrimitive.PopoverProps>;
 declare const PopoverTrigger: import('react').ForwardRefExoticComponent<PopoverPrimitive.PopoverTriggerProps & import('react').RefAttributes<HTMLButtonElement>>;
-declare const PopoverContent: import('react').ForwardRefExoticComponent<Omit<PopoverPrimitive.PopoverContentProps & import('react').RefAttributes<HTMLDivElement>, "ref"> & import('react').RefAttributes<HTMLDivElement>>;
+declare const PopoverContent: import('react').ForwardRefExoticComponent<Omit<PopoverPrimitive.PopoverContentProps & import('react').RefAttributes<HTMLDivElement>, "ref"> & {
+    /**
+     * 팝오버가 렌더될 portal container를 직접 지정합니다. 지정하지 않으면
+     * 상위 Modal 내부에서는 자동으로 모달 콘텐츠에, 그 밖에서는 `body`에
+     * 렌더됩니다. 일반적으로 지정할 필요가 없습니다.
+     */
+    container?: HTMLElement | null;
+} & import('react').RefAttributes<HTMLDivElement>>;
 export { Popover, PopoverTrigger, PopoverContent };

package/dist/src/utils/portalContainer.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 오버레이(Modal/Dialog)가 자신의 콘텐츠 DOM 노드를 자식 Popover 계열
+ * 컴포넌트에 전달하기 위한 컨텍스트입니다.
+ *
+ * Radix Dialog는 `modal=true`일 때 `body`에 `pointer-events: none`을
+ * 적용합니다. 그 결과 `body`로 portal되는 Popover content는 클릭이
+ * 막힙니다(시/분 선택 무반응 등). Modal이 자신의 Content 노드를 이
+ * 컨텍스트로 제공하면, 내부 Popover가 그 노드로 portal되어
+ * `pointer-events` 영향을 받지 않습니다.
+ *
+ * 값이 `null`이면(= Modal 밖) Popover는 Radix 기본값(`body`)으로
+ * portal됩니다. 따라서 단독 사용 시 동작 회귀가 없습니다.
+ */
+export declare const PortalContainerContext: import('react').Context<HTMLElement | null>;
+/**
+ * Popover 계열 컴포넌트의 portal container를 결정합니다.
+ *
+ * 우선순위: 명시적 `container` prop → 상위 Modal 컨텍스트 → `undefined`.
+ *
+ * @param explicit 소비자가 직접 지정한 container. 있으면 최우선입니다.
+ * @returns portal 대상 DOM 노드. 없으면 `undefined`(Radix 기본 = body).
+ */
+export declare function usePortalContainer(explicit?: HTMLElement | null): HTMLElement | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cashdoc/cashdoc-cms-design-system",
-  "version": "2.6.1",
+  "version": "2.7.0",
   "description": "Cashdoc CMS Design System",
   "type": "module",
   "main": "dist/index.umd.js",