@object-ui/react 17.7.0 → 18.0.0

package/dist/context/PrintPageContext.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 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 type { PagePrint } from '@objectstack/spec/ui';
+/**
+ * PrintPageContext — the `print` declaration of the page this subtree renders
+ * in, or `null` outside a print page (objectui#11958, card ② of the ruling of
+ * record on objectstack#8346).
+ *
+ * A page that declares `print` is a document: its blocks come from the spec's
+ * printable block subset (`PRINTABLE_PAGE_COMPONENT_TYPES` in
+ * `@objectstack/spec/ui`), and each of those blocks has to reach paper WHOLE.
+ * Most of them already do. The ones that draw a window of their data on screen
+ * read this context to stop doing so silently: `record:line_items` names its
+ * row cap when the cap cut lines off, and a collapsible `record:details`
+ * section draws open, because a closed section never reaches paper.
+ *
+ * Published by `PageRenderer` (`@object-ui/components`) for a page whose
+ * `print` is an object. The value is the declaration itself, so a block that
+ * ever needs one of its keys reads it from here rather than from a second
+ * channel. Defaults to `null`, so every page that does not declare `print` is
+ * untouched.
+ */
+declare const PrintPageContext: import("react").Context<{
+    paperSize?: "A4" | "A5" | "Letter" | "Legal" | undefined;
+    orientation?: "portrait" | "landscape" | undefined;
+    margins?: {
+        top?: number | undefined;
+        right?: number | undefined;
+        bottom?: number | undefined;
+        left?: number | undefined;
+    } | undefined;
+    repeatHeader?: boolean | undefined;
+    repeatFooter?: boolean | undefined;
+    pageNumbers?: boolean | undefined;
+    repeatTableHeaders?: boolean | undefined;
+    avoidBreakInside?: boolean | undefined;
+} | null>;
+export declare const PrintPageProvider: import("react").Provider<{
+    paperSize?: "A4" | "A5" | "Letter" | "Legal" | undefined;
+    orientation?: "portrait" | "landscape" | undefined;
+    margins?: {
+        top?: number | undefined;
+        right?: number | undefined;
+        bottom?: number | undefined;
+        left?: number | undefined;
+    } | undefined;
+    repeatHeader?: boolean | undefined;
+    repeatFooter?: boolean | undefined;
+    pageNumbers?: boolean | undefined;
+    repeatTableHeaders?: boolean | undefined;
+    avoidBreakInside?: boolean | undefined;
+} | null>;
+/** The enclosing page's `print` declaration, or `null` outside a print page. Safe outside a provider. */
+export declare const usePrintPage: () => PagePrint | null;
+export { PrintPageContext };

package/dist/context/PrintPageContext.js

@@ -0,0 +1,32 @@
+/**
+ * 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 { createContext, useContext } from 'react';
+/**
+ * PrintPageContext — the `print` declaration of the page this subtree renders
+ * in, or `null` outside a print page (objectui#11958, card ② of the ruling of
+ * record on objectstack#8346).
+ *
+ * A page that declares `print` is a document: its blocks come from the spec's
+ * printable block subset (`PRINTABLE_PAGE_COMPONENT_TYPES` in
+ * `@objectstack/spec/ui`), and each of those blocks has to reach paper WHOLE.
+ * Most of them already do. The ones that draw a window of their data on screen
+ * read this context to stop doing so silently: `record:line_items` names its
+ * row cap when the cap cut lines off, and a collapsible `record:details`
+ * section draws open, because a closed section never reaches paper.
+ *
+ * Published by `PageRenderer` (`@object-ui/components`) for a page whose
+ * `print` is an object. The value is the declaration itself, so a block that
+ * ever needs one of its keys reads it from here rather than from a second
+ * channel. Defaults to `null`, so every page that does not declare `print` is
+ * untouched.
+ */
+const PrintPageContext = createContext(null);
+export const PrintPageProvider = PrintPageContext.Provider;
+/** The enclosing page's `print` declaration, or `null` outside a print page. Safe outside a provider. */
+export const usePrintPage = () => useContext(PrintPageContext);
+export { PrintPageContext };

package/dist/context/RelatedRecordActionsContext.d.ts

@@ -30,6 +30,10 @@
  * it can route to, so the low-level renderers on a record page can turn a
  * lookup VALUE into a link to the referenced record without assembling a URL
  * of their own. Same provider, same builder, one route shape.
+ *
+ * Since objectui#12703 it also publishes the object-list URL builder
+ * ({@link RelatedRecordActionsValue.listHref} / `openList`), for a renderer
+ * that shows a few of an object's records and links to the rest.
  */
 import React from 'react';
 /** A child-object action surfaced in a related list's row menu. */
@@ -100,8 +104,40 @@ export interface RelatedRecordHandlers {
     toolbarActions?: RelatedRowActionDef[];
     /** Execute one of {@link toolbarActions} (no row context). */
     onToolbarAction?: (action: RelatedRowActionDef) => void | Promise<void>;
+    /**
+     * Open the child object's full list page, scoped to THIS parent on the
+     * relationship `resolve` was handed (objectui#12741). The related list's
+     * "View all" link calls it, unless the block declares `showViewAll: false`.
+     *
+     * The host builds the destination because only the host knows the console's
+     * routes, as it does for {@link onView}. It omits the handler when no route
+     * it has can show that scoped list, and the link is then not drawn. One case
+     * is a multi-value relationship: the list route's URL filter has no
+     * membership operator. Another is a relationship field the viewer cannot
+     * read: the list route drops that condition and would show every row.
+     */
+    onViewAll?: () => void;
 }
-/** Input to {@link RelatedRecordActionsValue.resolve}. */
+/**
+ * Input to {@link RelatedRecordActionsValue.resolve}.
+ *
+ * Its SHAPE says which kind of list asks (objectui#13089):
+ *
+ *  - **A related list always names its `relationshipField`.** The spec's
+ *    `record:related_list` declares it required, so a spec-valid related list
+ *    resolves with it, with or without a resolved `parentId`.
+ *  - **An input with no `relationshipField` (absent or empty) asks for an
+ *    OBJECT-SCOPED list's handlers**, a list of the object's own records with
+ *    no parent: a page `list-view` node resolves `{ objectName }` for its
+ *    `addRecord` Add button. A host may serve such an input a create that
+ *    links no parent, which it must not serve a related list whose parent did
+ *    not resolve.
+ *
+ * ⚠️ The limit of reading the shape: a future consumer that resolves a list
+ * with no parent and no relationship, and must NOT be offered a create, cannot
+ * say so here. It needs an explicit member on this input, not a second reading
+ * of the same shape.
+ */
 export interface ResolveRelatedRecordActionsInput {
     /** Child object machine name (the related list's `api`). */
     objectName: string;
@@ -132,6 +168,11 @@ export interface RelatedRecordActionsValue {
      *
      * Returns `null` when the host cannot route to that object (unknown object,
      * no app context), which consumers must render as the plain value.
+     *
+     * The value is a document href, read by the browser on "open in new tab" and
+     * "copy link address", so it carries the host router's basename (for
+     * example `/_console/apps/…`), while {@link openRecord} navigates by the
+     * router path (objectui#12233).
      */
     recordHref?: (objectName: string, recordId: string | number) => string | null;
     /**
@@ -140,6 +181,31 @@ export interface RelatedRecordActionsValue {
      * in-app; a modifier click is left to the browser and the href.
      */
     openRecord?: (objectName: string, recordId: string | number) => void;
+    /**
+     * The host's list-page URL for an object it can route to, optionally opened
+     * on one of the object's saved views (objectui#12703). The list-side twin of
+     * {@link recordHref}: a renderer that shows a few of an object's records (the
+     * compact list a page draws in a narrow region) presents "View all" as a real
+     * anchor to this destination, without assembling a URL of its own.
+     *
+     * `viewName` names a saved view of that object, as the block binding states
+     * it (`dataSource.view`); absent, the destination is the object's own list.
+     * The destination is a view or the object, never a query: a caller does not
+     * encode its own filter, columns or sort into it, and the host has no
+     * argument to receive them.
+     *
+     * Returns `null` when the host cannot route to that object (unknown object,
+     * no app context); consumers then draw no link. Like {@link recordHref} it is
+     * a document href that carries the router's basename, while {@link openList}
+     * navigates by the router path.
+     */
+    listHref?: (objectName: string, viewName?: string) => string | null;
+    /**
+     * SPA-navigate to the destination {@link listHref} addresses. Consumers call
+     * this from a plain left click on the anchor; a modifier click is left to the
+     * browser and the href.
+     */
+    openList?: (objectName: string, viewName?: string) => void;
 }
 export declare const RelatedRecordActionsProvider: React.FC<{
     value: RelatedRecordActionsValue;

package/dist/context/RelatedRecordActionsContext.js

@@ -31,6 +31,10 @@ import { jsx as _jsx } from "react/jsx-runtime";
  * it can route to, so the low-level renderers on a record page can turn a
  * lookup VALUE into a link to the referenced record without assembling a URL
  * of their own. Same provider, same builder, one route shape.
+ *
+ * Since objectui#12703 it also publishes the object-list URL builder
+ * ({@link RelatedRecordActionsValue.listHref} / `openList`), for a renderer
+ * that shows a few of an object's records and links to the rest.
  */
 import { createContext, useContext } from 'react';
 const RelatedRecordActionsContext = createContext(null);

package/dist/context/SchemaRendererContext.d.ts

@@ -2,10 +2,13 @@ import React from 'react';
 import type { DebugFlags } from '@object-ui/core';
 import type { DataSource } from '@object-ui/types';
 /**
- * Host-provided fetch used for `provider: 'api'` view data sources so custom
- * endpoints carry the same credentials (Authorization, tenant, locale headers)
- * as the native data channel. Optional — when absent, ApiDataSource falls back
- * to the bare global fetch (cookies only).
+ * Host-provided fetch the renderers use for their own reads of the host's API
+ * (a chart's metadata reads, dataset dimension labels, record-permission
+ * probes), so those reads carry the same credentials (Authorization, tenant,
+ * locale headers) as the native data channel. Optional — when absent, those
+ * reads fall back to the bare global fetch (cookies only). A view does not
+ * reach it: a view binds `provider: 'object'` or `provider: 'value'`, and a
+ * code-built `ApiDataSource` takes its own `fetch` in its config.
  */
 export type ApiFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
 interface SchemaRendererContextType {

package/dist/context/SchemaRendererContext.js

@@ -6,7 +6,7 @@ export { SchemaRendererContext };
 export const SchemaRendererProvider = ({ children, dataSource, debug, debugFlags, apiFetch, }) => {
     // Nested providers (react-page, studio preview surfaces) re-wrap with their
     // own dataSource but rarely know about the host's authenticated fetch —
-    // inherit it from the parent context so provider:'api' auth survives nesting.
+    // inherit it from the parent context so the host's auth survives nesting.
     const parent = useContext(SchemaRendererContext);
     const effectiveApiFetch = apiFetch ?? parent?.apiFetch;
     const value = useMemo(() => ({ dataSource, debug, debugFlags, apiFetch: effectiveApiFetch }), [dataSource, debug, debugFlags, effectiveApiFetch]);

package/dist/context/index.d.ts

@@ -11,3 +11,4 @@ export * from './DiscussionContext.js';
 export * from './DrillNavigationContext.js';
 export * from './HostNavigationContext.js';
 export * from './RelatedRecordActionsContext.js';
+export * from './PrintPageContext.js';

package/dist/context/index.js

@@ -11,3 +11,4 @@ export * from './DiscussionContext.js';
 export * from './DrillNavigationContext.js';
 export * from './HostNavigationContext.js';
 export * from './RelatedRecordActionsContext.js';
+export * from './PrintPageContext.js';

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

@@ -0,0 +1,28 @@
+/**
+ * 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 error panel of a page element's API binding (objectui#12197), titled in
+ * the page's language.
+ *
+ * `SchemaRenderer` draws it in place of a node whose binding the spec refused
+ * or whose read failed. The translation hook lives HERE, not in
+ * `SchemaRenderer`'s body: that body runs for every node on every page, and a
+ * language subscription there would re-render the whole tree on a language
+ * change. This component mounts only on the error path, so only it subscribes.
+ * The panel itself is {@link ElementDataSourceErrorPanel}; the inline
+ * `defaultValue`s are the `en` pack's values (`pnpm check:i18n-keys`).
+ */
+import * as React from 'react';
+export interface ElementApiDataSourcePanelProps {
+    /** `data-testid` stem — the node's registry key. */
+    testId: string;
+    /** `refused`: the spec's schema refused the binding. `error`: the read failed. */
+    state: 'refused' | 'error';
+    /** Why — the spec's refusal, or the failed read's sentence. */
+    message?: string;
+}
+export declare function ElementApiDataSourcePanel({ testId, state, message, }: ElementApiDataSourcePanelProps): React.ReactElement;

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

@@ -0,0 +1,10 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useObjectTranslation } from '@object-ui/i18n';
+import { ElementDataSourceErrorPanel } from './ElementDataSourceGate.js';
+export function ElementApiDataSourcePanel({ testId, state, message, }) {
+    const { t } = useObjectTranslation();
+    const title = state === 'refused'
+        ? t('element.component.apiRefused', { defaultValue: 'This component’s API data source is refused' })
+        : t('element.component.apiUnreadable', { defaultValue: 'This component’s API data source could not be read' });
+    return _jsx(ElementDataSourceErrorPanel, { testId: testId, title: title, message: message });
+}

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

@@ -193,7 +193,10 @@ export interface ElementDataSourceStatusPanelProps {
      * asserting about rather than a shared anonymous id.
      */
     testId: string;
-    /** Panel heading; defaults to a block-neutral sentence. */
+    /**
+     * Panel heading; defaults to a block-neutral sentence read from the bundle
+     * (objectui#12920). A passed `title`, an empty string included, wins.
+     */
     title?: string;
     /** The author-facing explanation from {@link useElementDataSourceSchema}. */
     message?: string;
@@ -208,6 +211,13 @@ export declare function ElementDataSourceErrorPanel({ testId, title, message, }:
  * 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 declare function ElementDataSourceLoadingPanel({ testId, }: Pick<ElementDataSourceStatusPanelProps, 'testId'>): React.ReactElement;
 /**
@@ -340,6 +350,24 @@ export interface ElementDataSourceGateProps<S> {
     requiresDataSource?: boolean;
     /** Explanation for the no-adapter panel; see {@link noDataSourceMessage}. */
     noDataSourceMessage?: string;
+    /**
+     * Whether THIS placement has nothing to show unless it names an object — when
+     * true and the bound schema names none on the mapping's object key (neither
+     * the node's own key nor `dataSource.object` landing on it), the gate renders
+     * the "no object named" hint instead of the block (objectui#11605).
+     *
+     * Read AFTER the binding is applied, so a node bound by `dataSource.object`
+     * is never told it names no object; and AFTER the view states, so a binding
+     * that is still resolving or failed to resolve keeps its own panel.
+     *
+     * The call site states it, for the reason {@link requiresDataSource} gives:
+     * the other record sources a block can draw from (inline `data`, inline
+     * `customFields`, a `dataset`, a `bind` path) are each block's own, and a
+     * predicate guessed here would paint a configuration hint over a block that
+     * is working. A mapping whose `object` is `false` lands no object key, so
+     * this prop does nothing there.
+     */
+    requiresObject?: boolean;
     /**
      * Renders the block with the bound schema. Called during the gate's own
      * render, so it must RETURN AN ELEMENT and never call hooks itself — the
@@ -356,4 +384,4 @@ export interface ElementDataSourceGateProps<S> {
  * against a half-resolved query is how a page shows a wider answer than the one
  * that was authored.
  */
-export declare function ElementDataSourceGate<S>({ schema, mapping, dataSource, testId, errorTitle, requiresDataSource, noDataSourceMessage: noDataSourceText, children, }: ElementDataSourceGateProps<S>): React.ReactElement | null;
+export declare function ElementDataSourceGate<S>({ schema, mapping, dataSource, testId, errorTitle, requiresDataSource, noDataSourceMessage: noDataSourceText, requiresObject, children, }: ElementDataSourceGateProps<S>): React.ReactElement | null;

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

@@ -387,8 +387,19 @@ export function useElementDataSourceSchema(schema, mapping = {}, dataSource) {
  * `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
@@ -425,13 +436,58 @@ function ElementDataSourceMalformedFilterPanel({ testId, 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
@@ -491,8 +547,14 @@ 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
@@ -560,7 +622,7 @@ export { elementDataSourceBlock } from '@object-ui/core';
  * 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
@@ -583,5 +645,12 @@ export function ElementDataSourceGate({ schema, mapping, dataSource, testId, err
     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;