@quandis/qbo4.ui 4.0.1-CI-20240403-131518

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@quandis/qbo4.ui",
+  "author": "Quandis, Inc.",
+  "license": "MIT",
+  "type": "module",
+  "version": "4.0.1-CI-20240403-131518",
+  "workspaces": [
+    "code"
+  ],
+  "main": "src/qbo/Program.js",
+  "private": false,
+  "scripts": {
+    "build": "npm run sass && tsc && npm run packdev && npm run packprod && del *.tgz && npm pack && ren *.tgz qbo4.ui.tgz",
+    "packdev": "webpack --config webpack.dev.js --no-color",
+    "packprod": "webpack --config webpack.prod.js --no-color",
+    "sass": "sass scss/:wwwroot/css && node cssshake.js"
+  },
+  "keywords": [
+    "qbo"
+  ],
+  "files": [
+    "wwwroot/js/",
+    "src/"
+  ],
+  "dependencies": {
+    "@codemirror/lang-html": "^6.4.6",
+    "@joint/core": "^4.0.1",
+    "bootstrap": "^5.3.3",
+    "bootstrap-icons": "^1.10.5",
+    "codemirror": "^6.0.1",
+    "lit": "^2.8.0",
+    "reflect-metadata": "^0.2.2",
+    "tsyringe": "^4.8.0",
+    "zero-md": "^2.5.3"
+  },
+  "devDependencies": {
+    "@esm-bundle/chai": "^4.3.4",
+    "@fullhuman/postcss-purgecss": "^5.0.0",
+    "autoprefixer": "^10.4.19",
+    "clean-css": "^5.3.3",
+    "glob": "^10.3.10",
+    "html-webpack-plugin": "^5.5.3",
+    "mini-css-extract-plugin": "^2.7.6",
+    "postcss": "^8.4.38",
+    "postcss-loader": "^8.1.1",
+    "sass": "^1.72.0",
+    "typescript": "^5.4.3",
+    "webpack": "^5.88.2",
+    "webpack-cli": "^5.1.4",
+    "webpack-merge": "^5.10.0"
+  }
+}

package/readme.md

@@ -0,0 +1,456 @@
+# 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)
+

package/src/qbo/Program.d.ts

@@ -0,0 +1,18 @@
+import 'reflect-metadata';
+export * from './qbo-badge.js';
+export * from './qbo-datalist.js';
+export * from './qbo-docviewer.js';
+export * from './qbo-json.js';
+export * from './qbo-logging.js';
+export * from './qbo-mainmenu.js';
+export * from './qbo-markdown.js';
+export * from './qbo-microphone.js';
+export * from './qbo-popover.js';
+export * from './qbo-popup.js';
+export * from './qbo-popup-listener.js';
+export * from './qbo-select.js';
+export * from './qbo-sidebar.js';
+export * from './qbo-table.js';
+export * from './qbo-validate.js';
+export * from './qbo-validators.js';
+export * from './qbo-api.js';

package/src/qbo/Program.js

@@ -0,0 +1,18 @@
+import 'reflect-metadata';
+export * from './qbo-badge.js';
+export * from './qbo-datalist.js';
+export * from './qbo-docviewer.js';
+export * from './qbo-json.js';
+export * from './qbo-logging.js';
+export * from './qbo-mainmenu.js';
+export * from './qbo-markdown.js';
+export * from './qbo-microphone.js';
+export * from './qbo-popover.js';
+export * from './qbo-popup.js';
+export * from './qbo-popup-listener.js';
+export * from './qbo-select.js';
+export * from './qbo-sidebar.js';
+export * from './qbo-table.js';
+export * from './qbo-validate.js';
+export * from './qbo-validators.js';
+export * from './qbo-api.js';

package/src/qbo/Program.ts

@@ -0,0 +1,19 @@
+import 'reflect-metadata';
+
+export * from './qbo-badge.js';
+export * from './qbo-datalist.js'
+export * from './qbo-docviewer.js'
+export * from './qbo-json.js';
+export * from './qbo-logging.js';
+export * from './qbo-mainmenu.js';
+export * from './qbo-markdown.js'
+export * from './qbo-microphone.js'
+export * from './qbo-popover.js'
+export * from './qbo-popup.js';
+export * from './qbo-popup-listener.js';
+export * from './qbo-select.js';
+export * from './qbo-sidebar.js'
+export * from './qbo-table.js';
+export * from './qbo-validate.js';
+export * from './qbo-validators.js';
+export * from './qbo-api.js';

package/src/qbo/qbo-api.d.ts

@@ -0,0 +1,27 @@
+import { LitElement } from 'lit';
+/**
+  * Defines a contract for form field validation.
+  * @remarks
+  * External classes may define custom validators by implementing this interface.
+  * Register the custom validator with the tsyringe DI container using {@link ValidateToken}.
+  */
+export interface IApiService {
+    fetch(relativePath: string | null, payload: Record<string, string> | null): Promise<any>;
+}
+export declare class RestApiService implements IApiService {
+    private headers;
+    private apiEndpoint;
+    private method;
+    constructor(apiEndpoint: string, headers?: HeadersInit, method?: string | null);
+    fetch(relativePath: string | null, payload?: Record<string, string> | null): Promise<any>;
+}
+export declare class ApiServiceComponent extends LitElement {
+    name: string | null;
+    apiEndpoint: string | null;
+    method: string;
+    firstUpdated(): void;
+    render(): import("lit").TemplateResult<1>;
+}
+declare function registerRestApi(name: string, apiEndpoint: string, headers?: HeadersInit, method?: string | null): void;
+declare function getApiService(name: string): IApiService;
+export { registerRestApi, getApiService };