@vendure/dashboard 3.3.6-master-202507020234 → 3.3.6-master-202507021511

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

@@ -1,161 +1,18 @@
-import { PageContextValue } from '@/framework/layout-engine/page-provider.js';
-import { AnyRoute, RouteOptions } from '@tanstack/react-router';
-import { DocumentNode } from 'graphql';
-import { LucideIcon } from 'lucide-react';
-import type React from 'react';
+// Import all domain-specific types
+export * from './types/index.js';
 
-import { DashboardAlertDefinition } from '../alert/types.js';
-import { DashboardWidgetDefinition } from '../dashboard-widget/types.js';
-import { BulkAction } from '../data-table/data-table-types.js';
-import { CustomFormComponentInputProps } from '../form-engine/custom-form-component.js';
-import { NavMenuItem } from '../nav-menu/nav-menu-extensions.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>;
-}
-
-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[];
-}
-
-/**
- * @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);
-}
-
-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);
-}
+// Import types for the main interface
+import {
+    DashboardActionBarItem,
+    DashboardAlertDefinition,
+    DashboardCustomFormComponents,
+    DashboardDataTableExtensionDefinition,
+    DashboardDetailFormExtensionDefinition,
+    DashboardNavSectionDefinition,
+    DashboardPageBlockDefinition,
+    DashboardRouteDefinition,
+    DashboardWidgetDefinition,
+} from './types/index.js';
 
 /**
  * @description
@@ -189,7 +46,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[];
     /**
@@ -200,9 +57,10 @@ export interface DashboardExtension {
     widgets?: DashboardWidgetDefinition[];
     /**
      * @description
-     * Allows you to define custom form components for custom fields in the dashboard.
+     * Unified registration for custom form components including custom field components,
+     * input components, and display components.
      */
-    customFormComponents?: DashboardCustomFormComponent[];
+    customFormComponents?: DashboardCustomFormComponents;
     /**
      * @description
      * Allows you to customize aspects of existing data tables in the dashboard.

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

@@ -0,0 +1,69 @@
+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 { 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);
+
+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: React.ComponentType<{ value: any; onChange: (value: any) => void; [key: string]: any }>;
+}) {
+    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);
+}

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,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 '@/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
+ * @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[];
+}