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

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/routes.ts

@@ -1,4 +1,8 @@
+import { createAppClientConfig } from '@nocobase/app-client';
+import { readAppClientRuntimeConfig } from '@nocobase/app-client/runtime';
+import { includeNotificationTemplateRoutes } from './pages/settings/notification-routes.js';
 import { Home } from 'lucide-react';
+import settingsShellRoutes from './pages/settings/shell-routes.js';
 import {
   defineAppRoutes,
   type AppClientRouteContribution,
@@ -64,6 +68,18 @@ const appRoutes: AppClientRouteContribution = defineAppRoutes([
   },
 ]);
 
-const routes: readonly AppClientRouteContribution[] = [appRoutes];
+// The System settings shell stays registered: it shows only the modules a viewer may open, and none until the
+// application or its plugins contribute one. Business administration such as `./pages/settings/routes.js` joins it.
+export function createApplicationRoutes(
+  rawConfig: unknown = readAppClientRuntimeConfig(),
+): readonly AppClientRouteContribution[] {
+  const config = createAppClientConfig({ rawConfig });
+  return includeNotificationTemplateRoutes(
+    [appRoutes, settingsShellRoutes],
+    config.get<boolean>('notificationTemplates.invitationConfigured') === true,
+  );
+}
+
+const routes: readonly AppClientRouteContribution[] = createApplicationRoutes();
 
 export default routes;

package/client/routing/app-router.tsx

@@ -6,9 +6,8 @@ import type { AppClientRegisteredRoute } from '@nocobase/app-client/plugins';
 import { useMemo, type ReactElement } from 'react';
 import { Navigate, Outlet, Route, Routes } from 'react-router';
 
-import { EMPTY_ARRAY } from '#lib/constants';
-
 import { AppLayout } from '../layouts/app-layout.js';
+import { filterRouteTree } from './route-navigation.js';
 import { renderRouteTree } from './route-tree.js';
 import { StandalonePageLayout } from './standalone-page-layout.js';
 import { SessionPreparation } from './session-preparation.js';
@@ -66,15 +65,3 @@ export function AppRouter({ clientRoutes }: AppRouterProps): ReactElement {
     </Routes>
   );
 }
-
-/** Pure groups can span shells; a page and its descendants always share their shell. */
-function filterRouteTree(
-  routes: readonly AppClientRegisteredRoute[],
-  predicate: (route: AppClientRegisteredRoute) => boolean,
-): AppClientRegisteredRoute[] {
-  return routes.flatMap((route) => {
-    if (route.componentLoader) return predicate(route) ? [route] : [];
-    const children = filterRouteTree(route.children ?? EMPTY_ARRAY, predicate);
-    return children.length ? [{ ...route, children }] : [];
-  });
-}

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 { 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,37 +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) return <ClientPageLoading />;
-  if (checkAccess && !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>
+      </>
+    );
 
+  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 (
-    <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>
+    <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' })}
@@ -92,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' })}
@@ -120,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 ?? '' };
+}

package/client/routing/route-context.tsx

@@ -37,8 +37,32 @@ export function useRouteSearches(): ReadonlyMap<string, string> {
 }
 
 const RouteTreeContext = createContext<readonly AppClientRegisteredRoute[]>([]);
+
+/** The shell's page permission check (`useRouteNavigation`), shared so pages reuse it instead of checking again. */
+export interface RouteAccess {
+  /** Route keys the viewer may not open. */
+  readonly denied: ReadonlySet<string>;
+  /** The check is still running; `denied` is not yet known. */
+  readonly loading: boolean;
+}
+
+const DEFAULT_ACCESS: RouteAccess = { denied: new Set(), loading: false };
+const RouteAccessContext = createContext<RouteAccess>(DEFAULT_ACCESS);
+
 export interface RouteTreeProviderProps extends PropsWithChildren {
   readonly routes: readonly AppClientRegisteredRoute[];
+  /** The shell's page permission result; without it every route counts as open. */
+  readonly access?: RouteAccess;
+}
+
+/** The registered business route tree the shell renders. */
+export function useRouteTree(): readonly AppClientRegisteredRoute[] {
+  return useContext(RouteTreeContext);
+}
+
+/** Which routes the viewer may open, from the shell's single permission check. */
+export function useRouteAccess(): RouteAccess {
+  return useContext(RouteAccessContext);
 }
 
 /**
@@ -51,6 +75,7 @@ export interface RouteTreeProviderProps extends PropsWithChildren {
 export function RouteTreeProvider({
   children,
   routes,
+  access,
 }: RouteTreeProviderProps): ReactElement {
   const location = useLocation();
   const pathname = location.pathname.replace(/\/+$/u, '') || '/';
@@ -74,9 +99,11 @@ export function RouteTreeProvider({
   }
   return (
     <RouteTreeContext.Provider value={routes}>
-      <RouteSearchContext.Provider value={queries}>
-        {children}
-      </RouteSearchContext.Provider>
+      <RouteAccessContext.Provider value={access ?? DEFAULT_ACCESS}>
+        <RouteSearchContext.Provider value={queries}>
+          {children}
+        </RouteSearchContext.Provider>
+      </RouteAccessContext.Provider>
     </RouteTreeContext.Provider>
   );
 }