@jielga/tmdatagrid 2.0.0-beta.13 → 2.0.0-beta.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jielga/tmdatagrid",
-  "version": "2.0.0-beta.13",
+  "version": "2.0.0-beta.14",
   "description": "A React data grid built on TanStack Table v9 and Mantine - always virtualized, with resizable, reorderable, sortable, filterable, hideable and pinnable columns.",
   "license": "MIT",
   "type": "module",

package/skills/appearance/SKILL.md

@@ -17,7 +17,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.13'
+  library_version: '2.0.0-beta.14'
 sources:
   - 'Jielga/TMDataGrid:src/docs/styling.md'
   - 'Jielga/TMDataGrid:src/docs/toolbar.md'

package/skills/cell-selection/SKILL.md

@@ -14,7 +14,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.13'
+  library_version: '2.0.0-beta.14'
 sources:
   - 'Jielga/TMDataGrid:src/docs/cell-selection.md'
   - 'Jielga/TMDataGrid:src/tmdatagrid/core/cellNavigation.ts'

package/skills/columns/SKILL.md

@@ -4,19 +4,19 @@ description: >
   Define and arrange TMDataGrid columns. Covers createTMDataGridColumnHelper,
   every column meta field (label, type, options, flex, align, autoSize,
   enableOrdering, and the meta.filter and meta.edit namespaces holding
-  defaultOperator, control, enabled, field, editor, validate and mapValue), the
-  six column types, fluid minmax sizing versus fixed width with minSize /
-  maxSize / size, autosizing and autosizeColumn, hiding through enableHiding and
-  the columns panel, pinning and why a pinned column becomes fixed-width,
-  ordering with enableColumnOrdering, meta.enableOrdering, moveColumn,
-  moveColumnByStep, getStepTargetColumn and the pinned regions, resetSettings,
-  sorting with multi-sort through isMultiSortEvent and a custom sortFn, and the
-  generated lanes. Load when adding or changing columns, controlling widths,
-  hiding, pinning, reordering or sorting them.
+  operators, defaultOperator, control, enabled, field, editor, validate and
+  mapValue), the six column types, fluid minmax sizing versus fixed width with
+  minSize / maxSize / size, autosizing and autosizeColumn, hiding through
+  enableHiding and the columns panel, pinning and why a pinned column becomes
+  fixed-width, ordering with enableColumnOrdering, meta.enableOrdering,
+  moveColumn, moveColumnByStep, getStepTargetColumn and the pinned regions,
+  resetSettings, sorting with multi-sort through isMultiSortEvent and a custom
+  sortFn, and the generated lanes. Load when adding or changing columns,
+  controlling widths, hiding, pinning, reordering or sorting them.
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.13'
+  library_version: '2.0.0-beta.14'
 sources:
   - 'Jielga/TMDataGrid:src/docs/columns.md'
   - 'Jielga/TMDataGrid:src/docs/column-layout.md'
@@ -97,7 +97,8 @@ which is why they are in neither.
 
 | Field | Type | Default | What it does |
 | --- | --- | --- | --- |
-| `defaultOperator` | `TMDataGridFilterOperator` | The type's default | The operator a fresh filter on this column starts with. |
+| `operators` | `readonly TMDataGridFilterOperator[]` | The type's list | The operators this column offers, a subset of its type's. For a backend that answers only some. |
+| `defaultOperator` | `TMDataGridFilterOperator` | The type's default, else the first offered | The operator a fresh filter on this column starts with. |
 | `control` | `TMDataGridFilterControlComponent` | By `meta.type` | Replaces the value control in this column's filter row. Module scope. |
 
 `meta.edit`:

package/skills/data/SKILL.md

@@ -15,7 +15,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.13'
+  library_version: '2.0.0-beta.14'
 sources:
   - 'Jielga/TMDataGrid:src/docs/pagination.md'
   - 'Jielga/TMDataGrid:src/docs/scrolling.md'

package/skills/editing/SKILL.md

@@ -18,7 +18,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.13'
+  library_version: '2.0.0-beta.14'
 sources:
   - 'Jielga/TMDataGrid:src/docs/editing.md'
   - 'Jielga/TMDataGrid:src/docs/query-builder.md'

package/skills/filtering/SKILL.md

@@ -3,9 +3,10 @@ name: filtering
 description: >
   Narrow the rows a TMDataGrid shows. Covers the shared tmDataGrid filter
   function and its {operator, value} model, the eighteen operators and which
-  meta.type offers each, meta.filter.defaultOperator, isFilterActive and the
-  half-typed filter, the filters option and its surfaces (popup, sidebar, none,
-  plus inHeader for header filters), TMDataGrid.FilterPanel and its layout prop,
+  meta.type offers each, meta.filter.operators to offer a column only a subset
+  of them, meta.filter.defaultOperator, isFilterActive and the half-typed
+  filter, the filters option and its surfaces (popup, sidebar, none, plus
+  inHeader for header filters), TMDataGrid.FilterPanel and its layout prop,
   TMDataGrid.FilterButton, TMDataGrid.FilterPills with its api prop,
   openColumnFilter, replacing a value control with DgRangeSliderFilter /
   DgDateRangeFilter / DgAutocompleteFilter / DgTriStateFilter or a
@@ -17,7 +18,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.13'
+  library_version: '2.0.0-beta.14'
 sources:
   - 'Jielga/TMDataGrid:src/docs/filtering.md'
   - 'Jielga/TMDataGrid:src/docs/quick-search.md'
@@ -84,6 +85,25 @@ columnHelper.accessor("salary", {
 });
 ```
 
+`meta.filter.operators` narrows the list a column offers to a subset of its
+type's - for a column whose backend answers only some operators, so the user is
+never offered one the query cannot express. The panel dropdown and the header
+funnel show only those, in the type's order. An operator the type does not
+offer is ignored; a list that leaves nothing falls back to the type's full set.
+Without `defaultOperator`, a fresh filter opens on the type's default when it is
+offered, else on the first offered operator.
+
+```tsx
+columnHelper.accessor("customer", {
+  header: "Customer",
+  meta: { filter: { operators: ["contains", "equals", "isEmpty", "isNotEmpty"] } },
+});
+```
+
+`getColumnOperators(column)` returns the resolved list and
+`getColumnDefaultOperator(column)` the operator a fresh filter opens on. The
+`server-side` skill shows the list typed together with the API mapping table.
+
 ## The filters option
 
 `filters` on `useTMDataGrid` picks the surface. It is read field by field, so a
@@ -400,7 +420,8 @@ Source: `src/docs/quick-search.md` (Fuzzy by default).
 | `enableColumnFilters` | Table option | `boolean` | `true` | `false` removes the panel, the button and the menu item. |
 | `enableColumnFilter` | Column option | `boolean` | `true` | `false` takes one column out of filtering. |
 | `meta.type` | Column meta | `TMDataGridColumnType` | `"string"` | Selects the operators and the value control. |
-| `meta.filter.defaultOperator` | Column meta | `TMDataGridFilterOperator` | The type's default | The operator a fresh filter opens on. |
+| `meta.filter.operators` | Column meta | `readonly TMDataGridFilterOperator[]` | The type's list | The operators this column offers, a subset of its type's. |
+| `meta.filter.defaultOperator` | Column meta | `TMDataGridFilterOperator` | The type's default, else the first offered | The operator a fresh filter opens on. |
 | `meta.filter.control` | Column meta | `TMDataGridFilterControlComponent` | By type and operator | Replaces the value control. Module scope. |
 | `filterFn` | Column option | name or fn | `"tmDataGrid"` | Custom matching for one column. |
 | `quickSearchMode` | Option | `"fuzzy" \| "contains"` | `"fuzzy"` | How the quick search matches. |
@@ -418,6 +439,7 @@ Source: `src/docs/quick-search.md` (Fuzzy by default).
 | `isFilterActive` | Export | `(value) => boolean` | – | Whether a filter value narrows anything. |
 | `activeColumnFilters` | Export | `(columnFilters \| table) => Array<{ id, value }>` | – | The filters in the grid's own value shape that narrow anything, typed. |
 | `getOperatorsForType` | Export | `(type) => operators` | – | The operator list a type offers. |
+| `getColumnOperators` · `getColumnDefaultOperator` | Exports | `(column) => operators` · `(column) => operator` | – | One column's list after `meta.filter.operators`, and the operator a fresh filter on it opens on. |
 | `FILTER_OPERATOR_LABELS` | Export | record | – | The label shown for each operator. |
 | `formatFilterLabel` | Export | `({ label, type, filter }) => string` | – | The one-line description used on the pills. |
 | `emptyValueForOperator` · `operatorNeedsValue` · `operatorTakesArrayValue` · `operatorTakesRangeValue` | Exports | – | – | What shape of value an operator expects. |

package/skills/getting-started/SKILL.md

@@ -11,7 +11,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.13'
+  library_version: '2.0.0-beta.14'
 sources:
   - 'Jielga/TMDataGrid:src/docs/getting-started.md'
   - 'Jielga/TMDataGrid:src/docs/anatomy.md'

package/skills/grouping/SKILL.md

@@ -14,7 +14,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.13'
+  library_version: '2.0.0-beta.14'
 sources:
   - 'Jielga/TMDataGrid:src/docs/grouping.md'
   - 'Jielga/TMDataGrid:src/docs/summary-row.md'

package/skills/options/SKILL.md

@@ -14,7 +14,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.13'
+  library_version: '2.0.0-beta.14'
 sources:
   - 'Jielga/TMDataGrid:src/docs/use-tm-data-grid.md'
   - 'Jielga/TMDataGrid:src/tmdatagrid/useTMDataGrid.tsx'

package/skills/rows/SKILL.md

@@ -17,7 +17,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.13'
+  library_version: '2.0.0-beta.14'
 sources:
   - 'Jielga/TMDataGrid:src/docs/row-selection.md'
   - 'Jielga/TMDataGrid:src/docs/row-interaction.md'

package/skills/server-side/SKILL.md

@@ -4,16 +4,21 @@ description: >
   Drive TMDataGrid from a server with TanStack manual modes - manualPagination,
   manualSorting, manualFiltering, rowCount, controlled state and onXChange
   callbacks. Covers the loading and totalRowCount meta fields, forwarding the
-  plain-JSON columnFilters model to an API with activeColumnFilters, the
-  first-page reset on a query change, persistence interaction, and row selection
-  across pages. Load when the grid is backed by a paginated API rather than a
-  local array.
+  plain-JSON columnFilters model to an API with activeColumnFilters, mapping
+  filters, sorting and the page index onto an endpoint's own query language
+  (field table, operator table, the three value shapes, meta.filter.operators
+  for an endpoint that answers only some operators, keying the fetch on the
+  request, paging against a page envelope), the first-page reset on a query
+  change, persistence interaction, and row selection across pages. Load when the
+  grid is backed by a paginated API rather than a local array, or when
+  translating grid filters into server-side queries.
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.13'
+  library_version: '2.0.0-beta.14'
 sources:
   - 'Jielga/TMDataGrid:src/docs/server-side.md'
+  - 'Jielga/TMDataGrid:src/docs/server-query.md'
   - 'Jielga/TMDataGrid:src/tmdatagrid/useTMDataGrid.tsx'
 ---
 
@@ -124,6 +129,118 @@ value - a custom filter control writing raw values - is dropped.
 
 Debounce requests. The filter value input updates on every keystroke.
 
+## Mapping onto the endpoint's query language
+
+An API takes a request body of its own: its own field names, its own operator
+set, its own status codes, and pages counted from 1. The layer between the
+grid's state and that body is one function over two lookup tables, plus one
+function on the way back:
+
+- **A field table** keyed by column id, giving the API field and the cast from
+  the string every filter control writes to the type the field holds
+  (`Number`, an enum code). A column missing from the table is one the API
+  cannot query: the mapping drops the filter rather than sending a field the
+  endpoint would reject.
+- **An operator table** from `TMDataGridFilterOperator` to the API's operators.
+  Several grid operators collapse onto one - a date `before` and a number
+  `lessThan` are both `lt` once the value is cast. Declare it as a `Record`, not
+  a `Partial`, so an operator added by a later grid version fails the build
+  here rather than reaching the server unmapped.
+- **`toRow`** from the API's record to the grid's row type.
+
+```ts
+const QUERY_FIELDS: Record<string, { field: string; cast: (raw: string) => string | number }> = {
+  id: { field: "orderRef", cast: Number },
+  amount: { field: "totalAmount", cast: Number },
+  status: { field: "status", cast: (raw) => STATUS_CODES[raw] ?? raw },
+};
+
+const PREDICATE_OPS: Record<TMDataGridFilterOperator, PredicateOp> = {
+  contains: "like",
+  between: "range",
+  before: "lt",
+  lessThan: "lt",
+  isAnyOf: "in",
+  isEmpty: "isNull",
+  // ...one line for every remaining operator.
+};
+```
+
+### The three value shapes
+
+`TMDataGridFilterValue` is `{ operator, value }`, and the operator decides what
+`value` holds. Branch on all four cases, in this order:
+
+| Operator | `value` | Sent as |
+| --- | --- | --- |
+| `isEmpty`, `isNotEmpty` | Not used | `{ field, op }` |
+| `isAnyOf`, `isNoneOf` | `ReadonlyArray<string>` | `{ field, op, values }` |
+| `between` | `[min, max]`, either end possibly `""` | `{ field, op, from?, to? }` |
+| Everything else | `string` | `{ field, op, value }` |
+
+An empty end of a `between` pair leaves that side open: an absent bound, not an
+empty string. Run `activeColumnFilters` over the slice first so a half-typed
+filter is not sent as a predicate that narrows the result to nothing.
+
+### An endpoint that answers only some operators
+
+Most endpoints do not have every operator the grid has - `like` and `eq` but no
+prefix match is common. Do not offer what you would have to drop.
+`meta.filter.operators` narrows the column to the operators the query can
+express, and the mapping table is declared over exactly that list, so one
+cannot be offered without a mapping or mapped without being offered:
+
+```ts
+const TEXT_OPERATORS = [
+  "contains",
+  "equals",
+  "isEmpty",
+  "isNotEmpty",
+] as const satisfies readonly TMDataGridFilterOperator[];
+
+const TEXT_OPS: Record<(typeof TEXT_OPERATORS)[number], PredicateOp> = {
+  contains: "like",
+  equals: "eq",
+  isEmpty: "isNull",
+  isNotEmpty: "isNotNull",
+};
+
+columnHelper.accessor("customer", {
+  header: "Customer",
+  meta: { filter: { operators: TEXT_OPERATORS } },
+});
+```
+
+A fresh filter opens on `meta.filter.defaultOperator` when set, else on the
+type's default when the list holds it, else on the first entry. The lookup at
+the boundary still returns `undefined` for an unmapped operator: a filter
+restored by `persist` from before the list was narrowed can carry one.
+
+### Keying the fetch on the request
+
+Serialize the request with `JSON.stringify` inside `useMemo` over
+`columnFilters`, `sorting` and `pagination`, and key the fetch effect (or the
+TanStack Query `queryKey`) on that string. Opening the panel and adding an
+empty row moves `columnFilters` but leaves the request unchanged, so nothing is
+sent. The effect owes the server a debounce (the value input updates on every
+keystroke) and a cancel (a `cancelled` flag in the cleanup, or an
+`AbortController` on a real `fetch`).
+
+### Paging against a page envelope
+
+| The API's | The grid's | Written as |
+| --- | --- | --- |
+| `page.number`, counted from 1 | `pagination.pageIndex`, counted from 0 | `number: pageIndex + 1` |
+| `page.totalItems`, the matched count | `rowCount` | `rowCount: page?.totalItems ?? 0` |
+| `page.totalPages` | `state.pageCount`, derived from `rowCount / pageSize` | Nothing; the grid computes it |
+
+Forward `totalPages` only when the server pages by something other than the
+size the grid asked for. `pageCount: -1` when the total is unknown. Show the
+page number through the Footer's `renderPagination` slot with
+`<Controls.PageSize /><Controls.PageNumber /><Controls.Pager />`.
+`meta.totalRowCount` is the unfiltered total, which no filtered response
+carries: take it from a separate count call.
+
 ## Persistence
 
 `persist` works unchanged. `dataKey` restores filters, sorting and pagination
@@ -168,6 +285,13 @@ current page, so the grid renders the matched count alone rather than a
 plausible-looking wrong total. Pass the unfiltered total as
 `meta.totalRowCount` to get the "42 / 5000" form back.
 
+### Offering operators the endpoint cannot answer
+
+The panel offers every operator of the column's type, and a mapping that drops
+`startsWith` leaves the user with a filter that silently does nothing. Declare
+`meta.filter.operators` on the column with the operators the endpoint answers,
+and type the operator table over that same list.
+
 ### Unstable getRowId across pages
 
 Defaulting to the row index means row 0 of page 2 shares an id with row 0 of

package/skills/testing/SKILL.md

@@ -11,7 +11,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.13'
+  library_version: '2.0.0-beta.14'
 sources:
   - 'Jielga/TMDataGrid:src/docs/testing.md'
   - 'Jielga/TMDataGrid:src/tmdatagrid/components/TMDataGrid.tsx'

package/src/tmdatagrid/components/TMDataGrid.tsx

@@ -55,26 +55,7 @@ export type TMDataGridProps<TData extends RowData> = TMDataGridApi<TData> & {
   "data-testid"?: string;
 };
 
-/**
- * Root of the grid. Takes the object returned by `useTMDataGrid` - spread it -
- * and publishes it to the compound components below it:
- *
- * ```tsx
- * const grid = useTMDataGrid({ data, columns });
- *
- * <TMDataGrid {...grid}>
- *   <TMDataGrid.Toolbar>
- *     <TMDataGrid.SummaryCount />
- *     <TMDataGrid.Spacer />
- *     <TMDataGrid.Menu>
- *       <TMDataGrid.Menu.Columns />
- *     </TMDataGrid.Menu>
- *   </TMDataGrid.Toolbar>
- *   <TMDataGrid.Table />
- *   <TMDataGrid.Footer />
- * </TMDataGrid>
- * ```
- */
+// Documented on the `TMDataGrid` export below.
 function TMDataGridRoot<TData extends RowData>({
   table,
   ui,
@@ -150,6 +131,26 @@ function TMDataGridRoot<TData extends RowData>({
   );
 }
 
+/**
+ * Root of the grid. Takes the object returned by `useTMDataGrid` - spread it -
+ * and publishes it to the compound components below it:
+ *
+ * ```tsx
+ * const grid = useTMDataGrid({ data, columns });
+ *
+ * <TMDataGrid {...grid}>
+ *   <TMDataGrid.Toolbar>
+ *     <TMDataGrid.SummaryCount />
+ *     <TMDataGrid.Spacer />
+ *     <TMDataGrid.Menu>
+ *       <TMDataGrid.Menu.Columns />
+ *     </TMDataGrid.Menu>
+ *   </TMDataGrid.Toolbar>
+ *   <TMDataGrid.Table />
+ *   <TMDataGrid.Footer />
+ * </TMDataGrid>
+ * ```
+ */
 export const TMDataGrid = Object.assign(TMDataGridRoot, {
   Toolbar: TMDataGridToolbar,
   Spacer: TMDataGridToolbarSpacer,

package/src/tmdatagrid/components/TMDataGridFilterPanel.tsx

@@ -5,6 +5,7 @@ import classes from "./TMDataGridFilterPanel.module.css";
 import { useTMDataGridContext } from "../TMDataGridContext";
 import {
   getColumnDefaultOperator,
+  getColumnOperators,
   getColumnLabel,
   getColumnType,
 } from "../core/columnUtils";
@@ -251,7 +252,10 @@ export function TMDataGridFilterPanel({
                   w={stacked ? "100%" : 170}
                   allowDeselect={false}
                   data-dg-part="filter-operator"
-                  data={getOperatorsForType(type).map((operator) => ({
+                  data={(column
+                    ? getColumnOperators(column)
+                    : getOperatorsForType(type)
+                  ).map((operator) => ({
                     value: operator,
                     label: labels.operators[operator],
                   }))}

package/src/tmdatagrid/components/TMDataGridHeaderFilterRow.tsx

@@ -7,7 +7,7 @@ import { useTMDataGridContext } from "../TMDataGridContext";
 import {
   getColumnDefaultOperator,
   getColumnLabel,
-  getColumnType,
+  getColumnOperators,
   isControlColumn,
 } from "../core/columnUtils";
 import {
@@ -15,7 +15,6 @@ import {
   type TMDataGridFilterValue,
   emptyValueForOperator,
   filterValueShape,
-  getOperatorsForType,
   isTMDataGridFilterValue,
 } from "../core/filterOperators";
 import { FilterIcon } from "./icons";
@@ -54,7 +53,6 @@ function HeaderFilterControl({ column }: { column: TMDataGridHeader["column"] })
     (state) => state.columnFilters.find((filter) => filter.id === column.id)?.value,
   );
 
-  const type = getColumnType(column);
   const defaultOperator = getColumnDefaultOperator(column);
   const current = isTMDataGridFilterValue(filterValue) ? filterValue : undefined;
   const operator = current?.operator ?? defaultOperator;
@@ -104,7 +102,7 @@ function HeaderFilterControl({ column }: { column: TMDataGridHeader["column"] })
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [table, column, facetKey],
   );
-  const operators = getOperatorsForType(type);
+  const operators = getColumnOperators(column);
 
   return (
     <>

package/src/tmdatagrid/components/TMDataGridMenu.tsx

@@ -44,16 +44,7 @@ export type TMDataGridMenuColumnsProps = {
   searchable?: boolean;
 };
 
-/**
- * Burger menu in the grid's top-right corner, holding whatever the consumer
- * puts in it. Every Mantine `Menu` prop is accepted and wins over the defaults
- * below.
- *
- * It always renders. It cannot know whether its children render anything, so
- * a menu holding only `TMDataGrid.Menu.Columns` on a grid where nothing can be
- * hidden still shows its button over an empty dropdown - leave the menu out of
- * the toolbar in that case.
- */
+// Documented on the `TMDataGridMenu` export below.
 function TMDataGridMenuRoot({
   children,
   icon,
@@ -247,6 +238,16 @@ export function TMDataGridMenuResetLayout() {
   );
 }
 
+/**
+ * Burger menu in the grid's top-right corner, holding whatever the consumer
+ * puts in it. Every Mantine `Menu` prop is accepted and wins over the defaults
+ * below.
+ *
+ * It always renders. It cannot know whether its children render anything, so
+ * a menu holding only `TMDataGrid.Menu.Columns` on a grid where nothing can be
+ * hidden still shows its button over an empty dropdown - leave the menu out of
+ * the toolbar in that case.
+ */
 export const TMDataGridMenu = Object.assign(TMDataGridMenuRoot, {
   Columns: TMDataGridMenuColumns,
   ColumnToggles: TMDataGridMenuColumnToggles,

package/src/tmdatagrid/core/columnUtils.ts

@@ -1,6 +1,7 @@
 import type { Row } from "@tanstack/react-table";
 import {
   getDefaultOperator,
+  getOperatorsForType,
   type TMDataGridColumnType,
   type TMDataGridFilterOperator,
 } from "./filterOperators";
@@ -37,17 +38,36 @@ export function getColumnType(column: ColumnLike): TMDataGridColumnType {
   return column.columnDef.meta?.type ?? "string";
 }
 
+/**
+ * The operators this column offers: the type's list, narrowed to
+ * `meta.filter.operators` when the column declares one. The type's order is
+ * kept so the menu reads the same on every column; an operator the type does
+ * not offer is dropped, and an allowlist that leaves nothing falls back to the
+ * type's full list rather than an empty menu.
+ */
+export function getColumnOperators(
+  column: ColumnLike,
+): readonly TMDataGridFilterOperator[] {
+  const offered = getOperatorsForType(getColumnType(column));
+  const allowed = column.columnDef.meta?.filter?.operators;
+  if (!allowed) return offered;
+  const narrowed = offered.filter((operator) => allowed.includes(operator));
+  return narrowed.length > 0 ? narrowed : offered;
+}
+
 /**
  * The operator a fresh filter on this column starts with -
- * `meta.filter.defaultOperator`, else the type's default.
+ * `meta.filter.defaultOperator`, else the type's default where the column
+ * offers it, else the first operator it does offer.
  */
 export function getColumnDefaultOperator(
   column: ColumnLike,
 ): TMDataGridFilterOperator {
-  return (
-    column.columnDef.meta?.filter?.defaultOperator ??
-    getDefaultOperator(getColumnType(column))
-  );
+  const declared = column.columnDef.meta?.filter?.defaultOperator;
+  if (declared) return declared;
+  const offered = getColumnOperators(column);
+  const typeDefault = getDefaultOperator(getColumnType(column));
+  return offered.includes(typeDefault) ? typeDefault : offered[0];
 }
 
 /**

package/src/tmdatagrid/core/filterControls.ts

@@ -86,10 +86,19 @@ export type TMDataGridFilterControlComponent =
  * declaration of each feeds the filter panel and the cell editor alike.
  */
 export type TMDataGridColumnFilterOptions = {
+  /**
+   * The operators this column offers, a subset of the type's own. For a
+   * column backed by an endpoint that answers only some of them - `contains`
+   * and `equals`, say - so the panel and the header funnel never offer an
+   * operator the query cannot express. Kept in the type's order; one the type
+   * does not offer is ignored, and a list that leaves nothing falls back to
+   * the type's full set.
+   */
+  operators?: readonly TMDataGridFilterOperator[];
   /**
    * The operator a fresh filter on this column starts with, instead of the
    * type's default - a salary column can open on `"between"`. Must be one of
-   * the type's own operators.
+   * the operators the column offers.
    */
   defaultOperator?: TMDataGridFilterOperator;
   /**

package/src/tmdatagrid/index.ts

@@ -147,6 +147,7 @@ export { TMDATAGRID_LABELS_SV } from "./core/labelsSv";
 export {
   getColumnDefaultOperator,
   getColumnFilterControl,
+  getColumnOperators,
   getColumnLabel,
   getColumnType,
   isColumnEditableForRow,

package/src/tmdatagrid/useTMDataGrid.tsx

@@ -186,8 +186,8 @@ export type TMDataGridColumnMeta = {
    */
   enableOrdering?: boolean;
   /**
-   * How this column filters: the operator a fresh filter starts with, and the
-   * value control the filter panel renders for it.
+   * How this column filters: which operators it offers, the operator a fresh
+   * filter starts with, and the value control the filter panel renders for it.
    *
    * ```tsx
    * meta: {