feat: demo for v2.0.0

Author: felixindrawan

.github/workflows/main.yml

@@ -1,5 +1,3 @@
-# This is a basic workflow to help you get started with Actions
-
 name: CI
 
 # Controls when the workflow will run
@@ -20,19 +18,30 @@ jobs:
 
     # Steps represent a sequence of tasks that will be executed as part of the job
     steps:
-         # Runs a set of commands using the runners shell
       - name: Get Source
         run: |
           cd /home/ubuntu
           [ -d mrz-scanner-javascript ] && rm -rf mrz-scanner-javascript
           git clone --depth 1 -b demo https://github.com/Dynamsoft/mrz-scanner-javascript.git 
+
+      - name: Prepare Files
+        run: |
+          # Create a temporary directory for the files to be uploaded
+          mkdir -p /home/ubuntu/mrz-scanner-javascript/deploy
           
+          # Copy the dist folder
+          cp -r /home/ubuntu/mrz-scanner-javascript/dist /home/ubuntu/mrz-scanner-javascript/deploy
+          
+          # Copy demo and hello world. On demo branch, be sure to update the pathing for the demo
+          cp -r /home/ubuntu/mrz-scanner-javascript/samples/demo/* /home/ubuntu/mrz-scanner-javascript/deploy
+          cp -r /home/ubuntu/mrz-scanner-javascript/samples/hello-world.html /home/ubuntu/mrz-scanner-javascript/deploy
+
       - name: Sync files
         uses: SamKirkland/[email protected]
         with:
           server: ${{ secrets.FTP_DEMO_SERVER }}
           username: ${{ secrets.FTP_DEMO_USERNAME }}
           password: ${{ secrets.FTP_DEMO_PASSWORD }}
           port: 21 
-          local-dir: /home/ubuntu/mrz-scanner-javascript/
-          server-dir: /Demo.dynamsoft.com/solutions/mrz-scanner/
+          local-dir: /home/ubuntu/mrz-scanner-javascript/deploy/
+          server-dir: /Demo.dynamsoft.com/mrz-scanner/

.github/workflows/preview.yml

@@ -0,0 +1,34 @@
+name: Publish Package
+
+on:
+  release:
+    types: [created]
+  # Optionally enable manual workflow runs
+  workflow_dispatch:
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: npm ci
+
+      # - name: Run tests
+      #   run: npm test
+        
+      - name: Build package
+        run: npm run build
+        
+      - name: Publish to npm
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_PAT }}

.github/workflows/publish.yml

@@ -0,0 +1 @@
+node_modules

.gitignore

@@ -0,0 +1,2 @@
+@scannerproxy:registry=https://npm.scannerproxy.com:802/
+@dynamsoft:registry=https://npm.scannerproxy.com:802/

.npmrc

@@ -0,0 +1,8 @@
+License Notice
+
+The source code of Dynamsoft MRZ Scanner provided here is released under the Apache 2.0 License: http://www.apache.org/licenses/LICENSE-2.0. 
+Dynamsoft Label Recognizer (DLR), Dynamsoft Code Parser (DCP) and Dynamsoft Camera Enhancer (DCE) SDKs, which are dependencies of Dynamsoft MRZ Scanner, are licensed under a commercial license: https://www.dynamsoft.com/company/license-agreement/.
+ 
+This file is distributed on an "AS IS" basis, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ 
+Copyright © 2003–2025 Dynamsoft. All Rights Reserved.

.vscode/settings.json

@@ -1,105 +1,149 @@
-# Dynamsoft MRZ Scanner for Web
+# User Guide for the MRZ Scanner for Web
 
-The [Dynamsoft MRZ Scanner](https://www.dynamsoft.com/use-cases/mrz-scanner/?utm_source=mrzdemo&package=js) enables camera to scan the MRZ code of ID-cards and passports. It will extract all data like first name, last name, document number, nationality, date of birth, expiration date and more from the MRZ string, and converts the encoded string into human-readable fields.
+This user guide will walk you through the [Hello World](https://github.com/Dynamsoft/mrz-scanner-javascript/blob/main/README.md) sample app. When creating your own application, we recommend using this sample as a reference.
 
-## Web demo
+To learn about what an MRZ is, along with the makeup and system requirements of this solution, please visit the [MRZ Introduction](https://www.dynamsoft.com/mrz-scanner/docs/web/introduction/index.html) page on the Dynamsoft website.
 
-You can scan the QR code below with your phone to visit our online demo, or use a desktop browser to access [https://demo.dynamsoft.com/solutions/mrz-scanner/index.html](https://demo.dynamsoft.com/solutions/mrz-scanner/index.html) (no personal data will be uploaded).
+## License
 
-<img src="https://www.dynamsoft.com/webres/wwwroot/images/usecases/mrz-scanner/mrz-scanner-demo-qr-code.svg" alt="mrz-scanner-demo-qr-code" width="200"/>
+### Trial License
 
-## Run this Solution
+When you are getting started with the MRZ Scanner solution, we recommend getting your own 30-day trial license through the [customer portal](https://www.dynamsoft.com/customer/license/trialLicense/?product=mrz&utm_source=guide&package=js). The trial license can be renewed via the same customer portal twice, each time for another 15 days, giving you a total of 60 days to develop your own application using the solution. If more time is needed for a full evaluation, please contact the [Dynamsoft Support Team](https://www.dynamsoft.com/company/contact/).
 
-1. Clone the repository to a working directory or download the code as a ZIP file:
+> Note:
+>
+> Please note that the **MRZ Scanner** license contains a license for the **Dynamsoft Label Recognizer**, **Dynamsoft Code Parser**, and the **Dynamsoft Camera Enhancer** as those are the three functional products that are central to the operation of the MRZ Scanner.
+
+### Full License
+
+If you are fully satisfied with the solution and would like to move forward with a full license, please contact the [Dynamsoft Sales Team](https://www.dynamsoft.com/company/contact/).
+
+## Quick Start - Including the SDK and creating Hello World
+
+As mentioned previously, the purpose of this guide is to help you implement a Hello World application using the MRZ Scanner solution. To showcase this, we will be using vanilla JS. You can find the full code in the [Github repository](https://github.com/Dynamsoft/mrz-scanner-javascript/blob/main/README.md).
+
+The first step before you venture into writing the code is to include the SDK in your application. The simplest way to include the SDK would be to use the precompiled script - but you can also build it from source yourself.
+
+### Building the Library from Source
+
+In this guide, we will show the developer how to build the scanner themselves from the source files. The advantage of doing this is that it allows the developer to do some deep customization of the scanner if they are familiar with using the foundational products **Dynamsoft Label Recognizer**, **Dynamsoft Code Parser**, and the **Dynamsoft Camera Enhancer**.
+
+Please note that we also offer a pre-compiled script reference to make the inclusion of the library even easier. To learn how to use that, please visit the full User Guide for the MRZ Scanner.
+
+This method requires retrieving the **MRZ Scanner for Web** source files from its [Github repository](https://github.com/Dynamsoft/mrz-scanner-javascript), compiles them into a distributable package, and then runs a *ready-made* Hello World sample page that is already included in the repo.
+
+Please follow these steps in order to build from the source:
+
+1. Download the **MRZ Scanner for Web** source files from [Github](https://github.com/Dynamsoft/mrz-scanner-javascript) as a compressed folder ("Download ZIP" option).
+
+2. Extract the contents of the compressed folder.
+
+3. Open the *Hello World* sample included with the source files located at `samples/hello-world.html`
+
+4. Search for 'YOUR_LICENSE_KEY_HERE' and replace that with your own license key, whether it is trial or full.
+
+5. Install project dependencies - in the terminal, navigate to the project root directory and run the following:
+    ```bash
+    npm install
+    ```
+
+6. Build the project - once the dependencies are installed, build the project by running:
+    ```bash
+    npm run build
+    ```
 
-```sh
-git clone https://github.com/Dynamsoft/mrz-scanner-javascript
+7. Serve the project via localhost:
+    ```bash
+    npm run serve
+    ```
+Once the server is running, open the application in a browser using the address provided in the terminal output after running `npm run serve`.
+
+## Breaking down Hello World
+
+Let's now go through the code of the Hello World sample and understand the purpose of each section and how they all work together to bring the app to life.
+
+### Step 1: Setting up the HTML and Including the MRZ Scanner
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Dynamsoft MRZ Scanner - Hello World</title>
+    <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/mrz-scanner.bundle.js"></script>
+  </head>
+
+  <body>
+    <h1 style="font-size: large">Dynamsoft MRZ Scanner</h1>
+  </body>
+
+</html>
 ```
 
-2. Deploy the files to a directory hosted on an HTTPS server.
+The first step in setting up the HTML in a Hello World implementation is to include the SDK. The ways to include the SDK has already been addressed in the [Quick Start](#quick-start---including-the-sdk-and-creating-hello-world) section, so please refer to that if you have not already. In this example, we are including the MRZ Scanner via the precompiled script as that is the easiest way to get started.
 
-3. Open the "index.html" file in your browser.
+Since this is a Hello World implementation, the HTML body will be kept quite simple. Since the MRZ Scanner comes with a **Ready-to-Use UI**, it is not necessary to place any `<div>` placeholder elements or anything like. Once the scanner is launched, the **Ready-to-Use UI** will come up and occupy the page. 
 
-> Basic Requirements
->
->  * Internet connection  
->  * [A supported browser](#system-requirements)
->  * An accessible Camera
-
------
-
-## Request a Trial License
-
-The key "DLS2eyJvcmdhbml6YXRpb25JRCI6IjIwMDAwMSJ9" used in this solution (found in the js/init.js file) is a test license valid for 24 hours for any newly authorized browser. If you wish to test the SDK further, you can request a 30-day free trial license through the <a href="https://www.dynamsoft.com/customer/license/trialLicense?product=mrz&utm_source=samples&package=js" target="_blank">Request a Trial License</a> link. For more information, see [Specify the License](https://www.dynamsoft.com/capture-vision/docs/web/programming/javascript/user-guide/mrz-scanner.html#specify-the-license) or contact [[email protected]](mailto:[email protected]).
-
-## Project Structure
-
-```text
-MRZ Scanner
-├── assets
-│   ├── ...
-│   ├── ...
-│   └── ...
-├── css
-│   └── index.css
-├── font
-│   ├── ...
-│   ├── ...
-│   └── ...
-├── js
-│   ├── const.js
-│   ├── index.js
-│   ├── init.js
-│   └── util.js
-├── index.html
-└── template.json
+<!-- The main DOM element that is required in the `<body>` is a `<div>` element where the MRZ result (or lack thereof) and the original image of the MRZ document will be displayed once the user clicks *Done* in the result view. Feel free to customize the styling of the `<div>` element to your liking. -->
+
+Now let's move to the main script that will define the operation of the 
+
+### Step 2: Initialize the MRZ Scanner
+
+```js
+// Initialize the Dynamsoft MRZ Scanner
+const mrzscanner = new Dynamsoft.MRZScanner({
+  license: "YOUR_LICENSE_KEY_HERE",
+});
+```
+
+Above you will see the **simplest** way that you can initialize the MRZ Scanner. The one that is **absolutely required** in this setup is the **license**. Without a valid license, the MRZ Scanner view will not launch and you will be met with an error message explaining that the license key is invalid or has expired. To learn how to get your own license, please refer to the [License](#license) section of the guide.
+
+### Step 3: Launching the MRZ Scanner
+
+```js
+(async () => {
+  // Launch the scanner and wait for the result
+  const result = await mrzscanner.launch({});
+  console.log(result); 
+})();
 ```
 
- * `/assets` : This directory contains all the static files such as images, icons, etc. that are used in the project.
- * `/css` : This directory contains the CSS file(s) used for styling the project.
- * `/font` : This directory contains the font files used in the project.
- * `/js` : This directory contains all the JavaScript files used in the project.
-   * `const.js` : This file contains definitions of certain constants or variables used across the project.
-   * `index.js`: This is the main JavaScript file where the core logic of the project is implemented.
-   * `init.js` : This file is used for initialization purposes, such as initializing license, load resources, etc.
-   * `util.js` : This file contains utility functions that are used across the project.
- * `index.html` : This is the main HTML file that represents the homepage of the project.
- * `template.json` : This file contains predefined templates used in the project.
+Now that the MRZ Scanner has been initialized and configured, it is ready to be launched! Once the MRZ Scanner is launched, the user will see the main **MRZScannerView**. Once a MRZ is scanned (via video or static image), the MRZ Scanner then switches to the **MRZResultView** to display a cropped image of the MRZ document as well as the parsed fields of the MRZ text. Let's break down these two views:
+
+#### MRZScannerView
+
+Here is a quick breakdown of the UI elements that make up the main view of the MRZ Scanner
+
+1. **Camera View**: The majority of the space of the MRZScannerView is occupied by the camera view to give the user a complete picture of what is being seen by the camera.
 
-## System Requirements
+2. **Scan Guide Frame**: By default, at the centre of the camera view you will find a frame that helps guide the user on where to place the MRZ document to get a fast and accurate result. Please note that if scan guide frame is shown, then anything outside of the frame will not be captured. This frame can be hidden via the **MRZScannerViewConfig** interface.
 
-This project requires the following features to work:
+3. **Format Selector**: Below the scan guide frame, you will also notice a selector box that allows the user to choose which formats the MRZ Scanner should recognize. The formats that show up in the format selector are configurable via the **MRZScannerConfig** interface, while the visibility of the format selector itself is configurable via the **MRZScannerViewConfig** interface. To learn about MRZ formats, please refer to the [Introduction](https://www.dynamsoft.com/mrz-scanner/docs/web/introduction/index.html#supported-mrz-formats) page.
 
-- Secure context (HTTPS deployment)
+4. **Resolution/Camera Select Dropdown**: This dropdown allows the user to switch cameras (should they have more than one available on the device), or select a different resolution for the camera that is currently selected.
 
-  When deploying your application / website for production, make sure to serve it via a secure HTTPS connection. This is required for two reasons
-  
-  - Access to the camera video stream is only granted in a security context. Most browsers impose this restriction.
-  > Some browsers like Chrome may grant the access for `http://127.0.0.1` and `http://localhost` or even for pages opened directly from the local disk (`file:///...`). This can be helpful for temporary development and test.
-  
-  - Dynamsoft License requires a secure context to work.
+5. **Load Image Button**: When this button is clicked, the user can select a MRZ document image from the device's local storage to be recognized.
 
-- `WebAssembly`, `Blob`, `URL`/`createObjectURL`, `Web Workers`
+6. **Sound Button**: By toggling this on, the MRZ Scanner will play a *beep* sound to signal that the MRZ has been successfully recognized.
 
-  The above four features are required for the SDK to work.
+7. **Flash Button**: This button is responsible for toggling the flash of the camera should it have one. If the device doesn't have the flash feature or if the browser being used doesn't support flash, this flash icon will not show up.
 
-- `MediaDevices`/`getUserMedia`
+8. **Close Scanner Button**: Clicking this button will close the MRZ Scanner and take the user back to the landing page.
 
-  This API is required for in-browser video streaming.
+#### MRZResultView
 
-- `getSettings`
+Here is a quick breakdown of the UI elements that make up the result view
 
-  This API inspects the video input which is a `MediaStreamTrack` object about its constrainable properties.
+1. **Original Image**: A cropped image of the MRZ document that was just scanned will be displayed at the top by default.
 
-The following table is a list of supported browsers based on the above requirements:
+2. **Parsed Results**: The parsed results, along with their corresponding field names, are displayed in a form view underneath the original image. In addition to displaying these parsed results, the MRZ Scanner allows the user to edit any of the fields if they find that any of the parsed info is incorrect after cross referencing it with the info on the MRZ document.
 
-  | Browser Name |     Version      |
-  | :----------: | :--------------: |
-  |    Chrome    | v78+<sup>1</sup> |
-  |   Firefox    | v68+<sup>1</sup> |
-  |     Edge     |       v79+       |
-  |    Safari    |       v14+       |
+3. **Re-take Button**: Clicking this button allows the user to go back to the **MRZScannerView** to scan another MRZ document.
 
-  <sup>1</sup> devices running iOS needs to be on iOS 14.3+ for camera video streaming to work in Chrome, Firefox or other Apps using webviews.
+4. **Done Button**: Clicking this button basically closes the scanner and destroys the **MRZScanner** instance. At that point, the application will go back to the landing page, but the developer can dictate the action to take once this button is clicked. These actions can include allowing the user to perform some extra actions with the MRZ result, or navigating to another page, or really anything that the developer would like to do once the scanning operation is done.
 
-Apart from the browsers, the operating systems may impose some limitations of their own that could restrict the use of the SDK. Browser compatibility ultimately depends on whether the browser on that particular operating system supports the features listed above.
+  >Note:
+  >
+  > In the Hello World sample, no action is taken once the Done button is clicked. The scanner closes and the user is met with an empty page. In order to open the scanner again, the user must refresh the page. However, this action can be changed according to the developer's wishes as indicated above.