@vendure/dashboard 3.2.3 → 3.3.0

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

@@ -2,6 +2,7 @@ import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/com
 import { cn } from '@/lib/utils.js';
 import { Trans } from '@/lib/trans.js';
 import { PropsWithChildren, useRef, useEffect, useState, createContext, useContext } from 'react';
+import type React from 'react';
 
 type WidgetDimensions = {
     width: number;

package/src/lib/framework/defaults.ts

@@ -122,6 +122,11 @@ export function registerDefaults() {
                         title: 'Healthchecks',
                         url: '/healthchecks',
                     },
+                    {
+                        id: 'scheduled-tasks',
+                        title: 'Scheduled Tasks',
+                        url: '/scheduled-tasks',
+                    },
                 ],
             },
             {
@@ -216,4 +221,33 @@ export function registerDefaults() {
         component: OrdersSummaryWidget,
         defaultSize: { w: 6, h: 3, x: 6, y: 0 },
     });
+
+    // registerAlert<boolean>({
+    //     id: 'test-alert',
+    //     title: data => `Test Alert ${String(data)}`,
+    //     description: 'This is a test alert',
+    //     severity: 'info',
+    //     check: () => Promise.resolve(true),
+    //     actions: [
+    //         {
+    //             label: 'Test Action',
+    //             onClick: () => console.log('Test Action'),
+    //         },
+    //     ],
+    // });
+
+    // registerAlert<boolean>({
+    //     id: 'test-alert-2',
+    //     title: 'Test Alert 2',
+    //     description: 'This is a test alert 2',
+    //     severity: 'info',
+    //     check: () => Promise.resolve(true),
+    //     shouldShow: data => data === true,
+    //     actions: [
+    //         {
+    //             label: 'Test Action',
+    //             onClick: () => console.log('Test Action'),
+    //         },
+    //     ],
+    // });
 }

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

@@ -1,7 +1,7 @@
 import { graphql } from 'gql.tada';
 import { describe, expect, it, vi } from 'vitest';
 
-import { getListQueryFields } from './get-document-structure.js';
+import { getListQueryFields, getOperationVariablesFields } from './get-document-structure.js';
 
 vi.mock('virtual:admin-api-schema', () => {
     return {
@@ -12,7 +12,10 @@ vi.mock('virtual:admin-api-schema', () => {
                     product: ['Product', false, false, false],
                     collection: ['Collection', false, false, false],
                 },
-                Mutation: {},
+                Mutation: {
+                    updateProduct: ['Product', false, false, false],
+                    adjustDraftOrderLine: ['Order', false, false, false],
+                },
 
                 Collection: {
                     id: ['ID', false, false, false],
@@ -126,8 +129,25 @@ vi.mock('virtual:admin-api-schema', () => {
                     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],
+                },
             },
-            inputs: {},
             scalars: ['ID', 'String', 'Int', 'Boolean', 'Float', 'JSON', 'DateTime', 'Upload', 'Money'],
             enums: {},
         },
@@ -308,3 +328,93 @@ describe('getListQueryFields', () => {
         ]);
     });
 });
+
+describe('getOperationVariablesFields', () => {
+    it('should extract fields from a simple mutation', () => {
+        const doc = graphql(`
+            mutation UpdateProduct($input: UpdateProductInput!) {
+                updateProduct(input: $input) {
+                    ...ProductDetail
+                }
+            }
+
+            fragment ProductDetail on Product {
+                id
+                name
+            }
+        `);
+
+        const fields = getOperationVariablesFields(doc, 'input');
+        expect(fields).toEqual([
+            {
+                isPaginatedList: false,
+                isScalar: true,
+                list: false,
+                name: 'id',
+                nullable: false,
+                type: 'ID',
+                typeInfo: undefined,
+            },
+            {
+                isPaginatedList: false,
+                isScalar: true,
+                list: false,
+                name: 'name',
+                nullable: false,
+                type: 'String',
+                typeInfo: undefined,
+            },
+        ]);
+    });
+
+    it('should handle a mutation with a nested input', () => {
+        const doc = graphql(`
+            mutation AdjustDraftOrderLine($orderId: ID!, $input: AdjustDraftOrderLineInput!) {
+                adjustDraftOrderLine(orderId: $orderId, input: $input) {
+                    id
+                }
+            }
+        `);
+
+        const fields = getOperationVariablesFields(doc, undefined);
+        expect(fields).toEqual([
+            {
+                name: 'orderId',
+                isPaginatedList: false,
+                isScalar: true,
+                list: false,
+                nullable: false,
+                type: 'ID',
+                typeInfo: undefined,
+            },
+            {
+                name: 'input',
+                isPaginatedList: false,
+                isScalar: false,
+                list: false,
+                nullable: true,
+                type: 'AdjustDraftOrderLineInput',
+                typeInfo: [
+                    {
+                        name: 'orderLineId',
+                        isPaginatedList: false,
+                        isScalar: true,
+                        list: false,
+                        nullable: false,
+                        type: 'ID',
+                        typeInfo: undefined,
+                    },
+                    {
+                        name: 'quantity',
+                        isPaginatedList: false,
+                        isScalar: true,
+                        list: false,
+                        nullable: false,
+                        type: 'Int',
+                        typeInfo: undefined,
+                    },
+                ],
+            },
+        ]);
+    });
+});

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

@@ -1,10 +1,11 @@
+import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
+import { VariablesOf } from 'gql.tada';
 import {
     DocumentNode,
-    OperationDefinitionNode,
     FieldNode,
     FragmentDefinitionNode,
     FragmentSpreadNode,
-    VariableDefinitionNode,
+    OperationDefinitionNode,
 } from 'graphql';
 import { DefinitionNode, NamedTypeNode, SelectionSetNode, TypeNode } from 'graphql/language/ast.js';
 import { schemaInfo } from 'virtual:admin-api-schema';
@@ -146,7 +147,10 @@ function findNestedPaginatedLists(
  *
  * The operation variables fields are the fields of the `UpdateProductInput` type.
  */
-export function getOperationVariablesFields(documentNode: DocumentNode): FieldInfo[] {
+export function getOperationVariablesFields<T extends TypedDocumentNode<any, any>>(
+    documentNode: T,
+    varName?: keyof VariablesOf<T>,
+): FieldInfo[] {
     const fields: FieldInfo[] = [];
 
     const operationDefinition = documentNode.definitions.find(
@@ -154,11 +158,31 @@ export function getOperationVariablesFields(documentNode: DocumentNode): FieldIn
     );
 
     if (operationDefinition?.variableDefinitions) {
-        operationDefinition.variableDefinitions.forEach(variable => {
-            const unwrappedType = unwrapVariableDefinitionType(variable.type);
-            const inputName = unwrappedType.name.value;
-            const inputFields = getInputTypeInfo(inputName);
-            fields.push(...inputFields);
+        const variableDefinitions = varName
+            ? operationDefinition.variableDefinitions.filter(
+                  variable => variable.variable.name.value === varName,
+              )
+            : operationDefinition.variableDefinitions;
+        variableDefinitions.forEach(variableDef => {
+            const unwrappedType = unwrapVariableDefinitionType(variableDef.type);
+            const isScalar = isScalarType(unwrappedType.name.value);
+            const fieldName = variableDef.variable.name.value;
+            const typeName = unwrappedType.name.value;
+            const inputTypeInfo = isScalar
+                ? {
+                      name: fieldName,
+                      type: typeName,
+                      nullable: false,
+                      list: false,
+                      isScalar: true,
+                      isPaginatedList: false,
+                  }
+                : getInputTypeInfo(fieldName, typeName);
+            if (varName && inputTypeInfo?.name === varName) {
+                fields.push(...(inputTypeInfo.typeInfo ?? []));
+            } else {
+                fields.push(inputTypeInfo);
+            }
         });
     }
 
@@ -331,7 +355,9 @@ export function getOperationTypeInfo(
     if (definitionNode.kind === 'OperationDefinition') {
         const firstSelection = definitionNode?.selectionSet.selections[0];
         if (firstSelection?.kind === 'Field') {
-            return getQueryInfo(firstSelection.name.value);
+            return definitionNode.operation === 'query'
+                ? getQueryInfo(firstSelection.name.value)
+                : getMutationInfo(firstSelection.name.value);
         }
     }
     if (definitionNode.kind === 'Field' && parentTypeName) {
@@ -349,7 +375,7 @@ export function getTypeFieldInfo(typeName: string): FieldInfo[] {
             }
             return fieldInfo;
         })
-        .filter(x => x != null) as FieldInfo[];
+        .filter(x => x != null);
 }
 
 function getQueryInfo(name: string): FieldInfo {
@@ -364,8 +390,40 @@ function getQueryInfo(name: string): FieldInfo {
     };
 }
 
-function getInputTypeInfo(name: string): FieldInfo[] {
-    return Object.entries(schemaInfo.inputs[name]).map(([fieldName, fieldInfo]: [string, any]) => {
+function getMutationInfo(name: string): FieldInfo {
+    const fieldInfo = schemaInfo.types.Mutation[name];
+    return {
+        name,
+        type: fieldInfo[0],
+        nullable: fieldInfo[1],
+        list: fieldInfo[2],
+        isPaginatedList: fieldInfo[3],
+        isScalar: schemaInfo.scalars.includes(fieldInfo[0]),
+    };
+}
+
+function getInputTypeInfo(name: string, type: string): FieldInfo {
+    const fieldInfo = schemaInfo.inputs[type];
+    if (!fieldInfo) {
+        throw new Error(`Input type ${type} not found`);
+    }
+    return {
+        name,
+        type,
+        nullable: true,
+        list: false,
+        isPaginatedList: false,
+        isScalar: false,
+        typeInfo: getInputTypeFields(type),
+    };
+}
+
+function getInputTypeFields(name: string): FieldInfo[] {
+    const inputType = schemaInfo.inputs[name];
+    if (!inputType) {
+        throw new Error(`Input type ${name} not found`);
+    }
+    return Object.entries(inputType).map(([fieldName, fieldInfo]: [string, any]) => {
         const type = fieldInfo[0];
         const isScalar = isScalarType(type);
         const isEnum = isEnumType(type);
@@ -376,7 +434,7 @@ function getInputTypeInfo(name: string): FieldInfo[] {
             list: fieldInfo[2],
             isPaginatedList: fieldInfo[3],
             isScalar,
-            typeInfo: !isScalar && !isEnum ? getInputTypeInfo(type) : undefined,
+            typeInfo: !isScalar && !isEnum ? getInputTypeFields(type) : undefined,
         };
     });
 }

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

@@ -1,14 +1,14 @@
-import { registerDashboardWidget } from '@/framework/dashboard-widget/widget-extensions.js';
-import { DashboardExtension } from '@/framework/extension-api/extension-api-types.js';
-import { addNavMenuItem, NavMenuItem } from '@/framework/nav-menu/nav-menu-extensions.js';
-import { registerRoute } from '@/framework/page/page-api.js';
-
+import { registerDashboardWidget } from '../dashboard-widget/widget-extensions.js';
 import {
     registerDashboardActionBarItem,
     registerDashboardPageBlock,
 } from '../layout-engine/layout-extensions.js';
+import { addNavMenuItem, 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';
+
 globalRegistry.register('extensionSourceChangeCallbacks', new Set<() => void>());
 globalRegistry.register('registerDashboardExtensionCallbacks', new Set<() => void>());
 
@@ -22,6 +22,16 @@ export function executeDashboardExtensionCallbacks() {
     }
 }
 
+/**
+ * @description
+ * **Status: Developer Preview**
+ *
+ * The main entry point for extensions to the React-based dashboard.
+ *
+ *
+ * @docsCategory extensions
+ * @since 3.3.0
+ */
 export function defineDashboardExtension(extension: DashboardExtension) {
     globalRegistry.get('registerDashboardExtensionCallbacks').add(() => {
         if (extension.routes) {

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

@@ -1,9 +1,10 @@
-import { NavMenuItem } from '@/framework/nav-menu/nav-menu-extensions.js';
+import { PageContextValue } from '@/framework/layout-engine/page-provider.js';
 import { AnyRoute, RouteOptions } from '@tanstack/react-router';
-import React from 'react';
+import type React from 'react';
 
+import { DashboardAlertDefinition } from '../alert/types.js';
 import { DashboardWidgetDefinition } from '../dashboard-widget/types.js';
-import { PageContext } from '../layout-engine/page-layout.js';
+import { NavMenuItem } from '../nav-menu/nav-menu-extensions.js';
 
 export interface DashboardRouteDefinition {
     component: (route: AnyRoute) => React.ReactNode;
@@ -17,42 +18,110 @@ export interface ActionBarButtonState {
     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 {
-    locationId: string;
-    component: React.FunctionComponent<{ context: PageContext }>;
+    /**
+     * @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: PageContext }>;
+    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: PageContext }>;
+    component: React.FunctionComponent<{ context: PageContextValue }>;
     requiresPermission?: string | string[];
 }
 
 /**
  * @description
- * The main entry point for a dashboard extension.
+ * **Status: Developer Preview**
+ *
  * This is used to define the routes, widgets, etc. that will be displayed in the dashboard.
+ *
+ * @docsCategory extensions
+ * @since 3.3.0
  */
 export interface DashboardExtension {
-    routes: DashboardRouteDefinition[];
-    widgets: DashboardWidgetDefinition[];
-    actionBarItems: DashboardActionBarItem[];
-    pageBlocks: DashboardPageBlockDefinition[];
+    /**
+     * @description
+     * Allows you to define custom routes such as list or detail views.
+     */
+    routes?: DashboardRouteDefinition[];
+    /**
+     * @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
+     * Not yet implemented
+     */
+    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[];
 }

package/src/lib/framework/form-engine/use-generated-form.tsx

@@ -13,13 +13,14 @@ import { useForm } from 'react-hook-form';
 
 export interface GeneratedFormOptions<
     T extends TypedDocumentNode<any, any>,
-    VarName extends keyof VariablesOf<T> = 'input',
+    VarName extends (keyof VariablesOf<T>) | undefined = 'input',
     E extends Record<string, any> = Record<string, any>,
 > {
     document?: T;
+    varName?: VarName;
     entity: E | null | undefined;
-    setValues: (entity: NonNullable<E>) => VariablesOf<T>[VarName];
-    onSubmit?: (values: VariablesOf<T>[VarName]) => void;
+    setValues: (entity: NonNullable<E>) => VarName extends keyof VariablesOf<T> ? VariablesOf<T>[VarName] : VariablesOf<T>;
+    onSubmit?: (values: VarName extends keyof VariablesOf<T> ? VariablesOf<T>[VarName] : VariablesOf<T>) => void;
 }
 
 /**
@@ -31,13 +32,13 @@ export interface GeneratedFormOptions<
  */
 export function useGeneratedForm<
     T extends TypedDocumentNode<any, any>,
-    VarName extends keyof VariablesOf<T> = 'input',
+    VarName extends keyof VariablesOf<T> | undefined,
     E extends Record<string, any> = Record<string, any>,
 >(options: GeneratedFormOptions<T, VarName, E>) {
-    const { document, entity, setValues, onSubmit } = options;
+    const { document, entity, setValues, onSubmit, varName } = options;
     const { activeChannel } = useChannel();
     const availableLanguages = useServerConfig()?.availableLanguages || [];
-    const updateFields = document ? getOperationVariablesFields(document) : [];
+    const updateFields = document ? getOperationVariablesFields(document, varName) : [];
     const schema = createFormSchemaFromFields(updateFields);
     const defaultValues = getDefaultValuesFromFields(updateFields, activeChannel?.defaultLanguageCode);
     const processedEntity = ensureTranslationsForAllLanguages(entity, availableLanguages);
@@ -58,7 +59,7 @@ export function useGeneratedForm<
     };
     if (onSubmit) {
         submitHandler = (event: FormEvent) => {
-            form.handleSubmit(onSubmit)(event);
+            form.handleSubmit(onSubmit as any)(event);
         };
     }
 

package/src/lib/framework/layout-engine/layout-extensions.ts

@@ -9,13 +9,13 @@ globalRegistry.register('dashboardPageBlockRegistry', new Map<string, DashboardP
 
 export function registerDashboardActionBarItem(item: DashboardActionBarItem) {
     globalRegistry.set('dashboardActionBarItemRegistry', map => {
-        map.set(item.locationId, [...(map.get(item.locationId) ?? []), item]);
+        map.set(item.pageId, [...(map.get(item.pageId) ?? []), item]);
         return map;
     });
 }
 
-export function getDashboardActionBarItems(locationId: string) {
-    return globalRegistry.get('dashboardActionBarItemRegistry').get(locationId) ?? [];
+export function getDashboardActionBarItems(pageId: string) {
+    return globalRegistry.get('dashboardActionBarItemRegistry').get(pageId) ?? [];
 }
 
 export function registerDashboardPageBlock(block: DashboardPageBlockDefinition) {