@nocobase/app-template-default 1.0.0-beta.83 → 1.0.0-beta.85

package/.agents/rules/build-and-deploy.md

@@ -16,7 +16,7 @@ For a Docker source build, pass `--build-arg CDN_BASE_URL=https://cdn.example.co
 
 ## Packing the build for a deployment
 
-`pnpm build --tar` writes `storage/exports/dist.tar.gz` after the build. The archive holds `dist/` as a directory next to `config.example.yml`, so extracting it produces exactly those two paths rather than scattering `server/` and `node_modules/` into whatever directory you unpacked in.
+`pnpm build --tar` writes `storage/exports/dist.tar.gz` after the build. The archive holds `dist/` as a directory next to `config.example.yml`, with the `Dockerfile` and `Dockerfile.dockerignore`, so extracting it produces exactly those paths rather than scattering `server/` and `node_modules/` into whatever directory you unpacked in, and a server can build the image from it alone with `docker build --build-arg DIST=prebuilt .`.
 
 `config.example.yml` travels with it because a deployment has to write a `config.yml` before it can start — `pnpm nocobase config init`, run inside `dist/`, does that from the example, in place, and `pnpm nocobase config check` there verifies it, database connection included, before the first start — and the example is the only statement of what may go in it. Directories of executable shims are left out: a `.bin` entry points at a path on the machine that installed it, and a dangling one makes `pnpm install` in the extracted tree report a corrupt store rather than repair it.
 

package/.agents/rules/shell.md

@@ -33,3 +33,7 @@ Use `Loading` for page or panel waits and `Spinner` (the shadcn-compatible adapt
 The shared list of shell behaviors to keep when customizing is in [customizing the shell](../skills/nocobase-app-development/references/frontend/references/shell.md).
 
 The signed-in region waits in `client/routing/session-preparation.tsx` before mounting `AppLayout`: the authentication provider first reconnects active realtime subscriptions as the current session and waits for the open notification, including permission invalidation. A ten-second timeout shows a localized retry/sign-out screen. Keep this boundary inside `RequiredAuthentication`; guest login must remain reachable without realtime. Readiness is only for initial session preparation. Subsequent permission notifications and reconnects still use normal fail-closed route unmounting, including portal and effect cleanup.
+
+## 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.

package/AGENTS.md

@@ -2,7 +2,7 @@
 
 This is a NocoBase 3 application. Do not apply globally installed NocoBase 2 Skills. You are building the application itself — its pages, its API, its database tables. Everything under this directory is application-owned source code that you may edit directly.
 
-Do not create a plugin to add a feature. Plugins are separately published packages for capabilities shared across several applications; building one for this application's own feature adds a package boundary, a version, and a release process to work that belongs in `client/` and `server/`. Create one only when the user explicitly asks for a reusable published package. Ordinary internal workspace packages under `packages/` may share code without becoming plugins or being published; follow [internal packages](.agents/rules/workspace.md) when the application needs that boundary.
+Build application-specific features directly in the application by default. Use a plugin when the user requests one or when code reuse or modular organization calls for a separately registered, maintainable feature. Local plugins belong under `packages/`; the App builds and packages registered local plugins for deployment, so publishing is optional and only needed when distributing the plugin through a package registry. Follow [the project plugin development Skill](.agents/skills/nocobase-app-plugin-development/SKILL.md). Ordinary internal packages can share code without plugin registration; follow [internal packages](.agents/rules/workspace.md) when that is the boundary the application needs.
 
 ## Default template scope
 
@@ -28,6 +28,8 @@ For creating or maintaining a plugin in this App, read [the project plugin devel
 
 `.agents/skills/nocobase-app-upgrade/` is a separate Skill for a separate job: merging a newer release of the template this application was generated from. Read it when the task is upgrading the template rather than building a feature — including when the user asks to upgrade NocoBase or its core version, because a newer template release is how this application moves to a newer NocoBase — and read it before touching anything — an upgrade done by copying the newest template over this application destroys the work that made it this application.
 
+When upgrading from an older installed Skill, also read the target template package’s `AGENTS.md` and `README.MD` and fetch its declared `@nocobase/app-skills` package before editing. Follow the target’s upgrade requirements in the same upgrade, including application-owned lists and installed Registry copies. Confirm the target baseline only after conflicts are resolved and dependency, source, behavior and retained-data checks pass; see the [upgrade Skill](.agents/skills/nocobase-app-upgrade/SKILL.md).
+
 `.agents/skills/nocobase-deployment/` covers moving this application from source to a production server: building for the target platform, what the archive does and does not carry, migrations and business data, production configuration, and what to verify afterwards. Read it before building for deployment, and when an application starts in production but does not work.
 
 ## Where things go
@@ -93,7 +95,7 @@ Put a package your **server** code (`server/`, `database/`, `cli/`) imports in `
 
 ### Plugins
 
-**Read a plugin's Skill before building what it already does.** Building a permission system, a notification sender, or a job scheduler by hand when a registered plugin already provides one is the most expensive mistake available here. Register and update plugins with `pnpm nocobase plugin register` and `pnpm nocobase plugin update`; customize a plugin's page through its options, a source extension or `client/route-overrides.ts`, never by redeclaring its route. `.agents/skills/` is generated output; never edit a file there. See [plugins](.agents/skills/nocobase-app-development/references/plugins.md).
+**Read a plugin's Skill before building what it already does.** Building a permission system, a notification sender, or a job scheduler by hand when a registered plugin already provides one is the most expensive mistake available here. Register and update plugins with `pnpm nocobase plugin register` and `pnpm nocobase plugin update`; customize a plugin's page through its options or an explicitly registered route component override, never by redeclaring its route. `.agents/skills/` is generated output; never edit a file there. See [plugins](.agents/skills/nocobase-app-development/references/plugins.md).
 
 ### Running the application
 
@@ -118,6 +120,10 @@ When the built-in mechanism genuinely cannot express what is being asked, changi
 - Comment what you changed and why the built-in path did not fit. On upgrade, an agent reconciling the template's version needs to know whether your change is still needed.
 - Record what the next agent needs to know in the matching `.agents/rules/` file, or a new one linked from the index below, so the guidance describes the application as it actually is without growing this file. If the framework's shared guidance is wrong for every application, update the source `@nocobase/app-skills` package instead of editing its synchronized copy.
 
+## Standard submissions
+
+Standard Repository writes require an operation key through the registered submission provider. Forms share `useSubmission` across all entries before asynchronous validation; custom effectful APIs explicitly join the receipt transaction. Follow [submission protection](.agents/skills/nocobase-app-development/references/submission.md) and [source upgrades](.agents/skills/nocobase-app-upgrade/references/submission-upgrade.md). Merge copied source and verify retained customizations on upgrade.
+
 ## Index
 
 | Read                                                                   | When                                                                                                         |

package/README.MD

@@ -4,6 +4,12 @@ A full-stack NocoBase 3 application. The server runs on `@nocobase/app-server` a
 
 You own everything in this directory. Add pages, API routes, database tables, and business logic directly here — this is your application's source code, not a framework you extend from the outside.
 
+## Upgrade this application
+
+Ask the application agent to upgrade NocoBase using the application-local [template upgrade Skill](.agents/skills/nocobase-app-upgrade/SKILL.md). This is the supported version-selection and three-way source reconciliation entry point. Before merging, read the selected target package’s `AGENTS.md`, this section and the upgrade Skill from its declared `@nocobase/app-skills` dependency, even if the application still has an older Skill. Fetch and inspect that guidance without first installing it.
+
+Complete the target’s requirements in that same upgrade: reconcile dependencies, copied template and Registry sources, application-owned table/card consumers and translations while preserving business customizations, grants, records and executed migrations. For list feedback, follow the target Skill’s `references/list-feedback-upgrade.md`. Do not finish with only a version bump, dependency update or Skill sync. Missing targets, unresolved business conflicts or failed acceptance stop completion; confirm `defaultTemplateVersion` only after the checks pass. See the target Skill’s `references/versioned-upgrade-verification.md` for package integrity records and verification after publication.
+
 ## Default and Examples
 
 Default provides the application shell and product capabilities without example plugins or business demo pages. Application-owned business API routes start empty, and new databases receive no article sample data. A bare create-app shows Home and, for unrestricted administrators only, System settings → App foundation. Foundation is installed and registered on both Client and Server; its read-only overview is available at `/foundation` under the application base path. As business capabilities are developed, the app development skill reconciles missing core administration on every iteration and registers the prepared Users and Roles and permissions contribution (`client/pages/settings/routes.ts`); each actually used configurable capability includes its administration as part of feature delivery. Its built-in Users integration lists direct Authorization Permission Sets as application roles, while access assigned to all authenticated users remains separate. Use `app-template-examples` for article management and runnable plugin demonstrations.
@@ -138,7 +144,7 @@ The three files named `runtime.ts`, `plugins.ts`, and `routes.ts` are compositio
 | `pnpm dev`         | Start the API server and client with hot reload                                      |
 | `pnpm build`       | Build the client and server into `dist/`                                             |
 | `pnpm start`       | Run the built server; requires `pnpm build` first                                    |
-| `pnpm build --tar` | Build, then pack `dist/` and `config.example.yml` into `storage/exports/dist.tar.gz` |
+| `pnpm build --tar` | Build, then pack `dist/`, `config.example.yml` and the `Dockerfile` with its `.dockerignore` into `storage/exports/dist.tar.gz` |
 
 ### Database
 
@@ -287,10 +293,12 @@ Pass the file's path relative to `dist/client/`, with or without a leading slash
 
 `pnpm build --tar` writes `storage/exports/dist.tar.gz`, the artifact `@nocobase/app-installer` installs on a server.
 
-The archive has two levels: `config.example.yml` and `dist/` sit at the root, and the build is inside `dist/`. What `dist/` holds varies with the application; this is the shape:
+The archive has two levels: `config.example.yml`, `dist/` and, when the application has them, the `Dockerfile` and `Dockerfile.dockerignore` sit at the root, and the build is inside `dist/`. A server builds the image from the extracted archive alone with `docker build --build-arg DIST=prebuilt .`. What `dist/` holds varies with the application; this is the shape:
 
 ```text
 dist.tar.gz
+├── Dockerfile
+├── Dockerfile.dockerignore
 ├── config.example.yml
 └── dist/
     ├── cli/

package/client/components/back-button.tsx

@@ -1,7 +1,7 @@
 import { useTranslation } from '@nocobase/i18n/client';
 import { ArrowLeftIcon } from 'lucide-react';
 import type { ReactElement, ReactNode } from 'react';
-import { Link, type To, useLocation, useResolvedPath } from 'react-router';
+import { Link, type To, useResolvedPath } from 'react-router';
 
 import { useRouteSearches } from '../routing/route-context.js';
 
@@ -10,7 +10,7 @@ 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 current query, as closing a route overlay does. An explicit destination is kept unchanged.
+   * to the default parent list. An explicit destination is kept unchanged.
    */
   readonly to?: To;
   /** The label, "Back" by default. */
@@ -33,7 +33,6 @@ export function BackButton({
   to,
 }: BackButtonProps = {}): ReactElement {
   const { t } = useTranslation();
-  const location = useLocation();
   const parent = useResolvedPath('..');
   const searches = useRouteSearches();
 
@@ -48,8 +47,7 @@ export function BackButton({
         to ?? {
           pathname: '..',
           search:
-            searches.get(parent.pathname.replace(/\/+$/u, '') || '/') ??
-            location.search,
+            searches.get(parent.pathname.replace(/\/+$/u, '') || '/') ?? '',
         }
       }
     >

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

@@ -1,4 +1,5 @@
-import { useTranslation } from '@nocobase/i18n/client';
+import type { ListState } from '@nocobase/app-client';
+import { ListFeedback, ListFeedbackActions } from '#components/list-feedback';
 import {
   type ColumnDef,
   type PaginationState,
@@ -41,13 +42,17 @@ export interface DataTableProps<TData, TValue = unknown> {
   readonly onSortingChange?: OnChangeFn<SortingState>;
   readonly showSelectedCount?: boolean;
   readonly loading?: boolean;
+  readonly listState?: ListState;
+  readonly onRetry?: () => void;
+  readonly onClearFilters?: () => void;
+  readonly emptyAction?: ReactNode;
   readonly className?: string;
   /**
    * Rendered above the table and handed the table instance, so filters and
    * `DataTableViewOptions` can read and drive its state.
    */
   readonly toolbar?: (table: TableInstance<TData>) => ReactNode;
-  /** Shown in place of the body when no row survives filtering. */
+  /** Shown in the table body when no row survives filtering. */
   readonly emptyMessage?: ReactNode;
   /** Set to `false` to render every row and hide the pagination footer. */
   readonly pagination?: boolean;
@@ -91,8 +96,11 @@ export function DataTable<TData, TValue = unknown>({
   onSortingChange,
   showSelectedCount = true,
   loading = false,
+  listState,
+  onRetry,
+  onClearFilters,
+  emptyAction,
 }: DataTableProps<TData, TValue>): ReactElement {
-  const { t } = useTranslation();
   const tableData = useMemo(() => [...data], [data]);
   const [sorting, setSorting] = useState<SortingState>([]);
   const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([]);
@@ -134,12 +142,56 @@ export function DataTable<TData, TValue = unknown>({
   });
 
   const rows = table.getRowModel().rows;
+  const requestedState =
+    (listState === 'ready' && rows.length === 0
+      ? columnFilters.length > 0
+        ? 'no-results'
+        : 'empty'
+      : listState) ??
+    (loading && data.length === 0
+      ? 'loading'
+      : rows.length
+        ? 'ready'
+        : columnFilters.length
+          ? 'no-results'
+          : 'empty');
+  const state =
+    (requestedState === 'empty' || requestedState === 'no-results') &&
+    ((manualPagination && columnFilters.length === 0 && (rowCount ?? 0) > 0) ||
+      (!manualPagination && table.getPrePaginationRowModel().rows.length > 0))
+      ? 'loading'
+      : requestedState;
+  const clearFilters = () => {
+    table.resetColumnFilters();
+    table.setPageIndex(0);
+    onClearFilters?.();
+  };
+  const hasStateActions =
+    (state === 'no-results' &&
+      (columnFilters.length > 0 || onClearFilters !== undefined)) ||
+    ((state === 'failed' || state === 'refresh-failed') &&
+      onRetry !== undefined) ||
+    state === 'unauthenticated';
+  const showRows =
+    rows.length > 0 && (state === 'ready' || state === 'refresh-failed');
+  const showFeedback = !showRows || state === 'refresh-failed';
+  const feedbackColumnCount = Math.max(1, table.getVisibleLeafColumns().length);
 
   return (
     <div className={cn('flex flex-col gap-4', className)}>
-      {toolbar ? (
+      {toolbar || hasStateActions ? (
         <div className='flex flex-wrap items-center gap-2'>
-          {toolbar(table)}
+          {toolbar?.(table)}
+          <ListFeedbackActions
+            state={state}
+            onClear={
+              columnFilters.length > 0 || onClearFilters
+                ? clearFilters
+                : undefined
+            }
+            onRetry={onRetry}
+            busy={loading}
+          />
         </div>
       ) : null}
       <div className='overflow-hidden rounded-lg border'>
@@ -173,39 +225,41 @@ export function DataTable<TData, TValue = unknown>({
             ))}
           </TableHeader>
           <TableBody>
-            {rows.length > 0 ? (
-              rows.map((row) => (
-                <TableRow
-                  key={row.id}
-                  data-state={row.getIsSelected() ? 'selected' : undefined}
-                  className={onRowClick ? 'cursor-pointer' : undefined}
-                  onClick={onRowClick ? () => onRowClick(row) : undefined}
-                >
-                  {row.getVisibleCells().map((cell) => (
-                    <TableCell key={cell.id}>
-                      {flexRender(
-                        cell.column.columnDef.cell,
-                        cell.getContext(),
-                      )}
-                    </TableCell>
-                  ))}
-                </TableRow>
-              ))
-            ) : (
+            {showFeedback ? (
               <TableRow>
-                <TableCell
-                  colSpan={columns.length}
-                  className='h-24 text-center text-muted-foreground'
-                >
-                  {emptyMessage ??
-                    t('dataTable.noResults', { defaultValue: 'No results.' })}
+                <TableCell colSpan={feedbackColumnCount} className='p-0'>
+                  <ListFeedback
+                    state={state}
+                    empty={emptyMessage}
+                    emptyAction={emptyAction}
+                  />
                 </TableCell>
               </TableRow>
-            )}
+            ) : null}
+            {showRows
+              ? rows.map((row) => (
+                  <TableRow
+                    key={row.id}
+                    data-state={row.getIsSelected() ? 'selected' : undefined}
+                    className={onRowClick ? 'cursor-pointer' : undefined}
+                    onClick={onRowClick ? () => onRowClick(row) : undefined}
+                  >
+                    {row.getVisibleCells().map((cell) => (
+                      <TableCell key={cell.id}>
+                        {flexRender(
+                          cell.column.columnDef.cell,
+                          cell.getContext(),
+                        )}
+                      </TableCell>
+                    ))}
+                  </TableRow>
+                ))
+              : null}
           </TableBody>
         </Table>
       </div>
-      {pagination ? (
+      {pagination &&
+      (state === 'ready' || (state === 'refresh-failed' && rows.length > 0)) ? (
         <DataTablePagination
           table={table}
           pageSizeOptions={pageSizeOptions}

package/client/components/default-access-editor.tsx

@@ -83,6 +83,7 @@ export function DefaultAccessEditor({
           <Input
             id={`${id}-key`}
             name='ruleKey'
+            data-field-path='key'
             value={ruleKey}
             required
             disabled={existing || readOnly}
@@ -91,7 +92,11 @@ export function DefaultAccessEditor({
             onChange={(event) => onKeyChange(event.target.value)}
           />
           {keyError && (
-            <p id={`${id}-key-error`} className='text-sm text-destructive'>
+            <p
+              data-feedback-field-error
+              id={`${id}-key-error`}
+              className='text-sm text-destructive'
+            >
               {keyError}
             </p>
           )}
@@ -108,6 +113,7 @@ export function DefaultAccessEditor({
           >
             <SelectTrigger
               id={`${id}-resource`}
+              data-field-path='resource'
               className='w-full'
               aria-invalid={Boolean(resourceError)}
               aria-describedby={
@@ -127,7 +133,11 @@ export function DefaultAccessEditor({
             </SelectContent>
           </Select>
           {resourceError && (
-            <p id={`${id}-resource-error`} className='text-sm text-destructive'>
+            <p
+              data-feedback-field-error
+              id={`${id}-resource-error`}
+              className='text-sm text-destructive'
+            >
               {resourceError}
             </p>
           )}
@@ -187,6 +197,7 @@ export function DefaultAccessEditor({
                     </Select>
                     {scope.error && (
                       <p
+                        data-feedback-field-error
                         id={`${id}-${scope.id}-error`}
                         className='text-sm text-destructive'
                       >