README
Table of contents
- Overview
- Installation
- API
- ArgUsageLocation
- SourceIdentifier
- Stories
- StoriesKind
- StoriesStore
- Story
- StoryArgument
- StoryComponents
- StoryKinds
- StoryPackages
- StoryParameters
- StoryStories
- StoryArguments
- ControlTypes
- ComponentControlArray
- ComponentControlBase
- ComponentControlBoolean
- ComponentControlButton
- ComponentControlColor
- ComponentControlData
- ComponentControlDate
- ComponentControlFiles
- ComponentControlNumber
- ComponentControlObject
- ComponentControlOptions
- ComponentControlText
- ComponentControls
- ComponentControl
- OptionsListType
- OptionsValueType
- ComponentInfo
- PropType
- PropTypes
- StoryComponent
- TypeInformation
- TypeValue
- getComponentName
- PropsInfoExtractorFunction
- CodeLocation
- CodePosition
- ImportName
- Imports
- PackageDependencies
- PackageInfo
- PackageRepository
- PackageDependency
- StoryRenderFn
- Configuration
- StoryRenderFn
- StoryArguments
- ComponentControl
- TypeValue
- PackageDependency
Overview
Typescript definitions of the component-controls specification. Includes definitions for:
- Story
- Stories
- ControlTypes
- ComponentControl
- PropTypes
- and more...
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
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