extended-dynamic-forms 0.5.0 → 0.5.1

package/README.md

@@ -18,7 +18,7 @@ npm install 'react@^18.0.0' 'react-dom@^18.0.0' 'antd@^5.24.0' 'dayjs@^1.11.13'
 ```
 
 React and React DOM 19 are also supported by the peer ranges. Keep their major
-versions aligned. EDF 0.5.0 bundles RJSF 6.11.0 and the AJV validator;
+versions aligned. EDF 0.5.1 bundles RJSF 6.11.0 and the AJV validator;
 you do not need a sibling RJSF checkout. Before upgrading, read the
 [0.5.0 migration guide](docs/migration-0.5.md), including the breaking host-template,
 cleared-value and one-step Wizard contracts.
@@ -34,6 +34,109 @@ provided; use an ESNext/Bundler-compatible module configuration.
 - Per-field options, custom widgets, fields, templates and grid layouts.
 - Field focus, blur and change events, submission hooks and webhook configuration.
 
+## Empty values: null contract
+
+Clearing Text, Textarea, Email, URL or Telephone emits `null` by default.
+An explicit own `ui:options.emptyValue` overrides this default, including `""` and `undefined`.
+Password, Number (including String Mode), Date, Time and DateTime retain their
+existing clear values.
+
+In both `ExtendedForm` and `WizardForm`, AJV validates a copy with null object
+properties omitted, for every schema type. Optional nulls therefore behave like
+absent answers for content constraints, enums, combinators and dependencies.
+Validation-only schema resolution uses that same null-omitted copy before
+expanding dependencies and conditionals. Clearing an optional answer cannot
+activate a presence-based requirement for another field. Live answers, dynamic
+item UI and submission payloads retain the original null.
+Required null properties fail with AJV's normal required error. This applies
+deeply to nested objects and object properties inside array items. Primitive
+array slots are never removed or normalized: their schema must explicitly
+accept null. Host custom validation still receives real null answers and may
+reject them. Null does not refill a schema default.
+
+Null survives submission callbacks, Wizard step data and webhook envelopes for
+visible, enabled fields. Hidden or disabled nulls are absent, while their valued
+answers are retained. Receivers must distinguish null (“answered, then cleared”)
+from absence (which can also mean an inactive null). Explicit overrides and other
+widgets retain their own empty-value semantics. The existing envelope shapes do not
+change: ExtendedForm submit envelopes contain the RJSF event under `formData`;
+one-step Wizard submit envelopes contain flat answers, and multi-step Wizard
+submit envelopes contain step data.
+
+EDF's null acceptance policy belongs to its validator, not its widgets.
+Native hosts using EDF widgets in their own `@rjsf/core` Form must pass EDF's
+exported `nullContractValidator` to get the same acceptance policy with existing
+string-only schemas. The existing `validator` export remains plain AJV.
+With plain RJSF/AJV, widgets still emit null and a string-only schema rejects it.
+Declaring `type: ["string", "null"]` suffices for simple optional string constraints,
+but does not bypass enums, dependencies or combinators, or make required nulls
+missing. Use `nullContractValidator` for the full contract and keep required
+fields in the parent schema's `required` array. No Formstudio marker is needed.
+
+## Submitted data: hidden and disabled fields
+
+`ExtendedForm` and `WizardForm` send valued answers unchanged, including hidden
+and disabled fields. Read-only fields also remain answers. The submit callback
+and `afterSubmit` receive optional `meta` alongside `formData` only when at least
+one flag list is non-empty. When emitted, both arrays are present:
+`{ hiddenFields: string[], disabledFields: string[] }`. Unflagged callbacks keep
+their existing shape. The exported `SubmissionMeta` type describes this property.
+
+Paths are RFC 6901 JSON Pointers relative to the delivered answers, including
+array indices (`/address/street`, `/items/0/note`). Indices refer to the delivered
+array after inactive-null omission; dynamic UI still evaluates original indices.
+Structured Wizard pointers include the step key. A hidden object is listed once,
+not once per descendant. An inactive object root uses the whole-document pointer `""`.
+Only paths with delivered values are flagged. `hiddenFields` lists effectively
+hidden fields addressed by visibility-capable conditional rule effects, including
+declarative `ui:dynamicItems` rule patches and base-hidden Show targets whose rules
+have not shown them. Only `ui:widget`, `ui:options`, or whole-UI replacements
+establish visibility provenance; only whole-UI replacements cover descendants.
+Static hidden fields that no visibility-capable rule addresses, such as IDs and
+prefills, are sent without a hidden flag.
+`disabledFields` includes static and rule-set disabled fields. A field may occur
+in both lists. Rule order still determines effective state at submit time.
+
+Hidden or disabled null values are absent; visible optional null values remain
+null under the empty-value contract. Live answers are not cleared, so re-showing
+a field restores its value. Dynamic item UI receives actual answers and context.
+Traversal follows RJSF-resolved references, `allOf`, schema dependencies and
+additional-property metadata. Declared fields use their own UI; pattern-only
+keys use `uiSchema.additionalProperties`, matching RJSF. Wizard's flat traversal
+is step-scoped, so an inactive step root cannot remove another step's answers.
+
+Hidden and disabled fields remain exempt from validation and Wizard navigation
+requirements. Their values are sent as entered, even when invalid. The
+validation-only schema removes inactive names from `required`, array-form
+`dependencies` and `dependentRequired`, and exempts field constraints, including
+matching pattern constraints. Field-scoped custom and host errors are excluded.
+Active fields retain validation; the authored schema remains unchanged. Leaf
+validation schemas are not resolved as rendering schemas: conditional content
+constraints still distinguish an explicit empty string from a supplied value,
+and corrected pattern configurations resume validation without losing answers.
+Array-level `minItems`, `maxItems` and `uniqueItems` validate the live array.
+
+`beforeSubmit` receives all valued answers in the component's existing hook shape
+(after inactive nulls are removed). Its returned answers are delivered as returned:
+there is no second filter. Metadata is captured from field state at submit and
+restricted to returned paths; it never removes answers or re-adds keys removed
+by the host. After `beforeSubmit` reorders or removes array items, flags are
+restricted by path, not item identity, so an index can refer to a different item.
+
+Submit webhook envelopes carry `meta` as a fixed root key only when a flag list
+is non-empty. Otherwise their existing bytes and component-specific `formData`
+wrappers are unchanged. `body` cannot supply or override `meta`.
+`formDataFields` still selects top-level answers; metadata is restricted to that
+selection, using flat answer pointers for Wizard's selected webhooks.
+Change, focus, blur, stepChange and validationError events carry unfiltered
+answer snapshots and no metadata. Their existing `fieldValue` semantics remain.
+Standalone `FormEventHub` callers remain responsible for their own field state.
+
+`includeHiddenStepsInSubmit` retains its existing structured Wizard membership
+policy. Fields belonging to hidden steps are not flagged by this mechanism.
+The flat answer view retains its existing all-step contract. Use structured
+Wizard answers when whole-step exclusion is required.
+
 ## Basic usage
 
 ```tsx
@@ -75,6 +178,10 @@ EDF supplies its widgets and validator by default. Override the RJSF `widgets`,
 `customWidgets`, `validator` and commonly used RJSF types are exported from
 `extended-dynamic-forms`; no private subpath import is needed.
 
+Both `ExtendedForm` and `WizardForm` accept an omitted `formData` prop. It uses a
+stable empty initial value, and edited answers persist across host re-renders.
+Pass `formData` when your host needs to supply answers explicitly.
+
 ## Multi-step forms
 
 `WizardForm` detects steps from root properties beginning with `STEP_`. Define at
@@ -129,7 +236,7 @@ for the one-step payload contract and the configured-step boundary.
 
 Step visibility rules use `x-edf:stepRules`. Hidden steps are skipped in navigation
 and excluded from structured submissions unless `includeHiddenStepsInSubmit` is
-true; `flatFormData` retains the all-step context. `onStepChange` reports the
+true; `flatFormData` retains the all-step context after inactive-null omission. `onStepChange` reports the
 visible-step index; `onStepChangeDetailed` also includes the original index as
 `allStepsIndex`. The last visible step can submit, and final submission validates
 all visible steps, including an earlier step newly revealed by a later answer.
@@ -145,7 +252,32 @@ errors by default; hiding the error list does not bypass validation.
 
 `LayoutGridField` is included for step layouts. Configure `ui:field` as
 `LayoutGridField` and use `ui:layoutGrid` with Ant Design's 24-column spans and
-gutters. Custom fields and templates remain overridable.
+gutters. Grouped objects display their own title and description once before
+their members, using the registered templates. UI titles and descriptions
+override schema metadata; empty UI values hide that heading, and
+`ui:options.label: false` hides both. Custom fields and templates remain
+overridable.
+
+### Form headings and step descriptions
+
+Root `uiSchema['ui:options'].label` defaults to `true`. Set it to `false` to hide
+the form title and description together on one-step and multi-step forms; field
+labels are unaffected. An empty root `ui:title` or `ui:description` hides only
+that heading.
+
+The `WizardForm` prop `showStepDescription` defaults to `true`. Multi-step forms
+show one active-step description inside the form, above the fields, even when
+progress is hidden. Set it to `false` to hide that description. It is a component
+prop, not a persisted uiSchema option, so hosts such as Formstudio must pass it
+explicitly. One-step forms show no step description.
+
+```tsx
+<WizardForm
+  schema={schema}
+  uiSchema={{ 'ui:options': { label: false } }}
+  showStepDescription={false}
+/>
+```
 
 ## Conditional logic
 
@@ -178,6 +310,46 @@ UI rules belong in `uiSchema['x-edf:rules']`; schema rules belong in
 per-item JsonLogic. Conditional requiredness changes validation, not just a
 visual required marker.
 
+### Rule order
+
+Rules in each conditional engine run in ascending numeric `order`. Use a finite
+number; negative values and zero are valid. Equal orders retain their array
+order. Rules without `order` run **after every explicitly ordered rule**, keeping
+their own array order. Evaluation does not reorder the caller's array.
+
+Only matching rules apply effects. Effects run sequentially, so a later effect
+on the same property wins: hide followed by show reveals a field, and a later
+widget replacement replaces the earlier widget. Effects within one rule also
+retain their array order. A false condition does not apply an automatic inverse;
+authors that need an inverse must supply another rule.
+
+This contract applies separately to the UI, schema, and validation engines.
+Schema effects determine both rendered constraints and submission validation.
+The code-only `useConditionalValidation` hook preserves the same rule order;
+`createCustomValidate` then runs the selected validation callbacks in sequence.
+Callbacks that add errors accumulate them; an earlier error is not automatically
+removed unless a later callback explicitly changes it.
+
+`ExtendedForm` applies embedded schema and UI rules with this ordering.
+`WizardForm` applies it independently for each step, including navigation and
+final validation. A step's rule list is its local rules followed by inherited
+root rules, then sorted by `order`; root rules therefore follow local rules when
+their orders tie or both omit `order`. Rule paths are relative to the step.
+
+For example, these UI rules reveal `answer` as a textarea even though the hide
+rule appears last in the array:
+
+```json
+{
+  "x-edf:rules": [
+    { "name": "Show", "order": 20, "condition": true,
+      "effect": [{ "op": "replace", "path": "/answer/ui:widget", "value": "textarea" }] },
+    { "name": "Hide", "order": 10, "condition": true,
+      "effect": [{ "op": "replace", "path": "/answer/ui:widget", "value": "hidden" }] }
+  ]
+}
+```
+
 ## Widgets and options
 
 Select a registered widget using `ui:widget`. The same registered key can also
@@ -250,19 +422,47 @@ Choice presenter-specific Ant Design options use `choiceConfig.antd`, such as
 
 ### Empty answers
 
-The built-in Text widget emits `undefined` when cleared by default. Object
-properties are omitted when serialized to JSON, including properties in array
-items; callbacks may still contain undefined-valued own properties. Array rows
-are not deleted or compacted. An explicit `emptyValue`, including `""` or `null`,
-is an override and must satisfy the schema. Password, Textarea and other widget
-empty defaults are not globally changed. Custom fields/widgets control their
-own child-change behavior.
+The five text widgets follow the [null contract](#empty-values-null-contract)
+above. Widgets that still emit `undefined` omit those object properties during
+JSON serialization, including properties in array items; callbacks may retain
+undefined-valued own properties. Clearing an array row does not delete or compact it;
+hidden or disabled null items are omitted at submit and the array compacts, while
+valued hidden items are kept. See “Indices refer to the delivered array” in
+[Submitted data: hidden and disabled fields](#submitted-data-hidden-and-disabled-fields).
+Explicit `emptyValue` overrides retain their configured value and validation
+behavior, including optional-null acceptance. Custom fields/widgets control
+their own child-change behavior.
 
 Stored/default answers are not rewritten on load. Turning off interaction
 feedback does not disable Submit or Wizard Next validation. Change callbacks
 can contain incomplete or invalid drafts; only accepted submissions should be
 stored as completed responses.
 
+### Conditional validation feedback
+
+`ExtendedForm` and every `WizardForm` step fold an AJV `if` error for a failed
+`then` or `else` branch when a specific, non-wrapper error has the same property
+path. Wrappers remain visible when no specific error exists at their path,
+even when several conditional rules fail there. Field feedback and the error
+list use the same transformed errors; schemas and submitted answers are unchanged.
+
+Both components accept `transformErrors(errors, uiSchema)`. EDF folds first,
+then calls the host transform. Wizard navigation and final validation use the
+same order as the step renderer. Hosts should not depend on redundant wrapper
+errors reaching their callback.
+
+### Configuration errors and email feedback
+
+Configuration failures carry `name: 'edf:configuration'`, including errors from
+the exported `nullContractValidator`. This marker is the supported way for hosts
+to recognise configuration failures. Host `transformErrors` callbacks should
+preserve `name` when copying or replacing error objects so Wizard retains its
+configuration-error feedback path.
+
+Email fields in `ExtendedForm` and `WizardForm` now honour `ui:hideError` for
+schema and custom validation messages. Widget-local blur feedback when no
+schema or custom errors exist is unchanged.
+
 ### Date and time answers
 
 | Widget/schema | Accepted answer |
@@ -309,6 +509,62 @@ Custom widgets can import `useFieldEventHandlers` from the root package alongsid
 other event exports. Call the RJSF `onChange` to update the answer and the field
 event handler to participate in EDF events.
 
+Both components send webhooks through `FormEventHub`, using a single JSON envelope
+with `eventType`, `timestamp`, `source` and `formData`. Subscriptions support
+`focus`, `blur`, `change`, `submit`, `validationError` and wizard `stepChange`.
+Field events also carry `fieldId`, `fieldValue` and `fieldPath`; step events carry
+`fromStep` and `toStep`; validation events carry `errors`.
+
+```tsx
+import type { JsonValue, WebhookConfig } from 'extended-dynamic-forms';
+
+const metadata: Record<string, JsonValue> = {
+  tenant: 'operations',
+  correlation: null,
+  label: '{{literal text}}',
+};
+const webhooks: WebhookConfig[] = [{
+  url: 'https://example.com/events?channel=forms#receiver',
+  events: ['change', 'submit'],
+  body: metadata,
+  query: [{ key: 'tag', value: 'customer care' }, { key: 'tag', value: '' }],
+  formDataFields: ['contact', 'consent'],
+}];
+```
+
+- `body` adds fixed extra root properties once. Its recursive `JsonValue` type
+  accepts JSON primitives, objects, arrays and null. There is no templating or
+  script execution: `{{...}}` remains literal text. Reserved keys are always
+  ignored, even when absent from the event: `eventType`, `timestamp`, `source`,
+  `formData`, `fieldId`, `fieldValue`, `fieldPath`, `fromStep`, `toStep`, `errors` and `meta`.
+- `query` appends URL-encoded string pairs in order. Existing query values,
+  duplicate keys and empty values are retained; the fragment remains last.
+  An absent or empty list leaves the URL byte-for-byte unchanged.
+- `formDataFields` selects literal own top-level answer keys for this webhook only.
+  It does not interpret paths, wildcards or renames. An absent list keeps existing
+  full-data delivery; an empty list sends `{}`. Missing keys stay absent. Selected
+  JSON values retain their complete nested structure and nulls. Null or missing
+  answer data stays as it is. Submit selection uses ExtendedForm's inner answers
+  and WizardForm's accepted flat answer view, not their compatibility wrappers.
+  Other events select from their answer data. Unselected payloads and callbacks
+  retain their existing component-specific shapes.
+
+Native `FormEventHub` callers may supply `handleAfterSubmit(data, { formData: answers })`
+when their canonical submit data is wrapped. Omitting the second argument selects
+from `data` as before; an explicit null or undefined snapshot stays null or missing.
+The snapshot travels with that event through deferred delivery and retries.
+
+These options apply to every subscribed event without changing methods, headers,
+debouncing, retries, timeouts or subscriptions. With all three absent, the URL and
+serialized request body remain byte-identical to existing delivery. They do not
+mutate the shared event, another webhook's payload or host/lifecycle callback data.
+**Answer selection is not a redaction control:** it filters only `formData`, not
+`fieldValue`, `errors`, query values or authored body properties. Hosts must apply
+their own disclosure policy before configuring a destination.
+
+These EDF options do not interpret Formstudio's legacy `request_body` or
+`form_data_fields` storage.
+
 ### RJSF 6.11 native integration in 0.5.0
 
 For native hosts that register EDF's `TelephoneWidget` on their own RJSF 6.11

package/dist/WizardForm.d.ts

@@ -1,4 +1,5 @@
 import { WebhookConfig } from './types';
+import { ErrorTransformer } from '@rjsf/utils';
 
 export interface WizardStep {
     id: string;
@@ -35,6 +36,7 @@ export interface WizardFormProps {
     submitButtonText?: string;
     liveValidate?: boolean;
     showErrorList?: boolean;
+    transformErrors?: ErrorTransformer;
     onWebhookStart?: (webhook: WebhookConfig, event: any) => void;
     onWebhookComplete?: (webhook: WebhookConfig, event: any, response: any) => void;
     onWebhookError?: (webhook: WebhookConfig, event: any, error: Error) => void;
@@ -44,4 +46,4 @@ export interface WizardFormProps {
     enableDynamicBinding?: boolean;
     includeHiddenStepsInSubmit?: boolean;
 }
-export declare function WizardForm({ schema, uiSchema, webhooks, formData: initialFormData, onSubmit, onStepChange, onFieldFocus, onFieldBlur, onFieldChange, onLiveChange, showProgressBar, showStepDescription, submitButtonText, liveValidate, showErrorList, onWebhookStart, onWebhookComplete, onWebhookError, widgets, fields, templates, enableDynamicBinding, onStepChangeDetailed, onStepAutoAdvance, includeHiddenStepsInSubmit, }: WizardFormProps): import("react/jsx-runtime").JSX.Element;
+export declare function WizardForm({ schema, uiSchema, webhooks, formData: initialFormData, onSubmit, onStepChange, onFieldFocus, onFieldBlur, onFieldChange, onLiveChange, showProgressBar, showStepDescription, submitButtonText, liveValidate, showErrorList, transformErrors, onWebhookStart, onWebhookComplete, onWebhookError, widgets, fields, templates, enableDynamicBinding, onStepChangeDetailed, onStepAutoAdvance, includeHiddenStepsInSubmit, }: WizardFormProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/RJSF611ErrorStateAdapter.d.ts

@@ -1,11 +1,16 @@
 import { default as React } from 'react';
-import { FormProps } from '@rjsf/core';
+import { default as Form, FormProps } from '@rjsf/core';
 
 type ErrorOwner = {
     setError: (id: string, message: string) => void;
     remove: (id: string) => void;
 };
 export declare const useRJSF611WidgetErrorOwner: () => ErrorOwner | undefined;
+/** Internal Wizard snapshot; ordinary validation belongs in RJSF state, not extraErrors. */
+export declare const WizardValidationContext: React.Context<{
+    validation: Pick<Form["state"], "errors" | "errorSchema">;
+    reveal: boolean;
+} | undefined>;
 export interface RJSF611ErrorStateAdapterProps {
     children: React.ReactElement<FormProps>;
     /** Same constraints as the child's customValidate, without lifecycle notifications. */

package/dist/components/index.d.ts

@@ -7,6 +7,7 @@ import { ArrayFieldTemplate, ArrayFieldItemTemplate } from './arrays';
 import { WizardObjectFieldTemplate, WizardSectionTemplate } from '../layouts/wizard';
 import { SubmitButton } from './templates/SubmitButton';
 import { FieldTemplate } from './templates/FieldTemplate';
+import { FieldErrorTemplate } from './templates/FieldErrorTemplate';
 import { FieldProps } from '@rjsf/utils';
 
 export declare const customFields: {
@@ -17,6 +18,7 @@ export declare const customFields: {
 };
 export declare const customTemplates: {
     FieldTemplate: React.FC<import('@rjsf/utils').FieldTemplateProps>;
+    FieldErrorTemplate: typeof FieldErrorTemplate;
     ObjectFieldTemplate: React.FC<import('@rjsf/utils').ObjectFieldTemplateProps>;
     ArrayFieldTemplate: (props: import('@rjsf/utils').ArrayFieldTemplateProps) => import("react/jsx-runtime").JSX.Element;
     ArrayFieldItemTemplate: (props: import('@rjsf/utils').ArrayFieldItemTemplateProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/templates/FieldErrorTemplate.d.ts

@@ -0,0 +1,3 @@
+import { FieldErrorProps } from '@rjsf/utils';
+
+export declare function FieldErrorTemplate({ errors, fieldPathId }: FieldErrorProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/conditionals/v2/utils/dynamicArrayItems.d.ts

@@ -52,6 +52,7 @@ export type DynamicItemsConfig = {
     base?: UiSchema;
     rules: DynamicItemsRule[];
 };
+export declare const dynamicItemsRulePatches: WeakMap<ArrayItemsFunction, Partial<UiSchema>[]>;
 /**
  * Compile a declarative JSON config into an ArrayItemsFunction
  * - Supports single-rule shorthand and multi-rule configs

package/dist/events/FormEventHub.d.ts

@@ -1,4 +1,4 @@
-import { FormEventHandlers, FieldEventHandlers, WebhookConfig } from '../types';
+import { FormEventHandlers, FieldEventHandlers, WebhookConfig, SubmissionMeta } from '../types';
 
 export declare class FormEventHub {
     private formHandlers;
@@ -20,7 +20,10 @@ export declare class FormEventHub {
         onWebhookError?: (webhook: WebhookConfig, event: any, error: Error) => void;
     }): void;
     handleBeforeSubmit(data: any): Promise<any>;
-    handleAfterSubmit(data: any): Promise<void>;
+    handleAfterSubmit(data: unknown, answerSnapshot?: {
+        formData: unknown;
+        meta?: SubmissionMeta;
+    }, meta?: SubmissionMeta, fullAnswers?: unknown): Promise<void>;
     handleBeforeValidation(data: any): Promise<any>;
     handleAfterValidation(validationErrors: any, formData: any): Promise<void>;
     handleStepChange(fromStep: number, toStep: number, formData: any): Promise<void>;

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export * from './hooks';
 export type { FormProps, IChangeEvent } from '@rjsf/core';
 export type { RJSFSchema, UiSchema, WidgetProps, FieldProps, ArrayFieldTemplateProps, ObjectFieldTemplateProps, FieldTemplateProps, ErrorSchema, RJSFValidationError, } from '@rjsf/utils';
 export { default as validator } from '@rjsf/validator-ajv8';
+export { nullContractValidator } from './utils/nullContractValidator';
 export { ExtendedForm } from './ExtendedForm';
 export { WizardForm } from './WizardForm';
 export type { WizardFormProps, WizardStep } from './WizardForm';