@object-ui/app-shell 3.3.0 → 3.3.1

package/dist/hooks/useNavigationSync.d.ts

@@ -0,0 +1,82 @@
+/**
+ * useNavigationSync
+ *
+ * Synchronizes the App navigation tree when Pages or Dashboards are
+ * created, deleted, or renamed.  Pure utility helpers are exported for
+ * unit-testing; the React hook wires them to the adapter / metadata
+ * context and shows sonner toasts with an undo action.
+ *
+ * @module
+ */
+import type { NavigationItem } from '@object-ui/types';
+/** Generate a simple unique id for a new navigation item. */
+export declare function generateNavId(prefix?: string): string;
+/**
+ * Add a navigation item to the end of a navigation array (immutable).
+ */
+export declare function addNavigationItem(navigation: NavigationItem[], item: NavigationItem): NavigationItem[];
+/**
+ * Recursively remove all navigation items that match a given type and name.
+ * Returns a new array (immutable).
+ */
+export declare function removeNavigationItems(navigation: NavigationItem[], type: 'page' | 'dashboard', name: string): NavigationItem[];
+/**
+ * Recursively rename all navigation items that reference the old name.
+ * Returns a new array (immutable).
+ */
+export declare function renameNavigationItems(navigation: NavigationItem[], type: 'page' | 'dashboard', oldName: string, newName: string): NavigationItem[];
+/**
+ * Shallow-structural equality check for two NavigationItem arrays.
+ * Works reliably because NavigationItem objects are plain serializable JSON
+ * whose key ordering is deterministic (we control object creation).
+ */
+export declare function navigationEqual(a: NavigationItem[], b: NavigationItem[]): boolean;
+export interface UseNavigationSyncReturn {
+    /** Call after a new page has been created / saved for the first time. */
+    syncPageCreated: (appName: string, pageName: string, label?: string) => Promise<void>;
+    /** Call after a new dashboard has been created / saved for the first time. */
+    syncDashboardCreated: (appName: string, dashboardName: string, label?: string) => Promise<void>;
+    /** Call after a page has been deleted. */
+    syncPageDeleted: (appName: string, pageName: string) => Promise<void>;
+    /** Call after a dashboard has been deleted. */
+    syncDashboardDeleted: (appName: string, dashboardName: string) => Promise<void>;
+    /** Call after a page has been renamed. */
+    syncPageRenamed: (appName: string, oldName: string, newName: string) => Promise<void>;
+    /** Call after a dashboard has been renamed. */
+    syncDashboardRenamed: (appName: string, oldName: string, newName: string) => Promise<void>;
+    /** Convenience: add page to navigation of ALL apps. */
+    syncPageCreatedAllApps: (pageName: string, label?: string) => Promise<void>;
+    /** Convenience: add dashboard to navigation of ALL apps. */
+    syncDashboardCreatedAllApps: (dashboardName: string, label?: string) => Promise<void>;
+    /** Convenience: remove page from navigation of ALL apps. */
+    syncPageDeletedAllApps: (pageName: string) => Promise<void>;
+    /** Convenience: remove dashboard from navigation of ALL apps. */
+    syncDashboardDeletedAllApps: (dashboardName: string) => Promise<void>;
+    /** Convenience: rename page references across ALL apps. */
+    syncPageRenamedAllApps: (oldName: string, newName: string) => Promise<void>;
+    /** Convenience: rename dashboard references across ALL apps. */
+    syncDashboardRenamedAllApps: (oldName: string, newName: string) => Promise<void>;
+}
+/**
+ * Hook that provides methods to keep the App navigation tree in sync with
+ * Page / Dashboard CRUD operations.  Each method:
+ *
+ * 1. Finds the target app from metadata
+ * 2. Mutates the `navigation` array (immutably)
+ * 3. Persists via `client.meta.saveItem`
+ * 4. Refreshes metadata cache
+ * 5. Shows a toast with an **Undo** action
+ */
+export declare function useNavigationSync(): UseNavigationSyncReturn;
+/**
+ * Headless component that watches the `pages` and `dashboards` metadata
+ * arrays.  When items are added or removed it automatically calls the
+ * matching navigation-sync methods for every app.
+ *
+ * Mount once inside the component tree (e.g. inside `AppContent`) where
+ * both `useMetadata` and `useAdapter` are available.
+ *
+ * > **Rename detection** is not possible with a simple diff — callers
+ * > should invoke `syncPageRenamed` / `syncDashboardRenamed` explicitly.
+ */
+export declare function NavigationSyncEffect(): null;

package/dist/hooks/useNavigationSync.js

@@ -0,0 +1,495 @@
+/**
+ * useNavigationSync
+ *
+ * Synchronizes the App navigation tree when Pages or Dashboards are
+ * created, deleted, or renamed.  Pure utility helpers are exported for
+ * unit-testing; the React hook wires them to the adapter / metadata
+ * context and shows sonner toasts with an undo action.
+ *
+ * @module
+ */
+import { useCallback, useEffect, useRef } from 'react';
+import { toast } from 'sonner';
+import { useAdapter } from '../providers/AdapterProvider';
+import { useMetadata } from '../providers/MetadataProvider';
+// ============================================================================
+// Pure utility helpers (exported for testing)
+// ============================================================================
+let _idCounter = 0;
+/** Generate a simple unique id for a new navigation item. */
+export function generateNavId(prefix = 'nav') {
+    return `${prefix}_${Date.now()}_${++_idCounter}`;
+}
+/**
+ * Add a navigation item to the end of a navigation array (immutable).
+ */
+export function addNavigationItem(navigation, item) {
+    return [...navigation, item];
+}
+/**
+ * Recursively remove all navigation items that match a given type and name.
+ * Returns a new array (immutable).
+ */
+export function removeNavigationItems(navigation, type, name) {
+    return navigation
+        .filter((item) => {
+        if (item.type === type) {
+            if (type === 'page' && item.pageName === name)
+                return false;
+            if (type === 'dashboard' && item.dashboardName === name)
+                return false;
+        }
+        return true;
+    })
+        .map((item) => {
+        if (item.children && item.children.length > 0) {
+            return {
+                ...item,
+                children: removeNavigationItems(item.children, type, name),
+            };
+        }
+        return item;
+    });
+}
+/**
+ * Recursively rename all navigation items that reference the old name.
+ * Returns a new array (immutable).
+ */
+export function renameNavigationItems(navigation, type, oldName, newName) {
+    return navigation.map((item) => {
+        let updated = item;
+        if (type === 'page' && item.type === 'page' && item.pageName === oldName) {
+            updated = { ...item, pageName: newName };
+        }
+        else if (type === 'dashboard' && item.type === 'dashboard' && item.dashboardName === oldName) {
+            updated = { ...item, dashboardName: newName };
+        }
+        if (updated.children && updated.children.length > 0) {
+            return {
+                ...updated,
+                children: renameNavigationItems(updated.children, type, oldName, newName),
+            };
+        }
+        return updated;
+    });
+}
+/**
+ * Shallow-structural equality check for two NavigationItem arrays.
+ * Works reliably because NavigationItem objects are plain serializable JSON
+ * whose key ordering is deterministic (we control object creation).
+ */
+export function navigationEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    // Fast-path: same reference
+    if (a === b)
+        return true;
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+/**
+ * Hook that provides methods to keep the App navigation tree in sync with
+ * Page / Dashboard CRUD operations.  Each method:
+ *
+ * 1. Finds the target app from metadata
+ * 2. Mutates the `navigation` array (immutably)
+ * 3. Persists via `client.meta.saveItem`
+ * 4. Refreshes metadata cache
+ * 5. Shows a toast with an **Undo** action
+ */
+export function useNavigationSync() {
+    const adapter = useAdapter();
+    const { apps, refresh } = useMetadata();
+    // Keep a ref so the undo closure always reads the latest adapter
+    const adapterRef = useRef(adapter);
+    adapterRef.current = adapter;
+    const refreshRef = useRef(refresh);
+    refreshRef.current = refresh;
+    /** Persist an updated app schema and refresh metadata. */
+    const saveApp = useCallback(async (appName, schema) => {
+        const client = adapterRef.current?.getClient();
+        if (client) {
+            await client.meta.saveItem('app', appName, schema);
+        }
+        await refreshRef.current?.();
+    }, []);
+    /** Find the current app schema from metadata by name. */
+    const findApp = useCallback((appName) => apps.find((a) => a.name === appName), [apps]);
+    // ------------------------------------------------------------------
+    // Created
+    // ------------------------------------------------------------------
+    const syncPageCreated = useCallback(async (appName, pageName, label) => {
+        const app = findApp(appName);
+        if (!app)
+            return;
+        const prev = app.navigation ?? [];
+        const newItem = {
+            id: generateNavId('nav_page'),
+            type: 'page',
+            label: label || pageName,
+            pageName,
+            icon: 'FileText',
+        };
+        const updated = addNavigationItem(prev, newItem);
+        const updatedApp = { ...app, navigation: updated };
+        try {
+            await saveApp(appName, updatedApp);
+            toast.success(`Navigation updated: added page "${label || pageName}"`, {
+                action: {
+                    label: 'Undo',
+                    onClick: async () => {
+                        try {
+                            await saveApp(appName, { ...app, navigation: prev });
+                            toast.info('Navigation change undone');
+                        }
+                        catch {
+                            toast.error('Failed to undo navigation change');
+                        }
+                    },
+                },
+            });
+        }
+        catch {
+            toast.error('Failed to update navigation');
+        }
+    }, [findApp, saveApp]);
+    const syncDashboardCreated = useCallback(async (appName, dashboardName, label) => {
+        const app = findApp(appName);
+        if (!app)
+            return;
+        const prev = app.navigation ?? [];
+        const newItem = {
+            id: generateNavId('nav_dash'),
+            type: 'dashboard',
+            label: label || dashboardName,
+            dashboardName,
+            icon: 'LayoutDashboard',
+        };
+        const updated = addNavigationItem(prev, newItem);
+        const updatedApp = { ...app, navigation: updated };
+        try {
+            await saveApp(appName, updatedApp);
+            toast.success(`Navigation updated: added dashboard "${label || dashboardName}"`, {
+                action: {
+                    label: 'Undo',
+                    onClick: async () => {
+                        try {
+                            await saveApp(appName, { ...app, navigation: prev });
+                            toast.info('Navigation change undone');
+                        }
+                        catch {
+                            toast.error('Failed to undo navigation change');
+                        }
+                    },
+                },
+            });
+        }
+        catch {
+            toast.error('Failed to update navigation');
+        }
+    }, [findApp, saveApp]);
+    // ------------------------------------------------------------------
+    // Deleted
+    // ------------------------------------------------------------------
+    const syncPageDeleted = useCallback(async (appName, pageName) => {
+        const app = findApp(appName);
+        if (!app)
+            return;
+        const prev = app.navigation ?? [];
+        const updated = removeNavigationItems(prev, 'page', pageName);
+        if (navigationEqual(updated, prev))
+            return; // nothing changed
+        const updatedApp = { ...app, navigation: updated };
+        try {
+            await saveApp(appName, updatedApp);
+            toast.success(`Navigation updated: removed page "${pageName}"`, {
+                action: {
+                    label: 'Undo',
+                    onClick: async () => {
+                        try {
+                            await saveApp(appName, { ...app, navigation: prev });
+                            toast.info('Navigation change undone');
+                        }
+                        catch {
+                            toast.error('Failed to undo navigation change');
+                        }
+                    },
+                },
+            });
+        }
+        catch {
+            toast.error('Failed to update navigation');
+        }
+    }, [findApp, saveApp]);
+    const syncDashboardDeleted = useCallback(async (appName, dashboardName) => {
+        const app = findApp(appName);
+        if (!app)
+            return;
+        const prev = app.navigation ?? [];
+        const updated = removeNavigationItems(prev, 'dashboard', dashboardName);
+        if (navigationEqual(updated, prev))
+            return;
+        const updatedApp = { ...app, navigation: updated };
+        try {
+            await saveApp(appName, updatedApp);
+            toast.success(`Navigation updated: removed dashboard "${dashboardName}"`, {
+                action: {
+                    label: 'Undo',
+                    onClick: async () => {
+                        try {
+                            await saveApp(appName, { ...app, navigation: prev });
+                            toast.info('Navigation change undone');
+                        }
+                        catch {
+                            toast.error('Failed to undo navigation change');
+                        }
+                    },
+                },
+            });
+        }
+        catch {
+            toast.error('Failed to update navigation');
+        }
+    }, [findApp, saveApp]);
+    // ------------------------------------------------------------------
+    // Renamed
+    // ------------------------------------------------------------------
+    const syncPageRenamed = useCallback(async (appName, oldName, newName) => {
+        const app = findApp(appName);
+        if (!app)
+            return;
+        const prev = app.navigation ?? [];
+        const updated = renameNavigationItems(prev, 'page', oldName, newName);
+        if (navigationEqual(updated, prev))
+            return;
+        const updatedApp = { ...app, navigation: updated };
+        try {
+            await saveApp(appName, updatedApp);
+            toast.success(`Navigation updated: renamed page "${oldName}" → "${newName}"`, {
+                action: {
+                    label: 'Undo',
+                    onClick: async () => {
+                        try {
+                            await saveApp(appName, { ...app, navigation: prev });
+                            toast.info('Navigation change undone');
+                        }
+                        catch {
+                            toast.error('Failed to undo navigation change');
+                        }
+                    },
+                },
+            });
+        }
+        catch {
+            toast.error('Failed to update navigation');
+        }
+    }, [findApp, saveApp]);
+    const syncDashboardRenamed = useCallback(async (appName, oldName, newName) => {
+        const app = findApp(appName);
+        if (!app)
+            return;
+        const prev = app.navigation ?? [];
+        const updated = renameNavigationItems(prev, 'dashboard', oldName, newName);
+        if (navigationEqual(updated, prev))
+            return;
+        const updatedApp = { ...app, navigation: updated };
+        try {
+            await saveApp(appName, updatedApp);
+            toast.success(`Navigation updated: renamed dashboard "${oldName}" → "${newName}"`, {
+                action: {
+                    label: 'Undo',
+                    onClick: async () => {
+                        try {
+                            await saveApp(appName, { ...app, navigation: prev });
+                            toast.info('Navigation change undone');
+                        }
+                        catch {
+                            toast.error('Failed to undo navigation change');
+                        }
+                    },
+                },
+            });
+        }
+        catch {
+            toast.error('Failed to update navigation');
+        }
+    }, [findApp, saveApp]);
+    // ------------------------------------------------------------------
+    // All-Apps convenience methods
+    // ------------------------------------------------------------------
+    /** Safely extract the app name from a metadata entry. */
+    const getAppName = (app) => app && typeof app === 'object' && 'name' in app ? app.name : undefined;
+    /** Add a page nav item to ALL apps that don't already reference it. */
+    const syncPageCreatedAllApps = useCallback(async (pageName, label) => {
+        for (const app of apps) {
+            const name = getAppName(app);
+            if (!name)
+                continue;
+            await syncPageCreated(name, pageName, label);
+        }
+    }, [apps, syncPageCreated]);
+    /** Add a dashboard nav item to ALL apps that don't already reference it. */
+    const syncDashboardCreatedAllApps = useCallback(async (dashboardName, label) => {
+        for (const app of apps) {
+            const name = getAppName(app);
+            if (!name)
+                continue;
+            await syncDashboardCreated(name, dashboardName, label);
+        }
+    }, [apps, syncDashboardCreated]);
+    /** Remove a page from navigation across ALL apps. */
+    const syncPageDeletedAllApps = useCallback(async (pageName) => {
+        for (const app of apps) {
+            const name = getAppName(app);
+            if (!name)
+                continue;
+            await syncPageDeleted(name, pageName);
+        }
+    }, [apps, syncPageDeleted]);
+    /** Remove a dashboard from navigation across ALL apps. */
+    const syncDashboardDeletedAllApps = useCallback(async (dashboardName) => {
+        for (const app of apps) {
+            const name = getAppName(app);
+            if (!name)
+                continue;
+            await syncDashboardDeleted(name, dashboardName);
+        }
+    }, [apps, syncDashboardDeleted]);
+    /** Rename page references across ALL apps. */
+    const syncPageRenamedAllApps = useCallback(async (oldName, newName) => {
+        for (const app of apps) {
+            const name = getAppName(app);
+            if (!name)
+                continue;
+            await syncPageRenamed(name, oldName, newName);
+        }
+    }, [apps, syncPageRenamed]);
+    /** Rename dashboard references across ALL apps. */
+    const syncDashboardRenamedAllApps = useCallback(async (oldName, newName) => {
+        for (const app of apps) {
+            const name = getAppName(app);
+            if (!name)
+                continue;
+            await syncDashboardRenamed(name, oldName, newName);
+        }
+    }, [apps, syncDashboardRenamed]);
+    return {
+        syncPageCreated,
+        syncDashboardCreated,
+        syncPageDeleted,
+        syncDashboardDeleted,
+        syncPageRenamed,
+        syncDashboardRenamed,
+        syncPageCreatedAllApps,
+        syncDashboardCreatedAllApps,
+        syncPageDeletedAllApps,
+        syncDashboardDeletedAllApps,
+        syncPageRenamedAllApps,
+        syncDashboardRenamedAllApps,
+    };
+}
+// ============================================================================
+// NavigationSyncEffect — auto-detect page/dashboard metadata changes
+// ============================================================================
+/**
+ * Headless component that watches the `pages` and `dashboards` metadata
+ * arrays.  When items are added or removed it automatically calls the
+ * matching navigation-sync methods for every app.
+ *
+ * Mount once inside the component tree (e.g. inside `AppContent`) where
+ * both `useMetadata` and `useAdapter` are available.
+ *
+ * > **Rename detection** is not possible with a simple diff — callers
+ * > should invoke `syncPageRenamed` / `syncDashboardRenamed` explicitly.
+ */
+export function NavigationSyncEffect() {
+    const { pages, dashboards, apps } = useMetadata();
+    const adapter = useAdapter();
+    const adapterRef = useRef(adapter);
+    adapterRef.current = adapter;
+    const { syncPageCreated, syncDashboardCreated, syncPageDeleted, syncDashboardDeleted, } = useNavigationSync();
+    // Track previous page/dashboard name sets
+    const prevPageNamesRef = useRef(null);
+    const prevDashNamesRef = useRef(null);
+    // Guard against circular refreshes and concurrent sync operations.
+    // Incremented on each effect invocation; the async closure captures
+    // its own version and bails out if a newer run has started.
+    const syncVersionRef = useRef(0);
+    const syncingRef = useRef(false);
+    /** Safely extract the app name from a metadata entry. */
+    const getAppName = (app) => app && typeof app === 'object' && 'name' in app ? app.name : undefined;
+    useEffect(() => {
+        if (syncingRef.current)
+            return;
+        const currentPageNames = new Set((pages ?? []).map((p) => p.name).filter(Boolean));
+        const currentDashNames = new Set((dashboards ?? []).map((d) => d.name).filter(Boolean));
+        const prevPages = prevPageNamesRef.current;
+        const prevDash = prevDashNamesRef.current;
+        // First render — seed refs and exit without syncing
+        if (prevPages === null || prevDash === null) {
+            prevPageNamesRef.current = currentPageNames;
+            prevDashNamesRef.current = currentDashNames;
+            return;
+        }
+        // Compute diff
+        const addedPages = [...currentPageNames].filter((n) => !prevPages.has(n));
+        const removedPages = [...prevPages].filter((n) => !currentPageNames.has(n));
+        const addedDash = [...currentDashNames].filter((n) => !prevDash.has(n));
+        const removedDash = [...prevDash].filter((n) => !currentDashNames.has(n));
+        if (addedPages.length === 0 &&
+            removedPages.length === 0 &&
+            addedDash.length === 0 &&
+            removedDash.length === 0) {
+            // Nothing changed — update refs and exit
+            prevPageNamesRef.current = currentPageNames;
+            prevDashNamesRef.current = currentDashNames;
+            return;
+        }
+        // Sync navigation across all apps
+        const version = ++syncVersionRef.current;
+        syncingRef.current = true;
+        let cancelled = false;
+        (async () => {
+            try {
+                for (const app of apps) {
+                    if (cancelled || syncVersionRef.current !== version)
+                        break;
+                    const appName = getAppName(app);
+                    if (!appName)
+                        continue;
+                    for (const pageName of addedPages) {
+                        if (cancelled)
+                            break;
+                        await syncPageCreated(appName, pageName);
+                    }
+                    for (const pageName of removedPages) {
+                        if (cancelled)
+                            break;
+                        await syncPageDeleted(appName, pageName);
+                    }
+                    for (const dashName of addedDash) {
+                        if (cancelled)
+                            break;
+                        await syncDashboardCreated(appName, dashName);
+                    }
+                    for (const dashName of removedDash) {
+                        if (cancelled)
+                            break;
+                        await syncDashboardDeleted(appName, dashName);
+                    }
+                }
+            }
+            finally {
+                // Only update refs if this is still the latest sync version
+                if (syncVersionRef.current === version) {
+                    prevPageNamesRef.current = currentPageNames;
+                    prevDashNamesRef.current = currentDashNames;
+                    syncingRef.current = false;
+                }
+            }
+        })();
+        return () => {
+            cancelled = true;
+        };
+    }, [pages, dashboards, apps, syncPageCreated, syncDashboardCreated, syncPageDeleted, syncDashboardDeleted]);
+    return null;
+}

package/dist/hooks/useObjectActions.d.ts

@@ -0,0 +1,38 @@
+/**
+ * useObjectActions Hook
+ *
+ * Provides action handlers for CRUD operations on an object, backed by
+ * the ActionRunner from @object-ui/core via the useActionRunner hook.
+ *
+ * Supports:
+ * - create: Open create dialog
+ * - delete: Delete a record with confirmation
+ * - navigate: Route to a specific view or record
+ * - refresh: Trigger a data refresh
+ */
+import type { ActionDef, ActionResult } from '@object-ui/core';
+interface ObjectActionConfig {
+    objectName: string;
+    objectLabel?: string;
+    dataSource: any;
+    onEdit?: (record: any) => void;
+    onRefresh?: () => void;
+}
+interface ObjectActions {
+    /** Run an action by schema or type string */
+    execute: (action: ActionDef) => Promise<ActionResult>;
+    /** Create new record — opens the create dialog */
+    create: () => void;
+    /** Delete a record by id */
+    deleteRecord: (recordId: string) => Promise<ActionResult>;
+    /** Navigate to a view */
+    navigateToView: (viewId: string) => void;
+    /** Navigate to a record detail */
+    navigateToRecord: (recordId: string) => void;
+    /** Whether an action is currently executing */
+    loading: boolean;
+    /** Last error message */
+    error: string | null;
+}
+export declare function useObjectActions({ objectName, objectLabel, dataSource, onEdit, onRefresh, }: ObjectActionConfig): ObjectActions;
+export {};