npm-allakando-publish/Developers.md

Allakando's web component library

# How to use the library

| Command               | Description                                                                  |
| --------------------- | ---------------------------------------------------------------------------- |
| `npm start`           | Run the test environment (index.html)                                        |
| `npm start:storybook` | Run the storybook environment in development mode                            |
| `npm run build`       | Run the entire build pipeline (typically before publishing)                  |
| `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:rollup`        | 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         |

# When workin in the library
The production branch is `master`. This branch should always be the same as what is currently published.
Changes that are stable but not yet commited to `master` can be found in `develop`.

When working on features and bug fixes, create a branch from `develop` and PR it back to `develop`. When changes are ready to be published merge `develop` to `master`, but do not remove the branch.

# Develop components
Each component has 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 all automated tests
- .md contains a written documentation of how the component works, is meant to be used, and so on.

Each component is essentially a vanilla web component. Very little boilerplate is necessary to bind all files together since most of this is done by Rollup at compile-time. Check the ako-spinner component for a fairly barebones .js file with all necessary boilerplate in it.

All components are documented using JSDoc at the top of the file right above the class declaration. These JSDoc comments are 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.

example:
```javascript
myWebComponent.myvariable = "Hello" // -> This will show up as "myvariables (string)" in Storybook
myWebComponent._myvariable2 = "Hello" // -> This will be hidden from the documentation tab in Storybook
```

# Utility functions
The library comes with utility functions that can be used to improve development speed.

## 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("Please Confirm", "This action is irreversible. Proceed?", "Yes, please proceed", "No, cancel")
	console.log(choice)
}
```

## alert()
The alert() function is a modern take on window.alrt(). 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 () => {
	const choice = await confirm("Important Message", "This is the message.", "Ok, got it!")
	console.log(choice)
}
```

## 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()
This is the easiest way to open up dialog windows.

These are the options that can be passed to the function:

```javascript
interface OpenDialogOptions {
	/** If true the window will have no built-in header. */
	noheader?: boolean
	/** If true the window will have no built-in footer. */
	nofooter?: boolean
	/** If true the window will have no close button. */
	noclose?: boolean
	/** Determines if the window has a backdrop, and if the backdrop closes the window when clicked. */
	modality?: "none" | "clickable" | "disabled"
	/** Determines if the dialog should size itself to fit its content. */
	fluid?: boolean
	/** The title for the modal header. */
	title?: string
	/** The subtitle for the modal header. */
	subtitle?: string
	/** Stylesheets for the dialog. */
	style?: string
	/** Should the dialog be scrollable? If false then the page will scroll. */
	scrollable?: boolean
	/** Should the dialog be centered in the viewport? */
	center?: boolean
	/** The main content of the window */
	body?: string | HTMLElement | ((...args: any[]) => HTMLElement)
	/** A custom header for the window */
	header?: string | HTMLElement | ((...args: any[]) => HTMLElement)
	/** The footer content for the window */
	footer?: string | HTMLElement | ((...args: any[]) => HTMLElement)
}
```

# Style injections
Style injections can be used to inject global css into your application like so:

```javascript
    AllakandoWebUI.injectStyle({
      typography: true,
    })
```

The following styles can be injected
- typography (Updates all text and adds the following supportive classes: .body-1 .body-2 .button-1 .button-2 .d1)

# Branding (CSS variables)
All components can be branded using CSS variables. Check out ./src/Assets/variables.scss to see what variables are configurable.

# When publishing
Ensure that all changes have been merged from `develop` to `master`.

Ensure that all documentation is up to date:
- Markdown files on a component level
- Markdown files on a project level
- JSDOC comments in changed components and files

Ensure that tests and linting is passing:
- `npm run lint:fix`
- `npm run test`

Execute the build:
- `npm run build`

Publish to production:
- `npm publish`