@uniai-fe/uds-templates 0.5.21 → 0.5.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/uds-templates",
-  "version": "0.5.21",
+  "version": "0.5.23",
   "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;
@@ -78,9 +106,34 @@ export default function AuthLoginFormField({
   const idLabel = idField?.label ?? texts?.idLabel ?? "아이디";
   const passwordLabel =
     passwordField?.label ?? texts?.passwordLabel ?? "비밀번호";
+  const isLoginSubmitting = Boolean(isSubmitting);
+  // Button loading은 readonly/aria-busy 같은 상태 의미를 제공하지만, 라벨은 자동 변경하지 않는다.
+  // pending 중에는 눈에 보이는 문구도 바꿔 사용자가 "요청 처리 중"임을 즉시 알 수 있게 한다.
+  const submitLabel = isLoginSubmitting
+    ? (texts?.submitting ?? "로그인 중...")
+    : (texts?.submit ?? "로그인");
+  const idInputProps = {
+    ...(idField?.inputProps ?? {}),
+    // 별도 fieldset 계층을 만들지 않고 primitives input에 직접 pending 잠금을 전달한다.
+    // readOnly는 현재 입력값을 유지하면서 편집만 막기 때문에, API 지연 중 RHF 값 흐름을 건드리지 않는다.
+    readOnly: isLoginSubmitting || idField?.inputProps?.readOnly,
+  };
+  const passwordInputProps = {
+    ...(passwordField?.inputProps ?? {}),
+    // 비밀번호 필드도 아이디와 같은 pending 잠금 정책을 따른다.
+    // disabled 대신 readOnly를 써서 제출 중 값 보존과 UI 잠금을 함께 맞춘다.
+    readOnly: isLoginSubmitting || passwordField?.inputProps?.readOnly,
+  };
 
+  // aria-busy는 외부 로그인 요청 진행 상태만 전달한다.
+  // 실제 사용자 피드백 modal/문구는 서비스 앱의 Modal.Alert/Dialog 흐름에서 처리한다.
   return (
-    <form className="auth-login-form" {...formAttr} onSubmit={onSubmit}>
+    <form
+      className="auth-login-form"
+      {...formAttr}
+      aria-busy={isLoginSubmitting || undefined}
+      onSubmit={handleFormSubmit}
+    >
       <div className="auth-login-fields">
         {/* 아이디 필드: placeholder/label/templateProps를 그대로 내려 투명한 조립 구조를 유지한다. */}
         <AuthLoginFormFieldId
@@ -94,7 +147,7 @@ export default function AuthLoginFormField({
               ? `${idLabel}를 입력해 주세요`
               : "아이디를 입력해 주세요")
           }
-          inputProps={idField?.inputProps}
+          inputProps={idInputProps}
           templateProps={idField?.templateProps}
         />
         {/* 비밀번호 필드: PasswordInput 특성만 다르고 나머지 구조는 동일하다. */}
@@ -107,7 +160,7 @@ export default function AuthLoginFormField({
             texts?.passwordPlaceholder ??
             "비밀번호를 입력해 주세요"
           }
-          inputProps={passwordField?.inputProps}
+          inputProps={passwordInputProps}
           templateProps={passwordField?.templateProps}
         />
         <Button.Default
@@ -116,9 +169,13 @@ export default function AuthLoginFormField({
           size="xlarge"
           priority="primary"
           block
+          // 외부 pending 중에는 primitives Button의 loading 경로를 사용한다.
+          // Button.Default는 loading=true일 때 readonly 상태와 aria-busy를 적용하므로,
+          // "값은 채워졌지만 로그인 요청 처리 중"인 상태를 disabled-only 상태와 구분할 수 있다.
+          loading={isLoginSubmitting}
           disabled={disabled}
         >
-          {texts?.submit ?? "로그인"}
+          {submitLabel}
         </Button.Default>
       </div>
     </form>

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

@@ -223,6 +223,7 @@ export interface AuthLoginPasswordFieldOptions extends AuthLoginFieldProps<Input
  * @property {ReactNode} [passwordLabel] 비밀번호 필드 기본 라벨
  * @property {string} [passwordPlaceholder] 비밀번호 필드 기본 placeholder
  * @property {ReactNode} [submit] submit 버튼 라벨
+ * @property {ReactNode} [submitting] 로그인 요청 pending 중 submit 버튼 라벨
  */
 export interface AuthLoginFieldTexts {
   /**
@@ -245,6 +246,10 @@ export interface AuthLoginFieldTexts {
    * submit 버튼 라벨
    */
   submit?: ReactNode;
+  /**
+   * 로그인 요청 pending 중 submit 버튼 라벨
+   */
+  submitting?: ReactNode;
 }
 
 /**
@@ -281,6 +286,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 +303,14 @@ export interface AuthLoginFieldOptions {
    * 로그인 form 기본 문구 옵션
    */
   texts?: AuthLoginFieldTexts;
+  /**
+   * 외부 로그인 요청 pending 여부
+   * @desc
+   * - 서비스 앱에서 React Query mutation pending 값을 주입한다.
+   * - RHF isSubmitting은 onLogin이 Promise를 반환할 때만 실제 요청 시간을 대표하므로,
+   *   mutate()를 호출하고 즉시 반환하는 서비스 흐름에서는 이 값으로 중복 제출을 잠근다.
+   */
+  isSubmitting?: boolean;
   /**
    * form attr
    */