MCF-Components

A component library based on React and Material-UI that lets you build complete interfaces from plain JavaScript objects, with no need to write JSX by hand.

Define your UI as data (JSON/objects), pass that definition to the library, and get the corresponding React components rendered to the DOM.

Table of contents

• Features
• Requirements
• Installation
• Quick start
• Architecture
• Available components
• Development environment
• Roadmap
• Contributing
• License

Features

• Declarative rendering of Material-UI components from a JSON configuration.
• Recursive composition of nested components (cards, dialogs, etc.).
• Minimal API: render and remove.
• Bundled as a UMD library, usable both in bundler-based projects and directly in the browser.

Requirements

• Node.js v12.13.1 (see .nvmrc)
• react and react-dom ^17.0.2 as peer dependencies in the host project

Installation

npm install mcf-components

If the package isn't published to the npm registry, you can install it directly from the GitHub repository:

npm install github:DausdasKreuz/mcf-components

Quick start

<div id="app"></div>

import { render, remove } from 'mcf-components'

const scheme = {
  type: 'card',
  params: {
    id: 'welcome-card',
    mainText: 'Card title',
    secondaryText: 'Secondary text',
    contents: [
      {
        type: 'text',
        params: {
          id: 'name',
          label: 'Name',
          variant: 'outlined',
          onChangeListener: (value, setError) => {
            setError(value.length === 0)
          },
        },
      },
      {
        type: 'button',
        params: {
          id: 'submit',
          text: 'Submit',
          color: 'primary',
          variant: 'contained',
          onClickListener: () => console.log('Form submitted'),
        },
      },
    ],
  },
}

// Renders the scheme inside the node with id="app"
render(scheme, 'app')

// Unmounts the components rendered on that node
remove('app')

Architecture

The source code lives in src/:

• index.js: the library's entry point. Exposes the public methods render and remove, along with the shared styles (useStyles) used by the components.
• ComponentFactory.js: a factory that, based on the type field of each configuration node, instantiates the corresponding React component. It walks the definition recursively to build trees of nested components.
• components/: individual implementation of each supported component (one per file).

Definition format

Each configuration node follows this shape:

{
  type: 'text' | 'button' | 'card' | ..., // see components table
  params: {
    id: 'unique-id',
    // ...remaining component-specific properties
  },
}

Components that support children (e.g. card, mediaCard, or dialog) receive them in params.contents, as an array of nodes following the same format.

Available components

type	Component	Based on
autocomplete	MCF_Autocomplete	react-select
button	MCF_Button	@material-ui/core/Button
card	MCF_Card	@material-ui/core/Card
checkbox	MCF_Checkbox	@material-ui/core/Checkbox
checkboxesGroup	MCF_CheckboxesGroup	@material-ui/core/Checkbox
dialog	MCF_Dialog	@material-ui/core/Dialog
divider	MCF_Divider	@material-ui/core/Divider
fileUpload	MCF_FileUpload	@material-ui/core/Button
mediaCard	MCF_MediaCard	@material-ui/core/Card
select	MCF_Select	@material-ui/core/Select
text	MCF_Text	@material-ui/core/TextField

The props supported by each component are documented as inline comments next to each prop in its corresponding file under src/components/. Some examples:

• text: label, value, placeholder, helperText, required, disabled, error, fullWidth, variant, type, onChangeListener.
• button: text, color, size, variant, disabled, onClickListener.
• select / autocomplete: options, value, label, onChangeListener / onSelectListener.
• dialog: openButtonText, titleText, contentText, actionContents, closeListener, openListener.
• fileUpload: url, token, storagePath, acceptedFormats, onUpload, onError.

Development environment

• Transpilation: Babel (.babelrc)
• Bundling: Webpack, with separate configs for development (webpack.dev.js) and production (webpack.prod.js), both extending webpack.common.js
• Linting: ESLint (.eslintrc.js)
• Testing: Jest

To spin up a local development environment:

npm install
npx webpack serve --config webpack.dev.js

Roadmap

Known pending items for the project (see src/index.js):

• Built-in state management.
• createSelectFromDictionary and createCheckboxGroupFromDictionary helper functions.
• A function to update an attribute of a component given its id.
• A function to look up an MCF component given its id.

Contributing

Issues and pull requests are welcome.

License

This project is under Apache Licence