@object-ui/react 0.3.1 → 2.0.0

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

@@ -0,0 +1,86 @@
+/**
+ * Tests for useExpression and useCondition hooks
+ */
+
+import { describe, it, expect } from 'vitest';
+import { renderHook } from '@testing-library/react';
+import { useExpression, useCondition } from '../useExpression';
+
+describe('useExpression', () => {
+  it('returns string value directly for non-expression strings', () => {
+    const { result } = renderHook(() => useExpression('hello'));
+
+    expect(result.current).toBe('hello');
+  });
+
+  it('returns number value directly', () => {
+    const { result } = renderHook(() => useExpression(42));
+
+    expect(result.current).toBe(42);
+  });
+
+  it('returns boolean value directly', () => {
+    const { result } = renderHook(() => useExpression(true));
+
+    expect(result.current).toBe(true);
+  });
+
+  it('returns null for null expressions', () => {
+    const { result } = renderHook(() => useExpression(null));
+
+    expect(result.current).toBeNull();
+  });
+
+  it('returns undefined for undefined expressions', () => {
+    const { result } = renderHook(() => useExpression(undefined));
+
+    expect(result.current).toBeUndefined();
+  });
+
+  it('evaluates expressions with ${...} syntax', () => {
+    const context = { data: { name: 'John' } };
+    const { result } = renderHook(() =>
+      useExpression('${data.name}', context),
+    );
+
+    expect(result.current).toBe('John');
+  });
+
+  it('evaluates expressions with context data', () => {
+    const context = { data: { age: 25 } };
+    const { result } = renderHook(() =>
+      useExpression('${data.age > 18}', context),
+    );
+
+    expect(result.current).toBe(true);
+  });
+});
+
+describe('useCondition', () => {
+  it('returns true for boolean true', () => {
+    const { result } = renderHook(() => useCondition(true));
+
+    expect(result.current).toBe(true);
+  });
+
+  it('returns false for boolean false', () => {
+    const { result } = renderHook(() => useCondition(false));
+
+    expect(result.current).toBe(false);
+  });
+
+  it('returns true for undefined', () => {
+    const { result } = renderHook(() => useCondition(undefined));
+
+    expect(result.current).toBe(true);
+  });
+
+  it('evaluates string conditions with context', () => {
+    const context = { data: { status: 'active' } };
+    const { result } = renderHook(() =>
+      useCondition('${data.status === "active"}', context),
+    );
+
+    expect(result.current).toBe(true);
+  });
+});

package/src/hooks/index.ts

@@ -8,4 +8,9 @@
 
 export * from './useExpression';
 export * from './useActionRunner';
+export * from './useNavigationOverlay';
+export * from './usePageVariables';
+export * from './useViewData';
+export * from './useDynamicApp';
+export * from './useDiscovery';
 

package/src/hooks/useActionRunner.ts

@@ -7,36 +7,74 @@
  */
 
 import { useState, useCallback, useMemo } from 'react';
-import { ActionRunner, type ActionContext, type ActionResult } from '@object-ui/core';
+import {
+  ActionRunner,
+  type ActionContext,
+  type ActionDef,
+  type ActionResult,
+  type ConfirmationHandler,
+  type ToastHandler,
+  type ModalHandler,
+  type NavigationHandler,
+} from '@object-ui/core';
+
+export interface UseActionRunnerOptions {
+  context?: ActionContext;
+  /** Custom confirmation handler — wire to Shadcn AlertDialog or similar */
+  onConfirm?: ConfirmationHandler;
+  /** Custom toast handler — wire to Sonner or similar */
+  onToast?: ToastHandler;
+  /** Custom modal handler — render modals in response to modal actions */
+  onModal?: ModalHandler;
+  /** Custom navigation handler — SPA-aware routing */
+  onNavigate?: NavigationHandler;
+}
 
 /**
- * Hook for executing actions with loading state
+ * Hook for executing actions with loading state, typed with ActionDef.
  * 
  * @example
  * ```tsx
- * const { execute, loading, error, result } = useActionRunner({ data: formData });
+ * const { execute, loading, error, result } = useActionRunner({
+ *   context: { data: formData },
+ *   onToast: (msg, opts) => toast[opts?.type || 'info'](msg),
+ * });
  * 
  * const handleClick = () => {
  *   execute({
- *     type: 'action',
+ *     type: 'api',
  *     api: '/api/save',
- *     successMessage: 'Saved successfully!'
+ *     successMessage: 'Saved successfully!',
  *   });
  * };
  * ```
  */
-export function useActionRunner(context: ActionContext = {}) {
+export function useActionRunner(
+  optionsOrContext: UseActionRunnerOptions | ActionContext = {},
+) {
+  // Backwards compat: if no 'context' key, treat entire object as context
+  const options: UseActionRunnerOptions = 'context' in optionsOrContext
+    ? optionsOrContext as UseActionRunnerOptions
+    : { context: optionsOrContext as ActionContext };
+
+  const { context = {}, onConfirm, onToast, onModal, onNavigate } = options;
+
   const [loading, setLoading] = useState(false);
   const [error, setError] = useState<string | null>(null);
   const [result, setResult] = useState<ActionResult | null>(null);
 
-  const runner = useMemo(
-    () => new ActionRunner(context),
-    [JSON.stringify(context)]
-  );
+  const runner = useMemo(() => {
+    const r = new ActionRunner(context);
+    if (onConfirm) r.setConfirmHandler(onConfirm);
+    if (onToast) r.setToastHandler(onToast);
+    if (onModal) r.setModalHandler(onModal);
+    if (onNavigate) r.setNavigationHandler(onNavigate);
+    return r;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [JSON.stringify(context)]);
 
   const execute = useCallback(
-    async (action: any): Promise<ActionResult> => {
+    async (action: ActionDef): Promise<ActionResult> => {
       setLoading(true);
       setError(null);
       setResult(null);

package/src/hooks/useDiscovery.ts

@@ -0,0 +1,141 @@
+/**
+ * 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, useEffect, useContext } from 'react';
+import { SchemaRendererContext } from '../context/SchemaRendererContext';
+
+/**
+ * Discovery service information structure.
+ * Represents server capabilities and service status.
+ */
+export interface DiscoveryInfo {
+  /** Server name and version */
+  name?: string;
+  version?: string;
+  
+  /** Service availability status */
+  services?: {
+    /** Authentication service status */
+    auth?: {
+      enabled: boolean;
+      status?: 'available' | 'unavailable';
+      message?: string;
+    };
+    /** Data access service status */
+    data?: {
+      enabled: boolean;
+      status?: 'available' | 'unavailable';
+    };
+    /** Metadata service status */
+    metadata?: {
+      enabled: boolean;
+      status?: 'available' | 'unavailable';
+    };
+    [key: string]: any;
+  };
+  
+  /** API capabilities */
+  capabilities?: string[];
+  
+  /** Additional discovery metadata */
+  [key: string]: any;
+}
+
+/**
+ * Hook to access discovery information from the ObjectStack server.
+ * 
+ * This hook retrieves server capabilities and service status, which can be used
+ * to conditionally enable/disable features based on server configuration.
+ * 
+ * @example
+ * ```tsx
+ * function App() {
+ *   const { discovery, isLoading } = useDiscovery();
+ *   
+ *   if (isLoading) {
+ *     return <LoadingScreen />;
+ *   }
+ *   
+ *   // Check if auth is enabled on the server
+ *   const authEnabled = discovery?.services?.auth?.enabled ?? true;
+ *   
+ *   return (
+ *     <div>
+ *       {authEnabled ? <AuthProvider>...</AuthProvider> : <App />}
+ *     </div>
+ *   );
+ * }
+ * ```
+ * 
+ * @returns Discovery information and loading state
+ */
+export function useDiscovery() {
+  const context = useContext(SchemaRendererContext);
+  const dataSource = context?.dataSource;
+  const [discovery, setDiscovery] = useState<DiscoveryInfo | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    async function fetchDiscovery() {
+      if (!dataSource) {
+        setIsLoading(false);
+        return;
+      }
+
+      try {
+        setIsLoading(true);
+        
+        // Check if dataSource has getDiscovery method
+        if (typeof (dataSource as any).getDiscovery === 'function') {
+          const discoveryData = await (dataSource as any).getDiscovery();
+          
+          if (!cancelled) {
+            setDiscovery(discoveryData);
+            setError(null);
+          }
+        } else {
+          // DataSource doesn't support discovery
+          if (!cancelled) {
+            setDiscovery(null);
+            setError(null);
+          }
+        }
+      } catch (err) {
+        if (!cancelled) {
+          setError(err instanceof Error ? err : new Error('Failed to fetch discovery'));
+          setDiscovery(null);
+        }
+      } finally {
+        if (!cancelled) {
+          setIsLoading(false);
+        }
+      }
+    }
+
+    fetchDiscovery();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [dataSource]);
+
+  return {
+    discovery,
+    isLoading,
+    error,
+    /**
+     * Check if authentication is enabled on the server.
+     * Defaults to true if discovery data is not available.
+     */
+    isAuthEnabled: discovery?.services?.auth?.enabled ?? true,
+  };
+}
+

package/src/hooks/useDynamicApp.ts

@@ -0,0 +1,142 @@
+/**
+ * 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, useEffect, useCallback, useRef } from 'react';
+
+/**
+ * Options for dynamic app configuration loading.
+ */
+export interface DynamicAppOptions<TAppConfig = unknown> {
+  /** Application identifier to load */
+  appId: string;
+  /**
+   * Static (fallback) configuration used when the server does not
+   * provide an app definition or is unreachable.
+   */
+  staticConfig?: TAppConfig;
+  /**
+   * Data source adapter with `getApp` and `invalidateCache` methods.
+   * Typically an ObjectStackAdapter instance.
+   */
+  adapter?: {
+    getApp: (appId: string) => Promise<unknown | null>;
+    invalidateCache?: (key?: string) => void;
+    getObjectSchema?: (objectName: string) => Promise<unknown>;
+  };
+  /** Whether to attempt loading from the server (default: true) */
+  enabled?: boolean;
+}
+
+/**
+ * Result returned by useDynamicApp.
+ */
+export interface DynamicAppResult<TAppConfig = unknown> {
+  /** The resolved app configuration (server or static fallback) */
+  config: TAppConfig | null;
+  /** Whether the configuration is currently loading */
+  isLoading: boolean;
+  /** Error from the most recent load attempt */
+  error: Error | null;
+  /** Whether the config was loaded from the server (vs static fallback) */
+  isServerConfig: boolean;
+  /** Re-fetch the app configuration from the server, invalidating cache */
+  refresh: () => Promise<void>;
+}
+
+/**
+ * React hook for dynamic app configuration loading.
+ *
+ * Fetches app configuration from the server via `adapter.getApp(appId)`,
+ * falling back to `staticConfig` when the server is unavailable.
+ * Supports cache-based hot-reload via the `refresh()` callback.
+ *
+ * @example
+ * ```tsx
+ * import { useDynamicApp } from '@object-ui/react';
+ * import staticAppConfig from '../config/app.json';
+ *
+ * function App() {
+ *   const { config, isLoading, refresh } = useDynamicApp({
+ *     appId: 'crm',
+ *     staticConfig: staticAppConfig,
+ *     adapter: dataSource,
+ *   });
+ *
+ *   if (isLoading) return <LoadingScreen />;
+ *   return <Console config={config} onRefresh={refresh} />;
+ * }
+ * ```
+ */
+export function useDynamicApp<TAppConfig = unknown>(
+  options: DynamicAppOptions<TAppConfig>,
+): DynamicAppResult<TAppConfig> {
+  const { appId, staticConfig, adapter, enabled = true } = options;
+
+  const [config, setConfig] = useState<TAppConfig | null>(staticConfig ?? null);
+  const [isLoading, setIsLoading] = useState(enabled && !!adapter);
+  const [error, setError] = useState<Error | null>(null);
+  const [isServerConfig, setIsServerConfig] = useState(false);
+
+  // Ref to track unmount / stale requests
+  const mountedRef = useRef(true);
+  useEffect(() => {
+    mountedRef.current = true;
+    return () => { mountedRef.current = false; };
+  }, []);
+
+  const loadConfig = useCallback(async () => {
+    if (!adapter || !enabled) {
+      setConfig(staticConfig ?? null);
+      setIsServerConfig(false);
+      setIsLoading(false);
+      return;
+    }
+
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      const serverConfig = await adapter.getApp(appId);
+
+      if (!mountedRef.current) return;
+
+      if (serverConfig) {
+        setConfig(serverConfig as TAppConfig);
+        setIsServerConfig(true);
+      } else {
+        // Server returned null — fall back to static config
+        setConfig(staticConfig ?? null);
+        setIsServerConfig(false);
+      }
+    } catch (err) {
+      if (!mountedRef.current) return;
+
+      setError(err instanceof Error ? err : new Error(String(err)));
+      // Fall back to static config on error
+      setConfig(staticConfig ?? null);
+      setIsServerConfig(false);
+    } finally {
+      if (mountedRef.current) {
+        setIsLoading(false);
+      }
+    }
+  }, [adapter, appId, staticConfig, enabled]);
+
+  // Load on mount and when appId changes
+  useEffect(() => {
+    loadConfig();
+  }, [loadConfig]);
+
+  const refresh = useCallback(async () => {
+    // Invalidate cache before re-fetching
+    adapter?.invalidateCache?.(`app:${appId}`);
+    await loadConfig();
+  }, [adapter, appId, loadConfig]);
+
+  return { config, isLoading, error, isServerConfig, refresh };
+}

package/src/hooks/useNavigationOverlay.ts

@@ -0,0 +1,180 @@
+/**
+ * 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.
+ */
+
+/**
+ * useNavigationOverlay
+ *
+ * A reusable hook for handling NavigationConfig-driven row/item click behavior.
+ * Manages overlay state (drawer/modal/split/popover) and generates click handlers
+ * that respect the ViewNavigationConfig specification.
+ *
+ * Used by plugin-grid, plugin-list, plugin-detail and any component that needs
+ * NavigationConfig support.
+ */
+
+import { useState, useCallback, useMemo } from 'react';
+
+/**
+ * Inline ViewNavigationConfig to avoid importing from @object-ui/types
+ * (which may not be a direct dependency of @object-ui/react).
+ * Mirrors the canonical definition in @object-ui/types/objectql.ts.
+ */
+export interface NavigationConfig {
+  mode: 'page' | 'drawer' | 'modal' | 'split' | 'popover' | 'new_window' | 'none';
+  view?: string;
+  preventNavigation?: boolean;
+  openNewTab?: boolean;
+  width?: string | number;
+}
+
+export type NavigationMode = NavigationConfig['mode'];
+
+export interface UseNavigationOverlayOptions {
+  /** The navigation configuration from the schema */
+  navigation?: NavigationConfig;
+  /** Object name — used to build default URLs for page/new_window modes */
+  objectName?: string;
+  /** External onNavigate callback (e.g., from ActionProvider or parent) */
+  onNavigate?: (recordId: string | number, action?: string) => void;
+  /** External onRowClick callback — if set, takes full priority */
+  onRowClick?: (record: Record<string, unknown>) => void;
+}
+
+export interface NavigationOverlayState {
+  /** Whether the overlay (drawer/modal/split/popover) is open */
+  isOpen: boolean;
+  /** The record that triggered the navigation */
+  selectedRecord: Record<string, unknown> | null;
+  /** The resolved navigation mode */
+  mode: NavigationMode;
+  /** Close the overlay */
+  close: () => void;
+  /** Open the overlay with a specific record */
+  open: (record: Record<string, unknown>) => void;
+  /** Set the open state (for controlled Sheet/Dialog `onOpenChange`) */
+  setIsOpen: (open: boolean) => void;
+  /** The click handler to attach to rows/items */
+  handleClick: (record: Record<string, unknown>) => void;
+  /** The width from NavigationConfig (for drawer/modal/split sizing) */
+  width: string | number | undefined;
+  /** Whether navigation is an overlay mode (drawer/modal/split/popover) */
+  isOverlay: boolean;
+}
+
+/**
+ * Hook for NavigationConfig-driven navigation overlay.
+ *
+ * @example
+ * ```tsx
+ * const { handleClick, isOpen, selectedRecord, mode, close, width } =
+ *   useNavigationOverlay({
+ *     navigation: schema.navigation,
+ *     objectName: schema.objectName,
+ *     onNavigate: schema.onNavigate,
+ *     onRowClick: props.onRowClick,
+ *   });
+ *
+ * return (
+ *   <>
+ *     <DataTable onRowClick={handleClick} ... />
+ *     {isOpen && mode === 'drawer' && (
+ *       <Sheet open onOpenChange={() => close()}>
+ *         <SheetContent style={{ maxWidth: width }}>
+ *           <RecordDetail record={selectedRecord} />
+ *         </SheetContent>
+ *       </Sheet>
+ *     )}
+ *   </>
+ * );
+ * ```
+ */
+export function useNavigationOverlay(
+  options: UseNavigationOverlayOptions
+): NavigationOverlayState {
+  const { navigation, objectName, onNavigate, onRowClick } = options;
+  const [isOpen, setIsOpen] = useState(false);
+  const [selectedRecord, setSelectedRecord] = useState<Record<string, unknown> | null>(null);
+
+  const mode: NavigationMode = navigation?.mode ?? 'page';
+  const width = navigation?.width;
+  const isOverlay = mode === 'drawer' || mode === 'modal' || mode === 'split' || mode === 'popover';
+
+  const close = useCallback(() => {
+    setIsOpen(false);
+    setSelectedRecord(null);
+  }, []);
+
+  const open = useCallback((record: Record<string, unknown>) => {
+    setSelectedRecord(record);
+    setIsOpen(true);
+  }, []);
+
+  const handleClick = useCallback(
+    (record: Record<string, unknown>) => {
+      // External onRowClick takes full priority
+      if (onRowClick) {
+        onRowClick(record);
+        return;
+      }
+
+      // No navigation config — default to page navigation
+      if (!navigation) {
+        const recordId = record._id || record.id;
+        if (onNavigate && recordId != null) {
+          onNavigate(recordId as string | number, 'view');
+        }
+        return;
+      }
+
+      // 'none' or preventNavigation — do nothing
+      if (mode === 'none' || navigation.preventNavigation) {
+        return;
+      }
+
+      // new_window / openNewTab — open in new browser tab
+      if (mode === 'new_window' || navigation.openNewTab) {
+        const recordId = record._id || record.id;
+        const url = objectName ? `/${objectName}/${recordId}` : `/${recordId}`;
+        window.open(url, '_blank');
+        return;
+      }
+
+      // page — delegate to onNavigate callback
+      if (mode === 'page') {
+        const recordId = record._id || record.id;
+        if (onNavigate && recordId != null) {
+          onNavigate(recordId as string | number, 'view');
+        }
+        return;
+      }
+
+      // Overlay modes: drawer, modal, split, popover
+      if (isOverlay) {
+        setSelectedRecord(record);
+        setIsOpen(true);
+        return;
+      }
+    },
+    [onRowClick, navigation, mode, objectName, onNavigate, isOverlay]
+  );
+
+  return useMemo(
+    () => ({
+      isOpen,
+      selectedRecord,
+      mode,
+      close,
+      open,
+      setIsOpen,
+      handleClick,
+      width,
+      isOverlay,
+    }),
+    [isOpen, selectedRecord, mode, close, open, handleClick, width, isOverlay]
+  );
+}