@vitus-labs/rocketstories

Auto-generated Storybook stories from rocketstyle components.

One factory call gives you a complete Storybook setup — default story, dimension showcases, custom renders, and list views. Auto-detects rocketstyle dimensions, generates controls for pseudo-states, and supports configurable layouts. Also works with plain React components.

Features

• Zero-boilerplate stories — .main(), .dimension(), .render(), .list() output methods
• Auto dimension detection — reads rocketstyle component dimensions and generates showcases
• Storybook controls — auto-generated arg table with pseudo-state toggles
• Configurable layout — direction, alignment, gap for story rendering
• Immutable chaining — .attrs(), .controls(), .storyOptions(), .config()
• Works with any component — rocketstyle components get enhanced features, plain components work too

Installation

npm install @vitus-labs/rocketstories

Quick Start

// Button.stories.tsx
import { init } from '@vitus-labs/rocketstories'
import Button from './Button'

const storyOf = init({ decorators: [ThemeDecorator] })
const stories = storyOf(Button).attrs({ label: 'Click me' })

export default stories.init()

export const Default = stories.main()
export const States = stories.dimension('states')
export const Sizes = stories
  .storyOptions({ direction: 'inline', gap: 24 })
  .dimension('sizes')

API

rocketstories(component, options?)

One-shot factory. Creates a story builder for the given component.

import { rocketstories } from '@vitus-labs/rocketstories'

const stories = rocketstories(Button, {
  storyOptions: { gap: 24, direction: 'rows' },
  decorators: [ThemeDecorator],
})

init(options?)

Curried factory for shared configuration across multiple components.

import { init } from '@vitus-labs/rocketstories'

const storyOf = init({
  storyOptions: { gap: 16, direction: 'rows', alignY: 'top' },
  decorators: [ThemeDecorator],
})

// Reuse for multiple components
const buttonStories = storyOf(Button)
const inputStories = storyOf(Input)

Output Methods

.init()

Returns the Storybook default export (title, component, argTypes).

export default stories.init()

.main()

Renders the component in its default state with Storybook controls.

export const Default = stories.main()

.dimension(name, options?)

Renders all values of a specific dimension side by side. Only available for rocketstyle components.

export const States = stories.dimension('states')
export const Sizes = stories.dimension('sizes')

// Ignore specific values
export const States = stories.dimension('states', { ignore: ['default'] })

.render(callback)

Custom render function for full control.

export const Custom = stories.render((props) => (
  <div style={{ display: 'flex', gap: 16 }}>
    <Button {...props} state="primary" label="Primary" />
    <Button {...props} state="danger" label="Danger" />
  </div>
))

.list(options)

Renders a list of component instances using @vitus-labs/elements List.

export const ItemList = stories.list({
  data: ['Apple', 'Banana', 'Cherry'],
  valueName: 'label',
})

Chaining Methods

All chaining methods return a new builder instance.

.attrs(props)

Set default props for all stories.

stories.attrs({ label: 'Button', size: 'md' })

.controls(config)

Define Storybook arg table controls.

stories.controls({
  label: { type: 'text', value: 'Click me' },
  disabled: { type: 'boolean', value: false },
  size: { type: 'select', options: ['sm', 'md', 'lg'], value: 'md' },
})

.storyOptions(options)

Configure story layout rendering.

stories.storyOptions({
  direction: 'inline',  // 'inline' | 'rows'
  alignX: 'left',       // 'left' | 'center' | 'right' | 'spaceBetween'
  alignY: 'center',     // 'top' | 'center' | 'bottom' | 'spaceBetween'
  gap: 24,              // spacing between items
  pseudo: true,         // show pseudo-state controls (hover, focus, etc.)
})

.config(options)

Update general configuration.

stories.config({
  name: 'CustomStoryName',
  decorators: [NewDecorator],
})

.replaceComponent(component)

Swap the component being showcased.

stories.replaceComponent(EnhancedButton)

.decorators(decorators)

Add Storybook decorators.

stories.decorators([ThemeDecorator, LayoutDecorator])

Rocketstyle Integration

For rocketstyle components, rocketstories automatically:

1. Detects all dimensions via getStaticDimensions()
2. Generates controls for pseudo-states (hover, focus, pressed, active)
3. Groups rocketstyle-specific controls under "Rocketstyle (Vitus-Labs)"
4. Enables .dimension() stories for each registered dimension

Plain React Components

Non-rocketstyle components work with .main(), .render(), and .list(). The .dimension() method returns null for plain components.

Peer Dependencies

| Package | Version | | ------- | ------- | | react | >= 19 | | @storybook/react | * | | @vitus-labs/core | * | | @vitus-labs/rocketstyle | * | | @vitus-labs/unistyle | * |

License

MIT