@wilshop/dashboard 3.5.2

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

@@ -0,0 +1,417 @@
+import {
+    FieldInfo,
+    isEnumType,
+    isScalarType,
+} from '@/vdb/framework/document-introspection/get-document-structure.js';
+import {
+    CustomFieldConfig,
+    DateTimeCustomFieldConfig,
+    FloatCustomFieldConfig,
+    IntCustomFieldConfig,
+    StringCustomFieldConfig,
+    StructCustomFieldConfig,
+    StructField,
+} from '@/vdb/framework/form-engine/form-engine-types.js';
+import { z, ZodRawShape, ZodType, ZodTypeAny } from 'zod';
+
+function mapGraphQLCustomFieldToConfig(field: StructField) {
+    const { __typename, ...rest } = field;
+    const baseConfig: CustomFieldConfig = {
+        ...rest,
+        list: field.list ?? false,
+        readonly: false,
+        requiresPermission: [],
+        nullable: true, // Default to true since GraphQL fields are nullable by default
+    };
+
+    switch (field.__typename) {
+        case 'StringStructFieldConfig':
+            return {
+                ...baseConfig,
+                __typename: 'StringCustomFieldConfig',
+                pattern: field.pattern ?? null,
+                options: [],
+            } satisfies StringCustomFieldConfig;
+        case 'IntStructFieldConfig':
+            return {
+                ...baseConfig,
+                __typename: 'IntCustomFieldConfig',
+                intMin: field.intMin ?? null,
+                intMax: field.intMax ?? null,
+                intStep: field.intStep ?? null,
+            } satisfies IntCustomFieldConfig;
+        case 'FloatStructFieldConfig':
+            return {
+                ...baseConfig,
+                __typename: 'FloatCustomFieldConfig',
+                floatMin: field.floatMin ?? null,
+                floatMax: field.floatMax ?? null,
+                floatStep: field.floatStep ?? null,
+            } satisfies FloatCustomFieldConfig;
+        case 'DateTimeStructFieldConfig':
+            return {
+                ...baseConfig,
+                __typename: 'DateTimeCustomFieldConfig',
+                datetimeMin: field.datetimeMin ?? null,
+                datetimeMax: field.datetimeMax ?? null,
+                datetimeStep: field.datetimeStep ?? null,
+            } satisfies DateTimeCustomFieldConfig;
+        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 | null): 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 createNumberValidationSchema(min?: number | null, max?: number | null): ZodType {
+    let schema = z.number();
+    if (min != null) {
+        schema = schema.min(min, {
+            message: `Value must be at least ${min}`,
+        });
+    }
+    if (max != null) {
+        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 as StringCustomFieldConfig).pattern);
+            break;
+        case 'int':
+            zodType = createNumberValidationSchema(
+                (customField as IntCustomFieldConfig).intMin,
+                (customField as IntCustomFieldConfig).intMax,
+            );
+            break;
+        case 'float':
+            zodType = createNumberValidationSchema(
+                (customField as FloatCustomFieldConfig).floatMin,
+                (customField as FloatCustomFieldConfig).floatMax,
+            );
+            break;
+        case 'datetime': {
+            const minDate = parseDate((customField as DateTimeCustomFieldConfig).datetimeMin);
+            const maxDate = parseDate((customField as DateTimeCustomFieldConfig).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);
+        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 applyCustomFieldModifiers(zodType: ZodType, customField: CustomFieldConfig): ZodType {
+    let modifiedType = zodType;
+
+    if (customField.list) {
+        modifiedType = z.array(modifiedType);
+    }
+    if (customField.nullable !== false) {
+        modifiedType = modifiedType.optional().nullable();
+    }
+    if (customField.readonly) {
+        modifiedType = modifiedType.readonly();
+    }
+    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 = applyCustomFieldModifiers(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) && field.name !== 'customFields') {
+            schemaConfig[field.name] = getZodTypeFromField(field);
+        } 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) {
+            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);
+}
+
+export function getDefaultValuesFromFields(fields: FieldInfo[], defaultLanguageCode?: string) {
+    const defaultValues: Record<string, any> = {};
+    for (const field of fields) {
+        if (field.typeInfo) {
+            const nestedObjectDefaults = getDefaultValuesFromFields(field.typeInfo, defaultLanguageCode);
+            if (field.list) {
+                defaultValues[field.name] = [nestedObjectDefaults];
+            } else {
+                defaultValues[field.name] = nestedObjectDefaults;
+            }
+        } else {
+            defaultValues[field.name] = getDefaultValueFromField(field, defaultLanguageCode);
+        }
+    }
+    return defaultValues;
+}
+
+export function getDefaultValueFromField(field: FieldInfo, defaultLanguageCode?: string) {
+    if (field.list) {
+        return [];
+    }
+    switch (field.type) {
+        case 'String':
+        case 'DateTime':
+            return '';
+        case 'Int':
+        case 'Float':
+        case 'Money':
+            return 0;
+        case 'Boolean':
+            return false;
+        case 'ID':
+            return '';
+        case 'LanguageCode':
+            return defaultLanguageCode || 'en';
+        case 'JSON':
+            return {};
+        default: {
+            return '';
+        }
+    }
+}
+
+export function getZodTypeFromField(field: FieldInfo): 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':
+        case 'DateTime':
+            zodType = z.string();
+            break;
+        case 'Int':
+        case 'Float':
+        case 'Money':
+            zodType = z.number();
+            break;
+        case 'Boolean':
+            zodType = z.boolean();
+            break;
+        default:
+            zodType = z.any();
+    }
+
+    if (field.list) {
+        zodType = z.array(zodType);
+    }
+    if (field.nullable) {
+        zodType = zodType.optional().nullable();
+    }
+    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,
+    useComponentRegistry,
+} from '@/vdb/framework/component-registry/component-registry.js';
+import { generateInputComponentKey } from '@/vdb/framework/extension-api/input-component-extensions.js';
+import { DashboardFormComponent } from '@/vdb/framework/form-engine/form-engine-types.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: DashboardFormComponent | 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

@@ -0,0 +1,226 @@
+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 type WithLooseCustomFields<T> = T extends { customFields?: any }
+    ? Omit<T, 'customFields'> & { customFields?: T['customFields'] | unknown }
+    : T;
+
+/**
+ * @description
+ * Options for the useGeneratedForm hook.
+ *
+ * @docsCategory detail-views
+ * @docsPage useGeneratedForm
+ * @since 3.3.0
+ */
+export interface GeneratedFormOptions<
+    T extends TypedDocumentNode<any, any>,
+    VarName extends keyof VariablesOf<T> | undefined = 'input',
+    E extends Record<string, any> = Record<string, any>,
+> {
+    /**
+     * @description
+     * The document to use to generate the form.
+     */
+    document?: T;
+    /**
+     * @description
+     * The name of the variable to use in the document.
+     */
+    varName?: VarName;
+    /**
+     * @description
+     * The entity to use to generate the form.
+     */
+    entity: E | null | undefined;
+    customFieldConfig?: any[]; // Add custom field config for validation
+    setValues: (
+        entity: NonNullable<E>,
+    ) => WithLooseCustomFields<
+        VarName extends keyof VariablesOf<T> ? VariablesOf<T>[VarName] : VariablesOf<T>
+    >;
+    onSubmit?: (
+        values: VarName extends keyof VariablesOf<T> ? VariablesOf<T>[VarName] : VariablesOf<T>,
+    ) => void;
+}
+
+/**
+ * @description
+ * This hook is used to create a form from a document and an entity.
+ * It will create a form with the fields defined in the document's input type.
+ * It will also create a submit handler that will submit the form to the server.
+ *
+ * This hook is mostly used internally by the higher-level {@link useDetailPage} hook,
+ * but can in some cases be useful to use directly.
+ *
+ * @example
+ * ```tsx
+ * const { form, submitHandler } = useGeneratedForm({
+ *  document: setDraftOrderCustomFieldsDocument,
+ *  varName: undefined,
+ *  entity: entity,
+ *  setValues: entity => {
+ *    return {
+ *      orderId: entity.id,
+ *      input: {
+ *        customFields: entity.customFields,
+ *      },
+ *    };
+ *  },
+ * });
+ * ```
+ *
+ * @docsCategory detail-views
+ * @docsPage useGeneratedForm
+ * @since 3.3.0
+ * @docsWeight 0
+ */
+export function useGeneratedForm<
+    T extends TypedDocumentNode<any, any>,
+    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, customFieldConfig } = options;
+    const { activeChannel } = useChannel();
+    const serverConfig = useServerConfig();
+    const availableLanguages = serverConfig?.availableLanguages || [];
+    const updateFields = document ? getOperationVariablesFields(document, varName) : [];
+
+    const schema = createFormSchemaFromFields(updateFields, customFieldConfig);
+    const defaultValues = getDefaultValuesFromFields(updateFields, activeChannel?.defaultLanguageCode);
+    const processedEntity = ensureTranslationsForAllLanguages(entity, availableLanguages, defaultValues);
+
+    const values = processedEntity
+        ? transformRelationFields(updateFields, setValues(processedEntity))
+        : defaultValues;
+
+    const form = useForm({
+        resolver: async (values, context, options) => {
+            const result = await zodResolver(schema)(values, context, options);
+            if (Object.keys(result.errors).length > 0) {
+                console.log('Zod form validation errors:', result.errors);
+            }
+            return result;
+        },
+        mode: 'onChange',
+        defaultValues,
+        values,
+    });
+    let submitHandler = (event: FormEvent): any => {
+        event.preventDefault();
+    };
+    if (onSubmit) {
+        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);
+        };
+    }
+
+    return { form, submitHandler };
+}
+
+/**
+ * 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
+ * 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 ||
+        !('translations' in entity) ||
+        !Array.isArray((entity as any).translations) ||
+        !availableLanguages.length
+    ) {
+        return entity;
+    }
+
+    // Create a deep copy of the entity to avoid mutation
+    const processedEntity = { ...entity } as any;
+    const translations = [...(processedEntity.translations || [])];
+
+    // 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)) {
+            const emptyTranslation: Record<string, any> = {
+                languageCode: langCode,
+            };
+
+            // Add empty fields based on merged template structure (excluding languageCode)
+            Object.keys(templateStructure).forEach(key => {
+                if (key !== 'languageCode') {
+                    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] = '';
+                        }
+                    }
+                });
+            }
+        }
+    }
+
+    // Update the processed entity with complete translations
+    processedEntity.translations = translations;
+
+    return processedEntity as E;
+}