@vendure/dashboard 3.6.0-minor-202511061555 → 3.6.0-minor-202512161252

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/display-component-extensions.tsx

@@ -5,6 +5,7 @@ import { Money } from '@/vdb/components/data-display/money.js';
 import { VendureImage } from '@/vdb/components/shared/vendure-image.js';
 import { DataDisplayComponent } from '../component-registry/component-registry.js';
 import { globalRegistry } from '../registry/global-registry.js';
+import { DataTableDisplayComponent } from './types/data-table.js';
 
 globalRegistry.register('displayComponents', new Map<string, DataDisplayComponent>());
 
@@ -21,7 +22,7 @@ displayComponents.set('vendure:money', Money);
 displayComponents.set('vendure:json', Json);
 
 export function getDisplayComponent(id: string): DataDisplayComponent | undefined {
-    return globalRegistry.get('displayComponents').get(id);
+    return globalRegistry.get('displayComponents').get(id) as DataDisplayComponent | undefined;
 }
 
 /**
@@ -42,10 +43,10 @@ export function addDisplayComponent({
     pageId: string;
     blockId: string;
     field: string;
-    component: React.ComponentType<{ value: any; [key: string]: any }>;
+    component: DataDisplayComponent | DataTableDisplayComponent;
 }) {
     const displayComponents = globalRegistry.get('displayComponents');
-
+    
     // Generate the key using the helper function
     const key = generateDisplayComponentKey(pageId, blockId, field);
 

package/src/lib/framework/extension-api/logic/detail-forms.ts

@@ -1,7 +1,6 @@
 import { addDetailQueryDocument } from '@/vdb/framework/form-engine/custom-form-component-extensions.js';
 import { parse } from 'graphql';
 
-import { addDisplayComponent } from '../display-component-extensions.js';
 import { addInputComponent } from '../input-component-extensions.js';
 import { DashboardDetailFormExtensionDefinition } from '../types/detail-forms.js';
 
@@ -31,18 +30,6 @@ export function registerDetailFormExtensions(detailForms?: DashboardDetailFormEx
                     });
                 }
             }
-
-            // Register display components for this detail form
-            if (detailForm.displays) {
-                for (const displayComponent of detailForm.displays) {
-                    addDisplayComponent({
-                        pageId: detailForm.pageId,
-                        blockId: displayComponent.blockId,
-                        field: displayComponent.field,
-                        component: displayComponent.component,
-                    });
-                }
-            }
         }
     }
 }

package/src/lib/framework/extension-api/logic/navigation.ts

@@ -10,7 +10,7 @@ export function registerNavigationExtensions(
         for (const section of navSections) {
             addNavMenuSection({
                 ...section,
-                placement: 'top',
+                placement: section.placement ?? 'top',
                 order: section.order ?? 999,
                 items: [],
             });

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

@@ -1,9 +1,11 @@
-import { DataDisplayComponentProps } from '@/vdb/framework/component-registry/component-registry.js';
+import { DataDisplayComponent } from '@/vdb/framework/component-registry/component-registry.js';
 import { Table } from '@tanstack/react-table';
 import { CellContext } from '@tanstack/table-core';
 import { DocumentNode } from 'graphql';
 import React from 'react';
 
+export type DataTableDisplayComponent = DataDisplayComponent<CellContext<any, any>>;
+
 /**
  * @description
  * Allows you to define custom display components for specific columns in data tables.
@@ -24,7 +26,7 @@ export interface DashboardDataTableDisplayComponent {
      * The React component that will be rendered as the display.
      * It should accept `value` and other standard display props.
      */
-    component: React.ComponentType<DataDisplayComponentProps<CellContext<any, any>>>;
+    component: DataTableDisplayComponent;
 }
 
 export type BulkActionContext<Item extends { id: string } & Record<string, any>> = {

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

@@ -52,8 +52,41 @@ export interface DashboardActionBarItem {
      * Any permissions that are required to display this action bar item.
      */
     requiresPermission?: string | string[];
+    /**
+     * @description
+     * A unique identifier for this action bar item. This is required if you want
+     * other extensions to be able to position their items relative to this one.
+     *
+     * @since 3.5.2
+     */
+    id?: string;
+    /**
+     * @description
+     * Position this item relative to another action bar item. The `itemId` should
+     * match the `id` of an existing action bar item (either a built-in item or one
+     * added by another extension).
+     *
+     * - `'before'`: Place this item before the target item
+     * - `'after'`: Place this item after the target item
+     * - `'replace'`: Replace the target item entirely with this item
+     *
+     * @since 3.5.2
+     */
+    position?: ActionBarItemPosition;
 }
 
+/**
+ * @description
+ * The relative position of an ActionBar item. This is determined by finding an existing
+ * action bar item by its `id`, and then specifying whether your custom item should come
+ * before, after, or completely replace that item.
+ *
+ * @docsCategory extensions-api
+ * @docsPage ActionBar
+ * @since 3.5.2
+ */
+export type ActionBarItemPosition = { itemId: string; order: 'before' | 'after' | 'replace' };
+
 /**
  * @description
  * The relative position of a PageBlock. This is determined by finding an existing
@@ -79,7 +112,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/extension-api/types/navigation.ts

@@ -39,7 +39,7 @@ export interface DashboardRouteDefinition {
      * The value is a Tanstack Router
      * [loader function](https://tanstack.com/router/latest/docs/framework/react/guide/data-loading#route-loaders)
      */
-    loader?: RouteOptions['loader'];
+    loader?: RouteOptions<any>['loader'];
 
     /**
      * @description
@@ -47,7 +47,7 @@ export interface DashboardRouteDefinition {
      * The value is a Tanstack Router
      * [validateSearch function](https://tanstack.com/router/latest/docs/framework/react/guide/search-params#search-param-validation)
      */
-    validateSearch?: RouteOptions['validateSearch'];
+    validateSearch?: RouteOptions<any>['validateSearch'];
 
     /**
      * @description
@@ -97,4 +97,9 @@ export interface DashboardNavSectionDefinition {
      * Optional order number to control the position of this section in the sidebar.
      */
     order?: number;
+    /**
+     * @description
+     * Optional placement to control the position of this section in the sidebar.
+     */
+    placement?: 'top' | 'bottom';
 }

package/src/lib/framework/form-engine/use-generated-form.tsx

@@ -9,6 +9,10 @@ import { getOperationVariablesFields } from '../document-introspection/get-docum
 import { createFormSchemaFromFields, getDefaultValuesFromFields } from './form-schema-tools.js';
 import { removeEmptyIdFields, transformRelationFields } from './utils.js';
 
+export type WithLooseCustomFields<T> = T extends { customFields?: any }
+    ? Omit<T, 'customFields'> & { customFields?: T['customFields'] | unknown }
+    : T;
+
 /**
  * @description
  * Options for the useGeneratedForm hook.
@@ -40,7 +44,9 @@ export interface GeneratedFormOptions<
     customFieldConfig?: any[]; // Add custom field config for validation
     setValues: (
         entity: NonNullable<E>,
-    ) => VarName extends keyof VariablesOf<T> ? VariablesOf<T>[VarName] : VariablesOf<T>;
+    ) => WithLooseCustomFields<
+        VarName extends keyof VariablesOf<T> ? VariablesOf<T>[VarName] : VariablesOf<T>
+    >;
     onSubmit?: (
         values: VarName extends keyof VariablesOf<T> ? VariablesOf<T>[VarName] : VariablesOf<T>,
     ) => void;

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;