@skyroc/scripts 2.5.0

package/templates/admin-shell/layouts/features/menus/menu-renderer.tsx

@@ -0,0 +1,149 @@
+import { BeyondHiding } from '@shell/ui/antd';
+import { I18nLabel, SvgIcon } from '@shell/ui/compose';
+import type { MenuProps } from 'antd';
+import type { ReactNode } from 'react';
+import { createElement } from 'react';
+
+import { getAdminLayoutsOptions } from '../../setup';
+import type { GeneratedMenu } from './menu-generator';
+import MenuBadge from './MenuBadge';
+
+type AntdMenuItems = NonNullable<MenuProps['items']>;
+
+interface RenderAntdMenuItemsOptions {
+  /** Ant Design 菜单模式，用于区分横向菜单和侧边菜单的 extra 布局。 */
+  mode?: MenuProps['mode'];
+}
+
+function createMenuTitle(menu: GeneratedMenu) {
+  return <I18nLabel fallback={menu.title} i18nKey={menu.i18nKey} />;
+}
+
+function createMenuExtra(menu: GeneratedMenu) {
+  const badge = menu.badge ? <MenuBadge badge={menu.badge} /> : null;
+  const extra = createCustomMenuExtra(menu);
+
+  if (badge && extra) {
+    return (
+      <span className="inline-flex items-center gap-6px">
+        {badge}
+        {extra}
+      </span>
+    );
+  }
+
+  return badge ?? extra;
+}
+
+function createCustomMenuExtra(menu: GeneratedMenu) {
+  if (!menu.extra) return undefined;
+
+  const { extras } = getAdminLayoutsOptions();
+  const Extra = extras?.[menu.extra];
+
+  if (!Extra) return undefined;
+
+  return createElement(Extra, menu);
+}
+
+function renderMenu(menu: GeneratedMenu): Menu.CommonMenu {
+  if (menu.type === 'divider') {
+    return {
+      key: menu.key,
+      label: null,
+      order: menu.order,
+      title: menu.title,
+      type: 'divider'
+    };
+  }
+
+  const title = createMenuTitle(menu);
+  const { defaultIcon } = getAdminLayoutsOptions();
+  const commonMenu: Menu.CommonMenu = {
+    extra: createMenuExtra(menu),
+    i18nKey: menu.i18nKey,
+    icon: <SvgIcon icon={menu.icon || defaultIcon} localIcon={menu.localIcon} style={{ fontSize: '20px' }} />,
+    key: menu.key,
+    label: <BeyondHiding title={title} />,
+    order: menu.order,
+    title: menu.title,
+    type: menu.type
+  };
+
+  if (menu.children?.length) {
+    commonMenu.children = renderCommonMenus(menu.children);
+  }
+
+  return commonMenu;
+}
+
+function createSubMenuLabel(label: ReactNode, extra: ReactNode) {
+  return (
+    <span
+      className="box-border flex-y-center min-w-0 w-full justify-between gap-8px pr-28px"
+      data-menu-submenu-label="with-extra"
+    >
+      <span className="min-w-0 flex-1 overflow-hidden">{label}</span>
+      <span className="inline-flex shrink-0 items-center">{extra}</span>
+    </span>
+  );
+}
+
+function createHorizontalMenuLabel(label: ReactNode, extra: ReactNode) {
+  return (
+    <span className="inline-flex max-w-full min-w-0 items-center gap-6px" data-menu-horizontal-label="with-extra">
+      <span className="min-w-0 overflow-hidden">{label}</span>
+      <span className="inline-flex shrink-0 items-center">{extra}</span>
+    </span>
+  );
+}
+
+function createMenuItemLabel(label: ReactNode, extra: ReactNode | undefined, isHorizontalRootMenu: boolean) {
+  if (!extra) {
+    return label;
+  }
+
+  if (isHorizontalRootMenu) {
+    return createHorizontalMenuLabel(label, extra);
+  }
+
+  return createSubMenuLabel(label, extra);
+}
+
+function createAntdMenuItem(
+  menu: Menu.CommonMenu,
+  options: RenderAntdMenuItemsOptions = {},
+  level = 0
+): AntdMenuItems[number] {
+  const { children, extra, i18nKey: _, label, ...rest } = menu;
+  const isHorizontalRootMenu = options.mode === 'horizontal' && level === 0;
+
+  if (children?.length) {
+    return {
+      ...rest,
+      children: children.map(child => createAntdMenuItem(child, options, level + 1)),
+      label: createMenuItemLabel(label, extra, isHorizontalRootMenu)
+    } as AntdMenuItems[number];
+  }
+
+  if (extra && isHorizontalRootMenu) {
+    return {
+      ...rest,
+      label: createHorizontalMenuLabel(label, extra)
+    } as AntdMenuItems[number];
+  }
+
+  return {
+    ...rest,
+    extra,
+    label
+  } as AntdMenuItems[number];
+}
+
+export function renderCommonMenus(menus: GeneratedMenu[]) {
+  return menus.map(renderMenu);
+}
+
+export function renderAntdMenuItems(menus: Menu.CommonMenu[], options: RenderAntdMenuItemsOptions = {}): AntdMenuItems {
+  return menus.map(menu => createAntdMenuItem(menu, options));
+}

package/templates/admin-shell/layouts/features/menus/permissions.ts

@@ -0,0 +1,28 @@
+import { getAdminLayoutsOptions } from '../../setup';
+
+interface PermissionRouteMatch {
+  staticData?: Router.Meta;
+}
+
+export function hasAnyRoutePermission(permissions: string[] | null | undefined, userInfo?: Api.Auth.UserInfo | null) {
+  if (!permissions?.length) {
+    return true;
+  }
+
+  const roles = userInfo?.roles ?? [];
+  const { permissionSuperRole } = getAdminLayoutsOptions();
+
+  if (permissionSuperRole && roles.includes(permissionSuperRole)) {
+    return true;
+  }
+
+  return permissions.some(permission => roles.includes(permission));
+}
+
+export function hasRoutePermission(routeMeta: Router.Meta | undefined, userInfo?: Api.Auth.UserInfo | null) {
+  return hasAnyRoutePermission(routeMeta?.permissions, userInfo);
+}
+
+export function hasMatchedRoutePermission(matches: PermissionRouteMatch[], userInfo?: Api.Auth.UserInfo | null) {
+  return matches.every(match => hasRoutePermission(match.staticData, userInfo));
+}

package/templates/admin-shell/layouts/features/menus/use-menus.ts

@@ -0,0 +1,98 @@
+import { atomWithPartial, getAtomValue } from '@skyroc/core-state';
+import { useAtom } from 'jotai';
+
+import { getAdminLayoutsOptions } from '../../setup';
+import type { GeneratedMenus } from './menu-generator';
+import { menuGenerator, normalizePath } from './menu-generator';
+import { hasRoutePermission } from './permissions';
+
+interface MenusAtom {
+  /** 当前用户首页路由 */
+  home: Router.RoutePath;
+  /** 原始菜单数据：RouteId(layoutId) -> 菜单列表 */
+  menus: GeneratedMenus;
+  quickReferenceMenus: Menu.QuickReferenceMenus;
+}
+
+function createInitialState(): MenusAtom {
+  return {
+    home: getAdminLayoutsOptions().defaultHome,
+    menus: new Map(),
+    quickReferenceMenus: new Map()
+  };
+}
+
+const menusAtom = atomWithPartial<MenusAtom>({
+  home: '' as Router.RoutePath,
+  menus: new Map(),
+  quickReferenceMenus: new Map()
+});
+
+export const useMenus = () => {
+  const [menusState, setMenusState] = useAtom(menusAtom);
+
+  async function initMenus(userInfo?: Api.Auth.UserInfo | null) {
+    const { loadDynamicRoutes, routeMode } = getAdminLayoutsOptions();
+
+    if (routeMode === 'dynamic') {
+      if (!loadDynamicRoutes) {
+        throw new Error('Admin layouts routeMode is dynamic, but loadDynamicRoutes is not configured.');
+      }
+
+      const routeData = await loadDynamicRoutes();
+      const { allMenus, home, quickReferenceMenus } = menuGenerator.generate({
+        backendRoutes: routeData.routes,
+        home: routeData.home,
+        userInfo
+      });
+
+      setMenusState({ home, menus: allMenus, quickReferenceMenus });
+      return;
+    }
+
+    const { allMenus, home, quickReferenceMenus } = menuGenerator.generate({ userInfo });
+    setMenusState({ home, menus: allMenus, quickReferenceMenus });
+  }
+
+  function clearMenus() {
+    setMenusState(createInitialState());
+  }
+
+  function getHomeRoute() {
+    return getAtomValue(menusAtom).home;
+  }
+
+  return {
+    ...menusState,
+    initMenus,
+    clearMenus,
+    getHomeRoute
+  };
+};
+
+export function getQuickReferenceMenuByPath(path: string) {
+  const normalizedPath = normalizePath(path) as Router.RoutePath;
+  const { quickReferenceMenus } = getAtomValue(menusAtom);
+
+  for (const quickReferenceMenuMap of quickReferenceMenus.values()) {
+    const menu = quickReferenceMenuMap.get(normalizedPath);
+
+    if (menu) {
+      return menu;
+    }
+  }
+
+  return null;
+}
+
+export function hasAuthorizedRoutePath(path: string, userInfo?: Api.Auth.UserInfo | null) {
+  const { routeMode } = getAdminLayoutsOptions();
+
+  if (routeMode !== 'dynamic') {
+    return true;
+  }
+
+  const menu = getQuickReferenceMenuByPath(path);
+
+  return Boolean(menu && hasRoutePermission(menu, userInfo));
+}

package/templates/admin-shell/layouts/features/use-route.ts

@@ -0,0 +1,30 @@
+import { stringifyQuery } from '@skyroc/utils';
+import { useMatches } from '@tanstack/react-router';
+
+import { normalizePath } from './menus/menu-generator';
+
+export function useRoute() {
+  const route = useMatches({
+    select: matches => {
+      const m = matches[matches.length - 1];
+
+      const qs = stringifyQuery(m.search);
+
+      const fullPath = qs ? `${m.pathname}${qs}` : m.pathname;
+
+      return {
+        routeId: m.routeId,
+        params: m.params,
+        pathname: m.pathname,
+        fullPath,
+        staticData: m.staticData,
+        searchStr: qs,
+        originPath: normalizePath(m.fullPath) as Router.RoutePath,
+        search: m.search
+      };
+    },
+    structuralSharing: false
+  });
+
+  return route;
+}

package/templates/admin-shell/layouts/index.ts

@@ -0,0 +1,44 @@
+export { default as AdminLayout } from './AdminLayout';
+export type { AdminLayoutProps } from './AdminLayout';
+export type { AdminLayoutLogoComponent, AdminLayoutLogoProps, AdminLayoutSlots } from './context';
+export type {
+  CreateAdminDynamicRouteLoaderOptions,
+  NormalizeBackendRouteResponseOptions
+} from './features/menus/dynamic-routes';
+export {
+  collectAvailableRoutePaths,
+  createAdminDynamicRouteLoader,
+  createBackendRouteNormalizer,
+  normalizeBackendRouteResponse
+} from './features/menus/dynamic-routes';
+export { normalizePath } from './features/menus/menu-generator';
+export type {
+  GeneratedMenu,
+  GeneratedMenus,
+  GenerateMenuOptions,
+  GenerateMenuResult
+} from './features/menus/menu-generator';
+
+export { hasAnyRoutePermission, hasMatchedRoutePermission, hasRoutePermission } from './features/menus/permissions';
+export { getQuickReferenceMenuByPath, hasAuthorizedRoutePath, useMenus } from './features/menus/use-menus';
+export { useRoute } from './features/use-route';
+export type {
+  AdminLayoutMenuCategory,
+  AdminLayoutsDynamicRoutes,
+  AdminLayoutsOptions,
+  AdminLayoutsStorage,
+  MenuNodeCallback,
+  MenuNodeConfig
+} from './setup';
+export { setupAdminLayouts } from './setup';
+export type { MenuBadgeValues } from './state/menus/use-admin-menu-badges';
+export {
+  clearMenuBadgeValues,
+  setMenuBadgeValue,
+  setMenuBadgeValues,
+  useAdminMenuBadges
+} from './state/menus/use-admin-menu-badges';
+export { useAdminMenus } from './state/menus/use-admin-menus';
+export { cacheTabs, useAdminTab } from './state/tabs/use-admin-tab';
+export { useAdminState } from './state/use-admin-state';
+export * from './types/storage';

package/templates/admin-shell/layouts/materials/index.ts

@@ -0,0 +1,6 @@
+import AdminLayout from './libs/admin-layout';
+import { LAYOUT_MAX_Z_INDEX, LAYOUT_SCROLL_EL_ID } from './libs/admin-layout/shared';
+import PageTab from './libs/page-tab';
+
+export * from './types';
+export { AdminLayout, LAYOUT_MAX_Z_INDEX, LAYOUT_SCROLL_EL_ID, PageTab };

package/templates/admin-shell/layouts/materials/libs/admin-layout/index.module.css

@@ -0,0 +1,63 @@
+/* @type */
+
+.layout-header,
+.layout-header-placement {
+  height: var(--soy-header-height);
+}
+
+.layout-header {
+  z-index: var(--soy-header-z-index);
+}
+
+.layout-tab {
+  top: var(--soy-header-height);
+  height: var(--soy-tab-height);
+  z-index: var(--soy-tab-z-index);
+}
+
+.layout-tab-placement {
+  height: var(--soy-tab-height);
+}
+
+.layout-sider {
+  width: var(--soy-sider-width) !important;
+  z-index: var(--soy-sider-z-index);
+}
+
+.layout-mobile-sider {
+  z-index: var(--soy-sider-z-index);
+}
+
+.layout-mobile-sider-mask {
+  z-index: var(--soy-mobile-sider-z-index);
+}
+
+.layout-sider_collapsed {
+  width: var(--soy-sider-collapsed-width);
+  z-index: var(--soy-sider-z-index);
+}
+
+.layout-footer,
+.layout-footer-placement {
+  height: var(--soy-footer-height);
+}
+
+.layout-footer {
+  z-index: var(--soy-footer-z-index);
+}
+
+.left-gap {
+  padding-left: var(--soy-sider-width);
+}
+
+.left-gap_collapsed {
+  padding-left: var(--soy-sider-collapsed-width);
+}
+
+.sider-padding-top {
+  padding-top: var(--soy-header-height);
+}
+
+.sider-padding-bottom {
+  padding-bottom: var(--soy-footer-height);
+}

package/templates/admin-shell/layouts/materials/libs/admin-layout/index.module.css.d.ts

@@ -0,0 +1,18 @@
+declare const styles: {
+  readonly 'layout-footer': string;
+  readonly 'layout-footer-placement': string;
+  readonly 'layout-header': string;
+  readonly 'layout-header-placement': string;
+  readonly 'layout-mobile-sider': string;
+  readonly 'layout-mobile-sider-mask': string;
+  readonly 'layout-sider': string;
+  readonly 'layout-sider_collapsed': string;
+  readonly 'layout-tab': string;
+  readonly 'layout-tab-placement': string;
+  readonly 'left-gap': string;
+  readonly 'left-gap_collapsed': string;
+  readonly 'sider-padding-bottom': string;
+  readonly 'sider-padding-top': string;
+};
+
+export default styles;

package/templates/admin-shell/layouts/materials/libs/admin-layout/index.tsx

@@ -0,0 +1,238 @@
+import classNames from 'clsx';
+import { type FC } from 'react';
+import type { AdminLayoutProps } from '../../types';
+import { LAYOUT_MAX_Z_INDEX, LAYOUT_SCROLL_EL_ID, createLayoutCssVars } from './shared';
+import style from './index.module.css';
+
+// eslint-disable-next-line complexity
+const AdminLayout: FC<AdminLayoutProps> = ({
+  children,
+  commonClass = 'transition-all-300',
+  contentClass,
+  fixedFooter,
+  fixedTop = true,
+  Footer,
+  footerClass,
+  footerHeight = 48,
+  footerVisible = true,
+  fullContent,
+  Header,
+  headerClass,
+  headerHeight = 56,
+  headerVisible = true,
+  isMobile,
+  maxZIndex = LAYOUT_MAX_Z_INDEX,
+  mobileSiderClass,
+  mode = 'vertical',
+  rightFooter = false,
+  scrollElId = LAYOUT_SCROLL_EL_ID,
+  scrollMode = 'content',
+  scrollWrapperClass,
+  Sider,
+  siderClass,
+  siderCollapse = false,
+  siderCollapsedWidth = 64,
+  siderVisible = true,
+  siderWidth = 220,
+  Tab,
+  tabClass,
+  tabHeight = 44,
+  tabVisible = true,
+  updateSiderCollapse
+  // eslint-disable-next-line complexity
+}) => {
+  const cssVar = createLayoutCssVars({
+    footerHeight,
+    headerHeight,
+    isMobile,
+    maxZIndex,
+    mode,
+    siderCollapsedWidth,
+    siderWidth,
+    tabHeight
+  }) as React.CSSProperties;
+  // config visible
+  const showHeader = Boolean(Header) && headerVisible;
+  const showSider = !isMobile && Boolean(Sider) && siderVisible;
+  const showMobileSider = isMobile && Boolean(Sider) && siderVisible;
+  const showTab = Boolean(Tab) && tabVisible;
+  const showFooter = Boolean(Footer) && footerVisible;
+
+  // scroll mode
+  const isWrapperScroll = scrollMode === 'wrapper';
+  const isContentScroll = scrollMode === 'content';
+  // layout direction
+  const isVertical = mode === 'vertical';
+  const isHorizontal = mode === 'horizontal';
+  const fixedHeaderAndTab = fixedTop || (isHorizontal && isWrapperScroll);
+
+  // css
+  const leftGapClass = () => {
+    if (!fullContent && showSider) {
+      return siderCollapse ? style['left-gap_collapsed'] : style['left-gap'];
+    }
+    return '';
+  };
+  const headerLeftGapClass = isVertical ? leftGapClass() : '';
+
+  const footerLeftGapClass = () => {
+    const condition1 = isVertical;
+    const condition2 = isHorizontal && isWrapperScroll && !fixedFooter;
+    const condition3 = Boolean(isHorizontal && rightFooter);
+
+    if (condition1 || condition2 || condition3) {
+      return leftGapClass();
+    }
+
+    return '';
+  };
+  const siderPaddingClass = () => {
+    let cls = '';
+
+    if (showHeader && !headerLeftGapClass) {
+      cls += style['sider-padding-top'];
+    }
+    if (showFooter && !footerLeftGapClass()) {
+      cls += ` ${style['sider-padding-bottom']}`;
+    }
+
+    return cls;
+  };
+  // display
+  const headerDisplay = !fullContent && fixedHeaderAndTab ? 'block' : 'none';
+  const siderDisplay = fullContent ? 'none' : 'block';
+  const mobileSider = siderCollapse ? 'none' : 'block';
+  const footerDisplay = !fullContent && fixedFooter ? 'block' : 'none';
+
+  return (
+    <section className={classNames('relative h-full', commonClass)} style={cssVar}>
+      <section
+        id={isWrapperScroll ? scrollElId : ''}
+        className={classNames('h-full flex flex-col', scrollWrapperClass, commonClass, {
+          'overflow-y-auto': isWrapperScroll
+        })}
+      >
+        {/* Header */}
+        {showHeader && (
+          <>
+            <header
+              style={{ display: fullContent ? 'none' : 'block' }}
+              className={classNames(
+                'flex-shrink-0',
+                style['layout-header'],
+                commonClass,
+                headerClass,
+                headerLeftGapClass,
+                { 'absolute left-0 top-0 w-full': fixedHeaderAndTab }
+              )}
+            >
+              {Header}
+            </header>
+            <div
+              className={classNames('flex-shrink-0 overflow-hidden', style['layout-header-placement'])}
+              style={{ display: headerDisplay }}
+            />
+          </>
+        )}
+
+        {/* Tab */}
+        {showTab && (
+          <>
+            <div
+              className={classNames(
+                'flex-shrink-0',
+                style['layout-tab'],
+                commonClass,
+                tabClass,
+                { 'top-0!': fullContent || !showHeader },
+                leftGapClass(),
+                { 'absolute left-0 w-full': fixedHeaderAndTab }
+              )}
+            >
+              {Tab}
+            </div>
+
+            <div
+              className={classNames('flex-shrink-0 overflow-hidden', [style['layout-tab-placement']])}
+              style={{ display: fixedHeaderAndTab || fullContent ? 'block' : 'none' }}
+            />
+          </>
+        )}
+
+        {/* Sider */}
+        {showSider && (
+          <aside
+            style={{ display: siderDisplay }}
+            className={classNames(
+              'absolute left-0 top-0 h-full',
+              commonClass,
+              siderClass,
+              siderPaddingClass(),
+              siderCollapse ? style['layout-sider_collapsed'] : style['layout-sider']
+            )}
+          >
+            {Sider}
+          </aside>
+        )}
+
+        {/* Mobile Sider */}
+        {showMobileSider && (
+          <>
+            <aside
+              className={classNames('absolute left-0 top-0 h-full w-0 bg-white', [
+                commonClass,
+                siderClass,
+                mobileSiderClass,
+                style['layout-mobile-sider'],
+                siderCollapse ? 'overflow-hidden' : style['layout-sider']
+              ])}
+            >
+              {Sider}
+            </aside>
+            <div
+              style={{ display: mobileSider }}
+              className={classNames('absolute left-0 top-0 h-full w-full bg-[rgba(0,0,0,0.2)]', [
+                style['layout-mobile-sider-mask']
+              ])}
+              onClick={() => updateSiderCollapse()}
+            />
+          </>
+        )}
+
+        {/*  Main Content  */}
+        <main
+          id={isContentScroll ? scrollElId : ''}
+          className={classNames('flex flex-col flex-grow bg-layout', commonClass, contentClass, leftGapClass(), {
+            'overflow-y-auto': isContentScroll
+          })}
+        >
+          {children}
+        </main>
+
+        {/* Footer */}
+        {showFooter && (
+          <>
+            <footer
+              style={{ display: siderDisplay }}
+              className={classNames(
+                'flex-shrink-0',
+                style['layout-footer'],
+                commonClass,
+                footerClass,
+                footerLeftGapClass(),
+                { 'absolute bottom-0 left-0 w-full': fixedFooter }
+              )}
+            >
+              {Footer}
+            </footer>
+            <div
+              className={classNames('flex-shrink-0 overflow-hidden', style['layout-footer-placement'])}
+              style={{ display: footerDisplay }}
+            />
+          </>
+        )}
+      </section>
+    </section>
+  );
+};
+export default AdminLayout;