@nocobase/app-skills 0.1.0-beta.52 → 0.1.0-beta.54

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (92) hide show
  1. package/package.json +7 -3
  2. package/skills/nocobase-app-development/SKILL.md +8 -4
  3. package/skills/nocobase-app-development/references/authorization.md +1 -1
  4. package/skills/nocobase-app-development/references/frontend/references/child-routes.md +88 -52
  5. package/skills/nocobase-app-development/references/frontend/references/example/delete-dialog.md +6 -0
  6. package/skills/nocobase-app-development/references/frontend/references/example/detail-drawer.md +8 -1
  7. package/skills/nocobase-app-development/references/frontend/references/example/list-page.md +40 -64
  8. package/skills/nocobase-app-development/references/frontend/references/example/project-form.md +69 -33
  9. package/skills/nocobase-app-development/references/frontend/references/example/server-table.md +57 -110
  10. package/skills/nocobase-app-development/references/frontend/references/example/session-expired-alert.md +24 -7
  11. package/skills/nocobase-app-development/references/frontend/references/example/settings-form.md +10 -2
  12. package/skills/nocobase-app-development/references/frontend/references/form.md +47 -4
  13. package/skills/nocobase-app-development/references/frontend/references/page.md +6 -2
  14. package/skills/nocobase-app-development/references/frontend/references/table.md +19 -3
  15. package/skills/nocobase-app-development/references/frontend/references/ui-library.md +17 -2
  16. package/skills/nocobase-app-development/references/lifecycle-ui.md +2 -2
  17. package/skills/nocobase-app-development/references/plugins.md +20 -2
  18. package/skills/nocobase-app-development/references/submission.md +62 -0
  19. package/skills/nocobase-app-plugin-development/SKILL.md +68 -0
  20. package/skills/nocobase-app-plugin-development/agents/openai.yaml +6 -0
  21. package/skills/nocobase-app-plugin-development/assets/testing-example/cli/count.ts +14 -0
  22. package/skills/nocobase-app-plugin-development/assets/testing-example/cli/index.ts +10 -0
  23. package/skills/nocobase-app-plugin-development/assets/testing-example/client/index.ts +16 -0
  24. package/skills/nocobase-app-plugin-development/assets/testing-example/client/locales/de-DE.ts +10 -0
  25. package/skills/nocobase-app-plugin-development/assets/testing-example/client/locales/en-US.ts +11 -0
  26. package/skills/nocobase-app-plugin-development/assets/testing-example/client/locales/es-ES.ts +10 -0
  27. package/skills/nocobase-app-plugin-development/assets/testing-example/client/locales/fr-FR.ts +10 -0
  28. package/skills/nocobase-app-plugin-development/assets/testing-example/client/locales/id-ID.ts +10 -0
  29. package/skills/nocobase-app-plugin-development/assets/testing-example/client/locales/index.ts +16 -0
  30. package/skills/nocobase-app-plugin-development/assets/testing-example/client/locales/ja-JP.ts +10 -0
  31. package/skills/nocobase-app-plugin-development/assets/testing-example/client/locales/pt-BR.ts +10 -0
  32. package/skills/nocobase-app-plugin-development/assets/testing-example/client/locales/vi-VN.ts +10 -0
  33. package/skills/nocobase-app-plugin-development/assets/testing-example/client/locales/zh-CN.ts +10 -0
  34. package/skills/nocobase-app-plugin-development/assets/testing-example/client/locales/zh-TW.ts +10 -0
  35. package/skills/nocobase-app-plugin-development/assets/testing-example/client/public-config.ts +13 -0
  36. package/skills/nocobase-app-plugin-development/assets/testing-example/client/reading-list.tsx +56 -0
  37. package/skills/nocobase-app-plugin-development/assets/testing-example/database/migrations/202610180001_reading_list.ts +16 -0
  38. package/skills/nocobase-app-plugin-development/assets/testing-example/eslint.config.js +6 -0
  39. package/skills/nocobase-app-plugin-development/assets/testing-example/package.json +49 -0
  40. package/skills/nocobase-app-plugin-development/assets/testing-example/server/config.ts +39 -0
  41. package/skills/nocobase-app-plugin-development/assets/testing-example/server/index.ts +22 -0
  42. package/skills/nocobase-app-plugin-development/assets/testing-example/server/provider.ts +31 -0
  43. package/skills/nocobase-app-plugin-development/assets/testing-example/server/providers/index.ts +5 -0
  44. package/skills/nocobase-app-plugin-development/assets/testing-example/server/routes.ts +56 -0
  45. package/skills/nocobase-app-plugin-development/assets/testing-example/server/service.ts +35 -0
  46. package/skills/nocobase-app-plugin-development/assets/testing-example/tests/cli/count.test.ts +55 -0
  47. package/skills/nocobase-app-plugin-development/assets/testing-example/tests/client/public-config.test.tsx +19 -0
  48. package/skills/nocobase-app-plugin-development/assets/testing-example/tests/client/reading-list.test.tsx +87 -0
  49. package/skills/nocobase-app-plugin-development/assets/testing-example/tests/database/migration.test.ts +26 -0
  50. package/skills/nocobase-app-plugin-development/assets/testing-example/tests/fixtures/app/package.json +5 -0
  51. package/skills/nocobase-app-plugin-development/assets/testing-example/tests/fixtures/app/server/app.ts +19 -0
  52. package/skills/nocobase-app-plugin-development/assets/testing-example/tests/fixtures/app/server/runtime.ts +67 -0
  53. package/skills/nocobase-app-plugin-development/assets/testing-example/tests/fixtures/app/server/standalone.ts +31 -0
  54. package/skills/nocobase-app-plugin-development/assets/testing-example/tests/helpers/app.ts +27 -0
  55. package/skills/nocobase-app-plugin-development/assets/testing-example/tests/server/config.test.ts +38 -0
  56. package/skills/nocobase-app-plugin-development/assets/testing-example/tests/server/routes.test.ts +50 -0
  57. package/skills/nocobase-app-plugin-development/assets/testing-example/tsconfig.json +16 -0
  58. package/skills/nocobase-app-plugin-development/assets/testing-example/vitest.config.ts +34 -0
  59. package/skills/nocobase-app-plugin-development/references/cli.md +363 -0
  60. package/skills/nocobase-app-plugin-development/references/client-api.md +222 -0
  61. package/skills/nocobase-app-plugin-development/references/client-child-routes.md +351 -0
  62. package/skills/nocobase-app-plugin-development/references/client-components.md +272 -0
  63. package/skills/nocobase-app-plugin-development/references/client-examples.md +641 -0
  64. package/skills/nocobase-app-plugin-development/references/client-pages-and-routes.md +125 -0
  65. package/skills/nocobase-app-plugin-development/references/client-routing.md +159 -0
  66. package/skills/nocobase-app-plugin-development/references/client.md +162 -0
  67. package/skills/nocobase-app-plugin-development/references/configuration.md +65 -0
  68. package/skills/nocobase-app-plugin-development/references/database.md +225 -0
  69. package/skills/nocobase-app-plugin-development/references/http-api.md +184 -0
  70. package/skills/nocobase-app-plugin-development/references/i18n.md +374 -0
  71. package/skills/nocobase-app-plugin-development/references/plugin-foundation.md +203 -0
  72. package/skills/nocobase-app-plugin-development/references/plugin-skills.md +118 -0
  73. package/skills/nocobase-app-plugin-development/references/registration.md +135 -0
  74. package/skills/nocobase-app-plugin-development/references/registry.md +11 -0
  75. package/skills/nocobase-app-plugin-development/references/repository-examples.md +264 -0
  76. package/skills/nocobase-app-plugin-development/references/server-route-examples.md +518 -0
  77. package/skills/nocobase-app-plugin-development/references/server.md +291 -0
  78. package/skills/nocobase-app-plugin-development/references/service-examples.md +470 -0
  79. package/skills/nocobase-app-plugin-development/references/services.md +188 -0
  80. package/skills/nocobase-app-plugin-development/references/system-settings.md +106 -0
  81. package/skills/nocobase-app-plugin-development/references/testing-example.md +59 -0
  82. package/skills/nocobase-app-plugin-development/references/testing.md +139 -0
  83. package/skills/nocobase-app-plugin-development/references/theme-tokens.md +105 -0
  84. package/skills/nocobase-app-plugin-development/scripts/verify-testing-example.mjs +90 -0
  85. package/skills/nocobase-app-upgrade/SKILL.md +32 -4
  86. package/skills/nocobase-app-upgrade/references/edge-cases.md +2 -0
  87. package/skills/nocobase-app-upgrade/references/form-feedback-upgrade.md +36 -0
  88. package/skills/nocobase-app-upgrade/references/list-navigation-upgrade.md +35 -3
  89. package/skills/nocobase-app-upgrade/references/plugin-development-skill.md +32 -0
  90. package/skills/nocobase-app-upgrade/references/submission-upgrade.md +18 -0
  91. package/skills/nocobase-app-upgrade/references/versioned-upgrade-verification.md +25 -0
  92. package/skills/nocobase-deployment/SKILL.md +2 -2
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@nocobase/app-skills",
3
- "version": "0.1.0-beta.52",
4
- "description": "Agent Skills for developing, upgrading and deploying NocoBase applications.",
3
+ "version": "0.1.0-beta.54",
4
+ "description": "Agent Skills for developing applications and plugins, upgrading and deploying NocoBase applications.",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
7
7
  "type": "git",
@@ -10,7 +10,11 @@
10
10
  },
11
11
  "prettier": "@nocobase/dev-config/prettier",
12
12
  "files": [
13
- "skills"
13
+ "skills",
14
+ "!skills/nocobase-app-plugin-development/**/node_modules",
15
+ "!skills/nocobase-app-plugin-development/**/storage",
16
+ "!skills/nocobase-app-plugin-development/**/dist",
17
+ "!skills/nocobase-app-plugin-development/**/coverage"
14
18
  ],
15
19
  "publishConfig": {
16
20
  "access": "public"
@@ -4,16 +4,18 @@ description: >-
4
4
  Primary entry for building complete NocoBase 3 applications and individual features:
5
5
  business and administration pages, routes, components, endpoints, data, permissions, services, translations, and tests.
6
6
  Use this application-local workflow instead of globally installed NocoBase 2
7
- Skills. Do not use for a published NocoBase 3 plugin package.
7
+ Skills. For local or published NocoBase 3 plugin packages, use the project plugin development Skill.
8
8
  metadata:
9
9
  short-description: Develop features in a NocoBase 3 application
10
10
  ---
11
11
 
12
12
  # NocoBase 3 application development
13
13
 
14
+ When the task creates or maintains a plugin under this App's `packages/`, read `<app-root>/.agents/skills/nocobase-app-plugin-development/SKILL.md` by its explicit project path. It ships alongside this Skill in `@nocobase/app-skills`. Use this application's guidance for App-owned features and the plugin Skill for plugin-owned contracts and packaging; do not install the older global plugin development Skill.
15
+
14
16
  Use this Skill when building a complete application or an individual feature: business and administration pages, endpoints, data, services and their tests.
15
17
 
16
- Do not use it to develop a published plugin package. Plugin development has its own protocol and lives in a separate repository.
18
+ For plugin-owned code, use the project plugin development Skill, whether the plugin stays local to this App or is published for reuse. Plugin development does not require a separate repository or a NocoBase source checkout.
17
19
 
18
20
  Do not use it to upgrade the template this application was generated from, which is also how the application moves to a newer NocoBase version when the user asks to upgrade NocoBase or its core. That is `.agents/skills/nocobase-app-upgrade/`, which reconciles a newer template release against the application without reverting the user's work.
19
21
 
@@ -35,9 +37,11 @@ If instead you find `client/plugin.ts`, `server/plugin.ts`, or a `defineServerPl
35
37
 
36
38
  Do not infer the application's capabilities from a template name or from this Skill. Inspect `package.json`, `client/plugins.ts`, `server/plugins.ts`, `cli/plugins.ts`, `server/config/index.ts`, and `database/` before deciding what is installed, registered, configured, or application-owned. `nocobase.templatePackage` and `nocobase.templateKind` identify known template ancestry when present, but a new template remains valid without being listed here. Read [template variants](references/template-variants.md) only when those files identify one of the documented official templates.
37
39
 
38
- ## The one rule that decides most tasks
40
+ ## Choose where the feature belongs
41
+
42
+ 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. Create local plugins under `packages/` with the project plugin development Skill; do not use the source repository's `packages/plugins/` layout. The App builds and packages registered local plugins for deployment without an npm release. Publish only when distributing the plugin through a package registry.
39
43
 
40
- Build the feature in the application. Do not run a plugin generator, create a `packages/plugins/` directory, or write a `defineServerPlugin()` declaration for this application's own feature. Create a plugin only when the user explicitly asks for an independently published, reusable package. Ordinary internal workspace packages for shared code are different: when the application needs them, follow [internal workspace packages](references/dependencies.md#internal-workspace-packages), keeping one application at the workspace root with internal packages under `packages/`. The [runnable package example](references/internal-package-example.md) supplies complete configuration and explains declaration watching.
44
+ Ordinary internal workspace packages can share code without plugin registration. Follow [internal workspace packages](references/dependencies.md#internal-workspace-packages), keeping one application at the workspace root with internal packages under `packages/`. The [runnable package example](references/internal-package-example.md) supplies complete configuration and explains declaration watching.
41
45
 
42
46
  ## Check the installed plugins first
43
47
 
@@ -18,7 +18,7 @@ Keep page access independent from business action grants. Distinguish operations
18
18
 
19
19
  For new and existing features alike, classify the requested changes by content. Supported operations, fields/relations, resolver behavior and enforcement belong to the model; selecting supported scopes/parameters, grants, rules and recipients belongs to configuration. A request can require both. When developing a permission model, also complete its usable initial or adjusted business configuration from the responsibility matrix; do not stop at declarations unless the user explicitly asks for model-only work. Clarify unknown recipients without guessing assignments.
20
20
 
21
- Declare reusable collection permissions and business operations, defined as composite resources, in a feature module. In `server/providers/`, resolve `authorizationToken`, then register collections (`authz.database.collections.add`), composites (`authz.compositeResources.define`), record access (`authz.recordAccess.define`), settings items (`authz.settings.add`) and, when the feature owns a team or department model, inherited subjects (`authz.subjects.add`, built as [an organisation dimension](organization.md)); add workspace subsections with `authz.ui.sections.add` and list each composite or settings item in one with `authz.ui.place`. Pages are not registered on the server; the client routes list them. Read the authorization Skill’s bundled `references/code-and-seeds.md` before choosing initialization: code declares capabilities, provider boot registers them, and seeds initialize the agreed business configuration for fresh installations. Use authorized services or controlled data changes for existing installations. Seeded permission sets, selected scopes, rules and assignments remain editable in the backend; seeds do not make them code-owned or protected. App features own composite declarations and initial business configuration, not root/member protection or other platform permission configuration. Never rewrite administrator configuration at boot. Normal seeds have a restricted database context, not the running authorization service. Keep schema changes in migrations and initial assignments in idempotent seeds or controlled provisioning. Do not create a plugin package for an application-owned feature.
21
+ Declare reusable collection permissions and business operations, defined as composite resources, in a feature module. In `server/providers/`, resolve `authorizationToken`, then register collections (`authz.database.collections.add`), composites (`authz.compositeResources.define`), record access (`authz.recordAccess.define`), settings items (`authz.settings.add`) and, when the feature owns a team or department model, inherited subjects (`authz.subjects.add`, built as [an organisation dimension](organization.md)); add workspace subsections with `authz.ui.sections.add` and list each composite or settings item in one with `authz.ui.place`. Pages are not registered on the server; the client routes list them. Read the authorization Skill’s bundled `references/code-and-seeds.md` before choosing initialization: code declares capabilities, provider boot registers them, and seeds initialize the agreed business configuration for fresh installations. Use authorized services or controlled data changes for existing installations. Seeded permission sets, selected scopes, rules and assignments remain editable in the backend; seeds do not make them code-owned or protected. App features own composite declarations and initial business configuration, not root/member protection or other platform permission configuration. Never rewrite administrator configuration at boot. Normal seeds have a restricted database context, not the running authorization service. Keep schema changes in migrations and initial assignments in idempotent seeds or controlled provisioning. Keep permission declarations with the feature that owns them: in the App for application-owned features, or in the plugin when the feature is organized as a plugin.
22
22
 
23
23
  Every `server/routes/` endpoint installs authentication and authorization. A business operation checks `{ resource: { type: 'composite', id }, action }` with the request context's `authorize` once and binds each returned `conditions.database` policy through `repository.withPolicy`. Do not replace it with collection-level authorization or an in-memory filter. Use `authz.database.policyFor` for collection CRUD and `authz.database.authorizeRepository` for simple business Repository routes, mapping each method to its composite action. The authorization Skill documents these choices and their contracts.
24
24
 
@@ -139,43 +139,47 @@ The parent page, `client/pages/project-reports/index.tsx`:
139
139
  ```tsx
140
140
  import { useTranslation } from '@nocobase/i18n/client';
141
141
  import type { ReactElement } from 'react';
142
- import {
143
- matchPath,
144
- Navigate,
145
- NavLink,
146
- Outlet,
147
- useLocation,
148
- useResolvedPath,
149
- } from 'react-router';
142
+ import { Navigate, NavLink, Outlet } from 'react-router';
150
143
 
151
144
  import { PageContainer } from '#components/page-container';
145
+ import { useListTabs } from '#hooks/use-list-tabs';
152
146
  import { PageHeader } from '#components/page-header';
153
147
  import { buttonVariants } from '#components/ui/button';
154
148
  import { cn } from 'cn';
155
149
 
156
150
  export default function ProjectReportsPage(): ReactElement {
157
151
  const { t } = useTranslation();
158
- const location = useLocation();
159
- const parentPath = useResolvedPath('.');
160
- // Redirect to the default tab only when the URL is exactly the parent page (/project-reports or /project-reports/).
161
- const isParentEntry =
162
- matchPath({ path: parentPath.pathname, end: true }, location.pathname) !==
163
- null;
164
152
 
165
153
  // The order is the display order. Both tabs use the parent page's access, so the first one is the default tab.
166
154
  const tabs = [
167
- { path: 'summary', label: t('projectReports.tabs.summary') },
168
- { path: 'owners', label: t('projectReports.tabs.owners') },
155
+ {
156
+ path: 'summary',
157
+ dataset: 'summary',
158
+ label: t('projectReports.tabs.summary'),
159
+ },
160
+ {
161
+ path: 'owners',
162
+ dataset: 'owners',
163
+ label: t('projectReports.tabs.owners'),
164
+ },
169
165
  ];
170
166
 
171
- if (isParentEntry) {
167
+ const tabState = useListTabs({
168
+ tabs,
169
+ parameterKeys: [
170
+ 'q',
171
+ 'status',
172
+ 'page',
173
+ 'pageSize',
174
+ 'sort',
175
+ 'order',
176
+ 'orderBy',
177
+ ],
178
+ });
179
+
180
+ if (tabState.fallback) {
172
181
  // replace: leaves no parent URL in the history, so going back does not get redirected again.
173
- return (
174
- <Navigate
175
- replace
176
- to={{ pathname: tabs[0].path, search: location.search }}
177
- />
178
- );
182
+ return <Navigate replace to={tabState.fallback} />;
179
183
  }
180
184
 
181
185
  return (
@@ -196,14 +200,14 @@ export default function ProjectReportsPage(): ReactElement {
196
200
  'text-muted-foreground aria-[current=page]:bg-muted aria-[current=page]:text-foreground',
197
201
  )}
198
202
  key={tab.path}
199
- to={{ pathname: tab.path, search: location.search }}
203
+ to={tabState.destination(tab)}
200
204
  >
201
205
  {tab.label}
202
206
  </NavLink>
203
207
  ))}
204
208
  </nav>
205
- {/* Content of the current tab */}
206
- <Outlet />
209
+ {/* Detail pages can use this source in their declared breadcrumb. */}
210
+ <Outlet context={{ source: tabState.source }} />
207
211
  </PageContainer>
208
212
  );
209
213
  }
@@ -248,7 +252,7 @@ Behavior:
248
252
  - Opening `/project-reports?range=30d` redirects with `replace` to `/project-reports/summary?range=30d`.
249
253
  - Opening `/project-reports/owners` directly stays on "By owner".
250
254
  - Clicking a tab adds a history entry, and the content renders where the Outlet is; the sidebar keeps "Project reports" highlighted (tab routes have no menu entry, so the nearest ancestor is highlighted).
251
- - Switching tabs keeps the query string, so the parameters of the page this one covers survive it. A tab's own parameters, named apart from everything else ([section 5 of `table.md`](table.md#5-writing-search-and-filters-to-the-url)), may stay when switching tabs or be dropped, as the business decides; the page removes them when the user leaves ([section 7 of `page.md`](page.md#7-back-button-and-breadcrumbs)).
255
+ - `useListTabs` derives the selected tab from the route. Give different datasets different `dataset` values and list every parameter owned by these lists in `parameterKeys`; changing datasets clears those keys and starts the destination at its defaults, retaining enclosing-page parameters. Display tabs for the same dataset share a `dataset` value and retain compatible state. Pass only accessible tabs and `pending: true` while permission checks load; an absent/deleted tab then replaces the URL with the first accessible tab. Keep the parent route mounted for unknown descendants (for example a final `:unavailableTab` child with a null component and children matching the declared detail paths, such as `:id`; static tab routes take precedence) so it can apply that fallback; the global unmatched-route redirect cannot infer a tab owner.
252
256
 
253
257
  Tabs are implemented as links because they are page navigation, announced as links with `aria-current` on the selected one. To borrow the button look, apply `buttonVariants` to `NavLink`. `<Button render={<NavLink />}>` would announce each tab as a button, which is right for an action that opens a route ("New project", [section 2 of `styling.md`](styling.md#2-components-are-built-on-base-ui-not-radix)) but not for navigation. The `tabs` primitive is for tabs inside one view that are not routes: it brings the ARIA tab keyboard behavior, and its `TabsTrigger` elements sit inside `TabsList` (the skill's composition rules). Using it for route tabs would mean keeping its selected value in sync with the URL yourself.
254
258
 
@@ -421,28 +425,17 @@ The parent page checks the same permission with `useCan`: tabs without permissio
421
425
  import { useCan } from '@nocobase/app-plugin-authorization/client';
422
426
  import { useTranslation } from '@nocobase/i18n/client';
423
427
  import type { ReactElement } from 'react';
424
- import {
425
- matchPath,
426
- Navigate,
427
- NavLink,
428
- Outlet,
429
- useLocation,
430
- useResolvedPath,
431
- } from 'react-router';
428
+ import { Navigate, NavLink, Outlet } from 'react-router';
432
429
 
433
430
  import { Loading } from '#components/loading';
434
431
  import { PageContainer } from '#components/page-container';
432
+ import { useListTabs } from '#hooks/use-list-tabs';
435
433
  import { PageHeader } from '#components/page-header';
436
434
  import { buttonVariants } from '#components/ui/button';
437
435
  import { cn } from 'cn';
438
436
 
439
437
  export default function ProjectReportsPage(): ReactElement {
440
438
  const { t } = useTranslation();
441
- const location = useLocation();
442
- const parentPath = useResolvedPath('.');
443
- const isParentEntry =
444
- matchPath({ path: parentPath.pathname, end: true }, location.pathname) !==
445
- null;
446
439
  // Keep in sync with the authz of the owners child route in routes.ts.
447
440
  const ownersAccess = useCan({
448
441
  resource: { type: 'page', id: 'project-reports-owners' },
@@ -452,13 +445,36 @@ export default function ProjectReportsPage(): ReactElement {
452
445
  // Tabs without permission are not shown. can is false while the check is pending and when it fails, so a failed check
453
446
  // hides the tab like a denial (page.md section 8); the tab route's own check still decides a direct URL.
454
447
  const tabs = [
455
- { path: 'summary', label: t('projectReports.tabs.summary') },
448
+ {
449
+ path: 'summary',
450
+ dataset: 'summary',
451
+ label: t('projectReports.tabs.summary'),
452
+ },
456
453
  ...(ownersAccess.can
457
- ? [{ path: 'owners', label: t('projectReports.tabs.owners') }]
454
+ ? [
455
+ {
456
+ path: 'owners',
457
+ dataset: 'owners',
458
+ label: t('projectReports.tabs.owners'),
459
+ },
460
+ ]
458
461
  : []),
459
462
  ];
460
463
 
461
- if (isParentEntry) {
464
+ const tabState = useListTabs({
465
+ tabs,
466
+ parameterKeys: [
467
+ 'q',
468
+ 'status',
469
+ 'page',
470
+ 'pageSize',
471
+ 'sort',
472
+ 'order',
473
+ 'orderBy',
474
+ ],
475
+ });
476
+
477
+ if (tabState.fallback) {
462
478
  // Redirecting before the permission check finishes may land on the wrong tab: show a loading state first.
463
479
  if (ownersAccess.isPending) {
464
480
  return (
@@ -471,12 +487,7 @@ export default function ProjectReportsPage(): ReactElement {
471
487
  }
472
488
  // The business specifies "By owner" as the default tab; when it is not accessible, use the first accessible tab.
473
489
  const target = tabs.find((tab) => tab.path === 'owners') ?? tabs[0];
474
- return (
475
- <Navigate
476
- replace
477
- to={{ pathname: target.path, search: location.search }}
478
- />
479
- );
490
+ return <Navigate replace to={tabState.destination(target)} />;
480
491
  }
481
492
 
482
493
  return (
@@ -497,14 +508,14 @@ export default function ProjectReportsPage(): ReactElement {
497
508
  'text-muted-foreground aria-[current=page]:bg-muted aria-[current=page]:text-foreground',
498
509
  )}
499
510
  key={tab.path}
500
- to={{ pathname: tab.path, search: location.search }}
511
+ to={tabState.destination(tab)}
501
512
  >
502
513
  {tab.label}
503
514
  </NavLink>
504
515
  ))}
505
516
  </nav>
506
- {/* Content of the current tab */}
507
- <Outlet />
517
+ {/* Detail pages can use this source in their declared breadcrumb. */}
518
+ <Outlet context={{ source: tabState.source }} />
508
519
  </PageContainer>
509
520
  );
510
521
  }
@@ -645,3 +656,28 @@ A page that shows a record whose detail is a page of its own — an orders list'
645
656
  9. Pages with tabs whose header opens overlays: from a tab other than the default, open each one. Its URL is the tab's URL plus its own segment, the tab stays selected and its content mounted behind it, and closing, saving, Esc and Back all return to that tab; opening that URL directly shows the same tab behind it.
646
657
 
647
658
  Write these behaviors as tests in `tests/` (see [`testing.md`](testing.md)).
659
+
660
+ ## List-tab breadcrumbs and private conditions
661
+
662
+ Register each detail under its actual list tab, including when several tabs open the same detail component. The list places `Outlet` after its table and the detail returns `RouteChildPage`; this is a full child page, not a dialog. Keep sensitive conditions in the mounted list's `useState` only. Do not put them in URLs, history state, browser storage, logs or a global cache. Refresh resets them; the template's identity-keyed session boundary unmounts the list on account changes. Keep page and sorting state in that same local owner when they depend on private conditions, and reset the page when a condition changes.
663
+
664
+ A private condition must filter the complete authorized dataset before computing its total and slicing a page; filtering only the fetched server page loses matching records and leaves the total wrong. For a small bounded dataset, fetch the complete authorized collection through its existing API and keep the condition, dependent pagination and sorting in list memory. For larger data, use an existing approved private query channel rather than adding URL or persistent state. Changing or clearing the condition starts at page one. Test with a condition that matches a record outside the previously visible page, then verify the total, all three return paths, refresh and account changes.
665
+
666
+ For a tab layout that supplies its own breadcrumb, pass `tabState.source` through outlet context and use it as the list level of `usePageBreadcrumb` in the detail, followed by the detail's label. This links directly to the source tab and its recorded list query instead of the tab group's default redirect. Keep existing enclosing breadcrumb levels. A direct detail has no recorded list query and uses the source tab's default list. The standard `BackButton` follows the actual parent tab; browser Back follows its original history entry. Never hard-code the other module's list for a shared detail.
667
+
668
+ Declare a final child under the tab group with `path: ":unavailableTab"`, a null component, and fallback children matching every supported detail shape. For example:
669
+
670
+ ```ts
671
+ {
672
+ name: "reports-unavailable-tab",
673
+ path: ":unavailableTab",
674
+ componentLoader: () => import("./missing-tab.js"),
675
+ children: [{
676
+ name: "reports-unavailable-detail",
677
+ path: ":id",
678
+ componentLoader: () => import("./missing-tab.js"),
679
+ }],
680
+ }
681
+ ```
682
+
683
+ `missing-tab.js` default-exports a component returning `null`. Include any deeper supported routes (such as `:id/edit`) as well: a single `:unavailableTab` only matches the list URL and cannot recover `/reports/deleted/42`. The parent `useListTabs` fallback handles it. The runtime does not accept wildcard page paths. Give this route the same inherited access boundary as its parent and no menu or breadcrumb.
@@ -1,5 +1,7 @@
1
1
  # Delete confirmation: `project-delete-dialog.tsx`
2
2
 
3
+ Use the parent list's shared `useListData().reload` after a confirmed success. For partial batch success, wait for every outcome, keep failed ids and errors, and refresh once; do not decrement a total optimistically. For an uncertain network result verify the list without automatically replaying the delete. See [list recovery](../table.md#delete-and-recover-a-list).
4
+
3
5
  Part of the [projects worked example](../example.md).
4
6
 
5
7
  **Depends on**: [session alert](session-expired-alert.md), [types](types.md), [copy](copy.md).
@@ -36,6 +38,8 @@ export interface ProjectDeleteDialogProps {
36
38
  readonly project: Pick<Project, 'id' | 'name'> | null | undefined;
37
39
  /** Called when the delete succeeds or the record was already deleted by someone else (404). The parent closes the confirmation dialog (or the whole drawer) and refreshes the list. */
38
40
  readonly onDeleted: () => void;
41
+ /** Verify server state after an uncertain response without replaying the delete. */
42
+ readonly onUncertain: () => void;
39
43
  /** Where focus goes after the delete. The button that opened the confirmation dialog usually disappears along with the record (guideline A6). */
40
44
  readonly deletedFocusRef?: RefObject<HTMLElement | null>;
41
45
  }
@@ -45,6 +49,7 @@ export function ProjectDeleteDialog({
45
49
  onOpenChange,
46
50
  project,
47
51
  onDeleted,
52
+ onUncertain,
48
53
  deletedFocusRef,
49
54
  }: ProjectDeleteDialogProps): ReactElement {
50
55
  const { t } = useTranslation();
@@ -72,6 +77,7 @@ export function ProjectDeleteDialog({
72
77
  });
73
78
  } catch (caught: unknown) {
74
79
  const status = caught instanceof ApiClientError ? caught.status : 0;
80
+ if (status === 0 || status >= 500) onUncertain();
75
81
  if (status !== 404) {
76
82
  // Other failures: keep the confirmation dialog open and explain the reason inside it, without showing the backend's raw message.
77
83
  setError(
@@ -171,7 +171,11 @@ function ProjectDetail({
171
171
  // Show no record actions before the record has loaded or when it does not exist.
172
172
  footer={
173
173
  project ? (
174
- <ProjectDetailActions project={project} onDeleted={afterDelete} />
174
+ <ProjectDetailActions
175
+ project={project}
176
+ onDeleted={afterDelete}
177
+ onUncertain={reloadPage}
178
+ />
175
179
  ) : undefined
176
180
  }
177
181
  >
@@ -189,9 +193,11 @@ function ProjectDetail({
189
193
  function ProjectDetailActions({
190
194
  project,
191
195
  onDeleted,
196
+ onUncertain,
192
197
  }: {
193
198
  readonly project: Project;
194
199
  readonly onDeleted: () => void;
200
+ readonly onUncertain: () => void;
195
201
  }): ReactElement {
196
202
  const { t } = useTranslation();
197
203
  const location = useLocation();
@@ -212,6 +218,7 @@ function ProjectDetailActions({
212
218
  </Button>
213
219
  {/* The delete confirmation uses component state. On success, first let the list refresh and arrange focus, then close the drawer. */}
214
220
  <ProjectDeleteDialog
221
+ onUncertain={onUncertain}
215
222
  open={deleteOpen}
216
223
  onOpenChange={setDeleteOpen}
217
224
  project={project}
@@ -12,9 +12,11 @@ Part of the [projects worked example](../example.md).
12
12
 
13
13
  Rules: sections [3](../table.md#3-known-datatable-behavior), [5](../table.md#5-writing-search-and-filters-to-the-url), [6](../table.md#6-loading-the-list), [7](../table.md#7-the-four-list-states), [8](../table.md#8-column-definitions-and-row-actions) and [9](../table.md#9-child-routes-and-refreshing-the-list) of `table.md`.
14
14
 
15
+ For deletion recovery and URL-backed pagination use the shared hooks in [delete and recover a list](../table.md#delete-and-recover-a-list), with the integration in [the server table example](server-table.md). The capped client example below corrects local pages only while the response is complete; use server pagination when the cap is exceeded. For complete client data pass the filtered row count to the same URL hook and keep `manualPagination` off. Child delete callbacks must use the shared `reload` from their parent, including on return from detail; batch callbacks refresh only after all outcomes settle.
16
+
15
17
  ```tsx
16
18
  // client/pages/projects/index.tsx
17
- import { ApiClientError, useApiClient } from '@nocobase/app-client';
19
+ import { ApiClientError } from '@nocobase/app-client';
18
20
  import { useLocale, useTranslation } from '@nocobase/i18n/client';
19
21
  import type { ColumnDef } from '@tanstack/react-table';
20
22
  import {
@@ -26,19 +28,15 @@ import {
26
28
  SearchIcon,
27
29
  Trash2Icon,
28
30
  } from 'lucide-react';
29
- import {
30
- type ReactElement,
31
- useEffect,
32
- useMemo,
33
- useReducer,
34
- useRef,
35
- useState,
36
- } from 'react';
31
+ import { type ReactElement, useEffect, useMemo, useRef, useState } from 'react';
37
32
  import { Link, Outlet, useLocation } from 'react-router';
38
33
 
39
34
  import { DataTable } from '#components/data-table';
40
35
  import { DataTableColumnHeader } from '#components/data-table/column-header';
41
36
  import { useUrlSearch } from '#hooks/use-url-search';
37
+ import { useListData } from '#hooks/use-list-data';
38
+ import { useListLocation } from '#hooks/use-list-location';
39
+ import { useTableUrlState } from '#hooks/use-table-url-state';
42
40
  import { PageContainer } from '#components/page-container';
43
41
  import { PageHeader } from '#components/page-header';
44
42
  import { SessionExpiredAlert } from '#components/session-expired-alert';
@@ -104,14 +102,13 @@ function isProjectStatus(value: string | null): value is ProjectStatus {
104
102
  export default function ProjectsPage(): ReactElement {
105
103
  const { t } = useTranslation();
106
104
  const { locale } = useLocale();
107
- const api = useApiClient();
108
105
  const location = useLocation();
109
106
  const searchRef = useRef<HTMLInputElement>(null);
110
107
 
111
108
  // The search term lives in the URL behind a search box that keeps its own text (url-search.md): typing, input
112
109
  // methods, back and forward all stay in step. The status filter is read from the same parameters.
113
110
  const { searchParams, search, text, inputProps, updateParams, clear } =
114
- useUrlSearch();
111
+ useUrlSearch({ resetParams: ['page'] });
115
112
  const statusParam = searchParams.get('status');
116
113
  // Treat an unrecognized value as no filter.
117
114
  const status = isProjectStatus(statusParam) ? statusParam : undefined;
@@ -120,6 +117,7 @@ export default function ProjectsPage(): ReactElement {
120
117
  updateParams((params) => {
121
118
  if (value && value !== 'all') params.set('status', value);
122
119
  else params.delete('status');
120
+ params.delete('page');
123
121
  });
124
122
  }
125
123
 
@@ -132,59 +130,35 @@ export default function ProjectsPage(): ReactElement {
132
130
  searchRef.current?.focus();
133
131
  }
134
132
 
135
- // Load the list. An effect must not call setState synchronously: store the result only in the request callbacks,
136
- // and derive "loading" from whether the result belongs to the current request.
137
- // Each reload() call increments the count, and the effect requests again.
138
- const [reloadCount, reload] = useReducer((count: number) => count + 1, 0);
139
- const requestKey = JSON.stringify([search, status ?? null, reloadCount]);
140
- const [result, setResult] = useState<{
141
- readonly key: string;
142
- readonly rows?: Project[];
143
- /** Whether this batch was fetched with filters; tells "empty" apart from "no results". */
144
- readonly filtered?: boolean;
145
- readonly error?: unknown;
146
- /** The number of matching records on all pages; more than rows.length when the page cap cut the list. */
147
- readonly total?: number;
148
- }>();
149
-
150
- useEffect(() => {
151
- // Abort the request when the filters change or the component unmounts, so an old result never overwrites a new one.
152
- const controller = new AbortController();
153
- const key = JSON.stringify([search, status ?? null, reloadCount]);
154
- api
155
- .request<ProjectList>({
156
- path: 'projects',
157
- query: { q: search || undefined, status, pageSize: PAGE_SIZE },
158
- signal: controller.signal,
159
- })
160
- .then(
161
- ({ data, meta }) => {
162
- if (!controller.signal.aborted) {
163
- setResult({
164
- key,
165
- rows: data,
166
- total: meta.total,
167
- filtered: search !== '' || status !== undefined,
168
- });
169
- }
170
- },
171
- (error: unknown) => {
172
- // Keep the previous batch on failure: after "Retry", show the old data and a small Spinner, not the skeleton.
173
- if (!controller.signal.aborted) {
174
- setResult((previous) => ({ ...previous, key, error }));
175
- }
176
- },
177
- );
178
- return () => controller.abort();
179
- }, [api, search, status, reloadCount]);
180
-
181
- const loading = result?.key !== requestKey;
182
- const error = loading ? undefined : result?.error;
183
- // While reloading, rows is still the previous batch.
184
- const rows = result?.rows;
185
- // Decide by the filters the displayed data was fetched with, not by the current filters:
186
- // right after "Clear filters" is clicked, the screen still shows the old filtered result.
187
- const rowsFiltered = result?.filtered ?? false;
133
+ const { active } = useListLocation();
134
+ const remote = new URLSearchParams({
135
+ q: search,
136
+ ...(status ? { status } : {}),
137
+ pageSize: String(PAGE_SIZE),
138
+ });
139
+ const request = useListData<ProjectList>(`projects?${remote}`, {
140
+ active,
141
+ keepPreviousData: true,
142
+ });
143
+ const rows = request.data?.data;
144
+ const result = request.data ? { total: request.data.meta.total } : undefined;
145
+ const loading = request.loading;
146
+ const tableState = useTableUrlState({
147
+ active,
148
+ revision: request.revision,
149
+ sortColumns: ['name', 'updatedAt'],
150
+ // Only a complete filtered dataset supports local last-page recovery.
151
+ rowCount:
152
+ !loading && !request.error && rows?.length === result?.total
153
+ ? result?.total
154
+ : undefined,
155
+ });
156
+ const reload = request.reload;
157
+ const error = tableState.error ?? request.error;
158
+ const displayedQuery = new URLSearchParams(request.path.split('?')[1]);
159
+ const rowsFiltered = Boolean(
160
+ displayedQuery.get('q') || displayedQuery.get('status'),
161
+ );
188
162
 
189
163
  // After a record is deleted in the drawer, its row and the link that opened the drawer disappear once the list refreshes:
190
164
  // wait for the refresh to finish, then move focus to the search box (guideline A6).
@@ -419,6 +393,7 @@ export default function ProjectsPage(): ReactElement {
419
393
  </p>
420
394
  ) : null}
421
395
  <DataTable
396
+ {...tableState}
422
397
  columns={columns}
423
398
  data={rows}
424
399
  getRowId={(row) => row.id}
@@ -503,6 +478,7 @@ export default function ProjectsPage(): ReactElement {
503
478
  {content}
504
479
 
505
480
  <ProjectDeleteDialog
481
+ onUncertain={reload}
506
482
  open={deletion.open}
507
483
  onOpenChange={(open) =>
508
484
  setDeletion((current) => ({ ...current, open }))