@firecms/core 3.4.0-canary.f6a889a → 3.5.0

package/src/types/license.ts

@@ -0,0 +1,90 @@
+/**
+ * What the FireCMS license check says about this project.
+ *
+ * - `not_required`: no PRO plugin is mounted.
+ * - `whitelisted`: the project is exempt from licensing.
+ * - `licensed`: a license covers this project.
+ * - `trial`: PRO plugins run on the free trial; see `daysLeft` and `trialEndsAt`.
+ * - `expired`: the trial ended without a license. PRO plugins are paused.
+ * - `invalid_project`: a license key was presented, but this project is not
+ *   linked to that license. PRO plugins are paused.
+ * - `over_quota`: the license links more projects than it pays for, and this
+ *   is not one of the projects it covers in production. PRO plugins are
+ *   paused.
+ *
+ * @group Models
+ */
+export type LicenseState =
+    | "not_required"
+    | "whitelisted"
+    | "licensed"
+    | "trial"
+    | "expired"
+    | "invalid_project"
+    | "over_quota";
+
+/**
+ * Response of the FireCMS license check (`POST https://api.firecms.co/access_log`).
+ *
+ * Servers older than the PRO relaunch send only `blocked` and `message`, so
+ * treat a missing `licenseState` as unknown. `blocked` is honoured either way.
+ *
+ * @group Models
+ */
+export type AccessResponse = {
+    /**
+     * True when the PRO plugins must be paused. The core CMS is never blocked.
+     */
+    blocked?: boolean;
+    licenseState?: LicenseState;
+    /**
+     * Number of projects the license pays for. Present with `licensed` and `over_quota`.
+     */
+    licensedProjects?: number;
+    /**
+     * Number of projects linked to the license.
+     */
+    linkedProjects?: number;
+    projectId?: string;
+    licenseId?: string;
+    /**
+     * ISO date the trial ends or ended. Present with `trial` and `expired`.
+     */
+    trialEndsAt?: string;
+    /**
+     * Whole days left in the trial, present with `trial`.
+     */
+    daysLeft?: number;
+    /**
+     * Where to get or update a license for this project.
+     */
+    subscribeUrl?: string;
+    /**
+     * A PRO plugin the server suggests for this project. Only read with
+     * `not_required`, and only shown when the app mounts no PRO plugin: the
+     * server also answers `not_required` to localhost and FireCMS Cloud,
+     * whatever they mount.
+     */
+    suggestion?: ProSuggestion;
+    message?: string;
+};
+
+/**
+ * A FireCMS PRO plugin the license check suggests to a project that runs
+ * none, such as user management for a CMS that several people sign in to.
+ * The server decides which projects get one; the CMS shows it as a note the
+ * user can dismiss for good.
+ *
+ * @group Models
+ */
+export type ProSuggestion = {
+    /**
+     * Key of the suggested plugin. Keys this version of FireCMS has no copy
+     * for are ignored, so the server can add new ones safely.
+     */
+    plugin: "user_management" | "entity_history";
+    /**
+     * How many people use this CMS, when the server counted them.
+     */
+    users?: number;
+};

package/src/types/navigation.ts

@@ -57,8 +57,12 @@ export type NavigationController<EC extends EntityCollection = EntityCollection<
     /**
      * Get the collection configuration for a given path.
      * The collection is resolved from the given path or alias.
+     *
+     * Pass `pathSegments` when you have them: without them the path is split on "/" and
+     * asserted to have an odd number of parts, which a chain containing a slash-bearing
+     * entity id fails — it throws instead of resolving.
      */
-    getCollection: (pathOrId: string, includeUserOverride?: boolean) => EC | undefined;
+    getCollection: (pathOrId: string, includeUserOverride?: boolean, pathSegments?: string[]) => EC | undefined;
 
     /**
      * Get the top level collection configuration for a given id
@@ -118,9 +122,30 @@ export type NavigationController<EC extends EntityCollection = EntityCollection<
     /**
      * Turn a path with collection ids into a resolved path.
      * The ids (typically used in urls) will be replaced with relative paths (typically used in database paths)
+     *
+     * Pass `pathSegments` whenever you have them. Without them this has to find the entity
+     * ids inside the flattened string by reading up to the next "/", which is wrong for any
+     * id that contains one — the chain then shifts by a segment and resolution fails.
+     *
      * @param pathWithAliases
+     * @param pathSegments `pathWithAliases` split at its real segment boundaries, if known
      */
-    resolveIdsFrom: (pathWithAliases: string) => string;
+    resolveIdsFrom: (pathWithAliases: string, pathSegments?: string[]) => string;
+
+    /**
+     * The segment-wise counterpart of {@link resolveIdsFrom}: replaces collection ids with
+     * their real paths while carrying every entity id through whole, slashes included.
+     *
+     * Idempotent — segments that are already resolved pass through unchanged.
+     *
+     * Optional so that a `navigationController` built against an earlier version keeps
+     * working: callers fall back to using the segments as given, which is what happened
+     * before this method existed. Controllers built by `useBuildNavigationController`
+     * always provide it.
+     *
+     * @param pathSegments
+     */
+    resolveSegmentsFrom?: (pathSegments: string[]) => string[];
 
     /**
      * Call this method to recalculate the navigation
@@ -128,16 +153,21 @@ export type NavigationController<EC extends EntityCollection = EntityCollection<
     refreshNavigation: () => void;
 
     /**
-     * Retrieve all the related parent references for a given path
+     * Retrieve all the related parent references for a given path.
+     *
+     * `path` is expected escaped, as it comes from the URL. Pass `pathSegments` when the
+     * path at hand is a raw datasource path, whose ids may contain a bare "/".
+     *
      * @param path
+     * @param pathSegments `path` split at its real segment boundaries, with raw ids
      */
-    getParentReferencesFromPath: (path: string) => EntityReference[];
+    getParentReferencesFromPath: (path: string, pathSegments?: string[]) => EntityReference[];
 
     /**
      * Retrieve all the related parent collection ids for a given path
      * @param path
      */
-    getParentCollectionIds: (path: string) => string[];
+    getParentCollectionIds: (path: string, pathSegments?: string[]) => string[];
 
     /**
      * Resolve paths from a list of ids

package/src/types/plugins.tsx

@@ -15,6 +15,9 @@ import { InternalUserManagement } from "./internal_user_management";
  * NOTE: This is a work in progress and the API is not stable yet.
  * @group Core
  */
+/** The strings a plugin contributes for one locale. */
+export type PluginTranslations = Record<string, string>;
+
 export type FireCMSPlugin<PROPS = any, FORM_PROPS = any, EC extends EntityCollection = EntityCollection, COL_ACTIONS_PROPS = any, COL_ACTIONS_START__PROPS = any> = {
 
     /**
@@ -33,8 +36,14 @@ export type FireCMSPlugin<PROPS = any, FORM_PROPS = any, EC extends EntityCollec
      * locales, specific for this plugin.
      * Keys can be existing `FireCMSTranslations` keys, or new keys if using
      * module augmentation.
+     *
+     * A value may be the strings themselves, or a function returning a promise
+     * of them. Use the function form for locales you ship in the plugin bundle:
+     * only the active language is ever read, so importing all of them statically
+     * puts every language into the bundle of every app that mounts the plugin.
+     * Both forms are supported; a plain record keeps working unchanged.
      */
-    i18n?: Record<string, Record<string, string>>;
+    i18n?: Record<string, PluginTranslations | (() => Promise<PluginTranslations>)>;
 
     /**
      * You can use this prop to add higher order components to the CMS.
@@ -146,6 +155,8 @@ export type FireCMSPlugin<PROPS = any, FORM_PROPS = any, EC extends EntityCollec
         blockSearch?: (props: {
             context: FireCMSContext,
             path: string,
+            /** `path` split at its real segment boundaries, when known. */
+            pathSegments?: string[],
             collection: EC,
             parentCollectionIds?: string[]
         }) => boolean;
@@ -153,6 +164,8 @@ export type FireCMSPlugin<PROPS = any, FORM_PROPS = any, EC extends EntityCollec
         showTextSearchBar?: (props: {
             context: FireCMSContext,
             path: string,
+            /** `path` split at its real segment boundaries, when known. */
+            pathSegments?: string[],
             collection: EC,
             parentCollectionIds?: string[]
         }) => boolean;
@@ -160,6 +173,8 @@ export type FireCMSPlugin<PROPS = any, FORM_PROPS = any, EC extends EntityCollec
         onTextSearchClick?: (props: {
             context: FireCMSContext,
             path: string,
+            /** `path` split at its real segment boundaries, when known. */
+            pathSegments?: string[],
             collection: EC,
             parentCollectionIds?: string[]
         }) => Promise<boolean>;
@@ -308,6 +323,13 @@ export interface PluginHomePageActionsProps<EP extends object = object, M extend
 export interface PluginFormActionProps<USER extends User = User, EC extends EntityCollection = EntityCollection> {
     entityId?: string;
     path: string;
+    /**
+     * `path` split at its real segment boundaries, e.g. `["nodes", "node/42", "edges"]`.
+     *
+     * Optional, and never derived by splitting `path` — a parent entity id may itself
+     * contain "/". Absent means "not known here", not "no slashes".
+     */
+    pathSegments?: string[];
     parentCollectionIds: string[];
     status: EntityStatus;
     collection: EC;

package/src/types/properties.ts

@@ -562,6 +562,22 @@ export type PropertyBuilderProps<M extends Record<string, any> = any> =
          * Current value of this property
          */
         propertyValue?: any;
+        /**
+         * Path of this property within the entity, in dot notation, e.g.
+         * `my_map.my_field` or `my_array.0.my_field`.
+         * Useful to look up sibling values in `values` with `getValueInPath`.
+         *
+         * When a property builder is used as the `of` prop of an array property,
+         * it is resolved twice: once per existing element, with an index
+         * qualified key (`my_array.0`), and once as the template for the element
+         * shape, with the array's own key (`my_array`). In the latter case
+         * `propertyValue` is the whole array, since the template is not bound to
+         * any element.
+         *
+         * It may be undefined if the property is resolved outside the context of
+         * an entity.
+         */
+        propertyKey?: string;
         /**
          * Index of this property (only for arrays)
          */
@@ -592,6 +608,7 @@ export type PropertyBuilder<T extends CMSType = any, M extends Record<string, an
         values,
         previousValues,
         propertyValue,
+        propertyKey,
         index,
         path,
         entityId,

package/src/types/side_entity_controller.tsx

@@ -19,6 +19,13 @@ export interface EntitySidePanelProps<M extends Record<string, any> = any> {
      * Full CMS path of the entity, including the collection and sub-collections.
      */
     fullIdPath?: string;
+    /**
+     * `path` split at its real segment boundaries, e.g. `["nodes", "node/42", "edges"]`.
+     *
+     * Optional, and never derived by splitting `path` — a guess would be wrong in exactly
+     * the case the field exists for. Absent means "not known here", not "no slashes".
+     */
+    pathSegments?: string[];
 
     /**
      * ID of the entity, if not set, it means we are creating a new entity

package/src/types/translations.ts

@@ -66,8 +66,40 @@ export interface FireCMSTranslations {
     select_from: string;
     done: string;
     log_out: string;
-    license_needed: string;
-    license_description: string;
+    /** License banner during the PRO trial. `{{days}}` is the number of days left; plural form. */
+    license_trial_banner: string;
+    /** `license_trial_banner` when one day is left (i18next `_one` plural form). */
+    license_trial_banner_one: string;
+    /** License banner once the trial has ended. `{{date}}` is the day it ended. */
+    license_expired_banner: string;
+    /** `license_expired_banner` when the end date is not known. */
+    license_expired_banner_undated: string;
+    /** License banner when the license key is not linked to this project. `{{projectId}}` is the Firebase project id. */
+    license_invalid_project_banner: string;
+    /** `license_invalid_project_banner` when the project id is not known. */
+    license_invalid_project_banner_unnamed: string;
+    /** License banner when more projects are linked than the license covers. `{{licensed}}` covered, `{{actual}}` linked; plural form. */
+    license_over_quota_banner: string;
+    /** `license_over_quota_banner` when the license covers one project (i18next `_one` plural form). */
+    license_over_quota_banner_one: string;
+    /** Link in the license banner to buy a license. */
+    license_get_license: string;
+    /** Link in the over-quota banner to the license settings. */
+    license_update_license: string;
+    /** Link in the invalid-project banner to link this project to the license. */
+    license_add_project_to_license: string;
+    /** Suggestion of the PRO user management plugin to a project without it. `{{users}}` is how many people use the CMS, always 2 or more. */
+    pro_suggestion_user_management: string;
+    /** `pro_suggestion_user_management` when the number of people is not known. */
+    pro_suggestion_user_management_uncounted: string;
+    /** Suggestion of the PRO entity history plugin to a project without it. */
+    pro_suggestion_entity_history: string;
+    /** Link in a PRO suggestion to the plugin's documentation. */
+    pro_suggestion_learn_more: string;
+    /** Title of the notice a PRO view shows while PRO features are paused. */
+    pro_features_paused: string;
+    /** Users and Roles views while PRO features are paused. */
+    user_management_paused_description: string;
     column_cannot_be_edited: string;
     close: string;
     unsaved_local_changes: string;
@@ -419,6 +451,14 @@ export interface FireCMSTranslations {
     download: string;
     large_number_of_documents: string;
     include_undefined_values: string;
+    /** Toggle in the export dialog, only shown when a filter or sort is active */
+    export_apply_filter_sort: string;
+    /** Choice in the export dialog, only shown when entities are selected */
+    export_all_entities: string;
+    /** Same choice; `{{count}}` is the number of selected entities */
+    export_selected_entities: string;
+    /** Shown in the export dialog when the export fails; `{{message}}` is the error's message */
+    export_error: string;
     submit: string;
 
     no_filterable_properties: string;
@@ -468,6 +508,8 @@ export interface FireCMSTranslations {
     roles_menu: string;
     project_settings: string;
     firestore_manager: string;
+    /** The DataTalk product name, keyed so a locale can transliterate it. */
+    datatalk: string;
     manage_your_firestore_data: string;
 
     // ─── FireCMS Cloud Login ──────────────────────────────────────
@@ -484,6 +526,7 @@ export interface FireCMSTranslations {
     not_the_admin_panel: string;
     join_our_newsletter: string;
     by_signing_in_you_agree_to_our: string;
+    please_accept_the_terms_to_continue: string;
     terms_and_conditions: string;
     and_our: string;
     privacy_policy: string;
@@ -526,6 +569,8 @@ export interface FireCMSTranslations {
     licensed_projects_lowercase: string;
     manage: string;
     update_payment_method: string;
+    /** Snackbar when a Stripe billing portal link can't be created. `{{message}}` is the reason. */
+    stripe_portal_error: string;
     your_firecms_cloud_projects: string;
     status_active: string;
     status_trialing: string;
@@ -620,6 +665,10 @@ export interface FireCMSTranslations {
     order_property_not_found: string;
     no_number_properties: string;
     order_property_description: string;
+    image_property: string;
+    image_property_not_found: string;
+    no_image_properties: string;
+    image_property_description: string;
     display_settings: string;
     default_row_size: string;
     side_dialog_width: string;

package/src/util/__tests__/collections.test.ts

@@ -0,0 +1,32 @@
+import { getLocalChangesBackup } from "../collections";
+import { EntityCollection } from "../../types";
+
+function collectionWith(localChangesBackup?: "manual_apply" | "auto_apply" | false): EntityCollection {
+    return {
+        id: "products",
+        name: "Products",
+        path: "products",
+        properties: {},
+        localChangesBackup
+    } as EntityCollection;
+}
+
+describe("getLocalChangesBackup", () => {
+
+    it("should default to manual_apply when not set", () => {
+        expect(getLocalChangesBackup(collectionWith(undefined))).toEqual("manual_apply");
+    });
+
+    it("should return manual_apply when explicitly set", () => {
+        expect(getLocalChangesBackup(collectionWith("manual_apply"))).toEqual("manual_apply");
+    });
+
+    it("should return auto_apply when explicitly set", () => {
+        expect(getLocalChangesBackup(collectionWith("auto_apply"))).toEqual("auto_apply");
+    });
+
+    it("should return false when explicitly disabled, and not fall back to the default", () => {
+        expect(getLocalChangesBackup(collectionWith(false))).toEqual(false);
+    });
+
+});

package/src/util/__tests__/urls.test.ts

@@ -0,0 +1,131 @@
+import { getFileExtensionFromUrl, getPreviewTypeFromUrl, isAbsoluteHttpUrl } from "../urls";
+
+describe("url utilities", () => {
+
+    describe("isAbsoluteHttpUrl", () => {
+
+        it("should detect absolute http and https URLs", () => {
+            expect(isAbsoluteHttpUrl("https://abc.com/abc.png")).toBe(true);
+            expect(isAbsoluteHttpUrl("http://abc.com/abc.png")).toBe(true);
+            expect(isAbsoluteHttpUrl("HTTPS://ABC.COM/ABC.PNG")).toBe(true);
+        });
+
+        it("should detect Firebase Storage download URLs as absolute URLs", () => {
+            expect(isAbsoluteHttpUrl("https://firebasestorage.googleapis.com/v0/b/demo.appspot.com/o/images%2Fcat.png?alt=media&token=abc")).toBe(true);
+            expect(isAbsoluteHttpUrl("https://storage.googleapis.com/demo.appspot.com/images/cat.png")).toBe(true);
+        });
+
+        it("should not consider storage paths absolute URLs", () => {
+            expect(isAbsoluteHttpUrl("images/cat.png")).toBe(false);
+            expect(isAbsoluteHttpUrl("/images/cat.png")).toBe(false);
+            expect(isAbsoluteHttpUrl("cat.png")).toBe(false);
+        });
+
+        it("should not consider other protocols absolute http URLs", () => {
+            expect(isAbsoluteHttpUrl("gs://demo.appspot.com/images/cat.png")).toBe(false);
+            expect(isAbsoluteHttpUrl("data:image/png;base64,AAAA")).toBe(false);
+            expect(isAbsoluteHttpUrl("//abc.com/abc.png")).toBe(false);
+        });
+
+        it("should handle empty values", () => {
+            expect(isAbsoluteHttpUrl("")).toBe(false);
+            expect(isAbsoluteHttpUrl(undefined)).toBe(false);
+            expect(isAbsoluteHttpUrl(null)).toBe(false);
+        });
+
+        it("should not match http appearing later in the value", () => {
+            expect(isAbsoluteHttpUrl("images/https://abc.com/abc.png")).toBe(false);
+        });
+
+    });
+
+    describe("getFileExtensionFromUrl", () => {
+
+        it("should extract the extension of a plain URL", () => {
+            expect(getFileExtensionFromUrl("https://abc.com/abc.png")).toBe("png");
+        });
+
+        it("should lowercase the extension", () => {
+            expect(getFileExtensionFromUrl("https://abc.com/ABC.PNG")).toBe("png");
+        });
+
+        it("should ignore query strings and hash fragments", () => {
+            expect(getFileExtensionFromUrl("https://abc.com/abc.png?width=200")).toBe("png");
+            expect(getFileExtensionFromUrl("https://abc.com/abc.png#anchor")).toBe("png");
+            expect(getFileExtensionFromUrl("https://firebasestorage.googleapis.com/v0/b/demo.appspot.com/o/images%2Fcat.jpeg?alt=media&token=abc")).toBe("jpeg");
+        });
+
+        it("should work with storage paths", () => {
+            expect(getFileExtensionFromUrl("images/cat.webp")).toBe("webp");
+        });
+
+        it("should use the last dot of the file name", () => {
+            expect(getFileExtensionFromUrl("https://abc.com/archive.tar.gz")).toBe("gz");
+        });
+
+        it("should return undefined when there is no extension", () => {
+            expect(getFileExtensionFromUrl("https://abc.com/abc")).toBeUndefined();
+            expect(getFileExtensionFromUrl("https://abc.com/")).toBeUndefined();
+            expect(getFileExtensionFromUrl("images/cat")).toBeUndefined();
+        });
+
+        it("should not take dots of the host or the path as extensions", () => {
+            expect(getFileExtensionFromUrl("https://abc.com/images/cat")).toBeUndefined();
+            expect(getFileExtensionFromUrl("https://abc.com/abc.png/download")).toBeUndefined();
+        });
+
+        it("should return undefined for dotfiles and trailing dots", () => {
+            expect(getFileExtensionFromUrl("https://abc.com/.gitignore")).toBeUndefined();
+            expect(getFileExtensionFromUrl("https://abc.com/abc.")).toBeUndefined();
+        });
+
+        it("should handle empty values", () => {
+            expect(getFileExtensionFromUrl("")).toBeUndefined();
+            expect(getFileExtensionFromUrl(undefined)).toBeUndefined();
+            expect(getFileExtensionFromUrl(null)).toBeUndefined();
+        });
+
+    });
+
+    describe("getPreviewTypeFromUrl", () => {
+
+        it("should infer image previews", () => {
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.png")).toBe("image");
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.jpg")).toBe("image");
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.jpeg")).toBe("image");
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.gif")).toBe("image");
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.webp")).toBe("image");
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.svg")).toBe("image");
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.avif")).toBe("image");
+        });
+
+        it("should infer video previews", () => {
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.mp4")).toBe("video");
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.webm")).toBe("video");
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.mov")).toBe("video");
+        });
+
+        it("should infer audio previews", () => {
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.mp3")).toBe("audio");
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.wav")).toBe("audio");
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.m4a")).toBe("audio");
+        });
+
+        it("should infer the type of Firebase Storage download URLs", () => {
+            expect(getPreviewTypeFromUrl("https://firebasestorage.googleapis.com/v0/b/demo.appspot.com/o/images%2Fcat.png?alt=media&token=abc")).toBe("image");
+        });
+
+        it("should be case insensitive", () => {
+            expect(getPreviewTypeFromUrl("https://abc.com/ABC.PNG")).toBe("image");
+        });
+
+        it("should return undefined for unknown or missing extensions", () => {
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.pdf")).toBeUndefined();
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.zip")).toBeUndefined();
+            expect(getPreviewTypeFromUrl("https://abc.com/abc")).toBeUndefined();
+            expect(getPreviewTypeFromUrl(undefined)).toBeUndefined();
+        });
+
+    });
+
+});

package/src/util/collections.ts

@@ -117,7 +117,7 @@ export const applyPermissionsFunctionIfEmpty = (collections: EntityCollection[],
 }
 
 export function getLocalChangesBackup(collection: EntityCollection) {
-    if (!collection.localChangesBackup) {
+    if (collection.localChangesBackup === undefined) {
         return "manual_apply";
     }