feat(web): overlay migration guardrails + Base UI primitives (#32824)

Signed-off-by: yyh <yuanyouhuilyz@gmail.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

web/app/components/base/modal/index.tsx

@@ -1,3 +1,8 @@
+/**
+ * @deprecated Use `@/app/components/base/ui/dialog` instead.
+ * This component will be removed after migration is complete.
+ * See: https://github.com/langgenius/dify/issues/32767
+ */
 import { Dialog, DialogPanel, DialogTitle, Transition, TransitionChild } from '@headlessui/react'
 import { noop } from 'es-toolkit/function'
 import { Fragment } from 'react'

web/app/components/base/modal/modal.tsx

@@ -1,3 +1,8 @@
+/**
+ * @deprecated Use `@/app/components/base/ui/dialog` instead.
+ * This component will be removed after migration is complete.
+ * See: https://github.com/langgenius/dify/issues/32767
+ */
 import type { ButtonProps } from '@/app/components/base/button'
 import { noop } from 'es-toolkit/function'
 import { memo } from 'react'

web/app/components/base/portal-to-follow-elem/index.tsx

@@ -1,4 +1,16 @@
 'use client'
+/**
+ * @deprecated Use semantic overlay primitives from `@/app/components/base/ui/` instead.
+ * This component will be removed after migration is complete.
+ * See: https://github.com/langgenius/dify/issues/32767
+ *
+ * Migration guide:
+ * - Tooltip → `@/app/components/base/ui/tooltip`
+ * - Menu/Dropdown → `@/app/components/base/ui/dropdown-menu`
+ * - Popover → `@/app/components/base/ui/popover`
+ * - Dialog/Modal → `@/app/components/base/ui/dialog`
+ * - Select → `@/app/components/base/ui/select`
+ */
 import type { OffsetOptions, Placement } from '@floating-ui/react'
 import {
   autoUpdate,
@@ -33,6 +45,7 @@ export type PortalToFollowElemOptions = {
   triggerPopupSameWidth?: boolean
 }
 
+/** @deprecated Use semantic overlay primitives instead. See #32767. */
 export function usePortalToFollowElem({
   placement = 'bottom',
   open: controlledOpen,
@@ -110,6 +123,7 @@ export function usePortalToFollowElemContext() {
   return context
 }
 
+/** @deprecated Use semantic overlay primitives instead. See #32767. */
 export function PortalToFollowElem({
   children,
   ...options
@@ -124,6 +138,7 @@ export function PortalToFollowElem({
   )
 }
 
+/** @deprecated Use semantic overlay primitives instead. See #32767. */
 export const PortalToFollowElemTrigger = (
   {
     ref: propRef,
@@ -164,6 +179,7 @@ export const PortalToFollowElemTrigger = (
 }
 PortalToFollowElemTrigger.displayName = 'PortalToFollowElemTrigger'
 
+/** @deprecated Use semantic overlay primitives instead. See #32767. */
 export const PortalToFollowElemContent = (
   {
     ref: propRef,

web/app/components/base/select/index.tsx

@@ -1,4 +1,9 @@
 'use client'
+/**
+ * @deprecated Use `@/app/components/base/ui/select` instead.
+ * This component will be removed after migration is complete.
+ * See: https://github.com/langgenius/dify/issues/32767
+ */
 import type { FC } from 'react'
 import { Combobox, ComboboxButton, ComboboxInput, ComboboxOption, ComboboxOptions, Listbox, ListboxButton, ListboxOption, ListboxOptions } from '@headlessui/react'
 import { ChevronDownIcon, ChevronUpIcon, XMarkIcon } from '@heroicons/react/20/solid'
@@ -236,7 +241,7 @@ const SimpleSelect: FC<ISelectProps> = ({
               }}
               className={cn(`flex h-full w-full items-center rounded-lg border-0 bg-components-input-bg-normal pl-3 pr-10 focus-visible:bg-state-base-hover-alt focus-visible:outline-none group-hover/simple-select:bg-state-base-hover-alt sm:text-sm sm:leading-6 ${disabled ? 'cursor-not-allowed' : 'cursor-pointer'}`, className)}
             >
-              <span className={cn('system-sm-regular block truncate text-left text-components-input-text-filled', !selectedItem?.name && 'text-components-input-text-placeholder')}>{selectedItem?.name ?? localPlaceholder}</span>
+              <span className={cn('block truncate text-left text-components-input-text-filled system-sm-regular', !selectedItem?.name && 'text-components-input-text-placeholder')}>{selectedItem?.name ?? localPlaceholder}</span>
               <span className="absolute inset-y-0 right-0 flex items-center pr-2">
                 {isLoading
                   ? <RiLoader4Line className="h-3.5 w-3.5 animate-spin text-text-secondary" />

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

@@ -1,4 +1,9 @@
 'use client'
+/**
+ * @deprecated Use `@/app/components/base/ui/tooltip` instead.
+ * This component will be removed after migration is complete.
+ * See: https://github.com/langgenius/dify/issues/32767
+ */
 import type { OffsetOptions, Placement } from '@floating-ui/react'
 import type { FC } from 'react'
 import { RiQuestionLine } from '@remixicon/react'
@@ -130,7 +135,7 @@ const Tooltip: FC<TooltipProps> = ({
         {!!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',
+              !noDecoration && 'relative max-w-[300px] break-words rounded-md bg-components-panel-bg px-3 py-2 text-left text-text-tertiary shadow-lg system-xs-regular',
               popupClassName,
             )}
             onMouseEnter={() => {

web/app/components/base/ui/dialog/index.tsx

@@ -0,0 +1,58 @@
+'use client'
+
+// z-index strategy (relies on root `isolation: isolate` in layout.tsx):
+//   All overlay primitives (Tooltip / Popover / Dropdown / Select / Dialog) — z-50
+//   Overlays share the same z-index; DOM order handles stacking when multiple are open.
+//   This ensures overlays inside a Dialog (e.g. a Tooltip on a dialog button) render
+//   above the dialog backdrop instead of being clipped by it.
+//   Toast — z-[99], always on top (defined in toast component)
+
+import { Dialog as BaseDialog } from '@base-ui/react/dialog'
+import * as React from 'react'
+import { cn } from '@/utils/classnames'
+
+export const Dialog = BaseDialog.Root
+export const DialogTrigger = BaseDialog.Trigger
+export const DialogTitle = BaseDialog.Title
+export const DialogDescription = BaseDialog.Description
+export const DialogClose = BaseDialog.Close
+
+type DialogContentProps = {
+  children: React.ReactNode
+  className?: string
+  overlayClassName?: string
+  closable?: boolean
+}
+
+export function DialogContent({
+  children,
+  className,
+  overlayClassName,
+  closable = false,
+}: DialogContentProps) {
+  return (
+    <BaseDialog.Portal>
+      <BaseDialog.Backdrop
+        className={cn(
+          'fixed inset-0 z-50 bg-background-overlay',
+          'transition-opacity duration-150 data-[ending-style]:opacity-0 data-[starting-style]:opacity-0 motion-reduce:transition-none',
+          overlayClassName,
+        )}
+      />
+      <BaseDialog.Popup
+        className={cn(
+          'fixed left-1/2 top-1/2 z-50 max-h-[80dvh] w-[480px] max-w-[calc(100vw-2rem)] -translate-x-1/2 -translate-y-1/2 overflow-y-auto rounded-2xl border-[0.5px] border-components-panel-border bg-components-panel-bg p-6 shadow-xl',
+          'transition-[transform,scale,opacity] duration-150 data-[ending-style]:scale-95 data-[starting-style]:scale-95 data-[ending-style]:opacity-0 data-[starting-style]:opacity-0 motion-reduce:transition-none',
+          className,
+        )}
+      >
+        {closable && (
+          <BaseDialog.Close aria-label="Close" className="absolute right-6 top-6 z-10 flex h-5 w-5 cursor-pointer items-center justify-center rounded-2xl hover:bg-state-base-hover">
+            <span className="i-ri-close-line h-4 w-4 text-text-tertiary" />
+          </BaseDialog.Close>
+        )}
+        {children}
+      </BaseDialog.Popup>
+    </BaseDialog.Portal>
+  )
+}

web/app/components/base/ui/dropdown-menu/index.tsx

@@ -0,0 +1,277 @@
+'use client'
+
+import type { Placement } from '@/app/components/base/ui/placement'
+import { Menu } from '@base-ui/react/menu'
+import * as React from 'react'
+import { parsePlacement } from '@/app/components/base/ui/placement'
+import { cn } from '@/utils/classnames'
+
+export const DropdownMenu = Menu.Root
+export const DropdownMenuPortal = Menu.Portal
+export const DropdownMenuTrigger = Menu.Trigger
+export const DropdownMenuSub = Menu.SubmenuRoot
+export const DropdownMenuGroup = Menu.Group
+export const DropdownMenuRadioGroup = Menu.RadioGroup
+
+const menuRowBaseClassName = 'mx-1 flex h-8 cursor-pointer select-none items-center rounded-lg px-2 outline-none'
+const menuRowStateClassName = 'data-[highlighted]:bg-state-base-hover data-[disabled]:cursor-not-allowed data-[disabled]:opacity-50'
+
+export function DropdownMenuRadioItem({
+  className,
+  ...props
+}: React.ComponentPropsWithoutRef<typeof Menu.RadioItem>) {
+  return (
+    <Menu.RadioItem
+      className={cn(
+        menuRowBaseClassName,
+        menuRowStateClassName,
+        className,
+      )}
+      {...props}
+    />
+  )
+}
+
+export function DropdownMenuRadioItemIndicator({
+  className,
+  ...props
+}: Omit<React.ComponentPropsWithoutRef<typeof Menu.RadioItemIndicator>, 'children'>) {
+  return (
+    <Menu.RadioItemIndicator
+      className={cn(
+        'ml-auto flex shrink-0 items-center text-text-accent',
+        className,
+      )}
+      {...props}
+    >
+      <span aria-hidden className="i-ri-check-line h-4 w-4" />
+    </Menu.RadioItemIndicator>
+  )
+}
+
+export function DropdownMenuCheckboxItem({
+  className,
+  ...props
+}: React.ComponentPropsWithoutRef<typeof Menu.CheckboxItem>) {
+  return (
+    <Menu.CheckboxItem
+      className={cn(
+        menuRowBaseClassName,
+        menuRowStateClassName,
+        className,
+      )}
+      {...props}
+    />
+  )
+}
+
+export function DropdownMenuCheckboxItemIndicator({
+  className,
+  ...props
+}: Omit<React.ComponentPropsWithoutRef<typeof Menu.CheckboxItemIndicator>, 'children'>) {
+  return (
+    <Menu.CheckboxItemIndicator
+      className={cn(
+        'ml-auto flex shrink-0 items-center text-text-accent',
+        className,
+      )}
+      {...props}
+    >
+      <span aria-hidden className="i-ri-check-line h-4 w-4" />
+    </Menu.CheckboxItemIndicator>
+  )
+}
+
+export function DropdownMenuGroupLabel({
+  className,
+  ...props
+}: React.ComponentPropsWithoutRef<typeof Menu.GroupLabel>) {
+  return (
+    <Menu.GroupLabel
+      className={cn(
+        'px-3 py-1 text-text-tertiary system-2xs-medium-uppercase',
+        className,
+      )}
+      {...props}
+    />
+  )
+}
+
+type DropdownMenuContentProps = {
+  children: React.ReactNode
+  placement?: Placement
+  sideOffset?: number
+  alignOffset?: number
+  className?: string
+  popupClassName?: string
+  positionerProps?: Omit<
+    React.ComponentPropsWithoutRef<typeof Menu.Positioner>,
+    'children' | 'className' | 'side' | 'align' | 'sideOffset' | 'alignOffset'
+  >
+  popupProps?: Omit<
+    React.ComponentPropsWithoutRef<typeof Menu.Popup>,
+    'children' | 'className'
+  >
+}
+
+type DropdownMenuPopupRenderProps = Required<Pick<DropdownMenuContentProps, 'children'>> & {
+  placement: Placement
+  sideOffset: number
+  alignOffset: number
+  className?: string
+  popupClassName?: string
+  positionerProps?: DropdownMenuContentProps['positionerProps']
+  popupProps?: DropdownMenuContentProps['popupProps']
+}
+
+function renderDropdownMenuPopup({
+  children,
+  placement,
+  sideOffset,
+  alignOffset,
+  className,
+  popupClassName,
+  positionerProps,
+  popupProps,
+}: DropdownMenuPopupRenderProps) {
+  const { side, align } = parsePlacement(placement)
+
+  return (
+    <Menu.Portal>
+      <Menu.Positioner
+        side={side}
+        align={align}
+        sideOffset={sideOffset}
+        alignOffset={alignOffset}
+        className={cn('z-50 outline-none', className)}
+        {...positionerProps}
+      >
+        <Menu.Popup
+          className={cn(
+            'max-h-[var(--available-height)] overflow-y-auto overflow-x-hidden rounded-xl border-[0.5px] border-components-panel-border bg-components-panel-bg py-1 text-sm text-text-secondary shadow-lg',
+            'origin-[var(--transform-origin)] transition-[transform,scale,opacity] data-[ending-style]:scale-95 data-[starting-style]:scale-95 data-[ending-style]:opacity-0 data-[starting-style]:opacity-0 motion-reduce:transition-none',
+            popupClassName,
+          )}
+          {...popupProps}
+        >
+          {children}
+        </Menu.Popup>
+      </Menu.Positioner>
+    </Menu.Portal>
+  )
+}
+
+export function DropdownMenuContent({
+  children,
+  placement = 'bottom-end',
+  sideOffset = 4,
+  alignOffset = 0,
+  className,
+  popupClassName,
+  positionerProps,
+  popupProps,
+}: DropdownMenuContentProps) {
+  return renderDropdownMenuPopup({
+    children,
+    placement,
+    sideOffset,
+    alignOffset,
+    className,
+    popupClassName,
+    positionerProps,
+    popupProps,
+  })
+}
+
+type DropdownMenuSubTriggerProps = React.ComponentPropsWithoutRef<typeof Menu.SubmenuTrigger> & {
+  destructive?: boolean
+}
+
+export function DropdownMenuSubTrigger({
+  className,
+  destructive,
+  children,
+  ...props
+}: DropdownMenuSubTriggerProps) {
+  return (
+    <Menu.SubmenuTrigger
+      className={cn(
+        menuRowBaseClassName,
+        menuRowStateClassName,
+        destructive && 'text-text-destructive',
+        className,
+      )}
+      {...props}
+    >
+      {children}
+      <span aria-hidden className="i-ri-arrow-right-s-line ml-auto size-[14px] shrink-0 text-text-tertiary" />
+    </Menu.SubmenuTrigger>
+  )
+}
+
+type DropdownMenuSubContentProps = {
+  children: React.ReactNode
+  placement?: Placement
+  sideOffset?: number
+  alignOffset?: number
+  className?: string
+  popupClassName?: string
+  positionerProps?: DropdownMenuContentProps['positionerProps']
+  popupProps?: DropdownMenuContentProps['popupProps']
+}
+
+export function DropdownMenuSubContent({
+  children,
+  placement = 'left-start',
+  sideOffset = 4,
+  alignOffset = 0,
+  className,
+  popupClassName,
+  positionerProps,
+  popupProps,
+}: DropdownMenuSubContentProps) {
+  return renderDropdownMenuPopup({
+    children,
+    placement,
+    sideOffset,
+    alignOffset,
+    className,
+    popupClassName,
+    positionerProps,
+    popupProps,
+  })
+}
+
+type DropdownMenuItemProps = React.ComponentPropsWithoutRef<typeof Menu.Item> & {
+  destructive?: boolean
+}
+
+export function DropdownMenuItem({
+  className,
+  destructive,
+  ...props
+}: DropdownMenuItemProps) {
+  return (
+    <Menu.Item
+      className={cn(
+        menuRowBaseClassName,
+        menuRowStateClassName,
+        destructive && 'text-text-destructive',
+        className,
+      )}
+      {...props}
+    />
+  )
+}
+
+export function DropdownMenuSeparator({
+  className,
+  ...props
+}: React.ComponentPropsWithoutRef<typeof Menu.Separator>) {
+  return (
+    <Menu.Separator
+      className={cn('my-1 h-px bg-divider-regular', className)}
+      {...props}
+    />
+  )
+}

web/app/components/base/ui/placement.ts

@@ -0,0 +1,29 @@
+// Placement type for overlay positioning.
+// Mirrors the Floating UI Placement spec — a stable set of 12 CSS-based position values.
+// Reference: https://floating-ui.com/docs/useFloating#placement
+
+type Side = 'top' | 'bottom' | 'left' | 'right'
+type Align = 'start' | 'center' | 'end'
+
+export type Placement
+  = 'top'
+    | 'top-start'
+    | 'top-end'
+    | 'right'
+    | 'right-start'
+    | 'right-end'
+    | 'bottom'
+    | 'bottom-start'
+    | 'bottom-end'
+    | 'left'
+    | 'left-start'
+    | 'left-end'
+
+export function parsePlacement(placement: Placement): { side: Side, align: Align } {
+  const [side, align] = placement.split('-') as [Side, Align | undefined]
+
+  return {
+    side,
+    align: align ?? 'center',
+  }
+}

web/app/components/base/ui/popover/index.tsx

@@ -0,0 +1,67 @@
+'use client'
+
+import type { Placement } from '@/app/components/base/ui/placement'
+import { Popover as BasePopover } from '@base-ui/react/popover'
+import * as React from 'react'
+import { parsePlacement } from '@/app/components/base/ui/placement'
+import { cn } from '@/utils/classnames'
+
+export const Popover = BasePopover.Root
+export const PopoverTrigger = BasePopover.Trigger
+export const PopoverClose = BasePopover.Close
+export const PopoverTitle = BasePopover.Title
+export const PopoverDescription = BasePopover.Description
+
+type PopoverContentProps = {
+  children: React.ReactNode
+  placement?: Placement
+  sideOffset?: number
+  alignOffset?: number
+  className?: string
+  popupClassName?: string
+  positionerProps?: Omit<
+    React.ComponentPropsWithoutRef<typeof BasePopover.Positioner>,
+    'children' | 'className' | 'side' | 'align' | 'sideOffset' | 'alignOffset'
+  >
+  popupProps?: Omit<
+    React.ComponentPropsWithoutRef<typeof BasePopover.Popup>,
+    'children' | 'className'
+  >
+}
+
+export function PopoverContent({
+  children,
+  placement = 'bottom',
+  sideOffset = 8,
+  alignOffset = 0,
+  className,
+  popupClassName,
+  positionerProps,
+  popupProps,
+}: PopoverContentProps) {
+  const { side, align } = parsePlacement(placement)
+
+  return (
+    <BasePopover.Portal>
+      <BasePopover.Positioner
+        side={side}
+        align={align}
+        sideOffset={sideOffset}
+        alignOffset={alignOffset}
+        className={cn('z-50 outline-none', className)}
+        {...positionerProps}
+      >
+        <BasePopover.Popup
+          className={cn(
+            'rounded-xl border-[0.5px] border-components-panel-border bg-components-panel-bg shadow-lg',
+            'origin-[var(--transform-origin)] transition-[transform,scale,opacity] data-[ending-style]:scale-95 data-[starting-style]:scale-95 data-[ending-style]:opacity-0 data-[starting-style]:opacity-0 motion-reduce:transition-none',
+            popupClassName,
+          )}
+          {...popupProps}
+        >
+          {children}
+        </BasePopover.Popup>
+      </BasePopover.Positioner>
+    </BasePopover.Portal>
+  )
+}

web/app/components/base/ui/select/index.tsx

@@ -0,0 +1,163 @@
+'use client'
+
+import type { Placement } from '@/app/components/base/ui/placement'
+import { Select as BaseSelect } from '@base-ui/react/select'
+import * as React from 'react'
+import { parsePlacement } from '@/app/components/base/ui/placement'
+import { cn } from '@/utils/classnames'
+
+export const Select = BaseSelect.Root
+export const SelectValue = BaseSelect.Value
+export const SelectGroup = BaseSelect.Group
+export const SelectGroupLabel = BaseSelect.GroupLabel
+export const SelectSeparator = BaseSelect.Separator
+
+type SelectTriggerProps = React.ComponentPropsWithoutRef<typeof BaseSelect.Trigger> & {
+  clearable?: boolean
+  onClear?: () => void
+  loading?: boolean
+}
+
+export function SelectTrigger({
+  className,
+  children,
+  clearable = false,
+  onClear,
+  loading = false,
+  ...props
+}: SelectTriggerProps) {
+  const showClear = clearable && !loading
+
+  return (
+    <BaseSelect.Trigger
+      className={cn(
+        'group relative flex h-8 w-full items-center rounded-lg border-0 bg-components-input-bg-normal px-2 text-left text-components-input-text-filled outline-none',
+        'hover:bg-state-base-hover-alt focus-visible:bg-state-base-hover-alt disabled:cursor-not-allowed disabled:opacity-50',
+        className,
+      )}
+      {...props}
+    >
+      <span className="grow truncate">{children}</span>
+      {loading
+        ? (
+            <span className="ml-1 shrink-0 text-text-quaternary">
+              <span className="i-ri-loader-4-line h-3.5 w-3.5 animate-spin" />
+            </span>
+          )
+        : showClear
+          ? (
+              <span
+                role="button"
+                aria-label="Clear selection"
+                tabIndex={-1}
+                className="ml-1 shrink-0 cursor-pointer text-text-quaternary hover:text-text-secondary"
+                onClick={(e) => {
+                  e.stopPropagation()
+                  onClear?.()
+                }}
+                onMouseDown={(e) => {
+                  e.stopPropagation()
+                }}
+              >
+                <span className="i-ri-close-circle-fill h-3.5 w-3.5" />
+              </span>
+            )
+          : (
+              <BaseSelect.Icon className="ml-1 shrink-0 text-text-quaternary transition-colors group-hover:text-text-secondary data-[open]:text-text-secondary">
+                <span className="i-ri-arrow-down-s-line h-4 w-4" />
+              </BaseSelect.Icon>
+            )}
+    </BaseSelect.Trigger>
+  )
+}
+
+type SelectContentProps = {
+  children: React.ReactNode
+  placement?: Placement
+  sideOffset?: number
+  alignOffset?: number
+  className?: string
+  popupClassName?: string
+  listClassName?: string
+  positionerProps?: Omit<
+    React.ComponentPropsWithoutRef<typeof BaseSelect.Positioner>,
+    'children' | 'className' | 'side' | 'align' | 'sideOffset' | 'alignOffset'
+  >
+  popupProps?: Omit<
+    React.ComponentPropsWithoutRef<typeof BaseSelect.Popup>,
+    'children' | 'className'
+  >
+  listProps?: Omit<
+    React.ComponentPropsWithoutRef<typeof BaseSelect.List>,
+    'children' | 'className'
+  >
+}
+
+export function SelectContent({
+  children,
+  placement = 'bottom-start',
+  sideOffset = 4,
+  alignOffset = 0,
+  className,
+  popupClassName,
+  listClassName,
+  positionerProps,
+  popupProps,
+  listProps,
+}: SelectContentProps) {
+  const { side, align } = parsePlacement(placement)
+
+  return (
+    <BaseSelect.Portal>
+      <BaseSelect.Positioner
+        side={side}
+        align={align}
+        sideOffset={sideOffset}
+        alignOffset={alignOffset}
+        alignItemWithTrigger={false}
+        className={cn('z-50 outline-none', className)}
+        {...positionerProps}
+      >
+        <BaseSelect.Popup
+          className={cn(
+            'rounded-xl border-[0.5px] border-components-panel-border bg-components-panel-bg shadow-lg',
+            'origin-[var(--transform-origin)] transition-[transform,scale,opacity] data-[ending-style]:scale-95 data-[starting-style]:scale-95 data-[ending-style]:opacity-0 data-[starting-style]:opacity-0 motion-reduce:transition-none',
+            popupClassName,
+          )}
+          {...popupProps}
+        >
+          <BaseSelect.List
+            className={cn('max-h-80 min-w-[10rem] overflow-auto p-1 outline-none', listClassName)}
+            {...listProps}
+          >
+            {children}
+          </BaseSelect.List>
+        </BaseSelect.Popup>
+      </BaseSelect.Positioner>
+    </BaseSelect.Portal>
+  )
+}
+
+export function SelectItem({
+  className,
+  children,
+  ...props
+}: React.ComponentPropsWithoutRef<typeof BaseSelect.Item>) {
+  return (
+    <BaseSelect.Item
+      className={cn(
+        'flex h-8 cursor-pointer items-center rounded-lg px-2 text-text-secondary outline-none system-sm-medium',
+        'data-[disabled]:cursor-not-allowed data-[highlighted]:bg-state-base-hover data-[disabled]:opacity-50',
+        className,
+      )}
+      {...props}
+    >
+      <BaseSelect.ItemText className="mr-1 grow truncate px-1">
+        {children}
+      </BaseSelect.ItemText>
+      <BaseSelect.ItemIndicator className="flex shrink-0 items-center text-text-accent">
+        <span className="i-ri-check-line h-4 w-4" />
+      </BaseSelect.ItemIndicator>
+    </BaseSelect.Item>
+  )
+}

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

@@ -0,0 +1,59 @@
+'use client'
+
+import type { Placement } from '@/app/components/base/ui/placement'
+import { Tooltip as BaseTooltip } from '@base-ui/react/tooltip'
+import * as React from 'react'
+import { parsePlacement } from '@/app/components/base/ui/placement'
+import { cn } from '@/utils/classnames'
+
+type TooltipContentVariant = 'default' | 'plain'
+
+export type TooltipContentProps = {
+  children: React.ReactNode
+  placement?: Placement
+  sideOffset?: number
+  alignOffset?: number
+  className?: string
+  popupClassName?: string
+  variant?: TooltipContentVariant
+} & Omit<React.ComponentPropsWithoutRef<typeof BaseTooltip.Popup>, 'children' | 'className'>
+
+export function TooltipContent({
+  children,
+  placement = 'top',
+  sideOffset = 8,
+  alignOffset = 0,
+  className,
+  popupClassName,
+  variant = 'default',
+  ...props
+}: TooltipContentProps) {
+  const { side, align } = parsePlacement(placement)
+
+  return (
+    <BaseTooltip.Portal>
+      <BaseTooltip.Positioner
+        side={side}
+        align={align}
+        sideOffset={sideOffset}
+        alignOffset={alignOffset}
+        className={cn('z-50 outline-none', className)}
+      >
+        <BaseTooltip.Popup
+          className={cn(
+            variant === 'default' && 'max-w-[300px] break-words rounded-md bg-components-panel-bg px-3 py-2 text-left text-text-tertiary shadow-lg system-xs-regular',
+            'origin-[var(--transform-origin)] transition-[opacity] data-[ending-style]:opacity-0 data-[starting-style]:opacity-0 data-[instant]:transition-none motion-reduce:transition-none',
+            popupClassName,
+          )}
+          {...props}
+        >
+          {children}
+        </BaseTooltip.Popup>
+      </BaseTooltip.Positioner>
+    </BaseTooltip.Portal>
+  )
+}
+
+export const TooltipProvider = BaseTooltip.Provider
+export const Tooltip = BaseTooltip.Root
+export const TooltipTrigger = BaseTooltip.Trigger