@qr-platform/qr-code.js 0.8.20 → 0.8.21

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @qr-platform/qr-code-js
 
+## 0.8.21
+
+### Patch Changes
+
+- dc60e82: Added useTemplate local base template option method and setTemplate global static method for QRCodeJs class
+
 ## 0.8.20
 
 ### Patch Changes

package/docs/examples.md

@@ -37,6 +37,68 @@ if (container && qrCode.svgElement) {
 
 ---
 
+## Using Templates
+
+Templates provide a way to apply a predefined set of options easily. You can use built-in templates or define your own.
+
+**Example 1: Using a Predefined Template ('rounded')**
+
+```javascript
+// filepath: /Users/kurdin/projects/qr-platform/qr-code-js/docs/examples.md
+
+// Set the 'rounded' template globally for subsequent instances
+QRCodeJs.setTemplate('rounded');
+
+const qrUsingTemplate = new QRCodeJs({
+  data: 'Uses the rounded template'
+});
+qrUsingTemplate.append(document.getElementById('template-rounded-container'));
+
+// Note: The template remains set until changed or cleared.
+```
+
+**Example 2: Using a Custom Template Object**
+
+```javascript
+// filepath: /Users/kurdin/projects/qr-platform/qr-code-js/docs/examples.md
+
+const myCustomTemplate = {
+  dotsOptions: { type: 'classy', color: '#8A2BE2' }, // BlueViolet classy dots
+  backgroundOptions: { color: '#FAFAFA' }, // Off-white background
+  cornersSquareOptions: { type: 'dot', color: '#8A2BE2' }
+};
+
+// Set the custom template globally
+QRCodeJs.setTemplate(myCustomTemplate);
+
+const qrCustomTemplate = new QRCodeJs({
+  data: 'Uses a custom template object'
+});
+qrCustomTemplate.append(document.getElementById('template-custom-container'));
+```
+
+**Example 3: Overriding Template Options**
+
+```javascript
+// filepath: /Users/kurdin/projects/qr-platform/qr-code-js/docs/examples.md
+
+// Assume 'dots' template is set globally
+QRCodeJs.setTemplate('dots');
+
+const qrOverrideTemplate = new QRCodeJs({
+  data: 'Overrides template color',
+  // This color will override the black color from the 'dots' template
+  dotsOptions: { color: '#FF4500' } // OrangeRed dots
+});
+qrOverrideTemplate.append(document.getElementById('template-override-container'));
+
+// Remember to clear the template if you don't want it for subsequent QRs
+// QRCodeJs.setTemplate(null); // Or set back to 'basic' or another template
+```
+
+---
+
+
 ## Examples by Option Group
 
 ### Core Options

package/docs/usage-guide.md

@@ -516,6 +516,26 @@ if (validationResult.isValid) {
   Configures a custom function for fetching license tokens.
 
 
+- **`QRCodeJs.setTemplate(templateNameOrOptions: string | RecursivePartial<Options>): void`**
+  Sets a default template to be used for subsequent `QRCodeJs` instances. This template's options will be merged with the options provided during instantiation, with the instantiation options taking precedence. You can provide either the name of a predefined template (e.g., `'rounded'`, `'dots'`) or a custom options object.
+
+  ```typescript
+  // Set a predefined template by name
+  QRCodeJs.setTemplate('rounded');
+  const qr1 = new QRCodeJs({ data: 'Uses rounded template' });
+
+  // Set a custom template object
+  const myTemplate = { dotsOptions: { type: 'classy', color: '#AA00AA' } };
+  QRCodeJs.setTemplate(myTemplate);
+  const qr2 = new QRCodeJs({ data: 'Uses custom classy template' });
+
+  // Clear the template (falls back to basic)
+  // @ts-expect-error - Accessing private static for testing/clearing
+  QRCodeJs._selectedTemplate = null;
+  const qr3 = new QRCodeJs({ data: 'Uses basic template again' });
+  ```
+
+
 ## FAQ
 
 ### How do I handle CORS issues with embedded images?

package/lib/builder/index.d.ts

@@ -0,0 +1,13 @@
+import { QRCodeJs } from '../index';
+import { QRCodeBuilderCore } from './qr-code-builder';
+/**
+ * Builder class specifically for the browser environment.
+ * Extends the core builder and provides the browser QRCodeJs constructor.
+ */
+export declare class QRCodeBuilder extends QRCodeBuilderCore<QRCodeJs> {
+    /**
+     * Creates a new QRCodeBuilder instance for the browser.
+     * @param templateName - Optional name of a predefined template to start with.
+     */
+    constructor(templateName?: string);
+}

package/lib/builder/node.d.ts

@@ -0,0 +1,13 @@
+import { QRCodeJs } from '../node';
+import { QRCodeBuilderCore } from './qr-code-builder';
+/**
+ * Builder class specifically for the Node.js environment.
+ * Extends the core builder and provides the node QRCodeJs constructor.
+ */
+export declare class QRCodeBuilder extends QRCodeBuilderCore<QRCodeJs> {
+    /**
+     * Creates a new QRCodeBuilder instance for Node.js.
+     * @param templateName - Optional name of a predefined template to start with.
+     */
+    constructor(templateName?: string);
+}

package/lib/builder/qr-code-builder.d.ts

@@ -0,0 +1,25 @@
+import { QRCodeJs as QRCodeJsBase } from '../core/qr-code-js';
+import { RecursivePartial } from '../types/helper';
+import { Options } from '../utils/options';
+type QRCodeJsConstructor<T extends QRCodeJsBase = QRCodeJsBase> = new (options: Options) => T;
+/**
+ * Core Builder class for fluently configuring QRCodeJs instances.
+ * This class is generic and requires the specific QRCodeJs constructor to be passed.
+ */
+export declare class QRCodeBuilderCore<T extends QRCodeJsBase> {
+    protected config: RecursivePartial<Options>;
+    protected qrCodeJsConstructor: QRCodeJsConstructor<T>;
+    /**
+     * Creates a new QRCodeBuilderCore instance.
+     * @param qrCodeJsConstructor - The constructor of the specific QRCodeJs class to use.
+     * @param templateName - Optional name of a predefined template to start with.
+     */
+    constructor(qrCodeJsConstructor: QRCodeJsConstructor<T>, templateName?: string);
+    /**
+     * Merges the provided options into the builder's configuration and creates the QRCodeJs instance.
+     * @param options - A partial options object to merge.
+     * @returns The created QRCodeJs instance.
+     */
+    options(options: RecursivePartial<Options>): T;
+}
+export {};

package/lib/core/qr-code-js.d.ts

@@ -9,6 +9,7 @@ export declare enum FileExtension {
 }
 export type ExtensionFunction = (svg: SVGElement, options: RecursivePartial<Options>) => void;
 export declare class QRCodeJs {
+    private static _selectedTemplate;
     private options;
     private container?;
     private qr?;
@@ -20,6 +21,7 @@ export declare class QRCodeJs {
         height: number;
     } | undefined;
     constructor(options: RecursivePartial<Options>);
+    static setTemplate(templateNameOrOptions: string | RecursivePartial<Options>): typeof QRCodeJs;
     update(options?: RecursivePartial<Options>): Promise<void>;
     append(
     /** This container will be used for appending of the QR code */

package/lib/core/qr-templates.d.ts

@@ -4,3 +4,6 @@ export declare const basicQRTemplate: RecursivePartial<Options>;
 export declare const roundedQRTemplate: RecursivePartial<Options>;
 export declare const dotsQRTemplate: RecursivePartial<Options>;
 export declare const classyQRTemplate: RecursivePartial<Options>;
+export declare const qrTemplates: {
+    [key: string]: RecursivePartial<Options>;
+};

package/lib/index.d.ts

@@ -1,3 +1,4 @@
+import { QRCodeBuilder } from './builder';
 import { QRCodeJs as _QRCodeJs } from './core/qr-code-js';
 import { type Options as QRCodeJsOptions } from './utils/options';
 import { ScanValidatorResponse } from './utils/scan-validators/abstract-scan-validator';
@@ -45,6 +46,13 @@ export declare class QRCodeJs extends _QRCodeJs {
     }>;
     validateScanning(validatorId?: string, // Default validator
     debug?: boolean): Promise<ScanValidatorResponse>;
+    /**
+     * Creates a QRCodeBuilder instance initialized with a specific template.
+     * Allows for fluent configuration chaining.
+     * @param templateName - The name of the template to start with.
+     * @returns A new QRCodeBuilder instance.
+     */
+    static useTemplate(templateName: string): QRCodeBuilder;
 }
 export declare class _ extends QRCodeJs {
     protected _hls(): boolean;

package/lib/node.d.ts

@@ -1,3 +1,4 @@
+import { QRCodeBuilder } from './builder/node';
 import { QRCodeJs as _QRCodeJs } from './core/qr-code-js';
 import { type ValidationResult } from './license/LicenseManagerNode';
 import type * as _browserUtils from './tools/browser-utils';
@@ -30,6 +31,13 @@ export declare class QRCodeJs extends _QRCodeJs {
     static setLicenseUrl(url: string): typeof QRCodeJs;
     constructor(options: RecursivePartial<Options>);
     validateScanning(): Promise<ScanValidatorResponse>;
+    /**
+     * Creates a QRCodeBuilder instance initialized with a specific template.
+     * Allows for fluent configuration chaining.
+     * @param templateName - The name of the template to start with.
+     * @returns A new QRCodeBuilder instance.
+     */
+    static useTemplate(templateName: string): QRCodeBuilder;
 }
 export declare class _ extends QRCodeJs {
     protected _hls(): boolean;