@uniai-fe/uds-templates 0.0.10 → 0.0.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/uds-templates",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "description": "UNIAI Design System; UI Templates Package",
   "type": "module",
   "private": false,
@@ -12,7 +12,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "packageManager": "pnpm@10.26.1",
+  "packageManager": "pnpm@10.26.2",
   "engines": {
     "node": ">=24",
     "pnpm": ">=10"
@@ -53,7 +53,8 @@
     "react": ">= 19",
     "react-dom": ">= 19",
     "react-hook-form": ">= 7",
-    "next": "^15"
+    "next": "^15",
+    "jotai": ">= 2"
   },
   "dependencies": {
     "clsx": "^2.1.1",
@@ -73,6 +74,7 @@
     "next": "^15.5.9",
     "prettier": "^3.7.4",
     "react-hook-form": "^7.69.0",
+    "jotai": "^2.16.1",
     "sass": "^1.97.1",
     "typescript": "~5.9.3"
   }

package/src/auth/common/complete/Template.tsx

@@ -0,0 +1,47 @@
+"use client";
+
+import "./index.scss";
+
+import clsx from "clsx";
+import { Button } from "@uniai-fe/uds-primitives";
+import { AuthContainer } from "../container";
+import CircleCheckCompleteIcon from "./img/circle-check-complete.svg";
+import type { AuthCompleteTemplateProps } from "./types";
+
+export default function AuthCompleteTemplate({
+  className,
+  title,
+  description,
+  children,
+  cta,
+}: AuthCompleteTemplateProps) {
+  const confirmButtonProps = {
+    type: "button" as const,
+    block: true,
+    ...cta?.buttonProps,
+  };
+
+  return (
+    <AuthContainer
+      className={clsx("auth-complete-container", className)}
+      footer={
+        <Button.Default {...confirmButtonProps}>
+          {cta?.label ?? "확인"}
+        </Button.Default>
+      }
+    >
+      <div className="auth-complete-wrapper">
+        <figure className="auth-complete-icon" aria-hidden="true">
+          <CircleCheckCompleteIcon />
+        </figure>
+        <h2 className="auth-complete-title">{title}</h2>
+        {description ? (
+          <p className="auth-complete-description">{description}</p>
+        ) : null}
+        {children ? (
+          <div className="auth-complete-contents">{children}</div>
+        ) : null}
+      </div>
+    </AuthContainer>
+  );
+}

package/src/auth/common/complete/img/circle-check-complete.svg

@@ -0,0 +1,4 @@
+<svg width="60" height="60" viewBox="0 0 60 60" fill="none" xmlns="http://www.w3.org/2000/svg">
+<circle cx="30" cy="30" r="25" fill="#1A6AFF"/>
+<path d="M21 30.3137L27.364 36.6777L38.6777 25.364" stroke="white" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/src/auth/common/complete/index.scss

@@ -0,0 +1,38 @@
+.auth-complete-container {
+  width: 100%;
+}
+
+.auth-complete-wrapper {
+  text-align: center;
+}
+
+.auth-complete-icon {
+  width: 60px;
+  height: 60px;
+  margin: 0 auto 12px;
+}
+
+.auth-complete-icon svg {
+  width: 100%;
+  height: 100%;
+  display: block;
+}
+
+.auth-complete-title {
+  font-size: var(--font-heading-medium-size, 24px);
+  font-weight: var(--font-heading-medium-weight, 600);
+  color: var(--color-cool-gray-20);
+  line-height: var(--font-heading-medium-line-height, 1.4em);
+}
+
+.auth-complete-description {
+  margin-top: 4px;
+  font-size: var(--font-caption-large-size, 12px);
+  color: var(--color-label-standard);
+  line-height: var(--font-caption-large-line-height, 1.5em);
+}
+
+.auth-complete-contents {
+  width: 100%;
+  margin-top: var(--spacing-padding-4, 16px);
+}

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

@@ -0,0 +1,15 @@
+import type { ReactNode } from "react";
+import type { ButtonProps } from "@uniai-fe/uds-primitives";
+
+export type AuthCompleteCTA = {
+  label: ReactNode;
+  buttonProps?: Omit<ButtonProps, "children">;
+};
+
+export type AuthCompleteTemplateProps = {
+  className?: string;
+  title: ReactNode;
+  description?: ReactNode;
+  children?: ReactNode;
+  cta?: AuthCompleteCTA;
+};

package/src/auth/common/container/header/StageHeader.tsx

@@ -0,0 +1,61 @@
+import clsx from "clsx";
+import type { ReactNode } from "react";
+import { PaginationCarousel } from "@uniai-fe/uds-primitives";
+import { PageFrameMobileHeader } from "../../../../page-frame/mobile/header";
+
+import "./stage-header.scss";
+
+export interface StageHeaderIndicatorProps {
+  total: number;
+  current: number;
+}
+
+export interface StageHeaderProps {
+  className?: string;
+  navigationTitle: ReactNode;
+  headline: ReactNode;
+  description?: ReactNode;
+  backIcon?: ReactNode;
+  onBack?: () => void;
+  indicator?: StageHeaderIndicatorProps;
+}
+
+/**
+ * Page Frame용 optional header 컴포넌트; 모바일 서비스 공통 헤더 패턴을 제공한다.
+ * @component
+ */
+export function AuthStageHeader({
+  className,
+  navigationTitle,
+  headline,
+  description,
+  backIcon,
+  onBack,
+  indicator,
+}: StageHeaderProps) {
+  return (
+    <div className={clsx("auth-stage-header", className)}>
+      <PageFrameMobileHeader
+        title={navigationTitle}
+        backIcon={backIcon}
+        onBack={onBack}
+      />
+      {indicator ? (
+        <div className="auth-stage-step">
+          <PaginationCarousel
+            className="auth-stage-step-pagination"
+            aria-label="진행 단계"
+            total={indicator.total}
+            current={indicator.current}
+          />
+        </div>
+      ) : null}
+      <div className="auth-stage-headline">
+        <p className="auth-stage-headline-text">{headline}</p>
+        {description ? (
+          <p className="auth-stage-headline-description">{description}</p>
+        ) : null}
+      </div>
+    </div>
+  );
+}

package/src/auth/common/container/header/index.tsx

@@ -0,0 +1,5 @@
+export { AuthStageHeader } from "./StageHeader";
+export type {
+  StageHeaderProps,
+  StageHeaderIndicatorProps,
+} from "./StageHeader";

package/src/auth/common/container/header/stage-header.scss

@@ -0,0 +1,50 @@
+.auth-stage-header {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-padding-5, 20px);
+  padding: 0 var(--spacing-padding-1, 4px);
+}
+
+.auth-stage-step {
+  display: flex;
+  justify-content: flex-start;
+}
+
+.auth-stage-step-pagination {
+  --pagination-carousel-gap: 6px;
+}
+
+.auth-stage-headline {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-padding-1, 4px);
+}
+
+.auth-stage-headline-text {
+  margin: 0;
+  font-size: 24px;
+  font-weight: 600;
+  line-height: 1.4;
+  letter-spacing: 0.2px;
+  color: var(--color-label-standard);
+  font-family:
+    "Pretendard JP Variable",
+    "Pretendard",
+    system-ui,
+    -apple-system,
+    BlinkMacSystemFont,
+    sans-serif;
+}
+
+.auth-stage-headline-description {
+  margin: 0;
+  font-size: 14px;
+  line-height: 1.4;
+  color: var(--color-label-assistive);
+  font-family:
+    "Pretendard",
+    system-ui,
+    -apple-system,
+    BlinkMacSystemFont,
+    sans-serif;
+}

package/src/{components/auth → auth/common}/container/index.tsx

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

package/src/auth/common/find/hooks/useFindAccountForm.ts

@@ -0,0 +1,79 @@
+import { useMemo } from "react";
+import { useWatch, type Path } from "react-hook-form";
+import type React from "react";
+import type { InputFieldProps } from "@uniai-fe/uds-primitives";
+import type {
+  UseFindAccountFormOptions,
+  UseFindAccountFormReturn,
+} from "../types";
+
+/**
+ * Find Account 단계 공통 RHF 훅.
+ * @hook
+ */
+export function useFindAccountForm<
+  TFields extends Record<string, InputFieldProps>,
+  TValues extends Record<string, unknown>,
+>({
+  fields,
+  form,
+  onSubmit,
+  isSubmittable,
+}: UseFindAccountFormOptions<TFields, TValues>): UseFindAccountFormReturn<
+  TFields,
+  TValues
+> {
+  const values = useWatch({
+    control: form.control,
+  }) as TValues | undefined;
+
+  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)) as Path<TValues>;
+        acc[fieldKey] = form.register(fieldName);
+        return acc;
+      },
+      {} as UseFindAccountFormReturn<TFields, TValues>["register"],
+    );
+  }, [fields, form]);
+
+  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)) as Path<TValues>;
+        const state = form.getFieldState(fieldName);
+        acc[fieldKey] = {
+          text: state.error?.message ?? config.helper,
+          state: state.invalid ? "error" : undefined,
+        };
+        return acc;
+      },
+      {} as UseFindAccountFormReturn<TFields, TValues>["helpers"],
+    );
+  }, [fields, form]);
+
+  const defaultFilled =
+    values &&
+    Object.values(values).every(value =>
+      typeof value === "string" ? value.trim().length > 0 : Boolean(value),
+    );
+  const resolvedFilled = isSubmittable
+    ? isSubmittable(values)
+    : Boolean(defaultFilled);
+  const disabled = form.formState.isSubmitting || !resolvedFilled;
+
+  const handleSubmit: React.FormEventHandler<HTMLFormElement> =
+    form.handleSubmit(onSubmit);
+
+  return {
+    register,
+    helpers,
+    disabled,
+    onSubmit: handleSubmit,
+  };
+}

package/src/auth/common/find/markup/CodeStep.tsx

@@ -0,0 +1,166 @@
+import clsx from "clsx";
+import { useMemo } from "react";
+import type { MouseEvent } from "react";
+import { useForm, useWatch } from "react-hook-form";
+import { AuthContainer } from "../../container";
+import { Button, EmailInput } from "@uniai-fe/uds-primitives";
+import type { ButtonProps } from "@uniai-fe/uds-primitives";
+import type { FindAccountCodeStepProps, FindAccountCodeValues } from "../types";
+import FindAccountHeader from "./Header";
+
+const DEFAULT_RESEND_LABEL = "인증코드 재요청";
+const DEFAULT_EXTEND_LABEL = "시간연장";
+const DEFAULT_CODE_LABEL = "인증코드 입력";
+const DEFAULT_EMAIL_LABEL = "메일";
+const DEFAULT_SUBMIT_LABEL = "완료";
+const DEFAULT_CODE_LENGTH = 6;
+type ButtonComponentEvent = Parameters<NonNullable<ButtonProps["onClick"]>>[0];
+type UtilityClickEvent =
+  | MouseEvent<HTMLButtonElement>
+  | MouseEvent<HTMLAnchorElement>;
+
+/**
+ * 인증코드 입력 Step
+ * @component
+ */
+export function FindAccountCodeStep({
+  className,
+  header,
+  footer,
+  emailDisplay,
+  timer,
+  fieldOptions,
+  cta,
+  navigation,
+  headline,
+}: FindAccountCodeStepProps) {
+  const { fields, formAttr, onSubmit, isSubmittable } = fieldOptions;
+  const codeFieldName = fields.code.attr?.name ?? "code";
+  const resolvedCodeLength = fields.code.length ?? DEFAULT_CODE_LENGTH;
+
+  const defaultValues = useMemo(
+    () =>
+      ({
+        [codeFieldName]: "",
+      }) as FindAccountCodeValues,
+    [codeFieldName],
+  );
+
+  const form = useForm<FindAccountCodeValues>({
+    mode: "onChange",
+    defaultValues,
+  });
+
+  const values = useWatch({
+    control: form.control,
+  }) as FindAccountCodeValues | undefined;
+
+  const submitButtonProps = {
+    type: "submit" as const,
+    scale: "solid-xlarge" as const,
+    priority: "primary" as const,
+    block: true,
+    ...cta?.buttonProps,
+  };
+  const resolvedEmailValue = String(emailDisplay.value ?? "");
+  const codeInputProps = {
+    ...(fields.code.props ?? {}),
+    register: form.register(codeFieldName),
+  };
+  const countdownActionLabel = timer?.extend
+    ? (timer.extend.label ?? DEFAULT_EXTEND_LABEL)
+    : undefined;
+  const countdownActionHandler = timer?.extend?.buttonProps?.onClick;
+  const countdownActionDisabled = timer?.extend?.buttonProps?.disabled;
+  const resendButtonLabel = emailDisplay.resend?.label ?? DEFAULT_RESEND_LABEL;
+  const resendButtonHandler = emailDisplay.resend?.buttonProps?.onClick;
+  const resendButtonDisabled = emailDisplay.resend?.buttonProps?.disabled;
+  const handleResendButtonClick = (event?: UtilityClickEvent) => {
+    if (!resendButtonHandler || !event) {
+      return;
+    }
+    resendButtonHandler(event as ButtonComponentEvent);
+  };
+  const handleCountdownActionClick = (event?: UtilityClickEvent) => {
+    if (!countdownActionHandler || !event) {
+      return;
+    }
+    countdownActionHandler(event as ButtonComponentEvent);
+  };
+
+  const resolvedHeader =
+    header ??
+    (navigation || headline ? (
+      <FindAccountHeader navigation={navigation} headline={headline} />
+    ) : undefined);
+
+  const resolvedValues = values ?? form.getValues();
+  const codeValue =
+    resolvedValues && typeof resolvedValues[codeFieldName] === "string"
+      ? resolvedValues[codeFieldName]
+      : "";
+  const normalizedCodeValue = codeValue.replace(/\D/g, "");
+  const defaultFilled = normalizedCodeValue.length === resolvedCodeLength;
+  const resolvedFilled = isSubmittable
+    ? isSubmittable(resolvedValues)
+    : defaultFilled;
+  const disabled = form.formState.isSubmitting || !resolvedFilled;
+
+  const fieldState = form.getFieldState(codeFieldName);
+  const codeHelper = fieldState.error?.message ?? fields.code.helper;
+  const codeState = fieldState.invalid ? "error" : undefined;
+
+  const handleSubmit = form.handleSubmit(onSubmit);
+
+  return (
+    <AuthContainer
+      className={clsx("auth-find-account-container", className)}
+      header={resolvedHeader}
+      footer={footer}
+    >
+      <form
+        className="auth-find-account-form auth-find-account-form--code"
+        {...formAttr}
+        onSubmit={handleSubmit}
+      >
+        <div className="auth-find-account-fields">
+          <EmailInput
+            priority="secondary"
+            label={emailDisplay.label ?? DEFAULT_EMAIL_LABEL}
+            value={resolvedEmailValue}
+            readOnly
+            helper={emailDisplay.helper}
+            onRequestCode={
+              resendButtonHandler ? handleResendButtonClick : undefined
+            }
+            requestButtonLabel={resendButtonLabel}
+            requestButtonDisabled={resendButtonDisabled}
+            codeVisible
+            codeLength={resolvedCodeLength}
+            codeLabel={fields.code.label ?? DEFAULT_CODE_LABEL}
+            codeHelper={codeHelper}
+            codeState={codeState}
+            countdownText={timer?.text}
+            countdownActionLabel={countdownActionLabel}
+            onCountdownAction={
+              countdownActionHandler ? handleCountdownActionClick : undefined
+            }
+            countdownActionDisabled={countdownActionDisabled}
+            codeInputProps={codeInputProps}
+          />
+        </div>
+        {timer?.helper ? (
+          <p className="auth-find-account-timer-helper">{timer.helper}</p>
+        ) : null}
+        <Button.Default
+          {...submitButtonProps}
+          disabled={cta?.buttonProps?.disabled ?? disabled}
+        >
+          {cta?.label ?? DEFAULT_SUBMIT_LABEL}
+        </Button.Default>
+      </form>
+    </AuthContainer>
+  );
+}
+
+export default FindAccountCodeStep;

package/src/auth/common/find/markup/Header.tsx

@@ -0,0 +1,46 @@
+import { AuthStageHeader } from "../../container/header";
+import type {
+  FindAccountHeadlineProps,
+  FindAccountNavigationProps,
+} from "../types";
+
+type FindAccountHeaderProps = {
+  navigation?: FindAccountNavigationProps;
+  headline?: FindAccountHeadlineProps;
+  className?: string;
+};
+
+/**
+ * Find Account 공통 헤더
+ * @component
+ */
+export function FindAccountHeader({
+  navigation,
+  headline,
+  className,
+}: FindAccountHeaderProps) {
+  if (!navigation && !headline) {
+    return null;
+  }
+
+  return (
+    <AuthStageHeader
+      className={className}
+      navigationTitle={navigation?.title ?? ""}
+      backIcon={navigation?.backIcon}
+      onBack={navigation?.onBack}
+      headline={headline?.title ?? null}
+      description={headline?.description}
+      indicator={
+        headline?.progress
+          ? {
+              total: headline.progress.total,
+              current: headline.progress.current,
+            }
+          : undefined
+      }
+    />
+  );
+}
+
+export default FindAccountHeader;

package/src/auth/common/find/markup/InfoStep.tsx

@@ -0,0 +1,109 @@
+import clsx from "clsx";
+import { useMemo } from "react";
+import { useForm } from "react-hook-form";
+import { AuthContainer } from "../../container";
+import { Button, Input, type InputProps } from "@uniai-fe/uds-primitives";
+import type { FindAccountInfoStepProps, FindAccountInfoValues } from "../types";
+import { useFindAccountForm } from "../hooks/useFindAccountForm";
+import { composeFindAccountFieldProps } from "../utils/composeFieldProps";
+import FindAccountHeader from "./Header";
+
+const DEFAULT_CTA_LABEL = "인증코드 요청";
+
+/**
+ * 이름/메일 입력 Step
+ * @component
+ */
+export function FindAccountInfoStep({
+  className,
+  header,
+  footer,
+  fieldOptions,
+  cta,
+  navigation,
+  headline,
+}: FindAccountInfoStepProps) {
+  const { fields, formAttr, onSubmit, isSubmittable } = fieldOptions;
+
+  const defaultValues = useMemo(
+    () =>
+      (Object.keys(fields) as Array<keyof typeof fields>).reduce(
+        (acc, fieldKey) => {
+          const config = fields[fieldKey];
+          const fieldName = config.attr?.name ?? String(fieldKey);
+          acc[fieldName] = "";
+          return acc;
+        },
+        {} as FindAccountInfoValues,
+      ),
+    [fields],
+  );
+
+  const form = useForm<FindAccountInfoValues>({
+    mode: "onChange",
+    defaultValues,
+  });
+
+  const {
+    register,
+    helpers,
+    disabled,
+    onSubmit: handleSubmit,
+  } = useFindAccountForm({
+    fields,
+    form,
+    onSubmit,
+    isSubmittable,
+  });
+
+  const buttonProps = {
+    type: "submit" as const,
+    scale: "solid-xlarge" as const,
+    priority: "primary" as const,
+    block: true,
+    ...cta?.buttonProps,
+    disabled: cta?.buttonProps?.disabled ?? disabled,
+  };
+
+  const resolvedHeader =
+    header ??
+    (navigation || headline ? (
+      <FindAccountHeader navigation={navigation} headline={headline} />
+    ) : undefined);
+
+  return (
+    <AuthContainer
+      className={clsx("auth-find-account-container", className)}
+      header={resolvedHeader}
+      footer={footer}
+    >
+      <form
+        className="auth-find-account-form auth-find-account-form--info"
+        {...formAttr}
+        onSubmit={handleSubmit}
+      >
+        <div className="auth-find-account-fields">
+          <Input
+            {...composeFindAccountFieldProps<InputProps>(
+              fields.name,
+              helpers.name,
+            )}
+            register={register.name}
+          />
+          <Input
+            {...composeFindAccountFieldProps<InputProps>(
+              fields.email,
+              helpers.email,
+            )}
+            register={register.email}
+          />
+        </div>
+        <Button.Default {...buttonProps}>
+          {cta?.label ?? DEFAULT_CTA_LABEL}
+        </Button.Default>
+      </form>
+    </AuthContainer>
+  );
+}
+
+export default FindAccountInfoStep;