react-id-card-generator 1.0.0

package/dist/types/components/IDCardPreview.d.ts

@@ -0,0 +1,15 @@
+import React from 'react';
+import type { IDCardPreviewProps } from '../types';
+/**
+ * IDCardPreview - Interactive card preview component
+ *
+ * Renders an ID card with:
+ * - Field selection and highlighting
+ * - Resize handles for selected fields
+ * - Grid overlay for alignment
+ * - Dynamic field rendering based on type
+ *
+ * Used inside the designer for visual editing
+ */
+export declare const IDCardPreview: React.FC<IDCardPreviewProps>;
+export default IDCardPreview;

package/dist/types/core/exportUtils.d.ts

@@ -0,0 +1,34 @@
+import type { ExportOptions, ExportResult, IDCardData } from '../types';
+interface DownloadIDCardOptions {
+    frontElementId?: string;
+    backElementId?: string;
+    filename?: string;
+    data?: IDCardData;
+    qrElementId?: string;
+    qrFields?: string[];
+    format?: 'pdf' | 'png' | 'jpeg';
+    scale?: number;
+    quality?: number;
+}
+/**
+ * Download ID card(s) as a PDF file
+ * Captures DOM elements and converts them to a multi-page PDF
+ * @param options - Configuration for PDF export
+ * @returns Export result with success status and any errors
+ */
+export declare function downloadIDCardAsPDF(options: DownloadIDCardOptions): Promise<ExportResult>;
+/**
+ * Download ID card as image (PNG or JPEG)
+ */
+export declare function downloadIDCardAsImage(options: DownloadIDCardOptions): Promise<ExportResult>;
+/**
+ * Export ID card with unified options
+ */
+export declare function exportIDCard(options: ExportOptions & {
+    frontElementId?: string;
+    backElementId?: string;
+    data?: IDCardData;
+    qrElementId?: string;
+    qrFields?: string[];
+}): Promise<ExportResult>;
+export {};

package/dist/types/core/qrUtils.d.ts

@@ -0,0 +1,27 @@
+import type { IDCardData } from '../types';
+/**
+ * Generate a QR code as a base64 data URL
+ * @param data - Data to encode in the QR code (will be JSON stringified)
+ * @param size - QR code size in pixels
+ * @param options - Customization options (error correction level, colors, etc.)
+ * @returns Base64 PNG data URL
+ */
+export declare function generateQrCodeDataURL(data: Record<string, unknown>, size?: number, options?: {
+    level?: 'L' | 'M' | 'Q' | 'H';
+    padding?: number;
+    background?: string;
+    foreground?: string;
+}): string;
+/**
+ * Generate QR code from specific fields in the card data
+ * Only includes fields that exist in the data object
+ * @param data - Full card data object
+ * @param fields - Array of field keys to include in QR code
+ * @param size - QR code size in pixels
+ * @returns Base64 PNG data URL
+ */
+export declare function generateQrCodeFromFields(data: IDCardData, fields: string[], size?: number): string;
+/**
+ * Set QR code image src on a DOM element
+ */
+export declare function setQrCodeOnElement(elementId: string, data: Record<string, unknown>, size?: number, container?: Document | HTMLElement): boolean;

package/dist/types/hooks/useFieldMapping.d.ts

@@ -0,0 +1,10 @@
+import type React from 'react';
+import type { FieldMapping, UseFieldMappingReturn } from '../types';
+interface UseFieldMappingOptions {
+    onFieldUpdate?: (field: FieldMapping) => void;
+    containerRef?: React.RefObject<HTMLElement>;
+    gridSize?: number;
+    snapToGrid?: boolean;
+}
+export declare function useFieldMapping(options?: UseFieldMappingOptions): UseFieldMappingReturn;
+export {};

package/dist/types/hooks/useIDCardExport.d.ts

@@ -0,0 +1,10 @@
+import type { IDCardData, UseIDCardExportReturn } from '../types';
+interface ExportConfig {
+    frontElementId?: string;
+    backElementId?: string;
+    data?: IDCardData;
+    qrElementId?: string;
+    qrFields?: string[];
+}
+export declare function useIDCardExport(config?: ExportConfig): UseIDCardExportReturn;
+export {};

package/dist/types/hooks/useIDCardTemplate.d.ts

@@ -0,0 +1,10 @@
+import type { IDCardTemplate, UseIDCardTemplateReturn } from '../types';
+/**
+ * Hook for managing ID card template state
+ * Provides methods for updating fields, backgrounds, and card properties
+ * Automatically updates the template's updatedAt timestamp on changes
+ *
+ * @param initialTemplate - Optional existing template to start with
+ * @returns Template state and helper methods
+ */
+export declare function useIDCardTemplate(initialTemplate?: Partial<IDCardTemplate>): UseIDCardTemplateReturn;

package/dist/types/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * React ID Card Generator Library
+ *
+ * A complete solution for creating customizable ID cards with:
+ * - Visual drag-and-drop designer
+ * - Template management
+ * - PDF/PNG export
+ * - QR code generation
+ *
+ * @example
+ * ```tsx
+ * import { IDCardDesigner, IDCardGenerator } from 'react-id-card-generator';
+ *
+ * // Design a template
+ * <IDCardDesigner onSave={handleSave} />
+ *
+ * // Generate cards
+ * <IDCardGenerator template={myTemplate} data={userData} />
+ * ```
+ */
+export { IDCardGenerator } from './components/IDCardGenerator';
+export { IDCardDesigner } from './components/IDCardDesigner';
+export { IDCardPreview } from './components/IDCardPreview';
+export { useIDCardTemplate } from './hooks/useIDCardTemplate';
+export { useIDCardExport } from './hooks/useIDCardExport';
+export { useFieldMapping } from './hooks/useFieldMapping';
+export { generateQrCodeDataURL, generateQrCodeFromFields, setQrCodeOnElement, } from './core/qrUtils';
+export { downloadIDCardAsPDF, downloadIDCardAsImage, exportIDCard, } from './core/exportUtils';
+export { saveTemplateToLocal, loadTemplateFromLocal, listTemplatesFromLocal, removeTemplateFromLocal, exportTemplateAsJSON, importTemplateFromJSON, imageFileToBase64, generateId, createDefaultTemplate, } from './storage/templateStorage';
+export { validateTemplate, validateField, validateCardSize, isFieldInBounds, } from './utils/validators';
+export { toReactStyle, fieldStyleToCSS, mergeStyles, positionToStyle, defaultFieldStyles, cn, } from './utils/styleUtils';
+export type { FieldPosition, FieldStyle, FieldType, FieldMapping, FieldDefinition, CardOrientation, CardSides, CardSize, CardBackground, IDCardTemplate, IDCardData, ExportOptions, ExportResult, IDCardGeneratorProps, IDCardDesignerProps, IDCardPreviewProps, UseIDCardTemplateReturn, UseIDCardExportReturn, UseFieldMappingReturn, TemplateStorage, DragState, ResizeState, } from './types';
+import './components/IDCardDesigner.css';

package/dist/types/storage/templateStorage.d.ts

@@ -0,0 +1,53 @@
+import type { IDCardTemplate } from '../types';
+/**
+ * Save a template to browser localStorage
+ * @param key - Unique identifier for the template
+ * @param template - The template to save
+ * @throws Error if localStorage is unavailable or quota exceeded
+ */
+export declare function saveTemplateToLocal(key: string, template: IDCardTemplate): void;
+/**
+ * Load a template from browser localStorage
+ * @param key - Template identifier
+ * @returns The template, or null if not found or invalid
+ */
+export declare function loadTemplateFromLocal(key: string): IDCardTemplate | null;
+/**
+ * Get all saved template keys from localStorage
+ * @returns Array of template keys (without the prefix)
+ */
+export declare function listTemplatesFromLocal(): string[];
+/**
+ * Remove a template from localStorage
+ * @param key - Template identifier to remove
+ */
+export declare function removeTemplateFromLocal(key: string): void;
+/**
+ * Export a template as a downloadable JSON file
+ * @param template - The template to export
+ * @param filename - Optional custom filename (defaults to template name)
+ */
+export declare function exportTemplateAsJSON(template: IDCardTemplate, filename?: string): void;
+/**
+ * Import a template from a JSON file
+ * @param file - The JSON file to read
+ * @returns Promise that resolves to the parsed template
+ */
+export declare function importTemplateFromJSON(file: File): Promise<IDCardTemplate>;
+/**
+ * Convert an image file to a base64 data URL
+ * Useful for embedding images in templates
+ * @param file - Image file (JPG, PNG, etc.)
+ * @returns Promise that resolves to a base64 data URL
+ */
+export declare function imageFileToBase64(file: File): Promise<string>;
+/**
+ * Generate a unique ID with timestamp and random component
+ * @param prefix - Prefix for the ID (e.g., 'field', 'template')
+ * @returns Unique string like 'field_1703234567890_abc123def'
+ */
+export declare function generateId(prefix?: string): string;
+/**
+ * Create a default template
+ */
+export declare function createDefaultTemplate(name?: string): IDCardTemplate;

package/dist/types/types/index.d.ts

@@ -0,0 +1,235 @@
+import type React from 'react';
+/**
+ * Position and dimensions of a field on the card
+ * All values are in pixels relative to the card's top-left corner
+ */
+export interface FieldPosition {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * CSS-like styling options for text and container fields
+ * Values should be valid CSS strings (e.g., '12px', '#000000', '50%')
+ */
+export interface FieldStyle {
+    fontSize?: string;
+    fontWeight?: 'normal' | 'bold' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900';
+    fontFamily?: string;
+    color?: string;
+    textAlign?: 'left' | 'center' | 'right';
+    textTransform?: 'none' | 'uppercase' | 'lowercase' | 'capitalize';
+    backgroundColor?: string;
+    borderRadius?: string;
+    padding?: string;
+    border?: string;
+    lineHeight?: string;
+    letterSpacing?: string;
+}
+/**
+ * Available field types for ID cards
+ * - text: Dynamic text data (name, ID, etc.)
+ * - image: Photos or logos
+ * - qrcode: QR codes generated from card data
+ * - label: Static text that doesn't change
+ */
+export type FieldType = 'text' | 'image' | 'qrcode' | 'label';
+/**
+ * A single field on the ID card (text, image, QR code, etc.)
+ * This defines what the field displays and how it's styled
+ */
+export interface FieldMapping {
+    id: string;
+    fieldKey: string;
+    label?: string;
+    placeholder?: string;
+    type: FieldType;
+    side: 'front' | 'back';
+    position: FieldPosition;
+    style?: FieldStyle;
+    required?: boolean;
+    qrFields?: string[];
+    aspectRatio?: number;
+    staticText?: string;
+    zIndex?: number;
+}
+export type CardOrientation = 'portrait' | 'landscape';
+export type CardSides = 'single' | 'double';
+/**
+ * Physical dimensions of the ID card
+ */
+export interface CardSize {
+    width: number;
+    height: number;
+    unit: 'px' | 'mm' | 'in';
+}
+/**
+ * Background images for card sides (base64 data URLs or HTTP URLs)
+ */
+export interface CardBackground {
+    front?: string;
+    back?: string;
+}
+/**
+ * Complete ID card template definition
+ * This is the reusable template that can be filled with different user data
+ */
+export interface IDCardTemplate {
+    id: string;
+    name: string;
+    version: string;
+    createdAt: string;
+    updatedAt: string;
+    orientation: CardOrientation;
+    sides: CardSides;
+    cardSize: CardSize;
+    backgrounds: CardBackground;
+    fields: FieldMapping[];
+    metadata?: Record<string, unknown>;
+}
+/**
+ * User data to fill into the card template
+ * Keys should match fieldKey values in FieldMapping
+ * Example: { name: 'John Doe', photo: 'data:image/jpeg;base64,...' }
+ */
+export interface IDCardData {
+    [key: string]: string | number | boolean | string[] | undefined;
+}
+/**
+ * Options for exporting cards to PDF or images
+ */
+export interface ExportOptions {
+    format: 'pdf' | 'png' | 'jpeg';
+    scale?: number;
+    quality?: number;
+    filename?: string;
+    pages?: ('front' | 'back')[];
+    includeBleed?: boolean;
+    bleedSize?: number;
+}
+/**
+ * Result from an export operation
+ */
+export interface ExportResult {
+    success: boolean;
+    blob?: Blob;
+    dataUrl?: string;
+    error?: string;
+}
+/**
+ * Props for IDCardGenerator - renders a filled ID card
+ */
+export interface IDCardGeneratorProps {
+    template: IDCardTemplate;
+    data: IDCardData;
+    side?: 'front' | 'back';
+    scale?: number;
+    className?: string;
+    style?: React.CSSProperties;
+    onFieldClick?: (field: FieldMapping) => void;
+    editable?: boolean;
+}
+/**
+ * Props for IDCardDesigner - the visual template builder
+ */
+export interface IDCardDesignerProps {
+    initialTemplate?: Partial<IDCardTemplate>;
+    onSave: (template: IDCardTemplate) => void;
+    onCancel?: () => void;
+    availableFields?: FieldDefinition[];
+    className?: string;
+    style?: React.CSSProperties;
+}
+/**
+ * Definition of a field type available in the designer
+ */
+export interface FieldDefinition {
+    key: string;
+    label: string;
+    type: FieldType;
+    defaultStyle?: FieldStyle;
+    required?: boolean;
+}
+/**
+ * Props for IDCardPreview - interactive card preview with editing
+ */
+export interface IDCardPreviewProps {
+    template: IDCardTemplate;
+    data: IDCardData;
+    side: 'front' | 'back';
+    scale?: number;
+    showGrid?: boolean;
+    onFieldSelect?: (field: FieldMapping | null) => void;
+    selectedFieldId?: string | null;
+    editable?: boolean;
+    onFieldUpdate?: (field: FieldMapping) => void;
+}
+/**
+ * Return value from useIDCardTemplate hook
+ * Provides template state management and helper methods
+ */
+export interface UseIDCardTemplateReturn {
+    template: IDCardTemplate;
+    setTemplate: (template: IDCardTemplate) => void;
+    updateField: (fieldId: string, updates: Partial<FieldMapping>) => void;
+    addField: (field: FieldMapping) => void;
+    removeField: (fieldId: string) => void;
+    setBackground: (side: 'front' | 'back', imageData: string) => void;
+    setCardSize: (size: CardSize) => void;
+    setOrientation: (orientation: CardOrientation) => void;
+    setSides: (sides: CardSides) => void;
+    duplicateField: (fieldId: string) => void;
+    moveFieldToSide: (fieldId: string, side: 'front' | 'back') => void;
+    reset: () => void;
+    isValid: boolean;
+    validationErrors: string[];
+}
+/**
+ * Return value from useIDCardExport hook
+ * Handles exporting cards to PDF or images
+ */
+export interface UseIDCardExportReturn {
+    exportAsPDF: (options?: Partial<ExportOptions>) => Promise<ExportResult>;
+    exportAsImage: (options?: Partial<ExportOptions>) => Promise<ExportResult>;
+    isExporting: boolean;
+    progress: number;
+    error: string | null;
+}
+/**
+ * Return value from useFieldMapping hook
+ * Handles field selection, dragging, and resizing
+ */
+export interface UseFieldMappingReturn {
+    selectedField: FieldMapping | null;
+    selectField: (field: FieldMapping | null) => void;
+    updatePosition: (position: Partial<FieldPosition>) => void;
+    updateStyle: (style: Partial<FieldStyle>) => void;
+    isDragging: boolean;
+    isResizing: boolean;
+    startDrag: (e: React.MouseEvent) => void;
+    startResize: (e: React.MouseEvent, handle: string) => void;
+}
+export interface TemplateStorage {
+    save: (key: string, template: IDCardTemplate) => Promise<void>;
+    load: (key: string) => Promise<IDCardTemplate | null>;
+    list: () => Promise<string[]>;
+    remove: (key: string) => Promise<void>;
+}
+export interface DragState {
+    isDragging: boolean;
+    startX: number;
+    startY: number;
+    currentX: number;
+    currentY: number;
+    fieldId: string | null;
+}
+export interface ResizeState {
+    isResizing: boolean;
+    handle: 'n' | 's' | 'e' | 'w' | 'ne' | 'nw' | 'se' | 'sw' | null;
+    startX: number;
+    startY: number;
+    startWidth: number;
+    startHeight: number;
+    fieldId: string | null;
+}

package/dist/types/utils/styleUtils.d.ts

@@ -0,0 +1,34 @@
+import type React from 'react';
+import type { FieldStyle } from '../types';
+/**
+ * Convert a style object with kebab-case keys to React camelCase
+ * Useful when importing styles from external sources
+ */
+export declare function toReactStyle(styleObj: Record<string, unknown> | undefined): React.CSSProperties;
+/**
+ * Convert FieldStyle to React CSS properties
+ * @param style - The field style object
+ * @returns React-compatible CSS properties object
+ */
+export declare function fieldStyleToCSS(style: FieldStyle | undefined): React.CSSProperties;
+/**
+ * Merge multiple style objects
+ */
+export declare function mergeStyles(...styles: (React.CSSProperties | undefined)[]): React.CSSProperties;
+/**
+ * Generate position styles from field position
+ */
+export declare function positionToStyle(position: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}): React.CSSProperties;
+/**
+ * Default styles for different field types
+ */
+export declare const defaultFieldStyles: Record<string, FieldStyle>;
+/**
+ * CSS class name generator
+ */
+export declare function cn(...classes: (string | undefined | null | false)[]): string;

package/dist/types/utils/validators.d.ts

@@ -0,0 +1,27 @@
+import type { IDCardTemplate, FieldMapping, CardSize } from '../types';
+export interface ValidationError {
+    field: string;
+    message: string;
+}
+/**
+ * Validate a complete ID card template
+ * Checks for required fields, valid dimensions, and proper field configuration
+ * @param template - The template to validate
+ * @returns Array of validation errors (empty if valid)
+ */
+export declare function validateTemplate(template: IDCardTemplate): ValidationError[];
+/**
+ * Validate a single field's configuration
+ * @param field - The field to validate
+ * @param index - Field index (for error messages)
+ * @returns Array of validation errors
+ */
+export declare function validateField(field: FieldMapping, index: number): ValidationError[];
+/**
+ * Validate card size against standard dimensions
+ */
+export declare function validateCardSize(size: CardSize): boolean;
+/**
+ * Check if a field is within card bounds
+ */
+export declare function isFieldInBounds(field: FieldMapping, cardSize: CardSize): boolean;

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "react-id-card-generator",
+  "version": "1.0.0",
+  "description": "A flexible React library for designing, configuring, and generating ID cards with drag-and-drop field positioning",
+  "main": "dist/cjs/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
+      "types": "./dist/types/index.d.ts"
+    },
+    "./styles": "./dist/styles.css"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "rollup -c && tsc --emitDeclarationOnly --outDir dist/types",
+    "build:watch": "rollup -c -w",
+    "test": "jest",
+    "lint": "eslint src --ext .ts,.tsx",
+    "prepublishOnly": "npm run build",
+    "example": "cd example && npm run dev"
+  },
+  "peerDependencies": {
+    "react": ">=17.0.0",
+    "react-dom": ">=17.0.0"
+  },
+  "dependencies": {
+    "html2canvas": "^1.4.1",
+    "jspdf": "^2.5.1",
+    "qrious": "^4.0.2"
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^25.0.7",
+    "@rollup/plugin-node-resolve": "^15.2.3",
+    "@rollup/plugin-typescript": "^11.1.5",
+    "@types/react": "^18.2.45",
+    "@types/react-dom": "^18.2.18",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "rollup": "^4.9.1",
+    "rollup-plugin-dts": "^6.1.0",
+    "rollup-plugin-postcss": "^4.0.2",
+    "tslib": "^2.8.1",
+    "typescript": "^5.3.3"
+  },
+  "keywords": [
+    "react",
+    "id-card",
+    "card-generator",
+    "id-card-designer",
+    "drag-drop",
+    "pdf-generator",
+    "qr-code"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": ""
+  }
+}