@rebasepro/admin 0.6.1 → 0.7.0

package/src/form/form_utils.ts

@@ -0,0 +1,163 @@
+import type { EntityCollection, PropertyConfig } from "@rebasepro/types";
+import type { AuthController, Entity, EntityStatus, EntityValues } from "@rebasepro/types";
+import { deepEqual as equal } from "fast-equals";
+import { getIn, setIn } from "@rebasepro/formex";
+import { getDefaultValuesFor } from "@rebasepro/common";
+import { isObject, mergeDeep } from "@rebasepro/utils";
+import { z } from "zod";
+
+// extract touched values for nested touched trees and map to current values
+export function extractTouchedValues(values: unknown, touched: Record<string, boolean>): Record<string, unknown> {
+    let acc: Record<string, unknown> = {};
+    if (!touched || typeof touched !== "object") {
+        return acc;
+    }
+
+    Object.entries(touched).forEach(([key, value]) => {
+        if (value) {
+            acc = setIn(acc, key, getIn(values, key)) as Record<string, unknown>;
+        }
+    })
+
+    return acc;
+}
+
+/**
+ * Recursively removes empty plain objects `{}` and empty arrays `[]` from a value tree.
+ * This prevents ghost containers created by `setIn` intermediate path construction
+ * (e.g. `{ address: {} }` when only `address.city` was touched but value is undefined)
+ * from falsely triggering the unsaved local changes indicator.
+ */
+/**
+ * Check if a value is semantically empty (null, undefined, or empty string).
+ */
+function isSemanticEmpty(v: unknown): boolean {
+    return v === null || v === undefined || v === "";
+}
+
+export function removeEmptyContainers(obj: unknown): unknown {
+    if (Array.isArray(obj)) {
+        const cleaned = obj.map(removeEmptyContainers);
+        // Keep arrays even if they contain only nulls/undefined — that's intentional data
+        return cleaned;
+    }
+    if (obj && typeof obj === "object" && Object.getPrototypeOf(obj) === Object.prototype) {
+        const result: Record<string, unknown> = {};
+        for (const key of Object.keys(obj)) {
+            const cleaned = removeEmptyContainers((obj as Record<string, unknown>)[key]);
+            // Skip empty plain objects
+            if (cleaned && typeof cleaned === "object" && !Array.isArray(cleaned)
+                && Object.getPrototypeOf(cleaned) === Object.prototype
+                && Object.keys(cleaned).length === 0) {
+                continue;
+            }
+            result[key] = cleaned;
+        }
+        // After cleaning, check if all remaining values are semantically empty
+        // (null, undefined, or ""). This catches ghost objects like {type: "", value: null}
+        // created by oneOf block initialization that aren't meaningful changes.
+        if (Object.keys(result).length > 0 && Object.values(result).every(isSemanticEmpty)) {
+            return {};
+        }
+        return result;
+    }
+    return obj;
+}
+
+export function getChanges<T extends object>(source: Partial<T>, comparison: Partial<T>): Partial<T> {
+    const changes: Partial<T> = {};
+
+    if (!source) {
+        return {};
+    }
+    if (!comparison) {
+        return source;
+    }
+
+    const allKeys = Array.from(new Set([...Object.keys(source), ...Object.keys(comparison)]));
+
+    for (const key of allKeys) {
+        const sourceValue = (source as Record<string, unknown>)[key];
+        const comparisonValue = (comparison as Record<string, unknown>)[key];
+
+        if (equal(sourceValue, comparisonValue)) {
+            continue;
+        }
+
+        const sourceHasKey = source && typeof source === "object" && Object.prototype.hasOwnProperty.call(source, key);
+        const comparisonHasKey = comparison && typeof comparison === "object" && Object.prototype.hasOwnProperty.call(comparison, key);
+
+        if (comparisonHasKey && !sourceHasKey) {
+            (changes as Record<string, unknown>)[key] = undefined;
+        } else if (Array.isArray(sourceValue)) {
+            const comparisonArray = Array.isArray(comparisonValue) ? comparisonValue : [];
+            if (sourceValue.length !== comparisonArray.length) {
+                (changes as Record<string, unknown>)[key] = sourceValue;
+                continue;
+            }
+            const hasChanges = sourceValue.some((item, index) => !equal(item, comparisonArray[index]));
+            if (hasChanges) {
+                (changes as Record<string, unknown>)[key] = sourceValue;
+            }
+        } else if (isObject(sourceValue) && sourceValue && isObject(comparisonValue) && comparisonValue) {
+            const nestedChanges = getChanges(sourceValue, comparisonValue);
+            if (Object.keys(nestedChanges).length > 0) {
+                (changes as Record<string, unknown>)[key] = nestedChanges;
+            }
+        } else {
+            (changes as Record<string, unknown>)[key] = sourceValue;
+        }
+    }
+
+    return changes;
+}
+
+export function getInitialEntityValues<M extends Record<string, unknown>>(
+    authController: AuthController,
+    collection: EntityCollection,
+    path: string,
+    status: "new" | "existing" | "copy",
+    entity: Entity<M> | undefined,
+    propertyConfigs?: Record<string, PropertyConfig>
+): Partial<EntityValues<M>> {
+    const properties = collection.properties;
+    if ((status === "existing" || status === "copy") && entity) {
+        let values: Partial<EntityValues<M>>;
+        if (!collection.alwaysApplyDefaultValues) {
+            values = entity.values ?? getDefaultValuesFor(properties);
+        } else {
+            const defaultValues = getDefaultValuesFor(properties);
+            values = mergeDeep(defaultValues, entity.values ?? {});
+        }
+        // When copying, clear ID fields so the database generates new IDs
+        if (status === "copy") {
+            const result = { ...values };
+            for (const [key, property] of Object.entries(properties)) {
+                if (property && "isId" in property && property.isId) {
+                    delete (result as Record<string, unknown>)[key];
+                }
+            }
+            return result;
+        }
+        return values;
+    } else if (status === "new") {
+        return getDefaultValuesFor(properties);
+    } else {
+        console.error({
+            status,
+            entity
+        });
+        throw new Error("Form has not been initialised with the correct parameters");
+    }
+}
+
+export function zodToFormErrors(zodError: z.ZodError): Record<string, string> {
+    let errors: Record<string, string> = {};
+    for (const issue of zodError.issues) {
+        const path = issue.path.join(".");
+        if (path && !getIn(errors, path)) {
+            errors = setIn(errors, path, issue.message) as Record<string, string>;
+        }
+    }
+    return errors;
+}

package/src/form/index.tsx

@@ -1,8 +1,8 @@
-export {
-    EntityForm,
-    zodToFormErrors
-} from "./EntityForm";
-// EntityFormProps is exported from @rebasepro/types
+export { EntityForm } from "./EntityForm";
+export type { EntityFormProps, OnUpdateParams } from "../types/components/EntityFormProps";
+
+export { EntityFormBinding } from "./EntityFormBinding";
+export type { EntityFormBindingProps } from "./EntityFormBinding";
 
 export { SelectFieldBinding } from "./field_bindings/SelectFieldBinding";
 export { MultiSelectFieldBinding } from "./field_bindings/MultiSelectFieldBinding";
@@ -26,3 +26,12 @@ export * from "./components";
 
 export { PropertyFieldBinding } from "./PropertyFieldBinding";
 export * from "./useClearRestoreValue";
+
+// Shared form utilities
+export {
+    extractTouchedValues,
+    removeEmptyContainers,
+    getChanges,
+    getInitialEntityValues,
+    zodToFormErrors
+} from "./form_utils";

package/src/hooks/navigation/contexts/CollectionRegistryContext.tsx

@@ -1,6 +1,6 @@
 import type { EntityCollection } from "@rebasepro/types";
 import React, { createContext } from "react";
-import { CollectionRegistryController, EntityReference } from "@rebasepro/types";
+import { CollectionRegistryController } from "@rebasepro/types";
 
 export const CollectionRegistryContext = createContext<CollectionRegistryController>({
     getCollection: () => undefined,
@@ -12,7 +12,7 @@ export const CollectionRegistryContext = createContext<CollectionRegistryControl
     initialised: false
 });
 
-export function useCollectionRegistryController<DB = Record<string, unknown>, EC extends EntityCollection = EntityCollection<any>>(): CollectionRegistryController<DB, EC> {
+export function useCollectionRegistryController<DB = Record<string, unknown>, EC extends EntityCollection = EntityCollection>(): CollectionRegistryController<DB, EC> {
     const context = React.useContext(CollectionRegistryContext);
     if (context === undefined) {
         throw new Error("useCollectionRegistryController must be used within a CollectionRegistryContext.Provider");

package/src/hooks/navigation/contexts/NavigationStateContext.tsx

@@ -1,6 +1,6 @@
-import type { NavigationStateController, AppView, NavigationResult, RebasePlugin } from "@rebasepro/types";
+import type { NavigationStateController } from "@rebasepro/types";
 import React, { createContext } from "react";
-;
+
 
 export const NavigationStateContext = createContext<NavigationStateController>({
     loading: true,

package/src/hooks/navigation/contexts/UrlContext.tsx

@@ -1,8 +1,7 @@
 import type { UrlController } from "@rebasepro/types";
 import React, { createContext } from "react";
-import { NavigateOptions } from "react-router-dom";
 
-;
+
 
 export const UrlContext = createContext<UrlController>({
     basePath: "/",

package/src/hooks/navigation/useAsyncResolver.ts

@@ -0,0 +1,100 @@
+import { useCallback, useEffect, useRef, useState, useMemo } from "react";
+
+export type UseAsyncResolverResult<T> = {
+    data: T;
+    loading: boolean;
+    error: Error | undefined;
+    refresh: () => void;
+};
+
+/**
+ * Generic hook that resolves an async value with loading/error/refresh
+ * state management, cancellation on unmount or deps change, and
+ * ref-based change detection to prevent unnecessary state updates.
+ *
+ * Extracted from the common pattern in useResolvedCollections and
+ * useResolvedViews.
+ */
+export function useAsyncResolver<T>({
+    resolver,
+    initialValue,
+    isEqual,
+    deps,
+    disabled,
+}: {
+    /** Async function that resolves the data */
+    resolver: () => Promise<T>;
+    /** Initial value before first resolution */
+    initialValue: T;
+    /** Equality check to prevent unnecessary state updates */
+    isEqual: (a: T, b: T) => boolean;
+    /** Effect dependencies — when these change, resolver re-runs */
+    deps: React.DependencyList;
+    /** When true, skip resolution */
+    disabled?: boolean;
+}): UseAsyncResolverResult<T> {
+
+    const [data, setData] = useState<T>(initialValue);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState<Error | undefined>(undefined);
+    const [refreshTrigger, setRefreshTrigger] = useState(0);
+
+    const refresh = useCallback(() => {
+        setRefreshTrigger(prev => prev + 1);
+    }, []);
+
+    // Ref for change detection — avoids state updates when data hasn't changed
+    const dataRef = useRef<T>(initialValue);
+
+    // Store resolver in a ref so we always call the latest version
+    // without adding it to effect deps (it's typically a new closure each render)
+    const resolverRef = useRef(resolver);
+    resolverRef.current = resolver;
+
+    // Same for isEqual
+    const isEqualRef = useRef(isEqual);
+    isEqualRef.current = isEqual;
+
+    useEffect(() => {
+        if (disabled) return;
+
+        let cancelled = false;
+
+        (async () => {
+            try {
+                const result = await resolverRef.current();
+
+                if (cancelled) return;
+
+                // Only update state if data actually changed
+                if (!isEqualRef.current(dataRef.current, result)) {
+                    dataRef.current = result;
+                    setData(result);
+                }
+
+                setError(undefined);
+            } catch (e) {
+                if (!cancelled) {
+                    console.error(e);
+                    setError(e as Error);
+                }
+            } finally {
+                if (!cancelled) {
+                    setLoading(false);
+                }
+            }
+        })();
+
+        return () => {
+            cancelled = true;
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [...deps, refreshTrigger, disabled]);
+
+    return useMemo(() => ({
+        data,
+        loading,
+        error,
+        refresh
+    }), [data, loading, error, refresh]);
+}

package/src/hooks/navigation/useBuildCollectionRegistryController.tsx

@@ -1,16 +1,21 @@
-import type { EntityCollection } from "@rebasepro/types";
-import { useCallback, useRef, useState, useMemo } from "react";
+import type { EntityCollection, DataSourceDefinition } from "@rebasepro/types";
+import { useCallback, useEffect, useRef, useState, useMemo } from "react";
 import { CollectionRegistry, getParentReferencesFromPath as commonGetParentReferencesFromPath, removeInitialAndTrailingSlashes, getSubcollections } from "@rebasepro/common";
 import { EntityReference, UserConfigurationPersistence, CollectionRegistryController } from "@rebasepro/types";
 import { mergeDeep } from "@rebasepro/utils";
 
 export function useBuildCollectionRegistryController(props: {
-    userConfigPersistence?: UserConfigurationPersistence
+    userConfigPersistence?: UserConfigurationPersistence,
+    dataSources?: Record<string, DataSourceDefinition>
 }): CollectionRegistryController & {
     collectionRegistryRef: React.MutableRefObject<CollectionRegistry>;
 } {
-    const { userConfigPersistence } = props;
-    const collectionRegistryRef = useRef<CollectionRegistry>(new CollectionRegistry());
+    const { userConfigPersistence, dataSources } = props;
+    const collectionRegistryRef = useRef<CollectionRegistry>(new CollectionRegistry(undefined, dataSources));
+    // Keep the registry's data sources in sync (used to resolve engine during
+    // normalization). Applied synchronously before the async registration
+    // effect in useResolvedCollections runs.
+    if (dataSources) collectionRegistryRef.current.setDataSources(dataSources);
     const [initialised, setInitialised] = useState(false);
 
     const getCollection = useCallback((
@@ -156,9 +161,11 @@ export function useBuildCollectionRegistryController(props: {
 
     // Determine initialised automatically based on whether collections exist,
     // though the NavigationStateController also plays a role in overall init
-    if (!initialised && collections.length > 0) {
-        setInitialised(true);
-    }
+    useEffect(() => {
+        if (!initialised && collections.length > 0) {
+            setInitialised(true);
+        }
+    }, [initialised, collections.length]);
 
     return useMemo(() => ({
         collections,

package/src/hooks/navigation/useBuildNavigationStateController.tsx

@@ -1,5 +1,5 @@
 import type { AppView, EntityCollection, NavigationResult, RebasePlugin, NavigationStateController, UrlController, NavigationGroupMapping } from "@rebasepro/types";
-import { useCallback, useMemo } from "react";
+import { useCallback, useMemo, useRef } from "react";
 
 import { AuthController, RebaseData, CollectionRegistryController, User } from "@rebasepro/types";
 import type { EntityCollectionsBuilder, AppViewsBuilder, EffectiveRoleController } from "@rebasepro/types";
@@ -100,10 +100,16 @@ export function useBuildNavigationStateController<EC extends EntityCollection, U
         collectionRegistryController
     });
 
-    // Expose a combined refresh function
+    // Expose a combined refresh function with microtask batching
+    const pendingRefreshRef = useRef(false);
     const refreshNavigation = useCallback(() => {
-        refreshCollections();
-        refreshViews();
+        if (pendingRefreshRef.current) return;
+        pendingRefreshRef.current = true;
+        queueMicrotask(() => {
+            pendingRefreshRef.current = false;
+            refreshCollections();
+            refreshViews();
+        });
     }, [refreshCollections, refreshViews]);
 
     return useMemo(() => ({
@@ -112,8 +118,7 @@ export function useBuildNavigationStateController<EC extends EntityCollection, U
         topLevelNavigation,
         loading: collectionsLoading || viewsLoading,
         navigationLoadingError: collectionsError ?? viewsError,
-        refreshNavigation,
-        plugins
+        refreshNavigation
     }), [
         views,
         adminViews,
@@ -122,7 +127,6 @@ export function useBuildNavigationStateController<EC extends EntityCollection, U
         viewsLoading,
         collectionsError,
         viewsError,
-        refreshNavigation,
-        plugins
+        refreshNavigation
     ]);
 }

package/src/hooks/navigation/useNavigationResolution.ts

@@ -211,5 +211,38 @@ export async function resolveAppViews(
         }
     }
 
+    // Detect duplicate view slugs (dev warning)
+    if (process.env.NODE_ENV !== 'production') {
+        const slugCounts = new Map<string, number>();
+        resolvedViews.forEach(v => {
+            slugCounts.set(v.slug, (slugCounts.get(v.slug) ?? 0) + 1);
+        });
+        slugCounts.forEach((count, slug) => {
+            if (count > 1) {
+                console.warn(
+                    `[Rebase] Duplicate view slug "${slug}" detected (${count} views). ` +
+                    `Last-write-wins. Ensure unique slugs across CMS views and plugins.`
+                );
+            }
+        });
+    }
+
+    // Filter by roles — applies to CMS, plugin, and builder-returned views
+    resolvedViews = filterViewsByRole(resolvedViews, authController);
+
     return resolvedViews;
 }
+
+/**
+ * Filter views by the `roles` field on AppView.
+ * When `roles` is set, the view is only included if the current user
+ * has at least one of the listed roles. Views without `roles` (or with
+ * an empty array) are always included.
+ */
+function filterViewsByRole(views: AppView[], authController: AuthController): AppView[] {
+    const userRoles = authController.user?.roles ?? [];
+    return views.filter(view => {
+        if (!view.roles || view.roles.length === 0) return true;
+        return view.roles.some(role => userRoles.includes(role));
+    });
+}

package/src/hooks/navigation/useResolvedCollections.ts

@@ -1,5 +1,5 @@
 import type { EntityCollection, RebasePlugin } from "@rebasepro/types";
-import { useCallback, useEffect, useRef, useState, useMemo } from "react";
+import { useRef, useMemo } from "react";
 
 import { AuthController, CollectionRegistryController, RebaseData, User } from "@rebasepro/types";
 import type { EntityCollectionsBuilder } from "@rebasepro/types";
@@ -8,6 +8,7 @@ import { CollectionRegistry } from "@rebasepro/common";
 
 import { resolveCollections } from "./useNavigationResolution";
 import { areCollectionListsEqual } from "./utils";
+import { useAsyncResolver } from "./useAsyncResolver";
 
 export type UseResolvedCollectionsProps<EC extends EntityCollection, USER extends User> = {
     authController: AuthController<USER>;
@@ -50,16 +51,11 @@ export function useResolvedCollections<EC extends EntityCollection, USER extends
         collectionRegistryController
     } = props;
 
-    const [loading, setLoading] = useState(true);
-    const [error, setError] = useState<Error | undefined>(undefined);
-    const [resolvedCollections, setResolvedCollections] = useState<EntityCollection[]>([]);
-
-    // Track the trigger count to allow force-refresh
-    const [refreshTrigger, setRefreshTrigger] = useState(0);
-
-    const refresh = useCallback(() => {
-        setRefreshTrigger(prev => prev + 1);
-    }, []);
+    // Stable identity string for the user — avoids re-triggering when the
+    // authController object reference changes but uid/roles are the same.
+    const userIdentity = authController.user
+        ? `${authController.user.uid}:${(authController.user.roles ?? []).sort().join(',')}`
+        : null;
 
     // Use refs for values that may be new objects each render but shouldn't
     // re-trigger the effect. The effect reads them at execution time.
@@ -70,74 +66,36 @@ export function useResolvedCollections<EC extends EntityCollection, USER extends
     const pluginsRef = useRef(plugins);
     pluginsRef.current = plugins;
 
+    const { data: collections, loading, error, refresh } = useAsyncResolver<EntityCollection[]>({
+        resolver: async () => {
+            const resolved = await resolveCollections(
+                collectionsProp,
+                authControllerRef.current,
+                dataRef.current,
+                pluginsRef.current
+            );
 
-    // Ref for resolved collections change detection
-    const resolvedCollectionsRef = useRef<EntityCollection[]>([]);
-
-    const initialLoading = authController.initialLoading;
-    const user = authController.user;
-
-    useEffect(() => {
-        if (disabled || initialLoading) return;
-
-        let cancelled = false;
-
-        (async () => {
-            try {
-                const resolved = await resolveCollections(
-                    collectionsProp,
-                    authControllerRef.current,
-                    dataRef.current,
-                    pluginsRef.current
-                );
+            const deduped = [...resolved];
 
-                if (cancelled) return;
+            // Register with the CollectionRegistry; returns true if changed
+            const changed = collectionRegistryController.collectionRegistryRef.current.registerMultiple(deduped);
 
-                const deduped = [...resolved];
-
-                // Register with the CollectionRegistry; returns true if changed
-                const changed = collectionRegistryController.collectionRegistryRef.current.registerMultiple(deduped);
-
-                if (changed) {
-                    console.debug("Collections have changed", deduped);
-                }
-
-                // Only update state if collections actually changed
-                if (!areCollectionListsEqual(resolvedCollectionsRef.current, deduped)) {
-                    resolvedCollectionsRef.current = deduped;
-                    setResolvedCollections(deduped);
-                }
-
-                setError(undefined);
-            } catch (e) {
-                if (!cancelled) {
-                    console.error(e);
-                    setError(e as Error);
-                }
-            } finally {
-                if (!cancelled) {
-                    setLoading(false);
-                }
+            if (changed) {
+                console.debug("Collections have changed", deduped);
             }
-        })();
 
-        return () => {
-            cancelled = true;
-        };
-    }, [
-        collectionsProp,
-        disabled,
-        collectionRegistryController.collectionRegistryRef,
-        refreshTrigger,
-        initialLoading,
-        user
-    ]);
+            return deduped;
+        },
+        initialValue: [],
+        isEqual: areCollectionListsEqual,
+        deps: [collectionsProp, userIdentity, disabled],
+        disabled: disabled || authController.initialLoading,
+    });
 
     return useMemo(() => ({
-        collections: resolvedCollections,
+        collections,
         loading,
         error,
         refresh
-    }), [resolvedCollections, loading, error, refresh]);
+    }), [collections, loading, error, refresh]);
 }
-