Advanced: Smart Features
Relevant source files
The following files were used as context for generating this wiki page:The QR-Tool incorporates several "smart features" designed to enhance user experience, improve the reliability of generated QR codes, and ensure security. These features operate automatically in the background, providing real-time feedback, validation, and intelligent suggestions to the user. They range from dynamic UI adjustments and live input validation to sophisticated QR code integrity checks like automatic Error Correction Code (ECC) selection and live scannability tests.
This document details the architecture and logic behind these advanced functionalities, which are primarily implemented within the main App component and utility helper functions. The goal of these features is to guide the user in creating high-quality, scannable, and secure QR codes with minimal effort.
Sources: README.md, src/App.jsx
UI Modes: Quick vs. Pro
The application offers two distinct user interface modes, "Quick" (🚀 Nhanh) and "Pro" (⚡ Chuyên sâu), to cater to different user needs. This is controlled by the uiMode state, which is persisted in localStorage.
- Quick Mode: A simplified interface that exposes only the most essential options, such as QR type and preset sizes. This is the default mode for new users.
- Pro Mode: Exposes a comprehensive set of controls for advanced customization, including manual size input, ECC level, color pickers, margin control, and logo options.
The UI conditionally renders different sets of components based on the uiMode state.
| Mode | Description | Key Features Exposed |
|---|---|---|
| Quick | Simplified UI for fast and easy QR code generation. | QR Type, Preset Sizes, Size Slider. |
| Pro | Advanced UI for fine-grained control over every aspect of the QR code. | Manual Size Input, ECC Level, Colors, Margin, Format (PNG/SVG), Logo Upload & Sizing. |
This diagram shows the conditional rendering logic based on the selected UI mode.
Sources: src/App.jsx:382-385, src/App.jsx:918-1180
Real-time Input Validation
The application performs real-time validation on user inputs to prevent errors and enhance security. A useEffect hook in App.jsx listens for changes in qrType and qrData and updates a validationErrors state object. These errors are then displayed to the user as helpful messages next to the corresponding input fields.
The core validation logic resides in src/utils/qr-helpers.js.
The following diagram illustrates the validation flow:
Sources: src/App.jsx:327-353
Validation Functions
The table below summarizes the key validation functions and their purposes.
| Feature | Validation Function(s) | Description | Source File |
|---|---|---|---|
| URL | isValidURL(), isSafeHttpUrl() | Checks for a valid URL structure and warns if the protocol is not http: or https:. | src/utils/qr-helpers.js:31-41, 78-87 |
isValidEmail() | Validates the email format using a regular expression. | src/utils/qr-helpers.js:48-52 | |
| Phone | isValidPhone() | Ensures the input contains only valid phone characters (\d, \s, +, -, ()). | src/utils/qr-helpers.js:59-63 |
| Geo-location | isValidLatLng() | Validates that latitude is between -90 and 90, and longitude is between -180 and 180. | src/utils/qr-helpers.js:70-76 |
| Hex Color | isValidHex() | Checks for a valid 3 or 6-digit hex color code. | src/utils/qr-helpers.js:104-105 |
Tests for these validation helpers can be found in tests/qr-helpers.test.js.
Sources: src/utils/qr-helpers.js, SECURITY_AUDIT_REPORT.md, tests/qr-helpers.test.js:40-90
Automatic ECC Level Selection
A critical smart feature is the automatic selection of the Error Correction Code (ECC) level. The ECC level determines the QR code's ability to withstand damage or obstruction (e.g., from a logo) and still be scannable. The application provides an "AUTO" mode for ECC, which is the default.
The logic is implemented in the pickECC function. It dynamically selects the best ECC level based on two factors:
- Logo Size: A larger logo requires a higher ECC level to compensate for the obscured data.
- Color Contrast: Poor color contrast makes scanning harder, so a higher ECC level is chosen to improve robustness.
This flow chart visualizes the decision-making process of the pickECC function.
When the ECC level is automatically set to 'H' due to a large logo, a temporary notice is shown to the user to inform them of this change.
Sources: src/App.jsx:471-483, src/App.jsx:1025-1034
Smart Suggestions and Warnings
The application provides several contextual suggestions and warnings to guide the user toward creating a high-quality QR code.
Color Contrast Checker
To ensure scannability, the contrast ratio between the foreground (QR code) and background colors is calculated in real-time. The application uses the WCAG standard formula.
relLum()calculates the relative luminance of each color.getContrastRatio()computes the ratio between the two luminance values.- If the ratio is below 4.5:1, a warning is displayed in the UI, as this can make the QR code difficult to scan, especially when printed.
Sources: src/utils/qr-helpers.js:8-28, src/App.jsx:449-450, src/App.jsx:1183-1190
Optimal Size Suggestion
The application suggests an optimal pixel size for the QR code to ensure its modules (the small black squares) are large enough to be scanned reliably. This is particularly important when the data length is long or the ECC level is high, which results in a denser QR code.
The suggestSize value is calculated based on:
- The estimated QR code dimension (number of modules) from
estimateDimension(). - A minimum module size in pixels (4px by default, or 6px if a logo is present).
// Simplified logic from App.jsx
const dim = estimateDimension(text.length, level);
const moduleMin = scale >= 0.2 ? 6 : 4;
const suggestSize = Math.ceil(dim * moduleMin);
This suggestion is displayed to the user, helping them choose an appropriate size.
Sources: src/App.jsx:457-461, src/utils/qr-helpers.js:268-274
Quiet Zone Warning
The "Quiet Zone" is a mandatory blank margin around a QR code. If the user disables the includeMargin option, the export function in ExportPanel.jsx will:
- Display a
window.confirmdialog warning the user that the QR code may be difficult to scan. - If the user proceeds, it automatically adds a safe padding (8% of the QR code's size) to the exported image to ensure reliability.
Sources: src/components/ExportPanel.jsx:35-44
Live QR Code Scannability Test
To provide immediate feedback, the application automatically runs a scannability test on the generated QR code. This feature uses the @zxing/browser library to attempt to decode the QR code directly from the rendered <canvas> element.
The process is triggered by a useEffect hook in App.jsx whenever the QR code's properties change.
This sequence diagram shows the live scanning process.
The scan is skipped for very large images (>2048px) to avoid performance issues. The result is displayed as a status message (e.g., "QR hợp lệ", "⚠️ QR có thể khó quét", "❌ Không thể đọc QR").
Sources: src/App.jsx:512-526, src/App.jsx:1222-1236
Secure by Design Features
The application integrates security-oriented "smart" features to protect users.
- File Upload Security: When uploading a logo, the
onPickLogofunction validates the file's size (max 4MB) and type (PNG, JPG, WebP, SVG) to prevent malicious uploads.
Sources: src/App.jsx:531-547, SECURITY_AUDIT_REPORT.md - URL Safety: The
isSafeHttpUrlfunction specifically checks that URLs usehttp:orhttps:protocols, warning the user against potentially dangerous schemes likejavascript:orftp:.
Sources: src/utils/qr-helpers.js:78-87, tests/qr-helpers.test.js:52-58 - Content Security Policy (CSP): A strict CSP is defined in
public/_headersto mitigate XSS and other injection attacks.
Sources: SECURITY_AUDIT_REPORT.md - Data Escaping: The application relies on React's built-in escaping for user-generated content rendered in the UI. For QR code content generation, specific escaping functions like
escWiFiandescVCARDare used to handle special characters according to their respective standards.
Sources: src/App.jsx:54-55, src/App.test.js:18-19
Conclusion
The "Advanced: Smart Features" of the QR-Tool represent a suite of intelligent, automated systems that work together to create a seamless and reliable user experience. By providing real-time validation, dynamic suggestions, and automated integrity checks, the application guides users toward producing high-quality, scannable, and secure QR codes. These features, rooted in the App.jsx component and qr-helpers.js utilities, are fundamental to the tool's goal of being both powerful for experts and accessible for beginners.