@pieai/swimmer-ui-kit 3.1.0 → 3.2.1

package/CHANGELOG.md

@@ -5,7 +5,29 @@ Format: [Keep a Changelog](https://keepachangelog.com); versioning: semver.
 
 ## Unreleased
 
-## 3.1.0 — 本地候选（2026-10-10，待发布到 latest）
+## 3.2.1 — 本地候选，待发布到 npm latest
+
+- 修正服务端渲染时 `GameHelpCard` 与 `GameTooltip` 的崩溃。当 Server Component 构造好触发器（例如 `GameIconButton href=…`）并作为子元素传入时，子元素可能以惰性元素到达；3.2.0 读取它的 `props` 会报 `Cannot read properties of undefined (reading 'ref')`，页面的服务端渲染与生产预渲染都会失败。现在这类子元素放在一个不占布局的 `game-ui-trigger-slot` 中，挂载后把 `aria-expanded` 与 `aria-controls`（卡片）或 `aria-describedby`（提示）加到第一个可聚焦元素上，卸载时移除。悬停、焦点、Escape，以及触摸“第一次点按只打开、第二次才执行”的规则不变；内层链接不会因第一次触摸而跳转。在客户端组件中构造的触发器保留原始元素，DOM 与行为与 3.2.0 相同。
+- 惰性触发器会在挂载时打印一条 `console.warn`，建议改在客户端组件中构造；每个组件只打印一次，不按构建模式关闭，因为发布后的库无法看到使用方的构建模式。
+- `GameTooltip` 此前不会崩溃，但惰性触发器读不到 `aria-describedby`；现在补上。
+- `GameHelpCard` 的一到三个主题页签在 340 像素卡片内保持一行，中文 `懒人包 / 设定图 / 选角单` 与英文 `Starter pack / Sheet / Cast` 在浅色、深色与任一页签选中时都不截断。页签的一行规则只写一次，由 `GameTabs` 的样式统一提供；`GameAccountMenu` 的等宽页签与 3.2.0 外观相同。
+- 新增两个页签故事（中文与英文）、页签一行的浏览器测试、惰性触发器的单元与浏览器测试，以及真实 Next 消费检查中的服务端触发器用例。该用例在 3.2.0 候选上复现了上述构建失败。
+- 公开名字与参数不变，没有删除或改名。版本号改为 3.2.1。
+
+## 3.2.0 — 2026-10-10（已发布到 npm latest）
+
+- 新增 `GameHelpCard`：帮助的第二级。悬停（经过 `openDelay`，默认 200 毫秒）、键盘聚焦或点按后打开一张小卡片，含一个标题、一到三行正文（`\n` 换行）、可选的循环短演示和“完整指南”链接；一到四个主题时用页签切换。卡片的可访问名称由 `label` 提供，触发器获得 `aria-expanded` 与 `aria-controls`。
+- 行为：鼠标指针可移入卡片切换页签或点击链接，离开约 150 毫秒后关闭；键盘 Tab 进入卡片，Escape 关闭并回到触发器，焦点不被抢走；触摸的第一次点按只打开卡片、阻止触发器动作，第二次点按才执行，点击卡片外关闭。
+- 媒体只在卡片第一次打开、并且所在主题被选中时才请求；视频静音、循环，只在可见时播放；系统要求减少动态时不自动播放，显示 `poster`。`width` / `height` 预留位置，打开时不跳动；`alt` 作为媒体的可访问文字。
+- 卡片经门户离开触发器的主题子树后，会复制触发器所在的 `data-game-ui-theme` / `data-game-ui-style` 与主题级 `--game-ui-*` 令牌，并在它们变化时同步；深色与风格因此与触发器一致。卡片自己的圆角不被继承。
+- 与 `GameTooltip` 一样使用静止水滴，不使用液体引擎或 LiquidPopover，因此不进入液体预算。公开名字新增 `GameHelpCard`、`GameHelpCardProps`、`GameHelpCardTopic`、`GameHelpMedia`；没有删除或改名。
+- 根入口体积：153,482 字节（gzip 44,908）增至 158,197 字节（gzip 46,152），增加 4,715 字节（约 4.6 KB，minified）。
+- 组件选择指南新增“帮助提示怎么选”，列出四级帮助及不适合放进帮助卡的内容；接口清单与迁移表由生成器更新，根入口为 133 个名字（56 个值、77 个类型）。
+- `GameAccountMenu` 的页签在 360 像素面板内保持一行：三个页签等宽（`flex: 1 1 0`），标签单行并以省略号截断，未选中的页签不再为隐藏的对勾预留宽度。页签文字包在 `GameTabs` 的 `game-ui-tab-label` 内，公开接口不变。新增 360 像素布局测试。
+- `GameAccountMenu` 的选中页签文字：在六种风格与两种明暗下，选中页签文字与其填充的对比度均不低于 6.8:1，并由新增的对比度测试守护。本仓库的故事与浏览器检查没有复现文字不可见；若产品仍遇到，请提供风格、明暗与页面结构，不需要产品覆写。
+- 版本号改为 3.2.0。发布前 npm `latest` 为 3.1.0，`next` 为 3.0.0-rc.3。
+
+## 3.1.0 — 已发布到 npm latest（2026-10-10）
 
 - 新增 `GameAccountMenu`：登录后的共享账号入口，从 `@pieai/swimmer-ui-kit/liquid-presence` 导入。头像与名字是 sm 次要按钮；点击打开一个液体面板，含产品提供的站内内容、全部产品列表（当前产品为纯文字，其余为真实链接）和账号页签（管理账号与安全、退出登录）。只有账号页签时不显示页签条。
 - 产品拥有用户、产品列表、目的地址和所有登录、退出动作；组件不联网、不存储、不做认证。退出按钮处理中显示 `pending` 但不禁用，组件忽略处理中的重复点击。头像只渲染 https 图片，否则显示首字母。
@@ -13,6 +35,7 @@ Format: [Keep a Changelog](https://keepachangelog.com); versioning: semver.
 - `GameTooltip` 新增可选 `align`（center / start / end）与 `placement`（top / bottom），向后兼容：默认仍居中于上方。长标签在 280px 内换行，标签中的换行保留。
 - 根入口公开名字不变（129 个）；迁移表与接口清单由生成器更新。`GameAccountMenu` 与其三个类型只从 liquid-presence 入口公开。没有删除或改名。
 - 版本号改为 3.1.0；发布前 npm `latest` 为 3.0.0，`next` 为 3.0.0-rc.3。
+- 发布记录：2026-10-10 16:19（+08）由 Claude 发布到 npm `latest`，发布的 tarball 为本地候选 `.scratch/release-3.1.0/swimmer-ui-kit-3.1.0.tgz`，SHA-256 `1954dd118ce94caba0d07aeed656dd48e668a5036894b0133e726af5cb9bdd28`。只读核对：registry 的 sha512 完整性与该候选一致；`latest` 为 3.1.0，`next` 为 3.0.0-rc.3。
 
 ## 3.0.0 — 已发布到 npm latest（2026-10-10）
 

package/README.md

@@ -2,7 +2,7 @@
 
 Swimmer 的共享 React UI：普通控件是平面水滴，主线 CTA 是潮汐液体。支持六套风格与独立明暗，表单、焦点、键盘和编辑内容仍由原生 DOM 承接。它不拥有产品数据、模型调用、账号验证或支付。
 
-**3.0.0 已发布到 npm latest（2026-10-10）。3.1.0 为本地候选（新增账号菜单与 GameTooltip 位置选项），待发布到 npm latest；发布前 latest 仍为 3.0.0。** 3.0.0-rc.1 与 rc.3 已发布到 npm next。现有产品继续锁定精确版本；主动升级先读[迁移表](docs/reference/migration-3.0.md)，发布证据见[当前工作](docs/reference/execution/current-work.md)。本仓库不自动升级任何产品。
+**3.0.0、3.1.0 与 3.2.0 已发布到 npm latest（3.2.0 于 2026-10-10 发布，新增 GameHelpCard）。3.2.1 为本地候选（修正 GameHelpCard 与 GameTooltip 的服务端触发器，页签一行），待发布到 npm latest；发布前 latest 为 3.2.0。** 3.0.0-rc.1 与 rc.3 已发布到 npm next。现有产品继续锁定精确版本；主动升级先读[迁移表](docs/reference/migration-3.0.md)，发布证据见[当前工作](docs/reference/execution/current-work.md)。本仓库不自动升级任何产品。
 
 ## 安装与最小使用
 

package/dist/{GameAvatar-CRJ1r8l5.js → GameAvatar-Cs5KVYFf.js}

@@ -866,7 +866,10 @@ function le({ activeId: e, id: t, onSelect: n, tabs: r, hue: i, orientation: a =
 			"data-game-ui-paint": "",
 			children: [
 				/* @__PURE__ */ h(Y, {}),
-				t.label,
+				/* @__PURE__ */ h("span", {
+					className: "game-ui-tab-label",
+					children: t.label
+				}),
 				/* @__PURE__ */ h(X, {})
 			]
 		}, t.id))