# zpdf - Generador PDF para Zig

> **Ultima actualizacion**: 2025-12-08
> **Lenguaje**: Zig 0.15.2
> **Estado**: v0.1 - Core funcional, en desarrollo activo
> **Inspiracion**: gofpdf (Go), fpdf (PHP)

## Descripcion del Proyecto

**zpdf** es una libreria pura Zig para generacion de documentos PDF. Sin dependencias externas, compila a un binario unico.

**Filosofia**:
- Zero dependencias (100% Zig puro)
- API simple y directa
- Enfocado en generacion de facturas/documentos comerciales
- Soporte para texto, tablas, imagenes y formas basicas
- Calidad open source (doc comments, codigo claro)

**Objetivo**: Ser el pilar para generar PDFs en Zig con codigo 100% propio, replicando funcionalidad de librerias maduras como gofpdf.

---

## Estado Actual del Proyecto

### Implementacion v0.1 (Core Funcional)

| Componente | Estado | Archivo |
|------------|--------|---------|
| **Document** | | |
| Document init/deinit | ✅ | `src/root.zig` |
| addPage (standard sizes) | ✅ | `src/root.zig` |
| addPageCustom | ✅ | `src/root.zig` |
| render() to buffer | ✅ | `src/root.zig` |
| saveToFile() | ✅ | `src/root.zig` |
| **Page** | | |
| Page init/deinit | ✅ | `src/root.zig` |
| setFont | ✅ | `src/root.zig` |
| drawText | ✅ | `src/root.zig` |
| setFillColor | ✅ | `src/root.zig` |
| setStrokeColor | ✅ | `src/root.zig` |
| setLineWidth | ✅ | `src/root.zig` |
| drawLine | ✅ | `src/root.zig` |
| drawRect | ✅ | `src/root.zig` |
| fillRect | ✅ | `src/root.zig` |
| drawFilledRect | ✅ | `src/root.zig` |
| **Types** | | |
| PageSize enum (A4, Letter, etc.) | ✅ | `src/root.zig` |
| Font enum (14 Type1 fonts) | ✅ | `src/root.zig` |
| Color struct (RGB) | ✅ | `src/root.zig` |

### Tests

| Categoria | Tests | Estado |
|-----------|-------|--------|
| Create empty document | 1 | ✅ |
| Add page | 1 | ✅ |
| Render minimal document | 1 | ✅ |
| Font names | 1 | ✅ |
| Color conversion | 1 | ✅ |
| Graphics operations | 1 | ✅ |
| **Total** | **6** | ✅ |

### Ejemplos

| Ejemplo | Descripcion | Estado |
|---------|-------------|--------|
| hello.zig | PDF minimo con texto y formas | ✅ |
| invoice.zig | Factura completa realista | ✅ |

---

## Roadmap

### Fase 1 - Core (COMPLETADO)
- [x] Estructura documento PDF 1.4
- [x] Paginas (A4, Letter, A3, A5, Legal, custom)
- [x] Texto basico (14 fuentes Type1 built-in)
- [x] Lineas y rectangulos
- [x] Colores RGB
- [x] Serializacion correcta

### Fase 2 - Texto Avanzado (PENDIENTE)
- [ ] Multiples fuentes en mismo documento
- [ ] Alineacion (izquierda, centro, derecha)
- [ ] Word wrap automatico
- [ ] Interlineado configurable
- [ ] Texto multilinea

### Fase 3 - Imagenes (PENDIENTE)
- [ ] JPEG embebido
- [ ] PNG embebido (con alpha)
- [ ] Escalado y posicionamiento
- [ ] Aspect ratio preservation

### Fase 4 - Utilidades (PENDIENTE)
- [ ] Helper para tablas
- [ ] Numeracion de paginas
- [ ] Headers/footers automaticos
- [ ] Margenes de pagina
- [ ] Links/URLs

### Fase 5 - Avanzado (FUTURO)
- [ ] Fuentes TTF embebidas
- [ ] Compresion de streams
- [ ] Metadatos documento (autor, titulo)
- [ ] Bookmarks/outline
- [ ] Forms (campos rellenables)

---

## Arquitectura

### Estructura de Archivos

```
zpdf/
├── CLAUDE.md              # Este archivo - estado del proyecto
├── build.zig              # Sistema de build
├── src/
│   └── root.zig           # Libreria principal (todo en uno por ahora)
└── examples/
    ├── hello.zig          # Ejemplo basico
    └── invoice.zig        # Factura ejemplo
```

### Formato PDF

Generamos PDF 1.4 (compatible con todos los lectores):

```
%PDF-1.4
%[binary marker]
1 0 obj << /Type /Catalog /Pages 2 0 R >> endobj
2 0 obj << /Type /Pages /Kids [...] /Count N >> endobj
3 0 obj << /Type /Page ... >> endobj
4 0 obj << /Length ... >> stream ... endstream endobj
xref
0 N
trailer << /Size N /Root 1 0 R >>
startxref
...
%%EOF
```

### Fuentes Type1 Built-in

PDF incluye 14 fuentes estandar que no necesitan embeber:
- **Helvetica**: helvetica, helvetica_bold, helvetica_oblique, helvetica_bold_oblique
- **Times**: times_roman, times_bold, times_italic, times_bold_italic
- **Courier**: courier, courier_bold, courier_oblique, courier_bold_oblique
- **Otros**: symbol, zapf_dingbats

### Tamanos de Pagina

| Nombre | Puntos | Milimetros |
|--------|--------|------------|
| A4 | 595 x 842 | 210 x 297 |
| A3 | 842 x 1191 | 297 x 420 |
| A5 | 420 x 595 | 148 x 210 |
| Letter | 612 x 792 | 216 x 279 |
| Legal | 612 x 1008 | 216 x 356 |

---

## API Actual

### Crear Documento

```zig
const pdf = @import("zpdf");

var doc = pdf.Document.init(allocator);
defer doc.deinit();
```

### Agregar Paginas

```zig
// Tamano estandar
var page = try doc.addPage(.a4);

// Tamano personalizado (en puntos, 1pt = 1/72 inch)
var page = try doc.addPageCustom(500, 700);
```

### Texto

```zig
try page.setFont(.helvetica_bold, 24);
page.setFillColor(pdf.Color{ .r = 0, .g = 0, .b = 255 });
try page.drawText(50, 750, "Titulo");

try page.setFont(.times_roman, 12);
page.setFillColor(pdf.Color.black);
try page.drawText(50, 700, "Texto normal");
```

### Graficos

```zig
// Linea
try page.setLineWidth(1);
page.setStrokeColor(pdf.Color.gray);
try page.drawLine(50, 600, 500, 600);

// Rectangulo solo borde
try page.drawRect(50, 500, 200, 100);

// Rectangulo relleno
page.setFillColor(pdf.Color.light_gray);
try page.fillRect(50, 400, 200, 100);

// Rectangulo con borde y relleno
page.setFillColor(pdf.Color{ .r = 200, .g = 220, .b = 255 });
page.setStrokeColor(pdf.Color.blue);
try page.drawFilledRect(50, 300, 200, 100);
```

### Guardar

```zig
// A archivo
try doc.saveToFile("documento.pdf");

// A buffer (para enviar por red, etc.)
const data = try doc.render(allocator);
defer allocator.free(data);
```

### Colores Predefinidos

```zig
pdf.Color.black       // (0, 0, 0)
pdf.Color.white       // (255, 255, 255)
pdf.Color.red         // (255, 0, 0)
pdf.Color.green       // (0, 255, 0)
pdf.Color.blue        // (0, 0, 255)
pdf.Color.gray        // (128, 128, 128)
pdf.Color.light_gray  // (200, 200, 200)
```

---

## Comandos

```bash
# Zig path
ZIG=/mnt/cello2/arno/re/recode/zig/zig-0.15.2/zig-x86_64-linux-0.15.2/zig

# Compilar
$ZIG build

# Tests
$ZIG build test

# Ejecutar ejemplos
$ZIG build hello && ./zig-out/bin/hello
$ZIG build invoice && ./zig-out/bin/invoice
```

---

## Equipo y Metodologia

### Normas de Trabajo Centralizadas

**IMPORTANTE**: Todas las normas de trabajo estan en:
```
/mnt/cello2/arno/re/recode/TEAM_STANDARDS/
```

**Archivos clave a leer**:
- `LAST_UPDATE.md` - **LEER PRIMERO** - Cambios recientes en normas
- `NORMAS_TRABAJO_CONSENSUADAS.md` - Metodologia fundamental
- `QUICK_REFERENCE.md` - Cheat sheet rapido

### Estandares Zig Open Source (Seccion #24)

- **Claridad**: Codigo autoexplicativo, nombres descriptivos
- **Doc comments**: `///` en todas las funciones publicas
- **Idiomatico**: snake_case, error handling explicito
- **Sin magia**: Preferir codigo explicito sobre abstracciones complejas

### Control de Versiones

```bash
# Remote
git remote: git@git.reugenio.com:reugenio/zpdf.git

# Branches
main        # Codigo estable
```

---

## Referencias

### gofpdf (Referencia principal)
- Repo: https://github.com/go-pdf/fpdf
- Objetivo: Replicar funcionalidad core en Zig

### PDF Reference
- PDF 1.4 Spec: https://opensource.adobe.com/dc-acrobat-sdk-docs/pdfstandards/pdfreference1.4.pdf

### Otros (Referencia)
- pdf-nano (Zig): https://github.com/GregorBudweiser/pdf-nano

---

## Historial de Desarrollo

### 2025-12-08 - v0.1 (Core Funcional)
- Estructura inicial del proyecto
- Document, Page, Color, Font, PageSize types
- Texto con 14 fuentes Type1 standard
- Graficos: lineas, rectangulos (stroke, fill, both)
- Colores RGB
- Serializacion PDF 1.4 correcta
- 6 tests unitarios pasando
- Ejemplos: hello.zig, invoice.zig funcionales

---

## Notas de Desarrollo

### Proxima Sesion
1. Implementar word wrap automatico para texto largo
2. Agregar helper para tablas (simplificar invoice.zig)
3. Soporte para imagenes JPEG
4. Alineacion de texto (center, right)

### Lecciones Aprendidas
- PDF es formato relativamente simple para generacion basica
- Content streams usan operadores PostScript-like
- Coordenadas PDF son desde bottom-left (Y aumenta hacia arriba)
- Las 14 fuentes Type1 estan garantizadas en todos los lectores PDF

### Zig 0.15 Notas
- `std.ArrayList` cambio a `std.ArrayListUnmanaged` con allocator explicito
- `writer()` ahora requiere allocator como parametro
- `toOwnedSlice()` requiere allocator
- `deinit()` requiere allocator

---

## Proyectos Relacionados

| Proyecto | Descripcion | Repo |
|----------|-------------|------|
| **zcatui** | TUI library (ratatui-style) | git.reugenio.com/reugenio/zcatui |
| **zsqlite** | SQLite wrapper | git.reugenio.com/reugenio/zsqlite |
| **zpdf** | PDF generator (este) | git.reugenio.com/reugenio/zpdf |
| **service-monitor** | Monitor de servicios | git.reugenio.com/reugenio/service-monitor |

---

**© zpdf - Generador PDF para Zig**
*2025-12-08 - En desarrollo activo*