@allakando/allakando-web-ui/Developers.md

Allakando's web component library

# Allakando Web UI

This library is commonly referred to as Allakando Web UI. It consists of a number of CSS files that implements the Allakando design system and a number of web components and utility functions.

# Architecture

## Web Components

Each web component consists of a number of files:

-   `.html` contains the shadow DOM
-   `.scss` compiles to a <style></style> element in the shadow DOM.
-   `.js` contains all JavaScript code
-   `.stories.js` contains the storybook configuration
-   `.test.js` contains any automated tests
-   `.md` contains a written documentation of how the component works, is meant to be used and so on.

The components are all vanilla web components. The js files have a bit of boilerplate in them in order to consume the HTML and SCSS files, but most work is done by the bundler. Check the ako-spinner component for a barebones js file.

All components are documented using JSDoc at the top of each js file, right above the class declaration. These JSDoc comments are automatically compiled into the documentation shown in Storybook. Remember to document all attributes, events, slots and functions here as well as a short description of the component.

When defining properties and functions in your components, prefix an underscore "\_" to the defined name if you don't want it to be included in the automatically generated documentation, or to indicate that it is not meant to be publicly accessed.

## Design System CSS

### External

The Stylesheets for the design system are compiled from SCSS files. Any file found in src/Stylesheets/External will be included in the distribution. All scss files in this folder should be imported into bundle.scss since this is meant to be an "import all" file.

The Stylesheets are designed to be, as far as is reasonable, classless. In other words, instead of for example targeting a class ".button" that has to be applied on all button elements in the consuming application the CSS will simply target the actual button elements. This results in most components having an Allakando look and feel by default.

### Internal

While all files in the External folder are meant to be consumable by external applications, the src/Stylesheets/Internal folder contains CSS used internally in the library for various purposes. This includes for example typography and color styles that can be imported and extended into other style files such as those of the web components.

The src/Stylesheets/variables file lets you import other variables and works like a central file for all SCSS variables.

It allows you to do things like this in your web components:

```scss
@import "../../Stylesheets/Internal/typography.scss";
@import "../../Stylesheets/variables.scss";

.some-element {
	@extend %h1;
	color: $primary-color-500;
}
```

### Tokens

Inside of src/Stylesheets/Tokens you will find a number of files where the most basic design system tokens are defined. These should rarely be imported directly into your code, instead you should implement them through the variables.scss file which contains a CSS variable wrapper that uses the tokens as fallback values. The reason for this is that it allows for the tokens to be reconfigured at runtime in any consuming application.

## Utilities

The library comes with utility functions that can be used to solve typically boiler plate heavy, common problems.

### confirm()

The confirm() function is a modern take on window.confirm(). It takes a message as input and returns a promise that will resolve to true if the user presses the confirm button, and false if the user presses the cancel button.

```javascript
import { confirm } from "allakando-web-ui"

const confirmWithUser = async () => {
	const choice = await confirm({ headerTitle: "Please Confirm", "This action is irreversible. Proceed?", resolveText: "Yes, please proceed", rejectText: "No, cancel" })
	console.log(choice)
}
```

### alert()

The alert() function is a modern take on window.alert(). It displays a message to the user in a modal form, and must be actively dismissed in order to be able to continue interacting with the page.

```javascript
import { alert } from "allakando-web-ui"

const alert = async () => {
	await alert({ headerTitle: "Important Message", message: "This is the message.", resolveText: "Ok, got it!" })
}
```

### showSpinner()

The showSpinner() function opens up a modal spinner with a loading message, and returns a function that can be used to close it again.

```javascript
import { showSpinner } from "allakando-web-ui"

const pretendToLoad = async () => {
	const closeSpinner = showSpinner("Loading things...")
	setTimeout(() => {
		closeSpinner()
	}, 3000)
}
```

### openDialog()

Open dialog allows you to easily create dialog windows that can be configured in a number of different ways. Generally speaking you will most likely wrap this function in a framework specific setting.

```javascript
import { openDialog } from "allakando-web-ui"
openDialog({
	icon: "iconurl",
	headerTitle: "This is a window!",
	subtitle,
	scrollable,
	center,
	bgcolor: "primary",
	body: `This is some content inside of the window.`
})
```

# How to develop

Most development should happen in Storybook but there is also a basic web server playground that can be spun up for vanilla tests.

## Storybook

Storybook is used in this project to document and develop the library. During development you can run a storybook server with hot reloading, and when necessary a storybook instance can be deployed in the cloud for testing and QA.

You start the development server by running:

```bash
npm run start:storybook
```

You can also run Storybook inside of docker by executing:

```bash
docker-compose up --build --force-recreate
```

## Local web server

There are times when Storybook has a bit too much magic in it, and if you ever feel like you want to try something out in a 100% vanilla environment you can start a basic web server based on the [index.html](./src/index.html) file in the src directory.

You can start this server by running:

```bash
npm run start
```

# Publishing (Deployment, Release)

## Branches

The production branch is `master`. This branch should always be the same as what is currently published.
Changes that are stable but not yet committed to `master` can be found in `staging`.

When working on features and bug fixes, create a branch from `staging` and PR it back to `staging`. When changes are ready to be published merge `staging` to `master`.

## Publishing

To publish the library to npmjs simply merge any branch into `master` and a pipeline will automatically be triggered.

**You should never manually update the package.json and package-lock.json version numbers.** This is all handled by the pipeline. The version number in staging does not need to be correct.

## Deployment

To deploy Web UI you can run the deploy-to-staging pipeline in bitbucket. This will build and publish Storybook.

Staging Web UI can be found here: https://staging.webui.allakando.se

For production no deployment currently exists, but you can access a (somewhat slow) copy through UNPKG: https://unpkg.com/@allakando/allakando-web-ui/dist/storybook/index.html

# Branding (CSS variables)

All components and Styleheets use CSS variables for branding. Most of these variables are also exported in the CSS exports to be available in the consuming applications.

By default variables for Allakando are used.

SCSS color variables can be imported internally in the project from [index.html](./src/Stylesheets/variables.scss)

CSS color variables for the consuming application are exported from [index.html](./src/Stylesheets/External/colors.scss)

# Test Automation

Test automation is done using Jest as well as Puppeteer for screenshot testing.

To run the test runner execute:

```bash
npm run test
```

## Cross browser (we are only testing Chromium)

Only Chromium is currently covered by the test runner. There have been instances with problems in other browsers, and in the future it may be of value to add other browsers to tests.

# NPM Scripts

| Command                   | Description                                                                       |
| ------------------------- | --------------------------------------------------------------------------------- |
| `npm run start:vanilla`   | Run the test environment (index.html)                                             |
| `npm run start:storybook` | Run the storybook environment in development mode                                 |
| `npm run start:docker`    | Used specifically by the docker container, not meant to be used outside of docker |
| `npm run start`           | Run the storybook environment in development mode                                 |
| `npm run test`            | Runs the test suite                                                               |
| `npm run test -- -u`      | Runs the test suite and overwrites all existing snapshots                         |
| `lint:fix`                | Runs the linter and formatter                                                     |
| `build:types`             | Builds all type definition files                                                  |
| `build:bundle`            | Builds all rollup builds                                                          |
| `build:documentation`     | Builds the custom-elements.json documentation files based on component JSDOC      |
| `build:storybook`         | Builds the production storybook SPA                                               |
| `build`                   | Builds the entire project for publishing and executes linter + tests              |

# Future Development

As the library has slowly stabilized there are a few updates that would be benefinicial in the future:

-   Upgrade from Storybook 6 to 7.
-   Add support for more browsers in the tests.