hazo_auth 0.1.0

package/src/components/layouts/reset_password/hooks/use_reset_password_form.ts

@@ -0,0 +1,276 @@
+// file_description: encapsulate reset password form state, validation, and data interactions
+// section: imports
+import { useCallback, useMemo, useState, useEffect } from "react";
+import { useSearchParams, useRouter } from "next/navigation";
+import { toast } from "sonner";
+import type { LayoutDataClient } from "@/components/layouts/shared/data/layout_data_client";
+import type { PasswordRequirementOptions } from "@/components/layouts/shared/config/layout_customization";
+import { RESET_PASSWORD_FIELD_IDS, type ResetPasswordFieldId } from "@/components/layouts/reset_password/config/reset_password_field_config";
+import { validatePassword } from "@/components/layouts/shared/utils/validation";
+
+// section: constants
+const PASSWORD_FIELDS: Array<ResetPasswordFieldId> = [
+  RESET_PASSWORD_FIELD_IDS.PASSWORD,
+  RESET_PASSWORD_FIELD_IDS.CONFIRM_PASSWORD,
+];
+
+// section: types
+export type ResetPasswordFormValues = Record<ResetPasswordFieldId, string>;
+export type ResetPasswordFormErrors = Partial<Record<ResetPasswordFieldId, string | string[]>>;
+export type PasswordVisibilityState = Record<
+  Extract<ResetPasswordFieldId, "password" | "confirm_password">,
+  boolean
+>;
+
+export type UseResetPasswordFormParams<TClient = unknown> = {
+  passwordRequirements: PasswordRequirementOptions;
+  dataClient: LayoutDataClient<TClient>;
+  loginPath?: string;
+};
+
+export type UseResetPasswordFormResult = {
+  values: ResetPasswordFormValues;
+  errors: ResetPasswordFormErrors;
+  passwordVisibility: PasswordVisibilityState;
+  isSubmitDisabled: boolean;
+  isSubmitting: boolean;
+  isSuccess: boolean;
+  token: string | null;
+  isValidatingToken: boolean;
+  tokenError: string | null;
+  handleFieldChange: (fieldId: ResetPasswordFieldId, value: string) => void;
+  togglePasswordVisibility: (fieldId: "password" | "confirm_password") => void;
+  handleSubmit: (event: React.FormEvent<HTMLFormElement>) => void;
+  handleCancel: () => void;
+};
+
+// section: helpers
+const buildInitialValues = (): ResetPasswordFormValues => ({
+  [RESET_PASSWORD_FIELD_IDS.PASSWORD]: "",
+  [RESET_PASSWORD_FIELD_IDS.CONFIRM_PASSWORD]: "",
+});
+
+// section: hook
+export const use_reset_password_form = <TClient,>({
+  passwordRequirements,
+  dataClient,
+  loginPath = "/login",
+}: UseResetPasswordFormParams<TClient>): UseResetPasswordFormResult => {
+  const router = useRouter();
+  const searchParams = useSearchParams();
+  const tokenParam = searchParams.get("token");
+
+  const [values, setValues] = useState<ResetPasswordFormValues>(buildInitialValues);
+  const [errors, setErrors] = useState<ResetPasswordFormErrors>({});
+  const [passwordVisibility, setPasswordVisibility] = useState<PasswordVisibilityState>({
+    password: false,
+    confirm_password: false,
+  });
+  const [isSubmitting, setIsSubmitting] = useState<boolean>(false);
+  const [isSuccess, setIsSuccess] = useState<boolean>(false);
+  const [token, setToken] = useState<string | null>(tokenParam);
+  const [isValidatingToken, setIsValidatingToken] = useState<boolean>(false);
+  const [tokenError, setTokenError] = useState<string | null>(null);
+
+  // Validate token on mount
+  useEffect(() => {
+    if (!tokenParam) {
+      setTokenError("Reset password link invalid or has expired. Please go to Reset Password page to get a new link.");
+      return;
+    }
+
+    // Validate token by calling validation API
+    const validateToken = async () => {
+      setIsValidatingToken(true);
+      setTokenError(null);
+
+      try {
+        const response = await fetch(`/api/auth/validate_reset_token?token=${encodeURIComponent(tokenParam)}`, {
+          method: "GET",
+        });
+
+        const data = await response.json();
+
+        if (!response.ok || !data.success) {
+          const errorMessage = data.error || "Reset password link invalid or has expired. Please go to Reset Password page to get a new link.";
+          setTokenError(errorMessage);
+          setToken(null);
+        } else {
+          // Token is valid
+          setToken(tokenParam);
+          setTokenError(null);
+        }
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : "An error occurred while validating the token";
+        setTokenError("Reset password link invalid or has expired. Please go to Reset Password page to get a new link.");
+        setToken(null);
+      } finally {
+        setIsValidatingToken(false);
+      }
+    };
+
+    void validateToken();
+  }, [tokenParam]);
+
+  const isSubmitDisabled = useMemo(() => {
+    if (isSubmitting || isSuccess || !token || tokenError) {
+      return true;
+    }
+
+    const hasEmptyField = Object.values(values).some((value) => value.trim() === "");
+    if (hasEmptyField) {
+      return true;
+    }
+
+    return Object.keys(errors).length > 0;
+  }, [isSubmitting, isSuccess, token, tokenError, values, errors]);
+
+  const handleFieldChange = useCallback((fieldId: ResetPasswordFieldId, value: string) => {
+    setValues((prev) => ({ ...prev, [fieldId]: value }));
+
+    // Clear error for this field when user starts typing
+    if (errors[fieldId]) {
+      setErrors((prev) => {
+        const next = { ...prev };
+        delete next[fieldId];
+        return next;
+      });
+    }
+
+    // Validate password fields in real-time
+    if (fieldId === RESET_PASSWORD_FIELD_IDS.PASSWORD) {
+      const passwordError = validatePassword(value, passwordRequirements);
+      if (passwordError) {
+        setErrors((prev) => ({
+          ...prev,
+          [RESET_PASSWORD_FIELD_IDS.PASSWORD]: passwordError,
+        }));
+      } else {
+        setErrors((prev) => {
+          const next = { ...prev };
+          delete next[RESET_PASSWORD_FIELD_IDS.PASSWORD];
+          return next;
+        });
+      }
+
+      // Also validate confirm password if it has a value
+      if (values[RESET_PASSWORD_FIELD_IDS.CONFIRM_PASSWORD]) {
+        if (value !== values[RESET_PASSWORD_FIELD_IDS.CONFIRM_PASSWORD]) {
+          setErrors((prev) => ({
+            ...prev,
+            [RESET_PASSWORD_FIELD_IDS.CONFIRM_PASSWORD]: "Passwords do not match",
+          }));
+        } else {
+          setErrors((prev) => {
+            const next = { ...prev };
+            delete next[RESET_PASSWORD_FIELD_IDS.CONFIRM_PASSWORD];
+            return next;
+          });
+        }
+      }
+    } else if (fieldId === RESET_PASSWORD_FIELD_IDS.CONFIRM_PASSWORD) {
+      if (value !== values[RESET_PASSWORD_FIELD_IDS.PASSWORD]) {
+        setErrors((prev) => ({
+          ...prev,
+          [RESET_PASSWORD_FIELD_IDS.CONFIRM_PASSWORD]: "Passwords do not match",
+        }));
+      } else {
+        setErrors((prev) => {
+          const next = { ...prev };
+          delete next[RESET_PASSWORD_FIELD_IDS.CONFIRM_PASSWORD];
+          return next;
+        });
+      }
+    }
+  }, [errors, passwordRequirements, values]);
+
+  const togglePasswordVisibility = useCallback((fieldId: "password" | "confirm_password") => {
+    setPasswordVisibility((prev) => ({
+      ...prev,
+      [fieldId]: !prev[fieldId],
+    }));
+  }, []);
+
+  const handleSubmit = useCallback(async (event: React.FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+
+    if (!token) {
+      toast.error("Reset token is missing");
+      return;
+    }
+
+    // Validate all fields
+    const passwordError = validatePassword(values[RESET_PASSWORD_FIELD_IDS.PASSWORD], passwordRequirements);
+    const confirmPasswordError =
+      values[RESET_PASSWORD_FIELD_IDS.PASSWORD] !== values[RESET_PASSWORD_FIELD_IDS.CONFIRM_PASSWORD]
+        ? "Passwords do not match"
+        : undefined;
+
+    if (passwordError || confirmPasswordError) {
+      setErrors({
+        ...(passwordError ? { [RESET_PASSWORD_FIELD_IDS.PASSWORD]: passwordError } : {}),
+        ...(confirmPasswordError ? { [RESET_PASSWORD_FIELD_IDS.CONFIRM_PASSWORD]: confirmPasswordError } : {}),
+      });
+      return;
+    }
+
+    setIsSubmitting(true);
+
+    try {
+      const response = await fetch("/api/auth/reset_password", {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          token,
+          new_password: values[RESET_PASSWORD_FIELD_IDS.PASSWORD],
+        }),
+      });
+
+      const data = await response.json();
+
+      if (!response.ok || !data.success) {
+        const errorMessage = data.error || "Failed to reset password";
+        toast.error(errorMessage);
+        setTokenError(errorMessage);
+        setIsSubmitting(false);
+        return;
+      }
+
+      toast.success(data.message || "Password reset successfully");
+      setIsSuccess(true);
+
+      // Redirect to login after a short delay
+      setTimeout(() => {
+        router.push(loginPath);
+      }, 2000);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : "An error occurred";
+      toast.error(errorMessage);
+      setTokenError(errorMessage);
+      setIsSubmitting(false);
+    }
+  }, [token, values, passwordRequirements, router, loginPath]);
+
+  const handleCancel = useCallback(() => {
+    router.push(loginPath);
+  }, [router, loginPath]);
+
+  return {
+    values,
+    errors,
+    passwordVisibility,
+    isSubmitDisabled,
+    isSubmitting,
+    isSuccess,
+    token,
+    isValidatingToken,
+    tokenError,
+    handleFieldChange,
+    togglePasswordVisibility,
+    handleSubmit,
+    handleCancel,
+  };
+};
+

package/src/components/layouts/reset_password/index.tsx

@@ -0,0 +1,294 @@
+// file_description: reset password layout component built atop shared layout utilities
+// section: client_directive
+"use client";
+
+// section: imports
+import { PasswordField } from "@/components/layouts/shared/components/password_field";
+import { FormFieldWrapper } from "@/components/layouts/shared/components/form_field_wrapper";
+import { FormHeader } from "@/components/layouts/shared/components/form_header";
+import { FormActionButtons } from "@/components/layouts/shared/components/form_action_buttons";
+import { TwoColumnAuthLayout } from "@/components/layouts/shared/components/two_column_auth_layout";
+import { CheckCircle, XCircle, Loader2 } from "lucide-react";
+import { AlreadyLoggedInGuard } from "@/components/layouts/shared/components/already_logged_in_guard";
+import {
+  type ButtonPaletteOverrides,
+  type LayoutFieldMapOverrides,
+  type LayoutLabelOverrides,
+  type PasswordRequirementOverrides,
+} from "@/components/layouts/shared/config/layout_customization";
+import {
+  RESET_PASSWORD_FIELD_IDS,
+  createResetPasswordFieldDefinitions,
+  resolveResetPasswordButtonPalette,
+  resolveResetPasswordLabels,
+  resolveResetPasswordPasswordRequirements,
+} from "@/components/layouts/reset_password/config/reset_password_field_config";
+import {
+  use_reset_password_form,
+  type UseResetPasswordFormResult,
+} from "@/components/layouts/reset_password/hooks/use_reset_password_form";
+import { type LayoutDataClient } from "@/components/layouts/shared/data/layout_data_client";
+import Link from "next/link";
+
+// section: types
+export type ResetPasswordLayoutProps<TClient = unknown> = {
+  image_src: string;
+  image_alt: string;
+  image_background_color?: string;
+  field_overrides?: LayoutFieldMapOverrides;
+  labels?: LayoutLabelOverrides;
+  button_colors?: ButtonPaletteOverrides;
+  password_requirements?: PasswordRequirementOverrides;
+  data_client: LayoutDataClient<TClient>;
+  alreadyLoggedInMessage?: string;
+  showLogoutButton?: boolean;
+  showReturnHomeButton?: boolean;
+  returnHomeButtonLabel?: string;
+  returnHomePath?: string;
+  errorMessage?: string;
+  successMessage?: string;
+  loginPath?: string;
+  forgotPasswordPath?: string;
+};
+
+const ORDERED_FIELDS: ResetPasswordFieldId[] = [
+  RESET_PASSWORD_FIELD_IDS.PASSWORD,
+  RESET_PASSWORD_FIELD_IDS.CONFIRM_PASSWORD,
+];
+
+type ResetPasswordFieldId = (typeof RESET_PASSWORD_FIELD_IDS)[keyof typeof RESET_PASSWORD_FIELD_IDS];
+
+// section: component
+export default function reset_password_layout<TClient>({
+  image_src,
+  image_alt,
+  image_background_color = "#f1f5f9",
+  field_overrides,
+  labels,
+  button_colors,
+  password_requirements,
+  data_client,
+  alreadyLoggedInMessage,
+  showLogoutButton = true,
+  showReturnHomeButton = false,
+  returnHomeButtonLabel = "Return home",
+  returnHomePath = "/",
+  errorMessage = "Reset password link invalid or has expired. Please go to Reset Password page to get a new link.",
+  successMessage = "Password reset successfully. Redirecting to login...",
+  loginPath = "/login",
+  forgotPasswordPath = "/forgot_password",
+}: ResetPasswordLayoutProps<TClient>) {
+  const fieldDefinitions = createResetPasswordFieldDefinitions(field_overrides);
+  const resolvedLabels = resolveResetPasswordLabels(labels);
+  const resolvedButtonPalette = resolveResetPasswordButtonPalette(button_colors);
+  const resolvedPasswordRequirements = resolveResetPasswordPasswordRequirements(
+    password_requirements,
+  );
+
+  const form = use_reset_password_form({
+    passwordRequirements: resolvedPasswordRequirements,
+    dataClient: data_client,
+    loginPath,
+  });
+
+  const renderFields = (formState: UseResetPasswordFormResult) => {
+    return ORDERED_FIELDS.map((fieldId) => {
+      const fieldDefinition = fieldDefinitions[fieldId];
+      const fieldValue = formState.values[fieldId];
+      const fieldError = formState.errors[fieldId];
+
+      const inputElement = (
+        <PasswordField
+          inputId={fieldDefinition.id}
+          ariaLabel={fieldDefinition.ariaLabel}
+          value={fieldValue}
+          placeholder={fieldDefinition.placeholder}
+          autoComplete={fieldDefinition.autoComplete}
+          isVisible={formState.passwordVisibility[fieldDefinition.id as "password" | "confirm_password"]}
+          onChange={(nextValue) => formState.handleFieldChange(fieldId, nextValue)}
+          onToggleVisibility={() =>
+            formState.togglePasswordVisibility(fieldDefinition.id as "password" | "confirm_password")
+          }
+          errorMessage={fieldError as string | string[] | undefined}
+        />
+      );
+
+      return (
+        <FormFieldWrapper
+          key={fieldId}
+          fieldId={fieldDefinition.id}
+          label={fieldDefinition.label}
+          input={inputElement}
+          errorMessage={fieldError as string | string[] | undefined}
+        />
+      );
+    });
+  };
+
+  // Show success message if password reset was successful
+  if (form.isSuccess) {
+    return (
+      <AlreadyLoggedInGuard
+        image_src={image_src}
+        image_alt={image_alt}
+        image_background_color={image_background_color}
+        message={alreadyLoggedInMessage}
+        showLogoutButton={showLogoutButton}
+        showReturnHomeButton={showReturnHomeButton}
+        returnHomeButtonLabel={returnHomeButtonLabel}
+        returnHomePath={returnHomePath}
+      >
+        <TwoColumnAuthLayout
+          imageSrc={image_src}
+          imageAlt={image_alt}
+          imageBackgroundColor={image_background_color}
+          formContent={
+            <>
+              <FormHeader
+                heading={resolvedLabels.heading}
+                subHeading={resolvedLabels.subHeading}
+              />
+              <div className="cls_reset_password_layout_success flex flex-col items-center justify-center gap-4 p-8 text-center">
+                <CheckCircle
+                  className="cls_reset_password_layout_success_icon h-16 w-16 text-green-600"
+                  aria-hidden="true"
+                />
+                <p className="cls_reset_password_layout_success_message text-lg font-medium text-slate-900">
+                  {successMessage}
+                </p>
+              </div>
+            </>
+          }
+        />
+      </AlreadyLoggedInGuard>
+    );
+  }
+
+  // Show loading state while validating token
+  if (form.isValidatingToken) {
+    return (
+      <AlreadyLoggedInGuard
+        image_src={image_src}
+        image_alt={image_alt}
+        image_background_color={image_background_color}
+        message={alreadyLoggedInMessage}
+        showLogoutButton={showLogoutButton}
+        showReturnHomeButton={showReturnHomeButton}
+        returnHomeButtonLabel={returnHomeButtonLabel}
+        returnHomePath={returnHomePath}
+      >
+        <TwoColumnAuthLayout
+          imageSrc={image_src}
+          imageAlt={image_alt}
+          imageBackgroundColor={image_background_color}
+          formContent={
+            <div className="cls_reset_password_layout_validating flex flex-col items-center justify-center gap-4 py-8">
+              <Loader2 className="h-12 w-12 animate-spin text-slate-600" aria-hidden="true" />
+              <div className="cls_reset_password_layout_validating_text text-center">
+                <h1 className="cls_reset_password_layout_validating_heading text-2xl font-semibold text-slate-900">
+                  {resolvedLabels.heading}
+                </h1>
+                <p className="cls_reset_password_layout_validating_subheading mt-2 text-sm text-slate-600">
+                  Validating reset token...
+                </p>
+              </div>
+            </div>
+          }
+        />
+      </AlreadyLoggedInGuard>
+    );
+  }
+
+  // Show error message if token is invalid or missing
+  if (form.tokenError || !form.token) {
+    return (
+      <AlreadyLoggedInGuard
+        image_src={image_src}
+        image_alt={image_alt}
+        image_background_color={image_background_color}
+        message={alreadyLoggedInMessage}
+        showLogoutButton={showLogoutButton}
+        showReturnHomeButton={showReturnHomeButton}
+        returnHomeButtonLabel={returnHomeButtonLabel}
+        returnHomePath={returnHomePath}
+      >
+        <TwoColumnAuthLayout
+          imageSrc={image_src}
+          imageAlt={image_alt}
+          imageBackgroundColor={image_background_color}
+          formContent={
+            <div className="cls_reset_password_layout_error flex flex-col items-center justify-center gap-4 p-8 text-center">
+              <XCircle
+                className="cls_reset_password_layout_error_icon h-16 w-16 text-red-600"
+                aria-hidden="true"
+              />
+              <div className="cls_reset_password_layout_error_text">
+                <h1 className="cls_reset_password_layout_error_heading text-2xl font-semibold text-slate-900">
+                  Invalid Reset Link
+                </h1>
+                <p className="cls_reset_password_layout_error_message mt-2 text-sm text-slate-600">
+                  {form.tokenError || errorMessage}
+                </p>
+              </div>
+              <Link
+                href={forgotPasswordPath}
+                className="cls_reset_password_layout_forgot_password_link mt-4 text-sm text-blue-600 hover:text-blue-800 underline"
+              >
+                Go to Reset Password page
+              </Link>
+            </div>
+          }
+        />
+      </AlreadyLoggedInGuard>
+    );
+  }
+
+  return (
+    <AlreadyLoggedInGuard
+      image_src={image_src}
+      image_alt={image_alt}
+      image_background_color={image_background_color}
+      message={alreadyLoggedInMessage}
+      showLogoutButton={showLogoutButton}
+      showReturnHomeButton={showReturnHomeButton}
+      returnHomeButtonLabel={returnHomeButtonLabel}
+      returnHomePath={returnHomePath}
+    >
+      <TwoColumnAuthLayout
+        imageSrc={image_src}
+        imageAlt={image_alt}
+        imageBackgroundColor={image_background_color}
+        formContent={
+          <>
+            <FormHeader
+              heading={resolvedLabels.heading}
+              subHeading={resolvedLabels.subHeading}
+            />
+            <form
+              className="cls_reset_password_layout_form_fields flex flex-col gap-5"
+              onSubmit={form.handleSubmit}
+              aria-label="Reset password form"
+            >
+              {renderFields(form)}
+              <FormActionButtons
+                submitLabel={resolvedLabels.submitButton}
+                cancelLabel={resolvedLabels.cancelButton}
+                buttonPalette={resolvedButtonPalette}
+                isSubmitDisabled={form.isSubmitDisabled}
+                onCancel={form.handleCancel}
+                submitAriaLabel="Submit reset password form"
+                cancelAriaLabel="Cancel reset password form"
+              />
+              {form.isSubmitting && (
+                <div className="cls_reset_password_layout_submitting_indicator text-sm text-slate-600 text-center">
+                  Resetting password...
+                </div>
+              )}
+            </form>
+          </>
+        }
+      />
+    </AlreadyLoggedInGuard>
+  );
+}
+

package/src/components/layouts/shared/components/already_logged_in_guard.tsx

@@ -0,0 +1,95 @@
+// file_description: reusable component to show "already logged in" message when user is authenticated
+// section: client_directive
+"use client";
+
+// section: imports
+import { use_auth_status } from "@/components/layouts/shared/hooks/use_auth_status";
+import { LogoutButton } from "@/components/layouts/shared/components/logout_button";
+import { Button } from "@/components/ui/button";
+import { TwoColumnAuthLayout } from "@/components/layouts/shared/components/two_column_auth_layout";
+import { useRouter } from "next/navigation";
+import { Home } from "lucide-react";
+
+// section: types
+export type AlreadyLoggedInGuardProps = {
+  image_src: string;
+  image_alt: string;
+  image_background_color?: string;
+  message?: string;
+  showLogoutButton?: boolean;
+  showReturnHomeButton?: boolean;
+  returnHomeButtonLabel?: string;
+  returnHomePath?: string;
+  requireEmailVerified?: boolean;
+  children: React.ReactNode;
+};
+
+// section: component
+/**
+ * Guard component that shows "already logged in" message if user is authenticated
+ * Otherwise renders children
+ * @param props - Component props including layout config and message customization
+ * @returns Either the "already logged in" UI or the children
+ */
+export function AlreadyLoggedInGuard({
+  image_src,
+  image_alt,
+  image_background_color = "#f1f5f9",
+  message = "You're already logged in.",
+  showLogoutButton = true,
+  showReturnHomeButton = false,
+  returnHomeButtonLabel = "Return home",
+  returnHomePath = "/",
+  requireEmailVerified = false,
+  children,
+}: AlreadyLoggedInGuardProps) {
+  const router = useRouter();
+  const authStatus = use_auth_status();
+
+  // Check if user should see "already logged in" message
+  // If requireEmailVerified is true, only show if email is verified
+  // If requireEmailVerified is false, show if authenticated
+  const shouldShowAlreadyLoggedIn =
+    authStatus.authenticated &&
+    !authStatus.loading &&
+    (!requireEmailVerified || authStatus.email_verified === true);
+
+  if (shouldShowAlreadyLoggedIn) {
+    return (
+      <TwoColumnAuthLayout
+        imageSrc={image_src}
+        imageAlt={image_alt}
+        imageBackgroundColor={image_background_color}
+        formContent={
+          <div className="cls_already_logged_in_guard flex flex-col items-center justify-center gap-4 p-8 text-center">
+            <p className="cls_already_logged_in_guard_message text-lg font-medium text-slate-900">
+              {message}
+            </p>
+            <div className="cls_already_logged_in_guard_actions flex flex-col gap-3 items-center mt-4">
+              {showLogoutButton && (
+                <LogoutButton
+                  className="cls_already_logged_in_guard_logout_button"
+                  variant="default"
+                />
+              )}
+              {showReturnHomeButton && (
+                <Button
+                  onClick={() => router.push(returnHomePath)}
+                  variant="outline"
+                  className="cls_already_logged_in_guard_return_home_button"
+                  aria-label={returnHomeButtonLabel}
+                >
+                  <Home className="h-4 w-4 mr-2" aria-hidden="true" />
+                  {returnHomeButtonLabel}
+                </Button>
+              )}
+            </div>
+          </div>
+        }
+      />
+    );
+  }
+
+  return <>{children}</>;
+}
+

package/src/components/layouts/shared/components/field_error_message.tsx

@@ -0,0 +1,29 @@
+// file_description: reusable error message component for form field validation errors
+// section: types
+type FieldErrorMessageProps = {
+  message: string | string[];
+  className?: string;
+};
+
+// section: component
+export function FieldErrorMessage({
+  message,
+  className,
+}: FieldErrorMessageProps) {
+  const messages = Array.isArray(message) ? message : [message];
+
+  return (
+    <div
+      className={`cls_field_error_message flex flex-col gap-1 text-sm text-red-600 ${className ?? ""}`}
+      role="alert"
+      aria-live="polite"
+    >
+      {messages.map((msg, index) => (
+        <p key={index} className="break-words leading-relaxed">
+          {msg}
+        </p>
+      ))}
+    </div>
+  );
+}
+