@object-ui/react 17.3.0 → 17.5.0

package/dist/hooks/useDatasetDimensionLabels.d.ts

@@ -0,0 +1,104 @@
+/**
+ * ObjectUI — useDatasetDimensionLabels
+ * 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 analytics label net's REACT half (objectui#4389) — the fetch-and-memo
+ * glue that carries a dataset query's dimension metadata to the pure
+ * `@object-ui/core` helpers that decide what a label IS.
+ *
+ * ## What this is, and what it is not
+ *
+ * Nothing here decides a label. The resolution rules are all core's, and were
+ * never duplicated: `loadDimensionFieldMeta` → `resolveDimensionFieldMeta`, and
+ * `deriveDimensionLabelMaps` → `buildDimensionLabelMap`, with the translator
+ * bound by `dimensionOptionTranslator` to `{ns}.fieldOptions.<object>.<field>.<value>`
+ * — the one convention list and form surfaces already translate select options
+ * through. What this hook owns is only the three things core structurally
+ * cannot: the host context read, the state, and the memo boundary between them.
+ *
+ * ## Why it lives HERE
+ *
+ * objectui#4389 filed the glue as duplicated between `plugin-dashboard`'s
+ * `DatasetWidget` and `plugin-report`'s `useDatasetDimensionLabels` (both
+ * created by PR #4388), and named `@object-ui/core` as its home. That home was
+ * retired by measurement, and the card's PM RULING #2 records the correction:
+ * `SchemaRendererContext` is defined in THIS package, which depends on
+ * `@object-ui/core`, so core importing it back is a cycle; core is also
+ * React-free by declaration, by content, and by AGENTS.md §3. This package is
+ * the one place that is downstream of core (the helpers are reachable),
+ * downstream of `@object-ui/i18n` (`useSafeFieldLabel` is reachable), the owner
+ * of `SchemaRendererContext` (`apiFetch` is a local read), and upstream of both
+ * consuming plugins. It already hosts this exact fetch-and-memo-off-`apiFetch`
+ * shape three times over — `useViewData`, `useElementDataSource`, `useDiscovery`.
+ *
+ * ## The two properties this hook exists to state ONCE
+ *
+ * Both are bug fixes that were previously written out on each surface, which is
+ * the drift objectui#4389 was filed to close:
+ *
+ * 1. **The read rides the host's AUTHENTICATED `apiFetch` (objectui#4121)**, so
+ *    `apiFetch` is IN the effect's deps. A bearer-token session carries its
+ *    credential in the `Authorization` header, not a cookie, so
+ *    `credentials: 'include'` alone left this read unauthenticated in a hosted
+ *    console — and because the net is best-effort, the symptom was not an error
+ *    but option colours and dimension labels silently never applying. The
+ *    context is consulted DIRECTLY rather than through a `useSchemaContext()`
+ *    that throws, so a surface rendered outside a host keeps degrading to the
+ *    global `fetch` instead of crashing the render.
+ * 2. **The fetched metadata stays LOCALE-FREE in state (objectui#4030 /
+ *    PR #4324)**, so the locale is NOT in the effect's deps. The bundle is
+ *    applied one memo down, in {@link useDatasetDimensionLabels}, which is what
+ *    makes a language switch re-label in place instead of re-issuing the
+ *    metadata read.
+ *
+ * Both are pinned in `useDatasetDimensionLabels.test.tsx`, which asserts them
+ * at this seam — the level the per-plugin pins cannot state, since neither
+ * plugin can observe that the OTHER one inherits the same wiring.
+ */
+import { type DimensionFieldMeta, type DimensionRelabelTarget } from '@object-ui/core';
+/** `{ dimension → { rowValue → displayLabel } }`, or null when nothing resolved. */
+export type DimensionLabelMaps = Record<string, Record<string, string>> | null;
+/** What the metadata read resolved, kept locale-free (objectui#4030). */
+export interface DatasetDimensionMeta {
+    /** `{ fieldPath → { object, field, options } }` for the paths that resolved. */
+    metaByPath: Record<string, DimensionFieldMeta>;
+    /** The dimensions this surface relabels, paired with their field paths. */
+    relabel: DimensionRelabelTarget[];
+}
+/** Shared options for both hooks below. */
+export interface DatasetDimensionLabelOptions {
+    /**
+     * Set false to issue no read at all. The dashboard's METRIC branch passes
+     * this: it renders ONE measure value plus that measure's header label, so a
+     * dimension's value never reaches its output in any spelling and resolving
+     * would be a metadata read nothing consumes (objectui#4263, pinned).
+     */
+    enabled?: boolean;
+}
+/**
+ * Resolve one dataset query's dimension field metadata — the LOCALE-FREE half.
+ *
+ * Use this directly only when the surface derives more from the metadata than
+ * label maps; the dashboard does, for its chart-only per-category colours and
+ * declared category order. Everything else wants {@link useDatasetDimensionLabels}.
+ *
+ * @param object the dataset's base object, as the query result reported it
+ * @param dimensionFields the result's `dimension → field path` map (a dotted
+ *   path resolves against the relationship TARGET, ADR-0071 multi-hop included)
+ * @param dimensions the dimension names this surface renders
+ */
+export declare function useDatasetDimensionMeta(object: string | undefined, dimensionFields: Record<string, string> | undefined, dimensions: readonly string[] | undefined, options?: DatasetDimensionLabelOptions): DatasetDimensionMeta | null;
+/**
+ * Resolve the `{ dimension → { value → displayLabel } }` maps for one dataset
+ * query's dimensions, with the locale bundle applied.
+ *
+ * The full glue: {@link useDatasetDimensionMeta} for the locale-free read, then
+ * core's `deriveDimensionLabelMaps` in a render memo. Feed the result to
+ * `relabelDimensions`. A language switch re-runs only the memo.
+ *
+ * Parameters are as {@link useDatasetDimensionMeta}.
+ */
+export declare function useDatasetDimensionLabels(object: string | undefined, dimensionFields: Record<string, string> | undefined, dimensions: readonly string[] | undefined, options?: DatasetDimensionLabelOptions): DimensionLabelMaps;

package/dist/hooks/useDatasetDimensionLabels.js

@@ -0,0 +1,154 @@
+/**
+ * ObjectUI — useDatasetDimensionLabels
+ * 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 analytics label net's REACT half (objectui#4389) — the fetch-and-memo
+ * glue that carries a dataset query's dimension metadata to the pure
+ * `@object-ui/core` helpers that decide what a label IS.
+ *
+ * ## What this is, and what it is not
+ *
+ * Nothing here decides a label. The resolution rules are all core's, and were
+ * never duplicated: `loadDimensionFieldMeta` → `resolveDimensionFieldMeta`, and
+ * `deriveDimensionLabelMaps` → `buildDimensionLabelMap`, with the translator
+ * bound by `dimensionOptionTranslator` to `{ns}.fieldOptions.<object>.<field>.<value>`
+ * — the one convention list and form surfaces already translate select options
+ * through. What this hook owns is only the three things core structurally
+ * cannot: the host context read, the state, and the memo boundary between them.
+ *
+ * ## Why it lives HERE
+ *
+ * objectui#4389 filed the glue as duplicated between `plugin-dashboard`'s
+ * `DatasetWidget` and `plugin-report`'s `useDatasetDimensionLabels` (both
+ * created by PR #4388), and named `@object-ui/core` as its home. That home was
+ * retired by measurement, and the card's PM RULING #2 records the correction:
+ * `SchemaRendererContext` is defined in THIS package, which depends on
+ * `@object-ui/core`, so core importing it back is a cycle; core is also
+ * React-free by declaration, by content, and by AGENTS.md §3. This package is
+ * the one place that is downstream of core (the helpers are reachable),
+ * downstream of `@object-ui/i18n` (`useSafeFieldLabel` is reachable), the owner
+ * of `SchemaRendererContext` (`apiFetch` is a local read), and upstream of both
+ * consuming plugins. It already hosts this exact fetch-and-memo-off-`apiFetch`
+ * shape three times over — `useViewData`, `useElementDataSource`, `useDiscovery`.
+ *
+ * ## The two properties this hook exists to state ONCE
+ *
+ * Both are bug fixes that were previously written out on each surface, which is
+ * the drift objectui#4389 was filed to close:
+ *
+ * 1. **The read rides the host's AUTHENTICATED `apiFetch` (objectui#4121)**, so
+ *    `apiFetch` is IN the effect's deps. A bearer-token session carries its
+ *    credential in the `Authorization` header, not a cookie, so
+ *    `credentials: 'include'` alone left this read unauthenticated in a hosted
+ *    console — and because the net is best-effort, the symptom was not an error
+ *    but option colours and dimension labels silently never applying. The
+ *    context is consulted DIRECTLY rather than through a `useSchemaContext()`
+ *    that throws, so a surface rendered outside a host keeps degrading to the
+ *    global `fetch` instead of crashing the render.
+ * 2. **The fetched metadata stays LOCALE-FREE in state (objectui#4030 /
+ *    PR #4324)**, so the locale is NOT in the effect's deps. The bundle is
+ *    applied one memo down, in {@link useDatasetDimensionLabels}, which is what
+ *    makes a language switch re-label in place instead of re-issuing the
+ *    metadata read.
+ *
+ * Both are pinned in `useDatasetDimensionLabels.test.tsx`, which asserts them
+ * at this seam — the level the per-plugin pins cannot state, since neither
+ * plugin can observe that the OTHER one inherits the same wiring.
+ */
+import { useContext, useEffect, useMemo, useState } from 'react';
+import { deriveDimensionLabelMaps, loadDimensionFieldMeta, } from '@object-ui/core';
+import { useSafeFieldLabel } from '@object-ui/i18n';
+import { SchemaRendererContext } from '../context/SchemaRendererContext';
+/**
+ * Resolve one dataset query's dimension field metadata — the LOCALE-FREE half.
+ *
+ * Use this directly only when the surface derives more from the metadata than
+ * label maps; the dashboard does, for its chart-only per-category colours and
+ * declared category order. Everything else wants {@link useDatasetDimensionLabels}.
+ *
+ * @param object the dataset's base object, as the query result reported it
+ * @param dimensionFields the result's `dimension → field path` map (a dotted
+ *   path resolves against the relationship TARGET, ADR-0071 multi-hop included)
+ * @param dimensions the dimension names this surface renders
+ */
+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 enabled = options?.enabled ?? true;
+    // LOCALE-FREE state (objectui#4030) — see property 2 in the file header.
+    const [meta, setMeta] = useState(null);
+    const dims = (dimensions ?? []).filter(Boolean);
+    // A string signature, for the same reason `useDatasetRows` uses one: the
+    // dimension list and field map reach a renderer as arrays/objects rebuilt on
+    // every render, so keying the effect on their identity would refetch forever.
+    // NOTE what is deliberately ABSENT from it: the locale. That absence is
+    // property 2, and it is pinned.
+    const signature = [
+        enabled ? '1' : '0',
+        object ?? '',
+        dims.join(','),
+        JSON.stringify(dimensionFields ?? null),
+    ].join('|');
+    useEffect(() => {
+        if (!enabled || !object || dims.length === 0) {
+            setMeta(null);
+            return;
+        }
+        const fieldOf = (dim) => (dimensionFields && dimensionFields[dim]) || dim;
+        let cancelled = false;
+        (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;
+                };
+                // 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.
+                const metaByPath = await loadDimensionFieldMeta(loadObjectSchema, object, dims.map(fieldOf));
+                if (!cancelled) {
+                    setMeta({ metaByPath, relabel: dims.map((dim) => ({ dim, path: fieldOf(dim) })) });
+                }
+            }
+            catch {
+                // Best-effort by construction: a failed read leaves the rows exactly as
+                // the server sent them, which is what these surfaces rendered before.
+                if (!cancelled)
+                    setMeta(null);
+            }
+        })();
+        return () => {
+            cancelled = true;
+        };
+        // `apiFetch` joins the deps (objectui#4121); the locale does NOT
+        // (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.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [signature, apiFetch]);
+    return meta;
+}
+/**
+ * Resolve the `{ dimension → { value → displayLabel } }` maps for one dataset
+ * query's dimensions, with the locale bundle applied.
+ *
+ * The full glue: {@link useDatasetDimensionMeta} for the locale-free read, then
+ * core's `deriveDimensionLabelMaps` in a render memo. Feed the result to
+ * `relabelDimensions`. A language switch re-runs only the memo.
+ *
+ * Parameters are as {@link useDatasetDimensionMeta}.
+ */
+export function useDatasetDimensionLabels(object, dimensionFields, dimensions, options) {
+    const { fieldOptionLabel } = useSafeFieldLabel();
+    const meta = useDatasetDimensionMeta(object, dimensionFields, dimensions, options);
+    return useMemo(() => deriveDimensionLabelMaps(meta?.metaByPath, meta?.relabel, fieldOptionLabel), [meta, fieldOptionLabel]);
+}

package/dist/hooks/useElementDataSource.d.ts

@@ -0,0 +1,68 @@
+/**
+ * ObjectUI — useElementDataSource
+ * 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.
+ *
+ * Runtime half of consuming `PageComponentSchema.dataSource` — the spec's
+ * `ElementDataSourceSchema` per-element data binding (objectstack#5576).
+ *
+ * `@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).
+ * This hook owns the part that needs React and a data source: FETCHING the
+ * object's saved views so `view` can be resolved to real columns/filter/sort.
+ *
+ * It lives in `@object-ui/react` rather than in the one plugin that consumes it
+ * today because the binding is declared on EVERY page component: `list-view`
+ * reads it here, `element:record_picker` already reads `schema.dataSource` (and
+ * still ignores `view`), and the remaining object-bound blocks will need the same
+ * resolution. One resolver in the runtime layer, not one per plugin.
+ */
+import { type ComposedElementDataSource, type ElementDataSourceConfig, type ElementSavedView } from '@object-ui/core';
+/**
+ * Where a resolution attempt stands. Distinguishing `loading` from `missing`
+ * matters: a component that treated "not resolved yet" as "does not exist" would
+ * flash the configuration error on every mount.
+ */
+export type ElementDataSourceStatus = 
+/** The node carries no `dataSource` binding — nothing to resolve. */
+'absent'
+/** Binding present, no `view` named — composition is already final. */
+ | 'ready'
+/** A `view` was named and the saved views are still being fetched. */
+ | 'loading'
+/** The named `view` was found and composed in. */
+ | 'resolved'
+/** The named `view` does not exist on the object (or could not be read). */
+ | 'missing';
+export interface UseElementDataSourceResult {
+    status: ElementDataSourceStatus;
+    /** The binding as authored, or `undefined` when the node carries none. */
+    config?: ElementDataSourceConfig;
+    /**
+     * Binding composed with the resolved view. Present for `ready` and
+     * `resolved`; withheld for `loading` and `missing` so a caller cannot render a
+     * half-resolved query by accident.
+     */
+    composed?: ComposedElementDataSource;
+    /** The saved view that was applied, when one was. */
+    view?: ElementSavedView;
+    /** Author-facing explanation, set only for `missing`. */
+    error?: string;
+}
+/**
+ * Resolve a schema node's `dataSource` binding, fetching the named saved view.
+ *
+ * @param schema      The component's schema node (its `dataSource` is read).
+ * @param dataSource  Explicit adapter; falls back to `SchemaRendererContext`.
+ *
+ * @example
+ * ```tsx
+ * const binding = useElementDataSource(schema, adapter);
+ * if (binding.status === 'missing') return <ConfigError message={binding.error} />;
+ * if (binding.status === 'loading') return <Skeleton />;
+ * const objectName = binding.composed?.object ?? schema.objectName;
+ * ```
+ */
+export declare function useElementDataSource(schema: unknown, dataSource?: unknown): UseElementDataSourceResult;

package/dist/hooks/useElementDataSource.js

@@ -0,0 +1,138 @@
+/**
+ * ObjectUI — useElementDataSource
+ * 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.
+ *
+ * Runtime half of consuming `PageComponentSchema.dataSource` — the spec's
+ * `ElementDataSourceSchema` per-element data binding (objectstack#5576).
+ *
+ * `@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).
+ * This hook owns the part that needs React and a data source: FETCHING the
+ * object's saved views so `view` can be resolved to real columns/filter/sort.
+ *
+ * It lives in `@object-ui/react` rather than in the one plugin that consumes it
+ * today because the binding is declared on EVERY page component: `list-view`
+ * reads it here, `element:record_picker` already reads `schema.dataSource` (and
+ * still ignores `view`), and the remaining object-bound blocks will need the same
+ * resolution. One resolver in the runtime layer, not one per plugin.
+ */
+import { useContext, useEffect, useMemo, useState } from 'react';
+import { collectSavedViews, composeElementDataSource, elementDataSourceViewNotFoundMessage, isElementDataSourceConfig, resolveSavedView, } from '@object-ui/core';
+import { SchemaRendererContext } from '../context/SchemaRendererContext';
+const isRecord = (v) => !!v && typeof v === 'object';
+/**
+ * Read every saved view for `object` from the two places they live, in the same
+ * precedence app-shell's `ObjectView` uses: the object definition's embedded
+ * `listViews` / `list_views` map first, then the metadata-overlay rows
+ * `listViews()` returns — so a user-saved view shadows a metadata one of the
+ * same id.
+ *
+ * `capable` is false when there is no data source, or it exposes neither read —
+ * "this object has no view called X" and "nobody here can answer that question"
+ * are different facts and must not be reported as the same one. Both are still
+ * reported; only the message differs.
+ *
+ * A REJECTION from either source is swallowed to an empty contribution rather
+ * than propagated: one unavailable source must not make an existing view in the
+ * OTHER source read as missing.
+ */
+async function fetchSavedViews(dataSource, object) {
+    const canReadObjectDef = typeof dataSource?.getObjectSchema === 'function';
+    const canReadOverlay = typeof dataSource?.listViews === 'function';
+    if (!canReadObjectDef && !canReadOverlay)
+        return { capable: false, views: {} };
+    const embedded = canReadObjectDef
+        ? dataSource.getObjectSchema(object).then((def) => (isRecord(def) ? (def.listViews ?? def.list_views) : undefined), () => undefined)
+        : Promise.resolve(undefined);
+    const overlay = canReadOverlay
+        ? dataSource.listViews(object).then((rows) => rows, () => undefined)
+        : Promise.resolve(undefined);
+    const [embeddedViews, overlayViews] = await Promise.all([embedded, overlay]);
+    return { capable: true, views: collectSavedViews(embeddedViews, overlayViews) };
+}
+/**
+ * Resolve a schema node's `dataSource` binding, fetching the named saved view.
+ *
+ * @param schema      The component's schema node (its `dataSource` is read).
+ * @param dataSource  Explicit adapter; falls back to `SchemaRendererContext`.
+ *
+ * @example
+ * ```tsx
+ * const binding = useElementDataSource(schema, adapter);
+ * if (binding.status === 'missing') return <ConfigError message={binding.error} />;
+ * if (binding.status === 'loading') return <Skeleton />;
+ * const objectName = binding.composed?.object ?? schema.objectName;
+ * ```
+ */
+export function useElementDataSource(schema, dataSource) {
+    const context = useContext(SchemaRendererContext);
+    const adapter = (dataSource ?? context?.dataSource ?? null);
+    const config = useMemo(() => {
+        const raw = isRecord(schema) ? schema.dataSource : undefined;
+        return isElementDataSourceConfig(raw) ? raw : undefined;
+    }, [schema]);
+    const object = config?.object;
+    const viewName = config?.view;
+    /**
+     * Which (object, view) pair a stored resolution belongs to.
+     *
+     * The state carries its own key instead of being CLEARED when the binding
+     * changes, so the effect never calls `setState` synchronously in its body
+     * (`react-hooks/set-state-in-effect`, an error in this repo — and the cascading
+     * render it names is real: every mount would render twice). A resolution whose
+     * key no longer matches simply does not count, which reads as `loading` below
+     * — the same answer clearing would have produced, without the extra render.
+     */
+    const requestKey = object && viewName ? JSON.stringify([object, viewName]) : '';
+    // `view: null` = resolved to nothing (missing). `null` state = never resolved.
+    const [resolved, setResolved] = useState(null);
+    useEffect(() => {
+        if (!object || !viewName)
+            return;
+        let cancelled = false;
+        fetchSavedViews(adapter, object).then(({ capable, views }) => {
+            if (cancelled)
+                return;
+            if (!capable) {
+                setResolved({
+                    key: requestKey,
+                    view: null,
+                    error: `dataSource.view "${viewName}" cannot be resolved: this data source ` +
+                        `cannot list the saved views of object "${object}".`,
+                });
+                return;
+            }
+            const view = resolveSavedView(views, viewName, object);
+            setResolved(view
+                ? { key: requestKey, view }
+                : {
+                    key: requestKey,
+                    view: null,
+                    error: elementDataSourceViewNotFoundMessage(object, viewName, Object.keys(views)),
+                });
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [adapter, object, viewName, requestKey]);
+    return useMemo(() => {
+        if (!config)
+            return { status: 'absent' };
+        if (!config.view) {
+            return { status: 'ready', config, composed: composeElementDataSource(config) };
+        }
+        if (resolved?.key !== requestKey)
+            return { status: 'loading', config };
+        if (resolved.view === null)
+            return { status: 'missing', config, error: resolved.error };
+        return {
+            status: 'resolved',
+            config,
+            view: resolved.view,
+            composed: composeElementDataSource(config, resolved.view),
+        };
+    }, [config, resolved, requestKey]);
+}

package/dist/hooks/useExpression.d.ts

@@ -56,6 +56,64 @@ export declare function usePredicateScope(): Record<string, any>;
  * dependencies").
  */
 export { toPredicateInput } from '@object-ui/core';
+/**
+ * Build the predicate context for a **row record** — the bag to hand
+ * {@link useCondition} when the thing being gated is scoped to one record.
+ *
+ * The row is bound the THREE ways the platform's row surfaces bind it:
+ * `record.status` (spec/canonical), bare `status` (row-action shorthand), and
+ * `data.status` (legacy). This is not three dialects; it is one rule, and it is
+ * `evalRowPredicate`'s rule (`core/evaluator/listConditional.ts` — the record
+ * header, list rows, the row kebab and conditional formatting all evaluate
+ * through it), restated here for the `useCondition` tier so both tiers answer
+ * an author's `visible:` the same way.
+ *
+ * ## Why a helper and not "just spread the row" (objectui#4075)
+ *
+ * `useCondition` evaluates on `new ExpressionEvaluator({ ...scope, ...context })`,
+ * so a caller that passes the row spread flat resolves the shorthand spelling
+ * and NOTHING else. The canonical spelling is the `record.` root — it is what
+ * `ExpressionEvaluator`'s CEL path binds (`bag.record` as the record
+ * namespace), what `evalRowPredicate` binds, and what the server enforces
+ * with. Under a root-only bag `record.viewer.can_act` does not read as `false`:
+ * the evaluator throws `record is not defined`, and a fail-closed `visible`
+ * turns that throw into "hidden". A correctly-authored predicate then deletes
+ * its own button, indistinguishably from the gate having said no.
+ *
+ * That was live, not theoretical: every declared action on framework's
+ * `sys_approval_request` gates on `record.viewer.*` (framework#3310 / #3424),
+ * so the whole server-declared approval decision set was invisible wherever
+ * `DeclaredActionsBar` rendered until objectui#4077 bound the row this way —
+ * and the four generic action renderers carried the same root-only binding
+ * until objectui#4075.
+ *
+ * `record` and `data` are written AFTER the spread deliberately: a row that
+ * happens to carry a field literally named `record` or `data` must not shadow
+ * the root every predicate is written against. Same precedence as
+ * `evalRowPredicate`.
+ *
+ * This is the BINDING rule only. It deliberately does not touch the evaluation
+ * entry — `useCondition` / `toPredicateInput` / `hasDeclaredVisibilityGate`
+ * keep their pinned semantics (objectui#3492 / #3842 / #3850 / #3871), and each
+ * caller keeps its own error policy (fail-closed `visible` vs the fail-soft
+ * legs). Binding the row is a different question from what to do when the
+ * predicate faults.
+ *
+ * ## No row → bind NOTHING, do not bind an empty one
+ *
+ * `null` / `undefined` / a non-object returns an EMPTY bag, not
+ * `{ record: {}, data: {} }`. The difference is load-bearing: `useCondition`
+ * merges this context OVER the ambient predicate scope, so binding an empty
+ * record would blank out a `record` that a host had put in the scope itself —
+ * which is exactly how `action:group`'s dropdown leaf is driven in
+ * `action-group-dropdown-visible.test.tsx`, and it is a legitimate way for a
+ * host to supply the row. "This surface has no row of its own" must stay
+ * distinct from "this surface's row is empty"; only the latter is entitled to
+ * shadow the scope.
+ *
+ * @param record The row, or nothing.
+ */
+export declare function usePredicateRecordContext(record: unknown): Record<string, any>;
 /**
  * Hook for evaluating expressions with dynamic context
  *

package/dist/hooks/useExpression.js

@@ -70,6 +70,71 @@ export function usePredicateScope() {
  * dependencies").
  */
 export { toPredicateInput } from '@object-ui/core';
+/**
+ * Build the predicate context for a **row record** — the bag to hand
+ * {@link useCondition} when the thing being gated is scoped to one record.
+ *
+ * The row is bound the THREE ways the platform's row surfaces bind it:
+ * `record.status` (spec/canonical), bare `status` (row-action shorthand), and
+ * `data.status` (legacy). This is not three dialects; it is one rule, and it is
+ * `evalRowPredicate`'s rule (`core/evaluator/listConditional.ts` — the record
+ * header, list rows, the row kebab and conditional formatting all evaluate
+ * through it), restated here for the `useCondition` tier so both tiers answer
+ * an author's `visible:` the same way.
+ *
+ * ## Why a helper and not "just spread the row" (objectui#4075)
+ *
+ * `useCondition` evaluates on `new ExpressionEvaluator({ ...scope, ...context })`,
+ * so a caller that passes the row spread flat resolves the shorthand spelling
+ * and NOTHING else. The canonical spelling is the `record.` root — it is what
+ * `ExpressionEvaluator`'s CEL path binds (`bag.record` as the record
+ * namespace), what `evalRowPredicate` binds, and what the server enforces
+ * with. Under a root-only bag `record.viewer.can_act` does not read as `false`:
+ * the evaluator throws `record is not defined`, and a fail-closed `visible`
+ * turns that throw into "hidden". A correctly-authored predicate then deletes
+ * its own button, indistinguishably from the gate having said no.
+ *
+ * That was live, not theoretical: every declared action on framework's
+ * `sys_approval_request` gates on `record.viewer.*` (framework#3310 / #3424),
+ * so the whole server-declared approval decision set was invisible wherever
+ * `DeclaredActionsBar` rendered until objectui#4077 bound the row this way —
+ * and the four generic action renderers carried the same root-only binding
+ * until objectui#4075.
+ *
+ * `record` and `data` are written AFTER the spread deliberately: a row that
+ * happens to carry a field literally named `record` or `data` must not shadow
+ * the root every predicate is written against. Same precedence as
+ * `evalRowPredicate`.
+ *
+ * This is the BINDING rule only. It deliberately does not touch the evaluation
+ * entry — `useCondition` / `toPredicateInput` / `hasDeclaredVisibilityGate`
+ * keep their pinned semantics (objectui#3492 / #3842 / #3850 / #3871), and each
+ * caller keeps its own error policy (fail-closed `visible` vs the fail-soft
+ * legs). Binding the row is a different question from what to do when the
+ * predicate faults.
+ *
+ * ## No row → bind NOTHING, do not bind an empty one
+ *
+ * `null` / `undefined` / a non-object returns an EMPTY bag, not
+ * `{ record: {}, data: {} }`. The difference is load-bearing: `useCondition`
+ * merges this context OVER the ambient predicate scope, so binding an empty
+ * record would blank out a `record` that a host had put in the scope itself —
+ * which is exactly how `action:group`'s dropdown leaf is driven in
+ * `action-group-dropdown-visible.test.tsx`, and it is a legitimate way for a
+ * host to supply the row. "This surface has no row of its own" must stay
+ * distinct from "this surface's row is empty"; only the latter is entitled to
+ * shadow the scope.
+ *
+ * @param record The row, or nothing.
+ */
+export function usePredicateRecordContext(record) {
+    return useMemo(() => {
+        if (record == null || typeof record !== 'object' || Array.isArray(record))
+            return {};
+        const row = record;
+        return { ...row, record: row, data: row };
+    }, [record]);
+}
 /**
  * Hook for evaluating expressions with dynamic context
  *