extended-dynamic-forms 0.3.13 → 0.4.1

package/README.md

@@ -1,741 +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:**
-- Requires RJSF source in sibling directory for development
-- Cannot be installed from npm due to local file dependencies  
-- JSON logic conditions don't work with vanilla JavaScript builds
-- Array drag-and-drop is not implemented
-- Automated coverage is provided by logic and snapshot suites; component/UI tests
-  are intentionally omitted
-- 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)
+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
 
-**Note:** This library currently requires local development setup and cannot be installed via npm due to local file dependencies.
-
 ```bash
-# Clone RJSF as sibling directory (required)
-cd ..
-git clone https://github.com/rjsf-team/react-jsonschema-form.git
-
-# Setup Extended Dynamic Forms
-cd extended-dynamic-forms
-npm install
-npm run dev
+npm install extended-dynamic-forms
 ```
 
-**Important:** The library is currently designed for internal use or as part of a monorepo setup. Standalone npm package distribution is not yet supported.
-
-## Testing
-
-The project uses Vitest with **Node** environment to cover pure logic and serialized
-outputs. Component or DOM-level tests are intentionally excluded.
-
-- Run the full suite: `npm test`
-- Logic-only focus: `npm test -- tests/logic`
-- Snapshot updates: `npm test -- tests/snapshots -- -u`
-
-After pulling dependencies or updating `package.json`, run `npm install` (or
-`yarn install`) so the lockfile reflects removed packages such as
-`@testing-library/*` and `jsdom`.
-
-## Core Architecture
-
-### Declarative Conditionals (JSON-only)
+Install compatible peer dependencies if your application does not already have them:
 
-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' },
+  },
+};
+
+const uiSchema: UiSchema = {
+  name: { 'ui:widget': 'text', 'ui:options': { allowClear: true } },
+  email: { 'ui:widget': 'email' },
 };
 
-// Conditions refer to flattened form data (no STEP_ prefix)
-// Example rule (in uiSchema.x-edf:rules): { "==": [{ "var": "hasDriversLicense" }, true] }
+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)}
+    />
+  );
+}
 ```
 
-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`).
+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
-
-#### 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)
-
-#### Text Input Widgets
-- **TextWidget** - Standard text input with Ant Design styling
-- **TextareaWidget** - Multi-line text input
-- **PasswordWidget** - Password input with visibility toggle
+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.
 
-#### 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
+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.
 
-#### Visual Input Widgets
-- **RangeWidget** / **SliderWidget** - Slider for numeric ranges
-- **RatingWidget** - Star rating component
+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.
 
-#### Date & Time Widgets
-- **DateWidget** / **EnhancedDateWidget** - Date picker with Ant Design DatePicker
-- **DateTimeWidget** - Combined date and time picker
+`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.
 
-#### File Upload Widgets
-- **FileWidget** - Basic file input
-- **FileUploadWidget** - Enhanced upload with progress, preview, and base64 support
+## Conditional logic
 
-### Widget Configuration Examples
+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.
 
-#### Basic Text Input
-```json
-{
-  "schema": {
-    "type": "string",
-    "title": "Full Name"
-  },
-  "uiSchema": {
-    "ui:widget": "text",
-    "ui:placeholder": "Enter your full name"
-  }
-}
-```
-
-#### 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
-    }
-  }
-}
-```
-
-#### Date Range (RangePicker)
-```json
-{
-  "schema": {
-    "type": "array",
-    "title": "Date Range",
-    "items": { "type": "string" },
-    "minItems": 2,
-    "maxItems": 2
-  },
-  "uiSchema": {
-    "ui:widget": "date",
-    "ui:options": {
-      "range": true,
-      "format": "YYYY-MM-DD",
-      "placeholder": ["Start date", "End date"],
-      "picker": "date"
-    }
-  }
-}
-```
-
-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"
-  }
-}
-```
+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.
 
-#### Rating Widget
-```json
-{
-  "schema": {
-    "type": "number",
-    "title": "Rate your experience",
-    "minimum": 0,
-    "maximum": 5
-  },
-  "uiSchema": {
-    "ui:widget": "rating",
-    "ui:options": {
-      "count": 5,
-      "allowHalf": true
-    }
-  }
-}
-```
+## Widgets and options
 
-#### 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"
-  },
-  "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"
+    "ui:options": { "format": "DD/MM/YYYY", "disableFutureDates": true }
   },
-  "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. **Dependencies**: Requires RJSF source in sibling directory
-2. **Installation**: Cannot install from npm
-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).