@unbabel/samora-vue3-components 0.0.4 → 0.1.1

package/README.md

@@ -1,9 +1,159 @@
-# Vue 3 + TypeScript + Vite
+# Samora Vue3 Components
 
-This template should help get you started developing with Vue 3 and TypeScript in Vite. The template uses Vue 3 `<script setup>` SFCs, check out the [script setup docs](https://v3.vuejs.org/api/sfc-script-setup.html#sfc-script-setup) to learn more.
+This is the Unbabel Design System Vue3 component library.
 
-## Recommended Setup
+## Table of Contents
 
-- [VS Code](https://code.visualstudio.com/) + [Vue - Official](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (previously Volar) and disable Vetur
+- [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)
 
-- Use [vue-tsc](https://github.com/vuejs/language-tools/tree/master/packages/tsc) for performing the same type checking from the command line, or for generating d.ts files for SFCs.
+## 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 - `npm 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 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
+   

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@unbabel/samora-vue3-components",
   "description": "Samora - the Unbabel design system - Vue3 components",
-  "version": "0.0.4",
+  "version": "0.1.1",
   "type": "module",
   "main": "./vue3-components.umd.js",
   "module": "./vue3-components.es.js",
@@ -67,8 +67,8 @@
     "eslint-plugin-vuejs-accessibility": "^2.3.0",
     "glob": "^10.4.1",
     "globals": "^15.3.0",
-    "prettier": "^3.3.1",
     "jsdom": "^24.1.0",
+    "prettier": "^3.3.1",
     "rimraf": "^5.0.7",
     "rollup": "^4.18.0",
     "rollup-plugin-typescript2": "^0.36.0",
@@ -80,6 +80,7 @@
     "typescript": "^5.2.2",
     "typescript-eslint": "^7.11.0",
     "vite": "^5.2.0",
+    "vite-plugin-css-injected-by-js": "^3.5.1",
     "vite-plugin-sass": "^0.1.0",
     "vite-svg-loader": "^5.1.0",
     "vitest": "^1.6.0",