@vendure/dashboard 3.4.0-minor-202506250934 → 3.4.0

package/src/lib/framework/document-introspection/get-document-structure.ts

@@ -1,5 +1,5 @@
 import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
-import { VariablesOf } from 'gql.tada';
+import { ResultOf, VariablesOf } from 'gql.tada';
 import {
     DocumentNode,
     FieldNode,
@@ -32,33 +32,165 @@ export interface FieldInfo {
  */
 export function getListQueryFields(documentNode: DocumentNode): FieldInfo[] {
     const fields: FieldInfo[] = [];
-    const fragments: Record<string, FragmentDefinitionNode> = {};
+    const fragments = collectFragments(documentNode);
+    const operationDefinition = findQueryOperation(documentNode);
+
+    for (const query of operationDefinition.selectionSet.selections) {
+        if (query.kind === 'Field') {
+            const queryField = query;
+            const fieldInfo = getQueryInfo(queryField.name.value);
+            if (fieldInfo.isPaginatedList) {
+                processPaginatedList(queryField, fieldInfo, fields, fragments);
+            } else if (queryField.selectionSet) {
+                // Check for nested paginated lists
+                findNestedPaginatedLists(queryField, fieldInfo.type, fields, fragments);
+            }
+        }
+    }
+
+    return fields;
+}
+
+// Utility type to get all valid paths into a type
+export type PathTo<T> = T extends object
+    ? {
+          [K in keyof T & (string | number)]: [K] | [K, ...PathTo<T[K]>];
+      }[keyof T & (string | number)]
+    : [];
 
-    // Collect all fragment definitions
+/**
+ * @description
+ * This function is used to get the FieldInfo for the fields in the path of a DocumentNode.
+ *
+ * For example, in the following query:
+ *
+ * ```graphql
+ * query {
+ *   product {
+ *     id
+ *     name
+ *     variants {
+ *       id
+ *       name
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * The path `['product', 'variants']` will return the FieldInfo for the `variants` field,
+ * namely the `id` and `name` fields.
+ */
+export function getFieldsFromDocumentNode<
+    T extends TypedDocumentNode<any, any>,
+    P extends PathTo<ResultOf<T>>,
+>(documentNode: T, path: P): FieldInfo[] {
+    const fragments = collectFragments(documentNode);
+    const operationDefinition = findQueryOperation(documentNode);
+
+    // Navigate to the target path
+    let currentSelections = operationDefinition.selectionSet.selections;
+    let currentType = 'Query';
+
+    for (let i = 0; i < path.length; i++) {
+        const pathSegment = path[i] as string;
+        const { fieldNode } = findFieldInSelections(
+            currentSelections,
+            pathSegment,
+            fragments,
+            path.slice(0, i + 1),
+        );
+
+        const fieldInfo = getObjectFieldInfo(currentType, pathSegment);
+        if (!fieldInfo) {
+            throw new Error(`Could not determine type for field "${pathSegment}"`);
+        }
+
+        // If this is the last path segment, collect the fields
+        if (i === path.length - 1) {
+            return collectFieldsFromNode(fieldNode, fieldInfo.type, fragments);
+        }
+
+        // Continue navigating deeper
+        if (!fieldNode.selectionSet) {
+            throw new Error(`Field "${pathSegment}" has no selection set but path continues`);
+        }
+        currentSelections = fieldNode.selectionSet.selections;
+        currentType = fieldInfo.type;
+    }
+
+    return [];
+}
+
+function collectFragments(documentNode: DocumentNode): Record<string, FragmentDefinitionNode> {
+    const fragments: Record<string, FragmentDefinitionNode> = {};
     documentNode.definitions.forEach(def => {
         if (def.kind === 'FragmentDefinition') {
             fragments[def.name.value] = def;
         }
     });
+    return fragments;
+}
 
+function findQueryOperation(documentNode: DocumentNode): OperationDefinitionNode {
     const operationDefinition = documentNode.definitions.find(
         (def): def is OperationDefinitionNode =>
             def.kind === 'OperationDefinition' && def.operation === 'query',
     );
+    if (!operationDefinition) {
+        throw new Error('Could not find query operation definition');
+    }
+    return operationDefinition;
+}
 
-    for (const query of operationDefinition?.selectionSet.selections ?? []) {
-        if (query.kind === 'Field') {
-            const queryField = query;
-            const fieldInfo = getQueryInfo(queryField.name.value);
-            if (fieldInfo.isPaginatedList) {
-                processPaginatedList(queryField, fieldInfo, fields, fragments);
-            } else if (queryField.selectionSet) {
-                // Check for nested paginated lists
-                findNestedPaginatedLists(queryField, fieldInfo.type, fields, fragments);
+function findMutationOperation(documentNode: DocumentNode): OperationDefinitionNode {
+    const operationDefinition = documentNode.definitions.find(
+        (def): def is OperationDefinitionNode =>
+            def.kind === 'OperationDefinition' && def.operation === 'mutation',
+    );
+    if (!operationDefinition) {
+        throw new Error('Could not find mutation operation definition');
+    }
+    return operationDefinition;
+}
+
+function findFieldInSelections(
+    selections: readonly any[],
+    pathSegment: string,
+    fragments: Record<string, FragmentDefinitionNode>,
+    currentPath: string[] = [],
+): { fieldNode: FieldNode; fragmentSelections: readonly any[] } {
+    for (const selection of selections) {
+        if (selection.kind === 'Field' && selection.name.value === pathSegment) {
+            return { fieldNode: selection, fragmentSelections: [] };
+        } else if (selection.kind === 'FragmentSpread') {
+            const fragment = fragments[selection.name.value];
+            if (fragment) {
+                const fragmentField = fragment.selectionSet.selections.find(
+                    s => s.kind === 'Field' && s.name.value === pathSegment,
+                ) as FieldNode;
+                if (fragmentField) {
+                    return { fieldNode: fragmentField, fragmentSelections: fragment.selectionSet.selections };
+                }
             }
         }
     }
+    const pathString = currentPath.join('.');
+    throw new Error(`Field "${pathSegment}" not found at path ${pathString}`);
+}
 
+function collectFieldsFromNode(
+    fieldNode: FieldNode,
+    typeName: string,
+    fragments: Record<string, FragmentDefinitionNode>,
+): FieldInfo[] {
+    const fields: FieldInfo[] = [];
+    if (fieldNode.selectionSet) {
+        for (const selection of fieldNode.selectionSet.selections) {
+            if (selection.kind === 'Field' || selection.kind === 'FragmentSpread') {
+                collectFields(typeName, selection, fields, fragments);
+            }
+        }
+    }
     return fields;
 }
 
@@ -199,6 +331,20 @@ function unwrapVariableDefinitionType(type: TypeNode): NamedTypeNode {
     return type;
 }
 
+/**
+ * @description
+ * Helper function to get the first field selection from a query operation definition.
+ */
+function getFirstQueryField(documentNode: DocumentNode): FieldNode {
+    const operationDefinition = findQueryOperation(documentNode);
+    const firstSelection = operationDefinition.selectionSet.selections[0];
+    if (firstSelection?.kind === 'Field') {
+        return firstSelection;
+    } else {
+        throw new Error('Could not determine query field');
+    }
+}
+
 /**
  * @description
  * This function is used to get the name of the query from a DocumentNode.
@@ -216,16 +362,32 @@ function unwrapVariableDefinitionType(type: TypeNode): NamedTypeNode {
  * The query name is `product`.
  */
 export function getQueryName(documentNode: DocumentNode): string {
-    const operationDefinition = documentNode.definitions.find(
-        (def): def is OperationDefinitionNode =>
-            def.kind === 'OperationDefinition' && def.operation === 'query',
-    );
-    const firstSelection = operationDefinition?.selectionSet.selections[0];
-    if (firstSelection?.kind === 'Field') {
-        return firstSelection.name.value;
-    } else {
-        throw new Error('Could not determine query name');
-    }
+    const firstField = getFirstQueryField(documentNode);
+    return firstField.name.value;
+}
+
+/**
+ * @description
+ * This function is used to get the entity name from a DocumentNode.
+ *
+ * For example, in the following query:
+ *
+ * ```graphql
+ * query ProductDetail($id: ID!) {
+ *   product(id: $id) {
+ *     ...ProductDetail
+ *   }
+ * }
+ * ```
+ *
+ * The entity name is `Product`.
+ */
+export function getEntityName(documentNode: DocumentNode): string {
+    const firstField = getFirstQueryField(documentNode);
+    // Get the return type from the field definition
+    const fieldName = firstField.name.value;
+    const queryInfo = getQueryInfo(fieldName);
+    return queryInfo.type;
 }
 
 /**
@@ -272,15 +434,7 @@ export function getObjectPathToPaginatedList(
     documentNode: DocumentNode,
     currentPath: string[] = [],
 ): string[] {
-    // get the query OperationDefinition
-    const operationDefinition = documentNode.definitions.find(
-        (def): def is OperationDefinitionNode =>
-            def.kind === 'OperationDefinition' && def.operation === 'query',
-    );
-    if (!operationDefinition) {
-        throw new Error('Could not find query operation definition');
-    }
-
+    const operationDefinition = findQueryOperation(documentNode);
     return findPaginatedListPath(operationDefinition.selectionSet, 'Query', currentPath);
 }
 
@@ -332,11 +486,8 @@ function findPaginatedListPath(
  * The mutation name is `createProduct`.
  */
 export function getMutationName(documentNode: DocumentNode): string {
-    const operationDefinition = documentNode.definitions.find(
-        (def): def is OperationDefinitionNode =>
-            def.kind === 'OperationDefinition' && def.operation === 'mutation',
-    );
-    const firstSelection = operationDefinition?.selectionSet.selections[0];
+    const operationDefinition = findMutationOperation(documentNode);
+    const firstSelection = operationDefinition.selectionSet.selections[0];
     if (firstSelection?.kind === 'Field') {
         return firstSelection.name.value;
     } else {

package/src/lib/framework/document-introspection/hooks.ts

@@ -1,4 +1,7 @@
-import { FieldInfo, getListQueryFields } from '@/framework/document-introspection/get-document-structure.js';
+import {
+    FieldInfo,
+    getListQueryFields,
+} from '@/vdb/framework/document-introspection/get-document-structure.js';
 import { DocumentNode } from 'graphql';
 import { useMemo } from 'react';
 

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

@@ -1,13 +1,16 @@
-import { registerDashboardWidget } from '../dashboard-widget/widget-extensions.js';
-import {
-    registerDashboardActionBarItem,
-    registerDashboardPageBlock,
-} from '../layout-engine/layout-extensions.js';
-import { addNavMenuItem, addNavMenuSection, NavMenuItem } from '../nav-menu/nav-menu-extensions.js';
-import { registerRoute } from '../page/page-api.js';
 import { globalRegistry } from '../registry/global-registry.js';
 
 import { DashboardExtension } from './extension-api-types.js';
+import {
+    registerAlertExtensions,
+    registerDataTableExtensions,
+    registerDetailFormExtensions,
+    registerFormComponentExtensions,
+    registerLayoutExtensions,
+    registerLoginExtensions,
+    registerNavigationExtensions,
+    registerWidgetExtensions,
+} from './logic/index.js';
 
 globalRegistry.register('extensionSourceChangeCallbacks', new Set<() => void>());
 globalRegistry.register('registerDashboardExtensionCallbacks', new Set<() => void>());
@@ -34,48 +37,31 @@ export function executeDashboardExtensionCallbacks() {
  */
 export function defineDashboardExtension(extension: DashboardExtension) {
     globalRegistry.get('registerDashboardExtensionCallbacks').add(() => {
-        if (extension.navSections) {
-            for (const section of extension.navSections) {
-                addNavMenuSection({
-                    ...section,
-                    placement: 'top',
-                    order: section.order ?? 999,
-                    items: [],
-                });
-            }
-        }
-        if (extension.routes) {
-            for (const route of extension.routes) {
-                if (route.navMenuItem) {
-                    // Add the nav menu item
-                    const item: NavMenuItem = {
-                        url: route.navMenuItem.url ?? route.path,
-                        id: route.navMenuItem.id ?? route.path,
-                        title: route.navMenuItem.title ?? route.path,
-                    };
-                    addNavMenuItem(item, route.navMenuItem.sectionId);
-                }
-                if (route.path) {
-                    // Configure a list page
-                    registerRoute(route);
-                }
-            }
-        }
-        if (extension.actionBarItems) {
-            for (const item of extension.actionBarItems) {
-                registerDashboardActionBarItem(item);
-            }
-        }
-        if (extension.pageBlocks) {
-            for (const block of extension.pageBlocks) {
-                registerDashboardPageBlock(block);
-            }
-        }
-        if (extension.widgets) {
-            for (const widget of extension.widgets) {
-                registerDashboardWidget(widget);
-            }
-        }
+        // Register navigation extensions (nav sections and routes)
+        registerNavigationExtensions(extension.navSections, extension.routes);
+
+        // Register layout extensions (action bar items and page blocks)
+        registerLayoutExtensions(extension.actionBarItems, extension.pageBlocks);
+
+        // Register widget extensions
+        registerWidgetExtensions(extension.widgets);
+
+        // Register form component extensions (custom form components, input components, and display components)
+        registerFormComponentExtensions(extension.customFormComponents);
+
+        // Register data table extensions
+        registerDataTableExtensions(extension.dataTables);
+
+        // Register detail form extensions
+        registerDetailFormExtensions(extension.detailForms);
+
+        // Register alert extensions
+        registerAlertExtensions(extension.alerts);
+
+        // Register login extensions
+        registerLoginExtensions(extension.login);
+
+        // Execute extension source change callbacks
         const callbacks = globalRegistry.get('extensionSourceChangeCallbacks');
         if (callbacks.size) {
             for (const callback of callbacks) {

package/src/lib/framework/extension-api/display-component-extensions.tsx

@@ -0,0 +1,69 @@
+import { BooleanDisplayBadge, BooleanDisplayCheckbox } from '@/vdb/components/data-display/boolean.js';
+import { DateTime } from '@/vdb/components/data-display/date-time.js';
+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';
+
+globalRegistry.register('displayComponents', new Map<string, DataDisplayComponent>());
+
+// Create component function for asset display
+const AssetDisplay: DataDisplayComponent = ({ value }) => <VendureImage asset={value} preset="tiny" />;
+
+// Register built-in display components
+const displayComponents = globalRegistry.get('displayComponents');
+displayComponents.set('vendure:booleanCheckbox', BooleanDisplayCheckbox);
+displayComponents.set('vendure:booleanBadge', BooleanDisplayBadge);
+displayComponents.set('vendure:dateTime', DateTime);
+displayComponents.set('vendure:asset', AssetDisplay);
+displayComponents.set('vendure:money', Money);
+
+export function getDisplayComponent(id: string): DataDisplayComponent | undefined {
+    return globalRegistry.get('displayComponents').get(id);
+}
+
+/**
+ * @description
+ * Gets a display component using the targeting properties.
+ * Uses the same key pattern as registration: pageId_blockId_fieldName
+ */
+export function getTargetedDisplayComponent(
+    pageId: string,
+    blockId: string,
+    field: string,
+): DataDisplayComponent | undefined {
+    const key = generateDisplayComponentKey(pageId, blockId, field);
+    return globalRegistry.get('displayComponents').get(key);
+}
+
+/**
+ * @description
+ * Generates a display component key based on the targeting properties.
+ * Follows the existing pattern: pageId_blockId_fieldName
+ */
+export function generateDisplayComponentKey(pageId: string, blockId: string, field: string): string {
+    return `${pageId}_${blockId}_${field}`;
+}
+
+export function addDisplayComponent({
+    pageId,
+    blockId,
+    field,
+    component,
+}: {
+    pageId: string;
+    blockId: string;
+    field: string;
+    component: React.ComponentType<{ value: any; [key: string]: any }>;
+}) {
+    const displayComponents = globalRegistry.get('displayComponents');
+
+    // Generate the key using the helper function
+    const key = generateDisplayComponentKey(pageId, blockId, field);
+
+    if (displayComponents.has(key)) {
+        // eslint-disable-next-line no-console
+        console.warn(`Display component with key "${key}" is already registered and will be overwritten.`);
+    }
+    displayComponents.set(key, component);
+}

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

@@ -1,100 +1,16 @@
-import { PageContextValue } from '@/framework/layout-engine/page-provider.js';
-import { AnyRoute, RouteOptions } from '@tanstack/react-router';
-import { LucideIcon } from 'lucide-react';
-import type React from 'react';
-
-import { DashboardAlertDefinition } from '../alert/types.js';
-import { DashboardWidgetDefinition } from '../dashboard-widget/types.js';
-import { NavMenuItem } from '../nav-menu/nav-menu-extensions.js';
-
-export interface DashboardRouteDefinition {
-    component: (route: AnyRoute) => React.ReactNode;
-    path: string;
-    navMenuItem?: Partial<NavMenuItem> & { sectionId: string };
-    loader?: RouteOptions['loader'];
-}
-
-export interface ActionBarButtonState {
-    disabled: boolean;
-    visible: boolean;
-}
-
-export interface DashboardNavSectionDefinition {
-    id: string;
-    title: string;
-    icon?: LucideIcon;
-    order?: number;
-}
-
-/**
- * @description
- * **Status: Developer Preview**
- *
- * Allows you to define custom action bar items for any page in the dashboard.
- *
- * @docsCategory extensions
- * @since 3.3.0
- */
-export interface DashboardActionBarItem {
-    /**
-     * @description
-     * The ID of the page where the action bar item should be displayed.
-     */
-    pageId: string;
-    /**
-     * @description
-     * A React component that will be rendered in the action bar.
-     */
-    component: React.FunctionComponent<{ context: PageContextValue }>;
-    /**
-     * @description
-     * Any permissions that are required to display this action bar item.
-     */
-    requiresPermission?: string | string[];
-}
-
-export interface DashboardActionBarDropdownMenuItem {
-    locationId: string;
-    component: React.FunctionComponent<{ context: PageContextValue }>;
-    requiresPermission?: string | string[];
-}
-
-export type PageBlockPosition = { blockId: string; order: 'before' | 'after' | 'replace' };
-
-/**
- * @description
- * **Status: Developer Preview**
- *
- * The location of a page block in the dashboard. The location can be found by turning on
- * "developer mode" in the dashboard user menu (bottom left corner) and then
- * clicking the `< />` icon when hovering over a page block.
- *
- * @docsCategory extensions
- * @since 3.3.0
- */
-export type PageBlockLocation = {
-    pageId: string;
-    position: PageBlockPosition;
-    column: 'main' | 'side';
-};
-
-/**
- * @description
- * **Status: Developer Preview**
- *
- * This allows you to insert a custom component into a specific location
- * on any page in the dashboard.
- *
- * @docsCategory extensions
- * @since 3.3.0
- */
-export interface DashboardPageBlockDefinition {
-    id: string;
-    title?: React.ReactNode;
-    location: PageBlockLocation;
-    component: React.FunctionComponent<{ context: PageContextValue }>;
-    requiresPermission?: string | string[];
-}
+// Import types for the main interface
+import {
+    DashboardActionBarItem,
+    DashboardAlertDefinition,
+    DashboardCustomFormComponents,
+    DashboardDataTableExtensionDefinition,
+    DashboardDetailFormExtensionDefinition,
+    DashboardLoginExtensions,
+    DashboardNavSectionDefinition,
+    DashboardPageBlockDefinition,
+    DashboardRouteDefinition,
+    DashboardWidgetDefinition,
+} from './types/index.js';
 
 /**
  * @description
@@ -128,7 +44,7 @@ export interface DashboardExtension {
     actionBarItems?: DashboardActionBarItem[];
     /**
      * @description
-     * Not yet implemented
+     * Allows you to define custom alerts that can be displayed in the dashboard.
      */
     alerts?: DashboardAlertDefinition[];
     /**
@@ -137,4 +53,24 @@ export interface DashboardExtension {
      * given components and optionally also add a nav menu item.
      */
     widgets?: DashboardWidgetDefinition[];
+    /**
+     * @description
+     * Unified registration for custom form custom field components.
+     */
+    customFormComponents?: DashboardCustomFormComponents;
+    /**
+     * @description
+     * Allows you to customize aspects of existing data tables in the dashboard.
+     */
+    dataTables?: DashboardDataTableExtensionDefinition[];
+    /**
+     * @description
+     * Allows you to customize the detail form for any page in the dashboard.
+     */
+    detailForms?: DashboardDetailFormExtensionDefinition[];
+    /**
+     * @description
+     * Allows you to customize the login page with custom components.
+     */
+    login?: DashboardLoginExtensions;
 }

package/src/lib/framework/extension-api/input-component-extensions.tsx

@@ -0,0 +1,73 @@
+import { CombinationModeInput } from '@/vdb/components/data-input/combination-mode-input.js';
+import { DateTimeInput } from '@/vdb/components/data-input/datetime-input.js';
+import { FacetValueInput } from '@/vdb/components/data-input/facet-value-input.js';
+import { MoneyInput } from '@/vdb/components/data-input/money-input.js';
+import { ProductMultiInput } from '@/vdb/components/data-input/product-multi-selector.js';
+import { Checkbox } from '@/vdb/components/ui/checkbox.js';
+import { Input } from '@/vdb/components/ui/input.js';
+import { DataInputComponent } from '../component-registry/component-registry.js';
+import { globalRegistry } from '../registry/global-registry.js';
+
+globalRegistry.register('inputComponents', new Map<string, DataInputComponent>());
+
+// Create component functions for built-in components
+const TextInput: DataInputComponent = props => (
+    <Input {...props} onChange={e => props.onChange(e.target.value)} />
+);
+const NumberInput: DataInputComponent = props => (
+    <Input {...props} onChange={e => props.onChange(e.target.valueAsNumber)} type="number" />
+);
+const CheckboxInput: DataInputComponent = props => (
+    <Checkbox
+        {...props}
+        checked={props.value === 'true' || props.value === true}
+        onCheckedChange={value => props.onChange(value)}
+    />
+);
+
+// Register built-in input components
+const inputComponents = globalRegistry.get('inputComponents');
+inputComponents.set('vendure:moneyInput', MoneyInput);
+inputComponents.set('vendure:textInput', TextInput);
+inputComponents.set('vendure:numberInput', NumberInput);
+inputComponents.set('vendure:dateTimeInput', DateTimeInput);
+inputComponents.set('vendure:checkboxInput', CheckboxInput);
+inputComponents.set('vendure:facetValueInput', FacetValueInput);
+inputComponents.set('vendure:combinationModeInput', CombinationModeInput);
+inputComponents.set('vendure:productMultiInput', ProductMultiInput);
+
+export function getInputComponent(id: string): DataInputComponent | undefined {
+    return globalRegistry.get('inputComponents').get(id);
+}
+
+/**
+ * @description
+ * Generates a component key based on the targeting properties.
+ * Follows the existing pattern: pageId_blockId_fieldName
+ */
+export function generateInputComponentKey(pageId: string, blockId: string, field: string): string {
+    return `${pageId}_${blockId}_${field}`;
+}
+
+export function addInputComponent({
+    pageId,
+    blockId,
+    field,
+    component,
+}: {
+    pageId: string;
+    blockId: string;
+    field: string;
+    component: DataInputComponent;
+}) {
+    const inputComponents = globalRegistry.get('inputComponents');
+
+    // Generate the key using the helper function
+    const key = generateInputComponentKey(pageId, blockId, field);
+
+    if (inputComponents.has(key)) {
+        // eslint-disable-next-line no-console
+        console.warn(`Input component with key "${key}" is already registered and will be overwritten.`);
+    }
+    inputComponents.set(key, component);
+}