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

package/docs/examples.md

@@ -156,8 +156,6 @@ The builder pattern provides a fluent way to configure QR codes, often starting
 
 **Example 1: Using `useTemplate` with a Predefined Template ('rounded')**
 
-```javascript
-// filepath: /Users/kurdin/projects/qr-platform/qr-code-js/docs/examples.md
 
 const qrFromTemplate = QRCodeJs.useTemplate('rounded') // Start builder with 'rounded' template
   .options({ data: 'Uses the rounded template via builder' }) // Add data
@@ -167,8 +165,6 @@ qrFromTemplate.append(document.getElementById('template-rounded-container'));
 
 **Example 2: Using `useTemplate` with 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
@@ -186,8 +182,6 @@ qrCustomTemplate.append(document.getElementById('template-custom-container'));
 
 **Example 3: Using `useStyle`**
 
-```javascript
-// filepath: /Users/kurdin/projects/qr-platform/qr-code-js/docs/examples.md
 
 const myStyle = {
   dotsOptions: { type: 'dots', color: '#FF4500' }, // OrangeRed dots
@@ -203,8 +197,6 @@ qrFromStyle.append(document.getElementById('style-container'));
 
 **Example 4: Chaining `useTemplate` and `useStyle`**
 
-```javascript
-// filepath: /Users/kurdin/projects/qr-platform/qr-code-js/docs/examples.md
 
 // Start with 'dots' template (black dots), then apply a style to change color
 const qrChained = QRCodeJs.useTemplate('dots')
@@ -225,8 +217,6 @@ Demonstrating fundamental settings like data, shape, and error correction.
 
 **Example 1: Minimal QR Code**
 
-```javascript
-// filepath: /Users/kurdin/projects/qr-platform/qr-code-js/docs/examples.md
 const qrMinimal = new QRCodeJs({
   data: 'Just the data!'
 });
@@ -235,8 +225,6 @@ qrMinimal.append(document.getElementById('minimal-qr-container'));
 
 **Example 2: Circle Shape**
 
-```javascript
-// filepath: /Users/kurdin/projects/qr-platform/qr-code-js/docs/examples.md
 const qrCircle = new QRCodeJs({
   data: 'https://example.com/circle',
   shape: 'circle' // Make the QR code boundary circular
@@ -246,8 +234,6 @@ qrCircle.append(document.getElementById('circle-qr-container'));
 
 **Example 3: High Error Correction**
 
-```javascript
-// filepath: /Users/kurdin/projects/qr-platform/qr-code-js/docs/examples.md
 const qrHighEC = new QRCodeJs({
   data: 'Important Data',
   qrOptions: {
@@ -265,8 +251,6 @@ Controlling margin, scale, and offsets.
 
 **Example 1: Adding Margin**
 
-```javascript
-// filepath: /Users/kurdin/projects/qr-platform/qr-code-js/docs/examples.md
 const qrMargin = new QRCodeJs({
   data: 'With Margin',
   margin: 20 // Add a 20px quiet zone around the QR code
@@ -276,8 +260,6 @@ qrMargin.append(document.getElementById('margin-qr-container'));
 
 **Example 2: Scaling Down**
 
-```javascript
-// filepath: /Users/kurdin/projects/qr-platform/qr-code-js/docs/examples.md
 const qrScaled = new QRCodeJs({
   data: 'Scaled Down',
   scale: 0.8 // Make the QR code 80% of its container/border size
@@ -293,8 +275,6 @@ Changing the appearance of the data dots.
 
 **Example 1: Rounded Dots**
 
-```javascript
-// filepath: /Users/kurdin/projects/qr-platform/qr-code-js/docs/examples.md
 const qrRoundedDots = new QRCodeJs({
   data: 'Rounded Dots',
   dotsOptions: {
@@ -307,8 +287,6 @@ qrRoundedDots.append(document.getElementById('rounded-dots-container'));
 
 **Example 2: Dot Style Dots**
 
-```javascript
-// filepath: /Users/kurdin/projects/qr-platform/qr-code-js/docs/examples.md
 const qrDotDots = new QRCodeJs({
   data: 'Dot Style Dots',
   dotsOptions: {
@@ -325,8 +303,6 @@ qrDotDots.append(document.getElementById('dot-dots-container'));
 
 Customizing the large corner squares.
 
-```javascript
-// filepath: /Users/kurdin/projects/qr-platform/qr-code-js/docs/examples.md
 const qrStyledCorners = new QRCodeJs({
   data: 'Styled Corners',
   dotsOptions: { color: '#333' }, // Standard dots
@@ -344,8 +320,6 @@ qrStyledCorners.append(document.getElementById('styled-corners-container'));
 
 Customizing the small dots inside the corner squares.
 
-```javascript
-// filepath: /Users/kurdin/projects/qr-platform/qr-code-js/docs/examples.md
 const qrStyledCornerDots = new QRCodeJs({
   data: 'Styled Corner Dots',
   dotsOptions: { color: '#4CAF50' }, // Green dots
@@ -366,8 +340,6 @@ Modifying the background color and shape.
 
 **Example 1: Colored Background**
 
-```javascript
-// filepath: /Users/kurdin/projects/qr-platform/qr-code-js/docs/examples.md
 const qrColoredBg = new QRCodeJs({
   data: 'Colored Background',
   dotsOptions: { color: '#FFFFFF' }, // White dots for contrast
@@ -380,8 +352,6 @@ qrColoredBg.append(document.getElementById('colored-bg-container'));
 
 **Example 2: Rounded Background**
 
-```javascript
-// filepath: /Users/kurdin/projects/qr-platform/qr-code-js/docs/examples.md
 const qrRoundedBg = new QRCodeJs({
   data: 'Rounded Background',
   backgroundOptions: {
@@ -395,7 +365,6 @@ qrRoundedBg.append(document.getElementById('rounded-bg-container'));
 **Example 3: Transparent Background**
 
 ```javascript
-// filepath: /Users/kurdin/projects/qr-platform/qr-code-js/docs/examples.md
 const qrTransparentBg = new QRCodeJs({
   data: 'Transparent Background',
   backgroundOptions: false // Disable the background element
@@ -412,7 +381,6 @@ Applying simple gradients.
 **Example 1: Linear Gradient on Dots**
 
 ```javascript
-// filepath: /Users/kurdin/projects/qr-platform/qr-code-js/docs/examples.md
 const qrGradientDots = new QRCodeJs({
   data: 'Gradient Dots',
   dotsOptions: {
@@ -433,7 +401,6 @@ qrGradientDots.append(document.getElementById('gradient-dots-container'));
 **Example 2: Radial Gradient on Background**
 
 ```javascript
-// filepath: /Users/kurdin/projects/qr-platform/qr-code-js/docs/examples.md
 const qrGradientBg = new QRCodeJs({
   data: 'Gradient Background',
   backgroundOptions: {
@@ -455,8 +422,6 @@ qrGradientBg.append(document.getElementById('gradient-bg-container'));
 
 Adding a simple logo.
 
-```javascript
-// filepath: /Users/kurdin/projects/qr-platform/qr-code-js/docs/examples.md
 const qrWithLogo = new QRCodeJs({
   data: 'QR with Logo',
   qrOptions: { errorCorrectionLevel: 'Q' }, // Use Q or H with images
@@ -469,14 +434,82 @@ const qrWithLogo = new QRCodeJs({
 qrWithLogo.append(document.getElementById('logo-qr-container'));
 ```
 
+**Example: Setting a Global Default Image with `setImage`**
+
+```javascript
+// Set a default logo for all subsequent QR codes use url or data url
+QRCodeJs.setImage('https://example.com/default-logo.png');
+
+const qrWithGlobalImage = new QRCodeJs({
+  data: 'This QR uses the global default image'
+});
+qrWithGlobalImage.append(document.getElementById('global-image-container'));
+
+// Override the global image for a specific instance
+const qrOverrideGlobalImage = new QRCodeJs({
+  data: 'This QR overrides the global image',
+  image: 'https://example.com/another-logo.png'
+});
+qrOverrideGlobalImage.append(document.getElementById('override-global-image-container'));
+
+// Clear the global image
+// QRCodeJs.setImage(null);
+```
+
+**Example: Using the Builder Pattern with `useImage`**
+
+```javascript
+const qrBuiltWithImage = QRCodeJs.useImage('https://example.com/builder-logo.png')
+  .options({
+    data: 'This QR was built with a specific image via useImage',
+    qrOptions: { errorCorrectionLevel: 'Q' }
+  });
+qrBuiltWithImage.append(document.getElementById('builder-image-container'));
+
+// Combining with other builder methods
+const qrCombinedBuilderImage = QRCodeJs.useTemplate('rounded')
+  .useImage('https://example.com/combined-builder-logo.png')
+  .useStyle({ dotsOptions: { color: 'green' } })
+  .options({
+    data: 'Combined builder methods with useImage'
+  });
+qrCombinedBuilderImage.append(document.getElementById('combined-builder-image-container'));
+```
+
+**Example: Using Override Option with Images**
+
+```javascript
+// The override option ensures this image takes precedence over any other image
+// settings, even those specified in the instance options
+const qrWithOverrideImage = QRCodeJs.useImage('https://example.com/priority-logo.png', { override: true })
+  .options({
+    data: 'Image with override',
+    // This image will be ignored because of the override option
+    image: 'https://example.com/ignored-image.png',
+    dotsOptions: { color: '#333333' }
+  });
+qrWithOverrideImage.append(document.getElementById('override-image-container'));
+
+// Global image with override
+QRCodeJs.setImage('https://example.com/global-priority.png', { override: true });
+
+// This instance will use the global priority image despite specifying another image
+const qrWithGlobalOverride = new QRCodeJs({
+  data: 'Global image override example',
+  image: 'https://example.com/will-be-ignored.png' // Ignored due to global override
+});
+qrWithGlobalOverride.append(document.getElementById('global-override-container'));
+
+// Clear the global image when done
+QRCodeJs.setImage(null);
+```
+
 ---
 
 ### Border Options (Free Version)
 
 Adding a basic border (includes "QR-Platform" branding).
 
-```javascript
-// filepath: /Users/kurdin/projects/qr-platform/qr-code-js/docs/examples.md
 const qrFreeBorder = new QRCodeJs({
   data: 'Free Border Example',
   borderOptions: {
@@ -489,6 +522,96 @@ const qrFreeBorder = new QRCodeJs({
 });
 qrFreeBorder.append(document.getElementById('free-border-container'));
 ```
+**Example: Setting a Global Default Border**
+
+
+// Set a default border configuration by name
+QRCodeJs.setBorder('basic-thin'); // Assumes 'basic-thin' is a predefined border template
+
+// This instance will use the 'basic-thin' border
+const qrWithDefaultBorder = new QRCodeJs({
+  data: 'Uses default border'
+});
+qrWithDefaultBorder.append(document.getElementById('default-border-container'));
+
+// You can also set by ID or with an options object:
+// QRCodeJs.setBorderId('border-id-example');
+// QRCodeJs.setBorder({ hasBorder: true, thickness: 10, color: 'red' });
+```
+
+**Example: Using the Builder Pattern for Borders**
+
+
+// Start the builder with a border configuration by name
+const qrBuiltWithBorder = QRCodeJs.useBorder('basic-curved') // Assumes 'basic-curved' is predefined
+  .options({
+    data: 'Built with border'
+  });
+qrBuiltWithBorder.append(document.getElementById('builder-border-container'));
+
+// Start the builder with a border configuration by ID
+const qrBuiltWithBorderId = QRCodeJs.useBorderId('border-id-example') // Assumes 'border-id-example' is predefined
+  .options({
+    data: 'Built with border ID'
+  });
+qrBuiltWithBorderId.append(document.getElementById('builder-border-id-container'));
+```
+
+**Example: Using Text in Borders with Override Option (Premium Feature)**
+
+```javascript
+// Ensure license is activated first for premium border features
+// await QRCodeJs.license('YOUR-LICENSE-KEY');
+
+// Setting text that will override any text specified in borderOptions
+QRCodeJs.setText({
+  topValue: 'TOP PRIORITY TEXT', 
+  bottomValue: 'BOTTOM PRIORITY TEXT'
+}, { override: true });
+
+// Even though this instance specifies different text values in the border decorations,
+// the global text with override option will take precedence
+const qrWithTextOverride = new QRCodeJs({
+  data: 'Text Override Example',
+  borderOptions: {
+    hasBorder: true,
+    thickness: 30,
+    color: '#9C27B0',
+    decorations: {
+      top: {
+        enableText: true,
+        value: 'THIS TEXT WILL BE IGNORED' // Ignored due to override
+      },
+      bottom: {
+        enableText: true,
+        value: 'THIS WILL ALSO BE IGNORED' // Ignored due to override
+      }
+    }
+  }
+});
+qrWithTextOverride.append(document.getElementById('text-override-container'));
+
+// Using the builder pattern with text override
+const qrBuilderWithTextOverride = QRCodeJs.useText({
+  leftValue: 'LEFT OVERRIDE',
+  rightValue: 'RIGHT OVERRIDE'
+}, { override: true })
+  .useBorder('fancy-border') // Assumes this is a predefined border
+  .options({
+    data: 'Builder Text Override Example',
+    borderOptions: {
+      decorations: {
+        left: { enableText: true, value: 'IGNORED' }, // Ignored due to override
+        right: { enableText: true, value: 'ALSO IGNORED' } // Ignored due to override
+      }
+    }
+  });
+qrBuilderWithTextOverride.append(document.getElementById('builder-text-override-container'));
+
+// Reset global text when done
+QRCodeJs.setText(null);
+```
+
 *For custom border text and advanced features like inner/outer borders, a [Premium License](./license-management.md#start) is required.*
 
 ---

package/docs/license-management.md

@@ -91,7 +91,7 @@ When using the basic border features in the free version, the library will autom
 - **Type**: `function(licenseKey: string): Promise<ValidationResult>`
 - **Process**:
   1. Calls `QRCodeJs.license('YOUR-LICENSE-KEY')`
-  2. Library sends key to backend endpoint (default: `POST /api/get-token`)
+  2. Library sends key to backend endpoint (default: `POST /api/license/get-token`)
   3. Backend validates key and returns signed JWT
   4. Library validates JWT signature and expiration date
   5. If valid, token and key are stored
@@ -192,7 +192,7 @@ When using the basic border features in the free version, the library will autom
 
 - **Purpose**: Configure the endpoint for license key validation
 - **Type**: `function(url: string): typeof QRCodeJs`
-- **Default**: `/api/get-token`
+- **Default**: `/api/license/get-token`
 - **Important**: Must be called before `QRCodeJs.license()`
 - **Returns**: `QRCodeJs` class for chaining
 - **Example**:
@@ -202,7 +202,7 @@ When using the basic border features in the free version, the library will autom
   ```
 - **Example** (chaining):
   ```typescript
-  await QRCodeJs.setLicenseUrl('/my-api/get-license').license('YOUR-LICENSE-KEY');
+  await QRCodeJs.setLicenseUrl('/my-api/license/get-token').license('YOUR-LICENSE-KEY');
   ```
 
 ### Custom License Fetcher
@@ -334,7 +334,7 @@ async function activateWithTokenNode(token) {
 
 ### Endpoint
 
-- **Default Path**: `/api/get-token`
+- **Default Path**: `/api/license/get-token`
 - **Method**: `POST`
 - **Content-Type**: `application/json`
 

package/docs/typescript-types-definitions.md

@@ -55,8 +55,8 @@ interface Options {
   /** Options for styling the background. Set to false to disable. */
   backgroundOptions?: BackgroundOptions | false;
 
-  /** URL, Buffer, or Blob of an image to embed in the QR code. */
-  image?: string | Buffer | Blob;
+  /** URL, Buffer, or Blob of an image to embed in the QR code. Can be influenced by `QRCodeJs.setImage()` or `QRCodeJs.useImage()`. */
+  image?: string | DataURL | Buffer | Blob;
 
   /** Options for the embedded image. */
   imageOptions: ImageOptions;

package/docs/usage-guide.md

@@ -278,6 +278,8 @@ const qrCodeWithGradient = new QRCodeJs({
 | `imageOptions.fill.color` | `string`                       | `'rgba(255,255,255,1)'` | Fill color for transparent areas.                                                                                |
 | `imageOptions.fill.gradient`| `Gradient` object            | `undefined`    | Apply a gradient fill to transparent areas. See [Gradients](#gradients) for configuration details.                                        |
 
+**Note on Image Source:** The `image` can be specified directly in the options, set globally for subsequent instances using `QRCodeJs.setImage('your_image_url')`, or set for a specific builder chain using `QRCodeJs.useImage('your_image_url').options(...)`. The builder's `useImage` typically overrides the global `setImage`, which in turn overrides an image set by a template. Direct options in the constructor or `.options()` call provide the final override.
+
 **`ImageMode` Enum Values:** `center`, `overlay`, `background`.
 
 **Important Considerations:**
@@ -515,76 +517,104 @@ if (validationResult.isValid) {
 - **`QRCodeJs.configureLicenseFetcher(fetcher: (licenseKey: string) => Promise<string>): void`**
   Configures a custom function for fetching license tokens.
 
+- **`QRCodeJs.setTemplate(templateNameOrOptions: string | RecursivePartial<Options>): void`**
+  Sets a global default template (by name or options object) for subsequent instances.
+
+- **`QRCodeJs.setTemplateId(templateId: string): void`**
+  Sets a global default template by its ID.
+
+- **`QRCodeJs.setStyle(styleNameOrOptions: string | StyleOptions): void`**
+  Sets a global default style (by name or options object) for subsequent instances.
+
+- **`QRCodeJs.setStyleId(styleId: string): void`**
+  Sets a global default style by its ID.
+
+- **`QRCodeJs.setBorder(borderNameOrOptions: string | RecursivePartial<BorderOptions>): void`**
+  Sets a global default border configuration (by name or options object) for subsequent instances.
+
+- **`QRCodeJs.setBorderId(borderId: string): void`**
+  Sets a global default border configuration by its ID.
+
 - **`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'
-  });
-  ```
+  Initiates the builder pattern pre-configured with a template (by name or options object).
+
+- **`QRCodeJs.useTemplateId(templateId: string): QRCodeBuilder`**
+  Initiates the builder pattern pre-configured with a template by its ID.
 
 - **`QRCodeJs.useStyle(styleNameOrOptions: string | StyleOptions): QRCodeBuilder`**
-  Creates a `QRCodeBuilder` instance initialized with a specific style.
+  Initiates the builder pattern pre-configured with a style (by name or options object).
 
-- **`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' });
-  ```
+- **`QRCodeJs.useStyleId(styleId: string): QRCodeBuilder`**
+  Initiates the builder pattern pre-configured with a style by its ID.
+
+- **`QRCodeJs.useBorder(borderNameOrOptions: string | BorderOptions): QRCodeBuilder`**
+  Initiates the builder pattern pre-configured with a border configuration (by name or options object).
 
+- **`QRCodeJs.useBorderId(borderId: string): QRCodeBuilder`**
+  Initiates the builder pattern pre-configured with a border configuration by its ID.
 
+- **`QRCodeJs.setImage(imageUrl: string | DataURL | null): void`**
+  Sets a global default image URL for subsequent `QRCodeJs` instances.
 
+- **`QRCodeJs.useImage(imageUrl: string | DataURL): QRCodeBuilder`**
+  Initiates the builder pattern pre-configured with an image URL.
 
-## Fluent Builder Pattern (`useTemplate`, `useStyle`, `build`)
+### Setting Global Defaults for Styles, Borders, and Images (`setStyle`, `setBorder`, `setImage`)
+
+Similar to `setTemplate`, you can set global defaults for styles, border configurations, and images that will apply to subsequently created instances:
+
+- **`QRCodeJs.setStyle(styleNameOrOptions)` / `QRCodeJs.setStyleId(styleId)`**: Sets a default style by name, object, or ID.
+- **`QRCodeJs.setBorder(borderNameOrOptions)` / `QRCodeJs.setBorderId(borderId)`**: Sets a default border configuration by name, object, or ID.
+- **`QRCodeJs.setImage(imageUrl)`**: Sets a default image URL.
+
+Options provided directly to the `new QRCodeJs(...)` constructor or via builder methods will override these global defaults for that specific instance.
+```javascript
+// 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.
+```
+
+## Fluent Builder Pattern (`useTemplate`, `useStyle`, `useBorder`, `useImage`, `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.
+1.  **Start:** Begin by calling `QRCodeJs.useTemplate()`, `QRCodeJs.useStyle()`, `QRCodeJs.useBorder()`, or `QRCodeJs.useImage()` with either a predefined name/ID or a custom options/style/border/image URL object. This returns a `QRCodeBuilder` instance.
+2.  **Chain (Optional):** Call `.useTemplate()`, `.useStyle()`, `.useBorder()`, or `.useImage()` again on the builder instance to layer additional configurations. 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:**
+**Combining Builder Methods:**
 
-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`).
+When you chain multiple `use...` methods, their options are merged. If different methods define the same property (e.g., `image` from `useImage()` and an image defined in a template via `useTemplate()`), the value from the method called *later* in the chain for that specific property generally takes precedence. The final `.options()` call provides the ultimate override.
 
 **Example:**
 
 ```typescript
-// Start with 'dots' template, override color with a style, add final data
+// 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
-  .options({ data: 'Built with Template and Style' }) // Final data
+  .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 for Styles, Borders, and Images (`useStyle`, `useBorder`, `useImage`)
+
+The builder pattern fully supports styles, borders, and images:
+
+- **`QRCodeJs.useStyle(styleNameOrOptions)` / `QRCodeJs.useStyleId(styleId)`**: Starts the builder pre-configured with a style.
+- **`QRCodeJs.useBorder(borderNameOrOptions)` / `QRCodeJs.useBorderId(borderId)`**: Starts the builder pre-configured with a border configuration.
+- **`QRCodeJs.useImage(imageUrl)`**: Starts the builder pre-configured with an image.
+
+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.
 ```
 
 ## FAQ
-
 ### How do I handle CORS issues with embedded images?
 
 Set `crossOrigin` in `imageOptions`:

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