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

package/template/src/components/SensitiveData/types.ts

@@ -0,0 +1,31 @@
+import type {
+  IDataMaskingPolicy,
+  SensitiveDataError,
+  TSensitiveDataClipboardAdapter,
+  TSensitiveDataCopyPolicy,
+  TSensitiveDataRevealAdapter,
+  TSensitiveDataRevealPolicy,
+  TSensitiveDataValue,
+} from '@/dataMasking'
+
+/** 安全展示、临时查看和复制一项敏感数据的组件参数。 */
+export interface ISensitiveDataProps {
+  /** 后端脱敏值或已经过后端数据权限授权的原始值。 */
+  readonly objValue: TSensitiveDataValue
+  /** 用于前端默认展示的脱敏策略。 */
+  readonly objMaskingPolicy: IDataMaskingPolicy
+  /** 原始值临时查看策略，默认禁用。 */
+  readonly objRevealPolicy?: TSensitiveDataRevealPolicy
+  /** 脱敏值或原始值复制策略，默认禁用。 */
+  readonly objCopyPolicy?: TSensitiveDataCopyPolicy
+  /** 字段可访问名称，用于查看和复制按钮的无障碍文案。 */
+  readonly strLabel: string
+  /** 根元素的可选样式类名。 */
+  readonly strClassName?: string
+  /** 后端仅返回脱敏值时，按需加载原始值的生成客户端 Adapter。 */
+  readonly fnRequestReveal?: TSensitiveDataRevealAdapter
+  /** 可替换的剪贴板写入 Adapter；默认使用安全上下文 Clipboard API。 */
+  readonly fnWriteClipboard?: TSensitiveDataClipboardAdapter
+  /** 接收不含原始值的稳定错误，供页面统一反馈。 */
+  readonly fnOnError?: (objError: SensitiveDataError) => void
+}

package/template/src/components/StatusBadge/StatusBadge.tsx

@@ -0,0 +1,28 @@
+import { cn } from '@/lib/utils'
+import { Badge } from '@/components/ui/badge'
+import { fnResolveStatusBadgeTone, objToneClasses } from './statusBadgeStyles'
+import type { TStatusBadgeTone } from './types'
+
+export function StatusBadge({
+  strStatus,
+  strLabel,
+  strTone = fnResolveStatusBadgeTone(strStatus),
+  strClassName,
+}: {
+  strStatus: string
+  strLabel: string
+  strTone?: TStatusBadgeTone
+  strClassName?: string
+}) {
+  return (
+    <Badge
+      variant='outline'
+      data-slot='status-badge'
+      data-status={strStatus}
+      data-tone={strTone}
+      className={cn('rounded-full', objToneClasses[strTone], strClassName)}
+    >
+      {strLabel}
+    </Badge>
+  )
+}

package/template/src/components/StatusBadge/index.ts

@@ -0,0 +1,2 @@
+export { StatusBadge } from './StatusBadge'
+export type { TStatusBadgeTone } from './types'

package/template/src/components/StatusBadge/statusBadgeStyles.ts

@@ -0,0 +1,30 @@
+import type { TStatusBadgeTone } from './types'
+
+export const objToneClasses: Record<TStatusBadgeTone, string> = {
+  neutral: 'border-transparent bg-muted text-muted-foreground dark:bg-muted/70',
+  info: 'border-transparent bg-blue-100 text-blue-700 dark:bg-blue-950 dark:text-blue-300',
+  accent:
+    'border-transparent bg-violet-100 text-violet-700 dark:bg-violet-950 dark:text-violet-300',
+  success:
+    'border-transparent bg-emerald-100 text-emerald-700 dark:bg-emerald-950 dark:text-emerald-300',
+  warning:
+    'border-transparent bg-amber-100 text-amber-800 dark:bg-amber-950 dark:text-amber-300',
+  danger:
+    'border-transparent bg-destructive/10 text-destructive dark:bg-destructive/20',
+}
+
+const objGenericStatusTones = new Map<string, TStatusBadgeTone>([
+  ['active', 'success'],
+  ['completed', 'success'],
+  ['enabled', 'success'],
+  ['pending', 'warning'],
+  ['error', 'danger'],
+  ['failed', 'danger'],
+  ['disabled', 'neutral'],
+  ['inactive', 'neutral'],
+  ['unknown', 'neutral'],
+])
+
+export function fnResolveStatusBadgeTone(strStatus: string) {
+  return objGenericStatusTones.get(strStatus) ?? 'neutral'
+}

package/template/src/components/StatusBadge/types.ts

@@ -0,0 +1,7 @@
+export type TStatusBadgeTone =
+  | 'neutral'
+  | 'info'
+  | 'accent'
+  | 'success'
+  | 'warning'
+  | 'danger'

package/template/src/components/layout/AppHeader/AppHeader.tsx

@@ -0,0 +1,57 @@
+import { useEffect, useState } from 'react'
+import { cn } from '@/lib/utils'
+import { Separator } from '@/components/ui/separator'
+import { SidebarTrigger, useSidebar } from '@/components/ui/sidebar'
+import { HeaderSearch } from './HeaderSearch'
+import { HeaderUserMenu } from './HeaderUserMenu'
+import { ThemeMenu } from './ThemeControls'
+
+export function AppHeader() {
+  const { state: strSidebarState } = useSidebar()
+  const [bHasScrolled, fnSetHasScrolled] = useState(false)
+  const bShowSidebarTrigger = strSidebarState === 'expanded'
+
+  useEffect(() => {
+    function fnOnScroll(objEvent: Event) {
+      const objTarget = objEvent.target
+      if (objTarget === document) {
+        fnSetHasScrolled(
+          document.body.scrollTop > 0 || document.documentElement.scrollTop > 0
+        )
+        return
+      }
+      if (
+        objTarget instanceof HTMLElement &&
+        objTarget.matches('main, [data-slot="sidebar-inset"]')
+      ) {
+        fnSetHasScrolled(objTarget.scrollTop > 0)
+      }
+    }
+    document.addEventListener('scroll', fnOnScroll, {
+      capture: true,
+      passive: true,
+    })
+    return () => document.removeEventListener('scroll', fnOnScroll, true)
+  }, [])
+
+  return (
+    <header
+      className={cn(
+        'header-fixed peer/header sticky top-0 z-50 h-16 w-[inherit] shrink-0 border-b border-border/40 bg-background/70 backdrop-blur-lg transition-shadow supports-[backdrop-filter]:bg-background/55',
+        bHasScrolled ? 'shadow-sm' : 'shadow-none'
+      )}
+    >
+      <div className='relative flex h-full items-center gap-3 p-4 sm:gap-4'>
+        {bShowSidebarTrigger && (
+          <>
+            <SidebarTrigger variant='outline' />
+            <Separator orientation='vertical' className='h-6' />
+          </>
+        )}
+        <HeaderSearch />
+        <ThemeMenu />
+        <HeaderUserMenu />
+      </div>
+    </header>
+  )
+}

package/template/src/components/layout/AppHeader/HeaderSearch.tsx

@@ -0,0 +1,160 @@
+import { useCallback, useEffect, useMemo, useState } from 'react'
+import { useNavigate, useRouter } from '@tanstack/react-router'
+import { useLocale, useLocaleMessages } from '@/locale'
+import { objRouteMessages } from '@/router/messages'
+import { fnCreateNavigationCatalog } from '@/router/navigation'
+import { ArrowRight, Search } from 'lucide-react'
+import { useTheme } from '@/context/ThemeProvider'
+import { Button } from '@/components/ui/button'
+import {
+  CommandDialog,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+  CommandSeparator,
+} from '@/components/ui/command'
+import { arrThemeOptions } from './themeOptions'
+
+type TSearchRoute = {
+  strId: string
+  strTitle: string
+  strTo: string
+  nOrder: number
+}
+
+type TSearchGroup = {
+  strTitle: string
+  nOrder: number
+  arrRoutes: TSearchRoute[]
+}
+
+export function HeaderSearch() {
+  const objRouter = useRouter()
+  const fnNavigate = useNavigate()
+  const { fnSetTheme } = useTheme()
+  const { fnCompare, fnTranslateShared } = useLocale()
+  const { fnTranslate: fnTranslateRoute } = useLocaleMessages(objRouteMessages)
+  const [bOpen, fnSetOpen] = useState(false)
+  const fnHasPermission = objRouter.options.context.objAuth.fnHasPermission
+  const arrSearchGroups = useMemo(
+    (): TSearchGroup[] =>
+      fnCreateNavigationCatalog(
+        objRouter,
+        fnHasPermission,
+        fnCompare,
+        fnTranslateRoute
+      ).map((objGroup) => ({
+        arrRoutes: objGroup.arrEntries.flatMap((objEntry) =>
+          (objEntry.arrChildren.length > 0
+            ? objEntry.arrChildren
+            : [objEntry]
+          ).map((objTargetEntry) => ({
+            nOrder: objTargetEntry.nOrder,
+            strId: objTargetEntry.objRoute.id,
+            strTitle: objTargetEntry.strTitle,
+            strTo: objTargetEntry.objRoute.to,
+          }))
+        ),
+        nOrder: objGroup.nOrder,
+        strTitle: objGroup.strTitle,
+      })),
+    [fnCompare, fnHasPermission, fnTranslateRoute, objRouter]
+  )
+  const fnRunCommand = useCallback((fnCommand: () => void) => {
+    fnSetOpen(false)
+    fnCommand()
+  }, [])
+
+  useEffect(() => {
+    function fnHandleShortcut(objEvent: KeyboardEvent) {
+      if (
+        (objEvent.metaKey || objEvent.ctrlKey) &&
+        objEvent.key.toLowerCase() === 'k'
+      ) {
+        objEvent.preventDefault()
+        fnSetOpen((bCurrentOpen) => !bCurrentOpen)
+      }
+    }
+    document.addEventListener('keydown', fnHandleShortcut)
+    return () => document.removeEventListener('keydown', fnHandleShortcut)
+  }, [])
+
+  return (
+    <>
+      <Button
+        type='button'
+        variant='outline'
+        aria-label={fnTranslateShared('header.search.ariaLabel')}
+        aria-haspopup='dialog'
+        aria-expanded={bOpen}
+        aria-keyshortcuts='Meta+K Control+K'
+        className='group relative me-auto h-8 w-full flex-1 justify-start rounded-md bg-muted/25 text-sm font-normal text-muted-foreground shadow-none hover:bg-accent sm:w-40 sm:pe-12 md:flex-none lg:w-52 xl:w-64'
+        onClick={() => fnSetOpen(true)}
+      >
+        <Search
+          aria-hidden='true'
+          className='absolute inset-s-1.5 top-1/2 size-4 -translate-y-1/2'
+        />
+        <span className='ms-4'>
+          {fnTranslateShared('header.search.shortLabel')}
+        </span>
+        <kbd className='pointer-events-none absolute inset-e-[0.3rem] top-[0.3rem] hidden h-5 items-center gap-1 rounded border bg-muted px-1.5 font-mono text-[10px] font-medium opacity-100 select-none group-hover:bg-accent sm:flex'>
+          <span className='text-xs'>⌘</span>K
+        </kbd>
+      </Button>
+      <CommandDialog
+        modal
+        open={bOpen}
+        onOpenChange={fnSetOpen}
+        title={fnTranslateShared('header.search.title')}
+        description={fnTranslateShared('header.search.description')}
+      >
+        <CommandInput
+          placeholder={fnTranslateShared('header.search.placeholder')}
+          aria-label={fnTranslateShared('header.search.inputAriaLabel')}
+        />
+        <CommandList>
+          <CommandEmpty>
+            {fnTranslateShared('header.search.empty')}
+          </CommandEmpty>
+          {arrSearchGroups.map((objGroup) => (
+            <CommandGroup key={objGroup.strTitle} heading={objGroup.strTitle}>
+              {objGroup.arrRoutes.map((objRoute) => (
+                <CommandItem
+                  key={objRoute.strId}
+                  value={`${objGroup.strTitle} ${objRoute.strTitle}`}
+                  onSelect={() =>
+                    fnRunCommand(() => fnNavigate({ to: objRoute.strTo }))
+                  }
+                >
+                  <span className='flex size-4 items-center justify-center'>
+                    <ArrowRight className='size-2 text-muted-foreground/80' />
+                  </span>
+                  {objRoute.strTitle}
+                </CommandItem>
+              ))}
+            </CommandGroup>
+          ))}
+          <CommandSeparator />
+          <CommandGroup heading={fnTranslateShared('header.search.themeGroup')}>
+            {arrThemeOptions.map(({ strMessageKey, strValue, Icon }) => {
+              const strLabel = fnTranslateShared(strMessageKey)
+              return (
+                <CommandItem
+                  key={strValue}
+                  value={`${fnTranslateShared('header.search.themeValuePrefix')} ${strLabel}`}
+                  onSelect={() => fnRunCommand(() => fnSetTheme(strValue))}
+                >
+                  <Icon />
+                  <span>{strLabel}</span>
+                </CommandItem>
+              )
+            })}
+          </CommandGroup>
+        </CommandList>
+      </CommandDialog>
+    </>
+  )
+}

package/template/src/components/layout/AppHeader/HeaderUserMenu.tsx

@@ -0,0 +1,59 @@
+import { useLocale } from '@/locale'
+import { LogOut } from 'lucide-react'
+import { fnSignOutAuthSession } from '@/api/authSession'
+import { useAuthStore } from '@/stores/authStore'
+import { Avatar, AvatarFallback } from '@/components/ui/avatar'
+import { Button } from '@/components/ui/button'
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu'
+
+export function HeaderUserMenu() {
+  const { fnTranslateShared } = useLocale()
+  const objUser = useAuthStore((objState) => objState.objUser)
+  const strDisplayName =
+    objUser?.strDisplayName ?? fnTranslateShared('header.user')
+  const strAccount = objUser?.strAccount ?? 'admin'
+
+  return (
+    <DropdownMenu modal={false}>
+      <DropdownMenuTrigger asChild>
+        <Button
+          type='button'
+          variant='ghost'
+          className='relative h-8 w-8 rounded-full p-0'
+          aria-label={fnTranslateShared('header.userMenu')}
+        >
+          <Avatar className='h-8 w-8'>
+            <AvatarFallback className='bg-muted font-medium text-foreground'>
+              {strDisplayName.slice(0, 1)}
+            </AvatarFallback>
+          </Avatar>
+        </Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align='end' className='w-52'>
+        <DropdownMenuLabel>
+          <div className='flex flex-col gap-1'>
+            <span>{strDisplayName}</span>
+            <span className='text-xs font-normal text-muted-foreground'>
+              {strAccount}
+            </span>
+          </div>
+        </DropdownMenuLabel>
+        <DropdownMenuSeparator />
+        <DropdownMenuItem
+          variant='destructive'
+          onSelect={() => void fnSignOutAuthSession()}
+        >
+          <LogOut />
+          {fnTranslateShared('header.signOut')}
+        </DropdownMenuItem>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}

package/template/src/components/layout/AppHeader/ThemeControls.tsx

@@ -0,0 +1,44 @@
+import { useLocale } from '@/locale'
+import { Check, Moon, Sun } from 'lucide-react'
+import { useTheme } from '@/context/ThemeProvider'
+import { Button } from '@/components/ui/button'
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu'
+import { arrThemeOptions } from './themeOptions'
+
+export function ThemeMenu() {
+  const { strTheme, fnSetTheme } = useTheme()
+  const { fnTranslateShared } = useLocale()
+  return (
+    <DropdownMenu modal={false}>
+      <DropdownMenuTrigger asChild>
+        <Button
+          type='button'
+          variant='ghost'
+          size='icon'
+          aria-label={fnTranslateShared('header.switchTheme')}
+          className='scale-95 rounded-full'
+        >
+          <Sun className='size-[1.2rem] scale-100 rotate-0 transition-all dark:scale-0 dark:-rotate-90' />
+          <Moon className='absolute size-[1.2rem] scale-0 rotate-90 transition-all dark:scale-100 dark:rotate-0' />
+        </Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align='end' className='w-36'>
+        {arrThemeOptions.map(({ strMessageKey, strValue, Icon }) => (
+          <DropdownMenuItem
+            key={strValue}
+            onSelect={() => fnSetTheme(strValue)}
+          >
+            <Icon />
+            {fnTranslateShared(strMessageKey)}
+            {strTheme === strValue && <Check className='ml-auto' />}
+          </DropdownMenuItem>
+        ))}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}

package/template/src/components/layout/AppHeader/index.ts

@@ -0,0 +1 @@
+export { AppHeader } from './AppHeader'

package/template/src/components/layout/AppHeader/themeOptions.ts

@@ -0,0 +1,13 @@
+import type { TSharedMessageKey } from '@/locale'
+import { Laptop, Moon, Sun } from 'lucide-react'
+import type { TTheme } from '@/context/ThemeProvider'
+
+export const arrThemeOptions: Array<{
+  strMessageKey: TSharedMessageKey
+  strValue: TTheme
+  Icon: typeof Sun
+}> = [
+  { strMessageKey: 'header.theme.light', strValue: 'light', Icon: Sun },
+  { strMessageKey: 'header.theme.dark', strValue: 'dark', Icon: Moon },
+  { strMessageKey: 'header.theme.system', strValue: 'system', Icon: Laptop },
+]