@object-ui/react 0.5.0 → 2.0.0

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]
+  );
+}

package/src/hooks/usePageVariables.tsx

@@ -0,0 +1,157 @@
+/**
+ * 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 React, { createContext, useContext, useState, useCallback, useMemo } from 'react';
+import type { PageVariable } from '@object-ui/types';
+
+/**
+ * Page variables context value.
+ * Provides access to page-level state variables.
+ */
+export interface PageVariablesContextValue {
+  /** Current variable values */
+  variables: Record<string, any>;
+  /** Set a single variable value */
+  setVariable: (name: string, value: any) => void;
+  /** Set multiple variable values at once */
+  setVariables: (updates: Record<string, any>) => void;
+  /** Reset all variables to their default values */
+  resetVariables: () => void;
+}
+
+const PageVariablesContext = createContext<PageVariablesContextValue | null>(null);
+
+/**
+ * Initialize page variables from their definitions.
+ * Sets each variable to its defaultValue or type-appropriate default.
+ */
+function initializeVariables(definitions?: PageVariable[]): Record<string, any> {
+  if (!definitions || definitions.length === 0) return {};
+
+  const initial: Record<string, any> = {};
+  for (const def of definitions) {
+    if (def.defaultValue !== undefined) {
+      initial[def.name] = def.defaultValue;
+    } else {
+      // Type-appropriate defaults
+      switch (def.type) {
+        case 'number':
+          initial[def.name] = 0;
+          break;
+        case 'boolean':
+          initial[def.name] = false;
+          break;
+        case 'object':
+          initial[def.name] = {};
+          break;
+        case 'array':
+          initial[def.name] = [];
+          break;
+        case 'string':
+        default:
+          initial[def.name] = '';
+          break;
+      }
+    }
+  }
+  return initial;
+}
+
+/**
+ * Props for PageVariablesProvider
+ */
+export interface PageVariablesProviderProps {
+  /** Variable definitions from PageSchema.variables */
+  definitions?: PageVariable[];
+  /** Child components */
+  children: React.ReactNode;
+}
+
+/**
+ * PageVariablesProvider — Provides page-level state variables to the component tree.
+ *
+ * Initializes variables from their definitions and provides read/write access
+ * to all child components via the usePageVariables hook.
+ *
+ * @example
+ * ```tsx
+ * <PageVariablesProvider definitions={[
+ *   { name: 'selectedId', type: 'string', defaultValue: '' },
+ *   { name: 'count', type: 'number', defaultValue: 0 },
+ * ]}>
+ *   <MyComponents />
+ * </PageVariablesProvider>
+ * ```
+ */
+export const PageVariablesProvider: React.FC<PageVariablesProviderProps> = ({
+  definitions,
+  children,
+}) => {
+  const [variables, setVariablesState] = useState<Record<string, any>>(() =>
+    initializeVariables(definitions)
+  );
+
+  const setVariable = useCallback((name: string, value: any) => {
+    setVariablesState((prev) => ({ ...prev, [name]: value }));
+  }, []);
+
+  const setVariables = useCallback((updates: Record<string, any>) => {
+    setVariablesState((prev) => ({ ...prev, ...updates }));
+  }, []);
+
+  const resetVariables = useCallback(() => {
+    setVariablesState(initializeVariables(definitions));
+  }, [definitions]);
+
+  const value = useMemo<PageVariablesContextValue>(
+    () => ({ variables, setVariable, setVariables, resetVariables }),
+    [variables, setVariable, setVariables, resetVariables]
+  );
+
+  return (
+    <PageVariablesContext.Provider value={value}>
+      {children}
+    </PageVariablesContext.Provider>
+  );
+};
+
+PageVariablesProvider.displayName = 'PageVariablesProvider';
+
+/**
+ * Hook to access page-level variables.
+ *
+ * Returns the current variable values and setter functions.
+ * Returns a no-op fallback if used outside a PageVariablesProvider.
+ *
+ * @example
+ * ```tsx
+ * const { variables, setVariable } = usePageVariables();
+ * const userId = variables.selectedId;
+ * setVariable('selectedId', '123');
+ * ```
+ */
+export function usePageVariables(): PageVariablesContextValue {
+  const ctx = useContext(PageVariablesContext);
+  if (!ctx) {
+    // Graceful fallback — allows components to work outside a Page
+    return {
+      variables: {},
+      setVariable: () => {},
+      setVariables: () => {},
+      resetVariables: () => {},
+    };
+  }
+  return ctx;
+}
+
+/**
+ * Hook to check if a PageVariablesProvider is available.
+ */
+export function useHasPageVariables(): boolean {
+  return useContext(PageVariablesContext) !== null;
+}