component-canvas

组件画布

构建一个画布，展示项目中现有组件的实际表现。画布会包裹组件，但绝不会修改它们。

基本规则

• 不要为了让画布正常工作而修改组件源码、导出项、样式、钩子或行为。组件不得导入或依赖画布代码。
• 不要修补库、浏览器 API、渲染后的组件 DOM 或 portal 根节点。
• 只展示用户指定的组件。添加组件、安装依赖、更改组件设计或公开画布，都必须先获得许可。
• 保留现有访问控制。
• 不要影响无关工作。如果要移除之前的画布集成，只撤销对组件所做的更改。
• 遵守关于命令、浏览器访问、依赖和编辑的任何限制。

开始构建前

阅读仓库约定、路由、组件公共 API、设计令牌和测试设置。使用现有框架和库。

仅在答案会改变构建内容或影响共享代码时询问用户：要包含哪些组件、是否可以添加新依赖，或是否可以预览实时服务。其他情况一律采用合理的默认方案，在报告中说明后继续。

构建顺序

1. 添加一个最精简的画布路由或入口，包含一个分组和一个组件。确认其正常工作。
2. 添加其余分组和示例数据。
3. 先添加变体对比，再逐项添加高级手势和持久化功能。

将画布代码集中在一处。移动文件时检查导入和包导出项。遵循项目的语言、验证和测试约定。不要添加项目中尚未采用的架构层或目录名称。

将布局和镜头逻辑与示例数据及组件源码分开。

布局

• 用纯色背景填满视口。
• 如果项目已支持浅色和深色主题，则使用现有主题 API 添加一个无障碍切换开关，并将所选主题应用到画布和原生 portal。如果不支持主题，则省略切换开关。不要自行创建主题或更改组件样式。
• 为每个分组设置相同的内边距、圆角和细虚线边框，在两种主题下都保持低调但清晰可见。边框使用现有的柔和色彩，透明度约为 25%。在边框上方 8px 处放置普通标题，使用不带透明度的柔和文字颜色。
• 使用宽分组，每行布置等宽的示例位置。需要时换行，并在分组内部及分组之间保留充足的水平和垂直间距。合理铺开布局，但不要放大组件。
• 不允许拖动分组。分组位置无需硬编码。测量其实际边界，包括标题、边框和内边距。忽略用于渲染约束的占位元素（在内容渲染前预留空间的空框），因为它们不能反映实际内容尺寸。
• 不要添加背景圆点、装饰卡片、页面菜单、说明横幅、选择工具或区块编辑功能。组件卡片和菜单可以作为示例显示。

变体

• 在请求的范围内展示所有受支持的命名变体和实用状态。查阅公开 API，了解样式、文本和图标尺寸、方向、位置、对齐方式、模态行为和折叠模式。
• 加入实用的内容和组合示例。
• 不要臆造变体，也不要生成所有属性组合。列出省略的内容及原因。
• 每次只比较一个属性或功能。其他内容保持不变：使用相同的包装器、示例数据、文本、图标、主题和间距。
• 进行样式比较时，只更改样式变体。尺寸、状态、位置和其他比较均使用同一种样式，通常为默认样式。

示例：在尺寸比较中，每个按钮都显示“Continue”，并使用 variant="default"。只更改 size。样式比较则更改 variant，并保持尺寸和文本不变。

• 保留组件自身的状态样式（禁用时的不透明度、选中时的颜色）。除非展示禁用或只读状态，否则示例应能响应输入。
• 通过真实的鼠标和键盘输入测试悬停、焦点和按下状态，不要通过添加类名来模拟。
• 对于传送门示例，每次都使用相同的触发器。不要同时强制打开多个模态框。
• 保留变体列表和覆盖率测试。项目支持时使用类型。
• 如果组件无法展示某种响应式或视觉效果，请说明限制。不要更改组件来伪造效果。

交互

• 点击、文本选择、键入、按钮和开关的激活、焦点以及嵌套滚动都必须正常工作。
• 画布快捷键（空格、方向键、Escape、原生撤销）仅作用于画布外壳。不得让预览控件失去对这些按键的响应。
• 在画布宿主中处理预览导航。指向画布分组的链接应移动镜头，而不是滚动页面。明确说明如何处理离开画布的链接，包括传送门内的链接。不要更改组件链接或路由器内部逻辑。
• 传送门应留在其原生根节点中，并保持屏幕空间尺寸。让库处理定位和模态焦点。仅在必要时使用公开的容器选项。检查画布变换下的定位和可点击区域。如果出现问题，请报告或提出使用独立预览文档的方案。不要修补组件。
• 画布不支持撤销/重做、编辑快捷键或历史记录。

预览安全

在挂载前确保每个预览都是安全的：

• 使用带测试数据的提供程序、模拟服务或现有回调属性，阻止实时调用和实际写入。
• 可以使用静态演示资源和本地测试数据。
• 绝不使用生产凭据或数据。
• 如果无法安全隔离，请省略实时示例并说明原因。仅使用独立文档并不能确保预览安全。

镜头

• 鼠标和触控板：平移，并围绕光标缩放。触摸：平移和双指捏合缩放。
• 从画布空白处开始普通平移。预览和传送门内部应保留原生手势。
• 不要广泛取消事件，也不要在交互内容上设置 touch-action: none。
• 处理指针数量变化、操作取消、失去捕获、窗口失焦和标签页隐藏。销毁时释放捕获，并清理监听器、观察器、计时器和动画帧。
• 每个动画帧最多应用一次手势变换。避免交替执行布局读取和写入。
• 内容扩展或视口调整大小时，避免分组重叠。避免布局循环和不必要的移动。布局稳定后再适配视图。适配操作绝不重新排列分组。
• 将镜头移至可见区域之外的键盘焦点处。原生页面滚动不得移动画布。
• 键盘镜头导航应可用，且画布控件应显示焦点。
• 提供带有无障碍名称的“适配全部”和“重置”图标按钮。即使视图丢失，这些按钮仍应可访问。
• 验证镜头数值，并将其限制在有效范围内。

持久化

• 仅以带版本号的格式保存摄像机状态，并为每个项目或工作区使用单独的存储键。
• 处理格式错误或过大的数据、存储不可用以及配额错误。
• 迁移已知的旧格式。对于未知格式，使用安全默认值并丢弃旧的分组位置和历史记录。
• 重置仅恢复摄像机状态，不清除预览状态或草稿。

检查

在允许的情况下运行仓库的检查。然后在浏览器中确认：

• 路由已挂载，导入和导出均可解析，控制台无错误。
• 组件源代码未更改。
• 所列变体均已显示，遗漏项均有说明，分组带有虚线边框，非样式比较使用同一种样式。
• 摄像机键盘导航和可见焦点正常。预览控件保留原生快捷键和手势。
• 在多个缩放级别和视口尺寸下，嵌套滚动、Portal 定位、可点击区域和模态框焦点均正常。
• 平移和双指缩放在指针变化及取消后仍正常。拆卸时会释放资源。
• 分组展开或调整大小后不会重叠。适配功能正常，离屏焦点能正确显示。
• 摄像机状态会在重新加载后保留。存储失败时会安全回退。重置会保留预览草稿。除非另有要求，草稿无需在重新加载后保留。
• 分组无法拖动。画布没有撤销/重做功能。
• 预览使用安全的测试数据，不会对真实项目或帐户进行写入。

只有实际运行过的检查才算通过。如果跳过了某项检查，请说明。

报告

每次构建或审查结束时，都使用以下标题：

• **更改：**列出文件及各文件的更改内容。注明任何组件更改（应为无）。
• **运行的检查：**列出每项检查及其结果。
• **未正常工作或未测试：**已知缺陷、遗漏的变体及原因，以及任何未经验证的内容。
• **所作决定：**列出未经询问而采用的默认设置。

除非以上所有检查均已通过，否则不要将实现描述为已验证，也不要称模板已就绪。