@uniai-fe/uds-templates 0.0.11 → 0.0.13

package/src/auth/common/password/markup/PasswordSetField.tsx

@@ -0,0 +1,250 @@
+import "../styles/password-set-field.scss";
+
+import { useMemo } from "react";
+import type { ReactNode } from "react";
+import {
+  useFormContext,
+  type FieldPath,
+  type FieldValues,
+} from "react-hook-form";
+import {
+  PasswordInput,
+  type InputPasswordProps,
+} from "@uniai-fe/uds-primitives";
+import CheckPasswordIcon from "../img/check-password.svg";
+import type {
+  AuthPasswordHelperItem,
+  AuthPasswordHelperState,
+  AuthPasswordRule,
+  AuthPasswordSetFieldProps,
+} from "../types";
+import { useCheckPassword } from "../hooks/useCheckPassword";
+import { composePasswordFieldProps } from "../utils/composePasswordFieldProps";
+
+const PASSWORD_MATCHED_HELPER_ID = "confirm-complete";
+const PASSWORD_MISMATCH_HELPER_ID = "confirm-error";
+const PASSWORD_MATCHED_TEXT = "비밀번호 일치";
+const RHF_CONTEXT_ERROR =
+  "AuthPasswordSetField requires react-hook-form context. Wrap it with FormProvider or pass a form prop.";
+
+/**
+ * RHF 컨텍스트 optional getter
+ * @hook
+ */
+function useOptionalFormContext<TValues extends FieldValues>() {
+  try {
+    return useFormContext<TValues>();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Helper 아이템 리스트 렌더러
+ * @param {{ items: AuthPasswordHelperItem[] }} props helper 컬렉션
+ */
+const HelperList = ({ items }: { items: AuthPasswordHelperItem[] }) =>
+  items.length ? (
+    <ul className="auth-password-set-helpers" aria-live="polite">
+      {items.map(item => (
+        <li
+          key={item.id}
+          className="auth-password-set-helper"
+          data-state={item.state}
+        >
+          <figure className="auth-password-set-helper-icon" aria-hidden="true">
+            <CheckPasswordIcon />
+          </figure>
+          <span>{item.text}</span>
+        </li>
+      ))}
+    </ul>
+  ) : null;
+
+/**
+ * Password Input Set; 비밀번호 + 재확인 필드 묶음
+ * @component
+ * @param {AuthPasswordSetFieldProps} props PasswordSetField 구성 요소
+ * @param {UseFormReturn} props.form react-hook-form 객체
+ * @param {AuthPasswordFieldProps<InputPasswordProps>} props.passwordField 비밀번호 입력 필드
+ * @param {AuthPasswordFieldProps<InputPasswordProps>} props.confirmPasswordField 비밀번호 재확인 필드
+ * @param {AuthPasswordRule[]} [props.passwordRules] 비밀번호 규칙 또는 predicate 목록
+ * @param {AuthPasswordSetMessages} [props.messages] 검증 메시지
+ */
+export function AuthPasswordSetField<
+  TValues extends FieldValues = Record<string, string>,
+>({
+  form,
+  passwordField,
+  confirmPasswordField,
+  passwordRules,
+  passwordFieldName,
+  confirmPasswordFieldName,
+  messages,
+}: AuthPasswordSetFieldProps<TValues>) {
+  const contextForm = useOptionalFormContext<TValues>();
+  const resolvedForm = form ?? contextForm;
+
+  if (!resolvedForm) {
+    throw new Error(RHF_CONTEXT_ERROR);
+  }
+  const resolvedPasswordFieldName: FieldPath<TValues> =
+    passwordFieldName ??
+    (passwordField.attr?.name as FieldPath<TValues> | undefined) ??
+    ("password" as FieldPath<TValues>);
+  const resolvedConfirmFieldName: FieldPath<TValues> =
+    confirmPasswordFieldName ??
+    (confirmPasswordField.attr?.name as FieldPath<TValues> | undefined) ??
+    ("confirmPassword" as FieldPath<TValues>);
+
+  const {
+    passwordValue = "",
+    confirmPasswordValue = "",
+    validator: confirmValidator,
+    helper: confirmState,
+    isMatched,
+  } = useCheckPassword<TValues>({
+    form: resolvedForm,
+    passwordField: resolvedPasswordFieldName,
+    confirmField: resolvedConfirmFieldName,
+    helperText: confirmPasswordField.helper,
+    messages,
+  });
+
+  const passwordHelperBase: AuthPasswordHelperState = useMemo(
+    () => ({
+      text:
+        (resolvedForm.getFieldState(resolvedPasswordFieldName).error
+          ?.message as ReactNode | undefined) ?? passwordField.helper,
+      state: resolvedForm.getFieldState(resolvedPasswordFieldName).invalid
+        ? "error"
+        : undefined,
+    }),
+    [passwordField.helper, resolvedForm, resolvedPasswordFieldName],
+  );
+
+  const evaluatedRules = useMemo(() => {
+    if (!passwordRules || passwordRules.length === 0) {
+      return undefined;
+    }
+    return passwordRules.map((rule: AuthPasswordRule) => {
+      const nextFulfilled =
+        typeof rule.fulfilled === "boolean"
+          ? rule.fulfilled
+          : typeof rule.predicate === "function"
+            ? rule.predicate(passwordValue ?? "")
+            : false;
+      return {
+        ...rule,
+        fulfilled: nextFulfilled,
+      };
+    });
+  }, [passwordRules, passwordValue]);
+
+  const hasPasswordValue =
+    typeof passwordValue === "string" && passwordValue.trim().length > 0;
+  const showRules =
+    Boolean(evaluatedRules?.length) &&
+    hasPasswordValue &&
+    passwordHelperBase.state !== "error";
+
+  const allRulesFulfilled =
+    evaluatedRules && evaluatedRules.length > 0
+      ? evaluatedRules.every(rule => rule.fulfilled)
+      : true;
+  const canConfirmPassword =
+    hasPasswordValue &&
+    passwordHelperBase.state !== "error" &&
+    allRulesFulfilled;
+
+  const passwordRulesItems: AuthPasswordHelperItem[] =
+    showRules && evaluatedRules
+      ? evaluatedRules.map((rule: AuthPasswordRule) => ({
+          id: rule.id,
+          text: rule.label,
+          state: rule.fulfilled ? "complete" : undefined,
+        }))
+      : [];
+
+  const confirmHelperItems: AuthPasswordHelperItem[] = [];
+  const blockedByPassword =
+    !canConfirmPassword && Boolean(confirmPasswordValue?.length);
+
+  if (blockedByPassword) {
+    confirmHelperItems.push({
+      id: `${resolvedConfirmFieldName}-blocked`,
+      text: messages?.missing ?? "비밀번호를 먼저 입력해 주세요.",
+      state: "error",
+    });
+  } else if (confirmState.state === "error" && confirmState.text) {
+    confirmHelperItems.push({
+      id: PASSWORD_MISMATCH_HELPER_ID,
+      text: confirmState.text,
+      state: "error",
+    });
+  } else if (
+    isMatched &&
+    passwordHelperBase.state !== "error" &&
+    allRulesFulfilled
+  ) {
+    confirmHelperItems.push({
+      id: PASSWORD_MATCHED_HELPER_ID,
+      text: PASSWORD_MATCHED_TEXT,
+      state: "complete",
+    });
+  }
+
+  const passwordHelperNode: AuthPasswordHelperState = passwordRulesItems.length
+    ? {
+        ...passwordHelperBase,
+        text: <HelperList items={passwordRulesItems} />,
+        state: undefined,
+      }
+    : passwordHelperBase;
+
+  const confirmHelperProps: AuthPasswordHelperState = confirmHelperItems.length
+    ? {
+        ...confirmState,
+        text: <HelperList items={confirmHelperItems} />,
+        state: confirmState.state === "error" ? "error" : undefined,
+      }
+    : { ...confirmState, text: undefined, state: undefined };
+
+  const passwordRegister = resolvedForm.register(resolvedPasswordFieldName);
+  const confirmPasswordRegister = resolvedForm.register(
+    resolvedConfirmFieldName,
+    {
+      validate: confirmValidator,
+    },
+  );
+
+  return (
+    <div className="auth-password-set">
+      <PasswordInput
+        {...composePasswordFieldProps<InputPasswordProps>(
+          passwordField,
+          passwordHelperNode,
+        )}
+        register={passwordRegister}
+        success={null}
+        error={null}
+      />
+      <PasswordInput
+        {...composePasswordFieldProps<InputPasswordProps>(
+          confirmPasswordField,
+          confirmHelperProps,
+        )}
+        register={confirmPasswordRegister}
+        success={null}
+        error={null}
+        disabled={
+          confirmPasswordField.props?.disabled ??
+          confirmPasswordField.attr?.disabled ??
+          !canConfirmPassword
+        }
+      />
+    </div>
+  );
+}
+
+export default AuthPasswordSetField;

package/src/auth/common/password/styles/password-set-field.scss

@@ -0,0 +1,49 @@
+@use "@uniai-fe/uds-foundation/css";
+
+.auth-password-set {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-gap-6, 12px);
+}
+
+.auth-password-set-helpers {
+  list-style: none;
+  padding: 0;
+  margin: var(--spacing-gap-3, 6px) 0 0;
+  display: flex;
+  gap: var(--spacing-gap-3, 6px);
+  flex-wrap: wrap;
+}
+
+.auth-password-set-helper {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  font-size: var(--font-label-small-size);
+  line-height: var(--font-label-small-line-height);
+  color: var(--color-label-assistive);
+
+  &[data-state="error"] {
+    color: var(--color-error);
+
+    svg path {
+      fill: var(--color-error);
+    }
+  }
+
+  &[data-state="complete"] {
+    color: var(--color-success);
+
+    svg path {
+      fill: var(--color-success);
+    }
+  }
+}
+
+.auth-password-set-helper-icon {
+  width: 16px;
+  height: 16px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}

package/src/auth/common/password/types.ts

@@ -0,0 +1,142 @@
+import type { ReactNode } from "react";
+import type {
+  InputFieldProps,
+  InputPasswordProps,
+  InputProps,
+} from "@uniai-fe/uds-primitives";
+import type { FieldPath, FieldValues, UseFormReturn } from "react-hook-form";
+
+/**
+ * Password 필드 공통 prop; primitives InputFieldProps를 그대로 확장한다.
+ * @typedef
+ */
+export type AuthPasswordFieldProps<TProps extends InputProps = InputProps> =
+  InputFieldProps<TProps>;
+
+/**
+ * Password 규칙 메타데이터
+ * @typedef
+ */
+export interface AuthPasswordRule {
+  /**
+   * 규칙 식별자
+   * @type {string}
+   */
+  id: string;
+  /**
+   * 규칙 라벨 또는 설명
+   * @type {ReactNode}
+   */
+  label: ReactNode;
+  /**
+   * 충족 여부(직접 전달)
+   * @type {boolean | undefined}
+   */
+  fulfilled?: boolean;
+  /**
+   * 규칙을 계산하는 predicate
+   * @type {(value: string) => boolean | undefined}
+   */
+  predicate?: (value: string) => boolean;
+}
+
+/**
+ * Password helper 상태
+ * @typedef
+ */
+export interface AuthPasswordHelperState {
+  /**
+   * helper 텍스트
+   * @type {ReactNode | undefined}
+   */
+  text?: ReactNode;
+  /**
+   * helper state (complete/error 등)
+   * @type {AuthPasswordHelperStatus | undefined}
+   */
+  state?: AuthPasswordHelperStatus;
+}
+
+/**
+ * Helper 출력 아이템; list 렌더링에 사용
+ * @typedef
+ */
+export interface AuthPasswordHelperItem {
+  /**
+   * helper 아이템 식별자
+   * @type {string}
+   */
+  id: string;
+  /**
+   * helper에 노출할 텍스트/노드
+   * @type {ReactNode}
+   */
+  text: ReactNode;
+  /**
+   * helper state (success/error 등)
+   * @type {AuthPasswordHelperStatus | undefined}
+   */
+  state?: AuthPasswordHelperStatus;
+}
+
+/**
+ * Password helper에서 사용하는 상태
+ */
+export type AuthPasswordHelperStatus = "error" | "complete";
+
+/**
+ * PasswordSetField 컴포넌트 props
+ * @typedef
+ */
+export interface AuthPasswordSetMessages {
+  /**
+   * 비밀번호 미입력 시 메시지
+   * @type {string | undefined}
+   */
+  missing?: string;
+  /**
+   * 비밀번호 불일치 메시지
+   * @type {string | undefined}
+   */
+  mismatch?: string;
+}
+
+export interface AuthPasswordSetFieldProps<
+  TValues extends FieldValues = Record<string, string>,
+> {
+  /**
+   * react-hook-form form 객체
+   * @type {UseFormReturn<TValues> | undefined}
+   */
+  form?: UseFormReturn<TValues>;
+  /**
+   * 비밀번호 입력 필드 설정
+   * @type {AuthPasswordFieldProps<InputPasswordProps>}
+   */
+  passwordField: AuthPasswordFieldProps<InputPasswordProps>;
+  /**
+   * 비밀번호 재확인 필드 설정
+   * @type {AuthPasswordFieldProps<InputPasswordProps>}
+   */
+  confirmPasswordField: AuthPasswordFieldProps<InputPasswordProps>;
+  /**
+   * 비밀번호 필드명(미지정 시 attr.name 또는 password)
+   * @type {FieldPath<TValues> | undefined}
+   */
+  passwordFieldName?: FieldPath<TValues>;
+  /**
+   * 재확인 필드명(미지정 시 attr.name 또는 confirmPassword)
+   * @type {FieldPath<TValues> | undefined}
+   */
+  confirmPasswordFieldName?: FieldPath<TValues>;
+  /**
+   * 비밀번호 규칙 목록
+   * @type {AuthPasswordRule[] | undefined}
+   */
+  passwordRules?: AuthPasswordRule[];
+  /**
+   * 검증 메시지 override
+   * @type {AuthPasswordSetMessages | undefined}
+   */
+  messages?: AuthPasswordSetMessages;
+}

package/src/auth/common/password/utils/composePasswordFieldProps.ts

@@ -0,0 +1,44 @@
+import type { InputProps } from "@uniai-fe/uds-primitives";
+import type { AuthPasswordFieldProps, AuthPasswordHelperState } from "../types";
+
+/**
+ * Password 전용 필드 구성; attr/props를 합쳐 helper/label/state를 통일한다.
+ * @util
+ * @param {AuthPasswordFieldProps<TProps>} config 입력 필드 설정값
+ * @param {AuthPasswordHelperState} [helper] 훅에서 계산한 helper 상태
+ * @returns {TProps} Input 컴포넌트에 그대로 전달할 props
+ */
+export const composePasswordFieldProps = <TProps extends InputProps>(
+  config: AuthPasswordFieldProps<TProps>,
+  helper?: AuthPasswordHelperState,
+): TProps => {
+  const baseProps = {
+    ...(config.attr ?? {}),
+    ...(config.props ?? ({} as TProps)),
+  } as TProps;
+  const mergedLabelProps = config.labelClassName
+    ? {
+        ...baseProps.labelProps,
+        className: config.labelClassName,
+      }
+    : baseProps.labelProps;
+  const mergedHelperProps = config.helperClassName
+    ? {
+        ...baseProps.helperProps,
+        className: config.helperClassName,
+      }
+    : baseProps.helperProps;
+
+  const helperDrivenState = helper?.state === "error" ? "error" : undefined;
+
+  return {
+    ...baseProps,
+    label: config.label ?? baseProps.label,
+    helper: helper?.text ?? config.helper ?? baseProps.helper,
+    state: helperDrivenState ?? baseProps.state,
+    block: config.block ?? baseProps.block ?? true,
+    className: config.className ?? baseProps.className,
+    labelProps: mergedLabelProps,
+    helperProps: mergedHelperProps,
+  };
+};

package/src/auth/find-account.ts

@@ -0,0 +1,28 @@
+import {
+  FindAccountInfoScreen,
+  FindAccountCodeScreen,
+  FindAccountIdComplete,
+  useFindAccountForm,
+} from "./find-id";
+import {
+  FindAccountPasswordForm,
+  FindAccountPasswordComplete,
+} from "./find-password";
+
+export type * from "./find-id/types";
+export { useFindAccountForm };
+export {
+  FindAccountInfoScreen,
+  FindAccountCodeScreen,
+  FindAccountIdComplete,
+  FindAccountPasswordForm,
+  FindAccountPasswordComplete,
+};
+
+export const FindAccount = {
+  Info: FindAccountInfoScreen,
+  Code: FindAccountCodeScreen,
+  IdComplete: FindAccountIdComplete,
+  PasswordForm: FindAccountPasswordForm,
+  PasswordComplete: FindAccountPasswordComplete,
+};

package/src/auth/find-id/hooks/index.ts

@@ -0,0 +1 @@
+export { useFindAccountForm } from "../../common/find/hooks/useFindAccountForm";

package/src/auth/find-id/index.scss

@@ -0,0 +1 @@
+@use "../common/find/styles/find-account.scss";

package/src/auth/find-id/index.ts

@@ -0,0 +1,23 @@
+import "./index.scss";
+import FindIdStepIdentify from "./markup/StepIdentify";
+import FindIdStepVerifyCode from "./markup/StepVerifyCode";
+import FindIdStepComplete from "./markup/StepComplete";
+
+export type * from "./types";
+export * from "./hooks";
+
+export const FindAccountInfoScreen = FindIdStepIdentify;
+export const FindAccountCodeScreen = FindIdStepVerifyCode;
+export const FindAccountIdComplete = FindIdStepComplete;
+
+export { FindIdStepIdentify, FindIdStepVerifyCode, FindIdStepComplete };
+
+export const FindId = {
+  StepIdentify: FindIdStepIdentify,
+  StepVerifyCode: FindIdStepVerifyCode,
+  StepComplete: FindIdStepComplete,
+  // Backwards compatibility
+  Info: FindAccountInfoScreen,
+  Code: FindAccountCodeScreen,
+  IdComplete: FindAccountIdComplete,
+};

package/src/auth/find-id/markup/StepComplete.tsx

@@ -0,0 +1,58 @@
+import clsx from "clsx";
+import type { FindAccountIdCompleteProps } from "../types";
+import AuthCompleteTemplate from "../../common/complete/Template";
+
+const DEFAULT_TITLE = "아이디 찾기 완료";
+const DEFAULT_ID_LABEL = "아이디";
+const DEFAULT_REGISTERED_LABEL = "가입일";
+const DEFAULT_DESCRIPTION = "입력하신 정보로 계정을 찾았어요.";
+const DEFAULT_CTA_LABEL = "로그인하기";
+
+/**
+ * 아이디 찾기 완료 화면
+ * @component
+ */
+export default function FindIdStepComplete({
+  className,
+  title,
+  summary,
+  description,
+  cta,
+}: FindAccountIdCompleteProps) {
+  return (
+    <AuthCompleteTemplate
+      className={clsx("auth-find-account-container", className)}
+      title={title ?? DEFAULT_TITLE}
+      description={description ?? DEFAULT_DESCRIPTION}
+      cta={{
+        label: cta?.label ?? DEFAULT_CTA_LABEL,
+        buttonProps: cta?.buttonProps,
+      }}
+    >
+      <section className="auth-find-account-id-summary">
+        <div className="auth-find-account-id-summary-card">
+          <dl className="auth-find-account-id-summary-row">
+            <dt className="auth-find-account-id-summary-text">
+              <span>{summary.userIdLabel ?? DEFAULT_ID_LABEL}</span>
+            </dt>
+            <dd className="auth-find-account-id-summary-text">
+              <span>{summary.userId}</span>
+            </dd>
+          </dl>
+          {summary.registeredAt ? (
+            <dl className="auth-find-account-id-summary-row">
+              <dt className="auth-find-account-id-summary-text">
+                <span>
+                  {summary.registeredAtLabel ?? DEFAULT_REGISTERED_LABEL}
+                </span>
+              </dt>
+              <dd className="auth-find-account-id-summary-text">
+                <span>{summary.registeredAt}</span>
+              </dd>
+            </dl>
+          ) : null}
+        </div>
+      </section>
+    </AuthCompleteTemplate>
+  );
+}

package/src/auth/find-id/markup/StepIdentify.tsx

@@ -0,0 +1,46 @@
+import type { ReactNode } from "react";
+import FindAccountInfoStep from "../../common/find/markup/InfoStep";
+import type { FindAccountInfoStepProps } from "../../common/find/types";
+
+const DEFAULT_NAVIGATION = {
+  title: "아이디 찾기",
+};
+
+const DEFAULT_HEADLINE = {
+  progress: { total: 2, current: 1 },
+  title: (
+    <>
+      가입한 이름과 메일 주소를
+      <br />
+      입력해 주세요
+    </>
+  ),
+};
+
+const DEFAULT_CTA_LABEL = "인증코드 요청";
+
+export type FindIdStepIdentifyProps = FindAccountInfoStepProps;
+
+/**
+ * Find ID Step1 — 이름/메일 입력
+ * @component
+ */
+export default function FindIdStepIdentify({
+  navigation,
+  headline,
+  cta,
+  ...rest
+}: FindIdStepIdentifyProps) {
+  const resolvedNavigation = navigation ?? DEFAULT_NAVIGATION;
+  const resolvedHeadline = headline ?? DEFAULT_HEADLINE;
+  const resolvedCTA = cta ?? { label: DEFAULT_CTA_LABEL as ReactNode };
+
+  return (
+    <FindAccountInfoStep
+      {...rest}
+      navigation={resolvedNavigation}
+      headline={resolvedHeadline}
+      cta={resolvedCTA}
+    />
+  );
+}

package/src/auth/find-id/markup/StepVerifyCode.tsx

@@ -0,0 +1,48 @@
+import FindAccountCodeStep from "../../common/find/markup/CodeStep";
+import type { FindAccountCodeStepProps } from "../../common/find/types";
+
+const DEFAULT_NAVIGATION = {
+  title: "아이디 찾기",
+};
+
+const DEFAULT_HEADLINE = {
+  progress: { total: 2, current: 2 },
+  title: (
+    <>
+      메일 주소로
+      <br />
+      인증을 진행해 주세요
+    </>
+  ),
+};
+
+const DEFAULT_EMAIL_LABEL = "메일";
+
+export type FindIdStepVerifyCodeProps = FindAccountCodeStepProps;
+
+/**
+ * Find ID Step2 — 인증코드 입력
+ * @component
+ */
+export default function FindIdStepVerifyCode({
+  navigation,
+  headline,
+  emailDisplay,
+  ...rest
+}: FindIdStepVerifyCodeProps) {
+  const resolvedNavigation = navigation ?? DEFAULT_NAVIGATION;
+  const resolvedHeadline = headline ?? DEFAULT_HEADLINE;
+  const resolvedEmailDisplay = {
+    label: DEFAULT_EMAIL_LABEL,
+    ...emailDisplay,
+  };
+
+  return (
+    <FindAccountCodeStep
+      {...rest}
+      navigation={resolvedNavigation}
+      headline={resolvedHeadline}
+      emailDisplay={resolvedEmailDisplay}
+    />
+  );
+}