@nocobase/client-v2 2.1.0-alpha.40 → 2.1.0-alpha.45

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

@@ -0,0 +1,111 @@
+/**
+ * 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 { FilterOutlined } from '@ant-design/icons';
+import type { Collection } from '@nocobase/flow-engine';
+import { Button, type ButtonProps, Popover, type PopoverProps } from 'antd';
+import React, { FC, useState } from 'react';
+import { FilterContent } from '../../../flow/components/filter';
+import { CompiledFilter, FilterApplyAction, useFilterActionProps } from './useFilterActionProps';
+
+const identity = (s: string) => s;
+
+export interface CollectionFilterProps {
+  /** Collection whose fields drive the filter row's field picker. */
+  collection: Collection | undefined;
+  /** Called on Submit or Reset with the compiled NocoBase filter param (`undefined` when cleared). */
+  onChange: (filter: CompiledFilter) => void;
+  /** Translator. Defaults to identity. */
+  t?: (key: string, options?: Record<string, any>) => string;
+  /** Whitelist of root-level field names to expose. */
+  filterableFieldNames?: string[];
+  /**
+   * 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;
+  /** Swap the default `t('Filter')` label for v1's `t('{{count}} filter items', { count })` when conditions are present. Defaults to `true`. */
+  showCount?: boolean;
+  /** Pass-through props for the antd `<Popover>`. */
+  popoverProps?: Omit<PopoverProps, 'open' | 'onOpenChange' | 'content' | 'children'>;
+  /** Pass-through props for the trigger `<Button>`. */
+  buttonProps?: Omit<ButtonProps, 'icon' | 'type' | 'children' | 'onClick'>;
+  /** Min-width applied to the popover body. Defaults to `520`. */
+  popoverMinWidth?: number;
+}
+
+/**
+ * Filter button bound to a collection. Renders an antd `<Popover>` over a `<Button>`; the popover hosts a multi-condition filter form (field picker, operator, value). Submit dismisses the popover and emits the compiled filter via `onChange`; Reset keeps the popover open and emits `undefined`.
+ *
+ * Pair with `<ExtendCollectionsProvider>` when the target collection is client-only (e.g. a `schema-only` server collection that isn't auto-published to the v2 data source).
+ */
+export const CollectionFilter: FC<CollectionFilterProps> = (props) => {
+  const {
+    collection,
+    onChange,
+    t = identity,
+    filterableFieldNames,
+    nonfilterableFieldNames,
+    noIgnore,
+    buttonText,
+    showCount = true,
+    popoverProps,
+    buttonProps,
+    popoverMinWidth = 520,
+  } = props;
+
+  const [open, setOpen] = useState(false);
+
+  const filterAction = useFilterActionProps({
+    collection,
+    filterableFieldNames,
+    nonfilterableFieldNames,
+    noIgnore,
+    t,
+    onApply: (filter: CompiledFilter, action: FilterApplyAction) => {
+      onChange(filter);
+      if (action === 'submit') setOpen(false);
+    },
+  });
+
+  // Matches v1's `Filter.Action`: when at least one condition is set, the button label switches to the count-aware string (`"N 个筛选项"` in zh-CN). The button itself stays in the default (white) style — v1 never flipped it to `type='primary'`.
+  const label =
+    buttonText ??
+    (showCount && filterAction.conditionCount > 0
+      ? t('{{count}} filter items', { count: filterAction.conditionCount })
+      : t('Filter'));
+
+  return (
+    <Popover
+      trigger="click"
+      placement="bottomLeft"
+      {...popoverProps}
+      open={open}
+      onOpenChange={setOpen}
+      content={
+        <div style={{ minWidth: popoverMinWidth }}>
+          <FilterContent value={filterAction.value} ctx={filterAction.ctx} FilterItem={filterAction.FilterItem} />
+        </div>
+      }
+    >
+      <Button icon={<FilterOutlined />} disabled={!collection} {...buttonProps}>
+        {label}
+      </Button>
+    </Popover>
+  );
+};
+
+export default CollectionFilter;

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

@@ -0,0 +1,184 @@
+/**
+ * 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 { css } from '@emotion/css';
+import { Collection, observer } from '@nocobase/flow-engine';
+import { Cascader, Select, Space } from 'antd';
+import React, { FC, useMemo } from 'react';
+import { FilterOption, useFilterOptions } from '../../../flow/components/filter/useFilterOptions';
+import { FilterValueInput } from './FilterValueInput';
+
+/**
+ * Lift the Cascader sub-menu height so a target collection with many fields (e.g. `users` → id / nickname / username / email / phone / password / createdAt / updatedAt / roles / createdBy / updatedBy) doesn't get truncated below the default antd menu viewport.
+ */
+const cascaderPopupClass = css`
+  .ant-cascader-menu {
+    height: fit-content;
+    max-height: 50vh;
+  }
+`;
+
+export interface CollectionFilterItemValue {
+  path: string;
+  operator: string;
+  /** Operator-dependent — string for default ops, descriptor for $date*, etc. */
+  value: any;
+}
+
+type CascaderOption = {
+  value: string;
+  label: string;
+  children?: CascaderOption[];
+};
+
+export interface CollectionFilterItemProps {
+  /** Reactive filter row managed by the parent `FilterContainer`. */
+  value: CollectionFilterItemValue;
+  /** Target collection whose fields populate the field selector. */
+  collection: Collection;
+  /** Whitelist of field names to expose; empty/undefined means all filterable fields. */
+  filterableFieldNames?: string[];
+  /**
+   * 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;
+}
+
+const identity = (s: string) => s;
+
+/**
+ * Walk a tree of field options by name path, returning the leaf option (or undefined when the path doesn't resolve). Used to look up operators for the currently selected field.
+ */
+const findOptionByPath = (options: FilterOption[], path: string[]): FilterOption | undefined => {
+  if (!path.length) return undefined;
+  const [head, ...rest] = path;
+  const match = options.find((option) => option.name === head);
+  if (!match) return undefined;
+  if (!rest.length) return match;
+  return findOptionByPath(match.children || [], rest);
+};
+
+/**
+ * Convert the field-option tree (as produced by `useFilterOptions`) into antd `Cascader`'s expected `{ value, label, children }` shape. With `changeOnSelect={false}` (see the render below), antd already requires selection at a leaf — we don't need to mark association parents as `disabled`, and doing so would also block `expandTrigger="hover"` from descending into them.
+ */
+const toCascaderOptions = (options: FilterOption[]): CascaderOption[] =>
+  options.map((option) => {
+    const children = option.children?.length ? toCascaderOptions(option.children) : undefined;
+    return {
+      value: option.name,
+      label: option.title,
+      children,
+    };
+  });
+
+/**
+ * Filter row bound directly to a `Collection`, with no `FlowModel` dependency. Use this from settings pages or other surfaces that need a filter UI but don't have (and shouldn't synthesise) a block model just to satisfy `FilterItem`. Pair with `FilterContainer` via either an inline wrapper or `createCollectionFilterItem(collection)`.
+ *
+ * The field selector is an antd `Cascader`, mirroring v1's `Filter.Action` so association fields (belongsTo / m2o / etc.) can be drilled into — picking `user.username` is a first-class action. The value renderer is delegated to `FilterValueInput`, which dispatches to interface-specific controls (the smart date picker for `$date*` operators, tag-mode Select for array/enum, etc.) the same way v1's `DynamicComponent` did.
+ */
+export const CollectionFilterItem: FC<CollectionFilterItemProps> = observer(
+  (props) => {
+    const { collection, filterableFieldNames, nonfilterableFieldNames, noIgnore = false, t = identity } = props;
+    const { path: leftValue, operator, value: rightValue } = props.value;
+
+    const options = useFilterOptions(collection, { filterableFieldNames, nonfilterableFieldNames, noIgnore, t });
+
+    const cascaderOptions = useMemo(() => toCascaderOptions(options), [options]);
+
+    const fieldPath = useMemo(() => (leftValue ? leftValue.split('.') : []), [leftValue]);
+
+    const selectedField = useMemo(() => findOptionByPath(options, fieldPath), [options, fieldPath]);
+
+    const operatorOptions = useMemo(() => selectedField?.operators || [], [selectedField]);
+
+    const selectedOperator = useMemo(
+      () => operatorOptions.find((op) => op.value === operator),
+      [operatorOptions, operator],
+    );
+
+    const handleFieldChange = (next: (string | number)[]) => {
+      const path = next.map(String);
+      props.value.path = path.join('.');
+      const leaf = findOptionByPath(options, path);
+      props.value.operator = leaf?.operators?.[0]?.value || '';
+      // The value's shape is operator-dependent (e.g. string for `$eq`, `{ type, number, unit }` for `$dateInPast`); reset on every field change so stale shapes don't leak across interfaces.
+      props.value.value = undefined;
+    };
+    const handleOperatorChange = (next: string) => {
+      props.value.operator = next;
+      // Same rationale as above — switching from `$eq` (string) to `$dateOn` (date descriptor) makes the previous value structurally incompatible. v1 handled this by remounting the DynamicComponent on operator change; we explicitly clear.
+      props.value.value = undefined;
+    };
+    const handleValueChange = (next: any) => {
+      props.value.value = next;
+    };
+
+    // Widths mirror the long-standing `FilterItem` row (200 / 120) so a settings page mixing CollectionFilterItem and FilterContainer doesn't visually drift from existing block-bound filter rows.
+    return (
+      <Space wrap>
+        <Cascader
+          style={{ width: 200 }}
+          placeholder={t('Select field')}
+          options={cascaderOptions}
+          value={fieldPath}
+          onChange={handleFieldChange}
+          changeOnSelect={false}
+          expandTrigger="click"
+          popupClassName={cascaderPopupClass}
+        />
+        <Select
+          style={{ width: 120 }}
+          placeholder={t('Comparision')}
+          value={operator || undefined}
+          onChange={handleOperatorChange}
+          disabled={!leftValue || operatorOptions.length === 0}
+        >
+          {operatorOptions.map((op) => (
+            <Select.Option key={op.value} value={op.value}>
+              {op.label}
+            </Select.Option>
+          ))}
+        </Select>
+        <FilterValueInput
+          field={selectedField}
+          operator={selectedOperator}
+          value={rightValue}
+          onChange={handleValueChange}
+          placeholder={t('Enter value')}
+          t={t}
+        />
+      </Space>
+    );
+  },
+  { displayName: 'CollectionFilterItem' },
+);
+
+/**
+ * Convenience factory returning a `FilterContainer`-compatible `FilterItem` component bound to a specific collection. Avoids creating an inline closure on every parent render, which would otherwise reset any focused inner antd control.
+ */
+export function createCollectionFilterItem(
+  collection: Collection,
+  bound?: Pick<CollectionFilterItemProps, 'filterableFieldNames' | 'nonfilterableFieldNames' | 'noIgnore' | 't'>,
+) {
+  const Component: FC<{ value: CollectionFilterItemValue }> = (props) => (
+    <CollectionFilterItem {...bound} value={props.value} collection={collection} />
+  );
+  Component.displayName = 'BoundCollectionFilterItem';
+  return Component;
+}
+
+export default CollectionFilterItem;