@firecms/core 3.1.0 → 3.2.0-canary.4c3b8f2

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> = {
@@ -189,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[]),
@@ -217,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[]),
@@ -242,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
         };
@@ -266,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);
@@ -284,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,
@@ -487,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]);
 
@@ -565,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[] {
@@ -662,12 +689,12 @@ async function resolveCMSViews(
     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[]) {
@@ -803,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);
         }
@@ -813,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);
         }
@@ -841,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);
@@ -849,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

@@ -10,7 +10,7 @@ const STORAGE_KEY_PREFIX = "firecms-collapsed-groups";
  * @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[], namespace: string = "default") {
+export function useCollapsedGroups(groupNames: (string | null)[], namespace: string = "default") {
     const storageKey = `${STORAGE_KEY_PREFIX}-${namespace}`;
 
     // Load collapsed groups from localStorage on mount
@@ -37,7 +37,7 @@ export function useCollapsedGroups(groupNames: string[], namespace: string = "de
         // 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(
@@ -56,12 +56,13 @@ export function useCollapsedGroups(groupNames: string[], namespace: string = "de
         });
     }, [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 {

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/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,7 @@ 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";

package/src/internal/useBuildSideEntityController.tsx

@@ -99,8 +99,8 @@ function getNestedPropertiesDepth(property: ResolvedProperty, accumulator: numbe
 }
 
 export const useBuildSideEntityController = (navigation: NavigationController,
-                                             sideDialogsController: SideDialogsController,
-                                             authController: AuthController
+    sideDialogsController: SideDialogsController,
+    authController: AuthController
 ): SideEntityController => {
 
     const location = useLocation();
@@ -121,9 +121,9 @@ export const useBuildSideEntityController = (navigation: NavigationController,
                 for (let i = 0; i < panelsFromUrl.length; i++) {
                     const props = panelsFromUrl[i];
                     if (i === 0)
-                        sideDialogsController.replace(propsToSidePanel(props, navigation.buildUrlCollectionPath, navigation.resolveIdsFrom, smallLayout, customizationController, authController));
+                        sideDialogsController.replace(propsToSidePanel(props, navigation.buildUrlCollectionPath, navigation.resolveIdsFrom, smallLayout, customizationController, authController, location.search));
                     else
-                        sideDialogsController.open(propsToSidePanel(props, navigation.buildUrlCollectionPath, navigation.resolveIdsFrom, smallLayout, customizationController, authController))
+                        sideDialogsController.open(propsToSidePanel(props, navigation.buildUrlCollectionPath, navigation.resolveIdsFrom, smallLayout, customizationController, authController, location.search))
                 }
             }
             initialised.current = true;
@@ -143,7 +143,7 @@ export const useBuildSideEntityController = (navigation: NavigationController,
                     return;
                 }
                 const lastPanel = panelsFromUrl[panelsFromUrl.length - 1];
-                const panelProps = propsToSidePanel(lastPanel, navigation.buildUrlCollectionPath, navigation.resolveIdsFrom, smallLayout, customizationController, authController);
+                const panelProps = propsToSidePanel(lastPanel, navigation.buildUrlCollectionPath, navigation.resolveIdsFrom, smallLayout, customizationController, authController, location.search);
                 const lastCurrentPanel = currentPanelKeys.length > 0 ? currentPanelKeys[currentPanelKeys.length - 1] : undefined;
                 if (!lastCurrentPanel || lastCurrentPanel !== panelProps.key) {
                     sideDialogsController.replace(panelProps);
@@ -156,7 +156,7 @@ export const useBuildSideEntityController = (navigation: NavigationController,
     useEffect(() => {
         const updatedSidePanels = sideDialogsController.sidePanels.map(sidePanelProps => {
             if (sidePanelProps.additional) {
-                return propsToSidePanel(sidePanelProps.additional, navigation.buildUrlCollectionPath, navigation.resolveIdsFrom, smallLayout, customizationController, authController);
+                return propsToSidePanel(sidePanelProps.additional, navigation.buildUrlCollectionPath, navigation.resolveIdsFrom, smallLayout, customizationController, authController, location.search);
             }
             return sidePanelProps;
         });
@@ -183,17 +183,18 @@ export const useBuildSideEntityController = (navigation: NavigationController,
 
         sideDialogsController.open(
             propsToSidePanel({
-                    selectedTab: defaultSelectedView,
-                    ...props
-                },
+                selectedTab: defaultSelectedView,
+                ...props
+            },
                 navigation.buildUrlCollectionPath,
                 navigation.resolveIdsFrom,
                 smallLayout,
                 customizationController,
-                authController
+                authController,
+                location.search
             ));
 
-    }, [sideDialogsController, navigation.buildUrlCollectionPath, navigation.resolveIdsFrom, smallLayout, authController.user]);
+    }, [sideDialogsController, navigation.buildUrlCollectionPath, navigation.resolveIdsFrom, smallLayout, authController.user, location.search]);
 
     const replace = useCallback((props: EntitySidePanelProps<any>) => {
 
@@ -201,9 +202,9 @@ export const useBuildSideEntityController = (navigation: NavigationController,
             throw Error("If you want to copy an entity you need to provide an entityId");
         }
 
-        sideDialogsController.replace(propsToSidePanel(props, navigation.buildUrlCollectionPath, navigation.resolveIdsFrom, smallLayout, customizationController, authController));
+        sideDialogsController.replace(propsToSidePanel(props, navigation.buildUrlCollectionPath, navigation.resolveIdsFrom, smallLayout, customizationController, authController, location.search));
 
-    }, [navigation.buildUrlCollectionPath, navigation.resolveIdsFrom, sideDialogsController, smallLayout, authController.user]);
+    }, [navigation.buildUrlCollectionPath, navigation.resolveIdsFrom, sideDialogsController, smallLayout, authController.user, location.search]);
 
     return {
         close,
@@ -265,18 +266,19 @@ export function buildSidePanelsFromUrl(path: string, collections: EntityCollecti
 }
 
 const propsToSidePanel = (props: EntitySidePanelProps,
-                          buildUrlCollectionPath: (path: string) => string,
-                          resolveIdsFrom: (pathWithAliases: string) => string,
-                          smallLayout: boolean,
-                          customizationController: CustomizationController,
-                          authController: AuthController
+    buildUrlCollectionPath: (path: string) => string,
+    resolveIdsFrom: (pathWithAliases: string) => string,
+    smallLayout: boolean,
+    customizationController: CustomizationController,
+    authController: AuthController,
+    locationSearch: string
 ): SideDialogPanelProps => {
 
     const collectionPath = removeInitialAndTrailingSlashes(props.path);
 
     const urlPath = props.entityId
-        ? buildUrlCollectionPath(`${collectionPath}/${props.entityId}${props.selectedTab ? "/" + props.selectedTab : ""}#${SIDE_URL_HASH}`)
-        : buildUrlCollectionPath(`${collectionPath}#${NEW_URL_HASH}`);
+        ? buildUrlCollectionPath(`${collectionPath}/${props.entityId}${props.selectedTab ? "/" + props.selectedTab : ""}${locationSearch}#${SIDE_URL_HASH}`)
+        : buildUrlCollectionPath(`${collectionPath}${locationSearch}#${NEW_URL_HASH}`);
 
     const resolvedPanelProps: EntitySidePanelProps<any> = {
         ...props,