pdf-catalog-generator 1.1.0 → 3.1.0

package/README.md

@@ -1,6 +1,20 @@
 # PDF Catalog Generator
 
-Generate beautiful product catalog PDFs from Excel, CSV, or JSON data.
+[![npm version](https://img.shields.io/npm/v/pdf-catalog-generator.svg)](https://www.npmjs.com/package/pdf-catalog-generator)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
+
+Generate beautiful product catalog PDFs from Excel, CSV, or JSON data with multiple professional templates.
+
+## Features
+
+- 🎨 **4 Professional Templates** - Choose from multiple layout options
+- 📊 **Multiple Input Formats** - Excel, CSV, and JSON support
+- 🏢 **Customizable Branding** - Add your company logo and name
+- 📦 **Dual Package** - Supports both ESM and CommonJS
+- 🔒 **Type Safe** - Full TypeScript support with type definitions
+- ✅ **Tested** - Comprehensive unit test coverage
+- 📚 **Well Documented** - Interactive Storybook documentation
 
 ## Installation
 
@@ -8,64 +22,439 @@ Generate beautiful product catalog PDFs from Excel, CSV, or JSON data.
 npm install pdf-catalog-generator
 ```
 
-## Usage
+## Quick Start
 
 ```typescript
 import { generateProductCatalog } from 'pdf-catalog-generator';
+import fs from 'fs';
 
-// From JSON
 const pdfBuffer = await generateProductCatalog({
   products: [
     {
-      Title: 'Product 1',
-      Description: 'Description here',
-      Image: 'https://example.com/image.jpg',
-      Price: 99.99,
+      Title: 'Laptop Pro 15',
+      Description: 'High-performance laptop',
+      Image: 'https://example.com/laptop.jpg',
+      Price: 1299.99,
       Rating: 4.5,
-      Link: 'https://example.com/product'
+      Link: 'https://store.example.com/laptop'
     }
   ],
-  companyLogo: 'https://example.com/logo.png', // or base64
-  companyName: 'Your Company',
-  template: 'template1' // template1, template2, or template3
+  companyName: 'Tech Store',
+  companyLogo: 'https://example.com/logo.png',
+  template: 'template1'
+});
+
+// Save to file
+fs.writeFileSync('catalog.pdf', pdfBuffer);
+```
+
+## Platform Compatibility
+
+This library works seamlessly across different JavaScript environments:
+
+- ✅ **Node.js** - Backend servers, build scripts, CLI tools
+- ✅ **Browser/React** - Client-side web applications
+- ✅ **Next.js** - Both server components (SSR) and client components
+
+### Browser/React Usage
+
+```typescript
+import { parseExcelFile, generateProductCatalog } from 'pdf-catalog-generator';
+
+async function handleFileUpload(event: React.ChangeEvent<HTMLInputElement>) {
+  const file = event.target.files?.[0];
+  if (!file) return;
+
+  // Use browser File API
+  const arrayBuffer = await file.arrayBuffer();
+
+  // Parse with ArrayBuffer (cross-platform compatible)
+  const products = parseExcelFile(arrayBuffer);
+
+  // Generate PDF
+  const pdfBuffer = await generateProductCatalog({
+    products,
+    companyName: 'My Store',
+    template: 'template1',
+  });
+
+  // Download in browser
+  const blob = new Blob([pdfBuffer], { type: 'application/pdf' });
+  const url = URL.createObjectURL(blob);
+  const link = document.createElement('a');
+  link.href = url;
+  link.download = 'catalog.pdf';
+  link.click();
+  URL.revokeObjectURL(url);
+}
+```
+
+### Next.js Usage
+
+**Server Component (App Router):**
+```typescript
+// app/api/generate-catalog/route.ts
+import { parseExcelFile, generateProductCatalog } from 'pdf-catalog-generator';
+
+export async function POST(request: Request) {
+  const formData = await request.formData();
+  const file = formData.get('file') as File;
+
+  // Convert File to ArrayBuffer
+  const arrayBuffer = await file.arrayBuffer();
+
+  const products = parseExcelFile(arrayBuffer);
+  const pdfBuffer = await generateProductCatalog({
+    products,
+    companyName: 'My Store',
+  });
+
+  return new Response(pdfBuffer, {
+    headers: {
+      'Content-Type': 'application/pdf',
+      'Content-Disposition': 'attachment; filename="catalog.pdf"',
+    },
+  });
+}
+```
+
+**Client Component:**
+```typescript
+'use client';
+
+import { useState } from 'react';
+import { parseExcelFile, generateProductCatalog } from 'pdf-catalog-generator';
+
+export default function CatalogGenerator() {
+  const handleGenerate = async (file: File) => {
+    const arrayBuffer = await file.arrayBuffer();
+    const products = parseExcelFile(arrayBuffer);
+    const pdfBuffer = await generateProductCatalog({
+      products,
+      companyName: 'My Store',
+    });
+
+    // Download
+    const blob = new Blob([pdfBuffer], { type: 'application/pdf' });
+    const url = URL.createObjectURL(blob);
+    const link = document.createElement('a');
+    link.href = url;
+    link.download = 'catalog.pdf';
+    link.click();
+  };
+
+  return (
+    <input
+      type="file"
+      accept=".xlsx,.csv"
+      onChange={(e) => e.target.files?.[0] && handleGenerate(e.target.files[0])}
+    />
+  );
+}
+```
+
+### Input Types
+
+The parser functions accept multiple input types for cross-platform compatibility:
+
+- **Node.js Buffer** - `fs.readFileSync()` returns Buffer
+- **ArrayBuffer** - Browser `File.arrayBuffer()` returns ArrayBuffer
+- **Uint8Array** - Universal typed array format
+
+All input types are automatically detected and handled correctly.
+
+## API Reference
+
+### `generateProductCatalog(config)`
+
+Generates a PDF catalog from the provided configuration.
+
+**Parameters:**
+- `config` (CatalogConfig):
+  - `products` (ProductData[]): Array of product data
+  - `companyName` (string): Your company name
+  - `companyLogo` (string | null, optional): Logo URL or base64 string
+  - `template` (TemplateType, optional): Template to use (default: 'template1')
+
+**Returns:** `Promise<Uint8Array>` - PDF file as Uint8Array (works in both Node.js and browser)
+
+### `parseExcelFile(buffer)`
+
+Parse Excel file buffer into product data.
+
+**Parameters:**
+- `buffer` (Buffer | ArrayBuffer | Uint8Array): Excel file data
+  - Node.js: Use `Buffer` from `fs.readFileSync()`
+  - Browser: Use `ArrayBuffer` from `file.arrayBuffer()`
+  - Universal: `Uint8Array` works everywhere
+
+**Returns:** `ProductData[]` - Array of products
+
+**Example (Node.js):**
+```typescript
+import { parseExcelFile, generateProductCatalog } from 'pdf-catalog-generator';
+import fs from 'fs';
+
+const excelBuffer = fs.readFileSync('products.xlsx');
+const products = parseExcelFile(excelBuffer);
+const pdfBuffer = await generateProductCatalog({
+  products,
+  companyName: 'My Store'
 });
+```
 
-// From Excel file
-import { parseExcelFile } from 'pdf-catalog-generator';
+**Example (Browser/React):**
+```typescript
+import { parseExcelFile, generateProductCatalog } from 'pdf-catalog-generator';
 
-const products = await parseExcelFile(fileBuffer);
+const file = event.target.files[0];
+const arrayBuffer = await file.arrayBuffer();
+const products = parseExcelFile(arrayBuffer);
 const pdfBuffer = await generateProductCatalog({
   products,
-  companyLogo: logoBase64,
-  companyName: 'Your Company',
-  template: 'template2'
+  companyName: 'My Store'
 });
+```
+
+### `parseCSVFile(csvString)`
+
+Parse CSV string into product data.
+
+**Parameters:**
+- `csvString` (string): CSV content as string
+
+**Returns:** `ProductData[]` - Array of products
+
+**Example:**
+```typescript
+import { parseCSVFile, generateProductCatalog } from 'pdf-catalog-generator';
+import fs from 'fs';
+
+const csvString = fs.readFileSync('products.csv', 'utf-8');
+const products = parseCSVFile(csvString);
+const pdfBuffer = await generateProductCatalog({
+  products,
+  companyName: 'My Store'
+});
+```
+
+### `parseCSVBuffer(buffer)`
+
+Parse CSV buffer into product data.
+
+**Parameters:**
+- `buffer` (Buffer | ArrayBuffer | Uint8Array): CSV file data
+  - Node.js: Use `Buffer` from `fs.readFileSync()`
+  - Browser: Use `ArrayBuffer` from `file.arrayBuffer()`
+  - Universal: `Uint8Array` works everywhere
+
+**Returns:** `ProductData[]` - Array of products
+
+### `parseJSON(data)`
 
-// From CSV file
-import { parseCSVFile } from 'pdf-catalog-generator';
+Parse JSON product data. No fields are mandatory - data is passed through as-is.
 
-const products = await parseCSVFile(csvString);
+**Parameters:**
+- `data` (any[]): Array of product objects
+
+**Returns:** `ProductData[]` - Products passed through without modification
+
+**Note:** parseJSON no longer validates or normalizes data. It simply passes through your data as-is, just like the Excel/CSV parsers.
+
+**Example:**
+```typescript
+import { parseJSON, generateProductCatalog } from 'pdf-catalog-generator';
+
+const rawData = [
+  { Title: 'Product 1', Link: 'https://example.com/1' },
+  { sku: 'ABC-123', name: 'Custom Product', color: 'Blue' },
+  { designNumber: 'DN-001', fabric: 'Cotton', gsm: 180 }
+];
+
+const products = parseJSON(rawData); // All pass through without modification
 const pdfBuffer = await generateProductCatalog({
   products,
-  companyLogo: logoUrl,
-  companyName: 'Your Company',
-  template: 'template3'
+  companyName: 'My Store'
 });
 ```
 
-## Product Data Format
+## Data Format
+
+### ProductData
+
+This library is **completely schema-free** - no fields are mandatory! You can use any data structure you want.
+
+```typescript
+interface ProductData {
+  [key: string]: string | number | boolean | null | undefined;
+}
+```
+
+**Dynamic Field Rendering:**
+- All templates automatically detect and display whatever fields you provide
+- Common fields (Title, Description, Image, Price, Rating, Link) are displayed prominently if present
+- All other fields are rendered dynamically with auto-formatted labels
+- Missing fields are gracefully handled - nothing breaks!
 
-Each product should have:
-- `Title` (string): Product name
-- `Description` (string): Product description
-- `Image` (string): Image URL or base64
-- `Price` (number): Product price
-- `Rating` (number): Star rating
-- `Link` (string): Buy/product link
+**Common Field Names (Optional):**
+Templates intelligently look for these common fields (case-insensitive):
+- **Title/Name/ProductName** - Displayed as main heading
+- **Image/ImageUrl/photo** - Used as product image (fallback image if missing)
+- **Description/Details/Info** - Shown as product description
+- **Price/Cost/Amount** - Displayed prominently (formatted if provided)
+- **Rating/Stars/Score** - Shown with star emoji if present
+- **Link/URL/ProductUrl** - Powers "Buy Now" buttons
+
+**Custom Fields:**
+Any other fields are automatically displayed with smart formatting:
+- `designNumber` → "Design Number"
+- `gsm` → "GSM" (uppercase for known acronyms)
+- `fabric_finish` → "Fabric Finish"
+
+**Example - Traditional E-commerce:**
+```typescript
+{
+  Title: 'Laptop Pro 15',
+  Description: 'High-performance laptop',
+  Image: 'https://example.com/laptop.jpg',
+  Price: 1299.99,
+  Rating: 4.5,
+  Link: 'https://store.example.com/laptop'
+}
+```
+
+**Example - Custom Textile Catalog:**
+```typescript
+{
+  designNumber: 'DN-12345',
+  fabric: '100% Cotton',
+  gsm: 180,
+  finish: 'Mercerized',
+  color: 'Navy Blue',
+  Image: 'https://example.com/fabric.jpg'
+}
+```
+
+**Example - Minimal:**
+```typescript
+{
+  name: 'Widget',
+  sku: 'WDG-001'
+}
+```
+
+All of the above work perfectly! Templates adapt to your data structure.
 
 ## Templates
 
-- `template1`: Grid layout with 2 columns
-- `template2`: Full-width list layout
-- `template3`: Compact grid layout
+All templates are **fully dynamic** and adapt to your data structure. They intelligently detect common fields and display all additional fields automatically.
+
+### Template 1: Grid Layout
+2-column grid layout with product cards. Perfect for showcasing multiple products.
+
+```typescript
+template: 'template1'
+```
+
+**Best for:** Products with mixed field types - automatically displays all fields in a compact grid card.
+
+### Template 2: List Layout
+Full-width horizontal layout with image on left, details on right. Great for detailed product information.
+
+```typescript
+template: 'template2'
+```
+
+**Best for:** Detailed products - shows all fields with room for descriptions and custom attributes.
+
+### Template 3: Full Page Layout
+Full-page product view with image background and overlay details box. One product per page.
+
+```typescript
+template: 'template3'
+```
+
+**Best for:** Premium catalogs with hero images - displays key fields in an elegant overlay box (shows up to 5 custom fields).
+
+### Template 4: One-Per-Page
+Full-page product view with header on each page and all product details listed. One product per page.
+
+```typescript
+template: 'template4'
+```
+
+**Best for:** Maximum detail - displays ALL product fields with formatted labels. Ideal for technical specifications or textile catalogs.
+
+## TypeScript Support
+
+This package is written in TypeScript and includes type definitions:
+
+```typescript
+import type { CatalogConfig, ProductData, TemplateType } from 'pdf-catalog-generator';
+
+const config: CatalogConfig = {
+  products: [],
+  companyName: 'My Company',
+  template: 'template1'
+};
+```
+
+## Examples
+
+Check the `examples/` directory for complete working examples:
+- Basic usage
+- Excel to PDF
+- CSV to PDF
+- Custom templates
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Run tests with coverage
+npm run test:coverage
+
+# Build package
+npm run build
+
+# Run Storybook
+npm run storybook
+
+# Lint code
+npm run lint
+
+# Format code
+npm run format
+```
+
+## Contributing
+
+Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for a list of changes.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Support
+
+- 📚 [Documentation](https://github.com/yourusername/pdf-catalog-generator)
+- 🐛 [Issue Tracker](https://github.com/yourusername/pdf-catalog-generator/issues)
+- 💬 [Discussions](https://github.com/yourusername/pdf-catalog-generator/discussions)
+
+## Credits
 
+Built with:
+- [@react-pdf/renderer](https://github.com/diegomura/react-pdf) - PDF generation
+- [xlsx](https://github.com/SheetJS/sheetjs) - Excel/CSV parsing
+- [TypeScript](https://www.typescriptlang.org/) - Type safety
+- [Vitest](https://vitest.dev/) - Testing
+- [Storybook](https://storybook.js.org/) - Documentation