@uniai-fe/uds-templates 0.3.14 → 0.3.15

package/README.md

@@ -142,7 +142,7 @@ ui-legacy에서 사용하던 모달 스택/옵션을 templates 레이어로 옮
 
 1. **Provider 1회 장착** — 서비스 레이아웃에서 `<Modal.Provider />`를 렌더합니다.
 2. **Route Reset 장착** — `<Modal.RouteReset />`을 Provider와 같은 레벨에서 렌더해 경로 변경 시 스택을 초기화합니다.
-3. **훅 사용** — `const { newModal, closeModal } = Modal.useModal();`
+3. **훅 사용** — `const { newModal, closeModal, hasBlockingModal } = Modal.useModal();`
 4. **템플릿 팩토리** — `Modal.Alert`, `Modal.Dialog`이 `ModalState` 객체를 반환하므로 `newModal(...)`에 그대로 전달합니다.
 
 ```tsx
@@ -211,6 +211,8 @@ export function ExampleActions() {
 ```
 
 - footer 버튼은 ui-legacy와 동일하게 `stackKey`, `role`, `defaultOptions/linkOptions` 구조로 관리하며, Alert(Text)/Dialog(Solid) 규격은 templates 내부에서 보장합니다.
+- `closeOnOutsideClick?: boolean`으로 overlay 클릭 닫힘을 제어할 수 있습니다. 기본값은 `true`입니다.
+- `preventRouteChange?: boolean`은 현재 열린 modal 중 route 변경 확인이 필요한 modal이 있는지 집계할 때 사용합니다. 서비스 앱은 `hasBlockingModal`을 읽어 공통 confirm UX를 연결할 수 있습니다.
 - Route Reset을 누락하면 이전 라우트의 모달 스택이 그대로 남으므로, layout 수준에서 Provider와 함께 반드시 렌더합니다.
 - 세부 가드레일·확장 기록은 `CONTEXT-MODAL.md`를 참고하고, 새 템플릿을 추가할 때 해당 문서를 선행 업데이트합니다.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/uds-templates",
-  "version": "0.3.14",
+  "version": "0.3.15",
   "description": "UNIAI Design System; UI Templates Package",
   "type": "module",
   "private": false,

package/src/modal/components/alert/Template.tsx

@@ -38,6 +38,8 @@ export function createAlertModal<FormContext extends FieldValues>({
   showDelay,
   width,
   padding,
+  closeOnOutsideClick,
+  preventRouteChange,
   formContextOptions,
 }: AlertTemplateOptions<FormContext>): ModalState<FormContext> {
   const primary: ModalTemplateButtonSpec = confirm ?? {
@@ -51,6 +53,8 @@ export function createAlertModal<FormContext extends FieldValues>({
       showDelay,
       width,
       padding,
+      closeOnOutsideClick,
+      preventRouteChange,
       // 변경 설명: 템플릿 생성 시점의 FormContext 제네릭을 modalProps로 전달한다.
       formContextOptions,
       body: <AlertContents message={message} />,

package/src/modal/components/core/Root.tsx

@@ -39,8 +39,11 @@ export function ModalRoot({
   }, [modalProps.show, stackKey, updateModal]);
 
   const handleClose = useCallback(() => {
+    if (modalProps.closeOnOutsideClick === false) {
+      return;
+    }
     closeModal({ stackKey });
-  }, [closeModal, stackKey]);
+  }, [closeModal, modalProps.closeOnOutsideClick, stackKey]);
 
   const stopPropagation = useCallback(
     (event: React.MouseEvent<HTMLDivElement>) => {

package/src/modal/components/dialog/Template.tsx

@@ -78,6 +78,8 @@ export function createDialogModal<FormContext extends FieldValues>({
   showDelay,
   width,
   padding,
+  closeOnOutsideClick,
+  preventRouteChange,
   formContextOptions,
 }: DialogTemplateOptions<FormContext>): ModalState<FormContext> {
   const primary = resolveDialogPrimaryButton(confirm);
@@ -122,6 +124,8 @@ export function createDialogModal<FormContext extends FieldValues>({
       showDelay,
       width,
       padding,
+      closeOnOutsideClick,
+      preventRouteChange,
       // 변경 설명: 템플릿 생성 시점의 FormContext 제네릭을 modalProps로 전달한다.
       formContextOptions,
       header: headerNode ?? undefined,

package/src/modal/hooks/useModal.ts

@@ -29,6 +29,9 @@ const ensureDelay = (value?: number): number =>
 export function useModal(): UseModalReturn {
   const [modalStacks, updateModalStack] = useAtom(modalStackAtom);
   const modalStacksRef = useRef(modalStacks);
+  const hasBlockingModal = modalStacks.some(
+    stack => stack.modalProps.preventRouteChange === true,
+  );
 
   useEffect(() => {
     // 변경 설명: closeModal이 최신 stack 상태를 기준으로 대상을 찾도록 현재 스냅샷 ref를 동기화한다.
@@ -130,5 +133,5 @@ export function useModal(): UseModalReturn {
     [updateModalStack],
   );
 
-  return { modalStacks, newModal, updateModal, closeModal };
+  return { modalStacks, hasBlockingModal, newModal, updateModal, closeModal };
 }

package/src/modal/types/hooks.ts

@@ -26,6 +26,7 @@ export type CloseFlagState = {
 /**
  * useModal 훅 반환값.
  * @property {ModalState[]} modalStacks 현재 모달 스택 목록
+ * @property {boolean} hasBlockingModal route 변경 확인이 필요한 모달 존재 여부
  * @property {<FormContext extends FieldValues>(newStack: ModalState<FormContext>) => void} newModal 신규 모달 추가 함수
  * @property {<FormContext extends FieldValues>(nextStack: ModalStatePatch<FormContext>) => void} updateModal 스택 상태 갱신 함수
  * @property {(request: ModalCloseRequest) => void} closeModal close 제어 함수
@@ -35,6 +36,10 @@ export type UseModalReturn = {
    * 현재 모달 스택 목록
    */
   modalStacks: ModalState[];
+  /**
+   * route 변경 확인이 필요한 모달 존재 여부
+   */
+  hasBlockingModal: boolean;
   /**
    * 신규 모달 추가 함수
    */

package/src/modal/types/state.ts

@@ -17,6 +17,8 @@ export type ModalShowState = "init" | boolean;
  * @property {ReactNode} [footer] footer 콘텐츠
  * @property {number | string} [width] 커스텀 width
  * @property {StyleSpacingType} [padding] 커스텀 padding
+ * @property {boolean} [closeOnOutsideClick] overlay 클릭 close 허용 여부
+ * @property {boolean} [preventRouteChange] route 변경 전 확인 필요 여부
  * @property {UseFormProps<FormContext>} [formContextOptions] form context 옵션
  */
 export type ModalSections<
@@ -48,6 +50,14 @@ export type ModalSections<
    * - [상, 우, 하, 좌]
    */
   padding?: StyleSpacingType;
+  /**
+   * overlay 클릭 close 허용 여부
+   */
+  closeOnOutsideClick?: boolean;
+  /**
+   * route 변경 전 확인 필요 여부
+   */
+  preventRouteChange?: boolean;
   /**
    * form context 옵션
    * - 옵션이 활성화되면, Form.Provider 사용으로 간주하여 활성화시킴
@@ -69,6 +79,8 @@ export type ModalSections<
  * @property {ModalShowState} show 노출 상태
  * @property {number} [showDelay] close 후 제거 지연(ms)
  * @property {ModalFooterButton[]} [footerButtons] footer 버튼 스펙
+ * @property {boolean} [closeOnOutsideClick] overlay 클릭 close 허용 여부 (@see ModalSections)
+ * @property {boolean} [preventRouteChange] route 변경 전 확인 필요 여부 (@see ModalSections)
  * @property {UseFormProps<FormContext>} [formContextOptions] form context 옵션
  */
 export type ModalProps<

package/src/modal/types/templates.ts

@@ -56,6 +56,8 @@ export type ModalTemplateButtonSpec = {
  * @property {number} [showDelay] close 후 제거 지연(ms)
  * @property {number | string} [width] 커스텀 width
  * @property {StyleSpacingType} [padding] 커스텀 padding
+ * @property {boolean} [closeOnOutsideClick] overlay 클릭 close 허용 여부
+ * @property {boolean} [preventRouteChange] route 변경 전 확인 필요 여부
  */
 type ModalTemplateBase<
   FormContext extends FieldValues = Record<string, unknown>,
@@ -82,6 +84,14 @@ type ModalTemplateBase<
    * - [상, 우, 하, 좌]
    */
   padding?: StyleSpacingType;
+  /**
+   * overlay 클릭 close 허용 여부
+   */
+  closeOnOutsideClick?: boolean;
+  /**
+   * route 변경 전 확인 필요 여부
+   */
+  preventRouteChange?: boolean;
   /**
    * modal 내부 Form.Provider 옵션
    * - 타입 안정성은 Modal.Alert/Dialog 생성 시점 제네릭으로 보장한다.
@@ -99,6 +109,8 @@ type ModalTemplateBase<
  * @property {ReactNode} [footer] 커스텀 footer
  * @property {number | string} [width] 커스텀 width
  * @property {StyleSpacingType} [padding] 커스텀 padding
+ * @property {boolean} [closeOnOutsideClick] overlay 클릭 close 허용 여부
+ * @property {boolean} [preventRouteChange] route 변경 전 확인 필요 여부
  * @property {UseFormProps<FormContext>} [formContextOptions] modal 내부 Form.Provider 옵션
  */
 export type AlertTemplateOptions<
@@ -145,6 +157,8 @@ export type AlertTemplateOptions<
  * @property {ReactNode} [footer] 커스텀 footer
  * @property {number | string} [width] 커스텀 width
  * @property {StyleSpacingType} [padding] 커스텀 padding
+ * @property {boolean} [closeOnOutsideClick] overlay 클릭 close 허용 여부
+ * @property {boolean} [preventRouteChange] route 변경 전 확인 필요 여부
  * @property {UseFormProps<FormContext>} [formContextOptions] modal 내부 Form.Provider 옵션
  */
 export type DialogTemplateOptions<