@nocobase/app-skills 0.1.0-beta.60 → 0.1.0-beta.61

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (20) hide show
  1. package/LICENSE.txt +129 -0
  2. package/package.json +1 -1
  3. package/skills/nocobase-app-development/SKILL.md +1 -1
  4. package/skills/nocobase-app-development/assets/date-picker-example/client/components/date-picker.tsx +152 -0
  5. package/skills/nocobase-app-development/assets/date-picker-example/client/lib/date-only.ts +13 -0
  6. package/skills/nocobase-app-development/assets/date-picker-example/tests/client/date-picker.test.tsx +185 -0
  7. package/skills/nocobase-app-development/references/dev-server.md +1 -1
  8. package/skills/nocobase-app-development/references/frontend/component-selection.md +2 -0
  9. package/skills/nocobase-app-development/references/frontend/references/form.md +17 -10
  10. package/skills/nocobase-app-development/references/frontend/references/shadcn.md +1 -1
  11. package/skills/nocobase-app-development/references/frontend/scripts/capture.md +1 -1
  12. package/skills/nocobase-app-development/references/frontend/scripts/capture.mjs +2 -2
  13. package/skills/nocobase-app-development/references/frontend/ui-guidelines.md +1 -1
  14. package/skills/nocobase-app-development/scripts/check-ui-components.mjs +75 -32
  15. package/skills/nocobase-app-plugin-development/SKILL.md +1 -0
  16. package/skills/nocobase-app-plugin-development/references/backends-configuration.md +56 -0
  17. package/skills/nocobase-app-plugin-development/references/configuration.md +2 -0
  18. package/skills/nocobase-app-plugin-development/references/server.md +1 -1
  19. package/skills/nocobase-app-upgrade/references/realtime-upgrade.md +69 -1
  20. package/skills/nocobase-deployment/SKILL.md +3 -1
package/LICENSE.txt ADDED
@@ -0,0 +1,129 @@
1
+ Updated Date: November 7, 2026
2
+
3
+ NocoBase License Agreement
4
+
5
+ NOCOBASE PTE. LTD., a Singaporean Exempt Private Company Limited by Shares with its principal place of business located at 112 ROBINSON ROAD, #03-01, SINGAPORE ("The Company") https://www.nocobase.com/ issues this License Agreement ("Agreement") to you. You, as an individual or a company ("The User"), will be deemed to voluntarily accept all terms of this Agreement by using NocoBase (including but not limited to obtaining NocoBase source code, installation package, or image in any form, installing and using NocoBase, developing Applications with NocoBase, purchasing NocoBase commercial license and services). If the User does not agree to any term of this Agreement, or cannot accurately understand our interpretation of the relevant terms, please stop using it immediately.
6
+
7
+ This Agreement applies to any use, quotation, contract, invoice, and all software delivered by the Company. The User and the Company or NocoBase's agents need not sign a separate license agreement for the sale and delivery of the software.
8
+
9
+ This Agreement applies to NocoBase 3 and later versions. NocoBase 2 and earlier versions are independent products and remain subject to their original license agreement. Where a NocoBase 2 Commercial Edition user uses NocoBase 3 or later versions under a policy announced by the Company, that use is subject to this Agreement.
10
+
11
+ The Company reserves the right to formulate and modify this Agreement from time to time as needed. If there are changes, the Company will announce them in the form of website announcements, without further individual notification. The changed Agreement will automatically take effect once it is announced, becoming part of this Agreement.
12
+
13
+ ==============
14
+ 1. Definitions
15
+ ==============
16
+
17
+ 1.1 "Software" refers to NocoBase, consisting of Core, Studio, and Commercial Plugins, including their source code, installation packages, images, and all their modifications, updates, and upgrades.
18
+
19
+ 1.2 "Core" refers to NocoBase Core, the open source application foundation released by the Company, including the runtime, plugins, application templates, development standards, and development skills placed in the same code repository.
20
+
21
+ 1.3 "Studio" refers to NocoBase Studio, the governance platform for people and agents building software together, provided in the Commercial Edition.
22
+
23
+ 1.4 "Commercial Plugins" refers to the plugins provided in the Commercial Edition that extend the capabilities of Core, such as advanced approvals and enterprise SSO.
24
+
25
+ 1.5 "Community Edition" refers to the free version of the Software provided to the User through public channels, namely Core.
26
+
27
+ 1.6 "Commercial Edition" refers to the paid version of the Software purchased by the User from the Company or its agents, downloaded through exclusive channels, and includes additional benefits. In addition to Core, it includes Studio and Commercial Plugins, and consists of two versions: Professional Edition and Enterprise Edition.
28
+
29
+ 1.7 "Application" refers to a specific business use case application serving internal or external customers of the User, developed based on the Software, such as ERP/CRM. Studio is a development tool and is not part of any Application.
30
+
31
+ 1.8 "Customer" refers to the clients who commission the User to develop Applications or purchase the User's Applications.
32
+
33
+ 1.9 "Agent" refers to an AI agent that works with the Software, including the coding agents the User uses to develop Applications and the business agents in Applications.
34
+
35
+ 1.10 "Third-Party Services" refers to the large models, coding agents, cloud services, and other third-party products and services that the User chooses to use with the Software.
36
+
37
+ 1.11 "Third-Party Open Source Software" refers to open source software provided with the Software. They are licensed through various published open source software licenses or copyright notices accompanying such software.
38
+
39
+ ===================================
40
+ 2. Intellectual Property Protection
41
+ ===================================
42
+
43
+ Except for Third-Party Open Source Software, the Company owns all copyrights, trademark rights, patent rights, trade secrets, and other intellectual property rights of the Software, and has registered and protected them in relevant countries and regions according to the "Paris Convention" or "TRIPS Agreement", ensuring that the intellectual property rights of the Software are internationally recognized and protected.
44
+
45
+ The Company claims no intellectual property rights in the business code written by the User or by Agents when developing Applications, or in the User's business data, skills, and knowledge bases. The parts of the Software contained in an Application remain the intellectual property of the Company and are subject to this Agreement.
46
+
47
+ =============
48
+ 3. Disclaimer
49
+ =============
50
+
51
+ 3.1 The User shall not use the Software to engage in activities that contravene applicable laws and regulations or offend against public order or religious prohibitions. All legal liabilities and consequences arising from the User's use shall be borne by the User.
52
+
53
+ 3.2 The Company shall not be liable for any direct, indirect, special, incidental, or consequential damages (including but not limited to loss of profits, business interruption, data loss, or business information disclosure) caused by the User's use of the Software, even if it has been previously informed of the possibility of such damages.
54
+
55
+ 3.3 Code written, content generated, and actions taken by Agents shall be reviewed and accepted by the User before being used in production. All consequences arising from the use of the work of Agents shall be borne by the User.
56
+
57
+ 3.4 Third-Party Services are chosen and paid for by the User and are subject to their own terms. The Company shall not be liable for the availability, output, or data handling of Third-Party Services.
58
+
59
+ ===============
60
+ 4. License Type
61
+ ===============
62
+
63
+ 4.1 This Agreement serves as the unified license agreement for NocoBase Software, applying to both the Community Edition and the Commercial Editions.
64
+
65
+ 4.2 Core is open source software. This Agreement incorporates and references the full text of the Apache License, Version 2.0 ("Apache-2.0", available at: https://www.apache.org/licenses/LICENSE-2.0 ). Users of Core must comply with the Apache-2.0 License as well as the supplementary terms set forth in this Agreement. In case of any inconsistency between Apache-2.0 and this Agreement, the supplementary terms of this Agreement shall prevail.
66
+
67
+ 4.3 Studio and Commercial Plugins are commercial software of the Company and are not licensed under Apache-2.0. They can only be used under the Commercial License and in accordance with this Agreement.
68
+
69
+ ================================================
70
+ 5. Rights and Obligations of Open Source License
71
+ ================================================
72
+
73
+ 5.1 The Community Edition can be used for commercial purposes, including developing Applications for Customers.
74
+
75
+ 5.2 It is not allowed to remove or change the NocoBase statement "AI + NocoBase" and "Build reliable business systems", or its link to https://www.nocobase.com/, at the bottom left of the interface of any Application, including Applications delivered to Customers, even though the code that displays the statement is part of the Application. If the default layout is replaced, the statement shall be kept at an equally visible position on the main interface of the Application. Pages that can be accessed without signing in and pages embedded in other systems are not subject to this requirement. When the sidebar is collapsed, showing the statement as an icon with a tooltip, as provided by default, meets this requirement. The main LOGO in the upper left corner of the page, the version number, and other information on the interface can be changed.
76
+
77
+ 5.3 It is not allowed to remove or change all intellectual property statements about NocoBase in the code.
78
+
79
+ 5.4 It is not allowed to provide to the public any form of AI application development platform or agent development platform SaaS/PaaS products using the original or modified Software.
80
+
81
+ ===============================
82
+ 6. Rights of Commercial License
83
+ ===============================
84
+
85
+ 6.1 Obtain a permanent commercial license of the Software.
86
+
87
+ 6.2 Can develop Applications for Customers, deploy the completed Applications, including the Commercial Plugins they use, on Customers' servers, or host them and provide them to Customers as a service. This does not include Studio.
88
+
89
+ 6.3 Customers can use the Commercial Plugins in the Applications delivered to them, within those Applications only, and can continue to develop those Applications on their own or through others.
90
+
91
+ 6.4 Get software upgrades and exclusive technical support during the upgrade validity period. Upgrades and technical support are provided to the User only, and the User can upgrade the Commercial Plugins in Applications delivered to Customers during this period.
92
+
93
+ 6.5 The licensed Software can be used for commercial purposes with no restrictions on the number of Applications, Customers, users, and Agents.
94
+
95
+ 6.6 Can remove or change the NocoBase statement described in 5.2, and the brand, name, link, and other information about NocoBase on the interface of Applications.
96
+
97
+ 6.7 If there are other agreements in the contract for the above rights, the contract agreement shall prevail.
98
+
99
+ ====================================
100
+ 7. Obligations of Commercial License
101
+ ====================================
102
+
103
+ 7.1 It is not allowed to remove or change all intellectual property statements about NocoBase in the code.
104
+
105
+ 7.2 It is not allowed to sell, transfer, lease, share, gift, or distribute the Commercial License. Deploying Applications for Customers under 6.2 is not considered sharing the Commercial License, but the license key, access token, or other credentials of the Commercial License shall not be provided to Customers for any purpose other than deploying and running the Applications delivered to them.
106
+
107
+ 7.3 It is not allowed to sell, transfer, lease, share, or distribute any form of AI application development platform, agent development platform, or developer tools developed based on Software.
108
+
109
+ 7.4 It is not allowed to provide any form of AI application development platform or agent development platform SaaS/PaaS products to the public using the original or modified Software.
110
+
111
+ 7.5 Studio can only be used by the User holding the Commercial License, on servers owned or rented by the User. It is not allowed to deploy Studio for Customers, or to provide Studio to Customers or any third party in any form, including as a hosted service. Customers that need Studio shall purchase their own Commercial License.
112
+
113
+ 7.6 Customer personnel can take part in requirement confirmation, acceptance, and release approval in the User's Studio for the Applications the User develops for them. This is not considered providing Studio to Customers, but it is not allowed to let Customers use Studio to develop their own projects.
114
+
115
+ 7.7 If there is a violation of the above obligations or the terms of this Agreement, the rights owned by the User will be immediately terminated, the paid fees will not be refunded, and the Company reserves the right to pursue the User's legal responsibility.
116
+
117
+ 7.8 If there are other agreements in the contract for the above obligations, the contract agreement shall prevail.
118
+
119
+ =============================================================
120
+ 8. Legal Jurisdiction, Interpretation, and Dispute Resolution
121
+ =============================================================
122
+
123
+ 8.1 Except for Mainland China, the interpretation, application, and all matters related to this agreement are subject to the jurisdiction of Singapore law.
124
+
125
+ 8.2 Any dispute related to this Agreement should first be resolved through friendly negotiation. If the negotiation fails to resolve the dispute, the dispute should be submitted to the International Chamber of Commerce (ICC) for arbitration. The arbitration venue should be Singapore, conducted in English.
126
+
127
+ 8.3 All terms and conditions of this Agreement shall be deemed enforceable to the maximum extent permitted by applicable law. If any term of this Agreement is deemed invalid by any applicable law, the invalidity of that term does not affect the validity of any other term of this Agreement, and it should be deemed that the invalid term has been modified as much as possible to make it valid and enforceable, or if the term cannot be modified, it should be deemed to have been deleted from this Agreement.
128
+
129
+ 8.4 The arbitration award is final, binding on both parties, and can be enforced in any court with jurisdiction.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nocobase/app-skills",
3
- "version": "0.1.0-beta.60",
3
+ "version": "0.1.0-beta.61",
4
4
  "description": "Agent Skills for developing applications and plugins, upgrading and deploying NocoBase applications.",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -125,7 +125,7 @@ For initialization prerequisites introduced by the feature, apply [setup readine
125
125
 
126
126
  ## Frontend work
127
127
 
128
- Before implementing interactions, follow [component selection and source review](references/frontend/component-selection.md): existing business component → installed shadcn primitive → registry addition → justified custom composition/primitive. Record the actual component source and run the targeted component checker before delivery; a matching screenshot alone does not justify duplicating a primitive.
128
+ Before implementing interactions, follow [component selection and source review](references/frontend/component-selection.md): existing business component → installed shadcn primitive → registry addition → justified custom composition/primitive. Record the actual component source and run the targeted component checker before delivery; a matching screenshot alone does not justify duplicating a primitive. A date field follows [Dates](references/frontend/references/form.md#dates): read the matching official shadcn Date Picker example, reuse or compose `client/components/date-picker.tsx` once, reuse it on every page, then run the checker and the field's behavior tests; a native or shadcn `Input` date input is never a date picker.
129
129
 
130
130
  Application and plugin UI share [the UI design contract](references/frontend/design-contract.md). Read the application's existing design records and original UI references first: record whether a reference controls appearance, structure or style, apply authorized page exceptions, and retain reusable decisions outside synchronized Skills. Use the contract's system-design section when planning a business system across modules; do not redesign the system for a small edit. Plugin implementation still belongs to `nocobase-app-plugin-development`, whose UI entry points to these same design and acceptance rules.
131
131
 
@@ -0,0 +1,152 @@
1
+ import { useLocale, useTranslation } from '@nocobase/i18n/client';
2
+ import { format, type Locale } from 'date-fns';
3
+ import { enUS, zhCN } from 'date-fns/locale';
4
+ import { CalendarIcon } from 'lucide-react';
5
+ import {
6
+ useEffect,
7
+ useRef,
8
+ useState,
9
+ type ComponentProps,
10
+ type ComponentType,
11
+ type ReactElement,
12
+ type Ref,
13
+ } from 'react';
14
+ import { cn } from 'cn';
15
+
16
+ import { Button } from '#components/ui/button';
17
+ import { Calendar, CalendarDayButton } from '#components/ui/calendar';
18
+ import {
19
+ Popover,
20
+ PopoverContent,
21
+ PopoverTrigger,
22
+ } from '#components/ui/popover';
23
+
24
+ export interface DatePickerProps {
25
+ /** Ties the trigger to its label: `<label htmlFor={id}>`. */
26
+ readonly id?: string;
27
+ readonly value: Date | undefined;
28
+ readonly onChange: (date: Date | undefined) => void;
29
+ readonly disabled?: boolean;
30
+ /** Shows a Clear action in the calendar while a date is selected. */
31
+ readonly clearable?: boolean;
32
+ readonly placeholder?: string;
33
+ /** A `date-fns` locale for the trigger and the calendar; defaults to the interface language. */
34
+ readonly locale?: Locale;
35
+ readonly className?: string;
36
+ }
37
+
38
+ /** One `date-fns` locale per interface language the application offers; add a line when you add a language. */
39
+ function interfaceDateLocale(language: string): Locale {
40
+ return language.startsWith('zh') ? zhCN : enUS;
41
+ }
42
+
43
+ /**
44
+ * The registry's `CalendarDayButton` keeps a focus ref it never attaches, so arrow keys would move the calendar's
45
+ * highlighted day while the browser focus stays behind. Attach one here instead of editing the generated primitive.
46
+ */
47
+ type DayButtonProps = ComponentProps<typeof CalendarDayButton>;
48
+ // Its remaining props, `ref` included (a plain prop in React 19), reach the underlying Button.
49
+ const CalendarDayButtonWithRef = CalendarDayButton as ComponentType<
50
+ DayButtonProps & { readonly ref: Ref<HTMLButtonElement> }
51
+ >;
52
+
53
+ function FocusedDayButton(props: DayButtonProps): ReactElement {
54
+ const ref = useRef<HTMLButtonElement>(null);
55
+ useEffect(() => {
56
+ if (props.modifiers.focused) ref.current?.focus();
57
+ }, [props.modifiers.focused]);
58
+ return <CalendarDayButtonWithRef {...props} ref={ref} />;
59
+ }
60
+
61
+ /**
62
+ * The application's single-date picker: shadcn's Date Picker composition of a `Popover` opened by an outline
63
+ * `Button`, holding a `Calendar` in single mode (https://ui.shadcn.com/docs/components/base/date-picker).
64
+ * Business pages reuse it instead of composing the primitives again or using a native date input.
65
+ */
66
+ export function DatePicker({
67
+ id,
68
+ value,
69
+ onChange,
70
+ disabled = false,
71
+ clearable = false,
72
+ placeholder,
73
+ locale,
74
+ className,
75
+ }: DatePickerProps): ReactElement {
76
+ const { t } = useTranslation();
77
+ const { locale: language } = useLocale();
78
+ const dateLocale = locale ?? interfaceDateLocale(language);
79
+ const [open, setOpen] = useState(false);
80
+ const calendarRef = useRef<HTMLDivElement>(null);
81
+ // A field that becomes disabled or locked while its calendar is open closes it, and stays closed once re-enabled.
82
+ if (disabled && open) setOpen(false);
83
+ const select = (date: Date | undefined): void => {
84
+ if (disabled) return;
85
+ onChange(date);
86
+ setOpen(false);
87
+ };
88
+ return (
89
+ <Popover
90
+ open={open && !disabled}
91
+ onOpenChange={(next) => setOpen(next && !disabled)}
92
+ >
93
+ <PopoverTrigger
94
+ render={
95
+ <Button
96
+ id={id}
97
+ type='button'
98
+ variant='outline'
99
+ disabled={disabled}
100
+ data-empty={!value}
101
+ className={cn(
102
+ 'w-full justify-start px-2.5 text-left font-normal data-[empty=true]:text-muted-foreground',
103
+ className,
104
+ )}
105
+ />
106
+ }
107
+ >
108
+ <CalendarIcon aria-hidden='true' data-icon='inline-start' />
109
+ {value ? (
110
+ format(value, 'PPP', { locale: dateLocale })
111
+ ) : (
112
+ <span>{placeholder ?? t('datePicker.placeholder')}</span>
113
+ )}
114
+ </PopoverTrigger>
115
+ <PopoverContent
116
+ className='w-auto p-0'
117
+ align='start'
118
+ // Start on the selected day (or today), the calendar's one tabbable day, so arrow keys move between days.
119
+ initialFocus={() =>
120
+ calendarRef.current?.querySelector<HTMLElement>(
121
+ '[role=grid] button[tabindex="0"]',
122
+ ) ?? true
123
+ }
124
+ >
125
+ <div ref={calendarRef}>
126
+ <Calendar
127
+ mode='single'
128
+ autoFocus
129
+ locale={dateLocale}
130
+ components={{ DayButton: FocusedDayButton }}
131
+ selected={value}
132
+ defaultMonth={value}
133
+ onSelect={select}
134
+ />
135
+ </div>
136
+ {clearable && value ? (
137
+ <div className='border-t p-2'>
138
+ <Button
139
+ type='button'
140
+ variant='ghost'
141
+ size='sm'
142
+ className='w-full'
143
+ onClick={() => select(undefined)}
144
+ >
145
+ {t('datePicker.clear')}
146
+ </Button>
147
+ </div>
148
+ ) : null}
149
+ </PopoverContent>
150
+ </Popover>
151
+ );
152
+ }
@@ -0,0 +1,13 @@
1
+ import { format, isValid, parseISO } from 'date-fns';
2
+
3
+ /** Reads a calendar date sent as `'yyyy-MM-dd'` as local midnight, so no time zone moves it to another day. */
4
+ export function parseDateOnly(value: string | undefined): Date | undefined {
5
+ if (!value) return undefined;
6
+ const date = parseISO(value);
7
+ return isValid(date) ? date : undefined;
8
+ }
9
+
10
+ /** Writes a picked calendar date as `'yyyy-MM-dd'` in local time; `toISOString()` would shift it east of UTC. */
11
+ export function formatDateOnly(date: Date | undefined): string {
12
+ return date ? format(date, 'yyyy-MM-dd') : '';
13
+ }
@@ -0,0 +1,185 @@
1
+ import {
2
+ TestI18nProvider,
3
+ createTestI18nRuntime,
4
+ } from '@nocobase/i18n/testing';
5
+ import { render, screen, waitFor } from '@testing-library/react';
6
+ import userEvent from '@testing-library/user-event';
7
+ import { useState, type ReactElement } from 'react';
8
+ import { afterEach, describe, expect, it, vi } from 'vitest';
9
+
10
+ import { DatePicker } from '#components/date-picker';
11
+ import { formatDateOnly, parseDateOnly } from '#lib/date-only';
12
+
13
+ import enUS from '../../client/locales/en-US.js';
14
+ import zhCN from '../../client/locales/zh-CN.js';
15
+
16
+ async function view(
17
+ ui: ReactElement,
18
+ locale: 'en-US' | 'zh-CN' = 'en-US',
19
+ ): Promise<(next: ReactElement) => void> {
20
+ const runtime = await createTestI18nRuntime({
21
+ locale,
22
+ application: {
23
+ namespace: '@nocobase/app-template-examples',
24
+ resources: locale === 'en-US' ? enUS : zhCN,
25
+ },
26
+ });
27
+ const { rerender } = render(
28
+ <TestI18nProvider runtime={runtime}>{ui}</TestI18nProvider>,
29
+ );
30
+ return (next) =>
31
+ rerender(<TestI18nProvider runtime={runtime}>{next}</TestI18nProvider>);
32
+ }
33
+
34
+ /** A form field the way a business page wires it: a label, and a `'yyyy-MM-dd'` value at the boundary. */
35
+ function HolidayField({
36
+ initial = '',
37
+ disabled = false,
38
+ onChange = () => {},
39
+ }: {
40
+ readonly initial?: string;
41
+ readonly disabled?: boolean;
42
+ readonly onChange?: (value: string) => void;
43
+ }): ReactElement {
44
+ const [value, setValue] = useState(initial);
45
+ return (
46
+ <>
47
+ <label htmlFor='holiday'>Holiday</label>
48
+ <DatePicker
49
+ id='holiday'
50
+ clearable
51
+ disabled={disabled}
52
+ value={parseDateOnly(value)}
53
+ onChange={(date) => {
54
+ setValue(formatDateOnly(date));
55
+ onChange(formatDateOnly(date));
56
+ }}
57
+ />
58
+ </>
59
+ );
60
+ }
61
+
62
+ describe('DatePicker', () => {
63
+ it('shows a loaded date, picks another from the calendar and returns focus to its labelled trigger', async () => {
64
+ const changes = vi.fn();
65
+ await view(<HolidayField initial='2026-01-01' onChange={changes} />);
66
+ const trigger = screen.getByRole('button', { name: /Holiday/ });
67
+ expect(trigger).toBe(screen.getByLabelText('Holiday'));
68
+ expect(trigger).toHaveTextContent('January 1st, 2026');
69
+
70
+ await userEvent.click(trigger);
71
+ const day = await screen.findByRole('button', {
72
+ name: /Friday, January 2nd, 2026/,
73
+ });
74
+ await userEvent.click(day);
75
+
76
+ expect(changes).toHaveBeenLastCalledWith('2026-01-02');
77
+ await waitFor(() => expect(screen.queryByRole('grid')).toBeNull());
78
+ expect(trigger).toHaveTextContent('January 2nd, 2026');
79
+ await waitFor(() => expect(trigger).toHaveFocus());
80
+ });
81
+
82
+ it('is operable from the keyboard', async () => {
83
+ const changes = vi.fn();
84
+ await view(<HolidayField initial='2026-01-01' onChange={changes} />);
85
+ screen.getByRole('button', { name: /Holiday/ }).focus();
86
+ await userEvent.keyboard('{Enter}');
87
+ // The calendar focuses the selected day; the arrow keys move between days.
88
+ await waitFor(() =>
89
+ expect(
90
+ screen.getByRole('button', { name: /January 1st, 2026/ }),
91
+ ).toHaveFocus(),
92
+ );
93
+ await userEvent.keyboard('{ArrowRight}');
94
+ expect(
95
+ screen.getByRole('button', { name: /January 2nd, 2026/ }),
96
+ ).toHaveFocus();
97
+ await userEvent.keyboard('{Enter}');
98
+ expect(changes).toHaveBeenLastCalledWith('2026-01-02');
99
+ });
100
+
101
+ it('clears the date and shows the placeholder', async () => {
102
+ const changes = vi.fn();
103
+ await view(<HolidayField initial='2026-01-01' onChange={changes} />);
104
+ await userEvent.click(screen.getByRole('button', { name: /Holiday/ }));
105
+ await userEvent.click(await screen.findByRole('button', { name: 'Clear' }));
106
+ expect(changes).toHaveBeenLastCalledWith('');
107
+ expect(screen.getByLabelText('Holiday')).toHaveTextContent('Pick a date');
108
+ // Nothing is left to clear.
109
+ await userEvent.click(screen.getByRole('button', { name: /Holiday/ }));
110
+ await screen.findByRole('grid');
111
+ expect(screen.queryByRole('button', { name: 'Clear' })).toBeNull();
112
+ });
113
+
114
+ it('does not open while disabled', async () => {
115
+ await view(<HolidayField initial='2026-01-01' disabled />);
116
+ const trigger = screen.getByLabelText('Holiday');
117
+ expect(trigger).toBeDisabled();
118
+ await userEvent.click(trigger);
119
+ expect(screen.queryByRole('grid')).toBeNull();
120
+ });
121
+
122
+ it('closes and ignores the calendar when it becomes disabled while open', async () => {
123
+ const changes = vi.fn();
124
+ const rerender = await view(
125
+ <HolidayField initial='2026-01-01' onChange={changes} />,
126
+ );
127
+ await userEvent.click(screen.getByRole('button', { name: /Holiday/ }));
128
+ const day = await screen.findByRole('button', {
129
+ name: /January 2nd, 2026/,
130
+ });
131
+ const clear = screen.getByRole('button', { name: 'Clear' });
132
+
133
+ rerender(<HolidayField initial='2026-01-01' onChange={changes} disabled />);
134
+ expect(screen.getByLabelText('Holiday')).toBeDisabled();
135
+ // Whatever is still on screen while the popover closes, neither picking a day nor clearing changes the value.
136
+ for (const control of [day, clear]) {
137
+ if (control.isConnected) control.click();
138
+ }
139
+ await waitFor(() => expect(screen.queryByRole('grid')).toBeNull());
140
+ expect(changes).not.toHaveBeenCalled();
141
+ expect(screen.getByLabelText('Holiday')).toHaveTextContent(
142
+ 'January 1st, 2026',
143
+ );
144
+
145
+ // Enabling the field again does not reopen the calendar on its own.
146
+ rerender(<HolidayField initial='2026-01-01' onChange={changes} />);
147
+ expect(screen.queryByRole('grid')).toBeNull();
148
+ });
149
+
150
+ it('formats the trigger and the calendar in the interface language', async () => {
151
+ await view(<HolidayField initial='2026-01-01' />, 'zh-CN');
152
+ const trigger = screen.getByLabelText('Holiday');
153
+ expect(trigger).toHaveTextContent('2026年1月1日');
154
+ await userEvent.click(trigger);
155
+ expect(await screen.findByRole('grid')).toHaveAccessibleName(
156
+ /2026年1月|一月 2026/,
157
+ );
158
+ await userEvent.click(screen.getByRole('button', { name: '清除' }));
159
+ expect(trigger).toHaveTextContent(zhCN.datePicker.placeholder);
160
+ });
161
+ });
162
+
163
+ describe('calendar date values', () => {
164
+ const zone = process.env.TZ;
165
+ afterEach(() => {
166
+ process.env.TZ = zone;
167
+ });
168
+
169
+ it.each(['America/Los_Angeles', 'Asia/Shanghai', 'Pacific/Kiritimati'])(
170
+ 'keep the same day in %s',
171
+ (timeZone) => {
172
+ process.env.TZ = timeZone;
173
+ const date = parseDateOnly('2026-01-02');
174
+ expect(date?.getDate()).toBe(2);
175
+ expect(formatDateOnly(date)).toBe('2026-01-02');
176
+ expect(formatDateOnly(new Date(2026, 11, 31))).toBe('2026-12-31');
177
+ },
178
+ );
179
+
180
+ it('reads an empty or invalid value as no date', () => {
181
+ expect(parseDateOnly('')).toBeUndefined();
182
+ expect(parseDateOnly('2026-02-30')).toBeUndefined();
183
+ expect(formatDateOnly(undefined)).toBe('');
184
+ });
185
+ });
@@ -28,7 +28,7 @@ Tests that start auxiliary Vite servers must use an isolated temporary `cacheDir
28
28
 
29
29
  ## File watching
30
30
 
31
- `pnpm dev` checks native file watching before starting its children. If watcher resources are exhausted or native events are unavailable, it uses polling for client and server hot updates and disables agent annotations for that run, with a warning. An explicit `CHOKIDAR_USEPOLLING=true` selects the same mode. Configuration files use stat polling so atomic saves and newly created files restart the server without native directory watchers.
31
+ `pnpm dev` checks native file watching before starting its children. If watcher resources are exhausted or native events are unavailable, it uses polling for client and server hot updates and disables annotations in older applications that still integrate them, with a warning. Current Default and Examples templates do not integrate annotations. An explicit `CHOKIDAR_USEPOLLING=true` selects the same mode. Configuration files use stat polling so atomic saves and newly created files restart the server without native directory watchers.
32
32
 
33
33
  Vite must exclude the application's entire `dist/` tree from development file watching. Its default exclusion covers only `dist/client`; watching the compiled server and vendored packages can cause `EMFILE` after a build. Keep the exclusion scoped to this application so linked workspace dependencies, including their `dist/` files, still receive hot updates.
34
34
 
@@ -29,6 +29,8 @@ Without file arguments it scans that package's `client/`. In a NocoBase source c
29
29
 
30
30
  The checker finds native buttons, visible inputs, selects, textareas, dialogs, summaries, literal widget roles, and selected clickable non-interactive elements. It skips the standard package-local `client/components/ui/` primitive implementation, test/story/fixture files, generated/vendor/output directories and symlinks. It permits hidden inputs, ordinary semantic layout and a native element passed directly to `render` on an imported local shadcn primitive. Compositions outside the primitive directory are still scanned; merely importing `Button` does not exempt other raw buttons in that file.
31
31
 
32
+ It also reports a native date interaction: an `<input>` or an imported local shadcn `Input`/`InputGroupInput` (including an alias such as `Input as TextInput` and a namespace such as `UI.Input`) whose `type` is the string `date` or `datetime-local`, written as an attribute string or a string expression, even when passed to a primitive's `render`. Its advice is the application's `DatePicker` ([Dates in `form.md`](references/form.md#dates)); for `datetime-local` it keeps the time with an `Input type='time'` beside it. A `Calendar` in a `Popover`, the official input-style variant, `Input type='time'`, `month` and `week` are not reported, and neither is a component merely named `DatePicker`: review its source for the `Calendar` composition. A `type` computed at runtime (`type={kind}`), passed by spread, or set inside another wrapper is outside the static check and left to the source review.
33
+
32
34
  For a necessary native adapter, place a specific `ui-component-exception:` comment on the line immediately before **one** flagged opening element. Explain the unmet behavior and refer to a durable decision when needed. For example, after confirming that the installed component cannot expose the required browser capability:
33
35
 
34
36
  ```tsx
@@ -207,12 +207,24 @@ Labels go above inputs (guideline T3.2): ordinary fields use the default `vertic
207
207
  ### Other controls
208
208
 
209
209
  - The registry also has `NativeSelect`, `Slider`, `InputOTP`, `ToggleGroup` and more (for `Combobox`, see "Choosing a related record"); the skill's forms rules say when each fits, for example `ToggleGroup` for two to seven options. Before wiring a component into `Controller`, confirm the controlled prop and the callback arguments with `pnpm exec shadcn docs <name>` and the source the CLI wrote: Base UI components often use different prop names from the Radix versions.
210
- - For dates, use the application's own `DatePicker` from `#components/date-picker`. If it does not exist yet, compose it there from the `calendar` and `popover` primitives as shadcn's Date Picker guide does (`pnpm exec shadcn docs date-picker`), with `date-fns` for formatting, rather than inline in a page. Give it `value: Date | undefined`, `onChange(date)`, `id` for the label and a `date-fns` `locale`; it accepts neither `ref` nor `aria-invalid`, so `FieldError` below it carries the error. It formats the trigger and the calendar in English unless it gets a `date-fns` locale, so map the interface language to one:
210
+ - For dates, follow [Dates](#dates) below: the application's own `DatePicker` from `#components/date-picker`, never a native date input.
211
+
212
+ - When a component you need is not in `client/components/ui/`, add it as [section 1 of `shadcn.md`](shadcn.md#1-what-the-template-ships-and-how-to-add-the-rest) describes; do not write it by hand.
213
+
214
+ ### Dates
215
+
216
+ A date field is the application's own `DatePicker`. shadcn has no `DatePicker` component to install: its [Date Picker](https://ui.shadcn.com/docs/components/base/date-picker) is a `Popover` opened by a `Button` and holding a `Calendar`, and the application composes that once. A native `<input type='date'>` and the shadcn `<Input type='date'>` both open the browser's own calendar, so neither is a date picker; `check-ui-components.mjs` reports both. Every date field goes through these four steps:
217
+
218
+ 1. **Read the matching official example first.** Look for `client/components/date-picker.tsx` and read it if it exists. Then read the installed `calendar`, `popover` and `button` sources and run `pnpm exec shadcn docs calendar popover button`, which prints each component's documentation and API for the project's base (`style` in `components.json`: `base-*` is Base UI, otherwise Radix). Read the Date Picker page for the same base — [Base UI](https://ui.shadcn.com/docs/components/base/date-picker) or [Radix](https://ui.shadcn.com/docs/components/radix/date-picker); `pnpm exec shadcn docs date-picker` reports "not found" because it is a composition, not a registry component. Base UI opens the popover with `<PopoverTrigger render={<Button … />}>`; Radix uses `<PopoverTrigger asChild>`. Do not mix the two, and do not write from memory.
219
+ 2. **Reuse or compose it once.** If `client/components/date-picker.tsx` exists, review that it really composes `Calendar` in a `Popover` (a component named `DatePicker` is not evidence) and reuse it. Otherwise add only the missing primitives (`yes n | pnpm exec shadcn add calendar popover button`) and compose it there from the official example, adapting only import paths, the interface language, the controlled value and what the business needs, such as clearing. The [tested composition from the Examples application](../../../assets/date-picker-example/client/components/date-picker.tsx) is the reference: copy it into `client/components/date-picker.tsx` and check its imports against the installed primitives. Never hand-write a calendar grid or popover positioning, never import another package's private date picker (a plugin's `client/components/date-picker.tsx` is not public), and never fall back to a native date input.
220
+ 3. **Reuse it on every page.** A page renders `<DatePicker id value onChange />` and converts at its boundary; it never composes `Calendar` and `Popover` again. In the Examples application, the holiday dates of the office workflow parameters (`client/pages/workflows/office-parameters.tsx`) are the reference field.
221
+ 4. **Check and verify.** Run the [component checker](../component-selection.md#run-the-targeted-check) on the changed files and test the field's behavior as the [reference tests](../../../assets/date-picker-example/tests/client/date-picker.test.tsx) do: picking, showing a loaded value, clearing, disabled, both interface languages, keyboard and focus return, and the submitted value in a time zone west and east of UTC. In the delivery report, record the official page used, the date picker's source location and the pages that call it.
222
+
223
+ The reference `DatePicker` takes `value: Date | undefined`, `onChange(date)`, `id` for the label, `disabled`, `clearable` (a Clear action under the calendar) and an optional `date-fns` `locale`, which defaults to the interface language for both the trigger text and the calendar; extend its language mapping when you add a language. It accepts neither `ref` nor `aria-invalid`, so `FieldError` below it carries the error. The registry's `CalendarDayButton` does not attach its focus ref, so the composition passes a day button that does; without it, the arrow keys move the highlighted day while focus stays behind. A wrapper that fixes a field's placeholder or locale stays thin:
211
224
 
212
225
  ```tsx
213
226
  // client/pages/projects/project-due-date-picker.tsx
214
- import { useLocale, useTranslation } from '@nocobase/i18n/client';
215
- import { enUS, zhCN } from 'date-fns/locale';
227
+ import { useTranslation } from '@nocobase/i18n/client';
216
228
  import type { ReactElement } from 'react';
217
229
 
218
230
  import { DatePicker } from '#components/date-picker';
@@ -229,16 +241,11 @@ export function ProjectDueDatePicker({
229
241
  onChange,
230
242
  }: ProjectDueDatePickerProps): ReactElement {
231
243
  const { t } = useTranslation();
232
- const { locale } = useLocale();
233
- // One date-fns locale per language the application offers; add a line when you add a language.
234
- const dateLocale = locale.startsWith('zh') ? zhCN : enUS;
235
244
  return (
236
245
  <DatePicker
237
246
  id={id}
238
- className='w-full'
239
247
  value={value}
240
248
  onChange={onChange}
241
- locale={dateLocale}
242
249
  placeholder={t('projects.form.dueDatePlaceholder')}
243
250
  />
244
251
  );
@@ -249,10 +256,10 @@ In the form, render it inside `Controller` with `value={field.value}` and `onCha
249
256
 
250
257
  How a date travels to and from the endpoint depends on what it is:
251
258
 
252
- - **A calendar date** (a due date, a birthday) travels as `'yyyy-MM-dd'`. Submit `format(date, 'yyyy-MM-dd')` and turn a loaded value into the default with `parseISO(value)`, both from `date-fns`: `parseISO` reads a date-only string as local midnight. `new Date('2026-01-02')` reads it as UTC midnight, which shows as January 1 west of UTC, and `toISOString()` turns local midnight into the previous day east of UTC.
259
+ - **A calendar date** (a due date, a birthday) travels as `'yyyy-MM-dd'`. Submit `format(date, 'yyyy-MM-dd')` and turn a loaded value into the default with `parseISO(value)`, both from `date-fns` (the reference's [`client/lib/date-only.ts`](../../../assets/date-picker-example/client/lib/date-only.ts) wraps them as `formatDateOnly` and `parseDateOnly`, which also read an empty or invalid value as no date): `parseISO` reads a date-only string as local midnight. `new Date('2026-01-02')` reads it as UTC midnight, which shows as January 1 west of UTC, and `toISOString()` turns local midnight into the previous day east of UTC.
253
260
  - **A point in time** (`updatedAt`, a meeting start) travels as an ISO 8601 string with its offset: send `date.toISOString()`, parse with `new Date(value)`, and display with `Intl.DateTimeFormat` in the current locale ("Dates and numbers" in [`i18n.md`](i18n.md#dates-and-numbers)).
254
261
 
255
- - When a component you need is not in `client/components/ui/`, add it as [section 1 of `shadcn.md`](shadcn.md#1-what-the-template-ships-and-how-to-add-the-rest) describes; do not write it by hand.
262
+ A date and time (a meeting start) keeps its time: put the `DatePicker` beside a shadcn `<Input type='time'>`, as the Date Picker page's Time Picker example does, and combine both into one value in the field's component. Do not replace it with a date-only picker, and keep a genuine time input (`<Input type='time'>`); a month or week has no single-day picker to replace it with.
256
263
 
257
264
  ## Validation timing, array fields, dependent fields and resetting
258
265
 
@@ -13,7 +13,7 @@ The Default template ships these; Examples adds `badge`, `card`, `field`, `selec
13
13
  | `button`, `dropdown-menu`, `input`, `label`, `popover`, `spinner`, `toast`, `tooltip` | The shell, the sign-in pages and the Appearance popover |
14
14
  | `dialog` | `RouteDialog` and `RouteDrawer` |
15
15
 
16
- A date field is the application's own `DatePicker`, composed from the `calendar` and `popover` primitives as shadcn's Date Picker guide does ([`form.md`](form.md)); add `calendar` in the same run as the primitives a page needs, such as `yes n | pnpm exec shadcn add card calendar`. A table is the application's own `DataTable`, built from the `table` primitive ([`table.md`](table.md#1-choosing-a-table-component)).
16
+ A date field is the application's own `DatePicker` in `client/components/date-picker.tsx`, composed once from the `calendar`, `popover` and `button` primitives as shadcn's Date Picker page does; follow the four steps in [Dates in `form.md`](form.md#dates), which start from the official example and a tested reference composition. Add `calendar` in the same run as the primitives a page needs, such as `yes n | pnpm exec shadcn add card calendar`. A table is the application's own `DataTable`, built from the `table` primitive ([`table.md`](table.md#1-choosing-a-table-component)).
17
17
 
18
18
  A file that imports any other primitive — `field`, `card`, `alert`, `badge`, `skeleton`, `empty`, `alert-dialog`, `sheet`, `checkbox` and so on — compiles only after it is added. Check `client/components/ui/` first (or the `components` list of `pnpm exec shadcn info --json`), add everything missing in one run, then format what the run created:
19
19
 
@@ -77,7 +77,7 @@ The sign-in session is saved to `storage/ui-workflow/auth.json` (`storage/` is i
77
77
  }
78
78
  ```
79
79
 
80
- At the top level, the configuration can set `base`, `out`, `locale`, `viewport`, `colorScheme`, `theme` and `hide` (elements hidden in screenshots; by default the development toolbar `#agent-annotations-root` is hidden). Each shot can set:
80
+ At the top level, the configuration can set `base`, `out`, `locale`, `viewport`, `colorScheme`, `theme` and `hide` (selectors explicitly hidden in screenshots; empty by default). Each shot can set:
81
81
 
82
82
  | Field | Description |
83
83
  | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -8,7 +8,7 @@
8
8
  // node .agents/skills/nocobase-app-development/references/frontend/scripts/capture.mjs shoot --spec storage/ui-workflow/<feature>/capture.json [--only list,dark]
9
9
  //
10
10
  // Top-level configuration fields: base, out, locale, viewport, colorScheme, theme, hide (elements hidden in screenshots;
11
- // the development toolbar by default), shots. Each shot: name, path, setup (steps run before the page opens), steps,
11
+ // none by default), shots. Each shot: name, path, setup (steps run before the page opens), steps,
12
12
  // waitUntil, viewport, colorScheme, theme, locale, fullPage, settle (milliseconds to wait before the screenshot),
13
13
  // screenshot (false skips the final screenshot). colorScheme and theme are saved as the application's own appearance
14
14
  // choices, so they win over client.app.defaultColorScheme and client.app.defaultTheme in config.yml.
@@ -223,7 +223,7 @@ async function shoot(options) {
223
223
  colorScheme: toContextColorScheme(shot.colorScheme ?? spec.colorScheme),
224
224
  deviceScaleFactor: shot.deviceScaleFactor ?? spec.deviceScaleFactor ?? 1,
225
225
  });
226
- const hide = spec.hide ?? ['#agent-annotations-root'];
226
+ const hide = spec.hide ?? [];
227
227
  if (hide.length > 0) {
228
228
  await context.addInitScript((selectors) => {
229
229
  const apply = () => {
@@ -150,7 +150,7 @@ Do not show raw backend error messages (untranslated exception messages, stack t
150
150
 
151
151
  **I9 [Must] Records and overlays open where the user is**: the view the user is on is the deepest thing they are looking at — a list with its search and filters, a dashboard, a board, a drawer, or the tab being shown on a page with tabs. A record opened from a view (a list, a dashboard, a board or another record's tab), and any overlay opened from a view, open over that view — a drawer or dialog for a short detail view or form, a covering child page (`RouteChildPage`) when the detail needs a page of its own (T2.1) — at the view's URL followed by the overlay's own segments, so the view stays rendered behind it, and closing or going back returns to exactly that URL, with no redirect in between. To check, remove the overlay's own segments from its URL: what remains is the URL the user opened it from. Declare the detail, with its edit, tab and print children, under every view that opens it, reusing the same modules; on a page with tabs, the overlays its header opens are declared under every tab, since the header sits above all of them. Never send the user to another page's route for a record, whether its overlay URL or its detail page: the page they were on disappears, the menu highlight moves to another entry, and closing lands them on a page they did not come from. Never open an overlay beside a page's tabs either: the tab unmounts behind it, and closing lands on the default tab.
152
152
 
153
- **I10 [Must] Dates are picked from a calendar**: never a native `<input type='date'>`. A date is the shadcn `Calendar` in a `Popover`, opened by an outline `Button` that shows the value in the current language's format ([the date picker in `references/form.md`](references/form.md#other-controls)). A range is one such trigger opening `Calendar mode='range'`, two months side by side on wide screens, with quick presets beside it (last 7 days, last 30 days, this month, last month, last 90 days), and keeps its two ends in the URL like other filters (T1.7).
153
+ **I10 [Must] Dates are picked from a calendar**: never a native `<input type='date'>` or a shadcn `<Input type='date'>`, which opens the same browser calendar. A date is the application's `DatePicker`: the shadcn `Calendar` in a `Popover`, opened by an outline `Button` that shows the value in the current language's format, composed once and reused by every page ([Dates in `references/form.md`](references/form.md#dates)). A date and time keeps its time input beside it. A range is one such trigger opening `Calendar mode='range'`, two months side by side on wide screens, with quick presets beside it (last 7 days, last 30 days, this month, last month, last 90 days), and keeps its two ends in the URL like other filters (T1.7).
154
154
 
155
155
  **I11 [Must] Drawers are wide enough for their content**: a drawer holding a form or a record's details is medium width (`RouteDrawer` already is); a plain `Sheet` used that way gets `className='w-full gap-0 data-[side=right]:sm:max-w-xl'`, or `sm:max-w-2xl` with the same prefix when it holds a wide table, a header with a bottom border and a scrolling body ([`Sheet` in `references/overlay.md`](references/overlay.md#5-sheet-temporary-panels)). Keep the narrow default only for a small panel, such as a short explanation.
156
156
 
@@ -18,6 +18,19 @@ const controls = new Map([
18
18
  ['dialog', 'Dialog or the owning route overlay'],
19
19
  ['summary', 'Accordion or Collapsible'],
20
20
  ]);
21
+ // Native date interactions: the browser's own calendar, not the shadcn Date Picker composition.
22
+ const dateTypes = new Map([
23
+ [
24
+ 'date',
25
+ "the application's DatePicker (#components/date-picker); if it does not exist, compose it there once from the calendar, popover and button primitives following https://ui.shadcn.com/docs/components/base/date-picker and the Skill's references/frontend/references/form.md (Dates)",
26
+ ],
27
+ [
28
+ 'datetime-local',
29
+ "the application's DatePicker for the day plus an Input type='time' for the time, combined into one value at the component boundary (the Time Picker example of https://ui.shadcn.com/docs/components/base/date-picker); keep the time, do not replace it with a date-only picker",
30
+ ],
31
+ ]);
32
+ // Primitive exports that render a native <input> and pass `type` through to it.
33
+ const inputPrimitives = new Set(['Input', 'InputGroupInput']);
21
34
  const widgetRoles = new Set([
22
35
  'button',
23
36
  'checkbox',
@@ -96,6 +109,8 @@ export function inspectSource(ts, text, file, root) {
96
109
  }
97
110
  const primitives = new Set();
98
111
  const namespaces = new Set();
112
+ // Local names bound to an input primitive, including aliases.
113
+ const inputs = new Set();
99
114
  for (const statement of source.statements) {
100
115
  if (
101
116
  !ts.isImportDeclaration(statement) ||
@@ -116,7 +131,10 @@ export function inspectSource(ts, text, file, root) {
116
131
  if (clause.name) primitives.add(clause.name.text);
117
132
  if (clause.namedBindings && ts.isNamedImports(clause.namedBindings)) {
118
133
  for (const item of clause.namedBindings.elements) {
119
- if (!item.isTypeOnly) primitives.add(item.name.text);
134
+ if (item.isTypeOnly) continue;
135
+ primitives.add(item.name.text);
136
+ if (inputPrimitives.has((item.propertyName ?? item.name).text))
137
+ inputs.add(item.name.text);
120
138
  }
121
139
  } else if (clause.namedBindings)
122
140
  namespaces.add(clause.namedBindings.name.text);
@@ -180,15 +198,59 @@ export function inspectSource(ts, text, file, root) {
180
198
  namespaces.has(tag.expression.text);
181
199
  }
182
200
 
201
+ /** A primitive that renders a native input: `Input`, an alias of it, or `UI.Input` from a namespace import. */
202
+ function inputPrimitive(tag) {
203
+ if (ts.isIdentifier(tag)) return inputs.has(tag.text);
204
+ return (
205
+ ts.isPropertyAccessExpression(tag) &&
206
+ ts.isIdentifier(tag.expression) &&
207
+ namespaces.has(tag.expression.text) &&
208
+ inputPrimitives.has(tag.name.text)
209
+ );
210
+ }
211
+
183
212
  const findings = [];
184
213
  const accepted = [];
214
+ function report(node, tag, replacement, type) {
215
+ const position = source.getLineAndCharacterOfPosition(
216
+ node.getStart(source),
217
+ );
218
+ const exception = [...exceptions.values()].find(
219
+ (item) =>
220
+ item.nextLine === position.line &&
221
+ !item.used &&
222
+ /^\s*$/.test(text.slice(item.end, node.getStart(source))),
223
+ );
224
+ const finding = {
225
+ file,
226
+ line: position.line + 1,
227
+ column: position.character + 1,
228
+ tag,
229
+ ...(type ? { type } : {}),
230
+ replacement,
231
+ };
232
+ if (exception?.reason && !/^(todo|n\/a|none)$/i.test(exception.reason)) {
233
+ exception.used = true;
234
+ accepted.push({ ...finding, reason: exception.reason });
235
+ } else findings.push(finding);
236
+ }
185
237
  function visit(node) {
186
238
  if (ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) {
187
239
  const tag = node.tagName.getText(source);
188
- if (/^[a-z]/.test(tag) && !tag.includes('.')) {
189
- const hidden =
190
- tag === 'input' &&
191
- literal(ts, attribute(ts, node, 'type')?.initializer) === 'hidden';
240
+ // Only a statically known type is checked; `type={kind}` and spread props are left to source review.
241
+ const type = literal(
242
+ ts,
243
+ attribute(ts, node, 'type')?.initializer,
244
+ )?.toLowerCase();
245
+ const dateReplacement = dateTypes.get(type);
246
+ if (
247
+ dateReplacement &&
248
+ (tag === 'input' || inputPrimitive(node.tagName))
249
+ ) {
250
+ // A date input stays a native calendar even inside a primitive's `render`.
251
+ report(node, tag, dateReplacement, type);
252
+ } else if (/^[a-z]/.test(tag) && !tag.includes('.')) {
253
+ const hidden = tag === 'input' && type === 'hidden';
192
254
  const role = literal(ts, attribute(ts, node, 'role')?.initializer);
193
255
  const clickable =
194
256
  passiveTags.has(tag) &&
@@ -200,31 +262,8 @@ export function inspectSource(ts, text, file, root) {
200
262
  (widgetRoles.has(role) || clickable
201
263
  ? 'the matching shadcn interaction or an existing business component'
202
264
  : undefined);
203
- if (replacement && !hidden && !renderedByPrimitive(node)) {
204
- const position = source.getLineAndCharacterOfPosition(
205
- node.getStart(source),
206
- );
207
- const exception = [...exceptions.values()].find(
208
- (item) =>
209
- item.nextLine === position.line &&
210
- !item.used &&
211
- /^\s*$/.test(text.slice(item.end, node.getStart(source))),
212
- );
213
- const finding = {
214
- file,
215
- line: position.line + 1,
216
- column: position.character + 1,
217
- tag,
218
- replacement,
219
- };
220
- if (
221
- exception?.reason &&
222
- !/^(todo|n\/a|none)$/i.test(exception.reason)
223
- ) {
224
- exception.used = true;
225
- accepted.push({ ...finding, reason: exception.reason });
226
- } else findings.push(finding);
227
- }
265
+ if (replacement && !hidden && !renderedByPrimitive(node))
266
+ report(node, tag, replacement);
228
267
  }
229
268
  }
230
269
  ts.forEachChild(node, visit);
@@ -272,6 +311,10 @@ function collectFiles(root, requested) {
272
311
  return { files: [...files].sort(), skipped };
273
312
  }
274
313
 
314
+ function label(item) {
315
+ return item.type ? `<${item.tag} type="${item.type}">` : `<${item.tag}>`;
316
+ }
317
+
275
318
  export function main(args) {
276
319
  let root = process.cwd();
277
320
  const requested = [];
@@ -307,12 +350,12 @@ export function main(args) {
307
350
  const result = inspectSource(ts, readFileSync(file, 'utf8'), file, root);
308
351
  for (const item of result.findings) {
309
352
  console.log(
310
- `${relative(root, file)}:${item.line}:${item.column} <${item.tag}>: use ${item.replacement}.`,
353
+ `${relative(root, file)}:${item.line}:${item.column} ${label(item)}: use ${item.replacement}.`,
311
354
  );
312
355
  }
313
356
  for (const item of result.accepted) {
314
357
  console.log(
315
- `${relative(root, file)}:${item.line}:${item.column} REVIEW EXCEPTION <${item.tag}>: ${item.reason}`,
358
+ `${relative(root, file)}:${item.line}:${item.column} REVIEW EXCEPTION ${label(item)}: ${item.reason}`,
316
359
  );
317
360
  }
318
361
  findings += result.findings.length;
@@ -21,6 +21,7 @@ These English references adapt the plugin development guide into task-specific i
21
21
  | Register, configure, upgrade, disable, unregister, or diagnose plugin integration | [Registration and lifecycle](references/registration.md) |
22
22
  | Choose Client components, ServiceProviders, React Providers, configuration, or API access | [Client architecture](references/client.md) |
23
23
  | Define Server configuration defaults, environment mappings, validation, or browser-visible fields | [Plugin configuration](references/configuration.md) |
24
+ | Migrate Concurrency, Jobs or Queue backend selectors and existing application factories | [Strict backend configuration](references/backends-configuration.md) |
24
25
  | Build or change any plugin UI | [Shared UI design and host acceptance](references/ui-design.md), then [shadcn components and styling](references/client-components.md) |
25
26
  | Add business pages, menus, Tabs, route dialogs/drawers, child routes, or page overrides | [Client routing](references/client-routing.md) |
26
27
  | Design configuration entities, settings permissions, routed editors and safe saves | [System settings](references/system-settings.md) |
@@ -0,0 +1,56 @@
1
+ # Concurrency, Jobs and Queue backend configuration
2
+
3
+ These three sections accept only `default` and `backends`. Keep adapter names unchanged: local Concurrency uses `mutex`, Jobs uses `memory`, and Queue uses `inMemory`. A backend name is a deployment selector, not a business resource, scope, task or queue name.
4
+
5
+ ```yaml
6
+ concurrency:
7
+ default: local
8
+ backends:
9
+ local:
10
+ adapter: mutex
11
+ jobs:
12
+ default: distributed
13
+ backends:
14
+ local:
15
+ adapter: memory
16
+ distributed:
17
+ adapter: redis
18
+ connection:
19
+ host: redis.internal
20
+ port: 6379
21
+ queue:
22
+ default: local
23
+ backends:
24
+ local:
25
+ adapter: inMemory
26
+ ```
27
+
28
+ Redis requires the corresponding commercial Server plugin, explicitly installed and registered. Declaring an unused Redis backend does not select it or require a Redis connection. A selected Redis backend without its implementation fails; it never silently becomes local. Registered implementations retain their existing entry-level validation and lifecycle: Queue and Concurrency validate unused registered entries, while Jobs resolves adapter options on acquisition.
29
+
30
+ ## Migrate an existing application
31
+
32
+ Move every old direct entry from `<section>.<name>` to `<section>.backends.<name>`; retain `<section>.default` at the section root with exactly the same selected name. Remove all old top-level entries, including unselected ones. Mixed formats and same-name duplicates are errors, even when a new default selects a valid backend. Merely adding `backends` alongside the old entries is not a migration. There is no compatibility shim.
33
+
34
+ Update both `config.yml` and application-owned TypeScript configuration factories. Updating a framework dependency does not rewrite an already-generated application's `server/config/concurrency.ts`, `jobs.ts` or `queue.ts`. Use `defineConcurrencyConfig()` for Concurrency. Move Jobs/Queue defaults into `backends` and register `validateAppJobsConfig` from `@nocobase/app-server/jobs` and `validateAppQueueConfig` from `@nocobase/app-server/queue` with `defineAppConfig({ defaults, validate })`. This validates the merged user YAML rather than only the factory defaults.
35
+
36
+ ```ts
37
+ import { defineAppConfig } from '@nocobase/app-server/config';
38
+ import { validateAppJobsConfig, type AppJobsConfig } from '@nocobase/app-server/jobs';
39
+
40
+ export default defineAppConfig<AppJobsConfig>({
41
+ defaults: ({ paths }) => ({
42
+ backends: {
43
+ local: { adapter: 'memory', persistence: { path: paths.storage('jobs') } },
44
+ },
45
+ }),
46
+ validate: validateAppJobsConfig,
47
+ });
48
+ ```
49
+
50
+ Run the application's `config:check` before restarting. Queue no longer discards the historical `connections`, `worker` and `jobs` fields or an invalid default with a warning and then starts on Memory. Migrate their backend configuration explicitly and move business worker/job options to their existing consumer APIs; deleting a warning is not sufficient. Invalid section, map or entry types, missing adapters, malformed defaults and defaults naming absent backends fail without a local fallback. Do not paste credentials into diagnostics.
51
+
52
+ ## Selection and data compatibility
53
+
54
+ A structurally valid section without `default` keeps that service's existing built-in local behavior, even if `backends` declares entries. Concurrency's factory still selects `memory` by default; the Jobs/Queue template factories still do not set `default`. Concurrency rejects an unknown explicit backend name. Jobs and Queue retain their business-name behavior: an unknown explicit name tries the configured default, then the built-in local configuration when no default exists. No backend inherits options from another entry.
55
+
56
+ Only the wrapper changes. Preserve adapter, connection target and database, namespace, configured persistence paths, scopes, task names, queue names and resource names. Do not add the backend configuration name to Redis keys or local paths. Keep the same Redis destinations and key encodings during rolling upgrades; no Redis data migration or Realtime change is part of this migration.
@@ -10,6 +10,8 @@ Keep paths in `env`, `public` and validation errors relative to the section: `pa
10
10
 
11
11
  Publish the factory through a documented package export, such as `@example/app-plugin-reading-list/config`. Its consumer is the application's Server composition; importing it must not start a service or read process-wide environment variables. The example [manifest](../assets/testing-example/package.json) shows the source export, while a release must also have the corresponding compiled export and declaration files described in [package contracts](plugin-foundation.md).
12
12
 
13
+ For application-owned Concurrency, Jobs and Queue sections, follow the [strict backend configuration and migration guide](backends-configuration.md). Named entries belong under `backends`; validation must inspect the merged user configuration, not only new factory defaults.
14
+
13
15
  ## Register the factory in the application
14
16
 
15
17
  Add the section to the application's existing `defaultAppConfigs()` map and register the Server plugin separately. The complete fixture's [runtime](../assets/testing-example/tests/fixtures/app/server/runtime.ts) shows both steps together with authentication, authorization and database prerequisites. In a generated application, preserve its other sections and its normal configuration-file loading:
@@ -274,7 +274,7 @@ Register handlers in `boot()`: the application's queue provider sets the service
274
274
 
275
275
  ### Test background work
276
276
 
277
- Test the real Provider against a service created for the test, with its memory state under a temporary directory: `createJobExecutorService(undefined, { appName, storagePath })` for jobs, or `createQueueService({ default: 'memory', memory: { adapter: 'inMemory', persistence: { path } } }, …)` for queues. Start or set up, submit or publish, wait for the effect, and shut down. Cover retry, idempotency and, for queues, deduplication, then run a target App integration test. A Route that submits work still needs its own authentication and authorization tests.
277
+ Test the real Provider against a service created for the test, with its memory state under a temporary directory: `createJobExecutorService(undefined, { appName, storagePath })` for jobs, or `createQueueService({ default: 'memory', backends: { memory: { adapter: 'inMemory', persistence: { path } } } }, …)` for queues. Start or set up, submit or publish, wait for the effect, and shut down. Cover retry, idempotency and, for queues, deduplication, then run a target App integration test. A Route that submits work still needs its own authentication and authorization tests.
278
278
 
279
279
  ## Verification and source references
280
280
 
@@ -43,12 +43,80 @@ Update test doubles to return publication promises and correlate subscription ac
43
43
 
44
44
  ## Redis implementation extraction
45
45
 
46
- When TARGET removes the built-in Redis broker, install a compatible `@nocobase/app-plugin-realtime-redis` and explicitly add its `/server` definition to the existing Server plugin composition. Keep realtime.adapter, namespace and redis configuration paths. Standalone consumers move createRedisRealtimeBroker and RedisRealtimeBrokerOptions imports to `@nocobase/app-plugin-realtime-redis/broker`; the core service and original realtimeServiceToken do not change. The public realtimeServiceOptions helper preserves its first two arguments and accepts an optional application-local registry; without one it supports only Memory. Custom factories register during register, before first service resolution.
46
+ When TARGET removes the built-in Redis broker, install a compatible `@nocobase/app-plugin-realtime-redis` and explicitly add its `/server` definition to the existing Server plugin composition. Extraction alone retained the old configuration paths; when TARGET includes broker nesting, also apply the configuration migration below. Standalone consumers move createRedisRealtimeBroker and RedisRealtimeBrokerOptions imports to `@nocobase/app-plugin-realtime-redis/broker`; the core service and original realtimeServiceToken do not change. The public realtimeServiceOptions helper preserves its first two arguments and accepts an optional application-local registry; without one it supports only Memory. Custom factories register during register, before first service resolution.
47
47
 
48
48
  For a required commercial package, follow the installed App development Skill's `references/plugins.md` commercial package workflow: automatically check that package's metadata at pkg-v3 with existing credentials and command-local global/scoped registry overrides, then install/register a compatible authorized version without prompting. If access is unavailable, leave a brief conversation notice and continue independent upgrade preparation without waiting for the user. Distinguish authorization denial from credentials/network/version issues. Keep the dependent rollout pending and preserve the working backend and rollback checkpoint; do not remove the OSS implementation before its required replacement is available.
49
49
 
50
50
  Resolve real published peer lower bounds, not merely workspace manifest versions. Roll out additive OSS API, compatible commercial package and application registration before final OSS removal. An unregistered selected adapter fails rather than silently using Memory. Roll back packages, lockfile, registration and configuration together; do not mix Memory and Redis replicas. Server plugin registration and config-factory aggregation are separate; config check proves neither plugin enablement nor Redis connectivity.
51
51
 
52
+ ## Broker configuration nesting
53
+
54
+ When TARGET selects brokers through `realtime.broker`, migrate every configuration source together. Old paths are errors, not compatibility aliases, including an old `adapter: inMemory` in code defaults. A new YAML broker merged with an old code default must fail rather than choose a hidden precedence.
55
+
56
+ Before:
57
+
58
+ ```yaml
59
+ realtime:
60
+ namespace: my-app
61
+ authorizationTimeoutMs: 5000
62
+ sessionCheckIntervalMs: 30000
63
+ limits:
64
+ maxConnections: 10000
65
+ adapter: redis
66
+ redis:
67
+ setupTimeoutMs: 5000
68
+ connection:
69
+ host: redis.internal
70
+ port: 6379
71
+ commandTimeout: 5000
72
+ ```
73
+
74
+ After:
75
+
76
+ ```yaml
77
+ realtime:
78
+ namespace: my-app
79
+ authorizationTimeoutMs: 5000
80
+ sessionCheckIntervalMs: 30000
81
+ limits:
82
+ maxConnections: 10000
83
+ broker:
84
+ adapter: redis
85
+ setupTimeoutMs: 5000
86
+ connection:
87
+ host: redis.internal
88
+ port: 6379
89
+ commandTimeout: 5000
90
+ ```
91
+
92
+ Keep namespace at the service level; it still defaults to app.name, then `default`. No broker.namespace, default broker selector, named brokers or Topic routing is introduced. All service limits and timer defaults are unchanged. Redis channels remain `nocobase:realtime:${namespace}` with the existing event/control formats; neither `broker` nor another configuration path enters the physical identity. Redis Pub/Sub ignores logical DB isolation; preserve channel ACLs and network isolation.
93
+
94
+ In `server/config/realtime.ts`, replace old `adapter` and `redis` defaults as well as YAML. Prefer an empty validated section for applications that should remain local until explicitly configured:
95
+
96
+ ```ts
97
+ import { defineRealtimeConfig } from '@nocobase/app-server/realtime';
98
+
99
+ export default defineRealtimeConfig();
100
+ ```
101
+
102
+ Add the import, `realtime: ReturnType<typeof realtime>` type entry and `realtime` value entry to the existing `defaultAppConfigs` map in `server/config/index.ts`. Default and Examples already supply this section. To intentionally select local-only operation, use `{ broker: { adapter: 'inMemory' } }`; intentionally configured Redis defaults use `{ broker: { adapter: 'redis', connection: { host, port }, setupTimeoutMs } }`, never a separate redis property. Install and register `@nocobase/app-plugin-realtime-redis/server` separately before selecting Redis; OSS templates do not depend on or register it.
103
+
104
+ An absent broker uses inMemory, but an explicit empty/null/array broker or a missing/empty/non-string adapter fails. The templates do not default broker.adapter, so incomplete user YAML cannot inherit it. Validation sees merged configuration, not each original source: if a custom App deliberately defaults a valid broker.adapter in code, YAML that omits that leaf can inherit it and is indistinguishable from a complete final broker. Remove that default when omission must fail. Connection stays optional, with existing SDK defaults and validation; this migration adds no connection whitelist, retry or lifecycle policy.
105
+
106
+ Update declared environment mappings and configuration-writing scripts using this path table. Environment variables are not auto-discovered; keep their existing names if needed but change their declared destination. Section-factory mappings use the relative path (for example, `broker.adapter`); an application-level environmentProvider mapping uses the full path. Keep passwords Server-only and mark their mappings secret.
107
+
108
+ | Old path | New path |
109
+ | ----------------------------- | ------------------------------ |
110
+ | realtime.adapter | realtime.broker.adapter |
111
+ | realtime.redis.connection | realtime.broker.connection |
112
+ | realtime.redis.setupTimeoutMs | realtime.broker.setupTimeoutMs |
113
+
114
+ For example, after removing the old keys from YAML and code defaults, change script writes to `pnpm nocobase config set realtime.broker.adapter=redis realtime.broker.connection.host=redis.internal realtime.broker.setupTimeoutMs=5000`. A secret write uses `pnpm nocobase config set --from-env realtime.broker.connection.password=REALTIME_REDIS_PASSWORD`. Do not leave old keys beside new keys; run config check and then a real startup/connectivity test. No new environment names are supplied by the core helper or Redis plugin.
115
+
116
+ Upgrade the OSS host, Redis plugin, application source defaults, YAML/environment mappings and lockfile as a coordinated cohort. The factory context shape stays `{ namespace, config, logger }`, with the entire service config under config and Redis options under config.broker; custom factories must update reads. The standalone SDK `createRedisRealtimeBroker({ namespace, connection, setupTimeoutMs, onError })` does not change. An old host may silently ignore a new broker selection; an old plugin under a new host may read missing config.redis and connect using SDK defaults. These package combinations are unsupported even if TypeScript compilation or peer ranges accept them. Resolve actual compatible published artifacts before deployment; do not represent an unmerged vendor source mirror as an installable dependency.
117
+
118
+ Merge the OSS implementation first, then update Pro's committed vendor pointer and synchronized settings/lockfile and rerun its checks before release. Make the matching Pro package available before deploying Redis applications on the new host. A wire-format equivalence test does not alone prove a rolling mixed-binary deployment; validate exact deployed versions before making that claim. Rollback restores matching packages, lockfile, composition and the old configuration, not just a binary. Existing default-local applications need no database or Redis data migration. This change does not modify WebSockets, authorization/session checks, subscriptions, resync, message semantics or Agents response streams.
119
+
52
120
  ## Preserve recovery during rollout
53
121
 
54
122
  Keep recovery polling until all relevant producers announce changes and disconnected clients can reconcile from durable data. External changes, time-based expiry and failed best-effort announcements may still require a suitable reconciliation interval. Replacing every poll is not a prerequisite for this upgrade.
@@ -95,7 +95,9 @@ Redis Queue support requires installation and explicit Server registration of `@
95
95
 
96
96
  For every required commercial backend package, automatically probe its metadata at `https://pkg-v3.nocobase.com/` using existing credentials and command-local global/scoped registry overrides, check runtime/peer compatibility and install/register an authorized version without prompting. Follow the installed App development Skill's `references/plugins.md` commercial package workflow. If access is unavailable, leave a brief conversation notice, distinguish authorization denial from credentials/network/version issues, and continue independent preparation without waiting for the user. Keep dependent deployment or scaling pending and existing working configuration intact; do not select an unregistered Redis adapter or claim Memory satisfies multi-instance requirements.
97
97
 
98
- When upgrading an application generated from an older template, add `adapter: redis` explicitly to every Redis Jobs entry in `config.yml` that previously relied on the template's TypeScript defaults. Templates now provide only Memory defaults; `jobs.redis.connection` alone does not identify a Redis backend. Preserve existing connection, namespace and scope values, and install and register the commercial Server plugin before selecting those configurations.
98
+ When upgrading an application generated from an older template, add `adapter: redis` explicitly to every Redis Jobs entry in `config.yml` that previously relied on the template's TypeScript defaults. Templates now provide only Memory defaults; `jobs.backends.redis.connection` alone does not identify a Redis backend. Preserve existing connection, namespace and scope values, and install and register the commercial Server plugin before selecting those configurations.
99
+
100
+ Concurrency, Jobs and Queue use strict `default`/`backends` sections. Follow the [backend configuration migration](../nocobase-app-plugin-development/references/backends-configuration.md), including updating application-owned factories and retaining physical backend identities. Queue no longer ignores legacy fields or invalid defaults.
99
101
 
100
102
  The reverse proxy must preserve the public `Host` and protocol headers, forward cookies, and support WebSocket `Upgrade` and `Connection` headers.
101
103