@sat-mtl/ui-components

UI Components is a (WIP) library of React components meant to be used in telepresence projects currently developed by the Société des Arts Technologiques [SAT], a non-profit artistic entity based in Montreal, Canada.

See the living style guide environment in order to try, test and develop your own components.

Install from NPM

>> npm i @sat-mtl/ui-components

Bootstrap a development environment

A nix-shell script may be used to bootstrap a development environment. It uses the Nix Package Manager and provides every tool required to contribute to this project.

>> nix-shell
Development environment with NodeJS v12.16.1 is ready!

Usage

Import JS components

All components are available inside the UIComponents object. Each of the common components are directly exported at root and each scoped component can be imported from their respective objects (ex: Inputs, Context...) For CommonJS imports, you must import each component separately.

/* All components can be imported once */
import UIComponents from '@sat-mtl/ui-components'

const {
  Common: {
    Button,
    Icon,
    Menu,
    NavBar,
    Preview,
    Spinner
  },
  Context: {
    ThemeProvider,
    ThemeContext
  },
  Feedback: {
    Drawer,
    Modal
  },
  Inputs: {
    Checkbox,
    FormGroup,
    InputNumber,
    InputText,
    InputSelect,
    Select,
    Slider,
    Switch
  },
  Layout: {
    Cell,
    FlexBox,
    FlexColumn,
    FlexRow
  },
  Shared: {
    ColumnHead,
    ColumnSeparator,
    ConnectionCell,
    RowHead,
    SceneCell,
    ShmdataCell,
    VersionSection
  }
} = UIComponents

/* Each component is scoped */
import { Inputs } from '@sat-mtl/ui-components'

const { InputText } = Inputs

Import SCSS styles

The current components are optimized with Webpack. It is highly recommended to use it with its style-loader. After installing these dependencies, use the embedded styles by importing them at the root of your development directory :

import '@sat-mtl/ui-components/dist/ui-components.css'

Use SCSS themes

All SCSS styles are loaded with a theme map (currently only one theme is being developed). Themes should be used with the ThemeContext and the ThemeProvider components.

import React, { Component } from 'react'
import 'my-styles.scss'
import { Context } from '@sat-valorisation/ui-components'

const { ThemeProvider, ThemeContext } = Context

class MyComponent extends Component {
  static contextType = ThemeContext

  render () {
    return (
      <div className={`my-component-${this.context}`} />
    )
  }
}

ReactDOM.render((
  <ThemeProvider value='simon'>
    <MyComponent>
  </ThemeProvider>
), document.getElementById('my-component-example'))

The below JS script needs an HTML wrapper with a tag exposing the my-component-example ID. It also depends on the styles defined in my-styles.scss. These styles expose the ui-components themes by using the themify SCSS function:

@import '@ui-components/assets/themes/themify.utils.scss';
@import '@ui-components/assets/themes/theme.simon.scss';

$themes: (
  simon: $simon
);

@include themify('my-component', $themes) {
  & {
    font-family: themed('font-family');
    color: themed('text-primary');
    background-color: themed('background');
  }
}

Use assets

The assets are imported into the @sat/ui-components package. You'll need to copy the assets into your build folder in order to use them. To easily resolve this issue, use the copy-webpack-plugin in your Webpack configuration :

const Copy = require('copy-webpack-plugin')

module.exports = {
  plugins: [
    new Copy([{
      from: 'assets',
      to: 'assets',
      context: 'node_modules/@sat-mtl/ui-components'
    }])
  ]
}

Scale the element sizes with rem values

For components that are styled using rem units, a change in the font size of the root element will allow the resizing of those components in a way so as to preserve their shape. A root font size of 100% sets it to the default text size of 16px in browsers. If the user wants to set the root font size to 10px for example, they can add the following code to their html styles (In this case, 1rem would be equivalent to 10px):

html {
  font-size: 62.5%;
}

Contributing

Check out our Contributing Guide to get started!

A nix shell environment is set in order to automatize the development setup. You can use it by installing nix and by inputing nix-shell in your terminal at the root of the project.

Versioning

SemVer is used for versioning. For the versions available, see the tags on this repository.

Authors

See here.

Licenses

This project is licensed under the MIT License.

Otherwise the font families Inter, Exo2 and Roboto are bundled with the ui-components. According to their respective licence, each one is re-bundled :

• Exo2
• Inter
• [Roboto](assets/fonts/Roboto/Apache License.txt)

Acknowledgments

This project was made possible by the Société des Arts Technologiques [SAT].