roi-theme/wp-content/themes/apus-theme/docs/APU-TABLES-GUIDE.md

# Guía de Tablas APU (Análisis de Precios Unitarios)

## Descripción

Las tablas APU son el contenido principal del sitio **Análisis de Precios Unitarios**. Este módulo proporciona estilos profesionales específicos para la industria de la construcción, incluyendo:

- **Sin bordes**: Diseño limpio y moderno
- **Zebra striping**: Filas alternadas para mejor legibilidad
- **Headers sticky**: Encabezados fijos al hacer scroll
- **4 tipos de filas especiales**:
  - `thead`: Encabezado con degradado azul
  - `.section-header`: Secciones (Material, Mano de Obra, Herramienta, Equipo)
  - `.subtotal-row`: Subtotales con fondo azul claro
  - `.total-row`: Costo Directo final con degradado azul
- **Responsive**: Scroll horizontal en móviles
- **Print styles**: Optimizado para impresión

---

## Métodos de Uso

### Método 1: Atributo data-apu (Automático)

La forma más simple. Solo agrega el atributo `data-apu` a tu tabla y el sistema la procesará automáticamente:

```html
<table data-apu>
    <thead>
        <tr>
            <th scope="col">Clave</th>
            <th scope="col">Descripción</th>
            <th scope="col">Unidad</th>
            <th scope="col">Cantidad</th>
            <th scope="col">Costo</th>
            <th scope="col">Importe</th>
        </tr>
    </thead>
    <tbody>
        <!-- Encabezado de sección -->
        <tr class="section-header">
            <td></td>
            <td>Material</td>
            <td class="c3"></td>
            <td class="c4"></td>
            <td class="c5"></td>
            <td class="c6"></td>
        </tr>

        <!-- Filas de datos -->
        <tr>
            <td>AGRE-016</td>
            <td>Agua potable</td>
            <td class="c3">m3</td>
            <td class="c4">0.237500</td>
            <td class="c5">$19.14</td>
            <td class="c6">$4.55</td>
        </tr>

        <!-- Subtotal -->
        <tr class="subtotal-row">
            <td></td>
            <td>Suma de Material</td>
            <td class="c3"></td>
            <td class="c4"></td>
            <td class="c5"></td>
            <td class="c6">$2,956.51</td>
        </tr>

        <!-- Total final -->
        <tr class="total-row">
            <td></td>
            <td>Costo Directo</td>
            <td class="c3"></td>
            <td class="c4"></td>
            <td class="c5"></td>
            <td class="c6">$3,283.52</td>
        </tr>
    </tbody>
</table>
```

### Método 2: Shortcode [apu_table]

Envuelve tu tabla con el shortcode:

```
[apu_table]
<table>
    <thead>...</thead>
    <tbody>...</tbody>
</table>
[/apu_table]
```

### Método 3: Clase .analisis (Manual)

Envuelve manualmente tu tabla con un div:

```html
<div class="analisis">
    <table>
        <thead>...</thead>
        <tbody>...</tbody>
    </table>
</div>
```

### Método 4: Shortcode [apu_row] para filas especiales

Para facilitar la creación de filas especiales:

```
[apu_table]
<table>
    <thead>...</thead>
    <tbody>
        [apu_row type="section"]
        <td></td>
        <td>Material</td>
        <td class="c3"></td>
        <td class="c4"></td>
        <td class="c5"></td>
        <td class="c6"></td>
        [/apu_row]

        <!-- Filas normales -->
        <tr>...</tr>

        [apu_row type="subtotal"]
        <td></td>
        <td>Suma de Material</td>
        <td class="c3"></td>
        <td class="c4"></td>
        <td class="c5"></td>
        <td class="c6">$2,956.51</td>
        [/apu_row]

        [apu_row type="total"]
        <td></td>
        <td>Costo Directo</td>
        <td class="c3"></td>
        <td class="c4"></td>
        <td class="c5"></td>
        <td class="c6">$3,283.52</td>
        [/apu_row]
    </tbody>
</table>
[/apu_table]
```

---

## Clases CSS Disponibles

### Para filas (`<tr>`):

- **`section-header`**: Encabezado de sección
  - Fondo gris (#e9ecef)
  - Texto en mayúsculas
  - Color azul oscuro (#1e3a5f)

- **`subtotal-row`**: Fila de subtotal
  - Fondo azul claro (#d1e7fd)
  - Texto en negrita
  - Color azul (#0d47a1)

- **`total-row`**: Fila de total final
  - Degradado azul (#1e3a5f → #2c5282)
  - Texto blanco en negrita
  - Texto en mayúsculas

### Para celdas (`<td>`):

- **`c3`**: Columna 3 (Unidad) - centrada, gris
- **`c4`**: Columna 4 (Cantidad) - derecha, monospace
- **`c5`**: Columna 5 (Costo) - derecha, monospace
- **`c6`**: Columna 6 (Importe) - derecha, monospace

---

## Estructura de Columnas

Las tablas APU siguen esta estructura estándar:

| # | Columna | Ancho | Alineación | Fuente |
|---|---------|-------|------------|--------|
| 1 | Clave | 150px | Izquierda | Normal |
| 2 | Descripción | Auto (min 300px) | Izquierda | Normal |
| 3 | Unidad | 80px | Centro | Normal |
| 4 | Cantidad | 110px | Derecha | Monospace |
| 5 | Costo | 120px | Derecha | Monospace |
| 6 | Importe | 120px | Derecha | Monospace |

---

## Secciones Típicas

Las tablas APU generalmente incluyen estas secciones:

1. **Material**: Insumos y materiales de construcción
2. **Mano de Obra**: Personal y cuadrillas
3. **Herramienta**: Herramientas pequeñas
4. **Equipo**: Maquinaria y equipo pesado

Cada sección debe tener:
- Un encabezado de sección (`.section-header`)
- Filas de datos normales
- Un subtotal (`.subtotal-row`)

Al final, una fila de **Costo Directo** (`.total-row`) suma todos los subtotales.

---

## Ejemplo Completo

```html
<table data-apu>
    <thead>
        <tr>
            <th scope="col">Clave</th>
            <th scope="col">Descripción</th>
            <th scope="col">Unidad</th>
            <th scope="col">Cantidad</th>
            <th scope="col">Costo</th>
            <th scope="col">Importe</th>
        </tr>
    </thead>
    <tbody>
        <!-- MATERIAL -->
        <tr class="section-header">
            <td></td>
            <td>Material</td>
            <td class="c3"></td>
            <td class="c4"></td>
            <td class="c5"></td>
            <td class="c6"></td>
        </tr>

        <tr>
            <td>AGRE-016</td>
            <td>Agua potable</td>
            <td class="c3">m3</td>
            <td class="c4">0.237500</td>
            <td class="c5">$19.14</td>
            <td class="c6">$4.55</td>
        </tr>

        <tr>
            <td>AGRE-001</td>
            <td>Arena en camión de 6 m3</td>
            <td class="c3">m3</td>
            <td class="c4">0.541500</td>
            <td class="c5">$1,750.00</td>
            <td class="c6">$947.63</td>
        </tr>

        <tr>
            <td>CEME-001</td>
            <td>Cemento CPC 30R gris de 50 kg</td>
            <td class="c3">ton</td>
            <td class="c4">0.392000</td>
            <td class="c5">$5,100.00</td>
            <td class="c6">$1,999.20</td>
        </tr>

        <tr class="subtotal-row">
            <td></td>
            <td>Suma de Material</td>
            <td class="c3"></td>
            <td class="c4"></td>
            <td class="c5"></td>
            <td class="c6">$2,956.51</td>
        </tr>

        <!-- MANO DE OBRA -->
        <tr class="section-header">
            <td></td>
            <td>Mano de Obra</td>
            <td class="c3"></td>
            <td class="c4"></td>
            <td class="c5"></td>
            <td class="c6"></td>
        </tr>

        <tr>
            <td>MOCU-027</td>
            <td>Cuadrilla No 27 (1 Albañil + 5 Peones)</td>
            <td class="c3">jor</td>
            <td class="c4">0.100000</td>
            <td class="c5">$2,257.04</td>
            <td class="c6">$225.70</td>
        </tr>

        <tr class="subtotal-row">
            <td></td>
            <td>Suma de Mano de Obra</td>
            <td class="c3"></td>
            <td class="c4"></td>
            <td class="c5"></td>
            <td class="c6">$225.70</td>
        </tr>

        <!-- HERRAMIENTA -->
        <tr class="section-header">
            <td></td>
            <td>Herramienta</td>
            <td class="c3"></td>
            <td class="c4"></td>
            <td class="c5"></td>
            <td class="c6"></td>
        </tr>

        <tr>
            <td>HERR-001</td>
            <td>Herramienta menor (5% M.O.)</td>
            <td class="c3">%</td>
            <td class="c4">5.000000</td>
            <td class="c5">$225.70</td>
            <td class="c6">$11.29</td>
        </tr>

        <tr class="subtotal-row">
            <td></td>
            <td>Suma de Herramienta</td>
            <td class="c3"></td>
            <td class="c4"></td>
            <td class="c5"></td>
            <td class="c6">$11.29</td>
        </tr>

        <!-- EQUIPO -->
        <tr class="section-header">
            <td></td>
            <td>Equipo</td>
            <td class="c3"></td>
            <td class="c4"></td>
            <td class="c5"></td>
            <td class="c6"></td>
        </tr>

        <tr>
            <td>EQUI-015</td>
            <td>Revolvedora gasolina 1 saco (9 p3)</td>
            <td class="c3">hr</td>
            <td class="c4">0.800000</td>
            <td class="c5">$125.00</td>
            <td class="c6">$100.00</td>
        </tr>

        <tr class="subtotal-row">
            <td></td>
            <td>Suma de Equipo</td>
            <td class="c3"></td>
            <td class="c4"></td>
            <td class="c5"></td>
            <td class="c6">$100.00</td>
        </tr>

        <!-- TOTAL FINAL -->
        <tr class="total-row">
            <td></td>
            <td>Costo Directo</td>
            <td class="c3"></td>
            <td class="c4"></td>
            <td class="c5"></td>
            <td class="c6">$3,293.50</td>
        </tr>
    </tbody>
</table>
```

---

## Responsive

Las tablas se adaptan automáticamente a diferentes tamaños de pantalla:

- **Desktop (>992px)**: Vista completa con todos los anchos
- **Tablet (768px-991px)**: Reducción de padding y tamaños de fuente
- **Móvil (<768px)**: Scroll horizontal con ajustes de tamaño

El contenedor `.analisis` tiene `overflow-x: auto` para permitir scroll horizontal en pantallas pequeñas.

---

## Impresión

Los estilos están optimizados para impresión:

- Colores forzados con `print-color-adjust: exact`
- Sin efectos hover
- Prevención de saltos de página dentro de tablas
- Borde agregado para mejor definición en papel

---

## Función Helper PHP

Para generar tablas APU programáticamente desde templates:

```php
<?php
$data = array(
    'headers' => array('Clave', 'Descripción', 'Unidad', 'Cantidad', 'Costo', 'Importe'),
    'sections' => array(
        array(
            'title' => 'Material',
            'rows' => array(
                array('AGRE-016', 'Agua potable', 'm3', '0.237500', '$19.14', '$4.55'),
                array('AGRE-001', 'Arena en camión', 'm3', '0.541500', '$1,750.00', '$947.63'),
            ),
            'subtotal' => '$2,956.51'
        ),
        array(
            'title' => 'Mano de Obra',
            'rows' => array(
                array('MOCU-027', 'Cuadrilla No 27', 'jor', '0.100000', '$2,257.04', '$225.70'),
            ),
            'subtotal' => '$225.70'
        ),
    ),
    'total' => '$3,293.50'
);

echo apus_generate_apu_table($data);
?>
```

---

## Accesibilidad

- Headers con `scope="col"` para lectores de pantalla
- Buen contraste de colores (WCAG AA)
- Focus visible para navegación por teclado
- Textos legibles en todos los fondos

---

## Compatibilidad

- ✅ Compatible con Bootstrap 5
- ✅ No requiere JavaScript
- ✅ Funciona en todos los navegadores modernos
- ✅ Optimizado para WordPress Block Editor
- ✅ Compatible con HTML clásico

---

## Archivos del Módulo

- **CSS**: `wp-content/themes/apus-theme/assets/css/tables-apu.css`
- **PHP**: `wp-content/themes/apus-theme/inc/apu-tables.php`
- **Enqueue**: `wp-content/themes/apus-theme/inc/enqueue-scripts.php` (líneas 297-311)
- **Carga**: `wp-content/themes/apus-theme/functions.php` (líneas 243-246)

---

## Notas de Diseño

1. **Sin bordes**: Diseño moderno sin bordes visibles
2. **Zebra striping**: Solo en filas normales, no en especiales
3. **Fuente monospace**: Courier New para columnas monetarias
4. **Colores profesionales**: Paleta azul corporativa
5. **Hover interactivo**: Fondo amarillo claro (#fff3cd)

---

## Soporte

Para más información sobre el desarrollo del tema, consulta:
- `README.md`
- `TEMPLATES.md`
- `docs/THEME-DOCUMENTATION.md`

---

Creado por [Claude Code](https://claude.com/claude-code) - Issue #30