npm package: @principal-ade/living-documentation-tour
Description: Interactive tour component for showcasing the ADE editor layout
Author: Principal ADE
Latest version: 0.1.4

# 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

### Run Storybook

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

### Build for Production

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

### Type Checking

```bash
yarn type-check
```

### Linting

```bash
yarn lint
yarn lint:fix
```

### Testing

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

## Usage

### Basic Usage

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

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

### Using the Hook Directly

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

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