@blockcerts/blockcerts-verifier 1.37.0

package/docs/ADR/adr-000-what-is-an-ADR.md

@@ -0,0 +1,23 @@
+# ADR 0: What is an ADR? 
+
+It stands for an Architectural Decision Report, and is described more thoroughly in this blog post: http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions 
+
+# Context 
+Projects tend to see a lot of different contributors intervene. Each of these contributors might influence the architecture in one way or another, and decisions remain, potentially hard to change, let alone understand. 
+
+# Decision 
+In order to maintain some sort of quick reference as to why some decisions have been made, we have decided to introduce this format. The purpose is to allow any new developer to the project to easily understand why some of the more important things have been done one way and not the other. 
+
+### Naming Convention
+The naming of files should be made as follows: 
+
+`adr-XXX-title-summary.md` 
+
+where XXX is a unique sequential number. 
+
+# Status 
+Accepted 
+
+# Consequences 
+Tricky/exposed/controversial architectural decisions now need to be documented in this file. 
+As stated in the original blog post, decisions can be superseded or deprecated, but need to be explicted once again via a new ADR.

package/docs/ADR/adr-001-tools-and-methodologies.md

@@ -0,0 +1,35 @@
+# ADR 1: Explaining the Tools and Methodologies
+
+## Context
+ Learning Machine handles a Blockcerts verifier in multiple repository and with different ways of deploying. This is costly and hard to maintain.
+ 
+ Decision has been made to unify the verifier into one sole component and repository, with scalibility and maintainability at heart. 
+ 
+ ## Decision
+ #### JS
+We decided to use Polymer 3.0 as previous versions of the verifier were already written with Polymer. Also because Web Components seem like a promising technology that could open a interesting future for the usage of the component.
+
+State of the application will be handled by Redux, as demonstrated in the [example project of Polymer](https://github.com/Polymer/pwa-starter-kit). 
+
+#### CSS
+We decided to use ITCSS for its interesting way to handle CSS scalability and maintainability.
+More information about this methodology can be found here:
+
+https://github.com/sky-uk/css
+
+https://www.xfive.co/blog/itcss-scalable-maintainable-css-architecture/
+
+#### Testing
+We are using the tools provided by the Polymer Project, hence [WCT](https://github.com/Polymer/tools/tree/master/packages/web-component-tester). We also test for accessibility.
+
+#### Accessibility
+The Web Component needs to be WCAG2.0 AA compliant.
+
+ ## Status
+ Accepted
+ 
+ ## Consequences
+ Follow above standards and methodologies for development. Maintain a good level of separation of concerns between state and views. Architecture for the communication with external APIs has not yet been decided, and will be subject of a future ADR. 
+ 
+ #### Testing
+ Since WCT exposes Mocha methods, prefer using the BDD methods `describe`, `it` and `expect`.

package/docs/ADR/adr-002-css-structure.md

@@ -0,0 +1,36 @@
+# ADR 2: Understanding the CSS structure
+
+## Context
+ Web Components encapsulate their shadow dom away from the rest of the DOM, meaning that a general stylesheet cannot style the internals of a Web Component.
+ 
+ As such, we need to find a strategy to maintain component level styles but enable shared styles so that we limit code duplication.
+ 
+ We had previously decided to follow ITCSS for its way to enable scalability as well as limit specificity war, and would like to keep following this approach.
+ 
+ ## Exploration
+ Using a general stylesheet is by essence out of the way.
+ 
+ Using `css-variables` cannot work as not all the problems that it solves are based on variables. Indeed we need to be able to apply blocks of styles in some cases, and maintaining a variable API for each component might lead to insanity.
+ 
+ [@apply](https://tabatkins.github.io/specs/css-apply-rule/) seemed promising, but the proposal has been discontinued, and its replacements (see [ShadyCSS Readme](https://github.com/webcomponents/shadycss/blob/master/README.md#about-applyshim)) are still in proposal stage and might not become the standard. 
+ 
+ Finally it seems that the only option in front of us is to embed styles per component.
+ 
+ ## Decision
+ Considering the outcome of the exploration, and seeing that we want to maintain a sense of scalability and separation of concerns as advocated by the ITCSS methodology, we have decided to maintain component specific stylesheets at component directory level, and use Sass `import` within these sheets to add specific classes that many component might use (basically any other layer from ITCSS beyond components).
+ 
+ Shared styles will be hosted under `src/shared-styles` folder and organized following the ITCSS nomenclature.
+ 
+ At this moment the `main.scss` file is maintained as it contains information around the available files, and may prove worthy in the future. The value of this needs to be reassessed.
+ 
+ ## Status
+ Accepted
+ 
+ ## Consequences
+ We are using [wc-sass-render](https://github.com/tristanMatthias/wc-sass-render) instead of our initial in-house solution, as it solves the exact problem we are facing, and provides the options we need.
+ 
+ CSS files under the components need to follow ITCSS convention in terms of naming, in order to better highlight their layer in the inverted triangle concepts.
+ 
+ Code duplication has been accepted as tech-debt, and might incur solutions to better handle large imports (such as tree-shaking, file splitting, etc).  
+ 
+ 

package/docs/ADR/adr-003-store-connector-container-component.md

@@ -0,0 +1,164 @@
+# ADR 3: Connecting the store to a component
+
+## Context
+[pwa-starter-kit](https://github.com/Polymer/pwa-starter-kit) is an example of a Redux application working with Polymer 3. While it serves its purpose, the separation of concerns is not entirely clear between the state and the views, which means that in the example views have too much knowledge of what provides and modfies the state.
+
+This is potentially dangerous for scalability, and bloats the view code with decisions that shouldn't be of its concerns.
+
+React provides an architectural pattern to handle this abstraction, in the shape of `Containers`. Containers are wrapper around the view component, which connect (via the `react-redux` helper function of the same name) the view and the state (to read it, and to action it). 
+
+This pattern is interesting because from an architectural standpoint every responsibility is properly distributed. The view receives props, may they be data or callback functions, and utilizes them, the container selects where to retrieve the data or callback functions, and the state solely stores the data and provide mechanisms to modify it.
+ 
+## Decision
+We decided to keep this approach for a Polymer project too. Because the out-of-the-box tools do not provide that abstraction, we implemented our own architectural approach to fit this need.
+
+A visual representation of the intent is as follows:
+![Chain of connection: State > Connector > Container > Component](https://user-images.githubusercontent.com/12797962/41294972-a254d432-6e59-11e8-8e08-214c43772173.png)
+ 
+- The state handles the live data of the application.
+- The connector has an instantiation of the store, but is also a metaview, which enables communication with the methods of the store, without exposing it elsewhere.
+- The container is an instance of the connector, which allows defining which part of the state and which actions we would like to bind to its wrapped component.
+- And the wrapped component is just a regular component which expects some props, but does not know nor care where they come from.
+
+## Status
+ Accepted
+ 
+## Consequences
+Implementation of components that need to access the state must follow this pattern.
+
+There are 2 types of components in Polymer, pure functions and classes (extending `LitElement`).
+The implementation of this approach differs a little bit, due to technical constraints of LitElement.
+
+Example of a pure function:
+
+**Component**
+
+```javascript
+const Input = ({ onInput = () => {} } = {}) => {
+  return html`
+    <label 
+      for='input'>Label for input</label>
+    <input 
+      type='text'
+      id='input'
+      on-input='${(e) => { onInput(e.target.value); }}'
+    />
+  `;
+};
+
+export default Input;
+```
+**Container**
+
+```javascript
+import foo from '../../../actions/foo';
+import connector from '../../../store/connector';
+import Input from './Input';
+
+const mapDispatchToProps = {
+  onInput: foo
+};
+
+const InputContainer = connector(Input, { mapDispatchToProps });
+export { InputContainer };
+```
+
+Example of a class component:
+
+**Component**
+```javascript
+class Button extends LitElement {
+  static get properties () {
+    return {
+      onClick: Function
+    };
+  }
+
+  _render (_props) {
+    return html`
+      <button on-click='${_props.onClick}'>
+       Label
+      </button>
+    `;
+  }
+}
+
+window.customElements.define('buv-verify-button-raw', Button);
+
+// wrap VerifyButton in order to plug into Container
+// necessary trade-off to deal with class component in the store connector
+function ButtonWrapper (props) {
+  return html`<buv-verify-button-raw onClick='${props.onClick}'></buv-verify-button-raw>`;
+}
+
+export { ButtonWrapper as Button };
+```
+We need to encapsulate the button (that we need to define as a reusable component for this purpose) into a pure function, in order to simplify the rendering of the connector. This function is then exported and reused in the container. 
+
+**Container**
+
+```javascript
+import bar from '../../../actions/bar';
+import connector from '../../../store/connector';
+import { Button } from './Button';
+
+const mapDispatchToProps = {
+  onClick: bar
+};
+
+const VerifyButtonContainer = connector(Button, { mapDispatchToProps });
+export { VerifyButtonContainer };
+```
+Encapsulating the wrapping function inside the component allows for containers to always follow the same pattern and improves expectability.
+
+#### mapping actions to a component
+use `mapDispatchToProps`.
+It should be an object expect the key (prop that is going to be passed down to the component), and the value should be the action creator to be mapped. See above example for more details.
+
+#### mapping state to a component
+use `mapStateToProps`.
+It should be a function taking `state` as a parameter, and returning an object with as the key the prop that is going to be passed down to the component, and as a value the selector method reading the state.
+
+```javascript
+import connector from '../../../store/connector';
+import Input from './Input';
+import { foo } from '../../../selectors/foo';
+
+const mapStateToProps = (state) => ({
+  isValid: foo(state)
+});
+
+const InputContainer = connector(Input, { mapStateToProps });
+export { InputContainer };
+
+```
+
+#### exposing the component own props
+use `ownProps`. 
+Sometimes you want to be able to pass the props from where you use the component directly.
+In the case of a connected component, this is not as straightforward as expected.
+In order to do so, you need to map the `ownProps` object to the component's actual properties.
+
+In practice, this means exposing your component as `SourceComponent`, and matching `ownProps` to `SourceComponents.properties`.
+
+ie:
+```javascript
+export {
+  BlockcertsVerifier as SourceComponent,
+  BUVWrapper as BlockcertsVerifier
+};
+```
+
+and in the container:
+
+```javascript
+import connector from '../store/connector';
+import { BlockcertsVerifier, SourceComponent } from './BlockcertsVerifier';
+
+const ownProps = SourceComponent.properties;
+
+const BlockcertsVerifierContainer = connector(BlockcertsVerifier, { ownProps });
+export { BlockcertsVerifierContainer };
+
+```
+

package/docs/ADR/adr-004-domain.md

@@ -0,0 +1,38 @@
+# ADR 4: Explaining the Domain
+
+## Context
+Redux provides a good mechanism to handle the state and its mutations, but not so much to handle the business logic.
+
+However, like always, to keep a good segregation of concerns, we want to handle all business related logic, as well as all external communication of the application isolated. 
+
+## Decision
+To do so, we introduce the concept of domain.
+
+The domain is the part responsible for everything that's not the view concern, nor the state concern.
+
+The view concern is to render data.
+The state concern is to store and modify data.
+
+The rest belongs to the domain.
+
+A visual representation is as follows:
+
+![Domain connection: outer world > domain > state > view](https://user-images.githubusercontent.com/12797962/41419432-4c70fd4e-6ff2-11e8-8acd-a18367087193.png)
+
+Each method of the next inner layer only knows about the layer above it.
+
+This domain is only inspired from Domain Driven Design and aims at being a simpler implementation of the approach.
+
+## Status
+ Accepted
+ 
+## Consequences
+Domain concerns must be implemented so that methods (use cases) can be called as follows:
+
+```
+domain.concern.usecase
+```
+
+Use cases must be tested.
+
+Objects resulting from domain methods can be stored in either Entities or Value Objects (see definitions: https://en.wikipedia.org/wiki/Domain-driven_design#Building_blocks), depending on the shape and concept they represent.

package/docs/ADR/adr-005-substeps-list.md

@@ -0,0 +1,35 @@
+# ADR 5: Substeps List size calculation
+
+## Context
+ SubstepsList needs to be animated between showing and hiding the substeps of a step.
+ Animating proves convenient on `max-height`
+ We were initially hard coding the `max-height` property of the substeps list to have a maximum to animate too (from 0).
+ However, hard-coding that value proved not flexible, especially when the substep was also holding an `ErrorMessage`, which could span an undeterminate height (multiple lines, responsiveness, etc).
+ 
+ The height of the list all determines the height of the progress bar which at this point is settled and working with little work. 
+ 
+ ## Exploration
+ Not many options are available to make sure we can pre-calculate the dynamic, correct, potential `max-height` of the list.
+ 
+ - One way could be render the list somewhere on the DOM, hidden, in order to retrieve its height. However this proves problematic as we need to do a prerender which means complicating the DOM and the application code.
+ - Another solution is to read the height of the list element once it has been rendered, and maintain it locally within the parent class. It is not super elegant as we need to overwrite the style property after rendering. 
+ 
+ ## Decision
+ We chose to follow the second approach which requires less code to work. It is however creating issues with the `html` templating function of `lit-element`, since we change the state of the attribute without informing the library.
+ Doing the latter would mean re-rendering via a state prop which would have to be updated at the `_didRender` moment, and would create complains from Polymer.
+ 
+ We thus decided to trick the component:
+ - we only calculate the `totalHeight` once, since content will not change once rendered.
+ - we only force the `max-height` with the calculated height once, if the component was forced rendered and if we haven't applied the trick already
+ 
+ We discovered that it would then require 3 clicks on the `hide` button to finally close the list. Some research led us to discover that the `html` templating function handles the values of the attributes, and does not trigger a change (cf: https://github.com/Polymer/lit-html/blob/master/src/core.ts#L538). As such, in the state of the code, the active value is `0` and not `[totalHeight]px` as we forced it to be. Since the closing value is 0 too, the code didn't see the reason for the change.
+ 
+ To circumvent this issue, we are now setting the `hidden` state value to be 1px, which allows for the initial closing.
+
+ ## Status
+ Accepted
+ 
+ ## Consequences
+ It is not a very elegant hack, but it seems the least aggressive for the browser.
+ You should avoid such approaches if you can, though. 
+ 

package/docs/ADR/adr-006-handling-plural-i18n.md

@@ -0,0 +1,20 @@
+# ADR 5: Handling plural for i18n label
+
+ ## Context
+ Sometimes labels need to handle pluralization. While it could be just as easy as adding a `s` at the end of the word in English (it is not), French or Spanish, other languages have a variation of their plural form that require a better handling.
+ 
+ ## Exploration
+ We could use a pluralization library but that comes at the cost of added weight to the bundle as well as not guaranteeing success for more complex strings.
+ Or we could also simply handle both strings in the translation files.
+ 
+ ## Decision
+ We chose to follow the second approach which adds less overhead to the bundle. 
+ It comes at the cost of having the contributor to add the plural version of the string they want translated. But this explicit approach also reduces the risk of error and inconsistency.
+ 
+ ## Status
+ Accepted
+ 
+ ## Consequences
+ The contributor will make sure they add a `keyPlural` version mapping to the singular version `key` to the translation files.
+ Using the `getText` method, they will have to set the third argument (`usePlural`) to true, and pass as the fourth argument the `count` property which will decide which string to use.
+ 

package/karma.conf.js

@@ -0,0 +1,26 @@
+/* eslint-disable import/no-extraneous-dependencies */
+const { createDefaultConfig } = require('@open-wc/testing-karma');
+const merge = require('deepmerge');
+
+module.exports = config => {
+  config.set(
+    merge(createDefaultConfig(config), {
+      files: [
+        // runs all files ending with .test in the test folder,
+        // can be overwritten by passing a --grep flag. examples:
+        //
+        // npm run test -- --grep test/foo/bar.test.js
+        // npm run test -- --grep test/bar/*
+        { pattern: config.grep ? config.grep : 'test/e2e/*.test.js', type: 'module' }
+      ],
+
+      browsers: ['FirefoxHeadless'], // Chrome from default config
+
+      esm: {
+        nodeResolve: true
+      }
+      // you can overwrite/extend the config further
+    })
+  );
+  return config;
+};

package/package.json

@@ -0,0 +1,125 @@
+{
+  "name": "@blockcerts/blockcerts-verifier",
+  "version": "1.37.0",
+  "description": "A standalone universal viewer and verifier for blockcerts credentials",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/blockchain-certificates/blockcerts-verifier.git"
+  },
+  "main": "dist/main.js",
+  "dependencies": {
+    "@babel/runtime": "^7.6.0",
+    "@blockcerts/cert-verifier-js": "^4.11.0",
+    "@polymer/lit-element": "0.5.1",
+    "@polymer/polymer": "3.4.1",
+    "@webcomponents/webcomponentsjs": "2.6.0",
+    "autolinker": "^3.14.1",
+    "cssfilter": "0.0.10",
+    "proxy-polyfill": "^0.3.0",
+    "redux": "^4.0.0",
+    "redux-thunk": "^2.3.0",
+    "whatwg-fetch": "^3.0.0",
+    "xss": "^1.0.3"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.6.0",
+    "@babel/plugin-transform-runtime": "^7.6.0",
+    "@babel/preset-env": "^7.6.0",
+    "@babel/preset-typescript": "^7.9.0",
+    "@commitlint/cli": "^13.1.0",
+    "@commitlint/config-conventional": "^12.0.1",
+    "@open-wc/testing": "^2.5.16",
+    "@open-wc/testing-karma": "^4.0.3",
+    "@polymer/iron-demo-helpers": "^3.0.0-pre.19",
+    "@types/jest": "^27.0.0",
+    "@types/sinon": "^10.0.0",
+    "@typescript-eslint/eslint-plugin": "^4.16.1",
+    "@typescript-eslint/parser": "^4.16.1",
+    "axe-core": "^4.0.1",
+    "babel-jest": "^26.0.0",
+    "codecov": "^3.1.0",
+    "concurrently": "^6.0.0",
+    "deepmerge": "^4.2.2",
+    "eslint": "^7.21.0",
+    "eslint-config-standard": "^16.0.2",
+    "eslint-config-standard-with-typescript": "^20.0.0",
+    "eslint-plugin-import": "^2.20.2",
+    "eslint-plugin-node": "^11.1.0",
+    "eslint-plugin-promise": "^4.2.1",
+    "eslint-plugin-standard": "^5.0.0",
+    "express": "^4.16.3",
+    "husky": "^7.0.1",
+    "jest": "^25.5.4",
+    "jest-fetch-mock": "^3.0.0",
+    "karma-firefox-launcher": "^2.0.0",
+    "polymer-cli": "^1.8.1",
+    "pwa-helpers": "^0.8.2",
+    "rollup": "^2.2.0",
+    "rollup-plugin-babel": "^4.3.3",
+    "rollup-plugin-commonjs": "^10.0.0",
+    "rollup-plugin-livereload": "^2.0.0",
+    "rollup-plugin-node-resolve": "^5.0.0",
+    "rollup-plugin-replace": "^2.0.0",
+    "rollup-plugin-serve": "^1.0.1",
+    "rollup-plugin-terser": "^7.0.0",
+    "rollup-plugin-typescript": "^1.0.1",
+    "sass-lint": "^1.12.1",
+    "semantic-release": "^17.0.2",
+    "semistandard": "^14.1.0",
+    "sinon": "^11.1.0",
+    "snazzy": "^9.0.0",
+    "ts-jest": "^26.5.2",
+    "typescript": "^4.2.2",
+    "watch": "^1.0.2",
+    "wc-sass-render": "1.0.0",
+    "wct-browser-legacy": "^1.0.2",
+    "web-component-tester": "^6.9.0"
+  },
+  "scripts": {
+    "build": "rollup -c rollup.config.js",
+    "build:sanitizer": "rollup -c rollup-sanitizer.config.js",
+    "test": "npm run test:application",
+    "test:build": "npm run test:components:retrieve && polymer test; npm run test:karma",
+    "test:karma": "tsc -p tsconfig-test.json && karma start; npm run test:karma:cleanup",
+    "test:karma:cleanup": "git clean -dfq",
+    "test:components:retrieve": "node test/wct-script/retrieveTestFiles",
+    "test:components:retrieve:watch": "npm run test:components:retrieve -- --watch",
+    "test:components:persist": "concurrently 'npm run test:components:retrieve:watch' 'polymer test -p'",
+    "test:application": "jest --runInBand --silent",
+    "test:application:watch": "jest --watch",
+    "test:coverage": "jest --maxWorkers=4 --silent --noStackTrace --coverage",
+    "test:coverage:report": "codecov",
+    "start": "concurrently 'rollup -c rollup.dev.config.js -w' 'npm run styles:compile:watch' 'npm run start:mock-server'",
+    "start:mock-server": "node test/mock-server",
+    "styles:compile": "sass-render ./src/components/**/*.scss",
+    "styles:compile:watch": "sass-render ./src/components/**/*.scss -w",
+    "lint": "npm run lint:js && npm run lint:ts && npm run lint:styles",
+    "lint:fix": "semistandard --fix",
+    "lint:js": "semistandard \"**/*.js\" | snazzy",
+    "lint:ts": "eslint . --ext .ts",
+    "lint:styles": "sass-lint --verbose",
+    "semantic-release": "semantic-release",
+    "prepare": "husky install"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "semistandard": {
+    "globals": [
+      "performance",
+      "fetch",
+      "FileReader",
+      "atob",
+      "CustomEvent",
+      "Image",
+      "domainParseStub"
+    ],
+    "ignore": [
+      "sanitizer/sanitizer.js",
+      "test/wct-script/getTestFiles.js",
+      "test/assertions/*",
+      "*-css.js"
+    ],
+    "env": "jest"
+  }
+}