ngx-t-forms-types 0.0.30 → 0.0.33

package/dist/skillet/members/document-picker.d.ts

@@ -0,0 +1,182 @@
+import { s } from '@hashbrownai/core';
+import type { AllFormInputPrimaryKeys } from '../../interfaces/FormBuilder/FormInputKeys.js';
+import { type DocumentPickerFilterOperator, type DocumentPickerFilterValueType } from '../../interfaces/formInput/WorkflowDocumentPicker.js';
+import { AssertNever } from '../internal/coupling.js';
+import type { AvailableWorkflow } from './mat-options.js';
+/**
+ * The `workflowPickerConfig` member: which workflow a document picker browses,
+ * and how that list is narrowed before the user is shown anything.
+ *
+ * ## Why this is a factory, and why it may decline to build a schema at all
+ *
+ * The one field an administrator must supply is `workflowId`, and it is a
+ * persisted id. A model asked for one emits a plausible hex string, and what
+ * comes back is a picker that renders, opens, and lists nothing — a failure
+ * that surfaces to an end user rather than to whoever generated the form.
+ *
+ * The builder never asks a human to type it either: the editor row for this
+ * property is a `WorkflowPicker`, which PICKS from the workflows the tenant
+ * actually has. So the model picks too. {@link createWorkflowPickerSchema}
+ * takes the workflows available in the caller's context and enumerates their
+ * ids, exactly as the `api` branch of `mat-options.ts` enumerates endpoint ids.
+ *
+ * With no workflows to enumerate, that reasoning goes one step further than it
+ * does there. In `mat-options` a missing endpoint list drops one BRANCH and the
+ * remaining sources still stand, so a schema is still worth offering. Here the
+ * unavailable field is the only required one, and every other member is scoped
+ * by it — a step id, a filter path, a document field all mean nothing until the
+ * workflow is known — so there is no reduced schema left to offer. The factory
+ * returns `null`, and the caller leaves `workflowPickerConfig` off the element
+ * rather than letting a model invent the one value that has to be real. That is
+ * also why this module exports no ready-made default schema: the no-workflows
+ * default is `null`, and an exported `null` reads as an oversight.
+ *
+ * ## Why this produces a draft
+ *
+ * `fromInputId` is stored as an input id — the runtime form group is keyed by
+ * input id, not by form-control name. A model authoring a form does not have
+ * those ids; it has just written the fields by NAME. So the draft carries the
+ * `formControlName`, the same trade `inputSourceId` makes in `mat-options.ts`,
+ * and the application resolves it against the form it was generated alongside
+ * before the config is stored. The member keeps its interface name so that
+ * resolution stays a substitution rather than a rename.
+ *
+ * The absent members are the second reason this is a draft: Skillet has no
+ * `optional()`, so every declared key is emitted and optionality is a `| null`
+ * branch. {@link WorkflowPickerConfigDraft} therefore describes what the model
+ * writes, not what `IWorkflowDocumentPickerConfig` stores, and stripping the
+ * nulls is part of the same expansion pass that resolves `fromInputId`.
+ *
+ * ## Deliberate omissions
+ *
+ * `primaryIdentifierKey` is `TreeNode[]` — nodes of the key tree the builder
+ * derives from a captured sample document. A model has no sample and therefore
+ * no tree to select from, and the behaviour it would be overriding (identify
+ * the transaction by `_id`) is already the right answer whenever it cannot.
+ *
+ * `sampleDocument` is captured from a real transaction when the workflow is
+ * chosen. It is evidence, not configuration; generated, it would be fiction
+ * that the key tree above is then built from.
+ *
+ * `availableSteps` is a cache of the chosen workflow's steps, refreshed by the
+ * builder whenever the workflow changes and never consulted at runtime — the
+ * step chooser always reads live steps. Generating it means inventing the very
+ * list the step filter is then checked against.
+ *
+ * A filter's `id` is stamped by the record-list editor the first time the
+ * filter is saved, and is the key that editor tracks a row by for edit and for
+ * delete. It is an identity, not a decision, so it is left to the editor that
+ * owns it.
+ *
+ * `value` is `unknown` on the interface and is narrowed here to a string,
+ * number or boolean — the three shapes `valueType` can actually coerce.
+ *
+ * ## Known gap: step ids
+ *
+ * `stepFilter.stepIds` is modelled, but the ids belong to the workflow and
+ * {@link AvailableWorkflow} carries only an id and a name, so nothing in this
+ * schema can enumerate them. The description says so plainly and tells the
+ * model to leave the step filter null unless the request itself names real step
+ * ids; an invented id narrows the picker to nothing, which is the same silent
+ * failure an invented `workflowId` produces. Widening `AvailableWorkflow` to
+ * carry its steps would close this properly, but that type is shared with
+ * `mat-options.ts` and is not changed from here.
+ */
+export interface WorkflowPickerSchemaOptions {
+    /**
+     * Workflows the model may point the picker at. Omit, or pass an empty list,
+     * and {@link createWorkflowPickerSchema} produces no schema at all — there is
+     * no useful subset of this config that does not name a workflow.
+     */
+    workflows?: readonly AvailableWorkflow[];
+}
+/**
+ * The two value sources, addressed by meaning.
+ *
+ * Each branch of the filter union carries DIFFERENT members, so these literals
+ * cannot be taken positionally out of `DOCUMENT_PICKER_FILTER_VALUE_SOURCES`:
+ * reordering that array would quietly file `value` and `valueType` under the
+ * input-bound source, and produce filters that validate and never match.
+ * {@link exhaustive} is this codebase's answer to restating members safely —
+ * the union it checks against is itself read off that array, so adding a third
+ * source fails to compile here until it is given a branch of its own.
+ */
+declare const FIXED_SOURCE: "fixed", INPUT_SOURCE: "input";
+export interface WorkflowStepFilterDraft {
+    stepIds: string[];
+}
+/** A clause comparing a document field against a value fixed in the form. */
+export interface FixedValueFilterDraft {
+    path: string;
+    op: DocumentPickerFilterOperator | null;
+    valueSource: typeof FIXED_SOURCE;
+    value: string | number | boolean;
+    valueType: DocumentPickerFilterValueType | null;
+}
+/** A clause comparing a document field against another field on this form. */
+export interface InputValueFilterDraft {
+    path: string;
+    op: DocumentPickerFilterOperator | null;
+    valueSource: typeof INPUT_SOURCE;
+    /** A `formControlName`, which the application resolves to an input id. */
+    fromInputId: string;
+    omitWhenEmpty: boolean;
+}
+export type DocumentPickerFilterDraft = FixedValueFilterDraft | InputValueFilterDraft;
+export interface WorkflowPickerConfigDraft {
+    workflowId: string;
+    stepFilter: WorkflowStepFilterDraft | null;
+    presetFilters: DocumentPickerFilterDraft[];
+}
+/**
+ * Builds the `workflowPickerConfig` schema over the workflows the caller has.
+ *
+ * @param options the workflows the model may choose between. Empty — the
+ *   default — yields `null` rather than a schema whose only required field
+ *   would have to be invented.
+ * @returns the schema, or `null` when there is no workflow to point it at.
+ */
+export declare function createWorkflowPickerSchema(options?: WorkflowPickerSchemaOptions): s.ObjectType<{
+    workflowId: s.EnumType<string[]>;
+    stepFilter: import("@hashbrownai/core/src/schema/base").SchemaForUnion<{
+        stepIds: string[];
+    } | null>;
+    presetFilters: s.ArrayType<import("@hashbrownai/core/src/schema/base").SchemaForUnion<{
+        path: string;
+        op: "eq" | "ne" | "in" | "nin" | "gt" | "gte" | "lt" | "lte" | "regex" | "exists" | null;
+        valueSource: "fixed";
+        value: string | number | boolean;
+        valueType: "string" | "number" | "boolean" | null;
+    } | {
+        path: string;
+        op: "eq" | "ne" | "in" | "nin" | "gt" | "gte" | "lt" | "lte" | "regex" | "exists" | null;
+        valueSource: "input";
+        fromInputId: string;
+        omitWhenEmpty: boolean;
+    }>>;
+}> | null;
+/** The schema the factory builds, independent of which workflows it was given. */
+type WorkflowPickerSchema = NonNullable<ReturnType<typeof createWorkflowPickerSchema>>;
+/**
+ * The drafted node produces the draft it declares. Loosening a branch, or
+ * retyping a member of {@link WorkflowPickerConfigDraft}, surfaces here by key
+ * name — the guarantee `_NoDraftDrift` gives `matOptions` in
+ * `input-members.ts`, applied to the one member this module owns. What no
+ * assertion can check is the expansion from draft to stored config; that
+ * contract lives with the caller.
+ */
+export type _NoWorkflowPickerDraftDrift = AssertNever<[
+    s.Infer<WorkflowPickerSchema>
+] extends [WorkflowPickerConfigDraft] ? never : AllFormInputPrimaryKeys.WorkflowPickerConfig>;
+/**
+ * Members of a generated `workflowPickerConfig` the application must resolve.
+ *
+ * Only one, and it is not a Joi requirement — `presetFilters[].id` is optional
+ * there, so an unexpanded filter still validates. It is listed because it would
+ * still be WRONG: `fromInputId` is keyed by input id, and a draft carries a
+ * formControlName in that slot. A filter left unresolved passes validation and
+ * then matches nothing, which is the failure mode this whole layer is most
+ * concerned with.
+ */
+export declare const WORKFLOW_PICKER_DRAFT_COMPLETION: readonly ["workflowPickerConfig.presetFilters[].fromInputId (resolved from formControlName)"];
+export {};

package/dist/skillet/members/document-picker.js

@@ -0,0 +1,111 @@
+import { s } from '@hashbrownai/core';
+import { DOCUMENT_PICKER_FILTER_OPERATORS, DOCUMENT_PICKER_FILTER_VALUE_TYPES, } from '../../interfaces/formInput/WorkflowDocumentPicker.js';
+import { exhaustive, optional } from '../internal/coupling.js';
+import { describe, describeIn } from '../internal/editor-guidance.js';
+// --- the value-source discriminator -----------------------------------------
+/**
+ * The two value sources, addressed by meaning.
+ *
+ * Each branch of the filter union carries DIFFERENT members, so these literals
+ * cannot be taken positionally out of `DOCUMENT_PICKER_FILTER_VALUE_SOURCES`:
+ * reordering that array would quietly file `value` and `valueType` under the
+ * input-bound source, and produce filters that validate and never match.
+ * {@link exhaustive} is this codebase's answer to restating members safely —
+ * the union it checks against is itself read off that array, so adding a third
+ * source fails to compile here until it is given a branch of its own.
+ */
+const [FIXED_SOURCE, INPUT_SOURCE] = exhaustive()([
+    'fixed',
+    'input',
+]);
+// --- schema -----------------------------------------------------------------
+/**
+ * The `deepBind` of the row that opens the preset-filter editor. The filter
+ * members below bind relative to the record that editor edits, so their
+ * guidance is looked up within it rather than at the top level — see
+ * `internal/editor-guidance.ts` for why the two indexes are kept apart.
+ */
+const FILTER_EDITOR = ['workflowPickerConfig', 'presetFilters'];
+// Shared by both branches, so declared once: a clause targets a field and
+// compares it the same way whichever side supplies the value.
+const filterPath = s.string(describeIn('The document field this clause compares. It must be a field the transactions of the chosen workflow actually carry — a field of their form, or one of the properties the document itself exposes.', FILTER_EDITOR, 'path'));
+const filterOp = optional(s.enumeration(describeIn("How the field is compared. Leave it null for the default, which is 'eq'. 'in' and 'nin' read the fixed value as a comma-separated list, and 'exists' ignores the comparison entirely and only tests whether the field is present, so pair it with a boolean value.", FILTER_EDITOR, 'op'), [...DOCUMENT_PICKER_FILTER_OPERATORS]));
+/**
+ * The fixed branch.
+ *
+ * Its value node is a union and so has no description slot of its own. The
+ * editor's guidance is composed onto the string branch, the only one the comma
+ * rule for `in` / `nin` can apply to; repeating it on the numeric and boolean
+ * branches would put the same sentence in one prompt three times for no gain,
+ * because the choice being made there is the type, not the format.
+ */
+const fixedValueFilter = s.object(describeIn('Compares the field against a value written into the form definition itself. Use this for a restriction that is always true of this picker, such as only ever offering approved transactions.', FILTER_EDITOR, 'valueSource'), {
+    path: filterPath,
+    op: filterOp,
+    valueSource: s.literal(FIXED_SOURCE),
+    value: s.anyOf([
+        s.string(describeIn('The fixed value, as text. Write it as the field is stored, not as it is labelled on screen.', FILTER_EDITOR, 'value')),
+        s.number('The fixed value, as a number. Set valueType to number to match.'),
+        s.boolean('The fixed value, as a boolean. Set valueType to boolean to match.'),
+    ]),
+    valueType: optional(s.enumeration(describeIn("How the fixed value is read before it is compared. Leave it null for the default, which is 'string'.", FILTER_EDITOR, 'valueType'), [...DOCUMENT_PICKER_FILTER_VALUE_TYPES])),
+});
+/** The input-bound branch. */
+const inputValueFilter = s.object(describeIn('Compares the field against whatever the user has entered in another field of this form, read when the picker is opened. Use this to tie the picker to a choice the user makes earlier in the same form.', FILTER_EDITOR, 'valueSource'), {
+    path: filterPath,
+    op: filterOp,
+    valueSource: s.literal(INPUT_SOURCE),
+    // Named for the interface member it becomes, but carrying a
+    // formControlName: the model knows the fields it just wrote by name and has
+    // no way to know the ids the runtime keys them by. The application performs
+    // that lookup — see the draft note in this file's header.
+    fromInputId: s.string(describeIn('The formControlName of the field on this form to take the value from. It must be a field that actually exists in the form being authored, and one the user reaches before this picker. The application resolves the name to that field’s input id.', FILTER_EDITOR, 'fromInputId')),
+    omitWhenEmpty: s.boolean(describeIn('Whether to drop this clause while that field is still empty. Prefer true: false filters on the empty value literally, so the user opens the picker, is shown nothing, and has no way to tell that the cause is a field further up the form.', FILTER_EDITOR, 'omitWhenEmpty')),
+});
+/**
+ * One preset filter, as a union over the two value sources.
+ *
+ * The exclusivity is real rather than conventional: the runtime uses one source
+ * and ignores the other, so a clause carrying both is not a richer clause — it
+ * is a clause half of whose configuration silently does nothing. Modelling it
+ * as a union makes the model choose the source BEFORE it is offered the members
+ * that source uses, instead of handing it a flat record of six optional keys
+ * and leaving it to infer which combinations mean anything.
+ */
+const presetFilter = s.anyOf([fixedValueFilter, inputValueFilter]);
+/**
+ * Builds the `workflowPickerConfig` schema over the workflows the caller has.
+ *
+ * @param options the workflows the model may choose between. Empty — the
+ *   default — yields `null` rather than a schema whose only required field
+ *   would have to be invented.
+ * @returns the schema, or `null` when there is no workflow to point it at.
+ */
+export function createWorkflowPickerSchema(options = {}) {
+    const workflows = options.workflows ?? [];
+    if (!workflows.length)
+        return null;
+    // Rendered into prose so the choice is made on the workflow's meaning rather
+    // than on the shape of its id, which carries none.
+    const candidates = workflows.map((w) => `${w.id} (${w.name})`).join('; ');
+    return s.object('Which workflow a document picker browses, and how its list of transactions is narrowed before the user sees it. Set this only on a control that picks an existing transaction.', {
+        workflowId: s.enumeration(describe(`Whose transactions this picker lists. Everything else here is scoped by it. Choose by meaning, not by position: ${candidates}.`, 'workflowPickerConfig', 'workflowId'), workflows.map((w) => w.id)),
+        stepFilter: optional(s.object('Restricts the picker to transactions currently sitting on particular workflow steps.', {
+            stepIds: s.array(describe('Workflow step ids the picker is limited to. These ids belong to the workflow and are not listed here, so leave the whole step filter null unless the request names real ones — an id that does not exist narrows the picker to nothing, and nothing says so. An empty list means the same as no filter: every step is eligible, and the user chooses one while browsing.', 'workflowPickerConfig', 'stepFilter', 'stepIds'), s.string('A workflow step id, exactly as the workflow defines it.')),
+        })),
+        presetFilters: s.array(describe('Filters applied before the user searches, each one narrowing which transactions can be picked at all. Leave this empty unless a restriction was actually asked for: every clause here is one the user can neither see nor undo.', 'workflowPickerConfig', 'presetFilters'), presetFilter),
+    });
+}
+/**
+ * Members of a generated `workflowPickerConfig` the application must resolve.
+ *
+ * Only one, and it is not a Joi requirement — `presetFilters[].id` is optional
+ * there, so an unexpanded filter still validates. It is listed because it would
+ * still be WRONG: `fromInputId` is keyed by input id, and a draft carries a
+ * formControlName in that slot. A filter left unresolved passes validation and
+ * then matches nothing, which is the failure mode this whole layer is most
+ * concerned with.
+ */
+export const WORKFLOW_PICKER_DRAFT_COMPLETION = [
+    'workflowPickerConfig.presetFilters[].fromInputId (resolved from formControlName)',
+];

package/dist/skillet/members/mat-options.d.ts

@@ -0,0 +1,187 @@
+import { s } from '@hashbrownai/core';
+import { DataSources } from '../../interfaces/formInput/APIDataFetchingConfigurationInterface.js';
+import type { FormInputBasicOptionInterface } from '../../interfaces/formInput/FormInputBasicOptionInterface.js';
+/**
+ * The `matOptions` member: where a control's value and its options come from.
+ *
+ * ## Why this is a factory, and why it produces a draft
+ *
+ * `APIDataFetchingConfigurationInterface` requires `_id`, `name`,
+ * `httpEndPoint`, `httpMethod`, `postFormData` and `backEndConfig`. A model
+ * asked for that will happily produce `httpEndPoint:
+ * 'https://api.example.com/departments'` and a plausible `_id`, and the result
+ * is a form that looks correct and is entirely broken — it points at an
+ * endpoint that does not exist. Of everything in these schemas, that is the
+ * failure most likely to reach production unnoticed, because nothing about the
+ * output looks wrong.
+ *
+ * The form builder never asks a human to do this either. The editor row for
+ * this property is `apiEndpointConfig`, backed by `postmanCollectionConfig` and
+ * `httpGetDataFunction` — the author PICKS an endpoint from a collection
+ * supplied at runtime. So the model picks too: {@link createMatOptionsSchema}
+ * takes the endpoints and workflows available in the caller's context and emits
+ * an enumeration over their ids. A source that has no candidates is not offered
+ * at all, which is why the branches are conditional rather than always present.
+ *
+ * The consequence is that this schema produces a {@link MatOptionsDraft}, not a
+ * `MatDataOptionsInterface`: an api draft carries the id of an endpoint, and
+ * the application expands it into the stored configuration before the form is
+ * validated. That expansion is the caller's job and there is no way around it —
+ * the full configuration is simply not knowable from a prompt.
+ *
+ * ## Deliberate narrowing
+ *
+ * `options` is declared as `Array<FormInputBasicOptionInterface |
+ * DynamicObjectInterface>`. The second branch is an index signature, which
+ * Skillet cannot express and a model has no basis for inventing, so only the
+ * `{ label, value }` shape is offered.
+ *
+ * A `mongoPipeline` source carries `pipeline: any[]` — a raw aggregation
+ * pipeline. Selecting the workflow is offered; authoring the pipeline is not.
+ */
+/** An endpoint the caller has available for the model to choose between. */
+export interface AvailableApiEndpoint {
+    /** The persisted `_id` of the endpoint configuration. */
+    id: string;
+    /** Human name, shown to the model so it can choose on meaning, not on id. */
+    name: string;
+    /** What the endpoint returns, if known. Sharpens the choice considerably. */
+    description?: string;
+}
+/** A workflow whose data pipeline the caller has available. */
+export interface AvailableWorkflow {
+    id: string;
+    name: string;
+}
+export interface MatOptionsSchemaOptions {
+    /**
+     * Endpoints the model may select for an `api` source. Omit, or pass an empty
+     * list, and the `api` branch is not offered — which is the safe default,
+     * because the alternative is a hallucinated URL.
+     */
+    apiEndpoints?: readonly AvailableApiEndpoint[];
+    /** Workflows the model may select for a `mongoPipeline` source. */
+    workflows?: readonly AvailableWorkflow[];
+}
+export interface LocalSourceDraft {
+    source: DataSources.Local;
+    inputSourceId: string;
+    allowManualValueEntry: boolean;
+}
+export interface CustomOptionsSourceDraft {
+    source: DataSources.CustomOptions;
+}
+export interface ApiSourceDraft {
+    source: DataSources.Api;
+    endpointId: string;
+    allowManualValueEntry: boolean;
+}
+export interface MongoSourceDraft {
+    source: DataSources.MongoDb;
+    workflowId: string;
+}
+export type ValueSourceDraft = LocalSourceDraft | CustomOptionsSourceDraft | ApiSourceDraft | MongoSourceDraft;
+export interface MatOptionsDraft {
+    optionType: 'user' | null;
+    options: FormInputBasicOptionInterface[];
+    fetch: {
+        value: ValueSourceDraft | null;
+        options: ValueSourceDraft | null;
+    };
+}
+/**
+ * Builds the `matOptions` schema for the sources available to the caller.
+ *
+ * @param options endpoints and workflows the model may choose between. Both
+ *   default to empty, which offers only the sources a model can author outright
+ *   and cannot get factually wrong.
+ */
+export declare function createMatOptionsSchema(options?: MatOptionsSchemaOptions): s.ObjectType<{
+    optionType: import("@hashbrownai/core/src/schema/base").SchemaForUnion<"user" | null>;
+    options: s.ArrayType<s.ObjectType<{
+        label: s.StringType;
+        value: s.StringType;
+    }>>;
+    fetch: s.ObjectType<{
+        value: import("@hashbrownai/core/src/schema/base").SchemaForUnion<{
+            source: DataSources.Local;
+            inputSourceId: string;
+            allowManualValueEntry: boolean;
+        } | {
+            source: DataSources.CustomOptions;
+        } | {
+            source: DataSources.Api;
+            endpointId: string;
+            allowManualValueEntry: boolean;
+        } | {
+            source: DataSources.MongoDb;
+            workflowId: string;
+        } | null>;
+        options: import("@hashbrownai/core/src/schema/base").SchemaForUnion<{
+            source: DataSources.Local;
+            inputSourceId: string;
+            allowManualValueEntry: boolean;
+        } | {
+            source: DataSources.CustomOptions;
+        } | {
+            source: DataSources.Api;
+            endpointId: string;
+            allowManualValueEntry: boolean;
+        } | {
+            source: DataSources.MongoDb;
+            workflowId: string;
+        } | null>;
+    }>;
+}>;
+/**
+ * The default `matOptions` schema: no external endpoints or workflows, so it
+ * offers only the sources a model can author correctly from a prompt alone.
+ *
+ * Callers holding a real endpoint collection should build their own with
+ * {@link createMatOptionsSchema} rather than reaching for this one.
+ */
+export declare const matOptionsSchema: s.ObjectType<{
+    optionType: import("@hashbrownai/core/src/schema/base").SchemaForUnion<"user" | null>;
+    options: s.ArrayType<s.ObjectType<{
+        label: s.StringType;
+        value: s.StringType;
+    }>>;
+    fetch: s.ObjectType<{
+        value: import("@hashbrownai/core/src/schema/base").SchemaForUnion<{
+            source: DataSources.Local;
+            inputSourceId: string;
+            allowManualValueEntry: boolean;
+        } | {
+            source: DataSources.CustomOptions;
+        } | {
+            source: DataSources.Api;
+            endpointId: string;
+            allowManualValueEntry: boolean;
+        } | {
+            source: DataSources.MongoDb;
+            workflowId: string;
+        } | null>;
+        options: import("@hashbrownai/core/src/schema/base").SchemaForUnion<{
+            source: DataSources.Local;
+            inputSourceId: string;
+            allowManualValueEntry: boolean;
+        } | {
+            source: DataSources.CustomOptions;
+        } | {
+            source: DataSources.Api;
+            endpointId: string;
+            allowManualValueEntry: boolean;
+        } | {
+            source: DataSources.MongoDb;
+            workflowId: string;
+        } | null>;
+    }>;
+}>;
+/**
+ * Members of a generated `matOptions` the application must expand.
+ *
+ * `endpointId` and `workflowId` are draft-only keys that do not exist on
+ * `MatDataOptionsInterface` at all — Joi rejects unknown keys, so a draft that
+ * reaches the validator unexpanded fails outright rather than degrading.
+ */
+export declare const MAT_OPTIONS_DRAFT_COMPLETION: readonly ["matOptions.fetch.value|options.endpointId (expanded to the stored APIDataFetchingConfiguration)", "matOptions.fetch.value|options.workflowId (expanded to the stored pipeline configuration)", "matOptions.fetch.value|options.inputSourceId (resolved from formControlName to an input id)"];

package/dist/skillet/members/mat-options.js

@@ -0,0 +1,92 @@
+import { s } from '@hashbrownai/core';
+import { DataSources } from '../../interfaces/formInput/APIDataFetchingConfigurationInterface.js';
+import { describe } from '../internal/editor-guidance.js';
+// --- schema -----------------------------------------------------------------
+const optionSchema = s.object('A selectable option.', {
+    label: s.string('The text shown to the user. It may change freely.'),
+    value: s.string("The value stored when this option is chosen: a single word with no spaces ('urgent', 'capex'), kept stable once the form is live. A decision gate compares the stored value, not the label, and splits its expression on spaces."),
+});
+/** Renders the endpoint list into prose so the model chooses on meaning. */
+function describeCandidates(lead, candidates) {
+    const lines = candidates.map((c) => c.description ? `${c.id} (${c.name}: ${c.description})` : `${c.id} (${c.name})`);
+    return `${lead} Choose by meaning, not by position: ${lines.join('; ')}.`;
+}
+function sourceBranches(slot, options) {
+    const localLead = slot === 'value'
+        ? 'Takes its value from another field on this form.'
+        : 'Takes its options from another field on this form.';
+    const endpoints = options.apiEndpoints ?? [];
+    const workflows = options.workflows ?? [];
+    // Built by conditional spread rather than by pushing onto an array: a `push`
+    // would have to widen every branch to the shape of the first two, which
+    // erases the per-branch typing that `s.Infer` needs to reconstruct the union.
+    return [
+        s.object(describe(localLead, 'matOptions', 'fetch', slot, 'source'), {
+            source: s.literal(DataSources.Local),
+            inputSourceId: s.string('The formControlName of the field on this form to read from. It must be a field that actually exists in the form being authored.'),
+            allowManualValueEntry: s.boolean('Only meaningful on the value slot of a field whose dataType is object or array (an mSCOA, a multiple-input table). An inherited value of that shape can arrive partly filled in — only some mSCOA segments, rows missing a column — and this decides whether the user may finish it. True leaves the field editable: whenever the inherited value changes, only what actually changed is applied over it and whatever the user added is kept. False locks the field. Choose false unless the field is object- or array-shaped AND the source field is expected to supply only part of it. It has no effect on a scalar field or on an options slot, where the inherited value always wins.'),
+        }),
+        s.object('Uses a fixed list of options authored into the form itself.', {
+            source: s.literal(DataSources.CustomOptions),
+        }),
+        ...(endpoints.length
+            ? [
+                s.object('Fetches from a configured API endpoint.', {
+                    source: s.literal(DataSources.Api),
+                    endpointId: s.enumeration(describeCandidates('Which configured endpoint to call.', endpoints), endpoints.map((e) => e.id)),
+                    allowManualValueEntry: s.boolean('Whether the user may supply what the endpoint does not. On a scalar field: true lets a value they type stand whenever the endpoint contributes nothing (no response, an empty one, a failed request), and a non-empty response always wins over what they typed. On a field whose dataType is object or array (an mSCOA, a multiple-input table): true leaves the field editable so they can finish a response that arrives incomplete — rows missing a column, only some mSCOA segments — and each new response is applied over the live value as a delta, so what the endpoint sends updates and what the user added is kept. False locks the field, which is the right choice whenever the endpoint answers completely.'),
+                }),
+            ]
+            : []),
+        ...(workflows.length
+            ? [
+                s.object('Fetches through a workflow data pipeline.', {
+                    source: s.literal(DataSources.MongoDb),
+                    workflowId: s.enumeration(describeCandidates('Which workflow supplies the data.', workflows), workflows.map((w) => w.id)),
+                }),
+            ]
+            : []),
+    ];
+}
+/**
+ * Builds the `matOptions` schema for the sources available to the caller.
+ *
+ * @param options endpoints and workflows the model may choose between. Both
+ *   default to empty, which offers only the sources a model can author outright
+ *   and cannot get factually wrong.
+ */
+export function createMatOptionsSchema(options = {}) {
+    const valueSource = s.anyOf(sourceBranches('value', options));
+    const optionsSource = s.anyOf(sourceBranches('options', options));
+    return s.object('Where this control gets its value and the options it offers. Only set this on a control that actually reads from somewhere; a plain text input does not.', {
+        optionType: s.anyOf([
+            s.literal('user'),
+            s.nullish(),
+        ]),
+        options: s.array(describe('The fixed options offered by this control, for a short list fixed by policy. Fill this in only when the options source is a custom list; leave it empty otherwise. Never retype a list a system already owns — departments, suppliers, users, cost centres — as custom options; it goes stale.', 'matOptions', 'options'), optionSchema),
+        fetch: s.object('Where the value and the options are read from.', {
+            value: s.anyOf([valueSource, s.nullish()]),
+            options: s.anyOf([optionsSource, s.nullish()]),
+        }),
+    });
+}
+/**
+ * The default `matOptions` schema: no external endpoints or workflows, so it
+ * offers only the sources a model can author correctly from a prompt alone.
+ *
+ * Callers holding a real endpoint collection should build their own with
+ * {@link createMatOptionsSchema} rather than reaching for this one.
+ */
+export const matOptionsSchema = createMatOptionsSchema();
+/**
+ * Members of a generated `matOptions` the application must expand.
+ *
+ * `endpointId` and `workflowId` are draft-only keys that do not exist on
+ * `MatDataOptionsInterface` at all — Joi rejects unknown keys, so a draft that
+ * reaches the validator unexpanded fails outright rather than degrading.
+ */
+export const MAT_OPTIONS_DRAFT_COMPLETION = [
+    'matOptions.fetch.value|options.endpointId (expanded to the stored APIDataFetchingConfiguration)',
+    'matOptions.fetch.value|options.workflowId (expanded to the stored pipeline configuration)',
+    'matOptions.fetch.value|options.inputSourceId (resolved from formControlName to an input id)',
+];