// 同一个「对话框」，四层工作在代码里的位置

// ① 自己写：只有开合，其余三层全缺
const [open, setOpen] = useState(false);
{open && <div className="modal">…</div>}   // 键盘能 Tab 出去、读屏器读不到、Esc 没反应

// ② 无头库：行为 + 无障碍 + 组合接口，样式归你
<Dialog.Root>
  <Dialog.Trigger>打开</Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Overlay className="fixed inset-0 bg-black/40" />   // 样式自己写
    <Dialog.Content className="fixed left-1/2 top-1/2 …">
      <Dialog.Title>标题</Dialog.Title>   // 自动接上 aria-labelledby
    </Dialog.Content>
  </Dialog.Portal>
</Dialog.Root>

// ③ 成套库：四层全包，代价是「长得像它」
<Dialog open={open} onClose={close}>
  <DialogTitle>标题</DialogTitle>                      // 视觉、动画、响应式都自带
</Dialog>

# 现查版本永远比记忆可靠：写代码前先跑这一行
$ npm view radix-ui version                 # 1.6.7
$ npm view @base-ui/react version           # 1.6.0
$ npm view element-plus version             # 2.14.3

# 已改名的包，registry 会直接告诉你
$ npm view @nextui-org/react deprecated
This package has been deprecated. Please use @heroui/react instead.

$ npm view @base-ui-components/react deprecated
Package was renamed to @base-ui/react

// 本页的章节地图（id 就是页面锚点）
00 全景        01 上手        02 三大流派      03 样式方案
04 设计令牌    05 无障碍      06 浮层与定位    07 对话框与焦点
08 表单        09 选择器族    10 表格与虚拟化  11 反馈与导航
12 动画        13 SSR/水合    14 体积与性能    15 国际化与 RTL
16 深水区      17 生态速查    18 自建组件库    19 测试与质量
20 路线图

// vite.config.js —— 路线 A 的完整配置就这么多
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import tailwindcss from "@tailwindcss/vite";
import path from "node:path";

export default defineConfig({
  plugins: [react(), tailwindcss()],
  resolve: {
    alias: { "@": path.resolve(import.meta.dirname, "./src") },  // shadcn 默认要这个别名
  },
});

/* src/index.css —— Tailwind 4 的全部引入代码 */
@import "tailwindcss";

import { Dialog } from "radix-ui";

export default function App() {
  return (
    <Dialog.Root>
      <Dialog.Trigger className="rounded bg-slate-900 px-4 py-2 text-white">
        打开对话框
      </Dialog.Trigger>

      <Dialog.Portal>                        {/* 渲染到 body 下，逃开父级的 overflow / transform */}
        <Dialog.Overlay className="fixed inset-0 bg-black/40" />
        <Dialog.Content
          className="fixed left-1/2 top-1/2 w-80 -translate-x-1/2 -translate-y-1/2 rounded-lg bg-white p-6 shadow-xl"
        >
          <Dialog.Title className="text-lg font-semibold">确认删除</Dialog.Title>
          <Dialog.Description className="mt-2 text-sm text-slate-600">
            删除后不可恢复。
          </Dialog.Description>
          <input className="mt-4 w-full rounded border p-2" placeholder="输入项目名以确认" />
          <Dialog.Close className="mt-4 rounded border px-3 py-1">取消</Dialog.Close>
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog.Root>
  );
}

// ① 缺 Provider —— 会直接抛
<Tooltip.Root>…</Tooltip.Root>             // Error: `Tooltip` must be used within `TooltipProvider`

// 正确：整个应用包一层，通常放在根组件
<Tooltip.Provider delayDuration={200}>
  <App />
</Tooltip.Provider>

// ③ 缺 Title —— 不报错，但读屏器读到一个无名对话框
<Dialog.Content>
  <p>确定要删除吗？</p>                       // 没有 Dialog.Title
</Dialog.Content>

// 修法之一：标题不想显示时，用视觉隐藏而不是删掉
<Dialog.Title className="sr-only">确认删除</Dialog.Title>   // 屏幕上不可见，读屏器能读到

// 三家成套库的「令牌层」定制，写法各不相同但意思一样

// MUI 9：createTheme + ThemeProvider
const theme = createTheme({
  palette: { primary: { main: "#7c3aed" }, mode: "dark" },
  shape: { borderRadius: 10 },
  components: { MuiButton: { defaultProps: { disableElevation: true } } },
});

// Ant Design 6：ConfigProvider + theme token
<ConfigProvider theme={{ token: { colorPrimary: "#7c3aed", borderRadius: 10 } }}>
  <App />
</ConfigProvider>

// Element Plus：直接覆盖 CSS 变量，连 JS 都不用改
:root {
  --el-color-primary: #7c3aed;
  --el-border-radius-base: 10px;
}

// 同一件事，四家的写法差异（都是「点开一个对话框」）

// Radix：Root/Trigger/Portal/Overlay/Content 五件套
<Dialog.Root><Dialog.Trigger/><Dialog.Portal><Dialog.Overlay/><Dialog.Content/></Dialog.Portal></Dialog.Root>

// Base UI：Backdrop / Popup 的命名不同，多一层 Positioner（浮层类才有）
<Dialog.Root><Dialog.Trigger/><Dialog.Portal><Dialog.Backdrop/><Dialog.Popup/></Dialog.Portal></Dialog.Root>

// Headless UI：状态自己管，open/onClose 是必填
<Dialog open={open} onClose={setOpen}><DialogPanel>…</DialogPanel></Dialog>

// React Aria：DialogTrigger 包住触发器与 Modal，默认不点外关闭
<DialogTrigger>
  <Button>打开</Button>
  <Modal isDismissable>                    // 不加这个属性，点遮罩不会关
    <Dialog>…</Dialog>
  </Modal>
</DialogTrigger>

# 初始化：生成 components.json，问你几个路径与主题问题
$ npx shadcn@latest init

# 加组件：源码直接落进 src/components/ui/
$ npx shadcn@latest add button dialog select

# 从任意 registry 加（公司内部私有源也一样）
$ npx shadcn@latest add https://example.com/r/our-table.json

# 想跟上游对齐时：重新 add，CLI 会问是否覆盖，然后自己 git diff
$ npx shadcn@latest add button --overwrite
$ git diff src/components/ui/button.tsx   # 人工判断哪些改动要留

/* 把层级收成一张表，两个库都听你的 */
:root {
  --z-dropdown: 1000;
  --z-sticky:   1020;
  --z-overlay:  1030;
  --z-modal:    1040;
  --z-toast:    1060;
}

/* 让第三方库的样式永远在自己的样式之下 */
@layer vendor, app;

@layer vendor {
  @import "element-plus/dist/index.css";
}
@layer app {
  .my-button { border-radius: 10px; }   /* 不用 !important 也能赢 */
}

// 薄封装让「换库」变成改一个文件

// src/components/ui/dialog.jsx —— 换库前（Radix）
import { Dialog as Rx } from "radix-ui";
export const Dialog = Rx.Root;
export const DialogTrigger = Rx.Trigger;
export function DialogContent({ children, ...rest }) { /* Portal + Overlay + Content */ }

// 换库后（Base UI）：业务代码一行不用改
import { Dialog as Bui } from "@base-ui/react/dialog";
export const Dialog = Bui.Root;
export const DialogTrigger = Bui.Trigger;
export function DialogContent({ children, ...rest }) { /* Portal + Backdrop + Popup */ }

// 前提：业务代码从来只写这一行 import
import { Dialog, DialogTrigger, DialogContent } from "@/components/ui/dialog";

/* Tailwind 4：配置写在 CSS 里，@theme 定义的变量同时就是 CSS 变量 */
@import "tailwindcss";

@theme {
  --color-brand-500: oklch(0.62 0.19 275);
  --radius-card: 12px;
}

/* 于是这两种写法等价，且能被任何非 Tailwind 的代码复用 */
.card { border-radius: var(--radius-card); }        /* 普通 CSS */
// <div className="rounded-card bg-brand-500">      // 工具类

/* 普通 CSS：跟着库的属性写 */
[data-state="open"] .dropdown-panel { opacity: 1; transform: none; }
[data-highlighted] { background: var(--color-accent-soft); }
[data-disabled] { opacity: 0.5; pointer-events: none; }
[data-side="top"] .arrow { rotate: 180deg; }

// Tailwind 4：同一件事写在类名里
<DropdownMenu.Content
  className="data-[state=open]:animate-in data-[state=closed]:animate-out
             data-[side=top]:slide-in-from-bottom-2"
/>

// Base UI 是无值属性，写法不同（照抄 Radix 会失效）
<Select.Popup className="data-open:opacity-100 data-closed:opacity-0" />

// cn()：clsx 负责拼接，tailwind-merge 负责让后来者赢
import clsx from "clsx";
import { twMerge } from "tailwind-merge";
export const cn = (...a) => twMerge(clsx(a));

cn("p-4 text-sm", "p-8");        // => "text-sm p-8"（p-4 被判定冲突并删掉）
clsx("p-4 text-sm", "p-8");      // => "p-4 text-sm p-8"（谁赢取决于 CSS 顺序）

/* @layer：把胜负从「特异性」改成「层序」 */
@layer reset, vendor, components, utilities;

@layer vendor  { .el-button { border-radius: 4px; } }
@layer components { .btn { border-radius: 12px; } }   /* 靠后的层赢，哪怕选择器更弱 */

/* 一个稳定的层序骨架，放在 CSS 入口最上面 */
@layer reset, vendor, tokens, components, utilities;

@layer reset  { /* normalize / preflight */ }
@layer vendor { /* 第三方库样式 */ }
@layer tokens { :root { --brand: oklch(0.62 0.19 275); } }
@layer components { .btn { background: var(--brand); } }

/* 提醒：不在任何层里的样式，优先级高于所有层 */
.legacy-hack { background: red; }   /* 这条会赢过上面所有层里的规则 */

/* ① 原始层：只有值，没有含义 */
:root {
  --blue-500:  oklch(0.62 0.19 250);
  --blue-300:  oklch(0.78 0.12 250);
  --gray-900:  oklch(0.21 0.01 260);
  --gray-50:   oklch(0.98 0.00 260);
  --space-4:   1rem;
}

/* ② 语义层：亮色下的指向 */
:root {
  --color-primary:     var(--blue-500);
  --color-on-primary:  var(--gray-50);
  --color-surface:     var(--gray-50);
  --color-text:        var(--gray-900);
}

/* ② 语义层：暗色只重新指向，原始层一个字都不动 */
[data-theme="dark"] {
  --color-primary:     var(--blue-300);
  --color-on-primary:  var(--gray-900);
  --color-surface:     var(--gray-900);
  --color-text:        var(--gray-50);
}

/* ③ 组件层：对外的定制接口 */
.btn {
  --btn-bg: var(--color-primary);
  background: var(--btn-bg);
  color: var(--color-on-primary);
}

/* Tailwind 4：@theme 里的令牌同时是变量与工具类 */
@import "tailwindcss";

@theme {
  --color-brand-500: oklch(0.62 0.19 275);
  --color-brand-600: oklch(0.55 0.20 275);
  --radius-card: 12px;
}

/* 语义层放 :root，运行时可被 JS 改写 */
:root {
  --color-primary: var(--color-brand-500);
  --color-surface: white;
}

/* 让第三方库跟着你的语义层走，而不是各改各的 */
:root {
  --el-color-primary: var(--color-primary);          /* Element Plus */
  --mantine-primary-color-filled: var(--color-primary); /* Mantine */
}

// 运行时换主题：一行，不触发任何组件重渲染
document.documentElement.style.setProperty("--color-primary", userColor);

<!-- 放进 <head>，必须同步内联执行 -->
<script>
  (function () {
    var saved = localStorage.getItem("theme");
    var sysDark = matchMedia("(prefers-color-scheme: dark)").matches;
    var theme = saved || (sysDark ? "dark" : "light");
    document.documentElement.dataset.theme = theme;
    document.documentElement.style.colorScheme = theme;   // 滚动条与原生控件跟着变
  })();
</script>

/* CSS 侧：语义层按主题重新指向即可 */
:root { color-scheme: light; --color-surface: oklch(0.98 0 0); --color-text: oklch(0.21 0 0); }
[data-theme="dark"] { color-scheme: dark; --color-surface: oklch(0.21 0 0); --color-text: oklch(0.98 0 0); }

/* 想同时支持「跟随系统」：把系统查询也写一份 */
@media (prefers-color-scheme: dark) {
  :root:not([data-theme]) { color-scheme: dark; --color-surface: oklch(0.21 0 0); }
}

/* 一套语义层，多个品牌各自重新指向 */
[data-brand="acme"]  { --brand: oklch(0.62 0.19 275); --radius-card: 12px; }
[data-brand="globex"] { --brand: oklch(0.70 0.15 145); --radius-card: 2px; }

/* 派生：不要让用户选七个颜色 */
:root {
  --color-primary:       var(--brand);
  --color-primary-hover: color-mix(in oklch, var(--brand) 88%, black);
  --color-primary-soft:  color-mix(in oklch, var(--brand) 12%, white);
}

// 用户自选主色时的对比度兜底（简化版判据）
function onPrimary(l) {                 // l = OKLCH 的亮度分量 0~1
  return l > 0.65 ? "var(--gray-900)" : "var(--gray-50)";
}

// tokens/color.json —— 向 W3C Design Tokens 规范靠拢的写法
{
  "color": {
    "brand":   { "500": { "$type": "color", "$value": "oklch(0.62 0.19 275)" } },
    "primary": { "$type": "color", "$value": "{color.brand.500}" }
  }
}

// style-dictionary 配置：一份源，多份产物
export default {
  source: ["tokens/**/*.json"],
  platforms: {
    css: {
      transformGroup: "css",
      buildPath: "src/styles/",
      files: [{ destination: "tokens.css", format: "css/variables" }],
    },
  },
};

/* 产物 src/styles/tokens.css（提交进仓库，别手改） */
:root {
  --color-brand-500: oklch(0.62 0.19 275);
  --color-primary: var(--color-brand-500);
}

// roving tabindex 的最小实现（理解原理用；实际请用库）
function onKeyDown(e) {
  const items = [...list.querySelectorAll('[role="option"]')];
  const i = items.indexOf(document.activeElement);
  let next = i;
  if (e.key === "ArrowDown") next = Math.min(i + 1, items.length - 1);
  if (e.key === "ArrowUp")   next = Math.max(i - 1, 0);
  if (e.key === "Home")      next = 0;
  if (e.key === "End")       next = items.length - 1;
  if (next !== i) {
    e.preventDefault();                 // 阻止方向键滚动页面
    items[i].tabIndex = -1;               // 只有一个项参与 Tab 序列
    items[next].tabIndex = 0;
    items[next].focus();
  }
}

/* 焦点可见：别删 outline，换一个更好看的 */
:focus-visible {
  outline: 2px solid var(--color-primary);
  outline-offset: 2px;
}

<!-- 图标按钮：名字 + 图标对读屏器隐藏 -->
<button aria-label="删除这一行">
  <svg aria-hidden="true" …></svg>
</button>

<!-- 想视觉隐藏标题但保留语义：用 sr-only，别用 display:none -->
<Dialog.Title className="sr-only">确认删除订单</Dialog.Title>

<!-- 表单控件：三种合规写法 -->
<label for="email">邮箱</label><input id="email" />      <!-- 最好，点标签能聚焦输入框 -->
<label>邮箱<input /></label>                              <!-- 包裹式，也行 -->
<input aria-label="邮箱" />                             <!-- 无可见标签时才用 -->

// 自查：在控制台里读出某个元素的可访问名
$0.getAttribute("aria-label") ?? document.getElementById($0.getAttribute("aria-labelledby"))?.textContent;

<!-- 现代做法：外面 inert，一个属性搞定三件事 -->
<div id="app" inert>…页面正文…</div>
<div role="dialog" aria-labelledby="t">
  <h2 id="t">确认删除</h2>
</div>

// 原生 dialog：焦点陷阱、Esc、top layer、backdrop 全都免费
const dlg = document.querySelector("dialog");
dlg.showModal();                 // 注意：show() 是非模态，没有以上任何一条
dlg.addEventListener("close", () => restoreFocus());

/* 遮罩用伪元素，不需要额外 DOM */
dialog::backdrop { background: rgb(0 0 0 / 0.4); }

<!-- ① 原生优先：这两行等价，但左边免费得到所有键盘行为 -->
<button type="button" onclick="…">保存</button>
<div role="button" tabindex="0" onclick="…" onkeydown="…">保存</div>   <!-- 还要处理 Enter/Space -->

<!-- ② 状态属性要真的跟着状态走 -->
<button aria-expanded="true" aria-controls="panel-1">详情</button>
<div id="panel-1">…</div>

<!-- ③ live region：容器先在，内容后填 -->
<div id="status" aria-live="polite" class="sr-only"></div>
// 之后：
document.getElementById("status").textContent = "已保存 3 条记录";

/* 用库暴露的变量写「不撑破屏幕的下拉」 */
.dropdown-content {
  max-height: var(--radix-popover-content-available-height);
  overflow-y: auto;
  width: var(--radix-popover-trigger-width);          /* 宽度对齐触发器 */
  transform-origin: var(--radix-popover-content-transform-origin);  /* 动画从正确的角落展开 */
}

// 直接用 Floating UI 时的最小配置（自研组件才需要）
import { computePosition, offset, flip, shift, size, autoUpdate } from "@floating-ui/dom";

autoUpdate(trigger, panel, () => {
  computePosition(trigger, panel, {
    placement: "bottom-start",
    middleware: [
      offset(8),
      flip(),                                     // 放不下就翻面
      shift({ padding: 8 }),                      // 贴边时平移，留 8px 余量
      size({
        apply({ availableHeight, elements }) {
          elements.floating.style.maxHeight = availableHeight + "px";
        },
      }),
    ],
  }).then(({ x, y }) => Object.assign(panel.style, { left: x + "px", top: y + "px" }));
});

// 症状与判据：在 DevTools 控制台里找出困住浮层的祖先
let n = $0;                                  // $0 = 当前选中的浮层元素
while ((n = n.parentElement)) {
  const s = getComputedStyle(n);
  if (
    s.transform !== "none" || s.filter !== "none" ||
    s.contain !== "none" || s.willChange !== "auto" ||
    s.overflow !== "visible" || (s.position !== "static" && s.zIndex !== "auto")
  ) {
    console.log("嫌疑祖先：", n, s.transform, s.overflow, s.zIndex);
  }
}

// 解法：套 Portal（各库写法）
<Popover.Portal>…</Popover.Portal>              // Radix / Base UI
<el-select :teleported="true" />                  // Element Plus（默认就是 true）
<Select getPopupContainer={() => document.body} />  // antd

// Tooltip 的延迟配置：全局一次，别每个都写
<Tooltip.Provider delayDuration={500} skipDelayDuration={200}>
  <App />                     // 首次悬停等 500ms；200ms 内移到下一个则立即显示
</Tooltip.Provider>

// 路由跳转时关闭浮层（最容易漏的一条）
useEffect(() => { setOpen(false); }, [pathname]);

// 需要拦住「点外部关闭」时（比如点到了自己的另一个浮层里）
<Popover.Content
  onInteractOutside={(e) => {
    if (e.target.closest("[data-my-datepicker]")) e.preventDefault();
  }}
/>

// 跨库嵌套的标准修法：把内层的 DOM 也算作「内部」
<Popover.Content
  onPointerDownOutside={(e) => {
    const t = e.target;
    // 内层日期面板被 portal 到了 body，这里手动放行
    if (t.closest(".el-picker__popper, .ant-picker-dropdown")) e.preventDefault();
  }}
  onFocusOutside={(e) => e.preventDefault()}      // 焦点跑进内层时也别关
>
  <DatePicker />
</Popover.Content>

// 另一条路：让内层别 portal 出去（各库的写法）
<el-date-picker :teleported="false" />
<DatePicker getPopupContainer={(node) => node.parentElement} />

<!-- 零 JS 的浮层：popover + anchor positioning -->
<button popovertarget="menu" style="anchor-name: --btn">菜单</button>

<div id="menu" popover>
  <a href="#">设置</a>
</div>

<style>
  #menu {
    position-anchor: --btn;
    position-area: bottom span-right;      /* 锚点下方、向右展开 */
    position-try-fallbacks: flip-block;    /* 放不下就翻到上面 —— 原生版 flip */
    margin: 6px 0 0;
  }
  /* 进场动画：popover 从 display:none 变过来，需要这两样 */
  #menu { opacity: 0; transition: opacity 0.15s, display 0.15s allow-discrete; }
  #menu:popover-open { opacity: 1; }
  @starting-style { #menu:popover-open { opacity: 0; } }
</style>

// 指定初始焦点：确认类对话框应当聚焦「取消」而不是「删除」
<Dialog.Content
  onOpenAutoFocus={(e) => {
    e.preventDefault();                 // 阻止默认的「第一个可聚焦元素」
    cancelRef.current?.focus();
  }}
>
  <Dialog.Title>删除这个项目？</Dialog.Title>
  <button ref={cancelRef}>取消</button>
  <button className="danger">删除</button>
</Dialog.Content>

// 关闭后想把焦点给别处（比如刚新建的那一行）
<Dialog.Content onCloseAutoFocus={(e) => { e.preventDefault(); newRowRef.current?.focus(); }} />

/* 自己实现时的最小版本：锁 + 补偿 */
function lockScroll() {
  const gap = window.innerWidth - document.documentElement.clientWidth;  // 滚动条宽度
  document.body.style.overflow = "hidden";
  if (gap > 0) document.body.style.paddingRight = gap + "px";
  return () => {                                // 解锁：把改过的都还原
    document.body.style.overflow = "";
    document.body.style.paddingRight = "";
  };
}

/* 更现代的做法：一开始就给页面留出滚动条槽位，锁的时候就不会跳 */
html { scrollbar-gutter: stable; }

/* 固定定位的元素（顶栏、悬浮按钮）也要一起补偿，否则只有它们会跳 */
body[data-scroll-locked] .fixed-header { padding-right: var(--removed-scrollbar-size, 0); }

<!-- 原生对话框的完整可用版本 -->
<dialog id="dlg" aria-labelledby="dlg-title">
  <h2 id="dlg-title">确认删除</h2>
  <form method="dialog">               <!-- method="dialog" 的按钮会直接关闭 -->
    <button value="cancel">取消</button>
    <button value="ok">删除</button>
  </form>
</dialog>

// 打开、读返回值、点遮罩关闭（后者要自己写）
dlg.showModal();
dlg.addEventListener("close", () => console.log(dlg.returnValue));   // "ok" / "cancel"
dlg.addEventListener("click", (e) => {
  if (e.target === dlg) dlg.close();    // 点到 dialog 本身 = 点在了 backdrop 上
});

/* 遮罩与动画 */
dialog::backdrop { background: rgb(0 0 0 / 0.4); }
dialog { opacity: 0; transition: opacity .2s, overlay .2s allow-discrete, display .2s allow-discrete; }
dialog[open] { opacity: 1; }
@starting-style { dialog[open] { opacity: 0; } }

// 确认框：禁止点外部关闭（Radix）
<AlertDialog.Content
  onInteractOutside={(e) => e.preventDefault()}
  onEscapeKeyDown={(e) => e.preventDefault()}     // 需要时连 Esc 也拦（慎用）
>

// Radix 专门提供了 AlertDialog：它与 Dialog 的差别正是「确认语义」
//   role="alertdialog"、必须有 Action 与 Cancel、默认焦点在 Cancel 上

// 抽屉的响应式模式：窄屏模态、宽屏常驻
const isNarrow = useMediaQuery("(max-width: 768px)");
return isNarrow
  ? <Drawer open={open} onOpenChange={setOpen}>{nav}</Drawer>
  : <aside className="w-64 border-r">{nav}</aside>;

// 非受控：值在 DOM 里，提交时一把读出来
<form onSubmit={(e) => {
  e.preventDefault();
  const data = Object.fromEntries(new FormData(e.currentTarget));
  save(data);                                  // { email: "...", plan: "pro" }
}}>
  <input name="email" defaultValue="" />
</form>

// 受控：需要联动时才这么写
const [country, setCountry] = useState("");
<select value={country} onChange={(e) => { setCountry(e.target.value); setCity(""); }}>…</select>

// 混合模式的库组件：传了就受控，不传自己管（16 章讲实现）
<Select.Root defaultValue="pro">                 // 非受控
<Select.Root value={plan} onValueChange={setPlan}> // 受控

// 给无头组件传 name，它才会渲染隐藏的原生控件
<Select.Root name="plan" defaultValue="pro">…</Select.Root>
<Checkbox.Root name="agree" value="yes">…</Checkbox.Root>

// 对话框底部的提交按钮在 form 外面：用 form 属性关联回去
<form id="profile-form" onSubmit={onSubmit}>…</form>
<Dialog.Footer>
  <button type="button">取消</button>
  <button type="submit" form="profile-form">保存</button>   // 关键：form="…"
</Dialog.Footer>

// 表单里的非提交按钮，一定要写 type="button"
<button type="button" onClick={addRow}>添加一行</button>

// zod 4 + react-hook-form：schema 一份，类型与校验都从它来
import { z } from "zod";
import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";

const schema = z.object({
  email: z.email("请填写有效的邮箱"),
  age: z.coerce.number().int().min(18, "必须年满 18 岁"),
});

const { register, handleSubmit, formState: { errors, isSubmitting } } = useForm({
  resolver: zodResolver(schema),
  mode: "onTouched",          // 失焦后才首次校验，之后实时更新
});

<form onSubmit={handleSubmit(save)} noValidate>   // noValidate：关掉浏览器默认气泡
  <input {...register("email")} type="email" autoComplete="email" />
  {errors.email && <p role="alert">{errors.email.message}</p>}
</form>

<!-- 完整的一个字段：标签、帮助文字、错误、三个 aria 属性 -->
<label for="pwd">新密码</label>
<input
  id="pwd"
  type="password"
  autocomplete="new-password"
  aria-invalid={hasError}
  aria-describedby="pwd-help pwd-err"       <!-- 可以指向多个 id -->
/>
<p id="pwd-help">至少 12 位，含数字与符号</p>
{hasError && <p id="pwd-err" role="alert">密码太短了</p>}

// 提交失败：焦点移到第一个错误字段（RHF 内置了这个能力）
useForm({ shouldFocusError: true });     // 默认就是 true，别关掉

// 自己实现时
const first = document.querySelector("[aria-invalid='true']");
first?.focus();

// 数组字段：key 用稳定 id，不要用下标
const { fields, append, remove } = useFieldArray({ control, name: "items" });

{fields.map((field, i) => (
  <div key={field.id}>                       // ← field.id 稳定；写 key={i} 会错位
    <input {...register(`items.${i}.name`)} />
    <button type="button" onClick={() => remove(i)}>删除</button>
  </div>
))}

// 只订阅需要的字段，避免整表重渲染
const country = useWatch({ control, name: "country" });   // 只有这里会因 country 变化而重渲染

// 提交四态
<button type="submit" disabled={isSubmitting} aria-busy={isSubmitting}>
  {isSubmitting ? "保存中…" : "保存"}
</button>

<!-- Select：按钮触发，焦点可以进列表 -->
<button role="combobox" aria-expanded="true" aria-controls="lb" aria-haspopup="listbox">专业版</button>
<div id="lb" role="listbox">
  <div role="option" aria-selected="true" tabindex="0">专业版</div>
  <div role="option" aria-selected="false" tabindex="-1">企业版</div>
</div>

<!-- Combobox：焦点必须留在 input，用 activedescendant 指高亮项 -->
<input
  role="combobox"
  aria-expanded="true"
  aria-controls="lb2"
  aria-autocomplete="list"
  aria-activedescendant="opt-2"       <!-- 指向当前高亮的那一项 -->
/>
<div id="lb2" role="listbox">
  <div id="opt-2" role="option" aria-selected="false">企业版</div>
</div>

<!-- 原生：简单场景的最优解 -->
<label for="plan">套餐</label>
<select id="plan" name="plan">
  <option value="free">免费版</option>
  <option value="pro" selected>专业版</option>
</select>

/* 只改触发器外观，仍然是原生 select（今天普遍可用的程度） */
select {
  appearance: none;                 /* 去掉系统箭头 */
  background: url("data:image/svg+xml,…") no-repeat right 8px center;
  padding-right: 28px;
}

// 响应式：窄屏用原生，宽屏用自定义
{isNarrow ? <select name="plan">…</select> : <Select.Root name="plan">…</Select.Root>}

// 异步搜索：防抖 + 取消 + 回显缓存
const ctrl = useRef(null);

async function search(q) {
  ctrl.current?.abort();                       // 取消上一次，避免竞态
  ctrl.current = new AbortController();
  try {
    const res = await fetch("/api/users?q=" + encodeURIComponent(q), { signal: ctrl.current.signal });
    setOptions(await res.json());
  } catch (e) {
    if (e.name !== "AbortError") setError(e);      // 取消不算错误
  }
}

<!-- 虚拟化列表的无障碍补丁：告诉读屏器真实总数 -->
<div role="listbox" aria-busy={loading}>
  {visible.map((item, i) => (
    <div role="option" aria-setsize={total} aria-posinset={item.index + 1} key={item.id}>…</div>
  ))}
</div>

// 展示：交给 Intl，别手拼
new Intl.DateTimeFormat("zh-CN", {
  dateStyle: "long", timeStyle: "short", timeZone: "Asia/Shanghai",
}).format(new Date(iso));          // "2026年3月5日 09:00"

// 一周从哪天开始，也别写死（各地区不同）
new Intl.Locale("en-US").getWeekInfo?.().firstDay;   // 7（周日）；zh-CN 是 1（周一）

// 纯日期字段：字符串进、字符串出，别经手 Date 对象
{ birthday: "2001-03-05" }                    // 对
{ birthday: new Date("2001-03-05") }          // 错：会被解释成 UTC 午夜，东八区显示成 3 月 5 日 08:00，
                                              //     在西半球的用户那里会变成 3 月 4 日

// 多选的隐藏 input：每个已选项一个，同名
{selected.map((v) => <input key={v} type="hidden" name="tags" value={v} />)}
// 服务端 / FormData 侧：
new FormData(form).getAll("tags");        // ["react", "vue"]

// 输入框最左端按退格删最后一个标签
function onKeyDown(e) {
  if (e.key === "Backspace" && e.target.selectionStart === 0 && e.target.selectionEnd === 0) {
    removeLast();
  }
}

<!-- 每个标签是一个可聚焦的元素，删除按钮要有名字 -->
<span role="option" aria-selected="true" tabindex="-1">
  React
  <button type="button" aria-label="移除 React">×</button>
</span>

// TanStack Table：只有状态与模型，DOM 全归你
const table = useReactTable({
  data, columns,
  getCoreRowModel: getCoreRowModel(),
  getSortedRowModel: getSortedRowModel(),      // 客户端排序
  manualPagination: true,                     // 分页交给服务端
  state: { sorting, pagination },
  onSortingChange: setSorting,
});

<table>
  <thead>{table.getHeaderGroups().map((hg) => (
    <tr key={hg.id}>{hg.headers.map((h) => (
      <th key={h.id} aria-sort={h.column.getIsSorted() === "asc" ? "ascending" : "none"}>
        <button onClick={h.column.getToggleSortingHandler()}>{h.column.columnDef.header}</button>
      </th>
    ))}</tr>
  ))}</thead>
  <tbody>{table.getRowModel().rows.map((row) => (
    <tr key={row.id}>{row.getVisibleCells().map((c) => <td key={c.id}>{render(c)}</td>)}</tr>
  ))}</tbody>
</table>

// TanStack Virtual：估高 + 动态测量
const rowVirtualizer = useVirtualizer({
  count: rows.length,
  getScrollElement: () => parentRef.current,
  estimateSize: () => 44,                 // 先给个估计值
  measureElement: (el) => el.getBoundingClientRect().height,  // 渲染后修正
  overscan: 8,                            // 上下各多渲染几行，减少空白闪烁
});

<div ref={parentRef} style={{ height: 600, overflow: "auto" }} role="grid" aria-rowcount={rows.length}>
  <div style={{ height: rowVirtualizer.getTotalSize(), position: "relative" }}>
    {rowVirtualizer.getVirtualItems().map((v) => (
      <div
        key={v.key}
        role="row"
        aria-rowindex={v.index + 1}          // 告诉读屏器真实序号
        style={{ position: "absolute", top: 0, transform: `translateY(${v.start}px)` }}
      >…</div>
    ))}
  </div>
</div>

/* 粘性表头 + 左固定列 */
.table-wrap { overflow: auto; max-height: 70vh; }      /* 滚动容器 */

th { position: sticky; top: 0; z-index: 2; background: var(--color-surface); }
.col-fixed { position: sticky; left: 0; z-index: 1; background: var(--color-surface); }
th.col-fixed { z-index: 3; }                           /* 左上角要压过两者 */

/* 横向可滚动时给个阴影提示，滚到头自动消失 */
.table-wrap { background:
  linear-gradient(to right, var(--color-surface) 30%, transparent),
  linear-gradient(to right, rgb(0 0 0 / .12), transparent 12px) 0 0 / 12px 100% no-repeat;
  background-attachment: local, scroll;
}

/* 窄屏堆叠：不用换组件，用 data-label 显示列名 */
@media (max-width: 640px) {
  thead { display: none; }
  tr { display: block; margin-bottom: 12px; }
  td { display: flex; justify-content: space-between; }
  td::before { content: attr(data-label); font-weight: 600; }
}

<!-- 语义完整的表格骨架 -->
<table>
  <caption class="sr-only">2026 年 3 月订单列表，共 128 条</caption>
  <thead>
    <tr>
      <th scope="col">
        <input type="checkbox" aria-label="全选本页" />
      </th>
      <th scope="col" aria-sort="ascending">
        <button>下单时间</button>              <!-- 可聚焦的是按钮，不是 th -->
      </th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><input type="checkbox" aria-label="选择订单 A1024" /></td>
      <th scope="row">A1024</th>              <!-- 行头：读单元格时会带上它 -->
    </tr>
  </tbody>
</table>

// 全选框的三态
checkbox.indeterminate = selected.length > 0 && selected.length < rows.length;

<!-- 容器常驻，内容后填（这一条决定了会不会被播报） -->
<div id="toast-region" role="status" aria-live="polite" aria-atomic="true"></div>

// Sonner：三行接入
import { Toaster, toast } from "sonner";
<Toaster richColors closeButton />                 // 放在应用根部，只放一次
toast.success("已保存", { action: { label: "撤销", onClick: undo } });

// 悬停暂停计时（自己实现时别忘了）
onMouseEnter: () => clearTimeout(timer.current),
onMouseLeave: () => { timer.current = setTimeout(dismiss, remaining); },

/* 尊重系统的「减少动态效果」设置 */
@media (prefers-reduced-motion: reduce) {
  .toast { animation: none; }
}

<!-- 完整的属性关联 -->
<div role="tablist" aria-label="账户设置">
  <button role="tab" id="t1" aria-selected="true"  aria-controls="p1" tabindex="0">资料</button>
  <button role="tab" id="t2" aria-selected="false" aria-controls="p2" tabindex="-1">安全</button>
</div>
<div role="tabpanel" id="p1" aria-labelledby="t1" tabindex="0">…</div>

// 内容重时用手动激活，避免方向键连续触发加载
<Tabs.Root activationMode="manual">…</Tabs.Root>

// 把当前 tab 同步到 URL，刷新与分享才不丢状态
<Tabs.Root value={tab} onValueChange={(v) => setSearchParams({ tab: v })}>

<!-- 导航：链接列表，不是 menu -->
<nav aria-label="主导航">
  <ul>
    <li><a href="/docs" aria-current="page">文档</a></li>
    <li><a href="/blog">博客</a></li>
  </ul>
</nav>

<!-- 跳过导航：页面最前面，聚焦时才显示 -->
<a href="#main" class="skip-link">跳到主内容</a>

<!-- Disclosure：原生就够了，还能被 Ctrl+F 搜到 -->
<details>
  <summary>运费怎么算？</summary>
  <p>满 99 元包邮…</p>
</details>

/* 跳过链接的标准写法 */
.skip-link { position: absolute; left: -9999px; }
.skip-link:focus { left: 8px; top: 8px; z-index: 100; }

/* ① Radix presence：必须用 animation 而不是 transition */
[data-state="open"]  { animation: fadeIn 150ms ease-out; }
[data-state="closed"] { animation: fadeOut 120ms ease-in; }   /* 库会等它播完再卸载 */

@keyframes fadeIn  { from { opacity: 0; transform: scale(.96); } }
@keyframes fadeOut { to   { opacity: 0; transform: scale(.96); } }

/* ④ 原生：连 display 与 top layer 的进出都能过渡 */
dialog {
  opacity: 0;
  transition: opacity .2s, display .2s allow-discrete, overlay .2s allow-discrete;
}
dialog[open] { opacity: 1; }
@starting-style { dialog[open] { opacity: 0; } }   /* 进场的起始值 */

// ③ React + Motion
<AnimatePresence>
  {open && <motion.div initial={{ opacity: 0 }} animate={{ opacity: 1 }} exit={{ opacity: 0 }} />}
</AnimatePresence>

/* 全局兜底：把位移换成淡入淡出，而不是一刀切关掉 */
@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: .01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: .01ms !important;
    scroll-behavior: auto !important;
  }
}

/* 手风琴的高度动画：库把测量结果放进 CSS 变量 */
@keyframes slideDown {
  from { height: 0; }
  to   { height: var(--radix-accordion-content-height); }
}
[data-state="open"] .accordion-content { animation: slideDown 180ms ease-out; }

// JS 侧也要能读到这个设置（比如决定要不要做滚动动画）
const reduce = matchMedia("(prefers-reduced-motion: reduce)").matches;
element.scrollIntoView({ behavior: reduce ? "auto" : "smooth" });

// 稳定 id：用框架的，别自己造
const id = useId();                         // React 18+ / Vue 3.5+
<label htmlFor={id}>邮箱</label><input id={id} />

// 响应式切换：优先用 CSS，而不是 JS 判断
<div className="md:hidden"><Drawer /></div>      // 两端渲染一致，靠 CSS 决定谁可见
<div className="hidden md:block"><Sidebar /></div>

// 不得不用 JS 时：先渲染服务端版本，挂载后再切
const [mounted, setMounted] = useState(false);
useEffect(() => setMounted(true), []);
if (!mounted) return <SkeletonOrServerVersion />;   // 代价：会闪一下

// ❌ 错：整页变成客户端组件
"use client";
export default async function Page() { … }

// ✅ 对：边界下沉到叶子，children 仍然是服务端渲染的
// app/page.jsx（服务端组件）
import { Tabs } from "@/components/ui/tabs";   // 里面有 "use client"

export default async function Page() {
  const data = await db.query(…);            // 服务端取数，不下发到浏览器
  return (
    <Tabs defaultValue="a">
      <TabPanel value="a">
        <HeavyServerRenderedTable data={data} />   // 作为 children 传入，仍在服务端渲染
      </TabPanel>
    </Tabs>
  );
}

<!-- Nuxt：只在客户端渲染的部分 -->
<ClientOnly>
  <ThemeToggle />
  <template #fallback><div class="h-9 w-9" /></template>   <!-- 占位，避免布局跳动 -->
</ClientOnly>

<!-- Teleport：SSR 时可以按需关掉 -->
<Teleport to="body" :disabled="!isMounted">
  <div class="modal">…</div>
</Teleport>

// 语言/主题这类「服务端已知」的信息，直接写进 HTML 属性
// 服务端：<html lang="zh-CN" data-theme="dark" dir="ltr">
// 客户端：读属性即可，不需要二次判断，也就不会不匹配

# 自己量一遍，比抄任何表格都可靠（三条命令）
$ npm create vite@latest size-test -- --template react
$ npm i <要测的库> && npm run build

# Vite 构建后会直接打印每个产物的 gzip 大小
dist/assets/index-XXXX.js   223.31 kB │ gzip: 69.94 kB

# 想看是谁贡献的体积：
$ npx vite-bundle-visualizer          # 或 rollup-plugin-visualizer

# 只想快速查单个包的体积量级（不含你的用法差异）
# 网站 bundlephobia.com 输入包名即可，但它测的是「整包」，
# 与 tree-shaking 后的真实增量差别可能很大 —— 以自己构建的结果为准

// 三种写法，三种代价
import clsx from "clsx";                          // ~0.05 KB
import { twMerge } from "tailwind-merge";           // ~8 KB —— 这是大头

export const cn = (...a) => twMerge(clsx(a));         // shadcn 默认
export const cn = (...a) => clsx(a);                  // 不需要外部覆盖时够用

/* 用 CSS 层解决冲突，就不需要在 JS 里删类名 */
@layer components, overrides;
@layer components { .btn { padding: 1rem; } }
@layer overrides  { .p-2 { padding: .5rem; } }   /* 靠后的层赢，与写法顺序无关 */

// 图标：具名 import 就能被 tree-shake（30 个图标才 2.7 KB gzip）
import { Home, Search, Settings } from "lucide-react";

// 排查「为什么按需没生效」：先全局搜这一类调用
$ grep -rn "app.use(" src/ | grep -iE "element|naive|vuetify|antd"

// 按需引入的完整写法（样式别忘）
import { ElButton, ElDialog } from "element-plus";
import "element-plus/theme-chalk/base.css";         // 基础变量与重置，必须
import "element-plus/theme-chalk/el-button.css";
import "element-plus/theme-chalk/el-dialog.css";

// 函数式 API 不经过模板，插件看不见，要单独处理
import { ElMessage } from "element-plus";
import "element-plus/theme-chalk/el-message.css";

// 对话框内容懒加载 + hover 预取
const Editor = lazy(() => import("./Editor"));

<button
  onMouseEnter={() => import("./Editor")}      // 悬停即开始下载，点击时已就绪
  onClick={() => setOpen(true)}
>编辑</button>

{open && (
  <Suspense fallback={<Skeleton className="h-96" />}>   // 等高占位，别让布局跳
    <Editor />
  </Suspense>
)}

// chunk 加载失败的重试包装（生产必备）
const retry = (fn, n = 2) => fn().catch((e) => (n ? retry(fn, n - 1) : Promise.reject(e)));
const Editor2 = lazy(() => retry(() => import("./Editor")));

# CI 里守住预算
$ npx size-limit                       # 配置在 package.json 的 "size-limit" 字段

// 成套库：一次配置，组件内置文案跟着换
<ConfigProvider locale={zhCN}><App /></ConfigProvider>      // antd
<el-config-provider :locale="zhCn">…</el-config-provider>    // Element Plus

// 数字、日期、相对时间、复数：全部交给 Intl
new Intl.NumberFormat("zh-CN", { style: "currency", currency: "CNY" }).format(1234.5);
// "¥1,234.50"

new Intl.RelativeTimeFormat("zh-CN", { numeric: "auto" }).format(-1, "day");
// "昨天"（numeric: "always" 时是 "1 天前"）

new Intl.PluralRules("ru-RU").select(2);      // "few" —— 俄语有三种复数形式

<!-- 一个属性驱动全站方向 -->
<html lang="ar" dir="rtl">

/* 用逻辑属性写 CSS，两个方向共用一套 */
.card {
  padding-inline-start: 1rem;      /* LTR 下是左内边距，RTL 下自动变右 */
  border-inline-start: 3px solid var(--color-primary);
  text-align: start;
}

/* 需要翻转的图标：用 CSS 而不是换资源 */
[dir="rtl"] .icon-arrow-back { transform: scaleX(-1); }

<!-- 用户名等不可控内容混排时，用 bdi 隔离双向算法 -->
<p>欢迎，<bdi>{userName}</bdi>！</p>

// 复合组件的最小实现：Root 提供 Context，子组件消费
const Ctx = createContext(null);

function Root({ children, defaultOpen = false }) {
  const [open, setOpen] = useState(defaultOpen);
  return <Ctx.Provider value={{ open, setOpen }}>{children}</Ctx.Provider>;
}

function useDialog() {
  const ctx = useContext(Ctx);
  if (!ctx) throw new Error("Dialog.Trigger 必须放在 Dialog.Root 内部");  // 早报错好过静默失效
  return ctx;
}

function Trigger(props) {
  const { setOpen } = useDialog();
  return <button {...props} onClick={() => setOpen(true)} />;
}

Root.Trigger = Trigger;   // 挂成命名空间：Dialog.Root / Dialog.Trigger

// 受控 / 非受控二合一（React）：这十几行是各家库的公共实现
function useControllableState({ prop, defaultProp, onChange }) {
  const [uncontrolled, setUncontrolled] = useState(defaultProp);
  const isControlled = prop !== undefined;             // ① 用 undefined 判断，不是 null
  const value = isControlled ? prop : uncontrolled;

  const setValue = useCallback((next) => {
    const resolved = typeof next === "function" ? next(value) : next;
    if (!isControlled) setUncontrolled(resolved);        // ② 受控时不碰内部 state
    if (resolved !== value) onChange?.(resolved);         // ③ 两种模式都要通知
  }, [isControlled, value, onChange]);

  return [value, setValue];
}

// Vue 3：同一套逻辑，写成 computed
const inner = ref(props.defaultValue);
const value = computed({
  get: () => (props.modelValue !== undefined ? props.modelValue : inner.value),
  set: (v) => { if (props.modelValue === undefined) inner.value = v; emit("update:modelValue", v); },
});

// asChild：不产生额外 DOM，行为注入到你的组件上
<Dialog.Trigger asChild>
  <MyButton variant="ghost">打开</MyButton>      // MyButton 必须把 props 透传到 <button>
</Dialog.Trigger>

// 你的组件必须长这样，asChild 才有效
function MyButton({ className, ...rest }) {
  return <button className={cn("btn", className)} {...rest} />;   // ...rest 不能漏
}

// Base UI 的等价写法是 render 属性
<Dialog.Trigger render={<MyButton variant="ghost" />}>打开</Dialog.Trigger>

// 事件合并的正确姿势（Slot 内部做的事）
const merged = (theirs, ours) => (e) => {
  theirs?.(e);                                // 使用者的先跑
  if (!e.defaultPrevented) ours?.(e);          // 被 preventDefault 就不跑库的
};

// Ark UI：同一份行为，四个框架各自的绑定层
// React
import { Dialog } from "@ark-ui/react/dialog";
<Dialog.Root><Dialog.Trigger>打开</Dialog.Trigger>…</Dialog.Root>

// Vue —— 组件名、data 属性、键盘行为与 React 版完全一致
import { Dialog } from "@ark-ui/vue/dialog";
<Dialog.Root><Dialog.Trigger>打开</Dialog.Trigger>…</Dialog.Root>

/* 于是同一份样式表能喂给两个框架的产物 */
[data-scope="dialog"][data-part="content"][data-state="open"] { … }

# 这张表会过期，查最新只要一条命令
$ npm view radix-ui version reka-ui version bits-ui version

# 看某个包最近还活着吗
$ npm view element-plus time.modified

# 看它有没有被改名/废弃
$ npm view @nextui-org/react deprecated

# 一个组合的例子：无头 + 专项库，各司其职
radix-ui              # 行为与无障碍
tailwindcss           # 样式
@tanstack/react-table # 表格数据层
@tanstack/react-virtual # 虚拟化
react-hook-form + zod # 表单与校验
sonner                # 通知
lucide-react          # 图标

# 这套组合的产物增量（按本页 14 章的量级估算）：
# Radix 若干组件 ~40 KB + 表格/虚拟化 ~15 KB + RHF/zod ~25 KB + 其余 ~10 KB
# ——总体仍小于一个成套库的入场费 + 常用组件

# 选型时的核对清单该长这样（写细节，不写组件名）
□ 表格：固定左 2 列 + 虚拟化 5000 行 + 行内编辑
□ 上传：分片、并发 3、失败重试、图片预览
□ 日期：区间选择 + 禁用节假日 + 时区固定为 UTC+8
□ 下拉：远程搜索 + 已选项回显 + 多选标签折叠
□ 表单：动态增删明细行 + 跨字段校验
□ 无障碍：键盘全流程可用 + axe 零 critical
□ 体积：首屏 gzip < 200 KB
□ 主题：一套语义令牌驱动亮暗两套 + 客户品牌色

# 拿这张表去试两个候选库，各花两小时 —— 比读十篇对比文章有用

# 形态 ③：自建一个 shadcn 兼容的 registry
# registry/button.json —— 描述这个组件由什么组成
{
  "name": "acme-button",
  "type": "registry:ui",
  "dependencies": ["radix-ui", "class-variance-authority"],
  "files": [{ "path": "ui/button.tsx", "type": "registry:ui" }]
}

# 各产品这样取用（可以是内网地址）
$ npx shadcn@latest add https://ui.acme.internal/r/acme-button.json

src/
  components/
    ui/          # 只放「对第三方的薄封装」：Button、Dialog、Input…
      button.jsx #   shadcn 生成的文件也落在这里
      dialog.jsx
    biz/         # 业务组件：OrderTable、UserPicker，只 import 上面的 ui/
  lib/
    utils.js     # cn() 之类的工具

// src/components/ui/button.jsx —— 一个够用的薄封装
import { Slot } from "radix-ui";
import { cva } from "class-variance-authority";
import { cn } from "@/lib/utils";

const button = cva("inline-flex items-center rounded font-medium transition", {
  variants: {
    variant: { solid: "bg-slate-900 text-white", ghost: "hover:bg-slate-100" },
    size: { sm: "h-8 px-3 text-sm", md: "h-10 px-4" },
  },
  defaultVariants: { variant: "solid", size: "md" },
});

export function Button({ className, variant, size, asChild, ...rest }) {
  const Comp = asChild ? Slot.Root : "button";   // 逃生口：渲染成别的标签
  return <Comp className={cn(button({ variant, size }), className)} {...rest} />;
}

// package.json 的关键字段
{
  "name": "@acme/ui",
  "type": "module",
  "sideEffects": ["*.css"],                 // 让打包器敢删没用到的 JS，但保留 CSS
  "peerDependencies": { "react": ">=18" },   // 绝不能放进 dependencies
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",           // types 必须在最前
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    },
    "./button": {
      "types": "./dist/button.d.ts",
      "import": "./dist/button.js"
    },
    "./styles.css": "./dist/styles.css"
  }
}

/* Tailwind 4：使用者要让扫描器看见你的包 */
@import "tailwindcss";
@source "../node_modules/@acme/ui/dist";   /* 否则你的类名一个都不生成 */

// 一个符合五条原则的组件签名
export function Select({
  value,                    // 受控
  defaultValue,             // 非受控
  onValueChange,            // 两种模式都会触发
  disabled = false,        // 跟随 HTML 命名
  size = "md",
  variant = "outline",      // 与 size 正交，不揉在一起
  classNames,               // 多层结构的插槽级定制
  className,
  ref,                      // React 19 起可直接作为 prop
  ...rest                   // 逃生口：未知属性一律透传
}) { … }

// 使用者可以钻进任意一层，而不必依赖你的内部类名
<Select classNames={{ content: "max-h-72", item: "text-sm" }} data-testid="plan" />

// 废弃警告：开发模式、只打一次、说明替代品
const warned = new Set();
function deprecate(key, msg) {
  if (process.env.NODE_ENV === "production" || warned.has(key)) return;
  warned.add(key);
  console.warn("[@acme/ui] " + msg);
}

export function Button({ type, variant, ...rest }) {
  if (type !== undefined) {
    deprecate("button.type", "Button 的 type 属性将在 v3 移除，请改用 variant。迁移：npx @acme/codemod button-variant");
  }
  return <button {...rest} data-variant={variant ?? type} />;
}

/** @deprecated 请改用 variant，v3 将移除 */
type ButtonType = "primary" | "default";    // IDE 里会显示删除线

// 好的组件测试：全程用用户视角
import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";

test("确认删除后会调用 onDelete", async () => {
  const user = userEvent.setup();
  const onDelete = vi.fn();
  render(<DeleteButton onDelete={onDelete} />);

  await user.click(screen.getByRole("button", { name: "删除" }));
  // 对话框是 portal 出去的，用 findBy 等它挂载
  const dialog = await screen.findByRole("dialog", { name: "确认删除" });
  await user.click(within(dialog).getByRole("button", { name: "确认" }));

  expect(onDelete).toHaveBeenCalledOnce();
});

// ❌ 反面：测的是实现细节，重构必挂且没有信息量
expect(wrapper.find(".btn-danger").length).toBe(1);
expect(component.state.isOpen).toBe(true);

// 单元测试层：每个组件一条断言
import { axe } from "jest-axe";

test("Button 没有无障碍问题", async () => {
  const { container } = render(<Button>保存</Button>);
  expect(await axe(container)).toHaveNoViolations();
});

// E2E 层：查整页，只让 serious 以上的失败
import AxeBuilder from "@axe-core/playwright";

test("结算页无严重无障碍问题", async ({ page }) => {
  await page.goto("/checkout");
  const { violations } = await new AxeBuilder({ page })
    .withTags(["wcag2a", "wcag2aa"])
    .analyze();
  const serious = violations.filter((v) => ["serious", "critical"].includes(v.impact));
  expect(serious).toEqual([]);
});

// Playwright 的截图对比：先把不稳定因素全掐掉
test("按钮各状态的视觉", async ({ page }) => {
  await page.goto("/iframe.html?id=button--all-states");
  await page.addStyleTag({ content: "*,*::before,*::after{animation:none!important;transition:none!important}" });
  await page.evaluate(() => document.fonts.ready);
  await expect(page.locator("#root")).toHaveScreenshot("button-states.png", {
    maxDiffPixelRatio: 0.01,      // 容忍极小差异，减少误报
  });
});

// Storybook play 函数：文档与测试同一份
export const Opens = {
  play: async ({ canvasElement }) => {
    const c = within(canvasElement);
    await userEvent.click(c.getByRole("button", { name: "打开" }));
    await expect(await c.findByRole("dialog")).toBeVisible();
  },
};

# CI 的四层（示意）
jobs:
  fast:                          // PR 必过，目标 < 5 分钟
    - npx tsc --noEmit
    - npx vitest run              // 含 axe 断言
    - npx size-limit              // 体积预算
    - npx eslint . && npx stylelint "**/*.css"

  slow:                          // 合并后跑
    - npx playwright test         // E2E + 视觉回归
    - npm pack && cd fixtures/consumer && npm i ../../*.tgz && npm run build

# 本地也要能一键跑最快的那层，否则没人会在提交前跑
"scripts": { "verify": "tsc --noEmit && vitest run && size-limit" }

// 三个可以现在就做、十分钟见效的检查

// ① 键盘走查：把鼠标拿开，Tab 走一遍主流程
//    看：焦点可见吗？陷进去出不来吗？弹窗关了焦点回来了吗？

// ② 体积基线：构建一次，记下首屏 gzip 数字，写进 README
$ npm run build

// ③ 无障碍快扫：控制台跑一行，看有多少个没名字的按钮
[...document.querySelectorAll("button, a")]
  .filter((el) => !el.textContent.trim() && !el.getAttribute("aria-label"))
  .length;

// 一个判断「这个知识值不值得学」的小测试
// 问自己：换成另一个库，这句话还成立吗？

"模态框打开时必须把外部内容 inert 或 aria-hidden"        // ✓ 永远成立 —— 学
"Radix 的 Dialog.Content 接受 onInteractOutside"         // ✗ 换库就没了 —— 查
"transform 会创建层叠上下文，困住子元素的 z-index"        // ✓ 浏览器规则 —— 学
"antd 6 的一个 Button 是 37.9 KB gzip"                   // ✗ 下个版本就变 —— 会量就行

// 把最容易忘的三条做成 lint 规则，比清单更可靠

// ① 业务代码不许直接 import 组件库
"no-restricted-imports": ["error", {
  patterns: [{ group: ["radix-ui", "@mui/*", "antd"], message: "请从 @/components/ui 引入" }]
}]

// ② 组件样式里不许出现原始层令牌
// stylelint: declaration-property-value-disallowed-list
{ "/color/": ["/var\\(--(blue|gray|red)-/"] }

// ③ 图标按钮必须有可访问名（eslint-plugin-jsx-a11y）
"jsx-a11y/control-has-associated-label": "error"