QRCode.js Usage Guide

# Using npm
npm install @qr-platform/qr-code.js

# Using yarn
yarn add @qr-platform/qr-code.js

# Using pnpm
pnpm add @qr-platform/qr-code.js

import { QRCodeJs } from '@qr-platform/qr-code.js';

// Create a basic QR code
const qrCode = new QRCodeJs({
  data: 'https://example.com',
});

// Render the QR code to a container
qrCode.append(document.getElementById('qr-container'));

const qrCode = new QRCodeJs({
  data: 'This QR code uses High error correction',
  shape: 'circle',
  qrOptions: {
    errorCorrectionLevel: 'H' // L, M, Q, H
  }
});

const qrCode = new QRCodeJs({
  data: 'Scaled and Offset QR Code',
  scale: 0.8,           // 80% of the available space
  offset: -10,          // Move QR code 10px up relative to center
  verticalOffset: 5,    // Absolute 5px down
  horizontalOffset: -5  // Absolute 5px left
});

const qrCode = new QRCodeJs({
  data: 'Styled Dots Example',
  dotsOptions: {
    type: 'rounded', // Use rounded dots
    color: '#ff0000', // Red dots
    size: 12         // Slightly larger dots
  }
});

const qrCode = new QRCodeJs({
  data: 'Styled Corners Example',
  dotsOptions: {
    type: 'square',
    color: '#0000ff' // Blue dots
  },
  cornersSquareOptions: {
    type: 'dot',      // Use dot shape for corners
    color: '#00ff00'  // Green corners
  }
});

const qrCode = new QRCodeJs({
  data: 'Styled Corner Dots Example',
  dotsOptions: {
    type: 'square',
    color: '#333333' // Dark grey dots
  },
  cornersSquareOptions: {
    type: 'square',
    color: '#aaaaaa' // Light grey corner squares
  },
  cornersDotOptions: {
    type: 'dot',      // Dot shape for inner corner dots
    color: '#ff00ff'  // Magenta inner corner dots
  }
});

const qrCode = new QRCodeJs({
  data: 'Styled Background Example',
  dotsOptions: {
    color: '#ffffff' // White dots to contrast
  },
  backgroundOptions: {
    color: '#000080', // Navy blue background
    round: 0.5        // Rounded background corners
  }
});
// Example: Transparent Background
const qrCodeTransparent = new QRCodeJs({
  data: 'Transparent Background',
  backgroundOptions: false // Disable background
});

const qrCodeWithGradient = new QRCodeJs({
  data: 'QR Code with Gradient Dots',
  dotsOptions: {
    type: 'rounded',
    gradient: {
      type: 'linear',
      rotation: Math.PI / 4, // 45°
      colorStops: [
        { offset: 0, color: '#0000ff' }, // Blue
        { offset: 1, color: '#00ff00' }  // Green
      ]
    }
  },
  backgroundOptions: {
    gradient: {
      type: 'radial',
      colorStops: [
        { offset: 0, color: '#ffffff' }, // White center
        { offset: 1, color: '#dddddd' }  // Grey edge
      ]
    }
  }
});

const qrCodeWithLogo = new QRCodeJs({
  data: 'https://mybrand.com',
  qrOptions: {
    errorCorrectionLevel: 'H' // High error correction
  },
  image: 'https://mybrand.com/logo.png', // URL or data URI
  imageOptions: {
    imageSize: 0.3, // 30% size
    margin: 2       // 2 block margin
  }
});

const qrCodeWithBorder = new QRCodeJs({
  data: 'QR Code with Fancy Border',
  borderOptions: {
    hasBorder: true,
    thickness: 20,
    color: '#663399', // Rebeccapurple
    radius: '20%',
    borderOuter: { color: '#FFD700', thickness: 2 }, // Gold outer line
    decorations: {
      top: {
        type: 'text',
        value: 'SCAN ME',
        style: { fontColor: '#FFFFFF', fontSize: 16, fontWeight: 'bold' },
        offset: -2 // Slightly up
      },
      bottom: {
        type: 'text',
        value: 'My Website',
        style: { fontColor: '#FFFFFF', fontSize: 14 },
        curveDisabled: false // Follow curve
      }
    }
  }
});

const qrCode = new QRCodeJs({
  data: 'Data to validate'
});

const validationResult = await qrCode.validateScanning();

if (validationResult.isValid) {
  console.log('QR Code is valid! Decoded:', validationResult.data);
  // document.body.appendChild(qrCode.svgElement);
} else {
  console.error('Validation failed:', validationResult.error, validationResult.errorCode);
}

const qrCode = new QRCodeJs({
  data: 'https://example.com/product/123'
});

// Set metadata using chainable methods
qrCode
  .setId('product-qr-123')
  .setName('Product Landing Page QR')
  .setDescription('QR code linking to product details and purchase options')
  .setMetadata({
    productId: '123',
    category: 'electronics',
    campaign: 'summer-sale-2024',
    createdBy: 'marketing-team',
    expires: '2024-12-31'
  });

// Retrieve metadata
console.log('QR ID:', qrCode.getId()); // 'product-qr-123'
console.log('QR Name:', qrCode.getName()); // 'Product Landing Page QR'
console.log('QR Description:', qrCode.getDescription()); // 'QR code linking to product details...'
console.log('Custom Metadata:', qrCode.getMetadata()); 
// { productId: '123', category: 'electronics', ... }

// Get current settings and options
const currentSettings = qrCode.getSettings();
console.log('Current Settings:', currentSettings);

const qrWithMetadata = QRCodeJs.useTemplate('modern')
  .useId('campaign-qr-2024-winter')
  .useName('Winter Campaign Landing')
  .useDescription('QR code for winter marketing campaign landing page')
  .useMetadata({
    campaignId: 'winter-2024',
    targetAudience: 'millennials',
    channels: ['social', 'email', 'print'],
    budget: 10000,
    kpi: 'conversion-rate'
  })
  .options({
    data: 'https://campaign.company.com/winter-2024'
  });

qrWithMetadata.append(document.getElementById('campaign-container'));

function createCMSQR(contentId, contentType, options = {}) {
  return QRCodeJs.useTemplate('cms-standard')
    .useId(`cms-${contentType}-${contentId}`)
    .useName(`${contentType.toUpperCase()} Content #${contentId}`)
    .useDescription(`QR code for ${contentType} content item ${contentId}`)
    .useMetadata({
      contentId,
      contentType,
      createdAt: new Date().toISOString(),
      source: 'cms',
      ...options.metadata
    })
    .options({
      data: `https://cms.company.com/${contentType}/${contentId}`,
      ...options
    });
}

// Usage
const articleQR = createCMSQR('article-456', 'article', {
  metadata: { author: 'john-doe', publishDate: '2024-03-15' }
});

function createEventQR(eventConfig) {
  const builder = QRCodeJs.useTemplate('event')
    .useId(`event-${eventConfig.eventId}`)
    .useName(eventConfig.eventName)
    .useDescription(`QR code for ${eventConfig.eventName} event registration`)
    .useMetadata({
      eventId: eventConfig.eventId,
      eventType: eventConfig.type,
      venue: eventConfig.venue,
      date: eventConfig.date,
      capacity: eventConfig.capacity,
      organizer: eventConfig.organizer
    });

  // Conditional metadata based on event type
  if (eventConfig.type === 'conference') {
    builder.useMetadata({
      speakers: eventConfig.speakers,
      tracks: eventConfig.tracks
    });
  } else if (eventConfig.type === 'workshop') {
    builder.useMetadata({
      instructor: eventConfig.instructor,
      prerequisites: eventConfig.prerequisites
    });
  }

  return builder.options({
    data: `https://events.company.com/register/${eventConfig.eventId}`
  });
}

// Usage
const conferenceQR = createEventQR({
  eventId: 'tech-conf-2024',
  eventName: 'Annual Tech Conference 2024',
  type: 'conference',
  venue: 'Convention Center',
  date: '2024-09-15',
  capacity: 500,
  organizer: 'Tech Corp',
  speakers: ['speaker1', 'speaker2'],
  tracks: ['AI', 'Web Dev', 'Mobile']
});

class ProductQRManager {
  static createProductQR(productData) {
    const metadata = {
      sku: productData.sku,
      category: productData.category,
      brand: productData.brand,
      price: productData.price,
      inStock: productData.inStock,
      trackingEnabled: true,
      createdAt: new Date().toISOString()
    };

    return QRCodeJs.useTemplate('product')
      .useId(`product-${productData.sku}`)
      .useName(`${productData.brand} ${productData.name}`)
      .useDescription(`Product QR for ${productData.name}`)
      .useMetadata(metadata)
      .options({
        data: `https://store.company.com/product/${productData.sku}?ref=qr`,
        image: productData.thumbnailUrl
      });
  }

  static updateProductMetadata(qrInstance, updates) {
    const currentMetadata = qrInstance.getMetadata() || {};
    qrInstance.setMetadata({
      ...currentMetadata,
      ...updates,
      lastUpdated: new Date().toISOString()
    });
  }
}

// Usage
const productQR = ProductQRManager.createProductQR({
  sku: 'LAPTOP-001',
  name: 'Gaming Laptop Pro',
  brand: 'TechBrand',
  category: 'electronics',
  price: 1299.99,
  inStock: true,
  thumbnailUrl: 'https://store.company.com/images/laptop-001-thumb.jpg'
});

// Later update
ProductQRManager.updateProductMetadata(productQR, {
  price: 1199.99,
  inStock: false,
  lastSale: '2024-03-20'
});

// Example metadata schema
const metadataSchema = {
  // Required fields
  id: 'string',
  name: 'string',
  description: 'string',
  
  // Tracking fields
  createdAt: 'ISO 8601 timestamp',
  updatedAt: 'ISO 8601 timestamp',
  createdBy: 'string (user id)',
  
  // Business fields
  campaign: 'string',
  channel: 'string',
  category: 'string',
  
  // Analytics
  trackingEnabled: 'boolean',
  analytics: {
    scans: 'number',
    lastScan: 'ISO 8601 timestamp',
    conversionRate: 'number'
  }
};

// Set global data that will be used if no data is provided at instantiation
QRCodeJs.setData('https://www.default-link.com');

// Set global options for margin and error correction
QRCodeJs.setOptions({
  margin: 15,
  qrOptions: { errorCorrectionLevel: 'M' }
});

// This QR code will use the global data, margin, and error correction level
const qrWithGlobalSettings = new QRCodeJs({}); // Data is optional now
qrWithGlobalSettings.append(document.getElementById('qr-global-container'));

// Override global data with an instance-specific value
const qrOverrideData = new QRCodeJs({ data: 'https://specific-link.com' });
// qrOverrideData will use 'https://specific-link.com', but still use global margin and EC level.

// Using override to make global data sticky
QRCodeJs.setData('https://sticky-link.com', { override: true });
const qrStickyData = new QRCodeJs({ data: 'https://ignored-link.com' });
// qrStickyData will use 'https://sticky-link.com' due to the override.

// Clear global settings when no longer needed
QRCodeJs.setData(null);
QRCodeJs.setOptions(null);

// Example of setting global image
QRCodeJs.setImage('https://example.com/default-logo.png');
const qrWithGlobalImage = new QRCodeJs({ data: 'Uses global image' });
// qrWithGlobalImage will use 'default-logo.png' unless overridden.

// Start with 'dots' template, override color with a style, add an image, then final data
const qrCode = QRCodeJs.useTemplate('dots')       // Base: dots template (e.g., black square dots)
  .useStyle({ dotsOptions: { color: 'navy' } }) // Style: Change dot color to navy
  .useImage('https://example.com/my-logo.png') // Image: Set a logo
  .options({ data: 'Built with Template, Style, and Image' }) // Final data

qrCode.append(document.getElementById('builder-example-container'));


### Builder Pattern Methods (`useTemplate`, `useStyle`, `useBorder`, `useImage`, `useData`, `useOptions`, `useSettings`)

These methods are called on `QRCodeJs` to initiate a builder chain (e.g., `QRCodeJs.useTemplate(...)`) or on an existing `QRCodeBuilder` instance (e.g., `builder.useStyle(...)`).

- **`useTemplate(templateNameOrOptions)` / `useTemplateId(templateId)`**: Start the builder with a predefined template or template ID.
- **`useStyle(styleNameOrOptions)` / `useStyleId(styleId)`**: Applies a style.
- **`useBorder(borderNameOrOptions)` / `useBorderId(borderId)`**: Applies a border configuration.
- **`useText(textNameOrOptions, overrideOpts?)` / `useTextId(textId, overrideOpts?)`**: Sets border text with optional override precedence.
- **`useImage(imageUrl, overrideOpts?)`**: Sets an image. `overrideOpts` ensures precedence over image in final `.options()`.
- **`useData(data, overrideOpts?)`**: Sets the data. `overrideOpts` ensures precedence over data in final `.options()`.
- **`useOptions(options, overrideOpts?)`**: Merges general options. `overrideOpts` ensures precedence for these specific options over final `.options()`.
- **`useId(id)`**, **`useName(name)`**, **`useDescription(description)`**, **`useMetadata(metadata)`**: Attach metadata to the QR code instance when the builder finalizes.
- **`useSettings(settings)`**: Applies a comprehensive `SettingsOptions` object as a new baseline for the builder chain, **resetting** any configurations previously applied to *that builder instance* via other `use...` methods.

You can chain these methods (e.g., `QRCodeJs.useTemplate(...).useStyle(...).useBorder(...).useImage(...)`) before finalizing with `.options(...)` or `.build()`. Options are merged progressively, with later calls overriding earlier ones for the same properties, unless an `override: true` was used.

**Example: Using Builder Methods**
```typescript
// Start with a template, layer on a style, then specific data and options
const qrBuilt = QRCodeJs.useTemplate('dots') // Start with 'dots' template
  .useStyle({ dotsOptions: { color: 'green' } }) // Override dot color to green
  .useData('https://example.com/builder-path') // Set data via builder
  .useOptions({ margin: 5 }) // Set margin via builder
  .options({ qrOptions: { errorCorrectionLevel: 'Q' } }); // Final options, builds the instance

qrBuilt.append(document.getElementById('qr-builder-container'));

// Using useData with override
const qrBuilderDataOverride = QRCodeJs.useTemplate('rounded')
  .useData('https://forced-builder-link.com', { override: true })
  .options({ data: 'https://this-data-is-ignored.com' }); // Data from useData takes precedence

qrBuilderDataOverride.append(document.getElementById('qr-builder-data-override'));

const myCompanyPreset: SettingsOptions = {
  name: 'CompanyStandardQR',
  description: 'Standard QR code style for company communications.',
  data: 'https://company.website.com', // Default data
  image: 'https://company.website.com/assets/logo.png', // Default image
  templateId: 'modern-dark', // Assumes this template ID exists
  style: { dotsOptions: { color: '#00447C' } }, // Company blue dots
  borderOptions: { hasBorder: true, thickness: 10, color: '#00447C' },
  options: { // General options
    margin: 10,
    qrOptions: { errorCorrectionLevel: 'Q' }
  }
};

QRCodeJs.setSettings(myCompanyPreset);

// This instance will use the 'CompanyStandardQR' preset
const qrFromPreset = new QRCodeJs({ /* Data can be omitted if in preset */ });
qrFromPreset.append(document.getElementById('qr-preset-container'));

// Override specific parts of the preset for another instance
const qrModifiedPreset = new QRCodeJs({
  data: 'https://company.website.com/specific-campaign', // Override data
  image: 'https://company.website.com/assets/campaign-logo.png' // Override image
  // Other settings like template, style, border, margin, EC level from preset still apply
});
qrModifiedPreset.append(document.getElementById('qr-modified-preset-container'));

// Clearing all static settings
QRCodeJs.setSettings(null);
const qrAfterClear = new QRCodeJs({ data: 'https://another.link.com/after-clear' }); // Uses base defaults, requires data
qrAfterClear.append(document.getElementById('qr-cleared-container'));

const eventSpecificConfig: SettingsOptions = {
  name: 'TechConference2024',
  data: 'https://techconf.example/schedule', // Baseline data for this builder
  image: 'https://techconf.example/assets/event-banner-qr.png', // Baseline image
  styleId: 'modern-dark', // Assumes 'modern-dark' style ID exists
  text: { // Border text configuration
    topValue: 'Tech Conference 2024',
    bottomValue: 'Scan for Schedule & Info'
  },
  borderOptions: {
    hasBorder: true,
    thickness: 25,
    color: '#333333',
    radius: '5px'
  },
  options: { // Baseline general options
    qrOptions: { errorCorrectionLevel: 'H' },
    isResponsive: true
  }
};

const qrEvent = QRCodeJs.useTemplate('basic') // Initial template (will be reset by useSettings)
  .useStyle({ dotsOptions: { color: 'red'} }) // This style will also be reset
  .useSettings(eventSpecificConfig) // Resets builder and applies eventSpecificConfig as baseline
  .useStyle({ // Further refine the style from useSettings
    dotsOptions: { gradient: { type: 'linear', colorStops: [{offset:0, color:'blue'}, {offset:1, color:'green'}] } }
  })
  .options({ // Final data override and other specific options
    data: 'https://techconf.example/live-updates', // Overrides data from eventSpecificConfig
    margin: 5 // Overrides margin if it was part of eventSpecificConfig.options
  })
  .build();

qrEvent.append(document.getElementById('event-qr-container'));

imageOptions: {
  crossOrigin: 'anonymous'
}

const qrCodeClassy = new QRCodeJs({
  data: 'https://stylish-qr.codes',
  qrOptions: { errorCorrectionLevel: 'H' },
  dotsOptions: {
    type: 'classyRounded',
    gradient: {
      type: 'linear',
      rotation: Math.PI / 3,
      colorStops: [{ offset: 0, color: '#3366FF' }, { offset: 1, color: '#66CCFF' }]
    }
  },
  cornersSquareOptions: {
    type: 'classy',
    gradient: {
      type: 'linear',
      rotation: Math.PI / 3,
      colorStops: [{ offset: 0, color: '#3366FF' }, { offset: 1, color: '#66CCFF' }]
    }
  },
  cornersDotOptions: {
    type: 'classy',
    gradient: {
      type: 'linear',
      rotation: Math.PI / 3,
      colorStops: [{ offset: 0, color: '#3366FF' }, { offset: 1, color: '#66CCFF' }]
    }
  },
  backgroundOptions: { color: '#FFFFFF' },
  image: 'logo.svg',
  imageOptions: { imageSize: 0.25, margin: 1 }
});

const qrCodeCircleStar = new QRCodeJs({
  data: 'Circle with Stars',
  shape: 'circle',
  dotsOptions: {
    type: 'star',
    color: '#FF6600' // Orange stars
  },
  cornersSquareOptions: { type: 'rounded', color: '#FF6600' },
  cornersDotOptions: { type: 'dot', color: '#FF6600' },
  backgroundOptions: false // Transparent
});

const qrCode = new QRCodeJs({
  qrOptions: { errorCorrectionLevel: 'Q' },
  dotsOptions: { type: 'square', color: '#006400' }, // Dark green
  cornersSquareOptions: { type: 'square', color: '#006400' },
  cornersDotOptions: { type: 'square', color: '#006400' },
  backgroundOptions: { color: '#F0FFF0' }, // Honeydew
  borderOptions: {
    hasBorder: true,
    thickness: 25,
    color: '#556B2F', // Dark Olive Green
    radius: '10px',
    borderOuter: { color: '#BDB76B', thickness: 3 }, // Dark Khaki
    borderInner: { color: '#9ACD32', thickness: 1 }, // Yellow Green
    decorations: {
      bottom: {
        type: 'text',
        value: 'SCAN ME',
        style: { fontColor: '#FFFFFF', fontSize: 18, fontWeight: 'bold' },
        curveDisabled: true // Straight text
      }
    }
  }
});