@nocobase/client-v2 2.2.0-beta.16 → 2.2.0-beta.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nocobase/client-v2",
-  "version": "2.2.0-beta.16",
+  "version": "2.2.0-beta.18",
   "license": "Apache-2.0",
   "main": "lib/index.js",
   "module": "es/index.mjs",
@@ -27,11 +27,11 @@
     "@formily/antd-v5": "1.2.3",
     "@formily/react": "^2.2.27",
     "@formily/shared": "^2.2.27",
-    "@nocobase/evaluators": "2.2.0-beta.16",
-    "@nocobase/flow-engine": "2.2.0-beta.16",
-    "@nocobase/sdk": "2.2.0-beta.16",
-    "@nocobase/shared": "2.2.0-beta.16",
-    "@nocobase/utils": "2.2.0-beta.16",
+    "@nocobase/evaluators": "2.2.0-beta.18",
+    "@nocobase/flow-engine": "2.2.0-beta.18",
+    "@nocobase/sdk": "2.2.0-beta.18",
+    "@nocobase/shared": "2.2.0-beta.18",
+    "@nocobase/utils": "2.2.0-beta.18",
     "ahooks": "^3.7.2",
     "antd": "5.24.2",
     "antd-style": "3.7.1",
@@ -48,5 +48,5 @@
     "react-i18next": "^11.15.1",
     "react-router-dom": "^6.30.1"
   },
-  "gitHead": "49d9bd2e21122eab9435f128375828b8c5bb4c07"
+  "gitHead": "b74c962f7d35aa12012d908d16bd74fe6ac20a3d"
 }

package/src/APIClient.ts

@@ -8,6 +8,68 @@
  */
 
 import { APIClient as APIClientSDK, hasHeaderValue } from '@nocobase/sdk';
+import type { NotificationInstance } from 'antd/es/notification/interface';
+import type { AxiosRequestConfig } from 'axios';
+import React from 'react';
+
+type ResponseMessage = string | { message?: unknown };
+
+interface APIClientApplication {
+  getName?: () => string | undefined;
+  context?: {
+    notification?: NotificationInstance;
+  };
+}
+
+interface NotificationError {
+  config?: AxiosRequestConfig & {
+    skipNotify?: boolean | ((error: unknown) => boolean);
+  };
+}
+
+const notificationCache = new Map<string, number>();
+
+function getMessageText(item: ResponseMessage): string {
+  if (typeof item === 'string') {
+    return item;
+  }
+  return typeof item?.message === 'string' ? item.message : '';
+}
+
+function deduplicateMessages(messages: ResponseMessage[]): ResponseMessage[] {
+  if (notificationCache.size > 10) {
+    notificationCache.clear();
+  }
+  const now = Date.now();
+  return messages.filter((item) => {
+    const message = getMessageText(item);
+    if (!message) {
+      return false;
+    }
+    const lastTime = notificationCache.get(message);
+    if (lastTime && now - lastTime < 500) {
+      return false;
+    }
+    notificationCache.set(message, now);
+    return true;
+  });
+}
+
+function notify(type: 'success' | 'error', messages: ResponseMessage[], instance?: NotificationInstance) {
+  if (!instance || messages.length === 0) {
+    return;
+  }
+  const filteredMessages = deduplicateMessages(messages);
+  if (filteredMessages.length === 0) {
+    return;
+  }
+  instance[type]({
+    message: filteredMessages.map((item, index) => {
+      const message = getMessageText(item);
+      return React.createElement('div', { key: `${index}_${message}` }, message);
+    }),
+  });
+}
 
 function offsetToTimeZone(offset: number) {
   const hours = Math.floor(Math.abs(offset));
@@ -23,6 +85,12 @@ function getCurrentTimezone() {
 }
 
 export class APIClient extends APIClientSDK {
+  app?: APIClientApplication;
+
+  get notification() {
+    return this.app?.context?.notification;
+  }
+
   getHostname() {
     if (process.env.API_BASE_URL) {
       try {
@@ -55,5 +123,29 @@ export class APIClient extends APIClientSDK {
       return config;
     });
     super.interceptors();
+    this.useNotificationMiddleware();
+  }
+
+  handleNotificationError(error: unknown) {
+    const notificationError = error as NotificationError;
+    const skipNotify = notificationError.config?.skipNotify;
+    if (skipNotify && (skipNotify === true || (typeof skipNotify === 'function' && skipNotify(error)))) {
+      throw error;
+    }
+    const messages = this.toErrMessages(error);
+    if (Array.isArray(messages)) {
+      notify('error', messages, this.notification);
+    }
+    throw error;
+  }
+
+  useNotificationMiddleware() {
+    this.axios.interceptors.response.use((response) => {
+      const messages = response.data?.messages;
+      if (Array.isArray(messages)) {
+        notify('success', messages, this.notification);
+      }
+      return response;
+    }, this.handleNotificationError.bind(this));
   }
 }

package/src/Application.tsx

@@ -45,7 +45,7 @@ export class Application extends BaseApplication<
   public hasLoadError = false;
 
   protected createApiClient(options: ApplicationOptions) {
-    return new APIClient({
+    const apiClient = new APIClient({
       // Cross-origin API deployments rely on cookies for auth (e.g. permanent file
       // URLs); trust is enforced server-side via the CORS origin whitelist and the
       // CSRF middleware, not by omitting credentials.
@@ -53,6 +53,8 @@ export class Application extends BaseApplication<
       ...options.apiClient,
       appName: options.name || getSubAppName(options.publicPath),
     });
+    apiClient.app = this;
+    return apiClient;
   }
 
   protected configureRuntimeAdapters() {

package/src/__tests__/APIClient.test.tsx

@@ -0,0 +1,58 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import { APIClient } from '@nocobase/client-v2';
+import type { NotificationInstance } from 'antd/es/notification/interface';
+import MockAdapter from 'axios-mock-adapter';
+import React from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+
+function createAPIClient() {
+  const notification = {
+    error: vi.fn(),
+    success: vi.fn(),
+  } as unknown as NotificationInstance;
+  const apiClient = new APIClient();
+  apiClient.app = { context: { notification } };
+  const apiMock = new MockAdapter(apiClient.axios);
+  return { apiClient, apiMock, notification };
+}
+
+describe('APIClient response notifications', () => {
+  it('shows error messages returned by failed requests', async () => {
+    const { apiClient, apiMock, notification } = createAPIClient();
+    apiMock.onPost('/posts:create').reply(400, { errors: [{ message: 'Request rejected by workflow' }] });
+
+    await expect(apiClient.request({ url: '/posts:create', method: 'post' })).rejects.toBeDefined();
+
+    expect(notification.error).toHaveBeenCalledOnce();
+    const [{ message }] = vi.mocked(notification.error).mock.calls[0];
+    expect(renderToStaticMarkup(<>{message}</>)).toContain('Request rejected by workflow');
+  });
+
+  it('does not show errors when skipNotify is enabled', async () => {
+    const { apiClient, apiMock, notification } = createAPIClient();
+    apiMock.onGet('/health').reply(500, { errors: [{ message: 'Health check failed' }] });
+
+    await expect(apiClient.request({ url: '/health', skipNotify: true })).rejects.toBeDefined();
+
+    expect(notification.error).not.toHaveBeenCalled();
+  });
+
+  it('shows messages returned by successful requests', async () => {
+    const { apiClient, apiMock, notification } = createAPIClient();
+    apiMock.onPost('/posts:create').reply(200, { messages: [{ message: 'Created successfully' }] });
+
+    await apiClient.request({ url: '/posts:create', method: 'post' });
+
+    expect(notification.success).toHaveBeenCalledOnce();
+    const [{ message }] = vi.mocked(notification.success).mock.calls[0];
+    expect(renderToStaticMarkup(<>{message}</>)).toContain('Created successfully');
+  });
+});

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

@@ -7,10 +7,17 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-import { ACLRolesCheckProvider, createMockClient, Plugin } from '@nocobase/client-v2';
-import { render, screen, waitFor, fireEvent } from '@testing-library/react';
+import {
+  ACLRolesCheckProvider,
+  createMockClient,
+  NocoBaseDesktopRouteType,
+  type NocoBaseDesktopRoute,
+  Plugin,
+} from '@nocobase/client-v2';
+import { act, render, screen, waitFor, fireEvent } from '@testing-library/react';
 import React from 'react';
 import { message } from 'antd';
+import { vi } from 'vitest';
 import { AdminSettingsLayoutModel as ClientV2AdminSettingsLayoutModel } from '../settings-center';
 import { AdminSettingsLayoutModel as ClientV1AdminSettingsLayoutModel } from '../../../client/src/pm/AdminSettingsLayoutModel';
 import { NocoBaseBuildInPlugin } from '../nocobase-buildin-plugin';
@@ -46,9 +53,15 @@ const mockAdminRuntime = (
     snippets?: string[];
     pmList?: any[];
     systemSettings?: Record<string, any>;
+    desktopRoutes?: NocoBaseDesktopRoute[];
   } = {},
 ) => {
-  const { snippets = ['pm', 'pm.system-settings.system-settings'], pmList = [], systemSettings = {} } = options;
+  const {
+    snippets = ['pm', 'pm.system-settings.system-settings'],
+    pmList = [],
+    systemSettings = {},
+    desktopRoutes = [],
+  } = options;
 
   app.dataSourceManager.getCollection = ((name: string, collectionName: string) => {
     if (name === 'main' && collectionName === 'attachments') {
@@ -92,7 +105,7 @@ const mockAdminRuntime = (
     },
   });
   app.apiMock.onGet('/desktopRoutes:listAccessible').reply(200, {
-    data: [],
+    data: desktopRoutes,
   });
   app.apiMock.onGet('systemSettings:get').reply(200, {
     data: {
@@ -243,6 +256,39 @@ describe('settings center', () => {
     expect(await screen.findByText('Demo plugin')).toBeInTheDocument();
   });
 
+  it('should redirect to the first accessible page when the role cannot access settings', async () => {
+    const app = createMockClient({
+      plugins: [NocoBaseBuildInPlugin, TestAclPlugin],
+      router: { type: 'memory', initialEntries: ['/admin/settings/system-settings'] },
+    });
+    mockAdminRuntime(app, {
+      snippets: ['!pm', '!pm.system-settings.system-settings'],
+      desktopRoutes: [
+        {
+          id: 1,
+          schemaUid: 'first-accessible-page',
+          title: 'First accessible page',
+          type: NocoBaseDesktopRouteType.flowPage,
+        },
+        {
+          id: 2,
+          schemaUid: 'second-accessible-page',
+          title: 'Second accessible page',
+          type: NocoBaseDesktopRouteType.flowPage,
+        },
+      ],
+    });
+
+    await renderApp(app);
+    await waitForGetRequests(app, ['/auth:check', 'roles:check', '/desktopRoutes:listAccessible']);
+
+    await waitFor(() => {
+      expect(app.router.state.location.pathname).toBe('/admin/first-accessible-page');
+    });
+    expect(app.router.state.historyAction).toBe('REPLACE');
+    expect(screen.queryByText('Current settings page is unavailable')).not.toBeInTheDocument();
+  });
+
   it('should hide plugin-manager menu item when pm snippet is missing', async () => {
     const app = createMockClient({
       plugins: [NocoBaseBuildInPlugin, TestAclPlugin],
@@ -264,12 +310,23 @@ describe('settings center', () => {
       plugins: [NocoBaseBuildInPlugin, TestAclPlugin],
       router: { type: 'memory', initialEntries: ['/admin/settings/unknown'] },
     });
-    mockAdminRuntime(app);
+    mockAdminRuntime(app, {
+      snippets: ['!pm', '!pm.system-settings.system-settings'],
+      desktopRoutes: [
+        {
+          id: 1,
+          schemaUid: 'first-accessible-page',
+          title: 'First accessible page',
+          type: NocoBaseDesktopRouteType.flowPage,
+        },
+      ],
+    });
 
     await renderApp(app);
     await waitForGetRequests(app, ['/auth:check', 'roles:check']);
 
     expect(await screen.findByText('Current settings page is unavailable')).toBeInTheDocument();
+    expect(app.router.state.location.pathname).toBe('/admin/settings/unknown');
   });
 
   it('should allow direct access to hidden page without showing menu entry', async () => {
@@ -290,13 +347,23 @@ describe('settings center', () => {
       plugins: [NocoBaseBuildInPlugin, TestAclPlugin, HiddenSettingsPlugin],
       router: { type: 'memory', initialEntries: ['/admin/settings/hidden-demo'] },
     });
-    mockAdminRuntime(app);
+    mockAdminRuntime(app, {
+      desktopRoutes: [
+        {
+          id: 1,
+          schemaUid: 'first-accessible-page',
+          title: 'First accessible page',
+          type: NocoBaseDesktopRouteType.flowPage,
+        },
+      ],
+    });
 
     await renderApp(app);
     await waitForGetRequests(app, ['/auth:check', 'roles:check']);
 
     expect(await screen.findByText('Hidden settings page')).toBeInTheDocument();
     expect(screen.queryByRole('menuitem', { name: 'Hidden demo' })).not.toBeInTheDocument();
+    expect(app.router.state.location.pathname).toBe('/admin/settings/hidden-demo');
   });
 
   it('should show route empty state when direct access page has no permission', async () => {
@@ -319,6 +386,14 @@ describe('settings center', () => {
     });
     mockAdminRuntime(app, {
       snippets: ['pm', 'pm.system-settings.system-settings', '!pm.secure-demo.index'],
+      desktopRoutes: [
+        {
+          id: 1,
+          schemaUid: 'first-accessible-page',
+          title: 'First accessible page',
+          type: NocoBaseDesktopRouteType.flowPage,
+        },
+      ],
     });
 
     await renderApp(app);
@@ -326,6 +401,195 @@ describe('settings center', () => {
 
     expect(await screen.findByText('Current settings page is unavailable')).toBeInTheDocument();
     expect(screen.queryByText('Secure settings page')).not.toBeInTheDocument();
+    expect(app.router.state.location.pathname).toBe('/admin/settings/secure-demo');
+  });
+
+  it('should redirect a denied settings tab to the first accessible tab', async () => {
+    const renderDeniedTab = vi.fn(() => <div>Denied tab content</div>);
+
+    class ProtectedSettingsTabsPlugin extends Plugin {
+      async load() {
+        this.pluginSettingsManager.addMenuItem({ key: 'protected-tabs', title: 'Protected tabs' });
+        this.pluginSettingsManager.addPageTabItem({
+          menuKey: 'protected-tabs',
+          key: 'a-second',
+          title: 'Second accessible tab',
+          aclSnippet: 'pm.protected-tabs.second',
+          sort: 20,
+          Component: () => <div>Second accessible tab content</div>,
+        });
+        this.pluginSettingsManager.addPageTabItem({
+          menuKey: 'protected-tabs',
+          key: 'z-first',
+          title: 'First accessible tab',
+          aclSnippet: 'pm.protected-tabs.first',
+          sort: 10,
+          Component: () => <div>First accessible tab content</div>,
+        });
+        this.pluginSettingsManager.addPageTabItem({
+          menuKey: 'protected-tabs',
+          key: 'denied',
+          title: 'Denied tab',
+          aclSnippet: 'pm.protected-tabs.denied',
+          sort: 30,
+          Component: renderDeniedTab,
+        });
+      }
+    }
+
+    const app = createMockClient({
+      plugins: [NocoBaseBuildInPlugin, TestAclPlugin, ProtectedSettingsTabsPlugin],
+      router: { type: 'memory', initialEntries: ['/admin/settings/protected-tabs/denied'] },
+    });
+    mockAdminRuntime(app, {
+      snippets: ['pm', '!pm.protected-tabs.denied'],
+    });
+
+    await renderApp(app);
+    await waitForGetRequests(app, ['/auth:check', 'roles:check']);
+
+    await waitFor(() => {
+      expect(app.router.router.state.location.pathname).toBe('/admin/settings/protected-tabs/z-first');
+    });
+    expect(app.router.router.state.historyAction).toBe('REPLACE');
+    expect(await screen.findByText('First accessible tab content')).toBeInTheDocument();
+    expect(screen.queryByText('Denied tab content')).not.toBeInTheDocument();
+    expect(renderDeniedTab).not.toHaveBeenCalled();
+
+    await act(async () => {
+      await app.router.router.navigate('/admin/settings/protected-tabs/a-second');
+    });
+
+    expect(await screen.findByText('Second accessible tab content')).toBeInTheDocument();
+    expect(app.router.router.state.location.pathname).toBe('/admin/settings/protected-tabs/a-second');
+  });
+
+  it('should skip an accessible dynamic tab when its route params cannot be resolved', async () => {
+    class DynamicSettingsTabsPlugin extends Plugin {
+      async load() {
+        this.pluginSettingsManager.addMenuItem({ key: 'dynamic-tabs', title: 'Dynamic tabs' });
+        this.pluginSettingsManager.addPageTabItem({
+          menuKey: 'dynamic-tabs',
+          key: ':name',
+          title: 'Dynamic tab',
+          aclSnippet: 'pm.dynamic-tabs.dynamic',
+          sort: 1,
+          Component: () => <div>Dynamic tab content</div>,
+        });
+        this.pluginSettingsManager.addPageTabItem({
+          menuKey: 'dynamic-tabs',
+          key: 'fallback',
+          title: 'Static fallback tab',
+          aclSnippet: 'pm.dynamic-tabs.fallback',
+          sort: 2,
+          Component: () => <div>Static fallback tab content</div>,
+        });
+        this.pluginSettingsManager.addPageTabItem({
+          menuKey: 'dynamic-tabs',
+          key: 'denied',
+          title: 'Denied tab',
+          aclSnippet: 'pm.dynamic-tabs.denied',
+          sort: 3,
+          Component: () => <div>Denied dynamic tab content</div>,
+        });
+      }
+    }
+
+    const app = createMockClient({
+      plugins: [NocoBaseBuildInPlugin, TestAclPlugin, DynamicSettingsTabsPlugin],
+      router: { type: 'memory', initialEntries: ['/admin/settings/dynamic-tabs/denied'] },
+    });
+    mockAdminRuntime(app, {
+      snippets: ['pm', '!pm.dynamic-tabs.denied'],
+    });
+
+    await renderApp(app);
+    await waitForGetRequests(app, ['/auth:check', 'roles:check']);
+
+    await waitFor(() => {
+      expect(app.router.router.state.location.pathname).toBe('/admin/settings/dynamic-tabs/fallback');
+    });
+    expect(await screen.findByText('Static fallback tab content')).toBeInTheDocument();
+  });
+
+  it('should preserve resolved route params when redirecting between dynamic tabs', async () => {
+    class DynamicSiblingTabsPlugin extends Plugin {
+      async load() {
+        this.pluginSettingsManager.addMenuItem({ key: 'dynamic-siblings', title: 'Dynamic sibling tabs' });
+        this.pluginSettingsManager.addPageTabItem({
+          menuKey: 'dynamic-siblings',
+          key: ':name/channels',
+          title: 'Dynamic channels tab',
+          aclSnippet: 'pm.dynamic-siblings.channels',
+          sort: 1,
+          Component: () => <div>Dynamic channels tab content</div>,
+        });
+        this.pluginSettingsManager.addPageTabItem({
+          menuKey: 'dynamic-siblings',
+          key: ':name/logs',
+          title: 'Dynamic logs tab',
+          aclSnippet: 'pm.dynamic-siblings.logs',
+          sort: 2,
+          Component: () => <div>Dynamic logs tab content</div>,
+        });
+      }
+    }
+
+    const app = createMockClient({
+      plugins: [NocoBaseBuildInPlugin, TestAclPlugin, DynamicSiblingTabsPlugin],
+      router: { type: 'memory', initialEntries: ['/admin/settings/dynamic-siblings/email:primary/logs'] },
+    });
+    mockAdminRuntime(app, {
+      snippets: ['pm', '!pm.dynamic-siblings.logs'],
+    });
+
+    await renderApp(app);
+    await waitForGetRequests(app, ['/auth:check', 'roles:check']);
+
+    await waitFor(() => {
+      expect(app.router.router.state.location.pathname).toBe('/admin/settings/dynamic-siblings/email:primary/channels');
+    });
+    expect(await screen.findByText('Dynamic channels tab content')).toBeInTheDocument();
+  });
+
+  it('should resolve hyphenated route param names when redirecting between dynamic tabs', async () => {
+    class HyphenatedParamTabsPlugin extends Plugin {
+      async load() {
+        this.pluginSettingsManager.addMenuItem({ key: 'hyphenated-params', title: 'Hyphenated param tabs' });
+        this.pluginSettingsManager.addPageTabItem({
+          menuKey: 'hyphenated-params',
+          key: ':data-source/channels',
+          title: 'Hyphenated channels tab',
+          aclSnippet: 'pm.hyphenated-params.channels',
+          sort: 1,
+          Component: () => <div>Hyphenated channels tab content</div>,
+        });
+        this.pluginSettingsManager.addPageTabItem({
+          menuKey: 'hyphenated-params',
+          key: ':data-source/logs',
+          title: 'Hyphenated logs tab',
+          aclSnippet: 'pm.hyphenated-params.logs',
+          sort: 2,
+          Component: () => <div>Hyphenated logs tab content</div>,
+        });
+      }
+    }
+
+    const app = createMockClient({
+      plugins: [NocoBaseBuildInPlugin, TestAclPlugin, HyphenatedParamTabsPlugin],
+      router: { type: 'memory', initialEntries: ['/admin/settings/hyphenated-params/email/logs'] },
+    });
+    mockAdminRuntime(app, {
+      snippets: ['pm', '!pm.hyphenated-params.logs'],
+    });
+
+    await renderApp(app);
+    await waitForGetRequests(app, ['/auth:check', 'roles:check']);
+
+    await waitFor(() => {
+      expect(app.router.router.state.location.pathname).toBe('/admin/settings/hyphenated-params/email/channels');
+    });
+    expect(await screen.findByText('Hyphenated channels tab content')).toBeInTheDocument();
   });
 
   it('should keep menu visible when menu acl is denied but child page is visible', async () => {

package/src/acl/ACLProvider.tsx

@@ -11,6 +11,7 @@ import { observable } from '@formily/reactive';
 import React, { useRef } from 'react';
 import { createContext, useCallback, useContext, useEffect, useMemo, useState, type FC } from 'react';
 import { useLocation } from 'react-router-dom';
+import { writeFlowSettingsPreference } from '../flow/admin-shell/admin-layout/flowSettingsPreference';
 import { useApp } from '../hooks/useApp';
 import { createAclSnippetAllow } from './createAclSnippetAllow';
 
@@ -118,6 +119,7 @@ export const ACLRolesCheckProvider: FC = ({ children }) => {
       }
 
       if (!createAclSnippetAllow(nextData?.snippets || [], !!nextData?.allowAll)('ui.*')) {
+        writeFlowSettingsPreference(false);
         await app.flowEngine.flowSettings.disable();
       }
     } catch (error) {

package/src/acl/__tests__/ACLProvider.test.tsx

@@ -0,0 +1,92 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import { render, screen, waitFor } from '@testing-library/react';
+import React from 'react';
+import { MemoryRouter } from 'react-router-dom';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  FLOW_SETTINGS_PREFERENCE_STORAGE_KEY,
+  writeFlowSettingsPreference,
+} from '../../flow/admin-shell/admin-layout/flowSettingsPreference';
+import { ACLRolesCheckProvider } from '../ACLProvider';
+
+const mocks = vi.hoisted(() => ({
+  app: undefined as unknown,
+}));
+
+vi.mock('../../hooks/useApp', () => ({
+  useApp: () => mocks.app,
+}));
+
+describe('ACLRolesCheckProvider', () => {
+  beforeEach(() => {
+    window.localStorage.removeItem(FLOW_SETTINGS_PREFERENCE_STORAGE_KEY);
+  });
+
+  it('exits UI editing mode when the current role cannot configure pages', async () => {
+    const disable = vi.fn(async () => undefined);
+    const setRole = vi.fn();
+    const aclContext: Record<string, unknown> = {};
+    const appContext = {
+      acl: undefined,
+      defineProperty(name: string, descriptor: PropertyDescriptor) {
+        Object.defineProperty(this, name, descriptor);
+      },
+      ...aclContext,
+    };
+
+    mocks.app = {
+      apiClient: {
+        auth: {
+          role: 'member',
+          setRole,
+        },
+        request: vi.fn(async () => ({
+          data: {
+            data: {
+              role: 'viewer',
+              snippets: [],
+            },
+            meta: {},
+          },
+        })),
+      },
+      context: appContext,
+      flowEngine: {
+        flowSettings: {
+          disable,
+        },
+      },
+      pluginSettingsManager: {
+        setAclSnippets: vi.fn(),
+      },
+      renderComponent: () => <div>Loading</div>,
+      router: {
+        isSkippedAuthCheckRoute: () => false,
+      },
+    };
+    writeFlowSettingsPreference(true);
+
+    render(
+      <MemoryRouter initialEntries={['/admin']}>
+        <ACLRolesCheckProvider>
+          <div>Page content</div>
+        </ACLRolesCheckProvider>
+      </MemoryRouter>,
+    );
+
+    expect(await screen.findByText('Page content')).toBeInTheDocument();
+    await waitFor(() => {
+      expect(disable).toHaveBeenCalledTimes(1);
+    });
+    expect(window.localStorage.getItem(FLOW_SETTINGS_PREFERENCE_STORAGE_KEY)).toBe('0');
+    expect(setRole).toHaveBeenCalledWith('viewer');
+  });
+});

package/src/components/form/filter/CollectionFilterItem.tsx

@@ -130,8 +130,10 @@ export const CollectionFilterItem: FC<CollectionFilterItemProps> = observer(
       [operatorOptions, operator],
     );
 
-    const handleFieldChange = (next: (string | number)[]) => {
-      const path = next.map(String);
+    const handleFieldChange = (next?: (string | number)[]) => {
+      // rc-cascader emits `undefined` when its clear icon is clicked in single-select mode, despite its public type
+      // declaring an array. Treat that runtime value as an empty path so clearing the field also resets the row.
+      const path = (next ?? []).map(String);
       props.value.path = path.join('.');
       const leaf = findOptionByPath(options, path);
       props.value.operator = leaf?.operators?.[0]?.value || '';