Utility: qr-helpers.js
Relevant source files
The following files were used as context for generating this wiki page:The qr-helpers.js file is a crucial utility module for the QR Generator Pro application. It provides a suite of helper functions responsible for input data validation, color and contrast calculations, dynamic QR code parameter selection, and image export processing. These functions ensure data integrity, enhance QR code scannability, and enable the advanced customization features offered in the application, such as adding logos, custom colors, and exporting to different formats.
The module is heavily utilized by the main App.jsx component to validate user input in real-time, calculate optimal QR code settings, and prepare the final image for download.
Input Validation
Sources: src/utils/qr-helpers.js:30-94, src/App.jsx:311-336, SECURITY_AUDIT_REPORT.md:50-71
This set of functions is responsible for validating user-provided data for various QR code types. This is a critical security and usability feature, preventing the generation of invalid or potentially malicious QR codes. The App.jsx component uses these functions within a React.useEffect hook to provide real-time feedback to the user.
The following diagram illustrates the validation flow within the App.jsx component.
This diagram shows how user input triggers a validation check in App.jsx, which calls the appropriate helper function from qr-helpers.js and updates the UI with any errors.
Validation Functions
The table below summarizes the available validation functions and their purpose. All functions are designed to return true if the input is empty, allowing for optional fields.
| Function | Description | Source File |
|---|---|---|
isValidURL(url) | Checks if a string is a structurally valid URL using the new URL() constructor. | src/utils/qr-helpers.js:30-38 |
isSafeHttpUrl(url) | Verifies that a URL uses only the http: or https: protocols to prevent schemes like javascript:. | src/utils/qr-helpers.js:85-94 |
isValidEmail(email) | Validates an email address format using a regular expression. | src/utils/qr-helpers.js:41-47 |
isValidPhone(phone) | Checks if a string contains only valid phone number characters (\d, \s, +, -, ()). | src/utils/qr-helpers.js:50-56 |
isValidLatLng(lat, lng) | Validates that latitude is between -90 and 90, and longitude is between -180 and 180. | src/utils/qr-helpers.js:59-68 |
isValidHex(hex) | Validates if a string is a valid 3 or 6-digit hex color code. | src/utils/qr-helpers.js:110-111 |
Sources: src/utils/qr-helpers.js, tests/qr-helpers.test.js:46-91
Color & Contrast Helpers
Sources: src/utils/qr-helpers.js:6-28, src/App.jsx:429-430
These functions are used to manage colors and ensure the generated QR code has sufficient contrast to be easily scannable, adhering to WCAG (Web Content Accessibility Guidelines) principles.
| Function | Description | Source File |
|---|---|---|
normalizeHex(hex) | Converts a 3-digit hex color (e.g., #F0C) to its 6-digit equivalent (#FF00CC). | src/utils/qr-helpers.js:97-107 |
relLum(hex) | Calculates the relative luminance of a 6-digit hex color, returning a value between 0 (black) and 1 (white). | src/utils/qr-helpers.js:6-17 |
getContrastRatio(lum1, lum2) | Calculates the contrast ratio between two relative luminance values. A ratio of >= 4.5:1 is generally recommended. | src/utils/qr-helpers.js:20-28 |
The App.jsx component uses getContrastRatio to warn the user if the selected foreground and background colors have low contrast.
Sources: src/App.jsx:429-430, src/App.jsx:1068-1075
QR Code Parameter Calculation
These helpers dynamically calculate optimal parameters for the QR code based on user settings like logo size and data length.
ECC Level Selection
The pickECC function automatically selects the best Error Correction Capability (ECC) level. A higher ECC level allows the QR code to be read even if parts of it are obscured (e.g., by a logo) or damaged.
This flowchart shows the decision logic for pickECC. It prioritizes robustness by selecting 'H' for large logos or poor contrast, otherwise choosing 'Q' or 'M' based on logo size.
The function takes the following arguments:
mode: The user-selected mode ('AUTO','L','M','Q','H').logoRatio: The ratio of the logo's size to the QR code's size (0 to 1).contrastOk: A boolean indicating if the color contrast is sufficient (>= 3.5:1).
Sources: src/utils/qr-helpers.js:241-249, src/App.jsx:432-435
Dimension Estimation
The estimateDimension function provides a suggested minimum size (in pixels) for the QR code to ensure scannability. It calculates the required number of modules based on the length of the data and the ECC level.
// src/utils/qr-helpers.js:252-261
export function estimateDimension(dataLength, ecc = 'M') {
const k = { L: 1.0, M: 1.2, Q: 1.4, H: 1.6 }[ecc];
const v = Math.ceil((dataLength * k) / 14);
const dim = 21 + 4 * Math.max(1, Math.min(40, v));
return dim;
}
This estimation is used in App.jsx to suggest an optimal size to the user, especially when a logo is present, which requires larger modules to maintain scannability.
Sources: src/utils/qr-helpers.js:252-261, src/App.jsx:437-441
Canvas & SVG Export Helpers
Sources: src/utils/qr-helpers.js:116-236
This group of functions handles the final export of the generated QR code to either a raster (PNG/JPG) or vector (SVG) format. They add features like padding (quiet zone), background colors, and rounded corners.
The following sequence diagram shows the export process for a PNG file.
Key Export Functions
| Function | Description | Source File |
|---|---|---|
buildDataURL(canvas, ext, options) | Takes a source canvas and generates a new data URL. It can add padding (padPx), a background color (bg), and rounded corners (rounded). Used for PNG/JPG export. | src/utils/qr-helpers.js:145-177 |
buildSVGBlob(svgElement, options) | Takes a source SVG element and generates a new SVG blob. It can add padding (padPx) and a background color (bg) by creating a new <rect> and transforming the original content. | src/utils/qr-helpers.js:180-217 |
downloadFile(data, filename) | Triggers a browser download for a given data URL or Blob by creating a temporary <a> element and simulating a click. | src/utils/qr-helpers.js:220-236 |
roundRectPath(ctx, ...) | A low-level canvas helper that draws a path for a rectangle with rounded corners. Used by buildDataURL. | src/utils/qr-helpers.js:116-130 |
Conclusion
The qr-helpers.js module is a cornerstone of the QR-Tool application, encapsulating the core logic for data validation, aesthetic customization, and file generation. By centralizing these functions, the module promotes code reuse, simplifies the main application component (App.jsx), and ensures consistent behavior across different features. Its robust validation and dynamic parameter calculations are key to producing high-quality, scannable, and secure QR codes.