@t-systems-innovation-lab/mvp-library v0.3.1

MVP Vue Component Library

This library provides a collection of commonly used Vue components, utility functions and structures that can be imported and reused in a new Vue project.

🚀 Quick Start in your project

Before starting, checkout the storybook to view all available components.

Setup with npm

Install this library in your project using npm:

npm install @t-systems-innovation-lab/mvp-library

NOTE: This implicitly installs @telekom/scale-components automatically.

Local Installation

Most of the components are based on the @telekom/scale-components package. If you use only specific components of this library, you have to install this plugin first. Inside of your Vue project (main.ts), import the module and install it:

import { createApp } from 'vue'
import App from './App.vue'

import { defineCustomElements } from "@telekom/scale-components/loader";
import "@telekom/scale-components/dist/scale-components/scale-components.css";

defineCustomElements();

const app = createApp(App)
app.config.compilerOptions.isCustomElement = (tag: string) => tag.startsWith('scale-');
app.mount('#app')

// ...

Global Installation

If you install the library globally, the @telekom/scale-components plugin is installed implicitly with it. Inside of your Vue project (main.ts), import the module and install it:

import { createApp } from 'vue'
import App from './App.vue'

import MVPLibrary from '@t-systems-innovation-lab/mvp-library'
import '@t-systems-innovation-lab/mvp-library/dist/style.css'

const app = createApp(App)
app.use(MVPLibrary)
app.mount('#app')

// ...

Use of Components

Local

To use a component import the components as named imports, then simply create a HTML like tag with the name of the component inside. For example the LoadingButton-component can be used as follows:

<script>
  import { LoadingButton } from '@t-systems-innovation-lab/mvp-library'
</script>

<template>
  <LoadingButton></LoadingButton>
</template>

Global

To use a component simply create a HTML like tag with the name of the component inside. For example the LoadingButton-component can be used as follows:

<LoadingButton></LoadingButton>

OR

<loading-button></loading-button>

Use of Utils / Hooks / Functions

To use a utility function it must be explicitly imported within a script-tag or in general a location that allows javascript. The useSize-function for example can be imported and executed as follows:

<script>
import { useSize } from '@t-systems-innovation-lab/mvp-library'

const { width, height } = useSize()
</script>

🔨 Contributing to this Framework

🗄️ Project Structure

The whole package is located inside the src folder, which has the following structure:

src
|
index.ts              # exports all components and functions
|
+-- components        # shared components used across the entire application
|
+-- utils             # shared utility functions

💻 Adding / Updating Compoments

Setup

If you want to add components or utility functions, you have to clone this repository first. Then inside of the project run this command:

npm run dev-setup

This command will install the dependencies, build the library and the storybook once.

Rebuild

Whenever you make changes to this project and want to rebuild the files for distribution, then you have to execute the following command:

npm run build

This will check the types and rebuild the distribution files.

NOTE: This is only needed for development, as the pipeline builds the project itself before publishing it to the npm registry.

Components

Create a new Vue component as usual - no export keyword is needed. Then add the component for export inside of the index.ts like this:

import TestComponent from './components/TestComponent.vue';

export default {
    install: (app: any) => {
        app.component("TestComponent", TestComponent);
    }
};

export {
  TestComponent
};

Utils / Hooks / Functions

Create a new file with the desired functions, variables and structures. Then add the keyword export, to make clear what you want to export:

export const testFunction = () => { 
    return "This is a test."; 
}

To make it accessible from outside, you have to add another export inside of the index.ts as following:

export { testFunction } from './utils/testFunction';

NOTE: As there is already a default export, only named exports are allowed here!

Local Testing

If you want to test the package locally without publishing it to the npm registry, you can create a link to this project. Inside of this library type in the following command:

npm link

Now create a new Vue project and inside of it, then link the package with the following command:

npm link @t-systems-innovation-lab/mvp-library

This has to be done once. Every time there is a change in the library, it is automatically applied to the test project.

📖 Storybook

Whenever you make changes to the storybook and want to rebuild the files, then you have to execute the following command:

npm run build-storybook

To run the storybook application run this command:

npm run storybook

Creating a stories file

In order to get a preview of a component and its properties, storybook is used. It provides an overview of all components and thus enables the developer to have a uniform presentation. Each component has to be added manually inside of the .storybook/stories folder, following the naming convention: componentname.stories.js. To avoid having to do everything from scratch, existing stories can serve as templates. It can be copied and edited to suit your needs.

Configure the stories file

Title and argtypes

The title of the default export object speficies the path of the component shown on the application.

The argtypes of the default export object are used to specify the possible inputs for the properties. For simple property types like string, number and boolean (without constraints), storybook will recognize it automatically. But for more complex types, like a selection of a few string values you have to define an argtype which contains the specific constraints.

import LoadingButton from '../../src/components/LoadingButton.vue';

export default {
  title: 'Example/LoadingButton',
  component: LoadingButton,
  argTypes: {
    size: {
      control: { type: 'select' },
      options: ['small', 'large'],
    },
    variant: {
        control: { type: 'select' },
        options: ['primary', 'secondary'],
      },
  },
};

Template

Make sure you also have adapted the appropriate component name in the template of the Template function. There you can specify the HTML which will be rendered by default. The v-bind="args" is necessary to bind the properties which can define (see next step).

Property definition

You will now use the Template to create specific characteristics of your component. The name of the exported function object will be displayed in the storybook. The args of the function object which you specify below will be applied to your component when opening that specific story.

const Template = (args) => ({
  // Components used in your story `template` are defined in the `components` object
  components: { LoadingButton },
  // The story's `args` need to be mapped into the template through the `setup()` method
  setup() {
    return { args };
  },
  // And then the `args` are bound to your component with `v-bind="args"`
  template: '<LoadingButton v-bind="args" />', //make sure you adapt the right component in this template to.
});

export const Loading = Template.bind({}); //First shape of your component will be called "Loading" and has the property loading="true".
Loading.args = {
  loading: true,
};

export const NotLoading = Template.bind({});//First shape of your component will be called "Loading" and has the property loading="false".
NotLoading.args = {
    loading: false,
};

Each story contains all the controls to adjust the properties and change a component, yet each core function should be included as a separate story. This way many different states of the component can be seen right away, without changing any properties.

🤖 CI/CD Pipeline

When pushing your changes to GITLAB, it will automatically build the project and publish it to the npm registry.

Additionally the storybook will be published to a public github page which is available via following link: https://t-systems-innovation-lab.github.io/

IMPORTANT: The pipeline is only executed on the master branch. Also, it is important to manually adjust the version in the package.json. Otherwise, the pipeline will fail and the new version will not be published on the npm registry.

Licensing

Please note that the use of the Telekom brand and design assets – including but not limited to the logos, the color magenta, the typeface and icons, as well as the footer and header components – are not available for free use and require Deutsche Telekom's express permission for use in commerce.

Licensed under the Mozilla Public License 2.0 (MPL-2.0) (the "License"); you may not use this file except in compliance with the License.

You may obtain a copy of the License by reviewing the file LICENSE in the repository.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the LICENSE for the specific language governing permissions and limitations under the License.

Contributing

We always welcome and encourage contributions and your feedback. For more information on how to contribute please get in touch with one of our developers via email.