react-vector-pdf 0.5.1 → 0.6.1

package/README.md

@@ -16,8 +16,8 @@
 - **Advanced Components**:
   - **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**: 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, custom sizes, portrait/landscape orientation, distinct margins, base fonts.
   - **Headers & Footers**: Custom render functions with full control.
@@ -95,6 +95,76 @@ import { PdfPreview, PdfText } from "react-vector-pdf";
 
 **Note:** Changing props (like options, colors, fonts) will automatically regenerate and update the preview.
 
+## Styling with CSS Classes
+
+You can use standard CSS classes (including generic CSS or utility frameworks like **Tailwind CSS**) to style PDF components using the `className` prop. The library uses a special `useClassStyles` hook that renders a hidden DOM element to compute CSS styles and converts them into PDF-compatible properties.
+
+### Supported CSS Properties
+
+| CSS Property       | PDF Mapping   | Notes                            |
+| ------------------ | ------------- | -------------------------------- |
+| `color`            | `color`       | Supports hex and RGBA            |
+| `background-color` | `fillColor`   | Supports hex and RGBA            |
+| `font-size`        | `fontSize`    | Converted from px to points (pt) |
+| `font-weight`      | `fontStyle`   | ≥700 maps to 'bold'              |
+| `font-style`       | `fontStyle`   | Supports italic/bold/bolditalic  |
+| `text-align`       | `align`       | left/center/right/justify        |
+| `line-height`      | `lineHeight`  | Converted to multiplier          |
+| `padding-*`        | `padding`     | Converted from px to mm          |
+| `margin-*`         | `margin`      | Converted from px to mm          |
+| `border-width`     | `borderWidth` | Uniform borders only, px to mm   |
+| `border-color`     | `borderColor` | Supports hex and RGBA            |
+| `border-radius`    | `radius`      | Converted from px to mm          |
+| `gap`              | `gap`         | PdfView only, px to mm           |
+| `width`            | `width`       | Explicit widths, px to mm        |
+| `height`           | `height`      | Explicit heights, px to mm       |
+
+### Unsupported Properties
+
+The following CSS properties are **not supported** and will trigger console warnings if used:
+
+- `box-shadow`, `text-shadow`
+- `z-index`
+- `float`
+- `overflow`
+- `transform`
+- Layout properties: `display: flex/grid`, `position: absolute/fixed`
+
+> **Note**: PDF layout uses standard flow or absolute positioning. Complex CSS layout features like flexbox and grid are not available.
+
+### Usage Examples
+
+```tsx
+// Using Tailwind CSS classes
+<PdfText className="text-red-600 font-bold text-xl mb-4">
+  Styled with Tailwind!
+</PdfText>
+
+<PdfView className="border border-gray-300 p-4 bg-gray-50 rounded gap-4">
+  <PdfText className="text-gray-800">
+    This box uses utility classes for padding, border, and background.
+  </PdfText>
+  <PdfText>
+    Items inside this view are separated by a 1rem (approx 4mm) gap.
+  </PdfText>
+</PdfView>
+
+// Mixing className with direct props (direct props take precedence)
+<PdfText className="text-blue-500" color="#FF0000">
+  This text will be red, not blue
+</PdfText>
+```
+
+### How It Works
+
+The library:
+
+1. Creates a hidden `<div>` element with the provided `className`
+2. Uses `getComputedStyle()` to read the final computed CSS values
+3. Converts pixel values to PDF units (mm for dimensions, pt for fonts)
+4. Maps CSS properties to PDF renderer properties
+5. Validates and warns about unsupported properties
+
 ## Components
 
 ### 1. `PdfDocument`
@@ -125,6 +195,8 @@ Renders a paragraph of text. Automatically wraps to the content width.
 - `align` ('left' | 'center' | 'right' | 'justify'): Text alignment.
 - `lineHeight` (number): Line height multiplier.
 - `spacingBelow` (number): Vertical space (mm) to add after the paragraph.
+- `className` (string): CSS class names for styling (supports Tailwind and other frameworks).
+- `style` (React.CSSProperties): Inline styles object.
 - `showInAllPages` (boolean): Make this text appear on multiple pages.
 - `scope` ('all' | 'first-only' | 'except-first' | number[]): Which pages to show on.
 
@@ -171,6 +243,8 @@ A robust table component designed for dynamic data.
 - `cellPadding`: Default padding for cells (number or object).
 - `striped` (boolean): Enable alternating row colors.
 - `repeatHeader` (boolean): Repeat header on each page (default: true).
+- `className` (string): CSS class names for styling.
+- `style` (React.CSSProperties): Inline styles object.
 
 **Complex Cell Example:**
 
@@ -223,6 +297,8 @@ Embed images (JPEG/PNG).
 - `align` ('left' | 'center' | 'right'): Horizontal alignment (flow mode only).
 - `layout` ('fixed' | 'flow'): Layout mode (default: 'fixed').
 - `sizing` ('fit' | 'fill' | 'auto'): How to size the image (default: 'fit').
+- `className` (string): CSS class names for styling.
+- `style` (React.CSSProperties): Inline styles object.
 - `showInAllPages` (boolean): Make this image appear on multiple pages.
 - `scope` ('all' | 'first-only' | 'except-first' | number[]): Which pages to show on.
 
@@ -252,7 +328,8 @@ A container component for grouping content, adding borders, backgrounds, or marg
 
 **Props:**
 
-- `style`: Object with `margin`, `padding` (granular: `marginTop`, `paddingLeft` etc.), `borderWidth`, `borderColor`, `fillColor`, `radius`.
+- `style`: Object with `margin`, `padding` (granular: `marginTop`, `paddingLeft` etc.), `borderWidth`, `borderColor`, `fillColor`, `radius`, `gap`.
+- `className` (string): CSS class names for styling (supports gap, padding, margin, borders, backgrounds).
 - `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.
@@ -284,6 +361,7 @@ Renders bulleted or numbered lists.
 - `indent`: Number (mm) for indentation. Default 5.
 - `markerWidth`: Number (mm) for the marker area. Default 5.
 - `spacing`: Number (mm) for space between items. Default 2.
+- `className` (string): CSS class names for styling list items.
 - `style`: TextStyle object for the list items.
 
 ```tsx

package/dist/index.d.ts

@@ -18,6 +18,7 @@ export declare interface BoxStyle {
     paddingRight?: number;
     paddingBottom?: number;
     paddingLeft?: number;
+    gap?: number;
 }
 
 export declare interface CenterLabelOptions {
@@ -84,6 +85,8 @@ declare interface PdfImageProps {
     align?: "left" | "center" | "right";
     showInAllPages?: boolean;
     scope?: "all" | "first-only" | "except-first" | number[];
+    className?: string;
+    style?: default_2.CSSProperties;
 }
 
 export declare const PdfList: default_2.FC<PdfListProps>;
@@ -95,6 +98,7 @@ declare interface PdfListProps {
     indent?: number;
     markerWidth?: number;
     spacing?: number;
+    className?: string;
 }
 
 export declare interface PDFOptions {
@@ -135,7 +139,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;
@@ -143,9 +153,14 @@ export declare class PdfRenderer {
     private footerDrawer?;
     private pendingTasks;
     private opQueue;
-    private generation;
+    generation: number;
+    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;
@@ -153,6 +168,15 @@ export declare class PdfRenderer {
     get contentRight(): number;
     get contentTop(): number;
     get contentBottom(): number;
+    private indentStack;
+    private currentIndent;
+    pushIndent(left: number, right: number): void;
+    popIndent(): void;
+    /**
+     * Returns the top Y position for content on a given page, accounting for recurring items.
+     * This is useful for drawing background boxes that shouldn't overlap headers.
+     */
+    getSafeContentTop(pageNum: number): number;
     get contentHeight(): number;
     get contentAreaWidth(): number;
     get baseFont(): {
@@ -161,6 +185,14 @@ export declare class PdfRenderer {
         size: number;
     };
     get baseLineHeight(): number;
+    private verticalPaddingStack;
+    pushVerticalPadding(top: number, bottom: number): void;
+    popVerticalPadding(): void;
+    get currentVerticalPadding(): {
+        top: number;
+        bottom: number;
+    };
+    setReservedHeight(h: number): 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;
@@ -178,6 +210,7 @@ export declare class PdfRenderer {
         h?: number;
         mime?: "PNG" | "JPEG";
         align?: "left" | "center" | "right";
+        radius?: number;
     }): Promise<{
         width: number;
         height: number;
@@ -215,6 +248,21 @@ 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, radius?: number | {
+        tl?: number;
+        tr?: number;
+        br?: number;
+        bl?: number;
+    }): void;
 }
 
 export declare const PdfTable: default_2.FC<PdfTableProps>;
@@ -237,6 +285,9 @@ declare interface PdfTableProps {
     headerHeight?: number;
     repeatHeader?: boolean;
     striped?: boolean;
+    className?: string;
+    style?: default_2.CSSProperties;
+    stripeColor?: string;
 }
 
 export declare const PdfText: default_2.FC<PdfTextProps>;
@@ -247,18 +298,23 @@ declare interface PdfTextProps extends TextStyle {
     y?: number;
     maxWidth?: number;
     spacingBelow?: number;
+    className?: string;
+    style?: default_2.CSSProperties;
 }
 
 export declare const PdfView: default_2.FC<PdfViewProps>;
 
 declare interface PdfViewProps {
-    style?: ViewStyle;
+    style?: ViewStyle | default_2.CSSProperties;
+    className?: string;
     children?: default_2.ReactNode;
     debug?: boolean;
     x?: number;
     y?: number;
     w?: number;
     h?: number;
+    showInAllPages?: boolean;
+    scope?: "all" | "first-only" | "except-first" | number[];
 }
 
 declare interface TableColumn {

package/dist/react-vector-pdf.css

@@ -0,0 +1 @@
+.pdf-preview-hidden{display:none!important}.pdf-preview-iframe{border:none}.pdf-preview-placeholder{width:100%;height:100%;display:flex;align-items:center;justify-content:center;background-color:#f3f4f6;color:#6b7280}