react-guide-step 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 react-guide-step
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,258 @@
+# react-guide-step
+
+English | [简体中文](./README.zh-CN.md)
+
+A lightweight, zero-dependency React component library for building interactive product tours, onboarding walkthroughs, and step-by-step guided experiences.
+
+## Features
+
+- **Step-based tours** — Define a sequence of steps targeting any DOM element
+- **Spotlight overlay** — Highlights target elements while dimming the rest of the page
+- **Smart positioning** — Auto-calculates tooltip placement with 12 positions and viewport flip logic
+- **Keyboard navigation** — Navigate with arrow keys, Enter, and Escape
+- **Custom rendering** — Full control over step content via render props
+- **Persistence** — Optional localStorage-based completion tracking to avoid re-showing tours
+- **Auto-scroll** — Automatically scrolls target elements into view
+- **Element waiting** — Waits for async/lazy DOM elements to appear before proceeding
+- **Theming** — Customize colors, border radius, z-index, and animation duration
+- **i18n ready** — All button labels are configurable
+- **Lifecycle hooks** — `beforeEnter` and `afterLeave` async hooks per step
+- **Image preloading** — Preload step images to prevent layout shifts
+- **Tree-shakeable** — Zero runtime dependencies, ESM and CJS support
+
+## Installation
+
+```bash
+npm install react-guide-step
+```
+
+```bash
+yarn add react-guide-step
+```
+
+```bash
+pnpm add react-guide-step
+```
+
+> **Peer dependencies:** `react >= 18.0.0` and `react-dom >= 18.0.0`
+
+## Quick Start
+
+### 1. Define your tour steps
+
+```ts
+// tours/onboarding.ts
+import type { GuideStep } from 'react-guide-step';
+
+const steps: GuideStep[] = [
+  {
+    target: '#welcome-header',
+    title: 'Welcome!',
+    content: 'Let us show you around the app.',
+    placement: 'bottom',
+  },
+  {
+    target: '#sidebar-nav',
+    title: 'Navigation',
+    content: 'Use the sidebar to navigate between pages.',
+    placement: 'right',
+  },
+  {
+    target: '#create-btn',
+    title: 'Create',
+    content: 'Click here to create a new project.',
+    placement: 'bottom',
+    highlightPadding: 8,
+  },
+];
+```
+
+### 2. Set up the provider and start the tour
+
+```tsx
+import { GuideProvider, useGuide } from 'react-guide-step';
+import type { GuideOptions } from 'react-guide-step';
+import { steps } from './tours/onboarding';
+
+function App() {
+  const options: GuideOptions = {
+    steps,
+    maskClosable: true,
+    keyboardNavigation: true,
+    onComplete: () => console.log('Tour completed!'),
+    onSkip: (step) => console.log(`Skipped at step ${step}`),
+  };
+
+  const guide = useGuide(options);
+
+  return (
+    <GuideProvider guide={guide} options={options}>
+      <YourApp />
+      <button onClick={() => guide.start()}>Start Tour</button>
+    </GuideProvider>
+  );
+}
+```
+
+## API Reference
+
+### `useGuide(options)`
+
+The main hook that creates a guide controller.
+
+**Returns: `GuideController`**
+
+| Property | Type | Description |
+|---|---|---|
+| `start()` | `() => void` | Start the tour |
+| `stop()` | `() => void` | Stop the tour |
+| `next()` | `() => void` | Go to next step |
+| `prev()` | `() => void` | Go to previous step |
+| `goTo(index)` | `(number) => void` | Jump to a specific step |
+| `isActive` | `boolean` | Whether the tour is currently running |
+| `currentStep` | `number` | Current step index |
+| `totalSteps` | `number` | Total number of steps |
+| `isCompleted` | `boolean` | Whether the tour has been completed |
+
+### `GuideOptions`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `steps` | `GuideStep[]` | *required* | Array of tour steps |
+| `initialStep` | `number` | `0` | Starting step index |
+| `autoStart` | `boolean` | `false` | Auto-start the guide on mount |
+| `maskClosable` | `boolean` | `false` | Close guide when clicking the overlay |
+| `keyboardNavigation` | `boolean` | `true` | Enable keyboard navigation |
+| `scrollBehavior` | `ScrollBehavior` | `'smooth'` | Scroll behavior when scrolling target into view |
+| `persistKey` | `string` | — | localStorage key; completed tours won't re-show |
+| `theme` | `GuideTheme` | — | Custom theme overrides |
+| `labels` | `GuideLabels` | — | Custom button labels for i18n |
+| `onComplete` | `() => void` | — | Called when the tour finishes |
+| `onSkip` | `(stepIndex) => void` | — | Called when the tour is skipped |
+| `onStepChange` | `(stepIndex) => void` | — | Called on each step transition |
+
+### `GuideStep`
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `target` | `string \| HTMLElement` | *required* | CSS selector or element reference |
+| `title` | `string` | — | Step title |
+| `content` | `ReactNode` | — | Step description (supports text, JSX, images) |
+| `placement` | `Placement` | `'bottom'` | Tooltip position relative to target |
+| `customRender` | `(props: StepRenderProps) => ReactNode` | — | Custom render function |
+| `beforeEnter` | `() => void \| Promise<void>` | — | Async hook before entering step |
+| `afterLeave` | `() => void \| Promise<void>` | — | Async hook after leaving step |
+| `highlightPadding` | `number` | — | Extra padding around the spotlight (px) |
+| `waitForElement` | `boolean` | `false` | Wait for target element to appear in DOM |
+| `showArrow` | `boolean` | `true` | Show arrow pointing to target |
+| `allowInteraction` | `boolean` | `false` | Allow user interaction with highlighted element |
+| `preloadImages` | `string[]` | — | Image URLs to preload before this step is displayed |
+
+### `Placement`
+
+```
+'top' | 'top-start' | 'top-end'
+'bottom' | 'bottom-start' | 'bottom-end'
+'left' | 'left-start' | 'left-end'
+'right' | 'right-start' | 'right-end'
+'center'
+```
+
+### `GuideTheme`
+
+| Property | Type | Description |
+|---|---|---|
+| `primaryColor` | `string` | Primary button and accent color |
+| `textColor` | `string` | Text color |
+| `bgColor` | `string` | Tooltip background color |
+| `overlayColor` | `string` | Overlay/mask color |
+| `borderRadius` | `number` | Border radius in px |
+| `zIndex` | `number` | Base z-index for the guide layer |
+| `animationDuration` | `number` | Animation duration in ms |
+
+### `GuideLabels`
+
+| Property | Type | Description |
+|---|---|---|
+| `next` | `string` | "Next" button text |
+| `prev` | `string` | "Previous" button text |
+| `skip` | `string` | "Skip" button text |
+| `finish` | `string` | "Finish" button text |
+| `stepOf` | `string` | Step counter template, e.g. `"{current} of {total}"` |
+
+## Advanced Usage
+
+### Custom Step Rendering
+
+```tsx
+const steps: GuideStep[] = [
+  {
+    target: '#feature',
+    customRender: ({ step, stepIndex, totalSteps, next, prev, skip }) => (
+      <div className="my-custom-tooltip">
+        <h3>Step {stepIndex + 1} of {totalSteps}</h3>
+        <p>Your custom content here</p>
+        <div>
+          <button onClick={prev}>Back</button>
+          <button onClick={next}>Continue</button>
+          <button onClick={skip}>Skip Tour</button>
+        </div>
+      </div>
+    ),
+  },
+];
+```
+
+### Persistence
+
+Prevent completed tours from re-appearing by setting a `persistKey`:
+
+```ts
+const options: GuideOptions = {
+  steps,
+  persistKey: 'onboarding-v1',
+};
+```
+
+Completion state is stored in `localStorage` under the key `rgs:<persistKey>`. To reset, remove the key:
+
+```ts
+localStorage.removeItem('rgs:onboarding-v1');
+```
+
+### Async Step Hooks
+
+Run async operations before entering or after leaving a step:
+
+```ts
+const steps: GuideStep[] = [
+  {
+    target: '#dynamic-section',
+    title: 'Dynamic Content',
+    content: 'This section was loaded just for you.',
+    waitForElement: true,
+    beforeEnter: async () => {
+      await fetchAndRenderSection();
+    },
+    afterLeave: async () => {
+      await trackStepViewed();
+    },
+  },
+];
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Start demo dev server
+npm run dev
+
+# Build the library
+npm run build
+
+# Preview demo production build
+npm run preview
+```

package/README.zh-CN.md

@@ -0,0 +1,258 @@
+# react-guide-step
+
+[English](./README.md) | 简体中文
+
+一个轻量级、零依赖的 React 组件库，用于构建交互式产品导览、用户引导和分步引导体验。
+
+## 特性
+
+- **分步引导** — 定义一系列步骤，定位到任意 DOM 元素
+- **聚光灯遮罩** — 高亮目标元素，同时遮暗页面其他区域
+- **智能定位** — 自动计算提示框位置，支持 12 种定位方式和视口翻转逻辑
+- **键盘导航** — 支持方向键、Enter 和 Escape 键导航
+- **自定义渲染** — 通过 render props 完全控制步骤内容
+- **持久化** — 可选的 localStorage 完成状态跟踪，避免重复展示
+- **自动滚动** — 自动滚动目标元素到可视区域
+- **元素等待** — 等待异步/懒加载 DOM 元素出现后再继续
+- **主题定制** — 自定义颜色、圆角、层级和动画时长
+- **国际化支持** — 所有按钮文案均可配置
+- **生命周期钩子** — 每个步骤支持 `beforeEnter` 和 `afterLeave` 异步钩子
+- **图片预加载** — 预加载步骤图片，防止布局抖动
+- **Tree-shakeable** — 零运行时依赖，支持 ESM 和 CJS
+
+## 安装
+
+```bash
+npm install react-guide-step
+```
+
+```bash
+yarn add react-guide-step
+```
+
+```bash
+pnpm add react-guide-step
+```
+
+> **对等依赖：** `react >= 18.0.0` 和 `react-dom >= 18.0.0`
+
+## 快速开始
+
+### 1. 定义引导步骤
+
+```ts
+// tours/onboarding.ts
+import type { GuideStep } from 'react-guide-step';
+
+const steps: GuideStep[] = [
+  {
+    target: '#welcome-header',
+    title: '欢迎！',
+    content: '让我们带你了解这个应用。',
+    placement: 'bottom',
+  },
+  {
+    target: '#sidebar-nav',
+    title: '导航栏',
+    content: '使用侧边栏在不同页面之间切换。',
+    placement: 'right',
+  },
+  {
+    target: '#create-btn',
+    title: '创建',
+    content: '点击这里创建一个新项目。',
+    placement: 'bottom',
+    highlightPadding: 8,
+  },
+];
+```
+
+### 2. 设置 Provider 并启动引导
+
+```tsx
+import { GuideProvider, useGuide } from 'react-guide-step';
+import type { GuideOptions } from 'react-guide-step';
+import { steps } from './tours/onboarding';
+
+function App() {
+  const options: GuideOptions = {
+    steps,
+    maskClosable: true,
+    keyboardNavigation: true,
+    onComplete: () => console.log('引导完成！'),
+    onSkip: (step) => console.log(`在第 ${step} 步跳过`),
+  };
+
+  const guide = useGuide(options);
+
+  return (
+    <GuideProvider guide={guide} options={options}>
+      <YourApp />
+      <button onClick={() => guide.start()}>开始引导</button>
+    </GuideProvider>
+  );
+}
+```
+
+## API 参考
+
+### `useGuide(options)`
+
+创建引导控制器的主要 Hook。
+
+**返回值：`GuideController`**
+
+| 属性 | 类型 | 说明 |
+|---|---|---|
+| `start()` | `() => void` | 开始引导 |
+| `stop()` | `() => void` | 停止引导 |
+| `next()` | `() => void` | 跳转到下一步 |
+| `prev()` | `() => void` | 跳转到上一步 |
+| `goTo(index)` | `(number) => void` | 跳转到指定步骤 |
+| `isActive` | `boolean` | 引导是否正在运行 |
+| `currentStep` | `number` | 当前步骤索引 |
+| `totalSteps` | `number` | 总步骤数 |
+| `isCompleted` | `boolean` | 引导是否已完成 |
+
+### `GuideOptions`
+
+| 选项 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| `steps` | `GuideStep[]` | *必填* | 引导步骤数组 |
+| `initialStep` | `number` | `0` | 起始步骤索引 |
+| `autoStart` | `boolean` | `false` | 挂载时自动启动引导 |
+| `maskClosable` | `boolean` | `false` | 点击遮罩层关闭引导 |
+| `keyboardNavigation` | `boolean` | `true` | 启用键盘导航 |
+| `scrollBehavior` | `ScrollBehavior` | `'smooth'` | 滚动目标到可视区域时的滚动行为 |
+| `persistKey` | `string` | — | localStorage 键名；已完成的引导不会再次显示 |
+| `theme` | `GuideTheme` | — | 自定义主题覆盖 |
+| `labels` | `GuideLabels` | — | 自定义按钮文案（用于国际化） |
+| `onComplete` | `() => void` | — | 引导完成时的回调 |
+| `onSkip` | `(stepIndex) => void` | — | 引导被跳过时的回调 |
+| `onStepChange` | `(stepIndex) => void` | — | 每次步骤切换时的回调 |
+
+### `GuideStep`
+
+| 属性 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| `target` | `string \| HTMLElement` | *必填* | CSS 选择器或元素引用 |
+| `title` | `string` | — | 步骤标题 |
+| `content` | `ReactNode` | — | 步骤描述（支持文本、JSX、图片） |
+| `placement` | `Placement` | `'bottom'` | 提示框相对于目标的位置 |
+| `customRender` | `(props: StepRenderProps) => ReactNode` | — | 自定义渲染函数 |
+| `beforeEnter` | `() => void \| Promise<void>` | — | 进入步骤前的异步钩子 |
+| `afterLeave` | `() => void \| Promise<void>` | — | 离开步骤后的异步钩子 |
+| `highlightPadding` | `number` | — | 聚光灯周围的额外内边距（px） |
+| `waitForElement` | `boolean` | `false` | 等待目标元素出现在 DOM 中 |
+| `showArrow` | `boolean` | `true` | 显示指向目标的箭头 |
+| `allowInteraction` | `boolean` | `false` | 允许用户与高亮元素交互 |
+| `preloadImages` | `string[]` | — | 在显示此步骤前预加载的图片 URL |
+
+### `Placement`
+
+```
+'top' | 'top-start' | 'top-end'
+'bottom' | 'bottom-start' | 'bottom-end'
+'left' | 'left-start' | 'left-end'
+'right' | 'right-start' | 'right-end'
+'center'
+```
+
+### `GuideTheme`
+
+| 属性 | 类型 | 说明 |
+|---|---|---|
+| `primaryColor` | `string` | 主按钮和强调色 |
+| `textColor` | `string` | 文字颜色 |
+| `bgColor` | `string` | 提示框背景颜色 |
+| `overlayColor` | `string` | 遮罩层颜色 |
+| `borderRadius` | `number` | 圆角大小（px） |
+| `zIndex` | `number` | 引导层的基础 z-index |
+| `animationDuration` | `number` | 动画时长（ms） |
+
+### `GuideLabels`
+
+| 属性 | 类型 | 说明 |
+|---|---|---|
+| `next` | `string` | "下一步" 按钮文案 |
+| `prev` | `string` | "上一步" 按钮文案 |
+| `skip` | `string` | "跳过" 按钮文案 |
+| `finish` | `string` | "完成" 按钮文案 |
+| `stepOf` | `string` | 步骤计数模板，例如 `"{current} / {total}"` |
+
+## 进阶用法
+
+### 自定义步骤渲染
+
+```tsx
+const steps: GuideStep[] = [
+  {
+    target: '#feature',
+    customRender: ({ step, stepIndex, totalSteps, next, prev, skip }) => (
+      <div className="my-custom-tooltip">
+        <h3>第 {stepIndex + 1} 步，共 {totalSteps} 步</h3>
+        <p>你的自定义内容</p>
+        <div>
+          <button onClick={prev}>上一步</button>
+          <button onClick={next}>继续</button>
+          <button onClick={skip}>跳过引导</button>
+        </div>
+      </div>
+    ),
+  },
+];
+```
+
+### 持久化
+
+通过设置 `persistKey` 防止已完成的引导再次出现：
+
+```ts
+const options: GuideOptions = {
+  steps,
+  persistKey: 'onboarding-v1',
+};
+```
+
+完成状态存储在 `localStorage` 中，键名为 `rgs:<persistKey>`。要重置，移除该键即可：
+
+```ts
+localStorage.removeItem('rgs:onboarding-v1');
+```
+
+### 异步步骤钩子
+
+在进入或离开步骤时执行异步操作：
+
+```ts
+const steps: GuideStep[] = [
+  {
+    target: '#dynamic-section',
+    title: '动态内容',
+    content: '这个区域是专门为你加载的。',
+    waitForElement: true,
+    beforeEnter: async () => {
+      await fetchAndRenderSection();
+    },
+    afterLeave: async () => {
+      await trackStepViewed();
+    },
+  },
+];
+```
+
+## 开发
+
+```bash
+# 安装依赖
+npm install
+
+# 启动 demo 开发服务器
+npm run dev
+
+# 构建库
+npm run build
+
+# 预览 demo 生产构建
+npm run preview
+```

package/dist/components/Guide.d.ts

@@ -0,0 +1,2 @@
+import React from 'react';
+export declare const Guide: React.FC;

package/dist/components/GuideArrow.d.ts

@@ -0,0 +1,11 @@
+import React from 'react';
+import type { Placement } from '../types';
+interface GuideArrowProps {
+    arrowPos: {
+        x: number;
+        y: number;
+    };
+    placement: Placement;
+}
+export declare const GuideArrow: React.FC<GuideArrowProps>;
+export {};

package/dist/components/GuideOverlay.d.ts

@@ -0,0 +1,11 @@
+import React from 'react';
+import type { Placement } from '../types';
+interface GuideOverlayProps {
+    targetElement: HTMLElement | null;
+    highlightPadding?: number;
+    allowInteraction?: boolean;
+    onMaskClick?: () => void;
+    placement?: Placement;
+}
+export declare const GuideOverlay: React.FC<GuideOverlayProps>;
+export {};

package/dist/components/GuideTooltip.d.ts

@@ -0,0 +1,17 @@
+import React from 'react';
+import type { GuideLabels, GuideStep, PositionResult } from '../types';
+interface GuideTooltipProps {
+    step: GuideStep;
+    stepIndex: number;
+    totalSteps: number;
+    position: PositionResult | null;
+    tooltipRef: React.Ref<HTMLDivElement>;
+    labels: Required<GuideLabels>;
+    showSkip?: boolean;
+    onNext: () => void;
+    onPrev: () => void;
+    onSkip: () => void;
+}
+export declare function resolveLabels(labels?: GuideLabels): Required<GuideLabels>;
+export declare const GuideTooltip: React.FC<GuideTooltipProps>;
+export {};

package/dist/context/GuideContext.d.ts

@@ -0,0 +1,6 @@
+import type { GuideController, GuideOptions } from '../types';
+export interface GuideContextValue {
+    controller: GuideController;
+    options: GuideOptions;
+}
+export declare const GuideContext: import("react").Context<GuideContextValue | null>;

package/dist/context/GuideProvider.d.ts

@@ -0,0 +1,13 @@
+import React from 'react';
+import type { GuideController, GuideOptions } from '../types';
+interface GuideProviderProps {
+    guide: GuideController;
+    options: GuideOptions;
+    children: React.ReactNode;
+}
+/**
+ * GuideProvider wraps your app and provides guide context.
+ * It also injects the base CSS styles and mounts the Guide component.
+ */
+export declare const GuideProvider: React.FC<GuideProviderProps>;
+export {};

package/dist/engine/arrow.d.ts

@@ -0,0 +1,15 @@
+import type { Placement } from '../types';
+type ArrowSide = 'top' | 'bottom' | 'left' | 'right';
+/**
+ * Get which side of the tooltip the arrow should appear on.
+ * The arrow points FROM the tooltip TOWARD the target.
+ */
+export declare function getArrowSide(placement: Placement): ArrowSide;
+/**
+ * Get CSS styles for the arrow element based on its position and the resolved placement.
+ */
+export declare function getArrowStyle(arrowPos: {
+    x: number;
+    y: number;
+}, placement: Placement): React.CSSProperties;
+export {};

package/dist/engine/computePosition.d.ts

@@ -0,0 +1,13 @@
+import type { Placement, PositionResult } from '../types';
+interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Main positioning function.
+ * Computes tooltip position with flip logic and viewport clamping.
+ */
+export declare function computePosition(targetRect: Rect, tooltipRect: Rect, placement?: Placement, offset?: number): PositionResult;
+export {};

package/dist/engine/constants.d.ts

@@ -0,0 +1,6 @@
+/** Default gap between the target element and the tooltip (px) */
+export declare const DEFAULT_OFFSET = 10;
+/** Arrow size in px */
+export declare const ARROW_SIZE = 8;
+/** Opposite side mapping for flip logic */
+export declare const OPPOSITE_SIDE: Record<string, string>;

package/dist/hooks/useGuide.d.ts

@@ -0,0 +1,2 @@
+import type { GuideController, GuideOptions } from '../types';
+export declare function useGuide(options: GuideOptions): GuideController;

package/dist/hooks/useKeyboard.d.ts

@@ -0,0 +1,12 @@
+interface UseKeyboardOptions {
+    enabled: boolean;
+    onNext: () => void;
+    onPrev: () => void;
+    onSkip: () => void;
+}
+/**
+ * Hook for keyboard navigation in the guide.
+ * ArrowRight / Enter = next, ArrowLeft = prev, Escape = skip
+ */
+export declare function useKeyboard({ enabled, onNext, onPrev, onSkip }: UseKeyboardOptions): void;
+export {};

package/dist/hooks/usePersistence.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Hook for persisting guide completion state in localStorage.
+ */
+export declare function usePersistence(persistKey?: string): {
+    isCompleted: boolean;
+    markCompleted: () => void;
+    reset: () => void;
+};

package/dist/hooks/usePosition.d.ts

@@ -0,0 +1,19 @@
+import type { Placement, PositionResult } from '../types';
+interface UsePositionOptions {
+    targetElement: HTMLElement | null;
+    placement: Placement;
+    enabled: boolean;
+    /** Extra padding around the highlight box — added to the tooltip offset */
+    highlightPadding?: number;
+}
+/**
+ * Hook that computes and tracks tooltip position relative to a target element.
+ * Re-computes on scroll, resize, and when the target changes.
+ * Retains the previous position during step transitions to avoid flicker.
+ */
+export declare function usePosition({ targetElement, placement, enabled, highlightPadding }: UsePositionOptions): {
+    position: PositionResult | null;
+    tooltipRef: import("react").RefObject<HTMLDivElement>;
+    updatePosition: () => void;
+};
+export {};