@nocobase/app-skills 0.1.0-beta.36 → 0.1.0-beta.38
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 +2 -2
- package/skills/nocobase-app-development/SKILL.md +28 -7
- package/skills/nocobase-app-development/references/business-administration.md +86 -0
- package/skills/nocobase-app-development/references/database-connections.md +1 -1
- package/skills/nocobase-app-development/references/frontend/references/api.md +5 -0
- package/skills/nocobase-app-development/references/frontend/references/example/list-page.md +1 -1
- package/skills/nocobase-app-development/references/frontend/references/example/server-table.md +25 -107
- package/skills/nocobase-app-development/references/frontend/references/example.md +2 -2
- package/skills/nocobase-app-development/references/frontend/references/overlay.md +6 -5
- package/skills/nocobase-app-development/references/frontend/references/page.md +6 -0
- package/skills/nocobase-app-development/references/frontend/references/table.md +30 -25
- package/skills/nocobase-app-development/references/frontend/references/testing.md +11 -59
- package/skills/nocobase-app-development/references/frontend/references/ui-library.md +32 -5
- package/skills/nocobase-app-development/references/frontend/ui-guidelines.md +2 -2
- package/skills/nocobase-app-development/references/lifecycle-parameters.md +12 -6
- package/skills/nocobase-app-development/references/lifecycle-ui.md +122 -0
- package/skills/nocobase-app-development/references/lifecycle.md +14 -8
- package/skills/nocobase-app-development/references/server-routes.md +11 -1
- package/skills/nocobase-app-development/references/services-and-jobs.md +10 -0
- package/skills/nocobase-app-development/references/system-administration.md +32 -0
- package/skills/nocobase-app-development/references/system-settings.md +83 -0
- package/skills/nocobase-app-development/references/template-variants.md +1 -1
- package/skills/nocobase-app-development/references/testing/cli/command.md +157 -0
- package/skills/nocobase-app-development/references/testing/cli/files.md +258 -0
- package/skills/nocobase-app-development/references/testing/client/page.md +301 -0
- package/skills/nocobase-app-development/references/testing/database/migration.md +50 -0
- package/skills/nocobase-app-development/references/testing/database/repository.md +160 -0
- package/skills/nocobase-app-development/references/testing/playwright/login.md +147 -0
- package/skills/nocobase-app-development/references/testing/server/routes.md +178 -0
- package/skills/nocobase-app-development/references/testing.md +69 -0
- package/skills/nocobase-app-upgrade/SKILL.md +2 -0
- package/skills/nocobase-app-upgrade/references/edge-cases.md +16 -0
- package/skills/nocobase-deployment/SKILL.md +2 -2
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@nocobase/app-skills",
|
|
3
|
-
"version": "0.1.0-beta.
|
|
3
|
+
"version": "0.1.0-beta.38",
|
|
4
4
|
"description": "Agent Skills for developing, upgrading and deploying NocoBase applications.",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"repository": {
|
|
@@ -18,7 +18,7 @@
|
|
|
18
18
|
"devDependencies": {
|
|
19
19
|
"@playwright/test": "^1.62.1",
|
|
20
20
|
"prettier": "^3.9.6",
|
|
21
|
-
"@nocobase/dev-config": "0.1.0-beta.
|
|
21
|
+
"@nocobase/dev-config": "0.1.0-beta.23"
|
|
22
22
|
},
|
|
23
23
|
"peerDependencies": {
|
|
24
24
|
"@playwright/test": "^1.62.1",
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: nocobase-app-development
|
|
3
3
|
description: >-
|
|
4
|
-
Primary entry for
|
|
5
|
-
pages, routes, components, endpoints, data, permissions, services, translations, and tests.
|
|
4
|
+
Primary entry for building complete NocoBase 3 applications and individual features:
|
|
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
7
|
Skills. Do not use for a published NocoBase 3 plugin package.
|
|
8
8
|
metadata:
|
|
@@ -11,7 +11,7 @@ metadata:
|
|
|
11
11
|
|
|
12
12
|
# NocoBase 3 application development
|
|
13
13
|
|
|
14
|
-
Use this Skill when building a
|
|
14
|
+
Use this Skill when building a complete application or an individual feature: business and administration pages, endpoints, data, services and their tests.
|
|
15
15
|
|
|
16
16
|
Do not use it to develop a published plugin package. Plugin development has its own protocol and lives in a separate repository.
|
|
17
17
|
|
|
@@ -59,6 +59,14 @@ For notification configuration or sending, follow the notification plugin Skill:
|
|
|
59
59
|
|
|
60
60
|
Install, update and customize plugins, and remove a direct NocoBase package, as [plugins](references/plugins.md) describes: `pnpm nocobase plugin register`, `plugin update` and `package remove` keep the manifest, the lockfile, the composition roots and the synchronized Skills consistent, so never hand-edit only one of them.
|
|
61
61
|
|
|
62
|
+
## Deliver system administration by default
|
|
63
|
+
|
|
64
|
+
When a user asks you to build a complete application, deliver a usable System management navigation section and administration pages alongside the business features, unless the user explicitly excludes them or requests a narrower deliverable such as an API-only service or a prototype explicitly limited to business screens. Users do not need to request administration pages individually. Include user management and role and permission management by default. Place workflow management, background tasks and other applicable administration entries directly under System management as siblings; show execution status, failures and supported recovery actions within each capability's pages, without an additional Operational monitoring group. Reuse existing pages and installed plugins, and implement missing application-owned pages. Read [system administration](references/system-administration.md) for the baseline, capability-specific pages and acceptance criteria. For a focused feature change, extend existing administration where that feature requires it.
|
|
65
|
+
|
|
66
|
+
Whenever application requirements include a process to develop, deliver its workflow management pages by default, even when the user mentions only the business process. Reuse the installed `workflow-management` UI Library block, or install it with `yes n | pnpm exec shadcn add @nocobase/workflow-management`. Follow [Lifecycle UI](references/lifecycle-ui.md) for installation, application adapters and the default layout: one Workflow management sidebar entry with in-page Definitions and Executions tabs, definition diagrams with visible parameter forms, and execution details with history and effects. The two tab views use URL-backed child routes without sidebar `navigation`. Extend an existing management area rather than adding a duplicate. Follow the scope exceptions in [system administration](references/system-administration.md#default-delivery).
|
|
67
|
+
|
|
68
|
+
For process management, distinguish administrator-adjustable reviewers, departments, thresholds and other [lifecycle parameters](references/lifecycle-parameters.md) from workflow structure, which remains defined in source unless a supported visual designer is explicitly required.
|
|
69
|
+
|
|
62
70
|
## Learn the endpoints from the API document
|
|
63
71
|
|
|
64
72
|
The running application describes every `/api` endpoint it serves — its own routes, every installed plugin's, the data endpoints and Better Auth's `/api/auth/...` — in an OpenAPI 3.1 document. Before calling an endpoint or building on one, fetch that document instead of reading route sources:
|
|
@@ -69,8 +77,14 @@ curl -H "x-api-key: <key>" http://127.0.0.1:13000/main/api/swagger
|
|
|
69
77
|
|
|
70
78
|
Replace `/main` with the application's `APP_BASE_PATH`. Swagger UI for people is at `<APP_BASE_PATH>/api/swagger/docs`. Reading either needs a signed-in session or an API key, which a signed-in user creates with `POST <APP_BASE_PATH>/api/apiKeys`; without one the routes answer `401`, and an application with no access check registered, such as one without the authentication plugin, answers `404`. Ask the user for a key rather than creating one yourself. [HTTP API design](references/http-api.md#api-documentation) explains how to read the document and how a new route declares itself in it.
|
|
71
79
|
|
|
80
|
+
## Include administration by default
|
|
81
|
+
|
|
82
|
+
For every application feature, apply [system settings delivery](references/system-settings.md): keep a newly created, Home-only application free of settings; as the application develops beyond that basic shell, reconcile the template's prepared Users and Roles and permissions routes and the management surfaces for each capability actually used. Inspect this on every build or iteration, enable missing routes once and preserve already enabled pages, including workflow definitions, diagrams, configuration and authorized execution history. When building process rules, proactively declare appropriate thresholds and reviewer choices as validated, authorized business parameters and provide visible parameter forms in workflow management, with optional diagram-bound shortcuts to the same editor; the user need not ask for configurability. Apply the same check to non-workflow business policy, mutable dictionaries, business document numbering, important operation records and the other used capabilities in that reference. Follow its [business administration recipes](references/business-administration.md) for application-owned implementations and acceptance. The real execution must consume the saved values; source/deployment configuration retains its owner. This is part of implementing the feature, not a separate user request.
|
|
83
|
+
|
|
72
84
|
## Frontend work
|
|
73
85
|
|
|
86
|
+
For business lists, reuse the template-provided `DataTable` and companions from `#components/data-table`, backed by the supported TanStack Table v8 dependency. Use its controlled manual mode for server paging/sorting. Do not replace it with an agent-written table engine when a dependency version is incompatible; inspect and repair the dependency first. See [tables](references/frontend/references/table.md).
|
|
87
|
+
|
|
74
88
|
Before writing or changing anything under `client/` — pages, components, styles, copy — read [the frontend workflow](references/frontend/ui-workflow.md). It decides whether the change takes the full workflow (a design file reviewed once, then an independent acceptance review), a theme change (tokens and presets, verified with the theme tests and a browser check) or a quick change (edit directly, then the static checks, the related tests and one look at the changed element in the browser), and which parts of [the UI guidelines](references/frontend/ui-guidelines.md) and [the frontend handbook](references/frontend/frontend-dev.md) to read at each step.
|
|
75
89
|
|
|
76
90
|
The handbook's "Look up by task" table routes each frontend task to the sections that cover it, and [the worked example](references/frontend/references/example.md) holds the complete files of the projects feature its rules are illustrated with. Components are shadcn/ui primitives, added with the CLI when a page first needs one: the shadcn/ui skill in `references/frontend/shadcn/` covers their API and composition rules, and [its guide in this handbook](references/frontend/references/shadcn.md) says what to read there and where this application departs from it.
|
|
@@ -84,7 +98,7 @@ Read the page for the task in front of you. Do not read all of them.
|
|
|
84
98
|
| Anything under `client/`: pages, routes, components, styling, forms, API calls, copy, frontend tests | [frontend workflow](references/frontend/ui-workflow.md), which routes to the [frontend handbook](references/frontend/frontend-dev.md), the theme reference or the worked example |
|
|
85
99
|
| Add an API endpoint, a webhook, or a callback; authenticate and authorize it | [server routes](references/server-routes.md) |
|
|
86
100
|
| Name an endpoint, shape its response or errors, validate its input, paginate a list, document it in the API document | [HTTP API design](references/http-api.md) |
|
|
87
|
-
| A list,
|
|
101
|
+
| A list, chart or polled endpoint, or keeping one live: read it with a fixed number of queries, refresh only what changed | [server routes](references/server-routes.md#lists-and-statistics-a-fixed-number-of-queries) and [client API requests](references/frontend/references/api.md#keeping-lists-and-charts-live) |
|
|
88
102
|
| Query or write data, resolve the database, work with transactions | [database and data access](references/database-and-data.md) |
|
|
89
103
|
| Create a table, alter a column, add an index, write required initial data | [migrations and seeds](references/migrations.md) |
|
|
90
104
|
| Switch the database, register a dialect, add a second connection | [database connections](references/database-connections.md) |
|
|
@@ -93,9 +107,10 @@ Read the page for the task in front of you. Do not read all of them.
|
|
|
93
107
|
| Design who gets what across departments, heads and cross-department work | [organisation permission design](references/organization/permission-design.md) |
|
|
94
108
|
| Add a reusable service, share it across routes, run background or scheduled work | [services and jobs](references/services-and-jobs.md) |
|
|
95
109
|
| A record that moves through stages defined in code: approvals, tickets, orders, timeouts, effects after a state change | [record lifecycles](references/lifecycle.md) |
|
|
96
|
-
| Administrator-adjustable approval departments, reviewers, thresholds or business values in a code-defined lifecycle | [configurable lifecycle parameters](references/lifecycle-parameters.md); keep workflow structure in source.
|
|
110
|
+
| Administrator-adjustable approval departments, reviewers, thresholds or business values in a code-defined lifecycle | [configurable lifecycle parameters](references/lifecycle-parameters.md); keep workflow structure in source. For management forms and optional diagram-bound editing, see [Lifecycle UI](references/lifecycle-ui.md). |
|
|
111
|
+
| Lifecycle definition catalogs, execution lists, process details, history or parameter settings | [Lifecycle UI](references/lifecycle-ui.md) |
|
|
97
112
|
| Flowcharts, process diagrams or lifecycle state diagrams | Use UI Library `@nocobase/flow-diagram` for generic graphs and `@nocobase/lifecycle-diagram` for lifecycle descriptions; see [diagram guidance](references/lifecycle.md#draw-an-interactive-lifecycle-diagram) and the [UI catalog](references/frontend/references/ui-library.md#diagrams). Preserve their application theme tokens. |
|
|
98
|
-
|
|
|
113
|
+
| Use `@nocobase/app-testing` for database, server, client or CLI tests; verify before finishing | [testing and verification](references/testing.md) |
|
|
99
114
|
| Run a CLI command: configure, migrate, manage plugins, read the data model | [the command line](references/cli.md) |
|
|
100
115
|
| Add or change an application command under `cli/commands/` | [adding an application command](references/commands.md) |
|
|
101
116
|
| Where a file goes, how the client and server are composed, configuration, changing the framework structure | [application structure](references/app-structure.md) |
|
|
@@ -134,7 +149,7 @@ Everything else — `client/routing/`, `client/layouts/`, `client/theme/`, the s
|
|
|
134
149
|
|
|
135
150
|
When the built-in mechanism genuinely cannot express the requirement, changing that structure is a legitimate answer. Comment what you changed and why the built-in path did not fit, and in the same change record the application-specific guidance in the matching `.agents/rules/<topic>.md`, adding its entry to the `AGENTS.md` index, so the guidance still describes the real application. Do not write the detail into `AGENTS.md` itself: it is a small always-on index of at most 32 KB that every agent loads on every start. The synchronized NocoBase Skills are package-owned; propose a change to their source package when the shared framework guidance itself is wrong.
|
|
136
151
|
|
|
137
|
-
When you do change the shell (`client/layouts/`, `client/routing/`), keep the behaviors listed in [customizing the shell](references/frontend/references/shell.md#1-behaviors-to-keep): a single App shell with
|
|
152
|
+
When you do change the shell (`client/layouts/`, `client/routing/`), keep the behaviors listed in [customizing the shell](references/frontend/references/shell.md#1-behaviors-to-keep): a single App shell with administration pages in the main sidebar rather than a separate settings layout, the language submenu, navigation group state, permission refresh and sign-out handling.
|
|
138
153
|
|
|
139
154
|
## Ownership
|
|
140
155
|
|
|
@@ -165,6 +180,8 @@ When customizing template or registry UI, prefer existing props and composition,
|
|
|
165
180
|
|
|
166
181
|
Treat disabling a feature as a reversible availability change by default: preserve its page and component source, conditionally exclude or guard its route, and hide its links and actions. A hidden navigation item alone does not disable direct URL access. Enforce the same feature policy on the server so direct API calls cannot execute the disabled operation. Do not delete feature code merely to remove it from the current UI; explicit permanent removal can justify deletion. See [pages and routes](references/frontend/references/page.md).
|
|
167
182
|
|
|
183
|
+
When workflows or approvals are used, deliver a standard process-management table first, even for a single process. A row opens that process's definition/design, node configuration and scoped execution history. Use the standard vertically arranged, automatically sized lifecycle diagram by default, with readable node summaries and configuration buttons; do not wait for an explicit request for these system settings. Reconcile later processes into the same directory and validate their identifiers and authorization on the server; a bare Home-only create-app still gets no unused settings. See [system settings delivery](references/system-settings.md).
|
|
184
|
+
|
|
168
185
|
## Non-negotiables
|
|
169
186
|
|
|
170
187
|
These cause real damage and appear in every reference:
|
|
@@ -210,3 +227,7 @@ Authentication diagnostics use the application `auth` logger unless an explicit
|
|
|
210
227
|
## Storage
|
|
211
228
|
|
|
212
229
|
Standalone source and compiled entries share the deployment directory's storage; `APP_STORAGE_DIR` selects another storage directory, and explicit storage paths take precedence over it. Embedded applications use Host-provided paths. Expanded releases live at `appRevisionsDir/<appId>/<sha256>` and restart recovery requires their installed metadata. Build archives use `storage/exports/dist.tar.gz`.
|
|
230
|
+
|
|
231
|
+
## Process UI delivery gate
|
|
232
|
+
|
|
233
|
+
When adding a business process, read [Lifecycle UI](references/lifecycle-ui.md#default-diagram-and-configuration-contract) before selecting a renderer. Current templates already ship the standard React Flow components and workflow-management parts. Preserve their default style unless the user explicitly requests another style; declare and connect suitable business parameters and contextual configuration automatically. UI Registry entries are not npm packages: an npm 404 is not installation failure. Acceptance must compare actual component use and configuration behavior to the original requirement, even if an intermediate design approved a fallback.
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
# Application-owned business administration
|
|
2
|
+
|
|
3
|
+
Use these recipes with [system settings delivery](system-settings.md) whenever a business feature implies administrator-maintained policy, reference data or operational visibility. They are implementation contracts for the building Agent, not claims that a generic dictionary, numbering or audit plugin is installed. Inspect the actual application and plugin Skills first, reuse existing services, and implement missing application-owned routes, migrations, permissions and pages as part of the feature. A bare Home-only application still registers none of these pages.
|
|
4
|
+
|
|
5
|
+
## Delivery pattern
|
|
6
|
+
|
|
7
|
+
1. Identify the administrator's actual decision and the business operation that consumes it. Define the scope, initial value and effective timing from the requirement or authoritative application state. Do not invent people, organization membership, regulatory policy or external credentials.
|
|
8
|
+
2. Reuse the owning plugin's public API. For application-owned persistence, follow [database and data](database-and-data.md), [migrations](migrations.md) and [HTTP APIs](http-api.md). Do not assume platform endpoints exist because a package or a similar example is installed.
|
|
9
|
+
3. Declare typed schemas, authorized read/write operations and stable keys. Validate and enforce scope on the server before looking up sensitive entities. Use an atomic revision precondition for concurrently edited settings, retaining drafts on conflicts.
|
|
10
|
+
4. Connect the actual business execution to the persisted configuration. Add the existing Settings entry or contextual editor only after the backend contract works. Reuse standard DataTable for management lists and the standard parameter editor contract for bound lifecycle parameters.
|
|
11
|
+
5. Reconcile existing state rather than re-seeding it. Create only missing defaults, routes and bindings, preserve edited values and unrelated grants, and verify a second reconciliation changes nothing. A schema evolution needs an explicit compatibility policy and migration where required.
|
|
12
|
+
6. Verify a valid administrator change, execution with that change, denied direct requests, invalid input, concurrent edits and historical behavior. Report observed results and any unsupported capability; do not replace missing functionality with an editable-looking placeholder.
|
|
13
|
+
|
|
14
|
+
## Business parameters
|
|
15
|
+
|
|
16
|
+
Extract administrator-owned values from actual business rules even without a configurability request: amounts, quantities, validity windows, warnings, supported switches or shared defaults. Keep authorization guards, workflow structure, technical constants and secrets source-owned. Infer administrator ownership from the business purpose and expected maintenance rather than requiring explicit "configurable" wording. Fixed technical/application invariants remain source-owned.
|
|
17
|
+
|
|
18
|
+
For a lifecycle, use [configurable lifecycle parameters](lifecycle-parameters.md), including explicit groups/bindings, complete-group saves, server validation, snapshot/live modes and usage history. For policy outside a lifecycle, inspect the application's existing service; otherwise implement an application-owned settings record with a stable key, typed payload, scope and revision. Use documented Repository/transaction contracts, reject undeclared fields, and compare the revision atomically when saving. The update response returns the effective saved values and revision; a stale write reports a conflict without overwriting either editor's work. This recipe does not add a generic platform configuration API.
|
|
19
|
+
|
|
20
|
+
Choose defaults from the requested policy or existing authoritative configuration and preserve them when the page is first enabled. Show units, bounds, dependent constraints and effective timing. Resolve the saved values in the real server-side calculation, route or task construction; shared caches must be invalidated consistently. A form over an unchanged hard-coded condition is incomplete. Decide whether documents retain the policy used when created/submitted or use current policy later; financial amounts and historical facts must not be silently recalculated.
|
|
21
|
+
|
|
22
|
+
For currency, units, reporting timezone and working calendars, define the affected calculation/report and storage convention before exposing edits. UI language, formatting timezone, business cutoff timezone and stored timestamps are different concerns. A display preference does not move historical timestamps or reschedule existing jobs. Startup configuration and browser-local preferences keep their documented ownership and precedence.
|
|
23
|
+
|
|
24
|
+
## Business dictionaries
|
|
25
|
+
|
|
26
|
+
Use a dictionary when the business needs to maintain options such as expense categories, lead sources, priorities or reason codes. Fixed technical states and permission action identifiers stay in code. Customers, suppliers, products and other substantive business entities keep their own business modules.
|
|
27
|
+
|
|
28
|
+
Reuse an existing reference-data service or create application-owned dictionary/item persistence. Give each dictionary and item a stable identifier and unique key within the application's actual scope, plus a display label, sort order and enabled flag. Add translated labels or extra metadata only when the feature needs them. Bind forms, filters, imports and server validation to these authoritative entries; changing the Settings page alone must not leave a second hard-coded option list in use.
|
|
29
|
+
|
|
30
|
+
An ordinary create/edit picker offers enabled items. Existing records still resolve disabled referenced items for display, and editing an unrelated field must preserve their valid existing references. Disable an in-use item instead of cascading its deletion into business records; reject removal or key reuse that would corrupt references. Define whether historical documents use their captured label or the current label and preserve that convention on renames. Seed missing initial items by stable key without overwriting administrator changes on restart or later development.
|
|
31
|
+
|
|
32
|
+
Verify that a new item becomes available in the real business form, a disabled item cannot be newly assigned through a direct API request, existing references remain readable, and repeated provisioning does not duplicate or reset items. Verify scope boundaries and sorting, not just the appearance of a dictionary page.
|
|
33
|
+
|
|
34
|
+
## Business document numbering
|
|
35
|
+
|
|
36
|
+
Provide this when users need a meaningful purchase-order, contract, invoice or request number. Internal primary keys remain generated by the application's normal ID service and are not editable numbering rules. Reuse an installed numbering service if present; otherwise implement the application-owned allocator with the database's documented atomic transaction/unique-constraint facilities.
|
|
37
|
+
|
|
38
|
+
Declare supported prefix, date segment, timezone, sequence partition and width fields with validation. Treat the format as constrained data rather than executable templates or arbitrary code. Show a non-consuming example; opening or previewing settings must not advance a counter. A rule change affects future allocation and never rewrites issued numbers or blindly resets a used counter.
|
|
39
|
+
|
|
40
|
+
Allocate in the authoritative server operation, using an atomic counter/reservation and a unique constraint in the correct business scope. A read-then-increment in application memory or a browser-generated number is insufficient. All create paths, imports, bulk actions and background jobs use the same allocator. Replay of the same successful logical request returns the same record/number; retry a transient allocation conflict without creating a second business operation. Define gaps and failed-transaction behavior explicitly; uniqueness does not imply gap-free numbering.
|
|
41
|
+
|
|
42
|
+
Test concurrent allocation, a replayed request, a failed transaction, a period boundary, a format change that could collide with existing numbers, and the absence of counter changes during preview. Preserve issued numbers and existing uniqueness guarantees when migrating a rule.
|
|
43
|
+
|
|
44
|
+
## Important operation records
|
|
45
|
+
|
|
46
|
+
When implementing account/role administration, configurable business rules or other important administrator actions, reuse an installed audit/event service. If none exists and these actions need a history, implement application-owned server capture and storage with the feature rather than generating a log page with invented data. Diagnostic console logs and a row's current revision do not constitute a searchable change history.
|
|
47
|
+
|
|
48
|
+
Capture the authenticated actor, server timestamp, action, target identifier, scope, result and an allowlisted change summary at the authoritative service boundary. Cover alternate routes, bulk actions, jobs and retries where those operations exist. Successful database mutations and their audit fact must commit together, or use the application's transactional outbox with replay-safe delivery. Never report success for a rolled-back change. Denied attempts, reads, login failures and external outcomes use the appropriate independent event path when supported; they do not fabricate a committed database mutation.
|
|
49
|
+
|
|
50
|
+
Use a schema allowlist for before/after summaries; exclude credentials, tokens, secret settings, uploaded contents and unnecessary personal/business payloads. Display explicit unknown/unrecorded history for operations predating capture. Authorization must filter event rows and linked records on the server. Users allowed to view history do not gain permission to rewrite it. Retention and deletion follow the existing server/operations policy, with supported controls only.
|
|
51
|
+
|
|
52
|
+
Verify one actual change and its actor/result, a failed mutation without a false success entry, a replay without duplicate audit facts, protected fields absent from stored payloads, and an unauthorized history request. State any historical coverage or retention limitation accurately.
|
|
53
|
+
|
|
54
|
+
## Extend the other capability surfaces
|
|
55
|
+
|
|
56
|
+
| Capability | Implementation boundary and observable result |
|
|
57
|
+
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
58
|
+
| Organization and approval relationships | Reuse the actual organization source or explicitly enabled authentication extension with its migration. Maintain the real manager/member/position relationships used by approvals and data scope. Filter inactive/ineligible users on the server; changes follow the task/snapshot contract rather than silently replacing existing assignees. |
|
|
59
|
+
| Authentication and account security | Read the authentication and Users Skills. Enabled SSO, registration, MFA or passkeys need their supported configuration, migrations and UI. Offer actual account/session controls. Show login history only when captured; source-owned login policy and secrets do not become runtime-editable merely because there is a form. |
|
|
60
|
+
| Notifications and mail | Reuse the notification/mail Skills for channels, ownership, message/recipient rules and real delivery states. Configurable templates must be the ones the sender actually resolves. Keep credential updates on the supported server path, masked in reads. A manual resend uses the service's documented idempotency and unknown-submission semantics. |
|
|
61
|
+
| Files and storage | Reuse File Repository and the installed preview/attachment UI. Apply actual type/size policy on upload and authorized content reads. Provide relevant metadata/status and supported policy controls, while disk credentials and deployment-owned configuration remain with operations. |
|
|
62
|
+
| Scheduled work | Reuse the Scheduler Skill, with real targets, execution history, timezone and authorized enable/disable. Current Scheduler Cron definitions are code-owned; do not fabricate Cron editing or cancellation/retry APIs. Distinguish schedule availability from an already running execution. |
|
|
63
|
+
| Integrations, Webhooks and API access | Expose the connections and supported status/delivery/sync records actually used. Reuse the API Keys Skill; default endpoints own the current caller's keys and inherit that owner's session permissions. Per-key scopes require the documented alternative configuration and server enforcement. No default key, arbitrary secret readback or unimplemented Test connection button. |
|
|
64
|
+
| Printing and business templates | Read the template-print Skill: the package provides guidance, not a rendering service or an installed template-management API. Reuse fixed App assets when appropriate; implement authorized managed uploads/versioning only when business users need to maintain templates. The actual renderer consumes the selected version, and preview/download respect business data scope. |
|
|
65
|
+
| Import/export and bulk processing | Use authoritative dictionaries, field validation, business authorization and the shared numbering path. Record real processing results, rejected rows and failure details. Long work uses an installed job service when applicable, with only its supported progress/retry controls. Replays do not duplicate imported records or external effects. |
|
|
66
|
+
| App-owned AI/model calls and knowledge | Inspect the installed Agents/model-service and knowledge contracts. Mount real catalogs, enabled configuration, allowed prompt/content maintenance and available run diagnostics only when the application uses them. Knowledge may be versioned documents rather than a vector database. Do not invent model discovery, agent creation, token-cost statistics or editable credentials unsupported by the actual service. |
|
|
67
|
+
|
|
68
|
+
Read only the installed plugin Skills relevant to the capability. The application owns composition; a dependency alone creates neither a management page nor a runtime API.
|
|
69
|
+
|
|
70
|
+
## Acceptance scenarios
|
|
71
|
+
|
|
72
|
+
Use a disposable application against one consistent package snapshot. Keep the capability request separate from administration hints so automatic delivery can actually be assessed. Record these as manual/unverified until an Agent build and runtime check have been performed; formatting or component tests do not prove Agent discovery.
|
|
73
|
+
|
|
74
|
+
| Request without asking for a settings page | Expected automatic delivery and verification |
|
|
75
|
+
| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
76
|
+
| Create a basic Default App | Home only; no settings route/menu, business seed or empty capability cards. |
|
|
77
|
+
| Build a purchase-request register with employee/admin access, filtering and 65 records | Core Users/Roles, scoped server enforcement and standard DataTable with 20/20/20/5 paging. No unused workflow administration. |
|
|
78
|
+
| Classify requests by purchase category and report totals by category | Dictionary administration and real picker/API integration. Add/disable a category; existing references survive and disabled items cannot be newly assigned. |
|
|
79
|
+
| Give purchase requests human-readable numbers with a prefix and date | Numbering administration/preview and a shared atomic allocator. Concurrent requests have unique numbers; a replay returns the same record and preview consumes none. |
|
|
80
|
+
| Add manager approval and finance review above a stated amount | Definitions, standard diagram, threshold/reviewer configuration and authorized executions. Change a rule and verify a new eligible submission; preserve prior snapshots/tasks. |
|
|
81
|
+
| Warn when an item's stock falls below 10, without an approval flow | Real typed business settings consumed by the server's warning calculation; no artificial lifecycle dependency or unused workflow page. |
|
|
82
|
+
| Change a role or a business rule | An authorized real operation record with actor/time/result and safe change summary; failed/replayed writes follow the defined event semantics. |
|
|
83
|
+
| Add notifications, scheduled reminders, attachments or an external integration in later rounds | Only the used capability's supported administration appears, with actual status/results and correct ownership. Existing settings, values and permissions remain intact. |
|
|
84
|
+
| Repeat a feature iteration and restart | No duplicate routes, dictionary items, rules, counters, role grants or configuration bindings; administrator edits and historical data remain intact. |
|
|
85
|
+
|
|
86
|
+
For chosen interfaces also verify loading/empty/error states, failed saves, conflict drafts, an ordinary user's denied direct requests, Chinese/English, light/dark and narrow layouts. Keep the delivery report factual: identify what was generated, what ran, and what remains unverified.
|
|
@@ -211,4 +211,4 @@ Application server builds retain declaration emission with `isolatedDeclarations
|
|
|
211
211
|
|
|
212
212
|
Application templates declare `@nocobase/db-sqlite`, the driver for the dialect their `server/config/database.ts` defaults to, and `create-app` adds no other. Any further driver an application's configuration needs — for its main connection or an additional one — has to be installed into its `dependencies` before building, because a deployment installs only what the application declares.
|
|
213
213
|
|
|
214
|
-
KingbaseES, Dameng and OceanBase drivers are
|
|
214
|
+
KingbaseES, Dameng and OceanBase drivers are NocoBase Pro commercial packages requiring the appropriate commercial license and authenticated access to the private package registry. Install the selected package in the application’s production dependencies, then configure its dialect and connection settings. Automatic loading and `config init --dialect` remain supported; explicit registration in `database.drivers` is optional and takes precedence.
|
|
@@ -307,6 +307,11 @@ When realtime events refresh what a page shows:
|
|
|
307
307
|
- Recompute a chart's figures at most every few seconds while it is visible, and not at all while the page is hidden; or update only the figure the event affects.
|
|
308
308
|
- Read nothing for a page that is not shown; read it when it is shown again.
|
|
309
309
|
- A component that needs one small fact reads the small endpoint that answers it, not the list that happens to contain it.
|
|
310
|
+
- Keep realtime subscriptions in one place, such as the page or a hook it owns, rather than one per row or card, and subscribe only to the topics the page shows.
|
|
311
|
+
- When a refresh is triggered while a request for the same data is still in flight, usually let it finish and read once more afterwards rather than aborting it and sending it again; repeated aborts under a stream of events can mean no request ever completes. Aborting is still right when the parameters change or the component unmounts, as above.
|
|
312
|
+
- Skip fetching while the page is hidden (`document.visibilityState`), and refresh once when it becomes visible again.
|
|
313
|
+
- Keep request keys stable: build them from the parameters that decide the data, not from values that change on every render or tick, such as the current time, or each change starts a new request.
|
|
314
|
+
- Be careful with data loaded by components mounted on every page, such as navigation or a header badge: they run on every page and in every open tab, so they usually read a small fact rather than a list.
|
|
310
315
|
|
|
311
316
|
The server side of these reads is in [server routes](../../server-routes.md#lists-and-statistics-a-fixed-number-of-queries).
|
|
312
317
|
|
|
@@ -4,7 +4,7 @@ Part of the [projects worked example](../example.md).
|
|
|
4
4
|
|
|
5
5
|
**Depends on**: [delete dialog](delete-dialog.md), [status badge](../i18n.md#dynamic-keys), [session alert](session-expired-alert.md), [types](types.md), [search hook](url-search.md), [copy](copy.md); the `projects` route in [section 1 of `page.md`](../page.md#1-declare-the-route).
|
|
6
6
|
|
|
7
|
-
**Add first**: `yes n | pnpm exec shadcn add alert empty input-group select skeleton table`, then format the files it creates ([how](../shadcn.md#1-what-the-template-ships-and-how-to-add-the-rest)), and
|
|
7
|
+
**Add first**: `yes n | pnpm exec shadcn add alert empty input-group select skeleton table`, then format the files it creates ([how](../shadcn.md#1-what-the-template-ships-and-how-to-add-the-rest)), and reuse the template's shipped `DataTable` in `client/components/data-table/` with its supported `@tanstack/react-table` v8 dependency ([section 1 of `table.md`](../table.md#1-choosing-a-table-component)).
|
|
8
8
|
|
|
9
9
|
**Links to**: the [create dialog](create-dialog.md), the [detail drawer](detail-drawer.md) and the [edit dialog](edit-dialog.md), which a row's menu opens alone, are its child routes. Without a detail view, render the name as plain text: a link to a route that does not exist lands on the home page.
|
|
10
10
|
|
package/skills/nocobase-app-development/references/frontend/references/example/server-table.md
CHANGED
|
@@ -8,7 +8,7 @@ Part of the [projects worked example](../example.md).
|
|
|
8
8
|
|
|
9
9
|
**Links to**: the same child routes as the list page.
|
|
10
10
|
|
|
11
|
-
Rules: [section 1 of `table.md`](../table.md#1-choosing-a-table-component).
|
|
11
|
+
Rules: [section 1 of `table.md`](../table.md#1-choosing-a-table-component). This adapter uses the standard `DataTable` in manual mode when the endpoint paginates; the list page keeps the page in the URL and passes it down.
|
|
12
12
|
|
|
13
13
|
The endpoint contract this assumes is the one in [types](types.md): `GET /api/projects` takes `page` (from 1), `pageSize` (at most 100) and `orderBy` besides `q` and `status`, and returns `{ data: Project[], meta: { page, pageSize, total } }` (`ProjectList`), where `total` counts the matching records on all pages. `orderBy` names a column the endpoint sorts by, `name` (in the order of the request's language) or `updatedAt`, followed by ` desc` for descending; the page always sends it, `updatedAt desc` by default (guideline T1.8).
|
|
14
14
|
|
|
@@ -225,49 +225,27 @@ The component it renders:
|
|
|
225
225
|
|
|
226
226
|
```tsx
|
|
227
227
|
// client/pages/projects/projects-server-table.tsx
|
|
228
|
-
import {
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
type PaginationState,
|
|
233
|
-
type SortingState,
|
|
234
|
-
useReactTable,
|
|
228
|
+
import type {
|
|
229
|
+
ColumnDef,
|
|
230
|
+
PaginationState,
|
|
231
|
+
SortingState,
|
|
235
232
|
} from '@tanstack/react-table';
|
|
236
233
|
import type { ReactElement, ReactNode } from 'react';
|
|
237
|
-
|
|
238
|
-
import { DataTablePagination } from '#components/data-table/pagination';
|
|
239
|
-
import {
|
|
240
|
-
Table,
|
|
241
|
-
TableBody,
|
|
242
|
-
TableCell,
|
|
243
|
-
TableHead,
|
|
244
|
-
TableHeader,
|
|
245
|
-
TableRow,
|
|
246
|
-
} from '#components/ui/table';
|
|
247
|
-
|
|
234
|
+
import { DataTable } from '#components/data-table';
|
|
248
235
|
import type { Project } from './types.js';
|
|
249
236
|
|
|
250
237
|
export interface ProjectsServerTableProps {
|
|
251
238
|
readonly columns: ColumnDef<Project>[];
|
|
252
|
-
/** The rows of the current page, as the endpoint returned them. */
|
|
253
239
|
readonly rows: Project[];
|
|
254
|
-
/** The number of matching records on all pages, from the endpoint. */
|
|
255
240
|
readonly total: number;
|
|
256
|
-
/** The page read from the URL; pageIndex starts at 0. */
|
|
257
241
|
readonly pagination: PaginationState;
|
|
258
|
-
/** Writes the new page to the URL; the list request follows the URL. */
|
|
259
242
|
readonly onPaginationChange: (pagination: PaginationState) => void;
|
|
260
|
-
/** The sort read from the URL, which the endpoint applied. */
|
|
261
243
|
readonly sorting: SortingState;
|
|
262
|
-
/** Writes the new sort to the URL; the list request follows the URL. */
|
|
263
244
|
readonly onSortingChange: (sorting: SortingState) => void;
|
|
264
|
-
/** Shown when the page has no rows, as DataTable's emptyMessage. */
|
|
265
245
|
readonly emptyMessage: ReactNode;
|
|
266
|
-
/** The rows-per-page choices; the list page accepts only these from the URL. */
|
|
267
246
|
readonly pageSizeOptions: readonly number[];
|
|
268
247
|
}
|
|
269
248
|
|
|
270
|
-
/** The markup of DataTable, paginated and sorted by the server instead of the browser. */
|
|
271
249
|
export function ProjectsServerTable({
|
|
272
250
|
columns,
|
|
273
251
|
rows,
|
|
@@ -279,86 +257,26 @@ export function ProjectsServerTable({
|
|
|
279
257
|
emptyMessage,
|
|
280
258
|
pageSizeOptions,
|
|
281
259
|
}: ProjectsServerTableProps): ReactElement {
|
|
282
|
-
// TanStack Table returns a mutable instance the React Compiler cannot memoize, as in `data-table/index.tsx`.
|
|
283
|
-
// eslint-disable-next-line react-hooks/incompatible-library
|
|
284
|
-
const table = useReactTable({
|
|
285
|
-
data: rows,
|
|
286
|
-
columns,
|
|
287
|
-
getRowId: (row) => row.id,
|
|
288
|
-
getCoreRowModel: getCoreRowModel(),
|
|
289
|
-
// The server already paginated and sorted: no pagination or sorted row model, and the page count comes from
|
|
290
|
-
// rowCount. Sorting one page in the browser would mislead, so the header only shows and changes the URL's sort.
|
|
291
|
-
manualPagination: true,
|
|
292
|
-
manualSorting: true,
|
|
293
|
-
rowCount: total,
|
|
294
|
-
state: { pagination, sorting },
|
|
295
|
-
onPaginationChange: (updater) => {
|
|
296
|
-
onPaginationChange(
|
|
297
|
-
typeof updater === 'function' ? updater(pagination) : updater,
|
|
298
|
-
);
|
|
299
|
-
},
|
|
300
|
-
onSortingChange: (updater) => {
|
|
301
|
-
onSortingChange(
|
|
302
|
-
typeof updater === 'function' ? updater(sorting) : updater,
|
|
303
|
-
);
|
|
304
|
-
},
|
|
305
|
-
});
|
|
306
|
-
const pageRows = table.getRowModel().rows;
|
|
307
|
-
|
|
308
260
|
return (
|
|
309
|
-
<
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
<TableBody>
|
|
329
|
-
{pageRows.length > 0 ? (
|
|
330
|
-
pageRows.map((row) => (
|
|
331
|
-
<TableRow key={row.id}>
|
|
332
|
-
{row.getVisibleCells().map((cell) => (
|
|
333
|
-
<TableCell key={cell.id}>
|
|
334
|
-
{flexRender(
|
|
335
|
-
cell.column.columnDef.cell,
|
|
336
|
-
cell.getContext(),
|
|
337
|
-
)}
|
|
338
|
-
</TableCell>
|
|
339
|
-
))}
|
|
340
|
-
</TableRow>
|
|
341
|
-
))
|
|
342
|
-
) : (
|
|
343
|
-
<TableRow>
|
|
344
|
-
<TableCell
|
|
345
|
-
colSpan={columns.length}
|
|
346
|
-
className='h-24 text-center text-muted-foreground'
|
|
347
|
-
>
|
|
348
|
-
{emptyMessage}
|
|
349
|
-
</TableCell>
|
|
350
|
-
</TableRow>
|
|
351
|
-
)}
|
|
352
|
-
</TableBody>
|
|
353
|
-
</Table>
|
|
354
|
-
</div>
|
|
355
|
-
{/* Reads the page index and page count from the table instance. */}
|
|
356
|
-
<DataTablePagination
|
|
357
|
-
table={table}
|
|
358
|
-
pageSizeOptions={pageSizeOptions}
|
|
359
|
-
showSelectedCount={false}
|
|
360
|
-
/>
|
|
361
|
-
</div>
|
|
261
|
+
<DataTable
|
|
262
|
+
columns={columns}
|
|
263
|
+
data={rows}
|
|
264
|
+
getRowId={(row) => String(row.id)}
|
|
265
|
+
manualPagination
|
|
266
|
+
rowCount={total}
|
|
267
|
+
paginationState={pagination}
|
|
268
|
+
onPaginationChange={(next) =>
|
|
269
|
+
onPaginationChange(typeof next === 'function' ? next(pagination) : next)
|
|
270
|
+
}
|
|
271
|
+
manualSorting
|
|
272
|
+
sortingState={sorting}
|
|
273
|
+
onSortingChange={(next) =>
|
|
274
|
+
onSortingChange(typeof next === 'function' ? next(sorting) : next)
|
|
275
|
+
}
|
|
276
|
+
emptyMessage={emptyMessage}
|
|
277
|
+
pageSizeOptions={pageSizeOptions}
|
|
278
|
+
showSelectedCount={false}
|
|
279
|
+
/>
|
|
362
280
|
);
|
|
363
281
|
}
|
|
364
282
|
```
|
|
@@ -18,10 +18,10 @@ Read the document for your task, and every document its **Depends on** line name
|
|
|
18
18
|
|
|
19
19
|
The template ships neither `client/components/session-expired-alert.tsx` nor `client/hooks/use-url-search.ts`. They are shared infrastructure rather than feature code: the first feature that needs one copies it unchanged from its document here, and later features import it.
|
|
20
20
|
|
|
21
|
-
The template ships
|
|
21
|
+
The template ships the standard `DataTable` and its companions plus the primitives its shell and compositions use. A document whose file imports another primitive or `DataTable` says so on its **Add first** line; run that command before your code imports one, then format the files it creates, as [section 1 of `shadcn.md`](shadcn.md#1-what-the-template-ships-and-how-to-add-the-rest) describes. The whole feature needs:
|
|
22
22
|
|
|
23
23
|
```bash
|
|
24
24
|
yes n | pnpm exec shadcn add alert alert-dialog badge card chart checkbox combobox empty field input-group radio-group select skeleton switch table textarea
|
|
25
25
|
```
|
|
26
26
|
|
|
27
|
-
`chart` installs `recharts`; move it to `devDependencies` ([section 1 of `shadcn.md`](shadcn.md#1-what-the-template-ships-and-how-to-add-the-rest)). `DataTable` is
|
|
27
|
+
`chart` installs `recharts`; move it to `devDependencies` ([section 1 of `shadcn.md`](shadcn.md#1-what-the-template-ships-and-how-to-add-the-rest)). `DataTable` is already shipped in `client/components/data-table/` and should be reused, as [section 1 of `table.md`](table.md#1-choosing-a-table-component) describes, with `@tanstack/react-table` in `devDependencies`.
|
|
@@ -104,7 +104,7 @@ Both take the same props:
|
|
|
104
104
|
| `title` | `ReactNode`, required | Title at the top, which is also the overlay's accessible name |
|
|
105
105
|
| `description` | `ReactNode` | Description under the title |
|
|
106
106
|
| `children` | `ReactNode` | Content area; scrolls internally when its content exceeds the height |
|
|
107
|
-
| `footer` | `ReactNode` | Fixed bottom area
|
|
107
|
+
| `footer` | `ReactNode` | Fixed bottom area rendered in `DialogFooter`: the buttons sit together on the right, and on narrow screens they stack with the last one on top |
|
|
108
108
|
| `closeTo` | `To` | Where to go after closing. Defaults to the parent route `{ pathname: '..', search: location.search, hash: '' }`, resolved by route hierarchy, keeping the query parameters and dropping the hash |
|
|
109
109
|
| `beforeClose` | `() => boolean \| Promise<boolean>` | Called before closing; returning `false` keeps the overlay open |
|
|
110
110
|
| `className` | `string` | Added to the panel to adjust its width: dialogs default to `sm:max-w-2xl`, drawers to `sm:max-w-xl`; a create or edit dialog of 1–4 fields passes `sm:max-w-md` (guideline I1) |
|
|
@@ -112,7 +112,8 @@ Both take the same props:
|
|
|
112
112
|
What the components already do:
|
|
113
113
|
|
|
114
114
|
- **Size**: a dialog is centered, is the screen width minus 2rem wide on narrow screens, and has a maximum height of `100dvh - 2rem`; a drawer sits against the right edge at full height and takes the full width on narrow screens. The title area and the bottom button area are fixed and only the content area scrolls, so the bottom buttons stay reachable on narrow screens too (guideline A4); there is no need to add `max-h` or `overflow` to the panel.
|
|
115
|
-
- **Content container**: the content area already has
|
|
115
|
+
- **Content container**: the content area already has the dialog's padding. Do not nest a `PageContainer` inside it, and do not add outer padding of your own.
|
|
116
|
+
- **Look**: the title, description and footer are the dialog primitives (`DialogHeader`, `DialogTitle`, `DialogDescription`, `DialogFooter` from `#components/ui/dialog`) inside the same padding, spacing and close-button position as `DialogContent`, so a route overlay looks like any other dialog of the application, and a change to the dialog primitive or its theme rules reaches both. A drawer uses the same regions against the right edge.
|
|
116
117
|
- **Ways to close**: a close button is built into the top-right corner (its accessible name comes from `routeOverlay.close`); Esc and clicking the backdrop close the overlay too. Each overlay layer has its own backdrop, and when layers stack only the topmost one closes.
|
|
117
118
|
- **Closing is navigation**: closing first calls `beforeClose`, then navigates to `closeTo` with `replace`. Because it uses `replace`, pressing the browser's "Forward" after closing does not reopen the overlay.
|
|
118
119
|
- **Focus**: on open, focus moves into the overlay; when the focused element inside the overlay disappears (for example, a button is replaced by a skeleton after clicking "Retry"), focus returns to the overlay panel; after closing, focus returns to the element that had focus before opening (usually the link that opened it; for a row menu's "Edit", the menu's trigger). When a nested overlay closes, focus returns to the element in the parent layer that opened it, or to the parent layer's panel if that element is gone; when `/projects/12/edit` is opened directly, both layers mount at once, and after the dialog closes, focus is on the drawer panel.
|
|
@@ -371,7 +372,7 @@ The details below describe `sheet.tsx` as the registry writes it today; the file
|
|
|
371
372
|
|
|
372
373
|
## 6. Plain dialogs: sizes and scrolling
|
|
373
374
|
|
|
374
|
-
A `Dialog` from `#components/ui/dialog` defaults to `sm:max-w-
|
|
375
|
+
A `Dialog` from `#components/ui/dialog` defaults to `sm:max-w-lg` and grows with its content without limit. Give it the width guideline I1 assigns to what it holds, and when its content can outgrow the screen, cap its height with the one idiom `max-h-[calc(100dvh-2rem)]` and scroll only its body, so the header and the footer's buttons stay in view (guideline A4):
|
|
375
376
|
|
|
376
377
|
```tsx
|
|
377
378
|
// A small form: 1–4 fields, the width alone.
|
|
@@ -380,12 +381,12 @@ A `Dialog` from `#components/ui/dialog` defaults to `sm:max-w-sm` and grows with
|
|
|
380
381
|
// Content that can outgrow the screen: a fixed header and footer around a scrolling body.
|
|
381
382
|
<DialogContent className='flex max-h-[calc(100dvh-2rem)] flex-col sm:max-w-2xl'>
|
|
382
383
|
<DialogHeader>…</DialogHeader>
|
|
383
|
-
<div className='-mx-
|
|
384
|
+
<div className='-mx-6 min-h-0 flex-1 overflow-y-auto px-6'>…</div>
|
|
384
385
|
<DialogFooter>…</DialogFooter>
|
|
385
386
|
</DialogContent>
|
|
386
387
|
```
|
|
387
388
|
|
|
388
|
-
- `flex flex-col` replaces the content's grid, and `min-h-0 flex-1` lets the body shrink and scroll; `-mx-
|
|
389
|
+
- `flex flex-col` replaces the content's grid, and `min-h-0 flex-1` lets the body shrink and scroll; `-mx-6 … px-6` matches the content's `p-6` and runs its scrollbar along the dialog's edge. When the body is the form, put the classes on the `form` and keep the submit button in `DialogFooter` with `form='…'`.
|
|
389
390
|
- Do not cap the height any other way (`90vh`, `85dvh`, `calc(100svh-2rem)`, `min(40rem,…)`), and do not put `overflow-y-auto` on `DialogContent` itself: the footer would scroll away with the content.
|
|
390
391
|
- Large read-only content (a transcript, a diff, a file preview) uses the same structure at `sm:max-w-4xl`, usually with no footer.
|
|
391
392
|
- `RouteDialog` and `RouteDrawer` are built this way already; pass them only a width.
|
|
@@ -204,6 +204,12 @@ A page and the endpoints it calls must agree: the example's `/api/projects` is o
|
|
|
204
204
|
|
|
205
205
|
**The resource id is the permission identifier**: the permission set page lists every route whose `authz` checks `page` `access`, keyed by `authz.resource.id` (deduplicated), under the Pages entry with its navigation groups in menu order. Stored grants reference that id, so changing it requires migrating them; renaming the route alone does not.
|
|
206
206
|
|
|
207
|
+
### Permission display names
|
|
208
|
+
|
|
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
|
+
|
|
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.
|
|
212
|
+
|
|
207
213
|
## 5. Settings pages
|
|
208
214
|
|
|
209
215
|
There is one kind of client route, `defineAppRoutes()`. The application has no separate settings area and no `/settings` or `/dev` prefix, and plugins contribute no settings pages: a page that configures something is an ordinary App page in the main navigation. Put such pages under a navigation group of their own, such as a Settings group at the end of the sidebar, and add the icons to the `lucide-react` import at the top of the file (here `Settings` and `SlidersHorizontal`):
|