# Samora Vue3 Components

This is the Unbabel Design System Vue3 component library.

## Table of Contents

- [Table of Contents](#table-of-contents)
- [Prerequisites](#prerequisites)
- [Install](#install)
- [Usage](#usage)
    - [Uncompiled version](#uncompiled-version)
    - [Compiled as UMD](#compiled-as-umd)
    - [Compiled as Web Components](#compiled-as-web-components)
    - [Compiled as ES module](#compiled-as-es-module)
- [Other build modes](#other-build-modes)
    - [Compiled as CommonJS](#compiled-as-commonjs)
- [Troubleshooting](#troubleshooting)
- [Components List](#components-list)
- [UI preview](#ui-preview)
- [Development](#development)
- [Testing](#testing)
- [Guidelines](#guidelines)
- [How to release a new version](#how-to-release-a-new-version)

## Prerequisites
⚠️  **Requires node >= 20** ⚠️

## Install
**1) Install it using `npm`**

```shell
npm i --save @unbabel/samora-vue3-components
```

**2) Add Erik Meyer's CSS reset to your App, which can be found [here](https://meyerweb.com/eric/tools/css/reset/), so that all CSS styles are rendered properly.**

## Usage
There are currently 4 (tested) ways of using Samora:

### Uncompiled version
Install Samora via NPM, saving it as a dependency
```shell
npm i --save @unbabel/samora-vue3-components
```

Import the components into your app using:

```vue
<script setup>
import { SamButton } from '@unbabel/samora-vue3-components';
</script>
```

And set it as a component on VueJS:
```vue
<template>
    <SamButton label="CLICK ME" />
</template>
```

### Compiled as UMD
Import Samora as a script from one of the CDN providers with the appropriate version you want to include on your project
```javascript
// UMD
<script src="https://unpkg.com/@unbabel/samora-vue3-components@0.1.0/vue3-components.umd.js"></script>

// or ES
<script src="https://unpkg.com/@unbabel/samora-vue3-components@0.1.0/vue3-components.es.js"></script>
```

If you are using import maps, you can also add this library to it:

```json
{
  "@unbabel/samora-vue3-components": "https://unpkg.com/@unbabel/samora-vue3-components@0.1.0/vue3-components.umd.js"
}
```

## Documentation preview

The library preview can be found [here](https://samora.unbabel.com/) along with the documentation on how to use the components

## Development

### Guidelines
Be sure to follow [Samora Operational Guidelines](https://gitlab.com/Unbabel/frontend-tribe/frontend-tribe/-/wikis/Samora) on the Frontend Tribe's wiki

### Process
1. From the main branch, get the latest changes from remote - `git pull origin main`
2. Create a new feature branch prefixed with the jira ticket id - `git checkout -b UFE-1234/brief-description`
3. Update package version (follow the [Samora Operational Guidelines](https://gitlab.com/Unbabel/frontend-tribe/frontend-tribe/-/wikis/Samora) to decide the type of version) - `npm version <major|minor|patch>`
4. Push your first commit and create an MR marking it as draft
5. Develop the solution for your task (Don't forget to add tests!)
6. Once the implementation is completed, mark your MR as ready and submit it for review
7. Merge MR and back to the first step

⚠️ Commits messages to follow the following format:\
**"[vue3-components] custom message"**

### Running your local environment
To develop or add new components, install the project dependencies and launch [Storybook](https://storybook.js.org/) server to preview your components:

```shell
npm i
npm run storybook
```

Don't forget to "register" your new component on the `src/components/index.ts` file.
If this is not done, even if the component has been coded, it won't be available to be used.

### Implementing a new component
- Following the [Atomic Design principles](https://bradfrost.com/blog/post/atomic-web-design/), identify the type of component you are going to develop
- Create a new folder ```src/components/<ComponentType>/<NewComponentName```
- In the _<NewComponentFolder\>_ implement the following:
  - _<NewComponentName\>_**.stories.ts**
  - _<NewComponentName\>_**.types.ts**
  - _<NewComponentName\>_**.vue**
  - **\_\_tests__**/_<NewComponentName\>_**.spec.ts**
- Register your component (as previously mentioned)
  - `src/components/index.ts` **import** and **export** _<NewComponentName\>_

## Testing a component
### Running all tests
`npm run test` or `npm run test:ui` to get a prettier visualisation.

### Running specific test
`vitest --run --testNamePattern=<describeName>.<testCaseName> <ComponentName>.spec.ts`

#### ⚠️ Running tests from IDEs shortcuts ⚠️
Ensure that your IDE terminal is configured to run on node >= 20

## Testing your builds
This Samora module creates two builds

### Samora documentation
- Build `npm run storybook:build`
- Test `cd storybook-static && hostr --port 11000`

### Vue3 components package
- Build `npm run build`
- Package Build `cp package.json dist && cd dist && npm pack`
- Test Package in your vue3 app `npm i <absolutePathToDistFolder>/unbabel-samora-vue3-components-<version>.tgz`

## How to release a new version

1. Ensure your main branch has the latest changes - `git pull origin main`
2. Create a tag to match the new npm version in your package.json - `git tag vue3-components/vX.Y.Z`
3. Push the new Gitlab tag - `git push origin tag vue3-components/vX.Y.Z`
4. The CI will pick up the new tag and initiate the process of deployment, 
   with needs to be finalised by manually triggering the components package 
   deployment to NPM and the documentation (storybook) updates to aws
   ([Samora Gitlab's Pipelines](https://gitlab.com/Unbabel/frontend/samora/-/pipelines))
5. Open the last step of the pipeline (Release Notes -
   [example](https://gitlab.com/Unbabel/frontend/samora/-/jobs/7733828939)) and copy the changelog outputted in the console
6. Go to the [Tags page on Samora](https://gitlab.com/Unbabel/frontend/samora/-/tags)
7. Click on 'Create Release' button for the tag just deployed
8. Paste & manually prettify the changelog and save
9. Manually share the release in the #samora Slack channel
   
