@bach.software/vue-dynamic-form 0.5.0 → 0.7.0

package/dist/src/examples/index.d.ts

@@ -1,3 +1,5 @@
 export * from './__tests__/TestFormTemplate.testcases';
+export { default as KeepValuesOnUnmountTestCase } from './KeepValuesOnUnmountTestCase.vue';
+export { default as ProgrammaticWritesTestCase } from './ProgrammaticWritesTestCase.vue';
 export { default as TestFormTemplate } from './TestFormTemplate.vue';
 export { type Metadata } from './TestFormTemplate.vue';

package/dist/src/index.d.ts

@@ -2,6 +2,7 @@ export { default as DynamicForm } from './components/DynamicForm.vue';
 export { default as DynamicFormItem } from './components/DynamicFormItem.vue';
 export { default as DynamicFormItemArray } from './components/DynamicFormItemArray.vue';
 export { default as DynamicFormItemChoice } from './components/DynamicFormItemChoice.vue';
+export { default as DynamicFormItemWizard } from './components/DynamicFormItemWizard.vue';
 export { default as DynamicFormTemplate } from './components/DynamicFormTemplate.vue';
 export * from './core/defineMetadata';
 export * from './core/useDynamicForm';

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

@@ -3,8 +3,8 @@ import type { FieldMetadata } from '../types/FieldMetadata';
 import type { InternalFieldMetadata } from '../types/InternalFieldMetadata';
 export interface DynamicFormItemProps<InternalMetadata extends InternalFieldMetadata<FieldMetadata>> {
     template: DefineComponent<object, object, {
-        default?: ((props: object) => any) | undefined;
-        attributes?: ((props: object) => any) | undefined;
+        default?: ((props: object) => any);
+        attributes?: ((props: object) => any);
     }>;
     fieldMetadata: InternalMetadata;
     /**
@@ -39,6 +39,20 @@ export interface DynamicFormItemProps<InternalMetadata extends InternalFieldMeta
      * mark all children optional if no value has been filled in.
      */
     partOfArrayField?: boolean;
+    /**
+     * In case this field is one of the parent's `attributes`, it is conditionally mounted based on
+     * whether the parent has a value. This marks it so unmount cleanup can tell it apart from a
+     * regular field and consult `attributeOwnerHasValue` before deciding whether to clear it.
+     */
+    partOfAttributeField?: boolean;
+    /**
+     * For an item marked `partOfAttributeField`, a getter that reports whether the owning field
+     * currently has a main value. Called at unmount time: when it returns false, the attribute's
+     * value is cleared regardless of `keepValuesOnUnmount`/`keepValueOnUnmount`, since it belongs
+     * to a value that is itself gone; when it returns true, the attribute follows the same keep
+     * flags as any other field.
+     */
+    attributeOwnerHasValue?: () => boolean;
     /**
      * In case this field is part of a choice field, it needs to co-operate with that choice field and
      * behave differently in some situations.
@@ -49,6 +63,29 @@ export interface DynamicFormItemProps<InternalMetadata extends InternalFieldMeta
      * In case the field is a child of a choice field, it needs to be made repeatable and we can set this to true.
      */
     isArrayOverride?: 'auto' | 'array' | 'single';
+    /**
+     * In case this item is a single occurrence of a repeatable explicit choice branch
+     * (`DynamicFormItemChoice`, `maxOccurs > 1`), the branch (choice child) `name` it belongs to.
+     * When set, it drives the `-choice-array-item` slot type suffix (mirroring `partOfArrayField`'s
+     * `-array-item` suffix) and is forwarded to the slot as `branchKey`.
+     */
+    branchKey?: string;
+    /**
+     * In case this item is a single occurrence of a repeatable explicit choice branch
+     * (`DynamicFormItemChoice`, `maxOccurs > 1`), this occurrence's zero-based position across
+     * every branch's active occurrences (not just its own branch). Forwarded to the slot as
+     * `globalIndex`. `undefined` everywhere else.
+     */
+    globalIndex?: number;
+    /**
+     * In case this item is a single occurrence of a repeatable explicit choice branch
+     * (`DynamicFormItemChoice`, `maxOccurs > 1`), the instance-local, ephemeral position at which
+     * this occurrence was added this session (1-based, in add-press order across every branch).
+     * `undefined` for an occurrence that existed before this session (loaded saved data) or that
+     * was never added through `addChoiceOccurrence`. Forwarded to the slot as `insertionOrder`;
+     * never written to form values.
+     */
+    insertionOrder?: number;
     /**
      * In case this item is part of a field array, we need some extra info
      */

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

@@ -59,8 +59,24 @@ export type DynamicFormSettings<ExtendedProperties extends object = object> = {
         required?: ValidationMessage;
         /** XSD: minOccurs. Available placeholders: `{field}`, `{0}` or `{min}` (min number of filled items) */
         minOccurs?: ValidationMessage;
+        /** XSD: maxOccurs. Available placeholders: `{field}`, `{0}` or `{max}` (max number of allowed items) */
+        maxOccurs?: ValidationMessage;
         /** XSD: choiceMinOccurs. Available placeholders: `{field}`, `{0}` or `{min}` (min number of filled items) */
         choiceMinOccurs?: ValidationMessage;
+        /** XSD: choiceMaxOccurs. Available placeholders: `{field}`, `{0}` or `{max}` (max number of choice occurrences allowed) */
+        choiceMaxOccurs?: ValidationMessage;
+        /**
+         * Non-XSD: maxOccursTotal, a choice branch's opt-in cap on its own total raw occurrence
+         * count. Available placeholders: `{field}`, `{0}` or `{max}` (the offending branch's cap).
+         *
+         * This is a single choice-level aggregate, not a per-branch error: `{field}` resolves to the
+         * choice's own anchor label, never the branch's, so the message cannot name which branch is
+         * over its cap. When several branches breach their own `maxOccursTotal` at once, `{max}`/`{0}`
+         * carry the cap of the first offending branch in declaration order only, not every breached
+         * cap. A single-branch choice skips choice-level validation entirely; there a breach surfaces
+         * as the branch's own `maxOccurs` message instead.
+         */
+        maxOccursTotal?: ValidationMessage;
         /** XSD: minLength. Available placeholders: `{field}`, `{0}` or `{length}` (min length) */
         minLength?: ValidationMessage;
         /** XSD: maxLength. Available placeholders: `{field}`, `{0}` or `{length}` (max length) */

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

@@ -28,6 +28,28 @@ export type FieldMetadata<ExtendedFieldTypes extends string = string, ExtendedPr
      * { name: 'emails', type: 'text', maxOccurs: 5, minOccurs: 1, autoAddMinOccurs: false }
      */
     autoAddMinOccurs?: boolean;
+    /**
+     * Opt-in, non-XSD cap on the total number of raw occurrences a `choice` branch may reach
+     * across the whole choice, independent of the occurrence batching `maxOccurs` drives. Only
+     * meaningful on a node that is itself an entry inside a `choice` array.
+     *
+     * Plain `<xs:choice>` has no equivalent: XSD only bounds how many times the choice itself
+     * repeats and how many items a single repetition of a branch may hold, never a branch's
+     * running total across the whole choice. Use this when a per-kind ceiling ("at most 3 of this
+     * kind") is a real requirement layered on top of correct XSD batching.
+     *
+     * - With `explicitChoiceSelection: true`, the branch's add affordance disables once its own
+     *   raw item count reaches this value, regardless of the shared choice budget.
+     * - Without it (auto mode), the branch's rendered array headroom is capped at this value even
+     *   when the shared choice budget would otherwise allow more.
+     *
+     * If set lower than `maxOccurs`, the cap simply limits the effective per-iteration reach.
+     * It can only ever tighten the branch's declared `maxOccurs`: a value above it has no effect.
+     *
+     * Read from static metadata only: it is excluded from `ComputedPropsFieldType`, so a
+     * `computedProps` function cannot flip occurrence capacity mid-form.
+     */
+    maxOccursTotal?: number;
     /**
      * Simple restrictions to the data, these are available in XSD and can be applied easily.
      * For more advance validation use the validation property.
@@ -117,6 +139,86 @@ export type FieldMetadata<ExtendedFieldTypes extends string = string, ExtendedPr
      *
      */
     choice?: FieldMetadata<ExtendedFieldTypes, ExtendedProperties>[];
+    /**
+     * Opt into selection-first rendering for a `choice` node. When true, no branch is shown until
+     * the template calls the `-choice` slot's (`-choice-array` for `maxOccurs > 1`)
+     * `addChoiceOccurrence(branchKey)`; the engine clears a
+     * deselected branch from the form values on switch. When false or omitted (the default), the
+     * current value-driven behaviour is unchanged: every branch renders and siblings disable once
+     * one holds a value.
+     *
+     * Has no effect on non-choice nodes. Read from static metadata only: it is excluded from
+     * `ComputedPropsFieldType`, so a `computedProps` function cannot flip it at runtime.
+     */
+    explicitChoiceSelection?: boolean;
+    /**
+     * Opt into preserve-on-switch for a `maxOccurs: 1` explicit choice (only meaningful together
+     * with `explicitChoiceSelection: true`). When true, switching away from a branch (calling
+     * `addChoiceOccurrence` for a different branch) deep-clones that branch's current values into
+     * an ephemeral, instance-local stash before clearing it as usual; switching back to that branch
+     * restores the stashed values via `setFieldValue`. The stash is never written to the form
+     * `values`, exactly like the selection state itself.
+     *
+     * When false or omitted (the default), switching clears the branch with nothing preserved,
+     * matching the baseline clear-on-switch behaviour.
+     *
+     * Restored fields start with fresh touched/validation state (as if freshly re-entered), and no
+     * error renders immediately after restore even if a required field is still empty.
+     *
+     * Has no effect on non-choice nodes, on `maxOccurs > 1` explicit choices, or when
+     * `explicitChoiceSelection` is not set. Read reactively from the metadata, so it may be
+     * flipped live through the metadata prop; it is excluded from `ComputedPropsFieldType`, so
+     * the metadata prop (not `computedProps`) is the channel for changing it.
+     */
+    preserveOnSwitch?: boolean;
+    /**
+     * How a repeatable explicit choice (`explicitChoiceSelection: true`, `maxOccurs > 1`) orders
+     * its occurrences on screen:
+     *
+     * - `'grouped'` (default): grouped by branch, in declaration order.
+     * - `'added'`: in the order the user clicked "add", mixing branches. Occurrences from loaded
+     *   data render first, in grouped order. This order is display-only and resets on reload;
+     *   combine with `preserveOrder` to keep it.
+     *
+     * May be changed while the form is mounted; the list re-sorts in place. Ignored everywhere
+     * else, and not settable from `computedProps`.
+     */
+    displayOrder?: 'grouped' | 'added';
+    /**
+     * Stores the add-order of a repeatable explicit choice (`explicitChoiceSelection: true`,
+     * `maxOccurs > 1`) in the form values, so it survives a reload: each occurrence gets a
+     * numeric `order` field (1..N across all branches, renumbered on removal, normalized at
+     * mount for loaded data). Use together with `displayOrder: 'added'`, which then sorts by
+     * this field.
+     *
+     * Note that `order` becomes part of your submitted values, next to the occurrence's own
+     * fields. Don't declare a child named `order` yourself; the engine owns that key.
+     *
+     * Requires every branch to have `children`, since the `order` field needs an object to live
+     * in. If any branch is a bare scalar, the flag is ignored for the whole choice, with a
+     * warning in development.
+     *
+     * May be changed while the form is mounted: turning it on adds `order` to the existing
+     * occurrences, seeding it from this session's add-order (so an interleaved display keeps the
+     * sequence the user built) and from grouped position for occurrences not added this session;
+     * turning it off removes it. Ignored everywhere else, and not settable from `computedProps`.
+     */
+    preserveOrder?: boolean;
+    /**
+     * Marks this node as a wizard: a first-class shape rendered through `DynamicFormItemWizard`,
+     * checked before `choice`/array/parent detection. Its pages are its `children` in declaration
+     * order; a non-empty `choice` or a `maxOccurs > 1` on the same node is ignored (a dev-mode
+     * `console.warn` fires once per ignored property). A choice of wizards or a repeated wizard is
+     * expressed by nesting `wizard: true` nodes inside a plain `choice` branch or an array item's
+     * children instead.
+     *
+     * `true` selects the defaults (linear: `next` blocks on an invalid page, forward `gotoStep` jumps
+     * refused); an object form opts into per-wizard configuration (see `WizardConfig`).
+     *
+     * Static, render-mode-defining metadata: excluded from `ComputedPropsFieldType` so
+     * `computedProps` cannot flip it mid-form.
+     */
+    wizard?: boolean | WizardConfig;
     /**
      * Attributes are additional metadata that can be attached to a field.
      * These attributes can be used to provide extra information about the field,
@@ -178,7 +280,27 @@ export type FieldMetadata<ExtendedFieldTypes extends string = string, ExtendedPr
      */
     computeOnChildValueChange?: boolean;
 } & ExtendedProperties;
-export type ComputedPropsFieldType<ExtendedFieldTypes extends string = string, ExtendedProperties extends object = object> = Omit<FieldMetadata<ExtendedFieldTypes, ExtendedProperties>, 'name' | 'path' | 'parent' | 'children' | 'choice' | 'attributes' | 'fieldOptions' | 'computedProps' | 'maxOccurs' | 'isComplexType' | 'computeOnChildValueChange'> & Readonly<{
+/** Per-wizard navigation gating. `wizard: true` resolves to `{ allowForwardJump: false, validateOnJump: true }`. */
+export interface WizardConfig {
+    /**
+     * Make the wizard non-linear: forward movement (both `next` and forward `gotoStep`) surfaces page
+     * errors but never blocks, so the user can move ahead with an invalid page. Default `false`, a
+     * linear wizard where `next` blocks on an invalid page and forward `gotoStep` jumps are refused.
+     */
+    allowForwardJump?: boolean;
+    /**
+     * Run validation on non-blocking forward movement so page errors surface. Default `true`; set
+     * `false` for a silent jump that moves without validating. No effect on a linear `next` (which
+     * always validates to decide whether to block) or on backward navigation (always silent).
+     */
+    validateOnJump?: boolean;
+}
+/** Call-time overrides for a single `gotoStep` call, taking priority over the wizard's own `WizardConfig`. */
+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<{
     name: string;
     path: string;
     parent: FieldMetadata<ExtendedFieldTypes, ExtendedProperties>;

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

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

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

@@ -1,7 +1,7 @@
 import type { GetMetadataType } from '../../types/GetMetadataType';
 export type TestMetadata = GetMetadataType<typeof _metadata>;
 declare const _metadata: {
-    fieldTypes: readonly ("default" | "text")[];
+    fieldTypes: readonly ("text" | "default")[];
     extendedProperties: {
         visited?: boolean;
         visitOrder?: number;

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

@@ -0,0 +1,10 @@
+/**
+ * Deep-clones a form value tree (plain objects, arrays, Dates and primitives) into plain,
+ * non-reactive data.
+ *
+ * Exists because `structuredClone` cannot be used on values read from the vee-validate form
+ * context: those are Vue reactive Proxies (any branch value that is an object, i.e. a node with
+ * `children`), and `structuredClone` throws a `DataCloneError` on a Proxy. Recursively copying
+ * by property instead reads *through* the proxy, so the clone comes out raw.
+ */
+export declare function deepCloneValue<T>(value: T): T;