@nocobase/client-v2 2.2.0-alpha.1 → 2.2.0-alpha.3

package/src/__tests__/nocobase-buildin-plugin-auth.test.tsx

@@ -12,6 +12,10 @@ import { act, render, screen, waitFor } from '@testing-library/react';
 import React from 'react';
 import { NocoBaseBuildInPlugin } from '../nocobase-buildin-plugin';
 
+const TestingAppSpin = () => <div data-testid="app-spin">app spin</div>;
+
+const TestingAppError = ({ error }: { error: Error }) => <div role="alert">{error.message}</div>;
+
 class SkippedPublicRoutePlugin extends Plugin {
   async load() {
     this.router.add('public', {
@@ -22,6 +26,31 @@ class SkippedPublicRoutePlugin extends Plugin {
   }
 }
 
+class DummySigninRoutePlugin extends Plugin {
+  async load() {
+    this.router.add('signin-test', {
+      path: '/signin',
+      skipAuthCheck: true,
+      Component: () => <div>signin page</div>,
+    });
+  }
+}
+
+class AuthBootstrapRoutePlugin extends Plugin {
+  async load() {
+    this.router.add('secure', {
+      path: '/secure',
+      authCheck: true,
+      Component: () => <div>secure page</div>,
+    });
+    this.router.add('guest', {
+      path: '/guest',
+      authCheck: false,
+      Component: () => <div>guest page</div>,
+    });
+  }
+}
+
 describe('nocobase buildin plugin auth redirect', () => {
   const originalLocation = globalThis.window.location;
 
@@ -155,6 +184,176 @@ describe('nocobase buildin plugin auth redirect', () => {
     });
   });
 
+  it('should defer data source bootstrap until auth-required route is authenticated after signin redirect', async () => {
+    const app = createMockClient({
+      publicPath: '/v2/',
+      plugins: [NocoBaseBuildInPlugin as any, DummySigninRoutePlugin as any, AuthBootstrapRoutePlugin as any],
+      components: { AppSpin: TestingAppSpin },
+      router: { type: 'memory', initialEntries: ['/v2/secure'] },
+    });
+    app.apiMock.onGet('app:getLang').reply(200, {
+      data: { lang: 'en-US', resources: { client: {} }, cron: {} },
+    });
+    const events: string[] = [];
+    app.apiMock.onGet('/auth:check').replyOnce(() => {
+      events.push('auth:first');
+      return [200, { data: {} }];
+    });
+    app.apiMock.onGet('/auth:check').reply(() => {
+      events.push('auth:second');
+      return [200, { data: { id: 1 } }];
+    });
+
+    const ensureLoaded = vi.spyOn(app.dataSourceManager, 'ensureLoaded').mockImplementation(() => {
+      if (!app.apiClient.auth.token) {
+        const pending = new Promise<void>(() => undefined);
+        app.dataSourceManager.loadingPromise = pending;
+        return pending;
+      }
+      events.push('bootstrap');
+      expect(events).toContain('auth:second');
+      return Promise.resolve();
+    });
+
+    const Root = app.getRootComponent();
+    render(<Root />);
+
+    await waitFor(() => {
+      expect(app.router.router.state.location.pathname).toBe('/v2/signin');
+      expect(app.router.router.state.location.search).toBe('?redirect=%2Fv2%2Fsecure');
+    });
+    expect(await screen.findByText('signin page')).toBeInTheDocument();
+    expect(screen.queryByTestId('app-spin')).not.toBeInTheDocument();
+    expect(ensureLoaded).not.toHaveBeenCalled();
+    expect(app.dataSourceManager.loadingPromise).toBeNull();
+    expect(events).toEqual(['auth:first']);
+
+    act(() => {
+      app.apiClient.auth.setToken('test-token');
+    });
+
+    await act(async () => {
+      await app.router.router.navigate('/secure');
+    });
+
+    expect(await screen.findByText('secure page')).toBeInTheDocument();
+    await waitFor(() => {
+      expect(document.querySelector('.ant-spin-spinning')).not.toBeInTheDocument();
+    });
+    expect(ensureLoaded).toHaveBeenCalledTimes(1);
+  });
+
+  it('should redirect on auth-required /auth:check 401 without bootstrapping data sources', async () => {
+    const app = createMockClient({
+      publicPath: '/v2/',
+      plugins: [NocoBaseBuildInPlugin as any, DummySigninRoutePlugin as any, AuthBootstrapRoutePlugin as any],
+      components: { AppSpin: TestingAppSpin },
+      router: { type: 'memory', initialEntries: ['/v2/secure'] },
+    });
+    app.apiMock.onGet('app:getLang').reply(200, {
+      data: { lang: 'en-US', resources: { client: {} }, cron: {} },
+    });
+    app.apiMock.onGet('/auth:check').reply(401, { errors: [{ code: 'EMPTY_TOKEN' }] });
+    const ensureLoaded = vi.spyOn(app.dataSourceManager, 'ensureLoaded').mockImplementation(() => {
+      const pending = new Promise<void>(() => undefined);
+      app.dataSourceManager.loadingPromise = pending;
+      return pending;
+    });
+
+    const Root = app.getRootComponent();
+    render(<Root />);
+
+    await waitFor(() => {
+      expect(app.router.router.state.location.pathname).toBe('/v2/signin');
+      expect(app.router.router.state.location.search).toBe('?redirect=%2Fv2%2Fsecure');
+    });
+    expect(await screen.findByText('signin page')).toBeInTheDocument();
+    expect(screen.queryByTestId('app-spin')).not.toBeInTheDocument();
+    expect(ensureLoaded).not.toHaveBeenCalled();
+    expect(app.dataSourceManager.loadingPromise).toBeNull();
+  });
+
+  it('should surface non-auth /auth:check errors instead of leaving auth-required route spinning', async () => {
+    const app = createMockClient({
+      publicPath: '/v2/',
+      plugins: [NocoBaseBuildInPlugin as any, AuthBootstrapRoutePlugin as any],
+      components: { AppSpin: TestingAppSpin, AppError: TestingAppError },
+      router: { type: 'memory', initialEntries: ['/v2/secure'] },
+    });
+    app.apiMock.onGet('app:getLang').reply(200, {
+      data: { lang: 'en-US', resources: { client: {} }, cron: {} },
+    });
+    app.apiMock.onGet('/auth:check').reply(500, { errors: [{ message: 'auth check failed' }] });
+    const ensureLoaded = vi.spyOn(app.dataSourceManager, 'ensureLoaded').mockResolvedValue(undefined);
+
+    const Root = app.getRootComponent();
+    render(<Root />);
+
+    expect(await screen.findByRole('alert')).toHaveTextContent('Request failed with status code 500');
+    expect(screen.queryByTestId('app-spin')).not.toBeInTheDocument();
+    expect(ensureLoaded).not.toHaveBeenCalled();
+  });
+
+  it.each(['/v2/signin', '/v2/public'])('should not bootstrap data sources on skipped auth route: %s', async (path) => {
+    const app = createMockClient({
+      publicPath: '/v2/',
+      plugins: [NocoBaseBuildInPlugin as any, DummySigninRoutePlugin as any, SkippedPublicRoutePlugin as any],
+      components: { AppSpin: TestingAppSpin },
+      router: { type: 'memory', initialEntries: [path] },
+    });
+    app.apiMock.onGet('app:getLang').reply(200, {
+      data: { lang: 'en-US', resources: { client: {} }, cron: {} },
+    });
+    const ensureLoaded = vi.spyOn(app.dataSourceManager, 'ensureLoaded').mockResolvedValue(undefined);
+
+    const Root = app.getRootComponent();
+    render(<Root />);
+
+    expect(await screen.findByText(path === '/v2/signin' ? 'signin page' : 'public page')).toBeInTheDocument();
+    expect(screen.queryByTestId('app-spin')).not.toBeInTheDocument();
+    expect(ensureLoaded).not.toHaveBeenCalled();
+    expect(app.apiMock.history.get.filter((request) => request.url === '/auth:check')).toHaveLength(0);
+  });
+
+  it('should bootstrap data sources for authenticated auth-required route access', async () => {
+    const app = createMockClient({
+      publicPath: '/v2/',
+      plugins: [NocoBaseBuildInPlugin as any, AuthBootstrapRoutePlugin as any],
+      router: { type: 'memory', initialEntries: ['/v2/secure'] },
+    });
+    app.apiClient.auth.setToken('test-token');
+    app.apiMock.onGet('app:getLang').reply(200, {
+      data: { lang: 'en-US', resources: { client: {} }, cron: {} },
+    });
+    app.apiMock.onGet('/auth:check').reply(200, { data: { id: 1 } });
+    const ensureLoaded = vi.spyOn(app.dataSourceManager, 'ensureLoaded').mockResolvedValue(undefined);
+
+    const Root = app.getRootComponent();
+    render(<Root />);
+
+    expect(await screen.findByText('secure page')).toBeInTheDocument();
+    expect(ensureLoaded).toHaveBeenCalledTimes(1);
+  });
+
+  it('should not auth-check or bootstrap authCheck false routes', async () => {
+    const app = createMockClient({
+      publicPath: '/v2/',
+      plugins: [NocoBaseBuildInPlugin as any, AuthBootstrapRoutePlugin as any],
+      router: { type: 'memory', initialEntries: ['/v2/guest'] },
+    });
+    app.apiMock.onGet('app:getLang').reply(200, {
+      data: { lang: 'en-US', resources: { client: {} }, cron: {} },
+    });
+    const ensureLoaded = vi.spyOn(app.dataSourceManager, 'ensureLoaded').mockResolvedValue(undefined);
+
+    const Root = app.getRootComponent();
+    render(<Root />);
+
+    expect(await screen.findByText('guest page')).toBeInTheDocument();
+    expect(ensureLoaded).not.toHaveBeenCalled();
+    expect(app.apiMock.history.get.filter((request) => request.url === '/auth:check')).toHaveLength(0);
+  });
+
   it('should render v2 admin root without redirecting away', async () => {
     const app = createMockClient({
       publicPath: '/v2/',

package/src/__tests__/plugin-manager.test.tsx

@@ -18,6 +18,19 @@ class TestAclPlugin extends Plugin {
   }
 }
 
+class TestSettingsLinkPlugin extends Plugin {
+  async load() {
+    this.app.pluginSettingsManager.addMenuItem({ key: 'shared-settings', title: 'Shared settings' });
+    this.app.pluginSettingsManager.addPageTabItem({
+      menuKey: 'shared-settings',
+      key: 'target',
+      title: 'Target settings',
+      Component: () => <div>Target settings page</div>,
+    });
+    this.app.pluginSettingsManager.setPluginSettingsLink('demo-plugin', 'shared-settings.target');
+  }
+}
+
 type MockClientApplication = ReturnType<typeof createMockClient>;
 
 const renderApp = (app: MockClientApplication) => {
@@ -35,9 +48,9 @@ const waitForGetRequests = async (app: MockClientApplication, urls: string[]) =>
   );
 };
 
-const setupApp = (pmList: any[]) => {
+const setupApp = (pmList: any[], plugins: Array<typeof Plugin> = []) => {
   const app = createMockClient({
-    plugins: [NocoBaseBuildInPlugin, TestAclPlugin],
+    plugins: [NocoBaseBuildInPlugin, TestAclPlugin, ...plugins],
     router: { type: 'memory', initialEntries: ['/admin/settings/plugin-manager'] },
   });
 
@@ -174,4 +187,33 @@ describe('plugin-manager page', () => {
       expect(removeCall?.params).toMatchObject({ filterByTk: 'demo-plugin' });
     });
   });
+
+  it('shows Settings for a plugin linked to a different settings page', async () => {
+    const app = setupApp(
+      [
+        {
+          name: 'demo-plugin',
+          packageName: '@nocobase/demo-plugin',
+          displayName: 'Demo plugin',
+          description: 'A demo',
+          enabled: true,
+          builtIn: false,
+          removable: false,
+          version: '0.1.0',
+          isCompatible: true,
+          keywords: [],
+        },
+      ],
+      [TestSettingsLinkPlugin],
+    );
+
+    renderApp(app);
+    await waitForGetRequests(app, ['/auth:check', 'roles:check', 'pm:list']);
+
+    const card = await screen.findByRole('button', { name: 'Demo plugin' });
+    const settingsLink = within(card.closest('.ant-card') as HTMLElement).getByText('Settings');
+    fireEvent.click(settingsLink);
+
+    expect(await screen.findByText('Target settings page')).toBeInTheDocument();
+  });
 });

package/src/__tests__/settings-center.test.tsx

@@ -14,7 +14,7 @@ import { message } from 'antd';
 import { AdminSettingsLayoutModel as ClientV2AdminSettingsLayoutModel } from '../settings-center';
 import { AdminSettingsLayoutModel as ClientV1AdminSettingsLayoutModel } from '../../../client/src/pm/AdminSettingsLayoutModel';
 import { NocoBaseBuildInPlugin } from '../nocobase-buildin-plugin';
-import { matchSettingsRoute } from '../settings-center/utils';
+import { matchSettingsRoute, sortTopLevelSettings } from '../settings-center/utils';
 
 class TestAclPlugin extends Plugin {
   async load() {
@@ -168,6 +168,12 @@ describe('settings center', () => {
     });
   });
 
+  it('should sort system-settings with other top-level settings by normal ordering', () => {
+    const settings = [{ name: 'system-settings' }, { name: 'api-keys' }, { name: 'backups' }] as any;
+
+    expect(sortTopLevelSettings(settings).map((item) => item.name)).toEqual(['api-keys', 'backups', 'system-settings']);
+  });
+
   it('should redirect /admin/settings to system-settings by default', async () => {
     const app = createMockClient({
       plugins: [NocoBaseBuildInPlugin, TestAclPlugin],
@@ -354,6 +360,39 @@ describe('settings center', () => {
     expect(screen.getByRole('menuitem', { name: 'Menu ACL Demo' })).toBeInTheDocument();
   });
 
+  it('should allow the settings sidebar menu to scroll independently', async () => {
+    class ManySettingsPlugin extends Plugin {
+      async load() {
+        for (let index = 0; index < 30; index += 1) {
+          this.pluginSettingsManager.addMenuItem({
+            key: `scroll-demo-${index}`,
+            title: `Scroll demo ${index}`,
+          });
+          this.pluginSettingsManager.addPageTabItem({
+            menuKey: `scroll-demo-${index}`,
+            key: 'index',
+            title: `Scroll demo ${index}`,
+            Component: () => <div>{`Scroll demo page ${index}`}</div>,
+          });
+        }
+      }
+    }
+
+    const app = createMockClient({
+      plugins: [NocoBaseBuildInPlugin, TestAclPlugin, ManySettingsPlugin],
+      router: { type: 'memory', initialEntries: ['/admin/settings/scroll-demo-29'] },
+    });
+    mockAdminRuntime(app);
+
+    await renderApp(app);
+    await waitForGetRequests(app, ['/auth:check', 'roles:check']);
+
+    expect(await screen.findByText('Scroll demo page 29')).toBeInTheDocument();
+
+    const sidebar = screen.getByRole('menuitem', { name: 'Scroll demo 29' }).closest('.ant-layout-sider');
+    expect(sidebar).toHaveStyle({ overflowY: 'auto' });
+  });
+
   it('should save system settings through systemSettings:put', async () => {
     const app = createMockClient({
       plugins: [NocoBaseBuildInPlugin, TestAclPlugin],

package/src/collection-manager/field-configure.ts

@@ -530,7 +530,7 @@ export function reverseFieldConfigureItems(): FieldConfigureItem[] {
       component: 'Input',
       required: true,
       description:
-        "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with an letter.')}}",
+        "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with a letter.')}}",
       hidden: ({ context, values }) => !context.showReverseFieldConfig && !get(values, 'autoCreateReverseField'),
       disabled: ({ context }) => !context.showReverseFieldConfig,
     },

package/src/collection-manager/interfaces/id.ts

@@ -48,7 +48,7 @@ export class IdFieldInterface extends CollectionFieldInterface {
       'x-decorator': 'FormItem',
       'x-component': 'Input',
       description:
-        "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with an letter.')}}",
+        "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with a letter.')}}",
     },
   };
   filterable = {

package/src/collection-manager/interfaces/m2m.tsx

@@ -158,7 +158,7 @@ export class M2MFieldInterface extends CollectionFieldInterface {
                   required: true,
                   default: '{{ useNewId("f_") }}',
                   description:
-                    "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with an letter.')}}",
+                    "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with a letter.')}}",
                   'x-decorator': 'FormItem',
                   'x-component': 'ForeignKey',
                   'x-validator': 'uid',
@@ -192,7 +192,7 @@ export class M2MFieldInterface extends CollectionFieldInterface {
                   required: true,
                   default: '{{ useNewId("f_") }}',
                   description:
-                    "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with an letter.')}}",
+                    "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with a letter.')}}",
                   'x-decorator': 'FormItem',
                   'x-component': 'ForeignKey',
                   'x-validator': 'uid',

package/src/collection-manager/interfaces/m2o.tsx

@@ -69,7 +69,7 @@ export class M2OFieldInterface extends CollectionFieldInterface {
       'x-decorator': 'FormItem',
       'x-component': 'Input',
       description:
-        "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with an letter.')}}",
+        "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with a letter.')}}",
     },
     type: relationshipType,
     grid: {
@@ -123,7 +123,7 @@ export class M2OFieldInterface extends CollectionFieldInterface {
                   required: true,
                   default: '{{ useNewId("f_") }}',
                   description:
-                    "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with an letter.')}}",
+                    "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with a letter.')}}",
                   'x-decorator': 'FormItem',
                   'x-component': 'ForeignKey',
                   'x-validator': 'uid',

package/src/collection-manager/interfaces/nanoid.ts

@@ -42,7 +42,7 @@ export class NanoidFieldInterface extends CollectionFieldInterface {
       'x-component': 'Input',
       'x-disabled': '{{ !createOnly }}',
       description:
-        "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with an letter.')}}",
+        "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with a letter.')}}",
     },
     customAlphabet: {
       type: 'string',

package/src/collection-manager/interfaces/o2m.tsx

@@ -68,7 +68,7 @@ export class O2MFieldInterface extends CollectionFieldInterface {
       'x-decorator': 'FormItem',
       'x-component': 'Input',
       description:
-        "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with an letter.')}}",
+        "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with a letter.')}}",
     },
     type: relationshipType,
     grid: {
@@ -135,7 +135,7 @@ export class O2MFieldInterface extends CollectionFieldInterface {
                   required: true,
                   default: '{{ useNewId("f_") }}',
                   description:
-                    "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with an letter.')}}",
+                    "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with a letter.')}}",
                   'x-decorator': 'FormItem',
                   'x-component': 'ForeignKey',
                   'x-validator': 'uid',

package/src/collection-manager/interfaces/obo.tsx

@@ -55,7 +55,7 @@ export class OBOFieldInterface extends CollectionFieldInterface {
       'x-decorator': 'FormItem',
       'x-component': 'Input',
       description:
-        "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with an letter.')}}",
+        "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with a letter.')}}",
     },
     type: relationshipType,
     grid: {
@@ -109,7 +109,7 @@ export class OBOFieldInterface extends CollectionFieldInterface {
                   required: true,
                   default: '{{ useNewId("f_") }}',
                   description:
-                    "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with an letter.')}}",
+                    "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with a letter.')}}",
                   'x-decorator': 'FormItem',
                   'x-component': 'ForeignKey',
                   'x-validator': 'uid',

package/src/collection-manager/interfaces/oho.tsx

@@ -55,7 +55,7 @@ export class OHOFieldInterface extends CollectionFieldInterface {
       'x-decorator': 'FormItem',
       'x-component': 'Input',
       description:
-        "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with an letter.')}}",
+        "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with a letter.')}}",
     },
     type: relationshipType,
     grid: {
@@ -123,7 +123,7 @@ export class OHOFieldInterface extends CollectionFieldInterface {
                   required: true,
                   default: '{{ useNewId("f_") }}',
                   description:
-                    "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with an letter.')}}",
+                    "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with a letter.')}}",
                   'x-decorator': 'FormItem',
                   'x-component': 'ForeignKey',
                   'x-validator': 'uid',

package/src/collection-manager/interfaces/properties/index.ts

@@ -141,7 +141,7 @@ export const reverseFieldProperties: Record<string, ISchema> = {
         'x-validator': 'uid',
         'x-disabled': '{{ !showReverseFieldConfig }}',
         description:
-          "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with an letter.')}}",
+          "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with a letter.')}}",
       },
     },
   },
@@ -399,7 +399,7 @@ export const defaultProps = {
     'x-component': 'Input',
     'x-validator': 'uid',
     description:
-      "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with an letter.')}}",
+      "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with a letter.')}}",
   },
 };
 

package/src/collection-manager/interfaces/uuid.ts

@@ -46,7 +46,7 @@ export class UUIDFieldInterface extends CollectionFieldInterface {
       'x-component': 'Input',
       'x-disabled': '{{ !createOnly }}',
       description:
-        "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with an letter.')}}",
+        "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with a letter.')}}",
     },
     autoFill,
     layout: {

package/src/components/AppComponents.tsx

@@ -21,7 +21,13 @@ import type { Application } from '../Application';
 interface AppErrorPayload {
   code?: string;
   message?: string;
-  command?: { name: string };
+  command?: {
+    name: string;
+    components?: {
+      maintaining?: string;
+      maintainingDialog?: string;
+    };
+  };
   [key: string]: any;
 }
 
@@ -188,7 +194,12 @@ export const AppError: FC<{ error: Error & { title?: string }; app: Application
 );
 
 export const AppMaintaining: FC<{ app: Application; error: Error }> = observer(
-  ({ app }) => {
+  ({ app, error }) => {
+    const component = (error as AppErrorPayload | undefined)?.command?.components?.maintaining;
+    if (component) {
+      return app.renderComponent(component, { app, error });
+    }
+
     const { icon, status, title, subTitle } = getProps(app);
     return (
       <div>
@@ -211,7 +222,12 @@ export const AppMaintaining: FC<{ app: Application; error: Error }> = observer(
 );
 
 export const AppMaintainingDialog: FC<{ app: Application; error: Error }> = observer(
-  ({ app }) => {
+  ({ app, error }) => {
+    const component = (error as AppErrorPayload | undefined)?.command?.components?.maintainingDialog;
+    if (component) {
+      return app.renderComponent(component, { app, error });
+    }
+
     const { icon, status, title, subTitle } = getProps(app);
     return (
       <Modal open={true} footer={null} closable={false}>

package/src/components/README.md

@@ -190,6 +190,10 @@ import { TypedVariableInput } from '@nocobase/client-v2';
 <Form.Item name={['options', 'secure']} label={t('Secure')} initialValue={true}>
   <TypedVariableInput types={['boolean']} namespaces={['$env']} />
 </Form.Item>
+
+// Inject a custom variable tree (e.g. a workflow node's upstream outputs,
+// which are not in the global registry)
+<TypedVariableInput types={['string', 'number']} metaTree={workflowMetaTree} />
 ```
 
 Key props:
@@ -197,6 +201,7 @@ Key props:
 - `types`: allowed constant types. Shape mirrors v1 `useTypedConstant` — pass bare type names (`['number', 'boolean']`) or `[type, editorProps]` tuples (`[['number', { min, max, step }]]`) to forward props to the underlying antd editor. Defaults to `['string', 'number', 'boolean', 'date']`. **Even when only one type is allowed, the `Constant` entry still expands into a typed submenu** (Number / Boolean / Date / String) — matches v1 so users can see what type the constant is
 - `namespaces`: restrict the variable picker to specific top-level namespaces (e.g. `['$env']`). Omit to expose every namespace registered on `flowEngine.context`
 - `extraNodes`: static leaves appended after the namespace-filtered nodes
+- `metaTree`: **inject the variable tree directly** instead of reading the global `flowEngine.context` meta tree. When set, `namespaces`/`extraNodes` are ignored and this tree is used verbatim — for context-scoped variable sources that are not in the global registry (typically a workflow node's upstream outputs, `$jobsMapByNodeKey`). Nodes whose `children` is a thunk (`() => Promise<MetaTreeNode[]>`) are **lazy-loaded on expand** (via flow-engine's `loadMetaTreeChildren`)
 - `nullable`: whether to expose the `Null` switcher entry. Default `true`. Combined with `Form.Item.rules={[{ required: true }]}`, the user can explicitly clear the field but submission is still blocked by validation — mirrors v1's "Null + required" pairing
 - `delimiters`: variable-token delimiters, default `['{{', '}}']` — same as `VariableInput`
 - `value` / `onChange` / `placeholder` / `disabled` / `style` / `className`: standard controlled-input props
@@ -212,9 +217,10 @@ When **not** to use it:
 - **Pure literal fields** (users will never pass a variable) → use the antd primitive directly (`InputNumber` / `Select` / `DatePicker` / `Input`) and skip the Cascader column overhead
 - **Pure variable fields** (users will never pass a literal) → use `EnvVariableInput` (`$env`-only, with optional password masking) or `VariableInput` (general-purpose)
 
+Supported constant types: `string` / `number` / `boolean` / `date` / `object`. The `object` (JSON) type renders an inline monospace textarea (2 rows by default, drag-resizable) — it keeps the raw text as a draft while editing and `JSON.parse`s it back into an object on blur. On a parse failure it shows the raw `JSON.parse` message (e.g. `Expected property name or '}' in JSON at position …`, matching v1) on its own row below the input, and does not emit. Mirrors v1 `useTypedConstant`'s object form (default value `{}`).
+
 Capabilities skipped (present in v1, not yet ported to v2):
 
-- `object` constant type (JSON editor) — v2 has no inline "JSON editor + Cascader switcher" yet; add when there's a concrete caller
 - Async `loadChildren` cascading — most MetaTree namespaces are already eagerly resolved by `useFilteredMetaTree`, so this hasn't been needed
 
 #### FileSizeInput

package/src/components/README.zh-CN.md

@@ -190,6 +190,9 @@ import { TypedVariableInput } from '@nocobase/client-v2';
 <Form.Item name={['options', 'secure']} label={t('安全模式')} initialValue={true}>
   <TypedVariableInput types={['boolean']} namespaces={['$env']} />
 </Form.Item>
+
+// 注入自定义变量树（如工作流节点的上游输出，不在全局注册表里）
+<TypedVariableInput types={['string', 'number']} metaTree={workflowMetaTree} />
 ```
 
 主要属性：
@@ -197,6 +200,7 @@ import { TypedVariableInput } from '@nocobase/client-v2';
 - `types`：允许的常量类型。形态对齐 v1 `useTypedConstant`，可以传裸类型名 `['number', 'boolean']`，也可以传 `[type, editorProps]` 元组 `[['number', { min, max, step }]]` 把 props 透传给底层 antd 编辑器。默认 `['string', 'number', 'boolean', 'date']`。**即使只允许一种类型，「常量」入口也会展开二级菜单**（数字 / 逻辑值 / 日期 / 字符串）——跟 v1 一致，让用户能直观看到当前常量是什么类型
 - `namespaces`：限定变量 picker 可选的顶层命名空间（如 `['$env']`）。不传就用 `flowEngine.context` 里所有已注册命名空间
 - `extraNodes`：在命名空间过滤后追加几条静态变量节点
+- `metaTree`：**直接注入变量树**，取代读取全局 `flowEngine.context` 的 MetaTree。传了它就**忽略** `namespaces`/`extraNodes`，原样使用这棵树——用于不在全局注册表里的、上下文相关的变量源（典型如工作流节点的上游节点输出 `$jobsMapByNodeKey`）。树里 `children` 为函数（`() => Promise<MetaTreeNode[]>`）的节点会在用户展开 Cascader 时**按需懒加载**（复用 flow-engine 的 `loadMetaTreeChildren`）
 - `nullable`：是否暴露「空值」入口，默认 `true`。配合 `Form.Item.rules={[{ required: true }]}` 可以让用户能手动清空、但提交时会被校验拦截——跟 v1 的「空值 + required」组合一致
 - `delimiters`：变量 token 开闭分隔符，默认 `['{{', '}}']`，跟 `VariableInput` 一致
 - `value` / `onChange` / `placeholder` / `disabled` / `style` / `className`：标准受控字段属性
@@ -212,9 +216,10 @@ import { TypedVariableInput } from '@nocobase/client-v2';
 - **纯字面量字段**（用户不会想填变量）→ 直接用 antd `InputNumber` / `Select` / `DatePicker` / `Input`，省掉 Cascader 那一格的视觉开销
 - **纯变量字段**（用户不会想填字面量）→ 用 `EnvVariableInput`（`$env` 专用，带 password mask）或 `VariableInput`（更通用）
 
+支持的常量类型：`string` / `number` / `boolean` / `date` / `object`。其中 `object`（即 JSON）渲染为一个等宽字体的内联 textarea（默认两行、可拖拽拉伸），编辑时保留原始文本草稿、失焦（blur）时 `JSON.parse` 回写为对象；解析失败则在输入框**下方单独一行**显示原生 `JSON.parse` 的错误信息（如 `Expected property name or '}' in JSON at position …`，对齐 v1）且不回写。对齐 v1 `useTypedConstant` 的 object 形态（默认值 `{}`）。
+
 跳过的能力（v1 有但 v2 还没补）：
 
-- `object` 类型（JSON 编辑器）——v2 还没对应的「内联 JSON 编辑器 + Cascader 切换」组件，等真有需求再补
 - 异步 `loadChildren` 分支——大多数命名空间的 MetaTree 已经由 `useFilteredMetaTree` 提前展平，没遇到刚需
 
 #### FileSizeInput