qrcodedemo/README.md

# QR Code Generator

A powerful QR code generator with support for custom images, color customization, and SVG export. Built with React and vanilla JavaScript utilities.

## Features

- ✅ **QR Code Generation**: Generate QR codes from any text
- ✅ **Custom Images**: Embed logos or images in the center of QR codes
- ✅ **Color Customization**: Customize foreground and background colors
- ✅ **SVG Export**: Export QR codes as scalable vector graphics
- ✅ **Bitmap Vectorization**: Convert bitmap images to vector paths in SVG
- ✅ **Multiple Formats**: Support for PNG, JPEG, GIF, WebP, and SVG images
- ✅ **Precise Positioning**: Perfect centering with decimal coordinates
- ✅ **Framework Agnostic**: Use with React or vanilla JavaScript

## Installation

```bash
npm install
```

## Usage

### With React

The main React component is located at `src/components/TextAreaComponent.jsx`:

```jsx
import TextAreaComponent from './components/TextAreaComponent';

function App() {
  return (
    <div className="App">
      <h1>QR Code Generator</h1>
      <TextAreaComponent />
    </div>
  );
}
```

### With Vanilla JavaScript

Use the utility functions directly in any JavaScript project:

```javascript
import {
  generateQRCode,
  generateCompleteSVGQRCode,
  downloadSVG,
  fileToDataURL,
  validateImageFile
} from './src/utils/qrCodeUtils.js';

// Generate a basic QR code
const qrCodeUrl = await generateQRCode('Hello World', '#000000', '#FFFFFF');

// Generate QR code with custom image
const svgContent = await generateCompleteSVGQRCode(
  'Hello World',
  'data:image/png;base64,...', // Custom image data URL
  20, // Image size percentage
  '#000000', // Foreground color
  '#FFFFFF'  // Background color
);

// Download as SVG
downloadSVG(svgContent, 'qrcode.svg');
```

## API Reference

### Core Functions

#### `generateQRCode(text, foregroundColor, backgroundColor)`
Generates a QR code as a data URL (PNG format).

- **Parameters:**
  - `text` (string): Text to encode in the QR code
  - `foregroundColor` (string): QR code color (default: '#000000')
  - `backgroundColor` (string): Background color (default: '#FFFFFF')
- **Returns:** Promise<string> - Data URL of the generated QR code

#### `generateSVGQRCode(text, foregroundColor, backgroundColor)`
Generates a QR code as an SVG string.

- **Parameters:**
  - `text` (string): Text to encode in the QR code
  - `foregroundColor` (string): QR code color (default: '#000000')
  - `backgroundColor` (string): Background color (default: '#FFFFFF')
- **Returns:** Promise<string> - SVG string of the generated QR code

#### `generateCompleteSVGQRCode(text, imageUrl, imageSize, foregroundColor, backgroundColor)`
Generates a complete SVG QR code with embedded image.

- **Parameters:**
  - `text` (string): Text to encode in the QR code
  - `imageUrl` (string, optional): Custom image data URL
  - `imageSize` (number): Image size as percentage (0-100, default: 20)
  - `foregroundColor` (string): QR code color (default: '#000000')
  - `backgroundColor` (string): Background color (default: '#FFFFFF')
- **Returns:** Promise<string> - Complete SVG string with embedded image

### Image Processing Functions

#### `addImageToQRCode(qrCodeUrl, imageUrl, imageSize)`
Adds a custom image to a QR code data URL.

- **Parameters:**
  - `qrCodeUrl` (string): The QR code data URL
  - `imageUrl` (string): The custom image data URL
  - `imageSize` (number): Image size as percentage (0-100)
- **Returns:** Promise<string> - Data URL of QR code with embedded image

#### `addImageToSVG(svgString, imageUrl, imageSize)`
Adds a custom image to an SVG QR code.

- **Parameters:**
  - `svgString` (string): The SVG QR code string
  - `imageUrl` (string): The custom image data URL
  - `imageSize` (number): Image size as percentage (0-100)
- **Returns:** Promise<string> - SVG string with embedded image

#### `vectorizeBitmap(img, targetSize, x, y, svgDoc)`
Converts a bitmap image to SVG vector elements.

- **Parameters:**
  - `img` (HTMLImageElement): The image element to vectorize
  - `targetSize` (number): Target size in QR coordinate system
  - `x` (number): X position in QR coordinate system
  - `y` (number): Y position in QR coordinate system
  - `svgDoc` (Document): The SVG document to add elements to
- **Returns:** Promise<Element> - SVG group element containing vectorized image

### Utility Functions

#### `downloadSVG(svgContent, filename)`
Downloads an SVG string as a file.

- **Parameters:**
  - `svgContent` (string): The SVG content to download
  - `filename` (string): The filename for the download (default: 'qrcode.svg')

#### `fileToDataURL(file)`
Converts a file to data URL.

- **Parameters:**
  - `file` (File): The file to convert
- **Returns:** Promise<string> - Data URL of the file

#### `validateImageFile(file, maxSize)`
Validates an image file.

- **Parameters:**
  - `file` (File): The file to validate
  - `maxSize` (number): Maximum file size in bytes (default: 2MB)
- **Returns:** Object - Validation result with success boolean and error message

## Examples

### Basic QR Code Generation

```javascript
import { generateQRCode } from './src/utils/qrCodeUtils.js';

const qrCode = await generateQRCode('https://example.com');
console.log(qrCode); // data:image/png;base64,...
```

### QR Code with Custom Image

```javascript
import { generateCompleteSVGQRCode, downloadSVG } from './src/utils/qrCodeUtils.js';

const svgContent = await generateCompleteSVGQRCode(
  'https://example.com',
  'data:image/svg+xml;base64,...', // Your logo
  25, // 25% of QR code size
  '#1a1a1a', // Dark gray
  '#ffffff'  // White
);

downloadSVG(svgContent, 'company-qrcode.svg');
```

### File Upload and Validation

```javascript
import { fileToDataURL, validateImageFile } from './src/utils/qrCodeUtils.js';

const fileInput = document.getElementById('file-input');
const file = fileInput.files[0];

const validation = validateImageFile(file);
if (validation.success) {
  const dataUrl = await fileToDataURL(file);
  // Use dataUrl for QR code generation
} else {
  alert(validation.error);
}
```

## Vanilla JavaScript Example

See `examples/vanilla-js-example.html` for a complete vanilla JavaScript implementation.

## Standalone Bundle

For projects that need a self-contained solution without external dependencies, we provide a standalone bundle that includes all utilities and dependencies in a single file.

### Bundle Files

The standalone build creates three formats in the `dist/` directory:

- **`qr-code-utils.iife.js`** (28 KB) - Immediately Invoked Function Expression for browser use
- **`qr-code-utils.umd.js`** (28 KB) - Universal Module Definition for Node.js and bundlers  
- **`qr-code-utils.es.js`** (61 KB) - ES Module for modern bundlers and browsers

### Building the Bundle

```bash
# Build standalone bundle
npm run build:standalone

# Build with detailed information
npm run build:standalone:info
```

### Usage Examples

#### Browser (IIFE)
```html
<!DOCTYPE html>
<html>
<head>
    <title>QR Code Generator</title>
</head>
<body>
    <div id="app"></div>
    
    <!-- Load the standalone bundle -->
    <script src="qr-code-utils.iife.js"></script>
    <script>
        // All functions are available on window.QRCodeUtils
        async function generateQR() {
            const qrCode = await window.QRCodeUtils.generateQRCode('Hello World');
            document.getElementById('qr-code').src = qrCode;
        }
        
        generateQR();
    </script>
</body>
</html>
```

#### ES Module
```javascript
import { generateQRCode, generateCompleteSVGQRCode } from './qr-code-utils.es.js';

// Generate basic QR code
const qrCode = await generateQRCode('Hello World');

// Generate QR code with custom image
const svgContent = await generateCompleteSVGQRCode(
    'Hello World',
    'data:image/png;base64,...', // Custom image
    20, // Image size percentage
    '#000000', // Foreground color
    '#FFFFFF'  // Background color
);
```

#### Node.js (UMD)
```javascript
const { generateQRCode } = require('./qr-code-utils.umd.js');

async function generateQR() {
    const qrCode = await generateQRCode('Hello World');
    console.log(qrCode);
}

generateQR();
```

### Standalone Bundle Features

- ✅ **Zero Dependencies**: No need to install `qrcode` or `imagetracer` separately
- ✅ **Framework Agnostic**: Works with React, Vue, Angular, or vanilla JavaScript
- ✅ **CDN Ready**: Can be distributed via CDN
- ✅ **Production Optimized**: Minified and optimized for performance
- ✅ **Multiple Formats**: Choose the format that works best for your use case
- ✅ **Complete API**: All functions from `qrCodeUtils.js` are included

### Use Cases

1. **Static Websites**: Generate QR codes without any build process
2. **CDN Distribution**: Load from CDN for instant use
3. **Node.js Applications**: Generate QR codes on the server
4. **Modern Bundlers**: Tree-shakeable imports for optimized builds

### Complete Example

See `examples/standalone-bundle-example.html` for a complete working example that demonstrates all features of the standalone bundle.

### Bundle Information

The standalone bundle includes:
- **QR Code Generation**: Complete QR code generation with error correction
- **Image Processing**: Custom image embedding with white background
- **Vectorization**: Bitmap to SVG vector conversion
- **File Handling**: File validation and data URL conversion
- **Download Utilities**: SVG download functionality
- **Error Handling**: Comprehensive error handling and validation

For detailed documentation, see [STANDALONE_BUNDLE.md](./STANDALONE_BUNDLE.md).

## Development

### Running the Development Server

```bash
npm run dev
```

### Building for Production

```bash
# Build React app
npm run build

# Build standalone bundle
npm run build:standalone

# Build standalone bundle with detailed info
npm run build:standalone:info
```

### Project Structure

```
src/
├── components/
│   └── TextAreaComponent.jsx    # Main React component
├── utils/
│   └── qrCodeUtils.js          # Pure JavaScript utility functions
├── bundle.js                   # Bundle entry point
├── App.jsx                     # React app entry point
├── main.jsx                    # React app initialization
└── style.css                   # Global styles

examples/
├── vanilla-js-example.html     # Vanilla JavaScript example
└── standalone-bundle-example.html # Standalone bundle example

scripts/
└── build-standalone.js         # Standalone bundle build script

dist/                           # Production build output
├── qr-code-utils.iife.js       # Standalone bundle (IIFE)
├── qr-code-utils.umd.js        # Standalone bundle (UMD)
├── qr-code-utils.es.js         # Standalone bundle (ES Module)
└── bundle-info.json            # Bundle information
```

## Dependencies

- **React**: UI framework
- **Vite**: Build tool and development server
- **qrcode**: QR code generation library
- **imagetracer**: Bitmap to vector conversion (optional)

## Browser Support

- Modern browsers with ES6 module support
- Canvas API support for image processing
- File API support for file uploads

## License

MIT License - feel free to use this project for any purpose.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## Changelog

### v1.0.0
- Initial release
- QR code generation with custom images
- SVG export with vectorization
- React and vanilla JavaScript support
- Color customization
- Precise coordinate positioning