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

package/src/components/form/createFormRegistry.ts

@@ -0,0 +1,60 @@
+/**
+ * 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.
+ */
+
+export interface FormRegistryEntry {
+  name: string;
+}
+
+export interface FormRegistry<T extends FormRegistryEntry> {
+  readonly namespace: string;
+  register(entry: T): void;
+  unregister(name: string): boolean;
+  get(name: string): T | undefined;
+  has(name: string): boolean;
+  list(): T[];
+}
+
+/**
+ * Create an isolated, namespaced registry of form-like entries.
+ *
+ * Each call returns a fresh registry instance backed by its own closure-scoped
+ * `Map`, so plugins do not share state across namespaces. Plugins that need an
+ * extension point for form-shaped registrations (e.g. storage configuration
+ * forms, data-source connection forms) can build their own typed registry on
+ * top of this primitive instead of re-implementing the same boilerplate.
+ *
+ * Re-registering the same `name` overwrites the previous entry and emits a
+ * console warning. This is intentional so HMR / hot reload works without
+ * throwing, while still surfacing unintended duplicates during development.
+ */
+export function createFormRegistry<T extends FormRegistryEntry>(namespace: string): FormRegistry<T> {
+  const entries = new Map<string, T>();
+
+  return {
+    namespace,
+    register(entry) {
+      if (entries.has(entry.name)) {
+        console.warn(`[${namespace}] entry "${entry.name}" already registered, overwriting.`);
+      }
+      entries.set(entry.name, entry);
+    },
+    unregister(name) {
+      return entries.delete(name);
+    },
+    get(name) {
+      return entries.get(name);
+    },
+    has(name) {
+      return entries.has(name);
+    },
+    list() {
+      return Array.from(entries.values());
+    },
+  };
+}

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;

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

@@ -0,0 +1,283 @@
+/**
+ * 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 { DatePicker, Divider, InputNumber, Select, Space, theme } from 'antd';
+import dayjs, { type Dayjs } from 'dayjs';
+import React, { useMemo, useState } from 'react';
+
+/**
+ * Value shape used by NocoBase's `$date*` filter operators. Two flavours:
+ *
+ * - For "Exact day" mode: a **formatted string** at the granularity of the picker — `"2026-02-15"` (date), `"2026-02"` (month), `"2026"` (year), `"2026-Q1"` (quarter). For `$dateBetween` (`isRange`), a `[string, string]` tuple. Strings (not Dayjs) so the value serializes verbatim into the query string the same way v1 does (`filter=%7B%22$and%22:[%7B%22lockedTs%22:%7B%22$dateOn%22:%222026-02%22%7D%7D]%7D`).
+ * - For relative modes (Today / Past 3 days / This Week / …): a `{ type, number?, unit? }` descriptor that the server resolves to a concrete range at query time.
+ */
+export type DateFilterValue =
+  | string
+  | [string, string]
+  | { type: string; number?: number; unit?: 'day' | 'week' | 'month' | 'year' }
+  | null
+  | undefined;
+
+export interface DateFilterDynamicComponentProps {
+  value?: DateFilterValue;
+  onChange?: (value: DateFilterValue) => void;
+  /** `true` for `$dateBetween`; renders a `DatePicker.RangePicker`. */
+  isRange?: boolean;
+  /**
+   * Translator. Defaults to identity so callers can omit it when running outside a translation context (tests, storybook).
+   */
+  t?: (key: string) => string;
+}
+
+const identity = (s: string) => s;
+
+const PICKER_OPTIONS = [
+  { label: 'Date', value: 'date' as const },
+  { label: 'Month', value: 'month' as const },
+  { label: 'Quarter', value: 'quarter' as const },
+  { label: 'Year', value: 'year' as const },
+];
+
+const RELATIVE_PRIMARY = [
+  { value: 'exact', label: 'Exact day' },
+  { value: 'past', label: 'Past' },
+  { value: 'next', label: 'Next' },
+];
+
+const RELATIVE_SECONDARY = [
+  { value: 'today', label: 'Today' },
+  { value: 'yesterday', label: 'Yesterday' },
+  { value: 'tomorrow', label: 'Tomorrow' },
+  { value: 'thisWeek', label: 'This Week' },
+  { value: 'lastWeek', label: 'Last Week' },
+  { value: 'nextWeek', label: 'Next Week' },
+  { value: 'thisMonth', label: 'This Month' },
+  { value: 'lastMonth', label: 'Last Month' },
+  { value: 'nextMonth', label: 'Next Month' },
+  { value: 'thisQuarter', label: 'This Quarter' },
+  { value: 'lastQuarter', label: 'Last Quarter' },
+  { value: 'nextQuarter', label: 'Next Quarter' },
+  { value: 'thisYear', label: 'This Year' },
+  { value: 'lastYear', label: 'Last Year' },
+  { value: 'nextYear', label: 'Next Year' },
+];
+
+const UNIT_OPTIONS = [
+  { value: 'day' as const, label: 'Day' },
+  { value: 'week' as const, label: 'Calendar week' },
+  { value: 'month' as const, label: 'Calendar Month' },
+  { value: 'year' as const, label: 'Calendar Year' },
+];
+
+const isRelativeDescriptor = (value: DateFilterValue): value is { type: string; number?: number; unit?: any } =>
+  !!value && typeof value === 'object' && !Array.isArray(value) && 'type' in (value as any);
+
+type PickerMode = 'date' | 'month' | 'quarter' | 'year';
+
+/**
+ * The exact format strings NocoBase's `$date*` server operators expect per picker granularity. Mirrors v1's `getPickerFormat` output under `underFilter=true`, so the URL-encoded query stays identical.
+ *
+ * Exported for unit tests and for downstream callers that need to parse / format `$date*` values outside this component.
+ */
+export const FORMAT_BY_PICKER: Record<PickerMode, string> = {
+  date: 'YYYY-MM-DD',
+  month: 'YYYY-MM',
+  quarter: 'YYYY-[Q]Q',
+  year: 'YYYY',
+};
+
+/**
+ * Parse a granularity-formatted string back into a `Dayjs`. Returns `null` on missing or unparseable input so the DatePicker's controlled-value contract stays clean.
+ */
+export const parseDateFilterValue = (value: string | undefined, picker: PickerMode): Dayjs | null => {
+  if (!value) return null;
+  const parsed = dayjs(value, FORMAT_BY_PICKER[picker]);
+  return parsed.isValid() ? parsed : null;
+};
+
+/**
+ * Format a `Dayjs` (typically from `DatePicker.onChange`) into the server-facing string at the active picker's granularity. Returns `undefined` for empty input so callers can drop the value entirely.
+ */
+export const formatDateFilterValue = (value: Dayjs | null | undefined, picker: PickerMode): string | undefined => {
+  if (!value || !dayjs.isDayjs(value)) return undefined;
+  return value.format(FORMAT_BY_PICKER[picker]);
+};
+
+/**
+ * v2 port of v1's `DateFilterDynamicComponent` — a multi-mode value input for the `$date*` operator family. Three sub-controls glued in a `Space.Compact` row:
+ *
+ * 1. Mode select — `Exact day` / `Past` / `Next` / `Today` / `This Week` / … Picking a relative mode emits a `{ type, number?, unit? }` descriptor that the server resolves at query time; picking `Exact day` emits a raw `Dayjs` instead.
+ * 2. Picker granularity — only when mode is `Exact day`: `Date` / `Month` / `Quarter` / `Year`. Controls the antd `DatePicker`'s `picker` mode so admins can filter to e.g. "any day in 2026-03".
+ * 3. Date input — antd `DatePicker` for single dates, or `DatePicker.RangePicker` when `isRange` is true (used by `$dateBetween`).
+ *
+ * v1 wired its own `<DatePicker.FilterWithPicker>` for the third slot; v2 inlines the picker-granularity selector here so we don't have to fork antd's DatePicker. Drops v1's `@emotion/css` (uses antd token spacing) and the `useCompile` schema-template chain (call sites pass a plain `t` translator).
+ */
+export const DateFilterDynamicComponent: React.FC<DateFilterDynamicComponentProps> = (props) => {
+  const { value, onChange, isRange, t = identity } = props;
+  const { token } = theme.useToken();
+  const [picker, setPicker] = useState<PickerMode>('date');
+  const [open, setOpen] = useState(false);
+
+  const mode = isRelativeDescriptor(value) ? value.type : 'exact';
+
+  const primaryOptions = useMemo(() => RELATIVE_PRIMARY.map((o) => ({ ...o, label: t(o.label) })), [t]);
+  const secondaryOptions = useMemo(() => RELATIVE_SECONDARY.map((o) => ({ ...o, label: t(o.label) })), [t]);
+  const pickerOptions = useMemo(() => PICKER_OPTIONS.map((o) => ({ ...o, label: t(o.label) })), [t]);
+  const unitOptions = useMemo(() => UNIT_OPTIONS.map((o) => ({ ...o, label: t(o.label) })), [t]);
+
+  const handleSelectMode = (next: string) => {
+    setOpen(false);
+    if (next === 'exact') {
+      onChange?.(undefined);
+      return;
+    }
+    if (next === 'past' || next === 'next') {
+      onChange?.({ type: next, number: 1, unit: 'day' });
+      return;
+    }
+    onChange?.({ type: next });
+  };
+
+  const renderModeDropdown = () => (
+    <div style={{ maxHeight: 300, overflowY: 'auto' }}>
+      {primaryOptions.map((opt) => (
+        <div
+          key={opt.value}
+          role="option"
+          aria-selected={mode === opt.value}
+          onClick={() => handleSelectMode(opt.value)}
+          style={{
+            padding: `${token.paddingXXS}px ${token.paddingSM}px`,
+            cursor: 'pointer',
+            whiteSpace: 'nowrap',
+          }}
+        >
+          {opt.label}
+        </div>
+      ))}
+      <Divider style={{ margin: `${token.marginXXS}px 0` }} />
+      {secondaryOptions.map((opt) => (
+        <div
+          key={opt.value}
+          role="option"
+          aria-selected={mode === opt.value}
+          onClick={() => handleSelectMode(opt.value)}
+          style={{
+            padding: `${token.paddingXXS}px ${token.paddingSM}px`,
+            cursor: 'pointer',
+            whiteSpace: 'nowrap',
+            overflow: 'hidden',
+            textOverflow: 'ellipsis',
+          }}
+          title={opt.label}
+        >
+          {opt.label}
+        </div>
+      ))}
+    </div>
+  );
+
+  // Mode select compresses when the chosen mode is "Exact day / Past / Next" (room is needed for the secondary picker / number+unit row beside it). For named ranges (Today, This Week, etc.) it stretches since no sub-control follows.
+  const compactModes = new Set(['exact', 'past', 'next']);
+  const isCompact = compactModes.has(mode);
+
+  return (
+    <Space.Compact style={{ width: '100%' }}>
+      <Select
+        open={open}
+        onDropdownVisibleChange={setOpen}
+        value={mode}
+        onChange={handleSelectMode}
+        style={{
+          flex: '0 0 auto',
+          minWidth: 100,
+          maxWidth: isCompact ? 100 : undefined,
+          width: isCompact ? 100 : 'auto',
+        }}
+        popupMatchSelectWidth={false}
+        dropdownRender={renderModeDropdown}
+        options={[...primaryOptions, ...secondaryOptions]}
+      />
+
+      {(mode === 'past' || mode === 'next') && (
+        <>
+          <InputNumber
+            value={isRelativeDescriptor(value) ? value.number : 1}
+            min={1}
+            onChange={(num) => {
+              if (!isRelativeDescriptor(value)) return;
+              onChange?.({ ...value, number: typeof num === 'number' ? num : 1 });
+            }}
+            style={{ flex: '0 0 auto' }}
+          />
+          <Select
+            value={isRelativeDescriptor(value) ? value.unit : 'day'}
+            onChange={(unit) => {
+              if (!isRelativeDescriptor(value)) return;
+              onChange?.({ ...value, unit });
+            }}
+            options={unitOptions}
+            style={{ flex: '0 0 auto', minWidth: 130 }}
+            popupMatchSelectWidth
+          />
+        </>
+      )}
+
+      {mode === 'exact' && !isRange && (
+        <>
+          <Select
+            value={picker}
+            onChange={(next) => {
+              setPicker(next);
+              // Picker change means the previously selected date is now expressed at a different granularity; clear it so the user doesn't carry a stale value into the new picker.
+              onChange?.(undefined);
+            }}
+            options={pickerOptions}
+            style={{ flex: '0 0 auto', width: 100 }}
+            popupMatchSelectWidth={false}
+          />
+          <DatePicker
+            // Stored value is a granularity-formatted string (e.g. `"2026-02"` for month picker). Hydrate it back to a Dayjs for antd's controlled-value contract, then re-emit a formatted string on change so the URL serialization matches v1 exactly. Without the format step, antd's Dayjs would JSON.stringify to a full ISO timestamp and the server's `$dateOn` would never match.
+            value={parseDateFilterValue(typeof value === 'string' ? value : undefined, picker)}
+            onChange={(next) => onChange?.(formatDateFilterValue(next, picker))}
+            picker={picker}
+            format={FORMAT_BY_PICKER[picker]}
+            style={{ flex: 1, minWidth: 0 }}
+          />
+        </>
+      )}
+
+      {mode === 'exact' && isRange && (
+        <DatePicker.RangePicker
+          // `$dateBetween` always operates at day granularity in v1's URL output, so we pin the range format to `YYYY-MM-DD`.
+          value={
+            Array.isArray(value)
+              ? ([parseDateFilterValue(value[0], 'date'), parseDateFilterValue(value[1], 'date')] as [
+                  Dayjs | null,
+                  Dayjs | null,
+                ])
+              : undefined
+          }
+          onChange={(next) => {
+            if (!next || !next[0] || !next[1]) {
+              onChange?.(undefined);
+              return;
+            }
+            const [start, end] = next as [Dayjs, Dayjs];
+            onChange?.([start.format(FORMAT_BY_PICKER.date), end.format(FORMAT_BY_PICKER.date)]);
+          }}
+          format={FORMAT_BY_PICKER.date}
+          style={{ flex: 1, minWidth: 0 }}
+        />
+      )}
+    </Space.Compact>
+  );
+};
+
+export default DateFilterDynamicComponent;