feat: Support autoPrefixTransformer

[zombieJ]

Summary by CodeRabbit

• 新功能

  • 新增自动前缀转换器（autoPrefixTransformer），支持自动为 CSS 属性添加浏览器前缀。
  • 新增“首次渲染”与“autoPrefix”相关的文档及示例，演示渲染性能和自动前缀功能。
  • 按需支持 CSS 变量哈希与优先级选择器，提升样式隔离与兼容性。

• 功能优化

  • 按组件粒度增强 Button 组件样式系统，支持更多自定义 token 和 CSS 变量。
  • 样式注册与缓存机制优化，提升样式注入和清理的准确性与性能。
  • 主题与 token 提供者（DesignTokenProvider）增强，支持动态主题切换和更严格的类型校验。

• Bug 修复

  • 修复样式提取和排序的稳定性，避免重复提取和顺序错乱。
  • 修复部分样式在组件卸载后未能及时清理的问题。

• 文档

  • 更新/新增多个示例与文档，删除部分过时文档和示例，文档结构更清晰。

• 测试

  • 增加和完善自动前缀、CSS 变量、主题等相关测试用例，移除对旧版 React 的兼容性测试。

• 依赖与脚本

  • 升级依赖版本，替换并优化部分构建与发布脚本，新增 TypeScript 类型检查命令。

本次更新为 2.0.0-alpha.6 版本，包含重要功能增强和兼容性提升。

[coderabbitai]

Caution

Review failed

Failed to post review comments.

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between e7fd8a3 and d93c93e.

⛔ Files ignored due to path filters (3)

• tests/__snapshots__/css-variables.spec.tsx.snap is excluded by !**/*.snap
• tests/__snapshots__/index.spec.tsx.snap is excluded by !**/*.snap
• tests/__snapshots__/server.spec.tsx.snap is excluded by !**/*.snap

📒 Files selected for processing (33)

• docs/demo/auto-clear.md (0 hunks)
• docs/demo/first-render.md (1 hunks)
• docs/examples/auto-clear.tsx (0 hunks)
• docs/examples/autoPrefix.tsx (1 hunks)
• docs/examples/components/Button.tsx (7 hunks)
• docs/examples/components/Spin.tsx (1 hunks)
• docs/examples/components/theme.tsx (2 hunks)
• docs/examples/css-var.tsx (2 hunks)
• docs/examples/first-render.tsx (1 hunks)
• package.json (4 hunks)
• src/Cache.ts (3 hunks)
• src/StyleContext.tsx (3 hunks)
• src/extractStyle.ts (3 hunks)
• src/hooks/useCSSVarRegister.ts (2 hunks)
• src/hooks/useCacheToken.tsx (6 hunks)
• src/hooks/useCompatibleInsertionEffect.tsx (0 hunks)
• src/hooks/useEffectCleanupRegister.ts (2 hunks)
• src/hooks/useGlobalCache.tsx (2 hunks)
• src/hooks/useStyleRegister.tsx (5 hunks)
• src/index.ts (2 hunks)
• src/transformers/autoPrefix.ts (1 hunks)
• src/util/css-variables.ts (3 hunks)
• src/util/index.ts (2 hunks)
• tests/animation.spec.tsx (11 hunks)
• tests/autoPrefix.spec.tsx (1 hunks)
• tests/css-variables.spec.tsx (7 hunks)
• tests/index.spec.tsx (32 hunks)
• tests/keyframes.spec.tsx (1 hunks)
• tests/legacy.spec.tsx (0 hunks)
• tests/linter.spec.tsx (14 hunks)
• tests/server.spec.tsx (12 hunks)
• tests/theme.spec.tsx (2 hunks)
• tests/util.spec.tsx (3 hunks)

💤 Files with no reviewable changes (4)

• docs/demo/auto-clear.md
• docs/examples/auto-clear.tsx
• src/hooks/useCompatibleInsertionEffect.tsx
• tests/legacy.spec.tsx

🧰 Additional context used

🧬 Code Graph Analysis (8)

tests/keyframes.spec.tsx (1)

src/hooks/useCacheToken.tsx (1)

• useCacheToken (154-239)

tests/util.spec.tsx (1)

src/hooks/useStyleRegister.tsx (1)

• normalizeStyle (83-89)

docs/examples/first-render.tsx (1)

docs/examples/ssr-advanced.tsx (1)

• Demo (9-43)

docs/examples/autoPrefix.tsx (3)

src/index.ts (4)

• useStyleRegister (28-28)
• createTheme (27-27)
• StyleProvider (32-32)
• autoPrefixTransformer (39-39)

src/hooks/useStyleRegister.tsx (1)

• useStyleRegister (377-522)

src/StyleContext.tsx (1)

• StyleProvider (100-139)

src/util/index.ts (1)

src/StyleContext.tsx (1)

• HashPriority (54-54)

tests/css-variables.spec.tsx (2)

docs/examples/components/theme.tsx (1)

• DesignTokenContext (54-62)

src/StyleContext.tsx (1)

• StyleProvider (100-139)

src/StyleContext.tsx (2)

src/index.ts (3)

• StyleContext (33-33)
• createCache (31-31)
• StyleProviderProps (61-61)

src/transformers/autoPrefix.ts (1)

• AUTO_PREFIX (3-3)

docs/examples/components/Button.tsx (3)

docs/examples/components/theme.tsx (2)

• DerivativeToken (23-25)
• useToken (95-128)

src/index.ts (3)

• CSSInterpolation (57-57)
• useCSSVarRegister (29-29)
• useStyleRegister (28-28)

src/hooks/useStyleRegister.tsx (2)

• CSSInterpolation (67-70)
• useStyleRegister (377-522)

🔇 Additional comments (87)

docs/demo/first-render.md (1)

1-8: 文档结构良好，符合规范

新增的文档文件结构清晰，YAML frontmatter 格式正确，代码示例引用路径合理。这个文档替换了之前删除的 auto-clear.md，体现了演示重点的调整。

tests/keyframes.spec.tsx (1)

39-39: 测试更新符合新的 API 要求

正确地为 useCacheToken 添加了 cssVar 配置参数，这与代码库中的其他测试文件保持一致。提供的测试键 'css-var-test' 是合理的测试值。

src/index.ts (2)

19-19: 正确导入 autoPrefixTransformer

导入语句遵循现有的模块导入模式，位置合理。

---

39-39: 正确导出 autoPrefixTransformer

在 "Transformer" 部分正确导出了 autoPrefixTransformer，与其他转换器的导出模式保持一致。

docs/examples/components/Spin.tsx (1)

44-51: 简化组件实现，移除不必要的包装

移除了 wrapSSR 包装器的使用，useStyleRegister 现在仅用于副作用（样式注册），直接返回 JSX 元素。这种简化符合代码库中的整体模式变化。

tests/linter.spec.tsx (1)

70-70: 测试用例统一更新，符合新的 API 要求

所有测试组件都正确地为 useCacheToken 添加了 cssVar 配置参数，保持了一致的测试键值 'css-var-test'。这种统一的更新确保了测试套件与新的样式系统保持同步。

Also applies to: 95-95, 113-113, 136-136, 165-165, 190-190, 205-205, 224-224, 255-255, 281-281, 311-311, 345-345, 373-373, 403-403

src/transformers/autoPrefix.ts (1)

5-5: ✅ Transformer 接口兼容性验证通过

经确认，Transformer 接口中唯一的属性 visit 为可选成员，空对象 AUTO_PREFIX 符合该结构，transform 函数返回值满足 Transformer 类型要求，无需修改。

tests/util.spec.tsx (3)

43-43: 正确更新了 normalizeStyle 函数调用

测试正确地为 normalizeStyle 函数添加了 autoPrefix 参数，传递 false 是合适的，因为这些测试应该验证没有前缀的基本样式规范化功能。

---

99-99: layer order 测试的参数更新正确

为 normalizeStyle 函数调用添加 false 参数是正确的，确保了测试的一致性。

---

160-160: leading & 测试的参数更新正确

测试正确地添加了 autoPrefix 参数，保持了测试逻辑的一致性。

src/util/index.ts (2)

4-4: 正确导入了 HashPriority 类型

从 StyleContext 导入 HashPriority 类型是正确的，支持新的 where 函数实现。

---

191-201: where 函数实现良好

函数逻辑正确：

• 适当的早期返回处理空 hashCls 情况
• 默认 hashPriority 为 'low' 是合理的
• 正确使用 :where() 伪类降低选择器优先级

考虑使用更明确的类型检查：

-  return hashPriority === 'low' ? `:where(${hashSelector})` : hashSelector;
+  return hashPriority === 'low' ? `:where(${hashSelector})` : hashSelector;

当前实现已经足够好，这只是一个可选的改进建议。

src/hooks/useCSSVarRegister.ts (4)

33-33: 正确添加了可选的 hashId 属性

为配置对象添加可选的 hashId 属性是正确的，保持了向后兼容性。

---

37-37: 正确解构了 hashId 参数

从配置对象中解构 hashId 的实现是正确的。

---

41-41: 正确从 StyleContext 提取 hashPriority

从 StyleContext 中提取 hashPriority 是正确的实现。

---

57-58: 正确将参数传递给 transformToken

将 hashPriority 和 hashCls: hashId 传递给 transformToken 函数是正确的，参数名称映射合理。

tests/theme.spec.tsx (3)

115-117: 正确更新了 useCacheToken 的解构语法

解构语法 [, , realToken] 正确地获取了第三个元素，并添加了必需的 cssVar 选项。这与新的 API 要求一致。

---

119-119: 正确使用了新的 token 变量

使用 realToken 而不是原来的 token 是正确的，与解构更新保持一致。

---

161-163: 支持管道派生的测试更新正确

同样正确地更新了解构语法和 cssVar 选项，保持了测试的一致性。

src/extractStyle.ts (7)

39-39: 新增的 once 参数功能设计合理

这个参数允许跳过已经提取过的样式，有助于提高性能并避免重复提取。

---

42-42: 默认值设置合理

once 参数默认为 false 保持了向后兼容性，不会影响现有代码的行为。

---

63-66: 提前返回逻辑实现正确

当 once 为 true 且样式已被提取时，正确地返回 null 跳过处理。这种实现方式高效且符合预期。

---

84-84: 提取状态记录逻辑正确

将已提取的 key 添加到 cache.extracted 集合中，确保后续调用时可以正确跳过。

---

86-86: 返回值类型更新正确

新增 updateTime 字段到返回的元组中，与后续排序逻辑保持一致。

---

89-94: 排序逻辑优化得当

首先按 order 排序，然后按 updateTime 排序，确保样式的一致性顺序。这种双重排序策略可以保证样式应用的稳定性。

---

77-77: 确认 cache.updateTimes 已在所有更新及删除场景中正确维护

在 Cache.ts 中，updateTimes 在每次执行 this.cache.set(key, value) 后都会调用 this.updateTimes.set(key, updateId)，并在 this.cache.delete(key) 时同步调用 this.updateTimes.delete(key)，未发现遗漏或不一致的场景。无需额外修改。

docs/examples/first-render.tsx (3)

5-11: 渲染时间测量实现正确

使用 useRef 记录开始时间，useEffect 计算渲染时间的方式准确有效。这种方法能够准确测量组件的初始渲染时间。

---

30-49: App 组件结构清晰

组件结构合理，使用受控组件管理显示状态，条件渲染避免了不必要的性能开销。

---

35-35: 确认：示例中文描述与当前行为一致
“默认情况下不会自动删除添加的样式” 正确反映了通过 import './basic.less' 引入的全局样式在组件卸载时不会自动清理，无需修改。

package.json (3)

3-3: 主版本更新到 2.0.0-alpha.6 合理

版本号正确反映了这次重大重构，包括新增的 autoPrefixTransformer 功能和移除 React 17 兼容性支持。

---

41-41: 新增 tsc 脚本很有用

添加独立的 TypeScript 类型检查脚本有助于 CI/CD 流程中的类型验证。

---

72-72: 缺少 [email protected] 官方变更日志，请手动验证兼容性

npm registry 上未提供任何 changelog 或 breaking-changes 信息，建议：

• 检查 GitHub 仓库或包源中的 CHANGELOG.md 以获取详细更新说明
• 使用 npm ls father 查看当前依赖树，排查可能的版本冲突
• 借助 npm-check-updates 等工具审计并升级潜在受影响的依赖
• 确保现有构建配置和脚本在 [email protected] 下能正常工作

tests/animation.spec.tsx (4)

56-56: CSS 变量选项配置正确

在所有 useCacheToken 调用中统一添加 cssVar: {key: 'css-var-test'} 选项，确保测试环境的一致性。

---

70-76: 样式元素数量和索引更新正确

预期样式元素数量从 2 增加到 3，索引相应调整以适应新增的 CSS 变量样式。这种更新确保了测试的准确性。

---

182-182: 异步测试处理合理

将测试函数标记为 async 并使用 await Promise.resolve() 确保样式注入的正确时序。

---

185-188: 测试配置保持一致

在重挂载测试中也正确添加了 cssVar 选项，保持了测试配置的一致性。

src/hooks/useEffectCleanupRegister.ts (4)

2-3: 导入优化得当

直接导入 useEffect 和 DependencyList 比导入整个 React 对象更高效。

---

6-6: 函数重命名更明确

从 useCleanupRegister 重命名为 useEffectCleanupRegister 更清楚地表达了其使用 useEffect 的实现方式。

---

9-20: 清理函数注册逻辑保持不变

警告逻辑和清理函数注册的核心逻辑保持不变，确保了功能的连续性。

---

22-31: 无需担心 React 17 兼容性
useEffect 自 React 16 起即已支持，package.json 中的 peerDependencies 明确为 react >= 16.0.0，本次简化逻辑改动不会影响对 React 17 的支持，无需额外处理或回退。

Likely an incorrect or invalid review comment.

src/hooks/useGlobalCache.tsx (4)

2-2: 导入更改符合移除 React 17 兼容性的目标

从自定义的 useCompatibleInsertionEffect 切换到原生的 useInsertionEffect 是合理的，符合 PR 中移除 React 17 兼容性支持的目标。

---

12-12: ExtractStyle 类型扩展支持 autoPrefix 选项

为 ExtractStyle 类型添加可选的 autoPrefix 标志符合 PR 中引入自动前缀转换器支持的目标。

---

16-16: effectMap 用于优化批量渲染中的效果去重

添加全局 effectMap 来跟踪活跃的缓存键，确保在单次批量渲染周期中只触发一次 onCacheEffect 回调，这是一个良好的优化。

---

77-103: 缓存生命周期管理的重大改进

useInsertionEffect 的重构实现了以下改进：

• 使用 effectMap 进行效果去重，避免重复触发
• 通过微任务清理机制确保单次批量渲染中只触发一次效果
• 改进的清理逻辑，当引用计数为零时立即调用 onCacheRemove
• 正确的引用计数管理，确保缓存条目的正确清理

这些改进提供了更好的性能和可靠性。

tests/autoPrefix.spec.tsx (2)

1-26: 测试设置和组件结构良好

测试设置包含了适当的样式清理逻辑，Demo 组件正确封装了样式注册逻辑，使用了合适的主题和令牌配置。测试结构清晰且专注于 autoPrefix 功能验证。

---

58-79: 负面测试用例提供了良好的功能覆盖

第二个测试用例正确验证了在没有 autoPrefixTransformer 时不会添加厂商前缀，提供了与第一个测试的良好对比。测试逻辑合理且覆盖面充分。

docs/examples/autoPrefix.tsx (3)

1-11: 导入和组件结构良好

示例正确导入了所有必要的 API，包括新的 autoPrefixTransformer，组件结构清晰且符合 React 最佳实践。

---

10-34: CSS 属性选择和样式实现优秀

示例选择了需要厂商前缀的优秀 CSS 属性组合：

• transform、transition、userSelect、flexbox 和 backdropFilter
• 包含悬停状态提供交互性演示
• useStyleRegister 配置正确，具有适当的主题和令牌设置

这些属性很好地展示了自动前缀功能的价值。

---

36-51: JSX 结构和 StyleProvider 使用恰当

示例具有清晰的 JSX 结构，包含有用的说明文本，StyleProvider 正确配置了 autoPrefixTransformer，并提供了检查 DevTools 的用户指导。这是一个有效的功能演示。

src/Cache.ts (3)

11-12: 全局 updateId 变量用于跟踪更新顺序

添加全局 updateId 变量来记录缓存更新的顺序，用于静态样式的顺序提取。注释清楚地解释了其用途。

---

23-24: updateTimes 映射用于记录每个键的更新时间

添加 updateTimes 映射来记录每个缓存键的更新时间，配合全局 updateId 实现基于顺序的提取逻辑。

---

54-59: opUpdate 方法正确实现了更新时间跟踪

修改后的 opUpdate 方法正确地：

• 删除缓存时移除对应的更新时间记录
• 更新/添加缓存时记录当前 updateId 并递增
• 保持缓存和 updateTimes 之间的一致性

实现逻辑正确，为更新顺序跟踪提供了必要的基础。

tests/css-variables.spec.tsx (4)

71-77: 默认值更改提供了合理的默认行为

为 DesignTokenContext 添加的默认值是合理的：

• hashed: false 是适当的默认值
• cssVar 的默认键 'css-var-root' 提供了可用的默认配置

这些更改支持将 cssVar 设为必需属性，同时保持良好的开箱即用体验。

---

278-278: 移除 autoClear 属性符合 API 简化目标

从 StyleProvider 中移除 autoClear 属性符合 PR 中简化 API 和移除遗留功能的目标。

Also applies to: 295-295

---

309-312: 测试修改正确反映了更新后的行为

测试用例的修改是合适的：

• 更新了断言和注释以反映组件样式保留行为
• 在需要哈希的特定测试用例中添加了 hashed: true
• 更改与 CSS 变量系统的更新行为一致

测试更新正确反映了新行为并保持了测试覆盖率。

Also applies to: 341-341, 365-365

---

65-69: 无需担心：cssVar 必需属性只在测试文件中定义

DesignTokenProviderProps 的定义出现在 tests/css-variables.spec.tsx 文件内，是测试用的本地类型，不会影响库的公共 API 或任何外部使用方。将 cssVar 设为必需属性仅用于测试逻辑，无需调整或兼容性评估。

Likely an incorrect or invalid review comment.

docs/examples/css-var.tsx (1)

1-60: 示例文件更新合理!

这个示例很好地展示了新的 DesignTokenProvider 的使用方式，包括：

• 默认主题使用
• 动态主题切换（使用 CSS 变量）
• 带哈希的 CSS 变量支持

代码结构清晰，功能演示全面。

tests/index.spec.tsx (1)

832-908: 新增的哈希稳定性测试很完善!

这个测试用例很好地验证了：

• 哈希 ID 只在 salt 或 CSS 变量前缀改变时才会变化
• token 值的变化不会影响哈希 ID
• CSS 变量样式的正确生成和更新

测试覆盖全面，逻辑清晰。

docs/examples/components/theme.tsx (2)

64-93: DesignTokenProvider 组件实现优秀!

组件设计考虑周到：

• 使用 React.useId() 生成唯一的 CSS 变量键，避免冲突
• 正确处理了默认值和用户配置的合并
• 保持了向后兼容性

实现清晰，逻辑合理。

---

95-128: useToken hook 更新合理!

hook 的改进包括：

• 返回实际 token 作为第五个参数，方便调试和使用
• CSS 变量配置更加明确和结构化
• 正确处理了 hashed 模式下的 hashId

这些改动提升了 API 的清晰度和可用性。

src/StyleContext.tsx (2)

100-139: StyleProvider 的改进设计良好!

改进亮点：

• autoPrefix 作为内部属性，不暴露给用户，保持了 API 的简洁性
• 通过检测 transformers 数组中的 AUTO_PREFIX 自动启用前缀功能，设计优雅
• 类型安全性得到了加强

移除 autoClear 并添加 autoPrefix 的设计决策合理。

---

6-6: AUTO_PREFIX 导入验证通过

在 src/transformers/autoPrefix.ts 中已使用 export const AUTO_PREFIX = {} 导出，import { AUTO_PREFIX } from './transformers/autoPrefix' 无误，无需修改。

src/util/css-variables.ts (1)

1-94: CSS 变量工具函数增强合理!

主要改进：

• 支持 hashCls 和 hashPriority 选项，实现条件性的 CSS 选择器生成
• 通过 where 函数智能处理选择器包装
• 保持了 preserve 选项的灵活性（第72行）

这些改动与整体的哈希 CSS 变量类支持目标一致，实现清晰。

tests/server.spec.tsx (9)

15-15: LGTM！

从 StyleContext 导入 ATTR_MARK 用于 SSR 样式标签的属性标记。

---

78-86: 组件模式简化得当

Box 组件的更改反映了样式系统的重要改进：

• 引入了必需的 cssVar 配置，支持 CSS 变量体系
• 简化了 useStyleRegister 的使用模式，不再需要包装函数

这种模式更加直观和易于维护。

---

88-96: 新增测试组件合理

Card 组件的实现与 Box 组件保持一致，遵循相同的样式注册模式。这有助于测试多组件场景下的样式提取和缓存行为。

---

124-127: 快照测试提升可维护性

使用快照测试替代精确断言是明智的选择，这样可以：

• 更容易捕获复杂的 HTML 和样式输出变化
• 在样式系统演进时减少测试维护成本

确保在 CI 中正确更新和审查快照。

---

138-145: 缓存键格式简化

缓存重置现在使用简化的键格式 '|.box': '1bbkdf1'，移除了之前的 token 前缀。这与整体的缓存机制简化保持一致。

样式标签数量增加到 4 个反映了新的样式注入逻辑。

---

189-203: 客户端样式测试保持完整性

Client 组件正确实现了 clientOnly 样式注册，确保这些样式不会在 SSR 时被提取。组件结构与其他测试组件保持一致。

---

356-358: 样式优先级索引调整

注意样式元素的索引从 1 开始而不是 0，这表明第一个样式元素可能是 CSS 变量定义或其他基础样式。确保这个假设在所有环境下都成立。

---

365-433: 全面的提取顺序测试

新增的测试用例验证了不同渲染顺序下的样式提取顺序保持一致性。测试覆盖了所有 6 种排列组合（A,B,C 的全排列），确保样式系统的顺序保证机制可靠。

这是一个很好的边界测试用例。

---

435-462: 新增的 once 选项测试合理

这个测试验证了 extractStyle 的重要优化特性：

• 当 once: true 时，每个样式只会被提取一次
• 避免了 SSR 场景下的重复样式提取

测试逻辑清晰，断言准确。建议在文档中说明这个选项的使用场景。

docs/examples/components/Button.tsx (6)

1-8: 导入组织合理

新增的 useCSSVarRegister 导入支持 CSS 变量注册功能，unit 工具函数用于处理 CSS 单位，这些都是样式系统增强的必要组件。

---

14-17: Token 接口扩展合理

ButtonToken 接口新增的属性明确定义了按钮特定的样式令牌：

• buttonPadding: 按钮内边距
• buttonBorderBottomWidth: 按钮底部边框宽度

命名清晰，符合设计令牌规范。

---

22-30: 样式函数正确使用新增令牌

样式生成函数已更新为使用 ButtonToken 类型，并正确引用了新增的令牌属性：

• buttonPadding 用于按钮内边距
• buttonBorderBottomWidth 用于默认按钮的边框宽度

类型安全得到保证。

Also applies to: 67-67

---

119-119: useToken 返回值扩展

useToken 现在返回 5 个值，包括新增的 realToken。这个实际令牌用于 CSS 变量生成，而转换后的令牌用于样式注册，实现了关注点分离。

---

126-145: CSS 变量注册配置完善

useCSSVarRegister 的配置非常全面：

• prefix: 使用组件前缀避免命名冲突
• unitless: 指定无单位的属性（如 lineHeight）
• ignore: 排除不需要转换为 CSS 变量的属性
• scope: 限定 CSS 变量的作用域
• hashId: 支持样式隔离

动态值定义合理，使用 calc() 实现动态计算。

---

169-169: className 包含 CSS 变量键

将 cssVarKey 添加到 className 中用于 CSS 变量的作用域隔离。确保这个键值在整个应用中是唯一的，避免样式冲突。

src/hooks/useCacheToken.tsx (4)

58-70: CSS 变量配置强制化合理

将 cssVar 设为必需项并要求提供 key 是正确的设计决策：

• 确保所有使用缓存令牌的地方都明确配置 CSS 变量
• key 的强制性避免了命名冲突
• hashed 标志提供了样式隔离的灵活控制

这种严格的类型定义提高了系统的可靠性。

---

193-210: 令牌转换逻辑增强

哈希生成和令牌转换的改进提供了更好的灵活性：

• 将 cssVar.prefix 纳入哈希计算增强了唯一性
• 条件性应用 hashCls 支持按需样式隔离
• transformToken 接收完整的配置选项，包括 hashPriority

这些改进支持了更复杂的样式场景。

---

221-235: 样式注入逻辑优化

CSS 变量样式注入的改进：

• 提前返回避免空样式注入（第 221-223 行）
• 使用 -999 优先级确保 CSS 变量在其他样式之前注入
• 使用 prepend: 'queue' 保证注入顺序

这确保了 CSS 变量定义在使用之前就绪。

---

90-90: 验证 TOKEN_THRESHOLD 值的影响

TOKEN_THRESHOLD 设置为 -1 会使清理更加激进。建议验证这是否会在令牌频繁添加/删除的场景下影响性能。

考虑在高频更新场景下进行性能测试，确保不会因过于频繁的清理操作而导致性能问题。

src/hooks/useStyleRegister.tsx (5)

7-7: Stylis 集成支持自动前缀

引入 Stylis 库的相关功能来实现 CSS 自动添加浏览器前缀。Stylis 是一个成熟的 CSS 处理器，能够可靠地处理供应商前缀。

---

83-89: 自动前缀实现正确

normalizeStyle 函数的条件性前缀处理实现得当：

• 仅在 autoPrefix 为 true 时应用 prefixer 中间件
• 保持了向后兼容性
• 使用标准的 Stylis 处理流程

这种可选的自动前缀支持为不同场景提供了灵活性。

---

407-411: 缓存键简化提升可维护性

移除基于令牌的缓存键，改用 hashId 或空字符串作为主要标识符：

• 减少了对令牌内部属性的依赖
• 使缓存行为更加可预测
• 简化了调试和问题排查

这是一个很好的架构改进。

---

476-519: 样式注入逻辑分层处理合理

样式注入的改进正确处理了 CSS 层级：

1. 将 @layer 样式与其他样式分离
2. @layer 样式使用 prepend: true 确保位于顶部
3. 所有样式类型都应用相同的 autoPrefix 设置

这确保了 CSS 层叠顺序的正确性，符合 CSS 规范要求。

---

531-532: SSR 提取支持自动前缀

extract 函数正确集成了自动前缀功能：

• 从选项中获取 autoPrefix 设置
• 在提取过程中对所有样式应用相同的前缀处理

这确保了服务端渲染的样式与客户端样式保持一致。

Also applies to: 556-559

📝 Walkthrough

Walkthrough

本次更新大幅重构了 CSS-in-JS 样式系统，重点引入了自动前缀（autoPrefix）支持、CSS 变量（cssVar）体系强化、样式缓存和提取机制优化，并移除了对 React 17 兼容性（如 useInsertionEffect polyfill）的支持。相关文档、示例和测试文件均同步调整，部分旧特性和兼容性测试被移除。

Changes

文件/路径分组	变更摘要
docs/demo/auto-clear.md docs/examples/auto-clear.tsx src/hooks/useCompatibleInsertionEffect.tsx tests/legacy.spec.tsx	删除了 auto-clear 相关文档、示例和 React 17 兼容性 hook 及测试
docs/demo/first-render.md docs/examples/first-render.tsx	新增“First Render”文档与性能示例
docs/examples/autoPrefix.tsx tests/autoPrefix.spec.tsx	新增 autoPrefixTransformer 示例和测试
docs/examples/components/Button.tsx	Button 组件支持 CSS 变量，增强 token 结构，集成 useCSSVarRegister
docs/examples/components/Spin.tsx	精简 style 注册方式，去除 wrapSSR 包裹
docs/examples/components/theme.tsx	新增 DesignTokenProvider，useToken 支持更强的 CSS 变量与哈希逻辑
docs/examples/css-var.tsx	示例重构，采用 DesignTokenProvider，支持动态主题色切换
package.json	版本升级至 2.0.0-alpha.6，发布脚本切换为 rc-np，依赖更新
src/Cache.ts	Entity 类增加更新顺序追踪，支持样式提取顺序
src/StyleContext.tsx	移除 autoClear，新增 autoPrefix，autoPrefix 由 transformer 控制
src/extractStyle.ts	extractStyle 支持 once 选项，按更新顺序排序样式
src/hooks/useCSSVarRegister.ts	支持 hashId、hashPriority 传递给 transformToken
src/hooks/useCacheToken.tsx	cssVar 选项必填，支持 hashed，缓存与 hash 生成逻辑优化
src/hooks/useEffectCleanupRegister.ts	hook 重命名为 useEffectCleanupRegister，移除 polyfill
src/hooks/useGlobalCache.tsx	直接使用 useInsertionEffect，优化缓存 effectMap 追踪，支持 autoPrefix
src/hooks/useStyleRegister.tsx	支持 autoPrefix，缓存与样式注入简化，移除 SSR 内联样式
src/index.ts src/transformers/autoPrefix.ts	新增 autoPrefixTransformer 导出及实现
src/util/css-variables.ts	serializeCSSVar/transformToken 支持 hashCls、hashPriority
src/util/index.ts	新增 where 方法，生成 hash 优先级选择器
tests/animation.spec.tsx tests/css-variables.spec.tsx tests/index.spec.tsx tests/keyframes.spec.tsx tests/linter.spec.tsx tests/server.spec.tsx tests/theme.spec.tsx tests/util.spec.tsx	测试用例统一适配 cssVar 选项、hash 逻辑、autoPrefix 行为及样式提取顺序，部分断言改为快照
docs/examples/components/Spin.tsx docs/examples/components/theme.tsx docs/examples/css-var.tsx docs/examples/components/Button.tsx	示例代码同步适配新的样式注册、token 与 CSS 变量体系

Sequence Diagram(s)

sequenceDiagram
  participant App
  participant StyleProvider
  participant useStyleRegister
  participant Cache
  participant Transformer (autoPrefix)
  participant DOM

  App->>StyleProvider: 包裹组件，传入 transformers
  StyleProvider->>useStyleRegister: 提供 autoPrefix、hashId 等上下文
  useStyleRegister->>Cache: 查询/注册样式缓存
  useStyleRegister->>Transformer (autoPrefix): 若 autoPrefix 启用，自动前缀化样式
  useStyleRegister->>DOM: 注入样式（含 CSS 变量、前缀）
  App->>DOM: 渲染组件

Loading

sequenceDiagram
  participant App
  participant DesignTokenProvider
  participant useToken
  participant useCacheToken
  participant useCSSVarRegister
  participant DOM

  App->>DesignTokenProvider: 传递 token、cssVar、hashed
  DesignTokenProvider->>useToken: 提供 token 上下文
  useToken->>useCacheToken: 获取/生成 token、hashId、cssVarKey
  useCacheToken->>useCSSVarRegister: 注册 CSS 变量样式
  useCacheToken->>DOM: 注入 CSS 变量样式
  App->>DOM: 渲染依赖 token 的组件

Loading

Suggested reviewers

• MadCcc

Poem

🐇
新版样式兔，前缀自来加，
变量体系强，缓存顺序佳。
旧兼容说再见，
新特性齐上马。
代码田野绿油油，
兔子乐开花！

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

docs/examples/components/Spin.tsx

Oops! Something went wrong! :(

ESLint: 7.32.0

ESLint couldn't find the config "prettier" to extend from. Please check that the name of the config is correct.

The config "prettier" was referenced from the config file in "/.eslintrc.js".

If you still have problems, please stop by https://eslint.org/chat/help to chat with the team.

docs/examples/autoPrefix.tsx

Oops! Something went wrong! :(

ESLint: 7.32.0

ESLint couldn't find the config "prettier" to extend from. Please check that the name of the config is correct.

The config "prettier" was referenced from the config file in "/.eslintrc.js".

If you still have problems, please stop by https://eslint.org/chat/help to chat with the team.

docs/examples/components/Button.tsx

Oops! Something went wrong! :(

ESLint: 7.32.0

ESLint couldn't find the config "prettier" to extend from. Please check that the name of the config is correct.

The config "prettier" was referenced from the config file in "/.eslintrc.js".

If you still have problems, please stop by https://eslint.org/chat/help to chat with the team.

• 24 others

✨ Finishing Touches

• 📝 Generate Docstrings

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch autoPrefix

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>, please review it.
  • Explain this complex logic.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
  • @coderabbitai explain this code block.
  • @coderabbitai modularize this function.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
  • @coderabbitai read src/utils.ts and explain its main purpose.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
  • @coderabbitai help me debug CodeRabbit configuration file.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai full review to do a full review from scratch and review all the files again.
• @coderabbitai summary to regenerate the summary of the PR.
• @coderabbitai generate docstrings to generate docstrings for this PR.
• @coderabbitai generate sequence diagram to generate a sequence diagram of the changes in this PR.
• @coderabbitai auto-generate unit tests to generate unit tests for this PR.
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
• @coderabbitai help to get help.

Other keywords and placeholders

• Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
• Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
• Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• Please see the configuration documentation for more information.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[codecov]

Codecov Report

Attention: Patch coverage is 90.47619% with 4 lines in your changes missing coverage. Please review.

Project coverage is 94.53%. Comparing base (2b33bea) to head (d93c93e).
Report is 1 commits behind head on next.

Files with missing lines	Patch %	Lines
src/hooks/useStyleRegister.tsx	73.33%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             next     #230      +/-   ##
==========================================
- Coverage   94.58%   94.53%   -0.05%     
==========================================
  Files          31       32       +1     
  Lines        2786     2817      +31     
  Branches      440      445       +5     
==========================================
+ Hits         2635     2663      +28     
- Misses        151      154       +3     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.