react-guide-step 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +258 -0
- package/README.zh-CN.md +258 -0
- package/dist/components/Guide.d.ts +2 -0
- package/dist/components/GuideArrow.d.ts +11 -0
- package/dist/components/GuideOverlay.d.ts +11 -0
- package/dist/components/GuideTooltip.d.ts +17 -0
- package/dist/context/GuideContext.d.ts +6 -0
- package/dist/context/GuideProvider.d.ts +13 -0
- package/dist/engine/arrow.d.ts +15 -0
- package/dist/engine/computePosition.d.ts +13 -0
- package/dist/engine/constants.d.ts +6 -0
- package/dist/hooks/useGuide.d.ts +2 -0
- package/dist/hooks/useKeyboard.d.ts +12 -0
- package/dist/hooks/usePersistence.d.ts +8 -0
- package/dist/hooks/usePosition.d.ts +19 -0
- package/dist/hooks/usePreloadImages.d.ts +6 -0
- package/dist/hooks/useScrollIntoView.d.ts +4 -0
- package/dist/hooks/useWaitForElement.d.ts +8 -0
- package/dist/index.d.ts +4 -0
- package/dist/react-guide-step.cjs +171 -0
- package/dist/react-guide-step.js +863 -0
- package/dist/styles/classes.d.ts +5 -0
- package/dist/styles/inject.d.ts +9 -0
- package/dist/styles/theme.d.ts +10 -0
- package/dist/types.d.ts +101 -0
- package/dist/utils/dom.d.ts +13 -0
- package/package.json +49 -0
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* All CSS class definitions for react-guide-step.
|
|
3
|
+
* Uses rgs- prefix and references CSS variables.
|
|
4
|
+
*/
|
|
5
|
+
export declare const BASE_STYLES = "\n .rgs-portal {\n position: fixed;\n inset: 0;\n z-index: var(--rgs-z);\n pointer-events: none;\n }\n\n .rgs-portal > * {\n pointer-events: auto;\n }\n\n /* Spotlight overlay \u2014 uses box-shadow for the mask */\n .rgs-spotlight {\n position: fixed;\n box-shadow: 0 0 0 9999px var(--rgs-overlay);\n border-radius: 4px;\n z-index: var(--rgs-z);\n pointer-events: none;\n }\n\n .rgs-spotlight--interactive {\n pointer-events: auto;\n }\n\n /* Clickable overlay behind everything to detect mask clicks */\n .rgs-overlay {\n position: fixed;\n inset: 0;\n z-index: calc(var(--rgs-z) - 1);\n cursor: default;\n }\n\n /* Tooltip container */\n .rgs-tooltip {\n position: fixed;\n z-index: calc(var(--rgs-z) + 1);\n background: var(--rgs-bg);\n color: var(--rgs-text);\n border-radius: var(--rgs-radius);\n box-shadow: 0 6px 16px 0 rgba(0, 0, 0, 0.08),\n 0 3px 6px -4px rgba(0, 0, 0, 0.12),\n 0 9px 28px 8px rgba(0, 0, 0, 0.05);\n padding: 16px;\n min-width: 280px;\n max-width: 420px;\n opacity: 0;\n transition: opacity var(--rgs-duration) ease;\n outline: none;\n }\n\n .rgs-tooltip--visible {\n opacity: 1;\n }\n\n .rgs-tooltip__title {\n font-size: 16px;\n font-weight: 600;\n margin: 0 0 8px 0;\n line-height: 1.4;\n }\n\n .rgs-tooltip__content {\n font-size: 14px;\n line-height: 1.6;\n margin: 0 0 16px 0;\n color: var(--rgs-text);\n opacity: 0.85;\n }\n\n .rgs-tooltip__footer {\n display: flex;\n align-items: center;\n justify-content: space-between;\n gap: 8px;\n }\n\n .rgs-tooltip__counter {\n font-size: 12px;\n color: var(--rgs-text);\n opacity: 0.45;\n flex-shrink: 0;\n }\n\n .rgs-tooltip__actions {\n display: flex;\n align-items: center;\n gap: 8px;\n margin-left: auto;\n }\n\n /* Buttons */\n .rgs-btn {\n display: inline-flex;\n align-items: center;\n justify-content: center;\n padding: 4px 16px;\n font-size: 14px;\n line-height: 1.5;\n border-radius: calc(var(--rgs-radius) - 2px);\n cursor: pointer;\n border: 1px solid transparent;\n transition: all 0.2s ease;\n white-space: nowrap;\n font-family: inherit;\n }\n\n .rgs-btn:focus-visible {\n outline: 2px solid var(--rgs-primary);\n outline-offset: 2px;\n }\n\n .rgs-btn--primary {\n background: var(--rgs-primary);\n color: #fff;\n border-color: var(--rgs-primary);\n }\n\n .rgs-btn--primary:hover {\n opacity: 0.85;\n }\n\n .rgs-btn--default {\n background: transparent;\n color: var(--rgs-text);\n border-color: #d9d9d9;\n }\n\n .rgs-btn--default:hover {\n color: var(--rgs-primary);\n border-color: var(--rgs-primary);\n }\n\n .rgs-btn--text {\n background: transparent;\n color: var(--rgs-text);\n opacity: 0.65;\n padding: 4px 8px;\n }\n\n .rgs-btn--text:hover {\n opacity: 1;\n }\n\n /* Arrow (styles applied inline, this is a fallback) */\n .rgs-arrow {\n position: absolute;\n }\n\n /* Waiting state */\n .rgs-waiting {\n position: fixed;\n top: 50%;\n left: 50%;\n transform: translate(-50%, -50%);\n z-index: calc(var(--rgs-z) + 1);\n color: var(--rgs-bg);\n font-size: 14px;\n }\n";
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Inject a <style> tag into <head> with a given id.
|
|
3
|
+
* If a style tag with the same id already exists, it will be updated.
|
|
4
|
+
*/
|
|
5
|
+
export declare function injectStyles(id: string, css: string): void;
|
|
6
|
+
/**
|
|
7
|
+
* Remove a previously injected <style> tag by id.
|
|
8
|
+
*/
|
|
9
|
+
export declare function removeStyles(id: string): void;
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import type { GuideTheme } from '../types';
|
|
2
|
+
export declare const DEFAULT_THEME: GuideTheme;
|
|
3
|
+
/**
|
|
4
|
+
* Merge user theme with defaults and generate CSS variable declarations.
|
|
5
|
+
*/
|
|
6
|
+
export declare function resolveTheme(theme?: GuideTheme): Required<GuideTheme>;
|
|
7
|
+
/**
|
|
8
|
+
* Convert a resolved theme to CSS custom property declarations.
|
|
9
|
+
*/
|
|
10
|
+
export declare function themeToCssVars(theme: Required<GuideTheme>): string;
|
package/dist/types.d.ts
ADDED
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
export type Placement = 'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'right' | 'right-start' | 'right-end' | 'center';
|
|
2
|
+
export interface GuideStep {
|
|
3
|
+
/** CSS selector or Element ref for the target element */
|
|
4
|
+
target: string | HTMLElement;
|
|
5
|
+
/** Step title */
|
|
6
|
+
title?: string;
|
|
7
|
+
/** Step description content — supports text, JSX, images, or any React node */
|
|
8
|
+
content?: React.ReactNode;
|
|
9
|
+
/** Preferred tooltip placement relative to target */
|
|
10
|
+
placement?: Placement;
|
|
11
|
+
/** Custom render function for the tooltip content */
|
|
12
|
+
customRender?: (props: StepRenderProps) => React.ReactNode;
|
|
13
|
+
/** Async hook called before entering this step */
|
|
14
|
+
beforeEnter?: () => void | Promise<void>;
|
|
15
|
+
/** Async hook called after leaving this step */
|
|
16
|
+
afterLeave?: () => void | Promise<void>;
|
|
17
|
+
/** Extra padding around the spotlight highlight (px) */
|
|
18
|
+
highlightPadding?: number;
|
|
19
|
+
/** If true, wait for the target element to appear in the DOM */
|
|
20
|
+
waitForElement?: boolean;
|
|
21
|
+
/** Whether to show the arrow pointing to the target (default: true) */
|
|
22
|
+
showArrow?: boolean;
|
|
23
|
+
/** Allow user interaction with the highlighted target element */
|
|
24
|
+
allowInteraction?: boolean;
|
|
25
|
+
/** Image URLs to preload before this step is displayed */
|
|
26
|
+
preloadImages?: string[];
|
|
27
|
+
}
|
|
28
|
+
export interface GuideTheme {
|
|
29
|
+
primaryColor?: string;
|
|
30
|
+
textColor?: string;
|
|
31
|
+
bgColor?: string;
|
|
32
|
+
overlayColor?: string;
|
|
33
|
+
borderRadius?: number;
|
|
34
|
+
zIndex?: number;
|
|
35
|
+
animationDuration?: number;
|
|
36
|
+
}
|
|
37
|
+
export interface GuideLabels {
|
|
38
|
+
next?: string;
|
|
39
|
+
prev?: string;
|
|
40
|
+
skip?: string;
|
|
41
|
+
finish?: string;
|
|
42
|
+
/** Template for step counter, e.g. "{current} of {total}" */
|
|
43
|
+
stepOf?: string;
|
|
44
|
+
}
|
|
45
|
+
export interface GuideOptions {
|
|
46
|
+
steps: GuideStep[];
|
|
47
|
+
onComplete?: () => void;
|
|
48
|
+
onSkip?: (stepIndex: number) => void;
|
|
49
|
+
onStepChange?: (stepIndex: number) => void;
|
|
50
|
+
initialStep?: number;
|
|
51
|
+
/** Close guide when clicking the mask overlay */
|
|
52
|
+
maskClosable?: boolean;
|
|
53
|
+
/** Show the skip button in the tooltip (default: true) */
|
|
54
|
+
showSkip?: boolean;
|
|
55
|
+
/** Enable keyboard navigation (default: true) */
|
|
56
|
+
keyboardNavigation?: boolean;
|
|
57
|
+
/** Scroll behavior when scrolling target into view */
|
|
58
|
+
scrollBehavior?: ScrollBehavior;
|
|
59
|
+
theme?: GuideTheme;
|
|
60
|
+
/** localStorage key for persistence; if set, completed tours won't re-show */
|
|
61
|
+
persistKey?: string;
|
|
62
|
+
/** Auto-start the guide on mount (default: false) */
|
|
63
|
+
autoStart?: boolean;
|
|
64
|
+
/** Custom labels for i18n */
|
|
65
|
+
labels?: GuideLabels;
|
|
66
|
+
}
|
|
67
|
+
export interface GuideController {
|
|
68
|
+
start: () => void;
|
|
69
|
+
stop: () => void;
|
|
70
|
+
next: () => void;
|
|
71
|
+
prev: () => void;
|
|
72
|
+
goTo: (stepIndex: number) => void;
|
|
73
|
+
isActive: boolean;
|
|
74
|
+
currentStep: number;
|
|
75
|
+
totalSteps: number;
|
|
76
|
+
isCompleted: boolean;
|
|
77
|
+
}
|
|
78
|
+
export interface GuideState {
|
|
79
|
+
isActive: boolean;
|
|
80
|
+
currentStep: number;
|
|
81
|
+
targetElement: HTMLElement | null;
|
|
82
|
+
isWaiting: boolean;
|
|
83
|
+
}
|
|
84
|
+
export interface StepRenderProps {
|
|
85
|
+
step: GuideStep;
|
|
86
|
+
stepIndex: number;
|
|
87
|
+
totalSteps: number;
|
|
88
|
+
next: () => void;
|
|
89
|
+
prev: () => void;
|
|
90
|
+
skip: () => void;
|
|
91
|
+
finish: () => void;
|
|
92
|
+
}
|
|
93
|
+
export interface PositionResult {
|
|
94
|
+
x: number;
|
|
95
|
+
y: number;
|
|
96
|
+
resolvedPlacement: Placement;
|
|
97
|
+
arrow: {
|
|
98
|
+
x: number;
|
|
99
|
+
y: number;
|
|
100
|
+
};
|
|
101
|
+
}
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Resolve a target to an HTMLElement.
|
|
3
|
+
* Accepts a CSS selector string or an HTMLElement directly.
|
|
4
|
+
*/
|
|
5
|
+
export declare function getElement(target: string | HTMLElement): HTMLElement | null;
|
|
6
|
+
/**
|
|
7
|
+
* Get the bounding rect of an element as a plain object.
|
|
8
|
+
*/
|
|
9
|
+
export declare function getRect(el: HTMLElement): DOMRect;
|
|
10
|
+
/**
|
|
11
|
+
* Simple className joiner — filters falsy values.
|
|
12
|
+
*/
|
|
13
|
+
export declare function clsx(...classes: (string | false | null | undefined)[]): string;
|
package/package.json
ADDED
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "react-guide-step",
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "React product guide step component for onboarding tours",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"main": "./dist/react-guide-step.cjs",
|
|
7
|
+
"module": "./dist/react-guide-step.js",
|
|
8
|
+
"types": "./dist/index.d.ts",
|
|
9
|
+
"exports": {
|
|
10
|
+
".": {
|
|
11
|
+
"import": "./dist/react-guide-step.js",
|
|
12
|
+
"require": "./dist/react-guide-step.cjs",
|
|
13
|
+
"types": "./dist/index.d.ts"
|
|
14
|
+
}
|
|
15
|
+
},
|
|
16
|
+
"files": [
|
|
17
|
+
"dist"
|
|
18
|
+
],
|
|
19
|
+
"scripts": {
|
|
20
|
+
"dev": "cd demo && npx vite",
|
|
21
|
+
"build": "vite build && tsc -p tsconfig.build.json --emitDeclarationOnly",
|
|
22
|
+
"preview": "cd demo && npx vite preview"
|
|
23
|
+
},
|
|
24
|
+
"peerDependencies": {
|
|
25
|
+
"react": ">=18.0.0",
|
|
26
|
+
"react-dom": ">=18.0.0"
|
|
27
|
+
},
|
|
28
|
+
"devDependencies": {
|
|
29
|
+
"@types/react": "^18.3.0",
|
|
30
|
+
"@types/react-dom": "^18.3.0",
|
|
31
|
+
"@vitejs/plugin-react": "^4.3.0",
|
|
32
|
+
"react": "^18.3.0",
|
|
33
|
+
"react-dom": "^18.3.0",
|
|
34
|
+
"typescript": "^5.5.0",
|
|
35
|
+
"vite": "^5.4.0",
|
|
36
|
+
"vite-plugin-dts": "^4.0.0"
|
|
37
|
+
},
|
|
38
|
+
"keywords": [
|
|
39
|
+
"react",
|
|
40
|
+
"guide",
|
|
41
|
+
"tour",
|
|
42
|
+
"onboarding",
|
|
43
|
+
"step",
|
|
44
|
+
"walkthrough",
|
|
45
|
+
"tooltip"
|
|
46
|
+
],
|
|
47
|
+
"license": "MIT",
|
|
48
|
+
"sideEffects": false
|
|
49
|
+
}
|