@vendure/dashboard 3.3.6-master-202507010243 → 3.3.6-master-202507010922

package/src/lib/framework/document-extension/extend-detail-form-query.ts

@@ -0,0 +1,50 @@
+import { extendDocument } from '@/framework/document-extension/extend-document.js';
+import { getDetailQueryDocuments } from '@/framework/form-engine/custom-form-component-extensions.js';
+import { DocumentNode } from 'graphql';
+
+/**
+ * @description
+ * Extends a detail page query document with any registered extensions provided by
+ * the `extendDetailDocument` function for the given page.
+ */
+export function extendDetailFormQuery<T extends DocumentNode>(
+    detailQuery: T,
+    pageId?: string,
+): {
+    extendedQuery: T;
+    errorMessage?: string | null;
+} {
+    let result: T = detailQuery;
+    let errorMessage: string | null = null;
+
+    if (!pageId) {
+        // If no pageId is provided, return the original query without any extensions
+        return { extendedQuery: detailQuery };
+    }
+
+    const detailQueryExtensions = getDetailQueryDocuments(pageId);
+
+    try {
+        result = detailQueryExtensions.reduce(
+            (acc, extension) => extendDocument(acc, extension),
+            detailQuery,
+        ) as T;
+    } catch (err) {
+        errorMessage = err instanceof Error ? err.message : String(err);
+        // Continue with the original query instead of the extended one
+        result = detailQuery;
+    }
+
+    // Store error for useEffect to handle
+    if (errorMessage) {
+        // Log the error and continue with the original query
+        // eslint-disable-next-line no-console
+        console.warn(`${errorMessage}. Continuing with original query.`, {
+            pageId,
+            extensionsCount: detailQueryExtensions.length,
+            error: errorMessage,
+        });
+    }
+
+    return { extendedQuery: result, errorMessage };
+}

package/src/lib/framework/document-extension/extend-document.spec.ts

@@ -546,4 +546,339 @@ describe('extendDocument', () => {
             `),
         );
     });
+
+    it('should extend detail query with fragments', () => {
+        const detailDocument = graphql(`
+            fragment ProductDetail on Product {
+                id
+                name
+                slug
+                description
+                featuredAsset {
+                    id
+                    preview
+                }
+            }
+
+            query ProductDetail($id: ID!) {
+                product(id: $id) {
+                    ...ProductDetail
+                }
+            }
+        `);
+
+        const extended = extendDocument(
+            detailDocument as any,
+            `
+            fragment ProductDetail on Product {
+                enabled
+                createdAt
+                updatedAt
+                assets {
+                    id
+                    preview
+                }
+            }
+
+            query ProductDetail($id: ID!) {
+                product(id: $id) {
+                    customFields
+                }
+            }
+            `,
+        );
+
+        const printed = print(extended);
+
+        expect(expectedSDL(printed)).toBe(
+            expectedSDL(`
+                query ProductDetail($id: ID!) {
+                    product(id: $id) {
+                        ...ProductDetail
+                        customFields
+                    }
+                }
+                fragment ProductDetail on Product {
+                    id
+                    name
+                    slug
+                    description
+                    featuredAsset {
+                        id
+                        preview
+                    }
+                }
+                fragment ProductDetail on Product {
+                    enabled
+                    createdAt
+                    updatedAt
+                    assets {
+                        id
+                        preview
+                    }
+                }
+            `),
+        );
+    });
+
+    it('should extend detail query with nested translations', () => {
+        const detailDocument = graphql(`
+            query ProductDetail($id: ID!) {
+                product(id: $id) {
+                    id
+                    name
+                    slug
+                    translations {
+                        id
+                        languageCode
+                        name
+                    }
+                }
+            }
+        `);
+
+        const extended = extendDocument(
+            detailDocument as any,
+            `
+            query ProductDetail($id: ID!) {
+                product(id: $id) {
+                    translations {
+                        slug
+                        description
+                    }
+                    facetValues {
+                        id
+                        name
+                        code
+                        facet {
+                            id
+                            name
+                            code
+                        }
+                    }
+                }
+            }
+            `,
+        );
+
+        const printed = print(extended);
+
+        expect(expectedSDL(printed)).toBe(
+            expectedSDL(`
+                query ProductDetail($id: ID!) {
+                    product(id: $id) {
+                        id
+                        name
+                        slug
+                        translations {
+                            id
+                            languageCode
+                            name
+                            slug
+                            description
+                        }
+                        facetValues {
+                            id
+                            name
+                            code
+                            facet {
+                                id
+                                name
+                                code
+                            }
+                        }
+                    }
+                }
+            `),
+        );
+    });
+
+    it('should extend detail query with asset fragments', () => {
+        const detailDocument = graphql(`
+            fragment Asset on Asset {
+                id
+                preview
+            }
+
+            query ProductDetail($id: ID!) {
+                product(id: $id) {
+                    id
+                    featuredAsset {
+                        ...Asset
+                    }
+                }
+            }
+        `);
+
+        const extended = extendDocument(
+            detailDocument as any,
+            `
+            fragment Asset on Asset {
+                name
+                source
+            }
+
+            query ProductDetail($id: ID!) {
+                product(id: $id) {
+                    assets {
+                        ...Asset
+                    }
+                }
+            }
+            `,
+        );
+
+        const printed = print(extended);
+
+        expect(expectedSDL(printed)).toBe(
+            expectedSDL(`
+                query ProductDetail($id: ID!) {
+                    product(id: $id) {
+                        id
+                        featuredAsset {
+                            ...Asset
+                        }
+                        assets {
+                            ...Asset
+                        }
+                    }
+                }
+                fragment Asset on Asset {
+                    id
+                    preview
+                }
+                fragment Asset on Asset {
+                    name
+                    source
+                }
+            `),
+        );
+    });
+
+    it('should extend detail query with custom fields', () => {
+        const detailDocument = graphql(`
+            query ProductDetail($id: ID!) {
+                product(id: $id) {
+                    id
+                    name
+                    customFields
+                }
+            }
+        `);
+
+        const extended = extendDocument(
+            detailDocument as any,
+            `
+            query ProductDetail($id: ID!) {
+                product(id: $id) {
+                    enabled
+                    createdAt
+                    updatedAt
+                    customFields
+                }
+            }
+            `,
+        );
+
+        const printed = print(extended);
+
+        expect(expectedSDL(printed)).toBe(
+            expectedSDL(`
+                query ProductDetail($id: ID!) {
+                    product(id: $id) {
+                        id
+                        name
+                        customFields
+                        enabled
+                        createdAt
+                        updatedAt
+                    }
+                }
+            `),
+        );
+    });
+
+    it('should extend detail query with complex nested structure', () => {
+        const detailDocument = graphql(`
+            query ProductDetail($id: ID!) {
+                product(id: $id) {
+                    id
+                    name
+                    featuredAsset {
+                        id
+                        preview
+                    }
+                    facetValues {
+                        id
+                        name
+                    }
+                }
+            }
+        `);
+
+        const extended = extendDocument(
+            detailDocument as any,
+            `
+            query ProductDetail($id: ID!) {
+                product(id: $id) {
+                    featuredAsset {
+                        name
+                        source
+                    }
+                    facetValues {
+                        code
+                        facet {
+                            id
+                            name
+                            code
+                        }
+                    }
+                    translations {
+                        id
+                        languageCode
+                        name
+                        slug
+                        description
+                    }
+                }
+            }
+            `,
+        );
+
+        const printed = print(extended);
+
+        expect(expectedSDL(printed)).toBe(
+            expectedSDL(`
+                query ProductDetail($id: ID!) {
+                    product(id: $id) {
+                        id
+                        name
+                        featuredAsset {
+                            id
+                            preview
+                            name
+                            source
+                        }
+                        facetValues {
+                            id
+                            name
+                            code
+                            facet {
+                                id
+                                name
+                                code
+                            }
+                        }
+                        translations {
+                            id
+                            languageCode
+                            name
+                            slug
+                            description
+                        }
+                    }
+                }
+            `),
+        );
+    });
 });

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

@@ -25,6 +25,35 @@ type RelationCustomFieldFragment = ResultOf<typeof relationCustomFieldFragment>;
 
 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>>>();
+
+/**
+ * Creates a cache key for the options object
+ */
+function createOptionsKey(options?: {
+    customFieldsMap?: Map<string, CustomFieldConfig[]>;
+    includeCustomFields?: string[];
+}): string {
+    if (!options) return 'default';
+
+    const parts: string[] = [];
+
+    if (options.customFieldsMap) {
+        // Create a deterministic key for the customFieldsMap
+        const mapEntries = Array.from(options.customFieldsMap.entries())
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([key, value]) => `${key}:${value.length}`);
+        parts.push(`map:${mapEntries.join(',')}`);
+    }
+
+    if (options.includeCustomFields) {
+        parts.push(`include:${options.includeCustomFields.sort().join(',')}`);
+    }
+
+    return parts.join('|') || 'default';
+}
+
 /**
  * @description
  * This function is used to set the global custom fields map.
@@ -56,6 +85,8 @@ export function getCustomFieldsMap() {
 /**
  * Given a GraphQL AST (DocumentNode), this function looks for fragment definitions and adds and configured
  * custom fields to those fragments.
+ *
+ * This function is memoized to return a stable identity for given inputs.
  */
 export function addCustomFields<T, V extends Variables = Variables>(
     documentNode: DocumentNode | TypedDocumentNode<T, V>,
@@ -64,6 +95,21 @@ export function addCustomFields<T, V extends Variables = Variables>(
         includeCustomFields?: string[];
     },
 ): TypedDocumentNode<T, V> {
+    const optionsKey = createOptionsKey(options);
+
+    // Check if we have a cached result for this document and options
+    let documentCache = memoizationCache.get(documentNode);
+    if (!documentCache) {
+        documentCache = new Map();
+        memoizationCache.set(documentNode, documentCache);
+    }
+
+    const cachedResult = documentCache.get(optionsKey);
+    if (cachedResult) {
+        return cachedResult as TypedDocumentNode<T, V>;
+    }
+
+    // If not cached, compute the result
     const clone = JSON.parse(JSON.stringify(documentNode)) as DocumentNode;
     const customFields = options?.customFieldsMap || globalCustomFieldsMap;
 
@@ -209,6 +255,8 @@ export function addCustomFields<T, V extends Variables = Variables>(
         }
     }
 
+    // Cache the result before returning
+    documentCache.set(optionsKey, clone);
     return clone;
 }
 

package/src/lib/framework/extension-api/define-dashboard-extension.ts

@@ -2,7 +2,10 @@ import { addBulkAction, addListQueryDocument } from '@/framework/data-table/data
 import { parse } from 'graphql';
 
 import { registerDashboardWidget } from '../dashboard-widget/widget-extensions.js';
-import { addCustomFormComponent } from '../form-engine/custom-form-component-extensions.js';
+import {
+    addCustomFormComponent,
+    addDetailQueryDocument,
+} from '../form-engine/custom-form-component-extensions.js';
 import {
     registerDashboardActionBarItem,
     registerDashboardPageBlock,
@@ -106,6 +109,21 @@ export function defineDashboardExtension(extension: DashboardExtension) {
                 }
             }
         }
+        if (extension.detailForms) {
+            for (const detailForm of extension.detailForms) {
+                if (detailForm.extendDetailDocument) {
+                    const document =
+                        typeof detailForm.extendDetailDocument === 'function'
+                            ? detailForm.extendDetailDocument()
+                            : detailForm.extendDetailDocument;
+
+                    addDetailQueryDocument(
+                        detailForm.pageId,
+                        typeof document === 'string' ? parse(document) : document,
+                    );
+                }
+            }
+        }
         const callbacks = globalRegistry.get('extensionSourceChangeCallbacks');
         if (callbacks.size) {
             for (const callback of callbacks) {

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

@@ -120,7 +120,7 @@ export interface DashboardPageBlockDefinition {
  * @docsCategory extensions
  * @since 3.4.0
  */
-export interface DashboardDataTableDefinition {
+export interface DashboardDataTableExtensionDefinition {
     /**
      * @description
      * The ID of the page where the data table is located, e.g. `'product-list'`, `'order-list'`.
@@ -145,6 +145,18 @@ export interface DashboardDataTableDefinition {
     extendListDocument?: string | DocumentNode | (() => DocumentNode | string);
 }
 
+export interface DashboardDetailFormExtensionDefinition {
+    /**
+     * @description
+     * The ID of the page where the detail form is located, e.g. `'product-detail'`, `'order-detail'`.
+     */
+    pageId: string;
+    /**
+     * @description
+     */
+    extendDetailDocument?: string | DocumentNode | (() => DocumentNode | string);
+}
+
 /**
  * @description
  * **Status: Developer Preview**
@@ -195,5 +207,6 @@ export interface DashboardExtension {
      * @description
      * Allows you to customize aspects of existing data tables in the dashboard.
      */
-    dataTables?: DashboardDataTableDefinition[];
+    dataTables?: DashboardDataTableExtensionDefinition[];
+    detailForms?: DashboardDetailFormExtensionDefinition[];
 }

package/src/lib/framework/form-engine/custom-form-component-extensions.ts

@@ -1,3 +1,5 @@
+import { DocumentNode } from 'graphql';
+
 import { DashboardCustomFormComponent } from '../extension-api/extension-api-types.js';
 import { globalRegistry } from '../registry/global-registry.js';
 
@@ -8,9 +10,7 @@ globalRegistry.register(
     new Map<string, React.FunctionComponent<CustomFormComponentInputProps>>(),
 );
 
-export function getCustomFormComponents() {
-    return globalRegistry.get('customFormComponents');
-}
+globalRegistry.register('detailQueryDocumentRegistry', new Map<string, DocumentNode[]>());
 
 export function getCustomFormComponent(
     id: string,
@@ -26,3 +26,13 @@ export function addCustomFormComponent({ id, component }: DashboardCustomFormCom
     }
     customFormComponents.set(id, component);
 }
+
+export function getDetailQueryDocuments(pageId: string): DocumentNode[] {
+    return globalRegistry.get('detailQueryDocumentRegistry').get(pageId) || [];
+}
+
+export function addDetailQueryDocument(pageId: string, document: DocumentNode) {
+    const listQueryDocumentRegistry = globalRegistry.get('detailQueryDocumentRegistry');
+    const existingDocuments = listQueryDocumentRegistry.get(pageId) || [];
+    listQueryDocumentRegistry.set(pageId, [...existingDocuments, document]);
+}

package/src/lib/framework/form-engine/utils.ts

@@ -1,24 +1,52 @@
 import { FieldInfo } from '../document-introspection/get-document-structure.js';
 
-export function transformRelationFields<E extends Record<string, any>>(fields: FieldInfo[], entity: E) {
-    const processedEntity = { ...entity } as any;
+/**
+ * Transforms relation fields in an entity, extracting IDs from relation objects.
+ * This is primarily used for custom fields of type "ID".
+ *
+ * @param fields - Array of field information
+ * @param entity - The entity to transform
+ * @returns A new entity with transformed relation fields
+ */
+export function transformRelationFields<E extends Record<string, any>>(fields: FieldInfo[], entity: E): E {
+    // Create a shallow copy to avoid mutating the original entity
+    const processedEntity = { ...entity };
 
-    for (const field of fields) {
-        if (field.name !== 'customFields' || !field.typeInfo) {
-            continue;
-        }
+    // Skip processing if there are no custom fields
+    if (!entity.customFields || !processedEntity.customFields) {
+        return processedEntity;
+    }
 
-        if (!entity.customFields || !processedEntity.customFields) {
-            continue;
-        }
+    // Find the customFields field info
+    const customFieldsInfo = fields.find(field => field.name === 'customFields' && field.typeInfo);
+    if (!customFieldsInfo?.typeInfo) {
+        return processedEntity;
+    }
+
+    // Process only ID type custom fields
+    const idTypeCustomFields = customFieldsInfo.typeInfo.filter(field => field.type === 'ID');
 
-        for (const customField of field.typeInfo) {
-            if (customField.type === 'ID') {
-                const relationField = customField.name;
-                const propertyAccessorKey = customField.name.replace(/Id$/, '');
-                const relationValue = entity.customFields[propertyAccessorKey];
-                const relationIdValue = relationValue?.id;
+    for (const customField of idTypeCustomFields) {
+        const relationField = customField.name;
+
+        if (customField.list) {
+            // For list fields, the accessor is the field name without the "Ids" suffix
+            const propertyAccessorKey = customField.name.replace(/Ids$/, '');
+            const relationValue = entity.customFields[propertyAccessorKey];
+
+            if (relationValue) {
+                const relationIdValue = relationValue.map((v: { id: string }) => v.id);
+                if (relationIdValue && relationIdValue.length > 0) {
+                    processedEntity.customFields[relationField] = relationIdValue;
+                }
+            }
+        } else {
+            // For single fields, the accessor is the field name without the "Id" suffix
+            const propertyAccessorKey = customField.name.replace(/Id$/, '');
+            const relationValue = entity.customFields[propertyAccessorKey];
 
+            if (relationValue) {
+                const relationIdValue = relationValue.id;
                 if (relationIdValue) {
                     processedEntity.customFields[relationField] = relationIdValue;
                 }

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

@@ -194,6 +194,7 @@ export function PageLayout({ children, className }: PageLayoutProps) {
             if (extensionBlock) {
                 const ExtensionBlock = (
                     <PageBlock
+                        key={childBlock.key}
                         column={extensionBlock.location.column}
                         blockId={extensionBlock.id}
                         title={extensionBlock.title}

package/src/lib/framework/page/detail-page-route-loader.tsx

@@ -1,6 +1,7 @@
 import { NEW_ENTITY_PATH } from '@/constants.js';
 
 import { PageBreadcrumb } from '@/components/layout/generated-breadcrumbs.js';
+import { extendDetailFormQuery } from '@/framework/document-extension/extend-detail-form-query.js';
 import { TypedDocumentNode } from '@graphql-typed-document-node/core';
 import { FileBaseRouteOptions, ParsedLocation } from '@tanstack/react-router';
 import { addCustomFields } from '../document-introspection/add-custom-fields.js';
@@ -9,6 +10,12 @@ import { DetailEntity } from './page-types.js';
 import { getDetailQueryOptions } from './use-detail-page.js';
 
 export interface DetailPageRouteLoaderConfig<T extends TypedDocumentNode<any, any>> {
+    /**
+     * @description
+     * The pageId is used to ensure any detail form extensions (such as extensions to
+     * the detail query document) get correctly applied at the route loader level.
+     */
+    pageId?: string;
     queryDocument: T;
     breadcrumb: (
         isNew: boolean,
@@ -18,6 +25,7 @@ export interface DetailPageRouteLoaderConfig<T extends TypedDocumentNode<any, an
 }
 
 export function detailPageRouteLoader<T extends TypedDocumentNode<any, any>>({
+    pageId,
     queryDocument,
     breadcrumb,
 }: DetailPageRouteLoaderConfig<T>) {
@@ -34,10 +42,14 @@ export function detailPageRouteLoader<T extends TypedDocumentNode<any, any>>({
             throw new Error('ID param is required');
         }
         const isNew = params.id === NEW_ENTITY_PATH;
+        const { extendedQuery: extendedQueryDocument } = extendDetailFormQuery(
+            addCustomFields(queryDocument),
+            pageId,
+        );
         const result = isNew
             ? null
             : await context.queryClient.ensureQueryData(
-                  getDetailQueryOptions(addCustomFields(queryDocument), { id: params.id }),
+                  getDetailQueryOptions(extendedQueryDocument, { id: params.id }),
                   { id: params.id },
               );