@zvenigora/ng-eval-forms 0.1.0

package/fesm2022/zvenigora-ng-eval-forms.mjs

@@ -0,0 +1,132 @@
+import { createSignalContext } from '@zvenigora/ng-eval-signals';
+
+/**
+ * Coerces an expression's result to the boolean a `visible` rule needs.
+ *
+ * **JavaScript truthiness, and nothing cleverer** (plan S 3.6). A rule author
+ * writing `visible: "country === 'US'"` gets a boolean already; the coercion
+ * exists for the ones who write `visible: "country"`.
+ *
+ * `undefined` is therefore the load-bearing input rather than an edge case.
+ * An *empty* field and a *missing* field are indistinguishable here - S 3.4.3:
+ * a field key bound to `undefined` is treated as absent, and an empty
+ * `FormControl` is the common case - so both arrive as `undefined`, and both
+ * mean "not visible".
+ *
+ * The string `'false'` is **visible**, because it is a non-empty string. That
+ * is truthiness rather than parsing, and it is the answer a form-builder UI
+ * storing every value as a string will hit. Documented in the README rather
+ * than special-cased: a coercion that parsed `'false'` would then owe an
+ * answer for `'no'`, `'0'` and `'off'`, none of which JavaScript has one for.
+ *
+ * Both adapters call this, which is why it is in the core: `/reactive` and
+ * `/signals` differ in how they schedule the recompute and not in what the
+ * result means (S 3.4.5).
+ *
+ * @param value - Whatever the expression evaluated to.
+ * @returns `true` when the value is truthy.
+ */
+const toVisible = (value) => !!value;
+/**
+ * Coerces an expression's result to the string a `text` rule needs.
+ *
+ * `String(value)`, with `null` and `undefined` mapping to `''` (plan S 3.6).
+ * Those two are the carve-out and the only one: rendering the literal text
+ * `undefined` into a label is the failure this rule exists to prevent, and it
+ * is what a bare `String(value)` would do for the most ordinary input a form
+ * has - the empty control of S 3.4.3.
+ *
+ * Every *other* falsy value stringifies normally: `0` is `'0'` and `false` is
+ * `'false'`. Mapping all falsy values to `''` would be the obvious way to
+ * write this rule wrongly, and it would blank a field whose value is
+ * legitimately zero.
+ *
+ * @param value - Whatever the expression evaluated to.
+ * @returns The value as a string, or `''` when it is `null` or `undefined`.
+ */
+const toText = (value) => value === null || value === undefined ? '' : String(value);
+
+/**
+ * Composes one `EvalContext` for one field, out of two live sources.
+ *
+ * The mechanism is **two lookups, not a joined record** (plan S 3.4.2). The
+ * field half is a `createSignalContext` over `fieldSource`; the form half is a
+ * second resolver pushed onto the same context's `lookups`. Both close over
+ * their source and read it at resolve time, so a key added to either after
+ * construction resolves - there is no third object to keep in sync, and no
+ * write-through to N contexts.
+ *
+ * `EvalContext.get` walks `lookups` in order and takes the first
+ * non-`undefined`, so the field half is consulted first.
+ *
+ * One context per field, never one shared across fields (plan S 3.4.1):
+ * `get` resolves `scopes` and `original` *before* `lookups`, so anything left
+ * on a shared context - an arrow function's leaked scope, say - would be read
+ * ahead of every other field's source key of the same name, for the life of
+ * the form.
+ *
+ * **Resolution is live; appearance is not reactive.** An expression that read
+ * a then-missing key subscribed to nothing, so the owner of the source calls
+ * `invalidate()` when the *key set* changes. A change to a *value* is
+ * Angular's job and needs nothing.
+ *
+ * **Precedence is value-dependent, not permanent.** A field key wins while
+ * its value is *present*: `EvalContext.get` treats `undefined` as absent at
+ * every step, and the field resolver returns `undefined` both for "no such
+ * key" and for "key bound to `undefined`" - so an empty `FormControl`, which
+ * is the common case rather than an exotic one, falls through to the form
+ * value. Documented as a limitation (plan S 3.4.3): distinguishing the two
+ * would need a sentinel threaded through `EvalContext.get`, which is
+ * `eval-core`'s and out of this phase's scope.
+ *
+ * @param formSource - The form-wide keys, shared by every field of the form.
+ * @param fieldSource - The field-local keys. These win on a name collision,
+ *                      while their value is not `undefined`.
+ * @param options - Passed to `createSignalContext` for **both** halves;
+ *                  configures this context and its resolvers, not the walk.
+ *                  As upstream, `caseInsensitive` corrects identifier keys
+ *                  here but not *property* names - the member visitor reads
+ *                  those off the state's options, so the same options must
+ *                  also reach `simpleEval` / `createState`.
+ */
+const createFieldContext = (formSource, fieldSource, options) => {
+    const context = createSignalContext(fieldSource, options);
+    // The form half **borrows upstream's resolver rather than rewriting it**
+    // (S 3.4.2, candidate A, settled in step 2). The second context is
+    // discarded and only its closure survives, so this is still one
+    // `EvalContext` per field and the field half is still consulted first.
+    //
+    // The deciding reason is row 2 of S 3.4.2's measured table, and it is that
+    // the hand-written read is *wrong*, not merely thinner: it returns a signal
+    // un-called, so a form key holding `signal(undefined)` resolves to the
+    // signal **function**, which is truthy - and `visible: "country"` then
+    // renders a field precisely when its value is absent, silently, on an empty
+    // control. That is every form's first render. Recorded here because the
+    // alternative was rejected on correctness and stays rejected even once
+    // S 3.5 names a mechanism that keeps a plain-value record live.
+    //
+    // Borrowing also brings own-property semantics - so a server-supplied field
+    // named `constructor` cannot resolve off `Object.prototype` *through this
+    // half*, which is a narrower claim than it looks and no test reaches it:
+    // `get` consults `original` before `lookups`, and `getContextValue` reads a
+    // plain object as a bare property access, so an inherited name resolves
+    // there first and never arrives here (S 3.4.3's third layer, upstream and
+    // out of this phase's scope). It also brings `caseInsensitive` correction
+    // and `warnOnNestedSignals` over the form source, with no import beyond the
+    // one already here.
+    //
+    // The scan is the one cost: `createSignalContext` runs
+    // `warnOnNestedSignals` unconditionally, so a form of N fields scans the
+    // same form source N times and, in dev mode, would warn N times under
+    // *upstream's* symbol name for a call this library made. Construction-time
+    // only - no per-node or per-recompute path is touched.
+    context.lookups.push(...createSignalContext(formSource, options).lookups);
+    return context;
+};
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { createFieldContext, toText, toVisible };
+//# sourceMappingURL=zvenigora-ng-eval-forms.mjs.map

package/fesm2022/zvenigora-ng-eval-forms.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"zvenigora-ng-eval-forms.mjs","sources":["../../../../modules/eval-forms/src/lib/coercion.ts","../../../../modules/eval-forms/src/lib/field-context.ts","../../../../modules/eval-forms/src/zvenigora-ng-eval-forms.ts"],"sourcesContent":["/**\r\n * Coerces an expression's result to the boolean a `visible` rule needs.\r\n *\r\n * **JavaScript truthiness, and nothing cleverer** (plan S 3.6). A rule author\r\n * writing `visible: \"country === 'US'\"` gets a boolean already; the coercion\r\n * exists for the ones who write `visible: \"country\"`.\r\n *\r\n * `undefined` is therefore the load-bearing input rather than an edge case.\r\n * An *empty* field and a *missing* field are indistinguishable here - S 3.4.3:\r\n * a field key bound to `undefined` is treated as absent, and an empty\r\n * `FormControl` is the common case - so both arrive as `undefined`, and both\r\n * mean \"not visible\".\r\n *\r\n * The string `'false'` is **visible**, because it is a non-empty string. That\r\n * is truthiness rather than parsing, and it is the answer a form-builder UI\r\n * storing every value as a string will hit. Documented in the README rather\r\n * than special-cased: a coercion that parsed `'false'` would then owe an\r\n * answer for `'no'`, `'0'` and `'off'`, none of which JavaScript has one for.\r\n *\r\n * Both adapters call this, which is why it is in the core: `/reactive` and\r\n * `/signals` differ in how they schedule the recompute and not in what the\r\n * result means (S 3.4.5).\r\n *\r\n * @param value - Whatever the expression evaluated to.\r\n * @returns `true` when the value is truthy.\r\n */\r\nexport const toVisible = (value: unknown): boolean => !!value;\r\n\r\n/**\r\n * Coerces an expression's result to the string a `text` rule needs.\r\n *\r\n * `String(value)`, with `null` and `undefined` mapping to `''` (plan S 3.6).\r\n * Those two are the carve-out and the only one: rendering the literal text\r\n * `undefined` into a label is the failure this rule exists to prevent, and it\r\n * is what a bare `String(value)` would do for the most ordinary input a form\r\n * has - the empty control of S 3.4.3.\r\n *\r\n * Every *other* falsy value stringifies normally: `0` is `'0'` and `false` is\r\n * `'false'`. Mapping all falsy values to `''` would be the obvious way to\r\n * write this rule wrongly, and it would blank a field whose value is\r\n * legitimately zero.\r\n *\r\n * @param value - Whatever the expression evaluated to.\r\n * @returns The value as a string, or `''` when it is `null` or `undefined`.\r\n */\r\nexport const toText = (value: unknown): string =>\r\n  value === null || value === undefined ? '' : String(value);\r\n","import { EvalContext, EvalOptions } from '@zvenigora/ng-eval-core';\r\nimport { SignalContextSource, createSignalContext } from '@zvenigora/ng-eval-signals';\r\n\r\n/**\r\n * Composes one `EvalContext` for one field, out of two live sources.\r\n *\r\n * The mechanism is **two lookups, not a joined record** (plan S 3.4.2). The\r\n * field half is a `createSignalContext` over `fieldSource`; the form half is a\r\n * second resolver pushed onto the same context's `lookups`. Both close over\r\n * their source and read it at resolve time, so a key added to either after\r\n * construction resolves - there is no third object to keep in sync, and no\r\n * write-through to N contexts.\r\n *\r\n * `EvalContext.get` walks `lookups` in order and takes the first\r\n * non-`undefined`, so the field half is consulted first.\r\n *\r\n * One context per field, never one shared across fields (plan S 3.4.1):\r\n * `get` resolves `scopes` and `original` *before* `lookups`, so anything left\r\n * on a shared context - an arrow function's leaked scope, say - would be read\r\n * ahead of every other field's source key of the same name, for the life of\r\n * the form.\r\n *\r\n * **Resolution is live; appearance is not reactive.** An expression that read\r\n * a then-missing key subscribed to nothing, so the owner of the source calls\r\n * `invalidate()` when the *key set* changes. A change to a *value* is\r\n * Angular's job and needs nothing.\r\n *\r\n * **Precedence is value-dependent, not permanent.** A field key wins while\r\n * its value is *present*: `EvalContext.get` treats `undefined` as absent at\r\n * every step, and the field resolver returns `undefined` both for \"no such\r\n * key\" and for \"key bound to `undefined`\" - so an empty `FormControl`, which\r\n * is the common case rather than an exotic one, falls through to the form\r\n * value. Documented as a limitation (plan S 3.4.3): distinguishing the two\r\n * would need a sentinel threaded through `EvalContext.get`, which is\r\n * `eval-core`'s and out of this phase's scope.\r\n *\r\n * @param formSource - The form-wide keys, shared by every field of the form.\r\n * @param fieldSource - The field-local keys. These win on a name collision,\r\n *                      while their value is not `undefined`.\r\n * @param options - Passed to `createSignalContext` for **both** halves;\r\n *                  configures this context and its resolvers, not the walk.\r\n *                  As upstream, `caseInsensitive` corrects identifier keys\r\n *                  here but not *property* names - the member visitor reads\r\n *                  those off the state's options, so the same options must\r\n *                  also reach `simpleEval` / `createState`.\r\n */\r\nexport const createFieldContext = (\r\n  formSource: SignalContextSource,\r\n  fieldSource: SignalContextSource,\r\n  options?: EvalOptions\r\n): EvalContext => {\r\n\r\n  const context = createSignalContext(fieldSource, options);\r\n\r\n  // The form half **borrows upstream's resolver rather than rewriting it**\r\n  // (S 3.4.2, candidate A, settled in step 2). The second context is\r\n  // discarded and only its closure survives, so this is still one\r\n  // `EvalContext` per field and the field half is still consulted first.\r\n  //\r\n  // The deciding reason is row 2 of S 3.4.2's measured table, and it is that\r\n  // the hand-written read is *wrong*, not merely thinner: it returns a signal\r\n  // un-called, so a form key holding `signal(undefined)` resolves to the\r\n  // signal **function**, which is truthy - and `visible: \"country\"` then\r\n  // renders a field precisely when its value is absent, silently, on an empty\r\n  // control. That is every form's first render. Recorded here because the\r\n  // alternative was rejected on correctness and stays rejected even once\r\n  // S 3.5 names a mechanism that keeps a plain-value record live.\r\n  //\r\n  // Borrowing also brings own-property semantics - so a server-supplied field\r\n  // named `constructor` cannot resolve off `Object.prototype` *through this\r\n  // half*, which is a narrower claim than it looks and no test reaches it:\r\n  // `get` consults `original` before `lookups`, and `getContextValue` reads a\r\n  // plain object as a bare property access, so an inherited name resolves\r\n  // there first and never arrives here (S 3.4.3's third layer, upstream and\r\n  // out of this phase's scope). It also brings `caseInsensitive` correction\r\n  // and `warnOnNestedSignals` over the form source, with no import beyond the\r\n  // one already here.\r\n  //\r\n  // The scan is the one cost: `createSignalContext` runs\r\n  // `warnOnNestedSignals` unconditionally, so a form of N fields scans the\r\n  // same form source N times and, in dev mode, would warn N times under\r\n  // *upstream's* symbol name for a call this library made. Construction-time\r\n  // only - no per-node or per-recompute path is touched.\r\n  context.lookups.push(...createSignalContext(formSource, options).lookups);\r\n\r\n  return context;\r\n};\r\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './index';\n"],"names":[],"mappings":";;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;AAyBG;AACI,MAAM,SAAS,GAAG,CAAC,KAAc,KAAc,CAAC,CAAC;AAExD;;;;;;;;;;;;;;;;AAgBG;AACI,MAAM,MAAM,GAAG,CAAC,KAAc,KACnC,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,GAAG,EAAE,GAAG,MAAM,CAAC,KAAK;;AC3C3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0CG;AACI,MAAM,kBAAkB,GAAG,CAChC,UAA+B,EAC/B,WAAgC,EAChC,OAAqB,KACN;IAEf,MAAM,OAAO,GAAG,mBAAmB,CAAC,WAAW,EAAE,OAAO,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BzD,IAAA,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,mBAAmB,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC;AAEzE,IAAA,OAAO,OAAO;AAChB;;ACtFA;;AAEG;;;;"}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@zvenigora/ng-eval-forms",
+  "version": "0.1.0",
+  "description": "Angular form field properties from ng-eval expressions",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zvenigora/ng-eval.git"
+  },
+  "keywords": [
+    "Angular",
+    "Eval",
+    "Forms"
+  ],
+  "author": "Zvenigora (https://github.com/zvenigora)",
+  "license": "MIT",
+  "homepage": "https://github.com/Zvenigora/ng-eval#readme",
+  "peerDependencies": {
+    "@angular/core": ">=19.0.0",
+    "@angular/forms": ">=19.0.0",
+    "rxjs": "^7.8.0",
+    "@zvenigora/ng-eval-core": "^0.3.0",
+    "@zvenigora/ng-eval-signals": "^0.1.0"
+  },
+  "sideEffects": false,
+  "module": "fesm2022/zvenigora-ng-eval-forms.mjs",
+  "typings": "types/zvenigora-ng-eval-forms.d.ts",
+  "exports": {
+    "./package.json": {
+      "default": "./package.json"
+    },
+    ".": {
+      "types": "./types/zvenigora-ng-eval-forms.d.ts",
+      "default": "./fesm2022/zvenigora-ng-eval-forms.mjs"
+    },
+    "./reactive": {
+      "types": "./types/zvenigora-ng-eval-forms-reactive.d.ts",
+      "default": "./fesm2022/zvenigora-ng-eval-forms-reactive.mjs"
+    }
+  },
+  "type": "module",
+  "dependencies": {
+    "tslib": "^2.3.0"
+  }
+}

package/types/zvenigora-ng-eval-forms-reactive.d.ts

@@ -0,0 +1,221 @@
+import { Injector } from '@angular/core';
+import { FormGroup } from '@angular/forms';
+import { SignalContextSource, EvalSignal } from '@zvenigora/ng-eval-signals';
+import { ExpressionErrorPolicy } from '@zvenigora/ng-eval-forms';
+
+/**
+ * Builds the form-wide source of an expression context from a `FormGroup`.
+ *
+ * One mirror **per control, never per group** (plan S 3.5.1). A disabled
+ * control is excluded from its parent's aggregate value and there is no
+ * `rawValueChanges` to go with `getRawValue()`, so a group-backed mirror would
+ * lose a field the moment anything disabled it - and this library computes
+ * disablement, so one field's rule would silently blank the value every *other*
+ * field's rules resolve against. A control's own `valueChanges` keeps emitting
+ * regardless of its enabled state.
+ *
+ * **The record holds live values behind accessors, not the mirrored signals**
+ * (S 3.5.5). Each key is an enumerable accessor that reads its change-signal -
+ * which is what a surrounding `computed()` records as a dependency, per key -
+ * and then answers with the control's *current* value. Reading the control
+ * rather than the signal is what makes `invalidate()` a working hatch for
+ * trap 3: a `{ emitEvent: false }` write leaves the change-signal stale, and a
+ * record that handed out that signal would have nothing to recover, however
+ * often it was re-evaluated.
+ *
+ * **One entry per key, for the life of that key** (S 3.5.5). A replaced control
+ * instance re-points its channel; it does not get a new accessor or a new
+ * signal. Building fresh ones would leave every property that had already read
+ * the key tracking the *dead* control's signal - frozen at its last value, for
+ * the life of the binding, which is the failure trap 5 exists to prevent
+ * reappearing one layer up.
+ *
+ * **The returned record must be passed by reference, never spread or cloned.**
+ * `{ ...source }` flattens the accessors to the values they happened to hold,
+ * so the copy records no dependency and every property over it freezes at its
+ * first value with no error. The type - `Record<string, unknown>` - gives no
+ * hint of this, and phase-3-plan S 9.2 describes composing sources by
+ * spreading, which is why it is said here.
+ *
+ * **`invalidate()` covers a stale *value*, not a suppressed *control-set*
+ * change.** Trap 3's hatch works because the accessor re-reads the control, so
+ * re-running the walk recovers. `setControl` / `addControl` / `removeControl`
+ * with `{ emitEvent: false }` suppress `group.events` instead, so `sync` never
+ * runs and the channel still points at the dead instance - there is nothing
+ * for a re-run to recover, in the same structural sense that rules out a
+ * signal-valued record. Current behaviour, pinned here rather than fixed:
+ * the observable is the only signal there is.
+ *
+ * @param group - A flat `FormGroup`. Nested groups and `FormArray` are out of
+ *                scope for this phase.
+ * @param options - `injector` scopes every subscription here to the form's
+ *                  lifetime; it is required rather than optional because an
+ *                  explicit injector means no `DestroyRef` auto-teardown, and
+ *                  an optional one would silently vary that (plan S 3.7).
+ */
+declare const createControlSource: (group: FormGroup, options: {
+    injector: Injector;
+}) => SignalContextSource;
+
+/**
+ * One field's rules, as strings resolved at runtime.
+ *
+ * This is the whole descriptor. It is deliberately not a schema *language*:
+ * `visible` and `text` are the two properties this phase ships (plan S 3.6),
+ * `disabled` is deferred with three reasons rather than a shrug, and
+ * `required` is deferred with the validators.
+ */
+interface FieldSchema {
+    /**
+     * The field's name, and the key its control is mirrored under.
+     *
+     * It does not have to name a control: a rule naming a field the group has
+     * no control for resolves `undefined`, which is S 3.4.3's ordinary case
+     * rather than an error. It may not be a member of `Object.prototype` -
+     * see {@link bindFieldProperties}.
+     */
+    readonly name: string;
+    /** An expression whose value is coerced by truthiness (`toVisible`). */
+    readonly visible?: string;
+    /** An expression whose value is coerced to a string (`toText`). */
+    readonly text?: string;
+}
+/**
+ * The signals bound for one field - one per rule the schema supplied.
+ *
+ * Typed as `EvalSignal`, not `Signal`, and both extra members are load-bearing
+ * on this path (plan S 5): `invalidate()` is trap 3's hatch for a
+ * `{ emitEvent: false }` write and S 3.4.2's hatch for a key-set change, and
+ * `destroy()` is what step 5's teardown counts. Typing these as `Signal` would
+ * put both out of reach through the published surface.
+ *
+ * The type arguments are `boolean` and `string` rather than S 5's original
+ * `unknown`, **because the coercion of S 3.6 happens here**. That section was
+ * written before the coercion's placement was settled and `coercion.ts` states
+ * the settlement - "both adapters call this" - so `unknown` would now describe
+ * the value the property is built *from* rather than the one it answers with.
+ */
+interface FieldProperties {
+    readonly visible?: EvalSignal<boolean>;
+    readonly text?: EvalSignal<string>;
+}
+/**
+ * What {@link bindFieldProperties} returns: the bound fields, and the one call
+ * that ends them.
+ *
+ * **Nested rather than a `destroy` written onto the record** (plan S 5's step-5
+ * amendment). The record is keyed by *field name*, `destroy` is a legal field
+ * name, and S 0's premise is that those names arrive from a server rather than
+ * from the consumer - so a flat shape would put a silent collision between the
+ * consumer's data and this library's API in precisely the case where the
+ * consumer controls the names least.
+ */
+interface FormBinding {
+    /** The bound properties, keyed by field name. */
+    readonly fields: Record<string, FieldProperties>;
+    /**
+     * Destroys every `EvalSignal` this binding created and releases the mirror.
+     *
+     * **Call it.** Every signal here is built with an explicit injector, and
+     * that means no `DestroyRef` registration of its own (`eval-signal.ts`) - so
+     * nothing auto-destroys and all N x M are the caller's (plan S 3.7).
+     *
+     * There is one net under that, and it is a net rather than a substitute: the
+     * binding registers this on the `DestroyRef` of the injector it was given,
+     * so a binding wired to a component or route injector is released when that
+     * injector dies even if nobody called it. It is not a licence to skip the
+     * call - a binding built on the root injector is released at the end of the
+     * application and no sooner.
+     *
+     * Idempotent, and that is load-bearing rather than polite: the scope is an
+     * `EnvironmentInjector`, and `R3Injector.destroy()` throws NG0205 when it
+     * has already run.
+     */
+    destroy(): void;
+}
+/**
+ * Binds a schema to a `FormGroup`, producing one `EvalSignal` per rule.
+ *
+ * ```ts
+ * const binding = bindFieldProperties(
+ *   [{ name: 'state', visible: "country === 'US'" }],
+ *   form,
+ *   { injector }
+ * );
+ *
+ * binding.fields['state'].visible();   // recomputes when `country` changes
+ *
+ * binding.destroy();                   // yours to call - nothing here
+ *                                      // auto-destroys (S 3.7)
+ * ```
+ *
+ * **One `EvalContext` per field, never one shared** (plan S 3.4.1). `get`
+ * resolves `scopes` and `original` *before* `lookups`, and
+ * `arrow-function-expression.ts` pushes its scope with no `try`/`finally` - so
+ * one field's arrow function that throws leaves a scope on the context for the
+ * life of the form, and under a shared context it would shadow every other
+ * field's key of the same name. The count is N contexts for N fields, and not
+ * N x M: the properties of one field resolve against the same names.
+ *
+ * **The field half of each context is empty in this phase.**
+ * `createFieldContext` takes two sources and the second is `{}` here. What a
+ * field-local key set should *contain* is specified nowhere - S 3.4.3's
+ * "a field named `value`, `name` or `index`" illustrates collision semantics
+ * rather than naming keys - and inventing three keys to fill a parameter is
+ * how a public surface acquires members nobody chose. The consequence, stated
+ * rather than left to be found: S 3.4.3's precedence rule is asserted at the
+ * core in `field-context.spec.ts` and ships **untested end to end**, because
+ * no `/reactive` path produces a field-local key. It gets settled by whichever
+ * phase first has a consumer for one.
+ *
+ * **`createControlSource` is called once, for the whole form.** Per field
+ * would build N mirrors over one group: N x the live `toSignal` subscriptions
+ * step 5 counts, and trap 5's O(N) diff running N times per `group.events`
+ * emission, on a signal that already fires several times per interaction.
+ *
+ * **Constructed, not computed.** `toSignal` opens with
+ * `assertNotInReactiveContext`, so calling this from inside an `effect()` or a
+ * `computed()` throws out of the mirror with an error naming `toSignal` and
+ * nothing naming this library. A form binding belongs in a service or a
+ * factory, which is the same premise `injector` being required rests on.
+ *
+ * **Teardown runs off a child injector, and there is only one of them**
+ * (S 3.7, amended in step 5). The binding opens an `EnvironmentInjector` under
+ * the caller's and scopes *both* the mirror and every `createEvalSignal` to it,
+ * so `destroy()` releases the whole mirror - every per-key `toSignal`
+ * subscription and the `group.events` one - in a single call, and a bind that
+ * throws part-way through releases exactly the same thing however far it got.
+ * The plan's earlier premise, that releasing the mirror needed a handle
+ * `createControlSource` does not return, was wrong: step 3 had already measured
+ * that destroying the injector drops every control's observer count to 0 and
+ * ends the diffing.
+ *
+ * The `EvalSignal`s are **not** covered by that, and that is the point of the
+ * count: built with an explicit injector, they take no `DestroyRef`
+ * registration, so `destroy()` walks them itself and N x M of them is what a
+ * spec asserts rather than "the form's destroy ran".
+ *
+ * @param schema - The fields to bind. Validated at construction: a duplicate
+ *                 name, a non-string rule, a name that resolves off
+ *                 `Object.prototype`, and a control that is not a
+ *                 `FormControl` all throw here rather than surfacing later as
+ *                 an evaluation result nobody can trace.
+ * @param group - A flat `FormGroup` of `FormControl`s.
+ * @param options - `injector` is **required**, not optional: S 3.7's argument
+ *                  is that every `EvalSignal` here has no auto-teardown, and
+ *                  an optional injector would silently vary that for a call
+ *                  that happened to sit in an injection context. `onError`
+ *                  defaults to `'undefined'` - the opposite of
+ *                  `eval-signals`' default, and resolved *here* rather than
+ *                  forwarded absent, since `createEvalSignal` would otherwise
+ *                  supply `'throw'` (S 3.4.4).
+ * @returns The bound properties keyed by field name, and the `destroy()` that
+ *          ends them.
+ */
+declare const bindFieldProperties: (schema: readonly FieldSchema[], group: FormGroup, options: {
+    injector: Injector;
+    onError?: ExpressionErrorPolicy;
+}) => FormBinding;
+
+export { bindFieldProperties, createControlSource };
+export type { FieldProperties, FieldSchema, FormBinding };

package/types/zvenigora-ng-eval-forms.d.ts

@@ -0,0 +1,139 @@
+import { EvalOptions, EvalContext } from '@zvenigora/ng-eval-core';
+import { SignalContextSource } from '@zvenigora/ng-eval-signals';
+
+/**
+ * Coerces an expression's result to the boolean a `visible` rule needs.
+ *
+ * **JavaScript truthiness, and nothing cleverer** (plan S 3.6). A rule author
+ * writing `visible: "country === 'US'"` gets a boolean already; the coercion
+ * exists for the ones who write `visible: "country"`.
+ *
+ * `undefined` is therefore the load-bearing input rather than an edge case.
+ * An *empty* field and a *missing* field are indistinguishable here - S 3.4.3:
+ * a field key bound to `undefined` is treated as absent, and an empty
+ * `FormControl` is the common case - so both arrive as `undefined`, and both
+ * mean "not visible".
+ *
+ * The string `'false'` is **visible**, because it is a non-empty string. That
+ * is truthiness rather than parsing, and it is the answer a form-builder UI
+ * storing every value as a string will hit. Documented in the README rather
+ * than special-cased: a coercion that parsed `'false'` would then owe an
+ * answer for `'no'`, `'0'` and `'off'`, none of which JavaScript has one for.
+ *
+ * Both adapters call this, which is why it is in the core: `/reactive` and
+ * `/signals` differ in how they schedule the recompute and not in what the
+ * result means (S 3.4.5).
+ *
+ * @param value - Whatever the expression evaluated to.
+ * @returns `true` when the value is truthy.
+ */
+declare const toVisible: (value: unknown) => boolean;
+/**
+ * Coerces an expression's result to the string a `text` rule needs.
+ *
+ * `String(value)`, with `null` and `undefined` mapping to `''` (plan S 3.6).
+ * Those two are the carve-out and the only one: rendering the literal text
+ * `undefined` into a label is the failure this rule exists to prevent, and it
+ * is what a bare `String(value)` would do for the most ordinary input a form
+ * has - the empty control of S 3.4.3.
+ *
+ * Every *other* falsy value stringifies normally: `0` is `'0'` and `false` is
+ * `'false'`. Mapping all falsy values to `''` would be the obvious way to
+ * write this rule wrongly, and it would blank a field whose value is
+ * legitimately zero.
+ *
+ * @param value - Whatever the expression evaluated to.
+ * @returns The value as a string, or `''` when it is `null` or `undefined`.
+ */
+declare const toText: (value: unknown) => string;
+
+/**
+ * What a field property does when its expression throws at runtime.
+ *
+ * - `'throw'` - rethrow, matching `eval-signals`' own default.
+ * - `'undefined'` - the property resolves `undefined`, which `toVisible`
+ *   reads as not visible and `toText` reads as `''`.
+ * - a function - called with the error; its return value becomes the
+ *   property's value.
+ *
+ * **The default here is `'undefined'`, the opposite of `eval-signals`'**, and
+ * the consumer is the reason (plan S 3.4.4). An expression that fails in
+ * `eval-signals` was written by the developer reading the stack trace. An
+ * expression that fails here may have been typed into a form builder by an
+ * end user, and the right response to "the admin wrote a bad rule" is a field
+ * that does not render, not an application that throws on every change
+ * detection pass. Consumers who want the strict behaviour pass `'throw'`.
+ *
+ * Resolving that default is a real step and not a formality: `createEvalSignal`
+ * does `options?.onError ?? 'throw'`, so forwarding an *absent* policy verbatim
+ * inherits `'throw'` - the opposite of this default. The `/reactive` binding
+ * substitutes its own before the call.
+ *
+ * The union is structurally identical to `EvalSignalOptions['onError']`
+ * **deliberately**: `/reactive` resolves the default here and forwards the
+ * value to `createEvalSignal` with no mapping between the two unions, which is
+ * where two near-identical types would drift apart.
+ *
+ * `SignalContextWriteError` is **not** routed through this, in either adapter,
+ * matching `phase-3-plan.md` S 3.6.3. A write violation is static - illegal on
+ * every recompute with every dataset - and swallowing it under a default of
+ * `'undefined'` would hand every consumer a silent blank for a bug in the
+ * rule's own syntax. `createEvalSignal` already bypasses `onError` for it.
+ *
+ * **Only the type ships in this phase.** A matching `applyErrorPolicy` helper
+ * would have no caller: on the `/reactive` path - the only path Phase 4 ships
+ * - `createEvalSignal` applies the three cases internally. Its sole consumer
+ * is the `/signals` adapter, which is on paper only (S 9), so the helper is
+ * deferred to that phase and will be written against this type. Shipping an
+ * unexercised code path is what S 9.1 declines to do for the scope-leak
+ * containment, and the rule applies to both or to neither.
+ */
+type ExpressionErrorPolicy = 'throw' | 'undefined' | ((error: unknown) => unknown);
+
+/**
+ * Composes one `EvalContext` for one field, out of two live sources.
+ *
+ * The mechanism is **two lookups, not a joined record** (plan S 3.4.2). The
+ * field half is a `createSignalContext` over `fieldSource`; the form half is a
+ * second resolver pushed onto the same context's `lookups`. Both close over
+ * their source and read it at resolve time, so a key added to either after
+ * construction resolves - there is no third object to keep in sync, and no
+ * write-through to N contexts.
+ *
+ * `EvalContext.get` walks `lookups` in order and takes the first
+ * non-`undefined`, so the field half is consulted first.
+ *
+ * One context per field, never one shared across fields (plan S 3.4.1):
+ * `get` resolves `scopes` and `original` *before* `lookups`, so anything left
+ * on a shared context - an arrow function's leaked scope, say - would be read
+ * ahead of every other field's source key of the same name, for the life of
+ * the form.
+ *
+ * **Resolution is live; appearance is not reactive.** An expression that read
+ * a then-missing key subscribed to nothing, so the owner of the source calls
+ * `invalidate()` when the *key set* changes. A change to a *value* is
+ * Angular's job and needs nothing.
+ *
+ * **Precedence is value-dependent, not permanent.** A field key wins while
+ * its value is *present*: `EvalContext.get` treats `undefined` as absent at
+ * every step, and the field resolver returns `undefined` both for "no such
+ * key" and for "key bound to `undefined`" - so an empty `FormControl`, which
+ * is the common case rather than an exotic one, falls through to the form
+ * value. Documented as a limitation (plan S 3.4.3): distinguishing the two
+ * would need a sentinel threaded through `EvalContext.get`, which is
+ * `eval-core`'s and out of this phase's scope.
+ *
+ * @param formSource - The form-wide keys, shared by every field of the form.
+ * @param fieldSource - The field-local keys. These win on a name collision,
+ *                      while their value is not `undefined`.
+ * @param options - Passed to `createSignalContext` for **both** halves;
+ *                  configures this context and its resolvers, not the walk.
+ *                  As upstream, `caseInsensitive` corrects identifier keys
+ *                  here but not *property* names - the member visitor reads
+ *                  those off the state's options, so the same options must
+ *                  also reach `simpleEval` / `createState`.
+ */
+declare const createFieldContext: (formSource: SignalContextSource, fieldSource: SignalContextSource, options?: EvalOptions) => EvalContext;
+
+export { createFieldContext, toText, toVisible };
+export type { ExpressionErrorPolicy };