@sat-valorisation/ui-components

Library of React components for telepresence projects

Usage no npm install needed!

<script type="module">
  import satValorisationUiComponents from 'https://cdn.skypack.dev/@sat-valorisation/ui-components';
</script>

README

@sat-valorisation/ui-components

npm (tag) pipeline status coverage report

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-valorisation/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-valorisation/ui-components'

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

/* Each component is scoped */
import { Inputs } from '@sat-valorisation/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-valorisation/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-valorisation/ui-components'
    }])
  ]
}

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 and Exo2 are bundled with the ui-components. According to their respective licence, each one is re-bundled :

Acknowledgments

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