Archivos de la Carpeta src/hooks #

// src/hooks/use.login.ts
import { useState, useCallback } from "react"; // Hooks de React
import { useAuthStorage } from "../components/auth/auth.storage"; // Hook para interactuar con el almacenamiento del token
import { useDecodeToken } from "./use.decode.token"; // Hook para decodificar tokens JWT
import * as Sentry from "@sentry/react"; // Librería para monitoreo de errores (Sentry)
import { UseLoginResult } from "../interface/hooks/login";

/**
 * Hook personalizado para gestionar la lógica de inicio de sesión después de obtener un token.
 * Se encarga de validar el token, almacenarlo y manejar los estados de carga y error.
 * @returns Un objeto con el estado de carga, el error de login y la función de login.
 */
export const useLogin = (): UseLoginResult => {
  // Obtiene funciones para actualizar y limpiar el token del almacenamiento
  const { updateToken, clearToken } = useAuthStorage();
  // Obtiene la función para decodificar tokens JWT
  const { decodeToken } = useDecodeToken(null); // No necesitamos el estado inicial aquí para useDecodeToken, solo la función

  // Estados locales del hook
  const [isLoading, setIsLoading] = useState(false); // Estado de carga del proceso de login
  const [loginError, setLoginError] = useState<string | null>(null); // Estado para errores específicos del login

  // Función principal de login, envuelta en useCallback para optimización
  const login = useCallback(
    async (newToken: string) => {
      setIsLoading(true); // Inicia el estado de carga
      setLoginError(null); // Limpia cualquier error previo
      try {
        const decoded = decodeToken(newToken);
        if (!decoded) {
          // Si la decodificación falla (el token es null/undefined o inválido)
          clearToken(); // Limpia cualquier token existente (por seguridad)
          const errorMessage =
            "El token recibido es inválido o está corrupto. Por favor, intente iniciar sesión nuevamente.";
          setLoginError(errorMessage); // Establece un mensaje de error más específico
          throw new Error(errorMessage); // Lanza un error para ser capturado externamente (y por Sentry)
        }

        // Si el token es válido, actualiza el token en el almacenamiento
        updateToken(newToken);
        // Aquí podrías devolver información adicional del token si es necesario al componente llamante
      } catch (error) {
        // Captura y reporta cualquier excepción a Sentry
        Sentry.captureException(error);
        clearToken(); // Asegura que el token se limpie en caso de cualquier error
        // Si el error ya es una instancia de Error, usa su mensaje, de lo contrario, un mensaje genérico
        setLoginError(
          error instanceof Error
            ? error.message
            : "Ocurrió un error inesperado durante el login."
        );
        throw error; // Propaga el error para que el componente llamante pueda manejarlo
      } finally {
        setIsLoading(false); // Finaliza el estado de carga, independientemente del resultado
      }
    },
    // Dependencias de useCallback: se re-crea si alguna de estas funciones cambia
    [updateToken, clearToken, decodeToken]
  );

  // Retorna los estados y la función de login
  return { isLoading, loginError, login };
};

// src/hooks/use.logout.ts
import { useCallback } from "react"; // Hook de React para memoizar funciones
import { useAuthStorage } from "../components/auth/auth.storage"; // Hook para interactuar con el almacenamiento del token

// Define la interfaz para el valor de retorno del hook
interface UseLogoutResult {
  logout: () => void; // Función para cerrar la sesión del usuario
}

/**
 * Hook personalizado para gestionar la lógica de cierre de sesión.
 * Se encarga de limpiar el token de autenticación del almacenamiento.
 * @returns Un objeto con la función `logout`.
 */
export const useLogout = (): UseLogoutResult => {
  // Obtiene la función para limpiar el token del almacenamiento
  const { clearToken } = useAuthStorage();

  // La función de logout, envuelta en useCallback para optimización.
  // Cuando se llama a 'logout', simplemente se ejecuta 'clearToken'.
  const logout = useCallback(() => {
    clearToken();
  }, [clearToken]); // clearToken es una dependencia para useCallback

  // Retorna la función de logout
  return { logout };
};

// src/hooks/use.profile.students.ts
import { useState, useEffect, useCallback } from "react"; // Hooks de React (añadido useCallback)
import {
  fetchStudent,
  updateStudent,
  deleteStudent,
} from "../utils/students.profile"; // Funciones para interactuar con la API de perfiles de estudiantes
import type { Student } from "../interface/student/student"; // Importación de tipo para la interfaz Student
import { toast } from "react-toastify"; // Librería para notificaciones toast
import { mapStudentToFormData } from "../utils/student.form.mapper"; // NUEVA IMPORTACIÓN: para mapear Student a FormData

/**
 * Hook personalizado para gestionar la lógica de un perfil de estudiante específico.
 * Se encarga de la obtención, edición, actualización y eliminación de los datos de un estudiante.
 * @param id El ID del estudiante a gestionar, puede ser `undefined` si no se ha proporcionado.
 * @param token El token de autenticación del usuario, puede ser `null` o `undefined`.
 * @returns Un objeto con los datos del estudiante, estados de UI y funciones de manejo.
 */
export const useStudentProfile = (
  id: string | undefined, // ID del estudiante obtenido de los parámetros de la URL
  token: string | null | undefined // Token de autenticación del usuario actual
) => {
  // Estados para almacenar los datos del estudiante y el control de la UI
  const [student, setStudent] = useState<Student | null>(null); // Datos originales del estudiante
  const [error, setError] = useState<string | null>(null); // Mensaje de error si algo falla
  const [isEditing, setIsEditing] = useState(false); // Bandera para controlar el modo de edición
  const [updatedData, setUpdatedData] = useState<Student | null>(null); // Datos del estudiante en el formulario de edición
  const [isDeleted, setIsDeleted] = useState(false); // Bandera para indicar si el estudiante ha sido eliminado
  const [isNotFound, setIsNotFound] = useState(false); // NUEVO ESTADO: Para indicar si el estudiante no fue encontrado (ej. 404)

  // Efecto para cargar los datos del estudiante cuando el 'id' o el 'token' cambian
  useEffect(() => {
    const fetchData = async () => {
      // Reiniciar estados de error y no encontrado al iniciar nueva carga
      setError(null);
      setIsNotFound(false);

      // Si el ID no está presente, marcamos como no encontrado y salimos.
      // Si el token no está presente, la `ProtectedRoute` debería manejar la redirección.
      if (!id) {
        setIsNotFound(true);
        return;
      }
      if (!token) {
        // En este punto, podríamos manejar un error específico aquí si el token es nulo
        // o confiar en que ProtectedRoute maneja la redirección.
        return;
      }

      try {
        // Llama a la función de utilidad para obtener los datos del estudiante
        const data = await fetchStudent(id, token);
        setStudent(data); // Guarda los datos originales
        setUpdatedData(data); // Inicializa los datos para el formulario de edición con los datos obtenidos
      } catch (err: any) {
        // Captura cualquier error durante la obtención de datos
        // Si el error es un mensaje que indica "no encontrado" (ej. de un 404), establecemos isNotFound
        if (
          err.message &&
          (err.message.includes("no se encontraron datos") ||
            err.message.includes("404") ||
            err.message.includes("not found"))
        ) {
          setIsNotFound(true);
          setError(null); // No es un error general, sino que el recurso no existe
        } else {
          setError(err.message || "Error desconocido al cargar el estudiante");
          setIsNotFound(false);
        }
      }
    };

    fetchData(); // Ejecuta la función de obtención de datos
  }, [id, token]); // Las dependencias aseguran que el efecto se re-ejecute si 'id' o 'token' cambian

  /**
   * Cambia el estado a modo de edición.
   */
  const handleEdit = useCallback(() => setIsEditing(true), []); // Memoizar para optimización

  /**
   * Manejador genérico para los cambios en los campos del formulario de edición.
   * Acepta eventos de cambio de inputs HTML o un objeto para actualizaciones programáticas.
   * Utiliza una función de actualización de estado para asegurar la fiabilidad con estados previos.
   * @param e El evento de cambio o un objeto con 'name' y 'value'.
   */
  const handleChange = useCallback(
    (
      e:
        | React.ChangeEvent<
            HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement
          >
        | { name: keyof Student; value: any } // Permite actualizaciones programáticas de campos
    ) => {
      // Es crucial usar un "updater function" para setUpdatedData cuando la dependencia es el estado previo
      // para evitar problemas con closures y updatedData no siendo el más reciente.
      setUpdatedData((prevData) => {
        if (!prevData) return null; // Si no hay datos previos, no hacemos nada

        if ("target" in e) {
          // Si es un evento de cambio de un elemento HTML (input, select, textarea)
          const { name, value, type } = e.target;
          if (type === "file") {
            // Manejo especial para inputs de tipo 'file'
            const inputElement = e.target as HTMLInputElement;
            return {
              ...prevData,
              [name]: inputElement.files?.[0] || null, // Guarda el primer archivo seleccionado o null si se borra
            };
          } else {
            // Para otros tipos de inputs, actualiza el valor directamente
            return { ...prevData, [name]: value };
          }
        } else {
          // Si es una actualización programática (objeto con 'name' y 'value')
          return { ...prevData, [e.name]: e.value }; // Actualiza el campo específico
        }
      });
    },
    []
  ); // Dependencias vacías porque `setUpdatedData` se llama con un updater function.

  /**
   * Marca un campo de archivo específico para ser eliminado en el backend.
   * Establece el valor del campo a `null` en `updatedData`.
   * @param fieldName El nombre del campo del archivo a eliminar (ej. 'studentImage').
   */
  const handleDeleteFile = useCallback(
    (fieldName: keyof Student) => {
      // Simplemente usamos el handleChange para actualizar el campo a null
      handleChange({ name: fieldName, value: null });
    },
    [handleChange]
  ); // Dependencia: handleChange

  /**
   * Manejador para enviar el formulario de actualización del estudiante.
   * Utiliza la función `mapStudentToFormData` para preparar los datos.
   * @param e El evento de formulario.
   */
  const handleSubmitEdit = useCallback(
    async (e: React.FormEvent) => {
      e.preventDefault(); // Previene el comportamiento por defecto de envío del formulario
      if (!updatedData || !id || !token) {
        // Muestra un toast de error si falta información crítica
        toast.error("Falta información para actualizar el estudiante.", {
          position: "top-right",
        });
        return;
      }

      // Utiliza la nueva función utilitaria para mapear a FormData
      const formData = mapStudentToFormData(updatedData);

      try {
        // Llama a la función de utilidad para actualizar el estudiante con el FormData
        const data = await updateStudent(id, token, formData);
        setStudent(data); // Actualiza los datos originales del estudiante con la respuesta del servidor
        setUpdatedData(data); // Actualiza también los datos del formulario de edición para reflejar los cambios
        setIsEditing(false); // Sale del modo de edición
        toast.success("Estudiante actualizado con éxito", {
          position: "top-right",
        }); // Muestra una notificación de éxito
      } catch (error: any) {
        toast.error(error.message || "Error inesperado al actualizar", {
          position: "top-right",
        }); // Muestra una notificación de error
      }
    },
    [updatedData, id, token]
  ); // Dependencias para memoizar la función

  /**
   * Manejador para eliminar el estudiante del sistema.
   * Pide confirmación al usuario antes de proceder con la eliminación.
   */
  const handleDelete = useCallback(async () => {
    if (!id || !token) return;
    if (
      !window.confirm(
        "¿Estás seguro de eliminar este estudiante? Esta acción es irreversible."
      )
    )
      return;
    try {
      await deleteStudent(id, token);
      setIsDeleted(true);
      toast.success("Estudiante eliminado con éxito", {
        position: "top-right",
      });
    } catch (error: any) {
      toast.error(error.message || "Error al eliminar estudiante", {
        position: "top-right",
      });
    }
  }, [id, token]); // Dependencias para memoizar la función

  // La función 'createDeleteFileEvent' ha sido eliminada, ya que su lógica
  // ahora se maneja de forma más limpia a través de `handleDeleteFile` que usa `handleChange`.

  // Retorna los estados y funciones que el componente de página puede usar
  return {
    student,
    error,
    isEditing,
    updatedData,
    handleEdit,
    handleChange,
    handleSubmitEdit,
    handleDelete,
    isDeleted,
    isNotFound, // ¡NUEVO: Exportar el estado de "no encontrado"!
    handleDeleteFile,
  };
};

// src/hooks/use.protected.route.ts
import { useEffect } from "react"; // Hook de React para efectos secundarios
import { useAuth } from "../components/auth/auth.context"; // Hook para acceder al contexto de autenticación
import { useNavigate, useLocation } from "react-router-dom"; // Hooks para navegación de React Router

/**
 * Hook personalizado para implementar la lógica de protección de rutas.
 * Redirige a los usuarios no autenticados a la página de inicio de sesión.
 * @returns El estado de carga del proceso de autenticación.
 */
export const useProtectedRoute = () => {
  // Obtiene el estado de autenticación y carga del contexto de autenticación
  const { isAuthenticated, isLoading } = useAuth();
  // Hooks para la navegación programática y para obtener la ubicación actual
  const navigate = useNavigate();
  const location = useLocation();

  // Efecto que se ejecuta cuando cambian las dependencias clave
  useEffect(() => {
    // Si la carga de autenticación ha terminado Y el usuario NO está autenticado,
    // entonces lo redirigimos a la página de inicio de sesión.
    if (!isLoading && !isAuthenticated) {
      // Redirige a la ruta raíz (normalmente la página de login)
      // `replace: true` evita que la ruta actual quede en el historial de navegación.
      // `state: { from: location.pathname }` guarda la URL original para una posible redirección posterior al login.
      navigate("/", { replace: true, state: { from: location.pathname } });
    }
  }, [isAuthenticated, isLoading, navigate, location]); // Dependencias del efecto

  // El hook retorna el estado de carga, permitiendo que el componente que lo usa
  // (ej. ProtectedRoute.tsx) muestre un spinner mientras se verifica la autenticación.
  return isLoading;
};

// src/hooks/use.school.class.ts

import { useMemo, useCallback } from "react";
import { useParams } from "react-router-dom";
import { School, Course } from "../interface/common/enums/enums";
import { Student } from "../interface/student/student";
import { UseSchoolClassReturn } from "../interface/hooks/school.class";

// Mapea slugs desde la URL al enum School
const mapSchoolSlugToEnum = (slug: string): School | undefined => {
  switch (slug) {
    case "quinta-normal":
      return School.Quinta;
    case "buin":
      return School.Buin;
    case "la-granja":
      return School.Granja;
    case "nunoa":
      return School.Nunoa;
    case "pudahuel":
      return School.Pudahuel;
    case "san-miguel":
      return School.Miguel;
    default:
      return undefined; // Slug desconocido
  }
};

// Mapea slugs desde la URL al enum Course
const mapCourseSlugToEnum = (slug: string): Course | undefined => {
  switch (slug) {
    case "1nb":
      return Course.NB1;
    case "2nb":
      return Course.NB2;
    case "3nb":
      return Course.NB3;
    case "1nm":
      return Course.NM1;
    case "2nm":
      return Course.NM2;
    default:
      return undefined; // Slug desconocido
  }
};

// Hook principal
export function useSchoolClass(): UseSchoolClassReturn {
  // Extrae los parámetros de la URL
  const { school, course } = useParams<{ school: string; course: string }>();

  // Obtiene el valor del enum School desde el slug de la URL
  const currentSchoolEnum = useMemo(() => {
    const mapped = school ? mapSchoolSlugToEnum(school) : undefined;
    return mapped;
  }, [school]);

  // Obtiene el valor del enum Course desde el slug de la URL
  const currentCourseEnum = useMemo(() => {
    const mapped = course ? mapCourseSlugToEnum(course) : undefined;
    return mapped;
  }, [course]);

  // Nombre del colegio para mostrar en UI (fallback si no hay match)
  const normalizedSchool = useMemo(() => {
    const displayValue = currentSchoolEnum || school || "Colegio Desconocido";
    return displayValue;
  }, [currentSchoolEnum, school]);

  // Nombre del curso para mostrar en UI (fallback si no hay match)
  const normalizedCourse = useMemo(() => {
    const displayValue = currentCourseEnum || course || "Curso Desconocido";
    return displayValue;
  }, [currentCourseEnum, course]);

  // Filtra estudiantes que coincidan con el colegio y curso actual
  const getFilteredStudentsBySchoolAndCourse = useCallback(
    (allStudents: Student[]): Student[] => {
      if (!currentSchoolEnum || !currentCourseEnum || !allStudents) {
        return [];
      }
      return allStudents.filter(
        (student) =>
          student.school === currentSchoolEnum &&
          student.course === currentCourseEnum
      );
    },
    [currentSchoolEnum, currentCourseEnum]
  );

  // Devuelve los valores necesarios para usar en la página SchoolClass
  return {
    normalizedSchool,
    normalizedCourse,
    getFilteredStudentsBySchoolAndCourse,
  };
}

// src/hooks/use.students.list.ts

import { useEffect, useState } from "react"; // Hooks de React
import { useAuth } from "../components/auth/auth.context"; // Hook para acceder al contexto de autenticación
import { fetchStudentsList } from "../utils/fetch.students"; // Función utilitaria para obtener la lista de estudiantes
import { Student } from "../interface/student/student"; // Importa la interfaz Student para tipado

/**
 * Hook personalizado para obtener la lista completa de estudiantes.
 * Gestiona el estado de carga, errores y los datos de los estudiantes.
 * @returns Un objeto con la lista de estudiantes, el error (si lo hay) y el estado de carga.
 */
export const useStudentsList = () => {
  // Obtiene el token de autenticación del contexto
  const { token } = useAuth();
  // Estados para almacenar la lista de estudiantes, errores y el estado de carga
  const [students, setStudents] = useState<Student[]>([]); // Lista de estudiantes, tipada como array de Student
  const [error, setError] = useState<string | null>(null); // Mensaje de error, o null
  const [loading, setLoading] = useState(true); // Estado de carga (true al inicio)

  // Efecto que se ejecuta cuando el token cambia, para cargar los estudiantes
  useEffect(() => {
    const fetchData = async () => {
      // Si no hay token, establece un error y finaliza la carga, luego retorna.
      // Esto previene llamadas a la API sin autenticación.
      if (!token) {
        setError("Token no proporcionado");
        setLoading(false);
        return;
      }

      try {
        // Llama a la función utilitaria para obtener los estudiantes
        const data = await fetchStudentsList(token);
        // Establece la lista de estudiantes. Se asume que 'data' es compatible con Student[].
        setStudents(data);
      } catch (err: any) {
        // Captura cualquier error durante la obtención y lo guarda en el estado 'error'.
        setError(err.message || "Error desconocido al obtener estudiantes");
      } finally {
        // Siempre desactiva el estado de carga al finalizar la operación.
        setLoading(false);
      }
    };

    fetchData(); // Ejecuta la función de obtención de datos
  }, [token]); // El efecto se re-ejecuta si el token de autenticación cambia

  // Retorna los estados y los datos para que el componente que usa el hook pueda acceder a ellos
  return { students, error, loading };
};

// src/hooks/use.add.students.ts

import { useState, ChangeEvent, FormEvent, useCallback } from "react"; // Añadido useCallback
import type { Student } from "../interface/student/student"; // Importación de tipo
import { DateTime } from "luxon"; // Para manejo de fechas
import { toast } from "react-toastify"; // Para notificaciones
import { mapStudentToFormData } from "../utils/student.form.mapper"; // Importa la nueva utilidad
import { addStudent } from "../utils/fetch.students"; // Importa la función de utilidad para agregar estudiante

/**
 * Hook personalizado para gestionar la lógica de añadir un nuevo estudiante.
 * Controla el estado del formulario, maneja los cambios de input (incluyendo archivos),
 * y gestiona el envío de datos a la API.
 * @param token El token de autenticación del usuario. Puede ser `null` o `undefined`.
 * @returns Un objeto con estados (mensajes de éxito/error, datos del estudiante),
 * manejadores de eventos (handleChange, handleSubmit) y una clave para reiniciar el formulario.
 */
export function useAddStudent(token: string | null | undefined) {
  const [formKey, setFormKey] = useState(Date.now()); // Para forzar el reinicio del formulario
  const [studentData, setStudentData] = useState<Student>({
    // Inicialización de los datos del estudiante
    name: "",
    lastname: "",
    rut: "",
    sex: undefined,
    birthdate: undefined,
    nationality: "",
    address: "",
    phone: "",
    email: "",
    source: undefined,
    contact: "",
    contactDate: undefined,
    call1: "",
    call2: "",
    call3: "",
    comments1: "",
    comments2: "",
    comments3: "",
    positiveFeedback: "AÚN SIN RESPUESTAS",
    studentImage: undefined,
    birthCertificate: undefined,
    studyCertificate: undefined,
    linkDni: undefined,
    school: undefined,
    course: undefined,
    communicationPreference: undefined,
    createdAt: undefined,
  });

  const [successMessage, setSuccessMessage] = useState<string>("");
  const [errorMessage, setErrorMessage] = useState<string>("");

  /**
   * Manejador genérico para cambios en los campos del formulario.
   * Actualiza el estado `studentData` basándose en el input del usuario.
   * @param e El evento de cambio del input (HTMLInputElement | HTMLSelectElement).
   */
  const handleChange = useCallback(
    (e: ChangeEvent<HTMLInputElement | HTMLSelectElement>) => {
      // Usamos una función de actualización de estado para asegurar el estado más reciente
      setStudentData((prevData) => {
        const { name, value, type } = e.target;

        if (type === "file") {
          const inputElement = e.target as HTMLInputElement;
          return { ...prevData, [name]: inputElement.files?.[0] || undefined }; // Guarda el archivo o undefined
        } else if ((name === "birthdate" || name === "contactDate") && value) {
          const formattedDate = DateTime.fromISO(value, {
            zone: "America/Santiago",
          }).isValid
            ? DateTime.fromISO(value, { zone: "America/Santiago" }).toISODate()
            : undefined; // Si no es válido, undefined
          return { ...prevData, [name]: formattedDate };
        } else if (value === "undefined") {
          return { ...prevData, [name]: undefined };
        } else {
          return { ...prevData, [name]: value };
        }
      });
    },
    []
  ); // Dependencias vacías, ya que se usa una función de actualización de estado

  /**
   * Manejador para el envío del formulario.
   * Envía los datos del estudiante a la API utilizando la función de utilidad `addStudent`.
   * @param e El evento de envío del formulario.
   */
  const handleSubmit = useCallback(
    async (e: FormEvent) => {
      e.preventDefault(); // Previene el comportamiento por defecto de envío del formulario

      if (!token) {
        setErrorMessage("No estás autenticado. Por favor, inicia sesión.");
        return;
      }

      setErrorMessage(""); // Limpia mensajes de error anteriores
      setSuccessMessage(""); // Limpia mensajes de éxito anteriores

      // Utiliza la utilidad mapStudentToFormData para preparar los datos
      const formData = mapStudentToFormData(studentData);

      try {
        // Llama a la función de utilidad `addStudent` que maneja la petición y errores primarios
        // NOTA: Asegúrate de que `addStudent` en `fetch.students.ts` acepte `FormData`.
        await addStudent(token, formData);

        setSuccessMessage("Estudiante agregado con éxito.");
        // Resetea los datos del formulario a sus valores iniciales
        setStudentData({
          name: "",
          lastname: "",
          rut: "",
          sex: undefined,
          birthdate: undefined,
          nationality: "",
          address: "",
          phone: "",
          email: "",
          source: undefined,
          contact: "",
          contactDate: undefined,
          call1: "",
          call2: "",
          call3: "",
          comments1: "",
          comments2: "",
          comments3: "",
          positiveFeedback: "AÚN SIN RESPUESTAS",
          studentImage: undefined,
          birthCertificate: undefined,
          studyCertificate: undefined,
          linkDni: undefined,
          school: undefined,
          course: undefined,
          communicationPreference: undefined,
          createdAt: undefined,
        });
        setFormKey(Date.now()); // Actualiza la clave para forzar el reinicio del formulario
      } catch (error: any) {
        // Captura el error lanzado por `addStudent` (que ya tiene un mensaje específico)
        console.error("Error al agregar estudiante:", error);
        setErrorMessage(
          error.message ||
            "Error de red al agregar el estudiante. Intente más tarde."
        );
      }
    },
    [token, studentData]
  ); // studentData como dependencia para que el formData se cree con el estado más reciente

  // Retorna los estados y manejadores para ser utilizados por el componente de página
  return {
    successMessage,
    errorMessage,
    handleSubmit,
    studentData,
    handleChange,
    formKey,
  };
}

// src/hooks/use.decode.token.ts
import { useState, useEffect } from "react"; // Hooks de React para estado y efectos
import { jwtDecode, JwtPayload } from "jwt-decode"; // Librería para decodificar JWTs, y tipo para la carga útil base
import * as Sentry from "@sentry/react"; // Librería para monitoreo de errores (Sentry)

/**
 * Hook personalizado para decodificar tokens JWT y extraer información del usuario.
 * Proporciona el ID, email y un estado de error, además de una función para decodificar tokens.
 * @param initialToken El token JWT inicial para decodificar al montar el hook.
 * @returns Un objeto con los datos del usuario decodificados, error y la función de decodificación.
 */
export const useDecodeToken = (
  initialToken: string | null // El token con el que se inicializa el hook (ej. token del localStorage)
): UseDecodeTokenResult => {
  // Estados para almacenar la información decodificada y errores
  const [userId, setUserId] = useState<string | null>(null);
  const [email, setEmail] = useState<string | null>(null);
  const [error, setError] = useState<string | null>(null);

  /**
   * Función interna para decodificar un token JWT.
   * Actualiza los estados internos del hook con la información decodificada o el error.
   * @param token La cadena JWT a decodificar.
   * @returns El objeto `DecodedToken` si la decodificación es exitosa, o `null` en caso de error.
   */
  const decodeToken = (token: string | null): DecodedToken | null => {
    // Si no hay token, resetea todos los estados a null y retorna null.
    if (!token) {
      setUserId(null);
      setEmail(null);
      setError(null);
      return null;
    }

    try {
      // Intenta decodificar el token usando jwtDecode y la interfaz DecodedToken
      const decoded = jwtDecode<DecodedToken>(token);
      // Extrae y guarda el ID de usuario y el email. Usa null si la propiedad no existe en el token.
      setUserId(decoded.uid || null);
      setEmail(decoded.email || null);
      setError(null); // Limpia cualquier error previo si la decodificación es exitosa
      return decoded; // Retorna el token decodificado
    } catch (err) {
      // Captura cualquier error durante la decodificación (ej. token inválido, corrupto)
      const error = err as Error; // Asegura que el error sea tratado como un objeto Error
      Sentry.captureException(error); // Reporta la excepción a Sentry para monitoreo
      setUserId(null); // Resetea el ID de usuario
      setEmail(null); // Resetea el email
      setError(
        "Error al decodificar el token. El token podría ser inválido o corrupto."
      ); // Mensaje de error específico
      return null; // Retorna null para indicar fallo en la decodificación
    }
  };

  // Efecto que se ejecuta al montar el hook o cuando 'initialToken' cambia.
  // Decodifica el token inicial proporcionado.
  // NOTA: La función `decodeToken` no necesita ser incluida en las dependencias de este useEffect
  // porque es una función interna del hook que no depende de ningún estado o prop que cambie
  // entre renders (su definición es estable).
  useEffect(() => {
    decodeToken(initialToken);
  }, [initialToken]); // El efecto se re-ejecuta si el token inicial cambia.

  // Retorna los estados actuales y la función `decodeToken` para uso externo.
  return { userId, email, error, decodeToken };
};

// src/hooks/use.document.handling.ts

import { useCallback } from "react"; // Hook de React para memoizar funciones
import { Student } from "../interface/student/student"; // Interfaz para el tipo Student
import {
  UseDocumentHandlingHookProps, // Propiedades que el hook espera
  UseDocumentHandlingHookResult, // Resultado que el hook retorna
} from "../interface/student/document.handling"; // Rutas a las interfaces

/**
 * Hook personalizado para manejar la lógica de subida y eliminación de documentos (archivos).
 * Proporciona manejadores para eventos de cambio de archivo y confirmación de eliminación.
 * @param {UseDocumentHandlingHookProps} { onChange, onDeleteFile } Props que incluyen callbacks para la gestión de archivos.
 * @returns {UseDocumentHandlingHookResult} Un objeto con las funciones de manejo de archivos.
 */
export const useDocumentHandling = ({
  onChange, // Callback del componente padre para actualizar un campo del estudiante (incluyendo archivos)
  onDeleteFile, // Callback del componente padre para marcar un archivo como eliminado
}: UseDocumentHandlingHookProps): UseDocumentHandlingHookResult => {
  /**
   * Manejador para el evento `onChange` de inputs de tipo `file`.
   * Extrae el archivo seleccionado y llama a `onChange` del padre.
   * Memoizado con `useCallback`.
   * @param e El evento de cambio de un input HTML (tipo file).
   */
  const handleFileChange = useCallback(
    (e: React.ChangeEvent<HTMLInputElement>) => {
      const { name, files } = e.target; // Extrae el nombre del input y la lista de archivos
      if (files && files.length > 0) {
        // Si hay archivos seleccionados, llama a onChange del padre con el primer archivo
        onChange({ name: name as keyof Student, value: files[0] });
      }
    },
    [onChange] // Dependencia: se re-crea si la función `onChange` del padre cambia
  );

  /**
   * Manejador para confirmar y ejecutar la eliminación de un archivo.
   * Muestra un `window.confirm` y llama a `onDeleteFile` del padre si se confirma.
   * Memoizado con `useCallback`.
   * @param fieldName El nombre del campo del estudiante asociado al archivo a eliminar.
   */
  const handleDeleteFile = useCallback(
    (fieldName: keyof Student) => {
      // Muestra un cuadro de diálogo de confirmación al usuario
      if (
        window.confirm(
          `¿Estás seguro de eliminar ${getLabelForField(
            fieldName
          ).toLowerCase()}?` // Usa getLabelForField para un mensaje amigable
        )
      ) {
        onDeleteFile(fieldName); // Si el usuario confirma, llama a onDeleteFile del padre
      }
    },
    [onDeleteFile] // Dependencia: se re-crea si la función `onDeleteFile` del padre cambia
  );

  /**
   * Función auxiliar para obtener una etiqueta legible para un campo de documento.
   * Memoizado con `useCallback`.
   * @param fieldName El nombre del campo del estudiante.
   * @returns La etiqueta legible del campo.
   */
  const getLabelForField = useCallback((fieldName: keyof Student): string => {
    switch (fieldName) {
      case "studentImage":
        return "Foto del Estudiante";
      case "birthCertificate":
        return "Certificado de nacimiento";
      case "studyCertificate":
        return "Certificado de estudio";
      case "linkDni":
        return "Cédula de identidad";
      default:
        return ""; // Retorna vacío si el campo no es reconocido
    }
  }, []); // Sin dependencias, ya que el mapeo es estático

  // Retorna las funciones de manejo de archivos para que el componente que usa el hook las utilice
  return { handleFileChange, handleDeleteFile, getLabelForField };
};