@component-controls/core NPM

Overview

Type definitions of the component-controls specification and accompanying utility functions. 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/core --save-dev

API

SourceIdentifier

interface

an identifier/variable.argument in the source code

defined in @component-controls/core/core/core/src/document.ts

properties

Name	Type	Description
`name*`	`string`
`loc`	`CodeLocation`	location in the source code of a story or part of it ie. arguments, usage of arguments

ArgUsageLocation

interface

defined in @component-controls/core/core/core/src/document.ts

properties

Name	Type	Description
`loc*`	`SourceLocationstart``line`: `numbercolumn`: `numberend``line`: `numbercolumn`: `number`	where in the story source code is the argument used code location is relative to the start of the story
`name`	`SourceIdentifier`	an identifier/variable.argument in the source code
`shorthand`	`boolean`	true if the property is a 'shorthand'. { prop: value } - not a shorthand. { prop } - a shorthand.

StoryArgument

interface

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

defined in @component-controls/core/core/core/src/document.ts

properties

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

StoryArguments

array

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

defined in @component-controls/core/core/core/src/document.ts

properties

Name	Type	Description
anonymous*	`StoryArgument`	arguments passed to the 'story' function, extracted by an AST loader

Story

type

Story interface - usually extracted by the AST instrumenting loader

defined in @component-controls/core/core/core/src/document.ts

properties

Name	Type	Parent	Description
`name*`	`string`		name of the Story.
`storyName`	`string`		alternative name prop
`id`	`string`		id of the story
`rawId`	`string`		raw id for the story as declared in ESM format
`doc`	`string`		title of the file/group of stories
`storyFn`	`StoryRenderFn`		story render function
`description`	`string`		story extended description. can use markdown.
`arguments`	`StoryArguments`		list of story arguments. Each argument can be a deconstructed argument of itself the first argument are the control 'values'
`loc`	`CodeLocation`		location in the source code of a story or part of it ie. arguments, usage of arguments
`source`	`string`		the source code of the story, extracted by the AST instrumenting loaders
`subtitle`	`string`		optional story subtitle property
`dynamic`	`boolean`		if set to true, the function is dynamically creating stories, returns a list of Story objects
`dynamicId`	`string`		if the story was created by a dynamic story (factory), this is the original story id. it is set internally and will be used to create a story URL
`component`	`typeat`: function* (`index`*: `number`) => `T` \| `undefined`	`StoryProps`	id for component associated with the story
`subcomponents`	`Record`<`string`, (`string`, `Record`<`string`, `unknown`>, `ElementType`<`Props`>)>	`StoryProps`	multiple components option
`controls`	`ComponentControls`	`StoryProps`	ComponentControls are defined in key value pairs the name of the property is the key and the value is the ComponentControl
`smartControls`	`SmartControlssmart`: `booleaninclude`: `string`[] \| `IncludeFnexclude`: `string`[] \| `IncludeFn`	`StoryProps`	"smart" controls options
`decorators`	`StoryRenderFn`[]	`StoryProps`	array of wrapper functions (decorators) to be called when rendering each individual story.
`plugins`	`any`	`StoryProps`	plugins configuration settings
`category`	`string`	`StoryProps`	category string - can be used for cleanly separating stories/components

DynamicExamples

array

defined in @component-controls/core/core/core/src/document.ts

properties

Name	Type	Description
anonymous*	`Story`	Story interface - usually extracted by the AST instrumenting loader

ExampleControl

union

defined in @component-controls/core/core/core/src/document.ts

values

ComponentControl | any

ExampleControls

type

defined in @component-controls/core/core/core/src/document.ts

properties

Name	Type
`name*`	[`string`]: `ExampleControl`

Example

type

es named export function, excapsulates a contained example code.

defined in @component-controls/core/core/core/src/document.ts

properties

Name	Type	Parent	Description
`bind*`	function (`props`: `Story`) => `Example`
`source`	`string`	`Story`	the source code of the story, extracted by the AST instrumenting loaders
`storyName`	`string`	`Story`	alternative name prop
`id`	`string`	`Story`	id of the story
`rawId`	`string`	`Story`	raw id for the story as declared in ESM format
`doc`	`string`	`Story`	title of the file/group of stories
`storyFn`	`StoryRenderFn`	`Story`	story render function
`description`	`string`	`Story`	story extended description. can use markdown.
`loc`	`CodeLocation`	`Story`	location in the source code of a story or part of it ie. arguments, usage of arguments
`subtitle`	`string`	`Story`	optional story subtitle property
`dynamic`	`boolean`	`Story`	if set to true, the function is dynamically creating stories, returns a list of Story objects
`dynamicId`	`string`	`Story`	if the story was created by a dynamic story (factory), this is the original story id. it is set internally and will be used to create a story URL
`component`	`typeat`: function* (`index`*: `number`) => `T` \| `undefined`	`StoryProps`	id for component associated with the story
`subcomponents`	`Record`<`string`, (`string`, `Record`<`string`, `unknown`>, `ElementType`<`Props`>)>	`StoryProps`	multiple components option
`smartControls`	`SmartControlssmart`: `booleaninclude`: `string`[] \| `IncludeFnexclude`: `string`[] \| `IncludeFn`	`StoryProps`	"smart" controls options
`decorators`	`StoryRenderFn`[]	`StoryProps`	array of wrapper functions (decorators) to be called when rendering each individual story.
`plugins`	`any`	`StoryProps`	plugins configuration settings
`category`	`string`	`StoryProps`	category string - can be used for cleanly separating stories/components
`controls`	`ExampleControls`

DocumentData

type

records of storyid/data pairs, to be associated with documents

defined in @component-controls/core/core/core/src/document.ts

properties

Name	Type
anonymous	[`string`]: `ExampleControls`

StoryFactoryFn

function

dynamic story creator function type. returns an array of dynamically loaded stories

defined in @component-controls/core/core/core/src/document.ts

parameters

Name	Type	Description
`doc*`	`Document`
`returns`	`typename`: `stringstoryName`: `stringid`: `stringrawId`: `stringdoc`: `stringstoryFn`: `StoryRenderFndescription`: `stringarguments`: `StoryArgumentsloc`: `CodeLocationsource`: `stringsubtitle`: `stringdynamic`: `booleandynamicId`: `stringcomponentat`: function (`index`*: `number`) => `T` \| `undefinedsubcomponents`: `Record`<`string`, (`string`, `Record`<`string`, `unknown`>, `ElementType`<`Props`>)>`controls`: `ComponentControlssmartControlssmart`: `booleaninclude`: `string`[] \| `IncludeFnexclude`: `string`[] \| `IncludeFndecorators`: `StoryRenderFn`[]`plugins`: `anycategory`: `string`	Story interface - usually extracted by the AST instrumenting loader

defDocType

union = "story"

defined in @component-controls/core/core/core/src/document.ts

values

Document

type

A documentation file's metadata. For MDX files, fromtmatter is used to declare the document properties. For ESM (ES Modules) documentation files, the default export is used.

defined in @component-controls/core/core/core/src/document.ts

properties

Name	Type	Parent	Description
`key*`	[`string`]: `any`		custom document props
`title*`	`string`		title of the document. If no 'route' parameter is specifified, the title is used to generate the document url. This is the only required field, to show the document in the menu structures.
`type`	`DocType`		document type - blogs, pages, stories and even custom ones. By default - story
`route`	`string`		if provided, will be used as the route for the page. if not provided, the title in lowercase will be used as the route
`date`	`string`		optional date the document was created. If not assigned, the instrumentation process will use birthtime
`dateModified`	`string`		optional date the document was last modified. If not assigned, the instrumentation process will use mtime
`status`	`"draft"` \| `"published"`		if set to draft, the document will be hidden in production builds.
`tags`	`string`[]		comma-separated list of document tags, used for search and for SOE keywords unless keyswords are specified.
`keywords`	`string`[]		comma-separated list of SEO keywords
`description`	`string` \| `JSX.Element`		documentation file description
`image`	`string`		link to an image for the document, will be used for SEO
`author`	`string`		document author
`order`	`number`		document order, used to sort documents within the same parent
`menu`	`string`		to which static menu to attach the document compatibility with docz
`template`	`Example`		es named export function, excapsulates a contained example code.
`stories`	`string`[]		list of story ids contained in the document.
`source`	`string`		source code of the entire file of stories
`fileName`	`string`		file name of the file of stories
`package`	`string`		lookup into the global store of PackageInfo package.json
`testFiles`	`string`[]		optional specify which test files are asociated with the document
`testCoverage`	`string`[]		optional specify which files to use for test coverage
`testData`	`string`		optional test data file
`renderFn`	`FrameworkRenderFn`		render function by framework. By default 'react'
`data`	`DocumentData`		records of storyid/data pairs, to be associated with documents
`componentsLookup`	`type`[`string`]: `string`		lookup into the global store.components since multiple components of the same name can be used example: ['Button']: 'c:/myapp/Button.tsx'
`MDXPage`	`any`		for MDX documents, this is an MDXContent function, to be rendered inside a MDXProvider
`isMDXComponent`	`boolean`		custom prop set by mdxjs
`parameters`	`any`		storybook compatibility field
`component`	`typeat`: function* (`index`*: `number`) => `T` \| `undefined`	`StoryProps`	id for component associated with the story
`subcomponents`	`Record`<`string`, (`string`, `Record`<`string`, `unknown`>, `ElementType`<`Props`>)>	`StoryProps`	multiple components option
`controls`	`ComponentControls`	`StoryProps`	ComponentControls are defined in key value pairs the name of the property is the key and the value is the ComponentControl
`smartControls`	`SmartControlssmart`: `booleaninclude`: `string`[] \| `IncludeFnexclude`: `string`[] \| `IncludeFn`	`StoryProps`	"smart" controls options
`decorators`	`StoryRenderFn`[]	`StoryProps`	array of wrapper functions (decorators) to be called when rendering each individual story.
`plugins`	`any`	`StoryProps`	plugins configuration settings
`category`	`string`	`StoryProps`	category string - can be used for cleanly separating stories/components
`navSidebar`	`boolean`	`PageLayoutProps`	whether to add navigation sidebar to the page
`contextSidebar`	`boolean`	`PageLayoutProps`	whether to add conext sidebar to navigate the sections of the current document
`fullPage`	`boolean`	`PageLayoutProps`	whether to take a fullpage theme option

dateToLocalString

react function

defined in @component-controls/core/core/core/src/document.ts

parameters

Name	Type
`date`	`Date`
`returns`	`string`

DocInfo

type

short document information. used in search results, or index page

defined in @component-controls/core/core/core/src/document.ts

properties

Name	Type	Parent	Description
`title*`	`string`	`Document`	title of the document. If no 'route' parameter is specifified, the title is used to generate the document url. This is the only required field, to show the document in the menu structures.
`image`	`string`	`Document`	link to an image for the document, will be used for SEO
`description`	`string` \| `JSX.Element`	`Document`	documentation file description
`tags`	`string`[]	`Document`	comma-separated list of document tags, used for search and for SOE keywords unless keyswords are specified.
`author`	`string`	`Document`	document author
`type`	`DocType`	`Document`	document type - blogs, pages, stories and even custom ones. By default - story
`date`	`string`	`Document`	optional date the document was created. If not assigned, the instrumentation process will use birthtime
`link*`	`string`		following fields are useful for highlighting search results
`authorLink`	`string`
`rawTags`	`string`[]
`rawType`	`string`

Documents

type

list of story files, or groups

defined in @component-controls/core/core/core/src/document.ts

properties

Name	Type
anonymous	[`string`]: `Document`

Pages

array

defined in @component-controls/core/core/core/src/document.ts

properties

Name	Type	Description
anonymous*	`Document`	A documentation file's metadata. For MDX files, fromtmatter is used to declare the document properties. For ESM (ES Modules) documentation files, the default export is used.

Stories

type

list of stories

defined in @component-controls/core/core/core/src/document.ts

properties

Name	Type
anonymous	[`string`]: `Story`

Packages

type

list of repositories

defined in @component-controls/core/core/core/src/document.ts

properties

Name	Type
anonymous	[`string`]: `PackageInfo`

StoreObserver

function

defined in @component-controls/core/core/core/src/document.ts

parameters

Name	Type	Description
`story`	`Story`	Story interface - usually extracted by the AST instrumenting loader

CURRENT_STORY

string = "."

Shorthand id to denote the current story

defined in @component-controls/core/core/core/src/document.ts

Store

interface

Store of stories information in memory after the loader is applied

defined in @component-controls/core/core/core/src/document.ts

properties

Name	Type	Description
`error`	`string`	build-time error string
`config*`	`RunConfiguration`	global configuration for config file
`docs*`	`Documents`	list of documents (pages)
`stories*`	`Stories`	list of stories
`components*`	`Components`	list of components used in stories and documents
`packages*`	`Packages`	list of package.json files and their data used by the components and the stories of the project
`addObserver*`	function (`observer`*: `StoreObserver`) => `void`	storybook integration notifiers
`removeObserver*`	function (`observer`*: `StoreObserver`) => `void`
`updateStory*`	function (`story`*: `Story`) => `void`	update store, for example controls or state
`search`	function (`store`: `Store`) => `SearchResultitems`: `SearchItem`[]`searchFn`: function* (`search`: `string`) => `voidproviderlogo`: ReactNode`url`: `stringname`: `string`