Chaperone (not publish yet)

is a react library which helps and guide the user interacts with UI step by step to have a better user experience in your react components. Chaperone gives you alot of option with such ability to make your user experience alot better. it allow such gesture to tell the user what to do next even without reading the dialog. it is even flexible in any component whether it is forwardRef or not.

Installation #

npm i chaperone

Imports #

import { Chaperone, ChaperoneStep, Trigger } from "chaperone";

Getting Started #

it is the basic usage of chaperone.

import React from "react";
import { Chaperone, ChaperoneStep, Trigger } from "chaperone";

#render(
    <div className="container">  
        <Chaperone>
            <Trigger label="Need Help?" />
            <form className="mt-3">
                <div className="n-form-field">
                    <label htmlFor="gs-email">Email address</label>
                    <ChaperoneStep 
                        index={0} 
                        message="To Login. Firstly, you must type your e-mail here." 
                        placement="top-right">
                        <input 
                            type="email" 
                            className="n-form-control" 
                            id="gs-email" 
                            aria-describedby="emailHelp" 
                            style={{backgroundColor: "transparent"}} />
                    </ChaperoneStep>
                </div>
                <div className="n-form-field">
                    <label htmlFor="gs-pass">Password</label>
                    <ChaperoneStep 
                        index={1} 
                        message="Secondly, you must put your password here." 
                        placement="top-right">
                        <input 
                            type="password" 
                            className="n-form-control" 
                            id="gs-pass" 
                            style={{backgroundColor: "transparent"}} />
                    </ChaperoneStep> 
                </div> 
                <div className="n-form-field"> 
                    <label className="n-form-check">
                        <ChaperoneStep 
                            index={2} 
                            message={<>Thirdly, if you want to remember the app your inputs just click <b>remember me</b>.</>} 
                            placement="left">
                            <input className="n-form-control" type="checkbox" /> 
                        </ChaperoneStep> 
                        remember me
                    </label> 
                </div>
                <ChaperoneStep 
                    isDone 
                    index={3} 
                    message={<>Lastly, you must press <b>Submit</b>.</>}>
                    <button type="button" className="n-btn">Submit</button>
                </ChaperoneStep> 
            </form>
        </Chaperone>
    </div>
)import React from "react";
import { Chaperone, ChaperoneStep, Trigger } from "chaperone";
#render(
    <div className="container">  
        <Chaperone>
            <Trigger label="Need Help?" />
            <form className="mt-3">
                <div className="n-form-field">
                    <label htmlFor="gs-email">Email address</label>
                    <ChaperoneStep 
                        index={0} 
                        message="To Login. Firstly, you must type your e-mail here." 
                        placement="top-right">
                        <input 
                            type="email" 
                            className="n-form-control" 
                            id="gs-email" 
                            aria-describedby="emailHelp" 
                            style={{backgroundColor: "transparent"}} />
                    </ChaperoneStep>
                </div>
                <div className="n-form-field">
                    <label htmlFor="gs-pass">Password</label>
                    <ChaperoneStep 
                        index={1} 
                        message="Secondly, you must put your password here." 
                        placement="top-right">
                        <input 
                            type="password" 
                            className="n-form-control" 
                            id="gs-pass" 
                            style={{backgroundColor: "transparent"}} />
                    </ChaperoneStep> 
                </div> 
                <div className="n-form-field"> 
                    <label className="n-form-check">
                        <ChaperoneStep 
                            index={2} 
                            message={<>Thirdly, if you want to remember the app your inputs just click <b>remember me</b>.</>} 
                            placement="left">
                            <input className="n-form-control" type="checkbox" /> 
                        </ChaperoneStep> 
                        remember me
                    </label> 
                </div>
                <ChaperoneStep 
                    isDone 
                    index={3} 
                    message={<>Lastly, you must press <b>Submit</b>.</>}>
                    <button type="button" className="n-btn">Submit</button>
                </ChaperoneStep> 
            </form>
        </Chaperone>
    </div>
)
Need Help?Email address
Password
 remember me

Don't forget to assign isDone at the last step or else it will throw exception.

ChaperoneStep Singleton #

it is use to make multiple and different id steps in single ChaperoneStep.

import React from "react";
import { Chaperone, ChaperoneStep, Trigger } from "chaperone";
const chaperoneData = [
    {
        index: 0,
        message: <b>Hello there!!</b>,
        find: "img"
    },
    {
        index: 1,
        message: "I'am Fernando.",
        placement: "left",
        find: "#p-name"
    },
    {
        index: 2,
        message: <>aka <b>Mytabworks</b></>,
        placement: "bottom-right",
        find: (children) => children.querySelector("#p-aka")
    },
    {
        index: 3,
        message: "It can even find outside the children scope.",
        placement: "bottom",
        isDone: true,
        find: () => document.querySelector("#chaperonestep-singleton > div")
    }
]
#render(
    <div className="container mb-4">  
        <Chaperone>
            <Trigger label="click here to know me." allowTransition />
            <ChaperoneStep
                navigation={chaperoneData.length}
                placement="top-right"
                propertyMutation={({ index, currentId }, defaultProps) => {
                    return {
                        ...defaultProps, 
                        ...chaperoneData.find(props => props.index === index)
                    }
                }}>
                <div className="d-flex flex-center-y mt-4">
                    <img className="b-round mr-4" src="/images/icons/icon-128x128.png" alt="beard-man"/>
                    <span id="p-name" className="mr-1">Fernando</span>
                    <span id="p-aka">(Mytabworks)</span>
                </div>
            </ChaperoneStep>
        </Chaperone>
    </div>
)import React from "react";
import { Chaperone, ChaperoneStep, Trigger } from "chaperone";
const chaperoneData = [
    {
        index: 0,
        message: <b>Hello there!!</b>,
        find: "img"
    },
    {
        index: 1,
        message: "I'am Fernando.",
        placement: "left",
        find: "#p-name"
    },
    {
        index: 2,
        message: <>aka <b>Mytabworks</b></>,
        placement: "bottom-right",
        find: (children) => children.querySelector("#p-aka")
    },
    {
        index: 3,
        message: "It can even find outside the children scope.",
        placement: "bottom",
        isDone: true,
        find: () => document.querySelector("#chaperonestep-singleton > div")
    }
]
#render(
    <div className="container mb-4">  
        <Chaperone>
            <Trigger label="click here to know me." allowTransition />
            <ChaperoneStep
                navigation={chaperoneData.length}
                placement="top-right"
                propertyMutation={({ index, currentId }, defaultProps) => {
                    return {
                        ...defaultProps, 
                        ...chaperoneData.find(props => props.index === index)
                    }
                }}>
                <div className="d-flex flex-center-y mt-4">
                    <img className="b-round mr-4" src="/images/icons/icon-128x128.png" alt="beard-man"/>
                    <span id="p-name" className="mr-1">Fernando</span>
                    <span id="p-aka">(Mytabworks)</span>
                </div>
            </ChaperoneStep>
        </Chaperone>
    </div>
)
click here to know me.Fernando(Mytabworks)

Multiple ID and Chaining #

you can create multiple guide in single Chaperone and you can chain another ID after done or skip.

import React from "react";
import { Chaperone, ChaperoneStep, Trigger } from "chaperone";

#render(
    <div className="container">  
        <Chaperone onDone={({previousId, trigger}) => {
            if(previousId === "guide-email") {
                trigger("guide-password")
            }
        }}>
            <Trigger id="guide-email" label="Email Help?" allowTransition /><br/>
            <Trigger id="guide-password" label="Password Help?" allowTransition /><br/>
            <form className="mt-3">
                <div className="n-form-field">
                    <ChaperoneStep 
                        navigation={2}
                        id="guide-email" 
                        index={0} 
                        message="It is the Email address label." 
                        placement="top-right"
                        allowSkip={false}>
                        <label htmlFor="mi-email">Email address</label>
                    </ChaperoneStep>
                    <ChaperoneStep 
                        isDone
                        navigation={2}
                        id="guide-email" 
                        index={1} 
                        message="you must type your valid e-mail here." 
                        placement="right-top"
                        onDone={({target, children, dialog}) => { 
                            const test = /^\w+@\w+\.[a-z]{2,4}$/.test(children.value)
                            children.style.borderColor = test ? null : 'red'
                            return test
                        }}>
                        <input 
                            type="email" 
                            className="n-form-control" 
                            id="mi-email" 
                            aria-describedby="emailHelp" 
                            style={{backgroundColor: "transparent"}} />
                    </ChaperoneStep>
                </div>
                <div className="n-form-field">
                    <ChaperoneStep 
                        id="guide-password" 
                        index={0} 
                        message="It is the password label." 
                        placement="top-right"
                        allowSkip={false}>
                        <label htmlFor="mi-pass">Password</label>
                    </ChaperoneStep>
                    <ChaperoneStep 
                        isDone
                        id="guide-password" 
                        index={1} 
                        message="you must put your password here." 
                        placement="top-right">
                        <input 
                            type="password" 
                            className="n-form-control" 
                            id="mi-pass" 
                            style={{backgroundColor: "transparent"}} />
                    </ChaperoneStep> 
                </div>  
                <div className="n-form-field"> 
                    <label className="n-form-check">
                        <input className="n-form-control" type="checkbox" /> 
                        remember me
                    </label> 
                </div>
                <button type="button" className="n-btn">Submit</button>
            </form>
        </Chaperone>
    </div>
)import React from "react";
import { Chaperone, ChaperoneStep, Trigger } from "chaperone";
#render(
    <div className="container">  
        <Chaperone onDone={({previousId, trigger}) => {
            if(previousId === "guide-email") {
                trigger("guide-password")
            }
        }}>
            <Trigger id="guide-email" label="Email Help?" allowTransition /><br/>
            <Trigger id="guide-password" label="Password Help?" allowTransition /><br/>
            <form className="mt-3">
                <div className="n-form-field">
                    <ChaperoneStep 
                        navigation={2}
                        id="guide-email" 
                        index={0} 
                        message="It is the Email address label." 
                        placement="top-right"
                        allowSkip={false}>
                        <label htmlFor="mi-email">Email address</label>
                    </ChaperoneStep>
                    <ChaperoneStep 
                        isDone
                        navigation={2}
                        id="guide-email" 
                        index={1} 
                        message="you must type your valid e-mail here." 
                        placement="right-top"
                        onDone={({target, children, dialog}) => { 
                            const test = /^\w+@\w+\.[a-z]{2,4}$/.test(children.value)
                            children.style.borderColor = test ? null : 'red'
                            return test
                        }}>
                        <input 
                            type="email" 
                            className="n-form-control" 
                            id="mi-email" 
                            aria-describedby="emailHelp" 
                            style={{backgroundColor: "transparent"}} />
                    </ChaperoneStep>
                </div>
                <div className="n-form-field">
                    <ChaperoneStep 
                        id="guide-password" 
                        index={0} 
                        message="It is the password label." 
                        placement="top-right"
                        allowSkip={false}>
                        <label htmlFor="mi-pass">Password</label>
                    </ChaperoneStep>
                    <ChaperoneStep 
                        isDone
                        id="guide-password" 
                        index={1} 
                        message="you must put your password here." 
                        placement="top-right">
                        <input 
                            type="password" 
                            className="n-form-control" 
                            id="mi-pass" 
                            style={{backgroundColor: "transparent"}} />
                    </ChaperoneStep> 
                </div>  
                <div className="n-form-field"> 
                    <label className="n-form-check">
                        <input className="n-form-control" type="checkbox" /> 
                        remember me
                    </label> 
                </div>
                <button type="button" className="n-btn">Submit</button>
            </form>
        </Chaperone>
    </div>
)
Email Help?
Password Help?
Email address
Password
 remember me

you must be extra careful when using onDone and onSkip in Chaperone component. especially if the component is having some sort of state. or else it will be called infinitely and will cause error in your app. as much as posible use hook useCallback without array dependency to prevent some sort of error any further.

Chaperone With Gestures #

you can create and append gestures.

import React from "react";
import { Chaperone, ChaperoneStep, Trigger } from "chaperone";

#render(
    <div className="container">  
        <Chaperone>
            <Trigger label="Need Help?" allowTransition /><br/> 
            <form>
                <div className="row">
                    <div className="n-form-field column-md-6">
                        <label htmlFor="inputEmail4">Email</label>
                        <ChaperoneStep
                            allowNext={false}
                            allowBack={false} 
                            propertyMutation={({ currentId, index }, defaultProps) => {
                                const props = [
                                    {
                                        index: 0, 
                                        message: "click the email input box.",
                                        placement: "top-right",
                                        allowNextOnClick: true,
                                        gesture: (
                                            <div className="custom-click-gesture">
                                                <i className="mytabworks hand-pointer"/>
                                            </div>
                                        )
                                    },
                                    {
                                        index: 1, 
                                        message: "input a valid e-mail address.",
                                        placement: "right",
                                        allowNextOnType: true,
                                        onNext: ({target, children, dialog}) => { 
                                            const test = /^\w+@\w+\.[a-z]{2,4}$/.test(children.value)
                                            children.style.borderColor = test ? null : 'red'
                                            return test
                                        },
                                        gesture: (
                                            <div className="custom-typing-gesture">
                                                <i className="mytabworks icon-keyboard"/>
                                            </div>
                                        )
                                    },
                                ]
                                return { 
                                    ...defaultProps,
                                    ...props.find((each) => each.index === index)
                                }
                            }}>
                            <input type="email" className="n-form-control" id="inputEmail4" placeholder="Email"/>
                        </ChaperoneStep>
                    </div>
                    <div className="n-form-field column-md-6">
                        <label htmlFor="inputPassword4">Password</label>
                        <ChaperoneStep 
                            allowNext={false}
                            allowBack={false} 
                            propertyMutation={({ currentId, index }, defaultProps) => {
                                const props = [
                                    {
                                        index: 2, 
                                        message: "click the password input box.",
                                        placement: "top-right", 
                                        allowNextOnClick: true,
                                        gesture: (
                                            <div className="custom-click-gesture">
                                                <i className="mytabworks hand-pointer"/>
                                            </div>
                                        )
                                    },
                                    {
                                        index: 3, 
                                        message: "input your password.",
                                        placement: "right",
                                        allowNextOnType: true,
                                        onNext: ({target, children, dialog}) => {  
                                            const test = target.value.length > 7
                                            children.style.borderColor = test ? null : 'red'
                                            return test
                                        },
                                        gesture: (
                                            <div className="custom-typing-gesture">
                                                <i className="mytabworks icon-keyboard"/>
                                            </div>
                                        )
                                    },
                                ]
                                return { 
                                    ...defaultProps,
                                    ...props.find((each) => each.index === index)
                                }
                            }}>
                            <input type="password" className="n-form-control" id="inputPassword4" placeholder="Password" />
                        </ChaperoneStep>
                    </div>
                </div>
                <div className="n-form-field">
                    <label htmlFor="inputAddress">Address</label>
                    <input type="text" className="n-form-control" id="inputAddress" placeholder="1234 Main St" />
                </div>
                <div className="n-form-field">
                    <label htmlFor="inputAddress2">Address 2</label>
                    <input type="text" className="n-form-control" id="inputAddress2" placeholder="Apartment, studio, or floor" />
                </div>
                <div className="row">
                    <div className="n-form-field column-md-6">
                        <label htmlFor="inputCity">City</label>
                        <input type="text" className="n-form-control" id="inputCity" />
                    </div>
                    <div className="n-form-field column-md-4">
                        <label htmlFor="inputState">State</label>
                        <select id="inputState" className="n-form-control">
                        <option>Choose...</option>
                        <option>...</option>
                        </select>
                    </div>
                    <div className="n-form-field column-md-2">
                        <label htmlFor="inputZip">Zip</label>
                        <input type="text" className="n-form-control" id="inputZip" />
                    </div>
                </div>
                <div className="n-form-field"> 
                    <label className="n-form-check">
                        <input className="n-form-control" type="checkbox" /> 
                        Check me out
                    </label> 
                </div>
                <ChaperoneStep 
                    isDoneOnClick
                    index={4}
                    message="submit your input."
                    gesture={(
                        <div className="custom-click-gesture">
                            <i className="mytabworks hand-pointer"/>
                        </div>
                    )}>
                    <button type="button" className="n-btn">Sign in</button>
                </ChaperoneStep>
            </form>
        </Chaperone>
    </div>
)import React from "react";
import { Chaperone, ChaperoneStep, Trigger } from "chaperone";
#render(
    <div className="container">  
        <Chaperone>
            <Trigger label="Need Help?" allowTransition /><br/> 
            <form>
                <div className="row">
                    <div className="n-form-field column-md-6">
                        <label htmlFor="inputEmail4">Email</label>
                        <ChaperoneStep
                            allowNext={false}
                            allowBack={false} 
                            propertyMutation={({ currentId, index }, defaultProps) => {
                                const props = [
                                    {
                                        index: 0, 
                                        message: "click the email input box.",
                                        placement: "top-right",
                                        allowNextOnClick: true,
                                        gesture: (
                                            <div className="custom-click-gesture">
                                                <i className="mytabworks hand-pointer"/>
                                            </div>
                                        )
                                    },
                                    {
                                        index: 1, 
                                        message: "input a valid e-mail address.",
                                        placement: "right",
                                        allowNextOnType: true,
                                        onNext: ({target, children, dialog}) => { 
                                            const test = /^\w+@\w+\.[a-z]{2,4}$/.test(children.value)
                                            children.style.borderColor = test ? null : 'red'
                                            return test
                                        },
                                        gesture: (
                                            <div className="custom-typing-gesture">
                                                <i className="mytabworks icon-keyboard"/>
                                            </div>
                                        )
                                    },
                                ]
                                return { 
                                    ...defaultProps,
                                    ...props.find((each) => each.index === index)
                                }
                            }}>
                            <input type="email" className="n-form-control" id="inputEmail4" placeholder="Email"/>
                        </ChaperoneStep>
                    </div>
                    <div className="n-form-field column-md-6">
                        <label htmlFor="inputPassword4">Password</label>
                        <ChaperoneStep 
                            allowNext={false}
                            allowBack={false} 
                            propertyMutation={({ currentId, index }, defaultProps) => {
                                const props = [
                                    {
                                        index: 2, 
                                        message: "click the password input box.",
                                        placement: "top-right", 
                                        allowNextOnClick: true,
                                        gesture: (
                                            <div className="custom-click-gesture">
                                                <i className="mytabworks hand-pointer"/>
                                            </div>
                                        )
                                    },
                                    {
                                        index: 3, 
                                        message: "input your password.",
                                        placement: "right",
                                        allowNextOnType: true,
                                        onNext: ({target, children, dialog}) => {  
                                            const test = target.value.length > 7
                                            children.style.borderColor = test ? null : 'red'
                                            return test
                                        },
                                        gesture: (
                                            <div className="custom-typing-gesture">
                                                <i className="mytabworks icon-keyboard"/>
                                            </div>
                                        )
                                    },
                                ]
                                return { 
                                    ...defaultProps,
                                    ...props.find((each) => each.index === index)
                                }
                            }}>
                            <input type="password" className="n-form-control" id="inputPassword4" placeholder="Password" />
                        </ChaperoneStep>
                    </div>
                </div>
                <div className="n-form-field">
                    <label htmlFor="inputAddress">Address</label>
                    <input type="text" className="n-form-control" id="inputAddress" placeholder="1234 Main St" />
                </div>
                <div className="n-form-field">
                    <label htmlFor="inputAddress2">Address 2</label>
                    <input type="text" className="n-form-control" id="inputAddress2" placeholder="Apartment, studio, or floor" />
                </div>
                <div className="row">
                    <div className="n-form-field column-md-6">
                        <label htmlFor="inputCity">City</label>
                        <input type="text" className="n-form-control" id="inputCity" />
                    </div>
                    <div className="n-form-field column-md-4">
                        <label htmlFor="inputState">State</label>
                        <select id="inputState" className="n-form-control">
                        <option>Choose...</option>
                        <option>...</option>
                        </select>
                    </div>
                    <div className="n-form-field column-md-2">
                        <label htmlFor="inputZip">Zip</label>
                        <input type="text" className="n-form-control" id="inputZip" />
                    </div>
                </div>
                <div className="n-form-field"> 
                    <label className="n-form-check">
                        <input className="n-form-control" type="checkbox" /> 
                        Check me out
                    </label> 
                </div>
                <ChaperoneStep 
                    isDoneOnClick
                    index={4}
                    message="submit your input."
                    gesture={(
                        <div className="custom-click-gesture">
                            <i className="mytabworks hand-pointer"/>
                        </div>
                    )}>
                    <button type="button" className="n-btn">Sign in</button>
                </ChaperoneStep>
            </form>
        </Chaperone>
    </div>
)
Need Help?
Email
Password
Address
Address 2
City
State
Zip
 Check me out

API

Chaperone #

It is the chaperone.

Property Property	Type Type	Default Default	Description Description
autoTrigger	boolean	false	When true, it will be triggered immidiately without clicking the trigger
id	string	-	It is the ID of the autoTrigger
onSkip	function	-	It will be executed if the children ChaperoneStep is skipped. you must be extra careful when using onSkip. especially if the component is having some sort of state. or else it will be called infinitely and will cause error in your app. as much as posible use hook useCallback without array dependency to prevent some sort of error any further.
onDone	function	-	It will be executed when the children ChaperoneStep is done. you must be extra careful when using onDone. especially if the component is having some sort of state. or else it will be called infinitely and will cause error in your app. as much as posible use hook useCallback without array dependency to prevent some sort of error any further.
waitSearchIndex	number	50	It is the waiting time when searching indexes
children	element	-	A children element to render.

ChaperoneStep #

It is the chaperone step.

Property Property	Type Type	Default Default	Description Description
id	string	-	It is use to identify which set of step will be trigger since you can use multiple set of steps to trigger inside Chaperone.
index	number	-	It is use to determine on what index should this component will be pop.
message	string \| element	-	It is the message of the popover.
placement	'top' \| 'bottom' \| 'left' \| 'right' \| 'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right' \| 'left-top' \| 'left-bottom' \| 'right-top' \| 'right-bottom'	bottom-right	It is the placement of the popover.
duration	miliseconds\|number	200	It the duration of the transitions.
navigation	number	0	It is use to show the navigation and how many bullets will be render. most commonly the number of your set steps. when 0, it will be hidden
children	element	-	It will be highligthened target of the step.
autoScrollDelay	miliseconds \| number	150	It is the delay when chasing the next or previous step viewport after triggered.
find	string \| function	-	It use to select element within or outside the children.
allowSkip	boolean	true	When false, the skip button will be hidden.
allowBack	boolean	true	When false, the back step button will be hidden.
allowNext	boolean	true	When false, the next step button will be hidden.
allowNextOnClick	boolean	false	When true, the next step is allowed to be triggered by hitting the highlightened element.
allowNextOnType	boolean	false	When true, the next step is allowed to be triggered by typing the highlightened form input element.
isDone	boolean	false	When true, the done button will be shown, and it is use to tell chaperone that it is the last step. it is required to put it one your last steps on every set or it will bring some error.
isDoneOnClick	boolean	false	When true, done is allowed to be triggered by clicking the highlightened element.
backToIndex	number	-	It is use to jump back a certain index when clicking the back button.
nextToIndex	number	-	It is use to jump on a certain index when triggering all the next event.
onNext	function	-	It will be executed when you triggered all the next events. when you return false it will be prevented to go next.
onBack	function	-	It will be executed when you clicking the back button. when you return false it will prevented you to go back.
onSkip	function	-	It will be executed when you clicking the skip button. when you return false it will prevented you to skip.
onDone	function	-	It will be executed when you triggered all the done events. when you return false it will prevented you to done.
onLoad	function	-	It will be executed when the entering step.
onUnLoad	function	-	It will be executed when leaving step. it is use to cleanup your onLoad messes.
gesture	element \| function	-	It will allow you to render a gestures.
background	object	{}	It allows you to customize the styles of the backdrop, highlight, and gesture.
propertyMutation	function	-	It allows you to make a multiple steps by providing you the currentId and index, and using the defaultProps to get the pre-assigned props.
neumorphism	boolean	false	When true, it change the style of the popover.
hideEvidence	boolean	true	When false, it will not re-render when find matches on every events and will not hide the wrapper <div/> to the children.

Trigger #

It is the trigger to the chaperone.

Property Property	Type Type	Default Default	Description Description
as	elementType	<a>	You can use a custom element type for this component.
label	string\|element	-	It is the label of the trigger.
id	string	-	It is use to determine which set will be open.
index	number	0	It is use to determine which index of the set will be open.
allowTransition	boolean	false	When true, it allows you to transition effect the highlight.

DARK THEME

Chaperone (not publish yet)

API

Warning!