@nocobase/client-v2 2.1.0-beta.37 → 2.1.0-beta.40

package/src/components/KeepAlive.tsx

@@ -0,0 +1,131 @@
+/**
+ * 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 { RouteContext } from '@ant-design/pro-layout';
+import _ from 'lodash';
+import React, { createContext, FC, memo, useContext, useRef } from 'react';
+import {
+  UNSAFE_DataRouterContext,
+  UNSAFE_DataRouterStateContext,
+  UNSAFE_LocationContext,
+  UNSAFE_RouteContext,
+} from 'react-router-dom';
+
+const KeepAliveContext = createContext(true);
+const hidden = { display: 'none' };
+
+export const KeepAliveProvider: FC<{ active: boolean; parentActive: boolean }> = memo(
+  ({ children, active, parentActive }) => {
+    const currentLocationContext = useContext(UNSAFE_LocationContext);
+    const currentRouteContext = useContext(UNSAFE_RouteContext);
+    const currentDataRouterContext = useContext(UNSAFE_DataRouterContext);
+    const currentDataRouterStateContext = useContext(UNSAFE_DataRouterStateContext);
+    const routeContextValue = useContext(RouteContext);
+
+    const prevLocationContextRef = useRef(currentLocationContext);
+    const prevRouteContextRef = useRef(currentRouteContext);
+    const prevDataRouterContextRef = useRef(currentDataRouterContext);
+    const prevDataRouterStateContextRef = useRef(currentDataRouterStateContext);
+    const prevRouteContextValueRef = useRef(routeContextValue);
+
+    if (active) {
+      prevDataRouterContextRef.current = currentDataRouterContext;
+      prevDataRouterStateContextRef.current = currentDataRouterStateContext;
+      prevRouteContextValueRef.current = routeContextValue;
+    }
+
+    if (
+      active &&
+      !_.isEqual(_.omit(prevLocationContextRef.current.location, 'key'), _.omit(currentLocationContext.location, 'key'))
+    ) {
+      prevLocationContextRef.current = currentLocationContext;
+    }
+
+    if (active && !_.isEqual(prevRouteContextRef.current, currentRouteContext)) {
+      prevRouteContextRef.current = currentRouteContext;
+    }
+
+    return (
+      <div style={active ? { height: '100%' } : hidden}>
+        <RouteContext.Provider value={prevRouteContextValueRef.current}>
+          <UNSAFE_DataRouterContext.Provider value={prevDataRouterContextRef.current}>
+            <UNSAFE_DataRouterStateContext.Provider value={prevDataRouterStateContextRef.current}>
+              <UNSAFE_LocationContext.Provider value={prevLocationContextRef.current}>
+                <UNSAFE_RouteContext.Provider value={prevRouteContextRef.current}>
+                  <KeepAliveContext.Provider value={parentActive === false ? false : active}>
+                    {children}
+                  </KeepAliveContext.Provider>
+                </UNSAFE_RouteContext.Provider>
+              </UNSAFE_LocationContext.Provider>
+            </UNSAFE_DataRouterStateContext.Provider>
+          </UNSAFE_DataRouterContext.Provider>
+        </RouteContext.Provider>
+      </div>
+    );
+  },
+);
+
+export const useKeepAlive = () => {
+  const active = useContext(KeepAliveContext);
+  return { active };
+};
+
+interface KeepAliveProps {
+  uid: string;
+  children: (uid: string) => React.ReactNode;
+}
+
+const MINIMUM_CACHED_PAGES = 5;
+const MAXIMUM_CACHED_PAGES = 15;
+
+const getMaxPageCount = () => {
+  const baseCount = MINIMUM_CACHED_PAGES;
+
+  try {
+    const memory = (navigator as any).deviceMemory;
+    if (memory) {
+      return Math.min(Math.max(baseCount, memory * 3), MAXIMUM_CACHED_PAGES);
+    }
+
+    const cores = navigator.hardwareConcurrency;
+    if (cores) {
+      return cores >= 8 ? MAXIMUM_CACHED_PAGES : cores >= 4 ? 7 : baseCount;
+    }
+
+    return baseCount;
+  } catch (e) {
+    return baseCount;
+  }
+};
+
+const MAX_RENDERED_PAGE_COUNT = getMaxPageCount();
+
+export const KeepAlive: FC<KeepAliveProps> = React.memo(({ children, uid }) => {
+  const { active } = useKeepAlive();
+  const renderedUidListRef = useRef<string[]>([]);
+
+  if (!renderedUidListRef.current.includes(uid)) {
+    renderedUidListRef.current.push(uid);
+    if (renderedUidListRef.current.length > MAX_RENDERED_PAGE_COUNT) {
+      renderedUidListRef.current = renderedUidListRef.current.slice(-MAX_RENDERED_PAGE_COUNT);
+    }
+  }
+
+  return (
+    <>
+      {renderedUidListRef.current.map((renderedUid) => (
+        <KeepAliveProvider active={renderedUid === uid} key={renderedUid} parentActive={active}>
+          {children(renderedUid)}
+        </KeepAliveProvider>
+      ))}
+    </>
+  );
+});
+
+KeepAlive.displayName = 'KeepAlive';

package/src/components/README.md

@@ -164,6 +164,7 @@ Key props:
 - `namespaces`: restrict the picker to specific top-level namespaces. Omit to expose every registered top-level property
 - `extraNodes`: static leaves appended after the namespace-filtered nodes. Use for variables that only make sense in the current page (e.g. `$resetLink`)
 - `converters`: override the default path ↔ string converters. `EnvVariableInput` uses this hook to lock its output to `$env`
+- `delimiters`: token pair wrapping the stored variable reference. Defaults to `['{{', '}}']` (Handlebars HTML-escaped). Pass `['{{{', '}}}']` for fields rendered as HTML where escaping would corrupt the variable value — e.g. the in-app message body
 - `value` / `onChange` / `placeholder` / `disabled`: standard controlled-input props
 
 Under the hood `VariableInput` wraps `VariableHybridInput` (inline pills), `VariableTextArea` wraps `TextAreaWithContextSelector` (textarea + variable button). Both share the same MetaTree.

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

@@ -164,6 +164,7 @@ import { VariableInput, VariableTextArea } from '@nocobase/client-v2';
 - `namespaces`：限定可选的顶层命名空间。不传就用 `flowEngine.context` 里全部已注册的
 - `extraNodes`：在命名空间过滤后追加几条静态变量（用于 `$resetLink` 这类只在当前页面有意义的局部变量）
 - `converters`：覆盖默认的 path ↔ string 转换器。`EnvVariableInput` 就是用这个钩子把输出锁定到 `$env`
+- `delimiters`：变量在存储字符串里使用的开闭分隔符，默认 `['{{', '}}']`（对应 Handlebars 的 HTML 转义形式）。若字段最终以 HTML 渲染、转义会破坏变量内容（如站内信正文），传 `['{{{', '}}}']` 走 Handlebars 的原样输出形式
 - `value` / `onChange` / `placeholder` / `disabled`：标准受控字段属性
 
 底层共用 `VariableHybridInput`（`VariableInput`）和 `TextAreaWithContextSelector`（`VariableTextArea`），用同一套 MetaTree 数据。

package/src/components/RouterBridge.tsx

@@ -7,11 +7,32 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-import { observable } from '@formily/reactive';
-import { useEffect, useMemo } from 'react';
-import { useLocation, useMatch, useMatches, useParams } from 'react-router-dom';
+import { useEffect } from 'react';
+import { useLocation, useMatches, useParams } from 'react-router-dom';
 import { Application } from '../Application';
 
+type LayoutMatchLike = {
+  id: string;
+  pathname: string;
+};
+
+type LayoutDefinitionLike = {
+  routeName: string;
+};
+
+export function findDeepestLayoutMatch(layouts: LayoutDefinitionLike[] = [], matches: LayoutMatchLike[] = []) {
+  const layoutRouteNames = new Set(layouts.map((layout) => layout.routeName));
+
+  for (let index = matches.length - 1; index >= 0; index -= 1) {
+    const match = matches[index];
+    if (layoutRouteNames.has(match.id)) {
+      return match;
+    }
+  }
+
+  return null;
+}
+
 export function useRouterSync(app: Application) {
   const params = useParams();
   const location = useLocation();
@@ -20,13 +41,16 @@ export function useRouterSync(app: Application) {
   useEffect(() => {
     const last = matches[matches.length - 1];
     if (!last) return;
+    const layoutMatch = findDeepestLayoutMatch(app.layoutManager?.listLayouts?.(), matches);
     engine.context['_observableCache']['route'] = {
       name: last.id,
       pathname: last.pathname,
       path: last.handle?.['path'] || null,
       params,
+      layoutRouteName: layoutMatch?.id,
+      layoutBasePathname: layoutMatch?.pathname,
     };
-  }, [engine.context, params, matches]);
+  }, [app, engine.context, params, matches]);
   useEffect(() => {
     engine.context['_observableCache']['location'] = location;
   }, [engine.context, location]);

package/src/components/__tests__/KeepAlive.test.tsx

@@ -0,0 +1,63 @@
+/**
+ * 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, { useEffect } from 'react';
+import { createMemoryRouter, Outlet, RouterProvider, useParams } from 'react-router-dom';
+import { describe, expect, it } from 'vitest';
+import { KeepAlive } from '../KeepAlive';
+
+describe('KeepAlive', () => {
+  it('keeps inactive outlet pages mounted while switching route params', async () => {
+    const events: string[] = [];
+
+    const Page = () => {
+      const { name } = useParams();
+      useEffect(() => {
+        events.push(`mount:${name}`);
+        return () => {
+          events.push(`unmount:${name}`);
+        };
+      }, [name]);
+
+      return <div>page {name}</div>;
+    };
+
+    const Layout = () => {
+      const { name } = useParams();
+      return <KeepAlive uid={name || ''}>{() => <Outlet />}</KeepAlive>;
+    };
+
+    const router = createMemoryRouter(
+      [
+        {
+          path: '/:name',
+          element: <Layout />,
+          children: [{ index: true, element: <Page /> }],
+        },
+      ],
+      {
+        initialEntries: ['/page-a'],
+      },
+    );
+
+    render(<RouterProvider router={router} />);
+
+    expect(await screen.findByText('page page-a')).toBeInTheDocument();
+
+    await router.navigate('/page-b');
+
+    expect(await screen.findByText('page page-b')).toBeInTheDocument();
+    expect(screen.getByText('page page-a')).toBeInTheDocument();
+
+    await waitFor(() => {
+      expect(events).toEqual(['mount:page-a', 'mount:page-b']);
+    });
+  });
+});

package/src/components/__tests__/RouterBridge.test.tsx

@@ -0,0 +1,27 @@
+/**
+ * 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 { describe, expect, it } from 'vitest';
+import { findDeepestLayoutMatch } from '../RouterBridge';
+
+describe('RouterBridge', () => {
+  it('uses the deepest matched layout route as layout base pathname', () => {
+    const match = findDeepestLayoutMatch(
+      [{ routeName: 'admin' }, { routeName: 'admin.settings.publicForms' }],
+      [
+        { id: 'admin', pathname: '/admin' },
+        { id: 'admin.settings', pathname: '/admin/settings' },
+        { id: 'admin.settings.publicForms', pathname: '/admin/settings/public-forms' },
+        { id: 'admin.settings.publicForms.page.view', pathname: '/admin/settings/public-forms/form-1/view/popup' },
+      ],
+    );
+
+    expect(match?.pathname).toBe('/admin/settings/public-forms');
+  });
+});

package/src/components/form/VariableInput.tsx

@@ -25,28 +25,75 @@ import { TextAreaWithContextSelector } from '../../flow/components/TextAreaWithC
  * stored values round-trip to a labelled pill instead of falling back to a
  * raw `{{…}}` literal.
  */
-const VARIABLE_EXPR_RE = /^\{\{\s*(.+?)\s*\}\}$/;
-
-export function parseVariablePath(value?: string): string[] | undefined {
-  if (typeof value !== 'string') return undefined;
-  const match = value.trim().match(VARIABLE_EXPR_RE);
-  if (!match) return undefined;
-  let pathString = match[1];
-  // Backwards-compat: accept the legacy `ctx.` prefix so values produced by
-  // pre-fix versions of the picker still resolve to a labelled pill.
-  if (pathString === 'ctx') return [];
-  if (pathString.startsWith('ctx.')) pathString = pathString.slice(4);
-  return pathString.split('.');
+
+/**
+ * Variable delimiters: opening + closing tokens. Default `['{{', '}}']`
+ * matches NocoBase server template convention (Handlebars HTML-escaped
+ * output). Pass `['{{{', '}}}']` to switch to Handlebars' raw/unescaped
+ * form — required for fields whose content is rendered as HTML (e.g.
+ * in-app message body) so the variable expansion bypasses HTML escaping.
+ *
+ * Restrict to literal-token pairs, since the regex builder escapes them
+ * verbatim.
+ */
+export type VariableDelimiters = readonly [string, string];
+
+const DEFAULT_DELIMITERS: VariableDelimiters = ['{{', '}}'];
+
+function escapeForRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
-export function formatVariablePath(meta?: MetaTreeNode): string | undefined {
-  const paths = meta?.paths || [];
-  if (paths.length === 0) return undefined;
-  // No inner spaces — matches the v1 storage shape exactly so round-trips
-  // through the API stay byte-stable.
-  return `{{${paths.join('.')}}}`;
+/**
+ * Factory: returns a `parseValueToPath` bound to the given delimiters.
+ * Anchored (`^…$`) — only treats the whole input as a single variable
+ * reference, matching the v1 single-line picker behaviour.
+ */
+export function makeParseVariablePath(delimiters: VariableDelimiters = DEFAULT_DELIMITERS) {
+  const [open, close] = delimiters;
+  const re = new RegExp(`^${escapeForRegExp(open)}\\s*(.+?)\\s*${escapeForRegExp(close)}$`);
+  return (value?: string): string[] | undefined => {
+    if (typeof value !== 'string') return undefined;
+    const match = value.trim().match(re);
+    if (!match) return undefined;
+    let pathString = match[1];
+    // Backwards-compat: accept the legacy `ctx.` prefix so values produced by
+    // pre-fix versions of the picker still resolve to a labelled pill.
+    if (pathString === 'ctx') return [];
+    if (pathString.startsWith('ctx.')) pathString = pathString.slice(4);
+    return pathString.split('.');
+  };
 }
 
+/**
+ * Factory: returns a `formatPathToValue` bound to the given delimiters.
+ * No inner spaces — matches the v1 storage shape exactly so round-trips
+ * through the API stay byte-stable.
+ */
+export function makeFormatVariablePath(delimiters: VariableDelimiters = DEFAULT_DELIMITERS) {
+  const [open, close] = delimiters;
+  return (meta?: MetaTreeNode): string | undefined => {
+    const paths = meta?.paths || [];
+    if (paths.length === 0) return undefined;
+    return `${open}${paths.join('.')}${close}`;
+  };
+}
+
+/**
+ * Factory: returns a global regex matching every occurrence of the
+ * variable token within a longer string. Used by `VariableHybridInput`
+ * to render embedded variables as pills.
+ */
+export function makeVariableRegExp(delimiters: VariableDelimiters = DEFAULT_DELIMITERS): RegExp {
+  const [open, close] = delimiters;
+  return new RegExp(`${escapeForRegExp(open)}\\s*([^{}]+?)\\s*${escapeForRegExp(close)}`, 'g');
+}
+
+// Default exports — `{{ ... }}` for the most common case. Kept named so
+// existing callers don't need to switch to the factory.
+export const parseVariablePath = makeParseVariablePath();
+export const formatVariablePath = makeFormatVariablePath();
+
 const META_TREE_CACHE_PREFIX = '@nocobase/client-v2:VariableInput:metaTree';
 
 /**
@@ -123,8 +170,22 @@ export interface VariableInputProps {
    * Override the converters used by the underlying `VariableHybridInput`.
    * Mostly useful when the caller wants to constrain `formatPathToValue` to a
    * specific namespace (see `EnvVariableInput` for that pattern).
+   *
+   * Takes precedence over `delimiters` when both are set on the same field
+   * (an explicit converter wins over the delimiter-derived one).
    */
   converters?: VariableHybridInputConverters;
+  /**
+   * Token pair wrapping variable references in the stored string. Defaults
+   * to `['{{', '}}']` — the standard NocoBase server-template form,
+   * HTML-escaped by Handlebars. Pass `['{{{', '}}}']` for fields rendered
+   * as HTML where escaping would corrupt the variable value (e.g. the
+   * in-app message body).
+   *
+   * Ignored when `converters` is also supplied — caller-provided converters
+   * win.
+   */
+  delimiters?: VariableDelimiters;
   className?: string;
   style?: React.CSSProperties;
 }
@@ -136,16 +197,24 @@ export interface VariableInputProps {
  * line of mixed literal+variable content is appropriate.
  */
 export function VariableInput(props: VariableInputProps) {
-  const { namespaces, extraNodes, converters, ...rest } = props;
+  const { namespaces, extraNodes, converters, delimiters, ...rest } = props;
   const metaTree = useFilteredMetaTree({ namespaces, extraNodes });
-  const mergedConverters = useMemo<VariableHybridInputConverters>(
-    () => ({
-      formatPathToValue: formatVariablePath,
-      parseValueToPath: parseVariablePath,
+  const mergedConverters = useMemo<VariableHybridInputConverters>(() => {
+    // Default delimiters → reuse the pre-built singletons.
+    if (!delimiters) {
+      return {
+        formatPathToValue: formatVariablePath,
+        parseValueToPath: parseVariablePath,
+        ...converters,
+      };
+    }
+    return {
+      formatPathToValue: makeFormatVariablePath(delimiters),
+      parseValueToPath: makeParseVariablePath(delimiters),
+      variableRegExp: makeVariableRegExp(delimiters),
       ...converters,
-    }),
-    [converters],
-  );
+    };
+  }, [converters, delimiters]);
   return <VariableHybridInput {...rest} converters={mergedConverters} metaTree={metaTree} />;
 }
 
@@ -161,9 +230,13 @@ export interface VariableTextAreaProps extends Omit<VariableInputProps, 'convert
  * is desirable (the server expands them at render time).
  */
 export function VariableTextArea(props: VariableTextAreaProps) {
-  const { namespaces, extraNodes, rows, maxRows, style, ...rest } = props;
+  const { namespaces, extraNodes, rows, maxRows, style, delimiters, ...rest } = props;
   const metaTree = useFilteredMetaTree({ namespaces, extraNodes });
   const metaTreeGetter = useMemo(() => () => metaTree, [metaTree]);
+  const formatPathToValue = useMemo(
+    () => (delimiters ? makeFormatVariablePath(delimiters) : formatVariablePath),
+    [delimiters],
+  );
   return (
     <TextAreaWithContextSelector
       {...rest}
@@ -171,7 +244,7 @@ export function VariableTextArea(props: VariableTextAreaProps) {
       maxRows={maxRows}
       style={style}
       metaTree={metaTreeGetter}
-      formatPathToValue={(meta) => formatVariablePath(meta) ?? ''}
+      formatPathToValue={(meta) => formatPathToValue(meta) ?? ''}
     />
   );
 }

package/src/components/form/__tests__/VariableInput.test.ts

@@ -0,0 +1,85 @@
+/**
+ * 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 { describe, expect, it } from 'vitest';
+import {
+  formatVariablePath,
+  makeFormatVariablePath,
+  makeParseVariablePath,
+  makeVariableRegExp,
+  parseVariablePath,
+} from '../VariableInput';
+
+describe('VariableInput delimiter helpers', () => {
+  describe('default delimiters {{ }}', () => {
+    it('formats meta nodes into `{{x.y}}` with no inner spaces', () => {
+      expect(formatVariablePath({ paths: ['$user', 'id'] } as any)).toBe('{{$user.id}}');
+    });
+
+    it('parses `{{x.y}}` into a path array', () => {
+      expect(parseVariablePath('{{ $user.id }}')).toEqual(['$user', 'id']);
+      expect(parseVariablePath('{{$user.id}}')).toEqual(['$user', 'id']);
+    });
+
+    it('strips a legacy `ctx.` prefix for backwards-compat', () => {
+      expect(parseVariablePath('{{ctx.$user.id}}')).toEqual(['$user', 'id']);
+      expect(parseVariablePath('{{ctx}}')).toEqual([]);
+    });
+
+    it('returns undefined for plain text', () => {
+      expect(parseVariablePath('hello world')).toBeUndefined();
+      expect(parseVariablePath('')).toBeUndefined();
+      expect(parseVariablePath(undefined)).toBeUndefined();
+    });
+  });
+
+  describe('triple-brace delimiters {{{ }}}', () => {
+    const format = makeFormatVariablePath(['{{{', '}}}']);
+    const parse = makeParseVariablePath(['{{{', '}}}']);
+
+    it('formats meta nodes into `{{{x.y}}}`', () => {
+      expect(format({ paths: ['$user', 'id'] } as any)).toBe('{{{$user.id}}}');
+    });
+
+    it('parses `{{{x.y}}}` into a path array', () => {
+      expect(parse('{{{$user.id}}}')).toEqual(['$user', 'id']);
+      expect(parse('{{{ $user.id }}}')).toEqual(['$user', 'id']);
+    });
+
+    it('does not match the double-brace form', () => {
+      expect(parse('{{$user.id}}')).toBeUndefined();
+    });
+  });
+
+  describe('makeVariableRegExp', () => {
+    it('matches every occurrence in a longer string under default delimiters', () => {
+      const re = makeVariableRegExp();
+      const matches = Array.from('hello {{ $user.id }} world {{ $env.X }}'.matchAll(re)).map((m) => m[1]);
+      expect(matches).toEqual(['$user.id', '$env.X']);
+    });
+
+    it('matches triple-brace occurrences when configured', () => {
+      const re = makeVariableRegExp(['{{{', '}}}']);
+      const matches = Array.from('hi {{{$user.id}}} :)'.matchAll(re)).map((m) => m[1]);
+      expect(matches).toEqual(['$user.id']);
+    });
+
+    it('does not match double-brace occurrences under triple-brace config', () => {
+      const re = makeVariableRegExp(['{{{', '}}}']);
+      const matches = Array.from('plain {{ x }} text'.matchAll(re));
+      expect(matches).toHaveLength(0);
+    });
+  });
+
+  it('handles empty paths consistently', () => {
+    expect(formatVariablePath({ paths: [] } as any)).toBeUndefined();
+    expect(formatVariablePath(undefined)).toBeUndefined();
+    expect(makeFormatVariablePath(['{{{', '}}}'])({ paths: [] } as any)).toBeUndefined();
+  });
+});

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

@@ -25,7 +25,15 @@ export interface CollectionFilterProps {
   t?: (key: string, options?: Record<string, any>) => string;
   /** Whitelist of root-level field names to expose. */
   filterableFieldNames?: string[];
-  /** Bypass the `filterableFieldNames` whitelist. */
+  /**
+   * Blacklist of root-level field names to drop. Mirrors v1's `nonfilterable: [...]` on `Filter.Action`. When both `filterableFieldNames` and this prop are supplied, both apply (final = whitelist ∩ ¬blacklist).
+   */
+  nonfilterableFieldNames?: string[];
+  /**
+   * Bypass the `filterableFieldNames` whitelist.
+   *
+   * Legacy escape hatch — prefer adjusting `filterableFieldNames` / `nonfilterableFieldNames` instead.
+   */
   noIgnore?: boolean;
   /** Override the trigger button's label. Defaults to `t('Filter')`, or the v1-style `t('{{count}} filter items', { count })` when conditions are present. */
   buttonText?: React.ReactNode;
@@ -50,6 +58,7 @@ export const CollectionFilter: FC<CollectionFilterProps> = (props) => {
     onChange,
     t = identity,
     filterableFieldNames,
+    nonfilterableFieldNames,
     noIgnore,
     buttonText,
     showCount = true,
@@ -63,6 +72,7 @@ export const CollectionFilter: FC<CollectionFilterProps> = (props) => {
   const filterAction = useFilterActionProps({
     collection,
     filterableFieldNames,
+    nonfilterableFieldNames,
     noIgnore,
     t,
     onApply: (filter: CompiledFilter, action: FilterApplyAction) => {

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

@@ -44,7 +44,15 @@ export interface CollectionFilterItemProps {
   collection: Collection;
   /** Whitelist of field names to expose; empty/undefined means all filterable fields. */
   filterableFieldNames?: string[];
-  /** Bypass the `filterableFieldNames` whitelist (matches the legacy FilterItem `noIgnore`). */
+  /**
+   * Blacklist of field names to drop. Mirrors v1's `nonfilterable: [...]` on `Filter.Action`. When both whitelist and blacklist are supplied, both apply (final = whitelist ∩ ¬blacklist).
+   */
+  nonfilterableFieldNames?: string[];
+  /**
+   * Bypass the `filterableFieldNames` whitelist (matches the legacy FilterItem `noIgnore`).
+   *
+   * Legacy escape hatch — prefer adjusting `filterableFieldNames` / `nonfilterableFieldNames` instead.
+   */
   noIgnore?: boolean;
   /** Translator; defaults to identity so callers can omit it. */
   t?: (key: string) => string;
@@ -84,10 +92,10 @@ const toCascaderOptions = (options: FilterOption[]): CascaderOption[] =>
  */
 export const CollectionFilterItem: FC<CollectionFilterItemProps> = observer(
   (props) => {
-    const { collection, filterableFieldNames, noIgnore = false, t = identity } = props;
+    const { collection, filterableFieldNames, nonfilterableFieldNames, noIgnore = false, t = identity } = props;
     const { path: leftValue, operator, value: rightValue } = props.value;
 
-    const options = useFilterOptions(collection, { filterableFieldNames, noIgnore, t });
+    const options = useFilterOptions(collection, { filterableFieldNames, nonfilterableFieldNames, noIgnore, t });
 
     const cascaderOptions = useMemo(() => toCascaderOptions(options), [options]);
 
@@ -164,7 +172,7 @@ export const CollectionFilterItem: FC<CollectionFilterItemProps> = observer(
  */
 export function createCollectionFilterItem(
   collection: Collection,
-  bound?: Pick<CollectionFilterItemProps, 'filterableFieldNames' | 'noIgnore' | 't'>,
+  bound?: Pick<CollectionFilterItemProps, 'filterableFieldNames' | 'nonfilterableFieldNames' | 'noIgnore' | 't'>,
 ) {
   const Component: FC<{ value: CollectionFilterItemValue }> = (props) => (
     <CollectionFilterItem {...bound} value={props.value} collection={collection} />