@vendure/dashboard 3.3.6-master-202507011151 → 3.3.6-master-202507020959

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

@@ -0,0 +1,48 @@
+import { addDetailQueryDocument } from '@/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';
+
+export function registerDetailFormExtensions(detailForms?: DashboardDetailFormExtensionDefinition[]) {
+    if (detailForms) {
+        for (const detailForm of detailForms) {
+            if (detailForm.extendDetailDocument) {
+                const document =
+                    typeof detailForm.extendDetailDocument === 'function'
+                        ? detailForm.extendDetailDocument()
+                        : detailForm.extendDetailDocument;
+
+                addDetailQueryDocument(
+                    detailForm.pageId,
+                    typeof document === 'string' ? parse(document) : document,
+                );
+            }
+
+            // Register input components for this detail form
+            if (detailForm.inputs) {
+                for (const inputComponent of detailForm.inputs) {
+                    addInputComponent({
+                        pageId: detailForm.pageId,
+                        blockId: inputComponent.blockId,
+                        field: inputComponent.field,
+                        component: inputComponent.component,
+                    });
+                }
+            }
+
+            // 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/form-components.ts

@@ -0,0 +1,13 @@
+import { addCustomFormComponent } from '../../form-engine/custom-form-component-extensions.js';
+import { DashboardCustomFormComponents } from '../types/form-components.js';
+
+export function registerFormComponentExtensions(customFormComponents?: DashboardCustomFormComponents) {
+    if (customFormComponents) {
+        // Handle custom field components
+        if (customFormComponents.customFields) {
+            for (const component of customFormComponents.customFields) {
+                addCustomFormComponent(component);
+            }
+        }
+    }
+}

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

@@ -0,0 +1,8 @@
+// Re-export all domain-specific logic functions
+export * from './alerts.js';
+export * from './data-table.js';
+export * from './detail-forms.js';
+export * from './form-components.js';
+export * from './layout.js';
+export * from './navigation.js';
+export * from './widgets.js';

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

@@ -0,0 +1,22 @@
+import {
+    registerDashboardActionBarItem,
+    registerDashboardPageBlock,
+} from '../../layout-engine/layout-extensions.js';
+import { DashboardActionBarItem, DashboardPageBlockDefinition } from '../types/layout.js';
+
+export function registerLayoutExtensions(
+    actionBarItems?: DashboardActionBarItem[],
+    pageBlocks?: DashboardPageBlockDefinition[],
+) {
+    if (actionBarItems) {
+        for (const item of actionBarItems) {
+            registerDashboardActionBarItem(item);
+        }
+    }
+
+    if (pageBlocks) {
+        for (const block of pageBlocks) {
+            registerDashboardPageBlock(block);
+        }
+    }
+}

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

@@ -0,0 +1,37 @@
+import { addNavMenuItem, addNavMenuSection, NavMenuItem } from '../../nav-menu/nav-menu-extensions.js';
+import { registerRoute } from '../../page/page-api.js';
+import { DashboardNavSectionDefinition, DashboardRouteDefinition } from '../types/navigation.js';
+
+export function registerNavigationExtensions(
+    navSections?: DashboardNavSectionDefinition[],
+    routes?: DashboardRouteDefinition[],
+) {
+    if (navSections) {
+        for (const section of navSections) {
+            addNavMenuSection({
+                ...section,
+                placement: 'top',
+                order: section.order ?? 999,
+                items: [],
+            });
+        }
+    }
+
+    if (routes) {
+        for (const route of 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);
+            }
+        }
+    }
+}

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

@@ -0,0 +1,10 @@
+import { registerDashboardWidget } from '../../dashboard-widget/widget-extensions.js';
+import { DashboardWidgetDefinition } from '../types/index.js';
+
+export function registerWidgetExtensions(widgets?: DashboardWidgetDefinition[]) {
+    if (widgets) {
+        for (const widget of widgets) {
+            registerDashboardWidget(widget);
+        }
+    }
+}

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

@@ -0,0 +1,54 @@
+/**
+ * @description
+ * **Status: Developer Preview**
+ *
+ * Allows you to define custom alerts that can be displayed in the dashboard.
+ *
+ * @docsCategory extensions
+ * @since 3.3.0
+ */
+export interface DashboardAlertDefinition<TResponse = any> {
+    /**
+     * @description
+     * A unique identifier for the alert.
+     */
+    id: string;
+    /**
+     * @description
+     * The title of the alert. Can be a string or a function that returns a string based on the response data.
+     */
+    title: string | ((data: TResponse) => string);
+    /**
+     * @description
+     * The description of the alert. Can be a string or a function that returns a string based on the response data.
+     */
+    description?: string | ((data: TResponse) => string);
+    /**
+     * @description
+     * The severity level of the alert.
+     */
+    severity: 'info' | 'warning' | 'error';
+    /**
+     * @description
+     * A function that checks the condition and returns the response data.
+     */
+    check: () => Promise<TResponse> | TResponse;
+    /**
+     * @description
+     * The interval in milliseconds to recheck the condition.
+     */
+    recheckInterval?: number;
+    /**
+     * @description
+     * A function that determines whether the alert should be shown based on the response data.
+     */
+    shouldShow?: (data: TResponse) => boolean;
+    /**
+     * @description
+     * Optional actions that can be performed when the alert is shown.
+     */
+    actions?: Array<{
+        label: string;
+        onClick: (data: TResponse) => void;
+    }>;
+}

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

@@ -0,0 +1,64 @@
+import { DocumentNode } from 'graphql';
+
+import { BulkAction } from '../../data-table/data-table-types.js';
+
+/**
+ * @description
+ * Allows you to define custom display components for specific columns in data tables.
+ * The pageId is already defined in the data table extension, so only the column name is needed.
+ *
+ * @docsCategory extensions
+ * @since 3.4.0
+ */
+export interface DashboardDataTableDisplayComponent {
+    /**
+     * @description
+     * The name of the column where this display component should be used.
+     */
+    column: string;
+    /**
+     * @description
+     * The React component that will be rendered as the display.
+     * It should accept `value` and other standard display props.
+     */
+    component: React.ComponentType<{ value: any; [key: string]: any }>;
+}
+
+/**
+ * @description
+ * **Status: Developer Preview**
+ *
+ * This allows you to customize aspects of existing data tables in the dashboard.
+ *
+ * @docsCategory extensions
+ * @since 3.4.0
+ */
+export interface DashboardDataTableExtensionDefinition {
+    /**
+     * @description
+     * The ID of the page where the data table is located, e.g. `'product-list'`, `'order-list'`.
+     */
+    pageId: string;
+    /**
+     * @description
+     * The ID of the data table block. Defaults to `'list-table'`, which is the default blockId
+     * for the standard list pages. However, some other pages may use a different blockId,
+     * such as `'product-variants-table'` on the `'product-detail'` page.
+     */
+    blockId?: string;
+    /**
+     * @description
+     * An array of additional bulk actions that will be available on the data table.
+     */
+    bulkActions?: BulkAction[];
+    /**
+     * @description
+     * Allows you to extend the list document for the data table.
+     */
+    extendListDocument?: string | DocumentNode | (() => DocumentNode | string);
+    /**
+     * @description
+     * Custom display components for specific columns in the data table.
+     */
+    displayComponents?: DashboardDataTableDisplayComponent[];
+}

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

@@ -0,0 +1,81 @@
+import {
+    DataDisplayComponent,
+    DataInputComponent,
+} from '@/framework/component-registry/component-registry.js';
+import { DocumentNode } from 'graphql';
+
+/**
+ * @description
+ * Allows you to define custom input components for specific fields in detail forms.
+ * The pageId is already defined in the detail form extension, so only the blockId and field are needed.
+ *
+ * @docsCategory extensions
+ * @since 3.4.0
+ */
+export interface DashboardDetailFormInputComponent {
+    /**
+     * @description
+     * The ID of the block where this input component should be used.
+     */
+    blockId: string;
+    /**
+     * @description
+     * The name of the field where this input component should be used.
+     */
+    field: string;
+    /**
+     * @description
+     * The React component that will be rendered as the input.
+     * It should accept `value`, `onChange`, and other standard input props.
+     */
+    component: DataInputComponent;
+}
+
+/**
+ * @description
+ * Allows you to define custom display components for specific fields in detail forms.
+ * The pageId is already defined in the detail form extension, so only the blockId and field are needed.
+ *
+ * @docsCategory extensions
+ * @since 3.4.0
+ */
+export interface DashboardDetailFormDisplayComponent {
+    /**
+     * @description
+     * The ID of the block where this display component should be used.
+     */
+    blockId: string;
+    /**
+     * @description
+     * The name of the field where this display component should be used.
+     */
+    field: string;
+    /**
+     * @description
+     * The React component that will be rendered as the display.
+     * It should accept `value` and other standard display props.
+     */
+    component: DataDisplayComponent;
+}
+
+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
+     * Custom input components for specific fields in the detail form.
+     */
+    inputs?: DashboardDetailFormInputComponent[];
+    /**
+     * @description
+     * Custom display components for specific fields in the detail form.
+     */
+    displays?: DashboardDetailFormDisplayComponent[];
+}

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

@@ -0,0 +1,32 @@
+import type React from 'react';
+
+import { CustomFormComponentInputProps } from '../../form-engine/custom-form-component.js';
+
+/**
+ * @description
+ * Allows you to define custom form components for custom fields in the dashboard.
+ *
+ * @docsCategory extensions
+ * @since 3.4.0
+ */
+export interface DashboardCustomFormComponent {
+    id: string;
+    component: React.FunctionComponent<CustomFormComponentInputProps>;
+}
+
+/**
+ * @description
+ * Interface for registering custom field components in the dashboard.
+ * For input and display components, use the co-located approach with detailForms.
+ *
+ * @docsCategory extensions
+ * @since 3.4.0
+ */
+export interface DashboardCustomFormComponents {
+    /**
+     * @description
+     * Custom form components for custom fields. These are used when rendering
+     * custom fields in forms.
+     */
+    customFields?: DashboardCustomFormComponent[];
+}

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

@@ -0,0 +1,8 @@
+// Re-export all domain-specific types
+export * from './alerts.js';
+export * from './data-table.js';
+export * from './detail-forms.js';
+export * from './form-components.js';
+export * from './layout.js';
+export * from './navigation.js';
+export * from './widgets.js';

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

@@ -0,0 +1,78 @@
+import type React from 'react';
+
+import { PageContextValue } from '../../layout-engine/page-provider.js';
+
+export interface ActionBarButtonState {
+    disabled: boolean;
+    visible: boolean;
+}
+
+/**
+ * @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[];
+}

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

@@ -0,0 +1,19 @@
+import { AnyRoute, RouteOptions } from '@tanstack/react-router';
+import { LucideIcon } from 'lucide-react';
+import type React from 'react';
+
+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 DashboardNavSectionDefinition {
+    id: string;
+    title: string;
+    icon?: LucideIcon;
+    order?: number;
+}

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

@@ -0,0 +1,94 @@
+import type React from 'react';
+
+/**
+ * @description
+ * **Status: Developer Preview**
+ *
+ * Base props interface for dashboard widgets.
+ *
+ * @docsCategory extensions
+ * @since 3.3.0
+ */
+export interface DashboardBaseWidgetProps {
+    widgetId: string;
+    config?: Record<string, unknown>;
+}
+
+/**
+ * @description
+ * **Status: Developer Preview**
+ *
+ * Represents an instance of a dashboard widget with its layout and configuration.
+ *
+ * @docsCategory extensions
+ * @since 3.3.0
+ */
+export type DashboardWidgetInstance = {
+    /**
+     * @description
+     * A unique identifier for the widget instance.
+     */
+    id: string;
+    /**
+     * @description
+     * The ID of the widget definition this instance is based on.
+     */
+    widgetId: string;
+    /**
+     * @description
+     * The layout configuration for the widget.
+     */
+    layout: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    /**
+     * @description
+     * Optional configuration data for the widget.
+     */
+    config?: Record<string, unknown>;
+};
+
+/**
+ * @description
+ * **Status: Developer Preview**
+ *
+ * Defines a dashboard widget that can be added to the dashboard.
+ *
+ * @docsCategory extensions
+ * @since 3.3.0
+ */
+export type DashboardWidgetDefinition = {
+    /**
+     * @description
+     * A unique identifier for the widget.
+     */
+    id: string;
+    /**
+     * @description
+     * The display name of the widget.
+     */
+    name: string;
+    /**
+     * @description
+     * The React component that renders the widget.
+     */
+    component: React.ComponentType<DashboardBaseWidgetProps>;
+    /**
+     * @description
+     * The default size and position of the widget.
+     */
+    defaultSize: { w: number; h: number; x?: number; y?: number };
+    /**
+     * @description
+     * The minimum size constraints for the widget.
+     */
+    minSize?: { w: number; h: number };
+    /**
+     * @description
+     * The maximum size constraints for the widget.
+     */
+    maxSize?: { w: number; h: number };
+};

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

@@ -11,11 +11,15 @@ import { AnyRoute, useNavigate } from '@tanstack/react-router';
 import { ResultOf, VariablesOf } from 'gql.tada';
 import { toast } from 'sonner';
 import {
+    FieldInfo,
     getEntityName,
     getOperationVariablesFields,
 } from '../document-introspection/get-document-structure.js';
 
 import { TranslatableFormFieldWrapper } from '@/components/shared/translatable-form-field.js';
+import { ControllerRenderProps, FieldPath, FieldValues } from 'react-hook-form';
+import { useComponentRegistry } from '../component-registry/component-registry.js';
+import { generateInputComponentKey } from '../extension-api/input-component-extensions.js';
 import {
     CustomFieldsPageBlock,
     DetailFormGrid,
@@ -85,10 +89,37 @@ export interface DetailPageProps<
     setValuesForUpdate: (entity: ResultOf<T>[EntityField]) => VariablesOf<U>['input'];
 }
 
+export interface DetailPageFieldProps<
+    TFieldValues extends FieldValues = FieldValues,
+    TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+> {
+    fieldInfo: FieldInfo;
+    field: ControllerRenderProps<TFieldValues, TName>;
+    blockId: string;
+    pageId: string;
+}
+
 /**
  * Renders form input components based on field type
  */
-function renderFieldInput(fieldInfo: { type: string }, field: any) {
+function FieldInputRenderer<
+    TFieldValues extends FieldValues = FieldValues,
+    TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+>({ fieldInfo, field, blockId, pageId }: DetailPageFieldProps<TFieldValues, TName>) {
+    const componentRegistry = useComponentRegistry();
+    const customInputComponentKey = generateInputComponentKey(pageId, blockId, fieldInfo.name);
+
+    const DisplayComponent = componentRegistry.getDisplayComponent(customInputComponentKey);
+    const InputComponent = componentRegistry.getInputComponent(customInputComponentKey);
+
+    if (DisplayComponent) {
+        return <DisplayComponent {...field} />;
+    }
+
+    if (InputComponent) {
+        return <InputComponent {...field} />;
+    }
+
     switch (fieldInfo.type) {
         case 'Int':
         case 'Float':
@@ -196,7 +227,14 @@ export function DetailPage<
                                         control={form.control}
                                         name={fieldInfo.name as never}
                                         label={fieldInfo.name}
-                                        render={({ field }) => renderFieldInput(fieldInfo, field)}
+                                        render={({ field }) => (
+                                            <FieldInputRenderer
+                                                fieldInfo={fieldInfo}
+                                                field={field}
+                                                blockId="main-form"
+                                                pageId={pageId}
+                                            />
+                                        )}
                                     />
                                 );
                             })}
@@ -211,7 +249,14 @@ export function DetailPage<
                                         control={form.control}
                                         name={fieldInfo.name as never}
                                         label={fieldInfo.name}
-                                        render={({ field }) => renderFieldInput(fieldInfo, field)}
+                                        render={({ field }) => (
+                                            <FieldInputRenderer
+                                                fieldInfo={fieldInfo}
+                                                field={field}
+                                                blockId="main-form"
+                                                pageId={pageId}
+                                            />
+                                        )}
                                     />
                                 );
                             })}

package/src/lib/framework/registry/registry-types.ts

@@ -2,6 +2,7 @@ import { DocumentNode } from 'graphql';
 import React from 'react';
 
 import { DashboardAlertDefinition } from '../alert/types.js';
+import { DataDisplayComponent, DataInputComponent } from '../component-registry/component-registry.js';
 import { DashboardWidgetDefinition } from '../dashboard-widget/types.js';
 import { BulkAction } from '../data-table/data-table-types.js';
 import {
@@ -20,6 +21,8 @@ export interface GlobalRegistryContents {
     dashboardWidgetRegistry: Map<string, DashboardWidgetDefinition>;
     dashboardAlertRegistry: Map<string, DashboardAlertDefinition>;
     customFormComponents: Map<string, React.FunctionComponent<CustomFormComponentInputProps>>;
+    inputComponents: Map<string, DataInputComponent>;
+    displayComponents: Map<string, DataDisplayComponent>;
     bulkActionsRegistry: Map<string, BulkAction[]>;
     listQueryDocumentRegistry: Map<string, DocumentNode[]>;
     detailQueryDocumentRegistry: Map<string, DocumentNode[]>;