breaking(TSteps): 收敛进度、可选择与纯展示模式

specs/030-steps-design-alignment/acceptance.md

@@ -0,0 +1,103 @@
+# 验收记录
+
+## 2026-09-09 可选择 Demo 动态标题
+
+- 修改仅限公开 Demo、对应测试、生成片段与 Spec；`TSteps` 生产实现、公开 API 和 Theme 未变。
+- 垂直可选择示例继续固定四项，根据唯一受控状态 `_selectedStep` 派生“已完成步骤 / 当前步骤 / 未完成步骤”；点击后节点视觉与标题语义同步更新，不复制小程序通过 `count` 动态增删步骤的 Demo 数据技巧。
+- Steps Demo 结构/交互测试 3/3 通过，点击第一项后断言 1 个“当前步骤”和 3 个“未完成步骤”；生成片段 `--check` 与三个修改文件的严格 analyze 通过。
+- macOS Flutter 3.32.0 严格复跑 Steps 整页 Golden 出现 light 4.73% / dark 4.70% 差异，与当前分支已记录的 Linux 基线跨平台字体渲染差异一致；本次初始状态的文案、结构和布局不变，未在 macOS 更新 Linux 权威基线。
+
+## 2026-09-09 命名构造收敛
+
+- 移除未命名 `TSteps(...)` 与同时混合指示器/使用模式的 `TStepsVariant`。
+- `TSteps.progress` 可选 `onChange` 只启用点击，横纵 `dot` 保持相同进度视觉；`TSteps.selectable` 固定垂直点状、必填回调并显示右箭头；`TSteps.display` 不接收进度、状态或交互参数。
+- 公开 Demo、站点文档、生成 API、组件和交互测试同步到新契约。
+- Flutter 3.32.0 与 3.47.0 组件测试均为 28/28、Demo 测试均为 3/3，组件和 Example 严格 analyze 零问题；3.32.0 生产源码覆盖率 245/246 = 99.59%，生成片段 `--check` 通过。
+- 已合并 `origin/develop@335b30bc`；合并后的 Flutter 3.32.0 analyze、Steps 组件测试 28/28、Demo 测试 3/3 通过。macOS 本地共享导航 Golden 差异 light 2.71% / dark 2.67%，未覆盖 Linux 权威基线。
+- Xiaomi Android 16 真机集成测试 1/1 通过，普通 Example 再次安装并核对浅色、深色、滚动、选择与 Toast；选择后受控 `value` 正确更新。当前 Demo 的步骤标题为静态数据，点击后不会像小程序 Demo 一样随索引切换“已完成 / 当前 / 未完成”文案，留给本轮针对性 Review 判断是否应作为 Demo 对齐问题修正。
+
+## 2026-09-08 最新 develop 同步与公开契约复审
+
+- 已合并 `origin/develop@d2ff7a0a`，保留 Cascader、SideBar 与 Popover 的新增
+  Demo、主题及回归登记；Steps 分支不再落后 develop。
+- 修复垂直可选择步骤使用 `customTitle` 或仅提供 `content` 时缺少右箭头的
+  问题；字符串标题与自定义标题现在共用标题行和间距，`onChange` 仍是唯一
+  可选择来源。
+- 重写 Steps 站点文档，删除不可编译的 `activeIndex`、`successIcon`、`simple`、
+  `readOnly`、`verticalSelect`、`TStepsStatus.success` 旧用法，补充受控、
+  自定义内容、错误态、纯展示及 breaking change 迁移说明。
+- Flutter 3.32.0：Steps/Text 组件测试 38/38、Steps Demo 3/3 通过，严格
+  analyze 零问题；组件路由、Example 与站点文档契约检查通过。
+- 合并后的共享导航 Golden 同时包含 Steps 与 SideBar 变更，不能选择任一旧
+  二进制基线冒充组合结果。当前先保留 develop 基线；固定 Linux + Flutter
+  3.32.0 的组合基线仍需在允许挂载仓库的可信环境中重新生成并严格复跑。
+
+## 2026-09-08 补充复审与修复
+
+本节为本轮结果；下方真机、构建及首轮检查是历史记录，不替代本轮证据。
+
+- 基于 PR head `79eff997` 修复；重新核对 `develop@3d5ed773` 未变化。
+- 修复横纵标题、内容和序号文字将默认值作为实例 style 传入的问题。内置 defaults 低于显式 TextTheme、DefaultTextStyle、TTextThemeData；只改字体族/字号不覆盖状态色，实例自定义 Widget 仍优先。
+- 新字段级解析仅对组合 defaults 生效；内部 `TTextThemeSource` 只读取原有投影快照，不导出、不持有新状态。无 defaults 的 TText 及其他组件维持原路径；试验性全局主题和共享消费者改动已撤回。
+- display 横纵均为全实心节点，忽略 value/status，交互仍只看 onChange。
+- 10 个公开代码入口逐个实际打开并与生成片段匹配；受控示例补充 State 初始字段和接入说明。10 份实际生成片段在最小宿主中编译/渲染，受控选择与反馈操作通过；临时拼接测试不作为独立示例实现提交。
+- Flutter 3.32.0 全部非视觉组件测试 2074/2074；3.47.0 Steps/Text/工具测试 73/73，Demo 与片段编译 13/13；两版本严格 analyze 零问题。
+- 生产覆盖率：Steps 238/239 = 99.58%，Text 219/222 = 98.65%。
+- Linux 3.32.0：Steps 整页与共享导航明暗 4 张基线更新后严格复跑。自动 Material 行高不再覆盖默认值，整页 375×3067 → 375×3055；共享导航仅 Steps 区域减少 2px，后续内容顺移。对照实际图/基线图，未见缺字、裁切或状态缺失。未设像素容差，复跑 diff 为 0。
+- 保留原路径的 Text/Button/ActionSheet 18 项结构与视觉测试通过，无需修改其基线。
+- 本轮未重新进行 Android/iOS 真机逐像素核对；不能将代码/Golden 验证等同于与设计稿逐像素完全一致。最新远端 CI 与 CNB Review 以推送后的结果为准。
+
+## 2026-09-08 develop 同步复审
+
+- 已合并 `origin/develop@3d5ed773`；组件 API、状态所有权与 Token 路径无新增冲突，
+  未发现实例默认样式向 Theme 或其他组件泄漏。
+- Flutter 3.32.0 `flutter analyze --fatal-infos` 通过；组件测试 23/23、集中回归
+  清单自测 13/13 通过；生产源码覆盖率 226/233 = 97.00%。
+- macOS 上公开 Demo 结构测试通过；整页 Golden 因 develop 的公共导航标题样式变更
+  出现 light 4.72%、dark 4.69% 的预期差异。权威基线只在 Flutter 3.32.0 Linux
+  更新，等待本轮 CI 产出 Linux failure artifact 后核对并提交。
+
+## 环境
+
+- 分支：`rss1102/breaking/steps-design-alignment`
+- 基线：`origin/develop` (`f3e14c43`)
+- Figma：页面 `24386:5241`，移动端画板 `28591:34552`
+- 真机：Xiaomi Android 16，ADB `40302eeb`
+
+## 当前已完成
+
+- [x] 新版 Figma / 小程序 / Flutter 三方差异与跨端取舍已记录。
+- [x] 组件公开契约、Flutter 状态所有权与 Theme Review 已完成首轮收敛。
+- [x] 真机首次安装运行并执行 uppercase `R`；浅色逐段滚动、点击，切换深色主题。
+- [x] 修复垂直可选择与纯展示节点状态后再次 uppercase `R`，重新进入页面并点击复验。
+- [x] Flutter 3.32.0 全包 analyze 为 0 issue；Steps focused tests 通过。
+- [x] 组件测试 23/23、Demo 结构/交互 2/2、生产源码覆盖率 226/233（97.00%）通过。
+- [x] Flutter 3.32.0 与 3.47.0 analyze、组件测试、Demo 测试、Web release 和 Android debug 构建通过。
+- [x] Flutter 3.32 Linux light/dark Golden 2/2 生成后无更新参数严格复跑 2/2；逐张检查无缺字、无裁切。
+- [x] 示例代码片段生成器完成 11 个旧片段清理、10 个新片段生成，`--check` 通过。
+- [x] Android 16 真机 integration 1/1 通过；普通 APK 安装返回 `Success`，强停后冷启动到 TDesign 首页。
+
+## API / Theme Review
+
+- `value` 是唯一受控值；组件不内部回写，越界值仅在渲染时收敛。
+- `onChange` 是唯一交互/只读开关；垂直回调同时启用点击和右箭头，不再由 Theme 或第二个布尔值控制。
+- `variant` 只负责 `standard`、`dot`、`display` 视觉结构，`status` 只负责当前步骤的 `process/error` 业务状态。
+- `customTitle/customContent` 明确覆盖字符串便利字段；`icon/errorIcon` 保持强类型 `IconData`。
+- 删除持有业务状态的 `TStepsThemeData`；颜色与字体使用 `context.tTheme` 语义 Token，固定节点/连线尺寸记录为组件设计常量。
+
+## Golden 人工检查
+
+- light/dark 均为 375×3067 完整长页，三组顺序与新版 Figma 一致。
+- 水平/垂直默认、图标、点状及自定义内容完整；错误态包含默认、图标、点状三种。
+- 垂直可选择默认前三项实心、当前项空心；纯展示四项均实心且无箭头。
+- 独立 Steps CJK 子集消除 Linux 缺字方框；深色仅改变语义颜色，不改变结构。
+- 合并含 TabBar #1085 的 `develop@1de424cb` 后，GitHub Actions 在本分支
+  `dac8ca16` 的 Flutter 3.32.0 Linux 任务仅产出共享导航 light/dark 两张差异图；
+  人工检查确认 TabBar 新 API 渲染保持不变，差异来自 Steps 标题/内容布局向上收敛
+  2px 及其后续内容等量上移。基线采用该任务 artifact 的 `testImage`，未使用 macOS
+  抗锯齿结果；更新后仍需由下一轮 Linux CI 严格复跑确认差异为零。
+
+## 待完成（当前）
+
+- GitHub #1084 / CNB #151 已存在；`dac8ca16` 的双版本 analyze 已通过，Linux
+  Golden 按最新 artifact 修正；完整 CI 与 CodeBuddy Review 待下一次推送后核验。

specs/030-steps-design-alignment/plan.md

@@ -0,0 +1,16 @@
+# 实施计划
+
+## 本轮补充修复
+
+- 以内部只读投影视图为共享解析器提供字段来源，只对组合 defaults 使用字段级解析，保留其他消费者原路径。
+- 标题、内容与数字节点使用低优先级 defaults；display 横纵状态一致。
+- 验证真实代码面板与核心片段接入，复用页面 State；补充组件、Demo、双版本与共享视觉回归。
+
+## 首轮计划
+
+1. 记录新版 Figma、小程序公开 Demo 与 Flutter 当前实现的结构、视觉和交互差异。
+2. 用 `progress`、`selectable`、`display` 命名构造分离使用模式，收敛 `value`、`status`、`indicator`、`onChange` 的职责及 Theme 所有权。
+3. 重构公开 Demo 为新版 Figma 的三组顺序，并保留小程序受控、只读和自定义内容的操作模式。
+4. 先完成组件、Demo、API/Theme Review 与真机明暗主题实际操作，再生成并严格复跑 light/dark Golden。
+5. 完成双 SDK analyze、测试、覆盖率、构建、生成产物和持久安装。
+6. 独立创建 GitHub/CNB PR，关联 #1027 Steps 条目并请求 CodeBuddy Review。

specs/030-steps-design-alignment/spec.md

@@ -0,0 +1,40 @@
+# Steps 设计与公开契约收敛
+
+## 背景
+
+Flutter Steps 的公开 Demo、状态命名及只读/可选择所有权与新版 Figma、小程序公开用法不一致。旧 Demo 分为六组，缺少完整垂直图标和三种错误状态；组件同时由实例与 Theme 持有 `simple`、`readOnly`、`verticalSelect` 业务状态。
+
+## 行为契约
+
+- `TSteps.progress` 表达普通受控进度：`value` 由调用方持有，越界值只在渲染时收敛；可选 `onChange` 只报告点击索引，不改变指示器的进度语义。
+- `TSteps.selectable` 表达垂直可选择步骤：固定为点状指示器，`onChange` 必填，并显示右箭头。
+- `TSteps.display` 表达纯展示：不接收 `value`、`status` 或 `onChange`，横向与纵向均显示全实心节点及完成态连线。
+- `indicator` 只表达进度步骤条的指示器样式：`standard` 或 `dot`。
+- `status` 是当前 `value` 的业务状态：`process` 或 `error`。
+- `icon` 替换默认数字/完成图标；`customTitle`、`customContent` 分别优先于字符串便利字段。
+- `progress + dot` 在横向与纵向保持相同进度语义；`selectable` 为已完成节点实心、当前节点空心。
+
+## Demo 契约
+
+- 公开 Demo 按新版 Figma 收敛为“组件类型 / 组件状态 / 特殊类型”三组。
+- 组件类型依次展示水平默认/图标/点状、垂直默认/图标/点状和自定义内容。
+- 错误状态同屏展示默认、图标、点状三种样式。
+- 特殊类型依次展示垂直可选择步骤与纯展示时间线；前者真实更新受控值并反馈选择结果，后者无点击回调。
+- 垂直可选择示例保持固定四项，并根据受控 `value` 派生“已完成步骤 / 当前步骤 / 未完成步骤”标题；不复制小程序通过 `count` 动态增删步骤的 Demo 数据技巧。
+- 可选择示例的核心片段标明 State 宿主、初始字段与 build 接入方式，展示实际运行的回调重建；不声称省略应用壳的片段可以直接运行。
+- 小程序公开 Demo 仍是交互参考：保留受控/只读、横纵方向、默认/点状和自定义内容能力，但不复制动态事件对象或非受控双状态源。
+
+## Theme 与尺寸
+
+- Steps 不再注册持有业务状态的 ThemeExtension；默认颜色与字体读取 `context.tTheme` 语义 Token。内置文字样式通过共享解析器的低优先级 defaults 入口提供，显式 TTextThemeData、DefaultTextStyle、TextTheme 按字段覆盖，不将默认值伪装成实例覆盖。
+- 22dp 默认节点、8dp 点节点、16/22dp 图标和 1dp 连线属于组件内固定设计尺寸，不作为业务状态或主题模式开放。
+- 明暗主题使用同一结构，由语义 Token 驱动颜色变化。
+- 组合文字解析通过内部只读投影视图辨认 Material 自动补全；不移动共享主题类、不改变无 defaults 的既有 TText 路径。只有 Steps 与 TabBar 使用该低优先级入口。
+
+## Breaking change
+
+- `TStepsStatus.success` 改为 `process`。
+- `TStepsItemData.successIcon` 改为 `icon`。
+- 移除未命名 `TSteps(...)` 构造和 `TStepsVariant`，分别改用 `TSteps.progress`、`TSteps.selectable`、`TSteps.display` 与 `TStepsIndicator`。
+- 移除 `TSteps.simple`、`readOnly`、`verticalSelect`；交互由各命名构造的 `onChange` 契约表达。
+- 删除只持有上述业务状态的 `TStepsThemeData`。

specs/030-steps-design-alignment/tasks.md

@@ -0,0 +1,15 @@
+# 任务清单
+
+- [x] 完成新版 Figma / 小程序 / Flutter 三方差异输出
+- [x] 收敛组件公开契约与 Theme 所有权
+- [x] 收敛公开 Demo 与代码片段源文件
+- [x] 完成首轮与修复后真机 uppercase `R`、明暗主题及交互操作
+- [x] 完成组件、Demo 与覆盖率本地验证
+- [x] 生成并严格复跑 light/dark Golden，逐张人工检查
+- [x] 完成 Flutter 3.32.0 / latest analyze、测试与构建
+- [x] 完成 Android 真机集成测试与持久安装
+- [x] 已创建 GitHub #1084 / CNB #151；PR 描述关联 GitHub #1027
+- [x] 处理上一轮 CodeBuddy Review 反馈
+- [x] 补充逐字段主题、双轴 display、实际代码面板和核心片段编译回归
+- [x] 用命名构造分离 progress/selectable/display，移除无效参数组合与 onChange 视觉耦合
+- [ ] 本轮修复推送后，检查新 head CI 并完成新一轮 CNB Review

specs/030-steps-design-alignment/visual-comparison.md

@@ -0,0 +1,25 @@
+# 三方视觉与交互对照
+
+## 参考
+
+- 新版 Figma：页面节点 `24386:5241`；移动端画板 `28591:34552`；组件类型 `28591:34556`、错误状态 `28591:34615`、特殊类型 `28591:34637`。
+- 小程序公开 Demo：TDesign 小程序 Steps 页面。
+- Flutter：`lib/src/components/steps/` 与 `example/lib/page/t_steps_page.dart`。
+
+## 差异
+
+| 项目 | 新版 Figma | 小程序公开 Demo | 修改前 Flutter | 收敛目标 |
+| --- | --- | --- | --- | --- |
+| 分组 | 组件类型、组件状态、特殊类型 | 基础、布局、类型、状态、只读、自定义 | 六个模块 | 三组及 Figma 顺序 |
+| 组件类型 | 水平/垂直默认、图标、点状及自定义内容 | 水平/垂直、默认/点状、自定义内容 | 缺完整垂直图标 | 补齐七个例子 |
+| 错误状态 | 默认、图标、点状 | 错误态示例 | 仅图标错误态 | 同屏三种错误态 |
+| 垂直可选择 | 已完成实心、当前空心、右箭头 | 点击事件更新 current，标题由 current 派生 | 独立 `verticalSelect` 状态 | `TSteps.selectable` 固定垂直点状结构与必填回调；Demo 固定四项并动态更新状态标题 |
+| 纯展示 | 四个蓝色实心节点与连线 | readonly 禁止点击 | `readOnly` 与 Theme 重复持有 | `TSteps.display` 不公开进度和交互参数 |
+| 状态所有权 | 结构与交互分离 | props/event | Theme 与实例重复持有业务状态 | 命名构造分离 progress/selectable/display，`indicator` 只管指示器 |
+
+## 已记录的平台差异
+
+- 小程序支持 `defaultCurrent` 非受控模式；Flutter 保持受控 `value/onChange`，避免双状态源。
+- 小程序 change 事件是动态事件对象；Flutter 保持 `ValueChanged<int>` 强类型回调。
+- 小程序公开分组和新版 Figma 三组布局差异较大；Flutter 视觉与 Demo 顺序优先新版 Figma，操作模式参考小程序。
+- 新版 Figma 仅提供浅色画板；深色由 TDesign 语义 Token 和严格 Golden 独立验证。