ngx-t-forms-types 0.0.30 → 0.0.34

package/dist/skillet/form.d.ts

@@ -0,0 +1,170 @@
+import { s } from '@hashbrownai/core';
+import { type AssertNever } from './internal/coupling.js';
+import { type AvailableApiEndpoint } from './members/mat-options.js';
+import { type ColumnSchemaOptions } from './variants.js';
+import { type WorkflowStepContext } from './workflow-context.js';
+/**
+ * The whole-form schema: slides of columns, plus how the form submits.
+ *
+ * ## This produces a draft, and it cannot not
+ *
+ * `FormSchema` requires `submissionHandle.submissionAPI` — an array of at least
+ * one full `APIDataFetchingConfiguration`, complete with `_id`, `httpEndPoint`
+ * and `httpMethod`. It is the same problem `matOptions` has, except mandatory:
+ * there is no valid form without it, and no model can author it from a prompt.
+ * `FormSlide.sectionId` is the same story on a smaller scale — an identifier
+ * the builder assigns, which a model can only fabricate.
+ *
+ * So a generated form is a {@link FormDraft}. The application supplies section
+ * ids and expands the chosen endpoint ids into stored configurations, and only
+ * then does `validateForm()` have something it can pass. Any pipeline built on
+ * this needs that expansion step; there is no arrangement of the schema that
+ * removes it.
+ *
+ * ## Streaming
+ *
+ * `streaming: true` switches the slide and column arrays to their streaming
+ * variants, so a client parses each slide as it arrives instead of waiting for
+ * the closing brace of a large form. It changes nothing about the data — only
+ * when a consumer can first see it.
+ */
+export interface SubmissionHandleDraft {
+    submissionAPI: string[];
+    /**
+     * The pre-submit gate, as an endpoint id, expanded into
+     * `FormSubmissionHandleInterface.canSubmitAPI`.
+     *
+     * Absent — not empty — on most drafts, and on every draft generated without
+     * `FormSchemaOptions.canSubmitEndpoints`: the key is only put to the model
+     * when the caller has gate endpoints to offer, and a hand-built form carries
+     * no `canSubmitAPI` key either, so a schema that always emitted one would
+     * make every generated form differ from an authored one over a member the
+     * form does not use.
+     */
+    canSubmitAPI?: string[];
+    submissionMessage: string | null;
+}
+export interface FormDraft {
+    formTitle: string;
+    /**
+     * Columns are typed loosely on purpose. The per-element variants are
+     * assembled at runtime from `DefaultInputConfig`, whose property arrays are
+     * `string[]` rather than const tuples, so there is no literal type for
+     * `s.Infer` to reconstruct. The compiler cannot describe these; the schema
+     * and `validateForm()` still constrain them.
+     */
+    slides: {
+        label: string;
+        columns: unknown[];
+    }[];
+    submissionHandle: SubmissionHandleDraft;
+}
+export interface FormSchemaOptions extends ColumnSchemaOptions {
+    /**
+     * Endpoints the form may submit to. As with `matOptions`, an empty list means
+     * the model is not asked to choose one — it emits an empty `submissionAPI`
+     * and the application fills it in.
+     */
+    submissionEndpoints?: readonly AvailableApiEndpoint[];
+    /**
+     * Endpoints that may gate submission — called with the form data, and their
+     * answer decides whether the submission proceeds.
+     *
+     * Unlike {@link submissionEndpoints} this one is genuinely optional at the
+     * schema level: `canSubmitAPI` is optional on
+     * `FormSubmissionHandleInterface` and most forms have no pre-submit check, so
+     * an empty list here removes the key from the schema entirely rather than
+     * degrading it to an empty array. That follows `matOptions`, where a source
+     * with no candidates is not offered at all — the alternative is asking a
+     * model to pick an endpoint out of an empty list, which it answers by
+     * inventing one.
+     */
+    canSubmitEndpoints?: readonly AvailableApiEndpoint[];
+    /**
+     * The workflow step this form serves, and the control names the workflow
+     * already fixes. See {@link WorkflowStepContext}: none of it is knowable
+     * from a prompt, and all of it decides what the form must contain.
+     */
+    step?: WorkflowStepContext;
+    /** Parse slides and columns incrementally as they stream in. */
+    streaming?: boolean;
+}
+declare function submissionHandleSchema(endpoints: readonly AvailableApiEndpoint[], canSubmitEndpoints: readonly AvailableApiEndpoint[]): s.ObjectType<{
+    submissionAPI: s.ArrayType<s.StringType | s.EnumType<string[]>>;
+    canSubmitAPI: s.ArrayType<s.EnumType<string[]>>;
+    submissionMessage: import("@hashbrownai/core/src/schema/base").SchemaForUnion<string | null>;
+}> | s.ObjectType<{
+    submissionAPI: s.ArrayType<s.StringType | s.EnumType<string[]>>;
+    submissionMessage: import("@hashbrownai/core/src/schema/base").SchemaForUnion<string | null>;
+}>;
+/** The submission-handle node, whichever endpoints the factory was given. */
+type SubmissionHandleSchema = ReturnType<typeof submissionHandleSchema>;
+/**
+ * The submission handle produces the draft it declares.
+ *
+ * The same check the per-member modules run on themselves, applied to the one
+ * nested object this file owns. It earns its keep on the `canSubmitAPI` branch
+ * in particular: that key exists only when the caller supplies
+ * `canSubmitEndpoints`, so the node's inferred type is a UNION of the two
+ * shapes, and a member added to either branch without a matching member on
+ * {@link SubmissionHandleDraft} fails here rather than at the application's
+ * expansion step.
+ */
+export type _NoSubmissionHandleDraftDrift = AssertNever<[
+    s.Infer<SubmissionHandleSchema>
+] extends [SubmissionHandleDraft] ? never : 'submissionHandle'>;
+/**
+ * Builds the form-draft schema.
+ *
+ * @param options which elements and data sources to offer, which endpoints the
+ *   form may submit to and which may gate that submission, and whether to
+ *   stream.
+ */
+export declare function createFormDraftSchema(options?: FormSchemaOptions): s.ObjectType<{
+    formTitle: s.StringType;
+    slides: s.ArrayType<s.ObjectType<{
+        label: s.StringType;
+        columns: s.ArrayType<s.HashbrownType<unknown>>;
+    }>>;
+    submissionHandle: s.ObjectType<{
+        submissionAPI: s.ArrayType<s.StringType | s.EnumType<string[]>>;
+        canSubmitAPI: s.ArrayType<s.EnumType<string[]>>;
+        submissionMessage: import("@hashbrownai/core/src/schema/base").SchemaForUnion<string | null>;
+    }> | s.ObjectType<{
+        submissionAPI: s.ArrayType<s.StringType | s.EnumType<string[]>>;
+        submissionMessage: import("@hashbrownai/core/src/schema/base").SchemaForUnion<string | null>;
+    }>;
+}>;
+/**
+ * Members of a generated draft the application must supply before the form is
+ * valid. Listed so the expansion step has something to check itself against.
+ *
+ * The per-member lists are pulled in rather than restated, so a module that
+ * takes on a new obligation adds it here by existing. Each entry is prefixed
+ * with the column path it hangs off, since the modules describe their own
+ * shape and do not know where in a form they sit.
+ *
+ * A module's own entries must therefore start at the MEMBER it owns —
+ * `validators[].id`, not `id` — because everything before that is added here
+ * and everything after is the module's to state. A list that skips its member
+ * name yields a path with a hole in it, which is worse than no list: it reads
+ * as authoritative and points nowhere.
+ *
+ * Three entries are not from any module and are worth reading twice:
+ *
+ * - `isCalculatedField` is derived, not authored — see `calculatedFieldSplit`
+ *   in `variants.ts`. It is required by the interface on EVERY column, so
+ *   expansion must set it on plain columns too, not only calculated ones.
+ * - `onlySetTempErrorOnTouch` is required by the interface but optional in the
+ *   schema (offered on every value-capturing element through the always-shown
+ *   editor rows), so a model may leave it null. Expansion then sets it, and the
+ *   guide's house rule says what to: true, so errors appear only after the
+ *   user leaves a field. The builder's own element templates default it to
+ *   false; the guide is explicit that this is the wrong default for nearly
+ *   every field.
+ * - the nulls. Skillet has no optional, so every unset member arrives as an
+ *   explicit `null`, and Joi rejects `null` for a typed optional key. Stripping
+ *   them is not tidying; a draft that keeps them fails validation.
+ */
+export declare const DRAFT_COMPLETION_REQUIRED: readonly ["slides[].sectionId", "slides[].columns[].id", "slides[].columns[].sectionId", "slides[].columns[].isCalculatedField (derived: calculatedFieldRules != null)", "slides[].columns[].onlySetTempErrorOnTouch (required by the interface and offered as optional; when the model leaves it null the application sets true)", "submissionHandle.submissionAPI[] (endpoint id expanded to its configuration)", "submissionHandle.canSubmitAPI[] (endpoint id expanded to its configuration; the key is present only when canSubmitEndpoints were offered, and an empty array is dropped)", ...string[], "every member emitted as null is stripped before validation"];
+export {};

package/dist/skillet/form.js

@@ -0,0 +1,139 @@
+import { s } from '@hashbrownai/core';
+import { ElementTypes } from '../interfaces/formInput/index.js';
+import { describeAuthoringRules } from './authoring-rules.js';
+import { optional } from './internal/coupling.js';
+import { CALCULATED_FIELD_DRAFT_COMPLETION } from './members/calculated-field.js';
+import { CONDITIONAL_DRAFT_COMPLETION } from './members/conditional.js';
+import { WORKFLOW_PICKER_DRAFT_COMPLETION } from './members/document-picker.js';
+import { MAT_OPTIONS_DRAFT_COMPLETION, } from './members/mat-options.js';
+import { MSCOA_DRAFT_COMPLETION } from './members/mscoa.js';
+import { PAGINATION_DRAFT_COMPLETION } from './members/pagination.js';
+import { TABLE_DRAFT_COMPLETION } from './members/table.js';
+import { VALIDATOR_DRAFT_COMPLETION } from './members/validators.js';
+import { CALCULATE_LIST_DRAFT_COMPLETION } from './members/value.js';
+import { createColumnSchema } from './variants.js';
+import { describeWorkflowStep, } from './workflow-context.js';
+function submissionHandleSchema(endpoints, canSubmitEndpoints) {
+    const endpointNode = endpoints.length
+        ? s.enumeration(`Which configured endpoint the completed form is submitted to. Choose by meaning: ${endpoints
+            .map((e) => `${e.id} (${e.name})`)
+            .join('; ')}.`, endpoints.map((e) => e.id))
+        : s.string('Leave this list empty. No submission endpoints were offered, so one cannot be chosen and must not be invented.');
+    const submissionAPI = s.array(endpoints.length
+        ? 'The endpoint the form submits to. Choose exactly one.'
+        : 'Leave empty — the application supplies the submission endpoint.', endpointNode, endpoints.length ? { minItems: 1, maxItems: 1 } : { maxItems: 0 });
+    // `innerComponentShowSubmitButton` is deliberately absent: it is deprecated,
+    // and a deprecated property left in a generation schema comes back on every
+    // form the model writes.
+    const submissionMessage = optional(s.string("Message shown to the user after a successful submission. One sentence, past tense, saying what happened and what happens next: 'Your requisition has been submitted and sent to your line manager for approval'."));
+    const description = 'How the completed form is submitted.';
+    // Two whole object nodes rather than one with a conditionally spread key:
+    // an optional key in a Skillet shape infers as `unknown`, which would leave
+    // the assertion at the foot of this file passing while proving nothing.
+    return canSubmitEndpoints.length
+        ? s.object(description, {
+            submissionAPI,
+            canSubmitAPI: s.array('An optional check run before the form is submitted: the endpoint is called with the form data and must approve before the submission proceeds. Leave this empty unless the form genuinely needs a gate — most do not. Choose at most one.', s.enumeration(`Which configured endpoint decides whether the form may be submitted. Choose by meaning: ${canSubmitEndpoints
+                .map((e) => `${e.id} (${e.name})`)
+                .join('; ')}.`, canSubmitEndpoints.map((e) => e.id)), { maxItems: 1 }),
+            submissionMessage,
+        })
+        : s.object(description, {
+            submissionAPI,
+            submissionMessage,
+        });
+}
+/**
+ * Builds the form-draft schema.
+ *
+ * @param options which elements and data sources to offer, which endpoints the
+ *   form may submit to and which may gate that submission, and whether to
+ *   stream.
+ */
+export function createFormDraftSchema(options = {}) {
+    const column = createColumnSchema(options);
+    const array = options.streaming ? s.streaming.array : s.array;
+    const object = options.streaming ? s.streaming.object : s.object;
+    // The guide's grouping rule names section titles, so it is only stated when
+    // that element is actually on offer — a sentence pointing a model at an
+    // element it cannot choose is an invitation to invent one.
+    const offersHeadings = (options.elements ?? Object.values(ElementTypes)).includes(ElementTypes.SectionTitle);
+    const slide = object('A page of the form: one topic, with five to seven fields, an item list counting as one. Over eight, split it. Its label becomes a section heading when the transaction is read back.', {
+        label: s.string("The heading for this page: a short statement of what it holds, in sentence case — 'Requester details', 'Items required' — never a question, a verb, or a number such as 'Section 3'."),
+        columns: array([
+            'The fields on this page, in the order they are shown: identifiers and choices first, free text, uploads, calculations and signatures last.',
+            offersHeadings
+                ? 'Start each group of three to five related fields with a sectionTitle whose hintLabel carries the guidance for the group.'
+                : null,
+            'Fields that belong together share one row by sharing out the 12 grid columns between them, and a field revealed by a condition sits immediately after the field that reveals it.',
+        ]
+            .filter((part) => part !== null)
+            .join(' '), column, { minItems: 1 }),
+    });
+    // The root is emitted exactly once, so it is where the form-wide rules go;
+    // see `authoring-rules.ts` for why they are not on the members themselves.
+    const formDescription = [
+        'A complete dynamic form. Group related fields onto slides rather than one long page; a form of fewer than about seven fields fits on one slide. Make the system do everything it can: prefill what it knows, calculate what it can derive, and let the user pick rather than type.',
+        describeAuthoringRules(),
+        options.step ? describeWorkflowStep(options.step) : null,
+    ]
+        .filter((part) => part !== null)
+        .join(' ');
+    return object(formDescription, {
+        formTitle: s.string('The title of the form, in sentence case. Name what the form is for.'),
+        slides: array('The pages of the form, in order.', slide, { minItems: 1 }),
+        submissionHandle: submissionHandleSchema(options.submissionEndpoints ?? [], options.canSubmitEndpoints ?? []),
+    });
+}
+/**
+ * Members of a generated draft the application must supply before the form is
+ * valid. Listed so the expansion step has something to check itself against.
+ *
+ * The per-member lists are pulled in rather than restated, so a module that
+ * takes on a new obligation adds it here by existing. Each entry is prefixed
+ * with the column path it hangs off, since the modules describe their own
+ * shape and do not know where in a form they sit.
+ *
+ * A module's own entries must therefore start at the MEMBER it owns —
+ * `validators[].id`, not `id` — because everything before that is added here
+ * and everything after is the module's to state. A list that skips its member
+ * name yields a path with a hole in it, which is worse than no list: it reads
+ * as authoritative and points nowhere.
+ *
+ * Three entries are not from any module and are worth reading twice:
+ *
+ * - `isCalculatedField` is derived, not authored — see `calculatedFieldSplit`
+ *   in `variants.ts`. It is required by the interface on EVERY column, so
+ *   expansion must set it on plain columns too, not only calculated ones.
+ * - `onlySetTempErrorOnTouch` is required by the interface but optional in the
+ *   schema (offered on every value-capturing element through the always-shown
+ *   editor rows), so a model may leave it null. Expansion then sets it, and the
+ *   guide's house rule says what to: true, so errors appear only after the
+ *   user leaves a field. The builder's own element templates default it to
+ *   false; the guide is explicit that this is the wrong default for nearly
+ *   every field.
+ * - the nulls. Skillet has no optional, so every unset member arrives as an
+ *   explicit `null`, and Joi rejects `null` for a typed optional key. Stripping
+ *   them is not tidying; a draft that keeps them fails validation.
+ */
+export const DRAFT_COMPLETION_REQUIRED = [
+    'slides[].sectionId',
+    'slides[].columns[].id',
+    'slides[].columns[].sectionId',
+    'slides[].columns[].isCalculatedField (derived: calculatedFieldRules != null)',
+    'slides[].columns[].onlySetTempErrorOnTouch (required by the interface and offered as optional; when the model leaves it null the application sets true)',
+    'submissionHandle.submissionAPI[] (endpoint id expanded to its configuration)',
+    'submissionHandle.canSubmitAPI[] (endpoint id expanded to its configuration; the key is present only when canSubmitEndpoints were offered, and an empty array is dropped)',
+    ...[
+        ...CALCULATED_FIELD_DRAFT_COMPLETION,
+        ...VALIDATOR_DRAFT_COMPLETION,
+        ...CONDITIONAL_DRAFT_COMPLETION,
+        ...PAGINATION_DRAFT_COMPLETION,
+        ...MSCOA_DRAFT_COMPLETION,
+        ...WORKFLOW_PICKER_DRAFT_COMPLETION,
+        ...MAT_OPTIONS_DRAFT_COMPLETION,
+        ...CALCULATE_LIST_DRAFT_COMPLETION,
+        ...TABLE_DRAFT_COMPLETION,
+    ].map((path) => `slides[].columns[].${path}`),
+    'every member emitted as null is stripped before validation',
+];

package/dist/skillet/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Skillet schemas for LLM-driven form authoring.
+ *
+ * Published as the `ngx-t-forms-types/skillet` subpath, NOT from the package
+ * root, because it is the only part of these typings that needs
+ * `@hashbrownai/core`. That dependency is an optional peer: consumers who never
+ * generate forms — the Node API, existing Angular apps — resolve the root entry
+ * and never load it.
+ *
+ * ## What this is for
+ *
+ * These schemas describe form structure to a model so it can author one. They
+ * are a GENERATION contract, not a validation contract. The Joi schemas under
+ * `src/schemas` remain the source of truth: a generated form is validated with
+ * `validateForm()` exactly like a hand-built one, and failures are fed back to
+ * the model as a repair turn. Where the two disagree, Joi wins.
+ *
+ * ## How drift is prevented
+ *
+ * Enum-backed nodes read their entries from the live enums at evaluation, so
+ * they cannot fall behind. Everything else is checked at compile time: see the
+ * assertions at the foot of `input-members.ts`, which fail the build — by
+ * name — when a key is added to `AllFormInputPrimaryKeys`, when a member is
+ * left unclassified, or when a node starts producing a value its interface
+ * cannot hold.
+ */
+export { enumValues, exhaustive, matches, optional, type AssertNever, } from './internal/coupling.js';
+export * from './shared-types.js';
+export * from './input-members.js';
+export * from './extra-members.js';
+export * from './members/mat-options.js';
+export * from './members/calculated-field.js';
+export * from './members/validators.js';
+export * from './members/conditional.js';
+export * from './members/document-picker.js';
+export * from './members/mscoa.js';
+export * from './members/pagination.js';
+export * from './members/table.js';
+export * from './members/value.js';
+export * from './variants.js';
+export * from './form.js';
+export * from './workflow-context.js';
+export * from './authoring-rules.js';

package/dist/skillet/index.js

@@ -0,0 +1,46 @@
+/**
+ * Skillet schemas for LLM-driven form authoring.
+ *
+ * Published as the `ngx-t-forms-types/skillet` subpath, NOT from the package
+ * root, because it is the only part of these typings that needs
+ * `@hashbrownai/core`. That dependency is an optional peer: consumers who never
+ * generate forms — the Node API, existing Angular apps — resolve the root entry
+ * and never load it.
+ *
+ * ## What this is for
+ *
+ * These schemas describe form structure to a model so it can author one. They
+ * are a GENERATION contract, not a validation contract. The Joi schemas under
+ * `src/schemas` remain the source of truth: a generated form is validated with
+ * `validateForm()` exactly like a hand-built one, and failures are fed back to
+ * the model as a repair turn. Where the two disagree, Joi wins.
+ *
+ * ## How drift is prevented
+ *
+ * Enum-backed nodes read their entries from the live enums at evaluation, so
+ * they cannot fall behind. Everything else is checked at compile time: see the
+ * assertions at the foot of `input-members.ts`, which fail the build — by
+ * name — when a key is added to `AllFormInputPrimaryKeys`, when a member is
+ * left unclassified, or when a node starts producing a value its interface
+ * cannot hold.
+ */
+export { enumValues, exhaustive, matches, optional, } from './internal/coupling.js';
+export * from './shared-types.js';
+export * from './input-members.js';
+export * from './extra-members.js';
+// Per-member modules. Each owns one nested configuration object, states why it
+// produces a draft where it does, and lists what the application must supply
+// before that draft is valid.
+export * from './members/mat-options.js';
+export * from './members/calculated-field.js';
+export * from './members/validators.js';
+export * from './members/conditional.js';
+export * from './members/document-picker.js';
+export * from './members/mscoa.js';
+export * from './members/pagination.js';
+export * from './members/table.js';
+export * from './members/value.js';
+export * from './variants.js';
+export * from './form.js';
+export * from './workflow-context.js';
+export * from './authoring-rules.js';