@skyroc/scripts 2.5.0

package/templates/admin-shell/runtime/app-update.ts

@@ -0,0 +1,156 @@
+import { TaskHub } from '@skyroc/utils/scheduler';
+
+const DEFAULT_UPDATE_CHECK_INTERVAL = 3 * 60 * 1000;
+
+/** 心跳粒度的上下限，见 resolveTickInterval */
+const MIN_TICK_INTERVAL = 1_000;
+const MAX_TICK_INTERVAL = 30_000;
+
+const CHECK_TASK = 'check-update';
+const VISIBILITY_TASK = 'visibility';
+
+interface GetHtmlBuildTimeOptions {
+  /** HTML entry base URL, usually Vite's base URL. */
+  baseUrl?: string;
+
+  /** Fetch implementation used to read the current index.html. */
+  fetcher?: typeof fetch;
+
+  /** Aborts the in-flight request when the caller tears down. */
+  signal?: AbortSignal;
+}
+
+export interface AppUpdateAvailableContext {
+  /** Build time bundled in the running application. */
+  currentBuildTime: string;
+
+  /** Build time read from the latest index.html. */
+  latestBuildTime: string;
+
+  /** Allows the next update check after the host notification closes. */
+  markPromptClosed: () => void;
+}
+
+export interface SetupAppVersionNotificationOptions {
+  /** HTML entry base URL, usually Vite's base URL. */
+  baseUrl?: string;
+
+  /** Build time bundled in the running application. */
+  currentBuildTime: string;
+
+  /** Whether update checks should be started. */
+  enabled: boolean;
+
+  /** Check interval in milliseconds. */
+  interval?: number;
+
+  /** Receives fetch errors from update checking. */
+  onError?: (error: unknown) => void;
+
+  /** Called when a newer build is detected. */
+  onUpdateAvailable: (context: AppUpdateAvailableContext) => void;
+}
+
+export async function getHtmlBuildTime(options: GetHtmlBuildTimeOptions = {}): Promise<string | null> {
+  const { baseUrl = '/', fetcher = globalThis.fetch?.bind(globalThis), signal } = options;
+
+  if (!fetcher) return null;
+
+  const res = await fetcher(`${baseUrl}index.html?time=${Date.now()}`, { signal });
+
+  if (!res.ok) {
+    return null;
+  }
+
+  const html = await res.text();
+  const match = html.match(/<meta name="buildTime" content="([^"]*)">/);
+
+  return match?.[1] || null;
+}
+
+/**
+ * 由检查间隔推导心跳粒度
+ *
+ * 周期任务的实际触发时刻落在 `[interval, interval + tickInterval)` 内。取 interval 的一半 是为了让抖动不超过 50%（3 分钟的检查不会拖成 6 分钟），封顶 30s
+ * 是为了不给一个低频任务 每秒空转的心跳。
+ */
+function resolveTickInterval(interval: number): number {
+  return Math.max(MIN_TICK_INTERVAL, Math.min(Math.floor(interval / 2), MAX_TICK_INTERVAL));
+}
+
+export function setupAppVersionNotification(options: SetupAppVersionNotificationOptions) {
+  const {
+    baseUrl = '/',
+    currentBuildTime,
+    enabled,
+    interval = DEFAULT_UPDATE_CHECK_INTERVAL,
+    onError,
+    onUpdateAvailable
+  } = options;
+
+  if (!enabled || typeof document === 'undefined') return;
+
+  /** 更新提示还开着的时候不再重复检查，等用户处理完再说 */
+  let isPromptOpen = false;
+
+  const hub = new TaskHub({
+    onTaskError: (_taskName, error) => onError?.(error),
+    tickInterval: resolveTickInterval(interval)
+  });
+
+  async function checkForUpdates(ctx: { signal: AbortSignal }) {
+    if (isPromptOpen) return;
+
+    const latestBuildTime = await getHtmlBuildTime({ baseUrl, signal: ctx.signal });
+
+    if (!latestBuildTime || latestBuildTime === currentBuildTime) {
+      return;
+    }
+
+    isPromptOpen = true;
+
+    onUpdateAvailable({
+      currentBuildTime,
+      latestBuildTime,
+      markPromptClosed() {
+        isPromptOpen = false;
+      }
+    });
+  }
+
+  function handleVisibilityChange() {
+    if (document.visibilityState !== 'visible') {
+      hub.pause();
+      return;
+    }
+
+    hub.resume();
+    // 回到前台立刻查一次，并把周期计时从此刻重新起算
+    hub.trigger(CHECK_TASK);
+  }
+
+  hub.register({
+    // 启动那一刻检查没有意义：比对的正是刚加载进来的这份构建
+    immediate: false,
+    interval,
+    name: CHECK_TASK,
+    run: checkForUpdates,
+    type: 'periodic'
+  });
+
+  hub.register({
+    cleanup: () => document.removeEventListener('visibilitychange', handleVisibilityChange),
+    name: VISIBILITY_TASK,
+    // 监听器的注册与「此刻是否可见」无关：在后台加载的页面切到前台时同样要能恢复轮询
+    run: () => document.addEventListener('visibilitychange', handleVisibilityChange),
+    type: 'listener'
+  });
+
+  hub.start();
+
+  if (document.visibilityState !== 'visible') {
+    hub.pause();
+  }
+
+  return () => hub.dispose();
+}

package/templates/admin-shell/runtime/dayjs.ts

@@ -0,0 +1,20 @@
+import { extend } from 'dayjs';
+import localeData from 'dayjs/plugin/localeData';
+
+export interface SetupDayjsOptions {
+  /** Syncs the host application locale into Dayjs. */
+  syncLocale?: () => void;
+
+  /** Whether to register Dayjs localeData plugin. */
+  withLocaleData?: boolean;
+}
+
+export function setupDayjs(options: SetupDayjsOptions = {}) {
+  const { syncLocale, withLocaleData = true } = options;
+
+  if (withLocaleData) {
+    extend(localeData);
+  }
+
+  syncLocale?.();
+}

package/templates/admin-shell/runtime/iconify.ts

@@ -0,0 +1,17 @@
+import { addAPIProvider } from '@iconify/react';
+
+export interface SetupIconifyOfflineOptions {
+  /** Iconify API URL used by the host application. */
+  apiUrl?: string;
+
+  /** Iconify provider name. Empty string configures the default provider. */
+  provider?: string;
+}
+
+export function setupIconifyOffline(options: SetupIconifyOfflineOptions = {}) {
+  const { apiUrl, provider = '' } = options;
+
+  if (apiUrl) {
+    addAPIProvider(provider, { resources: [apiUrl] });
+  }
+}

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

@@ -0,0 +1,10 @@
+export { getHtmlBuildTime, setupAppVersionNotification } from './app-update';
+export type { AppUpdateAvailableContext, SetupAppVersionNotificationOptions } from './app-update';
+export { setupDayjs } from './dayjs';
+export type { SetupDayjsOptions } from './dayjs';
+export { setupIconifyOffline } from './iconify';
+export type { SetupIconifyOfflineOptions } from './iconify';
+export { setupNProgress } from './nprogress';
+export type { SetupNProgressOptions } from './nprogress';
+export { setupAdminRuntimePlugins } from './plugins';
+export type { AdminRuntimePluginCleanup, AdminRuntimePluginConfig, SetupAdminRuntimePluginsOptions } from './plugins';

package/templates/admin-shell/runtime/nprogress.ts

@@ -0,0 +1,25 @@
+import NProgress from 'nprogress';
+import type { NProgress as NProgressInstance } from 'nprogress';
+
+export interface SetupNProgressOptions {
+  /** Animation easing. */
+  easing?: string;
+
+  /** Receives the initialized NProgress instance for host-level config. */
+  onReady?: (nprogress: NProgressInstance) => void;
+
+  /** CSS selector for the progress bar container. */
+  parent?: string;
+
+  /** Animation speed in milliseconds. */
+  speed?: number;
+}
+
+export function setupNProgress(options: SetupNProgressOptions = {}) {
+  const { easing = 'ease', onReady, parent = '.root', speed = 500 } = options;
+
+  NProgress.configure({ easing, parent, speed });
+  onReady?.(NProgress);
+
+  return NProgress;
+}

package/templates/admin-shell/runtime/plugins.ts

@@ -0,0 +1,62 @@
+import { setupAppVersionNotification } from './app-update';
+import type { SetupAppVersionNotificationOptions } from './app-update';
+import { setupDayjs } from './dayjs';
+import type { SetupDayjsOptions } from './dayjs';
+import { setupIconifyOffline } from './iconify';
+import type { SetupIconifyOfflineOptions } from './iconify';
+import { setupNProgress } from './nprogress';
+import type { SetupNProgressOptions } from './nprogress';
+
+export type AdminRuntimePluginConfig<T> = false | T;
+export type AdminRuntimePluginCleanup = () => void;
+
+export interface SetupAdminRuntimePluginsOptions {
+  /** App update check config. Disabled until the host app provides the required notification options. */
+  appVersionNotification?: AdminRuntimePluginConfig<SetupAppVersionNotificationOptions>;
+
+  /** Dayjs runtime setup config. */
+  dayjs?: AdminRuntimePluginConfig<SetupDayjsOptions>;
+
+  /** Iconify offline provider config. */
+  iconifyOffline?: AdminRuntimePluginConfig<SetupIconifyOfflineOptions>;
+
+  /** NProgress runtime setup config. */
+  nprogress?: AdminRuntimePluginConfig<SetupNProgressOptions>;
+}
+
+export function setupAdminRuntimePlugins(options: SetupAdminRuntimePluginsOptions = {}) {
+  const { appVersionNotification, dayjs, iconifyOffline, nprogress } = options;
+  const cleanups: AdminRuntimePluginCleanup[] = [];
+
+  if (dayjs !== false) {
+    setupDayjs(resolvePluginOptions(dayjs));
+  }
+
+  if (nprogress !== false) {
+    setupNProgress(resolvePluginOptions(nprogress));
+  }
+
+  if (iconifyOffline !== false) {
+    setupIconifyOffline(resolvePluginOptions(iconifyOffline));
+  }
+
+  if (appVersionNotification !== false && appVersionNotification !== undefined) {
+    const cleanup = setupAppVersionNotification(appVersionNotification);
+
+    if (cleanup) {
+      cleanups.push(cleanup);
+    }
+  }
+
+  return function cleanupAdminRuntimePlugins() {
+    for (let index = cleanups.length - 1; index >= 0; index -= 1) {
+      cleanups[index]();
+    }
+  };
+}
+
+function resolvePluginOptions<T>(config: AdminRuntimePluginConfig<T> | undefined): T | undefined {
+  if (config === false) return undefined;
+
+  return config;
+}

package/templates/admin-shell/styles/global.css

@@ -0,0 +1,54 @@
+@import './reset.css';
+@import './nprogress.css';
+
+html,
+body,
+#app {
+  height: 100%;
+  text-autospace: normal;
+}
+
+html {
+  overflow-x: hidden;
+  border-color: var(--color-border);
+  font-size: var(--font-size);
+  color: var(--color-text-base);
+}
+
+* {
+  scrollbar-width: thin;
+  scrollbar-color: rgba(144, 147, 153, 0.3) transparent;
+}
+
+*::-webkit-scrollbar {
+  width: 7px;
+  height: 7px;
+}
+
+*::-webkit-scrollbar-thumb {
+  background-color: rgba(144, 147, 153, 0.3);
+  border-radius: 10px;
+}
+
+*::-webkit-scrollbar-thumb:hover {
+  background-color: rgba(144, 147, 153, 0.3);
+}
+
+*::-webkit-scrollbar-track-piece {
+  background-color: transparent;
+  border-radius: 10px;
+}
+
+.ant-table-header::-webkit-scrollbar {
+  background-color: transparent;
+}
+
+html.grayscale {
+  filter: grayscale(100%);
+}
+
+::view-transition-old(root),
+::view-transition-new(root) {
+  animation: none;
+  mix-blend-mode: normal;
+}

package/templates/admin-shell/styles/nprogress.css

@@ -0,0 +1,85 @@
+/* Make clicks pass-through */
+#nprogress {
+  --nprogress-bar-color: var(--nprogress, var(--color-primary, #6366f1));
+
+  pointer-events: none;
+}
+
+#nprogress .bar {
+  background: var(--nprogress-bar-color);
+
+  position: fixed;
+  z-index: 1031;
+  top: 0;
+  left: 0;
+
+  width: 100%;
+  height: 2px;
+}
+
+/* Fancy blur effect */
+#nprogress .peg {
+  display: block;
+  position: absolute;
+  right: 0px;
+  width: 100px;
+  height: 100%;
+  box-shadow:
+    0 0 10px var(--nprogress-bar-color),
+    0 0 5px var(--nprogress-bar-color);
+  opacity: 1;
+
+  -webkit-transform: rotate(3deg) translate(0px, -4px);
+  -ms-transform: rotate(3deg) translate(0px, -4px);
+  transform: rotate(3deg) translate(0px, -4px);
+}
+
+/* Remove these to get rid of the spinner */
+#nprogress .spinner {
+  display: block;
+  position: fixed;
+  z-index: 1031;
+  top: 15px;
+  right: 15px;
+}
+
+#nprogress .spinner-icon {
+  width: 18px;
+  height: 18px;
+  box-sizing: border-box;
+
+  border: solid 2px transparent;
+  border-top-color: var(--nprogress-bar-color);
+  border-left-color: var(--nprogress-bar-color);
+  border-radius: 50%;
+
+  -webkit-animation: nprogress-spinner 400ms linear infinite;
+  animation: nprogress-spinner 400ms linear infinite;
+}
+
+.nprogress-custom-parent {
+  overflow: hidden;
+  position: relative;
+}
+
+.nprogress-custom-parent #nprogress .spinner,
+.nprogress-custom-parent #nprogress .bar {
+  position: absolute;
+}
+
+@-webkit-keyframes nprogress-spinner {
+  0% {
+    -webkit-transform: rotate(0deg);
+  }
+  100% {
+    -webkit-transform: rotate(360deg);
+  }
+}
+@keyframes nprogress-spinner {
+  0% {
+    transform: rotate(0deg);
+  }
+  100% {
+    transform: rotate(360deg);
+  }
+}