@unbabel/ui

v5.17.0

Published

2 months ago

Samora Design System - The component library for Unbabel User Interfaces

Downloads

859

0High
0Medium
0Low

component library ui vuejs frontend unbabel

Samora Design System

This is the Unbabel UI (Vue.js) component library AKA Samora.

Install

1) Install it using npm

npm i --save @unbabel/ui

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 @unbabel/ui --save

Import the components into your app using:

import { Button } from '@unbabel/ui';

And set it as a component on VueJS:

components: {
  Button
}

So you can use it in your templates:

<SamButton label="Click me"></SamButton>

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

// MINIFIED version with sourcemaps (sourcemaps are optional)
<script src="https://unpkg.com/@unbabel/[email protected]/samora.umd.min.js"></script>
<script src="https://unpkg.com/@unbabel/[email protected]/samora.umd.min.js.map"></script>

or

<script src="https://cdn.jsdelivr.net/npm/@unbabel/[email protected]/samora.umd.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@unbabel/[email protected]/samora.umd.min.js.map"></script>

// FULL version with sourcemaps (sourcemaps are optional)
<script src="https://unpkg.com/@unbabel/[email protected]/samora.umd.js"></script>
<script src="https://unpkg.com/@unbabel/[email protected]/samora.umd.js.map"></script>

or

<script src="https://cdn.jsdelivr.net/npm/@unbabel/[email protected]/samora.umd.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@unbabel/[email protected]/samora.umd.js.map"></script>

Usage Details

The usage of this version of the lib can differ according to architecture you are using. In our micro-frontend architecture it's used as following:

import { Button } from '@unbabel/ui';

And set it as a component on VueJS:

components: {
  Button
}

So you can use it in your templates:

<SamButton label="Click me"></SamButton>

But it can also be used as an ES module. Check further below an example.

Compiled as Web Components

Import Samora as a script from one of the CDN providers with the appropriate version you want to include on your project

// MINIFIED version with sourcemaps (sourcemaps are optional)
<script src="https://unpkg.com/@unbabel/[email protected]/samora.min.js"></script>
<script src="https://unpkg.com/@unbabel/[email protected]/samora.min.js.map"></script>

or

<script src="https://cdn.jsdelivr.net/npm/@unbabel/[email protected]/samora.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@unbabel/[email protected]/samora.min.js.map"></script>

// FULL version with sourcemaps (sourcemaps are optional)
<script src="https://unpkg.com/@unbabel/[email protected]/samora.js"></script>
<script src="https://unpkg.com/@unbabel/[email protected]/samora.js.map"></script>

or

<script src="https://cdn.jsdelivr.net/npm/@unbabel/[email protected]/samora.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@unbabel/[email protected]/samora.js.map"></script>

Usage Details

Use it on a simple HTML doc as the following example:

<html>
  <head>
  </head>
  <body>
  <div id="app">
    <samora-button id="btn"></samora-button>
  </div>

  // Add VueJS (mandatory)
  <script src="https://unpkg.com/vue"></script>
    
  // Your Web Components library script
  <script src="https://unpkg.com/@unbabel/[email protected]/samora.min.js"></script>
    
  <script>
    // instanciate VueJS so it works it's magic to whatever is inside #app
    new Vue({
    el: '#app'
    })
      
    // event handler function
    function logger (e) {
    console.log('i am logging', e.detail)
    }
      
    var btn = document.querySelector('#btn')
      
    // this is how you assign values to your props (Strings and Ints can be done
    // directly on the HTML but Objects and Arrays must be assigned this way)
    btn.label = 'button'
    btn.icon = 'v1-alarm'
    btn.iconPosition = 'right'
      
    // This is how you register a handler for a custom event of your component
    btn.addEventListener('click', logger, true)
  </script>
  </body>
</html>

Compiled as ES module

Import Samora as a script from one of the CDN providers with the appropriate version you want to include on your project

<script src="https://unpkg.com/@unbabel/[email protected]/samora.esm.js"></script>
<script src="https://unpkg.com/@unbabel/[email protected]/samora.esm.js.map"></script>

or

<script src="https://cdn.jsdelivr.net/npm/@unbabel/[email protected]/samora.esm.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@unbabel/[email protected]/samora.esm.js.map"></script>

Usage Details

<html>
  <head>
    <link href="https://fonts.googleapis.com/css2?family=Montserrat:wght@400;600&family=Open+Sans:wght@400;600&display=swap" rel="stylesheet">
    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/meyer-reset/2.0/reset.min.css" integrity="sha512-NmLkDIU1C/C88wi324HBc+S2kLhi08PN5GDeUVVVC/BVt/9Izdsc9SVeVfA1UZbY3sHUlDSyRXhCzHfr6hmPPw==" crossorigin="anonymous" />
  </head>
  <body>
    <script src="https://unpkg.com/vue"></script>
    <div id="app"></div>
    <script type="module">
      import samora from './samora.esm.js'
      const App = {
        components: { ...samora },
        name: 'App',
        data: () => ({
          options: [
            { label: 'option1', value: 'value1' },
            { label: 'option2', value: 'value2' }
          ]
        }),
        computed: {},
        methods: {
          handleClick: function (e) {
            console.log('clicked!', e)
          },
          handleChange (val) {
            console.log('changed', val)
          }
        },
        template: `
          <div>
            <SamButton label="ES build1" @click="handleClick" icon="interface-notification"></SamButton>
            <SamSelect id="select" label="select es build1" :items="options" @change="handleChange"></SamSelect>
          </div>
        `,
      };
      new Vue({
        render: h => h(App),
      }).$mount(`#app`);
    </script>
  </body>
</html>

<html>
  <head>
    <link href="https://fonts.googleapis.com/css2?family=Montserrat:wght@400;600&family=Open+Sans:wght@400;600&display=swap" rel="stylesheet">
    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/meyer-reset/2.0/reset.min.css" integrity="sha512-NmLkDIU1C/C88wi324HBc+S2kLhi08PN5GDeUVVVC/BVt/9Izdsc9SVeVfA1UZbY3sHUlDSyRXhCzHfr6hmPPw==" crossorigin="anonymous" />
  </head>
  <body>
  <div id="app">
    <unbabel-button id="btn" label="es build2" icon="interface-notification" icon-position="right"></unbabel-button>
    <unbabel-metriccard :type="'is-white'" :main-title="'main title'" :secondary-title="'secondary title'" :terniary-title="'terniary title'"></unbabel-metriccard>
    <unbabel-select id="select" label="select type" :select-items="options" @change="handleChange"></unbabel-select>
  </div>
<script src="https://unpkg.com/vue"></script>
<script type="module">
  import samora from './samora.esm.js'

  const components = { ...samora }
  Vue.component('unbabel-button', components.Button)
  Vue.component('unbabel-metriccard', components.MetricCard)
  Vue.component('unbabel-select', components.Select)
  const vm = new Vue({
    el: '#app',
    data: {
      options: [
        { label: 'label1', value: 'value1' },
        { label: 'label2', value: 'value2' }
      ]
    },
    methods: {
      handleChange (val) {
        console.log('changed', val)
      }
    }
  })
</script>
  </body>
</html>

Other build modes

Compiled as CommonJS

Import Samora as a script from one of the CDN providers with the appropriate version you want to include on your project

<script src="https://unpkg.com/@unbabel/[email protected]/samora.common.js"></script>
<script src="https://unpkg.com/@unbabel/[email protected]/samora.common.js.map"></script>

or

<script src="https://cdn.jsdelivr.net/npm/@unbabel/[email protected]/samora.common.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@unbabel/[email protected]/samora.common.js.map"></script>

Troubleshooting

If you want to import a component to a unit test and running the test, the following error occurs:

 ({"Object.<anonymous>":function(module,exports,require,__dirname,__filename,global,jest){import Button from './src/components/Button/Button.vue'
                                                  ^^^^^^
  SyntaxError: Unexpected identifier

You should add the following property to your package.json jest configuration:

"transformIgnorePatterns": [
   "/node_modules/(?!@unbabel/ui).+\\.js$"
]

This happens because Samora is published as an untranspiled library. Since all files inside node_modules are not transformed by default, Jest will not understand the code in these modules, resulting in syntax errors. To overcome this, you may use transformIgnorePatterns to allow transpiling such modules.

Jest config - transformIgnorePatterns

Components List

Badge
Breadcrumbs
Button
Card
Checkbox
Chip
ChipMultiSelect
DateTimePicker
DropdownButton
GroupedInputText
Icon
InputChip
InputText
Label
Link
Loader
Menu
MetricCard
Modal
MultiSelect
NumberPicker
Pagination
ProgressBar
ProgressIndicator
Radio
Select
SwitchToggle
Table
Textarea
Tooltip

UI preview

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

Development

To develop or add new components, install the project dependencies and launch the Styleguidist server to preview your components:

npm i
npm run styleguide

When developing a new component, be careful with the @import paths which need to be relative to the folder structure rather than using @/... otherwise the Uncompiled version of the library won't work
Don't forget to "register" your new component on the index.js file located on the root of the project, so that it's available on the Uncompiled version of the library. If this is not done, even if the compoment has been coded, it won't be available to be used.
The same in terms of "registration" for new component on the libConfigUmd.js file located on the root of the project, so that it's available on the UMD version of the library.
The same in terms of "registration" for new component on the libConfigWc&Esm.js file located on the root of the project, so that it's available on the ES module version or the Web Component version of the library.

Testing

After development and before commiting your changes it's good pratice to test run all of the build modes first:

npm run styleguide:build // UI Preview build
npm run build:umd // UMD library build
npm run build:es // ES module library build
npm run build:wc-all // Web Components library build
npm run build:wc-individual-static // Individual Web Components library build, copying files to styleguide/static

One should also test the output of the builds to make sure they are working properly. In order to do that, on the folder /lib-build-tests you will find various index.html files which indicate which build mode should be tested.

Just spin a local web server http-server on the /lib-build-tests folder, copy the build files to this same folder as run the index files on your browser.

Guidelines

Be sure to follow Samora Operational Guidelines on the Frontend Tribe's wiki

How to release a new version

Once all the desired changes are merged into master, decide if the next version is Major, Minor or Patch and bump package.json and package-lock.json creating new tag by running npm version (major|minor|patch)

Example: npm version minor

Push all changes
Push the new Gitlab tag (NOTE: make sure the Gitlab tag has the same version as the package.json tag)

Example: git push origin tag v1.0.42

The CI will pick up the new tag and initiate the process of deployment, with needs to be finalised by manually triggering the deploy to NPM on Samora Gitlab's Pipelines)
Please make sure that you manually go to the Tags page on Samora and include a brief changelog to the Tag release notes

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Table of Contents

Install

Usage

Uncompiled version

Compiled as UMD

Usage Details

Compiled as Web Components

Usage Details

Compiled as ES module

Usage Details

Other build modes

Compiled as CommonJS

Troubleshooting

Components List

UI preview

Development

Testing

Guidelines

How to release a new version