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

package/src/components/form/filter/__tests__/compileFilterGroup.test.ts

@@ -0,0 +1,146 @@
+/**
+ * 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 { compileFilterGroup } from '../useFilterActionProps';
+
+describe('compileFilterGroup', () => {
+  it('returns undefined for an empty group so callers can drop the filter param', () => {
+    expect(compileFilterGroup(undefined)).toBeUndefined();
+    expect(compileFilterGroup({ logic: '$and', items: [] })).toBeUndefined();
+  });
+
+  it('compiles a single condition into the NocoBase {path: {op: val}} envelope', () => {
+    const out = compileFilterGroup({
+      logic: '$and',
+      items: [{ path: 'lockReason', operator: '$includes', value: 'abuse' }],
+    });
+    expect(out).toEqual({ $and: [{ lockReason: { $includes: 'abuse' } }] });
+  });
+
+  it('preserves the parent logic ($and / $or)', () => {
+    const out = compileFilterGroup({
+      logic: '$or',
+      items: [
+        { path: 'lockReason', operator: '$eq', value: 'abuse' },
+        { path: 'lockReason', operator: '$eq', value: 'spam' },
+      ],
+    });
+    expect(out).toEqual({
+      $or: [{ lockReason: { $eq: 'abuse' } }, { lockReason: { $eq: 'spam' } }],
+    });
+  });
+
+  it('compiles nested groups recursively', () => {
+    const out = compileFilterGroup({
+      logic: '$and',
+      items: [
+        { path: 'lockReason', operator: '$eq', value: 'abuse' },
+        {
+          logic: '$or',
+          items: [
+            { path: 'lockedTs', operator: '$dateAfter', value: '2026-01-01' },
+            { path: 'lockedTs', operator: '$dateBefore', value: '2026-12-31' },
+          ],
+        },
+      ],
+    });
+    expect(out).toEqual({
+      $and: [
+        { lockReason: { $eq: 'abuse' } },
+        {
+          $or: [{ lockedTs: { $dateAfter: '2026-01-01' } }, { lockedTs: { $dateBefore: '2026-12-31' } }],
+        },
+      ],
+    });
+  });
+
+  it('drops items with empty values (undefined / "" / [] / {}) so half-edited rows do not 500 the server', () => {
+    // Mirrors v1's `removeNullCondition` behaviour. A user who selected a field + operator but hasn't typed a value yet must NOT cause `{path:{operator:undefined}}` to fly out — the server rejects empty operator bodies on `$dateOn` etc.
+    const out = compileFilterGroup({
+      logic: '$and',
+      items: [
+        { path: 'lockedTs', operator: '$dateOn', value: undefined },
+        { path: 'lockReason', operator: '$eq', value: '' },
+        { path: 'lockReason', operator: '$in', value: [] },
+        { path: 'lockedTs', operator: '$dateOn', value: {} },
+        { path: 'lockReason', operator: '$eq', value: 'kept' },
+      ],
+    });
+    expect(out).toEqual({ $and: [{ lockReason: { $eq: 'kept' } }] });
+  });
+
+  it('expands dotted association paths into nested objects (matches v1 payload shape)', () => {
+    // `user.createdBy.password` must reach the server as a nested object so the filter resolver walks the association chain. Flattened-key form (`{ "user.createdBy.password": ... }`) leaves the server treating the whole string as one column name.
+    const out = compileFilterGroup({
+      logic: '$and',
+      items: [{ path: 'user.createdBy.password', operator: '$includes', value: '123' }],
+    });
+    expect(out).toEqual({
+      $and: [{ user: { createdBy: { password: { $includes: '123' } } } }],
+    });
+  });
+
+  it('keeps relative date descriptors (non-empty plain objects) intact', () => {
+    // `{ type: 'today' }` is an empty-keys-only check away from being pruned by accident. Confirm it survives — that's the server-readable shape for relative-date filters.
+    const out = compileFilterGroup({
+      logic: '$and',
+      items: [{ path: 'lockedTs', operator: '$dateOn', value: { type: 'today' } }],
+    });
+    expect(out).toEqual({ $and: [{ lockedTs: { $dateOn: { type: 'today' } } }] });
+  });
+
+  it('drops items missing path or operator so half-typed rows do not break the query', () => {
+    const out = compileFilterGroup({
+      logic: '$and',
+      items: [
+        { path: '', operator: '$eq', value: 'orphan' },
+        { path: 'lockReason', operator: '', value: 'orphan' },
+        { path: 'lockReason', operator: '$eq', value: 'kept' },
+      ],
+    });
+    expect(out).toEqual({ $and: [{ lockReason: { $eq: 'kept' } }] });
+  });
+
+  it('drops empty nested groups so a half-built sub-group does not produce { $or: [] }', () => {
+    const out = compileFilterGroup({
+      logic: '$and',
+      items: [
+        { path: 'lockReason', operator: '$eq', value: 'abuse' },
+        { logic: '$or', items: [] },
+      ],
+    });
+    expect(out).toEqual({ $and: [{ lockReason: { $eq: 'abuse' } }] });
+  });
+
+  it('returns undefined when every item drops out', () => {
+    const out = compileFilterGroup({
+      logic: '$and',
+      items: [
+        { path: '', operator: '', value: '' },
+        { logic: '$or', items: [] },
+      ],
+    });
+    expect(out).toBeUndefined();
+  });
+
+  it('passes complex value shapes (date descriptors, arrays) through unchanged', () => {
+    const dateDescriptor = { type: 'past', number: 3, unit: 'day' };
+    const out = compileFilterGroup({
+      logic: '$and',
+      items: [
+        { path: 'lockedTs', operator: '$dateOn', value: dateDescriptor },
+        { path: 'lockReason', operator: '$in', value: ['abuse', 'spam'] },
+      ],
+    });
+    expect(out).toEqual({
+      $and: [{ lockedTs: { $dateOn: dateDescriptor } }, { lockReason: { $in: ['abuse', 'spam'] } }],
+    });
+  });
+});

package/src/components/form/filter/index.ts

@@ -0,0 +1,13 @@
+/**
+ * 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.
+ */
+
+// Higher-level filter compositions for non-schema surfaces (settings pages, panels, side drawers). The low-level primitives — `FilterContainer`, `FilterGroup`, `FilterItem`, `fieldsToOptions`, `useFilterOptions` — live under `src/flow/components/filter/`; this layer composes them with a `Collection` binding and exposes the hook/component pair callers actually reach for. The dependency direction is form/filter → flow/components/filter only.
+export { CollectionFilter } from './CollectionFilter';
+export type { CollectionFilterProps } from './CollectionFilter';
+export type { CompiledFilter } from './useFilterActionProps';

package/src/components/form/filter/useFilterActionProps.ts

@@ -0,0 +1,203 @@
+/**
+ * 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 { Collection, observable } from '@nocobase/flow-engine';
+import { useMemoizedFn } from 'ahooks';
+import { useMemo, useRef } from 'react';
+import { FilterOption, useFilterOptions, UseFilterOptionsArgs } from '../../../flow/components/filter/useFilterOptions';
+import { CollectionFilterItemValue, createCollectionFilterItem } from './CollectionFilterItem';
+
+/** A single condition row (`{ path, operator, value }`) or a nested group. */
+export type FilterGroupItem = CollectionFilterItemValue | FilterGroupValue;
+
+/**
+ * Reactive shape consumed by `FilterContainer` / `FilterGroup`. `logic` is the join (`$and` / `$or`) and `items` is a heterogeneous list of leaf conditions and nested groups.
+ */
+export type FilterGroupValue = {
+  logic: '$and' | '$or';
+  items: FilterGroupItem[];
+};
+
+/** Compiled filter param accepted by NocoBase resource `list`. */
+export type CompiledFilter = Record<string, unknown> | undefined;
+
+interface FilterCtxModel {
+  translate: (key: string) => string;
+  dispatchEvent: (event: 'submit' | 'reset' | (string & {})) => void;
+}
+
+export interface FilterCtx {
+  model: FilterCtxModel;
+}
+
+const isGroup = (item: FilterGroupItem): item is FilterGroupValue =>
+  Array.isArray((item as FilterGroupValue).items) && typeof (item as FilterGroupValue).logic === 'string';
+
+const isCondition = (item: FilterGroupItem): item is CollectionFilterItemValue =>
+  typeof (item as CollectionFilterItemValue).path === 'string' &&
+  Object.prototype.hasOwnProperty.call(item, 'operator');
+
+/**
+ * `true` when the rhs of a condition is "no real value yet" — covers `undefined` / `null` / empty string / empty array / empty plain object. Mirrors v1's `removeNullCondition` `isEmpty` predicate so half-filled rows ("Locked time → is → (no date picked yet)") get dropped on Submit instead of being sent to the server as `{lockedTs:{}}` and triggering a 500.
+ */
+const isEmptyFilterValue = (value: unknown): boolean => {
+  if (value === undefined || value === null || value === '') return true;
+  if (Array.isArray(value)) return value.length === 0;
+  if (typeof value === 'object') {
+    // Plain `{}` only — descriptor shapes like `{ type: 'today' }` have own keys and survive this check.
+    return Object.keys(value as Record<string, unknown>).length === 0;
+  }
+  return false;
+};
+
+/**
+ * Build a nested object from a dotted path. `'user.createdBy.password'` + `{ $includes: '123' }` becomes `{ user: { createdBy: { password: { $includes: '123' } } } }`. Matches v1's filter payload shape so server-side filter resolution sees the same association chain whether the request came from a v1 or v2 page.
+ */
+const nestPath = (path: string, leaf: unknown): Record<string, unknown> => {
+  const segments = path.split('.');
+  let result: unknown = leaf;
+  for (let i = segments.length - 1; i >= 0; i--) {
+    result = { [segments[i]]: result };
+  }
+  return result as Record<string, unknown>;
+};
+
+/**
+ * Compile a reactive filter group into the `{ $and: [{ path: { op: val } }] }` envelope accepted by NocoBase's resource `list` filter param. Returns `undefined` when the group is empty so callers can drop the param.
+ *
+ * Mirrors v1's `removeNullCondition` + filter compile path, but works on the v2 `{ logic, items }` group structure rather than v1's Formily-bracketed `$and.0.path.$eq` shape:
+ *
+ * - Rows missing `path` or `operator` are dropped (still mid-edit).
+ * - Rows whose `value` is empty (`undefined`, `''`, `[]`, `{}`) are dropped — matches v1, which sends `filter={}` for a row with only a field/operator picked. Sending `{lockedTs:{}}` would 500.
+ * - Dotted association paths (`user.createdBy.password`) are expanded into nested objects — matches v1's payload shape, which the server resolves along the association chain rather than treating the dotted string as a single key.
+ * - Empty groups (after pruning) propagate as `undefined` so the outermost caller can drop the whole `filter` param.
+ */
+export function compileFilterGroup(group: FilterGroupValue | undefined): CompiledFilter {
+  if (!group?.items?.length) return undefined;
+  const compiled = group.items
+    .map((entry) => {
+      if (isGroup(entry)) return compileFilterGroup(entry);
+      if (!isCondition(entry) || !entry.path || !entry.operator) return undefined;
+      if (isEmptyFilterValue(entry.value)) return undefined;
+      return nestPath(entry.path, { [entry.operator]: entry.value });
+    })
+    .filter((v): v is Record<string, unknown> => !!v);
+  if (!compiled.length) return undefined;
+  return { [group.logic]: compiled };
+}
+
+const createEmptyGroup = (): FilterGroupValue => ({ logic: '$and', items: [] });
+
+/** Which footer button triggered the apply — useful for closing a popover on Submit but keeping it open on Reset. */
+export type FilterApplyAction = 'submit' | 'reset';
+
+export interface UseFilterActionPropsArgs extends UseFilterOptionsArgs {
+  /** Collection whose fields populate the filter row's field picker. */
+  collection: Collection | undefined;
+  /**
+   * Called when the user submits or resets the filter popover. Receives the compiled filter param (`undefined` when cleared) and which footer button triggered the call. Typical implementation: `(filter, action) => { listRequest.run(filter); if (action === 'submit') closePopover(); }`.
+   */
+  onApply: (filter: CompiledFilter, action: FilterApplyAction) => void;
+}
+
+export interface UseFilterActionPropsResult {
+  /**
+   * Reactive filter group state. Pass directly to `<FilterContent value={...}>`. Stable across renders.
+   */
+  value: FilterGroupValue;
+  /** Field-option tree (for inspection or custom badges). */
+  options: FilterOption[];
+  /** Bound `FilterItem` component to plug into `<FilterContent FilterItem={...}>`. */
+  FilterItem: ReturnType<typeof createCollectionFilterItem> | undefined;
+  /**
+   * Ready-to-use `ctx` for `<FilterContent ctx={...}>`. Wires Submit / Reset buttons to `onSubmit` / `onReset` below.
+   */
+  ctx: FilterCtx;
+  /** Imperative trigger — submit current group as a compiled filter. */
+  onSubmit: () => void;
+  /** Imperative trigger — clear the group and emit an empty filter. */
+  onReset: () => void;
+  /**
+   * Count of top-level condition rows. Useful for showing a badge like `Filter (3)` on the trigger button — matches v1's `field.title = t('{{count}} filter items', { count })`.
+   */
+  conditionCount: number;
+}
+
+/**
+ * v2 equivalent of v1's `useFilterActionProps` for non-schema surfaces (settings pages, panels, side drawers). Bundles three things v1's hook returned implicitly through schema:
+ *
+ * - A reactive `{ logic, items }` group state that `<FilterContent>` reads.
+ * - A bound `FilterItem` component (driven by `createCollectionFilterItem`).
+ * - A `ctx` object that turns `<FilterContent>`'s `dispatchEvent('submit' | 'reset')` into a compiled filter param passed to `onApply`.
+ *
+ * Pair with antd `Popover` to recreate the legacy `Filter.Action` UX:
+ *
+ * ```tsx
+ * const { value, ctx, FilterItem, onSubmit, conditionCount } = useFilterActionProps({
+ *   collection,
+ *   onApply: (filter) => listRequest.run(filter),
+ *   t,
+ * });
+ * return (
+ *   <Popover content={<FilterContent value={value} ctx={ctx} FilterItem={FilterItem} />}>
+ *     <Button>{t('Filter')}{conditionCount ? ` (${conditionCount})` : ''}</Button>
+ *   </Popover>
+ * );
+ * ```
+ */
+export function useFilterActionProps(args: UseFilterActionPropsArgs): UseFilterActionPropsResult {
+  const { collection, onApply, filterableFieldNames, nonfilterableFieldNames, noIgnore, t } = args;
+
+  // Held in a ref so the group object identity is stable for the lifetime of the host component — `<FilterContent>` mutates this object directly (push/splice on `items`, swap `logic`), and a fresh observable on every render would reset that internal state.
+  const valueRef = useRef<FilterGroupValue>();
+  if (!valueRef.current) {
+    valueRef.current = observable(createEmptyGroup()) as FilterGroupValue;
+  }
+  const value = valueRef.current;
+
+  const options = useFilterOptions(collection, { filterableFieldNames, nonfilterableFieldNames, noIgnore, t });
+
+  const FilterItem = useMemo(
+    () =>
+      collection
+        ? createCollectionFilterItem(collection, { filterableFieldNames, nonfilterableFieldNames, noIgnore, t })
+        : undefined,
+    [collection, filterableFieldNames, nonfilterableFieldNames, noIgnore, t],
+  );
+
+  const onSubmit = useMemoizedFn(() => {
+    onApply(compileFilterGroup(value), 'submit');
+  });
+
+  const onReset = useMemoizedFn(() => {
+    value.logic = '$and';
+    value.items = [];
+    onApply(undefined, 'reset');
+  });
+
+  const translate = useMemoizedFn((key: string) => (t ? t(key) : key));
+
+  const ctx = useMemo<FilterCtx>(
+    () => ({
+      model: {
+        translate,
+        dispatchEvent: (event: string) => {
+          if (event === 'submit') onSubmit();
+          else if (event === 'reset') onReset();
+        },
+      },
+    }),
+    [translate, onSubmit, onReset],
+  );
+
+  // Re-read on each render so `observer`-wrapped hosts re-render when the reactive `items` array length changes. No useMemo needed — the `value` object's identity is stable (held in a ref), but its observable `items.length` is what we actually care about, and the eslint exhaustive-deps rule rightly complains about depending on a mutable property of a stable ref.
+  const conditionCount = value.items.length;
+
+  return { value, options, FilterItem, ctx, onSubmit, onReset, conditionCount };
+}

package/src/components/form/index.tsx

@@ -8,6 +8,7 @@
  */
 
 export * from './createFormRegistry';
+export * from './filter';
 export * from './DialogFormLayout';
 export * from './DrawerFormLayout';
 export * from './EnvVariableInput';

package/src/data-source/ExtendCollectionsProvider.tsx

@@ -0,0 +1,144 @@
+/**
+ * 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 type { CollectionOptions } from '@nocobase/flow-engine';
+import React, { FC, ReactNode, useEffect, useRef } from 'react';
+import { useApp } from '../hooks';
+
+export interface ExtendCollectionsProviderProps {
+  /** Data source key to extend. Defaults to `'main'`. */
+  dataSource?: string;
+  /** Collections to surface for the lifetime of this provider's subtree. */
+  collections: CollectionOptions[];
+  /**
+   * When `true`, re-sync the data source whenever the `collections` prop
+   * reference changes after mount: add entries newly present in the prop and
+   * remove entries no longer present (only those this provider registered).
+   * The diff runs in the same render as the prop change so children see the
+   * new state on their first render — at the cost of one observable mutation
+   * per change.
+   *
+   * Defaults to `false`. Most pages pass a stable (often module-level)
+   * `collections` list and don't need this; leaving it off avoids accidental
+   * re-registration when callers forget to memoize. Enable only when your
+   * collection list legitimately varies during the provider's lifetime.
+   */
+  syncOnChange?: boolean;
+  children?: ReactNode;
+}
+
+/**
+ * Mount-scoped collection injector. Adds the given `collections` to the target
+ * data source on first render — synchronously, so children can read
+ * `getCollection(name)` on their own first render — and removes them on
+ * unmount. Survives mid-session data-source reloads via the
+ * `dataSource:loaded` event by re-registering only the names this provider
+ * owns.
+ *
+ * Use this for client-only collections — e.g. a `schema-only` server
+ * collection that isn't auto-published to the v2 data source, or a pure
+ * UI-side mirror — so downstream components (like `<CollectionFilter>`) can
+ * resolve the collection by name.
+ *
+ * Default behavior is "static-at-mount": subsequent changes to the
+ * `collections` prop are ignored. Pass `syncOnChange` to opt into diffing on
+ * prop change.
+ */
+export const ExtendCollectionsProvider: FC<ExtendCollectionsProviderProps> = ({
+  dataSource = 'main',
+  collections,
+  syncOnChange = false,
+  children,
+}) => {
+  const app = useApp();
+  // Lazy-ref init guard. `ownedRef.current === null` only on the first render;
+  // once populated, StrictMode dev's second render and any subsequent
+  // re-render see a non-null ref and skip re-registering. React docs bless
+  // this idiom for "init exactly once on mount" — see "Avoiding recreating
+  // the ref contents".
+  const ownedRef = useRef<CollectionOptions[] | null>(null);
+  // Identity of the `collections` reference we last reacted to; gates the
+  // opt-in diff so StrictMode's double-render doesn't diff twice.
+  const lastCollectionsRef = useRef<CollectionOptions[] | null>(null);
+
+  if (ownedRef.current === null) {
+    const ds = app.dataSourceManager?.getDataSource?.(dataSource);
+    const owned: CollectionOptions[] = [];
+    if (ds) {
+      for (const c of collections) {
+        if (ds.getCollection?.(c.name)) continue;
+        ds.addCollection?.(c);
+        owned.push(c);
+      }
+    }
+    ownedRef.current = owned;
+    lastCollectionsRef.current = collections;
+  } else if (syncOnChange && lastCollectionsRef.current !== collections) {
+    const ds = app.dataSourceManager?.getDataSource?.(dataSource);
+    if (ds) {
+      const nextNames = new Set(collections.map((c) => c.name));
+      const prevOwned = new Map(ownedRef.current.map((c) => [c.name, c]));
+      for (const name of prevOwned.keys()) {
+        if (!nextNames.has(name)) ds.removeCollection?.(name);
+      }
+      const nextOwned: CollectionOptions[] = [];
+      for (const c of collections) {
+        const previous = prevOwned.get(c.name);
+        if (previous) {
+          // First-registered wins: keep the existing options object, mirroring
+          // the original behavior where re-adding a present name was a no-op.
+          // Callers who need to update a collection should remount the
+          // provider (e.g. `key={signature}`).
+          nextOwned.push(previous);
+          continue;
+        }
+        if (ds.getCollection?.(c.name)) continue;
+        ds.addCollection?.(c);
+        nextOwned.push(c);
+      }
+      ownedRef.current = nextOwned;
+    }
+    lastCollectionsRef.current = collections;
+  }
+
+  useEffect(() => {
+    const onLoaded = (event: Event) => {
+      const key = (event as CustomEvent<{ dataSourceKey: string }>).detail?.dataSourceKey;
+      if (key !== dataSource && key !== '*') return;
+      const ds = app.dataSourceManager?.getDataSource?.(dataSource);
+      if (!ds || !ownedRef.current) return;
+      // dataSource was just reloaded from the server — our owned client-only
+      // entries got wiped. Re-add only the ones we own, using the snapshot in
+      // the ref so we don't accidentally seize names this provider never
+      // registered.
+      for (const c of ownedRef.current) {
+        if (ds.getCollection?.(c.name)) continue;
+        ds.addCollection?.(c);
+      }
+    };
+    app.eventBus?.addEventListener('dataSource:loaded', onLoaded);
+    return () => {
+      app.eventBus?.removeEventListener('dataSource:loaded', onLoaded);
+      const ds = app.dataSourceManager?.getDataSource?.(dataSource);
+      const owned = ownedRef.current ?? [];
+      ownedRef.current = null;
+      lastCollectionsRef.current = null;
+      if (!ds) return;
+      for (const c of owned) ds.removeCollection?.(c.name);
+    };
+    // `collections` / `syncOnChange` intentionally excluded — they drive the
+    // render-phase init/diff above, not this effect. The listener reads
+    // `ownedRef` each time it fires (async, never during render).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [app, dataSource]);
+
+  return <>{children}</>;
+};
+
+export default ExtendCollectionsProvider;