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

package/client/pages/settings/routes.ts

@@ -1,134 +1,132 @@
-import {
-  Settings,
-  Users,
-  ShieldCheck,
-  KeyRound,
-  ListFilter,
-} from 'lucide-react';
+import { Users, ShieldCheck, KeyRound, ListFilter } from 'lucide-react';
 import {
   defineAppRoutes,
   type AppClientRouteContribution,
 } from '@nocobase/app-client/plugins';
 
-/** Register this contribution as business capabilities are developed; keep a bare Home-only application free of settings. */
+/**
+ * Users and Permission management, in the Accounts and permissions category of the System settings shell
+ * (`shell-routes.ts`). Register this contribution as business capabilities are developed; a bare application stays
+ * without them.
+ */
 const systemSettingsRoutes: AppClientRouteContribution = defineAppRoutes([
   {
-    name: 'settings',
-    path: '/settings',
-    navigation: { title: 'settings.title', icon: Settings, order: 100 },
+    parent: 'settingsAccount',
+    name: 'settingsUsers',
+    path: '/users',
+    auth: 'required',
+    authz: { resource: { type: 'user', id: '*' }, action: 'read' },
+    navigation: {
+      title: 'settings.users',
+      description: 'settings.usersDescription',
+      icon: Users,
+    },
+    breadcrumb: { title: 'settings.users' },
+    componentLoader: () => import('./users.js'),
     children: [
       {
-        name: 'settingsUsers',
-        path: '/users',
-        auth: 'required',
-        authz: { resource: { type: 'user', id: '*' }, action: 'read' },
-        navigation: { title: 'settings.users', icon: Users },
-        breadcrumb: { title: 'settings.users' },
-        componentLoader: () => import('./users.js'),
+        name: 'settingsUserCreate',
+        path: 'create',
+        authz: { resource: { type: 'user', id: '*' }, action: 'create' },
+        componentLoader: () => import('./user-form.js'),
+      },
+      {
+        name: 'settingsUser',
+        path: ':userId',
+        componentLoader: () => import('./user-detail.js'),
         children: [
           {
-            name: 'settingsUserCreate',
-            path: 'create',
-            authz: { resource: { type: 'user', id: '*' }, action: 'create' },
+            name: 'settingsUserEdit',
+            path: 'edit',
             componentLoader: () => import('./user-form.js'),
           },
-          {
-            name: 'settingsUser',
-            path: ':userId',
-            componentLoader: () => import('./user-detail.js'),
-            children: [
-              {
-                name: 'settingsUserEdit',
-                path: 'edit',
-                componentLoader: () => import('./user-form.js'),
-              },
-            ],
-          },
         ],
       },
+    ],
+  },
+  {
+    parent: 'settingsAccount',
+    name: 'permissionManagement',
+    navigation: {
+      title: 'settings.permissionManagement',
+      description: 'settings.permissionManagementDescription',
+      icon: ShieldCheck,
+    },
+    breadcrumb: { title: 'settings.permissionManagement' },
+    children: [
       {
-        name: 'permissionManagement',
-        navigation: {
-          title: 'settings.permissionManagement',
-          icon: ShieldCheck,
+        name: 'settingsRoles',
+        path: '/roles',
+        auth: 'required',
+        authz: {
+          resource: {
+            type: 'settings',
+            id: 'authorization.permission-sets',
+          },
+          action: 'read',
         },
-        breadcrumb: { title: 'settings.permissionManagement' },
+        navigation: { title: 'settings.roles', icon: KeyRound },
+        breadcrumb: { title: 'settings.roles' },
+        componentLoader: () => import('./roles.js'),
         children: [
           {
-            name: 'settingsRoles',
-            path: '/roles',
-            auth: 'required',
+            name: 'settingsRoleCreate',
+            path: 'create',
             authz: {
               resource: {
                 type: 'settings',
                 id: 'authorization.permission-sets',
               },
-              action: 'read',
+              action: 'create',
             },
-            navigation: { title: 'settings.roles', icon: KeyRound },
-            breadcrumb: { title: 'settings.roles' },
-            componentLoader: () => import('./roles.js'),
-            children: [
-              {
-                name: 'settingsRoleCreate',
-                path: 'create',
-                authz: {
-                  resource: {
-                    type: 'settings',
-                    id: 'authorization.permission-sets',
-                  },
-                  action: 'create',
-                },
-                breadcrumb: { title: 'settings.newRole' },
-                componentLoader: () => import('./role-form.js'),
-              },
-              {
-                name: 'settingsRoleEdit',
-                path: ':key/edit',
-                breadcrumb: { title: 'settings.editRole' },
-                componentLoader: () => import('./role-form.js'),
-              },
-            ],
+            breadcrumb: { title: 'settings.newRole' },
+            componentLoader: () => import('./role-form.js'),
           },
           {
-            name: 'settingsDefaultAccess',
-            path: '/default-access',
-            auth: 'required',
+            name: 'settingsRoleEdit',
+            path: ':key/edit',
+            breadcrumb: { title: 'settings.editRole' },
+            componentLoader: () => import('./role-form.js'),
+          },
+        ],
+      },
+      {
+        name: 'settingsDefaultAccess',
+        path: '/default-access',
+        auth: 'required',
+        authz: {
+          resource: {
+            type: 'settings',
+            id: 'authorization.default-access',
+          },
+          action: 'read',
+        },
+        navigation: {
+          title: 'settings.defaultAccess.title',
+          icon: ListFilter,
+        },
+        breadcrumb: { title: 'settings.defaultAccess.title' },
+        componentLoader: () => import('./default-access.js'),
+        children: [
+          {
+            name: 'settingsDefaultAccessCreate',
+            path: 'create',
             authz: {
               resource: {
                 type: 'settings',
                 id: 'authorization.default-access',
               },
-              action: 'read',
-            },
-            navigation: {
-              title: 'settings.defaultAccess.title',
-              icon: ListFilter,
+              action: 'create',
             },
-            breadcrumb: { title: 'settings.defaultAccess.title' },
-            componentLoader: () => import('./default-access.js'),
-            children: [
-              {
-                name: 'settingsDefaultAccessCreate',
-                path: 'create',
-                authz: {
-                  resource: {
-                    type: 'settings',
-                    id: 'authorization.default-access',
-                  },
-                  action: 'create',
-                },
-                breadcrumb: { title: 'settings.defaultAccess.new' },
-                componentLoader: () => import('./default-access-form.js'),
-              },
-              // Read permission opens the full rule even when the viewer may not update it.
-              {
-                name: 'settingsDefaultAccessEdit',
-                path: ':key/edit',
-                breadcrumb: { title: 'settings.defaultAccess.edit' },
-                componentLoader: () => import('./default-access-form.js'),
-              },
-            ],
+            breadcrumb: { title: 'settings.defaultAccess.new' },
+            componentLoader: () => import('./default-access-form.js'),
+          },
+          // Read permission opens the full rule even when the viewer may not update it.
+          {
+            name: 'settingsDefaultAccessEdit',
+            path: ':key/edit',
+            breadcrumb: { title: 'settings.defaultAccess.edit' },
+            componentLoader: () => import('./default-access-form.js'),
           },
         ],
       },

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