@rock-kit/ui-component-examples v0.1.1

category: packages

ui-component-examples

A utility for automatically generating component examples.

Installation

yarn add @rock-kit/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 '@rock-kit/ui-component-examples'

const result = generateComponentExamples(config)

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

Parameters

Returns

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

maxExamplesPerPage

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

// providing a number
maxExamplesPerPage: 50

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

Parameters

Returns

maxExamples

Specifies the total max number of examples

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 @rock-kit/ui-component-examples for documentation and example usage.

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.

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

Returns

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.

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

Returns

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

Returns

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

Returns

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).

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

Parameters

Returns