@nocobase/app-template-default 1.0.0-beta.88 → 1.0.0-beta.90

package/client/components/route-overlay.tsx

@@ -26,10 +26,14 @@ import {
   DialogPortal,
   DialogTitle,
 } from '#components/ui/dialog';
+import {
+  RouteOverlayContext,
+  RouteOverlayHostContext,
+  type RouteOverlayHostConfig,
+  type RouteOverlayHostValue,
+} from '@nocobase/app-client/route-containers';
 import { cn } from 'cn';
 
-import { RouteOverlayContext } from './use-route-overlay.js';
-
 export interface RouteOverlayProps {
   readonly title: ReactNode;
   readonly description?: ReactNode;
@@ -52,8 +56,103 @@ const ParentPopupContext =
 /**
  * The shared implementation of `RouteDialog` and `RouteDrawer`: a modal that is open for as long as its route matches,
  * and closes by navigating away from it. Route registration stays with the application.
+ *
+ * On a route that declares a `dialog` or `drawer` presentation the application has already opened the panel, and this
+ * component configures that one instead of opening a second: its title, description, footer, `closeTo` and
+ * `beforeClose` move to the host and its children render in the host's body. On any other route it opens its own.
+ * The host context comes from `@nocobase/app-client`, so a plugin's own copy of this component joins the same panel.
+ */
+export function RouteOverlay(
+  props: RouteOverlayProps & { readonly drawer?: boolean },
+): ReactElement {
+  const host = useContext(RouteOverlayHostContext);
+  return host ? (
+    <HostedRouteOverlay host={host} {...props} />
+  ) : (
+    <RouteOverlayFrame {...props} />
+  );
+}
+
+function HostedRouteOverlay({
+  host,
+  children,
+  drawer: _drawer,
+  ...config
+}: RouteOverlayProps & {
+  readonly host: RouteOverlayHostValue;
+  readonly drawer?: boolean;
+}): ReactElement {
+  // Runs after every render so the footer and guard the host shows are always this render's. There is no cleanup:
+  // the host stops using the configuration once it is told the page is gone, and an `<Activity>` that only hides
+  // the page during a recheck must not take its close guard away.
+  useLayoutEffect(() => {
+    host.configure(config);
+  });
+  return (
+    <RouteOverlayHostContext.Provider value={null}>
+      {children}
+    </RouteOverlayHostContext.Provider>
+  );
+}
+
+export interface RouteOverlayHostProps {
+  readonly drawer?: boolean;
+  /** Shown until the hosted page configures its own title, and whenever its content is concealed. */
+  readonly title: ReactNode;
+  /**
+   * True while the page component is mounted. While it is false — the module is loading, failed or was denied — the
+   * host ignores what an earlier mount configured and closes without a guard.
+   */
+  readonly ready?: boolean;
+  /**
+   * True while the mounted page is hidden, for example during an authorization recheck: the host shows only its own
+   * title and no footer, so nothing the page derived from protected data stays on screen. The page's close guard
+   * is temporarily blocked until the page's effects reconnect, because hiding disconnects form dirty registrations.
+   */
+  readonly concealed?: boolean;
+  readonly children?: ReactNode;
+}
+
+/**
+ * The panel the application opens for a route that declares a `dialog` or `drawer` presentation, before the page
+ * module, its authorization check or its data are ready. Waiting, denial and failure render as its children; once the
+ * page renders its own `RouteDialog` or `RouteDrawer` inside, that configures this panel. There is still one panel
+ * and one focus trap, and the same close path and focus return as a standalone overlay. A hosted page renders its
+ * `RouteDialog` or `RouteDrawer` unconditionally, as its root.
  */
-export function RouteOverlay({
+export function RouteOverlayHost({
+  drawer = false,
+  title,
+  ready = false,
+  concealed = false,
+  children,
+}: RouteOverlayHostProps): ReactElement {
+  const [config, setConfig] = useState<RouteOverlayHostConfig | null>(null);
+  const host = useMemo<RouteOverlayHostValue>(
+    () => ({ configure: setConfig }),
+    [],
+  );
+  const page = ready ? config : null;
+  const shown = concealed ? null : page;
+  return (
+    <RouteOverlayFrame
+      drawer={drawer}
+      title={shown?.title ?? title}
+      description={shown?.description}
+      footer={shown?.footer}
+      closeTo={page?.closeTo}
+      beforeClose={page?.beforeClose}
+      closeBlocked={ready && concealed}
+      className={page?.className}
+    >
+      <RouteOverlayHostContext.Provider value={host}>
+        {children}
+      </RouteOverlayHostContext.Provider>
+    </RouteOverlayFrame>
+  );
+}
+
+function RouteOverlayFrame({
   title,
   description,
   children,
@@ -62,10 +161,24 @@ export function RouteOverlay({
   beforeClose,
   className,
   drawer = false,
-}: RouteOverlayProps & { readonly drawer?: boolean }): ReactElement {
+  closeBlocked = false,
+}: RouteOverlayProps & {
+  readonly drawer?: boolean;
+  readonly closeBlocked?: boolean;
+}): ReactElement {
   const { t } = useTranslation();
   const parentPopup = useContext(ParentPopupContext);
   const popupRef = useRef<HTMLDivElement>(null);
+  const [portal, setPortal] = useState<HTMLDivElement | null>(null);
+  // A parent route's Activity can stop at its first DOM element, while this portal lives outside that element.
+  // Base UI creates the portal after mount, so track the actual node before connecting its visibility lifecycle.
+  useLayoutEffect(() => {
+    if (!portal) return;
+    portal.style.removeProperty('display');
+    return () => {
+      portal.style.display = 'none';
+    };
+  }, [portal]);
   const previousFocusRef = useRef<HTMLElement | null>(null);
   useLayoutEffect(() => {
     previousFocusRef.current =
@@ -75,29 +188,37 @@ export function RouteOverlay({
   }, []);
   const navigate = useNavigate();
   const location = useLocation();
-  const [closingLocation, setClosingLocation] = useState<
-    typeof location | null
-  >(null);
-  const isClosing = closingLocation === location;
+  const closeScope = useMemo(
+    () => ({ location, closeBlocked }),
+    [location, closeBlocked],
+  );
+  const [closingScope, setClosingScope] = useState<typeof closeScope | null>(
+    null,
+  );
+  const isClosing = closingScope === closeScope;
   const pendingRef = useRef<Promise<void> | null>(null);
   const generationRef = useRef(0);
 
-  // A still-mounted parent can change location while its confirmation is pending.
-  // Invalidate that request as well as requests from an unmounted route.
+  // A location change or concealment invalidates pending closes. Activity cleanup can resolve a form's old
+  // confirmation, but that result must never navigate, including after permission is restored.
   useLayoutEffect(() => {
     generationRef.current += 1;
     pendingRef.current = null;
     return () => {
       generationRef.current += 1;
+      setClosingScope(null);
     };
-  }, [location]);
+  }, [location, closeBlocked]);
 
   const close = useCallback((): Promise<void> => {
+    if (closeBlocked) return Promise.resolve();
     if (pendingRef.current) return pendingRef.current;
     const requestGeneration = generationRef.current;
-    setClosingLocation(location);
+    setClosingScope(closeScope);
     const request = Promise.resolve()
       .then(async () => {
+        // A recheck can start while an earlier confirmation is open, or before this microtask runs.
+        if (generationRef.current !== requestGeneration) return;
         const allowed = beforeClose ? await beforeClose() : true;
         if (allowed && generationRef.current === requestGeneration) {
           await navigate(
@@ -109,12 +230,12 @@ export function RouteOverlay({
       .finally(() => {
         if (generationRef.current === requestGeneration) {
           pendingRef.current = null;
-          setClosingLocation(null);
+          setClosingScope(null);
         }
       });
     pendingRef.current = request;
     return request;
-  }, [beforeClose, closeTo, location, navigate]);
+  }, [beforeClose, closeBlocked, closeScope, closeTo, location, navigate]);
   const value = useMemo(() => ({ close, isClosing }), [close, isClosing]);
 
   return (
@@ -131,7 +252,7 @@ export function RouteOverlay({
               });
           }}
         >
-          <DialogPortal>
+          <DialogPortal ref={setPortal}>
             {/* Each nested panel needs its own backdrop above its parent panel. */}
             <DialogOverlay forceRender />
             <DialogPrimitive.Popup
@@ -212,3 +333,16 @@ export function RouteOverlay({
     </RouteOverlayContext.Provider>
   );
 }
+
+/** Ends a `RouteOverlayHost`'s reach, so a route rendered inside one that is not hosted builds its own overlay. */
+export function RouteOverlayHostBoundary({
+  children,
+}: {
+  readonly children?: ReactNode;
+}): ReactElement {
+  return (
+    <RouteOverlayHostContext.Provider value={null}>
+      {children}
+    </RouteOverlayHostContext.Provider>
+  );
+}

package/client/components/task-progress.tsx

@@ -0,0 +1,155 @@
+import { Progress } from '@base-ui/react/progress';
+import { useTranslation } from '@nocobase/i18n/client';
+import type { ReactElement, ReactNode } from 'react';
+import { cn } from 'cn';
+
+export type TaskProgressStatus =
+  'queued' | 'running' | 'completed' | 'failed' | 'canceled';
+
+export interface TaskProgressProps {
+  /** The task's real lifecycle status, from the server's task record. */
+  readonly status: TaskProgressStatus;
+  /** What the task is, such as "Customer export". */
+  readonly label: string;
+  /** The application's own word for the status; defaults to the standard copy. */
+  readonly statusLabel?: string;
+  /** Units actually processed, as reported by the task. */
+  readonly processed?: number;
+  /** The real total; leave it out or pass null while it is unknown. */
+  readonly total?: number | null;
+  /** For tasks that report only a percentage (0–100) instead of counts. */
+  readonly percent?: number | null;
+  /** Show that the task keeps running after the user leaves the page. */
+  readonly continuesInBackground?: boolean;
+  /** Caller-owned detail: a failure reason, or where the result is. */
+  readonly message?: ReactNode;
+  /** Real actions only: download, retry, or a cancel the server supports. */
+  readonly actions?: ReactNode;
+  readonly className?: string;
+}
+
+/**
+ * One long-running task record. A known total shows a determinate bar and
+ * count; an unknown total shows an indeterminate bar without a percentage.
+ * Status changes are announced once; percentage updates are not.
+ */
+export function TaskProgress({
+  status,
+  label,
+  statusLabel,
+  processed,
+  total,
+  percent: reportedPercent,
+  continuesInBackground = false,
+  message,
+  actions,
+  className,
+}: TaskProgressProps): ReactElement {
+  const { t } = useTranslation();
+  const active = status === 'queued' || status === 'running';
+  const counted = total !== undefined && total !== null && total > 0;
+  const done = processed ?? 0;
+  const known =
+    counted || (reportedPercent !== undefined && reportedPercent !== null);
+  const percent = counted
+    ? Math.min(100, Math.floor((done / total) * 100))
+    : Math.min(100, Math.max(0, Math.floor(reportedPercent ?? 0)));
+  const statusText =
+    statusLabel ??
+    {
+      queued: t('taskProgress.queued', { defaultValue: 'Waiting to start' }),
+      running: t('taskProgress.running', { defaultValue: 'In progress' }),
+      completed: t('taskProgress.completed', { defaultValue: 'Completed' }),
+      failed: t('taskProgress.failed', { defaultValue: 'Failed' }),
+      canceled: t('taskProgress.canceled', { defaultValue: 'Canceled' }),
+    }[status];
+  const countText = counted
+    ? t('taskProgress.count', {
+        defaultValue: '{{processed}} of {{total}}',
+        processed: done,
+        total,
+      })
+    : processed
+      ? t('taskProgress.processed', {
+          defaultValue: '{{processed}} processed',
+          processed: done,
+        })
+      : undefined;
+  return (
+    <div
+      data-slot='task-progress'
+      data-status={status}
+      className={cn('flex flex-col gap-2', className)}
+    >
+      <div className='flex flex-wrap items-baseline justify-between gap-x-3 gap-y-1'>
+        <span className='min-w-0 text-sm font-medium wrap-anywhere'>
+          {label}
+        </span>
+        <span
+          className={cn(
+            'text-sm',
+            status === 'failed' ? 'text-destructive' : 'text-muted-foreground',
+          )}
+        >
+          {statusText}
+        </span>
+      </div>
+      {active ? (
+        <Progress.Root
+          value={known ? percent : null}
+          aria-label={label}
+          getAriaValueText={() =>
+            [statusText, countText, known ? `${percent}%` : undefined]
+              .filter(Boolean)
+              .join(', ')
+          }
+          className='flex flex-col gap-1.5'
+        >
+          <Progress.Track className='relative h-1.5 w-full overflow-hidden rounded-full bg-muted'>
+            {/* An unknown amount fills the whole track faintly, so no segment can be read as a fraction done. */}
+            <Progress.Indicator
+              data-slot='task-progress-indicator'
+              className={
+                known
+                  ? 'h-full bg-primary motion-safe:transition-[width] motion-safe:duration-500'
+                  : 'h-full w-full bg-primary/25 motion-safe:animate-pulse'
+              }
+            />
+          </Progress.Track>
+          {countText || known ? (
+            <span className='text-xs text-muted-foreground tabular-nums'>
+              {[countText, known ? `${percent}%` : undefined]
+                .filter(Boolean)
+                .join(' · ')}
+            </span>
+          ) : null}
+        </Progress.Root>
+      ) : countText && status !== 'completed' ? (
+        <span className='text-xs text-muted-foreground tabular-nums'>
+          {countText}
+        </span>
+      ) : null}
+      {active && continuesInBackground ? (
+        <p className='text-xs text-muted-foreground'>
+          {t('taskProgress.background', {
+            defaultValue: 'It keeps running if you leave this page.',
+          })}
+        </p>
+      ) : null}
+      {message ? (
+        <div
+          className={cn(
+            'text-sm',
+            status === 'failed' ? 'text-destructive' : 'text-muted-foreground',
+          )}
+        >
+          {message}
+        </div>
+      ) : null}
+      {actions ? <div className='flex flex-wrap gap-2'>{actions}</div> : null}
+      <span role='status' aria-live='polite' className='sr-only'>
+        {`${label}: ${statusText}`}
+      </span>
+    </div>
+  );
+}

package/client/components/use-route-overlay.ts

@@ -1,15 +1,12 @@
-import { createContext, useContext, type Context } from 'react';
+import {
+  RouteOverlayContext,
+  type RouteOverlayContextValue,
+} from '@nocobase/app-client/route-containers';
+import { useContext } from 'react';
 
-export interface RouteOverlayContextValue {
-  /** Runs `beforeClose`, then navigates to the parent route unless it declined. Concurrent calls share one request. */
-  readonly close: () => Promise<void>;
-  /** True while a close request for the current location is pending. */
-  readonly isClosing: boolean;
-}
-
-/** Internal context shared by both route overlay components. */
-export const RouteOverlayContext: Context<RouteOverlayContextValue | null> =
-  createContext<RouteOverlayContextValue | null>(null);
+// The context lives in `@nocobase/app-client` so every copy of the route overlay components, including a plugin's,
+// shares it: a footer button inside a panel the application opened reaches that panel's close request.
+export { RouteOverlayContext, type RouteOverlayContextValue };
 
 /**
  * Closes the enclosing `RouteDialog` or `RouteDrawer`. Call it from a component rendered inside the overlay — its

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

@@ -1,4 +1,5 @@
 import { messageKey } from '../lib/message-key.js';
+import { usePendingFeedback } from '@nocobase/app-client';
 import { useTranslation } from '@nocobase/i18n/client';
 import { RotateCcw, Trash2, UploadCloud, X } from 'lucide-react';
 import {
@@ -8,11 +9,12 @@ import {
   type ChangeEvent,
   type DragEvent,
   type ReactElement,
+  type ReactNode,
 } from 'react';
 
 import type { FileRecord, FileUploadFieldProps } from '../types.js';
 import { Button } from '#components/ui/button';
-import { Spinner } from '#components/ui/spinner';
+import { BrandLoadingMark } from '#components/brand-loading-mark';
 import { FileThumbnail } from './file-thumbnail.js';
 
 type UploadItem = {
@@ -23,6 +25,48 @@ type UploadItem = {
   readonly error?: Error;
 };
 
+/**
+ * The upload request reports no byte progress, so the item shows an honest
+ * indeterminate wait from one display hook: the mark appears after the shared
+ * display delay and a long upload says so after 10 seconds, next to the real
+ * cancel action.
+ */
+function UploadItemBody({
+  status,
+  failure,
+  children,
+}: {
+  readonly status: UploadItem['status'];
+  readonly failure?: string;
+  readonly children: ReactNode;
+}): ReactElement {
+  const { t } = useTranslation();
+  const feedback = usePendingFeedback(status === 'uploading');
+  return (
+    <>
+      <div className='flex h-20 items-center justify-center overflow-hidden rounded-sm bg-muted/30'>
+        {feedback.visible ? (
+          <BrandLoadingMark className='size-8 text-muted-foreground' />
+        ) : (
+          <UploadCloud aria-hidden='true' />
+        )}
+      </div>
+      {children}
+      <div className='text-xs text-muted-foreground'>
+        {status === 'error'
+          ? (failure ?? t('fileUi.files.failed', { defaultValue: 'Failed' }))
+          : status === 'uploading'
+            ? feedback.longWaiting
+              ? t('fileUi.files.longWait', {
+                  defaultValue: 'Still uploading. Keep waiting or cancel.',
+                })
+              : t('fileUi.files.uploading', { defaultValue: 'Uploading' })
+            : t('fileUi.files.pending', { defaultValue: 'Pending' })}
+      </div>
+    </>
+  );
+}
+
 function accepts(file: File, rules: readonly string[]): boolean {
   if (!rules.length) return true;
   const name = file.name.toLowerCase();
@@ -249,12 +293,10 @@ export function FileUploadField(
   };
 
   return (
-    <div
-      data-slot='file-upload-field'
-      className='space-y-3'
-      aria-busy={items.some((item) => item.status === 'uploading')}
-    >
+    <div data-slot='file-upload-field' className='space-y-3'>
+      {/* The polite summary below stays outside the busy drop zone. */}
       <div
+        aria-busy={items.some((item) => item.status === 'uploading')}
         className={`flex min-h-24 flex-wrap gap-3 rounded-md border border-dashed p-3 ${dragging ? 'border-primary bg-primary/5' : ''}`}
         onDragOver={(event) => {
           event.preventDefault();
@@ -288,32 +330,20 @@ export function FileUploadField(
         ))}
         {items.map((item) => (
           <div key={item.key} className='w-36 rounded-md border p-2'>
-            <div className='flex h-20 items-center justify-center overflow-hidden rounded-sm bg-muted/30'>
-              {item.status === 'uploading' ? (
-                <Spinner
-                  aria-label={t('fileUi.files.uploading', {
-                    defaultValue: 'Uploading',
-                  })}
-                />
-              ) : (
-                <UploadCloud aria-hidden='true' />
-              )}
-            </div>
-            <div className='mt-2 truncate text-sm' title={item.file.name}>
-              {item.file.name}
-            </div>
-            <div className='text-xs text-muted-foreground'>
-              {item.status === 'error'
-                ? ((item.error
-                    ? t(messageKey(item.error.message), {
-                        defaultValue: item.error.message,
-                      })
-                    : undefined) ??
-                  t('fileUi.files.failed', { defaultValue: 'Failed' }))
-                : item.status === 'uploading'
-                  ? t('fileUi.files.uploading', { defaultValue: 'Uploading' })
-                  : t('fileUi.files.pending', { defaultValue: 'Pending' })}
-            </div>
+            <UploadItemBody
+              status={item.status}
+              failure={
+                item.status === 'error' && item.error
+                  ? t(messageKey(item.error.message), {
+                      defaultValue: item.error.message,
+                    })
+                  : undefined
+              }
+            >
+              <div className='mt-2 truncate text-sm' title={item.file.name}>
+                {item.file.name}
+              </div>
+            </UploadItemBody>
             <div className='mt-2 flex gap-1'>
               {item.status === 'error' ? (
                 <Button

package/client/extensions/nocobase-file-component-ui/locales/de-DE.ts

@@ -26,6 +26,8 @@ const messages = {
   'files.retry': 'Erneut versuchen',
   'files.done': 'Erledigt',
   'files.uploading': 'Hochladen',
+  'files.longWait':
+    'Wird noch hochgeladen. Warten Sie weiter oder brechen Sie ab.',
   'files.failed': 'Fehlgeschlagen',
   'files.pending': 'Ausstehend',
   'files.previous': 'Vorherige Datei',

package/client/extensions/nocobase-file-component-ui/locales/en-US.ts

@@ -24,6 +24,7 @@ const messages = {
   'files.retry': 'Retry',
   'files.done': 'Done',
   'files.uploading': 'Uploading',
+  'files.longWait': 'Still uploading. Keep waiting or cancel.',
   'files.failed': 'Failed',
   'files.pending': 'Pending',
   'files.previous': 'Previous file',

package/client/extensions/nocobase-file-component-ui/locales/es-ES.ts

@@ -25,6 +25,7 @@ const messages = {
   'files.retry': 'Reintentar',
   'files.done': 'Hecho',
   'files.uploading': 'Subiendo',
+  'files.longWait': 'Aún se está subiendo. Siga esperando o cancele.',
   'files.failed': 'Falló',
   'files.pending': 'Pendiente',
   'files.previous': 'Archivo anterior',

package/client/extensions/nocobase-file-component-ui/locales/fr-FR.ts

@@ -26,6 +26,7 @@ const messages = {
   'files.retry': 'Réessayer',
   'files.done': 'Terminé',
   'files.uploading': 'Téléchargement',
+  'files.longWait': 'Envoi toujours en cours. Patientez ou annulez.',
   'files.failed': 'Échec',
   'files.pending': 'En attente',
   'files.previous': 'Fichier précédent',

package/client/extensions/nocobase-file-component-ui/locales/id-ID.ts

@@ -24,6 +24,7 @@ const messages = {
   'files.retry': 'Coba lagi',
   'files.done': 'Selesai',
   'files.uploading': 'Mengunggah',
+  'files.longWait': 'Masih mengunggah. Tunggu atau batalkan.',
   'files.failed': 'Gagal',
   'files.pending': 'Tertunda',
   'files.previous': 'Berkas sebelumnya',

package/client/extensions/nocobase-file-component-ui/locales/ja-JP.ts

@@ -27,6 +27,8 @@ const messages = {
   'files.retry': '再試行',
   'files.done': '完了',
   'files.uploading': 'アップロード中',
+  'files.longWait':
+    'アップロード中です。このまま待つか、キャンセルしてください。',
   'files.failed': '失敗しました',
   'files.pending': '保留中',
   'files.previous': '前のファイル',

package/client/extensions/nocobase-file-component-ui/locales/pt-BR.ts

@@ -26,6 +26,7 @@ const messages = {
   'files.retry': 'Tentar novamente',
   'files.done': 'Concluído',
   'files.uploading': 'Carregando',
+  'files.longWait': 'Ainda enviando. Continue aguardando ou cancele.',
   'files.failed': 'Falha',
   'files.pending': 'Pendente',
   'files.previous': 'Arquivo anterior',

package/client/extensions/nocobase-file-component-ui/locales/vi-VN.ts

@@ -25,6 +25,7 @@ const messages = {
   'files.retry': 'Thử lại',
   'files.done': 'Hoàn thành',
   'files.uploading': 'Đang tải lên',
+  'files.longWait': 'Vẫn đang tải lên. Hãy tiếp tục chờ hoặc hủy.',
   'files.failed': 'Thất bại',
   'files.pending': 'Đang chờ',
   'files.previous': 'Tệp trước đó',

package/client/extensions/nocobase-file-component-ui/locales/zh-CN.ts

@@ -23,6 +23,7 @@ const messages = {
   'files.retry': '重试',
   'files.done': '已完成',
   'files.uploading': '正在上传',
+  'files.longWait': '仍在上传，可继续等待或取消。',
   'files.failed': '失败',
   'files.pending': '等待中',
   'files.previous': '上一个文件',

package/client/extensions/nocobase-file-component-ui/locales/zh-TW.ts

@@ -23,6 +23,7 @@ const messages = {
   'files.retry': '重試',
   'files.done': '已完成',
   'files.uploading': '上傳中',
+  'files.longWait': '仍在上傳，可繼續等待或取消。',
   'files.failed': '失敗',
   'files.pending': '待處理',
   'files.previous': '上一個檔案',