@moatamed-sce/form-engine 0.1.5

package/types/moatamed-sce-form-engine.d.ts

@@ -0,0 +1,427 @@
+import { FormGroup, NonNullableFormBuilder, AbstractControl, ValidatorFn } from '@angular/forms';
+import { FormDefinition, FormArrayNode, FormFieldType, FormField, Condition, I18nText, DataSourceRef, FormPage, NamedValidator, NamedValidatorName } from '@moatamed-sce/form-schema';
+import { InjectionToken } from '@angular/core';
+import { Observable } from 'rxjs';
+
+/**
+ * Growing and shrinking a repeater.
+ *
+ * `buildFormGroup` already produces a `FormArray` for an `array` node and seeds it to `minItems`,
+ * and there it stopped: nothing could add a row or take one away, so a repeater rendered a fixed
+ * number of rows forever and `maxItems` described a limit nothing enforced. The capability was
+ * half-built, which is worse than absent — a definition could declare `minItems: 1, maxItems: 5`
+ * and get neither.
+ *
+ * Both bounds are enforced here rather than as validators on the array. A validator would let the
+ * user delete the last row and *then* tell them the form is invalid; refusing the removal keeps
+ * the form in a state the definition allows at every moment, and lets the renderer disable the
+ * button instead of rendering an error. {@link canAddArrayRow} and {@link canRemoveArrayRow} are
+ * that button's enabled state.
+ *
+ * Nothing throws. A path that names no repeater is an authoring mistake in the caller, and it is
+ * reported the way the rest of the engine reports one — in the result, with the form untouched.
+ *
+ * **Run `applyRuleState` after any change here.** Row state is keyed by index, so removing row 0
+ * makes what was row 1 into row 0 and every state below the cut is now describing its neighbour
+ * — a hidden field reappears one row up. A new row likewise has only its static state until a
+ * rule pass reads the values it was seeded with. Callers driven by a value-change effect get
+ * this for free, because both operations move `getRawValue()`.
+ */
+/** Why a row could not be added or removed. */
+type ArrayRowRefusal = 
+/** The path names no `array` node, or the group holds no `FormArray` there. */
+'no-such-array'
+/** Already at `maxItems`. */
+ | 'at-max'
+/** Already at `minItems`. */
+ | 'at-min'
+/** The index is outside the rows that exist. */
+ | 'no-such-row';
+/** What happened to the repeater. */
+interface ArrayRowResult {
+    readonly changed: boolean;
+    /** Row count after the attempt — unchanged when `changed` is false. */
+    readonly rows: number;
+    /** Set when `changed` is false. */
+    readonly refused?: ArrayRowRefusal;
+}
+/**
+ * The `array` node a control path names.
+ *
+ * Arrays nested inside arrays are not walked: their controls are indexed (`partners.0.phones`),
+ * and v1 has no way to address one. A definition that nests them still builds — only this lookup
+ * declines to find the inner one.
+ */
+declare function arrayNodeAt(definition: FormDefinition, path: string): FormArrayNode | undefined;
+/** True when the repeater has room for another row. An absent `maxItems` means no ceiling. */
+declare function canAddArrayRow(definition: FormDefinition, group: FormGroup, path: string): boolean;
+/** True when a row can be taken away without dropping below `minItems`. */
+declare function canRemoveArrayRow(definition: FormDefinition, group: FormGroup, path: string): boolean;
+/**
+ * Appends a row, seeded from `initial` where it has values for the row's fields.
+ *
+ * The row is built by the same code that built the ones already there, so a field's coercion and
+ * validators cannot drift between "was in the initial data" and "was added by the user".
+ */
+declare function addArrayRow(definition: FormDefinition, group: FormGroup, path: string, fb: NonNullableFormBuilder, initial?: Readonly<Record<string, unknown>>): ArrayRowResult;
+/**
+ * Removes one row.
+ *
+ * A missing row is reported before the `minItems` check, so a stale index from a double click
+ * does not come back as "you cannot remove any more rows" — which would be a lie the user would
+ * act on.
+ */
+declare function removeArrayRow(definition: FormDefinition, group: FormGroup, path: string, index: number): ArrayRowResult;
+
+/**
+ * The value shape each control type holds.
+ *
+ * A `FormGroup` built from a definition has to be typed before any data arrives, and getting
+ * this wrong is subtle: a multi-select seeded with `''` instead of `[]` makes `value.length`
+ * read 0 either way, then throws the first time something calls `.map`. A currency field seeded
+ * with `''` submits an empty string where the API expects a number or null.
+ */
+/** Types whose value is an array rather than a scalar. */
+declare const MULTI_VALUE_TYPES: ReadonlySet<FormFieldType>;
+/** The empty value a type holds before any input. */
+declare function typeFallback(type: FormFieldType): unknown;
+/** Coerces a provided value into the shape the type expects. */
+declare function coerceValue(type: FormFieldType, provided: unknown): unknown;
+
+/**
+ * Rule evaluation.
+ *
+ * No `eval`, no `new Function`, no expression parser — a closed operator set walked recursively.
+ * A definition may arrive from an API, so the evaluator has to be safe against a hostile
+ * document by construction rather than by sanitising one.
+ */
+/** What the rules currently say about one field. */
+interface FieldRuleState {
+    readonly hidden: boolean;
+    readonly disabled: boolean;
+    readonly readonly: boolean;
+    /** `true` when a rule added a requirement, `false` when one removed it, `undefined` when rules are silent. */
+    readonly required?: boolean;
+}
+/**
+ * Rule state for every field, keyed by the **control path** that addresses it.
+ *
+ * For a flat definition a path is just the field's key, so nothing changes. Inside a group it is
+ * dotted — `riyadh.q-5` — which is what `FormGroup.get` needs. Keying by the bare key instead
+ * meant a rule silently did nothing the moment a definition used groups: `group.get('q-5')`
+ * returns null when the control lives at `riyadh.q-5`, and the follow-up it was meant to reveal
+ * stayed hidden with nothing to say so.
+ */
+type RuleState = ReadonlyMap<string, FieldRuleState>;
+/**
+ * The repeater row a field lives in.
+ *
+ * Rules are authored against a definition, which knows the *shape* of a row and never how many
+ * of them exist — so an effect naming `crNumber` has to mean "that field, in whichever row is
+ * being resolved". The prefix is what turns it into a control path, and `keys` is what decides
+ * whether a condition is asking about this row or about the form.
+ */
+interface RowScope {
+    /** Control path of the row group — `partners.0`. */
+    readonly prefix: string;
+    /** Field paths declared inside one row, relative to {@link prefix}. */
+    readonly keys: ReadonlySet<string>;
+}
+/** A field and the control path that reaches it. */
+interface FieldPath {
+    readonly field: FormField;
+    readonly path: string;
+    /** Set when the field is inside a repeater row, which is what scopes a rule to that row. */
+    readonly row?: RowScope;
+}
+/**
+ * Every field a rule can address, with its control path.
+ *
+ * Repeater rows are walked only when `values` are supplied, because how many rows exist is a
+ * fact about the data and never about the definition — the same reason `buildFormGroup` seeds
+ * `max(rows.length, minItems)` rather than a number the schema could state. Called without
+ * values this returns the static tree, which is what a caller wants when it needs the fields a
+ * definition declares rather than the controls a form currently holds.
+ */
+declare function fieldPaths(definition: FormDefinition, values?: Readonly<Record<string, unknown>>): FieldPath[];
+/**
+ * Evaluates a condition against the live form values.
+ *
+ * `scope` is the row a rule is being resolved for. Inside one, a condition naming a field the
+ * row declares reads *that row's* answer — which is the only reading that lets "when this
+ * partner is a company, require this partner's CR number" be written at all. Every other field
+ * it names is read from the form, so a row can still depend on a question asked once above it.
+ */
+declare function evaluateCondition(condition: Condition, values: Readonly<Record<string, unknown>>, scope?: RowScope): boolean;
+/**
+ * Resolves every field's visibility, enablement and requirement for the current values.
+ *
+ * Starts from the definition's static state — `hiddenByDefault` — then applies each matching
+ * rule in document order, so a later rule wins over an earlier one. That ordering is the reason
+ * rules live on the definition rather than the field: it is deterministic and reviewable in one
+ * place, where a per-field predicate is neither.
+ *
+ * A rule that reaches into a repeater is resolved **once per row**, against that row's answers.
+ * Evaluating the condition once for the whole form instead would make every row share one
+ * verdict — the first partner declared a company would require a CR number from all of them.
+ */
+declare function evaluateRules(definition: FormDefinition, values: Readonly<Record<string, unknown>>): RuleState;
+/** Convenience default for a field the rules never mention. */
+declare const DEFAULT_FIELD_RULE_STATE: FieldRuleState;
+
+/**
+ * Where a select's options come from at runtime.
+ *
+ * A definition can already say `{ type: 'lookup', lookupKey: 'cities' }`, and until now nothing
+ * turned that into options — `formDefinitionToConfig` renders an empty list and says so in a
+ * comment. This is the seam that closes it, and the shape of the seam is the whole point:
+ *
+ *  - **The engine never fetches.** It is `type:core` and must not know `HttpClient` exists. A
+ *    feature implements this interface over whatever it already uses — `LookupApiService` here
+ *    returns promises, so `from()` is the adapter — and provides it at the route.
+ *  - **A lookup is a key, never a URL.** Enforced at the schema boundary already; restated here
+ *    because the port is the place an endpoint would otherwise sneak back in. A host maps keys
+ *    it recognises and refuses the rest, so a definition from an API cannot make the app fetch
+ *    from an arbitrary origin.
+ *  - **Only the declared dependency is passed.** A dependent dropdown needs its parent's value
+ *    and nothing else. Handing the resolver the whole value record would send every answer the
+ *    user has typed — a national ID, a salary — to whichever service happens to serve city
+ *    names.
+ *  - **Static sources never reach the port.** They are data on the document; routing them
+ *    through an injected service would make a form that renders perfectly offline fail because
+ *    a provider was missing.
+ */
+/** One option a select-like field offers. Mirrors the shape a static `DataSourceRef` carries. */
+interface FormOption {
+    readonly value: string;
+    readonly label: I18nText;
+}
+/** The control a dependent source reads, and what it currently holds. */
+interface FormDataSourceDependency {
+    /** Control key named by `DataSourceRef.dependsOn`. */
+    readonly field: string;
+    readonly value: unknown;
+}
+/** What the host is asked to resolve. */
+interface FormDataSourceRequest {
+    /** The definition's `lookupKey` — a key the host maps to an endpoint, never a URL. */
+    readonly lookupKey: string;
+    /** The definition asking, so a host serving several forms can scope caching or permissions. */
+    readonly definitionId: string;
+    /** Present only when the source declares `dependsOn`. */
+    readonly dependsOn?: FormDataSourceDependency;
+}
+/** The port a feature implements so the engine never has to know about HTTP. */
+interface FormDataSource {
+    options(request: FormDataSourceRequest): Observable<readonly FormOption[]>;
+}
+/**
+ * Provided in **features**, never in `ui-components`.
+ *
+ * The renderer injects it `{ optional: true }`: a form built entirely from static sources has
+ * no reason to force every host that renders one to supply a resolver.
+ */
+declare const FORM_DATA_SOURCE: InjectionToken<FormDataSource>;
+/** The outcome of resolving one field's data source. */
+interface ResolvedDataSource {
+    /** Options as they arrive. Emits once and completes for a static source. */
+    readonly options$: Observable<readonly FormOption[]>;
+    /**
+     * Why the list is empty, when it is empty for a reason worth surfacing.
+     *
+     * Follows `BuiltForm.unresolvedValidators`: the engine reports what it could not do and
+     * renders the rest, rather than throwing and blanking a page over one missing dropdown.
+     */
+    readonly issue?: string;
+}
+/** The source a field's `dataSourceId` names, if the definition declares one. */
+declare function dataSourceById(definition: FormDefinition, id: string | undefined): DataSourceRef | undefined;
+/**
+ * Resolves the options for one data source id.
+ *
+ * `source` is the injected port, or `null` when the host provided none. Passing it in rather
+ * than injecting it here keeps this function callable from a test — and from a mapper — without
+ * an injection context.
+ */
+declare function resolveDataSource(definition: FormDefinition, dataSourceId: string | undefined, values: Readonly<Record<string, unknown>>, source: FormDataSource | null): ResolvedDataSource;
+/**
+ * The value that decides whether a source must be re-fetched.
+ *
+ * A renderer re-resolves a dependent source when this changes and leaves every other source
+ * alone — refetching all of them on each keystroke is how a form ends up firing a request per
+ * character typed into an unrelated field.
+ */
+declare function dataSourceDependencyValue(definition: FormDefinition, dataSourceId: string | undefined, values: Readonly<Record<string, unknown>>): unknown;
+
+/**
+ * Wizard steps.
+ *
+ * `FormDefinition.steps` groups pages under a label, and until now nothing read it: a definition
+ * could describe a six-step service journey and the renderer drew all six pages stacked in one
+ * scroll. The schema said wizard and the runtime said long form.
+ *
+ * What lives here is the arithmetic a wizard needs and nothing else — which controls belong to a
+ * step, whether that step is answered, how far the user may go. Deliberately no chrome and no
+ * current-step state: the stepper is `sce-stepper`, and which step is showing is the host's, so
+ * that a wizard driven by a route parameter and one driven by a signal share one notion of
+ * "step 3 is not finished".
+ */
+/** Why a definition's steps could not be taken at face value. */
+interface FormStepIssue {
+    /** The step or page the problem is about. */
+    readonly id: string;
+    readonly reason: string;
+}
+/** One step, resolved against the pages and controls it actually covers. */
+interface FormStepView {
+    readonly id: string;
+    readonly index: number;
+    readonly title: I18nText;
+    readonly pages: readonly FormPage[];
+    /**
+     * Control paths this step holds, expanded against the current values.
+     *
+     * Repeater rows are included — `partners.0.name` — because a step containing a repeater is
+     * finished only when the rows the user actually added are.
+     */
+    readonly paths: readonly string[];
+}
+/** Steps as the runtime sees them, with whatever the definition got wrong. */
+interface ResolvedSteps {
+    readonly steps: readonly FormStepView[];
+    readonly issues: readonly FormStepIssue[];
+}
+/**
+ * Resolves a definition's steps, or falls back to one step per page.
+ *
+ * The fallback is what makes a step-aware host safe to point at any definition: a form that
+ * declares no steps is a one-page-per-step wizard, which for the single-page case is exactly the
+ * flat form it already was. A host that had to branch on `definition.steps` being present would
+ * end up with two layouts to keep in step.
+ *
+ * A page no step claims is reported rather than appended. Appending it would invent a step the
+ * author never wrote; dropping it in silence would lose the questions on it. The caller has an
+ * issues list to render, which is how the rest of this platform reports a document it cannot
+ * take literally.
+ */
+declare function resolveSteps(definition: FormDefinition, values?: Readonly<Record<string, unknown>>): ResolvedSteps;
+/**
+ * The controls a step holds, skipping paths the group does not have.
+ *
+ * A missing control is not an error here: a renderer that flattens groups holds `q-5` where the
+ * definition says `riyadh.q-5`, and a step asserting on every path would call such a form
+ * permanently incomplete.
+ */
+declare function stepControls(step: FormStepView, group: FormGroup): AbstractControl[];
+/**
+ * True when nothing in the step is blocking.
+ *
+ * Disabled controls are skipped rather than counted valid, because Angular reports a disabled
+ * control's `valid` as **false** — a step whose conditional half is currently hidden would never
+ * pass, and the Next button would sit dead with no error to explain why.
+ *
+ * A step holding no controls at all is complete: a page of `display` copy is something the user
+ * reads, not something they answer.
+ */
+declare function isStepComplete(step: FormStepView, group: FormGroup): boolean;
+/** Marks everything in the step touched, so `Next` reveals the errors instead of doing nothing. */
+declare function markStepTouched(step: FormStepView, group: FormGroup): void;
+/**
+ * Whether the user may move on from `index`.
+ *
+ * False on the last step: advancing past the end is a submit, and a wizard that treats it as a
+ * step change is how a form gets a seventh page nobody wrote.
+ */
+declare function canAdvance(steps: readonly FormStepView[], group: FormGroup, index: number): boolean;
+/**
+ * The furthest step the user has earned.
+ *
+ * Every step up to it is complete. This is what a stepper binds its clickable steps to — letting
+ * someone jump to step 5 from an unfinished step 2 produces a review page summarising answers
+ * that were never given.
+ */
+declare function furthestReachableStep(steps: readonly FormStepView[], group: FormGroup): number;
+/**
+ * The first step that is not complete, or `-1` when all of them are.
+ *
+ * A submit that fails should land the user on the question that failed it, not on step 1 with a
+ * toast — this is the index to navigate to.
+ */
+declare function firstIncompleteStep(steps: readonly FormStepView[], group: FormGroup): number;
+
+/**
+ * Resolves one named validator, or `null` when its parameters are missing or unusable.
+ *
+ * Returning `null` rather than throwing is deliberate: a definition with a malformed `min` should
+ * render the form without that one check, not blank the screen. Callers that need to know use
+ * {@link resolveNamedValidators}, which reports what it could not build.
+ */
+declare function resolveNamedValidator(validator: NamedValidator): ValidatorFn | null;
+/** Resolves a list of named validators, reporting the names that could not be built. */
+declare function resolveNamedValidators(validators?: readonly NamedValidator[]): {
+    readonly fns: ValidatorFn[];
+    readonly unresolved: NamedValidatorName[];
+};
+
+/**
+ * Builds the `FormGroup` a definition describes.
+ *
+ * Three decisions here are the ones that bite if they are made the other way:
+ *
+ *  - **Hidden fields still get a control.** They are `disable()`d rather than omitted, so
+ *    `getRawValue()` still carries their key and a rule can reveal one without rebuilding the
+ *    group and losing everything the user has typed. A hidden control that is merely absent is
+ *    how a conditional field ends up blocking submit with an error nobody can see.
+ *  - **`emitEvent: false` on every disable.** Toggling enablement during a `valueChanges`
+ *    handler otherwise re-enters the rule pass, and the second pass sees a half-applied state.
+ *  - **Requirement is reconciled, never toggled.** Each pass recomputes it from the rules and
+ *    the definition together, so a field a rule un-required becomes required again the moment
+ *    the condition stops matching.
+ */
+/** Everything the renderer needs after a build: the group, and what could not be resolved. */
+interface BuiltForm {
+    readonly group: FormGroup;
+    /** Validator names present in the definition that the engine could not resolve. Empty on a clean build. */
+    readonly unresolvedValidators: readonly string[];
+}
+/**
+ * Builds a row for an existing repeater, so a consumer can append one.
+ *
+ * Exported because `addArrayRow` has to produce a row indistinguishable from the ones the
+ * initial build produced — a second implementation would drift the moment a field type gained a
+ * coercion rule.
+ *
+ * A fresh row carries the definition's static state only. Rule state cannot be known here: the
+ * row does not exist in the values yet, so there is nothing for a condition to read. The caller
+ * settles it by running {@link applyRuleState} once the row is in the array, which
+ * {@link addArrayRow} documents as the step that must follow.
+ */
+declare function buildArrayRow(node: FormArrayNode, initial: Readonly<Record<string, unknown>>, fb: NonNullableFormBuilder, rowPath?: string): FormGroup;
+/** Builds a typed, non-nullable `FormGroup` from a definition and its initial values. */
+declare function buildFormGroup(definition: FormDefinition, initial: Readonly<Record<string, unknown>>, fb: NonNullableFormBuilder): BuiltForm;
+/**
+ * Re-applies rule state to an existing group after a value change.
+ *
+ * Rebuilding the group instead would discard `touched`, `dirty` and focus — which is exactly
+ * what users report as "the form reset itself while I was typing".
+ */
+declare function applyRuleState(definition: FormDefinition, group: FormGroup): RuleState;
+/**
+ * The values a submit should carry.
+ *
+ * Hidden fields are omitted rather than sent as empty: a conditional branch the user never saw
+ * should not appear in the payload at all, which is different from appearing as `""`.
+ */
+declare function pickActiveValues(definition: FormDefinition, group: FormGroup, state: RuleState): Record<string, unknown>;
+/**
+ * A signature of everything about a definition that requires a *rebuild* rather than a patch.
+ *
+ * Options are deliberately excluded. Including them meant every lookup fetch changed the
+ * signature, rebuilt the group and wiped whatever the user had already typed — options change
+ * what a select offers, never the shape of the control holding it. Keys are sorted so that two
+ * definitions differing only in property order produce the same signature.
+ */
+declare function structureSignature(definition: FormDefinition): string;
+
+export { DEFAULT_FIELD_RULE_STATE, FORM_DATA_SOURCE, MULTI_VALUE_TYPES, addArrayRow, applyRuleState, arrayNodeAt, buildArrayRow, buildFormGroup, canAddArrayRow, canAdvance, canRemoveArrayRow, coerceValue, dataSourceById, dataSourceDependencyValue, evaluateCondition, evaluateRules, fieldPaths, firstIncompleteStep, furthestReachableStep, isStepComplete, markStepTouched, pickActiveValues, removeArrayRow, resolveDataSource, resolveNamedValidator, resolveNamedValidators, resolveSteps, stepControls, structureSignature, typeFallback };
+export type { ArrayRowRefusal, ArrayRowResult, BuiltForm, FieldPath, FieldRuleState, FormDataSource, FormDataSourceDependency, FormDataSourceRequest, FormOption, FormStepIssue, FormStepView, ResolvedDataSource, ResolvedSteps, RowScope, RuleState };