flowsterix

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# Flowsterix

Guided tours and onboarding flows for React applications. State machine-based, fully typed, with built-in persistence.

## Getting Started

### 1. Install the packages

```bash
npm install @flowsterix/core @flowsterix/react motion
```

### 2. Add UI components via shadcn

```bash
npx shadcn@latest add https://flowsterix.com/r/tour-hud.json
```

This installs everything: overlay, popover, controls, progress, and step content primitives.

### 3. Define your first flow

```tsx
import { createFlow } from '@flowsterix/core'
import { StepContent, StepTitle, StepText } from '@/components/step-content'

export const onboardingFlow = createFlow({
  id: 'onboarding',
  version: { major: 1, minor: 0 },
  autoStart: true,
  steps: [
    {
      id: 'welcome',
      target: 'screen',
      advance: [{ type: 'manual' }],
      content: (
        <StepContent>
          <StepTitle>Welcome!</StepTitle>
          <StepText>Let us show you around.</StepText>
        </StepContent>
      ),
    },
    {
      id: 'feature',
      target: { selector: '[data-tour-target="main-feature"]' },
      advance: [{ type: 'event', event: 'click', on: 'target' }],
      content: (
        <StepContent>
          <StepTitle>Try this feature</StepTitle>
          <StepText>Click this button to continue.</StepText>
        </StepContent>
      ),
    },
  ],
})
```

### 4. Add to your app

```tsx
import { TourProvider } from '@flowsterix/react'
import { TourHUD } from '@/components/tour-hud'
import { onboardingFlow } from './flows'

export function App({ children }) {
  return (
    <TourProvider flows={[onboardingFlow]} storageNamespace="my-app">
      <TourHUD />
      {children}
    </TourProvider>
  )
}
```

That's it. The `target` selector matches any element in your DOM.

---

## Using with AI Assistants

Install the Flowsterix skill to help AI agents implement tours in your codebase:

```bash
npx skills kvngrf/flowsterix
```

The skill provides patterns for step definitions, advance rules, lifecycle hooks, router integration, and more. Works with Claude Code, Cursor, and other AI coding assistants.

---

## DevTools

Debug and manage your flows during development:

```tsx
import { DevToolsProvider } from '@flowsterix/react/devtools'

export function App({ children }) {
  return (
    <TourProvider flows={[onboardingFlow]} storageNamespace="my-app">
      <DevToolsProvider enabled={process.env.NODE_ENV === 'development'}>
        <TourHUD />
        {children}
      </DevToolsProvider>
    </TourProvider>
  )
}
```

**Features:**
- **Steps Tab** - Drag-and-drop reorder, jump to any step, track active state
- **Flows Tab** - View all registered flows, edit JSON state, delete flow storage
- **Element Grabber** - Click any element to copy its selector for step targets

---

## Features

- **Declarative flows** - Define steps with targets, content, and progression rules
- **5 advance rule types** - Manual, event, delay, route, predicate
- **Lifecycle hooks** - onEnter, onResume, onExit for UI synchronization
- **Persistence** - localStorage, API, or custom storage adapters
- **Versioning** - Semantic versions with migration support
- **Router integration** - TanStack Router, React Router, Next.js App/Pages
- **Accessibility** - Focus trapping, keyboard navigation, ARIA labels
- **Analytics hooks** - Event system for integrating with your tracking

## Documentation

| Guide                                               | Description                                            |
| --------------------------------------------------- | ------------------------------------------------------ |
| [DevTools](https://github.com/kvngrf/flowsterix/blob/HEAD/docs/guides/devtools.md)                 | Debug flows, manage state, capture element selectors   |
| [Storage Adapters](https://github.com/kvngrf/flowsterix/blob/HEAD/docs/guides/storage-adapters.md) | Persist state to localStorage, API, or custom backends |
| [Versioning](https://github.com/kvngrf/flowsterix/blob/HEAD/docs/guides/versioning.md)             | Handle flow updates and migrations                     |
| [Accessibility](https://github.com/kvngrf/flowsterix/blob/HEAD/docs/guides/accessibility.md)       | Focus management, ARIA, reduced motion                 |
| [Routing & Async](https://github.com/kvngrf/flowsterix/blob/HEAD/docs/guides/routing-and-async.md) | Router adapters, route-based steps, async targeting    |

## Shadcn Components

All UI components are available via the [shadcn registry](https://flowsterix.com):

```bash
# Individual components
npx shadcn@latest add https://flowsterix.com/r/tour-provider.json
npx shadcn@latest add https://flowsterix.com/r/tour-overlay.json
npx shadcn@latest add https://flowsterix.com/r/tour-controls.json
npx shadcn@latest add https://flowsterix.com/r/tour-progress.json

# Complete HUD (recommended)
npx shadcn@latest add https://flowsterix.com/r/tour-hud.json

# Example flow
npx shadcn@latest add https://flowsterix.com/r/onboarding-flow.json
```

## Examples

This repo includes example apps for different frameworks:

```bash
pnpm dev:react-vite     # TanStack Router
pnpm dev:react-router   # React Router v6
pnpm dev:next           # Next.js App Router
pnpm dev:shadcn         # shadcn component demo
```

## Browser Support

- Chrome/Edge 90+
- Firefox 90+
- Safari 15+

## License

MIT

---

## Development

```bash
# Install dependencies
pnpm install

# Run example app
pnpm dev

# Run tests
pnpm test        # Unit tests
pnpm test:e2e    # Playwright E2E tests

# Build packages
pnpm build

# Lint and format
pnpm lint
pnpm format
```

Flowsterix

Guided tours and onboarding flows for React applications. State machine-based, fully typed, with built-in persistence.

Getting Started

1. Install the packages

npm install @flowsterix/core @flowsterix/react motion

2. Add UI components via shadcn

npx shadcn@latest add https://flowsterix.com/r/tour-hud.json

This installs everything: overlay, popover, controls, progress, and step content primitives.

3. Define your first flow

import { createFlow } from '@flowsterix/core'
import { StepContent, StepTitle, StepText } from '@/components/step-content'

export const onboardingFlow = createFlow({
  id: 'onboarding',
  version: { major: 1, minor: 0 },
  autoStart: true,
  steps: [
    {
      id: 'welcome',
      target: 'screen',
      advance: [{ type: 'manual' }],
      content: (
        <StepContent>
          <StepTitle>Welcome!</StepTitle>
          <StepText>Let us show you around.</StepText>
        </StepContent>
      ),
    },
    {
      id: 'feature',
      target: { selector: '[data-tour-target="main-feature"]' },
      advance: [{ type: 'event', event: 'click', on: 'target' }],
      content: (
        <StepContent>
          <StepTitle>Try this feature</StepTitle>
          <StepText>Click this button to continue.</StepText>
        </StepContent>
      ),
    },
  ],
})

4. Add to your app

import { TourProvider } from '@flowsterix/react'
import { TourHUD } from '@/components/tour-hud'
import { onboardingFlow } from './flows'

export function App({ children }) {
  return (
    <TourProvider flows={[onboardingFlow]} storageNamespace="my-app">
      <TourHUD />
      {children}
    </TourProvider>
  )
}

That's it. The target selector matches any element in your DOM.

Using with AI Assistants

Install the Flowsterix skill to help AI agents implement tours in your codebase:

npx skills kvngrf/flowsterix

The skill provides patterns for step definitions, advance rules, lifecycle hooks, router integration, and more. Works with Claude Code, Cursor, and other AI coding assistants.

DevTools

Debug and manage your flows during development:

import { DevToolsProvider } from '@flowsterix/react/devtools'

export function App({ children }) {
  return (
    <TourProvider flows={[onboardingFlow]} storageNamespace="my-app">
      <DevToolsProvider enabled={process.env.NODE_ENV === 'development'}>
        <TourHUD />
        {children}
      </DevToolsProvider>
    </TourProvider>
  )
}

Features:

Steps Tab - Drag-and-drop reorder, jump to any step, track active state
Flows Tab - View all registered flows, edit JSON state, delete flow storage
Element Grabber - Click any element to copy its selector for step targets

Features

Declarative flows - Define steps with targets, content, and progression rules
5 advance rule types - Manual, event, delay, route, predicate
Lifecycle hooks - onEnter, onResume, onExit for UI synchronization
Persistence - localStorage, API, or custom storage adapters
Versioning - Semantic versions with migration support
Router integration - TanStack Router, React Router, Next.js App/Pages
Accessibility - Focus trapping, keyboard navigation, ARIA labels
Analytics hooks - Event system for integrating with your tracking

Documentation

Guide	Description
DevTools	Debug flows, manage state, capture element selectors
Storage Adapters	Persist state to localStorage, API, or custom backends
Versioning	Handle flow updates and migrations
Accessibility	Focus management, ARIA, reduced motion
Routing & Async	Router adapters, route-based steps, async targeting

Shadcn Components

All UI components are available via the shadcn registry:

# Individual components
npx shadcn@latest add https://flowsterix.com/r/tour-provider.json
npx shadcn@latest add https://flowsterix.com/r/tour-overlay.json
npx shadcn@latest add https://flowsterix.com/r/tour-controls.json
npx shadcn@latest add https://flowsterix.com/r/tour-progress.json

# Complete HUD (recommended)
npx shadcn@latest add https://flowsterix.com/r/tour-hud.json

# Example flow
npx shadcn@latest add https://flowsterix.com/r/onboarding-flow.json

Examples

This repo includes example apps for different frameworks:

pnpm dev:react-vite     # TanStack Router
pnpm dev:react-router   # React Router v6
pnpm dev:next           # Next.js App Router
pnpm dev:shadcn         # shadcn component demo

Browser Support

Chrome/Edge 90+
Firefox 90+
Safari 15+

License

MIT

Development

# Install dependencies
pnpm install

# Run example app
pnpm dev

# Run tests
pnpm test        # Unit tests
pnpm test:e2e    # Playwright E2E tests

# Build packages
pnpm build

# Lint and format
pnpm lint
pnpm format