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

package/.agents/rules/components.md

@@ -15,7 +15,7 @@ yes n | pnpm exec shadcn add card
 pnpm exec prettier --write client/components/ui/card.tsx
 ```
 
-Build your own components by composing these primitives, and put them in `client/components/`. A page below another one — a covering child page, a record's own page — leaves by the header's breadcrumb when its route declares `breadcrumb` or the page declares its trail with `usePageBreadcrumb`, and otherwise by `BackButton` (`client/components/back-button.tsx`) above its heading; never both.
+Build your own components by composing these primitives, and put them in `client/components/`. A covering child page, independent detail or edit declares its complete navigation with `breadcrumb` or `usePageBreadcrumb`; the shell renders desktop breadcrumbs and the mobile parent arrow. Declare dynamic/logic parents before loading succeeds and keep them on failure. Use `BackButton` only without that shell navigation, with route/access context for target validation; never show duplicate return entries.
 
 **Look components up in the shadcn skill.** The development Skill carries the shadcn/ui skill, unchanged from shadcn 4.21.0, in `.agents/skills/nocobase-app-development/references/frontend/shadcn/`. Read [the shadcn guide](../skills/nocobase-app-development/references/frontend/references/shadcn.md) first: it routes to the skill's rules and states where this application departs from them, among others `pnpm exec shadcn` instead of `npx shadcn@latest`, no `shadcn apply` or `--preset`, and create, edit and detail as `RouteDialog` or `RouteDrawer` child routes rather than a `Sheet`. `pnpm exec shadcn docs <name>` gives one primitive's documentation and examples for the Base UI version. For a whole page, start from the worked example that [the example index](../skills/nocobase-app-development/references/frontend/references/example.md) indexes.
 
@@ -31,6 +31,8 @@ Style with the semantic Tailwind tokens — `bg-background`, `text-foreground`,
 
 The default brand palette and density live in `client/theme/themes/*.css`; shared hover/cursor and Badge geometry live in `client/styles.css`, outside generated shadcn primitives. For semantic status labels, use `StatusBadge` from `client/components/status-badge.tsx` with `neutral`, `info`, `warning`, or `success`; choose the tone by meaning and keep the visible status text. A badge beside a title or on a dense card is the small one, `size='sm'` on `StatusBadge` or `data-size='sm'` on `Badge`. Reuse these shared components and tokens in new pages so template upgrades can carry the design consistently.
 
+Dialog and AlertDialog footer actions use the shared semantic-slot sizing rule in `client/styles.css`, including linked Buttons and RouteOverlay's composed DialogFooter. Keep route links and pending guards; avoid page height/padding patches. The [footer contract](../skills/nocobase-app-development/references/frontend/references/overlay.md#footer-ownership) explains precedence, wrapping and the source upgrade path for existing applications.
+
 **Follow the UI guidelines.** [The UI guidelines](../skills/nocobase-app-development/references/frontend/ui-guidelines.md) set the conventions every page follows, among them the page header and the single placement of the primary action, empty states, row actions behind one "…" menu, dates picked from a `Calendar` in a `Popover` rather than a native date input, and medium-width drawers; the frontend workflow says how much of it to read for a change.
 
 ## Standard process management

package/.agents/rules/shell.md

@@ -4,6 +4,8 @@ Read this before changing the layouts, header, sidebar, breadcrumbs, account men
 
 ## Breadcrumbs and layouts
 
+Both automatic and explicit parents pass through `client/routing/navigation-destination.ts`, using the shell's existing route/access context. Keep permission loading fail-closed, check every target ancestor, and remove denied parent names. Desktop breadcrumbs and the mobile parent arrow use the same resolved levels; mobile keeps the current title and omits the duplicate brand. Follow the [detail/edit generation contract](../skills/nocobase-app-development/references/frontend/references/navigation.md), including stable parents during record failures, source-tab state and direct-entry defaults. Do not add a second page BackButton under the shell.
+
 Layouts own breadcrumb route context and render the current page's trail in the header after the sidebar toggle (`client/components/breadcrumbs.tsx`): the route trail by default, or the trail a page declares with `usePageBreadcrumb` from `@nocobase/app-client` when it names records. Pages do not render breadcrumbs themselves. `AppRouter` selects routes and layouts. See [pages and routes](../skills/nocobase-app-development/references/frontend/references/page.md) for each layout's scope.
 
 The route-tree provider remembers each visited ancestor's query while its descendants are open. Default breadcrumbs and back links restore that query, including an empty one, instead of applying detail-only parameters to the list. Keep this provider mounted above page navigation. Explicit breadcrumb/back destinations remain application-owned. See the linked pages-and-routes reference for deep-link and reload fallbacks.
@@ -24,13 +26,13 @@ Theme lives in the account menu as a submenu beside Language, rather than a sepa
 
 The account menu checks Better Auth sign-out results before refreshing the session and shows a localized error toast for API or network failures. Preserve this behavior when upgrading the shell; navigation alone does not revoke a session.
 
-The authorization provider clears the permission snapshot before rendering a new session. Route navigation and page guards subscribe to the authorization revision; preserve these checks when customizing the shell so account changes and permission updates take effect without a reload. Keep `RouteLeaveBoundary` in `AppLayout`, outside all page Activities including nested routes, so `useSettingsLeave` navigation guards, confirmation UI and `beforeunload` survive permission checks. Clear retained guards on denial and session changes. Restored Activity Effects re-run existing data requests. Pending checks hide protected content with React Activity while retaining drafts; failed checks unmount it and deny access. Body portals must detach in an Effect cleanup so they also disappear while the page is hidden; use `BodyPortal` from `#components/body-portal` for application-owned content mounted on `document.body`.
+The authorization provider clears the permission snapshot before rendering a new session. Route navigation and page guards subscribe to the authorization revision; preserve these checks when customizing the shell so account changes and permission updates take effect without a reload. Keep `RouteLeaveBoundary` in `AppLayout`, outside all page Activities including nested routes, so `useSettingsLeave` navigation guards, confirmation UI and `beforeunload` survive permission checks. Clear retained guards on denial and session changes. Restored Activity Effects re-run existing data requests. Keep each resolved route module for the same loader and retry attempt when Activity reconnects; namespace-wrapping loaders may return a new component type on every invocation and discard form state if invoked again. Pending checks hide protected content with React Activity while retaining drafts; failed checks unmount it and deny access. Body portals must detach in an Effect cleanup so they also disappear while the page is hidden; use `BodyPortal` from `#components/body-portal` for application-owned content mounted on `document.body`.
 
 The account menu language control in `client/layouts/components/language-switcher.tsx` uses a shadcn submenu with radio items. Render it inside `DropdownMenuContent` to preserve menu keyboard navigation and selection semantics.
 
 ## Branded loading
 
-Use `Loading` for page or panel waits and `Spinner` (the shadcn-compatible adapter to `BrandSpinner`) for inline pending actions, uploads, and refresh indicators. Both share the stable NocoBase mark and orbit animation; do not introduce independent Lucide spinners for application loading. Keep skeletons for content placeholders and progress bars for determinate progress. `index.html` has the matching pre-JavaScript mark and must stay visually consistent. All animations respect reduced motion.
+Follow [pending feedback](../skills/nocobase-app-development/references/pending-feedback.md) for shared 300ms display and 10s long-wait guidance. Use `PendingButton` with real `submitting` for native form actions; preserve the shared submission lock. Use `Loading` for page or panel waits and `Spinner` (the shadcn-compatible adapter to `BrandSpinner`) for inline pending actions, uploads, and refresh indicators. Both share the stable NocoBase mark and orbit animation; do not introduce independent Lucide spinners for application loading. Keep skeletons for content placeholders and progress bars for determinate progress. `index.html` has the matching pre-JavaScript mark and must stay visually consistent. All animations respect reduced motion.
 
 The shared list of shell behaviors to keep when customizing is in [customizing the shell](../skills/nocobase-app-development/references/frontend/references/shell.md).
 
@@ -39,3 +41,7 @@ The signed-in region waits in `client/routing/session-preparation.tsx` before mo
 ## List context
 
 Keep the identity-keyed `SessionPreparation` boundary: mounted private list conditions and ancestor query memory must be discarded when the signed-in user changes. Public list state uses `useTableUrlState`; tabbed datasets use `useListTabs`, with complete owned parameter keys and permission-filtered tabs. Follow the synchronized [list navigation rules](../skills/nocobase-app-development/references/frontend/references/child-routes.md#list-tab-breadcrumbs-and-private-conditions). Default back links use an empty ancestor query when no source visit exists; explicit return destinations remain application-owned.
+
+## Page data freshness
+
+Follow the synchronized [page data freshness rules](../skills/nocobase-app-development/references/frontend/references/page-freshness.md): ordinary pages have no persistent Refresh action. Preserve contextual read retries, write invalidation and live progress updates. Dependency upgrades do not rewrite application-owned pages or installed Registry source; reconcile them through the template upgrade workflow.

package/AGENTS.md

@@ -63,7 +63,7 @@ A bare create-app shows Home to signed-in users and, only to unrestricted admini
 
 ### Pages and routes
 
-Declare every page in `client/routes.ts` with `defineAppRoutes()` and keep its component behind a lazy `componentLoader` whose module default-exports it. Never write the deployment base path such as `/main` into a route — the runtime restores it. `auth` controls browser navigation only and is not server security. Declare `navigation` on the route to put it in a menu, and always declare `authz` on the first page of every path; the page id identifies stored page grants, so changing it requires migrating the grants that reference it. Read [pages and routes](.agents/skills/nocobase-app-development/references/frontend/references/page.md), and [overlays](.agents/skills/nocobase-app-development/references/frontend/references/overlay.md) before implementing dialogs, drawers or close guards.
+Declare every page in `client/routes.ts` with `defineAppRoutes()` and keep its component behind a lazy `componentLoader` whose module default-exports it. Never write the deployment base path such as `/main` into a route — the runtime restores it. `auth` controls browser navigation only and is not server security. Declare `navigation` on the route to put it in a menu, and always declare `authz` on the first page of every path; the page id identifies stored page grants, so changing it requires migrating the grants that reference it. Every new independent detail/edit page follows the [navigation pattern](.agents/skills/nocobase-app-development/references/frontend/references/navigation.md), including a parent during loading/errors and mobile return; omit duplicate page back links under the shell. Read [pages and routes](.agents/skills/nocobase-app-development/references/frontend/references/page.md), and [overlays](.agents/skills/nocobase-app-development/references/frontend/references/overlay.md) before implementing dialogs, drawers or close guards.
 
 Every route listed as a page permission needs a localized display name: use its existing navigation/breadcrumb title, or add its application route name to `client/pages/settings/page-permission-titles.ts` for an overlay or other page with no title metadata. Do not add breadcrumbs/menus just to label an overlay. Run `tests/client/page-permission-titles.test.ts`; it requires non-empty English/Chinese labels and rejects missing or stale mappings. Never rename route/permission ids or change `authz` to fix display text.
 

package/client/components/back-button.tsx

@@ -1,16 +1,21 @@
 import { useTranslation } from '@nocobase/i18n/client';
 import { ArrowLeftIcon } from 'lucide-react';
 import type { ReactElement, ReactNode } from 'react';
-import { Link, type To, useResolvedPath } from 'react-router';
+import { Link, type To, parsePath, useResolvedPath } from 'react-router';
 
-import { useRouteSearches } from '../routing/route-context.js';
+import { navigationDestination } from '../routing/navigation-destination.js';
+import {
+  useRouteTree,
+  useRouteAccess,
+  useRouteSearches,
+} from '../routing/route-context.js';
 
 import { cn } from 'cn';
 
 export interface BackButtonProps {
   /**
    * Where it leads. Defaults to the parent route with its last visited query; a directly opened detail falls back
-   * to the default parent list. An explicit destination is kept unchanged.
+   * to the default parent list. An explicit destination must match an authorized application page.
    */
   readonly to?: To;
   /** The label, "Back" by default. */
@@ -31,11 +36,36 @@ export function BackButton({
   children,
   className,
   to,
-}: BackButtonProps = {}): ReactElement {
+}: BackButtonProps = {}): ReactElement | null {
   const { t } = useTranslation();
   const parent = useResolvedPath('..');
+  const resolved = useResolvedPath(to ?? '..');
+  const routes = useRouteTree();
+  const access = useRouteAccess();
   const searches = useRouteSearches();
 
+  const fallback = {
+    ...parent,
+    search: searches.get(parent.pathname.replace(/\/+$/u, '') || '/') ?? '',
+  };
+  const rawPath =
+    typeof to === 'string' ? parsePath(to).pathname : to?.pathname;
+  const unsafe =
+    rawPath &&
+    (/^(?:[a-z][a-z\d+.-]*:|\/\/)/iu.test(rawPath) ||
+      rawPath.includes('\\') ||
+      [...rawPath].some((character) => character.charCodeAt(0) <= 32));
+  const primary = unsafe
+    ? undefined
+    : navigationDestination(
+        to && rawPath?.startsWith('/') ? to : to ? resolved : fallback,
+        routes,
+        access,
+      );
+  const destination =
+    primary ?? navigationDestination(fallback, routes, access);
+  if (!destination) return null;
+
   return (
     <Link
       replace
@@ -43,16 +73,11 @@ export function BackButton({
         'inline-flex w-fit items-center gap-1 text-sm text-muted-foreground transition-colors hover:text-foreground',
         className,
       )}
-      to={
-        to ?? {
-          pathname: '..',
-          search:
-            searches.get(parent.pathname.replace(/\/+$/u, '') || '/') ?? '',
-        }
-      }
+      to={destination}
     >
       <ArrowLeftIcon className='size-4' />
-      {children ?? t('navigation.back', { defaultValue: 'Back' })}
+      {(primary ? children : undefined) ??
+        t('navigation.back', { defaultValue: 'Back' })}
     </Link>
   );
 }

package/client/components/brand-loading-mark.tsx

@@ -1,7 +1,10 @@
 import type { ComponentPropsWithoutRef, ReactElement } from 'react';
 import { cn } from 'cn';
 
-import { BRAND_MARK_PATH, BRAND_MARK_TRANSLATE } from './brand-mark-geometry';
+import {
+  BRAND_MARK_PATH,
+  BRAND_MARK_TRANSLATE,
+} from './brand-mark-geometry.js';
 
 /** Keep the brand recognizable; the orbit, rather than the bricks, conveys progress. */
 export function BrandLoadingMark({
@@ -25,7 +28,7 @@ export function BrandLoadingMark({
         strokeWidth='2'
         opacity='.12'
       />
-      <g className='nocobase-loading-orbit'>
+      <g className='origin-center motion-safe:animate-spin'>
         <path
           d='M32 4a28 28 0 0 1 28 28'
           stroke='currentColor'

package/client/components/brand-mark-geometry.ts

@@ -1,7 +1,7 @@
 /** Official Logomark vector from the supplied logos/Transparent/Vectors asset.
  * Keep geometry unchanged; color, size and decorative animation belong to consumers.
  */
-export const BRAND_MARK_VIEW_BOX = '0 0 100 87.19720458984375';
-export const BRAND_MARK_TRANSLATE = 'translate(0 -6.401886463165283)';
-export const BRAND_MARK_PATH =
+export const BRAND_MARK_VIEW_BOX: string = '0 0 100 87.19720458984375';
+export const BRAND_MARK_TRANSLATE: string = 'translate(0 -6.401886463165283)';
+export const BRAND_MARK_PATH: string =
   'M99.876 55.369c-.025-.045-.076-.072-.109-.111-.066-.078-.125-.168-.217-.221l-.014-.008-.001-.002h-.001L80.368 43.648v-24.67a.92.92 0 0 0-.124-.459c-.026-.045-.075-.072-.108-.111-.066-.08-.126-.168-.218-.221l-.014-.008-.001-.002h-.002L60.286 6.531a.92.92 0 0 0-.94 0L20.099 29.834h-.002l-.001.002-.014.006c-.092.055-.151.143-.218.221-.033.041-.082.068-.108.113a.907.907 0 0 0-.124.457v1.361L.466 43.373H.465l-.001.002c-.098.055-.162.143-.23.227-.034.041-.084.068-.109.113a.898.898 0 0 0-.125.457v25.195c0 .324.171.625.45.791l39.264 23.311c.002.002.006 0 .008.002l.007.008a.924.924 0 0 0 .911 0c.003-.002.004-.006.008-.008.001-.002.005 0 .007-.002l19.161-11.377 19.162 11.377c.002.002.006 0 .008.002.004.002.004.006.007.008a.924.924 0 0 0 .911 0c.003-.002.004-.006.008-.008.002-.002.005 0 .007-.002L99.55 81.812a.916.916 0 0 0 .45-.791V55.828a.92.92 0 0 0-.124-.459zM41.104 65.867V42.812l37.424-22.219v23.055L41.104 65.867zM59.815 8.391l17.83 10.588L59.82 29.561 40.185 41.219l-17.83-10.586 37.46-22.242zM39.264 42.812V65.866L21.472 55.305V32.248l17.792 10.564z';

package/client/components/breadcrumbs.tsx

@@ -1,6 +1,7 @@
 import { usePageBreadcrumbLevels } from '@nocobase/app-client';
 import type { PageBreadcrumbLevel } from '@nocobase/app-client';
 import { useTranslation } from '@nocobase/i18n/client';
+import { ArrowLeftIcon } from 'lucide-react';
 import { Fragment, type ReactElement } from 'react';
 import { Link } from 'react-router';
 
@@ -23,10 +24,13 @@ import { settingsHomeRoute } from '#lib/navigation-transform';
 import { cn } from 'cn';
 
 import {
+  useRouteTree,
+  useRouteAccess,
   useRouteTrail,
   useRouteSearches,
   type RouteTrailEntry,
 } from '../routing/route-context.js';
+import { navigationDestination } from '../routing/navigation-destination.js';
 import { routeKey } from '../routing/route-navigation.js';
 
 export interface BreadcrumbsProps {
@@ -45,7 +49,7 @@ export interface BreadcrumbsProps {
  * `usePageBreadcrumb` from `@nocobase/app-client`. Earlier levels link where a page sits behind them; the last is the
  * current page.
  *
- * On a phone only the last level shows, beside the brand; on a medium screen a trail of three or more levels keeps its
+ * On a phone the current title and a link to the nearest authorized parent show; on a medium screen a trail of three or more levels keeps its
  * first and last and folds the middle into a menu.
  */
 export function Breadcrumbs({
@@ -53,10 +57,18 @@ export function Breadcrumbs({
   denied,
 }: BreadcrumbsProps = {}): ReactElement | null {
   const trail = useRouteTrail();
+  const routes = useRouteTree();
+  const contextAccess = useRouteAccess();
+  const access = denied
+    ? {
+        ...contextAccess,
+        denied: new Set([...contextAccess.denied, ...denied]),
+      }
+    : contextAccess;
   const searches = useRouteSearches();
   const declared = usePageBreadcrumbLevels();
   const { t } = useTranslation();
-  const trailLevels =
+  const candidates =
     declared ??
     trail.flatMap((entry): PageBreadcrumbLevel[] => {
       const title = routeLevelTitle(entry);
@@ -93,6 +105,19 @@ export function Breadcrumbs({
       ];
     });
 
+  const trailLevels = candidates.flatMap(
+    (level, index): PageBreadcrumbLevel[] => {
+      if (!level.to) return [level];
+      const to = navigationDestination(level.to, routes, access);
+      // Keep the current title during permission checks, but never expose an inaccessible ancestor's name.
+      return to
+        ? [{ ...level, to }]
+        : index === candidates.length - 1
+          ? [{ label: level.label }]
+          : [];
+    },
+  );
+
   if (trailLevels.length === 0) return null;
   // A level is told apart by its depth and label; two levels may share either alone.
   const levels = trailLevels.map((level, depth) => ({
@@ -101,6 +126,7 @@ export function Breadcrumbs({
   }));
   const last = levels.length - 1;
   const folded = levels.slice(1, last);
+  const parent = levels.slice(0, last).findLast((level) => level.to);
 
   return (
     <Breadcrumb
@@ -108,6 +134,21 @@ export function Breadcrumbs({
       className={cn('min-w-0', className)}
     >
       <BreadcrumbList className='flex-nowrap'>
+        {parent ? (
+          <BreadcrumbItem className='shrink-0 md:hidden'>
+            <BreadcrumbLink
+              aria-label={t('navigation.backTo', {
+                label: parent.label,
+                defaultValue: `Back to ${parent.label}`,
+              })}
+              title={parent.label}
+              className='inline-flex size-9 items-center justify-center rounded-sm focus-visible:outline-2 focus-visible:outline-ring'
+              render={<Link to={parent.to!} replace />}
+            >
+              <ArrowLeftIcon aria-hidden='true' className='size-4' />
+            </BreadcrumbLink>
+          </BreadcrumbItem>
+        ) : null}
         {levels.map((level, index) => (
           <Fragment key={level.key}>
             {index === 1 && folded.length > 0 ? (
@@ -154,7 +195,10 @@ export function Breadcrumbs({
               )}
             >
               {index === last ? (
-                <BreadcrumbPage className='truncate font-medium'>
+                <BreadcrumbPage
+                  title={level.label}
+                  className='truncate font-medium'
+                >
                   {level.label}
                 </BreadcrumbPage>
               ) : level.to ? (

package/client/components/data-table/data-table.tsx

@@ -1,5 +1,6 @@
 import type { ListState } from '@nocobase/app-client';
 import { ListFeedback, ListFeedbackActions } from '#components/list-feedback';
+import { RefreshIndicator } from '#components/loading';
 import {
   type ColumnDef,
   type PaginationState,
@@ -17,7 +18,14 @@ import {
   getSortedRowModel,
   useReactTable,
 } from '@tanstack/react-table';
-import { type ReactElement, type ReactNode, useMemo, useState } from 'react';
+import {
+  type ReactElement,
+  type ReactNode,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
 
 import { DataTablePagination } from './pagination.js';
 import {
@@ -41,7 +49,18 @@ export interface DataTableProps<TData, TValue = unknown> {
   readonly sortingState?: SortingState;
   readonly onSortingChange?: OnChangeFn<SortingState>;
   readonly showSelectedCount?: boolean;
+  /**
+   * The current request is in flight. With rows of the current query and permission scope this is a background
+   * refresh: rows stay and a delayed refresh indicator appears. Without them the body shows the loading state.
+   * Explicit false pauses loading feedback for an unresolved, inactive query; omitting it uses listState.
+   */
   readonly loading?: boolean;
+  /**
+   * The current query's stable identity, such as its request path. When it
+   * changes the loading and refresh feedback restart their display delay;
+   * the table, its rows' geometry and its controls stay mounted.
+   */
+  readonly loadingIdentity?: unknown;
   readonly listState?: ListState;
   readonly onRetry?: () => void;
   readonly onClearFilters?: () => void;
@@ -95,7 +114,8 @@ export function DataTable<TData, TValue = unknown>({
   sortingState,
   onSortingChange,
   showSelectedCount = true,
-  loading = false,
+  loading,
+  loadingIdentity,
   listState,
   onRetry,
   onClearFilters,
@@ -176,6 +196,37 @@ export function DataTable<TData, TValue = unknown>({
     rows.length > 0 && (state === 'ready' || state === 'refresh-failed');
   const showFeedback = !showRows || state === 'refresh-failed';
   const feedbackColumnCount = Math.max(1, table.getVisibleLeafColumns().length);
+  const showPagination =
+    pagination &&
+    (state === 'ready' || (state === 'refresh-failed' && rows.length > 0));
+  // A new query hides the previous rows at once; keep their body and footer
+  // geometry while it loads so the page below does not jump.
+  const bodyRef = useRef<HTMLTableSectionElement>(null);
+  const footerRef = useRef<HTMLDivElement>(null);
+  const [reserved, setReserved] = useState<{
+    readonly body: number;
+    readonly footer: number;
+  }>();
+  if (!showRows && state !== 'loading' && reserved !== undefined)
+    setReserved(undefined);
+  useEffect(() => {
+    const body = bodyRef.current;
+    if (!showRows || !body || typeof ResizeObserver === 'undefined') return;
+    const footer = footerRef.current;
+    const observer = new ResizeObserver(() => {
+      const next = {
+        body: body.offsetHeight,
+        footer: footer?.offsetHeight ?? 0,
+      };
+      setReserved((old) =>
+        old?.body === next.body && old.footer === next.footer ? old : next,
+      );
+    });
+    observer.observe(body);
+    if (footer) observer.observe(footer);
+    return () => observer.disconnect();
+  }, [showRows, showPagination]);
+  const reserving = state === 'loading' && reserved !== undefined;
 
   return (
     <div className={cn('flex flex-col gap-4', className)}>
@@ -194,8 +245,14 @@ export function DataTable<TData, TValue = unknown>({
           />
         </div>
       ) : null}
-      <div className='overflow-hidden rounded-lg border'>
-        <Table aria-busy={loading}>
+      <div className='relative overflow-hidden rounded-lg border'>
+        {/* A retry after a refresh failure is announced by its own toolbar button. */}
+        <RefreshIndicator
+          pending={Boolean(loading && showRows && state !== 'refresh-failed')}
+          identity={loadingIdentity}
+        />
+        {/* Only retained rows are busy; a loading body owns its own busy region and status. */}
+        <Table aria-busy={loading && showRows}>
           <TableHeader>
             {table.getHeaderGroups().map((headerGroup) => (
               <TableRow key={headerGroup.id}>
@@ -224,15 +281,27 @@ export function DataTable<TData, TValue = unknown>({
               </TableRow>
             ))}
           </TableHeader>
-          <TableBody>
+          <TableBody ref={bodyRef}>
             {showFeedback ? (
               <TableRow>
-                <TableCell colSpan={feedbackColumnCount} className='p-0'>
-                  <ListFeedback
-                    state={state}
-                    empty={emptyMessage}
-                    emptyAction={emptyAction}
-                  />
+                <TableCell
+                  colSpan={feedbackColumnCount}
+                  className='p-0'
+                  style={
+                    reserving && reserved.body > 0
+                      ? { height: reserved.body }
+                      : undefined
+                  }
+                >
+                  {/* Readiness may stay unresolved while the parent query is paused. */}
+                  {state !== 'loading' || loading !== false ? (
+                    <ListFeedback
+                      state={state}
+                      identity={loadingIdentity}
+                      empty={emptyMessage}
+                      emptyAction={emptyAction}
+                    />
+                  ) : null}
                 </TableCell>
               </TableRow>
             ) : null}
@@ -258,14 +327,16 @@ export function DataTable<TData, TValue = unknown>({
           </TableBody>
         </Table>
       </div>
-      {pagination &&
-      (state === 'ready' || (state === 'refresh-failed' && rows.length > 0)) ? (
-        <DataTablePagination
-          table={table}
-          pageSizeOptions={pageSizeOptions}
-          showSelectedCount={showSelectedCount}
-          disabled={loading}
-        />
+      {showPagination || (pagination && reserving) ? (
+        <div ref={footerRef} data-slot='data-table-footer'>
+          <DataTablePagination
+            table={table}
+            pageSizeOptions={pageSizeOptions}
+            showSelectedCount={showSelectedCount}
+            disabled={loading || !showPagination}
+            countPending={!showPagination}
+          />
+        </div>
       ) : null}
     </div>
   );

package/client/components/data-table/pagination.tsx

@@ -26,6 +26,8 @@ export interface DataTablePaginationProps<
   /** Hide the "n of m selected" summary for tables without row selection. */
   readonly showSelectedCount?: boolean;
   readonly disabled?: boolean;
+  /** The current query has no total yet: keep the controls' place but show no previous count. */
+  readonly countPending?: boolean;
 }
 
 const DEFAULT_PAGE_SIZE_OPTIONS: readonly number[] = [10, 20, 30, 40, 50];
@@ -40,6 +42,7 @@ export function DataTablePagination<TData>({
   pageSizeOptions = DEFAULT_PAGE_SIZE_OPTIONS,
   showSelectedCount = true,
   disabled = false,
+  countPending = false,
   className,
   ...props
 }: DataTablePaginationProps<TData>): ReactElement {
@@ -60,7 +63,13 @@ export function DataTablePagination<TData>({
       )}
       {...props}
     >
-      <div className='flex-1 text-sm text-muted-foreground'>
+      <div
+        className={cn(
+          'flex-1 text-sm text-muted-foreground',
+          countPending && 'invisible',
+        )}
+        aria-hidden={countPending || undefined}
+      >
         {showSelectedCount
           ? t('dataTable.selectedCount', {
               defaultValue: '{{selected}} of {{total}} row(s) selected.',
@@ -102,7 +111,13 @@ export function DataTablePagination<TData>({
             </SelectContent>
           </Select>
         </div>
-        <div className='shrink-0 text-sm font-medium whitespace-nowrap tabular-nums'>
+        <div
+          className={cn(
+            'shrink-0 text-sm font-medium whitespace-nowrap tabular-nums',
+            countPending && 'invisible',
+          )}
+          aria-hidden={countPending || undefined}
+        >
           {t('dataTable.pageOf', {
             defaultValue: 'Page {{page}} of {{pageCount}}',
             page: pageIndex + 1,

package/client/components/list-feedback.tsx

@@ -3,7 +3,6 @@ import { useTranslation } from '@nocobase/i18n/client';
 import {
   CircleAlert,
   Inbox,
-  LoaderCircle,
   LockKeyhole,
   LogIn,
   RefreshCw,
@@ -14,6 +13,8 @@ import { Fragment, type ReactElement, type ReactNode } from 'react';
 import { Link } from 'react-router';
 import { Button } from '#components/ui/button';
 import { Alert } from '#components/ui/alert';
+import { Loading } from '#components/loading';
+import { PendingButton } from '#components/pending-button';
 import {
   Empty,
   EmptyContent,
@@ -23,7 +24,6 @@ import {
 } from '#components/ui/empty';
 
 const feedback = {
-  loading: ['listFeedback.loading', 'Loading', LoaderCircle],
   empty: ['listFeedback.empty', 'No data yet', Inbox],
   'no-results': ['listFeedback.noResults', 'No results', SearchX],
   forbidden: ['listFeedback.forbidden', 'Access denied', LockKeyhole],
@@ -38,6 +38,11 @@ export interface ListFeedbackProps {
   readonly empty?: ReactNode;
   /** Optional business-specific action; the standard create action belongs in the page header. */
   readonly emptyAction?: ReactNode;
+  /**
+   * The current query's stable identity, such as its request path. A new
+   * query restarts the display delay without remounting the list.
+   */
+  readonly identity?: unknown;
 }
 
 export interface ListFeedbackActionsProps {
@@ -67,19 +72,17 @@ export function ListFeedbackActions({
 
   if ((state === 'failed' || state === 'refresh-failed') && onRetry) {
     return (
-      <Button variant='outline' disabled={busy} onClick={onRetry}>
-        {busy ? (
-          <LoaderCircle
-            aria-hidden='true'
-            className='motion-safe:animate-spin'
-          />
-        ) : (
-          <RefreshCw aria-hidden='true' />
-        )}
-        {busy
-          ? t('listFeedback.retrying', { defaultValue: 'Retrying…' })
-          : t('listFeedback.retry', { defaultValue: 'Retry' })}
-      </Button>
+      <PendingButton
+        variant='outline'
+        busy={busy}
+        pendingLabel={t('listFeedback.retrying', {
+          defaultValue: 'Retrying…',
+        })}
+        onClick={onRetry}
+      >
+        <RefreshCw aria-hidden='true' />
+        {t('listFeedback.retry', { defaultValue: 'Retry' })}
+      </PendingButton>
     );
   }
 
@@ -105,6 +108,7 @@ export function ListFeedback({
   children,
   empty,
   emptyAction,
+  identity,
 }: ListFeedbackProps): ReactElement {
   const { t } = useTranslation();
 
@@ -134,6 +138,17 @@ export function ListFeedback({
     );
   }
 
+  if (state === 'loading') {
+    // The body keeps its footprint at once; the indicator and one status follow the shared display delay.
+    return (
+      <Loading
+        identity={identity}
+        label={t('listFeedback.loading', { defaultValue: 'Loading' })}
+        className='min-h-24 px-4 py-4'
+      />
+    );
+  }
+
   const [key, fallback, Icon] = feedback[state];
   const isError =
     state === 'failed' || state === 'forbidden' || state === 'unauthenticated';
@@ -145,15 +160,9 @@ export function ListFeedback({
       <Empty
         role={isError ? 'alert' : 'status'}
         className='min-h-24 flex-row flex-none gap-2 rounded-none border-0 px-4 py-6 text-pretty text-card-foreground'
-        aria-busy={state === 'loading'}
       >
         <EmptyMedia className='mb-0 size-4 text-muted-foreground'>
-          <Icon
-            aria-hidden='true'
-            className={
-              state === 'loading' ? 'size-4 motion-safe:animate-spin' : 'size-4'
-            }
-          />
+          <Icon aria-hidden='true' className='size-4' />
         </EmptyMedia>
         <EmptyTitle className='text-sm font-medium text-muted-foreground'>
           {t(key, { defaultValue: fallback })}