@object-ui/react 17.3.0 → 17.6.0

package/dist/context/AppShellContext.d.ts

@@ -1,7 +1,26 @@
 import type { ObjectStackAdapter } from '@object-ui/data-objectstack';
 export declare const AdapterCtx: import("react").Context<ObjectStackAdapter<unknown> | null>;
 export declare function useAdapter(): ObjectStackAdapter | null;
-export interface MetadataState {
+/**
+ * The metadata PROVIDER's cache — the collections `<MetadataProvider>` holds in
+ * React state, plus its aggregate load flags.
+ *
+ * Renamed from `MetadataState` in objectui#4167. `@objectstack/spec` 17.0.0-rc.6
+ * publishes `MetadataState` from `@objectstack/spec/system`, and it names a
+ * different thing in the SAME domain and the SAME two words: a metadata item's
+ * LIFECYCLE state, `'draft' | 'active' | 'deprecated' | 'archived'`
+ * (`MetadataStateSchema`). That is the `AuthProviderConfig` judgement from
+ * objectstack#4115 batch 5, not the `AuthProvider` one — nothing about a JSX
+ * element can be mistaken for a zod enum, but "the metadata state" absolutely
+ * can be read as canonical for the lifecycle enum by the next agent, and the
+ * two are mutually unassignable (an object of five arrays vs a string union),
+ * so nothing would have caught the misreading at the point it was made.
+ *
+ * `Cache` rather than a bare disambiguating prefix because it is what this is:
+ * `MetadataProvider` is a TTL cache with per-type entries, and these five
+ * arrays are its materialized contents.
+ */
+export interface MetadataCacheState {
     apps: any[];
     objects: any[];
     dashboards: any[];
@@ -11,7 +30,7 @@ export interface MetadataState {
     error: Error | null;
 }
 export type MetadataTypeStatus = 'idle' | 'loading' | 'ready' | 'error';
-export interface MetadataContextValue extends MetadataState {
+export interface MetadataContextValue extends MetadataCacheState {
     refresh: (type?: string) => Promise<void>;
     invalidate: (type: string, name?: string) => void;
     ensureType: (type: string) => Promise<any[]>;

package/dist/context/HostNavigationContext.d.ts

@@ -0,0 +1,82 @@
+/**
+ * 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.
+ */
+/**
+ * HostNavigationContext — the host's own in-app navigate, offered to renderers.
+ *
+ * A published renderer package cannot navigate correctly on its own. Its only
+ * dependency-free option is a browser-level navigation
+ * (`window.location.assign`), which resolves a rooted path such as `/thanks`
+ * against the ORIGIN. Under a host mounted at a sub-path — the framework CLI
+ * configures one for every embedded deployment — that leaves the application
+ * entirely. This is objectui#4989 defect 4, and the same class as
+ * objectui#4190 / #4181.
+ *
+ * The host is the only party that knows its mount, so the host supplies the
+ * navigate. This context is that seam: **optional injection**, ruled by the
+ * maintainer on 2026-08-17. Two mechanisms were rejected in that ruling and are
+ * named here so they are not re-proposed:
+ *
+ *   - **router-presence sniffing** (a renderer reading React Router's context
+ *     when it happens to be there) — implicit magic, and it forces every
+ *     renderer that wants mount-awareness to import `react-router`;
+ *   - **a `react-router` peer requirement** — it imposes module resolution on
+ *     router-less consumers. Two real ones exist in this repo (`apps/site`,
+ *     `packages/plugin-view`), and a published renderer's whole property is
+ *     that it drops into ANY React application.
+ *
+ * Explicit injection keeps every renderer dependency-free and puts
+ * mount-awareness on the type face where a host can see it is missing.
+ *
+ * ## Absent is a supported state, not a degraded one
+ *
+ * The default value is an empty object, so `useHostNavigation()` outside a
+ * provider answers `{ navigate: undefined }` and never throws. A consumer reads
+ * it as "no host navigate — fall back to whatever this renderer did before",
+ * which for a router-less host is already the correct behaviour: with no
+ * router there is no basename, so origin-rooted resolution is right. The seam
+ * changes what a MOUNTED host gets, and changes nothing else.
+ *
+ * ## Relationship to the other navigation seams in this package
+ *
+ * `DrillNavigationContext.openRecordList` is a SEMANTIC navigation — "show me
+ * the records behind this aggregate" — that only the console can turn into a
+ * URL. `ActionProvider`'s `onNavigate` is the ActionRunner's handler for
+ * `type: 'navigate'` actions, reachable only through an action dispatch. This
+ * one is neither: it is the plain "go to this already-resolved in-app path"
+ * that a renderer holds a destination for and cannot perform correctly itself.
+ * All three are supplied by the same shell from the same router `navigate`.
+ */
+import React from 'react';
+export interface HostNavigationValue {
+    /**
+     * Navigate to an in-app path, resolved by the HOST — so a mounted host's
+     * basename is applied and the transition stays inside the application.
+     *
+     * `to` is an already-resolved, application-relative path (e.g. `/thanks`,
+     * `/apps/crm/accounts/r1`), never an absolute URL: a renderer that holds an
+     * external destination must not launder it through the host's router. It is
+     * the CALLER's job to have judged the destination — this seam performs a
+     * navigation, it does not authorize one.
+     *
+     * Absent when no host wired it; consumers fall back to their own default.
+     */
+    navigate?: (to: string, options?: {
+        replace?: boolean;
+    }) => void;
+}
+export declare const HostNavigationContext: React.Context<HostNavigationValue>;
+export declare const HostNavigationProvider: React.FC<{
+    value: HostNavigationValue;
+    children: React.ReactNode;
+}>;
+/**
+ * Consume the host-provided in-app navigate. Answers `{}` (i.e. `navigate`
+ * undefined) when no host wired one — that is a supported state, see the module
+ * docblock.
+ */
+export declare function useHostNavigation(): HostNavigationValue;

package/dist/context/HostNavigationContext.js

@@ -0,0 +1,65 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * 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.
+ */
+/**
+ * HostNavigationContext — the host's own in-app navigate, offered to renderers.
+ *
+ * A published renderer package cannot navigate correctly on its own. Its only
+ * dependency-free option is a browser-level navigation
+ * (`window.location.assign`), which resolves a rooted path such as `/thanks`
+ * against the ORIGIN. Under a host mounted at a sub-path — the framework CLI
+ * configures one for every embedded deployment — that leaves the application
+ * entirely. This is objectui#4989 defect 4, and the same class as
+ * objectui#4190 / #4181.
+ *
+ * The host is the only party that knows its mount, so the host supplies the
+ * navigate. This context is that seam: **optional injection**, ruled by the
+ * maintainer on 2026-08-17. Two mechanisms were rejected in that ruling and are
+ * named here so they are not re-proposed:
+ *
+ *   - **router-presence sniffing** (a renderer reading React Router's context
+ *     when it happens to be there) — implicit magic, and it forces every
+ *     renderer that wants mount-awareness to import `react-router`;
+ *   - **a `react-router` peer requirement** — it imposes module resolution on
+ *     router-less consumers. Two real ones exist in this repo (`apps/site`,
+ *     `packages/plugin-view`), and a published renderer's whole property is
+ *     that it drops into ANY React application.
+ *
+ * Explicit injection keeps every renderer dependency-free and puts
+ * mount-awareness on the type face where a host can see it is missing.
+ *
+ * ## Absent is a supported state, not a degraded one
+ *
+ * The default value is an empty object, so `useHostNavigation()` outside a
+ * provider answers `{ navigate: undefined }` and never throws. A consumer reads
+ * it as "no host navigate — fall back to whatever this renderer did before",
+ * which for a router-less host is already the correct behaviour: with no
+ * router there is no basename, so origin-rooted resolution is right. The seam
+ * changes what a MOUNTED host gets, and changes nothing else.
+ *
+ * ## Relationship to the other navigation seams in this package
+ *
+ * `DrillNavigationContext.openRecordList` is a SEMANTIC navigation — "show me
+ * the records behind this aggregate" — that only the console can turn into a
+ * URL. `ActionProvider`'s `onNavigate` is the ActionRunner's handler for
+ * `type: 'navigate'` actions, reachable only through an action dispatch. This
+ * one is neither: it is the plain "go to this already-resolved in-app path"
+ * that a renderer holds a destination for and cannot perform correctly itself.
+ * All three are supplied by the same shell from the same router `navigate`.
+ */
+import { createContext, useContext } from 'react';
+export const HostNavigationContext = createContext({});
+export const HostNavigationProvider = ({ value, children }) => (_jsx(HostNavigationContext.Provider, { value: value, children: children }));
+/**
+ * Consume the host-provided in-app navigate. Answers `{}` (i.e. `navigate`
+ * undefined) when no host wired one — that is a supported state, see the module
+ * docblock.
+ */
+export function useHostNavigation() {
+    return useContext(HostNavigationContext);
+}

package/dist/context/RecordContext.d.ts

@@ -35,10 +35,6 @@ export interface RecordContextValue<TData = any, TObjectSchema = any> {
     data?: TData;
     /** Resolved object metadata schema (fields, label, etc.). */
     objectSchema?: TObjectSchema;
-    /** True while the record is fetching. */
-    loading?: boolean;
-    /** Last fetch error, if any. */
-    error?: Error | null;
     /** Re-fetch the record from the source. */
     refresh?: () => void | Promise<void>;
     /**

package/dist/context/RecordContext.js

@@ -96,8 +96,6 @@ export const RecordContextProvider = ({ children, ...value }) => {
         value.dataSource,
         value.data,
         value.objectSchema,
-        value.loading,
-        value.error,
         value.refresh,
         value.embedded,
         value.headerSystemActions,

package/dist/context/RelatedRecordActionsContext.d.ts

@@ -24,6 +24,12 @@
  * affordance. When no provider is present at all (e.g. the Studio designer, or
  * a standalone embedded renderer) the related list stays read-only, which is
  * the correct graceful fallback.
+ *
+ * Since objectui#4336 the same host also publishes its record-URL builder
+ * ({@link RelatedRecordActionsValue.recordHref} / `openRecord`) for any object
+ * 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.
  */
 import React from 'react';
 /** A child-object action surfaced in a related list's row menu. */
@@ -55,6 +61,21 @@ export interface RelatedRecordHandlers {
      * argument is needed here (增).
      */
     onCreate?: () => void;
+    /**
+     * [#4646] Offer "+ New", but GREYED — the `userActions.create.disabledWhen`
+     * verdict for the scope this toolbar sits in (the host parent record on a
+     * record page's related list).
+     *
+     * A separate channel from omitting {@link onCreate} because hidden and
+     * disabled are different answers, exactly as they are for the row Edit/Delete
+     * predicates (objectui#2614) and for the record header's (objectui#4419 /
+     * PR #4515): `visibleWhen` decides whether the affordance exists at all,
+     * `disabledWhen` decides whether the existing affordance can be pressed. The
+     * host still supplies `onCreate` in the disabled case, so the button keeps
+     * its label and tooltip and the user can see that creating is a thing this
+     * list does — just not right now.
+     */
+    createDisabled?: boolean;
     /** Open an edit form for an existing child record (改). */
     onEdit?: (recordId: string | number, record?: unknown) => void;
     /**
@@ -92,6 +113,29 @@ export interface RelatedRecordActionsValue {
      * identity.
      */
     resolve: (input: ResolveRelatedRecordActionsInput) => RelatedRecordHandlers;
+    /**
+     * The host's record-detail URL for ANY object it can route to — the SAME
+     * builder {@link RelatedRecordHandlers.onView} navigates with, published as
+     * an href so a renderer can present the destination as a real anchor
+     * (middle-click, "open in new tab", "copy link address") instead of a
+     * click-only affordance.
+     *
+     * Added for objectui#4336: a lookup value is a reference to a record of a
+     * DIFFERENT object, and the renderer that displays it (`LookupCellRenderer`,
+     * shared by the detail body and the related list's cells) has no router and
+     * no knowledge of the console's route shape. Route building stays here, in
+     * the one place that already owns it — never re-derived renderer-side.
+     *
+     * Returns `null` when the host cannot route to that object (unknown object,
+     * no app context), which consumers must render as the plain value.
+     */
+    recordHref?: (objectName: string, recordId: string | number) => string | null;
+    /**
+     * SPA-navigate to the destination {@link recordHref} addresses. Consumers
+     * call this from a plain left click on the anchor so navigation stays
+     * in-app; a modifier click is left to the browser and the href.
+     */
+    openRecord?: (objectName: string, recordId: string | number) => void;
 }
 export declare const RelatedRecordActionsProvider: React.FC<{
     value: RelatedRecordActionsValue;

package/dist/context/RelatedRecordActionsContext.js

@@ -25,6 +25,12 @@ import { jsx as _jsx } from "react/jsx-runtime";
  * affordance. When no provider is present at all (e.g. the Studio designer, or
  * a standalone embedded renderer) the related list stays read-only, which is
  * the correct graceful fallback.
+ *
+ * Since objectui#4336 the same host also publishes its record-URL builder
+ * ({@link RelatedRecordActionsValue.recordHref} / `openRecord`) for any object
+ * 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.
  */
 import { createContext, useContext } from 'react';
 const RelatedRecordActionsContext = createContext(null);

package/dist/context/index.d.ts

@@ -1,12 +1,13 @@
-export * from './SchemaRendererContext';
-export * from './PreviewModeContext';
-export * from './ActionContext';
-export * from './ThemeContext';
-export * from './NotificationContext';
-export * from './DndContext';
-export * from './AppShellContext';
-export * from './RecordContext';
-export * from './InlineEditContext';
-export * from './DiscussionContext';
-export * from './DrillNavigationContext';
-export * from './RelatedRecordActionsContext';
+export * from './SchemaRendererContext.js';
+export * from './PreviewModeContext.js';
+export * from './ActionContext.js';
+export * from './ThemeContext.js';
+export * from './NotificationContext.js';
+export * from './DndContext.js';
+export * from './AppShellContext.js';
+export * from './RecordContext.js';
+export * from './InlineEditContext.js';
+export * from './DiscussionContext.js';
+export * from './DrillNavigationContext.js';
+export * from './HostNavigationContext.js';
+export * from './RelatedRecordActionsContext.js';

package/dist/context/index.js

@@ -1,12 +1,13 @@
-export * from './SchemaRendererContext';
-export * from './PreviewModeContext';
-export * from './ActionContext';
-export * from './ThemeContext';
-export * from './NotificationContext';
-export * from './DndContext';
-export * from './AppShellContext';
-export * from './RecordContext';
-export * from './InlineEditContext';
-export * from './DiscussionContext';
-export * from './DrillNavigationContext';
-export * from './RelatedRecordActionsContext';
+export * from './SchemaRendererContext.js';
+export * from './PreviewModeContext.js';
+export * from './ActionContext.js';
+export * from './ThemeContext.js';
+export * from './NotificationContext.js';
+export * from './DndContext.js';
+export * from './AppShellContext.js';
+export * from './RecordContext.js';
+export * from './InlineEditContext.js';
+export * from './DiscussionContext.js';
+export * from './DrillNavigationContext.js';
+export * from './HostNavigationContext.js';
+export * from './RelatedRecordActionsContext.js';

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

@@ -0,0 +1,272 @@
+/**
+ * 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.
+ *
+ * Mapping half of consuming `PageComponentSchema.dataSource` — the spec's
+ * `ElementDataSourceSchema` per-element data binding (objectstack#5576 landed
+ * the resolution; objectstack#6953 wires it to the remaining blocks).
+ *
+ * `@object-ui/core` owns the pure half (telling the binding apart from a runtime
+ * adapter, matching a view name, composing the view with the binding's own
+ * keys). {@link useElementDataSource} owns the fetch half. This module owns the
+ * LAST hop: writing the composed result onto the schema keys a given block
+ * actually reads, and rendering the two non-final states.
+ *
+ * It exists because that hop was the part every block would otherwise copy.
+ * `dataSource` is declared on EVERY page component, so eight blocks need the
+ * same precedence table (below) with only the KEY NAMES differing — which is a
+ * mapping description, not eight algorithms. A per-block copy is how the two
+ * halves drift: one block ANDs the filters and the next replaces them, and the
+ * spec's "additional filter criteria" quietly becomes two dialects.
+ *
+ * `plugin-list`'s `ListViewBlock` carried the ORIGINAL copy of the table
+ * (objectstack#5576, which predates this module) and was collapsed onto this one
+ * by objectui#4038 — on the acceptance criterion that objectstack#5576's whole
+ * suite passes against this implementation untouched, which it does. Every
+ * object-bound block now reads the rules below from here, so this is the one
+ * place a change to them belongs.
+ *
+ * ## Precedence — one table, applied everywhere
+ *
+ * Three kinds of value arrive and they do not have the same standing:
+ *
+ *  - **`dataSource.*` keys are authoritative.** The author wrote them on THIS
+ *    placement and the spec says the binding "overrides page-level object
+ *    context", so they beat the component's own same-named key.
+ *  - **View-sourced values are a baseline.** A `view` is a *reference*; a key
+ *    written on the component itself is more specific than the view it points
+ *    at, so the component's key wins over one the view supplied.
+ *  - **`filter` never overrides — it combines.** The spec describes the
+ *    binding's filter as "*Additional* filter criteria", so component filter,
+ *    view filter and binding filter all AND together through
+ *    {@link mergeFilterNodes}. A binding can only narrow what the view already
+ *    restricts, never widen it: a mistyped per-element filter cannot expose rows
+ *    the saved view excluded.
+ *
+ * An authored-but-EMPTY `columns` counts as "not authored": `[]` is what the
+ * designer emits for an unconfigured column list, and supplying the columns is
+ * exactly why a view was named.
+ *
+ * ## What a mapping may NOT do
+ *
+ * {@link ElementDataSourceMapping} names only keys the target block genuinely
+ * reads. Writing a composed key onto a schema key the block ignores would
+ * reproduce the very defect this wiring removes — a value accepted and dropped —
+ * one layer further in, where it is even harder to see. A block with no row cap
+ * therefore leaves `limit` unmapped rather than parking it somewhere plausible,
+ * and the gap is recorded at the call site instead of being papered over here.
+ *
+ * ## A block with no ADAPTER fails loudly too (objectui#5378)
+ *
+ * The section below is about an unresolvable view NAME. The coarser failure —
+ * no runtime adapter reached the block at all — used to render an empty shell
+ * in exactly the same silence, and that is what `requiresDataSource` +
+ * {@link NoDataSourcePanel} now report. Measured on the published
+ * getting-started guide: all five of its blocks resolved no adapter, fetched
+ * nothing, and said nothing. The two panels are deliberately the same shape;
+ * they answer "which view?" and "which data source?", and an author who sees
+ * either one is being told where to look.
+ *
+ * ## An unresolvable `view` fails loudly
+ *
+ * When the named view does not exist the gate renders a configuration error
+ * instead of letting the block fall back to the object's default scope. Silently
+ * widening a named view to "all records" is the failure class the binding exists
+ * to remove, and it is the one an AI-authored page hides best: the page looks
+ * like it works.
+ */
+import * as React from 'react';
+import { type ElementDataSourceConfig } from '@object-ui/core';
+import { type ElementDataSourceStatus } from '../hooks/useElementDataSource.js';
+/**
+ * Where a block's row cap lives. Three spellings are real in this repo and each
+ * is the ONLY one its block reads: `list-view`/`object-grid` read
+ * `pagination.pageSize` (falling back to a flat `pageSize`), and
+ * `record:related_list` reads the spec's flat `limit`.
+ */
+export type ElementDataSourceLimitKey = 'limit' | 'pageSize' | 'pagination.pageSize';
+/**
+ * Which schema keys a block reads, so the composed binding lands on those and
+ * nothing else.
+ *
+ * Every field is opt-IN. The default mapping writes only the object name,
+ * because that is the one key every object-bound block in this repo reads; a
+ * block that also reads a filter, a sort, a column list or a row cap says so
+ * here, naming the key it reads.
+ */
+export interface ElementDataSourceMapping {
+    /**
+     * Schema key the binding's `object` lands on — `'objectName'` for every
+     * object-bound block in this repo, which is the default. `false` maps nothing
+     * (for a block that reads the composed object itself, like
+     * `element:record_picker`, whose object lives under `properties`).
+     */
+    object?: string | false;
+    /**
+     * Set when the block renders a FIELD column list a saved view can supply.
+     * Leave unset for a block whose `columns` mean something else — an
+     * `object-kanban`'s `columns` are its swimlane groups, not fields, and a
+     * view's field list written there would render a broken board.
+     */
+    columns?: boolean;
+    /** Set when the block reads `schema.filter` as its query filter. */
+    filter?: boolean;
+    /** Set when the block reads `schema.sort` as its query ordering. */
+    sort?: boolean;
+    /** The key a row cap lands on; omit for a block that enforces no cap. */
+    limit?: ElementDataSourceLimitKey;
+    /**
+     * Set when the block renders several view kinds off `schema.viewType`
+     * (`list-view` is the only such container: its registry `inputs` enumerate
+     * grid/kanban/gallery/…, so naming a saved kanban view and rendering a grid
+     * would be a silently wrong answer).
+     */
+    viewType?: boolean;
+}
+export interface UseElementDataSourceSchemaResult<S> {
+    /** Resolution state; see {@link ElementDataSourceStatus}. */
+    status: ElementDataSourceStatus;
+    /**
+     * The schema with the composed binding applied. Returned by REFERENCE when
+     * there is nothing to apply, so a block that carries no binding never sees a
+     * new schema identity (which would remount it and refetch on every render).
+     */
+    schema: S;
+    /** The binding as authored, or `undefined` when the node carries none. */
+    config?: ElementDataSourceConfig;
+    /** Author-facing explanation, set only for `missing`. */
+    error?: string;
+}
+/**
+ * Resolve a block's `dataSource` binding and apply it to the block's own schema
+ * keys, per {@link ElementDataSourceMapping}.
+ *
+ * @param schema     The block's schema node (its `dataSource` is read).
+ * @param mapping    Which schema keys this block reads.
+ * @param dataSource Explicit adapter; falls back to `SchemaRendererContext`.
+ *
+ * @example
+ * ```tsx
+ * const bound = useElementDataSourceSchema(schema, { filter: true, sort: true });
+ * if (bound.status === 'missing') return <ElementDataSourceErrorPanel message={bound.error} />;
+ * return <ObjectCalendar schema={bound.schema} />;
+ * ```
+ */
+export declare function useElementDataSourceSchema<S>(schema: S, mapping?: ElementDataSourceMapping, dataSource?: unknown): UseElementDataSourceSchemaResult<S>;
+export interface ElementDataSourceStatusPanelProps {
+    /**
+     * `data-testid` stem, normally the block's registry key — the panels append
+     * `-datasource-error` / `-resolving-view`, so a test names the block it is
+     * asserting about rather than a shared anonymous id.
+     */
+    testId: string;
+    /** Panel heading; defaults to a block-neutral sentence. */
+    title?: string;
+    /** The author-facing explanation from {@link useElementDataSourceSchema}. */
+    message?: string;
+}
+/**
+ * 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 declare function ElementDataSourceErrorPanel({ testId, title, message, }: ElementDataSourceStatusPanelProps): React.ReactElement;
+/**
+ * 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.
+ */
+export declare function ElementDataSourceLoadingPanel({ testId, }: Pick<ElementDataSourceStatusPanelProps, 'testId'>): React.ReactElement;
+/**
+ * The adapter this block would use, resolved the one way every block in the
+ * family resolves it: an explicit value first, the `SchemaRendererProvider`
+ * context second.
+ *
+ * The `isElementDataSourceConfig` guard is the same one
+ * {@link useElementDataSourceSchema} applies — a host handing us the spec
+ * BINDING under this name is handing us metadata, not an adapter, and counting
+ * it as one is how "no data source" reads as "resolved".
+ *
+ * `T` is what the CALLER expects to have been injected, and the assertion is
+ * the caller's, not this hook's: an adapter arrives here as a `dataSource` prop
+ * or a context value that nothing in this package can narrow, so the type has
+ * to be declared by whoever knows which interface their block consumes. Leave
+ * it off and you get `unknown`, which is the honest default.
+ */
+export declare function useResolvedDataSource<T = unknown>(explicit?: unknown): T | undefined;
+/**
+ * The author-facing sentence a block with no adapter says out loud.
+ *
+ * One wording for the whole object-bound family, because the reader's mistake
+ * is the same one every time and the fix is the same one every time: the
+ * adapter is injected by an ANCESTOR (`SchemaRendererProvider`), so nothing
+ * written on the block itself can supply it. Naming the block and the object
+ * it was about to read is what turns "nothing happened" into an address.
+ */
+export declare function noDataSourceMessage(blockKey: string, objectName?: unknown): string;
+/**
+ * The "this block resolved no adapter" panel — objectui#5378 item 2, and the
+ * #5349 shape it belongs to.
+ *
+ * Until this existed, a block that resolved no adapter rendered an EMPTY SHELL:
+ * `object-grid` painted a header-only table, `object-form` a field-less card,
+ * `detail-view` nothing at all — no error, no warning, no empty state that
+ * explained itself. Measured on the published getting-started guide
+ * (`content/docs/guide/building-crud-app.md`), every one of its five blocks was
+ * in that state and the page reported success while fetching nothing.
+ *
+ * The empty shell is the defect, not a side effect of it: it is indistinguishable
+ * from "the query ran and matched no rows", which is the reading an author (very
+ * often an AI author) takes, and it points at the DATA when the fault is in the
+ * 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 declare function NoDataSourcePanel({ testId, title, message, }: ElementDataSourceStatusPanelProps): React.ReactElement;
+export interface ElementDataSourceGateProps<S> {
+    /** The block's schema node. */
+    schema: S;
+    /** Which schema keys this block reads; see {@link ElementDataSourceMapping}. */
+    mapping?: ElementDataSourceMapping;
+    /** Explicit adapter; falls back to `SchemaRendererContext`. */
+    dataSource?: unknown;
+    /** `data-testid` stem for the two status panels — the block's registry key. */
+    testId: string;
+    /** Heading for the unresolvable-view panel. */
+    errorTitle?: string;
+    /**
+     * Whether THIS placement cannot do its job without a runtime adapter — when
+     * true and none resolves, the gate renders {@link NoDataSourcePanel} instead
+     * of the block (objectui#5378 item 2).
+     *
+     * The gate cannot compute this and does not try. "Needs an adapter" is a
+     * statement about the block's own fallbacks, and every block in the family
+     * has different ones: an `object-grid` carrying inline `data` rows needs no
+     * adapter, an `object-form` with inline `customFields` needs none, a
+     * `detail-view` handed a `data` record needs none. A predicate guessed HERE
+     * would paint a configuration error over a block that is working, which is a
+     * worse failure than the silence this replaces — so the call site, which
+     * knows its own fallbacks, states it.
+     */
+    requiresDataSource?: boolean;
+    /** Explanation for the no-adapter panel; see {@link noDataSourceMessage}. */
+    noDataSourceMessage?: string;
+    /**
+     * 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
+     * block's hooks belong to the block.
+     */
+    children: (schema: S) => React.ReactElement | null;
+}
+/**
+ * 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,
+ * for every block.
+ *
+ * The block itself is not mounted while a named view is unresolved: rendering it
+ * 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;