react-id-card-generator 1.0.2 → 1.0.3

package/dist/index.d.ts

@@ -0,0 +1,484 @@
+import 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
+ */
+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%')
+ */
+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
+ */
+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
+ */
+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;
+}
+type CardOrientation = 'portrait' | 'landscape';
+type CardSides = 'single' | 'double';
+/**
+ * Physical dimensions of the ID card
+ */
+interface CardSize {
+    width: number;
+    height: number;
+    unit: 'px' | 'mm' | 'in';
+}
+/**
+ * Background images for card sides (base64 data URLs or HTTP URLs)
+ */
+interface CardBackground {
+    front?: string;
+    back?: string;
+}
+/**
+ * Complete ID card template definition
+ * This is the reusable template that can be filled with different user data
+ */
+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,...' }
+ */
+interface IDCardData {
+    [key: string]: string | number | boolean | string[] | undefined;
+}
+/**
+ * Options for exporting cards to PDF or images
+ */
+interface ExportOptions {
+    format: 'pdf' | 'png' | 'jpeg';
+    scale?: number;
+    quality?: number;
+    filename?: string;
+    pages?: ('front' | 'back')[];
+    includeBleed?: boolean;
+    bleedSize?: number;
+}
+/**
+ * Result from an export operation
+ */
+interface ExportResult {
+    success: boolean;
+    blob?: Blob;
+    dataUrl?: string;
+    error?: string;
+}
+/**
+ * Props for IDCardGenerator - renders a filled ID card
+ */
+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
+ */
+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
+ */
+interface FieldDefinition {
+    key: string;
+    label: string;
+    type: FieldType;
+    defaultStyle?: FieldStyle;
+    required?: boolean;
+}
+/**
+ * Props for IDCardPreview - interactive card preview with editing
+ */
+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
+ */
+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
+ */
+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
+ */
+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;
+}
+interface TemplateStorage {
+    save: (key: string, template: IDCardTemplate) => Promise<void>;
+    load: (key: string) => Promise<IDCardTemplate | null>;
+    list: () => Promise<string[]>;
+    remove: (key: string) => Promise<void>;
+}
+interface DragState {
+    isDragging: boolean;
+    startX: number;
+    startY: number;
+    currentX: number;
+    currentY: number;
+    fieldId: string | null;
+}
+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;
+}
+
+/**
+ * IDCardGenerator - Renders a completed ID card
+ *
+ * Takes a template and user data, then renders the filled card.
+ * This is the component used to display actual ID cards for individual users.
+ *
+ * Example:
+ * ```tsx
+ * <IDCardGenerator
+ *   template={myTemplate}
+ *   data={{ name: 'John Doe', photo: '...' }}
+ *   side="front"
+ * />
+ * ```
+ */
+declare const IDCardGenerator: React.FC<IDCardGeneratorProps>;
+
+/**
+ * IDCardDesigner - Visual drag-and-drop template builder
+ *
+ * Allows users to:
+ * - Add and position fields on the card
+ * - Upload background images
+ * - Configure field styles (fonts, colors, etc.)
+ * - Choose card orientation and sides
+ * - Preview the card with sample data
+ */
+/**
+ * IDCardDesigner - Visual drag-and-drop ID card template builder
+ */
+declare const IDCardDesigner: React.FC<IDCardDesignerProps>;
+
+/**
+ * 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
+ */
+declare const IDCardPreview: React.FC<IDCardPreviewProps>;
+
+/**
+ * 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
+ */
+declare function useIDCardTemplate(initialTemplate?: Partial<IDCardTemplate>): UseIDCardTemplateReturn;
+
+interface ExportConfig {
+    frontElementId?: string;
+    backElementId?: string;
+    data?: IDCardData;
+    qrElementId?: string;
+    qrFields?: string[];
+}
+declare function useIDCardExport(config?: ExportConfig): UseIDCardExportReturn;
+
+interface UseFieldMappingOptions {
+    onFieldUpdate?: (field: FieldMapping) => void;
+    containerRef?: React.RefObject<HTMLElement>;
+    gridSize?: number;
+    snapToGrid?: boolean;
+}
+declare function useFieldMapping(options?: UseFieldMappingOptions): UseFieldMappingReturn;
+
+/**
+ * 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
+ */
+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
+ */
+declare function generateQrCodeFromFields(data: IDCardData, fields: string[], size?: number): string;
+/**
+ * Set QR code image src on a DOM element
+ */
+declare function setQrCodeOnElement(elementId: string, data: Record<string, unknown>, size?: number, container?: Document | HTMLElement): boolean;
+
+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
+ */
+declare function downloadIDCardAsPDF(options: DownloadIDCardOptions): Promise<ExportResult>;
+/**
+ * Download ID card as image (PNG or JPEG)
+ */
+declare function downloadIDCardAsImage(options: DownloadIDCardOptions): Promise<ExportResult>;
+/**
+ * Export ID card with unified options
+ */
+declare function exportIDCard(options: ExportOptions & {
+    frontElementId?: string;
+    backElementId?: string;
+    data?: IDCardData;
+    qrElementId?: string;
+    qrFields?: string[];
+}): Promise<ExportResult>;
+
+/**
+ * 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
+ */
+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
+ */
+declare function loadTemplateFromLocal(key: string): IDCardTemplate | null;
+/**
+ * Get all saved template keys from localStorage
+ * @returns Array of template keys (without the prefix)
+ */
+declare function listTemplatesFromLocal(): string[];
+/**
+ * Remove a template from localStorage
+ * @param key - Template identifier to remove
+ */
+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)
+ */
+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
+ */
+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
+ */
+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'
+ */
+declare function generateId(prefix?: string): string;
+/**
+ * Create a default template
+ */
+declare function createDefaultTemplate(name?: string): IDCardTemplate;
+
+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)
+ */
+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
+ */
+declare function validateField(field: FieldMapping, index: number): ValidationError[];
+/**
+ * Validate card size against standard dimensions
+ */
+declare function validateCardSize(size: CardSize): boolean;
+/**
+ * Check if a field is within card bounds
+ */
+declare function isFieldInBounds(field: FieldMapping, cardSize: CardSize): boolean;
+
+/**
+ * Convert a style object with kebab-case keys to React camelCase
+ * Useful when importing styles from external sources
+ */
+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
+ */
+declare function fieldStyleToCSS(style: FieldStyle | undefined): React.CSSProperties;
+/**
+ * Merge multiple style objects
+ */
+declare function mergeStyles(...styles: (React.CSSProperties | undefined)[]): React.CSSProperties;
+/**
+ * Generate position styles from field position
+ */
+declare function positionToStyle(position: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}): React.CSSProperties;
+/**
+ * Default styles for different field types
+ */
+declare const defaultFieldStyles: Record<string, FieldStyle>;
+/**
+ * CSS class name generator
+ */
+declare function cn(...classes: (string | undefined | null | false)[]): string;
+
+export { IDCardDesigner, IDCardGenerator, IDCardPreview, cn, createDefaultTemplate, defaultFieldStyles, downloadIDCardAsImage, downloadIDCardAsPDF, exportIDCard, exportTemplateAsJSON, fieldStyleToCSS, generateId, generateQrCodeDataURL, generateQrCodeFromFields, imageFileToBase64, importTemplateFromJSON, isFieldInBounds, listTemplatesFromLocal, loadTemplateFromLocal, mergeStyles, positionToStyle, removeTemplateFromLocal, saveTemplateToLocal, setQrCodeOnElement, toReactStyle, useFieldMapping, useIDCardExport, useIDCardTemplate, validateCardSize, validateField, validateTemplate };
+export type { CardBackground, CardOrientation, CardSides, CardSize, DragState, ExportOptions, ExportResult, FieldDefinition, FieldMapping, FieldPosition, FieldStyle, FieldType, IDCardData, IDCardDesignerProps, IDCardGeneratorProps, IDCardPreviewProps, IDCardTemplate, ResizeState, TemplateStorage, UseFieldMappingReturn, UseIDCardExportReturn, UseIDCardTemplateReturn };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-id-card-generator",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "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",
@@ -10,6 +10,10 @@
       "import": "./dist/esm/index.js",
       "require": "./dist/cjs/index.js",
       "types": "./dist/types/index.d.ts"
+    },
+    "./styles.css": {
+      "import": "./dist/esm/styles.css",
+      "require": "./dist/cjs/styles.css"
     }
   },
   "files": [