@uniai-fe/uds-templates 0.3.4 → 0.3.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/uds-templates",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "UNIAI Design System; UI Templates Package",
   "type": "module",
   "private": false,
@@ -12,7 +12,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "packageManager": "pnpm@10.30.2",
+  "packageManager": "pnpm@10.30.3",
   "engines": {
     "node": ">=24",
     "pnpm": ">=10"

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

@@ -8,6 +8,7 @@ import type {
   ModalState,
   ModalTemplateButtonSpec,
 } from "../../types";
+import type { FieldValues } from "react-hook-form";
 
 const DEFAULT_CONFIRM_LABEL = "확인";
 
@@ -23,11 +24,12 @@ const DEFAULT_CONFIRM_LABEL = "확인";
  * @param {number} [options.showDelay] close 후 제거 지연(ms)
  * @param {number | string} [options.width] 모달 width
  * @param {StyleSpacingType} [options.padding] 모달 body padding
+ * @param {UseFormProps<FormContext>} [options.formContextOptions] modal 내부 Form.Provider 옵션
  * @returns {ModalState}
  * @example
  * Modal.Alert({ stackKey: "sample", message: "완료되었습니다." })
  */
-export function createAlertModal({
+export function createAlertModal<FormContext extends FieldValues>({
   stackKey,
   message,
   confirm,
@@ -36,7 +38,8 @@ export function createAlertModal({
   showDelay,
   width,
   padding,
-}: AlertTemplateOptions): ModalState {
+  formContextOptions,
+}: AlertTemplateOptions<FormContext>): ModalState<FormContext> {
   const primary: ModalTemplateButtonSpec = confirm ?? {
     label: DEFAULT_CONFIRM_LABEL,
   };
@@ -48,6 +51,8 @@ export function createAlertModal({
       showDelay,
       width,
       padding,
+      // 변경 설명: 템플릿 생성 시점의 FormContext 제네릭을 modalProps로 전달한다.
+      formContextOptions,
       body: <AlertContents message={message} />,
       footer,
       // 변경: footer가 없을 때만 템플릿 버튼 스펙을 조합한다.

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

@@ -1,6 +1,6 @@
 "use client";
 
-import type { CSSProperties } from "react";
+import { type CSSProperties } from "react";
 
 import clsx from "clsx";
 import { stylePaddingSize } from "@uniai-fe/util-functions";
@@ -9,6 +9,7 @@ import type { ModalContainerProps } from "../../types";
 import { ModalBody } from "./Body";
 import { ModalHeaderContainer } from "./header/Container";
 import { ModalFooterButtonWrapper } from "./footer/ButtonWrapper";
+import { Form } from "@uniai-fe/uds-primitives";
 
 /**
  * Modal Container; header/body/footer 슬롯 조합 컨테이너
@@ -32,6 +33,7 @@ export function ModalContainer({
   footerButtons,
   padding,
   className,
+  formContextOptions,
 }: ModalContainerProps) {
   // 변경: modalProps의 padding을 CSS 변수로 주입해 템플릿 단위 body spacing 제어를 유지한다.
   const bodyStyle =
@@ -41,19 +43,28 @@ export function ModalContainer({
         } as CSSProperties)
       : undefined;
 
+  const ContextProvider = ({ children }: { children: React.ReactNode }) =>
+    typeof formContextOptions !== "undefined" ? (
+      <Form.Provider options={formContextOptions}>{children}</Form.Provider>
+    ) : (
+      children
+    );
+
   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>
+    <ContextProvider>
+      <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>
+    </ContextProvider>
   );
 }

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

@@ -8,6 +8,7 @@ import {
 } from "../../utils/create-dialog-footer-buttons";
 
 import type { DialogTemplateOptions, ModalState } from "../../types";
+import type { FieldValues } from "react-hook-form";
 
 /**
  * Modal Dialog Template; Dialog 모달 상태 생성기
@@ -29,11 +30,12 @@ import type { DialogTemplateOptions, ModalState } from "../../types";
  * @param {number} [options.showDelay] close 후 제거 지연(ms)
  * @param {number | string} [options.width] 모달 width
  * @param {StyleSpacingType} [options.padding] 모달 body padding
+ * @param {UseFormProps<FormContext>} [options.formContextOptions] modal 내부 Form.Provider 옵션
  * @returns {ModalState}
  * @example
  * Modal.Dialog({ stackKey: "sample", title: "제목", content: "본문" })
  */
-export function createDialogModal({
+export function createDialogModal<FormContext extends FieldValues>({
   stackKey,
   title,
   description,
@@ -50,7 +52,8 @@ export function createDialogModal({
   showDelay,
   width,
   padding,
-}: DialogTemplateOptions): ModalState {
+  formContextOptions,
+}: DialogTemplateOptions<FormContext>): ModalState<FormContext> {
   const primary = resolveDialogPrimaryButton(confirm);
 
   const headerNode =
@@ -77,6 +80,8 @@ export function createDialogModal({
       showDelay,
       width,
       padding,
+      // 변경 설명: 템플릿 생성 시점의 FormContext 제네릭을 modalProps로 전달한다.
+      formContextOptions,
       header: headerNode ?? undefined,
       body: <DialogContents content={content} className={bodyClassName} />,
       footer,

package/src/modal/hooks/useModal.ts

@@ -7,11 +7,13 @@ import { useAtom } from "jotai";
 import type {
   CloseFlagState,
   ModalCloseRequest,
+  ModalProps,
   ModalState,
   ModalStatePatch,
   UseModalReturn,
 } from "../types";
 import { modalStackAtom } from "../jotai/atoms";
+import type { FieldValues } from "react-hook-form";
 
 const DEFAULT_CLOSE_DELAY = 400;
 
@@ -30,7 +32,7 @@ export function useModal(): UseModalReturn {
   const [closeFlag, setCloseFlag] = useState<CloseFlagState | null>(null);
 
   const newModal = useCallback(
-    (newStack: ModalState) => {
+    <FormContext extends FieldValues>(newStack: ModalState<FormContext>) => {
       updateModalStack((stacks: ModalState[]) => {
         const exists = stacks.some(
           stack => stack.stackKey === newStack.stackKey,
@@ -45,7 +47,10 @@ export function useModal(): UseModalReturn {
           ...stacks,
           {
             ...newStack,
-            modalProps: { ...newStack.modalProps, show: "init" },
+            modalProps: {
+              ...(newStack.modalProps as ModalProps),
+              show: "init",
+            },
           },
         ];
       });
@@ -54,14 +59,20 @@ export function useModal(): UseModalReturn {
   );
 
   const updateModal = useCallback(
-    (nextStack: ModalStatePatch) => {
+    <FormContext extends FieldValues>(
+      nextStack: ModalStatePatch<FormContext>,
+    ) => {
       updateModalStack((stacks: ModalState[]) =>
         stacks.map(stack => {
           if (stack.stackKey !== nextStack.stackKey) {
             return stack;
           }
-          const mergedProps = nextStack.modalProps
-            ? { ...stack.modalProps, ...nextStack.modalProps }
+          // 변경 설명: 스택 저장 타입은 공통 ModalProps로 유지하고, 제네릭 옵션은 생성 경계에서만 보장한다.
+          const mergedProps: ModalProps = nextStack.modalProps
+            ? {
+                ...stack.modalProps,
+                ...(nextStack.modalProps as Partial<ModalProps>),
+              }
             : stack.modalProps;
           return {
             ...stack,

package/src/modal/types/components.ts

@@ -1,4 +1,5 @@
 import type { CSSProperties, ReactNode } from "react";
+import type { FieldValues } from "react-hook-form";
 import type {
   ModalFooterButtonAppearance,
   ModalFooterButtonDefaultOptions,
@@ -12,11 +13,13 @@ import type { ModalFooterButton } from "./footer";
 /**
  * ModalRoot 컴포넌트 props.
  * @property {string} stackKey 모달 스택 식별자
- * @property {ModalProps} modalProps 모달 렌더링에 필요한 상태
+ * @property {ModalProps<FormContext>} modalProps 모달 렌더링에 필요한 상태
  * @property {number} index Provider에서 전달한 스택 index
  * @property {string} [className] 사용자 정의 className
  */
-export type ModalRootProps = ModalState & {
+export type ModalRootProps<
+  FormContext extends FieldValues = Record<string, unknown>,
+> = ModalState<FormContext> & {
   /**
    * 모달 스택 식별자
    */
@@ -24,7 +27,7 @@ export type ModalRootProps = ModalState & {
   /**
    * 모달 렌더링에 필요한 상태
    */
-  modalProps: ModalProps;
+  modalProps: ModalProps<FormContext>;
   /**
    * Provider에서 전달한 스택 index
    */
@@ -43,8 +46,11 @@ export type ModalRootProps = ModalState & {
  * @property {ReactNode} [footer] footer 콘텐츠
  * @property {ModalFooterButton[]} [footerButtons] footer 버튼 목록
  * @property {string} [className] 컨테이너 className
+ * @property {UseFormProps<FormContext>} [formContextOptions] form context 옵션
  */
-export type ModalContainerProps = ModalSections & {
+export type ModalContainerProps<
+  FormContext extends FieldValues = Record<string, unknown>,
+> = ModalSections<FormContext> & {
   /**
    * 모달 스택 식별자
    */

package/src/modal/types/hooks.ts

@@ -1,11 +1,12 @@
 import type { ModalCloseRequest } from "./options";
 import type { ModalState, ModalStatePatch } from "./state";
+import type { FieldValues } from "react-hook-form";
 
 /**
  * close flag 상태; 모달 스택 제거 예약을 표현한다.
  * @property {string} stackKey 닫을 모달 스택 키
  * @property {number} showDelay 제거까지 대기할 지연(ms)
- * @property {ModalCloseRequest["callback"]} [callback] 완료 후 실행 콜백
+ * @property {() => void} [callback] 완료 후 실행 콜백
  */
 export type CloseFlagState = {
   /**
@@ -19,14 +20,14 @@ export type CloseFlagState = {
   /**
    * 완료 후 실행 콜백
    */
-  callback?: ModalCloseRequest["callback"];
+  callback?: () => void;
 };
 
 /**
  * useModal 훅 반환값.
  * @property {ModalState[]} modalStacks 현재 모달 스택 목록
- * @property {(newStack: ModalState) => void} newModal 신규 모달 추가 함수
- * @property {(nextStack: ModalStatePatch) => void} updateModal 스택 상태 갱신 함수
+ * @property {<FormContext extends FieldValues>(newStack: ModalState<FormContext>) => void} newModal 신규 모달 추가 함수
+ * @property {<FormContext extends FieldValues>(nextStack: ModalStatePatch<FormContext>) => void} updateModal 스택 상태 갱신 함수
  * @property {(request: ModalCloseRequest) => void} closeModal close 제어 함수
  */
 export type UseModalReturn = {
@@ -37,11 +38,15 @@ export type UseModalReturn = {
   /**
    * 신규 모달 추가 함수
    */
-  newModal: (newStack: ModalState) => void;
+  newModal: <FormContext extends FieldValues>(
+    newStack: ModalState<FormContext>,
+  ) => void;
   /**
    * 스택 상태 갱신 함수
    */
-  updateModal: (nextStack: ModalStatePatch) => void;
+  updateModal: <FormContext extends FieldValues>(
+    nextStack: ModalStatePatch<FormContext>,
+  ) => void;
   /**
    * close 제어 함수
    */

package/src/modal/types/state.ts

@@ -2,6 +2,7 @@ import type { ReactNode } from "react";
 
 import type { ModalFooterButton } from "./footer";
 import type { StyleSpacingType } from "@uniai-fe/util-functions";
+import type { FieldValues, UseFormProps } from "react-hook-form";
 
 /**
  * Modal 노출 상태 표현값.
@@ -16,8 +17,11 @@ export type ModalShowState = "init" | boolean;
  * @property {ReactNode} [footer] footer 콘텐츠
  * @property {number | string} [width] 커스텀 width
  * @property {StyleSpacingType} [padding] 커스텀 padding
+ * @property {UseFormProps<FormContext>} [formContextOptions] form context 옵션
  */
-export type ModalSections = {
+export type ModalSections<
+  FormContext extends FieldValues = Record<string, unknown>,
+> = {
   /**
    * 헤더 콘텐츠
    */
@@ -44,6 +48,15 @@ export type ModalSections = {
    * - [상, 우, 하, 좌]
    */
   padding?: StyleSpacingType;
+  /**
+   * form context 옵션
+   * - 옵션이 활성화되면, Form.Provider 사용으로 간주하여 활성화시킴
+   * ```
+   * // 다음과 같이 전달
+   * <Form.Provider options={formContextOptions}>
+   * ```
+   */
+  formContextOptions?: UseFormProps<FormContext>;
 };
 
 /**
@@ -56,8 +69,11 @@ export type ModalSections = {
  * @property {ModalShowState} show 노출 상태
  * @property {number} [showDelay] close 후 제거 지연(ms)
  * @property {ModalFooterButton[]} [footerButtons] footer 버튼 스펙
+ * @property {UseFormProps<FormContext>} [formContextOptions] form context 옵션
  */
-export type ModalProps = ModalSections & {
+export type ModalProps<
+  FormContext extends FieldValues = Record<string, unknown>,
+> = ModalSections<FormContext> & {
   /**
    * 노출 상태
    */
@@ -75,10 +91,12 @@ export type ModalProps = ModalSections & {
 /**
  * Modal 스택에 저장되는 상태.
  * @property {string} stackKey 모달 스택 키
- * @property {ModalProps} modalProps 컨테이너 props
+ * @property {ModalProps<FormContext>} modalProps 컨테이너 props
  * @property {string} [className] 추가 className
  */
-export type ModalState = {
+export type ModalState<
+  FormContext extends FieldValues = Record<string, unknown>,
+> = {
   /**
    * 모달 스택 키
    */
@@ -86,7 +104,7 @@ export type ModalState = {
   /**
    * 컨테이너 props
    */
-  modalProps: ModalProps;
+  modalProps: ModalProps<FormContext>;
   /**
    * 추가 className
    */
@@ -96,10 +114,12 @@ export type ModalState = {
 /**
  * Modal 상태 패치 데이터.
  * @property {string} stackKey 수정할 모달 스택 키
- * @property {Partial<ModalProps>} [modalProps] 덮어쓸 props
+ * @property {Partial<ModalProps<FormContext>>} [modalProps] 덮어쓸 props
  * @property {string} [className] 추가 className
  */
-export type ModalStatePatch = {
+export type ModalStatePatch<
+  FormContext extends FieldValues = Record<string, unknown>,
+> = {
   /**
    * 수정할 모달 스택 키
    */
@@ -107,7 +127,7 @@ export type ModalStatePatch = {
   /**
    * 덮어쓸 props
    */
-  modalProps?: Partial<ModalProps>;
+  modalProps?: Partial<ModalProps<FormContext>>;
   /**
    * 추가 className
    */

package/src/modal/types/templates.ts

@@ -1,4 +1,5 @@
 import type { ReactNode } from "react";
+import type { FieldValues, UseFormProps } from "react-hook-form";
 
 import type {
   ModalFooterButtonPosition,
@@ -56,7 +57,9 @@ export type ModalTemplateButtonSpec = {
  * @property {number | string} [width] 커스텀 width
  * @property {StyleSpacingType} [padding] 커스텀 padding
  */
-type ModalTemplateBase = {
+type ModalTemplateBase<
+  FormContext extends FieldValues = Record<string, unknown>,
+> = {
   /**
    * 모달 스택 키
    */
@@ -79,6 +82,11 @@ type ModalTemplateBase = {
    * - [상, 우, 하, 좌]
    */
   padding?: StyleSpacingType;
+  /**
+   * modal 내부 Form.Provider 옵션
+   * - 타입 안정성은 Modal.Alert/Dialog 생성 시점 제네릭으로 보장한다.
+   */
+  formContextOptions?: UseFormProps<FormContext>;
 };
 
 /**
@@ -91,8 +99,11 @@ type ModalTemplateBase = {
  * @property {ReactNode} [footer] 커스텀 footer
  * @property {number | string} [width] 커스텀 width
  * @property {StyleSpacingType} [padding] 커스텀 padding
+ * @property {UseFormProps<FormContext>} [formContextOptions] modal 내부 Form.Provider 옵션
  */
-export type AlertTemplateOptions = ModalTemplateBase & {
+export type AlertTemplateOptions<
+  FormContext extends FieldValues = Record<string, unknown>,
+> = ModalTemplateBase<FormContext> & {
   /**
    * 본문 메시지
    */
@@ -109,6 +120,10 @@ export type AlertTemplateOptions = ModalTemplateBase & {
    * 커스텀 footer
    */
   footer?: ReactNode;
+  /**
+   * modal 내부 Form.Provider 옵션
+   */
+  formContextOptions?: UseFormProps<FormContext>;
 };
 
 /**
@@ -129,8 +144,11 @@ export type AlertTemplateOptions = ModalTemplateBase & {
  * @property {ReactNode} [footer] 커스텀 footer
  * @property {number | string} [width] 커스텀 width
  * @property {StyleSpacingType} [padding] 커스텀 padding
+ * @property {UseFormProps<FormContext>} [formContextOptions] modal 내부 Form.Provider 옵션
  */
-export type DialogTemplateOptions = ModalTemplateBase & {
+export type DialogTemplateOptions<
+  FormContext extends FieldValues = Record<string, unknown>,
+> = ModalTemplateBase<FormContext> & {
   /**
    * 헤더 타이틀
    */
@@ -179,10 +197,16 @@ export type DialogTemplateOptions = ModalTemplateBase & {
    * 커스텀 footer
    */
   footer?: ReactNode;
+  /**
+   * modal 내부 Form.Provider 옵션
+   */
+  formContextOptions?: UseFormProps<FormContext>;
 };
 
 /**
  * Modal 템플릿 결과 타입.
  * @typedef {ModalState} ModalTemplateResult
  */
-export type ModalTemplateResult = ModalState;
+export type ModalTemplateResult<
+  FormContext extends FieldValues = Record<string, unknown>,
+> = ModalState<FormContext>;

package/src/page-frame/desktop/components/header/util/setting/Button.tsx

@@ -42,6 +42,10 @@ export default function PageHeaderSettingButton({
   );
   const pathname = usePathname();
   const resolvedPath = pathname ?? "";
+  const closestRoute = useMemo(
+    () => getClosestRoute(menuItems, resolvedPath),
+    [menuItems, resolvedPath],
+  );
 
   const dropdownItems: DropdownTemplateItem[] = useMemo(
     () =>
@@ -49,19 +53,12 @@ export default function PageHeaderSettingButton({
         id: item.routeKey,
         label: item.name,
         left: item.icon,
+        // 변경: Dropdown.Template 선택 계약은 items[].selected를 source로 사용한다.
+        selected: String(closestRoute?.routeKey) === String(item.routeKey),
       })),
-    [menuItems],
+    [closestRoute?.routeKey, menuItems],
   );
 
-  /**
-   * 현재 경로와 가장 근접한 설정 경로를 계산한다.
-   * - 메뉴 수가 많아져도 useMemo로 계산을 한 번만 수행한다.
-   */
-  const selectedIds = useMemo(() => {
-    const closestRoute = getClosestRoute(menuItems, resolvedPath);
-    return closestRoute ? [String(closestRoute.routeKey)] : [];
-  }, [menuItems, resolvedPath]);
-
   /**
    * dropdown 항목을 선택했을 때 routeKey에 대응하는 onSelect를 실행한다.
    * @param {DropdownTemplateChangePayload} payload 선택 결과 payload
@@ -98,7 +95,6 @@ export default function PageHeaderSettingButton({
         items={dropdownItems}
         width={170}
         size="small"
-        selectedIds={selectedIds}
         // Dropdown.Template 신규 계약(onChange payload)을 우선 사용한다.
         onChange={handleSelect}
         containerProps={{