@sit-onyx/storybook-utils

Storybook utilities for Vue.

Changelog

A full changelog can be found here.

Installation

Install the npm package with your corresponding package manager:

pnpm

pnpm add -D @sit-onyx/storybook-utils

npm

npm install -D @sit-onyx/storybook-utils

yarn

yarn install -D @sit-onyx/storybook-utils

Utilities

createPreview

Creates a default Storybook preview configuration for a project that uses onyx. Includes the following features:

• Improved controls (sorting and expanded controls so descriptions etc. are also shown in a single story)
• Setup for dark mode (including docs page). Requires addon @vueless/storybook-dark-mode (maintenance form of previous storybook-dark-mode) to be enabled in .storybook/main.ts file
• Custom Storybook theme using onyx colors (light and dark mode)
• Configure viewports / breakpoints as defined by onyx
• Logs Vue emits as Storybook actions
• Source code transformer that formats the code snippets with prettier and adds imports for used icons, flags and onyx components

.storybook/preview.ts

import { createPreview } from "@sit-onyx/storybook-utils";
import "@sit-onyx/storybook-utils/style.css";

const preview = {
  // we need to destructure here because as of Storybook 7.6
  // it can not statically analyze that the `preview` variable is an object
  ...createPreview({
    // optional overrides...
  }),
};

export default preview;

.storybook/main.ts

import type { StorybookConfig } from "@storybook/vue3-vite";

const config: StorybookConfig = {
  addons: ["@vueless/storybook-dark-mode"],
  // ...
};

export default config;

withVModelDecorator

Defines a custom decorator that will implement event handlers for all v-models. So the Storybook controls are updated live when the user interacts with the component.

import { withVModelDecorator } from "@sit-onyx/storybook-utils";

export default {
  decorators: [withVModelDecorator()],
};

createTheme

Creates a custom theme for Storybook that uses onyx colors. See the Storybook Theming docs for further information.

TIP

If you are using createPreview(), the custom light and dark theme will already be set up for you.

.storybook/manager.ts

import { createTheme } from "@sit-onyx/storybook-utils";
import { addons } from "storybook/manager-api";

addons.setConfig({
  theme: createTheme({
    base: "light", // choose whether you want a light or dark theme
  }),
});

.storybook/preview.ts

import { createTheme } from "@sit-onyx/storybook-utils";
import type { Preview } from "@storybook/vue3-vite";

const preview: Preview = {
  parameters: {
    docs: {
      theme: createTheme({
        base: "light", // choose whether you want a light or dark theme
      }),
    },
  },
};

export default preview;

withNativeEventLogging

Allows logging and documentation for the passed native event listeners in Storybook. These will be documented in a extra "Relevant HTML events" section in the Storybook documentation.

import { withNativeEventLogging } from "@sit-onyx/storybook-utils";

const meta: Meta<typeof OnyxButton> = {
  title: "Buttons/Button",
  component: OnyxButton,
  argTypes: {
    somethingElse: { ...someOtherArgType },
    ...withNativeEventLogging(["onClick"]),
  },
};

createActionLoggerWrapper

Wraps the original component and adds Storybook action logging. This is useful for slotted child components that emit relevant events.

Returns a wrapped component, which can be used in place of the original component.

import { createActionLoggerWrapper } from "@sit-onyx/storybook-utils";
import _ChildComponent from "./_ChildComponent.vue";

// Usual story setup...

/**
 * Wrapped child component
 */
const ChildComponent = createActionLoggerWrapper(_ChildComponent, ["onChildEmit"]);

/**
 * Use in a story like you usually would:
 */
export const Default = {
  args: {
    propName: 'Value'
    someSlot: () => h(ChildComponent, { label: "Item 1" }),
  },
} satisfies Story;