@wilshop/dashboard 3.5.2

package/src/lib/framework/document-introspection/testing-utils.ts

@@ -0,0 +1,161 @@
+export function getMockSchemaInfo() {
+    return {
+        schemaInfo: {
+            types: {
+                Query: {
+                    products: ['ProductList', false, false, true],
+                    product: ['Product', false, false, false],
+                    collection: ['Collection', false, false, false],
+                    order: ['Order', false, false, false],
+                },
+                Mutation: {
+                    updateProduct: ['Product', false, false, false],
+                    adjustDraftOrderLine: ['Order', false, false, false],
+                },
+
+                Collection: {
+                    id: ['ID', false, false, false],
+                    name: ['String', false, false, false],
+                    productVariants: ['ProductVariantList', false, false, true],
+                },
+
+                ProductVariantList: {
+                    items: ['ProductVariant', false, true, false],
+                    totalItems: ['Int', false, false, false],
+                },
+
+                Product: {
+                    channels: ['Channel', false, true, false],
+                    id: ['ID', false, false, false],
+                    createdAt: ['DateTime', false, false, false],
+                    updatedAt: ['DateTime', false, false, false],
+                    languageCode: ['LanguageCode', false, false, false],
+                    name: ['String', false, false, false],
+                    slug: ['String', false, false, false],
+                    description: ['String', false, false, false],
+                    enabled: ['Boolean', false, false, false],
+                    featuredAsset: ['Asset', true, false, false],
+                    assets: ['Asset', false, true, false],
+                    variants: ['ProductVariant', false, true, false],
+                    variantList: ['ProductVariantList', false, false, true],
+                    optionGroups: ['ProductOptionGroup', false, true, false],
+                    facetValues: ['FacetValue', false, true, false],
+                    translations: ['ProductTranslation', false, true, false],
+                    collections: ['Collection', false, true, false],
+                    reviews: ['ProductReviewList', false, false, true],
+                    reviewsHistogram: ['ProductReviewHistogramItem', false, true, false],
+                    customFields: ['ProductCustomFields', true, false, false],
+                },
+                ProductVariantPrice: {
+                    currencyCode: ['CurrencyCode', false, false, false],
+                    price: ['Money', false, false, false],
+                    customFields: ['JSON', true, false, false],
+                },
+                ProductVariant: {
+                    enabled: ['Boolean', false, false, false],
+                    trackInventory: ['GlobalFlag', false, false, false],
+                    stockOnHand: ['Int', false, false, false],
+                    stockAllocated: ['Int', false, false, false],
+                    outOfStockThreshold: ['Int', false, false, false],
+                    useGlobalOutOfStockThreshold: ['Boolean', false, false, false],
+                    prices: ['ProductVariantPrice', false, true, false],
+                    stockLevels: ['StockLevel', false, true, false],
+                    stockMovements: ['StockMovementList', false, false, false],
+                    channels: ['Channel', false, true, false],
+                    id: ['ID', false, false, false],
+                    product: ['Product', false, false, false],
+                    productId: ['ID', false, false, false],
+                    createdAt: ['DateTime', false, false, false],
+                    updatedAt: ['DateTime', false, false, false],
+                    languageCode: ['LanguageCode', false, false, false],
+                    sku: ['String', false, false, false],
+                    name: ['String', false, false, false],
+                    featuredAsset: ['Asset', true, false, false],
+                    assets: ['Asset', false, true, false],
+                    price: ['Money', false, false, false],
+                    currencyCode: ['CurrencyCode', false, false, false],
+                    priceWithTax: ['Money', false, false, false],
+                    stockLevel: ['String', false, false, false],
+                    taxRateApplied: ['TaxRate', false, false, false],
+                    taxCategory: ['TaxCategory', false, false, false],
+                    options: ['ProductOption', false, true, false],
+                    facetValues: ['FacetValue', false, true, false],
+                    translations: ['ProductVariantTranslation', false, true, false],
+                    customFields: ['JSON', true, false, false],
+                },
+                ProductCustomFields: {
+                    custom1: ['String', false, false, false],
+                },
+
+                Asset: {
+                    id: ['ID', false, false, false],
+                    createdAt: ['DateTime', false, false, false],
+                    updatedAt: ['DateTime', false, false, false],
+                    name: ['String', false, false, false],
+                    type: ['AssetType', false, false, false],
+                    fileSize: ['Int', false, false, false],
+                    mimeType: ['String', false, false, false],
+                    width: ['Int', false, false, false],
+                    height: ['Int', false, false, false],
+                    source: ['String', false, false, false],
+                    preview: ['String', false, false, false],
+                    focalPoint: ['Coordinate', true, false, false],
+                    tags: ['Tag', false, true, false],
+                    customFields: ['JSON', true, false, false],
+                },
+                ProductTranslation: {
+                    id: ['ID', false, false, false],
+                    createdAt: ['DateTime', false, false, false],
+                    updatedAt: ['DateTime', false, false, false],
+                    languageCode: ['LanguageCode', false, false, false],
+                    name: ['String', false, false, false],
+                    slug: ['String', false, false, false],
+                    description: ['String', false, false, false],
+                    customFields: ['ProductTranslationCustomFields', true, false, false],
+                },
+                ProductList: {
+                    items: ['Product', false, true, false],
+                    totalItems: ['Int', false, false, false],
+                },
+
+                ProductVariantTranslation: {
+                    id: ['ID', false, false, false],
+                    createdAt: ['DateTime', false, false, false],
+                    updatedAt: ['DateTime', false, false, false],
+                    languageCode: ['LanguageCode', false, false, false],
+                    name: ['String', false, false, false],
+                },
+                Order: {
+                    id: ['ID', false, false, false],
+                    lines: ['OrderLine', false, true, false],
+                },
+                OrderLine: {
+                    id: ['ID', false, false, false],
+                    quantity: ['Int', false, false, false],
+                },
+            },
+            inputs: {
+                UpdateProductInput: {
+                    id: ['ID', false, false, false],
+                    name: ['String', false, false, false],
+                },
+                AdjustDraftOrderLineInput: {
+                    orderLineId: ['ID', false, false, false],
+                    quantity: ['Int', false, false, false],
+                },
+            },
+            scalars: [
+                'ID',
+                'String',
+                'Int',
+                'Boolean',
+                'Float',
+                'JSON',
+                'DateTime',
+                'Upload',
+                'CurrencyCode',
+            ],
+            enums: {},
+        },
+    };
+}

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

@@ -0,0 +1,99 @@
+import { globalRegistry } from '../registry/global-registry.js';
+
+import { DashboardExtension } from './extension-api-types.js';
+import {
+    registerAlertExtensions,
+    registerDataTableExtensions,
+    registerDetailFormExtensions,
+    registerFormComponentExtensions,
+    registerHistoryEntryComponents,
+    registerLayoutExtensions,
+    registerLoginExtensions,
+    registerNavigationExtensions,
+    registerWidgetExtensions,
+} from './logic/index.js';
+
+globalRegistry.register('extensionSourceChangeCallbacks', new Set<() => void>());
+globalRegistry.register('registerDashboardExtensionCallbacks', new Set<() => void>());
+
+export function onExtensionSourceChange(callback: () => void) {
+    globalRegistry.get('extensionSourceChangeCallbacks').add(callback);
+}
+
+export function executeDashboardExtensionCallbacks() {
+    for (const callback of globalRegistry.get('registerDashboardExtensionCallbacks') ?? []) {
+        callback();
+    }
+}
+
+/**
+ * @description
+ * The main entry point for extensions to the React-based dashboard. Every dashboard extension
+ * must contain a call to this function, usually in the entry point file that is referenced by
+ * the `dashboard` property of the plugin decorator.
+ *
+ * Every type of customisation of the dashboard can be defined here, including:
+ *
+ * - Navigation (nav sections and routes)
+ * - Layout (action bar items and page blocks)
+ * - Widgets
+ * - Form components (custom form components, input components, and display components)
+ * - Data tables
+ * - Detail forms
+ * - Login
+ * - Custom history entries
+ *
+ * @example
+ * ```tsx
+ * defineDashboardExtension({
+ *  navSections: [],
+ *  routes: [],
+ *  pageBlocks: [],
+ *  actionBarItems: [],
+ * });
+ * ```
+ *
+ *
+ * @docsCategory extensions-api
+ * @docsPage defineDashboardExtension
+ * @docsWeight 0
+ * @since 3.3.0
+ */
+export function defineDashboardExtension(extension: DashboardExtension) {
+    globalRegistry.get('registerDashboardExtensionCallbacks').add(() => {
+        // 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);
+
+        // Register custom history entry components
+        registerHistoryEntryComponents(extension.historyEntries);
+
+        // Execute extension source change callbacks
+        const callbacks = globalRegistry.get('extensionSourceChangeCallbacks');
+        if (callbacks.size) {
+            for (const callback of callbacks) {
+                callback();
+            }
+        }
+    });
+}

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

@@ -0,0 +1,58 @@
+import { BooleanDisplayBadge, BooleanDisplayCheckbox } from '@/vdb/components/data-display/boolean.js';
+import { DateTime } from '@/vdb/components/data-display/date-time.js';
+import { Json } from '@/vdb/components/data-display/json.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';
+import { DataTableDisplayComponent } from './types/data-table.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);
+displayComponents.set('vendure:json', Json);
+
+export function getDisplayComponent(id: string): DataDisplayComponent | undefined {
+    return globalRegistry.get('displayComponents').get(id) as DataDisplayComponent | undefined;
+}
+
+/**
+ * @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: DataDisplayComponent | DataTableDisplayComponent;
+}) {
+    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

@@ -0,0 +1,92 @@
+// Import types for the main interface
+import {
+    DashboardActionBarItem,
+    DashboardAlertDefinition,
+    DashboardCustomFormComponents,
+    DashboardDataTableExtensionDefinition,
+    DashboardDetailFormExtensionDefinition,
+    DashboardHistoryEntryComponent,
+    DashboardLoginExtensions,
+    DashboardNavSectionDefinition,
+    DashboardPageBlockDefinition,
+    DashboardRouteDefinition,
+    DashboardWidgetDefinition,
+} from './types/index.js';
+
+/**
+ * @description
+ * This is the main interface for defining _all_ extensions to the dashboard.
+ *
+ * Every type of customisation of the dashboard can be defined here, including:
+ *
+ * - Navigation (nav sections and routes)
+ * - Layout (action bar items and page blocks)
+ * - Widgets for the Insights page
+ * - Form components
+ * - Data tables
+ * - Detail forms
+ * - Login page customisation
+ *
+ * @docsCategory extensions-api
+ * @docsPage defineDashboardExtension
+ * @since 3.3.0
+ */
+export interface DashboardExtension {
+    /**
+     * @description
+     * Allows you to define custom routes such as list or detail views.
+     */
+    routes?: DashboardRouteDefinition[];
+    /**
+     * @description
+     * Allows you to define custom nav sections for the dashboard.
+     */
+    navSections?: DashboardNavSectionDefinition[];
+    /**
+     * @description
+     * Allows you to define custom page blocks for any page in the dashboard.
+     */
+    pageBlocks?: DashboardPageBlockDefinition[];
+    /**
+     * @description
+     * Allows you to define custom action bar items for any page in the dashboard.
+     */
+    actionBarItems?: DashboardActionBarItem[];
+    /**
+     * @description
+     * Allows you to define custom alerts that can be displayed in the dashboard.
+     */
+    alerts?: DashboardAlertDefinition[];
+    /**
+     * @description
+     * Allows you to define custom routes for the dashboard, which will render the
+     * 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;
+    /**
+     * @description
+     * Allows a custom component to be used to render a history entry item
+     * in the Order or Customer history lists.
+     */
+    historyEntries?: DashboardHistoryEntryComponent[];
+}

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

@@ -0,0 +1,96 @@
+import { CombinationModeInput } from '@/vdb/components/data-input/combination-mode-input.js';
+import { DefaultRelationInput } from '@/vdb/components/data-input/default-relation-input.js';
+import {
+    CustomerGroupInput,
+    FacetValueInput,
+    MoneyInput,
+    ProductMultiInput,
+    RichTextInput,
+    SelectWithOptions,
+} from '@/vdb/components/data-input/index.js';
+import { PasswordFormInput } from '@/vdb/components/data-input/password-form-input.js';
+import { TextareaInput } from '@/vdb/components/data-input/textarea-input.js';
+import { DashboardFormComponent } from '@/vdb/framework/form-engine/form-engine-types.js';
+import { globalRegistry } from '../registry/global-registry.js';
+
+globalRegistry.register('inputComponents', new Map<string, DashboardFormComponent>());
+
+const DefaultProductInput: DashboardFormComponent = props => (
+    <DefaultRelationInput {...props} entityType="ProductVariant" />
+);
+DefaultProductInput.metadata = { isListInput: 'dynamic' };
+
+// Register built-in input components
+const inputComponents = globalRegistry.get('inputComponents');
+inputComponents.set('facet-value-input', FacetValueInput);
+inputComponents.set('combination-mode-input', CombinationModeInput);
+inputComponents.set('product-multi-input', ProductMultiInput);
+inputComponents.set('currency-form-input', MoneyInput);
+inputComponents.set('customer-group-form-input', CustomerGroupInput);
+inputComponents.set('facet-value-form-input', FacetValueInput);
+inputComponents.set('json-editor-form-input', TextareaInput);
+inputComponents.set('textarea-form-input', TextareaInput);
+inputComponents.set('html-editor-form-input', RichTextInput);
+inputComponents.set('rich-text-form-input', RichTextInput);
+inputComponents.set('password-form-input', PasswordFormInput);
+inputComponents.set('product-selector-form-input', DefaultProductInput);
+inputComponents.set('relation-form-input', DefaultRelationInput);
+inputComponents.set('select-form-input', SelectWithOptions);
+inputComponents.set('product-multi-form-input', ProductMultiInput);
+inputComponents.set('combination-mode-form-input', CombinationModeInput);
+
+export function getInputComponent(id: string | undefined): DashboardFormComponent | undefined {
+    if (!id) {
+        return undefined;
+    }
+    const inputComponent = globalRegistry.get('inputComponents').get(id);
+    return inputComponent;
+}
+
+/**
+ * @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: DashboardFormComponent;
+}) {
+    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);
+}
+
+export function addCustomFieldInputComponent({
+    id,
+    component,
+}: {
+    id: string;
+    component: DashboardFormComponent;
+}) {
+    const inputComponents = globalRegistry.get('inputComponents');
+
+    if (inputComponents.has(id)) {
+        // eslint-disable-next-line no-console
+        console.warn(`Input component with key "${id}" is already registered and will be overwritten.`);
+    }
+    inputComponents.set(id, component);
+}

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

@@ -0,0 +1,11 @@
+import { registerAlert } from '@/vdb/framework/alert/alert-extensions.js';
+
+import { DashboardAlertDefinition } from '../types/alerts.js';
+
+export function registerAlertExtensions(alerts?: DashboardAlertDefinition[]) {
+    if (alerts) {
+        for (const alert of alerts) {
+            registerAlert(alert);
+        }
+    }
+}

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

@@ -0,0 +1,37 @@
+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';
+
+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) {
+                    const blockId = dataTable.blockId ?? 'list-table';
+                    const { pageId } = dataTable;
+                    const { column, component } = displayComponent;
+                    addDisplayComponent({ pageId, blockId, field: column, component });
+                }
+            }
+        }
+    }
+}

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

@@ -0,0 +1,35 @@
+import { addDetailQueryDocument } from '@/vdb/framework/form-engine/custom-form-component-extensions.js';
+import { parse } from 'graphql';
+
+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,
+                    });
+                }
+            }
+        }
+    }
+}

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

@@ -0,0 +1,14 @@
+import { addCustomFieldInputComponent } from '@/vdb/framework/extension-api/input-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) {
+                addCustomFieldInputComponent(component);
+            }
+        }
+    }
+}

package/src/lib/framework/extension-api/logic/history-entries.ts

@@ -0,0 +1,24 @@
+import { DashboardHistoryEntryComponent } from '@/vdb/framework/extension-api/types/index.js';
+
+import { globalRegistry } from '../../registry/global-registry.js';
+
+export function registerHistoryEntryComponents(
+    historyEntryComponents: DashboardHistoryEntryComponent[] = [],
+) {
+    if (historyEntryComponents.length === 0) {
+        return;
+    }
+    globalRegistry.set('historyEntries', entryMap => {
+        for (const entry of historyEntryComponents) {
+            const existingEntry = entryMap.get(entry.type);
+            if (existingEntry) {
+                // eslint-disable-next-line no-console
+                console.warn(
+                    `The history entry type ${entry.type} already has a custom component registered (${String(existingEntry)}`,
+                );
+            }
+            entryMap.set(entry.type, entry.component);
+        }
+        return entryMap;
+    });
+}

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

@@ -0,0 +1,10 @@
+// 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 './history-entries.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);
+        }
+    }
+}