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

package/lib/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/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/core/templates/qr-styles-dark.d.ts

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

package/lib/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/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/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/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/demo.d.ts

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

package/lib/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.