@pipelex/mthds-form 0.2.0 → 0.4.0

package/dist/core/date-format.js

@@ -0,0 +1,3 @@
+export { asCalendarDate, dayWithinDateTime, isAcceptableDate, isAcceptableDateTime, toDateInputValue, toStoredDateValue } from '../chunk-GKV77RAS.js';
+//# sourceMappingURL=date-format.js.map
+//# sourceMappingURL=date-format.js.map

package/dist/core/date-format.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"date-format.js"}

package/dist/core/derive.d.ts

@@ -0,0 +1,20 @@
+import { PipeInputContract } from './contracts.js';
+import { RunField } from './descriptor.js';
+
+/**
+ * The ONE derivation function: `PipeInputContract` map → `RunField[]`.
+ *
+ * Everything heuristic stays module-private behind `buildRunFields`: the
+ * native-concept taxonomy, `isDocumentObject`, the depth-based prose/label
+ * rule, the `accept` strings, list splitting. Nothing here is exported except
+ * the function itself - so the M1 milestone can swap the source of the
+ * descriptor (server-derived) without touching consumers.
+ */
+
+/**
+ * Convert the API's per-input contracts into the runner's field descriptors.
+ * The map's insertion order is preserved (required-first is the caller's job).
+ */
+declare function buildRunFields(inputs: Record<string, PipeInputContract>): RunField[];
+
+export { buildRunFields };

package/dist/core/derive.js

@@ -0,0 +1,7 @@
+export { buildRunFields } from '../chunk-VMLXO5JS.js';
+import '../chunk-O4O3QNVC.js';
+import '../chunk-HARYEWNG.js';
+import '../chunk-V3OV2XQT.js';
+import '../chunk-NMT7BRLO.js';
+//# sourceMappingURL=derive.js.map
+//# sourceMappingURL=derive.js.map

package/dist/core/derive.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"derive.js"}

package/dist/{descriptor-X6MwFIWu.d.ts → core/descriptor.d.ts}

@@ -30,6 +30,20 @@ interface RunFieldCommon {
      * they are gated through their parent's `fieldFilled`.
      */
     gating?: boolean;
+    /**
+     * The single property this field's value sits inside on the wire, when its
+     * concept declares a scalar content model: `native.Text` is `TextContent
+     * {text}`, `native.Number` is `NumberContent {number}`, `native.YesNo` is
+     * `YesNoContent {yes_no}`. The control still holds the plain scalar; the
+     * value bridge wraps into this property on the way out and unwraps on the way
+     * back in.
+     *
+     * A property NAME, never a schema - the descriptor stays the only currency
+     * and `buildRunFields` stays the only reader of JSON Schema. Absent whenever
+     * the value is already the whole content (a structured concept, a file, a
+     * child property of a structure): wrapping those would double-nest them.
+     */
+    contentKey?: string;
 }
 interface TextRunField extends RunFieldCommon {
     kind: 'text';
@@ -75,6 +89,33 @@ interface ListRunField extends RunFieldCommon {
     kind: 'list';
     /** The element descriptor (its `name` is unused; the index labels items). */
     item: RunField;
+    /**
+     * The FEWEST items the slot accepts, when the schema states a lower bound.
+     * Absent for a variable `Concept[]` list, which demands none.
+     *
+     * Read off the array schema's `minItems` rather than off the contract's
+     * `item_count`, which states the same number: this exists so `fieldFilled` can
+     * answer the question **ajv** answers, and `minItems` is the keyword ajv
+     * reads. pipelex emits `minItems`/`maxItems` = N for a `[N]` slot and neither
+     * for `[]`, so on a top-level slot the two sources agree by construction.
+     *
+     * A schema may still state a lower bound alone - `mapSchema` recurses, so a
+     * nested array inside a structured concept reaches here with whatever its
+     * model declared and no MTHDS multiplicity behind it. Gating on that bound is
+     * the same rule, and it is the direction that cannot leave readiness more
+     * permissive than the gate.
+     */
+    itemCount?: number;
+    /**
+     * The MOST items the slot accepts, off the schema's `maxItems`.
+     *
+     * A separate field because it is a separate fact, and conflating them is a
+     * bug that hides: `itemCount` was read as a minimum by readiness and as a
+     * maximum by the control that stops offering `Add`, which agree only while
+     * a contract states both bounds equal. A list told "at least two" was then
+     * presented as a list of exactly two.
+     */
+    maxItemCount?: number;
 }
 interface UnknownRunField extends RunFieldCommon {
     kind: 'unknown';
@@ -84,4 +125,4 @@ type RunField = TextRunField | ProseRunField | DateRunField | NumberRunField | B
 type ConceptCategory = 'text' | 'date' | 'document' | 'image' | 'number' | 'boolean' | 'choice' | 'structured' | 'list';
 declare function conceptCategory(field: RunField): ConceptCategory;
 
-export { type BooleanRunField as B, type ConceptCategory as C, type DateRunField as D, type EnumRunField as E, type FileRunField as F, type ListRunField as L, type NumberRunField as N, type ObjectRunField as O, type ProseRunField as P, type RunField as R, type TextRunField as T, type UnknownRunField as U, type RunFieldCommon as a, type RunFieldKind as b, conceptCategory as c };
+export { type BooleanRunField, type ConceptCategory, type DateRunField, type EnumRunField, type FileRunField, type ListRunField, type NumberRunField, type ObjectRunField, type ProseRunField, type RunField, type RunFieldCommon, type RunFieldKind, type TextRunField, type UnknownRunField, conceptCategory };

package/dist/core/descriptor.js

@@ -0,0 +1,3 @@
+export { conceptCategory } from '../chunk-6XD6UZSU.js';
+//# sourceMappingURL=descriptor.js.map
+//# sourceMappingURL=descriptor.js.map

package/dist/core/descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"descriptor.js"}

package/dist/core/gate-validator.d.ts

@@ -0,0 +1,27 @@
+/**
+ * One validation error, in the shape hosts read (`property`, `message`,
+ * `name`, `stack`, `params.format`). Structurally a superset-compatible twin of
+ * RJSF's `RJSFValidationError`, so a host surface still holding RJSF form errors
+ * (an RJSF-based inputs panel) can hand them to the same message renderer.
+ */
+interface RunInputError {
+    /** The ajv keyword that failed (`required`, `format`, `type`, …). */
+    name?: string;
+    /** Dotted path into the form data (`.quote_date.date`); for a `required`
+     *  error the missing property name is appended (top-level: no leading dot). */
+    property?: string;
+    message?: string;
+    params?: Record<string, unknown>;
+    /** The human line: `property message`, or `'title' message` when the parent
+     *  schema titles the field. */
+    stack: string;
+    schemaPath?: string;
+}
+/**
+ * Validate `data` against `schema`, returning mapped errors (empty = valid).
+ * MUTATES `data` where ajv coerces (`"20"` → `20`) - deliberate and relied on:
+ * the string the user typed is stored as a number going forward.
+ */
+declare function validateRunInputsSchema(data: unknown, schema: object): RunInputError[];
+
+export { type RunInputError, validateRunInputsSchema };

package/dist/core/gate-validator.js

@@ -0,0 +1,4 @@
+export { validateRunInputsSchema } from '../chunk-VTPUDBSJ.js';
+import '../chunk-GKV77RAS.js';
+//# sourceMappingURL=gate-validator.js.map
+//# sourceMappingURL=gate-validator.js.map

package/dist/core/gate-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"gate-validator.js"}

package/dist/core/gate.d.ts

@@ -0,0 +1,144 @@
+import { RunInputError } from './gate-validator.js';
+import { PipeInputContract, PipeIOContract } from './contracts.js';
+
+type Dict = Record<string, unknown>;
+/**
+ * Combine the per-input schemas into one object schema.
+ *
+ * Each input variable becomes a property, titled with the variable name and
+ * described with the concept code. Only the inputs the method actually demands
+ * land in `required` - an optional (`?`) or variable-plural (`[]`) input must
+ * not block the form (see `inputMustBeFilled`).
+ *
+ * The per-input schema travels verbatim, which is how a fixed-count (`[N]`)
+ * list's declared count reaches ajv: pipelex states it as `minItems`/`maxItems`
+ * on the array wrapper, so the count is enforced here without the kernel
+ * restating it.
+ */
+declare function buildRunInputsSchema(inputs: Record<string, PipeInputContract>): Dict;
+/**
+ * Last-gate repair, in two passes against the exact schema ajv validates.
+ *
+ * 1. **HEAL** - persisted `inputData` may still carry the legacy double-wrapped
+ *    `{ text: { text } }` shape (or a form's state may lag a store fix).
+ * 2. **PRUNE** - RJSF fills every unset string with `""` on mount, which an
+ *    optional CONSTRAINED field rejects (`DateContent.time` is `format: "time"`)
+ *    - blocking a run on a field the user never opened. An absent optional field
+ *    is what pipelex means by `None` anyway, so dropping it is the semantically
+ *    correct repair, not a validation dodge.
+ */
+declare function prepareRunInputs(data: Dict, schema: Dict): Dict;
+interface RunInputsVerdict {
+    isValid: boolean;
+    /** Variable names the scan could pin a missing required field on. */
+    missingInputs: string[];
+    /** Raw ajv errors, for when the scan cannot name anything. */
+    errors: RunInputError[];
+}
+/**
+ * Validate PREPARED data against the combined schema.
+ *
+ * `missingInputs` is reported by VARIABLE NAME - the name on the node the user
+ * clicks - never by `concept_ref`, which used to produce "Missing required
+ * fields in: native.Text" and named neither the input at fault nor, when several
+ * inputs share a concept, which of them. Inputs the method declared omittable
+ * are skipped: an empty `?` input is not a missing one.
+ *
+ * The scan can come up empty even on an invalid form (a wrong value shape, a
+ * nested mismatch); `errors` is what the caller falls back to then, so a failure
+ * is never undiagnosable.
+ *
+ * `preparedData` is `unknown` for the same reason `gateRunInputs`' `data` is: on
+ * a public endpoint the body is whatever was sent, and ajv must be shown that
+ * rather than a repair of it, or `must be object` is a verdict no caller can
+ * ever receive. The name-the-variable scan below needs something indexable, so
+ * a body that is not a record scans against nothing and names every input the
+ * method demands - which is the honest answer for a body that carried none.
+ */
+declare function validateRunInputs(preparedData: unknown, inputs: Record<string, PipeInputContract>, schema: Dict): RunInputsVerdict;
+/**
+ * Build the `{ concept, content }` map a run expects, from PREPARED data.
+ *
+ * The two ways a method says "this may be nothing" land differently on the wire:
+ * - an **optional (`?`)** input left blank is OMITTED, so the runtime records a
+ *   real absence the method can branch on - sending `{ text: "" }` would look
+ *   like the caller supplied an empty string;
+ * - a **plural (`[]`)** input keeps its key, because a plural slot is never
+ *   absent - its empty form IS the empty list, and the runtime requires the key.
+ *   When that list is EMPTY it is sent BARE, without the envelope: the envelope
+ *   is the runtime's "explicit form", which bypasses the top-down shaper and
+ *   hands the value to the bottom-up factory, and that factory types a list from
+ *   its first item - so an empty list there raises "Cannot create Stuff from
+ *   empty list in content". The bare form keeps the shaper, which reads the
+ *   DECLARED concept and builds the empty list correctly. (pipelex/#1096 makes
+ *   the envelope agree; the bare form runs today and stays correct after.)
+ *
+ * A fixed-count (`[N]`) list takes that same empty-list path, and an empty one
+ * is not a payload the method can accept. It is unreachable through the gate,
+ * which demands the input and rejects a short list on `minItems`; building the
+ * payload straight from unvalidated data is what would reach it, and inventing
+ * a different absence here would only hide that.
+ */
+declare function apiInputsFromSchemaData(preparedData: Dict, inputs: Record<string, PipeInputContract>): Dict;
+/** The gate's verdict: the payload to send, or why the run may not start. */
+type RunInputsGateResult = {
+    ok: true;
+    inputs: Dict;
+} | {
+    ok: false;
+    /** Variable names the caller left empty or short. */
+    missingInputs: string[];
+    /** Raw ajv errors, for when the scan cannot name anything. */
+    errors: RunInputError[];
+    /** The repaired data the verdict was reached on - what
+     *  `describeValidationError` needs to quote the value it received. */
+    preparedData: Dict;
+};
+/**
+ * Gate a run: repair the caller's data, validate it against the contract,
+ * refuse anything the Run button would have refused, and build the payload.
+ *
+ * Returns a verdict rather than throwing. A server endpoint must not throw
+ * across the boundary to its client - frameworks routinely strip the message to
+ * an opaque digest in a production build - and a rejection here is an ordinary
+ * outcome, not an exceptional one.
+ *
+ * **`data` is `unknown` because that is what it is.** A run endpoint is public
+ * and no framework enforces a declared parameter type, so the argument is
+ * whatever the caller put in the body. The chain indexes the payload by
+ * variable name without first checking it is indexable, so a `null` body would
+ * throw *after* ajv had already reported `must be object` and before any
+ * verdict came back.
+ *
+ * So the two uses are separated rather than collapsed into one repair. **ajv
+ * judges the value the caller actually sent**, which is what makes `must be
+ * object` the verdict for a body that is not one; the indexing that follows
+ * uses a safe `{}` stand-in, which is what keeps the gate from throwing. Repair
+ * FIRST - coercing a non-object to `{}` before validating - is the shape that
+ * looks equivalent and is not: a contract whose inputs are all optional has an
+ * empty `required` list, so `{}` validates, and `gateRunInputs("garbage", …)`
+ * came back `ok: true` on a body the caller never meant as a run. Fail-closed
+ * costs a malformed caller an error it earned; the other direction bills a run.
+ *
+ * **The schema alone is not the rule.** ajv's `required` asserts only that a
+ * key is PRESENT, and a content model carries no `minLength` - so a required
+ * input that arrived empty (`{document: {url: ""}}`, `{text: {text: ""}}`)
+ * satisfies the schema. That is the natural payload, not a contrived one:
+ * `rjsfDataFromRunValues({}, fields)` emits exactly that when nothing is
+ * selected. So the gate re-applies the emptiness rule using
+ * `computeReadiness`'s OWN two functions over the same derived fields, which is
+ * the only way to be sure the two sides cannot disagree.
+ *
+ * Picking a pair that merely looks equivalent is not enough, and this is the
+ * whole reason the assembly lives here rather than in each host: the obvious
+ * choice, `inputMustBeFilled` + `isFilled`, agrees on every leaf kind and
+ * diverges on a structured concept in BOTH directions - `isFilled` on an object
+ * is `some(child filled)` where `fieldFilled` is `every(required child
+ * filled)`. That accepts a half-filled struct the browser refuses (a paid run
+ * past a disabled button) and rejects a filled all-optional struct the browser
+ * accepts. A host whose methods happen to use only native concepts has no test
+ * that can catch either.
+ */
+declare function gateRunInputs(contract: PipeIOContract, data: unknown): RunInputsGateResult;
+
+export { type RunInputsGateResult, type RunInputsVerdict, apiInputsFromSchemaData, buildRunInputsSchema, gateRunInputs, prepareRunInputs, validateRunInputs };

package/dist/core/gate.js

@@ -0,0 +1,13 @@
+export { apiInputsFromSchemaData, buildRunInputsSchema, gateRunInputs, prepareRunInputs, validateRunInputs } from '../chunk-XEPD5VJQ.js';
+import '../chunk-KFZ5MZOM.js';
+import '../chunk-7BMOPXDY.js';
+import '../chunk-PM55AHRO.js';
+import '../chunk-VMLXO5JS.js';
+import '../chunk-O4O3QNVC.js';
+import '../chunk-HARYEWNG.js';
+import '../chunk-V3OV2XQT.js';
+import '../chunk-VTPUDBSJ.js';
+import '../chunk-GKV77RAS.js';
+import '../chunk-NMT7BRLO.js';
+//# sourceMappingURL=gate.js.map
+//# sourceMappingURL=gate.js.map

package/dist/core/gate.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"gate.js"}