readme.md

# HUDS developer guide, basic workflow

## Install

1. `yarn install`
2. `yarn start` should start a dev server in port 3333. It displays the content from src/index.html

## Stencil

1. Have discussions with designers, agree on basic functionality
2. run `yarn generate` to generate a blanc component and start developing
3. Extract useful helper components, such as `<hy-row> <hy-column>`
4. Review the design with designer and PO or a colleague
5. Check with basic accessibility tools (TBD which tools?!?)
6. Write component documentation. At least it should
   1. Have a short introduction
   2. List all states the component can be in.
   3. List all variants the component can have
   4. Include code examples
7. Write unit tests where it makes sense. We use jest and puppeteer.
8. Run `bash bumpversion.sh` to run tests and bump the version number.
9. Do a final commit with all the build artefacts included.
10. Make a merge request -> pass the code review -> celebrate!

## Writing documentation in Vuepress

You should install the documentation project from https://version.helsinki.fi/julkiset-sivut/design-system.

To run it with your version of the design system, follow these steps:

1. Clone and install dependencies
2. Run `yarn add https://version.helsinki.fi/julkiset-sivut/design-system-lib.git#<YOUR-BRANCH>` to update the latest version of the library with the git branch you're currently working on.
3. Add necessary pages inside `.vuepress/config.js`
4. Manually add the Markdown documentation from the repository

## Combined workflow

In case you want to develop and see the component inside documentation right away, you can adapt the following workflow.

Inside the library Make a dynamic link of the library project:

`yarn link`

Inside the Vuepress project

`yarn link <library project name>`

The you need to start both development environments:

Vuepress directory: `yarn docs:dev`

Library directory: `yarn build.watch --target <VUEPRESS FOLDER>`

The second script starts both the stencil watcher in production mode, which builds the actual library on every change. It also concurrently runs a custom watcher script copying markdown files to Vuepress directory.

NOTE: Even when you have the documentation files in Vuepress, you'll need to manually add them to the navigation in docs/.vuepress/config.js

## Running with Docker (WIP)

If you don't want or cannot install node and other dependencies, you can run the development setup locally in a container like this:

`docker-compose up`

Image can be rebuilt with `docker-compose build` if needed for example after a node package was added.

CAVEAT: This doesn't solve running libraty with Vuepress and that use case requires vanilla docker way of running.

### Vanilla docker way

First build the container

`docker build -t helsinkifi/huds .`

Then run the image with optional Vuepress location and the npm script you want to run.

NOTE: If you want to use "watchdocs" or "build.watch" scripts, you must include the Vuepress location!

`docker run -v ${PWD}:/usr/src/app -v <YOUR VUEPRESS LOCATION FULL PATH>:/usr/src/app/tempdocuments -p 3333:3333 helsinkifi/huds <NPM SCRIPT>`

For example:

`docker run -v ${PWD}:/usr/src/app -p 3333:3333 helsinkifi/huds build`