extended-dynamic-forms 0.3.13 → 0.4.0

package/README.md

@@ -7,12 +7,11 @@ Conditional logic is configured with pure JSON via `x-edf:rules` in your `schema
 ## Project Status
 
 **Important Notes:**
-- Requires RJSF source in sibling directory for development
-- Cannot be installed from npm due to local file dependencies  
+- 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 is provided by logic and snapshot suites; component/UI tests
-  are intentionally omitted
+- 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
@@ -33,35 +32,290 @@ All custom widgets built on Ant Design components forward their props via `ui:op
   - 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.
+
 ## Installation
 
-**Note:** This library currently requires local development setup and cannot be installed via npm due to local file dependencies.
+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
-# 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
+yarn install --frozen-lockfile
+npm run build
 ```
 
-**Important:** The library is currently designed for internal use or as part of a monorepo setup. Standalone npm package distribution is not yet supported.
+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
 
-The project uses Vitest with **Node** environment to cover pure logic and serialized
-outputs. Component or DOM-level tests are intentionally excluded.
+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.
 
-- Run the full suite: `npm test`
-- Logic-only focus: `npm test -- tests/logic`
-- Snapshot updates: `npm test -- tests/snapshots -- -u`
+- 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.
 
-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`.
+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
 
@@ -163,6 +417,108 @@ Note on wizard detection:
 - 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.
+
+
+
 ### Step Layouts with LayoutGridField
 
 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`.
@@ -324,6 +680,41 @@ Common patterns for migrating from function-based conditions:
 - **TextareaWidget** - Multi-line text input
 - **PasswordWidget** - Password input with visibility toggle
 
+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
@@ -331,6 +722,87 @@ Common patterns for migrating from function-based conditions:
 - **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
@@ -381,7 +853,7 @@ Common patterns for migrating from function-based conditions:
   "schema": {
     "type": "array",
     "title": "Date Range",
-    "items": { "type": "string" },
+    "items": { "type": "string", "format": "date" },
     "minItems": 2,
     "maxItems": 2
   },
@@ -456,6 +928,89 @@ Month range:
 }
 ```
 
+#### 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.
+
+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.
+
 #### Rating Widget
 ```json
 {
@@ -712,8 +1267,8 @@ Run `npm run dev` to explore examples.
 
 ## Known Limitations
 
-1. **Dependencies**: Requires RJSF source in sibling directory
-2. **Installation**: Cannot install from npm
+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