# React
npm install @ark-ui/react
 
# Vue
npm install @ark-ui/vue
 
# Solid
npm install @ark-ui/solid
 
# Svelte
npm install @ark-ui/svelte

// React 示例
import { Dialog } from '@ark-ui/react/dialog'
import { Slider } from '@ark-ui/react/slider'
import { Tabs } from '@ark-ui/react/tabs'

import { Dialog } from '@ark-ui/react/dialog'
import { Portal } from '@ark-ui/react/portal'
 
export function MyDialog() {
  return (
    <Dialog.Root>
      <Dialog.Trigger asChild>
        <button>打开对话框</button>
      </Dialog.Trigger>
 
      <Portal>
        <Dialog.Backdrop className="dialog-backdrop" />
        <Dialog.Positioner className="dialog-positioner">
          <Dialog.Content className="dialog-content">
            <Dialog.Title>标题</Dialog.Title>
            <Dialog.Description>描述内容</Dialog.Description>
 
            <Dialog.CloseTrigger asChild>
              <button>关闭</button>
            </Dialog.CloseTrigger>
          </Dialog.Content>
        </Dialog.Positioner>
      </Portal>
    </Dialog.Root>
  )
}

<script setup>
import { Dialog } from '@ark-ui/vue/dialog'
import { Portal } from '@ark-ui/vue/portal'
</script>
 
<template>
  <Dialog.Root>
    <Dialog.Trigger asChild>
      <button>打开对话框</button>
    </Dialog.Trigger>
 
    <Portal>
      <Dialog.Backdrop class="dialog-backdrop" />
      <Dialog.Positioner class="dialog-positioner">
        <Dialog.Content class="dialog-content">
          <Dialog.Title>标题</Dialog.Title>
          <Dialog.Description>描述内容</Dialog.Description>
 
          <Dialog.CloseTrigger asChild>
            <button>关闭</button>
          </Dialog.CloseTrigger>
        </Dialog.Content>
      </Dialog.Positioner>
    </Portal>
  </Dialog.Root>
</template>

import { Dialog } from '@ark-ui/solid/dialog'
import { Portal } from '@ark-ui/solid/portal'
 
export function MyDialog() {
  return (
    <Dialog.Root>
      <Dialog.Trigger asChild>
        <button>打开对话框</button>
      </Dialog.Trigger>
 
      <Portal>
        <Dialog.Backdrop class="dialog-backdrop" />
        <Dialog.Positioner class="dialog-positioner">
          <Dialog.Content class="dialog-content">
            <Dialog.Title>标题</Dialog.Title>
            <Dialog.Description>描述内容</Dialog.Description>
 
            <Dialog.CloseTrigger asChild>
              <button>关闭</button>
            </Dialog.CloseTrigger>
          </Dialog.Content>
        </Dialog.Positioner>
      </Portal>
    </Dialog.Root>
  )
}

import { Slider } from '@ark-ui/react/slider'
import { useState } from 'react'
 
export function SliderDemo() {
  const [value, setValue] = useState([50])
 
  return (
    <Slider.Root
      value={value}
      onValueChange={(details) => setValue(details.value)}
      min={0}
      max={100}
    >
      <Slider.Label>音量</Slider.Label>
      <Slider.Control>
        <Slider.Track>
          <Slider.Range />
        </Slider.Track>
        <Slider.Thumb index={0} />
      </Slider.Control>
      <Slider.ValueText>{value[0]}%</Slider.ValueText>
    </Slider.Root>
  )
}

// Zag.js 状态机伪代码（以 NumberInput 为例）
import * as numberInput from '@zag-js/number-input'
 
// 1. 定义机器
const machine = numberInput.machine({
  context: { value: 0, min: 0, max: 100 },
})
 
// 2. 创建服务（框架适配层处理）
const service = useMachine(machine, { id: 'number-input' })
 
// 3. 连接为 API
const api = numberInput.connect(service, service, normalizeProps)
// api.value → 当前值
// api.increment() → 增加
// api.decrement() → 减少

// Slider 组件解剖
<Slider.Root data-scope="slider">
  <Slider.Label data-part="label">音量</Slider.Label>
  <Slider.Control data-part="control">
    <Slider.Track data-part="track">
      <Slider.Range data-part="range" />
    </Slider.Track>
    <Slider.Thumb data-part="thumb" data-index="0" />
  </Slider.Control>
  <Slider.ValueText data-part="value-text">50%</Slider.ValueText>
</Slider.Root>

// 非受控
<Dialog.Root defaultOpen={false}>
 
// 受控
<Dialog.Root open={isOpen} onOpenChange={(details) => setIsOpen(details.open)}>

// Tailwind CSS 样式化
<Dialog.Content
  data-state="open"
  className="fixed inset-0 z-50 bg-white rounded-lg shadow-xl
    data-[state=open]:animate-in data-[state=closed]:animate-out"
>

<Select.Root<{ items: Array<{ label: string; value: string }> }}>
  {/* 类型安全的 items 和 onValueChange */}
</Select.Root>

/* CSS 动画 */
[data-scope="dialog"][data-part="content"][data-state='open'] {
  animation: fadeIn 200ms ease-out;
}
[data-scope="dialog"][data-part="content"][data-state='closed'] {
  animation: fadeOut 200ms ease-in;
}

{
  "compilerOptions": {
    "strict": true,
    "jsx": "react-jsx",
    "moduleResolution": "bundler"
  }
}

import { render, screen } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import { Dialog } from '@ark-ui/react/dialog'
 
test('打开对话框', async () => {
  const user = userEvent.setup()
 
  render(
    <Dialog.Root>
      <Dialog.Trigger>打开</Dialog.Trigger>
      <Dialog.Positioner>
        <Dialog.Content>
          <Dialog.Title>标题</Dialog.Title>
          <Dialog.Description>描述内容</Dialog.Description>
        </Dialog.Content>
      </Dialog.Positioner>
    </Dialog.Root>
  )
 
  await user.click(screen.getByText('打开'))
  expect(screen.getByRole('dialog')).toBeInTheDocument()
})

// 使用 data 属性选择器
<Tabs.Root className="w-full">
  <Tabs.List className="flex border-b">
    <Tabs.Trigger
      value="tab1"
      className="px-4 py-2 data-[state=active]:border-b-2
        data-[state=active]:border-blue-500"
    >
      标签 1
    </Tabs.Trigger>
  </Tabs.List>
  <Tabs.Content value="tab1">内容 1</Tabs.Content>
</Tabs.Root>

import { defineSlotRecipe } from '@pandacss/dev'
 
const dialogRecipe = defineSlotRecipe({
  className: 'dialog',
  slots: ['trigger', 'backdrop', 'positioner', 'content', 'title', 'description', 'closeTrigger'],
  base: {
    backdrop: {
      bg: 'blackAlpha.600',
      backdropFilter: 'blur(4px)',
    },
    content: {
      bg: 'white',
      rounded: 'lg',
      shadow: 'xl',
      p: '6',
    },
    title: {
      fontSize: 'xl',
      fontWeight: 'bold',
    },
  },
})

/* 通过 data-scope 和 data-part 定位组件部件 */
[data-scope="slider"][data-part="track"] {
  height: 4px;
  background: #e2e8f0;
  border-radius: 2px;
}
 
[data-scope="slider"][data-part="range"] {
  background: #3b82f6;
  height: 100%;
  border-radius: 2px;
}
 
[data-scope="slider"][data-part="thumb"] {
  width: 16px;
  height: 16px;
  background: white;
  border: 2px solid #3b82f6;
  border-radius: 50%;
}
 
/* 通过 data-state 处理状态样式 */
[data-scope="dialog"][data-part="content"][data-state="open"] {
  opacity: 1;
  transform: scale(1);
}
 
[data-scope="dialog"][data-part="content"][data-state="closed"] {
  opacity: 0;
  transform: scale(0.95);
}

// 动态导入复杂组件
const DatePicker = lazy(() => import('./DatePicker'))

// 1. 检查 data 属性了解组件结构
// DevTools 中查看 data-scope、data-part、data-state
 
// 2. 状态机调试（开发环境）
// Zag.js 支持状态机日志输出
 
// 3. 检查 ARIA 属性
// 验证 role、aria-* 属性是否正确
 
// 4. 键盘导航测试
// Tab / Shift+Tab 焦点移动
// Enter / Space 触发操作
// Arrow 键导航列表
// Escape 关闭弹出层

import { axe, toHaveNoViolations } from 'jest-axe'
 
test('无可访问性违规', async () => {
  const { container } = render(
    <Dialog.Root open>
      <Dialog.Positioner>
        <Dialog.Content>
          <Dialog.Title>标题</Dialog.Title>
        </Dialog.Content>
      </Dialog.Positioner>
    </Dialog.Root>
  )
  const results = await axe(container)
  expect(results).toHaveNoViolations()
})

# Park UI 基于 Panda CSS
npm install @park-ui/react

// 推荐：使用 data-scope 和 data-part 组织样式
// CSS 文件按组件 scope 组织
// slider.css
[data-scope="slider"][data-part="root"] { ... }
[data-scope="slider"][data-part="track"] { ... }
[data-scope="slider"][data-part="range"] { ... }
[data-scope="slider"][data-part="thumb"] { ... }

// 推荐：使用 CSS 变量统一管理 z-index
// 所有浮层组件共享基础 z-index，通过 --layer-index 偏移
const zIndexVars = {
  '--layer-index': '1000',  // 基础层
}
 
// 避免：直接设置过高的 z-index
// 不要：style={{ zIndex: 99999 }}
 
// Portal 组件使用 --layer-index 偏移
<Portal style={{ '--layer-index': '100' }}>

// 封装通用的确认对话框
function ConfirmDialog({
  open,
  onOpenChange,
  title,
  description,
  onConfirm,
  children,
}: {
  open: boolean
  onOpenChange: (details: { open: boolean }) => void
  title: string
  description: string
  onConfirm: () => void
  children: React.ReactNode
}) {
  return (
    <Dialog.Root open={open} onOpenChange={onOpenChange}>
      <Portal>
        <Dialog.Backdrop />
        <Dialog.Positioner>
          <Dialog.Content>
            <Dialog.Title>{title}</Dialog.Title>
            <Dialog.Description>{description}</Dialog.Description>
            <div className="flex justify-end gap-2 mt-4">
              <Dialog.CloseTrigger asChild>
                <button>取消</button>
              </Dialog.CloseTrigger>
              <button onClick={onConfirm}>{children || '确认'}</button>
            </div>
          </Dialog.Content>
        </Dialog.Positioner>
      </Portal>
    </Dialog.Root>
  )
}

import { useForm, Controller } from 'react-hook-form'
import { Select } from '@ark-ui/react/select'
 
function FormWithSelect() {
  const { control, handleSubmit } = useForm()
 
  return (
    <form onSubmit={handleSubmit(data => console.log(data))}>
      <Controller
        name="category"
        control={control}
        render={({ field }) => (
          <Select.Root
            items={[
              { label: '技术', value: 'tech' },
              { label: '设计', value: 'design' },
            ]}
            value={[field.value]}
            onValueChange={(details) => field.onChange(details.value[0])}
          >
            <Select.Label>分类</Select.Label>
            <Select.Control>
              <Select.Trigger>
                <Select.ValueText placeholder="请选择" />
              </Select.Trigger>
            </Select.Control>
            <Portal>
              <Select.Positioner>
                <Select.Content>
                  {/* items 自动渲染 */}
                </Select.Content>
              </Select.Positioner>
            </Portal>
          </Select.Root>
        )}
      />
    </form>
  )
}

import { Presence } from '@ark-ui/react/presence'
import { useState } from 'react'
 
function AnimatedDialog() {
  const [open, setOpen] = useState(false)
 
  return (
    <>
      <button onClick={() => setOpen(true)}>打开</button>
 
      <Presence present={open}>
        <div
          data-state={open ? 'open' : 'closed'}
          className="dialog-content
            data-[state=open]:animate-in data-[state=open]:fade-in
            data-[state=closed]:animate-out data-[state=closed]:fade-out"
        >
          对话框内容
          <button onClick={() => setOpen(false)}>关闭</button>
        </div>
      </Presence>
    </>
  )
}