yingzios-platform-frontend-devtools 1.0.1

package/src/components/StandaloneAppLayout/index.tsx

@@ -0,0 +1,332 @@
+import React, { memo, useEffect, useMemo, useState } from 'react';
+import { Link, useLocation } from 'react-router-dom';
+
+import type { FrontendNavIconKey } from 'yz-frontend-core';
+import {
+  loadAppManifest,
+  buildMenuGroupsFromManifest,
+  type StandaloneMenuGroup,
+  type StandaloneMenuItem,
+} from '../../manifest-loader';
+import { DevUserMenu } from '../DevUserMenu';
+
+import { layoutStyles, leftNavStyles, groupNavStyles } from './styles';
+
+export type IconRenderer = (iconKey: FrontendNavIconKey) => React.ReactNode;
+
+type PrimaryNavItem = {
+  key: string;
+  label: string;
+  path: string;
+  iconKey?: FrontendNavIconKey;
+  items: StandaloneMenuItem[];
+};
+
+function isPathActive(currentPath: string, candidatePath: string, end?: boolean) {
+  if (candidatePath === currentPath) {
+    return true;
+  }
+
+  return end === false && currentPath.startsWith(candidatePath + '/');
+}
+
+function isStandaloneMenuItemActive(
+  currentPath: string,
+  item: StandaloneMenuItem,
+) {
+  if (isPathActive(currentPath, item.path, item.end)) {
+    return true;
+  }
+
+  return item.matchPaths.some((matchPath) =>
+    isPathActive(currentPath, matchPath, item.end),
+  );
+}
+
+export interface StandaloneAppLayoutProps {
+  /**
+   * manifest 文件路径，默认 'app-manifest.json'（相对路径，受 <base> 标签影响）
+   */
+  manifestUrl?: string;
+  /**
+   * 子内容
+   */
+  children: React.ReactNode;
+  /**
+   * 自定义 Logo 组件
+   */
+  logo?: React.ReactNode;
+  /**
+   * 自定义顶部右侧内容
+   * 如果为 false，则不显示默认的登录组件
+   */
+  headerRight?: React.ReactNode | false;
+  /**
+   * 自定义图标渲染函数
+   * 传入 iconKey，返回 React 节点
+   */
+  renderIcon?: IconRenderer;
+  /**
+   * API 基础路径，用于登录接口
+   * 默认 '/portal/api'
+   */
+  apiBasePath?: string;
+  /**
+   * 组织切换页面路径
+   * 默认 '/org-select'
+   */
+  orgSwitchPath?: string;
+}
+
+/**
+ * 独立运行模式下的应用布局
+ *
+ * 自动从 app-manifest.json 加载配置并生成导航菜单。
+ * 用于微应用本地独立开发时提供统一的导航体验。
+ *
+ * @example
+ * ```tsx
+ * import { StandaloneAppLayout } from 'yz-frontend-devtools';
+ *
+ * function StandaloneApp() {
+ *   return (
+ *     <StandaloneAppLayout>
+ *       <AppRoutes />
+ *     </StandaloneAppLayout>
+ *   );
+ * }
+ * ```
+ */
+export function StandaloneAppLayout({
+  manifestUrl = 'app-manifest.json',
+  children,
+  logo,
+  headerRight,
+  renderIcon,
+  apiBasePath = '/portal/api',
+  orgSwitchPath = '/org-select',
+}: StandaloneAppLayoutProps) {
+  const [menuGroups, setMenuGroups] = useState<StandaloneMenuGroup[]>([]);
+  const [appName, setAppName] = useState<string>('');
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const location = useLocation();
+
+  useEffect(() => {
+    loadAppManifest(manifestUrl)
+      .then((manifest) => {
+        const groups = buildMenuGroupsFromManifest(manifest);
+        setMenuGroups(groups);
+        setAppName(manifest.displayName);
+        setLoading(false);
+      })
+      .catch((err) => {
+        console.error('[StandaloneAppLayout] Failed to load manifest:', err);
+        setError(err.message);
+        setLoading(false);
+      });
+  }, [manifestUrl]);
+
+  const isMenuItemActive = (item: StandaloneMenuItem) =>
+    isStandaloneMenuItemActive(location.pathname, item);
+
+  const primaryNavItems = useMemo<PrimaryNavItem[]>(() => menuGroups.flatMap((group) => {
+    const firstItem = group.items[0];
+
+    if (!firstItem) {
+      return [];
+    }
+
+    return [{
+      key: `group-${group.groupLabel}`,
+      label: group.groupLabel,
+      path: firstItem.path,
+      iconKey: firstItem.iconKey,
+      items: group.items,
+    }];
+  }), [menuGroups]);
+
+  const activePrimaryNav = useMemo(
+    () => primaryNavItems.find((item) => item.items.some((child) => isMenuItemActive(child))) || primaryNavItems[0],
+    [location.pathname, primaryNavItems],
+  );
+
+  const activeSidebarItems = activePrimaryNav?.items ?? [];
+
+  // 渲染右上角内容
+  const renderHeaderRight = () => {
+    // 如果显式传入 false，则不渲染
+    if (headerRight === false) {
+      return null;
+    }
+
+    // 如果传入了自定义内容，则渲染自定义内容
+    if (headerRight) {
+      return headerRight;
+    }
+
+    // 默认渲染登录组件
+    return <DevUserMenu apiBasePath={apiBasePath} orgSwitchPath={orgSwitchPath} />;
+  };
+
+  if (loading) {
+    return (
+      <div style={layoutStyles.layout}>
+        <div style={layoutStyles.loading}>加载中...</div>
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <div style={layoutStyles.layout}>
+        <div style={layoutStyles.error}>
+          <span>加载失败: {error}</span>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div style={layoutStyles.layout}>
+      <header style={layoutStyles.header}>
+        <div style={layoutStyles.headerLeft}>
+          {logo ?? (
+            <span style={layoutStyles.logo}>{appName || 'App'}</span>
+          )}
+          <span style={layoutStyles.devBadge as React.CSSProperties}>DEV</span>
+        </div>
+        <div style={layoutStyles.headerRight}>{renderHeaderRight()}</div>
+      </header>
+      <div style={layoutStyles.shell}>
+        <aside style={layoutStyles.sidebar}>
+          <LeftNav
+            items={activeSidebarItems}
+            currentPath={location.pathname}
+            renderIcon={renderIcon}
+          />
+        </aside>
+        <main style={layoutStyles.main}>
+          <GroupNav items={primaryNavItems} currentPath={location.pathname} />
+          <div style={layoutStyles.content}>{children}</div>
+        </main>
+      </div>
+    </div>
+  );
+}
+
+interface LeftNavProps {
+  items: StandaloneMenuItem[];
+  currentPath: string;
+  renderIcon?: IconRenderer;
+}
+
+function LeftNav({ items, currentPath, renderIcon }: LeftNavProps) {
+  const [hoveredKey, setHoveredKey] = useState<string | null>(null);
+  
+  const isActive = (item: StandaloneMenuItem) =>
+    isStandaloneMenuItemActive(currentPath, item);
+
+  const getIcon = (iconKey?: FrontendNavIconKey, active?: boolean) => {
+    if (!iconKey) {
+      return <span style={leftNavStyles.itemIconPlaceholder} />;
+    }
+
+    if (renderIcon) {
+      return renderIcon(iconKey);
+    }
+
+    // 默认：显示一个简单的圆点
+    return <span style={leftNavStyles.itemIconDot} />;
+  };
+
+  const getItemStyle = (item: StandaloneMenuItem): React.CSSProperties => {
+    const active = isActive(item);
+    const hovered = hoveredKey === item.key;
+    
+    return {
+      ...leftNavStyles.item,
+      ...(hovered && !active ? leftNavStyles.itemHover : {}),
+      ...(active ? leftNavStyles.itemActive : {}),
+    };
+  };
+
+  const getIconStyle = (item: StandaloneMenuItem): React.CSSProperties => {
+    const active = isActive(item);
+    return {
+      ...leftNavStyles.itemIcon,
+      ...(active ? leftNavStyles.itemIconActive : {}),
+    };
+  };
+
+  return (
+    <nav aria-label="开发模式主导航" style={leftNavStyles.nav}>
+      <div style={leftNavStyles.scrollArea}>
+        <section style={leftNavStyles.group}>
+          {items.map((item) => (
+            <Link
+              aria-current={isActive(item) ? 'page' : undefined}
+              key={item.key}
+              to={item.path}
+              title={item.label}
+              style={getItemStyle(item)}
+              onMouseEnter={() => setHoveredKey(item.key)}
+              onMouseLeave={() => setHoveredKey(null)}
+            >
+              <span style={getIconStyle(item)}>
+                {getIcon(item.iconKey, isActive(item))}
+              </span>
+              <span style={leftNavStyles.itemLabel}>{item.label}</span>
+            </Link>
+          ))}
+        </section>
+      </div>
+    </nav>
+  );
+}
+
+interface GroupNavProps {
+  items: PrimaryNavItem[];
+  currentPath: string;
+}
+
+function GroupNav({ items, currentPath }: GroupNavProps) {
+  const [hoveredKey, setHoveredKey] = useState<string | null>(null);
+  
+  const isActive = (item: PrimaryNavItem) =>
+    item.items.some((child) => isStandaloneMenuItemActive(currentPath, child));
+
+  const getItemStyle = (item: PrimaryNavItem): React.CSSProperties => {
+    const active = isActive(item);
+    const hovered = hoveredKey === item.key;
+    
+    return {
+      ...groupNavStyles.item,
+      ...(hovered && !active ? groupNavStyles.itemHover : {}),
+      ...(active ? groupNavStyles.itemActive : {}),
+    };
+  };
+
+  return (
+    <div style={groupNavStyles.nav}>
+      <div style={groupNavStyles.scroll}>
+        {items.map((item) => (
+          <Link
+            aria-current={isActive(item) ? 'page' : undefined}
+            key={item.key}
+            to={item.path}
+            style={getItemStyle(item)}
+            onMouseEnter={() => setHoveredKey(item.key)}
+            onMouseLeave={() => setHoveredKey(null)}
+          >
+            {item.label}
+          </Link>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+StandaloneAppLayout.displayName = 'StandaloneAppLayout';
+
+export default memo(StandaloneAppLayout);

package/src/components/StandaloneAppLayout/styles.ts

@@ -0,0 +1,234 @@
+import type { CSSProperties } from 'react';
+
+// CSS-in-JS 样式定义，避免 scss 构建问题
+export const layoutStyles: Record<string, CSSProperties> = {
+  layout: {
+    display: 'flex',
+    flexDirection: 'column',
+    height: '100vh',
+    minHeight: 0,
+    width: '100%',
+    overflow: 'hidden',
+    background: '#ffffff',
+  },
+  loading: {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    minHeight: '100vh',
+    color: '#666',
+    fontSize: 14,
+  },
+  error: {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    minHeight: '100vh',
+    color: '#ff4d4f',
+    fontSize: 14,
+  },
+  header: {
+    position: 'sticky',
+    top: 0,
+    zIndex: 20,
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    height: 56,
+    padding: '0 16px',
+    background: '#ffffff',
+    borderBottom: '1px solid rgba(226, 232, 240, 0.9)',
+    flexShrink: 0,
+  },
+  headerLeft: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: 12,
+  },
+  headerRight: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: 8,
+  },
+  logo: {
+    fontSize: 18,
+    fontWeight: 600,
+    color: '#0f172a',
+  },
+  devBadge: {
+    display: 'inline-flex',
+    alignItems: 'center',
+    padding: '2px 8px',
+    fontSize: 11,
+    fontWeight: 600,
+    color: '#0f172a',
+    background: '#f1f5f9',
+    border: '1px solid #e2e8f0',
+    borderRadius: 999,
+    textTransform: 'uppercase',
+    letterSpacing: 0.5,
+  },
+  shell: {
+    display: 'flex',
+    flex: 1,
+    overflow: 'hidden',
+    minHeight: 0,
+    background: 'linear-gradient(180deg, #f8fafc 0%, #f3f6fb 100%)',
+  },
+  sidebar: {
+    width: 256,
+    display: 'flex',
+    flexShrink: 0,
+    minHeight: 0,
+    overflow: 'hidden',
+  },
+  main: {
+    flex: 1,
+    display: 'flex',
+    flexDirection: 'column',
+    minWidth: 0,
+    minHeight: 0,
+  },
+  content: {
+    flex: 1,
+    overflowY: 'auto',
+    minHeight: 0,
+    position: 'relative',
+    padding: '24px 28px 28px',
+    background: 'transparent',
+  },
+};
+
+export const leftNavStyles: Record<string, CSSProperties> = {
+  nav: {
+    width: 256,
+    flex: 1,
+    flexShrink: 0,
+    display: 'flex',
+    flexDirection: 'column',
+    minHeight: 0,
+    height: '100%',
+    borderRight: '1px solid rgba(226, 232, 240, 0.9)',
+    background: 'linear-gradient(180deg, rgba(255, 255, 255, 0.96) 0%, rgba(248, 250, 252, 0.98) 100%)',
+    padding: 0,
+    overflow: 'hidden',
+  },
+  scrollArea: {
+    flex: 1,
+    overflowY: 'auto',
+    padding: '18px 16px 12px',
+  },
+  group: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: 6,
+  },
+  item: {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'flex-start',
+    gap: 12,
+    minHeight: 44,
+    padding: '10px 12px',
+    color: '#475569',
+    textDecoration: 'none',
+    border: '1px solid transparent',
+    borderRadius: 8,
+    background: 'transparent',
+    transition: 'background 0.15s, color 0.15s',
+    cursor: 'pointer',
+  },
+  itemHover: {
+    background: '#f8fafc',
+    color: '#0f172a',
+  },
+  itemActive: {
+    background: '#030213',
+    color: '#ffffff',
+    fontWeight: 500,
+    boxShadow: '0 1px 3px rgba(0, 0, 0, 0.1), 0 1px 2px rgba(0, 0, 0, 0.1)',
+  },
+  itemIcon: {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    width: 32,
+    minWidth: 32,
+    height: 32,
+    borderRadius: 8,
+    background: 'linear-gradient(180deg, #f8fafc 0%, #edf2f7 100%)',
+    color: '#64748b',
+    boxShadow: 'inset 0 0 0 1px rgba(226, 232, 240, 0.85)',
+  },
+  itemIconActive: {
+    background: 'rgba(255, 255, 255, 0.15)',
+    color: '#ffffff',
+    boxShadow: 'none',
+  },
+  itemIconPlaceholder: {
+    width: 6,
+    height: 6,
+    borderRadius: '50%',
+    background: '#94a3b8',
+  },
+  itemIconDot: {
+    width: 6,
+    height: 6,
+    borderRadius: '50%',
+    background: 'currentColor',
+    opacity: 0.5,
+  },
+  itemLabel: {
+    fontSize: 14,
+    fontWeight: 500,
+    whiteSpace: 'nowrap',
+    overflow: 'hidden',
+    textOverflow: 'ellipsis',
+  },
+};
+
+export const groupNavStyles: Record<string, CSSProperties> = {
+  nav: {
+    display: 'flex',
+    alignItems: 'center',
+    height: 56,
+    padding: '0 28px',
+    borderBottom: '1px solid rgba(226, 232, 240, 0.9)',
+    background: 'rgba(255, 255, 255, 0.7)',
+    backdropFilter: 'blur(8px)',
+    flexShrink: 0,
+  },
+  scroll: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: 8,
+    overflowX: 'auto',
+  },
+  item: {
+    display: 'inline-flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    height: 32,
+    padding: '0 14px',
+    fontSize: 13,
+    fontWeight: 500,
+    color: '#64748b',
+    textDecoration: 'none',
+    border: '1px solid transparent',
+    borderRadius: 8,
+    background: 'transparent',
+    whiteSpace: 'nowrap',
+    cursor: 'pointer',
+    transition: 'all 0.15s',
+  },
+  itemHover: {
+    color: '#0f172a',
+    background: '#f1f5f9',
+  },
+  itemActive: {
+    color: '#0f172a',
+    background: '#ffffff',
+    borderColor: '#e2e8f0',
+    boxShadow: '0 1px 2px rgba(0, 0, 0, 0.05)',
+  },
+};

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './base-path';
+export * from './components/StandaloneAppLayout';
+export * from './components/DevUserMenu';
+export * from './manifest-loader';

package/src/manifest-loader.ts

@@ -0,0 +1,146 @@
+import type {
+  FrontendAppManifest,
+  FrontendAppSectionDefinition,
+  FrontendNavIconKey,
+} from 'yz-frontend-core';
+
+/**
+ * 加载 app-manifest.json 文件
+ * @param url manifest 文件路径，默认 'app-manifest.json'（相对路径，受 <base> 标签影响）
+ */
+export async function loadAppManifest(url = 'app-manifest.json'): Promise<FrontendAppManifest> {
+  const response = await fetch(url);
+
+  if (!response.ok) {
+    throw new Error(`Failed to load manifest: ${response.status} ${response.statusText}`);
+  }
+
+  return response.json();
+}
+
+/**
+ * 从 manifest 的 menus 构建 sections（用于导航菜单）
+ *
+ * 自动推导规则：
+ * - path: 默认 `${routeBase}/${key}`（useRelativePaths=true 时为 `/${key}`）
+ * - matchPaths: 默认 `[path]`
+ * - group: 仅在 manifest 中显式声明时保留；未声明由导航层使用 displayName 作为默认组
+ * - order: 默认按数组顺序
+ *
+ * @param manifest 应用 manifest
+ * @param useRelativePaths 是否使用相对路径（Standalone 模式下建议为 true）
+ */
+export function buildSectionsFromManifest(
+  manifest: FrontendAppManifest,
+  useRelativePaths = false,
+): FrontendAppSectionDefinition[] {
+  const { routeBase, menus } = manifest;
+
+  if (!menus || menus.length === 0) {
+    return [];
+  }
+
+  return menus.map((menu, index) => {
+    // useRelativePaths 为 true 时，使用相对路径 /${key}，否则用完整路径 ${routeBase}/${key}
+    const path = menu.path ?? (useRelativePaths ? `/${menu.key}` : `${routeBase}/${menu.key}`);
+
+    return {
+      key: menu.key,
+      label: menu.label,
+      path,
+      group: menu.group,
+      iconKey: menu.iconKey as FrontendNavIconKey | undefined,
+      description: menu.description,
+      order: menu.order ?? index,
+      end: menu.end,
+      matchPaths: menu.matchPaths ?? [path],
+    };
+  });
+}
+
+export interface StandaloneMenuItem {
+  key: string;
+  label: string;
+  path: string;
+  iconKey?: FrontendNavIconKey;
+  matchPaths: string[];
+  end?: boolean;
+  order: number;
+}
+
+export interface StandaloneMenuGroup {
+  groupLabel: string;
+  items: StandaloneMenuItem[];
+}
+
+type GroupAccumulator = {
+  firstIndex: number;
+  items: StandaloneMenuItem[];
+};
+
+export interface BuildMenuGroupsOptions {
+  /**
+   * 是否使用相对路径（Standalone 本地开发模式下建议为 true）
+   * - true: 菜单路径为 `/${key}`，如 `/profile`
+   * - false: 菜单路径为 `${routeBase}/${key}`，如 `/apps/personal/profile`
+   * @default true
+   */
+  useRelativePaths?: boolean;
+}
+
+/**
+ * 从 manifest 直接构建菜单组。
+ * 按 group 分组；未声明 group 的菜单统一归入 manifest.displayName 默认组。
+ *
+ * @param manifest 应用 manifest
+ * @param options 构建选项
+ */
+export function buildMenuGroupsFromManifest(
+  manifest: FrontendAppManifest,
+  options: BuildMenuGroupsOptions = {},
+): StandaloneMenuGroup[] {
+  const { useRelativePaths = true } = options;
+  const sections = buildSectionsFromManifest(manifest, useRelativePaths);
+
+  if (sections.length === 0) {
+    return [];
+  }
+
+  const defaultGroupName = manifest.displayName;
+  const groupedItems = new Map<string, GroupAccumulator>();
+
+  sections.forEach((section, index) => {
+    const groupName = section.group || defaultGroupName;
+
+    const existing = groupedItems.get(groupName) || {
+      items: [],
+      firstIndex: index,
+    };
+
+    existing.items.push({
+      key: section.key,
+      label: section.label,
+      path: section.path,
+      iconKey: section.iconKey,
+      matchPaths: section.matchPaths ?? [section.path],
+      end: section.end,
+      order: section.order ?? 0,
+    });
+
+    groupedItems.set(groupName, existing);
+  });
+
+  return Array.from(groupedItems.entries())
+    .map(([groupLabel, { items, firstIndex }]) => ({
+      firstIndex,
+      groupLabel,
+      items: items.sort((a, b) => {
+        if (a.order !== b.order) {
+          return a.order - b.order;
+        }
+        return a.label.localeCompare(b.label, 'zh-CN');
+      }),
+    }))
+    .sort((a, b) => a.firstIndex - b.firstIndex)
+    .map(({ groupLabel, items }) => ({ groupLabel, items }));
+}