@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.
- package/package.json +7 -3
- package/skills/nocobase-app-development/SKILL.md +8 -4
- package/skills/nocobase-app-development/references/authorization.md +1 -1
- package/skills/nocobase-app-development/references/frontend/references/child-routes.md +88 -52
- package/skills/nocobase-app-development/references/frontend/references/example/delete-dialog.md +6 -0
- package/skills/nocobase-app-development/references/frontend/references/example/detail-drawer.md +8 -1
- package/skills/nocobase-app-development/references/frontend/references/example/list-page.md +40 -64
- package/skills/nocobase-app-development/references/frontend/references/example/project-form.md +69 -33
- package/skills/nocobase-app-development/references/frontend/references/example/server-table.md +57 -110
- package/skills/nocobase-app-development/references/frontend/references/example/session-expired-alert.md +24 -7
- package/skills/nocobase-app-development/references/frontend/references/example/settings-form.md +10 -2
- package/skills/nocobase-app-development/references/frontend/references/form.md +47 -4
- package/skills/nocobase-app-development/references/frontend/references/page.md +6 -2
- package/skills/nocobase-app-development/references/frontend/references/table.md +19 -3
- package/skills/nocobase-app-development/references/frontend/references/ui-library.md +17 -2
- package/skills/nocobase-app-development/references/lifecycle-ui.md +2 -2
- package/skills/nocobase-app-development/references/plugins.md +20 -2
- package/skills/nocobase-app-development/references/submission.md +62 -0
- package/skills/nocobase-app-plugin-development/SKILL.md +68 -0
- package/skills/nocobase-app-plugin-development/agents/openai.yaml +6 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/cli/count.ts +14 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/cli/index.ts +10 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/client/index.ts +16 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/client/locales/de-DE.ts +10 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/client/locales/en-US.ts +11 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/client/locales/es-ES.ts +10 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/client/locales/fr-FR.ts +10 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/client/locales/id-ID.ts +10 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/client/locales/index.ts +16 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/client/locales/ja-JP.ts +10 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/client/locales/pt-BR.ts +10 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/client/locales/vi-VN.ts +10 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/client/locales/zh-CN.ts +10 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/client/locales/zh-TW.ts +10 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/client/public-config.ts +13 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/client/reading-list.tsx +56 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/database/migrations/202610180001_reading_list.ts +16 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/eslint.config.js +6 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/package.json +49 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/server/config.ts +39 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/server/index.ts +22 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/server/provider.ts +31 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/server/providers/index.ts +5 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/server/routes.ts +56 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/server/service.ts +35 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/tests/cli/count.test.ts +55 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/tests/client/public-config.test.tsx +19 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/tests/client/reading-list.test.tsx +87 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/tests/database/migration.test.ts +26 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/tests/fixtures/app/package.json +5 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/tests/fixtures/app/server/app.ts +19 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/tests/fixtures/app/server/runtime.ts +67 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/tests/fixtures/app/server/standalone.ts +31 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/tests/helpers/app.ts +27 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/tests/server/config.test.ts +38 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/tests/server/routes.test.ts +50 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/tsconfig.json +16 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/vitest.config.ts +34 -0
- package/skills/nocobase-app-plugin-development/references/cli.md +363 -0
- package/skills/nocobase-app-plugin-development/references/client-api.md +222 -0
- package/skills/nocobase-app-plugin-development/references/client-child-routes.md +351 -0
- package/skills/nocobase-app-plugin-development/references/client-components.md +272 -0
- package/skills/nocobase-app-plugin-development/references/client-examples.md +641 -0
- package/skills/nocobase-app-plugin-development/references/client-pages-and-routes.md +125 -0
- package/skills/nocobase-app-plugin-development/references/client-routing.md +159 -0
- package/skills/nocobase-app-plugin-development/references/client.md +162 -0
- package/skills/nocobase-app-plugin-development/references/configuration.md +65 -0
- package/skills/nocobase-app-plugin-development/references/database.md +225 -0
- package/skills/nocobase-app-plugin-development/references/http-api.md +184 -0
- package/skills/nocobase-app-plugin-development/references/i18n.md +374 -0
- package/skills/nocobase-app-plugin-development/references/plugin-foundation.md +203 -0
- package/skills/nocobase-app-plugin-development/references/plugin-skills.md +118 -0
- package/skills/nocobase-app-plugin-development/references/registration.md +135 -0
- package/skills/nocobase-app-plugin-development/references/registry.md +11 -0
- package/skills/nocobase-app-plugin-development/references/repository-examples.md +264 -0
- package/skills/nocobase-app-plugin-development/references/server-route-examples.md +518 -0
- package/skills/nocobase-app-plugin-development/references/server.md +291 -0
- package/skills/nocobase-app-plugin-development/references/service-examples.md +470 -0
- package/skills/nocobase-app-plugin-development/references/services.md +188 -0
- package/skills/nocobase-app-plugin-development/references/system-settings.md +106 -0
- package/skills/nocobase-app-plugin-development/references/testing-example.md +59 -0
- package/skills/nocobase-app-plugin-development/references/testing.md +139 -0
- package/skills/nocobase-app-plugin-development/references/theme-tokens.md +105 -0
- package/skills/nocobase-app-plugin-development/scripts/verify-testing-example.mjs +90 -0
- package/skills/nocobase-app-upgrade/SKILL.md +32 -4
- package/skills/nocobase-app-upgrade/references/edge-cases.md +2 -0
- package/skills/nocobase-app-upgrade/references/form-feedback-upgrade.md +36 -0
- package/skills/nocobase-app-upgrade/references/list-navigation-upgrade.md +35 -3
- package/skills/nocobase-app-upgrade/references/plugin-development-skill.md +32 -0
- package/skills/nocobase-app-upgrade/references/submission-upgrade.md +18 -0
- package/skills/nocobase-app-upgrade/references/versioned-upgrade-verification.md +25 -0
- 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.
|
|
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.
|
|
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
|
-
|
|
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
|
-
##
|
|
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
|
-
|
|
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.
|
|
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
|
-
{
|
|
168
|
-
|
|
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
|
-
|
|
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={
|
|
203
|
+
to={tabState.destination(tab)}
|
|
200
204
|
>
|
|
201
205
|
{tab.label}
|
|
202
206
|
</NavLink>
|
|
203
207
|
))}
|
|
204
208
|
</nav>
|
|
205
|
-
{/*
|
|
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
|
-
-
|
|
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
|
-
{
|
|
448
|
+
{
|
|
449
|
+
path: 'summary',
|
|
450
|
+
dataset: 'summary',
|
|
451
|
+
label: t('projectReports.tabs.summary'),
|
|
452
|
+
},
|
|
456
453
|
...(ownersAccess.can
|
|
457
|
-
? [
|
|
454
|
+
? [
|
|
455
|
+
{
|
|
456
|
+
path: 'owners',
|
|
457
|
+
dataset: 'owners',
|
|
458
|
+
label: t('projectReports.tabs.owners'),
|
|
459
|
+
},
|
|
460
|
+
]
|
|
458
461
|
: []),
|
|
459
462
|
];
|
|
460
463
|
|
|
461
|
-
|
|
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={
|
|
511
|
+
to={tabState.destination(tab)}
|
|
501
512
|
>
|
|
502
513
|
{tab.label}
|
|
503
514
|
</NavLink>
|
|
504
515
|
))}
|
|
505
516
|
</nav>
|
|
506
|
-
{/*
|
|
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.
|
package/skills/nocobase-app-development/references/frontend/references/example/delete-dialog.md
CHANGED
|
@@ -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(
|
package/skills/nocobase-app-development/references/frontend/references/example/detail-drawer.md
CHANGED
|
@@ -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
|
|
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
|
|
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
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
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 }))
|