@vendure/dashboard 3.4.0-minor-202506250934 → 3.4.0

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

@@ -0,0 +1,96 @@
+import type React from 'react';
+
+/**
+ * @description
+ * Defines a custom logo component for the login page.
+ *
+ * @docsCategory extensions
+ * @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
+ * @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
+ * @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 a custom login image component that replaces the default image panel.
+ *
+ * @docsCategory extensions
+ * @docsPage Login
+ * @since 3.4.0
+ */
+export interface LoginImageExtension {
+    /**
+     * @description
+     * A React component that will replace the default login image panel.
+     */
+    component: React.ComponentType;
+}
+
+/**
+ * @description
+ * Defines all available login page extensions.
+ *
+ * @docsCategory extensions
+ * @docsPage Login
+ * @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;
+    /**
+     * @description
+     * Custom login image component to replace the default image panel.
+     */
+    loginImage?: LoginImageExtension;
+}

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

@@ -0,0 +1,76 @@
+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
+ * @docsPage Navigation
+ * @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.
+     */
+    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['loader'];
+}
+
+/**
+ * @description
+ * Defines a custom navigation section in the dashboard sidebar.
+ *
+ * @docsCategory extensions
+ * @docsPage Navigation
+ * @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;
+}

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

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

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

@@ -1,7 +1,8 @@
-import { onExtensionSourceChange } from '@/framework/extension-api/define-dashboard-extension.js';
 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,

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,38 @@
+import { DocumentNode } from 'graphql';
+
+import { DashboardCustomFormComponent } from '../extension-api/extension-api-types.js';
+import { globalRegistry } from '../registry/global-registry.js';
+
+import { CustomFormComponentInputProps } from './custom-form-component.js';
+
+globalRegistry.register(
+    'customFormComponents',
+    new Map<string, React.FunctionComponent<CustomFormComponentInputProps>>(),
+);
+
+globalRegistry.register('detailQueryDocumentRegistry', new Map<string, DocumentNode[]>());
+
+export function getCustomFormComponent(
+    id: string,
+): React.FunctionComponent<CustomFormComponentInputProps> | undefined {
+    return globalRegistry.get('customFormComponents').get(id);
+}
+
+export function addCustomFormComponent({ id, component }: DashboardCustomFormComponent) {
+    const customFormComponents = globalRegistry.get('customFormComponents');
+    if (customFormComponents.has(id)) {
+        // eslint-disable-next-line no-console
+        console.warn(`Custom form component with id "${id}" is already registered and will be overwritten.`);
+    }
+    customFormComponents.set(id, component);
+}
+
+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,33 @@
+import { CustomFieldConfig } from '@vendure/common/lib/generated-types';
+import {
+    ControllerFieldState,
+    ControllerRenderProps,
+    FieldPath,
+    FieldValues,
+    UseFormStateReturn,
+} from 'react-hook-form';
+import { getCustomFormComponent } from './custom-form-component-extensions.js';
+
+export interface CustomFormComponentProps {
+    fieldProps: CustomFormComponentInputProps;
+    fieldDef: Pick<CustomFieldConfig, 'ui' | 'type' | 'name'>;
+}
+
+export interface CustomFormComponentInputProps<
+    TFieldValues extends FieldValues = FieldValues,
+    TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+> {
+    field: ControllerRenderProps<TFieldValues, TName>;
+    fieldState: ControllerFieldState;
+    formState: UseFormStateReturn<TFieldValues>;
+}
+
+export function CustomFormComponent({ fieldDef, fieldProps }: CustomFormComponentProps) {
+    const Component = getCustomFormComponent(fieldDef.ui?.component);
+
+    if (!Component) {
+        return null;
+    }
+
+    return <Component {...fieldProps} />;
+}