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

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @qr-platform/qr-code-js
 
+## 0.10.0
+
+### Minor Changes
+
+- 4ec372c: added template and style, text and border combination for qrcode js class
+
 ## 0.9.0
 
 ### Minor Changes

package/README.md

@@ -16,6 +16,7 @@ QRCode.js is a professional JavaScript/TypeScript library for creating customize
 *   **Gradients:** Apply linear or radial gradients to dots, corners, and backgrounds.
 *   **Image Embedding:** Embed logos or other images in the center, as an overlay, or as a background.
 *   **Borders (Free & Premium):** Add basic borders (with branding in free version) or advanced, customizable borders with text/images (Premium).
+*   **Flexible Border Configuration:** Set global border defaults (`setBorder`/`setBorderId`) or use the builder pattern (`useBorder`/`useBorderId`) for instance-specific borders.
 *   **Flexible Output:** Generate QR codes as SVG elements in the browser or SVG strings in Node.js.
 *   **Download Options:** Download QR codes as SVG, PNG, JPEG, or WEBP.
 *   **TypeScript Support:** Fully typed for a better development experience.

package/docs/advanced-examples.md

@@ -13,9 +13,7 @@ These examples focus on the fundamental QR code generation settings.
 
 **Example 1: High Error Correction & Specific Type Number**
 
-```typescript
-// filepath: /Users/kurdin/projects/qr-platform/qr-code-js/docs/advanced-examples.md
-const qrCoreHighEC = new QRCodeJs({
+```typescriptconst qrCoreHighEC = new QRCodeJs({
   data: 'https://example.com/high-ec',
   qrOptions: {
     typeNumber: 10, // Larger QR code version
@@ -30,9 +28,7 @@ qrCoreHighEC.append(document.getElementById('core-high-ec-container'));
 
 **Example 2: Auto Type Number & Medium Error Correction**
 
-```typescript
-// filepath: /Users/kurdin/projects/qr-platform/qr-code-js/docs/advanced-examples.md
-const qrCoreAutoEC = new QRCodeJs({
+```typescriptconst qrCoreAutoEC = new QRCodeJs({
   data: 'https://example.com/auto-ec-medium',
   qrOptions: {
     typeNumber: 0, // Auto-detect size
@@ -53,9 +49,7 @@ Demonstrates how to control the positioning and scaling within the container or
 
 **Example 1: Scaled Down with Offsets**
 
-```typescript
-// filepath: /Users/kurdin/projects/qr-platform/qr-code-js/docs/advanced-examples.md
-const qrLayoutScaledOffset = new QRCodeJs({
+```typescriptconst qrLayoutScaledOffset = new QRCodeJs({
   data: 'https://example.com/layout-scaled-offset',
   scale: 0.75, // QR code occupies 75% of the space
   offset: -15, // Moves QR code 15px up relative to center
@@ -73,9 +67,7 @@ qrLayoutScaledOffset.append(document.getElementById('layout-scaled-offset-contai
 
 **Example 2: Responsive QR Code**
 
-```typescript
-// filepath: /Users/kurdin/projects/qr-platform/qr-code-js/docs/advanced-examples.md
-const qrLayoutResponsive = new QRCodeJs({
+```typescriptconst qrLayoutResponsive = new QRCodeJs({
   data: 'https://example.com/layout-responsive',
   isResponsive: true, // SVG will resize with container
   margin: 10, // Add a 10px quiet zone
@@ -100,9 +92,7 @@ Showcases different shapes and colors for the main data dots.
 
 **Example 1: Classy Rounded Dots**
 
-```typescript
-// filepath: /Users/kurdin/projects/qr-platform/qr-code-js/docs/advanced-examples.md
-const qrDotsClassy = new QRCodeJs({
+```typescriptconst qrDotsClassy = new QRCodeJs({
   data: 'https://example.com/dots-classy',
   dotsOptions: {
     type: 'classyRounded',
@@ -115,9 +105,7 @@ qrDotsClassy.append(document.getElementById('dots-classy-container'));
 
 **Example 2: Star Dots**
 
-```typescript
-// filepath: /Users/kurdin/projects/qr-platform/qr-code-js/docs/advanced-examples.md
-const qrDotsStar = new QRCodeJs({
+```typescriptconst qrDotsStar = new QRCodeJs({
   data: 'https://example.com/dots-star',
   dotsOptions: {
     type: 'star',
@@ -130,9 +118,7 @@ qrDotsStar.append(document.getElementById('dots-star-container'));
 
 **Example 3: Diamond Dots**
 
-```typescript
-// filepath: /Users/kurdin/projects/qr-platform/qr-code-js/docs/advanced-examples.md
-const qrDotsDiamond = new QRCodeJs({
+```typescriptconst qrDotsDiamond = new QRCodeJs({
   data: 'https://example.com/dots-diamond',
   dotsOptions: {
     type: 'diamond',
@@ -151,9 +137,7 @@ Customizes the three large corner squares.
 
 **Example 1: Outpoint Corner Squares**
 
-```typescript
-// filepath: /Users/kurdin/projects/qr-platform/qr-code-js/docs/advanced-examples.md
-const qrCornerSquareOutpoint = new QRCodeJs({
+```typescriptconst qrCornerSquareOutpoint = new QRCodeJs({
   data: 'https://example.com/corner-square-outpoint',
   dotsOptions: { color: '#444' },
   cornersSquareOptions: {
@@ -166,9 +150,7 @@ qrCornerSquareOutpoint.append(document.getElementById('corner-square-outpoint-co
 
 **Example 2: Rounded Corner Squares**
 
-```typescript
-// filepath: /Users/kurdin/projects/qr-platform/qr-code-js/docs/advanced-examples.md
-const qrCornerSquareRounded = new QRCodeJs({
+```typescriptconst qrCornerSquareRounded = new QRCodeJs({
   data: 'https://example.com/corner-square-rounded',
   dotsOptions: { type: 'dot', color: '#7B1FA2' }, // Purple dots
   cornersSquareOptions: {
@@ -187,9 +169,7 @@ Customizes the smaller dots within the corner squares.
 
 **Example 1: Heart Corner Dots**
 
-```typescript
-// filepath: /Users/kurdin/projects/qr-platform/qr-code-js/docs/advanced-examples.md
-const qrCornerDotHeart = new QRCodeJs({
+```typescriptconst qrCornerDotHeart = new QRCodeJs({
   data: 'https://example.com/corner-dot-heart',
   dotsOptions: { color: '#555' },
   cornersSquareOptions: { type: 'square', color: '#E64A19' }, // Orange square corners
@@ -203,9 +183,7 @@ qrCornerDotHeart.append(document.getElementById('corner-dot-heart-container'));
 
 **Example 2: Square Corner Dots with Different Color**
 
-```typescript
-// filepath: /Users/kurdin/projects/qr-platform/qr-code-js/docs/advanced-examples.md
-const qrCornerDotSquare = new QRCodeJs({
+```typescriptconst qrCornerDotSquare = new QRCodeJs({
   data: 'https://example.com/corner-dot-square',
   dotsOptions: { type: 'rounded', color: '#004D40' }, // Dark Teal dots
   cornersSquareOptions: { type: 'rounded', color: '#FBC02D' }, // Yellow rounded corners
@@ -225,9 +203,7 @@ Applies color, rounding, and gradients to the background.
 
 **Example 1: Colored and Rounded Background**
 
-```typescript
-// filepath: /Users/kurdin/projects/qr-platform/qr-code-js/docs/advanced-examples.md
-const qrBackgroundStyled = new QRCodeJs({
+```typescriptconst qrBackgroundStyled = new QRCodeJs({
   data: 'https://example.com/background-styled',
   dotsOptions: { color: '#FFFFFF' }, // White dots for contrast
   backgroundOptions: {
@@ -240,9 +216,7 @@ qrBackgroundStyled.append(document.getElementById('background-styled-container')
 
 **Example 2: Background with Subtle Radial Gradient**
 
-```typescript
-// filepath: /Users/kurdin/projects/qr-platform/qr-code-js/docs/advanced-examples.md
-const qrBackgroundGradient = new QRCodeJs({
+```typescriptconst qrBackgroundGradient = new QRCodeJs({
   data: 'https://example.com/background-gradient',
   dotsOptions: { color: '#333' },
   backgroundOptions: {
@@ -267,9 +241,7 @@ Applies linear and radial gradients to various elements.
 
 **Example 1: Linear Gradient on Dots**
 
-```typescript
-// filepath: /Users/kurdin/projects/qr-platform/qr-code-js/docs/advanced-examples.md
-const qrGradientDotsLinear = new QRCodeJs({
+```typescriptconst qrGradientDotsLinear = new QRCodeJs({
   data: 'https://example.com/gradient-dots-linear',
   dotsOptions: {
     type: 'rounded',
@@ -289,9 +261,7 @@ qrGradientDotsLinear.append(document.getElementById('gradient-dots-linear-contai
 
 **Example 2: Radial Gradient on Corner Squares & Linear on Dots**
 
-```typescript
-// filepath: /Users/kurdin/projects/qr-platform/qr-code-js/docs/advanced-examples.md
-const qrGradientMultiple = new QRCodeJs({
+```typescriptconst qrGradientMultiple = new QRCodeJs({
   data: 'https://example.com/gradient-multiple',
   dotsOptions: {
     type: 'square',
@@ -337,9 +307,7 @@ Embeds logos or images within the QR code.
 
 **Example 1: Centered Logo with Fill**
 
-```typescript
-// filepath: /Users/kurdin/projects/qr-platform/qr-code-js/docs/advanced-examples.md
-const qrImageCenter = new QRCodeJs({
+```typescriptconst qrImageCenter = new QRCodeJs({
   data: 'https://example.com/image-center',
   qrOptions: { errorCorrectionLevel: 'Q' }, // Higher EC recommended
   image: 'https://upload.wikimedia.org/wikipedia/commons/a/a5/Instagram_icon.png', // Example: Instagram logo
@@ -357,9 +325,7 @@ qrImageCenter.append(document.getElementById('image-center-container'));
 
 **Example 2: Image as Background**
 
-```typescript
-// filepath: /Users/kurdin/projects/qr-platform/qr-code-js/docs/advanced-examples.md
-const qrImageBackground = new QRCodeJs({
+```typescriptconst qrImageBackground = new QRCodeJs({
   data: 'https://example.com/image-background',
   qrOptions: { errorCorrectionLevel: 'M' },
   image: 'https://source.unsplash.com/random/300x300?nature,water', // Example: Random nature image
@@ -379,19 +345,108 @@ const qrImageBackground = new QRCodeJs({
 qrImageBackground.append(document.getElementById('image-background-container'));
 ```
 
+**Example 3: Using the Override Option with Images**
+
+```typescript
+// Setting a global image with override that will take precedence
+// even over images specified in instance options
+QRCodeJs.setImage('https://example.com/global-priority-logo.png', { override: true });
+
+// Even when an instance specifies an image, the global one with override will be used
+const qrImageOverride = new QRCodeJs({
+  data: 'https://example.com/image-override-example',
+  image: 'https://example.com/this-will-be-ignored.png', // Will be ignored due to override
+  dotsOptions: { color: '#333333' }
+});
+qrImageOverride.append(document.getElementById('image-override-container'));
+
+// Using the builder pattern with image override
+const qrBuilderImageOverride = QRCodeJs.useImage('https://example.com/builder-priority-logo.png', { override: true })
+  .options({
+    data: 'https://example.com/builder-image-override-example',
+    image: 'https://example.com/another-ignored-image.png', // Will be ignored due to override
+    dotsOptions: { type: 'rounded', color: '#555555' }
+  });
+qrBuilderImageOverride.append(document.getElementById('builder-image-override-container'));
+
+// Reset the global image when done
+QRCodeJs.setImage(null);
+```
+
 ---
 
 ### Border Options and Decorations (Premium Feature)
 
 Uses premium border features for advanced styling and text. Requires a license.
 
-**Example 1: Elaborate Border with Multiple Decorations**
+**Example 1: Using Text Override Option**
 
 ```typescript
-// filepath: /Users/kurdin/projects/qr-platform/qr-code-js/docs/advanced-examples.md
 // Ensure license is activated first
 // await QRCodeJs.license('YOUR-LICENSE-KEY');
 
+// Setting global text with override that will take precedence 
+// even over text specified in instance options
+QRCodeJs.setText({
+  topValue: 'GLOBAL OVERRIDE TEXT',
+  bottomValue: 'PRIORITY FOOTER TEXT'
+}, { override: true });
+
+// Even when an instance specifies border text, the global one with override will be used
+const qrTextOverride = new QRCodeJs({
+  data: 'https://example.com/text-override-example',
+  borderOptions: {
+    hasBorder: true,
+    thickness: 30,
+    color: '#FF5722',
+    decorations: {
+      top: { 
+        enableText: true,
+        value: 'THIS TEXT WILL BE IGNORED' // Ignored due to global override
+      },
+      bottom: {
+        enableText: true,
+        value: 'THIS BOTTOM TEXT ALSO IGNORED' // Ignored due to global override
+      }
+    }
+  }
+});
+qrTextOverride.append(document.getElementById('text-override-container'));
+
+// Using the builder pattern with text override
+const qrBuilderTextOverride = QRCodeJs.useText({
+  leftValue: 'LEFT OVERRIDE TEXT',
+  rightValue: 'RIGHT OVERRIDE TEXT'
+}, { override: true })
+  .options({
+    data: 'https://example.com/builder-text-override-example',
+    borderOptions: {
+      hasBorder: true,
+      thickness: 30,
+      color: '#3F51B5',
+      decorations: {
+        left: { 
+          enableText: true,
+          value: 'IGNORED LEFT TEXT' // Will be ignored due to override
+        },
+        right: {
+          enableText: true,
+          value: 'IGNORED RIGHT TEXT' // Will be ignored due to override
+        }
+      }
+    }
+  });
+qrBuilderTextOverride.append(document.getElementById('builder-text-override-container'));
+
+// Reset the global text when done
+QRCodeJs.setText(null);
+```
+
+**Example 2: Elaborate Border with Multiple Decorations**
+
+```typescript// Ensure license is activated first
+// await QRCodeJs.license('YOUR-LICENSE-KEY');
+
 const qrBorderElaborate = new QRCodeJs({
   data: 'https://example.com/border-elaborate',
   dotsOptions: {
@@ -532,13 +587,79 @@ const qrBuilderExample = new QRCodeJs({ data: 'https://example.com/class-instanc
 ```
 ---
 
+### Combining Global Defaults (`setTemplate`, `setStyle`, `setBorder`)
+
+This example shows how to set global defaults for a template, style, and border configuration. Subsequent `QRCodeJs` instances will inherit these settings unless overridden during instantiation.
+
+```typescript
+// 1. Define and set global defaults
+const globalTemplate = { backgroundOptions: { color: '#E8F5E9' } }; // Light Green background
+const globalStyle = { dotsOptions: { type: 'classy', color: '#1B5E20' } }; // Dark Green classy dots
+const globalBorder = { borderOptions: { hasBorder: true, thickness: 15, color: '#A5D6A7' } }; // Light Green border
+
+QRCodeJs.setTemplate(globalTemplate);
+QRCodeJs.setStyle(globalStyle);
+QRCodeJs.setBorder(globalBorder); // Set the global border
+QRCodeJs.setImage('https://example.com/global-default-logo.svg'); // Set a global default image or data URL
+
+// 2. Create instance - it inherits all global defaults, including the image
+const qrGlobalCombined = new QRCodeJs({
+  data: 'https://example.com/global-combined-with-image'
+  // No image option here, it will use the global default
+});
+qrGlobalCombined.append(document.getElementById('global-combined-container'));
+
+// 3. Create another instance, overriding the global image and border color
+const qrGlobalCombinedOverride = new QRCodeJs({
+  data: 'https://example.com/global-combined-override-image',
+  image: 'https://example.com/override-logo.png', // Override global image
+  borderOptions: { color: '#FF0000' } // Override border color to Red
+});
+qrGlobalCombinedOverride.append(document.getElementById('global-combined-override-container'));
+
+// Remember to clear defaults if needed for subsequent unrelated QR codes
+// QRCodeJs.setTemplate('basic');
+// QRCodeJs.setStyle(null);
+// QRCodeJs.setBorder(null);
+// QRCodeJs.setImage(null);
+```
+
+---
+
+### Combining Builder Methods (`useTemplate`, `useStyle`, `useBorder`, `useImage`)
+
+This example demonstrates chaining builder methods to combine a template, style, and border configuration for a single instance without affecting global defaults.
+
+```typescript
+// 1. Define components (optional, could be predefined names or IDs)
+const baseTpl = { qrOptions: { errorCorrectionLevel: 'M' }, margin: 5 };
+const dotsStyle = { dotsOptions: { type: 'dots', color: '#01579B' } }; // Light Blue dots
+const frameBorder = { borderOptions: { hasBorder: true, thickness: 20, color: '#B3E5FC', radius: '10%' } }; // Light Blue border
+
+// 2. Chain builder methods
+const qrBuilderCombined = QRCodeJs.useTemplate(baseTpl) // Start with base template
+  .useStyle(dotsStyle) // Apply dot style
+  .useBorder(frameBorder) // Apply border configuration
+  .useImage('https://example.com/builder-specific-logo.svg') // Add an image via builder
+  .options({ data: 'https://example.com/builder-combined-with-image' }); // Add final data
+
+qrBuilderCombined.append(document.getElementById('builder-combined-container'));
+
+// Example using predefined names (assuming 'rounded', 'blue-gradient', 'thick-frame' exist)
+// const qrBuilderNames = QRCodeJs.useTemplate('rounded')
+//   .useStyle('blue-gradient')
+//   .useBorder('thick-frame')
+//   .useImage('another-logo.png')
+//   .options({ data: 'https://example.com/builder-names-with-image' });
+// qrBuilderNames.append(document.getElementById('builder-names-container'));
+```
+---
+
 ### Scan Validation (Premium Feature)
 
 Validate if the generated QR code is scannable using the built-in validator. This requires a premium license.
 
-```typescript
-// filepath: /Users/kurdin/projects/qr-platform/qr-code-js/docs/advanced-examples.md
-// Ensure license is activated first
+```typescript// Ensure license is activated first
 // await QRCodeJs.license('YOUR-LICENSE-KEY');
 
 const qrCodeToValidate = new QRCodeJs({

package/docs/api-reference-guide.md

@@ -48,7 +48,7 @@ qrCode.append(document.getElementById('qr-container'));
 | `backgroundOptions.color` | `string`                            | `'#FFFFFF'`    | The background color.                                                       |
 | `backgroundOptions.round` | `number \| string`                  | `0`            | Rounds the corners of the background (0-1 or percentage).                   |
 | `backgroundOptions.gradient` | `Gradient` object                | `undefined`    | Apply a gradient fill to the background. See [Gradient options](#gradientoptions) for configuration details.
-| `image`                | `string \| Buffer \| Blob`             | `undefined`    | URL, Buffer, or Blob of an image to embed in the QR code.                   |
+| `image`                | `string \| Buffer \| Blob`             | `undefined`    | URL, Buffer, or Blob of an image to embed in the QR code. Can be set globally via `QRCodeJs.setImage()` or per-instance via `QRCodeJs.useImage()` or direct options. |
 | `imageOptions`         | `object`                               | `{...}`        | Options for the embedded image.                                             |
 | `imageOptions.mode`    | `ImageMode` enum                       | `'center'`     | How the image is embedded. See `ImageMode` enum.                            |
 | `imageOptions.imageSize` | `number`                             | `0.4`          | Relative size of the image (0-1).                                           |
@@ -57,7 +57,7 @@ qrCode.append(document.getElementById('qr-container'));
 | `imageOptions.fill`    | `object`                               | `{...}`           | Fill `color` or `gradient`.                               |
 | `imageOptions.fill.color` | `string`                            | `'rgba(255,255,255,1)'`    | Fill color.
 | `imageOptions.fill.gradient` | `Gradient` object | `undefined`    | Apply a gradient fill to the QR code. See [Gradient options](#gradientoptions) for configuration details.
-| `borderOptions`        | `BorderOptions` object                 | `undefined`    | Options for adding decorative borders. See below for sub-options. **Premium option** | 
+| `borderOptions`        | `BorderOptions` object                 | `undefined`    | Options for adding decorative borders. Can be configured globally via `QRCodeJs.setBorder()`/`setBorderId()` or per-instance via the builder pattern (`useBorder()`/`useBorderId()`). See below for sub-options. **Premium option** |
 
 ---
 
@@ -71,7 +71,7 @@ qrCode.append(document.getElementById('qr-container'));
 | `cornersDotOptions.type` | `CornerDotType` enum| `Inherits` | Specifies the shape of the corner dots. Refer to the `CornerDotType` enum for available options (e.g., square, rounded). |
 | `cornersDotOptions.color`| `string`            | `Inherits` | Defines the solid color of the corner dots. Accepts any valid CSS color string (e.g., `'#FF0000'`, `'red'`, `'rgba(255, 0, 0, 0.5)'`). |
 | `cornersDotOptions.gradient` | `Gradient` object | `undefined`| Applies a gradient fill to the corner dots, overriding the `color` property if both are set. See [Gradient Sub-options](#gradient-sub-options) for configuration details. |
-
+  
 ### Additional Notes
 - The `data` option is the only required option for generating a QR code.
 - Premium features like `borderOptions` and `validateScanning` require a valid license to use.
@@ -86,13 +86,28 @@ qrCode.append(document.getElementById('qr-container'));
 | `serialize`         | `inverted?: boolean`                                                       | Converts the QR code to an SVG string. Returns `Promise<string \| undefined>`. |
 | `download`          | `downloadOptions?: { name?: string; extension: 'svg' \| 'png' \| 'jpeg' \| 'webp' }, canvasOptions?: CanvasOptions` | Downloads the QR code as a file. Returns `Promise<void>`.                   |
 | `update`            | `options?: RecursivePartial<Options>`                                      | Updates the QR code with new options. Returns `void`.                       |
-| `setTemplate`       | `templateNameOrOptions: string \| RecursivePartial<Options>` | Sets a global default template for subsequent instances. Returns `void`.    |\n| `useTemplate`       | `templateNameOrOptions: string \| RecursivePartial<Options>` | Initiates a builder pattern pre-configured with a template. Returns `QRCodeBuilder`. |
+| `setTemplate`       | `templateNameOrOptions: string \| RecursivePartial<Options>` | Sets a global default template (by name or options object) for subsequent instances. Returns `void`. |
+| `setTemplateId`     | `templateId: string`                                                       | Sets a global default template by its ID. Returns `void`. |
+| `setStyle`          | `styleNameOrOptions: string \| StyleOptions`                               | Sets a global default style (by name or options object) for subsequent instances. Returns `void`. |
+| `setStyleId`        | `styleId: string`                                                          | Sets a global default style by its ID. Returns `void`. |
+| `setText`           | `textNameOrOptions: string \| TextOptions \| null, options?: { override?: boolean }` | Sets a global default text configuration for border text. With `{ override: true }`, the text will take precedence over any instance-specific border text. Returns `void`. |
+| `setTextId`         | `textId: string \| null, options?: { override?: boolean }`                 | Sets a global default text configuration by its ID. With `{ override: true }`, the text will take precedence over any instance-specific border text. Returns `void`. |
+| `setBorder`         | `borderNameOrOptions: string \| RecursivePartial<BorderOptions>`           | Sets a global default border configuration (by name or options object) for subsequent instances. Returns `void`. |
+| `setBorderId`       | `borderId: string`                                                         | Sets a global default border configuration by its ID. Returns `void`. |
+| `setImage`          | `imageUrl: string \| DataURL \| null, options?: { override?: boolean }`    | Sets a global default image URL for subsequent instances. With `{ override: true }`, the image will take precedence over any instance-specific images.
+| `useTemplate`       | `templateNameOrOptions: string \| RecursivePartial<Options>`             | Initiates a builder pattern pre-configured with a template (by name or options object). Returns `QRCodeBuilder`. |
+| `useTemplateId`     | `templateId: string`                                                       | Initiates a builder pattern pre-configured with a template by its ID. Returns `QRCodeBuilder`. |
+| `useStyle`          | `styleNameOrOptions: string \| StyleOptions`                               | Initiates a builder pattern pre-configured with a style (by name or options object). Returns `QRCodeBuilder`. |
+| `useStyleId`        | `styleId: string`                                                          | Initiates a builder pattern pre-configured with a style by its ID. Returns `QRCodeBuilder`. |
+| `useText`           | `textNameOrOptions: string \| TextOptions, options?: { override?: boolean }` | Initiates a builder pattern pre-configured with text for border sides. With `{ override: true }`, the text will take precedence over any text set in final options. Returns `QRCodeBuilder`. |
+| `useTextId`         | `textId: string, options?: { override?: boolean }`                         | Initiates a builder pattern pre-configured with text by its ID. With `{ override: true }`, the text will take precedence over any text set in final options. Returns `QRCodeBuilder`. |
+| `useBorder`         | `borderNameOrOptions: string \| BorderOptions`                             | Initiates a builder pattern pre-configured with a border configuration (by name or options object). Returns `QRCodeBuilder`. |
+| `useBorderId`       | `borderId: string`                                                         | Initiates a builder pattern pre-configured with a border configuration by its ID. Returns `QRCodeBuilder`. |
+| `useImage`          | `imageUrl: string \| DataURL, options?: { override?: boolean }`            | Initiates a builder pattern pre-configured with an image URL. With `{ override: true }`, the image will take precedence over any image set in final options.
 | `validateScanning`  | `validatorId?: string, debug?: boolean`                                    | **(Premium method)** Validates that the QR code is scannable. Returns `Promise<ScanValidatorResponse>`. |
 
 ---
 
-| `useStyle`          | `styleNameOrOptions: string \| StyleOptions`                               | Creates a `QRCodeBuilder` instance initialized with a specific style. Returns `QRCodeBuilder`. |
-| `useTemplate`       | `templateNameOrOptions: string \| RecursivePartial<Options>`             | Creates a `QRCodeBuilder` instance initialized with a specific template. Returns `QRCodeBuilder`. |
 <a id="borderoptions"></a>
 ### borderOptions Options 
 
@@ -280,6 +295,11 @@ const qr3 = QRCodeJs.useTemplate('basic')
 | :------------ | :------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------- |
 | `useTemplate` | `templateNameOrOptions: string \| RecursivePartial<Options>`             | Applies a template's options to the current configuration. Options from subsequent calls take precedence. Returns `this`. |
 | `useStyle`    | `styleNameOrOptions: string \| StyleOptions`                               | Applies style options (mapping them to `Options`) to the current configuration. Returns `this`.            |
+| `useText`     | `textNameOrOptions: string \| TextOptions, options?: { override?: boolean }` | Applies text configuration for border sides. With `{ override: true}`, text will take precedence over any text set in final options. Returns `this`. |
+| `useTextId`   | `textId: string, options?: { override?: boolean }`                         | Applies text configuration by its ID. With `{ override: true}`, text will take precedence over any text set in final options. Returns `this`. |
+| `useBorder`   | `borderNameOrOptions: string \| BorderOptions`                             | Applies border configuration (by name or options object) to the current configuration. Returns `this`.     |
+| `useBorderId` | `borderId: string`                                                         | Applies border configuration by its ID to the current configuration. Returns `this`.                       |
+| `useImage`    | `imageUrl: string, options?: { override?: boolean }`                       | Sets the image URL for the current configuration. With `{ override: true}`, the image will take precedence over any image set in final options. Returns `this`. |
 | `options`     | `options: RecursivePartial<Options>`                                       | Merges the provided `Options` into the current configuration and returns the final `QRCodeJs` instance.    |
 | `build`       | -                                                                          | Creates and returns the final `QRCodeJs` instance based on the accumulated configuration.                  |
 ### See Also

package/docs/border-methods-update-plan.md

@@ -0,0 +1,28 @@
+# Plan: Update Documentation for Border Methods
+
+**Objective:** Update documentation files to include information about the new border configuration methods: `setBorder`, `setBorderId`, `useBorder`, and `useBorderId`.
+
+## 1. Target Files
+
+*   `README.md`
+*   `docs/documentation.md`
+*   `docs/usage-guide.md`
+*   `docs/api-reference-guide.md`
+*   `docs/examples.md`
+*   `docs/advanced-examples.md`
+*   `docs/typescript-types-definitions.md`
+
+## 2. Update Strategy & Content
+
+*   **Update README:** Briefly mention the new static methods (`setBorder`, `setBorderId`, `useBorder`, `useBorderId`) in a relevant section (e.g., Features) and link to the main documentation for details.
+*   **Explain Both Mechanisms:** In `documentation.md` and `usage-guide.md`, clearly differentiate the `set...` (global default) and `use...` (builder pattern) approaches for border configuration.
+*   **Update Method Tables:** Add entries for `setBorder`, `setBorderId`, `useBorder`, and `useBorderId` to static method tables in relevant files, detailing parameters, return types, and purpose.
+*   **Add Examples:**
+    *   In `examples.md`, add simple examples for `setBorder`, `setBorderId`, `useBorder`, and `useBorderId`.
+    *   In `advanced-examples.md`, add examples combining global defaults (`setTemplate`/`setStyle`/`setBorder`) and builder methods (`useTemplate`/`useStyle`/`useBorder`).
+*   **Update Options Tables:** Ensure the `borderOptions` description mentions configuration via the new static/builder methods.
+*   **Verify Types:** Briefly check `docs/typescript-types-definitions.md` for `BorderOptions`.
+
+## 3. Implementation
+
+This plan will be implemented by switching to Code mode after approval.

package/docs/border-text-implementation-plan.md

@@ -0,0 +1,155 @@
+# Plan for Implementing Border Text Functionality
+
+This document outlines the plan to implement `setText`, `useText`, `setTextId`, and `useTextId` functionality for managing text on QR code borders.
+
+## Phase 1: Define Core Structures and Text Templates
+
+1.  **Create `TextOptions` and `QRTextTemplateDefinition` Types:**
+    *   Define these interfaces. A new file like `src/types/text-options.ts` or an existing relevant types file (e.g., `src/utils/options.ts` or `src/types/style-options.ts`) can be used.
+    *   **`TextOptions` Interface:**
+        ```typescript
+        export interface TextOptions {
+          topValue?: string | null;
+          leftValue?: string | null;
+          rightValue?: string | null;
+          bottomValue?: string | null;
+        }
+        ```
+    *   **`QRTextTemplateDefinition` Interface:** (similar to `QRTemplateDefinition`)
+        ```typescript
+        // Assuming TextOptions is in 'text-options.ts' or similar
+        import { TextOptions } from './text-options'; // Adjust path as needed
+
+        export interface QRTextTemplateDefinition {
+          id: string;
+          name: string;
+          options: TextOptions;
+        }
+        ```
+
+2.  **Create New Text Templates File: `src/core/templates/qr-template-text.ts`**
+    *   This file will be analogous to `src/core/templates/qr-template-borders.ts`.
+    *   It will import `QRTextTemplateDefinition` and `TextOptions`.
+    *   Define at least 20 unique `QRTextTemplateDefinition` objects.
+        *   Each template will have a unique `id` (e.g., `"scan-me-top"`, `"return-if-found-bottom-left"`).
+        *   Each template will have a unique, descriptive `name` (e.g., `"Scan Me (Top Text)"`, `"Return If Found (Bottom & Left Text)"`).
+        *   The `options` field will be a `TextOptions` object with various combinations of `topValue`, `leftValue`, `rightValue`, `bottomValue`.
+        *   Include `null` values where appropriate to signify no text for a particular side.
+        *   Focus on call-to-action phrases like "Scan Me", "Visit Website", "Follow Us", "Contact Info", "Scan to Pay", "Product Details", "Event Info", "Lost & Found", etc.
+    *   Export an array `qrTextTemplates: QRTextTemplateDefinition[]`.
+    *   Export helper functions `findTextByName(name: string): QRTextTemplateDefinition | undefined` and `findTextById(id: string): QRTextTemplateDefinition | undefined`.
+
+## Phase 2: Implement Core Logic in `QRCodeJs` (`src/core/qr-code-js.ts`)
+
+1.  **Add Static Properties for Selected Text:**
+    *   `private static _selectedText: QRTextTemplateDefinition | TextOptions | null = null;`
+
+2.  **Implement `setText` Static Method:**
+    *   `public static setText(textNameOrOptions: string | TextOptions | null): typeof QRCodeJs`
+    *   If `null`, set `_selectedText` to `null`.
+    *   If `string`, use `findTextByName` from `qr-template-text.ts` to find the template. If found, store the `QRTextTemplateDefinition` in `_selectedText`. If not found, log a warning.
+    *   If `object` (instance of `TextOptions`), store it directly in `_selectedText`.
+
+3.  **Implement `setTextId` Static Method:**
+    *   `public static setTextId(textId: string | null): typeof QRCodeJs`
+    *   If `null`, set `_selectedText` to `null`.
+    *   Use `findTextById` from `qr-template-text.ts`. If found, store the `QRTextTemplateDefinition` in `_selectedText`. If not found, log a warning.
+
+4.  **Update Constructor and `update` Method Logic:**
+    *   In the constructor and `update` method, after merging `borderOptions`, apply `_selectedText`.
+    *   **Merging Logic:**
+        *   Resolve `_selectedText` to a `TextOptions` object (either from `QRTextTemplateDefinition.options` or directly).
+        *   Iterate through `topValue`, `leftValue`, `rightValue`, `bottomValue` of the resolved `TextOptions`.
+        *   For each provided value (not `undefined`):
+            *   Update `this.options.borderOptions.decorations.<side>.value`.
+            *   Set `this.options.borderOptions.decorations.<side>.enableText = true`.
+            *   If the value is `null`, set `this.options.borderOptions.decorations.<side>.value = null` and `this.options.borderOptions.decorations.<side>.enableText = false`.
+        *   Ensure `this.options.borderOptions.decorations` and each side object (`top`, `left`, etc.) are initialized if they don't exist.
+
+## Phase 3: Implement Builder Logic in `QRCodeBuilder` (`src/index.ts` and `src/node.ts`)
+
+*   Changes need to be mirrored in `QRCodeBuilder` in both `src/index.ts` and `src/node.ts`.
+
+1.  **Add Properties to `QRCodeBuilder`:**
+    *   `protected _textSource: string | TextOptions | null = null;`
+    *   `protected _isTextById: boolean = false;`
+
+2.  **Implement `useText` Method in `QRCodeBuilder`:**
+    *   `public useText(textNameOrOptions: string | TextOptions): this`
+    *   Stores `textNameOrOptions` in `_textSource`. Sets `_isTextById = false`.
+
+3.  **Implement `useTextId` Method in `QRCodeBuilder`:**
+    *   `public useTextId(textId: string): this`
+    *   Stores `textId` in `_textSource`. Sets `_isTextById = true`.
+
+4.  **Update `_resolveAndMergeConfig` in `QRCodeBuilder`:**
+    *   Add a step to apply text options after border options.
+    *   **Order:** Base Template -> Selected Template -> Selected Border -> **Selected Text** -> Selected Style -> Selected Image -> Final Options.
+    *   **Logic:**
+        *   Resolve `_textSource` (using `findTextById`/`findTextByName` if string, or directly if object).
+        *   If valid `TextOptions` are found:
+            *   Create a partial `Options` object: `let textOptionsToApply: RecursivePartial<Options> = { borderOptions: { decorations: {} } };`
+            *   For each key in resolved `TextOptions` (e.g., `topValue`):
+                *   `textOptionsToApply.borderOptions.decorations.top = { value: textOptions.topValue, enableText: textOptions.topValue !== null };`
+            *   Repeat for `left`, `right`, `bottom`.
+            *   Merge `textOptionsToApply` into `resolvedConfig`.
+
+5.  **Add Static `useText` and `useTextId` Methods to `QRCodeJs` class (in `src/index.ts` and `src/node.ts`):**
+    *   `public static useText(textNameOrOptions: string | TextOptions): QRCodeBuilder`
+        *   `return new QRCodeBuilder(this).useText(textNameOrOptions);`
+    *   `public static useTextId(textId: string): QRCodeBuilder`
+        *   `return new QRCodeBuilder(this).useTextId(textId);`
+
+## Phase 4: Update Imports and Exports
+
+1.  **In `src/index.ts` and `src/node.ts`:**
+    *   Import `findTextById`, `findTextByName` from `./core/templates/qr-template-text`.
+    *   Import `TextOptions`, `QRTextTemplateDefinition` (if in a separate file).
+    *   Export these types if intended for public use.
+
+## Phase 5: Testing and Documentation
+
+1.  **Update `src/templates/borders-templates.html`:**
+    *   Add a new dropdown selector for "Text Templates" populated from `qrTextTemplates`.
+    *   Modify the rendering loop:
+        *   After applying base template, style, and border, add a step to apply a selected text template using `QRCodeJs.setTextId()` or `QRCodeJs.setText()`.
+        *   This will demonstrate the override behavior where `setText` modifies the text values on borders already configured by `setBorder`.
+    *   Ensure the visual output clearly shows the text being applied/overridden.
+
+2.  **Add Unit Tests (Recommended):**
+    *   Test `findTextByName` and `findTextById`.
+    *   Test `setText`/`setTextId` in `QRCodeJs` core.
+    *   Test `useText`/`useTextId` in `QRCodeBuilder`.
+
+3.  **Update Documentation (`README.md`, API docs):**
+    *   Document new types, static methods, and builder methods.
+    *   Provide usage examples.
+
+## Mermaid Diagram: `QRCodeBuilder._resolveAndMergeConfig` Flow
+
+```mermaid
+graph TD
+    A[Start _resolveAndMergeConfig] --> B{Initial Options or Base Template};
+    B -- Initial Options --> C[Merge Initial Options];
+    B -- Base Template --> C[Merge baseQRTemplateOptions];
+    C --> D{Template Source Set?};
+    D -- Yes --> E[Find/Apply Template Options];
+    D -- No --> F;
+    E --> F;
+    F{Border Source Set?} --> G;
+    G -- Yes --> H[Find/Apply Border Options];
+    G -- No --> I;
+    H --> I;
+    I{Text Source Set?} --> J;
+    J -- Yes --> K[Find/Apply Text Options to Decorations];
+    J -- No --> L;
+    K --> L;
+    L{Style Source Set?} --> M;
+    M -- Yes --> N[Find/Apply Style Options];
+    M -- No --> O;
+    N --> O;
+    O{Image Source Set?} --> P;
+    P -- Yes --> Q[Apply Image Option];
+    P -- No --> R;
+    Q --> R;
+    R[Merge Final User Options] --> S[Return Resolved Config];