@eccenca/gui-elements 24.4.1 → 25.0.0-rc.0

package/src/components/TextReducer/TextReducer.tsx

@@ -0,0 +1,98 @@
+import React from "react";
+import { renderToString } from "react-dom/server";
+import * as ReactIs from "react-is";
+
+import { CLASSPREFIX as eccgui } from "../../configuration/constants";
+
+import { OverflowText, OverflowTextProps } from "./../Typography";
+
+export interface TextReducerProps extends Pick<React.HTMLAttributes<HTMLElement>, "children"> {
+    /**
+     * Maximum number of nodes that are used from the HTML content.
+     * An HTML element with multiple sub elements is count as only 1 node.
+     */
+    maxNodes?: number;
+    /**
+     * Set maximum string length of returned content.
+     */
+    maxLength?: number;
+    /**
+     * Wrap returned content automatically in a `OverflowText` component.
+     * This way you always will get a element returned that displays only 1 single text line.
+     */
+    useOverflowTextWrapper?: boolean;
+    /**
+     * Specify more `OverflowText` properties used when `useOverflowTextWrapper` is set to `true`.
+     */
+    overflowTextProps?: Omit<OverflowTextProps, "passDown">;
+}
+
+/**
+ * Component to reduce HTML markup content to simple text.
+ * Display can be wrapped easily in `OverflowText`.
+ */
+export const TextReducer = ({
+    children,
+    maxNodes,
+    maxLength,
+    useOverflowTextWrapper,
+    overflowTextProps,
+}: TextReducerProps) => {
+    const nodesCount = 0;
+
+    const onlyText = (children: React.ReactNode | React.ReactNode[], maxNodes?: number): string => {
+        if (typeof maxNodes !== "undefined" && nodesCount >= maxNodes) {
+            return "";
+        }
+
+        if (children instanceof Array) {
+            return children
+                .slice(0, maxNodes)
+                .map((child: React.ReactNode) => {
+                    return onlyText(child, maxNodes);
+                })
+                .join(" ");
+        }
+
+        return React.Children.toArray(children)
+            .slice(0, maxNodes)
+            .map((child) => {
+                if (ReactIs.isFragment(child)) {
+                    return onlyText(child.props?.children, maxNodes);
+                }
+                if (typeof child === "string") {
+                    return child;
+                }
+                if (typeof child === "number") {
+                    return child.toString();
+                }
+                if (ReactIs.isElement(child)) {
+                    // for some reasons `renderToString` returns empty string if not wrappe in a `span`
+                    return renderToString(<span>{child}</span>);
+                }
+                return "";
+            })
+            .join(" ")
+            .replaceAll("\n", " ");
+    };
+
+    const shrinkedContent = onlyText(children, maxNodes)
+        .replaceAll(/<[^\s][^>]*>/g, "")
+        .slice(0, maxLength);
+
+    return useOverflowTextWrapper ? (
+        <OverflowText
+            {...overflowTextProps}
+            className={
+                `${eccgui}-textreducer` +
+                (overflowTextProps && overflowTextProps.className ? ` ${overflowTextProps.className}` : "")
+            }
+        >
+            {shrinkedContent}
+        </OverflowText>
+    ) : (
+        <>{shrinkedContent}</>
+    );
+};
+
+export default TextReducer;

package/src/components/Tooltip/Tooltip.stories.tsx

@@ -2,6 +2,7 @@ import React from "react";
 import { loremIpsum } from "react-lorem-ipsum";
 import { OverlaysProvider } from "@blueprintjs/core";
 import { Meta, StoryFn } from "@storybook/react";
+import { fn } from "@storybook/test";
 
 import { Tooltip } from "../../index";
 
@@ -34,6 +35,7 @@ Default.args = {
     children: "hover me",
     content: testContent,
     addIndicator: true,
+    onOpening: fn(),
 };
 
 export const MarkdownSupport = Template.bind({});

package/src/components/Tooltip/Tooltip.test.tsx

@@ -0,0 +1,63 @@
+import React from "react";
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+
+import "@testing-library/jest-dom";
+
+import { CLASSPREFIX as eccgui } from "../../configuration/constants";
+
+import Tooltip from "./Tooltip";
+import { Default as TooltipStory } from "./Tooltip.stories";
+
+const checkForPlaceholderClass = (container: HTMLElement, tobe: number) => {
+    expect(container.getElementsByClassName(`${eccgui}-tooltip__wrapper--placeholder`).length).toBe(tobe);
+};
+
+describe("Tooltip", () => {
+    it("should render placeholder automatically for text tooltip", () => {
+        const { container } = render(<Tooltip {...TooltipStory.args} content="this is a simple text tooltip" />);
+        checkForPlaceholderClass(container, 1);
+    });
+    it("should render no placeholder automatically for html tooltip", () => {
+        const { container } = render(
+            <Tooltip {...TooltipStory.args} content={<div>this is a simple text tooltip</div>} />
+        );
+        checkForPlaceholderClass(container, 0);
+    });
+    it("should render placeholder when `usePlaceholder===true`", () => {
+        const { container } = render(
+            <Tooltip {...TooltipStory.args} content={<div>this is a simple text tooltip</div>} usePlaceholder={true} />
+        );
+        checkForPlaceholderClass(container, 1);
+    });
+    it("should render no placeholder when `usePlaceholder===false`", () => {
+        const { container } = render(
+            <Tooltip {...TooltipStory.args} content="this is a simple text tooltip" usePlaceholder={false} />
+        );
+        checkForPlaceholderClass(container, 0);
+    });
+    it("should be displayed on first mouse hover when no placeholder is used", async () => {
+        const { container } = render(<Tooltip {...TooltipStory.args} usePlaceholder={false} />);
+        fireEvent.mouseEnter(container.getElementsByClassName(`${eccgui}-tooltip__wrapper`)[0]);
+        expect(await screen.findByText(TooltipStory.args.content)).toBeVisible();
+    });
+    it("should not be displayed on first mouse hover when placeholder is used but placeholder markup is swapped", async () => {
+        const { container } = render(<Tooltip {...TooltipStory.args} usePlaceholder={true} />);
+        fireEvent.mouseEnter(container.getElementsByClassName(`${eccgui}-tooltip__wrapper--placeholder`)[0]);
+        checkForPlaceholderClass(container, 1);
+        await waitFor(() => {
+            expect(screen.queryAllByText(TooltipStory.args.content)).toHaveLength(0);
+            checkForPlaceholderClass(container, 0);
+        });
+    });
+    it("should be displayed on two continues mouse hover when placeholder is used", async () => {
+        const { container } = render(<Tooltip {...TooltipStory.args} usePlaceholder={true} />);
+        fireEvent.mouseEnter(container.getElementsByClassName(`${eccgui}-tooltip__wrapper`)[0]);
+        checkForPlaceholderClass(container, 1);
+        await waitFor(async () => {
+            expect(screen.queryAllByText(TooltipStory.args.content)).toHaveLength(0);
+            checkForPlaceholderClass(container, 0);
+            fireEvent.mouseOver(container.getElementsByClassName(`${eccgui}-tooltip__wrapper`)[0]);
+            expect(await screen.findByText(TooltipStory.args.content)).toBeVisible();
+        });
+    });
+});

package/src/components/Tooltip/Tooltip.tsx

@@ -19,7 +19,7 @@ export interface TooltipProps extends Omit<BlueprintTooltipProps, "position"> {
     /**
      * The size specifies the dimension the tooltip overlay element can maximal grow.
      */
-    size?: "small" | "medium" | "large";
+    size?: TooltipSize;
     /**
      * The tooltip will be attached to this element when it is hovered.
      */
@@ -50,6 +50,8 @@ export interface TooltipProps extends Omit<BlueprintTooltipProps, "position"> {
     swapPlaceholderDelay?: number;
 }
 
+export type TooltipSize = "small" | "medium" | "large"
+
 export const Tooltip = ({
     children,
     content,
@@ -199,7 +201,10 @@ export const Tooltip = ({
             targetProps={
                 {
                     ...otherTooltipProps.targetProps,
-                    "data-postplaceholder": `id${eventMemory.current}${searchId.current}`,
+                    "data-postplaceholder":
+                        eventMemory.current && searchId.current
+                            ? `id${eventMemory.current}${searchId.current}`
+                            : undefined,
                 } as React.HTMLProps<HTMLElement>
             }
         >

package/src/components/Tooltip/tooltip.scss

@@ -6,8 +6,9 @@ $eccgui-size-typo-tooltip-lineheight: $eccgui-size-typo-caption-lineheight !defa
 $eccgui-size-tooltip-width: 20em !default;
 
 // library vars
-$tooltip-background-color: $eccgui-color-applicationheader-text; // !default;
-$tooltip-text-color: $eccgui-color-applicationheader-background; // !default;
+$tooltip-background-color: #{eccgui-color-var("layout", "grey", "900")};
+$tooltip-text-color: #{eccgui-color-var("identity", "text", "300")};
+
 // $dark-tooltip-background-color: $light-gray3 !default;
 // $dark-tooltip-text-color: $dark-gray5 !default;
 $tooltip-padding-vertical: $eccgui-size-block-whitespace * 0.25; // !default;
@@ -45,7 +46,10 @@ $tooltip-padding-horizontal: $eccgui-size-block-whitespace * 0.5; // !default;
     pre,
     .#{$eccgui}-typography__contentblock pre,
     pre.#{$eccgui}-typography__text {
-        background-color: color.invert($eccgui-color-workspace-background);
+        background-color: eccgui-color-mix(
+            eccgui-color-var("identity", "background", "900") 100% * $eccgui-opacity-ghostly,
+            transparent
+        );
     }
 }
 

package/src/components/Typography/OverflowText.tsx

@@ -1,7 +1,7 @@
 import React from "react";
 
-import { CLASSPREFIX as eccgui } from "../../configuration/constants";
 import { TestableComponent } from "../../components/interfaces";
+import { CLASSPREFIX as eccgui } from "../../configuration/constants";
 
 export interface OverflowTextProps extends React.HTMLAttributes<HTMLElement>, TestableComponent {
     /**
@@ -25,11 +25,6 @@ export interface OverflowTextProps extends React.HTMLAttributes<HTMLElement>, Te
      * HTML element that is used for the component.
      */
     useHtmlElement?: "p" | "div" | "span";
-    /**
-     * Used for all other necessary properties.
-     * @deprecated (v25) we will allow only basic HTML element properties and testing IDs
-     */
-    [key: string]: any;
 }
 
 /** Prevents text from overflowing. */

package/src/components/Typography/typography.scss

@@ -53,7 +53,7 @@ mark {
         styles from other stylesheets we cannot control here
         TODO: need to reevaluated when it is not used together with MDL anymore
     */
-    background-color: rgba($eccgui-color-info-background, 1) !important;
+    background-color: eccgui-color-rgba($eccgui-color-info-background, 1) !important;
 }
 
 // HtmlContentBlock

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;