@skf-aurora/ui-components

SKF UI Components

MS Teams | Storybook Beta | Report Issues

Introduction

The SKF UI Library is a collection of components that is meant to visually align and facilitate the creation of web applications across the global SKF organization. Using the SKF UI Library will give apps an SKF look and feel, and will let users focus on building business logic and features, instead of worrying about the basics.

---

🔵 If you just want to get a grasp what the components are, please feel free to browse our component docs! 🔵

---

The SKF UI Library is created using Lit/native web components in order to support as many frameworks as possible. It works out of the box for all frameworks, including React >= 19.

🏃 Getting started

Let's go!

SSO Account

You need a single sign on account (SSO) in the Enterprise organization. If you don't already have an account you need to ask IT for one. Once received you can get to the github page.

SKF-email

You need a valid SKF-email ending with @skf.com as your primary GitHub-email to be able to clone and install this repo.

🙋‍♀️ But I am a consultant outside SKF domain without SKF email?

.npmrc

Since we aren't hosted in the public npm repo you need to start by adding an .npmrc file to your home folder (~/ on Linux+Mac or C:/Users/<username> on Windows) containing the following:

@skf-internal:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=<github-authtoken>

Notice the '<github-authtoken>' part at the end. This should be replaced with a valid GitHub access token which can be generated here: https://github.com/settings/tokens.

Instructions on generating a personal access token

1. Go to https://github.com/settings/tokens

2. Press the 'Generate new token' button (classic)

3. Write something under 'Note'. For example: SKFUiLibrary

4. Check the box below that says 'read:packages'

5. Click the green 'Generate token' button

6. Copy the token that should now be visible to you. This page will only be visible ONCE so make sure you copied it correctly

7. Make sure the Configure SSO dropdown has a "deauthorize" button on the lower right, otherwise click authorize.

   

8. Replace the '<github-authtoken>' part in your .npmrc file

9. Make sure to add .npmrc to .gitignore. This should not be checked into your repository, since it would be a security hazard.

Install using NPM

npm install @skf-internal/ui-components

Install using pnpm

pnpm add @skf-internal/ui-components

Install using Yarn

yarn add @skf-internal/ui-components

Start using!

How you get started using our components is of course a bit different depending on which framework or library you are using for your application. We will proceed to explain how you get going with the most common options on SKF.

Bootstraping CSS

In order for our components to work as intended you need to import our global styles where appropiate e.g. App.tsx.

import '@skf-internal/ui-components/styles/global.css';

Angular

In order for our components to get the correct styling you need add our global styling to your project. In angular you can do that in the angular.json like this:

// angular.json
{
...
"architect": {
   "build": {
      "options": {
         "styles": [
            "src/styles.css",
            "node_modules/@skf-internal/ui-components/dist/styles/global.css"
         ],
         ...
      }
   }
}}

After that, you import the specific component you want to use in your file and make an instance. You can choose to import all ui components by adding import '@skf-internal/ui-components' or a specific component by importing import '@skf-internal/ui-components/components/loader/loader.js';. It might look like this in angular:

// app.components.ts
import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import { RouterOutlet } from '@angular/router';
import '@skf-internal/ui-components/styles/global.css';
import '@skf-internal/ui-components';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [RouterOutlet],
  templateUrl: './app.component.html',
  styleUrl: './app.component.css',
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})

export class AppComponent {
  title = 'test-components-in-angular';
}

// app.component.html
<main class="main">
  <div class="content">
    <div class="left-side">
      <h1>Hello, {{ title }}</h1>
      <p>Congratulations! Your app is running. 🎉</p>
      <skf-loader></skf-loader>
    </div>
  </div>
</main>
<router-outlet />

React 19 beta / Next 15 beta

Web Components will become first class citizens in React 19. Should you want to use them in a version prior to 19 you have to wrap them in React, which essentially converts the native event to React Syntactic events. Long story short, use React 19 (when released) and your off the hook.

If you want to proceed to use the React 19 beta together with typescript, see React 19 RC upgrade guide.

You will also have to declare a global type for the web components to get it to play nice with JSX.

1. Create a definition file called custom-elements-types.d.ts as:

import type { CustomElements } from './node_modules/@skf-internal/ui-components/dist/types/jsx/custom-element-jsx';

declare global {
	namespace React.JSX {
		interface IntrinsicElements extends CustomElements {}
	}
}

2. include it in tsconfig.json:

{
  "compilerOptions": {
   ...
  },
  "include": [ ... , "custom-elements-types.d.ts"],
}

// MySkfCardLoader.tsx
// Example react component, no need for imports of web components here as they are defined at run time.

export const MySkfCardLoader = () => {
   return (
      <>
         <skf-card>
            <p>A loading card</p>
            <skf-loader></skf-loader>
         </skf-card>
      </>
   )
}

Events and EventTarget

Events and EventTarget should be casted as below

<skf-input
	name="input"
	onchange={(e) => console.log((e.target as HTMLInputElement).value)}
></skf-input>

or if you want all on the SkfElement

import { SkfInput } from "@skf-internal/ui-components";

...

<skf-input name="input" onchange={(e) => console.log((e.target as unknown as SkfInput).value)}></skf-input>

React 18

Note, for React 18 it is not necessary to install an extra plugin to get code completion since you are writing in react

React 18 does not support native web components out of the box. If you want to use SKF UI components with React 18 you will have to use our generated wrappers in order to do so.

import { SkfInput } from "@skf-internal/ui-components/react/index.js";

...

<SkfInput
  name="input"
  onChange={(e) => {
    console.log( e.target.value );
  }}
/>

Setting up code completion

Web components don't get code completion by default, but have no fear! You can install an extension for VScode in order for it to interpret SKF ui components. Please install Custom Elements Language Server if this is something that you want 💁🏼‍♀️. If you are using another IDE, we're sure that there might be similar plugins for you to use too!

VS Code

ui-components ships with a file called vscode.html-custom-data.json that can be used to describe it’s custom elements to Visual Studio Code. This enables code completion for ui-components components (also known as “code hinting” or “IntelliSense”). To enable it, you need to tell VS Code where the file is.

1. Install ui-components locally
2. If it doesn’t already exist, create a folder called .vscode at the root of your project
3. If it doesn’t already exist, create a file inside that folder called settings.json
4. Add the following to the file

{
  "html.customData": ["./node_modules/@skf-internal/ui-components/dist/vscode.html-custom-data.json"]
}

If settings.json already exists, simply add the above line to the root of the object. Note that you may need to restart VS Code for the changes to take effect.

JetBrains IDEs

If you are using a JetBrains IDE and you are installing ui-components from NPM, the editor will automatically detect the web-types.json file from the package and you should immediately see component information in your editor.

If you are installing from the CDN, you can download a local copy and add it to the root of your project. Be sure to add a reference to the web-types.json file in your package.json in order for your editor to properly detect it.

{
  ...
  "web-types": "./web-types.json"
  ...
}

If you are using types from multiple projects, you can add an array of references.

{
  ...
  "web-types": [
    ...,
    "./web-types.json"
  ]
  ...
}

Other Editors

Most popular editors support custom code completion with a bit of configuration. Please submit a feature request for your editor of choice. PRs are also welcome!

⚙️ Installation on build servers

If you use the component library in your CI/CD using a Azure pipeline or Github actions, you will need to authenticate there as well.

SKF UI Library Machine User

For your CI/CD we have a machine user, specifically set up for this scenario. This user has an access token that you can put on your server as a secret environment variable, and then use in your CI/CD script. Contact the ui library team in our Teams channel to get hold of this token.

Access token and environments

Ensure that the correct access token is used in corresponding environment. I.e - personal access token in your local environment and machine user token in CI/CD build pipeline.

Using UI components in your CI/CD pipeline

Every pipeline is different, but we assume that you are using GitHub since that is the standard for SKF. In order to authenticate on the server to install this dependency, you need to add the machine user token to a secret in your repo and then use it in your workflow file. It could look something like this:

// workflows/deploy.yaml
---
steps:
  - name: Install dependencies
    run: npm install
    env:
      NODE_AUTH_TOKEN: ${{ secrets.<ACCESS_TOKEN_SECRET> }} # <-- Provided by team Aurora, authors of ui-components

In this example a token has been added with the name ACCESS_TOKEN_SECRET, but you can give it any name you like ✨. If you want to know more about secret generation and usage you can read more about it in GitHub's docs.

🛠️ Troubleshooting

🙋‍♀️ But I am a consultant outside the SKF domain without SKF email?

Contact us and let's see what solution suit you best.

🙋‍♀️ I get a 404 when I try to reach the GitHub page/install package

You do not have github access.

Checklist:

• Do you have an SKF email address? If not contact your manager/SKF contact.
• Do you have SSO enabled? If not contact IT.
• Do you have access to GitHub on your SKF account? Contact IT and make sure your account have access to the Enterprise Organization.

📖 Further reading

🎁 Contributing

Would you like to contribute to the ui components library? That is awesome! Thank you for wanting to be part of our community. We have a few guidelines so please make sure to check out our contribution-documentation 🎉

👯 Apply for Github access on behalf of a friend

You obviously have access already, but you can apply for Github on behalf of a friend if you need or want to 🙏

🧑‍⚖️ License

Copyright SKF 2024