@nocobase/app-template-default 0.0.0-stage → 1.0.0-beta.57

package/client/extensions/nocobase-device-approval/use-device-approval.ts

@@ -0,0 +1,176 @@
+import { useAuthentication } from '@nocobase/app-plugin-authentication/client';
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+/**
+ * Where an approval stands: `checking` the code, `ready` to decide, `approving` or `denying`, decided (`approved`,
+ * `denied`), or a code that cannot be decided here: `expired`, `invalid`, `notYours` (another account claimed it), or
+ * an `error` worth retrying. `idle` means there is no code yet.
+ */
+export type DeviceApprovalStatus =
+  | 'idle'
+  | 'checking'
+  | 'ready'
+  | 'approving'
+  | 'denying'
+  | 'approved'
+  | 'denied'
+  | 'expired'
+  | 'invalid'
+  | 'notYours'
+  | 'error';
+
+export interface DeviceApprovalState {
+  readonly status: DeviceApprovalStatus;
+  /** The client that asked, such as `acme`, once the code is claimed for the signed-in person. */
+  readonly clientId?: string;
+  readonly approve: () => Promise<void>;
+  readonly deny: () => Promise<void>;
+  /** Checks the code again, after an `error`. */
+  readonly retry: () => void;
+}
+
+interface Verification {
+  readonly status?: string;
+  readonly client_id?: string;
+}
+
+interface FetchResult {
+  readonly data: unknown;
+  readonly error: unknown;
+}
+
+/** `abcd2345` as `ABCD-2345`: upper case, and an eight-character code in two groups of four. */
+export function formatUserCode(userCode: string): string {
+  const normalized = userCode.replace(/[^a-z0-9]/giu, '').toUpperCase();
+  return normalized.length === 8
+    ? `${normalized.slice(0, 4)}-${normalized.slice(4)}`
+    : normalized;
+}
+
+/** The status a failed device request means, read from Better Auth's `{ error, error_description }` body. */
+export function deviceErrorStatus(error: unknown): DeviceApprovalStatus {
+  const body =
+    typeof error === 'object' && error !== null
+      ? (error as Record<string, unknown>)
+      : {};
+  const code =
+    typeof body.error === 'string'
+      ? body.error
+      : typeof body.code === 'string'
+        ? body.code
+        : '';
+  switch (code.toLowerCase()) {
+    case 'expired_token':
+      return 'expired';
+    case 'invalid_request':
+    case 'invalid_user_code':
+      return 'invalid';
+    case 'access_denied':
+      return 'notYours';
+    default:
+      return 'error';
+  }
+}
+
+/**
+ * Drives one device authorization through Better Auth's `deviceAuthorization()` endpoints with the signed-in person's
+ * session: `GET /device` checks the code and claims it for this person, which Better Auth requires before the code can
+ * be approved or denied, then `POST /device/approve` or `/device/deny` decides it. The check runs once per code, since
+ * Better Auth rate-limits it, and never polls.
+ */
+export function useDeviceApproval(
+  userCode: string | undefined,
+): DeviceApprovalState {
+  const { client } = useAuthentication();
+  const code = userCode?.trim() ?? '';
+  const [attempt, setAttempt] = useState(0);
+  // Which check the state answers: a new code or a retry is being checked until its answer arrives.
+  const key = `${code}#${attempt}`;
+  const [state, setState] = useState<{
+    key: string;
+    status: DeviceApprovalStatus;
+    clientId?: string;
+  }>({ key: '', status: 'idle' });
+  const checkedRef = useRef<string | null>(null);
+
+  const request = useCallback(
+    (path: string, init: Record<string, unknown>): Promise<FetchResult> =>
+      client.$fetch(path, init),
+    [client],
+  );
+
+  useEffect(() => {
+    // Once per code: StrictMode runs effects twice, and the endpoint counts every call against its rate limit.
+    if (code === '' || checkedRef.current === key) return;
+    checkedRef.current = key;
+    void request('/device', {
+      method: 'GET',
+      query: { user_code: code },
+    }).then(
+      ({ data, error }) => {
+        if (checkedRef.current !== key) return;
+        if (error) {
+          setState({ key, status: deviceErrorStatus(error) });
+          return;
+        }
+        const verification = (data ?? {}) as Verification;
+        // Better Auth names the client only to the person the code is claimed for.
+        if (verification.client_id === undefined) {
+          setState({
+            key,
+            status: verification.status === 'pending' ? 'notYours' : 'invalid',
+          });
+          return;
+        }
+        setState({
+          key,
+          clientId: verification.client_id,
+          status:
+            verification.status === 'approved'
+              ? 'approved'
+              : verification.status === 'denied'
+                ? 'denied'
+                : 'ready',
+        });
+      },
+      () => {
+        if (checkedRef.current === key) setState({ key, status: 'error' });
+      },
+    );
+  }, [code, key, request]);
+
+  const decide = useCallback(
+    async (decision: 'approve' | 'deny'): Promise<void> => {
+      setState((current) => ({
+        ...current,
+        status: decision === 'approve' ? 'approving' : 'denying',
+      }));
+      try {
+        const { error } = await request(`/device/${decision}`, {
+          method: 'POST',
+          body: { userCode: code },
+        });
+        setState((current) => ({
+          ...current,
+          status: error
+            ? deviceErrorStatus(error)
+            : decision === 'approve'
+              ? 'approved'
+              : 'denied',
+        }));
+      } catch {
+        setState((current) => ({ ...current, status: 'error' }));
+      }
+    },
+    [code, request],
+  );
+
+  const current = state.key === key ? state : undefined;
+  return {
+    status: code === '' ? 'idle' : (current?.status ?? 'checking'),
+    ...(current?.clientId === undefined ? {} : { clientId: current.clientId }),
+    approve: () => decide('approve'),
+    deny: () => decide('deny'),
+    retry: () => setAttempt((value) => value + 1),
+  };
+}

package/client/extensions/nocobase-file-component-ui/README.md

@@ -0,0 +1,13 @@
+# File Component UI
+
+This Registry item installs editable App source for upload, list, thumbnail, and preview controls. The default destination is client/extensions/nocobase-file-component-ui. Import components and UI types from its index.ts.
+
+Pass the public ClientFileRepository returned by the App's clientFileRepositoryManagerToken to FileUploadField as repository. Read-only components consume FileRecord arrays and their contentUrl directly; they require no repository prop. See the Registry components section in the plugin's SKILL.md for installation, dependencies, and a complete React example.
+
+Upload success is controlled by value/onChange. Temporary progress and error items stay internal. Use onStatusChange to block form submission while uploading or after a failure. Upload cancellation forwards AbortSignal; it does not guarantee rollback after a server commit. removeOnDelete removes metadata only. App-owned business relations and physical cleanup remain the App's responsibility.
+
+Preview handles safe raster images, PDF, audio/video and text/Markdown. The content route serves attachments, so PDF is fetched and embedded as a local blob retyped to `application/pdf`; a response carrying an active markup type is reported as a preview failure rather than embedded, because a blob URL is same-origin. DOCX/XLSX/PPTX render locally with lazily loaded `@silurus/ooxml`; legacy Office and OpenDocument formats retain Office Online, which requires an internet-accessible absolute URL and cannot use the App session. Active HTML/SVG/XML and unsafe URL schemes are rejected. Markdown does not execute raw HTML.
+
+Follow the plugin Skill's Registry installation and preview sections for the exact viewer dependency, Vite dependency-prebundling exclusion, authentication adapter boundaries and acceptance checks. Same-origin content fetches use session cookies; external fetches omit credentials and require CORS. Bearer-only access requires changes to the App-owned source; setting `contentUrl` to an arbitrary blob URL is not supported. OOXML failures show an error and an optional download action; `download={false}` suppresses that action.
+
+There is no public/private record flag or access-token endpoint. The item contains no extension.ts, route, collection, or Server implementation. A private disk does not authorize a content request. Installed copies belong to the App; review upgrades with a three-way merge and preserve customizations. Supply translated labels and adapt additional copy in installed source.

package/client/extensions/nocobase-file-component-ui/components/file-list.tsx

@@ -0,0 +1,147 @@
+import { useTranslation } from '@nocobase/i18n/client';
+import { Download, Eye, Trash2 } from 'lucide-react';
+import { useState, type ReactElement } from 'react';
+
+import type { FileListProps, FileRecord } from '../types';
+import { Button } from '#components/ui/button';
+import { resolveSafeFileUrl } from '../lib/file-url';
+import { FilePreviewDialog } from './file-preview-dialog';
+import { FileThumbnail } from './file-thumbnail';
+
+function triggerDownload(url: string, filename: string): void {
+  const link = document.createElement('a');
+  link.href = url;
+  link.download = filename;
+  link.rel = 'noopener';
+  link.click();
+}
+
+export function FileList(inputProps: FileListProps): ReactElement {
+  const { t } = useTranslation('@nocobase/app-plugin-file');
+  const {
+    files,
+    onPreview,
+    onDownload,
+    onRemove,
+    onError,
+    labels,
+    emptyState,
+  } = inputProps;
+
+  const [previewIndex, setPreviewIndex] = useState(0);
+  const [previewOpen, setPreviewOpen] = useState(false);
+  const previewLabel =
+    labels?.preview ?? t('files.preview', { defaultValue: 'Preview' });
+  const downloadLabel =
+    labels?.download ?? t('files.download', { defaultValue: 'Download' });
+  const removeLabel =
+    labels?.remove ?? t('files.remove', { defaultValue: 'Remove' });
+
+  if (!files.length)
+    return (
+      <div role='status'>
+        {emptyState ??
+          labels?.empty ??
+          t('files.empty', { defaultValue: 'No files.' })}
+      </div>
+    );
+
+  const downloadFile = (file: FileRecord): void => {
+    if (onDownload) {
+      onDownload(file);
+      return;
+    }
+    void (async () => {
+      const raw = file.contentUrl;
+      const url = raw ? resolveSafeFileUrl(raw) : undefined;
+      if (!url)
+        throw new Error(
+          t('urlNotAllowed', {
+            defaultValue: 'File URL is not allowed.',
+          }),
+        );
+      triggerDownload(url, file.filename);
+    })().catch((error: unknown) => {
+      onError?.(
+        error instanceof Error
+          ? error
+          : new Error(
+              t('downloadFailed', {
+                defaultValue: 'File download failed.',
+              }),
+            ),
+      );
+    });
+  };
+
+  return (
+    <>
+      <ul data-slot='file-list' className='grid gap-3 sm:grid-cols-2'>
+        {files.map((file, index) => (
+          <li
+            key={file.id}
+            className='flex min-w-0 items-center gap-3 rounded-md border p-3'
+          >
+            <div className='h-12 w-12 shrink-0 overflow-hidden rounded-md'>
+              <FileThumbnail file={file} />
+            </div>
+            <div className='min-w-0 flex-1'>
+              <div className='truncate font-medium' title={file.filename}>
+                {file.filename}
+              </div>
+              <div className='text-sm text-muted-foreground'>
+                {file.mimeType}
+              </div>
+            </div>
+            <div className='flex shrink-0 items-center gap-1'>
+              <Button
+                type='button'
+                size='icon'
+                variant='ghost'
+                aria-label={`${previewLabel}: ${file.filename}`}
+                title={previewLabel}
+                onClick={() => {
+                  onPreview?.(file);
+                  setPreviewIndex(index);
+                  setPreviewOpen(true);
+                }}
+              >
+                <Eye aria-hidden='true' />
+              </Button>
+              <Button
+                type='button'
+                size='icon'
+                variant='ghost'
+                aria-label={`${downloadLabel}: ${file.filename}`}
+                title={downloadLabel}
+                onClick={() => downloadFile(file)}
+              >
+                <Download aria-hidden='true' />
+              </Button>
+              {onRemove ? (
+                <Button
+                  type='button'
+                  size='icon'
+                  variant='ghost'
+                  aria-label={`${removeLabel}: ${file.filename}`}
+                  title={removeLabel}
+                  onClick={() => void onRemove(file)}
+                >
+                  <Trash2 aria-hidden='true' />
+                </Button>
+              ) : null}
+            </div>
+          </li>
+        ))}
+      </ul>
+      <FilePreviewDialog
+        files={files}
+        initialIndex={previewIndex}
+        open={previewOpen}
+        onOpenChange={setPreviewOpen}
+        labels={labels}
+        onError={onError}
+      />
+    </>
+  );
+}

package/client/extensions/nocobase-file-component-ui/components/file-preview-dialog.tsx

@@ -0,0 +1,263 @@
+import { useTranslation } from '@nocobase/i18n/client';
+import { ChevronLeft, ChevronRight, Download } from 'lucide-react';
+import { useEffect, useMemo, useState, type ReactElement } from 'react';
+
+import type {
+  FilePreviewDialogProps,
+  FileRecord,
+  FileUiLabels,
+} from '../types';
+import {
+  isActiveMarkupMimeType,
+  resolveFilePreviewKind,
+  type FilePreviewKind,
+} from '../lib/file-preview';
+import { Button } from '#components/ui/button';
+import { Dialog, DialogContent, DialogTitle } from '#components/ui/dialog';
+import { fileUrlCredentials, resolveSafeFileUrl } from '../lib/file-url';
+import { FilePreviewContent } from './previewers/file-preview-content';
+
+const PDF_MIME_TYPE = 'application/pdf';
+const PDF_PREVIEW_ERROR = 'Unable to load the PDF preview.';
+const PDF_MARKUP_RESPONSE_ERROR =
+  'The file URL returned HTML or XML instead of a PDF.';
+
+export function FilePreviewDialog({
+  files,
+  initialIndex = 0,
+  open,
+  onOpenChange,
+  download: allowDownload = true,
+  labels,
+  onError,
+}: FilePreviewDialogProps): ReactElement | null {
+  if (!open || !files.length) return null;
+  const normalizedIndex = Math.max(0, Math.min(initialIndex, files.length - 1));
+  return (
+    <OpenFilePreviewDialog
+      key={`${normalizedIndex}:${files.map((file) => file.id).join(':')}`}
+      files={files}
+      initialIndex={normalizedIndex}
+      onOpenChange={onOpenChange}
+      download={allowDownload}
+      labels={labels}
+      onError={onError}
+    />
+  );
+}
+
+interface OpenFilePreviewDialogProps {
+  readonly files: readonly FileRecord[];
+  readonly initialIndex: number;
+  readonly onOpenChange: (open: boolean) => void;
+  readonly download: boolean;
+  readonly labels?: FileUiLabels;
+  readonly onError?: (error: Error) => void;
+}
+
+function OpenFilePreviewDialog(
+  inputProps: OpenFilePreviewDialogProps,
+): ReactElement {
+  const { t } = useTranslation('@nocobase/app-plugin-file');
+  const {
+    files,
+    initialIndex,
+    onOpenChange,
+    download: allowDownload,
+    labels,
+    onError,
+  } = inputProps;
+
+  const [index, setIndex] = useState(initialIndex);
+  const file = files[index];
+  if (!file) throw new Error('A preview file is required.');
+  const downloadLabel =
+    labels?.download ?? t('files.download', { defaultValue: 'Download' });
+  return (
+    <Dialog open onOpenChange={onOpenChange}>
+      <DialogContent
+        className='flex max-h-[calc(100dvh-2rem)] max-w-[calc(100%-2rem)] flex-col sm:max-w-4xl'
+        showCloseButton
+      >
+        <div className='flex items-center justify-between gap-3 pr-10'>
+          <div className='min-w-0'>
+            <DialogTitle className='truncate'>{file.filename}</DialogTitle>
+            <p className='text-sm text-muted-foreground'>{file.mimeType}</p>
+          </div>
+          <div className='flex gap-1'>
+            {files.length > 1 ? (
+              <>
+                <Button
+                  type='button'
+                  size='icon'
+                  variant='ghost'
+                  aria-label={t('files.previous', {
+                    defaultValue: 'Previous file',
+                  })}
+                  onClick={() =>
+                    setIndex(
+                      (value) => (value - 1 + files.length) % files.length,
+                    )
+                  }
+                >
+                  <ChevronLeft aria-hidden='true' />
+                </Button>
+                <Button
+                  type='button'
+                  size='icon'
+                  variant='ghost'
+                  aria-label={t('files.next', { defaultValue: 'Next file' })}
+                  onClick={() =>
+                    setIndex((value) => (value + 1) % files.length)
+                  }
+                >
+                  <ChevronRight aria-hidden='true' />
+                </Button>
+              </>
+            ) : null}
+            {allowDownload ? (
+              <Button
+                type='button'
+                size='icon'
+                variant='ghost'
+                aria-label={`${downloadLabel}: ${file.filename}`}
+                onClick={() =>
+                  void downloadFile(file).catch((error: unknown) =>
+                    reportDownloadError(onError, error),
+                  )
+                }
+              >
+                <Download aria-hidden='true' />
+              </Button>
+            ) : null}
+          </div>
+        </div>
+        {/* Only the preview scrolls; the title and its actions stay in view. */}
+        <div className='-mx-4 min-h-0 flex-1 overflow-auto px-4'>
+          <PreviewBody
+            key={`${file.id}:${String(file.updatedAt)}:${file.contentUrl}`}
+            file={file}
+            onDownload={
+              allowDownload
+                ? () =>
+                    void downloadFile(file).catch((error: unknown) =>
+                      reportDownloadError(onError, error),
+                    )
+                : undefined
+            }
+          />
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+async function downloadFile(file: FileRecord): Promise<void> {
+  const raw = file.contentUrl;
+  const url = raw ? resolveSafeFileUrl(raw) : undefined;
+  if (!url) throw new Error('File URL is not allowed.');
+  const link = document.createElement('a');
+  link.href = url;
+  link.download = file.filename;
+  link.rel = 'noopener';
+  link.click();
+}
+
+function reportDownloadError(
+  onError: ((error: Error) => void) | undefined,
+  error: unknown,
+): void {
+  onError?.(
+    error instanceof Error ? error : new Error('File download failed.'),
+  );
+}
+
+// A blob URL is same-origin, so the frame must receive the bytes as a PDF and
+// never as a document the browser would render and run. This retyping is the
+// safeguard; refusing an active markup response turns an HTML answer, such as
+// a login page, into an error that names the cause instead of a broken viewer.
+function asPdfBlob(blob: Blob): Blob {
+  return blob.type === PDF_MIME_TYPE
+    ? blob
+    : blob.slice(0, blob.size, PDF_MIME_TYPE);
+}
+
+function PreviewBody({
+  file,
+  onDownload,
+}: {
+  file: FileRecord;
+  onDownload?: () => void;
+}): ReactElement {
+  const sourceUrl = resolveSafeFileUrl(file.contentUrl ?? '');
+  const [text, setText] = useState<string>();
+  const [blobUrl, setBlobUrl] = useState<string>();
+  const [error, setError] = useState<string | undefined>(() =>
+    !sourceUrl ? 'File URL is missing or not allowed.' : undefined,
+  );
+  const kind: FilePreviewKind = useMemo(
+    () => resolveFilePreviewKind(file),
+    [file],
+  );
+  // The content route downloads PDFs as attachments; a local blob can be embedded.
+  useEffect(() => {
+    if (!sourceUrl || kind !== 'pdf') return undefined;
+    const controller = new AbortController();
+    let objectUrl: string | undefined;
+    void fetch(sourceUrl, {
+      credentials: fileUrlCredentials(sourceUrl),
+      signal: controller.signal,
+    })
+      .then(async (response) => {
+        if (!response.ok) throw new Error(PDF_PREVIEW_ERROR);
+        const blob = await response.blob();
+        if (controller.signal.aborted) return;
+        if (isActiveMarkupMimeType(blob.type))
+          throw new Error(PDF_MARKUP_RESPONSE_ERROR);
+        objectUrl = URL.createObjectURL(asPdfBlob(blob));
+        setBlobUrl(objectUrl);
+      })
+      .catch((cause: unknown) => {
+        if (!controller.signal.aborted)
+          setError(cause instanceof Error ? cause.message : PDF_PREVIEW_ERROR);
+      });
+    return () => {
+      controller.abort();
+      if (objectUrl) URL.revokeObjectURL(objectUrl);
+    };
+  }, [sourceUrl, kind]);
+  const url = kind === 'pdf' ? blobUrl : sourceUrl;
+  useEffect(() => {
+    if (!url || !['text', 'markdown'].includes(kind)) return undefined;
+    const controller = new AbortController();
+    void fetch(url, {
+      credentials: fileUrlCredentials(url),
+      signal: controller.signal,
+    })
+      .then((response) => {
+        if (!response.ok)
+          throw new Error(`Preview request failed (${response.status}).`);
+        return response.text();
+      })
+      .then(setText)
+      .catch((cause: unknown) => {
+        if (!(cause instanceof DOMException && cause.name === 'AbortError'))
+          setError(
+            cause instanceof Error
+              ? cause.message
+              : 'Unable to load the file preview.',
+          );
+      });
+    return () => controller.abort();
+  }, [file, kind, url]);
+  return (
+    <FilePreviewContent
+      file={file}
+      kind={kind}
+      url={url}
+      text={text}
+      error={error}
+      onDownload={onDownload}
+    />
+  );
+}

package/client/extensions/nocobase-file-component-ui/components/file-preview-field.tsx

@@ -0,0 +1,68 @@
+import { useTranslation } from '@nocobase/i18n/client';
+import { useState, type ReactElement } from 'react';
+import type { FilePreviewFieldProps } from '../types';
+import { Button } from '#components/ui/button';
+import { FilePreviewDialog } from './file-preview-dialog';
+import { FileThumbnail } from './file-thumbnail';
+
+export function FilePreviewField(
+  inputProps: FilePreviewFieldProps,
+): ReactElement {
+  const { t } = useTranslation('@nocobase/app-plugin-file');
+  const {
+    files,
+    labels,
+    emptyState,
+    showFilenames = false,
+    onError,
+  } = inputProps;
+
+  const [open, setOpen] = useState(false);
+  const [initialIndex, setInitialIndex] = useState(0);
+  if (!files.length)
+    return (
+      <>
+        {emptyState ?? (
+          <span role='status'>
+            {t('files.empty', { defaultValue: 'No files.' })}
+          </span>
+        )}
+      </>
+    );
+  return (
+    <>
+      <div data-slot='file-preview-field' className='flex flex-wrap gap-2'>
+        {files.map((file, index) => (
+          <div key={file.id} className='flex max-w-36 flex-col gap-1'>
+            <Button
+              type='button'
+              variant='ghost'
+              size='icon'
+              className='h-12 w-12 overflow-hidden'
+              aria-label={`${labels?.preview ?? t('files.preview', { defaultValue: 'Preview' })}: ${file.filename}`}
+              onClick={() => {
+                setInitialIndex(index);
+                setOpen(true);
+              }}
+            >
+              <FileThumbnail file={file} />
+            </Button>
+            {showFilenames ? (
+              <span className='truncate text-xs' title={file.filename}>
+                {file.filename}
+              </span>
+            ) : null}
+          </div>
+        ))}
+      </div>
+      <FilePreviewDialog
+        files={files}
+        initialIndex={initialIndex}
+        open={open}
+        onOpenChange={setOpen}
+        labels={labels}
+        onError={onError}
+      />
+    </>
+  );
+}