= (props) => {
7 | const copilot = useCopilot();
8 | return ;
9 | };
10 |
11 | Component.displayName = `CopilotInjector(${
12 | WrappedComponent.displayName ?? WrappedComponent.name ?? "Component"
13 | })`;
14 |
15 | return Component;
16 | };
17 |
18 | /**
19 | * @deprecated The HOC is deprecated. Please use `CopilotProvider` instead.
20 | */
21 | export function copilot(options: CopilotOptions) {
22 | return (WrappedComponent: ComponentType) => {
23 | const OuterComponent: FunctionComponent
= (props) => {
24 | const InnerComponentWithCopilotContext =
25 | ComponentWithCopilotContext(WrappedComponent);
26 |
27 | return (
28 |
29 |
30 |
31 | );
32 | };
33 |
34 | OuterComponent.displayName = `copilot(${
35 | WrappedComponent.displayName ?? WrappedComponent.name ?? "Component"
36 | })`;
37 |
38 | return OuterComponent;
39 | };
40 | }
41 |
--------------------------------------------------------------------------------
/src/hocs/tests/walkthroughable.test.tsx:
--------------------------------------------------------------------------------
1 | import React from "react";
2 | import { View, Text, ScrollView, TextInput } from "react-native";
3 | import renderer from "react-test-renderer";
4 | import { walkthroughable } from "../walkthroughable";
5 |
6 | const WalkthroughableView = walkthroughable(View);
7 | const WalkthroughableText = walkthroughable(Text);
8 | const WalkthroughableScrollView = walkthroughable(ScrollView);
9 | const WalkthroughableTextInput = walkthroughable(TextInput);
10 |
11 | const walkthroughableComponents = [
12 | WalkthroughableView,
13 | WalkthroughableText,
14 | WalkthroughableScrollView,
15 | WalkthroughableTextInput,
16 | ];
17 |
18 | const nativeComponents = [View, Text, ScrollView, TextInput];
19 |
20 | it("spreads the copilot prop object on the wrapped component", () => {
21 | const tree = renderer.create(
22 | // @ts-expect-error just for testing
23 |
24 | );
25 |
26 | const { props } = tree.root.findByType(View as any );
27 |
28 | expect(props.keyForNum).toBe(1);
29 | expect(props.keyForStr).toBe("hello");
30 | });
31 |
32 | it("spreads the copilot prop object on the wrapped component along with other flat props", () => {
33 | const tree = renderer.create(
34 |
39 | );
40 |
41 | const { props } = tree.root.findByType(View as any );
42 |
43 | expect(props.keyForNum).toBe(1);
44 | expect(props.keyForStr).toBe("hello");
45 | expect(props.otherProp).toBe("the other prop");
46 | });
47 |
48 | it("spreads the copilot prop object on the wrapped component not overriding the root props", () => {
49 | const tree = renderer.create(
50 |
55 | );
56 |
57 | const { props } = tree.root.findByType(View as any );
58 |
59 | expect(props.keyForNum).toBe(2);
60 | expect(props.keyForStr).toBe("hello");
61 | });
62 |
63 | it("works with all types of react native built-in components", () => {
64 | nativeComponents.forEach((Component, key) => {
65 | const WalkthroughableComponent = walkthroughableComponents[key];
66 |
67 | const tree = renderer.create(
68 |
72 | );
73 |
74 | const { props } = tree.root.findByType(Component as any );
75 |
76 | expect(props.keyForNum).toBe(1);
77 | expect(props.keyForStr).toBe("hello");
78 | });
79 | });
80 |
--------------------------------------------------------------------------------
/src/hocs/walkthroughable.tsx:
--------------------------------------------------------------------------------
1 | import React, { type FunctionComponent } from "react";
2 | import { type NativeMethods } from "react-native/types";
3 |
4 | interface CopilotType {
5 | ref?: React.RefObject;
6 | onLayout?: () => void;
7 | }
8 |
9 | export function walkthroughable(
10 | WrappedComponent: React.ComponentType
,
11 | ) {
12 | const Component: FunctionComponent
= (props: P) => {
13 | const { copilot, ...rest } = props as { copilot: CopilotType } & P;
14 | return ;
15 | };
16 |
17 | Component.displayName = "Walkthroughable";
18 |
19 | return Component;
20 | }
21 |
--------------------------------------------------------------------------------
/src/hooks/useStateWithAwait.ts:
--------------------------------------------------------------------------------
1 | import { useEffect, useRef, useState } from "react";
2 |
3 | /**
4 | * A hook like useState that allows you to use await the setter
5 | */
6 | export const useStateWithAwait = (
7 | initialState: T
8 | ): [T, (newValue: T) => Promise] => {
9 | const endPending = useRef(() => {});
10 | const newDesiredValue = useRef(initialState);
11 |
12 | const [state, setState] = useState(initialState);
13 |
14 | const setStateWithAwait = async (newState: T) => {
15 | const pending = new Promise((resolve) => {
16 | endPending.current = resolve;
17 | });
18 | newDesiredValue.current = newState;
19 | setState(newState);
20 | await pending;
21 | };
22 |
23 | useEffect(() => {
24 | if (state === newDesiredValue.current) {
25 | endPending.current();
26 | }
27 | }, [state]);
28 |
29 | return [state, setStateWithAwait];
30 | };
31 |
--------------------------------------------------------------------------------
/src/hooks/useStepsMap.ts:
--------------------------------------------------------------------------------
1 | import { useCallback, useMemo, useReducer, useState } from "react";
2 | import { type Step, type StepsMap } from "../types";
3 |
4 | type Action =
5 | | {
6 | type: "register";
7 | step: Step;
8 | }
9 | | {
10 | type: "unregister";
11 | stepName: string;
12 | };
13 |
14 | export const useStepsMap = () => {
15 | const [currentStep, setCurrentStepState] = useState(
16 | undefined
17 | );
18 | const [steps, dispatch] = useReducer((state: StepsMap, action: Action) => {
19 | switch (action.type) {
20 | case "register":
21 | return {
22 | ...state,
23 | [action.step.name]: action.step,
24 | };
25 | case "unregister": {
26 | const { [action.stepName]: _, ...rest } = state;
27 | return rest;
28 | }
29 | default:
30 | return state;
31 | }
32 | }, {});
33 |
34 | const orderedSteps = useMemo(
35 | () => Object.values(steps).sort((a, b) => a.order - b.order),
36 | [steps]
37 | );
38 |
39 | const stepIndex = useCallback(
40 | (step = currentStep) =>
41 | step
42 | ? orderedSteps.findIndex(
43 | (stepCandidate) => stepCandidate.order === step.order
44 | )
45 | : -1,
46 | [currentStep, orderedSteps]
47 | );
48 |
49 | const currentStepNumber = useMemo(
50 | (step = currentStep) => stepIndex(step) + 1,
51 | [currentStep, stepIndex]
52 | );
53 |
54 | const totalStepsNumber = useMemo(() => orderedSteps.length, [orderedSteps]);
55 |
56 | const getFirstStep = useCallback(() => orderedSteps[0], [orderedSteps]);
57 |
58 | const getLastStep = useCallback(
59 | () => orderedSteps[orderedSteps.length - 1],
60 | [orderedSteps]
61 | );
62 |
63 | const getPrevStep = useCallback(
64 | (step = currentStep) => step && orderedSteps[stepIndex(step) - 1],
65 | [currentStep, stepIndex, orderedSteps]
66 | );
67 |
68 | const getNextStep = useCallback(
69 | (step = currentStep) => step && orderedSteps[stepIndex(step) + 1],
70 | [currentStep, stepIndex, orderedSteps]
71 | );
72 |
73 | const getNthStep = useCallback(
74 | (n: number) => orderedSteps[n - 1],
75 | [orderedSteps]
76 | );
77 |
78 | const isFirstStep = useMemo(
79 | () => currentStep === getFirstStep(),
80 | [currentStep, getFirstStep]
81 | );
82 |
83 | const isLastStep = useMemo(
84 | () => currentStep === getLastStep(),
85 | [currentStep, getLastStep]
86 | );
87 |
88 | const registerStep = useCallback((step: Step) => {
89 | dispatch({ type: "register", step });
90 | }, []);
91 |
92 | const unregisterStep = useCallback((stepName: string) => {
93 | dispatch({ type: "unregister", stepName });
94 | }, []);
95 |
96 | return {
97 | currentStepNumber,
98 | totalStepsNumber,
99 | getFirstStep,
100 | getLastStep,
101 | getPrevStep,
102 | getNextStep,
103 | getNthStep,
104 | isFirstStep,
105 | isLastStep,
106 | currentStep,
107 | setCurrentStepState,
108 | steps,
109 | registerStep,
110 | unregisterStep,
111 | };
112 | };
113 |
--------------------------------------------------------------------------------
/src/index.ts:
--------------------------------------------------------------------------------
1 | import { StepNumber } from "./components/default-ui/StepNumber";
2 | import { Tooltip } from "./components/default-ui/Tooltip";
3 | export { walkthroughable } from "./hocs/walkthroughable";
4 | export { CopilotStep } from "./components/CopilotStep";
5 | export { CopilotProvider, useCopilot } from "./contexts/CopilotProvider";
6 | export type { CopilotOptions as CopilotProps, TooltipProps } from "./types";
7 |
8 | export const DefaultUI = {
9 | StepNumber,
10 | Tooltip,
11 | };
12 |
--------------------------------------------------------------------------------
/src/types.ts:
--------------------------------------------------------------------------------
1 | import type {
2 | Animated,
3 | LayoutRectangle,
4 | NativeMethods,
5 | ViewStyle,
6 | } from "react-native";
7 |
8 | export type WalktroughedComponent = NativeMethods & React.ComponentType;
9 |
10 | export interface Step {
11 | name: string;
12 | order: number;
13 | visible: boolean;
14 | wrapperRef: React.RefObject;
15 | measure: () => Promise;
16 | text: string;
17 | }
18 |
19 | export interface CopilotContext {
20 | registerStep: (step: Step) => void;
21 | unregisterStep: (name: string) => void;
22 | getCurrentStep: () => Step | undefined;
23 | }
24 |
25 | export interface ValueXY {
26 | x: number;
27 | y: number;
28 | }
29 |
30 | export type SvgMaskPathFunction = (args: {
31 | size: Animated.ValueXY;
32 | position: Animated.ValueXY;
33 | canvasSize: ValueXY;
34 | step: Step;
35 | }) => string;
36 |
37 | export type StepsMap = Record;
38 |
39 | export type EasingFunction = (value: number) => number;
40 |
41 | export type Labels = Partial<
42 | Record<"skip" | "previous" | "next" | "finish", string>
43 | >;
44 |
45 | export interface TooltipProps {
46 | labels: Labels;
47 | }
48 |
49 | export interface MaskProps {
50 | size: ValueXY;
51 | position: ValueXY;
52 | style: ViewStyle;
53 | easing?: EasingFunction;
54 | animationDuration: number;
55 | animated: boolean;
56 | backdropColor: string;
57 | svgMaskPath?: SvgMaskPathFunction;
58 | layout: {
59 | width: number;
60 | height: number;
61 | };
62 | onClick?: () => any;
63 | currentStep: Step;
64 | }
65 |
66 | export interface CopilotOptions {
67 | easing?: ((value: number) => number) | undefined;
68 | overlay?: "svg" | "view";
69 | animationDuration?: number;
70 | tooltipComponent?: React.ComponentType;
71 | tooltipStyle?: ViewStyle;
72 | stepNumberComponent?: React.ComponentType;
73 | animated?: boolean;
74 | labels?: Labels;
75 | androidStatusBarVisible?: boolean;
76 | svgMaskPath?: SvgMaskPathFunction;
77 | verticalOffset?: number;
78 | arrowColor?: string;
79 | arrowSize?: number
80 | margin?: number
81 | stopOnOutsideClick?: boolean;
82 | backdropColor?: string;
83 | }
84 |
--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
1 | {
2 | "extends": "@tsconfig/react-native/tsconfig.json",
3 | "exclude": ["dist"],
4 | "include": ["src", "./tsup.config.ts"],
5 | "compilerOptions": {
6 | "types": ["react-native", "jest", "node"],
7 | "target": "ES2015"
8 | }
9 | }
10 |
--------------------------------------------------------------------------------
/tsconfig.spec.json:
--------------------------------------------------------------------------------
1 | {
2 | "extends": "./tsconfig.json",
3 | "compilerOptions": {
4 | "jsx": "react"
5 | }
6 | }
7 |
--------------------------------------------------------------------------------
/tsup.config.ts:
--------------------------------------------------------------------------------
1 | import { defineConfig } from "tsup";
2 | import fs from "fs/promises";
3 | import path from "path";
4 |
5 | export default defineConfig({
6 | entry: ["src/index.ts"],
7 | format: ["cjs", "esm"],
8 | sourcemap: true,
9 | dts: true,
10 | external: ["react", "react-native", "react-native-svg"],
11 | platform: "neutral",
12 | async onSuccess() {
13 | if (process.env.NODE_ENV === "development") {
14 | const exampleOutputPath = path.resolve(
15 | "./example/node_modules/react-native-copilot"
16 | );
17 | const exampleOutputNodeModulesPath = path.resolve(
18 | exampleOutputPath,
19 | "node_modules"
20 | );
21 |
22 | await Promise.all(
23 | ["dist/index.js", "dist/index.d.ts"].map(async (file) => {
24 | const outputPath = path.resolve(exampleOutputPath, file);
25 | console.log("Copying file: ", file, "to ->", outputPath);
26 | await fs.copyFile(file, outputPath);
27 | })
28 | );
29 | await fs.rm(exampleOutputNodeModulesPath, {
30 | recursive: true,
31 | force: true,
32 | });
33 | console.log("Copied files to example project");
34 | }
35 | },
36 | });
37 |
--------------------------------------------------------------------------------
23 | 
7 | 
10 | 
13 |