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

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

@@ -1,4 +1,5 @@
 import foundation from '@nocobase/app-plugin-foundation/client';
+import applicationManifest from '../package.json' with { type: 'json' };
 import defaultAccess from '@nocobase/app-plugin-authz-default-access/client';
 import sharingRules from '@nocobase/app-plugin-authz-sharing-rules/client';
 import restrictionRules from '@nocobase/app-plugin-authz-restriction-rules/client';
@@ -35,7 +36,13 @@ const clientPlugins: AppClientPlugins = defineClientPlugins([
   file(),
   scheduler(),
   mail(),
-  foundation({ settingsGroup: true }),
+  // The manifest is what the capability guide lists: every plugin this application declares.
+  foundation({
+    settingsGroup: true,
+    manifest: applicationManifest,
+    guideSettingsPath: '/settings',
+    navigation: false,
+  }),
 ]);
 
 export default clientPlugins;

package/client/routes.ts

@@ -1,3 +1,4 @@
+import databaseExplorerRoutes from './pages/settings/database-explorer/routes.js';
 import { createAppClientConfig } from '@nocobase/app-client';
 import { readAppClientRuntimeConfig } from '@nocobase/app-client/runtime';
 import { includeNotificationTemplateRoutes } from './pages/settings/notification-routes.js';
@@ -75,7 +76,7 @@ export function createApplicationRoutes(
 ): readonly AppClientRouteContribution[] {
   const config = createAppClientConfig({ rawConfig });
   return includeNotificationTemplateRoutes(
-    [appRoutes, settingsShellRoutes],
+    [appRoutes, settingsShellRoutes, databaseExplorerRoutes],
     config.get<boolean>('notificationTemplates.invitationConfigured') === true,
   );
 }

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 ?? '' };
+}

package/client/routing/route-leave-boundary.tsx

@@ -95,6 +95,7 @@ class LeaveController {
 class LeaveScope {
   private readonly entries = new Set<LeaveController>();
   private hidden = false;
+  private generation = 0;
   constructor(private readonly dirtyChanged: (dirty: boolean) => void) {}
 
   changed = (): void => {
@@ -118,7 +119,12 @@ class LeaveScope {
     this.changed();
   }
   update(hidden: boolean, pathname: string): void {
-    this.hidden = hidden;
+    if (this.hidden !== hidden) {
+      this.generation += 1;
+      this.hidden = hidden;
+      // A confirmation started before concealment must not discard or resume its old navigation on recovery.
+      if (hidden) for (const entry of this.entries) entry.cancel();
+    }
     for (const entry of this.entries) {
       if (pathname !== entry.origin && !pathname.startsWith(`${entry.origin}/`))
         this.remove(entry);
@@ -130,8 +136,14 @@ class LeaveScope {
       for (const entry of this.entries) if (!entry.active) this.remove(entry);
   }
   guard = (): Decision => {
+    const generation = this.generation;
     const remaining = [...this.entries];
     const next = (): Decision => {
+      if (
+        generation !== this.generation ||
+        (this.hidden && this.entries.size > 0)
+      )
+        return false;
       const entry = remaining.shift();
       if (!entry) return true;
       const value = entry.guard();

package/client/styles.css

@@ -252,9 +252,26 @@ label:has(> .sr-only:focus-visible),
 :is([data-slot='dialog-description'], [data-slot='alert-dialog-description']) {
   line-height: 1.65;
 }
-:is([data-slot='dialog-footer'], [data-slot='alert-dialog-footer']) > button {
+/* Size semantic actions equally, including Button render={<Link />} and the
+   AlertDialog wrappers, which replace Button's slot. Footer sizing takes
+   precedence over primitive size utilities; long labels may grow and wrap. */
+:is([data-slot='dialog-footer'], [data-slot='alert-dialog-footer'])
+  > :is(
+    [data-slot='button'],
+    [data-slot='dialog-close'],
+    [data-slot='alert-dialog-action'],
+    [data-slot='alert-dialog-cancel']
+  ) {
+  height: auto;
   min-height: calc(var(--spacing) * 10);
+  min-width: 0;
+  align-self: stretch;
+  flex-shrink: 1;
+  padding-block: calc(var(--spacing) * 2);
   padding-inline: calc(var(--spacing) * 4);
+  white-space: normal;
+  overflow-wrap: anywhere;
+  text-align: center;
 }
 /* Route overlays compose the dialog primitives, so their close button sits where a dialog's does. */
 :is([data-slot='dialog-content'], [data-slot='route-overlay-content'])

package/config.example.yml

@@ -22,13 +22,19 @@
 #     max: 600
 #     window: 1m
 
-# Realtime events are transient and local to this process. Clients refetch after subscription acknowledgement.
+# Realtime defaults to inMemory when broker is omitted. An explicit broker requires adapter.
+# For local-only selection: realtime: { broker: { adapter: inMemory } }.
+# For multiple processes, install @nocobase/app-plugin-realtime-redis and register its
+# @nocobase/app-plugin-realtime-redis/server definition in server/plugins.ts on every instance.
+# Realtime events are transient; clients refetch after subscription acknowledgement.
 # realtime:
-#   adapter: inMemory # Use redis for multiple application processes.
-#   redis:
+#   broker:
+#     adapter: redis
+#     setupTimeoutMs: 5000
 #     connection:
 #       host: 127.0.0.1
 #       port: 6379
+#       commandTimeout: 5000
 #   namespace: my-app # Defaults to the application name; keep applications isolated.
 #   authorizationTimeoutMs: 5000
 #   sessionCheckIntervalMs: 30000
@@ -116,8 +122,7 @@ auth:
   # Set app.publicOrigin before explicitly enabling automatic password recovery.
   # passwordReset:
   #   enabled: true
-  # email:
-  #   mailer: system # omit to use mailers.default
+  #   mailer: system # omit to preserve existing default selection
   # Existing inline auth.email and AUTH_EMAIL_* remain supported for compatibility.
   emailAndPassword:
     enabled: true
@@ -190,12 +195,13 @@ snowflake:
 # Upgrading deployments must set adapter: redis explicitly; templates no longer supply Redis defaults.
 # jobs:
 #   default: redis
-#   redis:
-#     adapter: redis
-#     connection:
-#       host: 127.0.0.1
-#       port: 6379
-#     # namespace: my-app # defaults to the application name; set it when deployments share one Redis
+#   backends:
+#     redis:
+#       adapter: redis
+#       connection:
+#         host: 127.0.0.1
+#         port: 6379
+#       # namespace: my-app # defaults to the application name; set it when deployments share one Redis
 
 # The jobs configuration the Scheduler plugin's schedules run on, by name. Left out, they follow jobs.default.
 # scheduler:

package/index.html

@@ -32,9 +32,6 @@
         transform-origin: 32px 32px;
         animation: app-bootstrap-spin 1.1s linear infinite;
       }
-      .app-bootstrap-loading span {
-        color: oklch(0.556 0 0);
-      }
 
       html,
       body {
@@ -60,11 +57,6 @@
         }
       }
 
-      @media (prefers-color-scheme: dark) {
-        .app-bootstrap-loading span {
-          color: oklch(0.708 0 0);
-        }
-      }
       @media (prefers-reduced-motion: reduce) {
         .app-bootstrap-loading .nocobase-loading-orbit {
           animation: none;
@@ -76,10 +68,16 @@
   <body>
     <noscript>You need to enable JavaScript to run this app.</noscript>
     <div id="root">
+      <!--
+        The language is unknown until the client starts, so this placeholder shows no text. A screen reader still
+        perceives it as an indeterminate progress bar, a role it announces in its own language, named after the
+        brand in <title>, which reads the same in every language. The client's localized loading, a polite status,
+        replaces it once the language is ready, so nothing is announced twice.
+      -->
       <div
         class="app-bootstrap-loading"
-        role="status"
-        aria-label="Loading application"
+        role="progressbar"
+        aria-label="NocoBase"
       >
         <svg
           data-slot="loading-indicator"
@@ -114,7 +112,6 @@
             </g>
           </g>
         </svg>
-        <span>Loading application…</span>
       </div>
     </div>
     <script type="module" src="/client/index.tsx"></script>