@vendure/dashboard 3.5.1-master-202511080229 → 3.5.1-master-202511120232

package/src/lib/framework/document-introspection/add-custom-fields.ts

@@ -27,6 +27,7 @@ let globalCustomFieldsMap: Map<string, CustomFieldConfig[]> = new Map();
 
 // Memoization cache using WeakMap to avoid memory leaks
 const memoizationCache = new WeakMap<DocumentNode, Map<string, TypedDocumentNode<any, any>>>();
+const fragmentMemoizationCache = new WeakMap<DocumentNode, Map<string, TypedDocumentNode<any, any>>>();
 
 /**
  * Creates a cache key for the options object
@@ -34,6 +35,7 @@ const memoizationCache = new WeakMap<DocumentNode, Map<string, TypedDocumentNode
 function createOptionsKey(options?: {
     customFieldsMap?: Map<string, CustomFieldConfig[]>;
     includeCustomFields?: string[];
+    includeNestedFragments?: string[];
 }): string {
     if (!options) return 'default';
 
@@ -51,6 +53,10 @@ function createOptionsKey(options?: {
         parts.push(`include:${options.includeCustomFields.sort().join(',')}`);
     }
 
+    if (options.includeNestedFragments) {
+        parts.push(`nested:${options.includeNestedFragments.sort().join(',')}`);
+    }
+
     return parts.join('|') || 'default';
 }
 
@@ -82,10 +88,232 @@ export function getCustomFieldsMap() {
     return globalCustomFieldsMap;
 }
 
+/**
+ * @description
+ * Internal helper function that applies custom fields to a selection set for a given entity type.
+ * This is the core logic extracted for reuse.
+ */
+function applyCustomFieldsToSelection(
+    typeName: string,
+    selectionSet: SelectionSetNode,
+    customFields: Map<string, CustomFieldConfig[]>,
+    options?: {
+        includeCustomFields?: string[];
+    },
+): void {
+    let entityType = typeName;
+
+    if (entityType === ('OrderAddress' as any)) {
+        // OrderAddress is a special case of the Address entity, and shares its custom fields
+        // so we treat it as an alias
+        entityType = 'Address';
+    }
+
+    if (entityType === ('Country' as any)) {
+        // Country is an alias of Region
+        entityType = 'Region';
+    }
+
+    const customFieldsForType = customFields.get(entityType);
+    if (customFieldsForType && customFieldsForType.length) {
+        // Check if there is already a customFields field in the fragment
+        // to avoid duplication
+        const existingCustomFieldsField = selectionSet.selections.find(
+            selection => isFieldNode(selection) && selection.name.value === 'customFields',
+        ) as FieldNode | undefined;
+        const selectionNodes: SelectionNode[] = customFieldsForType
+            .filter(
+                field => !options?.includeCustomFields || options?.includeCustomFields.includes(field.name),
+            )
+            .map(
+                customField =>
+                    ({
+                        kind: Kind.FIELD,
+                        name: {
+                            kind: Kind.NAME,
+                            value: customField.name,
+                        },
+                        // For "relation" custom fields, we need to also select
+                        // all the scalar fields of the related type
+                        ...(customField.type === 'relation'
+                            ? {
+                                  selectionSet: {
+                                      kind: Kind.SELECTION_SET,
+                                      selections: (
+                                          customField as RelationCustomFieldFragment
+                                      ).scalarFields.map(f => ({
+                                          kind: Kind.FIELD,
+                                          name: { kind: Kind.NAME, value: f },
+                                      })),
+                                  },
+                              }
+                            : {}),
+                        ...(customField.type === 'struct'
+                            ? {
+                                  selectionSet: {
+                                      kind: Kind.SELECTION_SET,
+                                      selections: (customField as StructCustomFieldFragment).fields.map(
+                                          f => ({
+                                              kind: Kind.FIELD,
+                                              name: { kind: Kind.NAME, value: f.name },
+                                          }),
+                                      ),
+                                  },
+                              }
+                            : {}),
+                    }) as FieldNode,
+            );
+        if (!existingCustomFieldsField) {
+            // If no customFields field exists, add one
+            (selectionSet.selections as SelectionNode[]).push({
+                kind: Kind.FIELD,
+                name: {
+                    kind: Kind.NAME,
+                    value: 'customFields',
+                },
+                selectionSet: {
+                    kind: Kind.SELECTION_SET,
+                    selections: selectionNodes,
+                },
+            });
+        } else {
+            // If a customFields field already exists, add the custom fields
+            // to the existing selection set
+            (existingCustomFieldsField.selectionSet as any) = {
+                kind: Kind.SELECTION_SET,
+                selections: selectionNodes,
+            };
+        }
+
+        const localizedFields = customFieldsForType.filter(
+            field => field.type === 'localeString' || field.type === 'localeText',
+        );
+
+        const translationsField = selectionSet.selections
+            .filter(isFieldNode)
+            .find(field => field.name.value === 'translations');
+
+        if (localizedFields.length && translationsField && translationsField.selectionSet) {
+            (translationsField.selectionSet.selections as SelectionNode[]).push({
+                name: {
+                    kind: Kind.NAME,
+                    value: 'customFields',
+                },
+                kind: Kind.FIELD,
+                selectionSet: {
+                    kind: Kind.SELECTION_SET,
+                    selections: localizedFields.map(
+                        customField =>
+                            ({
+                                kind: Kind.FIELD,
+                                name: {
+                                    kind: Kind.NAME,
+                                    value: customField.name,
+                                },
+                            }) as FieldNode,
+                    ),
+                },
+            });
+        }
+    }
+}
+
+/**
+ * @description
+ * Adds custom fields to a single fragment document. This is a more granular version of `addCustomFields()`
+ * that operates on individual fragments, allowing for better composability.
+ *
+ * **Important behavior with fragment dependencies:**
+ * - When a document contains multiple fragments (e.g., a main fragment with dependencies passed to `graphql()`),
+ *   only the **first fragment** is modified with custom fields.
+ * - Any additional fragments (dependencies) are left untouched in the output document.
+ * - This allows you to selectively control which fragments get custom fields.
+ *
+ * This function is memoized to return a stable identity for given inputs.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const modifiedFragment = addCustomFieldsToFragment(orderDetailFragment, {
+ *     includeCustomFields: ['reviewCount', 'priority']
+ * });
+ *
+ * // With fragment dependencies (only OrderDetail gets custom fields, OrderLine doesn't)
+ * const orderDetailFragment = graphql(
+ *     `fragment OrderDetail on Order {
+ *         id
+ *         lines { ...OrderLine }
+ *     }`,
+ *     [orderLineFragment]  // This dependency won't get custom fields
+ * );
+ * const modified = addCustomFieldsToFragment(orderDetailFragment);
+ * ```
+ */
+export function addCustomFieldsToFragment<T, V extends Variables = Variables>(
+    fragmentDocument: DocumentNode | TypedDocumentNode<T, V>,
+    options?: {
+        customFieldsMap?: Map<string, CustomFieldConfig[]>;
+        includeCustomFields?: string[];
+    },
+): TypedDocumentNode<T, V> {
+    const optionsKey = createOptionsKey(options);
+
+    // Check if we have a cached result for this fragment and options
+    let documentCache = fragmentMemoizationCache.get(fragmentDocument);
+    if (!documentCache) {
+        documentCache = new Map();
+        fragmentMemoizationCache.set(fragmentDocument, documentCache);
+    }
+
+    const cachedResult = documentCache.get(optionsKey);
+    if (cachedResult) {
+        return cachedResult as TypedDocumentNode<T, V>;
+    }
+
+    // Validate that this is a fragment-only document
+    const fragmentDefs = fragmentDocument.definitions.filter(isFragmentDefinition);
+    const queryDefs = fragmentDocument.definitions.filter(isOperationDefinition);
+
+    if (queryDefs.length > 0) {
+        throw new Error(
+            'addCustomFieldsToFragment() expects a fragment-only document. Use addCustomFields() for documents with queries.',
+        );
+    }
+
+    if (fragmentDefs.length === 0) {
+        throw new Error(
+            'addCustomFieldsToFragment() expects a document with at least one fragment definition.',
+        );
+    }
+
+    // Clone the document
+    const clone = JSON.parse(JSON.stringify(fragmentDocument)) as DocumentNode;
+    const customFields = options?.customFieldsMap || globalCustomFieldsMap;
+
+    // Only modify the first fragment (the main one)
+    // Any additional fragments are dependencies and should be left untouched
+    const fragmentDef = clone.definitions.find(isFragmentDefinition) as FragmentDefinitionNode;
+
+    // Apply custom fields only to the first/main fragment
+    applyCustomFieldsToSelection(
+        fragmentDef.typeCondition.name.value,
+        fragmentDef.selectionSet,
+        customFields,
+        options,
+    );
+
+    // Cache the result before returning
+    documentCache.set(optionsKey, clone);
+    return clone;
+}
+
 /**
  * Given a GraphQL AST (DocumentNode), this function looks for fragment definitions and adds and configured
  * custom fields to those fragments.
  *
+ * By default, only adds custom fields to top-level fragments (those used directly in the query result).
+ * Use `includeNestedFragments` to also add custom fields to specific nested fragments.
+ *
  * This function is memoized to return a stable identity for given inputs.
  */
 export function addCustomFields<T, V extends Variables = Variables>(
@@ -93,6 +321,18 @@ export function addCustomFields<T, V extends Variables = Variables>(
     options?: {
         customFieldsMap?: Map<string, CustomFieldConfig[]>;
         includeCustomFields?: string[];
+        /**
+         * Names of nested fragments that should also get custom fields.
+         * By default, only top-level fragments get custom fields.
+         *
+         * @example
+         * ```typescript
+         * addCustomFields(orderDetailDocument, {
+         *     includeNestedFragments: ['OrderLine', 'Asset']
+         * })
+         * ```
+         */
+        includeNestedFragments?: string[];
     },
 ): TypedDocumentNode<T, V> {
     const optionsKey = createOptionsKey(options);
@@ -168,9 +408,13 @@ export function addCustomFields<T, V extends Variables = Variables>(
 
     for (const fragmentDef of fragmentDefs) {
         if (hasQueries) {
-            // If we have queries, only add custom fields to fragments used at the top level
-            // Skip fragments that are only used in nested contexts
-            if (topLevelFragments.has(fragmentDef.name.value)) {
+            // If we have queries, add custom fields to:
+            // 1. Fragments used at the top level (in the main query result)
+            // 2. Fragments explicitly listed in includeNestedFragments option
+            const isTopLevel = topLevelFragments.has(fragmentDef.name.value);
+            const isExplicitlyIncluded = options?.includeNestedFragments?.includes(fragmentDef.name.value);
+
+            if (isTopLevel || isExplicitlyIncluded) {
                 targetNodes.push({
                     typeName: fragmentDef.typeCondition.name.value,
                     selectionSet: fragmentDef.selectionSet,
@@ -187,122 +431,7 @@ export function addCustomFields<T, V extends Variables = Variables>(
     }
 
     for (const target of targetNodes) {
-        let entityType = target.typeName;
-
-        if (entityType === ('OrderAddress' as any)) {
-            // OrderAddress is a special case of the Address entity, and shares its custom fields
-            // so we treat it as an alias
-            entityType = 'Address';
-        }
-
-        if (entityType === ('Country' as any)) {
-            // Country is an alias of Region
-            entityType = 'Region';
-        }
-
-        const customFieldsForType = customFields.get(entityType);
-        if (customFieldsForType && customFieldsForType.length) {
-            // Check if there is already a customFields field in the fragment
-            // to avoid duplication
-            const existingCustomFieldsField = target.selectionSet.selections.find(
-                selection => isFieldNode(selection) && selection.name.value === 'customFields',
-            ) as FieldNode | undefined;
-            const selectionNodes: SelectionNode[] = customFieldsForType
-                .filter(
-                    field =>
-                        !options?.includeCustomFields || options?.includeCustomFields.includes(field.name),
-                )
-                .map(
-                    customField =>
-                        ({
-                            kind: Kind.FIELD,
-                            name: {
-                                kind: Kind.NAME,
-                                value: customField.name,
-                            },
-                            // For "relation" custom fields, we need to also select
-                            // all the scalar fields of the related type
-                            ...(customField.type === 'relation'
-                                ? {
-                                      selectionSet: {
-                                          kind: Kind.SELECTION_SET,
-                                          selections: (
-                                              customField as RelationCustomFieldFragment
-                                          ).scalarFields.map(f => ({
-                                              kind: Kind.FIELD,
-                                              name: { kind: Kind.NAME, value: f },
-                                          })),
-                                      },
-                                  }
-                                : {}),
-                            ...(customField.type === 'struct'
-                                ? {
-                                      selectionSet: {
-                                          kind: Kind.SELECTION_SET,
-                                          selections: (customField as StructCustomFieldFragment).fields.map(
-                                              f => ({
-                                                  kind: Kind.FIELD,
-                                                  name: { kind: Kind.NAME, value: f.name },
-                                              }),
-                                          ),
-                                      },
-                                  }
-                                : {}),
-                        }) as FieldNode,
-                );
-            if (!existingCustomFieldsField) {
-                // If no customFields field exists, add one
-                (target.selectionSet.selections as SelectionNode[]).push({
-                    kind: Kind.FIELD,
-                    name: {
-                        kind: Kind.NAME,
-                        value: 'customFields',
-                    },
-                    selectionSet: {
-                        kind: Kind.SELECTION_SET,
-                        selections: selectionNodes,
-                    },
-                });
-            } else {
-                // If a customFields field already exists, add the custom fields
-                // to the existing selection set
-                (existingCustomFieldsField.selectionSet as any) = {
-                    kind: Kind.SELECTION_SET,
-                    selections: selectionNodes,
-                };
-            }
-
-            const localizedFields = customFieldsForType.filter(
-                field => field.type === 'localeString' || field.type === 'localeText',
-            );
-
-            const translationsField = target.selectionSet.selections
-                .filter(isFieldNode)
-                .find(field => field.name.value === 'translations');
-
-            if (localizedFields.length && translationsField && translationsField.selectionSet) {
-                (translationsField.selectionSet.selections as SelectionNode[]).push({
-                    name: {
-                        kind: Kind.NAME,
-                        value: 'customFields',
-                    },
-                    kind: Kind.FIELD,
-                    selectionSet: {
-                        kind: Kind.SELECTION_SET,
-                        selections: localizedFields.map(
-                            customField =>
-                                ({
-                                    kind: Kind.FIELD,
-                                    name: {
-                                        kind: Kind.NAME,
-                                        value: customField.name,
-                                    },
-                                }) as FieldNode,
-                        ),
-                    },
-                });
-            }
-        }
+        applyCustomFieldsToSelection(target.typeName, target.selectionSet, customFields, options);
     }
 
     // Cache the result before returning

package/src/lib/framework/extension-api/types/layout.ts

@@ -79,7 +79,7 @@ export type PageBlockPosition = { blockId: string; order: 'before' | 'after' | '
 export type PageBlockLocation = {
     pageId: string;
     position: PageBlockPosition;
-    column: 'main' | 'side';
+    column: 'main' | 'side' | 'full';
 };
 
 /**

package/src/lib/framework/history-entry/history-entry.tsx

@@ -34,7 +34,7 @@ export interface HistoryEntryProps {
      *
      * ```ts
      * const success = 'bg-success text-success-foreground';
-     * const destructive = 'bg-danger text-danger-foreground';
+     * const destructive = 'bg-destructive text-destructive-foreground';
      * ```
      */
     timelineIconClassName?: string;

package/src/lib/framework/layout-engine/page-layout.spec.tsx

@@ -0,0 +1,138 @@
+import React from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { PageBlock, PageLayout } from './page-layout.js';
+import { registerDashboardPageBlock } from './layout-extensions.js';
+import { PageContext } from './page-provider.js';
+import { globalRegistry } from '../registry/global-registry.js';
+import { UserSettingsContext, type UserSettingsContextType } from '../../providers/user-settings.js';
+
+const useMediaQueryMock = vi.hoisted(() => vi.fn());
+const useCopyToClipboardMock = vi.hoisted(() => vi.fn(() => [null, vi.fn()]));
+
+vi.mock('@uidotdev/usehooks', () => ({
+    useMediaQuery: useMediaQueryMock,
+    useCopyToClipboard: useCopyToClipboardMock,
+}));
+
+function registerBlock(
+    id: string,
+    order: 'before' | 'after' | 'replace',
+    pageId = 'customer-list',
+): void {
+    registerDashboardPageBlock({
+        id,
+        title: id,
+        location: {
+            pageId,
+            column: 'main',
+            position: { blockId: 'list-table', order },
+        },
+        component: ({ context }) => <div data-testid={`page-block-${id}`}>{context.pageId}</div>,
+});
+}
+
+function renderPageLayout(children: React.ReactNode, { isDesktop = true } = {}) {
+    useMediaQueryMock.mockReturnValue(isDesktop);
+    const noop = () => undefined;
+    const contextValue = {
+        settings: {
+            displayLanguage: 'en',
+            contentLanguage: 'en',
+            theme: 'system',
+            displayUiExtensionPoints: false,
+            mainNavExpanded: true,
+            activeChannelId: '',
+            devMode: false,
+            hasSeenOnboarding: false,
+            tableSettings: {},
+        },
+        settingsStoreIsAvailable: true,
+        setDisplayLanguage: noop,
+        setDisplayLocale: noop,
+        setContentLanguage: noop,
+        setTheme: noop,
+        setDisplayUiExtensionPoints: noop,
+        setMainNavExpanded: noop,
+        setActiveChannelId: noop,
+        setDevMode: noop,
+        setHasSeenOnboarding: noop,
+        setTableSettings: () => undefined,
+        setWidgetLayout: noop,
+    } as UserSettingsContextType;
+
+    return renderToStaticMarkup(
+        <UserSettingsContext.Provider value={contextValue}>
+            <PageContext.Provider value={{ pageId: 'customer-list' }}>
+                <PageLayout>{children}</PageLayout>
+            </PageContext.Provider>
+        </UserSettingsContext.Provider>,
+    );
+}
+
+function getRenderedBlockIds(markup: string) {
+    return Array.from(markup.matchAll(/data-testid="(page-block-[^"]+)"/g)).map(match => match[1]);
+}
+
+describe('PageLayout', () => {
+    beforeEach(() => {
+        useMediaQueryMock.mockReset();
+        useCopyToClipboardMock.mockReset();
+        useCopyToClipboardMock.mockReturnValue([null, vi.fn()]);
+        const pageBlockRegistry = globalRegistry.get('dashboardPageBlockRegistry');
+        pageBlockRegistry.clear();
+    });
+
+    it('renders multiple before/after extension blocks in registration order', () => {
+        registerBlock('before-1', 'before');
+        registerBlock('before-2', 'before');
+        registerBlock('after-1', 'after');
+
+        const markup = renderPageLayout(
+            <PageBlock column="main" blockId="list-table">
+        <div data-testid="page-block-original">original</div>
+            </PageBlock>,
+        { isDesktop: true },
+    );
+
+        expect(getRenderedBlockIds(markup)).toEqual([
+            'page-block-before-1',
+            'page-block-before-2',
+            'page-block-original',
+            'page-block-after-1',
+        ]);
+    });
+
+    it('replaces original block when replacement extensions are registered', () => {
+        registerBlock('replacement-1', 'replace');
+        registerBlock('replacement-2', 'replace');
+
+        const markup = renderPageLayout(
+            <PageBlock column="main" blockId="list-table">
+        <div data-testid="page-block-original">original</div>
+            </PageBlock>,
+        { isDesktop: true },
+    );
+
+        expect(getRenderedBlockIds(markup)).toEqual(['page-block-replacement-1', 'page-block-replacement-2']);
+    });
+
+    it('renders extension blocks in mobile layout', () => {
+        registerBlock('before-mobile', 'before');
+        registerBlock('after-mobile', 'after');
+
+        const markup = renderPageLayout(
+            <PageBlock column="main" blockId="list-table">
+        <div data-testid="page-block-original">original</div>
+            </PageBlock>,
+        { isDesktop: false },
+    );
+
+        expect(getRenderedBlockIds(markup)).toEqual([
+            'page-block-before-mobile',
+            'page-block-original',
+            'page-block-after-mobile',
+        ]);
+    });
+});

package/src/lib/framework/layout-engine/page-layout.tsx

@@ -234,34 +234,63 @@ export function PageLayout({ children, className }: Readonly<PageLayoutProps>) {
             const blockId =
                 childBlock.props.blockId ??
                 (isOfType(childBlock, CustomFieldsPageBlock) ? 'custom-fields' : undefined);
-            const extensionBlock = extensionBlocks.find(block => block.location.position.blockId === blockId);
 
-            if (extensionBlock) {
-                let extensionBlockShouldRender = true;
-                if (typeof extensionBlock?.shouldRender === 'function') {
-                    extensionBlockShouldRender = extensionBlock.shouldRender(page);
+            // Get all extension blocks with the same position blockId
+            const matchingExtensionBlocks = extensionBlocks.filter(
+                block => block.location.position.blockId === blockId,
+            );
+
+            // sort the blocks to make sure we have the correct order
+            const arrangedExtensionBlocks = matchingExtensionBlocks.sort((a, b) => {
+                const orderPriority = { before: 1, replace: 2, after: 3 };
+                return orderPriority[a.location.position.order] - orderPriority[b.location.position.order];
+            });
+
+            const replacementBlockExists = arrangedExtensionBlocks.some(
+                block => block.location.position.order === 'replace',
+            );
+
+            let childBlockInserted = false;
+            if (matchingExtensionBlocks.length > 0) {
+                for (const extensionBlock of arrangedExtensionBlocks) {
+                    let extensionBlockShouldRender = true;
+                    if (typeof extensionBlock?.shouldRender === 'function') {
+                        extensionBlockShouldRender = extensionBlock.shouldRender(page);
+                    }
+
+                    // Insert child block before the first non-"before" block
+                    if (
+                        !childBlockInserted &&
+                        !replacementBlockExists &&
+                        extensionBlock.location.position.order !== 'before'
+                    ) {
+                        finalChildArray.push(childBlock);
+                        childBlockInserted = true;
+                    }
+
+                    const isFullWidth = extensionBlock.location.column === 'full';
+                    const BlockComponent = isFullWidth ? FullWidthPageBlock : PageBlock;
+
+                    const ExtensionBlock =
+                        extensionBlock.component && extensionBlockShouldRender ? (
+                            <BlockComponent
+                                key={extensionBlock.id}
+                                column={extensionBlock.location.column}
+                                blockId={extensionBlock.id}
+                                title={extensionBlock.title}
+                            >
+                                {<extensionBlock.component context={page} />}
+                            </BlockComponent>
+                        ) : undefined;
+
+                    if (extensionBlockShouldRender && ExtensionBlock) {
+                        finalChildArray.push(ExtensionBlock);
+                    }
                 }
-                const ExtensionBlock =
-                    extensionBlock.component && extensionBlockShouldRender ? (
-                        <PageBlock
-                            key={childBlock.key}
-                            column={extensionBlock.location.column}
-                            blockId={extensionBlock.id}
-                            title={extensionBlock.title}
-                        >
-                            {<extensionBlock.component context={page} />}
-                        </PageBlock>
-                    ) : undefined;
-                if (extensionBlock.location.position.order === 'before') {
-                    finalChildArray.push(...[ExtensionBlock, childBlock].filter(x => !!x));
-                } else if (extensionBlock.location.position.order === 'after') {
-                    finalChildArray.push(...[childBlock, ExtensionBlock].filter(x => !!x));
-                } else if (
-                    extensionBlock.location.position.order === 'replace' &&
-                    extensionBlockShouldRender &&
-                    ExtensionBlock
-                ) {
-                    finalChildArray.push(ExtensionBlock);
+
+                // If all blocks were "before", insert child block at the end
+                if (!childBlockInserted && !replacementBlockExists) {
+                    finalChildArray.push(childBlock);
                 }
             } else {
                 finalChildArray.push(childBlock);
@@ -286,7 +315,7 @@ export function PageLayout({ children, className }: Readonly<PageLayoutProps>) {
                     <div className="@3xl/layout:col-span-1 space-y-4">{sideBlocks}</div>
                 </div>
             ) : (
-                <div className="space-y-4">{children}</div>
+                <div className="space-y-4">{finalChildArray}</div>
             )}
         </div>
     );