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

package/template/src/components/AppTable/toolbar/TableToolbar.tsx

@@ -0,0 +1,336 @@
+import {
+  ChevronDown,
+  Download,
+  Loader2,
+  Plus,
+  RefreshCw,
+  Save,
+  SlidersHorizontal,
+  X,
+} from 'lucide-react'
+import { cn } from '@/lib/utils'
+import { Button } from '@/components/ui/button'
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu'
+import type { TableColumn } from '@/components/AppTable/engine/columns/column'
+import type { TableDensity } from '@/components/AppTable/engine/shared/theme'
+import type { TableRow } from '@/components/AppTable/engine/shared/types'
+import type { TableExportAction } from '@/components/AppTable/engine/summary/config/types'
+import type { TableController } from '@/components/AppTable/engine/table/controller/TableController'
+import type { TableSnapshot } from '@/components/AppTable/engine/table/controller/types'
+import { TableColumnEditor } from '../columns'
+import type { ResolvedTableComponentProps } from '../config'
+import { useAppTableMessages } from '../messages'
+
+interface ITableToolbarProps<T extends TableRow> {
+  objProps: ResolvedTableComponentProps<T>
+  objController: TableController<T>
+  objSnapshot: TableSnapshot<T>
+  arrSelectedRows: T[]
+  strDensity: TableDensity
+  arrColumns: TableColumn<T>[]
+  nFrozenRows: number
+  bDensityControlEnabled: boolean
+  fnOnSave: () => void
+  fnOnDensityChange: (strDensity: TableDensity) => void
+  fnOnRefresh: () => void
+  fnOnColumnsChange: (arrColumns: TableColumn<T>[]) => void
+  fnOnResetColumns: () => void
+  fnOnFrozenRowsChange: (nCount: number) => void
+  fnReportError: (objError: unknown) => void
+  bHasSelection: boolean
+  bCanSelectAllMatching: boolean
+  bSelectingAllMatching: boolean
+  strSelectionLabel: string
+  arrExportActions: readonly TableExportAction[]
+  fnOnClearSelection: () => void
+  fnOnSelectAllMatching: () => void
+  fnOnExportAction: (objAction: TableExportAction) => void
+}
+
+export function TableToolbar<T extends TableRow>({
+  objProps,
+  objController,
+  objSnapshot,
+  arrSelectedRows,
+  strDensity,
+  arrColumns,
+  nFrozenRows,
+  bDensityControlEnabled,
+  fnOnSave,
+  fnOnDensityChange,
+  fnOnRefresh,
+  fnOnColumnsChange,
+  fnOnResetColumns,
+  fnOnFrozenRowsChange,
+  fnReportError,
+  bHasSelection,
+  bCanSelectAllMatching,
+  bSelectingAllMatching,
+  strSelectionLabel,
+  arrExportActions,
+  fnOnClearSelection,
+  fnOnSelectAllMatching,
+  fnOnExportAction,
+}: ITableToolbarProps<T>) {
+  const objMessages = useAppTableMessages()
+  const arrDensityOptions = [
+    { value: 'compact', label: objMessages.strDensityCompact },
+    { value: 'default', label: objMessages.strDensityDefault },
+    { value: 'comfortable', label: objMessages.strDensityComfortable },
+  ] satisfies readonly { value: TableDensity; label: string }[]
+  const objSelection = objController.getSelection()
+  const arrVisibleButtons = objProps.buttons.filter((objButton) =>
+    typeof objButton.hidden === 'function'
+      ? !objButton.hidden(arrSelectedRows, objSelection)
+      : !objButton.hidden
+  )
+  const strDensityLabel =
+    arrDensityOptions.find((objOption) => objOption.value === strDensity)
+      ?.label ?? strDensity
+  const bHasContent =
+    arrVisibleButtons.length > 0 ||
+    objSnapshot.isDirty ||
+    objProps.showColumnEditor ||
+    objProps.showDensityControl ||
+    Boolean(objProps.query) ||
+    bHasSelection ||
+    arrExportActions.length > 0
+
+  if (!bHasContent) return null
+
+  return (
+    <div
+      data-slot='table-toolbar'
+      className='flex min-h-[46px] shrink-0 flex-wrap items-center justify-between gap-3 bg-background px-2.5 py-1.5'
+    >
+      <div className='flex flex-wrap items-center gap-2'>
+        {arrVisibleButtons.map((objButton) => {
+          const bDisabled =
+            typeof objButton.disabled === 'function'
+              ? objButton.disabled(arrSelectedRows, objSelection)
+              : objButton.disabled
+          if (objButton.dropdown?.length) {
+            return (
+              <DropdownMenu key={objButton.key}>
+                <DropdownMenuTrigger asChild>
+                  <Button
+                    type='button'
+                    variant={
+                      objButton.type === 'danger'
+                        ? 'destructive'
+                        : objButton.type === 'primary'
+                          ? 'default'
+                          : 'outline'
+                    }
+                    disabled={bDisabled || objButton.loading}
+                  >
+                    {objButton.loading ? (
+                      <Loader2 className='animate-spin' />
+                    ) : objButton.icon === 'ri:add-line' ? (
+                      <Plus />
+                    ) : null}
+                    {objButton.label}
+                    <ChevronDown />
+                  </Button>
+                </DropdownMenuTrigger>
+                <DropdownMenuContent align='start'>
+                  {objButton.dropdown.map((objItem) => {
+                    const bItemDisabled =
+                      typeof objItem.disabled === 'function'
+                        ? objItem.disabled(arrSelectedRows, objSelection)
+                        : objItem.disabled
+                    return (
+                      <DropdownMenuItem
+                        key={objItem.key ?? objItem.label}
+                        disabled={bItemDisabled}
+                        onSelect={() => {
+                          Promise.resolve(
+                            objItem.onClick(arrSelectedRows, objSelection)
+                          ).catch(fnReportError)
+                        }}
+                      >
+                        {objItem.label}
+                      </DropdownMenuItem>
+                    )
+                  })}
+                </DropdownMenuContent>
+              </DropdownMenu>
+            )
+          }
+          return (
+            <Button
+              key={objButton.key}
+              type='button'
+              variant={
+                objButton.type === 'danger'
+                  ? 'destructive'
+                  : objButton.type === 'primary'
+                    ? 'default'
+                    : 'outline'
+              }
+              disabled={bDisabled || objButton.loading}
+              onClick={() => {
+                if ('onClick' in objButton && objButton.onClick) {
+                  Promise.resolve(
+                    objButton.onClick(arrSelectedRows, objSelection)
+                  ).catch(fnReportError)
+                }
+              }}
+            >
+              {objButton.loading ? (
+                <Loader2 className='animate-spin' />
+              ) : objButton.icon === 'ri:add-line' ? (
+                <Plus />
+              ) : null}
+              {objButton.label}
+            </Button>
+          )
+        })}
+        {objSnapshot.isDirty ? (
+          <>
+            <Button
+              type='button'
+              disabled={objSnapshot.saving || objSnapshot.validating}
+              onClick={fnOnSave}
+            >
+              {objSnapshot.saving ? (
+                <Loader2 className='animate-spin' />
+              ) : (
+                <Save />
+              )}
+              {objMessages.fnSaveChanges(objSnapshot.dirtyCount)}
+            </Button>
+            <Button
+              type='button'
+              variant='outline'
+              disabled={objSnapshot.saving}
+              onClick={() => objController.discardChanges()}
+            >
+              <X />
+              {objMessages.strDiscardChanges}
+            </Button>
+          </>
+        ) : null}
+      </div>
+      <div className='flex items-center gap-1'>
+        {bHasSelection ? (
+          <div className='flex items-center gap-1 text-sm text-muted-foreground'>
+            <span className='px-1'>{strSelectionLabel}</span>
+            {bCanSelectAllMatching ? (
+              <Button
+                type='button'
+                variant='ghost'
+                size='sm'
+                disabled={bSelectingAllMatching}
+                onClick={fnOnSelectAllMatching}
+              >
+                {bSelectingAllMatching ? (
+                  <Loader2 className='animate-spin' />
+                ) : null}
+                {objMessages.strSelectAllMatching}
+              </Button>
+            ) : null}
+            <Button
+              type='button'
+              variant='ghost'
+              size='sm'
+              onClick={fnOnClearSelection}
+            >
+              {objMessages.strClearSelection}
+            </Button>
+          </div>
+        ) : null}
+        {arrExportActions.length ? (
+          <DropdownMenu>
+            <DropdownMenuTrigger asChild>
+              <Button
+                type='button'
+                variant='ghost'
+                size='sm'
+                disabled={objSnapshot.exporting}
+              >
+                {objSnapshot.exporting ? (
+                  <Loader2 className='animate-spin' />
+                ) : (
+                  <Download />
+                )}
+                {objMessages.strExport}
+                <ChevronDown />
+              </Button>
+            </DropdownMenuTrigger>
+            <DropdownMenuContent align='end'>
+              {arrExportActions.map((objAction) => (
+                <DropdownMenuItem
+                  key={objAction.key}
+                  disabled={objAction.disabled}
+                  onSelect={() => fnOnExportAction(objAction)}
+                >
+                  {objAction.label}
+                </DropdownMenuItem>
+              ))}
+            </DropdownMenuContent>
+          </DropdownMenu>
+        ) : null}
+        {objProps.showColumnEditor ? (
+          <TableColumnEditor
+            arrColumns={arrColumns}
+            nFrozenRows={nFrozenRows}
+            nRowCount={objSnapshot.rows.length}
+            fnOnColumnsChange={fnOnColumnsChange}
+            fnOnResetColumns={fnOnResetColumns}
+            fnOnFrozenRowsChange={fnOnFrozenRowsChange}
+          />
+        ) : null}
+        {objProps.showDensityControl ? (
+          <DropdownMenu>
+            <DropdownMenuTrigger asChild>
+              <Button
+                type='button'
+                variant='ghost'
+                size='sm'
+                aria-label={objMessages.fnDensityAriaLabel(strDensityLabel)}
+                disabled={!bDensityControlEnabled}
+              >
+                <SlidersHorizontal />
+                {objMessages.strDensity} · {strDensityLabel}
+                <ChevronDown />
+              </Button>
+            </DropdownMenuTrigger>
+            <DropdownMenuContent align='end'>
+              <DropdownMenuRadioGroup value={strDensity}>
+                {arrDensityOptions.map((objOption) => (
+                  <DropdownMenuRadioItem
+                    key={objOption.value}
+                    value={objOption.value}
+                    onSelect={() => fnOnDensityChange(objOption.value)}
+                  >
+                    {objOption.label}
+                  </DropdownMenuRadioItem>
+                ))}
+              </DropdownMenuRadioGroup>
+            </DropdownMenuContent>
+          </DropdownMenu>
+        ) : null}
+        {objProps.query ? (
+          <Button
+            type='button'
+            variant='ghost'
+            size='icon-sm'
+            aria-label={objMessages.strRefreshAriaLabel}
+            disabled={objSnapshot.loading}
+            onClick={fnOnRefresh}
+          >
+            <RefreshCw className={cn(objSnapshot.loading && 'animate-spin')} />
+          </Button>
+        ) : null}
+      </div>
+    </div>
+  )
+}

package/template/src/components/AppTable/toolbar/index.ts

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

package/template/src/components/BrandLogo/BrandLogo.tsx

@@ -0,0 +1,41 @@
+import { useState } from 'react'
+import { objAppConfig } from '@/config/appConfig'
+import { cn } from '@/lib/utils'
+import { useTheme } from '@/context/ThemeProvider'
+
+/** 根据已解析主题选择白标 Logo；资产失败时回退为品牌首字符。 */
+export function BrandLogo({ strClassName }: { strClassName?: string }) {
+  const { bIsDarkTheme } = useTheme()
+  const [strFailedUrl, fnSetFailedUrl] = useState<string | null>(null)
+  const strLogoUrl = bIsDarkTheme
+    ? objAppConfig.brand.strDarkLogoUrl
+    : objAppConfig.brand.strLogoUrl
+  const bHasFailed = strFailedUrl === strLogoUrl
+
+  if (bHasFailed) {
+    return (
+      <span
+        aria-hidden='true'
+        data-slot='brand-logo-fallback'
+        className={cn(
+          'inline-flex items-center justify-center bg-primary/10 font-semibold text-primary',
+          strClassName
+        )}
+      >
+        {objAppConfig.brand.strName.trim().charAt(0).toLocaleUpperCase()}
+      </span>
+    )
+  }
+
+  return (
+    <img
+      src={strLogoUrl}
+      alt=''
+      aria-hidden='true'
+      draggable={false}
+      data-slot='brand-logo'
+      className={strClassName}
+      onError={() => fnSetFailedUrl(strLogoUrl)}
+    />
+  )
+}

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

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

package/template/src/components/Can/Can.tsx

@@ -0,0 +1,19 @@
+import { usePermission } from '@/permissions'
+import type { TCanProps } from './types'
+
+/** 以认证会话为唯一权限源，统一控制操作的隐藏或禁用状态。 */
+export function Can(objProps: TCanProps) {
+  const bIsAllowed = usePermission(
+    objProps.objRequirement,
+    objProps.strMatchMode
+  )
+
+  if (objProps.strDeniedBehavior === 'disable') {
+    return objProps.children({
+      bIsAllowed,
+      bIsDisabled: !bIsAllowed,
+    })
+  }
+
+  return bIsAllowed ? objProps.children : objProps.objFallback
+}

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

@@ -0,0 +1,7 @@
+export { Can } from './Can'
+export type {
+  ICanDisableProps,
+  ICanHideProps,
+  ICanRenderState,
+  TCanProps,
+} from './types'

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

@@ -0,0 +1,41 @@
+import type { ReactNode } from 'react'
+import type {
+  TPermissionMatchMode,
+  TPermissionRequirement,
+} from '@/permissions'
+
+/** `Can` 禁用模式传给业务组件的权限状态。 */
+export interface ICanRenderState {
+  /** 当前用户是否满足权限要求。 */
+  bIsAllowed: boolean
+  /** 当前交互是否应被禁用；与 `bIsAllowed` 互为相反值。 */
+  bIsDisabled: boolean
+}
+
+interface ICanBaseProps {
+  /** 当前操作要求的一个或多个稳定权限码。 */
+  objRequirement?: TPermissionRequirement
+  /** 多个权限码是全部满足还是满足任意一个，默认 `all`。 */
+  strMatchMode?: TPermissionMatchMode
+}
+
+/** 无权限时隐藏内容的属性；这是 `Can` 的默认行为。 */
+export interface ICanHideProps extends ICanBaseProps {
+  /** 无权限时隐藏内容。 */
+  strDeniedBehavior?: 'hide'
+  /** 有权限时展示的内容。 */
+  children: ReactNode
+  /** 无权限时替代原内容的安全占位。 */
+  objFallback?: ReactNode
+}
+
+/** 无权限时由调用方显式渲染禁用态的属性。 */
+export interface ICanDisableProps extends ICanBaseProps {
+  /** 无权限时保留内容并禁用交互。 */
+  strDeniedBehavior: 'disable'
+  /** 根据权限状态渲染真实交互元素，并将 `bIsDisabled` 传给其 `disabled`。 */
+  children: (objState: ICanRenderState) => ReactNode
+}
+
+/** `Can` 支持隐藏和显式禁用两种拒绝策略。 */
+export type TCanProps = ICanHideProps | ICanDisableProps

package/template/src/components/EnumBadge/EnumBadge.tsx

@@ -0,0 +1,44 @@
+import { useEnum } from '@/api/enums'
+import { StatusBadge, type TStatusBadgeTone } from '@/components/StatusBadge'
+import type { IEnumBadgeProps } from './types'
+
+const arrEnumBadgeTones: readonly TStatusBadgeTone[] = [
+  'neutral',
+  'info',
+  'accent',
+  'success',
+  'warning',
+  'danger',
+]
+
+function fnIsEnumBadgeTone(strColor: string): strColor is TStatusBadgeTone {
+  return arrEnumBadgeTones.some((strTone) => strTone === strColor)
+}
+
+function fnReadEnumBadgeTone(strColor: string | undefined) {
+  return strColor && fnIsEnumBadgeTone(strColor) ? strColor : undefined
+}
+
+/** 使用全局枚举文本和受控语义色调渲染状态 Badge。 */
+export function EnumBadge({
+  objValue,
+  strClassName,
+  strEnumKey,
+  strLoadingText = '-',
+  strTone,
+}: IEnumBadgeProps) {
+  const objEnum = useEnum(strEnumKey)
+  const objOption = objEnum.fnGetOption(objValue)
+  const strLabel = objEnum.bIsLoading
+    ? strLoadingText
+    : objEnum.fnGetLabel(objValue)
+
+  return (
+    <StatusBadge
+      strClassName={strClassName}
+      strLabel={strLabel}
+      strStatus={String(objValue ?? 'unknown')}
+      strTone={strTone ?? fnReadEnumBadgeTone(objOption?.color)}
+    />
+  )
+}

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

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

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

@@ -0,0 +1,16 @@
+import type { TEnumValue } from '@/api/enums'
+import type { TStatusBadgeTone } from '@/components/StatusBadge'
+
+/** 使用全局枚举渲染状态 Badge 的公共参数。 */
+export interface IEnumBadgeProps {
+  /** 当前值；空值统一显示为短横线。 */
+  objValue: TEnumValue | null | undefined
+  /** 可选样式类名。 */
+  strClassName?: string
+  /** 后端定义的稳定枚举 Key。 */
+  strEnumKey: string
+  /** 首次目录加载期间的占位文本，默认短横线。 */
+  strLoadingText?: string
+  /** 显式语义色调，优先级高于枚举选项的安全色调。 */
+  strTone?: TStatusBadgeTone
+}

package/template/src/components/EnumText/EnumText.tsx

@@ -0,0 +1,33 @@
+import { useEnum } from '@/api/enums'
+import type { IEnumTextProps } from './types'
+
+/** 使用全局枚举统一处理加载、缺失和未知值回退的文本组件。 */
+export function EnumText({
+  objValue,
+  strClassName,
+  strEnumKey,
+  strLoadingText = '-',
+}: IEnumTextProps) {
+  const objEnum = useEnum(strEnumKey)
+  const strState = objEnum.bIsLoading
+    ? 'loading'
+    : objEnum.bIsError
+      ? 'error'
+      : objEnum.bIsMissing
+        ? 'missing'
+        : 'ready'
+  const strLabel = objEnum.bIsLoading
+    ? strLoadingText
+    : objEnum.fnGetLabel(objValue)
+
+  return (
+    <span
+      aria-busy={objEnum.bIsLoading}
+      className={strClassName}
+      data-enum-key={strEnumKey}
+      data-state={strState}
+    >
+      {strLabel}
+    </span>
+  )
+}

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

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

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

@@ -0,0 +1,13 @@
+import type { TEnumValue } from '@/api/enums'
+
+/** 使用全局枚举渲染文本的公共参数。 */
+export interface IEnumTextProps {
+  /** 当前值；空值统一显示为短横线。 */
+  objValue: TEnumValue | null | undefined
+  /** 可选样式类名。 */
+  strClassName?: string
+  /** 后端定义的稳定枚举 Key。 */
+  strEnumKey: string
+  /** 首次目录加载期间的占位文本，默认短横线。 */
+  strLoadingText?: string
+}

package/template/src/components/FilePreview/FilePreview.tsx

@@ -0,0 +1,120 @@
+import { useEffect, useState } from 'react'
+import { useLocale } from '@/locale'
+import { Loader2 } from 'lucide-react'
+import { cn } from '@/lib/utils'
+import { fnCreateFilePreview } from './preview'
+import type { IFilePreviewProps, TFilePreviewViewState } from './types'
+
+/** 图片/PDF 内建、Office 等格式可注入适配器的文件预览组件。 */
+export function FilePreview({
+  arrAdapters,
+  arrAllowedOrigins,
+  objBlob,
+  strAlt,
+  strClassName,
+  strFileName,
+  strMimeType,
+  strTitle,
+}: IFilePreviewProps) {
+  const { fnTranslateShared } = useLocale()
+  const [objState, fnSetState] = useState<TFilePreviewViewState>({
+    strStatus: 'loading',
+  })
+
+  useEffect(() => {
+    const objController = new AbortController()
+    let objResource: Awaited<ReturnType<typeof fnCreateFilePreview>> | null =
+      null
+
+    async function fnLoadPreview() {
+      try {
+        const objNextResource = await fnCreateFilePreview({
+          arrAdapters,
+          arrAllowedOrigins,
+          objBlob,
+          objSignal: objController.signal,
+          strFileName,
+          strMimeType,
+        })
+        if (objController.signal.aborted) {
+          objNextResource.fnDispose?.()
+          return
+        }
+        objResource = objNextResource
+        fnSetState({
+          objResource: objNextResource,
+          objSourceBlob: objBlob,
+          strStatus: 'ready',
+        })
+      } catch (objCaughtError) {
+        if (objController.signal.aborted) return
+        fnSetState({
+          objError:
+            objCaughtError instanceof Error
+              ? objCaughtError
+              : new Error(fnTranslateShared('filePreview.error')),
+          objSourceBlob: objBlob,
+          strStatus: 'error',
+        })
+      }
+    }
+
+    void fnLoadPreview()
+
+    return () => {
+      objController.abort()
+      objResource?.fnDispose?.()
+    }
+  }, [
+    arrAdapters,
+    arrAllowedOrigins,
+    fnTranslateShared,
+    objBlob,
+    strFileName,
+    strMimeType,
+  ])
+
+  if (objState.strStatus === 'loading' || objState.objSourceBlob !== objBlob) {
+    return (
+      <div
+        aria-busy='true'
+        className={cn('flex items-center gap-2 p-4 text-sm', strClassName)}
+      >
+        <Loader2 className='size-4 animate-spin' />
+        {fnTranslateShared('filePreview.loading')}
+      </div>
+    )
+  }
+  if (objState.strStatus === 'error') {
+    return (
+      <p
+        className={cn('p-4 text-sm text-destructive', strClassName)}
+        role='alert'
+      >
+        {objState.objError.message}
+      </p>
+    )
+  }
+  if (objState.objResource.strKind === 'image') {
+    return (
+      <img
+        alt={strAlt ?? strFileName}
+        className={cn('max-h-full max-w-full object-contain', strClassName)}
+        src={objState.objResource.strUrl}
+      />
+    )
+  }
+
+  return (
+    <iframe
+      className={cn('min-h-96 w-full border-0', strClassName)}
+      referrerPolicy='no-referrer'
+      sandbox='allow-downloads'
+      src={objState.objResource.strUrl}
+      title={
+        strTitle ??
+        `${strFileName} ${fnTranslateShared('filePreview.titleSuffix')}`
+      }
+    />
+  )
+}