@object-ui/core 17.6.0 → 17.7.0

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,
+    };
+}

package/dist/utils/normalize-list-view.d.ts

@@ -5,6 +5,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+import type { ViewType } from '@object-ui/types';
 import type { RowHeight } from '@objectstack/spec/ui';
 /** ListView's toolbar density vocabulary — three steps, not the spec's five. */
 export type DensityMode = 'compact' | 'comfortable' | 'spacious';
@@ -62,6 +63,101 @@ export declare const ROW_HEIGHT_TO_DENSITY_MODE: Record<RowHeight, DensityMode>;
  * something typed `DensityMode`.
  */
 export declare function rowHeightToDensityMode(rowHeight: unknown): DensityMode | undefined;
+/**
+ * A visualization `ListView` actually draws — one member per `case` in its
+ * `viewComponentSchema` switch (`packages/plugin-list/src/ListView.tsx`).
+ *
+ * DERIVED from {@link ViewType} (`ca3942729`), which is itself derived from
+ * `@objectstack/spec/ui` `ListView['type']`. Spelled as an `Exclude` of the
+ * members this renderer does not draw rather than as the spec's own
+ * `VisualizationType`, deliberately: `Exclude` leaves the SPEC's list as the
+ * thing being subtracted from, so ANY member the spec adds — visualization or
+ * not — lands here as a required key and fails the build, which is what the
+ * promise below actually says. Keying on `VisualizationType` instead would let
+ * a future non-visualization list type (another `page`) pass this site in
+ * silence, which is the exact failure being fixed.
+ *
+ * ⭐ What it subtracts is {@link UndrawableViewKind} — the keys of
+ * {@link UNDRAWABLE_VIEW_KINDS} the current `ViewType` still carries — and
+ * never a literal list of kinds (objectui#9880). A literal list is a second
+ * hand-written copy of the vocabulary, the failure class `ca3942729` removed
+ * from `ViewType` itself, and it rots in the direction the spec actually moved:
+ * `Exclude<ViewType, 'list' | 'detail' | 'page'>` kept subtracting `'page'`
+ * after objectstack RETIRED it, where `Exclude` of a non-member is a silent
+ * no-op no compiler reads. The sibling record's excess `page:` key is what went
+ * red; this line stayed green while saying something that had stopped being
+ * true.
+ *
+ * It happens to equal `@objectstack/spec/ui`'s `VisualizationType` today. That
+ * is a fact about the resolved spec, not the definition.
+ */
+export type ListViewVisualization = Exclude<ViewType, UndrawableViewKind>;
+/**
+ * Every member of {@link ViewType} that {@link LIST_VIEW_KINDS} does NOT carry,
+ * with the reason — and, where the answer is "the author authored something
+ * valid and will get a grid", the sentence to say out loud.
+ *
+ * The two tables together still partition the derived union — a member the spec
+ * ADDS must be classed as drawable or explained HERE, and until it is the build
+ * is red — but the red lands on {@link LIST_VIEW_KINDS} alone, because a kind
+ * neither table classes is not extracted into {@link UndrawableViewKind} and so
+ * stays inside {@link ListViewVisualization}, whose record is total. A key
+ * MISSPELLED here fails the same way, for the same reason: the kind it was
+ * meant to class is not extracted either. Both directions are pinned in
+ * `__tests__/normalize-list-view.undrawableBothLegs-9880.test.ts` rather than
+ * asserted in this sentence.
+ *
+ * ⛔ NOT annotated `Record<Exclude<ViewType, ListViewVisualization>, …>`, and
+ * the `satisfies` is not a style choice (objectui#9880). An annotation makes
+ * the literal EXACT in BOTH directions: a kind the spec adds is a missing key
+ * (wanted) and a kind the spec RETIRES is an EXCESS PROPERTY — a TS2353 that
+ * demands a deletion this repository cannot make while it resolves a published
+ * spec which still carries the kind (as it did with `page` through 17.4.0).
+ * `satisfies` keeps the value constraint
+ * (every reason is a `string` or `null`) and drops the exactness, which is what
+ * lets one spelling compile against both the pinned published spec and one
+ * built from objectstack `main`.
+ *
+ * `null` means silence is correct — these are objectui view CATEGORIES, never
+ * authored as a list-view kind:
+ *  - `list` is the view CATEGORY, not a kind — it already folds to `grid`.
+ *  - `detail` is a different renderer (`plugin-detail`), never a ListView case.
+ *
+ * `page` had a row here until objectui#11073. objectstack#17063 removed
+ * `type: 'page'` from the list-view enum, and the row answered for it while this
+ * repository still resolved a spec that published the kind. `@objectstack/spec`
+ * 17.5.0 carries the removal: both published `@object-ui/types` faces refuse
+ * `page`, `Extract` no longer extracted the row, and the residual pins that held
+ * it (`normalize-list-view.pageResidual-8429.test.ts`) were converted, so it was
+ * deleted as it said it would be. A stored `page` view now degrades like any
+ * kind outside the vocabulary.
+ */
+declare const UNDRAWABLE_VIEW_KINDS: {
+    list: null;
+    detail: null;
+};
+/**
+ * The members of the current {@link ViewType} that {@link UNDRAWABLE_VIEW_KINDS}
+ * classes — the other half of the partition, derived rather than written out.
+ *
+ * `Extract` over the table's keys, not the table's raw `keyof`, is the load-
+ * bearing operator (objectui#9880): the table may carry a row for a kind the
+ * spec has since RETIRED, and `Extract` drops that row from the TYPE without
+ * the table having to lose it at runtime. That is what made one spelling
+ * correct against both the published spec (which published `page` through
+ * 17.4.0) and a spec built from objectstack `main` (which retired it), and what
+ * made the row's deletion at 17.5.0 a plain deletion (objectui#11073).
+ */
+type UndrawableViewKind = Extract<ViewType, keyof typeof UNDRAWABLE_VIEW_KINDS>;
+/**
+ * Whether `value` names a visualization `ListView` draws.
+ *
+ * Exported so a read site cannot restate the membership question as its own
+ * literal array: the gate and the seam must answer one question, which is the
+ * rule this file's own `availableViews` notes already argue for (objectui#5042,
+ * objectui#7544, and now `ca3942729`).
+ */
+export declare function isListViewVisualization(value: unknown): value is ListViewVisualization;
 /**
  * ObjectUI's `list-view` node historically used a different vocabulary from
  * `@objectstack/spec` for the same concepts (`fields` where the spec says
@@ -114,10 +210,34 @@ export declare function rowHeightToDensityMode(rowHeight: unknown): DensityMode
  *    so objectui's field is typed from the spec but used as something else.
  *    That mismatch is real and out of scope here; converting formats inside a
  *    vocabulary fold would change what reaches the data source.
+ *  - `data: { provider: 'object', object }` → `objectName` (#7477, step 6 of
+ *    #2890). This is the spelling the published `react-blocks` contract
+ *    recommends and the one `@objectstack/spec`'s `ViewDataSchema` declares;
+ *    ListView read it at ZERO sites, so a page bound that way validated green
+ *    upstream and rendered an empty list here with no diagnostic. The `object`
+ *    provider is a `strictObject` carrying exactly `{ provider, object }`, so
+ *    `objectName` captures all of it. Two deliberate departures from the folds
+ *    above, both narrowing:
+ *      · an already-present `objectName` WINS — this fold only fills a gap, it
+ *        never re-points a binding that already resolves;
+ *      · `data` is NOT deleted. Every other fold deletes because the legacy key
+ *        has one meaning and one home; `data` has four providers, `api`/`value`
+ *        are read live in `ListView`, and the whole block is FORWARDED to child
+ *        views (the gantt branch), whose own `getDataConfig` reads `data` before
+ *        `objectName`. Deleting it for one provider would rewrite what a child
+ *        resolves. Nothing in `ListView` reads `data.provider === 'object'`, so
+ *        keeping it cannot create a second de-facto contract inside the renderer.
  *  - `viewType`: a missing kind, or the view CATEGORY `'list'` that AI-authored
  *    metadata stores and hosts forward verbatim, becomes the renderable `'grid'`
  *    — otherwise it reaches the renderer's typeless default branch and shows as
- *    a red "Unknown component type" box.
+ *    a red "Unknown component type" box. Before that default applies, the
+ *    AUTHOR's kind is read (#7477): `specType` — the slot
+ *    `components/renderers/layout/react-page.tsx` parks a react-tier `type` in
+ *    when the SDUI envelope claims the `type` key (ADR-0078) — and then a bare
+ *    `type` when it names a kind ListView draws, which the component
+ *    discriminator (`'list-view'`) never does. Same two legs, same order, as
+ *    `normalizeChartSchema`'s chart-family read. An explicit `viewType` still
+ *    wins: this leg only fills the gap that used to resolve to `'grid'`.
  *  - each `columns` entry's IDENTITY — `name` / `fieldName` → the spec's `field`
  *    (#3104). This one MIRRORS instead of deleting, for the reason given on
  *    {@link normalizeColumnIdentities}: `columns` entries cross the package