@multiplatform.one/table 6.1.0 → 6.4.0

package/src/types.ts

@@ -1,11 +1,42 @@
 import type { ColumnDef, ColumnFiltersState, Row } from "@tanstack/react-table";
 import type { UrlStateStrategy } from "./hooks/useDataTable";
 import type { AnyFormApi } from "@multiplatform.one/forms";
+import type React from "react";
 
 // Core Data Types
 
 export type DataTableData = Record<string, any>;
 
+/** Bulk action for DataTable selection toolbar (DG-TBL-02). */
+export interface BulkAction<T = any> {
+  id: string;
+  label: string;
+  icon?: React.ReactNode;
+  confirmMessage?: string;
+  confirmTitle?: string;
+  variant?: "default" | "destructive" | "secondary";
+  onExecute: (selectedItems: T[], clearSelection: () => void) => void | Promise<void>;
+  requiresConfirmation?: boolean;
+  disabled?: boolean;
+  /**
+   * DG-ST-03 — explains why the action is disabled. Flows through the Button /
+   * DropdownMenu explain affordances (visible reason, no hover needed). A bare
+   * `disabled` without it DEV-warns `bare-disabled`.
+   */
+  disabledReason?: string;
+}
+
+/** Select-all checkbox scope (DG-TBL-03). Default: page. */
+export type SelectAllScope = "page" | "filtered";
+
+/**
+ * Responsive layout mode for the table body.
+ * - `auto`: grid on `$sm` and up, stacked card list below (default)
+ * - `table`: always render the grid, even at phone widths
+ * - `cards`: always render the stacked card list
+ */
+export type DataTableLayout = "auto" | "table" | "cards";
+
 /**
  * Field types - the UI component used to render/edit a cell.
  * If no field is specified on a column, defaults to "input" (read-only).
@@ -53,6 +84,17 @@ export type DataTableField =
   // Custom
   | "custom";
 
+/**
+ * Cell state passed to custom cell renderers as the (optional) 4th `render`
+ * argument. When `readOnly` (or `disabled`) is true the cell blocks commits,
+ * so the renderer must produce a non-interactive presentation — rendering an
+ * interactive-looking control whose edits go nowhere lies about editability.
+ */
+export interface DataTableCellRenderContext {
+  readOnly: boolean;
+  disabled: boolean;
+}
+
 /**
  * Field-specific props passed to the underlying field component.
  * Use this for options, validation, formatters, etc.
@@ -100,8 +142,17 @@ export interface DataTableFieldProps {
   dateRangeIsEndColumn?: boolean;
   /** Allow multiple selection for togglegroup */
   allowMultiple?: boolean;
-  /** Custom render function for 'custom' fieldType */
-  render?: (value: any, row: any, onChange: (value: any) => void) => React.ReactNode;
+  /**
+   * Custom render function for the 'custom' fieldType. Honor
+   * `context.readOnly` / `context.disabled` — the cell blocks commits in
+   * those states, so the custom presentation must go non-interactive too.
+   */
+  render?: (
+    value: any,
+    row: any,
+    onChange: (value: any) => void,
+    context?: DataTableCellRenderContext,
+  ) => React.ReactNode;
   /** Any additional props to pass to the field component */
   [key: string]: any;
 }
@@ -115,6 +166,12 @@ export type DataTableColumn<TData extends DataTableData = DataTableData> = Colum
   width?: number;
   minWidth?: number;
   maxWidth?: number;
+  /**
+   * Text alignment override (DG-TBL-01).
+   * When omitted, defaults from field/data type: numbers/currency right,
+   * text left, actions right, booleans center.
+   */
+  align?: "left" | "center" | "right";
   /**
    * UI component type for rendering/editing cells in this column.
    * If not specified, defaults to "input" (read-only text display).
@@ -127,8 +184,6 @@ export type DataTableColumn<TData extends DataTableData = DataTableData> = Colum
    * Props passed to the field component (options, placeholder, min/max, etc.)
    */
   fieldProps?: DataTableFieldProps;
-  /** Custom validation function for cell values. Return error message or undefined. */
-  validate?: (value: any, row: TData) => string | undefined;
 };
 
 // Filter System Types
@@ -183,6 +238,28 @@ export interface TableFilter {
   label?: string; // Human-readable label for the filter
 }
 
+/**
+ * A field the table can filter on, declared SEPARATELY from visible columns.
+ * Lets consumers expose hidden / non-column data keys (e.g. every Frappe
+ * doctype field) to the toolbar filter surface. `id` is the row-data key.
+ */
+export interface FilterableField {
+  id: string;
+  label: string;
+  /** Filter editor type. Defaults to "text". */
+  type?: DataTableColumnType;
+  /** Options for select-type fields. */
+  options?: Array<{ label: string; value: any }>;
+}
+
+/** FilterableField merged with column info — type always resolved. */
+export interface ResolvedFilterField {
+  id: string;
+  label: string;
+  type: DataTableColumnType;
+  options?: Array<{ label: string; value: any }>;
+}
+
 export interface FacetedFilterOption {
   label: string;
   value: string | number | boolean;
@@ -203,6 +280,59 @@ export interface TablePaginationState extends TablePagination {
   hasPreviousPage?: boolean;
 }
 
+// Infinite pagination (paginationMode="infinite")
+
+/**
+ * Pagination presentation mode.
+ * - "pages" (default): footer pager built on the catalog `Pagination` component.
+ * - "infinite": appends the next page as the user nears the end of the list,
+ *   pre-loading page N+1 in the background so appends resolve instantly.
+ */
+export type PaginationMode = "pages" | "infinite";
+
+/** Query passed to the async page loader (infinite mode, server/async data). */
+export interface PageLoadQuery {
+  /** 0-based page index to load */
+  pageIndex: number;
+  /** Rows per page (chunk size in infinite mode) */
+  pageSize: number;
+  sorting: TableSorting[];
+  filters: TableFilter[];
+  columnFilters: ColumnFiltersState;
+  globalFilter?: string;
+}
+
+export interface PageLoadResult<TData = any> {
+  rows: TData[];
+  /** Total row count across all pages, when known (enables exact end-of-data). */
+  totalCount?: number;
+}
+
+/**
+ * Async page loader contract for infinite mode. Must be side-effect-free per
+ * query: the table may call it ahead of time (prefetch) and cache the result.
+ */
+export type DataTablePageLoader<TData = any> = (
+  query: PageLoadQuery,
+) => Promise<PageLoadResult<TData>>;
+
+/** Computed infinite-mode state exposed by useDataTable / DataTableStateContext. */
+export interface DataTableInfiniteState {
+  /** How many row-model rows are currently revealed */
+  visibleRowCount: number;
+  loadedPages: number;
+  /** Total row count when known (loader totalCount or client filtered count) */
+  totalCount?: number;
+  /** No further pages exist */
+  exhausted: boolean;
+  /** Page 0 for the current query is still loading (loader mode) */
+  isInitialLoading: boolean;
+  /** A page append is awaiting the loader (cache miss / in-flight prefetch) */
+  isAppending: boolean;
+  /** Append the next page (no-op while pending or exhausted) */
+  loadMore: () => void;
+}
+
 // Sorting Types
 
 export interface TableSorting {
@@ -277,6 +407,12 @@ export interface DataTableProps<TData extends DataTableData = DataTableData> {
   // State Management
   initialState?: Partial<DataTableState>;
   onStateChange?: (state: DataTableState) => void;
+  /**
+   * Retry action for the failed-load chrome. When `state.error` is set the
+   * table renders error chrome instead of rows; providing `onRetry` adds the
+   * Retry button so "error with retry" is reachable (DG-ST-01).
+   */
+  onRetry?: () => void;
 
   // URL State Integration
   syncWithUrl?: boolean;
@@ -289,9 +425,49 @@ export interface DataTableProps<TData extends DataTableData = DataTableData> {
   manualSorting?: boolean;
 
   // Features
+  /**
+   * Owns the table's filter CHROME (default true): the toolbar Filter
+   * button, column-header funnels, the active-filter chips row, and the
+   * card-layout "Add Filter" control.
+   *
+   * `false` is the chrome-suppression contract for screens where an OUTER
+   * surface is the single filtering authority (e.g. the backoffice list
+   * chrome): the table renders no filter entry points, but filters injected
+   * through `initialState.filters` / the state channel still apply — they
+   * pre-filter client-side data and map to server params under
+   * `manualFiltering` — and no table chrome can mutate them (the search
+   * clear-X then clears only the search text). Search (`enableGlobalSearch`)
+   * and header sort are independent of this flag.
+   */
   enableFiltering?: boolean;
+  /**
+   * Fields filterable via the toolbar Filter surface, independent of visible
+   * columns. Merged with column-derived fields (columns first, then "More
+   * fields"). Hidden/non-column fields filter client-side against row data
+   * keys, or map to server params when manualFiltering is on. With
+   * `enableFiltering: false` the list still resolves filter types for
+   * injected filters but exposes no filter UI.
+   */
+  filterableFields?: FilterableField[];
   enableSorting?: boolean;
   enablePagination?: boolean;
+  /**
+   * Page sizes offered by the built-in footer pager (and forwarded to
+   * `renderPagination`). Defaults to the pager's DG-TBL-04 options.
+   */
+  pageSizeOptions?: number[];
+  /**
+   * Pagination presentation mode. Default "pages" (footer pager).
+   * "infinite" appends pages at the scroll tail with prefetch-ahead.
+   */
+  paginationMode?: PaginationMode;
+  /**
+   * Async page loader for infinite mode with server/async data. When set,
+   * the table owns a small page cache and pre-loads page N+1 while page N
+   * is on screen. Rows are treated as pre-filtered/sorted server-side
+   * (manual filtering/sorting/pagination are forced on).
+   */
+  loadPage?: DataTablePageLoader<TData>;
   enableColumnVisibility?: boolean;
   enableColumnOrdering?: boolean;
   enableColumnResizing?: boolean;
@@ -307,6 +483,14 @@ export interface DataTableProps<TData extends DataTableData = DataTableData> {
    */
   columnLayout?: "equal" | "auto" | "scroll";
 
+  /**
+   * Responsive body layout (W11 breakpoints): `auto` renders the grid on
+   * `$sm` and up and a stacked card list below it; `table` / `cards` pin
+   * one mode regardless of viewport. Search, filters, sorting, selection,
+   * and pagination operate on the same table state in both layouts.
+   */
+  layout?: DataTableLayout;
+
   // Virtualization (Phase 3)
   /** Use virtual scrolling for table body. Requires virtualizationHeight when true. */
   enableVirtualization?: boolean;
@@ -341,6 +525,25 @@ export interface DataTableProps<TData extends DataTableData = DataTableData> {
   /** Enable Excel-like keyboard navigation. */
   enableKeyboardNavigation?: boolean;
 
+  // Row selection + bulk actions (DG-TBL-02, DG-TBL-03)
+  /** Enable row checkboxes and automatic selection toolbar. */
+  enableRowSelection?: boolean;
+  /**
+   * Scope for the header select-all checkbox.
+   * - `page`: current page only (default)
+   * - `filtered`: all rows matching current filters
+   *
+   * Defaults from the house `selectAllScope` theme knob (DG-TBL-03); the
+   * prop is the per-table eject. With `page` scope, the bulk bar exposes a
+   * "Select all N" switch once the page is fully selected.
+   */
+  selectAllScope?: SelectAllScope;
+  /**
+   * Bulk actions shown in the auto SelectionToolbar when rows are selected.
+   * Up to 5 visible; extras go to an overflow menu.
+   */
+  bulkActions?: BulkAction<TData>[];
+
   // Cell editing - cells are always fields, this controls behavior
   /**
    * Read-only mode: all cells display values but cannot be edited.
@@ -454,7 +657,10 @@ export interface UseDataTableReturn<TData extends DataTableData = DataTableData>
   actions: {
     setGlobalFilter: (value: string) => void;
     setFilters: (filters: TableFilter[]) => void;
-    addFilter: (filter: Omit<TableFilter, "id">) => void;
+    /** Adds an advanced filter and returns its generated id. */
+    addFilter: (filter: Omit<TableFilter, "id">) => string;
+    /** Updates an existing advanced filter in place (live commit). */
+    updateFilter: (filterId: string, updates: Partial<Omit<TableFilter, "id">>) => void;
     removeFilter: (filterId: string) => void;
     clearFilters: () => void;
     setPagination: (pagination: TablePagination) => void;
@@ -472,8 +678,14 @@ export interface UseDataTableReturn<TData extends DataTableData = DataTableData>
     filteredData: TData[];
     paginatedData: TData[];
     totalPages: number;
+    /** Total row count across all pages (post-filter; server total when paginating manually). */
+    totalRows: number;
     hasActiveFilters: boolean;
     activeFilterCount: number;
+    /** Column-derived + declared filterableFields, merged (columns first). */
+    filterFields: ResolvedFilterField[];
+    /** Present when paginationMode="infinite" */
+    infinite?: DataTableInfiniteState;
   };
 }
 

package/src/utils/columnAlign.spec.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest";
+import { alignToFlex, getDefaultColumnAlign } from "./columnAlign";
+
+describe("getDefaultColumnAlign (DG-TBL-01)", () => {
+  it("defaults text / input columns to left", () => {
+    expect(getDefaultColumnAlign({ field: "input" })).toBe("left");
+    expect(getDefaultColumnAlign({ field: "textarea" })).toBe("left");
+    expect(getDefaultColumnAlign({})).toBe("left");
+  });
+
+  it("right-aligns numeric field types", () => {
+    for (const field of ["stepper", "slider", "progress", "duration"] as const) {
+      expect(getDefaultColumnAlign({ field })).toBe("right");
+    }
+  });
+
+  it("right-aligns currency via fieldProps.currency", () => {
+    expect(getDefaultColumnAlign({ field: "input", fieldProps: { currency: "USD" } })).toBe(
+      "right",
+    );
+    expect(getDefaultColumnAlign({ field: "stepper", fieldProps: { currency: "$" } })).toBe(
+      "right",
+    );
+  });
+
+  it("right-aligns actions columns by id / meta.role", () => {
+    expect(getDefaultColumnAlign({ id: "actions" })).toBe("right");
+    expect(getDefaultColumnAlign({ id: "row_actions" })).toBe("right");
+    expect(getDefaultColumnAlign({ id: "foo:actions" })).toBe("right");
+    expect(getDefaultColumnAlign({ meta: { role: "actions" } })).toBe("right");
+  });
+
+  it("centers boolean and icon-like fields", () => {
+    expect(getDefaultColumnAlign({ field: "checkbox" })).toBe("center");
+    expect(getDefaultColumnAlign({ field: "switch" })).toBe("center");
+    expect(getDefaultColumnAlign({ field: "rating" })).toBe("center");
+  });
+
+  it("lets explicit align override smart defaults", () => {
+    expect(getDefaultColumnAlign({ field: "stepper", align: "left" })).toBe("left");
+    expect(getDefaultColumnAlign({ id: "actions", align: "center" })).toBe("center");
+    expect(getDefaultColumnAlign({ field: "input", meta: { align: "right" } })).toBe("right");
+  });
+});
+
+describe("alignToFlex", () => {
+  it("maps align tokens to flex justify values", () => {
+    expect(alignToFlex("left")).toBe("flex-start");
+    expect(alignToFlex("center")).toBe("center");
+    expect(alignToFlex("right")).toBe("flex-end");
+    expect(alignToFlex(undefined)).toBe("flex-start");
+  });
+});

package/src/utils/columnAlign.ts

@@ -0,0 +1,60 @@
+/**
+ * DG-TBL-01 — default column alignment by field / data type.
+ *
+ * numbers/currency → right, text → left, actions → right.
+ * Explicit `align` (or meta.align) always wins.
+ */
+
+import type { DataTableField, DataTableFieldProps } from "../types";
+
+export type ColumnAlign = "left" | "center" | "right";
+
+export type ColumnAlignInput = {
+  id?: string;
+  align?: ColumnAlign;
+  field?: DataTableField;
+  fieldProps?: Pick<DataTableFieldProps, "currency"> | DataTableFieldProps;
+  meta?: { align?: ColumnAlign; role?: string };
+};
+
+const NUMERIC_FIELDS = new Set<DataTableField>(["stepper", "slider", "progress", "duration"]);
+
+/** Booleans + icon-like metrics (EUI: center symbols). */
+const CENTER_FIELDS = new Set<DataTableField>(["checkbox", "switch", "rating"]);
+
+function isActionsColumn(column: ColumnAlignInput): boolean {
+  if (column.meta?.role === "actions") return true;
+  const id = column.id ?? "";
+  return id === "actions" || id.endsWith("_actions") || id.endsWith(":actions");
+}
+
+function isCurrencyColumn(column: ColumnAlignInput): boolean {
+  return column.fieldProps?.currency != null && column.fieldProps.currency !== "";
+}
+
+function isNumericColumn(column: ColumnAlignInput): boolean {
+  if (isCurrencyColumn(column)) return true;
+  return column.field != null && NUMERIC_FIELDS.has(column.field);
+}
+
+/** Resolve smart-default column alignment (DG-TBL-01). */
+export function getDefaultColumnAlign(column: ColumnAlignInput): ColumnAlign {
+  if (column.align) return column.align;
+  if (column.meta?.align) return column.meta.align;
+  if (isActionsColumn(column)) return "right";
+  if (isNumericColumn(column)) return "right";
+  if (column.field && CENTER_FIELDS.has(column.field)) return "center";
+  return "left";
+}
+
+/** Map ColumnAlign → Tamagui/flex justifyContent. */
+export function alignToFlex(align?: ColumnAlign): "flex-start" | "center" | "flex-end" {
+  switch (align) {
+    case "center":
+      return "center";
+    case "right":
+      return "flex-end";
+    default:
+      return "flex-start";
+  }
+}

package/src/utils/filterFields.spec.ts

@@ -0,0 +1,237 @@
+import { describe, expect, it } from "vitest";
+import type { DataTableColumn, TableFilter } from "../types";
+import {
+  applyFiltersToData,
+  defaultOperatorForFilterType,
+  filterOperatorLabel,
+  getFilterChipLabel,
+  getFilterFieldType,
+  isFilterValueShape,
+  mapFieldToFilterType,
+  operatorNeedsNoValue,
+  operatorsForFilterType,
+  resolveFilterFields,
+} from "./filterFields";
+
+const columns: DataTableColumn[] = [
+  { accessorKey: "firstName", header: "First Name" },
+  { accessorKey: "age", header: "Age", field: "stepper" },
+  {
+    accessorKey: "status",
+    header: "Status",
+    field: "select",
+    fieldProps: {
+      options: [
+        { label: "Active", value: "active" },
+        { label: "Inactive", value: "inactive" },
+      ],
+    },
+  },
+];
+
+const hiddenFields = [
+  { id: "email", label: "Email" },
+  { id: "salary", label: "Salary", type: "number" as const },
+  { id: "joinDate", label: "Join Date", type: "date" as const },
+];
+
+const rows = [
+  {
+    firstName: "Ada",
+    age: 36,
+    status: "active",
+    email: "ada@corp.com",
+    salary: 90,
+    joinDate: "2021-03-01",
+    verified: true,
+  },
+  {
+    firstName: "Grace",
+    age: 45,
+    status: "inactive",
+    email: "grace@corp.com",
+    salary: 120,
+    joinDate: "2019-07-15",
+    verified: false,
+  },
+  {
+    firstName: "Alan",
+    age: 41,
+    status: "active",
+    email: "alan@other.org",
+    salary: 100,
+    joinDate: "2020-01-20",
+    verified: true,
+  },
+];
+
+function filter(columnId: string, operator: string, value: any, values?: any[]): TableFilter {
+  return { id: `f-${columnId}`, columnId, value: { operator: operator as any, value, values } };
+}
+
+describe("resolveFilterFields", () => {
+  it("derives fields from columns (visible first) and appends declared hidden fields", () => {
+    const fields = resolveFilterFields(columns, hiddenFields);
+    expect(fields.map((f) => f.id)).toEqual([
+      "firstName",
+      "age",
+      "status",
+      "email",
+      "salary",
+      "joinDate",
+    ]);
+  });
+
+  it("maps column field types to filter types and carries select options", () => {
+    const fields = resolveFilterFields(columns, hiddenFields);
+    const byId = Object.fromEntries(fields.map((f) => [f.id, f]));
+    expect(byId.firstName.type).toBe("text");
+    expect(byId.age.type).toBe("number");
+    expect(byId.status.type).toBe("select");
+    expect(byId.status.options).toHaveLength(2);
+    expect(byId.email.type).toBe("text"); // default
+    expect(byId.salary.type).toBe("number");
+  });
+
+  it("lets a declared field override the column-derived descriptor by id", () => {
+    const fields = resolveFilterFields(columns, [
+      { id: "age", label: "Age (years)", type: "text" },
+    ]);
+    const age = fields.find((f) => f.id === "age");
+    expect(age?.label).toBe("Age (years)");
+    expect(age?.type).toBe("text");
+    // Position preserved (still grouped with columns)
+    expect(fields.findIndex((f) => f.id === "age")).toBe(1);
+  });
+
+  it("skips columns with filterable: false", () => {
+    const fields = resolveFilterFields([
+      { accessorKey: "a", header: "A" },
+      { accessorKey: "b", header: "B", filterable: false },
+    ]);
+    expect(fields.map((f) => f.id)).toEqual(["a"]);
+  });
+});
+
+describe("applyFiltersToData (hidden / non-column fields)", () => {
+  const fields = resolveFilterFields(columns, hiddenFields);
+
+  it("filters on a field with no visible column (text contains)", () => {
+    const out = applyFiltersToData(rows, [filter("email", "contains", "corp")], fields);
+    expect(out.map((r) => r.firstName)).toEqual(["Ada", "Grace"]);
+  });
+
+  it("filters numbers with comparison operators", () => {
+    const out = applyFiltersToData(rows, [filter("salary", "isGreaterThan", "95")], fields);
+    expect(out.map((r) => r.firstName)).toEqual(["Grace", "Alan"]);
+  });
+
+  it("filters dates with before/after", () => {
+    const out = applyFiltersToData(rows, [filter("joinDate", "isBefore", "2020-06-01")], fields);
+    expect(out.map((r) => r.firstName)).toEqual(["Grace", "Alan"]);
+  });
+
+  it("treats select fields as text comparisons", () => {
+    const out = applyFiltersToData(rows, [filter("status", "is", "active")], fields);
+    expect(out.map((r) => r.firstName)).toEqual(["Ada", "Alan"]);
+  });
+
+  it("ANDs multiple filters together", () => {
+    const out = applyFiltersToData(
+      rows,
+      [filter("status", "is", "active"), filter("salary", "isGreaterThan", "95")],
+      fields,
+    );
+    expect(out.map((r) => r.firstName)).toEqual(["Alan"]);
+  });
+
+  it("returns data unchanged when there are no filters", () => {
+    expect(applyFiltersToData(rows, [], fields)).toBe(rows);
+  });
+
+  it("handles isEmpty / isNotEmpty without a value", () => {
+    const withEmpty = [...rows, { firstName: "Nia", email: "", age: 30 }];
+    const out = applyFiltersToData(withEmpty, [filter("email", "isEmpty", null)], fields);
+    expect(out.map((r) => r.firstName)).toEqual(["Nia"]);
+  });
+});
+
+describe("operator vocabulary", () => {
+  it("offers type-appropriate operators (same sets as the column funnel)", () => {
+    expect(operatorsForFilterType("text")).toContain("contains");
+    expect(operatorsForFilterType("text")).toContain("isEmpty");
+    expect(operatorsForFilterType("number")).toContain("isGreaterThan");
+    expect(operatorsForFilterType("number")).not.toContain("contains");
+    expect(operatorsForFilterType("date")).toContain("isBefore");
+    expect(operatorsForFilterType("boolean")).toEqual(["is", "isNot"]);
+    expect(operatorsForFilterType("select")).toContain("isAnyOf");
+  });
+
+  it("knows which operators carry no value", () => {
+    expect(operatorNeedsNoValue("isEmpty")).toBe(true);
+    expect(operatorNeedsNoValue("isNotEmpty")).toBe(true);
+    expect(operatorNeedsNoValue("contains")).toBe(false);
+  });
+
+  it("defaults text to contains and everything else to is", () => {
+    expect(defaultOperatorForFilterType("text")).toBe("contains");
+    expect(defaultOperatorForFilterType("number")).toBe("is");
+    expect(defaultOperatorForFilterType("select")).toBe("is");
+  });
+
+  it("labels operators in English (translated at render)", () => {
+    expect(filterOperatorLabel("contains")).toBe("Contains");
+    expect(filterOperatorLabel("isOnOrAfter")).toBe("On or after");
+  });
+});
+
+describe("getFilterChipLabel", () => {
+  it('reads "Field: operator value"', () => {
+    expect(getFilterChipLabel("Email", { operator: "contains", value: "corp" })).toBe(
+      "Email: contains corp",
+    );
+  });
+
+  it("omits the value for no-value operators", () => {
+    expect(getFilterChipLabel("Email", { operator: "isEmpty", value: null })).toBe(
+      "Email: is empty",
+    );
+  });
+
+  it("shows option labels instead of raw values for select fields", () => {
+    expect(
+      getFilterChipLabel("Status", { operator: "is", value: "active" }, [
+        { label: "Active", value: "active" },
+      ]),
+    ).toBe("Status: is Active");
+  });
+
+  it("joins multi-values", () => {
+    expect(
+      getFilterChipLabel("Status", { operator: "isAnyOf", value: null, values: ["a", "b"] }),
+    ).toBe("Status: is any of a, b");
+  });
+});
+
+describe("isFilterValueShape", () => {
+  it("detects FilterValue objects and rejects plain values", () => {
+    expect(isFilterValueShape({ operator: "contains", value: "x" })).toBe(true);
+    expect(isFilterValueShape("x")).toBe(false);
+    expect(isFilterValueShape(null)).toBe(false);
+    expect(isFilterValueShape(["a"])).toBe(false);
+  });
+});
+
+describe("mapFieldToFilterType / getFilterFieldType", () => {
+  it("maps cell field types to filter editor types", () => {
+    expect(mapFieldToFilterType("stepper")).toBe("number");
+    expect(mapFieldToFilterType("datepicker")).toBe("date");
+    expect(mapFieldToFilterType("switch")).toBe("boolean");
+    expect(mapFieldToFilterType("combobox")).toBe("select");
+    expect(mapFieldToFilterType(undefined)).toBe("text");
+  });
+
+  it("falls back to text for unknown field ids", () => {
+    expect(getFilterFieldType([], "nope")).toBe("text");
+  });
+});