@object-ui/react 17.7.0 → 18.0.0

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

@@ -0,0 +1,198 @@
+/**
+ * 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 { useContext, useEffect, useMemo, useState } from 'react';
+import { ElementApiDataSourceSchema } from '@objectstack/spec/ui';
+import { SchemaRendererContext } from '../context/SchemaRendererContext.js';
+import { isConfigBag } from '../utils/configBag.js';
+/**
+ * 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 function isElementApiDataSourceShape(value) {
+    return isConfigBag(value) && value.provider === 'api';
+}
+/**
+ * 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 function judgeElementApiDataSource(value) {
+    if (!isElementApiDataSourceShape(value))
+        return { status: 'absent' };
+    const parsed = ElementApiDataSourceSchema.safeParse(value);
+    if (!parsed.success) {
+        return {
+            status: 'refused',
+            error: parsed.error.issues.map((issue) => issue.message).join(' '),
+        };
+    }
+    return { status: 'parsed', config: parsed.data };
+}
+/**
+ * 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 function selectElementApiPath(body, path) {
+    if (!path)
+        return { found: true, value: body };
+    let current = body;
+    for (const segment of path.split('.')) {
+        if (Array.isArray(current) && /^\d+$/.test(segment)) {
+            const index = Number(segment);
+            if (index >= current.length)
+                return { found: false, segment };
+            current = current[index];
+            continue;
+        }
+        if (!isConfigBag(current) || !Object.prototype.hasOwnProperty.call(current, segment)) {
+            return { found: false, segment };
+        }
+        current = current[segment];
+    }
+    return { found: true, value: current };
+}
+/** Pending reads, keyed by URL. An entry lives exactly as long as its request. */
+const IN_FLIGHT = new Map();
+/**
+ * `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 function readElementApi(url, doFetch) {
+    const pending = IN_FLIGHT.get(url);
+    if (pending)
+        return pending;
+    const request = doFetch(url, {
+        method: 'GET',
+        headers: { Accept: 'application/json' },
+        credentials: 'include',
+    })
+        .then(async (res) => {
+        if (!res.ok)
+            throw new Error(`GET ${url} answered ${res.status}.`);
+        try {
+            return await res.json();
+        }
+        catch {
+            throw new Error(`GET ${url} did not answer JSON.`);
+        }
+    })
+        .finally(() => {
+        IN_FLIGHT.delete(url);
+    });
+    IN_FLIGHT.set(url, request);
+    return request;
+}
+/**
+ * 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 function useElementApiDataSource(schema) {
+    const context = useContext(SchemaRendererContext);
+    const doFetch = context?.apiFetch ?? fetch;
+    const raw = isConfigBag(schema) ? schema.dataSource : undefined;
+    // Keyed on the binding's CONTENT, never on its identity (AGENTS.md #10): a
+    // re-render that hands over an equal binding is the same read.
+    const bindingKey = isElementApiDataSourceShape(raw) ? JSON.stringify(raw) : '';
+    const judged = useMemo(() => judgeElementApiDataSource(bindingKey ? JSON.parse(bindingKey) : undefined), [bindingKey]);
+    const url = judged.status === 'parsed' ? judged.config.read.url : '';
+    const path = judged.status === 'parsed' ? judged.config.path : undefined;
+    const requestKey = url ? JSON.stringify([url, path ?? null]) : '';
+    // The settled answer carries its own key instead of being cleared when the
+    // binding changes, so the effect never sets state synchronously; an answer
+    // whose key no longer matches reads as `loading` (useElementDataSource's rule).
+    const [settled, setSettled] = useState(null);
+    useEffect(() => {
+        if (!url)
+            return;
+        let cancelled = false;
+        readElementApi(url, doFetch).then((body) => {
+            if (cancelled)
+                return;
+            const selected = selectElementApiPath(body, path);
+            setSettled(selected.found
+                ? { key: requestKey, ok: true, data: selected.value }
+                : {
+                    key: requestKey,
+                    ok: false,
+                    error: `dataSource.path "${path}" selects nothing in the answer of GET ${url}: `
+                        + `it has no "${selected.segment}".`,
+                });
+        }, (error) => {
+            if (cancelled)
+                return;
+            setSettled({
+                key: requestKey,
+                ok: false,
+                error: error instanceof Error ? error.message : `GET ${url} failed.`,
+            });
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [url, path, requestKey, doFetch]);
+    if (judged.status === 'absent')
+        return { status: 'absent' };
+    if (judged.status === 'refused')
+        return { status: 'refused', error: judged.error };
+    if (settled?.key !== requestKey)
+        return { status: 'loading', config: judged.config };
+    if (!settled.ok)
+        return { status: 'error', config: judged.config, error: settled.error };
+    return { status: 'ready', config: judged.config, data: settled.data };
+}

package/dist/hooks/useActionTextLocalizer.d.ts

@@ -40,7 +40,17 @@
  *   AUTHORED text. That is `useObjectLabel`'s own fallback contract; nothing
  *   here overrides it.
  * - **A nameless action is not translatable.** Without `action.name` there is
- *   no `_actions.<name>` key to look up, so the literals pass through.
+ *   no `_actions.<name>` key to look up, so the literals pass through —
+ *   collapsed to the active language like every other caller's (below), since
+ *   an inline action (`element:button`) is often nameless (objectui#12757).
+ * - **The entry is keyed on the action's own object** (objectui#11439): its
+ *   declared `objectName`, else the host object the caller draws it on — the
+ *   object `translateObject` in `@objectstack/spec` stamps on an embedded
+ *   action. Only an action with neither reads `globalActions.<name>`; a bound
+ *   action never does (see `actionSuffixes` in `@object-ui/i18n`). The
+ *   runtime-side resolvers (`useConsoleActionRuntime`, `RecordDetailView`)
+ *   already key the param / description / result-dialog copy the same way, so
+ *   one action reads one bundle node on every surface.
  * - **`confirmText` / `successMessage` are resolved only when the action
  *   DECLARES them.** A bundle must not be able to bolt a confirmation gate
  *   onto an action whose metadata never asked for one (nor a success toast).
@@ -52,13 +62,14 @@
  *   declares resolves `_actions.<name>.outcomeMessages.<outcome>`; a bundle
  *   entry for an outcome the action does not declare is never read, so a
  *   bundle cannot add copy for an answer the author never wrote one for.
- * - **`label`, `successMessage` and each `outcomeMessages` entry are reduced
- *   through `pickLocalized` first**, because each is an `I18nLabel` — a string
- *   or an inline per-locale map. The map is collapsed to the active language
+ * - **`label`, `confirmText`, `successMessage`, `errorMessage` and each
+ *   `outcomeMessages` entry are reduced through `pickLocalized` first**,
+ *   because each is an `I18nLabel` — a string or an inline per-locale map. The map is collapsed to the active language
  *   BEFORE it is offered to the bundle as the fallback, so a per-locale
  *   literal and a bundle entry cannot disagree about what "the authored text"
  *   is, and the action runner, which has no language, only ever receives a
- *   string.
+ *   string. `errorMessage` has no bundle key (the spec's action translation
+ *   declares none), so the collapse is all it gets (objectui#12757).
  * - **The success copy stays a template.** A `${result.*}` token, in a bundle
  *   entry or in the authored text, passes through this hook untouched: the
  *   action has not run yet, so there is no result to read. The runner fills
@@ -74,9 +85,11 @@ export interface ActionTextLocalizerOptions {
 }
 /**
  * Returns a copy of `action` with `label` — plus `confirmText`,
- * `successMessage` and `outcomeMessages` when the action declares them —
+ * `successMessage`, `errorMessage` and `outcomeMessages` when the action
+ * declares them —
  * resolved from the active locale's bundle, falling back to the authored
- * literals.
+ * literals. `objectName` is the host object the action is drawn on; the
+ * action's own declared `objectName` wins over it when present.
  */
 export type ActionTextLocalizer = <T extends Record<string, any>>(objectName: string | undefined, action: T, options?: ActionTextLocalizerOptions) => T;
 export declare function useActionTextLocalizer(): ActionTextLocalizer;

package/dist/hooks/useActionTextLocalizer.js

@@ -40,7 +40,17 @@
  *   AUTHORED text. That is `useObjectLabel`'s own fallback contract; nothing
  *   here overrides it.
  * - **A nameless action is not translatable.** Without `action.name` there is
- *   no `_actions.<name>` key to look up, so the literals pass through.
+ *   no `_actions.<name>` key to look up, so the literals pass through —
+ *   collapsed to the active language like every other caller's (below), since
+ *   an inline action (`element:button`) is often nameless (objectui#12757).
+ * - **The entry is keyed on the action's own object** (objectui#11439): its
+ *   declared `objectName`, else the host object the caller draws it on — the
+ *   object `translateObject` in `@objectstack/spec` stamps on an embedded
+ *   action. Only an action with neither reads `globalActions.<name>`; a bound
+ *   action never does (see `actionSuffixes` in `@object-ui/i18n`). The
+ *   runtime-side resolvers (`useConsoleActionRuntime`, `RecordDetailView`)
+ *   already key the param / description / result-dialog copy the same way, so
+ *   one action reads one bundle node on every surface.
  * - **`confirmText` / `successMessage` are resolved only when the action
  *   DECLARES them.** A bundle must not be able to bolt a confirmation gate
  *   onto an action whose metadata never asked for one (nor a success toast).
@@ -52,13 +62,14 @@
  *   declares resolves `_actions.<name>.outcomeMessages.<outcome>`; a bundle
  *   entry for an outcome the action does not declare is never read, so a
  *   bundle cannot add copy for an answer the author never wrote one for.
- * - **`label`, `successMessage` and each `outcomeMessages` entry are reduced
- *   through `pickLocalized` first**, because each is an `I18nLabel` — a string
- *   or an inline per-locale map. The map is collapsed to the active language
+ * - **`label`, `confirmText`, `successMessage`, `errorMessage` and each
+ *   `outcomeMessages` entry are reduced through `pickLocalized` first**,
+ *   because each is an `I18nLabel` — a string or an inline per-locale map. The map is collapsed to the active language
  *   BEFORE it is offered to the bundle as the fallback, so a per-locale
  *   literal and a bundle entry cannot disagree about what "the authored text"
  *   is, and the action runner, which has no language, only ever receives a
- *   string.
+ *   string. `errorMessage` has no bundle key (the spec's action translation
+ *   declares none), so the collapse is all it gets (objectui#12757).
  * - **The success copy stays a template.** A `${result.*}` token, in a bundle
  *   entry or in the authored text, passes through this hook untouched: the
  *   action has not run yet, so there is no result to read. The runner fills
@@ -68,6 +79,8 @@
 import { useMemo } from 'react';
 import { useObjectLabel, useObjectTranslation, pickLocalized } from '@object-ui/i18n';
 import { isConfigBag } from '../utils/configBag.js';
+/** The declared `I18nLabel` copy, besides `label`, that reaches the runner. */
+const DECLARED_COPY_KEYS = ['confirmText', 'successMessage', 'errorMessage'];
 export function useActionTextLocalizer() {
     const { actionLabel, actionConfirm, actionSuccess, actionOutcome } = useObjectLabel();
     const { language } = useObjectTranslation();
@@ -82,21 +95,39 @@ export function useActionTextLocalizer() {
                 ? action.name
                 : undefined;
             const displayLabel = authoredLabel || name || options?.fallbackLabel || '';
-            // No name, no translation key: the literals are the answer. The label is
+            // Every declared `I18nLabel` copy collapses the same way, so neither the
+            // bundle fallbacks below nor the nameless return hand the runner a map.
+            const collapsed = { ...action, label: displayLabel };
+            let changed = displayLabel !== action.label;
+            for (const key of DECLARED_COPY_KEYS) {
+                const declaredCopy = action[key];
+                if (declaredCopy === undefined)
+                    continue;
+                collapsed[key] = pickLocalized(declaredCopy, language);
+                if (collapsed[key] !== declaredCopy)
+                    changed = true;
+            }
+            // No name, no translation key: the literals are the answer. They are
             // still normalized (map to string, last-resort placeholder applied) so
             // every caller reads one shape.
             if (!name) {
-                return displayLabel === action.label ? action : { ...action, label: displayLabel };
+                return (changed ? collapsed : action);
             }
+            // The key object: the action's declared `objectName`, else the host the
+            // caller passes (objectui#11439). An action declared on `sales_order`
+            // drawn where the caller knows no object still reads `sales_order`'s
+            // `_actions` node, never `globalActions`.
+            const declared = action.objectName;
+            const keyObject = (typeof declared === 'string' && declared) || objectName;
             const out = {
-                ...action,
-                label: actionLabel(objectName, name, displayLabel),
+                ...collapsed,
+                label: actionLabel(keyObject, name, displayLabel),
             };
             if (action.confirmText !== undefined) {
-                out.confirmText = actionConfirm(objectName, name, action.confirmText);
+                out.confirmText = actionConfirm(keyObject, name, collapsed.confirmText);
             }
             if (action.successMessage !== undefined) {
-                out.successMessage = actionSuccess(objectName, name, pickLocalized(action.successMessage, language));
+                out.successMessage = actionSuccess(keyObject, name, collapsed.successMessage);
             }
             // The map is an authored bag (outcome → copy), so the one "is this a
             // real bag?" predicate in this package answers whether to read it.
@@ -104,7 +135,7 @@ export function useActionTextLocalizer() {
             if (isConfigBag(authoredOutcomes)) {
                 const outcomeMessages = {};
                 for (const [outcome, copy] of Object.entries(authoredOutcomes)) {
-                    const text = actionOutcome(objectName, name, outcome, pickLocalized(copy, language));
+                    const text = actionOutcome(keyObject, name, outcome, pickLocalized(copy, language));
                     if (text !== undefined)
                         outcomeMessages[outcome] = text;
                 }

package/dist/hooks/useConfigBagEvaluator.d.ts

@@ -9,10 +9,11 @@
  * The `properties` evaluation of the `SchemaRenderer` memo, for a node that is
  * rendered WITHOUT `SchemaRenderer` (objectui#10290).
  *
- * The action containers (`action:bar`, `action:group`, `action:menu` in
- * `@object-ui/components`) draw their member actions themselves, so a member's
- * `properties` never passes through the memo. Its static execution values ride
- * `properties.params` (objectui#10289), and those values are templates
+ * `action:bar` (in `@object-ui/components`) mounts its member actions itself,
+ * so a member's `properties` never passes through the memo. Its static
+ * execution values ride `properties.params` (objectui#10289; an `action:group`
+ * / `action:menu` member carries no `properties` bag and its container reads
+ * none, objectui#11638), and those values are templates
  * evaluated where `properties` are (objectui#7867). This hook is that
  * evaluation: the memo's per-key rule, its `ExpressionEvaluator`, and its
  * scope (the host's ambient roots, `current_user`, the page's bound row as

package/dist/hooks/useConfigBagEvaluator.js

@@ -13,10 +13,11 @@ import { usePageVariables } from './usePageVariables.js';
  * The `properties` evaluation of the `SchemaRenderer` memo, for a node that is
  * rendered WITHOUT `SchemaRenderer` (objectui#10290).
  *
- * The action containers (`action:bar`, `action:group`, `action:menu` in
- * `@object-ui/components`) draw their member actions themselves, so a member's
- * `properties` never passes through the memo. Its static execution values ride
- * `properties.params` (objectui#10289), and those values are templates
+ * `action:bar` (in `@object-ui/components`) mounts its member actions itself,
+ * so a member's `properties` never passes through the memo. Its static
+ * execution values ride `properties.params` (objectui#10289; an `action:group`
+ * / `action:menu` member carries no `properties` bag and its container reads
+ * none, objectui#11638), and those values are templates
  * evaluated where `properties` are (objectui#7867). This hook is that
  * evaluation: the memo's per-key rule, its `ExpressionEvaluator`, and its
  * scope (the host's ambient roots, `current_user`, the page's bound row as

package/dist/hooks/useDatasetDimensionLabels.js

@@ -77,7 +77,12 @@ import { SchemaRendererContext } from '../context/SchemaRendererContext.js';
 export function useDatasetDimensionMeta(object, dimensionFields, dimensions, options) {
     // The host's AUTHENTICATED fetch (objectui#4121) — see property 1 in the
     // file header for why it is read off the context directly.
-    const apiFetch = useContext(SchemaRendererContext)?.apiFetch;
+    const context = useContext(SchemaRendererContext);
+    const apiFetch = context?.apiFetch;
+    // The host data source, when it can answer `getObjectSchema` (objectui#13039):
+    // the data layer's shared request-key cache, so N dataset widgets over one
+    // object make ONE `meta/object/NAME` request instead of one each.
+    const dataSource = context?.dataSource;
     const enabled = options?.enabled ?? true;
     // LOCALE-FREE state (objectui#4030) — see property 2 in the file header.
     const [meta, setMeta] = useState(null);
@@ -103,14 +108,22 @@ export function useDatasetDimensionMeta(object, dimensionFields, dimensions, opt
         (async () => {
             try {
                 const doFetch = apiFetch ?? fetch;
-                const loadObjectSchema = async (name) => {
-                    const r = await doFetch(`/api/v1/meta/object/${encodeURIComponent(name)}`, {
-                        headers: { accept: 'application/json' },
-                        credentials: 'include',
-                    });
-                    const doc = await r.json().catch(() => null);
-                    return doc?.item ?? doc?.data ?? doc;
-                };
+                // objectui#13039 — through the data source's `getObjectSchema` when one
+                // that answers it is in scope: the read the dashboard's chart, metric
+                // and table widgets make, which the adapter's metadata cache joins while
+                // it is in flight. It answers the bare object document, which is what
+                // the raw leg's unwrap yields, so core gets one shape from either leg.
+                // The raw read stays as the fallback for a surface with no such source.
+                const loadObjectSchema = typeof dataSource?.getObjectSchema === 'function'
+                    ? (name) => dataSource.getObjectSchema(name)
+                    : async (name) => {
+                        const r = await doFetch(`/api/v1/meta/object/${encodeURIComponent(name)}`, {
+                            headers: { accept: 'application/json' },
+                            credentials: 'include',
+                        });
+                        const doc = await r.json().catch(() => null);
+                        return doc?.item ?? doc?.data ?? doc;
+                    };
                 // ONE walk for every dimension, memoized per call inside core — sibling
                 // dimensions sharing a relationship prefix read that object once, and
                 // the base object is seeded so it is never re-read.
@@ -133,8 +146,10 @@ export function useDatasetDimensionMeta(object, dimensionFields, dimensions, opt
         // (objectui#4030 / PR #4324). `apiFetch` comes from the provider's
         // memoized context value, and this hook's own `setState` cannot re-render
         // the provider, so its identity is stable across the effect's own updates.
+        // `dataSource` joins for the same reason and from the same value
+        // (objectui#13039): it decides which leg the read takes.
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [signature, apiFetch]);
+    }, [signature, apiFetch, dataSource]);
     return meta;
 }
 /**

package/dist/hooks/useDensityMode.d.ts

@@ -53,9 +53,11 @@ export interface DensityResult {
  * import { DENSITY_MODE_TO_ROW_HEIGHT, rowHeightToDensityMode } from '@object-ui/core';
  *
  * // A view stores the protocol's `rowHeight`; the legacy `densityMode` key is
- * // retired on `NamedListView` (objectui#7924), so persist the spec value.
+ * // retired on `NamedListView` (objectui#7924), so persist the spec value —
+ * // here into the host's own per-user store (`saveUserRowHeight` is the
+ * // host's; the console keeps the choice on the user's own list state).
  * const density = useDensityMode(rowHeightToDensityMode(activeView?.rowHeight) ?? 'comfortable', {
- *   onChange: (m) => dataSource.updateViewConfig(obj, vid, { rowHeight: DENSITY_MODE_TO_ROW_HEIGHT[m] }),
+ *   onChange: (m) => saveUserRowHeight(vid, DENSITY_MODE_TO_ROW_HEIGHT[m]),
  * });
  * ```
  */

package/dist/hooks/useDensityMode.js

@@ -38,9 +38,11 @@ const DENSITY_ORDER = ['compact', 'comfortable', 'spacious'];
  * import { DENSITY_MODE_TO_ROW_HEIGHT, rowHeightToDensityMode } from '@object-ui/core';
  *
  * // A view stores the protocol's `rowHeight`; the legacy `densityMode` key is
- * // retired on `NamedListView` (objectui#7924), so persist the spec value.
+ * // retired on `NamedListView` (objectui#7924), so persist the spec value —
+ * // here into the host's own per-user store (`saveUserRowHeight` is the
+ * // host's; the console keeps the choice on the user's own list state).
  * const density = useDensityMode(rowHeightToDensityMode(activeView?.rowHeight) ?? 'comfortable', {
- *   onChange: (m) => dataSource.updateViewConfig(obj, vid, { rowHeight: DENSITY_MODE_TO_ROW_HEIGHT[m] }),
+ *   onChange: (m) => saveUserRowHeight(vid, DENSITY_MODE_TO_ROW_HEIGHT[m]),
  * });
  * ```
  */

package/dist/hooks/usePageAssignment.d.ts

@@ -6,9 +6,10 @@
  * LICENSE file in the root directory of this source tree.
  *
  * `usePageAssignment` — resolve the record PageSchema that should be rendered
- * for a given object. Walks the metadata cache exposed by `<MetadataProvider>`
- * and returns the first PageSchema whose `type === 'record'` and `object`
- * matches the requested name.
+ * for a given object. Walks the metadata cache exposed by `<MetadataProvider>`,
+ * keeps the PageSchemas whose `type === 'record'` and `object` matches the
+ * requested name, and returns the object's DEFAULT record page among them
+ * (`isDefault: true`), else the first of them.
  *
  * Returns a discriminated result by `PageSchema.kind`:
  *   - `kind === 'full'` (default): the schema fully describes the page;
@@ -18,13 +19,17 @@
  *     `buildDefaultPageSchema(objectDef, { slots })` so omitted slots
  *     fall through to synthesized defaults.
  *
- * Selection is by DECLARATION ORDER: the first matching page wins, so callers
- * can deterministically fall back to the auto-generated DetailView when no
- * record Page is authored.
+ * Selection is by the declared `PageSchema.isDefault`, then by DECLARATION
+ * ORDER among pages that are not the default: the spec allows one default
+ * record page per object, so the flag needs no tie-break here, and with no
+ * default the first matching page wins. No match returns null, so callers can
+ * deterministically fall back to the auto-generated DetailView when no record
+ * Page is authored.
  *
  * Future work (deferred): recordType / profile / app / formFactor filtering.
- * Any author-driven ordering would have to be DECLARED on `PageSchema` in
- * `@objectstack/spec` first — see the note on the selection itself below.
+ * Any further author-driven ordering would have to be DECLARED on
+ * `PageSchema` in `@objectstack/spec` first — see the note on the selection
+ * itself below.
  */
 export interface PageAssignmentOptions {
     /** Salesforce-style record type filter (reserved for future use). */
@@ -62,6 +67,24 @@ export interface PageAssignmentResult {
     /** Loader error, if any. */
     error: Error | null;
 }
+/**
+ * True when `page` is a record page bound to `objectName`: its `type` is
+ * `'record'` and its `object` names that object.
+ *
+ * This is the ONE reading of "a record page of object O" in the console. The
+ * object-based lookup below filters its candidates with it, and a route that
+ * names a page explicitly (the console's named record page route,
+ * objectui#12715) asks it before rendering the named page for a record of O,
+ * so a name that is a page of another object, or not a record page at all, is
+ * refused rather than rendered. The `pageName` override of
+ * {@link usePageAssignment} does not ask it: that option returns the page with
+ * that name whatever it is, and a caller that renders a record on the page it
+ * gets back asks this first.
+ *
+ * `type` is the one discriminator, as the lookup's own comment explains
+ * (objectui#9674): `pageType` is a key `PageSchema` refuses, so it is not read.
+ */
+export declare function isRecordPageOf(page: unknown, objectName: string | undefined | null): boolean;
 /**
  * Resolve the record PageSchema for the given object name. Returns `null`
  * when no record Page is configured, signalling the caller to fall back