@bach.software/vue-dynamic-form 0.1.3 → 0.2.0

package/dist/src/types/FieldMetadata.d.ts

@@ -1,25 +1,47 @@
-import type { WatchSource } from 'vue';
+import type { FieldOptions, RuleExpression } from 'vee-validate';
+import type { Ref } from 'vue';
 export type FieldMetadata<ExtendedFieldTypes extends string = string, ExtendedProperties extends object = object> = {
     name?: string;
     type?: ExtendedFieldTypes;
     path?: string;
+    /**
+     * The minimal occurrence of a value.
+     * Optional fields have a value of 0.
+     * Required fields have a value of 1.
+     * We also allow to specify if you need a minimum higher then 1.
+     */
     minOccurs?: number;
+    /**
+     * The maximal occurrence of a value.
+     */
     maxOccurs?: number;
     /**
-     * Simple restrictions to the data
+     * Simple restrictions to the data, these are available in XSD and can be applied easily.
+     * For more advance validation use the validation property.
      */
-    restrictions?: {
-        maxLength?: number;
+    restriction?: {
         minLength?: number;
+        maxLength?: number;
         pattern?: string;
         minInclusive?: number;
         maxInclusive?: number;
-        enumeration?: string;
+        minExclusive?: number;
+        maxExclusive?: number;
+        enumeration?: unknown[];
         length?: number;
-        whiteSpace?: string;
+        whiteSpace?: 'preserve' | 'replace' | 'collapse';
         fractionDigits?: number;
         totalDigits?: number;
     };
+    /**
+     * Vee-Validate validation rules that should be applied to this field.
+     */
+    validation?: RuleExpression<unknown>;
+    /**
+     * The vee-validate field options.
+     * - label: you can set a ref to make this dynamically update.
+     */
+    fieldOptions?: Partial<FieldOptions<unknown>>;
     children?: FieldMetadata<ExtendedFieldTypes, ExtendedProperties>[];
     /**
      * Choice is similar to children, with the difference that only one of the items in the array
@@ -50,15 +72,34 @@ export type FieldMetadata<ExtendedFieldTypes extends string = string, ExtendedPr
      * <ContactInfo>
      *   <Email>someone@example.com</Email>
      * </ContactInfo>
-     * or
+     * <!-- or -->
      * <ContactInfo>
      *   <Phone>+31 123 456 789</Phone>
      * </ContactInfo>
      *
-     * but this is invalid:
+     * <!-- but this is invalid: -->
      * <ContactInfo>
      * </ContactInfo>
+     * ```
      *
+     * Or json
+     * ```json
+     * {
+     *  "contactInfo": {
+     *     "email": "someone@example.com"
+     *  }
+     * }
+     * <!-- or -->
+     * {
+     *  "contactInfo": {
+     *   "phone": "+31 123 456 789"
+     *  }
+     * }
+     *
+     * <!-- but this is invalid: -->
+     * {
+     * "contactInfo": { }
+     * }
      * ```
      *
      */
@@ -69,33 +110,62 @@ export type FieldMetadata<ExtendedFieldTypes extends string = string, ExtendedPr
      * such as for example whether the data is verified.
      *
      * These attributes will be shown when the parent will have a value filled in.
+     * The field automatically becomes a complex type, meaning that the value will be
+     * an object containing the value and the attributes.
      *
      * For example:
      * ```
      * <ContactInfo>
      *   <Phone certainty="unverified">+31 123 456 789</Phone>
      * </ContactInfo>
-     * or
+     * <!-- or -->
      * <ContactInfo>
      *   <Phone certainty="verified">+31 123 456 789</Phone>
      * </ContactInfo>
      * ```
      */
     attributes?: FieldMetadata<ExtendedFieldTypes, ExtendedProperties>[];
+    /**
+     * To support generating a form based on a xsd, we need to be able to work with complex types.
+     * In case a SimpleContent has a ComplexType as parent, the json converter creates a value object
+     * with the value inside i.e. { value: 'the actual value' } and the attributes alongside it.
+     *
+     * By setting isComplexType to true, the form generator knows it needs to look for the value inside
+     * the value property.
+     *
+     * When attributes are present, isComplexType is automatically set to true.
+     *
+     * In case you need to change the default value property 'value', do this in the DynamicFormSettings.
+     */
+    isComplexType?: boolean;
     /**
      * The parent of the current field.
+     * This is purely for reference, these values cannot be updated.
      */
-    parent?: FieldMetadata<ExtendedFieldTypes, ExtendedProperties>;
+    parent?: Readonly<FieldMetadata<ExtendedFieldTypes, ExtendedProperties>>;
     /**
-     * You can add methods that transform the field metadata based on other external values.
-     * Make sure to include the reactive value's in your function, so that the function is re-evaluated once
-     * the value changes (internally we use a computed that is re-valuated when one of the used reactive values is changed).
-     * This way we can for example change the property minOccurs to 1 (required) if another field has a value or change one of the ExtendedAttributes.
+     * Compute field values locally in the component that represents the field.
+     *
+     * This is a list of functions that are executed inside a computed in the component of the field.
+     * This means that if you reference other computed, refs, etc, these functions will be re-evaluated once one of the used reactive values changes.
+     *
+     * Allowing you to change the properties in the fieldMetadata, based on other values in the form, without re-rendering the entire component tree.
+     *
+     * It is also possible to read & write
      *
      * @param thisField the reactive & cloned current MetadataField that can be changed.
+     * @param fieldValue the value of the field, you can read and modify it. If you do, the reactivity is activated and the computed
+     * is re-computed every time the value changes. If you don't use it, a change in value will not re-trigger the reactivity of the computed.
      * @returns A transformed FieldMetadata
      */
-    transformReactively?: ((thisField: Omit<FieldMetadata<ExtendedFieldTypes, ExtendedProperties>, 'name' | 'children' | 'choice' | 'attributes'> & {
-        name: string;
-    }, fieldValue?: WatchSource<any>) => Omit<FieldMetadata<ExtendedFieldTypes, ExtendedProperties>, 'children'>)[];
+    computedProps?: ((thisField: ComputedPropsType<FieldMetadata<ExtendedFieldTypes, ExtendedProperties>>, fieldValue: Ref<unknown>) => void)[];
+    /**
+     * Normally the computedProps are not re-calculate if a child value changes. If you need this functionality, you can enable this by
+     * setting this property to true.
+     */
+    computeOnChildValueChange?: boolean;
 } & ExtendedProperties;
+export type ComputedPropsType<T> = Omit<T, 'name' | 'path' | 'children' | 'choice' | 'attributes' | 'fieldOptions' | 'computedProps' | 'maxOccurs'> & Readonly<{
+    name: string;
+    path: string;
+}>;

package/dist/src/types/InternalFieldMetadata.d.ts

@@ -1,3 +1,3 @@
-import type { FieldMetadata } from './FieldMetadata.js';
-import type { RequireOnly } from './RequireOnly.js';
+import type { FieldMetadata } from '../types/FieldMetadata.js';
+import type { RequireOnly } from '../types/RequireOnly.js';
 export type InternalFieldMetadata<Metadata extends FieldMetadata> = RequireOnly<Metadata, 'name' | 'type' | 'minOccurs' | 'maxOccurs'>;

package/dist/src/types/KeyValue.d.ts

@@ -0,0 +1,3 @@
+export interface KeyValue<T = any> {
+    [key: string]: T;
+}

package/dist/src/types/MetadataConfiguration.d.ts

@@ -1,4 +1,5 @@
 export interface MetadataConfiguration {
     fieldTypes: readonly string[];
     extendedProperties: object;
+    valueTypes: Record<string, any>;
 }

package/dist/src/types/ValidationMessage.d.ts

@@ -0,0 +1,3 @@
+import type { GenericValidateFunction } from 'vee-validate';
+export type FieldValidationMetaInfo = Parameters<GenericValidateFunction>[1];
+export type ValidationMessage = string | ((ctx: FieldValidationMetaInfo) => string);

package/dist/src/utils/camelize.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Coming from vue source code
+ * @private
+ */
+export declare const camelize: (str: string) => string;

package/dist/src/utils/checkTreeHasValue.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Recursively traverses a data structure to determine if it holds any meaningful data.
+ * Returns false only when the entire structure consists of null/undefined values.
+ * Particularly useful for validation frameworks to detect populated form fields.
+ *
+ * @param element Data structure to analyze (supports primitives, objects, arrays)
+ * @returns Boolean indicating presence of non-nullish values
+ */
+export declare function checkTreeHasValue(element: unknown): boolean;

package/dist/src/utils/checkTreeHasValue.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/utils/createValidation.d.ts

@@ -0,0 +1,12 @@
+import type { ValidationRule } from '../core/validation';
+import type { FieldValidationMetaInfo, ValidationMessage } from '../types/ValidationMessage';
+/**
+ * Creates a validation that uses a globally defined rule in our 'vdf' namespace.
+ * When the validation fails we either show the message override from the settings.messages
+ * or let the user override the message using the configure.generateMessage
+ *
+ * @param rule
+ * @param param
+ * @param customMessage
+ */
+export declare function createValidation(rule: ValidationRule, param?: unknown, customMessage?: ValidationMessage): (value: unknown, ctx: FieldValidationMetaInfo) => Promise<string | true>;

package/dist/src/utils/createValidation.test.d.ts

@@ -0,0 +1 @@
+import '../core/validation';

package/dist/src/utils/getFieldLabel.d.ts

@@ -0,0 +1,16 @@
+import type { FieldValidationMetaInfo } from '../types/ValidationMessage';
+/**
+ * Resolves the most user-friendly label for a field validation context.
+ *
+ * Most components (e.g. DynamicFormItem, DynamicFormItemArray) call `useField`
+ * with the field's `fieldOptions`, so vee-validate already sets `ctx.label`
+ * and `ctx.field` to a human-readable name. Choice fields are special: they
+ * validate at the root path (`''`) and historically registered without any
+ * `fieldOptions`, which left vee-validate with the literal placeholder
+ * string `{field}`. Normalizing the label here ensures shared helpers like
+ * createValidation/splitValidationFunctions always receive a real display name
+ * even for those “virtual” fields.
+ *
+ * Preference order: explicit label → ctx.field → ctx.name → empty string.
+ */
+export declare function getFieldLabel(ctx: FieldValidationMetaInfo): string;

package/dist/src/utils/normalizePath.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Helper function that converts a path with bracket notation to a dot notation.
+ * When adding an extra path segment, we do this by using the bracket notation, i.e.: person['value'].
+ *
+ * Vee-validate can't work with this notation, therefore this function fixes those cases.
+ *
+ * const actualPath = normalizePath(
+ *  'this.is["added"].to.my.path.and.more',
+ * )
+ *
+ * console.log(actualPath) // 'this.is.added.to.my.path.and.more'
+ *
+ * @param path to be normalized
+ */
+export declare function normalizePath(path: string): string;

package/dist/src/utils/normalizePath.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/utils/overridePath.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Merges two dot-notation paths by replacing leading segments of the base path
+ * with segments from the replacement path. Useful for resolving array indices
+ * in nested field paths where parent context contains array positions.
+ *
+ * @example
+ * // Given a generic path and an indexed parent path, produce the indexed child path
+ * const result = overridePath(
+ *  'data.users.contact.email',
+ *  'data.users[2]'
+ * )
+ *
+ * console.log(result) // 'data.users[2].contact.email'
+ *
+ * @param path Base path string to be modified
+ * @param overrideWithPath Replacement path that will substitute initial segments
+ * @returns Modified path with replaced segments
+ */
+export declare function overridePath(path: string, overrideWithPath: string | undefined): string;

package/dist/src/utils/overridePath.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/utils/resolveMessage.d.ts

@@ -0,0 +1,17 @@
+import type { FieldValidationMetaInfo, ValidationMessage } from '../types/ValidationMessage';
+/**
+ * Helper function to resolve a validation message, with parameters.
+ *
+ * All three param styles work:
+ * 'Must be at least {0} characters'   // positional
+ * 'Must be at least {min} characters' // named (object params)
+ * 'The {field} value {value} is invalid' // context properties
+ *
+ * This is exactly how @vee-validate/i18n handles it internally.
+ * @param message - The message template or function
+ * @param ctx - The vee-validate field validation context
+ * @param params - Optional param override. Array for positional `{0}, {1}`, or object for
+ *   named `{min}, {length}` (also supports positional via numeric keys). Falls back to ctx.rule.params if not provided.
+ * @returns The resolved message string
+ */
+export declare function resolveMessage(message: ValidationMessage, ctx: FieldValidationMetaInfo, params?: unknown[] | Record<string, unknown>): string;

package/dist/src/utils/resolveMessage.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/utils/setInPath.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Sets a value at a nested path within an object.
+ * Based on vee-validate's internal setInPath implementation.
+ * Creates intermediate objects/arrays as needed.
+ *
+ * @param object - The object to modify
+ * @param path - Dot-separated path (e.g., "user.address.city") or with array notation (e.g., "items[0].name")
+ * @param value - The value to set at the path
+ */
+export declare function setInPath(object: Record<string, any>, path: string, value: unknown): void;

package/dist/src/utils/setInPath.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/utils/splitValidationFunctions.d.ts

@@ -0,0 +1,15 @@
+import type { GenericValidateFunction, RuleExpression } from 'vee-validate';
+/**
+ * Splits a vee-validate `RuleExpression` into an array of individual `GenericValidateFunction`s,
+ * one per rule. This allows vee-validate to run each rule independently and collect all errors
+ * when `bails: false` is configured.
+ *
+ * Handles all `RuleExpression` formats:
+ * - **Function** — returned as-is in a single-element array
+ * - **Array** — each element is recursively split
+ * - **String** — pipe-separated rules (e.g. `'required|email'`) are split into separate functions,
+ *   each delegating to vee-validate's `validate()`
+ * - **Object** — each key/value pair (e.g. `{ required: true, min: 3 }`) becomes a separate function,
+ *   each delegating to vee-validate's `validate()`
+ */
+export declare function splitToValidationFunctions(userRules: RuleExpression<unknown>): GenericValidateFunction[];

package/dist/src/utils/splitValidationFunctions.test.d.ts

@@ -0,0 +1 @@
+export {};