@firecms/core 3.4.0 → 3.5.0

package/src/components/LicenseBanner.tsx

@@ -0,0 +1,287 @@
+import React, { useContext, useState } from "react";
+import { Alert, Button, CloseIcon, IconButton } from "@firecms/ui";
+import { AccessResponse, ProSuggestion } from "../types";
+import { getLicenseSubscribeUrl, PRO_PLUGIN_KEYS } from "../core/pro_plugins";
+import { CustomizationControllerContext } from "../contexts/CustomizationControllerContext";
+import { useLicenseStatus } from "../hooks/useLicenseStatus";
+import { useTranslation } from "../hooks/useTranslation";
+
+const DISMISSED_STORAGE_KEY = "firecms_license_banner_dismissed";
+const DISMISSED_SUGGESTIONS_STORAGE_KEY = "firecms_pro_suggestions_dismissed";
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * @group Components
+ */
+export interface LicenseBannerProps {
+    /**
+     * Applied to the banner's outer element when there is something to show.
+     */
+    className?: string;
+    style?: React.CSSProperties;
+}
+
+type BannerContent = {
+    state: string;
+    color: "info" | "warning";
+    message: string;
+    linkLabel: string;
+    href: string;
+    /**
+     * `session` hides it until the browser session ends, `forever` in this
+     * browser for good.
+     */
+    dismissal: "none" | "session" | "forever";
+};
+
+/**
+ * Where each PRO suggestion links: the plugin's docs, which say how to add it.
+ * The UTM parameters let the website count the clicks.
+ */
+const SUGGESTION_DOCS_URLS: Record<ProSuggestion["plugin"], string> = {
+    user_management: "https://firecms.co/docs/pro/user_management/?utm_source=firecms&utm_medium=cms_suggestion&utm_campaign=user_management",
+    entity_history: "https://firecms.co/docs/pro/entity_history/?utm_source=firecms&utm_medium=cms_suggestion&utm_campaign=entity_history"
+};
+
+/**
+ * Tells the user where their FireCMS PRO license stands: days left in the
+ * trial, or why PRO is paused (the trial ended, the key is not linked to this
+ * project, or the license pays for other projects). Renders nothing when
+ * licensed and while the status is unknown. When no license is needed, it
+ * shows only a PRO plugin the license check suggests for this project, if any.
+ *
+ * The default `Scaffold` already renders it above the main content. Place it
+ * yourself only in a custom layout.
+ *
+ * @group Components
+ */
+export function LicenseBanner({
+                                  className,
+                                  style
+                              }: LicenseBannerProps) {
+
+    const licenseStatus = useLicenseStatus();
+    const { t, i18n } = useTranslation();
+
+    // The server answers `not_required` to every localhost and FireCMS Cloud
+    // request, whatever the app mounts, so a suggestion is only shown to an
+    // app that really runs no PRO plugin.
+    const plugins = useContext(CustomizationControllerContext)?.plugins;
+    const runsProPlugin = plugins?.some(plugin => PRO_PLUGIN_KEYS.includes(plugin.key)) ?? false;
+
+    // States dismissed in this browser session; a different state shows again.
+    const [dismissed, setDismissed] = useState<string[]>(() => readDismissed(sessionDismissals));
+    // Suggestions dismissed in this browser, for good.
+    const [dismissedForGood, setDismissedForGood] = useState<string[]>(() => readDismissed(browserDismissals));
+
+    // `language`, not `resolvedLanguage`: locale bundles are added after init,
+    // and `resolvedLanguage` stays on the English fallback when they are.
+    const content = licenseStatus
+        ? buildBannerContent(licenseStatus, t, i18n?.language, runsProPlugin)
+        : null;
+
+    if (!content
+        || (content.dismissal === "session" && dismissed.includes(content.state))
+        || (content.dismissal === "forever" && dismissedForGood.includes(content.state)))
+        return null;
+
+    const dismiss = () => {
+        if (content.dismissal === "forever") {
+            const next = [...dismissedForGood, content.state];
+            writeDismissed(browserDismissals, next);
+            setDismissedForGood(next);
+        } else {
+            const next = [...dismissed, content.state];
+            writeDismissed(sessionDismissals, next);
+            setDismissed(next);
+        }
+    };
+
+    return (
+        <div className={className} style={style}>
+            <Alert
+                color={content.color}
+                size={"small"}
+                className={"text-sm"}
+                action={<div className={"flex flex-row items-center gap-1 flex-shrink-0"}>
+                    <Button
+                        variant={"text"}
+                        size={"small"}
+                        component={"a"}
+                        href={content.href}
+                        target={"_blank"}
+                        rel={"noopener noreferrer"}>
+                        {content.linkLabel}
+                    </Button>
+                    {content.dismissal !== "none" && <IconButton
+                        size={"small"}
+                        aria-label={t("close")}
+                        onClick={dismiss}>
+                        <CloseIcon size={"small"}/>
+                    </IconButton>}
+                </div>}>
+                {content.message}
+            </Alert>
+        </div>
+    );
+}
+
+type Translate = ReturnType<typeof useTranslation>["t"];
+
+function buildBannerContent(status: AccessResponse,
+                            t: Translate,
+                            language: string | undefined,
+                            runsProPlugin: boolean): BannerContent | null {
+    const href = getLicenseSubscribeUrl(status);
+    switch (status.licenseState) {
+        case "trial": {
+            const days = trialDaysLeft(status);
+            if (days === null) return null;
+            return {
+                state: "trial",
+                color: "info",
+                message: t("license_trial_banner", {
+                    count: days,
+                    days: String(days)
+                }),
+                linkLabel: t("license_get_license"),
+                href,
+                dismissal: "session"
+            };
+        }
+        case "expired": {
+            const date = formatDate(status.trialEndsAt, language);
+            return {
+                state: "expired",
+                color: "warning",
+                message: date
+                    ? t("license_expired_banner", { date })
+                    : t("license_expired_banner_undated"),
+                linkLabel: t("license_get_license"),
+                href,
+                dismissal: "none"
+            };
+        }
+        case "invalid_project":
+            return {
+                state: "invalid_project",
+                color: "warning",
+                message: status.projectId
+                    ? t("license_invalid_project_banner", { projectId: status.projectId })
+                    : t("license_invalid_project_banner_unnamed"),
+                linkLabel: t("license_add_project_to_license"),
+                href,
+                dismissal: "none"
+            };
+        case "over_quota": {
+            const licensed = status.licensedProjects;
+            if (!isCount(licensed)) return null;
+            return {
+                state: "over_quota",
+                color: "warning",
+                message: t("license_over_quota_banner", {
+                    count: licensed,
+                    licensed: String(licensed)
+                }),
+                linkLabel: t("license_update_license"),
+                href,
+                dismissal: "none"
+            };
+        }
+        case "not_required":
+            return runsProPlugin ? null : buildSuggestionContent(status.suggestion, t);
+        default:
+            // licensed, whitelisted, and servers too old to say
+            return null;
+    }
+}
+
+function buildSuggestionContent(suggestion: ProSuggestion | undefined,
+                                t: Translate): BannerContent | null {
+    if (!suggestion || typeof suggestion !== "object") return null;
+    let message: string;
+    switch (suggestion.plugin) {
+        case "user_management": {
+            const users = suggestion.users;
+            // The copy is plural only: one person is not a reason to suggest roles.
+            message = isCount(users) && users >= 2
+                ? t("pro_suggestion_user_management", { users: String(Math.floor(users)) })
+                : t("pro_suggestion_user_management_uncounted");
+            break;
+        }
+        case "entity_history":
+            message = t("pro_suggestion_entity_history");
+            break;
+        default:
+            // A plugin this version has no copy for.
+            return null;
+    }
+    return {
+        state: `suggestion_${suggestion.plugin}`,
+        color: "info",
+        message,
+        linkLabel: t("pro_suggestion_learn_more"),
+        href: SUGGESTION_DOCS_URLS[suggestion.plugin],
+        dismissal: "forever"
+    };
+}
+
+function isCount(value: unknown): value is number {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+
+function trialDaysLeft(status: AccessResponse): number | null {
+    if (isCount(status.daysLeft)) return Math.ceil(status.daysLeft);
+    const end = status.trialEndsAt ? new Date(status.trialEndsAt).getTime() : NaN;
+    if (Number.isNaN(end)) return null;
+    return Math.max(0, Math.ceil((end - Date.now()) / DAY_MS));
+}
+
+function formatDate(iso: string | undefined, language: string | undefined): string | null {
+    if (!iso) return null;
+    const date = new Date(iso);
+    if (Number.isNaN(date.getTime())) return null;
+    const options: Intl.DateTimeFormatOptions = {
+        year: "numeric",
+        month: "long",
+        day: "numeric"
+    };
+    try {
+        return new Intl.DateTimeFormat(language, options).format(date);
+    } catch {
+        return date.toLocaleDateString(undefined, options);
+    }
+}
+
+type DismissedStore = {
+    storage: () => Storage;
+    key: string;
+};
+
+const sessionDismissals: DismissedStore = {
+    storage: () => sessionStorage,
+    key: DISMISSED_STORAGE_KEY
+};
+
+const browserDismissals: DismissedStore = {
+    storage: () => localStorage,
+    key: DISMISSED_SUGGESTIONS_STORAGE_KEY
+};
+
+function readDismissed(store: DismissedStore): string[] {
+    try {
+        const value = store.storage().getItem(store.key);
+        const parsed = value ? JSON.parse(value) : [];
+        return Array.isArray(parsed) ? parsed.filter((s): s is string => typeof s === "string") : [];
+    } catch {
+        return [];
+    }
+}
+
+function writeDismissed(store: DismissedStore, states: string[]) {
+    try {
+        store.storage().setItem(store.key, JSON.stringify(states));
+    } catch {
+        // Private mode or storage disabled: dismissed for this page view only.
+    }
+}

package/src/components/index.tsx

@@ -43,3 +43,4 @@ export * from "./EntityPreview";
 
 export * from "./AIIcon";
 export * from "./LanguageToggle";
+export * from "./LicenseBanner";

package/src/contexts/LicenseStatusContext.tsx

@@ -0,0 +1,50 @@
+import React from "react";
+import { AccessResponse } from "../types";
+
+/**
+ * License status of the enclosing `FireCMS`. `undefined` means there is no
+ * `FireCMS` above; `null` means the check has not answered (or was skipped).
+ * @internal
+ */
+export const LicenseStatusContext = React.createContext<AccessResponse | null | undefined>(undefined);
+
+/*
+ * The same status, published outside React's tree.
+ *
+ * `useBuildNavigationController` runs in the app component that renders
+ * `<FireCMS>`, above it, so it cannot read the context. It still has to know
+ * when PRO is paused: it applies the plugins' collection, view and home page
+ * navigation contributions itself. `FireCMS` publishes here, and the navigation
+ * controller subscribes with `useSyncExternalStore`.
+ *
+ * One value per page: two `FireCMS` instances on one page would share it, which
+ * is harmless because both check the same project.
+ */
+
+let currentStatus: AccessResponse | null = null;
+const listeners = new Set<() => void>();
+
+/** @internal */
+export function getLicenseStatusSnapshot(): AccessResponse | null {
+    return currentStatus;
+}
+
+/** @internal */
+export function getServerLicenseStatusSnapshot(): AccessResponse | null {
+    return null;
+}
+
+/** @internal */
+export function subscribeLicenseStatus(listener: () => void): () => void {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}
+
+/** @internal */
+export function publishLicenseStatus(status: AccessResponse | null): void {
+    if (status === currentStatus) return;
+    currentStatus = status;
+    listeners.forEach(listener => listener());
+}

package/src/core/DefaultAppBar.tsx

@@ -1,7 +1,7 @@
 import React from "react";
 
 import { Link, useNavigate } from "react-router-dom";
-import { ErrorBoundary, FireCMSLogo, LanguageToggle } from "../components";
+import { ErrorBoundary, LanguageToggle } from "../components";
 import {
     Avatar,
     BrightnessMediumIcon,
@@ -20,6 +20,7 @@ import { useAuthController, useLargeLayout, useModeController, useNavigationCont
 import { User } from "../types";
 import { useApp } from "../app/useApp";
 import { useBreadcrumbsController } from "../hooks/useBreadcrumbsController";
+import { DrawerLogo } from "./DefaultDrawer";
 
 export type DefaultAppBarProps<ADDITIONAL_PROPS = object> = {
 
@@ -119,32 +120,43 @@ export const DefaultAppBar = function DefaultAppBar({
                 "flex flex-row gap-2 px-4 items-center",
                 {
                     "pl-[19rem]": drawerOpen && largeLayout,
-                    "pl-24": hasDrawer && !(drawerOpen && largeLayout),
+                    // The title has to sit at the same x whether or not a Drawer
+                    // is mounted, so the bar reserves the collapsed rail's width
+                    // in both cases. Only a pinned-open drawer moves it, in step
+                    // with the drawer itself.
+                    "pl-24": !(drawerOpen && largeLayout) && (hasDrawer || largeLayout),
                     "z-10": largeLayout,
                     "duration-100": drawerOpen && largeLayout,
                 },
                 className)}>
 
 
+            {/* Rendering DrawerLogo itself, rather than rebuilding its box here,
+                is what keeps the mark from moving when a screen with a drawer
+                follows one without: matching it by hand still left it 4px high,
+                because DrawerLogo centres a 40px box under `pt-4` instead of
+                centring in the 64px bar.
+
+                Gated on `largeLayout`, not on `lg:`: useLargeLayout resolves at
+                min-width 1025px while Tailwind's `lg:` starts at 1024px, and at
+                exactly 1024px the logo would render into a bar that had not
+                reserved room for it, landing on top of the title. */}
+            {navigation && !hasDrawer && largeLayout &&
+                <div className={"absolute left-0 top-0"}>
+                    <DrawerLogo logo={logo} />
+                </div>}
+
             {navigation && <div className="mr-2 hidden lg:block">
                 <Link
                     className="visited:text-inherit visited:dark:text-inherit block"
                     to={navigation?.basePath ?? "/"}
                 >
-                    <div className={"flex flex-row gap-4"}>
-                        {!hasDrawer && (logo
-                            ? <img src={logo}
-                                alt="Logo"
-                                className={cls("w-[32px] h-[32px] object-contain")} />
-                            : <FireCMSLogo width={"32px"} height={"32px"} />)}
-
-                        {typeof title === "string"
-                            ? <Typography variant="subtitle1"
-                                noWrap>
-                                {title}
-                            </Typography>
-                            : title}
-                    </div>
+                    {typeof title === "string"
+                        ? <Typography variant="subtitle1"
+                            noWrap>
+                            {title}
+                        </Typography>
+                        : title}
                 </Link>
             </div>}
 

package/src/core/FireCMS.tsx

@@ -1,7 +1,9 @@
 "use client";
 
-import React, { useEffect, useMemo } from "react";
-import { CenteredView, Typography } from "@firecms/ui";
+import React, { useEffect, useMemo, useRef } from "react";
+import { CenteredView } from "@firecms/ui";
+import { AppliedBundles, applyPluginTranslations, createAppliedBundles } from "./plugin_translations";
+import { filterPausedPlugins, isProPaused } from "./pro_plugins";
 import { AuthController } from "../types";
 import { CustomizationController, FireCMSContext, FireCMSPlugin, FireCMSProps, User } from "../types";
 import { AuthControllerContext, ModeControllerProvider } from "../contexts";
@@ -23,6 +25,7 @@ import { AnalyticsContext } from "../contexts/AnalyticsContext";
 import { useProjectLog } from "../hooks/useProjectLog";
 import { BreadcrumbsProvider } from "../contexts/BreacrumbsContext";
 import { InternalUserManagementContext } from "../contexts/InternalUserManagementContext";
+import { LicenseStatusContext, publishLicenseStatus } from "../contexts/LicenseStatusContext";
 
 /**
  * If you are using independent components of the CMS
@@ -54,6 +57,7 @@ export function FireCMS<USER extends User>(props: FireCMSProps<USER>) {
         components,
         navigationController,
         apiKey,
+        telemetry,
         userManagement: _userManagement
     } = props;
 
@@ -61,11 +65,42 @@ export function FireCMS<USER extends User>(props: FireCMSProps<USER>) {
         console.warn("The `plugins` prop is deprecated in the FireCMS component. You should pass your plugins to `useBuildNavigationController` instead.");
     }
 
-    const { t, i18n } = useTranslation();
+    const { i18n } = useTranslation();
 
     const modeController = useBuildModeController();
 
-    const plugins = navigationController.plugins ?? _pluginsProp;
+    // Every plugin the app mounts. The license check is sent all of their keys:
+    // the server decides from them whether the project needs a license.
+    const allPlugins = navigationController.plugins ?? _pluginsProp;
+
+    const licenseStatus = useProjectLog({
+        apiKey,
+        telemetry,
+        authController,
+        dataSourceDelegate,
+        plugins: allPlugins
+    });
+
+    // The CMS always renders. While PRO is paused, PRO plugins drop out of
+    // everything below (providers, form, collection view and home page
+    // contributions); `useBuildNavigationController` drops their collection,
+    // view and navigation contributions from the status published below.
+    const plugins = useMemo(
+        () => filterPausedPlugins(allPlugins, licenseStatus),
+        [allPlugins, licenseStatus]
+    );
+
+    useEffect(() => {
+        publishLicenseStatus(licenseStatus);
+        if (licenseStatus?.message) {
+            if (isProPaused(licenseStatus)) console.warn(licenseStatus.message);
+            else console.debug(licenseStatus.message);
+        }
+    }, [licenseStatus]);
+
+    // The status belongs to this FireCMS; do not leave it to a later one.
+    useEffect(() => () => publishLicenseStatus(null), []);
+
     const userManagement = plugins?.find(p => p.userManagement)?.userManagement
         ?? _userManagement
         ?? {
@@ -95,13 +130,6 @@ export function FireCMS<USER extends User>(props: FireCMSProps<USER>) {
         onAnalyticsEvent
     }), []);
 
-    const accessResponse = useProjectLog({
-        apiKey,
-        authController,
-        dataSourceDelegate,
-        plugins
-    });
-
     /**
      * Controller in charge of fetching and persisting data
      */
@@ -112,27 +140,42 @@ export function FireCMS<USER extends User>(props: FireCMSProps<USER>) {
         authController
     });
 
-    // Inject plugin translations into the existing i18next instance
+    // Inject plugin translations into the live i18next instance.
+    //
+    // The work, and the reason repeat writes have to be suppressed, is in
+    // `applyPluginTranslations`. Paused plugins keep their strings: app code
+    // may render their components directly, and strings unlock nothing.
+    const appliedBundles = useRef<AppliedBundles>(createAppliedBundles());
+    const appliedTo = useRef<unknown>(null);
+
     useEffect(() => {
         if (!i18n) return;
-        plugins?.forEach(plugin => {
-            if (plugin.i18n) {
-                Object.keys(plugin.i18n).forEach(locale => {
-                    i18n.addResourceBundle(
-                        locale,
-                        "firecms_core",
-                        plugin.i18n![locale],
-                        true,  // deep merge
-                        true   // overwrite
-                    );
-                });
-            }
+
+        // A different instance has its own store and has been written nothing.
+        // Reset here rather than in an effect of its own, which would run after
+        // this one and wipe the record of what this pass just wrote.
+        if (appliedTo.current !== i18n) {
+            appliedTo.current = i18n;
+            appliedBundles.current = createAppliedBundles();
+        }
+
+        let active = true;
+        const isActive = () => active;
+        const applyFor = (language: string) => applyPluginTranslations({
+            i18n,
+            plugins: allPlugins,
+            language,
+            applied: appliedBundles.current,
+            isActive
         });
-    }, [i18n, plugins]);
 
-    if (accessResponse?.message) {
-        console.warn(accessResponse.message);
-    }
+        applyFor(i18n.language ?? "en");
+        i18n.on("languageChanged", applyFor);
+        return () => {
+            active = false;
+            i18n.off("languageChanged", applyFor);
+        };
+    }, [i18n, allPlugins]);
 
     if (navigationController.navigationLoadingError) {
         return (
@@ -154,26 +197,8 @@ export function FireCMS<USER extends User>(props: FireCMSProps<USER>) {
         );
     }
 
-    if (accessResponse?.blocked) {
-        return (
-            <CenteredView maxWidth={"md"} fullScreen={true} className={"flex flex-col gap-2"}>
-                {/* eslint-disable-next-line i18next/no-literal-string */}
-                <Typography variant={"h4"} gutterBottom>
-                    {t("license_needed")}
-                </Typography>
-                <Typography>
-                    {(() => {
-                        const parts = t("license_description", { email: "%%EMAIL%%" }).split("%%EMAIL%%");
-                        return <>{parts[0]}<a href={"mailto:hello@firecms.co"}>hello@firecms.co</a>{parts[1]}</>;
-                    })()}
-                </Typography>
-                {accessResponse?.message &&
-                    <Typography>{accessResponse?.message}</Typography>}
-            </CenteredView>
-        );
-    }
-
     return (
+        <LicenseStatusContext.Provider value={licenseStatus}>
         <AnalyticsContext.Provider value={analyticsController}>
             <CustomizationControllerContext.Provider value={customizationController}>
                 <UserConfigurationPersistenceContext.Provider
@@ -209,6 +234,7 @@ export function FireCMS<USER extends User>(props: FireCMSProps<USER>) {
                 </UserConfigurationPersistenceContext.Provider>
             </CustomizationControllerContext.Provider>
         </AnalyticsContext.Provider>
+        </LicenseStatusContext.Provider>
     );
 
 }

package/src/core/SideDialogs.tsx

@@ -1,4 +1,4 @@
-import React, { useContext, useEffect, useState } from "react";
+import React, { useContext, useEffect, useRef, useState } from "react";
 import { useSideDialogsController } from "../hooks";
 import { EntitySidePanelProps, SideDialogPanelProps } from "../types";
 import { Sheet } from "@firecms/ui";
@@ -67,6 +67,40 @@ export function SideDialogs() {
     </>;
 }
 
+// Menus, selects and popovers opened inside a side dialog are dismissed by Radix as
+// soon as the pointer goes down, but the dialog underneath only makes up its mind on
+// the click that follows, when that layer is already gone and the dialog looks like
+// the topmost one. Without this, the click that dismisses an open menu also asks the
+// panel to close, and an edited entity greets the user with the unsaved changes dialog.
+const NESTED_LAYER_SELECTOR = [
+    "[data-radix-menu-content]",
+    "[data-radix-select-viewport]",
+    "[data-radix-popper-content-wrapper] [role=\"dialog\"]",
+    "[data-suggestion-menu=\"true\"]"
+].join(",");
+
+function useNestedLayerOpenOnPointerDown() {
+    const ref = useRef(false);
+    useEffect(() => {
+        const onPointerDown = () => {
+            ref.current = Array.from(document.querySelectorAll(NESTED_LAYER_SELECTOR))
+                .some(element => window.getComputedStyle(element).visibility !== "hidden");
+        };
+        // the keyboard dismisses one layer at a time on its own, so a stale pointer
+        // interaction must not swallow a close requested with Escape
+        const onKeyDown = () => {
+            ref.current = false;
+        };
+        document.addEventListener("pointerdown", onPointerDown, true);
+        document.addEventListener("keydown", onKeyDown, true);
+        return () => {
+            document.removeEventListener("pointerdown", onPointerDown, true);
+            document.removeEventListener("keydown", onKeyDown, true);
+        };
+    }, []);
+    return ref;
+}
+
 function SideDialogView({
     offsetPosition,
     panel
@@ -82,6 +116,8 @@ function SideDialogView({
 
     const [pendingClose, setPendingClose] = useState(false);
 
+    const nestedLayerOpenOnPointerDown = useNestedLayerOpenOnPointerDown();
+
     const widthRef = React.useRef<string | undefined>(panel?.width);
     const width = widthRef.current;
 
@@ -144,6 +180,13 @@ function SideDialogView({
                             // Let Tiptap handle closing the menu first
                             return;
                         }
+                        // this interaction started on top of a menu or popover: it dismissed
+                        // that layer, it was not a request to close the panel. The flag is
+                        // left alone because a single click asks to close more than once;
+                        // the next pointer or key interaction recomputes it.
+                        if (nestedLayerOpenOnPointerDown.current) {
+                            return;
+                        }
                         onCloseRequest();
                     }
                 }}

package/src/core/index.tsx

@@ -1,4 +1,5 @@
 export * from "./FireCMS";
+export * from "./pro_plugins";
 
 export * from "./DefaultDrawer";
 export * from "./DrawerNavigationItem";