Add ui classes and id, update file selection UI & graduate useBarCode…

…DetectorIfSupported from experimental

#### Add support for custom CSS
Developer / User Story: As a developer I can write custom CSS for `Html5QrcodeScanner`.

Feature request: [Issue#389](#389)

List of CSS class and IDs added.

1. All key elements will have a common CSS class `html5-qrcode-element`. This way developers can customise element by element. For example:

```css
button.html5-qrcode-element {
    color: 'red' !important,
    border: '1px solid red' !important
}
```

Key elements are:
-    Request camera permission button.
-    "Scan and image file" vs "Scan using camera directly" link.
-    "File selection" input ('file')
-    Start or Stop camera button.
-    Camera selection Select element
-    Torch button

2. key elements will have specific IDs defined in `src/ui/scanner/base.ts`. This can be used to customise per elements.

##### TODOs
-   [ ] Document in a blog post
-   [ ] Add pointer in qrcode.minhazav.dev
-   [ ] Add pointer in Readme

#### Graduate `useBarCodeDetectorIfSupported` to `Html5QrcodeConfigs`.
`useBarCodeDetectorIfSupported` was tested as an experimental configuration for
a long time and has proven to be very efficient and well supported. It has been
tested in [ScanApp](https://scanapp.org) for quiet some time.

Considering this experimental API is not well documented, it makes it hard for
folks to discover it. By graduating this configuration to `Html5QrcodeConfigs` I
hope to make it more discoverable.

In this version the `ExperimentalFeaturesConfig#useBarCodeDetectorIfSupported`
has been marked deprecated but not removed due to backwards compatibility
reasons. Users can set either of them but `Html5QrcodeConfigs` one will take
precedence if set.

Once further support is added to browsers, this can be set as true by default.

##### TODOS
-    [ ] Update documentation on readme.
-    [ ] Update documentation on [qrcode.minhazav.dev](https://qrcode.minhazav.dev).
-    [ ] Publish article around this.

README.md

@@ -437,6 +437,21 @@ interface Html5QrcodeConfigs {
    * Array of formats to support of type {@type Html5QrcodeSupportedFormats}.
    */
   formatsToSupport: Array<Html5QrcodeSupportedFormats> | undefined;
+
+
+  /**
+   * {@class BarcodeDetector} is being implemented by browsers at the moment.
+   * It has very limited browser support but as it gets available it could
+   * enable faster native code scanning experience.
+   * 
+   * Set this flag to true, to enable using {@class BarcodeDetector} if
+   * supported. This is false by default.
+   * 
+   * Documentations:
+   *  - https://developer.mozilla.org/en-US/docs/Web/API/BarcodeDetector
+   *  - https://web.dev/shape-detection/#barcodedetector
+   */
+  useBarCodeDetectorIfSupported?: boolean | undefined;
 }
 
 /** Configuration for creating {@class Html5Qrcode}. */

changelog.md

@@ -1,5 +1,57 @@
 ### Version 2.2.7
-TBD
+
+#### Add support for custom CSS
+Developer / User Story: As a developer I can write custom CSS for `Html5QrcodeScanner`.
+
+Feature request: [Issue#389](https://github.com/mebjas/html5-qrcode/issues/389)
+
+List of CSS class and IDs added.
+
+1. All key elements will have a common CSS class `html5-qrcode-element`. This way developers can customise element by element. For example:
+
+```css
+button.html5-qrcode-element {
+    color: 'red' !important,
+    border: '1px solid red' !important
+}
+```
+
+Key elements are:
+-    Request camera permission button.
+-    "Scan and image file" vs "Scan using camera directly" link.
+-    "File selection" input ('file')
+-    Start or Stop camera button.
+-    Camera selection Select element
+-    Torch button
+
+2. key elements will have specific IDs defined in `src/ui/scanner/base.ts`. This can be used to customise per elements.
+
+
+##### TODOs
+-   [ ] Document in a blog post
+-   [ ] Add pointer in qrcode.minhazav.dev
+-   [ ] Add pointer in Readme
+
+#### Graduate `useBarCodeDetectorIfSupported` to `Html5QrcodeConfigs`.
+`useBarCodeDetectorIfSupported` was tested as an experimental configuration for
+a long time and has proven to be very efficient and well supported. It has been
+tested in [ScanApp](https://scanapp.org) for quiet some time.
+
+Considering this experimental API is not well documented, it makes it hard for
+folks to discover it. By graduating this configuration to `Html5QrcodeConfigs` I
+hope to make it more discoverable.
+
+In this version the `ExperimentalFeaturesConfig#useBarCodeDetectorIfSupported`
+has been marked deprecated but not removed due to backwards compatibility
+reasons. Users can set either of them but `Html5QrcodeConfigs` one will take
+precedence if set.
+
+Once further support is added to browsers, this can be set as true by default.
+
+##### TODOS
+-    [ ] Update documentation on readme.
+-    [ ] Update documentation on [qrcode.minhazav.dev](https://qrcode.minhazav.dev).
+-    [ ] Publish article around this.
 
 ### Version 2.2.5 & Version 2.2.6
 

experimental.md

@@ -6,15 +6,16 @@ library. In future, based on the support level and compatibility, some of
 these features will get upgraded to general feature list.
 
 ## Using experimental native BarcodeDetector API
+> **Note** This config has now been graduated to `Html5QrcodeConfigs` and
+deprecated from experimental config.
+
 Turning on this flag allows using native [BarcodeDetector](https://developer.mozilla.org/en-US/docs/Web/API/BarcodeDetector)
 api now being introduced in web browsers for code scanning instead of `ZXing`
 library we use officially.
 
 ### How to turn this on
-It can be turned on using new config called `useBarCodeDetectorIfSupported`
-added to `experimentalFeatures` config group. It's off (`value = false`) by
-default. If set to on (`value = true`) and the `BarcodeDetector` is supported
-by the browser, it'll be used for scanning all the kind of 1d and 2d codes.
+Setting `useBarCodeDetectorIfSupported` to `true` in `Html5QrcodeConfigs` will
+enable this option.
 
 #### Html5Qrcode class
 
@@ -24,10 +25,7 @@ function onScanSuccess(decodedText, decodedResult) {
 }
 
 let html5qrcode = new Html5Qrcode("reader", {
-    // Use this flag to turn on the feature.
-    experimentalFeatures: {
-        useBarCodeDetectorIfSupported: false
-    }
+    useBarCodeDetectorIfSupported: false
 });
 
 const scanConfig = { fps: 10, qrbox: 250 };
@@ -47,10 +45,7 @@ let html5QrcodeScanner = new Html5QrcodeScanner(
     { 
         fps: 10,
         qrbox: 250,
-        // Use this flag to turn on the feature.
-        experimentalFeatures: {
-            useBarCodeDetectorIfSupported: false
-        }
+        useBarCodeDetectorIfSupported: false
     });
 html5QrcodeScanner.render(onScanSuccess);
 ```

package.json

@@ -9,12 +9,11 @@
   "unpkg": "./html5-qrcode.min.js",
   "scripts": {
     "build-windows": "npm run build:es2015 && npm run build:esm && npm run build:esnext && npm run build:cjs && npm run build:umd_windows && npm run build:typing && npm run build:copy_windows",
-    "test": "npm run-script test:build && npm run-script test:run && npm run-script test:clean",
-    "test_windows": "npm run-script test:build && npm run-script test:run && npm run-script test:clean_windows",
+    "test": "npm run-script test:build && npm run-script test:run",
+    "test_windows": "npm run-script test:build && npm run-script test:run_windows",
     "test:build": "tsc --build tsconfig.test.json",
-    "test:clean": "rm -Rf ./output",
-    "test:clean_windows": "rmdir /s /q .\\output",
-    "test:run": "mocha -r tsconfig-paths/register --timeout 200000 output/tests/**/*.test.js",
+    "test:run_windows": ".\\scripts\\test-run.bat",
+    "test:run": "./scripts/test-run.sh",
     "lint-md": "remark .",
     "clean": "rm -Rf ./lib/* ./build/* ./meta/bundlesize/* ./meta/coverage/* ./.rpt2_cache  ./dist/* ./src/*.d.ts",
     "prebuild": "npm run clean",
@@ -61,6 +60,8 @@
     "babel-minify": "^0.5.1",
     "chai": "^4.3.4",
     "expose-loader": "^2.0.0",
+    "jsdom": "20.0.2",
+    "jsdom-global": "3.0.2",
     "mocha": "^9.1.3",
     "mocha-lcov-reporter": "^1.3.0",
     "promise-polyfill": "^8.1.3",

scripts/test-run.bat

@@ -0,0 +1,10 @@
+@ECHO OFF
+:: This is a script for running tests on Windows OS.
+
+ECHO Initiating test script.
+
+mocha -r tsconfig-paths/register --timeout 200000 output/tests/**/*.test.js output/tests/tests/ui/scanner/*.test.js
+
+ECHO Cleaning up test artifacts
+
+rmdir /s /q .\\output

scripts/test-run.sh

@@ -0,0 +1,13 @@
+#!/bin/bash
+## Build Script
+
+echo 'Initiating test script.'
+
+mocha -r tsconfig-paths/register \
+    -r jsdom-global/register \
+    --timeout 200000 \
+    output/tests/**/*.test.js \
+    output/tests/tests/ui/scanner/*.test.js
+
+echo 'Cleaning up test artifacts'
+rm -Rf ./output

src/code-decoder.ts

@@ -17,7 +17,6 @@ import {
 
 import { ZXingHtml5QrcodeDecoder } from "./zxing-html5-qrcode-decoder";
 import { BarcodeDetectorDelegate } from "./native-bar-code-detector";
-import { ExperimentalFeaturesConfig } from "./experimental-features";
 
 /**
  * Shim layer for {@interface QrcodeDecoder}.
@@ -35,14 +34,14 @@ export class Html5QrcodeShim implements QrcodeDecoderAsync {
 
     public constructor(
         requestedFormats: Array<Html5QrcodeSupportedFormats>,
+        useBarCodeDetectorIfSupported: boolean,
         verbose: boolean,
-        logger: Logger,
-        experimentalFeatureConfig: ExperimentalFeaturesConfig) {
+        logger: Logger) {
         this.verbose = verbose;
 
         // Use BarcodeDetector library if enabled by config and is supported.
-        if (experimentalFeatureConfig.useBarCodeDetectorIfSupported === true
-            && BarcodeDetectorDelegate.isSupported()) {
+        if (useBarCodeDetectorIfSupported
+                && BarcodeDetectorDelegate.isSupported()) {
             this.decoder = new BarcodeDetectorDelegate(
                 requestedFormats, verbose, logger);
         } else {
@@ -51,16 +50,18 @@ export class Html5QrcodeShim implements QrcodeDecoderAsync {
         }
     }
 
-    decodeAsync(canvas: HTMLCanvasElement): Promise<QrcodeResult> {
+    async decodeAsync(canvas: HTMLCanvasElement): Promise<QrcodeResult> {
         let start = performance.now();
-        return this.decoder.decodeAsync(canvas).finally(() => {
+        try {
+            return await this.decoder.decodeAsync(canvas);
+        } finally {
             if (this.verbose) {
                 let executionTime = performance.now() - start;
                 this.executionResults.push(executionTime);
                 this.executions++;
                 this.possiblyFlushPerformanceReport();
             }
-        });
+        }
     }
 
     // Dumps mean decoding latency to console for last

src/experimental-features.ts

@@ -31,32 +31,14 @@ export interface ExperimentalFeaturesConfig {
      * Set this flag to true, to enable using {@class BarcodeDetector} if
      * supported. This is false by default.
      * 
+     * @deprecated This configuration has graduated to
+     * {@code Html5QrcodeCameraScanConfig} you can set it there directly. All
+     * documentation and future improvements shall be added to that one. This
+     * config will still work for backwards compatibility.
+     * 
      * Documentations:
      *  - https://developer.mozilla.org/en-US/docs/Web/API/BarcodeDetector
      *  - https://web.dev/shape-detection/#barcodedetector
      */
     useBarCodeDetectorIfSupported?: boolean | undefined;
 }
-
-/** Factory for {@interface ExperimentalFeaturesConfig}. */
-export class ExperimentalFeaturesConfigFactory {
-
-    /**
-     * Creates fully filled experimental config.
-    */
-    public static createExperimentalFeaturesConfig(
-        config?: ExperimentalFeaturesConfig | undefined)
-        : ExperimentalFeaturesConfig {
-        if (!config) {
-            return {
-                useBarCodeDetectorIfSupported: false
-            };
-        }
-
-        if (config.useBarCodeDetectorIfSupported !== true) {
-            config.useBarCodeDetectorIfSupported = false;
-        }
-
-        return config;
-    }
-}