npm package: @lightspeed/cirrus-spotlight
Description: Cirrus Spotlight Component
Author: Lightspeed
Latest version: 1.0.1

# Spotlight

A cirrus component that guides the users through an app.

## Usage

First, make sure you have been through the [install steps](https://github.com/lightspeed/flame#installing) 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](?selectedKind=Popover) (see examples below).

### Example with single spotlight

```js
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

```js
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

```js
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;
```