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

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @qr-platform/qr-code-js
 
+## 0.10.2
+
+### Patch Changes
+
+- 45342a8: added useSettings and setSettings to combine all options and templates into one json object
+
 ## 0.10.0
 
 ### Minor Changes

package/docs/api-reference-guide.md

@@ -95,6 +95,8 @@ qrCode.append(document.getElementById('qr-container'));
 | `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.
+| `settings`          | `settings: SettingsOptions \| null`                                        | **(Static)** Sets global default settings from a `SettingsOptions` object. This will override/reset any previously set static template, style, text, or border. Returns `typeof QRCodeJs`. |
+| `setSettings`       | `settings: SettingsOptions`                                                | **(Instance)** Applies settings from a `SettingsOptions` object to the current instance, completely replacing its current options. Returns `Promise<void>`. |
 | `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`. |
@@ -158,7 +160,8 @@ The `borderOptions` object is a premium feature that allows you to add decorativ
 | `style.fontSize`   | `number`                               | `28`           | The font size for the text in pixels.                                       |
 | `style.fontColor`  | `string`                               | `'#ffffff'`    | The color of the text.                                                      |
 | `style.letterSpacing` | `number`                            | `0`            | The letter spacing for the text in pixels.                                  |
-| `style.fontWeight` | `'normal' \| 'bold'`                   | `'normal'`     | The font weight for the text.                                               |
+| `style.textTransform` | `'uppercase' \| 'lowercase' \| 'capitalize'` | `uppercase` | The text transformation style.                                             |
+| `style.fontWeight` | `'normal' \| 'bold'`                   | `'bold'`     | The font weight for the text.                                               |
 
 ### Enums
 
@@ -300,6 +303,7 @@ const qr3 = QRCodeJs.useTemplate('basic')
 | `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`. |
+| `useSettings` | `settings: SettingsOptions`                                                | Applies a comprehensive `SettingsOptions` object to the builder. This will override/reset any previously set builder configurations (template, style, text, border, image, data). 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/documentation.md

@@ -698,6 +698,7 @@ Options for adding decorative borders around the QR code. Borders can be configu
           fontFace: 'Helvetica',
           fontSize: 28,
           fontColor: '#ffffff',
+          textTransform: 'uppercase',
           letterSpacing: 2,
           fontWeight: 'bold'
         }
@@ -826,10 +827,10 @@ QRCode.js provides dedicated methods for managing text on QR code borders, allow
 - **Example**:
   ```typescript
   // Set global text using a predefined template ID
-  QRCodeJs.setTextId('visit-website-bottom');
+  QRCodeJs.setTextId('scan-to-visit-website');
   
   // With override option
-  QRCodeJs.setTextId('lost-found-all-sides', { override: true });
+  QRCodeJs.setTextId('lost-found', { override: true });
   
   // Clear global text
   QRCodeJs.setTextId(null);
@@ -884,11 +885,11 @@ QRCode.js provides dedicated methods for managing text on QR code borders, allow
 - **Example**:
   ```typescript
   // Start builder with a predefined text template by ID
-  const qrCode = QRCodeJs.useTextId('visit-website-bottom')
+  const qrCode = QRCodeJs.useTextId('scan-to-visit-website')
     .options({ data: 'https://example.com' });
     
   // With override option
-  const qrWithOverride = QRCodeJs.useTextId('scan-me-top', { override: true })
+  const qrWithOverride = QRCodeJs.useTextId('scan-me', { override: true })
     .options({ data: 'https://example.com' });
   ```
 

package/docs/ft009-settings-option-continuation-plan.md

@@ -0,0 +1,124 @@
+# Feature Task FT009 - Settings Option - Continuation Plan
+
+## 1. Original Task Description (FT009)
+
+**Feature:** Settings Option
+**Task Description:** Add a mechanism to configure QR code instances using a comprehensive `SettingsOptions` object. This was initially planned as an instance method `setSettings()` and a static builder-style method `QRCodeJs.settings()`. The requirements evolved to include a `useSettings()` method for the `QRCodeBuilder` and to make the instance-level application a static utility method.
+
+**Core Requirements:**
+*   Provide a centralized way to configure multiple QR code properties: `id`, `name`, `description`, `data`, `image`, `template`, `templateId`, `style`, `styleId`, `text`, `textId`, `border`, `borderId`, and a general `options` override.
+*   Ensure this new configuration method interacts correctly with existing setup methods, generally by overriding previous settings.
+
+## 2. Current Implementation Status
+
+### 2.1. Core Class Changes ([`src/core/qr-code-js.ts`](src/core/qr-code-js.ts))
+*   **`SettingsOptions` Type:** Defined in [`src/types/settings-options.ts`](src/types/settings-options.ts). It includes:
+    ```typescript
+    export interface SettingsOptions {
+      id?: string;
+      name?: string;
+      description?: string;
+      data?: string;
+      image?: string | Buffer | Blob;
+      template?: string | RecursivePartial<Options>;
+      templateId?: string;
+      style?: string | StyleOptions;
+      styleId?: string;
+      text?: string | TextOptions;
+      textId?: string;
+      border?: string | RecursivePartial<BorderOptions>;
+      borderId?: string;
+      options?: RecursivePartial<Options>;
+    }
+    ```
+*   **Static `setSettings` Method:**
+    *   A `public static async setSettings(instance: QRCodeJs, settings: SettingsOptions): Promise<void>` method has been added to `QRCodeJs`.
+    *   This method applies the provided `SettingsOptions` to a given `QRCodeJs` instance.
+    *   It completely replaces the instance's current options by:
+        1.  Starting with `baseQRTemplateOptions`.
+        2.  Applying `template`, `style`, `text`, `border` from the `settings` object.
+        3.  Setting `newOptions.image = settings.image` if `settings.image` is provided.
+        4.  Setting `newOptions.data = settings.data` if `settings.data` is provided. If not, it attempts to use `settings.options.data`. If still not present, it retains `instance.options.data`.
+        5.  Merging `settings.options` for any other direct overrides.
+        6.  Validating and sanitizing the resulting options.
+        7.  Calling `await instance.update()`.
+*   **Removed Static Configuration:** The previously planned static `QRCodeJs.settings()` method (that would set static defaults like `_selectedSettings`) and related static properties (`_selectedSettings`, `_selectedData`) have been removed from `QRCodeJs` as per user feedback.
+
+### 2.2. Documentation
+*   [`docs/typescript-types-definitions.md`](docs/typescript-types-definitions.md): Updated with the `SettingsOptions` interface.
+*   [`docs/api-reference-guide.md`](docs/api-reference-guide.md): Updated to reflect the new static `QRCodeJs.setSettings(instance, settings)` method and remove the old static `QRCodeJs.settings()` method.
+*   [`docs/usage-guide.md`](docs/usage-guide.md): Updated with examples for the new static `QRCodeJs.setSettings(instance, settings)` method.
+
+### 2.3. Unit Tests
+*   [`tests/node/node.settings.test.ts`](tests/node/node.settings.test.ts): Initial tests for the static `setSettings(instance, settings)` method have been created and partially debugged. Import paths and type assertions have been refined.
+
+## 3. Remaining Tasks
+
+### 3.1. Implement `useSettings` in `QRCodeBuilder`
+This is the primary remaining coding task. The `useSettings` method needs to be added to the `QRCodeBuilder` class in both:
+*   [`src/index.ts`](src/index.ts) (for browser environment)
+*   [`src/node.ts`](src/node.ts) (for Node.js environment)
+
+**`QRCodeBuilder.useSettings(settings: SettingsOptions): this` Method Details:**
+*   **Store Settings:**
+    *   Add a new protected property to `QRCodeBuilder`: `protected _settingsSource: SettingsOptions | null = null;`
+    *   The `useSettings` method will set `this._settingsSource = settings;`.
+*   **Override Behavior:**
+    *   Calling `useSettings` must reset/nullify all other builder-specific configuration sources to ensure it takes precedence over any prior `useTemplate()`, `useStyle()`, `useBorder()`, `useText()`, `useImage()` calls, and `_initialOptions`. This includes:
+        *   `this._templateSource = null;`
+        *   `this._isTemplateById = false;`
+        *   `this._borderSource = null;`
+        *   `this._isBorderById = false;`
+        *   `this._styleSource = null;`
+        *   `this._isStyleById = false;`
+        *   `this._imageSource = null;`
+        *   `this._imageOverride = false;`
+        *   `this._textSource = null;`
+        *   `this._isTextById = false;`
+        *   `this._textOverride = false;`
+        *   `this._initialOptions = null;`
+*   **Modify `_resolveAndMergeConfig(finalOptions: RecursivePartial<Options> = {})` in `QRCodeBuilder`:**
+    *   **Priority for `_settingsSource`:**
+        1.  If `this._settingsSource` is set:
+            *   Initialize `resolvedConfig = mergeDeep({}, baseQRTemplateOptions)`.
+            *   Apply `template/templateId` from `this._settingsSource` to `resolvedConfig`.
+            *   Apply `style/styleId` from `this._settingsSource` (mapping style options) to `resolvedConfig`.
+            *   Apply `border/borderId` from `this._settingsSource` to `resolvedConfig`.
+            *   Apply `text/textId` from `this._settingsSource` (mapping to `borderOptions.decorations`) to `resolvedConfig`.
+            *   If `this._settingsSource.image` is defined, set `resolvedConfig.image = this._settingsSource.image;`.
+            *   If `this._settingsSource.data` is defined, set `resolvedConfig.data = this._settingsSource.data;`.
+            *   Merge `this._settingsSource.options` into `resolvedConfig`.
+    *   **Else (no `_settingsSource`):**
+        *   Follow the existing logic: apply `_initialOptions`, then `_templateSource`, `_borderSource`, `_styleSource`, `_imageSource` (non-override), `_textSource` (non-override).
+    *   **Final Merge & Overrides:**
+        *   Merge `finalOptions` (from a subsequent `.options()` call) into `resolvedConfig`. This allows `.options()` to override settings from `useSettings`.
+        *   The existing `_imageOverride` and `_textOverride` logic should apply last. If `useImage(..., {override:true})` or `useText(..., {override:true})` is called *after* `useSettings()`, it effectively clears `_settingsSource` (because `useSettings` resets those specific sources) and these specific overrides would then apply as intended.
+
+### 3.2. Unit Testing
+*   Add comprehensive unit tests for `QRCodeBuilder.useSettings` in both [`tests/node/node.settings.test.ts`](tests/node/node.settings.test.ts) and potentially a new browser-specific test file if behavior differs or requires DOM.
+*   Tests should cover:
+    *   `useSettings` correctly applying all properties from `SettingsOptions`.
+    *   `useSettings` overriding configurations from previous `useTemplate`, `useStyle`, `useBorder`, `useText`, `useImage` calls.
+    *   A subsequent `.options()` call overriding configurations set by `useSettings`.
+    *   `.build()` using the correct configuration when `useSettings` is involved.
+    *   Interaction with `useImage(..., {override:true})` and `useText(..., {override:true})` when called after `useSettings`.
+
+### 3.3. Documentation Updates
+*   **[`docs/api-reference-guide.md`](docs/api-reference-guide.md):** Add `useSettings` to the `QRCodeBuilder` methods table.
+*   **[`docs/usage-guide.md`](docs/usage-guide.md):** Add a new subsection explaining `QRCodeBuilder.useSettings` with clear examples, emphasizing its override behavior and interaction with `.options()`.
+
+## 4. Files to be Modified for Remaining Tasks
+*   [`src/index.ts`](src/index.ts) (for `QRCodeBuilder`)
+*   [`src/node.ts`](src/node.ts) (for `QRCodeBuilder`)
+*   [`tests/node/node.settings.test.ts`](tests/node/node.settings.test.ts) (and potentially new test files)
+*   [`docs/api-reference-guide.md`](docs/api-reference-guide.md)
+*   [`docs/usage-guide.md`](docs/usage-guide.md)
+
+## 5. Key Considerations for `_resolveAndMergeConfig`
+The logic for merging needs to be precise:
+1.  If `_settingsSource` is present, it forms the new "base" by applying its constituent parts (template, style, border, text, image, data, options) sequentially on top of `baseQRTemplateOptions`.
+2.  If `_settingsSource` is NOT present, the old logic of applying `_initialOptions`, `_templateSource`, etc., applies.
+3.  `finalOptions` (from `.options()`) are merged *after* the above, allowing them to override anything set by `useSettings` or other builder methods.
+4.  Specific `override: true` calls for `useImage` or `useText` should still function as the ultimate override for those specific properties if they are called *after* `useSettings` (which would have nulled out `_settingsSource` and re-activated `_imageSource`/`_textSource`).
+
+This structured plan should allow for a smooth continuation of the task.

package/docs/ft009-settings-option-plan.md

@@ -0,0 +1,254 @@
+# Feature FT009 - Settings Option Implementation Plan
+
+This document outlines the plan to implement the `setSettings()` instance method and the `.settings()` builder method for the `QRCodeJs` class, as per Task ID FT009.
+
+## I. Define `SettingsOptions` Type
+
+1.  **Create/Update Type Definition File:**
+    *   A new file, `src/types/settings-options.ts`, will be created.
+    *   **Content:**
+        ```typescript
+        import { RecursivePartial } from './helper';
+        import { Options, BorderOptions } from '../utils/options';
+        import { StyleOptions } from './style-options';
+        import { TextOptions } from './text-options';
+
+        export interface SettingsOptions {
+          id?: string;
+          name?: string;
+          description?: string;
+          template?: string | RecursivePartial<Options>;
+          templateId?: string;
+          style?: string | StyleOptions;
+          styleId?: string;
+          text?: string | TextOptions;
+          textId?: string;
+          border?: string | RecursivePartial<BorderOptions>;
+          borderId?: string;
+          options?: RecursivePartial<Options>; // For direct overrides/merges into the main Options
+        }
+        ```
+2.  **Export:** Ensure `SettingsOptions` is exported from this new file.
+3.  **Import in `qr-code-js.ts`:** Add the necessary import for `SettingsOptions`.
+
+## II. Implement Static `QRCodeJs.settings()` Method in `qr-code-js.ts`
+
+1.  **Add Static Property:**
+    ```typescript
+    private static _selectedSettings: SettingsOptions | null = null;
+    ```
+2.  **Create Static `settings()` Method:**
+    *   Define the public static method:
+        ```typescript
+        public static settings(settings: SettingsOptions | null): typeof QRCodeJs {
+          // 1. Reset all existing static configurations to ensure "replace" behavior
+          QRCodeJs._selectedTemplate = null;
+          QRCodeJs._selectedBorder = null;
+          QRCodeJs._selectedStyle = null;
+          QRCodeJs._selectedImage = null;
+          QRCodeJs._selectedImageOverride = false;
+          QRCodeJs._selectedText = null;
+          QRCodeJs._selectedTextOverride = false;
+          // Potentially other static states if any are missed here.
+
+          if (settings === null) {
+            QRCodeJs._selectedSettings = null;
+            return QRCodeJs;
+          }
+
+          QRCodeJs._selectedSettings = settings;
+
+          // 2. Apply individual configurations from the 'settings' object
+          if (settings.templateId) {
+            QRCodeJs.setTemplateId(settings.templateId);
+          } else if (settings.template) {
+            QRCodeJs.setTemplate(settings.template);
+          }
+
+          if (settings.styleId) {
+            QRCodeJs.setStyleId(settings.styleId);
+          } else if (settings.style) {
+            QRCodeJs.setStyle(settings.style);
+          }
+
+          if (settings.textId) {
+            QRCodeJs.setTextId(settings.textId);
+          } else if (settings.text) {
+            QRCodeJs.setText(settings.text);
+          }
+
+          if (settings.borderId) {
+            QRCodeJs.setBorderId(settings.borderId);
+          } else if (settings.border) {
+            QRCodeJs.setBorder(settings.border);
+          }
+          
+          return QRCodeJs;
+        }
+        ```
+
+## III. Modify `QRCodeJs` Constructor in `qr-code-js.ts`
+
+*   The constructor's option merging logic needs to account for `_selectedSettings`.
+*   **Revised Constructor Logic (Conceptual):**
+    1.  Initialize `baseOptions`.
+    2.  Initialize `staticSettingsOptions = {}`.
+    3.  **If `QRCodeJs._selectedSettings` exists:**
+        *   If `QRCodeJs._selectedSettings.options` exists, `staticSettingsOptions` is merged with `QRCodeJs._selectedSettings.options`.
+        *   The presence of `_selectedSettings` implies that `_selectedTemplate`, `_selectedStyle`, etc., would have already been set by the `QRCodeJs.settings()` static method. The existing constructor logic that processes these will pick up the values derived from `_selectedSettings`.
+    4.  The merging order would be: `baseQRTemplateOptions`, then `staticSettingsOptions` (from `_selectedSettings.options`), then options from `_selectedTemplate`, `_selectedBorder`, `_selectedText`, `_selectedStyle`, `_selectedImage` (if any), and finally `rawOptions` passed to the constructor.
+    5.  `mergeDeep` will handle the combination.
+    6.  Proceed with validation and sanitization.
+
+## IV. Implement Instance `setSettings()` Method in `qr-code-js.ts`
+
+1.  **Create Instance `setSettings()` Method:**
+    ```typescript
+    public async setSettings(settings: SettingsOptions): Promise<void> {
+      let newOptions: RecursivePartial<Options> = { ...baseQRTemplateOptions }; // Start fresh for "replace"
+
+      // 1. Apply template
+      if (settings.templateId) {
+        const foundTemplate = findTemplateById(settings.templateId);
+        if (foundTemplate) newOptions = mergeDeep(newOptions, foundTemplate.options);
+      } else if (settings.template) {
+        if (typeof settings.template === 'string') {
+          const foundTemplate = findTemplateByName(settings.template);
+          if (foundTemplate) newOptions = mergeDeep(newOptions, foundTemplate.options);
+        } else {
+          newOptions = mergeDeep(newOptions, settings.template);
+        }
+      }
+
+      // 2. Apply style
+      if (settings.styleId) {
+        const foundStyleDef = findStyleById(settings.styleId);
+        if (foundStyleDef) newOptions = mergeDeep(newOptions, mapStyleToOptions(foundStyleDef.style));
+      } else if (settings.style) {
+        if (typeof settings.style === 'string') {
+          const foundStyleDef = findStyleByName(settings.style);
+          if (foundStyleDef) newOptions = mergeDeep(newOptions, mapStyleToOptions(foundStyleDef.style));
+        } else {
+          const { isValid, errors } = validateStyleOptions(settings.style);
+          if (isValid) {
+            newOptions = mergeDeep(newOptions, mapStyleToOptions(settings.style));
+          } else {
+            console.warn('Invalid style options in setSettings:', errors);
+          }
+        }
+      }
+
+      // 3. Apply text
+      let textOptionsToApply: RecursivePartial<Options> = {};
+      let textOpts: TextOptions | null = null;
+      if (settings.textId) {
+        const foundTextTemplate = findTextTemplateById(settings.textId);
+        if (foundTextTemplate) textOpts = foundTextTemplate.options;
+      } else if (settings.text) {
+        if (typeof settings.text === 'string') {
+          const foundTextTemplate = findTextByName(settings.text);
+          if (foundTextTemplate) textOpts = foundTextTemplate.options;
+        } else {
+          textOpts = settings.text;
+        }
+      }
+      if (textOpts) {
+        // Logic to map textOpts to borderOptions.decorations (similar to constructor)
+        if (!textOptionsToApply.borderOptions) textOptionsToApply.borderOptions = {};
+        if (!textOptionsToApply.borderOptions.decorations) textOptionsToApply.borderOptions.decorations = {};
+        const decorations = textOptionsToApply.borderOptions.decorations;
+        // ... (full mapping logic for value, topValue, leftValue, etc.)
+        newOptions = mergeDeep(newOptions, textOptionsToApply);
+      }
+
+      // 4. Apply border
+      if (settings.borderId) {
+        const foundBorder = findBorderById(settings.borderId);
+        if (foundBorder) newOptions = mergeDeep(newOptions, foundBorder.options);
+      } else if (settings.border) {
+        if (typeof settings.border === 'string') {
+          const foundBorder = findBorderByName(settings.border);
+          if (foundBorder) newOptions = mergeDeep(newOptions, foundBorder.options);
+        } else { // It's RecursivePartial<BorderOptions>
+          newOptions = mergeDeep(newOptions, { borderOptions: settings.border });
+        }
+      }
+
+      // 5. Apply direct options override
+      if (settings.options) {
+        newOptions = mergeDeep(newOptions, settings.options);
+      }
+
+      // 6. Validate and sanitize the completely new options
+      const { warnings, validatedOptions } = validateQROptions(newOptions);
+      if (warnings.length > 0) {
+        this._logValidationWarnings('QR Code setSettings Validation Warnings:', warnings);
+      }
+      
+      this.options = sanitizeOptions(validatedOptions as Options); // Replace current options
+
+      // 7. Update the QR code
+      await this.update();
+    }
+    ```
+
+## V. Documentation and Tests
+
+1.  **Documentation:**
+    *   Add `SettingsOptions` to `docs/typescript-types-definitions.md`.
+    *   Document `QRCodeJs.settings()` and `instance.setSettings()` in `docs/api-reference-guide.md` and `docs/usage-guide.md`.
+    *   Clearly explain the "replace" behavior for both methods.
+    *   Provide usage examples.
+2.  **Unit Tests:**
+    *   Add comprehensive tests for static `settings()`, instance `setSettings()`, their "replace" behavior, and interactions.
+
+## Mermaid Diagram
+
+```mermaid
+graph TD
+    subgraph Initialization
+        A[Define SettingsOptions Interface in src/types/settings-options.ts]
+    end
+
+    subgraph Static/Builder Method
+        B[Add static _selectedSettings to QRCodeJs]
+        C[Implement static QRCodeJs.settings(settings)]
+        C --> C1{settings === null?}
+        C1 -- Yes --> C2[Reset _selectedSettings AND all other static config (_template, _style, etc.)]
+        C1 -- No --> C3[Reset all other static config (_template, _style, etc.)]
+        C3 --> C4[Store in _selectedSettings]
+        C4 --> C5[Apply settings.template/Id via QRCodeJs.setTemplate/Id]
+        C5 --> C6[Apply settings.style/Id via QRCodeJs.setStyle/Id]
+        C6 --> C7[Apply settings.text/Id via QRCodeJs.setText/Id]
+        C7 --> C8[Apply settings.border/Id via QRCodeJs.setBorder/Id]
+    end
+
+    subgraph Constructor Modification
+        D[Modify QRCodeJs Constructor]
+        D --> D1[If _selectedSettings exists, its .options form part of the base]
+        D --> D2[Existing logic for _selectedTemplate, _selectedStyle, etc. then applies (values may come from _selectedSettings)]
+    end
+
+    subgraph Instance Method
+        E[Implement instance.setSettings(settings)]
+        E --> E1[Start with newOptions = baseQRTemplateOptions]
+        E1 --> E2[Apply settings.template/Id to newOptions (mergeDeep)]
+        E2 --> E3[Apply settings.style/Id to newOptions (map & mergeDeep)]
+        E3 --> E4[Apply settings.text/Id to newOptions (convert & mergeDeep)]
+        E4 --> E5[Apply settings.border/Id to newOptions (mergeDeep)]
+        E5 --> E6[Apply settings.options to newOptions (mergeDeep)]
+        E6 --> E7[Validate and Sanitize newOptions]
+        E7 --> E8[this.options = sanitizedNewOptions (REPLACE)]
+        E8 --> E9[Call this.update()]
+    end
+
+    subgraph Documentation & Testing
+        F[Update Documentation (Type, Static Method, Instance Method)]
+        G[Add Unit Tests (Static, Instance, Interactions, Replace Behavior)]
+    end
+
+    A --> C
+    A --> E
+    C8 --> D1
+    E9 --> G
+    F --> G

package/docs/typescript-types-definitions.md

@@ -270,6 +270,7 @@ interface DecorationOptions {
     fontSize: number;
     fontColor: string;
     letterSpacing: number;
+    textTransform: 'uppercase' | 'lowercase' | 'capitalize';
     fontWeight: 'normal' | 'bold';
   };
 }
@@ -292,6 +293,60 @@ interface Gradient {
 }
 ```
 
+### SettingsOptions
+
+Options for configuring multiple aspects of the QR code in a centralized way via `QRCodeJs.settings()` (static) or `instance.setSettings()` (instance).
+
+```typescript
+interface SettingsOptions {
+  /** Optional ID for the settings preset. */
+  id?: string;
+
+  /** Optional name for the settings preset. */
+  name?: string;
+
+  /** Optional description for the settings preset. */
+  description?: string;
+
+  /**
+   * Template to apply. Can be a template name (string) or a
+   * `RecursivePartial<Options>` object.
+   * This will be applied via `QRCodeJs.setTemplate()` or `QRCodeJs.setTemplateId()`.
+   */
+  template?: string | RecursivePartial<Options>;
+  templateId?: string;
+
+  /**
+   * Style to apply. Can be a style name (string) or a `StyleOptions` object.
+   * This will be applied via `QRCodeJs.setStyle()` or `QRCodeJs.setStyleId()`.
+   */
+  style?: string | StyleOptions;
+  styleId?: string;
+
+  /**
+   * Text configuration to apply. Can be a text template name (string) or a `TextOptions` object.
+   * This will be applied via `QRCodeJs.setText()` or `QRCodeJs.setTextId()`.
+   */
+  text?: string | TextOptions;
+  textId?: string;
+
+  /**
+   * Border configuration to apply. Can be a border template name (string) or a
+   * `RecursivePartial<BorderOptions>` object.
+   * This will be applied via `QRCodeJs.setBorder()` or `QRCodeJs.setBorderId()`.
+   */
+  border?: string | RecursivePartial<BorderOptions>;
+  borderId?: string;
+
+  /**
+   * A `RecursivePartial<Options>` object that will be deeply merged into
+   * the QR code's main options. This allows for direct overrides of any specific
+   * properties within the `Options` interface.
+   */
+  options?: RecursivePartial<Options>;
+}
+```
+
 ## Enums
 
 These enums provide predefined values for certain properties, ensuring type safety.