@lightspeed/cirrus-spotlight

Spotlight

A cirrus component that guides the users through an app.

Usage

First, make sure you have been through the install steps steps required to add Flame in your application. Although it's not required to have Flame installed to use Logo, you will need to install its peer dependencies.

This component is divided in 3 different components. SpotlightProvider, Spotlight and Spotlight.Target.

SpotlightProvider

This component is mandatory and will set the overlay when the user is opening the spotlight. It will save at what step the user is in the process and will define what to display in the screen.

Note. The SpotlightContext context is exposed, if you want to use it with React hooks for example.

Spotlight

The children of this component will be highlighted, when the rest of the page will be darkened. It is highlighted when the user arrives at the step defined in the props.

NB. The step numbers are not necessarily defined sequentially. For example, in the page 3 Spotlight components could be defined with the steps 10, 50 and 27. The Provider will just follow the order.

Props

Prop	Type	Description
step (required)	number	The step to which the component should be highlighted.
namespace	string	Optional if you want to specify different spotlights.
children (required)	any	The content to highlight.

Spotlight.Target

This optional component indicates indicates which DOM element (or React Component) the popover (or any of your implementation) should point at.

Props

Prop	Type	Description
step (required)	number	The step to which the component should be shown.
namespace	string	Optional if you want to specify different spotlights.
renderComponent (required)	any	The Component to display when the user is at a specific step.
children (required)	any	The component to target.

The renderComponent has 2 props available:

• spotlight: access to the Spotlight methods and state (see HOC section, bellow)
• targetComponent: The component that is targeted.

It's important to node that there is NO popover defined, on purpose: you can define whatever component that you want. If you need a popover, you can reuse the Cirrus Popover component (see examples below).

Example with single spotlight

import React from 'react';
import { SpotlightProvider, withSpotlight, Spotlight } from '@lightspeed/cirrus/Spotlight';
import Popover from '@lightspeed/cirrus/Popover';

const Popup = ({ spotlight, targetComponent }) => (
  <Popover
    placement="top-start"
    isOpen={true}
    target={({ targetProps, targetEvents }) => (
      <div {...targetProps} {...targetEvents}>
        {targetComponent}
      </div>
    )}
  >
    <div>
      <button onClick={spotlight.nextStep}>next</button>
    </div>
  </Popover>
);

const MyComponent = () => (
  <SpotlightProvider>
    <Spotlight step={1}>
      <Card>
        <CardHeader title="Header" />
        <CardSection>
          <Spotlight.Target step={1} renderComponent={Popup}>
            First important content.
          </Spotlight.Target>
        </CardSection>
        <CardFooter>Footer</CardFooter>
      </Card>
    </Spotlight>
    <Spotlight step={2}>
      <Card>
        <CardHeader title="Header" />
        <CardSection>
          <Spotlight.Target step={2} renderComponent={Popup}>
            Second important content.
          </Spotlight.Target>
        </CardSection>
        <CardFooter>Footer</CardFooter>
      </Card>
    </Spotlight>
  </SpotlightProvider>
);

export default MyComponent;

Example with multiple spotlights

import React from 'react';
import { SpotlightProvider, withSpotlight, Spotlight } from '@lightspeed/cirrus/Spotlight';
import Popover from '@lightspeed/cirrus/Popover';

const Popup = ({ spotlight, targetComponent }) => (
  <Popover
    placement="top-start"
    isOpen={true}
    target={({ targetProps, targetEvents }) => (
      <div {...targetProps} {...targetEvents}>
        {targetComponent}
      </div>
    )}
  >
    <div>
      <button onClick={spotlight.nextStep}>next</button>
    </div>
  </Popover>
);

const MyComponent = () => (
  <SpotlightProvider>
    <Spotlight step={1} namespace="tutorial">
      <Card>
        <CardHeader title="Header" />
        <CardSection>
          <Spotlight.Target step={1} namespace="tutorial" renderComponent={Popup}>
            First important content.
          </Spotlight.Target>
        </CardSection>
        <CardFooter>Footer</CardFooter>
      </Card>
    </Spotlight>
    <Spotlight step={2} namespace="tutorial">
      <Card>
        <CardHeader title="Header" />
        <CardSection>
          <Spotlight.Target step={2} namespace="tutorial" renderComponent={Popup}>
            Second important content.
          </Spotlight.Target>
        </CardSection>
        <CardFooter>Footer</CardFooter>
      </Card>
    </Spotlight>

    <Spotlight step={1} namespace="first-time">
      <Spotlight.Target step={1} namespace="first-time" renderComponent={Popup}>
        <div>Important text that the user shouldn't miss at the first connection.</div>
      </Spotlight.Target>
    </Spotlight>
  </SpotlightProvider>
);

export default MyComponent;

withSpotlight HOC

This HOC will bring the methods and state of the Spotlight. It provides methods to go to the next step, the previous step, start and stop the current Spotlight.

The HOC can be useful to access to the methods to start the spotlight.

Props

Prop	Description
currentStep: number	The current step number the user is at.
currentNS: string	The id of the current spotlight running.
nextStep(): void	Method to go to the next step in the current spotlight. If there is no next step defined, the spotlight will stop.
previousStep(): void	Method to go to the previous step in the current spotlight. If there is no previous step defined, the spotlight will stop.
start(namespace?: number): void	Start the Spotlight. If an id is provided, start a specific spotlight.
stop(): void	Start the Spotlight. If an id is provided, start a specific spotlight.

Example

import React from 'react';
import { SpotlightProvider, withSpotlight, Spotlight } from '@lightspeed/cirrus/Spotlight';

const StartTutorial = withSpotlight(({ spotlight }) => (
  <button onClick={spotlight.start}>StartTutorial</button>
));

const MyComponent = () => (
  <SpotlightProvider>
    <Spotlight step={1}>
      <Card>
        <CardHeader title="Header" />
        <CardSection>First important content.</CardSection>
        <CardFooter>Footer</CardFooter>
      </Card>
    </Spotlight>
  </SpotlightProvider>
);

export default MyComponent;