@vendure/dashboard 3.4.1-master-202508210231 → 3.4.1

package/src/lib/framework/form-engine/form-engine-types.ts

@@ -0,0 +1,163 @@
+import { configurableOperationDefFragment } from '@/vdb/graphql/fragments.js';
+import {
+    allCustomFieldsFragment,
+    booleanCustomFieldFragment,
+    customFieldConfigFragment,
+    dateTimeCustomFieldFragment,
+    floatCustomFieldFragment,
+    intCustomFieldFragment,
+    localeStringCustomFieldFragment,
+    localeTextCustomFieldFragment,
+    relationCustomFieldFragment,
+    stringCustomFieldFragment,
+    structCustomFieldFragment,
+    textCustomFieldFragment,
+} from '@/vdb/providers/server-config.js';
+import { ResultOf } from 'gql.tada';
+import React from 'react';
+import { ControllerRenderProps, FieldPath, FieldValues } from 'react-hook-form';
+
+// Base custom field config
+export type CustomFieldConfig = ResultOf<typeof customFieldConfigFragment>;
+
+// Individual custom field type configurations
+export type StringCustomFieldConfig = ResultOf<typeof stringCustomFieldFragment>;
+export type LocaleStringCustomFieldConfig = ResultOf<typeof localeStringCustomFieldFragment>;
+export type TextCustomFieldConfig = ResultOf<typeof textCustomFieldFragment>;
+export type LocaleTextCustomFieldConfig = ResultOf<typeof localeTextCustomFieldFragment>;
+export type BooleanCustomFieldConfig = ResultOf<typeof booleanCustomFieldFragment>;
+export type IntCustomFieldConfig = ResultOf<typeof intCustomFieldFragment>;
+export type FloatCustomFieldConfig = ResultOf<typeof floatCustomFieldFragment>;
+export type DateTimeCustomFieldConfig = ResultOf<typeof dateTimeCustomFieldFragment>;
+export type RelationCustomFieldConfig = ResultOf<typeof relationCustomFieldFragment>;
+export type StructCustomFieldConfig = ResultOf<typeof structCustomFieldFragment>;
+
+// Union type of all custom field configs
+export type AllCustomFieldConfigs = ResultOf<typeof allCustomFieldsFragment>;
+
+// Configurable operation argument definition
+export type ConfigurableArgDef = ResultOf<typeof configurableOperationDefFragment>['args'][number];
+
+// Union type for all field definitions
+export type ConfigurableFieldDef = AllCustomFieldConfigs | ConfigurableArgDef;
+
+// Struct field types (used within struct custom fields)
+export type StructField = StructCustomFieldConfig['fields'][number];
+
+// Individual struct field type configurations (for type guards)
+export type StringStructField = Extract<StructField, { type: 'string' }>;
+export type IntStructField = Extract<StructField, { type: 'int' }>;
+export type FloatStructField = Extract<StructField, { type: 'float' }>;
+export type BooleanStructField = Extract<StructField, { type: 'boolean' }>;
+export type DateTimeStructField = Extract<StructField, { type: 'datetime' }>;
+
+/**
+ * @description
+ * Props that get passed to all form input components. They are based on the
+ * controller props used by the underlying `react-hook-form`, i.e.:
+ *
+ * ```ts
+ * export type ControllerRenderProps = {
+ *     onChange: (event: any) => void;
+ *     onBlur: () => void;
+ *     value: any;
+ *     disabled?: boolean;
+ *     name: string;
+ *     ref: RefCallBack;
+ * };
+ * ```
+ *
+ * in addition, they can optionally be passed a `fieldDef` prop if the
+ * component is used in the context of a custom field or configurable operation arg.
+ *
+ * The `fieldDef` arg, when present, has the following shape:
+ *
+ * ```ts
+ * export type ConfigurableArgDef = {
+ *     defaultValue: any
+ *     description: string | null
+ *     label: string | null
+ *     list: boolean
+ *     name: string
+ *     required: boolean
+ *     type: string
+ *     ui: any
+ * }
+ * ```
+ *
+ * @docsCategory forms
+ * @docsPage DashboardFormComponent
+ */
+export type DashboardFormComponentProps<
+    TFieldValues extends FieldValues = FieldValues,
+    TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+> = ControllerRenderProps<TFieldValues, TName> & {
+    fieldDef?: ConfigurableFieldDef;
+};
+
+/**
+ * @description
+ * Metadata which can be defined on a {@link DashboardFormComponent} which
+ * provides additional information about how the dashboard should render the
+ * component.
+ *
+ * The metadata is defined by adding the static property on the component:
+ *
+ * @example
+ * ```ts
+ * export const MyCustomInput: DashboardFormComponent = props => {
+ *   // implementation omitted
+ * }
+ *
+ * // highlight-start
+ * MyCustomInput.metadata = {
+ *   isListInput: true
+ * }
+ * // highlight-end
+ * ```
+ *
+ * @docsCategory forms
+ * @docsPage DashboardFormComponent
+ */
+export type DashboardFormComponentMetadata = {
+    /**
+     * @description
+     * Defines whether this form component is designed to handle list inputs.
+     * If set to `'dynamic'`, it means the component has internal logic that can
+     * handle both lists and single values.
+     */
+    isListInput?: boolean | 'dynamic';
+    isFullWidth?: boolean;
+};
+
+/**
+ * @description
+ * This is the common type for all custom form components registered for:
+ *
+ * - custom fields
+ * - configurable operation args
+ * - detail page fields
+ *
+ * Here's a simple example:
+ *
+ * ```ts
+ * import { DashboardFormComponent, Input } from '\@vendure/dashboard';
+ *
+ * const MyComponent: DashboardFormComponent = (props) => {
+ *     return <Input value={props.value}
+ *                   onChange={props.onChange}
+ *                   onBlur={props.onBlur}
+ *                   name={props.name}
+ *                   disabled={props.disabled}
+ *                   ref={props.ref}
+ *                   />;
+ * };
+ * ```
+ *
+ * @docsCategory forms
+ * @docsPage DashboardFormComponent
+ * @docsWeight 0
+ */
+export type DashboardFormComponent = React.ComponentType<DashboardFormComponentProps> & {
+    metadata?: DashboardFormComponentMetadata;
+};

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

@@ -3,33 +3,24 @@ import {
     isEnumType,
     isScalarType,
 } from '@/vdb/framework/document-introspection/get-document-structure.js';
-import { StructCustomFieldConfig } from '@vendure/common/lib/generated-types';
-import { ResultOf } from 'gql.tada';
+import {
+    CustomFieldConfig,
+    DateTimeCustomFieldConfig,
+    FloatCustomFieldConfig,
+    IntCustomFieldConfig,
+    StringCustomFieldConfig,
+    StructCustomFieldConfig,
+    StructField,
+} from '@/vdb/framework/form-engine/form-engine-types.js';
 import { z, ZodRawShape, ZodType, ZodTypeAny } from 'zod';
 
-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,
+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
     };
 
@@ -37,26 +28,34 @@ function mapGraphQLCustomFieldToConfig(field: StructFieldConfig): CustomFieldCon
         case 'StringStructFieldConfig':
             return {
                 ...baseConfig,
-                pattern: field.pattern ?? undefined,
-            };
+                __typename: 'StringCustomFieldConfig',
+                pattern: field.pattern ?? null,
+                options: [],
+            } satisfies StringCustomFieldConfig;
         case 'IntStructFieldConfig':
             return {
                 ...baseConfig,
-                intMin: field.intMin ?? undefined,
-                intMax: field.intMax ?? undefined,
-            };
+                __typename: 'IntCustomFieldConfig',
+                intMin: field.intMin ?? null,
+                intMax: field.intMax ?? null,
+                intStep: field.intStep ?? null,
+            } satisfies IntCustomFieldConfig;
         case 'FloatStructFieldConfig':
             return {
                 ...baseConfig,
-                floatMin: field.floatMin ?? undefined,
-                floatMax: field.floatMax ?? undefined,
-            };
+                __typename: 'FloatCustomFieldConfig',
+                floatMin: field.floatMin ?? null,
+                floatMax: field.floatMax ?? null,
+                floatStep: field.floatStep ?? null,
+            } satisfies FloatCustomFieldConfig;
         case 'DateTimeStructFieldConfig':
             return {
                 ...baseConfig,
-                datetimeMin: field.datetimeMin ?? undefined,
-                datetimeMax: field.datetimeMax ?? undefined,
-            };
+                __typename: 'DateTimeCustomFieldConfig',
+                datetimeMin: field.datetimeMin ?? null,
+                datetimeMax: field.datetimeMax ?? null,
+                datetimeStep: field.datetimeStep ?? null,
+            } satisfies DateTimeCustomFieldConfig;
         default:
             return baseConfig;
     }
@@ -116,7 +115,7 @@ function createDateValidationSchema(minDate: Date | undefined, maxDate: Date | u
  * @param pattern - Optional regex pattern string for validation
  * @returns Zod string schema with optional pattern validation
  */
-function createStringValidationSchema(pattern?: string): ZodType {
+function createStringValidationSchema(pattern?: string | null): ZodType {
     let schema = z.string();
     if (pattern) {
         schema = schema.regex(new RegExp(pattern), {
@@ -134,30 +133,7 @@ function createStringValidationSchema(pattern?: string): ZodType {
  * @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 != 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 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 {
+function createNumberValidationSchema(min?: number | null, max?: number | null): ZodType {
     let schema = z.number();
     if (min != null) {
         schema = schema.min(min, {
@@ -187,17 +163,23 @@ function createCustomFieldValidationSchema(customField: CustomFieldConfig): ZodT
         case 'localeString':
         case 'localeText':
         case 'string':
-            zodType = createStringValidationSchema(customField.pattern);
+            zodType = createStringValidationSchema((customField as StringCustomFieldConfig).pattern);
             break;
         case 'int':
-            zodType = createIntValidationSchema(customField.intMin, customField.intMax);
+            zodType = createNumberValidationSchema(
+                (customField as IntCustomFieldConfig).intMin,
+                (customField as IntCustomFieldConfig).intMax,
+            );
             break;
         case 'float':
-            zodType = createFloatValidationSchema(customField.floatMin, customField.floatMax);
+            zodType = createNumberValidationSchema(
+                (customField as FloatCustomFieldConfig).floatMin,
+                (customField as FloatCustomFieldConfig).floatMax,
+            );
             break;
         case 'datetime': {
-            const minDate = parseDate(customField.datetimeMin);
-            const maxDate = parseDate(customField.datetimeMax);
+            const minDate = parseDate((customField as DateTimeCustomFieldConfig).datetimeMin);
+            const maxDate = parseDate((customField as DateTimeCustomFieldConfig).datetimeMax);
             zodType = createDateValidationSchema(minDate, maxDate);
             break;
         }
@@ -227,7 +209,7 @@ function createStructFieldSchema(structFieldConfig: StructCustomFieldConfig): Zo
 
     const nestedSchema: ZodRawShape = {};
     for (const structSubField of structFieldConfig.fields) {
-        const config = mapGraphQLCustomFieldToConfig(structSubField as StructFieldConfig);
+        const config = mapGraphQLCustomFieldToConfig(structSubField);
         let subFieldType = createCustomFieldValidationSchema(config);
 
         // Handle list and nullable for struct sub-fields
@@ -253,7 +235,7 @@ function createStructFieldSchema(structFieldConfig: StructCustomFieldConfig): Zo
  * @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 {
+function applyCustomFieldModifiers(zodType: ZodType, customField: CustomFieldConfig): ZodType {
     let modifiedType = zodType;
 
     if (customField.list) {
@@ -262,7 +244,9 @@ function applyListAndNullableModifiers(zodType: ZodType, customField: CustomFiel
     if (customField.nullable !== false) {
         modifiedType = modifiedType.optional().nullable();
     }
-
+    if (customField.readonly) {
+        modifiedType = modifiedType.readonly();
+    }
     return modifiedType;
 }
 
@@ -299,7 +283,7 @@ function processCustomFieldsSchema(
             zodType = createCustomFieldValidationSchema(customField);
         }
 
-        zodType = applyListAndNullableModifiers(zodType, customField);
+        zodType = applyCustomFieldModifiers(zodType, customField);
         const schemaPropertyName = getGraphQlInputName(customField);
         customFieldsSchema[schemaPropertyName] = zodType;
     }
@@ -319,7 +303,7 @@ export function createFormSchemaFromFields(
         const isEnum = isEnumType(field.type);
 
         if ((isScalar || isEnum) && field.name !== 'customFields') {
-            schemaConfig[field.name] = getZodTypeFromField(field, customFieldConfigs);
+            schemaConfig[field.name] = getZodTypeFromField(field);
         } else if (field.name === 'customFields') {
             const customFieldsSchema =
                 customFieldConfigs && customFieldConfigs.length > 0
@@ -391,7 +375,7 @@ export function getDefaultValueFromField(field: FieldInfo, defaultLanguageCode?:
     }
 }
 
-export function getZodTypeFromField(field: FieldInfo, customFieldConfigs?: CustomFieldConfig[]): ZodTypeAny {
+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

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

@@ -1,9 +1,9 @@
 import {
     DataDisplayComponent,
-    DataInputComponent,
     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';
@@ -34,7 +34,7 @@ export function OverriddenFormComponent({ fieldName, field, children }: Readonly
     const pageBlock = usePageBlock({ optional: true });
     const componentRegistry = useComponentRegistry();
     let DisplayComponent: DataDisplayComponent | undefined;
-    let InputComponent: DataInputComponent | undefined;
+    let InputComponent: DashboardFormComponent | undefined;
     if (page.pageId && pageBlock?.blockId) {
         const customInputComponentKey = generateInputComponentKey(page.pageId, pageBlock.blockId, fieldName);
         DisplayComponent = componentRegistry.getDisplayComponent(customInputComponentKey);

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

@@ -1,3 +1,25 @@
+import {
+    AllCustomFieldConfigs,
+    BooleanCustomFieldConfig,
+    BooleanStructField,
+    ConfigurableArgDef,
+    ConfigurableFieldDef,
+    DateTimeCustomFieldConfig,
+    DateTimeStructField,
+    FloatCustomFieldConfig,
+    FloatStructField,
+    IntCustomFieldConfig,
+    IntStructField,
+    LocaleStringCustomFieldConfig,
+    LocaleTextCustomFieldConfig,
+    RelationCustomFieldConfig,
+    StringCustomFieldConfig,
+    StringStructField,
+    StructCustomFieldConfig,
+    StructField,
+    TextCustomFieldConfig,
+} from '@/vdb/framework/form-engine/form-engine-types.js';
+
 import { FieldInfo } from '../document-introspection/get-document-structure.js';
 
 /**
@@ -97,3 +119,204 @@ export function removeEmptyIdFields<T extends Record<string, any>>(values: T, fi
     recursiveRemove(result, fields);
     return result;
 }
+
+// =============================================================================
+// TYPE GUARDS FOR CONFIGURABLE FIELD DEFINITIONS
+// =============================================================================
+
+/**
+ * Determines if a field definition is a custom field config (vs configurable operation arg)
+ */
+export function isCustomFieldConfig(input: ConfigurableFieldDef): input is AllCustomFieldConfigs {
+    return input.hasOwnProperty('readonly');
+}
+
+/**
+ * Determines if a field definition is a configurable operation argument
+ */
+export function isConfigurableArgDef(input: ConfigurableFieldDef): input is ConfigurableArgDef {
+    return !input.hasOwnProperty('readonly');
+}
+
+// =============================================================================
+// TYPE GUARDS FOR SPECIFIC CUSTOM FIELD TYPES
+// =============================================================================
+
+/**
+ * String custom field with optional pattern and options
+ */
+export function isStringCustomFieldConfig(input: ConfigurableFieldDef): input is StringCustomFieldConfig {
+    return input.type === 'string' && isCustomFieldConfig(input);
+}
+
+/**
+ * String custom field that has options (select dropdown)
+ */
+export function isStringFieldWithOptions(input: ConfigurableFieldDef): input is StringCustomFieldConfig {
+    const isCustomFieldWithOptions =
+        input.type === 'string' &&
+        isCustomFieldConfig(input) &&
+        input.hasOwnProperty('options') &&
+        Array.isArray((input as any).options);
+    if (isCustomFieldWithOptions) {
+        return true;
+    }
+    const isConfigArgWithOptions =
+        input.type === 'string' && isConfigurableArgDef(input) && Array.isArray(input.ui?.options);
+    if (isConfigArgWithOptions) {
+        return true;
+    }
+    return false;
+}
+
+/**
+ * Locale string custom field
+ */
+export function isLocaleStringCustomFieldConfig(
+    input: ConfigurableFieldDef,
+): input is LocaleStringCustomFieldConfig {
+    return input.type === 'localeString' && isCustomFieldConfig(input);
+}
+
+/**
+ * Text custom field (textarea)
+ */
+export function isTextCustomFieldConfig(input: ConfigurableFieldDef): input is TextCustomFieldConfig {
+    return input.type === 'text' && isCustomFieldConfig(input);
+}
+
+/**
+ * Locale text custom field (localized textarea)
+ */
+export function isLocaleTextCustomFieldConfig(
+    input: ConfigurableFieldDef,
+): input is LocaleTextCustomFieldConfig {
+    return input.type === 'localeText' && isCustomFieldConfig(input);
+}
+
+/**
+ * Boolean custom field
+ */
+export function isBooleanCustomFieldConfig(input: ConfigurableFieldDef): input is BooleanCustomFieldConfig {
+    return input.type === 'boolean' && isCustomFieldConfig(input);
+}
+
+/**
+ * Integer custom field with optional min/max/step
+ */
+export function isIntCustomFieldConfig(input: ConfigurableFieldDef): input is IntCustomFieldConfig {
+    return input.type === 'int' && isCustomFieldConfig(input);
+}
+
+/**
+ * Float custom field with optional min/max/step
+ */
+export function isFloatCustomFieldConfig(input: ConfigurableFieldDef): input is FloatCustomFieldConfig {
+    return input.type === 'float' && isCustomFieldConfig(input);
+}
+
+/**
+ * DateTime custom field with optional min/max/step
+ */
+export function isDateTimeCustomFieldConfig(input: ConfigurableFieldDef): input is DateTimeCustomFieldConfig {
+    return input.type === 'datetime' && isCustomFieldConfig(input);
+}
+
+/**
+ * Relation custom field (references another entity)
+ */
+export function isRelationCustomFieldConfig(input: ConfigurableFieldDef): input is RelationCustomFieldConfig {
+    return input.type === 'relation' && isCustomFieldConfig(input);
+}
+
+/**
+ * Struct custom field (nested object with sub-fields)
+ */
+export function isStructCustomFieldConfig(input: ConfigurableFieldDef): input is StructCustomFieldConfig {
+    return input.type === 'struct' && isCustomFieldConfig(input);
+}
+
+// Legacy alias for backward compatibility
+export const isStructFieldConfig = isStructCustomFieldConfig;
+
+// =============================================================================
+// TYPE GUARDS FOR STRUCT FIELD TYPES (fields within struct custom fields)
+// =============================================================================
+
+/**
+ * String field within a struct custom field
+ */
+export function isStringStructField(input: StructField): input is StringStructField {
+    return input.type === 'string';
+}
+
+/**
+ * String struct field that has options (select dropdown)
+ */
+export function isStringStructFieldWithOptions(
+    input: StructField,
+): input is StringStructField & { options: any[] } {
+    return (
+        input.type === 'string' && input.hasOwnProperty('options') && Array.isArray((input as any).options)
+    );
+}
+
+/**
+ * Integer field within a struct custom field
+ */
+export function isIntStructField(input: StructField): input is IntStructField {
+    return input.type === 'int';
+}
+
+/**
+ * Float field within a struct custom field
+ */
+export function isFloatStructField(input: StructField): input is FloatStructField {
+    return input.type === 'float';
+}
+
+/**
+ * Boolean field within a struct custom field
+ */
+export function isBooleanStructField(input: StructField): input is BooleanStructField {
+    return input.type === 'boolean';
+}
+
+/**
+ * DateTime field within a struct custom field
+ */
+export function isDateTimeStructField(input: StructField): input is DateTimeStructField {
+    return input.type === 'datetime';
+}
+
+// =============================================================================
+// UTILITY TYPE GUARDS
+// =============================================================================
+
+/**
+ * Determines if a field is a list/array field
+ */
+export function isListField(input?: ConfigurableFieldDef): boolean {
+    return input && isCustomFieldConfig(input) ? Boolean(input.list) : false;
+}
+
+/**
+ * Determines if a field is readonly
+ */
+export function isReadonlyField(input?: ConfigurableFieldDef): boolean {
+    return input && isCustomFieldConfig(input) ? Boolean(input.readonly) : false;
+}
+
+/**
+ * Determines if a field requires special permissions
+ */
+export function hasPermissionRequirement(input: ConfigurableFieldDef): boolean {
+    return isCustomFieldConfig(input) && Boolean(input.requiresPermission);
+}
+
+/**
+ * Determines if a field is nullable
+ */
+export function isNullableField(input: ConfigurableFieldDef): boolean {
+    return isCustomFieldConfig(input) && Boolean(input.nullable);
+}