@vention/machine-ui 3.27.0

package/src/lib/components/vention-modal-base/vention-modal-base.test.tsx

@@ -0,0 +1,117 @@
+import { fireEvent, screen } from "@testing-library/react"
+import { renderWithTheme } from "../../testing/utils"
+import { VentionModalBase, ventionModalBaseTestIds } from "./vention-modal-base"
+
+function emptyFunction() {
+  return
+}
+
+describe("VentionModalBase", () => {
+  it("renders without crashing", () => {
+    renderWithTheme(
+      <VentionModalBase isOpen={true} onClose={emptyFunction}>
+        <div>Test Content</div>
+      </VentionModalBase>
+    )
+    expect(screen.getByText("Test Content")).toBeInTheDocument()
+  })
+
+  it("doesn't display modal unless opened", () => {
+    const { queryByTestId } = renderWithTheme(
+      <VentionModalBase isOpen={false} onClose={emptyFunction}>
+        <div>Test Content</div>
+      </VentionModalBase>
+    )
+    expect(queryByTestId(ventionModalBaseTestIds.modalContainer)).not.toBeInTheDocument()
+  })
+
+  it("handles close button click", () => {
+    const handleClose = jest.fn()
+    const { getByTestId } = renderWithTheme(
+      <VentionModalBase isOpen={true} onClose={handleClose} isTouchDevice>
+        <div>Test Content</div>
+      </VentionModalBase>
+    )
+    fireEvent.click(getByTestId(ventionModalBaseTestIds.closeIcon))
+    expect(handleClose).toHaveBeenCalled()
+  })
+
+  it("applies correct width based on modalSize - small", () => {
+    const { getByTestId } = renderWithTheme(
+      <VentionModalBase isOpen={true} onClose={emptyFunction} modalSize="small">
+        <div>Test Content</div>
+      </VentionModalBase>
+    )
+    const modalContainer = getByTestId(ventionModalBaseTestIds.modalContainer)
+    expect(modalContainer).toHaveStyle(`width: 320px`)
+  })
+
+  it("applies correct width based on modalSize - large", () => {
+    const { getByTestId } = renderWithTheme(
+      <VentionModalBase isOpen={true} onClose={emptyFunction} modalSize="large">
+        <div>Test Content</div>
+      </VentionModalBase>
+    )
+    const modalContainer = getByTestId(ventionModalBaseTestIds.modalContainer)
+    expect(modalContainer).toHaveStyle(`width: 480px`)
+  })
+
+  it("renders dynamic modal size correctly", () => {
+    const { getByTestId } = renderWithTheme(
+      <VentionModalBase isOpen={true} onClose={emptyFunction} modalSize="dynamic" backDropClickClosable={false}>
+        <div>Dynamic Content</div>
+      </VentionModalBase>
+    )
+    const modalContainer = getByTestId(ventionModalBaseTestIds.modalContainer)
+    expect(modalContainer).toHaveStyle(`width: fit-content`)
+  })
+
+  it("renders custom with modal size correctly", () => {
+    const { getByTestId } = renderWithTheme(
+      <VentionModalBase isOpen={true} onClose={emptyFunction} modalSize="small" width="1000px" backDropClickClosable={false}>
+        <div>Dynamic Content</div>
+      </VentionModalBase>
+    )
+    const modalContainer = getByTestId(ventionModalBaseTestIds.modalContainer)
+    expect(modalContainer).toHaveStyle(`width: 1000px`)
+  })
+
+  it("should NOT close when clicking outside if backDropClickClosable is false", () => {
+    // eslint-disable-next-line eslint-rules/handle-functions-naming
+    const onCloseMock = jest.fn()
+
+    renderWithTheme(
+      <VentionModalBase isOpen={true} onClose={onCloseMock} modalSize="dynamic" backDropClickClosable={false}>
+        <div>Dynamic Content</div>
+      </VentionModalBase>
+    )
+
+    // Get the modal and the backdrop
+    const modalContainer = screen.getByTestId(ventionModalBaseTestIds.modalContainer)
+    const backdrop = screen.getByTestId(ventionModalBaseTestIds.backdrop)
+    fireEvent.click(backdrop)
+
+    // Assert the modal is still in the document
+    expect(modalContainer).toBeInTheDocument()
+
+    // Ensure onClose was NOT called
+    expect(onCloseMock).not.toHaveBeenCalled()
+  })
+
+  it("should close when clicking outside if backDropClickClosable is true", () => {
+    // eslint-disable-next-line eslint-rules/handle-functions-naming
+    const onCloseMock = jest.fn()
+
+    renderWithTheme(
+      <VentionModalBase isOpen={true} onClose={onCloseMock} modalSize="dynamic" backDropClickClosable={true}>
+        <div>Dynamic Content</div>
+      </VentionModalBase>
+    )
+
+    const backdrop = screen.getByTestId(ventionModalBaseTestIds.backdrop)
+    fireEvent.click(backdrop)
+
+    // Ensure onClose was NOT called
+    expect(onCloseMock).toHaveBeenCalled()
+  })
+})

package/src/lib/components/vention-modal-base/vention-modal-base.tsx

@@ -0,0 +1,149 @@
+import { Modal } from "@mui/material"
+import { IconX } from "@tabler/icons-react"
+import { forwardRef } from "react"
+import { tss } from "tss-react/mui"
+import { Sizes, StrictExtract, machineUiTheme } from "../../theme/machine-ui-theme"
+
+export type ModalSize = StrictExtract<Sizes, "small" | "medium" | "large" | "x-large" | "xx-large" | "dynamic">
+
+export interface VentionModalBaseProps {
+  modalSize?: ModalSize
+  isOpen: boolean
+  onClose: () => void
+  children: React.ReactNode
+  isTouchDevice?: boolean
+  backDropClickClosable?: boolean
+
+  /**
+   * The custom width will override the modals' default from the {@link modalSize}.
+   * If nothing is provided, {@link modalSize} will drive the width.
+   */
+  width?: `${number}px`
+}
+
+export const VentionModalBase = (props: VentionModalBaseProps) => {
+  const { modalSize = "medium", isTouchDevice = false, backDropClickClosable = true, width } = props
+  const { classes, cx } = useStyles({ modalSize, isTouchDevice, width })
+
+  const handleClose = (event: React.SyntheticEvent, reason: string) => {
+    if (!backDropClickClosable && reason === "backdropClick") {
+      return
+    }
+    props.onClose()
+  }
+
+  const Backdrop = forwardRef<HTMLDivElement, { open?: boolean; className: string; ownerState?: unknown }>((props, ref) => {
+    const { open, className, ownerState, ...other } = props
+
+    return (
+      <div
+        className={cx(classes.backdrop, { "base-Backdrop-open": open }, className)}
+        ref={ref}
+        {...other}
+        data-testid={ventionModalBaseTestIds.backdrop}
+      />
+    )
+  })
+
+  const iconSize = isTouchDevice ? machineUiTheme.spacing(7) : machineUiTheme.spacing(4)
+
+  return (
+    <Modal open={props.isOpen} onClose={handleClose} slots={{ backdrop: Backdrop }} className={classes.modal}>
+      <div className={classes.modalContainer} data-testid={ventionModalBaseTestIds.modalContainer}>
+        <div className={classes.closeIconButton} onClick={props.onClose} data-testid={ventionModalBaseTestIds.closeIcon}>
+          <IconX stroke={1} size={iconSize} />
+        </div>
+        {props.children}
+      </div>
+    </Modal>
+  )
+}
+
+type ModalStyle = {
+  width: string
+}
+
+const getModalStyle = (modalSize: ModalSize, width?: `${number}px`): ModalStyle => {
+  if (width !== undefined) {
+    return { width }
+  }
+
+  const modalStyles: Record<ModalSize, ModalStyle> = {
+    small: {
+      width: "320px",
+    },
+    medium: {
+      width: "400px",
+    },
+    large: {
+      width: "480px",
+    },
+    "x-large": {
+      width: "600px",
+    },
+    "xx-large": {
+      width: "800px",
+    },
+    dynamic: {
+      width: "fit-content",
+    },
+  }
+
+  return modalStyles[modalSize]
+}
+
+const useStyles = tss
+  .withParams<Pick<VentionModalBaseProps, "modalSize" | "isTouchDevice" | "width">>()
+  .create(({ modalSize, isTouchDevice, width, theme }) => {
+    const modalStyle = getModalStyle(modalSize, width)
+
+    return {
+      modal: {
+        position: "fixed",
+        zIndex: theme.zIndex.modal,
+        inset: 0,
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+        outline: "none",
+      },
+      modalContainer: {
+        position: "relative",
+        display: "flex",
+        flexDirection: "column",
+        width: modalStyle.width,
+        backgroundColor: theme.palette.background.paper,
+        padding: isTouchDevice ? theme.spacing(9, 8, 8, 8) : theme.spacing(8, 7, 7, 7),
+        borderRadius: 8,
+        boxShadow: "0px 25px 50px -12px rgba(2, 6, 23, 0.18)",
+        outline: "none",
+      },
+      backdrop: {
+        zIndex: -1,
+        position: "fixed",
+        inset: 0,
+        backgroundColor: "rgb(0 0 0 / 0.5)",
+      },
+      closeIconButton: {
+        position: "absolute",
+        top: 0,
+        right: 0,
+        height: isTouchDevice ? theme.spacing(11) : theme.spacing(9),
+        width: isTouchDevice ? theme.spacing(11) : theme.spacing(9),
+        cursor: "pointer",
+        display: "flex",
+        justifyContent: "center",
+        alignItems: "center",
+        color: theme.palette.icon.secondary,
+        "&:hover": {
+          color: theme.palette.icon.tertiaryHover,
+        },
+      },
+    }
+  })
+
+export const ventionModalBaseTestIds = {
+  closeIcon: "vention-modal-close-icon",
+  modalContainer: "vention-modal-container",
+  backdrop: "vention-modal-backdrop",
+}

package/src/lib/components/vention-popover/vention-popover.stories.tsx

@@ -0,0 +1,30 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import React from "react"
+
+import { VentionPopover, VentionPopoverProps } from "./vention-popover"
+
+const meta: Meta<typeof VentionPopover> = {
+  component: VentionPopover,
+  title: "Components/VentionPopover",
+}
+
+export default meta
+type Story = StoryObj<typeof VentionPopover>
+
+const Template = (args: VentionPopoverProps) => {
+  return (
+    <div style={{ height: 400 }}>
+      <VentionPopover {...args}></VentionPopover>
+    </div>
+  )
+}
+
+export const Default: Story = Template.bind({})
+Default.args = {
+  image: "https://placehold.co/300x180.png",
+  title: "Popover heading",
+  visible: true,
+  arrowPosition: "bottom",
+  description:
+    "Because a popover disappears after the user interacts with it, limit the amount of functionality in the popover to a few related tasks.",
+}

package/src/lib/components/vention-popover/vention-popover.test.tsx

@@ -0,0 +1,148 @@
+import "@testing-library/jest-dom"
+
+import { renderWithTheme } from "../../testing/utils"
+import { VentionPopover, VentionPopoverProps, ventionPopoverArrowSize } from "./vention-popover"
+
+describe("<VentionPopover />", () => {
+  it("should render correctly", () => {
+    const text = "Popover heading"
+    const { getByText } = renderWithTheme(<VentionPopover title={text} arrowPosition="bottom" visible={true} />)
+    expect(getByText(text)).toBeInTheDocument()
+  })
+
+  it("should show description", () => {
+    const description = "Popover description"
+    const { getByText } = renderWithTheme(
+      <VentionPopover title="Popover heading" description={description} arrowPosition="bottom" visible={true} />
+    )
+    expect(getByText(description)).toBeInTheDocument()
+  })
+
+  it("should show title icon", () => {
+    const titleIcon = "icon.png"
+    const { getByAltText } = renderWithTheme(
+      <VentionPopover title="Popover heading" titleIcon={titleIcon} arrowPosition="bottom" visible={true} />
+    )
+    const icon = getByAltText("icon")
+    expect(icon).toBeInTheDocument()
+    expect(icon).toHaveAttribute("src", titleIcon)
+  })
+
+  it("should display the image with the correct src and title", () => {
+    const props: VentionPopoverProps = {
+      image: "test-image.jpg",
+      title: "Test Title",
+      arrowPosition: "bottom",
+      visible: true,
+    }
+
+    const { getByRole } = renderWithTheme(<VentionPopover {...props} />)
+
+    const image = getByRole("img")
+    expect(image).toBeInTheDocument()
+    expect(image).toHaveAttribute("style", `background-image: url(${props.image});`)
+    expect(image).toHaveAttribute("title", props.title)
+  })
+
+  it("should be positioned at correct location", () => {
+    const pos2D = { left: 200, top: 350 }
+    const { getByTestId } = renderWithTheme(<VentionPopover title="Popover heading" pos2D={pos2D} arrowPosition="bottom" visible={true} />)
+    const popover = getByTestId("popover")
+    expect(popover).toHaveStyle(`top: ${pos2D.top - ventionPopoverArrowSize}px`)
+    expect(popover).toHaveStyle(`left: ${pos2D.left}px`)
+  })
+
+  it("should be visible", () => {
+    const { getByTestId } = renderWithTheme(<VentionPopover title="Popover heading" visible={true} arrowPosition="bottom" />)
+    const popover = getByTestId("popover")
+    expect(popover).toHaveStyle("visibility: visible")
+  })
+
+  it("should be NOT visible", () => {
+    const { getByTestId } = renderWithTheme(<VentionPopover title="Popover heading" visible={false} arrowPosition="bottom" />)
+    const popover = getByTestId("popover")
+    expect(popover).toHaveStyle("visibility: hidden")
+  })
+
+  it("Should have some buttons", () => {
+    const buttons: VentionPopoverProps["buttons"] = [
+      {
+        labelText: "Button1",
+        variant: "shaded",
+      },
+      {
+        labelText: "Button2",
+        variant: "outline",
+      },
+      {
+        labelText: "Button3",
+        variant: "filled",
+      },
+    ]
+    const { getByText } = renderWithTheme(
+      <VentionPopover title="Popover heading" buttons={buttons} arrowPosition="bottom" visible={true} />
+    )
+    buttons.forEach(button => {
+      expect(getByText(button.labelText)).toBeInTheDocument()
+    })
+  })
+
+  it("Should be positioned based on an anchor element", () => {
+    const anchorElement = document.createElement("div")
+    document.body.appendChild(anchorElement)
+
+    // Mock getBoundingClientRect to return expected dimensions and position
+    const top = 500
+    const left = 300
+    const height = 10
+    const width = 40
+    anchorElement.getBoundingClientRect = jest.fn(() => ({
+      top,
+      left,
+      width,
+      height,
+      right: 500,
+      bottom: 600,
+      // need to disable these to avoid ESLint errors for mocking
+      // eslint-disable-next-line id-length
+      x: 300,
+      // eslint-disable-next-line id-length
+      y: 500,
+      // eslint-disable-next-line @typescript-eslint/no-empty-function
+      toJSON: () => {},
+    }))
+
+    const { getByTestId } = renderWithTheme(
+      <VentionPopover title="Popover heading" anchorElement={anchorElement} arrowPosition="bottom" visible={true} />
+    )
+    const popover = getByTestId("popover")
+    expect(popover).toHaveStyle(`top: ${top - height / 2 - ventionPopoverArrowSize}px`)
+    expect(popover).toHaveStyle(`left: ${left + width / 2}px`)
+  })
+
+  const positions = [
+    { arrowPos: "top", pos2D: { left: 200, top: 0 } },
+    { arrowPos: "bottom", pos2D: { left: 200, top: 350 } },
+    { arrowPos: "left", pos2D: { left: 0, top: 200 } },
+    { arrowPos: "right", pos2D: { left: 350, top: 2200 } },
+  ]
+
+  test.each(positions)(
+    "should have arrow pointing to the $arrowPos with position at (left: $pos2D.left, top: $pos2D.top)",
+    ({ arrowPos, pos2D }: { arrowPos: VentionPopoverProps["arrowPosition"]; pos2D: { left: number; top: number } }) => {
+      const { getByTestId } = renderWithTheme(
+        <VentionPopover title="Popover heading" arrowPosition={arrowPos} visible={true} pos2D={pos2D} />
+      )
+      const popover = getByTestId("popover")
+      const arrow = getByTestId("popoverArrow")
+
+      if (arrowPos === "top" || arrowPos === "bottom") {
+        expect(popover).toHaveStyle(`top: ${pos2D.top + ventionPopoverArrowSize * (arrowPos === "top" ? 1 : -1)}px`)
+      }
+      if (arrowPos === "left" || arrowPos === "right") {
+        expect(popover).toHaveStyle(`left: ${pos2D.left + ventionPopoverArrowSize * (arrowPos === "left" ? 1 : -1)}px`)
+      }
+      expect(arrow).toHaveClass(arrowPos)
+    }
+  )
+})

package/src/lib/components/vention-popover/vention-popover.tsx

@@ -0,0 +1,211 @@
+import { Box, Card, CardContent, CardMedia, Stack, Typography } from "@mui/material"
+import { useCallback, useEffect, useRef, useState } from "react"
+import { tss } from "tss-react/mui"
+
+import { VentionButton } from "../vention-button/vention-button"
+import { VentionButtonProps } from "../vention-button/button-utils"
+
+export interface VentionPopoverProps {
+  /** Supporting image for the popover */
+  image?: string
+  /** Title icon placed to the left of the title */
+  titleIcon?: string
+  /** Header title text */
+  title?: string
+  /** Description of the popover */
+  description?: string
+  /** The element to anchor the popover to */
+  anchorElement?: HTMLElement | null
+  /** Absolute position of the popover from 'top' and 'left' */
+  pos2D?: { top: number; left: number } | null
+  /** Visibility of the popover */
+  visible: boolean
+  /** Three possible buttons which automatically fill the width of their container */
+  buttons?: [VentionButtonProps?, VentionButtonProps?, VentionButtonProps?]
+  /** Arrow position of the popover */
+  arrowPosition: "top" | "bottom" | "left" | "right"
+}
+export const ventionPopoverArrowSize = 10
+
+export const VentionPopover = (props: VentionPopoverProps) => {
+  const { classes } = useStyles()
+  const popoverRef = useRef<HTMLElement | null>(null)
+  const { title, description, anchorElement, pos2D, titleIcon, visible, image } = props
+  const [position, setPosition] = useState({ top: 0, left: 0 })
+
+  /**
+   * Depending on the arrow position, calculate the position of the popover
+   * @param top The top position of the popover
+   * @param left The left position of the popover
+   * @param popoverRef The reference to the popover element
+   * @returns The position of the popover adjusted for the arrow
+   */
+  const calculatePositionFromArrow = useCallback(
+    (top: number, left: number, popoverRef: HTMLElement) => {
+      const popoverRect = popoverRef.getBoundingClientRect()
+      const arrowSize = ventionPopoverArrowSize
+      switch (props.arrowPosition) {
+        case "top":
+          return { top: top + popoverRect.height / 2 + arrowSize, left }
+        case "bottom":
+          return { top: top - popoverRect.height / 2 - arrowSize, left }
+        case "left":
+          return { top, left: left + popoverRect.width / 2 + arrowSize }
+        case "right":
+          return { top, left: left - popoverRect.width / 2 - arrowSize }
+      }
+    },
+    [props.arrowPosition]
+  )
+
+  /**
+   * Determine the position of the popover to be center aligned with the target
+   * @param top Position of the target from the top
+   * @param left Position of the target from the left
+   * @param popoverRef The reference to the popover element
+   * @returns The position of the popover to be center aligned with the target
+   */
+  const getCenterPosition = (top: number, left: number, popoverRef: HTMLElement) => {
+    const popoverRect = popoverRef.getBoundingClientRect()
+
+    return {
+      top: top - popoverRect.height / 2,
+      left: left - popoverRect.width / 2,
+    }
+  }
+
+  useEffect(() => {
+    if (popoverRef.current && anchorElement) {
+      const anchorRect = anchorElement.getBoundingClientRect()
+      const centerPosition = getCenterPosition(
+        anchorRect.top - anchorRect.height / 2,
+        anchorRect.left + anchorRect.width / 2,
+        popoverRef.current
+      )
+      setPosition(calculatePositionFromArrow(centerPosition.top, centerPosition.left, popoverRef.current))
+    }
+  }, [anchorElement, calculatePositionFromArrow])
+
+  useEffect(() => {
+    if (pos2D) {
+      const centerPosition = getCenterPosition(pos2D.top, pos2D.left, popoverRef.current)
+      setPosition(calculatePositionFromArrow(centerPosition.top, centerPosition.left, popoverRef.current))
+    }
+  }, [pos2D, calculatePositionFromArrow])
+
+  return (
+    <Box
+      data-testid="popover"
+      ref={popoverRef}
+      className={classes.box}
+      style={{ top: position.top, left: position.left, visibility: visible ? "visible" : "hidden" }}
+    >
+      <Card className={classes.card}>
+        {image && <CardMedia className={classes.media} image={image} title={props.title} />}
+        <CardContent className={classes.cardContent}>
+          <Box display="grid" gap={2} gridTemplateColumns="auto 1fr">
+            {titleIcon && <img src={titleIcon} alt="icon" />}
+            {title && (
+              <Typography variant="heading16SemiBold" component="div">
+                {title}
+              </Typography>
+            )}
+          </Box>
+          {description && (
+            <Typography variant="uiText14Regular" className={classes.description}>
+              {description}
+            </Typography>
+          )}
+          {props.buttons && (
+            <Stack direction="row" justifyContent="flex-end" spacing={2}>
+              {props.buttons.map((buttonProps, index) => (
+                <VentionButton key={`popover_button_${index}`} {...buttonProps} className={classes.button} />
+              ))}
+            </Stack>
+          )}
+        </CardContent>
+      </Card>
+      <div data-testid="popoverArrow" className={`${classes.popoverArrow} ${props.arrowPosition}`} />
+    </Box>
+  )
+}
+
+/**
+ * Get the styles for the arrow of the popover depending on the position provided
+ * @param arrowPos Position of the arrow
+ * @returns The styles for the arrow of the popover
+ */
+const getArrowStyles = (arrowPos: VentionPopoverProps["arrowPosition"]) => {
+  const sizeInPx = `${ventionPopoverArrowSize}px`
+
+  const getBorderWidth = () =>
+    `${arrowPos === "top" ? 0 : sizeInPx}
+     ${arrowPos === "right" ? 0 : sizeInPx}
+     ${arrowPos === "bottom" ? 0 : sizeInPx}
+     ${arrowPos === "left" ? 0 : sizeInPx}`
+
+  const getBorderColor = () =>
+    `${arrowPos === "bottom" ? "white" : "transparent"}
+     ${arrowPos === "left" ? "white" : "transparent"}
+     ${arrowPos === "top" ? "white" : "transparent"}
+     ${arrowPos === "right" ? "white" : "transparent"}`
+
+  const getMainPosition = () => {
+    return {
+      top: { left: "50%", bottom: "100%", transform: "translateX(-50%)" },
+      bottom: { left: "50%", top: "100%", transform: "translateX(-50%)" },
+      left: { right: "100%", top: "50%", transform: "translateY(-50%)" },
+      right: { left: "100%", top: "50%", transform: "translateY(-50%)" },
+    }[arrowPos]
+  }
+
+  return {
+    ...getMainPosition(),
+    borderWidth: getBorderWidth(),
+    borderColor: getBorderColor(),
+  }
+}
+
+const useStyles = tss.create(({ theme }) => {
+  return {
+    box: {
+      display: "inline-block",
+      position: "absolute",
+      zIndex: 10,
+      minWidth: 280,
+      maxWidth: 300,
+    },
+    card: {
+      padding: theme.spacing(4),
+      margin: 0,
+      boxShadow: "0px 10px 15px 0px rgba(0,0,0,0.1)",
+    },
+    cardContent: {
+      padding: 0,
+      "&:last-child": {
+        paddingBottom: 0,
+      },
+    },
+    media: {
+      height: 140,
+      marginBottom: theme.spacing(4),
+    },
+    description: {
+      paddingTop: theme.spacing(2),
+      paddingBottom: 0,
+    },
+    button: {
+      width: "100%",
+    },
+    popoverArrow: {
+      position: "absolute",
+      width: 0,
+      height: 0,
+      borderStyle: "solid",
+      "&.top": getArrowStyles("top"),
+      "&.bottom": getArrowStyles("bottom"),
+      "&.left": getArrowStyles("left"),
+      "&.right": getArrowStyles("right"),
+    },
+  }
+})