@firecms/core 3.3.0 → 3.4.0-canary.00f9be5

package/dist/types/navigation.d.ts

@@ -48,8 +48,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
      */
@@ -99,23 +103,48 @@ 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, 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
      */
-    resolveIdsFrom: (pathWithAliases: string) => string;
+    resolveSegmentsFrom?: (pathSegments: string[]) => string[];
     /**
      * Call this method to recalculate the navigation
      */
     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
      * @param ids

package/dist/types/plugins.d.ts

@@ -13,6 +13,8 @@ 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> = {
     /**
      * Key of the plugin. This is used to identify the plugin in the CMS.
@@ -28,8 +30,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.
      * The components will be added to the root of the CMS, so any component
@@ -121,18 +129,24 @@ 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;
         showTextSearchBar?: (props: {
             context: FireCMSContext;
             path: string;
+            /** `path` split at its real segment boundaries, when known. */
+            pathSegments?: string[];
             collection: EC;
             parentCollectionIds?: string[];
         }) => boolean;
         onTextSearchClick?: (props: {
             context: FireCMSContext;
             path: string;
+            /** `path` split at its real segment boundaries, when known. */
+            pathSegments?: string[];
             collection: EC;
             parentCollectionIds?: string[];
         }) => Promise<boolean>;
@@ -258,6 +272,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/dist/types/properties.d.ts

@@ -433,6 +433,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)
      */
@@ -456,7 +472,7 @@ export type PropertyBuilderProps<M extends Record<string, any> = any> = {
  * current value of the property, as well as the path and entity ID.
  * @group Entity properties
  */
-export type PropertyBuilder<T extends CMSType = any, M extends Record<string, any> = any> = ({ values, previousValues, propertyValue, index, path, entityId, authController }: PropertyBuilderProps<M>) => Property<T> | null;
+export type PropertyBuilder<T extends CMSType = any, M extends Record<string, any> = any> = ({ values, previousValues, propertyValue, propertyKey, index, path, entityId, authController }: PropertyBuilderProps<M>) => Property<T> | null;
 /**
  * @group Entity properties
  */

package/dist/types/side_entity_controller.d.ts

@@ -15,6 +15,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/dist/types/translations.d.ts

@@ -56,8 +56,32 @@ 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;
+    /** 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;
@@ -368,6 +392,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;
     apply_filters: string;
@@ -413,6 +445,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;
     build_admin_panel_in_minutes: string;
     go_live_instantly: string;
@@ -427,6 +461,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;
@@ -465,6 +500,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;
@@ -547,6 +584,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/dist/util/__tests__/collections.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/util/__tests__/urls.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/util/collections.d.ts

@@ -9,4 +9,4 @@ export declare function resolveDefaultSelectedView(defaultSelectedView: string |
  * @param permissionsBuilder
  */
 export declare const applyPermissionsFunctionIfEmpty: (collections: EntityCollection[], permissionsBuilder?: PermissionsBuilder<any, any>) => EntityCollection[];
-export declare function getLocalChangesBackup(collection: EntityCollection): "manual_apply" | "auto_apply";
+export declare function getLocalChangesBackup(collection: EntityCollection): false | "manual_apply" | "auto_apply";

package/dist/util/date_fns_locales.d.ts

@@ -0,0 +1,18 @@
+import type { Locale as DateFnsLocale } from "date-fns";
+import { Locale } from "../types";
+/**
+ * Load a date-fns locale, resolving from cache when it is already in memory.
+ * Concurrent callers for the same locale share one request.
+ */
+export declare function loadDateFnsLocale(locale: Locale): Promise<DateFnsLocale | undefined>;
+/** The locale if it is already loaded, otherwise undefined. Never suspends. */
+export declare function getLoadedDateFnsLocale(locale?: Locale): DateFnsLocale | undefined;
+/**
+ * The date-fns locale for `locale`, loading it in the background on first use.
+ *
+ * Returns undefined until the chunk arrives, which formats the first paint with
+ * date-fns' built-in English and then re-renders. That is a change only for
+ * projects that set a locale, and only for the few hundred milliseconds before
+ * the chunk lands — in exchange for every project no longer waiting on 625KB.
+ */
+export declare function useDateFnsLocale(locale?: Locale): DateFnsLocale | undefined;

package/dist/util/entities.d.ts

@@ -25,3 +25,4 @@ export declare function sanitizeData<M extends Record<string, any>>(values: Enti
 export declare function getReferenceFrom<M extends Record<string, any>>(entity: Entity<M>): EntityReference;
 export declare function traverseValuesProperties<M extends Record<string, any>>(inputValues: Partial<EntityValues<M>>, properties: ResolvedProperties<M>, operation: (value: any, property: Property) => any): EntityValues<M> | undefined;
 export declare function traverseValueProperty(inputValue: any, property: Property, operation: (value: any, property: Property) => any): any;
+export declare function isDataTypeFilterable(dataType: DataType, isPartOfArray?: boolean): boolean;

package/dist/util/entity_cache.d.ts

@@ -1,3 +1,14 @@
+/**
+ * Key identifying one entity in a cache.
+ *
+ * The id is escaped so that a `(path, entityId)` pair maps to exactly one key. Without it
+ * `("a", "b/c")` and `("a/b", "c")` both flatten to `"a/b/c"`, and one entity's cached
+ * values are served for the other.
+ *
+ * `encodeEntityId` is the identity for any id without "/", "?", "#" or "%", so this changes
+ * no key in an app whose ids cannot contain them.
+ */
+export declare function entityCacheKey(path: string | undefined, entityId: string | undefined): string;
 /**
  * Saves data to the in-memory cache and persists it individually in `localStorage`.
  * @param path - The unique path/key for the data.

package/dist/util/geopoint.d.ts

@@ -0,0 +1,22 @@
+import { GeoPoint } from "../types";
+export type GeoPointLike = GeoPoint | {
+    latitude?: number;
+    longitude?: number;
+    lat?: number;
+    lng?: number;
+    _lat?: number;
+    _long?: number;
+} | null | undefined;
+export interface GeoPointCoordinates {
+    latitude: number;
+    longitude: number;
+}
+export declare function getGeoPointCoordinates(value: GeoPointLike): GeoPointCoordinates | undefined;
+export declare function normalizeGeoPoint(value: GeoPointLike): GeoPoint | undefined;
+export declare function formatGeoPoint(value: GeoPointLike, options?: {
+    maximumFractionDigits?: number;
+}): string;
+export declare function parseGeoPoint(input: string): {
+    point: GeoPoint | null;
+    error?: string;
+};

package/dist/util/index.d.ts

@@ -6,12 +6,14 @@ export * from "./enums";
 export * from "./objects";
 export * from "./paths";
 export * from "./regexp";
+export * from "./urls";
 export * from "./navigation_utils";
 export * from "./entity_actions";
 export * from "./useDebouncedCallback";
 export * from "./property_utils";
 export * from "./resolutions";
 export * from "./permissions";
+export * from "./geopoint";
 export * from "./icon_list";
 export * from "./icon_synonyms";
 export * from "./icons";
@@ -26,3 +28,4 @@ export * from "./storage";
 export * from "./callbacks";
 export * from "./conditions";
 export * from "./lazy_eager";
+export * from "./date_fns_locales";

package/dist/util/lazy_eager.d.ts

@@ -1,7 +1,7 @@
 import React from "react";
 /**
- * Returns a React.lazy component that is also preloaded immediately using
- * requestIdleCallback or setTimeout.
- * This ensures that chunks are split, but fetched in the background before they are actually needed.
+ * Returns a React.lazy component that is also preloaded in the background, once
+ * the page has finished loading.
+ * This ensures that chunks are split, but fetched before they are actually needed.
  */
 export declare function lazyEager<T extends React.ComponentType<any>>(factory: () => Promise<any>, exportName?: string): React.LazyExoticComponent<T>;

package/dist/util/navigation_blocking.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Pure predicate deciding whether an in-progress navigation away from an open
+ * entity form should be blocked (to warn about unsaved changes).
+ *
+ * Extracted from FireCMSRoute so the branching can be unit-tested without
+ * mounting the router. This is an internal helper — it is intentionally not
+ * re-exported from the package index.
+ */
+export interface NavigationBlockLocation {
+    pathname: string;
+    hash: string;
+}
+export declare function shouldBlockEntityNavigation(params: {
+    currentLocation: NavigationBlockLocation;
+    nextLocation: NavigationBlockLocation;
+    /** Path of the currently open entity (basePath + "/" + entityId). */
+    entityPath: string;
+    /** Collection path the entity form lives under. */
+    basePath: string;
+    /** Whether the form currently has unsaved modifications. */
+    blocked: boolean;
+}): boolean;

package/dist/util/navigation_from_path.d.ts

@@ -6,6 +6,8 @@ export interface NavigationViewEntityInternal<M extends Record<string, any>> {
     path: string;
     fullIdPath: string;
     fullPath: string;
+    /** `path` split at its real boundaries — see `pathSegments` on the datasource props. */
+    pathSegments: string[];
     parentCollection: EntityCollection<M>;
 }
 export interface NavigationViewCollectionInternal<M extends Record<string, any>> {
@@ -14,6 +16,8 @@ export interface NavigationViewCollectionInternal<M extends Record<string, any>>
     path: string;
     fullIdPath: string;
     fullPath: string;
+    /** `path` split at its real boundaries — see `pathSegments` on the datasource props. */
+    pathSegments: string[];
     collection: EntityCollection<M>;
 }
 export interface NavigationViewEntityCustomInternal<M extends Record<string, any>> {
@@ -21,13 +25,26 @@ export interface NavigationViewEntityCustomInternal<M extends Record<string, any
     path: string;
     fullIdPath: string;
     fullPath: string;
+    /** `path` split at its real boundaries — see `pathSegments` on the datasource props. */
+    pathSegments: string[];
     entityId: string;
     view: EntityCustomView<M>;
 }
+/**
+ * Note on encoding: `path` arrives from the URL, so any entity id in it is escaped (see
+ * `encodeEntityId`). Two chains are threaded through the recursion:
+ *
+ *  - `currentFullPath` carries RAW ids and feeds the `path` / `fullPath` used to address
+ *    the datasource.
+ *  - `currentFullUrlPath` carries ESCAPED ids and feeds `fullPath`, which is handed back
+ *    to `buildUrlCollectionPath` for breadcrumbs and links.
+ */
 export declare function getNavigationEntriesFromPath(props: {
     path: string;
     collections: EntityCollection[] | undefined;
     currentFullPath?: string;
     currentFullIdPath?: string;
+    currentFullUrlPath?: string;
+    currentPathSegments?: string[];
     contextEntityViews?: EntityCustomView<any>[];
 }): NavigationViewInternal[];

package/dist/util/navigation_utils.d.ts

@@ -3,22 +3,124 @@ export declare function removeInitialAndTrailingSlashes(s: string): string;
 export declare function removeInitialSlash(s: string): string;
 export declare function removeTrailingSlash(s: string): string;
 export declare function addInitialSlash(s: string): string;
+/**
+ * Characters that would otherwise be read as structure once an entity id is joined into a
+ * path: "/" separates segments, "?" and "#" start the query and hash in a URL, and "%"
+ * has to be escaped first so that no escape sequence we introduce can be misread as one
+ * that was already part of the id.
+ *
+ * Entity ids are escaped ONLY inside URL-facing strings — anything handed to
+ * `buildUrlCollectionPath` or `navigate`. Every other path string (the `path` field of a
+ * navigation entry, datasource paths, `EntityReference.path`) carries raw ids.
+ *
+ * @group Hooks and utilities
+ */
+export declare function encodeEntityId(entityId: string): string;
+/**
+ * Inverse of {@link encodeEntityId}. "%25" is undone last, mirroring the encoder, so an id
+ * that legitimately contains the text "%2F" survives the round trip.
+ *
+ * @group Hooks and utilities
+ */
+export declare function decodeEntityId(encodedEntityId: string): string;
+/**
+ * Segments of a subcollection sitting under the entity `entityId` of `parentPathSegments`.
+ *
+ * The parent entity id is kept whole however many slashes it contains, while the
+ * subcollection's own configured path is spread — a collection path never contains an
+ * entity id, so splitting that one is unambiguous.
+ *
+ * So `["test"] + "test/test" + "accommodation"` yields three segments,
+ * `["test", "test/test", "accommodation"]`, where splitting the flattened path
+ * `"test/test/test/accommodation"` would wrongly yield four.
+ *
+ * Returns undefined when the parent segments are unknown: the parent chain cannot be
+ * recovered from a flattened path, so there is nothing honest to build on.
+ *
+ * @group Hooks and utilities
+ */
+export declare function buildSubcollectionPathSegments(parentPathSegments: string[] | undefined, entityId: string | undefined, subcollectionPath: string): string[] | undefined;
 export declare function getLastSegment(path: string): string;
-export declare function resolveCollectionPathIds(path: string, allCollections: EntityCollection[]): string;
+/**
+ * The outcome of walking a segment chain against a collection tree.
+ * @group Hooks and utilities
+ */
+export type PathSegmentsWalkStep = {
+    collection: EntityCollection;
+    /** Resolved path of this collection, e.g. `"products/pid/locales"`. */
+    collectionPath: string;
+    /** `collectionPath` split at its real segment boundaries. */
+    collectionSegments: string[];
+    /** The entity addressed inside it, when the chain continues past the collection. */
+    entityId?: string;
+};
+export type PathSegmentsWalk = {
+    /** Segments with every collection id replaced by the collection's real `path`. */
+    resolved: string[];
+    /** The collection the chain ends in, if the whole chain matched. */
+    collection?: EntityCollection;
+    /** One entry per collection level traversed, outermost first. */
+    steps: PathSegmentsWalkStep[];
+    /** The first segment that could not be matched, if the walk stopped early. */
+    unmatched?: string;
+};
+/**
+ * Walk a segment chain against a collection tree, matching a collection by either its
+ * `path` or its `id` and treating exactly one segment as each entity id.
+ *
+ * This is the primitive the string-based helpers cannot have: working on the flattened
+ * path they must *guess* where an entity id ends by reading up to the next "/", which is
+ * wrong for any id that contains one. Here the boundaries are given.
+ *
+ * Stops at the first segment it cannot match and reports it, rather than throwing.
+ *
+ * @group Hooks and utilities
+ */
+export declare function walkPathSegments(pathSegments: string[], allCollections: EntityCollection[]): PathSegmentsWalk;
+/**
+ * Resolve collection aliases in a segment array: every collection id is replaced by the
+ * collection's real `path`, and every entity id is carried through untouched.
+ *
+ * The segment-wise counterpart of {@link resolveCollectionPathIds}, and the reason it
+ * exists: that one works on the flattened string, so an entity id containing "/" shifts
+ * the rest of the chain by a segment and resolution fails with
+ * "Collection definition not found for segment starting with …".
+ *
+ * Matching accepts either a collection's `path` or its `id`, so already-resolved segments
+ * pass through unchanged — the function is idempotent.
+ *
+ * Mirrors the string version when a chain cannot be matched: it warns and carries the
+ * remainder through unresolved, rather than throwing.
+ *
+ * @group Hooks and utilities
+ */
+export declare function resolveCollectionPathSegments(pathSegments: string[], allCollections: EntityCollection[]): string[];
+/**
+ * Find the collection a segment chain addresses, whether it ends on the collection itself
+ * or on one of its entities.
+ *
+ * The segment-wise counterpart of {@link getCollectionByPathOrId}, which asserts an odd
+ * number of "/"-separated parts — an assertion a slash-bearing entity id fails, throwing
+ * where it should simply have resolved.
+ *
+ * @group Hooks and utilities
+ */
+export declare function getCollectionByPathSegments(pathSegments: string[], collections: EntityCollection[]): EntityCollection | undefined;
+export declare function resolveCollectionPathIds(path: string, allCollections: EntityCollection[], pathSegments?: string[]): string;
 /**
  * Find the corresponding view at any depth for a given path.
  * Note that path or segments of the paths can be collection aliases.
  * @param pathOrId
  * @param collections
  */
-export declare function getCollectionByPathOrId(pathOrId: string, collections: EntityCollection[]): EntityCollection | undefined;
+export declare function getCollectionByPathOrId(pathOrId: string, collections: EntityCollection[], pathSegments?: string[]): EntityCollection | undefined;
 /**
  * Get the subcollection combinations from a path:
  * "sites/es/locales" => ["sites/es/locales", "sites"]
  * @param subpaths
  */
 export declare function getCollectionPathsCombinations(subpaths: string[]): string[];
-export declare function navigateToEntity({ openEntityMode, collection, entityId, copy, path, fullIdPath, selectedTab, sideEntityController, onClose, navigation }: {
+export declare function navigateToEntity({ openEntityMode, collection, entityId, copy, path, fullIdPath, pathSegments, selectedTab, sideEntityController, onClose, navigation }: {
     openEntityMode: "side_panel" | "full_screen";
     collection?: EntityCollection;
     entityId?: string;
@@ -26,6 +128,8 @@ export declare function navigateToEntity({ openEntityMode, collection, entityId,
     copy?: boolean;
     path: string;
     fullIdPath?: string;
+    /** `path` split at its real segment boundaries. */
+    pathSegments?: string[];
     sideEntityController: SideEntityController;
     onClose?: () => void;
     navigation: NavigationController;

package/dist/util/parent_references_from_path.d.ts

@@ -1,6 +1,22 @@
 import { EntityCollection, EntityReference } from "../types";
+/**
+ * References to every parent entity in a path.
+ *
+ * NOTE on encoding: `path` is expected ESCAPED, because it comes from the URL — the entity
+ * ids in it are decoded on the way out. Pass `pathSegments` instead whenever the path at
+ * hand is a raw datasource path (`entity.path`), which is not escaped and whose ids may
+ * therefore contain a bare "/": splitting that would silently produce the wrong references.
+ */
 export declare function getParentReferencesFromPath(props: {
     path: string;
     collections: EntityCollection[] | undefined;
     currentFullPath?: string;
+    currentPathSegments?: string[];
+    /** `path` split at its real segment boundaries, with RAW ids. Takes precedence. */
+    pathSegments?: string[];
 }): EntityReference[];
+/**
+ * The segment-wise counterpart: the boundaries are given, so an entity id keeps its
+ * slashes and nothing has to be decoded.
+ */
+export declare function getParentReferencesFromPathSegments(pathSegments: string[], collections: EntityCollection[]): EntityReference[];

package/dist/util/paths.d.ts

@@ -9,6 +9,34 @@ export declare function segmentsToStrippedPath(paths: string[]): string;
 /**
  * Extract the collection path routes
  * `products/B44RG6APH/locales` => [`products`, `locales`]
+ *
+ * Finds the entity ids by position, which only works while no id contains "/" — with one,
+ * every following segment shifts and the wrong elements are kept. Use
+ * {@link collectionSegmentsFrom} when the real boundaries are known.
+ *
  * @param path
  */
 export declare function fullPathToCollectionSegments(path: string): string[];
+/**
+ * The collection chain of an already-segmented path:
+ * `['products', 'B44RG6APH', 'locales']` => [`products`, `locales`]
+ *
+ * The counterpart of {@link fullPathToCollectionSegments} for callers that know the real
+ * segment boundaries. Kept as a separate function rather than an extra parameter on that
+ * one: these helpers are small enough to be passed point-free, and `paths.map(fn)` would
+ * then hand the array index in as the new argument.
+ */
+export declare function collectionSegmentsFrom(pathSegments: string[]): string[];
+/**
+ * The historical, positional reading of a flattened path:
+ * `products/B44RG6APH/locales` => [`products`, `locales`]
+ *
+ * This produces a **collection chain**, not a datasource `pathSegments` value, and must
+ * never be used as one — see `path_segments_no_fabrication.test.ts`. It is only correct
+ * while no entity id contains "/", which is why every caller prefers real segments when
+ * they are available, and why it is named for what it assumes.
+ *
+ * It is still the right reading for a path that came from a URL, where entity ids arrive
+ * escaped and so cannot contain a bare "/".
+ */
+export declare function positionalCollectionSegments(path: string): string[];