@rebasepro/admin 0.5.0 → 0.6.1

package/src/components/EntityCollectionView/EntityCollectionView.tsx

@@ -2,10 +2,11 @@
 import type { AdditionalFieldDelegate, EntityCollection } from "@rebasepro/types";
 import type { EntityAction, Property } from "@rebasepro/types";
 import React, { useCallback, useEffect, useMemo, useState } from "react";
+import { useSearchParams } from "react-router-dom";
 
 import { deepEqual as equal } from "fast-equals"
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any -- used as fallback for many array types
+
 const EMPTY_ARRAY: any[] = [];
 const DEFAULT_ENTITY_OPEN_MODE = "split";
 
@@ -31,7 +32,9 @@ import {
     usePermissions,
     useTranslation,
     useSlot,
-    IconForView
+    IconForView,
+    useComponentOverride,
+    CollectionComponentOverrideProvider
 } from "@rebasepro/core";
 import { useUserConfigurationPersistence } from "@rebasepro/core";
 import { EntityCollectionViewActions } from "./EntityCollectionViewActions";
@@ -40,7 +43,7 @@ import { EntityCollectionListView } from "./EntityCollectionListView";
 import { SplitListView } from "./SplitListView";
 import { EntityCollectionBoardView } from "./EntityCollectionBoardView";
 import { ViewModeToggle, KanbanPropertyOption } from "./ViewModeToggle";
-import { Button, cls, focusedDisabled, IconButton, Markdown, Popover, Skeleton, TextField, Tooltip, Typography, VirtualTableColumn , iconSize } from "@rebasepro/ui";
+import { Button, cls, focusedDisabled, IconButton, Markdown, Popover, Skeleton, TextField, Tooltip, Typography, VirtualTableColumn, iconSize } from "@rebasepro/ui";
 import { ArrowRightToLineIcon, ErrorBoundary, PlusIcon, SearchIcon } from "@rebasepro/ui";
 import { setIn } from "@rebasepro/formex";
 import { getSubcollectionColumnId } from "../EntityCollectionTable/internal/common";
@@ -141,8 +144,8 @@ export type EntityCollectionViewProps<M extends Record<string, unknown>> = {
 
  * @group Components
  */
-export const EntityCollectionView = React.memo(
-    function EntityCollectionView<M extends Record<string, unknown>>({
+const EntityCollectionViewInner = React.memo(
+    function EntityCollectionViewInner<M extends Record<string, unknown>>({
         path: pathProp,
 
         parentCollectionSlugs, parentEntityIds,
@@ -227,16 +230,16 @@ export const EntityCollectionView = React.memo(
 
         // View mode priority: URL > saved user config > collection.defaultViewMode
         const defaultViewMode = collection.defaultViewMode ?? "list";
+        const [searchParams, setSearchParams] = useSearchParams();
 
-        // Parse view from URL
-        const getViewFromUrl = useCallback((): ViewMode | null => {
-            const params = new URLSearchParams(window.location.search);
-            const urlView = params.get("__view");
-            if (urlView && ["list", "table", "kanban", "cards"].includes(urlView)) {
-                return urlView as ViewMode;
+        // Read view from React Router's searchParams (reactive on back/forward)
+        const urlView = useMemo((): ViewMode | null => {
+            const v = searchParams.get("__view");
+            if (v && ["list", "table", "kanban", "cards"].includes(v)) {
+                return v as ViewMode;
             }
             return null;
-        }, []);
+        }, [searchParams]);
 
         // Get saved view from local persistence
         const getSavedView = useCallback((): ViewMode | null => {
@@ -246,7 +249,6 @@ export const EntityCollectionView = React.memo(
 
         const [viewMode, setViewModeState] = useState<ViewMode>(() => {
             // Priority: URL > saved config > collection default
-            const urlView = getViewFromUrl();
             if (urlView) return urlView;
             const savedView = getSavedView();
             if (savedView) return savedView;
@@ -257,12 +259,13 @@ export const EntityCollectionView = React.memo(
 
         // Sync URL with current view on init (if view came from saved config)
         useEffect(() => {
-            const urlView = getViewFromUrl();
             if (!urlView && viewMode !== defaultViewMode) {
                 // View came from saved config but URL doesn't have it - update URL without push
-                const url = new URL(window.location.href);
-                url.searchParams.set("__view", viewMode);
-                window.history.replaceState({}, "", url.toString());
+                setSearchParams((prev) => {
+                    const next = new URLSearchParams(prev);
+                    next.set("__view", viewMode);
+                    return next;
+                }, { replace: true });
             }
         }, []); // Only on mount
 
@@ -270,33 +273,27 @@ export const EntityCollectionView = React.memo(
         const setViewMode = useCallback((newMode: ViewMode) => {
             setViewModeState(newMode);
 
-            // Update URL with __view param
-            const url = new URL(window.location.href);
-            if (newMode === defaultViewMode) {
-                url.searchParams.delete("__view");
-            } else {
-                url.searchParams.set("__view", newMode);
-            }
-            window.history.pushState({}, "", url.toString());
-        }, [defaultViewMode]);
-
-        // Listen for browser back/forward
-        useEffect(() => {
-            const handlePopState = () => {
-                const urlView = getViewFromUrl();
-                if (urlView) {
-                    // URL has explicit view - use it
-                    setViewModeState(urlView);
+            // Update URL with __view param via React Router
+            setSearchParams((prev) => {
+                const next = new URLSearchParams(prev);
+                if (newMode === defaultViewMode) {
+                    next.delete("__view");
                 } else {
-                    // No URL param - fallback to saved config or collection default
-                    const savedView = getSavedView();
-                    setViewModeState(savedView ?? defaultViewMode);
+                    next.set("__view", newMode);
                 }
-            };
+                return next;
+            });
+        }, [defaultViewMode, setSearchParams]);
 
-            window.addEventListener("popstate", handlePopState);
-            return () => window.removeEventListener("popstate", handlePopState);
-        }, [getViewFromUrl, getSavedView, defaultViewMode]);
+        // Sync viewMode state when URL changes via back/forward navigation
+        useEffect(() => {
+            if (urlView) {
+                setViewModeState(urlView);
+            } else {
+                const savedView = getSavedView();
+                setViewModeState(savedView ?? defaultViewMode);
+            }
+        }, [urlView, getSavedView, defaultViewMode]);
 
         // List view size state - controls row height and info density
         const [listSize, setListSize] = useState<CollectionSize>(collection.defaultSize ?? "m");
@@ -352,10 +349,11 @@ export const EntityCollectionView = React.memo(
                 sideEntityController,
                 openEntityMode,
                 collection,
-                entityId: clickedEntity.id
+                entityId: clickedEntity.id,
+                replace: openEntityMode === "split" && selectedEntityIdProp !== undefined
             });
 
-        }, [unselectNavigatedEntity, sideEntityController]);
+        }, [sideEntityController, openEntityMode, selectedEntityIdProp, path, urlController, analyticsController]);
 
         const onNewClick = useCallback(() => {
             const collection = collectionRef.current;
@@ -418,14 +416,16 @@ export const EntityCollectionView = React.memo(
 
         const pluginAddColumnComponents = useSlot("collection.add-column", {
             path,
-            parentCollectionSlugs: parentCollectionSlugs ?? EMPTY_ARRAY, parentEntityIds: parentEntityIds ?? EMPTY_ARRAY,
+            parentCollectionSlugs: parentCollectionSlugs ?? EMPTY_ARRAY,
+parentEntityIds: parentEntityIds ?? EMPTY_ARRAY,
             collection,
             tableController
         });
 
         const pluginToolbarWidgets = useSlot("collection.toolbar", {
             path,
-            parentCollectionSlugs: parentCollectionSlugs ?? EMPTY_ARRAY, parentEntityIds: parentEntityIds ?? EMPTY_ARRAY,
+            parentCollectionSlugs: parentCollectionSlugs ?? EMPTY_ARRAY,
+parentEntityIds: parentEntityIds ?? EMPTY_ARRAY,
             collection: collection,
             tableController: tableController,
             selectionController: usedSelectionController
@@ -433,7 +433,8 @@ export const EntityCollectionView = React.memo(
 
         const pluginEmptyStates = useSlot("collection.empty-state", {
             path,
-            parentCollectionSlugs: parentCollectionSlugs ?? EMPTY_ARRAY, parentEntityIds: parentEntityIds ?? EMPTY_ARRAY,
+            parentCollectionSlugs: parentCollectionSlugs ?? EMPTY_ARRAY,
+parentEntityIds: parentEntityIds ?? EMPTY_ARRAY,
             collection,
             canCreate: canCreateEntities,
             onNewClick
@@ -441,7 +442,8 @@ export const EntityCollectionView = React.memo(
 
         const pluginInsights = useSlot("collection.insights", {
             path,
-            parentCollectionSlugs: parentCollectionSlugs ?? EMPTY_ARRAY, parentEntityIds: parentEntityIds ?? EMPTY_ARRAY,
+            parentCollectionSlugs: parentCollectionSlugs ?? EMPTY_ARRAY,
+parentEntityIds: parentEntityIds ?? EMPTY_ARRAY,
             collection
         });
 
@@ -776,7 +778,8 @@ export const EntityCollectionView = React.memo(
                 path,
                 collection: collection as EntityCollection,
                 tableController: tableController as EntityTableController,
-                parentCollectionSlugs: parentCollectionSlugs ?? EMPTY_ARRAY, parentEntityIds: parentEntityIds ?? EMPTY_ARRAY
+                parentCollectionSlugs: parentCollectionSlugs ?? EMPTY_ARRAY,
+parentEntityIds: parentEntityIds ?? EMPTY_ARRAY
             };
             return <>{headerActionContributions.map((s, i) => (
                 <ErrorBoundary key={`header_action_${propertyKey}_${i}`}>
@@ -819,13 +822,19 @@ export const EntityCollectionView = React.memo(
                     .forEach(plugin => {
                         plugin.hooks!.onColumnsReorder!({
                             fullPath: path,
-                            parentCollectionSlugs: parentCollectionSlugs ?? EMPTY_ARRAY, parentEntityIds: parentEntityIds ?? EMPTY_ARRAY,
+                            parentCollectionSlugs: parentCollectionSlugs ?? EMPTY_ARRAY,
+                            parentEntityIds: parentEntityIds ?? EMPTY_ARRAY,
                             collection,
                             newPropertiesOrder
                         });
                     });
             }
-        }, [collection, setLocalPropertiesOrder, customizationController, path, parentCollectionSlugs]);
+
+            // Save to user configuration persistence (local storage)
+            if (userConfigPersistence) {
+                onCollectionModifiedForUser(path, { propertiesOrder: newPropertiesOrder } as PartialEntityCollection<M>);
+            }
+        }, [collection, setLocalPropertiesOrder, customizationController, path, parentCollectionSlugs, parentEntityIds, userConfigPersistence, onCollectionModifiedForUser]);
 
         // Popover open state managed at parent level to prevent closing when view changes
         const [viewModePopoverOpen, setViewModePopoverOpen] = useState(false);
@@ -850,34 +859,28 @@ export const EntityCollectionView = React.memo(
         const pluginErrorViews = useSlot("collection.error", {
             path,
             collection,
-            parentCollectionSlugs, parentEntityIds,
+            parentCollectionSlugs,
+parentEntityIds,
             error: tableController.dataLoadingError as Error
         });
         const pluginErrorView = tableController.dataLoadingError && pluginErrorViews.length > 0
             ? pluginErrorViews[0]
             : null;
 
-        // Shared empty state — plugin slot takes priority, then default
+        // Shared empty state — plugin slot takes priority, then override, then default
         const isSearching = !!tableController.searchString;
         const isFilteredOrSorted = tableController.filterValues !== undefined || tableController.sortBy !== undefined || isSearching;
+        const ResolvedEmptyState = useComponentOverride("Collection.EmptyState", DefaultCollectionEmptyState);
+        const ResolvedCollectionActions = useComponentOverride("Collection.Actions", EntityCollectionViewActions);
+        const ResolvedCollectionTable = useComponentOverride("Collection.Table", EntityCollectionTable) as typeof EntityCollectionTable;
         const emptyComponent = pluginEmptyStates.length > 0
             ? <>{pluginEmptyStates}</>
-            : canCreateEntities && !isFilteredOrSorted
-                ? <div className="flex flex-col items-center justify-center">
-                    <Typography variant={"subtitle2"}>{t("so_empty")}</Typography>
-                    <Button
-                        onClick={onNewClick}
-                        className="mt-4"
-                    >
-                        <PlusIcon/>
-                        {t("create_your_first_entry")}
-                    </Button>
-                </div>
-                : <Typography variant={"label"}>
-                    {isSearching
-                        ? t("no_results_search", { search: tableController.searchString ?? "" })
-                        : t("no_results_filter_sort")}
-                </Typography>;
+            : <ResolvedEmptyState
+                canCreate={canCreateEntities && !isFilteredOrSorted}
+                onNewClick={onNewClick}
+                isSearching={isSearching}
+                searchString={tableController.searchString ?? ""}
+            />;
 
         const toolbarNode = (
             <CollectionTableToolbar
@@ -898,7 +901,7 @@ export const EntityCollectionView = React.memo(
                     openNewDocument={openNewDocument}
                     compact={isCompact}/>}
                 actions={
-                    <EntityCollectionViewActions
+                    <ResolvedCollectionActions
                         parentCollectionSlugs={parentCollectionSlugs ?? EMPTY_ARRAY} parentEntityIds={parentEntityIds ?? EMPTY_ARRAY}
                         collection={collection}
                         tableController={tableController}
@@ -913,7 +916,7 @@ export const EntityCollectionView = React.memo(
                         compact={isCompact}
                     >
                         {pluginToolbarWidgets}
-                    </EntityCollectionViewActions>
+                    </ResolvedCollectionActions>
                 }
             />
         ); const innerView = viewMode === "kanban" ? (
@@ -961,7 +964,7 @@ export const EntityCollectionView = React.memo(
                 openEntityMode={openEntityMode}
             />
         ) : (
-            <EntityCollectionTable
+            <ResolvedCollectionTable
                 key={`collection_table_${path}`}
                 hideToolbar={true}
                 additionalFields={additionalFields}
@@ -996,12 +999,20 @@ export const EntityCollectionView = React.memo(
             />
         );
 
-        return (
+        const mainContent = (
             <div className={cls("overflow-hidden h-full w-full rounded-md flex flex-col dark:bg-surface-800", className)}
                 ref={containerRef}>
 
                 {countFetcher}
 
+                {tableController.dataLoadingError && tableController.data.length > 0 && (
+                    <div className="flex items-center gap-4 px-4 py-2 bg-red-50 dark:bg-red-900/20 border-b border-red-200 dark:border-red-800 flex-shrink-0">
+                        <Typography variant="body2" className="text-red-700 dark:text-red-300 flex-1">
+                            <strong>Warning:</strong> {tableController.dataLoadingError.message || "Failed to update data."}
+                        </Typography>
+                    </div>
+                )}
+
 
                 {/* When isSplitLayout, SplitListView is ALWAYS mounted — regardless
                     of viewMode. The toolbar + current view live in the left panel;
@@ -1160,6 +1171,8 @@ export const EntityCollectionView = React.memo(
 
             </div>
         );
+
+        return mainContent;
     }, (a, b) => {
         return equal(a.path, b.path) &&
             equal(a.parentCollectionSlugs, b.parentCollectionSlugs) && equal(a.parentEntityIds, b.parentEntityIds) &&
@@ -1182,7 +1195,67 @@ export const EntityCollectionView = React.memo(
             equal(a.fixedFilter, b.fixedFilter) &&
             equal(a.selectedEntityId, b.selectedEntityId) &&
             equal(a.selectedTab, b.selectedTab);
-    }) as React.FunctionComponent<EntityCollectionViewProps<any>>
+    }) as React.FunctionComponent<EntityCollectionViewProps<any>>;
+
+export const EntityCollectionView = React.memo(
+    function EntityCollectionView<M extends Record<string, unknown>>(props: EntityCollectionViewProps<M>) {
+        const collectionRegistry = useCollectionRegistryController();
+        const path = props.path ?? props.slug;
+        const collection = collectionRegistry.getCollection(path) ?? props;
+
+        const content = <EntityCollectionViewInner {...props} />;
+
+        if (collection?.components) {
+            return (
+                <CollectionComponentOverrideProvider overrides={collection.components}>
+                    {content}
+                </CollectionComponentOverrideProvider>
+            );
+        }
+        return content;
+    }
+) as React.FunctionComponent<EntityCollectionViewProps<any>>;
+
+/**
+ * Default empty state shown when a collection has no entities.
+ * Used as the fallback for the `"Collection.EmptyState"` component override.
+ *
+ * @internal
+ */
+function DefaultCollectionEmptyState({
+    canCreate,
+    onNewClick,
+    isSearching,
+    searchString
+}: {
+    canCreate: boolean;
+    onNewClick: () => void;
+    isSearching: boolean;
+    searchString: string;
+}) {
+    const { t } = useTranslation();
+    if (canCreate) {
+        return (
+            <div className="flex flex-col items-center justify-center">
+                <Typography variant={"subtitle2"}>{t("so_empty")}</Typography>
+                <Button
+                    onClick={onNewClick}
+                    className="mt-4"
+                >
+                    <PlusIcon/>
+                    {t("create_your_first_entry")}
+                </Button>
+            </div>
+        );
+    }
+    return (
+        <Typography variant={"label"}>
+            {isSearching
+                ? t("no_results_search", { search: searchString })
+                : t("no_results_filter_sort")}
+        </Typography>
+    );
+}
 
 /**
  * Inflight count request deduplication map.

package/src/components/EntityCollectionView/EntityCollectionViewActions.tsx

@@ -112,7 +112,8 @@ export function EntityCollectionViewActions<M extends Record<string, unknown>>({
     const actionProps: CollectionActionsProps<M> = {
         path,
         relativePath,
-        parentCollectionSlugs, parentEntityIds,
+        parentCollectionSlugs,
+parentEntityIds,
         collection,
         selectionController,
         context,

package/src/components/EntityCollectionView/EntityCollectionViewStartActions.tsx

@@ -3,7 +3,7 @@ import type { EntityCollection } from "@rebasepro/types";
 import React, { useState, useCallback } from "react";
 import { useAuthController, useLargeLayout, useTranslation, useSlot } from "@rebasepro/core";
 import { CollectionActionsProps, EntityTableController, SelectionController } from "@rebasepro/types";
-import { ErrorBoundary , iconSize } from "@rebasepro/ui";
+import { ErrorBoundary, iconSize } from "@rebasepro/ui";
 import { ArrowLeftIcon, Badge, Button, cls, FilterIcon, IconButton, Tooltip } from "@rebasepro/ui";
 import { ClearFilterSortButton } from "../ClearFilterSortButton";
 import { FiltersDialog } from "./FiltersDialog";
@@ -61,7 +61,8 @@ export function EntityCollectionViewStartActions<M extends Record<string, unknow
     const actionProps: CollectionActionsProps<M> = {
         path,
         relativePath,
-        parentCollectionSlugs, parentEntityIds,
+        parentCollectionSlugs,
+parentEntityIds,
         collection,
         selectionController,
         context,

package/src/components/EntityCollectionView/FilterPresetsButton.tsx

@@ -79,8 +79,10 @@ function generateLabel(filterValues: FilterValues<string>): string {
  * Truncate a label if it exceeds MAX_LABEL_LENGTH.
  */
 function truncateLabel(label: string): { display: string; truncated: boolean } {
-    if (label.length <= MAX_LABEL_LENGTH) return { display: label, truncated: false };
-    return { display: label.slice(0, MAX_LABEL_LENGTH - 1) + "…", truncated: true };
+    if (label.length <= MAX_LABEL_LENGTH) return { display: label,
+truncated: false };
+    return { display: label.slice(0, MAX_LABEL_LENGTH - 1) + "…",
+truncated: true };
 }
 
 // ─── Overflow Menu ──────────────────────────────────────────────────

package/src/components/EntityCollectionView/ViewModeToggle.tsx

@@ -79,7 +79,6 @@ export function ViewModeToggle({
     const { t } = useTranslation();
 
 
-
     // Get icon for current view mode
     const getViewModeIcon = () => {
         if (viewMode === "kanban") return <KanbanIcon size={iconSize.smallest}/>;

package/src/components/EntityCollectionView/useBoardDataController.tsx

@@ -276,7 +276,7 @@ export function useBoardDataController<M extends Record<string, unknown> = any,
             if (isCleaningUpRef.current) return;
 
             const pendingMap = pendingItemsRef.current;
-            
+
             // Apply pending updates to incoming entities
             const mergedEntities = entities.map(e => {
                 const pending = pendingMap[String(e.id)];
@@ -284,7 +284,7 @@ export function useBoardDataController<M extends Record<string, unknown> = any,
                     // Check if DB entity has caught up to the expected column and order
                     const expectedCol = pending.expectedValues[currentColumnProperty];
                     const expectedOrder = currentOrderProperty ? pending.expectedValues[currentOrderProperty] : undefined;
-                    
+
                     let caughtUp = true;
                     if (e.values?.[currentColumnProperty] !== expectedCol) {
                         caughtUp = false;
@@ -292,15 +292,17 @@ export function useBoardDataController<M extends Record<string, unknown> = any,
                     if (currentOrderProperty && e.values?.[currentOrderProperty] !== expectedOrder) {
                         caughtUp = false;
                     }
-                    
+
                     if (caughtUp) {
                         // DB has caught up, clear pending state
                         delete pendingMap[String(e.id)];
                         return e; // Use the real DB entity
                     }
-                    
+
                     // DB hasn't caught up, overlay expected values
-                    return { ...e, values: { ...e.values, ...pending.expectedValues } };
+                    return { ...e,
+values: { ...e.values,
+...pending.expectedValues } };
                 }
                 return e;
             });
@@ -326,14 +328,14 @@ export function useBoardDataController<M extends Record<string, unknown> = any,
                 processed = [...processed].sort((a, b) => {
                     const valA = a.values?.[currentOrderProperty] as string | undefined | null;
                     const valB = b.values?.[currentOrderProperty] as string | undefined | null;
-                    
+
                     const isAEmpty = valA === undefined || valA === null || valA === "";
                     const isBEmpty = valB === undefined || valB === null || valB === "";
-                    
+
                     if (isAEmpty && isBEmpty) return 0;
                     if (isAEmpty) return 1;
                     if (isBEmpty) return -1;
-                    
+
                     return valA < valB ? -1 : valA > valB ? 1 : 0;
                 });
             }
@@ -618,7 +620,7 @@ export function useBoardDataController<M extends Record<string, unknown> = any,
                     ...itemToMove.values,
                     ...(newValues || {})
                 };
-                
+
                 const updatedEntity = {
                     ...itemToMove,
                     values: newValuesMerged
@@ -631,7 +633,7 @@ export function useBoardDataController<M extends Record<string, unknown> = any,
                 };
 
                 const targetEntities = sourceColumn === targetColumn ? sourceEntities : [...(updated[targetColumn]?.entities || [])];
-                
+
                 if (newIndex !== undefined && newIndex >= 0 && newIndex <= targetEntities.length) {
                     targetEntities.splice(newIndex, 0, updatedEntity);
                 } else {
@@ -641,15 +643,15 @@ export function useBoardDataController<M extends Record<string, unknown> = any,
                         targetEntities.sort((a, b) => {
                             const valA = a.values?.[orderProp] as string | undefined | null;
                             const valB = b.values?.[orderProp] as string | undefined | null;
-                            
+
                             // Handle nulls/empty strings to match Postgres NULLS LAST (ASC) behavior
                             const isAEmpty = valA === undefined || valA === null || valA === "";
                             const isBEmpty = valB === undefined || valB === null || valB === "";
-                            
+
                             if (isAEmpty && isBEmpty) return 0;
                             if (isAEmpty) return 1; // A is null, B is not -> A goes after B
                             if (isBEmpty) return -1; // B is null, A is not -> A goes before B
-                            
+
                             return valA < valB ? -1 : valA > valB ? 1 : 0;
                         });
                     }
@@ -658,8 +660,8 @@ export function useBoardDataController<M extends Record<string, unknown> = any,
                 updated[sourceColumn] = {
                     ...updated[sourceColumn],
                     entities: sourceColumn === targetColumn ? targetEntities : sourceEntities,
-                    totalCount: sourceColumn === targetColumn 
-                        ? updated[sourceColumn].totalCount 
+                    totalCount: sourceColumn === targetColumn
+                        ? updated[sourceColumn].totalCount
                         : Math.max(0, (updated[sourceColumn].totalCount ?? 0) - 1)
                 };
 

package/src/components/EntityCollectionView/useEntityPreviewSlots.ts

@@ -166,31 +166,38 @@ export function resolveCollectionSlotKeys(
         }
     }
 
-    // Relations: collect ALL relation property keys.
-    // We iterate properties (not a hardcoded key list) and check the
-    // resolved relation metadata for type === "relation".
+    // Relations: collect relation property keys for chip rendering.
+    // When propertiesOrder is explicitly set, skip this — relations will
+    // be shown in the developer-defined order, not as separate chips.
+    const hasExplicitOrder = !!(collection.propertiesOrder as string[] | undefined);
     const relationKeys: string[] = [];
-    for (const [key, prop] of Object.entries(collection.properties)) {
-        const p = prop as Property;
-        if (p.type === "relation") {
-            relationKeys.push(key);
+    if (!hasExplicitOrder) {
+        for (const [key, prop] of Object.entries(collection.properties)) {
+            const p = prop as Property;
+            if (p.type === "relation") {
+                relationKeys.push(key);
+            }
         }
     }
 
-    // Subtitle: first preview key that isn't title/image/status/date/relation/id.
+    // Subtitle: first preview key that isn't title/image/status/date/id.
+    // When propertiesOrder is not set, also exclude relation keys (they render as chips).
     // Prefer string fields (especially multiline/description-like) over numbers.
     const excludeKeys = new Set([titleKey, imageKey, statusKey, dateKey, ...relationKeys]);
     const previewKeys = getEntityPreviewKeys(authController, collection, propertyConfigs, undefined, 10)
         .filter(k => !excludeKeys.has(k) && k !== "id");
 
-    // Sort: strings first (prefer multiline → good description candidate), then others
-    const sortedPreviewKeys = [...previewKeys].sort((a, b) => {
-        const propA = collection.properties[a] as Property | undefined;
-        const propB = collection.properties[b] as Property | undefined;
-        const scoreA = propA?.type === "string" ? (propA.multiline ? 2 : 1) : 0;
-        const scoreB = propB?.type === "string" ? (propB.multiline ? 2 : 1) : 0;
-        return scoreB - scoreA;
-    });
+    // When propertiesOrder is set, respect the developer-defined order (no re-sorting).
+    // When not set, sort: strings first (prefer multiline → good description candidate).
+    const sortedPreviewKeys = hasExplicitOrder
+        ? previewKeys
+        : [...previewKeys].sort((a, b) => {
+            const propA = collection.properties[a] as Property | undefined;
+            const propB = collection.properties[b] as Property | undefined;
+            const scoreA = propA?.type === "string" ? (propA.multiline ? 2 : 1) : 0;
+            const scoreB = propB?.type === "string" ? (propB.multiline ? 2 : 1) : 0;
+            return scoreB - scoreA;
+        });
     const subtitleKey = sortedPreviewKeys.length > 0 ? sortedPreviewKeys[0] : undefined;
 
     return { titleKey,
@@ -333,7 +340,7 @@ value: val };
         const items: RelationChipItem[] = [];
         let totalCount = 0;
 
-        const isMany = prop.relation?.cardinality === "many";
+        const isMany = prop.cardinality === "many" || prop.relation?.cardinality === "many";
 
         if (isMany && Array.isArray(val)) {
             // cardinality:"many" → array of EntityRelation
@@ -351,9 +358,12 @@ id });
             }
         } else if (!isMany && val && typeof val === "object") {
             // cardinality:"one" → single EntityRelation
-            const isRelation = "__type" in val && (val as Record<string, unknown>).__type === "relation";
+            const obj = val as Record<string, unknown>;
+            const isRelation = ("__type" in obj && obj.__type === "relation")
+                || (typeof obj.isEntityRelation === "function"
+                    && (obj.isEntityRelation as () => boolean)());
             if (isRelation) {
-                const relation = val as EntityRelation;
+                const relation = obj as unknown as EntityRelation;
                 const displayName = resolveRelationDisplayName(relation, prop);
                 totalCount = 1;
                 if (displayName) {