@vendure/dashboard 3.3.6-master-202507041203 → 3.4.0-minor-202506250934

package/src/lib/framework/dashboard-widget/latest-orders-widget/index.tsx

@@ -1,13 +1,13 @@
-import { PaginatedListDataTable } from '@/vdb/components/shared/paginated-list-data-table.js';
-import { Button } from '@/vdb/components/ui/button.js';
-import { useLocalFormat } from '@/vdb/hooks/use-local-format.js';
+import { useQuery } from '@tanstack/react-query';
+import { latestOrdersQuery } from './latest-orders-widget.graphql.js';
+import { DashboardBaseWidget } from '../base-widget.js';
+import { PaginatedListDataTable, addCustomFields, useLocalFormat } from '@/index.js';
+import { ColumnFiltersState } from '@tanstack/react-table';
+import { useState } from 'react';
+import { SortingState } from '@tanstack/react-table';
 import { Link } from '@tanstack/react-router';
-import { ColumnFiltersState, SortingState } from '@tanstack/react-table';
 import { formatRelative } from 'date-fns';
-import { useState } from 'react';
-import { DashboardBaseWidget } from '../base-widget.js';
-import { latestOrdersQuery } from './latest-orders-widget.graphql.js';
-
+import { Button } from '@/components/ui/button.js';
 export const WIDGET_ID = 'latest-orders-widget';
 
 export function LatestOrdersWidget() {

package/src/lib/framework/dashboard-widget/latest-orders-widget/latest-orders-widget.graphql.ts

@@ -1,4 +1,4 @@
-import { graphql } from '@/vdb/graphql/graphql.js';
+import { graphql } from '@/graphql/graphql.js';
 
 export const latestOrderItemFragment = graphql(`
     fragment LatestOrderItem on Order {

package/src/lib/framework/dashboard-widget/metrics-widget/index.tsx

@@ -1,12 +1,13 @@
-import { Tabs, TabsList, TabsTrigger } from '@/vdb/components/ui/tabs.js';
-import { api } from '@/vdb/graphql/api.js';
-import { useChannel } from '@/vdb/hooks/use-channel.js';
-import { useLocalFormat } from '@/vdb/hooks/use-local-format.js';
+import { api } from '@/graphql/api.js';
 import { useQuery } from '@tanstack/react-query';
 import { useMemo, useState } from 'react';
-import { DashboardBaseWidget } from '../base-widget.js';
-import { MetricsChart } from './chart.js';
+import { Area, AreaChart, CartesianGrid, Tooltip, XAxis, YAxis } from 'recharts';
+import { DashboardBaseWidget, useWidgetDimensions } from '../base-widget.js';
 import { orderChartDataQuery } from './metrics-widget.graphql.js';
+import { MetricsChart } from './chart.js';
+import { useLocalFormat } from '@/hooks/use-local-format.js';
+import { useChannel } from '@/hooks/use-channel.js';
+import { Tabs, TabsList, TabsTrigger } from '@/components/ui/tabs.js';
 
 enum DATA_TYPES {
     OrderCount = 'OrderCount',

package/src/lib/framework/dashboard-widget/metrics-widget/metrics-widget.graphql.ts

@@ -1,4 +1,4 @@
-import { graphql } from '@/vdb/graphql/graphql.js';
+import { graphql } from '@/graphql/graphql.js';
 
 export const orderChartDataQuery = graphql(`
     query GetOrderChartData($refresh: Boolean, $types: [MetricType!]!) {

package/src/lib/framework/dashboard-widget/orders-summary/index.tsx

@@ -1,13 +1,12 @@
-import { AnimatedCurrency, AnimatedNumber } from '@/vdb/components/shared/animated-number.js';
-import { Tabs, TabsList, TabsTrigger } from '@/vdb/components/ui/tabs.js';
-import { api } from '@/vdb/graphql/api.js';
-import { useChannel } from '@/vdb/hooks/use-channel.js';
-import { useLocalFormat } from '@/vdb/hooks/use-local-format.js';
 import { useQuery } from '@tanstack/react-query';
-import { endOfDay, endOfMonth, startOfDay, startOfMonth, subDays, subMonths } from 'date-fns';
-import { useMemo, useState } from 'react';
 import { DashboardBaseWidget } from '../base-widget.js';
 import { orderSummaryQuery } from './order-summary-widget.graphql.js';
+import { api } from '@/graphql/api.js';
+import { useMemo, useState } from 'react';
+import { Tabs, TabsList, TabsTrigger } from '@/components/ui/tabs.js';
+import { useChannel, useLocalFormat } from '@/index.js';
+import { startOfDay, endOfDay, subDays, subMonths, startOfMonth, endOfMonth } from 'date-fns';
+import { AnimatedCurrency, AnimatedNumber } from '@/components/shared/animated-number.js';
 
 const WIDGET_ID = 'orders-summary-widget';
 

package/src/lib/framework/dashboard-widget/orders-summary/order-summary-widget.graphql.ts

@@ -1,4 +1,4 @@
-import { graphql } from '@/vdb/graphql/graphql.js';
+import { graphql } from '@/graphql/graphql.js';
 
 export const orderSummaryQuery = graphql(`
     query GetOrderSummary($start: DateTime!, $end: DateTime!) {

package/src/lib/framework/dashboard-widget/types.ts

@@ -0,0 +1,22 @@
+import { DashboardBaseWidgetProps } from './base-widget.js';
+
+export type DashboardWidgetInstance = {
+    id: string;
+    widgetId: string;
+    layout: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    config?: Record<string, unknown>;
+};
+
+export type DashboardWidgetDefinition = {
+    id: string;
+    name: string;
+    component: React.ComponentType<DashboardBaseWidgetProps>;
+    defaultSize: { w: number; h: number; x?: number; y?: number };
+    minSize?: { w: number; h: number };
+    maxSize?: { w: number; h: number };
+};

package/src/lib/framework/dashboard-widget/widget-extensions.tsx

@@ -1,4 +1,4 @@
-import { DashboardWidgetDefinition } from '@/vdb/framework/extension-api/types/index.js';
+import { DashboardWidgetDefinition } from './types.js';
 import { globalRegistry } from '../registry/global-registry.js';
 
 globalRegistry.register('dashboardWidgetRegistry', new Map<string, DashboardWidgetDefinition>());

package/src/lib/framework/defaults.ts

@@ -1,4 +1,4 @@
-import { setNavMenuConfig } from '@/vdb/framework/nav-menu/nav-menu-extensions.js';
+import { setNavMenuConfig } from '@/framework/nav-menu/nav-menu-extensions.js';
 import {
     LayoutDashboardIcon,
     Mail,

package/src/lib/framework/document-introspection/add-custom-fields.ts

@@ -1,9 +1,9 @@
-import { Variables } from '@/vdb/graphql/api.js';
+import { Variables } from '@/graphql/api.js';
 import {
     getServerConfigDocument,
     relationCustomFieldFragment,
     structCustomFieldFragment,
-} from '@/vdb/providers/server-config.js';
+} from '@/providers/server-config.js';
 import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
 import { CustomFieldConfig } from '@vendure/common/lib/generated-types';
 import { ResultOf } from 'gql.tada';
@@ -25,35 +25,6 @@ type RelationCustomFieldFragment = ResultOf<typeof relationCustomFieldFragment>;
 
 let globalCustomFieldsMap: Map<string, CustomFieldConfig[]> = new Map();
 
-// Memoization cache using WeakMap to avoid memory leaks
-const memoizationCache = new WeakMap<DocumentNode, Map<string, TypedDocumentNode<any, any>>>();
-
-/**
- * Creates a cache key for the options object
- */
-function createOptionsKey(options?: {
-    customFieldsMap?: Map<string, CustomFieldConfig[]>;
-    includeCustomFields?: string[];
-}): string {
-    if (!options) return 'default';
-
-    const parts: string[] = [];
-
-    if (options.customFieldsMap) {
-        // Create a deterministic key for the customFieldsMap
-        const mapEntries = Array.from(options.customFieldsMap.entries())
-            .sort(([a], [b]) => a.localeCompare(b))
-            .map(([key, value]) => `${key}:${value.length}`);
-        parts.push(`map:${mapEntries.join(',')}`);
-    }
-
-    if (options.includeCustomFields) {
-        parts.push(`include:${options.includeCustomFields.sort().join(',')}`);
-    }
-
-    return parts.join('|') || 'default';
-}
-
 /**
  * @description
  * This function is used to set the global custom fields map.
@@ -85,8 +56,6 @@ export function getCustomFieldsMap() {
 /**
  * Given a GraphQL AST (DocumentNode), this function looks for fragment definitions and adds and configured
  * custom fields to those fragments.
- *
- * This function is memoized to return a stable identity for given inputs.
  */
 export function addCustomFields<T, V extends Variables = Variables>(
     documentNode: DocumentNode | TypedDocumentNode<T, V>,
@@ -95,21 +64,6 @@ export function addCustomFields<T, V extends Variables = Variables>(
         includeCustomFields?: string[];
     },
 ): TypedDocumentNode<T, V> {
-    const optionsKey = createOptionsKey(options);
-
-    // Check if we have a cached result for this document and options
-    let documentCache = memoizationCache.get(documentNode);
-    if (!documentCache) {
-        documentCache = new Map();
-        memoizationCache.set(documentNode, documentCache);
-    }
-
-    const cachedResult = documentCache.get(optionsKey);
-    if (cachedResult) {
-        return cachedResult as TypedDocumentNode<T, V>;
-    }
-
-    // If not cached, compute the result
     const clone = JSON.parse(JSON.stringify(documentNode)) as DocumentNode;
     const customFields = options?.customFieldsMap || globalCustomFieldsMap;
 
@@ -255,8 +209,6 @@ export function addCustomFields<T, V extends Variables = Variables>(
         }
     }
 
-    // Cache the result before returning
-    documentCache.set(optionsKey, clone);
     return clone;
 }
 

package/src/lib/framework/document-introspection/get-document-structure.ts

@@ -199,23 +199,6 @@ function unwrapVariableDefinitionType(type: TypeNode): NamedTypeNode {
     return type;
 }
 
-/**
- * @description
- * Helper function to get the first field selection from a query operation definition.
- */
-function getFirstQueryField(documentNode: DocumentNode): FieldNode {
-    const operationDefinition = documentNode.definitions.find(
-        (def): def is OperationDefinitionNode =>
-            def.kind === 'OperationDefinition' && def.operation === 'query',
-    );
-    const firstSelection = operationDefinition?.selectionSet.selections[0];
-    if (firstSelection?.kind === 'Field') {
-        return firstSelection;
-    } else {
-        throw new Error('Could not determine query field');
-    }
-}
-
 /**
  * @description
  * This function is used to get the name of the query from a DocumentNode.
@@ -233,32 +216,16 @@ function getFirstQueryField(documentNode: DocumentNode): FieldNode {
  * The query name is `product`.
  */
 export function getQueryName(documentNode: DocumentNode): string {
-    const firstField = getFirstQueryField(documentNode);
-    return firstField.name.value;
-}
-
-/**
- * @description
- * This function is used to get the entity name from a DocumentNode.
- *
- * For example, in the following query:
- *
- * ```graphql
- * query ProductDetail($id: ID!) {
- *   product(id: $id) {
- *     ...ProductDetail
- *   }
- * }
- * ```
- *
- * The entity name is `Product`.
- */
-export function getEntityName(documentNode: DocumentNode): string {
-    const firstField = getFirstQueryField(documentNode);
-    // Get the return type from the field definition
-    const fieldName = firstField.name.value;
-    const queryInfo = getQueryInfo(fieldName);
-    return queryInfo.type;
+    const operationDefinition = documentNode.definitions.find(
+        (def): def is OperationDefinitionNode =>
+            def.kind === 'OperationDefinition' && def.operation === 'query',
+    );
+    const firstSelection = operationDefinition?.selectionSet.selections[0];
+    if (firstSelection?.kind === 'Field') {
+        return firstSelection.name.value;
+    } else {
+        throw new Error('Could not determine query name');
+    }
 }
 
 /**

package/src/lib/framework/document-introspection/hooks.ts

@@ -1,7 +1,4 @@
-import {
-    FieldInfo,
-    getListQueryFields,
-} from '@/vdb/framework/document-introspection/get-document-structure.js';
+import { FieldInfo, getListQueryFields } from '@/framework/document-introspection/get-document-structure.js';
 import { DocumentNode } from 'graphql';
 import { useMemo } from 'react';
 

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

@@ -1,15 +1,13 @@
+import { registerDashboardWidget } from '../dashboard-widget/widget-extensions.js';
+import {
+    registerDashboardActionBarItem,
+    registerDashboardPageBlock,
+} from '../layout-engine/layout-extensions.js';
+import { addNavMenuItem, addNavMenuSection, NavMenuItem } from '../nav-menu/nav-menu-extensions.js';
+import { registerRoute } from '../page/page-api.js';
 import { globalRegistry } from '../registry/global-registry.js';
 
 import { DashboardExtension } from './extension-api-types.js';
-import {
-    registerAlertExtensions,
-    registerDataTableExtensions,
-    registerDetailFormExtensions,
-    registerFormComponentExtensions,
-    registerLayoutExtensions,
-    registerNavigationExtensions,
-    registerWidgetExtensions,
-} from './logic/index.js';
 
 globalRegistry.register('extensionSourceChangeCallbacks', new Set<() => void>());
 globalRegistry.register('registerDashboardExtensionCallbacks', new Set<() => void>());
@@ -36,28 +34,48 @@ export function executeDashboardExtensionCallbacks() {
  */
 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);
-
-        // Execute extension source change callbacks
+        if (extension.navSections) {
+            for (const section of extension.navSections) {
+                addNavMenuSection({
+                    ...section,
+                    placement: 'top',
+                    order: section.order ?? 999,
+                    items: [],
+                });
+            }
+        }
+        if (extension.routes) {
+            for (const route of extension.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);
+                }
+            }
+        }
+        if (extension.actionBarItems) {
+            for (const item of extension.actionBarItems) {
+                registerDashboardActionBarItem(item);
+            }
+        }
+        if (extension.pageBlocks) {
+            for (const block of extension.pageBlocks) {
+                registerDashboardPageBlock(block);
+            }
+        }
+        if (extension.widgets) {
+            for (const widget of extension.widgets) {
+                registerDashboardWidget(widget);
+            }
+        }
         const callbacks = globalRegistry.get('extensionSourceChangeCallbacks');
         if (callbacks.size) {
             for (const callback of callbacks) {

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

@@ -1,15 +1,100 @@
-// Import types for the main interface
-import {
-    DashboardActionBarItem,
-    DashboardAlertDefinition,
-    DashboardCustomFormComponents,
-    DashboardDataTableExtensionDefinition,
-    DashboardDetailFormExtensionDefinition,
-    DashboardNavSectionDefinition,
-    DashboardPageBlockDefinition,
-    DashboardRouteDefinition,
-    DashboardWidgetDefinition,
-} from './types/index.js';
+import { PageContextValue } from '@/framework/layout-engine/page-provider.js';
+import { AnyRoute, RouteOptions } from '@tanstack/react-router';
+import { LucideIcon } from 'lucide-react';
+import type React from 'react';
+
+import { DashboardAlertDefinition } from '../alert/types.js';
+import { DashboardWidgetDefinition } from '../dashboard-widget/types.js';
+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 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
@@ -43,7 +128,7 @@ export interface DashboardExtension {
     actionBarItems?: DashboardActionBarItem[];
     /**
      * @description
-     * Allows you to define custom alerts that can be displayed in the dashboard.
+     * Not yet implemented
      */
     alerts?: DashboardAlertDefinition[];
     /**
@@ -52,16 +137,4 @@ export interface DashboardExtension {
      * given components and optionally also add a nav menu item.
      */
     widgets?: DashboardWidgetDefinition[];
-    /**
-     * @description
-     * Unified registration for custom form components including custom field components,
-     * input components, and display components.
-     */
-    customFormComponents?: DashboardCustomFormComponents;
-    /**
-     * @description
-     * Allows you to customize aspects of existing data tables in the dashboard.
-     */
-    dataTables?: DashboardDataTableExtensionDefinition[];
-    detailForms?: DashboardDetailFormExtensionDefinition[];
 }

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

@@ -1,8 +1,7 @@
+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/form-engine/form-schema-tools.ts

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