bklit-ship

Bklit Ship Skill

此技能面向 bklit-ui monorepo 贡献者，帮助他们将已在 Studio 中验证的图表或组件投入生产：发布到 UI 包中、编写文档，并准备好供用户使用。

何时使用此技能

• 你克隆了 bklit/bklit-ui，并在 Studio（/studio）中验证了一个可用的原型，现在想将其发布。
• 你已准备好从“搭建”进入“正式落地”阶段：API 以及关键属性／变体已在原型设计阶段确定。

---

计划：原型 → 生产

按顺序执行以下步骤。请将其视为一份检查清单；每一步都列出了仓库中的具体位置。

1. 移入 UI 包并导出

• 移入或完成位于 packages/ui/ 中的图表／组件源代码（例如，图表位于 packages/ui/src/charts/）。如果你遵循了 bklit-studio，原型应该已经在这里；如果 apps/web/components/playground/ 下还有残留副本，请删除。
• 从该包的公共 API 导出新图表／组件：
  • 对于图表：在 packages/ui/src/charts/index.ts 中添加导出。
  • 如果该包在 package.json 中使用 exports 指定入口，请添加或更新相应入口，使新组件可通过 @bklitui/ui/charts（或适当路径）导入。
• 不要在 apps/web/components/playground/ 下添加仅供应用使用的图表副本（已弃用）。Studio 预览应放在 packages/studio 中。

2. 文档和示例（apps/web）

文档位于 apps/web/ 下。请完成以下所有事项。

• 更新现有组件文档，适用于发布内容扩展现有图表的情况（新增属性、子组件或行为）：

  • 在父级文档的相关表格中添加新属性（例如，在 line-chart.mdx 中记录 Grid highlightRowValues、ChartTooltip indicatorColor）。
  • 视需要更新相关工具文档（例如，content/docs/utility/grid.mdx、tooltip.mdx）。
  • 保持主要文档预览不变——不要将现有页面上的标准预览替换为新变体。
  • 当某个功能值得单独成页时，添加一个链接至专门文档页的简短章节（例如，Profit/Loss → profit-loss-line.mdx）。

• 图表示例（/charts/[slug] 上的实时演示）

  • 在对应的图库路由中添加示例（例如，将 Profit/Loss 变体放在 /charts/line-chart 下，而不只是新增一个文档预览）。
  • 如果该功能属于一种新的图表类型，请将其 slug 添加到 apps/web/components/charts/chart-slugs.ts，并在 apps/web/components/charts/chart-examples.tsx 中注册示例（视情况使用 CHART_NAV_ITEMS／工厂注册表）。
  • 复用或映射你在搭建阶段验证过的属性变体。

• 专门的文档页（发布新的可组合组件或图表类型时）

  • 添加 apps/web/content/docs/components/<name>.mdx，包含 frontmatter、<ComponentPreview>、安装说明、用法和属性，并与现有组件文档保持一致。
  • 将 slug 添加到 apps/web/content/docs/components/meta.json。此文件会同时驱动桌面侧边栏和移动菜单——apps/web/components/docs/site-header.tsx 会根据文档页面树（docsTree）生成移动导航，因此无需在该处手动维护列表。
  • 可选的“New”徽章：将文档和图库 URL 添加到 apps/web/lib/nav-badges.ts（侧边栏、移动菜单和站点导航都会读取它）。
  • 顶层站点链接（Docs、Components、Recipes、……）位于 apps/web/lib/site-nav-links.ts；图表页面不应添加到这里。

3. Studio

• 如果新功能是现有类型的变体，更新现有的 Studio 图表；如果是不同类型，添加新的 Studio 图表。
• 将所有可调属性接入 Studio（如果原型阶段尚未完成）：
  • packages/studio/src/lib/studio-parsers.ts — URL 状态键和默认值
  • packages/studio/src/lib/registry-control-groups.ts — 控制组
  • packages/studio/src/lib/registry.tsx — 渲染预览 + generateCode
  • packages/studio/src/lib/studio-components.ts — 图层树
  • 在 packages/studio/src/components/studio-state-provider.tsx 中设置切换图表类型时的图表类型默认值
• 新的 Studio slug 还需要（TypeScript 会检查 Record<ChartSlug, …> 对应的条目，但不会检查其他条目）：
  • packages/studio/src/chart-slugs.ts — 添加 slug
  • packages/studio/src/lib/types.ts — 添加 chartLabels 条目（显示名称；satisfies Record<ChartSlug, string>）
  • packages/studio/src/components/chart-type-icons.tsx — 添加 CHART_TYPE_ICONS 条目（Record<ChartSlug, IconName>）
  • packages/studio/src/components/catalog/catalog-chart-preview-grid.tsx — 如果目录卡片需要自定义尺寸或状态覆盖，则添加 CATALOG_CHART_LAYOUT 条目（如果有 y 轴，还需添加 STUDIO_Y_AXIS_CHART_PREFIX）
  • packages/studio/src/lib/studio-url-key-orders.ts — 将每个新的 URL 状态键追加到 STUDIO_STATE_KEY_ORDER 末尾（冻结，只能追加；绝不要插入或重新排序，否则会破坏共享 URL；studio-url-codec.test.ts 会对此进行检查）
  • packages/studio/src/lib/studio-visibility-sync.ts — 如果图表有图例或画笔图层，则在 legendComponentIdForChart / brushComponentIdForChart 中添加对应分支（否则默认使用 null）

4. 重建 shadcn 注册表

• 在仓库根目录运行：pnpm registry:build。
• 此命令会根据 packages/ui 更新 apps/web/public/r/。如果新组件需要通过 shadcn 安装，请确保将其列入 packages/ui/registry.json。

5. Lint、格式化、测试和构建

从仓库根目录运行，直到所有检查通过：

pnpm lint
pnpm format
pnpm --filter @bklitui/ui test   # when package logic changed
pnpm build
pnpm registry:build              # if not already run in step 4

修复所有错误；重复执行，直到提交时的钩子通过。

6. 提交、推送并创建 PR

• 使用简短、清晰的提交消息提交（例如：feat(charts): add ProfitLossLine component）。
• 推送分支。
• 填写发版检查清单（见下文）并创建 PR。

---

PR 检查清单

• 图表/组件已移至 packages/ui 并导出
• 已更新现有文档，说明新增的属性/功能（标准预览保持不变）
• Gallery 示例位于正确的 /charts/** 路由
• 专属文档页面 + 侧边栏 + 移动端导航（如果是新的可组合类型/图表类型）
• Studio 图表已更新或添加，且所有属性均已加入控制组（新 slug：标签、图标、目录布局、URL 键顺序已追加）
• 注册表已重建（pnpm registry:build）
• pnpm lint、测试（如适用）和 pnpm build 均通过

---

文件参考（快速查找）

步骤	位置
图表导出	packages/ui/src/charts/index.ts
图表 slug	apps/web/components/charts/chart-slugs.ts
图表示例（导航 + 注册表）	apps/web/components/charts/chart-examples.tsx
组件文档	apps/web/content/docs/components/<name>.mdx
工具文档（Grid、Tooltip 等）	apps/web/content/docs/utility/*.mdx
侧边栏 + 移动端导航	apps/web/content/docs/components/meta.json → pages（site-header.tsx 中的移动端菜单由文档页面树生成）
“New” 徽章	apps/web/lib/nav-badges.ts
Studio 注册表	packages/studio/src/lib/registry.tsx
Studio 组件树	packages/studio/src/lib/studio-components.ts
Studio 控件	packages/studio/src/lib/registry-control-groups.ts
Studio URL 状态	packages/studio/src/lib/studio-parsers.ts + 在 packages/studio/src/lib/studio-url-key-orders.ts 中追加键
Studio slug 列表 / 标签 / 图标	packages/studio/src/chart-slugs.ts、packages/studio/src/lib/types.ts（chartLabels）、packages/studio/src/components/chart-type-icons.tsx
Studio 目录图块	packages/studio/src/components/catalog/catalog-chart-preview-grid.tsx
Studio 图层可见性同步	packages/studio/src/lib/studio-visibility-sync.ts
注册表（源文件）	packages/ui/registry.json；构建输出：apps/web/public/r/
注册表构建	在根目录运行：pnpm registry:build