A next-generation tool to create blazing-fast documentation sites
API
created:8/18/2020
updated:8/31/2020

Controls API

Overview

The component controls are designed to provide an extensible interface for specifying and using input controls to enter component properties at run-time.

Usage

ESM

import { ControlTypes } from '@component-controls/core';
export const textControl = ({ text }) => (<div>{props.text}</div>);
textControl.controls = {
text: 'some text'
};

MDX

import { ControlTypes } from '@component-controls/core';
import { Story, Playground, PropsTable } from '@component-controls/blocks';
<Playground>
<Story name='text-control' controls={{ text: 'some text' }}>
{props => (
<div>{props.text}</div>
)}
</Story>
</Playground>

Interfaces

ComponentControls

ComponentControls are defined in key value pairs where the name of the property is the key and the value is a ComponentControl object
Record<string, ComponentControl>

ComponentControl

ComponentControl is a either an object of property settings ControlTypes:
import { ControlTypes } from '@component-controls/core';
export const textControl = ({ text }) => (<div>{props.text}</div>);
textControl.controls = {
text: { type: ControlTypes.TEXT, value: 'some text'}
};
Or a shortcut can be used for types TEXT, NUMBER and DATE:
import { ControlTypes } from '@component-controls/core';
export const textControl = ({ text }) => (<div>{props.text}</div>);
textControl.controls = {
text: 'some text', //shortcut notation
};

ControlTypes

All control types descend from ControlType

ControlType

The base class has the following properties that apply to all control types
common properties for all controls
NameTypeDescription
type*ControlTypes
valuea default value for the property
descriptionstringfull text property description. can use markdown.
groupIdstringallows grouping of the properties in a property editor, for example, different editor tabs
hiddenbooleanhide the property editor for this property will only use the value
labelstringlabel to display next to the field editor by default uses the property name itself
ordernumberallows custom sorting of the properties if 'order' is not provided, the props will be sorted by the order/key of the object (unreliable)
requiredbooleanvisually display the control property as required
dataComponentControlData | null | falsehelper information to generate random data will be used in conjunction with faker.js data can be set to false, if the control should not be randomized
defaultValuedefault value is usually set at run-time, from the value
More info on the pre-defined controls, however, you can also create custom control types and their respective control editors.

ComponentControlData

properties
NameTypeDescription
name*string'name' for generating random data from faker.js usually comprised of two parts, separated by a dot example 'internet.avatar'
options[key: string]: anyoptions to be passed to the random data generators example { min: 10, max: 20 }

SmartControls

properties
NameTypeDescription
excludestring[]exclude props only
includestring[]include props only
smartbooleanwhether to generate "smart" controls for a story