@qr-styled/browser 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luis Manuel Yerena Sosa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,341 @@
+# @qr-styled/browser
+
+[![npm version](https://img.shields.io/npm/v/@qr-styled/browser.svg)](https://www.npmjs.com/package/@qr-styled/browser)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A professional browser QR code generator library with advanced styling options including **gradients**, **rounded modules**, **logo support**, **specialized QR types** (vCard, WiFi, Email, SMS, Geo), and **eye customization**.
+
+## Features
+
+✅ **Browser-native** - Uses HTML5 Canvas API
+✅ **PNG/JPEG export** - Download or convert to Blob/DataURL
+✅ **SVG support** - Vector graphics export
+✅ **Custom colors & gradients** - Multi-color linear gradients
+✅ **Logo integration** - Circle/square shapes, customizable size
+✅ **Eye customization** - Custom colors and corner radius
+✅ **Rounded modules** - Smooth, professional appearance
+✅ **Specialized QR types** - vCard, WiFi, Email, SMS, Geo
+✅ **TypeScript** - Full type safety
+✅ **Zero dependencies** - Only `qrcode` library
+
+## Installation
+
+```bash
+npm install @qr-styled/browser
+```
+
+## Quick Start
+
+```typescript
+import { QRGenerator } from '@qr-styled/browser';
+
+const qr = new QRGenerator({
+  url: 'https://example.com',
+  size: 400,
+  foregroundColor: '#1a73e8',
+  backgroundColor: '#ffffff',
+  rounded: true
+});
+
+// Append to DOM
+await qr.appendTo(document.body);
+
+// Download as PNG
+await qr.download('qrcode.png');
+
+// Get as Blob
+const blob = await qr.generateToBlob();
+
+// Get as Data URL
+const dataURL = await qr.generateToDataURL();
+```
+
+## API Reference
+
+### Constructor
+
+```typescript
+new QRGenerator(options: QROptions)
+```
+
+### Methods
+
+#### `generate(): Promise<HTMLCanvasElement>`
+Generates and returns the QR code canvas element.
+
+#### `appendTo(element: HTMLElement): Promise<HTMLCanvasElement>`
+Generates the QR code and appends it to the specified DOM element.
+
+#### `generateToDataURL(format?: 'png' | 'jpeg'): Promise<string>`
+Generates a data URL of the QR code.
+
+#### `generateToBlob(format?: 'png' | 'jpeg'): Promise<Blob>`
+Generates a Blob of the QR code image.
+
+#### `download(filename?: string): Promise<void>`
+Generates and downloads the QR code as an image file.
+
+#### `generateToSVG(): Promise<string>`
+Generates an SVG string of the QR code.
+
+#### `downloadSVG(filename?: string): Promise<void>`
+Generates and downloads the QR code as an SVG file.
+
+#### `updateOptions(options: Partial<QROptions>): void`
+Updates the generator options.
+
+### Helper Functions
+
+```typescript
+// Quick generation
+import { generateQR, generateQRToElement, generateQRAndDownload } from '@qr-styled/browser';
+
+// Generate canvas
+const canvas = await generateQR({ url: 'https://example.com' });
+
+// Generate and append to DOM
+const canvas = await generateQRToElement({ url: 'https://example.com' }, document.body);
+
+// Generate and download
+await generateQRAndDownload({ url: 'https://example.com' }, 'qrcode.png');
+```
+
+## Options
+
+### Basic Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `url` | `string` | - | URL or text content |
+| `type` | `QRDataType` | `'url'` | Type of QR data |
+| `size` | `number` | `400` | Canvas size in pixels |
+| `foregroundColor` | `string` | `'#000000'` | QR code color |
+| `backgroundColor` | `string` | `'#ffffff'` | Background color |
+| `padding` | `number` | `20` | Canvas padding |
+| `margin` | `number` | `4` | QR quiet zone (modules) |
+| `errorCorrectionLevel` | `'L'\|'M'\|'Q'\|'H'` | `'M'` | Error correction |
+
+### Styling Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `rounded` | `boolean` | `false` | Use rounded corners |
+| `moduleRadius` | `number` | `0.5` | Module corner radius (0-0.5) |
+| `cornerRadius` | `number` | `30` | Background corner radius |
+| `gradient` | `boolean` | `false` | Enable gradient |
+| `gradientColors` | `string` | - | Comma-separated colors |
+| `gradientAngle` | `number` | `45` | Gradient angle |
+
+### Logo Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `logo` | `string\|HTMLImageElement` | - | Logo path/URL or image element |
+| `logoSize` | `number` | - | Logo size override |
+| `logoPadding` | `number` | `20` | Padding around logo |
+| `logoShape` | `'circle'\|'square'` | `'circle'` | Logo background shape |
+| `logoRadius` | `number` | `10` | Square logo corner radius |
+
+### Eye Customization
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `eyeColor` | `string` | - | Custom eye (finder) color |
+| `eyeRadius` | `number` | - | Custom eye corner radius |
+
+## Examples
+
+### Basic QR Code
+
+```typescript
+const qr = new QRGenerator({
+  url: 'https://example.com',
+  size: 400
+});
+
+await qr.appendTo(document.getElementById('qr-container'));
+```
+
+### Gradient QR Code
+
+```typescript
+const qr = new QRGenerator({
+  url: 'https://example.com',
+  size: 400,
+  gradient: true,
+  gradientColors: '#667eea, #764ba2, #f093fb',
+  gradientAngle: 135,
+  rounded: true
+});
+
+await qr.download('gradient-qr.png');
+```
+
+### QR Code with Logo
+
+```typescript
+const qr = new QRGenerator({
+  url: 'https://example.com',
+  size: 400,
+  foregroundColor: '#1a73e8',
+  logo: 'https://example.com/logo.png',
+  logoShape: 'circle',
+  rounded: true
+});
+
+const blob = await qr.generateToBlob();
+```
+
+### Using HTMLImageElement
+
+```typescript
+const img = new Image();
+img.src = 'logo.png';
+await img.decode();
+
+const qr = new QRGenerator({
+  url: 'https://example.com',
+  size: 400,
+  logo: img
+});
+
+await qr.appendTo(document.body);
+```
+
+### vCard Contact QR
+
+```typescript
+import { QRGenerator, formatVCard } from '@qr-styled/browser';
+
+const qr = new QRGenerator({
+  type: 'vcard',
+  data: {
+    firstName: 'John',
+    lastName: 'Doe',
+    organization: 'Company Inc.',
+    phone: '+1234567890',
+    email: 'john@example.com',
+    url: 'https://johndoe.com'
+  },
+  size: 400,
+  gradient: true,
+  gradientColors: '#667eea, #764ba2'
+});
+
+await qr.download('contact.png');
+```
+
+### WiFi QR Code
+
+```typescript
+const qr = new QRGenerator({
+  type: 'wifi',
+  data: {
+    ssid: 'MyNetwork',
+    password: 'mypassword',
+    encryption: 'WPA'
+  },
+  size: 400,
+  foregroundColor: '#2196f3'
+});
+
+await qr.appendTo(document.body);
+```
+
+### SVG Export
+
+```typescript
+const qr = new QRGenerator({
+  url: 'https://example.com',
+  size: 400,
+  foregroundColor: '#ff5722'
+});
+
+const svg = await qr.generateToSVG();
+console.log(svg); // SVG string
+
+// Or download directly
+await qr.downloadSVG('qrcode.svg');
+```
+
+### Custom Eyes
+
+```typescript
+const qr = new QRGenerator({
+  url: 'https://example.com',
+  size: 400,
+  foregroundColor: '#000000',
+  eyeColor: '#ff0000',
+  eyeRadius: 0.5,
+  rounded: true
+});
+
+await qr.download();
+```
+
+## Specialized QR Types
+
+### Email
+
+```typescript
+const qr = new QRGenerator({
+  type: 'email',
+  data: {
+    email: 'hello@example.com',
+    subject: 'Hello',
+    body: 'Message body'
+  }
+});
+```
+
+### SMS
+
+```typescript
+const qr = new QRGenerator({
+  type: 'sms',
+  data: {
+    phone: '+1234567890',
+    message: 'Hello from QR'
+  }
+});
+```
+
+### Geolocation
+
+```typescript
+const qr = new QRGenerator({
+  type: 'geo',
+  data: {
+    latitude: 40.7128,
+    longitude: -74.0060
+  }
+});
+```
+
+## Browser Compatibility
+
+- Chrome/Edge 90+
+- Firefox 88+
+- Safari 14+
+- Opera 76+
+
+Requires support for:
+- HTML5 Canvas API
+- ES2020+ features
+- Promises/async-await
+
+## Related Packages
+
+- [@qr-styled/node](../node) - Node.js version with PNG/JPEG file export
+
+## License
+
+MIT © Luis Manuel Yerena Sosa
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
+
+## Repository
+
+[https://github.com/Luisma92/qr-styled](https://github.com/Luisma92/qr-styled)

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { QRGenerator, generateQR, generateQRToElement, generateQRAndDownload } from './lib/QRGenerator.js';
+export type { QROptions, QRDataType, VCardData, WiFiData, EmailData, SMSData, GeoData } from './lib/utils/types.js';
+export { formatVCard, formatWiFi, formatEmail, formatSMS, formatGeo } from './lib/utils/formatters.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { QRGenerator, generateQR, generateQRToElement, generateQRAndDownload } from './lib/QRGenerator.js';
+export { formatVCard, formatWiFi, formatEmail, formatSMS, formatGeo } from './lib/utils/formatters.js';

package/dist/lib/QRGenerator.d.ts

@@ -0,0 +1,59 @@
+import { QROptions } from './utils/types.js';
+/**
+ * QR Code Generator with advanced styling options for browsers
+ */
+export declare class QRGenerator {
+    private options;
+    /**
+     * Creates a new QR generator instance
+     */
+    constructor(options: QROptions);
+    /**
+     * Generates QR code content from options
+     */
+    private getQRContent;
+    /**
+     * Generates QR code and returns the canvas
+     */
+    generate(): Promise<HTMLCanvasElement>;
+    /**
+     * Generates QR code and returns data URL
+     */
+    generateToDataURL(format?: 'png' | 'jpeg'): Promise<string>;
+    /**
+     * Generates QR code and returns Blob
+     */
+    generateToBlob(format?: 'png' | 'jpeg'): Promise<Blob>;
+    /**
+     * Generates QR code and downloads it as an image file
+     */
+    download(filename?: string): Promise<void>;
+    /**
+     * Generates QR code as SVG string
+     */
+    generateToSVG(): Promise<string>;
+    /**
+     * Generates QR code as SVG and downloads it
+     */
+    downloadSVG(filename?: string): Promise<void>;
+    /**
+     * Appends the generated QR code canvas to a DOM element
+     */
+    appendTo(element: HTMLElement): Promise<HTMLCanvasElement>;
+    /**
+     * Updates generator options
+     */
+    updateOptions(options: Partial<QROptions>): void;
+}
+/**
+ * Helper function to quickly generate a QR code
+ */
+export declare function generateQR(options: QROptions): Promise<HTMLCanvasElement>;
+/**
+ * Helper function to quickly generate and append QR code to DOM
+ */
+export declare function generateQRToElement(options: QROptions, element: HTMLElement): Promise<HTMLCanvasElement>;
+/**
+ * Helper function to quickly generate and download QR code
+ */
+export declare function generateQRAndDownload(options: QROptions, filename?: string): Promise<void>;

package/dist/lib/QRGenerator.js

@@ -0,0 +1,184 @@
+import QRCode from 'qrcode';
+import { BackgroundRenderer } from './renderers/BackgroundRenderer.js';
+import { GradientRenderer } from './renderers/GradientRenderer.js';
+import { ModuleRenderer } from './renderers/ModuleRenderer.js';
+import { LogoRenderer } from './renderers/LogoRenderer.js';
+import { SVGRenderer } from './renderers/SVGRenderer.js';
+import { DEFAULT_OPTIONS } from './utils/types.js';
+import { validateOptions, normalizeOptions } from './utils/validators.js';
+import { formatQRData } from './utils/formatters.js';
+/**
+ * QR Code Generator with advanced styling options for browsers
+ */
+export class QRGenerator {
+    /**
+     * Creates a new QR generator instance
+     */
+    constructor(options) {
+        this.options = normalizeOptions(options, DEFAULT_OPTIONS);
+        // Support deprecated 'color' field with backward compatibility
+        if (options.color && !options.foregroundColor) {
+            this.options.foregroundColor = options.color;
+        }
+        validateOptions(this.options);
+    }
+    /**
+     * Generates QR code content from options
+     */
+    getQRContent() {
+        const { type, url, data } = this.options;
+        // Use formatter to handle different data types
+        return formatQRData(type, url, data);
+    }
+    /**
+     * Generates QR code and returns the canvas
+     */
+    async generate() {
+        const { errorCorrectionLevel, size, padding, foregroundColor } = this.options;
+        const qrSize = size - padding * 2;
+        // Get formatted content based on type
+        const content = this.getQRContent();
+        // Generate QR data
+        const qrData = await QRCode.create(content, {
+            errorCorrectionLevel
+        });
+        const modules = qrData.modules;
+        const moduleCount = modules.size;
+        const moduleSize = qrSize / moduleCount;
+        // Create canvas
+        const canvas = document.createElement('canvas');
+        canvas.width = size;
+        canvas.height = size;
+        const ctx = canvas.getContext('2d');
+        if (!ctx) {
+            throw new Error('Failed to get 2D context from canvas. Canvas API may not be supported in this environment.');
+        }
+        // Render background
+        const backgroundRenderer = new BackgroundRenderer(ctx, this.options);
+        backgroundRenderer.render();
+        backgroundRenderer.applyClipping();
+        // Create fill style (gradient or solid)
+        const gradientRenderer = new GradientRenderer(ctx, this.options);
+        const fillStyle = gradientRenderer.getFillStyle();
+        // Render QR modules with eye customization support
+        const moduleRenderer = new ModuleRenderer(ctx, modules, {
+            ...this.options,
+            color: foregroundColor, // Use new foregroundColor
+            moduleCount,
+            moduleSize
+        });
+        moduleRenderer.render(fillStyle);
+        backgroundRenderer.restoreClipping();
+        // Render logo if provided
+        if (this.options.logo) {
+            const logoRenderer = new LogoRenderer(ctx, this.options);
+            await logoRenderer.render(this.options.logo);
+        }
+        return canvas;
+    }
+    /**
+     * Generates QR code and returns data URL
+     */
+    async generateToDataURL(format = 'png') {
+        const canvas = await this.generate();
+        if (format === 'jpeg') {
+            return canvas.toDataURL('image/jpeg');
+        }
+        return canvas.toDataURL('image/png');
+    }
+    /**
+     * Generates QR code and returns Blob
+     */
+    async generateToBlob(format = 'png') {
+        const canvas = await this.generate();
+        return new Promise((resolve, reject) => {
+            canvas.toBlob(blob => {
+                if (blob) {
+                    resolve(blob);
+                }
+                else {
+                    reject(new Error('Failed to generate blob'));
+                }
+            }, format === 'jpeg' ? 'image/jpeg' : 'image/png');
+        });
+    }
+    /**
+     * Generates QR code and downloads it as an image file
+     */
+    async download(filename = 'qrcode.png') {
+        const format = filename.endsWith('.jpeg') || filename.endsWith('.jpg') ? 'jpeg' : 'png';
+        const dataURL = await this.generateToDataURL(format);
+        const link = document.createElement('a');
+        link.href = dataURL;
+        link.download = filename;
+        link.click();
+    }
+    /**
+     * Generates QR code as SVG string
+     */
+    async generateToSVG() {
+        const { errorCorrectionLevel, size } = this.options;
+        // Get formatted content based on type
+        const content = this.getQRContent();
+        // Generate QR data
+        const qrData = await QRCode.create(content, {
+            errorCorrectionLevel
+        });
+        // Use SVG renderer
+        const svgRenderer = new SVGRenderer(qrData, this.options, size);
+        return svgRenderer.generate();
+    }
+    /**
+     * Generates QR code as SVG and downloads it
+     */
+    async downloadSVG(filename = 'qrcode.svg') {
+        const svg = await this.generateToSVG();
+        const blob = new Blob([svg], { type: 'image/svg+xml' });
+        const url = URL.createObjectURL(blob);
+        const link = document.createElement('a');
+        link.href = url;
+        link.download = filename;
+        link.click();
+        URL.revokeObjectURL(url);
+    }
+    /**
+     * Appends the generated QR code canvas to a DOM element
+     */
+    async appendTo(element) {
+        const canvas = await this.generate();
+        element.appendChild(canvas);
+        return canvas;
+    }
+    /**
+     * Updates generator options
+     */
+    updateOptions(options) {
+        this.options = normalizeOptions({ ...this.options, ...options }, DEFAULT_OPTIONS);
+        // Support deprecated 'color' field
+        if (options.color && !options.foregroundColor) {
+            this.options.foregroundColor = options.color;
+        }
+        validateOptions(this.options);
+    }
+}
+/**
+ * Helper function to quickly generate a QR code
+ */
+export async function generateQR(options) {
+    const generator = new QRGenerator(options);
+    return generator.generate();
+}
+/**
+ * Helper function to quickly generate and append QR code to DOM
+ */
+export async function generateQRToElement(options, element) {
+    const generator = new QRGenerator(options);
+    return generator.appendTo(element);
+}
+/**
+ * Helper function to quickly generate and download QR code
+ */
+export async function generateQRAndDownload(options, filename) {
+    const generator = new QRGenerator(options);
+    return generator.download(filename);
+}

package/dist/lib/renderers/BackgroundRenderer.d.ts

@@ -0,0 +1,21 @@
+import { QROptions } from '../utils/types.js';
+/**
+ * Handles background rendering for QR codes
+ */
+export declare class BackgroundRenderer {
+    private ctx;
+    private options;
+    constructor(ctx: CanvasRenderingContext2D, options: Required<QROptions>);
+    /**
+     * Renders background with rounded corners
+     */
+    render(): void;
+    /**
+     * Applies clipping path for rounded corners
+     */
+    applyClipping(): void;
+    /**
+     * Restores canvas context after clipping
+     */
+    restoreClipping(): void;
+}

package/dist/lib/renderers/BackgroundRenderer.js

@@ -0,0 +1,47 @@
+/**
+ * Handles background rendering for QR codes
+ */
+export class BackgroundRenderer {
+    constructor(ctx, options) {
+        this.ctx = ctx;
+        this.options = options;
+    }
+    /**
+     * Renders background with rounded corners
+     */
+    render() {
+        const { size, cornerRadius, backgroundColor } = this.options;
+        const ctx = this.ctx;
+        ctx.fillStyle = backgroundColor;
+        ctx.beginPath();
+        ctx.moveTo(cornerRadius, 0);
+        ctx.arcTo(size, 0, size, size, cornerRadius);
+        ctx.arcTo(size, size, 0, size, cornerRadius);
+        ctx.arcTo(0, size, 0, 0, cornerRadius);
+        ctx.arcTo(0, 0, size, 0, cornerRadius);
+        ctx.closePath();
+        ctx.fill();
+    }
+    /**
+     * Applies clipping path for rounded corners
+     */
+    applyClipping() {
+        const { size, cornerRadius } = this.options;
+        const ctx = this.ctx;
+        ctx.save();
+        ctx.beginPath();
+        ctx.moveTo(cornerRadius, 0);
+        ctx.arcTo(size, 0, size, size, cornerRadius);
+        ctx.arcTo(size, size, 0, size, cornerRadius);
+        ctx.arcTo(0, size, 0, 0, cornerRadius);
+        ctx.arcTo(0, 0, size, 0, cornerRadius);
+        ctx.closePath();
+        ctx.clip();
+    }
+    /**
+     * Restores canvas context after clipping
+     */
+    restoreClipping() {
+        this.ctx.restore();
+    }
+}

package/dist/lib/renderers/GradientRenderer.d.ts

@@ -0,0 +1,17 @@
+import { QROptions } from '../utils/types.js';
+/**
+ * Handles gradient creation for QR codes
+ */
+export declare class GradientRenderer {
+    private ctx;
+    private options;
+    constructor(ctx: CanvasRenderingContext2D, options: Required<QROptions>);
+    /**
+     * Creates a gradient fill style
+     */
+    createGradient(): CanvasGradient;
+    /**
+     * Gets the appropriate fill style (gradient or solid color)
+     */
+    getFillStyle(): string | CanvasGradient;
+}