ac-react-onboarding-guide/README.md

A customizable onboarding guide component for React applications

# Onboarding Guide Component Library

A customizable onboarding guide component for React applications. This library provides a step-by-step onboarding experience that can be easily integrated into any React application.

## Features

- **Step-by-step onboarding flow**
- **Responsive design**
- **Keyboard navigation**
- **Theming support** (light/dark mode)
- **Progress tracking**
- **Skippable steps**
- **Persistent state** (using localStorage)
- **Fully accessible** (WAI-ARIA compliant)
- **Customizable appearance**
- **TypeScript support**

## Installation

```bash
npm install @acme/onboarding-guide
# or
yarn add @acme/onboarding-guide
# or
pnpm add @acme/onboarding-guide
```

## Peer Dependencies

This library requires the following peer dependencies:

```json
{
  "react": "^18.0.0 || ^19.0.0",
  "react-dom": "^18.0.0 || ^19.0.0",
  "tailwindcss": "^3.0.0"
}
```

## Usage

### Basic Usage

```tsx
import { OnboardingProvider, OnboardingSidebar } from '@acme/onboarding-guide';

const steps = [
  {
    id: 'welcome',
    title: 'Welcome',
    description: 'Get started with our app',
    component: <WelcomeStep />,
  },
  {
    id: 'profile',
    title: 'Complete Profile',
    description: 'Set up your profile',
    component: <ProfileStep />,
  },
  {
    id: 'preferences',
    title: 'Preferences',
    description: 'Configure your preferences',
    component: <PreferencesStep />,
  },
];

function App() {
  return (
    <OnboardingProvider steps={steps}>
      <div className="flex h-screen">
        <OnboardingSidebar />
        <main className="flex-1 p-8">
          {/* Your app content */}
        </main>
      </div>
    </OnboardingProvider>
  );
}
```

### With Theme Provider

```tsx
import { ThemeProvider } from '@acme/onboarding-guide';

function App() {
  return (
    <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
      <OnboardingProvider steps={steps}>
        {/* Your app */}
      </OnboardingProvider>
    </ThemeProvider>
  );
}
```

### Programmatic Control

```tsx
import { useOnboarding } from '@acme/onboarding-guide';

function MyComponent() {
  const {
    currentStep,
    goToNextStep,
    goToPreviousStep,
    goToStep,
    skipOnboarding,
    completeOnboarding,
    isFirstStep,
    isLastStep,
    isCompleted,
    isSkipped,
  } = useOnboarding();

  return (
    <div>
      <h1>Current Step: {currentStep + 1}</h1>
      <button onClick={goToPreviousStep} disabled={isFirstStep}>
        Previous
      </button>
      <button onClick={goToNextStep}>
        {isLastStep ? 'Finish' : 'Next'}
      </button>
      <button onClick={skipOnboarding}>
        Skip
      </button>
    </div>
  );
}
```

## API Reference

### OnboardingProvider

The main provider component that manages the onboarding state.

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `steps` | `OnboardingStep[]` | `[]` | Array of onboarding steps |
| `initialStep` | `number` | `0` | Initial step index |
| `skipable` | `boolean` | `true` | Whether the onboarding can be skipped |
| `storageKey` | `string` | `'onboarding-steps'` | Key for localStorage |
| `onComplete` | `() => void` | `undefined` | Callback when onboarding is completed |
| `onSkip` | `() => void` | `undefined` | Callback when onboarding is skipped |
| `children` | `ReactNode` | - | Child components |

### OnboardingSidebar

A pre-built sidebar component for the onboarding flow.

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `className` | `string` | `''` | Additional CSS class names |
| `showProgress` | `boolean` | `true` | Show progress bar |
| `showStepTitles` | `boolean` | `true` | Show step titles |
| `showStepIcons` | `boolean` | `true` | Show step icons |
| `showNavigation` | `boolean` | `true` | Show navigation buttons |
| `showSkipButton` | `boolean` | `true` | Show skip button |
| `position` | `'left' \| 'right'` | `'left'` | Position of the sidebar |
| `width` | `number \| string` | `280` | Width of the expanded sidebar |
| `collapsedWidth` | `number \| string` | `80` | Width of the collapsed sidebar |
| `defaultCollapsed` | `boolean` | `false` | Whether the sidebar is collapsed by default |
| `collapsible` | `boolean` | `true` | Whether the sidebar can be collapsed |
| `onCollapseChange` | `(collapsed: boolean) => void` | `undefined` | Callback when the sidebar is toggled |

### useOnboarding

A hook to access the onboarding context.

#### Return Value

| Property | Type | Description |
|----------|------|-------------|
| `currentStep` | `number` | Current step index |
| `steps` | `OnboardingStep[]` | Array of all steps |
| `isFirstStep` | `boolean` | Whether the current step is the first step |
| `isLastStep` | `boolean` | Whether the current step is the last step |
| `isCompleted` | `boolean` | Whether the onboarding is completed |
| `isSkipped` | `boolean` | Whether the onboarding was skipped |
| `goToStep` | `(step: number) => void` | Go to a specific step |
| `goToNextStep` | `() => Promise<void>` | Go to the next step |
| `goToPreviousStep` | `() => Promise<void>` | Go to the previous step |
| `skipOnboarding` | `() => Promise<void>` | Skip the entire onboarding |
| `completeOnboarding` | `() => void` | Complete the onboarding |
| `resetOnboarding` | `() => void` | Reset the onboarding state |
| `updateStepStatus` | `(stepId: string, status: 'completed' \| 'in-progress' \| 'pending') => void` | Update the status of a step |

## Styling

This library uses [Tailwind CSS](https://tailwindcss.com/) for styling. Make sure to include Tailwind CSS in your project.

### Customization

You can customize the appearance by overriding the default styles using the `className` prop or by using Tailwind's utility classes.

## Accessibility

This library follows WAI-ARIA design patterns and includes proper keyboard navigation and screen reader support.

## License

MIT