@wilshop/dashboard 3.5.2

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: [] } });
+    });
+});

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

@@ -0,0 +1,356 @@
+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 { FormEvent } from 'react';
+import { UseFormReturn } from 'react-hook-form';
+
+import { FieldInfo } from '../document-introspection/get-document-structure.js';
+
+/**
+ * Transforms relation fields in an entity, extracting IDs from relation objects.
+ * This is primarily used for custom fields of type "ID".
+ *
+ * @param fields - Array of field information
+ * @param entity - The entity to transform
+ * @returns A new entity with transformed relation fields
+ */
+export function transformRelationFields<E extends Record<string, any>>(fields: FieldInfo[], entity: E): E {
+    // Create a shallow copy to avoid mutating the original entity
+    const processedEntity = { ...entity, customFields: { ...(entity.customFields ?? {}) } };
+
+    // Skip processing if there are no custom fields
+    if (!entity.customFields || !processedEntity.customFields) {
+        return processedEntity;
+    }
+
+    // Find the customFields field info
+    const customFieldsInfo = fields.find(field => field.name === 'customFields' && field.typeInfo);
+    if (!customFieldsInfo?.typeInfo) {
+        return processedEntity;
+    }
+
+    // Process only ID type custom fields
+    const idTypeCustomFields = customFieldsInfo.typeInfo.filter(field => field.type === 'ID');
+
+    for (const customField of idTypeCustomFields) {
+        const relationField = customField.name;
+
+        if (customField.list) {
+            // For list fields, the accessor is the field name without the "Ids" suffix
+            const propertyAccessorKey = customField.name.replace(/Ids$/, '');
+            const relationValue = entity.customFields[propertyAccessorKey];
+
+            if (relationValue) {
+                const relationIdValue = relationValue.map((v: { id: string }) => v.id);
+                if (relationIdValue && relationIdValue.length > 0) {
+                    processedEntity.customFields[relationField] = relationIdValue;
+                }
+            }
+        } else {
+            // For single fields, the accessor is the field name without the "Id" suffix
+            const propertyAccessorKey = customField.name.replace(/Id$/, '');
+            const relationValue = entity.customFields[propertyAccessorKey];
+            processedEntity.customFields[relationField] = relationValue?.id;
+            delete processedEntity.customFields[propertyAccessorKey];
+        }
+    }
+    return processedEntity;
+}
+
+/**
+ * @description
+ * Due to the schema types, sometimes "create" mutations will have a default empty "id"
+ * field which can cause issues if we actually send them with a "create" mutation to the server.
+ * This function deletes any empty ID fields on the entity or its nested objects.
+ */
+export function removeEmptyIdFields<T extends Record<string, any>>(values: T, fields: FieldInfo[]): T {
+    if (!values) {
+        return values;
+    }
+
+    // Create a deep copy to avoid mutating the original values
+    const result = structuredClone(values);
+
+    function recursiveRemove(obj: any, fieldDefs: FieldInfo[]) {
+        if (Array.isArray(obj)) {
+            for (const item of obj) {
+                recursiveRemove(item, fieldDefs);
+            }
+        } else if (typeof obj === 'object' && obj !== null) {
+            for (const field of fieldDefs) {
+                // Remove empty string ID fields at this level
+                if (field.type === 'ID' && typeof obj[field.name] === 'string' && obj[field.name] === '') {
+                    delete obj[field.name];
+                }
+                // If the field is an object or array, recurse into it
+                if (Array.isArray(obj[field.name])) {
+                    if (field.typeInfo) {
+                        for (const item of obj[field.name]) {
+                            recursiveRemove(item, field.typeInfo);
+                        }
+                    }
+                } else if (
+                    typeof obj[field.name] === 'object' &&
+                    obj[field.name] !== null &&
+                    field.typeInfo
+                ) {
+                    recursiveRemove(obj[field.name], field.typeInfo);
+                }
+            }
+        }
+    }
+
+    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);
+}
+
+/**
+ * Handles nested form submission to prevent event bubbling in nested forms.
+ * This is useful when you have a form inside a dialog that's within another form.
+ *
+ * @param form - The react-hook-form instance
+ * @param onSubmit - The submit handler function
+ * @returns An event handler that prevents propagation and handles the form submission
+ *
+ * @example
+ * ```tsx
+ * const form = useForm<FormSchema>({ resolver: zodResolver(formSchema) });
+ *
+ * return (
+ *   <form onSubmit={handleNestedFormSubmit(form, (data) => {
+ *     // Handle form submission
+ *   })}>
+ *     ...
+ *   </form>
+ * );
+ * ```
+ */
+export function handleNestedFormSubmit<TFieldValues extends Record<string, any>>(
+    form: UseFormReturn<TFieldValues>,
+    onSubmit: (data: TFieldValues) => void | Promise<void>,
+) {
+    return (e: FormEvent<HTMLFormElement>) => {
+        e.preventDefault();
+        e.stopPropagation();
+        void form.handleSubmit(onSubmit)(e);
+    };
+}

package/src/lib/framework/form-engine/value-transformers.ts

@@ -0,0 +1,150 @@
+import { ConfigurableFieldDef } from '@/vdb/framework/form-engine/form-engine-types.js';
+
+export type ValueMode = 'native' | 'json-string';
+
+/**
+ * Interface for transforming values between native JavaScript types and JSON strings
+ */
+export interface ValueTransformer {
+    parse: (value: string, fieldDef: ConfigurableFieldDef) => any;
+    serialize: (value: any, fieldDef: ConfigurableFieldDef) => string;
+}
+
+/**
+ * Native value transformer - passes values through unchanged
+ */
+export const nativeValueTransformer: ValueTransformer = {
+    parse: (value: string, fieldDef: ConfigurableFieldDef) => {
+        // For native mode, values are already in their correct JavaScript type
+        return value;
+    },
+    serialize: (value: any, fieldDef: ConfigurableFieldDef) => {
+        // For native mode, values are already in their correct JavaScript type
+        return value;
+    },
+};
+
+/**
+ * JSON string value transformer - converts between JSON strings and native values
+ */
+export const jsonStringValueTransformer: ValueTransformer = {
+    parse: (value: string, fieldDef: ConfigurableFieldDef) => {
+        if (value === undefined) {
+            return getDefaultValue(fieldDef);
+        }
+        // This case arises often when the administrator is actively editing
+        // values and clears out the input. At that point, we don't want to suddenly
+        // switch to the default value otherwise it results in poor UX, e.g. pressing
+        // backspace to delete a number would result in `0` suddenly appearing as the value.
+        if (value === '') {
+            return value;
+        }
+
+        try {
+            // For JSON string mode, parse the string to get the native value
+            const parsed = JSON.parse(value);
+
+            // Handle special cases for different field types
+            switch (fieldDef.type) {
+                case 'boolean':
+                    return parsed === true || parsed === 'true';
+                case 'int':
+                case 'float':
+                    return typeof parsed === 'number' ? parsed : parseFloat(parsed) || 0;
+                case 'datetime':
+                    return parsed;
+                default:
+                    return parsed;
+            }
+        } catch (error) {
+            // If parsing fails, try to handle as a plain string for certain types
+            switch (fieldDef.type) {
+                case 'boolean':
+                    return value === 'true';
+                case 'int':
+                case 'float':
+                    return parseFloat(value) || 0;
+                default:
+                    return value;
+            }
+        }
+    },
+    serialize: (value: any, fieldDef: ConfigurableFieldDef) => {
+        if (value === null || value === undefined) {
+            return '';
+        }
+
+        // Handle special cases for different field types
+        switch (fieldDef.type) {
+            case 'boolean':
+                return (value === true || value === 'true').toString();
+            case 'int':
+            case 'float':
+                return typeof value === 'number' ? value.toString() : (parseFloat(value) || 0).toString();
+            case 'string':
+                return typeof value === 'string' ? value : JSON.stringify(value);
+            default:
+                // For complex values (arrays, objects), serialize as JSON
+                return typeof value === 'string' ? value : JSON.stringify(value);
+        }
+    },
+};
+
+/**
+ * Get the appropriate value transformer based on the value mode
+ */
+export function getValueTransformer(valueMode: ValueMode): ValueTransformer {
+    switch (valueMode) {
+        case 'native':
+            return nativeValueTransformer;
+        case 'json-string':
+            return jsonStringValueTransformer;
+        default:
+            return nativeValueTransformer;
+    }
+}
+
+/**
+ * Get default value for a field type
+ */
+function getDefaultValue(fieldDef: ConfigurableFieldDef): any {
+    if (fieldDef.list) {
+        return [];
+    }
+
+    switch (fieldDef.type) {
+        case 'string':
+        case 'ID':
+        case 'localeString':
+        case 'localeText':
+            return '';
+        case 'int':
+        case 'float':
+            return 0;
+        case 'boolean':
+            return false;
+        case 'datetime':
+            return '';
+        case 'relation':
+            return fieldDef.list ? [] : null;
+        case 'struct':
+            return fieldDef.list ? [] : {};
+        default:
+            return '';
+    }
+}
+
+/**
+ * Utility to transform a value using the appropriate transformer
+ */
+export function transformValue(
+    value: any,
+    fieldDef: ConfigurableFieldDef,
+    valueMode: ValueMode,
+    direction: 'parse' | 'serialize',
+): any {
+    const transformer = getValueTransformer(valueMode);
+    return direction === 'parse'
+        ? transformer.parse(value, fieldDef)
+        : transformer.serialize(value, fieldDef);
+}

package/src/lib/framework/history-entry/history-entry-extensions.ts

@@ -0,0 +1,11 @@
+import { DashboardHistoryEntryComponent } from '@/vdb/framework/extension-api/types/index.js';
+
+import { globalRegistry } from '../registry/global-registry.js';
+
+globalRegistry.register('historyEntries', new Map<string, DashboardHistoryEntryComponent['component']>());
+
+export function getCustomHistoryEntryForType(
+    type: string,
+): DashboardHistoryEntryComponent['component'] | undefined {
+    return globalRegistry.get('historyEntries').get(type);
+}

package/src/lib/framework/history-entry/history-entry.tsx

@@ -0,0 +1,129 @@
+import { HistoryEntryItem } from '@/vdb/framework/extension-api/types/index.js';
+import { cn } from '@/vdb/lib/utils.js';
+import React from 'react';
+import { HistoryEntryDate } from '../../components/shared/history-timeline/history-entry-date.js';
+
+/**
+ * @description
+ * The props for the {@link HistoryEntry} component.
+ *
+ * @docsCategory extensions-api
+ * @docsPage HistoryEntries
+ * @since 3.4.3
+ */
+export interface HistoryEntryProps {
+    /**
+     * @description
+     * The entry itself, which will get passed down to your custom component
+     */
+    entry: HistoryEntryItem;
+    /**
+     * @description
+     * The title of the entry
+     */
+    title: string | React.ReactNode;
+    /**
+     * @description
+     * An icon which is used to represent the entry. Note that this will only
+     * display if `isPrimary` is `true`.
+     */
+    timelineIcon?: React.ReactNode;
+    /**
+     * @description
+     * Optional tailwind classes to apply to the icon. For instance
+     *
+     * ```ts
+     * const success = 'bg-success text-success-foreground';
+     * const destructive = 'bg-destructive text-destructive-foreground';
+     * ```
+     */
+    timelineIconClassName?: string;
+    /**
+     * @description
+     * The name to display of "who did the action". For instance:
+     *
+     * ```ts
+     * const getActorName = (entry: HistoryEntryItem) => {
+     *     if (entry.administrator) {
+     *         return `${entry.administrator.firstName} ${entry.administrator.lastName}`;
+     *     } else if (entity?.customer) {
+     *         return `${entity.customer.firstName} ${entity.customer.lastName}`;
+     *     }
+     *     return '';
+     * };
+     * ```
+     */
+    actorName?: string;
+    children: React.ReactNode;
+    /**
+     * @description
+     * When set to `true`, the timeline entry will feature the specified icon and will not
+     * be collapsible.
+     */
+    isPrimary?: boolean;
+}
+
+/**
+ * @description
+ * A component which is used to display a history entry in the order/customer history timeline.
+ *
+ * @docsCategory extensions-api
+ * @docsPage HistoryEntries
+ * @since 3.4.3
+ */
+export function HistoryEntry({
+    entry,
+    timelineIcon,
+    timelineIconClassName,
+    actorName,
+    title,
+    children,
+    isPrimary = true,
+}: Readonly<HistoryEntryProps>) {
+    return (
+        <div key={entry.id} className="relative group">
+            <div
+                className={`flex gap-3 p-3 rounded-lg hover:bg-muted/30 transition-colors ${!isPrimary ? 'opacity-90' : ''}`}
+            >
+                <div className={cn(`relative z-10 flex-shrink-0`, isPrimary ? 'ml-0' : 'ml-2 mt-1')}>
+                    <div
+                        className={`rounded-full flex items-center justify-center ${isPrimary ? 'h-6 w-6' : 'h-2 w-2 border'} ${timelineIconClassName ?? ''}  ${isPrimary ? 'shadow-sm' : 'shadow-none'}`}
+                    >
+                        <div className={isPrimary ? 'text-current scale-80' : 'text-current scale-0'}>
+                            {timelineIcon ?? ''}
+                        </div>
+                    </div>
+                </div>
+
+                <div className="flex-1 min-w-0">
+                    <div className="flex items-start justify-between">
+                        <div className="flex-1 min-w-0">
+                            <h4
+                                className={`text-sm ${isPrimary ? 'font-medium text-foreground' : 'font-normal text-muted-foreground'}`}
+                            >
+                                {title}
+                            </h4>
+                            <div className="mt-1">{children}</div>
+                        </div>
+
+                        <div className="flex items-center gap-2 ml-4 flex-shrink-0">
+                            <div className="text-right">
+                                <HistoryEntryDate
+                                    date={entry.createdAt}
+                                    className={`text-xs cursor-help ${isPrimary ? 'text-muted-foreground' : 'text-muted-foreground/70'}`}
+                                />
+                                {actorName && (
+                                    <div
+                                        className={`text-xs ${isPrimary ? 'text-muted-foreground' : 'text-muted-foreground/70'}`}
+                                    >
+                                        {actorName}
+                                    </div>
+                                )}
+                            </div>
+                        </div>
+                    </div>
+                </div>
+            </div>
+        </div>
+    );
+}