@moatamed-sce/form-engine 0.1.5

package/README.md

@@ -0,0 +1,98 @@
+# @moatamed-sce/form-engine
+
+The runtime half of the SCE form platform. [`@moatamed-sce/form-schema`](../form-schema) says what a form _is_ — a versioned JSON document; this package turns that document into a working Angular form: a typed `FormGroup`, resolved validators, evaluated rules, repeating rows, and lookup-backed options.
+
+It renders nothing. Rendering is `sce-dynamic-form` in [`@moatamed-sce/ui-components`](../ui-components). The split is deliberate: the engine is `type:core`, so it may use `@angular/forms` but never `HttpClient`, NgRx, or the design system — which is what lets the same document be built into a form inside a designer preview, a unit test, and the app.
+
+## Status — not published
+
+**This package is not currently on npmjs.org**, and neither is `@moatamed-sce/form-schema`, which it declares as a peer. Inside the SCE monorepo both resolve through TypeScript path aliases.
+
+## What's in it
+
+**`buildFormGroup(definition, initialValue, fb)`** — the entry point. Walks the definition's pages depth-first and returns a non-nullable `FormGroup`: fields become `FormControl`s, `group` nodes become nested `FormGroup`s, and `array` nodes become a `FormArray` of row groups. A field's initial value is coerced to its type, so a `number` field handed `"5"` does not poison the form value with a string.
+
+**Named validators** — `resolveNamedValidator` / `resolveNamedValidators` turn a `NamedValidator` (`{ name: 'saudiId' }`) into a real `ValidatorFn`, resolved against the implementations in `@moatamed-sce/core`. This is the half of the schema's central constraint that makes it work: the document carries a _name_ because a function is not serializable, and this is where the name becomes a function again.
+
+**Rule evaluation** — `applyRuleState` reads the definition's rules against the current form value and produces the per-field state the renderer needs: hidden, disabled, required, readonly. Rules are the closed operator set the schema defines; there is no `eval` and no expression parser.
+
+**Repeating rows** — `addArrayRow`, `removeArrayRow`, `canAddArrayRow`, `canRemoveArrayRow`, `buildArrayRow` and `arrayNodeAt`, which honour the node's `minItems` / `maxItems` so the UI never has to re-derive the bounds.
+
+**Wizard steps** — `resolveSteps` turns a definition's `steps` into a `FormStepView` per step, reporting a `FormStepIssue` for anything that does not line up.
+
+**Data sources** — the `FORM_DATA_SOURCE` injection token and `resolveDataSource`. The engine never fetches: the host provides a `FormDataSource`, and a `DataSourceRef` names a `lookupKey` the host resolves. A `dependsOn` source is re-requested with the value of the control it depends on.
+
+**`pickActiveValues`** — the submit-time value with hidden and disabled controls removed, so a conditional branch the user never saw does not travel to the API.
+
+**`structureSignature`** — a cheap string that changes only when a definition's _shape_ changes, which is what lets the renderer rebuild the `FormGroup` on a real structural change and leave it alone otherwise.
+
+## Peer dependencies
+
+Angular **21** (`@angular/core`, `@angular/forms`), RxJS 7.8, `@moatamed-sce/core` (the Saudi validators live there) and `@moatamed-sce/form-schema` (the contract).
+
+## Quick start
+
+```ts
+import { inject } from '@angular/core';
+import { NonNullableFormBuilder } from '@angular/forms';
+import { parseFormDefinition } from '@moatamed-sce/form-schema';
+import { buildFormGroup, applyRuleState, pickActiveValues } from '@moatamed-sce/form-engine';
+
+const fb = inject(NonNullableFormBuilder);
+
+// Parse first — buildFormGroup trusts the definition completely.
+const { definition, problems } = parseFormDefinition(stored);
+if (!definition) {
+  return this.error.set(problems);
+}
+
+const { group } = buildFormGroup(definition, { nationalId: '1234567890' }, fb);
+
+// Which fields are hidden / required / readonly right now:
+const state = applyRuleState(definition, group);
+
+// On submit — hidden and disabled controls are dropped:
+const payload = pickActiveValues(definition, group, state);
+```
+
+Provide a data source when the definition uses `lookup` options:
+
+```ts
+import {
+  FORM_DATA_SOURCE,
+  type FormDataSource,
+  type FormDataSourceRequest,
+  type FormOption,
+} from '@moatamed-sce/form-engine';
+
+@Injectable({ providedIn: 'root' })
+export class LookupFormDataSource implements FormDataSource {
+  private readonly lookups = inject(LookupsApiService);
+
+  // `lookupKey` is a key, never a URL — the document cannot choose an endpoint.
+  // Returns an Observable; the engine subscribes, it never fetches.
+  options(request: FormDataSourceRequest): Observable<readonly FormOption[]> {
+    return this.lookups.byKey(request.lookupKey, request.dependsOn?.value);
+  }
+}
+
+providers: [{ provide: FORM_DATA_SOURCE, useExisting: LookupFormDataSource }];
+```
+
+The request also carries `definitionId`, so a host serving several forms can scope caching or
+permissions. The renderer injects the token `{ optional: true }` — a form built entirely from
+static sources should not force every host that renders one to supply a resolver.
+
+## A caveat worth knowing
+
+`buildFormGroup` trusts the definition it is handed. Run it through `parseFormDefinition` first for anything that did not come from a TypeScript literal in this repo — a stored draft, an API response, an uploaded file. The parser is where prototype-pollution paths, non-JSON values and unbounded row counts are refused; the engine assumes that already happened.
+
+## Docs
+
+- [ADR 0002 — a form is a versioned JSON definition](../../docs/adr/0002-form-definition-platform.md)
+- [Form definition platform — full plan](../../plans/form-builder-platform.md)
+- [The JSON contract](../form-schema/README.md)
+
+## License
+
+MIT