ngx-t-forms-types 0.0.30 → 0.0.34

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

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

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

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

package/dist/skillet/members/conditional.js

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

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)',
+];