Parse examples

Examples (also known as presets) are useful configurations of your component that act as starting points for your designers to use - they are the component configurations you can drag and drop onto the canvas in Figma.

Approach

You can create individual examples by configuring component instances in the Interplay UI, but for large numbers it is usually easier to parse examples from your repo.

You do this by:

1. Configuring the CLI to parse components in your repo using an index file as an entry point

2. Configuring the CLI to parse examples from specific instances of each component:
• presetPaths controls which files are parsed looking for component instances
• presetRules controls which components instances are imported as examples from those files.

Once these settings are configured in interplay.config.js, you can run the CLI parsing with:

interplay parse

During its run, the CLI will:

• Find all the components in the index file

• Parse the presetPaths files, find all component instances that match the components in the index

• Use the presetRules to select which instances to use to generate examples config

Example files

For example, when importing the reactstrap components, we may also configure this file as one of the presetPaths for the repo:

//buttongroup.example.js
import React from 'react';
import { Button, ButtonGroup, Stack } from 'reactstrap';

export const Example = () => {
	return (
	<Stack>
	    <ButtonGroup>
	      <Button>Button</Button>
	      <Button>Button</Button>
	      <Button>Button</Button>
	    </ButtonGroup>
	</Stack>
	);
}

The CLI would find the instances of Stack, ButtonGroup and Button. These instances are then compared with presetRules to determine which should be created as examples in Interplay. The default rules match the ButtonGroup instance in the buttongroup.story.js file, Card in card.story.js file etc.

So in this case the ButtonGroup instance would be imported as an example and the Stack and Button instances would be ignored. This approach allows you to parse your existing storybook or documentation files but control which instances are used as examples.

For even greater control of your examples, we recommend either:

• Create dedicated example files for Interplay to parse.

• Adding data attributes to your specific examples to mark them for import.

See Curating examples below for more details.

Supported File Formats

You may already have suitable configurations of your components that you use as documentation files (e.g. storybook files), in which case you can configure those files as your presetPaths in interplay.config.js.

Javascript and Typescript

The CLI extracts examples from .js and .jsx files by first attempting to require the files using babel-register, so that data imported from other files and dynamically generated component instances can be found.

If the file cannot be loaded (required), or no component instances are exported from the file then the CLI falls back to using static analysis. In this mode the file is parsed to AST and the syntax scanned - this allows basic component usages to be found but does not support dynamically generated content.

The parser will recognise exported instances of components as in the example above and Storybook format files using both Storybook's Component Story Format (CSF) and the older storiesOf format, in both typescript and javascript. We recommend using the newer Component Story Format.

Markdown

When extracting examples from Markdown files the CLI first examines the Markdown file to extract javascript or JSX code blocks. It then processes those sections in turn, treating them as independent fragments of code to process.

In this case Interplay will find the jsx fragment and then parse the 5 different Button configurations from within it.

As outlined above, Interplay can parse your existing repo files to find examples to get you up and running quickly. Depending on how your existing files are structured, this approach may be sufficient. Running the CLI again will import any example changes in those files into Interplay.

presetRules

You specify presetRules in interplay.config.js to specify which instances of components found in your presetPaths should be matched and used as examples.

Example rules use simple regex patterns to match component instances. A component instance will be converted into an example if it matches any of your example rules. If you use the {componentName} string in a rule, it will be substituted before attempting to match the rule.

Here are some examples of presetRules:

//interplay.config.js

presetRules: [
{ //match component instances whose name matches first part of filename
	"presetPath": "/{componentName}.",
	limit: 5 //per-component, per-file limit
},
{ //match component instances whose name matches folder in preset file path
	"presetPath": "/{componentName}/",
	 limit: 5
},
{ //match all component instances in Icons.stories.js whose source file path matches a pattern
    "presetPath": "lib/components/icons/Icons.stories.js",   //rule only applies to this file
    "componentPath": "lib/components/icons/*.*"              //match components whose source resolves here
},
{ //always true - matches every component instance
    "presetPath": ".*",
},
],

Subcomponents

In Interplay, subcomponents are components that can only be used inside a particular parent component. e.g. MenuItem components that must run inside a Menu component.

You can tell the CLI not to create standalone examples for these components by configuring them as subcomponents under the packages section of your CLI settings as shown in Importing code components

Instead of creating standalone examples for subcomponents, the CLI will create examples that point to instances inside their parent component.

Curating Examples

Interplay can parse exported instances of your components from files to use as examples from Storybook stories in both Component Story Format and the older storiesOf format. Stories can be in either javascript or typescript files.

For best control over your examples in Interplay, we recommend writing your examples in Component Story Format, an open format proposed by the creators of Storybook.

Using Storybook CSF

Component Story Format is an open format proposed by the creators of Storybook and includes provision for adding metadata and including/excluding stories from processing.

Here is a CSF file that exports 2 examples (stories) for the Button component:

//import your components via relative path or package alias so Interplay can find your code
import Button from './Button';
export default {
  title: 'Button'
}
//export examples individually
export const primaryButton = () => <Button appearance="primary">Primary Button</Button>;
export const secondaryButton = () => <Button appearance="secondary">Secondary Button</Button>;

//The preset name is determined by the named export, or you can optionally set metadata:
primaryButton.story = {
    name: "Primary Button example"
    description: "Here is a description for the primary button example."
}

When writing examples to parse:

• Use a separate named export for each example to retain control of the metadata. e.g. the file above has 4 named exports with one Button configuration in each, not 1 export containing 4 Buttons.

• Import the components used in your example from their source files using relative paths to help the parser resolve the component.

For full details of Component Story Format please see the Storybook website

Troubleshooting Example Parsing

Examples not imported

If you create example files using the recommended format, the CLI parsing should find the instances of your components and create examples for them.

When parsing existing repo files that contain instances of your components, some instances may not be discovered or may not be converted to examples.

You can find two log files output by the CLI for further information:

.interplay/logs/summary.txt

This file contains a table for all the exports found in your component index, showing how was resolved to its source file, and any component properties that were found when parsing this source file.

.interplay/logs/instances.json

This file contains an entry for all the instances of your components found in your examples files.

.interplay/logs/matched.json

This file contains an entry for all the instances of your components that matched your presetRules.

For the instances that matched your example rules, a further validation status is shown:

Imported - instance passed validation.

UnknownComponent - instance was rejected because it contains a component that is not in recognised as being in your component index - usually either a local component (i.e. not exported from your index) or one that has been imported from a different location from where your component index resolved.