@vendure/dashboard 3.4.0-minor-202506250934 → 3.4.0

package/src/lib/framework/form-engine/form-schema-tools.ts

@@ -2,27 +2,349 @@ import {
     FieldInfo,
     isEnumType,
     isScalarType,
-} from '@/framework/document-introspection/get-document-structure.js';
+} from '@/vdb/framework/document-introspection/get-document-structure.js';
+import { StructCustomFieldConfig } from '@vendure/common/lib/generated-types';
+import { ResultOf } from 'gql.tada';
 import { z, ZodRawShape, ZodType, ZodTypeAny } from 'zod';
 
-export function createFormSchemaFromFields(fields: FieldInfo[]) {
+import { structCustomFieldFragment } from '../../providers/server-config.js';
+
+type CustomFieldConfig = {
+    name: string;
+    type: string;
+    pattern?: string;
+    intMin?: number;
+    intMax?: number;
+    floatMin?: number;
+    floatMax?: number;
+    datetimeMin?: string;
+    datetimeMax?: string;
+    list?: boolean;
+    nullable?: boolean;
+};
+
+type StructFieldConfig = ResultOf<typeof structCustomFieldFragment>['fields'][number];
+
+function mapGraphQLCustomFieldToConfig(field: StructFieldConfig): CustomFieldConfig {
+    const baseConfig = {
+        name: field.name,
+        type: field.type,
+        list: field.list ?? false,
+        nullable: true, // Default to true since GraphQL fields are nullable by default
+    };
+
+    switch (field.__typename) {
+        case 'StringStructFieldConfig':
+            return {
+                ...baseConfig,
+                pattern: field.pattern ?? undefined,
+            };
+        case 'IntStructFieldConfig':
+            return {
+                ...baseConfig,
+                intMin: field.intMin ?? undefined,
+                intMax: field.intMax ?? undefined,
+            };
+        case 'FloatStructFieldConfig':
+            return {
+                ...baseConfig,
+                floatMin: field.floatMin ?? undefined,
+                floatMax: field.floatMax ?? undefined,
+            };
+        case 'DateTimeStructFieldConfig':
+            return {
+                ...baseConfig,
+                datetimeMin: field.datetimeMin ?? undefined,
+                datetimeMax: field.datetimeMax ?? undefined,
+            };
+        default:
+            return baseConfig;
+    }
+}
+
+/**
+ * Safely parses a date string into a Date object.
+ * Used for parsing datetime constraints in custom field validation.
+ *
+ * @param dateStr - The date string to parse
+ * @returns Parsed Date object or undefined if invalid
+ */
+function parseDate(dateStr: string | undefined | null): Date | undefined {
+    if (!dateStr) return undefined;
+    const date = new Date(dateStr);
+    return isNaN(date.getTime()) ? undefined : date;
+}
+
+/**
+ * Creates a Zod validation schema for datetime fields with optional min/max constraints.
+ * Supports both string and Date inputs, which is common in form handling.
+ *
+ * @param minDate - Optional minimum date constraint
+ * @param maxDate - Optional maximum date constraint
+ * @returns Zod schema that validates date ranges
+ */
+function createDateValidationSchema(minDate: Date | undefined, maxDate: Date | undefined): ZodType {
+    const baseSchema = z.union([z.string(), z.date()]);
+    if (!minDate && !maxDate) return baseSchema;
+
+    const dateMinString = minDate?.toLocaleDateString() ?? '';
+    const dateMaxString = maxDate?.toLocaleDateString() ?? '';
+    const dateMinMessage = minDate ? `Date must be after ${dateMinString}` : '';
+    const dateMaxMessage = maxDate ? `Date must be before ${dateMaxString}` : '';
+
+    return baseSchema.refine(
+        val => {
+            if (!val) return true;
+            const date = val instanceof Date ? val : new Date(val);
+            if (minDate && date < minDate) return false;
+            if (maxDate && date > maxDate) return false;
+            return true;
+        },
+        val => {
+            const date = val instanceof Date ? val : new Date(val);
+            if (minDate && date < minDate) return { message: dateMinMessage };
+            if (maxDate && date > maxDate) return { message: dateMaxMessage };
+            return { message: '' };
+        },
+    );
+}
+
+/**
+ * Creates a Zod validation schema for string fields with optional regex pattern validation.
+ * Used for string-type custom fields that may have pattern constraints.
+ *
+ * @param pattern - Optional regex pattern string for validation
+ * @returns Zod string schema with optional pattern validation
+ */
+function createStringValidationSchema(pattern?: string): ZodType {
+    let schema = z.string();
+    if (pattern) {
+        schema = schema.regex(new RegExp(pattern), {
+            message: `Value must match pattern: ${pattern}`,
+        });
+    }
+    return schema;
+}
+
+/**
+ * Creates a Zod validation schema for integer fields with optional min/max constraints.
+ * Used for int-type custom fields that may have numeric range limits.
+ *
+ * @param min - Optional minimum value constraint
+ * @param max - Optional maximum value constraint
+ * @returns Zod number schema with optional range validation
+ */
+function createIntValidationSchema(min?: number, max?: number): ZodType {
+    let schema = z.number();
+    if (min !== undefined) {
+        schema = schema.min(min, {
+            message: `Value must be at least ${min}`,
+        });
+    }
+    if (max !== undefined) {
+        schema = schema.max(max, {
+            message: `Value must be at most ${max}`,
+        });
+    }
+    return schema;
+}
+
+/**
+ * Creates a Zod validation schema for float fields with optional min/max constraints.
+ * Used for float-type custom fields that may have numeric range limits.
+ *
+ * @param min - Optional minimum value constraint
+ * @param max - Optional maximum value constraint
+ * @returns Zod number schema with optional range validation
+ */
+function createFloatValidationSchema(min?: number, max?: number): ZodType {
+    let schema = z.number();
+    if (min !== undefined) {
+        schema = schema.min(min, {
+            message: `Value must be at least ${min}`,
+        });
+    }
+    if (max !== undefined) {
+        schema = schema.max(max, {
+            message: `Value must be at most ${max}`,
+        });
+    }
+    return schema;
+}
+
+/**
+ * Creates a Zod validation schema for a single custom field based on its type and constraints.
+ * This is the main dispatcher that routes different custom field types to their specific
+ * validation schema creators. Handles all standard custom field types in Vendure.
+ *
+ * @param customField - The custom field configuration object
+ * @returns Zod schema appropriate for the custom field type
+ */
+function createCustomFieldValidationSchema(customField: CustomFieldConfig): ZodType {
+    let zodType: ZodType;
+
+    switch (customField.type) {
+        case 'localeString':
+        case 'localeText':
+        case 'string':
+            zodType = createStringValidationSchema(customField.pattern);
+            break;
+        case 'int':
+            zodType = createIntValidationSchema(customField.intMin, customField.intMax);
+            break;
+        case 'float':
+            zodType = createFloatValidationSchema(customField.floatMin, customField.floatMax);
+            break;
+        case 'datetime': {
+            const minDate = parseDate(customField.datetimeMin);
+            const maxDate = parseDate(customField.datetimeMax);
+            zodType = createDateValidationSchema(minDate, maxDate);
+            break;
+        }
+        case 'boolean':
+            zodType = z.boolean();
+            break;
+        default:
+            zodType = z.any();
+            break;
+    }
+
+    return zodType;
+}
+
+/**
+ * Creates a Zod validation schema for struct-type custom fields.
+ * Struct fields contain nested sub-fields, each with their own validation rules.
+ * This recursively processes each sub-field to create a nested object schema.
+ *
+ * @param structFieldConfig - The struct custom field configuration with nested fields
+ * @returns Zod object schema representing the struct with all sub-field validations
+ */
+function createStructFieldSchema(structFieldConfig: StructCustomFieldConfig): ZodType {
+    if (!structFieldConfig.fields || !Array.isArray(structFieldConfig.fields)) {
+        return z.object({}).passthrough();
+    }
+
+    const nestedSchema: ZodRawShape = {};
+    for (const structSubField of structFieldConfig.fields) {
+        const config = mapGraphQLCustomFieldToConfig(structSubField as StructFieldConfig);
+        let subFieldType = createCustomFieldValidationSchema(config);
+
+        // Handle list and nullable for struct sub-fields
+        if (config.list) {
+            subFieldType = z.array(subFieldType);
+        }
+        if (config.nullable) {
+            subFieldType = subFieldType.optional().nullable();
+        }
+
+        nestedSchema[config.name] = subFieldType;
+    }
+
+    return z.object(nestedSchema);
+}
+
+/**
+ * Applies common list and nullable modifiers to a Zod schema based on custom field configuration.
+ * Many custom fields can be configured as lists (arrays) and/or nullable, so this helper
+ * centralizes that logic to avoid duplication.
+ *
+ * @param zodType - The base Zod schema to modify
+ * @param customField - Custom field config containing list/nullable flags
+ * @returns Modified Zod schema with list/nullable modifiers applied
+ */
+function applyListAndNullableModifiers(zodType: ZodType, customField: CustomFieldConfig): ZodType {
+    let modifiedType = zodType;
+
+    if (customField.list) {
+        modifiedType = z.array(modifiedType);
+    }
+    if (customField.nullable !== false) {
+        modifiedType = modifiedType.optional().nullable();
+    }
+
+    return modifiedType;
+}
+
+/**
+ * Processes all custom fields and creates a complete validation schema for the customFields object.
+ * Handles context-aware filtering (translation vs root context) and orchestrates the creation
+ * of validation schemas for all custom field types including complex struct fields.
+ *
+ * @param customFieldConfigs - Array of all custom field configurations
+ * @param isTranslationContext - Whether we're processing fields for translation forms
+ * @returns Zod schema shape for the entire customFields object
+ */
+function processCustomFieldsSchema(
+    customFieldConfigs: CustomFieldConfig[],
+    isTranslationContext: boolean,
+): ZodRawShape {
+    const customFieldsSchema: ZodRawShape = {};
+    const translatableTypes = ['localeString', 'localeText'];
+
+    const filteredCustomFields = customFieldConfigs.filter(cf => {
+        if (isTranslationContext) {
+            return translatableTypes.includes(cf.type);
+        } else {
+            return !translatableTypes.includes(cf.type);
+        }
+    });
+
+    for (const customField of filteredCustomFields) {
+        let zodType: ZodType;
+
+        if (customField.type === 'struct') {
+            zodType = createStructFieldSchema(customField as StructCustomFieldConfig);
+        } else {
+            zodType = createCustomFieldValidationSchema(customField);
+        }
+
+        zodType = applyListAndNullableModifiers(zodType, customField);
+        const schemaPropertyName = getGraphQlInputName(customField);
+        customFieldsSchema[schemaPropertyName] = zodType;
+    }
+
+    return customFieldsSchema;
+}
+
+export function createFormSchemaFromFields(
+    fields: FieldInfo[],
+    customFieldConfigs?: CustomFieldConfig[],
+    isTranslationContext = false,
+) {
     const schemaConfig: ZodRawShape = {};
+
     for (const field of fields) {
         const isScalar = isScalarType(field.type);
         const isEnum = isEnumType(field.type);
-        if (isScalar || isEnum) {
-            schemaConfig[field.name] = getZodTypeFromField(field);
+
+        if ((isScalar || isEnum) && field.name !== 'customFields') {
+            schemaConfig[field.name] = getZodTypeFromField(field, customFieldConfigs);
+        } else if (field.name === 'customFields') {
+            const customFieldsSchema =
+                customFieldConfigs && customFieldConfigs.length > 0
+                    ? processCustomFieldsSchema(customFieldConfigs, isTranslationContext)
+                    : {};
+            schemaConfig[field.name] = z.object(customFieldsSchema).optional();
         } else if (field.typeInfo) {
-            let nestedType: ZodType = createFormSchemaFromFields(field.typeInfo);
+            const isNestedTranslationContext = field.name === 'translations' || isTranslationContext;
+            let nestedType: ZodType = createFormSchemaFromFields(
+                field.typeInfo,
+                customFieldConfigs,
+                isNestedTranslationContext,
+            );
+
             if (field.nullable) {
                 nestedType = nestedType.optional().nullable();
             }
             if (field.list) {
                 nestedType = z.array(nestedType);
             }
+
             schemaConfig[field.name] = nestedType;
         }
     }
+
     return z.object(schemaConfig);
 }
 
@@ -69,8 +391,12 @@ export function getDefaultValueFromField(field: FieldInfo, defaultLanguageCode?:
     }
 }
 
-export function getZodTypeFromField(field: FieldInfo): ZodTypeAny {
+export function getZodTypeFromField(field: FieldInfo, customFieldConfigs?: CustomFieldConfig[]): ZodTypeAny {
     let zodType: ZodType;
+
+    // This function is only used for non-custom fields, so we don't need custom field logic here
+    // Custom fields are handled separately in createFormSchemaFromFields
+
     switch (field.type) {
         case 'String':
         case 'ID':
@@ -88,6 +414,7 @@ export function getZodTypeFromField(field: FieldInfo): ZodTypeAny {
         default:
             zodType = z.any();
     }
+
     if (field.list) {
         zodType = z.array(zodType);
     }
@@ -96,3 +423,11 @@ export function getZodTypeFromField(field: FieldInfo): ZodTypeAny {
     }
     return zodType;
 }
+
+export function getGraphQlInputName(config: { name: string; type: string; list?: boolean }): string {
+    if (config.type === 'relation') {
+        return config.list === true ? `${config.name}Ids` : `${config.name}Id`;
+    } else {
+        return config.name;
+    }
+}

package/src/lib/framework/form-engine/overridden-form-component.tsx

@@ -0,0 +1,51 @@
+import {
+    DataDisplayComponent,
+    DataInputComponent,
+    useComponentRegistry,
+} from '@/vdb/framework/component-registry/component-registry.js';
+import { generateInputComponentKey } from '@/vdb/framework/extension-api/input-component-extensions.js';
+import { usePageBlock } from '@/vdb/hooks/use-page-block.js';
+import { usePage } from '@/vdb/hooks/use-page.js';
+import { ControllerRenderProps, FieldPath, FieldValues } from 'react-hook-form';
+
+export interface OverriddenFormComponent<
+    TFieldValues extends FieldValues = any,
+    TName extends FieldPath<TFieldValues> = any,
+> {
+    fieldName: string;
+    field: ControllerRenderProps<TFieldValues, TName>;
+    children?: React.ReactNode;
+}
+
+/**
+ * @description
+ * Based on the pageId and blockId of where this is placed, it will check whether any custom components
+ * are registered and render them if so. Otherwise, it will render the children, which act as the
+ * default if this location has not been overridden.
+ *
+ * ```tsx
+ * <OverriddenFormComponent fieldName="myField" field={field}>
+ *   <Input {...field} />
+ * </OverriddenFormComponent>
+ * ```
+ */
+export function OverriddenFormComponent({ fieldName, field, children }: Readonly<OverriddenFormComponent>) {
+    const page = usePage();
+    const pageBlock = usePageBlock({ optional: true });
+    const componentRegistry = useComponentRegistry();
+    let DisplayComponent: DataDisplayComponent | undefined;
+    let InputComponent: DataInputComponent | undefined;
+    if (page.pageId && pageBlock?.blockId) {
+        const customInputComponentKey = generateInputComponentKey(page.pageId, pageBlock.blockId, fieldName);
+        DisplayComponent = componentRegistry.getDisplayComponent(customInputComponentKey);
+        InputComponent = componentRegistry.getInputComponent(customInputComponentKey);
+    }
+    if (DisplayComponent) {
+        return <DisplayComponent {...field} />;
+    }
+
+    if (InputComponent) {
+        return <InputComponent {...field} />;
+    }
+    return children ?? null;
+}

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

@@ -1,26 +1,29 @@
-import { getOperationVariablesFields } from '@/framework/document-introspection/get-document-structure.js';
-import {
-    createFormSchemaFromFields,
-    getDefaultValuesFromFields,
-} from '@/framework/form-engine/form-schema-tools.js';
-import { useChannel } from '@/hooks/use-channel.js';
-import { useServerConfig } from '@/hooks/use-server-config.js';
 import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
 import { zodResolver } from '@hookform/resolvers/zod';
 import { VariablesOf } from 'gql.tada';
 import { FormEvent } from 'react';
 import { useForm } from 'react-hook-form';
+import { useChannel } from '../../hooks/use-channel.js';
+import { useServerConfig } from '../../hooks/use-server-config.js';
+import { getOperationVariablesFields } from '../document-introspection/get-document-structure.js';
+import { createFormSchemaFromFields, getDefaultValuesFromFields } from './form-schema-tools.js';
+import { removeEmptyIdFields, transformRelationFields } from './utils.js';
 
 export interface GeneratedFormOptions<
     T extends TypedDocumentNode<any, any>,
-    VarName extends (keyof VariablesOf<T>) | undefined = '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>) => VarName extends keyof VariablesOf<T> ? VariablesOf<T>[VarName] : VariablesOf<T>;
-    onSubmit?: (values: VarName extends keyof VariablesOf<T> ? VariablesOf<T>[VarName] : VariablesOf<T>) => void;
+    customFieldConfig?: any[]; // Add custom field config for validation
+    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;
 }
 
 /**
@@ -35,13 +38,19 @@ export function useGeneratedForm<
     VarName extends keyof VariablesOf<T> | undefined,
     E extends Record<string, any> = Record<string, any>,
 >(options: GeneratedFormOptions<T, VarName, E>) {
-    const { document, entity, setValues, onSubmit, varName } = options;
+    const { document, entity, setValues, onSubmit, varName, customFieldConfig } = options;
     const { activeChannel } = useChannel();
-    const availableLanguages = useServerConfig()?.availableLanguages || [];
+    const serverConfig = useServerConfig();
+    const availableLanguages = serverConfig?.availableLanguages || [];
     const updateFields = document ? getOperationVariablesFields(document, varName) : [];
-    const schema = createFormSchemaFromFields(updateFields);
+
+    const schema = createFormSchemaFromFields(updateFields, customFieldConfig);
     const defaultValues = getDefaultValuesFromFields(updateFields, activeChannel?.defaultLanguageCode);
-    const processedEntity = ensureTranslationsForAllLanguages(entity, availableLanguages);
+    const processedEntity = ensureTranslationsForAllLanguages(entity, availableLanguages, defaultValues);
+
+    const values = processedEntity
+        ? transformRelationFields(updateFields, setValues(processedEntity))
+        : defaultValues;
 
     const form = useForm({
         resolver: async (values, context, options) => {
@@ -53,14 +62,28 @@ export function useGeneratedForm<
         },
         mode: 'onChange',
         defaultValues,
-        values: processedEntity ? setValues(processedEntity) : defaultValues,
+        values,
     });
-    let submitHandler = (event: FormEvent) => {
+    let submitHandler = (event: FormEvent): any => {
         event.preventDefault();
     };
     if (onSubmit) {
-        submitHandler = (event: FormEvent) => {
-            form.handleSubmit(onSubmit as any)(event);
+        submitHandler = async (event: FormEvent) => {
+            event.preventDefault();
+
+            // Trigger validation on ALL fields, not just dirty ones
+            const isValid = await form.trigger();
+
+            if (!isValid) {
+                console.log(`Form invalid!`);
+                event.stopPropagation();
+                return;
+            }
+
+            const onSubmitWrapper = (values: any) => {
+                onSubmit(removeEmptyIdFields(values, updateFields));
+            };
+            form.handleSubmit(onSubmitWrapper)(event);
         };
     }
 
@@ -69,11 +92,13 @@ export function useGeneratedForm<
 
 /**
  * Ensures that an entity with translations has entries for all available languages.
- * If a language is missing, it creates an empty translation based on the structure of existing translations.
+ * If a language is missing, it creates an empty translation based on the structure of existing translations
+ * and the expected form structure from defaultValues.
  */
 function ensureTranslationsForAllLanguages<E extends Record<string, any>>(
     entity: E | null | undefined,
     availableLanguages: string[] = [],
+    expectedStructure?: Record<string, any>,
 ): E | null | undefined {
     if (
         !entity ||
@@ -91,23 +116,56 @@ function ensureTranslationsForAllLanguages<E extends Record<string, any>>(
     // Get existing language codes
     const existingLanguageCodes = new Set(translations.map((t: any) => t.languageCode));
 
+    // Get the expected translation structure from defaultValues or existing translations
+    const existingTemplate = translations[0] || {};
+    const expectedTranslationStructure = expectedStructure?.translations?.[0] || {};
+
+    // Merge the structures to ensure we have all expected fields
+    const templateStructure = {
+        ...expectedTranslationStructure,
+        ...existingTemplate,
+    };
+
     // Add missing language translations
     for (const langCode of availableLanguages) {
         if (!existingLanguageCodes.has(langCode)) {
-            // Find a translation to use as template for field structure
-            const template = translations[0] || {};
             const emptyTranslation: Record<string, any> = {
                 languageCode: langCode,
             };
 
-            // Add empty fields based on template (excluding languageCode)
-            Object.keys(template).forEach(key => {
+            // Add empty fields based on merged template structure (excluding languageCode)
+            Object.keys(templateStructure).forEach(key => {
                 if (key !== 'languageCode') {
-                    emptyTranslation[key] = '';
+                    if (typeof templateStructure[key] === 'object' && templateStructure[key] !== null) {
+                        // For nested objects like customFields, create an empty object
+                        emptyTranslation[key] = Array.isArray(templateStructure[key]) ? [] : {};
+                    } else {
+                        // For primitive values, use empty string as default
+                        emptyTranslation[key] = '';
+                    }
                 }
             });
 
             translations.push(emptyTranslation);
+        } else {
+            // For existing translations, ensure they have all expected fields
+            const existingTranslation = translations.find((t: any) => t.languageCode === langCode);
+            if (existingTranslation) {
+                Object.keys(expectedTranslationStructure).forEach(key => {
+                    if (key !== 'languageCode' && !(key in existingTranslation)) {
+                        if (
+                            typeof expectedTranslationStructure[key] === 'object' &&
+                            expectedTranslationStructure[key] !== null
+                        ) {
+                            existingTranslation[key] = Array.isArray(expectedTranslationStructure[key])
+                                ? []
+                                : {};
+                        } else {
+                            existingTranslation[key] = '';
+                        }
+                    }
+                });
+            }
         }
     }
 

package/src/lib/framework/form-engine/utils.spec.ts

@@ -0,0 +1,37 @@
+import { graphql, VariablesOf } from 'gql.tada';
+import { describe, expect, it } from 'vitest';
+
+import { getOperationVariablesFields } from '../document-introspection/get-document-structure.js';
+
+import { removeEmptyIdFields } from './utils.js';
+
+const createProductDocument = graphql(`
+    mutation CreateProduct($input: CreateProductInput!) {
+        createProduct(input: $input) {
+            id
+        }
+    }
+`);
+
+type CreateProductInput = VariablesOf<typeof createProductDocument>;
+
+describe('removeEmptyIdFields', () => {
+    it('should remove empty translation id field', () => {
+        const values: CreateProductInput = {
+            input: { translations: [{ id: '', languageCode: 'en' }] },
+        };
+        const fields = getOperationVariablesFields(createProductDocument);
+        const result = removeEmptyIdFields(values, fields);
+
+        expect(result).toEqual({ input: { translations: [{ languageCode: 'en' }] } });
+    });
+
+    it('should remove empty featuredAsset id field', () => {
+        const values: CreateProductInput = {
+            input: { featuredAssetId: '', translations: [] },
+        };
+        const fields = getOperationVariablesFields(createProductDocument);
+        const result = removeEmptyIdFields(values, fields);
+        expect(result).toEqual({ input: { translations: [] } });
+    });
+});