第 3 课：Radix UI

┌─────────────────────────────────────────────────────────────────┐
│  🎯 核心观点：Headless UI 是 AI 时代组件库的最佳底层架构        │
├─────────────────────────────────────────────────────────────────┤
│  📚 你将学到：                                                   │
│    • 理解 Radix 的设计愿景：可访问、无样式、开放                │
│    • 掌握 Composition 模式和 asChild 的工作原理                 │
│    • 深入可访问性原语（WAI-ARIA、焦点管理、键盘导航）           │
│    • 学习 2025 新原语（PasswordToggleField、OneTimePassword）   │
│    • 掌握 radix-ui 统一包和增量采用策略                         │
│    • 横向对比 Radix / Headless UI / React Aria / Ark UI        │
└─────────────────────────────────────────────────────────────────┘

// shadcn/ui 的 Dialog 组件核心代码
import * as DialogPrimitive from "@radix-ui/react-dialog"

const Dialog = DialogPrimitive.Root
const DialogTrigger = DialogPrimitive.Trigger
const DialogContent = DialogPrimitive.Content

export { Dialog, DialogTrigger, DialogContent }

import { Modal } from 'antd'

<Modal
  title="确认删除"
  open={isOpen}
  onOk={handleOk}
  onCancel={handleCancel}
>
  <p>确定要删除这条记录吗？</p>
</Modal>

import * as Dialog from '@radix-ui/react-dialog'

<Dialog.Root open={isOpen} onOpenChange={setIsOpen}>
  <Dialog.Trigger asChild>
    <button>打开对话框</button>
  </Dialog.Trigger>

  <Dialog.Portal>
    <Dialog.Overlay className="fixed inset-0 bg-black/50" />
    <Dialog.Content className="fixed top-1/2 left-1/2 ...">
      <Dialog.Title>确认删除</Dialog.Title>
      <Dialog.Description>
        确定要删除这条记录吗？
      </Dialog.Description>

      <button onClick={() => setIsOpen(false)}>取消</button>
      <button onClick={handleDelete}>确认</button>

      <Dialog.Close asChild>
        <button>×</button>
      </Dialog.Close>
    </Dialog.Content>
  </Dialog.Portal>
</Dialog.Root>

1. Dialog.Root 管理状态
2. Dialog.Trigger 触发打开
3. Dialog.Portal 渲染到 body
4. Dialog.Overlay 作为遮罩
5. Dialog.Content 作为内容容器
6. Dialog.Title/Description 提供语义
7. Dialog.Close 关闭

import * as Dialog from '@radix-ui/react-dialog'
import { X, AlertTriangle } from 'lucide-react'

function DeleteConfirmDialog() {
  const [open, setOpen] = useState(false)

  return (
    <Dialog.Root open={open} onOpenChange={setOpen}>
      {/* 触发器：可以是任何元素 */}
      <Dialog.Trigger asChild>
        <button className="bg-red-500 text-white px-4 py-2 rounded">
          删除
        </button>
      </Dialog.Trigger>

      <Dialog.Portal>
        {/* 遮罩层：完全自定义样式 */}
        <Dialog.Overlay className="fixed inset-0 bg-black/50 backdrop-blur-sm" />

        {/* 内容区域：完全自定义布局 */}
        <Dialog.Content className="fixed top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 bg-white rounded-lg shadow-xl p-6 w-[400px]">
          
          {/* 标题：可以加任何内容 */}
          <div className="flex items-center gap-2 mb-4">
            <AlertTriangle className="text-red-500" />
            <Dialog.Title className="text-lg font-semibold">
              确认删除
            </Dialog.Title>
          </div>

          <Dialog.Description className="text-gray-600 mb-6">
            此操作不可撤销。确定要删除这条记录吗？
          </Dialog.Description>

          {/* 自定义内容：可以加任何东西 */}
          <div className="bg-yellow-50 border border-yellow-200 rounded p-3 mb-6">
            <p className="text-sm text-yellow-800">警告：删除后将无法恢复</p>
          </div>

          {/* 按钮组 */}
          <div className="flex justify-end gap-3">
            <Dialog.Close asChild>
              <button className="px-4 py-2 border rounded">取消</button>
            </Dialog.Close>
            <button 
              className="px-4 py-2 bg-red-500 text-white rounded"
              onClick={() => { handleDelete(); setOpen(false); }}
            >
              确认删除
            </button>
          </div>

          {/* 关闭按钮：放在右上角 */}
          <Dialog.Close asChild>
            <button className="absolute top-4 right-4 text-gray-400 hover:text-gray-600">
              <X size={20} />
            </button>
          </Dialog.Close>
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog.Root>
  )
}

// 简化版的 Slot 实现
function Slot({ children, ...props }) {
  if (React.isValidElement(children)) {
    return React.cloneElement(children, {
      ...props,           // 父组件的 props
      ...children.props,  // 子组件的 props
    })
  }
  return null
}

// ❌ 一个看起来"能用"但有问题的 Dialog
function MyDialog({ open, onClose, children }) {
  if (!open) return null

  return (
    <div className="fixed inset-0 bg-black/50" onClick={onClose}>
      <div className="fixed top-1/2 left-1/2 ...">
        {children}
      </div>
    </div>
  )
}

<Dialog.Content>
  <Dialog.Title>标题</Dialog.Title>
  <Dialog.Description>描述</Dialog.Description>
</Dialog.Content>

<div 
  role="dialog" 
  aria-modal="true"
  aria-labelledby="radix-:r1:"
  aria-describedby="radix-:r2:"
>
  <h2 id="radix-:r1:">标题</h2>
  <p id="radix-:r2:">描述</p>
</div>

// Radix 内部的焦点管理逻辑（简化版）
useEffect(() => {
  if (open) {
    const previousFocus = document.activeElement  // 保存当前焦点
    contentRef.current?.focus()                   // 移动焦点到 Dialog
    
    return () => {
      previousFocus?.focus()                      // 恢复焦点
    }
  }
}, [open])

// 简化版的焦点陷阱逻辑
function handleKeyDown(e) {
  if (e.key === 'Tab') {
    const focusableElements = contentRef.current.querySelectorAll(
      'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
    )
    
    const first = focusableElements[0]
    const last = focusableElements[focusableElements.length - 1]
    
    if (e.shiftKey && document.activeElement === first) {
      e.preventDefault()
      last.focus()  // Shift+Tab 在第一个元素时，跳到最后一个
    } else if (!e.shiftKey && document.activeElement === last) {
      e.preventDefault()
      first.focus() // Tab 在最后一个元素时，跳到第一个
    }
  }
}

// ESC 关闭
function handleKeyDown(e) {
  if (e.key === 'Escape') {
    onOpenChange(false)
  }
}

// @radix-ui/react-slot 简化版源码
import * as React from 'react'

interface SlotProps extends React.HTMLAttributes<HTMLElement> {
  children?: React.ReactNode
}

const Slot = React.forwardRef<HTMLElement, SlotProps>(
  (props, forwardedRef) => {
    const { children, ...slotProps } = props
    const childrenArray = React.Children.toArray(children)
    const slottable = childrenArray.find(isSlottable)

    if (slottable) {
      // 如果子元素是 Slottable，特殊处理
      const newElement = slottable.props.children as React.ReactNode
      const newChildren = childrenArray.map((child) => {
        if (child === slottable) {
          // 替换 Slottable 的内容
          if (React.Children.count(newElement) > 1) {
            return React.Children.only(null)
          }
          return React.isValidElement(newElement)
            ? (newElement.props.children as React.ReactNode)
            : null
        }
        return child
      })

      return (
        <SlotClone {...slotProps} ref={forwardedRef}>
          {React.isValidElement(newElement)
            ? React.cloneElement(newElement, undefined, newChildren)
            : null}
        </SlotClone>
      )
    }

    // 正常情况：合并 props 到子元素
    return (
      <SlotClone {...slotProps} ref={forwardedRef}>
        {children}
      </SlotClone>
    )
  }
)

// SlotClone 核心逻辑
const SlotClone = React.forwardRef<any, SlotCloneProps>(
  (props, forwardedRef) => {
    const { children, ...slotProps } = props

    if (React.isValidElement(children)) {
      // 🔑 核心：使用 cloneElement 合并 props
      return React.cloneElement(children, {
        ...mergeProps(slotProps, children.props),
        ref: forwardedRef
          ? composeRefs(forwardedRef, (children as any).ref)
          : (children as any).ref,
      })
    }

    return React.Children.count(children) > 1 
      ? React.Children.only(null) 
      : null
  }
)

// mergeProps 的实现逻辑
function mergeProps(slotProps: AnyProps, childProps: AnyProps) {
  const overrideProps = { ...childProps }

  for (const propName in childProps) {
    const slotPropValue = slotProps[propName]
    const childPropValue = childProps[propName]

    const isHandler = /^on[A-Z]/.test(propName)
    
    if (isHandler) {
      // 🟡 事件处理器：两个都调用
      if (slotPropValue && childPropValue) {
        overrideProps[propName] = (...args: unknown[]) => {
          childPropValue(...args)
          slotPropValue(...args)
        }
      } else if (slotPropValue) {
        overrideProps[propName] = slotPropValue
      }
    } else if (propName === 'style') {
      // 🟢 style：深度合并
      overrideProps[propName] = { ...slotPropValue, ...childPropValue }
    } else if (propName === 'className') {
      // 🔵 className：拼接
      overrideProps[propName] = [slotPropValue, childPropValue]
        .filter(Boolean)
        .join(' ')
    }
  }

  return { ...slotProps, ...overrideProps }
}

// composeRefs 实现
function composeRefs<T>(...refs: React.Ref<T>[]) {
  return (node: T) => {
    refs.forEach((ref) => {
      if (typeof ref === 'function') {
        ref(node)
      } else if (ref !== null) {
        (ref as React.MutableRefObject<T>).current = node
      }
    })
  }
}

// 使用场景
<Dialog.Trigger asChild>
  <Button ref={myButtonRef}>  {/* 两个 ref 都会生效 */}
    点击我
  </Button>
</Dialog.Trigger>

// Radix 的核心 Hook，支持受控和非受控
function useControllableState<T>({
  prop,
  defaultProp,
  onChange = () => {},
}: UseControllableStateParams<T>) {
  // 非受控状态
  const [uncontrolledProp, setUncontrolledProp] = useUncontrolledState({
    defaultProp,
    onChange,
  })
  
  // 判断是否受控
  const isControlled = prop !== undefined
  const value = isControlled ? prop : uncontrolledProp
  
  const handleChange = useCallbackRef(onChange)

  const setValue: React.Dispatch<React.SetStateAction<T | undefined>> = 
    React.useCallback(
      (nextValue) => {
        if (isControlled) {
          // 受控模式：调用 onChange
          const setter = nextValue as SetStateFn<T>
          const value = typeof nextValue === 'function' 
            ? setter(prop) 
            : nextValue
          if (value !== prop) handleChange(value as T)
        } else {
          // 非受控模式：更新内部状态
          setUncontrolledProp(nextValue)
        }
      },
      [isControlled, prop, setUncontrolledProp, handleChange]
    )

  return [value, setValue] as const
}

// 非受控：内部管理状态
<Dialog.Root defaultOpen={false}>
  {/* ... */}
</Dialog.Root>

// 受控：外部管理状态
const [open, setOpen] = useState(false)
<Dialog.Root open={open} onOpenChange={setOpen}>
  {/* ... */}
</Dialog.Root>

// 混合：外部监听，内部管理
<Dialog.Root 
  defaultOpen={false} 
  onOpenChange={(open) => {
    console.log('Dialog state changed:', open)
    analytics.track('dialog_toggled', { open })
  }}
>
  {/* ... */}
</Dialog.Root>

// 创建类型安全的 Context
interface DialogContextValue {
  triggerRef: React.RefObject<HTMLButtonElement>
  contentId: string
  titleId: string
  descriptionId: string
  open: boolean
  onOpenChange(open: boolean): void
  onOpenToggle(): void
  modal: boolean
}

const [DialogProvider, useDialogContext] = 
  createContext<DialogContextValue>('Dialog')

// Root 组件提供 Context
function DialogRoot({ children, open, onOpenChange, modal = true }) {
  const [_open, setOpen] = useControllableState({
    prop: open,
    defaultProp: false,
    onChange: onOpenChange,
  })
  
  return (
    <DialogProvider
      open={_open}
      onOpenChange={setOpen}
      onOpenToggle={() => setOpen(prev => !prev)}
      modal={modal}
      triggerRef={triggerRef}
      contentId={useId()}
      titleId={useId()}
      descriptionId={useId()}
    >
      {children}
    </DialogProvider>
  )
}

// Trigger 消费 Context
function DialogTrigger({ asChild, children, ...props }) {
  const context = useDialogContext('DialogTrigger')
  const Comp = asChild ? Slot : 'button'
  
  return (
    <Comp
      type="button"
      aria-haspopup="dialog"
      aria-expanded={context.open}
      aria-controls={context.contentId}
      onClick={() => context.onOpenToggle()}
      ref={context.triggerRef}
      {...props}
    >
      {children}
    </Comp>
  )
}

import { createPortal } from 'react-dom'

interface PortalProps {
  container?: HTMLElement | null
  children: React.ReactNode
}

function Portal({ container, children }: PortalProps) {
  const [mounted, setMounted] = React.useState(false)
  
  // 确保在客户端渲染
  React.useEffect(() => {
    setMounted(true)
  }, [])
  
  // 默认渲染到 document.body
  const portalContainer = container ?? 
    (globalThis?.document?.body as HTMLElement)

  if (!mounted || !portalContainer) {
    return null
  }

  return createPortal(
    <div data-radix-portal="">
      {children}
    </div>,
    portalContainer
  )
}

// 统一的 Dismiss 处理
function useDismiss({
  onDismiss,
  disableOutsidePointerEvents = false,
}) {
  const handleEscape = useEscapeKeydown((event) => {
    onDismiss()
  })
  
  const handleOutsideClick = useOutsideClick((event) => {
    onDismiss()
  }, disableOutsidePointerEvents)
  
  const handleFocusOutside = useFocusOutside((event) => {
    // 处理焦点离开的情况
  })
  
  return {
    onEscapeKeyDown: handleEscape,
    onPointerDownOutside: handleOutsideClick,
    onFocusOutside: handleFocusOutside,
  }
}

// Dialog Content 的事件处理
function DialogContent({ 
  onEscapeKeyDown,
  onPointerDownOutside,
  onInteractOutside,
  ...props 
}) {
  return (
    <DismissableLayer
      // 允许拦截默认行为
      onEscapeKeyDown={(event) => {
        onEscapeKeyDown?.(event)
        if (!event.defaultPrevented) {
          context.onOpenChange(false)
        }
      }}
      // 点击外部关闭
      onPointerDownOutside={(event) => {
        onPointerDownOutside?.(event)
        if (!event.defaultPrevented) {
          context.onOpenChange(false)
        }
      }}
      // 统一的交互外部事件
      onInteractOutside={(event) => {
        onInteractOutside?.(event)
      }}
      {...props}
    />
  )
}

// 使用示例：阻止 ESC 关闭
<DialogContent
  onEscapeKeyDown={(e) => {
    e.preventDefault()  // 阻止默认关闭行为
    showConfirmation()  // 显示确认弹窗
  }}
>
  {/* ... */}
</DialogContent>

// Radix 自动注入 data-state 属性
<DialogOverlay 
  data-state="open"   // 或 "closed"
  className="..."
/>

<DialogContent
  data-state="open"   // 或 "closed"
  className="..."
/>

/* 使用 Tailwind + data-state */
.dialog-overlay {
  @apply fixed inset-0 bg-black/50;
  
  /* 进入动画 */
  &[data-state="open"] {
    @apply animate-in fade-in;
  }
  
  /* 退出动画 */
  &[data-state="closed"] {
    @apply animate-out fade-out;
  }
}

.dialog-content {
  @apply fixed top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2;
  
  &[data-state="open"] {
    @apply animate-in fade-in-0 zoom-in-95;
  }
  
  &[data-state="closed"] {
    @apply animate-out fade-out-0 zoom-out-95;
  }
}

import { motion, AnimatePresence } from 'framer-motion'

function AnimatedDialog({ open, onOpenChange }) {
  return (
    <Dialog.Root open={open} onOpenChange={onOpenChange}>
      <Dialog.Trigger asChild>
        <Button>打开</Button>
      </Dialog.Trigger>
      
      <AnimatePresence>
        {open && (
          <Dialog.Portal forceMount>
            <Dialog.Overlay asChild>
              <motion.div
                className="fixed inset-0 bg-black/50"
                initial={{ opacity: 0 }}
                animate={{ opacity: 1 }}
                exit={{ opacity: 0 }}
              />
            </Dialog.Overlay>
            
            <Dialog.Content asChild>
              <motion.div
                className="fixed top-1/2 left-1/2 ..."
                initial={{ opacity: 0, scale: 0.95, y: '-48%', x: '-50%' }}
                animate={{ opacity: 1, scale: 1, y: '-50%', x: '-50%' }}
                exit={{ opacity: 0, scale: 0.95, y: '-48%', x: '-50%' }}
                transition={{ duration: 0.2 }}
              >
                {/* Dialog content */}
              </motion.div>
            </Dialog.Content>
          </Dialog.Portal>
        )}
      </AnimatePresence>
    </Dialog.Root>
  )
}

import * as React from "react"
import { Slot } from "@radix-ui/react-slot"       // ← Radix 的 Slot
import { cva, type VariantProps } from "class-variance-authority"  // ← CVA 管理变体
import { cn } from "@/lib/utils"                  // ← 类名合并工具

const buttonVariants = cva(
  "inline-flex items-center justify-center ...",  // ← 基础样式
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground ...",
        destructive: "bg-destructive ...",
        outline: "border border-input ...",
        // ...
      },
      size: {
        default: "h-9 px-4 py-2",
        sm: "h-8 rounded-md px-3 text-xs",
        lg: "h-10 rounded-md px-8",
        icon: "h-9 w-9",
      },
    },
    defaultVariants: { variant: "default", size: "default" },
  }
)

const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
  ({ className, variant, size, asChild = false, ...props }, ref) => {
    const Comp = asChild ? Slot : "button"  // ← 支持 asChild 模式
    return (
      <Comp
        className={cn(buttonVariants({ variant, size, className }))}
        ref={ref}
        {...props}
      />
    )
  }
)

export { Button, buttonVariants }

import * as DialogPrimitive from "@radix-ui/react-dialog"

// 直接导出 Radix 原语
const Dialog = DialogPrimitive.Root
const DialogTrigger = DialogPrimitive.Trigger
const DialogPortal = DialogPrimitive.Portal
const DialogClose = DialogPrimitive.Close

// 包装样式
const DialogOverlay = React.forwardRef(({ className, ...props }, ref) => (
  <DialogPrimitive.Overlay
    ref={ref}
    className={cn(
      "fixed inset-0 z-50 bg-black/80",
      "data-[state=open]:animate-in data-[state=closed]:animate-out",
      "data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
      className
    )}
    {...props}
  />
))

const DialogContent = React.forwardRef(({ className, children, ...props }, ref) => (
  <DialogPortal>
    <DialogOverlay />
    <DialogPrimitive.Content
      ref={ref}
      className={cn(
        "fixed left-[50%] top-[50%] z-50 ...",
        "data-[state=open]:animate-in data-[state=closed]:animate-out",
        className
      )}
      {...props}
    >
      {children}
      {/* 内置关闭按钮 */}
      <DialogPrimitive.Close className="absolute right-4 top-4 ...">
        <X className="h-4 w-4" />
        <span className="sr-only">Close</span>
      </DialogPrimitive.Close>
    </DialogPrimitive.Content>
  </DialogPortal>
))

// 便利组件
const DialogHeader = ({ className, ...props }) => (
  <div className={cn("flex flex-col space-y-1.5 ...", className)} {...props} />
)

const DialogFooter = ({ className, ...props }) => (
  <div className={cn("flex flex-col-reverse sm:flex-row ...", className)} {...props} />
)

const DialogTitle = React.forwardRef(({ className, ...props }, ref) => (
  <DialogPrimitive.Title
    ref={ref}
    className={cn("text-lg font-semibold ...", className)}
    {...props}
  />
))

const DialogDescription = React.forwardRef(({ className, ...props }, ref) => (
  <DialogPrimitive.Description
    ref={ref}
    className={cn("text-sm text-muted-foreground", className)}
    {...props}
  />
))

<Dialog>
  <DialogTrigger asChild>
    <Button>打开对话框</Button>
  </DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>确认删除</DialogTitle>
      <DialogDescription>
        此操作不可撤销。确定要删除这条记录吗？
      </DialogDescription>
    </DialogHeader>
    <DialogFooter>
      <Button variant="outline">取消</Button>
      <Button variant="destructive">删除</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>

import * as Select from '@radix-ui/react-select'
import { ChevronDown, Check } from 'lucide-react'

const roles = [
  { value: 'admin', label: '管理员', description: '拥有所有权限' },
  { value: 'editor', label: '编辑者', description: '可以编辑内容' },
  { value: 'viewer', label: '查看者', description: '只能查看内容' },
]

function RoleSelect({ value, onValueChange }) {
  return (
    <Select.Root value={value} onValueChange={onValueChange}>
      <Select.Trigger
        className="inline-flex items-center justify-between
          w-[200px] px-3 py-2 text-sm
          border rounded-md bg-white
          focus:outline-none focus:ring-2 focus:ring-blue-500"
      >
        <Select.Value placeholder="选择角色..." />
        <Select.Icon>
          <ChevronDown className="w-4 h-4 text-gray-500" />
        </Select.Icon>
      </Select.Trigger>

      <Select.Portal>
        <Select.Content
          className="overflow-hidden bg-white rounded-md shadow-lg
            border animate-in fade-in-0 zoom-in-95"
          position="popper"
          sideOffset={4}
        >
          <Select.Viewport className="p-1">
            {roles.map((role) => (
              <Select.Item
                key={role.value}
                value={role.value}
                className="relative flex items-center px-8 py-2 text-sm
                  rounded cursor-pointer select-none
                  data-[highlighted]:bg-blue-50
                  data-[highlighted]:outline-none"
              >
                <Select.ItemIndicator className="absolute left-2">
                  <Check className="w-4 h-4 text-blue-500" />
                </Select.ItemIndicator>
                <div>
                  <Select.ItemText>{role.label}</Select.ItemText>
                  <p className="text-xs text-gray-500">{role.description}</p>
                </div>
              </Select.Item>
            ))}
          </Select.Viewport>
        </Select.Content>
      </Select.Portal>
    </Select.Root>
  )
}

import * as DropdownMenu from '@radix-ui/react-dropdown-menu'
import { Settings, User, LogOut, ChevronRight } from 'lucide-react'

function UserMenu() {
  return (
    <DropdownMenu.Root>
      <DropdownMenu.Trigger asChild>
        <button className="flex items-center gap-2 px-3 py-2 rounded-full
          hover:bg-gray-100 focus:outline-none focus:ring-2">
          <img
            src="/avatar.png"
            alt=""
            className="w-8 h-8 rounded-full"
          />
          <span>张三</span>
        </button>
      </DropdownMenu.Trigger>

      <DropdownMenu.Portal>
        <DropdownMenu.Content
          className="min-w-[220px] bg-white rounded-md shadow-lg border p-1
            animate-in fade-in-0 zoom-in-95"
          sideOffset={5}
        >
          {/* 普通菜单项 */}
          <DropdownMenu.Item
            className="flex items-center gap-2 px-3 py-2 text-sm rounded
              cursor-pointer outline-none
              data-[highlighted]:bg-gray-100"
          >
            <User className="w-4 h-4" />
            个人资料
          </DropdownMenu.Item>

          <DropdownMenu.Item className="flex items-center gap-2 px-3 py-2 text-sm rounded
            cursor-pointer outline-none data-[highlighted]:bg-gray-100">
            <Settings className="w-4 h-4" />
            设置
          </DropdownMenu.Item>

          {/* 分割线 */}
          <DropdownMenu.Separator className="h-px bg-gray-200 my-1" />

          {/* 子菜单 */}
          <DropdownMenu.Sub>
            <DropdownMenu.SubTrigger
              className="flex items-center justify-between px-3 py-2 text-sm
                rounded cursor-pointer outline-none
                data-[highlighted]:bg-gray-100"
            >
              主题
              <ChevronRight className="w-4 h-4" />
            </DropdownMenu.SubTrigger>
            
            <DropdownMenu.Portal>
              <DropdownMenu.SubContent
                className="min-w-[160px] bg-white rounded-md shadow-lg border p-1"
                sideOffset={2}
              >
                <DropdownMenu.RadioGroup value="system">
                  <DropdownMenu.RadioItem value="light" className="...">
                    浅色
                  </DropdownMenu.RadioItem>
                  <DropdownMenu.RadioItem value="dark" className="...">
                    深色
                  </DropdownMenu.RadioItem>
                  <DropdownMenu.RadioItem value="system" className="...">
                    跟随系统
                  </DropdownMenu.RadioItem>
                </DropdownMenu.RadioGroup>
              </DropdownMenu.SubContent>
            </DropdownMenu.Portal>
          </DropdownMenu.Sub>

          <DropdownMenu.Separator className="h-px bg-gray-200 my-1" />

          {/* 危险操作 */}
          <DropdownMenu.Item
            className="flex items-center gap-2 px-3 py-2 text-sm text-red-600
              rounded cursor-pointer outline-none
              data-[highlighted]:bg-red-50"
          >
            <LogOut className="w-4 h-4" />
            退出登录
          </DropdownMenu.Item>
        </DropdownMenu.Content>
      </DropdownMenu.Portal>
    </DropdownMenu.Root>
  )
}

import * as Tabs from '@radix-ui/react-tabs'

function SettingsTabs() {
  return (
    <Tabs.Root defaultValue="profile" className="w-full">
      {/* Tab 列表 */}
      <Tabs.List className="flex border-b">
        <Tabs.Trigger
          value="profile"
          className="px-4 py-2 text-sm font-medium
            border-b-2 border-transparent
            data-[state=active]:border-blue-500
            data-[state=active]:text-blue-600
            hover:text-gray-700"
        >
          个人资料
        </Tabs.Trigger>
        
        <Tabs.Trigger
          value="security"
          className="px-4 py-2 text-sm font-medium
            border-b-2 border-transparent
            data-[state=active]:border-blue-500
            data-[state=active]:text-blue-600
            hover:text-gray-700"
        >
          安全设置
        </Tabs.Trigger>
        
        <Tabs.Trigger
          value="notifications"
          className="px-4 py-2 text-sm font-medium
            border-b-2 border-transparent
            data-[state=active]:border-blue-500
            data-[state=active]:text-blue-600
            hover:text-gray-700"
        >
          通知设置
        </Tabs.Trigger>
      </Tabs.List>

      {/* Tab 内容 */}
      <Tabs.Content value="profile" className="p-4">
        <h3 className="text-lg font-medium mb-4">个人资料</h3>
        <form className="space-y-4">
          <div>
            <label className="block text-sm font-medium mb-1">用户名</label>
            <input type="text" className="w-full px-3 py-2 border rounded" />
          </div>
          <div>
            <label className="block text-sm font-medium mb-1">邮箱</label>
            <input type="email" className="w-full px-3 py-2 border rounded" />
          </div>
        </form>
      </Tabs.Content>

      <Tabs.Content value="security" className="p-4">
        <h3 className="text-lg font-medium mb-4">安全设置</h3>
        <div className="space-y-4">
          <button className="px-4 py-2 bg-blue-500 text-white rounded">
            修改密码
          </button>
          <button className="px-4 py-2 border rounded">
            启用两步验证
          </button>
        </div>
      </Tabs.Content>

      <Tabs.Content value="notifications" className="p-4">
        <h3 className="text-lg font-medium mb-4">通知设置</h3>
        {/* 内容... */}
      </Tabs.Content>
    </Tabs.Root>
  )
}

import * as Tooltip from '@radix-ui/react-tooltip'

function TooltipDemo() {
  return (
    <Tooltip.Provider delayDuration={200}>
      <Tooltip.Root>
        <Tooltip.Trigger asChild>
          <button className="p-2 rounded hover:bg-gray-100">
            <HelpCircle className="w-5 h-5 text-gray-500" />
          </button>
        </Tooltip.Trigger>
        
        <Tooltip.Portal>
          <Tooltip.Content
            className="px-3 py-1.5 text-sm text-white bg-gray-900 rounded
              animate-in fade-in-0 zoom-in-95
              data-[side=top]:slide-in-from-bottom-2
              data-[side=bottom]:slide-in-from-top-2"
            sideOffset={5}
          >
            这是一个提示信息
            <Tooltip.Arrow className="fill-gray-900" />
          </Tooltip.Content>
        </Tooltip.Portal>
      </Tooltip.Root>
    </Tooltip.Provider>
  )
}

import * as Popover from '@radix-ui/react-popover'
import { Calendar } from 'lucide-react'

function DatePicker() {
  const [date, setDate] = useState<Date | null>(null)
  
  return (
    <Popover.Root>
      <Popover.Trigger asChild>
        <button className="flex items-center gap-2 px-3 py-2 border rounded
          hover:bg-gray-50">
          <Calendar className="w-4 h-4" />
          {date ? format(date, 'yyyy-MM-dd') : '选择日期'}
        </button>
      </Popover.Trigger>

      <Popover.Portal>
        <Popover.Content
          className="w-auto p-4 bg-white rounded-lg shadow-lg border
            animate-in fade-in-0 zoom-in-95"
          sideOffset={5}
        >
          {/* 日历组件 */}
          <CalendarComponent
            selected={date}
            onSelect={setDate}
          />
          
          <Popover.Arrow className="fill-white" />
        </Popover.Content>
      </Popover.Portal>
    </Popover.Root>
  )
}

import * as AlertDialog from '@radix-ui/react-alert-dialog'

function DeleteConfirm({ onConfirm }) {
  return (
    <AlertDialog.Root>
      <AlertDialog.Trigger asChild>
        <button className="px-4 py-2 bg-red-500 text-white rounded">
          删除账户
        </button>
      </AlertDialog.Trigger>

      <AlertDialog.Portal>
        <AlertDialog.Overlay className="fixed inset-0 bg-black/50" />
        
        <AlertDialog.Content
          className="fixed top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2
            w-[400px] bg-white rounded-lg p-6 shadow-xl"
        >
          <AlertDialog.Title className="text-lg font-semibold">
            确认删除账户？
          </AlertDialog.Title>
          
          <AlertDialog.Description className="mt-2 text-gray-600">
            此操作不可撤销。删除后，您的所有数据将被永久删除。
          </AlertDialog.Description>

          <div className="flex justify-end gap-3 mt-6">
            <AlertDialog.Cancel asChild>
              <button className="px-4 py-2 border rounded hover:bg-gray-50">
                取消
              </button>
            </AlertDialog.Cancel>
            
            <AlertDialog.Action asChild>
              <button
                onClick={onConfirm}
                className="px-4 py-2 bg-red-500 text-white rounded
                  hover:bg-red-600"
              >
                确认删除
              </button>
            </AlertDialog.Action>
          </div>
        </AlertDialog.Content>
      </AlertDialog.Portal>
    </AlertDialog.Root>
  )
}

import * as Dialog from '@radix-ui/react-dialog'
import { Command } from 'cmdk'  // 搭配 cmdk 库使用

function CommandPalette() {
  const [open, setOpen] = useState(false)
  
  // 快捷键监听
  useEffect(() => {
    const down = (e: KeyboardEvent) => {
      if (e.key === 'k' && (e.metaKey || e.ctrlKey)) {
        e.preventDefault()
        setOpen((open) => !open)
      }
    }
    document.addEventListener('keydown', down)
    return () => document.removeEventListener('keydown', down)
  }, [])

  return (
    <Dialog.Root open={open} onOpenChange={setOpen}>
      <Dialog.Portal>
        <Dialog.Overlay className="fixed inset-0 bg-black/50 backdrop-blur-sm" />
        
        <Dialog.Content
          className="fixed top-[20%] left-1/2 -translate-x-1/2
            w-[640px] bg-white rounded-xl shadow-2xl overflow-hidden"
        >
          <Command className="[&_[cmdk-input]]:px-4 [&_[cmdk-input]]:py-3">
            <Command.Input
              placeholder="输入命令或搜索..."
              className="w-full border-b outline-none"
            />
            
            <Command.List className="max-h-[300px] overflow-auto p-2">
              <Command.Empty className="p-4 text-center text-gray-500">
                未找到结果
              </Command.Empty>
              
              <Command.Group heading="导航">
                <Command.Item className="px-3 py-2 rounded cursor-pointer
                  data-[selected=true]:bg-blue-50">
                  🏠 首页
                </Command.Item>
                <Command.Item className="px-3 py-2 rounded cursor-pointer
                  data-[selected=true]:bg-blue-50">
                  📊 仪表盘
                </Command.Item>
              </Command.Group>
              
              <Command.Group heading="操作">
                <Command.Item className="px-3 py-2 rounded cursor-pointer
                  data-[selected=true]:bg-blue-50">
                  ➕ 新建文档
                </Command.Item>
                <Command.Item className="px-3 py-2 rounded cursor-pointer
                  data-[selected=true]:bg-blue-50">
                  🔍 搜索
                </Command.Item>
              </Command.Group>
            </Command.List>
          </Command>
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog.Root>
  )
}

import { unstable_PasswordToggleField as PasswordToggleField } from "radix-ui"
import { EyeOpenIcon, EyeClosedIcon } from "@radix-ui/react-icons"

function PasswordField() {
  return (
    <PasswordToggleField.Root>
      <PasswordToggleField.Input 
        placeholder="输入密码"
        className="px-3 py-2 border rounded"
      />
      <PasswordToggleField.Toggle className="absolute right-2 top-1/2 -translate-y-1/2">
        <PasswordToggleField.Icon
          visible={<EyeOpenIcon />}
          hidden={<EyeClosedIcon />}
        />
      </PasswordToggleField.Toggle>
    </PasswordToggleField.Root>
  )
}

import { unstable_OneTimePasswordField as OneTimePasswordField } from "radix-ui"

function OTPVerify() {
  return (
    <OneTimePasswordField.Root 
      onComplete={(value) => console.log('OTP:', value)}
    >
      <div className="flex gap-2">
        <OneTimePasswordField.Input className="w-12 h-12 text-center border rounded" />
        <OneTimePasswordField.Input className="w-12 h-12 text-center border rounded" />
        <OneTimePasswordField.Input className="w-12 h-12 text-center border rounded" />
        <span className="flex items-center">-</span>
        <OneTimePasswordField.Input className="w-12 h-12 text-center border rounded" />
        <OneTimePasswordField.Input className="w-12 h-12 text-center border rounded" />
        <OneTimePasswordField.Input className="w-12 h-12 text-center border rounded" />
      </div>
      <OneTimePasswordField.HiddenInput name="otp" />
    </OneTimePasswordField.Root>
  )
}

# 推荐：统一包（Tree-shakeable）
npm install radix-ui

# 不再推荐：单独安装
npm install @radix-ui/react-dialog @radix-ui/react-dropdown-menu

// ✅ 推荐：从统一包导入
import { Dialog, DropdownMenu, Tooltip } from "radix-ui"

// ⚠️ 旧方式：仍然支持，但不推荐
import * as Dialog from "@radix-ui/react-dialog"
import * as DropdownMenu from "@radix-ui/react-dropdown-menu"

// 常见错误：自定义组件没有 forwardRef
function MyButton({ children, ...props }) {
  return <button {...props}>{children}</button>
}

// ❗ 这样会出问题，因为 ref 不会传递
<Dialog.Trigger asChild>
  <MyButton>Open</MyButton>  {/* ref 丢失！ */}
</Dialog.Trigger>

// ✅ 正确做法：使用 forwardRef
const MyButton = React.forwardRef<HTMLButtonElement, ButtonProps>(
  ({ children, ...props }, ref) => {
    return <button ref={ref} {...props}>{children}</button>
  }
)

<Dialog.Trigger asChild>
  <MyButton>Open</MyButton>  {/* ref 正确传递 */}
</Dialog.Trigger>

/* tailwind.css */
@keyframes slideDown {
  from { opacity: 0; transform: translateY(-10px); }
  to { opacity: 1; transform: translateY(0); }
}

@keyframes slideUp {
  from { opacity: 1; transform: translateY(0); }
  to { opacity: 0; transform: translateY(-10px); }
}

.dropdown-content[data-state="open"] {
  animation: slideDown 200ms ease-out;
}

.dropdown-content[data-state="closed"] {
  animation: slideUp 200ms ease-in;
}

<DropdownMenu.Content
  className="data-[state=open]:animate-in data-[state=closed]:animate-out
    data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0
    data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95
    data-[side=bottom]:slide-in-from-top-2
    data-[side=top]:slide-in-from-bottom-2"
/>

import { AnimatePresence, motion } from 'framer-motion'

<Dialog.Root open={open} onOpenChange={setOpen}>
  <AnimatePresence>
    {open && (
      <Dialog.Portal forceMount>
        <Dialog.Content asChild>
          <motion.div
            initial={{ opacity: 0, scale: 0.95 }}
            animate={{ opacity: 1, scale: 1 }}
            exit={{ opacity: 0, scale: 0.95 }}
          >
            {/* content */}
          </motion.div>
        </Dialog.Content>
      </Dialog.Portal>
    )}
  </AnimatePresence>
</Dialog.Root>

// 问题：CSS 作用域限制，Portal 内容在 body 下，父组件样式不生效

// 方案 1：使用全局样式
// globals.css
[data-radix-portal] {
  /* 全局样式 */
}

// 方案 2：指定 Portal 容器
const [container, setContainer] = useState<HTMLElement | null>(null)

<div ref={setContainer}>
  <Dialog.Root>
    <Dialog.Portal container={container}>
      {/* 渲染到父容器内，样式作用域正常 */}
    </Dialog.Portal>
  </Dialog.Root>
</div>

// 方案 3：Tailwind 内联样式（推荐）
<Dialog.Content className="fixed ... bg-white rounded-lg">
  {/* Tailwind 不受作用域影响 */}
</Dialog.Content>

import * as Dialog from '@radix-ui/react-dialog'
import { ComponentPropsWithoutRef } from 'react'

// 获取组件的 Props 类型
type DialogContentProps = ComponentPropsWithoutRef<typeof Dialog.Content>

// 扩展组件
interface CustomDialogProps extends DialogContentProps {
  title: string
  description?: string
}

const CustomDialog = React.forwardRef<
  React.ElementRef<typeof Dialog.Content>,
  CustomDialogProps
>(({ title, description, children, ...props }, ref) => (
  <Dialog.Content ref={ref} {...props}>
    <Dialog.Title>{title}</Dialog.Title>
    {description && <Dialog.Description>{description}</Dialog.Description>}
    {children}
  </Dialog.Content>
))

// 使用
<CustomDialog
  title="确认删除"
  description="此操作不可撤销"
  onOpenAutoFocus={(e) => e.preventDefault()}
>
  {/* content */}
</CustomDialog>

// Radix 完全支持 SSR，但有些注意事项：

// 1. Portal 需要客户端渲染
function ClientOnlyDialog() {
  const [mounted, setMounted] = useState(false)
  
  useEffect(() => {
    setMounted(true)
  }, [])
  
  if (!mounted) return null
  
  return (
    <Dialog.Root>
      {/* ... */}
    </Dialog.Root>
  )
}

// 2. 使用 'use client' 指令 (Next.js App Router)
'use client'

import * as Dialog from '@radix-ui/react-dialog'

export function MyDialog() {
  // 客户端组件
}

// 3. Hydration 错误处理
// 如果遇到 hydration mismatch，检查：
// - 是否使用了服务器特定的值
// - Portal 容器是否在服务器端存在

import { render, screen } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import * as Dialog from '@radix-ui/react-dialog'

describe('Dialog', () => {
  it('应该能打开和关闭', async () => {
    const user = userEvent.setup()
    
    render(
      <Dialog.Root>
        <Dialog.Trigger>打开</Dialog.Trigger>
        <Dialog.Portal>
          <Dialog.Content>
            <Dialog.Title>标题</Dialog.Title>
            <Dialog.Close>关闭</Dialog.Close>
          </Dialog.Content>
        </Dialog.Portal>
      </Dialog.Root>
    )
    
    // Dialog 初始关闭
    expect(screen.queryByRole('dialog')).not.toBeInTheDocument()
    
    // 点击打开
    await user.click(screen.getByText('打开'))
    expect(screen.getByRole('dialog')).toBeInTheDocument()
    
    // ESC 关闭
    await user.keyboard('{Escape}')
    expect(screen.queryByRole('dialog')).not.toBeInTheDocument()
  })
  
  it('应该正确管理焦点', async () => {
    const user = userEvent.setup()
    
    render(
      <Dialog.Root>
        <Dialog.Trigger data-testid="trigger">打开</Dialog.Trigger>
        <Dialog.Portal>
          <Dialog.Content>
            <input data-testid="input" />
            <Dialog.Close>关闭</Dialog.Close>
          </Dialog.Content>
        </Dialog.Portal>
      </Dialog.Root>
    )
    
    const trigger = screen.getByTestId('trigger')
    await user.click(trigger)
    
    // 焦点应该移到 Dialog 内
    const input = screen.getByTestId('input')
    input.focus()
    expect(document.activeElement).toBe(input)
    
    // 关闭后焦点应该回到触发器
    await user.keyboard('{Escape}')
    expect(document.activeElement).toBe(trigger)
  })
})

// 创建一个支持两种模式的组件
interface ControlledDialogProps {
  // 受控 props
  open?: boolean
  onOpenChange?: (open: boolean) => void
  // 非受控 props
  defaultOpen?: boolean
  // 共同 props
  trigger: React.ReactNode
  children: React.ReactNode
}

function SmartDialog({
  open,
  onOpenChange,
  defaultOpen,
  trigger,
  children,
}: ControlledDialogProps) {
  // 判断是否受控
  const isControlled = open !== undefined
  
  return (
    <Dialog.Root
      // 受控模式
      {...(isControlled && {
        open,
        onOpenChange,
      })}
      // 非受控模式
      {...(!isControlled && {
        defaultOpen,
        onOpenChange,  // 仍然可以监听变化
      })}
    >
      <Dialog.Trigger asChild>{trigger}</Dialog.Trigger>
      <Dialog.Portal>
        <Dialog.Overlay className="fixed inset-0 bg-black/50" />
        <Dialog.Content className="fixed top-1/2 left-1/2 ...">
          {children}
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog.Root>
  )
}

// 使用方式 1：非受控
<SmartDialog
  defaultOpen={false}
  trigger={<Button>打开</Button>}
>
  内容
</SmartDialog>

// 使用方式 2：受控
const [open, setOpen] = useState(false)
<SmartDialog
  open={open}
  onOpenChange={setOpen}
  trigger={<Button>打开</Button>}
>
  内容
</SmartDialog>

npx shadcn-ui@latest init
npx shadcn-ui@latest add button dialog select

my-ui/
  components/
    button.tsx
    dialog.tsx
    select.tsx
  lib/
    utils.ts
  styles/
    globals.css

Prompt: "用 Radix Dialog 和 Tailwind 写一个确认删除对话框，
        要有警告图标、红色按钮、模糊背景"