@object-ui/react 3.1.4 → 3.3.0

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @object-ui/react@3.1.4 build /home/runner/work/objectui/objectui/packages/react
+> @object-ui/react@3.3.0 build /home/runner/work/objectui/objectui/packages/react
 > tsc
 

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @object-ui/react
 
+## 3.3.0
+
+### Patch Changes
+
+- @object-ui/types@3.3.0
+- @object-ui/core@3.3.0
+- @object-ui/i18n@3.3.0
+
+## 3.2.0
+
+### Patch Changes
+
+- @object-ui/types@3.2.0
+- @object-ui/core@3.2.0
+- @object-ui/i18n@3.2.0
+
+## 3.1.5
+
+### Patch Changes
+
+- Updated dependencies [cfe0596]
+  - @object-ui/i18n@3.1.5
+  - @object-ui/types@3.1.5
+  - @object-ui/core@3.1.5
+
 ## 3.1.4
 
 ### Patch Changes

package/README.md

@@ -120,13 +120,18 @@ Access server discovery information including preview mode detection:
 import { useDiscovery } from '@object-ui/react'
 
 function MyComponent() {
-  const { discovery, isLoading, isAuthEnabled } = useDiscovery()
+  const { discovery, isLoading, isAuthEnabled, isAiEnabled } = useDiscovery()
   
   // Check if the server is in preview mode
   if (discovery?.mode === 'preview') {
     console.log('Preview mode active:', discovery.previewMode)
   }
 
+  // Check if AI service is available
+  if (isAiEnabled) {
+    console.log('AI service route:', discovery?.services?.ai?.route)
+  }
+
   return <div>Server: {discovery?.name}</div>
 }
 ```
@@ -139,7 +144,7 @@ function MyComponent() {
 | `version` | `string` | Server version |
 | `mode` | `string` | Runtime mode (e.g. `'development'`, `'production'`, `'preview'`) |
 | `previewMode` | `object` | Preview mode configuration (present when mode is `'preview'`) |
-| `services` | `object` | Service availability status (auth, data, metadata) |
+| `services` | `object` | Service availability status (auth, data, metadata, ai) |
 | `capabilities` | `string[]` | API capabilities |
 
 The `previewMode` object contains:

package/dist/SchemaRenderer.js

@@ -56,7 +56,7 @@ export class SchemaErrorBoundary extends Component {
     render() {
         if (this.state.hasError && this.state.error) {
             const error = this.state.error;
-            const isDev = process.env.NODE_ENV !== 'production';
+            const isDev = globalThis.process?.env?.NODE_ENV !== 'production';
             const objuiError = isObjectUIError(error) ? error : null;
             return (_jsxs("div", { className: "p-4 border border-orange-400 rounded bg-orange-50 text-orange-700 my-2", role: "alert", children: [_jsxs("p", { className: "font-medium", children: ["Component", this.props.componentType ? ` "${this.props.componentType}"` : '', " failed to render"] }), _jsx("p", { className: "text-sm mt-1", children: error.message }), isDev && objuiError?.code && (_jsxs("p", { className: "text-xs mt-1 text-orange-500", children: ["Error code: ", objuiError.code, objuiError.details?.suggestion ? (_jsxs("span", { className: "block mt-0.5", children: ["\uD83D\uDCA1 ", String(objuiError.details.suggestion)] })) : null] })), _jsx("button", { onClick: this.handleRetry, className: "mt-2 text-sm underline hover:no-underline", children: "Retry" })] }));
         }
@@ -137,7 +137,7 @@ export const SchemaRenderer = forwardRef(({ schema, ...props }, _ref) => {
     if (!Component) {
         debugLog('schema', 'Component not found in registry', { type: evaluatedSchema.type });
         const errorInfo = ERROR_CODES['OBJUI-001'];
-        return (_jsxs("div", { className: "p-4 border border-red-500 rounded text-red-500 bg-red-50 my-2", role: "alert", children: [_jsxs("p", { className: "font-medium", children: ["Unknown component type: ", _jsx("strong", { children: evaluatedSchema.type })] }), process.env.NODE_ENV !== 'production' && (_jsxs("p", { className: "text-xs mt-1", children: ["\uD83D\uDCA1 ", errorInfo.suggestion, " (OBJUI-001)"] })), _jsx("pre", { className: "text-xs mt-2 overflow-auto", children: JSON.stringify(evaluatedSchema, null, 2) })] }));
+        return (_jsxs("div", { className: "p-4 border border-red-500 rounded text-red-500 bg-red-50 my-2", role: "alert", children: [_jsxs("p", { className: "font-medium", children: ["Unknown component type: ", _jsx("strong", { children: evaluatedSchema.type })] }), globalThis.process?.env?.NODE_ENV !== 'production' && (_jsxs("p", { className: "text-xs mt-1", children: ["\uD83D\uDCA1 ", errorInfo.suggestion, " (OBJUI-001)"] })), _jsx("pre", { className: "text-xs mt-2 overflow-auto", children: JSON.stringify(evaluatedSchema, null, 2) })] }));
     }
     // Note: We don't forward the ref to the Component because components in the registry
     // may not support refs. The SchemaRenderer itself can still receive refs for its own use.

package/dist/components/form/FieldFactory.js

@@ -1,11 +1,14 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { resolveI18nLabel } from '../../utils/i18n';
+import { createSafeTranslation } from '@object-ui/i18n';
+const useSafeTranslation = createSafeTranslation({ 'common.selectOption': 'Select an option' }, 'common.selectOption');
 /**
  * FieldFactory component that renders different input types based on
  * the widget property or field type
  */
 export const FieldFactory = ({ field, methods, disabled = false, }) => {
     const { register, formState: { errors } } = methods;
+    const { t } = useSafeTranslation();
     // Cast to extended field for properties not in base schema
     const extendedField = field;
     // Determine the widget type
@@ -61,7 +64,7 @@ export const FieldFactory = ({ field, methods, disabled = false, }) => {
             return renderField(_jsxs("select", { id: fieldName, disabled: disabled, multiple: extendedField.multiple, className: "w-full px-3 py-2 border border-gray-300 rounded-md shadow-sm focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-blue-500 disabled:bg-gray-100 disabled:cursor-not-allowed", ...register(fieldName, {
                     required: field.required ? `${fieldLabel || fieldName} is required` : false,
                     setValueAs: handleMultipleSelectValue,
-                }), children: [!extendedField.multiple && _jsx("option", { value: "", children: fieldPlaceholder || 'Select an option' }), extendedField.options?.map((option) => (_jsx("option", { value: option.value, disabled: option.disabled, children: option.label }, option.value)))] }));
+                }), children: [!extendedField.multiple && _jsx("option", { value: "", children: fieldPlaceholder || t('common.selectOption') }), extendedField.options?.map((option) => (_jsx("option", { value: option.value, disabled: option.disabled, children: option.label }, option.value)))] }));
         case 'date':
             return renderField(_jsx("input", { id: fieldName, type: "date", placeholder: fieldPlaceholder, disabled: disabled, className: "w-full px-3 py-2 border border-gray-300 rounded-md shadow-sm focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-blue-500 disabled:bg-gray-100 disabled:cursor-not-allowed", ...register(fieldName, {
                     required: field.required ? `${fieldLabel || fieldName} is required` : false,
@@ -118,7 +121,7 @@ export const FieldFactory = ({ field, methods, disabled = false, }) => {
             return renderField(_jsxs("select", { id: fieldName, disabled: disabled, multiple: extendedField.multiple, className: "w-full px-3 py-2 border border-gray-300 rounded-md shadow-sm focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-blue-500 disabled:bg-gray-100 disabled:cursor-not-allowed", ...register(fieldName, {
                     required: field.required ? `${fieldLabel || fieldName} is required` : false,
                     setValueAs: handleMultipleSelectValue,
-                }), children: [!extendedField.multiple && _jsx("option", { value: "", children: fieldPlaceholder || 'Select an option' }), extendedField.options?.map((option) => (_jsx("option", { value: option.value, disabled: option.disabled, children: option.label }, option.value)))] }));
+                }), children: [!extendedField.multiple && _jsx("option", { value: "", children: fieldPlaceholder || t('common.selectOption') }), extendedField.options?.map((option) => (_jsx("option", { value: option.value, disabled: option.disabled, children: option.label }, option.value)))] }));
         case 'user':
         case 'owner':
             return renderField(_jsxs("select", { id: fieldName, disabled: disabled, multiple: extendedField.multiple, className: "w-full px-3 py-2 border border-gray-300 rounded-md shadow-sm focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-blue-500 disabled:bg-gray-100 disabled:cursor-not-allowed", ...register(fieldName, {

package/dist/hooks/index.d.ts

@@ -32,3 +32,4 @@ export * from './useSchemaPersistence';
 export * from './useGlobalUndo';
 export * from './useDebugMode';
 export * from './useActionEngine';
+export * from './useDataRefresh';

package/dist/hooks/index.js

@@ -32,3 +32,4 @@ export * from './useSchemaPersistence';
 export * from './useGlobalUndo';
 export * from './useDebugMode';
 export * from './useActionEngine';
+export * from './useDataRefresh';

package/dist/hooks/useDataRefresh.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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 { DataSource } from '@object-ui/types';
+/**
+ * Reusable hook that encapsulates the data-refresh pattern:
+ *  1. A numeric `refreshKey` that triggers React effect re-runs when incremented.
+ *  2. An imperative `refresh()` function to trigger a re-fetch on demand.
+ *  3. Auto-subscription to `DataSource.onMutation()` — if the DataSource
+ *     implements the optional mutation event bus, the hook auto-refreshes
+ *     whenever a mutation occurs on the matching `objectName`.
+ *
+ * @param dataSource - The DataSource instance (may be undefined during initial render)
+ * @param objectName - The resource/object name to watch for mutations
+ * @returns `{ refreshKey, refresh }` — include `refreshKey` in your effect deps
+ *
+ * @example
+ * ```tsx
+ * const { refreshKey, refresh } = useDataRefresh(dataSource, schema.objectName);
+ *
+ * useEffect(() => {
+ *   dataSource.find(objectName, params).then(setData);
+ * }, [objectName, refreshKey]);
+ *
+ * // Or trigger manually:
+ * <button onClick={refresh}>Refresh</button>
+ * ```
+ */
+export declare function useDataRefresh(dataSource: DataSource | undefined, objectName: string | undefined): {
+    refreshKey: number;
+    refresh: () => void;
+};

package/dist/hooks/useDataRefresh.js

@@ -0,0 +1,50 @@
+/**
+ * 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 { useState, useCallback, useEffect } from 'react';
+/**
+ * Reusable hook that encapsulates the data-refresh pattern:
+ *  1. A numeric `refreshKey` that triggers React effect re-runs when incremented.
+ *  2. An imperative `refresh()` function to trigger a re-fetch on demand.
+ *  3. Auto-subscription to `DataSource.onMutation()` — if the DataSource
+ *     implements the optional mutation event bus, the hook auto-refreshes
+ *     whenever a mutation occurs on the matching `objectName`.
+ *
+ * @param dataSource - The DataSource instance (may be undefined during initial render)
+ * @param objectName - The resource/object name to watch for mutations
+ * @returns `{ refreshKey, refresh }` — include `refreshKey` in your effect deps
+ *
+ * @example
+ * ```tsx
+ * const { refreshKey, refresh } = useDataRefresh(dataSource, schema.objectName);
+ *
+ * useEffect(() => {
+ *   dataSource.find(objectName, params).then(setData);
+ * }, [objectName, refreshKey]);
+ *
+ * // Or trigger manually:
+ * <button onClick={refresh}>Refresh</button>
+ * ```
+ */
+export function useDataRefresh(dataSource, objectName) {
+    const [refreshKey, setRefreshKey] = useState(0);
+    const refresh = useCallback(() => {
+        setRefreshKey(k => k + 1);
+    }, []);
+    // Auto-subscribe to DataSource mutation events
+    useEffect(() => {
+        if (!dataSource?.onMutation || !objectName)
+            return;
+        const unsub = dataSource.onMutation((event) => {
+            if (event.resource === objectName) {
+                setRefreshKey(k => k + 1);
+            }
+        });
+        return unsub;
+    }, [dataSource, objectName]);
+    return { refreshKey, refresh };
+}

package/dist/hooks/useDiscovery.d.ts

@@ -42,6 +42,13 @@ export interface DiscoveryInfo {
             enabled: boolean;
             status?: 'available' | 'unavailable';
         };
+        /** AI service configuration */
+        ai?: {
+            enabled: boolean;
+            status?: 'available' | 'unavailable';
+            /** AI service endpoint route (e.g. '/api/v1/ai') */
+            route?: string;
+        };
         [key: string]: any;
     };
     /** API capabilities */
@@ -86,4 +93,9 @@ export declare function useDiscovery(): {
      * Defaults to true if discovery data is not available.
      */
     isAuthEnabled: boolean;
+    /**
+     * Check if AI service is enabled and available on the server.
+     * Defaults to false if discovery data is not available.
+     */
+    isAiEnabled: boolean;
 };

package/dist/hooks/useDiscovery.js

@@ -92,5 +92,11 @@ export function useDiscovery() {
          * Defaults to true if discovery data is not available.
          */
         isAuthEnabled: discovery?.services?.auth?.enabled ?? true,
+        /**
+         * Check if AI service is enabled and available on the server.
+         * Defaults to false if discovery data is not available.
+         */
+        isAiEnabled: discovery?.services?.ai?.enabled === true &&
+            discovery?.services?.ai?.status === 'available',
     };
 }

package/dist/hooks/usePerformanceBudget.js

@@ -122,7 +122,7 @@ export function usePerformanceBudget(userBudget = {}) {
             timestamp: Date.now(),
         };
         setViolations((prev) => [...prev, violation]);
-        if (budget.warnOnViolation && process.env.NODE_ENV !== 'production') {
+        if (budget.warnOnViolation && globalThis.process?.env?.NODE_ENV !== 'production') {
             console.warn(`[ObjectUI] Performance budget violated: ${metric} = ${violation.actual} (budget: ${budgetValue})`);
         }
         onViolationRef.current?.(violation);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/react",
-  "version": "3.1.4",
+  "version": "3.3.0",
   "type": "module",
   "license": "MIT",
   "description": "React bindings and SchemaRenderer component for Object UI",
@@ -24,11 +24,11 @@
     }
   },
   "dependencies": {
-    "@objectstack/spec": "^3.2.9",
-    "react-hook-form": "^7.72.0",
-    "@object-ui/core": "3.1.4",
-    "@object-ui/i18n": "3.1.4",
-    "@object-ui/types": "3.1.4"
+    "@objectstack/spec": "^4.0.3",
+    "react-hook-form": "^7.72.1",
+    "@object-ui/core": "3.3.0",
+    "@object-ui/i18n": "3.3.0",
+    "@object-ui/types": "3.3.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
@@ -37,7 +37,7 @@
   "devDependencies": {
     "@types/react": "19.2.14",
     "@types/react-dom": "19.2.3",
-    "typescript": "^5.9.3"
+    "typescript": "^6.0.2"
   },
   "scripts": {
     "build": "tsc",

package/src/SchemaRenderer.tsx

@@ -72,7 +72,7 @@ export class SchemaErrorBoundary extends Component<
   render() {
     if (this.state.hasError && this.state.error) {
       const error = this.state.error;
-      const isDev = process.env.NODE_ENV !== 'production';
+      const isDev = (globalThis as any).process?.env?.NODE_ENV !== 'production';
       const objuiError = isObjectUIError(error) ? error as ObjectUIError : null;
 
       return (
@@ -189,7 +189,7 @@ export const SchemaRenderer = forwardRef<any, { schema: SchemaNode } & Record<st
     return (
       <div className="p-4 border border-red-500 rounded text-red-500 bg-red-50 my-2" role="alert">
         <p className="font-medium">Unknown component type: <strong>{evaluatedSchema.type}</strong></p>
-        {process.env.NODE_ENV !== 'production' && (
+        {(globalThis as any).process?.env?.NODE_ENV !== 'production' && (
           <p className="text-xs mt-1">💡 {errorInfo.suggestion} (OBJUI-001)</p>
         )}
         <pre className="text-xs mt-2 overflow-auto">{JSON.stringify(evaluatedSchema, null, 2)}</pre>

package/src/components/form/FieldFactory.tsx

@@ -10,6 +10,12 @@ import React from 'react';
 import { UseFormReturn } from 'react-hook-form';
 import type { FormField } from '@objectstack/spec/ui';
 import { resolveI18nLabel } from '../../utils/i18n';
+import { createSafeTranslation } from '@object-ui/i18n';
+
+const useSafeTranslation = createSafeTranslation(
+  { 'common.selectOption': 'Select an option' },
+  'common.selectOption',
+);
 
 /**
  * Extended form field with additional properties for complex widgets
@@ -51,6 +57,7 @@ export const FieldFactory: React.FC<FieldFactoryProps> = ({
   disabled = false,
 }) => {
   const { register, formState: { errors } } = methods;
+  const { t } = useSafeTranslation();
   
   // Cast to extended field for properties not in base schema
   const extendedField = field as ExtendedFormField;
@@ -193,7 +200,7 @@ export const FieldFactory: React.FC<FieldFactoryProps> = ({
             setValueAs: handleMultipleSelectValue,
           })}
         >
-          {!extendedField.multiple && <option value="">{fieldPlaceholder || 'Select an option'}</option>}
+          {!extendedField.multiple && <option value="">{fieldPlaceholder || t('common.selectOption')}</option>}
           {extendedField.options?.map((option) => (
             <option key={option.value} value={option.value} disabled={option.disabled}>
               {option.label}
@@ -400,7 +407,7 @@ export const FieldFactory: React.FC<FieldFactoryProps> = ({
             setValueAs: handleMultipleSelectValue,
           })}
         >
-          {!extendedField.multiple && <option value="">{fieldPlaceholder || 'Select an option'}</option>}
+          {!extendedField.multiple && <option value="">{fieldPlaceholder || t('common.selectOption')}</option>}
           {extendedField.options?.map((option) => (
             <option key={option.value} value={option.value} disabled={option.disabled}>
               {option.label}

package/src/hooks/__tests__/useDataRefresh.test.ts

@@ -0,0 +1,115 @@
+/**
+ * ObjectUI — useDataRefresh Tests
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * Tests for the reusable data-refresh hook (P1/P2).
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import { useDataRefresh } from '../useDataRefresh';
+
+describe('useDataRefresh', () => {
+  it('should return refreshKey=0 and a refresh function', () => {
+    const { result } = renderHook(() => useDataRefresh(undefined, undefined));
+
+    expect(result.current.refreshKey).toBe(0);
+    expect(typeof result.current.refresh).toBe('function');
+  });
+
+  it('should increment refreshKey when refresh() is called', () => {
+    const { result } = renderHook(() => useDataRefresh(undefined, 'contacts'));
+
+    act(() => {
+      result.current.refresh();
+    });
+
+    expect(result.current.refreshKey).toBe(1);
+
+    act(() => {
+      result.current.refresh();
+    });
+
+    expect(result.current.refreshKey).toBe(2);
+  });
+
+  it('should auto-subscribe to DataSource.onMutation() when available', () => {
+    let listener: ((event: any) => void) | null = null;
+    const unsub = vi.fn();
+    const ds: any = {
+      onMutation: vi.fn((cb: any) => {
+        listener = cb;
+        return unsub;
+      }),
+    };
+
+    const { result } = renderHook(() => useDataRefresh(ds, 'contacts'));
+
+    expect(ds.onMutation).toHaveBeenCalledOnce();
+
+    // Simulate a mutation on the same resource
+    act(() => {
+      listener?.({ type: 'create', resource: 'contacts' });
+    });
+
+    expect(result.current.refreshKey).toBe(1);
+  });
+
+  it('should NOT increment refreshKey for mutations on a different resource', () => {
+    let listener: ((event: any) => void) | null = null;
+    const ds: any = {
+      onMutation: vi.fn((cb: any) => {
+        listener = cb;
+        return vi.fn();
+      }),
+    };
+
+    const { result } = renderHook(() => useDataRefresh(ds, 'contacts'));
+
+    act(() => {
+      listener?.({ type: 'create', resource: 'accounts' });
+    });
+
+    expect(result.current.refreshKey).toBe(0);
+  });
+
+  it('should unsubscribe on unmount', () => {
+    const unsub = vi.fn();
+    const ds: any = {
+      onMutation: vi.fn(() => unsub),
+    };
+
+    const { unmount } = renderHook(() => useDataRefresh(ds, 'contacts'));
+
+    expect(unsub).not.toHaveBeenCalled();
+
+    unmount();
+
+    expect(unsub).toHaveBeenCalledOnce();
+  });
+
+  it('should work without onMutation (backward compatible)', () => {
+    const ds: any = {
+      find: vi.fn(),
+    };
+
+    const { result } = renderHook(() => useDataRefresh(ds, 'contacts'));
+
+    expect(result.current.refreshKey).toBe(0);
+    // Should not throw
+    act(() => {
+      result.current.refresh();
+    });
+    expect(result.current.refreshKey).toBe(1);
+  });
+
+  it('should skip subscription when objectName is undefined', () => {
+    const ds: any = {
+      onMutation: vi.fn(() => vi.fn()),
+    };
+
+    renderHook(() => useDataRefresh(ds, undefined));
+
+    expect(ds.onMutation).not.toHaveBeenCalled();
+  });
+});

package/src/hooks/__tests__/useDiscovery.test.tsx

@@ -122,6 +122,104 @@ describe('useDiscovery', () => {
     expect(result.current.isAuthEnabled).toBe(false);
   });
 
+  it('isAiEnabled defaults to false when no discovery', async () => {
+    const { result } = renderHook(() => useDiscovery());
+
+    await waitFor(() => {
+      expect(result.current.isLoading).toBe(false);
+    });
+
+    expect(result.current.isAiEnabled).toBe(false);
+  });
+
+  it('isAiEnabled is true when ai service is enabled and available', async () => {
+    const discoveryData = {
+      services: {
+        ai: { enabled: true, status: 'available' as const, route: '/api/v1/ai' },
+      },
+    };
+
+    const dataSource = {
+      getDiscovery: vi.fn().mockResolvedValue(discoveryData),
+    };
+
+    const { result } = renderHook(() => useDiscovery(), {
+      wrapper: createWrapper(dataSource),
+    });
+
+    await waitFor(() => {
+      expect(result.current.isLoading).toBe(false);
+    });
+
+    expect(result.current.isAiEnabled).toBe(true);
+  });
+
+  it('isAiEnabled is false when ai service is enabled but unavailable', async () => {
+    const discoveryData = {
+      services: {
+        ai: { enabled: true, status: 'unavailable' as const },
+      },
+    };
+
+    const dataSource = {
+      getDiscovery: vi.fn().mockResolvedValue(discoveryData),
+    };
+
+    const { result } = renderHook(() => useDiscovery(), {
+      wrapper: createWrapper(dataSource),
+    });
+
+    await waitFor(() => {
+      expect(result.current.isLoading).toBe(false);
+    });
+
+    expect(result.current.isAiEnabled).toBe(false);
+  });
+
+  it('isAiEnabled is false when ai service is disabled', async () => {
+    const discoveryData = {
+      services: {
+        ai: { enabled: false, status: 'available' as const },
+      },
+    };
+
+    const dataSource = {
+      getDiscovery: vi.fn().mockResolvedValue(discoveryData),
+    };
+
+    const { result } = renderHook(() => useDiscovery(), {
+      wrapper: createWrapper(dataSource),
+    });
+
+    await waitFor(() => {
+      expect(result.current.isLoading).toBe(false);
+    });
+
+    expect(result.current.isAiEnabled).toBe(false);
+  });
+
+  it('isAiEnabled is false when ai service has no status', async () => {
+    const discoveryData = {
+      services: {
+        ai: { enabled: true },
+      },
+    };
+
+    const dataSource = {
+      getDiscovery: vi.fn().mockResolvedValue(discoveryData),
+    };
+
+    const { result } = renderHook(() => useDiscovery(), {
+      wrapper: createWrapper(dataSource),
+    });
+
+    await waitFor(() => {
+      expect(result.current.isLoading).toBe(false);
+    });
+
+    expect(result.current.isAiEnabled).toBe(false);
+  });
+
   it('cleans up on unmount (cancelled flag)', async () => {
     let resolveDiscovery: (value: any) => void;
     const discoveryPromise = new Promise((resolve) => {

package/src/hooks/index.ts

@@ -33,3 +33,4 @@ export * from './useSchemaPersistence';
 export * from './useGlobalUndo';
 export * from './useDebugMode';
 export * from './useActionEngine';
+export * from './useDataRefresh';

package/src/hooks/useDataRefresh.ts

@@ -0,0 +1,58 @@
+/**
+ * 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 { useState, useCallback, useEffect } from 'react';
+import type { DataSource } from '@object-ui/types';
+
+/**
+ * Reusable hook that encapsulates the data-refresh pattern:
+ *  1. A numeric `refreshKey` that triggers React effect re-runs when incremented.
+ *  2. An imperative `refresh()` function to trigger a re-fetch on demand.
+ *  3. Auto-subscription to `DataSource.onMutation()` — if the DataSource
+ *     implements the optional mutation event bus, the hook auto-refreshes
+ *     whenever a mutation occurs on the matching `objectName`.
+ *
+ * @param dataSource - The DataSource instance (may be undefined during initial render)
+ * @param objectName - The resource/object name to watch for mutations
+ * @returns `{ refreshKey, refresh }` — include `refreshKey` in your effect deps
+ *
+ * @example
+ * ```tsx
+ * const { refreshKey, refresh } = useDataRefresh(dataSource, schema.objectName);
+ *
+ * useEffect(() => {
+ *   dataSource.find(objectName, params).then(setData);
+ * }, [objectName, refreshKey]);
+ *
+ * // Or trigger manually:
+ * <button onClick={refresh}>Refresh</button>
+ * ```
+ */
+export function useDataRefresh(
+  dataSource: DataSource | undefined,
+  objectName: string | undefined,
+): { refreshKey: number; refresh: () => void } {
+  const [refreshKey, setRefreshKey] = useState(0);
+
+  const refresh = useCallback(() => {
+    setRefreshKey(k => k + 1);
+  }, []);
+
+  // Auto-subscribe to DataSource mutation events
+  useEffect(() => {
+    if (!dataSource?.onMutation || !objectName) return;
+    const unsub = dataSource.onMutation((event) => {
+      if (event.resource === objectName) {
+        setRefreshKey(k => k + 1);
+      }
+    });
+    return unsub;
+  }, [dataSource, objectName]);
+
+  return { refreshKey, refresh };
+}