@object-ui/react 0.3.1 → 2.0.0

package/dist/hooks/useActionRunner.js

@@ -6,28 +6,48 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { useState, useCallback, useMemo } from 'react';
-import { ActionRunner } from '@object-ui/core';
+import { ActionRunner, } from '@object-ui/core';
 /**
- * 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 = {}) {
+export function useActionRunner(optionsOrContext = {}) {
+    // Backwards compat: if no 'context' key, treat entire object as context
+    const options = 'context' in optionsOrContext
+        ? optionsOrContext
+        : { context: optionsOrContext };
+    const { context = {}, onConfirm, onToast, onModal, onNavigate } = options;
     const [loading, setLoading] = useState(false);
     const [error, setError] = useState(null);
     const [result, setResult] = useState(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) => {
         setLoading(true);
         setError(null);

package/dist/hooks/useDiscovery.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare function useDiscovery(): {
+    discovery: DiscoveryInfo | null;
+    isLoading: boolean;
+    error: Error | null;
+    /**
+     * Check if authentication is enabled on the server.
+     * Defaults to true if discovery data is not available.
+     */
+    isAuthEnabled: boolean;
+};

package/dist/hooks/useDiscovery.js

@@ -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.
+ */
+import { useState, useEffect, useContext } from 'react';
+import { SchemaRendererContext } from '../context/SchemaRendererContext';
+/**
+ * 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(null);
+    const [isLoading, setIsLoading] = useState(true);
+    const [error, setError] = useState(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.getDiscovery === 'function') {
+                    const discoveryData = await dataSource.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/dist/hooks/useDynamicApp.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare function useDynamicApp<TAppConfig = unknown>(options: DynamicAppOptions<TAppConfig>): DynamicAppResult<TAppConfig>;

package/dist/hooks/useDynamicApp.js

@@ -0,0 +1,92 @@
+/**
+ * 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';
+/**
+ * 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(options) {
+    const { appId, staticConfig, adapter, enabled = true } = options;
+    const [config, setConfig] = useState(staticConfig ?? null);
+    const [isLoading, setIsLoading] = useState(enabled && !!adapter);
+    const [error, setError] = useState(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);
+                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/dist/hooks/useNavigationOverlay.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare function useNavigationOverlay(options: UseNavigationOverlayOptions): NavigationOverlayState;

package/dist/hooks/useNavigationOverlay.js

@@ -0,0 +1,112 @@
+/**
+ * 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';
+/**
+ * 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) {
+    const { navigation, objectName, onNavigate, onRowClick } = options;
+    const [isOpen, setIsOpen] = useState(false);
+    const [selectedRecord, setSelectedRecord] = useState(null);
+    const mode = 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) => {
+        setSelectedRecord(record);
+        setIsOpen(true);
+    }, []);
+    const handleClick = useCallback((record) => {
+        // 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, '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, '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/dist/hooks/usePageVariables.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 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 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;
+}
+/**
+ * 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 declare const PageVariablesProvider: React.FC<PageVariablesProviderProps>;
+/**
+ * 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 declare function usePageVariables(): PageVariablesContextValue;
+/**
+ * Hook to check if a PageVariablesProvider is available.
+ */
+export declare function useHasPageVariables(): boolean;