ngx-t-forms-types 0.0.30 → 0.0.33

package/dist/skillet/internal/editor-guidance.js

@@ -0,0 +1,291 @@
+import { SpecialElementKeys } from '../../interfaces/FormBuilder/FormInputKeys.js';
+import { getElementEditorConfig } from '../../interfaces/FormBuilder/inputConfig/ElementEditConfig.js';
+/** Joins a `deepBind` path into the key this module indexes rows by. */
+const pathKey = (path) => path.join('.');
+function collectRows() {
+    const rows = [];
+    for (const section of getElementEditorConfig.editorSections ?? []) {
+        for (const element of section.elements ?? []) {
+            rows.push(element);
+        }
+    }
+    return rows;
+}
+/**
+ * Rows belonging to a `secondaryElementEditorConfig`, indexed by the path of
+ * the row that opens them and then by their own path within that editor.
+ *
+ * ## Why these are indexed separately rather than prefixed into `rowsByPath`
+ *
+ * A secondary editor's rows bind RELATIVE to the record it edits, so making
+ * them globally addressable means prefixing them with something. The obvious
+ * prefix — the opening row's `deepBind` — is right in one case and wrong in the
+ * other, which is the whole reason for this split:
+ *
+ * - `workflowPickerConfig.presetFilters` opens a `RecordListManager` over the
+ *   filters themselves, so its inner `op` row really is
+ *   `workflowPickerConfig.presetFilters[].op`.
+ * - `mscoaConfig` opens a composite editor whose secondary rows edit
+ *   `dualCashExclusion.rules[]`, NOT `mscoaConfig` directly. Prefixing there
+ *   would file the dual-cash `pattern` hint under `mscoaConfig.pattern` — a
+ *   path nothing has, silently attaching accounting-exclusion guidance to
+ *   whatever member later claimed that name.
+ *
+ * Nothing on the row says which of the two it is, so rather than guess, the
+ * caller states the container it is describing and looks rows up within it.
+ * Keeping this index apart from `rowsByPath` also means top-level descriptions
+ * are unchanged by its existence.
+ */
+function collectSecondaryRows() {
+    const index = new Map();
+    for (const parent of collectRows()) {
+        const sections = parent.secondaryElementEditorConfig;
+        if (!sections?.length || !parent.deepBind?.length)
+            continue;
+        const parentKey = pathKey(parent.deepBind);
+        const inner = index.get(parentKey) ?? new Map();
+        for (const section of sections) {
+            for (const row of section.elements ?? []) {
+                if (!row.deepBind?.length)
+                    continue;
+                const key = pathKey(row.deepBind);
+                const existing = inner.get(key);
+                if (existing)
+                    existing.push(row);
+                else
+                    inner.set(key, [row]);
+            }
+        }
+        if (inner.size)
+            index.set(parentKey, inner);
+    }
+    return index;
+}
+/**
+ * Every editor row, indexed by its `deepBind` path.
+ *
+ * `name` is not the index: it reads `'default'` on most rows, with the property
+ * actually being edited carried in `deepBind`. Nested paths
+ * (`matOptions.fetch.options`) are indexed too, so the sub-schemas for the
+ * pending members can draw on the same guidance when they are built.
+ */
+const rowsByPath = (() => {
+    const index = new Map();
+    for (const row of collectRows()) {
+        if (!row.deepBind?.length)
+            continue;
+        const key = pathKey(row.deepBind);
+        const existing = index.get(key);
+        if (existing)
+            existing.push(row);
+        else
+            index.set(key, [row]);
+    }
+    return index;
+})();
+/**
+ * Expressions this module could not read, exposed so a test can assert the set
+ * is empty.
+ *
+ * The grammar in use is closed — `key === value`, joined only by `||` — but it
+ * is a string, so nothing stops a future edit reaching for `&&` or `!==`.
+ * Rather than throw at import time and take a consumer's app down over editor
+ * copy, unreadable expressions are skipped and recorded here, which turns a
+ * silent loss of guidance into a failing test.
+ */
+export const UNREADABLE_EXPRESSIONS = [];
+/**
+ * Renders one comparison as prose.
+ *
+ * `!==` is tested first because `===` is not a substring of it — splitting on
+ * `===` would leave `valueSource !` as the key and read the rule backwards,
+ * which is worse than not reading it at all.
+ */
+function readComparison(clause) {
+    const negated = clause.includes('!==');
+    const parts = clause.split(negated ? '!==' : '===');
+    if (parts.length !== 2)
+        return null;
+    const key = parts[0].trim();
+    const value = parts[1].trim();
+    if (!key || !value)
+        return null;
+    return { key, negated, value };
+}
+/**
+ * Turns one applicability test into a clause such as
+ * `type is number or date`, or `null` if it cannot be read.
+ */
+function readTest(test) {
+    if (test.expression) {
+        const expression = test.expression;
+        // `&&` remains unreadable. Unlike `!==`, it changes the SHAPE of the rule
+        // from "any of these" to "all of these", and every collapse below assumes
+        // alternatives — reading one as a disjunction would state the opposite of
+        // what the editor enforces.
+        if (expression.includes('&&')) {
+            UNREADABLE_EXPRESSIONS.push(expression);
+            return null;
+        }
+        const comparisons = expression.split('||').map(readComparison);
+        if (comparisons.some((c) => c === null)) {
+            UNREADABLE_EXPRESSIONS.push(expression);
+            return null;
+        }
+        const read = comparisons;
+        const phrase = (negated) => (negated ? 'is not' : 'is');
+        // Every clause in the observed grammar tests the same key against
+        // alternatives, which reads far better collapsed than repeated. Collapsing
+        // requires a shared operator as well as a shared key: `a === x || a !== y`
+        // states two different things about `a` and must stay spelled out.
+        const [first] = read;
+        const uniform = read.every((c) => c.key === first.key && c.negated === first.negated);
+        if (uniform) {
+            const values = read.map((c) => c.value);
+            const list = values.length === 1
+                ? values[0]
+                : `${values.slice(0, -1).join(', ')} or ${values[values.length - 1]}`;
+            return `${first.key} ${phrase(first.negated)} ${list}`;
+        }
+        return read
+            .map((c) => `${c.key} ${phrase(c.negated)} ${c.value}`)
+            .join(', or ');
+    }
+    if (test.testType === 'exists' && test.deepBind?.length) {
+        return `${pathKey(test.deepBind)} is set`;
+    }
+    return null;
+}
+/**
+ * Secondary-editor rows, indexed by opening path and then by their own path.
+ * See {@link collectSecondaryRows} for why these are kept out of
+ * {@link rowsByPath}.
+ */
+const secondaryRowsByParent = collectSecondaryRows();
+/** The applicability sentence for a property, if the editor declares one. */
+function applicabilityIn(rows) {
+    if (!rows?.length)
+        return undefined;
+    const clauses = rows
+        .flatMap((row) => row.additionalTest ?? [])
+        .map(readTest)
+        .filter((clause) => clause !== null);
+    const unique = [...new Set(clauses)];
+    if (!unique.length)
+        return undefined;
+    return `Only applies when ${unique.join(', or when ')}.`;
+}
+/**
+ * Collapses the whitespace a hint picked up from its source.
+ *
+ * Several hints are written as indented multi-line template literals, so they
+ * arrive carrying newlines and runs of leading spaces. Rendered into a schema
+ * description those become blank lines and stray gaps before punctuation, which
+ * is exactly the kind of noise that makes a long system prompt harder to read.
+ */
+const collapseWhitespace = (text) => text
+    .replace(/\s+/g, ' ')
+    .replace(/\s+([.,;:])/g, '$1')
+    // Pulling a hint flush can bring a stray trailing full stop up against the
+    // one ending the previous sentence — at least one hint is written with a
+    // lone `.` on its own line. Collapse the pair back to a single stop.
+    .replace(/([.!?])[\s]*\1+/g, '$1')
+    .trim();
+/** The authored hint for a property, if the editor carries one. */
+function hintIn(rows) {
+    const hint = rows
+        ?.map((row) => row.hint)
+        .find((h) => !!h?.trim());
+    return hint ? collapseWhitespace(hint) : undefined;
+}
+/** Ends a fragment with a full stop so composed sentences read cleanly. */
+const terminate = (text) => /[.!?]$/.test(text) ? text : `${text}.`;
+/**
+ * Composes the description for a property: the authored sentence, then the
+ * editor's hint where it adds something, then when the property applies.
+ *
+ * @param base authored, model-facing description of the property
+ * @param path the property's `deepBind` path — a single key for a top-level
+ *   member, a longer path for a member of a nested config
+ */
+export function describe(base, ...path) {
+    return compose(base, rowsByPath.get(pathKey(path)));
+}
+/**
+ * Composes a description for a member of a record edited by a SECONDARY
+ * editor — a preset filter within `workflowPickerConfig.presetFilters`, say.
+ *
+ * @param base authored, model-facing description of the property
+ * @param opensAt the `deepBind` path of the row that opens the editor
+ * @param path the property's path within the record being edited
+ */
+export function describeIn(base, opensAt, ...path) {
+    return compose(base, secondaryRowsByParent.get(pathKey(opensAt))?.get(pathKey(path)));
+}
+/** Shared body of {@link describe} and {@link describeIn}. */
+function compose(base, rows) {
+    const parts = [terminate(base)];
+    const hint = hintIn(rows);
+    // Skip a hint the authored text already covers, so composition cannot
+    // produce the same guidance twice in one description.
+    if (hint && !base.toLowerCase().includes(hint.toLowerCase())) {
+        parts.push(terminate(hint));
+    }
+    const applicability = applicabilityIn(rows);
+    if (applicability)
+        parts.push(applicability);
+    return parts.join(' ');
+}
+/**
+ * Numeric bounds the editor enforces on a property, ready to spread into a
+ * Skillet numeric node so the schema constrains what the settings panel does.
+ */
+export function rangeFor(...path) {
+    const rows = rowsByPath.get(pathKey(path));
+    const row = rows?.find((r) => r.min !== undefined || r.max !== undefined);
+    if (!row)
+        return undefined;
+    const range = {};
+    if (typeof row.min === 'number')
+        range.minimum = row.min;
+    if (typeof row.max === 'number')
+        range.maximum = row.max;
+    return Object.keys(range).length ? range : undefined;
+}
+/** Property paths the editor config carries guidance for. Used by tests. */
+export const GUIDED_PATHS = [...rowsByPath.keys()];
+/**
+ * The top-level members the settings panel edits on EVERY element.
+ *
+ * A row named `SpecialElementKeys.Default` is not looked up in an element's
+ * `properties` at all: it is rendered for every element, gated only by its own
+ * `additionalTest` and `disabled` tests. So the members those rows edit are
+ * part of every element's surface in the builder while appearing in no
+ * element's property list — `readonly`, `onlySetTempErrorOnTouch` and
+ * `tourContent` among them. Read here so variant assembly can offer what the
+ * builder offers, from the same source the builder reads.
+ *
+ * Only ungated rows qualify. A gated row is conditional on a VALUE (`min`
+ * needs a numeric `type`; `calculatedFieldRules` needs the flag), which is not
+ * "always shown" and is handled elsewhere. Nested bindings (`script.onChange`,
+ * `matOptions.fetch.value.source`) are members of a nested object, not of the
+ * column, and are left to the modules that own those objects.
+ */
+export const ALWAYS_SHOWN_MEMBERS = [
+    ...new Set(collectRows()
+        .filter((row) => row.name === SpecialElementKeys.Default &&
+        row.deepBind?.length === 1 &&
+        !row.additionalTest?.length &&
+        !row.disabled?.length)
+        .map((row) => row.deepBind[0])),
+];
+/**
+ * Secondary-editor paths, as `openingPath -> propertyPath`. Used by tests to
+ * assert the nested editors are actually being reached: before these were
+ * collected, every hint inside a record-list editor was invisible here, and
+ * nothing failed to say so.
+ */
+export const SECONDARY_GUIDED_PATHS = new Map([...secondaryRowsByParent].map(([parent, inner]) => [
+    parent,
+    [...inner.keys()],
+]));

package/dist/skillet/members/calculated-field.d.ts

@@ -0,0 +1,155 @@
+import { s } from '@hashbrownai/core';
+import type { CalculatedFieldRules } from '../../interfaces/formInput/calculatedFieldRules.js';
+import { CalculationFunctions } from '../../interfaces/formInput/calculationVariableInterface.js';
+/**
+ * The `calculatedFieldRules` member: a value computed from other fields rather
+ * than typed by the user.
+ *
+ * ## Why this is a draft
+ *
+ * `calculationVariableInterface` requires both `id` and `inputId` on every
+ * variable. Those are builder-assigned: `inputId` is the `id` of another input
+ * in the form, stamped when that input was created, and a model has no way to
+ * know it — the form it is authoring does not exist yet, so the ids do not
+ * either. Asked for one it will invent a plausible string, and the formula then
+ * references a field that is not there. The failure is quiet: the form saves,
+ * renders, and computes nothing.
+ *
+ * So the model binds by `formControlName`, which it genuinely does author, and
+ * the application resolves each one to that input's `id` on expansion. Both
+ * names are already on the interface — `formControlName` and
+ * `parentInputFormControl` sit alongside `inputId` and `parentInputId` — so the
+ * draft is not inventing a vocabulary. It fills in the half of each pair a
+ * model can actually know.
+ *
+ * ## The two ways a variable binds
+ *
+ * A variable reads EITHER one field's value directly, OR an aggregate over one
+ * column of a repeatable list. The second needs a set of members the first has
+ * no use for — `function`, `parentInputFormControl`, `applyFunctionToCol` — and
+ * Joi accepts them all on the same flat object, so nothing in the stored shape
+ * says which belong together. Offered flat, a model fills in
+ * `applyFunctionToCol` for a plain field and `function` for something with
+ * nothing to aggregate.
+ *
+ * They are therefore two branches of an `anyOf`, discriminated by an explicit
+ * `bindingType`. That key is NOT a member of `calculationVariableInterface`;
+ * like `endpointId` in `members/mat-options.ts` it exists only in the draft and
+ * is dropped on expansion. It earns the extra expansion step because an
+ * undiscriminated union of two objects sharing three of their keys is exactly
+ * the shape a model picks wrongly.
+ *
+ * The grouping is not invented here: `schemas/customValidationSchema.ts`
+ * annotates the same `parentInputId` + `function` pair as "Multiple-input
+ * (list) bindings", which is the distinction drawn.
+ */
+/** `roundingMode` is a string union with no runtime enum to derive from. */
+export declare const ROUNDING_MODE_VALUES: readonly ["FLOOR", "CEIL", "ROUND"];
+interface VariableCommonDraft {
+    /** The token this variable is referenced by inside `formula`. */
+    variable: string;
+    label: string;
+    formControlName: string;
+}
+export interface FieldVariableDraft extends VariableCommonDraft {
+    bindingType: 'field';
+}
+export interface ListVariableDraft extends VariableCommonDraft {
+    bindingType: 'listAggregate';
+    parentInputFormControl: string;
+    function: CalculationFunctions;
+    applyFunctionToCol: string;
+    applyFunctionToLabel: string | null;
+    filterValuesByCol: string | null;
+    filterValuesByThisColLabel: string | null;
+    tableCell: boolean | null;
+}
+export type CalculationVariableDraft = FieldVariableDraft | ListVariableDraft;
+export interface CalculatedFieldRulesDraft {
+    formula: string;
+    variables: CalculationVariableDraft[];
+    decimalPlaces: number | null;
+    roundingMode: (typeof ROUNDING_MODE_VALUES)[number] | null;
+    getFormulaFromAFormInput: boolean | null;
+    formControlWithFormula: string | null;
+}
+export declare const calculationVariableDraftSchema: import("@hashbrownai/core/src/schema/base").SchemaForUnion<{
+    bindingType: "field";
+    variable: string;
+    label: string;
+    formControlName: string;
+} | {
+    bindingType: "listAggregate";
+    variable: string;
+    label: string;
+    formControlName: string;
+    parentInputFormControl: string;
+    function: CalculationFunctions;
+    applyFunctionToCol: string;
+    applyFunctionToLabel: string | null;
+    filterValuesByCol: string | null;
+    filterValuesByThisColLabel: string | null;
+    tableCell: boolean | null;
+}>;
+/**
+ * The editor's applicability text for this row is deliberately NOT composed in.
+ *
+ * `describe(..., 'calculatedFieldRules')` resolves to "Only applies when
+ * isCalculatedField is true", which is correct in the settings panel and
+ * incoherent here: `variants.ts` encodes that rule as the shape of the union
+ * and drops `isCalculatedField` from the schema entirely, so the sentence would
+ * point a model at a member it is never shown — an invitation to invent one.
+ *
+ * This is the same judgement `internal/editor-guidance.ts` records for `label`
+ * and `options`: derived text earns its place by telling a model something it
+ * does not already have, and a rule the structure already makes unbreakable is
+ * not that.
+ */
+export declare const calculatedFieldRulesDraftSchema: s.ObjectType<{
+    formula: s.StringType;
+    variables: s.ArrayType<import("@hashbrownai/core/src/schema/base").SchemaForUnion<{
+        bindingType: "field";
+        variable: string;
+        label: string;
+        formControlName: string;
+    } | {
+        bindingType: "listAggregate";
+        variable: string;
+        label: string;
+        formControlName: string;
+        parentInputFormControl: string;
+        function: CalculationFunctions;
+        applyFunctionToCol: string;
+        applyFunctionToLabel: string | null;
+        filterValuesByCol: string | null;
+        filterValuesByThisColLabel: string | null;
+        tableCell: boolean | null;
+    }>>;
+    decimalPlaces: import("@hashbrownai/core/src/schema/base").SchemaForUnion<number | null>;
+    roundingMode: import("@hashbrownai/core/src/schema/base").SchemaForUnion<"FLOOR" | "CEIL" | "ROUND" | null>;
+    getFormulaFromAFormInput: import("@hashbrownai/core/src/schema/base").SchemaForUnion<boolean | null>;
+    formControlWithFormula: import("@hashbrownai/core/src/schema/base").SchemaForUnion<string | null>;
+}>;
+/**
+ * The draft is checked against its declared shape, not against
+ * `CalculatedFieldRules`: it deliberately differs, carrying `bindingType` and
+ * omitting the two identifiers the application supplies. What the compiler can
+ * still hold is that the node produces the draft it claims to.
+ */
+export type _NoCalculatedFieldDraftDrift = [
+    s.Infer<typeof calculatedFieldRulesDraftSchema>
+] extends [CalculatedFieldRulesDraft] ? never : ['calculatedFieldRulesDraftSchema drifted from CalculatedFieldRulesDraft'];
+/**
+ * The parts of the draft stored verbatim stay pinned to the real interface, so
+ * retyping `roundingMode` upstream surfaces here rather than in a form that
+ * silently rounds the wrong way.
+ */
+export type _RoundingModeMatchesInterface = [
+    (typeof ROUNDING_MODE_VALUES)[number]
+] extends [NonNullable<CalculatedFieldRules['roundingMode']>] ? never : ['ROUNDING_MODE_VALUES drifted from CalculatedFieldRules'];
+/**
+ * Members of a generated `calculatedFieldRules` the application must supply
+ * before Joi will accept it.
+ */
+export declare const CALCULATED_FIELD_DRAFT_COMPLETION: readonly ["calculatedFieldRules.variables[].id", "calculatedFieldRules.variables[].inputId (resolved from formControlName)", "calculatedFieldRules.variables[].parentInputId (resolved from parentInputFormControl)", "calculatedFieldRules.variables[].bindingType (draft-only; dropped on expansion)"];
+export {};

package/dist/skillet/members/calculated-field.js

@@ -0,0 +1,105 @@
+import { s } from '@hashbrownai/core';
+import { CalculationFunctions } from '../../interfaces/formInput/calculationVariableInterface.js';
+import { enumValues, exhaustive, optional } from '../internal/coupling.js';
+/**
+ * The `calculatedFieldRules` member: a value computed from other fields rather
+ * than typed by the user.
+ *
+ * ## Why this is a draft
+ *
+ * `calculationVariableInterface` requires both `id` and `inputId` on every
+ * variable. Those are builder-assigned: `inputId` is the `id` of another input
+ * in the form, stamped when that input was created, and a model has no way to
+ * know it — the form it is authoring does not exist yet, so the ids do not
+ * either. Asked for one it will invent a plausible string, and the formula then
+ * references a field that is not there. The failure is quiet: the form saves,
+ * renders, and computes nothing.
+ *
+ * So the model binds by `formControlName`, which it genuinely does author, and
+ * the application resolves each one to that input's `id` on expansion. Both
+ * names are already on the interface — `formControlName` and
+ * `parentInputFormControl` sit alongside `inputId` and `parentInputId` — so the
+ * draft is not inventing a vocabulary. It fills in the half of each pair a
+ * model can actually know.
+ *
+ * ## The two ways a variable binds
+ *
+ * A variable reads EITHER one field's value directly, OR an aggregate over one
+ * column of a repeatable list. The second needs a set of members the first has
+ * no use for — `function`, `parentInputFormControl`, `applyFunctionToCol` — and
+ * Joi accepts them all on the same flat object, so nothing in the stored shape
+ * says which belong together. Offered flat, a model fills in
+ * `applyFunctionToCol` for a plain field and `function` for something with
+ * nothing to aggregate.
+ *
+ * They are therefore two branches of an `anyOf`, discriminated by an explicit
+ * `bindingType`. That key is NOT a member of `calculationVariableInterface`;
+ * like `endpointId` in `members/mat-options.ts` it exists only in the draft and
+ * is dropped on expansion. It earns the extra expansion step because an
+ * undiscriminated union of two objects sharing three of their keys is exactly
+ * the shape a model picks wrongly.
+ *
+ * The grouping is not invented here: `schemas/customValidationSchema.ts`
+ * annotates the same `parentInputId` + `function` pair as "Multiple-input
+ * (list) bindings", which is the distinction drawn.
+ */
+/** `roundingMode` is a string union with no runtime enum to derive from. */
+export const ROUNDING_MODE_VALUES = exhaustive()(['FLOOR', 'CEIL', 'ROUND']);
+// --- schema -----------------------------------------------------------------
+const variableToken = s.string('The name this variable is referenced by inside the formula. Keep it short and lower case, and spell it identically in the formula.', { pattern: '^[a-zA-Z][a-zA-Z0-9_]*$' });
+const variableLabel = s.string('A human-readable name for this variable, shown when the formula is explained back to an administrator.');
+const fieldVariableSchema = s.object("Reads one field's value directly.", {
+    bindingType: s.literal('field'),
+    variable: variableToken,
+    label: variableLabel,
+    formControlName: s.string('The formControlName of the field on this form supplying the value. It must be a field that actually exists in the form being authored.'),
+});
+const listVariableSchema = s.object('Aggregates one column across every row of a repeatable item list.', {
+    bindingType: s.literal('listAggregate'),
+    variable: variableToken,
+    label: variableLabel,
+    formControlName: s.string('The formControlName of the column being aggregated, as it is named inside the list.'),
+    parentInputFormControl: s.string('The formControlName of the item-list field whose rows are aggregated. It must be a multipleInput field in this form.'),
+    function: s.enumeration('How the column is reduced to a single value across the rows.', enumValues(CalculationFunctions)),
+    applyFunctionToCol: s.string('The column within each row the function is applied to.'),
+    applyFunctionToLabel: optional(s.string('Display label for the aggregated column.')),
+    filterValuesByCol: optional(s.string('Restricts the aggregate to rows matching a value in this column. Leave unset to aggregate every row.')),
+    filterValuesByThisColLabel: optional(s.string('Display label for the column the rows are filtered by.')),
+    tableCell: optional(s.boolean('Whether this variable resolves to a single table cell.')),
+});
+export const calculationVariableDraftSchema = s.anyOf([
+    fieldVariableSchema,
+    listVariableSchema,
+]);
+/**
+ * The editor's applicability text for this row is deliberately NOT composed in.
+ *
+ * `describe(..., 'calculatedFieldRules')` resolves to "Only applies when
+ * isCalculatedField is true", which is correct in the settings panel and
+ * incoherent here: `variants.ts` encodes that rule as the shape of the union
+ * and drops `isCalculatedField` from the schema entirely, so the sentence would
+ * point a model at a member it is never shown — an invitation to invent one.
+ *
+ * This is the same judgement `internal/editor-guidance.ts` records for `label`
+ * and `options`: derived text earns its place by telling a model something it
+ * does not already have, and a rule the structure already makes unbreakable is
+ * not that.
+ */
+export const calculatedFieldRulesDraftSchema = s.object('How this field computes its value from other fields on the form, so the user never types a figure the system can work out: a line total, VAT, an age. Whenever a total, average, minimum, maximum or count over an item list is used anywhere else — a decision gate, a validator, another formula, a list column, the next person — it must be a calculated field like this one on the form itself, aggregating the list; the roll-up shown beneath the list is for the user only.', {
+    formula: s.string('The arithmetic expression, written using the variable names declared below and nothing else. Every name in the formula must be declared as a variable, and every declared variable should appear in the formula.'),
+    variables: s.array('The fields the formula reads, one entry per variable name used in it.', calculationVariableDraftSchema, { minItems: 1 }),
+    decimalPlaces: optional(s.integer('How many decimal places the result is rounded to: 2 for money, 0 for a count.', { minimum: 0 })),
+    roundingMode: optional(s.enumeration("How the result is rounded at that precision: 'ROUND' to the nearest, which is right for money; 'FLOOR' or 'CEIL' only when the business rule says round down or up.", [...ROUNDING_MODE_VALUES])),
+    getFormulaFromAFormInput: optional(s.boolean('Whether the formula is read from another field on the form at runtime instead of being fixed here. Leave unset unless the form genuinely lets a user supply the formula.')),
+    formControlWithFormula: optional(s.string('The formControlName of the field supplying the formula. Only meaningful when the formula is read from a form input.')),
+});
+/**
+ * Members of a generated `calculatedFieldRules` the application must supply
+ * before Joi will accept it.
+ */
+export const CALCULATED_FIELD_DRAFT_COMPLETION = [
+    'calculatedFieldRules.variables[].id',
+    'calculatedFieldRules.variables[].inputId (resolved from formControlName)',
+    'calculatedFieldRules.variables[].parentInputId (resolved from parentInputFormControl)',
+    'calculatedFieldRules.variables[].bindingType (draft-only; dropped on expansion)',
+];

package/dist/skillet/members/conditional.d.ts

@@ -0,0 +1,69 @@
+import { s } from '@hashbrownai/core';
+import type { ConditionalInputRule } from '../../interfaces/formInput/ConditionalInputRule.js';
+import { type ObservedInputDraft } from './validators.js';
+/**
+ * The `conditionalInputConfig` member: when this control is shown at all.
+ *
+ * ## Only half of the interface is offered
+ *
+ * `ConditionalInputRule` carries two shapes at once. The `expression` half is
+ * read by the engine; `formControlName`, `label`, `testType` and `valueMatch`
+ * are a legacy descriptive half, marked `@deprecated` on every member and never
+ * read by the runtime. Only the expression half is modelled, for the reason
+ * `DEPRECATED_INPUT_MEMBERS` gives in `input-members.ts`: a deprecated property
+ * left in a generation schema comes back on every form the model writes, and
+ * these four would come back describing a rule that does nothing.
+ *
+ * The consequence is worth being explicit about, because it is the one case
+ * here where narrowing changes behaviour rather than just shape: a rule with no
+ * `expression` is inert. Since the deprecated members are the only thing a rule
+ * could otherwise carry, every rule this schema produces is an active one.
+ *
+ * ## Polarity and combination come from the interface
+ *
+ * `ConditionalInputRule`'s own documentation states two things a model cannot
+ * infer from the types and gets wrong by default:
+ *
+ * - `true` means the input is REVEALED — the opposite polarity to a custom
+ *   validator's expression, where `true` means invalid. The two share a DSL and
+ *   are trivially confused.
+ * - Multiple rules combine with AND, and an empty list means always visible.
+ *
+ * Both are restated in the descriptions rather than paraphrased loosely, on the
+ * same principle that `internal/editor-guidance.ts` harvests the builder's
+ * hints instead of rewriting them.
+ *
+ * ## Why this is a draft
+ *
+ * `id` is a builder-assigned rule identifier, and the observed inputs bind by
+ * `inputId`. Both are handled exactly as in `members/validators.ts` — the model
+ * binds by `formControlName` and the application resolves it.
+ */
+export interface ConditionalRuleDraft {
+    expression: string;
+    inputsObservedForChanges: ObservedInputDraft[];
+}
+export declare const conditionalInputConfigDraftSchema: s.ArrayType<s.ObjectType<{
+    expression: s.StringType;
+    inputsObservedForChanges: s.ArrayType<s.ObjectType<{
+        formControlName: s.StringType;
+        variable: s.StringType;
+        parentInputFormControl: import("@hashbrownai/core/src/schema/base").SchemaForUnion<string | null>;
+        function: import("@hashbrownai/core/src/schema/base").SchemaForUnion<import("../../index.js").CalculationFunctions | null>;
+    }>>;
+}>>;
+/** The node produces the draft it declares. */
+export type _NoConditionalDraftDrift = [
+    s.Infer<typeof conditionalInputConfigDraftSchema>
+] extends [ConditionalRuleDraft[]] ? never : ['conditionalInputConfigDraftSchema drifted from ConditionalRuleDraft[]'];
+/**
+ * `expression` is carried through expansion untouched, so it stays pinned to
+ * the stored interface.
+ */
+export type _ExpressionMatchesStoredShape = [
+    ConditionalRuleDraft['expression']
+] extends [NonNullable<ConditionalInputRule['expression']>] ? never : ['ConditionalRuleDraft.expression drifted from ConditionalInputRule'];
+/**
+ * Members of a generated rule the application must supply.
+ */
+export declare const CONDITIONAL_DRAFT_COMPLETION: readonly ["conditionalInputConfig[].id", "conditionalInputConfig[].inputsObservedForChanges[].inputId (resolved from formControlName)", "conditionalInputConfig[].inputsObservedForChanges[].parentInputId (resolved from parentInputFormControl)"];

package/dist/skillet/members/conditional.js

@@ -0,0 +1,16 @@
+import { s } from '@hashbrownai/core';
+import { describe } from '../internal/editor-guidance.js';
+import { observedInputSchema } from './validators.js';
+const conditionalRuleSchema = s.object('One rule deciding whether this control is shown.', {
+    expression: s.string("An expression in the form engine's comparison language — NOT JavaScript — that is TRUE when this control should be SHOWN. Like a validator expression, it is true when the condition it names holds — here that condition is the reason to reveal the field. The grammar is a comparison `variable OP value`, with OP one of ===, !==, ==, !=, >, <, >=, <=, or a keyword operator includes, in, startsWith, endsWith or matches; a bare variable tests truthiness; ! negates; comparisons combine with && and || and group with parentheses; a variable may be a dotted path (reason.length > 15). There is no arithmetic, no function or method call and no ternary: to compare against a computed figure, make the figure a calculated field and compare against that field. A date is compared as an ISO string. Reference other fields only by the variable names declared below, compare against the stored option value rather than its label (urgency === 'urgent'), and put quotes around every string literal. For 'either of two conditions' write one rule with || inside it."),
+    inputsObservedForChanges: s.array('The fields the expression reads, one entry per variable name used in it.', observedInputSchema, { minItems: 1 }),
+});
+export const conditionalInputConfigDraftSchema = s.array(describe('Rules controlling when this control is visible: a follow-up question, an exception, a branch, a rejection reason when a decision toggle is off. Every rule must hold for it to be shown; leave empty to show it always. Never hide a field the engine reads.', 'conditionalInputConfig'), conditionalRuleSchema);
+/**
+ * Members of a generated rule the application must supply.
+ */
+export const CONDITIONAL_DRAFT_COMPLETION = [
+    'conditionalInputConfig[].id',
+    'conditionalInputConfig[].inputsObservedForChanges[].inputId (resolved from formControlName)',
+    'conditionalInputConfig[].inputsObservedForChanges[].parentInputId (resolved from parentInputFormControl)',
+];