@object-ui/react 17.5.0 → 17.7.0

package/dist/context/SchemaRendererContext.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { createContext, useContext, useMemo } from 'react';
+import { usePredicateScope } from '../hooks/useExpression.js';
 const SchemaRendererContext = createContext(null);
 export { SchemaRendererContext };
 export const SchemaRendererProvider = ({ children, dataSource, debug, debugFlags, apiFetch, }) => {
@@ -18,13 +19,45 @@ export const useSchemaContext = () => {
     }
     return context;
 };
+/**
+ * Resolve a `bind` path against the ambient predicate scope.
+ *
+ * ## What it reads, and what it deliberately does not (objectui#9308)
+ *
+ * The scope a host publishes through `PredicateScopeProvider` — the same
+ * channel `useCondition` / `useExpression` merge under a locally-passed
+ * context, and the one app-shell's `ExpressionProvider` already feeds. It is
+ * NOT `SchemaRendererContext.dataSource`.
+ *
+ * `dataSource` is the host's injected ADAPTER, declared as the published
+ * `DataSource` contract (objectui#7912). An adapter has no `users` member, no
+ * `value` member, no member a `bind` path names — so walking it resolved
+ * `undefined` for every conformant host, and the nine production readers of
+ * this hook have all been running their fallback (`boundData || schema.items`,
+ * `|| schema.nodes`, or a fall-through to their own fetch chain) ever since.
+ * The only hosts it answered were ones injecting a data bag through a key the
+ * contract says is an adapter, which has been a compile error since
+ * objectui#7912.
+ *
+ * Maintainer ruling 2026-09-13 (option B) points it at the channel that can
+ * actually answer it. No published key is added: the provider, the hook and
+ * the host wiring all already exist.
+ *
+ * Returns `undefined` for an absent or empty path, and for any path the scope
+ * does not carry — the readers' fallbacks are what run then, exactly as
+ * before.
+ */
 export const useDataScope = (path) => {
-    const context = useContext(SchemaRendererContext);
-    const dataSource = context?.dataSource;
+    const scope = usePredicateScope();
     if (!path)
         return undefined;
-    if (!dataSource)
+    if (!scope)
         return undefined;
-    // Simple path resolution for now. In real app might be more complex
-    return path.split('.').reduce((acc, part) => acc && acc[part], dataSource);
+    // Simple path resolution for now. In real app might be more complex.
+    //
+    // The accumulator is `any` BY DECLARATION: this walk addresses arbitrary
+    // member names on a host-published bag, and `Record<string, any>` declares
+    // none of them beyond the first segment. The hook's published return type is
+    // unchanged — `any` before and after — so no reader of `useDataScope` moves.
+    return path.split('.').reduce((acc, part) => acc && acc[part], scope);
 };

package/dist/context/ThemeContext.js

@@ -131,7 +131,7 @@ export function ThemeProvider({ themes: themesInput = [], defaultTheme, defaultM
         // Apply mode class
         el.classList.remove('light', 'dark');
         el.classList.add(resolvedMode);
-        // No favicon here: spec v17 (#3494) pruned `Theme.logo`, so the key is
+        // No favicon here: spec v17 (objectstack-ai/objectstack#3494) pruned `Theme.logo`, so the key is
         // stripped at parse and could never arrive. The live favicon comes from
         // operator branding (`getFaviconUrl()`), applied in the console's
         // index.html, main.tsx, and on route change.

package/dist/context/actionRunnerTranslator.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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.
+ */
+/** What `ActionRunner.setTranslator` takes. */
+type ActionRunnerTranslate = (key: string, options: {
+    defaultValue: string;
+}) => string;
+/**
+ * The translator both React owners of an `ActionRunner` — `<ActionProvider>`
+ * and `useActionRunner` — install on the runner they build, so the text the
+ * runner writes itself (the generic success toast an action with no
+ * `successMessage` ends in) renders in the session's language instead of
+ * English. Internal to this package; not re-exported from its entry.
+ *
+ * The function is created once per mount and reads the latest `t` when it is
+ * CALLED, so a language switch reaches a runner that was built before it. Both
+ * owners rebuild their runner only when their `context` changes, and a
+ * translator captured at build time would keep answering in the language that
+ * was active then. The identity comes from `useState`'s initializer, not from a
+ * memo, so nothing depends on a `useMemo` result staying put (AGENTS.md #10).
+ */
+export declare function useActionRunnerTranslator(): ActionRunnerTranslate;
+export {};

package/dist/context/actionRunnerTranslator.js

@@ -0,0 +1,37 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { useEffect, useRef, useState } from 'react';
+import { useObjectTranslation } from '@object-ui/i18n';
+/**
+ * The translator both React owners of an `ActionRunner` — `<ActionProvider>`
+ * and `useActionRunner` — install on the runner they build, so the text the
+ * runner writes itself (the generic success toast an action with no
+ * `successMessage` ends in) renders in the session's language instead of
+ * English. Internal to this package; not re-exported from its entry.
+ *
+ * The function is created once per mount and reads the latest `t` when it is
+ * CALLED, so a language switch reaches a runner that was built before it. Both
+ * owners rebuild their runner only when their `context` changes, and a
+ * translator captured at build time would keep answering in the language that
+ * was active then. The identity comes from `useState`'s initializer, not from a
+ * memo, so nothing depends on a `useMemo` result staying put (AGENTS.md #10).
+ */
+export function useActionRunnerTranslator() {
+    const { t } = useObjectTranslation();
+    const latest = useRef(t);
+    // No dependency list: after every render, the ref holds that render's `t`.
+    // Actions run from user events, which arrive after the commit.
+    useEffect(() => {
+        latest.current = t;
+    });
+    const [translate] = useState(() => {
+        const read = (key, options) => String(latest.current(key, options));
+        return read;
+    });
+    return translate;
+}

package/dist/context/index.d.ts

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

package/dist/context/index.js

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

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

@@ -50,6 +50,27 @@
  * designer emits for an unconfigured column list, and supplying the columns is
  * exactly why a view was named.
  *
+ * The row cap answers "did the component author one?" the same way, and for the
+ * same reason (objectui#9899). A cap the contract REFUSES — `pageSize: 0`,
+ * a negative, a fraction — is not a cap this relay may treat as the author's
+ * intent, so it does not suppress the one the bound view supplies. Deciding
+ * that question by PRESENCE is how a view's legitimate cap was dropped in
+ * favour of the consuming renderer's own default: measured end to end on
+ * `list-view` before the repair, a component carrying `pagination.pageSize: 0`
+ * under a view supplying `7` put `$top: 100` on the wire — the view's cap never
+ * reached it, so the read was WIDER than the view asked for.
+ *
+ * The VIEW's own cap can be refused too, and `@object-ui/core` drops it before
+ * it reaches this relay (objectui#9928). The drop is right, but it left the
+ * consuming renderer nothing to refuse, so it went silent — and this relay
+ * reports the view's refusal instead (objectui#10015). See
+ * {@link describeRefusedViewRowLimit} for when that message applies.
+ *
+ * The BINDING's own cap follows the same rule (objectui#10016): a `limit` the
+ * contract refuses is not authored, so `@object-ui/core` lets the view's cap
+ * through in its place, and that cap is a baseline here like any other
+ * view-sourced value. See {@link describeRefusedBindingRowLimit}.
+ *
  * ## What a mapping may NOT do
  *
  * {@link ElementDataSourceMapping} names only keys the target block genuinely
@@ -59,6 +80,17 @@
  * therefore leaves `limit` unmapped rather than parking it somewhere plausible,
  * and the gap is recorded at the call site instead of being papered over here.
  *
+ * ## A block with no ADAPTER fails loudly too (objectui#5378)
+ *
+ * The section below is about an unresolvable view NAME. The coarser failure —
+ * no runtime adapter reached the block at all — used to render an empty shell
+ * in exactly the same silence, and that is what `requiresDataSource` +
+ * {@link NoDataSourcePanel} now report. Measured on the published
+ * getting-started guide: all five of its blocks resolved no adapter, fetched
+ * nothing, and said nothing. The two panels are deliberately the same shape;
+ * they answer "which view?" and "which data source?", and an author who sees
+ * either one is being told where to look.
+ *
  * ## An unresolvable `view` fails loudly
  *
  * When the named view does not exist the gate renders a configuration error
@@ -68,8 +100,8 @@
  * like it works.
  */
 import * as React from 'react';
-import { type ElementDataSourceConfig } from '@object-ui/core';
-import { type ElementDataSourceStatus } from '../hooks/useElementDataSource';
+import { type ElementDataSourceConfig, type FilterOperatorError } from '@object-ui/core';
+import { type ElementDataSourceStatus } from '../hooks/useElementDataSource.js';
 /**
  * Where a block's row cap lives. Three spellings are real in this repo and each
  * is the ONLY one its block reads: `list-view`/`object-grid` read
@@ -128,6 +160,15 @@ export interface UseElementDataSourceSchemaResult<S> {
     config?: ElementDataSourceConfig;
     /** Author-facing explanation, set only for `missing`. */
     error?: string;
+    /**
+     * The refused filter that stopped the binding from applying — set only with
+     * `missing`, and `error` then carries its message (objectui#10789). Either
+     * merge can refuse: the view's filter with the binding's own
+     * ({@link useElementDataSource}), or the component's filter with that result
+     * (this hook). {@link ElementDataSourceGate} draws the malformed-filter
+     * notice from it.
+     */
+    filterRefusal?: FilterOperatorError;
 }
 /**
  * Resolve a block's `dataSource` binding and apply it to the block's own schema
@@ -169,6 +210,108 @@ export declare function ElementDataSourceErrorPanel({ testId, title, message, }:
  * would flash a configuration error on every mount.
  */
 export declare function ElementDataSourceLoadingPanel({ testId, }: Pick<ElementDataSourceStatusPanelProps, 'testId'>): React.ReactElement;
+/**
+ * The adapter this block would use, resolved the one way every block in the
+ * family resolves it: an explicit value first, the `SchemaRendererProvider`
+ * context second.
+ *
+ * The `isElementDataSourceConfig` guard is the same one
+ * {@link useElementDataSourceSchema} applies — a host handing us the spec
+ * BINDING under this name is handing us metadata, not an adapter, and counting
+ * it as one is how "no data source" reads as "resolved".
+ *
+ * `T` is what the CALLER expects to have been injected, and the assertion is
+ * the caller's, not this hook's: an adapter arrives here as a `dataSource` prop
+ * or a context value that nothing in this package can narrow, so the type has
+ * to be declared by whoever knows which interface their block consumes. Leave
+ * it off and you get `unknown`, which is the honest default.
+ */
+export declare function useResolvedDataSource<T = unknown>(explicit?: unknown): T | undefined;
+/**
+ * The author-facing sentence a block with no adapter says out loud.
+ *
+ * One wording for the whole object-bound family, because the reader's mistake
+ * is the same one every time and the fix is the same one every time: the
+ * adapter is injected by an ANCESTOR (`SchemaRendererProvider`), so nothing
+ * written on the block itself can supply it. Naming the block and the object
+ * it was about to read is what turns "nothing happened" into an address.
+ */
+export declare function noDataSourceMessage(blockKey: string, objectName?: unknown): string;
+/**
+ * The "this block resolved no adapter" panel — objectui#5378 item 2, and the
+ * #5349 shape it belongs to.
+ *
+ * Until this existed, a block that resolved no adapter rendered an EMPTY SHELL:
+ * `object-grid` painted a header-only table, `object-form` a field-less card,
+ * `detail-view` nothing at all — no error, no warning, no empty state that
+ * explained itself. Measured on the published getting-started guide
+ * (`content/docs/guide/building-crud-app.md`), every one of its five blocks was
+ * in that state and the page reported success while fetching nothing.
+ *
+ * The empty shell is the defect, not a side effect of it: it is indistinguishable
+ * from "the query ran and matched no rows", which is the reading an author (very
+ * often an AI author) takes, and it points at the DATA when the fault is in the
+ * WIRING one level up. Same posture as {@link ElementDataSourceErrorPanel}: the
+ * metadata is answerable, so the answer is rendered where the author can see it.
+ */
+export declare function NoDataSourcePanel({ testId, title, message, }: ElementDataSourceStatusPanelProps): React.ReactElement;
+/**
+ * The wrapping seam — mark `renderer` as one that wraps {@link
+ * ElementDataSourceGate}, so its registrations DECLARE the `dataSource` key this
+ * gate READS (objectui#6678).
+ *
+ * ```tsx
+ * export const ObjectMapRenderer = elementDataSourceBlock<React.FC<any>>(({ schema }) => (
+ *   <ElementDataSourceGate schema={schema} testId="object-map" …>
+ *     {(bound) => <ObjectMap schema={bound} />}
+ *   </ElementDataSourceGate>
+ * ));
+ * ```
+ *
+ * ## What this closes
+ *
+ * `PageComponentSchema.dataSource` is the one spelling that resolves a saved
+ * view for an object-bound block. It works — and because no registration
+ * declared it, `sdui-parser`'s `validateTree` reported it with the SAME
+ * `unknown-prop` warning it gives the spellings that do nothing. On the tier
+ * built to accept AI-authored pages the diagnostic IS the contract, so the
+ * tier's only signal pointed away from the one key that works.
+ *
+ * ## Why a seam and not nine declarations
+ *
+ * Maintainer ruling, 2026-08-29: option B **in the injection form**. Nine
+ * hand-written copies across nine packages is the shape that ruling refused —
+ * they drift, and the tenth block forgets. Passing through here is the only
+ * thing a block does; `Registry.register` emits the declaration
+ * (`withElementDataSourceInput`), and `ELEMENT_DATA_SOURCE_INPUT` in
+ * `@object-ui/core` is its single copy, beside the binding's own semantics.
+ *
+ * ## And it cannot be forgotten
+ *
+ * `scripts/check-element-data-source-declaration.mjs` fails any source that
+ * renders `ElementDataSourceGate` for a registration without passing that
+ * registration's renderer through this function. That is the mechanical half of
+ * "a tenth block gets it automatically"; this function is the seam it enforces.
+ *
+ * Returns the renderer UNCHANGED (the mark is held in a `WeakSet`), so it is safe
+ * over a `React.forwardRef` object, over `React.memo`, and over a component that
+ * something else already re-exports by reference.
+ *
+ * ⚠️ Re-exported from `@object-ui/core` — where the marker and the declaration
+ * live — rather than wrapped here: ONE function under ONE name. This export
+ * exists for DISCOVERABILITY, so the seam is findable beside the gate it is
+ * about; **call sites must import it from `@object-ui/core`**, and
+ * `check:element-data-source-declaration` enforces that.
+ *
+ * The rule is measured, not stylistic. A registration runs at MODULE SCOPE, 101
+ * suites in this repo partially mock `@object-ui/react` by hand-listing the
+ * exports they return, and a module-scope read of a name absent from such a list
+ * throws at COLLECTION time — the importing test file dies before running one
+ * assertion. Taking the seam from here reddened 17 files across all four CI
+ * shards with zero failed assertions among them. Nothing mocks `@object-ui/core`,
+ * and every registration module already imports `ComponentRegistry` from it.
+ */
+export { elementDataSourceBlock } from '@object-ui/core';
 export interface ElementDataSourceGateProps<S> {
     /** The block's schema node. */
     schema: S;
@@ -180,6 +323,23 @@ export interface ElementDataSourceGateProps<S> {
     testId: string;
     /** Heading for the unresolvable-view panel. */
     errorTitle?: string;
+    /**
+     * Whether THIS placement cannot do its job without a runtime adapter — when
+     * true and none resolves, the gate renders {@link NoDataSourcePanel} instead
+     * of the block (objectui#5378 item 2).
+     *
+     * The gate cannot compute this and does not try. "Needs an adapter" is a
+     * statement about the block's own fallbacks, and every block in the family
+     * has different ones: an `object-grid` carrying inline `data` rows needs no
+     * adapter, an `object-form` with inline `customFields` needs none, a
+     * `detail-view` handed a `data` record needs none. A predicate guessed HERE
+     * would paint a configuration error over a block that is working, which is a
+     * worse failure than the silence this replaces — so the call site, which
+     * knows its own fallbacks, states it.
+     */
+    requiresDataSource?: boolean;
+    /** Explanation for the no-adapter panel; see {@link noDataSourceMessage}. */
+    noDataSourceMessage?: string;
     /**
      * Renders the block with the bound schema. Called during the gate's own
      * render, so it must RETURN AN ELEMENT and never call hooks itself — the
@@ -196,4 +356,4 @@ export interface ElementDataSourceGateProps<S> {
  * against a half-resolved query is how a page shows a wider answer than the one
  * that was authored.
  */
-export declare function ElementDataSourceGate<S>({ schema, mapping, dataSource, testId, errorTitle, children, }: ElementDataSourceGateProps<S>): React.ReactElement | null;
+export declare function ElementDataSourceGate<S>({ schema, mapping, dataSource, testId, errorTitle, requiresDataSource, noDataSourceMessage: noDataSourceText, children, }: ElementDataSourceGateProps<S>): React.ReactElement | null;