dify

dify/web/app/components/base/tooltip/TooltipManager.ts

@@ -0,0 +1,27 @@
+class TooltipManager {
+  private activeCloser: (() => void) | null = null
+
+  register(closeFn: () => void) {
+    if (this.activeCloser)
+      this.activeCloser()
+    this.activeCloser = closeFn
+  }
+
+  clear(closeFn: () => void) {
+    if (this.activeCloser === closeFn)
+      this.activeCloser = null
+  }
+
+  /**
+   * Closes the currently active tooltip by calling its closer function
+   * and clearing the reference to it
+   */
+  closeActiveTooltip() {
+    if (this.activeCloser) {
+      this.activeCloser()
+      this.activeCloser = null
+    }
+  }
+}
+
+export const tooltipManager = new TooltipManager()

dify/web/app/components/base/tooltip/content.tsx

@@ -0,0 +1,22 @@
+import type { FC, PropsWithChildren, ReactNode } from 'react'
+
+export type ToolTipContentProps = {
+  title?: ReactNode
+  action?: ReactNode
+} & PropsWithChildren
+
+export const ToolTipContent: FC<ToolTipContentProps> = ({
+  title,
+  action,
+  children,
+}) => {
+  return (
+    <div className='w-[180px]'>
+      {title && (
+        <div className='mb-1.5 font-semibold text-text-secondary'>{title}</div>
+      )}
+      <div className='mb-1.5 text-text-tertiary'>{children}</div>
+      {action && <div className='cursor-pointer text-text-accent'>{action}</div>}
+    </div>
+  )
+}

dify/web/app/components/base/tooltip/index.spec.tsx

@@ -0,0 +1,116 @@
+import React from 'react'
+import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
+import '@testing-library/jest-dom'
+import Tooltip from './index'
+
+afterEach(cleanup)
+
+describe('Tooltip', () => {
+  describe('Rendering', () => {
+    test('should render default tooltip with question icon', () => {
+      const triggerClassName = 'custom-trigger'
+      const { container } = render(<Tooltip popupContent="Tooltip content" triggerClassName={triggerClassName} />)
+      const trigger = container.querySelector(`.${triggerClassName}`)
+      expect(trigger).not.toBeNull()
+      expect(trigger?.querySelector('svg')).not.toBeNull() // question icon
+    })
+
+    test('should render with custom children', () => {
+      const { getByText } = render(
+        <Tooltip popupContent="Tooltip content">
+          <button>Hover me</button>
+        </Tooltip>,
+      )
+      expect(getByText('Hover me').textContent).toBe('Hover me')
+    })
+  })
+
+  describe('Disabled state', () => {
+    test('should not show tooltip when disabled', () => {
+      const triggerClassName = 'custom-trigger'
+      const { container } = render(<Tooltip popupContent="Tooltip content" disabled triggerClassName={triggerClassName} />)
+      const trigger = container.querySelector(`.${triggerClassName}`)
+      act(() => {
+        fireEvent.mouseEnter(trigger!)
+      })
+      expect(screen.queryByText('Tooltip content')).not.toBeInTheDocument()
+    })
+  })
+
+  describe('Trigger methods', () => {
+    test('should open on hover when triggerMethod is hover', () => {
+      const triggerClassName = 'custom-trigger'
+      const { container } = render(<Tooltip popupContent="Tooltip content" triggerClassName={triggerClassName} />)
+      const trigger = container.querySelector(`.${triggerClassName}`)
+      act(() => {
+        fireEvent.mouseEnter(trigger!)
+      })
+      expect(screen.queryByText('Tooltip content')).toBeInTheDocument()
+    })
+
+    test('should close on mouse leave when triggerMethod is hover', () => {
+      const triggerClassName = 'custom-trigger'
+      const { container } = render(<Tooltip popupContent="Tooltip content" triggerClassName={triggerClassName} needsDelay={false} />)
+      const trigger = container.querySelector(`.${triggerClassName}`)
+      act(() => {
+        fireEvent.mouseEnter(trigger!)
+        fireEvent.mouseLeave(trigger!)
+      })
+      expect(screen.queryByText('Tooltip content')).not.toBeInTheDocument()
+    })
+
+    test('should toggle on click when triggerMethod is click', () => {
+      const triggerClassName = 'custom-trigger'
+      const { container } = render(<Tooltip popupContent="Tooltip content" triggerMethod="click" triggerClassName={triggerClassName} />)
+      const trigger = container.querySelector(`.${triggerClassName}`)
+      act(() => {
+        fireEvent.click(trigger!)
+      })
+      expect(screen.queryByText('Tooltip content')).toBeInTheDocument()
+    })
+
+    test('should not close immediately on mouse leave when needsDelay is true', () => {
+      const triggerClassName = 'custom-trigger'
+      const { container } = render(<Tooltip popupContent="Tooltip content" triggerMethod="hover" needsDelay triggerClassName={triggerClassName} />)
+      const trigger = container.querySelector(`.${triggerClassName}`)
+      act(() => {
+        fireEvent.mouseEnter(trigger!)
+        fireEvent.mouseLeave(trigger!)
+      })
+      expect(screen.queryByText('Tooltip content')).toBeInTheDocument()
+    })
+  })
+
+  describe('Styling and positioning', () => {
+    test('should apply custom trigger className', () => {
+      const triggerClassName = 'custom-trigger'
+      const { container } = render(<Tooltip popupContent="Tooltip content" triggerClassName={triggerClassName} />)
+      const trigger = container.querySelector(`.${triggerClassName}`)
+      expect(trigger?.className).toContain('custom-trigger')
+    })
+
+    test('should apply custom popup className', async () => {
+      const triggerClassName = 'custom-trigger'
+      const { container } = render(<Tooltip popupContent="Tooltip content" triggerClassName={triggerClassName} popupClassName="custom-popup" />)
+      const trigger = container.querySelector(`.${triggerClassName}`)
+      act(() => {
+        fireEvent.mouseEnter(trigger!)
+      })
+      expect((await screen.findByText('Tooltip content'))?.className).toContain('custom-popup')
+    })
+
+    test('should apply noDecoration when specified', async () => {
+      const triggerClassName = 'custom-trigger'
+      const { container } = render(<Tooltip
+        popupContent="Tooltip content"
+        triggerClassName={triggerClassName}
+        noDecoration
+      />)
+      const trigger = container.querySelector(`.${triggerClassName}`)
+      act(() => {
+        fireEvent.mouseEnter(trigger!)
+      })
+      expect((await screen.findByText('Tooltip content'))?.className).not.toContain('bg-components-panel-bg')
+    })
+  })
+})

dify/web/app/components/base/tooltip/index.stories.tsx

@@ -0,0 +1,60 @@
+import type { Meta, StoryObj } from '@storybook/nextjs'
+import Tooltip from '.'
+
+const TooltipGrid = () => {
+  return (
+    <div className="flex w-full max-w-xl flex-col gap-6 rounded-2xl border border-divider-subtle bg-components-panel-bg p-6">
+      <div className="text-xs uppercase tracking-[0.18em] text-text-tertiary">Hover tooltips</div>
+      <div className="flex flex-wrap gap-4">
+        <Tooltip popupContent="Helpful hint explaining the setting.">
+          <button
+            type="button"
+            className="rounded-md border border-divider-subtle bg-background-default px-3 py-1 text-xs font-medium text-text-secondary hover:bg-state-base-hover"
+          >
+            Hover me
+          </button>
+        </Tooltip>
+        <Tooltip popupContent="Placement can vary." position="right">
+          <span className="rounded-md bg-background-default px-3 py-1 text-xs text-text-secondary">
+            Right tooltip
+          </span>
+        </Tooltip>
+      </div>
+      <div className="text-xs uppercase tracking-[0.18em] text-text-tertiary">Click tooltips</div>
+      <div className="flex flex-wrap gap-4">
+        <Tooltip popupContent="Click again to close." triggerMethod="click" position="bottom-start">
+          <button
+            type="button"
+            className="rounded-md border border-divider-subtle bg-background-default px-3 py-1 text-xs font-medium text-text-secondary hover:bg-state-base-hover"
+          >
+            Click trigger
+          </button>
+        </Tooltip>
+        <Tooltip popupContent="Decoration disabled" triggerMethod="click" noDecoration>
+          <span className="rounded-md border border-dashed border-divider-regular px-3 py-1 text-xs text-text-secondary">
+            Plain content
+          </span>
+        </Tooltip>
+      </div>
+    </div>
+  )
+}
+
+const meta = {
+  title: 'Base/Feedback/Tooltip',
+  component: TooltipGrid,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: 'Portal-based tooltip component supporting hover and click triggers, custom placements, and decorated content.',
+      },
+    },
+  },
+  tags: ['autodocs'],
+} satisfies Meta<typeof TooltipGrid>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Playground: Story = {}

dify/web/app/components/base/tooltip/index.tsx

@@ -0,0 +1,126 @@
+'use client'
+import type { FC } from 'react'
+import React, { useEffect, useRef, useState } from 'react'
+import { useBoolean } from 'ahooks'
+import type { OffsetOptions, Placement } from '@floating-ui/react'
+import { RiQuestionLine } from '@remixicon/react'
+import cn from '@/utils/classnames'
+import { PortalToFollowElem, PortalToFollowElemContent, PortalToFollowElemTrigger } from '@/app/components/base/portal-to-follow-elem'
+import { tooltipManager } from './TooltipManager'
+
+export type TooltipProps = {
+  position?: Placement
+  triggerMethod?: 'hover' | 'click'
+  triggerClassName?: string
+  triggerTestId?: string
+  disabled?: boolean
+  popupContent?: React.ReactNode
+  children?: React.ReactNode
+  popupClassName?: string
+  portalContentClassName?: string
+  noDecoration?: boolean
+  offset?: OffsetOptions
+  needsDelay?: boolean
+  asChild?: boolean
+}
+
+const Tooltip: FC<TooltipProps> = ({
+  position = 'top',
+  triggerMethod = 'hover',
+  triggerClassName,
+  triggerTestId,
+  disabled = false,
+  popupContent,
+  children,
+  popupClassName,
+  portalContentClassName,
+  noDecoration,
+  offset,
+  asChild = true,
+  needsDelay = true,
+}) => {
+  const [open, setOpen] = useState(false)
+  const [isHoverPopup, {
+    setTrue: setHoverPopup,
+    setFalse: setNotHoverPopup,
+  }] = useBoolean(false)
+
+  const isHoverPopupRef = useRef(isHoverPopup)
+  useEffect(() => {
+    isHoverPopupRef.current = isHoverPopup
+  }, [isHoverPopup])
+
+  const [isHoverTrigger, {
+    setTrue: setHoverTrigger,
+    setFalse: setNotHoverTrigger,
+  }] = useBoolean(false)
+
+  const isHoverTriggerRef = useRef(isHoverTrigger)
+  useEffect(() => {
+    isHoverTriggerRef.current = isHoverTrigger
+  }, [isHoverTrigger])
+
+  const close = () => setOpen(false)
+
+  const handleLeave = (isTrigger: boolean) => {
+    if (isTrigger)
+      setNotHoverTrigger()
+    else
+      setNotHoverPopup()
+
+    // give time to move to the popup
+    if (needsDelay) {
+      setTimeout(() => {
+        if (!isHoverPopupRef.current && !isHoverTriggerRef.current) {
+          setOpen(false)
+          tooltipManager.clear(close)
+        }
+      }, 300)
+    }
+    else {
+      setOpen(false)
+      tooltipManager.clear(close)
+    }
+  }
+
+  return (
+    <PortalToFollowElem
+      open={disabled ? false : open}
+      onOpenChange={setOpen}
+      placement={position}
+      offset={offset ?? 8}
+    >
+      <PortalToFollowElemTrigger
+        onClick={() => triggerMethod === 'click' && setOpen(v => !v)}
+        onMouseEnter={() => {
+          if (triggerMethod === 'hover') {
+            setHoverTrigger()
+            tooltipManager.register(close)
+            setOpen(true)
+          }
+        }}
+        onMouseLeave={() => triggerMethod === 'hover' && handleLeave(true)}
+        asChild={asChild}
+        className={!asChild ? triggerClassName : ''}
+      >
+        {children || <div data-testid={triggerTestId} className={triggerClassName || 'h-3.5 w-3.5 shrink-0 p-[1px]'}><RiQuestionLine className='h-full w-full text-text-quaternary hover:text-text-tertiary' /></div>}
+      </PortalToFollowElemTrigger>
+      <PortalToFollowElemContent
+        className={cn('z-[9999]', portalContentClassName || '')}
+      >
+        {popupContent && (<div
+          className={cn(
+            !noDecoration && 'system-xs-regular relative max-w-[300px] break-words rounded-md bg-components-panel-bg px-3 py-2 text-left text-text-tertiary shadow-lg',
+            popupClassName,
+          )}
+          onMouseEnter={() => triggerMethod === 'hover' && setHoverPopup()}
+          onMouseLeave={() => triggerMethod === 'hover' && handleLeave(false)}
+        >
+          {popupContent}
+        </div>)}
+      </PortalToFollowElemContent>
+    </PortalToFollowElem>
+  )
+}
+
+export default React.memo(Tooltip)