npm package: @quandis/qbo4.ui.web
Description: The `qbo4.UI.Web` project contains the web components to add sugar to any UI, including qbo3 and qbo4 UI.
Author: Quandis, Inc.
Latest version: 4.0.5

﻿# Overview

The `qbo4.UI.Web` project contains the web components to add sugar to any UI, including qbo3 and qbo4 UI.

This replace's the qbo3/Mootools `Behaviors` concept. Web components are reusable in any modern framework.

## Background Reading

- [HTML Accessiblilty](https://developer.mozilla.org/en-US/docs/Learn/Accessibility/HTML)
- [Accessible Rich Internet Applications (ARIA)](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA)
- [Web components](https://developer.mozilla.org/en-US/docs/Web/Web_Components) ([examples](https://github.com/mdn/web-components-examples) on Github)
- [Form validation](https://www.w3.org/TR/2009/WD-html5-20090825/forms.html#attr-input-pattern)
- [Javascript Modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules)
- [TSDoc](https://tsdoc.org/) for Typescript comments

## Custom Web components

There is a [debate](https://github.com/WebKit/standards-positions/issues/97) about customizing standard html elements.
Apple has refused to support customizing existing elements, and Quandis agrees with this approach.

This means that you can do:

```html
<qbo-select></qbo-select>
```

but you may not do:

```html
<select is="qbo-select"></select>
```

Components that customize `<select>` should do this:

```javascript
@customElement('qbo-select')
export class QboSelect extends QboFetch
{
    ...
    render() {
        ...
        return html`
            <select>
                ${this.options.map(option => html`...`)}
            </select>`;
    }
}
```

# Project Structure

While this project is a `Microsoft.NET.Sdk.Web` project, it does not include any meaningful server-side code.

## Technology Components

| Technology | Config File | Purpose |
|-|-|-|
|Typescript|`tsconfig.json`|Type safe version of Javascript. `tsc --build` is used to compile (transpile) .ts files to .js file.|
|Node package manager (npm)|`package.json`|Javascript equivalent to Nuget package manager.|
|Webpack|`webpack.config.cjs`|Javascript equivalent to MSBuild. Webpack products a single `.js` and `.css` file for use by other projects.|
|Lit|--|Google's web component library. `LitElement` is the base class for most qbo4 web components.|
|web-test-runner|--|A test runner that runs tests in browser(s)' javascript/DOM engine.|

## Folder Structure

|Folder|Purpose|
|-|-|
|`wwwroot`|Contains .html pages to enable testing of web components.|
|`wwwroot/scripts`|Contains `main.js` and `main.css` files to be linked to by `.html` pages.|
|`package`|Folder containing the files to be packaged by `npm` and pushed to an artifact feed. This is specified in `package.json`|
|`src`|Source `.ts` files that comprise qbo4.UI.Web's components and libaries.|
|`tests`|Test `*.test.ts` files for testing components and libraries.|

## Typescript (tsconfig.json)

This project includes the `Microsoft.Typecript.MSBuild` Nuget package, which includes the `tsc` compiler.
When the project is built, MSBuild automatically calls `tsc` to compile `.ts` files to `.js` files.

It is convention to place `.ts` files in a `src` folder, and `.test.ts` files in a `tests` folder.
However, when we publish the package, we want to include only the `src` files. 
To address this issue, we have three `tsconfig.json` files:

- `tsconfig.json`: in the root folder
- `src\tsconfig.json`: in the `src` folder, and instructs `tsc` where to output the files (`package` folder)
- `tests\tsconfig.json`: in the `tests` folder, and instructs `tsc` where to output the files (`tests` (same) folder)

The significant takeaway for our use of `tsconfig.json` is that we target `ESNext` for our output, 
meaning that we produce javascript files that use the latest `ECMA` standards, including `import` and `export` of `modules`.
This means that these libraries will only work with modern browsers, which comprise 94+% of all browsers currently in use.
**IE is right out**.

## Node (package.json)

The `package.json` is used instruct `npm` how to behave. While it has many options, 
the most relevent are the defined `scripts` that allow you to execute node command with a shortcut:

```console
// execute the tests using web-test-runner
npm run test
// package the files for deployment
npm run pack
```

The following `npm` commands are not scripts, but you will use frequently:

```console
// install all packages listed in package.json
npm install
// install a package and add it to package.json
npm install <package> --save
// install a package and add it to package.json as a dev dependency
npm install <package> --save-dev
// run any package installed globally
npx <package>
```

## Webpack (webpack.config.cjs)

Typescript projects must be transpiled into javascript, and will leverage modules via `import` and `export`.
Convention dictates that:

```typescript
import `lit`;   // This expects lit to be defined in the folder node_modules\lit
import `./qbo`  // This expects qbo to be defined in the current folder
```

Webpack's job is to look a one (or more) 'entry' javascript files, build a dependency graph of all the imports actually in use,
and create a single Javascript file containing all referenced code (a dependency graph).
The entry point for qbo modules is `qbo.js`.

Webpack uses the following configuration files:

- `webpack.config.cjs`: common configuration for both development and production, produces output in `package\dist`
- `webpack.config.dev.cjs`: does not minify, does copies `package\dist` to `wwwroot\scripts` for testing (merges with `webpack.config.cjs`)
- `webpack.config.prod.cjs`: minifies javascript and css (merges with `webpack.config.cjs`)

> Webpack looks for a `webpack.config.js` first, but expects the json to be `CommonJs`, 
instead of a `module` as specified in `package.json` - as needed to tell node our modules use `import` instead of `require`. 
Naming the file with `.cjs` tells `node` that file is `CommonJS`, regardless of what `package.json's` `target` says.

The `qbo.UI.Web.csproj` includes a build target for `webpack`, so that every time the project is built, new `qbo4.js` and `qbo4.css` are created.

```xml
<Target Name="NpmRunPack" AfterTargets="Build">
	<Exec Command="npm run packprod" />
</Target>
```

paired with the `pack` script defined in `pacakge.json`:

```json
{ ...
  "scripts": {
    "packprod": "webpack --config webpack.prod.cjs --no-color"
  },
  ...
}
```

# HTML Coding Guidelines

When creating web pages, features should be implemented with:

- HTML, first, if possible,
- CSS, second, if possible,
- Javascript, otherwise

## Web Components

When designing reusable browser-based components, [web components](https://developer.mozilla.org/en-US/docs/Web/Web_Components) should be used. 
Web components use Javascript, HTML and CSS to define new tags ~~or extend existing tags~~ , and scope all functionality to a [shadow DOM](https://developers.google.com/web/fundamentals/web-components/shadowdom). 
This allows a given component to use javascript without worrying that it will interfere with other components.

The goal of creating web components is to strive to ensure QBO components can be **mixed into a variety of frameworks**, 
including Angular and React.

In most cases, Quandis recommends use of Google's [Lit library](https://lit.dev/) to speed the development of pure web components.

A sampling custom components includes:

|Component|Purpose|
|-|-|
|`qbo-fetch`|Acts as a base class for elements that need to do API calls (via Javascript's `fetch` statement).|
|`qbo-select`|Renders a `<select>` element with options from the results of an API call.|
|`qbo-popup`|Renders a popup, with content optionally coming from an API call (via `qbo-fetch`).|
|`qbo-logging`|Provides UI around handling errors.|

## Form validation

HTML5 supports [extensive form validation](https://www.w3.org/TR/2009/WD-html5-20090825/forms.html#attr-input-pattern); use it!  Examples:

```html
<input name="zipcode" type="text" pattern="\d{5}(-\d{4})?"/>
<input name="creditcard" type="text" pattern="[0-9]{13,16}"/>
```

# Typescrpit / Javascript Coding Guidelines

- Use the [MDN Style Guide](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide) (which Microsoft also uses)
- Use `const` and `let` [instead of](https://stackoverflow.com/questions/40070631/v8-javascript-performance-implications-of-const-let-and-var/40070682#40070682) `var`
- Use camelcase for variables and function names

``` javascript
const myLongVariableName = "foo";
```

- Use template literals for code readability

``` javascript
const firstName = "Bob";
const lastName = "Jones";
const result = `Hello ${firstName}, ${lastName}`;
```

- Omit the protocol from links to other sites, if possible, to support `http` and `https`

``` javascript
<style src="//maps.googleapis.com/maps/api/js"/>
```

## Namespacing

Use [`modules`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) via the `export` and `import` features to build javascript libraries.
Related classes and functions should be imported as a module. For example, qbo4-related modules:

- src
  - qbo.ts
  - qbo-fetch.ts
  - qbo-json.ts
  - qbo-select.ts

where `qbo.js` [aggregates](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules#aggregating_modules) related classes an functions:

```javascript
export * from './qbo-fetch.js'
export * from './qbo-json.js'
export * from './qbo-select.js'
```
and the website's root includes a `qbo4.js` created by `webpack`:

```javascript
import * as qbo4 from './qbo4.js';
```
To use qbo4 from a browser debugger window:

```javascript
const qbo = await import('/scirpts/qbo4.js'); 
// now you can access qbo.* functions
```

## Error handling in the browser

- Assume our code will fail
- Log errors to the server
- Our code, not the browser, should handle errors
- Identify errors that might occur (arguments, network)
  - use [custom errors](https://medium.com/@iaincollins/error-handling-in-javascript-a6172ccdf9af)
- `throw` at a low level, `catch` at a high level
- Distinguish between fatal and non-fatal
- Global debug mode: help the developer figure out the problem

> Credit [Nicholas Zakas](https://www.slideshare.net/nzakas/enterprise-javascript-error-handling-presentation/48-E_tcetera_M_y_blog)

## Comments

Quandis shall follow the [TSDoc](https://tsdoc.org/) to work with Visual Studio Intellisense.

``` javascript
/* @description These are sample comments
 * @param foo {string} Foo is used to ...
 * @param bar {array} Each item in bar is used to ...
 * @returns {object} An object representing ...
*/
qbo4.someMethod = function (foo, bar) {...}
```

## Third Party Libraries

- Use native Javascript methods ahead of third party library methods
  - e.g. `document.getElementById(id)` is preferrable to jQuery's `$('#id')[0]`.
  - e.g. `{array}.forEach(...)` is preferable to Mootool's `{array}.each(...)`

|Library|qbo3|qbo4|Notes|
|-|-|-|-|
|[Mootools](https://mootools.net/)|yes|no|Deprecated; not under development.|
|[jQuery](https://jquery.com/)|yes|yes|For sugar **not supported by the DOM**. <br/>Use [noconflict](https://api.jquery.com/jQuery.noConflict/); $ shall be used for Mootools in qbo3.|
|[Google Visualizations](https://developers.google.com/chart/interactive/docs/gallery)|yes|yes|For charting.|
|[Bootstrap](https://getbootstrap.com/)|yes|yes|For styling and layout.|
|[Dropzone](https://www.dropzonejs.com/)|yes|yes|For file upload controls.|
|[Modernizr](https://modernizr.com/)|yes|yes|For older browsers (consumer-facing sites).|

## Feature adoption

|Feature|qbo3|qbo4|Notes|
|-|-|-|-|
|Promises|yes|yes||
|async/await|yes|yes||

> Use new features [only if available](https://caniuse.com/) to 90% or more of global users.


# References

- [Web components](https://developers.google.com/web/fundamentals/web-components/customelements) *Read this!*
- [Composing events with the shadow DOM](https://stackoverflow.com/questions/43061417/how-to-listen-for-custom-events-defined-web-component)
- [Webpack](https://webpack.js.org/)
- [TypeScript with ASP.NET core](https://www.typescriptlang.org/docs/handbook/asp-net-core.html)


# Typescript in a Microsoft Stack

A basic Typescript project (`.esproj` file) looks something like this:

```xml
<Project Sdk="Microsoft.VisualStudio.JavaScript.Sdk/0.5.74-alpha">
  <PropertyGroup>
    <!-- Command to run on project build -->
    <BuildCommand>npm run build</BuildCommand>
    <!-- Command to run on project clean -->
    <CleanCommand>npm run clean</CleanCommand>
  </PropertyGroup>
  <ItemGroup>
    <Folder Include="build\" />
  </ItemGroup>
</Project>
```

The following files are automatically added:

|File|Description|
|-|-|
|tsconfig.json|Typescript configuration file that provides tsc (a node package that is the Typescript compiler) with it's [build options](https://aka.ms/tsconfig).|
|package.json|Node.js configuration file that provides npm.exe (the [Node Package Manager](https://docs.npmjs.com/files/package.json)) with the Node packages to include.|
|nuget.config|Sources to use for Nuget packages.|

## Building

- When a developer select Project > Build, the `BuildCommand` is executed, which in turn runs `npm run build`. 
- `npm` looks for a `build` script defined in `package.json`, which is defined in by the `scrips` entry in `package.json`:

```json
"scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "build": "tsc --build",
    "clean": "tsc --build --clean"
},
```

- `tsc` is the Typescript compiler, which is installed as a Node package.

By default, calling `tsc --build` will find any `.ts` files, and compile them to `.js` and `.js.map` files.

> The `.js.map` file is a mapping between the generated/transpiled/minified JavaScript file and one or more original source files. 
The main purpose of Sourcemaps is to aid debugging. 
If there is an error in the generated code file, the map can tell you the original source file location. 
That's it.

This all happens in the root of the project.

# Quandis Customizations

## `/src` and `/build` folders

A common convention is to store `.ts` files in a `/src` folder, and the generated `.js` files in a `/build` folder.
This is enabled by modifying the `tsconfig.json` file:
```json
{
    "compilerOptions": {
        "experimentalDecorators": true, // for Lit compatibility
	    "outDir": "./js",
	    ...
    },
    "include": [ "src/**/*", "tests/**/*" ]
}
```

## Testing

[Lit recommends](https://lit.dev/docs/tools/testing/#web-test-runner) using [@web-test-runner](https://modern-web.dev/guides/test-runner/getting-started/) for testing Lit-based web components.
The `web-test-runner` tests javascript against actual browser javascript engines, rather than Node.js.
This is important because Node.js does not support the DOM, and Lit is a DOM-based library.
The `@web/test-runner-playwright` enables testing against Chrome, Safari and Edge.

To install `web-test-runner`:

```
npm install --save-dev @web/test-runner
npm install --save-dev @web/test-runner-playwright
```

To run tests, `packages.json` includes:
```json
{
    ...
    "scripts": {
        "test": "web-test-runner \"js/tests/**/*.test.js\" --node-resolve",
        "test:watch": "web-test-runner \"js/tests/**/*.test.js\" --node-resolve --watch",
        "test:all": "web-test-runner \"js/tests/**/*.test.js\" --node-resolve --playwright --browsers chromium firefox webkit --static-logging",
    },
    ...
}
```

## Publish Node Packages to Azure Devops

By default, `npm` will publish to the [npmjs.com](https://www.npmjs.com/) registry.
To publish to a private Azure Devops feed, you will create 2 .npmrc files:

- c:\users\your.username\\.npmrc: this will contain authentication info
- \{project folder}\\.npmrc: this will contain just the feed URL

The private `npmrc` file will look something like this:

```ini
qbo4:registry=https://pkgs.dev.azure.com/quandis/_packaging/qbo4-Build/npm/registry/ 
always-auth=true
; begin auth token
//pkgs.dev.azure.com/quandis/_packaging/qbo4-Build/npm/registry/:username=quandis
//pkgs.dev.azure.com/quandis/_packaging/qbo4-Build/npm/registry/:_password={your Devops PAT, base64 encoded}
//pkgs.dev.azure.com/quandis/_packaging/qbo4-Build/npm/registry/:email=npm requires email to be set but doesn't use the value
//pkgs.dev.azure.com/quandis/_packaging/qbo4-Build/npm/:username=quandis
//pkgs.dev.azure.com/quandis/_packaging/qbo4-Build/npm/:_password={your Devops PAT, base64 encoded}
//pkgs.dev.azure.com/quandis/_packaging/qbo4-Build/npm/:email=npm requires email to be set but doesn't use the value
; end auth token
```

> Yor PAT is an Azure Devops Personal Access Token, which you have configured for Visual Studio to pull Quandis Nuget packages
> You can use Fiddler's TextWizard to base64 encode your PAT.

The project `.npmrc` file will look something like this:

```ini
registry=https://pkgs.dev.azure.com/quandis/_packaging/qbo4-Build/npm/registry/ 
```

Some useful `npm` commands:

```ini
// list all npm config settings, including registries defined in various .npmrc files
npm config list

// publish to a specific registry
npm publish --registry=https://pkgs.dev.azure.com/quandis/_packaging/qbo4-Build/npm/registry/

// publish to whatever registry is defined in the local .npmrc file
npm publish

// increment the version number in package.json
npm version patch
```


# Notes 

- [Debug client scripts with VS and Chrome](https://learn.microsoft.com/en-us/visualstudio/javascript/debug-nodejs?view=vs-2022#debug-client-side-script)