@object-ui/react 0.5.0 → 3.0.0

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/useETagCache.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 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.
+ */
+/** Configuration for ETag-based HTTP caching. */
+export interface ETagCacheConfig {
+    /** Enable ETag caching (default: true) */
+    enabled?: boolean;
+    /** Storage backend for ETags ('memory' | 'localStorage') */
+    storage?: 'memory' | 'localStorage';
+    /** Storage key prefix (default: 'oui-etag') */
+    storagePrefix?: string;
+    /** Max cache entries (default: 1000) */
+    maxEntries?: number;
+    /** Cache TTL in ms (default: 3600000 = 1 hour) */
+    ttl?: number;
+    /** Whether to register a Service Worker for caching (default: false) */
+    useServiceWorker?: boolean;
+    /** Service Worker script URL */
+    serviceWorkerUrl?: string;
+}
+/** A single cache entry with its associated ETag and metadata. */
+export interface CacheEntry<T = unknown> {
+    data: T;
+    etag: string;
+    url: string;
+    timestamp: number;
+    lastModified?: string;
+}
+/** Result returned by the useETagCache hook. */
+export interface ETagCacheResult {
+    /** Fetch data with ETag support — sends If-None-Match header, returns cached data on 304. */
+    fetchWithETag: <T>(url: string, options?: RequestInit) => Promise<{
+        data: T;
+        fromCache: boolean;
+        etag?: string;
+    }>;
+    /** Invalidate cache for a specific URL. */
+    invalidate: (url: string) => void;
+    /** Invalidate all cache entries matching a pattern. */
+    invalidatePattern: (pattern: string | RegExp) => void;
+    /** Clear entire cache. */
+    clearCache: () => void;
+    /** Number of cached entries. */
+    cacheSize: number;
+    /** Whether Service Worker is registered and active. */
+    serviceWorkerActive: boolean;
+    /** Register/update the Service Worker. */
+    registerServiceWorker: () => Promise<boolean>;
+}
+/**
+ * Hook for ETag-based HTTP caching with optional Service Worker support.
+ * Integrates with @objectstack/client ETag caching for efficient data fetching.
+ * When the server responds with 304 Not Modified, cached data is reused.
+ *
+ * @example
+ * ```tsx
+ * function UserProfile({ userId }: { userId: string }) {
+ *   const cache = useETagCache({ storage: 'localStorage', ttl: 60_000 });
+ *
+ *   useEffect(() => {
+ *     cache.fetchWithETag<User>(`/api/users/${userId}`).then(({ data, fromCache }) => {
+ *       console.log(fromCache ? 'Served from cache' : 'Fresh data');
+ *       setUser(data);
+ *     });
+ *   }, [userId]);
+ *
+ *   return <div>Cache entries: {cache.cacheSize}</div>;
+ * }
+ * ```
+ */
+export declare function useETagCache(userConfig?: ETagCacheConfig): ETagCacheResult;