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

package/dist/src/components/DynamicFormTemplate.vue.d.ts

@@ -1,7 +1,7 @@
 import type { FieldContext as _FieldContext } from 'vee-validate';
 import type { ComputedRef, MaybeRefOrGetter, Ref } from 'vue';
 import type { DynamicFormSettings } from '../types/DynamicFormSettings';
-import type { ReadOnlyFieldType } from '../types/FieldMetadata';
+import type { ReadOnlyFieldType, WizardConfig, WizardGotoStepOptions } from '../types/FieldMetadata';
 import type { MetadataConfiguration } from '../types/MetadataConfiguration';
 export interface FieldContext<TValue = unknown> extends _FieldContext<TValue> {
     /**
@@ -29,7 +29,7 @@ export interface LimitedFieldContext<TValue = unknown> {
  * public prop signature of the user-facing DynamicFormTemplate component.
  */
 export interface Attributes<TMetadataConfiguration extends MetadataConfiguration> {
-    type: TMetadataConfiguration['fieldTypes'][number] | 'default' | 'default-array' | 'default-array-item' | 'default-choice';
+    type: TMetadataConfiguration['fieldTypes'][number] | 'default' | 'default-array' | 'default-array-item' | 'default-choice' | 'default-choice-array' | 'default-choice-array-item' | 'default-wizard' | 'default-wizard-page';
     /** The metadata you configured for this field. */
     fieldMetadata: ReadOnlyFieldType<TMetadataConfiguration['fieldTypes'][number], TMetadataConfiguration['extendedProperties']>;
     /** Whether the field is required. */
@@ -72,6 +72,91 @@ export interface ItemAttributes<TMetadataConfiguration extends MetadataConfigura
 export interface ArrayChoiceAttributes<TMetadataConfiguration extends MetadataConfiguration> extends Attributes<TMetadataConfiguration> {
     fieldContext: LimitedFieldContext<unknown[]>;
 }
+/** An active branch occurrence, as reported by `activeChoiceOccurrences`. */
+export interface ChoiceOccurrence {
+    /** The choice branch's `name` (e.g. 'selfServe', 'apiEndpoint'). */
+    branchKey: string;
+    /** 0 for maxOccurs:1; the occurrence's index within its branch for maxOccurs > 1. */
+    index: number;
+}
+export interface ChoiceAttributes<TMetadataConfiguration extends MetadataConfiguration> extends ArrayChoiceAttributes<TMetadataConfiguration> {
+    /** Mark a branch active (maxOccurs:1) or add one occurrence of it (maxOccurs > 1). No-op when canAddChoiceOccurrence is false. */
+    addChoiceOccurrence: (branchKey: string) => void;
+    /** Remove a previously added occurrence. index is required in maxOccurs > 1; ignored (optional) in maxOccurs:1 where it deselects the active branch. */
+    removeChoiceOccurrence: (branchKey: string, index?: number) => void;
+    /** Per-branch guard: false when this branch's own maxOccurs or the choice's shared occurrence budget is exhausted, or when the choice is disabled. */
+    canAddChoiceOccurrence: (branchKey: string) => boolean;
+    /** The currently active occurrences the template iterates for counts/selector state. */
+    activeChoiceOccurrences: ChoiceOccurrence[];
+    /**
+     * Choice slots currently consumed, in choice-occurrence units rather than raw item count.
+     * For a repeatable branch (its own `maxOccurs > 1`), every group of up to that many items
+     * counts as one slot, the same unit `maxOccurs` on the choice itself is measured in, so a
+     * template can show an accurate "N of maxOccurs" without re-deriving the batching math.
+     */
+    usedChoiceOccurrences: number;
+}
+/**
+ * Slot props for a single occurrence of a repeatable explicit choice (`maxOccurs > 1`), rendered
+ * through the `*-choice-array-item` / `default-choice-array-item` slot. Mirrors `ItemAttributes`
+ * (the same shape `*-array-item` receives) plus `branchKey`, the occurrence's branch name (drives
+ * a "kind" badge in the template).
+ */
+export interface ChoiceArrayItemAttributes<TMetadataConfiguration extends MetadataConfiguration, FieldType extends string = string> extends ItemAttributes<TMetadataConfiguration, FieldType> {
+    /** The choice branch this occurrence belongs to (the child's `name`). Drives the "kind" badge. */
+    branchKey: string;
+    /**
+     * This occurrence's zero-based position across every branch's active occurrences, in the same
+     * order `activeChoiceOccurrences` reports them (grouped by branch declaration order, then by
+     * index within branch). Renumbers live when an occurrence is removed; never stored.
+     */
+    globalIndex: number;
+    /**
+     * This occurrence's ephemeral, instance-local add-order position (1-based, in add-press order
+     * across every branch), set only when it was added via `addChoiceOccurrence` this session.
+     * `undefined` for an occurrence that already existed when the form mounted (loaded saved data).
+     * Gone on remount; never stored in form values.
+     */
+    insertionOrder?: number;
+}
+/**
+ * Slot props for the wizard container (`<type>-wizard` / `default-wizard`). `pages` is the
+ * engine's resolved page list (the corrected page metadata nodes, in page order): the single
+ * source of truth for a stepper, so a template never re-derives `fieldMetadata.children` itself.
+ */
+export interface WizardAttributes<TMetadataConfiguration extends MetadataConfiguration> extends Attributes<TMetadataConfiguration> {
+    fieldContext: LimitedFieldContext;
+    currentStepIndex: number;
+    pages: ReadOnlyFieldType<TMetadataConfiguration['fieldTypes'][number], TMetadataConfiguration['extendedProperties']>[];
+    pageCount: number;
+    isFirst: boolean;
+    isLast: boolean;
+    isValidating: boolean;
+    /** The wizard's navigation config with defaults applied, so a stepper reflects the resolved mode (e.g. enable forward jumps when `allowForwardJump`) without re-reading `fieldMetadata.wizard` or re-deriving defaults. */
+    wizardConfig: Required<WizardConfig>;
+    next: () => Promise<void>;
+    prev: () => void;
+    gotoStep: (index: number, options?: WizardGotoStepOptions) => Promise<void> | void;
+}
+/**
+ * Slot props for a single wizard page (`<type>-wizard-page` / `default-wizard-page`). Delivered
+ * for every page, not only the current one; the template gates visibility with `isCurrent`
+ * (`v-show`, never `v-if`: `v-if` deregisters the page's fields from vee-validate regardless of
+ * `keepValuesOnUnmount`, and also clears their values unless that flag is set, so `v-show` stays
+ * required for any page with fields).
+ */
+export interface WizardPageAttributes<TMetadataConfiguration extends MetadataConfiguration> extends Attributes<TMetadataConfiguration> {
+    isCurrent: boolean;
+    pageIndex: number;
+    currentStepIndex: number;
+    isFirst: boolean;
+    isLast: boolean;
+    /** The wizard's navigation config with defaults applied (same object as the container slot), so a page can build its own mode-aware controls. */
+    wizardConfig: Required<WizardConfig>;
+    next: () => Promise<void>;
+    prev: () => void;
+    gotoStep: (index: number, options?: WizardGotoStepOptions) => Promise<void> | void;
+}
 declare const _default: <TMetadataConfiguration extends MetadataConfiguration>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_expose?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
     props: __VLS_PrettifyLocal<Pick<Partial<{}> & Omit<{} & import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps, never>, never> & DynamicFormConfigurationProps<TMetadataConfiguration> & Partial<{}>> & import("vue").PublicProps;
     expose(exposed: import("vue").ShallowUnwrapRef<{}>): void;
@@ -85,8 +170,16 @@ declare const _default: <TMetadataConfiguration extends MetadataConfiguration>(_
     } & {
         'default-array-item': (props: ItemAttributes<TMetadataConfiguration, string>) => any;
     } & {
-        'default-choice': (props: ArrayChoiceAttributes<TMetadataConfiguration>) => any;
-    } & { [K in TMetadataConfiguration["fieldTypes"][number]]: (props: ItemAttributes<TMetadataConfiguration, K>) => any; } & { [K_1 in `${TMetadataConfiguration["fieldTypes"][number]}-input`]: (props: ItemAttributes<TMetadataConfiguration, K_1 extends `${infer FieldType}-input` ? FieldType : never>) => any; } & { [K_2 in `${TMetadataConfiguration["fieldTypes"][number]}-array`]: (props: ArrayChoiceAttributes<TMetadataConfiguration>) => any; } & { [K_3 in `${TMetadataConfiguration["fieldTypes"][number]}-array-item`]: (props: ItemAttributes<TMetadataConfiguration, K_3 extends `${infer FieldType}-input` ? FieldType : never>) => any; } & { [K_4 in `${TMetadataConfiguration["fieldTypes"][number]}-choice`]: (props: ArrayChoiceAttributes<TMetadataConfiguration>) => any; };
+        'default-choice': (props: ChoiceAttributes<TMetadataConfiguration>) => any;
+    } & {
+        'default-choice-array': (props: ChoiceAttributes<TMetadataConfiguration>) => any;
+    } & {
+        'default-choice-array-item': (props: ChoiceArrayItemAttributes<TMetadataConfiguration, string>) => any;
+    } & {
+        'default-wizard': (props: WizardAttributes<TMetadataConfiguration>) => any;
+    } & {
+        'default-wizard-page': (props: WizardPageAttributes<TMetadataConfiguration>) => any;
+    } & { [K in TMetadataConfiguration["fieldTypes"][number]]: (props: ItemAttributes<TMetadataConfiguration, K>) => any; } & { [K_1 in `${TMetadataConfiguration["fieldTypes"][number]}-input`]: (props: ItemAttributes<TMetadataConfiguration, K_1 extends `${infer FieldType}-input` ? FieldType : never>) => any; } & { [K_2 in `${TMetadataConfiguration["fieldTypes"][number]}-array`]: (props: ArrayChoiceAttributes<TMetadataConfiguration>) => any; } & { [K_3 in `${TMetadataConfiguration["fieldTypes"][number]}-array-item`]: (props: ItemAttributes<TMetadataConfiguration, K_3 extends `${infer FieldType}-input` ? FieldType : never>) => any; } & { [K_4 in `${TMetadataConfiguration["fieldTypes"][number]}-choice`]: (props: ChoiceAttributes<TMetadataConfiguration>) => any; } & { [K_5 in `${TMetadataConfiguration["fieldTypes"][number]}-choice-array`]: (props: ChoiceAttributes<TMetadataConfiguration>) => any; } & { [K_6 in `${TMetadataConfiguration["fieldTypes"][number]}-choice-array-item`]: (props: ChoiceArrayItemAttributes<TMetadataConfiguration, K_6 extends `${infer FieldType}-choice-array-item` ? FieldType : never>) => any; } & { [K_7 in `${TMetadataConfiguration["fieldTypes"][number]}-wizard`]: (props: WizardAttributes<TMetadataConfiguration>) => any; } & { [K_8 in `${TMetadataConfiguration["fieldTypes"][number]}-wizard-page`]: (props: WizardPageAttributes<TMetadataConfiguration>) => any; };
     emit: {};
 }>) => import("vue").VNode & {
     __ctx?: Awaited<typeof __VLS_setup>;

package/dist/src/components/__tests__/DynamicFormItem.formApi.test.d.ts

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

package/dist/src/components/__tests__/DynamicFormItem.unmount.logic.test.d.ts

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

package/dist/src/components/__tests__/DynamicFormItemArray.analytics.test.d.ts

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

package/dist/src/components/__tests__/DynamicFormItemArray.formApi.test.d.ts

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

package/dist/src/components/__tests__/DynamicFormItemArray.test-helpers.d.ts

@@ -0,0 +1,9 @@
+import type { mount } from '@vue/test-utils';
+/**
+ * Accesses the internal `<script setup>` state of the DynamicFormItemArray registered at `path`.
+ * Mirrors `DynamicFormItem.test-helpers.ts`'s `setupState`, reaching into `vm.$.setupState` for
+ * private state not exposed via `defineExpose`.
+ */
+export declare function setupState(wrapper: ReturnType<typeof mount>, path: string): Record<string, any> | undefined;
+/** Reads how many times the array's `combinedValidation` computed has run. Returns -1 if the array is not found. */
+export declare function arrayConstructValidationCount(wrapper: ReturnType<typeof mount>, path: string): number;

package/dist/src/components/__tests__/DynamicFormItemChoice.analytics.test.d.ts

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

package/dist/src/components/__tests__/DynamicFormItemChoice.formApi.test.d.ts

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

package/dist/src/components/__tests__/DynamicFormItemChoice.test-helpers.d.ts

@@ -0,0 +1,100 @@
+import type { mount } from '@vue/test-utils';
+/**
+ * Accesses the internal `<script setup>` state of the DynamicFormItemChoice registered at `path`
+ * (matched via its `normalizedPath` setup variable). Mirrors `DynamicFormItem.test-helpers.ts`'s
+ * `setupState`, reaching into `vm.$.setupState` for private state not exposed via `defineExpose`.
+ */
+export declare function setupState(wrapper: ReturnType<typeof mount>, path: string): Record<string, any> | undefined;
+/** Finds the DynamicFormItemChoice instance registered at `path` (its `normalizedPath`). */
+export declare function findDynamicFormItemChoiceByPath(wrapper: ReturnType<typeof mount>, path: string): import("@vue/test-utils").VueWrapper<any, any> | undefined;
+/** Reads `activeChoiceOccurrences` for the choice at `path`. Returns undefined if the choice is not found. */
+export declare function activeChoiceOccurrences(wrapper: ReturnType<typeof mount>, path: string): {
+    branchKey: string;
+    index: number;
+}[] | undefined;
+/** Reads `explicitlySelectedBranch` for the choice at `path`. Returns undefined if the choice is not found. */
+export declare function explicitlySelectedBranch(wrapper: ReturnType<typeof mount>, path: string): string | null | undefined;
+/**
+ * Reads the ephemeral preserve-on-switch stash for the choice at `path`. Returns
+ * undefined if the choice is not found. Best-effort internal-state reader: it names the stash
+ * ref directly for tests that want a stronger assertion than the observable restore
+ * behaviour alone.
+ */
+export declare function stashedBranchValues(wrapper: ReturnType<typeof mount>, path: string): Record<string, unknown> | undefined;
+/**
+ * Patches fixture metadata to enable preserve-on-switch on the choice at `branchKey`
+ * (the choice's own `name`, e.g. `'pick'`). Centralises the flag surface (the `FieldMetadata`
+ * boolean `preserveOnSwitch`) so tests do not hardcode a property name directly.
+ */
+export declare function enablePreserveOnSwitch<T>(metadata: T[], choicePath: string, enabled?: boolean): T[];
+/**
+ * Reads the `childValues` entry for `branchKey` at the choice registered at `path`, resolving the
+ * branch name to its internal numeric index via the choice's own metadata.
+ */
+export declare function childValuesEntry(wrapper: ReturnType<typeof mount>, path: string, branchKey: string): {
+    occurrences: number;
+    valuesCount: number;
+} | undefined;
+/**
+ * Reads the `-kind-badge` testid text at `occurrencePath` (e.g. `pick.apiEndpoint[0]`), asserting
+ * the `*-choice-array-item`/`default-choice-array-item` slot actually received `branchKey` as a real slot
+ * prop, rather than the test inferring it from the path itself.
+ */
+export declare function occurrenceBranchKey(wrapper: ReturnType<typeof mount>, occurrencePath: string): string | undefined;
+/**
+ * Reads the `-global-index` testid at `occurrencePath` (e.g. `pick.apiEndpoint[0]`), asserting
+ * the `*-choice-array-item`/`default-choice-array-item` slot actually received `globalIndex` as a
+ * real slot prop, rather than the test inferring it from the path itself. Mirrors
+ * `occurrenceBranchKey`'s rationale.
+ */
+export declare function occurrenceGlobalIndex(wrapper: ReturnType<typeof mount>, occurrencePath: string): number | undefined;
+/**
+ * Reads the fixture's per-branch add-choice button `disabled` attribute for `branchKey` at the
+ * choice rendered at `choicePath`, exercising `canAddChoiceOccurrence` through the real public
+ * slot-prop contract (the same indirection used elsewhere in this suite), not a `setupState()` reach-in.
+ */
+export declare function canAddChoiceOccurrence(wrapper: ReturnType<typeof mount>, choicePath: string, branchKey: string): boolean;
+/**
+ * Reads the `usedChoiceOccurrences` slot prop for the choice rendered at `choicePath`, through
+ * the fixture's real public slot-prop contract (the same indirection `canAddChoiceOccurrence`
+ * above uses), not a `setupState()` reach-in.
+ */
+export declare function usedChoiceOccurrences(wrapper: ReturnType<typeof mount>, choicePath: string): number | undefined;
+/** Reads the number of rules currently present in `combinedValidation` for the choice at `path`. */
+export declare function combinedValidationCount(wrapper: ReturnType<typeof mount>, path: string): number;
+/** Reads the `maxOccursTotalBreach` computed (the offending branch's cap, or undefined) for the choice at `path`. */
+export declare function maxOccursTotalBreach(wrapper: ReturnType<typeof mount>, path: string): number | undefined;
+/**
+ * Reads the `-insertion-order` testid at `occurrencePath` (e.g. `pick.apiEndpoint[0]`), asserting
+ * the `*-choice-array-item`/`default-choice-array-item` slot actually received `insertionOrder` as
+ * a real slot prop. Unlike `occurrenceGlobalIndex`, the testid is conditionally rendered (the
+ * fixture's `v-if`), so its absence (an occurrence never added this session) reads back as
+ * `undefined` rather than a rendered "undefined" string.
+ */
+export declare function occurrenceInsertionOrder(wrapper: ReturnType<typeof mount>, occurrencePath: string): number | undefined;
+/** Reads the internal `renderedChoiceOccurrences` computed for the choice at `path`. Returns undefined if the choice is not found. */
+export declare function renderedChoiceOccurrences(wrapper: ReturnType<typeof mount>, path: string): {
+    branchKey: string;
+    index: number;
+}[] | undefined;
+/**
+ * Reads the ephemeral `insertionOrders` map for the choice at `path`. Returns undefined if the
+ * choice is not found. Best-effort internal-state reader, mirroring `stashedBranchValues`'s
+ * rationale: it names the store directly so a test can assert it is instance-local (a plain `Map`,
+ * never anything reachable through form `values`), a stronger check than the observable slot-prop
+ * values alone.
+ */
+export declare function insertionOrdersMap(wrapper: ReturnType<typeof mount>, path: string): Map<string, number> | undefined;
+/**
+ * Patches fixture metadata to set `displayOrder` on the choice at `choicePath` (the choice's own
+ * `name`, e.g. `'pick'`). Centralises the flag surface (the `FieldMetadata` property
+ * `displayOrder`) so tests do not hardcode the property name, mirroring `enablePreserveOnSwitch`.
+ */
+export declare function enableDisplayOrder<T>(metadata: T[], choicePath: string, mode?: 'grouped' | 'added'): T[];
+/**
+ * Patches fixture metadata to enable `preserveOrder` on the choice at `choicePath` (the choice's
+ * own `name`, e.g. `'pick'`). Centralises the flag surface (the `FieldMetadata` boolean
+ * `preserveOrder`) so tests do not hardcode a property name directly, mirroring
+ * `enablePreserveOnSwitch`/`enableDisplayOrder` field-for-field.
+ */
+export declare function enablePreserveOrder<T>(metadata: T[], choicePath: string, enabled?: boolean): T[];

package/dist/src/components/__tests__/DynamicFormItemWizard.analytics.test.d.ts

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

package/dist/src/components/__tests__/DynamicFormItemWizard.formApi.test.d.ts

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

package/dist/src/components/__tests__/DynamicFormItemWizard.logic.test.d.ts

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

package/dist/src/components/__tests__/DynamicFormItemWizard.test-helpers.d.ts

@@ -0,0 +1,24 @@
+import type { mount } from '@vue/test-utils';
+/**
+ * Accesses the internal `<script setup>` state of the DynamicFormItemWizard registered at `path`
+ * (matched via its `normalizedPath` setup variable). Mirrors `DynamicFormItemChoice.test-helpers.ts`'s
+ * `setupState`.
+ */
+export declare function setupState(wrapper: ReturnType<typeof mount>, path: string): Record<string, any> | undefined;
+/** Finds the DynamicFormItemWizard instance registered at `path` (its `normalizedPath`). */
+export declare function findDynamicFormItemWizardByPath(wrapper: ReturnType<typeof mount>, path: string): import("@vue/test-utils").VueWrapper<any, any> | undefined;
+export declare function currentStepIndex(wrapper: ReturnType<typeof mount>, path: string): number;
+export declare function pageCount(wrapper: ReturnType<typeof mount>, path: string): number;
+export declare function isFirst(wrapper: ReturnType<typeof mount>, path: string): boolean;
+export declare function isLast(wrapper: ReturnType<typeof mount>, path: string): boolean;
+export declare function isValidating(wrapper: ReturnType<typeof mount>, path: string): boolean;
+/** Reads the resolved `wizardConfig` slot prop (defaults applied) as surfaced by the test fixture. */
+export declare function wizardConfig(wrapper: ReturnType<typeof mount>, path: string): {
+    allowForwardJump: boolean;
+    validateOnJump: boolean;
+};
+export declare function clickNext(wrapper: ReturnType<typeof mount>, path: string): Promise<void>;
+export declare function clickPrev(wrapper: ReturnType<typeof mount>, path: string): Promise<void>;
+export declare function clickGotoStep(wrapper: ReturnType<typeof mount>, path: string, index: number): Promise<void>;
+/** Reads the `v-show`-driven visibility of the page rendered at `pagePath`, through the fixture's `-page` wrapper. */
+export declare function isPageVisible(wrapper: ReturnType<typeof mount>, pagePath: string): boolean;

package/dist/src/components/__tests__/DynamicFormItemWizard.validation.test.d.ts

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

package/dist/src/components/__tests__/DynamicFormTemplate.test.d.ts

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

package/dist/src/core/__tests__/useIsResetPending.test.d.ts

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

package/dist/src/core/__tests__/useIsValidationSuppressed.test.d.ts

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

package/dist/src/core/useIsResetPending.d.ts

@@ -0,0 +1,13 @@
+import type { MaybeRefOrGetter } from 'vue';
+/**
+ * While `resetForm()` / `resetField()` flushes, vee-validate marks every affected path state
+ * with a private `pendingReset` flag (cleared again on the next tick) so that its own value
+ * watchers skip validation during the reset. Our components own their validation timing through
+ * custom value watchers, so they must honour the same flag; otherwise the reset-triggered value
+ * change would validate the freshly reset value and write the just-cleared errors straight back.
+ *
+ * `getPathState` and `__flags` are deliberately left off vee-validate's public FormContext type,
+ * so they are read through a loosely typed access (the same way DynamicFormItem reads
+ * `keepValuesOnUnmount`).
+ */
+export declare function useIsResetPending(path: MaybeRefOrGetter<string>): () => boolean;

package/dist/src/core/useIsValidationSuppressed.d.ts

@@ -0,0 +1,20 @@
+import type { MaybeRefOrGetter } from 'vue';
+/**
+ * Makes a form context's `shouldValidate: false` argument actually stick: wraps `setFieldValue`
+ * and `setValues` so that writes which ask to skip validation are remembered until their flush
+ * settles. vee-validate only skips its *own* validation for such writes; our components run their
+ * validation from custom value watchers, which would otherwise fire regardless.
+ *
+ * Mutates the context in place (vee-validate provides the very object it returns from `useForm`),
+ * so the consumer's handle and every injected `useFormContext()` share the wrapped functions.
+ * Safe to call multiple times on the same form.
+ */
+export declare function trackNonValidatingWrites(form: unknown): void;
+/**
+ * True while the field's value is changing through a programmatic write that asked not to
+ * validate: a `resetForm()`/`resetField()` flush (vee-validate's `pendingReset` window) or a
+ * `setFieldValue`/`setValues` call with `shouldValidate: false` on a form wrapped by
+ * `trackNonValidatingWrites`. Value watchers that own validation timing must skip validation
+ * while this returns true, otherwise they would override the caller's explicit intent.
+ */
+export declare function useIsValidationSuppressed(path: MaybeRefOrGetter<string>): () => boolean;

package/dist/src/core/validation.d.ts

@@ -1,6 +1,12 @@
 export { resolveMessage } from '../utils/resolveMessage';
-/** XSD-derived rule names registered globally via vee-validate's `defineRule`. */
-export type ValidationRule = 'xsd_required' | 'xsd_minOccurs' | 'xsd_choiceMinOccurs' | 'xsd_minLength' | 'xsd_maxLength' | 'xsd_pattern' | 'xsd_minInclusive' | 'xsd_maxInclusive' | 'xsd_minExclusive' | 'xsd_maxExclusive' | 'xsd_enumeration' | 'xsd_length' | 'xsd_whiteSpace' | 'xsd_fractionDigits' | 'xsd_totalDigits';
+/**
+ * XSD-derived rule names registered globally via vee-validate's `defineRule`, plus one
+ * non-XSD occurrence extension (`vdf_maxOccursTotal`, a per-branch choice cap with no XSD
+ * equivalent). Every name is prefixed (`xsd_` or `vdf_`): `defineRule` is a last-write-wins
+ * global registry shared with the consuming app, so an unprefixed name could silently
+ * collide with a consumer-defined rule.
+ */
+export type ValidationRule = 'xsd_required' | 'xsd_minOccurs' | 'xsd_maxOccurs' | 'xsd_choiceMinOccurs' | 'xsd_choiceMaxOccurs' | 'vdf_maxOccursTotal' | 'xsd_minLength' | 'xsd_maxLength' | 'xsd_pattern' | 'xsd_minInclusive' | 'xsd_maxInclusive' | 'xsd_minExclusive' | 'xsd_maxExclusive' | 'xsd_enumeration' | 'xsd_length' | 'xsd_whiteSpace' | 'xsd_fractionDigits' | 'xsd_totalDigits';
 /**
  * Maps each rule to its semantic parameter name, enabling named placeholder
  * interpolation (e.g. `{length}`, `{min}`) alongside positional `{0}` in messages.

package/dist/src/examples/KeepValuesOnUnmountTestCase.vue.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("vue").DefineComponent<{}, void, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+export default _default;

package/dist/src/examples/ProgrammaticWritesTestCase.vue.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("vue").DefineComponent<{}, void, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+export default _default;

package/dist/src/examples/TestForm.vue.d.ts

@@ -7,6 +7,12 @@ export interface Props {
     initialEdit?: boolean;
     hideFieldsWithoutValue?: boolean;
     initialValues?: GenericObject;
+    keepValuesOnUnmount?: boolean;
 }
-declare const _default: import("vue").DefineComponent<Props, void, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: import("vue").DefineComponent<Props, {
+    setFieldValue: <T extends string>(field: T, value: T extends `${infer K}.${infer R}` ? K extends string ? R extends string ? R extends infer T_1 ? T_1 extends R ? T_1 extends `${infer K}.${infer R}` ? K extends string | number | symbol ? R extends string ? R extends infer T_2 ? T_2 extends R ? T_2 extends `${infer K}.${infer R}` ? K extends string | number | symbol ? R extends string ? R extends infer T_3 ? T_3 extends R ? T_3 extends `${infer K}.${infer R}` ? K extends string | number | symbol ? R extends string ? R extends infer T_4 ? T_4 extends R ? T_4 extends `${infer K}.${infer R}` ? K extends string | number | symbol ? R extends string ? R extends infer T_5 ? T_5 extends R ? T_5 extends `${infer K}.${infer R}` ? K extends string | number | symbol ? R extends string ? R extends infer T_6 ? T_6 extends R ? T_6 extends `${infer K}.${infer R}` ? K extends string | number | symbol ? R extends string ? R extends infer T_7 ? T_7 extends R ? T_7 extends `${infer K}.${infer R}` ? K extends string | number | symbol ? R extends string ? R extends infer T_8 ? T_8 extends R ? T_8 extends `${infer K}.${infer R}` ? K extends string | number | symbol ? R extends string ? R extends infer T_9 ? T_9 extends R ? T_9 extends `${infer K}.${infer R}` ? K extends string | number | symbol ? R extends string ? R extends infer T_10 ? T_10 extends R ? T_10 extends `${infer K}.${infer R}` ? K extends string | number | symbol ? R extends string ? /*elided*/ any : never : K extends `${number}` ? /*elided*/ any : never : T_10 extends string | number | symbol ? any : T_10 extends `${number}` ? unknown : never : never : never : never : K extends `${number}` ? R & "" extends infer T_11 ? T_11 extends R & "" ? T_11 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? /*elided*/ any : never : K extends `${number}` ? never : never : T_11 extends never ? unknown : T_11 extends `${number}` ? never : never : never : never : never : T_9 extends string | number | symbol ? any : T_9 extends `${number}` ? unknown : never : never : never : never : K extends `${number}` ? R & "" extends infer T_12 ? T_12 extends R & "" ? T_12 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? R extends infer T_13 ? T_13 extends R ? T_13 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? /*elided*/ any : never : K extends `${number}` ? never : never : T_13 extends never ? unknown : T_13 extends `${number}` ? never : never : never : never : never : K extends `${number}` ? never : never : T_12 extends never ? unknown : T_12 extends `${number}` ? never : never : never : never : never : T_8 extends string | number | symbol ? any : T_8 extends `${number}` ? unknown : never : never : never : never : K extends `${number}` ? R & "" extends infer T_14 ? T_14 extends R & "" ? T_14 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? R extends infer T_15 ? T_15 extends R ? T_15 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? R extends infer T_16 ? T_16 extends R ? T_16 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? /*elided*/ any : never : K extends `${number}` ? never : never : T_16 extends never ? unknown : T_16 extends `${number}` ? never : never : never : never : never : K extends `${number}` ? never : never : T_15 extends never ? unknown : T_15 extends `${number}` ? never : never : never : never : never : K extends `${number}` ? never : never : T_14 extends never ? unknown : T_14 extends `${number}` ? never : never : never : never : never : T_7 extends string | number | symbol ? any : T_7 extends `${number}` ? unknown : never : never : never : never : K extends `${number}` ? R & "" extends infer T_17 ? T_17 extends R & "" ? T_17 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? R extends infer T_18 ? T_18 extends R ? T_18 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? R extends infer T_19 ? T_19 extends R ? T_19 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? R extends infer T_20 ? T_20 extends R ? T_20 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? /*elided*/ any : never : K extends `${number}` ? never : never : T_20 extends never ? unknown : T_20 extends `${number}` ? never : never : never : never : never : K extends `${number}` ? never : never : T_19 extends never ? unknown : T_19 extends `${number}` ? never : never : never : never : never : K extends `${number}` ? never : never : T_18 extends never ? unknown : T_18 extends `${number}` ? never : never : never : never : never : K extends `${number}` ? never : never : T_17 extends never ? unknown : T_17 extends `${number}` ? never : never : never : never : never : T_6 extends string | number | symbol ? any : T_6 extends `${number}` ? unknown : never : never : never : never : K extends `${number}` ? R & "" extends infer T_21 ? T_21 extends R & "" ? T_21 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? R extends infer T_22 ? T_22 extends R ? T_22 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? R extends infer T_23 ? T_23 extends R ? T_23 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? R extends infer T_24 ? T_24 extends R ? T_24 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? R extends infer T_25 ? T_25 extends R ? T_25 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? /*elided*/ any : never : K extends `${number}` ? never : never : T_25 extends never ? unknown : T_25 extends `${number}` ? never : never : never : never : never : K extends `${number}` ? never : never : T_24 extends never ? unknown : T_24 extends `${number}` ? never : never : never : never : never : K extends `${number}` ? never : never : T_23 extends never ? unknown : T_23 extends `${number}` ? never : never : never : never : never : K extends `${number}` ? never : never : T_22 extends never ? unknown : T_22 extends `${number}` ? never : never : never : never : never : K extends `${number}` ? never : never : T_21 extends never ? unknown : T_21 extends `${number}` ? never : never : never : never : never : T_5 extends string | number | symbol ? any : T_5 extends `${number}` ? unknown : never : never : never : never : K extends `${number}` ? R & "" extends infer T_26 ? T_26 extends R & "" ? T_26 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? R extends infer T_27 ? T_27 extends R ? T_27 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? R extends infer T_28 ? T_28 extends R ? T_28 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? R extends infer T_29 ? T_29 extends R ? T_29 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? R extends infer T_30 ? T_30 extends R ? T_30 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? R extends infer T_31 ? T_31 extends R ? T_31 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? /*elided*/ any : never : K extends `${number}` ? never : never : T_31 extends never ? unknown : T_31 extends `${number}` ? never : never : never : never : never : K extends `${number}` ? never : never : T_30 extends never ? unknown : T_30 extends `${number}` ? never : never : never : never : never : K extends `${number}` ? never : never : T_29 extends never ? unknown : T_29 extends `${number}` ? never : never : never : never : never : K extends `${number}` ? never : never : T_28 extends never ? unknown : T_28 extends `${number}` ? never : never : never : never : never : K extends `${number}` ? never : never : T_27 extends never ? unknown : T_27 extends `${number}` ? never : never : never : never : never : K extends `${number}` ? never : never : T_26 extends never ? unknown : T_26 extends `${number}` ? never : never : never : never : never : T_4 extends string | number | symbol ? any : T_4 extends `${number}` ? unknown : never : never : never : never : K extends `${number}` ? R & "" extends infer T_32 ? T_32 extends R & "" ? T_32 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? R extends infer T_33 ? T_33 extends R ? T_33 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? R extends infer T_34 ? T_34 extends R ? T_34 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? R extends infer T_35 ? T_35 extends R ? T_35 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? R extends infer T_36 ? T_36 extends R ? T_36 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? R extends infer T_37 ? T_37 extends R ? T_37 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? R extends infer T_38 ? T_38 extends R ? T_38 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? /*elided*/ any : never : K extends `${number}` ? never : never : T_38 extends never ? unknown : T_38 extends `${number}` ? never : never : never : never : never : K extends `${number}` ? never : never : T_37 extends never ? unknown : T_37 extends `${number}` ? never : never : never : never : never : K extends `${number}` ? never : never : T_36 extends never ? unknown : T_36 extends `${number}` ? never : never : never : never : never : K extends `${number}` ? never : never : T_35 extends never ? unknown : T_35 extends `${number}` ? never : never : never : never : never : K extends `${number}` ? never : never : T_34 extends never ? unknown : T_34 extends `${number}` ? never : never : never : never : never : K extends `${number}` ? never : never : T_33 extends never ? unknown : T_33 extends `${number}` ? never : never : never : never : never : K extends `${number}` ? never : never : T_32 extends never ? unknown : T_32 extends `${number}` ? never : never : never : never : never : T_3 extends string | number | symbol ? any : T_3 extends `${number}` ? unknown : never : never : never : never : K extends `${number}` ? R & "" extends infer T_39 ? T_39 extends R & "" ? T_39 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? R extends infer T_40 ? T_40 extends R ? T_40 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? R extends infer T_41 ? T_41 extends R ? T_41 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? R extends infer T_42 ? T_42 extends R ? T_42 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? R extends infer T_43 ? T_43 extends R ? T_43 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? R extends infer T_44 ? T_44 extends R ? T_44 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? R extends infer T_45 ? T_45 extends R ? T_45 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? R extends infer T_46 ? T_46 extends R ? T_46 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? /*elided*/ any : never : K extends `${number}` ? never : never : T_46 extends never ? unknown : T_46 extends `${number}` ? never : never : never : never : never : K extends `${number}` ? never : never : T_45 extends never ? unknown : T_45 extends `${number}` ? never : never : never : never : never : K extends `${number}` ? never : never : T_44 extends never ? unknown : T_44 extends `${number}` ? never : never : never : never : never : K extends `${number}` ? never : never : T_43 extends never ? unknown : T_43 extends `${number}` ? never : never : never : never : never : K extends `${number}` ? never : never : T_42 extends never ? unknown : T_42 extends `${number}` ? never : never : never : never : never : K extends `${number}` ? never : never : T_41 extends never ? unknown : T_41 extends `${number}` ? never : never : never : never : never : K extends `${number}` ? never : never : T_40 extends never ? unknown : T_40 extends `${number}` ? never : never : never : never : never : K extends `${number}` ? never : never : T_39 extends never ? unknown : T_39 extends `${number}` ? never : never : never : never : never : T_2 extends string | number | symbol ? any : T_2 extends `${number}` ? unknown : never : never : never : never : K extends `${number}` ? R & "" extends infer T_47 ? T_47 extends R & "" ? T_47 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? R extends infer T_48 ? T_48 extends R ? T_48 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? R extends infer T_49 ? T_49 extends R ? T_49 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? R extends infer T_50 ? T_50 extends R ? T_50 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? R extends infer T_51 ? T_51 extends R ? T_51 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? R extends infer T_52 ? T_52 extends R ? T_52 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? R extends infer T_53 ? T_53 extends R ? T_53 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? R extends infer T_54 ? T_54 extends R ? T_54 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? R extends infer T_55 ? T_55 extends R ? T_55 extends `${infer K}.${infer R}` ? K extends never ? R extends "" ? /*elided*/ any : never : K extends `${number}` ? never : never : T_55 extends never ? unknown : T_55 extends `${number}` ? never : never : never : never : never : K extends `${number}` ? never : never : T_54 extends never ? unknown : T_54 extends `${number}` ? never : never : never : never : never : K extends `${number}` ? never : never : T_53 extends never ? unknown : T_53 extends `${number}` ? never : never : never : never : never : K extends `${number}` ? never : never : T_52 extends never ? unknown : T_52 extends `${number}` ? never : never : never : never : never : K extends `${number}` ? never : never : T_51 extends never ? unknown : T_51 extends `${number}` ? never : never : never : never : never : K extends `${number}` ? never : never : T_50 extends never ? unknown : T_50 extends `${number}` ? never : never : never : never : never : K extends `${number}` ? never : never : T_49 extends never ? unknown : T_49 extends `${number}` ? never : never : never : never : never : K extends `${number}` ? never : never : T_48 extends never ? unknown : T_48 extends `${number}` ? never : never : never : never : never : K extends `${number}` ? never : never : T_47 extends never ? unknown : T_47 extends `${number}` ? never : never : never : never : never : T_1 extends string | number | symbol ? any : T_1 extends `${number}` ? unknown : never : never : never : never : K extends `${number}` ? never : never : T extends string ? any : T extends `${number}` ? never : never, shouldValidate?: boolean) => void;
+    setValues: (fields: {
+        [x: string]: any;
+    }, shouldValidate?: boolean) => void;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 export default _default;

package/dist/src/examples/TestFormTemplate.vue.d.ts

@@ -1,9 +1,10 @@
+import type { WizardGotoStepOptions } from '../types/FieldMetadata';
 import type { GetDynamicFormSettingsType } from '../types/GetDynamicFormSettingsType';
 import type { GetMetadataType } from '../types/GetMetadataType';
 export type Metadata = GetMetadataType<typeof metadata>;
 export type DynamicFormSettings = GetDynamicFormSettingsType<typeof metadata>;
 declare const metadata: {
-    fieldTypes: readonly ("default" | "checkbox" | "select" | "text" | "textBoundByVModel" | "selectBoundByVModel" | "checkboxBoundByVModel" | "heading" | "group")[];
+    fieldTypes: readonly ("text" | "default" | "checkbox" | "select" | "textBoundByVModel" | "selectBoundByVModel" | "checkboxBoundByVModel" | "heading" | "group")[];
     extendedProperties: {
         description?: string;
         options?: {
@@ -21,9 +22,17 @@ declare const metadata: {
         /** Helps identifying that we're below a choice field, so if we're rendering an array we can adjust our layout */
         belowChoiceField?: boolean;
         hidden?: boolean;
+        /** Bound by the wizard page wrapper below, so a page's own content can offer "jump to step" affordances */
+        gotoStep?: (index: number, options?: WizardGotoStepOptions) => Promise<void> | void;
     };
     extendedSettingsProperties: {
         showOptionalInsteadOfRequired?: boolean;
+        /**
+         * Example-only switch for the wizard page wrapper: gate page visibility with `v-if` (unmounts
+         * non-current pages) instead of the correct `v-show`. Lets a playground demonstrate the
+         * clear-on-unmount data loss `v-show` avoids, and how `keepValuesOnUnmount` changes it.
+         */
+        wizardPageUseVIf?: boolean;
     };
     valueTypes: {
         text: string;
@@ -40,36 +49,62 @@ declare const metadata: {
 };
 declare var __VLS_21: {
     level: number;
-}, __VLS_24: {}, __VLS_27: {
+}, __VLS_31: {
+    hideLabel: boolean;
+    level: number;
+}, __VLS_34: {
     level: number;
     belowChoiceField: boolean;
 }, __VLS_37: {
+    level: number;
+    belowChoiceField: boolean;
+}, __VLS_54: {
+    level: number;
+}, __VLS_57: {
+    level: number;
+}, __VLS_60: {
+    gotoStep: (index: number, options?: WizardGotoStepOptions) => Promise<void> | void;
+    level: number | undefined;
+}, __VLS_62: {
+    gotoStep: (index: number, options?: WizardGotoStepOptions) => Promise<void> | void;
+    level: number | undefined;
+}, __VLS_72: {
     hideLabel: boolean;
-}, __VLS_40: {}, __VLS_49: {}, __VLS_59: {
+}, __VLS_75: {}, __VLS_84: {}, __VLS_94: {
     level: number;
-}, __VLS_61: {}, __VLS_78: {
+}, __VLS_96: {}, __VLS_113: {
     level: number;
-}, __VLS_80: {};
+}, __VLS_115: {};
 type __VLS_Slots = {} & {
     default?: (props: typeof __VLS_21) => any;
 } & {
-    default?: (props: typeof __VLS_24) => any;
+    default?: (props: typeof __VLS_31) => any;
 } & {
-    default?: (props: typeof __VLS_27) => any;
+    default?: (props: typeof __VLS_34) => any;
 } & {
     default?: (props: typeof __VLS_37) => any;
 } & {
-    default?: (props: typeof __VLS_40) => any;
+    default?: (props: typeof __VLS_54) => any;
+} & {
+    default?: (props: typeof __VLS_57) => any;
+} & {
+    default?: (props: typeof __VLS_60) => any;
+} & {
+    default?: (props: typeof __VLS_62) => any;
+} & {
+    default?: (props: typeof __VLS_72) => any;
+} & {
+    default?: (props: typeof __VLS_75) => any;
 } & {
-    attributes?: (props: typeof __VLS_49) => any;
+    attributes?: (props: typeof __VLS_84) => any;
 } & {
-    default?: (props: typeof __VLS_59) => any;
+    default?: (props: typeof __VLS_94) => any;
 } & {
-    default?: (props: typeof __VLS_61) => any;
+    default?: (props: typeof __VLS_96) => any;
 } & {
-    default?: (props: typeof __VLS_78) => any;
+    default?: (props: typeof __VLS_113) => any;
 } & {
-    attributes?: (props: typeof __VLS_80) => any;
+    attributes?: (props: typeof __VLS_115) => any;
 };
 declare const __VLS_component: import("vue").DefineComponent<{}, void, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
 declare const _default: __VLS_WithSlots<typeof __VLS_component, __VLS_Slots>;