@businessoptics/frontend-library

BusinessOptics Frontend Library

This library consists of modern and useful reusable components for React based BusinessOptics apps. It works best with apps that have been built using create-react-app version 2+. It consists of three primary sections:

• Small but useful utilities
• A resusable component library
• SCSS based theme components

All modern BusinessOptics apps should use it, and abstract any common functionality to it. The library is a little disorganised right now, but we will strive to keep the external interfaces reasonably stable.

Usage

the library can be installed with npm straight off Github assuming you have the correct permissions, via:

npm install @businessoptics/frontend-library

Development usage

Use npm link to make devlopment usage easier (this is probably mandatory for now). This allows changes you make to automatically be picked up by projects using it on your local development machine.

1. git clone the library

2. Navigate to the root folder

3. Run npm link (you may have to sudo)

4. Run npm run build:watch (this will automatically build the library when you make changes)

5. Navigate to a project that is using the library (and already has it installed)

6. Run npm link @businessoptics/frontend-library

7. Run npm start

Now if you make a change in this library, the application using it should automatically update, making for a great development cycle.

You will have to rerun the second part of the steps when you run npm install in an application.

Components

Utilities

These can be imported directly form the root module. They include a small set of helpers particularly useful for dealing with redux stores, without heavy weight dependencies like immutable.js.

Immutability helpers

These all work off iupdate

• root is a nested object
• path is an array of strings/numbers, or a single item
• updateFn is a function that takes a single value and returns the value to replace it with

/* Given a nested data structure this will follow the path, and replace
 * the item at the end of the path with the result of calling the updateFn on it.
 * */
export const iupdate = (root, path, updateFn) => ..

/* Given a nested data structure this will follow the path, and replace
 *  the item at the end of the path with the value.
 */
export const iset = (root, path, value) => iupdate(root, path, () => value);

/* Given a nested data structure this will follow the path, and add the
 * given value to the end of the array at that path.
 */
export const ipush = (root, path, value) =>
  iupdate(root, path, list => list.concat([value]));

/* Given a nested data structure this will follow the path, and remove the
 * given idex in the array at that path
 */
export const iremove = (root, path, index) =>
  iupdate(root, path, list => [
    ...list.slice(0, index),
    ...list.slice(index + 1)
  ]);

Other useful helpers can be found in utilities.js.

General Input Component

The <Input/> component is a generalised input component that deals with many edge cases around the traditional inputs and has a unified styling system. Primarily it accepts a type prop which defines the data type (and default widget), and an optional widget prop which customises what widget is used. These are meant to be used as controlled components. The options are

• type: text, number, currency, boolean
• widget: text, number, currency, checkbox, toggle, select, radiogroup, radiogroup-vertical

Obviously only some types can support some widgets, use common sense. Null is correctly supported and the value is always of the correct type.

The input takes an onChange(value) event handler which is given the value of the control of the correct type.

Other props include:

• value: The value
• disabled: Disable the input
• choices: a list of {value, label} pairs for use by select, radiogroup, radiogroup-vertical.
• Other props are passed directly to the implementing component, look at the code for more details.

Additionally there is a list widget which takes a list of objects as it's value, and required a list of field definitions, which are props for the various columns field types.

SCSS based mixins

These assume a create-react-app v2+ is using the library. The scss can be included through:

@import "~@businessoptics/frontend-library/css/mixins.scss";

The following mixins are available.

// Only style the <Input/> component from this library
@include businessoptics-input-components($primaryColor, $secondaryColor);

//Applies styling to standard input components (to teh degree possible)
@include standard-input-components($primaryColor, $secondaryColor);

//Decent stying for tables with className="data-table"
@include data-tables($primaryColor, $secondaryColor);

//Some decent typography defaults
@include businessoptics-typography;

//A set of utility classes, this includes the whole of basscss, a small but useful library
//See utitily mixins for additional utility classes
@include utility-classes($primaryColor, $secondaryColor);