shared-dev

name	shared-dev
description	处理 nil-design 仓库中 @nild/shared 类型、React helpers、class utilities、runtime utilities、通用工具方法、性能基准和 shared 包公开接口的设计、开发、重构、测试、维护或导出。

开发共享能力

处理 @nild/shared 时，按下面的职责边界、核对清单、包边界、实现偏好和验证要求推进。shared 是跨包基础层；只有抽象稳定且至少有真实复用价值时才放入 shared。

职责边界

• 优先负责 packages/shared/src/**、shared 测试、shared 构建形状和下游导入方式。
• shared 只承载跨包基础能力，不提前吸收尚未稳定的组件私有行为。

第一轮核对

• 修改导出前读 packages/shared/src/index.ts 和相关子入口。
• 新增工具前读最接近的 helper、测试和调用方。
• 涉及 class utility、React helper、type-only helper 或 runtime utility 时读 references/patterns.md。
• 任何跨包影响都要回看 components/hooks/docs 的调用方式。

包边界

• interfaces 放可复用 TypeScript 类型，保持 type-only，避免 runtime 依赖。
• react 放 React 专属 helpers，可以依赖 React，但要保持跨组件通用。
• utils 放 runtime utilities、class helpers、字符串转换、环境判断、数值工具和少量稳定 re-export。
• 不把组件专属行为提前搬进 shared；先在组件内稳定，再考虑抽象。

实现偏好

• 工具函数保持小、纯、依赖少，优先直接命名和直接行为。
• 不做选项很多的万能 helper；调用侧更清楚时宁可保持局部实现。
• 默认导出配合 barrel export，保持本地 tree-shaking 和导入风格一致。
• TypeScript generics 只在改善调用侧推导或约束时使用。
• 不给 utils 或 type-only 模块引入 React 依赖。
• class utilities 保持职责分层：普通 class join、Tailwind conflict merge、variant class function 各自语义清晰。

验证

• runtime helper 跑聚焦测试或 pnpm shared:test。
• 类型形状变化运行 pnpm shared:build 或包级 typecheck。
• shared 变化影响 components/hooks 时，同时运行对应包的聚焦测试或构建。
• 公开入口或 package export 形状变化时，检查 packages/shared/package.json 的 exports 与生成的 dist 结构一致。

Benchmark

• 以 packages/shared/src/react/index.ts 和 packages/shared/src/utils/index.ts 的自有运行时导出为覆盖清单；每个方法在相邻 __benchmarks__/ 放一份 <method-name>.bench.ts(x)，不覆盖 type-only 接口或第三方直接 re-export。
• 使用代表性公开输入测量真实调用路径；有缓存的 helper 避免始终命中同一输入，只有浏览器相关 helper 使用 // @vitest-environment jsdom。
• 新增或修改用例后运行 pnpm shared:bench。