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

package/client/pages/settings/roles.tsx

@@ -12,7 +12,6 @@ import { PlusIcon } from 'lucide-react';
 import { PermissionManagementPage } from './permission-management-page.js';
 import { Input } from '#components/ui/input';
 import { Button } from '#components/ui/button';
-import { Spinner } from '#components/ui/spinner';
 import { useTableUrlState } from '#hooks/use-table-url-state';
 import { RoleList } from '#components/role-list';
 import { ListFeedback, ListFeedbackActions } from '#components/list-feedback';
@@ -123,34 +122,35 @@ export default function RolesPage(): ReactElement {
             state={listState}
             onClear={clearSearch}
             onRetry={request.reload}
-            busy={request.loading}
+            busy={active && request.loading}
           />
-          {active && request.loading && request.data ? (
-            <Spinner className='text-muted-foreground' />
-          ) : null}
         </div>
-        <ListFeedback state={listState}>
-          <RoleList
-            tableState={tableState}
-            ariaLabel={t('settings.roles')}
-            roles={rows.map((role) => ({
-              key: role.key,
-              title: text(role.title ?? role.key),
-              to: {
-                pathname: `${encodeURIComponent(role.key)}/edit`,
-                search: location.search,
-              },
-              protected: Boolean(role.protection),
-            }))}
-            labels={{
-              name: t('settings.roleName'),
-              key: t('settings.key'),
-              type: t('settings.roleType'),
-              protected: t('settings.protected'),
-              custom: t('settings.custom'),
-            }}
-          />
-        </ListFeedback>
+        {active || listState !== 'loading' ? (
+          <ListFeedback state={listState}>
+            <RoleList
+              tableState={tableState}
+              // After a refresh failure the toolbar's retry button owns the wait.
+              loading={active && request.loading && listState === 'ready'}
+              ariaLabel={t('settings.roles')}
+              roles={rows.map((role) => ({
+                key: role.key,
+                title: text(role.title ?? role.key),
+                to: {
+                  pathname: `${encodeURIComponent(role.key)}/edit`,
+                  search: location.search,
+                },
+                protected: Boolean(role.protection),
+              }))}
+              labels={{
+                name: t('settings.roleName'),
+                key: t('settings.key'),
+                type: t('settings.roleType'),
+                protected: t('settings.protected'),
+                custom: t('settings.custom'),
+              }}
+            />
+          </ListFeedback>
+        ) : null}
       </PermissionManagementPage>
       <Outlet context={{ reload: request.reload }} />
     </>

package/client/pages/settings/routes.ts

@@ -24,23 +24,27 @@ const systemSettingsRoutes: AppClientRouteContribution = defineAppRoutes([
     breadcrumb: { title: 'settings.users' },
     componentLoader: () => import('./users.js'),
     children: [
+      // The forms declare their presentation, so the dialog or drawer opens at once and the wait for the form's module,
+      // its authorization and its data stays inside it instead of under the list.
       {
         name: 'settingsUserCreate',
         path: 'create',
         authz: { resource: { type: 'user', id: '*' }, action: 'create' },
+        presentation: { kind: 'dialog', title: 'settings.newUser' },
         componentLoader: () => import('./user-form.js'),
       },
+      // A sibling rather than the parent of the editor, so closing the drawer returns to the list instead of to this
+      // route, which only forwards older detail links to the editor.
       {
         name: 'settingsUser',
         path: ':userId',
         componentLoader: () => import('./user-detail.js'),
-        children: [
-          {
-            name: 'settingsUserEdit',
-            path: 'edit',
-            componentLoader: () => import('./user-form.js'),
-          },
-        ],
+      },
+      {
+        name: 'settingsUserEdit',
+        path: ':userId/edit',
+        presentation: { kind: 'drawer', title: 'settings.editUser' },
+        componentLoader: () => import('./user-form.js'),
       },
     ],
   },
@@ -80,12 +84,14 @@ const systemSettingsRoutes: AppClientRouteContribution = defineAppRoutes([
               action: 'create',
             },
             breadcrumb: { title: 'settings.newRole' },
+            presentation: { kind: 'child-page' },
             componentLoader: () => import('./role-form.js'),
           },
           {
             name: 'settingsRoleEdit',
             path: ':key/edit',
             breadcrumb: { title: 'settings.editRole' },
+            presentation: { kind: 'child-page' },
             componentLoader: () => import('./role-form.js'),
           },
         ],
@@ -119,6 +125,7 @@ const systemSettingsRoutes: AppClientRouteContribution = defineAppRoutes([
               action: 'create',
             },
             breadcrumb: { title: 'settings.defaultAccess.new' },
+            presentation: { kind: 'child-page' },
             componentLoader: () => import('./default-access-form.js'),
           },
           // Read permission opens the full rule even when the viewer may not update it.
@@ -126,6 +133,7 @@ const systemSettingsRoutes: AppClientRouteContribution = defineAppRoutes([
             name: 'settingsDefaultAccessEdit',
             path: ':key/edit',
             breadcrumb: { title: 'settings.defaultAccess.edit' },
+            presentation: { kind: 'child-page' },
             componentLoader: () => import('./default-access-form.js'),
           },
         ],

package/client/pages/settings/user-detail.tsx

@@ -1,24 +1,10 @@
 import type { ReactElement } from 'react';
-import {
-  Navigate,
-  useLocation,
-  useOutlet,
-  useOutletContext,
-  useResolvedPath,
-} from 'react-router';
-import type { ManagedUser } from '@nocobase/app-plugin-users/client/user-client';
+import { Navigate, useLocation } from 'react-router';
 
-/** Keep stored route identifiers and old detail links while using one editor. */
+/** Keeps stored route identifiers and old detail links working by forwarding them to the editor. */
 export default function UserDetail(): ReactElement {
-  const parent = useOutletContext<{
-    reload: (updated?: ManagedUser) => void;
-  }>();
   const location = useLocation();
-  const listPath = useResolvedPath('..').pathname;
-  const outlet = useOutlet({ ...parent, listPath });
   return (
-    outlet ?? (
-      <Navigate to={{ pathname: 'edit', search: location.search }} replace />
-    )
+    <Navigate to={{ pathname: 'edit', search: location.search }} replace />
   );
 }

package/client/pages/settings/user-form.tsx

@@ -1,3 +1,4 @@
+import { PendingButton } from '#components/pending-button';
 import { FeedbackForm } from '#components/feedback-form';
 import { useAuthentication } from '@nocobase/app-plugin-authentication/client';
 import { useSubmission } from '@nocobase/app-client';
@@ -197,7 +198,6 @@ function UserEditor(): ReactElement {
   const location = useLocation();
   const parent = useOutletContext<{
     reload: (updated?: ManagedUser) => void;
-    listPath?: string;
   }>();
   const data = useSettingsData<{ data: ManagedUser }>(
     userId ? `users/${encodeURIComponent(userId)}` : 'users/options',
@@ -281,11 +281,8 @@ function UserEditor(): ReactElement {
   const [serverErrors, setServerErrors] = useState<Record<string, string>>({});
   const [submitted, setSubmitted] = useState(false);
 
-  const parentPath = useResolvedPath('..').pathname;
-  const closeTo = {
-    pathname: creating ? parentPath : (parent.listPath ?? parentPath),
-    search: location.search,
-  };
+  const listPath = useResolvedPath('..').pathname;
+  const closeTo = { pathname: listPath, search: location.search };
   const fieldError = (name: keyof typeof fields): string | undefined => {
     if (!submitted) return;
     if (serverErrors[name]) return serverErrors[name];
@@ -436,7 +433,9 @@ function UserEditor(): ReactElement {
         {t('settings.cancel')}
       </Button>
       {allowed && (
-        <Button
+        <PendingButton
+          busy={busy}
+          pendingLabel={t('settings.saving')}
           form={formId}
           type='submit'
           disabled={
@@ -455,14 +454,8 @@ function UserEditor(): ReactElement {
               (options.loading || Boolean(options.error) || !options.data))
           }
         >
-          {t(
-            busy
-              ? 'settings.saving'
-              : creating
-                ? 'settings.create'
-                : 'settings.save',
-          )}
-        </Button>
+          {t(creating ? 'settings.create' : 'settings.save')}
+        </PendingButton>
       )}
     </>
   );
@@ -475,6 +468,7 @@ function UserEditor(): ReactElement {
       ) : (
         !data.error && (
           <FeedbackForm
+            aria-busy={busy}
             submitting={busy}
             error={error}
             errorContent={<SettingsError error={error} inline />}

package/client/pages/settings/users.tsx

@@ -31,12 +31,12 @@ import {
 } from 'react';
 import { Link, Outlet, useLocation, useResolvedPath } from 'react-router';
 import { PlusIcon } from 'lucide-react';
+import { cn } from 'cn';
 import { PageContainer } from '#components/page-container';
 import { PageHeader } from '#components/page-header';
 import { Button } from '#components/ui/button';
 import { Input } from '#components/ui/input';
 import { StatusBadge } from '#components/status-badge';
-import { Spinner } from '#components/ui/spinner';
 import {
   Select,
   SelectTrigger,
@@ -46,25 +46,6 @@ import {
 } from '#components/ui/select';
 import { ConfirmAction, SettingsError } from './shared.js';
 
-function UsersRefreshing(): ReactElement | null {
-  const { t } = useTranslation();
-  const [visible, setVisible] = useState(false);
-  useEffect(() => {
-    // Fast background reads should not flash feedback on overlay close.
-    const timer = setTimeout(() => setVisible(true), 300);
-    return () => clearTimeout(timer);
-  }, []);
-  return visible ? (
-    <span
-      role='status'
-      className='flex items-center gap-2 text-sm text-muted-foreground'
-    >
-      <Spinner aria-hidden='true' className='size-4' />
-      {t('settings.loading')}
-    </span>
-  ) : null;
-}
-
 function UserName({ user }: { readonly user: ManagedUser }): ReactElement {
   const canUpdate = useUserPermission('update', user.id);
   const canAssign = useUserPermission('assign-role', user.id);
@@ -515,11 +496,6 @@ export default function UsersPage(): ReactElement {
               {t('settings.clear')}
             </Button>
           )}
-          <div className='ml-auto flex h-8 w-28 items-center justify-end'>
-            {active && hasCurrentResponse && request.loading && request.data ? (
-              <UsersRefreshing />
-            ) : null}
-          </div>
         </div>
         {Boolean(roleScope) !== Boolean(role) && (
           <p role='alert' className='text-sm text-destructive'>
@@ -536,13 +512,21 @@ export default function UsersPage(): ReactElement {
           {...tableState}
           manualSorting
           showSelectedCount={false}
-          loading={request.loading}
+          loading={active && request.loading}
+          loadingIdentity={requestPath}
           listState={listState}
           onRetry={request.reload}
           onClearFilters={clearFilters}
         />
         {request.data && (
-          <p className='text-sm text-muted-foreground'>
+          // A previous query's total keeps its line but is never shown as the current one.
+          <p
+            className={cn(
+              'text-sm text-muted-foreground',
+              !hasCurrentResponse && 'invisible',
+            )}
+            aria-hidden={!hasCurrentResponse || undefined}
+          >
             {t('settings.total', { count: request.data.meta.total })}
           </p>
         )}

package/client/routing/client-route.tsx

@@ -1,22 +1,51 @@
 import { useTranslation } from '@nocobase/i18n/client';
+import { useNavigationGuard } from '@nocobase/app-client';
 import type {
   AppClientRegisteredRoute,
   AppClientRouteComponentModule,
 } from '@nocobase/app-client/plugins';
 import { useCan } from '@nocobase/app-plugin-authorization/client';
 import { NamespaceScope } from '@nocobase/i18n/client';
-import { Activity, type ReactElement, useEffect, useState } from 'react';
+import {
+  Activity,
+  type ReactElement,
+  type ReactNode,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+} from 'react';
 import { ErrorBoundary } from 'react-error-boundary';
 
 import { Loading } from '#components/loading';
+import {
+  RouteChildPageHost,
+  RouteChildPageHostBoundary,
+} from '#components/route-child-page';
+import {
+  RouteOverlayHost,
+  RouteOverlayHostBoundary,
+} from '#components/route-overlay';
 import { Button } from '#components/ui/button';
+import { cn } from 'cn';
 
 export interface ClientRouteProps {
   readonly route: AppClientRegisteredRoute;
 }
 
+// Where a route's waiting, denial and failure render: the content area for a page, or the container the application
+// opened for a declared child page, dialog or drawer. A route without a presentation keeps the page-sized placeholder.
+type ClientRouteRegion = 'page' | 'child-page' | 'overlay';
+
+const REGION_CLASS_NAMES: Record<ClientRouteRegion, string> = {
+  page: 'min-h-[calc(100svh-4rem)]',
+  'child-page': 'min-h-full',
+  overlay: 'min-h-40',
+};
+
 export function ClientRoute({ route }: ClientRouteProps): ReactElement {
-  const { authz, componentLoader } = route;
+  const { t } = useTranslation();
+  const { authz, componentLoader, presentation } = route;
   const checkAccess = authz !== 'skip';
   const { can: allowed, isPending: accessLoading } = useCan(
     authz === 'skip' ? undefined : authz,
@@ -24,14 +53,33 @@ export function ClientRoute({ route }: ClientRouteProps): ReactElement {
   const [componentModule, setComponentModule] =
     useState<AppClientRouteComponentModule>();
   const [loadError, setLoadError] = useState<unknown>();
+  const [attempt, setAttempt] = useState(0);
+  const [renderFailed, setRenderFailed] = useState(false);
+  const loadedRef = useRef<
+    | {
+        loader: typeof componentLoader;
+        attempt: number;
+      }
+    | undefined
+  >(undefined);
 
   useEffect(() => {
     if (checkAccess && !allowed) return;
+    // Activity reconnects Effects after a parent permission recheck. Keep the loaded component's identity:
+    // loaders that wrap a module (for example, withNamespace) can return a new component on every call.
+    if (
+      loadedRef.current &&
+      loadedRef.current.loader === componentLoader &&
+      loadedRef.current.attempt === attempt
+    )
+      return;
+    loadedRef.current = undefined;
     let active = true;
 
     componentLoader!().then(
       (module) => {
         if (active) {
+          loadedRef.current = { loader: componentLoader, attempt };
           setComponentModule(module);
           setLoadError(undefined);
         }
@@ -46,44 +94,126 @@ export function ClientRoute({ route }: ClientRouteProps): ReactElement {
     return () => {
       active = false;
     };
-  }, [allowed, checkAccess, componentLoader]);
-
-  if (loadError) {
-    return <ClientPageError route={route} />;
-  }
+  }, [allowed, attempt, checkAccess, componentLoader]);
 
-  if (checkAccess && !accessLoading && !allowed)
-    return <ClientPageDenied route={route} />;
+  // Retries only this route's module, so the pages around it keep their drafts and scroll positions.
+  const retryLoad = useCallback(() => {
+    setLoadError(undefined);
+    setAttempt((value) => value + 1);
+  }, []);
 
-  if (!componentModule) {
-    return <ClientPageLoading />;
-  }
+  const kind = presentation?.kind;
+  const region: ClientRouteRegion =
+    kind === 'dialog' || kind === 'drawer'
+      ? 'overlay'
+      : kind === 'child-page'
+        ? 'child-page'
+        : 'page';
+  const checking = checkAccess && accessLoading;
+  const denied = checkAccess && !accessLoading && !allowed;
+  const Component = componentModule?.default;
+  const [mounted, setMounted] = useState(false);
+  const present = Boolean(Component) && !denied && !loadError && !renderFailed;
+  if (!checking && mounted !== present) setMounted(present);
+  const rechecking = checking && mounted && !loadError && !renderFailed;
+  // Activity disconnects form effects, including dirty registrations. This guard stays outside it and refuses
+  // route departures until the page's effects reconnect; settled denial still unmounts the protected page.
+  useNavigationGuard(() => !rechecking);
+  useEffect(() => {
+    if (!rechecking) return;
+    const warn = (event: BeforeUnloadEvent): void => {
+      event.preventDefault();
+      event.returnValue = '';
+    };
+    window.addEventListener('beforeunload', warn);
+    return () => window.removeEventListener('beforeunload', warn);
+  }, [rechecking]);
 
-  const Component = componentModule.default;
+  let content: ReactNode;
+  // A settled denial wins over an older load failure: the viewer may not see this page at all.
+  if (denied) content = <ClientPageDenied route={route} region={region} />;
+  else if (loadError)
+    content = (
+      <ClientPageError
+        route={route}
+        region={region}
+        onRetry={retryLoad}
+        retried={attempt > 0}
+      />
+    );
+  else if (!Component) content = <ClientPageLoading region={region} />;
+  else
+    content = (
+      <>
+        {checking ? <ClientPageLoading region={region} /> : null}
+        {/* Conceal a previously allowed page during rechecks without discarding its draft. A denial unmounts it. */}
+        <Activity mode={checking ? 'hidden' : 'visible'}>
+          <ErrorBoundary
+            onError={() => setRenderFailed(true)}
+            onReset={() => setRenderFailed(false)}
+            fallbackRender={({ resetErrorBoundary }) => (
+              <ClientPageError
+                route={route}
+                region={region}
+                onRetry={resetErrorBoundary}
+              />
+            )}
+          >
+            {/* The owning package is the page's namespace, so a plugin page translates with a bare useTranslation(). */}
+            <NamespaceScope ns={route.packageName}>
+              <Component />
+            </NamespaceScope>
+          </ErrorBoundary>
+        </Activity>
+      </>
+    );
 
-  const checking = checkAccess && accessLoading;
+  if (kind === 'dialog' || kind === 'drawer') {
+    const title = presentation!.title!;
+    return (
+      <RouteChildPageHostBoundary>
+        <RouteOverlayHost
+          drawer={kind === 'drawer'}
+          title={t(title, {
+            ns: presentation!.namespace ?? route.packageName,
+            defaultValue: title,
+          })}
+          ready={mounted && !denied && !loadError && !renderFailed}
+          concealed={checking}
+        >
+          {content}
+        </RouteOverlayHost>
+      </RouteChildPageHostBoundary>
+    );
+  }
+  if (kind === 'child-page')
+    return (
+      <RouteOverlayHostBoundary>
+        <RouteChildPageHost>{content}</RouteChildPageHost>
+      </RouteOverlayHostBoundary>
+    );
+  // A page that is not hosted builds its own container, including one rendered through a hosted page's outlet.
   return (
-    <>
-      {checking ? <ClientPageLoading /> : null}
-      {/* Conceal a previously allowed page during rechecks without discarding its draft. A denial unmounts it. */}
-      <Activity mode={checking ? 'hidden' : 'visible'}>
-        <ErrorBoundary fallback={<ClientPageError route={route} />}>
-          {/* The owning package is the page's namespace, so a plugin page translates with a bare useTranslation(). */}
-          <NamespaceScope ns={route.packageName}>
-            <Component />
-          </NamespaceScope>
-        </ErrorBoundary>
-      </Activity>
-    </>
+    <RouteOverlayHostBoundary>
+      <RouteChildPageHostBoundary>{content}</RouteChildPageHostBoundary>
+    </RouteOverlayHostBoundary>
   );
 }
 
-function ClientPageDenied(inputProps: ClientRouteProps): ReactElement {
+interface ClientRouteStateProps extends ClientRouteProps {
+  readonly region: ClientRouteRegion;
+}
+
+function ClientPageDenied({
+  route,
+  region,
+}: ClientRouteStateProps): ReactElement {
   const { t } = useTranslation();
-  const { route } = inputProps;
 
   return (
-    <section className='grid min-h-[calc(100svh-4rem)] place-items-center px-6'>
+    <section
+      className={cn('grid place-items-center px-6', REGION_CLASS_NAMES[region])}
+    >
       <section className='w-full max-w-lg space-y-3 text-center'>
         <h1 className='text-xl font-semibold'>
           {t('status.denied', { defaultValue: 'Access denied' })}
@@ -99,23 +229,40 @@ function ClientPageDenied(inputProps: ClientRouteProps): ReactElement {
   );
 }
 
-function ClientPageLoading(): ReactElement {
+function ClientPageLoading({
+  region,
+}: {
+  readonly region: ClientRouteRegion;
+}): ReactElement {
   const { t } = useTranslation();
 
   return (
     <Loading
-      className='min-h-[calc(100svh-4rem)]'
+      className={REGION_CLASS_NAMES[region]}
       label={t('status.loadingPage', { defaultValue: 'Loading page' })}
     />
   );
 }
 
-function ClientPageError(inputProps: ClientRouteProps): ReactElement {
+function ClientPageError({
+  route,
+  region,
+  onRetry,
+  retried = false,
+}: ClientRouteStateProps & {
+  readonly onRetry: () => void;
+  /**
+   * Set once a retry of the module failed too. A browser may keep answering a failed module import from its module
+   * map without fetching again, so the full reload that does fetch it becomes the second way out.
+   */
+  readonly retried?: boolean;
+}): ReactElement {
   const { t } = useTranslation();
-  const { route } = inputProps;
 
   return (
-    <section className='grid min-h-[calc(100svh-4rem)] place-items-center px-6'>
+    <section
+      className={cn('grid place-items-center px-6', REGION_CLASS_NAMES[region])}
+    >
       <section className='w-full max-w-lg space-y-4 text-center'>
         <h1 className='text-xl font-semibold'>
           {t('status.pageFailed', { defaultValue: 'Unable to load page' })}
@@ -127,9 +274,24 @@ function ClientPageError(inputProps: ClientRouteProps): ReactElement {
             defaultValue: `Route ${route.name} from ${route.packageName} could not be loaded.`,
           })}
         </p>
-        <Button onClick={() => window.location.reload()}>
-          {t('status.retry', { defaultValue: 'Retry' })}
-        </Button>
+        {retried && (
+          <p className='text-sm text-muted-foreground'>
+            {t('status.retryFailedDescription', {
+              defaultValue:
+                'It still could not be loaded. Reloading the whole page may help; unsaved changes on this page may be lost.',
+            })}
+          </p>
+        )}
+        <div className='flex flex-wrap justify-center gap-2'>
+          <Button onClick={onRetry}>
+            {t('status.retry', { defaultValue: 'Retry' })}
+          </Button>
+          {retried && (
+            <Button variant='outline' onClick={() => window.location.reload()}>
+              {t('status.reloadPage', { defaultValue: 'Reload page' })}
+            </Button>
+          )}
+        </div>
       </section>
     </section>
   );

package/client/routing/navigation-destination.ts

@@ -0,0 +1,42 @@
+import type { AppClientRegisteredRoute } from '@nocobase/app-client/plugins';
+import { parsePath, type To, type Path } from 'react-router';
+
+import type { RouteAccess } from './route-context.js';
+import { matchRouteTree, routeKey } from './route-navigation.js';
+
+/** Only application-absolute, registered, authorized pages can be navigation destinations. */
+export function navigationDestination(
+  to: To,
+  routes: readonly AppClientRegisteredRoute[],
+  access: RouteAccess,
+): Partial<Path> | undefined {
+  if (access.loading) return undefined;
+  const path = typeof to === 'string' ? parsePath(to) : to;
+  const pathname = path.pathname;
+  if (
+    !pathname ||
+    !pathname.startsWith('/') ||
+    pathname.startsWith('//') ||
+    pathname.includes('\\') ||
+    [...pathname].some((character) => character.charCodeAt(0) <= 32)
+  )
+    return undefined;
+  // Do not normalize dot segments or malformed escapes into a different authorized route.
+  try {
+    if (
+      pathname
+        .split('/')
+        .some((segment) => ['.', '..'].includes(decodeURIComponent(segment)))
+    )
+      return undefined;
+  } catch {
+    return undefined;
+  }
+  const matches = matchRouteTree(routes, pathname);
+  if (
+    !matches?.at(-1)?.route.componentLoader ||
+    matches.some(({ route }) => access.denied.has(routeKey(route)))
+  )
+    return undefined;
+  return { pathname, search: path.search ?? '', hash: path.hash ?? '' };
+}