@eccenca/gui-elements 24.4.1-featurechatcomponentscmem6775.3 → 24.4.1-featurepreparefinalnextcmem6943.0

package/src/components/VisualTour/VisualTour.tsx

@@ -0,0 +1,381 @@
+import React from "react";
+import { createPortal } from "react-dom";
+import { Classes as BlueprintClasses } from "@blueprintjs/core";
+import { createPopper } from "@popperjs/core";
+
+import { CLASSPREFIX as eccgui } from "../../configuration/constants";
+import {
+    Badge,
+    Button,
+    Card,
+    CardActions,
+    CardActionsAux,
+    CardContent,
+    CardHeader,
+    CardOptions,
+    CardTitle,
+    IconButton,
+    Markdown,
+    ModalSize,
+    SimpleDialog,
+    Spacing,
+    TooltipSize,
+} from "../../index";
+
+export interface VisualTourProps {
+    /** 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;
+    /** The label for the 'previous' button. */
+    prevLabel?: string;
+    /** The step target is usable, e.g. it can be clicked. */
+    usableStepTarget?: boolean;
+    /** Need to be set to `true` that the tour is displayed. */
+    isOpen?: boolean;
+}
+
+export interface VisualTourStep {
+    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. The step content is displayed as a tooltip instead of a modal.
+     * In case of an array, the first match is highlighted. */
+    highlightElementQuery?: string | string[];
+    /** The texts used in the step, e.g. when custom layouts are rendered, these will be used for the text strings. */
+    texts?: Record<string, string>;
+    /** An image URL. This will be displayed in the step description. */
+    image?: string;
+    /** The size of the tooltip or modal. */
+    size?: TooltipSize | ModalSize;
+    /** The step target is usable, e.g. it can be clicked. Overwrites the setting in `<VisualTour/>`. */
+    usableStepTarget?: boolean;
+}
+
+/** This should be used for defining steps in a separate object/file. Use with 'satisfies' after the object definition. */
+export type VisualTourStepDefinitions = Record<string, Partial<VisualTourStep>>;
+
+const highlightElementBaseClass = `${eccgui}-visual-tour__highlighted-element`;
+
+/** A visual tour multi-step tour of the current view. */
+export const VisualTour = ({
+    steps,
+    onClose,
+    closeLabel = "Close",
+    nextLabel = "Next",
+    prevLabel = "Back",
+    usableStepTarget = false,
+    isOpen = false,
+}: VisualTourProps) => {
+    if (isOpen === false) {
+        return null;
+    }
+
+    const [currentStepIndex, setCurrentStepIndex] = React.useState<number>(0);
+    const [currentStepComponent, setCurrentStepComponent] = React.useState<React.JSX.Element | null>(null);
+
+    React.useEffect(() => {
+        const closeTour = () => {
+            // clear observer and disconnect
+            if (lastObserver) {
+                lastObserver.takeRecords();
+                lastObserver.disconnect();
+            }
+            // empty step
+            setCurrentStepComponent(null);
+            // remove highlight classes
+            document.querySelector(`.${highlightElementBaseClass}`)?.classList.remove(highlightElementBaseClass);
+            document
+                .querySelector(`.${highlightElementBaseClass}--useable`)
+                ?.classList.remove(`${highlightElementBaseClass}--useable`);
+            // call callback function from outside
+            onClose();
+        };
+
+        const step = steps[currentStepIndex];
+        if (!step) {
+            // This should not happen
+            closeTour();
+            return;
+        }
+        const highlightElementClass = (
+            typeof step["usableStepTarget"] === "undefined" ? usableStepTarget : step["usableStepTarget"]
+        )
+            ? `${highlightElementBaseClass}--useable`
+            : highlightElementBaseClass;
+        const hasNextStep = currentStepIndex + 1 < steps.length;
+        const hasPreviousStep = currentStepIndex > 0;
+        // Configure optional highlighting
+        let elementToHighlight: HTMLElement | null = null;
+        let lastObserver: MutationObserver | null = null;
+        const setStepComponent = () => {
+            const stepDisplay = (
+                <Badge tagProps={{ emphasis: "weaker" }} size="large">
+                    {` ${currentStepIndex + 1}/${steps.length} `}
+                </Badge>
+            );
+            const closeButton = <IconButton name="navigation-close" text={closeLabel} onClick={closeTour} />;
+            const titleOptions = (
+                <>
+                    {stepDisplay}
+                    {closeButton}
+                </>
+            );
+            const actionButtons = [
+                hasNextStep ? (
+                    <Button
+                        key={"next"}
+                        variant="outlined"
+                        intent={"primary"}
+                        onClick={() => {
+                            setCurrentStepIndex(currentStepIndex + 1);
+                        }}
+                        rightIcon={"navigation-next"}
+                    >
+                        {nextLabel}: {steps[currentStepIndex + 1].title}
+                    </Button>
+                ) : (
+                    <Button
+                        key={"close"}
+                        text={closeLabel}
+                        onClick={closeTour}
+                        variant="outlined"
+                        intent={"primary"}
+                        rightIcon={"navigation-close"}
+                    />
+                ),
+                hasPreviousStep ? (
+                    <CardActionsAux>
+                        <Button
+                            key={"prev"}
+                            variant="outlined"
+                            onClick={() => {
+                                setCurrentStepIndex(currentStepIndex - 1);
+                            }}
+                            icon={"navigation-previous"}
+                        >
+                            {prevLabel}
+                        </Button>
+                    </CardActionsAux>
+                ) : null,
+            ];
+            // TODO: What to do if an element should have been highlighted, but none was found?
+            if (elementToHighlight) {
+                setCurrentStepComponent(
+                    <StepPopover
+                        highlightedElement={elementToHighlight}
+                        titleOption={titleOptions}
+                        actionButtons={actionButtons}
+                        step={step}
+                    />
+                );
+            } else {
+                setCurrentStepComponent(
+                    <StepModal
+                        titleOption={titleOptions}
+                        actionButtons={actionButtons}
+                        step={step}
+                        onClose={closeTour}
+                    />
+                );
+            }
+        };
+        const addElementHighlighting = () => {
+            if (step.highlightElementQuery) {
+                const queries: string[] =
+                    typeof step.highlightElementQuery === "string"
+                        ? [step.highlightElementQuery]
+                        : step.highlightElementQuery;
+                queries.forEach((query) => {
+                    if (elementToHighlight == null) {
+                        elementToHighlight = document.querySelector(query);
+                    }
+                });
+            } else {
+                elementToHighlight = null;
+            }
+            if (elementToHighlight) {
+                // Typescript for some reason incorrectly infers the type of elementToHighlight as never
+                (elementToHighlight as HTMLElement).classList.add(highlightElementClass);
+                (elementToHighlight as HTMLElement).scrollIntoView({
+                    behavior: "smooth",
+                    block: "center",
+                });
+                if (lastObserver) {
+                    lastObserver.disconnect();
+                }
+                lastObserver = new MutationObserver(function () {
+                    // Re-new element highlighting
+                    if (step.highlightElementQuery) {
+                        if (!document.body.contains(elementToHighlight)) {
+                            // Element has been removed or replaced
+                            elementToHighlight = null;
+                            addElementHighlighting();
+                        } else if (!elementToHighlight?.classList.contains(highlightElementClass)) {
+                            // Only the classes have been removed
+                            elementToHighlight?.classList.add(highlightElementClass);
+                        }
+                    }
+                });
+                lastObserver.observe(document.body, { childList: true, subtree: true });
+            }
+            setStepComponent();
+        };
+        addElementHighlighting();
+        return () => {
+            // Remove previous element highlight
+            document.querySelector(`.${highlightElementClass}`)?.classList.remove(highlightElementClass);
+            if (lastObserver) {
+                lastObserver.disconnect();
+            }
+        };
+    }, [currentStepIndex, usableStepTarget]);
+
+    return currentStepComponent;
+};
+
+interface StepModalProps {
+    step: VisualTourStep;
+    // Current step starting with 1
+    titleOption: React.JSX.Element;
+    // Close the visual tour
+    onClose: () => void;
+    // The navigation buttons
+    actionButtons: (React.JSX.Element | null)[];
+}
+
+// Main content of a step
+const StepContent = ({ step }: { step: VisualTourStep }) => {
+    return (
+        <>
+            {step.image && (
+                <>
+                    <img src={step.image} />
+                    <Spacing size="small" />
+                </>
+            )}
+            {typeof step.content === "string" ? <Markdown>{step.content}</Markdown> : step.content()}
+        </>
+    );
+};
+
+/** Modal that is displayed for a step. */
+const StepModal = ({ step, titleOption, onClose, actionButtons }: StepModalProps) => {
+    return (
+        <SimpleDialog
+            title={step.title}
+            headerOptions={titleOption}
+            isOpen={true}
+            preventSimpleClosing={true}
+            onClose={onClose}
+            actions={actionButtons}
+            size={step.size === "medium" ? "regular" : step.size ?? "regular"}
+            overlayClassName={`${eccgui}-visual-tour__dialog`}
+        >
+            <StepContent step={step} />
+        </SimpleDialog>
+    );
+};
+
+interface StepPopoverProps {
+    highlightedElement: Element;
+    step: VisualTourStep;
+    // Current step starting with 1
+    titleOption: React.JSX.Element;
+    // The navigation buttons
+    actionButtons: (React.JSX.Element | null)[];
+}
+
+/** Popover that is displayed and points at the highlighted element. */
+const StepPopover = ({ highlightedElement, step, titleOption, actionButtons }: StepPopoverProps) => {
+    const tooltipRef = React.useCallback(
+        (tooltip: HTMLDivElement | null) => {
+            if (tooltip) {
+                createPopper(highlightedElement, tooltip, {
+                    placement: "auto",
+                    modifiers: [
+                        {
+                            name: "offset",
+                            options: {
+                                offset: [0, 15],
+                            },
+                        },
+                    ],
+                });
+            }
+        },
+        [highlightedElement]
+    );
+
+    const backdropRef = React.useCallback(
+        (backdrop: HTMLDivElement | null) => {
+            const highlightStencil = () => {
+                const targetRect = highlightedElement.getBoundingClientRect();
+                backdrop!.style.left = `calc(${
+                    targetRect.left + window.scrollX + "px"
+                } - var(--${eccgui}-visual-tour-focus-padding))`;
+                backdrop!.style.top = `calc(${
+                    targetRect.top + window.scrollY + "px"
+                } - var(--${eccgui}-visual-tour-focus-padding))`;
+                backdrop!.style.width = `calc(${
+                    targetRect.width + "px"
+                } + 2 * var(--${eccgui}-visual-tour-focus-padding))`;
+                backdrop!.style.height = `calc(${
+                    targetRect.height + "px"
+                } + 2 * var(--${eccgui}-visual-tour-focus-padding))`;
+            };
+            if (backdrop) {
+                highlightStencil();
+                window.addEventListener("resize", highlightStencil);
+                return () => {
+                    window.removeEventListener("resize", highlightStencil);
+                };
+            }
+            return;
+        },
+        [highlightedElement]
+    );
+
+    return createPortal(
+        <div className={`${eccgui}-visual-tour`}>
+            <div className={`${eccgui}-visual-tour__focushelper`} ref={backdropRef} />
+            <div>
+                <div className={`${eccgui}-visual-tour__backdrop`} />
+            </div>
+            <div
+                className={
+                    `${eccgui}-visual-tour__overlay` +
+                    ` ${eccgui}-visual-tour__overlay--${step.size ?? "large"}` +
+                    ` ${BlueprintClasses.POPOVER}`
+                }
+                role="tooltip"
+                ref={tooltipRef}
+            >
+                <div
+                    className={`${eccgui}-visual-tour__arrow ${BlueprintClasses.POPOVER_ARROW}`}
+                    data-popper-arrow
+                    aria-hidden
+                />
+                <div className={`${BlueprintClasses.POPOVER_CONTENT} ${eccgui}-visual-tour__overlay__content`}>
+                    <Card isOnlyLayout elevation={-1} whitespaceAmount="small">
+                        <CardHeader>
+                            <CardTitle>{step.title}</CardTitle>
+                            <CardOptions>{titleOption}</CardOptions>
+                        </CardHeader>
+                        <CardContent>
+                            <StepContent step={step} />
+                        </CardContent>
+                        <CardActions inverseDirection>{actionButtons}</CardActions>
+                    </Card>
+                </div>
+            </div>
+        </div>,
+        document.body
+    );
+};
+
+export default VisualTour;

package/src/components/VisualTour/stories/VisualTour.stories.tsx

@@ -0,0 +1,112 @@
+import React from "react";
+import { Meta, StoryFn } from "@storybook/react";
+
+import {
+    Button,
+    Icon,
+    OverflowText,
+    OverviewItem,
+    OverviewItemDepiction,
+    OverviewItemDescription,
+    OverviewItemLine,
+    Toolbar,
+    ToolbarSection,
+    VisualTour,
+    VisualTourProps,
+} from "../../../../index";
+
+import stepDefinitionsEn from "./defaultTour";
+
+export default {
+    title: "Components/VisualTour",
+    component: VisualTour,
+    argTypes: {},
+} as Meta<typeof VisualTour>;
+
+const Template: StoryFn<typeof VisualTour> = (args: VisualTourProps) => {
+    const [isOpen, setIsOpen] = React.useState<boolean | undefined>();
+
+    return (
+        <div style={{ minHeight: "600px", minWidth: "800px" }}>
+            <Toolbar id={"tourContainer"}>
+                <ToolbarSection canGrow={true}>
+                    <span id={"textSection"}>Some text</span>
+                </ToolbarSection>
+                <ToolbarSection id={"buttonSection"}>
+                    <Button id={"actionA"}>Action A</Button>
+                    <Button id={"actionB"}>Action B</Button>
+                    <Button id={"startTour"} intent={"primary"} onClick={() => setIsOpen(true)}>
+                        Start tour!
+                    </Button>
+                </ToolbarSection>
+            </Toolbar>
+            <div id="actionC" style={{ margin: "1rem", padding: "1rem", border: "dotted 1px lightgray" }}>
+                Some other element for the tour.
+            </div>
+            <div style={{ height: "100vh" }} />
+            <div id="actionD" style={{ margin: "1rem", padding: "1rem", border: "dotted 1px lightgray" }}>
+                Another element for the tour, not visible at first.
+            </div>
+            <VisualTour
+                {...args}
+                onClose={() => setIsOpen(false)}
+                isOpen={typeof isOpen !== "undefined" ? isOpen : args.isOpen}
+            />
+        </div>
+    );
+};
+
+const stepDefinitions = stepDefinitionsEn;
+
+export const Default = Template.bind({});
+const defaultArgs: VisualTourProps = {
+    steps: [
+        {
+            ...stepDefinitions.firstStep,
+        },
+        {
+            ...stepDefinitions.customContent,
+            content: () => {
+                const texts = stepDefinitions.customContent.texts;
+                return (
+                    <OverviewItem>
+                        <OverviewItemDepiction>
+                            <Icon name={"item-info"} />
+                        </OverviewItemDepiction>
+                        <OverviewItemDescription>
+                            <OverviewItemLine>
+                                <OverflowText>{texts.firstLine}</OverflowText>
+                            </OverviewItemLine>
+                            <OverviewItemLine>
+                                <OverflowText>{texts.secondLine}</OverflowText>
+                            </OverviewItemLine>
+                        </OverviewItemDescription>
+                    </OverviewItem>
+                );
+            },
+        },
+        {
+            ...stepDefinitions.highlightElementA,
+            highlightElementQuery: "#actionA",
+        },
+        {
+            ...stepDefinitions.highlightElementB,
+            highlightElementQuery: "#actionB",
+        },
+        {
+            ...stepDefinitions.highlightElementLeft,
+            highlightElementQuery: "#textSection",
+        },
+        {
+            ...stepDefinitions.highlightElementC,
+            highlightElementQuery: "#actionC",
+        },
+        {
+            ...stepDefinitions.highlightElementD,
+            highlightElementQuery: "#actionD",
+        },
+    ],
+    onClose: () => {},
+    isOpen: false,
+};
+Default.args = defaultArgs;

package/src/components/VisualTour/stories/defaultTour.ts

@@ -0,0 +1,42 @@
+import { VisualTourStepDefinitions } from "../VisualTour";
+
+const definition = {
+    firstStep: {
+        title: "First step",
+        content: "This is a demonstration of a visual tour. A step can be simple text.",
+    },
+    customContent: {
+        title: "Custom content",
+        texts: {
+            firstLine: "Or a step can be arbitrary content that is displayed in a modal by default.",
+            secondLine: "The developer can choose what's appropriate.",
+        },
+    },
+    highlightElementA: {
+        title: "Highlight element A",
+        usableStepTarget: false,
+        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.",
+    },
+    highlightElementB: {
+        title: "Highlight element B",
+        usableStepTarget: true,
+        content: "Context overlay for another highlighted element.",
+    },
+    highlightElementLeft: {
+        title: "Highlight element on the left & portrait image",
+        image: "https://upload.wikimedia.org/wikipedia/commons/a/a3/Knowledge_graph_installation_at_the_Futurium_Berlin_21.jpg",
+        content: "The tooltip is placed where it is best seen by the user.",
+    },
+    highlightElementC: {
+        title: "Highlight element C & landscape image",
+        image: "https://upload.wikimedia.org/wikipedia/commons/1/15/Knowledge_graph_installation_at_the_Futurium_Berlin.jpg",
+        content: "Element outside tour container.",
+    },
+    highlightElementD: {
+        title: "Highlight element D",
+        content: "Element not visible at first.",
+    },
+} satisfies VisualTourStepDefinitions;
+
+export default definition;

package/src/components/VisualTour/visualTour.scss

@@ -0,0 +1,83 @@
+.#{$eccgui}-visual-tour {
+    opacity: 1;
+
+    --#{$eccgui}-visual-tour-focus-padding: #{0.5 * $eccgui-size-block-whitespace};
+}
+
+[class*="#{$eccgui}-visual-tour__highlighted-element"] {
+    .#{$eccgui}-overviewitem__actions--hiddeninteractions:has(&) {
+        display: inherit;
+    }
+}
+
+.#{$eccgui}-visual-tour__highlighted-element--useable {
+    position: relative;
+    z-index: 999999 !important;
+}
+
+.#{$eccgui}-visual-tour__focushelper {
+    position: absolute;
+    z-index: 8001; // 1 over application header
+    box-sizing: border-box;
+    border: 2px solid $eccgui-color-accent;
+    border-radius: var(--#{$eccgui}-visual-tour-focus-padding);
+    box-shadow: 0 0 0 10000px $eccgui-color-modal-backdrop;
+}
+
+.#{$eccgui}-visual-tour__backdrop {
+    position: fixed;
+    inset: 0;
+    box-sizing: content-box;
+    opacity: 0;
+}
+
+.#{$eccgui}-visual-tour__arrow {
+    &::before {
+        background: $card-background-color;
+    }
+
+    .#{$eccgui}-visual-tour__overlay[data-popper-placement="top"] & {
+        bottom: -0.5 * $eccgui-size-block-whitespace;
+    }
+    .#{$eccgui}-visual-tour__overlay[data-popper-placement="right"] & {
+        left: -0.5 * $eccgui-size-block-whitespace;
+    }
+    .#{$eccgui}-visual-tour__overlay[data-popper-placement="bottom"] & {
+        top: -0.5 * $eccgui-size-block-whitespace;
+    }
+    .#{$eccgui}-visual-tour__overlay[data-popper-placement="left"] & {
+        right: -0.5 * $eccgui-size-block-whitespace;
+    }
+}
+
+.#{$eccgui}-visual-tour__overlay {
+    z-index: 8002; // 2 over application header
+    &--small {
+        @extend .#{$eccgui}-tooltip--small;
+    }
+
+    &--medium {
+        @extend .#{$eccgui}-tooltip--medium;
+    }
+
+    &--large {
+        @extend .#{$eccgui}-tooltip--large;
+    }
+}
+
+.#{$eccgui}-card__content {
+    .#{$eccgui}-visual-tour__overlay__content & {
+        max-height: 45vh;
+    }
+    .#{$eccgui}-visual-tour__overlay__content &,
+    .#{$eccgui}-visual-tour__dialog & {
+        img {
+            display: block;
+            width: auto;
+            max-width: 100%;
+            height: auto;
+            max-height: 40vh;
+            margin: 0 auto;
+        }
+    }
+}

package/src/components/index.scss

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

package/src/components/index.ts

@@ -1,16 +1,13 @@
 export * from "./Accordion";
 export * from "./Application";
-export * from "./AutocompleteField";
-export * from "./SuggestField";
-export * from "./AutoSuggestion";
-export * from "./CodeAutocompleteField";
 export * from "./Badge/Badge";
 export * from "./Breadcrumb";
 export * from "./Button/Button";
 export * from "./Card";
 export * from "./Chat";
 export * from "./Checkbox/Checkbox";
-export * from "./ContentShrinker/ContentShrinker";
+export * from "./CodeAutocompleteField";
+export * from "./ContentGroup/ContentGroup";
 export * from "./ContextOverlay";
 export * from "./Depiction/Depiction";
 export * from "./Dialog";
@@ -25,8 +22,7 @@ export * from "./Label/Label";
 export * from "./Link/Link";
 export * from "./List/List";
 export * from "./Menu";
-export * from "./MultiSelect/MultiSelect";
-export * from "./MultiSuggestField/MultiSuggestField";
+export * from "./MultiSuggestField";
 export * from "./Notification";
 export * from "./OverviewItem";
 export * from "./Pagination/Pagination";
@@ -40,16 +36,18 @@ export * from "./Skeleton/Skeleton";
 export * from "./Spinner/Spinner";
 export * from "./Sticky";
 export * from "./Structure";
+export * from "./SuggestField";
 export * from "./Switch/Switch";
 export * from "./Table";
 export * from "./Tabs";
 export * from "./Tag";
 export * from "./TextField";
+export * from "./TextReducer/TextReducer";
 export * from "./Toolbar";
 export * from "./Tooltip/Tooltip";
 export * from "./Tree/Tree";
 export * from "./Typography";
+export * from "./VisualTour/VisualTour";
 export * from "./Workspace";
-export * from "./ContentGroup/ContentGroup";
 
 export * from "./interfaces";

package/src/configuration/_libprefix.scss

@@ -0,0 +1 @@
+$eccgui: "eccgui" !default;