@groupviz/react 2.0.0 → 2.1.1

package/components/Canvas/SublatticeScene.d.ts

@@ -45,6 +45,9 @@ export interface SublatticeSceneProps {
     /** 渲染主题（格取色 palette）。缺省回落到 ThemeContext（无 Provider 时 'dark'）；
      *  主应用壳不传即保持现状（读全局主题），包消费端显式传以与容器主题解耦 */
     theme?: 'dark' | 'light';
+    /** 本地枚举子群格的群阶上限（`order > 该值` 且未显式传 `lattice` 时不枚举、渲染空态）；
+     *  缺省 60（与 `findAllSubgroups` 内建守卫一致）。放开需自行确认性能与后端通路 */
+    maxEnumerateOrder?: number;
 }
 interface SeriesPanelProps {
     group: Group;
@@ -66,5 +69,5 @@ export declare function SeriesPanel({ group, series, color, theme: themeProp }:
  *  3. 省掉的文字不丢——底部 caption 行按 hover ?? 选中给出完整名片；密度真的高时
  *     用 `mergeConjugates` 把共轭子群合成一个轨道节点（×n，n = |G : N_G(H)|）。
  */
-export declare function SublatticeScene({ group, lattice, canvasTransform, availableSize, labelDetail, mergeConjugates, nodeScale, showSeriesPanel, series, centerIds, subsets, activeNodeIdx: activeNodeIdxProp, onActivateNode, noGroupText, theme: themeProp, }: SublatticeSceneProps): import("react/jsx-runtime").JSX.Element;
+export declare function SublatticeScene({ group, lattice, canvasTransform, availableSize, labelDetail, mergeConjugates, nodeScale, showSeriesPanel, series, centerIds, subsets, activeNodeIdx: activeNodeIdxProp, onActivateNode, noGroupText, theme: themeProp, maxEnumerateOrder, }: SublatticeSceneProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/components/Canvas/SymmetryViewScene.d.ts

@@ -1,3 +1,4 @@
+import type { SceneTheme } from './SceneThemeRoot.js';
 import type { Group } from '@groupviz/core';
 import type { SymmetryType } from '@groupviz/core';
 export interface SymmetryViewSceneProps {
@@ -28,7 +29,16 @@ export interface SymmetryViewSceneProps {
     /** 重放信号：宿主自增该值即对当前演示元素重播一次动画（姿态不改变目标，
      *  解决同元素动画播完一次后无入口重看的缺口）；缺省 0 */
     replaySignal?: number;
+    /** 显式主题（`'dark' | 'light'`）；与 `dark` 二选一，本项优先。
+     *  推荐新代码用 `theme` —— 与其余 Scene 命名统一（`dark` 作为兼容别名保留） */
+    theme?: SceneTheme;
+    /** 演示动画期间是否禁用相机旋转 / 平移；缺省 `false`。
+     *  **注意行为变更**：旧实现恒等于 `true`（`enableRotate = !showAction && !locked`），
+     *  导致"演示元素未命中 / 恒等元素时动画不跑，视角却已被锁死"。需要旧行为的宿主显式传 `true`。 */
+    lockCameraOnAction?: boolean;
+    /** 演示动画播放结束（姿态落定）回调；用于宿主编排「看完自动切下一个」等自定义流程 */
+    onAnimationEnd?: () => void;
 }
 /** 对称性视图纯渲染核（props 化、主题解耦）：Canvas + 场景 + 顶部标注 + 演示动画。
  *  主画布经 SymmetryView 适配器接入全局 context；ViewWindow（FGVE 引擎）受控直接使用。 */
-export declare function SymmetryViewScene({ group, symmetryType: symmetryTypeProp, dark, variant, showAction, actionElementId, rotateSpeed, showFigureTitle, locked, onHint, hintOnIdle, replaySignal, }: SymmetryViewSceneProps): import("react/jsx-runtime").JSX.Element;
+export declare function SymmetryViewScene({ group, symmetryType: symmetryTypeProp, dark, variant, showAction, actionElementId, rotateSpeed, showFigureTitle, locked, onHint, hintOnIdle, replaySignal, theme, lockCameraOnAction, onAnimationEnd, }: SymmetryViewSceneProps): import("react/jsx-runtime").JSX.Element;

package/components/Canvas/TableView.d.ts

@@ -1,3 +1,4 @@
+import { type SceneTheme } from './SceneThemeRoot.js';
 import type { CanvasTransform, Group, GroupElement, Subset } from '@groupviz/core';
 import type { CosetInfo } from '@groupviz/core';
 import type { TableStrategy } from '@groupviz/core';
@@ -39,5 +40,12 @@ export interface TableViewProps {
     onSelect?: (elId: string, additive: boolean) => void;
     onHover?: (el: GroupElement | null) => void;
     noGroupText?: string;
+    /** 文字乘法表「过大」阈值覆盖（群阶 > 该值时先出告警占位）；缺省 100（core.sizeLimitFor('table')） */
+    maxTableOrder?: number;
+    /** 热力图「过大」阈值覆盖；缺省 240（core.sizeLimitFor('heatmap')，聚合缩略图可承载更大群） */
+    maxHeatmapOrder?: number;
+    /** 视图主题作用域（`'dark' | 'light'`）。缺省不注入、跟随外层主题；显式传值时在本子树内
+     *  应用 `theme.css` 对应变量块（需宿主已 `import '@groupviz/react/theme.css'`） */
+    theme?: SceneTheme;
 }
-export declare function TableView({ group, selectedElements, viewBoxSize, canvasTransform, subsets: subsetsProp, cosetElementMap, cosetColors, cosetData: cosetDataProp, cosetType: cosetTypeProp, showAllCosets: showAllCosetsProp, forceShowLargeGroup, onForceShowLargeGroup, strategy: strategyProp, cellSize: cellSizeProp, showHeatmap, onStrategyChange, onLayoutSize, onSelect, onHover, noGroupText, }: TableViewProps): import("react/jsx-runtime").JSX.Element;
+export declare function TableView(props: TableViewProps): import("react/jsx-runtime").JSX.Element;

package/context/cayleyActions.d.ts

@@ -3,9 +3,12 @@ import { type CayleyShape2D } from '@groupviz/core';
 import type { CayleyActionParam } from '@groupviz/core';
 export declare function getInitialCayleyActions(group: Group): CayleyAction[];
 /**
- * 归一化凯莱视图作用边参数：过滤群中不存在的 elementId，补全 enabled（默认 true）与
+ * 归一化凯莱视图作用边参数：解析并过滤群中不存在的元素引用，补全 enabled（默认 true）与
  * color（默认 COLOR_PALETTE 按序）。actions 未提供时返回群生成元集合。
  * ViewWindow 参数面板与 CayleyView 渲染共用，保证两边对「当前边集合」的判定一致。
+ *
+ * `elementId` **接受元素引用**（`id` / `label` / `value` 串，见 `core.resolveElement`）：
+ * 传人类记号 `(234)` 不再被静默丢弃；确实解析不到时告警一次再忽略（不再无声无息）。
  */
 export declare function normalizeCayleyActions(group: Group, actions?: CayleyActionParam[]): CayleyAction[];
 export interface CayleyShapeConfig {

package/hooks/useSceneState.d.ts

@@ -0,0 +1,116 @@
+import { type CSSProperties, type ReactNode } from 'react';
+import type { CanvasTransform, Group, GroupElement, NodePosition } from '@groupviz/core';
+export interface SceneStateOptions {
+    /** 初始平移 / 缩放；缺省 `{ x:0, y:0, scale:1 }` */
+    initialTransform?: CanvasTransform;
+    /** 锁定交互（透传给 Scene 的 `locked`；同时禁用本 hook 的平移缩放） */
+    locked?: boolean;
+    /** 滚轮缩放开关；缺省 `true` */
+    enableZoom?: boolean;
+    /** 拖拽平移开关；缺省 `true` */
+    enablePan?: boolean;
+    /** 缩放下限；缺省 `0.25`（与主画布一致） */
+    minScale?: number;
+    /** 缩放上限；缺省 `8` */
+    maxScale?: number;
+    /** 受控选中集合（传入即受控，配合 `onSelectionChange`） */
+    selectedElements?: Set<string>;
+    /** 选中集合变更回调（受控 / 非受控都会触发，便于宿主记录） */
+    onSelectionChange?: (next: Set<string>) => void;
+    /** ResizeObserver 首帧前的兜底尺寸；缺省 `{ width:800, height:600 }` */
+    fallbackViewBoxSize?: {
+        width: number;
+        height: number;
+    };
+    /** 宿主容器附加样式（与内建样式合并，内建优先保证定位/尺寸） */
+    hostStyle?: CSSProperties;
+    /** hover 气泡主题；缺省 `'dark'` */
+    theme?: 'dark' | 'light';
+    /** hover 气泡自定义渲染；返回 `null` 表示禁用内建气泡 */
+    renderHoverBubble?: (el: GroupElement, anchor: {
+        x: number;
+        y: number;
+    } | null) => ReactNode;
+}
+/** 可直接 spread 到四类 2D Scene 的公共受控 props。 */
+export interface SceneStateProps {
+    selectedElements: Set<string>;
+    canvasTransform: CanvasTransform;
+    viewBoxSize: {
+        width: number;
+        height: number;
+    };
+    onSelect: (elId: string, additive: boolean) => void;
+    onHover: (el: GroupElement | null, anchor?: {
+        x: number;
+        y: number;
+    } | null) => void;
+}
+export interface SceneState {
+    /** 容器实测尺寸（ResizeObserver；首帧为兜底值） */
+    viewBoxSize: {
+        width: number;
+        height: number;
+    };
+    /**
+     * 宿主容器的 props —— **一次 spread 即可**：
+     *
+     * ```tsx
+     * const s = useSceneState(group)
+     * <div {...s.hostProps}><SetView group={group} {...s.sceneProps} />{s.hoverBubble}</div>
+     * ```
+     *
+     * 内含 `ref`（回调 ref）、内建样式（定位/尺寸/`touchAction`/光标）与拖拽平移事件。
+     *
+     * ⚠️ 别在 spread 之后再写 `ref`：那会顶掉内建 ref，尺寸测量与悬浮气泡换算会静默失效。
+     * 需要 DOM 节点请用 `getHostElement()`。
+     *
+     * 设计说明：ref 只以**嵌套**形式出现在 `hostProps` 里，绝不作为顶层字段暴露。
+     * React Compiler 的 `react-hooks/refs` 规则会把「顶层返回了写 ref 的回调」的 hook
+     * 整体判为 ref 载体，此后宿主每次 `s.xxx` 读取都会报「渲染期访问 ref」；
+     * 嵌套形式不触发该判定（实测）。
+     */
+    hostProps: {
+        ref: (el: HTMLDivElement | null) => void;
+        style: CSSProperties;
+        onMouseDown: (e: React.MouseEvent) => void;
+        onMouseMove: (e: React.MouseEvent) => void;
+        onMouseUp: () => void;
+        onMouseLeave: () => void;
+    };
+    /** 需要 DOM 节点时用（如导出 SVG）：取宿主容器元素 */
+    getHostElement: () => HTMLDivElement | null;
+    canvasTransform: CanvasTransform;
+    setCanvasTransform: (t: CanvasTransform) => void;
+    selectedElements: Set<string>;
+    setSelectedElements: (next: Set<string> | ((prev: Set<string>) => Set<string>)) => void;
+    /** 选中语义：`additive`（⊕/Ctrl/⌘）→ 切换成员；否则 → 单选替换 */
+    select: (elId: string, additive?: boolean) => void;
+    clearSelection: () => void;
+    /** 当前悬停元素（`onHover` 自动维护） */
+    hovered: GroupElement | null;
+    /** 悬停锚点（viewBox 坐标系下映射到容器内的屏幕坐标） */
+    hoverAnchor: {
+        x: number;
+        y: number;
+    } | null;
+    /** 内建 hover 气泡节点（可直接 `{s.hoverBubble}`；想自己画就用 `renderHoverBubble`） */
+    hoverBubble: ReactNode;
+    /** 直接 spread 给 SetView / CycleView / CayleyView / CosetStripScene */
+    sceneProps: SceneStateProps;
+    /** 复位平移缩放 */
+    resetTransform: () => void;
+    /** 以容器中心为锚缩放（按钮用，`factor > 1` 放大） */
+    zoomBy: (factor: number) => void;
+    /** 是否锁定（= `options.locked`） */
+    locked: boolean;
+    /** 共享节点位置：接 `CycleView.getNodePosition` */
+    getNodePosition: (elId: string) => NodePosition | undefined;
+    /** 共享节点位置：接 `CycleView.onNodePositionChange` */
+    onNodePositionChange: (elId: string, x: number, y: number) => void;
+    /** 清空共享节点位置 */
+    resetNodePositions: () => void;
+}
+export declare function useSceneState(group?: Group | null, options?: SceneStateOptions): SceneState;
+/** 无群 / 无操作时的稳定引用（供宿主做默认值，避免每次新建对象触发重渲染）。 */
+export declare const SCENE_STATE_NOOP: () => void;

package/i18n/I18nContext.d.ts

@@ -6,6 +6,12 @@ export interface I18nContextValue {
     t: (key: string, params?: Record<string, string | number>) => string;
 }
 export declare const I18nContext: import("react").Context<I18nContextValue>;
-export declare function I18nProvider({ children }: {
+export interface I18nProviderProps {
     children: ReactNode;
-}): import("react/jsx-runtime").JSX.Element;
+    /** 初始语言；缺省按 `getDefaultLang()`（读 localStorage / 浏览器语言） */
+    lang?: Lang;
+    /** 是否把语言选择写入 `localStorage('groupviz-lang')`；缺省 `true`。
+     *  嵌入宿主不希望与主应用抢同一 key 时可传 `false`。 */
+    persist?: boolean;
+}
+export declare function I18nProvider({ children, lang: langProp, persist }: I18nProviderProps): import("react/jsx-runtime").JSX.Element;