@firecms/core 3.1.0-canary.1df3b2c → 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;
@@ -52,18 +55,18 @@ const rejectDropClasses = "transition-colors duration-200 ease-[cubic-bezier(0,0
 type StorageUploadFieldProps = FieldProps<string | string[]>;
 
 export function StorageUploadFieldBinding({
-                                              propertyKey,
-                                              value,
-                                              setValue,
-                                              error,
-                                              showError,
-                                              autoFocus,
-                                              minimalistView,
-                                              property,
-                                              includeDescription,
-                                              context,
-                                              isSubmitting,
-                                          }: StorageUploadFieldProps) {
+    propertyKey,
+    value,
+    setValue,
+    error,
+    showError,
+    autoFocus,
+    minimalistView,
+    property,
+    includeDescription,
+    context,
+    isSubmitting,
+}: StorageUploadFieldProps) {
 
     const authController = useAuthController();
 
@@ -100,7 +103,7 @@ export function StorageUploadFieldBinding({
     });
 
     const resolvedProperty = resolveProperty({
-        propertyOrBuilder: property as PropertyOrBuilder,
+        propertyOrBuilder: property as PropertyOrBuilder<string>,
         authController
     }) as ResolvedStringProperty | ResolvedArrayProperty<string[]>;
 
@@ -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}
@@ -128,14 +146,13 @@ export function StorageUploadFieldBinding({
                 onFileUploadComplete={onFileUploadComplete}
                 storagePathBuilder={storagePathBuilder}
                 storage={storage}
-                multipleFilesSupported={multipleFilesSupported}/>
+                multipleFilesSupported={multipleFilesSupported} />
 
             <FieldHelperText includeDescription={includeDescription}
-                             showError={showError}
-                             error={error}
-                             disabled={disabled}
-                             property={property}/>
-
+                showError={showError}
+                error={error}
+                disabled={disabled}
+                property={property} />
         </>
     );
 }
@@ -154,15 +171,15 @@ interface SortableStorageItemProps {
 }
 
 function SortableStorageItem({
-                                 id,
-                                 entry,
-                                 property,
-                                 metadata,
-                                 storagePathBuilder,
-                                 onFileUploadComplete,
-                                 onClear,
-                                 disabled,
-                             }: SortableStorageItemProps) {
+    id,
+    entry,
+    property,
+    metadata,
+    storagePathBuilder,
+    onFileUploadComplete,
+    onClear,
+    disabled,
+}: SortableStorageItemProps) {
 
     const {
         attributes,
@@ -201,7 +218,7 @@ function SortableStorageItem({
                 disabled={disabled}
                 value={entry.storagePathOrDownloadUrl}
                 onRemove={() => onClear(entry.storagePathOrDownloadUrl!)}
-                size={entry.size}/>
+                size={entry.size} />
         );
     } else if (entry.file) {
         child = (
@@ -231,21 +248,21 @@ function SortableStorageItem({
 }
 
 function FileDropComponent({
-                               storage,
-                               disabled,
-                               onFilesAdded,
-                               multipleFilesSupported,
-                               autoFocus,
-                               internalValue,
-                               property,
-                               onClear,
-                               metadata,
-                               storagePathBuilder,
-                               onFileUploadComplete,
-                               name,
-                               helpText,
-                               isDndItemDragging
-                           }: {
+    storage,
+    disabled,
+    onFilesAdded,
+    multipleFilesSupported,
+    autoFocus,
+    internalValue,
+    property,
+    onClear,
+    metadata,
+    storagePathBuilder,
+    onFileUploadComplete,
+    name,
+    helpText,
+    isDndItemDragging
+}: {
     storage: StorageConfig,
     disabled: boolean,
     onFilesAdded: (acceptedFiles: File[]) => Promise<void>,
@@ -271,33 +288,33 @@ function FileDropComponent({
         isDragAccept,
         isDragReject
     } = useDropzone({
-            accept: storage.acceptedFiles ? storage.acceptedFiles.reduce((acc, ext) => ({
-                ...acc,
-                [ext]: []
-            }), {}) : undefined,
-            disabled: disabled || isDndItemDragging,
-            noDragEventsBubbling: true,
-            maxSize: storage.maxSize,
-            onDrop: onFilesAdded,
-            onDropRejected: (fileRejections) => {
-                for (const fileRejection of fileRejections) {
-                    for (const error of fileRejection.errors) {
-                        console.error("Error uploading file: ", error);
-                        if (error.code === "file-too-large") {
-                            snackbarContext.open({
-                                type: "error",
-                                message: `Error uploading file: File is larger than ${storage.maxSize} bytes`
-                            });
-                        } else if (error.code === "file-invalid-type") {
-                            snackbarContext.open({
-                                type: "error",
-                                message: "Error uploading file: File type is not supported"
-                            });
-                        }
+        accept: storage.acceptedFiles ? storage.acceptedFiles.reduce((acc, ext) => ({
+            ...acc,
+            [ext]: []
+        }), {}) : undefined,
+        disabled: disabled || isDndItemDragging,
+        noDragEventsBubbling: true,
+        maxSize: storage.maxSize,
+        onDrop: onFilesAdded,
+        onDropRejected: (fileRejections) => {
+            for (const fileRejection of fileRejections) {
+                for (const error of fileRejection.errors) {
+                    console.error("Error uploading file: ", error);
+                    if (error.code === "file-too-large") {
+                        snackbarContext.open({
+                            type: "error",
+                            message: `Error uploading file: File is larger than ${storage.maxSize} bytes`
+                        });
+                    } else if (error.code === "file-invalid-type") {
+                        snackbarContext.open({
+                            type: "error",
+                            message: "Error uploading file: File type is not supported"
+                        });
                     }
                 }
             }
         }
+    }
     );
 
     return (
@@ -349,8 +366,8 @@ function FileDropComponent({
             <div
                 className="flex-grow min-h-[38px] box-border m-2 text-center">
                 <Typography align={"center"}
-                            variant={"label"}
-                            className={disabled ? "text-surface-accent-600 dark:text-surface-accent-500" : ""}>
+                    variant={"label"}
+                    className={disabled ? "text-surface-accent-600 dark:text-surface-accent-500" : ""}>
                     {helpText}
                 </Typography>
             </div>
@@ -374,19 +391,20 @@ export interface StorageUploadProps {
 }
 
 export function StorageUpload({
-                                  property,
-                                  name,
-                                  value, // This is internalValue from useStorageUploadController
-                                  setInternalValue,
-                                  onChange,
-                                  multipleFilesSupported,
-                                  onFileUploadComplete,
-                                  disabled,
-                                  onFilesAdded,
-                                  autoFocus,
-                                  storage,
-                                  storagePathBuilder,
-                              }: StorageUploadProps) {
+    property,
+    name,
+    value, // This is internalValue from useStorageUploadController
+    setInternalValue,
+    onChange,
+    multipleFilesSupported,
+    onFileUploadComplete,
+    disabled,
+    onFilesAdded,
+    autoFocus,
+    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
@@ -500,6 +518,6 @@ export function StorageUpload({
         );
     } else {
         // For single file, no D&D context is needed
-        return <FileDropComponent {...fileDropProps} isDndItemDragging={false}/>;
+        return <FileDropComponent {...fileDropProps} isDndItemDragging={false} />;
     }
 }

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> = {
@@ -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);
 
@@ -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 };
+}