@object-ui/react 5.0.2 → 5.2.1

package/CHANGELOG.md

@@ -1,5 +1,158 @@
 # @object-ui/react
 
+## 5.2.1
+
+### Patch Changes
+
+- @object-ui/types@5.2.1
+- @object-ui/core@5.2.1
+- @object-ui/i18n@5.2.1
+- @object-ui/data-objectstack@5.2.1
+
+## 5.2.0
+
+### Minor Changes
+
+- b2d1704: feat(cmdk): record search across objects in the Command Palette
+  - New `useRecordSearch` hook in `@object-ui/react` debounces a query, fans out
+    to `dataSource.find(name, { $search, $top })` across candidate objects, and
+    aggregates hits. Race-safe via a monotonic runId; per-object 404s are
+    silently dropped via `Promise.allSettled`.
+  - `CommandPalette` (`@object-ui/app-shell`) now accepts a `dataSource` prop;
+    when supplied, the palette renders a `Records` group at the top with hits
+    scoped to the active app's nav objects. Item `value` embeds the live query
+    so cmdk's client-side filter doesn't hide async results.
+  - Added `console.commandPalette.records` i18n key (`Records` / `记录`).
+
+- 3ebba63: Fix silent blank page on shorthand record deep-links.
+
+  Three related fixes that all addressed the same UX: a user follows a URL
+  shaped `/{object}/{recordId}` and sees a completely blank content area.
+  1. **`useNavigationOverlay` produced the broken URL itself.** When
+     middle-click / Cmd-click opened a gallery card in a new tab and no
+     `onNavigate` was provided, the hook built `/{object}/{id}` — a URL
+     shape that does not match any route in the console route table. The
+     builder now emits the canonical `/{object}/record/{id}`.
+  2. **Shorthand redirect for externally shared links.** Even with the
+     producer fixed, links pasted from email / Slack / older builds
+     still use the shorthand. The console now intercepts
+     `/{:objectName}/:maybeRecordId` and, when the second segment looks
+     like a record id (URL-safe slug ≥ 6 chars, not a reserved keyword),
+     redirects to `/{objectName}/record/{recordId}` preserving query and
+     hash.
+  3. **Visible 404 fallback.** Routes that match nothing at all now
+     render an explicit "Page not found" empty state with a "Go back"
+     action instead of leaving the content area blank. Silent failures
+     are now visible failures.
+
+- aa063db: `useRecordSearch` now orders hits by relevance instead of object-fanout
+  order. Tiers (higher wins):
+  - 110: exact recordId paste
+  - 100: display exactly equals the query
+  - 80: display starts with the query
+  - 60: any token in display starts with the query
+  - 40: display contains the query as a substring
+
+  This makes `⌘K → "Ada"` rank "Ada Lovelace" above "AdvancedTradingAccount"
+  even though Account is queried before Contact in the fanout.
+
+  `RecordSearchHit` gains a `score` field for callers that want to render
+  hint chips, filter low-confidence rows, or further customize ordering.
+
+- 7c7400a: feat(react): dev-mode schema validation in SchemaRenderer
+
+  `SchemaRenderer` now runs the canonical `validateSchema` from
+  `@object-ui/core` on every schema object it renders (deduped per-object
+  via a WeakSet so re-renders don't re-log). Errors are surfaced via a
+  single grouped `console.warn` that includes the offending JSON path,
+  and the host element receives `data-obj-schema-invalid="true"` so apps
+  can hook a visual cue (e.g. red outline) via CSS.
+
+  The entire pass is gated on `process.env.NODE_ENV !== 'production'`
+  and is a no-op in production builds — zero runtime cost shipped to
+  users.
+
+### Patch Changes
+
+- Updated dependencies [de0c5e6]
+- Updated dependencies [9997cae]
+- Updated dependencies [321294c]
+- Updated dependencies [b2d1704]
+- Updated dependencies [0a644f0]
+- Updated dependencies [a3cb88f]
+- Updated dependencies [5425608]
+- Updated dependencies [e919433]
+- Updated dependencies [70b5570]
+- Updated dependencies [d9c3bae]
+- Updated dependencies [d1442e3]
+  - @object-ui/types@5.2.0
+  - @object-ui/data-objectstack@5.2.0
+  - @object-ui/core@5.2.0
+  - @object-ui/i18n@5.2.0
+
+## 5.1.1
+
+### Patch Changes
+
+- @object-ui/types@5.1.1
+- @object-ui/core@5.1.1
+- @object-ui/i18n@5.1.1
+- @object-ui/data-objectstack@5.1.1
+
+## 5.1.0
+
+### Patch Changes
+
+- bd8447d: Three platform-wide detail polish items.
+
+  **Tighter page rhythm**
+  - Outer `PageRenderer` padding `p-4 md:p-6 lg:p-8` → `p-3 md:p-4 lg:p-6`
+    and outer body wrap `space-y-8` → `space-y-6` so list / detail / home
+    pages share the same edge rhythm. Cuts ~16px of edge slack on lg.
+
+  **Highlights KPI treatment**
+  - `HeaderHighlight` now renders numeric / currency / percent / decimal
+    values as KPI numbers (`text-xl md:text-2xl font-semibold tabular-nums`)
+    instead of the uniform `text-sm font-semibold`, so amount / probability
+    / count fields read as headline stats — Salesforce-style key facts.
+
+  **Discussion footer upgrade**
+  - `RecordActivityTimeline` now uses `RichTextCommentInput` (bold / italic /
+    list / code, `@`-mention autocomplete, preview toggle, Send) instead of
+    a bare `<textarea>`.
+  - `DiscussionContext` gains an optional `mentionSuggestions` array that
+    hosts can wire (e.g. team member directory). Falls back to free-text
+    `@mention` when omitted.
+  - `RecordChatterPanel` threads `mentionSuggestions` through both inline
+    and sidebar positions.
+
+- d51a577: feat(platform): Discussion attachments + @mention directory + Reference Rail aside
+  - **Discussion attachments** — `RichTextCommentInput` now accepts an `extraSlot`
+    and a `canSubmitEmpty` flag so hosts can mount the existing
+    `CommentAttachment` composer beneath the editor without forking the toolbar.
+    `RecordActivityTimeline` plumbs the attachments through
+    `DiscussionContext.onUploadAttachments` and submits attachment-only comments.
+  - **@mention directory** — `DiscussionContext` gains a `mentionSuggestions`
+    field; `RecordDetailView` populates it from the host `sys_user` collection so
+    `@` autocomplete in the composer now resolves against real users.
+  - **Reference Rail** — New `record:reference_rail` renderer + a dedicated
+    `aside` region emitted by `buildDefaultPageSchema` whenever a record has
+    ≥ 2 related lists. The rail surfaces a Salesforce/HubSpot-style snapshot
+    of related collections (count badge + top 3 records) on `xl+` viewports.
+  - **Layout** — `PageRenderer`'s structured-layout `<aside>` wrappers now honor
+    `aside.className`, letting schemas attach responsive utilities like
+    `hidden xl:flex` to the rail region.
+
+- Updated dependencies [1976691]
+- Updated dependencies [cf30cc2]
+- Updated dependencies [5b80cfd]
+- Updated dependencies [49b1760]
+- Updated dependencies [c0b236f]
+  - @object-ui/i18n@5.1.0
+  - @object-ui/types@5.1.0
+  - @object-ui/core@5.1.0
+  - @object-ui/data-objectstack@5.1.0
+
 ## 5.0.2
 
 ### Patch Changes

package/dist/SchemaRenderer.js

@@ -7,9 +7,58 @@ import { jsxs as _jsxs, jsx as _jsx, Fragment as _Fragment } from "react/jsx-run
  * LICENSE file in the root directory of this source tree.
  */
 import React, { forwardRef, useContext, useMemo, useEffect, useReducer, useState, Component } from 'react';
-import { ComponentRegistry, ExpressionEvaluator, isObjectUIError, ERROR_CODES, debugLog, debugTime, debugTimeEnd, DebugCollector, } from '@object-ui/core';
+import { ComponentRegistry, ExpressionEvaluator, isObjectUIError, ERROR_CODES, debugLog, debugTime, debugTimeEnd, DebugCollector, validateSchema, } from '@object-ui/core';
 import { SchemaRendererContext } from './context/SchemaRendererContext';
 import { resolveI18nLabel } from './utils/i18n';
+/**
+ * Dev-mode schema validation.
+ *
+ * In development, every schema object is validated exactly once (deduped
+ * via a WeakSet) using the canonical {@link validateSchema} from
+ * `@object-ui/core`. Errors are reported via `console.warn` with the
+ * offending JSON path, and the rendered host element gets a
+ * `data-obj-schema-invalid` attribute so apps can opt into a visual cue
+ * (e.g. red outline) via CSS.
+ *
+ * In production this is a no-op: the validation pass is skipped entirely
+ * and `data-obj-schema-invalid` is never emitted.
+ */
+const __DEV__ = (() => {
+    try {
+        return globalThis.process?.env?.NODE_ENV !== 'production';
+    }
+    catch {
+        return true;
+    }
+})();
+const _validatedSchemas = typeof WeakSet !== 'undefined' ? new WeakSet() : { add() { }, has() { return false; } };
+function validateSchemaOnce(schema) {
+    if (!__DEV__ || !schema || typeof schema !== 'object') {
+        return { valid: true, messages: [] };
+    }
+    if (_validatedSchemas.has(schema)) {
+        // We don't cache the result intentionally — once a schema object has
+        // been logged, we don't re-log on every re-render. Visual invalid flag
+        // still derives from the structural presence of required fields below.
+        return { valid: true, messages: [] };
+    }
+    _validatedSchemas.add(schema);
+    try {
+        const result = validateSchema(schema);
+        if (!result.valid) {
+            const msgs = result.errors.map(e => `${e.path}: ${e.message}`);
+            // eslint-disable-next-line no-console
+            console.warn('[ObjectUI] Invalid schema detected:\n' + msgs.join('\n'), schema);
+            return { valid: false, messages: msgs };
+        }
+    }
+    catch (err) {
+        // Validator itself failed — surface but don't crash render.
+        // eslint-disable-next-line no-console
+        console.warn('[ObjectUI] Schema validator threw:', err);
+    }
+    return { valid: true, messages: [] };
+}
 /**
  * Extract AriaPropsSchema properties from a schema node and convert
  * them to standard HTML ARIA attributes.
@@ -166,6 +215,10 @@ export const SchemaRenderer = forwardRef(({ schema, ...props }, _ref) => {
     // If schema is just a string, render it as text
     if (typeof evaluatedSchema === 'string')
         return _jsx(_Fragment, { children: evaluatedSchema });
+    // Dev-mode validation: log once per schema object, attach visual flag
+    // when invalid. Production path returns { valid: true, messages: [] }
+    // without doing any work.
+    const _validation = __DEV__ ? validateSchemaOnce(schema) : { valid: true, messages: [] };
     debugLog('schema', 'Rendering schema node', { type: evaluatedSchema.type, id: evaluatedSchema.id });
     const Component = ComponentRegistry.get(evaluatedSchema.type);
     if (!Component) {
@@ -214,6 +267,7 @@ export const SchemaRenderer = forwardRef(({ schema, ...props }, _ref) => {
             className: evaluatedSchema.className,
             'data-obj-id': evaluatedSchema.id,
             'data-obj-type': evaluatedSchema.type,
+            ...(__DEV__ && !_validation.valid ? { 'data-obj-schema-invalid': 'true' } : {}),
             ...props
         }) }));
     debugTimeEnd(`render:${evaluatedSchema.type}:${evaluatedSchema.id ?? 'anon'}`);

package/dist/context/DiscussionContext.d.ts

@@ -22,11 +22,32 @@ export interface DiscussionFeedItem {
     type?: string;
     [k: string]: any;
 }
+export interface DiscussionMentionSuggestion {
+    id: string;
+    label: string;
+    avatarUrl?: string;
+}
+export interface DiscussionAttachment {
+    id: string;
+    name: string;
+    size: number;
+    type: string;
+    url?: string;
+    thumbnailUrl?: string;
+}
 export interface DiscussionContextValue {
     items: DiscussionFeedItem[];
-    onAddComment?: (text: string, attachments?: any[]) => void | Promise<void>;
+    onAddComment?: (text: string, attachments?: DiscussionAttachment[]) => void | Promise<void>;
     onAddReply?: (parentId: string, text: string) => void | Promise<void>;
     onToggleReaction?: (itemId: string, reaction: string) => void | Promise<void>;
+    /** Optional list of users (or any mentionable entities) the comment
+     *  input can suggest after the user types `@`. When omitted the input
+     *  falls back to free-text @-mentions without autocompletion. */
+    mentionSuggestions?: DiscussionMentionSuggestion[];
+    /** Optional uploader. When provided, the comment composer renders a
+     *  drag-and-drop attachment panel; returned attachments are passed
+     *  alongside the comment text to `onAddComment`. */
+    onUploadAttachments?: (files: FileList) => Promise<DiscussionAttachment[]>;
     loading?: boolean;
     error?: Error | null;
 }

package/dist/context/DiscussionContext.js

@@ -24,6 +24,8 @@ export const DiscussionContextProvider = ({ children, ...value }) => {
         value.onAddComment,
         value.onAddReply,
         value.onToggleReaction,
+        value.mentionSuggestions,
+        value.onUploadAttachments,
         value.loading,
         value.error,
     ]);

package/dist/hooks/index.d.ts

@@ -34,3 +34,4 @@ export * from './useDebugMode';
 export * from './useActionEngine';
 export * from './useDataRefresh';
 export * from './usePageAssignment';
+export * from './useRecordSearch';

package/dist/hooks/index.js

@@ -34,3 +34,4 @@ export * from './useDebugMode';
 export * from './useActionEngine';
 export * from './useDataRefresh';
 export * from './usePageAssignment';
+export * from './useRecordSearch';

package/dist/hooks/useNavigationOverlay.js

@@ -98,9 +98,14 @@ export function useNavigationOverlay(options) {
                 onNavigate(recordId, 'new_window');
                 return;
             }
-            const viewPath = view ? `/${view}` : '';
+            // Build a URL that matches the AppContent route shape
+            // `:objectName/record/:recordId`. Previously this used
+            // `/{object}/{id}` which is unrouted and produced a silent
+            // blank page when users middle-/Cmd-clicked a gallery card.
             const encodedId = encodeURIComponent(String(recordId));
-            const url = objectName ? `/${objectName}/${encodedId}${viewPath}` : `/${encodedId}${viewPath}`;
+            const url = objectName
+                ? `/${objectName}/record/${encodedId}`
+                : `/${encodedId}`;
             window.open(url, '_blank');
             return;
         }

package/dist/hooks/useRecordSearch.d.ts

@@ -0,0 +1,96 @@
+/**
+ * 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.
+ */
+export interface RecordSearchHit {
+    /** Object name the record belongs to. */
+    objectName: string;
+    /** Human-readable object label (uses `objectDef.label`, falls back to name). */
+    objectLabel: string;
+    /** Stable record identifier (record.id ?? record._id). */
+    recordId: string;
+    /** Resolved display name (via objectDef.titleFormat or fallback chain). */
+    display: string;
+    /** Optional secondary line (e.g. status or email). Always falsy by default. */
+    subtitle?: string;
+    /** Pass-through icon hint from the object def. */
+    icon?: string;
+    /**
+     * Relevance score (higher = better) used to interleave hits across
+     * objects. Stable across runs for the same (query, display) pair.
+     */
+    score: number;
+    /** Raw record payload, for callers that want extra context. */
+    raw: any;
+}
+export interface UseRecordSearchOptions {
+    /** Current query string from the input. The hook debounces internally. */
+    query: string;
+    /** All known object definitions; the hook picks candidates from this list. */
+    objects: any[];
+    /**
+     * The data source to query. When null/undefined the hook returns empty
+     * results without firing any requests.
+     */
+    dataSource: any;
+    /**
+     * Optional whitelist of object names to search (typically derived from the
+     * current app's nav). When non-empty, only these objects are queried — in
+     * the order provided. When omitted, the hook falls back to every object
+     * where `searchable !== false`, capped at `maxObjectsQueried`.
+     */
+    objectNames?: string[];
+    /**
+     * Hard cap on parallel object queries. Defaults to 8. Lower this on
+     * slow backends.
+     */
+    maxObjectsQueried?: number;
+    /** Per-object result cap. Defaults to 3. */
+    topPerObject?: number;
+    /** Min query length before any request fires. Defaults to 2. */
+    minLength?: number;
+    /** Debounce in ms. Defaults to 250. */
+    debounceMs?: number;
+    /** Set to false to disable the hook entirely (returns empty, no requests). */
+    enabled?: boolean;
+    /**
+     * Optional display-name resolver. Defaults to the same `titleFormat`
+     * fallback chain used by app-shell. Pass `getRecordDisplayName` from
+     * `@object-ui/app-shell` to share that implementation exactly.
+     */
+    getDisplayName?: (objectDef: any, record: any) => string;
+}
+export interface UseRecordSearchResult {
+    results: RecordSearchHit[];
+    isSearching: boolean;
+    error?: Error;
+}
+/**
+ * Search records across multiple objects in parallel, fanning out to
+ * `dataSource.find(name, { $search, $top })`. Designed for the Cmd-K
+ * command palette and similar global-search affordances.
+ *
+ * The hook:
+ *
+ *  - Debounces `query` so fast typing doesn't generate one request per
+ *    keystroke.
+ *  - Skips requests when the trimmed query is shorter than `minLength`,
+ *    when `enabled` is false, when `dataSource` is null, or when there are
+ *    no candidate objects.
+ *  - Uses a monotonically-increasing `runId` to discard stale results — if
+ *    the user keeps typing while requests are still in flight, only the
+ *    newest run mutates state.
+ *  - Tolerates per-object failures (404, etc) via `Promise.allSettled`; a
+ *    backend that doesn't know about one object doesn't poison the rest of
+ *    the result set.
+ *
+ * The hook trusts `$search` — backends that silently ignore it would
+ * return top-N records unrelated to the query. The ObjectStack mock + REST
+ * adapters both honor `$search`; if you need to integrate with a backend
+ * that doesn't, set `enabled` to false or wrap the data source to add
+ * `$filter` translation.
+ */
+export declare function useRecordSearch(opts: UseRecordSearchOptions): UseRecordSearchResult;

package/dist/hooks/useRecordSearch.js

@@ -0,0 +1,221 @@
+/**
+ * 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, useMemo, useRef, useState } from 'react';
+/**
+ * Local copy of the display-name resolver used by app-shell. Kept in
+ * `@object-ui/react` so hooks can derive a record's visible label without
+ * pulling in the shell. Mirrors `app-shell/src/utils#getRecordDisplayName`;
+ * the two should stay in sync.
+ */
+function defaultDisplayName(objectDef, record) {
+    const fmt = objectDef?.titleFormat;
+    if (fmt && typeof fmt === 'string') {
+        const rendered = fmt.replace(/\{\{\s*([\w.]+)\s*\}\}/g, (_m, path) => {
+            const v = path.split('.').reduce((acc, k) => (acc == null ? acc : acc[k]), record);
+            return v == null ? '' : String(v);
+        }).trim();
+        if (rendered.length > 0)
+            return rendered;
+    }
+    return (record?.name ||
+        record?.full_name ||
+        record?.fullName ||
+        record?.title ||
+        record?.label ||
+        record?.subject ||
+        record?.id ||
+        record?._id ||
+        'Untitled');
+}
+/**
+ * Relevance score for a single record hit against the query. Higher wins.
+ *
+ * Tiers (designed to be distinct enough to survive small noise):
+ *   100  Exact case-insensitive match on display.
+ *    80  Display starts with the query.
+ *    60  A query-token starts at a word boundary inside the display
+ *        (e.g. "ACME" matches "Acme Corp" or "Globex / ACME").
+ *    40  Substring contains.
+ *     0  No textual evidence — server returned it but we can't justify
+ *        ranking it. Still included so the user can see what came back.
+ *
+ * The hook also nudges score by recordId equality (exact id paste) so
+ * "paste an id, hit enter" stays the top hit.
+ */
+function scoreHit(query, display, recordId) {
+    if (!query)
+        return 0;
+    const q = query.toLowerCase();
+    const d = (display || '').toLowerCase();
+    const id = (recordId || '').toLowerCase();
+    if (id === q)
+        return 110; // exact id wins everything
+    if (d === q)
+        return 100;
+    if (d.startsWith(q))
+        return 80;
+    // Word-boundary start: split on common separators.
+    const tokens = d.split(/[\s_\-/.,:;()[\]]+/).filter(Boolean);
+    if (tokens.some((tok) => tok.startsWith(q)))
+        return 60;
+    if (d.includes(q))
+        return 40;
+    return 0;
+}
+/**
+ * Search records across multiple objects in parallel, fanning out to
+ * `dataSource.find(name, { $search, $top })`. Designed for the Cmd-K
+ * command palette and similar global-search affordances.
+ *
+ * The hook:
+ *
+ *  - Debounces `query` so fast typing doesn't generate one request per
+ *    keystroke.
+ *  - Skips requests when the trimmed query is shorter than `minLength`,
+ *    when `enabled` is false, when `dataSource` is null, or when there are
+ *    no candidate objects.
+ *  - Uses a monotonically-increasing `runId` to discard stale results — if
+ *    the user keeps typing while requests are still in flight, only the
+ *    newest run mutates state.
+ *  - Tolerates per-object failures (404, etc) via `Promise.allSettled`; a
+ *    backend that doesn't know about one object doesn't poison the rest of
+ *    the result set.
+ *
+ * The hook trusts `$search` — backends that silently ignore it would
+ * return top-N records unrelated to the query. The ObjectStack mock + REST
+ * adapters both honor `$search`; if you need to integrate with a backend
+ * that doesn't, set `enabled` to false or wrap the data source to add
+ * `$filter` translation.
+ */
+export function useRecordSearch(opts) {
+    const { query, objects, dataSource, objectNames, maxObjectsQueried = 8, topPerObject = 3, minLength = 2, debounceMs = 250, enabled = true, getDisplayName = defaultDisplayName, } = opts;
+    const [results, setResults] = useState([]);
+    const [isSearching, setIsSearching] = useState(false);
+    const [error, setError] = useState(undefined);
+    // 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.
+    const candidates = useMemo(() => {
+        if (!Array.isArray(objects) || objects.length === 0)
+            return [];
+        let pool = objects;
+        if (Array.isArray(objectNames) && objectNames.length > 0) {
+            const byName = new Map();
+            for (const obj of objects) {
+                const name = obj?.name;
+                if (typeof name === 'string')
+                    byName.set(name, obj);
+            }
+            pool = objectNames
+                .map((n) => byName.get(n))
+                .filter((obj) => obj != null);
+        }
+        else {
+            pool = objects.filter((o) => o?.searchable !== false);
+        }
+        return pool.slice(0, maxObjectsQueried);
+    }, [objects, objectNames, maxObjectsQueried]);
+    const candidateSignature = useMemo(() => {
+        return candidates.map((o) => `${o?.name}:${o?.titleField ?? ''}`).join('|');
+    }, [candidates]);
+    // Run ID for racing-request guarding. Stable across renders.
+    const runIdRef = useRef(0);
+    useEffect(() => {
+        if (!enabled || !dataSource || candidates.length === 0) {
+            setResults([]);
+            setIsSearching(false);
+            setError(undefined);
+            return;
+        }
+        const trimmed = (query ?? '').trim();
+        if (trimmed.length < minLength) {
+            setResults([]);
+            setIsSearching(false);
+            setError(undefined);
+            return;
+        }
+        const myRunId = ++runIdRef.current;
+        setIsSearching(true);
+        setError(undefined);
+        const timer = setTimeout(() => {
+            // Skip if a newer run started during the debounce window.
+            if (runIdRef.current !== myRunId)
+                return;
+            const requests = candidates.map((obj) => Promise.resolve()
+                .then(() => dataSource.find(obj.name, {
+                $search: trimmed,
+                $top: topPerObject,
+            }))
+                .then((res) => ({ obj, res, err: null }))
+                .catch((err) => ({ obj, res: null, err })));
+            Promise.allSettled(requests).then((settled) => {
+                // Discard if a newer run started while we were waiting.
+                if (runIdRef.current !== myRunId)
+                    return;
+                const hits = [];
+                let lastError;
+                for (const s of settled) {
+                    if (s.status !== 'fulfilled')
+                        continue;
+                    const { obj, res, err } = s.value;
+                    if (err) {
+                        // Tolerate 404 / object_not_found / similar; only surface the
+                        // 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')
+                            continue;
+                        lastError = err instanceof Error ? err : new Error(String(err));
+                        continue;
+                    }
+                    const rows = Array.isArray(res?.data)
+                        ? res.data
+                        : Array.isArray(res)
+                            ? res
+                            : [];
+                    for (const record of rows.slice(0, topPerObject)) {
+                        const recordId = record?.id ?? record?._id;
+                        if (recordId == null)
+                            continue;
+                        const display = getDisplayName(obj, record);
+                        hits.push({
+                            objectName: obj.name,
+                            objectLabel: typeof obj.label === 'string' && obj.label.length > 0
+                                ? obj.label
+                                : obj.name,
+                            recordId: String(recordId),
+                            display,
+                            icon: obj?.icon,
+                            score: scoreHit(trimmed, display, String(recordId)),
+                            raw: record,
+                        });
+                    }
+                }
+                // Stable sort by score desc, then by original (object-fanout)
+                // order so ties preserve the upstream candidate ordering.
+                hits.sort((a, b) => b.score - a.score);
+                setResults(hits);
+                setIsSearching(false);
+                setError(lastError);
+            });
+        }, debounceMs);
+        return () => {
+            clearTimeout(timer);
+        };
+    }, [
+        query,
+        enabled,
+        dataSource,
+        candidateSignature,
+        topPerObject,
+        minLength,
+        debounceMs,
+        getDisplayName,
+    ]);
+    return { results, isSearching, error };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/react",
-  "version": "5.0.2",
+  "version": "5.2.1",
   "type": "module",
   "license": "MIT",
   "description": "React bindings and SchemaRenderer component for Object UI",
@@ -26,10 +26,10 @@
   "dependencies": {
     "@objectstack/spec": "^4.0.5",
     "react-hook-form": "^7.76.0",
-    "@object-ui/core": "5.0.2",
-    "@object-ui/data-objectstack": "5.0.2",
-    "@object-ui/i18n": "5.0.2",
-    "@object-ui/types": "5.0.2"
+    "@object-ui/core": "5.2.1",
+    "@object-ui/data-objectstack": "5.2.1",
+    "@object-ui/i18n": "5.2.1",
+    "@object-ui/types": "5.2.1"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",