@skyroc/scripts 2.5.0

package/templates/admin-shell/theme/types/theme.d.ts

@@ -0,0 +1,316 @@
+// oxlint-disable unicorn/require-module-specifiers
+/** The theme namespace */
+declare global {
+  namespace Theme {
+    /** Color palette number */
+    type ColorPaletteNumber = import('@skyroc/color').ColorPaletteNumber;
+
+    /** Watermark settings (Ant Design) */
+    type WatermarkSettings = import('antd').WatermarkProps;
+
+    /**
+     * Theme mode
+     *
+     * - Auto: follow system theme
+     * - Dark: dark mode
+     * - Light: light mode
+     */
+    type ThemeMode = 'auto' | 'dark' | 'light';
+
+    /**
+     * Theme layout mode
+     *
+     * - Vertical: the vertical menu in left
+     * - Horizontal: the horizontal menu in top
+     * - Vertical-mix: two vertical mixed menus in left
+     * - Vertical-hybrid-header-first: vertical mixed menus with header first-level menu
+     * - Top-hybrid-sidebar-first: vertical first level menus in left and horizontal child level menus in top
+     * - Top-hybrid-header-first: horizontal first level menus in top and vertical child level menus in left
+     */
+    type ThemeLayoutMode =
+      | 'horizontal'
+      | 'top-hybrid-header-first'
+      | 'top-hybrid-sidebar-first'
+      | 'vertical'
+      | 'vertical-hybrid-header-first'
+      | 'vertical-mix';
+
+    /**
+     * Theme scroll mode
+     *
+     * - Wrapper: the wrapper component's root element overflow
+     * - Content: the content component overflow
+     */
+    type ThemeScrollMode = 'content' | 'wrapper';
+
+    /** Theme page animate mode */
+    type ThemePageAnimateMode =
+      | 'fade'
+      | 'fade-bottom'
+      | 'fade-scale'
+      | 'fade-slide'
+      | 'none'
+      | 'zoom-fade'
+      | 'zoom-out';
+
+    /**
+     * Theme tab mode
+     *
+     * - Chrome: chrome style
+     * - Button: button style
+     */
+    type ThemeTabMode = 'button' | 'chrome' | 'slider';
+
+    /** Theme color key */
+    type ThemeColorKey = 'error' | 'info' | 'primary' | 'success' | 'warning';
+
+    /** Other color (without primary) */
+    interface OtherColor {
+      error: string;
+      info: string;
+      success: string;
+      warning: string;
+    }
+
+    /** Theme color (includes primary) */
+    interface ThemeColor extends OtherColor {
+      primary: string;
+    }
+
+    /** Theme icons mapping */
+    interface ThemeIcons {
+      auto: string;
+      dark: string;
+      light: string;
+    }
+
+    /** Base watermark settings - platform agnostic */
+    interface BaseWatermarkSettings {
+      /** Font settings */
+      font?: {
+        fontSize?: number;
+      };
+      /** Height */
+      height?: number;
+      /** Offset */
+      offset?: [number, number];
+      /** Rotate angle */
+      rotate?: number;
+      /** Width */
+      width?: number;
+      /** Z-index */
+      zIndex?: number;
+    }
+
+    /** Theme setting token color */
+    interface ThemeSettingTokenColor {
+      'base-text': string;
+      container: string;
+      inverted: string;
+      layout: string;
+      /** The progress bar color, if not set, will use the primary color */
+      nprogress?: string;
+    }
+
+    /** Theme setting token box shadow */
+    interface ThemeSettingTokenBoxShadow {
+      header: string;
+      sider: string;
+      tab: string;
+    }
+
+    /** Theme setting token */
+    interface ThemeSettingToken {
+      boxShadow: ThemeSettingTokenBoxShadow;
+      colors: ThemeSettingTokenColor;
+    }
+
+    /** Theme palette color - all color shades */
+    type ThemePaletteColor = {
+      [key in ThemeColorKey | `${ThemeColorKey}-${ColorPaletteNumber}`]: string;
+    };
+
+    /** Base token type */
+    type BaseToken = Record<string, Record<string, string>>;
+
+    /** Theme token color - palette + setting token color */
+    type ThemeTokenColor = ThemePaletteColor & ThemeSettingTokenColor;
+
+    /** Theme token CSS variables */
+    interface ThemeTokenCSSVars {
+      boxShadow: ThemeSettingTokenBoxShadow & { [key: string]: string };
+      colors: ThemeTokenColor & { [key: string]: string };
+    }
+
+    /** Theme preset metadata */
+    interface ThemePresetMeta {
+      /** Preset description */
+      desc: string;
+      /** I18n key for the preset name */
+      i18nkey: string;
+      /** Preset name */
+      name: string;
+      /** Display order */
+      order: number;
+      /** Preset version */
+      version: string;
+    }
+
+    /** Theme preset type */
+    type ThemePreset = ThemePresetMeta & Partial<ThemeSetting>;
+
+    /** Theme setting */
+    interface ThemeSetting {
+      /** Colour weakness mode */
+      colourWeakness: boolean;
+      /** Fixed header and tab */
+      fixedHeaderAndTab: boolean;
+      /** Footer */
+      footer: {
+        /** Whether fixed the footer */
+        fixed: boolean;
+        /** Footer height */
+        height: number;
+        /**
+         * Whether float the footer to the right when the layout is 'top-hybrid-sidebar-first' or
+         * 'top-hybrid-header-first'
+         */
+        right: boolean;
+        /** Whether to show the footer */
+        visible: boolean;
+      };
+      /** Grayscale mode */
+      grayscale: boolean;
+      /** Header */
+      header: {
+        /** Header breadcrumb */
+        breadcrumb: {
+          /** Whether to show the breadcrumb icon */
+          showIcon: boolean;
+          /** Whether to show the breadcrumb */
+          visible: boolean;
+        };
+        globalSearch: {
+          /** Whether to show the GlobalSearch */
+          visible: boolean;
+        };
+        /** Header height */
+        height: number;
+        /** Multilingual */
+        multilingual: {
+          /** Whether to show the multilingual */
+          visible: boolean;
+        };
+      };
+      /** Whether info color is followed by the primary color */
+      isInfoFollowPrimary: boolean;
+      /** Layout */
+      layout: {
+        /** Layout mode */
+        mode: ThemeLayoutMode;
+        /** Scroll mode */
+        scrollMode: ThemeScrollMode;
+      };
+      /** Other color */
+      otherColor: OtherColor;
+      /** Page */
+      page: {
+        /** Whether to show the page transition */
+        animate: boolean;
+        /** Page animate mode */
+        animateMode: ThemePageAnimateMode;
+      };
+      /** Whether to recommend color */
+      recommendColor: boolean;
+      /** Sider */
+      sider: {
+        /** Whether to auto select the first submenu */
+        autoSelectFirstMenu: boolean;
+        /** Collapsed sider width */
+        collapsedWidth: number;
+        /** Inverted sider */
+        inverted: boolean;
+        /** Child menu width when the layout is 'vertical-mix', 'top-hybrid-sidebar-first', or 'top-hybrid-header-first' */
+        mixChildMenuWidth: number;
+        /**
+         * Collapsed sider width when the layout is 'vertical-mix', 'top-hybrid-sidebar-first', or
+         * 'top-hybrid-header-first'
+         */
+        mixCollapsedWidth: number;
+        /** Sider width when the layout is 'vertical-mix', 'top-hybrid-sidebar-first', or 'top-hybrid-header-first' */
+        mixWidth: number;
+        /** Sider width */
+        width: number;
+      };
+      /** Tab */
+      tab: {
+        /**
+         * Whether to cache the tab
+         *
+         * If cache, the tabs will get from the local storage when the page is refreshed
+         */
+        cache: boolean;
+        /** Whether to close tab by middle click */
+        closeTabByMiddleClick: boolean;
+        /** Tab height */
+        height: number;
+        /** Tab mode */
+        mode: ThemeTabMode;
+        /** Whether to show the tab */
+        visible: boolean;
+      };
+      /** Theme color */
+      themeColor: string;
+      /** Theme radius */
+      themeRadius: number;
+      /** Theme scheme */
+      themeScheme: ThemeMode;
+      /** Theme text size */
+      themeTextSize: number;
+      /** Define some theme settings tokens, will transform to css variables */
+      tokens: {
+        dark?: {
+          [K in keyof ThemeSettingToken]?: Partial<ThemeSettingToken[K]>;
+        };
+        light: ThemeSettingToken;
+      };
+      /** Watermark */
+      watermark: {
+        /** Whether to use user id as watermark text */
+        enableCustomText: boolean;
+        /** Whether to use current time as watermark text */
+        enableTime: boolean;
+        /** Whether to use user name as watermark text */
+        enableUserName: boolean;
+        /** Watermark settings */
+        settings: WatermarkSettings;
+        /** Watermark text */
+        text: string;
+        /** Time format for watermark text */
+        timeFormat: string;
+
+        /** Whether to show the watermark */
+        visible: boolean;
+      };
+    }
+  }
+
+  namespace StorageType {
+    interface Local {
+      /** Dark mode snapshot consumed by the admin app bootstrap. */
+      darkMode: boolean;
+      /**
+       * Theme override version flag.
+       *
+       * The value is the build time of the project.
+       */
+      overrideThemeFlag: string;
+      /** Primary theme color cached by the theme package. */
+      themeColor: string;
+      /** Persisted admin theme settings. */
+      themeSettings: Theme.ThemeSetting;
+    }
+  }
+}
+
+export {};

package/templates/admin-shell/theme/utils/dark-mode.ts

@@ -0,0 +1,46 @@
+/** Dark mode class name */
+const DARK_CLASS = 'dark';
+
+/**
+ * Toggle HTML class helper
+ *
+ * @param className Class name to toggle
+ * @returns Object with add and remove functions
+ */
+function toggleHtmlClass(className: string) {
+  function add() {
+    document.documentElement.classList.add(className);
+  }
+
+  function remove() {
+    document.documentElement.classList.remove(className);
+  }
+
+  return { add, remove };
+}
+
+/**
+ * Toggle CSS dark mode
+ *
+ * Adds or removes the 'dark' class on the html element
+ *
+ * @param darkMode Is dark mode enabled
+ */
+export function toggleCssDarkMode(darkMode = false): void {
+  const { add, remove } = toggleHtmlClass(DARK_CLASS);
+
+  if (darkMode) {
+    add();
+  } else {
+    remove();
+  }
+}
+
+/**
+ * Check if dark mode class is present
+ *
+ * @returns Whether dark mode class is on html element
+ */
+export function isDarkModeClass(): boolean {
+  return document.documentElement.classList.contains(DARK_CLASS);
+}

package/templates/admin-shell/theme/utils/filters.ts

@@ -0,0 +1,20 @@
+/**
+ * Toggle auxiliary color modes
+ *
+ * Applies CSS filters for grayscale and colour weakness modes
+ *
+ * @param grayscaleMode Enable grayscale mode
+ * @param colourWeakness Enable colour weakness mode
+ */
+export function toggleAuxiliaryColorModes(grayscaleMode = false, colourWeakness = false): void {
+  const htmlElement = document.documentElement;
+
+  htmlElement.style.filter = [grayscaleMode ? 'grayscale(100%)' : '', colourWeakness ? 'invert(80%)' : '']
+    .filter(Boolean)
+    .join(' ');
+}
+
+/** Clear all auxiliary color modes */
+export function clearAuxiliaryColorModes(): void {
+  document.documentElement.style.filter = '';
+}

package/templates/admin-shell/theme/utils/index.ts

@@ -0,0 +1,3 @@
+export { isDarkModeClass, toggleCssDarkMode } from './dark-mode';
+export { clearAuxiliaryColorModes, toggleAuxiliaryColorModes } from './filters';
+export { getDefaultThemeSettings, getThemeColors, mergeThemeSettings } from './settings';

package/templates/admin-shell/theme/utils/settings.ts

@@ -0,0 +1,43 @@
+import { defu } from 'defu';
+import { defaultThemeSettings } from '../config/default';
+import type { ThemeColor } from '../types';
+
+/**
+ * Get default theme settings
+ *
+ * @returns Default theme settings
+ */
+export function getDefaultThemeSettings(): Theme.ThemeSetting {
+  return defaultThemeSettings;
+}
+
+/**
+ * Merge theme settings with defaults
+ *
+ * @param settings Partial theme settings to merge
+ * @param defaults Base theme settings (defaults to defaultThemeSettings)
+ * @returns Merged theme settings
+ */
+export function mergeThemeSettings(
+  settings?: Partial<Theme.ThemeSetting>,
+  defaults: Theme.ThemeSetting = defaultThemeSettings
+): Theme.ThemeSetting {
+  if (!settings) return defaults;
+  return defu(settings, defaults) as Theme.ThemeSetting;
+}
+
+/**
+ * Get theme colors from settings
+ *
+ * @param settings Theme settings
+ * @returns Complete theme colors including primary
+ */
+export function getThemeColors(settings: Theme.ThemeSetting): ThemeColor {
+  const { isInfoFollowPrimary, otherColor, themeColor } = settings;
+
+  return {
+    primary: themeColor,
+    ...otherColor,
+    info: isInfoFollowPrimary ? themeColor : otherColor.info
+  };
+}

package/templates/admin-shell/types/api/auth.d.ts

@@ -0,0 +1,148 @@
+// oxlint-disable unicorn/require-module-specifiers
+/**
+ * 命名空间 Api.Auth
+ *
+ * 后端 API 模块：认证模块
+ */
+declare global {
+  namespace Api.Auth {
+    /**
+     * 每种登录方式都要带的字段
+     *
+     * 它们不是用户填的表单项，由 fetchLogin 统一补上，所以在类型上是可选的
+     */
+    type LoginContext = {
+      /** 客户端 id，对应后端 sys_client.client_id，一行是一个端（PC 后台 / App / 小程序） */
+      clientId?: string;
+      /** 是否保持登录，具体会话时长由后端决定 */
+      remember?: boolean;
+      /** 租户id */
+      tenantId?: string;
+    };
+
+    /** 账号密码登录 */
+    type PwdLoginParams = LoginContext & {
+      /** 图形验证码内容 */
+      code?: string;
+      grantType?: 'password';
+      /** 密码 */
+      password: string;
+      /** 用户名 */
+      userName: string;
+      /** 图形验证码唯一标识 */
+      uuid?: string;
+    };
+
+    /** 手机验证码登录 */
+    type SmsLoginParams = LoginContext & {
+      grantType: 'sms';
+      /** 账号绑定的手机号 */
+      phone: string;
+      /** POST /auth/sms/code 发到手机上的验证码 */
+      smsCode: string;
+    };
+
+    /** 邮箱验证码登录 */
+    type EmailLoginParams = LoginContext & {
+      /** 账号绑定的邮箱 */
+      email: string;
+      /** POST /auth/email/code 发到邮箱里的验证码 */
+      emailCode: string;
+      grantType: 'email';
+    };
+
+    /**
+     * 登录请求参数，按 grantType 分派
+     *
+     * 和后端那个可辨识联合一一对应：每种方式各要哪些字段是分开声明的，混着传会被后端 422。 加一种登录方式在这里加一个成员，别往某一种上挂可选字段。
+     */
+    type LoginParams = EmailLoginParams | PwdLoginParams | SmsLoginParams;
+
+    /** 发手机登录验证码的参数 */
+    type SmsCodeParams = {
+      /** 收验证码的手机号，必须是某个账号绑定的号码 */
+      phone: string;
+      /** 租户id */
+      tenantId?: string;
+    };
+
+    /** 发邮箱登录验证码的参数 */
+    type EmailCodeParams = {
+      /** 收验证码的邮箱，必须是某个账号绑定的地址 */
+      email: string;
+      /** 租户id */
+      tenantId?: string;
+    };
+
+    /** 登录响应数据 */
+    type LoginResponse = LoginToken;
+
+    /** 登录页租户下拉框里的一项 */
+    interface LoginTenantOption {
+      /** 企业名称，下拉框显示的就是它 */
+      companyName: string;
+      /** 绑定的域名，没配就是空串 */
+      domain: string;
+      /** 租户编号，登录和发码时原样带回后端 */
+      tenantId: string;
+    }
+
+    /** GET /auth/tenant/list 的响应，不需要登录就能拿 */
+    interface LoginTenantInfo {
+      /** 这个部署是不是多租户，false 时登录页不显示下拉框 */
+      tenantEnabled: boolean;
+      /** 字段名跟着后端（RuoYi 的 LoginTenantVo）叫 voList，关闭多租户时是空数组 */
+      voList: LoginTenantOption[];
+    }
+
+    /** 图形验证码 */
+    interface CaptchaInfo {
+      /** 当前是否启用图形验证码 */
+      captcha_enabled: boolean;
+      /** Base64 编码的 PNG 图片，不包含 data URL 前缀 */
+      img: null | string;
+      /** 验证码唯一标识 */
+      uuid: null | string;
+    }
+
+    /**
+     * 登录令牌
+     *
+     * 后端 /auth/login 和 /auth/refreshToken 四个字段都给，续签流程内部只传两个，所以那两个是可选的
+     */
+    interface LoginToken {
+      /** 访问令牌还有多少秒过期，据此提前续签，不用等一次 401 */
+      expiresIn?: number;
+      /** 刷新令牌还有多少秒过期，到期前没续过签就要重新登录 */
+      refreshExpiresIn?: number;
+      /** 刷新令牌，只能用一次，用过即作废 */
+      refreshToken: string;
+      /** 访问令牌 */
+      token: string;
+    }
+
+    /** 用户信息 */
+    interface UserInfo {
+      /** 用户按钮权限列表 */
+      buttons: string[];
+      /** 昵称，给界面显示用 */
+      nickname: string;
+      /** 用户角色列表 */
+      roles: string[];
+      /** 用户 ID */
+      userId: string;
+      /** 用户名 */
+      userName: string;
+    }
+
+    /** 用户认证信息 */
+    type Info = {
+      /** 访问令牌 */
+      token: LoginToken['token'];
+      /** 用户信息 */
+      userInfo: UserInfo;
+    };
+  }
+}
+
+export {};

package/templates/admin-shell/types/api/common.d.ts

@@ -0,0 +1,54 @@
+// oxlint-disable unicorn/require-module-specifiers
+/**
+ * 命名空间 Api.Common
+ *
+ * 通用类型和工具类型
+ */
+declare global {
+  namespace Api.Common {
+    /** 分页通用参数 */
+    interface PaginatingCommonParams {
+      /** 当前页码 */
+      current: number;
+      /** 每页条数 */
+      size: number;
+      /** 总条数 */
+      total: number;
+    }
+
+    /** 分页查询列表数据的通用参数 */
+    interface PaginatingQueryRecord<T = any> extends PaginatingCommonParams {
+      /** 数据列表 */
+      records: T[];
+    }
+
+    /** 通用搜索参数 */
+    type CommonSearchParams = Pick<Api.Common.PaginatingCommonParams, 'current' | 'size'>;
+
+    /**
+     * 启用状态
+     *
+     * - "1": 启用
+     * - "2": 禁用
+     */
+    type EnableStatus = '1' | '2';
+
+    /** 通用记录类型 */
+    type CommonRecord<T = any> = {
+      /** 创建人 */
+      createBy: string;
+      /** 创建时间 */
+      createTime: string;
+      /** 记录 ID */
+      id: number;
+      /** 记录状态 */
+      status: EnableStatus | null;
+      /** 更新人 */
+      updateBy: string;
+      /** 更新时间 */
+      updateTime: string;
+    } & T;
+  }
+}
+
+export {};