walkerOS
Visualize, debug, and validate walkerOS event tracking in your Storybook stories. Real-time event capture with visual DOM highlighting for data-attribute based tagging.
@walkeros/storybook-addon
A Storybook addon that integrates walkerOS tagging support for data collection and tracking validation. Visualize, debug, and validate walkerOS events in your stories.
Features
- 📊 Events Tab: View all detected walkerOS events with JSON syntax highlighting
- 🔴 Live Events Tab: Real-time event capture as you interact with components
- 🎯 Visual Highlighting: Toggle highlights for Context, Entity, Property, and Action attributes
- 🔄 Auto-refresh: Updates automatically when navigating stories or changing controls
- ⚙️ Custom Prefix Support: Configure custom data attribute prefixes
- 🚀 Zero Configuration: Works out of the box with walkerOS data attributes
Installation
npm install --save-dev @walkeros/storybook-addon
// .storybook/main.ts
const config: StorybookConfig = {
addons: ['@walkeros/storybook-addon'],
};
Usage
Basic Setup
- Install and register the addon
- Add walkerOS tracking to your components:
import { tagger } from '../utils/tagger';
export const Button = ({ label, onClick }) => {
const trackingProps = tagger('button').data({ label }).action('click').get();
return (
<button {...trackingProps} onClick={onClick}>
{label}
</button>
);
};
- Use in stories:
export const Primary: Story = {
args: {
label: 'Button',
dataElb: {
entity: 'button',
action: 'click',
data: { category: 'primary' },
},
},
};
Custom Prefix Configuration
Configure a custom prefix in your Storybook preview:
// .storybook/preview.ts
const preview: Preview = {
parameters: {
walkerOS: {
prefix: 'data-elb',
autoRefresh: true,
},
},
};
Update your tagger configuration to match:
// utils/tagger.ts
const taggerInstance = createTagger({
prefix: 'data-elb',
});
Addon Panels
Events Tab
Shows all walkerOS events detected in the current story's DOM. Click "Update events" to manually refresh.
Live Events Tab
Captures events in real-time as you interact with components. Events are automatically sent to the panel via the walker collector.
Visual Highlighting
Use the highlight toggles to visually identify different types of walkerOS attributes:
- Context: Yellow outline for context attributes
- Entity: Green outline for entity attributes
- Property: Red outline for property attributes
- Action: Purple outline for action attributes
API Reference
import { DataElb, dataElbArgTypes } from '@walkeros/storybook-addon';
DataElb
Interface
interface DataElb {
entity?: string;
trigger?: string;
action?: string;
data?: WalkerOS.Properties;
context?: WalkerOS.Properties;
globals?: WalkerOS.Properties;
link?: Record<string, string>;
}
Story ArgTypes
export default {
argTypes: {
...dataElbArgTypes,
// Adds a walkerOS object control to your story
},
};
Configuration
Option | Type | Default | Description |
---|---|---|---|
prefix |
string |
'data-elb' |
Data attribute prefix (must match your walker setup) |
autoRefresh |
boolean |
true |
Auto-refresh events on story/control changes |
Troubleshooting
Events Not Showing
- Ensure components have walkerOS attributes:
data-elb
,data-elb-*
, etc. - Check prefix matches between addon config and tagger config
- Try manual refresh with "Update events" button
Live Events Not Working
- Verify walker is properly initialized with matching prefix
- Check browser console for walker initialization errors
- Ensure components generate events when clicked/interacted with
Highlighting Not Working
- Confirm prefix configuration matches in both addon and tagger
- Check that elements have the expected data attributes in DOM inspector
License
MIT © elbwalker GmbH
Links
- alexanderkirtzel