ngx-t-forms-types 0.0.30 → 0.0.34

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

@@ -0,0 +1,154 @@
+import { s } from '@hashbrownai/core';
+import type { IBasicFormInput } from '../../interfaces/formInput/BasicFormInputInterface.js';
+import { CalculationFunctions } from '../../interfaces/formInput/calculationVariableInterface.js';
+import type { IMultipleInputCal } from '../../interfaces/formInput/MultipleInterface.js';
+import { AssertNever } from '../internal/coupling.js';
+/**
+ * Three members that carry a value rather than describe a control: the value an
+ * input starts with, the script hook it fires, and the roll-ups a repeatable
+ * group computes over its own rows.
+ *
+ * They are grouped because they share one problem. Each is declared in the
+ * interfaces with a type wide enough to hold anything the running application
+ * might put there — a `File`, an open `Record`, a builder-assigned id — and in
+ * every case the widest part is exactly the part a model cannot produce. So
+ * each node here is narrower than its member, and one of them is a draft.
+ */
+/**
+ * The `value` member: what the control holds before the user touches it.
+ *
+ * ## Deliberate narrowing
+ *
+ * The interface declares
+ * `number | string | boolean | Date | File | {[key: string]: any} | Array<{[key: string]: any}>`,
+ * and the Joi schema accepts the same set (with `''` explicitly allowed on the
+ * string branch). This node offers three of those seven branches:
+ *
+ * - `Date` — a model emits JSON, and the best JSON carries is an ISO string. A
+ *   string is not assignable to `Date`, so a "date default" authored here would
+ *   be a mistyped value that only fails somewhere far from this schema. A real
+ *   date default needs the draft-and-expand treatment, not a quiet coercion,
+ *   and until something does that it is better refused.
+ * - `File` — a browser runtime object. It has no JSON representation at all; it
+ *   exists only once a user has picked something off their disk.
+ * - `{[key: string]: any}` and `Array<{[key: string]: any}>` — index
+ *   signatures. Skillet has no record node, so the shape cannot be expressed,
+ *   and a model asked for an open object has no basis for inventing keys. What
+ *   it would produce is plausible-looking structure that nothing reads.
+ *
+ * The three that remain — number, string, boolean — ARE members of the declared
+ * union, so the node stays assignable to the member: narrower than the
+ * interface, never wider. That is the direction `internal/coupling.ts` fails
+ * on. A schema may refuse a value the interface tolerates; it may never admit
+ * one the interface cannot hold, because that is the drift that produces a
+ * value the rest of the codebase has nowhere to put.
+ *
+ * ## Why this one is a union at all
+ *
+ * Most members have a single type. This one genuinely does not: the same
+ * property holds `0` on a numeric input, `'Pretoria'` on a text input and
+ * `false` on a toggle, and which is correct is decided entirely by the element
+ * the model has already chosen. So the branches are described by the CONTROL
+ * each belongs to rather than by its JavaScript type — a model choosing between
+ * "a number" and "a string" is choosing on the wrong axis, and will reach for a
+ * string on a numeric field because the label sounded textual.
+ *
+ * A union node has no description slot of its own, so the rule that governs all
+ * three branches — agree with `dataType` — is stated on each of them.
+ */
+export declare const valueSchema: import("@hashbrownai/core/src/schema/base").SchemaForUnion<string | number | boolean>;
+/**
+ * The `script` member: application behaviour attached to the control.
+ *
+ * Declared as `Record<string, unknown>` and validated as a bare `Joi.object()`,
+ * so at the type level it is an open map and nothing constrains its keys.
+ * Skillet has no record node and an open map is not expressible in it — but
+ * modelling this as "some object" would be worse than not modelling it at all,
+ * because a model handed an open slot fills it. Every key it invented would be
+ * accepted by the interface, accepted by Joi, stored on the input, and then
+ * ignored at runtime by an application that only reads keys it already knows.
+ *
+ * The form builder answers what those keys are: its editor declares exactly one
+ * row for this member, at the `deepBind` path `['script', 'onChange']`. That is
+ * the entire surface a human author is offered, so it is the entire surface
+ * offered here. A closed object carrying that single key is still assignable to
+ * `Record<string, unknown>`, which keeps the coupling honest while leaving the
+ * model no room to invent hooks that do not exist.
+ */
+export declare const scriptSchema: s.ObjectType<{
+    onChange: s.StringType;
+}>;
+/**
+ * The `calculateListFunctions` member of a repeatable group: the roll-ups shown
+ * across its rows.
+ *
+ * ## Why this produces a draft
+ *
+ * `IMultipleInputCal` is
+ * `{ id: string; inputId: string; func: CalculationFunctions }`, and Joi
+ * requires all three. Two of the three are identifiers the builder assigns:
+ * `id` names the roll-up itself, and `inputId` is the stored `id` of the column
+ * being aggregated — a value that does not exist until that column has been
+ * created and persisted. A model asked for either produces a convincing uuid
+ * pointing at nothing, and the failure is silent: the roll-up renders, resolves
+ * no column, and totals nothing.
+ *
+ * What the model does author, and authors reliably, is `formControlName` — it
+ * chose the name itself, a few properties earlier in the same form. So the
+ * draft names the target column and the application resolves that name to an
+ * `inputId` and stamps an `id`, the same trade already made for `inputSourceId`
+ * on a local `matOptions` source, where the model names a field and the
+ * application turns the name into a reference.
+ *
+ * The resolution step is the caller's and there is no way around it. What stays
+ * checked here is that the draft keeps the shape it declares.
+ */
+export interface CalculateListFunctionDraft {
+    /**
+     * The `formControlName` of the column inside this group to aggregate. It must
+     * name a field that actually exists in the group being authored.
+     */
+    formControlName: string;
+    /** Which aggregate to compute over that column. */
+    func: CalculationFunctions;
+}
+/** What the model produces in place of `Array<IMultipleInputCal>`. */
+export type CalculateListFunctionsDraft = CalculateListFunctionDraft[];
+export declare const calculateListFunctionsSchema: s.ArrayType<s.ObjectType<{
+    formControlName: s.StringType;
+    func: s.EnumType<CalculationFunctions[]>;
+}>>;
+/**
+ * The `value` node still produces something its member can hold. Narrowing is
+ * the point of that node, and this is what proves the narrowing stayed INSIDE
+ * the declared union rather than drifting out of it.
+ */
+export type _NoValueMemberDrift = AssertNever<[
+    s.Infer<typeof valueSchema>
+] extends [NonNullable<IBasicFormInput['value']>] ? never : 'value'>;
+/** The closed `script` object is still assignable to the open record. */
+export type _NoScriptMemberDrift = AssertNever<[
+    s.Infer<typeof scriptSchema>
+] extends [NonNullable<IBasicFormInput['script']>] ? never : 'script'>;
+/**
+ * The roll-up node produces the draft it declares. The expansion from draft to
+ * `IMultipleInputCal` is the caller's, but the draft itself stays checked.
+ */
+export type _NoCalculateListFunctionsDraftDrift = AssertNever<[
+    s.Infer<typeof calculateListFunctionsSchema>
+] extends [
+    CalculateListFunctionsDraft
+] ? never : 'calculateListFunctions'>;
+/**
+ * Every member of the stored `IMultipleInputCal` is accounted for: `func` is
+ * authored, `id` and `inputId` are assigned by the application. A fourth field
+ * added to that interface fails here, which forces the question of whether a
+ * model can author it — rather than letting the draft quietly stop covering the
+ * shape it is expanded into.
+ */
+export type _CalculateListFunctionShapeAccountedFor = AssertNever<Exclude<keyof IMultipleInputCal, 'id' | 'inputId' | 'func'>>;
+/**
+ * Members of a generated `calculateListFunctions` the application must supply.
+ * Both are required by Joi, so an unexpanded draft fails validation.
+ */
+export declare const CALCULATE_LIST_DRAFT_COMPLETION: readonly ["calculateListFunctions[].id", "calculateListFunctions[].inputId (resolved from formControlName)"];

package/dist/skillet/members/value.js

@@ -0,0 +1,97 @@
+import { s } from '@hashbrownai/core';
+import { CalculationFunctions } from '../../interfaces/formInput/calculationVariableInterface.js';
+import { enumValues } from '../internal/coupling.js';
+import { describe } from '../internal/editor-guidance.js';
+/**
+ * Three members that carry a value rather than describe a control: the value an
+ * input starts with, the script hook it fires, and the roll-ups a repeatable
+ * group computes over its own rows.
+ *
+ * They are grouped because they share one problem. Each is declared in the
+ * interfaces with a type wide enough to hold anything the running application
+ * might put there — a `File`, an open `Record`, a builder-assigned id — and in
+ * every case the widest part is exactly the part a model cannot produce. So
+ * each node here is narrower than its member, and one of them is a draft.
+ */
+// --- value ------------------------------------------------------------------
+/**
+ * The `value` member: what the control holds before the user touches it.
+ *
+ * ## Deliberate narrowing
+ *
+ * The interface declares
+ * `number | string | boolean | Date | File | {[key: string]: any} | Array<{[key: string]: any}>`,
+ * and the Joi schema accepts the same set (with `''` explicitly allowed on the
+ * string branch). This node offers three of those seven branches:
+ *
+ * - `Date` — a model emits JSON, and the best JSON carries is an ISO string. A
+ *   string is not assignable to `Date`, so a "date default" authored here would
+ *   be a mistyped value that only fails somewhere far from this schema. A real
+ *   date default needs the draft-and-expand treatment, not a quiet coercion,
+ *   and until something does that it is better refused.
+ * - `File` — a browser runtime object. It has no JSON representation at all; it
+ *   exists only once a user has picked something off their disk.
+ * - `{[key: string]: any}` and `Array<{[key: string]: any}>` — index
+ *   signatures. Skillet has no record node, so the shape cannot be expressed,
+ *   and a model asked for an open object has no basis for inventing keys. What
+ *   it would produce is plausible-looking structure that nothing reads.
+ *
+ * The three that remain — number, string, boolean — ARE members of the declared
+ * union, so the node stays assignable to the member: narrower than the
+ * interface, never wider. That is the direction `internal/coupling.ts` fails
+ * on. A schema may refuse a value the interface tolerates; it may never admit
+ * one the interface cannot hold, because that is the drift that produces a
+ * value the rest of the codebase has nowhere to put.
+ *
+ * ## Why this one is a union at all
+ *
+ * Most members have a single type. This one genuinely does not: the same
+ * property holds `0` on a numeric input, `'Pretoria'` on a text input and
+ * `false` on a toggle, and which is correct is decided entirely by the element
+ * the model has already chosen. So the branches are described by the CONTROL
+ * each belongs to rather than by its JavaScript type — a model choosing between
+ * "a number" and "a string" is choosing on the wrong axis, and will reach for a
+ * string on a numeric field because the label sounded textual.
+ *
+ * A union node has no description slot of its own, so the rule that governs all
+ * three branches — agree with `dataType` — is stated on each of them.
+ */
+export const valueSchema = s.anyOf([
+    s.number('A numeric starting value, for a control whose dataType is number: a quantity, a rate, an amount. Write it as a JSON number, never as a quoted string. Use 0 only where zero is a meaningful default rather than a stand-in for "empty" — an untouched numeric field is better left with no value at all than pre-filled with a figure the user may not notice and may not mean.'),
+    s.string('A text starting value, for a control whose dataType is string: a default selection, a standard reference, a boilerplate line. This is also the branch for a date control, whose value must then be written as an ISO date string. The empty string is permitted and means "starts blank", which is the same as omitting the member; prefer omitting it.'),
+    s.boolean('A starting state for a toggle, checkbox or slide toggle, whose dataType is boolean. Set it to the state the user should not have to change: false where the affirmative is the exception, true where consent or inclusion is the norm for this form.'),
+]);
+// --- script -----------------------------------------------------------------
+/**
+ * The `script` member: application behaviour attached to the control.
+ *
+ * Declared as `Record<string, unknown>` and validated as a bare `Joi.object()`,
+ * so at the type level it is an open map and nothing constrains its keys.
+ * Skillet has no record node and an open map is not expressible in it — but
+ * modelling this as "some object" would be worse than not modelling it at all,
+ * because a model handed an open slot fills it. Every key it invented would be
+ * accepted by the interface, accepted by Joi, stored on the input, and then
+ * ignored at runtime by an application that only reads keys it already knows.
+ *
+ * The form builder answers what those keys are: its editor declares exactly one
+ * row for this member, at the `deepBind` path `['script', 'onChange']`. That is
+ * the entire surface a human author is offered, so it is the entire surface
+ * offered here. A closed object carrying that single key is still assignable to
+ * `Record<string, unknown>`, which keeps the coupling honest while leaving the
+ * model no room to invent hooks that do not exist.
+ */
+export const scriptSchema = s.object('Application behaviour attached to this control. Set this only where the form genuinely has to react to this field changing; most inputs carry no script at all.', {
+    onChange: s.string(describe('The name of the handler the host application runs when this value changes. It must be a handler the application already registers — an unrecognised name is ignored at runtime, so inventing one produces a field that looks wired up and does nothing.', 'script', 'onChange')),
+});
+export const calculateListFunctionsSchema = s.array('Totals and averages computed across the rows of this repeatable group and shown beneath it. Add one entry per figure the user should see summarised; leave the list empty when the rows do not roll up to anything meaningful. These are for the user only: a figure used anywhere else — a decision gate, a validator, a list column — must also be a calculated field on the form itself, aggregating this list.', s.object('One roll-up over one column of the group.', {
+    formControlName: s.string('The formControlName of the column to aggregate. It must be a field that exists inside this repeatable group, and — except for a count — a field that holds a number.'),
+    func: s.enumeration('Which aggregate to compute. Use count to report how many rows were captured: it is the only function that does not need a numeric column.', enumValues(CalculationFunctions)),
+}));
+/**
+ * Members of a generated `calculateListFunctions` the application must supply.
+ * Both are required by Joi, so an unexpanded draft fails validation.
+ */
+export const CALCULATE_LIST_DRAFT_COMPLETION = [
+    'calculateListFunctions[].id',
+    'calculateListFunctions[].inputId (resolved from formControlName)',
+];

package/dist/skillet/shared-types.d.ts

@@ -0,0 +1,57 @@
+import { s } from '@hashbrownai/core';
+import { AdjudicationSteps, AutocompleteOptions, AutocapitalizeOptions, ElementTypes, InputDataTypes, InputPipeTypes, InputTypes } from '../interfaces/formInput/index.js';
+import { DataSources } from '../interfaces/formInput/APIDataFetchingConfigurationInterface.js';
+import { InputViewTypes, OptionSelectTypes } from '../interfaces/formInput/BasicFormInputInterface.js';
+import { InputFileType } from '../interfaces/formInput/FileUploadInputInterface.js';
+import { AccountingBasis } from '../interfaces/formInput/IMscoaAccount.js';
+import { MultipleInputAvailableOperations } from '../interfaces/formInput/MultipleInterface.js';
+import { RichTextEditorType } from '../interfaces/formInput/RichTextEditorInput.js';
+import { LabelPosition } from '../interfaces/formInput/ToggleInputInterface.js';
+/**
+ * Skillet nodes for the shared vocabulary — every closed set of values a form
+ * input can carry.
+ *
+ * Enum-backed nodes call {@link enumValues}, so their entries are read off the
+ * live enum at module evaluation. There is no list here to fall out of date:
+ * adding `ElementTypes.Foo` puts `'foo'` in the schema and widens `s.Infer`
+ * automatically. Only the DESCRIPTION is authored, and the description is the
+ * part that actually steers the model.
+ *
+ * Union-backed nodes (types with no runtime object to read) go through
+ * {@link exhaustive}, which fails to compile if the restated tuple drifts from
+ * the union.
+ */
+export declare const elementTypeSchema: s.EnumType<ElementTypes[]>;
+export declare const inputTypeSchema: s.EnumType<InputTypes[]>;
+export declare const inputDataTypeSchema: s.EnumType<InputDataTypes[]>;
+export declare const inputViewTypeSchema: s.EnumType<InputViewTypes.ViewOnly[]>;
+/**
+ * `MatFormFieldAppearance` is a string-union type, not an enum, so its members
+ * are restated here under {@link exhaustive} rather than derived.
+ */
+export declare const APPEARANCE_VALUES: readonly ["fill", "outline"];
+export declare const appearanceSchema: s.EnumType<["fill", "outline"]>;
+export declare const labelPositionSchema: s.EnumType<LabelPosition[]>;
+export declare const optionSelectTypeSchema: s.EnumType<OptionSelectTypes[]>;
+/**
+ * `AutocompleteOptions` is a two-member enum — `on` and `off`.
+ *
+ * The description used to tell the model to "use a specific token such as email
+ * or tel", which is what the HTML `autocomplete` attribute accepts but NOT what
+ * this enum offers. A model following it emitted `email`, which is not a member,
+ * so the value was rejected — an instruction the schema itself made impossible
+ * to obey. Derived entries and authored prose have to agree, and here only the
+ * prose could be wrong.
+ */
+export declare const autocompleteSchema: s.EnumType<AutocompleteOptions[]>;
+export declare const autocapitalizeSchema: s.EnumType<AutocapitalizeOptions[]>;
+/** `wrap` is declared inline on the textarea interface as a string union. */
+export declare const TEXTAREA_WRAP_VALUES: readonly ["hard", "soft"];
+export declare const textareaWrapSchema: s.EnumType<["hard", "soft"]>;
+export declare const inputPipeTypeSchema: s.EnumType<InputPipeTypes[]>;
+export declare const richTextEditorTypeSchema: s.EnumType<RichTextEditorType[]>;
+export declare const inputFileTypeSchema: s.EnumType<InputFileType[]>;
+export declare const dataSourceSchema: s.EnumType<DataSources[]>;
+export declare const multipleInputOperationSchema: s.EnumType<MultipleInputAvailableOperations[]>;
+export declare const adjudicationStepSchema: s.EnumType<AdjudicationSteps[]>;
+export declare const accountingBasisSchema: s.EnumType<AccountingBasis[]>;

package/dist/skillet/shared-types.js

@@ -0,0 +1,69 @@
+import { s } from '@hashbrownai/core';
+import { AdjudicationSteps, AutocompleteOptions, AutocapitalizeOptions, ElementTypes, InputDataTypes, InputPipeTypes, InputTypes, } from '../interfaces/formInput/index.js';
+import { DataSources } from '../interfaces/formInput/APIDataFetchingConfigurationInterface.js';
+import { InputViewTypes, OptionSelectTypes, } from '../interfaces/formInput/BasicFormInputInterface.js';
+import { InputFileType } from '../interfaces/formInput/FileUploadInputInterface.js';
+import { AccountingBasis } from '../interfaces/formInput/IMscoaAccount.js';
+import { MultipleInputAvailableOperations } from '../interfaces/formInput/MultipleInterface.js';
+import { RichTextEditorType } from '../interfaces/formInput/RichTextEditorInput.js';
+import { LabelPosition } from '../interfaces/formInput/ToggleInputInterface.js';
+import { enumValues, exhaustive } from './internal/coupling.js';
+import { describe } from './internal/editor-guidance.js';
+/**
+ * Skillet nodes for the shared vocabulary — every closed set of values a form
+ * input can carry.
+ *
+ * Enum-backed nodes call {@link enumValues}, so their entries are read off the
+ * live enum at module evaluation. There is no list here to fall out of date:
+ * adding `ElementTypes.Foo` puts `'foo'` in the schema and widens `s.Infer`
+ * automatically. Only the DESCRIPTION is authored, and the description is the
+ * part that actually steers the model.
+ *
+ * Union-backed nodes (types with no runtime object to read) go through
+ * {@link exhaustive}, which fails to compile if the restated tuple drifts from
+ * the union.
+ */
+// --- Element identity -------------------------------------------------------
+export const elementTypeSchema = s.enumeration(describe('The kind of control to render. This determines which other properties are meaningful, so choose it first and let it drive the rest.', 'element'), enumValues(ElementTypes));
+export const inputTypeSchema = s.enumeration(describe("The native HTML input type, for elements that render an <input>. Match it to the data: 'number' for a quantity, an amount or a percentage; 'email'; 'tel' for a phone number; 'url'; 'password' for a one-time code; 'date' for a memorable date typed from memory such as a date of birth; 'time' or 'month'; 'text' for names, references and codes.", 'type'), enumValues(InputTypes));
+export const inputDataTypeSchema = s.enumeration(describe("The JavaScript type the captured value is stored as: 'number' for a numeric input or a calculated field, 'boolean' for a toggle, 'date' for a date picker, 'array' for an item list, 'object' for a file, a location or an account picker, 'string' for everything else.", 'dataType'), enumValues(InputDataTypes));
+export const inputViewTypeSchema = s.enumeration(describe('Renders the control as read-only presentation rather than an editable field.', 'viewType'), enumValues(InputViewTypes));
+// --- Presentation -----------------------------------------------------------
+/**
+ * `MatFormFieldAppearance` is a string-union type, not an enum, so its members
+ * are restated here under {@link exhaustive} rather than derived.
+ */
+export const APPEARANCE_VALUES = exhaustive()([
+    'fill',
+    'outline',
+]);
+export const appearanceSchema = s.enumeration(describe("The Material form-field style. Use 'outline' unless the surrounding form already uses 'fill'; do not mix the two within one form.", 'appearance'), [...APPEARANCE_VALUES]);
+export const labelPositionSchema = s.enumeration(describe("Which side of a toggle its label sits on. Use 'after'.", 'labelPosition'), enumValues(LabelPosition));
+export const optionSelectTypeSchema = s.enumeration(describe("How a set of options is presented: 'radioButton' for one choice from two to five fixed options, so the user can scan them all at once; 'dropDown' for six or more, sorted alphabetically unless there is a natural order; 'chipSelect' when several options are chosen together from a short list. A short list left as a dropdown is a common mistake.", 'optionSelectType'), enumValues(OptionSelectTypes));
+/**
+ * `AutocompleteOptions` is a two-member enum — `on` and `off`.
+ *
+ * The description used to tell the model to "use a specific token such as email
+ * or tel", which is what the HTML `autocomplete` attribute accepts but NOT what
+ * this enum offers. A model following it emitted `email`, which is not a member,
+ * so the value was rejected — an instruction the schema itself made impossible
+ * to obey. Derived entries and authored prose have to agree, and here only the
+ * prose could be wrong.
+ */
+export const autocompleteSchema = s.enumeration(describe('Whether the browser may autofill this field from the user profile.', 'autocomplete'), enumValues(AutocompleteOptions));
+export const autocapitalizeSchema = s.enumeration(describe("How the on-screen keyboard capitalises typed text. Use 'words' for names and 'characters' for reference codes.", 'autocapitalize'), enumValues(AutocapitalizeOptions));
+/** `wrap` is declared inline on the textarea interface as a string union. */
+export const TEXTAREA_WRAP_VALUES = exhaustive()([
+    'hard',
+    'soft',
+]);
+export const textareaWrapSchema = s.enumeration(describe("How a textarea wraps long lines when the form is submitted. 'soft' leaves the text unchanged; 'hard' inserts real newlines at the wrap points.", 'wrap'), [...TEXTAREA_WRAP_VALUES]);
+export const inputPipeTypeSchema = s.enumeration(describe('A display transform applied to the value when it is shown back to the user. This is presentation only and never changes the stored value.', 'pipe', 'pipeType'), enumValues(InputPipeTypes));
+export const richTextEditorTypeSchema = s.enumeration(describe('Which rich-text editor library backs an editor element.', 'richTextEditorLibrary'), enumValues(RichTextEditorType));
+export const inputFileTypeSchema = s.enumeration(describe("The kind of upload a file control accepts: 'file' for a document such as a quote, an invoice or a certificate; 'captureImage' for a photo taken on the phone camera; 'image' for a picture from disk.", 'fileType'), enumValues(InputFileType));
+// --- Data sourcing ----------------------------------------------------------
+export const dataSourceSchema = s.enumeration("Where a control's options come from: values typed into the form definition, an HTTP endpoint, a MongoDB aggregation pipeline, or a custom option set.", enumValues(DataSources));
+// --- Domain-specific --------------------------------------------------------
+export const multipleInputOperationSchema = s.enumeration(describe('An operation a user may perform on the rows of a repeatable multiple-input group.', 'multipleInputAvailableOperations'), enumValues(MultipleInputAvailableOperations));
+export const adjudicationStepSchema = s.enumeration(describe('Which stage of the tender adjudication workflow this control belongs to.', 'adjudicationStep'), enumValues(AdjudicationSteps));
+export const accountingBasisSchema = s.enumeration("The accounting basis an mSCOA account selection is resolved against. 'accrual' is the usual choice for a budget capture; 'dual' only when the form genuinely captures the cash side as well.", enumValues(AccountingBasis));

package/dist/skillet/tests/house-rules.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/skillet/tests/house-rules.spec.js

@@ -0,0 +1,162 @@
+import { s } from '@hashbrownai/core';
+import { AllFormInputPrimaryKeys } from '../../interfaces/FormBuilder/FormInputKeys.js';
+import { ElementTypes } from '../../interfaces/formInput/index.js';
+import { AUTHORING_RULES, CONTROL_NAME_PATTERN } from '../authoring-rules.js';
+import { DRAFT_COMPLETION_REQUIRED, createFormDraftSchema } from '../form.js';
+import { inputMemberSchemas } from '../input-members.js';
+import { createValidatorsSchema, validatorsDraftSchema, } from '../members/validators.js';
+import { COMMON_ELEMENTS, createColumnSchema } from '../variants.js';
+import { RESERVED_CONTROL_NAMES, describeWorkflowStep, } from '../workflow-context.js';
+/**
+ * The rules the schemas carry from the Form Creation Guide
+ * (`doc/guides/form-creation-guide.md`) that a test can hold them to.
+ *
+ * Most of the guide arrives as prose in descriptions, which no test can judge.
+ * What can be pinned is the handful of places where the prose and a structure
+ * have to agree — the reserved names against the control-name pattern, the
+ * step context against the form description, an element the description
+ * names against the elements on offer — and the two rules the guide overturned
+ * outright: the autocomplete note and the handle-label description.
+ */
+describe('house rules from the Form Creation Guide', () => {
+    it('names every reserved control name the pattern would let through', () => {
+        // The pattern stops `_id` and the SYSTEM_* inputs on shape alone. The
+        // ones it lets through — `reference`, `status`, `data` — have to be named
+        // in the rules, or the model has no way to know them. Filtering at
+        // evaluation rather than listing by hand is what this pins: add a
+        // lowerCamelCase name to RESERVED_CONTROL_NAMES and it appears here.
+        const pattern = new RegExp(CONTROL_NAME_PATTERN);
+        const rules = AUTHORING_RULES.join(' ');
+        const uncovered = RESERVED_CONTROL_NAMES.filter((name) => pattern.test(name) && !new RegExp(`\\b${name}\\b`).test(rules));
+        expect(uncovered).toEqual([]);
+        expect(pattern.test('_id')).toBe(false);
+        expect(pattern.test('SYSTEM_TAGS')).toBe(false);
+        expect(pattern.test('CURRENT_FINANCIAL_CYCLE')).toBe(false);
+        expect(rules).toContain('reference');
+    });
+    it('states the rules once, at the root of the form', () => {
+        // Hashbrown names `$defs` entries by description and repeats the name at
+        // every `$ref`, so a rule on a member every element shares is paid once
+        // per element. The root is emitted once, so that is where the rules go —
+        // and the member the rule concerns must NOT repeat it.
+        const json = s.toJsonSchema(createFormDraftSchema({ elements: COMMON_ELEMENTS }));
+        expect(json.description).toContain('never one of the names');
+        expect(json.description).toContain('reference');
+        const member = s.getDescription(inputMemberSchemas[AllFormInputPrimaryKeys.FormControlName]) ?? '';
+        expect(member).not.toContain('reference,');
+        expect(member.length).toBeLessThan(400);
+    });
+    it('withdraws the named-validator branch until names are supplied', () => {
+        // Same reasoning as the api source and the document picker: a free string
+        // invites a validator name that looks authoritative and resolves to
+        // nothing. With no names the item is the inline rule alone; with names it
+        // is a union whose string branch enumerates exactly those names.
+        const items = (json) => json
+            .properties.__wrappedPrimitive.items;
+        const bare = items(s.toJsonSchema(validatorsDraftSchema));
+        expect(bare.anyOf).toBeUndefined();
+        expect(bare.type).toBe('object');
+        const named = items(s.toJsonSchema(createValidatorsSchema({
+            namedValidators: [
+                { name: 'email', description: 'a well-formed email address' },
+            ],
+        })));
+        expect(Array.isArray(named.anyOf)).toBe(true);
+        const text = JSON.stringify(named.anyOf);
+        expect(text).toContain('"enum"');
+        expect(text).toContain('"email"');
+        expect(text).toContain('a well-formed email address');
+        expect(named.anyOf.some((b) => b.type === 'object')).toBe(true);
+    });
+    it('threads the named validators through the column options', () => {
+        const json = JSON.stringify(s.toJsonSchema(createColumnSchema({
+            elements: [ElementTypes.Input],
+            namedValidators: [{ name: 'southAfricanId' }],
+        })));
+        expect(json).toContain('southAfricanId');
+        const bare = JSON.stringify(s.toJsonSchema(createColumnSchema({ elements: [ElementTypes.Input] })));
+        expect(bare).not.toContain('southAfricanId');
+    });
+    it('tells the model which step the form serves', () => {
+        const json = JSON.stringify(s.toJsonSchema(createFormDraftSchema({
+            elements: COMMON_ELEMENTS,
+            step: {
+                type: 'review',
+                controlName: 'managerReview',
+                expectedControls: [
+                    {
+                        name: 'totalAmount',
+                        purpose: 'decision gate compares it against 30000',
+                    },
+                ],
+                prefilledControlNames: ['department'],
+            },
+        })));
+        expect(json).toContain('serves the review step');
+        expect(json).toContain("'managerReview'");
+        expect(json).toContain('totalAmount');
+        expect(json).toContain('decision gate compares it against 30000');
+        expect(json).toContain("'department'");
+    });
+    it('says nothing about a workflow step unless one was given', () => {
+        const json = JSON.stringify(s.toJsonSchema(createFormDraftSchema({ elements: COMMON_ELEMENTS })));
+        expect(json).not.toContain('serves the');
+    });
+    it('asks for the review control name when it was not supplied', () => {
+        // A review step routes on one toggle, and its name is the workflow
+        // designer's. Without it the model must be told to get it from the
+        // request rather than left to pick one.
+        expect(describeWorkflowStep({ type: 'review' })).toContain('which the request must state');
+        expect(describeWorkflowStep({ type: 'initiate' })).toContain('never ask the user for it');
+    });
+    it('points the model at section titles only when they are on offer', () => {
+        // A sentence naming an element the union does not contain is how a model
+        // talks itself into inventing one.
+        const withHeadings = JSON.stringify(s.toJsonSchema(createFormDraftSchema({ elements: COMMON_ELEMENTS })));
+        expect(withHeadings).toContain('sectionTitle whose hintLabel');
+        const without = JSON.stringify(s.toJsonSchema(createFormDraftSchema({ elements: [ElementTypes.Input] })));
+        expect(without).not.toContain('sectionTitle whose hintLabel');
+    });
+    it('offers the always-shown settings on every element that captures a value', () => {
+        // `readonly`, `onlySetTempErrorOnTouch` and `tourContent` are edited
+        // through `Default` rows, which the settings panel shows on every element
+        // and which no element's `properties` lists. The guide treats the first
+        // two as settings set on nearly every field — a prefilled value is
+        // read-only, errors wait for the user to leave the field — and the step
+        // context tells the model to use `readonly`, so it has to be there.
+        const json = s.toJsonSchema(createColumnSchema({ elements: COMMON_ELEMENTS }));
+        for (const branch of json.anyOf) {
+            const keys = Object.keys(branch.properties);
+            const element = branch.properties['element'].const;
+            const captures = element !== ElementTypes.SectionTitle;
+            for (const key of ['readonly', 'onlySetTempErrorOnTouch', 'tourContent']) {
+                expect(keys.includes(key))
+                    .withContext(`${element} ${captures ? 'should' : 'should not'} offer ${key}`)
+                    .toBe(captures);
+            }
+        }
+        // The interface requires the flag and the schema leaves it optional, so
+        // the application still owes a default — and the guide says which.
+        const entry = DRAFT_COMPLETION_REQUIRED.find((path) => path.startsWith('slides[].columns[].onlySetTempErrorOnTouch'));
+        expect(entry).toBeDefined();
+        expect(entry).toContain('true');
+    });
+    it('describes the item-list handle as a row button, not a file control', () => {
+        // `handleLabel` is declared by `IMultiple` and listed only by the item
+        // list, yet its description used to speak of "the attached file".
+        const description = s.getDescription(inputMemberSchemas[AllFormInputPrimaryKeys.HandleLabel]) ??
+            '';
+        expect(description).toContain('Add item');
+        expect(description).not.toContain('file');
+    });
+    it('steers the autocomplete by whether the user may add a value, not by list length', () => {
+        // The guide draws the line the old note did not: an autocomplete stores
+        // whatever is typed, so it is for a list the user may add to; a merely
+        // long list is a paginated selection table.
+        const json = s.toJsonSchema(createColumnSchema({ elements: [ElementTypes.AutoCompleteInput] }));
+        const notes = json.anyOf.map((branch) => branch.description ?? '').join(' ');
+        expect(notes).toContain('stores whatever the user types');
+        expect(notes).toContain('paginatedSelectionTable');
+        expect(notes).not.toContain('Prefer it over a select when the list is long');
+    });
+});

package/dist/skillet/tests/skillet-coupling.spec.d.ts

@@ -0,0 +1 @@
+export {};