Introduction

SamGuide

import SamGuide from '@unbabel/ui';

Introduction to 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:

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/ui@4.4.10/samora.umd.min.js"></script>
<script src="https://unpkg.com/@unbabel/ui@4.4.10/samora.umd.min.js.map"></script>

or

<script src="https://cdn.jsdelivr.net/npm/@unbabel/ui@4.4.10/samora.umd.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@unbabel/ui@4.4.10/samora.umd.min.js.map"></script>

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

or

<script src="https://cdn.jsdelivr.net/npm/@unbabel/ui@4.4.10/samora.umd.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@unbabel/ui@4.4.10/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 { SamButton } from '@unbabel/ui';

And set it as a component on VueJS:

components: {
  SamButton
}

So you can use it in your templates:

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/ui@4.4.10/samora.min.js"></script>
<script src="https://unpkg.com/@unbabel/ui@4.4.10/samora.min.js.map"></script>

or

<script src="https://cdn.jsdelivr.net/npm/@unbabel/ui@4.4.10/samora.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@unbabel/ui@4.4.10/samora.min.js.map"></script>

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

or

<script src="https://cdn.jsdelivr.net/npm/@unbabel/ui@4.4.10/samora.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@unbabel/ui@4.4.10/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/ui@4.4.10/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 = '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/ui@4.4.10/samora.esm.js"></script>
<script src="https://unpkg.com/@unbabel/ui@4.4.10/samora.esm.js.map"></script>

or

<script src="https://cdn.jsdelivr.net/npm/@unbabel/ui@4.4.10/samora.esm.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@unbabel/ui@4.4.10/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="alarm"></Button>
           
            <SamSelect id="select" label="select es build1" :items="options" @change="handleChange"></Select>
          </div>
        `,
      };
      new Vue({
        render: h => h(App),
      }).$mount(`#app`);
    </script>
  </body>
</html>

or

<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="alarm" icon-position="right"></unbabel-button>
    <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.SamButton)
  Vue.component('unbabel-select', components.SamSelect)
  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/ui@4.4.10/samora.common.js"></script>
<script src="https://unpkg.com/@unbabel/ui@4.4.10/samora.common.js.map"></script>

or

<script src="https://cdn.jsdelivr.net/npm/@unbabel/ui@4.4.10/samora.common.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@unbabel/ui@4.4.10/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

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

  1. 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)

  2. Example: npm version minor

  3. Push all changes

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

  5. Example: git push origin tag v1.0.42

  6. 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)
  7. Please make sure that you manually go to the Tags page on Samora and include a brief changelog to the Tag release notes

Unbabel Samora