@uniai-fe/uds-templates 0.5.21 → 0.5.22

package/package.json

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

package/src/auth/login/hooks/useAuthLoginForm.ts

@@ -21,6 +21,7 @@ import type {
 export function useAuthLoginForm({
   fieldNames,
   form,
+  isSubmitting,
   onLogin,
 }: UseAuthLoginFormOptions): UseAuthLoginFormReturn {
   /** 1) form init — useForm은 FormField에서 생성 후 주입된다. */
@@ -67,7 +68,11 @@ export function useAuthLoginForm({
       return typeof value === "string" ? value.trim().length > 0 : false;
     });
 
-  const disabled = form.formState.isSubmitting || !trimmedFilled;
+  // RHF isSubmitting은 handleSubmit 콜백이 반환한 Promise 동안만 유지된다.
+  // 서비스 앱 로그인 컨테이너는 React Query mutate()를 호출하고 즉시 반환하므로,
+  // 실제 API pending 동안의 중복 클릭/Enter submit 차단은 외부 isSubmitting을 함께 봐야 한다.
+  const disabled =
+    form.formState.isSubmitting || Boolean(isSubmitting) || !trimmedFilled;
 
   /** 4) submit — onLogin을 handleSubmit과 결합한다. */
   const onSubmit = form.handleSubmit(onLogin);

package/src/auth/login/markup/FormField.tsx

@@ -3,6 +3,7 @@
 import { useMemo } from "react";
 import { useForm } from "react-hook-form";
 import { Button } from "@uniai-fe/uds-primitives";
+import type { FormEventHandler, SubmitEvent } from "react";
 import type { AuthLoginFieldOptions, AuthLoginFormValues } from "../types";
 import { useAuthLoginForm } from "../hooks";
 import AuthLoginFormFieldId from "./UserId";
@@ -15,6 +16,7 @@ import AuthLoginFormFieldPassword from "./Password";
  * @property {AuthLoginIdFieldOptions} [props.idField] 아이디 필드 옵션
  * @property {AuthLoginPasswordFieldOptions} [props.passwordField] 비밀번호 필드 옵션
  * @property {AuthLoginFieldTexts} [props.texts] 로그인 form 기본 문구 옵션
+ * @property {boolean} [props.isSubmitting] 외부 로그인 요청 pending 여부
  * @property {React.FormHTMLAttributes<HTMLFormElement>} [props.formAttr] <form> attr
  * @property {SubmitHandler<AuthLoginFormValues>} props.onLogin 로그인 콜백
  */
@@ -22,6 +24,7 @@ export default function AuthLoginFormField({
   idField,
   passwordField,
   texts,
+  isSubmitting,
   formAttr,
   onLogin,
 }: AuthLoginFieldOptions) {
@@ -55,9 +58,34 @@ export default function AuthLoginFormField({
       password: passwordFieldName,
     },
     form,
+    isSubmitting,
     onLogin,
   });
 
+  const handleFormSubmit: FormEventHandler<HTMLFormElement> = event => {
+    const nativeEvent =
+      event.nativeEvent as unknown as SubmitEvent<HTMLFormElement>;
+
+    // 소비 앱이 formAttr.onSubmit에서 analytics, validation bridge, custom preventDefault 등을
+    // 처리할 수 있으므로 템플릿 guard보다 먼저 실행한다.
+    formAttr?.onSubmit?.(nativeEvent);
+    if (event.defaultPrevented || nativeEvent.defaultPrevented) {
+      event.preventDefault();
+      return;
+    }
+
+    // disabled는 버튼 상태뿐 아니라 form submit 경계의 단일 잠금 조건이다.
+    // 버튼 클릭이 아닌 Enter submit도 같은 경로에서 막아 로그인 지연 중 중복 API 요청을 차단한다.
+    if (disabled) {
+      event.preventDefault();
+      return;
+    }
+
+    // 잠금 조건을 통과한 경우에만 RHF handleSubmit으로 넘긴다.
+    // 이 시점 이후의 API 호출, 오류 분류, Modal.Alert/Dialog 표시는 서비스 앱 책임이다.
+    void onSubmit(event);
+  };
+
   // helper 텍스트는 RHF 에러 > 필드 옵션 helper 순으로 병합하며, state가 없으면 undefined 처리한다.
   const idHelperNode =
     helpers.id.text !== undefined ? helpers.id.text : idField?.helper;
@@ -79,8 +107,15 @@ export default function AuthLoginFormField({
   const passwordLabel =
     passwordField?.label ?? texts?.passwordLabel ?? "비밀번호";
 
+  // aria-busy는 외부 로그인 요청 진행 상태만 전달한다.
+  // 실제 사용자 피드백 modal/문구는 서비스 앱의 Modal.Alert/Dialog 흐름에서 처리한다.
   return (
-    <form className="auth-login-form" {...formAttr} onSubmit={onSubmit}>
+    <form
+      className="auth-login-form"
+      {...formAttr}
+      aria-busy={Boolean(isSubmitting) || undefined}
+      onSubmit={handleFormSubmit}
+    >
       <div className="auth-login-fields">
         {/* 아이디 필드: placeholder/label/templateProps를 그대로 내려 투명한 조립 구조를 유지한다. */}
         <AuthLoginFormFieldId

package/src/auth/login/types/hooks.ts

@@ -39,6 +39,7 @@ export interface AuthLoginFieldNames {
  * @property {UseFormReturn<AuthLoginFormValues>} form RHF useForm 반환값
  * @property {SubmitHandler<AuthLoginFormValues>} onLogin 제출 핸들러
  * @property {AuthLoginFieldNames} fieldNames RHF field name 매핑
+ * @property {boolean} [isSubmitting] 외부 로그인 요청 pending 여부
  */
 export interface UseAuthLoginFormOptions {
   /**
@@ -53,6 +54,13 @@ export interface UseAuthLoginFormOptions {
    * field name 매핑
    */
   fieldNames: AuthLoginFieldNames;
+  /**
+   * 외부 로그인 요청 pending 여부
+   * @desc
+   * - onLogin이 mutate()처럼 동기 반환되는 경우 RHF isSubmitting만으로는 API pending 구간을 잠글 수 없다.
+   * - 서비스 앱의 pending 상태를 병합해 버튼 클릭과 Enter submit의 중복 요청을 차단한다.
+   */
+  isSubmitting?: boolean;
 }
 
 /**

package/src/auth/login/types/props.ts

@@ -281,6 +281,7 @@ export interface AuthLoginTexts
  * @property {AuthLoginIdFieldOptions} [idField] 로그인 아이디 필드 옵션
  * @property {AuthLoginPasswordFieldOptions} [passwordField] 로그인 비밀번호 필드 옵션
  * @property {AuthLoginFieldTexts} [texts] 로그인 form 기본 문구 옵션
+ * @property {boolean} [isSubmitting] 외부 로그인 요청 pending 여부
  * @property {React.FormHTMLAttributes<HTMLFormElement>} [formAttr] <form /> attributes
  * @property {SubmitHandler<Record<string, string>>} onLogin 로그인 콜백 이벤트
  */
@@ -297,6 +298,14 @@ export interface AuthLoginFieldOptions {
    * 로그인 form 기본 문구 옵션
    */
   texts?: AuthLoginFieldTexts;
+  /**
+   * 외부 로그인 요청 pending 여부
+   * @desc
+   * - 서비스 앱에서 React Query mutation pending 값을 주입한다.
+   * - RHF isSubmitting은 onLogin이 Promise를 반환할 때만 실제 요청 시간을 대표하므로,
+   *   mutate()를 호출하고 즉시 반환하는 서비스 흐름에서는 이 값으로 중복 제출을 잠근다.
+   */
+  isSubmitting?: boolean;
   /**
    * form attr
    */