@nocobase/app-template-default 1.0.0-beta.87 → 1.0.0-beta.89

package/client/components/flow-diagram.tsx

@@ -8,7 +8,7 @@ import {
   type ReactElement,
   type ReactNode,
 } from 'react';
-import { createPortal } from 'react-dom';
+import { BodyPortal } from './body-portal.js';
 import {
   BaseEdge,
   Controls,
@@ -934,7 +934,7 @@ export function FlowDiagram({
       )}
     </div>
   );
-  return expanded ? createPortal(canvas, document.body) : canvas;
+  return expanded ? <BodyPortal>{canvas}</BodyPortal> : canvas;
 }
 
 /** View controls belong inside React Flow so they always use this canvas's viewport. */

package/client/components/list-feedback.tsx

@@ -3,7 +3,6 @@ import { useTranslation } from '@nocobase/i18n/client';
 import {
   CircleAlert,
   Inbox,
-  LoaderCircle,
   LockKeyhole,
   LogIn,
   RefreshCw,
@@ -14,6 +13,8 @@ import { Fragment, type ReactElement, type ReactNode } from 'react';
 import { Link } from 'react-router';
 import { Button } from '#components/ui/button';
 import { Alert } from '#components/ui/alert';
+import { Loading } from '#components/loading';
+import { PendingButton } from '#components/pending-button';
 import {
   Empty,
   EmptyContent,
@@ -23,7 +24,6 @@ import {
 } from '#components/ui/empty';
 
 const feedback = {
-  loading: ['listFeedback.loading', 'Loading', LoaderCircle],
   empty: ['listFeedback.empty', 'No data yet', Inbox],
   'no-results': ['listFeedback.noResults', 'No results', SearchX],
   forbidden: ['listFeedback.forbidden', 'Access denied', LockKeyhole],
@@ -38,6 +38,11 @@ export interface ListFeedbackProps {
   readonly empty?: ReactNode;
   /** Optional business-specific action; the standard create action belongs in the page header. */
   readonly emptyAction?: ReactNode;
+  /**
+   * The current query's stable identity, such as its request path. A new
+   * query restarts the display delay without remounting the list.
+   */
+  readonly identity?: unknown;
 }
 
 export interface ListFeedbackActionsProps {
@@ -67,19 +72,17 @@ export function ListFeedbackActions({
 
   if ((state === 'failed' || state === 'refresh-failed') && onRetry) {
     return (
-      <Button variant='outline' disabled={busy} onClick={onRetry}>
-        {busy ? (
-          <LoaderCircle
-            aria-hidden='true'
-            className='motion-safe:animate-spin'
-          />
-        ) : (
-          <RefreshCw aria-hidden='true' />
-        )}
-        {busy
-          ? t('listFeedback.retrying', { defaultValue: 'Retrying…' })
-          : t('listFeedback.retry', { defaultValue: 'Retry' })}
-      </Button>
+      <PendingButton
+        variant='outline'
+        busy={busy}
+        pendingLabel={t('listFeedback.retrying', {
+          defaultValue: 'Retrying…',
+        })}
+        onClick={onRetry}
+      >
+        <RefreshCw aria-hidden='true' />
+        {t('listFeedback.retry', { defaultValue: 'Retry' })}
+      </PendingButton>
     );
   }
 
@@ -105,6 +108,7 @@ export function ListFeedback({
   children,
   empty,
   emptyAction,
+  identity,
 }: ListFeedbackProps): ReactElement {
   const { t } = useTranslation();
 
@@ -134,6 +138,17 @@ export function ListFeedback({
     );
   }
 
+  if (state === 'loading') {
+    // The body keeps its footprint at once; the indicator and one status follow the shared display delay.
+    return (
+      <Loading
+        identity={identity}
+        label={t('listFeedback.loading', { defaultValue: 'Loading' })}
+        className='min-h-24 px-4 py-4'
+      />
+    );
+  }
+
   const [key, fallback, Icon] = feedback[state];
   const isError =
     state === 'failed' || state === 'forbidden' || state === 'unauthenticated';
@@ -145,15 +160,9 @@ export function ListFeedback({
       <Empty
         role={isError ? 'alert' : 'status'}
         className='min-h-24 flex-row flex-none gap-2 rounded-none border-0 px-4 py-6 text-pretty text-card-foreground'
-        aria-busy={state === 'loading'}
       >
         <EmptyMedia className='mb-0 size-4 text-muted-foreground'>
-          <Icon
-            aria-hidden='true'
-            className={
-              state === 'loading' ? 'size-4 motion-safe:animate-spin' : 'size-4'
-            }
-          />
+          <Icon aria-hidden='true' className='size-4' />
         </EmptyMedia>
         <EmptyTitle className='text-sm font-medium text-muted-foreground'>
           {t(key, { defaultValue: fallback })}

package/client/components/loading.tsx

@@ -1,36 +1,147 @@
+import { usePendingFeedback } from '@nocobase/app-client';
 import { useTranslation } from '@nocobase/i18n/client';
 import type { ComponentPropsWithoutRef, ReactElement } from 'react';
-
-import { BrandLoadingMark } from '#components/brand-loading-mark';
 import { cn } from 'cn';
+import { BrandLoadingMark } from './brand-loading-mark.js';
 
 export interface LoadingProps extends ComponentPropsWithoutRef<'div'> {
   readonly fullscreen?: boolean;
+  readonly pending?: boolean;
+  readonly identity?: unknown;
   readonly label?: string;
+  readonly longWaitLabel?: string;
 }
 
-export function Loading(inputProps: LoadingProps): ReactElement {
+/** Mount inside the region that owns the work; fullscreen is for application startup. */
+export function Loading({
+  className,
+  fullscreen = false,
+  pending = true,
+  identity,
+  label,
+  longWaitLabel,
+  ...props
+}: LoadingProps): ReactElement {
   const { t } = useTranslation();
-  const {
-    className,
-    fullscreen = false,
-    label = t('status.loading', { defaultValue: 'Loading' }),
-    ...props
-  } = inputProps;
+  const feedback = usePendingFeedback(pending, identity);
+  const loadingLabel =
+    label ?? t('status.loading', { defaultValue: 'Loading' });
+  const waitingLabel =
+    longWaitLabel ??
+    t('pendingFeedback.longWait', {
+      defaultValue: 'This is taking longer than usual. You can keep waiting.',
+    });
+  const message = feedback.longWaiting ? waitingLabel : loadingLabel;
+  return (
+    <>
+      <div
+        {...props}
+        data-slot='loading'
+        aria-busy={pending}
+        className={cn(
+          'flex flex-col items-center justify-center',
+          fullscreen && 'min-h-svh w-full bg-background',
+          className,
+        )}
+      >
+        <div
+          aria-hidden='true'
+          className={cn(
+            'flex flex-col items-center gap-3 text-center',
+            !feedback.visible && 'invisible',
+          )}
+        >
+          <BrandLoadingMark />
+          <span className='grid text-sm text-muted-foreground'>
+            <span
+              className={cn(
+                'col-start-1 row-start-1',
+                feedback.longWaiting && 'invisible',
+              )}
+            >
+              {loadingLabel}
+            </span>
+            <span
+              className={cn(
+                'col-start-1 row-start-1',
+                !feedback.longWaiting && 'invisible',
+              )}
+            >
+              {waitingLabel}
+            </span>
+          </span>
+        </div>
+      </div>
+      {feedback.visible && (
+        <span
+          role='status'
+          aria-live='polite'
+          aria-label={message}
+          className='sr-only'
+        >
+          {message}
+        </span>
+      )}
+    </>
+  );
+}
 
+export interface RefreshIndicatorProps {
+  readonly pending: boolean;
+  readonly identity?: unknown;
+  readonly label?: string;
+  readonly longWaitLabel?: string;
+  readonly className?: string;
+}
+
+/**
+ * Background refresh of content that still belongs to the current query and permission scope. Render it inside the
+ * positioned element that owns that content; it takes no layout space and never replaces the content.
+ */
+export function RefreshIndicator({
+  pending,
+  identity,
+  label,
+  longWaitLabel,
+  className,
+}: RefreshIndicatorProps): ReactElement | null {
+  const { t } = useTranslation();
+  const feedback = usePendingFeedback(pending, identity);
+  if (!feedback.visible) return null;
+  const message = feedback.longWaiting
+    ? (longWaitLabel ??
+      t('pendingFeedback.longWait', {
+        defaultValue: 'This is taking longer than usual. You can keep waiting.',
+      }))
+    : (label ?? t('status.refreshing', { defaultValue: 'Refreshing' }));
   return (
     <div
-      aria-label={label}
+      data-slot='refresh-indicator'
       className={cn(
-        'flex flex-col items-center justify-center gap-3',
-        fullscreen && 'min-h-svh w-full bg-background',
+        'pointer-events-none absolute inset-x-0 top-0 z-10 flex flex-col items-end',
         className,
       )}
-      role='status'
-      {...props}
     >
-      <BrandLoadingMark />
-      <span className='text-sm text-muted-foreground'>{label}</span>
+      <div
+        aria-hidden='true'
+        className='h-0.5 w-full bg-primary/70 motion-safe:animate-pulse'
+      />
+      {feedback.longWaiting && (
+        <span
+          aria-hidden='true'
+          className='m-2 max-w-[calc(100%-1rem)] rounded-md border border-border bg-popover px-2 py-1 text-xs text-muted-foreground shadow-sm'
+        >
+          {message}
+        </span>
+      )}
+      <span
+        role='status'
+        aria-live='polite'
+        aria-label={message}
+        className='sr-only'
+      >
+        {message}
+      </span>
     </div>
   );
 }

package/client/components/pending-button.tsx

@@ -0,0 +1,111 @@
+import { usePendingFeedback } from '@nocobase/app-client';
+import { useTranslation } from '@nocobase/i18n/client';
+import {
+  useImperativeHandle,
+  useRef,
+  type ComponentProps,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+import { Tooltip } from '@base-ui/react/tooltip';
+import { cn } from 'cn';
+import { Button } from '#components/ui/button';
+import { BrandLoadingMark } from './brand-loading-mark.js';
+
+export interface PendingButtonProps extends Omit<
+  ComponentProps<typeof Button>,
+  'children' | 'className' | 'render' | 'nativeButton'
+> {
+  readonly busy: boolean;
+  readonly identity?: unknown;
+  readonly pendingLabel?: string;
+  readonly longWaitLabel?: string;
+  readonly children: ReactNode;
+  readonly className?: string;
+}
+
+/** Consume useSubmission().submitting; the submission controller still owns the lock. */
+export function PendingButton({
+  busy,
+  identity,
+  pendingLabel,
+  longWaitLabel,
+  children,
+  ref,
+  disabled,
+  className,
+  'aria-label': ariaLabel,
+  ...props
+}: PendingButtonProps): ReactElement {
+  const { t } = useTranslation();
+  const anchorRef = useRef<HTMLButtonElement>(null);
+  useImperativeHandle(ref, () => anchorRef.current!, []);
+  const feedback = usePendingFeedback(busy, identity);
+  const label =
+    pendingLabel ?? t('pendingFeedback.working', { defaultValue: 'Working…' });
+  const message = feedback.longWaiting
+    ? (longWaitLabel ??
+      t('pendingFeedback.longWait', {
+        defaultValue: 'This is taking longer than usual. You can keep waiting.',
+      }))
+    : label;
+  return (
+    <>
+      <Button
+        {...props}
+        ref={anchorRef}
+        disabled={disabled || busy}
+        aria-busy={busy}
+        aria-label={feedback.visible ? label : ariaLabel}
+        className={cn('motion-reduce:transition-none', className)}
+      >
+        <span className='grid'>
+          <span
+            className={cn(
+              'col-start-1 row-start-1 inline-flex items-center justify-center gap-1.5',
+              feedback.visible && 'invisible',
+            )}
+            aria-hidden={feedback.visible || undefined}
+          >
+            {children}
+          </span>
+          <span
+            className={cn(
+              'col-start-1 row-start-1 inline-flex items-center justify-center gap-1.5',
+              !feedback.visible && 'invisible',
+            )}
+            aria-hidden='true'
+          >
+            <BrandLoadingMark className='size-4 text-current' />
+            {label}
+          </span>
+        </span>
+      </Button>
+      <Tooltip.Root open={feedback.longWaiting}>
+        <Tooltip.Portal>
+          <Tooltip.Positioner
+            anchor={anchorRef}
+            side='top'
+            sideOffset={8}
+            collisionPadding={12}
+            // The hint only explains the wait; it must not block the controls it covers.
+            className='pointer-events-none z-50'
+          >
+            <Tooltip.Popup
+              data-slot='pending-hint'
+              aria-hidden='true'
+              className='max-w-64 rounded-md bg-foreground px-3 py-2 text-xs text-background shadow-md'
+            >
+              {message}
+            </Tooltip.Popup>
+          </Tooltip.Positioner>
+        </Tooltip.Portal>
+      </Tooltip.Root>
+      {feedback.visible && (
+        <span className='sr-only' role='status' aria-live='polite'>
+          {message}
+        </span>
+      )}
+    </>
+  );
+}

package/client/components/role-list.tsx

@@ -26,6 +26,11 @@ export interface RoleListProps {
     readonly custom: string;
   };
   readonly ariaLabel?: string;
+  /**
+   * The host is refreshing these current roles. Pass false while another
+   * control, such as a retry after a refresh failure, already announces the wait.
+   */
+  readonly loading?: boolean;
   readonly tableState?: Pick<
     DataTableProps<RoleListRole>,
     | 'paginationState'
@@ -41,6 +46,7 @@ export function RoleList({
   roles,
   labels,
   ariaLabel,
+  loading = false,
   tableState,
 }: RoleListProps): ReactElement {
   const columns = useMemo<ColumnDef<RoleListRole>[]>(
@@ -95,6 +101,7 @@ export function RoleList({
         data={roles}
         getRowId={(role) => role.key}
         showSelectedCount={false}
+        loading={loading}
       />
     </div>
   );

package/client/components/route-child-page.tsx

@@ -1,8 +1,15 @@
+import {
+  RouteChildPageHostContext,
+  type RouteChildPageHostValue,
+} from '@nocobase/app-client/route-containers';
 import {
   createContext,
   useContext,
   useEffect,
+  useLayoutEffect,
+  useMemo,
   useRef,
+  useState,
   type ReactElement,
   type ReactNode,
   type RefObject,
@@ -36,7 +43,58 @@ const EnclosingLayerContext =
  * the tab's outlet — anchors to the outer element: it covers this layer whole instead of scrolling out of sight with
  * the content once the user has scrolled this page.
  */
-export function RouteChildPage({
+export function RouteChildPage(props: RouteChildPageProps): ReactElement {
+  const host = useContext(RouteChildPageHostContext);
+  if (host) return <HostedRouteChildPage host={host} {...props} />;
+  return <RouteChildPageLayer {...props} />;
+}
+
+// Inside the layer the application opened, the page's `RouteChildPage` adds no second layer: its content renders in
+// that layer and its `className` moves onto it, so a migrated page keeps its layout.
+function HostedRouteChildPage({
+  host,
+  children,
+  className,
+}: RouteChildPageProps & {
+  readonly host: RouteChildPageHostValue;
+}): ReactElement {
+  useLayoutEffect(() => {
+    host.configure({ className });
+    return () => host.configure({});
+  }, [host, className]);
+  return (
+    <RouteChildPageHostContext.Provider value={null}>
+      {children}
+    </RouteChildPageHostContext.Provider>
+  );
+}
+
+/**
+ * The layer the application opens for a route that declares a `child-page` presentation, before the page module, its
+ * authorization check or its data are ready. Waiting, denial and failure render inside it; once the page renders, its
+ * own `RouteChildPage` contributes content to this layer. Everything the hosted page renders, including an outlet it
+ * places beside its `RouteChildPage`, is inside the layer, so a deeper child page covers this one whole.
+ */
+export function RouteChildPageHost({
+  children,
+}: {
+  readonly children?: ReactNode;
+}): ReactElement {
+  const [className, setClassName] = useState<string>();
+  const host = useMemo<RouteChildPageHostValue>(
+    () => ({ configure: (config) => setClassName(config.className) }),
+    [],
+  );
+  return (
+    <RouteChildPageLayer className={className}>
+      <RouteChildPageHostContext.Provider value={host}>
+        {children}
+      </RouteChildPageHostContext.Provider>
+    </RouteChildPageLayer>
+  );
+}
+
+function RouteChildPageLayer({
   children,
   className,
 }: RouteChildPageProps): ReactElement {
@@ -119,3 +177,16 @@ export function RouteChildPage({
     </div>
   );
 }
+
+/** Ends a `RouteChildPageHost`'s reach, so a route rendered inside one that is not hosted builds its own layer. */
+export function RouteChildPageHostBoundary({
+  children,
+}: {
+  readonly children?: ReactNode;
+}): ReactElement {
+  return (
+    <RouteChildPageHostContext.Provider value={null}>
+      {children}
+    </RouteChildPageHostContext.Provider>
+  );
+}