pols-pdf 1.1.3 → 1.2.0

package/README.md

@@ -110,7 +110,7 @@ pdf.rectangle({
 pdf.cell({
 	text: 'Texto de la celda',
 	width: 200,
-	height: 40,                 // o autojump: true si no se conoce el alto de antemano
+	height: 40,                 // opcional: si se omite, el alto se calcula según el contenido
 	padding: 6,
 	hAlign: 'center',
 	vAlign: 'center',
@@ -122,11 +122,12 @@ pdf.cell({
 
 - `text` acepta `string`, `number`, `null`/`undefined`, un objeto `{ chars, font? }`, o un arreglo
   de estos últimos para mezclar fuentes/estilos dentro de una misma celda.
-- Una celda necesita **o bien** `height` (alto fijo) **o bien** `autojump: true` (el alto se
-  calcula según el contenido y, si no entra en la página actual, el texto restante continúa
-  automáticamente en una página nueva).
-- Si el contenido no entra en la página, `cell()` agrega una página nueva y continúa dibujando el
-  resto automáticamente.
+- Una celda admite `height` (alto fijo) **o** `autojump` (opcional, `boolean`, por defecto `true`):
+  con `autojump` el alto se calcula según el contenido y, si no entra en la página actual, el
+  texto restante continúa automáticamente en una página nueva. Pasar `autojump: false` desactiva
+  ese salto automático (el contenido que no entre se recorta al borde de la página).
+- Si el contenido no entra en la página (con `autojump` activo, que es el default), `cell()`
+  agrega una página nueva y continúa dibujando el resto automáticamente.
 
 ---
 
@@ -193,6 +194,25 @@ Cambia la fuente activa del documento; los métodos de texto (`cell`, `row`, `ta
 aceptan `font` por llamada (y por fragmento de texto individual dentro de `text`), sin necesidad
 de llamar a `setFont` explícitamente.
 
+`font` se hereda en cascada — tabla → fila → celda → fragmento de texto — y cada nivel solo
+sobrescribe las propiedades que declara explícitamente, heredando el resto del nivel anterior. Por
+ejemplo, en:
+
+```typescript
+pdf.table({
+	font: { size: '80%' },
+	rows: [{
+		cells: [
+			{ text: 'Solped:', font: { bold: true }, weight: 1 },
+			{ text: '12345', weight: 3 },
+		]
+	}]
+})
+```
+
+la celda `'Solped:'` se dibuja en **negrita y al 80% del tamaño de fuente activo**: `bold: true`
+la define la celda, pero `size: '80%'` lo hereda de la tabla porque la celda no lo redefine.
+
 ---
 
 ## Tipos con forma abreviada (`*Params`)
@@ -211,6 +231,8 @@ completo:
 
 ## Convención de nombres
 
-Todas las clases y tipos exportados llevan el prefijo `P` (`PPdf`, `PCell`, `PRowParams`, etc.),
-siguiendo la convención usada en los paquetes hermanos de este ecosistema: `pols-date` (`PDate`)
-y `pols-utils` (`PRecord`, `PUtilsNumber`).
+Todas las clases y tipos exportados llevan el prefijo `P` (`PPdf`, `PCellParams`, `PRowParams`,
+etc.), siguiendo la convención usada en los paquetes hermanos de este ecosistema: `pols-date`
+(`PDate`) y `pols-utils` (`PRecord`, `PUtilsNumber`). Los tipos ya resueltos que usa el motor de
+layout internamente (`PCellCompiled`, `PRowCompiled`, `PTableCompiled`, etc.) llevan el sufijo
+`Compiled` y no se exportan — no forman parte de la API pública.

package/dist/index.d.ts

@@ -31,10 +31,17 @@ export type PBorderColorParams = string | {
     left?: string;
     leftTop?: string;
 };
+export type PPageMarginsParams = number | {
+    top?: number;
+    bottom?: number;
+    left?: number;
+    right?: number;
+    show?: boolean;
+};
 export type PPage = {
     size: 'A4' | 'LETTER';
     layout: 'portrait' | 'landscape';
-    margins: PBoundParams;
+    margins: PPageMarginsParams;
 };
 export type PFont = {
     name: string;
@@ -176,6 +183,7 @@ export declare class PPdf {
         addFirstPage?: boolean;
     });
     addPage(config?: Partial<PPage>): void;
+    private drawMarginLines;
     rectangleTo(params: Omit<PRectangle, 'width' | 'height'>): void;
     rectangle(params: PRectangle): void;
     build(): PDFKit.PDFDocument;
@@ -198,6 +206,7 @@ export declare class PPdf {
     cell(params: PCellParams): void;
     image(params: PImage): void;
     private prepareBoundValues;
+    private prepareMarginsValues;
     private prepareRadiusValues;
     private prepareBorderValues;
     private prepareBorderColorValues;

package/dist/index.js

@@ -95,11 +95,12 @@ class PPdf {
             size: 'A4',
             layout: 'portrait',
             ...(params?.page ?? {}),
-            margins: this.prepareBoundValues(params?.page?.margins, {
+            margins: this.prepareMarginsValues(params?.page?.margins, {
                 left: 20,
                 top: 20,
                 right: 20,
-                bottom: 20
+                bottom: 20,
+                show: false
             })
         };
         if (params?.addFirstPage == null || params.addFirstPage)
@@ -109,18 +110,25 @@ class PPdf {
         const finalConfig = {
             ...this.configPage,
             ...(config ?? {}),
-            margins: this.prepareBoundValues(config?.margins ?? this.configPage.margins, {
-                left: 20,
-                top: 20,
-                right: 20,
-                bottom: 20
-            })
+            margins: this.prepareMarginsValues(config?.margins ?? this.configPage.margins, this.configPage.margins)
         };
         this.engine.addPage(finalConfig);
         this.configPage = finalConfig;
         this.cursor.top = finalConfig.margins.top;
+        this.drawMarginLines();
         this.template?.();
     }
+    /* Dibuja líneas grises en los márgenes de la hoja actual, sin alterar el cursor */
+    drawMarginLines() {
+        if (!this.configPage.margins.show)
+            return;
+        const left = this.configPage.margins.left;
+        const top = this.configPage.margins.top;
+        const right = this.engine.page.width - this.configPage.margins.right;
+        const bottom = this.engine.page.height - this.configPage.margins.bottom;
+        this.engine.lineWidth(0.5);
+        this.engine.path(`M${left},${top} L${right},${top} L${right},${bottom} L${left},${bottom} Z`).stroke('#999999');
+    }
     rectangleTo(params) {
         this.rectangle({
             ...params,
@@ -374,6 +382,9 @@ class PPdf {
         if (value == 'left') {
             n = this.engine.page.margins.left;
         }
+        else if (value < 0) {
+            n = this.engine.page.width + value;
+        }
         else {
             n = value;
         }
@@ -389,6 +400,9 @@ class PPdf {
         if (value == 'top') {
             n = this.engine.page.margins.top;
         }
+        else if (value < 0) {
+            n = this.engine.page.height + value;
+        }
         else {
             n = value;
         }
@@ -683,7 +697,12 @@ class PPdf {
             left: params.left,
             pdf: this
         });
-        let paramsToDraw = { ...params, width };
+        const left = params.left ?? this.cursor.left;
+        let paramsToDraw = {
+            ...params,
+            width,
+            left
+        };
         while (paramsToDraw) {
             const prepared = this.prepareCell(paramsToDraw);
             this.drawCell(prepared.currentPage);
@@ -698,6 +717,7 @@ class PPdf {
                 paramsToDraw = null;
             }
         }
+        this.setCursorLeftPosition(left);
     }
     image(params) {
         const options = {};
@@ -751,6 +771,12 @@ class PPdf {
             return defa;
         }
     }
+    prepareMarginsValues(value, defa) {
+        return {
+            ...this.prepareBoundValues(value, defa),
+            show: (typeof value == 'object' ? value.show : undefined) ?? defa.show,
+        };
+    }
     prepareRadiusValues(value, defa = {
         leftTop: 0,
         leftBottom: 0,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pols-pdf",
-	"version": "1.1.3",
+	"version": "1.2.0",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
 	"scripts": {