# Utilidades compartidas del Frontend

Esta carpeta (`frontend/src/utils/`) contiene funciones de uso común que
**todas las páginas deben reutilizar** en lugar de reimplementar cada una
por su cuenta.

---

## `format.ts` — Formato de fechas

### Por qué existe

La base de datos devuelve fechas en formato ISO (`"2026-06-19"`). Mostrar ese
string directamente en la interfaz es poco amigable. Este util convierte
cualquier fecha ISO al formato argentino estándar `DD/MM/YYYY`.

### Función disponible

```ts
import { formatFecha } from "@/utils/format";
```

#### `formatFecha(iso: string | null | undefined): string`

| Entrada | Salida |
|---------|--------|
| `"2026-06-19"` | `"19/06/2026"` |
| `"2025-01-05"` | `"05/01/2025"` |
| `null` | `"—"` |
| `undefined` | `"—"` |
| `""` | `"—"` |
| Formato inválido | `"—"` |

### Ejemplo de uso en una tabla

```tsx
import { formatFecha } from "@/utils/format";

// En la definición de columnas de DataTable:
{
  key: "fecha_inscripcion",
  label: "Fecha de inscripción",
  render: (row) => formatFecha(row.fecha_inscripcion),
}
```

### Páginas que ya la usan

- `Periodos.tsx`
- `AsistenciasSecretaria.tsx`
- `HorarioDocente.tsx`
- `Asistencias.tsx`
- `Matriculaciones.tsx`

---

## `colors.ts` — Colores de estado para badges

### Por qué existe

Los badges de estado (Activo, Ausente, Mañana, etc.) deben verse exactamente
igual en todas las pantallas del sistema. Este util es la única fuente de verdad
para esos colores; ninguna página debe tener colores hardcodeados.

### Tipo base

```ts
import { type ColorTrio } from "@/utils/colors";

// ColorTrio es: { bg: string; text: string; border: string }
// Los valores son colores hex listos para usar en estilos inline.
```

### Paleta base

Estas constantes están disponibles si necesitás un color específico puntual:

| Constante | Color visual | Cuándo usarla |
|-----------|-------------|---------------|
| `COLOR_VERDE` | Verde | Éxito, activo, aprobado |
| `COLOR_ROJO` | Rojo | Error, baja, reprobado, abandono |
| `COLOR_AMARILLO` | Amarillo | Advertencia, pendiente, tardanza |
| `COLOR_AZUL` | Azul | Información, egresado, noche |
| `COLOR_NARANJA` | Naranja | Turno tarde |
| `COLOR_MORADO` | Morado | Modalidad modular |
| `COLOR_GRIS` | Gris | Inactivo, desconocido, sin dato |

### Funciones semánticas

Estas son las funciones que deben usarse en el código. Reciben el valor del
campo y devuelven un `ColorTrio`.

---

#### `colorActivo(activo: boolean): ColorTrio`

Para cualquier campo `activo: boolean` de un catálogo (grupos, docentes,
niveles académicos, períodos, etc.).

```ts
import { colorActivo } from "@/utils/colors";

// Activo → verde / Inactivo → gris
const c = colorActivo(docente.activo);
```

```tsx
<span style={{ background: c.bg, color: c.text, border: `1px solid ${c.border}` }}
      className="px-2 py-0.5 rounded-full text-xs font-medium">
  {docente.activo ? "Activo" : "Inactivo"}
</span>
```

---

#### `colorEstadoAsistencia(nombre?: string | null): ColorTrio`

Para el estado de asistencia de un alumno en una sesión.

| Valor (parcial) | Color |
|----------------|-------|
| `"Presente"` | Verde |
| `"Ausente"`, `"Falta"` | Rojo |
| `"Tardanza"` | Amarillo |
| `"Justificado"`, `"Licencia"` | Azul |
| Cualquier otro | Gris |

La comparación es insensible a mayúsculas y verifica si el texto *contiene*
la palabra clave, no si es igual, por lo que funciona con cualquier variante
del nombre guardado en la BD.

---

#### `colorEstadoEstudiante(nombre?: string | null, activoFallback?: boolean): ColorTrio`

Para el estado de un estudiante.

| Valor | Color |
|-------|-------|
| `"Activo"` | Verde |
| `"Egresado"` | Azul |
| `"Suspendido"` | Amarillo |
| `"Abandono"` | Rojo |
| `"Inactivo"` / otro | Gris |

El parámetro `activoFallback` es opcional. Si el nombre viene nulo pero sabés
que el campo booleano `activo` es `true`, podés pasarlo como segundo argumento
para que devuelva verde en lugar de gris.

```ts
// Con nombre de estado
colorEstadoEstudiante(estudiante.estado_nombre)

// Cuando no hay nombre pero sí campo booleano
colorEstadoEstudiante(null, estudiante.activo)
```

---

#### `colorEstadoInscripcion(nombre?: string | null): ColorTrio`

Para el estado de una inscripción/matrícula.

| Valor | Color |
|-------|-------|
| `"Activa"`, `"Aprobada"` | Verde |
| `"Baja"`, `"Reprobada"`, `"Abandono"` | Rojo |
| `"Pendiente"` | Amarillo |
| `"Convalidada"` | Azul |
| Otro | Gris |

---

#### `colorTurno(nombre?: string | null): ColorTrio`

Para el turno de una oferta de asignatura o grupo.

| Valor | Color |
|-------|-------|
| `"Mañana"` | Verde |
| `"Tarde"` | Naranja |
| `"Noche"` | Azul |
| `"Sábado"`, `"Domingo"`, otro | Gris |

---

#### `colorModalidad(nombre?: string | null): ColorTrio`

Para la modalidad académica de un período.

| Valor | Color |
|-------|-------|
| `"Semestral"` | Azul |
| `"Modular"` | Morado |
| `"Anual"` | Verde |
| Otro | Gris |

---

### Ejemplo completo — badge de estado en una tabla

```tsx
import { colorEstadoEstudiante } from "@/utils/colors";

// En la definición de columnas:
{
  key: "estado",
  label: "Estado",
  render: (row) => {
    const c = colorEstadoEstudiante(row.estado_nombre);
    return (
      <span
        style={{ background: c.bg, color: c.text, border: `1px solid ${c.border}` }}
        className="px-2 py-0.5 rounded-full text-xs font-medium"
      >
        {row.estado_nombre ?? "Sin estado"}
      </span>
    );
  },
}
```

### Páginas que ya los usan

- `Asistencias.tsx`
- `AsistenciasSecretaria.tsx`
- `Ofertas.tsx`
- `Periodos.tsx`
- `NivelesAcademicos.tsx`
- `Grupos.tsx`
- `Docentes.tsx`
- `InscritosMKT.tsx`
- `InscripcionMKT.tsx`

---

## Agregar una nueva función de color

Si aparece un nuevo tipo de estado en el sistema:

1. Abrí `frontend/src/utils/colors.ts`.
2. Agregá una función nueva siguiendo el mismo patrón: recibís el nombre como
   string, usás `toLowerCase()` con `.includes()` para matchear, y devolvés
   una constante `COLOR_*`.
3. **No agregues colores inline en los componentes.** Siempre agregá la lógica
   aquí y exportá la función.
