@qr-platform/qr-code.js 0.20.1 → 0.20.2

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @qr-platform/qr-code-js
 
+## 0.20.2
+
+### Patch Changes
+
+- 0e4b1dd: Added documentation about width and height options
+
 ## 0.20.1
 
 ### Patch Changes

package/README.md

@@ -63,6 +63,8 @@ import { QRCodeJs, Options } from '@qr-platform/qr-code.js';
 // 1. Define options (only 'data' is required)
 const options: Options = {
   data: 'https://example.com',
+  width: 300,       // Fixed 300px width
+  height: 300,      // Fixed 300px height
   dotsOptions: {
     color: '#007bff', // Blue dots
     type: 'rounded'   // Use rounded dots
@@ -98,7 +100,10 @@ qrCode.serialize().then(svgString => {
 | :--------------------- | :----------------------------------------------- | :------------------- |
 | `data`                 | **Required.** The content to encode.             | `'Your URL here'`    |
 | `shape`                | Overall shape (`'square'` or `'circle'`).        | `'circle'`           |
+| `width`                | QR code width (pixels/CSS units). Ignored when `isResponsive: true`. | `300` or `'20rem'`   |
+| `height`               | QR code height (pixels/CSS units). Ignored when `isResponsive: true`. | `300` or `'20rem'`   |
 | `margin`               | Quiet zone around the QR code (pixels).          | `10`                 |
+| `isResponsive`         | Makes SVG responsive (100% width/height), ignoring `width`/`height`. | `true`               |
 | `qrOptions.errorCorrectionLevel` | Error correction (`'L'`, `'M'`, `'Q'`, `'H'`). | `'H'`                |
 | `dotsOptions.type`     | Shape of the data dots (e.g., `rounded`, `dot`). | `'rounded'`          |
 | `dotsOptions.color`    | Color of the data dots.                          | `'#ff5733'`          |

package/docs/advanced-examples.md

@@ -90,6 +90,45 @@ if (responsiveContainer) {
 }
 ```
 
+**Example 3: Fixed Dimensions with CSS Units**
+
+```typescript
+const qrLayoutCSSUnits = new QRCodeJs({
+  data: 'https://example.com/css-dimensions',
+  width: '25rem',     // Fixed width using rem units
+  height: '25rem',    // Fixed height using rem units
+  isResponsive: false, // Use specified dimensions (default)
+  dotsOptions: {
+    color: '#7B1FA2',  // Purple dots
+    type: 'extraRounded'
+  },
+  backgroundOptions: {
+    color: '#F3E5F5',  // Light purple background
+    round: 0.1
+  }
+});
+qrLayoutCSSUnits.append(document.getElementById('layout-css-units-container'));
+```
+
+**Example 4: Mixed Pixel and Percentage Dimensions**
+
+```typescript
+const qrLayoutMixed = new QRCodeJs({
+  data: 'https://example.com/mixed-dimensions',
+  width: 400,         // Fixed pixel width
+  height: '50vh',     // Height as 50% of viewport height
+  dotsOptions: {
+    color: '#E65100',  // Deep orange dots
+    type: 'classy'
+  },
+  cornersSquareOptions: {
+    color: '#FF8F00',  // Lighter orange corners
+    type: 'rounded'
+  }
+});
+qrLayoutMixed.append(document.getElementById('layout-mixed-container'));
+```
+
 ---
 
 ### Dot Styling

package/docs/api-reference-guide.md

@@ -23,8 +23,10 @@ qrCode.append(document.getElementById('qr-container'));
 | :--------------------- | :------------------------------------- | :------------- | :-------------------------------------------------------------------------- |
 | `data`                 | `string`                               | -              | Specifies the text, URL, or other data to encode into the QR code. **Required option**  | 
 | `shape`                | `'square' \| 'circle'`                 | `'square'`     | The overall shape of the QR code's boundary. See [ShapeType](#enums-shapetype) enum.
+| `width`                | `number \| string`                     | Auto-calculated| QR code width in pixels or CSS units. When `isResponsive` is false, overrides auto-calculated width. When `isResponsive` is true, this value is ignored. |
+| `height`               | `number \| string`                     | Auto-calculated| QR code height in pixels or CSS units. When `isResponsive` is false, overrides auto-calculated height. When `isResponsive` is true, this value is ignored. |
 | `margin`               | `number`                               | `0`            | The quiet zone (empty space) around the QR code in pixels.                  |
-| `isResponsive`         | `boolean`                              | `false`        | When `true`, the QR code SVG resizes dynamically to fill the width or height of the parent container, with no internal size dimensions applied. |
+| `isResponsive`         | `boolean`                              | `false`        | Controls whether the QR code SVG should be responsive to its container. When true, SVG uses 100% width/height, ignoring any specified width/height values. When false, SVG uses specified width/height values or auto-calculated dimensions. |
 | `scale`                | `number` (0 to 1.5)                    | `1`            | Scales the QR code size relative to its container or border.                |
 | `offset`               | `number`                               | `0`            | Applies a vertical offset (positive moves down, negative moves up) relative to the center. |
 | `verticalOffset`       | `number`                               | `0`            | Applies an absolute vertical offset in pixels.                              |

package/docs/documentation.md

@@ -67,16 +67,79 @@ qrCode.append(document.getElementById('qr-container'));
   margin: 20
   ```
 
+### `width` and `height`
+
+- **Purpose**: Allows you to specify custom dimensions for the QR code SVG. When `isResponsive` is `false`, these values override the auto-calculated dimensions. When `isResponsive` is `true`, these values are ignored in favor of responsive sizing.
+- **Type**: `number | string` (optional)
+- **Default**: Auto-calculated based on QR code content and options
+- **Supported formats**: 
+  - Numbers (pixels): `300`, `500`
+  - CSS units: `'300px'`, `'20rem'`, `'50vh'`, `'100%'`
+- **Examples**:
+  ```typescript
+  // Fixed pixel dimensions
+  width: 300,
+  height: 300
+
+  // CSS units
+  width: '20rem',
+  height: '20rem'
+
+  // Mixed units
+  width: 400,
+  height: '30vh'
+  ```
+
 ### `isResponsive`
 
-- **Purpose**: Allows the QR code SVG to resize dynamically based on its container size. If `false`, fixed `width` and `height` attributes are set on the SVG.
+- **Purpose**: Controls whether the QR code SVG should be responsive to its container. When `true`, the SVG uses 100% width/height and ignores any specified `width`/`height` values. When `false`, the SVG uses specified `width`/`height` values or auto-calculated dimensions.
 - **Type**: `boolean`
 - **Default**: `false`
-- **Example**:
+- **Interaction with width/height**:
+  - When `true`: SVG becomes fluid (100% width/height), any `width`/`height` values are ignored
+  - When `false`: SVG uses `width`/`height` values if provided, otherwise uses auto-calculated dimensions
+- **Examples**:
   ```typescript
-  isResponsive: true
+  // Responsive QR code (ignores width/height)
+  isResponsive: true,
+  width: 500,  // This will be ignored
+  height: 500  // This will be ignored
+
+  // Fixed size QR code (uses width/height)
+  isResponsive: false, // or omit (default)
+  width: 300,
+  height: 300
   ```
 
+### Dimension Control Use Cases
+
+**1. Fixed-Size QR Codes (Print, Downloads):**
+```typescript
+const qrCode = new QRCodeJs({
+  data: 'Fixed size for printing',
+  width: 300,
+  height: 300,
+  isResponsive: false // Default behavior
+});
+```
+
+**2. Responsive Web QR Codes:**
+```typescript
+const qrCode = new QRCodeJs({
+  data: 'Responsive for web',
+  isResponsive: true // Ignores width/height, uses container size
+});
+```
+
+**3. CSS Unit Dimensions:**
+```typescript
+const qrCode = new QRCodeJs({
+  data: 'Using CSS units',
+  width: '20rem',
+  height: '20rem'
+});
+```
+
 ### `qrOptions`
 
 Options that affect the QR code generation algorithm.

package/docs/examples.md

@@ -684,6 +684,82 @@ qrUseSettings1.append(document.getElementById('builder-usesettings-container-1')
 
 ---
 
+## Dimension Control
+
+Control the size and responsiveness of your QR codes with `width`, `height`, and `isResponsive` options.
+
+### Fixed Size QR Codes
+
+Perfect for downloads, print materials, or when you need exact pixel dimensions:
+
+```javascript
+// Basic fixed size QR code
+const fixedQR = new QRCodeJs({
+  data: 'Fixed size QR code - 300x300 pixels',
+  width: 300,
+  height: 300,
+  isResponsive: false // Default behavior
+});
+fixedQR.append(document.getElementById('fixed-size-container'));
+```
+
+### Using CSS Units
+
+You can specify dimensions using any CSS units:
+
+```javascript
+// QR code with CSS units
+const cssUnitsQR = new QRCodeJs({
+  data: 'QR code with CSS units',
+  width: '20rem',    // Using rem units
+  height: '20rem',   // Using rem units
+  dotsOptions: {
+    color: '#007bff',
+    type: 'rounded'
+  }
+});
+cssUnitsQR.append(document.getElementById('css-units-container'));
+```
+
+### Responsive QR Codes
+
+For web applications where the QR code should adapt to its container:
+
+```javascript
+// Responsive QR code - scales with container
+const responsiveQR = new QRCodeJs({
+  data: 'Responsive QR code - fills container',
+  width: 500,        // This will be ignored
+  height: 500,       // This will be ignored
+  isResponsive: true, // SVG becomes fluid (100% width/height)
+  dotsOptions: {
+    color: '#28a745',
+    type: 'extraRounded'
+  }
+});
+responsiveQR.append(document.getElementById('responsive-container'));
+```
+
+### Real-World Example: Your Provided Code
+
+```javascript
+const qrCode = new QRCodeJs({
+  data: 'test/test/test22dasdasd',
+  scale: 1,
+  width: '100',     // String width value
+  height: '100',    // String height value
+  imageOptions: {
+    imageSize: 1,
+    backgroundColor: '#8e44ad',
+    margin: 0.2,
+    padding: 8,
+    radius: '5%'
+  }
+});
+```
+
+---
+
 ### Border Options (Free Version)
 
 Adding a basic border (includes "QR-Platform" branding).

package/docs/typescript-types-definitions.md

@@ -24,10 +24,30 @@ interface Options {
   /** The overall shape of the QR code's boundary. */
   shape: ShapeType;
 
+  /** 
+   * QR code width in pixels or CSS units (e.g., '300px', '100%').
+   * When isResponsive is false: This value overrides the auto-calculated width and sets the SVG width attribute.
+   * When isResponsive is true: This value is ignored and the SVG uses 100% width.
+   * If not specified, the library calculates the optimal width based on QR code size and options.
+   */
+  width?: number | string;
+
+  /** 
+   * QR code height in pixels or CSS units (e.g., '300px', '100%').
+   * When isResponsive is false: This value overrides the auto-calculated height and sets the SVG height attribute.
+   * When isResponsive is true: This value is ignored and the SVG uses 100% height.
+   * If not specified, the library calculates the optimal height based on QR code size and options.
+   */
+  height?: number | string;
+
   /** The quiet zone (empty space) around the QR code in pixels. */
   margin: number;
 
-  /** When true, the QR code SVG resizes dynamically to fill the width or height of the parent container, with no internal size dimensions applied. */
+  /** 
+   * Controls whether the QR code SVG should be responsive to its container.
+   * When true: SVG uses 100% width/height, ignoring any specified width/height values.
+   * When false (default): SVG uses specified width/height values or auto-calculated dimensions.
+   */
   isResponsive: boolean;
 
   /** Scales the QR code size relative to its container or border. */

package/docs/usage-guide.md

@@ -70,14 +70,16 @@ const qrCode = new QRCodeJs({
 
 These options control the positioning, scaling, and responsiveness of the QR code within its container or border.
 
-| Option             | Type     | Default | Description                                                                 |
-| :----------------- | :------- | :------ | :-------------------------------------------------------------------------- |
-| `margin`           | `number` | `0`     | The quiet zone (empty space) around the QR code in pixels.                  |
-| `isResponsive`     | `boolean`| `false` | When `true`, the QR code SVG resizes dynamically to fill the width or height of the parent container, with no internal size dimensions applied. |
-| `scale`            | `number` | `1`     | Scales the QR code size relative to its container or border (0 to 1.5).     |
-| `offset`           | `number` | `0`     | Applies a vertical offset (positive moves down, negative moves up) relative to the center. |
-| `verticalOffset`   | `number` | `0`     | Applies an absolute vertical offset in pixels.                              |
-| `horizontalOffset` | `number` | `0`     | Applies an absolute horizontal offset in pixels.                            |
+| Option             | Type               | Default         | Description                                                                 |
+| :----------------- | :----------------- | :-------------- | :-------------------------------------------------------------------------- |
+| `width`            | `number \| string` | Auto-calculated | QR code width in pixels or CSS units. When `isResponsive` is false, overrides auto-calculated width. When `isResponsive` is true, this value is ignored. |
+| `height`           | `number \| string` | Auto-calculated | QR code height in pixels or CSS units. When `isResponsive` is false, overrides auto-calculated height. When `isResponsive` is true, this value is ignored. |
+| `margin`           | `number`           | `0`             | The quiet zone (empty space) around the QR code in pixels.                  |
+| `isResponsive`     | `boolean`          | `false`         | Controls whether the QR code SVG should be responsive to its container. When true, SVG uses 100% width/height, ignoring any specified width/height values. When false, SVG uses specified width/height values or auto-calculated dimensions. |
+| `scale`            | `number`           | `1`             | Scales the QR code size relative to its container or border (0 to 1.5).     |
+| `offset`           | `number`           | `0`             | Applies a vertical offset (positive moves down, negative moves up) relative to the center. |
+| `verticalOffset`   | `number`           | `0`             | Applies an absolute vertical offset in pixels.                              |
+| `horizontalOffset` | `number`           | `0`             | Applies an absolute horizontal offset in pixels.                            |
 
 ##### Example: Layout Options
 
@@ -90,6 +92,39 @@ const qrCode = new QRCodeJs({
   horizontalOffset: -5  // Absolute 5px left
 });
 ```
+
+##### Dimension Control Examples
+
+**Fixed Size QR Code:**
+```javascript
+const qrCode = new QRCodeJs({
+  data: 'Fixed size QR code',
+  width: 300,           // Fixed 300px width
+  height: 300,          // Fixed 300px height
+  isResponsive: false   // Use fixed dimensions (default)
+});
+```
+
+**Responsive QR Code:**
+```javascript
+const qrCode = new QRCodeJs({
+  data: 'Responsive QR code',
+  width: 500,           // This will be ignored
+  height: 500,          // This will be ignored
+  isResponsive: true    // SVG will use 100% width/height
+});
+```
+
+**CSS Units:**
+```javascript
+const qrCode = new QRCodeJs({
+  data: 'QR code with CSS units',
+  width: '20rem',       // Using rem units
+  height: '20rem',      // Using rem units
+  isResponsive: false
+});
+```
+
 ---
 
 ### Styling Options