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

package/client/pages/settings/settings-home.tsx

@@ -0,0 +1,109 @@
+import type { AppClientRegisteredRoute } from '@nocobase/app-client/plugins';
+import { useTranslation } from '@nocobase/i18n/client';
+import { ChevronRight, Settings } from 'lucide-react';
+import { useMemo, type ReactElement } from 'react';
+import { Link } from 'react-router';
+
+import { Loading } from '#components/loading';
+import { PageContainer } from '#components/page-container';
+import { PageHeader } from '#components/page-header';
+import { Empty, EmptyHeader, EmptyTitle } from '#components/ui/empty';
+import type { SettingsModule } from '#lib/navigation-transform';
+
+import { useRouteAccess, useRouteTree } from '../../routing/route-context.js';
+import {
+  buildSettingsCatalog,
+  routeKey,
+} from '../../routing/route-navigation.js';
+
+/**
+ * The System settings home: the settings modules the viewer may open, as cards grouped by category. Everything shown
+ * comes from the registered routes and the shell's permission check, so a module appears here once it is registered
+ * under a settings category, and disappears with its permission.
+ */
+export default function SettingsHomePage(): ReactElement {
+  const { t } = useTranslation();
+  const routes = useRouteTree();
+  const { denied, loading } = useRouteAccess();
+  const categories = useMemo(
+    () => buildSettingsCatalog(routes, denied),
+    [routes, denied],
+  );
+  return (
+    <PageContainer className='space-y-8'>
+      <PageHeader
+        title={t('settings.title')}
+        description={t('settings.home.description')}
+      />
+      {loading ? (
+        <Loading />
+      ) : categories.length === 0 ? (
+        <Empty className='border border-dashed'>
+          <EmptyHeader>
+            <EmptyTitle>{t('settings.home.empty')}</EmptyTitle>
+          </EmptyHeader>
+        </Empty>
+      ) : (
+        categories.map((category) => {
+          const title = routeText(t, category.route, 'title');
+          return (
+            <section
+              key={routeKey(category.route)}
+              aria-label={title}
+              className='space-y-3'
+            >
+              <h2 className='font-heading text-base font-semibold'>{title}</h2>
+              <ul className='grid gap-3 sm:grid-cols-2 xl:grid-cols-3'>
+                {category.modules.map((module) => (
+                  <li key={routeKey(module.route)} className='min-w-0'>
+                    <SettingsCard module={module} />
+                  </li>
+                ))}
+              </ul>
+            </section>
+          );
+        })
+      )}
+    </PageContainer>
+  );
+}
+
+function SettingsCard({ module }: { module: SettingsModule }): ReactElement {
+  const { t } = useTranslation();
+  // The card's text is its accessible name: the module and what it is for.
+  const title = routeText(t, module.route, 'title');
+  const description = routeText(t, module.route, 'description');
+  const Icon = module.route.navigation?.icon ?? Settings;
+  return (
+    <Link
+      to={module.target.path}
+      className='group flex h-full items-start gap-3 rounded-lg border bg-card p-4 text-card-foreground shadow-xs transition-colors outline-none hover:border-primary/40 hover:bg-accent/40 focus-visible:ring-3 focus-visible:ring-ring/50'
+    >
+      <span className='flex size-9 shrink-0 items-center justify-center rounded-md bg-muted text-muted-foreground group-hover:text-foreground'>
+        <Icon className='size-4' />
+      </span>
+      <span className='min-w-0 flex-1'>
+        <span className='block font-medium'>{title}</span>
+        {description ? (
+          <span className='mt-1 block text-sm leading-6 text-muted-foreground'>
+            {description}
+          </span>
+        ) : null}
+      </span>
+      <ChevronRight
+        aria-hidden
+        className='mt-0.5 size-4 shrink-0 text-muted-foreground transition-transform group-hover:translate-x-0.5 group-hover:text-foreground'
+      />
+    </Link>
+  );
+}
+
+/** A navigation text of a route, translated in the namespace of the package that registered it. */
+function routeText(
+  t: ReturnType<typeof useTranslation>['t'],
+  route: AppClientRegisteredRoute,
+  field: 'title' | 'description',
+): string | undefined {
+  const key = route.navigation?.[field];
+  return key ? t(key, { ns: route.packageName, defaultValue: key }) : undefined;
+}

package/client/pages/settings/settings-module-page.tsx

@@ -0,0 +1,158 @@
+import type { AppClientRegisteredRoute } from '@nocobase/app-client/plugins';
+import { useTranslation } from '@nocobase/i18n/client';
+import {
+  useEffect,
+  useMemo,
+  useRef,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+import { useLocation, useNavigate } from 'react-router';
+
+import { PageContainer } from '#components/page-container';
+import { PageHeader } from '#components/page-header';
+import { Tabs, TabsContent, TabsList, TabsTrigger } from '#components/ui/tabs';
+import { settingsHomeRoute } from '#lib/navigation-transform';
+
+import { useRouteAccess, useRouteTrail } from '../../routing/route-context.js';
+import { routeKey } from '../../routing/route-navigation.js';
+
+const TAB_NAVIGATION = 'settingsTabNavigation';
+
+interface SettingsModuleTabsState {
+  /** The module group: its pages are the tabs. */
+  readonly module?: AppClientRegisteredRoute;
+  /** The tabs the viewer may open, in route order. */
+  readonly tabs: readonly AppClientRegisteredRoute[];
+  /** The tab page the current URL is on. */
+  readonly active?: AppClientRegisteredRoute;
+}
+
+/**
+ * The module the current page belongs to, read from the route trail: a settings module registered as a group has its
+ * menu pages as tabs. A direct child group of the settings group is a category rather than a module, so a page placed
+ * straight in a category has no tabs.
+ */
+function useSettingsModuleTabs(): SettingsModuleTabsState {
+  const trail = useRouteTrail();
+  const { denied } = useRouteAccess();
+  return useMemo(() => {
+    const pageIndex = trail.findIndex((entry) => entry.route.componentLoader);
+    const page = trail[pageIndex]?.route;
+    const group = pageIndex > 0 ? trail[pageIndex - 1].route : undefined;
+    const parent = pageIndex > 1 ? trail[pageIndex - 2].route : undefined;
+    if (!page || !group || group.componentLoader || settingsHomeRoute(group))
+      return { tabs: [], active: page };
+    if (parent && settingsHomeRoute(parent)) return { tabs: [], active: page };
+    const tabs = (group.children ?? []).filter(
+      (child) =>
+        child.componentLoader &&
+        child.navigation &&
+        !denied.has(routeKey(child)),
+    );
+    return { module: group, tabs, active: page };
+  }, [trail, denied]);
+}
+
+/**
+ * The frame of a settings module page. When the module has several views it is a route group whose pages are its tabs:
+ * each tab is its own URL, so refresh, bookmarks and Back keep the view, and a tab the viewer may not open is not
+ * shown. A module with one view the viewer may open shows no tab bar.
+ */
+export function SettingsModulePage({
+  title,
+  description,
+  actions,
+  children,
+}: {
+  /** Defaults to the module group's navigation title. */
+  readonly title?: string;
+  readonly description?: ReactNode;
+  readonly actions?: ReactNode;
+  readonly children: ReactNode;
+}): ReactElement {
+  const { t } = useTranslation();
+  const navigate = useNavigate();
+  const location = useLocation();
+  const { module, tabs, active } = useSettingsModuleTabs();
+  const { loading } = useRouteAccess();
+  const activeRef = useRef<HTMLButtonElement>(null);
+  const focusedRef = useRef(false);
+  const moduleTitle = module?.navigation
+    ? t(module.navigation.title, {
+        ns: module.packageName,
+        defaultValue: module.navigation.title,
+      })
+    : undefined;
+  const heading = title ?? moduleTitle;
+  // Until the shell's permission check answers, a tab the viewer may not open could still be listed.
+  const showTabs = !loading && tabs.length > 1 && active !== undefined;
+  // Each tab is a route, so switching remounts the page; keep keyboard focus on the selected tab.
+  useEffect(() => {
+    if (
+      !focusedRef.current &&
+      location.state &&
+      typeof location.state === 'object' &&
+      Reflect.get(location.state, TAB_NAVIGATION) === true &&
+      activeRef.current
+    ) {
+      const frame = requestAnimationFrame(() => {
+        const selected = activeRef.current;
+        if (selected) {
+          if (
+            !selected
+              .closest('[role="tablist"]')
+              ?.contains(selected.ownerDocument.activeElement)
+          )
+            selected.focus();
+          focusedRef.current = true;
+        }
+      });
+      return () => cancelAnimationFrame(frame);
+    }
+  }, [location.state, tabs]);
+  const header = (
+    <PageHeader title={heading} description={description} actions={actions} />
+  );
+  // Keep the content under the same frame while permissions reload or the tab count changes.
+  const value = active ? routeKey(active) : 'settings-content';
+  return (
+    <PageContainer>
+      {header}
+      <Tabs
+        className='gap-6'
+        value={value}
+        onValueChange={(next) => {
+          const tab = tabs.find((candidate) => routeKey(candidate) === next);
+          if (tab && tab !== active)
+            void navigate(tab.path, { state: { [TAB_NAVIGATION]: true } });
+        }}
+      >
+        {/* Many tabs scroll sideways on a narrow screen instead of widening the page. */}
+        {showTabs ? (
+          <div className='-mx-1 max-w-full overflow-x-auto px-1'>
+            <TabsList variant='line' aria-label={heading}>
+              {tabs.map((tab) => (
+                <TabsTrigger
+                  key={routeKey(tab)}
+                  ref={tab === active ? activeRef : undefined}
+                  value={routeKey(tab)}
+                >
+                  {tab.navigation
+                    ? t(tab.navigation.title, {
+                        ns: tab.packageName,
+                        defaultValue: tab.navigation.title,
+                      })
+                    : null}
+                </TabsTrigger>
+              ))}
+            </TabsList>
+          </div>
+        ) : null}
+        <TabsContent value={value} className='space-y-6'>
+          {children}
+        </TabsContent>
+      </Tabs>
+    </PageContainer>
+  );
+}

package/client/pages/settings/shell-routes.ts

@@ -0,0 +1,53 @@
+import { Settings } from 'lucide-react';
+import {
+  defineAppRoutes,
+  type AppClientRouteContribution,
+} from '@nocobase/app-client/plugins';
+
+/**
+ * The System settings shell: one sidebar entry opening a home page of cards. Child groups are the home page's
+ * categories; register an administration module with `parent` naming its category, such as
+ * `parent: 'settingsAccount'`. A module with several views is a group whose pages become its tabs
+ * (`SettingsModulePage`). A category the viewer can open nothing in is not shown, so a bare application shows only
+ * what its plugins contribute, such as App Foundation for an unrestricted administrator.
+ */
+const settingsShellRoutes: AppClientRouteContribution = defineAppRoutes([
+  {
+    name: 'settings',
+    path: '/settings',
+    navigation: { title: 'settings.title', icon: Settings, order: 100 },
+    breadcrumb: { title: 'settings.title' },
+    children: [
+      {
+        // Lists only modules the viewer may open, so it needs no grant of its own.
+        name: 'settingsHome',
+        path: '/',
+        auth: 'required',
+        authz: 'skip',
+        componentLoader: () => import('./settings-home.js'),
+      },
+      {
+        name: 'settingsAccount',
+        navigation: { title: 'settings.categories.account', order: 10 },
+        children: [],
+      },
+      {
+        name: 'settingsBusiness',
+        navigation: { title: 'settings.categories.business', order: 20 },
+        children: [],
+      },
+      {
+        name: 'settingsAi',
+        navigation: { title: 'settings.categories.ai', order: 30 },
+        children: [],
+      },
+      {
+        name: 'settingsSystem',
+        navigation: { title: 'settings.categories.system', order: 40 },
+        children: [],
+      },
+    ],
+  },
+]);
+
+export default settingsShellRoutes;

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

@@ -5,7 +5,7 @@ import type {
 } 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, useEffect, useState } from 'react';
 import { ErrorBoundary } from 'react-error-boundary';
 
 import { Loading } from '#components/loading';
@@ -52,8 +52,8 @@ export function ClientRoute({ route }: ClientRouteProps): ReactElement {
     return <ClientPageError route={route} />;
   }
 
-  if (checkAccess && accessLoading) return <ClientPageLoading />;
-  if (checkAccess && !allowed) return <ClientPageDenied route={route} />;
+  if (checkAccess && !accessLoading && !allowed)
+    return <ClientPageDenied route={route} />;
 
   if (!componentModule) {
     return <ClientPageLoading />;
@@ -61,13 +61,20 @@ export function ClientRoute({ route }: ClientRouteProps): ReactElement {
 
   const Component = componentModule.default;
 
+  const checking = checkAccess && accessLoading;
   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>
+    <>
+      {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>
+    </>
   );
 }
 

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