extended-dynamic-forms 0.4.0 → 0.4.1

package/README.md

@@ -1,1296 +1,320 @@
 # Extended Dynamic Forms
 
-## Declarative Configuration (JSON-only)
-
-Conditional logic is configured with pure JSON via `x-edf:rules` in your `schema` and `uiSchema`. Function-based conditions and external hooks are not required and should not be used in app code.
-
-## Project Status
-
-**Important Notes:**
-- Source development uses the pinned RJSF packages in `yarn.lock`; no sibling checkout is needed.
-- Source package version is `0.4.0`; a checkout or local tarball is not proof of registry publication.
-- JSON logic conditions don't work with vanilla JavaScript builds
-- Array drag-and-drop is not implemented
-- Automated coverage includes logic/snapshot suites and real jsdom wizard component regressions.
-- JSON Patch implementation supports add/remove/replace only (not move/copy/test)
-
-## Overview
-
-Extended Dynamic Forms is an extension library for React JSON Schema Form (RJSF) v6 that adds:
-
-- **Declarative conditionals** with O(N) performance (rules + dynamic arrays)
-- **Multi-step wizard forms** with automatic step detection
-- **Central event orchestration** with webhook support
-- **25+ Ant Design components** for professional UI
-- **TypeScript-first** development with full type safety
-
-### Ant Design Prop Pass-through
-
-All custom widgets built on Ant Design components forward their props via `ui:options`. For example, Rate, Slider, DatePicker, Input, InputNumber, ColorPicker, and TimePicker can be configured using the same prop names from AntD. In addition, you can customize the containing `Form.Item` using `ui:options.formItem`. See docs/custom-widgets-configuration.md for details and examples.
-
-- DatePicker notes:
-  - JSON-only flags: `disablePastDates`, `disableFutureDates`, `disableWeekends` (builds `disabledDate` internally)
-  - Range support: set `ui:options.range: true` to render AntD `RangePicker` (see examples below)
-
-### Text Input clear (BUGS-S0-R020, 0.4.0)
-
-This correction, including fixes added after the earlier !6 artifact, is part of
-0.4.0 release preparation. Publication and Formstudio adoption remain separate gates.
-
-Clearing the built-in `text` / `TextWidget` now emits `undefined` by default.
-Object properties, including properties inside array items, are omitted when
-serialized as JSON. Undefined-valued own properties may still exist in callbacks.
-Required fields and invalid nonempty formats remain invalid; clearing an optional
-formatted Text Input no longer creates an invalid empty string.
-
-Defined `emptyValue` options remain explicit overrides, including `""`, `null`
-and other sentinels. They must satisfy the consumer's schema: an explicit empty
-string still fails an email format. Wizard blank-string normalization is retained
-unless a positive string `minLength`, a valid explicit `maxLength` (including
-zero), or an explicit string `pattern` (including the empty regex) constrains
-that property. See [Wizard explicit string minimums](#wizard-explicit-string-minimums),
-[Wizard supplied pattern strings](#wizard-supplied-pattern-strings), and
-[Wizard explicit string maximums](#wizard-explicit-string-maximums).
-An unconstrained widget's legacy empty string is not a promise of a
-final Wizard empty-string submission.
-
-Stored/default answers are not rewritten on load. Array positions and row
-identity are preserved; this is not a primitive-array deletion or compaction
-policy. The array-item integration forwards built-in TextWidget property clears
-as leaf paths, so batched sibling updates use current form state rather than a
-render-time object snapshot. It delegates host `ArraySchemaField`/`SchemaField`
-components and retains array row keys. Consumer-supplied fields/widgets remain
-authoritative; an overridden `ArrayField` owns its child-change policy.
-Password, Textarea and other widget empty defaults are unchanged.
-Traversal uses RJSF's effective schema-type resolver after reference resolution,
-including supported nullable array/object containers. Untouched explicit nulls
-are preserved; this is not global null normalization.
-Field authority is resolved before TextWidget eligibility at the leaf and each
-ancestor: normalized UI/global field options take precedence, then registered
-schema `$id`, then the type's registry field. Unknown UI field names fall through
-as in RJSF. A custom field selected by schema ID retains the same ordinary array
-handling as that field selected by `ui:field`; it does not inherit TextWidget's
-omission policy.
-Host item/schema renderers that replace TextWidget retain ordinary array
-undefined-to-null handling. Delegating renderers retain omission for the actual
-TextWidget they render, including public relative-path changes and batched host
-controls. The adapter checks committed field-scoped rendering and the public
-callback's target path, not widget IDs or schema metadata alone; replacement,
-unmount and row moves withdraw obsolete rendering authority.
-
-### 0.4.0 adoption and migration
-
-`0.4.0` intentionally changes the Date, Time, DateTime and calendar Date Range
-serialization contracts described below. Treat this pre-1.0 minor release as a
-contract boundary, not a transparent patch to `0.3.13`. Consumers using `^0.3.x`
-do not receive `0.4.x` automatically.
-
-External/native integrators must explicitly adopt `0.4.x`, update their dependency
-lockfile, and check callback handlers, schema validation and submission storage
-against the relevant contract. Date/Time schemas without their respective
-`format` retain their documented native formatted-output exception. Calendar
-ranges use ISO dates even with plain string items; explicit `showTime` / `withTime`
-ranges retain their time-bearing contract. DateTime uses the UTC-instant contract
-for both Ant Design and native inputs, not a configurable floating-time mode.
-
-Do not automatically rewrite persisted or in-progress responses during an
-upgrade. Restore supported values without load-time change callbacks; legacy
-values that fail the applicable schema/instant contract require respondent
-re-entry rather than a guessed timezone or bulk normalization. Pending invalid
-edit callbacks are not accepted submissions. Existing non-production Formstudio
-forms need no migration infrastructure; this does not authorize changing external
-stored data.
-
-Formstudio adoption is a separate step **after published registry proof** of the
-new SDK. Pair the reviewed producer changes with the exact released dependency
-and lockfile, then verify the resolved package in the consumer. Local packed
-integration alone does not establish publication, authenticated hosted/managed
-behavior or deployed adoption. Never replace registry `0.3.13` with these bytes.
-
-Release preparation covers the declared ESM and browser UMD bundles, CSS and
-ESNext/Bundler declarations. The existing CommonJS/NodeNext packaging limitations
-and the separate vanilla build's missing entry are not repaired by this release.
-
-Only the browser UMD output resolves `process.env.NODE_ENV` to production at build
-time; script-tag hosts do not need a Node `process` shim. ESM retains its
-environment checks so consumers control development diagnostics and production
-behavior. The normal UMD peer globals remain required: `React`, `ReactDOM`,
-`React.jsxRuntime`, `antd` and `dayjs`.
-
-### Single Date Picker values (ON-41, 0.4.0)
-
-For `ui:widget: "date"` with a scalar `schema.format: "date"`, selection emits
-`YYYY-MM-DD` to form data and field-change events. `ui:options.format` controls
-display only: `DD/MM/YYYY` displays `23/10/2026` but submits `2026-10-23`.
-The value is a calendar day, not a UTC timestamp; no timezone conversion is used.
-Clearing still emits the configured `emptyValue`.
-
-This intentionally corrects the previous, schema-invalid formatted output in
-`0.4.0`; it does not replace published `0.3.13`.
-Native string schemas without `format: "date"` retain their formatted output.
-Existing ISO dates and legacy values matching the configured string format are
-readable, including day-first dates. Loading does not rewrite stored answers:
-a legacy non-ISO answer still fails a date schema until the respondent selects
-a valid date. Impossible ISO dates are not rolled into a different calendar day.
-Consumers upgrading date-schema forms must expect canonical values in callbacks
-and submissions; do not rewrite saved/in-progress responses as an upgrade side effect.
-
-This change covers the single Date Picker only, not Time, DateTime or Date Range.
-
-### Time Picker values (BUGS-S0-R272, 0.4.0)
-
-For `ui:widget: "time"` with `schema.format: "time"`, selection emits
-`HH:mm:ss` wall-clock values to form data, callbacks and submissions.
-`ui:options.format` controls display: `hh:mm A` displays `02:35 PM` while
-the value is `14:35:00`. No `Z`, offset or timezone conversion is added.
-Clearing retains the configured `emptyValue`.
-
-Canonical values and legacy strings matching the configured format are parsed
-strictly. Invalid values are not displayed as `Invalid Date` or rolled into a
-different time. Reading does not call `onChange` or rewrite saved answers:
-schema-invalid legacy values still require reselection before valid submission.
-The readonly native input shows the same clock time.
-
-Native string schemas without `format: "time"` retain configured-format output
-and prefer that format when reading ambiguous values. This approved time-schema
-contract correction requires explicit `0.4.x` consumer adoption; do not replace
-registry `0.3.13` or migrate saved/in-progress responses implicitly.
-It does not change DateTime or Date Range behavior.
-
-### DateTime values (BUGS-S0-R273, 0.4.0)
-
-DateTime (`datetime`, `datetime-local`, `DateTimeWidget`, or the default
-`format: "date-time"` widget) captures and displays the respondent's **browser-local
-wall clock**. Every newly accepted selection emits a UTC ISO timestamp with `Z`,
-for example `2024-11-03T05:30:00.000Z`. `ui:options.format` controls presentation
-only. Ant Design, native `useNativeInput`, readonly display, plain forms and
-wizard validation share this instant contract. There is no form timezone setting.
-
-The widget rejects a nonexistent local time during a daylight-saving gap. For a
-repeated local time it requires an explicit **First occurrence** or **Second
-occurrence**, labelled with the corresponding UTC offset, before accepting an
-instant. A restored UTC/offset-bearing instant already identifies its occurrence;
-loading it does not call `onChange`, normalize storage or ask the respondent to
-choose again. Different browser timezones may display different calendar dates
-for the same instant.
-
-Valid restored fractional seconds may exceed three digits (for example `.1230Z`
-or `.123456789Z`). The original string is preserved on load and unchanged
-submission; millisecond-resolution controls do not rewrite stored precision.
-New respondent edits emit the standard ISO millisecond precision shown above.
-
-Invalid or zone-less saved strings require re-entry; their timezone is never
-guessed. Pending/invalid edits invalidate the previous form value and block submit
-and wizard progression, even on optional fields. During such an edit, change
-callbacks can contain the non-instant `Invalid date-time` marker and validation
-errors; do not persist it as an accepted answer. Only a valid, completed selection
-emits an instant. Clearing emits `undefined` (omitted in JSON), regardless of old
-DateTime `emptyValue` options; required clear remains invalid. Other widgets'
-empty sentinels and Date/Time/Range semantics are unchanged.
-Wizard `onLiveChange` publishes the same deletion-aware flat snapshot used
-internally: clearing removes the answer while retaining sibling and other-step
-data. Validation also covers positional tuple entries and additional items using
-their corresponding schema references and item UI schema, including explicit
-native DateTime widgets whose string schema has no `format`.
-The supported `ui:field` aliases obey the same contract and forward widget errors.
-For `oneOf`/`anyOf`, validation follows RJSF's active schema and corresponding
-branch UI, retaining explicit choices when branches match equally. Inactive text
-branches are not treated as DateTime. Wizard final submission validates every
-visible step with its own UI and retained branch choice, including earlier steps
-newly revealed by a final-step answer.
-Returning to a wizard step restores its actual rendered selector and nested/ref
-branch UI, not only a validation hint. Navigation preserves answers and emits no
-answer-change callback merely to restore a choice. Choices are scoped by step and
-nested branch; authored discriminators still determine matching when data differs.
-In arrays, choices follow RJSF's stable row identities through removal and both
-reorder directions, including equal-valued and nested rows. Removed-row choices
-are retired; added rows use normal matching/defaults. Answer/error paths remain
-positional, with no IDs added to responses. Registry and per-field
-`ArrayFieldTemplate` / `ArrayFieldItemTemplate` overrides retain their rendering
-and public row actions; identity tracking neither replays nor replaces callbacks.
-
-`disablePastDates`, `disableFutureDates`, `disableWeekends` and explicit date bounds
-compare browser-local calendar labels, not the UTC instant of a picker container.
-Picker selection, typed/native input and restored-answer validation agree.
-An explicit `disabledDate` callback takes precedence over convenience flags;
-bounds still apply. Callback calendar/clock fields are preserved, using a
-fixed-offset carrier for a skipped local date or clock rather than shifting it.
-
-This is the approved **clean DateTime cutover**, not an opt-in or floating-time
-mode. Existing non-production Formstudio forms need no migration infrastructure.
-External consumers must explicitly adopt `0.4.x` and account for the changed
-DateTime callbacks/submissions; never replace published `0.3.13` with these
-contents or rewrite external stored answers on load.
-
-### Calendar Date Range values (BUGS-S0-R274, 0.4.0)
-
-`ui:widget: "date"` with `ui:options.range: true` reuses Ant Design's
-`RangePicker`, including RJSF array dispatch. Calendar endpoints are always
-`[YYYY-MM-DD, YYYY-MM-DD]`, even for native SDK schemas whose items are plain
-strings. `format` controls display/input only. Dates are calendar days, not
-instants: there is no UTC conversion or timezone shifting. Readonly mode displays
-both endpoints using native date inputs.
-
-Impossible dates, reversed pairs and incomplete pairs are rejected in plain forms
-and wizard progression. Invalid typed drafts invalidate the answer rather than
-submitting a previous valid pair; do not persist change callbacks as accepted
-submissions without validation. Typed/restored dates also obey picker constraints.
-Loading valid ISO data does not rewrite it or emit a change callback.
-Character-by-character endpoint edits retain their text and caret through parent
-updates while each partial draft still reaches change callbacks and validation.
-A genuine external answer replacement replaces the draft without replaying it.
-Explicit Clear discards both endpoint texts, including a partial draft entered
-into an already-empty range, and emits `[]` without replaying the discarded draft.
-Fresh typing starts from blank inputs; optional `[]` remains valid and required
-`[]` remains invalid.
-The same guards apply to the registered `date` / `DateWidget` field aliases
-(`ui:field` takes precedence over `ui:widget`) and the actually selected referenced
-`oneOf` / `anyOf` branch. Inactive text branches remain text, including through
-Wizard Back/final validation and stable array-row changes.
-
-Past/future restrictions compare calendar-day keys with the respondent's **local
-today**, not UTC-midnight containers with local-midnight instants. Picker cells,
-typed/restored validation and wizard progression use the same internal calendar
-constraint adapter as DateTime. Native min/max bounds retain their displayed
-calendar days; an explicit `disabledDate` callback still takes precedence over
-JSON flags, independently of those bounds. Its date and `info.from` preserve
-calendar and clock fields in local mode where representable; a locally skipped
-day or clock uses a separate fixed-offset carrier without mutating the picker's
-input. Range-only options and explicit with-time behavior remain unchanged.
-This does not repair the separate pre-existing full-form UI-option normalization
-of native Dayjs instances.
-
-Calendar clear emits `[]`: optional answers may submit it; required answers may
-not. An optional array schema must permit zero or two items (for example,
-`minItems: 0`, `maxItems: 2`, `not: { minItems: 1, maxItems: 1 }`).
-Explicit `allowEmpty: [true, false]` preserves `["", "YYYY-MM-DD"]`; only the
-allowed endpoint may be empty, and populated endpoints remain ISO. Native schema
-constraints still apply: `items.format: "date"` does not permit `""`; use matching
-tuple item schemas if an empty endpoint is intentional.
-
-Explicit `showTime` / `withTime` ranges remain outside this calendar cutover:
-they retain their existing formatted string pair and time information. No UTC
-DateTime policy is applied to them. Single Date, Time and DateTime are unchanged.
-
-This explicitly approved non-production cutover supersedes the old configured
-string calendar output; it is not a migration or compatibility mode. External
-native consumers must explicitly adopt `0.4.x` with this contract. Do not replace
-published `0.3.13`. Formstudio's reviewed producer change must be paired with
-the new SDK only after registry publication is proved; an older installed package
-or a local packed fixture is not proof of released consumer adoption.
+Extended Dynamic Forms (EDF) extends React JSON Schema Form (RJSF) v6 with
+Ant Design widgets, JSON-configured conditional logic, multi-step forms and
+field events. Use it in a React application with JSON Schema for data constraints
+and `uiSchema` for presentation.
 
 ## Installation
 
-For this source checkout, use the maintained Yarn lockfile. The older npm lockfile
-still contains local RJSF references and is not a reproducible install for this tree.
-
 ```bash
-yarn install --frozen-lockfile
-npm run build
+npm install extended-dynamic-forms
 ```
 
-For local consumer verification, run `npm pack --ignore-scripts` after building and
-install the resulting `extended-dynamic-forms-0.4.0.tgz` in an isolated consumer.
-The root version fields in the legacy npm lockfile match `0.4.0`; its stale
-dependency graph is deliberately unchanged and must not be used for this install.
-Package preparation does not authorize publication. See the adoption boundary
-above and the existing packaging limitations below.
-
-## Testing
+Install compatible peer dependencies if your application does not already have them:
 
-Vitest defaults to the **Node** environment for logic and serialized-output tests.
-`tests/integration/WizardForm.regression.test.tsx` opts into **jsdom** and mounts
-the real wizard, renderer, widgets, validator and Ant Design components.
-
-- Full suite: `npm test -- --run`
-- Wizard and step-rule regressions: `npm test -- --run tests/integration/WizardForm.regression.test.tsx tests/logic/conditionals/stepRules.test.ts`
-- Date selection, display/value round-trip and plain/wizard validation: `npm test -- --run tests/integration/DatePicker.regression.test.tsx`
-- Time selection, canonical/native values, strict parsing and required plain/wizard submission: `npm test -- --run tests/integration/TimePicker.regression.test.tsx`
-- Logic-only focus: `npm test -- --run tests/logic`
-- Real Chromium Text status/color and host-CSS regressions: `npm run test:browser`. This opt-in suite builds and packs the current SDK, builds an isolated public consumer and asserts rendered colors, token/neutral transitions, authored plain/addon-affix backgrounds and submission behavior; it is separate from the default Node/jsdom suite.
-
-The browser suite needs Chromium/Chrome (`CHROME_BIN` overrides discovery), `npm` and `tar`.
-It creates a fresh profile and consumer under `TMPDIR` and closes/removes only its own runtime.
-Set `EDF_BROWSER_ARTIFACT_DIR` to retain genuine PNG, DOM/raw observations and package/resource identities outside the temporary runtime.
-
-The plain-form array comparisons use `noHtml5Validate` so JSON Schema, rather
-than native HTML `required` attributes on array-item inputs, determines whether
-empty strings are valid.
-
-## Core Architecture
-
-### Declarative Conditionals (JSON-only)
-
-Embed rules directly inside your configs. EDF evaluates JsonLogic `condition` and applies JSON Patch `effect` internally. No hooks, functions, or classes in user code.
-
-- UI rules → `uiSchema['x-edf:rules']`
-- Schema rules → `schema['x-edf:rules']`
-
-Example (UI rules):
-```json
-{
-  "x-edf:rules": [
-    {
-      "name": "Show license number when has license",
-      "condition": { "==": [{ "var": "hasDriversLicense" }, true] },
-      "effect": [{ "op": "remove", "path": "/licenseNumber/ui:widget" }]
-    }
-  ]
-}
-```
-
-Example (Schema rules):
-```json
-{
-  "x-edf:rules": [
-    {
-      "name": "Add premium fields",
-      "condition": { "==": [{ "var": "accountType" }, "premium"] },
-      "effect": [
-        { "op": "add", "path": "/properties/premiumFeatures", "value": { "type": "object" } }
-      ]
-    }
-  ]
-}
+```bash
+npm install 'react@^18.0.0' 'react-dom@^18.0.0' 'antd@^5.24.0' 'dayjs@^1.11.13'
 ```
 
-### Dynamic Arrays with O(N) Performance
-
-Use declarative `ui:dynamicItems` with per-item JsonLogic. No functions:
-
-```json
-{
-  "directors": {
-    "items": {
-      "ui:dynamicItems": {
-        "base": { "shareholdingPercentage": { "ui:widget": "hidden" } },
-        "rules": [
-          {
-            "condition": { "===": [{ "var": "hasShareholding" }, true] },
-            "ui": { "shareholdingPercentage": { "ui:widget": "updown" } },
-            "otherwise": { "shareholdingPercentage": { "ui:widget": "hidden" } }
-          }
-        ]
-      }
-    }
-  }
-}
-```
+React and React DOM 19 are also supported by the peer ranges. Keep their major
+versions aligned. RJSF and the AJV validator are included in the library bundle;
+you do not need a sibling RJSF checkout.
 
-## Multi-Step Wizard Forms
+Use ESM imports and include the exported stylesheet. TypeScript declarations are
+provided; use an ESNext/Bundler-compatible module configuration.
 
-Create wizard forms with automatic step detection:
+## Features
 
-```typescript
-import { WizardForm } from 'extended-dynamic-forms';
+- Single-page forms and wizards with step visibility, navigation and validation.
+- Declarative JsonLogic conditions and JSON Patch effects in JSON configuration.
+- Ant Design text, choice, numeric, date/time, file and display widgets.
+- Per-field options, custom widgets, fields, templates and grid layouts.
+- Field focus, blur and change events, submission hooks and webhook configuration.
 
-<WizardForm
-  schema={wizardSchema}
-  uiSchema={uiSchema}
-  formData={formData}
-  onStepChange={(fromStep, toStep) => {
-    console.log(`Step ${fromStep} → ${toStep}`);
-  }}
-/>
-```
+## Basic usage
 
-**Important:** Wizard forms flatten nested step data. Use flat paths in conditions:
+```tsx
+import { useState } from 'react';
+import { ExtendedForm, type RJSFSchema, type UiSchema } from 'extended-dynamic-forms';
+import 'extended-dynamic-forms/dist/style.css';
 
-```typescript
-// Schema uses STEP_ prefixes
-const schema = {
+const schema: RJSFSchema = {
+  type: 'object',
+  required: ['name'],
   properties: {
-    STEP_PERSONAL: {
-      properties: {
-        hasDriversLicense: { type: 'boolean' }
-      }
-    }
-  }
+    name: { type: 'string', title: 'Name', minLength: 1 },
+    email: { type: 'string', title: 'Email', format: 'email' },
+  },
 };
 
-// Conditions refer to flattened form data (no STEP_ prefix)
-// Example rule (in uiSchema.x-edf:rules): { "==": [{ "var": "hasDriversLicense" }, true] }
-```
-
-Note on wizard detection:
-- Wizard mode activates only when the root schema contains two or more properties whose keys start with `STEP_`.
-- With a single `STEP_…` property, the form renders as a single-page form (no progress/navigation UI).
-- To display steps UI, define at least two step objects (e.g., `STEP_PERSONAL`, `STEP_REVIEW`).
-
-### Completion and array-value guarantees
-
-- The final visible step can submit without a following step. Submission
-  validates every visible step snapshot against its step schema before calling
-  `onSubmit`; a newly revealed invalid earlier step is activated for completion.
-- A trailing step skipped by `x-edf:stepRules` does not disable completion.
-  Hidden steps are excluded from structured `formData` unless
-  `includeHiddenStepsInSubmit` is enabled; `flatFormData` retains its existing
-  all-step value context.
-- A root skip rule on a single-page form renders the no-visible-steps state,
-  not inputs with a submit action that cannot complete.
-- Public `WizardLayout`/`StepNavigation` omit hidden steps from navigation and
-  progress while retaining original step indices in `onStepChange`.
-- Supplied step data is available on the first render. Empty-string and whitespace
-  array entries, nested arrays and array positions survive editing, step
-  navigation, `onLiveChange`, and both structured and flat submission data.
-- Flat initial answers are assigned to their schema-owned step snapshots, so
-  untouched answers appear in structured submission as well as `flatFormData`.
-  Supplied flat values reach validation unchanged, including composed constraints.
-  Explicit nested `STEP_*` snapshots retain precedence; editing or clearing an
-  answer does not restore its initial value.
-- For nested snapshots and respondent edits, blank-string normalization outside
-  arrays remains in place when no string `pattern`, positive `minLength`, or
-  valid explicit `maxLength` applies. Explicit constraints follow the contracts below.
-  Array contents are not compacted or normalized by the wizard.
-
-### Wizard explicit string minimums
-
-0.4.0 R139 correction: a string property with an explicit positive
-`minLength` retains supplied empty and whitespace-only strings for validation.
-An optional absent property remains optional, but an explicit `""` cannot bypass
-the minimum by being removed from the step snapshot. This applies on initial
-load, editing/clearing, Next, and final submission.
-
-Length counts the original characters, not digits or trimmed text. Nonempty
-Phone values and sibling callback data are not normalized by this correction.
-Blank normalization without a pattern, positive minimum, or valid explicit maximum,
-date empty defaults, and array positions remain unchanged.
-
-This correction is included in 0.4.0, not registry `0.3.13`.
-Publication and Formstudio adoption remain separate gates.
-
-### Wizard supplied pattern strings
-
-0.4.0 R138 correction: a string property with an explicit string `pattern`
-retains every supplied string unchanged for AJV validation, including `""` and
-whitespace-only strings. Nonmatching blanks block Next and final submission;
-matching blanks remain intact in live changes and both structured and flat
-submission data. This applies to restored values and editing/clearing, not only
-Phone fields. Native `pattern: ""` is an explicit regex matching all strings;
-an omitted pattern is distinct.
-
-An actually absent optional property remains absent. This does not add
-requiredness or a minimum, trim values, change widget clear defaults, or alter
-the positive-minimum contract above. A widget emitting absence is not treated
-as supplying an empty string.
-
-This correction is included in 0.4.0, not registry `0.3.13`.
-Publication and Formstudio adoption remain separate gates.
-
-### Wizard explicit string maximums
-
-0.4.0 R140 correction: a string property with a valid explicit nonnegative
-integer `maxLength` retains supplied strings unchanged for AJV validation,
-including empty and whitespace-only values. Eleven spaces under `maxLength: 10`
-and one space under `maxLength: 0` block Next and final submission, just as in a
-plain form. Permitted blanks and clears remain intact in live changes and both
-structured and flat submission data, including after back navigation.
-
-This deliberately changes required-plus-maximum blanks: JSON Schema `required`
-checks presence, so a supplied matching `""` or whitespace value is present
-rather than normalized to absence. Plain schema validation already accepts it.
-A genuinely missing required property still rejects. Use a positive `minLength`
-to reject empty strings, or an appropriate `pattern` to reject whitespace;
-neither content rule is added implicitly. Native HTML validation is separate.
-
-An absent optional property stays optional; an undefined value is not converted
-to a supplied string. This does not trim values, count only digits, change widget
-clear defaults, or change unconstrained/zero-minimum-only blank normalization.
-Array positions remain unchanged.
-
-This correction is included in 0.4.0, not registry `0.3.13`.
-Publication and Formstudio adoption remain separate gates.
-
-### Wizard configuration errors
-
-In multi-step mode, invalid schema configuration (for example, a malformed
-`pattern`) blocks Next or Submit and shows the validator's root error by default.
-This does not change pattern matching or remove the malformed constraint.
-Ordinary answer-validation errors remain field-local by default.
-
-An explicit `showErrorList={false}` opts out of the root error list without
-allowing invalid progression; `showErrorList={true}` enables the list. Custom
-`templates.ErrorListTemplate` renders this feedback as it does other RJSF errors.
-Configuration feedback tracks schema-only edits on the same mounted Wizard,
-including when answers do not change. Correcting the schema clears configuration
-feedback and restores navigation without discarding current values or replaying
-answer-change callbacks. Initial and final step guards use the current validation
-result; the error list does not replace those guards.
+const uiSchema: UiSchema = {
+  name: { 'ui:widget': 'text', 'ui:options': { allowClear: true } },
+  email: { 'ui:widget': 'email' },
+};
 
+export default function ContactForm() {
+  const [formData, setFormData] = useState({});
+
+  return (
+    <ExtendedForm
+      schema={schema}
+      uiSchema={uiSchema}
+      formData={formData}
+      onChange={({ formData }) => setFormData(formData)}
+      onSubmit={({ formData }) => console.log('Accepted answers', formData)}
+    />
+  );
+}
+```
 
+EDF supplies its widgets and validator by default. Override the RJSF `widgets`,
+`fields` or `templates` props when your application needs custom rendering.
+`customWidgets`, `validator` and commonly used RJSF types are exported from
+`extended-dynamic-forms`; no private subpath import is needed.
 
-### Step Layouts with LayoutGridField
+## Multi-step forms
 
-Wizard steps can define their own grid layout using a custom object field (e.g., `LayoutGridField`). Place the layout at the step key in `uiSchema` and pass your custom field via `fields` to `WizardForm`.
+`WizardForm` detects steps from root properties beginning with `STEP_`. Define at
+least two step objects to show wizard navigation; one step renders as a
+single-page form.
 
 ```tsx
 import { WizardForm } from 'extended-dynamic-forms';
+import 'extended-dynamic-forms/dist/style.css';
 
 const schema = {
   type: 'object',
   properties: {
-    STEP_LAYOUT: {
+    STEP_PERSONAL: {
       type: 'object',
-      title: 'Personal Info',
-      properties: {
-        firstName: { type: 'string', title: 'First Name' },
-        lastName: { type: 'string', title: 'Last Name' },
-        age: { type: 'number', title: 'Age' },
-        gender: { type: 'string', enum: ['Male','Female','Other'] },
-        favoriteBook: { type: 'string' },
-      }
-    }
-  }
-};
-
-const uiSchema = {
-  STEP_LAYOUT: {
-    'ui:field': 'LayoutGridField',
-    'ui:layoutGrid': {
-      'ui:row': [
-        { 'ui:row': { gutter: [16,16], children: [
-          { 'ui:col': { span: 12, children: ['firstName'] } },
-          { 'ui:col': { span: 12, children: ['lastName'] } }
-        ]}},
-        { 'ui:row': { gutter: [16,16], children: [
-          { 'ui:col': { span: 24, children: ['age'] } }
-        ]}},
-        { 'ui:row': { gutter: [16,16], children: [
-          { 'ui:col': { span: 24, children: ['gender'] } }
-        ]}},
-        { 'ui:row': { gutter: [16,16], children: [
-          { 'ui:col': { span: 24, children: ['favoriteBook'] } }
-        ]}}
-      ]
-    }
-  }
-};
-
-// LayoutGridField is included by default in EDF; no extra wiring needed
-<WizardForm schema={schema} uiSchema={uiSchema} />
-```
-
-Notes:
-- EDF includes `LayoutGridField` out of the box. Just set `ui:field: 'LayoutGridField'` on the step object.
-- EDF variant uses `'ui:layoutGrid'` with AntD gutter and 24-grid spans. The RJSF canonical layout (`'ui:layout'` with 12-grid widths) is also parsed.
-- You can still override or extend via the `fields` prop if needed.
-- LayoutGridField now writes nested updates immutably using path metadata. This is enabled by default; set `ui:options.pathAware: false` on a step to fall back to the previous shallow merge behaviour.
-
-## Event System & Webhooks
-
-Central event orchestration for all form interactions:
-
-```typescript
-<ExtendedForm
-  schema={schema}
-  uiSchema={uiSchema}
-  webhooks={[{
-    url: 'https://api.example.com/events',
-    events: ['change', 'blur'],
-    debounceMs: 500,
-    retries: 3
-  }]}
-  onFieldChange={(event) => console.log(event.fieldId, event.fieldValue)}
-/>
-```
-
-**Event Types:**
-- `focus` - Field focus
-- `blur` - Field blur
-- `change` - Value changes
-- `submit` - Form submission
-- `stepChange` - Wizard navigation
-- `validationError` - Validation failures
-
-## Custom Widgets
-
-All widgets must integrate with the event system:
-
-```typescript
-import { WidgetProps } from '@rjsf/utils';
-import { useFieldEventHandlers } from 'extended-dynamic-forms/events';
-
-export const CustomWidget: FC<WidgetProps> = ({ id, value, onChange, schema }) => {
-  const fieldEventHandlers = useFieldEventHandlers(id, schema);
-  
-  const handleChange = async (newValue) => {
-    onChange(newValue);  // RJSF update
-    await fieldEventHandlers.onChange(newValue);  // Event system
-  };
-  
-  return <Input value={value} onChange={(e) => handleChange(e.target.value)} />;
+      title: 'Personal details',
+      required: ['name'],
+      properties: { name: { type: 'string', minLength: 1 } },
+    },
+    STEP_CONTACT: {
+      type: 'object',
+      title: 'Contact details',
+      properties: { email: { type: 'string', format: 'email' } },
+    },
+  },
 };
-```
-
-### Auto-registered by Default
-- All EDF custom widgets are included by default; no wiring is required.
-- Every widget is also exposed as a field, so you can use either `ui:widget` or `ui:field` with the same key.
-
-Examples:
-
-```json
-{
-  "schema": { "type": "string", "title": "First Name" },
-  "uiSchema": { "ui:widget": "text" }
-}
-```
 
-```json
-{
-  "schema": { "type": "string", "title": "First Name" },
-  "uiSchema": { "ui:field": "text" }
+export default function RegistrationForm() {
+  return (
+    <WizardForm
+      schema={schema}
+      uiSchema={{}}
+      onStepChange={(stepIndex, data, stepId) => {
+        console.log('Current step', stepIndex, stepId, data);
+      }}
+      onLiveChange={(flatData) => console.log('Current answers', flatData)}
+      onSubmit={({ formData, flatFormData }) => {
+        console.log('Accepted step answers', formData);
+        console.log('Accepted flat answers', flatFormData);
+      }}
+    />
+  );
 }
 ```
 
-## JsonLogic Migration Examples
-
-Common patterns for migrating from function-based conditions:
-
-```typescript
-// Equality
-// Before: (formData) => formData.field === "value"
-// After:  { "==": [{ "var": "field" }, "value"] }
-
-// Boolean check
-// Before: (formData) => formData.isEnabled
-// After:  { "var": "isEnabled" }
-
-// AND condition
-// Before: (formData) => formData.a && formData.b
-// After:  { "and": [{ "var": "a" }, { "var": "b" }] }
-
-// Array contains
-// Before: (formData) => formData.roles?.includes("admin")
-// After:  { "in": ["admin", { "var": "roles" }] }
-```
-
-## Available Widgets
-
-### Complete Widget List
+Conditions use flat answer paths without the `STEP_` prefix. Initial answers may
+be flat or nested under step keys; explicit nested snapshots take precedence.
+Use distinct answer keys across steps when working with flat data.
 
-#### Choice Widget (Unified Selection)
-- **ChoiceWidget** - Intelligent widget that automatically adapts based on schema:
-  - Renders as dropdown/select for regular choices
-  - Renders as radio group when `ui:widget` is "radio"
-  - Renders as checkbox group for multi-select arrays
-  - Supports static and dynamic data sources (API, WebSocket)
+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
+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.
 
-#### Text Input Widgets
-- **TextWidget** - Standard text input with Ant Design styling
-- **TextareaWidget** - Multi-line text input
-- **PasswordWidget** - Password input with visibility toggle
+Array positions and blank array entries are preserved through editing and
+navigation. Supplied strings with directly declared `pattern`, positive
+`minLength`, or a valid explicit `maxLength` retain their characters for
+validation. Other nested/edit blank-string normalization remains in place.
+JSON Schema `required` checks presence. A positive `minLength` rejects an empty
+string; rejecting whitespace-only answers requires an appropriate non-whitespace
+`pattern`. Malformed schema patterns block progression and show configuration
+errors by default; hiding the error list does not bypass validation.
 
-With the SDK's default `FieldTemplate`, Text, Email, URL and Password
-`ui:options.style` overrides the selected input's theme presentation.
-For example: `{ "ui:widget": "text", "ui:options": { "style": { "color": "#b4141e", "fontSize": 18 } } }`.
-Updating or removing this style does not change answers; styles stay scoped to
-that field, including nested fields. `ui:style` and `ui:options.formItem.style`
-remain container styling. A custom widget's explicit `options.style` takes
-precedence, and a host replacing `FieldTemplate` retains control of its styling.
-With addons, the complete style still reaches Ant Design's outer `Input.style`
-surface. Only explicit control presentation is additionally applied to the
-editable control: text color/font/spacing/alignment/decoration/caret, background
-paint, padding, and border color/style/width/radius (including physical/logical
-padding and border sides). Inputs with icons, prefix/suffix, clear or count use
-the affix control so inner padding is not applied twice.
-Other properties retain native outer ownership rather than being copied onto a
-second surface: sizing, margins, positioning/insets, transforms, layout/alignment
-and compositional effects are not duplicated. No properties are removed from
-the original `Input.style`; this rule also applies to explicit host
-`options.style`. Without addons, native control styling is unchanged.
-
-`PasswordWidget` uses the same field-scoped style and control-presentation rules,
-including its masked and revealed states. The default template supplies a style
-only for the matching field ID when the widget has no explicit `options.style`.
-An explicit host style wins as a complete object, including `{}`; parent/object
-styles do not become a nested password's control style. The password eye, clear,
-count, prefix and addons retain their native Ant Design behavior. Numeric zero
-values and the original style declaration order are preserved when presentation
-properties are mirrored onto the control. Style changes do not replace answers
-or synthesize change/submission callbacks.
-Recovered field typography also reaches the editable input inside an affix
-wrapper, so its own theme font does not override the author's font. Host
-semantic input properties remain unless the field overrides that property.
-Email uses the same borderless status-background fallback as Text; explicit
-backgrounds, disabled controls and host CSS retain their existing precedence.
-
-
-#### Specialized Input Widgets
-- **ColorWidget** - Color picker using HTML5 color input
-- **EmailWidget** - Email input with validation
-- **URLWidget** - URL input with validation
-- **TelephoneWidget** - Phone number input
-- **NumberWidget** - Numeric input with increment/decrement controls
-
-URLWidget honors an active `ui:options.type` on its existing native input
-(for example, `text` or `url`), independently of `inputMode`. TextWidget
-honors that override only on the existing URL route, identified by
-`ui:options.inputType: 'url'`. Other TextWidget routes, including utility
-Email/Phone and direct Text, retain their published native Text behavior.
-Omitted, `undefined`, `null` and empty-string types preserve each route's
-existing default: URL for URLWidget, Text for TextWidget. The `inputType`
-marker alone never supplies a native type.
-
-Changing HTML type can change native browser validity; it does not change
-schema type, URI format, pattern, Required, answers or callbacks. Explicit
-schema URL constraints still apply with HTML Text. Formstudio's URL author
-choices remain Text/URL. URL acceptance uses HTTP/HTTPS by default, independently
-of the HTML type and `validateUrl`. To allow extra schemes, set
-`ui:options.allowedProtocols`, for example `['http://', 'https://', 'mailto']`.
-Scheme names are case-insensitive and accept bare names, `:` or `://` suffixes.
-An explicit list replaces the defaults, and `[]` rejects every nonempty URL.
-`javascript:`, `data:` and `vbscript:` are always blocked, even when listed.
-Optional empty answers still follow the schema's existing validation.
-This applies to ExtendedForm submission, Wizard progression/final submission and
-the TextWidget URL route. Raw answers are not migrated or rewritten.
-After adopting this SDK change, existing forms with no protocol list reject
-non-HTTP(S) answers. Authors must explicitly allow other safe schemes before
-those answers are accepted. Link preview remains restricted to HTTP/HTTPS.
-
-With the default `FieldTemplate`, ordinary `tel`/`telephone` fields recover
-`ui:options.style` for that field's Phone control. Changing, clearing or restoring
-the style leaves the current answer and sibling fields unchanged. A custom
-widget's explicit native `options.style`, including `{}`, takes precedence;
-recovery requires a matching field ID, so a host-replaced child template cannot
-borrow an ancestor's style.
-
-For recovered Phone styles with addons, control presentation (text, background,
-padding and borders) also reaches the editable input or affix control through
-Ant Design's supported semantic styles. Layout and effects retain native outer
-`Input.style` ownership. Explicit native styles are not rewritten or mirrored.
-Intentional outer `Form.Item` presentation remains separate; outer and control
-borders/padding are not a single combined-border contract.
-
-Recovered Phone typography also reaches the editable input inside an affix
-wrapper, where Ant Design otherwise applies its own font rule. This includes
-the existing Phone-via-Text route (`inputType: 'tel'`), without changing its
-native Text input type or unrelated Text behavior. Host input semantic styles
-remain unless the selected field overrides the same typography property.
-Padding, borders and background remain on the visible control rather than
-being duplicated onto its inner input. Explicit native `options.style` and
-intentional outer styling retain their existing ownership.
-
-Exact inside Before/After placement preserves distinct prefix/suffix content
-and stable wrappers through clear; omitted/outside/unsupported markers retain
-the native outside slot. These placement options do not enter phone answers.
-Phone `ui:options.mask` uses `9` for a digit, `a` for an ASCII letter and `*`
-for any character. Other characters are display literals. For example,
-`+1 (999) 999-9999` displays `+1 (202) 555-0123` and emits `+12025550123`.
-A national mask uses the configured country code. An international mask includes
-its own calling-code digits. Explicit foreign numbers are preserved rather than
-silently changed to a fixed mask country.
-
-Letter slots are display-only (no phoneword conversion). They survive the current
-edit but are absent from saved answers and cannot be reconstructed on reload.
-Only `+` and digit content enter answers, events and validation. Masked answers
-use E.164 syntax plus the existing configured phone constraints. Empty optional
-answers retain existing empty-value behaviour. Display separators do not spend
-the canonical length budget. Backspace/Delete cross inserted literals.
-
-A non-empty mask with slots takes precedence over native formatter/parser
-callbacks and international grouping. Clearing the mask restores those existing
-paths. Invalid/non-string masks without slots are ignored. The default keyboard
-hint remains `tel`. Loading a saved answer does not rewrite stored data.
-
-Phone country entries accept an optional `pattern` in the same mask grammar.
-Set `ui:options.useCountryMasks: true` to use the selected/detected country's
-pattern as a fallback. False or unset keeps existing behaviour, including stored
-country names/codes and answers. An explicit field `mask` always takes priority.
-For example, `countries: [{ code: '+44', name: 'UK', pattern: '+44 99 9999 9999' }]`
-formats `+442079460018` as `+44 20 7946 0018`. Countries also accept JSON text.
-Missing/non-string patterns or patterns without slots keep the unmasked route.
-No regex or exact-length validation is inferred from a country display pattern.
-Existing canonical-phone feedback and explicit schema constraints still apply.
-Disabling the opt-in restores the prior display path without migrating answers.
-
-#### Visual Input Widgets
-- **RangeWidget** / **SliderWidget** - Slider for numeric ranges
-- **RatingWidget** - Star rating component
-
-#### Date & Time Widgets
-- **DateWidget** / **EnhancedDateWidget** - Date picker with Ant Design DatePicker
-- **DateTimeWidget** - Combined date and time picker
-
-#### File Upload Widgets
-- **FileWidget** - Basic file input
-- **FileUploadWidget** - Enhanced upload with progress, preview, and base64 support
-
-### Widget Configuration Examples
-
-#### Basic Text Input
-```json
-{
-  "schema": {
-    "type": "string",
-    "title": "Full Name"
-  },
-  "uiSchema": {
-    "ui:widget": "text",
-    "ui:placeholder": "Enter your full name"
-  }
-}
-```
+`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.
 
-#### Text Input with Variant and Auto-complete
-```json
-{
-  "schema": { "type": "string", "title": "Username" },
-  "uiSchema": {
-    "ui:widget": "text",
-    "ui:options": {
-      "variant": "outlined",
-      "autoFocus": true,
-      "autoComplete": "username",
-      "allowClear": true
-    }
-  }
-}
-```
+## Conditional logic
 
-#### Date Range (RangePicker)
-```json
-{
-  "schema": {
-    "type": "array",
-    "title": "Date Range",
-    "items": { "type": "string", "format": "date" },
-    "minItems": 2,
-    "maxItems": 2
-  },
-  "uiSchema": {
-    "ui:widget": "date",
-    "ui:options": {
-      "range": true,
-      "format": "YYYY-MM-DD",
-      "placeholder": ["Start date", "End date"],
-      "picker": "date"
-    }
-  }
-}
-```
+Put JsonLogic conditions and JSON Patch effects in `x-edf:rules` on the schema
+or UI schema. Configuration is JSON-only; JavaScript source strings are not
+executed.
 
-With time selection:
-```json
-{
-  "schema": {
-    "type": "array",
-    "title": "Date Range With Time",
-    "items": { "type": "string" },
-    "minItems": 2,
-    "maxItems": 2
-  },
-  "uiSchema": {
-    "ui:widget": "date",
-    "ui:options": {
-      "range": true,
-      "showTime": true,
-      "format": "YYYY-MM-DD HH:mm",
-      "placeholder": ["Start date/time", "End date/time"]
-    }
-  }
-}
-```
+For example, this schema rule adds a property when `accountType` is `premium`:
 
-Month range:
 ```json
 {
-  "schema": {
-    "type": "array",
-    "title": "Month Range",
-    "items": { "type": "string" },
-    "minItems": 2,
-    "maxItems": 2
+  "type": "object",
+  "properties": {
+    "accountType": { "type": "string", "enum": ["basic", "premium"] }
   },
-  "uiSchema": {
-    "ui:widget": "date",
-    "ui:options": {
-      "range": true,
-      "picker": "month",
-      "format": "YYYY-MM",
-      "placeholder": ["Start month", "End month"]
+  "x-edf:rules": [
+    {
+      "name": "Premium details",
+      "condition": { "==": [{ "var": "accountType" }, "premium"] },
+      "effect": [
+        { "op": "add", "path": "/properties/premiumFeatures", "value": { "type": "string" } }
+      ]
     }
-  }
-}
-```
-
-#### Number Input with Range
-```json
-{
-  "schema": {
-    "type": "number",
-    "title": "Age",
-    "minimum": 0,
-    "maximum": 120
-  },
-  "uiSchema": {
-    "ui:widget": "number"
-  }
-}
-```
-
-#### Number grouping (BUGS-S0-R202, 0.4.0)
-
-The default `number` / `updown` NumberWidget supports an explicitly configured
-ordinary single-character `ui:options.groupSeparator`. For example:
-
-```json
-{
-  "ui:widget": "updown",
-  "ui:options": {
-    "groupSeparator": "_",
-    "precision": 2,
-    "decimalSeparator": "."
-  }
-}
-```
-
-`1234567.89` displays as `1_234_567.89`; editing `7_654_321.25` emits the
-number `7654321.25`, not formatted text. Grouping affects the integer part only.
-Native precision, step-derived precision and decimal normalization delegate to
-the declared public `@rc-component/mini-decimal` API used by Ant's numeric input;
-EDF does not replace that arithmetic or rewrite restored answers on render.
-Partial user typing is retained until native blur/step normalization.
-
-Absent, undefined or empty-string group options retain inactive native behavior.
-An active (truthy) native formatter or parser retains its existing path, as does
-an explicitly provided input `type`. Empty formatter/parser strings are inactive,
-matching native hooks; they do not disable literal grouping. This option neither
-overrides active hooks nor executes serialized JavaScript. Multi-character
-groups, numeric/sign/exponent/decimal-token ambiguity and broader locale or
-StringMode policies are not established here; those inputs retain native behavior
-rather than removing numeric characters. Custom fields/widgets remain host-owned.
-
-This correction is included in 0.4.0 release preparation.
-Publication and downstream adoption remain separate gates; do not republish
-different contents under an existing published version.
-
-#### Numeric controls and exact decimal values
-
-Number, Currency and Percentage presentations use the same `number` / `updown`
-widget. `ui:options.min` / `max` clamp input on blur; `step` controls increments.
-Schema `minimum`, `maximum`, `multipleOf` and numeric draft-7
-`exclusiveMinimum` / `exclusiveMaximum` independently validate submissions.
-`controls`, `keyboard` and `changeOnWheel` independently enable their respective
-input interactions; wheel changes require focus.
-
-Native integrations can preserve exact decimal strings with a **string schema**
-and `stringMode`, for example:
-
-```json
-{
-  "schema": {
-    "type": "string",
-    "title": "Exact decimal",
-    "pattern": "^-?[0-9]+(?:\\.[0-9]+)?(?![\\s\\S])"
-  },
-  "uiSchema": {
-    "ui:widget": "updown",
-    "ui:options": { "stringMode": true }
-  }
+  ]
 }
 ```
 
-This preserves values such as `"9007199254740993.123456789123456789"` as strings
-through editing and submission. It is not a numeric-schema migration:
-RJSF's numeric field converts values to JavaScript numbers, which can lose
-precision even with `stringMode`. JSON Schema numeric constraints do not validate
-strings; hosts choosing string responses must supply decimal-aware validation.
-Do not change existing numeric schemas or drop their constraints implicitly.
-
-Native callable `formatter` / `parser` hooks remain supported. JavaScript source
-text in JSON is not a callable hook, and EDF does not evaluate it. Formstudio's
-author-entered formatter/parser execution requires separate approval.
+UI rules belong in `uiSchema['x-edf:rules']`; schema rules belong in
+`schema['x-edf:rules']`. Array-item presentation can use `ui:dynamicItems` with
+per-item JsonLogic. Conditional requiredness changes validation, not just a
+visual required marker.
 
-Formstudio String Mode exports this string schema for Number, Currency and
-Percentage. Fields without String Mode retain numeric schemas. Existing answers
-are not migrated. Clearing String Mode emits an absent value unless `emptyValue`
-is explicitly configured, so optional decimal fields remain submittable.
-Numeric schema bounds and multiples do not validate strings.
-UI min/max, step and explicitly configured precision still apply in the widget.
-String Mode preserves decimal precision, while the numeric input normalises
-spelling such as leading/trailing zeroes. The generated pattern accepts signed
-plain decimals and rejects exponent notation, grouping, affixes and whitespace.
+## Widgets and options
 
-#### Rating Widget
-```json
-{
-  "schema": {
-    "type": "number",
-    "title": "Rate your experience",
-    "minimum": 0,
-    "maximum": 5
-  },
-  "uiSchema": {
-    "ui:widget": "rating",
-    "ui:options": {
-      "count": 5,
-      "allowHalf": true
-    }
-  }
-}
-```
-
-#### Choice Widget (Dropdown)
-```json
-{
-  "schema": {
-    "type": "string",
-    "title": "Country",
-    "enum": ["us", "uk", "au", "ca"],
-    "enumNames": ["United States", "United Kingdom", "Australia", "Canada"]
-  },
-  "uiSchema": {
-    "ui:widget": "choice"
-  }
-}
-```
+Select a registered widget using `ui:widget`. The same registered key can also
+be used as `ui:field`; an explicit field override controls its own rendering.
 
-#### Choice Widget with AntD props (Dropdown)
-```json
-{
-  "schema": { "type": "string", "title": "Country" },
-  "uiSchema": {
-    "ui:widget": "choice",
-    "ui:options": {
-      "choiceConfig": {
-        "presentationMode": "dropdown",
-        "dataSource": { "type": "static", "options": [
-          { "label": "USA", "value": "us" }, { "label": "UK", "value": "uk" }
-        ]},
-        "antd": { "select": { "dropdownMatchSelectWidth": 280, "placement": "bottomLeft" } }
-      }
-    }
-  }
-}
-```
+| Input | Registered keys |
+| --- | --- |
+| Text | `text`, `textarea`, `password` |
+| Email, URL and phone | `email`, `url`, `tel`, `telephone` |
+| Number | `number`, `updown` |
+| Choices | `choice` with dropdown, radio or checkbox presentation |
+| Date and time | `date`, `time`, `datetime-local` |
+| Visual inputs | `color`, `range`, `slider`, `rating`, `switch` |
+| Files | `file`, `fileUpload` |
+| Display | `title`, `heading`, `html`, `markdown`, `image`, `alert`, `spacer`, `divider` |
 
-#### Choice Widget (Radio Group)
-```json
-{
-  "schema": {
-    "type": "string",
-    "title": "Gender",
-    "enum": ["male", "female", "other"]
-  },
-  "uiSchema": {
-    "ui:widget": "choice",
-    "ui:options": {
-      "presenter": "radio"
-    }
-  }
-}
-```
+Configure supported Ant Design props in `ui:options`. Container options belong
+in `ui:options.formItem`; input styling and container styling are separate.
+For the unified choice widget, use `ui:options.choiceConfig` for data sources,
+presentation and presenter-specific Ant Design options.
 
-#### Choice Widget (Checkbox Group - Multi-select)
 ```json
 {
-  "schema": {
-    "type": "array",
-    "title": "Interests",
-    "items": {
-      "type": "string",
-      "enum": ["sports", "music", "reading", "travel"]
-    },
-    "uniqueItems": true
-  },
-  "uiSchema": {
-    "ui:widget": "choice",
+  "name": {
+    "ui:widget": "text",
     "ui:options": {
-      "presenter": "checkbox"
+      "allowClear": true,
+      "autoComplete": "name",
+      "variant": "outlined",
+      "style": { "fontSize": 18 },
+      "formItem": { "style": { "marginBottom": 24 } }
     }
-  }
-}
-```
-
-#### Date Picker
-```json
-{
-  "schema": {
-    "type": "string",
-    "title": "Date of Birth",
-    "format": "date"
   },
-  "uiSchema": {
+  "birthday": {
     "ui:widget": "date",
-    "ui:options": {
-      "format": "DD/MM/YYYY",
-      "picker": "date"
-    }
-  }
-}
-```
-
-#### File Upload
-```json
-{
-  "schema": {
-    "type": "string",
-    "title": "Resume",
-    "format": "data-url"
-  },
-  "uiSchema": {
-    "ui:widget": "fileUpload",
-    "ui:options": {
-      "accept": ".pdf,.doc,.docx",
-      "maxSize": 5242880,
-      "multiple": false
-    }
-  }
-}
-```
-
-#### File Upload (Ant Upload options)
-```json
-{
-  "schema": { "type": "string", "title": "Profile Picture" },
-  "uiSchema": {
-    "ui:widget": "fileUpload",
-    "ui:options": {
-      "useAntUpload": true,
-      "listType": "picture-card",
-      "showUploadList": { "showPreviewIcon": true, "showRemoveIcon": true },
-      "maxCount": 1,
-      "accept": "image/*"
-    }
-  }
-}
-```
-
-#### Color Picker
-```json
-{
-  "schema": {
-    "type": "string",
-    "title": "Favorite Color",
-    "format": "color"
+    "ui:options": { "format": "DD/MM/YYYY", "disableFutureDates": true }
   },
-  "uiSchema": {
-    "ui:widget": "color"
-  }
-}
-```
-
-#### Range/Slider Widget
-```json
-{
-  "schema": {
-    "type": "number",
-    "title": "Volume",
-    "minimum": 0,
-    "maximum": 100
-  },
-  "uiSchema": {
-    "ui:widget": "range",
-    "ui:options": {
-      "marks": {
-        "0": "Mute",
-        "50": "50%",
-        "100": "Max"
-      }
-    }
-  }
-}
-```
-
-#### Hidden Field
-```json
-{
-  "schema": {
-    "type": "string",
-    "title": "User ID"
-  },
-  "uiSchema": {
-    "ui:widget": "hidden"
+  "score": {
+    "ui:widget": "rating",
+    "ui:options": { "count": 5, "allowHalf": true }
   }
 }
 ```
 
-### Widget Registration (optional)
-
-Widgets are auto-registered. You can still override or pass a subset if needed:
-
-```typescript
-import { ExtendedForm, customWidgets } from 'extended-dynamic-forms';
-
-// Override or register specific widgets
-<ExtendedForm 
-  widgets={{
-    text: customWidgets.text,
-    date: customWidgets.date,
-    choice: customWidgets.choice
-  }}
-/>
-```
-
-## Development
-
-```bash
-# Development
-npm run dev              # Start playground
-npm run test             # Run tests
-npm run test:ui          # Test with UI
-
-# Building
-npm run build            # Build library
-npm run build:vanilla    # Build standalone (currently broken - JsonLogic incompatible)
-npm run preview          # Preview build
-
-# Code Quality
-npm run lint             # ESLint
-npm run format           # Prettier
-```
-
-## Project Structure
-
-```
-src/
-├── components/          # Core form components
-├── conditionals/        # Declarative conditional engines (internal)
-│   └── v2/             # Current implementation
-├── events/             # Event orchestration
-├── layouts/            # Layout systems
-│   └── wizard/         # Wizard form components
-├── widgets/            # Input widgets
-└── utils/              # Utilities
-```
-
-## Examples
-
-Interactive examples available at `/playground/src/demos/`:
-
-- **Wizard Forms**: Australian Company Onboarding, Employee Onboarding
-- **Conditionals**: Dynamic visibility, validation, array handling
-- **Events**: Webhook integration, field tracking
-- **Widgets**: All available components
-
-Run `npm run dev` to explore examples.
-
-## Known Limitations
-
-1. **Dependency installation**: The legacy npm lockfile is stale; use `yarn.lock` for this checkout.
-2. **CommonJS packaging**: `require` resolves to `.umd.js` inside a `"type": "module"` package; a Node consumer returned no named SDK exports. ESM imports work. This pre-existing packaging defect is not repaired by the wizard fixes.
-3. **Vanilla JS**: JsonLogic not supported in standalone builds
-4. **Arrays**: No drag-and-drop functionality
-5. **JSON Patch**: Only supports add/remove/replace operations
-6. **Test Coverage**: Limited for UI components and events
-
-## TypeScript
-
-Full TypeScript support with exported types:
-
-```typescript
-import { ExtendedForm, WizardForm } from 'extended-dynamic-forms';
-// Config is JSON-only; rules are embedded via x-edf:rules
-```
-
-## Contributing
-
-1. Fork the repository
-2. Create your feature branch
-3. Add tests for new functionality
-4. Ensure all tests pass
-5. Submit a pull request
-
-## License
-
-MIT License - see LICENSE file for details.
+- Choices can use schema enums or configured static/remote data sources. Single
+  choices emit scalars; multiple choices emit arrays. Remote paging is not implemented.
+- Date options include `disablePastDates`, `disableFutureDates`,
+  `disableWeekends` and `range: true` for a range picker.
+- Number options include `min`, `max`, `step`, `precision`, `groupSeparator`,
+  `decimalSeparator`, `controls`, `keyboard` and `changeOnWheel`. Display grouping
+  does not become part of numeric answers. Schema bounds validate independently
+  of input clamping.
+- Exact decimals require `stringMode: true` with a string schema and suitable
+  string/decimal-aware validation. Numeric schemas convert values to JavaScript
+  numbers; numeric JSON Schema bounds do not validate decimal strings.
+- Telephone `mask` uses `9` for a digit, `a` for an ASCII letter and `*` for any
+  character. Mask literals affect display, while answers retain digits and an
+  optional leading `+`. `useCountryMasks: true` enables country-pattern fallback;
+  an explicit field mask takes precedence. Letter slots are display-only.
+- URL answers accept HTTP/HTTPS by default. `allowedProtocols` replaces those
+  defaults; `[]` rejects every nonempty URL. `javascript:`, `data:` and `vbscript:`
+  remain blocked even if listed. Link previews are restricted to HTTP/HTTPS.
+- File upload options include `accept`, `maxSize`, `multiple` and Ant Upload
+  presentation controls. Use a schema compatible with the selected value mode.
+
+Choice presenter-specific Ant Design options use `choiceConfig.antd`, such as
+`choiceConfig.antd.select` for dropdown props.
+
+## Values and validation
+
+### 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.
+
+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.
+
+### Date and time answers
+
+| Widget/schema | Accepted answer |
+| --- | --- |
+| Single Date with `format: "date"` | Calendar day, `YYYY-MM-DD` |
+| Time with `format: "time"` | Wall-clock time, `HH:mm:ss`, without timezone conversion |
+| DateTime | UTC ISO instant with `Z`, displayed in the respondent's browser-local timezone |
+| Calendar Date Range (`date` with `range: true`) | Pair of ISO calendar days, even with plain string item schemas |
+
+Date/Time display formats do not change those schema-formatted answers. Native
+Date/Time string schemas without their respective `format` retain configured-format
+output. Explicit `showTime` / `withTime` ranges retain formatted time-bearing
+pairs rather than the UTC DateTime contract.
+
+DateTime rejects nonexistent daylight-saving times and requires an explicit
+occurrence choice for repeated local times. Restored valid offset-bearing instants
+and fractional-second precision are preserved until edited. Zone-less or invalid
+saved DateTime strings require re-entry; no timezone is guessed. Pending invalid
+edits block submission and wizard progression, even on optional fields, and can
+emit the `Invalid date-time` draft marker. DateTime clear emits `undefined`
+regardless of an old `emptyValue` setting.
+
+Calendar ranges reject impossible, reversed and incomplete pairs. Clear emits
+`[]`; optional schemas must allow zero items if clear should be valid. Required
+ranges reject `[]`. Explicit `allowEmpty` endpoint options also need schemas
+that permit an empty string at that endpoint. Calendar bounds compare local days;
+an explicit `disabledDate` callback takes precedence over convenience flags,
+while explicit bounds still apply.
+
+When upgrading from 0.3.x, review the date/time, empty-answer and URL contracts
+against your schemas, callbacks and stored responses. Do not rewrite persisted
+or in-progress answers automatically. See the changelog for version-specific changes.
+
+## Events and webhooks
+
+`ExtendedForm` delivers `onFieldFocus`, `onFieldBlur` and `onFieldChange` events
+with `fieldId` and `fieldValue`. `WizardForm` currently does not deliver those
+field callback props; use `onLiveChange` to subscribe to wizard answer snapshots.
+Use `onSubmit` for accepted form answers. Optional `webhooks` configure event
+destinations, event names, debounce timing and retries. Keep endpoint authorization
+and response-storage policy in your host application.
+
+Custom widgets can import `useFieldEventHandlers` from the root package alongside
+other event exports. Call the RJSF `onChange` to update the answer and the field
+event handler to participate in EDF events.
+
+## Known limitations
+
+- CommonJS `require` is unsupported; use ESM imports. NodeNext declaration
+  compatibility is not established; use the ESNext/Bundler configuration above.
+- The separate vanilla JavaScript build lacks JsonLogic support. Use the React
+  package for declarative conditional forms.
+- Arrays do not support drag-and-drop.
+- JSON Patch effects support `add`, `remove` and `replace` only, not `move`, `copy` or `test`.
+
+## Links and license
+
+- [npm package](https://www.npmjs.com/package/extended-dynamic-forms)
+
+MIT. See [LICENSE](LICENSE).