@zvenigora/ng-eval-forms 0.1.0 → 0.2.0

package/README.md

@@ -1,7 +1,7 @@
 # @zvenigora/ng-eval-forms
 
-Angular form field properties — `visible` and `text` — driven by **string** expressions
-resolved at runtime.
+Angular form field properties — `visible` and `text`, plus `disabled` at the `/signals` entry
+point — driven by **string** expressions resolved at runtime.
 
 ```ts
 { name: 'state', visible: "country === 'US'" }
@@ -45,36 +45,54 @@ npm install @zvenigora/ng-eval-forms @zvenigora/ng-eval-signals @zvenigora/ng-ev
 
 ## Entry points
 
-| Import | Contains |
-| :--- | :--- |
-| `@zvenigora/ng-eval-forms` | The shared core — context composition and the coercion and error-policy rules every adapter uses. Imports nothing from `@angular/core` or `@angular/forms`. |
-| `@zvenigora/ng-eval-forms/reactive` | The Angular Reactive Forms adapter — `FormGroup` / `FormControl`. **This is the entry point you want.** |
+| Import | Contains | Requires |
+| :--- | :--- | :--- |
+| `@zvenigora/ng-eval-forms` | The shared core — context composition and the coercion and error-policy rules every adapter uses. Imports nothing from `@angular/core` or `@angular/forms`. | — |
+| `@zvenigora/ng-eval-forms/reactive` | The Angular **Reactive Forms** adapter — `FormGroup` / `FormControl`. `visible` and `text`. | Angular 19+ |
+| `@zvenigora/ng-eval-forms/signals` | The Angular **[Signal Forms](https://angular.dev/guide/forms/signals)** adapter — `schema()` / `form()`. `visible`, `text` and `disabled`. | **Angular 22+** |
 
-A `/signals` entry point for Angular's Signal Forms is designed but not built; see
-[the Phase 4 plan](https://github.com/zvenigora/ng-eval/blob/master/docs/forms/phase-4-plan.md)
-§ 9.
+**Pick the adapter that matches the forms API you already use.** The two are independent — the
+same expression string means the same thing at both — and neither imports the other. The design
+and the measurements behind `/signals` are in
+[the Phase 6 plan](https://github.com/zvenigora/ng-eval/blob/master/docs/forms/phase-6-plan.md).
 
 ## Versions
 
-The package declares **one** peer range, at the floor:
+`peerDependencies` are declared per **package**, not per entry point, so the manifest holds one
+set of ranges covering both adapters:
 
 ```json
 "peerDependencies": {
   "@angular/core": ">=19.0.0",
   "@angular/forms": ">=19.0.0",
   "rxjs": "^7.8.0",
+  "acorn-walk": "^8.3.0",
   "@zvenigora/ng-eval-core": "^0.3.0",
   "@zvenigora/ng-eval-signals": "^0.1.0"
 }
 ```
 
-`peerDependencies` are declared per **package**, not per entry point, so a narrower range
-for a single entry point is not expressible. `/reactive` — everything this release ships —
-works from Angular 19. When `/signals` arrives it will require **Angular 22 or later**, and
-an older consumer importing it gets `Cannot find module '@angular/forms/signals'` from
-Angular's own `exports` map rather than anything this library declares.
+**The Angular range is at the floor, and the floor is `/reactive`'s.** `/signals` requires
+**Angular 22 or later** — that is when `@angular/forms/signals` ships — and the manifest cannot
+say so: narrowing it to `>=22.0.0` would break every Reactive Forms consumer on 19–21 to add a
+diagnostic for an entry point they do not import. An older consumer importing `/signals` gets
+`Cannot find module '@angular/forms/signals'` from Angular's own `exports` map rather than
+anything this library declares.
+
+**`acorn-walk` is new in 0.2.0 and imposes no new install.** `/signals` walks the parsed
+expression with it. A consumer of this package already peer-depends on
+`@zvenigora/ng-eval-core`, whose own peers include `acorn-walk ^8.3.0`, so npm 7+ has already
+placed it; it is declared here because importing it undeclared resolves today by accident of
+hoisting and would not resolve at all under pnpm's isolated layout. `acorn` itself is
+deliberately **not** declared — this package imports no `acorn` symbol, and `acorn-walk`
+depends on it directly.
 
-## Quick start
+## Quick start — Reactive Forms (`/reactive`)
+
+Everything from here to [Lifetime](#lifetime) is the `/reactive` adapter, except for three
+sections that cover both: [How it fits together](#how-it-fits-together), [Coercion](#coercion)
+and [When a rule fails](#when-a-rule-fails). Signal Forms has
+[its own section](#signal-forms--signals) below.
 
 ```ts
 import { Injectable, Injector, OnDestroy, inject } from '@angular/core';
@@ -142,6 +160,11 @@ worked example of a whole form is in
 | `createFieldContext(formSource, fieldSource, options?)` | core | Composes one `EvalContext` out of a form-wide and a field-local source. |
 | `toVisible(value)` / `toText(value)` | core | The two coercions, exported so an adapter or a test can apply the same rule. |
 | `ExpressionErrorPolicy` | core | `'throw' \| 'undefined' \| ((error) => unknown)`. |
+| `applyErrorPolicy(run, policy?)` | core | Runs `run` under a policy, **new in 0.2.0**. Rethrows a `SignalContextWriteError` whatever the policy says — see [When a rule fails](#when-a-rule-fails). Exported so an adapter applies the rule rather than reimplementing it. |
+| `createExpressionRules(model, options?)` | `/signals` | The primary API. Binds one model signal and returns `evalVisible` / `evalText` / `evalDisabled`. |
+| `ExpressionRules` | `/signals` | The three registrars, each `(path, expression, options?) => void`. |
+| `ExpressionRuleOptions` | `/signals` | `{ eval?: EvalOptions; onError?: ExpressionErrorPolicy }`, accepted by the factory and per registration. |
+| `TEXT` | `/signals` | The metadata key `evalText` writes through and `field().metadata(TEXT)` reads back. |
 
 `FieldProperties` members are `EvalSignal`, not plain `Signal`, and both extra members
 matter here: `invalidate()` is the escape hatch described under
@@ -193,6 +216,41 @@ the diff runs in a subscriber, where a throw is reported out of band and far fro
 `addControl` that caused it — and it could not undo that call anyway. Validate a control
 set you assemble dynamically, or re-bind.
 
+### Expressions are not validated
+
+**No check in the table above inspects an expression.** Two of the four are on **names** — the
+schema's field names and the group's control names; the other two are on a rule's *type* and a
+control's *class*. `bindFieldProperties` compiles each expression, so one that does not *parse*
+throws; nothing inspects what a parsed expression **names**.
+
+**So `visible: "constructor"` binds here without complaint, and renders the field:**
+
+```ts
+const form = new FormGroup({ country: new FormControl('CA') });
+
+const binding = bindFieldProperties(
+  [{ name: 'city', visible: 'constructor' }],
+  form,
+  { injector }
+);
+
+binding.fields['city'].visible?.();   // => true — against a form with no `city` and no
+                                      //    `constructor`, with nothing logged
+```
+
+The identifier resolves off `Object.prototype` to a *function*, a function is truthy, and
+truthiness means visible. It is the same failure the field-name check above prevents, reached
+through the expression instead of through the name.
+
+**`/signals` rejects this and `/reactive` does not**, so one authored rule string behaves two
+ways: it throws under `@zvenigora/ng-eval-forms/signals` and silently renders a data-less field
+here. The asymmetry is deliberate rather than an oversight — adding the check to `/reactive`
+would make an expression that registers today start throwing, which is a breaking change to a
+released entry point, and it is logged as a question for a later major in the
+[roadmap](https://github.com/zvenigora/ng-eval/blob/master/ROADMAP.md). Until it is answered:
+if your model keys or expressions can come from a server or a form-builder UI, prefer
+`/signals`, or screen the expressions yourself.
+
 ## What an expression can name
 
 **The values of the form's controls, by control name.** Every control is mirrored,
@@ -284,6 +342,16 @@ Two things are **not** routed through it:
   dataset. Swallowing it under the default would hand you a silent blank for a syntax bug
   in the rule itself.
 
+  **That guarantee has one boundary, and it is stated here because the guarantee is.** It
+  holds for an assignment the expression makes directly. An assignment **nested inside a
+  call** — `[1].map(x => (country = 'CA'))` — is caught by the evaluator's own call wrapper
+  and re-raised as a plain `Error`, which loses the class the bypass matches on. It is then
+  routed by `onError` like any other failure, so under the default you get a blank field with
+  nothing in the console. It is a misuse inside a misuse — a rule author writing an assignment
+  writes `country = 'CA'`, not one buried in a `.map` callback — but it is the one shape where
+  the mechanism cannot see what it is for. The re-wrap belongs to
+  `@zvenigora/ng-eval-core` and cannot be fixed from this side.
+
 ## Reactivity, and its two holes
 
 A property recomputes when a control it named emits on `valueChanges`. The mirror
@@ -394,16 +462,226 @@ throws, with an error naming `toSignal` and nothing naming this library. If you
 one would silently pick up the ambient injection context when there is one, and teardown
 would then run at a time that varied with where the call happened to sit.
 
+## Signal Forms — `/signals`
+
+**Requires Angular 22 or later.** Import from `@zvenigora/ng-eval-forms/signals`.
+
+One factory, bound to one model signal, returning three registrars you call from inside a
+`schema()` body beside Angular's own rules:
+
+```ts
+import { signal } from '@angular/core';
+import { form, schema } from '@angular/forms/signals';
+import { TEXT, createExpressionRules } from '@zvenigora/ng-eval-forms/signals';
+
+interface Order {
+  country: string;
+  state: string;
+  zip: string;
+  orderTotal: number;
+}
+
+const model = signal<Order>({ country: 'CA', state: '', zip: '', orderTotal: 80 });
+
+const rules = createExpressionRules(model);
+
+const orderSchema = schema<Order>((p) => {
+  rules.evalVisible(p.state, "country === 'US'");
+  rules.evalText(p.zip, "orderTotal >= 100 ? 'Free shipping' : 'Standard'");
+  rules.evalDisabled(p.zip, "country !== 'US'", { reason: 'ZIP is US-only' });
+});
+
+const f = form(model, orderSchema);
+```
+
+There is no `FormBinding` here and nothing to look a field up in: the rules register through
+Angular's own primitives, so you read them back off Angular's field state.
+
+```ts
+f.state().hidden();                                // => true
+f.zip().metadata(TEXT)?.();                        // => 'Standard'
+f.zip().disabled();                                // => true
+f.zip().disabledReasons().map((r) => r.message);   // => ['ZIP is US-only']
+
+model.set({ country: 'US', state: '', zip: '', orderTotal: 120 });
+
+f.state().hidden();                                // => false
+f.zip().metadata(TEXT)?.();                        // => 'Free shipping'
+f.zip().disabled();                                // => false
+```
+
+Recompute is Angular's own dependency tracking, per key: a rule that named `country`
+re-evaluates when `country` changes and not when any other key does.
+
+### The three registrars, and their polarity
+
+| Registrar | Registers | A **true** expression means |
+| :--- | :--- | :--- |
+| `evalVisible(path, expression, options?)` | Angular's `hidden`, **inverted** | the field is **visible** |
+| `evalText(path, expression, options?)` | `metadata(path, TEXT, …)` | — |
+| `evalDisabled(path, expression, options?)` | Angular's `disabled`, uninverted | the field is **disabled** |
+
+**`evalVisible` is named after the property, not after Angular's rule, and the inversion lives
+inside the library.** That is the whole reason it exists rather than a thin `hidden` wrapper:
+the same rule string means the same thing at both entry points, so `country === 'US'` is "show
+it when the country is US" under `/reactive`'s `visible` and under `evalVisible` alike, with no
+consumer's expression carrying a `!`. `evalDisabled` keeps Angular's polarity instead, because
+`/reactive` ships no `disabled` — there is no second entry point for its expressions to agree
+with, and `true` disabling is what an author expects.
+
+**`reason` is a static string, never expression-derived.** Angular's `disabled` config is a
+single field: `when` returns `boolean | string`, and a truthy string is *both* "disabled" and
+"the reason". A registrar forwarding the expression's value raw would disable a field on the
+string `'false'` **with the reason `"false"`** — [Coercion](#coercion)'s truthiness trap in a
+new shape. Keeping the expression boolean and sourcing the reason from the registration is what
+kills it. A *dynamic* reason is out of scope for the same reason.
+
+### Lifetime — there is nothing to destroy
+
+Unlike [`/reactive`](#lifetime), this entry point creates no `EvalSignal`, registers nothing
+with a `DestroyRef`, and has **no `destroy()`**. Angular owns the field tree's lifetime and the
+rules die with the schema. What is retained, on two different clocks: **per factory**, one
+private memo of per-key `computed`s, bounded by the union of keys the rules name — it lives as
+long as the `createExpressionRules` value does, which for a factory built at module scope is
+longer than any one form; and **per rule per `form()`**, one evaluation context and one compiled
+expression, garbage when that form is.
+
+### Reuse a schema *function*, not a schema *value*
+
+The registrars close over the **factory's** model, and a factory is bound to one model. So the
+supported way to share rules across forms is a function of the rules, called once per form:
+
+```ts
+import { ExpressionRules } from '@zvenigora/ng-eval-forms/signals';
+
+const makeSchema = (rules: ExpressionRules) =>
+  schema<Order>((p) => {
+    rules.evalVisible(p.state, "country === 'US'");
+  });
+
+const modelA = signal<Order>({ country: 'US', state: '', zip: '', orderTotal: 0 });
+const modelB = signal<Order>({ country: 'CA', state: '', zip: '', orderTotal: 0 });
+
+const fA = form(modelA, makeSchema(createExpressionRules(modelA)));
+const fB = form(modelB, makeSchema(createExpressionRules(modelB)));
+```
+
+**Sharing a schema *value* across models compiles, runs, and is wrong.** Angular re-invokes the
+schema body once per `form()`, so each form does mint its own contexts — but every rule inside
+them still reads the model the *factory* was given. A schema built from
+`createExpressionRules(modelA)` and passed to `form(modelB, …)` yields a fully functional form B
+rendering against form A's data, silently, with no error anywhere.
+
+### Prototype-shadowed identifiers are rejected
+
+An expression naming a member of `Object.prototype` — `constructor`, `toString`, `valueOf`,
+`hasOwnProperty`, `isPrototypeOf`, `propertyIsEnumerable`, `toLocaleString`, and the five
+`__proto__`-style accessors `Object.getOwnPropertyNames(Object.prototype)` also returns —
+**throws**, naming the expression and the identifier:
+
+```ts
+const bad = schema<Order>((p) => {
+  rules.evalVisible(p.state, 'constructor');
+});
+
+form(model, bad);   // throws: identifier 'constructor' is a member of Object.prototype …
+```
+
+Without the check the identifier resolves off the prototype to a *function*, a function is
+truthy, and `evalVisible` would render precisely the field that has no data — with nothing
+logged. The fix is to rename the model key.
+
+**The throw arrives from `form()`, not from `schema()`.** The schema body is what registers, and
+Angular invokes that body once per `form()` — so building the schema is silent and every
+`form()` made from it throws. `/reactive` makes its (different, name-based) check at the
+`bindFieldProperties(…)` call instead, so **the two entry points reject at different times**.
+
+Three bounds on the check, none of them obvious from the paragraph above:
+
+- **It is the expression that is checked, never the model.** A model key named off
+  `Object.prototype` that no expression names stays unreadable and unreported. That is
+  harmless — a key is only ever read because some expression names it — but it is not covered,
+  and it is the one thing `/reactive`'s control-name check catches that this does not.
+- **A *member* expression is not this check's business.** `user.constructor` goes to
+  `@zvenigora/ng-eval-core`'s prototype-pollution guard, under the rules documented there.
+- **It over-rejects a name the expression *binds* itself**, deliberately.
+  `'[1].map(valueOf => valueOf)'` throws, even though an arrow's own parameter shadows the
+  prototype and would have resolved correctly. A scope-aware guard would be a second copy of
+  the evaluator's frame logic, and one that drifted out of step would fail by
+  *under*-rejecting — a silent wrong answer in place of a rename. Rename the parameter.
+  (`'[1].map(valueOf => 1)'` registers: a binding that is never referenced is not visited.)
+
+**`/reactive` makes no equivalent check on expressions** — see
+[Expressions are not validated](#expressions-are-not-validated).
+
+### `caseInsensitive` is in practice a *factory* option
+
+`ExpressionRuleOptions` — `{ eval?, onError? }` — is accepted by the factory and by each
+registration, and **registration wins per key**: a registration supplying only `onError` keeps
+the factory's `eval`, and vice versa. Neither key is deep-merged.
+
+That resolution is exact for `onError` and **only partial for `eval.caseInsensitive`**:
+
+```ts
+interface Profile {
+  country: string;
+  address: { name: string };
+  label: string;
+}
+
+const profile = signal<Profile>({ country: 'US', address: { name: 'HQ' }, label: '' });
+
+const rules = createExpressionRules(profile);        // caseInsensitive off at the factory
+
+const profileSchema = schema<Profile>((p) => {
+  rules.evalText(p.label, 'Country + address.NAME', {
+    eval: { caseInsensitive: true },                 // on for this registration
+  });
+});
+
+form(profile, profileSchema).label().metadata(TEXT)?.();
+// => 'undefinedHQ'
+//    address.NAME  resolved  — a *property* name, corrected by the walk
+//    Country       did not   — an *identifier* key, still on the factory's setting
+```
+
+The walk is the only one of the three places the option must reach that a per-registration
+value gets to. The other two — the factory's key memo, and the evaluation context every rule is
+given — are built from the options handed to `createExpressionRules`, fixed at factory time; the
+context is minted per rule, but always from that same fixed setting, so a registration cannot
+move it. One expression then ends up obeying two casing rules. **Set `caseInsensitive` on the
+factory** unless that is precisely what you want.
+
+### Two things that are not available here
+
+Neither is about resolution. Every key an expression can name resolves, at any spelling
+`caseInsensitive` allows, whether or not the model held it when the form was built — there is
+no `invalidate()` at this entry point and nothing to call it on.
+
+- **The nested-signal diagnostic does not reach `/signals`.** A model property holding a signal
+  — `{ user: { name: signal('a') } }` — is read un-called by the member visitor, and
+  `@zvenigora/ng-eval-signals`' dev-mode warning never fires here. That shape is precisely what
+  the upstream scan reports, so the check is neither switched off nor blind to it: it runs over
+  the *source record* a context is built from, and this adapter hands it an empty one. Every
+  model key resolves through a lookup instead, where nothing scans. Widening the scan would not
+  recover it.
+- **The form's key set is not enumerable from upstream**, because the memo is deliberately
+  private. That is the fix rather than the cost: an enumerable record is exactly what froze a
+  case-insensitively matched key to its first spelling for the life of the form. It is the
+  counterpart to [`/reactive`'s key-set caveat](#the-key-set-is-not-reactive) and the milder
+  one — nothing here goes stale.
+
 ## What is not here
 
 Deferred deliberately, each additive when it arrives:
 
-- **`disabled`.** Applying it means calling `control.disable()`, which is three problems at
-  once: it is a write back into the form rather than derived state; it emits on
-  `valueChanges` by default, so a rule naming its own field re-enters its own input and
-  whether that converges depends on the expression; and it removes the value from the
-  parent's aggregate. Under Signal Forms none of the three exists, which is why `disabled`
-  is a better fit for the future `/signals` entry point than for this one.
+- **`disabled` at `/reactive`.** It ships at [`/signals`](#the-three-registrars-and-their-polarity)
+  and not here, and the asymmetry is the point rather than a gap. Applying it to a
+  `FormControl` means calling `control.disable()`, which is three problems at once: it is a
+  write back into the form rather than derived state; it emits on `valueChanges` by default, so
+  a rule naming its own field re-enters its own input and whether that converges depends on the
+  expression; and it removes the value from the parent's aggregate. Under Signal Forms
+  `disabled` is a schema rule over derived state and none of the three exists.
 - **`required` and validators**, which affect form validity rather than presentation.
 - **Form state keys**, `FormArray` and nested `FormGroup`, and field-local keys — see
   [What an expression can name](#what-an-expression-can-name).
@@ -419,6 +697,12 @@ npx nx test eval-forms
 npx nx run eval-forms:build:production
 ```
 
-`readme-examples.spec.ts` executes the runnable examples in this file and in the worked
-example, so a documented example that stops working fails the suite rather than shipping.
-The template and manifest blocks are not executable and are not covered.
+Two `readme-examples.spec.ts` files execute the runnable examples in this document, and the
+split is not quite by folder: the one under `reactive/src/lib/` covers the `/reactive` blocks,
+the shared core's two [Coercion](#coercion) blocks and the
+[worked example](https://github.com/zvenigora/ng-eval/blob/master/docs/forms/worked-example.md);
+the one under `signals/src/lib/` covers the `/signals` blocks **plus the one `/reactive` block
+whose subject is the difference between the two entry points**, because that claim is a pair and
+splitting it would let either half drift alone. So a documented example that stops working fails
+the suite rather than shipping. The template and manifest blocks are not executable and are not
+covered.