react-vector-pdf 0.3.1

package/README.md

@@ -0,0 +1,254 @@
+# react-vector-pdf
+
+**Vector-based, React-driven PDF generation.**
+
+`react-vector-pdf` is a React wrapper around **jsPDF** that allows you to build complex, multi-page PDFs using declarative React components. Unlike HTML-to-Canvas solutions, this library renders **selectable, searchable vector text**, resulting in smaller file sizes and crystal-clear output at any zoom level.
+
+## Features
+
+- **Vector Text**: High-quality, selectable, and searchable text (no canvas rasterization).
+- **React Component API**: Build PDFs using declarative components like `<PdfDocument>`, `<PdfText>`, `<PdfTable>`, `<PdfView>`, etc.
+- **Smart Layout Engine**:
+  - **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).
+  - **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`).
+- **Global Document Options**:
+  - **Formatting**: A4, Letter, distinct margins, base fonts.
+  - **Headers & Footers**: Custom render functions.
+  - **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.
+
+## Installation
+
+```bash
+npm install react-vector-pdf
+```
+
+## Quick Start
+
+Wrap your application in the `PdfDocument` component. This component serves as the context provider and renderer.
+
+```tsx
+import React from "react";
+import { PdfDocument, PdfText, PdfTable } from "pdfify-core";
+
+const MyPdf = () => {
+  const handleSave = (pdf) => {
+    pdf.save("my-document.pdf");
+  };
+
+  return (
+    <PdfDocument
+      onReady={handleSave}
+      options={{
+        margin: { top: 20, right: 15, bottom: 15, left: 15 },
+        font: { size: 12, name: "helvetica" }, // default font
+        lineHeight: 1.25,
+      }}
+    >
+      <PdfText fontSize={18} fontStyle="bold" spacingBelow={10}>
+        Hello World
+      </PdfText>
+
+      <PdfText>This is a vector PDF generated from React components.</PdfText>
+    </PdfDocument>
+  );
+};
+```
+
+## Components
+
+### 1. `PdfText`
+
+Renders a paragraph of text. Automatically wraps to the content width.
+
+**Props:**
+
+- `fontSize` (number): Font size in points.
+- `fontStyle` ('normal' | 'bold' | 'italic' | 'bolditalic'): Font style.
+- `color` (string): Hex color code (e.g., "#FF0000").
+- `align` ('left' | 'center' | 'right' | 'justify'): Text alignment.
+- `lineHeight` (number): Line height multiplier.
+- `spacingBelow` (number): Vertical space (mm) to add after the paragraph.
+
+```tsx
+<PdfText
+  fontSize={14}
+  fontStyle="bold"
+  color="#333333"
+  align="center"
+  spacingBelow={5}
+>
+  I am a centered, bold heading.
+</PdfText>
+```
+
+### 2. `PdfTable`
+
+A robust table component designed for dynamic data.
+
+**Key Features:**
+
+- **Auto-layout**: Columns can use explicit widths or percentage-based widths.
+- **Spanning**: Support for `rowSpan` and `colSpan`.
+- **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.
+
+**Props:**
+
+- `data`: Array of objects or cell definitions.
+- `columns`: Array of column definitions `{ header, accessor, width, align }`.
+- `width`: Table width (number or string percentage like "100%").
+- `borderWidth`, `borderColor`: Global table border settings.
+- `headerStyle`, `rowStyle`: Default styles for headers and rows.
+- `cellPadding`: Default padding for cells (number or object).
+
+**Complex Cell Example:**
+
+```tsx
+<PdfTable
+  width="100%"
+  columns={[
+    { header: "ID", accessor: "id", width: 10 },
+    { header: "Description", accessor: "desc", width: "auto" },
+    { header: "Price", accessor: "price", width: 20, align: "right" },
+  ]}
+  data={[
+    // Simple Row
+    { id: 1, desc: "Standard Item", price: "$10.00" },
+
+    // Row with Spans and Custom Styles
+    {
+      id: "2", // Simple cell
+      desc: {
+        content: "I span 2 rows and am vertically centered",
+        rowSpan: 2,
+        style: {
+          fillColor: "#e0f2fe",
+          align: "center",
+          verticalAlign: "middle", // 'top' | 'middle' | 'bottom'
+          paddingTop: 5,
+        },
+      },
+      price: "$20.00",
+    },
+    // Next row must account for the rowspan above
+    { id: 3, desc: null, price: "$5.00" },
+  ]}
+/>
+```
+
+### 3. `PdfImage`
+
+Embed images (JPEG/PNG).
+
+**Props:**
+
+- `src` (string): URL or Base64 data of the image.
+- `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.
+
+**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" />
+```
+
+### 4. `PdfView` & `PdfBox`
+
+Containers for grouping content, adding borders, backgrounds, or margins/padding.
+
+`PdfView` is akin to a block-level `div`, and `PdfBox` is similar but allows explicit positioning.
+
+**Styling Support:**
+
+- `margin` / `padding`: Shorthand (number or object `{top, right...}`).
+- **Granular Props**: `marginTop`, `marginBottom`, `paddingLeft`, `paddingRight`, etc.
+- `borderWidth`, `borderColor`: Draw borders.
+- `fillColor`: Background color.
+
+```tsx
+<PdfView
+  style={{
+    marginTop: 10,
+    marginBottom: 10,
+    padding: 5,
+    borderWidth: 0.2,
+    borderColor: "#ccc",
+  }}
+>
+  <PdfText>Content inside a styled box.</PdfText>
+</PdfView>
+```
+
+### 5. `PdfList`
+
+Renders bulleted or numbered lists.
+
+**Props:**
+
+- `items`: Array of strings.
+- `ordered`: Boolean. `true` for numbered (1., 2.), `false` for bullets.
+- `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.
+- `style`: TextStyle object for the list items.
+
+```tsx
+<PdfList
+  ordered={true}
+  indent={10}
+  spacing={3}
+  items={["First item", "Second item"]}
+/>
+```
+
+## Global Document Features
+
+Configuration is passed via the `PdfDocument` props.
+
+### Page Numbering
+
+Automatically adds page numbers to every page (or specific pages) with full customization.
+
+```tsx
+<PdfDocument
+  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
+    style: { fontSize: 9, color: "#666" }
+  }}
+>
+```
+
+### Center Label / Watermark
+
+Adds a centered label (e.g., "CONFIDENTIAL") to the header or footer area.
+
+```tsx
+<PdfDocument
+  centerLabel={{
+    enabled: true,
+    text: "CONFIDENTIAL",
+    position: "header",
+    scope: "all",
+    style: { color: "red", fontSize: 12 }
+  }}
+>
+```
+
+## License
+
+MIT

package/dist/components/PdfBox.d.ts

@@ -0,0 +1,10 @@
+import { default as React } from 'react';
+import { BoxStyle } from '../core/types';
+export interface PdfBoxProps extends BoxStyle {
+    x?: number;
+    y?: number;
+    w?: number;
+    h?: number;
+    children?: React.ReactNode;
+}
+export declare const PdfBox: React.FC<PdfBoxProps>;

package/dist/components/PdfImage.d.ts

@@ -0,0 +1,12 @@
+import { default as React } from 'react';
+export interface PdfImageProps {
+    src: string;
+    x?: number;
+    y?: number;
+    w?: number;
+    h?: number;
+    mime?: "PNG" | "JPEG";
+    flow?: boolean;
+    align?: "left" | "center" | "right";
+}
+export declare const PdfImage: React.FC<PdfImageProps>;

package/dist/components/PdfList.d.ts

@@ -0,0 +1,11 @@
+import { default as React } from 'react';
+import { TextStyle } from '../core/types';
+export interface PdfListProps {
+    items: string[];
+    ordered?: boolean;
+    style?: TextStyle;
+    indent?: number;
+    markerWidth?: number;
+    spacing?: number;
+}
+export declare const PdfList: React.FC<PdfListProps>;

package/dist/components/PdfProvider.d.ts

@@ -0,0 +1,22 @@
+import { default as React } from 'react';
+import { PdfRenderer } from '../core/PdfRenderer';
+import { CenterLabelOptions, PDFOptions, PageNumberOptions } from '../core/types';
+export declare const usePdf: () => PdfRenderer;
+export interface PdfDocumentProps {
+    options?: PDFOptions;
+    header?: (ctx: PdfRenderer, page: number, total: number) => void;
+    footer?: (ctx: PdfRenderer, page: number, total: number) => void;
+    pageNumbers?: PageNumberOptions;
+    centerLabel?: CenterLabelOptions;
+    metadata?: {
+        title?: string;
+        author?: string;
+        subject?: string;
+        keywords?: string[];
+    };
+    children: React.ReactNode;
+    onReady?: (ctx: PdfRenderer) => void;
+    filename?: string;
+    autoSave?: boolean;
+}
+export declare const PdfDocument: React.FC<PdfDocumentProps>;

package/dist/components/PdfTable.d.ts

@@ -0,0 +1,33 @@
+import { default as React } from 'react';
+import { BoxStyle, TextStyle } from '../core/types';
+export interface TableColumn {
+    header?: string;
+    accessor?: string | ((row: any) => React.ReactNode);
+    width?: number | string;
+    align?: "left" | "center" | "right";
+    id?: string;
+}
+export interface TableCell {
+    content?: string | number;
+    colSpan?: number;
+    rowSpan?: number;
+    style?: TextStyle & BoxStyle;
+}
+export interface PdfTableProps {
+    data: any[];
+    columns: TableColumn[];
+    width?: number | string;
+    borderWidth?: number;
+    borderColor?: string;
+    cellPadding?: number | {
+        top?: number;
+        right?: number;
+        bottom?: number;
+        left?: number;
+    };
+    headerStyle?: TextStyle & BoxStyle;
+    rowStyle?: TextStyle & BoxStyle;
+    alternateRowStyle?: TextStyle & BoxStyle;
+    headerHeight?: number;
+}
+export declare const PdfTable: React.FC<PdfTableProps>;

package/dist/components/PdfText.d.ts

@@ -0,0 +1,10 @@
+import { default as React } from 'react';
+import { TextStyle } from '../core/types';
+export interface PdfTextProps extends TextStyle {
+    children: string;
+    x?: number;
+    y?: number;
+    maxWidth?: number;
+    spacingBelow?: number;
+}
+export declare const PdfText: React.FC<PdfTextProps>;

package/dist/components/PdfView.d.ts

@@ -0,0 +1,8 @@
+import { default as React } from 'react';
+import { ViewStyle } from '../core/types';
+export interface PdfViewProps {
+    style?: ViewStyle;
+    children?: React.ReactNode;
+    debug?: boolean;
+}
+export declare const PdfView: React.FC<PdfViewProps>;

package/dist/components/index.d.ts

@@ -0,0 +1,7 @@
+export { PdfBox } from './PdfBox';
+export { PdfImage } from './PdfImage';
+export { PdfList } from './PdfList';
+export { PdfDocument } from './PdfProvider';
+export { PdfTable } from './PdfTable';
+export { PdfText } from './PdfText';
+export { PdfView } from './PdfView';

package/dist/core/PdfRenderer.d.ts

@@ -0,0 +1,82 @@
+import { jsPDF } from 'jspdf';
+import { BoxStyle, PDFOptions, TextStyle } from './types';
+type FontStyle = "normal" | "bold" | "italic" | "bolditalic";
+export declare class PdfRenderer {
+    private pdf;
+    private pageWidth;
+    private pageHeight;
+    private cursorX;
+    private cursorY;
+    private contentWidth;
+    private margin;
+    private defaultFont;
+    private defaultColor;
+    private defaultLineHeight;
+    private headerDrawer?;
+    private footerDrawer?;
+    private pendingTasks;
+    private opQueue;
+    constructor(opts?: PDFOptions);
+    get instance(): jsPDF;
+    get width(): number;
+    get height(): number;
+    get contentLeft(): number;
+    get contentRight(): number;
+    get contentTop(): number;
+    get contentBottom(): number;
+    get contentHeight(): number;
+    get contentAreaWidth(): number;
+    get baseFont(): {
+        name?: string;
+        style: FontStyle;
+        size: number;
+    };
+    get baseLineHeight(): number;
+    resetFlowCursor(): void;
+    setHeaderFooter(header?: (pdf: jsPDF, pageNum: number, pageCount: number, renderer: PdfRenderer) => void, footer?: (pdf: jsPDF, pageNum: number, pageCount: number, renderer: PdfRenderer) => void): void;
+    private applyBaseFont;
+    addPage(): void;
+    private ensureSpace;
+    setTextStyle(style?: TextStyle): void;
+    textRaw(text: string, x: number, y: number, style?: TextStyle, maxWidth?: number, align?: TextStyle["align"]): void;
+    box(x: number, y: number, w: number, h: number, style?: BoxStyle): void;
+    line(x1: number, y1: number, x2: number, y2: number): void;
+    imageFromUrl(url: string, opts?: {
+        x?: number;
+        y?: number;
+        w?: number;
+        h?: number;
+        mime?: "PNG" | "JPEG";
+        align?: "left" | "center" | "right";
+    }): Promise<{
+        width: number;
+        height: number;
+        x: number | undefined;
+        y: number;
+    }>;
+    queueOperation(op: () => Promise<void> | void): void;
+    private registerTask;
+    waitForTasks(): Promise<void>;
+    private loadImageAsDataURL;
+    paragraph(text: string, style?: TextStyle, maxWidth?: number): number;
+    moveCursor(dx: number, dy: number): void;
+    setCursor(x: number, y: number): void;
+    getCursor(): {
+        x: number;
+        y: number;
+    };
+    getPageCount(): number;
+    applyHeaderFooter(): void;
+    measureText(text: string, style?: TextStyle, maxWidth?: number): {
+        width: number;
+        height: number;
+    };
+    setMetadata(metadata: {
+        title?: string;
+        author?: string;
+        subject?: string;
+        keywords?: string[];
+    }): void;
+    save(filename: string): void;
+}
+export {};

package/dist/core/types.d.ts

@@ -0,0 +1,80 @@
+export type PDFFormat = "a4" | "letter" | [number, number];
+export type Align = "left" | "center" | "right" | "justify";
+export interface PDFOptions {
+    format?: PDFFormat;
+    orientation?: "p" | "l";
+    unit?: "mm" | "pt";
+    margin?: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    font?: {
+        name?: string;
+        style?: "normal" | "bold" | "italic" | "bolditalic";
+        size?: number;
+    };
+    color?: string;
+    lineHeight?: number;
+}
+export interface TextStyle {
+    fontSize?: number;
+    fontStyle?: "normal" | "bold" | "italic" | "bolditalic";
+    color?: string;
+    align?: Align;
+    verticalAlign?: "top" | "middle" | "bottom";
+    lineHeight?: number;
+}
+export interface BoxStyle {
+    borderColor?: string;
+    borderWidth?: number;
+    fillColor?: string;
+    radius?: number;
+    padding?: number | {
+        top?: number;
+        right?: number;
+        bottom?: number;
+        left?: number;
+    };
+    paddingTop?: number;
+    paddingRight?: number;
+    paddingBottom?: number;
+    paddingLeft?: number;
+}
+export interface ViewStyle extends BoxStyle {
+    margin?: number | {
+        top?: number;
+        right?: number;
+        bottom?: number;
+        left?: number;
+    };
+    marginTop?: number;
+    marginRight?: number;
+    marginBottom?: number;
+    marginLeft?: number;
+    width?: number | string;
+    height?: number;
+}
+export type PageNumberPreset = "page-slash-total" | "slash" | "page-of-total";
+export interface PageNumberOptions {
+    enabled?: boolean;
+    position?: "header" | "footer";
+    align?: "left" | "right" | "center";
+    preset?: PageNumberPreset;
+    template?: string;
+    y?: number;
+    offsetX?: number;
+    style?: TextStyle;
+    scope?: "all" | "first-only" | "except-first";
+    format?: "arabic" | "roman-upper" | "roman-lower";
+}
+export interface CenterLabelOptions {
+    enabled?: boolean;
+    position?: "header" | "footer";
+    text: string;
+    scope?: "all" | "first-only" | "except-first" | number[];
+    y?: number;
+    offsetX?: number;
+    style?: TextStyle;
+}

package/dist/core/utils.d.ts

@@ -0,0 +1,14 @@
+export declare const mm: (v: number) => number;
+export declare function resolvePadding(p?: number | {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+}): {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+};
+export declare function hexToRgb(hex: string): [number, number, number] | null;
+export declare function toRoman(n: number, uppercase?: boolean): string;

package/dist/demo/CodeBlock.d.ts

@@ -0,0 +1,6 @@
+import { default as React } from 'react';
+interface CodeBlockProps {
+    code: string;
+}
+export declare const CodeBlock: React.FC<CodeBlockProps>;
+export {};

package/dist/demo/DemoApp.d.ts

@@ -0,0 +1,2 @@
+import { default as React } from 'react';
+export declare const DemoApp: React.FC;

package/dist/demo/DemoPdfDocument.d.ts

@@ -0,0 +1,30 @@
+import { default as React } from 'react';
+export interface DemoPdfProps {
+    pnEnabled: boolean;
+    pnPos: "header" | "footer";
+    pnAlign: "left" | "center" | "right";
+    pnPreset: "page-slash-total" | "slash" | "page-of-total";
+    pnTemplate: string;
+    pnFormat: "arabic" | "roman-upper" | "roman-lower";
+    pnScope: "all" | "first-only" | "except-first" | "custom";
+    pnCustomPages: string;
+    pnY: string;
+    pnOffsetX: string;
+    pnFontSize: string;
+    pnColor: string;
+    clEnabled: boolean;
+    clPos: "header" | "footer";
+    clText: string;
+    clScope: "all" | "first-only" | "except-first" | "custom";
+    clCustomPages: string;
+    clY: string;
+    clOffsetX: string;
+    clFontSize: string;
+    clColor: string;
+    tableStriped: boolean;
+    tableBorderWidth: string;
+    tableHeaderColor: string;
+    onReady: (pdf: any) => void;
+    filename: string;
+}
+export declare const DemoPdfDocument: React.FC<DemoPdfProps>;

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './components';
+export { PdfList } from './components/PdfList';
+export { PdfRenderer } from './core/PdfRenderer';
+export * from './core/types';