@object-ui/react 17.3.0 → 17.5.0

package/README.md

@@ -121,6 +121,43 @@ function MyComponent() {
 }
 ```
 
+### useElementDataSourceSchema / ElementDataSourceGate
+
+Consume `PageComponentSchema.dataSource` — the spec's per-element data binding
+(`{ object, view?, filter?, sort?, limit? }`) — in a block that has its own key
+names. `useElementDataSource` resolves the binding (fetching the object's saved
+views so `view` can be matched); these two apply the composed result to the
+block's schema and render the two non-final states.
+
+```tsx
+import { ElementDataSourceGate } from '@object-ui/react'
+
+// `mapping` names ONLY the keys this block reads. A composed value written onto
+// a key the block ignores would be accepted and silently dropped — the defect
+// the binding exists to remove.
+const OBJECT_GRID_BINDING = {
+  columns: true,          // the view's FIELD list may fill `schema.columns`
+  filter: true,           // AND-combined, never replaced ("additional criteria")
+  sort: true,
+  limit: 'pagination.pageSize' as const,
+}
+
+const ObjectGridRenderer = ({ schema, ...props }) => (
+  <ElementDataSourceGate schema={schema} mapping={OBJECT_GRID_BINDING} testId="object-grid">
+    {(bound) => <ObjectGrid schema={bound} {...props} />}
+  </ElementDataSourceGate>
+)
+```
+
+`object` lands on `objectName` by default (pass `object: 'apiName'` for another
+key, or `object: false` for a block that reads the composed binding itself).
+Precedence: binding keys beat the component's own, view-sourced values are only a
+baseline the component's own key overrides, and `filter` AND-combines all three.
+A `view` name that does not resolve renders a configuration error rather than
+falling back to the object's full scope. Use `useElementDataSourceSchema` (plus
+the exported `ElementDataSourceErrorPanel` / `ElementDataSourceLoadingPanel`) when
+a block cannot be wrapped — a renderer whose hooks must run before the panels.
+
 ### useRegistry
 
 Access the component registry:
@@ -225,22 +262,11 @@ leaves the surface on its own anchor), `visibleNotificationStack` (`maxVisible`
 
 ## API Reference
 
-See [full documentation](https://objectui.org/api/react) for detailed API reference.
-
-<!-- release-metadata:v3.3.0 -->
-
-## Compatibility
-
-- **React:** 18.x or 19.x
-- **Node.js:** ≥ 18
-- **TypeScript:** ≥ 5.0 (strict mode)
-- **`@objectstack/spec`:** ^3.3.0
-- **`@objectstack/client`:** ^3.3.0
-- **Tailwind CSS:** ≥ 3.4 (for packages with UI)
+See [full documentation](https://objectui.org/docs/core/schema-renderer) for detailed API reference.
 
 ## Links
 
-- 📚 [Documentation](https://www.objectui.org/docs/packages/react)
+- 📚 [Documentation](https://www.objectui.org/docs/core/schema-renderer)
 - 📦 [npm package](https://www.npmjs.com/package/@object-ui/react)
 - 📝 [Changelog](./CHANGELOG.md)
 - 🐛 [Report an issue](https://github.com/objectstack-ai/objectui/issues)

package/dist/SchemaRenderer.d.ts

@@ -5,8 +5,8 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import React, { Component } from 'react';
-import { SchemaNode } from '@object-ui/core';
+import React, { Component, type ForwardRefExoticComponent, type RefAttributes } from 'react';
+import type { BaseSchema } from '@object-ui/types';
 /**
  * Per-component Error Boundary for SchemaRenderer.
  * Catches render errors in individual components, preventing one broken
@@ -30,7 +30,80 @@ export declare class SchemaErrorBoundary extends Component<{
     handleRetry: () => void;
     render(): string | number | bigint | boolean | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | null | undefined> | React.JSX.Element | null | undefined;
 }
-export declare const SchemaRenderer: React.ForwardRefExoticComponent<Omit<{
-    schema: SchemaNode;
-} & Record<string, any>, "ref"> & React.RefAttributes<any>>;
+/**
+ * The props `SchemaRenderer` DECLARES and reads itself (objectui#4548).
+ *
+ * ## Why `schema` is spelled as this union and not as a `SchemaNode`
+ *
+ * The repo carries two competing `SchemaNode` types: `@object-ui/core`'s
+ * interface (which requires `type: string`) and `@object-ui/types`' union
+ * (`BaseSchema | string | number | boolean | null | undefined`). This component
+ * matched NEITHER. It declared core's — narrower than what it accepts, so every
+ * caller holding the types union was wrong and could not be told — while its
+ * runtime returns early for strings and nullish, which core's interface forbids.
+ * The erasure below hid the mismatch completely: with props collapsed to an
+ * index signature, `schema` resolved to `any` and no call site was ever checked.
+ *
+ * So the contract is STATED HERE, by this component, as what it actually
+ * handles: an object schema, a bare string (rendered as text), or nothing at
+ * all. `number` / `boolean` are deliberately excluded — the runtime tolerates
+ * them defensively (see the primitive guard in the evaluation memo) but no
+ * author should be invited to pass them. Reconciling the two repo-wide
+ * `SchemaNode` spellings is a separate concern and deliberately not done here.
+ */
+export interface SchemaRendererProps {
+    schema: BaseSchema | string | null | undefined;
+}
+/**
+ * The open forwarding surface, named once so it reads as the decision it is.
+ *
+ * `SchemaRenderer` passes every prop it does not itself read straight through to
+ * the component the schema names, which is resolved at RUNTIME from a
+ * plugin-extensible registry — so the set of valid keys is not knowable here,
+ * and `packages/react/README.md` documents callers relying on it. The `any` is
+ * the point: this is a pass-through channel, not a typed prop.
+ */
+type ForwardedProps = Record<string, any>;
+/**
+ * The renderer loop.
+ *
+ * ## The explicit type annotation is the contract, and it is deliberate
+ *
+ * `forwardRef< T, P >` routes `P` through React's `PropsWithoutRef`:
+ *
+ *     Props extends any ? ('ref' extends keyof Props ? Omit< Props, 'ref' > : Props) : Props
+ *
+ * A string index signature on `P` puts `string` into `keyof Props`, so
+ * `'ref' extends keyof Props` is ALWAYS true, the `Omit` branch always runs, and
+ * `Omit` over a type carrying a string index signature keeps ONLY the index
+ * signature. Every declared prop is erased — on both sides. This component used
+ * to hand `forwardRef` a props type of `{ schema: SchemaNode } & Record< string,
+ * any >`, so its own `schema` resolved to `any` at every one of the ~376 call
+ * sites in this repo, and was not even REQUIRED: `< SchemaRenderer / >` with no
+ * schema at all type-checked (objectui#4548, measured).
+ *
+ * The fix is NOT to close the surface. This is the renderer loop: it forwards
+ * every prop it does not read to the component the schema names, resolved at
+ * RUNTIME from a plugin-extensible `ComponentRegistry`. That forwarding is a
+ * documented, load-bearing feature — `packages/react/README.md` shows
+ * `< SchemaRenderer schema={formSchema} onSubmit={handleSubmit} / >`, and
+ * `@object-ui/components`' form renderer consumes that `onSubmit` as a React
+ * prop. A closed props type would state a FALSE contract and would force every
+ * leaf plugin's props into this package to stay usable.
+ *
+ * So the two halves are separated deliberately:
+ *
+ *   * the `forwardRef` TYPE ARGUMENT is the honest `SchemaRendererProps`, with
+ *     no index signature — nothing for `PropsWithoutRef` to collapse, so
+ *     `schema` survives to the call site typed and required; and
+ *   * the open forwarding surface is stated ONCE, here, in this export
+ *     annotation. Because the annotation is applied to the already-built
+ *     component, `PropsWithoutRef` never runs over it, so `Record< string, any >`
+ *     widens the surface WITHOUT erasing anything.
+ *
+ * The repo-wide guard (`scripts/__tests__/forwardref-props-erasure.guard.test.ts`)
+ * judges the TYPE ARGUMENT only, for exactly this reason: an index signature
+ * there is an accidental eraser, whereas one here is a stated contract.
+ */
+export declare const SchemaRenderer: ForwardRefExoticComponent<SchemaRendererProps & ForwardedProps & RefAttributes<unknown>>;
 export {};

package/dist/SchemaRenderer.js

@@ -7,11 +7,11 @@ import { jsxs as _jsxs, jsx as _jsx, Fragment as _Fragment } from "react/jsx-run
  * LICENSE file in the root directory of this source tree.
  */
 import React, { forwardRef, useContext, useMemo, useEffect, useReducer, useState, Component } from 'react';
-import { ComponentRegistry, ExpressionEvaluator, isObjectUIError, ERROR_CODES, debugLog, debugTime, debugTimeEnd, DebugCollector, validateSchema, hasResponsiveStyles, scopeClassFor, compileScopedStyles, } from '@object-ui/core';
+import { ComponentRegistry, ExpressionEvaluator, isObjectUIError, ERROR_CODES, debugLog, debugTime, debugTimeEnd, DebugCollector, validateSchema, hasDeclaredPredicate, hasResponsiveStyles, scopeClassFor, compileScopedStyles, } from '@object-ui/core';
 import { SchemaRendererContext } from './context/SchemaRendererContext';
 import { usePredicateScope } from './hooks/useExpression';
 import { usePageVariables } from './hooks/usePageVariables';
-import { resolveI18nLabel } from './utils/i18n';
+import { resolveKeyedI18nLabel } from './utils/i18n';
 /**
  * Dev-mode schema validation.
  *
@@ -84,7 +84,7 @@ function validateSchemaOnce(schema) {
 function resolveAriaProps(schema) {
     const aria = {};
     if (schema.ariaLabel) {
-        aria['aria-label'] = resolveI18nLabel(schema.ariaLabel);
+        aria['aria-label'] = resolveKeyedI18nLabel(schema.ariaLabel);
     }
     if (schema.ariaDescribedBy) {
         aria['aria-describedby'] = schema.ariaDescribedBy;
@@ -131,7 +131,7 @@ export class SchemaErrorBoundary extends Component {
             const error = this.state.error;
             const isDev = globalThis.process?.env?.NODE_ENV !== 'production';
             const objuiError = isObjectUIError(error) ? error : null;
-            return (_jsxs("div", { className: "p-4 border border-orange-400 rounded bg-orange-50 text-orange-700 my-2", role: "alert", children: [_jsxs("p", { className: "font-medium", children: ["Component", this.props.componentType ? ` "${this.props.componentType}"` : '', " failed to render"] }), _jsx("p", { className: "text-sm mt-1", children: error.message }), isDev && objuiError?.code && (_jsxs("p", { className: "text-xs mt-1 text-orange-500", children: ["Error code: ", objuiError.code, objuiError.details?.suggestion ? (_jsxs("span", { className: "block mt-0.5", children: ["\uD83D\uDCA1 ", String(objuiError.details.suggestion)] })) : null] })), _jsx("button", { onClick: this.handleRetry, className: "mt-2 text-sm underline hover:no-underline", children: "Retry" })] }));
+            return (_jsxs("div", { className: "p-4 border border-orange-400 rounded bg-orange-50 text-orange-700 my-2", role: "alert", children: [_jsxs("p", { className: "font-medium", children: ["Component", this.props.componentType ? ` "${this.props.componentType}"` : '', " failed to render"] }), _jsx("p", { className: "text-sm mt-1", children: error.message }), isDev && objuiError?.code && (_jsxs("p", { className: "text-xs mt-1 text-orange-500", children: ["Error code: ", objuiError.code, objuiError.details?.suggestion ? (_jsxs("span", { className: "block mt-0.5", children: ["\uD83D\uDCA1 ", String(objuiError.details.suggestion)] })) : null] })), _jsx("button", { type: "button", onClick: this.handleRetry, className: "mt-2 text-sm underline hover:no-underline", children: "Retry" })] }));
         }
         return this.props.children;
     }
@@ -146,6 +146,47 @@ export class SchemaErrorBoundary extends Component {
  * `useState` wiped (objectui#2954's latent hazard, made real by this line).
  */
 const NO_DATA_SOURCE = {};
+/**
+ * The renderer loop.
+ *
+ * ## The explicit type annotation is the contract, and it is deliberate
+ *
+ * `forwardRef< T, P >` routes `P` through React's `PropsWithoutRef`:
+ *
+ *     Props extends any ? ('ref' extends keyof Props ? Omit< Props, 'ref' > : Props) : Props
+ *
+ * A string index signature on `P` puts `string` into `keyof Props`, so
+ * `'ref' extends keyof Props` is ALWAYS true, the `Omit` branch always runs, and
+ * `Omit` over a type carrying a string index signature keeps ONLY the index
+ * signature. Every declared prop is erased — on both sides. This component used
+ * to hand `forwardRef` a props type of `{ schema: SchemaNode } & Record< string,
+ * any >`, so its own `schema` resolved to `any` at every one of the ~376 call
+ * sites in this repo, and was not even REQUIRED: `< SchemaRenderer / >` with no
+ * schema at all type-checked (objectui#4548, measured).
+ *
+ * The fix is NOT to close the surface. This is the renderer loop: it forwards
+ * every prop it does not read to the component the schema names, resolved at
+ * RUNTIME from a plugin-extensible `ComponentRegistry`. That forwarding is a
+ * documented, load-bearing feature — `packages/react/README.md` shows
+ * `< SchemaRenderer schema={formSchema} onSubmit={handleSubmit} / >`, and
+ * `@object-ui/components`' form renderer consumes that `onSubmit` as a React
+ * prop. A closed props type would state a FALSE contract and would force every
+ * leaf plugin's props into this package to stay usable.
+ *
+ * So the two halves are separated deliberately:
+ *
+ *   * the `forwardRef` TYPE ARGUMENT is the honest `SchemaRendererProps`, with
+ *     no index signature — nothing for `PropsWithoutRef` to collapse, so
+ *     `schema` survives to the call site typed and required; and
+ *   * the open forwarding surface is stated ONCE, here, in this export
+ *     annotation. Because the annotation is applied to the already-built
+ *     component, `PropsWithoutRef` never runs over it, so `Record< string, any >`
+ *     widens the surface WITHOUT erasing anything.
+ *
+ * The repo-wide guard (`scripts/__tests__/forwardref-props-erasure.guard.test.ts`)
+ * judges the TYPE ARGUMENT only, for exactly this reason: an index signature
+ * there is an accidental eraser, whereas one here is a stated contract.
+ */
 export const SchemaRenderer = forwardRef(({ schema, ...props }, _ref) => {
     const context = useContext(SchemaRendererContext);
     const dataSource = context?.dataSource || NO_DATA_SOURCE;
@@ -176,7 +217,19 @@ export const SchemaRenderer = forwardRef(({ schema, ...props }, _ref) => {
     const autoStyleId = React.useId();
     // Evaluate schema expressions against the data source
     const evaluatedSchema = useMemo(() => {
-        if (!schema || typeof schema === 'string')
+        // Nothing to evaluate unless the node is an OBJECT. `!schema` covers the
+        // nullish/empty cases and `typeof !== 'object'` covers every primitive —
+        // both return the value untouched for the render pass below to place.
+        //
+        // The `typeof` half is what used to be missing (objectui#4548): the guard
+        // named `string` only, so a `number` or `true` fell through to the
+        // `{ ...schema }` shallow copy on the next line, spread to an EMPTY object,
+        // lost its `type`, and surfaced as the red "Unknown component type:
+        // undefined" box — an accident of the spread, not a decision. The declared
+        // props type now excludes those primitives outright; this guard is the
+        // defence-in-depth behind it, and it is what makes the copy below provably
+        // an object spread.
+        if (!schema || typeof schema !== 'object')
             return schema;
         // `data` (record/datasource) plus the ambient host scope. `current_user`
         // is aliased to `user` so both `user.email` and `current_user.email`
@@ -248,10 +301,28 @@ export const SchemaRenderer = forwardRef(({ schema, ...props }, _ref) => {
             if (newSchema.visibility !== undefined) {
                 return !evaluator.evaluateCondition(newSchema.visibility);
             }
-            if (newSchema.hidden !== undefined) {
+            // Ask "is a `hidden` gate DECLARED?" — not "is the key present?"
+            // (objectui#3955). These two legs are the only ones in this chain whose
+            // verdict is NOT negated, so the evaluator's single default for "there is
+            // nothing to evaluate" (`true`, meaning *visible/enabled*) arrives here
+            // meaning HIDE: `hidden: ''` / `null` (`null !== undefined`) / a
+            // whitespace-only string / the `{ dialect, source: '' }` envelope
+            // `objectstack build` emits for an empty predicate each made the node
+            // VANISH, on the generic path, for a value the metadata never used to say
+            // anything. Harder to diagnose than its `disabled` twin below
+            // (objectui#3862): a greyed-out control is still on screen, a node that
+            // never rendered is indistinguishable from metadata that meant it.
+            //
+            // `hasDeclaredPredicate` is the repo's one definition of "declared"
+            // (core's `evaluator/declaredPredicate.ts`) — a local `&& !== ''` here
+            // would have been the Nth dialect of one question. The verdict still reads
+            // the RAW value; only the gate in front of it narrowed. Not an
+            // equivalence, and pinned as a behaviour change: an UNDECLARED `hidden` no
+            // longer short-circuits, so a declared `hiddenOn` is finally consulted.
+            if (hasDeclaredPredicate(newSchema.hidden)) {
                 return evaluator.evaluateCondition(newSchema.hidden);
             }
-            if (newSchema.hiddenOn !== undefined) {
+            if (hasDeclaredPredicate(newSchema.hiddenOn)) {
                 return evaluator.evaluateCondition(newSchema.hiddenOn);
             }
             return false;
@@ -260,11 +331,41 @@ export const SchemaRenderer = forwardRef(({ schema, ...props }, _ref) => {
             newSchema._hidden = true;
         }
         // Evaluate disabled: disabled / disabledOn
+        //
+        // Ask "is a `disabled` gate DECLARED?" — not "is the key present?"
+        // (objectui#3862). `!== undefined` was the widest of the three spellings this
+        // question used to have, and this is the key where breadth is not free: the
+        // evaluation entry answers an empty predicate with `true`, meaning "no
+        // condition → visible/enabled", and on `disabled` that `true` means GREYED
+        // OUT. So `disabled: ''`, `disabled: null` (`null !== undefined`), a
+        // whitespace-only string and the `{ dialect, source: '' }` envelope
+        // `objectstack build` emits for an empty predicate each disabled the node —
+        // on the GENERIC path, since this block runs for every schema type, and not
+        // as an internal flag either: `_disabled` is forwarded below as a real
+        // `disabled` prop.
+        //
+        // The `visible` / `visibleWhen` / `visibleOn` / `visibility` legs above keep
+        // `!== undefined` deliberately: their `true` is NEGATED, so an empty predicate
+        // already lands on "shown", which is what "no gate" means anyway, and
+        // narrowing them would change ALIAS PRECEDENCE rather than fix anything. The
+        // `hidden` / `hiddenOn` legs were the exception — not negated, so they carried
+        // this same defect with the polarity that makes the node VANISH — and they now
+        // read this same definition (objectui#3955).
+        //
+        // `hasDeclaredPredicate` is the one definition of "declared" (core's
+        // `evaluator/declaredPredicate.ts`, objectui#3850's ruling — read there for
+        // the scope), shared with the action renderers' `hasDeclaredVisibilityGate`
+        // and `ActionRunner`'s execution gates. A local `&& !== ''` here would have
+        // been a fourth dialect of one question, which is what objectui#3842 /
+        // objectui#3849 spent two PRs merging away. The verdict still reads the RAW
+        // value, exactly as before — only the gate in front of it narrowed. An
+        // undeclared `disabled` now falls through to `disabledOn` instead of
+        // short-circuiting on an empty predicate.
         const isDisabled = (() => {
-            if (newSchema.disabled !== undefined) {
+            if (hasDeclaredPredicate(newSchema.disabled)) {
                 return evaluator.evaluateCondition(newSchema.disabled);
             }
-            if (newSchema.disabledOn !== undefined) {
+            if (hasDeclaredPredicate(newSchema.disabledOn)) {
                 return evaluator.evaluateCondition(newSchema.disabledOn);
             }
             return false;
@@ -276,12 +377,25 @@ export const SchemaRenderer = forwardRef(({ schema, ...props }, _ref) => {
     }, [schema, dataSource, predicateScope, pageVariables]);
     if (!evaluatedSchema)
         return null;
-    // Handle visibility: if evaluated schema is hidden, render nothing
-    if (evaluatedSchema?._hidden)
-        return null;
     // If schema is just a string, render it as text
     if (typeof evaluatedSchema === 'string')
         return _jsx(_Fragment, { children: evaluatedSchema });
+    // Any other primitive that reached here renders as its text too
+    // (objectui#4548). The declared props type does not admit `number` /
+    // `boolean`, so this is unreachable from typed code and exists for untyped
+    // callers and stored metadata; it replaces the empty-spread "Unknown
+    // component type: undefined" box, which said nothing true about the input.
+    if (typeof evaluatedSchema !== 'object')
+        return _jsx(_Fragment, { children: String(evaluatedSchema) });
+    // Handle visibility: if evaluated schema is hidden, render nothing.
+    //
+    // Reads AFTER the primitive narrowing above (objectui#4548) so the property
+    // access is on a known object. Behaviour is unchanged: `_hidden` is only ever
+    // set on the object copy built in the memo, so for a string or any other
+    // primitive this test was always falsy and fell through to exactly the
+    // branches that now precede it.
+    if (evaluatedSchema._hidden)
+        return null;
     // Dev-mode validation: log once per schema object, attach visual flag
     // when invalid. Production path returns { valid: true, messages: [] }
     // without doing any work.
@@ -308,7 +422,19 @@ export const SchemaRenderer = forwardRef(({ schema, ...props }, _ref) => {
     // Note: We don't forward the ref to the Component because components in the registry
     // may not support refs. The SchemaRenderer itself can still receive refs for its own use.
     // Extract schema metadata properties that should NOT be passed as React props
-    const { type: _type, children: _children, body: _body, schema: _schema, visible: _visible, visibleWhen: _visibleWhen, visibleOn: _visibleOn, visibility: _visibility, hidden: _hidden, hiddenOn: _hiddenOn, disabled: _disabled, disabledOn: _disabledOn, _hidden: __hidden, // stripped: internal visibility flag
+    const { type: _type, children: _children, body: _body, schema: _schema, visible: _visible, visibleWhen: _visibleWhen, visibleOn: _visibleOn, visibility: _visibility, hidden: _hidden, hiddenOn: _hiddenOn, disabled: _disabled, disabledOn: _disabledOn, 
+    // stripped: `PageComponentSchema.dataSource` is the spec's per-element data
+    // BINDING (`{ object, view, filter, sort, limit }`) — schema metadata, like
+    // `visibleWhen` above, not a visual prop. Renderers that consume it read
+    // `schema.dataSource` (element:record_picker, list-view); it must not be
+    // spread as a React prop, because several data-bound blocks take the
+    // injected data-source ADAPTER under that very name. Spreading it shadowed
+    // the adapter with a plain `{ object, view }` object, so the first
+    // `dataSource.find(…)` threw `dataSource.find is not a function` and the
+    // block reported "Couldn't load records" — writing the binding the spec
+    // documents BROKE the component (objectstack#5576). An explicit React
+    // `dataSource` prop is unaffected: it arrives via `...props`, spread last.
+    dataSource: _dataSource, _hidden: __hidden, // stripped: internal visibility flag
     _disabled: __disabled, // stripped: internal disabled flag
     responsiveStyles: _responsiveStyles, // stripped: compiled to scoped CSS, not a DOM prop
     ...componentProps } = evaluatedSchema;

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/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. */
@@ -92,6 +98,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);