@uniai-fe/uds-templates 0.3.2 → 0.3.4

package/dist/styles.css

@@ -606,7 +606,8 @@
   word-break: keep-all;
   color: var(--modal-alert-body-color);
 }
-.uds-modal-alert-message :where(p, span, strong, em) {
+.uds-modal-alert-message > :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);
@@ -653,7 +654,7 @@
   align-items: center;
   gap: var(--spacing-gap-1, 4px);
 }
-.uds-modal-dialog-header-leading-content :where(p, span, strong, em) {
+.uds-modal-dialog-header-leading-content > :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;
@@ -665,7 +666,7 @@
   justify-content: center;
   text-align: center;
 }
-.uds-modal-dialog-header-title > :where(h1, h2, h3, h4, h5, h6, p, span, strong, em) {
+.uds-modal-dialog-header-title > :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);
@@ -683,7 +684,7 @@
   margin: 0;
   text-align: inherit;
 }
-.uds-modal-dialog-header-description > :where(p, span, strong, em) {
+.uds-modal-dialog-header-description > :where(p, span, strong, em):not([class]) {
   margin: 0;
   color: var(--modal-dialog-body-color);
   font-size: var(--modal-dialog-body-font-size);
@@ -707,7 +708,8 @@
   word-break: keep-all;
   color: var(--modal-dialog-body-color);
 }
-.uds-modal-dialog-body-content :where(p, span, strong, em) {
+.uds-modal-dialog-body-content > :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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/uds-templates",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "UNIAI Design System; UI Templates Package",
   "type": "module",
   "private": false,
@@ -12,7 +12,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "packageManager": "pnpm@10.28.2",
+  "packageManager": "pnpm@10.30.2",
   "engines": {
     "node": ">=24",
     "pnpm": ">=10"
@@ -52,6 +52,7 @@
     "@tanstack/react-query": "^5",
     "@uniai-fe/uds-foundation": "^0.1.0",
     "@uniai-fe/uds-primitives": "^0.1.0",
+    "@uniai-fe/util-api": "^0.1.0",
     "@uniai-fe/util-functions": "^0.2.0",
     "@uniai-fe/util-jotai": "^0.1.5",
     "@uniai-fe/util-next": "^0.2.0",
@@ -60,7 +61,8 @@
     "next": "^15",
     "react": "^19",
     "react-dom": "^19",
-    "react-hook-form": "^7"
+    "react-hook-form": "^7",
+    "clsx": "^2.1.1"
   },
   "dependencies": {
     "clsx": "^2.1.1",
@@ -68,9 +70,9 @@
   },
   "devDependencies": {
     "@svgr/webpack": "^8.1.0",
-    "@tanstack/react-query": "^5.90.20",
+    "@tanstack/react-query": "^5.90.21",
     "@types/node": "^24.10.2",
-    "@types/react": "^19.2.11",
+    "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@uniai-fe/eslint-config": "workspace:*",
     "@uniai-fe/next-devkit": "workspace:*",
@@ -78,15 +80,16 @@
     "@uniai-fe/tsconfig": "workspace:*",
     "@uniai-fe/uds-foundation": "workspace:*",
     "@uniai-fe/uds-primitives": "workspace:*",
+    "@uniai-fe/util-api": "workspace:*",
     "@uniai-fe/util-functions": "workspace:*",
     "@uniai-fe/util-jotai": "workspace:*",
     "@uniai-fe/util-next": "workspace:*",
     "@uniai-fe/util-rtc": "workspace:*",
     "eslint": "^9.39.2",
-    "jotai": "^2.17.1",
+    "jotai": "^2.18.0",
     "next": "^15.5.11",
     "prettier": "^3.8.1",
-    "react-hook-form": "^7.71.1",
+    "react-hook-form": "^7.71.2",
     "sass": "^1.97.3",
     "typescript": "~5.9.3"
   }

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

@@ -0,0 +1,28 @@
+"use client";
+
+import clsx from "clsx";
+
+import type { AlertContentsProps } from "../../types";
+
+/**
+ * Modal Alert Contents; Alert 본문 메시지 콘텐츠
+ * @component
+ * @param {AlertContentsProps} props
+ * @param {React.ReactNode} props.message alert 본문 메시지
+ * @param {string} [props.className] 콘텐츠 wrapper className
+ * @example
+ * <AlertContents message="저장되었습니다." />
+ */
+export default function AlertContents({
+  message,
+  className,
+}: AlertContentsProps) {
+  // 변경: text 전용 children은 string | number일 때만 래핑해 스타일 충돌을 방지한다.
+  const shouldWrapAsText = ["string", "number"].includes(typeof message);
+
+  return (
+    <div className={clsx("uds-modal-alert-message", className)}>
+      {shouldWrapAsText ? <p>{message}</p> : message}
+    </div>
+  );
+}

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

@@ -0,0 +1,59 @@
+"use client";
+
+import AlertContents from "./Contents";
+import { createAlertFooterButtons } from "../../utils/create-alert-footer-buttons";
+
+import type {
+  AlertTemplateOptions,
+  ModalState,
+  ModalTemplateButtonSpec,
+} from "../../types";
+
+const DEFAULT_CONFIRM_LABEL = "확인";
+
+/**
+ * Modal Alert Template; Alert 모달 상태 생성기
+ * @component
+ * @param {AlertTemplateOptions} options Alert 모달 옵션
+ * @param {string} options.stackKey 모달 스택 키
+ * @param {React.ReactNode} options.message 본문 메시지
+ * @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.Alert({ stackKey: "sample", message: "완료되었습니다." })
+ */
+export function createAlertModal({
+  stackKey,
+  message,
+  confirm,
+  cancel,
+  footer,
+  showDelay,
+  width,
+  padding,
+}: AlertTemplateOptions): ModalState {
+  const primary: ModalTemplateButtonSpec = confirm ?? {
+    label: DEFAULT_CONFIRM_LABEL,
+  };
+
+  return {
+    stackKey,
+    modalProps: {
+      show: "init",
+      showDelay,
+      width,
+      padding,
+      body: <AlertContents message={message} />,
+      footer,
+      // 변경: footer가 없을 때만 템플릿 버튼 스펙을 조합한다.
+      footerButtons: footer
+        ? undefined
+        : createAlertFooterButtons({ stackKey, primary, cancel }),
+    },
+  };
+}

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

@@ -0,0 +1,23 @@
+"use client";
+
+import clsx from "clsx";
+
+import type { ModalBodyProps } from "../../types";
+
+/**
+ * Modal Body; 모달 body wrapper
+ * @component
+ * @param {ModalBodyProps} props
+ * @param {React.ReactNode} props.children body 내부 콘텐츠
+ * @param {React.CSSProperties} [props.style] 런타임 주입 스타일
+ * @param {string} [props.className] body className
+ * @example
+ * <ModalBody><div>본문</div></ModalBody>
+ */
+export function ModalBody({ children, style, className }: ModalBodyProps) {
+  return (
+    <div className={clsx("uds-modal-body", className)} style={style}>
+      {children}
+    </div>
+  );
+}

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

@@ -0,0 +1,59 @@
+"use client";
+
+import type { CSSProperties } from "react";
+
+import clsx from "clsx";
+import { stylePaddingSize } from "@uniai-fe/util-functions";
+
+import type { ModalContainerProps } from "../../types";
+import { ModalBody } from "./Body";
+import { ModalHeaderContainer } from "./header/Container";
+import { ModalFooterButtonWrapper } from "./footer/ButtonWrapper";
+
+/**
+ * Modal Container; header/body/footer 슬롯 조합 컨테이너
+ * @component
+ * @param {ModalContainerProps} props
+ * @param {string} props.stackKey 모달 스택 키
+ * @param {React.ReactNode} [props.header] 헤더 슬롯
+ * @param {React.ReactNode} props.body 본문 슬롯
+ * @param {React.ReactNode} [props.footer] footer 슬롯
+ * @param {ModalFooterButton[]} [props.footerButtons] footer 버튼 스펙 배열
+ * @param {StyleSpacingType} [props.padding] body padding 오버라이드
+ * @param {string} [props.className] 컨테이너 className
+ * @example
+ * <ModalContainer stackKey="sample" body={<div />} />
+ */
+export function ModalContainer({
+  stackKey,
+  header,
+  body,
+  footer,
+  footerButtons,
+  padding,
+  className,
+}: ModalContainerProps) {
+  // 변경: modalProps의 padding을 CSS 변수로 주입해 템플릿 단위 body spacing 제어를 유지한다.
+  const bodyStyle =
+    typeof padding !== "undefined"
+      ? ({
+          "--modal-dialog-body-padding": stylePaddingSize("rem", padding),
+        } as CSSProperties)
+      : undefined;
+
+  return (
+    <div className={clsx("uds-modal-container", className)}>
+      {header ? <ModalHeaderContainer>{header}</ModalHeaderContainer> : null}
+      <ModalBody style={bodyStyle}>{body}</ModalBody>
+      {footer ? <div className="uds-modal-footer">{footer}</div> : null}
+      {!footer && footerButtons && footerButtons.length ? (
+        <div className="uds-modal-footer">
+          <ModalFooterButtonWrapper
+            stackKey={stackKey}
+            buttons={footerButtons}
+          />
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/src/modal/{core/components → components/core}/Root.tsx

@@ -2,25 +2,27 @@
 
 import { useCallback, useEffect, useMemo } from "react";
 import type { CSSProperties } from "react";
-import clsx from "clsx";
 
-import { useModal } from "../hooks/useModal";
-import { ModalContainer } from "./Container";
+import clsx from "clsx";
 
 import type { ModalRootProps } from "../../types";
+import { useModal } from "../../hooks/useModal";
+import { ModalContainer } from "./Container";
 
 type ModalSurfaceStyle = CSSProperties & {
   "--modal-panel-width"?: string | number;
 };
 
 /**
- * 모달 Root; overlay 클릭 닫기와 상태 전환을 담당한다.
+ * Modal Root; overlay 클릭 닫기와 상태 전환 처리
  * @component
- * @param {ModalRootProps} props 루트 속성
- * @property {string} stackKey 모달 스택 식별자
- * @property {ModalProps} modalProps 모달 렌더링에 필요한 상태
- * @property {number} index Provider에서 전달한 스택 index
- * @property {string} [className] 사용자 정의 className
+ * @param {ModalRootProps} props
+ * @param {string} props.stackKey 모달 스택 식별자
+ * @param {ModalProps} props.modalProps 모달 렌더링에 필요한 상태
+ * @param {number} props.index Provider에서 전달한 스택 index
+ * @param {string} [props.className] 사용자 정의 className
+ * @example
+ * <ModalRoot stackKey="sample" modalProps={modalProps} index={0} />
  */
 export function ModalRoot({
   stackKey,
@@ -47,7 +49,7 @@ export function ModalRoot({
     [],
   );
 
-  // show 상태를 data-state로 직접 매핑해 애니메이션 상태를 표현한다.
+  // 변경: show 상태를 data-state로 매핑해 애니메이션 상태를 명확히 유지한다.
   const dataState = useMemo(() => {
     if (modalProps.show === "init") {
       return "init";

package/src/modal/{core/components → components/core}/RouteReset.tsx

@@ -1,10 +1,11 @@
 "use client";
 
 import { useEffect } from "react";
+
 import { usePathname } from "next/navigation";
 import { useSetAtom } from "jotai";
 
-import { modalStackAtom } from "../jotai/atoms";
+import { modalStackAtom } from "../../jotai/atoms";
 
 /**
  * Modal Route Reset; 라우트 변경 시 모달 스택 초기화
@@ -12,6 +13,8 @@ import { modalStackAtom } from "../jotai/atoms";
  * @desc
  * - Next.js pathname 변경을 감지해 `modalStackAtom`을 빈 배열로 되돌린다.
  * - 최상위 layout에서 `<Modal.RouteReset />`을 Provider와 함께 렌더링해야 한다.
+ * @example
+ * <ModalRouteReset />
  */
 export function ModalRouteReset() {
   const pathname = usePathname();

package/src/modal/{core/components/Provider.tsx → components/core/StackProvider.tsx}

@@ -2,20 +2,24 @@
 
 import { Fragment } from "react";
 
-import { useModal } from "../hooks/useModal";
+import { useModal } from "../../hooks/useModal";
 import { ModalRoot } from "./Root";
 
 /**
- * 서비스 루트에서 1회 배치되는 모달 Provider.
+ * Modal Stack Provider; 모달 스택 루트 렌더러
  * @component
  * @desc
- * - `useModal()`에서 관리하는 스택을 순회하며 `ModalRoot`를 순차 렌더링한다.
- * - 모달이 없으면 아무 것도 렌더하지 않는다.
+ * - `useModal()`에서 관리하는 스택을 순회하며 `ModalRoot`를 렌더링한다.
+ * - 스택이 비어 있으면 아무 것도 렌더하지 않는다.
+ * @example
+ * <ModalStackProvider />
  */
-export function ModalProvider() {
+export function ModalStackProvider() {
   const { modalStacks } = useModal();
 
-  if (!modalStacks.length) return null;
+  if (!modalStacks.length) {
+    return null;
+  }
 
   return (
     <Fragment>
@@ -29,3 +33,5 @@ export function ModalProvider() {
     </Fragment>
   );
 }
+
+export const ModalProvider = ModalStackProvider;

package/src/modal/{core/components/FooterPositionButton.tsx → components/core/footer/Button.tsx}

@@ -3,15 +3,21 @@
 import clsx from "clsx";
 import { Button } from "@uniai-fe/uds-primitives";
 
-import type { FooterPositionButtonProps } from "../../types";
+import type { FooterPositionButtonProps } from "../../../types";
 
 /**
- * footer 버튼 단일 요소.
+ * Modal Footer Button; footer 단일 버튼 요소
  * @component
- * @param {FooterPositionButtonProps} props 버튼 정보
+ * @param {FooterPositionButtonProps} props
  * @param {FooterResolvedButton} props.button 렌더링할 버튼
+ * @param {string} [props.className] 버튼 className
+ * @example
+ * <ModalFooterButtonElement button={resolvedButton} />
  */
-export function FooterPositionButton({ button }: FooterPositionButtonProps) {
+export function ModalFooterButtonElement({
+  button,
+  className,
+}: FooterPositionButtonProps) {
   const { appearance, width, block, defaultOptions, linkOptions, onClick } =
     button;
   const anchorProps = linkOptions
@@ -28,6 +34,7 @@ export function FooterPositionButton({ button }: FooterPositionButtonProps) {
       ? "uds-modal-footer-button-text"
       : "uds-modal-footer-button-solid",
     defaultOptions.className,
+    className,
   );
   const commonProps = {
     className: baseClassName,
@@ -43,6 +50,7 @@ export function FooterPositionButton({ button }: FooterPositionButtonProps) {
       defaultOptions.priority && defaultOptions.priority !== "primary"
         ? defaultOptions.priority
         : "secondary";
+
     return (
       <Button.Text
         {...commonProps}
@@ -56,6 +64,7 @@ export function FooterPositionButton({ button }: FooterPositionButtonProps) {
 
   const fill = defaultOptions.fill ?? "solid";
   const size = defaultOptions.size ?? "large";
+
   return (
     <Button.Default
       {...commonProps}

package/src/modal/components/core/footer/ButtonGroup.tsx

@@ -0,0 +1,34 @@
+"use client";
+
+import clsx from "clsx";
+
+import type { FooterPositionGroupProps } from "../../../types";
+import { ModalFooterButtonElement } from "./Button";
+
+/**
+ * Modal Footer ButtonGroup; footer 위치 그룹 컨테이너
+ * @component
+ * @param {FooterPositionGroupProps} props
+ * @param {FooterPosition} props.position 렌더링 위치
+ * @param {FooterResolvedButton[]} props.buttons 위치별 버튼 목록
+ * @param {string} [props.className] 그룹 className
+ * @example
+ * <ModalFooterButtonGroup position="left" buttons={buttons} />
+ */
+export function ModalFooterButtonGroup({
+  position,
+  buttons,
+  className,
+}: FooterPositionGroupProps) {
+  return (
+    <div
+      className={clsx("uds-modal-footer-group", className)}
+      data-position={position}
+      data-has-buttons={buttons.length > 0}
+    >
+      {buttons.map(button => (
+        <ModalFooterButtonElement key={button.elementKey} button={button} />
+      ))}
+    </div>
+  );
+}

package/src/modal/{core/components/FooterButtons.tsx → components/core/footer/ButtonWrapper.tsx}

@@ -1,35 +1,37 @@
 "use client";
 
-import { useModal } from "../hooks/useModal";
-import { FooterPositionGroup } from "./FooterPositionGroup";
-import { FooterPositionButton } from "./FooterPositionButton";
+import clsx from "clsx";
 
 import type {
-  FooterResolvedButton,
   FooterPosition,
-  ModalFooterButton,
-} from "../../types";
+  FooterResolvedButton,
+  FooterButtonWrapperProps,
+} from "../../../types";
+import { useModal } from "../../../hooks/useModal";
+import { ModalFooterButtonElement } from "./Button";
+import { ModalFooterButtonGroup } from "./ButtonGroup";
 
 /**
- * 모달 footer 버튼 리스트 렌더러.
+ * Modal Footer ButtonWrapper; footer 버튼 목록 조합 렌더러
  * @component
- * @param {object} props footer 버튼 렌더 옵션
+ * @param {FooterButtonWrapperProps} props
  * @param {string} props.stackKey 버튼이 속한 모달 스택 키
  * @param {ModalFooterButton[]} props.buttons footer 버튼 정의 목록
+ * @param {string} [props.className] wrapper className
+ * @example
+ * <ModalFooterButtonWrapper stackKey="sample" buttons={buttons} />
  */
-export function ModalFooterButtons({
+export function ModalFooterButtonWrapper({
   stackKey,
   buttons,
-}: {
-  stackKey: string;
-  buttons: ModalFooterButton[];
-}) {
+  className,
+}: FooterButtonWrapperProps) {
   const { closeModal } = useModal();
   const resolvedButtons: FooterResolvedButton[] = buttons.map(
     (button, index) => {
       const appearance = button.defaultOptions.appearance ?? "default";
       const position = button.position ?? "center";
-      // 기본 폭 정책: center는 fill, 좌/우는 fit
+      // 변경: 기본 폭 정책은 center=fill, 좌/우=fit을 유지한다.
       const width = button.width ?? (position === "center" ? "fill" : "fit");
       const block =
         typeof button.defaultOptions.block === "boolean"
@@ -37,12 +39,14 @@ export function ModalFooterButtons({
           : width === "full";
       const closeOnClick = button.closeOnClick ?? button.role === "close";
       const elementKey = `modal/${stackKey}/footer/${button.role}/${index}`;
+
       const handleClick = () => {
         button.defaultOptions.onClick?.();
         if (closeOnClick) {
           closeModal({ stackKey });
         }
       };
+
       return {
         elementKey,
         appearance,
@@ -55,6 +59,7 @@ export function ModalFooterButtons({
       };
     },
   );
+
   const groupAppearance = resolvedButtons.every(
     button => button.appearance === "text",
   )
@@ -63,18 +68,19 @@ export function ModalFooterButtons({
 
   return (
     <div
-      className="uds-modal-footer-buttons"
+      className={clsx("uds-modal-footer-buttons", className)}
       data-count={resolvedButtons.length}
       data-appearance={groupAppearance}
     >
-      {/* start/end 그룹을 렌더링하고 center 버튼은 wrap 컨테이너로 처리한다. */}
       {(["left", "right"] as FooterPosition[]).map(position => {
         const groupButtons = resolvedButtons.filter(
           button => button.position === position,
         );
-        if (!groupButtons.length) return null;
+        if (!groupButtons.length) {
+          return null;
+        }
         return (
-          <FooterPositionGroup
+          <ModalFooterButtonGroup
             key={`modal/${stackKey}/footer-group/${position}`}
             position={position}
             buttons={groupButtons}
@@ -86,7 +92,10 @@ export function ModalFooterButtons({
           {resolvedButtons
             .filter(button => button.position === "center")
             .map(button => (
-              <FooterPositionButton key={button.elementKey} button={button} />
+              <ModalFooterButtonElement
+                key={button.elementKey}
+                button={button}
+              />
             ))}
         </div>
       ) : null}

package/src/modal/components/core/header/CloseButton.tsx

@@ -0,0 +1,32 @@
+"use client";
+
+import clsx from "clsx";
+
+import type { ModalHeaderCloseButtonProps } from "../../../types";
+
+/**
+ * Modal Header CloseButton; 모달 헤더 닫기 버튼
+ * @component
+ * @param {ModalHeaderCloseButtonProps} props
+ * @param {() => void} props.onClick 클릭 핸들러
+ * @param {string} [props.ariaLabel] 접근성 라벨
+ * @param {string} [props.className] 버튼 className
+ * @example
+ * <ModalHeaderCloseButton onClick={handleClose} />
+ */
+export function ModalHeaderCloseButton({
+  onClick,
+  ariaLabel = "닫기",
+  className,
+}: ModalHeaderCloseButtonProps) {
+  return (
+    <button
+      type="button"
+      className={clsx("uds-modal-header-close-button", className)}
+      aria-label={ariaLabel}
+      onClick={onClick}
+    >
+      X
+    </button>
+  );
+}

package/src/modal/components/core/header/Container.tsx

@@ -0,0 +1,21 @@
+"use client";
+
+import clsx from "clsx";
+
+import type { ModalHeaderContainerProps } from "../../../types";
+
+/**
+ * Modal Header Container; 모달 header wrapper
+ * @component
+ * @param {ModalHeaderContainerProps} props
+ * @param {React.ReactNode} props.children 헤더 콘텐츠
+ * @param {string} [props.className] 헤더 wrapper className
+ * @example
+ * <ModalHeaderContainer><h3>제목</h3></ModalHeaderContainer>
+ */
+export function ModalHeaderContainer({
+  children,
+  className,
+}: ModalHeaderContainerProps) {
+  return <div className={clsx("uds-modal-header", className)}>{children}</div>;
+}

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

@@ -0,0 +1,32 @@
+"use client";
+
+import clsx from "clsx";
+
+import type { DialogContentsProps } from "../../types";
+
+/**
+ * Modal Dialog Contents; Dialog 본문 콘텐츠 영역
+ * @component
+ * @param {DialogContentsProps} props
+ * @param {React.ReactNode} props.content 본문 콘텐츠
+ * @param {string} [props.className] body wrapper className
+ * @param {string} [props.contentClassName] 본문 콘텐츠 className
+ * @example
+ * <DialogContents content="본문" />
+ */
+export function DialogContents({
+  content,
+  className,
+  contentClassName,
+}: DialogContentsProps) {
+  // 변경: text 전용 children은 string | number일 때만 래핑해 스타일 충돌을 줄인다.
+  const shouldWrapAsText = ["string", "number"].includes(typeof content);
+
+  return (
+    <div className={clsx("uds-modal-dialog-body", className)}>
+      <div className={clsx("uds-modal-dialog-body-content", contentClassName)}>
+        {shouldWrapAsText ? <p>{content}</p> : content}
+      </div>
+    </div>
+  );
+}