@object-ui/core 17.6.0 → 18.0.0

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.
  *
@@ -74,8 +174,12 @@ export declare function convertFiltersToAST(filter: Record<string, any>): Filter
  *
  * The third is the one that kept getting lost. Renderers tested `source.length
  * > 0` before using it, which is `undefined > 0` for an object — so a
- * `table.defaultFilters` (declared `Record<string, any>`) was DROPPED and the
- * view returned every record. Silently: no error, just a wider answer.
+ * `table.defaultFilters` (declared `Record<string, any>` until objectui#6152
+ * round 10; the protocol's `ViewFilterRule` array since, and the record no
+ * longer validates there) was DROPPED and the view returned every record.
+ * Silently: no error, just a wider answer. That narrowing moved what an author
+ * may write, not this sink: the object arm below still lowers a record whatever
+ * caller hands it one.
  *
  * The FIRST never worked at all (objectui#3431). The array branch returned
  * every array VERBATIM, so a saved view's `ViewFilterRule[]` travelled to
@@ -108,9 +212,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.
  *