Storybook for V4Fire

Table of Contents

• Requirements
• Getting Started
  • In a project without Storybook
• Writing stories
  • Extending stories in the upper layers

Requirements

• V4Fire >= 4.x
• Storybook >= 7.x
• Node.js >= 18

Getting Started

In a project without Storybook

Follow the prompts after running this command in your V4Fire project's root directory:

npx [email protected] init --type html
yarn remove @storybook/html @storybook/html-webpack5
yarn add -E -D @v4fire/storybook-framework-webpack5 @v4fire/storybook

Change all versions to exact in package.json.

Check .storybook directory, change language of underlying files to javascript if needed.

Rename .babelrc.json to babel.config.js, and change it's contents to:

'use strict';

module.exports = {
	sourceType: 'unambiguous',
	presets: [
		['@babel/preset-typescript'],
		['@babel/preset-env']
	]
};

More on getting started with Storybook

Writing stories

Writing stories for v4fire is fairly simple, but a significant limitation to note is: only the import type can be used for the source code of the components, since *.ss files cannot be parsed by the storybook.

Take, for instance, a component named b-bottom-slide with the following hierarchy:

src/components/base/b-bottom-slide
	b-bottom-slide.ts
	b-bottom-slide.ss
	b-bottom-slide.styl
	...

If a component doesn't have too many stories, you can create a single file:

// src/components/base/b-bottom-slide/b-bottom-slide.stories.ts 

// Typings for writing a story
import type { Meta, StoryObj } from '@v4fire/storybook';
// Only import type can be used for components
import type bBottomSlide from 'components/base/b-bottom-slide/b-bottom-slide';
// The `?raw` suffix at the end is mandatory - it loads the markdown as a raw string
import readme from 'components/base/b-bottom-slide/README.md?raw';

const config: Meta<bBottomSlide> = {
	// Title of the story - it could be anything,
	// however, maintaining the hierarchy of components is recommended
	title: 'Base/bBottomSlide',
	// The component name must be written in dash-case
	component: 'b-bottom-slide',
	// If `autodocs` is specified, documentation will be generated
	tags: ['autodocs'],
	argTypes: {
		heightMode: {control: 'inline-radio', options: ['full', 'content']}
	},
	parameters: {
		docs: {
			// Include readme in autogenerated docs
			readme
		}
	}
};

export default config;

// Stories for the component are outlined below

// For more on writing stories with args: https://storybook.js.org/docs/html/writing-stories/args
export const Default: StoryObj<bBottomSlide> = {
	args: {
		heightMode: 'content',
		steps: [50],
		visible: 60,
		'slot-default': 'Hello'
	}
};

Otherwise, the stories should be divided among multiple files. To accomplish this, create a stories directory within the module:

src/components/base/b-bottom-slide/stories
	b-bottom-slide.stories.ts
	b-bottom-slide-steps.stories.ts
	b-bottom-slide-gestures.stories.ts

Note that prefixing all story files with b-bottom-slide is mandatory.

The file b-bottom-slide.stories.ts serves as the main story file. It is essential, and it should include documentation along with a readme file.

Extending stories in the upper layers

V4Fire, as a framework, anticipates projects to have layers. Therefore, it is essential to be able to override stories in upper layers. This can be achieved by creating a story file in the upper layer:

// src/components/base/b-bottom-slide/b-bottom-slide.stories.ts

// Import the base config and stories from the underlying layer (`@super` is not supported)
import config, { Default } from '@v4fire/client/components/base/b-bottom-slide/b-bottom-slide.stories';

export default {
	// The title must be set statically since the storybook
	// performs a static analysis of story files
	title: 'Base/bBottomSlide',
	// Tags must also be set statically for the same reasons
	tags: ['autodocs'],
	// Spread the parent configuration
	...config,
	parameters: {
		...config.parameters,
		// Overwrite a parameter
		backgrounds: {default: 'light'}
	}
};

// Manually re-export all parent stories 
export { Default };

P.S. The name of the file should match the parent's. Otherwise, both the overridden and parent's stories would be included.