@qfei-design/make-filter

Make advanced filter package with a headless core, a host-controlled React panel, optional component-library adapters, and Make Data API compatible filter.expression output.

The v1 interaction and internal panel styling follow the current ExpensePoc advanced-filter baseline. The package does not render Popover, Modal, Drawer, or any scroll container; host apps decide where to mount the panel and how wide, tall, or scrollable that container is. It also does not implement table-header filter UI. Header filter UI is a host integration that may call the package controller.

For Make App record-list pages, filtering is normally delivered as one integrated feature. Make App filtering should wire the toolbar advanced filter and host-owned CanvasTable header linkage together: this package provides the advanced filter model, panel, controller, and openWithField; the host provides the CanvasTable header UI/menu and calls the same controller.

Install

pnpm add @qfei-design/make-filter@^0.1.4

npm install @qfei-design/make-filter@^0.1.4

yarn add @qfei-design/make-filter@^0.1.4

0.1.4 is the minimum runtime baseline. 0.1.5 adds the AI documentation files published with the package.

Public Entrypoints

• @qfei-design/make-filter: headless core helpers, operators, validation, summary, CEL compile/parse, and compileListFilter.
• @qfei-design/make-filter/react: AdvancedFilterPanel, useAdvancedFilterController, candidate-source types, and component contracts.
• @qfei-design/make-filter/adapters/antd: createAntdFilterComponents for Ant Design hosts.
• @qfei-design/make-filter/styles.css: internal panel styles. Import once in the host UI entry.

Do not import from src, dist, or package-internal files.

Quick Start: AntD Popover Host

The package renders only the advanced filter panel. The host owns the toolbar button, Popover, width, max height, scroll behavior, applied state, and record reload.

import { Button, Popover } from "antd";
import { useState } from "react";
import {
  AdvancedFilterPanel,
  useAdvancedFilterController,
} from "@qfei-design/make-filter/react";
import { createAntdFilterComponents } from "@qfei-design/make-filter/adapters/antd";
import "@qfei-design/make-filter/styles.css";

const filterComponents = createAntdFilterComponents();

export function AdvancedFilterPopover({
  appliedGroup,
  candidateSources,
  fields,
  onConfirm,
}) {
  const [open, setOpen] = useState(false);
  const controller = useAdvancedFilterController({
    fields,
    value: appliedGroup,
    onChange: onConfirm,
  });

  function handleOpenChange(nextOpen) {
    if (nextOpen) {
      controller.beginDraft();
      setOpen(true);
      return;
    }
    controller.resetDraft();
    setOpen(false);
  }

  function handleConfirm() {
    const validation = controller.confirm();
    if (validation.valid) setOpen(false);
  }

  return (
    <Popover
      open={open}
      trigger="click"
      placement="bottomLeft"
      content={
        <div style={{ width: 724, maxHeight: 560, overflow: "auto" }}>
          <AdvancedFilterPanel
            candidateSources={candidateSources}
            components={filterComponents}
            fields={fields}
            value={controller.draftValue}
            validationErrors={controller.validationErrors}
            onChange={controller.setDraftValue}
            onClear={controller.clearDraft}
            onConfirm={handleConfirm}
          />
        </div>
      }
      onOpenChange={handleOpenChange}
    >
      <Button>筛选</Button>
    </Popover>
  );
}

Quick Start: Compile Service Filter

Use compileListFilter to merge toolbar search and applied advanced filters.

import { compileListFilter } from "@qfei-design/make-filter";

const filter = compileListFilter({
  advancedFilter: appliedGroup,
  fields,
  searchText,
});

const requestPayload = filter ? { filter } : {};

When compileListFilter returns undefined, omit filter. Do not send filter: [], filter: {}, or { expression: "" }.

Package provides

• Filter IR helpers.
• Make field support and operator matrix.
• Default values, validation, and active-condition summary.
• CEL expression compile and parse.
• AdvancedFilterPanel for React hosts.
• Complete default condition rows with the first filterable field and first supported operator selected. Field dropdowns are not auto-opened by the package.
• useAdvancedFilterController for draft, reset, clear, confirm, validation, and openWithField for host-owned field entry points.
• candidateSources props for remote user and department values.
• createAntdFilterComponents for Ant Design controls.
• ExpensePoc-derived internal panel styling through styles.css.

Host app provides

• Normalized Make field metadata.
• Applied advanced-filter state.
• Toolbar trigger placement.
• Popover, Modal, Drawer, or another mounting container.
• Container width, max height, and scrolling.
• User and department candidate APIs.
• Service request adapter and record reload timing.
• CanvasTable header filter UI, menu behavior, and openWithField linkage.
• Optional URL/deep-link encoding and parsing policy.

Host-Owned CanvasTable Header Linkage

Header filter UI is a host integration, not a package feature. For CanvasTable header menus, keep the table integration in the host and call the package controller when the user chooses 按该字段筛选:

controller.openWithField(fieldKey);

The package does not implement CanvasTable header filter UI. The package does not implement CanvasTable suffixRender. The package also does not implement header menu placement or scroll cleanup. The header action should only open the same toolbar advanced filter draft; it must not submit immediately or reload records before 确认.

Candidate Sources

User and department filter values should use identities, not display labels. Pass remote candidates through candidateSources:

const candidateSources = {
  users: { options: userOptions, loading: usersLoading, onSearch: searchUsers },
  departments: {
    options: departmentOptions,
    loading: departmentsLoading,
    onSearch: searchDepartments,
  },
};

Do not source production user or department options from field schema options, current table rows, local demo arrays, or display labels.

Out Of Scope

This package does not render Popover, Modal, Drawer, or scroll containers. It does not implement Service routes, authentication, deployment, saved views, CanvasTable header filter UI, CanvasTable suffixRender, or local filtering of already loaded table rows.

Documentation

• AI code modification rules: docs/ai-frontend-code-rules.md
• npm publishing rules: docs/publishing.md
• Agent guide: docs/agent-usage.md
• Public API: PUBLIC_API.md
• Capability catalog: capabilities.json
• Recipes: recipes.json
• Package metadata for agents: package.ai.json
• Historical API note: docs/api.md
• AntD host example: examples/antd-host/README.md

Development

pnpm test
pnpm typecheck
pnpm build