@firecms/core 3.0.0 → 3.1.0-canary.02232f4

package/src/hooks/useBuildNavigationController.tsx

@@ -34,7 +34,6 @@ import { getParentReferencesFromPath } from "../util/parent_references_from_path
 const DEFAULT_BASE_PATH = "/";
 const DEFAULT_COLLECTION_PATH = "/c";
 
-export const NAVIGATION_DEFAULT_GROUP_NAME = "Views";
 export const NAVIGATION_ADMIN_GROUP_NAME = "Admin";
 
 export type BuildNavigationContextProps<EC extends EntityCollection, USER extends User> = {
@@ -122,10 +121,10 @@ export function useBuildNavigationController<EC extends EntityCollection, USER e
 
     const navigate = useNavigate();
 
-    const collectionsRef = useRef<EntityCollection[] | undefined>();
-    const viewsRef = useRef<CMSView[] | undefined>();
-    const adminViewsRef = useRef<CMSView[] | undefined>();
-    const navigationEntriesOrderRef = useRef<string[] | undefined>();
+    const collectionsRef = useRef<EntityCollection[] | undefined>(undefined);
+    const viewsRef = useRef<CMSView[] | undefined>(undefined);
+    const adminViewsRef = useRef<CMSView[] | undefined>(undefined);
+    const navigationEntriesOrderRef = useRef<string[] | undefined>(undefined);
 
     const [initialised, setInitialised] = useState<boolean>(false);
 
@@ -140,8 +139,12 @@ export function useBuildNavigationController<EC extends EntityCollection, USER e
 
     const fullCollectionPath = cleanBasePath ? `/${cleanBasePath}/${cleanBaseCollectionPath}` : `/${cleanBaseCollectionPath}`;
 
-    const buildCMSUrlPath = useCallback((path: string): string => cleanBasePath ? `/${cleanBasePath}/${encodePath(path)}` : `/${encodePath(path)}`,
-        [cleanBasePath]);
+
+    const buildCMSUrlPath = useCallback((path: string): string => {
+        // Strip trailing /* wildcard from paths (used for nested routes in React Router)
+        const cleanPath = path.replace(/\/\*$/, "");
+        return cleanBasePath ? `/${cleanBasePath}/${encodePath(cleanPath)}` : `/${encodePath(cleanPath)}`;
+    }, [cleanBasePath]);
 
     const buildUrlCollectionPath = useCallback((path: string): string => `${removeInitialAndTrailingSlashes(baseCollectionPath)}/${encodePath(path)}`,
         [baseCollectionPath]);
@@ -185,7 +188,7 @@ export function useBuildNavigationController<EC extends EntityCollection, USER e
                     path: pathKey,
                     collection,
                     description: collection.description?.trim(),
-                    group: groupName ?? NAVIGATION_DEFAULT_GROUP_NAME
+                    group: groupName
                 });
                 return acc;
             }, [] as NavigationEntry[]),
@@ -213,7 +216,7 @@ export function useBuildNavigationController<EC extends EntityCollection, USER e
                     path: view.path,
                     view,
                     description: view.description?.trim(),
-                    group: groupName ?? NAVIGATION_DEFAULT_GROUP_NAME
+                    group: groupName
                 });
                 return acc;
             }, [] as NavigationEntry[]),
@@ -238,7 +241,7 @@ export function useBuildNavigationController<EC extends EntityCollection, USER e
             }, [] as NavigationEntry[])
         ];
 
-        const groupOrderValue = (groupName?: string): number => {
+        const groupOrderValue = (groupName?: string | null): number => {
             if (groupName === NAVIGATION_ADMIN_GROUP_NAME) return 1;
             return 0; // Other groups
         };
@@ -262,7 +265,10 @@ export function useBuildNavigationController<EC extends EntityCollection, USER e
 
         const collectedGroupsFromEntries = navigationEntries
             .map(e => e.group)
-            .filter(Boolean) as string[];
+            .filter((g): g is string => g !== null && Boolean(g));
+
+        // Check if there are any ungrouped entries
+        const hasUngroupedEntries = navigationEntries.some(e => e.group === null && e.type !== "admin");
 
         // Preserve order from finalNavigationGroupMappings (persisted order)
         const groupsFromMappings = finalNavigationGroupMappings.map(g => g.name);
@@ -280,7 +286,12 @@ export function useBuildNavigationController<EC extends EntityCollection, USER e
         const uniqueGroupsArray = [...new Set(allDefinedGroups)];
         const adminGroups = uniqueGroupsArray.filter(g => g === NAVIGATION_ADMIN_GROUP_NAME);
         const nonAdminGroups = uniqueGroupsArray.filter(g => g !== NAVIGATION_ADMIN_GROUP_NAME);
-        const uniqueGroups = [...nonAdminGroups, ...adminGroups];
+        // Place null (ungrouped) first if there are ungrouped entries
+        const uniqueGroups: (string | null)[] = [
+            ...(hasUngroupedEntries ? [null] : []),
+            ...nonAdminGroups,
+            ...adminGroups
+        ];
 
         return {
             allowDragAndDrop: plugins?.some(plugin => plugin.homePage?.allowDragAndDrop) ?? false,
@@ -331,10 +342,10 @@ export function useBuildNavigationController<EC extends EntityCollection, USER e
         try {
 
             const [resolvedCollections = [], resolvedViews, resolvedAdminViews = []] = await Promise.all([
-                    resolveCollections(collectionsProp, collectionPermissions, authController, dataSourceDelegate, plugins),
-                    resolveCMSViews(viewsProp, authController, dataSourceDelegate),
-                    resolveCMSViews(adminViewsProp, authController, dataSourceDelegate)
-                ]
+                resolveCollections(collectionsProp, collectionPermissions, authController, dataSourceDelegate, plugins),
+                resolveCMSViews(viewsProp, authController, dataSourceDelegate, plugins),
+                resolveCMSViews(adminViewsProp, authController, dataSourceDelegate)
+            ]
             );
 
             const computedTopLevelNav = computeTopNavigation(resolvedCollections, resolvedViews, resolvedAdminViews, viewsOrder, undefined, onNavigationEntriesOrderUpdate);
@@ -483,8 +494,10 @@ export function useBuildNavigationController<EC extends EntityCollection, USER e
 
     const urlPathToDataPath = useCallback((path: string): string => {
         const decodedPath = decodeURIComponent(path);
-        if (decodedPath.startsWith(fullCollectionPath))
-            return decodedPath.replace(fullCollectionPath, "");
+        const withoutHash = decodedPath.split("#")[0];
+        const cleanPath = withoutHash.split("?")[0];
+        if (cleanPath.startsWith(fullCollectionPath))
+            return cleanPath.replace(fullCollectionPath, "");
         throw Error("Expected path starting with " + fullCollectionPath);
     }, [fullCollectionPath]);
 
@@ -561,9 +574,27 @@ export function useBuildNavigationController<EC extends EntityCollection, USER e
 }
 
 function encodePath(input: string) {
-    return encodeURIComponent(removeInitialAndTrailingSlashes(input))
-        .replaceAll("%2F", "/")
-        .replaceAll("%23", "#");
+    const cleanInput = removeInitialAndTrailingSlashes(input);
+    const [pathPart, rest] = cleanInput.split("?", 2);
+
+    let encodedPath = encodeURIComponent(pathPart).replaceAll("%2F", "/");
+    let result = encodedPath;
+
+    if (rest !== undefined) {
+        const [searchPart, hashPart] = rest.split("#", 2);
+        result += `?${searchPart}`;
+        if (hashPart !== undefined) {
+            result += `#${hashPart}`;
+        }
+    } else {
+        const [pathOnly, hashOnly] = cleanInput.split("#", 2);
+        if (hashOnly !== undefined) {
+            encodedPath = encodeURIComponent(pathOnly).replaceAll("%2F", "/");
+            result = `${encodedPath}#${hashOnly}`;
+        }
+    }
+
+    return result;
 }
 
 function filterOutNotAllowedCollections(resolvedCollections: EntityCollection[], authController: AuthController<User>): EntityCollection[] {
@@ -597,10 +628,10 @@ function applyPluginModifyCollection(resolvedCollections: EntityCollection[], mo
 }
 
 async function resolveCollections(collections: undefined | EntityCollection[] | EntityCollectionsBuilder<any>,
-                                  collectionPermissions: PermissionsBuilder | undefined,
-                                  authController: AuthController,
-                                  dataSource: DataSourceDelegate,
-                                  plugins: FireCMSPlugin[] | undefined): Promise<EntityCollection[]> {
+    collectionPermissions: PermissionsBuilder | undefined,
+    authController: AuthController,
+    dataSource: DataSourceDelegate,
+    plugins: FireCMSPlugin[] | undefined): Promise<EntityCollection[]> {
     let resolvedCollections: EntityCollection[] = [];
     if (typeof collections === "function") {
         resolvedCollections = await collections({
@@ -629,7 +660,12 @@ async function resolveCollections(collections: undefined | EntityCollection[] |
     return resolvedCollections;
 }
 
-async function resolveCMSViews(baseViews: CMSView[] | CMSViewsBuilder | undefined, authController: AuthController, dataSource: DataSourceDelegate) {
+async function resolveCMSViews(
+    baseViews: CMSView[] | CMSViewsBuilder | undefined,
+    authController: AuthController,
+    dataSource: DataSourceDelegate,
+    plugins?: FireCMSPlugin[]
+) {
     let resolvedViews: CMSView[] = [];
     if (typeof baseViews === "function") {
         resolvedViews = await baseViews({
@@ -640,15 +676,25 @@ async function resolveCMSViews(baseViews: CMSView[] | CMSViewsBuilder | undefine
     } else if (Array.isArray(baseViews)) {
         resolvedViews = baseViews;
     }
+
+    // Inject views from plugins
+    if (plugins) {
+        for (const plugin of plugins) {
+            if (plugin.views && plugin.views.length > 0) {
+                resolvedViews = [...resolvedViews, ...plugin.views];
+            }
+        }
+    }
+
     return resolvedViews;
 }
 
-function getGroup(collectionOrView: EntityCollection<any, any> | CMSView) {
+function getGroup(collectionOrView: EntityCollection<any, any> | CMSView): string | null {
     const trimmed = collectionOrView.group?.trim();
     if (!trimmed || trimmed === "") {
-        return NAVIGATION_DEFAULT_GROUP_NAME;
+        return null;
     }
-    return trimmed ?? NAVIGATION_DEFAULT_GROUP_NAME;
+    return trimmed;
 }
 
 function areCollectionListsEqual(a: EntityCollection[], b: EntityCollection[]) {
@@ -688,8 +734,8 @@ function useCustomBlocker(): NavigationBlocker {
     let blocker: any;
     try {
         blocker = useBlocker(({
-                                  nextLocation
-                              }) => {
+            nextLocation
+        }) => {
             const allBasePaths = Object.values(blockListeners).map(b => b.basePath).filter(Boolean) as string[];
             if (allBasePaths && allBasePaths.some(path => nextLocation.pathname.startsWith(path)))
                 return false;
@@ -729,11 +775,11 @@ function useCustomBlocker(): NavigationBlocker {
 }
 
 function computeNavigationGroups({
-                                     navigationGroupMappings,
-                                     collections,
-                                     views,
-                                     plugins
-                                 }: {
+    navigationGroupMappings,
+    collections,
+    views,
+    plugins
+}: {
     navigationGroupMappings?: NavigationGroupMapping[],
     collections?: EntityCollection[],
     views?: CMSView[],
@@ -743,6 +789,7 @@ function computeNavigationGroups({
     let result = navigationGroupMappings;
 
     // Merge plugin navigation entries
+    // IMPORTANT: Deep clone the groups to avoid mutating the original input
     result = plugins ? plugins?.reduce((acc, plugin) => {
         if (plugin.homePage?.navigationEntries) {
             plugin.homePage.navigationEntries.forEach((entry) => {
@@ -763,7 +810,10 @@ function computeNavigationGroups({
 
         }
         return acc;
-    }, [...(result ?? [])] as NavigationGroupMapping[]) : result;
+    }, (result ?? []).map(g => ({
+        name: g.name,
+        entries: [...g.entries]
+    }))) : result;
 
     // Track all entries that are already assigned to groups
     const assignedEntries = new Set<string>();
@@ -780,7 +830,7 @@ function computeNavigationGroups({
     (collections ?? []).forEach(collection => {
         const entry = collection.id ?? collection.path;
         if (!assignedEntries.has(entry)) {
-            const groupName = getGroup(collection);
+            const groupName = getGroup(collection) ?? "__default__";
             if (!unassignedGroupMap[groupName]) unassignedGroupMap[groupName] = [];
             unassignedGroupMap[groupName].push(entry);
         }
@@ -790,7 +840,7 @@ function computeNavigationGroups({
     (views ?? []).forEach(view => {
         const entry = view.path;
         if (!assignedEntries.has(entry)) {
-            const groupName = getGroup(view);
+            const groupName = getGroup(view) ?? "__default__";
             if (!unassignedGroupMap[groupName]) unassignedGroupMap[groupName] = [];
             unassignedGroupMap[groupName].push(entry);
         }
@@ -818,7 +868,7 @@ function computeNavigationGroups({
 
         // Add collections
         (collections ?? []).forEach(collection => {
-            const name = getGroup(collection);
+            const name = getGroup(collection) ?? "__default__";
             const entry = collection.id ?? collection.path;
             if (!groupMap[name]) groupMap[name] = [];
             groupMap[name].push(entry);
@@ -826,7 +876,7 @@ function computeNavigationGroups({
 
         // Add views
         (views ?? []).forEach(view => {
-            const name = getGroup(view);
+            const name = getGroup(view) ?? "__default__";
             const entry = view.path;
             if (!groupMap[name]) groupMap[name] = [];
             groupMap[name].push(entry);

package/src/hooks/useCollapsedGroups.ts

@@ -1,15 +1,22 @@
 import { useCallback, useEffect, useState } from "react";
 
+const STORAGE_KEY_PREFIX = "firecms-collapsed-groups";
+
 /**
  * Custom hook for managing collapsed/expanded state of navigation groups
  * with localStorage persistence. Automatically cleans up stale group entries
  * when groups are removed from the navigation.
+ * 
+ * @param groupNames - Array of group names to track
+ * @param namespace - Namespace for localStorage key (e.g., "home", "drawer") to allow independent state
  */
-export function useCollapsedGroups(groupNames: string[]) {
+export function useCollapsedGroups(groupNames: (string | null)[], namespace: string = "default") {
+    const storageKey = `${STORAGE_KEY_PREFIX}-${namespace}`;
+
     // Load collapsed groups from localStorage on mount
     const [collapsedGroups, setCollapsedGroups] = useState<Record<string, boolean>>(() => {
         try {
-            const stored = localStorage.getItem('firecms-collapsed-groups');
+            const stored = localStorage.getItem(storageKey);
             return stored ? JSON.parse(stored) : {};
         } catch {
             return {};
@@ -19,18 +26,18 @@ export function useCollapsedGroups(groupNames: string[]) {
     // Save to localStorage whenever collapsedGroups changes
     useEffect(() => {
         try {
-            localStorage.setItem('firecms-collapsed-groups', JSON.stringify(collapsedGroups));
+            localStorage.setItem(storageKey, JSON.stringify(collapsedGroups));
         } catch {
             // Silently fail if localStorage is not available
         }
-    }, [collapsedGroups]);
+    }, [collapsedGroups, storageKey]);
 
     // Clean up collapsed groups state when groups change - remove entries for groups that no longer exist
     useEffect(() => {
         // Only clean up if we have actual groups loaded (avoid cleaning up during initial load)
         if (groupNames.length === 0) return;
 
-        const currentGroupNames = new Set(groupNames);
+        const currentGroupNames = new Set(groupNames.map(g => g ?? "__default__"));
 
         setCollapsedGroups(prev => {
             const cleaned = Object.fromEntries(
@@ -49,12 +56,13 @@ export function useCollapsedGroups(groupNames: string[]) {
         });
     }, [groupNames]);
 
-    const isGroupCollapsed = useCallback((name: string) => {
-        return !!collapsedGroups[name];
+    const isGroupCollapsed = useCallback((name?: string | null) => {
+        return !!collapsedGroups[name ?? "__default__"];
     }, [collapsedGroups]);
 
-    const toggleGroupCollapsed = useCallback((name: string) => {
-        setCollapsedGroups(prev => ({ ...prev, [name]: !prev[name] }));
+    const toggleGroupCollapsed = useCallback((name?: string | null) => {
+        const key = name ?? "__default__";
+        setCollapsedGroups(prev => ({ ...prev, [key]: !prev[key] }));
     }, []);
 
     return {
@@ -62,3 +70,4 @@ export function useCollapsedGroups(groupNames: string[]) {
         toggleGroupCollapsed
     };
 }
+

package/src/hooks/useTranslation.ts

@@ -0,0 +1,31 @@
+import { useTranslation as useI18nTranslation } from "react-i18next";
+
+const FIRECMS_NS = "firecms_core";
+
+/**
+ * Internal hook for translating FireCMS UI strings.
+ *
+ * Uses the `firecms_core` i18next namespace that is initialised by
+ * `FireCMSi18nProvider`. Do NOT use `react-i18next` directly in internal
+ * components — always go through this hook so the namespace is consistent.
+ *
+ * @example
+ * const { t } = useTranslation();
+ * <Button>{t("save")}</Button>
+ *
+ * @internal
+ */
+export function useTranslation() {
+    const { t, i18n } = useI18nTranslation(FIRECMS_NS);
+
+    /**
+     * Typed translation function scoped to FirecmsTranslations keys.
+     * Also supports i18next interpolation variables, e.g.
+     *   t("add_to_field", { fieldName: "Tags" })
+     *   t("error_deleting", { message: err.message })
+     */
+    const typedT = (key: string, vars?: Record<string, string>): string =>
+        t(key, vars) as string;
+
+    return { t: typedT, i18n };
+}

package/src/hooks/useValidateAuthenticator.tsx

@@ -51,7 +51,7 @@ export function useValidateAuthenticator<USER extends User = any>
      * We use this ref to check the authentication only if the user has
      * changed.
      */
-    const checkedUserRef = useRef<User | undefined>();
+    const checkedUserRef = useRef<User | undefined>(undefined);
 
     const checkAuthentication = useCallback(async () => {
 

package/src/i18n/FireCMSi18nProvider.tsx

@@ -0,0 +1,160 @@
+import React, { PropsWithChildren, useEffect, useRef } from "react";
+import i18next, { i18n } from "i18next";
+import { I18nextProvider, initReactI18next } from "react-i18next";
+import { en } from "../locales/en";
+import { es } from "../locales/es";
+import { de } from "../locales/de";
+import { fr } from "../locales/fr";
+import { it } from "../locales/it";
+import { hi } from "../locales/hi";
+import { pt } from "../locales/pt";
+import { FireCMSTranslations } from "../types/translations";
+
+const FIRECMS_NS = "firecms_core";
+
+export const FIRECMS_LOCALE_STORAGE_KEY = "firecms_locale";
+
+/** DeepPartial helper — allows partial overrides at any nesting level */
+type DeepPartial<T> = T extends object
+    ? { [K in keyof T]?: DeepPartial<T[K]> }
+    : T;
+
+export interface FireCMSi18nProviderProps {
+    /** BCP-47 locale tag, e.g. "en", "es", "fr". Defaults to "en". */
+    locale?: string;
+    /**
+     * Override or extend any FireCMS UI string, keyed by locale.
+     *
+     * @example
+     * translations={{
+     *   en: { save: "Publish" },
+     *   es: { save: "Publicar", discard: "Descartar" }
+     * }}
+     */
+    translations?: {
+        [locale: string]: DeepPartial<FireCMSTranslations>;
+    };
+}
+
+/**
+ * Initialises a dedicated i18next instance for FireCMS's internal UI strings.
+ *
+ * This instance is isolated from any app-level i18next configuration the
+ * consumer may have. Mount this at the top of the FireCMS component tree.
+ *
+ * @internal
+ */
+export function FireCMSi18nProvider({
+    locale = "en",
+    translations,
+    children
+}: PropsWithChildren<FireCMSi18nProviderProps>) {
+    const i18nRef = useRef<i18n | null>(null);
+    const [ready, setReady] = React.useState(false);
+
+    if (!i18nRef.current) {
+        const instance = i18next.createInstance();
+
+        // Build the initial resources: English baseline + any consumer overrides
+        const resources = buildResources(translations);
+
+        let initialLocale = locale;
+        if (typeof window !== "undefined") {
+            const stored = localStorage.getItem(FIRECMS_LOCALE_STORAGE_KEY);
+            if (stored) initialLocale = stored;
+        }
+
+        instance
+            .use(initReactI18next)
+            .init({
+                lng: initialLocale,
+                fallbackLng: "en",
+                ns: [FIRECMS_NS],
+                defaultNS: FIRECMS_NS,
+                resources,
+                interpolation: {
+                    // React already escapes — don't double-escape
+                    escapeValue: false,
+                },
+            }, () => {
+                setReady(true);
+            });
+
+        instance.on("languageChanged", (lng) => {
+            if (typeof window !== "undefined") {
+                localStorage.setItem(FIRECMS_LOCALE_STORAGE_KEY, lng);
+            }
+        });
+
+        i18nRef.current = instance;
+    }
+
+    // When `locale` prop changes, switch language on the existing instance
+    // ONLY if the user hasn't explicitly set a preference
+    useEffect(() => {
+        if (i18nRef.current && i18nRef.current.language !== locale) {
+            const hasUserPreference = typeof window !== "undefined" && Boolean(localStorage.getItem(FIRECMS_LOCALE_STORAGE_KEY));
+            if (!hasUserPreference) {
+                i18nRef.current.changeLanguage(locale);
+            }
+        }
+    }, [locale]);
+
+    // When consumer translations prop changes, update the resource bundles
+    useEffect(() => {
+        if (!i18nRef.current) return;
+        const resources = buildResources(translations);
+        for (const [lang, bundle] of Object.entries(resources)) {
+            i18nRef.current.addResourceBundle(
+                lang,
+                FIRECMS_NS,
+                bundle[FIRECMS_NS],
+                true,  // deep merge
+                true   // overwrite existing keys
+            );
+        }
+    }, [translations]);
+
+    if (!ready || !i18nRef.current) return null;
+
+    return (
+        <I18nextProvider i18n={i18nRef.current}>
+            {children}
+        </I18nextProvider>
+    );
+}
+
+/**
+ * Build an i18next resources object from the English baseline plus any
+ * consumer-provided overrides.
+ */
+function buildResources(
+    translations?: { [locale: string]: DeepPartial<FireCMSTranslations> }
+): Record<string, Record<string, object>> {
+    const resources: Record<string, Record<string, object>> = {
+        en: { [FIRECMS_NS]: { ...en } },
+        es: { [FIRECMS_NS]: { ...es } },
+        de: { [FIRECMS_NS]: { ...de } },
+        fr: { [FIRECMS_NS]: { ...fr } },
+        it: { [FIRECMS_NS]: { ...it } },
+        hi: { [FIRECMS_NS]: { ...hi } },
+        pt: { [FIRECMS_NS]: { ...pt } },
+    };
+
+    if (!translations) return resources;
+
+    for (const [lang, overrides] of Object.entries(translations)) {
+        if (!resources[lang]) {
+            // For non-English/Spanish locales, start from English as the fallback base
+            resources[lang] = { [FIRECMS_NS]: { ...en } };
+        }
+        // Merge consumer overrides (shallow merge is enough since translations
+        // is a flat record — deepMerge option in addResourceBundle handles deeper)
+        resources[lang][FIRECMS_NS] = {
+            ...resources[lang][FIRECMS_NS],
+            ...overrides,
+        };
+    }
+
+    return resources;
+}

package/src/index.ts

@@ -7,3 +7,8 @@ export * from "./hooks";
 export * from "./components";
 export * from "./util";
 export * from "./contexts";
+export * from "./i18n/FireCMSi18nProvider";
+export * from "./locales/en";
+export * from "./locales/es";
+export * from "./editor";
+export * from "./util/objects";