@uniai-fe/uds-templates 0.3.3 → 0.3.5

package/src/modal/{templates/components/DialogHeader.tsx → components/dialog/Header.tsx}

@@ -5,10 +5,17 @@ import clsx from "clsx";
 import type { DialogHeaderProps } from "../../types";
 
 /**
- * Dialog 템플릿 header 컴포넌트.
+ * Modal Dialog Header; Dialog 헤더 영역
  * @component
- * @param {DialogHeaderProps} props header 구성 옵션
- * @returns {JSX.Element}
+ * @param {DialogHeaderProps} props
+ * @param {React.ReactNode} props.title 타이틀 콘텐츠
+ * @param {React.ReactNode} [props.description] description 콘텐츠
+ * @param {"center" | "split"} [props.layout] 헤더 레이아웃
+ * @param {React.ReactNode} [props.leadingContent] 타이틀 왼쪽 콘텐츠
+ * @param {React.ReactNode} [props.trailingContent] 우측 액션 콘텐츠
+ * @param {string} [props.className] 헤더 className
+ * @example
+ * <DialogHeader title="제목" description="설명" />
  */
 export function DialogHeader({
   title,
@@ -20,6 +27,11 @@ export function DialogHeader({
 }: DialogHeaderProps) {
   const hasRight = Boolean(trailingContent);
   const hasDescription = Boolean(description);
+  // 변경: title/description은 string | number일 때만 래핑한다.
+  const shouldWrapTitleAsText = ["string", "number"].includes(typeof title);
+  const shouldWrapDescriptionAsText = ["string", "number"].includes(
+    typeof description,
+  );
 
   return (
     <header
@@ -41,7 +53,7 @@ export function DialogHeader({
               </div>
             ) : null}
             <div className="uds-modal-dialog-header-title">
-              {typeof title === "string" ? <h3>{title}</h3> : title}
+              {shouldWrapTitleAsText ? <h3>{title}</h3> : title}
             </div>
           </div>
           {hasRight ? (
@@ -52,7 +64,7 @@ export function DialogHeader({
         </div>
         {description ? (
           <p className="uds-modal-dialog-header-description">
-            {typeof description === "string" ? (
+            {shouldWrapDescriptionAsText ? (
               <span>{description}</span>
             ) : (
               description

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

@@ -0,0 +1,86 @@
+"use client";
+
+import { DialogHeader } from "./Header";
+import { DialogContents } from "./Contents";
+import {
+  createDialogFooterButtons,
+  resolveDialogPrimaryButton,
+} from "../../utils/create-dialog-footer-buttons";
+
+import type { DialogTemplateOptions, ModalState } from "../../types";
+
+/**
+ * Modal Dialog Template; Dialog 모달 상태 생성기
+ * @component
+ * @param {DialogTemplateOptions} options Dialog 모달 옵션
+ * @param {string} options.stackKey 모달 스택 키
+ * @param {React.ReactNode} options.title 헤더 타이틀
+ * @param {React.ReactNode} [options.description] 헤더 description
+ * @param {"center" | "split"} [options.headerLayout] 헤더 레이아웃
+ * @param {React.ReactNode} [options.headerLeadingContent] 타이틀 왼쪽 콘텐츠
+ * @param {React.ReactNode} [options.headerTrailingContent] 우측 액션 콘텐츠
+ * @param {string} [options.headerClassName] 헤더 className
+ * @param {React.ReactNode} [options.customHeader] 완전 커스텀 header
+ * @param {React.ReactNode} options.content 본문 콘텐츠
+ * @param {string} [options.bodyClassName] body wrapper className
+ * @param {ModalTemplateButtonSpec} [options.confirm] 확인 버튼 스펙
+ * @param {ModalTemplateButtonSpec} [options.cancel] 취소 버튼 스펙
+ * @param {React.ReactNode} [options.footer] 커스텀 footer
+ * @param {number} [options.showDelay] close 후 제거 지연(ms)
+ * @param {number | string} [options.width] 모달 width
+ * @param {StyleSpacingType} [options.padding] 모달 body padding
+ * @returns {ModalState}
+ * @example
+ * Modal.Dialog({ stackKey: "sample", title: "제목", content: "본문" })
+ */
+export function createDialogModal({
+  stackKey,
+  title,
+  description,
+  headerLayout,
+  headerLeadingContent,
+  headerTrailingContent,
+  headerClassName,
+  customHeader,
+  content,
+  bodyClassName,
+  confirm,
+  cancel,
+  footer,
+  showDelay,
+  width,
+  padding,
+}: DialogTemplateOptions): ModalState {
+  const primary = resolveDialogPrimaryButton(confirm);
+
+  const headerNode =
+    customHeader ??
+    (title ? (
+      <DialogHeader
+        title={title}
+        description={description}
+        layout={headerLayout}
+        leadingContent={headerLeadingContent}
+        trailingContent={headerTrailingContent}
+        className={headerClassName}
+      />
+    ) : null);
+
+  const footerButtons = footer
+    ? undefined
+    : createDialogFooterButtons({ stackKey, primary, cancel });
+
+  return {
+    stackKey,
+    modalProps: {
+      show: "init",
+      showDelay,
+      width,
+      padding,
+      header: headerNode ?? undefined,
+      body: <DialogContents content={content} className={bodyClassName} />,
+      footer,
+      footerButtons,
+    },
+  };
+}

package/src/modal/components/index.tsx

@@ -0,0 +1,27 @@
+import { ModalProvider, ModalStackProvider } from "./core/StackProvider";
+import { ModalRouteReset } from "./core/RouteReset";
+import { createAlertModal } from "./alert/Template";
+import { createDialogModal } from "./dialog/Template";
+
+import { useModal } from "../hooks/useModal";
+
+/**
+ * Modal Namespace; 모달 네임스페이스 집계
+ */
+export const ModalNamespace = {
+  Provider: ModalProvider,
+  StackProvider: ModalStackProvider,
+  RouteReset: ModalRouteReset,
+  useModal,
+  Alert: createAlertModal,
+  Dialog: createDialogModal,
+};
+
+export {
+  ModalProvider,
+  ModalStackProvider,
+  ModalRouteReset,
+  useModal,
+  createAlertModal,
+  createDialogModal,
+};

package/src/modal/{core/hooks → hooks}/useModal.ts

@@ -1,9 +1,8 @@
 "use client";
 
 import { useCallback, useEffect, useState } from "react";
-import { useAtom } from "jotai";
 
-import { modalStackAtom } from "../jotai/atoms";
+import { useAtom } from "jotai";
 
 import type {
   CloseFlagState,
@@ -11,7 +10,8 @@ import type {
   ModalState,
   ModalStatePatch,
   UseModalReturn,
-} from "../../types";
+} from "../types";
+import { modalStackAtom } from "../jotai/atoms";
 
 const DEFAULT_CLOSE_DELAY = 400;
 
@@ -19,14 +19,11 @@ const ensureDelay = (value?: number): number =>
   typeof value === "number" ? value : DEFAULT_CLOSE_DELAY;
 
 /**
- * ui-legacy 스펙을 최대한 유지한 모달 스택 훅.
+ * Modal Hook; ui-legacy 스택 정책 유지 훅
  * @hook
- * @returns {UseModalReturn} 스택 상태와 조작자(new/open/close)
- * @desc
- * - modalStacks: 현재 열린 스택 배열
- * - newModal: stackKey 중복 검증 후 "init" 상태로 푸시
- * - updateModal: 부분 업데이트(클래스/슬롯 변경)
- * - closeModal: show=false → delay 후 제거
+ * @returns {UseModalReturn} 모달 스택 상태/조작자
+ * @example
+ * const { newModal, closeModal } = useModal();
  */
 export function useModal(): UseModalReturn {
   const [modalStacks, updateModalStack] = useAtom(modalStackAtom);
@@ -60,7 +57,9 @@ export function useModal(): UseModalReturn {
     (nextStack: ModalStatePatch) => {
       updateModalStack((stacks: ModalState[]) =>
         stacks.map(stack => {
-          if (stack.stackKey !== nextStack.stackKey) return stack;
+          if (stack.stackKey !== nextStack.stackKey) {
+            return stack;
+          }
           const mergedProps = nextStack.modalProps
             ? { ...stack.modalProps, ...nextStack.modalProps }
             : stack.modalProps;
@@ -84,7 +83,9 @@ export function useModal(): UseModalReturn {
 
       updateModalStack((stacks: ModalState[]) =>
         stacks.map(stack => {
-          if (stack.stackKey !== stackKey) return stack;
+          if (stack.stackKey !== stackKey) {
+            return stack;
+          }
           hasTarget = true;
           resolvedDelay = ensureDelay(stack.modalProps.showDelay);
           return {
@@ -107,7 +108,9 @@ export function useModal(): UseModalReturn {
   );
 
   useEffect(() => {
-    if (!closeFlag) return;
+    if (!closeFlag) {
+      return;
+    }
 
     const timer = setTimeout(() => {
       updateModalStack((stacks: ModalState[]) =>

package/src/modal/index.tsx

@@ -1,22 +1,21 @@
 import "./index.scss";
 
-import { ModalProvider } from "./core/components/Provider";
-import { ModalRouteReset } from "./core/components/RouteReset";
-import { useModal } from "./core/hooks/useModal";
-import { createAlertModal } from "./templates/Alert";
-import { createDialogModal } from "./templates/Dialog";
-import { modalStackAtom } from "./core/jotai/atoms";
-
-export const Modal = {
-  Provider: ModalProvider,
-  RouteReset: ModalRouteReset,
+import { modalStackAtom } from "./jotai/atoms";
+import {
+  ModalNamespace,
+  ModalProvider,
+  ModalStackProvider,
+  ModalRouteReset,
   useModal,
-  Alert: createAlertModal,
-  Dialog: createDialogModal,
-};
+  createAlertModal,
+  createDialogModal,
+} from "./components";
+
+export const Modal = ModalNamespace;
 
 export {
   ModalProvider,
+  ModalStackProvider,
   ModalRouteReset,
   useModal,
   createAlertModal,

package/src/modal/{core/jotai → jotai}/atoms.ts

@@ -1,9 +1,9 @@
 import { atom } from "jotai";
 
-import type { ModalState } from "../../types";
+import type { ModalState } from "../types";
 
 /**
- * 모달 스택 상태
+ * Modal Atom; 모달 스택 상태 atom
  * @state
  * @desc ui-legacy 스택 정책을 유지한다.
  */

package/src/modal/styles/container.scss

@@ -116,7 +116,10 @@
 
   color: var(--modal-alert-body-color);
 
-  :where(p, span, strong, em) {
+  // 변경: alert 본문은 직계 + class 없는 텍스트 태그에만 기본 타이포를 적용한다.
+  // 복합 모듈(children) 내부의 텍스트 스타일 오염을 방지하기 위함이다.
+  > :where(p, span, strong, em):not([class]) {
+    margin: 0;
     font-size: var(--modal-alert-body-font-size);
     line-height: 1.5em;
     font-weight: var(--font-body-small-weight, 400);
@@ -165,7 +168,8 @@
   align-items: center;
   gap: var(--spacing-gap-1, 4px);
 
-  :where(p, span, strong, em) {
+  // 변경: header leading slot은 class 없는 직계 텍스트만 기본 타이포를 적용한다.
+  > :where(p, span, strong, em):not([class]) {
     color: var(--modal-dialog-title-color);
     font-size: var(--modal-dialog-body-font-size);
     line-height: 1.4em;
@@ -178,7 +182,8 @@
   justify-content: center;
   text-align: center;
 
-  > :where(h1, h2, h3, h4, h5, h6, p, span, strong, em) {
+  // 변경: className이 있는 헤더 텍스트 요소는 모듈 자체 스타일을 우선한다.
+  > :where(h1, h2, h3, h4, h5, h6, p, span, strong, em):not([class]) {
     margin: 0;
     color: var(--modal-dialog-title-color);
     font-size: var(--modal-dialog-title-font-size);
@@ -197,7 +202,8 @@
   margin: 0;
   text-align: inherit;
 
-  > :where(p, span, strong, em) {
+  // 변경: description도 class 없는 직계 텍스트에만 기본 스타일을 적용한다.
+  > :where(p, span, strong, em):not([class]) {
     margin: 0;
     color: var(--modal-dialog-body-color);
     font-size: var(--modal-dialog-body-font-size);
@@ -227,7 +233,10 @@
   word-break: keep-all;
   color: var(--modal-dialog-body-color);
 
-  :where(p, span, strong, em) {
+  // 변경: body 전체 하위 요소가 아닌 직계 텍스트 요소만 기본 타이포를 적용해
+  // 내부 모듈 컴포넌트의 span/p 스타일 오염을 방지한다.
+  > :where(p, span, strong, em):not([class]) {
+    margin: 0;
     font-size: var(--modal-dialog-body-font-size);
     line-height: 1.5em;
     font-weight: var(--font-body-small-weight, 400);

package/src/modal/types/components.ts

@@ -1,4 +1,4 @@
-import type { ReactNode } from "react";
+import type { CSSProperties, ReactNode } from "react";
 import type {
   ModalFooterButtonAppearance,
   ModalFooterButtonDefaultOptions,
@@ -6,7 +6,8 @@ import type {
   ModalFooterButtonWidth,
 } from "./footer";
 import type { ModalDialogHeaderLayout } from "./templates";
-import type { ModalProps, ModalState } from "./state";
+import type { ModalProps, ModalState, ModalSections } from "./state";
+import type { ModalFooterButton } from "./footer";
 
 /**
  * ModalRoot 컴포넌트 props.
@@ -34,6 +35,88 @@ export type ModalRootProps = ModalState & {
   className?: string;
 };
 
+/**
+ * Modal Container props.
+ * @property {string} stackKey 모달 스택 식별자
+ * @property {ReactNode} [header] 헤더 콘텐츠
+ * @property {ReactNode} body 본문 콘텐츠
+ * @property {ReactNode} [footer] footer 콘텐츠
+ * @property {ModalFooterButton[]} [footerButtons] footer 버튼 목록
+ * @property {string} [className] 컨테이너 className
+ */
+export type ModalContainerProps = ModalSections & {
+  /**
+   * 모달 스택 식별자
+   */
+  stackKey: string;
+  /**
+   * footer 버튼 목록
+   */
+  footerButtons?: ModalFooterButton[];
+  /**
+   * 컨테이너 className
+   */
+  className?: string;
+};
+
+/**
+ * Modal Body props.
+ * @property {ReactNode} children body 내부 콘텐츠
+ * @property {CSSProperties} [style] 런타임 주입 스타일
+ * @property {string} [className] body className
+ */
+export type ModalBodyProps = {
+  /**
+   * body 내부 콘텐츠
+   */
+  children: ReactNode;
+  /**
+   * 런타임 주입 스타일
+   */
+  style?: CSSProperties;
+  /**
+   * body className
+   */
+  className?: string;
+};
+
+/**
+ * Modal Header Container props.
+ * @property {ReactNode} children 헤더 콘텐츠
+ * @property {string} [className] 헤더 wrapper className
+ */
+export type ModalHeaderContainerProps = {
+  /**
+   * 헤더 콘텐츠
+   */
+  children: ReactNode;
+  /**
+   * 헤더 wrapper className
+   */
+  className?: string;
+};
+
+/**
+ * Modal Header CloseButton props.
+ * @property {() => void} onClick 클릭 핸들러
+ * @property {string} [ariaLabel] 접근성 라벨
+ * @property {string} [className] 버튼 className
+ */
+export type ModalHeaderCloseButtonProps = {
+  /**
+   * 클릭 핸들러
+   */
+  onClick: () => void;
+  /**
+   * 접근성 라벨
+   */
+  ariaLabel?: string;
+  /**
+   * 버튼 className
+   */
+  className?: string;
+};
+
 /**
  * footer 위치 정의.
  * @typedef {"left" | "center" | "right"} FooterPosition
@@ -90,6 +173,7 @@ export type FooterResolvedButton = {
  * FooterPositionGroup props.
  * @property {FooterPosition} position 렌더링 위치
  * @property {FooterResolvedButton[]} buttons 위치별 버튼 목록
+ * @property {string} [className] 그룹 className
  */
 export type FooterPositionGroupProps = {
   /**
@@ -100,17 +184,63 @@ export type FooterPositionGroupProps = {
    * 위치별 버튼 목록
    */
   buttons: FooterResolvedButton[];
+  /**
+   * 그룹 className
+   */
+  className?: string;
 };
 
 /**
  * FooterPositionButton props.
  * @property {FooterResolvedButton} button 렌더링할 버튼
+ * @property {string} [className] 버튼 className
  */
 export type FooterPositionButtonProps = {
   /**
    * 렌더링할 버튼
    */
   button: FooterResolvedButton;
+  /**
+   * 버튼 className
+   */
+  className?: string;
+};
+
+/**
+ * Footer 버튼 래퍼 props.
+ * @property {string} stackKey 버튼이 속한 모달 스택 키
+ * @property {ModalFooterButton[]} buttons footer 버튼 정의 목록
+ * @property {string} [className] wrapper className
+ */
+export type FooterButtonWrapperProps = {
+  /**
+   * 버튼이 속한 모달 스택 키
+   */
+  stackKey: string;
+  /**
+   * footer 버튼 정의 목록
+   */
+  buttons: ModalFooterButton[];
+  /**
+   * wrapper className
+   */
+  className?: string;
+};
+
+/**
+ * AlertContents props.
+ * @property {ReactNode} message alert 본문 메시지
+ * @property {string} [className] 콘텐츠 wrapper className
+ */
+export type AlertContentsProps = {
+  /**
+   * alert 본문 메시지
+   */
+  message: ReactNode;
+  /**
+   * 콘텐츠 wrapper className
+   */
+  className?: string;
 };
 
 /**
@@ -150,11 +280,12 @@ export interface DialogHeaderProps {
 }
 
 /**
- * DialogBody props.
+ * DialogContents props.
  * @property {ReactNode} content 본문 콘텐츠
  * @property {string} [className] wrapper className
+ * @property {string} [contentClassName] 본문 콘텐츠 className
  */
-export interface DialogBodyProps {
+export interface DialogContentsProps {
   /**
    * 본문 콘텐츠
    */
@@ -163,4 +294,8 @@ export interface DialogBodyProps {
    * wrapper className
    */
   className?: string;
+  /**
+   * 본문 콘텐츠 className
+   */
+  contentClassName?: string;
 }

package/src/modal/types/index.ts

@@ -24,10 +24,16 @@ export type {
 export type { CloseFlagState, UseModalReturn } from "./hooks";
 export type {
   ModalRootProps,
+  ModalContainerProps,
+  ModalBodyProps,
+  ModalHeaderContainerProps,
+  ModalHeaderCloseButtonProps,
   FooterPosition,
   FooterResolvedButton,
+  FooterButtonWrapperProps,
   FooterPositionGroupProps,
   FooterPositionButtonProps,
+  AlertContentsProps,
   DialogHeaderProps,
-  DialogBodyProps,
+  DialogContentsProps,
 } from "./components";

package/src/modal/utils/create-alert-footer-buttons.ts

@@ -0,0 +1,59 @@
+import type { ModalFooterButton, ModalTemplateButtonSpec } from "../types";
+
+const DEFAULT_CONFIRM_LABEL = "확인";
+const DEFAULT_CANCEL_LABEL = "취소";
+
+/**
+ * Modal Alert Footer Buttons; Alert footer 버튼 스펙 생성
+ * @param {string} stackKey 모달 스택 키
+ * @param {ModalTemplateButtonSpec} primary 확인 버튼 스펙
+ * @param {ModalTemplateButtonSpec} [cancel] 취소 버튼 스펙
+ * @returns {ModalFooterButton[]}
+ */
+export const createAlertFooterButtons = ({
+  stackKey,
+  primary,
+  cancel,
+}: {
+  stackKey: string;
+  primary: ModalTemplateButtonSpec;
+  cancel?: ModalTemplateButtonSpec;
+}): ModalFooterButton[] => {
+  const buttons: ModalFooterButton[] = [];
+
+  if (cancel) {
+    buttons.push({
+      stackKey,
+      role: "close",
+      position: cancel.position ?? "center",
+      width: cancel.width === "full" || !cancel.width ? "fill" : cancel.width,
+      defaultOptions: {
+        label: cancel.label ?? DEFAULT_CANCEL_LABEL,
+        appearance: "text",
+        priority: "tertiary",
+        textSize: "large",
+        disabled: cancel.disabled,
+        onClick: cancel.onClick,
+      },
+      closeOnClick: cancel.closeOnClick,
+    });
+  }
+
+  buttons.push({
+    stackKey,
+    role: "close",
+    position: primary.position ?? "center",
+    width: primary.width === "full" || !primary.width ? "fill" : primary.width,
+    defaultOptions: {
+      label: primary.label ?? DEFAULT_CONFIRM_LABEL,
+      appearance: "text",
+      priority: "secondary",
+      textSize: "large",
+      disabled: primary.disabled,
+      onClick: primary.onClick,
+    },
+    closeOnClick: primary.closeOnClick,
+  });
+
+  return buttons;
+};

package/src/modal/utils/create-dialog-footer-buttons.ts

@@ -0,0 +1,72 @@
+import type {
+  DialogTemplateOptions,
+  ModalFooterButton,
+  ModalTemplateButtonSpec,
+} from "../types";
+
+/**
+ * Modal Dialog Footer Buttons; Dialog footer 버튼 스펙 생성
+ * @param {string} stackKey 모달 스택 키
+ * @param {ModalTemplateButtonSpec} primary 확인 버튼 스펙
+ * @param {ModalTemplateButtonSpec} [cancel] 취소 버튼 스펙
+ * @returns {ModalFooterButton[]}
+ */
+export const createDialogFooterButtons = ({
+  stackKey,
+  primary,
+  cancel,
+}: {
+  stackKey: string;
+  primary: ModalTemplateButtonSpec;
+  cancel?: ModalTemplateButtonSpec;
+}): ModalFooterButton[] => {
+  const buttons: ModalFooterButton[] = [];
+
+  if (cancel) {
+    buttons.push({
+      stackKey,
+      role: "close",
+      position: cancel.position,
+      width: cancel.width,
+      defaultOptions: {
+        label: cancel.label ?? "취소",
+        fill: "outlined",
+        size: "large",
+        priority: "secondary",
+        disabled: cancel.disabled,
+        onClick: cancel.onClick,
+      },
+      closeOnClick: cancel.closeOnClick,
+    });
+  }
+
+  buttons.push({
+    stackKey,
+    role: "close",
+    position: primary.position,
+    width: primary.width,
+    defaultOptions: {
+      label: primary.label ?? "확인",
+      fill: "solid",
+      size: "large",
+      priority: "primary",
+      disabled: primary.disabled,
+      onClick: primary.onClick,
+    },
+    closeOnClick: primary.closeOnClick,
+  });
+
+  return buttons;
+};
+
+/**
+ * Modal Dialog Primary Button; Dialog 기본 확인 버튼 스펙 생성
+ * @param {DialogTemplateOptions["confirm"]} confirm 확인 버튼 옵션
+ * @returns {ModalTemplateButtonSpec}
+ */
+export const resolveDialogPrimaryButton = (
+  confirm: DialogTemplateOptions["confirm"],
+): ModalTemplateButtonSpec =>
+  confirm ?? {
+    label: "확인",
+  };