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

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>
+  );
+}

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>
+  );
+}