@nocobase/app-skills 0.1.0-beta.49 → 0.1.0-beta.50

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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nocobase/app-skills",
3
- "version": "0.1.0-beta.49",
3
+ "version": "0.1.0-beta.50",
4
4
  "description": "Agent Skills for developing, upgrading and deploying NocoBase applications.",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -44,7 +44,7 @@ Default to named users selected through User management → Assign roles. Do not
44
44
 
45
45
  A global default is supported only when the user explicitly requests it and the application delivers an authorized administration control to inspect its recipient population, change the default role and revoke that assignment. User access details must distinguish direct roles from inherited roles and link to the source. If those controls are unavailable, explain the limitation and use explicit user assignments instead. Never invent a configuration flag, seed-only setting or undocumented SQL instruction as the administrator's normal adjustment interface.
46
46
 
47
- Retain and run `pnpm exec vitest run tests/logic/authorization-assignment-safety.test.ts` from the template. The test starts the real application on an isolated database, including registered migrations/seeds, and checks actual global assignments and member grants rather than searching source literals. When adding a genuinely requested global default, extend the expected baseline narrowly only after delivering the management UI and testing its visibility, update, revocation and authorization. Record that deliberate exception with the feature's tests; never delete or skip the guard. This test covers initialized state, not every later administrative write or custom subject resolver; also test effective access and direct API denials with ordinary identities.
47
+ Retain and run `pnpm exec vitest run tests/server/authorization-assignment-safety.test.ts` from the template. The test starts the real application on an isolated database, including registered migrations/seeds, and checks actual global assignments and member grants rather than searching source literals. When adding a genuinely requested global default, extend the expected baseline narrowly only after delivering the management UI and testing its visibility, update, revocation and authorization. Record that deliberate exception with the feature's tests; never delete or skip the guard. This test covers initialized state, not every later administrative write or custom subject resolver; also test effective access and direct API denials with ordinary identities.
48
48
 
49
49
  For page-access presentation, compose `section.navigation` from the application's complete runtime menu hierarchy and its existing navigation transforms, without filtering the catalog by the signed-in editor's own visible menus. Reference stable page row ids, deduplicate inherited/shared page grants, retain independently protected non-menu pages, and keep flat menus at one level. Structural groups only expand/collapse; actual parent pages and child pages have independent checkboxes. Searching retains ancestor context and never changes grants. See the permission-editor Registry contract for its optional navigation nodes and translated disclosure labels. The page-access tree contains business pages only. Group all actual system-settings pages and operations, including user management and business configuration, under Configuration permissions; preserve original row ids and grants, avoid duplicate page controls or category-jump placeholders, and explain the boundary in section descriptions.
50
50
 
@@ -119,8 +119,8 @@ pnpm exec vitest run <related-test-files>
119
119
  - Primitives the change added are changed files too: formatted with Prettier, their built-in English translated as ["English built into primitives"](references/shadcn.md#english-built-into-primitives) lists, and otherwise exactly what the CLI wrote.
120
120
  - Lint does not check the shadcn skill's "Critical Rules". Read the changed components against them: items inside their groups, `gap-*` rather than `space-*`, `data-icon` and no sizing classes on icons inside components, full `Card` structure, semantic tokens ([`references/shadcn.md`](references/shadcn.md)).
121
121
  - Choose the related tests by searching `tests/` for the changed component, page or route name.
122
- - A changed route always includes `tests/logic/client-routes.test.ts`.
123
- - A changed `t()` key or route title always includes `tests/logic/app-locale-coverage.test.ts`; what it does not catch is in ["Checks" in `i18n.md`](references/i18n.md#checks).
122
+ - A changed route always includes `tests/client/client-routes.test.ts`.
123
+ - A changed `t()` key or route title always includes `tests/client/app-locale-coverage.test.ts`; what it does not catch is in ["Checks" in `i18n.md`](references/i18n.md#checks).
124
124
  - Confirm that every test file you named ran: see ["Running tests" in `testing.md`](references/testing.md#running-tests).
125
125
  - When you changed server or database code as well, also run `pnpm exec tsc -p tsconfig.server.json --noEmit`.
126
126
  - When you changed a browser test under `tests/playwright/`, also run `pnpm exec tsc -p tsconfig.node.json --noEmit`, which covers `tests/playwright/` once Playwright is set up (an application without it sets it up first, as [`references/testing.md`](references/testing.md) describes).
@@ -421,11 +421,11 @@ export default function CustomerOverviewTab(): ReactElement {
421
421
 
422
422
  ## The test
423
423
 
424
- `tests/components/customer-page.test.tsx` renders the page with the routes `customerDetailRoutes` declares, written out, and opens the header's "Edit" from every tab, which catches a tab that does not pass the page's context on through its `Outlet`; that every tab declares the header's overlays is the route test's to check (below). It then goes back to check that the list gets exactly its own parameters:
424
+ `tests/client/customer-page.test.tsx` renders the page with the routes `customerDetailRoutes` declares, written out, and opens the header's "Edit" from every tab, which catches a tab that does not pass the page's context on through its `Outlet`; that every tab declares the header's overlays is the route test's to check (below). It then goes back to check that the list gets exactly its own parameters:
425
425
 
426
426
  ```tsx
427
- // tests/components/customer-page.test.tsx
428
- // The setup of tests/components/page-harness.test.tsx — its vi.hoisted values and every vi.mock — unchanged; only
427
+ // tests/client/customer-page.test.tsx
428
+ // The setup of tests/client/page-harness.test.tsx — its vi.hoisted values and every vi.mock — unchanged; only
429
429
  // what differs is shown. The runtime reads the application's own locale files,
430
430
  // where the customer copy lives, so the queries name what the user reads.
431
431
  import {
@@ -582,10 +582,10 @@ describe('customer page', () => {
582
582
 
583
583
  ## The route test
584
584
 
585
- Every page that declares `customerDetailRoutes` adds a route per tab and per overlay under each tab to the page grant list of `tests/logic/client-routes.test.ts` ([section 12 of `page.md`](../page.md#12-update-the-route-test)). A helper in the test spells out one owner's set, with its names and authorization written literally rather than taken from the application's function, whose output is what the test checks:
585
+ Every page that declares `customerDetailRoutes` adds a route per tab and per overlay under each tab to the page grant list of `tests/client/client-routes.test.ts` ([section 12 of `page.md`](../page.md#12-update-the-route-test)). A helper in the test spells out one owner's set, with its names and authorization written literally rather than taken from the application's function, whose output is what the test checks:
586
586
 
587
587
  ```ts
588
- // tests/logic/client-routes.test.ts, in 'pins the page authorization of every signed-in page'
588
+ // tests/client/client-routes.test.ts, in 'pins the page authorization of every signed-in page'
589
589
  expect(pageAuthorizations(resolved.routes)).toEqual([
590
590
  { name: 'home', authorizedAs: null },
591
591
  { name: 'customers', authorizedAs: null },
@@ -22,7 +22,7 @@ Rules:
22
22
  - Add menu titles to the existing `navigation` group (`navigation.projects`), and write `navigation: { title: 'navigation.projects' }` in the route (see [`page.md`](page.md)).
23
23
  - Add the key to `en-US.ts` first, then add the same key to `zh-CN.ts`. A key missing from `zh-CN.ts` or extra in it (including a misspelled one) fails type checking.
24
24
  - The sign-in pages' copy is the flat `auth.*` keys; the authentication blocks in `client/extensions/nocobase-auth-*/` take their text as props, so `client/pages/auth/` passes these translations in.
25
- - **Keys passed to `t()` are not type-checked.** `t('projects.titel')` compiles, and the page shows `projects.titel` as is. `tests/logic/app-locale-coverage.test.ts` catches it; run it after every copy change (its limits are in ["Checks"](#checks)).
25
+ - **Keys passed to `t()` are not type-checked.** `t('projects.titel')` compiles, and the page shows `projects.titel` as is. `tests/client/app-locale-coverage.test.ts` catches it; run it after every copy change (its limits are in ["Checks"](#checks)).
26
26
  - The English built into a few shadcn/ui primitives, such as the visually hidden "Close" of `Sheet`, is translated too (guideline C1): pass the translation as a prop where the primitive takes one, and otherwise replace the literal in the primitive with a key. ["English built into primitives" in `shadcn.md`](shadcn.md#english-built-into-primitives) lists each case.
27
27
 
28
28
  ## Existing shared keys
@@ -371,7 +371,7 @@ To add a language (Japanese as the example):
371
371
  Limit these to the changed files and the parts they affect:
372
372
 
373
373
  - `pnpm exec tsc -p tsconfig.json --noEmit`: reports keys missing from or extra in the Chinese locale. It does not check whether the keys used in `t()` exist.
374
- - `pnpm exec vitest run tests/logic/app-locale-coverage.test.ts`: reports every literal key the code uses (`t('…')` calls, including ones Prettier wrapped, and route `title`s) that either locale lacks, and every dynamic family (``t(`…${x}`)`` or `t('….' + x)`) with no key under its prefix. It does not check each value of a family: a missing `projects.status.done` passes while `projects.status.active` exists, so write one entry per value and look at each in the browser. It skips files that translate in a plugin's namespace (`useTranslation('@nocobase/…')`); a key held in data and passed as `t(item.key)` is not seen, so check those in the browser.
374
+ - `pnpm exec vitest run tests/client/app-locale-coverage.test.ts`: reports every literal key the code uses (`t('…')` calls, including ones Prettier wrapped, and route `title`s) that either locale lacks, and every dynamic family (``t(`…${x}`)`` or `t('….' + x)`) with no key under its prefix. It does not check each value of a family: a missing `projects.status.done` passes while `projects.status.active` exists, so write one entry per value and look at each in the browser. It skips files that translate in a plugin's namespace (`useTranslation('@nocobase/…')`); a key held in data and passed as `t(item.key)` is not seen, so check those in the browser.
375
375
  - After adding or removing a language: `pnpm nocobase locales check` (see "Adding a language").
376
376
  - Look at the page in the browser in each language: no leftover English or Chinese, no key names; also check `aria-label`, placeholders, toasts and validation messages.
377
377
  - Switch the language without reloading and check that the page follows: column headers, options, validation messages and date formats all update.
@@ -208,7 +208,7 @@ A page and the endpoints it calls must agree: the example's `/api/projects` is o
208
208
 
209
209
  Every application route that resolves to a `page` permission needs a non-empty, translated display name, including URL-addressable forms, dialogs, drawers and detail pages. Navigation/breadcrumb titles provide it where already appropriate. For a page that intentionally has neither (especially an overlay), add its existing application route `name` and a static application translation key to `client/pages/settings/page-permission-titles.ts`. This mapping labels permissions only; do not add a menu/breadcrumb or change a route name, `authz.resource.id`, inheritance, `'skip'` or stored grants to repair copy. Plugin routes retain their owning namespace and are not overridden by an application's same-named route.
210
210
 
211
- Provide English and Chinese text without unresolved interpolation placeholders. The permission catalog uses `pagePermissionResources()` and a localized unnamed-page/path fallback instead of exposing technical ids. That fallback is a diagnostic, not successful delivery: `tests/logic/page-permission-titles.test.ts` must pass against the application's actual resolved routes and locales; it rejects missing labels, stale mapping keys and untranslated keys. When fixing an existing app, preserve the complete resource/action identity list and grants, and verify display labels without rewriting authorization data.
211
+ Provide English and Chinese text without unresolved interpolation placeholders. The permission catalog uses `pagePermissionResources()` and a localized unnamed-page/path fallback instead of exposing technical ids. That fallback is a diagnostic, not successful delivery: `tests/client/page-permission-titles.test.ts` must pass against the application's actual resolved routes and locales; it rejects missing labels, stale mapping keys and untranslated keys. When fixing an existing app, preserve the complete resource/action identity list and grants, and verify display labels without rewriting authorization data.
212
212
 
213
213
  ## 5. Settings pages
214
214
 
@@ -279,7 +279,7 @@ Write `navigation` on the route. The application sidebar reads its menu entries
279
279
  - **A path with a parameter (`:projectId`) cannot have `navigation`**; registration raises an error, because a menu entry must point to a fixed URL (wildcards are rejected on every route, [section 1](#1-declare-the-route)).
280
280
  - Navigation group: write only `name`, `navigation` and `children`, without `componentLoader`. For groups and clickable parents, see [`child-routes.md`](child-routes.md).
281
281
  - Do not change the shell (`client/layouts/`) or the ServiceProvider to add a menu entry; the home page entry is declared in the routes as well.
282
- - A new page with a menu entry usually touches four places: `client/routes.ts`, the page component, `client/locales/` and, for an App page that requires sign-in, the page grant list in `tests/logic/client-routes.test.ts` ([section 12](#12-update-the-route-test)).
282
+ - A new page with a menu entry usually touches four places: `client/routes.ts`, the page component, `client/locales/` and, for an App page that requires sign-in, the page grant list in `tests/client/client-routes.test.ts` ([section 12](#12-update-the-route-test)).
283
283
 
284
284
  ### A count beside an entry
285
285
 
@@ -491,13 +491,13 @@ When customizing the shell, keep the behaviors listed in [section 1 of `shell.md
491
491
 
492
492
  ## 12. Update the route test
493
493
 
494
- `tests/logic/client-routes.test.ts` checks the application's routes:
494
+ `tests/client/client-routes.test.ts` checks the application's routes:
495
495
 
496
496
  - `keeps the landing page and the authentication pages`: the home page and the four authentication pages still exist. Adding a page does not require changing it.
497
497
  - `loads every page component`: calls every page's `componentLoader` in turn (including child routes at every level) and confirms that the module default-exports a component. Adding a page does not require changing it; it fails when a page file has no default export. An entry with `parent` pointing at another package's group is the exception: register that package's routes in `resolveRoutes()` first.
498
498
  - `pins the page authorization of every signed-in page`: lists, in depth-first order, every page in the app routes that requires sign-in, including child routes. **When you add a page with `auth: 'required'`, including its child routes, add it here, or the comparison fails**: `authorizedAs` is `null` for a page whose resolved `authz` is `'skip'`, `'unrestricted'` for an unrestricted-only page, the resource id for a page that checks page access (`'projects'`), and `type:id` for any other resource (`'composite:project-reports'`); a nested page that omits `authz` shows its parent's value. The example's projects routes add `projects`, `project-new`, `project-edit`, `project-detail` and `project-detail-edit`, all `null`, in that order; a page that declares the drawer under itself adds its own pair, such as `project-dashboard-detail` and `project-dashboard-detail-edit`. A page with tabs whose header opens overlays adds a route per tab and per overlay under each tab: `customerDetailRoutes('customer')` adds `customer-detail`, `customer-detail-overview`, `customer-detail-overview-edit`, `customer-detail-orders` and `customer-detail-orders-edit`, every other page that declares it adds the same set under its own owner, and a helper in the test spells one set out (["The route test" in `example/detail-page-tabs.md`](example/detail-page-tabs.md#the-route-test)). Stored page grants reference the resource id, and changing one requires migrating existing grants, so this list is deliberately pinned.
499
499
 
500
- After the change, run `pnpm exec vitest run tests/logic/client-routes.test.ts`.
500
+ After the change, run `pnpm exec vitest run tests/client/client-routes.test.ts`.
501
501
 
502
502
  ## 13. Verify
503
503
 
@@ -520,4 +520,4 @@ Root holds every grant, so a hidden page, a denied tab or a read-only settings c
520
520
  4. Ask the user to sign in as the test account into a second session file, `capture.mjs login --state storage/ui-workflow/auth-limited.json` ([`../scripts/capture.md`](../scripts/capture.md)), and take the permission shots with `"state": "storage/ui-workflow/auth-limited.json"` in their configuration. The same session calls the endpoints "as an ordinary user".
521
521
  5. Afterwards delete the permission set and ask the user to remove the account, or list both in the report; delete `auth-limited.json` with the other records.
522
522
 
523
- The pending and failed outcomes of `useCan` cannot be produced this way: cover them in a test, setting `permission.isPending` or `permission.error`, which the `useCan` mock of `tests/components/page-harness.test.tsx` returns.
523
+ The pending and failed outcomes of `useCan` cannot be produced this way: cover them in a test, setting `permission.isPending` or `permission.error`, which the `useCan` mock of `tests/client/page-harness.test.tsx` returns.
@@ -28,7 +28,7 @@ pnpm exec prettier --write client/components/ui/field.tsx client/components/ui/s
28
28
  - When a primitive needs an npm package the application does not have yet (`recharts` for `chart`, `cmdk` for `command`), the CLI installs it into `dependencies`, such as `react-day-picker` for `calendar`, and a UI Library item does the same with the packages it declares. Move them to `devDependencies`: client code is bundled, and `dependencies` is what every deployment installs ([adding a dependency](../../dependencies.md)). A package already declared in `devDependencies` stays there. An item that translates its labels also adds `@nocobase/i18n` again, which pins its range in `dependencies` to an exact version; leave it in `dependencies`, where the server needs it, and put the `^` back.
29
29
  - Import `cn` from the `cn` package, which `devDependencies` declares, as the registry's primitives and the template's own code do. `client/lib/utils.ts` only re-exports it, the way `shadcn init` writes the file, so an older `#lib/utils` import still works; write new code against `cn`.
30
30
  - Apart from formatting and those translations, keep each primitive as the CLI writes it. For a different look, use its props or change the theme ([`theme.md`](theme.md)). The template's own copies differ from the registry too, which is one more reason to answer no: `dialog.tsx`, `sheet.tsx`, `spinner.tsx` and `toast.tsx` translate their labels, and `button.tsx` sizes its small text with `text-sm` instead of the registry's fixed `text-[0.8rem]`.
31
- - To update a primitive, compare first with `pnpm exec shadcn add <name> --diff <file>`, and overwrite only with the user's approval, as "Updating Components" in the skill says. Then apply the translations again: `tests/components/primitive-labels.test.tsx` fails when a shipped primitive has lost one.
31
+ - To update a primitive, compare first with `pnpm exec shadcn add <name> --diff <file>`, and overwrite only with the user's approval, as "Updating Components" in the skill says. Then apply the translations again: `tests/client/primitive-labels.test.tsx` fails when a shipped primitive has lost one.
32
32
 
33
33
  ### English built into primitives
34
34
 
@@ -85,9 +85,9 @@ export function HeaderActions(): ReactElement {
85
85
 
86
86
  - Translate the copy and use tokens for colors. Header icon buttons match the existing entries in size, spacing, focus style, and button styling.
87
87
  - Leave overlay positioning to the component, including at the right edge of the screen.
88
- - Whichever entry you change, reuse its existing interaction tests (for example `tests/components/header-hover.test.tsx`). Do not simulate layout or submenu pointer geometry in jsdom; it does not match how a real browser behaves.
88
+ - Whichever entry you change, reuse its existing interaction tests (for example `tests/client/header-hover.test.tsx`). Do not simulate layout or submenu pointer geometry in jsdom; it does not match how a real browser behaves.
89
89
 
90
90
  ## 3. Verify
91
91
 
92
- - Run the shell tests that cover what you changed: `tests/components/header-hover.test.tsx` (hover, keyboard and Escape), `navigation-menu.test.tsx`, `sidebar-permissions.test.tsx`, `sidebar-preference.test.tsx` and `language-switcher.test.tsx` under `tests/components/`, and `tests/logic/client-shell.test.tsx` and `tests/logic/user-menu-sign-out.test.tsx`.
92
+ - Run the shell tests that cover what you changed: `tests/client/header-hover.test.tsx` (hover, keyboard and Escape), `navigation-menu.test.tsx`, `sidebar-permissions.test.tsx`, `sidebar-preference.test.tsx` and `language-switcher.test.tsx` under `tests/client/`, and `tests/client/client-shell.test.tsx` and `tests/client/user-menu-sign-out.test.tsx`.
93
93
  - Look at the App layout in the browser, on the desktop and at 375px, with the sidebar expanded and collapsed.
@@ -3,12 +3,11 @@
3
3
  ## Where tests go
4
4
 
5
5
  ```text
6
- tests/components/ Component tests: rendering and interaction of pages and components (Vitest, jsdom)
7
- tests/logic/ Logic tests: route declarations, pure functions, providers (Vitest)
8
- tests/playwright/ End-to-end tests against a running application (Playwright); create the directory with the first test
6
+ tests/client/ Pages, components, route declarations, client services and pure client functions (Vitest, jsdom)
7
+ tests/playwright/ Browser behavior against a running application (Playwright)
9
8
  ```
10
9
 
11
- Tests never go beside the source. Vitest discovers `tests/**/*.test.{ts,tsx}` and skips `tests/playwright/` (`vitest.config.ts`); Playwright discovers `tests/playwright/**/*.test.ts` (`playwright.config.ts`). Use `tests/playwright/` for browser behavior and complete browser-to-API flows. A real server, database or sign-in alone belongs in a Node test with `createAppTest()` from `@nocobase/app-testing/server`; it does not require Playwright. Applications created from the Default and Examples templates have Playwright set up; an application without it, before its first end-to-end test, adds `@playwright/test` to `devDependencies`, a `playwright.config.ts` with `testDir: './tests/playwright'` and `testMatch: '**/*.test.ts'`, a `test:e2e` script running `playwright test --pass-with-no-tests`, `exclude: ['tests/playwright/**']` to the `test` section of `vitest.config.ts` unless it is already there, and `playwright.config.ts` and `tests/playwright/**/*.ts` to the `include` of `tsconfig.node.json`.
10
+ Tests never go beside the source. The client Vitest project discovers `tests/client/**/*.test.{ts,tsx}` in jsdom; the Node project discovers server, database, CLI and project tests, with no client setup files. Both projects leave `tests/playwright/` to its own runner (`vitest.config.ts`); Playwright discovers `tests/playwright/**/*.test.ts` (`playwright.config.ts`). Use `tests/playwright/` for browser behavior and complete browser-to-API flows. A real server, database or sign-in alone belongs in a Node test with `createAppTest()` from `@nocobase/app-testing/server`; it does not require Playwright. Applications created from the Default and Examples templates have Playwright set up; an application without it, before its first end-to-end test, adds `@playwright/test` to `devDependencies`, a `playwright.config.ts` with `testDir: './tests/playwright'` and `testMatch: '**/*.test.ts'`, a `test:e2e` script running `playwright test --pass-with-no-tests`, Vitest include patterns that leave `tests/playwright/**` out (or an explicit exclusion in every applicable project), and `playwright.config.ts` and `tests/playwright/**/*.ts` to the `include` of `tsconfig.node.json`.
12
11
 
13
12
  ## What to test
14
13
 
@@ -17,17 +16,17 @@ Tests never go beside the source. Vitest discovers `tests/**/*.test.{ts,tsx}` an
17
16
  | Page or component | What it renders in each state (loading, empty, no results, failed) and what happens after an interaction: the request sent, the state change, the toast, the error shown where the action started |
18
17
  | Overlay (child route) | Opening its URL renders the overlay over the parent; closing returns to the parent URL with the query kept; `beforeClose` blocks closing while submitting; opened from a view other than the first one the page shows — every tab of a page whose header opens it — the URL keeps that view and closing returns to it ([`example/detail-page-tabs.md`](example/detail-page-tabs.md#the-test)) |
19
18
  | Covering child page | Opening its URL covers the parent: the parent's content stays in the document, and `RouteChildPage` makes what it covers `inert`, so `expect(screen.getByRole('heading', { name: parentTitle }).closest('[inert]')).not.toBeNull()` passes, and fails for a child route that renders inline below the parent's content; the back button returns to the parent URL with the query kept |
20
- | Route declarations | `tests/logic/client-routes.test.ts` already checks that every page loads and pins each page's resolved `authz`; when you add a page that requires sign-in, add it to the test's page grant list, as [section 12 of `page.md`](page.md#12-update-the-route-test) describes |
21
- | Copy | `tests/logic/app-locale-coverage.test.ts` passes: every key the application's code passes to `t()` or names as a route `title`, and every dynamic key family, exists in both locale files. Component tests render with the real i18n runtime (below) rather than a mocked `t`, so both languages show real text, not keys |
19
+ | Route declarations | `tests/client/client-routes.test.ts` already checks that every page loads and pins each page's resolved `authz`; when you add a page that requires sign-in, add it to the test's page grant list, as [section 12 of `page.md`](page.md#12-update-the-route-test) describes |
20
+ | Copy | `tests/client/app-locale-coverage.test.ts` passes: every key the application's code passes to `t()` or names as a route `title`, and every dynamic key family, exists in both locale files. Component tests render with the real i18n runtime (below) rather than a mocked `t`, so both languages show real text, not keys |
22
21
  | A bug fix | A test that fails before the fix and passes after it, when jsdom can reproduce the bug |
23
22
 
24
23
  ## Building the test harness
25
24
 
26
- Also run `tests/logic/page-permission-titles.test.ts` when adding or changing routes. It requires translated names for every application page permission, including overlays without navigation/breadcrumbs, and preserves the complete resource/action identity list. See [permission display names](page.md#permission-display-names).
25
+ Also run `tests/client/page-permission-titles.test.ts` when adding or changing routes. It requires translated names for every application page permission, including overlays without navigation/breadcrumbs, and preserves the complete resource/action identity list. See [permission display names](page.md#permission-display-names).
27
26
 
28
27
  For a page or component that uses application services, start from the [complete `@nocobase/app-testing/client` example](../../testing/client/page.md). `renderWithApp()` supplies the real API client, router, translations and toaster. Supply HTTP responses through `answerApi()`, load the application's locale map, and assert visible state and `view.toasts()`. Register the client plugins or service doubles that the page actually consumes; avoid mocking the whole `@nocobase/app-client` module.
29
28
 
30
- `tests/components/page-harness.test.tsx` in the official templates uses `renderWithApp()` with real API, authorization, translation and toaster hooks. It covers a pending request, the request payload, a `403` without retry, a `401` with session refresh, allowed and denied actions, and a child route opened by URL and closed with a success toast. It replaces the authentication service through `services` while keeping its provider and hooks real. When adapting those cases, import the real page and supply its required plugins or services. Put new files in the application's current test layout; the worked example uses `tests/client/` with an explicit React config.
29
+ `tests/client/page-harness.test.tsx` in the official templates uses `renderWithApp()` with real API, authorization, translation and toaster hooks. It covers a pending request, the request payload, a `403` without retry, a `401` with session refresh, allowed and denied actions, and a child route opened by URL and closed with a success toast. It replaces the authentication service through `services` while keeping its provider and hooks real. When adapting those cases, import the real page and supply its required plugins or services. Put new files in the application's current test layout; the worked example uses `tests/client/` with an explicit React config.
31
30
 
32
31
  The template's local Vitest inline rules transform client plugins in any scope, including `@acme/app-plugin-*`, alongside `app-client` and the client test helper. Preserve that scope coverage when changing the configuration so installed plugins share application contexts and service tokens. Keep server and database modules external. The shared React preset handles native router resolution; preserve its package export conditions and router externalization when adjusting local rules.
33
32
 
@@ -35,8 +34,8 @@ The template's local Vitest inline rules transform client plugins in any scope,
35
34
 
36
35
  For anything else, start from the test that already sets it up:
37
36
 
38
- - **A second language**: pass the `client/locales/index.ts` loader map and switch with `changeLanguage` inside `act`, as the next section shows; `tests/components/primitive-labels.test.tsx` renders in Chinese from the start with `locale: 'zh-CN'`.
39
- - **Overlay behavior in depth** (`beforeClose`, nested layers, focus): `tests/logic/route-overlay.test.tsx`.
37
+ - **A second language**: pass the `client/locales/index.ts` loader map and switch with `changeLanguage` inside `act`, as the next section shows; `tests/client/primitive-labels.test.tsx` renders in Chinese from the start with `locale: 'zh-CN'`.
38
+ - **Overlay behavior in depth** (`beforeClose`, nested layers, focus): `tests/client/route-overlay.test.tsx`.
40
39
  - **A UI Library item**: it passes its English as `defaultValue`, but the strict runtime still fails on a key `client/locales/` lacks, so add the keys the item's README lists before testing a page that renders it.
41
40
 
42
41
  - Assert what the user can see: text, roles and accessible names, the result of a click (`@testing-library/react`, `@testing-library/user-event` and the jest-dom assertions are set up). Do not assert internal state.
@@ -6,19 +6,19 @@ The theming in the shadcn skill does not apply here: no `shadcn apply`, `shadcn
6
6
 
7
7
  ## 1. Files and mechanism
8
8
 
9
- | Location | Role |
10
- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
11
- | `client/theme/themes/<id>.css` | One file per preset: a light rule and a dark rule |
12
- | `client/theme/themes/compact.css` | Compact: the default preset and the fallback |
13
- | `client/theme/themes/default.css` | Spacious (id `default`). Its rules also match bare `:root` and `:root.dark`, so every token has a value before a preset is applied to `<html>` |
14
- | `client/styles.css` | Imported by `client/index.tsx`. Imports every preset (`default.css` first) and connects the variables to Tailwind: colors become `bg-*`, `text-*` and similar classes, `--radius` derives the `rounded-*` scale, and `@utility` adapters keep the shadow classes on the runtime variables |
15
- | `client/theme/theme-presets.ts` | The preset registry: `id` and `labelKey` per preset. The first entry is the fallback |
16
- | `appearance.themes.<id>` in `client/locales/*.ts` | Preset labels |
17
- | `client/theme/theme-settings.tsx` | The Appearance popover: color mode and theme |
18
- | `client/theme/theme-provider.tsx`, `client/theme/theme-context.ts` | `AppThemeProvider`, which `client/react-providers.ts` mounts in the `root` layer, and `useThemePreset()` |
19
- | `client/theme/theme-preferences.ts` | Storage keys, configured defaults, and `initializeTheme()`, which `client/index.tsx` calls at startup |
20
- | `client.app.defaultColorScheme` and `client.app.defaultTheme` in `config.yml` | Application defaults, see [section 6](#6-application-defaults) |
21
- | `tests/logic/theme-*.test.ts`, `tests/logic/client-theme.test.tsx`, `tests/fixtures/theme-tokens.*` | Contract tests and a browser fixture, see [section 7](#7-verify) |
9
+ | Location | Role |
10
+ | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
11
+ | `client/theme/themes/<id>.css` | One file per preset: a light rule and a dark rule |
12
+ | `client/theme/themes/compact.css` | Compact: the default preset and the fallback |
13
+ | `client/theme/themes/default.css` | Spacious (id `default`). Its rules also match bare `:root` and `:root.dark`, so every token has a value before a preset is applied to `<html>` |
14
+ | `client/styles.css` | Imported by `client/index.tsx`. Imports every preset (`default.css` first) and connects the variables to Tailwind: colors become `bg-*`, `text-*` and similar classes, `--radius` derives the `rounded-*` scale, and `@utility` adapters keep the shadow classes on the runtime variables |
15
+ | `client/theme/theme-presets.ts` | The preset registry: `id` and `labelKey` per preset. The first entry is the fallback |
16
+ | `appearance.themes.<id>` in `client/locales/*.ts` | Preset labels |
17
+ | `client/theme/theme-settings.tsx` | The Appearance popover: color mode and theme |
18
+ | `client/theme/theme-provider.tsx`, `client/theme/theme-context.ts` | `AppThemeProvider`, which `client/react-providers.ts` mounts in the `root` layer, and `useThemePreset()` |
19
+ | `client/theme/theme-preferences.ts` | Storage keys, configured defaults, and `initializeTheme()`, which `client/index.tsx` calls at startup |
20
+ | `client.app.defaultColorScheme` and `client.app.defaultTheme` in `config.yml` | Application defaults, see [section 6](#6-application-defaults) |
21
+ | `tests/client/theme-*.test.ts`, `tests/client/client-theme.test.tsx`, `tests/fixtures/theme-tokens.*` | Contract tests and a browser fixture, see [section 7](#7-verify) |
22
22
 
23
23
  How a preset takes effect:
24
24
 
@@ -202,7 +202,7 @@ Each adapter has this form:
202
202
  - Each preset's light rule defines every color and every non-color token. Its dark rule defines every color and may override non-color values; anything it leaves out comes from the preset's light rule.
203
203
  - The same declarations go on the preview selectors `.theme-preview[data-theme='<id>']` and `:root.dark .theme-preview[data-theme='<id>']`, aliases included. A custom property inherits its resolved value, so an alias such as `--font-heading: var(--font-sans)` or `--sidebar: var(--card)` declared only for the page would carry the page's preset into another preset's thumbnail. Listing the preview selector in the same rule, as the template files do, keeps the two identical.
204
204
  - Do not reset whole Tailwind namespaces, and do not add per-page overrides to create a theme.
205
- - Extend the shared token contract only after design approval. An approved token needs a Tailwind mapping in `client/styles.css`, a value in every preset rule, and an entry in the token lists of `tests/logic/theme-tokens.test.ts`. Do not change `components.json`, routes, component props or plugin APIs as a side effect of theme work.
205
+ - Extend the shared token contract only after design approval. An approved token needs a Tailwind mapping in `client/styles.css`, a value in every preset rule, and an entry in the token lists of `tests/client/theme-tokens.test.ts`. Do not change `components.json`, routes, component props or plugin APIs as a side effect of theme work.
206
206
 
207
207
  ### Fixed-size exceptions
208
208
 
@@ -218,7 +218,7 @@ Some values stay fixed on purpose. Know which ones, and keep your own explicit.
218
218
 
219
219
  ### Constraints from the token test
220
220
 
221
- `tests/logic/theme-tokens.test.ts` requires `compact.css` and `default.css` to be identical, in both the light and the dark rule, except for `--spacing`, `--radius` and the `--text-*` variables, and it requires Compact's `--spacing` to be smaller than Spacious'. Today the two differ in spacing and line heights; the radius and the text sizes are the same. So:
221
+ `tests/client/theme-tokens.test.ts` requires `compact.css` and `default.css` to be identical, in both the light and the dark rule, except for `--spacing`, `--radius` and the `--text-*` variables, and it requires Compact's `--spacing` to be smaller than Spacious'. Today the two differ in spacing and line heights; the radius and the text sizes are the same. So:
222
222
 
223
223
  - A change to colors, fonts or shadows goes into both files, light and dark rules alike.
224
224
  - Density (spacing, radius, text sizes and line heights) may differ between the two.
@@ -330,7 +330,7 @@ The steps below add a preset with the id `forest`.
330
330
  /* … */
331
331
  ```
332
332
 
333
- 4. **Register the preset.** Append an entry to `themePresets` in `client/theme/theme-presets.ts`. Keep `compact` first: the first entry is the fallback, and `tests/logic/theme-preferences.test.ts` expects it there. The `labelKey` is `appearance.themes.<id>`.
333
+ 4. **Register the preset.** Append an entry to `themePresets` in `client/theme/theme-presets.ts`. Keep `compact` first: the first entry is the fallback, and `tests/client/theme-preferences.test.ts` expects it there. The `labelKey` is `appearance.themes.<id>`.
334
334
 
335
335
  ```ts
336
336
  // client/theme/theme-presets.ts
@@ -346,7 +346,7 @@ The steps below add a preset with the id `forest`.
346
346
 
347
347
  `ThemePresetId` is derived from the array, so the new id is accepted wherever a preset id is typed. `defaultThemePreset` does not decide the fallback, and no template code reads it; keep it equal to the first entry.
348
348
 
349
- 5. **Add the label** to `appearance.themes` in every application locale file, spreading the system group as [`i18n.md`](i18n.md) describes; removing or renaming a template preset rewords its key after the spread rather than editing `client/locales/system/`. `zh-CN.ts` is typed from `en-US.ts`, so the two must have the same keys or the type check fails; a label missing from both fails `tests/logic/app-locale-coverage.test.ts`, which reads the registry's `labelKey` (without the label the popover would show the capitalized id). Give each preset a distinct label: it is the accessible name of the preset's radio option. Translation rules are in [`i18n.md`](i18n.md).
349
+ 5. **Add the label** to `appearance.themes` in every application locale file, spreading the system group as [`i18n.md`](i18n.md) describes; removing or renaming a template preset rewords its key after the spread rather than editing `client/locales/system/`. `zh-CN.ts` is typed from `en-US.ts`, so the two must have the same keys or the type check fails; a label missing from both fails `tests/client/app-locale-coverage.test.ts`, which reads the registry's `labelKey` (without the label the popover would show the capitalized id). Give each preset a distinct label: it is the accessible name of the preset's radio option. Translation rules are in [`i18n.md`](i18n.md).
350
350
 
351
351
  ```ts
352
352
  // client/locales/en-US.ts
@@ -429,14 +429,14 @@ Each choice resolves on its own, from the first valid source:
429
429
  Run the theme tests:
430
430
 
431
431
  ```bash
432
- pnpm exec vitest run tests/logic/theme-tokens.test.ts tests/logic/theme-preferences.test.ts tests/logic/client-theme.test.tsx
432
+ pnpm exec vitest run tests/client/theme-tokens.test.ts tests/client/theme-preferences.test.ts tests/client/client-theme.test.tsx
433
433
  ```
434
434
 
435
435
  - `theme-tokens.test.ts` checks that every registered preset defines all 32 colors and every non-color token in its light rule and every color in its dark rule, with the same declarations on the preview selectors; that Compact and Spacious differ only in dimensions, with Compact's spacing smaller; and, by compiling `client/styles.css` with Tailwind, that the color, font, size, line height, spacing, radius and shadow classes and the `body`, `h1` and `code` fonts still read the runtime variables.
436
436
  - `theme-preferences.test.ts` checks that Compact is first, the storage keys for each base path, restoring both choices at startup without reading another application's keys, and the fallbacks for invalid values, removed presets and unavailable storage.
437
437
  - `client-theme.test.tsx` checks the provider and the popover: labels in en-US and zh-CN, choosing and saving, configured defaults against saved choices, startup and provider agreeing, clearing and syncing across tabs, invalid values, and unavailable storage.
438
438
 
439
- Format the changed CSS and TypeScript files with Prettier, and lint only the TypeScript ones (ESLint has no CSS configuration; see ["Self-check before finishing" in `../frontend-dev.md`](../frontend-dev.md#self-check-before-finishing)). After changing the popover or its header entry, also run `pnpm exec vitest run tests/components/header-hover.test.tsx` (hover, keyboard and Escape). After changing the registry or a locale file, type-check the client with `pnpm exec tsc -p tsconfig.json --noEmit` and run `pnpm exec vitest run tests/logic/app-locale-coverage.test.ts`.
439
+ Format the changed CSS and TypeScript files with Prettier, and lint only the TypeScript ones (ESLint has no CSS configuration; see ["Self-check before finishing" in `../frontend-dev.md`](../frontend-dev.md#self-check-before-finishing)). After changing the popover or its header entry, also run `pnpm exec vitest run tests/client/header-hover.test.tsx` (hover, keyboard and Escape). After changing the registry or a locale file, type-check the client with `pnpm exec tsc -p tsconfig.json --noEmit` and run `pnpm exec vitest run tests/client/app-locale-coverage.test.ts`.
440
440
 
441
441
  A compiled CSS check cannot prove the layout. Check in a browser, scaled to the change:
442
442
 
@@ -92,7 +92,7 @@ The confirmed design is the basis for development and the acceptance review.
92
92
  2. Implement according to `design.md`: every item in the component list, every state, every interaction and every piece of copy must have a matching implementation.
93
93
  3. When new backend endpoints are needed, implement them to the endpoint contract in the design (for backend code, see [`../server-routes.md`](../server-routes.md), [`../migrations.md`](../migrations.md) and [`../database-and-data.md`](../database-and-data.md)).
94
94
  4. When the design contains decisions that the code does not show by itself but that anyone changing this page later needs to know (for example, why an approach was not used, or what limits an endpoint has), write them as code comments. `design.md` is deleted when the task ends.
95
- 5. Cover the page's key behavior (state changes, submission, error handling) with component tests in `tests/components/`, written as [`references/testing.md`](references/testing.md) describes, and add a new App page to the route test ([section 12 of `references/page.md`](references/page.md#12-update-the-route-test)).
95
+ 5. Cover the page's key behavior (state changes, submission, error handling) with component tests in `tests/client/`, written as [`references/testing.md`](references/testing.md) describes, and add a new App page to the route test ([section 12 of `references/page.md`](references/page.md#12-update-the-route-test)).
96
96
  6. Move on to step 4 only after every check in ["Self-check before finishing" in `frontend-dev.md`](frontend-dev.md#self-check-before-finishing) passes.
97
97
 
98
98
  If you find during development that the design is not feasible, follow "Design changes".
@@ -20,7 +20,7 @@ The directory names organize the examples and their suggested test files. They a
20
20
 
21
21
  The examples assume `@nocobase/app-testing`, Vitest and the selected database driver are installed at versions compatible with the application. The client example additionally uses the React Vitest preset, Testing Library and jsdom already configured by the official templates. Each example lists its additional prerequisites. Run the named file and confirm it appears in the test summary; a successful command with no tests found is not verification.
22
22
 
23
- The examples use `tests/database/`, `tests/server/`, `tests/client/`, `tests/cli/` and `tests/playwright/`. An existing application may still use the `logic/` and `components/` layout below; follow its current conventions instead of moving unrelated tests. Directory names alone do not select a Vitest environment. Each complete Vitest example supplies a dedicated configuration that selects Node or jsdom and limits test discovery; use the matching `--config` when running it. When adopting the files into the regular suite, use the application's existing environment selection or Vitest projects and keep `tests/playwright/**` excluded from Vitest. Preserve existing aliases, setup files and test discovery.
23
+ The examples use `tests/database/`, `tests/server/`, `tests/client/`, `tests/cli/` and `tests/playwright/`. An existing application may still use a legacy `logic/` and `components/` layout; follow its current conventions instead of moving unrelated tests. Directory names alone do not select a Vitest environment. Each complete Vitest example supplies a dedicated configuration that selects Node or jsdom and limits test discovery; use the matching `--config` when running it. When adopting the files into the regular suite, use the application's existing environment selection or Vitest projects and keep `tests/playwright/**` excluded from Vitest. Preserve existing aliases, setup files and test discovery.
24
24
 
25
25
  ### Fixture selection and ownership
26
26
 
@@ -56,14 +56,20 @@ If startup fails, check the installed package exports, the selected driver, the
56
56
  ## Where tests go
57
57
 
58
58
  ```text
59
- tests/logic/ Logic and integration tests
60
- tests/components/ Component tests
61
- tests/playwright/ Browser tests against a running application at APP_URL (Playwright; Vitest skips it)
59
+ tests/client/ Pages, components, client services and runtime logic (jsdom)
60
+ tests/server/ Services, routes and permission boundaries (Node)
61
+ tests/database/ Migrations and seeds (Node)
62
+ tests/cli/ Application commands (Node)
63
+ tests/project/ Root configuration, package metadata and build artifacts (Node)
64
+ tests/fixtures/ Test data and fixture applications, without test files
65
+ tests/helpers/ Shared test helpers, without test files
66
+ tests/setup/ Application setup files
67
+ tests/playwright/ Browser tests against a running application (Playwright)
62
68
  ```
63
69
 
64
70
  **Never put a test beside the source it covers.** Name files `*.test.ts` or `*.test.tsx`.
65
71
 
66
- `vitest.config.ts` discovers `tests/**/*.test.{ts,tsx}` automatically. Theme token tests compile the real CSS; browser checks still need to verify computed styles, typography, spacing and focus.
72
+ `vitest.config.ts` uses Vitest projects: the React preset discovers `tests/client/**/*.test.{ts,tsx}`, while the Node preset discovers `tests/{server,database,cli,project}/**/*.test.{ts,tsx}`. Keep client setup files in the client project and run Node files sequentially. Do not add per-file `@vitest-environment` overrides; put the test in the directory of the source it covers. Create an optional directory when it has its first file. Playwright has its own runner and is outside both Vitest include patterns. Theme token tests compile the real CSS; browser checks still need to verify computed styles, typography, spacing and focus.
67
73
 
68
74
  Templates ship their tests into generated applications. Keep them runnable from the application root after scaffolding: read application identity from `package.json`, resolve application paths relative to the test file, and import dependencies through their published package exports. Do not depend on a monorepo checkout, a fixed template directory name, or a particular pnpm store layout. Run the affected test files in the generated application as well as in the template when changing these contracts.
69
75
 
@@ -241,6 +247,6 @@ Vite configuration imports the proxy helpers from `@nocobase/app-cli/dev/proxy`.
241
247
 
242
248
  ## Permission assignment acceptance
243
249
 
244
- Run the template's `tests/logic/authorization-assignment-safety.test.ts` after installing the real application migrations/seeds in isolated test storage. Retain it as business features are added: it catches unexpected wildcard role assignments and business grants hidden in the inherited member role. Do not treat a source-code scan as proof of the resulting assignments. See [assignment safety](authorization.md#visible-and-manageable-assignments) for intentional global defaults and the limits of the initialized-state check.
250
+ Run the template's `tests/server/authorization-assignment-safety.test.ts` after installing the real application migrations/seeds in isolated test storage. Retain it as business features are added: it catches unexpected wildcard role assignments and business grants hidden in the inherited member role. Do not treat a source-code scan as proof of the resulting assignments. See [assignment safety](authorization.md#visible-and-manageable-assignments) for intentional global defaults and the limits of the initialized-state check.
245
251
 
246
252
  For an ordinary identity assigned only the intended business role, enumerate direct and inherited grant sources, confirm visible menus/buttons match effective access, and exercise forbidden direct API requests. Test page-only versus action-only access separately. If a global default is explicitly requested, test its authorized administration control, inherited-role display and revocation while preserving independent direct grants. Never silently assign all authenticated users a role to make an acceptance test pass.
@@ -38,7 +38,7 @@ pnpm test
38
38
  pnpm build
39
39
  ```
40
40
 
41
- If merging the template's regression tests, include `tests/logic/session-isolation.test.ts`; it uses the application's own configuration and shared synthetic test keys/storage to test the cookie boundary. Never point it at deployment sessions or databases.
41
+ If merging the template's regression tests, include `tests/server/session-isolation.test.ts`; it uses the application's own configuration and shared synthetic test keys/storage to test the cookie boundary. Never point it at deployment sessions or databases.
42
42
 
43
43
  ## Expected upgrade behavior
44
44
 
@@ -143,7 +143,7 @@ A release whose Default or Examples template has `testDir: './tests/playwright'`
143
143
 
144
144
  ### The template's copy moved to `client/locales/system/`
145
145
 
146
- A release whose template has `client/locales/system/en-US.ts` keeps the template's own copy there — the shell, the sign-in pages, shared components and the homepage — and `client/locales/en-US.ts` and `zh-CN.ts` spread it before the application's own groups. Earlier releases kept everything in one file per language. Take the template's `client/locales/system/` as it is, then reduce each application locale file to `...systemEnUS` (or `...systemZhCN`) followed by the groups the application added itself: compare each group with the template's previous locale file, drop the ones the application never changed, and keep a reworded template key after the spread. A shared group the application extended, such as `navigation`, becomes `navigation: { ...systemEnUS.navigation, <the application's entries> }`. Run `pnpm exec tsc -p tsconfig.json --noEmit` and `tests/logic/app-locale-coverage.test.ts` afterward. From then on, an upgrade replaces `client/locales/system/` and leaves the application's locale files alone.
146
+ A release whose template has `client/locales/system/en-US.ts` keeps the template's own copy there — the shell, the sign-in pages, shared components and the homepage — and `client/locales/en-US.ts` and `zh-CN.ts` spread it before the application's own groups. Earlier releases kept everything in one file per language. Take the template's `client/locales/system/` as it is, then reduce each application locale file to `...systemEnUS` (or `...systemZhCN`) followed by the groups the application added itself: compare each group with the template's previous locale file, drop the ones the application never changed, and keep a reworded template key after the spread. A shared group the application extended, such as `navigation`, becomes `navigation: { ...systemEnUS.navigation, <the application's entries> }`. Run `pnpm exec tsc -p tsconfig.json --noEmit` and `tests/client/app-locale-coverage.test.ts` afterward. From then on, an upgrade replaces `client/locales/system/` and leaves the application's locale files alone.
147
147
 
148
148
  ## Where the user's code lives
149
149
 
@@ -197,7 +197,7 @@ Make these changes together, before the [Finish step](../SKILL.md#8-finish) inst
197
197
  3. An application that still registers `@nocobase/app-plugin-notification-provider` removes it with `pnpm nocobase package remove @nocobase/app-plugin-notification-provider`, which drops the dependency and its `client/plugins.ts` entry together.
198
198
  4. In `package.json`, take the target's ranges for `@nocobase/app-client` and the four plugins together: a plugin that reports through `useToaster()` needs the `@nocobase/app-client` that exports it. `pnpm nocobase plugin update` alone does not do this. These plugin versions stay inside the `^1.0.0-beta` ranges the application already declares, so it installs them, but it updates only registered plugins and leaves `@nocobase/app-client` where it is: their pages then fail to load because `@nocobase/app-client` does not export `useToaster`. Update `@nocobase/app-client` in the same step, and only after steps 1 and 2.
199
199
  5. Rewrite application code that shows toasts to call `const toaster = useToaster()` and `toaster.show(...)`. `toast.add({ ... })` from `@/components/ui/toast` keeps its `type`, `title` and `description`; `timeout` becomes `duration`, `actionProps` becomes `action: { label, onClick }`, and `priority` goes, because `client/lib/toaster.ts` decides it. `toast.success(message)`, `toast.error(message)` and `toast.info(message)` imported from `sonner` become `toaster.show({ type: 'success', title: message })` and its `error` and `info` counterparts, and calls to Refine's `useNotification()` move to `useToaster()` too. When `grep -rn "from 'sonner'\|useNotification" client/` finds nothing, remove `sonner` from `package.json`.
200
- 6. A test that stands in for the application with a hand-written `services` object, as the template's `tests/logic/client-shell.test.tsx` does, gives it `has` alongside `resolve`. `useToaster()` asks whether a toaster is registered before resolving one, so a stub without `has` fails every page that shows the account menu with `services.has is not a function`.
200
+ 6. A test that stands in for the application with a hand-written `services` object, as the template's `tests/client/client-shell.test.tsx` does, gives it `has` alongside `resolve`. `useToaster()` asks whether a toaster is registered before resolving one, so a stub without `has` fails every page that shows the account menu with `services.has is not a function`.
201
201
 
202
202
  After the Finish step, run `pnpm typecheck` and `pnpm build`, then show one toast from the application and one from a plugin: sign out while the server is stopped for the account menu's error toast, and trigger an action on a plugin page that reports one, such as saving a project setting on a Projects page. A toast that does not appear means step 1 did not land when the console logs `Toast not shown: the application registers no toaster`, and step 2 when it does not; one that appears twice means a second `Toaster` is mounted. An upgrade done by hand, outside this Skill, needs the same six steps.
203
203
 
@@ -229,7 +229,7 @@ The release in which `@nocobase/app-client` 4 drops Refine removes `app.refine`,
229
229
 
230
230
  Make these changes together, before the [Finish step](../SKILL.md#8-finish) installs dependencies:
231
231
 
232
- 1. In `client/service-provider.ts`, delete `this.app.refine.setOptions({ title: { text: title } })`; the `document.title` lines beside it are what set the title and stay. An application from the Examples template also deletes the `this.app.refine.addResources([...])` call. `grep -rn "app\.refine\|refineConfig\|AppClientRefine\|runWithProviderContext\|RefineI18nProvider\|repository-example/client/providers" client/ tests/` lists any other call: a resource, option or provider set this way was never read by anything but Refine, so the call goes without a replacement. A test asserting `app.refineConfig.options?.title` asserts `document.title` instead, as the target's `tests/components/app-title.test.tsx` does.
232
+ 1. In `client/service-provider.ts`, delete `this.app.refine.setOptions({ title: { text: title } })`; the `document.title` lines beside it are what set the title and stay. An application from the Examples template also deletes the `this.app.refine.addResources([...])` call. `grep -rn "app\.refine\|refineConfig\|AppClientRefine\|runWithProviderContext\|RefineI18nProvider\|repository-example/client/providers" client/ tests/` lists any other call: a resource, option or provider set this way was never read by anything but Refine, so the call goes without a replacement. A test asserting `app.refineConfig.options?.title` asserts `document.title` instead, as the target's `tests/client/app-title.test.tsx` does.
233
233
  2. In `package.json`, remove `@refinedev/cli`, `@refinedev/core`, `@refinedev/react-hook-form`, `@refinedev/react-router` and `@refinedev/react-table` from `devDependencies`, and take the target's range for `@tanstack/react-query`. Remove `<Refine>` from any test fixture that wraps a component in it, such as `tests/fixtures/theme-tokens.tsx`.
234
234
  3. Search for imports from `@refinedev/` in `client/` before removing the packages. An application that adopted Refine's data hooks with a data provider of its own keeps those packages and mounts `<Refine>` itself in an `application`-layer entry of `client/react-providers.ts`, passing what the old shell passed: its data provider, `routerProvider` from `@refinedev/react-router`, and `options={{ syncWithLocation: true, disableTelemetry: true }}`. Refine's data hooks call TanStack Query's hooks, which read the nearest `QueryClientProvider`, so when a page calls them they use the cache around the routes, as they did before. Refine's own `authProvider` invalidates the cache Refine creates for itself, which pages do not read. Resolve a single copy of `@tanstack/react-query`, since the hooks of a second copy read another context and find no cache. An application that relied on Refine's translations also passes an `i18nProvider` of its own, because `createRefineI18nProvider` is no longer exported from `@nocobase/i18n/client`.
235
235
 
@@ -266,7 +266,7 @@ Verify the rendered directory/detail/history pages and parameter read/save behav
266
266
 
267
267
  ## Page permission label upgrades
268
268
 
269
- Reconcile `client/pages/settings/page-permissions.ts`, the role form's catalog adapter, the application-owned `page-permission-titles.ts` mapping, the localized unnamed-page fallback and `tests/logic/page-permission-titles.test.ts` together. Preserve existing mapping entries, route names, resource ids, actions, grants and policies; add translations for untitled page permissions rather than changing their authorization or adding breadcrumbs to overlays. Check the application's actual resolved routes in both languages, not just the bare template.
269
+ Reconcile `client/pages/settings/page-permissions.ts`, the role form's catalog adapter, the application-owned `page-permission-titles.ts` mapping, the localized unnamed-page fallback and `tests/client/page-permission-titles.test.ts` together. Preserve existing mapping entries, route names, resource ids, actions, grants and policies; add translations for untitled page permissions rather than changing their authorization or adding breadcrumbs to overlays. Check the application's actual resolved routes in both languages, not just the bare template.
270
270
 
271
271
  Reconcile the catalog descriptions, individual account-permission groups, category names without counts, individual action controls and labelled multi-scope summaries with the role form and locale updates. A display resource may share a stored resource ID with another display group: resolve a changed row by resource type, resource ID and action together, so later groups remain editable. Preserve all registered action IDs and existing unknown or structured policies. Update the authorization and Agent plugins together when adopting their new catalog labels, action-description metadata and administrative placement. An empty scope means no additional record access; retain default access, sharing and restriction behavior.
272
272