@object-ui/core 17.5.0 → 17.7.0

package/dist/utils/managedBy.d.ts

@@ -19,7 +19,7 @@
  *
  * What is genuinely objectui's and keeps a local name:
  * {@link resolveEffectiveCrudAffordances} — the spec's object-level matrix
- * INTERSECTED with the server-resolved effective API operation set (#3391), so
+ * INTERSECTED with the server-resolved effective API operation set (objectstack#3391), so
  * the UI never offers a button the server would 405. The spec's function has
  * no such notion; naming ours after it was the misdescription this burn-down
  * removes.
@@ -51,8 +51,33 @@ export type UserActionOverride = boolean | {
     disabledWhen?: RowCrudPredicates['disabledWhen'];
 };
 export interface UserActionsOverride {
-    create?: boolean;
-    import?: boolean;
+    /**
+     * Bare boolean or the object form. Widened from `boolean` in objectui#4646:
+     * `@objectstack/spec@17.0.0` types this key
+     * `z.union([z.boolean(), RowCrudActionOverrideSchema])`, and the spec's
+     * resolver emits the parsed predicates as `CrudAffordances.createPredicates`.
+     * The local type said `boolean` — so an author writing the shape the spec
+     * accepts, and that the related-list toolbar now honours
+     * (`RelatedRecordActionsBridge`, objectui#4646), was rejected by objectui's
+     * own type while the runtime handled it.
+     */
+    create?: UserActionOverride;
+    /**
+     * Bare boolean or the object form — the SAME union as `create` above, which
+     * is how `@objectstack/spec@17.0.0` types the two toolbar keys
+     * (`z.union([z.boolean(), RowCrudActionOverrideSchema])` for each), and its
+     * resolver emits `CrudAffordances.importPredicates` beside
+     * `createPredicates`.
+     *
+     * Widened in objectui#5142, deliberately IN THE SAME change that gave the
+     * object-list toolbar's Import button a consumer for those predicates
+     * (`ObjectView`). objectui#4646 left this key narrow on purpose and said why:
+     * widening a type ahead of its consumer re-declares the inert-metadata defect
+     * — objectui would have *claimed* to accept the object form while still
+     * dropping the predicate. Type and consumer travel together, so the
+     * declaration stays an honest statement of what this renderer honours.
+     */
+    import?: UserActionOverride;
     edit?: UserActionOverride;
     delete?: UserActionOverride;
     exportCsv?: boolean;
@@ -100,7 +125,7 @@ export declare function userActionPredicates(v: UserActionOverride | undefined |
  *
  * @param obj The object schema (managedBy bucket + userActions overrides).
  * @param effectiveApiOperations OPTIONAL server-resolved effective API operation
- *   set for this object (from `/me/permissions` `apiOperations`, #3391). When
+ *   set for this object (from `/me/permissions` `apiOperations`, objectstack#3391). When
  *   provided, each affordance bit is ANDed with the corresponding API operation
  *   (create/import→create/import, edit→update, delete→delete, exportCsv→export),
  *   so the UI never shows a button the server would 405. Passing `undefined`
@@ -138,7 +163,7 @@ export declare function isSystemWritable(obj: SchemaLike | null | undefined): bo
  * object-level editability, so only the resolved boolean matters here.)
  *
  * @param effectiveApiOperations OPTIONAL server-resolved effective API operation
- *   set for this object (`/me/permissions` `apiOperations`, #3391/#3546). When
+ *   set for this object (`/me/permissions` `apiOperations`, objectstack#3391/objectstack#3546). When
  *   provided, inline-edit is additionally ANDed with the server allowing
  *   `update`, so a record page never offers double-click/pencil editing the
  *   server would 405. `undefined` (old backend / unrestricted) leaves the

package/dist/utils/managedBy.js

@@ -19,7 +19,7 @@
  *
  * What is genuinely objectui's and keeps a local name:
  * {@link resolveEffectiveCrudAffordances} — the spec's object-level matrix
- * INTERSECTED with the server-resolved effective API operation set (#3391), so
+ * INTERSECTED with the server-resolved effective API operation set (objectstack#3391), so
  * the UI never offers a button the server would 405. The spec's function has
  * no such notion; naming ours after it was the misdescription this burn-down
  * removes.
@@ -73,7 +73,7 @@ export function userActionPredicates(v) {
 }
 /**
  * The affordance-bit → server API-operation mapping used to intersect the
- * UI-intent affordances with the server's effective API operation set (#3391).
+ * UI-intent affordances with the server's effective API operation set (objectstack#3391).
  * This is the objectui end of the framework's `API_METHOD_DERIVATION` contract:
  * the button predicate is `affordance(op) ∧ effective.api(op)`.
  */
@@ -97,7 +97,7 @@ const AFFORDANCE_TO_API_OPERATION = {
  *
  * @param obj The object schema (managedBy bucket + userActions overrides).
  * @param effectiveApiOperations OPTIONAL server-resolved effective API operation
- *   set for this object (from `/me/permissions` `apiOperations`, #3391). When
+ *   set for this object (from `/me/permissions` `apiOperations`, objectstack#3391). When
  *   provided, each affordance bit is ANDed with the corresponding API operation
  *   (create/import→create/import, edit→update, delete→delete, exportCsv→export),
  *   so the UI never shows a button the server would 405. Passing `undefined`
@@ -113,7 +113,7 @@ export function resolveEffectiveCrudAffordances(obj, effectiveApiOperations) {
         managedBy: obj?.managedBy ?? undefined,
         userActions: (obj?.userActions ?? undefined),
     });
-    // [#3391] Intersect with the server's effective API operations when present.
+    // [objectstack#3391] Intersect with the server's effective API operations when present.
     // The frontend consumes the effective set the server hands down; it never
     // reads the raw `apiMethods` nor re-derives.
     if (Array.isArray(effectiveApiOperations)) {
@@ -159,7 +159,7 @@ export function isSystemWritable(obj) {
  * object-level editability, so only the resolved boolean matters here.)
  *
  * @param effectiveApiOperations OPTIONAL server-resolved effective API operation
- *   set for this object (`/me/permissions` `apiOperations`, #3391/#3546). When
+ *   set for this object (`/me/permissions` `apiOperations`, objectstack#3391/objectstack#3546). When
  *   provided, inline-edit is additionally ANDed with the server allowing
  *   `update`, so a record page never offers double-click/pencil editing the
  *   server would 405. `undefined` (old backend / unrestricted) leaves the

package/dist/utils/native-date-value.d.ts

@@ -0,0 +1,48 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Stored value → `<input type="date">` value (`YYYY-MM-DD`).
+ *
+ * A leading `YYYY-MM-DD` is passed through VERBATIM rather than re-parsed: a
+ * date-only string is parsed as UTC midnight by `new Date()`, so reading local
+ * calendar components back out of it shifts the day by one everywhere west of
+ * Greenwich. `2026-06-17` must stay June 17th in every zone.
+ */
+export declare function toDateInputValue(value: unknown): string;
+/**
+ * Stored value → `<input type="datetime-local">` value (`YYYY-MM-DDTHH:mm`),
+ * expressed in the viewer's local wall clock — the same instant the detail
+ * page shows, so opening the editor never appears to move the time.
+ *
+ * A value that is ALREADY a zone-less local datetime is truncated to minutes
+ * in place instead of being round-tripped through `Date`, which would
+ * reinterpret it and then re-render it, twice risking an off-by-a-zone shift.
+ */
+export declare function toDateTimeInputValue(value: unknown): string;
+/**
+ * `<input type="datetime-local">` value → stored value (ISO-8601, UTC).
+ *
+ * The control hands us a zone-less local wall clock; `new Date()` reads that
+ * form as local time, which is the inverse of what `toDateTimeInputValue`
+ * wrote — the pair is what keeps read and write on one basis.
+ *
+ * An unparseable string is returned untouched rather than blanked: dropping a
+ * value the user can see in the box would be a data loss dressed up as a fix.
+ */
+export declare function fromDateTimeInputValue(value: string): string;
+/**
+ * True when a stored value is written on a calendar day that does not exist
+ * (`2026-02-30`, `2026-02-30T10:00:00Z`, `2026-02-30T10:00+08:00`) — the day
+ * read AS WRITTEN from the leading `YYYY-MM-DD`, by the one judgement the read
+ * faces use (`isRealCalendarDate`). A parsed `Date` always names a real day,
+ * so the check can only be made before any conversion.
+ *
+ * Anything without a leading `YYYY-MM-DD` (a `Date`, a number, free text) is
+ * not this case and answers `false`.
+ */
+export declare function isImpossibleStoredDay(value: unknown): boolean;

package/dist/utils/native-date-value.js

@@ -0,0 +1,167 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * native-date-value - the ONE adapter set between a stored date / datetime
+ * value and the native date/time controls (objectui#3127).
+ *
+ * ## Why it lives in `core` (objectui#10625)
+ *
+ * It was written in `@object-ui/fields` (`widgets/nativeDateValue.ts`), and
+ * `@object-ui/components`' data table could not import it from there:
+ * `fields` depends on `components`, so the reverse import is a package cycle.
+ * The table therefore kept private copies with no impossible-day check, and a
+ * stored `2026-02-30T10:00:00Z` showed as March 2nd in its inline editor and
+ * could be written back as that day. The functions move DOWN into the
+ * React-free engine, next to the judgement they share (`isRealCalendarDate`
+ * in `date-display.ts`), and `fields` re-exports them unchanged: one home,
+ * nothing to drift. `date-display.ts`'s header is the same remedy applied to
+ * the display side.
+ *
+ * ## The defect these close
+ *
+ * `<input type="date">` accepts exactly `YYYY-MM-DD` and
+ * `<input type="datetime-local">` exactly `YYYY-MM-DDTHH:mm[:ss]` — a **local
+ * wall clock with no zone suffix**. Anything else is not "coerced" or
+ * "warned about": the browser SILENTLY rejects it. The attribute still lands
+ * in the DOM, so the value looks present to anyone inspecting markup, while
+ * `input.value` reads back `""` and the control paints its empty placeholder:
+ *
+ * ```js
+ * el.getAttribute('value')  // "2026-08-16T00:33:00.000Z"  ← the record's value
+ * el.value                  // ""                          ← what the user sees
+ * ```
+ *
+ * Records come back from the API as full ISO-8601 (`…T00:33:00.000Z`) — which
+ * is precisely one of those rejected shapes. So EVERY datetime field in an
+ * edit dialog rendered blank while holding a real value, and users read that
+ * as "the date was lost" and retyped it (which is the only way the display bug
+ * could turn into a data change).
+ *
+ * ## Why a round trip, and not just a formatter
+ *
+ * Formatting on the way IN without converting on the way OUT would be the
+ * worse bug: the control would then be read as UTC but written back as a naive
+ * local string, so a user in UTC+8 who picked "08:33" would store 08:33Z and
+ * see 16:33 on the detail page. Read basis and write basis must be the same
+ * one, so `toDateTimeInputValue` / `fromDateTimeInputValue` are a pair and are
+ * used as a pair.
+ *
+ * ## Shape kept in form state
+ *
+ * `datetime` round-trips through ISO — the shape the API hands us and the one
+ * display/format code already assumes. `date` stays a plain `YYYY-MM-DD`
+ * string. Untouched fields are never re-emitted, so a form that opens and
+ * closes without an edit still submits nothing for them.
+ *
+ * ## A stored day that does not exist (objectui#10474)
+ *
+ * The engine's date parse accepts a day of `01`-`31` for every month and rolls
+ * the surplus forward, so `new Date('2026-02-30T10:00:00Z')` is March 2nd. The
+ * READ faces refuse such a value through the shared judgement
+ * (`isRealCalendarDate`, objectui#10026 / objectui#10301); this pair used to
+ * reach the engine first, so the editor showed `2026-03-02T10:00` for it and a
+ * save could write that day back. `isImpossibleStoredDay` asks the same
+ * judgement of the day AS WRITTEN, before any `new Date(...)`, in every
+ * spelling (`Z`, offset, zone-less, date-only).
+ *
+ * The control cannot show the stored string instead: measured in Chromium, a
+ * `datetime-local` (and a `date`) sanitises a nonexistent day to `""`, in the
+ * zone-less spelling too. So `toDateTimeInputValue` hands the control `""` and
+ * the WIDGET names the stored string beside it with an invalid marker — an
+ * empty control alone would be objectui#3127's silent blank again. Nothing is
+ * written until the user picks a new value.
+ */
+import { isRealCalendarDate } from './date-display.js';
+function pad2(n) {
+    return String(n).padStart(2, '0');
+}
+/**
+ * Stored value → `<input type="date">` value (`YYYY-MM-DD`).
+ *
+ * A leading `YYYY-MM-DD` is passed through VERBATIM rather than re-parsed: a
+ * date-only string is parsed as UTC midnight by `new Date()`, so reading local
+ * calendar components back out of it shifts the day by one everywhere west of
+ * Greenwich. `2026-06-17` must stay June 17th in every zone.
+ */
+export function toDateInputValue(value) {
+    if (value == null || value === '')
+        return '';
+    if (typeof value === 'string') {
+        const m = value.match(/^(\d{4}-\d{2}-\d{2})/);
+        if (m)
+            return m[1];
+    }
+    const d = value instanceof Date ? value : new Date(String(value));
+    if (Number.isNaN(d.getTime()))
+        return '';
+    return `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())}`;
+}
+/**
+ * Stored value → `<input type="datetime-local">` value (`YYYY-MM-DDTHH:mm`),
+ * expressed in the viewer's local wall clock — the same instant the detail
+ * page shows, so opening the editor never appears to move the time.
+ *
+ * A value that is ALREADY a zone-less local datetime is truncated to minutes
+ * in place instead of being round-tripped through `Date`, which would
+ * reinterpret it and then re-render it, twice risking an off-by-a-zone shift.
+ */
+export function toDateTimeInputValue(value) {
+    if (value == null || value === '')
+        return '';
+    // Judged before any `new Date(...)`, which would roll it (objectui#10474).
+    if (isImpossibleStoredDay(value))
+        return '';
+    if (typeof value === 'string') {
+        const local = value.match(/^(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2})(?::\d{2}(?:\.\d+)?)?$/);
+        if (local)
+            return `${local[1]}T${local[2]}`;
+    }
+    const d = value instanceof Date ? value : new Date(String(value));
+    if (Number.isNaN(d.getTime()))
+        return '';
+    return (`${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())}` +
+        `T${pad2(d.getHours())}:${pad2(d.getMinutes())}`);
+}
+/**
+ * `<input type="datetime-local">` value → stored value (ISO-8601, UTC).
+ *
+ * The control hands us a zone-less local wall clock; `new Date()` reads that
+ * form as local time, which is the inverse of what `toDateTimeInputValue`
+ * wrote — the pair is what keeps read and write on one basis.
+ *
+ * An unparseable string is returned untouched rather than blanked: dropping a
+ * value the user can see in the box would be a data loss dressed up as a fix.
+ */
+export function fromDateTimeInputValue(value) {
+    if (!value)
+        return '';
+    // A nonexistent day is returned untouched, like an unparseable string: the
+    // engine would re-emit it as the rolled day (objectui#10474).
+    if (isImpossibleStoredDay(value))
+        return value;
+    const d = new Date(value);
+    if (Number.isNaN(d.getTime()))
+        return value;
+    return d.toISOString();
+}
+/**
+ * True when a stored value is written on a calendar day that does not exist
+ * (`2026-02-30`, `2026-02-30T10:00:00Z`, `2026-02-30T10:00+08:00`) — the day
+ * read AS WRITTEN from the leading `YYYY-MM-DD`, by the one judgement the read
+ * faces use (`isRealCalendarDate`). A parsed `Date` always names a real day,
+ * so the check can only be made before any conversion.
+ *
+ * Anything without a leading `YYYY-MM-DD` (a `Date`, a number, free text) is
+ * not this case and answers `false`.
+ */
+export function isImpossibleStoredDay(value) {
+    if (typeof value !== 'string')
+        return false;
+    const m = value.match(/^(\d{4}-\d{2}-\d{2})(?:$|T)/);
+    return m != null && !isRealCalendarDate(m[1]);
+}

package/dist/utils/non-grid-row-ceiling.d.ts

@@ -0,0 +1,143 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * The platform's hard row ceiling for a NON-GRID visualisation — gantt,
+ * calendar, map and tree (objectui#7210, maintainer ruling a′, 2026-09-02).
+ *
+ * ## Why this lives in `@object-ui/core` (objectui#7508, ruling A′)
+ *
+ * The four views live in four packages, so whatever they share is public by
+ * construction: every package here has a single entry and no subpath export.
+ * The non-React half of the mechanism — this constant, the query it sends and
+ * {@link applyNonGridRowCeiling} — wraps this package's own
+ * `extractRecords`, and every one of the four already imports core helpers,
+ * so this is its home. `@object-ui/react` re-exports the three names it
+ * carried before, and keeps only the React half (`NonGridRowCeilingNote`).
+ *
+ * ## What was ruled, and what was rejected
+ *
+ * A non-grid visualisation may fetch the whole FILTERED result set, because a
+ * truthful range or layout needs all of it: a gantt cannot compute
+ * `min(start) → max(end)` from one page, and a map cannot fit a camera to
+ * markers it never received. What it may not do is fetch it UNBOUNDED — at
+ * 100k scheduled rows that is the whole table into the browser, with no knob
+ * reachable from view metadata, since these four requests never carried a
+ * `$top` for `pagination.pageSize` to set.
+ *
+ * So the fetch carries a ceiling, and the ceiling is a NAMED CONSTANT IN THE
+ * RENDERER — not an authorable view key. Three alternatives were considered
+ * and are not what landed:
+ *
+ *   - a documentation note only — still the whole table into the browser;
+ *   - truncate at `pagination.pageSize` — SILENT truncation, and it caps a
+ *     complete schedule at one page;
+ *   - an authorable `maxRows` key — a new permanent key every author must set.
+ *
+ * ⛔ The direction the ruling names as dangerous is SILENT truncation: a
+ * cut-off schedule still looks like a schedule, a cut-off map still looks like
+ * a map. Nothing on screen distinguishes "these are all the records" from
+ * "these are the first 2,000 of 40,000" unless the view says so. That is why
+ * `NonGridRowCeilingNote` (`@object-ui/react`) is not decoration — crossing
+ * this ceiling quietly is the defect, and the note is the fix.
+ *
+ * ## Why 2,000, measured
+ *
+ * The ruling sets ONE constant across the four views, chosen after measuring
+ * them, so the binding view decides it. Measured in this repo's jsdom lane
+ * (`@testing-library/react`, real child views, inline `value` provider, mount
+ * to settled paint), DOM elements materialised and mount duration:
+ *
+ * | rows  | gantt      | calendar  | map            | tree            |
+ * |------:|-----------:|----------:|---------------:|----------------:|
+ * |   250 |  726 · 314ms |  415 · 231ms |   478 · 152ms |   1,306 ·  326ms |
+ * | 1,000 |  726 · 226ms |  415 · 235ms | 1,512 · 299ms |   5,206 · 1,025ms |
+ * | 2,000 |  726 · 484ms |  415 · 237ms | 2,770 · 1,250ms | 10,406 · 2,720ms |
+ * | 4,000 |  726 · 420ms |  415 · 211ms | 3,020 · 648ms |  20,806 · 3,105ms |
+ * | 8,000 |         —    |        —    |          —    |  41,606 · 7,597ms |
+ *
+ * Three of the four hold their DOM flat as rows grow, and for structural
+ * reasons that will not change: the gantt VIRTUALISES its task list and
+ * timeline window, the calendar month grid draws at most four events per day
+ * cell, and the map auto-clusters above 100 markers. Their cost in rows is the
+ * O(n) transform, not the DOM.
+ *
+ * `ObjectTree` is the outlier and therefore the constraint: it flattens every
+ * expanded node into the document, measured at a strictly linear **5.2 DOM
+ * elements per record**, with no virtualisation anywhere on that path.
+ *
+ * The budget applied to that: keep the WORST of the four inside ~10,000 DOM
+ * elements — an order of magnitude above Lighthouse's ~1,400-element
+ * "excessive DOM size" warning, and the last point at which the tree's mount
+ * stays under ~3s in an environment that does no layout and no paint at all.
+ * 2,000 rows is where that lands, measured rather than interpolated: 10,406
+ * elements. It is also ~10x the real application result set this card was
+ * filed from (186 rows of `duly_task`), so a genuine working view is nowhere
+ * near it, which is the property that keeps the note meaningful when it does
+ * appear.
+ *
+ * ⚠️ These are SHARED-BOX jsdom seconds, not browser wall clock, and jsdom
+ * does no layout or paint. The DOM-element counts are the environment-
+ * independent half and the reason the ratio between the four views is the
+ * load-bearing part of the reading, not the milliseconds. This table is a
+ * reading taken once, when objectui#7210 landed; nothing re-derives it.
+ */
+export declare const NON_GRID_ROW_CEILING = 2000;
+/**
+ * The query keys a non-grid view sends to honour {@link NON_GRID_ROW_CEILING}:
+ * `$top` is the ceiling plus ONE probe row.
+ *
+ * This is the ONE place the `+ 1` is written (objectui#7508, ruling A′). It
+ * used to be a published constant beside the ceiling, which left the
+ * mechanism split in two — `$top` at each call site, the slice in
+ * {@link applyNonGridRowCeiling} — and gave every caller a number to get
+ * wrong. A caller now spreads this into its `find()` query and never spells
+ * the probe row itself.
+ *
+ * The `+ 1` is what makes truncation DETECTABLE, and a site that lost it would
+ * look correct and report nothing: with exactly `$top: NON_GRID_ROW_CEILING`,
+ * a result set of exactly 2,000 and one of 200,000 both come back as 2,000
+ * rows, and the only thing separating them is a `total` the adapter is not
+ * obliged to send (`QueryResult.total` is optional, and an adapter answering
+ * with a bare array carries none at all). One extra row makes the distinction
+ * a fact about the rows in hand.
+ *
+ * A fresh object per call, so a caller that mutates the query it built cannot
+ * change what the next caller sends.
+ */
+export declare function nonGridRowCeilingQuery(): {
+    $top: number;
+};
+/** What {@link applyNonGridRowCeiling} tells a caller about its result set. */
+export interface NonGridCeilingResult<T = any> {
+    /** The rows to draw — never more than {@link NON_GRID_ROW_CEILING}. */
+    rows: T[];
+    /**
+     * The size of the whole filtered result set when the adapter reported one
+     * (`QueryResult.total`), otherwise `undefined`. `undefined` is NOT "not
+     * truncated" — see {@link NonGridCeilingResult.truncated}, which is decided
+     * by the rows in hand and never by this.
+     */
+    total?: number;
+    /** `true` when the source had more rows than the ceiling allows drawn. */
+    truncated: boolean;
+}
+/**
+ * Cap a non-grid view's result set at {@link NON_GRID_ROW_CEILING} and report
+ * whether it had to.
+ *
+ * Truncation is decided by the PROBE ROW (`rows.length > NON_GRID_ROW_CEILING`
+ * against a query built by {@link nonGridRowCeilingQuery}), never by comparing
+ * against `total`: `total` is optional on `QueryResult` and absent entirely
+ * from a bare-array response, so a `total`-based test would silently stop
+ * reporting on exactly the adapters least likely to be paging correctly.
+ *
+ * The rows are read by `extractRecords`, so this sink accepts exactly the
+ * envelopes that helper does (objectui#6839) — pinned in
+ * `non-grid-row-ceiling.contractEnvelope-6839.test.ts`.
+ */
+export declare function applyNonGridRowCeiling<T = any>(result: unknown): NonGridCeilingResult<T>;

package/dist/utils/non-grid-row-ceiling.js

@@ -0,0 +1,141 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { extractRecords } from './extract-records.js';
+/**
+ * The platform's hard row ceiling for a NON-GRID visualisation — gantt,
+ * calendar, map and tree (objectui#7210, maintainer ruling a′, 2026-09-02).
+ *
+ * ## Why this lives in `@object-ui/core` (objectui#7508, ruling A′)
+ *
+ * The four views live in four packages, so whatever they share is public by
+ * construction: every package here has a single entry and no subpath export.
+ * The non-React half of the mechanism — this constant, the query it sends and
+ * {@link applyNonGridRowCeiling} — wraps this package's own
+ * `extractRecords`, and every one of the four already imports core helpers,
+ * so this is its home. `@object-ui/react` re-exports the three names it
+ * carried before, and keeps only the React half (`NonGridRowCeilingNote`).
+ *
+ * ## What was ruled, and what was rejected
+ *
+ * A non-grid visualisation may fetch the whole FILTERED result set, because a
+ * truthful range or layout needs all of it: a gantt cannot compute
+ * `min(start) → max(end)` from one page, and a map cannot fit a camera to
+ * markers it never received. What it may not do is fetch it UNBOUNDED — at
+ * 100k scheduled rows that is the whole table into the browser, with no knob
+ * reachable from view metadata, since these four requests never carried a
+ * `$top` for `pagination.pageSize` to set.
+ *
+ * So the fetch carries a ceiling, and the ceiling is a NAMED CONSTANT IN THE
+ * RENDERER — not an authorable view key. Three alternatives were considered
+ * and are not what landed:
+ *
+ *   - a documentation note only — still the whole table into the browser;
+ *   - truncate at `pagination.pageSize` — SILENT truncation, and it caps a
+ *     complete schedule at one page;
+ *   - an authorable `maxRows` key — a new permanent key every author must set.
+ *
+ * ⛔ The direction the ruling names as dangerous is SILENT truncation: a
+ * cut-off schedule still looks like a schedule, a cut-off map still looks like
+ * a map. Nothing on screen distinguishes "these are all the records" from
+ * "these are the first 2,000 of 40,000" unless the view says so. That is why
+ * `NonGridRowCeilingNote` (`@object-ui/react`) is not decoration — crossing
+ * this ceiling quietly is the defect, and the note is the fix.
+ *
+ * ## Why 2,000, measured
+ *
+ * The ruling sets ONE constant across the four views, chosen after measuring
+ * them, so the binding view decides it. Measured in this repo's jsdom lane
+ * (`@testing-library/react`, real child views, inline `value` provider, mount
+ * to settled paint), DOM elements materialised and mount duration:
+ *
+ * | rows  | gantt      | calendar  | map            | tree            |
+ * |------:|-----------:|----------:|---------------:|----------------:|
+ * |   250 |  726 · 314ms |  415 · 231ms |   478 · 152ms |   1,306 ·  326ms |
+ * | 1,000 |  726 · 226ms |  415 · 235ms | 1,512 · 299ms |   5,206 · 1,025ms |
+ * | 2,000 |  726 · 484ms |  415 · 237ms | 2,770 · 1,250ms | 10,406 · 2,720ms |
+ * | 4,000 |  726 · 420ms |  415 · 211ms | 3,020 · 648ms |  20,806 · 3,105ms |
+ * | 8,000 |         —    |        —    |          —    |  41,606 · 7,597ms |
+ *
+ * Three of the four hold their DOM flat as rows grow, and for structural
+ * reasons that will not change: the gantt VIRTUALISES its task list and
+ * timeline window, the calendar month grid draws at most four events per day
+ * cell, and the map auto-clusters above 100 markers. Their cost in rows is the
+ * O(n) transform, not the DOM.
+ *
+ * `ObjectTree` is the outlier and therefore the constraint: it flattens every
+ * expanded node into the document, measured at a strictly linear **5.2 DOM
+ * elements per record**, with no virtualisation anywhere on that path.
+ *
+ * The budget applied to that: keep the WORST of the four inside ~10,000 DOM
+ * elements — an order of magnitude above Lighthouse's ~1,400-element
+ * "excessive DOM size" warning, and the last point at which the tree's mount
+ * stays under ~3s in an environment that does no layout and no paint at all.
+ * 2,000 rows is where that lands, measured rather than interpolated: 10,406
+ * elements. It is also ~10x the real application result set this card was
+ * filed from (186 rows of `duly_task`), so a genuine working view is nowhere
+ * near it, which is the property that keeps the note meaningful when it does
+ * appear.
+ *
+ * ⚠️ These are SHARED-BOX jsdom seconds, not browser wall clock, and jsdom
+ * does no layout or paint. The DOM-element counts are the environment-
+ * independent half and the reason the ratio between the four views is the
+ * load-bearing part of the reading, not the milliseconds. This table is a
+ * reading taken once, when objectui#7210 landed; nothing re-derives it.
+ */
+export const NON_GRID_ROW_CEILING = 2000;
+/**
+ * The query keys a non-grid view sends to honour {@link NON_GRID_ROW_CEILING}:
+ * `$top` is the ceiling plus ONE probe row.
+ *
+ * This is the ONE place the `+ 1` is written (objectui#7508, ruling A′). It
+ * used to be a published constant beside the ceiling, which left the
+ * mechanism split in two — `$top` at each call site, the slice in
+ * {@link applyNonGridRowCeiling} — and gave every caller a number to get
+ * wrong. A caller now spreads this into its `find()` query and never spells
+ * the probe row itself.
+ *
+ * The `+ 1` is what makes truncation DETECTABLE, and a site that lost it would
+ * look correct and report nothing: with exactly `$top: NON_GRID_ROW_CEILING`,
+ * a result set of exactly 2,000 and one of 200,000 both come back as 2,000
+ * rows, and the only thing separating them is a `total` the adapter is not
+ * obliged to send (`QueryResult.total` is optional, and an adapter answering
+ * with a bare array carries none at all). One extra row makes the distinction
+ * a fact about the rows in hand.
+ *
+ * A fresh object per call, so a caller that mutates the query it built cannot
+ * change what the next caller sends.
+ */
+export function nonGridRowCeilingQuery() {
+    return { $top: NON_GRID_ROW_CEILING + 1 };
+}
+/**
+ * Cap a non-grid view's result set at {@link NON_GRID_ROW_CEILING} and report
+ * whether it had to.
+ *
+ * Truncation is decided by the PROBE ROW (`rows.length > NON_GRID_ROW_CEILING`
+ * against a query built by {@link nonGridRowCeilingQuery}), never by comparing
+ * against `total`: `total` is optional on `QueryResult` and absent entirely
+ * from a bare-array response, so a `total`-based test would silently stop
+ * reporting on exactly the adapters least likely to be paging correctly.
+ *
+ * The rows are read by `extractRecords`, so this sink accepts exactly the
+ * envelopes that helper does (objectui#6839) — pinned in
+ * `non-grid-row-ceiling.contractEnvelope-6839.test.ts`.
+ */
+export function applyNonGridRowCeiling(result) {
+    const all = extractRecords(result);
+    const rawTotal = result && typeof result === 'object' && typeof result.total === 'number'
+        ? result.total
+        : undefined;
+    const truncated = all.length > NON_GRID_ROW_CEILING;
+    return {
+        rows: truncated ? all.slice(0, NON_GRID_ROW_CEILING) : all,
+        total: rawTotal,
+        truncated,
+    };
+}