@object-ui/react 17.6.0 → 18.0.0

package/dist/element-data-source/ElementDataSourceGate.js

@@ -51,6 +51,27 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * designer emits for an unconfigured column list, and supplying the columns is
  * exactly why a view was named.
  *
+ * The row cap answers "did the component author one?" the same way, and for the
+ * same reason (objectui#9899). A cap the contract REFUSES — `pageSize: 0`,
+ * a negative, a fraction — is not a cap this relay may treat as the author's
+ * intent, so it does not suppress the one the bound view supplies. Deciding
+ * that question by PRESENCE is how a view's legitimate cap was dropped in
+ * favour of the consuming renderer's own default: measured end to end on
+ * `list-view` before the repair, a component carrying `pagination.pageSize: 0`
+ * under a view supplying `7` put `$top: 100` on the wire — the view's cap never
+ * reached it, so the read was WIDER than the view asked for.
+ *
+ * The VIEW's own cap can be refused too, and `@object-ui/core` drops it before
+ * it reaches this relay (objectui#9928). The drop is right, but it left the
+ * consuming renderer nothing to refuse, so it went silent — and this relay
+ * reports the view's refusal instead (objectui#10015). See
+ * {@link describeRefusedViewRowLimit} for when that message applies.
+ *
+ * The BINDING's own cap follows the same rule (objectui#10016): a `limit` the
+ * contract refuses is not authored, so `@object-ui/core` lets the view's cap
+ * through in its place, and that cap is a baseline here like any other
+ * view-sourced value. See {@link describeRefusedBindingRowLimit}.
+ *
  * ## What a mapping may NOT do
  *
  * {@link ElementDataSourceMapping} names only keys the target block genuinely
@@ -80,9 +101,135 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * like it works.
  */
 import * as React from 'react';
-import { isElementDataSourceConfig, mergeFilterNodes, } from '@object-ui/core';
+import { elementDataSourceRefusedLimitMessage, filterRefusalSubject, isElementDataSourceConfig, mergeFilterNodes, toFilterNodeSafely, } from '@object-ui/core';
+import { useObjectTranslation } from '@object-ui/i18n';
 import { useElementDataSource, } from '../hooks/useElementDataSource.js';
 import { SchemaRendererContext } from '../context/SchemaRendererContext.js';
+/**
+ * What the contract admits as a row cap (objectui#9899).
+ *
+ * `@objectstack/spec` has already answered what `0` means for the keys this
+ * branch writes. Its view pagination config declares `pageSize` a positive
+ * integer with a default; every component row cap its component props map
+ * declares is `z.number().int().positive()`; and that flat `limit` is the key a
+ * view's `pagination.pageSize` is LOWERED INTO for the blocks that read it. So
+ * `0`, a negative and a fraction are not spellings this relay may assign a
+ * meaning to — they are values the contract refuses.
+ *
+ * ⚠️ Said precisely, because it is easy to overstate: the `object-grid` props
+ * face declares its OWN `pagination` key `z.unknown()`, so a save gate does not
+ * refuse a component-level `pagination.pageSize: 0` on that face, and the flat
+ * `pageSize` shorthand beside it is a bare `z.number()`. The refusal rests on
+ * the pagination CONFIG contract and on the `limit` the value is lowered into —
+ * the same ground objectui#9853, objectui#9897 and objectui#9925 already stood
+ * on at the renderer sites.
+ *
+ * ⛔ Deliberately a LOCAL restatement of the predicate objectui#9925 landed at
+ * the renderer sites, not an import and not a shared helper: hoisting it would
+ * be a cross-package extraction this card may not make. The cost is stated
+ * rather than hidden — one rule now has a spelling at every site that enforces
+ * it, and `git grep 'isUsableRowLimit\|isUsablePageSize'` is what enumerates
+ * them; the day one is meant to change, all of them are.
+ */
+function isUsableRowLimit(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value > 0;
+}
+/**
+ * The loud half, and the reason a RELAY owes one at all.
+ *
+ * A relay that merely declines to treat a value as authored could reasonably
+ * say nothing — the renderer it forwards to has its own refusal and its own
+ * message. Measured rather than assumed: BEFORE this repair, a `list-view`
+ * carrying `pagination.pageSize: 0` under a bound view was told about it, once,
+ * by `ListView`'s own diagnostic. AFTER it, the gate writes the view's usable
+ * cap, that renderer sees a value it accepts, and its message correctly goes
+ * silent — so the repair REMOVES the only place the author was being told.
+ * This restores that one message at the layer that now makes the decision.
+ *
+ * ⛔ NOT a second guard: the predicate lives once, in {@link isUsableRowLimit},
+ * and this reads it. `null` means "nothing to say" — an absent cap is not a
+ * mistake and a usable one is not either, which is what keeps this from
+ * becoming an always-on marker that states nothing.
+ */
+const describeDisplacedRowLimit = (authored, key, used, componentType, objectName) => {
+    if (authored === undefined || authored === null)
+        return null;
+    if (isUsableRowLimit(authored))
+        return null;
+    const type = typeof componentType === 'string' && componentType ? componentType : 'component';
+    const where = typeof objectName === 'string' && objectName ? `${type} on ${objectName}` : type;
+    return (`[ObjectUI] ElementDataSourceGate row cap: ${where} declared ${key}: ${String(authored)}, `
+        + 'which is not a positive integer. A row cap must be a positive integer '
+        + '(the spec refuses zero and negative values), so it was ignored and the cap '
+        + `from this component's bound data source (${used}) was used instead.`);
+};
+/**
+ * The loud half for a cap the SAVED VIEW declared and the contract refuses
+ * (objectui#10015).
+ *
+ * `@object-ui/core` drops such a cap while composing, so `composed.limit`
+ * never carries it and the renderer below never sees it. Its own diagnostic
+ * treats an absent key as "not a mistake", so after that drop nothing said
+ * anything. The wording is the core builder's, not this file's: it is the one
+ * sentence both consumers of the composed binding use, and `ViewDataProvider`
+ * already reports it on the path with no renderer. The builder is pure because
+ * the composer runs inside a `useMemo`; this relay reports its result from an
+ * effect, the same way it reports {@link describeDisplacedRowLimit}.
+ *
+ * It speaks only when the refusal CHANGED what this block receives — when a
+ * usable view cap would have been written here:
+ *
+ *  - the binding declared no usable `limit` of its own (if it did, the
+ *    binding's cap is what the block gets whatever the view carries). The
+ *    builder applies this condition itself, because `ViewDataProvider` needs
+ *    it too (objectui#10016), so this relay hands it the binding; and
+ *  - the component's own cap is not a usable one (a usable one wins over any
+ *    view cap).
+ *
+ * In both of those excluded cases the builder's sentence — the block falls
+ * back to its own default — would not be true, so silence is the honest
+ * answer, not a gap. The caller adds the third condition: the block reads a
+ * row cap at all.
+ *
+ * ## Never together with {@link describeDisplacedRowLimit}
+ *
+ * That message needs a usable cap to have been WRITTEN. With a refused view
+ * cap, the only usable cap left is a binding's usable `limit`, and that is
+ * excluded above. So the two are exclusive by construction. When the component
+ * AND the view both carry a refused cap, this message names the view and the
+ * renderer names the component: two declarations, one message each.
+ */
+const describeRefusedViewRowLimit = (view, config, authored) => {
+    if (!config)
+        return null;
+    if (isUsableRowLimit(authored))
+        return null;
+    return elementDataSourceRefusedLimitMessage(view, config.view, config.object, config);
+};
+/**
+ * The loud half for a cap the BINDING declared and the contract refuses
+ * (objectui#10016), in the core builder's words for that operand.
+ *
+ * `@object-ui/core` treats such a cap as not authored: it lets the view's
+ * usable cap through in its place, or none. Nothing downstream can see the
+ * refused value any more, so this relay reports it, from an effect, the same
+ * way it reports the view's refusal.
+ *
+ * It needs no condition beyond the caller's (the block reads a row cap at
+ * all). A usable binding cap is written whatever the component or the view
+ * carries, so a refused one is always a cap this block did not get.
+ *
+ * It can fire beside the other two, and that is one message per declaration,
+ * not two per mistake: beside {@link describeRefusedViewRowLimit} when the view
+ * ALSO carries a refused cap, and beside {@link describeDisplacedRowLimit} when
+ * the component ALSO carries a refused cap and the view's usable one displaced
+ * it.
+ */
+const describeRefusedBindingRowLimit = (view, config) => {
+    if (!config)
+        return null;
+    return elementDataSourceRefusedLimitMessage(view, config.view, config.object, config, 'binding');
+};
 const readLimit = (base, key) => {
     if (key === 'pagination.pageSize')
         return base.pagination?.pageSize;
@@ -122,10 +269,16 @@ export function useElementDataSourceSchema(schema, mapping = {}, dataSource) {
     const { object: objectKey = 'objectName', columns, filter, sort, limit, viewType } = mapping;
     const mapped = React.useMemo(() => {
         const composed = binding.composed;
+        // BY REFERENCE when there is nothing to apply — a fresh object every render
+        // would remount the block and refetch. The wrapper is memoised alongside it,
+        // so the identity this carries is the one the caller sees.
         if (!composed)
-            return schema;
+            return { schema, capMessage: null, viewCapMessage: null, bindingCapMessage: null };
         const base = (schema ?? {});
         const next = { ...base };
+        let capMessage = null;
+        let viewCapMessage = null;
+        let bindingCapMessage = null;
         if (objectKey !== false)
             next[objectKey] = composed.object;
         if (columns) {
@@ -139,7 +292,23 @@ export function useElementDataSourceSchema(schema, mapping = {}, dataSource) {
             // Component filter AND (view filter AND binding filter). `composed.filter`
             // already carries the latter pair; a single surviving source comes back
             // unwrapped, so the common "only the view filters" case stays flat.
-            const merged = mergeFilterNodes(base.filter, composed.filter);
+            //
+            // ⚠️ Each source is lowered through `toFilterNodeSafely` first, the way
+            // `RelatedList` and `LineItemsPanel` lower their own filter before they
+            // merge it — objectui#10789. This is a RENDER-time `useMemo`, and the
+            // lowering refuses malformed authored shapes with a `FilterOperatorError`:
+            // uncaught, that was a render error, thrown BEFORE the wrapped block
+            // reached its own safe lowering and its malformed-filter state. The
+            // refusal is returned as a VALUE and the block is not rendered at all —
+            // never merged as "no filter", which would run it unconstrained. The
+            // merge below then only re-reads nodes the lowering already produced.
+            const own = toFilterNodeSafely(base.filter);
+            if (!own.ok)
+                return { schema, capMessage: null, viewCapMessage: null, bindingCapMessage: null, filterRefusal: own.refusal };
+            const bound = toFilterNodeSafely(composed.filter);
+            if (!bound.ok)
+                return { schema, capMessage: null, viewCapMessage: null, bindingCapMessage: null, filterRefusal: bound.refusal };
+            const merged = mergeFilterNodes(own.node, bound.node);
             if (merged !== undefined)
                 next.filter = merged;
             else
@@ -153,38 +322,172 @@ export function useElementDataSourceSchema(schema, mapping = {}, dataSource) {
                 next.sort = composed.sort;
         }
         if (limit && composed.limit !== undefined) {
-            const fromView = binding.config?.limit === undefined;
-            if (!fromView || readLimit(base, limit) === undefined) {
+            // For the row cap, "declared one" means a cap the contract admits
+            // (objectui#10016): a refused binding `limit` is not authored, so the
+            // composer let the view's cap through in its place, and that cap is a
+            // baseline the component's usable cap still wins over.
+            const fromView = !isUsableRowLimit(binding.config?.limit);
+            // PRESENCE is not authorship (objectui#9899) — the same question the
+            // `columns` branch above answers by CONTENT, answered the same way here.
+            const authored = readLimit(base, limit);
+            if (!fromView || !isUsableRowLimit(authored)) {
                 writeLimit(next, base, limit, composed.limit);
+                capMessage = describeDisplacedRowLimit(authored, limit, composed.limit, base.type, composed.object);
             }
         }
+        // Outside the branch above on purpose: a refused cap never reaches
+        // `composed.limit`, so that branch does not run for it (objectui#10015,
+        // and objectui#10016 for the binding's).
+        if (limit) {
+            viewCapMessage = describeRefusedViewRowLimit(binding.view, binding.config, readLimit(base, limit));
+            bindingCapMessage = describeRefusedBindingRowLimit(binding.view, binding.config);
+        }
         if (viewType && composed.viewType !== undefined && base.viewType === undefined) {
             next.viewType = composed.viewType;
         }
-        return next;
-    }, [schema, binding.composed, binding.config, objectKey, columns, filter, sort, limit, viewType]);
-    return React.useMemo(() => ({
-        status: binding.status,
-        schema: mapped,
-        config: binding.config,
-        error: binding.error,
-    }), [binding.status, binding.config, binding.error, mapped]);
+        return { schema: next, capMessage, viewCapMessage, bindingCapMessage };
+    }, [schema, binding.composed, binding.config, binding.view, objectKey, columns, filter, sort, limit, viewType]);
+    // Keyed on the MESSAGE, so it is one warning per declaration rather than one
+    // per render — and it fires from an effect, never from render, which is the
+    // same shape the renderer sites use for "you declared it, we dropped it".
+    // One effect per message, so a change to one never re-emits another.
+    const { schema: boundSchema, capMessage, viewCapMessage, bindingCapMessage, filterRefusal: mergeRefusal } = mapped;
+    React.useEffect(() => {
+        if (capMessage)
+            console.warn(capMessage);
+    }, [capMessage]);
+    React.useEffect(() => {
+        if (viewCapMessage)
+            console.warn(viewCapMessage);
+    }, [viewCapMessage]);
+    React.useEffect(() => {
+        if (bindingCapMessage)
+            console.warn(bindingCapMessage);
+    }, [bindingCapMessage]);
+    // A refused filter — from either merge — is `missing`, the one state every
+    // caller already answers by withholding the block (objectui#10789).
+    const filterRefusal = binding.filterRefusal ?? mergeRefusal;
+    return React.useMemo(() => filterRefusal
+        ? {
+            status: 'missing',
+            schema: boundSchema,
+            config: binding.config,
+            error: filterRefusal.message,
+            filterRefusal,
+        }
+        : {
+            status: binding.status,
+            schema: boundSchema,
+            config: binding.config,
+            error: binding.error,
+        }, [binding.status, binding.config, binding.error, boundSchema, filterRefusal]);
 }
 /**
  * The "named view does not resolve" panel. Same posture (and shape) as
  * `SchemaRenderer`'s "Unknown component type": authored metadata pointing at
  * something that is not there, reported where the author can see it.
  */
-export function ElementDataSourceErrorPanel({ testId, title = 'This component’s data source could not be resolved', message, }) {
-    return (_jsxs("div", { className: "p-4 border border-red-500 rounded text-red-500 bg-red-50 my-2", role: "alert", "data-testid": `${testId}-datasource-error`, children: [_jsx("p", { className: "font-medium", children: title }), message ? _jsx("p", { className: "text-sm mt-1", children: message }) : null] }));
+export function ElementDataSourceErrorPanel({ testId, title, message, }) {
+    // objectui#12920 — the default reads the bundle; it was an English literal.
+    // Only an ABSENT `title` takes it, as the parameter default did. The hook
+    // runs on this error path only, for the reason
+    // {@link ElementDataSourceMalformedFilterPanel} gives, and the inline
+    // `defaultValue` is the `en` pack's value (`pnpm check:i18n-keys`).
+    const { t } = useObjectTranslation();
+    const heading = title === undefined
+        ? t('element.component.sourceUnresolved', {
+            defaultValue: 'This component’s data source could not be resolved',
+        })
+        : title;
+    return (_jsxs("div", { className: "p-4 border border-red-500 rounded text-red-500 bg-red-50 my-2", role: "alert", "data-testid": `${testId}-datasource-error`, children: [_jsx("p", { className: "font-medium", children: heading }), message ? _jsx("p", { className: "text-sm mt-1", children: message }) : null] }));
 }
+/**
+ * The malformed-filter notice, drawn IN PLACE OF the block when a filter the
+ * gate had to merge is refused (objectui#10789).
+ *
+ * It is the notice the wrapped blocks draw themselves (objectui#9050 step 2 —
+ * `record:related_list`, the line-items panel, `object-grid`): the same
+ * sentence (`view.malformedFilter`), naming the refused operator or field in a
+ * separately addressable headline, with the refusal's own message beneath it.
+ * The gate draws it because its merge refuses FIRST — before the block's own
+ * safe lowering ever runs — so without it the author would get the error
+ * boundary's "failed to render" instead of the sentence those blocks give.
+ *
+ * ⚠️ A separate component, so `useObjectTranslation` runs only on this path:
+ * the gate wraps every object-bound block, and a translation hook in the
+ * gate's own body would run for all of them, including under the many suites
+ * that mock `@object-ui/i18n` by hand.
+ *
+ * The provider-less default is the sentence itself, written the way the
+ * sibling blocks carry it: a LITERAL copy of the `en` pack's value, never a
+ * read of the pack object. The siblings keep theirs in a module-scope
+ * `createSafeTranslation` table, which this module cannot have: it is
+ * re-exported from the package entry, so a factory call at module scope would
+ * run on import for every consumer (`NonGridRowCeilingNote` records that
+ * hazard). So the copy sits in the call's inline `defaultValue`, where
+ * `pnpm check:i18n-keys` holds it byte-identical to the pack, as the siblings'
+ * tables are held. With an `I18nProvider` the pack's value wins, and without
+ * one this literal is interpolated (objectui#6219).
+ */
+function ElementDataSourceMalformedFilterPanel({ testId, refusal, }) {
+    const { t } = useObjectTranslation();
+    return (_jsxs("div", { role: "alert", className: "rounded-md border border-amber-300 bg-amber-50 p-3 my-2 text-sm text-amber-800", "data-testid": `${testId}-malformed-filter`, children: [_jsx("p", { className: "font-medium", "data-testid": `${testId}-malformed-filter-subject`, children: t('view.malformedFilter', {
+                    subject: filterRefusalSubject(refusal) ?? '',
+                    defaultValue: 'This view’s filter is malformed, so no records are shown: the {{subject}} condition cannot be applied.',
+                }) }), _jsx("p", { className: "mt-1 text-xs opacity-80", children: refusal.message })] }));
+}
+/**
+ * The "no object named" hint, drawn IN PLACE OF the block when a placement
+ * that opted in with `requiresObject` names its object in neither place: not
+ * on the block's own object key, and not through `dataSource.object`
+ * (objectui#11605).
+ *
+ * Why it exists: the object-bound registrations no longer declare their object
+ * key `required`, because the binding can supply it and the manifest has no
+ * "this key or that binding" form. So the page compile accepts a node that
+ * names no object at all, and this hint is the one signal left for it. Before
+ * it, those blocks drew an empty board, a field-less form, a dash or a "no
+ * data yet" state, which reads as an empty query rather than a missing object.
+ *
+ * The wording is `element:number`'s own no-object notice (objectui#10951) with
+ * the property as a hole, so the two blocks that answer this question say it
+ * the same way. The property name is interpolated, never translated.
+ *
+ * A separate component for the reason {@link ElementDataSourceMalformedFilterPanel}
+ * gives: `useObjectTranslation` runs only on this path, and the provider-less
+ * default is a literal copy of the `en` pack's value, held byte-identical to it
+ * by `pnpm check:i18n-keys`.
+ */
+function ElementDataSourceNoObjectPanel({ testId, property, }) {
+    const { t } = useObjectTranslation();
+    return (_jsx("div", { className: "p-4 text-sm text-muted-foreground my-2", "data-testid": `${testId}-no-object`, children: t('view.noObject', {
+            property,
+            defaultValue: 'No object named: set {{property}} or dataSource.object.',
+        }) }));
+}
+/**
+ * Does the bound schema name an object on `key`? A blank string names nothing,
+ * the same reading `noDataSourceMessage` gives an object name.
+ */
+const namesObject = (schema, key) => {
+    const value = schema?.[key];
+    return typeof value === 'string' && value.trim().length > 0;
+};
 /**
  * The "saved views are still being fetched" placeholder. Distinct from the error
  * panel because a component that treated "not resolved yet" as "does not exist"
  * would flash a configuration error on every mount.
+ *
+ * Its copy reads `common.loading` (objectui#12889), the key the rest of the
+ * tree reads for a bare "Loading…": it printed an English "Loading view…" on
+ * every locale before. `useObjectTranslation` runs only while a view resolves,
+ * for the reason {@link ElementDataSourceMalformedFilterPanel} gives, and the
+ * inline `defaultValue` is the `en` pack's value, held byte-identical to it by
+ * `pnpm check:i18n-keys`.
  */
 export function ElementDataSourceLoadingPanel({ testId, }) {
-    return (_jsx("div", { className: "p-2 text-sm text-muted-foreground animate-pulse", role: "status", "aria-live": "polite", "data-testid": `${testId}-resolving-view`, children: "Loading view\u2026" }));
+    const { t } = useObjectTranslation();
+    return (_jsx("div", { className: "p-2 text-sm text-muted-foreground animate-pulse", role: "status", "aria-live": "polite", "data-testid": `${testId}-resolving-view`, children: t('common.loading', { defaultValue: 'Loading…' }) }));
 }
 /**
  * The adapter this block would use, resolved the one way every block in the
@@ -203,6 +506,9 @@ export function ElementDataSourceLoadingPanel({ testId, }) {
  * it off and you get `unknown`, which is the honest default.
  */
 export function useResolvedDataSource(explicit) {
+    // Read AS DECLARED (objectui#7209): the only cast in this hook is the
+    // caller's `T` on the way out, never one erasing the context on the way in.
+    // Pinned by `useResolvedDataSource.schemaRendererContextRead-7209.test.ts`.
     const context = React.useContext(SchemaRendererContext);
     const named = isElementDataSourceConfig(explicit) ? undefined : explicit;
     return (named ?? context?.dataSource ?? undefined);
@@ -241,9 +547,72 @@ export function noDataSourceMessage(blockKey, objectName) {
  * WIRING one level up. Same posture as {@link ElementDataSourceErrorPanel}: the
  * metadata is answerable, so the answer is rendered where the author can see it.
  */
-export function NoDataSourcePanel({ testId, title = 'No data source resolved', message, }) {
-    return (_jsxs("div", { className: "p-4 border border-red-500 rounded text-red-500 bg-red-50 my-2", role: "alert", "data-testid": `${testId}-no-data-source`, children: [_jsx("p", { className: "font-medium", children: title }), message ? _jsx("p", { className: "text-sm mt-1", children: message }) : null] }));
+export function NoDataSourcePanel({ testId, title, message, }) {
+    // objectui#12920 — same reading as {@link ElementDataSourceErrorPanel}: an
+    // absent `title` reads the bundle, a passed one wins.
+    const { t } = useObjectTranslation();
+    const heading = title === undefined
+        ? t('element.component.noDataSource', { defaultValue: 'No data source resolved' })
+        : title;
+    return (_jsxs("div", { className: "p-4 border border-red-500 rounded text-red-500 bg-red-50 my-2", role: "alert", "data-testid": `${testId}-no-data-source`, children: [_jsx("p", { className: "font-medium", children: heading }), message ? _jsx("p", { className: "text-sm mt-1", children: message }) : null] }));
 }
+/**
+ * The wrapping seam — mark `renderer` as one that wraps {@link
+ * ElementDataSourceGate}, so its registrations DECLARE the `dataSource` key this
+ * gate READS (objectui#6678).
+ *
+ * ```tsx
+ * export const ObjectMapRenderer = elementDataSourceBlock<React.FC<any>>(({ schema }) => (
+ *   <ElementDataSourceGate schema={schema} testId="object-map" …>
+ *     {(bound) => <ObjectMap schema={bound} />}
+ *   </ElementDataSourceGate>
+ * ));
+ * ```
+ *
+ * ## What this closes
+ *
+ * `PageComponentSchema.dataSource` is the one spelling that resolves a saved
+ * view for an object-bound block. It works — and because no registration
+ * declared it, `sdui-parser`'s `validateTree` reported it with the SAME
+ * `unknown-prop` warning it gives the spellings that do nothing. On the tier
+ * built to accept AI-authored pages the diagnostic IS the contract, so the
+ * tier's only signal pointed away from the one key that works.
+ *
+ * ## Why a seam and not nine declarations
+ *
+ * Maintainer ruling, 2026-08-29: option B **in the injection form**. Nine
+ * hand-written copies across nine packages is the shape that ruling refused —
+ * they drift, and the tenth block forgets. Passing through here is the only
+ * thing a block does; `Registry.register` emits the declaration
+ * (`withElementDataSourceInput`), and `ELEMENT_DATA_SOURCE_INPUT` in
+ * `@object-ui/core` is its single copy, beside the binding's own semantics.
+ *
+ * ## And it cannot be forgotten
+ *
+ * `scripts/check-element-data-source-declaration.mjs` fails any source that
+ * renders `ElementDataSourceGate` for a registration without passing that
+ * registration's renderer through this function. That is the mechanical half of
+ * "a tenth block gets it automatically"; this function is the seam it enforces.
+ *
+ * Returns the renderer UNCHANGED (the mark is held in a `WeakSet`), so it is safe
+ * over a `React.forwardRef` object, over `React.memo`, and over a component that
+ * something else already re-exports by reference.
+ *
+ * ⚠️ Re-exported from `@object-ui/core` — where the marker and the declaration
+ * live — rather than wrapped here: ONE function under ONE name. This export
+ * exists for DISCOVERABILITY, so the seam is findable beside the gate it is
+ * about; **call sites must import it from `@object-ui/core`**, and
+ * `check:element-data-source-declaration` enforces that.
+ *
+ * The rule is measured, not stylistic. A registration runs at MODULE SCOPE, 101
+ * suites in this repo partially mock `@object-ui/react` by hand-listing the
+ * exports they return, and a module-scope read of a name absent from such a list
+ * throws at COLLECTION time — the importing test file dies before running one
+ * assertion. Taking the seam from here reddened 17 files across all four CI
+ * shards with zero failed assertions among them. Nothing mocks `@object-ui/core`,
+ * and every registration module already imports `ComponentRegistry` from it.
+ */
+export { elementDataSourceBlock } from '@object-ui/core';
 /**
  * Wrap an object-bound block so its `dataSource` binding reaches the keys it
  * reads, and so the two non-final resolution states render once, the same way,
@@ -253,7 +622,7 @@ export function NoDataSourcePanel({ testId, title = 'No data source resolved', m
  * against a half-resolved query is how a page shows a wider answer than the one
  * that was authored.
  */
-export function ElementDataSourceGate({ schema, mapping, dataSource, testId, errorTitle, requiresDataSource, noDataSourceMessage: noDataSourceText, children, }) {
+export function ElementDataSourceGate({ schema, mapping, dataSource, testId, errorTitle, requiresDataSource, noDataSourceMessage: noDataSourceText, requiresObject, children, }) {
     const bound = useElementDataSourceSchema(schema, mapping, dataSource);
     const adapter = useResolvedDataSource(dataSource);
     // Reported BEFORE the view state, because with no adapter every downstream
@@ -264,11 +633,24 @@ export function ElementDataSourceGate({ schema, mapping, dataSource, testId, err
     if (requiresDataSource && adapter == null) {
         return _jsx(NoDataSourcePanel, { testId: testId, message: noDataSourceText });
     }
+    // A refused filter is `missing` too, but it gets the malformed-filter notice
+    // rather than the "could not be resolved" panel: the binding resolved, and
+    // what the author has to fix is a filter condition (objectui#10789).
+    if (bound.filterRefusal) {
+        return _jsx(ElementDataSourceMalformedFilterPanel, { testId: testId, refusal: bound.filterRefusal });
+    }
     if (bound.status === 'missing') {
         return _jsx(ElementDataSourceErrorPanel, { testId: testId, title: errorTitle, message: bound.error });
     }
     if (bound.status === 'loading') {
         return _jsx(ElementDataSourceLoadingPanel, { testId: testId });
     }
+    // Named in neither place: not on the block's own key, and not by a binding
+    // (whose `object` the hook above has already landed on that key). See
+    // `requiresObject` for why the call site, not this gate, decides it applies.
+    const objectKey = mapping?.object ?? 'objectName';
+    if (requiresObject && objectKey !== false && !namesObject(bound.schema, objectKey)) {
+        return _jsx(ElementDataSourceNoObjectPanel, { testId: testId, property: objectKey });
+    }
     return children(bound.schema);
 }

package/dist/element-data-source/useElementApiDataSource.d.ts

@@ -0,0 +1,119 @@
+/**
+ * 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 renderer half of the spec's API binding of a page element (objectui#12197):
+ * `PageComponentSchema.dataSource` as `ElementApiDataSourceSchema`,
+ *
+ * ```json
+ * { "provider": "api", "read": { "url": "/api/v1/cloud/home" }, "path": "data" }
+ * ```
+ *
+ * The spec states what a renderer does with it: the element reads ONE
+ * same-origin endpoint with the console's signed-in fetch and binds the selected
+ * value, "which the element reads as `data` in its expression holes and its
+ * `visibleWhen`". `SchemaRenderer` is the one place both of those are evaluated,
+ * so it calls {@link useElementApiDataSource} for every node and binds the
+ * answer as the `data` root (see "The API binding" there). This module owns the
+ * read itself.
+ *
+ * ## The binding is judged by the spec's own schema
+ *
+ * A node's `dataSource` reaches the renderer as stored metadata, unparsed. The
+ * hook parses it with `ElementApiDataSourceSchema` before it reads anything,
+ * so a binding the spec refuses — an absolute or protocol-relative `url`, a
+ * credential key, a `method` other than `GET`, a malformed `path` — is
+ * `refused` here with the spec's own message, and no request is sent. There is
+ * no second, hand-kept same-origin rule in this repo to drift from the
+ * contract's.
+ *
+ * A `dataSource` that is not an API binding (absent, or the object binding
+ * `useElementDataSource` reads) is `absent` here: the two shapes are told apart
+ * by `provider: 'api'`, the spec's discriminator.
+ *
+ * ## The read
+ *
+ * Through `SchemaRendererContext.apiFetch`, the host's authenticated fetch the
+ * console hands every renderer (`ConsoleShell`), falling back to the global
+ * fetch only when no host supplies one — the rule every `apiFetch` reader in
+ * the tree follows. `GET`, `Accept: application/json`, `credentials: 'include'`.
+ * A non-2xx answer, a body that is not JSON, or a `path` that selects nothing
+ * is `error`, with a sentence naming which; the value is never guessed.
+ *
+ * Concurrent elements that bind the same URL share ONE request: {@link
+ * readElementApi} keeps a pending request per URL and forgets it the moment it
+ * settles, so it caches no answer (the shape `readStorageUsage` uses).
+ *
+ * @module
+ */
+import { type ElementApiDataSource } from '@objectstack/spec/ui';
+import { type ApiFetch } from '../context/SchemaRendererContext.js';
+/**
+ * Where an API binding stands.
+ *
+ *  - `absent` — the node carries no API binding; nothing is read.
+ *  - `refused` — the node carries one the spec refuses; nothing is read.
+ *  - `loading` — the read is in flight.
+ *  - `ready` — the read answered and `path` selected a value.
+ *  - `error` — the read failed, or `path` selected nothing.
+ */
+export type ElementApiDataSourceStatus = 'absent' | 'refused' | 'loading' | 'ready' | 'error';
+export interface UseElementApiDataSourceResult {
+    status: ElementApiDataSourceStatus;
+    /** The parsed binding, for every status but `absent` and `refused`. */
+    config?: ElementApiDataSource;
+    /** The selected value, set only for `ready`. */
+    data?: unknown;
+    /** Author-facing explanation, set for `refused` and `error`. */
+    error?: string;
+}
+/**
+ * Is this `dataSource` value the API binding — whatever it says beyond
+ * `provider`? `provider: 'api'` is the spec's discriminator between the two
+ * shapes of `PageComponentSchema.dataSource`; the object binding carries no
+ * `provider`.
+ */
+export declare function isElementApiDataSourceShape(value: unknown): boolean;
+/**
+ * Judge a node's `dataSource` as an API binding: `absent` when it is not one,
+ * `refused` with the spec's message when the spec refuses it, otherwise the
+ * parsed binding.
+ */
+export declare function judgeElementApiDataSource(value: unknown): {
+    status: 'absent';
+} | {
+    status: 'refused';
+    error: string;
+} | {
+    status: 'parsed';
+    config: ElementApiDataSource;
+};
+/**
+ * Select `path` (dotted segments; a numeric segment indexes an array) from a
+ * response body. `found: false` when any segment has nothing under it — an
+ * absent key, not a key whose value is `undefined`, is what "selects nothing"
+ * means.
+ */
+export declare function selectElementApiPath(body: unknown, path: string | undefined): {
+    found: true;
+    value: unknown;
+} | {
+    found: false;
+    segment: string;
+};
+/**
+ * `GET url` through `doFetch`, resolving with the parsed JSON body. Rejects on
+ * a network failure, a non-2xx answer or a body that is not JSON. Callers that
+ * ask while a read of the same URL is pending share it.
+ */
+export declare function readElementApi(url: string, doFetch: ApiFetch): Promise<unknown>;
+/**
+ * Resolve a node's API binding: read its endpoint and select its `path`.
+ *
+ * Called unconditionally by `SchemaRenderer` for every node; a node without an
+ * API binding costs one `isPlainObject` test and issues no request.
+ */
+export declare function useElementApiDataSource(schema: unknown): UseElementApiDataSourceResult;