@gadmin2n/schematics 0.0.96 → 0.0.97

package/dist/lib/application/files/gadmin2-game-angle-demo/web/src/components/layout/sider.tsx

@@ -3,6 +3,7 @@ import React, {
   useEffect,
   useRef,
   useCallback,
+  useState,
   type CSSProperties,
 } from 'react';
 
@@ -35,19 +36,25 @@ import {
 } from 'antd';
 import { Title } from './title';
 import { agentAttrs } from 'components/agentPanel/agentAttributes';
+import {
+  HEADER_HEIGHT,
+  SIDER_WIDTH,
+  SIDER_COLLAPSED_WIDTH,
+  Z_INDEX,
+} from 'constants/layout';
+
+const { SubMenu: _SubMenu } = Menu; // eslint silencer; preserved for future use
+void _SubMenu;
+const { useToken } = theme;
 
-const drawerButtonStyles: CSSProperties = {
-  borderTopLeftRadius: 0,
-  borderBottomLeftRadius: 0,
-  position: 'fixed',
-  top: 64,
-  zIndex: 1001,
-};
-
-let reRouteNum = 0;
+/**
+ * Auto-redirect 安全阀: 一次 mount 周期内允许的最大重定向次数。
+ * 超过这个次数说明已经在 ping-pong, 应该停手避免死循环。
+ */
+const MAX_AUTO_REDIRECTS = 5;
 
-const { SubMenu } = Menu;
-const { useToken } = theme;
+/** Auto-redirect 触发延迟, 让 selectedKey / items 在同一帧内尘埃落定 */
+const AUTO_REDIRECT_DEBOUNCE_MS = 300;
 
 const getParentKeysFromMenuTree = (
   items: ITreeMenu[],
@@ -85,16 +92,41 @@ const getMenuLabel = (
   return meta?.label || name;
 };
 
+/** 共用的标题栏（移动端 Drawer 与桌面 Sider 头部都用） */
+const SiderTitleBar: React.FC<{ collapsed: boolean }> = ({ collapsed }) => {
+  const { token } = useToken();
+  return (
+    <div
+      {...agentAttrs({ type: 'app-title' })}
+      style={{
+        width: collapsed ? SIDER_COLLAPSED_WIDTH : SIDER_WIDTH,
+        padding: collapsed ? 0 : '0 16px',
+        display: 'flex',
+        justifyContent: collapsed ? 'center' : 'flex-start',
+        alignItems: 'center',
+        height: HEADER_HEIGHT,
+        backgroundColor: token.colorBgElevated,
+        borderBottom: `1px solid ${token.colorBorderSecondary}`,
+      }}
+    >
+      <Title collapsed={collapsed} />
+    </div>
+  );
+};
+
 export const Sider: React.FC = () => {
   const { token } = useToken();
   const { menuItems, selectedKey, defaultOpenKeys } = useMenu();
   const { pathname: currentPathname } = useLocation();
-  const { t, i18n } = useTranslation();
+  const { i18n } = useTranslation();
   const currentLocale = i18n.language;
 
-  const [openKeys, setOpenKeys] = React.useState<string[]>(defaultOpenKeys);
+  const [openKeys, setOpenKeys] = useState<string[]>(defaultOpenKeys);
 
   const lastSelectedKeyRef = useRef<string | undefined>(undefined);
+  // 之前是 module-level 的 `let reRouteNum = 0`, 跨多个 mount 共享, HMR 后永远写死.
+  // 改成 useRef 让每次 mount 拿到独立计数器, 而仍然跨同一 mount 内的多次 effect 触发.
+  const redirectCountRef = useRef(0);
 
   useEffect(() => {
     if (
@@ -131,15 +163,20 @@ export const Sider: React.FC = () => {
   const renderTreeView = useCallback(
     (tree: ITreeMenu[], currentSelectedKey?: string): MenuProps['items'] => {
       return tree
-        .map((item: ITreeMenu) => {
+        .map((item: ITreeMenu, index: number) => {
           const { key, name, children, meta = {}, list } = item;
           const { icon, parent: parentName } = meta;
 
           const route = typeof list === 'string' ? list : listUrl(name);
 
+          // 优先用 item.key, 退而求其次用 name (永远存在), 最后才用稳定的 path-index.
+          // 之前用 Math.random() 作为 fallback —— 那是 React 反模式, 每次渲染都换 key
+          // 会让整棵子树 unmount/mount, 破坏滚动位置和动画状态.
+          const stableKey = key || name || `fallback-${index}`;
+
           if (children.length > 0) {
             return {
-              key: item.key || Math.random().toString(),
+              key: stableKey,
               label: (
                 <span style={{ fontWeight: 600 }}>
                   {getMenuLabel(name, meta, currentLocale)}
@@ -150,15 +187,14 @@ export const Sider: React.FC = () => {
             };
           }
 
-          const menuItemKey = item.key || Math.random().toString();
-          const isSelected = menuItemKey === currentSelectedKey;
+          const isSelected = stableKey === currentSelectedKey;
           const isRoute = !(
             pickNotDeprecated(meta?.parent, meta?.parent, parentName) !==
               undefined && children.length === 0
           );
 
           return {
-            key: menuItemKey,
+            key: stableKey,
             label: (
               <>
                 <Link to={route ?? ''}>
@@ -181,9 +217,10 @@ export const Sider: React.FC = () => {
     return renderTreeView(menuItems, selectedKey)?.filter(Boolean);
   }, [menuItems, selectedKey, renderTreeView]);
 
-  // Auto-redirect to first available menu item if current selectedKey is not in the menu
+  // Auto-redirect to first available menu item if current selectedKey is not in the menu.
+  // 触发条件: items / selectedKey / pathname 变化.
   useEffect(() => {
-    if (reRouteNum > 5) return;
+    if (redirectCountRef.current >= MAX_AUTO_REDIRECTS) return;
 
     const isKeyInMenuItems = (
       menuItems: MenuProps['items'],
@@ -201,12 +238,12 @@ export const Sider: React.FC = () => {
       return false;
     };
 
-    // If selectedKey is in the menu, no need to redirect
+    // selectedKey 已经在菜单里, 不需要重定向.
     if (selectedKey && isKeyInMenuItems(items, selectedKey)) {
       return;
     }
 
-    // Skip auto-redirect for CRUD detail pages (edit/show/create)
+    // Skip auto-redirect for CRUD detail pages (edit/show/create).
     // These pages are not in the menu but are valid navigation targets.
     // Also skip auto-generated /admin/data-mngt/* CRUD list pages —
     // some of them are intentionally hidden from the sidebar via
@@ -224,36 +261,41 @@ export const Sider: React.FC = () => {
     }
 
     const timer = setTimeout(() => {
-      reRouteNum++;
+      redirectCountRef.current += 1;
 
       const firstKey = items?.[0]?.key;
-      if (firstKey && firstKey !== '/dashboard') {
-        setOpenKeys([String(firstKey)]);
-        const firstItem = items?.find((item) => item?.key === firstKey) as any;
-        if (firstItem?.children?.length > 0) {
-          let childItem = firstItem?.children?.find(
-            (item: any) => selectedKey.indexOf(item?.key) !== -1,
-          );
-          if (!childItem) {
-            childItem = firstItem?.children?.[0];
-          }
-          const childKey = childItem?.key;
-          if (childItem?.children?.length > 0) {
-            setOpenKeys([String(firstKey), String(childKey)]);
-            const grandsonItem = childItem?.children?.find(
-              (item: any) => selectedKey.indexOf(item?.key) !== -1,
-            );
-            const grandsonKey =
-              grandsonItem?.key || firstItem?.children?.[0]?.children?.[0]?.key;
-            go({ to: grandsonKey, type: 'replace' });
-          } else {
-            go({ to: childKey, type: 'replace' });
-          }
-        } else {
-          go({ to: String(firstKey), type: 'replace' });
+      if (!firstKey || firstKey === '/dashboard') return;
+
+      setOpenKeys([String(firstKey)]);
+      const firstItem = items?.find((item) => item?.key === firstKey) as any;
+      if (!firstItem?.children?.length) {
+        go({ to: String(firstKey), type: 'replace' });
+        return;
+      }
+
+      const safeSelectedKey = selectedKey ?? '';
+      let childItem = firstItem.children.find((child: any) =>
+        safeSelectedKey.includes(String(child?.key ?? '')),
+      );
+      if (!childItem) {
+        childItem = firstItem.children[0];
+      }
+      const childKey = childItem?.key;
+
+      if (childItem?.children?.length) {
+        setOpenKeys([String(firstKey), String(childKey)]);
+        const grandsonItem = childItem.children.find((g: any) =>
+          safeSelectedKey.includes(String(g?.key ?? '')),
+        );
+        const grandsonKey =
+          grandsonItem?.key ?? firstItem.children[0]?.children?.[0]?.key;
+        if (grandsonKey) {
+          go({ to: String(grandsonKey), type: 'replace' });
         }
+      } else if (childKey) {
+        go({ to: String(childKey), type: 'replace' });
       }
-    }, 300);
+    }, AUTO_REDIRECT_DEBOUNCE_MS);
 
     return () => clearTimeout(timer);
   }, [items, selectedKey, currentPathname, go]);
@@ -284,35 +326,51 @@ export const Sider: React.FC = () => {
     [menuItems, setMobileSiderOpen],
   );
 
-  const renderMenu = useCallback(() => {
-    return (
-      <Menu
-        selectedKeys={selectedKey ? [selectedKey] : []}
-        defaultOpenKeys={defaultOpenKeys}
-        openKeys={openKeys}
-        onOpenChange={handleOpenChange}
-        mode="inline"
-        items={items}
-        style={{
-          paddingTop: '8px',
-          border: 'none',
-          overflow: 'auto',
-          height: 'calc(100% - 72px)',
-          background: 'transparent',
-        }}
-        onClick={handleMenuClick}
-      ></Menu>
-    );
-  }, [
-    selectedKey,
-    defaultOpenKeys,
-    openKeys,
-    handleOpenChange,
-    items,
-    handleMenuClick,
-  ]);
-
-  const renderDrawerSider = () => {
+  const renderMenu = useCallback(
+    (collapsed: boolean) => {
+      return (
+        <Menu
+          selectedKeys={selectedKey ? [selectedKey] : []}
+          defaultOpenKeys={defaultOpenKeys}
+          openKeys={openKeys}
+          onOpenChange={handleOpenChange}
+          mode="inline"
+          // Layout.Sider 的 collapsed 只压宽度, 不会自动让 Menu 切到 collapsed 模式.
+          // 必须显式 inlineCollapsed, 否则 SubMenu 的 label 仍渲染, 折叠时溢出 80px 容器
+          // (常见症状: 中文 label 被截成 "系统管", active 项还是蓝字)
+          inlineCollapsed={collapsed}
+          items={items}
+          style={{
+            paddingTop: 8,
+            border: 'none',
+            overflow: 'auto',
+            // 减去标题栏 (HEADER_HEIGHT) + 桌面 trigger 默认 ~48px 的占位.
+            height: `calc(100% - ${HEADER_HEIGHT + 8}px)`,
+            background: 'transparent',
+          }}
+          onClick={handleMenuClick}
+        />
+      );
+    },
+    [
+      selectedKey,
+      defaultOpenKeys,
+      openKeys,
+      handleOpenChange,
+      items,
+      handleMenuClick,
+    ],
+  );
+
+  const drawerButtonStyles: CSSProperties = {
+    borderTopLeftRadius: 0,
+    borderBottomLeftRadius: 0,
+    position: 'fixed',
+    top: HEADER_HEIGHT,
+    zIndex: Z_INDEX.FAB,
+  };
+
+  if (isMobile) {
     return (
       <>
         <Drawer
@@ -320,39 +378,22 @@ export const Sider: React.FC = () => {
           onClose={() => setMobileSiderOpen(false)}
           placement="left"
           closable={false}
-          width={256}
-          styles={{
-            body: {
-              padding: 0,
-            },
-          }}
-          maskClosable={true}
+          width={SIDER_WIDTH}
+          styles={{ body: { padding: 0 } }}
+          maskClosable
         >
-          <Layout>
+          <Layout style={{ height: '100vh' }}>
             <Layout.Sider
-              width={500}
+              width={SIDER_WIDTH}
               style={{
                 height: '100vh',
                 backgroundColor: token.colorBgContainer,
                 borderRight: `1px solid ${token.colorBorderBg}`,
               }}
             >
-              <div
-                {...agentAttrs({ type: 'app-title' })}
-                style={{
-                  width: '256px',
-                  padding: '0 16px',
-                  display: 'flex',
-                  justifyContent: 'flex-start',
-                  alignItems: 'center',
-                  height: '64px',
-                  backgroundColor: token.colorBgElevated,
-                  borderBottom: 'none',
-                }}
-              >
-                <Title collapsed={false} />
-              </div>
-              {renderMenu()}
+              <SiderTitleBar collapsed={false} />
+              {/* 移动端 Drawer 打开时给的是全宽容器, Menu 永远展开. */}
+              {renderMenu(false)}
             </Layout.Sider>
           </Layout>
         </Drawer>
@@ -361,13 +402,10 @@ export const Sider: React.FC = () => {
           size="large"
           onClick={() => setMobileSiderOpen(true)}
           icon={<BarsOutlined />}
+          aria-label="Open navigation menu"
         />
       </>
     );
-  };
-
-  if (isMobile) {
-    return renderDrawerSider();
   }
 
   const siderStyles: React.CSSProperties = {
@@ -377,67 +415,48 @@ export const Sider: React.FC = () => {
     top: 0,
     left: 0,
     height: '100vh',
-    zIndex: 999,
+    zIndex: Z_INDEX.STICKY,
   };
 
   return (
-    <>
-      <Layout.Sider
-        style={siderStyles}
-        width={256}
-        collapsible
-        collapsed={siderCollapsed}
-        onCollapse={(collapsed, type) => {
-          if (type === 'clickTrigger') {
-            setSiderCollapsed(collapsed);
-          }
-        }}
-        collapsedWidth={80}
-        breakpoint="lg"
-        trigger={
-          <Button
-            type="text"
-            style={{
-              borderRadius: 0,
-              height: '100%',
-              width: '100%',
-              backgroundColor: token.colorBgElevated,
-              borderRight: `1px solid ${token.colorBorderBg}`,
-            }}
-          >
-            {siderCollapsed ? (
-              <RightOutlined
-                style={{
-                  color: token.colorPrimary,
-                }}
-              />
-            ) : (
-              <LeftOutlined
-                style={{
-                  color: token.colorPrimary,
-                }}
-              />
-            )}
-          </Button>
+    <Layout.Sider
+      style={siderStyles}
+      width={SIDER_WIDTH}
+      collapsible
+      collapsed={siderCollapsed}
+      onCollapse={(collapsed, type) => {
+        if (type === 'clickTrigger') {
+          setSiderCollapsed(collapsed);
         }
-      >
-        <div
-          {...agentAttrs({ type: 'app-title' })}
+      }}
+      collapsedWidth={SIDER_COLLAPSED_WIDTH}
+      breakpoint="lg"
+      trigger={
+        <Button
+          type="text"
+          aria-label={
+            siderCollapsed
+              ? 'Expand navigation menu'
+              : 'Collapse navigation menu'
+          }
+          aria-expanded={!siderCollapsed}
           style={{
-            width: siderCollapsed ? '80px' : '256px',
-            padding: siderCollapsed ? '0' : '0 16px',
-            display: 'flex',
-            justifyContent: siderCollapsed ? 'center' : 'flex-start',
-            alignItems: 'center',
-            height: '64px',
+            borderRadius: 0,
+            height: '100%',
+            width: '100%',
             backgroundColor: token.colorBgElevated,
-            fontSize: '14px',
+            borderRight: `1px solid ${token.colorBorderBg}`,
+            // 之前用 colorPrimary 给 chrome 控件上色, 与 One Voice Rule 冲突.
+            // chrome 收纳器不需要抢眼, 用次级文本色即可.
+            color: token.colorTextSecondary,
           }}
         >
-          <Title collapsed={siderCollapsed} />
-        </div>
-        {renderMenu()}
-      </Layout.Sider>
-    </>
+          {siderCollapsed ? <RightOutlined /> : <LeftOutlined />}
+        </Button>
+      }
+    >
+      <SiderTitleBar collapsed={siderCollapsed} />
+      {renderMenu(siderCollapsed)}
+    </Layout.Sider>
   );
 };

package/dist/lib/application/files/gadmin2-game-angle-demo/web/src/components/layout/title.tsx

@@ -2,60 +2,63 @@ import React from 'react';
 
 import type { RefineLayoutThemedTitleProps } from '@refinedev/antd';
 import { useLink } from '@refinedev/core';
+import { useTranslation } from 'react-i18next';
 
-import { Space, theme, Typography } from 'antd';
+import { theme } from 'antd';
 
 import { Logo } from './logo';
 
 const { useToken } = theme;
 
-const name = 'AI+ Ops Admin';
-
+/**
+ * App 品牌入口（左上角 Logo + 名称）。
+ *
+ * 设计意图：
+ *  - 不再使用 Typography.Title —— 它会在每个页面渲染一个重复的 <h1>，
+ *    与页面自身的 <h1> 冲突，破坏 a11y 层级。这里只是一个导航入口，
+ *    用 <span> + 显式样式即可。
+ *  - 名称走 i18n，方便后续 white-label 替换。
+ *  - Logo 用 currentColor，颜色由这里的 wrapper 决定（主色蓝）。
+ */
 export const Title: React.FC<RefineLayoutThemedTitleProps> = ({
   collapsed,
   wrapperStyles,
 }) => {
   const { token } = useToken();
+  const { t } = useTranslation();
   const Link = useLink();
 
+  const appName = t('app.name', 'AI+ Ops Admin');
+
   return (
     <Link
       to="/"
       style={{
-        display: 'inline-block',
+        display: 'inline-flex',
+        alignItems: 'center',
+        gap: 8,
+        color: token.colorPrimary,
         textDecoration: 'none',
+        ...wrapperStyles,
       }}
+      aria-label={appName}
     >
-      <Space
-        style={{
-          display: 'flex',
-          alignItems: 'center',
-          fontSize: 'inherit',
-          ...wrapperStyles,
-        }}
-      >
-        <div
+      <Logo width={24} height={24} />
+
+      {!collapsed && (
+        <span
           style={{
-            height: '24px',
-            width: '24px',
-            color: token.colorPrimary,
+            fontSize: 16,
+            fontWeight: 600,
+            lineHeight: 1.4,
+            color: token.colorTextHeading,
+            letterSpacing: 0,
+            whiteSpace: 'nowrap',
           }}
         >
-          <Logo />
-        </div>
-
-        {!collapsed && (
-          <Typography.Title
-            style={{
-              fontSize: 'inherit',
-              marginBottom: 0,
-              fontWeight: 700,
-            }}
-          >
-            {name}
-          </Typography.Title>
-        )}
-      </Space>
+          {appName}
+        </span>
+      )}
     </Link>
   );
 };

package/dist/lib/application/files/gadmin2-game-angle-demo/web/src/constants/layout.ts

@@ -1,3 +1,27 @@
+/**
+ * App chrome 共享尺寸。layout / sider / header / floating triggers
+ * 都从这里取，避免在多个文件里散落同一个魔法数字。
+ */
+export const HEADER_HEIGHT = 64;
+export const SIDER_WIDTH = 256;
+export const SIDER_COLLAPSED_WIDTH = 80;
+
+/**
+ * 语义化的 z-index 层级表。
+ *
+ * Ant Design v5 的浮层 (Modal / Drawer / Dropdown / Select) 默认从 1000 起；
+ * 所以这里的 STICKY / FAB 都安排在 1000 以下，确保 chrome 在 popup 打开时
+ * 被正确遮挡。永远不要在业务代码里写裸 zIndex 数字 —— 加一个语义键回到这里。
+ */
+export const Z_INDEX = {
+  /** AppHeader、Sider 等 sticky chrome */
+  STICKY: 100,
+  /** 悬浮按钮：移动端的 Drawer 触发器 */
+  FAB: 110,
+  /** 自定义遮罩，低于 Ant popups */
+  OVERLAY: 800,
+} as const;
+
 /** List / Create 页面顶层组件的内容区样式 */
 export const LIST_CONTENT_PROPS = {
   style: { marginTop: '1rem' },

package/dist/lib/application/files/gadmin2-game-angle-demo/web/src/locales/en/common.json

@@ -1,4 +1,10 @@
 {
+  "app": {
+    "name": "AI+ Ops Admin"
+  },
+  "header": {
+    "changeLanguage": "Change language"
+  },
   "pages": {
     "login": {
       "title": "Sign in to your account",

package/dist/lib/application/files/gadmin2-game-angle-demo/web/src/locales/zh_CN/common.json

@@ -1,4 +1,10 @@
 {
+  "app": {
+    "name": "AI+ Ops Admin"
+  },
+  "header": {
+    "changeLanguage": "切换语言"
+  },
   "pages": {
     "login": {
       "title": "Sign in to your account",