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

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

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

@@ -0,0 +1,249 @@
+import { useNavigationGuard } from '@nocobase/app-client';
+import { useTranslation } from '@nocobase/i18n/client';
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useState,
+  type PropsWithChildren,
+  type ReactElement,
+} from 'react';
+import { useLocation } from 'react-router';
+import { ConfirmAction } from '../pages/settings/shared.js';
+
+/* eslint-disable react-refresh/only-export-components -- the route boundary and its hook share one context */
+
+type Decision = boolean | Promise<boolean>;
+interface Prompt {
+  readonly owner: LeaveController;
+  readonly title: string;
+  readonly description: string;
+}
+
+class LeaveController {
+  dirty = false;
+  busy = false;
+  active = false;
+  private allowed = false;
+  private pending?: {
+    promise: Promise<boolean>;
+    resolve: (value: boolean) => void;
+  };
+
+  constructor(
+    readonly origin: string,
+    private readonly show: (prompt: Prompt | undefined) => void,
+  ) {}
+
+  title = '';
+  description = '';
+  onDiscard?: () => void;
+
+  update(
+    dirty: boolean,
+    busy: boolean,
+    onDiscard: (() => void) | undefined,
+    title: string,
+    description: string,
+  ): void {
+    this.dirty = dirty;
+    this.busy = busy;
+    this.onDiscard = onDiscard;
+    this.title = title;
+    this.description = description;
+  }
+
+  guard = (): Decision => {
+    if (this.allowed) return true;
+    if (this.busy) return false;
+    if (!this.dirty) return true;
+    if (!this.pending) {
+      let resolve!: (value: boolean) => void;
+      const promise = new Promise<boolean>((done) => {
+        resolve = done;
+      });
+      this.pending = { promise, resolve };
+      this.show({
+        owner: this,
+        title: this.title,
+        description: this.description,
+      });
+    }
+    return this.pending.promise;
+  };
+
+  decide(value: boolean): void {
+    if (value) this.onDiscard?.();
+    this.allowed = value;
+    this.pending?.resolve(value);
+    this.pending = undefined;
+    this.show(undefined);
+  }
+
+  allow = (): void => {
+    this.allowed = true;
+  };
+  reset(): void {
+    this.allowed = false;
+  }
+  cancel(): void {
+    if (this.pending) this.decide(false);
+  }
+}
+
+class LeaveScope {
+  private readonly entries = new Set<LeaveController>();
+  private hidden = false;
+  constructor(private readonly dirtyChanged: (dirty: boolean) => void) {}
+
+  changed = (): void => {
+    this.dirtyChanged([...this.entries].some((entry) => entry.dirty));
+  };
+  attach(entry: LeaveController): void {
+    entry.active = true;
+    this.entries.add(entry);
+    this.changed();
+  }
+  detach(entry: LeaveController): void {
+    entry.active = false;
+    // Activity disconnects Effects before the shell commits its new visibility.
+    queueMicrotask(() => {
+      if (!entry.active && !this.hidden) this.remove(entry);
+    });
+  }
+  private remove(entry: LeaveController): void {
+    this.entries.delete(entry);
+    entry.cancel();
+    this.changed();
+  }
+  update(hidden: boolean, pathname: string): void {
+    this.hidden = hidden;
+    for (const entry of this.entries) {
+      if (pathname !== entry.origin && !pathname.startsWith(`${entry.origin}/`))
+        this.remove(entry);
+      else entry.reset();
+    }
+  }
+  prune(): void {
+    if (!this.hidden)
+      for (const entry of this.entries) if (!entry.active) this.remove(entry);
+  }
+  guard = (): Decision => {
+    const remaining = [...this.entries];
+    const next = (): Decision => {
+      const entry = remaining.shift();
+      if (!entry) return true;
+      const value = entry.guard();
+      return typeof value === 'boolean'
+        ? value && next()
+        : value.then((allowed) => allowed && next());
+    };
+    return next();
+  };
+  dispose(): void {
+    for (const entry of this.entries) entry.cancel();
+    this.entries.clear();
+  }
+}
+
+interface BoundaryContext {
+  readonly scope: LeaveScope;
+  readonly show: (prompt: Prompt | undefined) => void;
+}
+const Context = createContext<BoundaryContext | undefined>(undefined);
+
+function useBeforeUnload(dirty: boolean): void {
+  useEffect(() => {
+    if (!dirty) return;
+    const handler = (event: BeforeUnloadEvent) => {
+      event.preventDefault();
+      event.returnValue = '';
+    };
+    window.addEventListener('beforeunload', handler);
+    return () => window.removeEventListener('beforeunload', handler);
+  }, [dirty]);
+}
+
+function promptDialog(prompt: Prompt | undefined): ReactElement | null {
+  return prompt ? (
+    <ConfirmAction
+      open
+      title={prompt.title}
+      description={prompt.description}
+      busy={false}
+      onCancel={() => prompt.owner.decide(false)}
+      onConfirm={() => prompt.owner.decide(true)}
+    />
+  ) : null;
+}
+
+/** The shell owns leave decisions and their UI, outside every page's Activity and its nested routes. */
+export function RouteLeaveBoundary({
+  hidden,
+  children,
+}: PropsWithChildren<{ readonly hidden: boolean }>): ReactElement {
+  const location = useLocation();
+  const [prompt, setPrompt] = useState<Prompt>();
+  const [dirty, setDirty] = useState(false);
+  const [context] = useState(() => ({
+    scope: new LeaveScope(setDirty),
+    show: setPrompt,
+  }));
+  useNavigationGuard(context.scope.guard);
+  useBeforeUnload(dirty);
+  useLayoutEffect(
+    () => context.scope.update(hidden, location.pathname),
+    [context, hidden, location.pathname, location.key],
+  );
+  useEffect(() => {
+    context.scope.prune();
+  }, [context, hidden]);
+  useEffect(() => () => context.scope.dispose(), [context]);
+  return (
+    <Context.Provider value={context}>
+      {children}
+      {promptDialog(prompt)}
+    </Context.Provider>
+  );
+}
+
+/** Compatible with standalone form renders; routed forms keep protection in the shell during permission rechecks. */
+export function usePageLeave(
+  dirty: boolean,
+  busy: boolean,
+  onDiscard?: () => void,
+) {
+  const boundary = useContext(Context);
+  const { t } = useTranslation();
+  const location = useLocation();
+  const [prompt, setPrompt] = useState<Prompt>();
+  const [controller] = useState(
+    () => new LeaveController(location.pathname, boundary?.show ?? setPrompt),
+  );
+  useNavigationGuard(boundary ? () => true : controller.guard);
+  useBeforeUnload(!boundary && dirty);
+  useLayoutEffect(() => {
+    controller.update(
+      dirty,
+      busy,
+      onDiscard,
+      t('settings.discardTitle'),
+      t('settings.discardHint'),
+    );
+    boundary?.scope.changed();
+  }, [controller, dirty, busy, onDiscard, boundary, t]);
+  useLayoutEffect(() => {
+    controller.reset();
+  }, [controller, location.key]);
+  useLayoutEffect(() => {
+    if (!boundary) return () => controller.cancel();
+    boundary.scope.attach(controller);
+    return () => boundary.scope.detach(controller);
+  }, [boundary, controller]);
+  return {
+    guard: controller.guard,
+    allow: controller.allow,
+    dialog: boundary ? null : promptDialog(prompt),
+  };
+}

package/client/routing/route-navigation.ts

@@ -8,7 +8,12 @@ import { useEffect, useMemo, useState } from 'react';
 import { matchPath, matchRoutes, type RouteObject } from 'react-router';
 
 import { EMPTY_ARRAY } from '#lib/constants';
-import { transformNavigation } from '#lib/navigation-transform';
+import {
+  organizeNavigation,
+  settingsCatalog,
+  transformNavigation,
+  type SettingsCategory,
+} from '#lib/navigation-transform';
 
 export interface RouteNavigationItem {
   /** Route keys represented by a single sidebar entry whose content uses tabs. */
@@ -22,7 +27,17 @@ export function buildRouteNavigation(
   routes: readonly AppClientRegisteredRoute[],
   denied: ReadonlySet<string>,
 ): RouteNavigationItem[] {
-  return transformNavigation(visibleRouteNavigation(routes, denied));
+  return transformNavigation(visibleRouteNavigation(routes, denied), routes);
+}
+
+/** The settings home's categories and modules the viewer may open (`settingsCatalog`). */
+export function buildSettingsCatalog(
+  routes: readonly AppClientRegisteredRoute[],
+  denied: ReadonlySet<string>,
+): SettingsCategory[] {
+  return settingsCatalog(
+    organizeNavigation(visibleRouteNavigation(routes, denied), routes),
+  );
 }
 
 function visibleRouteNavigation(
@@ -96,6 +111,8 @@ function navigationPages(
   ]);
 }
 
+const NONE_DENIED: ReadonlySet<string> = new Set();
+
 export function useRouteNavigation(
   routes: readonly AppClientRegisteredRoute[],
 ) {
@@ -151,9 +168,8 @@ export function useRouteNavigation(
       result.guards !== guards ||
       result.revision !== revision),
   );
-  const denied = guards.length
-    ? (result?.denied ?? new Set<string>())
-    : new Set<string>();
+  // A stable empty set keeps consumers that memoize on `denied` from recomputing on every render.
+  const denied = (guards.length && result?.denied) || NONE_DENIED;
   return {
     loading,
     items: loading ? [] : buildRouteNavigation(routes, denied),
@@ -165,11 +181,17 @@ export function matchRouteTree(
   routes: readonly AppClientRegisteredRoute[],
   pathname: string,
 ) {
-  const toMatch = (nodes: readonly AppClientRegisteredRoute[]): RouteObject[] =>
+  const toMatch = (
+    nodes: readonly AppClientRegisteredRoute[],
+    parentPath = '',
+  ): RouteObject[] =>
     nodes.map((route) => ({
-      path: route.path,
+      path: relativeRoutePath(route, parentPath),
       handle: route,
-      children: toMatch(route.children ?? EMPTY_ARRAY),
+      children: toMatch(
+        route.children ?? EMPTY_ARRAY,
+        childRouteParentPath(route, parentPath),
+      ),
     }));
   return matchRoutes(toMatch(routes), pathname)?.map((match) => ({
     ...match,
@@ -177,6 +199,48 @@ export function matchRouteTree(
   }));
 }
 
+/**
+ * A registered route's path relative to its parent's, as the router nests it. Registered paths are absolute; a route at
+ * its parent's own path (a group's home page, a pathless group) nests with an empty path.
+ */
+export function relativeRoutePath(
+  route: AppClientRegisteredRoute,
+  parentPath: string,
+): string {
+  if (!parentPath) return route.path;
+  if (
+    route.path === parentPath ||
+    parentPath.startsWith(`${route.path.replace(/\/$/, '')}/`)
+  )
+    return '';
+  return route.path.slice(parentPath === '/' ? 1 : parentPath.length + 1);
+}
+
+/** The path a route's children are relative to. */
+export function childRouteParentPath(
+  route: AppClientRegisteredRoute,
+  parentPath: string,
+): string {
+  return parentPath.startsWith(`${route.path.replace(/\/$/, '')}/`)
+    ? parentPath
+    : route.path;
+}
+
 export function routeKey(route: AppClientRegisteredRoute): string {
   return `${route.packageName}:${route.path}:${route.id}`;
 }
+
+/** Pure groups can span shells; a page and its descendants always share their shell. */
+export 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);
+    // A group declared empty, such as a settings category waiting for modules, stays so its title is still known.
+    return children.length || !route.children?.length
+      ? [{ ...route, children }]
+      : [];
+  });
+}

package/client/routing/route-tree.tsx

@@ -4,7 +4,11 @@ import { Outlet, Route } from 'react-router';
 
 import { EMPTY_ARRAY } from '#lib/constants';
 
-import { routeKey } from './route-navigation.js';
+import {
+  childRouteParentPath,
+  relativeRoutePath,
+  routeKey,
+} from './route-navigation.js';
 import { ClientRoute } from './client-route.js';
 
 /** Groups pass children through; pages deliberately own their Outlet placement. */
@@ -15,14 +19,7 @@ export function renderRouteTree(
   return routes.map((route) => (
     <Route
       key={routeKey(route)}
-      path={
-        parentPath
-          ? route.path === parentPath ||
-            parentPath.startsWith(`${route.path.replace(/\/$/, '')}/`)
-            ? ''
-            : route.path.slice(parentPath === '/' ? 1 : parentPath.length + 1)
-          : route.path
-      }
+      path={relativeRoutePath(route, parentPath)}
       element={
         route.componentLoader ? (
           <ClientRoute key={routeKey(route)} route={route} />
@@ -33,9 +30,7 @@ export function renderRouteTree(
     >
       {renderRouteTree(
         route.children ?? EMPTY_ARRAY,
-        parentPath.startsWith(`${route.path.replace(/\/$/, '')}/`)
-          ? parentPath
-          : route.path,
+        childRouteParentPath(route, parentPath),
       )}
     </Route>
   ));

package/client/routing/standalone-page-layout.tsx

@@ -1,14 +1,9 @@
 import type { ReactElement } from 'react';
 import { Outlet } from 'react-router';
 
-import { ThemeSettings } from '../theme/index.js';
-
 export function StandalonePageLayout(): ReactElement {
   return (
     <div className='relative min-h-svh'>
-      <div className='fixed top-4 right-4 z-50'>
-        <ThemeSettings />
-      </div>
       <Outlet />
     </div>
   );

package/client/runtime.ts

@@ -5,7 +5,7 @@ import { defineAppRuntime } from '@nocobase/app-client/runtime';
 import locales from './locales/index.js';
 import plugins from './plugins.js';
 import reactProviders from './react-providers.js';
-import routes from './routes.js';
+import { createApplicationRoutes } from './routes.js';
 import serviceProviders from './service-provider.js';
 
 const appRuntime = defineAppRuntime({
@@ -15,7 +15,7 @@ const appRuntime = defineAppRuntime({
   serviceProviders,
   locales,
   reactProviders,
-  routes,
+  routes: () => createApplicationRoutes(),
   plugins,
 });