@temporg/ui-component-examples

---

category: packages

ui-component-examples

     

A utility for automatically generating component examples.

Installation

yarn add @temporg/ui-component-examples

Usage

Using the webpack loader

For convenience, this package contains a webpack loader which can be used to load example configuration files. In the loader, each configuration file is passed to the generateComponentExamples function to generate examples.

In your webpack.config.js:

module.exports = {
  module: {
    rules: [
      {
        test: /\.js$/,
        include: [/\.examples\.js/],
        use: [
          'component-examples-loader',
          'babel-loader'
        ]
      }
    ]
  }
}

Calling the generateComponentExamples function directly

The generateComponentExamples function can be called directly as follows:

import generateComponentExamples from '@temporg/ui-component-examples'

const result = generateComponentExamples(config)

Given a configuration object, generateComponentExamples returns an array of generated examples:

Parameters

Param	Type	Default	Description
config	Object	undefined	the generator config object. See config section below for more details

Returns

Type	Description
Array	array of examples broken into sections and pages if configured to do so. See examples section for more details

Example config

export default {
 sectionProp: 'variant',
 maxExamplesPerPage: 50,
 maxExamples: 200,
 propValues: {
   variant: ['circular', 'rectangular'],
   placement: ['top', 'bottom', 'start', 'end'],
   children: [null, <button>hello</button>, <a href="#">world</a>]
 },
 getComponentProps: (props) => ({
   size: props.variant === 'circular' ? 'large' : 'small'
 }),
 getExampleProps: (props) => ({
   height: props.placement === 'top' ? '50rem' : '10rem'
 }),
 renderExample: ({ Component, componentProps, exampleProps, key }) => {
   return <View key={key} {...exampleProps}><Component {...componentProps} /></View>
 },
 renderPage: ({ examples, key, renderExample }) => {
   return <View key={key}>{examples.map(renderExample)}</View>
 },
 getParameters: ({ examples, index}) {
   return { delay: 200, viewports: [320, 1200] }
 }
}

The config is an object that sets the configuration for the example generation. It has the following properties:

sectionProp

A string value used to divide the resulting examples into sections. It should correspond to an enumerated prop in the Component

Type	Default
string	undefined

maxExamplesPerPage

Specifies the max number of examples that can exist in a single page within a section

Type	Default
number or function	null

// providing a number
maxExamplesPerPage: 50

// providing a function
maxExamplesPerPage: (sectionName) => sectionName === 'inverse' ? 20 : 50

Parameters

Param	Type	Default	Description
sectionName	string	undefined	the name of the current example section

Returns

Type	Description
number	a number specifying the maximum examples per page

maxExamples

Specifies the total max number of examples

Type	Default
number	500

propValues

An object with keys that correspond to the component props. Each key has a corresponding value array. This array contains possible values for that prop.

To avoid having to manually write out every possible value for all props in each example config, we have tools available to facilitate parsing boolean and enumerated prop values. See the README for @temporg/ui-component-examples for documentation and example usage.

Type	Default
object of keys corresponding to arrays of possible values	undefined

propValues: {
 variant: ['circular', 'rectangular'],
 placement: ['top', 'bottom', 'start', 'end'],
 children: [null, <button>hello</button>, <a href="#">world</a>]
}

getComponentProps

A function called with the prop combination for the current example. It returns an object of props that will be passed into the renderExample function as componentProps.

Type	Default
function	undefined

getComponentProps: (props) => ({
 // Change the size prop passed to the component based on the value of
 // `variant` in the current prop combination
 size: props.variant === 'circular' ? 'large' : 'small'
})

Parameters

Param	Type	Default	Description
props	Object	undefined	the prop combination for the current example

Returns

Type	Description
Object	a props object that will be passed to the renderExample function as componentProps

getExampleProps

A function called with the prop combination for the current example. It returns an object of props that will be passed into the renderExample function as exampleProps.

Type	Default
function	undefined

getExampleProps: (props) => ({
 // Change the height prop passed to the example based on the value of
 // `placement` in the current prop combination
 height: props.placement === 'top' ? '50rem' : '10rem'
})

Parameters

Param	Type	Default	Description
props	Object	undefined	the prop combination for the current example

Returns

Type	Description
Object	a props object that will be passed to the renderExample function as exampleProps

renderExample

A optional function which receives the component and example props and returns an example.

renderExample: ({ Component, componentProps, exampleProps, key }) => {
 return <View key={key} {...exampleProps}><Component {...componentProps} /></View>
}

Parameters

The parameters consist of an object with the following properties

Param	Type	Default	Description
Component	ReactComponent	undefined	the component to render
componentProps	Object	undefined	props corresponding to the component. The result of the getComponentProps method
exampleProps	Object	undefined	props corresponding to the example. The result of the getExampleProps method
key	string	undefined	a unique key generated for each example

Returns

Type	Description
ReactComponent	the rendered example

renderPage

An optional function which receives an array of examples and a function to render them.

renderPage: ({ examples, renderExample }) => {
 return <View margin="small">{ examples.map(renderExample) }</View>
}

Parameters

The parameters consist of an object with the following properties

Param	Type	Default	Description
examples	Array	undefined	array of example objects with properties identical to those outlined in the renderExample params
renderExample	function	Identical to the default in the renderExample section	The render method for each component example

Returns

Type	Description
ReactComponent	the rendered page of examples

getParameters

A function called with the examples and index for the current page of examples. It returns an object of parameters/meta data for that page of examples (e.g. to be passed in to a visual regression tool like chromatic).

Type	Default
function	undefined

getParameters: ({ examples, index }) => ({
  // add a delay for the first page of examples only:
  index === 1 ? { delay: 200 } : {}
})

Parameters

Param	Type	Default	Description
props	Object	undefined	the examples and index of the current page

Returns

Type	Description
Object	a parameters object with delay and viewport sizes configuration for the page