@tent-official/react-walkthrough 1.0.0

package/README.md

@@ -0,0 +1,174 @@
+# @tent-official/react-walkthrough
+
+Lightweight React walkthrough/tour component with auto-positioning, dependency chains, and smooth animations.
+
+## Features
+
+- SVG-based spotlight overlay with smooth animated transitions
+- Auto-positioning popover (top/bottom/left/right) with viewport detection
+- Dependency chains — start a walkthrough only after another completes
+- Customizable labels, colors, and layout
+- Reset and replay walkthroughs without page refresh
+- Portal-based rendering (works inside modals)
+- Zero external dependencies (only React + styled-components as peer deps)
+
+## Installation
+
+```bash
+npm install @tent-official/react-walkthrough
+# or
+yarn add @tent-official/react-walkthrough
+```
+
+### Peer Dependencies
+
+Make sure these are installed in your project:
+
+```bash
+npm install react react-dom styled-components
+```
+
+## Quick Start
+
+```jsx
+import { useWalkthrough, WalkthroughOverlay } from "@tent-official/react-walkthrough";
+
+function App() {
+  useWalkthrough({
+    name: "intro-tour",
+    steps: [
+      {
+        el: "welcome-title",
+        title: "Welcome!",
+        description: [{ description: "This is the main title of your app." }],
+      },
+      {
+        el: "nav-menu",
+        title: "Navigation",
+        description: [{ description: "Use this menu to navigate around." }],
+        position: "right",
+      },
+    ],
+  });
+
+  return (
+    <div>
+      <h1 id="welcome-title">My App</h1>
+      <nav id="nav-menu">...</nav>
+      <WalkthroughOverlay />
+    </div>
+  );
+}
+```
+
+## API
+
+### `useWalkthrough(options)`
+
+Hook to register a walkthrough tour.
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `name` | `string` | **required** | Unique name for this walkthrough |
+| `steps` | `WalkthroughStep[]` | **required** | Array of steps |
+| `storageKey` | `string` | `""` | Storage key prefix for localStorage |
+| `dependsOn` | `string[]` | `[]` | Walkthrough names that must complete first |
+| `onWalkthroughComplete` | `(name: string) => void` | — | Callback when walkthrough completes |
+| `isShowSkip` | `boolean` | `true` | Show skip button |
+| `isShowPrev` | `boolean` | `true` | Show back button |
+| `nextLabel` | `string` | `"Next →"` | Next button label |
+| `prevLabel` | `string` | `"Back"` | Previous button label |
+| `skipLabel` | `string` | `"Skip"` | Skip button label |
+| `doneLabel` | `string` | `"Done ✓"` | Done button label (last step) |
+| `nextColor` | `string` | — | Custom next button color |
+| `prevColor` | `string` | — | Custom previous button color |
+| `skipColor` | `string` | — | Custom skip button color |
+
+**Returns:** `{ start: () => void }`
+
+### `WalkthroughStep`
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `el` | `string` | **required** | DOM element ID to highlight |
+| `title` | `string` | — | Popover title |
+| `description` | `StepDescription[]` | **required** | Description blocks |
+| `position` | `"top" \| "bottom" \| "left" \| "right"` | auto | Preferred popover position |
+| `padding` | `number` | `8` | Padding around highlighted element (px) |
+| `borderRadius` | `number` | `10` | Border radius of highlight cutout (px) |
+| `width` | `number \| string` | `"auto"` | Popover width |
+| `height` | `number \| string` | — | Popover height |
+| `isTriggerEl` | `boolean` | `false` | Click the target element when "Next" is pressed |
+
+### `StepDescription`
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `title` | `string` | Optional label for this block |
+| `description` | `ReactNode` | Description content |
+| `direction` | `"row" \| "column"` | Layout direction |
+
+### `<WalkthroughOverlay />`
+
+Place this component once at the root of your app. It renders via React Portal into `document.body`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `$popoverPadding` | `number` | `12` | Inner padding of popover (px) |
+| `$popoverBorderRadius` | `number` | `8` | Border radius of popover (px) |
+| `$popoverGap` | `number` | `12` | Gap between highlight and popover (px) |
+| `$fontFamily` | `string` | system default | Font family for popover text |
+| `$animationSpeed` | `number` | `350` | Highlight transition speed (ms) |
+
+### `resetWalkthrough(options?)`
+
+Reset walkthroughs so they can be replayed without page refresh.
+
+```js
+import { resetWalkthrough } from "@tent-official/react-walkthrough";
+
+resetWalkthrough({
+  storageKey: "my-app",
+  walkthroughList: ["intro-tour", "feature-tour"],
+});
+```
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `storageKey` | `string` | `""` | Storage key prefix |
+| `walkthroughList` | `string[]` | `[]` | Names of walkthroughs to reset |
+
+## Dependency Chains
+
+You can create sequential walkthroughs using `dependsOn`:
+
+```jsx
+// This runs first
+useWalkthrough({
+  name: "intro-tour",
+  storageKey: "my-app",
+  steps: [/* ... */],
+});
+
+// This starts automatically after intro-tour completes
+useWalkthrough({
+  name: "advanced-tour",
+  storageKey: "my-app",
+  dependsOn: ["intro-tour"],
+  steps: [/* ... */],
+});
+```
+
+## Auto-Positioning
+
+The popover automatically positions itself to stay within the viewport:
+
+1. If `position` is specified, it tries that position first
+2. If it doesn't fit, it falls back to: bottom → top → right → left
+3. If nothing fits perfectly, it picks the direction with the most available space
+
+The popover also waits for the target element to be scrolled into view before appearing.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,124 @@
+import { ReactNode, ReactPortal } from 'react';
+
+/**
+ * Position of the popover relative to the target element.
+ * If the preferred position doesn't fit in the viewport, it will auto-fallback.
+ */
+type PopoverPosition = "top" | "bottom" | "left" | "right";
+/**
+ * Direction for description block layout.
+ */
+type DescriptionDirection = "row" | "column";
+/**
+ * A single description block within a step.
+ */
+interface StepDescription {
+    /** Optional title for this description block */
+    title?: string;
+    /** Description text or React node */
+    description: ReactNode;
+    /** Layout direction for this block */
+    direction?: DescriptionDirection;
+}
+/**
+ * A single step in a walkthrough tour.
+ */
+interface WalkthroughStep {
+    /** The DOM element ID to highlight */
+    el: string;
+    /** Title displayed at the top of the popover */
+    title?: string;
+    /** Array of description blocks */
+    description: StepDescription[];
+    /** Preferred popover position. Auto-positioned if omitted or if preferred doesn't fit */
+    position?: PopoverPosition;
+    /** Padding around the highlighted element (px). Default: 8 */
+    padding?: number;
+    /** Border radius of the highlight cutout (px). Default: 10 */
+    borderRadius?: number;
+    /** Popover width (px or "auto"). Default: "auto" */
+    width?: number | string;
+    /** Popover height (px or "auto"). Default: auto */
+    height?: number | string;
+    /** If true, clicking "Next" will also trigger a click on the target element */
+    isTriggerEl?: boolean;
+}
+/**
+ * Options for the useWalkthrough hook.
+ */
+interface UseWalkthroughOptions {
+    /** Unique name for this walkthrough */
+    name: string;
+    /** Storage key prefix for localStorage. Walkthroughs sharing the same key share completion state */
+    storageKey?: string;
+    /** List of walkthrough names that must complete before this one starts */
+    dependsOn?: string[];
+    /** Array of steps for this walkthrough */
+    steps: WalkthroughStep[];
+    /** Callback fired when the walkthrough completes (either finished or skipped) */
+    onWalkthroughComplete?: (name: string) => void;
+    /** Show the skip button. Default: true */
+    isShowSkip?: boolean;
+    /** Show the back/previous button. Default: true */
+    isShowPrev?: boolean;
+    /** Label for the next button. Default: "Next →" */
+    nextLabel?: string;
+    /** Label for the previous button. Default: "Back" */
+    prevLabel?: string;
+    /** Label for the skip button. Default: "Skip" */
+    skipLabel?: string;
+    /** Label for the done button (last step). Default: "Done ✓" */
+    doneLabel?: string;
+    /** Custom color for the next button */
+    nextColor?: string;
+    /** Custom color for the previous button */
+    prevColor?: string;
+    /** Custom color for the skip button */
+    skipColor?: string;
+}
+/**
+ * Return value of the useWalkthrough hook.
+ */
+interface UseWalkthroughReturn {
+    /** Manually start the walkthrough (respects isDone and dependsOn checks) */
+    start: () => void;
+}
+/**
+ * Props for the WalkthroughOverlay component.
+ */
+interface WalkthroughOverlayProps {
+    /** Inner padding of the popover (px). Default: 12 */
+    $popoverPadding?: number;
+    /** Border radius of the popover (px). Default: 8 */
+    $popoverBorderRadius?: number;
+    /** Gap between the highlight and the popover (px). Default: 12 */
+    $popoverGap?: number;
+    /** Font family for the popover text */
+    $fontFamily?: string;
+    /** Animation speed for highlight transitions (ms). Default: 350 */
+    $animationSpeed?: number;
+}
+/**
+ * Options for the resetWalkthrough function.
+ */
+interface ResetWalkthroughOptions {
+    /** Storage key prefix matching the one used in useWalkthrough. Default: "" */
+    storageKey?: string;
+    /** List of walkthrough names to reset */
+    walkthroughList?: string[];
+}
+/**
+ * Reset specified walkthroughs so they can be replayed without page refresh.
+ */
+declare function resetWalkthrough(options?: ResetWalkthroughOptions): void;
+/**
+ * Hook to register and control a walkthrough tour.
+ */
+declare function useWalkthrough(options: UseWalkthroughOptions): UseWalkthroughReturn;
+/**
+ * Overlay component that renders the walkthrough spotlight, popover, and controls.
+ * Place this once at the root of your app.
+ */
+declare function WalkthroughOverlay(props?: WalkthroughOverlayProps): ReactPortal | null;
+
+export { type DescriptionDirection, type PopoverPosition, type ResetWalkthroughOptions, type StepDescription, type UseWalkthroughOptions, type UseWalkthroughReturn, WalkthroughOverlay, type WalkthroughOverlayProps, type WalkthroughStep, resetWalkthrough, useWalkthrough };

package/dist/index.d.ts

@@ -0,0 +1,124 @@
+import { ReactNode, ReactPortal } from 'react';
+
+/**
+ * Position of the popover relative to the target element.
+ * If the preferred position doesn't fit in the viewport, it will auto-fallback.
+ */
+type PopoverPosition = "top" | "bottom" | "left" | "right";
+/**
+ * Direction for description block layout.
+ */
+type DescriptionDirection = "row" | "column";
+/**
+ * A single description block within a step.
+ */
+interface StepDescription {
+    /** Optional title for this description block */
+    title?: string;
+    /** Description text or React node */
+    description: ReactNode;
+    /** Layout direction for this block */
+    direction?: DescriptionDirection;
+}
+/**
+ * A single step in a walkthrough tour.
+ */
+interface WalkthroughStep {
+    /** The DOM element ID to highlight */
+    el: string;
+    /** Title displayed at the top of the popover */
+    title?: string;
+    /** Array of description blocks */
+    description: StepDescription[];
+    /** Preferred popover position. Auto-positioned if omitted or if preferred doesn't fit */
+    position?: PopoverPosition;
+    /** Padding around the highlighted element (px). Default: 8 */
+    padding?: number;
+    /** Border radius of the highlight cutout (px). Default: 10 */
+    borderRadius?: number;
+    /** Popover width (px or "auto"). Default: "auto" */
+    width?: number | string;
+    /** Popover height (px or "auto"). Default: auto */
+    height?: number | string;
+    /** If true, clicking "Next" will also trigger a click on the target element */
+    isTriggerEl?: boolean;
+}
+/**
+ * Options for the useWalkthrough hook.
+ */
+interface UseWalkthroughOptions {
+    /** Unique name for this walkthrough */
+    name: string;
+    /** Storage key prefix for localStorage. Walkthroughs sharing the same key share completion state */
+    storageKey?: string;
+    /** List of walkthrough names that must complete before this one starts */
+    dependsOn?: string[];
+    /** Array of steps for this walkthrough */
+    steps: WalkthroughStep[];
+    /** Callback fired when the walkthrough completes (either finished or skipped) */
+    onWalkthroughComplete?: (name: string) => void;
+    /** Show the skip button. Default: true */
+    isShowSkip?: boolean;
+    /** Show the back/previous button. Default: true */
+    isShowPrev?: boolean;
+    /** Label for the next button. Default: "Next →" */
+    nextLabel?: string;
+    /** Label for the previous button. Default: "Back" */
+    prevLabel?: string;
+    /** Label for the skip button. Default: "Skip" */
+    skipLabel?: string;
+    /** Label for the done button (last step). Default: "Done ✓" */
+    doneLabel?: string;
+    /** Custom color for the next button */
+    nextColor?: string;
+    /** Custom color for the previous button */
+    prevColor?: string;
+    /** Custom color for the skip button */
+    skipColor?: string;
+}
+/**
+ * Return value of the useWalkthrough hook.
+ */
+interface UseWalkthroughReturn {
+    /** Manually start the walkthrough (respects isDone and dependsOn checks) */
+    start: () => void;
+}
+/**
+ * Props for the WalkthroughOverlay component.
+ */
+interface WalkthroughOverlayProps {
+    /** Inner padding of the popover (px). Default: 12 */
+    $popoverPadding?: number;
+    /** Border radius of the popover (px). Default: 8 */
+    $popoverBorderRadius?: number;
+    /** Gap between the highlight and the popover (px). Default: 12 */
+    $popoverGap?: number;
+    /** Font family for the popover text */
+    $fontFamily?: string;
+    /** Animation speed for highlight transitions (ms). Default: 350 */
+    $animationSpeed?: number;
+}
+/**
+ * Options for the resetWalkthrough function.
+ */
+interface ResetWalkthroughOptions {
+    /** Storage key prefix matching the one used in useWalkthrough. Default: "" */
+    storageKey?: string;
+    /** List of walkthrough names to reset */
+    walkthroughList?: string[];
+}
+/**
+ * Reset specified walkthroughs so they can be replayed without page refresh.
+ */
+declare function resetWalkthrough(options?: ResetWalkthroughOptions): void;
+/**
+ * Hook to register and control a walkthrough tour.
+ */
+declare function useWalkthrough(options: UseWalkthroughOptions): UseWalkthroughReturn;
+/**
+ * Overlay component that renders the walkthrough spotlight, popover, and controls.
+ * Place this once at the root of your app.
+ */
+declare function WalkthroughOverlay(props?: WalkthroughOverlayProps): ReactPortal | null;
+
+export { type DescriptionDirection, type PopoverPosition, type ResetWalkthroughOptions, type StepDescription, type UseWalkthroughOptions, type UseWalkthroughReturn, WalkthroughOverlay, type WalkthroughOverlayProps, type WalkthroughStep, resetWalkthrough, useWalkthrough };