@component-controls/specification

Component controls specification with typescript definitions

Usage no npm install needed!

<script type="module">
  import componentControlsSpecification from 'https://cdn.skypack.dev/@component-controls/specification';
</script>

README

Table of contents

Overview

Typescript definitions of the component-controls specification. Includes definitions for:

Installation

This package is usually installed as part of the @component-controls package, but you can also install it standalone:

$ npm install @component-controls/specification --save-dev

API

ArgUsageLocation

defined in @component-controls/specification/src/stories.ts

properties

Name Type Description
loc* CodeLocation where in the story source code is the argument used code location is relative to the start of the story
name SourceIdentifier optional name for the usage of the argument example: export const story = ({ value }) => <Story value={{ age: value }} />; in this example the name will be 'age'
shorthand boolean true if the property is a 'shorthand'. { prop: value } - not a shorthand. { prop } - a shorthand.

SourceIdentifier

an identifier/variable.argument in the source code

defined in @component-controls/specification/src/stories.ts

properties

Name Type Description
loc CodeLocation
name* string

Stories

map of stories. The id is compatible with CSF story ids

defined in @component-controls/specification/src/stories.ts

id*: string: Story

StoriesKind

a group of stories. Usually multiple stories are in one csf file and the 'group' is the default export in the case of MDX stories, the kind is crated using a <Meta /> tag

defined in @component-controls/specification/src/stories.ts

name*: string: any

properties

Name Type Description
MDXPage any for MDX pages, this is an MDXContent function, to be rendered inside a MDXProvider
component string | object id for component associated with the stories file
components* [name: string]: string lookup into the global store.components since multiple components of the same name can be used example: ['Button']: 'c:/myapp/Button.tsx'
controls ComponentControls object of key/value pairs specifying the controls for the stories file this will apply to all the stories in the file
decorators StoryRenderFn[] story decorators (or wrappers)
excludeStories string[] | RegExp list of stories to exclude from the stories file can also use regexp match
fileName string file name of the file of stories
includeStories string[] | RegExp list of stories to include in the stories file can also use regexp match
package string lookup into the global store of PackageInfo package.json
parameters StoryParameters configuration parameters passed to the story groups configured either as CSF default export or MDX <Meta /> tag
source string source code of the entire file of stories
stories string[] list of stories contained in the file/groups
subcomponents string[] | object[] multiple components option
title* string title of the groups of stories (or kind). used to generate CSF story ids

StoriesStore

store of stories information in memory after the loader is applied

defined in @component-controls/specification/src/stories.ts

properties

Name Type Description
components* StoryComponents list of components used in stories
kinds* StoryKinds list of story files, or groups
packages* StoryPackages list of package.json files and their data used by the components and the stories of the project
stories* StoryStories list of stories

Story

Story interface - usually extracted by the AST instrumenting loader

defined in @component-controls/specification/src/stories.ts

properties

Name Type Description
arguments StoryArguments arguments pass to a CSF story eg `export const story = props => <Story {...props} />;`
component string | object id for component associated with the story
controls ComponentControls object of key/value pairs specifying the controls for the story
decorators StoryRenderFn[] story decorators (or wrappers)
description string story extended description. can use markdown.
id string csf id of the story
kind string title of the file/group of stories
loc CodeLocation location in the source file of the story definition
name* string name of the Story.
parameters StoryParameters configuration parameters passed to the story - either CSF or MDX
renderFn StoryRenderFn render function for the story
source string the source code of the story, extracted byt the AST instrumenting loaders
subcomponents [key: string]: string | object multiple components option
subtitle string optional story subtitle property

StoryArgument

arguments passed to the 'story' function, extracted by an AST loader

defined in @component-controls/specification/src/stories.ts

properties

Name Type Description
loc CodeLocation location of the argument declaration, relative to the story source code
name string the original name of the argument
usage ArgUsageLocation[] list of locations where the argument is used in the body of the story
value* string | StoryArguments either the name used (or a variable alias), or an array of sub-arguments ({ name: alias })

StoryComponents

list of components used in stories

defined in @component-controls/specification/src/stories.ts

fileName*: string: StoryComponent

StoryKinds

list of story files, or groups

defined in @component-controls/specification/src/stories.ts

title*: string: StoriesKind

StoryPackages

list of repositories

defined in @component-controls/specification/src/stories.ts

id*: string: PackageInfo

StoryParameters

list of configuration parameters for stories and 'kinds' can be specified either through CSF or MDX tags

defined in @component-controls/specification/src/stories.ts

name*: string: any

StoryStories

list of stories

defined in @component-controls/specification/src/stories.ts

id*: string: Story

StoryArguments

list of story arguments. Each argument can be a deconstructed argument of itself the first argument are the control 'values'

defined in @component-controls/specification/src/stories.ts

StoryArgument[]

ControlTypes

Control field types examples are provided for the different types:

defined in @component-controls/specification/src/controls.ts

properties

Name Type Description
ARRAY* function ARRAY arrayItems: { type: ControlTypes.ARRAY, label: 'Items', rowType: { name: { type: ControlTypes.TEXT }, }, value: [{ name: 'Laptop' }, { name: 'Book' }, { name: 'Whiskey' }], },
BOOLEAN* function BOOLEAN nice: { type: ControlTypes.BOOLEAN, label: 'Nice', value: true, },
BUTTON* function BUTTON button: { type: ControlTypes.BUTTON, onClick: () => { ... code to modify some variables } },
COLOR* function COLOR color: { type: 'color', value: '#000000', },
DATE* function DATE birthday: { type: ControlTypes.DATE, label: 'Birthday', value: new Date(), },
FILES* function FILES images: { type: ControlTypes.FILES, label: 'Happy Picture', accept: 'image/*', value: [ 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAQAAAC1+jfqAAAABGdBTUEAALGPC/xhBQAAACBjSFJNAAB6JgAAgIQAAPoAAACA6AAAdTAAAOpgAAA6mAAAF3CculE8AAAAAmJLR0QA/4ePzL8AAAAHdElNRQfiARwMCyEWcOFPAAAAP0lEQVQoz8WQMQoAIAwDL/7/z3GwghSp4KDZyiUpBMCYUgd8rehtH16/l3XewgU2KAzapjXBbNFaPS6lDMlKB6OiDv3iAH1OAAAAJXRFWHRkYXRlOmNyZWF0ZQAyMDE4LTAxLTI4VDEyOjExOjMzLTA3OjAwlAHQBgAAACV0RVh0ZGF0ZTptb2RpZnkAMjAxOC0wMS0yOFQxMjoxMTozMy0wNzowMOVcaLoAAAAASUVORK5CYII=', ], },
NUMBER* function NUMBER age: { type: ControlTypes.NUMBER, label: 'Age', value: 78, range: true, min: 0, max: 90, step: 5, },
OBJECT* function OBJECT style: { type: ControlTypes.OBJECT, label: 'Styles', value: { // do not randomize the border style border: { type: ControlTypes.TEXT, value: '2px dashed silver', data: null }, borderRadius: { type: ControlTypes.NUMBER, value: 10 }, padding: { type: ControlTypes.NUMBER, value: 10 }, }, }
OPTIONS* function OPTIONS fruit: { type: ControlTypes.OPTIONS, label: 'Fruit', value: 'apple', options: { Apple: 'apple', Banana: 'banana', Cherry: 'cherry', }, },
TEXT* function TEXT userName: { type: ControlTypes.TEXT, label: 'Name', value: 'Storyteller', },

ComponentControlArray

defined in @component-controls/specification/src/controls.ts

** extends ComponentControlBase<[key: string]: any[]>**

properties

Name Type Description
data ComponentControlData | null | false helper information to generate random data will be used in conjunction with faker.js datacan be set to false, if the control should not be randomized
defaultValue [key: string]: any[] default value is usually set at run-time, from the value
description string full text property description. can use markdown.
editLabel string the label for the editor button
groupId string allows grouping of the properties in a property editor for example different editor tabs
hidden boolean hide the property editor for this property will only use the value
label string label to display next to the field editor by default uses the property name itself
order number allows custom sorting of the properties if 'order' is not provided, the props will be sorted by the order/key of the object (unreliable)
required boolean visually display the control property as required
resetValue [key: string]: any[] reset value - this is automatically saved as the initial 'value' used when user wants to click rest and go back to the initial values
rowType* ComponentControls type of the items in each row of the array
type* ARRAY
value [key: string]: any[] a default value for the property

ComponentControlBase

Base inteface for creating control types All new property typs should extend this interface and support

defined in @component-controls/specification/src/controls.ts

properties

Name Type Description
data ComponentControlData | null | false helper information to generate random data will be used in conjunction with faker.js datacan be set to false, if the control should not be randomized
defaultValue default value is usually set at run-time, from the value
description string full text property description. can use markdown.
groupId string allows grouping of the properties in a property editor for example different editor tabs
hidden boolean hide the property editor for this property will only use the value
label string label to display next to the field editor by default uses the property name itself
order number allows custom sorting of the properties if 'order' is not provided, the props will be sorted by the order/key of the object (unreliable)
required boolean visually display the control property as required
resetValue reset value - this is automatically saved as the initial 'value' used when user wants to click rest and go back to the initial values
type* ControlTypes
value a default value for the property

ComponentControlBoolean

defined in @component-controls/specification/src/controls.ts

** extends ComponentControlBase<boolean>**

properties

Name Type Description
data ComponentControlData | null | false helper information to generate random data will be used in conjunction with faker.js datacan be set to false, if the control should not be randomized
defaultValue boolean default value is usually set at run-time, from the value
description string full text property description. can use markdown.
groupId string allows grouping of the properties in a property editor for example different editor tabs
hidden boolean hide the property editor for this property will only use the value
label string label to display next to the field editor by default uses the property name itself
order number allows custom sorting of the properties if 'order' is not provided, the props will be sorted by the order/key of the object (unreliable)
required boolean visually display the control property as required
resetValue boolean reset value - this is automatically saved as the initial 'value' used when user wants to click rest and go back to the initial values
type* BOOLEAN
value boolean a default value for the property

ComponentControlButton

defined in @component-controls/specification/src/controls.ts

** extends ComponentControlBase<>**

properties

Name Type Description
data ComponentControlData | null | false helper information to generate random data will be used in conjunction with faker.js datacan be set to false, if the control should not be randomized
defaultValue default value is usually set at run-time, from the value
description string full text property description. can use markdown.
groupId string allows grouping of the properties in a property editor for example different editor tabs
hidden boolean hide the property editor for this property will only use the value
label string label to display next to the field editor by default uses the property name itself
onClick function (prop*: ComponentControlButton): void; for button type fields, an onClick handler
order number allows custom sorting of the properties if 'order' is not provided, the props will be sorted by the order/key of the object (unreliable)
required boolean visually display the control property as required
resetValue reset value - this is automatically saved as the initial 'value' used when user wants to click rest and go back to the initial values
type* BUTTON
value a default value for the property

ComponentControlColor

defined in @component-controls/specification/src/controls.ts

** extends ComponentControlBase<string>**

properties

Name Type Description
data ComponentControlData | null | false helper information to generate random data will be used in conjunction with faker.js datacan be set to false, if the control should not be randomized
defaultValue string default value is usually set at run-time, from the value
description string full text property description. can use markdown.
groupId string allows grouping of the properties in a property editor for example different editor tabs
hidden boolean hide the property editor for this property will only use the value
label string label to display next to the field editor by default uses the property name itself
order number allows custom sorting of the properties if 'order' is not provided, the props will be sorted by the order/key of the object (unreliable)
required boolean visually display the control property as required
resetValue string reset value - this is automatically saved as the initial 'value' used when user wants to click rest and go back to the initial values
type* COLOR
value string a default value for the property

ComponentControlData

defined in @component-controls/specification/src/controls.ts

properties

Name Type Description
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]: any options to be passe to the random data generators example { min: 10, max: 20 }

ComponentControlDate

defined in @component-controls/specification/src/controls.ts

** extends ComponentControlBase<Date>**

properties

Name Type Description
data ComponentControlData | null | false helper information to generate random data will be used in conjunction with faker.js datacan be set to false, if the control should not be randomized
datePicker boolean whether to display a date picker (calendar). default: true
defaultValue Date default value is usually set at run-time, from the value
description string full text property description. can use markdown.
groupId string allows grouping of the properties in a property editor for example different editor tabs
hidden boolean hide the property editor for this property will only use the value
label string label to display next to the field editor by default uses the property name itself
order number allows custom sorting of the properties if 'order' is not provided, the props will be sorted by the order/key of the object (unreliable)
required boolean visually display the control property as required
resetValue Date reset value - this is automatically saved as the initial 'value' used when user wants to click rest and go back to the initial values
timePicker boolean whether to display a time picker (calendar). default: true
type* DATE
value Date a default value for the property

ComponentControlFiles

defined in @component-controls/specification/src/controls.ts

** extends ComponentControlBase<string[]>**

properties

Name Type Description
accept string type of files to accept user to open ex 'image/*',
data ComponentControlData | null | false helper information to generate random data will be used in conjunction with faker.js datacan be set to false, if the control should not be randomized
defaultValue string[] default value is usually set at run-time, from the value
description string full text property description. can use markdown.
groupId string allows grouping of the properties in a property editor for example different editor tabs
hidden boolean hide the property editor for this property will only use the value
label string label to display next to the field editor by default uses the property name itself
order number allows custom sorting of the properties if 'order' is not provided, the props will be sorted by the order/key of the object (unreliable)
required boolean visually display the control property as required
resetValue string[] reset value - this is automatically saved as the initial 'value' used when user wants to click rest and go back to the initial values
type* FILES
value string[] a default value for the property

ComponentControlNumber

defined in @component-controls/specification/src/controls.ts

** extends ComponentControlBase<number>**

properties

Name Type Description
data ComponentControlData | null | false helper information to generate random data will be used in conjunction with faker.js datacan be set to false, if the control should not be randomized
defaultValue number default value is usually set at run-time, from the value
description string full text property description. can use markdown.
groupId string allows grouping of the properties in a property editor for example different editor tabs
hidden boolean hide the property editor for this property will only use the value
label string label to display next to the field editor by default uses the property name itself
max number maximum allowed value for numeric property
min number minimum allowed value for numeric property
order number allows custom sorting of the properties if 'order' is not provided, the props will be sorted by the order/key of the object (unreliable)
range boolean if true, will display a range type slider editor
required boolean visually display the control property as required
resetValue number reset value - this is automatically saved as the initial 'value' used when user wants to click rest and go back to the initial values
step number stepper for numeric editor /i nc/dec value
type* NUMBER
value number a default value for the property

ComponentControlObject

defined in @component-controls/specification/src/controls.ts

** extends ComponentControlBase<ComponentControls>**

properties

Name Type Description
data ComponentControlData | null | false helper information to generate random data will be used in conjunction with faker.js datacan be set to false, if the control should not be randomized
defaultValue ComponentControls default value is usually set at run-time, from the value
description string full text property description. can use markdown.
editLabel string the label for the editor button
groupId string allows grouping of the properties in a property editor for example different editor tabs
hidden boolean hide the property editor for this property will only use the value
label string label to display next to the field editor by default uses the property name itself
order number allows custom sorting of the properties if 'order' is not provided, the props will be sorted by the order/key of the object (unreliable)
required boolean visually display the control property as required
resetValue ComponentControls reset value - this is automatically saved as the initial 'value' used when user wants to click rest and go back to the initial values
type* OBJECT
value ComponentControls a default value for the property

ComponentControlOptions

list of options can be 1. key-value pair object: in format { label: value } 2. array of strings 3. array of key-value pair objects

defined in @component-controls/specification/src/controls.ts

** extends ComponentControlBase<OptionsValueType<>>**

properties

Name Type Description
data ComponentControlData | null | false helper information to generate random data will be used in conjunction with faker.js datacan be set to false, if the control should not be randomized
defaultValue OptionsValueType<> default value is usually set at run-time, from the value
description string full text property description. can use markdown.
display 'select' | 'multi-select' | 'radio' | 'inline-radio' | 'check' | 'inline-check' how to render selecting the options: default is 'select'
groupId string allows grouping of the properties in a property editor for example different editor tabs
hidden boolean hide the property editor for this property will only use the value
label string label to display next to the field editor by default uses the property name itself
options* OptionsListType<>
order number allows custom sorting of the properties if 'order' is not provided, the props will be sorted by the order/key of the object (unreliable)
required boolean visually display the control property as required
resetValue OptionsValueType<> reset value - this is automatically saved as the initial 'value' used when user wants to click rest and go back to the initial values
type* OPTIONS
value OptionsValueType<> a default value for the property

ComponentControlText

defined in @component-controls/specification/src/controls.ts

** extends ComponentControlBase<string>**

properties

Name Type Description
data ComponentControlData | null | false helper information to generate random data will be used in conjunction with faker.js datacan be set to false, if the control should not be randomized
defaultValue string default value is usually set at run-time, from the value
description string full text property description. can use markdown.
escapeValue boolean allows to receive escaped string values to help prevent XSS attacks by default - false
groupId string allows grouping of the properties in a property editor for example different editor tabs
hidden boolean hide the property editor for this property will only use the value
label string label to display next to the field editor by default uses the property name itself
order number allows custom sorting of the properties if 'order' is not provided, the props will be sorted by the order/key of the object (unreliable)
placeholder string placeholder for empty properties either undefined initial value or user clears the field
required boolean visually display the control property as required
resetValue string reset value - this is automatically saved as the initial 'value' used when user wants to click rest and go back to the initial values
rows number number of rows for a TextArea field for longer text by default, only 1 row = means a Input field > 1 rows = an area field
type* TEXT
value string a default value for the property

ComponentControls

ComponentControls are