valixa 0.0.0-stage → 1.0.0-rc.1

package/ADVANCED.md

@@ -0,0 +1,149 @@
+# Advanced reactive forms
+
+These APIs extend the existing `valixa` store. No framework or DOM is imported into core. Existing tuple/definition fields and atomic object/array values retain their meaning.
+
+## Dependencies and automatic validation
+
+```ts
+const form = createValixa({
+  subtotal: [0],
+  discount: { initial: 0, dependsOn: ['subtotal'],
+    validate: (value, { values }) => value <= Number(values.subtotal) },
+  password: ['', 'required | min:8'],
+  confirm: ['', 'same:password']
+}, { validation: { mode: 'onChange', debounce: 300, timeout: 5000 } });
+```
+
+`same` infers an edge; explicit `dependsOn` adds edges. Omitted dependencies on a custom validator mean it may read any value; every mutation invalidates that validator and its dependents. `dependsOn: []` explicitly declares independence. Declare **all** values a custom validator reads. Reverse traversal includes transitive dependents and visits each once. Unrelated errors and field snapshot identities remain intact. Error invalidation includes mapped server errors on affected fields.
+
+`form.dependencies` exposes frozen `dependencies`, `dependents`, `unknown` and `cycles` indexes. Missing references and cycles containing a new explicit `dependsOn` edge throw during blueprint construction, with an actionable cycle path. Existing inferred-only `same` cycles remain supported: validators compare a frozen snapshot and each affected field is traversed once, without recursive revalidation; diagnostics list those cycles. Unknown-dependency wildcards are not declared graph edges and do not create artificial cycles. Graphs describe validation reads, never derived-value computations.
+
+| Mode | Trigger |
+| --- | --- |
+| omitted / `manual` | Explicit `validate` and `submit` only |
+| `onSubmit` | Same automatic policy as manual; submit always validates |
+| `onChange` | Changed and dependent fields, after a value mutation |
+| `onBlur` | A field when `setTouched(name, true)`/binding blur is called |
+| `immediate` | Initially, and changed/dependent fields on mutation |
+
+Legacy `validateOn: 'change' | 'blur' | 'submit'` remains supported. An explicit new `validation.mode` takes precedence. No trigger is added by default. A no-op value write does not validate. On blur mode, a value change invalidates dependent errors, but waits for an explicit blur/validation trigger to revalidate them.
+
+Debounce is independently owned **per field**, including the initial immediate-mode run. `pending` includes scheduled timers and running validation; `validating` means running work. The optional form validator has its own single debounce timer. `validate(name)` bypasses debounce for that field; `validate()` and submit cancel queued field/form timers and validate everything freshly. Automatic and explicit requests for independent fields coexist. Replacing a request for a field aborts its previous owner. Validators within one field remain sequential, after built-in constraints; independent fields execute concurrently. Results ready in the same microtask turn share a snapshot publication.
+
+`timeout` is a finite positive duration **per running field/form request**, excluding debounce. Timeout aborts the signal and produces the structured `timeout` error. Omit it for no timeout. Cancellation also settles core validation promises when application validators ignore signals; it cannot undo remote side effects. `cancelValidation()`, reset, disposal and superseding error operations release owned timers. Cancelled/obsolete results return `stale` and cannot commit. `cancelValidation` is idempotent after disposal; other mutations still reject.
+
+## Conditional state
+
+```ts
+const form = createValixa({ country: [''], city: [''] }, {
+  behaviors: { city: {
+    dependsOn: ['country'],
+    visibleWhen: ({ values }) => Boolean(values.country),
+    enabledWhen: ({ values }) => Boolean(values.country),
+    requiredWhen: ({ values }) => Boolean(values.country),
+    readonlyWhen: ({ values }) => values.country === 'locked',
+    validateWhen: ({ values }) => Boolean(values.country)
+  } }
+});
+form.getFieldState('city'); // visible, disabled, readonly, required, validationEnabled
+```
+
+Predicates are synchronous, pure functions over frozen value snapshots. Explicit dependencies limit reevaluation; omitted dependencies are conservative. Dependencies/targets must name existing fields in that store. Behavior dependencies control reevaluation, separately from validator dependency declarations.
+
+| State | Values | Validation | Submission |
+| --- | --- | --- | --- |
+| Hidden | Retained | Continues unless `validateWhen` returns false | Included |
+| Disabled | Retained; binding user writes blocked | Continues, matching existing behavior | Included; a globally disabled form cannot submit |
+| Readonly | Retained; binding user writes blocked | Continues | Included |
+| Conditionally required | Retained | Adds the required rule; does not remove an existing static required rule | Included |
+| `validateWhen: false` | Retained | Skips field rules/custom validators; fresh validation clears its field errors | Included |
+
+Visibility is application state: use `visible` in React conditional rendering, Vue `v-if`, or Angular `@if`. No adapter removes DOM automatically. Binding flags are projected; core programmatic writes remain allowed. MUI and Angular native controls expose `aria-required`; Vuetify accepts explicit required metadata and otherwise uses core metadata. Applications can choose visual required markers without enabling a second validation owner.
+
+`resetWhen` resets a field **to its initial value on a false-to-true transition**, including initial evaluation. It does not repeatedly erase subsequent edits while true. Reset cascades evaluate on a draft, and only converge before publication; nonconvergent transitions throw. Ordinary reset restores initial values and reevaluates all behaviors without enabling automatic validation. It clears errors/touched/submission state; locale and global flags remain. Server errors are literals, survive presentation-only changes, and are invalidated by affected value or validation-eligibility changes. There is no automatic submission exclusion or configurable hidden-field erasure policy; express clearing with `resetWhen` and an appropriate initial value.
+
+## Explicit nested schemas and paths
+
+```ts
+import { createValixa, nested } from 'valixa';
+const form = createValixa({
+  user: nested({ name: ['', 'required'], email: ['', 'email'] }),
+  profile: { initial: { city: 'Cairo' as string } }, // atomic
+  tags: { initial: [] as string[] }                // atomic
+});
+form.setValue('user.name', 'Ahmed');
+form.setValues({ user: { email: 'a@example.com' } });
+form.state.values.user.name;
+form.field('user.email').state.errors;
+```
+
+Grammar is unambiguous: `[initial, rules?]` or `{initial, ...}` defines an atomic field; **only** `nested(schema)` introduces addressable children. Bare nested objects are rejected. An atomic object cannot be addressed via its internal properties. Nested patches preserve siblings. Values/submission payloads are nested data; compatibility `errors`/`touched` maps use canonical leaf path keys. `nestedErrors`, `nestedTouched`, and `nestedDirty` provide nested projections. `field(name)` is a cached core controller with a current `state` getter, `setValue`, `onBlur` and `subscribe`; its writes have core programmatic semantics.
+
+Nested path segments escape `.` as `\.` and `\` as `\\` (double these backslashes inside JavaScript string literals). `escapePath(segment)` and `parsePath(path)` are exported. Existing top-level literal names—including dots/backslashes—retain exact lookup priority. Conflicting canonical paths are rejected. Empty nested segments and `__proto__`, `prototype`, `constructor` segments are rejected. Malformed escapes are rejected by `parsePath`; no expression evaluation or prototype traversal occurs. Atomic values can contain plain data properties without becoming navigable paths. Type inference supports up to eight nested levels beneath a top-level nested container; deeper schemas require a shallower grouping boundary. `FieldName<V>`, `FieldValue<V, K>`, and `ValuesPatch<V>` are shared by framework packages.
+
+## Dynamic collections
+
+```ts
+import { collection, createValixa } from 'valixa';
+const form = createValixa({ addresses: collection({ city: ['', 'required'], street: [''] }) });
+const addresses = form.array('addresses');
+addresses.append({ city: '', street: '' });
+const row = addresses.items[0]!;
+row.form.setValue('city', 'Cairo');
+addresses.prepend({ city: 'Giza', street: '' });
+addresses.move(0, 1);
+// row.key and row.form remain stable across moves.
+```
+
+`collection(itemSchema, initialItems?)` opts into row management. Existing atomic arrays stay atomic. Each row has `{key, form}`: an opaque collection-local monotonic UI key and an independently typed `ValixaForm`. Current position is its array index; **an index is never its identity**. Bind controls to `row.form` and use `row.key` for reconciliation. Nested item schemas and nested collections are supported. `ValueInput<T>` strips schema-only metadata from input values.
+
+Operations are `append(item)`, `prepend(item)`, `insert(index, item)`, `remove(index)`, `move(from, to)`, `swap(a, b)`, `replace(items)`, `clear()` and `reset()`. Invalid indexes throw. Replace resets row lifetimes; move/swap preserve each surviving row's values, errors, initial values, touched/dirty state, graph, subscriptions and pending validation. Removed/replaced rows dispose, abort and can never commit into a later row. Core programmatic collection replacement through `setValues` also creates fresh row lifetimes; malformed collection patches are checked before changing form values.
+
+`items`, frozen `values`, `getSnapshot()` and `subscribe()` expose collection state. A collection owns its row stores; application view unmounts should unsubscribe, not dispose surviving rows. Parent reset restores the originally configured items with **fresh** keys, clears row state and cancels timers without restarting initial immediate-mode validation. Parent global disabled/readonly and locale changes propagate to rows, including future appended rows. Parent submit touches and validates all rows and submits their ordered nested values. Parent errors aggregate row messages with current `[index]` prefixes; nested projections preserve per-row error/touched/dirty maps. A collection-root `validateWhen: false` skips row validation and excludes row errors from parent validity/projections while retaining each row's independently owned error state. Ordinary row writes schedule their own field closure; parent automatic work targets other dependents and form constraints, avoiding duplicate row requests. Structural changes can validate the complete collection.
+
+Graph namespaces are explicit: item dependencies name fields **inside the row**. Parent dependencies name the collection root. Adding/removing rows creates/disposes their row graphs; reordering leaves graphs intact. Use parent `validateForm` (optionally `formDependsOn: ['addresses']`) for cross-row/aggregate constraints. Parent `form.setValue('addresses.0.city', ...)` is deliberately not an index-based field API; use `addresses.items[0].form.setValue('city', ...)`. No wildcard path expression or arbitrary index-identity rewriting is implemented. A parent complete validation becomes stale on a concurrent structural/value edit, even when surviving row work remains independently valid.
+
+React: `useValixaField(row.form, 'city')` or `useMuiField`. Vue: `useValixaField` / `useVuetifyField` in a keyed row component. Subscribe to parent state or the collection for structural rendering. Angular: `form.array('addresses')` delegates to core, then `bindValixa(row.form, {id, destroyRef})` supplies **borrowed** signal projections in the keyed row component. Borrowed-view destruction releases projections while parent collection ownership retains the row store.
+
+## Form validation and error precedence
+
+```ts
+const form = createValixa({ startDate: [''], endDate: [''] }, {
+  formDependsOn: ['startDate', 'endDate'],
+  validateForm: async (values, { signal }) => {
+    // Forward signal to any remote request.
+    return values.startDate > values.endDate
+      ? { endDate: 'End date must follow start date', $form: 'Review the date range' }
+      : {};
+  }
+});
+```
+
+The callback returns a field-path map of strings/string arrays; undefined entries are ignored. `$form` supplies form-wide strings in `state.formErrors`, unless `$form` is an actual schema field, in which case it retains normal field meaning. Unknown returned field names become an actionable form-wide validation failure. Exceptions become a generic structured form error without leaking exception contents. Only explicit field paths are accepted; errors inside collection rows belong to row stores. Use a collection-root form error for an aggregate constraint.
+
+Full validation/submit runs field and form validation concurrently against frozen values, including form validation when field rules fail. `validate(name)` runs only that field. Automatic form work is one independent request/timer per form, restricted by `formDependsOn`; omitted dependencies mean any value may affect it. A timeout applies to form work as well. Reset/disposal/obsolete values prevent late commits. Precedence is field messages before form-field messages. `setError` cancels active work and supersedes form-field messages on that target; the **next fresh explicit validation** may replace it, preserving existing retry semantics. Form-wide failures contribute to `valid`/`invalid` even when `errors` is empty; render `state.formErrors` in form-level UI.
+
+## Localization
+
+English is the default. `locale`, `fallbackLocale`, locale-keyed `labels`, and existing rule `messages` configure presentation. `setLocale(locale)` rerenders structured built-in/custom-false/exception/timeout messages without revalidation. `state.errorDetails` retains `code`, `field`, `label`, `param` and `source`; literal custom/server/form-returned messages additionally retain `message`. String validators and server errors are application literals and are not implicitly translated. `messages` overrides rule catalogs in every locale.
+
+```ts
+import { registerLocale } from 'valixa';
+registerLocale('fr', { messages: { required: '{label} est obligatoire.' }, labels: { email: 'Courriel' } });
+const form = createValixa({ email: ['', 'required'] }, {
+  locale: 'ar', fallbackLocale: 'en', labels: { ar: { email: 'البريد الإلكتروني' } }
+});
+await form.validate();
+form.state.errors.email; // ['البريد الإلكتروني مطلوب.']
+form.setLocale('fr');
+```
+
+Catalog fallback order is custom messages → selected locale → fallback locale → English. Label fallback follows selected/fallback locale overrides/catalogs and then the blueprint label. Catalog registration is process-wide configuration; the selected locale is owned by each form, not global user state. Register catalogs during application setup. Document direction is never changed. Applications choose `dir="rtl"`, logical CSS properties, component-library RTL/theme settings and translated literal messages themselves.
+
+## Verification and scope
+
+`pnpm test:advanced` runs focused core and representative framework tests; `pnpm test:performance` checks deterministic identity/notification contracts. The repository retains strict builds, all original tests, production browser flows and isolated installed-package consumers. `pnpm benchmark` retains its original workloads in `benchmarks/results.json`; `pnpm benchmark:compare` pairs preserved Phase 5 with current core and identical correctness assertions.
+
+Phase 5.1 structurally shares immutable branches and reuses unchanged snapshots. Pending/error/locale transitions retain `values` identity; unrelated nested branches, error arrays and field projections remain stable. External values are still copied before becoming owned state, including shallow-frozen application objects. Native cancellation signals are allocated lazily and retain existing abort/stale behavior. Genuinely redundant operations do not create new snapshots or callbacks, while effective field/pending transitions retain subscription notifications.
+
+Value-record copying, nested path projection and ordered collection operations can still cost O(form/collection size); active field subscribers require projection checks. Graph selectivity does not imply constant-time whole-form work. Profiling and retained-heap measurements are separate from end-to-end timings, and no cross-library speed claim is made. Auto Forms and DevTools UI are outside this phase.

package/API.md

@@ -0,0 +1,206 @@
+# Core public API
+
+All exports below come from `valixa`. Core performs no rendering and imports
+no framework or DOM APIs. Values must be acyclic plain objects, arrays or primitive
+data; class instances, dates, files, functions, and symbols are rejected as values.
+Use strings for dates until value normalization is implemented.
+
+## Definitions and inference
+
+`blueprint(input)` returns a reusable, deeply frozen `Blueprint<S>`. Its constructor
+also accepts the same input. `createValixa(inputOrBlueprint, options?)` returns a
+`ValixaForm<InferValues<S>>`. Each instance owns independent values and state.
+
+```ts
+import { blueprint, createValixa } from 'valixa';
+
+const signup = blueprint({
+  email: ['', 'required | email'],
+  age: { initial: 18, rules: ['minValue:18'], label: 'Age' },
+  password: ['', 'required | min:8'],
+  confirm: ['', 'required | same:password'],
+  username: {
+    initial: '',
+    rules: 'required',
+    validate: async (value: string, { signal, values, field }) => {
+      // Replace this with your availability check; forward signal to your API.
+      return value !== 'reserved' || 'Username is unavailable.';
+    }
+  }
+});
+const form = createValixa(signup, {
+  validateOn: 'submit',
+  messages: { required: '{label} cannot be empty.' }
+});
+```
+
+A field is `[initial, rules?]` or `{ initial, rules?, validate?, label?, dependsOn? }`.
+Explicit `nested(schema)` and `collection(itemSchema, initialItems?)` introduce
+addressable children and keyed row stores; existing object/array values remain atomic.
+See [the advanced guide](ADVANCED.md) for their typed grammar and lifecycle.
+`validate` accepts one callback or an array. Callbacks run sequentially within a
+field, concurrently across fields, after built-in rules pass. `true` or `undefined`
+passes; `false` uses the custom message template; a string becomes an error.
+Exceptions become generic validation errors without exposing exception contents.
+Custom validators should be pure and use `context.values` for cross-field reads.
+
+Top-level string, number and boolean literals widen to their primitive types.
+Annotate nullable or union initial values when necessary, e.g.
+`initial: null as string | null`. Exported `InferValues`, `DeepReadonly`,
+`FieldName`, `FieldInput`, `FieldDefinition`, `BlueprintInput`, `RuleInput`,
+`Validator`, `ValidationOutcome` and `ValidationContext` describe the boundary.
+Compiled blueprint metadata is readable but is not an extension point.
+
+## Rules
+
+`parseRules(string | readonly string[])` returns readonly `ParsedRule[]`.
+`RuleSyntaxError` identifies invalid syntax, unknown rules and invalid parameters.
+Definitions are checked eagerly, including missing `same` references.
+
+Grammar: `identifier (":" parameter)? ("|" identifier (":" parameter)?)*`.
+An empty expression means no rules. Arrays compose pipelines. There is no dynamic
+execution, quoted-string expression language or implicit rule registration.
+
+| Rule | Behavior |
+| --- | --- |
+| `required` | Reject null, undefined, empty string, empty array and false; accept zero |
+| `email` | Basic email shape; does not verify deliverability or full RFC grammar |
+| `url` | Platform URL parser, HTTP(S) protocol and nonempty hostname; no whitespace, host resolution or reachability check |
+| `min:n`, `max:n` | String length (UTF-16 code units) or array length; n is a nonnegative integer |
+| `minValue:n`, `maxValue:n` | Finite numeric values; no implicit string coercion |
+| `same:field` | `Object.is` comparison against another top-level field |
+
+Non-required rules skip null, undefined, empty strings and empty arrays. Required
+does not trim whitespace. Normalize values before writing them if needed. Pattern
+checks and custom named rules can be expressed as custom validators in this phase.
+
+`defaultMessages` exposes the immutable English message catalog.
+`options.messages` overrides templates by rule name, `custom`, or `exception`;
+`{label}` and `{param}` interpolate. Locale switching and Arabic catalogs are
+deferred. Arbitrary validator strings are displayed as text by future UI bindings,
+never HTML.
+
+## State and writes
+
+`form.state` and `form.getSnapshot()` expose the same deeply immutable
+`FormState<V>`. Snapshot identity is stable between transitions.
+
+| State | Meaning |
+| --- | --- |
+| `values`, `initialValues` | Current data and original immutable defaults |
+| `errors` | Sparse field-to-message-array map, no field values or exception text |
+| `touched` | Set explicitly, on blur via bindings, or for every field on submit |
+| `dirty`, `pristine` | Deep comparison with original defaults; revert makes pristine |
+| `valid`, `invalid` | Absence/presence of known errors; initial valid is not proof of validation |
+| `validating` | One or more field/form/row requests are running |
+| `pending` | Running work or debounced automatic validation is scheduled |
+| `formErrors`, `errorDetails`, `locale` | Form-wide messages, structured metadata and selected locale |
+| `submitting` | Submission owns validation or an active handler |
+| `submitted` | Most recent submission succeeded; false when a new attempt starts |
+| `submitCount` | Accepted attempts, including invalid or failed attempts |
+| `disabled`, `readonly` | Global flags available to bindings |
+
+- `setValue(name, value)` writes a typed field.
+- `setValues(partial)` validates field names and copies data before applying one
+  batch. Equal writes do nothing. Changes invalidate the changed/dependent closure;
+  custom validators with unknown dependencies retain conservative invalidation.
+- `setTouched(name, touched = true)` changes touched state.
+- `setError(name, messageOrMessages)` applies server/application errors.
+- `clearErrors(name?)` clears one field or all fields. Error writes invalidate
+  pending validation, protecting server errors from older responses.
+- `setDisabled(boolean)`, `setReadonly(boolean)` update global metadata. Programmatic
+  writes and explicit validation remain allowed. Disabled forms cannot submit.
+  Fields remain in data. Declarative behaviors can add per-field state.
+- `reset()` restores original defaults, clears errors/touched/submitted/count and
+  aborts validation/submission. Flags and subscriptions remain.
+- `dispose()` is idempotent, aborts work and clears subscriptions. Subsequent writes,
+  subscriptions, validation and submission reject. Final snapshots remain readable.
+
+Atomic nested objects/arrays are copied/frozen as before. Explicit nested schemas
+expose leaf paths; dynamic collections expose independently owned row stores.
+
+## Subscriptions
+
+`subscribe(listener)` returns an idempotent unsubscribe function and fires for
+every state transition. `subscribeField(name, listener)` fires only when that
+field's `FieldState` changes. Neither invokes its callback immediately. Call
+`getSnapshot()` / `getFieldState(name)` to read initial state and read again in the
+callback. `getFieldState` includes `value`, `initialValue`, `errors`, `touched`,
+`dirty`, `validating`, `pending`, `disabled`, `readonly`, `visible`, `required`
+and `validationEnabled`.
+
+Unchanged field snapshots retain identity. Notifications are synchronous, with
+`setValues` batching multiple writes; validation has separate pending/result
+transitions. Listeners must not throw. Unsubscribe on consumer teardown, then
+dispose the form when its owner is destroyed. React hooks live in `valixa-react`;
+the core package itself has no framework integration dependencies.
+
+## Validation and cancellation
+
+`await validate(name?)` returns `ValidationResult<V>`:
+`{ valid, errors, stale }`. With no name it validates all fields; with a name it
+updates only that field's errors, while `valid` still reflects all known errors.
+Unvalidated fields are not implicitly valid. No touched state changes here.
+
+The default remains manual/submit. Legacy `validateOn: 'change'` validates the
+changed/dependent closure; `'blur'` validates a field when touched. The additive
+`validation` option supports modes, per-field debounce and running-request timeout.
+
+A newer request supersedes previous work for its target fields; independent field
+requests coexist. Value changes invalidate their dependency closure. Reset, error
+operations and disposal cancel owned work. Every callback receives an `AbortSignal`;
+ignored cancellation cannot allow stale commits. A stale result has `valid: false,
+stale: true`. Full validate/submit is fresh and also runs optional form validation.
+See [scheduling, behaviors, nested schemas, collections and localization](ADVANCED.md)
+for complete semantics, error precedence and explicit limitations.
+
+## Submission
+
+`await submit(handler)` executes immediately. `handleSubmit(handler)` returns an
+event callback accepting an optional structural `{ preventDefault() }` event.
+This avoids overloading an immediate Promise API with callback-factory behavior.
+
+`handler(values, { signal })` receives an isolated mutable copy of validated data.
+`SubmitResult<V, R>` is a discriminated union:
+
+- `{ status: 'success', data: R }`: handler resolved.
+- `{ status: 'invalid', errors }`: validation failed; handler was not called.
+- `{ status: 'busy' }`: another submission owns the form.
+- `{ status: 'stale' }`: data or validation changed before handler execution.
+- `{ status: 'cancelled' }`: disabled form or submission was cancelled.
+
+Handler failures reject the Promise; `submitting` clears in `finally`. The caller
+owns error UI. `cancelSubmit()` signals cancellation and invalidates validation.
+Reset and disposal also cancel. Abort is cooperative: a callback ignoring its
+signal may continue its external side effects. The submission lock remains until
+the pending callback settles, preventing overlapping requests.
+
+Edits during the handler are allowed; it keeps the already-validated data copy.
+Success does not reset automatically. Call `reset()` after success if desired.
+Retry validates again, replacing previous server errors. There is no HTTP-client
+dependency or automatic 422 payload guesser. Map your API's known payload explicitly:
+
+```ts
+try {
+  await form.submit(async data => {
+    // const response = await yourApi(data);
+    // if (response.status === 422) {
+    //   form.setError('email', response.errors.email);
+    //   throw new Error('Server rejected submission');
+    // }
+  });
+} catch (error) {
+  // Show a request-level message; field errors remain in form.state.errors.
+}
+```
+
+Other exported types: `Errors`, `FormState`, `FieldState`, `ValidationResult`,
+`FormOptions`, `SubmitHandler`, `SubmitContext`, `SubmitResult`.
+
+## Readonly descriptions and optional lifecycle observation
+
+`form.describe()` returns a lazily cached value-free blueprint description (paths, labels, parsed rules, validator counts, child collection schemas). `form.getBehaviorStates()` returns readonly configured behavior states without creating all field projections.
+
+`form.observeEvents(listener, {types?})` returns an unsubscribe function. Immutable events contain per-form sequence/type and optional field/request/reason/index/to/key metadata; no values, messages or handler output. Observer exceptions are isolated. Actual cancelled timers/jobs emit cancellation; independent async work keeps actual resolution order. Invalid validation emits failed then completed; cancelled runs do not commit completion. Root disposal emits then clears observers. Use listeners for diagnostic reads, since reentrant writes can interleave ordinary operations. No event objects are allocated without an interested listener.
+
+Optional valixa-auto and valixa-devtools consume these contracts without introducing framework/DOM imports into core. See the repository Phase 6 guide for full event ordering and privacy.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Valixa contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,29 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# valixa
+
+Framework-independent form state, validation, subscriptions and submission.
+ESM and TypeScript declarations, with no runtime dependencies.
+
+```js
+import { createValixa } from 'valixa';
+
+const form = createValixa({ email: ['', 'required | email'] });
+form.setValue('email', 'user@example.com');
+const result = await form.validate();
+if (result.valid) await form.submit(async data => data.email);
+form.dispose();
+```
+
+Core API: `blueprint`, `createValixa`, `nested`, `collection`, `registerLocale`, `parseRules`, `RuleSyntaxError`,
+`defaultMessages`, `Blueprint`, `ValixaForm`, plus public TypeScript contracts.
+Use `form.state` to read immutable snapshots, `subscribe` / `subscribeField` to
+observe them, and `handleSubmit` for an event callback.
+
+Supported rules: required, email, url, min/max length, minValue/maxValue, same.
+Custom and asynchronous validators are supported with abort signals and stale-result
+protection. Values are acyclic plain data. Existing object/array fields stay atomic;
+explicit `nested` and `collection` constructors opt into typed paths and stable rows.
+Dependency graphs, field scheduling, conditional behaviors, form validation and
+English/Arabic localization are included. Framework bindings remain separate packages.
+See [API.md](API.md) and the [advanced guide](ADVANCED.md) for semantics and examples.
+
+MIT license. This initial version has not been published.

package/dist/behaviors.d.ts

@@ -0,0 +1,20 @@
+import type { FieldBehavior } from './types.js';
+export interface BehaviorState {
+    readonly visible: boolean;
+    readonly enabled: boolean;
+    readonly required: boolean;
+    readonly readonly: boolean;
+    readonly validate: boolean;
+    readonly reset: boolean;
+}
+export declare class BehaviorEngine {
+    private readonly config;
+    private readonly inflate;
+    private states;
+    readonly configured: boolean;
+    constructor(config: Readonly<Record<string, FieldBehavior>>, names: readonly string[], inflate?: (flat: Record<string, unknown>) => Record<string, unknown>);
+    get(name: string): BehaviorState | undefined;
+    /** Evaluate on a draft; commit only after reset transitions converge. */
+    evaluate<V extends Record<string, unknown>>(input: V, initial: V, changed?: ReadonlySet<string>, reset?: boolean): V;
+}
+//# sourceMappingURL=behaviors.d.ts.map

package/dist/behaviors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"behaviors.d.ts","sourceRoot":"","sources":["../src/behaviors.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,MAAM,WAAW,aAAa;IAAG,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE;AACpM,qBAAa,cAAc;IAGb,OAAO,CAAC,QAAQ,CAAC,MAAM;IAAqE,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFhI,OAAO,CAAC,MAAM,CAAoC;IAClD,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;gBACA,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,EAAmB,OAAO,GAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAkB;IAO7M,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAC5C,yEAAyE;IACzE,QAAQ,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,EAAE,KAAK,UAAQ,GAAG,CAAC;CAqBnH"}

package/dist/behaviors.js

@@ -0,0 +1,50 @@
+import { copy, equal, freeze } from './data.js';
+export class BehaviorEngine {
+    config;
+    inflate;
+    states = new Map();
+    configured;
+    constructor(config, names, inflate = value => value) {
+        this.config = config;
+        this.inflate = inflate;
+        this.configured = Object.keys(config).length > 0;
+        for (const [name, behavior] of Object.entries(config)) {
+            if (!names.includes(name))
+                throw new TypeError(`Behavior references unknown field ${name}`);
+            for (const dependency of behavior.dependsOn ?? [])
+                if (!names.includes(dependency))
+                    throw new TypeError(`Behavior ${name} depends on unknown field ${dependency}`);
+        }
+    }
+    get(name) { return this.states.get(name); }
+    /** Evaluate on a draft; commit only after reset transitions converge. */
+    evaluate(input, initial, changed, reset = false) {
+        if (!this.configured)
+            return input;
+        const draft = { ...input }, next = reset ? new Map() : new Map(this.states);
+        let affected = changed;
+        for (let pass = 0; pass <= Object.keys(this.config).length + 1; pass++) {
+            const context = { values: freeze(this.inflate(draft)) };
+            const resets = [];
+            for (const [name, behavior] of Object.entries(this.config)) {
+                if (affected && behavior.dependsOn !== undefined && !behavior.dependsOn.some(dependency => affected.has(dependency)) && next.has(name))
+                    continue;
+                const state = { visible: behavior.visibleWhen?.(context) ?? true, enabled: behavior.enabledWhen?.(context) ?? true,
+                    required: behavior.requiredWhen?.(context) ?? false, readonly: behavior.readonlyWhen?.(context) ?? false,
+                    validate: behavior.validateWhen?.(context) ?? true, reset: behavior.resetWhen?.(context) ?? false };
+                if (state.reset && !next.get(name)?.reset && !equal(draft[name], initial[name]))
+                    resets.push(name);
+                next.set(name, Object.freeze(state));
+            }
+            if (!resets.length) {
+                this.states = next;
+                return draft;
+            }
+            for (const name of resets)
+                draft[name] = copy(initial[name]);
+            affected = new Set(resets);
+        }
+        throw new TypeError('Conditional reset behaviors did not converge; remove cyclic resetWhen transitions');
+    }
+}
+//# sourceMappingURL=behaviors.js.map

package/dist/behaviors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"behaviors.js","sourceRoot":"","sources":["../src/behaviors.ts"],"names":[],"mappings":"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"}

package/dist/blueprint.d.ts

@@ -0,0 +1,33 @@
+import { DependencyGraph } from './graph.js';
+import type { ParsedRule } from './rules.js';
+import type { BlueprintInput, CollectionSchema, FormDescription, InferValues, NestedSchema, Validator, ValueInput } from './types.js';
+export interface CompiledField {
+    readonly initial: unknown;
+    readonly label: string;
+    readonly rules: readonly ParsedRule[];
+    readonly validators: readonly Validator[];
+    readonly dependsOn?: readonly string[];
+}
+/** Immutable reusable definition. Each createValixa call owns independent state. */
+export declare class Blueprint<S extends BlueprintInput> {
+    readonly __values: InferValues<S>;
+    readonly fields: Readonly<Record<string, CompiledField>>;
+    readonly graph: DependencyGraph;
+    readonly paths: Readonly<Record<string, readonly string[]>>;
+    readonly collections: Readonly<Record<string, Blueprint<BlueprintInput>>>;
+    readonly flat: boolean;
+    /** Owned frozen defaults can be shared across independent copy-on-write form instances. */
+    readonly initialValues: Readonly<Record<string, unknown>>;
+    constructor(input: S);
+    get description(): FormDescription;
+    inflate(flat: Readonly<Record<string, unknown>>): Record<string, unknown>;
+    /** Internal immutable projection: leaves are already owned and deeply frozen. */
+    project(flat: Readonly<Record<string, unknown>>, previous?: Readonly<Record<string, unknown>>): Record<string, unknown>;
+    /** Validate collection replacements before allocating row lifetimes or mutating a form. */
+    assertCollections(flat: Readonly<Record<string, unknown>>): void;
+    flattenPatch(patch: Readonly<Record<string, unknown>>): Record<string, unknown>;
+}
+export declare function blueprint<const S extends BlueprintInput>(input: S): Blueprint<S>;
+export declare function nested<const S extends BlueprintInput>(schema: S): NestedSchema<S>;
+export declare function collection<const S extends BlueprintInput>(schema: S, initial?: readonly ValueInput<InferValues<S>>[]): CollectionSchema<S>;
+//# sourceMappingURL=blueprint.d.ts.map

package/dist/blueprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blueprint.d.ts","sourceRoot":"","sources":["../src/blueprint.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE7C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAmB,eAAe,EAAE,WAAW,EAAE,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAKvJ,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;IACtC,QAAQ,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,CAAC;IAC1C,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AACD,oFAAoF;AACpF,qBAAa,SAAS,CAAC,CAAC,SAAS,cAAc;IAC7C,SAAiB,QAAQ,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC;IACzD,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;IAC5D,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;IAC1E,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,2FAA2F;IAC3F,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;gBAC9C,KAAK,EAAE,CAAC;IAoCpB,IAAI,WAAW,IAAI,eAAe,CAOjC;IACD,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAQzE,iFAAiF;IACjF,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAQvH,2FAA2F;IAC3F,iBAAiB,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI;IAYhE,YAAY,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAehF;AACD,wBAAgB,SAAS,CAAC,KAAK,CAAC,CAAC,SAAS,cAAc,EAAE,KAAK,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAAiC;AAClH,wBAAgB,MAAM,CAAC,KAAK,CAAC,CAAC,SAAS,cAAc,EAAE,MAAM,EAAE,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAA6D;AAC/I,wBAAgB,UAAU,CAAC,KAAK,CAAC,CAAC,SAAS,cAAc,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,GAAE,SAAS,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAAO,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAA0E"}