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

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @qr-platform/qr-code-js
 
+## 0.10.4
+
+### Patch Changes
+
+- 1692491: Add metadata support (id, name, description) in QRCodeJs and QRCodeBuilder for enhanced configuration options
+
+## 0.10.3
+
+### Patch Changes
+
+- 093f83a: Updated documentation for useSettings, setSettings, setData, useData, setOptions, useOptions methods
+
 ## 0.10.2
 
 ### Patch Changes

package/README.md

@@ -14,9 +14,13 @@ QRCode.js is a professional JavaScript/TypeScript library for creating customize
 *   **Core QR Code Generation**: Encode any text, URL, or data.
 *   **Highly Customizable:** Control dot shapes, colors, sizes, corner styles, and background.
 *   **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).
+*   **Image Embedding:** Embed logos or other images in the center, as an overlay, or as a background. Control image precedence with global `QRCodeJs.setImage()` or builder `useImage()`, both supporting an `override` option.
+*   **Borders (Free & Premium):** Add basic borders (with branding in free version) or advanced, customizable borders with text/images (Premium). Control text precedence with `QRCodeJs.setText()` or builder `useText()`, both supporting an `override` option.
 *   **Flexible Border Configuration:** Set global border defaults (`setBorder`/`setBorderId`) or use the builder pattern (`useBorder`/`useBorderId`) for instance-specific borders.
+*   **Templates & Styles**: Use predefined templates and styles, or create your own for consistent branding. Apply them globally with `QRCodeJs.setTemplate()` / `QRCodeJs.setStyle()` or per-instance with the builder's `useTemplate()` / `useStyle()`.
+*   **Comprehensive Configuration:**
+    *   Use `QRCodeJs.setData()`, `QRCodeJs.setOptions()`, and `QRCodeJs.setSettings()` for powerful global default configurations, with `override` options for strong precedence.
+    *   Employ the builder pattern's `useData()`, `useOptions()`, and `useSettings()` for instance-specific comprehensive setups, also with `override` capabilities. `useSettings()` resets prior builder steps to establish a new baseline.
 *   **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.
@@ -104,8 +108,9 @@ qrCode.serialize().then(svgString => {
 | `image`                | URL/Buffer/Blob of image to embed.               | `'logo.png'`         |
 | `imageOptions`         | Options for the embedded image (size, margin).   | `{ imageSize: 0.3, margin: 2 }` |
 | `borderOptions`        | **Premium.** Options for decorative borders.     | `{ hasBorder: true, thickness: 20, ... }` |
+| `SettingsOptions`      | Comprehensive object for `setSettings`/`useSettings`. | `{ templateId: '...', data: '...', ...}` |
 
-#### For a full list of options, see the [API Reference Guide](https://qr-platform.github.io/qr-code.js/docs/api-reference-guide.html).
+#### For a full list of options and detailed explanations of `SettingsOptions`, `setData`, `setOptions`, and their builder counterparts, see the [API Reference Guide](https://qr-platform.github.io/qr-code.js/docs/api-reference-guide.html) and [Usage Guide](https://qr-platform.github.io/qr-code.js/docs/usage-guide.html).
 
 ## 🎨 Examples
 
@@ -200,13 +205,13 @@ const qrPremium = new QRCodeJs({
 
 ## 📚 Documentation
 
-*   ##### [Usage Guide](https://qr-platform.github.io/qr-code.js/docs/usage-guide.html) Comprehensive guide covering all options.
-*   ##### [API Reference](https://qr-platform.github.io/qr-code.js/docs/api-reference-guide.html) Detailed reference for all options, methods, and enums.
-*   ##### [TypeScript Definitions](https://qr-platform.github.io/qr-code.js/docs/typescript-types-definitions.html) Full TypeScript type definitions.
-*   ##### [Basic Examples](https://qr-platform.github.io/qr-code.js/docs/examples.html) Simple examples to get started.
-*   ##### [Advanced Examples](https://qr-platform.github.io/qr-code.js/docs/advanced-examples.html) Complex customization examples.
-*   ##### [License Management](https://qr-platform.github.io/qr-code.js/docs/license-management.html) Details on free vs. premium features and activation. 
+*   **[Full Documentation](./docs/documentation.md#start)**: The main guide covering all features, options, and concepts.
+*   **[API Reference](./docs/api-reference-guide.md#start)**: Detailed reference for all classes, methods, and types.
+*   **[Usage Guide](./docs/usage-guide.md#start)**: Practical examples and explanations for common use cases.
+*   **[Basic Examples](./docs/examples.md#start)**: Simple examples to get started quickly.
+*   **[Advanced Examples](./docs/advanced-examples.md#start)**: Demonstrations of complex configurations and feature combinations, including `setSettings` and `useSettings`.
+*   **[License Management](./docs/license-management.md#start)**: Information on activating and managing premium features.
 
 ## 📜 License
 
-This Software is licensed, not sold, by QR-Platform ("Licensor") for use only under the terms of this license. The source code for the Software is proprietary, confidential, and is **not** provided or licensed under this agreement. Licensor reserves all rights not expressly granted to User - see the [LICENSE](https://qr-platform.github.io/qr-code.js/LICENSE.md) file for details. Premium features require a separate commercial license from [QR-Platform](https://www.qr-platform.com).
+This Software is licensed, not sold, by QR-Platform ("Licensor") for use only under the terms of this license. The source code for the Software is proprietary, confidential, and is **not** provided or licensed under this agreement. Licensor reserves all rights not expressly granted to User - see the [LICENSE](https://qr-platform.github.io/qr-code.js/LICENSE.md) file for details. Premium features require a separate commercial license from [QR-Platform](https://www.qr-platform.com).

package/docs/advanced-examples.md

@@ -375,6 +375,127 @@ QRCodeJs.setImage(null);
 
 ---
 
+### Comprehensive Configuration with `SettingsOptions` (`setSettings` and `useSettings`)
+
+Demonstrates using `QRCodeJs.setSettings()` for establishing global presets and `QRCodeJs.useSettings()` for applying comprehensive configurations within a builder chain. These methods utilize the `SettingsOptions` interface.
+
+**Example 1: Defining and Applying a Global Preset with `QRCodeJs.setSettings()`**
+
+`QRCodeJs.setSettings()` acts as a macro, calling other static setters like `setData()`, `setImage()`, `setTemplate()`, `setStyle()`, `setOptions()`, etc., based on the provided `SettingsOptions`. It overrides/resets previous static configurations for the aspects it covers.
+
+```typescript
+// Define a comprehensive global preset using SettingsOptions
+const companyGlobalPreset: SettingsOptions = {
+  name: 'CompanyStandardGlobalQR',
+  data: 'https://company.com/global-default', // Will call QRCodeJs.setData()
+  image: 'https://company.com/assets/global-logo.png', // Will call QRCodeJs.setImage()
+  templateId: 'dots', // Assumes 'dots' template exists, will call QRCodeJs.setTemplateId()
+  style: { // Will call QRCodeJs.setStyle()
+    dotsOptions: { color: '#003366' }, // Company dark blue
+    backgroundOptions: { color: '#EFEFEF' }
+  },
+  borderOptions: { // Will call QRCodeJs.setBorder()
+    hasBorder: true,
+    thickness: 12,
+    color: '#003366'
+  },
+  options: { // Will call QRCodeJs.setOptions()
+    margin: 8,
+    qrOptions: { errorCorrectionLevel: 'Q' }
+  }
+};
+
+// Apply the preset globally
+QRCodeJs.setSettings(companyGlobalPreset);
+
+// This QR code will inherit all settings from companyGlobalPreset
+const qrFromGlobalSettings = new QRCodeJs({
+  // Data is inherited from companyGlobalPreset.data
+  // Image, template, style, border, margin, EC level are also inherited.
+});
+qrFromGlobalSettings.append(document.getElementById('global-settings-preset-container'));
+
+// Another instance, overriding only the data from the global preset
+const qrOverrideGlobalData = new QRCodeJs({
+  data: 'https://company.com/specific-product-page' // Overrides companyGlobalPreset.data
+});
+qrOverrideGlobalData.append(document.getElementById('global-settings-override-data-container'));
+
+// Clear all global settings when done if they are not needed for subsequent QRs
+// QRCodeJs.setSettings(null);
+```
+
+**Example 2: Using `QRCodeJs.useSettings()` in a Builder Chain**
+
+`QRCodeBuilder.useSettings()` resets any configurations previously applied to *that builder instance* and establishes the provided `SettingsOptions` as the new baseline.
+
+```typescript
+const eventSpecificBuilderConfig: SettingsOptions = {
+  name: 'TechConferenceBuilderQR',
+  data: 'https://techconf.example/main-schedule', // Baseline data for this builder
+  image: 'https://techconf.example/assets/event-logo-qr.png', // Baseline image
+  styleId: 'modern-dark', // Assumes 'modern-dark' style ID exists
+  text: { // Border text configuration (will be part of the baseline)
+    topValue: 'Tech Conference 2024',
+    bottomValue: 'Scan for Schedule & Info'
+  },
+  borderOptions: { // Baseline border
+    hasBorder: true,
+    thickness: 20,
+    color: '#2C3E50',
+    radius: '8px'
+  },
+  options: { // Baseline general options
+    qrOptions: { errorCorrectionLevel: 'H' },
+    isResponsive: true,
+    margin: 12
+  }
+};
+
+// Start with a base template (will be reset), apply comprehensive settings, then further customize
+const qrEventSpecialBuilder = QRCodeJs.useTemplate('dots') // This 'dots' template will be reset by useSettings
+  .useStyle({ dotsOptions: { color: 'red' }}) // This style will also be reset
+  .useSettings(eventSpecificBuilderConfig) // Applies the full eventSpecificConfig, resetting prior builder steps
+  .useStyle({ // Further refine the style from the useSettings baseline
+    dotsOptions: { gradient: { type: 'linear', colorStops: [{offset:0, color:'#5DADE2'}, {offset:1, color:'#2E86C1'}] } }
+  })
+  .options({ // Final data override and other specific options
+    data: 'https://techconf.example/live-updates-feed', // Overrides data from eventSpecificBuilderConfig
+    margin: 6 // Overrides margin from eventSpecificBuilderConfig.options
+  });
+
+qrEventSpecialBuilder.append(document.getElementById('builder-usesettings-container'));
+```
+
+**Example 3: Showcasing `overrideOpts` with Static `setData` and `setOptions`**
+
+The `overrideOpts: { override: true }` parameter makes static settings "sticky", meaning they are harder to override by instance options or non-overriding builder methods.
+
+```typescript
+// Set data with override:true; it will take precedence over instance data
+QRCodeJs.setData('https://permanent-global-link.com', { override: true });
+
+// Set some options with override:true
+QRCodeJs.setOptions(
+    { dotsOptions: { type: 'star', color: 'gold' }, margin: 0, shape: 'circle' },
+    { override: true }
+);
+
+const qrStaticOverridesDemo = new QRCodeJs({
+    data: 'https://this-data-is-ignored-by-instance.com', // Will use 'https://permanent-global-link.com'
+    dotsOptions: { type: 'square', color: 'black' }, // Will use star, gold (type and color overridden)
+    margin: 20, // Will use 0 (overridden)
+    shape: 'square' // Will use 'circle' (overridden)
+});
+qrStaticOverridesDemo.append(document.getElementById('static-override-example-container'));
+
+// Clear static settings when done to avoid affecting other examples
+QRCodeJs.setData(null); // This clears the override as well
+QRCodeJs.setOptions(null); // This clears the override as well
+```
+
+---
+
 ### Border Options and Decorations (Premium Feature)
 
 Uses premium border features for advanced styling and text. Requires a license.
@@ -387,10 +508,13 @@ Uses premium border features for advanced styling and text. Requires a license.
 
 // 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 });
+QRCodeJs.setText(
+  {
+    topValue: 'GLOBAL OVERRIDE TEXT',
+    bottomValue: 'PRIORITY FOOTER TEXT'
+  }, 
+  { override: true } // MethodOverrideOptions
+);
 
 // Even when an instance specifies border text, the global one with override will be used
 const qrTextOverride = new QRCodeJs({
@@ -414,10 +538,13 @@ const qrTextOverride = new QRCodeJs({
 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 })
+const qrBuilderTextOverride = QRCodeJs.useText(
+  {
+    leftValue: 'LEFT OVERRIDE TEXT',
+    rightValue: 'RIGHT OVERRIDE TEXT'
+  }, 
+  { override: true } // MethodOverrideOptions
+)
   .options({
     data: 'https://example.com/builder-text-override-example',
     borderOptions: {

package/docs/api-reference-guide.md

@@ -90,22 +90,26 @@ qrCode.append(document.getElementById('qr-container'));
 | `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`. |
+| `setText`           | `textNameOrOptions: string \| TextOptions \| null, overrideOpts?: MethodOverrideOptions` | 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, overrideOpts?: MethodOverrideOptions`                 | 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.
-| `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>`. |
+| `setImage`          | `imageUrl: string \| DataURL \| null, overrideOpts?: MethodOverrideOptions`    | Sets a global default image URL for subsequent instances. With `{ override: true }`, the image will take precedence over any instance-specific images. Returns `typeof QRCodeJs`. |
+| `setData`           | `data: string \| null, overrideOpts?: MethodOverrideOptions`                   | **(Static)** Sets a global default data string for subsequent `QRCodeJs` instances. If `overrideOpts.override` is `true`, this data will take precedence over data set by other means (e.g., in constructor options or through `useData` without override). Returns `typeof QRCodeJs`. |
+| `setOptions`        | `options: RecursivePartial<Options> \| null, overrideOpts?: MethodOverrideOptions` | **(Static)** Sets global default options for subsequent `QRCodeJs` instances. These are merged deeply with other defaults and instance-specific options. If `overrideOpts.override` is `true`, these options take higher precedence over options set by other means for the properties they cover. Returns `typeof QRCodeJs`. |
+| `setSettings`       | `settings: SettingsOptions \| null`                                        | **(Static)** Sets multiple global defaults at once using a comprehensive `SettingsOptions` object. This acts as a macro, internally calling other static setters (like `setTemplate`, `setStyle`, `setData`, `setImage`, `setOptions`, etc.) based on the properties provided in the `settings` object. It will override/reset any previously set static configurations for the aspects it covers. Passing `null` clears all static configurations. Returns `typeof QRCodeJs`. |
 | `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`. |
+| `useText`           | `textNameOrOptions: string \| TextOptions, overrideOpts?: MethodOverrideOptions` | 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, overrideOpts?: MethodOverrideOptions`                         | 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.
+| `useImage`          | `imageUrl: string \| DataURL, overrideOpts?: MethodOverrideOptions`            | Initiates a builder pattern pre-configured with an image URL. If `overrideOpts.override` is `true`, this image will take precedence over any image set in the final `.options()` call or by other non-overriding builder methods. Returns `QRCodeBuilder`. |
+| `useData`           | `data: string, overrideOpts?: MethodOverrideOptions`                           | Applies a data string to the current builder configuration. If `overrideOpts.override` is `true`, this data will take precedence over data provided in the final `.options()` call or by other non-overriding builder methods. Returns `QRCodeBuilder`. |
+| `useOptions`        | `options: RecursivePartial<Options>, overrideOpts?: MethodOverrideOptions`     | Applies a partial options object to the current builder configuration. If `overrideOpts.override` is `true`, these options take higher precedence over options provided in the final `.options()` call or by other non-overriding builder methods for the properties they cover. Returns `QRCodeBuilder`. |
+| `useSettings`       | `settings: SettingsOptions`                                                | Applies a comprehensive `SettingsOptions` object as a new baseline for the builder chain. This will **reset** any configurations previously applied to *that builder instance* via methods like `useTemplate()`, `useStyle()`, `useData()`, `useOptions()`, etc. Subsequent builder methods will modify this new baseline. Returns `QRCodeBuilder`. |
 | `validateScanning`  | `validatorId?: string, debug?: boolean`                                    | **(Premium method)** Validates that the QR code is scannable. Returns `Promise<ScanValidatorResponse>`. |
 
 ---
@@ -298,13 +302,15 @@ 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`. |
+| `useText`     | `textNameOrOptions: string \| TextOptions, overrideOpts?: MethodOverrideOptions` | 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, overrideOpts?: MethodOverrideOptions`                         | 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`. |
-| `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.    |
+| `useImage`    | `imageUrl: string, overrideOpts?: MethodOverrideOptions`                       | Sets the image URL for the current configuration. If `overrideOpts.override` is `true`, this image will take precedence over any image set in the final `.options()` call. Returns `this`. |
+| `useData`     | `data: string, overrideOpts?: MethodOverrideOptions`                           | Applies a data string to the current builder configuration. If `overrideOpts.override` is `true`, this data will take precedence over data provided in the final `.options()` call. Returns `this`. |
+| `useOptions`  | `options: RecursivePartial<Options>, overrideOpts?: MethodOverrideOptions`     | Applies a partial options object to the current builder configuration. If `overrideOpts.override` is `true`, these options take higher precedence over options provided in the final `.options()` call for the properties they cover. Returns `this`. |
+| `useSettings` | `settings: SettingsOptions`                                                | Applies a comprehensive `SettingsOptions` object as a new baseline for the builder chain. This will **reset** any configurations previously applied to *that builder instance* via other `use` methods. Subsequent builder methods modify this new baseline. Returns `this`. |
+| `options`     | `options: RecursivePartial<Options>`                                       | Merges the provided `Options` into the current configuration and creates and returns the final `QRCodeJs` instance.    |
 | `build`       | -                                                                          | Creates and returns the final `QRCodeJs` instance based on the accumulated configuration.                  |
 ### See Also
 - [QRCode.js Documentation](./documentation.md#start)