@object-ui/core 17.5.0 → 17.7.0

package/dist/utils/expand-fields.js

@@ -8,21 +8,181 @@
 import { columnIdentity } from './column-identity.js';
 /**
  * Relational ("reference-bearing") field types whose stored value is a foreign
- * key into another object — and which therefore benefit from `$expand` so a
- * list / grid / detail cell can render the related record's display name
- * instead of a bare id placeholder ("—").
- *
- * This mirrors the form layer's `DATA_SOURCE_FIELD_TYPES`
- * (`lookup` / `master_detail` / `tree`) and additionally covers `user` — a
- * lookup specialised to `sys_user`. The server resolves `user` through the
- * same expand path as `lookup` / `master_detail` (it carries the same
- * `reference` + id storage), so a `user` column that is NOT requested for
- * expansion comes back as a raw user id and renders as "—". Keeping the set
- * here as the single source of truth is what closes that gap.
+ * key into another object — and which therefore benefit from `$expand`, so a
+ * response carries the related record instead of only its foreign key.
+ *
+ * `user` is a lookup specialised to `sys_user`: it carries the same `reference`
+ * + id storage and the server resolves it through the same expand path as
+ * `lookup` / `master_detail`, so a `user` column that is NOT requested for
+ * expansion comes back as a raw user id (objectui#2032). What a CELL then
+ * prints for that id is deliberately not stated here — see the next section.
+ *
+ * ## No rendering claim is made here, on purpose — objectui#8693
+ *
+ * Both paragraphs above used to make one: the `user` sentence ended "…and
+ * renders as '—'", and the opening one called the unexpanded cell "a bare id
+ * placeholder ('—')". Measured on `da5e4f69e` by resolving each family through
+ * `getCellRenderer` and rendering three unexpanded primitives:
+ *
+ * | unexpanded value     | `lookup` / `master_detail` / `tree` | `user`             |
+ * |----------------------|-------------------------------------|--------------------|
+ * | `'u_1'`              | `u_1`, plain truncated span         | `u_1`, same span   |
+ * | `'01HQZX9K2M4N6P8R'` | muted `—`                           | the raw ULID       |
+ * | `'Ada Lovelace'`     | `Ada Lovelace`, plain span          | the raw string     |
+ *
+ * Wrong twice over. `user` never drew the em-dash at all — `UserCellRenderer`
+ * has no resolver, no `useLookupName`, no `isLikelyOpaqueId`. And the three
+ * families that do draw it draw it ONLY for values `isLikelyOpaqueId` accepts;
+ * that qualifier is the entire content of the behaviour and the sentence never
+ * carried it, so a reader was told a human-readable id would degrade visibly
+ * when it printed as if it were a name — the defect objectui#8434 was for.
+ *
+ * It is not replaced by a corrected sentence, because a corrected sentence
+ * could not be kept true HERE. `@object-ui/core` does not depend on
+ * `@object-ui/fields` in `dependencies`, `peerDependencies` or
+ * `devDependencies` — the arrow runs the other way — so no test that can reach
+ * this file can render the cell it would describe, and nothing in this repo
+ * compares a docblock to rendered output. A replacement would be checked by
+ * whatever checked the last one: nobody. Its shelf life was measured too —
+ * while objectui#8693 was open, PR #8698 (objectui#8434) sat in the merge
+ * queue rewriting the `user` column of that very table: on its head
+ * `3692f7218` all three primitives render an unresolved-reference affordance
+ * that KEEPS the raw value. A corrected sentence would have been stale before
+ * it landed. The other three families are byte-identical on both trees.
+ *
+ * The storage claim is the half this set actually depends on, and that half IS
+ * checkable here (`__tests__/expand-fields.test.ts`, plus the identity pins
+ * below). How an unexpanded reference prints belongs next to the renderers in
+ * `@object-ui/fields`, where a test can fail.
  *
  * Note on `tree`: a self-referencing hierarchy field is a reference too, so it
  * belongs in this set; whether the backend materialises the expanded object
  * for it is a server concern — requesting it is harmless and forward-compatible.
+ *
+ * ## One family, many consumers — and NO reliable count of them
+ *
+ * This section used to open "One family, four consumers" and enumerate four.
+ * That count was hand-kept, and hand-kept counts of this table are exactly what
+ * keeps going wrong: it was already stale by two when objectui#5692 measured it
+ * (`paramToField` in `app-shell` had joined with objectui#5312, and
+ * `ListView`'s relational-sort rule reads the set directly), and objectui#5312's
+ * claim to have converted "the LAST private copy" was false by two MORE — see
+ * the falsification note at the end. Read the list below as the lineage of the
+ * conversions, not as a census; the mechanical fact is the identity pins.
+ *
+ * Re-measured for objectui#8693 on `da5e4f69e`: stale again, by FOUR. The
+ * commit that corrected the "fourth and last" claim (objectui#5874 / #6064)
+ * converged four more private copies of its own and never added them here —
+ * the last four bullets below. Re-derive before trusting it; the recipe is at
+ * the end of the list.
+ *
+ * This is the reference-bearing FAMILY, not the `$expand` builder's private
+ * list, and these concerns read it under several different words:
+ *
+ *  - `$expand` construction — `buildExpandFields` below ("expandable");
+ *  - predicate-record projection — `predicate-record.ts` ("relational");
+ *  - the object form's data-source wiring — `needsDataSourceWiring` in
+ *    `packages/components/src/renderers/form/form.tsx`, which decides which
+ *    registered widget gets `dataSource` / `dependentValues` /
+ *    `dependsOnLabels` threaded to it;
+ *  - the grid's bulk-action dialog — `widgetNeedsDataSource` in
+ *    `packages/plugin-grid/src/components/bulkParamToField.ts`, which decides
+ *    which param widget is handed the grid's `DataSource` and which param field
+ *    shape carries `reference` / `displayField`;
+ *  - the action-param dialog — `paramToField` in
+ *    `packages/app-shell/src/utils/paramToField.ts`, which decides which param
+ *    carries a reference target (objectui#5312);
+ *  - the list view's relational-sort rule — `ListView.tsx`, which will not offer
+ *    a server-side sort on a field whose stored value is a foreign key;
+ *  - the dashboard table's `$expand` whitelist — `computeLookupExpand` in
+ *    `packages/plugin-dashboard/src/ObjectDataTable.tsx` (objectui#5692);
+ *  - the dashboard's relation/link test — `isLookupType` in
+ *    `packages/plugin-dashboard/src/recordFields.tsx` (objectui#5692);
+ *  - the action-param RESOLVER (one step before `paramToField`) —
+ *    `packages/app-shell/src/utils/resolveActionParams.ts` (objectui#5874);
+ *  - the detail header's relation test — `HeaderHighlight.tsx` in
+ *    `packages/plugin-detail` (objectui#5874);
+ *  - the detail drawer's relation test — `RecordDetailDrawer.tsx` in
+ *    `packages/plugin-detail`, reading through `isExpandableFieldType`
+ *    (objectui#5874);
+ *  - the kanban board's `$expand` — `ObjectKanban.tsx` in
+ *    `packages/plugin-kanban`, reading through `buildExpandFields`
+ *    (objectui#5874).
+ *
+ * ⚠️ Re-derive rather than trust. One command, from the repo root, over the
+ * whole tree with NO pathspec. (Narrowing it to `packages/` + a `*` segment +
+ * `/src` matches ZERO files, and would drop `apps/` besides. The two-character
+ * sequence is spelled out in words here because writing it literally would end
+ * this comment.)
+ *
+ *     git grep -lE 'EXPANDABLE_FIELD_TYPES|isExpandableFieldType|buildExpandFields'
+ *
+ * 96 files on `da5e4f69e`. Drop tests, changesets and changelogs and the
+ * production readers fall into three radii, only the first of which the list
+ * above is about: this file plus 8 more naming the set directly, plus 4 more
+ * calling `isExpandableFieldType`, plus 13 more calling `buildExpandFields`.
+ * The sweep was controlled by planting a reader under `apps/console/src/` and
+ * confirming the same command found it — `apps/` holds no reader today, and a
+ * zero-hit region is otherwise indistinguishable from a blind spot.
+ *
+ * The third one used to be a second hand-maintained copy, and this comment used
+ * to claim the set "mirrors the form layer's `DATA_SOURCE_FIELD_TYPES`
+ * (`lookup` / `master_detail` / `tree`)". That was true for 15 days. The form's
+ * copy then gained `capability-multiselect` (objectui#2403) and, the same day,
+ * `object-ref` / `filter-condition` / `recipient-picker` (objectui#2421), after
+ * which the two sets were not in a subset relation in EITHER direction — `user`
+ * only here, three picker names only there — and no gate could say so
+ * (objectui#4790). The form now DERIVES from this set instead of restating it:
+ *
+ *     form's data-source rule  ==  EXPANDABLE_FIELD_TYPES
+ *                                  + three widget-hint-only picker names
+ *
+ * The extension is one-directional and cannot fold back into this set:
+ * `object-ref` / `filter-condition` / `recipient-picker` are widget HINTS, never
+ * declarable field types (`widgetHintOnly: true` in
+ * `app-shell/src/utils/paramValueShape.ts`), so no object schema can produce a
+ * field whose `type` is one of them.
+ *
+ * The fourth was a hand-maintained copy too, one member set removed from BOTH
+ * of the above (`lookup` / `master_detail` / `user` — no `tree`, no pickers, and
+ * for a while a fifth spelling, `owner`, that objectui#4814 retired). It now
+ * derives from this set with NO extension, because the bulk dialog's params
+ * cannot produce the three widget-hint names (objectui#4815):
+ *
+ *     bulk dialog's data-source rule  ==  EXPANDABLE_FIELD_TYPES
+ *
+ * Neither consumer copies the set — both call `.has()` on THIS object, and both
+ * carry an identity pin (a spy on this `has`) so a member-identical private copy
+ * fails rather than quietly re-forking the table.
+ *
+ * ## The "LAST private copy" claim was false — objectui#5692
+ *
+ * objectui#5312 converted `paramToField` (`app-shell`) and recorded it as the
+ * fourth and LAST private copy of this rule. `packages/plugin-dashboard` held
+ * two more the whole time — `LOOKUP_TYPES` in `recordFields.tsx` and an inline
+ * disjunction inside `computeLookupExpand` in `ObjectDataTable.tsx` — which
+ * predate that sweep and were outside its file surface, so nothing contradicted
+ * the claim. Both now derive from this set with NO extension and carry the same
+ * identity pin.
+ *
+ * Those two were NOT member-identical to this set, in either direction: they
+ * lacked `tree` and carried a fifth spelling, `reference`. Converging them was
+ * therefore a behaviour change in two directions, and the direction that could
+ * have widened THIS set was settled by measurement rather than by preference:
+ * `reference` is absent from `@objectstack/spec`'s closed `FieldType`
+ * vocabulary and is refused by `FieldSchema.safeParse` — measured with `lookup`
+ * / `master_detail` / `user` / `tree` as live controls and the retired `owner`
+ * plus a nonsense spelling as dead ones — so no spec-compliant object schema can
+ * declare a field whose stored type is `reference`, and the dashboard's copies
+ * were carrying a dead spelling, not a member this set was missing. This set is
+ * unchanged by objectui#5692; the two dashboard faces simply stopped answering
+ * for a type no producer can emit.
+ *
+ * Stated so it reads as a decision rather than a surprise: **adding a member
+ * here also grants that type the form's data-source wiring.** That is the
+ * intended coupling — a type whose stored value is a foreign key needs a
+ * `DataSource` to resolve that key on the read path (expand) and on the edit
+ * path (the picker) alike.
  */
 export const EXPANDABLE_FIELD_TYPES = new Set([
     'lookup',

package/dist/utils/extract-records.d.ts

@@ -6,11 +6,71 @@
  * LICENSE file in the root directory of this source tree.
  */
 /**
- * Extract an array of records from various API response formats.
- * Supports: raw array, { records: [] }, { data: [] }, { value: [] }.
+ * Extract the rows array out of a `DataSource.find()` answer.
  *
- * This utility normalises the different shapes returned by ObjectStack,
- * OData, and MSW mock endpoints so that every data-fetching component
- * can rely on a single extraction path.
+ * Accepted shapes, in the order they are tried:
+ *
+ *   1. a bare array — the live non-envelope shape fakes and `ValueDataSource`
+ *      answer with;
+ *   2. `{ data: [] }` — the ONE rows member `QueryResult` (`@object-ui/types`)
+ *      declares;
+ *   3. `{ value: [] }` — the OData spelling, still LIVE at this seam (see
+ *      below).
+ *
+ * ## `records` is NOT read here (objectui#6839, following #5945 / #6726)
+ *
+ * A `records` arm used to sit AHEAD of `data` — the precedence inversion
+ * objectui#5945 was filed about and objectui#6726 repaired by hand in seven
+ * modules. `records` is the below-the-adapter spelling: both
+ * `ObjectStackAdapter.normalizeQueryResult` (`@object-ui/data-objectstack`)
+ * and `ApiDataSource.normalizeQueryResult` (its `['data','items','results',
+ * 'records','value']` envelope loop) CONSUME the server/SDK `records` envelope
+ * and return `data` before the answer ever reaches this helper. Every consumer
+ * below calls it strictly ABOVE that fold, so the arm was unreachable — and an
+ * unreachable tolerant arm is exactly where a non-conforming producer keeps
+ * working unrejected (AGENTS.md #0.1). Worse, being FIRST, it outranked the
+ * contract's own member: a producer emitting both would have had `data`
+ * ignored.
+ *
+ * Measured on this tree, per consumer rather than once for all of them, since
+ * this helper is reached from ten call sites in nine packages:
+ *
+ *   packages/plugin-charts/src/ObjectChart.tsx        (x2: rows, ref labels)
+ *   packages/plugin-dashboard/src/ObjectDataTable.tsx
+ *   packages/plugin-dashboard/src/ObjectPivotTable.tsx
+ *   packages/plugin-gantt/src/ObjectGantt.tsx         (ref option labels)
+ *   packages/plugin-kanban/src/ObjectKanban.tsx
+ *   packages/plugin-timeline/src/ObjectTimeline.tsx
+ *   packages/core/src/utils/non-grid-row-ceiling.ts   (applyNonGridRowCeiling,
+ *     itself the seam for ObjectCalendar, ObjectGantt, ObjectMap, ObjectTree;
+ *     measured when it lived in `@object-ui/react`, moved here unchanged by
+ *     objectui#7508)
+ *
+ * ZERO of them can be reached by a `records` envelope: no `find()` in any of
+ * those packages, nor in the apps and examples that mount them, emits one.
+ * CONTROL, so the zero is a reading rather than a miss — the same sweep DOES
+ * find `records` envelopes elsewhere: `ViewDataProvider`'s own `ResolvedData`
+ * (a different contract, served by that module's own private reader), the raw
+ * Cloud HTTP payloads, the client-SDK doubles below `normalizeQueryResult`,
+ * the record-visibility batch route stubs, and one live `find()` double at
+ * `plugin-list`'s ObjectGallery — a consumer with its OWN unwrap ladder, which
+ * does not come through here.
+ *
+ * ⛔ Do not restore the arm, and ⛔ do not widen `QueryResult` to bless
+ * `records` instead — that is a published-type change and the maintainer's
+ * call, the same floor objectui#6726 and #6840 respected. A producer that
+ * really does speak `records` belongs behind an adapter that folds it into
+ * `data`, which is what both adapters above already do.
+ *
+ * ## `value` STAYS — it is live here, and that is seam-local
+ *
+ * objectui#6840 / PR #6916 deleted the `value` arm from `ObjectView`'s ladder
+ * on a measured zero at THAT seam, and said in as many words that its zero
+ * must not be carried here. It does not: five `find()` doubles emit
+ * `{ value: [...] }` into this helper today (three in `plugin-kanban`, two in
+ * `plugin-calendar`). Deleting it here would break them. Whether `value`
+ * should survive at this seam is its own card with its own measurement.
+ *
+ * Pinned per module by the `*.contractEnvelope-6839.*` suites.
  */
 export declare function extractRecords(results: unknown): any[];

package/dist/utils/extract-records.js

@@ -6,21 +6,78 @@
  * LICENSE file in the root directory of this source tree.
  */
 /**
- * Extract an array of records from various API response formats.
- * Supports: raw array, { records: [] }, { data: [] }, { value: [] }.
+ * Extract the rows array out of a `DataSource.find()` answer.
  *
- * This utility normalises the different shapes returned by ObjectStack,
- * OData, and MSW mock endpoints so that every data-fetching component
- * can rely on a single extraction path.
+ * Accepted shapes, in the order they are tried:
+ *
+ *   1. a bare array — the live non-envelope shape fakes and `ValueDataSource`
+ *      answer with;
+ *   2. `{ data: [] }` — the ONE rows member `QueryResult` (`@object-ui/types`)
+ *      declares;
+ *   3. `{ value: [] }` — the OData spelling, still LIVE at this seam (see
+ *      below).
+ *
+ * ## `records` is NOT read here (objectui#6839, following #5945 / #6726)
+ *
+ * A `records` arm used to sit AHEAD of `data` — the precedence inversion
+ * objectui#5945 was filed about and objectui#6726 repaired by hand in seven
+ * modules. `records` is the below-the-adapter spelling: both
+ * `ObjectStackAdapter.normalizeQueryResult` (`@object-ui/data-objectstack`)
+ * and `ApiDataSource.normalizeQueryResult` (its `['data','items','results',
+ * 'records','value']` envelope loop) CONSUME the server/SDK `records` envelope
+ * and return `data` before the answer ever reaches this helper. Every consumer
+ * below calls it strictly ABOVE that fold, so the arm was unreachable — and an
+ * unreachable tolerant arm is exactly where a non-conforming producer keeps
+ * working unrejected (AGENTS.md #0.1). Worse, being FIRST, it outranked the
+ * contract's own member: a producer emitting both would have had `data`
+ * ignored.
+ *
+ * Measured on this tree, per consumer rather than once for all of them, since
+ * this helper is reached from ten call sites in nine packages:
+ *
+ *   packages/plugin-charts/src/ObjectChart.tsx        (x2: rows, ref labels)
+ *   packages/plugin-dashboard/src/ObjectDataTable.tsx
+ *   packages/plugin-dashboard/src/ObjectPivotTable.tsx
+ *   packages/plugin-gantt/src/ObjectGantt.tsx         (ref option labels)
+ *   packages/plugin-kanban/src/ObjectKanban.tsx
+ *   packages/plugin-timeline/src/ObjectTimeline.tsx
+ *   packages/core/src/utils/non-grid-row-ceiling.ts   (applyNonGridRowCeiling,
+ *     itself the seam for ObjectCalendar, ObjectGantt, ObjectMap, ObjectTree;
+ *     measured when it lived in `@object-ui/react`, moved here unchanged by
+ *     objectui#7508)
+ *
+ * ZERO of them can be reached by a `records` envelope: no `find()` in any of
+ * those packages, nor in the apps and examples that mount them, emits one.
+ * CONTROL, so the zero is a reading rather than a miss — the same sweep DOES
+ * find `records` envelopes elsewhere: `ViewDataProvider`'s own `ResolvedData`
+ * (a different contract, served by that module's own private reader), the raw
+ * Cloud HTTP payloads, the client-SDK doubles below `normalizeQueryResult`,
+ * the record-visibility batch route stubs, and one live `find()` double at
+ * `plugin-list`'s ObjectGallery — a consumer with its OWN unwrap ladder, which
+ * does not come through here.
+ *
+ * ⛔ Do not restore the arm, and ⛔ do not widen `QueryResult` to bless
+ * `records` instead — that is a published-type change and the maintainer's
+ * call, the same floor objectui#6726 and #6840 respected. A producer that
+ * really does speak `records` belongs behind an adapter that folds it into
+ * `data`, which is what both adapters above already do.
+ *
+ * ## `value` STAYS — it is live here, and that is seam-local
+ *
+ * objectui#6840 / PR #6916 deleted the `value` arm from `ObjectView`'s ladder
+ * on a measured zero at THAT seam, and said in as many words that its zero
+ * must not be carried here. It does not: five `find()` doubles emit
+ * `{ value: [...] }` into this helper today (three in `plugin-kanban`, two in
+ * `plugin-calendar`). Deleting it here would break them. Whether `value`
+ * should survive at this seam is its own card with its own measurement.
+ *
+ * Pinned per module by the `*.contractEnvelope-6839.*` suites.
  */
 export function extractRecords(results) {
     if (Array.isArray(results)) {
         return results;
     }
     if (results && typeof results === 'object') {
-        if (Array.isArray(results.records)) {
-            return results.records;
-        }
         if (Array.isArray(results.data)) {
             return results.data;
         }

package/dist/utils/filter-converter.d.ts

@@ -23,6 +23,34 @@ export type FilterNode = [string, string, any] | [string, ...FilterNode[]];
  * @param operator - MongoDB-style operator (e.g., '$gte', '$in')
  * @returns ObjectStack operator or null if not recognized
  */
+/**
+ * What the refusal is ABOUT, as structured data rather than as prose to scrape.
+ *
+ * `message` already names both, but a renderer that wants to say "the
+ * $icontains condition cannot be applied" must not recover the token with a
+ * regular expression over an English paragraph that every one of these
+ * refusals deliberately writes differently. objectui#9050's step 2 requires the
+ * render-time diagnostic to NAME the operator, so the name travels as a field.
+ *
+ * `operator` is the spelling the AUTHOR wrote — `$startswith` for a retired
+ * alias, `icontains` for a view rule — never a canonical form substituted for
+ * it, for the reason the view-rule arm's own tail already gives: prescribing a
+ * spelling the author's vocabulary does not have sends them looking for a key
+ * their metadata cannot contain.
+ *
+ * It is OPTIONAL because some refusals are not about an operator at all: the
+ * bare-array and exotic-comparand arms judge a COMPARAND written in the
+ * implicit-equality position, and the empty-operator-map arm judges a field
+ * that names NO operator (`{ a: {} }`, objectui#9164). In each, no operator was
+ * spelled and `field` is the only handle the author can act on. A renderer
+ * reads {@link filterRefusalSubject} rather than choosing between them itself.
+ */
+export interface FilterRefusalSubject {
+    /** The operator spelling the author wrote, when the refusal is about one. */
+    operator?: string;
+    /** The field the refused condition is on, when the refusal is about one. */
+    field?: string;
+}
 /**
  * A filter operator this layer will not translate.
  *
@@ -34,8 +62,22 @@ export type FilterNode = [string, string, any] | [string, ...FilterNode[]];
 export declare class FilterOperatorError extends Error {
     readonly code = "INVALID_FILTER";
     readonly httpStatus = 400;
-    constructor(message: string);
+    /** @see FilterRefusalSubject */
+    readonly operator: string | undefined;
+    /** @see FilterRefusalSubject */
+    readonly field: string | undefined;
+    constructor(message: string, subject?: FilterRefusalSubject);
 }
+/**
+ * The one token a "this view's filter is malformed" state names.
+ *
+ * Operator first, because that is what the ruling asks the state to name and
+ * what an author can act on — `$regex` is not supported, `$startswith` is
+ * retired. Field second, for the refusals that have no operator to name — the
+ * two comparand arms and the empty operator map. `undefined` for neither, which no arm produces today and which a
+ * renderer must still handle rather than print "undefined" at a user.
+ */
+export declare function filterRefusalSubject(error: FilterOperatorError): string | undefined;
 export declare function convertOperatorToAST(operator: string): string | null;
 /**
  * Convert object-based filters to ObjectStack FilterNode AST format.
@@ -59,9 +101,67 @@ export declare function convertOperatorToAST(operator: string): string | null;
  * convertFiltersToAST({ age: { $gte: 18, $lte: 65 }, status: 'active' })
  * // => ['and', ['age', '>=', 18], ['age', '<=', 65], ['status', '=', 'active']]
  *
- * @throws {Error} If an unknown operator is encountered
+ * @example
+ * // Logical combinators (objectui#6948) — children lower recursively
+ * convertFiltersToAST({ $or: [{ status: 'open' }, { status: 'blocked' }] })
+ * // => ['or', ['status', '=', 'open'], ['status', '=', 'blocked']]
+ *
+ * @example
+ * // A Date is a comparand, not an operator map (objectui#8555). It lowers as
+ * // the Date INSTANCE — the spec accepts one, and the operator form already
+ * // emits one.
+ * convertFiltersToAST({ created: new Date('2026-01-01') })
+ * // => ['created', '=', Date(2026-01-01)]
+ *
+ * @throws {FilterOperatorError} If an unknown operator is encountered, if
+ * `$not` is used — see the `$not` arm for why the AST cannot carry it — if a
+ * field's value is a bare ARRAY (`{ tags: ['a', 'b'] }`) — see the array arm for
+ * why that is refused rather than read as `$in` — or if a field's value is an
+ * EXOTIC object the spec does not accept as a comparand (`{ name: /abc/ }`,
+ * a `Set`, a `Map`): see the exotic-comparand arm for why that is refused
+ * rather than dropped (objectui#8567), or if an `$icontains` comparand is not a
+ * NON-EMPTY STRING (`{ name: { $icontains: '' } }`, `{ name: { $icontains: 42 } }`)
+ * — two shapes `@objectstack/spec`'s `FILTER_TEXT_CASES` declares REFUSED and
+ * `ValueDataSource` has refused since objectui#8748; see
+ * {@link refuseTextComparand} (objectui#9001), or if a field is an EMPTY
+ * operator map (`{ a: {} }`) — alone (objectui#9164) or
+ * beside a key that lowers (objectui#10788): see {@link refuseEmptyOperatorMap},
+ * or if a `$empty` flag is not a boolean (`{ a: { $empty: 'yes' } }`,
+ * objectui#11094).
+ *
+ * @example
+ * // A field with NO operator (objectui#9164)
+ * convertFiltersToAST({ a: {} })
+ * // => throws FilterOperatorError (INVALID_FILTER / 400), field 'a'
+ *
+ * @example
+ * // … and beside a key that lowers, where it used to vanish and widen the
+ * // result to `['status', '=', 'a']` (objectui#10788)
+ * convertFiltersToAST({ status: 'a', created: {} })
+ * // => throws FilterOperatorError (INVALID_FILTER / 400), field 'created'
+ *
+ * @example
+ * // A filter that is NOTHING BUT combinators reducing to the TRUE identity
+ * // constrains nothing, and says so (objectui#8770). Callers skip the slot.
+ * convertFiltersToAST({ $and: [] })
+ * // => undefined
+ *
+ * @example
+ * // A filter whose EVERY key is skipped for a null/undefined value also
+ * // constrains nothing — the same answer this function already gives that key
+ * // when a sibling survives (objectui#9020). Callers skip the slot.
+ * convertFiltersToAST({ a: null })
+ * // => undefined
+ *
+ * @example
+ * // … and a filter that MIXES the two constrains nothing either, because the
+ * // identity fold counts only the keys the loop actually PROCESSED
+ * // (objectui#9030). A skipped key used to be counted against that fold, so a
+ * // filter whose every key folds alone did not fold together.
+ * convertFiltersToAST({ $and: [], b: undefined })
+ * // => undefined
  */
-export declare function convertFiltersToAST(filter: Record<string, any>): FilterNode | Record<string, any>;
+export declare function convertFiltersToAST(filter: Record<string, any>): FilterNode | Record<string, any> | undefined;
 /**
  * Normalize ONE filter source into a single filter node.
  *
@@ -108,9 +208,57 @@ export declare function convertFiltersToAST(filter: Record<string, any>): Filter
  * untouched.
  *
  * Returns `undefined` for an absent or empty source, so callers can skip
- * `$filter` rather than sending an empty array.
+ * `$filter` rather than sending an empty array — and, since objectui#8770, for
+ * an object source that is nothing but TRUE-identity combinators
+ * (`{ $and: [] }`), and since objectui#9020 for one whose every key is skipped
+ * for a null/undefined value (`{ a: null }`). Both constrain nothing and so
+ * contribute nothing to the `and` {@link mergeFilterNodes} builds. Those answers
+ * are inherited from {@link convertFiltersToAST}, not decided a second time
+ * here — including the fact that they are two separate decisions there.
  */
 export declare function toFilterNode(source: unknown): FilterNode | Record<string, any> | undefined;
+/**
+ * {@link toFilterNode}'s answer for a caller that has no `catch` above it.
+ *
+ * ## Why this exists (objectui#9050, ruling C′ step 2)
+ *
+ * `toFilterNode` is documented as "the last stop before the wire", and the two
+ * callers that reach the wire — `plugin-list`'s `buildEffectiveFilter` and
+ * `plugin-view`'s `ObjectView` — do have a `catch`: they call it inside a load
+ * `try`, `classifyLoadError` reads this file's `INVALID_FILTER` / 400 envelope,
+ * and the author sees "this filter is malformed". Three OTHER callers reach it
+ * from a RENDER-time `useMemo` (`plugin-detail`'s `RelatedList`,
+ * `plugin-form`'s `LineItemsPanel`, `plugin-grid`'s `ObjectGrid`), where a
+ * throw is a render error and there is no `classifyLoadError` in the path.
+ * A fourth is an ADAPTER rather than a renderer: `ValueDataSource.find` lowers
+ * an array `$filter` through this before matching it in memory
+ * (objectui#10767), and a `find` that never threw on a bad filter must not
+ * start to — it re-seats `refusal` as its own excluded-and-logged refusal.
+ *
+ * ## Why the return type is a UNION and not `node | undefined`
+ *
+ * Because `undefined` is the refused answer. A `try`/`catch` that swallows the
+ * refusal and hands back `undefined` means NO FILTER — every row — which is a
+ * silently unconstrained query on a view whose whole purpose can be to hide
+ * rows, and is the failure objectui#9001 closed. So the refusal is not
+ * representable as a node: `ok: false` carries the error and has no `node` to
+ * read at all, and TypeScript makes a caller narrow before it can build a
+ * query. That is the whole difference between this and a bare `catch`.
+ *
+ * ⚠️ Only a {@link FilterOperatorError} is caught. Anything else is a defect in
+ * this file rather than a statement about the author's filter, and is rethrown
+ * so it keeps reaching whatever boundary would have seen it — a render-time
+ * `TypeError` swallowed into "your filter is malformed" would send the author
+ * to edit a filter that is fine.
+ */
+export type FilterNodeResult = {
+    ok: true;
+    node: FilterNode | Record<string, any> | undefined;
+} | {
+    ok: false;
+    refusal: FilterOperatorError;
+};
+export declare function toFilterNodeSafely(source: unknown): FilterNodeResult;
 /**
  * Combine filter sources under a single `and`, each as its OWN child.
  *