@vendure/dashboard 3.4.0-minor-202506250934 → 3.4.0

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

@@ -1,36 +1,55 @@
-import { NEW_ENTITY_PATH } from '@/constants.js';
+import { NEW_ENTITY_PATH } from '@/vdb/constants.js';
 
-import { PageBreadcrumb } from '@/components/layout/generated-breadcrumbs.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 } from '@tanstack/react-router';
+import { FileBaseRouteOptions, ParsedLocation } from '@tanstack/react-router';
+import { addCustomFields } from '../document-introspection/add-custom-fields.js';
 import { getQueryName, getQueryTypeFieldInfo } from '../document-introspection/get-document-structure.js';
 import { DetailEntity } from './page-types.js';
 import { getDetailQueryOptions } from './use-detail-page.js';
-import { addCustomFields } from '../document-introspection/add-custom-fields.js';
+
 export interface DetailPageRouteLoaderConfig<T extends TypedDocumentNode<any, any>> {
+    /**
+     * @description
+     * The pageId is used to ensure any detail form extensions (such as extensions to
+     * the detail query document) get correctly applied at the route loader level.
+     */
+    pageId?: string;
     queryDocument: T;
-    breadcrumb: (isNew: boolean, entity: DetailEntity<T>) => Array<PageBreadcrumb | undefined>;
+    breadcrumb: (
+        isNew: boolean,
+        entity: DetailEntity<T>,
+        location: ParsedLocation,
+    ) => Array<PageBreadcrumb | undefined>;
 }
 
 export function detailPageRouteLoader<T extends TypedDocumentNode<any, any>>({
+    pageId,
     queryDocument,
     breadcrumb,
 }: DetailPageRouteLoaderConfig<T>) {
     const loader: FileBaseRouteOptions<any, any>['loader'] = async ({
         context,
         params,
+        location,
     }: {
         context: any;
         params: any;
+        location: ParsedLocation;
     }) => {
         if (!params.id) {
             throw new Error('ID param is required');
         }
         const isNew = params.id === NEW_ENTITY_PATH;
+        const { extendedQuery: extendedQueryDocument } = extendDetailFormQuery(
+            addCustomFields(queryDocument),
+            pageId,
+        );
         const result = isNew
             ? null
             : await context.queryClient.ensureQueryData(
-                  getDetailQueryOptions(addCustomFields(queryDocument), { id: params.id }),
+                  getDetailQueryOptions(extendedQueryDocument, { id: params.id }),
                   { id: params.id },
               );
 
@@ -41,7 +60,7 @@ export function detailPageRouteLoader<T extends TypedDocumentNode<any, any>>({
             throw new Error(`${entityName} with the ID ${params.id} was not found`);
         }
         return {
-            breadcrumb: breadcrumb(isNew, result?.[entityField]),
+            breadcrumb: breadcrumb(isNew, result?.[entityField], location),
         };
     };
     return loader;

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

@@ -1,17 +1,24 @@
-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 { getOperationVariablesFields } from '../document-introspection/get-document-structure.js';
+import {
+    FieldInfo,
+    getEntityName,
+    getOperationVariablesFields,
+} from '../document-introspection/get-document-structure.js';
 
+import { TranslatableFormFieldWrapper } from '@/vdb/components/shared/translatable-form-field.js';
+import { FormControl } from '@/vdb/components/ui/form.js';
+import { ControllerRenderProps, FieldPath, FieldValues } from 'react-hook-form';
 import {
     CustomFieldsPageBlock,
     DetailFormGrid,
@@ -41,6 +48,7 @@ export interface DetailPageProps<
     /**
      * @description
      * The name of the entity.
+     * If not provided, it will be inferred from the query document.
      */
     entityName?: string;
     /**
@@ -80,6 +88,54 @@ 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>;
+}
+
+/**
+ * Renders form input components based on field type
+ */
+function FieldInputRenderer<
+    TFieldValues extends FieldValues = FieldValues,
+    TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+>({ fieldInfo, field }: DetailPageFieldProps<TFieldValues, TName>) {
+    switch (fieldInfo.type) {
+        case 'Int':
+        case 'Float':
+            return (
+                <FormControl>
+                    <Input
+                        type="number"
+                        value={field.value}
+                        onChange={e => field.onChange(e.target.valueAsNumber)}
+                    />
+                </FormControl>
+            );
+        case 'DateTime':
+            return (
+                <FormControl>
+                    <DateTimeInput {...field} />
+                </FormControl>
+            );
+        case 'Boolean':
+            return (
+                <FormControl>
+                    <Checkbox value={field.value} onCheckedChange={field.onChange} />
+                </FormControl>
+            );
+        default:
+            return (
+                <FormControl>
+                    <Input {...field} />
+                </FormControl>
+            );
+    }
+}
+
 /**
  * @description
  * **Status: Developer Preview**
@@ -100,7 +156,7 @@ export function DetailPage<
 >({
     pageId,
     route,
-    entityName,
+    entityName: passedEntityName,
     queryDocument,
     createDocument,
     updateDocument,
@@ -110,11 +166,15 @@ export function DetailPage<
     const params = route.useParams();
     const creatingNewEntity = params.id === NEW_ENTITY_PATH;
     const navigate = useNavigate();
+    const inferredEntityName = getEntityName(queryDocument);
+
+    const entityName = passedEntityName ?? inferredEntityName;
 
     const { form, submitHandler, entity, isPending, resetForm } = useDetailPage<any, any, any>({
         queryDocument,
         updateDocument,
         createDocument,
+        entityName,
         params: { id: params.id },
         setValuesForUpdate,
         onSuccess: async data => {
@@ -133,6 +193,7 @@ export function DetailPage<
     });
 
     const updateFields = getOperationVariablesFields(updateDocument, 'input');
+    const translations = updateFields.find(fieldInfo => fieldInfo.name === 'translations');
 
     return (
         <Page pageId={pageId} form={form} submitHandler={submitHandler}>
@@ -152,6 +213,7 @@ export function DetailPage<
                     <DetailFormGrid>
                         {updateFields
                             .filter(fieldInfo => fieldInfo.name !== 'customFields')
+                            .filter(fieldInfo => fieldInfo.name !== 'translations')
                             .map(fieldInfo => {
                                 if (fieldInfo.name === 'id' && fieldInfo.type === 'ID') {
                                     return null;
@@ -162,33 +224,28 @@ export function DetailPage<
                                         control={form.control}
                                         name={fieldInfo.name as never}
                                         label={fieldInfo.name}
-                                        render={({ field }) => {
-                                            switch (fieldInfo.type) {
-                                                case 'Int':
-                                                case 'Float':
-                                                    return (
-                                                        <Input
-                                                            type="number"
-                                                            value={field.value}
-                                                            onChange={e =>
-                                                                field.onChange(e.target.valueAsNumber)
-                                                            }
-                                                        />
-                                                    );
-                                                case 'DateTime':
-                                                    return <DateTimeInput {...field} />;
-                                                case 'Boolean':
-                                                    return (
-                                                        <Checkbox
-                                                            value={field.value}
-                                                            onCheckedChange={field.onChange}
-                                                        />
-                                                    );
-                                                case 'String':
-                                                default:
-                                                    return <Input {...field} />;
-                                            }
-                                        }}
+                                        renderFormControl={false}
+                                        render={({ field }) => (
+                                            <FieldInputRenderer fieldInfo={fieldInfo} field={field} />
+                                        )}
+                                    />
+                                );
+                            })}
+                        {translations?.typeInfo
+                            ?.filter(
+                                fieldInfo => !['customFields', 'id', 'languageCode'].includes(fieldInfo.name),
+                            )
+                            .map(fieldInfo => {
+                                return (
+                                    <TranslatableFormFieldWrapper
+                                        key={fieldInfo.name}
+                                        control={form.control}
+                                        name={fieldInfo.name as never}
+                                        label={fieldInfo.name}
+                                        renderFormControl={false}
+                                        render={({ field }) => (
+                                            <FieldInputRenderer fieldInfo={fieldInfo} field={field} />
+                                        )}
                                     />
                                 );
                             })}

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

@@ -3,26 +3,22 @@ import {
     CustomFieldKeysOfItem,
     CustomizeColumnConfig,
     FacetedFilterConfig,
+    ListQueryFields,
     ListQueryOptionsShape,
     ListQueryShape,
-    ListQueryFields,
     PaginatedListDataTable,
+    PaginatedListRefresherRegisterFn,
     RowAction,
-} from '@/components/shared/paginated-list-data-table.js';
-import { useUserSettings } from '@/hooks/use-user-settings.js';
+} from '@/vdb/components/shared/paginated-list-data-table.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 { BulkAction } from '@/vdb/framework/extension-api/types/index.js';
 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
@@ -57,6 +53,13 @@ export interface ListPageProps<
     rowActions?: RowAction<ListQueryFields<T>>[];
     transformData?: (data: any[]) => any[];
     setTableOptions?: (table: TableOptions<any>) => TableOptions<any>;
+    bulkActions?: BulkAction[];
+    /**
+     * Register a function that allows you to assign a refresh function for
+     * this list. The function can be assigned to a ref and then called when
+     * the list needs to be refreshed.
+     */
+    registerRefresher?: PaginatedListRefresherRegisterFn;
 }
 
 /**
@@ -93,7 +96,9 @@ export function ListPage<
     rowActions,
     transformData,
     setTableOptions,
-}: ListPageProps<T, U, V, AC>) {
+    bulkActions,
+    registerRefresher,
+}: Readonly<ListPageProps<T, U, V, AC>>) {
     const route = typeof routeOrFn === 'function' ? routeOrFn() : routeOrFn;
     const routeSearch = route.useSearch();
     const navigate = useNavigate<AnyRouter>({ from: route.fullPath });
@@ -191,8 +196,10 @@ export function ListPage<
                         }}
                         facetedFilters={facetedFilters}
                         rowActions={rowActions}
+                        bulkActions={bulkActions}
                         setTableOptions={setTableOptions}
                         transformData={transformData}
+                        registerRefresher={registerRefresher}
                     />
                 </FullWidthPageBlock>
             </PageLayout>

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

@@ -1,5 +1,4 @@
-import { NEW_ENTITY_PATH } from '@/constants.js';
-import { api, Variables } from '@/graphql/api.js';
+import { removeReadonlyAndLocalizedCustomFields } from '@/vdb/lib/utils.js';
 import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
 import {
     DefinedInitialDataOptions,
@@ -13,8 +12,16 @@ import { DocumentNode } from 'graphql';
 import { FormEvent } from 'react';
 import { UseFormReturn } from 'react-hook-form';
 
+import { NEW_ENTITY_PATH } from '../../constants.js';
+import { api } from '../../graphql/api.js';
+import { useCustomFieldConfig } from '../../hooks/use-custom-field-config.js';
+import { useExtendedDetailQuery } from '../../hooks/use-extended-detail-query.js';
 import { addCustomFields } from '../document-introspection/add-custom-fields.js';
-import { getMutationName, getQueryName } from '../document-introspection/get-document-structure.js';
+import {
+    getEntityName,
+    getMutationName,
+    getQueryName,
+} from '../document-introspection/get-document-structure.js';
 import { useGeneratedForm } from '../form-engine/use-generated-form.js';
 
 import { DetailEntityPath } from './page-types.js';
@@ -26,6 +33,8 @@ type RemoveNullFields<T> = {
     [K in keyof T]: RemoveNull<T[K]>;
 };
 
+const NEW_ENTITY_ID = '__NEW__';
+
 /**
  * @description
  * **Status: Developer Preview**
@@ -42,6 +51,12 @@ export interface DetailPageOptions<
     VarNameCreate extends keyof VariablesOf<C> = 'input',
     VarNameUpdate extends keyof VariablesOf<U> = 'input',
 > {
+    /**
+     * @description
+     * The page id. This is optional, but if provided, it will be used to
+     * identify the page when extending the detail page query
+     */
+    pageId?: string;
     /**
      * @description
      * The query document to fetch the entity.
@@ -59,6 +74,13 @@ export interface DetailPageOptions<
     params: {
         id: string;
     };
+    /**
+     * @description
+     * The entity type name for custom field configuration lookup.
+     * Required to filter out readonly custom fields before mutations.
+     * If not provided, the function will try to infer it from the query document.
+     */
+    entityName?: string;
     /**
      * @description
      * The document to create the entity.
@@ -88,14 +110,16 @@ export interface DetailPageOptions<
     onError?: (error: unknown) => void;
 }
 
-export function getDetailQueryOptions<T, V extends Variables = Variables>(
+export function getDetailQueryOptions<T, V extends { id: string }>(
     document: TypedDocumentNode<T, V> | DocumentNode,
     variables: V,
+    options: Partial<Parameters<typeof queryOptions>[0]> = {},
 ): DefinedInitialDataOptions {
     const queryName = getQueryName(document);
     return queryOptions({
         queryKey: ['DetailPage', queryName, variables],
-        queryFn: () => api.query(document, variables),
+        queryFn: () => (variables.id === NEW_ENTITY_ID ? null : api.query(document, variables)),
+        ...options,
     }) as DefinedInitialDataOptions;
 }
 
@@ -132,7 +156,6 @@ export type DetailPageEntity<
  */
 export interface UseDetailPageResult<
     T extends TypedDocumentNode<any, any>,
-    C extends TypedDocumentNode<any, any>,
     U extends TypedDocumentNode<any, any>,
     EntityField extends keyof ResultOf<T>,
 > {
@@ -222,8 +245,9 @@ export function useDetailPage<
     VarNameCreate extends keyof VariablesOf<C> = 'input',
 >(
     options: DetailPageOptions<T, C, U, EntityField, VarNameCreate, VarNameUpdate>,
-): UseDetailPageResult<T, C, U, EntityField> {
+): UseDetailPageResult<T, U, EntityField> {
     const {
+        pageId,
         queryDocument,
         createDocument,
         updateDocument,
@@ -232,17 +256,22 @@ export function useDetailPage<
         transformUpdateInput,
         params,
         entityField,
+        entityName,
         onSuccess,
         onError,
     } = options;
     const isNew = params.id === NEW_ENTITY_PATH;
     const queryClient = useQueryClient();
-    const detailQueryOptions = getDetailQueryOptions(addCustomFields(queryDocument), {
-        id: isNew ? '__NEW__' : params.id,
+    const returnEntityName = entityName ?? getEntityName(queryDocument);
+    const customFieldConfig = useCustomFieldConfig(returnEntityName);
+    const extendedDetailQuery = useExtendedDetailQuery(addCustomFields(queryDocument), pageId);
+    const detailQueryOptions = getDetailQueryOptions(extendedDetailQuery, {
+        id: isNew ? NEW_ENTITY_ID : params.id,
     });
     const detailQuery = useSuspenseQuery(detailQueryOptions);
-    const entityQueryField = entityField ?? getQueryName(queryDocument);
-    const entity = (detailQuery?.data as any)[entityQueryField] as
+    const entityQueryField = entityField ?? getQueryName(extendedDetailQuery);
+
+    const entity = (detailQuery?.data as any)?.[entityQueryField] as
         | DetailPageEntity<T, EntityField>
         | undefined;
 
@@ -278,12 +307,17 @@ export function useDetailPage<
         document,
         varName: 'input',
         entity,
+        customFieldConfig,
         setValues: setValuesForUpdate,
         onSubmit(values: any) {
+            const filteredValues = removeReadonlyAndLocalizedCustomFields(values, customFieldConfig || []);
+
             if (isNew) {
-                createMutation.mutate({ input: transformCreateInput?.(values) ?? values });
+                const finalInput = transformCreateInput?.(filteredValues) ?? filteredValues;
+                createMutation.mutate({ input: finalInput });
             } else {
-                updateMutation.mutate({ input: transformUpdateInput?.(values) ?? values });
+                const finalInput = transformUpdateInput?.(filteredValues) ?? filteredValues;
+                updateMutation.mutate({ input: finalInput });
             }
         },
     });

package/src/lib/framework/page/use-extended-router.tsx

@@ -1,10 +1,9 @@
-import { ErrorPage } from '@/components/shared/error-page.js';
-import { useDashboardExtensions } from '@/framework/extension-api/use-dashboard-extensions.js';
-import { ListPage } from '@/framework/page/list-page.js';
-import { extensionRoutes } from '@/framework/page/page-api.js';
-import { AUTHENTICATED_ROUTE_PREFIX } from '@/constants.js';
 import { AnyRoute, createRoute, Router } from '@tanstack/react-router';
 import { useMemo } from 'react';
+import { ErrorPage } from '../../components/shared/error-page.js';
+import { AUTHENTICATED_ROUTE_PREFIX } from '../../constants.js';
+import { useDashboardExtensions } from '../extension-api/use-dashboard-extensions.js';
+import { extensionRoutes } from './page-api.js';
 
 /**
  * Extends the TanStack Router with additional routes for each dashboard

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

@@ -36,6 +36,10 @@ class GlobalRegistry {
         const oldValue = this.get(key);
         this.registry.set(key, updater(oldValue));
     }
+
+    public has(key: string): boolean {
+        return this.registry.has(key);
+    }
 }
 
 export type GlobalRegistryKey = keyof GlobalRegistryContents;

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

@@ -1,9 +1,16 @@
-import { DashboardAlertDefinition } from '../alert/types.js';
-import { DashboardWidgetDefinition } from '../dashboard-widget/types.js';
 import {
+    BulkAction,
     DashboardActionBarItem,
+    DashboardLoginExtensions,
     DashboardPageBlockDefinition,
-} from '../extension-api/extension-api-types.js';
+    DashboardWidgetDefinition,
+} from '@/vdb/framework/extension-api/types/index.js';
+import { DocumentNode } from 'graphql';
+import React from 'react';
+
+import { DataDisplayComponent, DataInputComponent } from '../component-registry/component-registry.js';
+import { DashboardAlertDefinition } from '../extension-api/types/alerts.js';
+import { CustomFormComponentInputProps } from '../form-engine/custom-form-component.js';
 import { NavMenuConfig } from '../nav-menu/nav-menu-extensions.js';
 
 export interface GlobalRegistryContents {
@@ -14,6 +21,11 @@ export interface GlobalRegistryContents {
     dashboardPageBlockRegistry: Map<string, DashboardPageBlockDefinition[]>;
     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[]>;
+    loginExtensions: DashboardLoginExtensions;
 }
-
-export type GlobalRegistryKey = keyof GlobalRegistryContents;

package/src/lib/graphql/api.ts

@@ -3,7 +3,10 @@ import { AwesomeGraphQLClient } from 'awesome-graphql-client';
 import { DocumentNode, print } from 'graphql';
 import { uiConfig } from 'virtual:vendure-ui-config';
 
-const API_URL = uiConfig.apiHost + (uiConfig.apiPort !== 'auto' ? `:${uiConfig.apiPort}` : '') + '/admin-api';
+const API_URL =
+    uiConfig.api.host +
+    (uiConfig.api.port !== 'auto' ? `:${uiConfig.api.port}` : '') +
+    `/${uiConfig.api.adminApiPath}`;
 
 export type Variables = object;
 export type RequestDocument = string | DocumentNode;
@@ -16,10 +19,29 @@ const awesomeClient = new AwesomeGraphQLClient({
         const headers = new Headers(options.headers);
 
         if (channelToken) {
-            headers.set('vendure-token', channelToken);
+            headers.set(uiConfig.api.channelTokenKey, channelToken);
         }
 
-        return fetch(url, {
+        // Get the content language from user settings and add as query parameter
+        let finalUrl = url;
+        try {
+            const userSettings = localStorage.getItem('vendure-user-settings');
+            if (userSettings) {
+                const settings = JSON.parse(userSettings);
+                const contentLanguage = settings.contentLanguage;
+
+                if (contentLanguage) {
+                    const urlObj = new URL(finalUrl);
+                    urlObj.searchParams.set('languageCode', contentLanguage);
+                    finalUrl = urlObj.toString();
+                }
+            }
+        } catch (error) {
+            // eslint-disable-next-line no-console
+            console.warn('Failed to read content language from user settings:', error);
+        }
+
+        return fetch(finalUrl, {
             ...options,
             headers,
             credentials: 'include',

package/src/lib/graphql/common-operations.ts

@@ -0,0 +1,18 @@
+import { graphql } from './graphql.js';
+
+export const duplicateEntityDocument = graphql(`
+    mutation DuplicateEntity($input: DuplicateEntityInput!) {
+        duplicateEntity(input: $input) {
+            ... on DuplicateEntitySuccess {
+                newEntityId
+            }
+            ... on ErrorResult {
+                errorCode
+                message
+            }
+            ... on DuplicateEntityError {
+                duplicationError
+            }
+        }
+    }
+`);

package/src/lib/graphql/{fragments.tsx → fragments.ts}

@@ -1,4 +1,4 @@
-import { graphql, ResultOf } from "./graphql.js";
+import { graphql, ResultOf } from './graphql.js';
 
 export const assetFragment = graphql(`
     fragment Asset on Asset {
@@ -58,5 +58,4 @@ export const errorResultFragment = graphql(`
     }
 `);
 
-
 export type ConfigurableOperationDefFragment = ResultOf<typeof configurableOperationDefFragment>;