zcatpdf/CLAUDE.md

zpdf - Generador PDF para Zig

Ultima actualizacion: 2025-12-08 Lenguaje: Zig 0.15.2 Estado: v0.5 - Clickable Links + Complete Feature Set Fuente principal: fpdf2 (Python) - https://github.com/py-pdf/fpdf2

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 inspirada en fpdf2
• Enfocado en generacion de facturas/documentos comerciales
• Soporte completo: texto, tablas, imagenes, links, paginacion

Caracteristicas principales:

• Sistema de texto completo (cell, multiCell, alineacion, word wrap)
• 14 fuentes Type1 standard (Helvetica, Times, Courier, etc.)
• Imagenes JPEG embebidas (passthrough, sin re-encoding)
• Table helper para tablas formateadas
• Paginacion automatica (numeros de pagina, headers, footers)
• Links clickeables (URLs externas + links internos entre paginas)
• Colores RGB, CMYK, Grayscale

---

Estado Actual - v0.5

Funcionalidades Implementadas

Categoria	Funcionalidad	Estado
Documento
	Crear PDF 1.4	OK
	Metadatos (titulo, autor, etc.)	OK
	Multiples paginas	OK
	Tamanos estandar (A4, Letter, A3, A5, Legal)	OK
Texto
	drawText() - texto en posicion	OK
	cell() - celda con bordes/relleno	OK
	multiCell() - word wrap automatico	OK
	Alineacion (left, center, right)	OK
	14 fuentes Type1 standard	OK
Graficos
	Lineas	OK
	Rectangulos (stroke, fill)	OK
	Colores RGB/CMYK/Gray	OK
Imagenes
	JPEG embedding	OK
	image() / imageFit()	OK
	Aspect ratio preservation	OK
Tablas
	Table helper	OK
	header(), row(), footer()	OK
	Alineacion por columna	OK
	Estilos personalizados	OK
Paginacion
	Numeros de pagina	OK
	Headers automaticos	OK
	Footers automaticos	OK
	skip_pages option	OK
Links
	URL links clickeables	OK
	Internal page links	OK
	Visual styling (azul+subrayado)	OK
	Link annotations	OK

Tests y Ejemplos

• ~70 tests unitarios pasando
• 7 ejemplos funcionales:
  • hello.zig - PDF minimo
  • invoice.zig - Factura completa
  • text_demo.zig - Sistema de texto
  • image_demo.zig - Imagenes JPEG
  • table_demo.zig - Table helper
  • pagination_demo.zig - Paginacion multi-pagina
  • links_demo.zig - Links clickeables

---

Arquitectura

zpdf/
├── CLAUDE.md                 # Documentacion del proyecto
├── build.zig                 # Sistema de build
├── src/
│   ├── root.zig              # Exports publicos
│   ├── pdf.zig               # Pdf facade (API principal)
│   ├── page.zig              # Page + texto + links
│   ├── content_stream.zig    # Operadores PDF
│   ├── table.zig             # Table helper
│   ├── pagination.zig        # Paginacion, headers, footers
│   ├── links.zig             # Link types
│   ├── fonts/
│   │   └── type1.zig         # 14 fuentes Type1 + metricas
│   ├── graphics/
│   │   └── color.zig         # Color (RGB, CMYK, Gray)
│   ├── images/
│   │   ├── jpeg.zig          # JPEG parser
│   │   ├── png.zig           # PNG metadata
│   │   └── image_info.zig    # ImageInfo struct
│   ├── objects/
│   │   └── base.zig          # PageSize, Orientation
│   └── output/
│       └── producer.zig      # Serializa PDF + images + links
└── examples/
    ├── hello.zig
    ├── invoice.zig
    ├── text_demo.zig
    ├── image_demo.zig
    ├── table_demo.zig
    ├── pagination_demo.zig
    └── links_demo.zig

---

API Quick Reference

Documento Basico

const zpdf = @import("zpdf");

var doc = zpdf.Pdf.init(allocator, .{});
defer doc.deinit();

doc.setTitle("Mi Documento");
var page = try doc.addPage(.{});

try page.setFont(.helvetica_bold, 24);
try page.drawText(50, 750, "Hello, PDF!");

try doc.save("output.pdf");

Celdas y Tablas

// cell() simple
try page.cell(100, 20, "Hello", zpdf.Border.all, .center, true);

// multiCell con word wrap
try page.multiCell(400, null, texto_largo, zpdf.Border.none, .left, false);

// Table helper
const widths = [_]f32{ 200, 100, 100 };
var table = zpdf.Table.init(page, .{
    .col_widths = &widths,
});
try table.header(&.{ "Producto", "Qty", "Precio" });
try table.row(&.{ "Item A", "10", "$50" });
try table.footer(&.{ "Total", "", "$50" });

Imagenes

const img_idx = try doc.addJpegImageFromFile("foto.jpg");
const info = doc.getImage(img_idx).?;
try page.image(img_idx, info, 50, 500, 200, 150);

Links Clickeables

// URL link con visual styling
_ = try page.urlLink(100, 700, "Click aqui", "https://example.com");

// O desde posicion actual
_ = try page.writeUrlLink("Visitar web", "https://example.com");

// Link interno (saltar a pagina)
try page.addInternalLink(2, 100, 700, 150, 20);  // page 2

Paginacion

// Numeros de pagina
try zpdf.Pagination.addPageNumbers(&doc, .{
    .format = "Page {PAGE} of {PAGES}",
    .position = .bottom_center,
});

// Header con linea
try zpdf.addHeader(&doc, "Documento", .{
    .draw_line = true,
});

---

Comandos

# 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

# Ejemplos
./zig-out/bin/hello
./zig-out/bin/invoice
./zig-out/bin/text_demo
./zig-out/bin/image_demo
./zig-out/bin/table_demo
./zig-out/bin/pagination_demo
./zig-out/bin/links_demo

---

Roadmap Completado

Fase 1 - Core (COMPLETADO)

• Estructura PDF 1.4
• Paginas multiples
• Texto basico
• Graficos (lineas, rectangulos)
• Colores

Fase 2 - Texto Avanzado (COMPLETADO)

• cell() / cellAdvanced()
• multiCell() con word wrap
• Alineacion
• Bordes

Fase 3 - Imagenes (COMPLETADO)

• JPEG embedding
• image() / imageFit()
• PNG metadata (embedding pendiente)

Fase 4 - Utilidades (COMPLETADO)

• Table helper
• Paginacion
• Headers/Footers
• Links visuales

Fase 5 - Links Clickeables (COMPLETADO)

• URL annotations
• Internal page links
• Link annotations en PDF

Futuro (Opcional)

• PNG embedding completo
• Compresion de streams
• Fuentes TTF
• Bookmarks

---

Historial

2025-12-08 - v0.5 (Links Clickeables)

• Link annotations clickeables en PDF
• addUrlLink() / addInternalLink() en Page
• urlLink() / writeUrlLink() combinan visual + annotation
• OutputProducer genera /Annots en pages
• links_demo.zig ejemplo con 2 paginas
• 7 ejemplos, ~70 tests

2025-12-08 - v0.4 (Utilidades)

• Table helper
• Pagination (numeros de pagina)
• Headers/Footers automaticos
• Links visuales

2025-12-08 - v0.3 (Imagenes)

• JPEG embedding
• image() / imageFit()

2025-12-08 - v0.2 (Texto)

• cell() / multiCell()
• Word wrap, alineacion

2025-12-08 - v0.1 (Core)

• Estructura inicial

---

Equipo

/mnt/cello2/arno/re/recode/TEAM_STANDARDS/
git remote: git@git.reugenio.com:reugenio/zpdf.git

---

zpdf - Generador PDF para Zig v0.5 - Feature Complete - 2025-12-08