Interactive tour component for showcasing the ADE editor layout
npm install @principal-ade/living-documentation-tourAn interactive tour component for showcasing the ADE (Autonomous Development Environment) editor layout. Perfect for landing pages, demos, and onboarding experiences.
- Driver.js Integration: Lightweight, framework-agnostic product tour library
- Reusable Component: Export and use in any React application
- Storybook Ready: Perfect your tour in Storybook before deploying
- Customizable: Fully configurable tour steps, themes, and behavior
- No Panel Modifications Needed: Works with existing panel system via orchestration layer
- TypeScript: Full type safety and IntelliSense support
``bash`
yarn install
`bash`
yarn storybook
This will start Storybook on http://localhost:6006 where you can:
- Preview different tour configurations
- Test auto-start and manual triggers
- Experiment with light/dark themes
- Perfect your tour before deployment
`bash`
yarn build
This creates a distributable package in the dist/ folder that can be:
- Published to npm
- Imported into your landing page
- Used in other applications
`bash`
yarn type-check
`bash`
yarn lint
yarn lint:fix
`bash`
yarn test
yarn test:ui
yarn test:coverage
`tsx
import { TourableEditorLayout } from '@principal-ade/living-documentation-tour';
import '@principal-ade/living-documentation-tour/tour.css';
function App() {
return (
theme="light"
onTourComplete={() => console.log('Tour completed!')}
/>
);
}
`
`tsx
import { TourableEditorLayout, TourConfig } from '@principal-ade/living-documentation-tour';
const customTour: TourConfig = {
showProgress: true,
allowClose: true,
steps: [
{
popover: {
title: 'Welcome!',
description: 'Let us show you around.',
},
},
{
element: '#panel-left',
popover: {
title: 'Documentation Panel',
description: 'Find all your docs here.',
side: 'right',
},
},
// Add more steps...
],
};
function App() {
return (
tourConfig={customTour}
/>
);
}
`
`tsx
import { useTour } from '@principal-ade/living-documentation-tour';
function MyComponent() {
const { startTour, stopTour, goToStep } = useTour({
steps: [
// your tour steps
],
});
return (
Architecture
$3
No Panel Modifications Required: The tour functionality is implemented as a higher-level orchestration layer that uses existing panel APIs:
- TabGroup controlled mode for programmatic tab switching
- SnapCarousel navigation methods
- Event bus for inter-panel communication
- Layout props for showing/hiding panels
This approach means:
- ✅ Panels remain generic and reusable
- ✅ Tour logic is decoupled from panel implementation
- ✅ Easy to maintain and update
- ✅ Can be used with any panel configuration
$3
`
src/
├── components/
│ ├── TourableEditorLayout.tsx # Main component
│ └── TourableEditorLayout.stories.tsx # Storybook stories
├── hooks/
│ └── useTour.ts # Driver.js integration hook
├── tour-configs/
│ └── defaultEditorTour.ts # Default tour configuration
├── types/
│ └── index.ts # TypeScript definitions
└── index.ts # Public exports
`Storybook Stories
We provide several pre-configured stories:
- Default: Auto-start tour with default configuration
- ManualStart: Tour doesn't start automatically
- DarkTheme: Dark mode variant
- CustomTour: Example of custom tour steps
- MinimalTour: Lightweight tour with minimal UI
- LandingPageDemo: Full-featured demo for marketing sites
Tour Library: Driver.js
We chose Driver.js for the following reasons:
- ✅ MIT License: Free for commercial use
- ✅ Lightweight: 82.5 kB bundle size, no dependencies
- ✅ Framework-agnostic: Works seamlessly with React
- ✅ Excellent highlighting: Powerful element highlighting capabilities
- ✅ Clean API: Simple and intuitive to use
$3
- Shepherd.js: Requires commercial license (AGPL), smaller ecosystem
- Intro.js: Requires paid license for commercial use ($9.99+)
- React Joyride: React-specific, good alternative if you need React-native features
API Reference
$3
| Prop | Type | Default | Description |
|------|------|---------|-------------|
|
autoStart | boolean | false | Start tour automatically on mount |
| tourConfig | TourConfig | defaultEditorTour | Custom tour configuration |
| onTourComplete | () => void | - | Callback when tour completes |
| onTourClose | () => void | - | Callback when tour is closed |
| initialLayout | object | See below | Initial panel configuration |
| theme | 'light' \| 'dark' | 'light' | Visual theme |$3
| Property | Type | Default | Description |
|----------|------|---------|-------------|
|
steps | TourStep[] | [] | Array of tour steps |
| showProgress | boolean | true | Show progress indicator |
| allowClose | boolean | true | Allow closing the tour |
| overlayOpacity | number | 0.5 | Overlay opacity (0-1) |
| smoothScroll | boolean | true | Smooth scroll to elements |
| animate | boolean | true | Animate transitions |$3
`tsx
const { startTour, stopTour, goToStep, driver } = useTour(config);
`Returns:
-
startTour(): Start the tour
- stopTour(): Stop/destroy the tour
- goToStep(index): Jump to specific step
- driver`: Driver.js instance for advanced control1. Make changes to components
2. Test in Storybook
3. Run type-check and linting
4. Build to ensure no errors
5. Submit PR
MIT