Add initial visual tour component

Author: andreas-schultz

src/components/VisualTour/VisualTour.stories.tsx

@@ -0,0 +1,79 @@
+import React from "react";
+import { Meta, Story } from "@storybook/react";
+
+import {
+    Button,
+    Icon,
+    OverviewItem,
+    OverviewItemDepiction,
+    OverviewItemDescription,
+    OverviewItemLine,
+    Toolbar,
+    ToolbarSection,
+    VisualTourProps,
+} from "../../../index";
+
+import VisualTour from "./VisualTour";
+
+export default {
+    title: "Components/VisualTour",
+    component: VisualTour,
+    argTypes: {},
+} as Meta<typeof VisualTour>;
+
+const Template: Story<typeof VisualTour> = (args: VisualTourProps) => {
+    const [closed, setClosed] = React.useState<boolean>(true);
+
+    return (
+        <div style={{ minHeight: "600px", minWidth: "800px" }}>
+            <Toolbar id={"tourContainer"}>
+                <ToolbarSection id={"textSection"} canGrow={true}>
+                    Some text
+                </ToolbarSection>
+                <ToolbarSection id={"buttonSection"}>
+                    <Button id={"actionA"}>Action A</Button>
+                    <Button id={"actionB"}>Action B</Button>
+                    <Button id={"startTour"} intent={"primary"} onClick={() => setClosed(false)}>
+                        Start tour!
+                    </Button>
+                </ToolbarSection>
+            </Toolbar>
+            {!closed ? <VisualTour {...args} onClose={() => setClosed(true)} /> : null}
+        </div>
+    );
+};
+
+export const Default = Template.bind({});
+const defaultArgs: VisualTourProps = {
+    containerElementQuery: "#tourContainer",
+    steps: [
+        {
+            title: "First step",
+            content: "This is a demonstration of a visual tour. A step can be simple text.",
+        },
+        {
+            title: "Custom content",
+            content: () => (
+                <OverviewItem>
+                    <OverviewItemDepiction>
+                        <Icon name={"item-info"} />
+                    </OverviewItemDepiction>
+                    <OverviewItemDescription>
+                        <OverviewItemLine>
+                            Or a step can be arbitrary content that is displayed in a modal by default.
+                        </OverviewItemLine>
+                        <OverviewItemLine>The developer can choose what's appropriate.</OverviewItemLine>
+                    </OverviewItemDescription>
+                </OverviewItem>
+            ),
+        },
+        {
+            title: "Highlight elements",
+            content:
+                "It's possible to highlight specific elements on a page. The step content is then displayed in a kind of tooltip instead of a modal.",
+            highlightElementQuery: "#actionA",
+        },
+    ],
+    onClose: () => {},
+};
+Default.args = defaultArgs;

src/components/VisualTour/VisualTour.tsx

@@ -0,0 +1,95 @@
+import React from "react";
+
+import { CLASSPREFIX as eccgui } from "../../configuration/constants";
+import Button from "../Button/Button";
+import { SimpleDialog } from "../Dialog";
+
+export interface VisualTourProps {
+    /** The CSS query of the container element that contains the feature that will be given a tour of.
+     * If element highlighting is enabled, this will grey out every other element in the container element.
+     * Default: body*/
+    containerElementQuery?: string;
+    /** The steps of the tour. */
+    steps: VisualTourStep[];
+    /** Called when the tour is cancelled or closed at then end. This should usually remove the component from the outside. */
+    onClose: () => void;
+    /** Label of the button to close the tour. */
+    closeLabel?: string;
+    /** The label for the next button. */
+    nextLabel?: string;
+}
+
+interface VisualTourStep {
+    /** (Short) Title of the current step. */
+    title: string;
+    /** The description or more elaborate content element that is shown in the modal/overlay. */
+    content: string | (() => React.JSX.Element);
+    /** Optional element that should be highlighted, every other element in the container element is greyed out. */
+    highlightElementQuery?: string;
+}
+
+const containerHighlightClass = `${eccgui}-visual-tour__container`;
+const highlightElementClass = `${eccgui}-visual-tour__highlighted-element`;
+
+/** A visual tour multi-step tour of the current view. */
+export const VisualTour = ({
+    containerElementQuery = "body",
+    steps,
+    onClose,
+    closeLabel = "Close",
+    nextLabel = "Next",
+}: VisualTourProps) => {
+    const [currentStepIndex, setCurrentStepIndex] = React.useState<number>(0);
+    const [currentStepComponent, setCurrentStepComponent] = React.useState<React.JSX.Element | null>(null);
+
+    React.useEffect(() => {
+        const step = steps[currentStepIndex];
+        if (!step) {
+            // This should not happen
+            setCurrentStepComponent(null);
+            onClose();
+            return;
+        }
+        const hasNextStep = currentStepIndex + 1 < steps.length;
+        // Configure optional highlighting
+        const element = document.querySelector(containerElementQuery);
+        if (element) {
+            // Remove previous element highlight
+            element.classList.remove(containerHighlightClass);
+            document.querySelector(`.${highlightElementClass}`)?.classList.remove(highlightElementClass);
+            if (step.highlightElementQuery) {
+                const elementToHighlight = document.querySelector(step.highlightElementQuery);
+                if (elementToHighlight) {
+                    element.classList.add(containerHighlightClass);
+                    elementToHighlight.classList.add(highlightElementClass);
+                }
+            }
+        }
+        setCurrentStepComponent(
+            <SimpleDialog
+                title={step.title + ` ${currentStepIndex + 1} / ${steps.length}`}
+                isOpen={true}
+                preventSimpleClosing={true}
+                onClose={onClose}
+                actions={[
+                    <Button onClick={onClose}>{closeLabel}</Button>,
+                    hasNextStep ? (
+                        <Button
+                            onClick={() => {
+                                setCurrentStepIndex(currentStepIndex + 1);
+                            }}
+                        >
+                            {nextLabel}: {steps[currentStepIndex + 1].title}
+                        </Button>
+                    ) : null,
+                ]}
+            >
+                {typeof step.content === "string" ? step.content : step.content()}
+            </SimpleDialog>
+        );
+    }, [currentStepIndex]);
+
+    return currentStepComponent;
+};
+
+export default VisualTour;

src/components/VisualTour/visualTour.scss

@@ -0,0 +1,7 @@
+.eccapp-visual-tour__container {
+    :not(.eccapp-visual-tour__highlighted-element) {
+        z-index: 0;
+        opacity: $eccgui-opacity-disabled;
+        filter: grayscale(1);
+    }
+}

src/components/index.scss

@@ -34,6 +34,7 @@
 @import "./TagInput/taginput";
 @import "./Toolbar/toolbar";
 @import "./Tooltip/tooltip";
+@import "./VisualTour/visualTour";
 @import "./Tree/tree";
 @import "./Typography/typography";
 @import "./Workspace/workspace";

src/components/index.ts

@@ -49,5 +49,6 @@ export * from "./Tree/Tree";
 export * from "./Typography";
 export * from "./Workspace";
 export * from "./ContentGroup/ContentGroup";
+export * from "./VisualTour/VisualTour";
 
 export * from "./interfaces";