Samora Vue3 Components

This is the Unbabel Design System Vue3 component library.

Table of Contents

• Table of Contents
• Prerequisites
• Install
• Usage
  • Uncompiled version
  • Compiled as UMD
  • Compiled as Web Components
  • Compiled as ES module
• Other build modes
  • Compiled as CommonJS
• Troubleshooting
• Components List
• UI preview
• Development
• Testing
• Guidelines
• How to release a new version

Prerequisites

⚠️ Requires node >= 20 ⚠️

Install

1) Install it using npm

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

2) Add Erik Meyer's CSS reset to your App, which can be found here, 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

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

Import the components into your app using:

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

And set it as a component on VueJS:

<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

// UMD
<script src="https://unpkg.com/@unbabel/[email protected]/vue3-components.umd.js"></script>

// or ES
<script src="https://unpkg.com/@unbabel/[email protected]/vue3-components.es.js"></script>

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

{
  "@unbabel/samora-vue3-components": "https://unpkg.com/@unbabel/[email protected]/vue3-components.umd.js"
}

Documentation preview

The library preview can be found here along with the documentation on how to use the components

Development

Guidelines

Be sure to follow Samora Operational Guidelines 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 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 server to preview your components:

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, 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)
5. Open the last step of the pipeline (Release Notes - example) and copy the changelog outputted in the console
6. Go to the Tags page on Samora
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