Storybook addon

The walkerOS Storybook addon integrates event tracking visualization into Storybook. It enables developers to inspect walker attributes, monitor real-time events, and visually highlight tagged elements while building components.

Installation

npm install --save-dev @walkeros/storybook-addon

Setup

Register the addon in your Storybook configuration:

// .storybook/main.ts
const config: StorybookConfig = {
addons: ['@walkeros/storybook-addon'],
};

export default config;

Configuration

Optionally customize the addon behavior in your preview file:

// .storybook/preview.ts
const preview: Preview = {
parameters: {
  walkerOS: {
    prefix: 'data-elb',      // Custom data attribute prefix
    autoRefresh: true,       // Auto-refresh on story changes
  },
},
};

export default preview;

Option	Type	Default	Description
prefix	string	'data-elb'	Data attribute prefix for walker attributes
autoRefresh	boolean	true	Automatically refresh events when story or controls change

Features

The addon panel provides three tabs for inspecting walkerOS data:

Events tab

Displays all detected walkerOS events in the current story's DOM. Click "Update events" to manually refresh the event list.

Live events tab

Captures events in real-time as you interact with components. Shows timestamps for each event and stores up to 50 events. Use the "Clear" button to reset.

Skeleton tab

Shows a hierarchical tree of the entities found in the DOM, with each entity's properties resolved onto it the way the walker reads them:

• Generic (data-elb-) and scoped (data-elb_) values are shown on the entities that consume them, labeled by origin (G for generic, S for scoped; directly declared properties are unlabeled)
• Expandable/collapsible entity structure
• Click to view element markup
• Attribute counts by type

Visual highlighting

Toggle buttons highlight elements with different attribute types:

Attribute	Color	Data Attribute
Globals	Cyan	data-elbglobals
Context	Yellow	data-elbcontext
Entity	Green	data-elb
Property	Red	data-elb-*, data-elb_
Action	Purple	data-elbaction

Multiple highlights can be active simultaneously, displaying layered outlines.

Usage in stories

Import dataElbArgTypes to add walkerOS controls to your stories:

import { dataElbArgTypes } from '@walkeros/storybook-addon';

export default {
title: 'Components/Button',
argTypes: {
  ...dataElbArgTypes,
},
};

Troubleshooting

No events detected:

• Verify components have data-elb attributes
• Check the prefix matches your configuration
• Click "Update events" to manually refresh

Highlights not showing:

• Ensure the story iframe has loaded
• Toggle highlights off and on again
• Check browser console for errors

Next steps

• Storybook Demo: See the addon in action
• HTML Attributes: Learn walker attribute syntax
• Browser Source: Understand DOM event capture