ODA 2 common UI library

This repository contains common UI components for ODA-applications, created with React and styled-components. This repository also acts as a living style guide for the ODA project.

Key technologies

Here are the key libraries used in the project.

Library	Description
react	UI-component library
styled-components	React primitives
storybook	A UI to preview the components

Usage

Installation from NPM

Install the latest version of oda-ui-common as a dependency to your project by running:

npm install @omahoito/oda-ui-common

Theming

oda-ui-common components require a wrapping ThemeProvider-component, to inject theming-related props to the UI-components. A ThemeProvider passes theme properties to their children UI-components (all children, not just direct children).

You can have as many ThemeProviders in your application as you want, but you should probably have one at the top-level of your app. By default, ThemeProvider uses the default theme bundled with the app, but you can also pass a custom theme, which is just an object.

If you want to create your own themes, you can use oda-ui-common/src/themes/defaultTheme.js as your basis.

Here is an example of using the themeProvider with the default theme:

import React from 'react'
import {render} from 'react-dom'
import {ThemeProvider, P} from '@omahoito/oda-ui-common'

render(
    <ThemeProvider>
        <P>Hello, world!</P>
    </ThemeProvider>,
    document.querySelector('#app')
)

And here with a custom theme:

import React from 'react'
import {render} from 'react-dom'
import {ThemeProvider, P, defaultTheme} from '@omahoito/oda-ui-common'

const customTheme = {
    ...defaultTheme:
    myCustomComponent: {
        text: 'pink'
    }
}

render(
    <ThemeProvider theme={customTheme}>
        <P>Hello, world!</P>
    </ThemeProvider>,
    document.querySelector('#app')
)

Recommended global styles

While the vast majority of styles in this repository are self contained, some styles are intentionally left out of repository, such as fonts and normalizations.

We recommend the following global styles to be used with the defaultTheme:

*, *::before, *::after {
  box-sizing: border-box;
}

body {
  font-family: 'Gill Sans', sans-serif;
  font-size: 16px;
  font-weight: normal;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
}

Using normalize.css or equivalent is also highly recommended.

Fonts

We recommend the font Gill Sans to be used with the default theme. This font is not included in the package, and it must be downloaded and licensed separately.

These are the font-weight mappings used in oda-web-front:

Font-weight	Font
300	Gill Sans Light
500 / normal	Gill Sans Book
700 / bold	Gill Sans Medium

Local installation

If you want to contribute to oda-ui-common, you should clone the repository and compile the components locally.

Node.js is needed to run the front-end build. You can download it from here. Version 8.0.0 or above is recommended.

All project dependencies are listed in package.json. To install them you need NPM (installed automatically with Node.js).

Once you have installed Node.js, run this command in the root folder (the one that contains file package.json) of the project to install project's dependencies:

npm install

Some dependencies are marked as peer dependencies. These need to be installed separately. You can either install each one or use a utility, like npm-install-peers:

npm install -g npm-install-peers
npm-install-peers

Building the project

To build the project run

npm run build

Storybook

To launch the style guide UI locally, run

npm run storybook

This will start a local server on port 6006.

Other scripts

All of these scripts can be run with "npm run [script name]"

Script	Description
lint	Runs eslint linter (see .eslinrc.json for linting settings)
clean	Removes dist/-folder
start	Runs babel build in watch-mode
deploy-storybook	Push master to gh-pages branch

Contributing to the project

Guidelines

1. Follow atomic web design principles
2. All inputs should be controlled components
3. Avoid writing stateful components

Folder structure

Folder	Description
/	Project root, build configuration files
/src	Application source codes
/src/atoms	Primitive components
/src/atoms/[type]	Atomic components of similar type (e.g. "button")
/src/molecules/	Components, combinations of atoms
/src/molecules/[type]	Molecular components of similar type (e.g. "form")
/src/themes	Default theme and themeProvider-component

Naming conventions

Here is an example of file naming conventions. For example, the contents of an imaginary /src/atoms/button -folder might look like this

File	Description
buttonWithIcon.js	Exports ButtonWithIcon-component as default
bigRoundButton.js	Exports BigRoundButton-component as default
button.story.js	Story file for the components of this folder
index.js	Exports ButtonWithIcon and BigRoundButton as named exports

Publishing to NPM

To publish the package to NPM, you must be a member of the Omahoito-organization in NPM.

If you already are a member of the organization, you can publish the package using these commands:

npm version patch
npm publish
git push

NPM version patch will increase the version and automatically create a Git-tag for the new version. The tag should be pushed to git after a succesful publish.

Versioning

Versioning follows SemVer guidelines.