@object-ui/react 16.1.0 → 17.1.0

package/dist/hooks/useClientNotifications.js

@@ -17,8 +17,13 @@
  * `sys_inbox_message` materialization and the `sys_notification_receipt`
  * read-state spine (the re-modeled `sys_notification` L2 event carries no
  * recipient/read columns). This hook only needs to call the SDK with its
- * current signatures: `list(options)`, `markRead(ids[])`, `markAllRead()`,
- * and `registerDevice(request)`.
+ * current signatures: `list(options)`, `markRead(ids[])`, `markAllRead()`.
+ *
+ * The former registerDevice/getPreferences/updatePreferences delegates were
+ * removed (objectstack#3612): the SDK deleted those methods because the
+ * /notifications/devices and /notifications/preferences server routes were
+ * never built — every call was a guaranteed error. They return when the
+ * server side exists.
  */
 import { useCallback, useContext, useEffect, useRef, useState } from 'react';
 import { SchemaRendererContext } from '../context/SchemaRendererContext';
@@ -113,54 +118,6 @@ export function useClientNotifications(options = {}) {
             setLoading(false);
         }
     }, [client, notify]);
-    /* ---- registerDevice ---- */
-    const registerDevice = useCallback(async (token, platform) => {
-        if (!client?.notifications)
-            return;
-        setError(null);
-        try {
-            // ADR-0030 / @objectstack/client v7+: registerDevice takes a single
-            // RegisterDeviceRequest object (`{ token, platform }`), not positional
-            // args. `platform` is the device platform enum.
-            await client.notifications.registerDevice({
-                token,
-                platform: platform,
-            });
-        }
-        catch (err) {
-            const wrapped = err instanceof Error ? err : new Error('Failed to register device');
-            setError(wrapped);
-            throw wrapped;
-        }
-    }, [client]);
-    /* ---- getPreferences ---- */
-    const getPreferences = useCallback(async () => {
-        if (!client?.notifications)
-            return null;
-        setError(null);
-        try {
-            return await client.notifications.getPreferences();
-        }
-        catch (err) {
-            const wrapped = err instanceof Error ? err : new Error('Failed to get preferences');
-            setError(wrapped);
-            throw wrapped;
-        }
-    }, [client]);
-    /* ---- updatePreferences ---- */
-    const updatePreferences = useCallback(async (prefs) => {
-        if (!client?.notifications)
-            return;
-        setError(null);
-        try {
-            await client.notifications.updatePreferences(prefs);
-        }
-        catch (err) {
-            const wrapped = err instanceof Error ? err : new Error('Failed to update preferences');
-            setError(wrapped);
-            throw wrapped;
-        }
-    }, [client]);
     /* ---- markAsRead (server + local) ---- */
     const markAsRead = useCallback(async (id) => {
         // Optimistically mark locally first
@@ -198,9 +155,6 @@ export function useClientNotifications(options = {}) {
     }, [pollInterval, client, fetchNotifications]);
     return {
         fetchNotifications,
-        registerDevice,
-        getPreferences,
-        updatePreferences,
         markAsRead,
         loading,
         error,

package/dist/hooks/useFilterScope.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 { type ReactNode } from 'react';
+import type { FilterTokenScope } from '@object-ui/core';
+/**
+ * Provide the session scope used to resolve filter placeholders.
+ *
+ * Mount once, above any surface that renders filtered data. The console shell
+ * mounts it next to `ExpressionProvider`, where both the signed-in user and
+ * the active organization are already resolved.
+ */
+export declare function FilterScopeProvider({ currentUserId, currentOrgId, children, }: {
+    currentUserId?: string | null;
+    currentOrgId?: string | null;
+    children: ReactNode;
+}): import("react").FunctionComponentElement<import("react").ProviderProps<FilterTokenScope>>;
+/**
+ * Read the session scope for filter placeholder resolution.
+ *
+ * Pass the result straight to `resolveFilterPlaceholders(filter, scope)` from
+ * `@object-ui/core` — that helper expands every placeholder vocabulary in one
+ * call, which is the point: resolving only some of them is the defect behind
+ * #3574.
+ */
+export declare function useFilterScope(): FilterTokenScope;

package/dist/hooks/useFilterScope.js

@@ -0,0 +1,55 @@
+/**
+ * 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 { createContext, createElement, useContext, useMemo } from 'react';
+/**
+ * The session values filter placeholders resolve against — `{current_user_id}`
+ * and `{current_org_id}` (framework #3574).
+ *
+ * ## Why a dedicated context
+ *
+ * The renderer packages (`plugin-dashboard`, `plugin-charts`, `plugin-list`)
+ * deliberately do not depend on `@object-ui/auth`; they receive everything
+ * they need as schema or context. But a widget cannot resolve
+ * `{current_user_id}` without knowing who is signed in, and the surfaces that
+ * DO know (the app-shell) sit above them.
+ *
+ * `PredicateScopeContext` already carries `current_user` and would have
+ * covered the user id, but it is the *expression* evaluation scope — it
+ * carries no organization, and widening it for an unrelated consumer would
+ * couple filter resolution to predicate semantics. A separate, two-field
+ * context keeps the contract explicit and lets a non-console host provide
+ * exactly these values without adopting the expression stack.
+ *
+ * When no provider is mounted this returns an empty scope. That is a safe
+ * default: unresolved tokens are left intact by the resolver, so the filter
+ * matches nothing rather than silently widening, and the resolver emits one
+ * warning naming the token.
+ */
+const FilterScopeContext = createContext({});
+/**
+ * Provide the session scope used to resolve filter placeholders.
+ *
+ * Mount once, above any surface that renders filtered data. The console shell
+ * mounts it next to `ExpressionProvider`, where both the signed-in user and
+ * the active organization are already resolved.
+ */
+export function FilterScopeProvider({ currentUserId, currentOrgId, children, }) {
+    const value = useMemo(() => ({ currentUserId, currentOrgId }), [currentUserId, currentOrgId]);
+    return createElement(FilterScopeContext.Provider, { value }, children);
+}
+/**
+ * Read the session scope for filter placeholder resolution.
+ *
+ * Pass the result straight to `resolveFilterPlaceholders(filter, scope)` from
+ * `@object-ui/core` — that helper expands every placeholder vocabulary in one
+ * call, which is the point: resolving only some of them is the defect behind
+ * #3574.
+ */
+export function useFilterScope() {
+    return useContext(FilterScopeContext);
+}

package/dist/hooks/useNavigationOverlay.d.ts

@@ -15,8 +15,19 @@ export interface NavigationConfig {
     view?: string;
     preventNavigation?: boolean;
     openNewTab?: boolean;
+    /** Spec `NavigationConfig.size` (#2578) — coarse overlay bucket. */
+    size?: 'auto' | 'sm' | 'md' | 'lg' | 'xl' | 'full';
+    /** @deprecated [#2578 → `size`] explicit pixel/percent width. */
     width?: string | number;
 }
+/**
+ * Resolve the overlay width from a NavigationConfig: an explicit `width` wins
+ * (app-shell pre-resolves `size` into it); otherwise a declared bucket maps
+ * through {@link OVERLAY_SIZE_WIDTHS}. `'auto'`/absent stays `undefined` — the
+ * host's default width — because deriving `auto` needs the object's field
+ * count, which only schema-aware hosts have. Exported for the parity test.
+ */
+export declare function resolveOverlayWidth(navigation: NavigationConfig | undefined): string | number | undefined;
 export type NavigationMode = NavigationConfig['mode'];
 export interface UseNavigationOverlayOptions {
     /** The navigation configuration from the schema */

package/dist/hooks/useNavigationOverlay.js

@@ -16,6 +16,40 @@
  * NavigationConfig support.
  */
 import { useState, useCallback, useMemo } from 'react';
+/**
+ * Pixel cap per overlay `size` bucket, clamped to the viewport at render —
+ * mirrors `plugin-view/src/recordSurface.ts` (`OVERLAY_SIZE_PX`), which owns
+ * the `size: 'auto'` field-count derivation this layer cannot perform (no
+ * object schema here). Kept in lockstep by the spec-parity test.
+ *
+ * Before #2942 this hook only read the deprecated `width`, so an authored
+ * `size` bucket was silently ignored by every host except app-shell (which
+ * pre-resolves it before calling in).
+ */
+const OVERLAY_SIZE_WIDTHS = {
+    sm: 'min(92vw, 480px)',
+    md: 'min(92vw, 720px)',
+    lg: 'min(92vw, 960px)',
+    xl: 'min(92vw, 1200px)',
+    full: 'min(92vw, 1600px)',
+};
+/**
+ * Resolve the overlay width from a NavigationConfig: an explicit `width` wins
+ * (app-shell pre-resolves `size` into it); otherwise a declared bucket maps
+ * through {@link OVERLAY_SIZE_WIDTHS}. `'auto'`/absent stays `undefined` — the
+ * host's default width — because deriving `auto` needs the object's field
+ * count, which only schema-aware hosts have. Exported for the parity test.
+ */
+export function resolveOverlayWidth(navigation) {
+    if (!navigation)
+        return undefined;
+    if (navigation.width !== undefined)
+        return navigation.width;
+    const size = navigation.size;
+    if (size && size !== 'auto')
+        return OVERLAY_SIZE_WIDTHS[size];
+    return undefined;
+}
 /**
  * Hook for NavigationConfig-driven navigation overlay.
  *
@@ -48,7 +82,7 @@ export function useNavigationOverlay(options) {
     const [isOpen, setIsOpen] = useState(false);
     const [selectedRecord, setSelectedRecord] = useState(null);
     const mode = navigation?.mode ?? 'page';
-    const width = navigation?.width;
+    const width = resolveOverlayWidth(navigation);
     const view = navigation?.view;
     const isOverlay = mode === 'drawer' || mode === 'modal' || mode === 'split' || mode === 'popover';
     const close = useCallback(() => {

package/dist/hooks/usePageVariables.js

@@ -117,18 +117,30 @@ PageVariablesProvider.displayName = 'PageVariablesProvider';
  */
 export function usePageVariables() {
     const ctx = useContext(PageVariablesContext);
-    if (!ctx) {
-        // Graceful fallback — allows components to work outside a Page
-        return {
-            variables: {},
-            definitions: [],
-            setVariable: () => { },
-            setVariables: () => { },
-            resetVariables: () => { },
-        };
-    }
-    return ctx;
+    return ctx ?? OUTSIDE_PAGE;
 }
+/**
+ * Graceful fallback — allows components to work outside a Page.
+ *
+ * MUST be a module constant, not a fresh literal per call. `SchemaRenderer`
+ * feeds `variables` into the `evaluatedSchema` memo's dependency list, so a new
+ * object each render defeats that memo for every component rendered outside a
+ * PageVariablesProvider — and hands children a new schema identity every time.
+ * A `kind:'react'` page memoises its compiled source on that identity, so the
+ * page was being remounted and its `useState` reset (objectui#2954).
+ *
+ * Frozen through, because sharing one instance means a stray write would no
+ * longer be scoped to one render — it would leak to every consumer outside a
+ * provider. There is no writer today (the setters are the API, and here they
+ * are no-ops); the freeze keeps it that way.
+ */
+const OUTSIDE_PAGE = Object.freeze({
+    variables: Object.freeze({}),
+    definitions: Object.freeze([]),
+    setVariable: () => { },
+    setVariables: () => { },
+    resetVariables: () => { },
+});
 /**
  * Hook to check if a PageVariablesProvider is available.
  */

package/dist/hooks/useRecordSearch.js

@@ -7,6 +7,7 @@
  */
 import { useEffect, useMemo, useRef, useState } from 'react';
 import { getRecordDisplayName as defaultDisplayName } from '@object-ui/core';
+import { errorCodeIs } from '@object-ui/types';
 // ADR-0079: the global-search default display-name resolver is now the ONE
 // shared `getRecordDisplayName` from `@object-ui/core` (honors titleFormat →
 // `displayNameField` → type-aware derivation → `Record #<id>`). Callers can
@@ -80,6 +81,15 @@ export function useRecordSearch(opts) {
     // Stable signature derived from the object metadata fields we actually
     // touch. Prevents pointless re-runs when the parent re-renders with a
     // new array reference but identical content.
+    //
+    // Deliberately UNCAPPED: `maxObjectsQueried` bounds the number of parallel
+    // per-object requests on the fanout path (applied there), not the search
+    // scope itself. Capping here also truncated the `objects` whitelist sent to
+    // the single-request `/api/v1/search` call, so the palette silently searched
+    // only the first N nav objects — records in every later object were
+    // unfindable no matter what the user typed. Measured symptom: ⌘K in an app
+    // with 40+ searchable objects only ever queried the first 8 nav entries,
+    // so which sidebar group happened to come first decided what was findable.
     const candidates = useMemo(() => {
         if (!Array.isArray(objects) || objects.length === 0)
             return [];
@@ -99,8 +109,8 @@ export function useRecordSearch(opts) {
         else {
             pool = objects.filter((o) => o?.searchable !== false);
         }
-        return pool.slice(0, maxObjectsQueried);
-    }, [objects, objectNames, maxObjectsQueried]);
+        return pool;
+    }, [objects, objectNames]);
     const candidateSignature = useMemo(() => {
         return candidates.map((o) => `${o?.name}:${o?.titleField ?? ''}`).join('|');
     }, [candidates]);
@@ -127,7 +137,90 @@ export function useRecordSearch(opts) {
             // Skip if a newer run started during the debounce window.
             if (runIdRef.current !== myRunId)
                 return;
-            const requests = candidates.map((obj) => Promise.resolve()
+            // Prefer the platform's unified global-search endpoint when the data
+            // source exposes it (ObjectStackAdapter → GET /api/v1/search?q=). The
+            // per-object `find({ $search })` fanout below only runs each object's
+            // metadata-driven search (ADR-0061) and can miss records the global
+            // search index knows about — the command-palette symptom in framework
+            // #3371, where `/api/v1/search` returned an account/opportunity the
+            // palette never showed. When `searchAll` is absent (mock/test adapters,
+            // non-ObjectStack backends) we fall back to the fanout.
+            const searchAll = dataSource.searchAll;
+            if (typeof searchAll === 'function') {
+                // Scope to the candidate objects (the app's searchable nav objects) so
+                // the palette doesn't surface records from objects the current app
+                // can't route to. We both ask the server to scope (`objects`) and
+                // re-filter locally, guarding servers that ignore the param.
+                const byName = new Map();
+                for (const obj of candidates) {
+                    if (typeof obj?.name === 'string')
+                        byName.set(obj.name, obj);
+                }
+                Promise.resolve()
+                    .then(() => searchAll.call(dataSource, trimmed, {
+                    limit: maxObjectsQueried * topPerObject,
+                    objects: Array.from(byName.keys()),
+                }))
+                    .then((res) => {
+                    // Discard if a newer run started while we were waiting.
+                    if (runIdRef.current !== myRunId)
+                        return;
+                    const rawHits = Array.isArray(res?.hits)
+                        ? res.hits
+                        : Array.isArray(res)
+                            ? res
+                            : [];
+                    const hits = [];
+                    for (const h of rawHits) {
+                        const objectName = h?.object ?? h?.objectName;
+                        if (typeof objectName !== 'string')
+                            continue;
+                        // Keep only whitelisted objects (no-op when the server already
+                        // honored `objects`).
+                        if (byName.size > 0 && !byName.has(objectName))
+                            continue;
+                        const recordId = h?.id ?? h?.record?.id ?? h?.record?._id;
+                        if (recordId == null)
+                            continue;
+                        const objDef = byName.get(objectName) ?? { name: objectName };
+                        const title = typeof h?.title === 'string' && h.title.trim() !== '' ? h.title.trim() : '';
+                        const display = title || getDisplayName(objDef, h?.record ?? {}) || `Record #${recordId}`;
+                        const snippet = typeof h?.snippet === 'string' ? h.snippet.trim() : '';
+                        hits.push({
+                            objectName,
+                            objectLabel: typeof objDef.label === 'string' && objDef.label.length > 0
+                                ? objDef.label
+                                : objectName,
+                            recordId: String(recordId),
+                            display,
+                            // Only surface a snippet when it adds information beyond the title.
+                            subtitle: snippet && snippet !== display ? snippet : undefined,
+                            icon: objDef?.icon,
+                            score: scoreHit(trimmed, display, String(recordId)),
+                            raw: h?.record ?? h,
+                        });
+                    }
+                    // The server already ranks hits across objects; preserve that order.
+                    // Only float an exact-id paste to the very top (parity with the
+                    // fanout path). Array.prototype.sort is stable, so every other hit
+                    // keeps the server ordering.
+                    hits.sort((a, b) => (b.score === 110 ? 1 : 0) - (a.score === 110 ? 1 : 0));
+                    setResults(hits);
+                    setIsSearching(false);
+                    setError(undefined);
+                })
+                    .catch((err) => {
+                    if (runIdRef.current !== myRunId)
+                        return;
+                    setResults([]);
+                    setIsSearching(false);
+                    setError(err instanceof Error ? err : new Error(String(err)));
+                });
+                return;
+            }
+            // Fanout fallback only: one request per object, so THIS is where the
+            // parallel-request cap applies.
+            const requests = candidates.slice(0, maxObjectsQueried).map((obj) => Promise.resolve()
                 .then(() => dataSource.find(obj.name, {
                 $search: trimmed,
                 $top: topPerObject,
@@ -149,7 +242,7 @@ export function useRecordSearch(opts) {
                         // last real error so the UI can show a non-blocking hint.
                         const status = err?.httpStatus ?? err?.status;
                         const code = err?.code;
-                        if (status === 404 || code === 'object_not_found')
+                        if (status === 404 || errorCodeIs(err, 'OBJECT_NOT_FOUND'))
                             continue;
                         lastError = err instanceof Error ? err : new Error(String(err));
                         continue;
@@ -194,6 +287,7 @@ export function useRecordSearch(opts) {
         dataSource,
         candidateSignature,
         topPerObject,
+        maxObjectsQueried,
         minLength,
         debounceMs,
         getDisplayName,

package/dist/index.d.ts

@@ -12,5 +12,6 @@ export * from './LazyPluginLoader';
 export * from './spec-bridge';
 export * from './data-invalidation';
 export { resolveI18nLabel } from './utils/i18n';
-export { extractWriteErrorMessage, isPermissionError } from './utils/error-message';
+export { extractWriteErrorMessage, isPermissionError, extractFieldErrors } from './utils/error-message';
+export type { WriteFieldError } from './utils/error-message';
 export { I18nProvider, useObjectTranslation, useSafeTranslate, useObjectLabel, useSafeFieldLabel, useI18nContext, createI18n, getDirection, getAvailableLanguages, formatDate, formatDateTime, formatRelativeTime, formatCurrency, formatNumber, type I18nConfig, type I18nProviderProps, type TranslationKeys, type DateFormatOptions, type CurrencyFormatOptions, type NumberFormatOptions, } from '@object-ui/i18n';

package/dist/index.js

@@ -15,6 +15,6 @@ export * from './data-invalidation';
 export { resolveI18nLabel } from './utils/i18n';
 // Write-error surfacing utilities (shared by drag-write plugins so a failed
 // PATCH — e.g. an RLS 403 — is never silently swallowed).
-export { extractWriteErrorMessage, isPermissionError } from './utils/error-message';
+export { extractWriteErrorMessage, isPermissionError, extractFieldErrors } from './utils/error-message';
 // Built-in i18n support
 export { I18nProvider, useObjectTranslation, useSafeTranslate, useObjectLabel, useSafeFieldLabel, useI18nContext, createI18n, getDirection, getAvailableLanguages, formatDate, formatDateTime, formatRelativeTime, formatCurrency, formatNumber, } from '@object-ui/i18n';

package/dist/spec-bridge/SpecBridge.d.ts

@@ -18,9 +18,5 @@ export declare class SpecBridge {
     transformListView(spec: any): SchemaNode;
     /** Transform a FormView spec */
     transformFormView(spec: any): SchemaNode;
-    /** Transform a Page spec */
-    transformPage(spec: any): SchemaNode;
-    /** Transform a Dashboard spec */
-    transformDashboard(spec: any): SchemaNode;
     updateContext(ctx: Partial<BridgeContext>): void;
 }

package/dist/spec-bridge/SpecBridge.js

@@ -7,8 +7,6 @@
  */
 import { bridgeListView } from './bridges/list-view';
 import { bridgeFormView } from './bridges/form-view';
-import { bridgePage } from './bridges/page';
-import { bridgeDashboard } from './bridges/dashboard';
 export class SpecBridge {
     constructor(context = {}) {
         Object.defineProperty(this, "bridges", {
@@ -26,8 +24,6 @@ export class SpecBridge {
         this.context = context;
         this.register('list', bridgeListView);
         this.register('form', bridgeFormView);
-        this.register('page', bridgePage);
-        this.register('dashboard', bridgeDashboard);
     }
     register(specType, bridge) {
         this.bridges.set(specType, bridge);
@@ -48,14 +44,6 @@ export class SpecBridge {
     transformFormView(spec) {
         return this.transform('form', spec);
     }
-    /** Transform a Page spec */
-    transformPage(spec) {
-        return this.transform('page', spec);
-    }
-    /** Transform a Dashboard spec */
-    transformDashboard(spec) {
-        return this.transform('dashboard', spec);
-    }
     updateContext(ctx) {
         this.context = { ...this.context, ...ctx };
     }

package/dist/spec-bridge/bridges/list-view.js

@@ -134,17 +134,11 @@ export const bridgeListView = (spec, _context) => {
     // P1.6 — i18n & ARIA
     if (spec.aria)
         node.aria = spec.aria;
-    if (spec.sharing) {
-        // Normalize spec sharing format: map type → visibility, set enabled = true
-        const sharing = { ...spec.sharing };
-        if (sharing.type && !sharing.visibility) {
-            sharing.visibility = sharing.type === 'collaborative' ? 'team' : 'private';
-        }
-        if (sharing.type && sharing.enabled == null) {
-            sharing.enabled = true;
-        }
-        node.sharing = sharing;
-    }
+    // `sharing` is already the spec's `ViewSharing` shape on both sides (#2890) —
+    // this used to DOWNGRADE it here, inventing a legacy `visibility` audience and
+    // an `enabled` flag that the renderer then had to fold back.
+    if (spec.sharing)
+        node.sharing = spec.sharing;
     if (spec.hiddenFields)
         node.hiddenFields = spec.hiddenFields;
     if (spec.fieldOrder)

package/dist/spec-bridge/index.d.ts

@@ -9,5 +9,3 @@ export { SpecBridge } from './SpecBridge';
 export type { BridgeContext, BridgeFn, ObjectDefLite } from './types';
 export { bridgeListView } from './bridges/list-view';
 export { bridgeFormView } from './bridges/form-view';
-export { bridgePage } from './bridges/page';
-export { bridgeDashboard } from './bridges/dashboard';

package/dist/spec-bridge/index.js

@@ -8,5 +8,3 @@
 export { SpecBridge } from './SpecBridge';
 export { bridgeListView } from './bridges/list-view';
 export { bridgeFormView } from './bridges/form-view';
-export { bridgePage } from './bridges/page';
-export { bridgeDashboard } from './bridges/dashboard';

package/dist/utils/error-message.d.ts

@@ -12,6 +12,37 @@
  * usable can be extracted, so callers fall back to a generic localized string.
  */
 export declare function extractWriteErrorMessage(err: unknown): string | null;
+/** One field the server rejected, normalised for `form.setError`. */
+export interface WriteFieldError {
+    /** Field name, matching the form control's `name`. */
+    field: string;
+    /** Human-readable reason, already localized by the server when it can be. */
+    message: string;
+}
+/**
+ * Per-field errors from a rejected write, or `null` when the failure was not
+ * field-scoped.
+ *
+ * The server has always sent these. `@objectstack/objectql`'s validators throw
+ * `{ code: 'VALIDATION_FAILED', fields: [{ field, code, message }] }`, and both
+ * the REST layer and the runtime dispatcher serve that as a 400 with `fields[]`
+ * intact. What was missing was the last hop: every form caught the rejection,
+ * showed one generic toast, and dropped `fields[]` on the floor — so a user told
+ * "Validation failed" had to guess WHICH input was wrong, on a surface that
+ * already knows how to mark it.
+ *
+ * Reads three shapes, because the error can arrive from either side of the
+ * adapter boundary:
+ *   - `validationErrors` — a `ValidationError` from `@object-ui/data-objectstack`;
+ *   - `details.fields` — the raw `@objectstack/client` error, whose `details`
+ *     falls back to the whole response body;
+ *   - `fields` — a hand-rolled error of the same shape (the server duck-types
+ *     these identically, so we do too).
+ *
+ * Entries without a usable `field` are dropped rather than guessed at: a wrong
+ * mark on an innocent input is worse than the generic toast we already show.
+ */
+export declare function extractFieldErrors(err: unknown): WriteFieldError[] | null;
 /**
  * True when a failed write was rejected for authorization reasons (HTTP 403 /
  * `PERMISSION_DENIED` / `FORBIDDEN` / a row-level-security denial). Lets a

package/dist/utils/error-message.js

@@ -68,6 +68,55 @@ export function extractWriteErrorMessage(err) {
         .trim();
     return clean || null;
 }
+/**
+ * Per-field errors from a rejected write, or `null` when the failure was not
+ * field-scoped.
+ *
+ * The server has always sent these. `@objectstack/objectql`'s validators throw
+ * `{ code: 'VALIDATION_FAILED', fields: [{ field, code, message }] }`, and both
+ * the REST layer and the runtime dispatcher serve that as a 400 with `fields[]`
+ * intact. What was missing was the last hop: every form caught the rejection,
+ * showed one generic toast, and dropped `fields[]` on the floor — so a user told
+ * "Validation failed" had to guess WHICH input was wrong, on a surface that
+ * already knows how to mark it.
+ *
+ * Reads three shapes, because the error can arrive from either side of the
+ * adapter boundary:
+ *   - `validationErrors` — a `ValidationError` from `@object-ui/data-objectstack`;
+ *   - `details.fields` — the raw `@objectstack/client` error, whose `details`
+ *     falls back to the whole response body;
+ *   - `fields` — a hand-rolled error of the same shape (the server duck-types
+ *     these identically, so we do too).
+ *
+ * Entries without a usable `field` are dropped rather than guessed at: a wrong
+ * mark on an innocent input is worse than the generic toast we already show.
+ */
+export function extractFieldErrors(err) {
+    const e = err;
+    if (!e || typeof e !== 'object')
+        return null;
+    const raw = (Array.isArray(e.validationErrors) && e.validationErrors) ||
+        (Array.isArray(e.details?.fields) && e.details.fields) ||
+        (Array.isArray(e.fields) && e.fields) ||
+        null;
+    if (!raw || !Array.isArray(raw))
+        return null;
+    const out = [];
+    for (const entry of raw) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const rec = entry;
+        const field = firstString(rec.field, rec.name, rec.path);
+        if (!field)
+            continue;
+        // `code` is the machine enum (`required`, `invalid_option`, …). It is a
+        // last resort only: the server builds `message` to be shown verbatim, and
+        // an untranslated enum in the UI reads as a bug.
+        const message = firstString(rec.message, rec.error, rec.code) ?? '';
+        out.push({ field, message });
+    }
+    return out.length > 0 ? out : null;
+}
 /**
  * True when a failed write was rejected for authorization reasons (HTTP 403 /
  * `PERMISSION_DENIED` / `FORBIDDEN` / a row-level-security denial). Lets a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/react",
-  "version": "16.1.0",
+  "version": "17.1.0",
   "type": "module",
   "license": "MIT",
   "description": "React bindings and SchemaRenderer component for Object UI",
@@ -24,12 +24,12 @@
     }
   },
   "dependencies": {
-    "@objectstack/spec": "^16.0.0-rc.0",
-    "react-hook-form": "^7.82.0",
-    "@object-ui/core": "16.1.0",
-    "@object-ui/data-objectstack": "16.1.0",
-    "@object-ui/i18n": "16.1.0",
-    "@object-ui/types": "16.1.0"
+    "@objectstack/spec": "^17.0.0-rc.0",
+    "react-hook-form": "^7.83.0",
+    "@object-ui/core": "17.1.0",
+    "@object-ui/data-objectstack": "17.1.0",
+    "@object-ui/i18n": "17.1.0",
+    "@object-ui/types": "17.1.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",