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

package/client/pages/settings/routes.ts

@@ -1,134 +1,140 @@
-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: [
+      // The forms declare their presentation, so the dialog or drawer opens at once and the wait for the form's module,
+      // its authorization and its data stays inside it instead of under the list.
+      {
+        name: 'settingsUserCreate',
+        path: 'create',
+        authz: { resource: { type: 'user', id: '*' }, action: 'create' },
+        presentation: { kind: 'dialog', title: 'settings.newUser' },
+        componentLoader: () => import('./user-form.js'),
+      },
+      // A sibling rather than the parent of the editor, so closing the drawer returns to the list instead of to this
+      // route, which only forwards older detail links to the editor.
+      {
+        name: 'settingsUser',
+        path: ':userId',
+        componentLoader: () => import('./user-detail.js'),
+      },
       {
-        name: 'settingsUsers',
-        path: '/users',
+        name: 'settingsUserEdit',
+        path: ':userId/edit',
+        presentation: { kind: 'drawer', title: 'settings.editUser' },
+        componentLoader: () => import('./user-form.js'),
+      },
+    ],
+  },
+  {
+    parent: 'settingsAccount',
+    name: 'permissionManagement',
+    navigation: {
+      title: 'settings.permissionManagement',
+      description: 'settings.permissionManagementDescription',
+      icon: ShieldCheck,
+    },
+    breadcrumb: { title: 'settings.permissionManagement' },
+    children: [
+      {
+        name: 'settingsRoles',
+        path: '/roles',
         auth: 'required',
-        authz: { resource: { type: 'user', id: '*' }, action: 'read' },
-        navigation: { title: 'settings.users', icon: Users },
-        breadcrumb: { title: 'settings.users' },
-        componentLoader: () => import('./users.js'),
+        authz: {
+          resource: {
+            type: 'settings',
+            id: 'authorization.permission-sets',
+          },
+          action: 'read',
+        },
+        navigation: { title: 'settings.roles', icon: KeyRound },
+        breadcrumb: { title: 'settings.roles' },
+        componentLoader: () => import('./roles.js'),
         children: [
           {
-            name: 'settingsUserCreate',
+            name: 'settingsRoleCreate',
             path: 'create',
-            authz: { resource: { type: 'user', id: '*' }, action: 'create' },
-            componentLoader: () => import('./user-form.js'),
+            authz: {
+              resource: {
+                type: 'settings',
+                id: 'authorization.permission-sets',
+              },
+              action: 'create',
+            },
+            breadcrumb: { title: 'settings.newRole' },
+            presentation: { kind: 'child-page' },
+            componentLoader: () => import('./role-form.js'),
           },
           {
-            name: 'settingsUser',
-            path: ':userId',
-            componentLoader: () => import('./user-detail.js'),
-            children: [
-              {
-                name: 'settingsUserEdit',
-                path: 'edit',
-                componentLoader: () => import('./user-form.js'),
-              },
-            ],
+            name: 'settingsRoleEdit',
+            path: ':key/edit',
+            breadcrumb: { title: 'settings.editRole' },
+            presentation: { kind: 'child-page' },
+            componentLoader: () => import('./role-form.js'),
           },
         ],
       },
       {
-        name: 'permissionManagement',
+        name: 'settingsDefaultAccess',
+        path: '/default-access',
+        auth: 'required',
+        authz: {
+          resource: {
+            type: 'settings',
+            id: 'authorization.default-access',
+          },
+          action: 'read',
+        },
         navigation: {
-          title: 'settings.permissionManagement',
-          icon: ShieldCheck,
+          title: 'settings.defaultAccess.title',
+          icon: ListFilter,
         },
-        breadcrumb: { title: 'settings.permissionManagement' },
+        breadcrumb: { title: 'settings.defaultAccess.title' },
+        componentLoader: () => import('./default-access.js'),
         children: [
           {
-            name: 'settingsRoles',
-            path: '/roles',
-            auth: 'required',
+            name: 'settingsDefaultAccessCreate',
+            path: 'create',
             authz: {
               resource: {
                 type: 'settings',
-                id: 'authorization.permission-sets',
+                id: 'authorization.default-access',
               },
-              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.defaultAccess.new' },
+            presentation: { kind: 'child-page' },
+            componentLoader: () => import('./default-access-form.js'),
           },
+          // Read permission opens the full rule even when the viewer may not update it.
           {
-            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: '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'),
-              },
-            ],
+            name: 'settingsDefaultAccessEdit',
+            path: ':key/edit',
+            breadcrumb: { title: 'settings.defaultAccess.edit' },
+            presentation: { kind: 'child-page' },
+            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/pages/settings/user-detail.tsx

@@ -1,24 +1,10 @@
 import type { ReactElement } from 'react';
-import {
-  Navigate,
-  useLocation,
-  useOutlet,
-  useOutletContext,
-  useResolvedPath,
-} from 'react-router';
-import type { ManagedUser } from '@nocobase/app-plugin-users/client/user-client';
+import { Navigate, useLocation } from 'react-router';
 
-/** Keep stored route identifiers and old detail links while using one editor. */
+/** Keeps stored route identifiers and old detail links working by forwarding them to the editor. */
 export default function UserDetail(): ReactElement {
-  const parent = useOutletContext<{
-    reload: (updated?: ManagedUser) => void;
-  }>();
   const location = useLocation();
-  const listPath = useResolvedPath('..').pathname;
-  const outlet = useOutlet({ ...parent, listPath });
   return (
-    outlet ?? (
-      <Navigate to={{ pathname: 'edit', search: location.search }} replace />
-    )
+    <Navigate to={{ pathname: 'edit', search: location.search }} replace />
   );
 }

package/client/pages/settings/user-form.tsx

@@ -1,3 +1,4 @@
+import { PendingButton } from '#components/pending-button';
 import { FeedbackForm } from '#components/feedback-form';
 import { useAuthentication } from '@nocobase/app-plugin-authentication/client';
 import { useSubmission } from '@nocobase/app-client';
@@ -197,7 +198,6 @@ function UserEditor(): ReactElement {
   const location = useLocation();
   const parent = useOutletContext<{
     reload: (updated?: ManagedUser) => void;
-    listPath?: string;
   }>();
   const data = useSettingsData<{ data: ManagedUser }>(
     userId ? `users/${encodeURIComponent(userId)}` : 'users/options',
@@ -281,11 +281,8 @@ function UserEditor(): ReactElement {
   const [serverErrors, setServerErrors] = useState<Record<string, string>>({});
   const [submitted, setSubmitted] = useState(false);
 
-  const parentPath = useResolvedPath('..').pathname;
-  const closeTo = {
-    pathname: creating ? parentPath : (parent.listPath ?? parentPath),
-    search: location.search,
-  };
+  const listPath = useResolvedPath('..').pathname;
+  const closeTo = { pathname: listPath, search: location.search };
   const fieldError = (name: keyof typeof fields): string | undefined => {
     if (!submitted) return;
     if (serverErrors[name]) return serverErrors[name];
@@ -436,7 +433,9 @@ function UserEditor(): ReactElement {
         {t('settings.cancel')}
       </Button>
       {allowed && (
-        <Button
+        <PendingButton
+          busy={busy}
+          pendingLabel={t('settings.saving')}
           form={formId}
           type='submit'
           disabled={
@@ -455,14 +454,8 @@ function UserEditor(): ReactElement {
               (options.loading || Boolean(options.error) || !options.data))
           }
         >
-          {t(
-            busy
-              ? 'settings.saving'
-              : creating
-                ? 'settings.create'
-                : 'settings.save',
-          )}
-        </Button>
+          {t(creating ? 'settings.create' : 'settings.save')}
+        </PendingButton>
       )}
     </>
   );
@@ -475,6 +468,7 @@ function UserEditor(): ReactElement {
       ) : (
         !data.error && (
           <FeedbackForm
+            aria-busy={busy}
             submitting={busy}
             error={error}
             errorContent={<SettingsError error={error} inline />}