@groupviz/react 2.1.0 → 2.1.2

package/API.md

@@ -35,15 +35,19 @@ export function Figure() {
 
 ## 1. 元素引用（element reference）—— 所有元素类 props 的通用约定
 
-群元素同时有两种记号：
+群元素同时有多种记号：
 
 | 记号 | 来源 | 例子（S₄） |
 |---|---|---|
 | `id` | 机器键，`GroupElement.id` | `"1,3,4,2"` |
-| `label` | 人类记号，`GroupElement.label` | `"34"` / `"e"` |
+| `label` | 人类记号，`GroupElement.label` | `"34"` / `"234"` / `"(12)(34)"` / `"e"` |
 | `value` | 数组，`GroupElement.value` | `[1,3,4,2]` |
+| 循环记号 | 手写置换 | `"(234)"` / `"(12)(34)"` / `"(1 2 3)"` |
 
-**下列 props 接受任一记号**，内部统一经 `core.resolveElement` 解析（匹配序 `id` → `label` → `value`，忽略空白）：
+> `label` 约定**因群而异**：Aₙ 带括号（`(234)`），Sₙ 单环不带括号（`234`）、多环带括号（`(12)(34)`），循环群为指数（`3`），同构群为 `\alpha_3`。
+> **不必记住用哪套**——手写标准循环记号即可，`resolveElement` 会按语义解析成同一个置换。
+
+**下列 props 接受任一记号**，内部统一经 `core.resolveElement` 解析（匹配序 `id` → `label` → `value` → **循环记号语义档**，忽略空白）：
 
 | 归属 | prop |
 |---|---|
@@ -326,11 +330,12 @@ import { I18nProvider, useTranslation } from '@groupviz/react'
 
 | 导出 | 签名 | 说明 |
 |---|---|---|
-| `resolveElement` | `(group, ref) => GroupElement \| null` | 元素引用解析（`id` → `label` → `value`，忽略空白） |
+| `resolveElement` | `(group, ref) => GroupElement \| null` | 元素引用解析（`id` → `label` → `value` → **循环记号**，忽略空白） |
 | `findElement` | 同上 | `resolveElement` 的别名 |
 | `resolveElementRefs` | `(group, refs) => { elements, ids, unresolved }` | 批量解析 + 未命中回收 |
 | `resolveElementIds` | `(group, refs) => string[]` | 批量解析为规范 id（去重、丢未命中） |
 | `normalizeElementRef` | `(ref) => string` | 去空白归一化 |
+| `parseCycleNotation` | `(ref, degree) => number[] \| null` | 循环记号 → 置换数组；`(234)`/`234`/`(12)(34)`/`(1 2 3)` 均可，非循环记号返回 `null` |
 | `elementOrder` | `(group, el) => number` | 元素阶（group-first 公共入口） |
 | `elementOrderDistribution` | `(group) => Map<number, number>` | 阶分布 |
 | `elementOrderDistributionOf` | `(elements, group) => Map<number, number>` | 子集阶分布 |

package/README.md

@@ -68,12 +68,12 @@ import '@groupviz/react/theme.css' // 主题样式（模块化工程可 import
 **交互约定**：Scene 是纯受控内核——标签显隐 / hover 气泡 / 选中高亮等由宿主通过 props
 （`showLabels` / `onHover` / `onSelect`）注入。
 
-**完整 props 全表**：见包内 [API.md](./API.md)（10 个 Scene 逐项 + 便利层 + core 新增导出）；
-更多组合示例见仓库 `examples/host-minimal/`。
+**完整 props 全表**：见 [docs/API.md](https://github.com/rrCathy/GroupViz/blob/main/docs/API.md)（10 个 Scene 逐项 + 便利层 + core 新增导出；该文件亦随包分发）；
+更多组合示例见 [examples/host-minimal/](https://github.com/rrCathy/GroupViz/tree/main/examples/host-minimal)。
 
 **稳定性**：当前公开 API 为 2.x——破坏性变更才会升 major（core 与 react 成对同版发布，react peer 锁 core `^2.x`），
 非破坏性演进在 minor/patch 内进行；变更记录见 [GroupViz CHANGELOG](https://github.com/rrCathy/GroupViz/blob/main/docs/CHANGELOG.md)。
 
 **来源**：本包由 GroupViz 主仓库 `src/package/` 门面构建发布（单仓库内子目录产出，非 monorepo），
-完整组件 / 交互文档：[GroupViz 主仓库](https://github.com/rrCathy/GroupViz)（docs/VIEWS.md · docs/PRESENTATION.md）。
+完整组件 / 交互文档：[GroupViz 主仓库](https://github.com/rrCathy/GroupViz)（[docs/VIEWS.md](https://github.com/rrCathy/GroupViz/blob/main/docs/VIEWS.md) · [docs/PRESENTATION.md](https://github.com/rrCathy/GroupViz/blob/main/docs/PRESENTATION.md)）。
 MIT License。

package/index.js

@@ -726,7 +726,7 @@ function Ce(e, t, n) {
 	if (r) return r;
 	if (!e || t == null || t === "") return null;
 	let i = `${n}|${e.symbol}|${t}`;
-	return Se.has(i) || (Se.add(i), console.warn(`[groupviz] ${n}: 元素引用 ${JSON.stringify(t)} 在群 ${e?.symbol ?? "?"} 中解析不到（已试 id / label / value 三种记号），该项已忽略。`)), null;
+	return Se.has(i) || (Se.add(i), console.warn(`[groupviz] ${n}: 元素引用 ${JSON.stringify(t)} 在群 ${e?.symbol ?? "?"} 中解析不到（已试 id / label / value / 循环记号四种写法），该项已忽略。`)), null;
 }
 function we(e, t, n) {
 	if (!t) return [];
@@ -1090,7 +1090,7 @@ var je = {
 		"theme.viewWindowDark": "视图窗口切换为浅色",
 		"theme.viewWindowLight": "视图窗口切换为深色",
 		"welcome.subtitle": "群论可视化平台",
-		"welcome.version": "v2.1.0",
+		"welcome.version": "v2.1.2",
 		"welcome.tagline": "探索抽象代数的对称之美 — 交互式群论可视化与学习工具",
 		"welcome.enter": "进入应用",
 		"welcome.section.done": "已实现",
@@ -1719,7 +1719,7 @@ var je = {
 		"theme.viewWindowDark": "View windows: switch to light",
 		"theme.viewWindowLight": "View windows: switch to dark",
 		"welcome.subtitle": "Group Theory Visualization Platform",
-		"welcome.version": "v2.1.0",
+		"welcome.version": "v2.1.2",
 		"welcome.tagline": "Explore the beauty of symmetry in abstract algebra — Interactive group theory visualization & learning tool",
 		"welcome.enter": "Enter",
 		"welcome.section.done": "Implemented",