@sama/ui-library

This library was generated with Angular CLI version 15.2.5 and migrated to nx.

Prerequisites

- [node](https://nodejs.org/)
- [npm](https://www.npmjs.com/) (Included with node)
- [git](https://git-scm.com/)
Copy

Install Gemfury dependencies

This library is published to Gemfury so, to be able to use this library in your project you need to make sure that npm can get Sama packages from their package repository. To do this, you'll need to add a .npmrc to the root folder of your project with the following contents:

; Set a new registry for sama packages
@sama:registry=https://npm-proxy.fury.io/samasource/
Copy

In our CI/CD pipeline, npm uses the .npmrc file located in ./ci that contains the registry pointing to Gemfury proxy.

Download and Install

Run the following in the terminal:

- npm install @sama/ui-library
Copy

How can I use the @sama/ui-library?

Storybook showcase

How can I use @sama/ui-library theming?

• On your styles.scss (or any globally imported scss file) add

  @import '@sama/ui-library/styles/external/m3-sama-theme';

  html {
    @include mat.all-component-themes($sama-light-theme);
    @include mat.color-variants-backwards-compatibility($sama-light-theme);
    @include mat.typography-hierarchy($sama-light-theme, $back-compat: true);
    @include mat.system-level-colors($sama-light-theme);
    @include mat.system-level-typography($sama-light-theme);
  }
Copy

Design Tokens

• The support to access the tokens thought ui-library will be deprecate soon. The suggestion is to start to using design-token library instead.

• To import style Token variables into your .scss just include the following line of code @import '@sama/ui-library/variables/scss/{resource-name}';

Resource Name	Documentation
border-radius
border-widths
colors	colors
font-families
font-sizes
font-weights
letter-spacing
line-heights
sizing
spacing

• To import styles classes resources into your .scss just include the following line of code @import '@sama/ui-library/classes/scss/{resource-name}';.

Resource Name	Documentation
box-shadows
typographies	typographies

• To import js Token variables into your .js just include the following line of code @import {variable} '@sama/ui-library/styles';

Running unit tests

Run nx test ui-library to execute the unit tests via Karma.

Create a component with code scaffolding

• Open your terminal
• Go to the project library e.g project/ui-library
• Run

nx g m component-name
nx g c component-name
Copy

Here the snippet code for module file.

import { component-name } from './component-name.component';
@NgModule({
declarations: [component-name],
exports: [component-name]
})
Copy

The building and blocks library was built using subentries. It means your must include the following extra files by component.

• The index.ts is just there to point to the public-api which is helpful during imports.
• The public-api.ts exports all the modules and components from our module.
• The ng-package.json contains ng-packagr-specific configurations. It’s enough to specify the entryFile.

Example folder layout for each component.

component-name
├── src
|   ├── x.component.css
|   └── *.component.html
|   └── *.component.ts
|   └── *.component.spec.ts
|   └── *.harness.ts
|   └── *.module.ts
├── ng-package.json
├── index.ts
└── public_api.ts
Copy

Here the snippet code by each file.

• index.ts

export * from './public-api';
Copy

• ng-package.json

{
  "lib": {
    "entryFile": "public-api.ts"
  }
}
Copy

• public-api.ts

export * from './component-name.component';
export * from './component-name.module';
Copy

• Register the component into the library public-api.ts principal entry file.
• Run npm run format
• Run nx build ui-library
• Register the new component into Storybook

Note:

• Any UMD libraries used by a component must be include into the library package.json into the peerDependencies node.