create-react-admin-template 0.0.0-stage → 0.1.0

package/template/src/components/ui/skeleton.tsx

@@ -0,0 +1,13 @@
+import { cn } from '@/lib/utils'
+
+function Skeleton({ className, ...props }: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot='skeleton'
+      className={cn('animate-pulse rounded-md bg-accent', className)}
+      {...props}
+    />
+  )
+}
+
+export { Skeleton }

package/template/src/components/ui/sonner.tsx

@@ -0,0 +1,33 @@
+import type { CSSProperties } from 'react'
+import { Toaster as Sonner, type ToasterProps } from 'sonner'
+import { cn } from '@/lib/utils'
+import { useTheme } from '@/context/ThemeProvider'
+
+function Toaster({ ...objProps }: ToasterProps) {
+  const { strTheme } = useTheme()
+
+  return (
+    <Sonner
+      theme={strTheme}
+      className='toaster group'
+      style={
+        {
+          '--normal-bg': 'var(--popover)',
+          '--normal-text': 'var(--popover-foreground)',
+          '--normal-border': 'var(--border)',
+        } as CSSProperties
+      }
+      {...objProps}
+      toastOptions={{
+        ...objProps.toastOptions,
+        className: cn('pointer-events-none', objProps.toastOptions?.className),
+        style: {
+          ...objProps.toastOptions?.style,
+          pointerEvents: 'none',
+        },
+      }}
+    />
+  )
+}
+
+export { Toaster }

package/template/src/components/ui/tooltip.tsx

@@ -0,0 +1,54 @@
+import * as React from 'react'
+import { Tooltip as TooltipPrimitive } from 'radix-ui'
+import { cn } from '@/lib/utils'
+
+function TooltipProvider({
+  delayDuration = 0,
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Provider>) {
+  return (
+    <TooltipPrimitive.Provider
+      data-slot='tooltip-provider'
+      delayDuration={delayDuration}
+      {...props}
+    />
+  )
+}
+
+function Tooltip({
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Root>) {
+  return <TooltipPrimitive.Root data-slot='tooltip' {...props} />
+}
+
+function TooltipTrigger({
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Trigger>) {
+  return <TooltipPrimitive.Trigger data-slot='tooltip-trigger' {...props} />
+}
+
+function TooltipContent({
+  className,
+  sideOffset = 0,
+  children,
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Content>) {
+  return (
+    <TooltipPrimitive.Portal>
+      <TooltipPrimitive.Content
+        data-slot='tooltip-content'
+        sideOffset={sideOffset}
+        className={cn(
+          'z-(--z-index-tooltip) w-fit origin-(--radix-tooltip-content-transform-origin) animate-in rounded-md bg-foreground px-3 py-1.5 text-xs text-balance text-background fade-in-0 zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95',
+          className
+        )}
+        {...props}
+      >
+        {children}
+        <TooltipPrimitive.Arrow className='z-(--z-index-tooltip) size-2.5 translate-y-[calc(-50%_-_2px)] rotate-45 rounded-[2px] bg-foreground fill-foreground' />
+      </TooltipPrimitive.Content>
+    </TooltipPrimitive.Portal>
+  )
+}
+
+export { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider }

package/template/src/config/RuntimeConfigErrorPage.tsx

@@ -0,0 +1,48 @@
+import { objBuildInfo } from '@/config/buildInfo'
+
+export function RuntimeConfigErrorPage({
+  strCode,
+  strMessage,
+}: {
+  /** 便于部署人员检索的稳定错误码。 */
+  strCode: string
+  /** 不包含配置值或凭据的故障说明。 */
+  strMessage: string
+}) {
+  return (
+    <main className='flex min-h-screen items-center justify-center bg-background p-6 text-foreground'>
+      <section
+        aria-labelledby='runtime-config-error-title'
+        className='w-full max-w-xl rounded-xl border bg-card p-6 shadow-sm'
+        role='alert'
+      >
+        <p className='text-sm font-medium text-destructive'>启动失败</p>
+        <h1
+          className='mt-2 text-2xl font-semibold'
+          id='runtime-config-error-title'
+        >
+          应用运行时配置不可用
+        </h1>
+        <p className='mt-3 text-sm text-muted-foreground'>{strMessage}</p>
+        <dl className='mt-4 rounded-md bg-muted p-3 text-sm'>
+          <dt className='font-medium'>错误码</dt>
+          <dd className='mt-1 font-mono'>{strCode}</dd>
+          <dt className='mt-3 font-medium'>应用版本</dt>
+          <dd className='mt-1 font-mono'>
+            v{objBuildInfo.strVersion} · {objBuildInfo.strCommit.slice(0, 12)}
+          </dd>
+        </dl>
+        <p className='mt-4 text-sm text-muted-foreground'>
+          请检查部署环境中的 runtime-config.json，修正后重新加载。
+        </p>
+        <button
+          className='mt-6 inline-flex h-9 items-center justify-center rounded-md bg-primary px-4 text-sm font-medium text-primary-foreground hover:bg-primary/90 focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none'
+          onClick={() => window.location.reload()}
+          type='button'
+        >
+          重新加载
+        </button>
+      </section>
+    </main>
+  )
+}

package/template/src/config/appConfig.ts

@@ -0,0 +1,126 @@
+import { objBuildInfo } from '@/config/buildInfo'
+import { fnGetRuntimeConfig } from '@/config/runtimeConfig'
+import type {
+  IAppConfig,
+  IRuntimeBrandPalette,
+  IRuntimeConfig,
+} from '@/config/types'
+
+function fnResolvePublicAssetUrl(strPath: string) {
+  if (/^(?:[a-z]+:)?\/\//i.test(strPath) || strPath.startsWith('data:')) {
+    return strPath
+  }
+
+  return `${import.meta.env.BASE_URL}${strPath.replace(/^\/+/, '')}`
+}
+
+function fnCreateAppConfig(objRuntimeConfig: IRuntimeConfig): IAppConfig {
+  const strStorageNamespace = objRuntimeConfig.app.strStorageNamespace
+
+  return Object.freeze({
+    runtime: Object.freeze({
+      strMode: objRuntimeConfig.app.strMode,
+    }),
+    brand: Object.freeze({
+      strId: objRuntimeConfig.app.strBrandId,
+      strName: objRuntimeConfig.app.strTitle,
+      strDescription: objRuntimeConfig.app.strDescription,
+      strLogoUrl: fnResolvePublicAssetUrl(objRuntimeConfig.app.strLogoPath),
+      strDarkLogoUrl: fnResolvePublicAssetUrl(
+        objRuntimeConfig.app.strDarkLogoPath
+      ),
+      strFaviconUrl: fnResolvePublicAssetUrl(
+        objRuntimeConfig.app.strFaviconPath
+      ),
+      objTheme: Object.freeze({
+        objLight: Object.freeze({
+          ...objRuntimeConfig.app.objTheme.objLight,
+        }),
+        objDark: Object.freeze({ ...objRuntimeConfig.app.objTheme.objDark }),
+      }),
+    }),
+    api: Object.freeze({
+      strBaseUrl: objRuntimeConfig.api.strBaseUrl,
+    }),
+    auth: Object.freeze({ ...objRuntimeConfig.auth }),
+    observability: Object.freeze({
+      bEnabled: objRuntimeConfig.observability.bEnabled,
+    }),
+    locale: Object.freeze({ ...objRuntimeConfig.locale }),
+    release: Object.freeze({
+      ...objBuildInfo,
+      strEnvironment: objRuntimeConfig.observability.strEnvironment,
+    }),
+    navigation: Object.freeze({
+      strDefaultAuthenticatedPath: '/dashboard',
+    }),
+    storage: Object.freeze({
+      strAuthSessionKey: `${strStorageNamespace}.auth-session`,
+      strTenantWorkspaceKey: `${strStorageNamespace}.tenant-workspace`,
+      strThemeKey: `${strStorageNamespace}.theme`,
+      strUiPreferenceKey: `${strStorageNamespace}.ui-preferences`,
+    }),
+  })
+}
+
+/** 应用模块统一消费的已校验运行时配置。 */
+export const objAppConfig: IAppConfig = fnCreateAppConfig(fnGetRuntimeConfig())
+
+function fnApplyBrandPaletteVariables(
+  strMode: 'dark' | 'light',
+  objPalette: IRuntimeBrandPalette
+) {
+  const objRoot = document.documentElement
+  objRoot.style.setProperty(
+    `--brand-${strMode}-primary`,
+    objPalette.strPrimaryColor
+  )
+  objRoot.style.setProperty(
+    `--brand-${strMode}-primary-foreground`,
+    objPalette.strPrimaryForegroundColor
+  )
+  objRoot.style.setProperty(
+    `--brand-${strMode}-secondary`,
+    objPalette.strSecondaryColor
+  )
+  objRoot.style.setProperty(
+    `--brand-${strMode}-secondary-foreground`,
+    objPalette.strSecondaryForegroundColor
+  )
+}
+
+/** 将已校验的品牌语义色同步到根节点；不接受任意 CSS 名称或值。 */
+export function fnApplyAppBrandTheme(bIsDarkTheme: boolean) {
+  const objPalette = bIsDarkTheme
+    ? objAppConfig.brand.objTheme.objDark
+    : objAppConfig.brand.objTheme.objLight
+  fnApplyBrandPaletteVariables('light', objAppConfig.brand.objTheme.objLight)
+  fnApplyBrandPaletteVariables('dark', objAppConfig.brand.objTheme.objDark)
+  document
+    .querySelector('meta[name="theme-color"]')
+    ?.setAttribute('content', objPalette.strBrowserThemeColor)
+}
+
+/** 将运行时品牌同步到浏览器文档元数据。 */
+export function fnApplyAppDocumentMetadata() {
+  document.documentElement.dataset.brand = objAppConfig.brand.strId
+  document.title = objAppConfig.brand.strName
+  document
+    .querySelector('meta[name="title"]')
+    ?.setAttribute('content', objAppConfig.brand.strName)
+  document
+    .querySelector('meta[name="description"]')
+    ?.setAttribute('content', objAppConfig.brand.strDescription)
+  const arrIconLinks = Array.from(
+    document.querySelectorAll<HTMLLinkElement>('link[rel~="icon"]')
+  )
+  if (arrIconLinks.length === 0) {
+    const objIconLink = document.createElement('link')
+    objIconLink.rel = 'icon'
+    document.head.append(objIconLink)
+    arrIconLinks.push(objIconLink)
+  }
+  for (const objIconLink of arrIconLinks) {
+    objIconLink.setAttribute('href', objAppConfig.brand.strFaviconUrl)
+  }
+}

package/template/src/config/buildInfo.ts

@@ -0,0 +1,8 @@
+import type { IBuildInfo } from '@/observability/types'
+
+/** 构建时写入、在运行时配置失败时也可读取的公开版本信息。 */
+export const objBuildInfo: Readonly<IBuildInfo> = Object.freeze({
+  strVersion: strBuildAppVersion,
+  strCommit: strBuildCommit,
+  strBuildTime,
+})

package/template/src/config/observabilityAdapter.ts

@@ -0,0 +1,8 @@
+import { fnCreateConsoleObservabilityAdapter } from '@/observability'
+
+/**
+ * 项目级监控供应商接入点。脚手架仅在开发环境输出脱敏事件，生产默认不连接第三方服务。
+ */
+export const objProjectObservabilityAdapter = import.meta.env.DEV
+  ? fnCreateConsoleObservabilityAdapter()
+  : undefined

package/template/src/config/runtimeConfig.ts

@@ -0,0 +1,360 @@
+import { z } from 'zod'
+import type {
+  IRuntimeApplicationConfig,
+  IRuntimeBrandPalette,
+  IRuntimeConfig,
+  TRuntimeConfigErrorCode,
+} from '@/config/types'
+
+const strRuntimeConfigPath = `${import.meta.env.BASE_URL}runtime-config.json`
+
+function fnIsHttpOrRelativeUrl(strValue: string) {
+  try {
+    const objUrl = new URL(strValue, 'https://runtime-config.invalid')
+    return (
+      ['http:', 'https:'].includes(objUrl.protocol) &&
+      !objUrl.username &&
+      !objUrl.password
+    )
+  } catch {
+    return false
+  }
+}
+
+function fnIsBrandAssetLocation(strValue: string) {
+  if (strValue.startsWith('data:')) {
+    return /^data:image\/(?:gif|jpeg|png|webp);base64,[a-z0-9+/]+={0,2}$/i.test(
+      strValue
+    )
+  }
+  return strValue.length <= 2048 && fnIsHttpOrRelativeUrl(strValue)
+}
+
+function fnIsIanaTimeZone(strValue: string) {
+  try {
+    new Intl.DateTimeFormat('en-US', { timeZone: strValue }).format()
+    return true
+  } catch {
+    return false
+  }
+}
+
+const objDefaultLightBrandPalette: IRuntimeBrandPalette = {
+  strPrimaryColor: '#4068d5',
+  strPrimaryForegroundColor: '#ffffff',
+  strSecondaryColor: '#49beff',
+  strSecondaryForegroundColor: '#102a43',
+  strBrowserThemeColor: '#ffffff',
+}
+
+const objDefaultDarkBrandPalette: IRuntimeBrandPalette = {
+  strPrimaryColor: '#8aadff',
+  strPrimaryForegroundColor: '#0f172a',
+  strSecondaryColor: '#49beff',
+  strSecondaryForegroundColor: '#102a43',
+  strBrowserThemeColor: '#000000',
+}
+
+function fnGetRelativeLuminance(strColor: string) {
+  const objMatch = /^#([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(strColor)
+  if (!objMatch) return 0
+  const arrChannels = objMatch.slice(1).map((strChannel) => {
+    const nChannel = Number.parseInt(strChannel, 16) / 255
+    return nChannel <= 0.04045
+      ? nChannel / 12.92
+      : ((nChannel + 0.055) / 1.055) ** 2.4
+  })
+  return (
+    0.2126 * arrChannels[0] + 0.7152 * arrChannels[1] + 0.0722 * arrChannels[2]
+  )
+}
+
+function fnGetContrastRatio(strBackground: string, strForeground: string) {
+  const nBackground = fnGetRelativeLuminance(strBackground)
+  const nForeground = fnGetRelativeLuminance(strForeground)
+  const nLighter = Math.max(nBackground, nForeground)
+  const nDarker = Math.min(nBackground, nForeground)
+  return (nLighter + 0.05) / (nDarker + 0.05)
+}
+
+const objHexColorSchema = z
+  .string()
+  .trim()
+  .regex(/^#[a-f\d]{6}$/i)
+const objRuntimeBrandPaletteSchema = z
+  .object({
+    strPrimaryColor: objHexColorSchema,
+    strPrimaryForegroundColor: objHexColorSchema,
+    strSecondaryColor: objHexColorSchema,
+    strSecondaryForegroundColor: objHexColorSchema,
+    strBrowserThemeColor: objHexColorSchema,
+  })
+  .strict()
+  .superRefine((objPalette, objContext) => {
+    const arrPairs = [
+      {
+        strBackground: objPalette.strPrimaryColor,
+        strForeground: objPalette.strPrimaryForegroundColor,
+        strPath: 'strPrimaryForegroundColor',
+      },
+      {
+        strBackground: objPalette.strSecondaryColor,
+        strForeground: objPalette.strSecondaryForegroundColor,
+        strPath: 'strSecondaryForegroundColor',
+      },
+    ]
+    for (const objPair of arrPairs) {
+      if (
+        fnGetContrastRatio(objPair.strBackground, objPair.strForeground) < 4.5
+      ) {
+        objContext.addIssue({
+          code: 'custom',
+          message: '品牌背景色与前景色的对比度必须达到 WCAG AA 4.5:1。',
+          path: [objPair.strPath],
+        })
+      }
+    }
+  })
+
+const objRuntimeBrandThemeSchema = z
+  .object({
+    objLight: objRuntimeBrandPaletteSchema,
+    objDark: objRuntimeBrandPaletteSchema,
+  })
+  .strict()
+  .superRefine((objTheme, objContext) => {
+    const arrModes = [
+      {
+        objPalette: objTheme.objLight,
+        strBackground: '#ffffff',
+        strPath: 'objLight',
+      },
+      {
+        objPalette: objTheme.objDark,
+        strBackground: '#000000',
+        strPath: 'objDark',
+      },
+    ]
+    for (const objMode of arrModes) {
+      if (
+        fnGetContrastRatio(
+          objMode.objPalette.strPrimaryColor,
+          objMode.strBackground
+        ) < 4.5
+      ) {
+        objContext.addIssue({
+          code: 'custom',
+          message:
+            '品牌主色作为链接和强调文本时必须与页面背景达到 WCAG AA 4.5:1。',
+          path: [objMode.strPath, 'strPrimaryColor'],
+        })
+      }
+    }
+  })
+  .default({
+    objLight: objDefaultLightBrandPalette,
+    objDark: objDefaultDarkBrandPalette,
+  })
+
+const objRuntimeApplicationSchema = z
+  .object({
+    strBrandId: z
+      .string()
+      .trim()
+      .regex(/^[a-z0-9]+(?:[._-][a-z0-9]+)*$/i)
+      .optional(),
+    strTitle: z.string().trim().min(1),
+    strDescription: z.string().trim().min(1),
+    strLogoPath: z
+      .string()
+      .trim()
+      .min(1)
+      .max(500_000)
+      .refine(fnIsBrandAssetLocation),
+    strDarkLogoPath: z
+      .string()
+      .trim()
+      .min(1)
+      .max(500_000)
+      .refine(fnIsBrandAssetLocation)
+      .optional(),
+    strFaviconPath: z
+      .string()
+      .trim()
+      .min(1)
+      .max(500_000)
+      .refine(fnIsBrandAssetLocation)
+      .optional(),
+    strStorageNamespace: z
+      .string()
+      .trim()
+      .regex(/^[a-z0-9]+(?:[._-][a-z0-9]+)*$/i),
+    strMode: z.enum(['connected', 'demo']),
+    objTheme: objRuntimeBrandThemeSchema,
+  })
+  .strict()
+
+const objRuntimeApiSchema = z
+  .object({
+    strBaseUrl: z
+      .string()
+      .trim()
+      .refine((strValue) => !strValue || fnIsHttpOrRelativeUrl(strValue))
+      .transform((strValue) => strValue.replace(/\/+$/, '')),
+  })
+  .strict()
+
+const objRuntimeAuthSchema = z
+  .object({
+    strAudience: z.string().trim().min(1),
+    strClientId: z.string().trim().min(1),
+    strScope: z.string().trim().min(1),
+    strSessionStorage: z.enum(['memory', 'session']),
+    strSignInPath: z.string().trim().min(1).refine(fnIsHttpOrRelativeUrl),
+    strRefreshPath: z.string().trim().min(1).refine(fnIsHttpOrRelativeUrl),
+    strSignOutPath: z.string().trim().min(1).refine(fnIsHttpOrRelativeUrl),
+  })
+  .strict()
+
+const objRuntimeObservabilitySchema = z
+  .object({
+    bEnabled: z.boolean(),
+    strEnvironment: z
+      .string()
+      .trim()
+      .regex(/^[a-z0-9]+(?:[._-][a-z0-9]+)*$/i),
+  })
+  .strict()
+
+const objRuntimeLocaleSchema = z
+  .object({
+    strLocale: z.enum(['en-US', 'zh-CN']),
+    strTimeZone: z.string().trim().min(1).refine(fnIsIanaTimeZone),
+  })
+  .strict()
+
+const objRuntimeConfigSchema = z
+  .object({
+    nSchemaVersion: z.literal(1),
+    app: objRuntimeApplicationSchema,
+    api: objRuntimeApiSchema,
+    auth: objRuntimeAuthSchema,
+    locale: objRuntimeLocaleSchema.default({
+      strLocale: 'zh-CN',
+      strTimeZone: 'Asia/Shanghai',
+    }),
+    observability: objRuntimeObservabilitySchema.default({
+      bEnabled: false,
+      strEnvironment: 'local',
+    }),
+  })
+  .strict()
+
+let objLoadedRuntimeConfig: IRuntimeConfig | undefined
+
+export class RuntimeConfigError extends Error {
+  constructor(
+    readonly strCode: TRuntimeConfigErrorCode,
+    strMessage: string
+  ) {
+    super(strMessage)
+    this.name = 'RuntimeConfigError'
+  }
+}
+
+/** 校验来自部署环境的公开运行时配置，并冻结全部层级。 */
+export function fnParseRuntimeConfig(objInput: unknown): IRuntimeConfig {
+  const objResult = objRuntimeConfigSchema.safeParse(objInput)
+
+  if (!objResult.success) {
+    const strIssues = objResult.error.issues
+      .map(
+        (objIssue) =>
+          `${objIssue.path.join('.') || 'root'}: ${objIssue.message}`
+      )
+      .join('; ')
+    throw new RuntimeConfigError(
+      'invalid_config',
+      `runtime-config.json 配置不符合契约：${strIssues}`
+    )
+  }
+
+  const objParsedConfig = objResult.data
+  const objApplicationConfig: IRuntimeApplicationConfig = {
+    ...objParsedConfig.app,
+    strBrandId:
+      objParsedConfig.app.strBrandId ?? objParsedConfig.app.strStorageNamespace,
+    strDarkLogoPath:
+      objParsedConfig.app.strDarkLogoPath ?? objParsedConfig.app.strLogoPath,
+    strFaviconPath: objParsedConfig.app.strFaviconPath ?? 'favicon.ico',
+  }
+  const objConfig: IRuntimeConfig = {
+    ...objParsedConfig,
+    app: objApplicationConfig,
+  }
+  return Object.freeze({
+    ...objConfig,
+    app: Object.freeze({
+      ...objConfig.app,
+      objTheme: Object.freeze({
+        objLight: Object.freeze({ ...objConfig.app.objTheme.objLight }),
+        objDark: Object.freeze({ ...objConfig.app.objTheme.objDark }),
+      }),
+    }),
+    api: Object.freeze(objConfig.api),
+    auth: Object.freeze(objConfig.auth),
+    locale: Object.freeze(objConfig.locale),
+    observability: Object.freeze(objConfig.observability),
+  })
+}
+
+/** 在加载应用模块前获取并校验运行时配置。 */
+export async function fnLoadRuntimeConfig(
+  fnFetch: typeof fetch = fetch
+): Promise<IRuntimeConfig> {
+  let objResponse: Response
+
+  try {
+    objResponse = await fnFetch(strRuntimeConfigPath, {
+      cache: 'no-store',
+      credentials: 'same-origin',
+      headers: { Accept: 'application/json' },
+    })
+  } catch {
+    throw new RuntimeConfigError(
+      'load_failed',
+      `无法加载 ${strRuntimeConfigPath}，请检查部署文件和网络。`
+    )
+  }
+
+  if (!objResponse.ok) {
+    throw new RuntimeConfigError(
+      'load_failed',
+      `无法加载 ${strRuntimeConfigPath}（HTTP ${objResponse.status}）。`
+    )
+  }
+
+  let objInput: unknown
+  try {
+    objInput = await objResponse.json()
+  } catch {
+    throw new RuntimeConfigError(
+      'invalid_json',
+      `${strRuntimeConfigPath} 不是有效的 JSON。`
+    )
+  }
+
+  objLoadedRuntimeConfig = fnParseRuntimeConfig(objInput)
+  return objLoadedRuntimeConfig
+}
+
+/** 仅供运行时配置加载完成后的应用模块读取。 */
+export function fnGetRuntimeConfig(): IRuntimeConfig {
+  if (!objLoadedRuntimeConfig) {
+    throw new RuntimeConfigError(
+      'not_initialized',
+      '应用模块加载前必须先初始化运行时配置。'
+    )
+  }
+  return objLoadedRuntimeConfig
+}