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

package/template/src/router/RootRouteLayout.tsx

@@ -0,0 +1,11 @@
+import { Outlet } from '@tanstack/react-router'
+import { UnsavedChangesProvider } from '@/context/UnsavedChangesProvider'
+
+/** 为全部路由分支安装一次跨组件未保存内容保护。 */
+export function RootRouteLayout() {
+  return (
+    <UnsavedChangesProvider>
+      <Outlet />
+    </UnsavedChangesProvider>
+  )
+}

package/template/src/router/authLifecycle.ts

@@ -0,0 +1,39 @@
+interface IAuthStateSnapshot {
+  bIsAuthenticated: boolean
+  nSessionGeneration: number
+}
+
+interface IAuthLifecycleEffects {
+  fnClearQueryCache: () => void
+  fnInvalidateRouter: () => void
+  fnNavigateToSignIn: () => void
+}
+
+/**
+ * 统一处理认证会话结束后的跨模块副作用。
+ *
+ * Zustand Store 只持有认证状态；路由跳转和请求缓存清理由应用层在状态边沿触发，
+ * 避免 API、页头和侧栏各自维护一套退出逻辑。
+ */
+export function fnHandleAuthSessionTransition(
+  objCurrentState: IAuthStateSnapshot,
+  objPreviousState: IAuthStateSnapshot,
+  {
+    fnClearQueryCache,
+    fnInvalidateRouter,
+    fnNavigateToSignIn,
+  }: IAuthLifecycleEffects
+) {
+  const bSessionChanged =
+    objCurrentState.nSessionGeneration !== objPreviousState.nSessionGeneration
+  const bSessionEnded =
+    objPreviousState.bIsAuthenticated && !objCurrentState.bIsAuthenticated
+
+  if (bSessionChanged) {
+    fnClearQueryCache()
+    fnInvalidateRouter()
+  }
+  if (bSessionEnded) fnNavigateToSignIn()
+
+  return bSessionChanged || bSessionEnded
+}

package/template/src/router/config.ts

@@ -0,0 +1,293 @@
+import {
+  Outlet,
+  createRootRouteWithContext,
+  createRoute,
+  redirect,
+} from '@tanstack/react-router'
+import { objAppConfig } from '@/config/appConfig'
+import {
+  CircleAlert,
+  FileUp,
+  FileQuestion,
+  House,
+  KeyRound,
+  ListChecks,
+  MessageSquareMore,
+  PanelsTopLeft,
+  ServerCrash,
+  ShieldCheck,
+  ShieldX,
+  SlidersHorizontal,
+  TableProperties,
+  Wrench,
+} from 'lucide-react'
+import { RootRouteLayout } from './RootRouteLayout'
+import { fnInterceptRoute } from './interceptors'
+import {
+  AuthLayout,
+  AccessShowcasePage,
+  AppLayout,
+  ForbiddenError,
+  FeedbackShowcasePage,
+  FileShowcasePage,
+  FormShowcasePage,
+  GeneralError,
+  Home,
+  MaintenanceError,
+  MetadataShowcasePage,
+  NotFoundError,
+  RouteError,
+  SignIn,
+  TableShowcasePage,
+  UnauthorizedError,
+} from './lazyRouteComponents'
+import { fnValidateSignInSearch } from './searchSchemas'
+import type { IRouterContext } from './types'
+
+const objRootRoute = createRootRouteWithContext<IRouterContext>()({
+  component: RootRouteLayout,
+  notFoundComponent: NotFoundError,
+  errorComponent: RouteError,
+})
+
+const objIndexRoute = createRoute({
+  getParentRoute: () => objRootRoute,
+  path: '/',
+  beforeLoad: (objOptions) => fnInterceptRoute(objOptions, 'entry'),
+})
+
+const objGuestRoute = createRoute({
+  getParentRoute: () => objRootRoute,
+  id: '_guest',
+  beforeLoad: (objOptions) => fnInterceptRoute(objOptions, 'guest'),
+  component: AuthLayout,
+})
+
+const objSignInRoute = createRoute({
+  getParentRoute: () => objGuestRoute,
+  path: 'sign-in',
+  validateSearch: fnValidateSignInSearch,
+  component: SignIn,
+  staticData: {
+    strTitle: 'route.signIn.title',
+  },
+})
+
+const objSignUpRoute = createRoute({
+  getParentRoute: () => objGuestRoute,
+  path: 'sign-up',
+  beforeLoad: () => {
+    throw redirect({ to: '/sign-in', replace: true })
+  },
+  staticData: {
+    strTitle: 'route.signUp.title',
+  },
+})
+
+const objAppRoute = createRoute({
+  getParentRoute: () => objRootRoute,
+  id: '_app',
+  beforeLoad: (objOptions) => fnInterceptRoute(objOptions, 'authenticated'),
+  component: AppLayout,
+})
+
+const objHomeRoute = createRoute({
+  getParentRoute: () => objAppRoute,
+  path: 'dashboard',
+  component: Home,
+  staticData: {
+    strTitle: 'route.home.title',
+    Icon: House,
+    strNavigationGroup: 'route.group.workspace',
+    nNavigationGroupOrder: 10,
+    nNavigationOrder: 10,
+  },
+})
+
+const objShowcaseRoute = createRoute({
+  getParentRoute: () => objAppRoute,
+  path: 'showcase',
+  component: Outlet,
+  staticData: {
+    strTitle: 'route.showcase.title',
+    Icon: PanelsTopLeft,
+    strNavigationGroup: 'route.group.showcase',
+    nNavigationGroupOrder: 20,
+    nNavigationOrder: 10,
+  },
+})
+
+const objShowcaseIndexRoute = createRoute({
+  getParentRoute: () => objShowcaseRoute,
+  path: '/',
+  beforeLoad: () => {
+    throw redirect({ to: '/showcase/table', replace: true })
+  },
+})
+
+const objAccessShowcaseRoute = createRoute({
+  getParentRoute: () => objShowcaseRoute,
+  path: 'access',
+  component: AccessShowcasePage,
+  staticData: {
+    strTitle: 'route.showcase.access',
+    Icon: ShieldCheck,
+    nNavigationOrder: 5,
+    strPermission: 'showcase:access',
+  },
+})
+
+const objTableShowcaseRoute = createRoute({
+  getParentRoute: () => objShowcaseRoute,
+  path: 'table',
+  component: TableShowcasePage,
+  staticData: {
+    strTitle: 'route.showcase.table',
+    Icon: TableProperties,
+    nNavigationOrder: 10,
+  },
+})
+
+const objFormShowcaseRoute = createRoute({
+  getParentRoute: () => objShowcaseRoute,
+  path: 'form',
+  component: FormShowcasePage,
+  staticData: {
+    strTitle: 'route.showcase.form',
+    Icon: ListChecks,
+    nNavigationOrder: 20,
+  },
+})
+
+const objMetadataShowcaseRoute = createRoute({
+  getParentRoute: () => objShowcaseRoute,
+  path: 'metadata',
+  component: MetadataShowcasePage,
+  staticData: {
+    strTitle: 'route.showcase.metadata',
+    Icon: SlidersHorizontal,
+    nNavigationOrder: 30,
+  },
+})
+
+const objFileShowcaseRoute = createRoute({
+  getParentRoute: () => objShowcaseRoute,
+  path: 'files',
+  component: FileShowcasePage,
+  staticData: {
+    strTitle: 'route.showcase.files',
+    Icon: FileUp,
+    nNavigationOrder: 40,
+  },
+})
+
+const objFeedbackShowcaseRoute = createRoute({
+  getParentRoute: () => objShowcaseRoute,
+  path: 'feedback',
+  component: FeedbackShowcasePage,
+  staticData: {
+    strTitle: 'route.showcase.feedback',
+    Icon: MessageSquareMore,
+    nNavigationOrder: 50,
+  },
+})
+
+const objErrorsRoute = createRoute({
+  getParentRoute: () => objRootRoute,
+  path: 'errors',
+  beforeLoad: (objOptions) => fnInterceptRoute(objOptions, 'authenticated'),
+  component: Outlet,
+  staticData: {
+    strTitle: 'route.error.title',
+    Icon: CircleAlert,
+    strNavigationGroup: 'route.group.system',
+    nNavigationGroupOrder: 20,
+    nNavigationOrder: 10,
+    bShowInSidebar: false,
+  },
+})
+
+const objUnauthorizedRoute = createRoute({
+  getParentRoute: () => objErrorsRoute,
+  path: '401',
+  component: UnauthorizedError,
+  staticData: {
+    strTitle: 'route.error.unauthorized',
+    Icon: KeyRound,
+    nNavigationOrder: 10,
+  },
+})
+
+const objForbiddenRoute = createRoute({
+  getParentRoute: () => objErrorsRoute,
+  path: '403',
+  component: ForbiddenError,
+  staticData: {
+    strTitle: 'route.error.forbidden',
+    Icon: ShieldX,
+    nNavigationOrder: 20,
+  },
+})
+
+const objNotFoundRoute = createRoute({
+  getParentRoute: () => objErrorsRoute,
+  path: '404',
+  component: NotFoundError,
+  staticData: {
+    strTitle: 'route.error.notFound',
+    Icon: FileQuestion,
+    nNavigationOrder: 30,
+  },
+})
+
+const objInternalServerErrorRoute = createRoute({
+  getParentRoute: () => objErrorsRoute,
+  path: '500',
+  component: GeneralError,
+  staticData: {
+    strTitle: 'route.error.general',
+    Icon: ServerCrash,
+    nNavigationOrder: 40,
+  },
+})
+
+const objMaintenanceRoute = createRoute({
+  getParentRoute: () => objErrorsRoute,
+  path: '503',
+  component: MaintenanceError,
+  staticData: {
+    strTitle: 'route.error.maintenance',
+    Icon: Wrench,
+    nNavigationOrder: 50,
+  },
+})
+
+const arrAuthenticatedRoutes = [
+  objHomeRoute,
+  ...(objAppConfig.runtime.strMode === 'demo'
+    ? [
+        objShowcaseRoute.addChildren([
+          objShowcaseIndexRoute,
+          objAccessShowcaseRoute,
+          objTableShowcaseRoute,
+          objFormShowcaseRoute,
+          objMetadataShowcaseRoute,
+          objFileShowcaseRoute,
+          objFeedbackShowcaseRoute,
+        ]),
+      ]
+    : []),
+]
+
+export const objRouteTree = objRootRoute.addChildren([
+  objIndexRoute,
+  objGuestRoute.addChildren([objSignInRoute, objSignUpRoute]),
+  objAppRoute.addChildren(arrAuthenticatedRoutes),
+  objErrorsRoute.addChildren([
+    objUnauthorizedRoute,
+    objForbiddenRoute,
+    objNotFoundRoute,
+    objInternalServerErrorRoute,
+    objMaintenanceRoute,
+  ]),
+])

package/template/src/router/interceptors.ts

@@ -0,0 +1,48 @@
+import { redirect } from '@tanstack/react-router'
+import {
+  fnParseInternalRedirect,
+  strDefaultAuthenticatedPath,
+} from '@/lib/navigationRedirect'
+import type { IRouterContext } from './types'
+
+type TRouteAccessMode = 'entry' | 'guest' | 'authenticated'
+
+interface IRouteInterceptorOptions {
+  context: Pick<IRouterContext, 'objAuth'>
+  location: { href: string }
+}
+
+export function fnInterceptRoute(
+  { context: objContext, location: objLocation }: IRouteInterceptorOptions,
+  strAccessMode: TRouteAccessMode,
+  strPermission?: string
+) {
+  const bIsAuthenticated = objContext.objAuth.fnIsAuthenticated()
+
+  if (strAccessMode === 'entry') {
+    throw redirect({
+      to: bIsAuthenticated ? strDefaultAuthenticatedPath : '/sign-in',
+      replace: true,
+    })
+  }
+
+  if (strAccessMode === 'guest') {
+    if (bIsAuthenticated) {
+      throw redirect({ to: strDefaultAuthenticatedPath, replace: true })
+    }
+
+    return
+  }
+
+  if (!bIsAuthenticated) {
+    throw redirect({
+      to: '/sign-in',
+      search: { redirect: fnParseInternalRedirect(objLocation.href) },
+      replace: true,
+    })
+  }
+
+  if (strPermission && !objContext.objAuth.fnHasPermission(strPermission)) {
+    throw redirect({ to: '/errors/403', replace: true })
+  }
+}

package/template/src/router/lazyRouteComponents.ts

@@ -0,0 +1,78 @@
+import { lazyRouteComponent } from '@tanstack/react-router'
+
+export const AppLayout = lazyRouteComponent(
+  () => import('@/layouts/AppLayout'),
+  'AppLayout'
+)
+
+export const SignIn = lazyRouteComponent(
+  () => import('@/features/auth'),
+  'SignIn'
+)
+
+export const AuthLayout = lazyRouteComponent(
+  () => import('@/features/auth'),
+  'AuthLayout'
+)
+
+export const Home = lazyRouteComponent(() => import('@/features/home'), 'Home')
+
+export const AccessShowcasePage = lazyRouteComponent(
+  () => import('@/features/showcase'),
+  'AccessShowcasePage'
+)
+
+export const TableShowcasePage = lazyRouteComponent(
+  () => import('@/features/showcase'),
+  'TableShowcasePage'
+)
+
+export const FormShowcasePage = lazyRouteComponent(
+  () => import('@/features/showcase'),
+  'FormShowcasePage'
+)
+
+export const MetadataShowcasePage = lazyRouteComponent(
+  () => import('@/features/showcase'),
+  'MetadataShowcasePage'
+)
+
+export const FileShowcasePage = lazyRouteComponent(
+  () => import('@/features/showcase'),
+  'FileShowcasePage'
+)
+
+export const FeedbackShowcasePage = lazyRouteComponent(
+  () => import('@/features/showcase'),
+  'FeedbackShowcasePage'
+)
+
+export const UnauthorizedError = lazyRouteComponent(
+  () => import('@/features/errors'),
+  'UnauthorizedError'
+)
+
+export const ForbiddenError = lazyRouteComponent(
+  () => import('@/features/errors'),
+  'ForbiddenError'
+)
+
+export const NotFoundError = lazyRouteComponent(
+  () => import('@/features/errors'),
+  'NotFoundError'
+)
+
+export const GeneralError = lazyRouteComponent(
+  () => import('@/features/errors'),
+  'GeneralError'
+)
+
+export const RouteError = lazyRouteComponent(
+  () => import('@/features/errors'),
+  'RouteError'
+)
+
+export const MaintenanceError = lazyRouteComponent(
+  () => import('@/features/errors'),
+  'MaintenanceError'
+)

package/template/src/router/messages.ts

@@ -0,0 +1,48 @@
+import { fnDefineLocaleMessages } from '@/locale'
+import type { TRouteMessageKey } from './types'
+
+/** 路由标题和导航分组的完整中英文语言包。 */
+export const objRouteMessages = fnDefineLocaleMessages<TRouteMessageKey>({
+  'en-US': {
+    'route.error.forbidden': 'Forbidden',
+    'route.error.general': 'Server error',
+    'route.error.maintenance': 'Maintenance',
+    'route.error.notFound': 'Page not found',
+    'route.error.title': 'Error pages',
+    'route.error.unauthorized': 'Sign-in required',
+    'route.group.system': 'System',
+    'route.group.showcase': 'Live demos',
+    'route.group.workspace': 'Workspace',
+    'route.home.title': 'Home',
+    'route.showcase.access': 'Identity and access',
+    'route.showcase.feedback': 'Dialogs and feedback',
+    'route.showcase.files': 'Upload and preview',
+    'route.showcase.form': 'PageForm scenarios',
+    'route.showcase.metadata': 'Enums and parameters',
+    'route.showcase.table': 'Table scenarios',
+    'route.showcase.title': 'Feature demos',
+    'route.signIn.title': 'Sign in',
+    'route.signUp.title': 'Sign up',
+  },
+  'zh-CN': {
+    'route.error.forbidden': '无权访问',
+    'route.error.general': '服务器错误',
+    'route.error.maintenance': '系统维护',
+    'route.error.notFound': '页面不存在',
+    'route.error.title': '错误页面',
+    'route.error.unauthorized': '未登录',
+    'route.group.system': '系统页面',
+    'route.group.showcase': '功能演示',
+    'route.group.workspace': '工作台',
+    'route.home.title': '首页',
+    'route.showcase.access': '身份、会话与权限',
+    'route.showcase.feedback': '弹窗与反馈',
+    'route.showcase.files': '上传与预览',
+    'route.showcase.form': 'PageForm 场景',
+    'route.showcase.metadata': '枚举与参数',
+    'route.showcase.table': '表格业务场景',
+    'route.showcase.title': '功能演示',
+    'route.signIn.title': '登录',
+    'route.signUp.title': '注册',
+  },
+})

package/template/src/router/navigation.ts

@@ -0,0 +1,167 @@
+import type { RegisteredRouter } from '@tanstack/react-router'
+import type {
+  INavigationCatalogEntry,
+  INavigationCatalogGroup,
+  TRouteMessageKey,
+} from './types'
+
+type TAppRoute =
+  RegisteredRouter['routesById'][keyof RegisteredRouter['routesById']]
+
+function fnGetParentRouteId(strRouteId: string) {
+  const nLastSeparatorIndex = strRouteId.lastIndexOf('/')
+  return nLastSeparatorIndex > 0
+    ? strRouteId.slice(0, nLastSeparatorIndex)
+    : undefined
+}
+
+function fnGetNavigationOrder(objRoute: TAppRoute) {
+  return (
+    objRoute.options.staticData?.nNavigationOrder ?? Number.MAX_SAFE_INTEGER
+  )
+}
+
+function fnCompareNavigationEntries(
+  objLeft: INavigationCatalogEntry,
+  objRight: INavigationCatalogEntry,
+  fnCompare: (strLeft: string, strRight: string) => number
+) {
+  return objLeft.nOrder === objRight.nOrder
+    ? fnCompare(objLeft.strTitle, objRight.strTitle)
+    : objLeft.nOrder - objRight.nOrder
+}
+
+/** 判断路由是否满足导航目录的基础展示契约。 */
+function fnIsNavigationRouteVisible(
+  objRoute: TAppRoute,
+  fnHasPermission: (strPermission?: string) => boolean
+) {
+  const objStaticData = objRoute.options.staticData
+
+  return Boolean(
+    objStaticData?.bShowInSidebar !== false &&
+    objStaticData?.strTitle &&
+    objStaticData.Icon &&
+    fnHasPermission(objStaticData.strPermission)
+  )
+}
+
+/** 读取一个父路由下满足同一权限和可见性规则的直接子路由。 */
+function fnGetVisibleNavigationChildren(
+  objRouter: RegisteredRouter,
+  objRoute: TAppRoute,
+  fnHasPermission: (strPermission?: string) => boolean
+) {
+  return Object.values(objRouter.routesById).filter(
+    (objChildRoute) =>
+      fnGetParentRouteId(objChildRoute.id) === objRoute.id &&
+      fnIsNavigationRouteVisible(objChildRoute, fnHasPermission)
+  )
+}
+
+function fnCreateNavigationEntry(
+  objRouter: RegisteredRouter,
+  objRoute: TAppRoute,
+  fnHasPermission: (strPermission?: string) => boolean,
+  fnCompare: (strLeft: string, strRight: string) => number,
+  fnTranslateRoute: (strKey: TRouteMessageKey) => string
+): INavigationCatalogEntry | null {
+  const objStaticData = objRoute.options.staticData
+  if (
+    !objStaticData?.strTitle ||
+    !fnIsNavigationRouteVisible(objRoute, fnHasPermission)
+  ) {
+    return null
+  }
+
+  const arrChildren = fnGetVisibleNavigationChildren(
+    objRouter,
+    objRoute,
+    fnHasPermission
+  )
+    .map((objChildRoute) =>
+      fnCreateNavigationEntry(
+        objRouter,
+        objChildRoute,
+        fnHasPermission,
+        fnCompare,
+        fnTranslateRoute
+      )
+    )
+    .filter((objEntry): objEntry is INavigationCatalogEntry =>
+      Boolean(objEntry)
+    )
+    .sort((objLeft, objRight) =>
+      fnCompareNavigationEntries(objLeft, objRight, fnCompare)
+    )
+
+  if (Array.isArray(objRoute.children) && arrChildren.length === 0) return null
+
+  return Object.freeze({
+    arrChildren: Object.freeze(arrChildren),
+    nOrder: fnGetNavigationOrder(objRoute),
+    objRoute,
+    strTitle: fnTranslateRoute(objStaticData.strTitle),
+  })
+}
+
+/** 从 Route metadata 创建侧栏、搜索和面包屑共用的稳定导航目录。 */
+export function fnCreateNavigationCatalog(
+  objRouter: RegisteredRouter,
+  fnHasPermission: (strPermission?: string) => boolean,
+  fnCompare: (strLeft: string, strRight: string) => number,
+  fnTranslateRoute: (strKey: TRouteMessageKey) => string
+): readonly INavigationCatalogGroup[] {
+  const objGroups = new Map<TRouteMessageKey, INavigationCatalogGroup>()
+
+  Object.values(objRouter.routesById).forEach((objRoute) => {
+    const objStaticData = objRoute.options.staticData
+    const strGroupKey = objStaticData?.strNavigationGroup
+    if (!strGroupKey) return
+
+    const objEntry = fnCreateNavigationEntry(
+      objRouter,
+      objRoute,
+      fnHasPermission,
+      fnCompare,
+      fnTranslateRoute
+    )
+    if (!objEntry) return
+
+    const objCurrentGroup = objGroups.get(strGroupKey)
+    objGroups.set(
+      strGroupKey,
+      Object.freeze({
+        arrEntries: Object.freeze([
+          ...(objCurrentGroup?.arrEntries ?? []),
+          objEntry,
+        ]),
+        nOrder:
+          objCurrentGroup?.nOrder ??
+          objStaticData.nNavigationGroupOrder ??
+          Number.MAX_SAFE_INTEGER,
+        strKey: strGroupKey,
+        strTitle: fnTranslateRoute(strGroupKey),
+      })
+    )
+  })
+
+  return Object.freeze(
+    Array.from(objGroups.values())
+      .map((objGroup) =>
+        Object.freeze({
+          ...objGroup,
+          arrEntries: Object.freeze(
+            [...objGroup.arrEntries].sort((objLeft, objRight) =>
+              fnCompareNavigationEntries(objLeft, objRight, fnCompare)
+            )
+          ),
+        })
+      )
+      .sort((objLeft, objRight) =>
+        objLeft.nOrder === objRight.nOrder
+          ? fnCompare(objLeft.strTitle, objRight.strTitle)
+          : objLeft.nOrder - objRight.nOrder
+      )
+  )
+}