@wilshop/dashboard 3.5.2

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

@@ -0,0 +1,76 @@
+import type React from 'react';
+
+/**
+ * @description
+ * Defines a custom logo component for the login page.
+ *
+ * @docsCategory extensions-api
+ * @docsPage Login
+ * @since 3.4.0
+ */
+export interface LoginLogoExtension {
+    /**
+     * @description
+     * A React component that will replace the default Vendure logo.
+     */
+    component: React.ComponentType;
+}
+
+/**
+ * @description
+ * Defines content to display before the login form.
+ *
+ * @docsCategory extensions-api
+ * @docsPage Login
+ * @since 3.4.0
+ */
+export interface LoginBeforeFormExtension {
+    /**
+     * @description
+     * A React component that will be rendered before the login form.
+     */
+    component: React.ComponentType;
+}
+
+/**
+ * @description
+ * Defines content to display after the login form.
+ *
+ * @docsCategory extensions-api
+ * @docsPage Login
+ * @since 3.4.0
+ */
+export interface LoginAfterFormExtension {
+    /**
+     * @description
+     * A React component that will be rendered after the login form.
+     */
+    component: React.ComponentType;
+}
+
+/**
+ * @description
+ * Defines all available login page extensions.
+ *
+ * @docsCategory extensions-api
+ * @docsPage Login
+ * @docsWeight 0
+ * @since 3.4.0
+ */
+export interface DashboardLoginExtensions {
+    /**
+     * @description
+     * Custom logo component to replace the default Vendure logo.
+     */
+    logo?: LoginLogoExtension;
+    /**
+     * @description
+     * Component to render before the login form.
+     */
+    beforeForm?: LoginBeforeFormExtension;
+    /**
+     * @description
+     * Component to render after the login form.
+     */
+    afterForm?: LoginAfterFormExtension;
+}

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

@@ -0,0 +1,105 @@
+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';
+
+/**
+ * @description
+ * Defines a custom route for the dashboard with optional navigation menu integration.
+ *
+ * @docsCategory extensions-api
+ * @docsPage Routes
+ * @since 3.4.0
+ */
+export interface DashboardRouteDefinition {
+    /**
+     * @description
+     * The React component that will be rendered for this route.
+     */
+    component: (route: AnyRoute) => React.ReactNode;
+    /**
+     * @description
+     * The URL path for this route, e.g. '/my-custom-page'.
+     */
+    path: string;
+    /**
+     * @description
+     * Optional navigation menu item configuration to add this route to the nav menu
+     * on the left side of the dashboard.
+     *
+     * The `sectionId` specifies which nav menu section (e.g. "catalog", "customers")
+     * this item should appear in. It can also point to custom nav menu sections that
+     * have been defined using the `navSections` extension property.
+     */
+    navMenuItem?: Partial<NavMenuItem> & { sectionId: string };
+    /**
+     * @description
+     * Optional loader function to fetch data before the route renders.
+     * The value is a Tanstack Router
+     * [loader function](https://tanstack.com/router/latest/docs/framework/react/guide/data-loading#route-loaders)
+     */
+    loader?: RouteOptions<any>['loader'];
+
+    /**
+     * @description
+     * Optional search parameter validation function.
+     * The value is a Tanstack Router
+     * [validateSearch function](https://tanstack.com/router/latest/docs/framework/react/guide/search-params#search-param-validation)
+     */
+    validateSearch?: RouteOptions<any>['validateSearch'];
+
+    /**
+     * @description
+     * Define if the route should be under the authentication context, i.e have the authenticated route
+     * as a parent.
+     * @default true
+     */
+    authenticated?: boolean;
+}
+
+/**
+ * @description
+ * Defines a custom navigation section in the dashboard sidebar.
+ *
+ * Individual items can then be added to the section by defining routes in the
+ * `routes` property of your Dashboard extension.
+ *
+ * @docsCategory extensions-api
+ * @docsPage Navigation
+ * @docsWeight 0
+ * @since 3.4.0
+ */
+export interface DashboardNavSectionDefinition {
+    /**
+     * @description
+     * A unique identifier for the navigation section.
+     */
+    id: string;
+    /**
+     * @description
+     * The display title for the navigation section.
+     */
+    title: string;
+    /**
+     * @description
+     * Optional icon to display next to the section title. The icons should
+     * be imported from `'lucide-react'`.
+     *
+     * @example
+     * ```ts
+     * import { PlusIcon } from 'lucide-react';
+     * ```
+     */
+    icon?: LucideIcon;
+    /**
+     * @description
+     * Optional order number to control the position of this section in the sidebar.
+     */
+    order?: number;
+    /**
+     * @description
+     * Optional placement to control the position of this section in the sidebar.
+     */
+    placement?: 'top' | 'bottom';
+}

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

@@ -0,0 +1,101 @@
+import React, { PropsWithChildren } from 'react';
+
+/**
+ * @description
+ * Base props interface for dashboard widgets.
+ *
+ * @docsCategory extensions-api
+ * @docsPage widgets
+ * @since 3.3.0
+ */
+export type DashboardBaseWidgetProps = PropsWithChildren<{
+    id: string;
+    title?: string;
+    description?: string;
+    config?: Record<string, unknown>;
+    actions?: React.ReactNode;
+}>;
+
+/**
+ * @description
+ * Represents an instance of a dashboard widget with its layout and configuration.
+ *
+ * @docsCategory extensions-api
+ * @docsPage widgets
+ * @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;
+        minW?: number;
+        minH?: number;
+        maxW?: number;
+        maxH?: 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-api
+ * @docsPage Widgets
+ * @docsWeight 0
+ * @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/extension-api/use-dashboard-extensions.ts

@@ -0,0 +1,27 @@
+import { useEffect, useState } from 'react';
+import { runDashboardExtensions } from 'virtual:dashboard-extensions';
+
+import { onExtensionSourceChange } from './define-dashboard-extension.js';
+
+/**
+ * @description
+ * This hook is used to load dashboard extensions via the `virtual:dashboard-extensions` module,
+ * which is provided by the `vite-plugin-dashboard-metadata` plugin.
+ *
+ * It should be used in any component whose rendering depends on the content of the dashboard extensions.
+ */
+export function useDashboardExtensions() {
+    const [extensionsLoaded, setExtensionsLoaded] = useState(false);
+    const [reloadCount, setReloadCount] = useState(0);
+
+    useEffect(() => {
+        void runDashboardExtensions().then(() => setExtensionsLoaded(true));
+        onExtensionSourceChange(() => {
+            // Setting this state var is only really done
+            // in order to force a re-render of components using this hook.
+            // This allows components to react to HMR events during development.
+            setReloadCount(old => old + 1);
+        });
+    }, []);
+    return { extensionsLoaded, reloadCount };
+}

package/src/lib/framework/extension-api/use-login-extensions.ts

@@ -0,0 +1,26 @@
+import { useEffect, useState } from 'react';
+
+import { globalRegistry } from '../registry/global-registry.js';
+
+import { onExtensionSourceChange } from './define-dashboard-extension.js';
+import { DashboardLoginExtensions } from './types/login.js';
+
+export function useLoginExtensions(): DashboardLoginExtensions {
+    const [extensions, setExtensions] = useState<DashboardLoginExtensions>(() => {
+        return globalRegistry.get('loginExtensions') || {};
+    });
+
+    useEffect(() => {
+        const updateExtensions = () => {
+            setExtensions(globalRegistry.get('loginExtensions') || {});
+        };
+
+        // Subscribe to extension changes
+        onExtensionSourceChange(updateExtensions);
+
+        // Update immediately in case extensions were registered before this hook was called
+        updateExtensions();
+    }, []);
+
+    return extensions;
+}

package/src/lib/framework/form-engine/custom-form-component-extensions.ts

@@ -0,0 +1,15 @@
+import { DocumentNode } from 'graphql';
+
+import { globalRegistry } from '../registry/global-registry.js';
+
+globalRegistry.register('detailQueryDocumentRegistry', new Map<string, DocumentNode[]>());
+
+export function getDetailQueryDocuments(pageId: string): DocumentNode[] {
+    return globalRegistry.get('detailQueryDocumentRegistry').get(pageId) || [];
+}
+
+export function addDetailQueryDocument(pageId: string, document: DocumentNode) {
+    const listQueryDocumentRegistry = globalRegistry.get('detailQueryDocumentRegistry');
+    const existingDocuments = listQueryDocumentRegistry.get(pageId) || [];
+    listQueryDocumentRegistry.set(pageId, [...existingDocuments, document]);
+}

package/src/lib/framework/form-engine/custom-form-component.tsx

@@ -0,0 +1,16 @@
+import { getInputComponent } from '@/vdb/framework/extension-api/input-component-extensions.js';
+
+import { DashboardFormComponentProps } from '@/vdb/framework/form-engine/form-engine-types.js';
+
+export function CustomFormComponent(props: DashboardFormComponentProps) {
+    if (!props.fieldDef) {
+        return null;
+    }
+    const Component = getInputComponent(props.fieldDef.ui?.component);
+
+    if (!Component) {
+        return null;
+    }
+
+    return <Component {...props} />;
+}

package/src/lib/framework/form-engine/default-input-for-type.tsx

@@ -0,0 +1,35 @@
+import { BooleanInput } from '@/vdb/components/data-input/boolean-input.js';
+import { DefaultRelationInput } from '@/vdb/components/data-input/default-relation-input.js';
+import { DateTimeInput, SelectWithOptions } from '@/vdb/components/data-input/index.js';
+import { NumberInput } from '@/vdb/components/data-input/number-input.js';
+import { TextInput } from '@/vdb/components/data-input/text-input.js';
+import { DashboardFormComponentProps } from '@/vdb/framework/form-engine/form-engine-types.js';
+import { isStringFieldWithOptions } from '@/vdb/framework/form-engine/utils.js';
+
+/**
+ * Consolidated input component for rendering form inputs based on field type
+ * This replaces the duplicate implementations in custom fields and config args
+ */
+export function DefaultInputForType({ fieldDef, ...fieldProps }: Readonly<DashboardFormComponentProps>) {
+    const type = fieldDef?.type;
+    switch (type) {
+        case 'int':
+        case 'float':
+            return <NumberInput {...fieldProps} fieldDef={fieldDef} />;
+        case 'boolean':
+            return <BooleanInput {...fieldProps} fieldDef={fieldDef} />;
+        case 'datetime':
+            return <DateTimeInput {...fieldProps} fieldDef={fieldDef} />;
+        case 'relation':
+            return <DefaultRelationInput {...fieldProps} fieldDef={fieldDef} />;
+        case 'string': {
+            if (fieldDef && isStringFieldWithOptions(fieldDef)) {
+                return <SelectWithOptions {...fieldProps} fieldDef={fieldDef} />;
+            } else {
+                return <TextInput {...fieldProps} fieldDef={fieldDef} />;
+            }
+        }
+        default:
+            return <TextInput {...fieldProps} fieldDef={fieldDef} />;
+    }
+}

package/src/lib/framework/form-engine/form-control-adapter.tsx

@@ -0,0 +1,193 @@
+import { JSX, useMemo } from 'react';
+import { ControllerRenderProps } from 'react-hook-form';
+
+import { CustomFieldListInput } from '@/vdb/components/data-input/custom-field-list-input.js';
+import { StringListInput } from '@/vdb/components/data-input/string-list-input.js';
+import { StructFormInput } from '@/vdb/components/data-input/struct-form-input.js';
+import { ConfigurableOperationListInput } from '../../components/data-input/configurable-operation-list-input.js';
+
+import { getInputComponent } from '@/vdb/framework/extension-api/input-component-extensions.js';
+import {
+    ConfigurableFieldDef,
+    DashboardFormComponent,
+} from '@/vdb/framework/form-engine/form-engine-types.js';
+import { isCustomFieldConfig } from '@/vdb/framework/form-engine/utils.js';
+import { DefaultInputForType } from './default-input-for-type.js';
+import { transformValue, ValueMode } from './value-transformers.js';
+
+export interface FormControlAdapterProps {
+    fieldDef: ConfigurableFieldDef;
+    field: ControllerRenderProps<any, any>;
+    valueMode: ValueMode;
+}
+
+/**
+ * Gets the default value for list inputs based on field type
+ */
+function getDefaultValueForType(fieldType: string): any {
+    switch (fieldType) {
+        case 'string':
+        case 'localeString':
+        case 'localeText':
+            return '';
+        case 'int':
+        case 'float':
+            return 0;
+        case 'boolean':
+            return false;
+        default:
+            return '';
+    }
+}
+
+/**
+ * Validates if a custom component is correctly configured for list fields
+ */
+function validateCustomComponent(
+    CustomComponent: any,
+    componentId: string,
+    fieldName: string,
+    isList: boolean,
+): void {
+    if (!CustomComponent.metadata?.isListInput || CustomComponent.metadata.isListInput === 'dynamic') {
+        return;
+    }
+
+    const isConfiguredForList = CustomComponent.metadata.isListInput === true;
+    if (isConfiguredForList !== isList) {
+        // eslint-disable-next-line no-console
+        console.warn([
+            `Custom component ${componentId} is not correctly configured for the ${fieldName} field:`,
+            `The component ${isConfiguredForList ? 'is' : 'is not'} configured as a list input, but the field ${isList ? 'is' : 'is not'} a list field.`,
+        ]);
+    }
+}
+
+/**
+ * Determines if a custom component can be used for the given field configuration
+ */
+function canUseCustomComponent(
+    CustomComponent: DashboardFormComponent | undefined,
+    isList: boolean,
+): CustomComponent is DashboardFormComponent {
+    if (!CustomComponent) return false;
+
+    const listInputMode = CustomComponent.metadata?.isListInput;
+
+    // Dynamic components can handle both list and non-list
+    if (listInputMode === 'dynamic') return true;
+
+    // Exact match: both are list or both are non-list
+    return (isList && listInputMode === true) || (!isList && listInputMode !== true);
+}
+
+/**
+ * Renders struct field inputs
+ */
+function renderStructField(
+    fieldDef: ConfigurableFieldDef,
+    field: ControllerRenderProps<any, any>,
+    fieldWithTransform: ControllerRenderProps<any, any>,
+    isList: boolean,
+    isReadonly: boolean,
+): JSX.Element {
+    if (isList) {
+        return (
+            <CustomFieldListInput
+                {...field}
+                disabled={isReadonly}
+                renderInput={(index, inputField) => (
+                    <StructFormInput {...fieldWithTransform} fieldDef={fieldDef} />
+                )}
+                defaultValue={{}}
+            />
+        );
+    }
+    return <StructFormInput {...fieldWithTransform} fieldDef={fieldDef} />;
+}
+
+/**
+ * Renders list field inputs
+ */
+function renderListField(
+    fieldDef: ConfigurableFieldDef,
+    field: ControllerRenderProps<any, any>,
+    fieldWithTransform: ControllerRenderProps<any, any>,
+    valueMode: ValueMode,
+    isReadonly: boolean,
+): JSX.Element {
+    if (valueMode === 'json-string') {
+        return <ConfigurableOperationListInput {...fieldWithTransform} fieldDef={fieldDef} />;
+    }
+
+    if (fieldDef.type === 'relation') {
+        return <DefaultInputForType {...fieldWithTransform} fieldDef={fieldDef} />;
+    }
+
+    if (fieldDef.type === 'string') {
+        return <StringListInput {...fieldWithTransform} fieldDef={fieldDef} />;
+    }
+
+    return (
+        <CustomFieldListInput
+            {...field}
+            disabled={isReadonly}
+            renderInput={(index, inputField) => <DefaultInputForType {...inputField} fieldDef={fieldDef} />}
+            defaultValue={getDefaultValueForType(fieldDef.type)}
+        />
+    );
+}
+
+/**
+ * This is a wrapper component around the final DashboardFormComponent instances.
+ *
+ * It is responsible for ensuring the correct props get passed to the final component,
+ * and for handling differences between form control use between:
+ *
+ * - Auto-generated forms
+ * - Custom field forms
+ * - Configurable operation forms
+ */
+export function FormControlAdapter({ fieldDef, field, valueMode }: Readonly<FormControlAdapterProps>) {
+    const isList = fieldDef.list ?? false;
+    const isReadonly = isCustomFieldConfig(fieldDef) ? fieldDef.readonly === true : false;
+    const componentId = fieldDef.ui?.component as string | undefined;
+
+    const fieldWithTransform = useMemo(() => {
+        const fieldOnChange = field.onChange.bind(field);
+        const transformedField: FormControlAdapterProps['field'] = {
+            ...field,
+            value: transformValue(field.value, fieldDef, valueMode, 'parse'),
+            onChange: (newValue: any) => {
+                const serializedValue = transformValue(newValue, fieldDef, valueMode, 'serialize');
+                fieldOnChange(serializedValue);
+            },
+        };
+        return transformedField;
+    }, [field.name, field.value, field.onChange, fieldDef, valueMode]);
+
+    const CustomComponent = getInputComponent(componentId);
+
+    // Try to use custom component if available and compatible
+    if (canUseCustomComponent(CustomComponent, isList)) {
+        return <CustomComponent {...fieldWithTransform} fieldDef={fieldDef} />;
+    }
+
+    // Validate custom component configuration for debugging
+    if (CustomComponent) {
+        validateCustomComponent(CustomComponent, componentId!, fieldDef.name, isList);
+    }
+
+    // Handle struct fields (custom fields mode only)
+    if (fieldDef.type === 'struct' && valueMode === 'native') {
+        return renderStructField(fieldDef, field, fieldWithTransform, isList, isReadonly);
+    }
+
+    // Handle list fields
+    if (isList) {
+        return renderListField(fieldDef, field, fieldWithTransform, valueMode, isReadonly);
+    }
+
+    // Default case: non-list, non-struct fields
+    return <DefaultInputForType {...fieldWithTransform} fieldDef={fieldDef} />;
+}