@moatamed-sce/form-engine 0.1.5

package/fesm2022/moatamed-sce-form-engine.mjs

@@ -0,0 +1,1144 @@
+import { Validators, FormControl, FormArray } from '@angular/forms';
+import { isFormField, isFormGroupNode, isFormArrayNode, isFieldCondition, PATTERN_SOURCE_MAX_LENGTH } from '@moatamed-sce/form-schema';
+import { shortAddressValidator, crNumberValidator, vatNumberValidator, ibanValidator, saudiMobile05Validator, iqamaValidator, saudiIdValidator } from '@moatamed-sce/core';
+import { InjectionToken } from '@angular/core';
+import { of } from 'rxjs';
+
+/**
+ * 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. */
+const MULTI_VALUE_TYPES = new Set([
+    'multiselect',
+    'checkbox',
+    // A searchable checkbox list is still a checkbox list. Leaving it out seeded it with `''`,
+    // so `.length` read 0 like an empty selection and the first `.map` threw.
+    'checkbox-search',
+    'file',
+]);
+/**
+ * Types whose value is structured and must not be coerced at all.
+ *
+ * `geo` holds `{ lat, lng, address }`. The default branch below runs `String(provided)`, which
+ * turns that into the literal text `[object Object]` — the coordinates are gone, and nothing
+ * downstream can tell that they ever existed. A structured value is passed through untouched.
+ */
+const OPAQUE_TYPES = new Set(['geo']);
+/** The empty value a type holds before any input. */
+function typeFallback(type) {
+    if (MULTI_VALUE_TYPES.has(type)) {
+        return [];
+    }
+    switch (type) {
+        case 'switch':
+            return false;
+        case 'rating':
+            // 0 stars, not `''` — the widget takes a number, and `''` renders as no rating while
+            // failing a `min` check with a type error rather than a rating error.
+            return 0;
+        case 'currency':
+            // null, not 0: an untouched amount is "not stated", and 0 is a real figure.
+            return null;
+        case 'geo':
+            // null: no location picked. `''` is not a place.
+            return null;
+        default:
+            return '';
+    }
+}
+/** Coerces a provided value into the shape the type expects. */
+function coerceValue(type, provided) {
+    if (MULTI_VALUE_TYPES.has(type)) {
+        return Array.isArray(provided) ? provided : provided == null || provided === '' ? [] : [provided];
+    }
+    if (OPAQUE_TYPES.has(type)) {
+        return provided ?? null;
+    }
+    switch (type) {
+        case 'switch':
+            return Boolean(provided);
+        case 'rating': {
+            const parsed = Number(provided);
+            return Number.isFinite(parsed) ? parsed : 0;
+        }
+        case 'currency':
+        case 'number': {
+            if (provided == null || provided === '') {
+                return type === 'currency' ? null : '';
+            }
+            const parsed = Number(provided);
+            return Number.isFinite(parsed) ? parsed : type === 'currency' ? null : String(provided);
+        }
+        default:
+            return provided == null ? '' : String(provided);
+    }
+}
+
+/** The field paths one row of a repeater declares, relative to the row. */
+function rowKeys(node) {
+    const keys = new Set();
+    const walk = (nodes, prefix) => {
+        for (const inner of nodes) {
+            const at = prefix ? `${prefix}.${inner.key}` : inner.key;
+            if (isFormField(inner)) {
+                keys.add(at);
+            }
+            else if (isFormGroupNode(inner)) {
+                walk(inner.nodes, at);
+            }
+        }
+    };
+    walk(node.nodes, '');
+    return keys;
+}
+/**
+ * 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.
+ */
+function fieldPaths(definition, values) {
+    const out = [];
+    const walk = (nodes, prefix, local, row) => {
+        for (const node of nodes) {
+            const path = prefix ? `${prefix}.${node.key}` : node.key;
+            if (isFormField(node)) {
+                out.push(row ? { field: node, path, row } : { field: node, path });
+                continue;
+            }
+            if (isFormGroupNode(node)) {
+                walk(node.nodes, path, asRecord(local[node.key]), row);
+                continue;
+            }
+            if (!values || !isFormArrayNode(node)) {
+                continue;
+            }
+            const rows = Array.isArray(local[node.key]) ? local[node.key] : [];
+            // The same count `buildFormGroup` seeds, so the state map describes the controls that
+            // exist rather than the ones the data happened to arrive with.
+            const rowCount = Math.max(rows.length, node.minItems ?? 0);
+            const keys = rowKeys(node);
+            for (let index = 0; index < rowCount; index += 1) {
+                const rowPrefix = `${path}.${index}`;
+                walk(node.nodes, rowPrefix, asRecord(rows[index]), { prefix: rowPrefix, keys });
+            }
+        }
+    };
+    const root = values ?? {};
+    for (const page of definition.pages) {
+        walk(page.nodes, '', root);
+    }
+    return out;
+}
+/** A nested value as a record, so the walk can keep descending without a null check per branch. */
+function asRecord(value) {
+    return value !== null && typeof value === 'object' ? value : {};
+}
+/** Reads a control value by key, or by dotted path for a field inside a group or a row. */
+function readPath(values, field) {
+    if (!field.includes('.')) {
+        return values[field];
+    }
+    let current = values;
+    for (const segment of field.split('.')) {
+        if (current === null || typeof current !== 'object') {
+            return undefined;
+        }
+        current = current[segment];
+    }
+    return current;
+}
+/**
+ * Reads the value a condition names, from the row when the row declares that field.
+ *
+ * Membership decides this, not whether the row happens to hold a value: `undefined` is a real
+ * answer to an unanswered question, and choosing by value would make a rule read the *form's*
+ * `type` for the first row and the row's own `type` for the second.
+ */
+function readValue$1(values, field, scope) {
+    return scope?.keys.has(field) ? readPath(values, `${scope.prefix}.${field}`) : readPath(values, field);
+}
+/**
+ * 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.
+ */
+function evaluateCondition(condition, values, scope) {
+    if (!isFieldCondition(condition)) {
+        return condition.op === 'and'
+            ? condition.clauses.every(clause => evaluateCondition(clause, values, scope))
+            : condition.clauses.some(clause => evaluateCondition(clause, values, scope));
+    }
+    const value = readValue$1(values, condition.field, scope);
+    switch (condition.op) {
+        case 'eq':
+            return value === condition.value;
+        case 'neq':
+            return value !== condition.value;
+        case 'in':
+            return Array.isArray(condition.value) && condition.value.some(candidate => candidate === value);
+        case 'truthy':
+            // An empty array is falsy here even though `Boolean([])` is true: a multi-select with
+            // nothing chosen has not been answered, and every rule that reads one means it that way.
+            return Array.isArray(value) ? value.length > 0 : Boolean(value);
+        case 'falsy':
+            return Array.isArray(value) ? value.length === 0 : !value;
+        default:
+            return false;
+    }
+}
+const APPLY = {
+    show: state => ({ ...state, hidden: false }),
+    hide: state => ({ ...state, hidden: true }),
+    enable: state => ({ ...state, disabled: false }),
+    disable: state => ({ ...state, disabled: true }),
+    require: state => ({ ...state, required: true }),
+    unrequire: state => ({ ...state, required: false }),
+    readonly: state => ({ ...state, readonly: true }),
+};
+/**
+ * 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.
+ */
+function evaluateRules(definition, values) {
+    const state = new Map();
+    const paths = fieldPaths(definition, values);
+    const scopes = new Map();
+    for (const { field, path, row } of paths) {
+        state.set(path, {
+            hidden: field.hiddenByDefault === true,
+            disabled: field.props?.['disabled'] === true,
+            readonly: field.props?.['readonly'] === true,
+        });
+        scopes.set(path, row);
+    }
+    for (const rule of definition.rules ?? []) {
+        // One verdict per scope, not per target: a rule with four effects on the same row must not
+        // evaluate its condition four times, and two rows must not share one.
+        const verdicts = new Map();
+        for (const effect of rule.then) {
+            for (const path of resolveTarget(effect.target, state, paths)) {
+                const scope = scopes.get(path);
+                const key = scope?.prefix ?? '';
+                let holds = verdicts.get(key);
+                if (holds === undefined) {
+                    holds = evaluateCondition(rule.when, values, scope);
+                    verdicts.set(key, holds);
+                }
+                if (holds) {
+                    state.set(path, APPLY[effect.action](state.get(path)));
+                }
+            }
+        }
+    }
+    return state;
+}
+/**
+ * The control paths a rule effect names.
+ *
+ * An effect may address a field by full path or by bare key. The bare key is what every mapper
+ * writes, because a `Requirement` knows its own id and not which group it landed in — resolving
+ * it here is what lets the mapper stay ignorant of the tree it produced. A key matching several
+ * groups applies to all of them, which is right for a definition that repeats the same question
+ * per scope, and it is also how a rule reaches a repeater: a row's controls are indexed, so
+ * `partners.0.crNumber` is a path no author can write and `crNumber` has to mean every row.
+ *
+ * A target matching nothing is skipped: a rule pointing at a deleted field is an authoring
+ * mistake, not a reason to stop rendering the rest of the form.
+ */
+function resolveTarget(target, state, paths) {
+    if (state.has(target)) {
+        return [target];
+    }
+    return paths.filter(({ field }) => field.key === target).map(({ path }) => path);
+}
+/** Convenience default for a field the rules never mention. */
+const DEFAULT_FIELD_RULE_STATE = { hidden: false, disabled: false, readonly: false };
+
+/**
+ * Resolves the names on a `FormDefinition` to the real validators.
+ *
+ * This is the seam that makes named validators worth having. The Saudi rules already exist,
+ * tested, in `libs/core/src/lib/validation/` — the problem was that a form had to import each
+ * one and attach it as a function, so a JSON document could not describe them and pages kept
+ * re-typing the regexes instead.
+ *
+ * Deliberately NOT wired: `libs/core/src/lib/utils/validation.utils.ts` also exports
+ * `isValidSaudiId` and `isValidIBAN`, and they disagree with the validators above — the utils
+ * version applies a Luhn check and only accepts a `1` prefix, rejecting the Iqama-holder `2`
+ * prefix the validator accepts. The validator directory is canonical here; see ADR 0002.
+ */
+/** Reads a numeric parameter, tolerating the string form an API may send. */
+function numberParam(params, key) {
+    const raw = params?.[key];
+    const value = typeof raw === 'string' ? Number(raw) : raw;
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+/**
+ * Flags that make a `RegExp` carry state between calls.
+ *
+ * `Validators.pattern` uses a supplied `RegExp` object directly, and `.test()` on a `g` or `y`
+ * regex advances `lastIndex` — so validating the *same unchanged value* returned valid, invalid,
+ * valid, invalid on successive passes. A field flickered between states on every keystroke, and
+ * whether a form could be submitted depended on how many times it had been validated. Dropping
+ * the flag is the only reading that makes a stored pattern mean one thing.
+ */
+const STATEFUL_REGEX_FLAGS = /[gy]/g;
+/** Rebuilds a `RegExp` from the serialized `{ source, flags }` a JSON definition carries. */
+function patternParam(params) {
+    const source = params?.['source'];
+    if (typeof source !== 'string' || source === '') {
+        return null;
+    }
+    // A pathological pattern from an untrusted definition is a ReDoS vector. The cap is the
+    // schema's, imported rather than restated: two copies of a security bound drift, and the one
+    // that drifts down is the one nobody notices.
+    if (source.length > PATTERN_SOURCE_MAX_LENGTH) {
+        return null;
+    }
+    const flags = params?.['flags'];
+    const safeFlags = typeof flags === 'string' ? flags.replace(STATEFUL_REGEX_FLAGS, '') : '';
+    try {
+        return new RegExp(source, safeFlags);
+    }
+    catch {
+        return null;
+    }
+}
+/** At least `minSelected` entries chosen in a multi-value control. */
+function minSelectedValidator(min) {
+    return control => {
+        const value = control.value;
+        const count = Array.isArray(value) ? value.length : value == null || value === '' ? 0 : 1;
+        return count >= min ? null : { minSelected: { required: min, actual: count } };
+    };
+}
+/** Value must differ from `expected`. */
+function notEqualValidator(expected) {
+    return control => (control.value === expected ? { notEqual: { disallowed: expected } } : null);
+}
+/** Every selected file is at or under `bytes`. */
+function fileSizeValidator(bytes) {
+    return control => {
+        const files = Array.isArray(control.value) ? control.value : [];
+        const tooBig = files.filter(file => file instanceof File && file.size > bytes);
+        return tooBig.length ? { fileSize: { max: bytes, files: tooBig.map(file => file.name) } } : null;
+    };
+}
+/**
+ * One `accept` entry against one file: an extension, an exact MIME type, or a `type/*` wildcard.
+ *
+ * The wildcard is not a nicety. `sce-file-upload-zone` has always honoured `image/*`, so a
+ * definition written with it let the user pick a PNG, accepted it into the control — and then
+ * this validator marked the control invalid, because it compared `'image/png' === 'image/*'`.
+ * The file was allowed in and made the form unsubmittable, with an error naming a type the file
+ * plainly was. The two checks have to agree.
+ */
+function fileMatches(file, entry) {
+    if (entry.startsWith('.')) {
+        return file.name.toLowerCase().endsWith(entry);
+    }
+    const type = file.type.toLowerCase();
+    return entry.endsWith('/*') ? type.startsWith(entry.slice(0, -1)) : type === entry;
+}
+/** Every selected file matches one of the accepted extensions or MIME types. */
+function fileTypeValidator(accept) {
+    const normalized = accept.map(entry => entry.trim().toLowerCase()).filter(Boolean);
+    return control => {
+        const files = Array.isArray(control.value) ? control.value : [];
+        const rejected = files.filter(file => file instanceof File && !normalized.some(entry => fileMatches(file, entry)));
+        return rejected.length ? { fileType: { accept: normalized, files: rejected.map(file => file.name) } } : null;
+    };
+}
+/**
+ * The accepted types, from either shape a definition writes them in.
+ *
+ * An array is the schema's own form. A comma-separated string is the **HTML `accept` attribute**,
+ * which is what `sce-file-upload-zone` takes and what `fromLegacyConfig` carries across from a
+ * legacy config — so a definition written that way is not malformed, it is written the way the
+ * widget is. Accepting only the array made `resolveNamedValidator` return `null`, and an
+ * unresolved validator is not a validator that fails: it is one that never runs. The field
+ * advertised `.pdf,.png,.jpg`, accepted an `.exe`, and submitted valid.
+ */
+function acceptParam(params) {
+    const accept = params?.['accept'];
+    const entries = Array.isArray(accept) ? accept : typeof accept === 'string' ? accept.split(',') : [];
+    // Empties are dropped here rather than inside the validator, so that a param carrying nothing
+    // usable — `''`, or `','` — resolves to no validator at all instead of to one that rejects
+    // every file for not matching a type nobody named.
+    return entries.filter((entry) => typeof entry === 'string' && entry.trim() !== '');
+}
+/** `YYYY-MM-DD` — the shape `sce-date-field` emits and every date bound in a definition is written in. */
+const DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/;
+/**
+ * Orders a value against a date bound: negative before, zero same, positive after.
+ *
+ * A date-only bound is compared by **calendar day**, not by instant. Comparing timestamps meant
+ * `max: '2026-08-21'` parsed as midnight UTC while a value of `2026-08-21T14:00` parsed as local
+ * time that afternoon — so the last day the bound permits rejected every answer given on it. The
+ * user is told the date is too late while looking at the date they were told to use.
+ *
+ * `null` when either side cannot be read. A bound nobody can parse must not fail every value,
+ * and an unparseable value is a different validator's complaint.
+ */
+function compareToDateBound(value, bound) {
+    const text = String(value);
+    if (DATE_ONLY.test(bound)) {
+        const day = text.slice(0, 10);
+        if (DATE_ONLY.test(day)) {
+            return Math.sign(day.localeCompare(bound));
+        }
+    }
+    const left = new Date(text).getTime();
+    const right = new Date(bound).getTime();
+    return Number.isNaN(left) || Number.isNaN(right) ? null : Math.sign(left - right);
+}
+/** A date at or after `dateMin`. */
+function dateMinValidator(min) {
+    return control => {
+        if (!control.value) {
+            return null;
+        }
+        const order = compareToDateBound(control.value, min);
+        return order === null || order >= 0 ? null : { dateMin: { min } };
+    };
+}
+/** A date at or before `dateMax`. */
+function dateMaxValidator(max) {
+    return control => {
+        if (!control.value) {
+            return null;
+        }
+        const order = compareToDateBound(control.value, max);
+        return order === null || order <= 0 ? null : { dateMax: { max } };
+    };
+}
+/** Validators that take no parameters, resolved by name alone. */
+const ZERO_ARG = {
+    required: () => Validators.required,
+    requiredTrue: () => Validators.requiredTrue,
+    email: () => Validators.email,
+    saudiId: saudiIdValidator,
+    iqama: iqamaValidator,
+    saudiMobile05: saudiMobile05Validator,
+    iban: ibanValidator,
+    vat: vatNumberValidator,
+    cr: crNumberValidator,
+    shortAddress: shortAddressValidator,
+};
+/**
+ * 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.
+ */
+function resolveNamedValidator(validator) {
+    const zeroArg = ZERO_ARG[validator.name];
+    if (zeroArg) {
+        return zeroArg();
+    }
+    const { name, params } = validator;
+    switch (name) {
+        case 'min': {
+            const min = numberParam(params, 'min');
+            return min === null ? null : Validators.min(min);
+        }
+        case 'max': {
+            const max = numberParam(params, 'max');
+            return max === null ? null : Validators.max(max);
+        }
+        case 'minLength': {
+            const min = numberParam(params, 'minLength');
+            return min === null ? null : Validators.minLength(min);
+        }
+        case 'maxLength': {
+            const max = numberParam(params, 'maxLength');
+            return max === null ? null : Validators.maxLength(max);
+        }
+        case 'pattern': {
+            const pattern = patternParam(params);
+            return pattern === null ? null : Validators.pattern(pattern);
+        }
+        case 'minSelected': {
+            const min = numberParam(params, 'min');
+            return min === null ? null : minSelectedValidator(min);
+        }
+        case 'notEqual':
+            return params && 'value' in params ? notEqualValidator(params['value']) : null;
+        case 'fileSize': {
+            const bytes = numberParam(params, 'bytes');
+            return bytes === null ? null : fileSizeValidator(bytes);
+        }
+        case 'fileType': {
+            const accept = acceptParam(params);
+            return accept.length ? fileTypeValidator(accept) : null;
+        }
+        case 'dateMin': {
+            const min = params?.['min'];
+            return typeof min === 'string' ? dateMinValidator(min) : null;
+        }
+        case 'dateMax': {
+            const max = params?.['max'];
+            return typeof max === 'string' ? dateMaxValidator(max) : null;
+        }
+        default:
+            return null;
+    }
+}
+/** Resolves a list of named validators, reporting the names that could not be built. */
+function resolveNamedValidators(validators = []) {
+    const fns = [];
+    const unresolved = [];
+    for (const validator of validators) {
+        const fn = resolveNamedValidator(validator);
+        if (fn) {
+            fns.push(fn);
+        }
+        else {
+            unresolved.push(validator.name);
+        }
+    }
+    return { fns, unresolved };
+}
+
+function fieldValidators(field) {
+    const { fns, unresolved } = resolveNamedValidators(field.validators);
+    return { fns, unresolved };
+}
+/** True when the definition itself marks a field required, before any rule speaks. */
+function isStaticallyRequired(field) {
+    return field.validators?.some(validator => validator.name === 'required') === true;
+}
+/**
+ * Whether a field is required right now.
+ *
+ * A rule wins when it has something to say and the definition applies otherwise — which is what
+ * makes `unrequire` work at all. Toggling instead of reconciling would leave a field that a rule
+ * un-required stuck that way after the condition stopped matching.
+ */
+function isRequiredNow(field, ruleState) {
+    return ruleState?.required ?? isStaticallyRequired(field);
+}
+/**
+ * Adds or removes `Validators.required` to match the rules, leaving every other validator alone.
+ *
+ * `require` and `unrequire` were evaluated and then dropped on the floor: `evaluateRules` wrote
+ * the flag into its state map and no one read it, so a definition saying "when the answer is
+ * yes, require the follow-up" produced a form where the follow-up was never required. It looked
+ * right — the renderer draws its asterisk from the same flag — and submitted empty.
+ *
+ * Reference identity is what makes this safe to do repeatedly: `Validators.required` is the same
+ * function object every time, and `resolveNamedValidator` hands back that exact reference for
+ * the `required` name, so adding and removing it cannot disturb a `saudiId` or `maxLength` sharing
+ * the control. `emitEvent: false` for the same reason every `disable` here uses it — re-validating
+ * inside a `valueChanges` handler otherwise re-enters the rule pass mid-flight.
+ */
+function syncRequired(control, required) {
+    if (required === control.hasValidator(Validators.required)) {
+        return;
+    }
+    if (required) {
+        control.addValidators(Validators.required);
+    }
+    else {
+        control.removeValidators(Validators.required);
+    }
+    control.updateValueAndValidity({ emitEvent: false });
+}
+/** Resolves a field's starting value: supplied initial → definition default → type fallback. */
+function initialValue(field, initial) {
+    if (Object.prototype.hasOwnProperty.call(initial, field.key)) {
+        return coerceValue(field.type, initial[field.key]);
+    }
+    if (field.defaultValue !== undefined && field.defaultValue !== null) {
+        return coerceValue(field.type, field.defaultValue);
+    }
+    return typeFallback(field.type);
+}
+function buildField(field, path, initial, state, fb, unresolved) {
+    const { fns, unresolved: missing } = fieldValidators(field);
+    unresolved.push(...missing);
+    const control = fb.control(initialValue(field, initial), { validators: fns });
+    const ruleState = state.get(path);
+    syncRequired(control, isRequiredNow(field, ruleState));
+    if (ruleState?.hidden || ruleState?.disabled || ruleState?.readonly || field.type === 'display') {
+        control.disable({ emitEvent: false });
+    }
+    return control;
+}
+/**
+ * Builds one repeater row: a group of the array node's fields, stated for *that* row.
+ *
+ * The prefix is the whole point. A row built at prefix `''` looked its state up by bare key, so
+ * `state.get('name')` inside a row resolved to whatever *top-level* field happened to be called
+ * `name` — a partner's name disabled because an unrelated question shared its key. Passing
+ * `partners.0` down means every lookup addresses the control it is actually building, and a
+ * rule that resolved per row reaches it.
+ */
+function buildRow(node, rowPath, initial, state, fb, unresolved) {
+    return fb.group(buildNodes(node.nodes, rowPath, initial, state, fb, unresolved));
+}
+/**
+ * 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.
+ */
+function buildArrayRow(node, initial, fb, rowPath = '') {
+    // Unresolved names are discarded: the row's validators are the same set the definition
+    // declares, which `buildFormGroup` already reported when it built the form.
+    return buildRow(node, rowPath, initial, staticRowState(node, rowPath), fb, []);
+}
+/**
+ * A row's state before any rule speaks: what the fields themselves declare.
+ *
+ * Without this a row added by the user starts every `hiddenByDefault` field visible and every
+ * statically-disabled one editable, until the next rule pass corrects it — a flash of controls
+ * the definition says are not there, on a row the user just created and is looking at.
+ */
+function staticRowState(node, rowPath) {
+    const state = new Map();
+    const walk = (nodes, prefix) => {
+        for (const inner of nodes) {
+            const path = prefix ? `${prefix}.${inner.key}` : inner.key;
+            if (isFormField(inner)) {
+                state.set(path, {
+                    hidden: inner.hiddenByDefault === true,
+                    disabled: inner.props?.['disabled'] === true,
+                    readonly: inner.props?.['readonly'] === true,
+                });
+            }
+            else if (isFormGroupNode(inner)) {
+                // Positively narrowed rather than "not an array": a double negative treats anything
+                // unrecognised as a group and reads `.nodes` off it, which throws on the first node
+                // shape that is neither.
+                walk(inner.nodes, path);
+            }
+        }
+    };
+    walk(node.nodes, rowPath);
+    return state;
+}
+function buildNodes(nodes, prefix, initial, state, fb, unresolved) {
+    const controls = {};
+    for (const node of nodes) {
+        const path = prefix ? `${prefix}.${node.key}` : node.key;
+        if (isFormField(node)) {
+            controls[node.key] = buildField(node, path, initial, state, fb, unresolved);
+            continue;
+        }
+        if (isFormArrayNode(node)) {
+            const rows = Array.isArray(initial[node.key]) ? initial[node.key] : [];
+            // A minItems array with no data still renders its required rows, so the user sees the
+            // shape of what is being asked for rather than an empty list with an add button.
+            const rowCount = Math.max(rows.length, node.minItems ?? 0);
+            const array = fb.array(Array.from({ length: rowCount }, (_, index) => buildRow(node, `${path}.${index}`, rows[index] ?? {}, state, fb, unresolved)));
+            controls[node.key] = array;
+            continue;
+        }
+        const nested = (initial[node.key] ?? {});
+        controls[node.key] = fb.group(buildNodes(node.nodes, path, nested, state, fb, unresolved));
+    }
+    return controls;
+}
+/** Builds a typed, non-nullable `FormGroup` from a definition and its initial values. */
+function buildFormGroup(definition, initial, fb) {
+    const state = evaluateRules(definition, initial);
+    const unresolved = [];
+    const controls = {};
+    for (const page of definition.pages) {
+        Object.assign(controls, buildNodes(page.nodes, '', initial, state, fb, unresolved));
+    }
+    return { group: fb.group(controls), unresolvedValidators: unresolved };
+}
+/**
+ * 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".
+ */
+function applyRuleState(definition, group) {
+    const values = group.getRawValue();
+    const state = evaluateRules(definition, values);
+    // Expanded against the same values the rules were evaluated with, so a row's fields are in the
+    // map. Walking the definition alone would leave every `partners.0.name` unmatched, and the
+    // loop below skips what it cannot name — the row would keep whatever state it was built with.
+    const fields = new Map(fieldPaths(definition, values).map(({ field, path }) => [path, field]));
+    for (const [path, fieldState] of state) {
+        const control = group.get(path);
+        if (!control) {
+            continue;
+        }
+        const field = fields.get(path);
+        // A display field is never editable, so a rule that merely un-hides it must not hand the
+        // user a live control — nor let its (absent) value re-enter the payload.
+        const shouldDisable = fieldState.hidden || fieldState.disabled || fieldState.readonly || field?.type === 'display';
+        // Requirement is reconciled against the definition on every pass, not toggled: a field a
+        // rule un-required has to become required again when the condition stops matching.
+        if (field && control instanceof FormControl) {
+            syncRequired(control, isRequiredNow(field, fieldState));
+        }
+        if (shouldDisable && control.enabled) {
+            control.disable({ emitEvent: false });
+        }
+        else if (!shouldDisable && control.disabled) {
+            control.enable({ emitEvent: false });
+        }
+    }
+    return state;
+}
+/**
+ * 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 `""`.
+ */
+function pickActiveValues(definition, group, state) {
+    const raw = group.getRawValue();
+    const prune = (nodes, values, prefix) => {
+        const out = {};
+        for (const node of nodes) {
+            const path = prefix ? `${prefix}.${node.key}` : node.key;
+            if (isFormField(node)) {
+                if (!state.get(path)?.hidden) {
+                    out[node.key] = values[node.key];
+                }
+                continue;
+            }
+            if (isFormArrayNode(node)) {
+                const rows = Array.isArray(values[node.key]) ? values[node.key] : [];
+                // Each row prunes against its own indexed prefix. Pruning at `''` looked every row field
+                // up by bare key, so a row's `name` was dropped from the payload whenever an unrelated
+                // top-level `name` happened to be hidden.
+                out[node.key] = rows.map((row, index) => prune(node.nodes, row ?? {}, `${path}.${index}`));
+                continue;
+            }
+            // A group is kept even when empty: its key is part of the payload shape the API expects,
+            // and an absent group reads as "not submitted" rather than "nothing was asked here".
+            out[node.key] = prune(node.nodes, (values[node.key] ?? {}), path);
+        }
+        return out;
+    };
+    const out = {};
+    for (const page of definition.pages) {
+        Object.assign(out, prune(page.nodes, raw, ''));
+    }
+    return out;
+}
+/**
+ * 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.
+ */
+function structureSignature(definition) {
+    const parts = [];
+    const walk = (nodes, prefix) => {
+        for (const node of nodes) {
+            const path = prefix ? `${prefix}.${node.key}` : node.key;
+            if (isFormField(node)) {
+                const validators = (node.validators ?? [])
+                    .map(validator => `${validator.name}(${stableStringify(validator.params)})`)
+                    .sort()
+                    .join(',');
+                // `hiddenByDefault` and a static `disabled` both decide whether the control is built
+                // enabled, so a definition that flips either has to rebuild rather than wait for the
+                // next value change to notice.
+                const flags = `${node.hiddenByDefault ? 'h' : ''}${node.props?.['disabled'] === true ? 'd' : ''}`;
+                parts.push(`${path}:${node.type}:${validators}:${flags}`);
+            }
+            else if (isFormArrayNode(node)) {
+                // The bounds are structural: `minItems` decides how many rows a fresh build seeds, so a
+                // definition raising it must rebuild or the rows it now requires never appear.
+                parts.push(`${path}:array:${node.minItems ?? ''}:${node.maxItems ?? ''}`);
+                walk(node.nodes, path);
+            }
+            else {
+                parts.push(`${path}:${node.kind}`);
+                walk(node.nodes, path);
+            }
+        }
+    };
+    for (const page of definition.pages) {
+        walk(page.nodes, '');
+    }
+    return parts.join('|');
+}
+/** `JSON.stringify` with sorted keys, so property order cannot change the result. */
+function stableStringify(value) {
+    if (value === undefined) {
+        return '';
+    }
+    if (value === null || typeof value !== 'object') {
+        return JSON.stringify(value) ?? '';
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(stableStringify).join(',')}]`;
+    }
+    const entries = Object.entries(value).sort(([a], [b]) => a.localeCompare(b));
+    return `{${entries.map(([key, entry]) => `${key}:${stableStringify(entry)}`).join(',')}}`;
+}
+
+/**
+ * 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.
+ */
+function arrayNodeAt(definition, path) {
+    let byKey;
+    const walk = (nodes, prefix) => {
+        for (const node of nodes) {
+            const at = prefix ? `${prefix}.${node.key}` : node.key;
+            if (isFormArrayNode(node)) {
+                if (at === path) {
+                    return node;
+                }
+                // A repeater inside a group is declared at `applicant.partners` but a renderer that
+                // flattens groups holds its control at `partners`. Remembered rather than returned, so
+                // an exact path always wins over a bare key that happens to match deeper.
+                if (node.key === path) {
+                    byKey ??= node;
+                }
+                continue;
+            }
+            if (isFormGroupNode(node)) {
+                const found = walk(node.nodes, at);
+                if (found) {
+                    return found;
+                }
+            }
+        }
+        return undefined;
+    };
+    for (const page of definition.pages) {
+        const found = walk(page.nodes, '');
+        if (found) {
+            return found;
+        }
+    }
+    return byKey;
+}
+/** The node and control a path names, when both are really a repeater. */
+function repeaterAt(definition, group, path) {
+    const node = arrayNodeAt(definition, path);
+    const control = group.get(path);
+    return node && control instanceof FormArray ? { node, array: control } : null;
+}
+/** True when the repeater has room for another row. An absent `maxItems` means no ceiling. */
+function canAddArrayRow(definition, group, path) {
+    const repeater = repeaterAt(definition, group, path);
+    if (!repeater) {
+        return false;
+    }
+    return repeater.node.maxItems === undefined || repeater.array.length < repeater.node.maxItems;
+}
+/** True when a row can be taken away without dropping below `minItems`. */
+function canRemoveArrayRow(definition, group, path) {
+    const repeater = repeaterAt(definition, group, path);
+    if (!repeater) {
+        return false;
+    }
+    return repeater.array.length > (repeater.node.minItems ?? 0);
+}
+/**
+ * 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".
+ */
+function addArrayRow(definition, group, path, fb, initial = {}) {
+    const repeater = repeaterAt(definition, group, path);
+    if (!repeater) {
+        return { changed: false, rows: 0, refused: 'no-such-array' };
+    }
+    const { node, array } = repeater;
+    if (node.maxItems !== undefined && array.length >= node.maxItems) {
+        return { changed: false, rows: array.length, refused: 'at-max' };
+    }
+    array.push(buildArrayRow(node, initial, fb, `${path}.${array.length}`));
+    return { changed: true, rows: array.length };
+}
+/**
+ * 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.
+ */
+function removeArrayRow(definition, group, path, index) {
+    const repeater = repeaterAt(definition, group, path);
+    if (!repeater) {
+        return { changed: false, rows: 0, refused: 'no-such-array' };
+    }
+    const { node, array } = repeater;
+    if (!Number.isInteger(index) || index < 0 || index >= array.length) {
+        return { changed: false, rows: array.length, refused: 'no-such-row' };
+    }
+    if (array.length <= (node.minItems ?? 0)) {
+        return { changed: false, rows: array.length, refused: 'at-min' };
+    }
+    array.removeAt(index);
+    return { changed: true, rows: array.length };
+}
+
+/**
+ * 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.
+ */
+const FORM_DATA_SOURCE = new InjectionToken('sce.form-engine.dataSource');
+/** No options, for every case that resolves to nothing. */
+const NONE = of([]);
+/** The source a field's `dataSourceId` names, if the definition declares one. */
+function dataSourceById(definition, id) {
+    if (!id) {
+        return undefined;
+    }
+    return definition.dataSources?.find(source => source.id === id);
+}
+/**
+ * A dependency's value is "set" when it would pass a `truthy` condition.
+ *
+ * Same rule as the rule evaluator's `truthy`, deliberately: an empty multi-select has not been
+ * answered, so a city list keyed on it must not fetch with an empty region.
+ */
+function isSet(value) {
+    return Array.isArray(value) ? value.length > 0 : value !== '' && value !== null && value !== undefined;
+}
+/** Reads a control value by key, or by dotted path for a field inside a group. */
+function readValue(values, field) {
+    let current = values;
+    for (const segment of field.split('.')) {
+        if (current === null || typeof current !== 'object') {
+            return undefined;
+        }
+        current = current[segment];
+    }
+    return current;
+}
+/**
+ * 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.
+ */
+function resolveDataSource(definition, dataSourceId, values, source) {
+    if (!dataSourceId) {
+        return { options$: NONE };
+    }
+    const ref = dataSourceById(definition, dataSourceId);
+    if (!ref) {
+        return { options$: NONE, issue: `"${dataSourceId}" names no data source on the definition` };
+    }
+    if (ref.type === 'static') {
+        return { options$: of(ref.options ?? []) };
+    }
+    if (!ref.lookupKey) {
+        return { options$: NONE, issue: `lookup source "${ref.id}" carries no lookupKey` };
+    }
+    if (!source) {
+        return { options$: NONE, issue: `lookup "${ref.lookupKey}" needs FORM_DATA_SOURCE, which no provider supplied` };
+    }
+    // A dependent source with nothing chosen yet is not an error: the list is empty until the
+    // parent is answered, which is exactly what a region/city pair should do on first paint.
+    if (ref.dependsOn) {
+        const value = readValue(values, ref.dependsOn);
+        if (!isSet(value)) {
+            return { options$: NONE };
+        }
+        return {
+            options$: source.options({
+                lookupKey: ref.lookupKey,
+                definitionId: definition.id,
+                dependsOn: { field: ref.dependsOn, value },
+            }),
+        };
+    }
+    return { options$: source.options({ lookupKey: ref.lookupKey, definitionId: definition.id }) };
+}
+/**
+ * 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.
+ */
+function dataSourceDependencyValue(definition, dataSourceId, values) {
+    const ref = dataSourceById(definition, dataSourceId);
+    return ref?.dependsOn ? readValue(values, ref.dependsOn) : undefined;
+}
+
+/**
+ * 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.
+ */
+function resolveSteps(definition, values = {}) {
+    const issues = [];
+    const pagesById = new Map(definition.pages.map(page => [page.id, page]));
+    const pathsByPage = pagePaths(definition, values);
+    if (!definition.steps?.length) {
+        return {
+            steps: definition.pages.map((page, index) => ({
+                id: page.id,
+                index,
+                title: page.title ?? { ar: '', en: '' },
+                pages: [page],
+                paths: pathsByPage.get(page.id) ?? [],
+            })),
+            issues,
+        };
+    }
+    const claimed = new Set();
+    const steps = [];
+    definition.steps.forEach((step, index) => {
+        const pages = [];
+        for (const pageId of step.pageIds) {
+            const page = pagesById.get(pageId);
+            if (!page) {
+                issues.push({ id: step.id, reason: `step names page "${pageId}", which the definition does not contain` });
+                continue;
+            }
+            if (claimed.has(pageId)) {
+                // Two steps sharing a page means answering it twice and validating it in two places.
+                issues.push({ id: step.id, reason: `page "${pageId}" is already claimed by an earlier step` });
+                continue;
+            }
+            claimed.add(pageId);
+            pages.push(page);
+        }
+        steps.push({
+            id: step.id,
+            index,
+            title: step.title,
+            pages,
+            paths: pages.flatMap(page => pathsByPage.get(page.id) ?? []),
+        });
+    });
+    for (const page of definition.pages) {
+        if (!claimed.has(page.id)) {
+            issues.push({ id: page.id, reason: 'page belongs to no step, so a stepped render never reaches it' });
+        }
+    }
+    return { steps, issues };
+}
+/** The control paths each page contributes, expanded for the rows the values carry. */
+function pagePaths(definition, values) {
+    const byPage = new Map();
+    for (const page of definition.pages) {
+        // One page at a time, so a path can be attributed to the page that declared it. Walking the
+        // whole definition would give the paths and lose which page each came from.
+        const single = { ...definition, pages: [page] };
+        byPage.set(page.id, fieldPaths(single, values).map(entry => entry.path));
+    }
+    return byPage;
+}
+/**
+ * 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.
+ */
+function stepControls(step, group) {
+    return step.paths.map(path => group.get(path)).filter((control) => control !== null);
+}
+/**
+ * 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.
+ */
+function isStepComplete(step, group) {
+    return stepControls(step, group).every(control => control.disabled || control.valid);
+}
+/** Marks everything in the step touched, so `Next` reveals the errors instead of doing nothing. */
+function markStepTouched(step, group) {
+    for (const control of stepControls(step, group)) {
+        control.markAllAsTouched();
+    }
+}
+/**
+ * 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.
+ */
+function canAdvance(steps, group, index) {
+    const step = steps[index];
+    return step !== undefined && index < steps.length - 1 && isStepComplete(step, group);
+}
+/**
+ * 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.
+ */
+function furthestReachableStep(steps, group) {
+    let reached = 0;
+    while (reached < steps.length - 1 && isStepComplete(steps[reached], group)) {
+        reached += 1;
+    }
+    return reached;
+}
+/**
+ * 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.
+ */
+function firstIncompleteStep(steps, group) {
+    return steps.findIndex(step => !isStepComplete(step, group));
+}
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+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 };
+//# sourceMappingURL=moatamed-sce-form-engine.mjs.map