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

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

@@ -0,0 +1,11 @@
+export { FilePreview } from './FilePreview'
+export { fnCreateFilePreview } from './preview'
+export type {
+  ICreateFilePreviewOptions,
+  IFilePreviewAdapter,
+  IFilePreviewAdapterContext,
+  IFilePreviewInput,
+  IFilePreviewProps,
+  IFilePreviewResource,
+  TFilePreviewKind,
+} from './types'

package/template/src/components/FilePreview/preview.ts

@@ -0,0 +1,88 @@
+import { FileCapabilityError } from '@/files'
+import type { ICreateFilePreviewOptions, IFilePreviewResource } from './types'
+
+const arrSafeImageMimeTypes: readonly string[] = [
+  'image/avif',
+  'image/gif',
+  'image/jpeg',
+  'image/png',
+  'image/webp',
+]
+const objSafeImageMimeTypes = new Set<string>(arrSafeImageMimeTypes)
+
+function fnResolvePreviewMimeType(objOptions: ICreateFilePreviewOptions) {
+  return (objOptions.strMimeType || objOptions.objBlob.type).toLowerCase()
+}
+
+function fnCreateObjectUrlPreview(
+  objOptions: ICreateFilePreviewOptions
+): IFilePreviewResource | null {
+  const strMimeType = fnResolvePreviewMimeType(objOptions)
+  const strKind = objSafeImageMimeTypes.has(strMimeType)
+    ? 'image'
+    : strMimeType === 'application/pdf'
+      ? 'pdf'
+      : null
+  if (!strKind) return null
+
+  const strUrl = URL.createObjectURL(objOptions.objBlob)
+  return {
+    strKind,
+    strUrl,
+    fnDispose: () => URL.revokeObjectURL(strUrl),
+  }
+}
+
+function fnAssertExternalPreviewUrl(
+  strUrl: string,
+  arrAllowedOrigins: readonly string[] | undefined
+) {
+  const objUrl = new URL(strUrl, window.location.origin)
+  const arrOrigins = arrAllowedOrigins ?? [window.location.origin]
+  const bHasSafeTransport =
+    objUrl.protocol === 'https:' ||
+    (objUrl.protocol === 'http:' && objUrl.origin === window.location.origin)
+  if (!bHasSafeTransport || !arrOrigins.includes(objUrl.origin)) {
+    throw new FileCapabilityError({
+      strCode: 'INVALID_PREVIEW_URL',
+      strMessage: '预览服务返回了不受信任的地址',
+    })
+  }
+}
+
+/**
+ * 为图片/PDF 创建本地对象 URL，其他格式按顺序委托给外部适配器。
+ *
+ * SVG 不进入内建图片白名单；Office 适配器若把文件交给第三方服务，必须由
+ * 应用明确配置允许 Origin，并在接入前完成数据合规评审。
+ */
+export async function fnCreateFilePreview(
+  objOptions: ICreateFilePreviewOptions
+) {
+  const objBuiltinResource = fnCreateObjectUrlPreview(objOptions)
+  if (objBuiltinResource) return objBuiltinResource
+
+  const objAdapter = objOptions.arrAdapters?.find((objCurrentAdapter) =>
+    objCurrentAdapter.fnCanPreview(objOptions)
+  )
+  if (!objAdapter) {
+    throw new FileCapabilityError({
+      strCode: 'UNSUPPORTED_PREVIEW_TYPE',
+      strMessage: '当前文件类型暂不支持预览',
+    })
+  }
+
+  const objResource = await objAdapter.fnCreatePreview({
+    objBlob: objOptions.objBlob,
+    objSignal: objOptions.objSignal ?? new AbortController().signal,
+    strFileName: objOptions.strFileName,
+    strMimeType: objOptions.strMimeType,
+  })
+  try {
+    fnAssertExternalPreviewUrl(objResource.strUrl, objOptions.arrAllowedOrigins)
+  } catch (objError) {
+    objResource.fnDispose?.()
+    throw objError
+  }
+  return objResource
+}

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

@@ -0,0 +1,91 @@
+/** 文件预览适配器接收的输入。 */
+export interface IFilePreviewInput {
+  /** 已获得的文件 Blob；适配器不得把敏感文件发送给未授权第三方。 */
+  objBlob: Blob
+  /** 用于展示和扩展名判断的文件名。 */
+  strFileName: string
+  /** 调用方声明的 MIME；省略时使用 Blob MIME。 */
+  strMimeType?: string
+}
+
+/** 预览资源类别。 */
+export type TFilePreviewKind = 'external' | 'image' | 'pdf'
+
+/** 可渲染的文件预览资源。 */
+export interface IFilePreviewResource {
+  /** 预览渲染方式。 */
+  strKind: TFilePreviewKind
+  /** 浏览器对象 URL、当前站点开发 HTTP URL 或通过安全校验的外部 HTTPS URL。 */
+  strUrl: string
+  /** 释放对象 URL 或适配器临时资源；调用方必须在替换和卸载时执行。 */
+  fnDispose?: () => void
+}
+
+/** Office 等外部预览实现接收的上下文。 */
+export interface IFilePreviewAdapterContext extends IFilePreviewInput {
+  /** 取消信号，适配器发起上传或换票请求时必须透传。 */
+  objSignal: AbortSignal
+}
+
+/** 可替换的外部文件预览适配器。 */
+export interface IFilePreviewAdapter {
+  /** 根据文件名和 MIME 判断是否支持，不得读取或执行文件内容。 */
+  fnCanPreview: (objInput: IFilePreviewInput) => boolean
+  /** 创建外部预览资源。 */
+  fnCreatePreview: (
+    objContext: IFilePreviewAdapterContext
+  ) => Promise<IFilePreviewResource>
+}
+
+/** 创建预览资源的配置。 */
+export interface ICreateFilePreviewOptions extends IFilePreviewInput {
+  /** Office 等外部预览适配器，按顺序选择第一个支持项。 */
+  arrAdapters?: readonly IFilePreviewAdapter[]
+  /** 外部预览允许的完整 Origin；默认仅允许当前 Origin，跨站地址还必须使用 HTTPS。 */
+  arrAllowedOrigins?: readonly string[]
+  /** 调用方提供的取消信号。 */
+  objSignal?: AbortSignal
+}
+
+/** 文件预览组件的公共参数。 */
+export interface IFilePreviewProps {
+  /** Office 等外部预览适配器，内建图片/PDF 不需要配置。 */
+  arrAdapters?: readonly IFilePreviewAdapter[]
+  /** 外部预览地址允许的完整 Origin，默认仅当前站点。 */
+  arrAllowedOrigins?: readonly string[]
+  /** 文件 Blob。 */
+  objBlob: Blob
+  /** 图片预览的替代文本，默认使用文件名。 */
+  strAlt?: string
+  /** 外层容器样式类名。 */
+  strClassName?: string
+  /** 文件名，用于展示和外部适配器判断。 */
+  strFileName: string
+  /** 文件 MIME，省略时使用 Blob MIME。 */
+  strMimeType?: string
+  /** PDF 和外部预览 iframe 的标题。 */
+  strTitle?: string
+}
+
+/** 文件预览组件内部的互斥状态。 */
+export type TFilePreviewViewState =
+  | {
+      /** 正在创建预览资源。 */
+      strStatus: 'loading'
+    }
+  | {
+      /** 当前文件预览已经可渲染。 */
+      strStatus: 'ready'
+      /** 已创建的预览资源。 */
+      objResource: IFilePreviewResource
+      /** 资源对应的 Blob，用于防止切换文件时短暂展示旧资源。 */
+      objSourceBlob: Blob
+    }
+  | {
+      /** 当前文件无法创建预览。 */
+      strStatus: 'error'
+      /** 可安全展示的预览错误。 */
+      objError: Error
+      /** 错误对应的 Blob，用于防止切换文件时展示旧错误。 */
+      objSourceBlob: Blob
+    }

package/template/src/components/FileUpload/FileUpload.tsx

@@ -0,0 +1,172 @@
+import { useEffect, useMemo, useRef } from 'react'
+import { fnCreateFileAccept, useFileUpload } from '@/files'
+import { useLocale } from '@/locale'
+import { Loader2, RotateCcw, Upload, X } from 'lucide-react'
+import { cn } from '@/lib/utils'
+import { Button } from '@/components/ui/button'
+import { Input } from '@/components/ui/input'
+import type { IFileUploadProps } from './types'
+
+/**
+ * 复用全局 Button/Input 的通用上传组件。
+ *
+ * 组件只负责交互与状态，网络调用必须由 `fnUpload` 使用生成客户端完成。
+ */
+export function FileUpload<TResult>({
+  bDisabled = false,
+  bMultiple = false,
+  fnOnError,
+  fnOnSuccess,
+  fnUpload,
+  objValidation,
+  strClassName,
+  strSelectText: strSelectTextOverride,
+  strInputAriaLabel,
+  strInputId,
+}: IFileUploadProps<TResult>) {
+  const { fnTranslateShared } = useLocale()
+  const strSelectText =
+    strSelectTextOverride ?? fnTranslateShared('fileUpload.select')
+  const objInputRef = useRef<HTMLInputElement>(null)
+  const objUploadOptions = useMemo(
+    () => ({ fnUpload, objValidation }),
+    [fnUpload, objValidation]
+  )
+  const {
+    fnCancel,
+    fnRetry,
+    fnUpload: fnStartUpload,
+    objState,
+  } = useFileUpload(objUploadOptions)
+  const objNotifiedStateRef = useRef(objState)
+  const strAccept = fnCreateFileAccept(objValidation)
+  const bIsUploading = objState.strStatus === 'uploading'
+  const arrFiles = 'arrFiles' in objState ? objState.arrFiles : []
+
+  useEffect(() => {
+    if (objNotifiedStateRef.current === objState) return
+    objNotifiedStateRef.current = objState
+    if (objState.strStatus === 'success') {
+      fnOnSuccess?.(objState.objResult)
+    } else if (objState.strStatus === 'error') {
+      fnOnError?.(objState.objError)
+    }
+  }, [fnOnError, fnOnSuccess, objState])
+
+  const fnHandleSelection = (objEvent: React.ChangeEvent<HTMLInputElement>) => {
+    const arrSelectedFiles = Array.from(objEvent.currentTarget.files ?? [])
+    objEvent.currentTarget.value = ''
+    if (arrSelectedFiles.length > 0) {
+      void fnStartUpload(arrSelectedFiles)
+    }
+  }
+
+  return (
+    <section
+      aria-busy={bIsUploading}
+      className={cn('space-y-3 rounded-md border p-4', strClassName)}
+    >
+      <Input
+        ref={objInputRef}
+        id={strInputId}
+        accept={strAccept || undefined}
+        aria-label={strInputAriaLabel ?? strSelectText}
+        className='hidden'
+        disabled={bDisabled || bIsUploading}
+        multiple={bMultiple}
+        type='file'
+        onChange={fnHandleSelection}
+      />
+      <div className='flex flex-wrap gap-2'>
+        <Button
+          type='button'
+          disabled={bDisabled || bIsUploading}
+          variant='outline'
+          onClick={() => objInputRef.current?.click()}
+        >
+          <Upload />
+          {strSelectText}
+        </Button>
+        {bIsUploading ? (
+          <Button
+            type='button'
+            disabled={bDisabled}
+            variant='outline'
+            onClick={fnCancel}
+          >
+            <X />
+            {fnTranslateShared('fileUpload.cancel')}
+          </Button>
+        ) : null}
+        {objState.strStatus === 'error' || objState.strStatus === 'canceled' ? (
+          <Button
+            type='button'
+            disabled={bDisabled || arrFiles.length === 0}
+            variant='outline'
+            onClick={() => void fnRetry()}
+          >
+            <RotateCcw />
+            {fnTranslateShared('fileUpload.retry')}
+          </Button>
+        ) : null}
+      </div>
+
+      {arrFiles.length > 0 ? (
+        <ul
+          className='space-y-1 text-sm'
+          aria-label={fnTranslateShared('fileUpload.selectedFiles')}
+        >
+          {arrFiles.map((objFile, nIndex) => (
+            <li key={`${objFile.name}-${objFile.size}-${nIndex}`}>
+              {objFile.name}
+            </li>
+          ))}
+        </ul>
+      ) : null}
+
+      {bIsUploading ? (
+        <div className='space-y-1' aria-live='polite'>
+          <div className='flex items-center gap-2 text-sm text-muted-foreground'>
+            <Loader2 className='size-4 animate-spin' />
+            {objState.objProgress.strMessage ??
+              fnTranslateShared('fileUpload.uploading')}
+          </div>
+          {objState.objProgress.nPercent !== undefined ? (
+            <progress
+              aria-label={fnTranslateShared('fileUpload.progress')}
+              className='h-2 w-full'
+              max={100}
+              value={objState.objProgress.nPercent}
+            />
+          ) : null}
+        </div>
+      ) : null}
+
+      {objState.strStatus === 'success' ? (
+        <p className='text-sm text-emerald-600' role='status'>
+          {fnTranslateShared('fileUpload.success')}
+        </p>
+      ) : null}
+      {objState.strStatus === 'canceled' ? (
+        <p className='text-sm text-muted-foreground' role='status'>
+          {fnTranslateShared('fileUpload.canceled')}
+        </p>
+      ) : null}
+      {objState.strStatus === 'error' ? (
+        <div className='space-y-1 text-sm text-destructive' role='alert'>
+          {objState.arrIssues.length > 0 ? (
+            <ul>
+              {objState.arrIssues.map((objIssue, nIndex) => (
+                <li key={`${objIssue.strCode}-${nIndex}`}>
+                  {objIssue.strMessage}
+                </li>
+              ))}
+            </ul>
+          ) : (
+            <p>{objState.objError.message}</p>
+          )}
+        </div>
+      ) : null}
+    </section>
+  )
+}

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

@@ -0,0 +1,2 @@
+export { FileUpload } from './FileUpload'
+export type { IFileUploadProps, TFileUploadStatus } from './types'

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

@@ -0,0 +1,32 @@
+import type {
+  IFileValidationOptions,
+  TFileUploadRequest,
+  TFileUploadState,
+} from '@/files'
+
+/** 开箱即用文件上传组件的公共参数。 */
+export interface IFileUploadProps<TResult> {
+  /** 是否允许一次选择多个文件，默认 false。 */
+  bMultiple?: boolean
+  /** 是否禁用选择、取消和重试操作。 */
+  bDisabled?: boolean
+  /** 由业务层使用 Swagger 生成客户端实现的上传函数。 */
+  fnUpload: TFileUploadRequest<TResult>
+  /** 上传失败或浏览器体验校验失败时触发。 */
+  fnOnError?: (objError: Error) => void
+  /** 上传完成时触发。 */
+  fnOnSuccess?: (objResult: TResult) => void
+  /** 浏览器体验校验规则，后端仍必须做最终校验。 */
+  objValidation?: IFileValidationOptions
+  /** 外层容器样式类名。 */
+  strClassName?: string
+  /** 空闲状态按钮文本。 */
+  strSelectText?: string
+  /** 原生文件输入框 ID，用于与外部表单标签建立关联。 */
+  strInputId?: string
+  /** 原生文件输入框的无障碍名称；省略时与选择按钮文案一致。 */
+  strInputAriaLabel?: string
+}
+
+/** FileUpload 向外报告的互斥状态。 */
+export type TFileUploadStatus<TResult> = TFileUploadState<TResult>

package/template/src/components/JsonEditor/JsonEditor.tsx

@@ -0,0 +1,103 @@
+import { useCallback, useState } from 'react'
+import { useLocale } from '@/locale'
+import { json, jsonParseLinter } from '@codemirror/lang-json'
+import { lintGutter, linter } from '@codemirror/lint'
+import CodeMirror from '@uiw/react-codemirror'
+import { Braces, WandSparkles } from 'lucide-react'
+import { cn } from '@/lib/utils'
+import { useTheme } from '@/context/ThemeProvider'
+import { Button } from '@/components/ui/button'
+import type { IJsonEditorProps } from './types'
+
+const arrJsonEditorExtensions = [
+  json(),
+  linter(jsonParseLinter()),
+  lintGutter(),
+]
+
+export function JsonEditor({
+  strValue,
+  fnOnChange,
+  bIsReadOnly = false,
+  strAriaLabel: strAriaLabelOverride,
+  strClassName,
+  strPlaceholder: strPlaceholderOverride,
+}: IJsonEditorProps) {
+  const { bIsDarkTheme } = useTheme()
+  const { fnTranslateShared } = useLocale()
+  const strAriaLabel =
+    strAriaLabelOverride ?? fnTranslateShared('jsonEditor.ariaLabel')
+  const strPlaceholder =
+    strPlaceholderOverride ?? fnTranslateShared('jsonEditor.placeholder')
+  const strFormatErrorText = fnTranslateShared('jsonEditor.formatError')
+  const [strFormatError, fnSetFormatError] = useState('')
+
+  const fnFormatJson = useCallback(() => {
+    try {
+      const objJsonValue = JSON.parse(strValue) as object
+      fnOnChange(JSON.stringify(objJsonValue, null, 2))
+      fnSetFormatError('')
+    } catch {
+      fnSetFormatError(strFormatErrorText)
+    }
+  }, [fnOnChange, strFormatErrorText, strValue])
+
+  return (
+    <div
+      data-slot='json-editor'
+      className={cn(
+        'flex h-full min-h-0 flex-col overflow-hidden rounded-md border bg-background focus-within:border-ring focus-within:ring-2 focus-within:ring-ring/20',
+        strClassName
+      )}
+    >
+      <div className='flex min-h-10 shrink-0 items-center justify-between gap-3 border-b bg-muted/40 px-3'>
+        <span className='flex items-center gap-2 text-xs font-medium text-muted-foreground'>
+          <Braces className='size-4' />
+          JSON
+        </span>
+        <Button
+          type='button'
+          size='sm'
+          variant='ghost'
+          disabled={bIsReadOnly || !strValue.trim()}
+          onClick={fnFormatJson}
+        >
+          <WandSparkles />
+          {fnTranslateShared('jsonEditor.format')}
+        </Button>
+      </div>
+
+      <CodeMirror
+        value={strValue}
+        height='100%'
+        theme={bIsDarkTheme ? 'dark' : 'light'}
+        extensions={arrJsonEditorExtensions}
+        placeholder={strPlaceholder}
+        readOnly={bIsReadOnly}
+        editable={!bIsReadOnly}
+        indentWithTab
+        basicSetup={{
+          lineNumbers: true,
+          foldGutter: true,
+          highlightActiveLine: true,
+          highlightActiveLineGutter: true,
+        }}
+        aria-label={strAriaLabel}
+        className='min-h-112 flex-1 overflow-hidden text-sm xl:min-h-0 [&_.cm-editor]:h-full [&_.cm-editor]:outline-none [&_.cm-scroller]:font-mono'
+        onChange={(strNextValue) => {
+          fnSetFormatError('')
+          fnOnChange(strNextValue)
+        }}
+      />
+
+      {strFormatError && (
+        <p
+          role='alert'
+          className='shrink-0 border-t px-3 py-2 text-xs text-destructive'
+        >
+          {strFormatError}
+        </p>
+      )}
+    </div>
+  )
+}

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

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

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

@@ -0,0 +1,14 @@
+export interface IJsonEditorProps {
+  /** 当前 JSON 源文本。 */
+  strValue: string
+  /** 源文本发生变化时触发。 */
+  fnOnChange: (strValue: string) => void
+  /** 是否禁止编辑和格式化。 */
+  bIsReadOnly?: boolean
+  /** 编辑器无障碍名称；省略时使用当前 Locale 的共享文案。 */
+  strAriaLabel?: string
+  /** 外层样式类名。 */
+  strClassName?: string
+  /** 空编辑器占位文案；省略时使用当前 Locale 的共享文案。 */
+  strPlaceholder?: string
+}