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

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

@@ -0,0 +1,32 @@
+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
+ * @since 3.4.0
+ */
+export interface DashboardCustomFormComponent {
+    id: string;
+    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
+ * @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,8 @@
+// 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 './navigation.js';
+export * from './widgets.js';

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

@@ -0,0 +1,78 @@
+import type React from 'react';
+
+import { PageContextValue } from '../../layout-engine/page-provider.js';
+
+export interface ActionBarButtonState {
+    disabled: boolean;
+    visible: boolean;
+}
+
+/**
+ * @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[];
+}

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

@@ -0,0 +1,19 @@
+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';
+
+export interface DashboardRouteDefinition {
+    component: (route: AnyRoute) => React.ReactNode;
+    path: string;
+    navMenuItem?: Partial<NavMenuItem> & { sectionId: string };
+    loader?: RouteOptions['loader'];
+}
+
+export interface DashboardNavSectionDefinition {
+    id: string;
+    title: string;
+    icon?: LucideIcon;
+    order?: number;
+}

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

@@ -0,0 +1,94 @@
+import type React from 'react';
+
+/**
+ * @description
+ * **Status: Developer Preview**
+ *
+ * Base props interface for dashboard widgets.
+ *
+ * @docsCategory extensions
+ * @since 3.3.0
+ */
+export interface DashboardBaseWidgetProps {
+    widgetId: string;
+    config?: Record<string, unknown>;
+}
+
+/**
+ * @description
+ * **Status: Developer Preview**
+ *
+ * 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/form-engine/form-schema-tools.ts

@@ -2,7 +2,7 @@ import {
     FieldInfo,
     isEnumType,
     isScalarType,
-} from '@/framework/document-introspection/get-document-structure.js';
+} from '@/vdb/framework/document-introspection/get-document-structure.js';
 import { z, ZodRawShape, ZodType, ZodTypeAny } from 'zod';
 
 export function createFormSchemaFromFields(fields: FieldInfo[]) {

package/src/lib/framework/layout-engine/location-wrapper.tsx

@@ -1,10 +1,10 @@
-import { CopyableText } from '@/components/shared/copyable-text.js';
-import { Button } from '@/components/ui/button.js';
-import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover.js';
-import { usePage } from '@/hooks/use-page.js';
-import { useUserSettings } from '@/hooks/use-user-settings.js';
-import { cn } from '@/lib/utils.js';
-import { Trans } from '@/lib/trans.js';
+import { CopyableText } from '@/vdb/components/shared/copyable-text.js';
+import { Button } from '@/vdb/components/ui/button.js';
+import { Popover, PopoverContent, PopoverTrigger } from '@/vdb/components/ui/popover.js';
+import { usePage } from '@/vdb/hooks/use-page.js';
+import { useUserSettings } from '@/vdb/hooks/use-user-settings.js';
+import { Trans } from '@/vdb/lib/trans.js';
+import { cn } from '@/vdb/lib/utils.js';
 import { CodeXmlIcon, InfoIcon } from 'lucide-react';
 import { createContext, useContext, useState } from 'react';
 

package/src/lib/framework/layout-engine/page-block-provider.tsx

@@ -1,4 +1,4 @@
-import { PageBlockProps } from '@/framework/layout-engine/page-layout.js';
+import { PageBlockProps } from '@/vdb/framework/layout-engine/page-layout.js';
 import { createContext } from 'react';
 
 export type PageBlockContextValue = Pick<PageBlockProps, 'blockId' | 'column' | 'title' | 'description'>;

package/src/lib/framework/layout-engine/page-layout.tsx

@@ -1,19 +1,19 @@
-import { CustomFieldsForm } from '@/components/shared/custom-fields-form.js';
-import { NavigationConfirmation } from '@/components/shared/navigation-confirmation.js';
-import { PermissionGuard } from '@/components/shared/permission-guard.js';
-import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card.js';
-import { Form } from '@/components/ui/form.js';
-import { useCustomFieldConfig } from '@/hooks/use-custom-field-config.js';
-import { usePage } from '@/hooks/use-page.js';
-import { cn } from '@/lib/utils.js';
+import { CustomFieldsForm } from '@/vdb/components/shared/custom-fields-form.js';
+import { NavigationConfirmation } from '@/vdb/components/shared/navigation-confirmation.js';
+import { PermissionGuard } from '@/vdb/components/shared/permission-guard.js';
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/vdb/components/ui/card.js';
+import { Form } from '@/vdb/components/ui/form.js';
+import { useCustomFieldConfig } from '@/vdb/hooks/use-custom-field-config.js';
+import { usePage } from '@/vdb/hooks/use-page.js';
+import { cn } from '@/vdb/lib/utils.js';
 import { useMediaQuery } from '@uidotdev/usehooks';
 import React, { ComponentProps } from 'react';
 import { Control, UseFormReturn } from 'react-hook-form';
 
 import { DashboardActionBarItem } from '../extension-api/extension-api-types.js';
 
-import { PageBlockContext } from '@/framework/layout-engine/page-block-provider.js';
-import { PageContext, PageContextValue } from '@/framework/layout-engine/page-provider.js';
+import { PageBlockContext } from '@/vdb/framework/layout-engine/page-block-provider.js';
+import { PageContext, PageContextValue } from '@/vdb/framework/layout-engine/page-provider.js';
 import { getDashboardActionBarItems, getDashboardPageBlocks } from './layout-extensions.js';
 import { LocationWrapper } from './location-wrapper.js';
 

package/src/lib/framework/page/detail-page-route-loader.tsx

@@ -1,7 +1,7 @@
-import { NEW_ENTITY_PATH } from '@/constants.js';
+import { NEW_ENTITY_PATH } from '@/vdb/constants.js';
 
-import { PageBreadcrumb } from '@/components/layout/generated-breadcrumbs.js';
-import { extendDetailFormQuery } from '@/framework/document-extension/extend-detail-form-query.js';
+import { PageBreadcrumb } from '@/vdb/components/layout/generated-breadcrumbs.js';
+import { extendDetailFormQuery } from '@/vdb/framework/document-extension/extend-detail-form-query.js';
 import { TypedDocumentNode } from '@graphql-typed-document-node/core';
 import { FileBaseRouteOptions, ParsedLocation } from '@tanstack/react-router';
 import { addCustomFields } from '../document-introspection/add-custom-fields.js';

package/src/lib/framework/page/detail-page.tsx

@@ -1,21 +1,25 @@
-import { DateTimeInput } from '@/components/data-input/datetime-input.js';
-import { FormFieldWrapper } from '@/components/shared/form-field-wrapper.js';
-import { Button } from '@/components/ui/button.js';
-import { Checkbox } from '@/components/ui/checkbox.js';
-import { Input } from '@/components/ui/input.js';
-import { NEW_ENTITY_PATH } from '@/constants.js';
-import { useDetailPage } from '@/framework/page/use-detail-page.js';
-import { Trans } from '@/lib/trans.js';
+import { DateTimeInput } from '@/vdb/components/data-input/datetime-input.js';
+import { FormFieldWrapper } from '@/vdb/components/shared/form-field-wrapper.js';
+import { Button } from '@/vdb/components/ui/button.js';
+import { Checkbox } from '@/vdb/components/ui/checkbox.js';
+import { Input } from '@/vdb/components/ui/input.js';
+import { NEW_ENTITY_PATH } from '@/vdb/constants.js';
+import { useDetailPage } from '@/vdb/framework/page/use-detail-page.js';
+import { Trans } from '@/vdb/lib/trans.js';
 import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
 import { AnyRoute, useNavigate } from '@tanstack/react-router';
 import { ResultOf, VariablesOf } from 'gql.tada';
 import { toast } from 'sonner';
 import {
+    FieldInfo,
     getEntityName,
     getOperationVariablesFields,
 } from '../document-introspection/get-document-structure.js';
 
-import { TranslatableFormFieldWrapper } from '@/components/shared/translatable-form-field.js';
+import { TranslatableFormFieldWrapper } from '@/vdb/components/shared/translatable-form-field.js';
+import { ControllerRenderProps, FieldPath, FieldValues } from 'react-hook-form';
+import { useComponentRegistry } from '../component-registry/component-registry.js';
+import { generateInputComponentKey } from '../extension-api/input-component-extensions.js';
 import {
     CustomFieldsPageBlock,
     DetailFormGrid,
@@ -85,10 +89,37 @@ export interface DetailPageProps<
     setValuesForUpdate: (entity: ResultOf<T>[EntityField]) => VariablesOf<U>['input'];
 }
 
+export interface DetailPageFieldProps<
+    TFieldValues extends FieldValues = FieldValues,
+    TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+> {
+    fieldInfo: FieldInfo;
+    field: ControllerRenderProps<TFieldValues, TName>;
+    blockId: string;
+    pageId: string;
+}
+
 /**
  * Renders form input components based on field type
  */
-function renderFieldInput(fieldInfo: { type: string }, field: any) {
+function FieldInputRenderer<
+    TFieldValues extends FieldValues = FieldValues,
+    TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+>({ fieldInfo, field, blockId, pageId }: DetailPageFieldProps<TFieldValues, TName>) {
+    const componentRegistry = useComponentRegistry();
+    const customInputComponentKey = generateInputComponentKey(pageId, blockId, fieldInfo.name);
+
+    const DisplayComponent = componentRegistry.getDisplayComponent(customInputComponentKey);
+    const InputComponent = componentRegistry.getInputComponent(customInputComponentKey);
+
+    if (DisplayComponent) {
+        return <DisplayComponent {...field} />;
+    }
+
+    if (InputComponent) {
+        return <InputComponent {...field} />;
+    }
+
     switch (fieldInfo.type) {
         case 'Int':
         case 'Float':
@@ -196,7 +227,14 @@ export function DetailPage<
                                         control={form.control}
                                         name={fieldInfo.name as never}
                                         label={fieldInfo.name}
-                                        render={({ field }) => renderFieldInput(fieldInfo, field)}
+                                        render={({ field }) => (
+                                            <FieldInputRenderer
+                                                fieldInfo={fieldInfo}
+                                                field={field}
+                                                blockId="main-form"
+                                                pageId={pageId}
+                                            />
+                                        )}
                                     />
                                 );
                             })}
@@ -211,7 +249,14 @@ export function DetailPage<
                                         control={form.control}
                                         name={fieldInfo.name as never}
                                         label={fieldInfo.name}
-                                        render={({ field }) => renderFieldInput(fieldInfo, field)}
+                                        render={({ field }) => (
+                                            <FieldInputRenderer
+                                                fieldInfo={fieldInfo}
+                                                field={field}
+                                                blockId="main-form"
+                                                pageId={pageId}
+                                            />
+                                        )}
                                     />
                                 );
                             })}

package/src/lib/framework/page/list-page.tsx

@@ -8,16 +8,22 @@ import {
     ListQueryShape,
     PaginatedListDataTable,
     RowAction,
-} from '@/components/shared/paginated-list-data-table.js';
-import { BulkAction } from '@/framework/data-table/data-table-types.js';
-import { useUserSettings } from '@/hooks/use-user-settings.js';
+} from '@/vdb/components/shared/paginated-list-data-table.js';
+import { BulkAction } from '@/vdb/framework/data-table/data-table-types.js';
+import { useUserSettings } from '@/vdb/hooks/use-user-settings.js';
 import { TypedDocumentNode } from '@graphql-typed-document-node/core';
 import { AnyRoute, AnyRouter, useNavigate } from '@tanstack/react-router';
 import { ColumnFiltersState, SortingState, Table } from '@tanstack/react-table';
 import { TableOptions } from '@tanstack/table-core';
 
 import { addCustomFields } from '../document-introspection/add-custom-fields.js';
-import { FullWidthPageBlock, Page, PageActionBar, PageLayout, PageTitle } from '../layout-engine/page-layout.js';
+import {
+    FullWidthPageBlock,
+    Page,
+    PageActionBar,
+    PageLayout,
+    PageTitle,
+} from '../layout-engine/page-layout.js';
 
 /**
  * @description

package/src/lib/framework/page/use-detail-page.ts

@@ -1,4 +1,4 @@
-import { removeReadonlyCustomFields } from '@/lib/utils.js';
+import { removeReadonlyCustomFields } from '@/vdb/lib/utils.js';
 import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
 import {
     DefinedInitialDataOptions,

package/src/lib/framework/registry/registry-types.ts

@@ -2,6 +2,7 @@ import { DocumentNode } from 'graphql';
 import React from 'react';
 
 import { DashboardAlertDefinition } from '../alert/types.js';
+import { DataDisplayComponent, DataInputComponent } from '../component-registry/component-registry.js';
 import { DashboardWidgetDefinition } from '../dashboard-widget/types.js';
 import { BulkAction } from '../data-table/data-table-types.js';
 import {
@@ -20,6 +21,8 @@ export interface GlobalRegistryContents {
     dashboardWidgetRegistry: Map<string, DashboardWidgetDefinition>;
     dashboardAlertRegistry: Map<string, DashboardAlertDefinition>;
     customFormComponents: Map<string, React.FunctionComponent<CustomFormComponentInputProps>>;
+    inputComponents: Map<string, DataInputComponent>;
+    displayComponents: Map<string, DataDisplayComponent>;
     bulkActionsRegistry: Map<string, BulkAction[]>;
     listQueryDocumentRegistry: Map<string, DocumentNode[]>;
     detailQueryDocumentRegistry: Map<string, DocumentNode[]>;