Table of contents

• Shocase sites
• Overview
  • Storybook addon panels
• Custom documentation pages
  • Hide storybookjs Canvas
  • Create custom Canvas page
  • Configure '@component-controls/storybook' to load out custom page only
• List of components
  • ComponentSource
  • Description
  • Meta
  • Playground
  • PropsTable
  • Stories
  • Story
  • StoryConfig
  • StorySource
  • Subtitle
  • Title
  • BlockContextProvider
  • ControlsProvider
  • ThemeProvider
  • PageContextContainer
  • DocsContainer
  • AddonPanel
  • PropsTablePanel
  • StoryConfigPanel
  • StorySourcePanel

Shocase sites

• Storybook 6 without addon-docs
• Storybook 6

Overview

Storybook plugin for documenting your projects with component controls

• Full replacement for the storybook addon-docs
• Works with storybook-5 and storybook-6

Limitations

• Initial version is only for react apps. More frameworks are on the roadmap.
• Only handles the ESM(CSF) and MDX stories format. The storiesOf API is not supported and there are currently no plans to support it.

Getting started with storybook

Storybook addon panels

The component-controls block components have been designed from the ground up to be able to be placed either on documentation pages or in addon tabs.

You can turn on and off the available panels:

  {
    name: '@component-controls/storybook',
    options: {
      controlsPanel: true,
      propsPanel: true,
      storySourcePanel: true,
    }
  }  

Custom documentation pages

component-controls installs a default Page with some standard documentation boocks, however you can replace the deafult page and add new pages.

Here is an example that will completely hide the storybook Canvas tab and replace it with our custom documentation page

Hide storybookjs Canvas

.storybook/manager.js

import { addons } from '@storybook/addons';
addons.setConfig({
  previewTabs: {
    canvas: {
      //hide storybooks Canvas tab
      hidden: true,
    },
    'CUSTOM_PAGE_ADDON/canvas': {
      //place our custom Canvas page first in order of tabs
      index: 0,
    },

  },
});

Create custom Canvas page

.storybook/canvas-page.tsx

import React from 'react';
import { CanvasPage } from '@component-controls/pages';
import { DocsContainer } from '@component-controls/storybook';

export default {
  key: 'canvas',
  title: 'Canvas',
  render: ({ active }: { active: boolean }) => (
    <DocsContainer active={active}>
      <CanvasPage />
    </DocsContainer>
  ),
};

Configure '@component-controls/storybook' to load out custom page only

.storybook/main.tsx

module.exports = {
  addons: [
    '@storybook/addon-docs',
    {
      name: '@component-controls/storybook',
      options: {
        pages: [require.resolve('./canvas-page.tsx')],
      }
    },
  ],
};

List of components

ComponentSource

ComponentSource source code

properties

| Name | Type | Description | | ------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | onSelect | ((name: string, component: Component) => boolean | void) & ((event: SyntheticEvent<HTMLDivElement, Event>) => void) | callback to be called when the tab changes if the function returns false, it can stop chabging to the new tab | | ref | ((instance: HTMLDivElement) => void) | RefObject<HTMLDivElement> | | | title | string | optional section title for the block. optional title to display for the code block. Usually used from MDX | | sx | ThemeUIStyleObject | | | id | string | optional id to be used for the block if no id is provided, one will be calculated automatically from the title. | | visibility | ComponentVisibility | by default will show both controls and props tables user setting can display only props table or only controls | | of | any | Specify the component(s), for which to have information displayed. The default, a value of `"."` will indicate to display information for the current component (associated with the current Story). If an array of components is specified, each component will be displayed in a separate tab. | | name | string | some component-oriented ui components can also be driven by a story id (name). ie the PropsTable can display component props, or story controls | | description | string | optional markdown description. | | collapsible | boolean | if false, will nothave a collapsible frame. | | data-testid | string | testing id | | plain | boolean | inner container variant or plain if plain, skip the border and spacing around the children | | actions | ActionItem[] | optional actions provided to the component | | theme | PrismTheme | optional `PrismTheme` theme provided to the component. Themes can be imported from `prism-react-renderer/themes`. | | language | Language | source lnguage used, by default "jsx". | | renderFn | (props: RenderProps, other: { theme: PrismTheme; }) => ReactNode | custom function to render the source code. | | dark | boolean | used to specify a "dark" color theme - applcable only if no custom theme prop is provided. if dark: true, duotoneDark theme is used. if dark: false, duotoneLight theme is used. | | metastring | string | code configuration string passed from MDX |

Description

Description source code

properties

| Name | Type | Description | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | components | { [key: string]: ComponentOverride<any, any>; a?: ComponentOverride<any, any>; br?: ComponentOverride<any, any>; button?: ComponentOverride<any, any>; ... 27 more ...; ul?: ComponentOverride<...>; } | components to customize the markdown display. | | of | any | Specify the component(s), for which to have information displayed. The default, a value of `"."` will indicate to display information for the current component (associated with the current Story). If an array of components is specified, each component will be displayed in a separate tab. | | name | string | some component-oriented ui components can also be driven by a story id (name). ie the PropsTable can display component props, or story controls |

Meta

empty component for storybook addon-docs compatibility

Meta source code

Playground

Playground source code

properties

| Name | Type | Description | | ------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | scale | number | default scale for the zoom feature. If scale is set to 0, the zoom feature will be disabled. | | source | string | playground source option - valid when a Story is not embedded inside the Playground. | | dark | boolean | whether to use the dark theme for the story source component. | | title | string | optional section title for the block. | | description | string | optional markdown description. | | id | string | optional id to be used for the block if no id is provided, one will be calculated automatically from the title. | | collapsible | boolean | if false, will nothave a collapsible frame. | | data-testid | string | testing id | | plain | boolean | inner container variant or plain if plain, skip the border and spacing around the children | | sx | ThemeUIStyleObject | | | ref | ((instance: HTMLDivElement) => void) | RefObject<HTMLDivElement> | | | openTab | ReactNode | by default, which tab to have open. | | visibleTabs | boolean | if true, the tabs on the panels will be visible | | background | BackgroundType | background pattern type | | direction | DirectionType | direction type | | actions | ActionItem[] | optional actions provided to the component |

PropsTable

PropsTable source code

properties

| Name | Type | Description | | -------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | extraColumns | Column<{}>[] | extra custom columns passed to the PropsTable. | | flat | boolean | if true, will flatten the group by | | onSelect | ((name: string, component: Component) => boolean | void) & ((event: SyntheticEvent<HTMLDivElement, Event>) => void) | callback to be called when the tab changes if the function returns false, it can stop chabging to the new tab | | ref | ((instance: HTMLDivElement) => void) | RefObject<HTMLDivElement> | | | title | string | optional section title for the block. | | sx | ThemeUIStyleObject | | | id | string | optional id to be used for the block if no id is provided, one will be calculated automatically from the title. | | visibility | ComponentVisibility | by default will show both controls and props tables user setting can display only props table or only controls | | of | any | Specify the component(s), for which to have information displayed. The default, a value of `"."` will indicate to display information for the current component (associated with the current Story). If an array of components is specified, each component will be displayed in a separate tab. | | name | string | some component-oriented ui components can also be driven by a story id (name). ie the PropsTable can display component props, or story controls | | description | string | optional markdown description. | | collapsible | boolean | if false, will nothave a collapsible frame. | | data-testid | string | testing id | | plain | boolean | inner container variant or plain |

Stories

Stories source code

properties

| Name | Type | Description | | ------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | dark | boolean | whether to display the dark theme storysource code component whether to use the dark theme for the story source component. | | id | string | optional id to be used for the block if no id is provided, one will be calculated automatically from the title. | | name | string | | | storyProps | any | | | scale | number | default scale for the zoom feature. If scale is set to 0, the zoom feature will be disabled. | | source | string | playground source option - valid when a Story is not embedded inside the Playground. | | title | string | optional section title for the block. | | description | string | optional markdown description. | | collapsible | boolean | if false, will nothave a collapsible frame. | | data-testid | string | testing id | | plain | boolean | inner container variant or plain if plain, skip the border and spacing around the children | | sx | ThemeUIStyleObject | | | ref | ((instance: HTMLDivElement) => void) | RefObject<HTMLDivElement> | | | openTab | ReactNode | by default, which tab to have open. | | visibleTabs | boolean | if true, the tabs on the panels will be visible | | background | BackgroundType | background pattern type | | direction | DirectionType | direction type | | actions | ActionItem[] | optional actions provided to the component |

Story

Story source code

properties

| Name | Type | Description | | ------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------- | | ref | Ref<HTMLDivElement> | ref can be used by blocks embedding Story - ie ally plugin | | onRender | () => void | used by other blocks ie ally plugin uses it launch a new ally test on re-render | | wrapper | StoryWrapperType | wrapper type - can be an iframe or just regular react | | iframeStyle | CSSProperties | if an iframe wrapper - this is additional iframe style | | id | string | optional id to be used for the block if no id is provided, one will be calculated automatically from the title. | | name | string | | | title | string | optional section title for the block. | | description | string | optional markdown description. | | collapsible | boolean | if false, will nothave a collapsible frame. | | data-testid | string | testing id | | plain | boolean | inner container variant or plain | | sx | ThemeUIStyleObject | |

StoryConfig

StoryConfig source code

properties

| Name | Type | Description | | ------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | title | string | optional section title for the block. | | description | string | optional markdown description. | | id | string | optional id to be used for the block if no id is provided, one will be calculated automatically from the title. | | collapsible | boolean | if false, will nothave a collapsible frame. | | data-testid | string | testing id | | plain | boolean | inner container variant or plain | | sx | ThemeUIStyleObject | | | ref | ((instance: HTMLDivElement) => void) | RefObject<HTMLDivElement> | | | sourceProps | SourceProps | | | name | string | |

StorySource

StorySource source code

properties

| Name | Type | Description | | ------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | viewStyle | ViewStyle | initial view mode | | sourceProps | SourceProps | source code options | | title | string | optional section title for the block. | | description | string | optional markdown description. | | id | string | optional id to be used for the block if no id is provided, one will be calculated automatically from the title. | | collapsible | boolean | if false, will nothave a collapsible frame. | | data-testid | string | testing id | | plain | boolean | inner container variant or plain | | sx | ThemeUIStyleObject | | | ref | ((instance: HTMLDivElement) => void) | RefObject<HTMLDivElement> | | | name | string | |

Subtitle

Subtitle source code

properties

| Name | Type | Description | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | | id | string | | | name | string | | | children | string | (string & {}) | (string & ReactElement<any, string | ((props: any) => ReactElement<any, any>) | (new (props: any) => Component<any, any, any>)>) | (string & ReactNodeArray) | (string & ReactPortal) | text to be displayed in the component. | | as | "h2" | "h1" | "h3" | "h4" | "h5" | DOM node type to render as. By default h3. | | ref | ((instance: HTMLHeadingElement) => void) | RefObject<HTMLHeadingElement> | | | sx | ThemeUIStyleObject | |

Title

Title source code

properties

| Name | Type | Description | | -------------- | ---------------------------------------------------------------------- | ----------- | | contributors | boolean | | | id | string | | | name | string | | | sx | ThemeUIStyleObject | | | ref | ((instance: HTMLDivElement) => void) | RefObject<HTMLDivElement> | |

BlockContextProvider

BlockContextProvider source code

properties

| Name | Type | Description | | ---- | -------- | ----------- | | id | string | |

ControlsProvider

ControlsProvider source code

ThemeProvider

ThemeProvider source code

PageContextContainer

PageContextContainer source code

DocsContainer

DocsContainer source code

properties

| Name | Type | Description | | -------- | --------- | ----------- | | active | boolean | |

AddonPanel

AddonPanel source code

properties

| Name | Type | Description | | -------- | --------- | ----------- | | active | boolean | | | api* | API | |

PropsTablePanel

PropsTablePanel source code

properties

| Name | Type | Description | | -------- | --------- | ----------- | | active | boolean | | | api* | API | |

StoryConfigPanel

StoryConfigPanel source code

properties

| Name | Type | Description | | -------- | --------- | ----------- | | active | boolean | | | api* | API | |

StorySourcePanel

StorySourcePanel source code

properties

| Name | Type | Description | | -------- | --------- | ----------- | | active | boolean | | | api* | API | |