@firecms/core 3.1.0-canary.24c8270 → 3.1.0-canary.501d471

package/src/form/field_bindings/StorageUploadFieldBinding.tsx

@@ -38,9 +38,12 @@ import {
     fieldBackgroundDisabledMixin,
     fieldBackgroundHoverMixin,
     fieldBackgroundMixin,
-    Typography
+    Typography,
+    IconButton,
+    CloseIcon
 } from "@firecms/ui";
 import { useClearRestoreValue } from "../useClearRestoreValue";
+import { useTranslation } from "../../hooks/useTranslation";
 
 const dropZoneClasses = "box-border relative pt-[2px] items-center border border-transparent min-h-[254px] outline-none rounded-md duration-200 ease-[cubic-bezier(0.4,0,0.2,1)] focus:border-primary-solid";
 const disabledClasses = fieldBackgroundDisabledMixin;
@@ -109,12 +112,27 @@ export function StorageUploadFieldBinding({
         <>
 
             {!minimalistView &&
-                <LabelWithIconAndTooltip
-                    propertyKey={propertyKey}
-                    icon={getIconForProperty(property, "small")}
-                    required={property.validation?.required}
-                    title={property.name}
-                    className={"h-8 text-text-secondary dark:text-text-secondary-dark ml-3.5"} />}
+                <div className="flex items-center w-full">
+                    <LabelWithIconAndTooltip
+                        propertyKey={propertyKey}
+                        icon={getIconForProperty(property, "small")}
+                        required={property.validation?.required}
+                        title={property.name}
+                        className={"h-8 text-text-secondary dark:text-text-secondary-dark ml-3.5"} />
+                    <div className="flex-grow"/>
+                    {(property.nullable || property.clearable) && !disabled && (
+                        <IconButton
+                            size="small"
+                            onClick={(e) => {
+                                e.stopPropagation();
+                                e.preventDefault();
+                                setValue(null);
+                            }}
+                        >
+                            <CloseIcon size={"small"}/>
+                        </IconButton>
+                    )}
+                </div>}
 
             <StorageUpload
                 value={internalValue}
@@ -135,7 +153,6 @@ export function StorageUploadFieldBinding({
                 error={error}
                 disabled={disabled}
                 property={property} />
-
         </>
     );
 }
@@ -387,6 +404,7 @@ export function StorageUpload({
     storage,
     storagePathBuilder,
 }: StorageUploadProps) {
+    const { t } = useTranslation();
 
     if (multipleFilesSupported) {
         const arrayProperty = property as ResolvedArrayProperty<string[]>;
@@ -461,8 +479,8 @@ export function StorageUpload({
     }, [value, multipleFilesSupported, onChange, setInternalValue]);
 
     const helpText = multipleFilesSupported
-        ? "Drag 'n' drop some files here, or click to select files. Drag to reorder."
-        : "Drag 'n' drop a file here, or click to select one";
+        ? t("drag_drop_multiple")
+        : t("drag_drop_single");
 
     const renderProperty: ResolvedStringProperty = multipleFilesSupported
         ? (property as ResolvedArrayProperty<string[]>).of as ResolvedStringProperty

package/src/form/field_bindings/SwitchFieldBinding.tsx

@@ -3,7 +3,7 @@ import React from "react";
 import { FieldProps } from "../../types";
 import { getIconForProperty } from "../../util";
 import { FieldHelperText, LabelWithIcon } from "../components";
-import { BooleanSwitchWithLabel } from "@firecms/ui";
+import { BooleanSwitchWithLabel, IconButton, CloseIcon } from "@firecms/ui";
 import { useClearRestoreValue } from "../useClearRestoreValue";
 import { PropertyIdCopyTooltip } from "../../components";
 
@@ -39,19 +39,36 @@ export const SwitchFieldBinding = function SwitchFieldBinding({
         <>
 
             <PropertyIdCopyTooltip propertyKey={propertyKey}>
-                <BooleanSwitchWithLabel
-                    value={value}
-                    onValueChange={(v) => setValue(v)}
-                    error={showError}
-                    className={property.widthPercentage !== undefined ? "mt-8" : undefined}
-                    label={<LabelWithIcon
-                        icon={getIconForProperty(property, "small")}
-                        required={property.validation?.required}
-                        title={property.name}/>}
-                    disabled={disabled}
-                    autoFocus={autoFocus}
-                    size={size}
-                />
+                <div className="flex items-center">
+                    <BooleanSwitchWithLabel
+                        value={value}
+                        onValueChange={(v) => setValue(v)}
+                        error={showError}
+                        className={property.widthPercentage !== undefined ? "mt-8" : undefined}
+                        label={<LabelWithIcon
+                            icon={getIconForProperty(property, "small")}
+                            required={property.validation?.required}
+                            title={property.name}/>}
+                        disabled={disabled}
+                        autoFocus={autoFocus}
+                        size={size}
+                        switchAdornment={
+                            (property.nullable || property.clearable) && !disabled && value !== null && (
+                                <IconButton
+                                    size="small"
+                                    onClick={(e) => {
+                                        e.stopPropagation();
+                                        e.preventDefault();
+                                        setValue(null);
+                                    }}
+                                    className="mr-2"
+                                >
+                                    <CloseIcon size={"small"}/>
+                                </IconButton>
+                            )
+                        }
+                    />
+                </div>
             </PropertyIdCopyTooltip>
 
             <FieldHelperText includeDescription={includeDescription}

package/src/form/field_bindings/TextFieldBinding.tsx

@@ -100,10 +100,10 @@ export function TextFieldBinding<T extends string | number>({
                             showError && error ? "text-red-500 dark:text-red-600" : ""
                         )}
                     />
-                    {property.clearable && (
+                    {(property.nullable || property.clearable) && value !== null && value !== undefined && (
                         <div className="flex flex-row justify-center items-center absolute h-full right-0 top-0 mr-4">
-                            <IconButton onClick={handleClearClick}>
-                                <CloseIcon />
+                            <IconButton size="small" onClick={handleClearClick}>
+                                <CloseIcon size="small" />
                             </IconButton>
                         </div>
                     )}
@@ -119,10 +119,13 @@ export function TextFieldBinding<T extends string | number>({
                     type={inputType}
                     disabled={disabled}
                     endAdornment={
-                        property.clearable && <IconButton
-                            onClick={handleClearClick}>
-                            <CloseIcon />
-                        </IconButton>
+                        (property.nullable || property.clearable) && value !== null && value !== undefined ? (
+                            <IconButton
+                                size="small"
+                                onClick={handleClearClick}>
+                                <CloseIcon size="small" />
+                            </IconButton>
+                        ) : undefined
                     }
                     error={showError ? error : undefined}
                     inputClassName={error ? "text-red-500 dark:text-red-600" : ""} />

package/src/form/field_bindings/UserSelectFieldBinding.tsx

@@ -59,11 +59,13 @@ export function UserSelectFieldBinding({
                         />
                     </PropertyIdCopyTooltip>}
                 endAdornment={
-                    property.clearable && !disabled && value && <IconButton
-                        size="small"
-                        onClick={handleClearClick}>
-                        <CloseIcon size={"small"}/>
-                    </IconButton>
+                    (property.nullable || property.clearable) && !disabled && value !== null && value !== undefined ? (
+                        <IconButton
+                            size="small"
+                            onClick={handleClearClick}>
+                            <CloseIcon size={"small"}/>
+                        </IconButton>
+                    ) : undefined
                 }
                 onValueChange={(updatedValue: string) => {
                     const newValue = updatedValue || null;

package/src/hooks/index.tsx

@@ -31,3 +31,4 @@ export * from "./useBuildLocalConfigurationPersistence";
 export * from "./useBuildModeController";
 
 export * from "./useValidateAuthenticator";
+export * from "./useTranslation";

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,
@@ -682,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[]) {
@@ -823,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);
         }
@@ -833,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);
         }
@@ -861,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);
@@ -869,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,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";