@qr-platform/qr-code.js 0.9.10 → 0.10.1

package/lib/license/LicenseManager.d.ts

@@ -10,7 +10,7 @@ export interface ValidationResult {
 }
 export declare class LicenseManager {
     private static _instance;
-    private static _defaultLicenseApiUrl;
+    private static _customLicenseApiUrl;
     private static _currentHostname;
     private _hls;
     private _decodedToken;

package/lib/node/config/runtime-config.d.ts

@@ -0,0 +1,3 @@
+export const SERVICE_ENDPOINT: "https://api.qr-platform.com";
+export const GET_DATAURL_ROUTE: "/v1/utils/get-dataurl?url=";
+export const GET_LICENSE_TOKEN_ROUTE: "/v1/license/get-token";

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

@@ -1,7 +1,13 @@
 import { CanvasOptions } from '~/utils/canvas-options';
-import { RecursivePartial } from '../types/helper';
+import { MethodOverrideOptions, RecursivePartial } from '../types/helper';
 import { StyleOptions } from '../types/style-options';
-import { Options } from '../utils/options';
+import { QRTextTemplateDefinition, TextOptions } from '../types/text-options';
+import { BorderOptions, Options } from '../utils/options';
+import { findStyleById, findStyleByName, QRStyleDefinition } from './templates/qr-styles';
+import { findBorderById, findBorderByName } from './templates/qr-template-borders';
+import { findTextByName, findTextById as findTextTemplateById } from './templates/qr-template-text';
+import { findTemplateById, findTemplateByName, type QRTemplateDefinition } from './templates/qr-templates';
+export type { QRTemplateDefinition, QRStyleDefinition, QRTextTemplateDefinition, StyleOptions };
 export declare enum FileExtension {
     svg = "svg",
     png = "png",
@@ -13,30 +19,99 @@ export declare class QRCodeJs {
     /** Library version injected at build time */
     static version: string;
     private static _selectedTemplate;
+    private static _selectedBorder;
     private static _selectedStyle;
+    private static _selectedImage;
+    private static _selectedImageOverride;
+    private static _selectedText;
+    private static _selectedTextOverride;
     private options;
     private container?;
     private qr?;
     private extension?;
     private svgDrawingPromise?;
     private qrSVG?;
+    private _svgId;
     get size(): {
         width: number;
         height: number;
     } | undefined;
     constructor(options: RecursivePartial<Options>, _?: boolean);
-    static setTemplate(templateNameOrOptions: string | RecursivePartial<Options>): typeof QRCodeJs;
+    /**
+     * Sets the static template to be used as a base for new instances,
+     * accepting either a template name or a template options object.
+     * @param templateNameOrOptions - The user-friendly name of the template or a partial options object.
+     * @returns The QRCodeJs class for chaining.
+     */
+    static setTemplate(templateNameOrOptions: string | RecursivePartial<Options> | null): typeof QRCodeJs;
+    /**
+     * Sets the static template to be used as a base for new instances by its ID.
+     * @param templateId - The ID of the template (original key).
+     * @returns The QRCodeJs class for chaining.
+     */
+    static setTemplateId(templateId: string | null): typeof QRCodeJs;
+    static getTemplates(): {
+        findTextTemplateById: typeof findTextTemplateById;
+        findTextByName: typeof findTextByName;
+        findTemplateByName: typeof findTemplateByName;
+        findTemplateById: typeof findTemplateById;
+        findBorderById: typeof findBorderById;
+        findBorderByName: typeof findBorderByName;
+        findStyleById: typeof findStyleById;
+        findStyleByName: typeof findStyleByName;
+        baseTemplates: QRTemplateDefinition[];
+        borderTemplates: QRTemplateDefinition[];
+        styleTemplates: QRStyleDefinition[];
+        textTemplates: QRTextTemplateDefinition[];
+    };
     /**
      * 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.
+     * @param styleNameOrOptions - The name of the style or the StyleOptions object.
+     * @returns The QRCodeJs class for chaining.
+     */
+    static setStyle(styleNameOrOptions: string | StyleOptions | null): typeof QRCodeJs;
+    /**
+     * Sets the static border template to be used as a base for new instances,
+     * accepting either a border template name or a BorderOptions object.
+     * @param borderNameOrOptions - The user-friendly name of the border template or a BorderOptions object.
+     * @returns The QRCodeJs class for chaining.
+     */
+    static setBorder(borderNameOrOptions: string | RecursivePartial<BorderOptions> | null): typeof QRCodeJs;
+    /**
+     * Sets the static border template to be used as a base for new instances by its ID.
+     * @param borderId - The ID of the border template.
+     * @returns The QRCodeJs class for chaining.
+     */
+    static setBorderId(borderId: string | null): typeof QRCodeJs;
+    /**
+     * Sets the static style to be used as a base for new instances by its ID.
+     * @param styleId - The ID of the style.
+     * @returns The QRCodeJs class for chaining.
+     */
+    static setStyleId(styleId: string | null): typeof QRCodeJs;
+    /**
+     * Sets the static image URL to be used as a base for new instances.
+     * @param imageUrl - The URL of the image or null to clear.
+     * @returns The QRCodeJs class for chaining.
+     */
+    static setImage(imageUrl: string | null, overrideOpts?: MethodOverrideOptions): typeof QRCodeJs;
+    /**
+     * Sets the static text template or options to be used for new instances.
+     * @param textNameOrOptions - The name of the text template, a TextOptions object, or null to clear.
+     * @returns The QRCodeJs class for chaining.
+     */
+    static setText(textNameOrOptions: string | TextOptions | null, overrideOpts?: MethodOverrideOptions): typeof QRCodeJs;
+    /**
+     * Sets the static text template to be used for new instances by its ID.
+     * @param textId - The ID of the text template or null to clear.
      * @returns The QRCodeJs class for chaining.
      */
-    static setStyle(styleNameOrOptions: string | StyleOptions): typeof QRCodeJs;
+    static setTextId(textId: string | null, overrideOpts?: MethodOverrideOptions): typeof QRCodeJs;
+    getOptions(): Options;
     update(options?: RecursivePartial<Options>): Promise<void>;
-    append(
-    /** This container will be used for appending of the QR code */
-    container?: HTMLElement): QRCodeJs | undefined;
+    append(container?: HTMLElement): this;
     applyExtension(extension: ExtensionFunction): Promise<void>;
     deleteExtension(): Promise<void>;
     serialize(inverted?: boolean): Promise<string | undefined>;

package/lib/node/core/qr-options-validation.d.ts

@@ -1,5 +1,5 @@
 import { RecursivePartial } from '../types/helper';
-import { Options } from '../utils/options.js';
+import { Options } from '../utils/options';
 export interface ValidationWarning {
     path: string;
     message: string;

package/lib/node/core/qr-svg.d.ts

@@ -19,6 +19,7 @@ type QRSVGOptions = Pick<Options, 'width' | 'height' | 'isResponsive' | 'margin'
 };
 export declare class QRSVG {
     static instanceCount: number;
+    private static readonly FALLBACK_IMAGE_DATA_URL;
     private _element;
     private defs;
     private backgroundMask?;
@@ -53,11 +54,12 @@ export declare class QRSVG {
     drawBackgroundForBorder(padding: number, baseRadius: number): SVGElement | undefined;
     drawDots(filter?: (i: number, j: number) => boolean): void;
     drawCorners(): void;
-    drawImage({ width, height, count, dotSize }: {
+    drawImage({ width, height, count, dotSize, radius }: {
         width: number;
         height: number;
         count: number;
         dotSize: number;
+        radius?: string | number;
     }): Promise<void>;
     createColor({ options, borderOptions, color, additionalRotation, x, y, height, width, name, returnSVGGroup }: {
         options?: Gradient;

package/lib/node/core/templates/qr-styles-dark.d.ts

@@ -0,0 +1,2 @@
+import { QRStyleDefinition } from './qr-styles';
+export declare const qrStyleDarkDefinitions: QRStyleDefinition[];

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

@@ -0,0 +1,9 @@
+import { StyleOptions } from '../../types/style-options';
+export interface QRStyleDefinition {
+    id: string;
+    name: string;
+    style: StyleOptions;
+}
+export declare const qrStyleDefinitions: QRStyleDefinition[];
+export declare function findStyleByName(name: string): QRStyleDefinition | undefined;
+export declare function findStyleById(id: string): QRStyleDefinition | undefined;

package/lib/node/core/templates/qr-template-borders.d.ts

@@ -0,0 +1,4 @@
+import { QRTemplateDefinition } from './qr-templates';
+export declare const qrBorderTemplates: QRTemplateDefinition[];
+export declare function findBorderByName(name: string): QRTemplateDefinition | undefined;
+export declare function findBorderById(id: string): QRTemplateDefinition | undefined;

package/lib/node/core/templates/qr-template-text.d.ts

@@ -0,0 +1,4 @@
+import { QRTextTemplateDefinition } from '../../types/text-options';
+export declare const qrTextTemplates: QRTextTemplateDefinition[];
+export declare function findTextByName(name: string): QRTextTemplateDefinition | undefined;
+export declare function findTextById(id: string): QRTextTemplateDefinition | undefined;

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

@@ -0,0 +1,12 @@
+import { type Options } from '~/utils/options';
+import { RecursivePartial } from '~/types/helper';
+export interface QRTemplateDefinition {
+    id: string;
+    name: string;
+    options: RecursivePartial<Options>;
+}
+export declare const baseQRTemplateOptions: RecursivePartial<Options>;
+export declare const qrTemplates: QRTemplateDefinition[];
+export declare function findTemplateByName(name: string): QRTemplateDefinition | undefined;
+export declare function findTemplateById(id: string): QRTemplateDefinition | undefined;
+export declare const baseQRTemplate: QRTemplateDefinition | undefined;

package/lib/node/demo.d.ts

@@ -0,0 +1 @@
+export declare const initializeQRCode: () => Promise<void>;

package/lib/node/index.d.ts

@@ -1,7 +1,8 @@
 import { QRCodeJs as _QRCodeJs } from './core/qr-code-js';
-import { RecursivePartial } from './types/helper';
+import { MethodOverrideOptions, RecursivePartial } from './types/helper';
 import { StyleOptions } from './types/style-options';
-import { Options, type Options as QRCodeJsOptions } from './utils/options';
+import { TextOptions } from './types/text-options';
+import { type Options as _QRCodeJsOptions, type BorderOptions } from './utils/options';
 import { ScanValidatorResponse } from './utils/scan-validators/abstract-scan-validator';
 import { type DecodedLicenseToken } from './utils/token-validator';
 export { ErrorCorrectionLevel, Mode, TypeNumber } from './lib/qrcode/QRCodeMinimal';
@@ -11,9 +12,13 @@ export { type RecursivePartial } from './types/helper';
 export { type CanvasOptions } from './utils/canvas-options';
 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 { type BorderOptions, // Keep exporting the type
+CornerDotType, CornerSquareType, DotType, ImageMode, ShapeType } from './utils/options.js';
+export type Options = RecursivePartial<_QRCodeJsOptions>;
+export type { Options as QRCodeJsOptions };
+type QRCodeJsConstructor = new (options: Options, internal?: boolean) => QRCodeJs;
 export declare class QRCodeJs extends _QRCodeJs {
-    constructor(options: RecursivePartial<QRCodeJsOptions>, _?: boolean);
+    constructor(options: RecursivePartial<_QRCodeJsOptions>, _?: boolean);
     protected _hls(): boolean;
     static initializeIfNeeded(): Promise<boolean>;
     static get hls(): boolean;
@@ -48,13 +53,19 @@ 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. 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.
+     * Creates a QRCodeBuilder instance initialized with a specific template by its name.
+     * Allows for fluent configuration chaining.
+     * @param templateName - The user-friendly name of the template to start with.
      * @returns A new QRCodeBuilder instance.
      */
-    static useTemplate(templateNameOrOptions: string | RecursivePartial<Options>): QRCodeBuilder;
+    static useTemplate(templateName: string): QRCodeBuilder;
+    /**
+     * Creates a QRCodeBuilder instance initialized with a specific template by its ID.
+     * Allows for fluent configuration chaining.
+     * @param templateId - The ID (original key) of the template to start with.
+     * @returns A new QRCodeBuilder instance.
+     */
+    static useTemplateId(templateId: string): QRCodeBuilder;
     /**
      * Creates a QRCodeBuilder instance initialized with a specific style.
      * Allows for fluent configuration chaining.
@@ -62,37 +73,140 @@ export declare class QRCodeJs extends _QRCodeJs {
      * @returns A new QRCodeBuilder instance.
      */
     static useStyle(styleNameOrOptions: string | StyleOptions): QRCodeBuilder;
+    /**
+     * Creates a QRCodeBuilder instance initialized with a specific style by its ID.
+     * Allows for fluent configuration chaining.
+     * @param styleId - The ID of the predefined style.
+     * @returns A new QRCodeBuilder instance.
+     */
+    static useStyleId(styleId: string): QRCodeBuilder;
+    /**
+     * Creates a QRCodeBuilder instance initialized with specific border options.
+     * Allows for fluent configuration chaining.
+     * @param borderNameOrOptions - The name of the predefined border or a BorderOptions object.
+     * @returns A new QRCodeBuilder instance.
+     */
+    static useBorder(borderNameOrOptions: string | BorderOptions): QRCodeBuilder;
+    /**
+     * Creates a QRCodeBuilder instance initialized with a specific border by its ID.
+     * Allows for fluent configuration chaining.
+     * @param borderId - The ID of the predefined border.
+     * @returns A new QRCodeBuilder instance.
+     */
+    static useBorderId(borderId: string): QRCodeBuilder;
+    /**
+     * Creates a QRCodeBuilder instance initialized with a specific image.
+     * Allows for fluent configuration chaining.
+     * @param imageUrl - The URL or data URL of the image to use.
+     * @returns A new QRCodeBuilder instance.
+     */
+    static useImage(imageUrl: string, overrideOpts?: MethodOverrideOptions): QRCodeBuilder;
+    /**
+     * Creates a QRCodeBuilder instance initialized with specific text options.
+     * Allows for fluent configuration chaining.
+     * @param textNameOrOptions - The name of the predefined text template or a TextOptions object.
+     * @returns A new QRCodeBuilder instance.
+     */
+    static useText(textNameOrOptions: string | TextOptions, overrideOpts?: MethodOverrideOptions): QRCodeBuilder;
+    /**
+     * Creates a QRCodeBuilder instance initialized with a specific text template by its ID.
+     * Allows for fluent configuration chaining.
+     * @param textId - The ID of the predefined text template.
+     * @returns A new QRCodeBuilder instance.
+     */
+    static useTextId(textId: string, overrideOpts?: MethodOverrideOptions): QRCodeBuilder;
 }
 export declare class _ extends QRCodeJs {
     protected _hls(): boolean;
-    constructor(options: QRCodeJsOptions);
+    constructor(options: Options);
 }
 declare class QRCodeBuilder {
-    protected config: RecursivePartial<Options>;
+    private _qrCodeConstructor;
+    protected _templateSource: string | Options | null;
+    protected _borderSource: string | BorderOptions | null;
+    protected _styleSource: string | StyleOptions | null;
+    protected _imageSource: string | null;
+    protected _imageOverride: boolean;
+    protected _textSource: string | TextOptions | null;
+    protected _textOverride: boolean;
+    protected _isTemplateById: boolean;
+    protected _isBorderById: boolean;
+    protected _isStyleById: boolean;
+    protected _isTextById: boolean;
+    protected _initialOptions: Options | null;
     /**
      * Creates a new QRCodeBuilder instance.
+     * @param qrCodeConstructor - The constructor function (QRCodeJs or _) to use for the final instance.
      * @param templateNameOrOptions - Optional name of a predefined template or a partial options object to start with.
      */
-    constructor(templateNameOrOptions?: string | RecursivePartial<Options>);
+    constructor(qrCodeConstructor: QRCodeJsConstructor, templateNameOrOptions?: string | 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.
+     * Sets the template to use by its name. Overwrites any previously set template.
+     * @param templateName - The user-friendly name of the template to apply.
      * @returns The builder instance for chaining.
      */
-    useTemplate(templateNameOrOptions: string | RecursivePartial<Options>): this;
+    useTemplate(templateName: string): this;
     /**
-     * Applies style options to the builder's configuration.
-     * @param styleNameOrOptions - Name of a predefined style or Style options object to apply.
+     * Sets the template to use by its ID. Overwrites any previously set template.
+     * @param templateId - The ID (original key) of the template to apply.
+     * @returns The builder instance for chaining.
+     */
+    useTemplateId(templateId: string): this;
+    /**
+     * Sets the style to use by its name or a style options object. Overwrites any previously set style.
+     * @param styleNameOrOptions - Name of a predefined style or a StyleOptions 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.
+     * Sets the style to use by its ID. Overwrites any previously set style.
+     * @param styleId - ID of the predefined style to apply.
+     * @returns The builder instance for chaining.
+     */
+    useStyleId(styleId: string): this;
+    /**
+     * Sets the border to use by its name or a border options object. Overwrites any previously set border.
+     * @param borderNameOrOptions - Name of a predefined border or a BorderOptions object to apply.
+     * @returns The builder instance for chaining.
+     */
+    useBorder(borderNameOrOptions: string | BorderOptions): this;
+    /**
+     * Sets the border to use by its ID. Overwrites any previously set border.
+     * @param borderId - ID of the predefined border to apply.
+     * @returns The builder instance for chaining.
+     */
+    useBorderId(borderId: string): this;
+    /**
+     * Sets the image to use. Overwrites any previously set image from other sources like templates.
+     * @param imageUrl - The URL or data URL of the image to apply.
      * @returns The builder instance for chaining.
      */
-    options(options: RecursivePartial<Options>): QRCodeJs;
+    useImage(imageUrl: string, overrideOpts?: MethodOverrideOptions): this;
+    /**
+     * Sets the text to use by its name or a text options object. Overwrites any previously set text.
+     * @param textNameOrOptions - Name of a predefined text template or a TextOptions object to apply.
+     * @returns The builder instance for chaining.
+     */
+    useText(textNameOrOptions: string | TextOptions, overrideOpts?: MethodOverrideOptions): this;
+    /**
+     * Sets the text to use by its ID. Overwrites any previously set text.
+     * @param textId - ID of the predefined text template to apply.
+     * @returns The builder instance for chaining.
+     */
+    useTextId(textId: string, overrideOpts?: MethodOverrideOptions): this;
+    /**
+     * Resolves the template, border, style, and image sources and merges them in the correct order.
+     * Order: Base Template -> Selected Template -> Selected Border -> Selected Text -> Selected Style -> Selected Image -> Final Options
+     * @param finalOptions - The final options object passed to .options() or .build().
+     * @returns The fully resolved and merged Options object.
+     */
+    private _resolveAndMergeConfig;
+    /**
+     * Merges the provided options into the builder's configuration and creates the QRCodeJs instance.
+     * @param options - A partial options object to merge as the final step.
+     * @returns The created QRCodeJs instance.
+     */
+    options(options: Options): QRCodeJs;
     /**
      * Builds the QRCodeJs instance with the accumulated configuration.
      * @returns The created QRCodeJs instance.

package/lib/node/license/LicenseManager.d.ts

@@ -10,7 +10,7 @@ export interface ValidationResult {
 }
 export declare class LicenseManager {
     private static _instance;
-    private static _defaultLicenseApiUrl;
+    private static _customLicenseApiUrl;
     private static _currentHostname;
     private _hls;
     private _decodedToken;

package/lib/node/node.d.ts

@@ -1,9 +1,10 @@
 import { QRCodeJs as _QRCodeJs } from './core/qr-code-js';
 import { type ValidationResult } from './license/LicenseManagerNode';
 import type * as _browserUtils from './tools/browser-utils';
-import { RecursivePartial } from './types/helper';
+import { MethodOverrideOptions, RecursivePartial } from './types/helper';
 import { StyleOptions } from './types/style-options';
-import { Options } from './utils/options';
+import { TextOptions } from './types/text-options';
+import { Options, type BorderOptions } from './utils/options';
 import { ImageDataLike } from './utils/scan-validator-worker';
 import { ScanValidatorResponse } from './utils/scan-validators/abstract-scan-validator';
 import { type DecodedLicenseToken } from './utils/token-validator';
@@ -13,9 +14,10 @@ export { FileExtension } from './tools/browser-utils';
 export { type RecursivePartial } from './types/helper';
 export { type CanvasOptions } from './utils/canvas-options';
 export { GradientType, type Gradient } from './utils/gradient';
-export { CornerDotType, CornerSquareType, DotType, ImageMode, ShapeType, type Options } from './utils/options';
+export { CornerDotType, CornerSquareType, DotType, ImageMode, ShapeType, type Options, type BorderOptions } from './utils/options';
 export { ErrorCorrectionPercents } from './utils/qrcode';
 export declare const browserUtils: typeof _browserUtils | undefined;
+type QRCodeJsConstructor = new (options: RecursivePartial<Options>, internal?: boolean) => QRCodeJs;
 export declare class QRCodeJs extends _QRCodeJs {
     static initializeIfNeeded(): Promise<boolean>;
     static get hls(): boolean;
@@ -40,11 +42,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.
+     * @param templateName - The user-friendly name of the template to start with.
      * @returns A new QRCodeBuilder instance.
      */
-    static useTemplate(templateNameOrOptions: string | RecursivePartial<Options>): QRCodeBuilder;
+    static useTemplate(templateName: string): QRCodeBuilder;
+    /**
+     * Creates a QRCodeBuilder instance initialized with a specific template by its ID.
+     * Allows for fluent configuration chaining.
+     * @param templateId - The ID (original key) of the template to start with.
+     * @returns A new QRCodeBuilder instance.
+     */
+    static useTemplateId(templateId: string): QRCodeBuilder;
     /**
      * Creates a QRCodeBuilder instance initialized with a specific style.
      * Allows for fluent configuration chaining.
@@ -52,32 +60,135 @@ export declare class QRCodeJs extends _QRCodeJs {
      * @returns A new QRCodeBuilder instance.
      */
     static useStyle(styleNameOrOptions: string | StyleOptions): QRCodeBuilder;
+    /**
+     * Creates a QRCodeBuilder instance initialized with a specific style by its ID.
+     * Allows for fluent configuration chaining.
+     * @param styleId - The ID of the predefined style.
+     * @returns A new QRCodeBuilder instance.
+     */
+    static useStyleId(styleId: string): QRCodeBuilder;
+    /**
+     * Creates a QRCodeBuilder instance initialized with specific border options.
+     * Allows for fluent configuration chaining.
+     * @param borderNameOrOptions - The name of the predefined border or a BorderOptions object.
+     * @returns A new QRCodeBuilder instance.
+     */
+    static useBorder(borderNameOrOptions: string | BorderOptions): QRCodeBuilder;
+    /**
+     * Creates a QRCodeBuilder instance initialized with a specific border by its ID.
+     * Allows for fluent configuration chaining.
+     * @param borderId - The ID of the predefined border.
+     * @returns A new QRCodeBuilder instance.
+     */
+    static useBorderId(borderId: string): QRCodeBuilder;
+    /**
+     * Creates a QRCodeBuilder instance initialized with a specific image.
+     * Allows for fluent configuration chaining.
+     * @param imageUrl - The URL or data URL of the image to use.
+     * @returns A new QRCodeBuilder instance.
+     */
+    static useImage(imageUrl: string, overrideOpts?: MethodOverrideOptions): QRCodeBuilder;
+    /**
+     * Creates a QRCodeBuilder instance initialized with specific text options.
+     * Allows for fluent configuration chaining.
+     * @param textNameOrOptions - The name of the predefined text template or a TextOptions object.
+     * @returns A new QRCodeBuilder instance.
+     */
+    static useText(textNameOrOptions: string | TextOptions, overrideOpts?: MethodOverrideOptions): QRCodeBuilder;
+    /**
+     * Creates a QRCodeBuilder instance initialized with a specific text template by its ID.
+     * Allows for fluent configuration chaining.
+     * @param textId - The ID of the predefined text template.
+     * @returns A new QRCodeBuilder instance.
+     */
+    static useTextId(textId: string, overrideOpts?: MethodOverrideOptions): QRCodeBuilder;
 }
-declare class QRCodeBuilder {
-    protected config: RecursivePartial<Options>;
+export declare class QRCodeBuilder {
+    private _qrCodeConstructor;
+    protected _templateSource: string | RecursivePartial<Options> | null;
+    protected _borderSource: string | BorderOptions | null;
+    protected _styleSource: string | StyleOptions | null;
+    protected _imageSource: string | null;
+    protected _imageOverride: boolean;
+    protected _textSource: string | TextOptions | null;
+    protected _textOverride: boolean;
+    protected _isTemplateById: boolean;
+    protected _isBorderById: boolean;
+    protected _isStyleById: boolean;
+    protected _isTextById: boolean;
+    protected _initialOptions: RecursivePartial<Options> | null;
     /**
      * Creates a new QRCodeBuilder instance.
+     * @param qrCodeConstructor - The constructor function (QRCodeJs or _) to use for the final instance.
      * @param templateNameOrOptions - Optional name of a predefined template or a partial options object to start with.
      */
-    constructor(templateNameOrOptions?: string | RecursivePartial<Options>);
+    constructor(qrCodeConstructor: QRCodeJsConstructor, 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.
+     * Sets the template to use by its name. Overwrites any previously set template.
+     * @param templateName - The user-friendly name of the template to apply.
      * @returns The builder instance for chaining.
      */
-    useTemplate(templateNameOrOptions: string | RecursivePartial<Options>): this;
+    useTemplate(templateName: string): this;
     /**
-     * Applies style options to the builder's configuration.
-     * @param styleNameOrOptions - Name of a predefined style or Style options object to apply.
+     * Sets the template to use by its ID. Overwrites any previously set template.
+     * @param templateId - The ID (original key) of the template to apply.
+     * @returns The builder instance for chaining.
+     */
+    useTemplateId(templateId: string): this;
+    /**
+     * Sets the style to use by its name or a style options object. Overwrites any previously set style.
+     * @param styleNameOrOptions - Name of a predefined style or a StyleOptions 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.
+     * Sets the style to use by its ID. Overwrites any previously set style.
+     * @param styleId - ID of the predefined style to apply.
      * @returns The builder instance for chaining.
      */
+    useStyleId(styleId: string): this;
+    /**
+     * Sets the border to use by its name or a border options object. Overwrites any previously set border.
+     * @param borderNameOrOptions - Name of a predefined border or a BorderOptions object to apply.
+     * @returns The builder instance for chaining.
+     */
+    useBorder(borderNameOrOptions: string | BorderOptions): this;
+    /**
+     * Sets the border to use by its ID. Overwrites any previously set border.
+     * @param borderId - ID of the predefined border to apply.
+     * @returns The builder instance for chaining.
+     */
+    useBorderId(borderId: string): this;
+    /**
+     * Sets the image to use. Overwrites any previously set image from other sources like templates.
+     * @param imageUrl - The URL or data URL of the image to apply.
+     * @returns The builder instance for chaining.
+     */
+    useImage(imageUrl: string, overrideOpts?: MethodOverrideOptions): this;
+    /**
+     * Sets the text to use by its name or a text options object. Overwrites any previously set text.
+     * @param textNameOrOptions - Name of a predefined text template or a TextOptions object to apply.
+     * @returns The builder instance for chaining.
+     */
+    useText(textNameOrOptions: string | TextOptions, overrideOpts?: MethodOverrideOptions): this;
+    /**
+     * Sets the text to use by its ID. Overwrites any previously set text.
+     * @param textId - ID of the predefined text template to apply.
+     * @returns The builder instance for chaining.
+     */
+    useTextId(textId: string, overrideOpts?: MethodOverrideOptions): this;
+    /**
+     * Resolves the template, border, style, and image sources and merges them in the correct order.
+     * Order: Base Template -> Selected Template -> Selected Border -> Selected Text -> Selected Style -> Selected Image -> Final Options
+     * @param finalOptions - The final options object passed to .options() or .build().
+     * @returns The fully resolved and merged Options object.
+     */
+    private _resolveAndMergeConfig;
+    /**
+     * Merges the provided options into the builder's configuration and creates the QRCodeJs instance.
+     * @param options - A partial options object to merge as the final step.
+     * @returns The created QRCodeJs instance.
+     */
     options(options: RecursivePartial<Options>): QRCodeJs;
     /**
      * Builds the QRCodeJs instance with the accumulated configuration.