@uniai-fe/uds-templates 0.0.8 → 0.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/uds-templates",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "description": "UNIAI Design System; UI Templates Package",
   "type": "module",
   "private": false,
@@ -12,7 +12,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "packageManager": "pnpm@10.25.0",
+  "packageManager": "pnpm@10.26.1",
   "engines": {
     "node": ">=24",
     "pnpm": ">=10"
@@ -51,15 +51,15 @@
     "@uniai-fe/uds-foundation": "^0.0.1",
     "@uniai-fe/uds-primitives": "^0.0.2",
     "react": ">= 19",
-    "react-dom": ">= 19"
+    "react-dom": ">= 19",
+    "react-hook-form": ">= 7",
+    "next": "^15"
   },
   "dependencies": {
     "clsx": "^2.1.1",
     "dayjs": "^1.11.19"
   },
   "devDependencies": {
-    "@uniai-fe/uds-foundation": "workspace:*",
-    "@uniai-fe/uds-primitives": "workspace:*",
     "@svgr/webpack": "^8.1.0",
     "@types/node": "^24.10.2",
     "@types/react": "^19.2.7",
@@ -67,10 +67,13 @@
     "@uniai-fe/eslint-config": "workspace:*",
     "@uniai-fe/next-devkit": "workspace:*",
     "@uniai-fe/tsconfig": "workspace:*",
-    "eslint": "^9.39.1",
+    "@uniai-fe/uds-foundation": "workspace:*",
+    "@uniai-fe/uds-primitives": "workspace:*",
+    "eslint": "^9.39.2",
+    "next": "^15.5.9",
     "prettier": "^3.7.4",
-    "sass": "^1.96.0",
     "react-hook-form": "^7.68.0",
+    "sass": "^1.97.0",
     "typescript": "~5.9.3"
   }
 }

package/src/components/auth/container/AuthContainer.tsx

@@ -0,0 +1,24 @@
+import clsx from "clsx";
+import type { AuthContainerProps } from "./types";
+
+/**
+ * 로그인/회원가입 화면을 감싸는 공용 컨테이너
+ * @component
+ */
+export function AuthContainer({
+  className,
+  header,
+  children,
+  footer,
+}: AuthContainerProps) {
+  // 단일 열 레이아웃을 강제해 모바일·PC 환경에서 동일한 시각적 구조를 보장한다.
+  return (
+    <section className={clsx("auth-container", className)}>
+      <div className="auth-container__inner">
+        {header && <header className="auth-container__header">{header}</header>}
+        <div className="auth-container__body">{children}</div>
+        {footer && <footer className="auth-container__footer">{footer}</footer>}
+      </div>
+    </section>
+  );
+}

package/src/components/auth/container/index.scss

@@ -0,0 +1,52 @@
+:root {
+  --auth-container-max-width: 335px;
+  --auth-container-gap: var(--spacing-padding-7, 28px);
+  --auth-container-padding-inline: var(--spacing-padding-6, 24px);
+  --auth-container-padding-top: calc(
+    var(--spacing-padding-9, 32px) + env(safe-area-inset-top, 0px)
+  );
+  --auth-container-padding-bottom: var(--spacing-padding-10, 40px);
+}
+
+.auth-container {
+  min-height: min(100svh, 100dvh);
+  padding: var(--auth-container-padding-top)
+    var(--auth-container-padding-inline)
+    calc(
+      var(--auth-container-padding-bottom) + env(safe-area-inset-bottom, 0px)
+    );
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  background-color: var(--color-common-100, #ffffff);
+  color: inherit;
+}
+
+.auth-container__inner {
+  width: min(100%, var(--auth-container-max-width, 335px));
+  display: flex;
+  flex-direction: column;
+  gap: var(--auth-container-gap);
+  margin-block: auto;
+}
+
+.auth-container__header {
+  width: 100%;
+}
+
+.auth-container__body {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-padding-6, 24px);
+}
+
+.auth-container__footer {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-padding-4, 16px);
+}
+
+.auth-container__footer {
+  margin-top: auto;
+}

package/src/components/auth/container/index.tsx

@@ -0,0 +1,4 @@
+import "./index.scss";
+
+export { AuthContainer } from "./AuthContainer";
+export type { AuthContainerProps } from "./types";

package/src/components/auth/container/types.ts

@@ -0,0 +1,8 @@
+import type { ReactNode } from "react";
+
+export type AuthContainerProps = {
+  className?: string;
+  header?: ReactNode;
+  children: ReactNode;
+  footer?: ReactNode;
+};

package/src/components/auth/index.tsx

@@ -0,0 +1,9 @@
+import "./login/index.scss";
+
+import { AuthContainer } from "./container";
+import { AuthLogin } from "./login";
+
+export const Auth = {
+  Container: AuthContainer,
+  Login: AuthLogin,
+};

package/src/components/auth/login/data/valid-options.ts

@@ -0,0 +1,8 @@
+export const authLoginValidOptions = {
+  id: {
+    required: "아이디를 입력해 주세요.",
+  },
+  password: {
+    required: "비밀번호를 입력해 주세요.",
+  },
+};

package/src/components/auth/login/hooks/index.ts

@@ -0,0 +1,6 @@
+export { useAuthLoginForm } from "./useAuthLoginForm";
+export type {
+  AuthLoginFormValues,
+  UseAuthLoginFormOptions,
+  UseAuthLoginFormReturn,
+} from "../types/hooks";

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

@@ -0,0 +1,80 @@
+import { useMemo } from "react";
+import { useWatch } from "react-hook-form";
+import type { ReactNode } from "react";
+import type {
+  AuthLoginFields,
+  AuthLoginFormValues,
+  UseAuthLoginFormOptions,
+  UseAuthLoginFormReturn,
+} from "../types";
+
+/**
+ * 로그인 폼 훅
+ * @hook
+ * @template TFields
+ * @param {UseAuthLoginFormOptions<TFields>} options 훅 옵션
+ * @desc
+ * - 1) form init → 2) register merge → 3) helper/state → 4) submit 순서
+ */
+export function useAuthLoginForm<
+  TFields extends AuthLoginFields = AuthLoginFields,
+>({
+  fields,
+  form,
+  onLogin,
+}: UseAuthLoginFormOptions<TFields>): UseAuthLoginFormReturn<TFields> {
+  /** 1) form init — useForm은 FormField에서 생성 후 주입된다. */
+  const values = useWatch({
+    control: form.control,
+  }) as AuthLoginFormValues | undefined;
+
+  /** 2) register merge — 필드별 register 함수를 생성한다. */
+  const register = useMemo(() => {
+    return (Object.keys(fields) as Array<keyof TFields>).reduce(
+      (acc, fieldKey) => {
+        const config = fields[fieldKey];
+        const fieldName = config.attr?.name ?? String(fieldKey);
+        acc[fieldKey] = form.register(fieldName);
+        return acc;
+      },
+      {} as UseAuthLoginFormReturn<TFields>["register"],
+    );
+  }, [fields, form]);
+
+  /** 3) helper/state — helper 메시지와 버튼 상태를 계산한다. */
+  const helpers = useMemo(() => {
+    return (Object.keys(fields) as Array<keyof TFields>).reduce(
+      (acc, fieldKey) => {
+        const config = fields[fieldKey];
+        const fieldName = config.attr?.name ?? String(fieldKey);
+        const state = form.getFieldState(fieldName);
+        const helperText =
+          (state.error?.message as ReactNode | undefined) ?? config.helper;
+        acc[fieldKey] = {
+          text: helperText,
+          state: state.invalid ? "error" : undefined,
+        };
+        return acc;
+      },
+      {} as UseAuthLoginFormReturn<TFields>["helpers"],
+    );
+  }, [fields, form]);
+
+  const trimmedFilled =
+    values &&
+    Object.values(values).every(value =>
+      typeof value === "string" ? value.trim().length > 0 : false,
+    );
+
+  const disabled = form.formState.isSubmitting || !trimmedFilled;
+
+  /** 4) submit — onLogin을 handleSubmit과 결합한다. */
+  const onSubmit = form.handleSubmit(onLogin);
+
+  return {
+    register,
+    onSubmit,
+    disabled,
+    helpers,
+  };
+}

package/src/components/auth/login/index.scss

@@ -0,0 +1 @@
+@use "./styles/login.scss";

package/src/components/auth/login/index.tsx

@@ -0,0 +1,12 @@
+import "./index.scss";
+
+export type { AuthLoginProps as AuthLoginTemplateProps } from "./types";
+export * from "./hooks";
+
+import AuthLoginContainer from "./markup/Container";
+import AuthLoginFormField from "./markup/FormField";
+
+export const AuthLogin = {
+  Container: AuthLoginContainer,
+  FormField: AuthLoginFormField,
+};

package/src/components/auth/login/markup/Container.tsx

@@ -0,0 +1,34 @@
+import clsx from "clsx";
+import { AuthContainer } from "../../container";
+import AuthLoginFormField from "./FormField";
+import AuthLoginLinkButtons from "./LinkButtons";
+import type { AuthLoginProps } from "../types";
+
+/**
+ * 로그인 화면 템플릿 — AuthContainer 위에 아이디/비밀번호 입력과 CTA를 배치한다.
+ * @component
+ */
+export default function AuthLoginContainer({
+  className,
+  header,
+  footer,
+  linkOptions,
+  fieldOptions,
+}: AuthLoginProps) {
+  return (
+    <>
+      <AuthContainer
+        className={clsx("auth-login-container", className)}
+        header={header}
+        footer={footer}
+      >
+        <AuthLoginFormField {...fieldOptions} />
+        <AuthLoginLinkButtons
+          hrefFindId={linkOptions.find.id}
+          hrefFindPassword={linkOptions.find.password}
+          hrefSignup={linkOptions.signup}
+        />
+      </AuthContainer>
+    </>
+  );
+}

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

@@ -0,0 +1,115 @@
+import { useMemo } from "react";
+import type { ReactNode } from "react";
+import {
+  Button,
+  Input,
+  PasswordInput,
+  type InputPasswordProps,
+  type InputProps,
+  type InputState,
+} from "@uniai-fe/uds-primitives";
+import type {
+  AuthLoginFieldConfig,
+  AuthLoginFieldOptions,
+  AuthLoginFields,
+  AuthLoginFormValues,
+} from "../types";
+import { useAuthLoginForm } from "../hooks";
+import { useForm } from "react-hook-form";
+
+type HelperState = {
+  /**
+   * helper 텍스트
+   */
+  text?: ReactNode;
+  /**
+   * helper 상태
+   */
+  state?: InputState;
+};
+
+const composeFieldProps = <TProps extends InputProps>(
+  config: AuthLoginFieldConfig<TProps>,
+  helper?: HelperState,
+): 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;
+
+  return {
+    ...baseProps,
+    label: config.label ?? baseProps.label,
+    helper: helper?.text ?? config.helper ?? baseProps.helper,
+    state: helper?.state ?? baseProps.state,
+    block: config.block ?? baseProps.block ?? true,
+    className: config.className ?? baseProps.className,
+    labelProps: mergedLabelProps,
+    helperProps: mergedHelperProps,
+  };
+};
+
+export default function AuthLoginFormField<
+  TFields extends AuthLoginFields = AuthLoginFields,
+>({ fields, formAttr, onLogin }: AuthLoginFieldOptions<TFields>) {
+  const defaultValues = useMemo(
+    () =>
+      (Object.keys(fields) as Array<keyof TFields>).reduce((acc, fieldKey) => {
+        const config = fields[fieldKey];
+        const fieldName = config.attr?.name ?? String(fieldKey);
+        acc[fieldName] = "";
+        return acc;
+      }, {} as AuthLoginFormValues),
+    [fields],
+  );
+
+  const form = useForm<AuthLoginFormValues>({
+    mode: "onChange",
+    defaultValues,
+  });
+
+  const { register, helpers, onSubmit, disabled } = useAuthLoginForm<TFields>({
+    fields,
+    form,
+    onLogin,
+  });
+
+  return (
+    <form className="auth-login-form" {...formAttr} onSubmit={onSubmit}>
+      <div className="auth-login-fields">
+        <Input
+          {...composeFieldProps<InputProps>(fields.id, helpers.id)}
+          register={register.id}
+        />
+        <PasswordInput
+          {...composeFieldProps<InputPasswordProps>(
+            fields.password,
+            helpers.password,
+          )}
+          register={register.password}
+        />
+        <Button.Default
+          type="submit"
+          scale="solid-xlarge"
+          priority="primary"
+          block
+          disabled={disabled}
+        >
+          로그인
+        </Button.Default>
+      </div>
+    </form>
+  );
+}

package/src/components/auth/login/markup/LinkButtons.tsx

@@ -0,0 +1,40 @@
+import Link from "next/link";
+import { Button, Divider } from "@uniai-fe/uds-primitives";
+
+export default function AuthLoginLinkButtons({
+  hrefFindId,
+  hrefFindPassword,
+  hrefSignup,
+}: {
+  hrefFindId: string;
+  hrefFindPassword: string;
+  hrefSignup: string;
+}) {
+  return (
+    <div className="auth-login-util-container">
+      <div className="auth-login-find-account">
+        <Link href={hrefFindId} className="auth-login-find-account-button">
+          <span>아이디 찾기</span>
+        </Link>
+        <Divider />
+        <Link
+          href={hrefFindPassword}
+          className="auth-login-find-account-button"
+        >
+          <span>비밀번호 찾기</span>
+        </Link>
+      </div>
+      <div className="auth-login-signup">
+        <Button.Rounded
+          as={Link}
+          href={hrefSignup}
+          className="auth-login-signup-button"
+          priority="tertiary"
+          size="small"
+        >
+          회원가입
+        </Button.Rounded>
+      </div>
+    </div>
+  );
+}

package/src/components/auth/login/styles/login.scss

@@ -0,0 +1,52 @@
+.auth-login-form {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-padding-7, 28px);
+  margin-top: var(--spacing-padding-10, 40px);
+}
+
+.auth-login-fields {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-padding-5, 20px);
+}
+
+.auth-login-util-container {
+  margin-top: 80px;
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-padding-6, 24px);
+}
+
+.auth-login-find-account {
+  display: flex;
+  justify-content: center;
+  align-items: center;
+
+  --divider-height: 13px;
+  --divider-color: var(--color-label-neutral);
+}
+
+.auth-login-find-account-button {
+  color: var(--color-label-standard);
+  font-size: 13px;
+  line-height: 1em;
+  font-weight: 400;
+  padding-inline: var(--spacing-padding-1, 4px);
+
+  &:hover {
+    color: var(--color-primary-50, #2563eb);
+  }
+}
+
+.auth-login-signup {
+  display: flex;
+  justify-content: center;
+}
+
+.auth-login-signup-button {
+  text-decoration: none;
+  min-width: 160px;
+  justify-content: center;
+  --theme-button-font-label-medium-size: var(--font-caption-medium-size);
+}

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

@@ -0,0 +1,82 @@
+import type {
+  SubmitHandler,
+  UseFormRegisterReturn,
+  UseFormReturn,
+} from "react-hook-form";
+import type { ReactNode } from "react";
+import type { AuthLoginFields } from "./props";
+import type { InputState } from "@uniai-fe/uds-primitives";
+
+/**
+ * 로그인 폼 값 타입
+ * @typedef {AuthLoginFormValues}
+ * @desc
+ * - 모든 로그인 필드 입력값을 문자열 레코드로 취급한다.
+ */
+export type AuthLoginFormValues = Record<string, string>;
+
+/**
+ * 로그인 훅 옵션; useAuthLoginForm 설정
+ * @typedef {UseAuthLoginFormOptions}
+ * @desc
+ * - 필드 정의, useForm 반환 객체, 로그인 핸들러를 전달한다.
+ * - 필드 타입은 제네릭으로 확장 가능하다.
+ * @property {AuthLoginFields<TFields>} fields 로그인 입력 필드 설정
+ * @property {UseFormReturn<Record<string, string>>} form RHF useForm 반환 객체
+ * @property {SubmitHandler<Record<string, string>>} onLogin 제출 콜백
+ */
+export type UseAuthLoginFormOptions<
+  TFields extends AuthLoginFields = AuthLoginFields,
+> = {
+  /**
+   * 로그인 필드 설정
+   * - 필수 id/password + 확장 필드를 포함한다.
+   */
+  fields: TFields;
+  /**
+   * RHF useForm 반환 객체
+   * - register/onSubmit 등을 전달한다.
+   */
+  form: UseFormReturn<AuthLoginFormValues>;
+  /**
+   * 로그인 제출 핸들러
+   * - form.handleSubmit으로 감싼 뒤 동작한다.
+   */
+  onLogin: SubmitHandler<AuthLoginFormValues>;
+};
+
+/**
+ * 로그인 훅 반환타입; useAuthLoginForm 결과
+ * @typedef {UseAuthLoginFormReturn}
+ * @desc
+ * - register/onSubmit/disabled/helpers 네 축만 노출한다.
+ * - 필드는 제네릭 기반으로 key를 유지한다.
+ * @property {Record<keyof TFields, UseFormRegisterReturn>} register 필드별 register 함수
+ * @property {ReturnType<UseFormReturn["handleSubmit"]>} onSubmit 로그인 제출 핸들러
+ * @property {boolean} disabled 버튼 disabled 여부
+ * @property {Record<keyof TFields, { text?: string; state?: string }>} helpers 필드별 helper 상태
+ */
+export type UseAuthLoginFormReturn<
+  TFields extends AuthLoginFields = AuthLoginFields,
+> = {
+  /**
+   * 필드별 register 함수
+   * - id/password 및 확장 필드를 동일 구조로 제공한다.
+   */
+  register: Record<keyof TFields, UseFormRegisterReturn>;
+  /**
+   * 로그인 제출 핸들러
+   * - form.handleSubmit 결과를 그대로 노출한다.
+   */
+  onSubmit: ReturnType<UseFormReturn["handleSubmit"]>;
+  /**
+   * 버튼 disabled 여부
+   * - trim 여부, isSubmitting 등 내부 로직으로 계산한다.
+   */
+  disabled: boolean;
+  /**
+   * 필드별 helper 상태
+   * - text/state 조합으로 error/info 메시지를 표현한다.
+   */
+  helpers: Record<keyof TFields, { text?: ReactNode; state?: InputState }>;
+};

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

@@ -0,0 +1,95 @@
+import React from "react";
+import type { SubmitHandler } from "react-hook-form";
+import type { AuthContainerProps } from "../../container";
+import type {
+  InputFieldConfig,
+  InputPasswordProps,
+  InputProps,
+} from "@uniai-fe/uds-primitives";
+
+/**
+ * 로그인 입력 필드 설정
+ * @typedef {AuthLoginFieldConfig}
+ * @template TProps
+ * @desc
+ * - InputFieldConfig 제네릭을 래핑해 로그인 요구사항과 연결한다.
+ * - props 제네릭으로 Input/PasswordInput 등 세부 props를 주입한다.
+ */
+export type AuthLoginFieldConfig<TProps extends InputProps = InputProps> =
+  InputFieldConfig<TProps>;
+
+/**
+ * 로그인 필드 묶음
+ * @template TAdditional
+ * @desc
+ * - 필수 id/password 필드와 확장 필드를 포함한다.
+ * @property {AuthLoginFieldConfig} id 아이디 필드 설정
+ * @property {AuthLoginFieldConfig} password 비밀번호 필드 설정
+ */
+export type AuthLoginFields<
+  TAdditional extends Record<string, AuthLoginFieldConfig> = Record<
+    string,
+    AuthLoginFieldConfig
+  >,
+> = TAdditional & {
+  /**
+   * 아이디 필드 설정
+   */
+  id: AuthLoginFieldConfig<InputProps>;
+  /**
+   * 비밀번호 필드 설정
+   */
+  password: AuthLoginFieldConfig<InputPasswordProps>;
+};
+
+/**
+ * 로그인 필드 옵션
+ * @template TFields
+ * @desc
+ * - fields, formAttr, onLogin을 묶어 전달한다.
+ * @property {TFields} fields 로그인 입력 필드 설정
+ * @property {React.FormHTMLAttributes<HTMLFormElement>} [formAttr] form 요소 attr
+ * @property {SubmitHandler<Record<string, string>>} onLogin 로그인 제출 핸들러
+ */
+export type AuthLoginFieldOptions<
+  TFields extends AuthLoginFields = AuthLoginFields,
+> = {
+  /** 로그인 필드 설정 */
+  fields: TFields;
+  /** form 요소에 전달할 attr */
+  formAttr?: React.FormHTMLAttributes<HTMLFormElement>;
+  /** 로그인 제출 핸들러 */
+  onLogin: SubmitHandler<Record<string, string>>;
+};
+
+/**
+ * 로그인 화면 링크 옵션
+ * @typedef {Object} AuthLoginLinkOptions
+ * @desc
+ * - 아이디/비밀번호 찾기, 회원가입 링크를 전달한다.
+ * @property {Object} find 아이디/비밀번호 찾기 링크
+ * @property {string} find.id 아이디 찾기 링크
+ * @property {string} find.password 비밀번호 찾기 링크
+ * @property {string} signup 회원가입 링크
+ */
+export type AuthLoginLinkOptions = {
+  find: {
+    id: string;
+    password: string;
+  };
+  signup: string;
+};
+
+/**
+ * 로그인 템플릿 props
+ * @template TFields
+ * @desc
+ * - AuthContainer props와 fieldOptions/linkOptions를 조합한다.
+ * @property {AuthLoginFieldOptions<TFields>} fieldOptions 입력 필드/폼 옵션
+ * @property {AuthLoginLinkOptions} linkOptions 링크 옵션
+ */
+export type AuthLoginProps<TFields extends AuthLoginFields = AuthLoginFields> =
+  Omit<AuthContainerProps, "children"> & {
+    fieldOptions: AuthLoginFieldOptions<TFields>;
+    linkOptions: AuthLoginLinkOptions;
+  };