@vendure/dashboard 3.4.0-minor-202506250934 → 3.4.0

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

@@ -0,0 +1,10 @@
+import { globalRegistry } from '../../registry/global-registry.js';
+import { DashboardAlertDefinition } from '../types/alerts.js';
+
+export function registerAlertExtensions(alerts?: DashboardAlertDefinition[]) {
+    if (alerts) {
+        for (const alert of alerts) {
+            globalRegistry.get('dashboardAlertRegistry').set(alert.id, alert);
+        }
+    }
+}

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

@@ -0,0 +1,60 @@
+import { parse } from 'graphql';
+
+import { addBulkAction, addListQueryDocument } from '../../data-table/data-table-extensions.js';
+import { addDisplayComponent } from '../display-component-extensions.js';
+import { DashboardDataTableExtensionDefinition } from '../types/index.js';
+
+/**
+ * @description
+ * Generates a data table display component key based on the pageId and column name.
+ * Uses the pattern: pageId_columnName
+ */
+export function generateDataTableDisplayComponentKey(pageId: string, column: string): string {
+    return `${pageId}_${column}`;
+}
+
+/**
+ * @description
+ * Adds a display component for a specific column in a data table.
+ */
+export function addDataTableDisplayComponent(
+    pageId: string,
+    column: string,
+    component: React.ComponentType<{ value: any; [key: string]: any }>,
+) {
+    const key = generateDataTableDisplayComponentKey(pageId, column);
+    addDisplayComponent({ pageId, blockId: 'list-table', field: column, component });
+}
+
+export function registerDataTableExtensions(dataTables?: DashboardDataTableExtensionDefinition[]) {
+    if (dataTables) {
+        for (const dataTable of dataTables) {
+            if (dataTable.bulkActions?.length) {
+                for (const action of dataTable.bulkActions) {
+                    addBulkAction(dataTable.pageId, dataTable.blockId, action);
+                }
+            }
+            if (dataTable.extendListDocument) {
+                const document =
+                    typeof dataTable.extendListDocument === 'function'
+                        ? dataTable.extendListDocument()
+                        : dataTable.extendListDocument;
+
+                addListQueryDocument(
+                    dataTable.pageId,
+                    dataTable.blockId,
+                    typeof document === 'string' ? parse(document) : document,
+                );
+            }
+            if (dataTable.displayComponents?.length) {
+                for (const displayComponent of dataTable.displayComponents) {
+                    addDataTableDisplayComponent(
+                        dataTable.pageId,
+                        displayComponent.column,
+                        displayComponent.component,
+                    );
+                }
+            }
+        }
+    }
+}

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

@@ -0,0 +1,48 @@
+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';
+
+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,9 @@
+// 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 './login.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/login.ts

@@ -0,0 +1,17 @@
+import { globalRegistry } from '../../registry/global-registry.js';
+import { DashboardLoginExtensions } from '../types/login.js';
+
+export function registerLoginExtensions(loginExtensions?: DashboardLoginExtensions) {
+    if (!loginExtensions) {
+        return;
+    }
+
+    const registryKey = 'loginExtensions';
+
+    globalRegistry.set(registryKey, (oldValue: DashboardLoginExtensions) => {
+        return {
+            ...oldValue,
+            ...loginExtensions,
+        };
+    });
+}

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

@@ -0,0 +1,38 @@
+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,
+                    order: route.navMenuItem.order,
+                };
+                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,96 @@
+import { Table } from '@tanstack/react-table';
+import { DocumentNode } from 'graphql';
+
+/**
+ * @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
+ * @docsPage DataTable
+ * @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 }>;
+}
+
+export type BulkActionContext<Item extends { id: string } & Record<string, any>> = {
+    selection: Item[];
+    table: Table<Item>;
+};
+
+export type BulkActionComponent<Item extends { id: string } & Record<string, any>> = React.FunctionComponent<
+    BulkActionContext<Item>
+>;
+
+/**
+ * @description
+ * **Status: Developer Preview**
+ *
+ * A bulk action is a component that will be rendered in the bulk actions dropdown.
+ *
+ * @docsCategory components
+ * @docsPage DataTable
+ * @since 3.4.0
+ */
+export type BulkAction = {
+    /**
+     * @description
+     * Optional order number to control the position of this bulk action in the dropdown.
+     * A larger number will appear lower in the list.
+     */
+    order?: number;
+    /**
+     * @description
+     * The React component that will be rendered as the bulk action item.
+     */
+    component: BulkActionComponent<any>;
+};
+
+/**
+ * @description
+ * This allows you to customize aspects of existing data tables in the dashboard.
+ *
+ * @docsCategory extensions
+ * @docsPage DataTable
+ * @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,94 @@
+import {
+    DataDisplayComponent,
+    DataInputComponent,
+} from '@/vdb/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
+ * @docsPage DetailForms
+ * @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
+ * @docsPage DetailForms
+ * @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;
+}
+
+/**
+ * @description
+ * Allows you to extend existing detail forms (e.g. on the product detail or customer detail pages)
+ * with custom GraphQL queries, input components, and display components.
+ *
+ * @since 3.4.0
+ * @docsPage DetailForms
+ * @docsCategory extensions
+ */
+export interface DashboardDetailFormExtensionDefinition {
+    /**
+     * @description
+     * The ID of the page where the detail form is located, e.g. `'product-detail'`, `'order-detail'`.
+     */
+    pageId: string;
+    /**
+     * @description
+     * Extends the GraphQL query used to fetch data for the detail page, allowing you to add additional
+     * fields that can be used by custom input or display components.
+     */
+    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,43 @@
+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
+ * @docsPage FormComponents
+ * @since 3.4.0
+ */
+export interface DashboardCustomFormComponent {
+    /**
+     * @description
+     * A unique identifier for the custom form component. It is a good practice to namespace
+     * these IDs to avoid naming collisions, for example `"my-plugin.markdown-editor"`.
+     */
+    id: string;
+    /**
+     * @description
+     * The React component that will be rendered as the custom form input.
+     */
+    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
+ * @docsPage FormComponents
+ * @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,9 @@
+// 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 './login.js';
+export * from './navigation.js';
+export * from './widgets.js';

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

@@ -0,0 +1,90 @@
+import type React from 'react';
+
+import { PageContextValue } from '../../layout-engine/page-provider.js';
+
+export interface ActionBarButtonState {
+    disabled: boolean;
+    visible: boolean;
+}
+
+/**
+ * @description
+ * Allows you to define custom action bar items for any page in the dashboard.
+ *
+ * @docsCategory extensions
+ * @docsPage Layout
+ * @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
+     * The type of action bar item to display. Defaults to `button`.
+     * The 'dropdown' type is used to display the action bar item as a dropdown menu item.
+     *
+     * When using the dropdown type, use a suitable [dropdown item](https://ui.shadcn.com/docs/components/dropdown-menu)
+     * component, such as:
+     *
+     * ```tsx
+     * import { DropdownMenuItem } from '\@vendure/dashboard';
+     *
+     * // ...
+     *
+     * {
+     *   component: () => <DropdownMenuItem>My Item</DropdownMenuItem>
+     * }
+     * ```
+     *
+     * @default 'button'
+     */
+    type?: 'button' | 'dropdown';
+    /**
+     * @description
+     * Any permissions that are required to display this action bar item.
+     */
+    requiresPermission?: string | string[];
+}
+
+export type PageBlockPosition = { blockId: string; order: 'before' | 'after' | 'replace' };
+
+/**
+ * @description
+ * 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
+ * @docsPage Layout
+ * @since 3.3.0
+ */
+export type PageBlockLocation = {
+    pageId: string;
+    position: PageBlockPosition;
+    column: 'main' | 'side';
+};
+
+/**
+ * @description
+ * This allows you to insert a custom component into a specific location
+ * on any page in the dashboard.
+ *
+ * @docsCategory extensions
+ * @docsPage Layout
+ * @since 3.3.0
+ */
+export interface DashboardPageBlockDefinition {
+    id: string;
+    title?: React.ReactNode;
+    location: PageBlockLocation;
+    component: React.FunctionComponent<{ context: PageContextValue }>;
+    requiresPermission?: string | string[];
+}