@bach.software/vue-dynamic-form 0.6.0 → 0.8.0

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

@@ -219,6 +219,37 @@ export type FieldMetadata<ExtendedFieldTypes extends string = string, ExtendedPr
      * `computedProps` cannot flip it mid-form.
      */
     wizard?: boolean | WizardConfig;
+    /**
+     * The value stored in the form when the user selects this choice branch.
+     *
+     * Normally a branch has fields, and filling those in is what marks the branch as selected.
+     * A branch without any fields has nothing to fill in, so without help its value stays
+     * `undefined`: validation thinks nothing was selected, and the selection is lost when the
+     * form values are submitted or loaded back in. Set `presenceValue` to fix that: the moment
+     * the user picks the branch, this value is written as the branch's value, so the selection
+     * validates and survives a save/reload round-trip.
+     *
+     * Any JSON-serializable value works (`true`, `'selected'`, `{}`, ...), except `null` and the
+     * empty string: those read as selected but still fail the branch's own required check, so the
+     * selection would show an error. When the form loads existing values, the branch shows as
+     * selected whenever its value is not `undefined`.
+     *
+     * Selecting the branch is a session action: `resetForm()` clears a marker written by a click
+     * this session and deselects the branch, while a marker that was part of the loaded values is
+     * restored and keeps the branch selected.
+     *
+     * Only useful on a non-repeatable (`maxOccurs: 1`) branch without `children`, inside a
+     * `choice` with `explicitChoiceSelection: true`. On other branches it is ignored, because
+     * their values already show that they were selected (a repeated branch has its occurrences,
+     * a branch with children has its filled-in fields). Using it on a branch with `children`
+     * logs a development warning.
+     *
+     * Two things to keep in mind:
+     * - Prefer a non-empty value: if you clean up the submitted values with `removeNullValues`,
+     *   an empty `{}` or `[]` marker is removed and the selection is lost.
+     * - This is static metadata only; `computedProps` cannot set or change it at runtime.
+     */
+    presenceValue?: unknown;
     /**
      * Attributes are additional metadata that can be attached to a field.
      * These attributes can be used to provide extra information about the field,
@@ -300,7 +331,7 @@ export interface WizardGotoStepOptions {
     allowForwardJump?: boolean;
     validateOnJump?: boolean;
 }
-export type ComputedPropsFieldType<ExtendedFieldTypes extends string = string, ExtendedProperties extends object = object> = Omit<FieldMetadata<ExtendedFieldTypes, ExtendedProperties>, 'name' | 'path' | 'parent' | 'children' | 'choice' | 'attributes' | 'fieldOptions' | 'computedProps' | 'maxOccurs' | 'maxOccursTotal' | 'isComplexType' | 'computeOnChildValueChange' | 'explicitChoiceSelection' | 'preserveOnSwitch' | 'displayOrder' | 'preserveOrder' | 'wizard'> & Readonly<{
+export type ComputedPropsFieldType<ExtendedFieldTypes extends string = string, ExtendedProperties extends object = object> = Omit<FieldMetadata<ExtendedFieldTypes, ExtendedProperties>, 'name' | 'path' | 'parent' | 'children' | 'choice' | 'attributes' | 'fieldOptions' | 'computedProps' | 'maxOccurs' | 'maxOccursTotal' | 'isComplexType' | 'computeOnChildValueChange' | 'explicitChoiceSelection' | 'preserveOnSwitch' | 'displayOrder' | 'preserveOrder' | 'wizard' | 'presenceValue'> & Readonly<{
     name: string;
     path: string;
     parent: FieldMetadata<ExtendedFieldTypes, ExtendedProperties>;

package/dist/src/utils/__tests__/deepEqual.test.d.ts

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

package/dist/src/utils/__tests__/hashField.test.d.ts

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

package/dist/src/utils/__tests__/isPathInSection.test.d.ts

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

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

@@ -0,0 +1,11 @@
+import type { GenericValidateFunction } from 'vee-validate';
+import type { DynamicFormSettings } from '../types/DynamicFormSettings';
+import type { FieldMetadata } from '../types/FieldMetadata';
+/**
+ * Builds the XSD restriction rules plus any custom validation declared directly on a field,
+ * shared by every place that registers a vee-validate field for that metadata (a plain field, or
+ * a choice-hosting field whose own restriction/validation is folded into its nested choice).
+ * Required/minOccurs is intentionally not part of this: it is a separate concern each caller
+ * decides for itself.
+ */
+export declare function buildRestrictionValidations(restriction: FieldMetadata['restriction'] | undefined, validation: FieldMetadata['validation'], messages: DynamicFormSettings['messages'] | undefined): GenericValidateFunction[];

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

@@ -0,0 +1,9 @@
+/**
+ * Compares two values by content instead of by reference. Primitives, plain objects, arrays and
+ * Dates are compared recursively; everything else (functions, class instances, Maps, ...) only
+ * counts as equal when it is the exact same reference.
+ *
+ * Mirrors the value scope of `deepCloneValue`. Useful to detect "rebuilt but identical" objects,
+ * such as metadata that computedProps functions recreate on every run.
+ */
+export declare function deepEqual(a: unknown, b: unknown): boolean;

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

@@ -0,0 +1,9 @@
+/**
+ * Checks whether a field path falls at or under a section path.
+ * Matches the section itself, `section.child`, and `section[0]`, but not
+ * unrelated paths that happen to share a prefix string (e.g. `addressLine` vs `address`).
+ *
+ * @param path - Dot-notated field path (e.g. `'address.street'` or `'contacts[0].email'`)
+ * @param sectionPath - Dot-notated path prefix (e.g. `'address'` or `'contacts[0]'`)
+ */
+export declare function isPathInSection(path: string, sectionPath: string): boolean;

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

@@ -1,5 +1,9 @@
 /**
  * Removes all null value's from object properties and array's.
+ *
+ * Note: an empty-object or empty-array `presenceValue` marker on a choice branch is stripped
+ * back to `undefined` by this cleanup, same as any other empty object/array; use a non-empty
+ * marker if the branch's selection must survive this round-trip.
  * @param element any value
  */
 export declare function removeNullValues<T>(element: T): T | undefined;