Living Documentation Tour

An interactive tour component for showcasing the ADE (Autonomous Development Environment) editor layout. Perfect for landing pages, demos, and onboarding experiences.

Features

- 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

Installation

``bash
yarn install
`

Development

$3

`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

$3

`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

$3

`bash
yarn type-check
`

$3

`bash
yarn lint
yarn lint:fix
`

$3

`bash
yarn test
yarn test:ui
yarn test:coverage
`

Usage

$3

`tsx
import { TourableEditorLayout } from '@principal-ade/living-documentation-tour';
import '@principal-ade/living-documentation-tour/tour.css';

function App() {
return (
autoStart={true}
theme="light"
onTourComplete={() => console.log('Tour completed!')}
/>
);
}
`

$3

`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 (
autoStart={true}
tourConfig={customTour}
/>
);
}
`

$3

`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 control

Contributing

1. Make changes to components
2. Test in Storybook
3. Run type-check and linting
4. Build to ensure no errors
5. Submit PR

License

MIT