@qr-platform/qr-code.js 0.8.24 → 0.9.0

package/docs/usage-guide.md

@@ -515,6 +515,24 @@ if (validationResult.isValid) {
 - **`QRCodeJs.configureLicenseFetcher(fetcher: (licenseKey: string) => Promise<string>): void`**
   Configures a custom function for fetching license tokens.
 
+- **`QRCodeJs.useTemplate(templateNameOrOptions: string | RecursivePartial<Options>): QRCodeBuilder`**
+  Creates a `QRCodeBuilder` instance initialized with a specific template.
+
+  ```typescript
+  // Using a template name
+  const qrBuilder1 = QRCodeJs.useTemplate('rounded').options({
+    data: 'Built with rounded template',
+    dotsOptions: { color: '#FF8C00' } // DarkOrange override
+  });
+
+  // Using inline options
+  const qrBuilder2 = QRCodeJs.useTemplate({ shape: 'circle' }).options({
+    data: 'Built with inline circle shape'
+  });
+  ```
+
+- **`QRCodeJs.useStyle(styleNameOrOptions: string | StyleOptions): QRCodeBuilder`**
+  Creates a `QRCodeBuilder` instance initialized with a specific style.
 
 - **`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.
@@ -536,6 +554,35 @@ if (validationResult.isValid) {
   ```
 
 
+
+
+## Fluent Builder Pattern (`useTemplate`, `useStyle`, `build`)
+
+For a more structured and readable configuration process, especially when combining predefined settings with custom overrides, QRCode.js offers a fluent builder pattern.
+
+**How it Works:**
+
+1.  **Start:** Begin by calling `QRCodeJs.useTemplate()` or `QRCodeJs.useStyle()` with either a predefined name (e.g., `'rounded'`) or a custom options/style object. This returns a `QRCodeBuilder` instance.
+2.  **Chain (Optional):** Call `.useTemplate()` or `.useStyle()` again on the builder instance to layer additional templates or styles. Options are merged, with later calls overriding earlier ones for the same properties.
+3.  **Finalize:**
+    *   Call `.options(yourOptions)` to merge any final, specific options.
+    *   Or call `.build()` to create the `QRCodeJs` instance with the accumulated configuration. This is optional if `.options(yourOptions)` is NOT called. If `.options(yourOptions)` is called, calling `.build()` is not necessary. You can use `.update()` after `.build()` to update the data.
+
+**Combining Templates and Styles:**
+
+When you chain `useTemplate` and `useStyle`, their options are merged. If both define the same property (e.g., `dotsOptions.color`), the value from the `useStyles` is always applied over the `useTemplate` options (e.g., `dotsOptions.color` from the `useTemplate` is overridden by the `dotsOptions.color` from the `useStyle`).
+
+**Example:**
+
+```typescript
+// Start with 'dots' template, override color with a style, add 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
+  .options({ data: 'Built with Template and Style' }) // Final data
+
+qrCode.append(document.getElementById('builder-example-container'));
+```
+
 ## FAQ
 
 ### How do I handle CORS issues with embedded images?

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

@@ -1,5 +1,6 @@
 import { CanvasOptions } from '~/utils/canvas-options';
 import { RecursivePartial } from '../types/helper';
+import { StyleOptions } from '../types/style-options';
 import { Options } from '../utils/options';
 export declare enum FileExtension {
     svg = "svg",
@@ -12,6 +13,7 @@ export declare class QRCodeJs {
     /** Library version injected at build time */
     static version: string;
     private static _selectedTemplate;
+    private static _selectedStyle;
     private options;
     private container?;
     private qr?;
@@ -24,6 +26,13 @@ export declare class QRCodeJs {
     } | undefined;
     constructor(options: RecursivePartial<Options>);
     static setTemplate(templateNameOrOptions: string | RecursivePartial<Options>): typeof QRCodeJs;
+    /**
+     * Sets the static style to be used as a base for new instances.
+     * Accepts either a predefined style name or a StyleOptions object.
+     * @param styleNameOrOptions - The name of the style or the StyleOptions object.
+     * @returns The QRCodeJs class for chaining.
+     */
+    static setStyle(styleNameOrOptions: string | StyleOptions): typeof QRCodeJs;
     update(options?: RecursivePartial<Options>): Promise<void>;
     append(
     /** This container will be used for appending of the QR code */

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

@@ -0,0 +1,4 @@
+import { StyleOptions } from '../types/style-options';
+export declare const qrStyles: {
+    [key: string]: StyleOptions;
+};

package/lib/index.d.ts

@@ -1,5 +1,6 @@
 import { QRCodeJs as _QRCodeJs } from './core/qr-code-js';
 import { RecursivePartial } from './types/helper';
+import { StyleOptions } from './types/style-options';
 import { Options, type Options as QRCodeJsOptions } from './utils/options';
 import { ScanValidatorResponse } from './utils/scan-validators/abstract-scan-validator';
 import { type DecodedLicenseToken } from './utils/token-validator';
@@ -12,7 +13,7 @@ export { GradientType, type Gradient } from './utils/gradient';
 export { STORAGE_KEY } from './license/LicenseManager';
 export { type BorderOptions, CornerDotType, CornerSquareType, DotType, ImageMode, ShapeType, type Options as QRCodeJsOptions } from './utils/options.js';
 export declare class QRCodeJs extends _QRCodeJs {
-    constructor(options: QRCodeJsOptions);
+    constructor(options: RecursivePartial<QRCodeJsOptions>);
     protected _hls(): boolean;
     static initializeIfNeeded(): Promise<boolean>;
     static get hls(): boolean;
@@ -50,9 +51,17 @@ export declare class QRCodeJs extends _QRCodeJs {
      * Creates a QRCodeBuilder instance initialized with a specific template.
      * Allows for fluent configuration chaining. We need it here to avoid circular dependency
      * @param templateName - The name of the template to start with.
+     * @param templateNameOrOptions - The name of the template or a partial options object to start with.
+     * @returns A new QRCodeBuilder instance.
+     */
+    static useTemplate(templateNameOrOptions: string | RecursivePartial<Options>): QRCodeBuilder;
+    /**
+     * Creates a QRCodeBuilder instance initialized with a specific style.
+     * Allows for fluent configuration chaining.
+     * @param styleNameOrOptions - The name of the predefined style or a StyleOptions object.
      * @returns A new QRCodeBuilder instance.
      */
-    static useTemplate(templateName: string): QRCodeBuilder;
+    static useStyle(styleNameOrOptions: string | StyleOptions): QRCodeBuilder;
 }
 export declare class _ extends QRCodeJs {
     protected _hls(): boolean;
@@ -61,14 +70,32 @@ export declare class _ extends QRCodeJs {
 declare class QRCodeBuilder {
     protected config: RecursivePartial<Options>;
     /**
-     * Creates a new QRCodeBuilderCore instance.
-     * @param templateName - Optional name of a predefined template to start with.
+     * Creates a new QRCodeBuilder instance.
+     * @param templateNameOrOptions - Optional name of a predefined template or a partial options object to start with.
+     */
+    constructor(templateNameOrOptions?: string | RecursivePartial<Options>);
+    /**
+     * Applies a template to the builder's configuration. Template options
+     * will be overridden by subsequently chained .style() or .options() calls.
+     * @param templateNameOrOptions - The name of the template or a partial options object to apply.
+     * @returns The builder instance for chaining.
      */
-    constructor(templateName?: string);
+    useTemplate(templateNameOrOptions: string | RecursivePartial<Options>): this;
     /**
-     * Merges the provided options into the builder's configuration and creates the QRCodeJs instance.
+     * Applies style options to the builder's configuration.
+     * @param styleNameOrOptions - Name of a predefined style or Style options object to apply.
+     * @returns The builder instance for chaining.
+     */
+    useStyle(styleNameOrOptions: string | StyleOptions): this;
+    /**
+     * Merges the provided options into the builder's configuration.
      * @param options - A partial options object to merge.
-     * @returns The created QRCodeJs instance.
+     * @returns The builder instance for chaining.
      */
     options(options: RecursivePartial<Options>): QRCodeJs;
+    /**
+     * Builds the QRCodeJs instance with the accumulated configuration.
+     * @returns The created QRCodeJs instance.
+     */
+    build(): QRCodeJs;
 }