ngx-t-forms-types 0.0.30 → 0.0.34

package/dist/skillet/variants.d.ts

@@ -0,0 +1,138 @@
+import { s } from '@hashbrownai/core';
+import { ElementTypes } from '../interfaces/formInput/index.js';
+import { type WorkflowPickerSchemaOptions } from './members/document-picker.js';
+import { type MatOptionsSchemaOptions } from './members/mat-options.js';
+import { type ValidatorsSchemaOptions } from './members/validators.js';
+/**
+ * Per-element column schemas, assembled from the registries.
+ *
+ * ## The element decides the shape
+ *
+ * A flat object carrying every property an input might have is the wrong shape
+ * to hand a model: nothing in it says `trueLabel` belongs to a toggle and
+ * `fileType` to an upload, so it will put them wherever. Each element instead
+ * gets its own object containing only its own properties, tagged with
+ * `element: s.literal(...)`, and the column is the union of those.
+ *
+ * ## The partition is not invented here
+ *
+ * `DefaultInputConfig[element].properties` already states which properties an
+ * element has, and `requiredProperties` which it must have — the form builder
+ * has been driven by that list all along. Assembly reads it rather than
+ * restating it, so an element gaining a property in the builder gains it in the
+ * schema too, with no second list to keep in step.
+ *
+ * Three kinds of listed key are skipped, each for its own reason: editor-only
+ * rows that store nothing, members still pending a module, and members the
+ * system owns or has deprecated. Anything skipped for a reason not on that list
+ * is recorded in {@link UNRESOLVED_VARIANT_KEYS}, which a test asserts is
+ * empty — so a key that falls through goes noticed rather than silently missing
+ * from every generated form.
+ */
+/**
+ * The keys `baseFormColumnInputsSchema` requires of every column, read off the
+ * Joi schema itself.
+ *
+ * `DefaultInputConfig.properties` does NOT list all of them — it lists the rows
+ * the settings panel shows, and the builder shows no row for `element` (chosen
+ * by dragging) nor usually for `colSize` and `dataType` (taken from the element
+ * template). Assembling from `properties` alone therefore produced variants
+ * that could never pass `validateForm()`: a generated toggle came out with no
+ * `dataType` and was rejected every time.
+ *
+ * Deriving the set from Joi rather than restating it means the generation
+ * schema cannot come to disagree with the validator about what a column must
+ * have — the same reason the enums are read at runtime rather than copied.
+ *
+ * ## Why an empty validate() rather than describe()
+ *
+ * `describe()` reads this straight off the schema and is the obvious way to do
+ * it — but Joi's BROWSER build ships with manifest functionality compiled out,
+ * so calling it throws `AssertError: Manifest functionality disabled`. Since
+ * this module is evaluated on import, that would take down any Angular
+ * consumer of the skillet subpath the moment it loaded.
+ *
+ * Validating an empty object reaches the same fact through `validate()`, which
+ * is core Joi and present in both builds: every unsatisfied `any.required`
+ * names a key the schema demands. Verified to return an identical set.
+ */
+export declare const JOI_MANDATORY_COLUMN_KEYS: readonly string[];
+/**
+ * Modelled members `formColumnInputsSchema` does not declare, and which a
+ * generated form therefore must not carry.
+ *
+ * **This set is empty today, and a test asserts it stays that way.** It is kept
+ * because it is the guard that made the problem visible in the first place, and
+ * because it costs one `validate()` call at load to keep it visible.
+ *
+ * ## What it caught
+ *
+ * Joi objects reject unknown keys, so a column carrying an undeclared member
+ * does not merely lose it — the whole form fails validation:
+ *
+ *     "Slides > Columns > Placeholder" is not allowed
+ *
+ * Eleven members were in that state: `placeholder`, `autocomplete`, `disabled`,
+ * the four prefix/suffix affixes, `selectUpto`, `showTotalsOf`, and the two
+ * table configs. Every one was declared on an interface and most were listed in
+ * `DefaultInputConfig.properties`, so the generator offered them and the
+ * validator rejected them. They have since been added to
+ * `baseFormColumnInputsSchema`, given editor rows, and scoped to the elements
+ * that can actually use them.
+ *
+ * ## Why it is derived rather than listed
+ *
+ * Nothing here had to be edited when the validator was fixed. The set is
+ * computed from the validator at load, so it emptied itself — and it will fill
+ * itself again the moment a member is modelled that Joi does not accept. A
+ * hand-maintained list would have needed deleting, and would not have been
+ * watching afterwards.
+ *
+ * Probed against `formColumnInputsSchema` rather than the base, because
+ * `formInputs` is appended there; probing the base would report a list's own
+ * contents as unknown and quietly withdraw every item list.
+ */
+export declare const JOI_UNKNOWN_COLUMN_KEYS: ReadonlySet<string>;
+/**
+ * Property keys assembly could not resolve to a node, and could not account for
+ * as a deliberate omission. Should always be empty; a test enforces it.
+ */
+export declare const UNRESOLVED_VARIANT_KEYS: string[];
+/** The elements worth offering before the exotic ones have been proven out. */
+export declare const COMMON_ELEMENTS: readonly ElementTypes[];
+/**
+ * How many levels of nested list contents to offer by default.
+ *
+ * One level means a form may contain an item list, and that list's rows may
+ * contain ordinary fields — which is the shape nearly every real item list has.
+ * Two would allow a list inside a list; it is available, but it multiplies the
+ * schema by roughly the size of a whole column union each time, so it is not
+ * the default.
+ */
+export declare const DEFAULT_NESTING_DEPTH = 1;
+export interface ColumnSchemaOptions extends MatOptionsSchemaOptions, WorkflowPickerSchemaOptions, ValidatorsSchemaOptions {
+    /**
+     * Which elements the model may choose between. Defaults to every element the
+     * builder configures. Narrowing this to {@link COMMON_ELEMENTS} makes the
+     * union markedly smaller and the choice markedly more reliable.
+     */
+    elements?: readonly ElementTypes[];
+    /**
+     * How deeply item lists may nest. Defaults to {@link DEFAULT_NESTING_DEPTH}.
+     * Zero withdraws the item-list element entirely — see
+     * {@link buildColumnSchema} for why it cannot simply be offered without its
+     * contents.
+     */
+    depth?: number;
+}
+/**
+ * Builds the column schema: a discriminated union over the offered elements.
+ *
+ * @param options which elements to offer, how deeply item lists may nest, and
+ *   the endpoints and workflows a `matOptions` source or a document picker may
+ *   select between. See `members/mat-options.ts` for why those are supplied
+ *   rather than authored.
+ */
+export declare function createColumnSchema(options?: ColumnSchemaOptions): s.HashbrownType<unknown>;
+/** Which properties each element contributes, for inspection and testing. */
+export declare function variantKeys(element: ElementTypes, options?: ColumnSchemaOptions): string[];

package/dist/skillet/variants.js

@@ -0,0 +1,536 @@
+import { s } from '@hashbrownai/core';
+import { DefaultInputConfig } from '../interfaces/FormBuilder/DefaultEelement.js';
+import { AllFormInputPrimaryKeys } from '../interfaces/FormBuilder/FormInputKeys.js';
+import { ElementTypes, InputDataTypes, InputTypes } from '../interfaces/formInput/index.js';
+import { baseFormColumnInputsSchema, formColumnInputsSchema, } from '../schemas/FormInputSchema.js';
+import { EDITOR_ONLY_KEYS, PENDING_EXTRA_MEMBERS, extraDraftMemberSchemas, extraInputMemberSchemas, } from './extra-members.js';
+import { DEPRECATED_INPUT_MEMBERS, PENDING_INPUT_MEMBERS, SYSTEM_OWNED_INPUT_MEMBERS, draftMemberSchemas, inputMemberSchemas, } from './input-members.js';
+import { optional } from './internal/coupling.js';
+import { ALWAYS_SHOWN_MEMBERS } from './internal/editor-guidance.js';
+import { calculatedFieldRulesDraftSchema } from './members/calculated-field.js';
+import { createWorkflowPickerSchema, } from './members/document-picker.js';
+import { createMatOptionsSchema, } from './members/mat-options.js';
+import { createValidatorsSchema, } from './members/validators.js';
+/**
+ * Per-element column schemas, assembled from the registries.
+ *
+ * ## The element decides the shape
+ *
+ * A flat object carrying every property an input might have is the wrong shape
+ * to hand a model: nothing in it says `trueLabel` belongs to a toggle and
+ * `fileType` to an upload, so it will put them wherever. Each element instead
+ * gets its own object containing only its own properties, tagged with
+ * `element: s.literal(...)`, and the column is the union of those.
+ *
+ * ## The partition is not invented here
+ *
+ * `DefaultInputConfig[element].properties` already states which properties an
+ * element has, and `requiredProperties` which it must have — the form builder
+ * has been driven by that list all along. Assembly reads it rather than
+ * restating it, so an element gaining a property in the builder gains it in the
+ * schema too, with no second list to keep in step.
+ *
+ * Three kinds of listed key are skipped, each for its own reason: editor-only
+ * rows that store nothing, members still pending a module, and members the
+ * system owns or has deprecated. Anything skipped for a reason not on that list
+ * is recorded in {@link UNRESOLVED_VARIANT_KEYS}, which a test asserts is
+ * empty — so a key that falls through goes noticed rather than silently missing
+ * from every generated form.
+ */
+/**
+ * The keys `baseFormColumnInputsSchema` requires of every column, read off the
+ * Joi schema itself.
+ *
+ * `DefaultInputConfig.properties` does NOT list all of them — it lists the rows
+ * the settings panel shows, and the builder shows no row for `element` (chosen
+ * by dragging) nor usually for `colSize` and `dataType` (taken from the element
+ * template). Assembling from `properties` alone therefore produced variants
+ * that could never pass `validateForm()`: a generated toggle came out with no
+ * `dataType` and was rejected every time.
+ *
+ * Deriving the set from Joi rather than restating it means the generation
+ * schema cannot come to disagree with the validator about what a column must
+ * have — the same reason the enums are read at runtime rather than copied.
+ *
+ * ## Why an empty validate() rather than describe()
+ *
+ * `describe()` reads this straight off the schema and is the obvious way to do
+ * it — but Joi's BROWSER build ships with manifest functionality compiled out,
+ * so calling it throws `AssertError: Manifest functionality disabled`. Since
+ * this module is evaluated on import, that would take down any Angular
+ * consumer of the skillet subpath the moment it loaded.
+ *
+ * Validating an empty object reaches the same fact through `validate()`, which
+ * is core Joi and present in both builds: every unsatisfied `any.required`
+ * names a key the schema demands. Verified to return an identical set.
+ */
+export const JOI_MANDATORY_COLUMN_KEYS = (() => {
+    const { error } = baseFormColumnInputsSchema.validate({}, { abortEarly: false });
+    return (error?.details ?? [])
+        .filter((detail) => detail.type === 'any.required')
+        .map((detail) => detail.path.join('.'));
+})();
+/**
+ * Modelled members `formColumnInputsSchema` does not declare, and which a
+ * generated form therefore must not carry.
+ *
+ * **This set is empty today, and a test asserts it stays that way.** It is kept
+ * because it is the guard that made the problem visible in the first place, and
+ * because it costs one `validate()` call at load to keep it visible.
+ *
+ * ## What it caught
+ *
+ * Joi objects reject unknown keys, so a column carrying an undeclared member
+ * does not merely lose it — the whole form fails validation:
+ *
+ *     "Slides > Columns > Placeholder" is not allowed
+ *
+ * Eleven members were in that state: `placeholder`, `autocomplete`, `disabled`,
+ * the four prefix/suffix affixes, `selectUpto`, `showTotalsOf`, and the two
+ * table configs. Every one was declared on an interface and most were listed in
+ * `DefaultInputConfig.properties`, so the generator offered them and the
+ * validator rejected them. They have since been added to
+ * `baseFormColumnInputsSchema`, given editor rows, and scoped to the elements
+ * that can actually use them.
+ *
+ * ## Why it is derived rather than listed
+ *
+ * Nothing here had to be edited when the validator was fixed. The set is
+ * computed from the validator at load, so it emptied itself — and it will fill
+ * itself again the moment a member is modelled that Joi does not accept. A
+ * hand-maintained list would have needed deleting, and would not have been
+ * watching afterwards.
+ *
+ * Probed against `formColumnInputsSchema` rather than the base, because
+ * `formInputs` is appended there; probing the base would report a list's own
+ * contents as unknown and quietly withdraw every item list.
+ */
+export const JOI_UNKNOWN_COLUMN_KEYS = (() => {
+    const candidates = [
+        ...Object.keys(inputMemberSchemas),
+        ...Object.keys(draftMemberSchemas),
+        ...Object.keys(extraInputMemberSchemas),
+        ...Object.keys(extraDraftMemberSchemas),
+    ];
+    // One probe carrying every candidate at once. Joi reports each unknown key
+    // separately, so a single pass names them all — and a single `validate()`
+    // keeps this cheap enough to run at module load, the same way
+    // JOI_MANDATORY_COLUMN_KEYS does.
+    const probe = Object.fromEntries(candidates.map((key) => [key, 'probe']));
+    const { error } = formColumnInputsSchema.validate(probe, {
+        abortEarly: false,
+    });
+    return new Set((error?.details ?? [])
+        .filter((detail) => detail.type === 'object.unknown')
+        .map((detail) => String(detail.path[0])));
+})();
+/**
+ * Elements the mandatory base does not apply to.
+ *
+ * `validateForm()` filters section-title columns out before validating, so Joi
+ * never sees one. Forcing `formControlName` and `dataType` onto a heading that
+ * captures no value would be inventing a requirement the system does not have.
+ */
+const EXEMPT_FROM_MANDATORY = new Set([
+    ElementTypes.SectionTitle,
+]);
+const SKIPPED_KEYS = new Set([
+    ...EDITOR_ONLY_KEYS,
+    ...PENDING_EXTRA_MEMBERS,
+    ...PENDING_INPUT_MEMBERS,
+    ...SYSTEM_OWNED_INPUT_MEMBERS,
+    ...DEPRECATED_INPUT_MEMBERS,
+]);
+/**
+ * Property keys assembly could not resolve to a node, and could not account for
+ * as a deliberate omission. Should always be empty; a test enforces it.
+ */
+export const UNRESOLVED_VARIANT_KEYS = [];
+/**
+ * Prose for each element on WHEN to reach for it, and what shape of data it
+ * captures.
+ *
+ * This is the Form Creation Guide's Step 3 decision table ("Choose the control
+ * for each field"), restated per element so the choice is made on the shape of
+ * the data rather than on what sounds right. Four of the guide's twelve most
+ * common mistakes are wrong-element mistakes — a dropdown for a long list, a
+ * short custom list left as a dropdown, a number left as text, an API select
+ * for something that is really a workflow document — and each of those rules
+ * is stated on the element it belongs to.
+ *
+ * One note in particular changed on the strength of the guide. The
+ * autocomplete used to be recommended "over a select when the list is long".
+ * The guide draws the line elsewhere: an autocomplete is for a list the user
+ * may ADD TO, because it stores whatever is typed, and a merely long list is a
+ * paginated selection table. The old sentence would have steered a model to
+ * the wrong element for exactly the case the guide calls out.
+ */
+const ELEMENT_NOTES = {
+    [ElementTypes.Input]: "A single-line field for text, a number, an email, a phone number, a code or a memorable date. Set type to the data — 'number' for an amount or a quantity, 'email', 'tel' — never leave a number as text.",
+    [ElementTypes.Textarea]: 'A few sentences of free text: an explanation, a comment, a reason. Always full width, with a maximum length so the user knows the limit.',
+    [ElementTypes.Select]: 'One or several choices from a closed list the user may not add to. Options come from a fixed custom list when policy owns them and from an API when a system owns them; never retype a system list by hand.',
+    [ElementTypes.AutoCompleteInput]: 'A text field that suggests known options but stores whatever the user types. Use it when the user may give an answer that is not on the list, or for a lookup key such as a supplier number; not for a value a decision gate reads, since the stored value may be free text. For a merely long list use a paginatedSelectionTable instead.',
+    [ElementTypes.Toggle]: "A yes/no state, storing a boolean, with trueLabel and falseLabel naming the two real states. For a review decision its formControlName must be exactly the review step's control name, required and never conditionally hidden.",
+    [ElementTypes.DatePicker]: "A single date the user knows or looks up: a delivery date, an invoice date. For a memorable date far in the past, such as a date of birth, use an input of type 'date' instead, because a calendar is slow there. A date the engine schedules on must be required.",
+    [ElementTypes.DateRangePicker]: 'A period with a start and an end, stored under two control names of its own.',
+    [ElementTypes.DateTimePicker]: 'A single moment — a date AND a time of day — stored as one value: an appointment, a site visit, an inspection, a deadline that falls at a particular hour. Use a plain datePicker when the hour does not matter; the extra time field is friction the user pays for nothing.',
+    [ElementTypes.FileUpload]: 'A document, a picture from disk or a photo from the camera. State the accepted types in the hint, and allow several only when several are genuinely expected.',
+    [ElementTypes.SectionTitle]: 'A heading that breaks a slide into groups. Captures no value, so it needs no control name. Put one above every group of three to five related fields and carry the guidance for the group in its hintLabel: where the source documents are, or the rule the group must satisfy.',
+    [ElementTypes.MultipleInput]: 'A repeatable group of rows of the same shape, for a record that contains a list of records: order lines, attendees, assets, bidders. A row may hold any ordinary field, including a number, a date, a select or an account picker. Show totals for the numeric columns.',
+    [ElementTypes.Editor]: 'A rich-text area for formatted prose. Use a plain textarea unless formatting genuinely carries meaning, as in a specification or a resolution.',
+    [ElementTypes.PaginatedSelectionTable]: 'A paged, searchable table for choosing from a very large list, or from options that need several columns to tell apart, such as a supplier number, name and status. A plain dropdown for a long list is a common mistake.',
+    [ElementTypes.MscoaSelection]: 'Picks an account from the municipal chart of accounts, segment by segment. Stores an account object, never a number, so amounts are always separate number inputs. Only for accounting contexts.',
+    [ElementTypes.WorkflowDocumentPicker]: 'Picks an existing transaction of another workflow: an approved budget, the original requisition, a contract. Use it, never a select over an API, whenever the option is a workflow transaction; it already knows the workflow, its columns, its search and its steps.',
+    [ElementTypes.WorkflowAdjudication]: 'Captures tender adjudication scoring. Only within an adjudication workflow.',
+    [ElementTypes.Signature]: 'Captures a drawn signature. Every review form carries one; elsewhere only where a signature has legal or procedural meaning, since the system already records who submitted.',
+    [ElementTypes.ImageCapture]: 'Captures a photo from the device camera.',
+    [ElementTypes.Location]: 'Captures a place on a map, stored as an object of coordinates rather than text.',
+    [ElementTypes.IconSelect]: 'Chooses an icon from a picker, for an option best recognised by a picture. Rare.',
+};
+/** The elements worth offering before the exotic ones have been proven out. */
+export const COMMON_ELEMENTS = [
+    ElementTypes.Input,
+    ElementTypes.Textarea,
+    ElementTypes.Select,
+    ElementTypes.Toggle,
+    ElementTypes.DatePicker,
+    ElementTypes.DateRangePicker,
+    ElementTypes.FileUpload,
+    ElementTypes.SectionTitle,
+];
+/**
+ * How many levels of nested list contents to offer by default.
+ *
+ * One level means a form may contain an item list, and that list's rows may
+ * contain ordinary fields — which is the shape nearly every real item list has.
+ * Two would allow a list inside a list; it is available, but it multiplies the
+ * schema by roughly the size of a whole column union each time, so it is not
+ * the default.
+ */
+export const DEFAULT_NESTING_DEPTH = 1;
+/** Resolves one listed property key to its node, or explains its absence. */
+function resolveMember(key, ctx) {
+    // Checked before anything else: a member the validator will not accept must
+    // not reach a generated form even when a registry has a perfectly good node
+    // for it. See JOI_UNKNOWN_COLUMN_KEYS.
+    if (JOI_UNKNOWN_COLUMN_KEYS.has(key))
+        return null;
+    // The context-built members are checked first and NEVER fall through to
+    // `UNRESOLVED_VARIANT_KEYS`. A null here is a decision — no workflows were
+    // offered, or the nesting budget is spent — not a key nobody modelled.
+    if (key === AllFormInputPrimaryKeys.MatOptions)
+        return ctx.matOptions;
+    if (key === AllFormInputPrimaryKeys.Validators)
+        return ctx.validators;
+    if (key === AllFormInputPrimaryKeys.WorkflowPickerConfig) {
+        return ctx.workflowPicker;
+    }
+    if (key === AllFormInputPrimaryKeys.FormInputs) {
+        if (!ctx.nestedColumns)
+            return null;
+        return s.array('The fields captured for each row of this list, one per column, each with its own control name and column size (a description at 12; quantity, unit price and line total at 4, 4 and 4). Give each one a control name unique within the row; they do not need to be unique across the whole form. A total over these rows that is used anywhere else belongs in a calculated field on the form itself, not only in a roll-up beneath the list.', ctx.nestedColumns, { minItems: 1 });
+    }
+    const registries = [
+        inputMemberSchemas,
+        draftMemberSchemas,
+        extraInputMemberSchemas,
+        extraDraftMemberSchemas,
+    ];
+    for (const registry of registries) {
+        const node = registry[key];
+        if (node)
+            return node;
+    }
+    if (!SKIPPED_KEYS.has(key))
+        UNRESOLVED_VARIANT_KEYS.push(key);
+    return null;
+}
+/**
+ * Whether an element can be offered at all in this context.
+ *
+ * Each of these withdraws an element rather than emitting a broken one. An
+ * element whose `requiredProperties` name a member we cannot supply would
+ * otherwise be generated without it and fail `validateForm()` every time — the
+ * exact failure the Joi-mandatory keys were introduced to stop.
+ */
+function canOffer(element, ctx, nested) {
+    const required = new Set(DefaultInputConfig[element]?.requiredProperties ?? []);
+    // `formInputs` is required of an item list. With the nesting budget spent
+    // there is nothing to put in one, so the element goes rather than the member.
+    if (required.has(AllFormInputPrimaryKeys.FormInputs) && !ctx.nestedColumns) {
+        return false;
+    }
+    // Same for a document picker with no workflow to point at.
+    if (required.has(AllFormInputPrimaryKeys.WorkflowPickerConfig) &&
+        !ctx.workflowPicker) {
+        return false;
+    }
+    // A section title is exempt from the mandatory base because `validateForm()`
+    // strips section titles from a SLIDE before validating. It does not strip
+    // them from `formInputs`, which Joi validates through `Joi.link` against the
+    // full column schema — so a nested heading would be required to have a
+    // `formControlName` and a `dataType` it is deliberately built without, and
+    // would fail. Headings therefore only exist at slide level.
+    if (nested && element === ElementTypes.SectionTitle)
+        return false;
+    return true;
+}
+/**
+ * Builds the object schema(s) for one element.
+ *
+ * Returns a list because one element can contribute more than one branch — see
+ * the calculated-field split below.
+ */
+function buildVariant(element, ctx) {
+    const config = DefaultInputConfig[element];
+    if (!config)
+        return [];
+    const mandatory = EXEMPT_FROM_MANDATORY.has(element)
+        ? []
+        : JOI_MANDATORY_COLUMN_KEYS;
+    const declared = new Set(config.properties ?? []);
+    const listed = [
+        ...new Set([
+            ...declared,
+            ...mandatory,
+            ...rowRollUps(declared),
+            ...alwaysShown(element),
+        ]),
+    ];
+    const required = new Set([
+        ...(config.requiredProperties ?? []),
+        ...mandatory,
+    ]);
+    const shape = {};
+    for (const key of listed) {
+        if (key === AllFormInputPrimaryKeys.Element)
+            continue;
+        const node = resolveMember(key, ctx);
+        if (!node)
+            continue;
+        shape[key] = required.has(key) ? node : optional(node);
+    }
+    const note = ELEMENT_NOTES[element];
+    const description = note ? `${config.label}. ${note}` : `${config.label}.`;
+    if (!canBeCalculated(declared)) {
+        return [s.object(description, { ...discriminator(element), ...shape })];
+    }
+    return calculatedFieldSplit(element, description, shape);
+}
+/**
+ * The `element` discriminator, as a FRESH node each time it is asked for.
+ *
+ * The whole union hangs off this being a single known value, so it is pinned to
+ * a literal rather than reusing the registry's element enum — and, less
+ * obviously, it must not be a shared instance. Skillet hoists any node it sees
+ * more than once into `$defs` and leaves a `$ref` behind, so reusing one
+ * literal across an element's two calculated-field branches turned the
+ * discriminator itself into a reference. That is legal JSON Schema and still
+ * validates, but it puts the one value a model reads to choose a branch behind
+ * an indirection, in the one place indirection is least affordable.
+ */
+function discriminator(element) {
+    return { element: s.literal(element) };
+}
+/**
+ * Whether an element can carry a calculated field, from what it lets an author
+ * set.
+ *
+ * ## Why this is not read from `properties`
+ *
+ * It is the one place assembly departs from `DefaultInputConfig.properties`,
+ * so it is worth being exact about why. NO element lists `isCalculatedField` or
+ * `calculatedFieldRules` in `properties` — yet the settings panel plainly
+ * offers both, through two rows in `ElementEditConfig` named
+ * `SpecialElementKeys.Default` and gated only by `additionalTest`:
+ * `type === number` for the toggle, `isCalculatedField === true` for the rules.
+ *
+ * A row named `Default` is not looked up in `properties` at all; its
+ * `additionalTest` is the whole of its gate. So `properties` is simply not the
+ * list that governs these two, and assembling from it alone left calculated
+ * fields unreachable in every generated form — a feature the builder has and
+ * the generator silently did not.
+ *
+ * This is the second time that list has proved incomplete, and the precedent
+ * for supplementing it is already here: {@link JOI_MANDATORY_COLUMN_KEYS}
+ * exists for exactly the same reason. As there, the supplement is DERIVED
+ * rather than hand-listed — an element qualifies when it lets an author set
+ * both `type` and `dataType`, because a calculated field must be able to be a
+ * number and both must move for that. On today's config that is `input` and
+ * `autoCompleteInput`; `datePicker` offers `type` but pins `dataType` to
+ * `date` in its template, and so correctly does not qualify.
+ */
+function canBeCalculated(declared) {
+    return (declared.has(AllFormInputPrimaryKeys.Type) &&
+        declared.has(AllFormInputPrimaryKeys.DataType));
+}
+/**
+ * The roll-up list an element can carry over its own rows, if it has rows.
+ *
+ * ## Why this is not read from `properties` either
+ *
+ * The THIRD time that list has proved incomplete, for the same reason as the
+ * two above: `properties` names the rows the settings panel renders, and a
+ * roll-up is not authored through a row. It is added by a bespoke control on
+ * the item-list editor — `addFunction` on the multiple-input editor, wired at
+ * `form-section-stepper.component.ts:147` in `ngx-t-forms` to the store action
+ * `addMultipleInputValueCalculationFunction` — and read back at runtime by
+ * `getListCalculated.ts`. There is no `ElementEditConfig` entry for
+ * `calculateListFunctions` at all, so it could never have appeared in
+ * `properties`, and adding it there would make the generic settings panel try
+ * to render a row it has no configuration for.
+ *
+ * So the builder has the feature and, until now, the generator silently did
+ * not — the same gap `canBeCalculated` was written to close, in the same shape.
+ *
+ * Derived rather than hand-listed, as with the other two: an element qualifies
+ * when it declares `formInputs`, because a roll-up aggregates a column across
+ * that element’s own rows and an element without rows has nothing to total.
+ * On today’s config that is `multipleInput` alone.
+ */
+function rowRollUps(declared) {
+    return declared.has(AllFormInputPrimaryKeys.FormInputs)
+        ? [AllFormInputPrimaryKeys.CalculateListFunctions]
+        : [];
+}
+/**
+ * The members every element's settings panel shows regardless of `properties`.
+ *
+ * The FOURTH supplement to `properties`, and the most general. A row named
+ * `SpecialElementKeys.Default` is rendered for every element, gated only by
+ * its own tests, and `properties` never lists what such a row edits. So
+ * `readonly`, `onlySetTempErrorOnTouch` and `tourContent` were never offered
+ * to the model although the builder offers them on every input — and the Form
+ * Creation Guide's Step 6.1 treats the first two as settings a designer sets on
+ * nearly every field: read-only for a prefilled or fetched value, errors only
+ * after the user leaves a field.
+ *
+ * Derived from the editor config by `ALWAYS_SHOWN_MEMBERS` rather than listed
+ * here, for the reason the other three supplements are derived: a hand-kept
+ * list is right on the day it is written. Only ungated rows are included; a
+ * gated one (`min` needs a numeric type) is conditional on a value, which is
+ * what `canBeCalculated` handles structurally and the descriptions handle in
+ * prose, and offering it everywhere would put `min` on a toggle.
+ *
+ * Section titles are exempt, as they are from the mandatory base: their editor
+ * shows the rows too, but a heading that captures no value has nothing to make
+ * read-only or to validate.
+ */
+function alwaysShown(element) {
+    return EXEMPT_FROM_MANDATORY.has(element) ? [] : ALWAYS_SHOWN_MEMBERS;
+}
+/**
+ * Splits an element into a plain branch and a calculated branch.
+ *
+ * ## Encoding the rule instead of describing it
+ *
+ * Two rules govern calculated fields, and both are conditional in a way Skillet
+ * cannot express on a single object:
+ *
+ * - `calculatedFieldRules` only means anything when `isCalculatedField` is true
+ * - `isCalculatedField` only applies when `type` is number
+ *
+ * Left as prose on a flat object, a model is free to emit rules on a field that
+ * is not calculated, or to mark a text field calculated and leave it with no
+ * formula. The second is not hypothetical:
+ * `validateFormColumnInputsWithRequired` makes `calculatedFieldRules` REQUIRED
+ * the moment `isCalculatedField` is true, so a model that sets the flag and
+ * stops has produced a column the builder rejects.
+ *
+ * As two branches of the union the rules stop being advice. A field is either
+ * plain — with no rules member existing at all — or calculated, in which case
+ * `type` and `dataType` are pinned to number and the rules are mandatory.
+ * Neither invalid combination is expressible.
+ *
+ * ## `isCalculatedField` is derived, not asked for
+ *
+ * The obvious encoding pins the flag to a literal on each branch, and Skillet
+ * cannot do it: `literal<T extends string>` takes strings only, so there is no
+ * boolean constant to pin to.
+ *
+ * That turned out to be the better answer anyway. The flag carries no
+ * information the branch does not already carry — it is true exactly when
+ * `calculatedFieldRules` is present — so asking a model for it only creates a
+ * value that can contradict the rest of the object. It is therefore omitted
+ * from the schema entirely and the application sets it during expansion, in the
+ * same step that stamps ids: `isCalculatedField = calculatedFieldRules != null`.
+ * The interface requires the member (`IFormElementTemplate.isCalculatedField`
+ * is not optional), so expansion must set it on EVERY column, plain ones
+ * included.
+ *
+ * ## What this costs, and the one thing it does not enforce
+ *
+ * It doubles the branch count for the two qualifying elements. That is the
+ * whole cost, and it buys the elimination of the most common way a generated
+ * calculated field is wrong.
+ *
+ * `validateForm()` itself does NOT enforce the pairing — `formColumnInputsSchema`
+ * marks `calculatedFieldRules` optional, so a flag with no rules passes there.
+ * The rule is the builder's, via `validateFormColumnInputsWithRequired`. It is
+ * encoded here because a generated form is meant to be indistinguishable from a
+ * built one, not merely to clear the looser of the two gates.
+ */
+function calculatedFieldSplit(element, description, shape) {
+    const plain = s.object(`${description} The value is entered by the user.`, {
+        ...discriminator(element),
+        ...shape,
+    });
+    const calculated = s.object(`${description} This variant is computed from other fields on the form rather than entered by the user, so it is always a number and always carries its formula.`, {
+        ...discriminator(element),
+        ...shape,
+        [AllFormInputPrimaryKeys.Type]: s.literal(InputTypes.Number),
+        [AllFormInputPrimaryKeys.DataType]: s.literal(InputDataTypes.Number),
+        [AllFormInputPrimaryKeys.CalculatedFieldRules]: calculatedFieldRulesDraftSchema,
+    });
+    return [plain, calculated];
+}
+/** Builds the column union for one nesting level. */
+function buildColumnSchema(options, depth, nested) {
+    const requested = options.elements ?? Object.values(ElementTypes);
+    // Only unroll the nesting if an item list is actually on offer. Building it
+    // unconditionally would double the work — and the emitted schema — for every
+    // caller that never asked for one.
+    const wantsNesting = requested.includes(ElementTypes.MultipleInput);
+    const ctx = {
+        matOptions: createMatOptionsSchema(options),
+        validators: createValidatorsSchema(options),
+        workflowPicker: createWorkflowPickerSchema(options),
+        nestedColumns: wantsNesting && depth > 0
+            ? buildColumnSchema(options, depth - 1, true)
+            : null,
+    };
+    const variants = requested
+        .filter((element) => canOffer(element, ctx, nested))
+        .flatMap((element) => buildVariant(element, ctx));
+    if (!variants.length) {
+        throw new Error('createColumnSchema: no elements to offer. Every element passed was either absent from DefaultInputConfig or withdrawn for want of a member it requires.');
+    }
+    return s.anyOf(variants);
+}
+/**
+ * Builds the column schema: a discriminated union over the offered elements.
+ *
+ * @param options which elements to offer, how deeply item lists may nest, and
+ *   the endpoints and workflows a `matOptions` source or a document picker may
+ *   select between. See `members/mat-options.ts` for why those are supplied
+ *   rather than authored.
+ */
+export function createColumnSchema(options = {}) {
+    return buildColumnSchema(options, options.depth ?? DEFAULT_NESTING_DEPTH, false);
+}
+/** Which properties each element contributes, for inspection and testing. */
+export function variantKeys(element, options = {}) {
+    const config = DefaultInputConfig[element];
+    if (!config)
+        return [];
+    const ctx = {
+        matOptions: createMatOptionsSchema(options),
+        validators: createValidatorsSchema(options),
+        workflowPicker: createWorkflowPickerSchema(options),
+        nestedColumns: null,
+    };
+    return [
+        ...new Set([...(config.properties ?? []), ...alwaysShown(element)]),
+    ].filter((key) => key !== AllFormInputPrimaryKeys.Element &&
+        resolveMember(key, ctx) !== null);
+}