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

yarn install

Development

Run Storybook

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

Build for Production

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

Type Checking

yarn type-check

Linting

yarn lint
yarn lint:fix

Testing

yarn test
yarn test:ui
yarn test:coverage

Usage

Basic Usage

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

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

Custom Tour Configuration

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

Using the Hook Directly

import { useTour } from '@principal-ade/living-documentation-tour';

function MyComponent() {
  const { startTour, stopTour, goToStep } = useTour({
    steps: [
      // your tour steps
    ],
  });

  return (
    <div>
      <button onClick={startTour}>Start Tour</button>
      <button onClick={stopTour}>Stop Tour</button>
      <button onClick={() => goToStep(2)}>Jump to Step 3</button>
    </div>
  );
}

Architecture

Design Decisions

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

Component Structure

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

Alternatives Considered

• 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

TourableEditorLayout Props

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

TourConfig

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

useTour Hook

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