ngx-t-forms-types 0.0.30 → 0.0.34

package/dist/skillet/members/pagination.js

@@ -0,0 +1,16 @@
+import { s } from '@hashbrownai/core';
+import { AllFormInputPrimaryKeys } from '../../interfaces/FormBuilder/FormInputKeys.js';
+import { optional } from '../internal/coupling.js';
+import { describe } from '../internal/editor-guidance.js';
+const paginationColumnSchema = s.object('One column shown in the selection table.', {
+    key: s.string('The property on each record whose value fills this column.'),
+    label: s.string('The column heading, in sentence case. Name what the column shows.'),
+});
+export const paginationSelectionConfigDraftSchema = s.object('How the selection table pages through records and which of their properties it shows.', {
+    useLocalPagination: optional(s.boolean(describe('Whether paging is done in the browser over an already-fetched list.', AllFormInputPrimaryKeys.PaginationSelectionConfig, 'useLocalPagination'))),
+    columns: s.array('The columns shown in the table, in order. Pick the few properties a user needs to tell one record from another.', paginationColumnSchema),
+});
+/** Members of a generated config the application must supply. */
+export const PAGINATION_DRAFT_COMPLETION = [
+    'paginationSelectionConfig.columns[].id',
+];

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

@@ -0,0 +1,178 @@
+import { s } from '@hashbrownai/core';
+import type { IMatrixInput } from '../../interfaces/formInput/MatrixInputInterface.js';
+import type { TableColumnConfigInterface } from '../../interfaces/formInput/TableConfigurationsInterface.js';
+import { AssertNever } from '../internal/coupling.js';
+import { calculatedFieldRulesDraftSchema } from './calculated-field.js';
+/**
+ * The two members that configure a table-shaped control: where a matrix reads
+ * its rows from, and how a table's columns are laid out.
+ *
+ * `matrixTableConfig` is a single string and models directly. `tableConfig`
+ * does not, and the reason is worth stating up front: its `columnsConfig` is a
+ * record keyed by column name, and Skillet has no record node. That one fact
+ * decides the shape of everything below.
+ */
+/**
+ * The `matrixTableConfig` member: which data set a matrix control renders.
+ *
+ * `{ dataSource: string }` — the whole type. Nothing here is builder-assigned
+ * and nothing is unexpressible, so this is one of the few nested configs that
+ * models as itself, with no draft and no narrowing.
+ */
+export declare const matrixTableConfigSchema: s.ObjectType<{
+    dataSource: s.StringType;
+}>;
+/**
+ * The four values `TableColumnConfigInterface['type']` admits.
+ *
+ * A string union, not an enum, so there is no runtime object to derive from and
+ * the members have to be restated. {@link exhaustive} makes restating them
+ * safe: drop one, or add a fifth to the union, and the tuple collapses to
+ * `never` and this file stops compiling.
+ *
+ * `'caluculated'` is spelled that way in the source interface. It is NOT
+ * corrected here. It is the value stored on every table already in the
+ * database, so the misspelling is the contract; "fixing" it would emit a
+ * literal nothing reads and quietly break every calculated column generated
+ * from this point on.
+ */
+export declare const TABLE_COLUMN_TYPE_VALUES: readonly ["caluculated", "property", "checkBox", "primaryKey"];
+/**
+ * One column, as the model authors it.
+ *
+ * Identical to `TableColumnConfigInterface` but for `key`, which the stored
+ * shape does not carry because there it IS the record key. Optional members
+ * surface as `| null`: Skillet has no `optional()`, so every declared key is
+ * emitted and `null` is how the model says "not set".
+ */
+export interface TableColumnDraft {
+    /**
+     * The name this column is filed under in `columnsConfig`, and the name
+     * `displayedColumnsInOrder` refers to it by.
+     */
+    key: string;
+    type: TableColumnConfigInterface['type'];
+    property: string;
+    label: string;
+    inEdit: boolean;
+    checkUpto: string;
+    calculatedFieldRules: s.Infer<typeof calculatedFieldRulesDraftSchema>;
+    reductionFunction: 'sum' | null;
+    colorScale: string | null;
+}
+/**
+ * What the model produces in place of a `TableConfigurationsInterface`.
+ *
+ * The columns arrive as a LIST, each carrying its own key. The application
+ * folds that list into the `columnsConfig` record — `key` becomes the record
+ * key and the rest of the entry becomes the value — before the input is
+ * validated. Until it does, this is not a `TableConfigurationsInterface` and
+ * must not be treated as one.
+ */
+export interface TableConfigDraft {
+    displayedColumnsInOrder: string[];
+    columns: TableColumnDraft[];
+}
+/**
+ * The `tableConfig` member: the columns of a table control.
+ *
+ * ## Why this produces a draft
+ *
+ * `columnsConfig` is declared `{ [key: string]: TableColumnConfigInterface | any }`
+ * — a record keyed by the column's own name, decided per table by whoever is
+ * authoring it. Skillet has no record or map node, so there is no way to say
+ * "an object whose keys I do not know yet and whose values all look like this".
+ * The only expressible alternatives are both bad: a fixed set of column names,
+ * which would be wrong for every table but the one it was written for, or an
+ * open object, which a model fills with structure nothing reads.
+ *
+ * So the record is INVERTED into a list. Each entry carries the key it is to be
+ * filed under, and the application folds the list back into the record before
+ * validation. A list is also the shape the second half of this config already
+ * wants: `displayedColumnsInOrder` is an ordered list of those same keys, and
+ * asking a model to keep an array and an object's key set in agreement is
+ * asking for the two to disagree.
+ *
+ * ## What is not defined here
+ *
+ * `calculatedFieldRules` belongs to `./calculated-field` and is composed in.
+ * The interface declares it REQUIRED on every column, not just calculated ones,
+ * so the node is present on every column too; the description says what to do
+ * with it on a column that computes nothing.
+ */
+export declare const tableConfigSchema: s.ObjectType<{
+    displayedColumnsInOrder: s.ArrayType<s.StringType>;
+    columns: s.ArrayType<s.ObjectType<{
+        key: s.StringType;
+        type: s.EnumType<["caluculated", "property", "checkBox", "primaryKey"]>;
+        property: s.StringType;
+        label: s.StringType;
+        inEdit: s.BooleanType;
+        checkUpto: s.StringType;
+        calculatedFieldRules: 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: import("../../index.js").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>;
+        }>;
+        reductionFunction: import("@hashbrownai/core/src/schema/base").SchemaForUnion<"sum" | null>;
+        colorScale: import("@hashbrownai/core/src/schema/base").SchemaForUnion<string | null>;
+    }>>;
+}>;
+/**
+ * `matrixTableConfig` models as itself, so it is held to the real member type.
+ */
+export type _NoMatrixTableConfigDrift = AssertNever<[
+    s.Infer<typeof matrixTableConfigSchema>
+] extends [
+    NonNullable<IMatrixInput['matrixTableConfig']>
+] ? never : 'matrixTableConfig'>;
+/**
+ * `tableConfig` is held to its DRAFT, not to `TableConfigurationsInterface`.
+ *
+ * The two differ in shape on purpose — a list of keyed columns against a record
+ * of columns — so asserting against the interface would fail by design and tell
+ * us nothing. What is worth checking is that the node keeps producing the draft
+ * the application's folding step expects, and that is what this checks. The
+ * fold itself is the caller's contract and no compiler here can see it.
+ */
+export type _NoTableConfigDraftDrift = AssertNever<[
+    s.Infer<typeof tableConfigSchema>
+] extends [TableConfigDraft] ? never : 'tableConfig'>;
+/**
+ * The draft column still covers every member of the stored column.
+ *
+ * This is the assertion the draft would otherwise lose. Because
+ * {@link _NoTableConfigDraftDrift} checks the node against a type declared in
+ * this file, both could drift away from `TableColumnConfigInterface` together
+ * without anything failing. A field added to the stored column surfaces here
+ * instead, by name.
+ */
+export type _TableColumnShapeCovered = AssertNever<Exclude<keyof TableColumnConfigInterface, keyof Omit<TableColumnDraft, 'key'>>>;
+/**
+ * What the application must do to a generated `tableConfig`.
+ *
+ * The first entry is not a missing value but a change of shape: the column LIST
+ * must be folded into the `columnsConfig` record before anything will accept
+ * it. See {@link TableConfigDraft}.
+ */
+export declare const TABLE_DRAFT_COMPLETION: readonly ["tableConfig.columns[] folded into columnsConfig, keyed by each entry's `key`", "tableConfig.columnsConfig[].calculatedFieldRules (see CALCULATED_FIELD_DRAFT_COMPLETION)"];

package/dist/skillet/members/table.js

@@ -0,0 +1,105 @@
+import { s } from '@hashbrownai/core';
+import { exhaustive, optional } from '../internal/coupling.js';
+// Calculated-field rules are owned by their own module. They appear on a table
+// column, on a plain input and inside an mSCOA config, so defining them here
+// would create a second definition that starts drifting from the first the day
+// it is written. This module composes theirs.
+import { calculatedFieldRulesDraftSchema } from './calculated-field.js';
+/**
+ * The two members that configure a table-shaped control: where a matrix reads
+ * its rows from, and how a table's columns are laid out.
+ *
+ * `matrixTableConfig` is a single string and models directly. `tableConfig`
+ * does not, and the reason is worth stating up front: its `columnsConfig` is a
+ * record keyed by column name, and Skillet has no record node. That one fact
+ * decides the shape of everything below.
+ */
+// --- matrixTableConfig ------------------------------------------------------
+/**
+ * The `matrixTableConfig` member: which data set a matrix control renders.
+ *
+ * `{ dataSource: string }` — the whole type. Nothing here is builder-assigned
+ * and nothing is unexpressible, so this is one of the few nested configs that
+ * models as itself, with no draft and no narrowing.
+ */
+export const matrixTableConfigSchema = s.object('Which data set the matrix renders its rows from. Set this on a matrix control and on nothing else.', {
+    dataSource: s.string('The name of the data set supplying the matrix rows. It must be a source the application already publishes under that name — this is a lookup key, not a description, so a plausible-sounding name that nothing serves leaves the matrix permanently empty.'),
+});
+// --- tableConfig ------------------------------------------------------------
+/**
+ * The four values `TableColumnConfigInterface['type']` admits.
+ *
+ * A string union, not an enum, so there is no runtime object to derive from and
+ * the members have to be restated. {@link exhaustive} makes restating them
+ * safe: drop one, or add a fifth to the union, and the tuple collapses to
+ * `never` and this file stops compiling.
+ *
+ * `'caluculated'` is spelled that way in the source interface. It is NOT
+ * corrected here. It is the value stored on every table already in the
+ * database, so the misspelling is the contract; "fixing" it would emit a
+ * literal nothing reads and quietly break every calculated column generated
+ * from this point on.
+ */
+export const TABLE_COLUMN_TYPE_VALUES = exhaustive()(['caluculated', 'property', 'checkBox', 'primaryKey']);
+/**
+ * `reductionFunction` is declared as the single literal `'sum'` — a union of
+ * one, which will not stay that way forever. Held under {@link exhaustive} for
+ * the same reason as the column types.
+ */
+const REDUCTION_FUNCTION_VALUES = exhaustive()(['sum']);
+/**
+ * The `tableConfig` member: the columns of a table control.
+ *
+ * ## Why this produces a draft
+ *
+ * `columnsConfig` is declared `{ [key: string]: TableColumnConfigInterface | any }`
+ * — a record keyed by the column's own name, decided per table by whoever is
+ * authoring it. Skillet has no record or map node, so there is no way to say
+ * "an object whose keys I do not know yet and whose values all look like this".
+ * The only expressible alternatives are both bad: a fixed set of column names,
+ * which would be wrong for every table but the one it was written for, or an
+ * open object, which a model fills with structure nothing reads.
+ *
+ * So the record is INVERTED into a list. Each entry carries the key it is to be
+ * filed under, and the application folds the list back into the record before
+ * validation. A list is also the shape the second half of this config already
+ * wants: `displayedColumnsInOrder` is an ordered list of those same keys, and
+ * asking a model to keep an array and an object's key set in agreement is
+ * asking for the two to disagree.
+ *
+ * ## What is not defined here
+ *
+ * `calculatedFieldRules` belongs to `./calculated-field` and is composed in.
+ * The interface declares it REQUIRED on every column, not just calculated ones,
+ * so the node is present on every column too; the description says what to do
+ * with it on a column that computes nothing.
+ */
+export const tableConfigSchema = s.object('The columns of a table control: which columns exist, what each one shows, and the order they are displayed in.', {
+    displayedColumnsInOrder: s.array('The column keys to display, left to right. Every entry must be the key of a column defined below, and a column left out of this list exists but is not shown — which is how a value is carried without being displayed, and otherwise a mistake.', s.string('The key of a column defined below.')),
+    columns: s.array('Every column this table holds. Define each one once here; the order of this list does not matter, because display order is set by displayedColumnsInOrder.', s.object('One column of the table.', {
+        key: s.string('The key this column is stored and referred to by. Derive it from the label, in lowerCamelCase, and use the same spelling in displayedColumnsInOrder.'),
+        type: s.enumeration("What the column holds. 'property' reads a stored value; 'caluculated' computes one from the calculated-field rules below; 'checkBox' renders a tick per row; 'primaryKey' is the column that identifies the row. Note the spelling of 'caluculated' — it is stored that way and must be emitted exactly as shown, not corrected.", [...TABLE_COLUMN_TYPE_VALUES]),
+        property: s.string('The property on each row this column reads. For a property column it names the field holding the value; for a primaryKey column it names the field that identifies the row.'),
+        label: s.string('The column heading, in sentence case. Name what the column contains, not how it is computed.'),
+        inEdit: s.boolean('Whether the user may edit this column in place. Leave it false for a calculated column and for the primary key, both of which are derived rather than entered.'),
+        checkUpto: s.string(
+        // Required by the stored shape, with no editor row and no other use
+        // anywhere in this package — so the description commits to the one
+        // thing that is safe rather than inventing a meaning for it.
+        'Only meaningful on a checkBox column, where it bounds how far the ticks may run. The stored shape requires the key to be present, so use an empty string on every other column type.'),
+        calculatedFieldRules: calculatedFieldRulesDraftSchema,
+        reductionFunction: optional(s.enumeration("How this column's values are reduced into the footer total. Set it only on a numeric column that genuinely totals; leave it null everywhere else, including on counts and identifiers.", [...REDUCTION_FUNCTION_VALUES])),
+        colorScale: optional(s.string('The name of a colour scale used to shade this column by value. Presentation only, and rarely wanted — leave it null unless a heat-map reading of the column was actually asked for.')),
+    })),
+});
+/**
+ * What the application must do to a generated `tableConfig`.
+ *
+ * The first entry is not a missing value but a change of shape: the column LIST
+ * must be folded into the `columnsConfig` record before anything will accept
+ * it. See {@link TableConfigDraft}.
+ */
+export const TABLE_DRAFT_COMPLETION = [
+    'tableConfig.columns[] folded into columnsConfig, keyed by each entry\'s `key`',
+    'tableConfig.columnsConfig[].calculatedFieldRules (see CALCULATED_FIELD_DRAFT_COMPLETION)',
+];

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

@@ -0,0 +1,197 @@
+import { s } from '@hashbrownai/core';
+import type { DraftFormControlCustomValidator, FormControlCustomValidatorsInterface } from '../../interfaces/formInput/FormControlCustomValidatorsInterface.js';
+import { CalculationFunctions } from '../../interfaces/formInput/calculationVariableInterface.js';
+/**
+ * The `validators` member: the checks a control must pass.
+ *
+ * ## An entry is one of two different things
+ *
+ * `validators` is typed `Array<FormControlCustomValidatorsInterface | string>`,
+ * and Joi mirrors that exactly —
+ * `Joi.array().items(Joi.alternatives().try(Joi.string(), formControlCustomValidatorSchema))`.
+ * An entry is EITHER the name of a validator the application already has, or a
+ * whole custom validator authored inline. This is the clearest case in the form
+ * model of a member where more than one kind of value is genuinely acceptable,
+ * and it is modelled as what it is: an `s.anyOf` at the ARRAY ITEM, so the two
+ * possibilities sit side by side in one list rather than being flattened into
+ * some third shape that is neither.
+ *
+ * Flattening was the alternative and it is worse in both directions. Offering
+ * only the object forces a model to write out an expression for something the
+ * application already implements; offering only the string makes every
+ * form-specific rule unexpressible.
+ *
+ * ## Why the named branch is a factory, and why it may not be offered
+ *
+ * This package declares no list of built-in validator names — they are
+ * registered by the consuming application. So the names are supplied by the
+ * caller and enumerated, exactly as `members/mat-options.ts` enumerates
+ * endpoint ids, and with none supplied the branch is withdrawn for the same
+ * reason the `api` source is: a free string invites a name that looks
+ * authoritative and resolves to nothing at runtime.
+ *
+ * Withdrawing it costs a generated form nothing. The Form Creation Guide
+ * records that the application provides five named validators — required,
+ * email, min, max and a regex pattern — and that four of them duplicate members
+ * the field already has (`required`, `min`, `max`, `pattern`) while the fifth is
+ * applied by `type: email`. Its advice is to use the members and reach for a
+ * named validator only when asked to by name, which is what the enumeration's
+ * description says too.
+ *
+ * ## Why the custom branch is a draft
+ *
+ * Two identifiers on the stored shape are assigned by the builder, not chosen:
+ *
+ * - `FormControlCustomValidatorsInterface.id`, stamped on save. The codebase
+ *   already names the id-less shape — {@link DraftFormControlCustomValidator} —
+ *   so this module does not invent that distinction, it reuses it.
+ * - `InputObservedForChange.inputId`, the id of another input in the form.
+ *   Same problem as `calculatedFieldRules`: the form being authored does not
+ *   exist yet, so neither do its ids. The model binds by `formControlName` and
+ *   the application resolves it. `parentInputFormControl` is draft-only in the
+ *   same way, standing in for `parentInputId`.
+ *
+ * ## Guidance is taken from the interface and the guide, not reinvented
+ *
+ * `InputObservedForChange` carries an unusually complete doc comment about when
+ * `function` is required and when it must be omitted — it is the one rule here
+ * a model cannot infer from the types. It is restated in the descriptions
+ * below for the same reason the editor hints are harvested in
+ * `internal/editor-guidance.ts`: the guidance already exists and a second,
+ * looser paraphrase would only drift from it.
+ *
+ * The rules for the message and for `canOverride` come from the guide's
+ * Step 5 and Step 6.2. Two of them are engine rules worth knowing the reason
+ * for: an override reason is stored in the transaction's audit trail and
+ * GRADED by the application — under 15 characters, or a stock phrase, is
+ * reported as weak — so the message has to tell the user what a good reason
+ * contains; and the guide's house rule is that a data-quality rule is never
+ * overridable, because a phone number is never "overridably" wrong.
+ */
+/** A validator the application registers, offered to the model by name. */
+export interface AvailableValidator {
+    /** The name the application registers the validator under. */
+    name: string;
+    /** What it checks, if the name does not say. */
+    description?: string;
+}
+export interface ValidatorsSchemaOptions {
+    /**
+     * Validators the application already provides, which the model may name.
+     * Omit, or pass an empty list, and only inline rules are offered — the safe
+     * default, because the alternative is a fabricated name.
+     */
+    namedValidators?: readonly AvailableValidator[];
+}
+export interface ObservedInputDraft {
+    /** Resolved to `InputObservedForChange.inputId` on expansion. */
+    formControlName: string;
+    variable: string;
+    /** Resolved to `InputObservedForChange.parentInputId` on expansion. */
+    parentInputFormControl: string | null;
+    function: CalculationFunctions | null;
+}
+export interface CustomValidatorDraft {
+    message: string;
+    expression: string;
+    canOverride: boolean;
+    inputsObservedForChanges: ObservedInputDraft[];
+}
+export type ValidatorEntryDraft = string | CustomValidatorDraft;
+/**
+ * One dependency of an expression.
+ *
+ * Exported because `conditionalInputConfig` observes its inputs through the
+ * very same `InputObservedForChange`, and a property must mean the same thing
+ * everywhere it appears — the rule the member registry in `input-members.ts`
+ * states for itself. Redeclaring it there would let the two descriptions drift
+ * apart while the stored shape stayed identical.
+ */
+export declare const observedInputSchema: 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<CalculationFunctions | null>;
+}>;
+/**
+ * Builds the `validators` schema for the named validators the caller has.
+ *
+ * Two whole array nodes rather than one whose item is conditionally a union:
+ * the inferred type has to be a union of the two shapes for the drift
+ * assertion below to hold each branch to {@link ValidatorEntryDraft}.
+ *
+ * @param options the validators the model may name. Empty — the default —
+ *   offers inline rules only.
+ */
+export declare function createValidatorsSchema(options?: ValidatorsSchemaOptions): s.ArrayType<import("@hashbrownai/core/src/schema/base").SchemaForUnion<string | {
+    message: string;
+    expression: string;
+    canOverride: boolean;
+    inputsObservedForChanges: {
+        formControlName: string;
+        variable: string;
+        parentInputFormControl: string | null;
+        function: CalculationFunctions | null;
+    }[];
+}>> | s.ArrayType<s.ObjectType<{
+    message: s.StringType;
+    expression: s.StringType;
+    canOverride: s.BooleanType;
+    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<CalculationFunctions | null>;
+    }>>;
+}>>;
+/**
+ * The default `validators` schema: no named validators, so only rules written
+ * inline are offered. Callers whose application registers validators should
+ * pass their names through `namedValidators` on the column options instead.
+ */
+export declare const validatorsDraftSchema: s.ArrayType<import("@hashbrownai/core/src/schema/base").SchemaForUnion<string | {
+    message: string;
+    expression: string;
+    canOverride: boolean;
+    inputsObservedForChanges: {
+        formControlName: string;
+        variable: string;
+        parentInputFormControl: string | null;
+        function: CalculationFunctions | null;
+    }[];
+}>> | s.ArrayType<s.ObjectType<{
+    message: s.StringType;
+    expression: s.StringType;
+    canOverride: s.BooleanType;
+    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<CalculationFunctions | null>;
+    }>>;
+}>>;
+/** The schema the factory builds, whichever names it was given. */
+type ValidatorsSchema = ReturnType<typeof createValidatorsSchema>;
+/** Both shapes the factory can build produce the draft they declare. */
+export type _NoValidatorDraftDrift = [s.Infer<ValidatorsSchema>] extends [
+    ValidatorEntryDraft[]
+] ? never : ['createValidatorsSchema drifted from ValidatorEntryDraft[]'];
+/**
+ * The members carried through expansion untouched stay pinned to the stored
+ * interface. Only `inputsObservedForChanges` is excluded, because that is the
+ * part the draft deliberately reshapes; retyping `message`, `expression` or
+ * `canOverride` upstream still surfaces here.
+ */
+export type _DraftMatchesStoredShape = [
+    Omit<CustomValidatorDraft, 'inputsObservedForChanges'>
+] extends [Omit<DraftFormControlCustomValidator, 'inputsObservedForChanges'>] ? never : ['CustomValidatorDraft drifted from DraftFormControlCustomValidator'];
+/** The string branch really is a member of the stored union. */
+export type _NamedBranchIsStorable = [string] extends [
+    FormControlCustomValidatorsInterface | string
+] ? never : ['the named-validator branch is not assignable to a stored validator'];
+/**
+ * Members of a generated validator the application must supply before Joi will
+ * accept it.
+ */
+export declare const VALIDATOR_DRAFT_COMPLETION: readonly ["validators[].id", "validators[].inputsObservedForChanges[].inputId (resolved from formControlName)", "validators[].inputsObservedForChanges[].parentInputId (resolved from parentInputFormControl)"];
+export {};

package/dist/skillet/members/validators.js

@@ -0,0 +1,74 @@
+import { s } from '@hashbrownai/core';
+import { CalculationFunctions } from '../../interfaces/formInput/calculationVariableInterface.js';
+import { enumValues, optional } from '../internal/coupling.js';
+import { describe } from '../internal/editor-guidance.js';
+// --- schema -----------------------------------------------------------------
+/**
+ * One dependency of an expression.
+ *
+ * Exported because `conditionalInputConfig` observes its inputs through the
+ * very same `InputObservedForChange`, and a property must mean the same thing
+ * everywhere it appears — the rule the member registry in `input-members.ts`
+ * states for itself. Redeclaring it there would let the two descriptions drift
+ * apart while the stored shape stayed identical.
+ */
+export const observedInputSchema = s.object('One input the expression reads.', {
+    formControlName: s.string('The formControlName of the field being read. It must be a field that actually exists in the form being authored.'),
+    variable: s.string('The name the expression references this value by. Use the same spelling in the expression exactly.', { pattern: '^[a-zA-Z][a-zA-Z0-9_]*$' }),
+    parentInputFormControl: optional(s.string('Only for a field inside a repeatable item list: the formControlName of the list containing it. Leave unset for an ordinary field.')),
+    function: optional(s.enumeration('How a list column is reduced to a single value. Required when this validator sits on an ordinary field but reads a field inside a list, because the expression cannot compare against an array. Leave unset when the validator and the field it reads are in the same list, where a row resolves to its own value.', enumValues(CalculationFunctions))),
+});
+/**
+ * The custom branch: a rule written for this form.
+ *
+ * `expression` is free text by necessity — it is evaluated at runtime and this
+ * package holds no parser to constrain it against. The description therefore
+ * does the constraining: it states the engine's grammar in prose — a comparison
+ * language that is emphatically not JavaScript — and ties every name in an
+ * expression to the declared variables.
+ */
+const customValidatorSchema = s.object('A validation rule written specifically for this form: a check of this field against a rule, often involving other fields, that the ordinary limits cannot express.', {
+    message: s.string("The message shown to the user when the check fails: one sentence saying what is wrong and what to do, starting with the action — 'Enter a delivery date that is after today', 'Select at least one item'. Be specific to the rule, never write 'invalid', 'error', 'please' or 'sorry', and do not repeat the hint. When the check can be overridden, say what a good reason contains, because the reason is stored, graded and read by reviewers: 'Total exceeds the available budget. To continue, state who approved the excess and attach the approval'."),
+    expression: s.string("An expression in the form engine's comparison language — NOT JavaScript — that is TRUE when the value must be REJECTED. It states the fault, not the requirement: for a spending limit write amount > limit, never amount <= limit; for an end date write endDate < startDate. 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. The message above is what the user is shown when the expression holds. Reference other fields only by the variable names declared below, and put quotes around every string literal you compare against (urgency === 'urgent')."),
+    canOverride: s.boolean('Whether the form may still be submitted while this check fails. Ask of every rule whether there is a legitimate exception: if there is, true, and the user must type a reason that is stored in the audit trail and shown to reviewers — the established case is a total that exceeds the available budget. If there is not, false, and the form cannot be submitted. Never make a data-quality rule overridable; a phone number is never overridably wrong.'),
+    inputsObservedForChanges: s.array('Every field the expression reads, one entry per variable name used in it — including this field itself when the expression tests its own value. An expression sees nothing but the variables declared here, not even the field it sits on, and an undeclared name is not an error: it reads as an absent field or as literal text, and the rule silently never fires.', observedInputSchema),
+});
+/** Renders the supplied names into prose so the model chooses on meaning. */
+function namedValidatorSchema(validators) {
+    const candidates = validators
+        .map((v) => (v.description ? `${v.name} (${v.description})` : v.name))
+        .join('; ');
+    return s.enumeration(`The name of a validator the application already provides, chosen by meaning: ${candidates}. Reach for one only when the request asks for it by name. The ordinary limits are members of the field, not validators: required, min, max, minLength, maxLength and pattern, with the email check applied by type email.`, validators.map((v) => v.name));
+}
+const VALIDATORS_DESCRIPTION = describe("The checks this control must pass, beyond being filled in. Leave empty unless the form states a real rule; the ordinary limits — required, min, max, minLength, maxLength, pattern — are the field's own members and need no validator.", 'validators');
+/**
+ * Builds the `validators` schema for the named validators the caller has.
+ *
+ * Two whole array nodes rather than one whose item is conditionally a union:
+ * the inferred type has to be a union of the two shapes for the drift
+ * assertion below to hold each branch to {@link ValidatorEntryDraft}.
+ *
+ * @param options the validators the model may name. Empty — the default —
+ *   offers inline rules only.
+ */
+export function createValidatorsSchema(options = {}) {
+    const named = options.namedValidators ?? [];
+    return named.length
+        ? s.array(VALIDATORS_DESCRIPTION, s.anyOf([namedValidatorSchema(named), customValidatorSchema]))
+        : s.array(VALIDATORS_DESCRIPTION, customValidatorSchema);
+}
+/**
+ * The default `validators` schema: no named validators, so only rules written
+ * inline are offered. Callers whose application registers validators should
+ * pass their names through `namedValidators` on the column options instead.
+ */
+export const validatorsDraftSchema = createValidatorsSchema();
+/**
+ * Members of a generated validator the application must supply before Joi will
+ * accept it.
+ */
+export const VALIDATOR_DRAFT_COMPLETION = [
+    'validators[].id',
+    'validators[].inputsObservedForChanges[].inputId (resolved from formControlName)',
+    'validators[].inputsObservedForChanges[].parentInputId (resolved from parentInputFormControl)',
+];