react-vector-pdf 0.5.0 → 0.6.0

package/README.md

@@ -14,16 +14,18 @@
   - **Auto-Paging**: Content that exceeds the page height automatically moves to the next page.
   - **Flow & Absolute Positioning**: Stack elements naturally or place them at fixed coordinates.
 - **Advanced Components**:
-  - **PdfTable**: Supports auto-wrapping, **row spans**, **col spans**, **vertical alignment**, custom cell styling, and **intelligent page breaking** (keeps spanned rows together).
+  - **PdfTable**: Supports auto-wrapping, **row spans**, **col spans**, **vertical alignment**, custom cell styling, **striped rows**, and **intelligent page breaking** (keeps spanned rows together).
   - **PdfImage**: Renders images from URLs with options for flow or absolute positioning. Automatically handles page breaks in flow mode.
-  - **PdfList**: Bullet and numbered lists with auto-wrapping.
-  - **PdfView/PdfBox**: Container components with support for borders, background colors, and granular **padding/margin** (e.g., `paddingTop`, `marginBottom`).
+  - **PdfList**: Bullet and numbered lists with auto-wrapping and **orphan protection**.
+  - **PdfView**: Advanced container with **perfect multi-page spanning**, support for borders, background colors (rendered strictly behind content), and granular **persistent padding** (padding is maintained across page breaks).
 - **Global Document Options**:
-  - **Formatting**: A4, Letter, distinct margins, base fonts.
-  - **Headers & Footers**: Custom render functions.
+  - **Formatting**: A4, Letter, custom sizes, portrait/landscape orientation, distinct margins, base fonts.
+  - **Headers & Footers**: Custom render functions with full control.
   - **Page Numbering**: Highly configurable (presets, templates, scopes, formats like Roman/Arabic).
   - **Center Labels**: Watermarks or classification labels in header/footer.
   - **Metadata**: Set PDF title, author, subject, and keywords.
+- **Recurring Elements**: Make any component appear on all pages or specific pages using `showInAllPages` and `scope`.
+- **TypeScript**: Written in TypeScript with complete type definitions.
 
 ## Installation
 
@@ -48,10 +50,18 @@ const MyPdf = () => {
     <PdfDocument
       onReady={handleSave}
       options={{
+        format: "a4", // or "letter", or [width, height] in mm
+        orientation: "p", // "p" for portrait, "l" for landscape
         margin: { top: 20, right: 15, bottom: 15, left: 15 },
-        font: { size: 12, name: "helvetica" }, // default font
+        font: { size: 12, name: "helvetica" },
         lineHeight: 1.25,
       }}
+      metadata={{
+        title: "My Document",
+        author: "Your Name",
+        subject: "Document Subject",
+        keywords: ["pdf", "react"],
+      }}
     >
       <PdfText fontSize={18} fontStyle="bold" spacingBelow={10}>
         Hello World
@@ -82,14 +92,28 @@ import { PdfPreview, PdfText } from "react-vector-pdf";
 - `height` (string | number): Height of the container (default "100%").
 - `className` / `style`: Styling for the wrapper div.
 - `iframeClassName` / `iframeStyle`: Styling for the internal iframe.
-  83:
-  84: **Note:** Changing props (like options, colors, fonts) will automatically regenerate and update the preview.
-  85:
-  86: ## Components
+
+**Note:** Changing props (like options, colors, fonts) will automatically regenerate and update the preview.
 
 ## Components
 
-### 1. `PdfText`
+### 1. `PdfDocument`
+
+The main wrapper component that provides context and handles PDF generation.
+
+**Props:**
+
+- `options`: PDF configuration (format, margins, fonts, etc.)
+- `metadata`: Document metadata (title, author, subject, keywords)
+- `header`: Custom header render function `(renderer, page, total) => void`
+- `footer`: Custom footer render function `(renderer, page, total) => void`
+- `pageNumbers`: Page numbering configuration
+- `centerLabel`: Center label/watermark configuration
+- `onReady`: Callback when PDF is ready `(renderer) => void`
+- `filename`: Filename for auto-save
+- `autoSave`: Automatically save PDF when rendered (default: false)
+
+### 2. `PdfText`
 
 Renders a paragraph of text. Automatically wraps to the content width.
 
@@ -97,10 +121,12 @@ Renders a paragraph of text. Automatically wraps to the content width.
 
 - `fontSize` (number): Font size in points.
 - `fontStyle` ('normal' | 'bold' | 'italic' | 'bolditalic'): Font style.
-- `color` (string): Hex color code (e.g., "#FF0000").
+- `color` (string): Hex color (e.g., "#FF0000") or RGBA (e.g., "rgba(255, 0, 0, 0.5)").
 - `align` ('left' | 'center' | 'right' | 'justify'): Text alignment.
 - `lineHeight` (number): Line height multiplier.
 - `spacingBelow` (number): Vertical space (mm) to add after the paragraph.
+- `showInAllPages` (boolean): Make this text appear on multiple pages.
+- `scope` ('all' | 'first-only' | 'except-first' | number[]): Which pages to show on.
 
 ```tsx
 <PdfText
@@ -111,10 +137,17 @@ Renders a paragraph of text. Automatically wraps to the content width.
   spacingBelow={5}
 >
   I am a centered, bold heading.
-</PdfText>
+</PdfText>;
+
+{
+  /* Recurring header on all pages except first */
+}
+<PdfText showInAllPages scope="except-first" fontSize={10} color="#666">
+  Document Header
+</PdfText>;
 ```
 
-### 2. `PdfTable`
+### 3. `PdfTable`
 
 A robust table component designed for dynamic data.
 
@@ -125,6 +158,8 @@ A robust table component designed for dynamic data.
 - **Page Breaking**: Smartly handles page breaks, ensuring rows with rowspans are kept together if possible.
 - **Styling**: Supports granular padding (`paddingTop`, `paddingLeft`, etc.) and borders.
 - **Alignment**: Supports both horizontal (`align`) and vertical (`verticalAlign`) alignment.
+- **Striped Rows**: Alternating row colors for better readability.
+- **Header Repeat**: Optionally repeat header row on each page.
 
 **Props:**
 
@@ -134,12 +169,18 @@ A robust table component designed for dynamic data.
 - `borderWidth`, `borderColor`: Global table border settings.
 - `headerStyle`, `rowStyle`: Default styles for headers and rows.
 - `cellPadding`: Default padding for cells (number or object).
+- `striped` (boolean): Enable alternating row colors.
+- `repeatHeader` (boolean): Repeat header on each page (default: true).
 
 **Complex Cell Example:**
 
 ```tsx
 <PdfTable
   width="100%"
+  striped={true}
+  repeatHeader={true}
+  borderWidth={0.5}
+  headerStyle={{ fillColor: "#f3f4f6", fontStyle: "bold" }}
   columns={[
     { header: "ID", accessor: "id", width: 10 },
     { header: "Description", accessor: "desc", width: "auto" },
@@ -151,7 +192,7 @@ A robust table component designed for dynamic data.
 
     // Row with Spans and Custom Styles
     {
-      id: "2", // Simple cell
+      id: "2",
       desc: {
         content: "I span 2 rows and am vertically centered",
         rowSpan: 2,
@@ -170,7 +211,7 @@ A robust table component designed for dynamic data.
 />
 ```
 
-### 3. `PdfImage`
+### 4. `PdfImage`
 
 Embed images (JPEG/PNG).
 
@@ -180,15 +221,32 @@ Embed images (JPEG/PNG).
 - `x`, `y` (number): Optional fixed coordinates. If omitted, uses **flow layout**.
 - `w`, `h` (number): Explicit dimensions. If only one is provided, aspect ratio is maintained.
 - `align` ('left' | 'center' | 'right'): Horizontal alignment (flow mode only).
-- `flow` (boolean): Force flow mode if necessary.
+- `layout` ('fixed' | 'flow'): Layout mode (default: 'fixed').
+- `sizing` ('fit' | 'fill' | 'auto'): How to size the image (default: 'fit').
+- `showInAllPages` (boolean): Make this image appear on multiple pages.
+- `scope` ('all' | 'first-only' | 'except-first' | number[]): Which pages to show on.
 
 **Flow Behavior**: In flow mode, if an image is too tall for the remaining page space, it will automatically trigger a page break and render on the next page.
 
 ```tsx
-<PdfImage src="https://example.com/logo.png" h={20} align="center" />
+{
+  /* Flow layout with auto-sizing */
+}
+<PdfImage
+  src="https://example.com/logo.png"
+  h={20}
+  align="center"
+  layout="flow"
+  sizing="fit"
+/>;
+
+{
+  /* Recurring logo on all pages */
+}
+<PdfImage src="logo.png" h={15} showInAllPages scope="all" x={10} y={10} />;
 ```
 
-### 4. `PdfView`
+### 5. `PdfView`
 
 A container component for grouping content, adding borders, backgrounds, or margins/padding. It is the primary container for both flow and absolute layouts.
 
@@ -197,6 +255,8 @@ A container component for grouping content, adding borders, backgrounds, or marg
 - `style`: Object with `margin`, `padding` (granular: `marginTop`, `paddingLeft` etc.), `borderWidth`, `borderColor`, `fillColor`, `radius`.
 - `x`, `y`, `w`, `h`: Optional props for **absolute positioning**. If provided, the view will be placed at exactly these coordinates.
 - `children`: Nested components to render inside the view.
+- `showInAllPages` (boolean): Make this view appear on multiple pages.
+- `scope` ('all' | 'first-only' | 'except-first' | number[]): Which pages to show on.
 
 ```tsx
 <PdfView
@@ -206,13 +266,14 @@ A container component for grouping content, adding borders, backgrounds, or marg
     padding: 5,
     borderWidth: 0.2,
     borderColor: "#ccc",
+    fillColor: "rgba(240, 240, 240, 0.5)",
   }}
 >
   <PdfText>Content inside a styled box.</PdfText>
 </PdfView>
 ```
 
-### 5. `PdfList`
+### 6. `PdfList`
 
 Renders bulleted or numbered lists.
 
@@ -230,7 +291,7 @@ Renders bulleted or numbered lists.
   ordered={true}
   indent={10}
   spacing={3}
-  items={["First item", "Second item"]}
+  items={["First item", "Second item", "Third item"]}
 />
 ```
 
@@ -247,10 +308,13 @@ Automatically adds page numbers to every page (or specific pages) with full cust
   pageNumbers={{
     enabled: true,
     position: "footer",       // 'header' | 'footer'
-    align: "right",
-    format: "page-slash-total", // 'Page 1/10', '1/10', 'Page 1 of 10'
-    scope: "except-first",    // 'all' | 'first-only' | 'except-first' | 'custom'
-    template: "Pg {page} / {total}", // Custom template support
+    align: "right",           // 'left' | 'center' | 'right'
+    preset: "page-slash-total", // 'Page 1/10', '1/10', 'Page 1 of 10'
+    scope: "except-first",    // 'all' | 'first-only' | 'except-first' | [2,3,5]
+    template: "Pg {page} / {total}", // Custom template (overrides preset)
+    format: "arabic",         // 'arabic' | 'roman-upper' | 'roman-lower'
+    y: 285,                   // Custom Y position (optional)
+    offsetX: 0,               // X offset from alignment (optional)
     style: { fontSize: 9, color: "#666" }
   }}
 >
@@ -265,13 +329,171 @@ Adds a centered label (e.g., "CONFIDENTIAL") to the header or footer area.
   centerLabel={{
     enabled: true,
     text: "CONFIDENTIAL",
-    position: "header",
-    scope: "all",
+    position: "header",       // 'header' | 'footer'
+    scope: "all",             // 'all' | 'first-only' | 'except-first' | [2,3,5]
+    y: 10,                    // Custom Y position (optional)
+    offsetX: 0,               // X offset (optional)
     style: { color: "red", fontSize: 12 }
   }}
 >
 ```
 
+### Custom Headers & Footers
+
+For complete control, use custom render functions:
+
+```tsx
+<PdfDocument
+  header={(renderer, page, total) => {
+    const pdf = renderer.instance;
+
+    // Set font and color
+    pdf.setFontSize(10);
+    pdf.setTextColor("#333");
+
+    // Draw custom header
+    pdf.text("My Company", renderer.contentLeft, 10);
+    pdf.text(`Page ${page}`, renderer.contentRight, 10, { align: 'right' });
+
+    // Draw a line
+    pdf.setDrawColor("#e5e7eb");
+    pdf.setLineWidth(0.5);
+    pdf.line(renderer.contentLeft, 12, renderer.contentRight, 12);
+  }}
+  footer={(renderer, page, total) => {
+    const pdf = renderer.instance;
+    const y = renderer.height - 10;
+
+    pdf.setFontSize(9);
+    pdf.setTextColor("#666");
+    pdf.text("© 2024 My Company", renderer.contentLeft, y);
+  }}
+>
+```
+
+### Metadata
+
+Set PDF document metadata for better organization and searchability:
+
+```tsx
+<PdfDocument
+  metadata={{
+    title: "Annual Report 2024",
+    author: "John Doe",
+    subject: "Financial Analysis",
+    keywords: ["finance", "report", "2024", "analysis"]
+  }}
+>
+```
+
+### Page Format & Orientation
+
+Configure page size and orientation:
+
+```tsx
+<PdfDocument
+  options={{
+    format: "a4",           // "a4", "letter", or custom [width, height] in mm
+    orientation: "p",       // "p" for portrait, "l" for landscape
+    margin: { top: 20, right: 15, bottom: 15, left: 15 },
+  }}
+>
+
+{/* Custom page size */}
+<PdfDocument
+  options={{
+    format: [210, 297],     // Custom size in mm (width, height)
+    orientation: "p",
+  }}
+>
+```
+
+## Advanced Features
+
+### Recurring Items
+
+Make any component appear on multiple pages using `showInAllPages` and `scope`:
+
+```tsx
+{
+  /* Appear on all pages */
+}
+<PdfText showInAllPages scope="all">
+  This appears on every page
+</PdfText>;
+
+{
+  /* Appear on all pages except the first */
+}
+<PdfImage
+  src="logo.png"
+  showInAllPages
+  scope="except-first"
+  x={10}
+  y={10}
+  h={15}
+/>;
+
+{
+  /* Appear only on first page */
+}
+<PdfView showInAllPages scope="first-only">
+  <PdfText>Cover page content</PdfText>
+</PdfView>;
+
+{
+  /* Appear on specific pages */
+}
+<PdfText showInAllPages scope={[2, 3, 5]}>
+  This appears only on pages 2, 3, and 5
+</PdfText>;
+```
+
+### RGBA Color Support
+
+All color props support both hex and RGBA formats:
+
+```tsx
+<PdfText color="#FF0000">Red text</PdfText>
+<PdfText color="rgba(255, 0, 0, 0.5)">Semi-transparent red text</PdfText>
+
+<PdfView style={{ fillColor: "rgba(0, 0, 255, 0.1)" }}>
+  <PdfText>Content with semi-transparent blue background</PdfText>
+</PdfView>
+```
+
+### Auto-Save
+
+Automatically save the PDF when it's generated:
+
+```tsx
+<PdfDocument filename="my-document.pdf" autoSave={true}>
+  {/* PDF will automatically download when rendered */}
+</PdfDocument>
+```
+
+## TypeScript Support
+
+This library is written in TypeScript and includes complete type definitions. All components and props are fully typed for the best developer experience.
+
+```tsx
+import { PdfDocument, PdfText, PdfDocumentProps } from "react-vector-pdf";
+
+const MyComponent: React.FC = () => {
+  const pdfOptions: PdfDocumentProps["options"] = {
+    format: "a4",
+    orientation: "p",
+    margin: { top: 20, right: 15, bottom: 15, left: 15 },
+  };
+
+  return (
+    <PdfDocument options={pdfOptions}>
+      <PdfText>Fully typed!</PdfText>
+    </PdfDocument>
+  );
+};
+```
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -135,7 +135,13 @@ export declare class PdfRenderer {
     private cursorX;
     private cursorY;
     private contentWidth;
-    private margin;
+    private reservedBottomHeight;
+    margin: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
     private defaultFont;
     private defaultColor;
     private defaultLineHeight;
@@ -144,8 +150,13 @@ export declare class PdfRenderer {
     private pendingTasks;
     private opQueue;
     private generation;
+    private recordingStack;
     private recurringItems;
     constructor(opts?: PDFOptions);
+    startRecording(): void;
+    stopRecording(): (() => void)[];
+    playback(ops: Array<() => void>): void;
+    private drawOp;
     get instance(): jsPDF;
     get width(): number;
     get height(): number;
@@ -161,6 +172,11 @@ export declare class PdfRenderer {
         size: number;
     };
     get baseLineHeight(): number;
+    setReservedHeight(h: number): void;
+    private indentStack;
+    private currentIndent;
+    pushIndent(left: number, right: number): void;
+    popIndent(): void;
     resetFlowCursor(): void;
     reset(): void;
     setHeaderFooter(header?: (pdf: jsPDF, pageNum: number, pageCount: number, renderer: PdfRenderer) => void, footer?: (pdf: jsPDF, pageNum: number, pageCount: number, renderer: PdfRenderer) => void): void;
@@ -215,6 +231,16 @@ export declare class PdfRenderer {
     }): void;
     save(filename: string): void;
     getBlobUrl(): URL;
+    /**
+     * Injects a filled rectangle at the beginning of the page stream.
+     * This ensures the background is drawn BEHIND all other content on the page.
+     */
+    injectFill(pageNum: number, rect: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    }, color: string): void;
 }
 
 export declare const PdfTable: default_2.FC<PdfTableProps>;