@texaryn/core 0.8.0 → 0.10.0

package/dist/runtime/types.d.ts

@@ -4,11 +4,49 @@ import type { UIHints } from '../hints/types.js';
 import type { Command } from '../commands/types.js';
 import type { SubmissionState } from '../ir/runtime-state.js';
 import type { NodeId, MaybePromise, ValidationError, VisibleError } from '../types.js';
+import type { DefaultConflict, DefaultRefusal } from '../initialization/index.js';
+/** Which initialization policy consumes the schema's `default` annotations. */
+export type InitializationPolicy = 'none' | 'schema-defaults';
+/**
+ * What one run of ADR-003's initialization pass did, without the data, which
+ * the runtime publishes on `data` like any other.
+ *
+ * A discarded run reports only that it was discarded. Carrying the conflicts
+ * and refusals of the run that produced them would say a run found them and
+ * then say nothing was written, and the two readings are not the same claim.
+ */
+export type InitializationReport = {
+    readonly outcome: 'initialized';
+    /** Locations left absent because their applicable declarations disagreed. */
+    readonly conflicts: readonly DefaultConflict[];
+    /** Locations left absent because filling would have meant guessing or destroying. */
+    readonly refusals: readonly DefaultRefusal[];
+    readonly passes: number;
+} | {
+    readonly outcome: 'budget-exhausted';
+    readonly passes: number;
+};
 export interface FormRuntimeOptions {
     initialData?: unknown;
     hints?: UIHints;
     onSubmit?: (data: unknown) => MaybePromise<void>;
     validationDebounceMs?: number;
+    /**
+     * ADR-003. `'none'`, the default, materialises nothing: given `{}` the
+     * runtime's data stays `{}`.
+     *
+     * `'schema-defaults'` fills every reachable location the schema declares a
+     * default for and the data leaves absent. A location is filled when it
+     * becomes reachable, so this runs at construction, on `Reset`, and after any
+     * edit that can change what is reachable: activating a `oneOf` branch by
+     * setting its discriminator fills that branch's own defaults. It never
+     * overwrites, so `false`, `0`, `''` and `null` are values and are left alone.
+     *
+     * What the run wrote is the baseline at construction and on `Reset`, and is
+     * not between them: a location seeded by an edit differs from
+     * `state.initialData`, which is what `modified` reports.
+     */
+    initialization?: InitializationPolicy;
 }
 export interface NodeState {
     readonly value: Store<unknown>;
@@ -25,6 +63,26 @@ export interface FormRuntime {
     readonly data: Store<unknown>;
     readonly submission: Store<SubmissionState>;
     readonly visibleErrors: Store<VisibleError[]>;
+    /**
+     * The last initialization run, or `undefined` where no policy is configured.
+     *
+     * `dispatch` returns void and is typically called from an event handler, so a
+     * run that exhausts its budget reports here rather than throwing into the
+     * host's render. What that discards depends on the moment: a `Reset`
+     * establishes a baseline, so it is refused whole and nothing lands, while an
+     * ordinary edit establishes none, so the edit lands and only the seeding is
+     * dropped. `createFormRuntime` throws instead, because a caller can decline a
+     * runtime it never received.
+     *
+     * A new report is published on every data-mutating dispatch under the policy,
+     * including one where the pass wrote nothing, because each dispatch is a run
+     * and what a run finds changes as the user types. Anything subscribed here
+     * therefore updates per edit.
+     *
+     * It is not the projection's diagnostics channel, which describes a schema
+     * rather than one run over data.
+     */
+    readonly initialization: Store<InitializationReport | undefined>;
     dispatch(command: Command): void;
     getNodeState(nodeId: NodeId): NodeState | undefined;
     destroy(): void;

package/dist/runtime/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/runtime/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAC9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAChD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAA;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAC7D,OAAO,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAEtF,MAAM,WAAW,kBAAkB;IACjC,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,YAAY,CAAC,IAAI,CAAC,CAAA;IAChD,oBAAoB,CAAC,EAAE,MAAM,CAAA;CAC9B;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,CAAA;IAC9B,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,eAAe,EAAE,CAAC,CAAA;IACzC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,CAAA;IAC9B,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,CAAA;IAChC,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,CAAA;IAChC,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,CAAA;IACjC,QAAQ,CAAC,gBAAgB,EAAE,KAAK,CAAC,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC,CAAA;IAC1E,QAAQ,CAAC,UAAU,EAAE,KAAK,CAAC,OAAO,CAAC,CAAA;CACpC;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC,UAAU,CAAC,CAAA;IACpC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,CAAA;IAC7B,QAAQ,CAAC,UAAU,EAAE,KAAK,CAAC,eAAe,CAAC,CAAA;IAC3C,QAAQ,CAAC,aAAa,EAAE,KAAK,CAAC,YAAY,EAAE,CAAC,CAAA;IAC7C,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAA;IAChC,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAAA;IACnD,OAAO,IAAI,IAAI,CAAA;CAChB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/runtime/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAC9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAChD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAA;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAC7D,OAAO,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AACtF,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAA;AAEjF,+EAA+E;AAC/E,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,iBAAiB,CAAA;AAE7D;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,GAC5B;IACE,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAA;IAC/B,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,EAAE,SAAS,eAAe,EAAE,CAAA;IAC9C,qFAAqF;IACrF,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAA;IAC5C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB,GACD;IAAE,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAErE,MAAM,WAAW,kBAAkB;IACjC,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,YAAY,CAAC,IAAI,CAAC,CAAA;IAChD,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B;;;;;;;;;;;;;;OAcG;IACH,cAAc,CAAC,EAAE,oBAAoB,CAAA;CACtC;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,CAAA;IAC9B,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,eAAe,EAAE,CAAC,CAAA;IACzC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,CAAA;IAC9B,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,CAAA;IAChC,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,CAAA;IAChC,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,CAAA;IACjC,QAAQ,CAAC,gBAAgB,EAAE,KAAK,CAAC,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC,CAAA;IAC1E,QAAQ,CAAC,UAAU,EAAE,KAAK,CAAC,OAAO,CAAC,CAAA;CACpC;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC,UAAU,CAAC,CAAA;IACpC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,CAAA;IAC7B,QAAQ,CAAC,UAAU,EAAE,KAAK,CAAC,eAAe,CAAC,CAAA;IAC3C,QAAQ,CAAC,aAAa,EAAE,KAAK,CAAC,YAAY,EAAE,CAAC,CAAA;IAC7C;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,cAAc,EAAE,KAAK,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAAA;IAChE,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAA;IAChC,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAAA;IACnD,OAAO,IAAI,IAAI,CAAA;CAChB"}

package/dist/schema/port.d.ts

@@ -8,17 +8,20 @@ export interface SchemaEvaluationPort {
 export interface SchemaProjection {
     nodes: Map<JsonPointer, NodeProjection>;
     /**
-     * Every place the adapter could not choose a shape to render, and why.
+     * Every place the adapter could not choose, and why.
      *
-     * A pointer absent from `nodes` renders no field, and without this the
-     * caller cannot tell an intentional omission from a schema the adapter did
-     * not understand. That distinction is not cosmetic: a schema declaring a
-     * field the form silently never collects is the failure mode this exists to
-     * make visible.
+     * A pointer absent from `nodes` renders no field, and an annotation absent
+     * from a node states less than the schema does. Without this the caller
+     * cannot tell an intentional omission from a schema the adapter did not
+     * understand. That distinction is not cosmetic: a schema declaring a field
+     * the form silently never collects is the failure mode this exists to make
+     * visible.
      *
-     * The rule the codes divide up: an explicit `type` is used, an unambiguous
-     * structural shape is derived, and a schema that yields neither is reported
-     * here. Nothing is guessed and no schema disappears without a word.
+     * The rule the shape codes divide up: an explicit `type` is used, an
+     * unambiguous structural shape is derived, and a schema that yields neither
+     * is reported here. `ambiguous-default` is the same rule one level down, for
+     * a value rather than a shape. Nothing is guessed and nothing the schema
+     * declares disappears without a word.
      *
      * The boundary worth stating, because it is what keeps this channel worth
      * reading: these describe schemas, not data.
@@ -38,11 +41,17 @@ export interface SchemaProjection {
      *
      * Optional, so an adapter that reports nothing stays valid, and empty rather
      * than absent means "nothing to report".
+     *
+     * "Nothing to report" is per code rather than per adapter, and the
+     * conformance suite is what says which codes an adapter detects. An empty
+     * array is therefore not a claim that no code applies, only that none of the
+     * ones this adapter detects did.
      */
     diagnostics?: readonly ProjectionDiagnostic[];
 }
 /**
- * One reason a pointer has no node.
+ * One reason a pointer projects less than the schema declares: no node at all,
+ * or a node missing something the schema states.
  *
  * `code` is a stable identifier a caller can branch on; `message` is for a
  * person reading a log and is not a contract.
@@ -51,6 +60,21 @@ export interface ProjectionDiagnostic {
     pointer: JsonPointer;
     code: ProjectionDiagnosticCode;
     message: string;
+    /**
+     * The schema positions the diagnostic is about, as JSON Pointers into the
+     * schema document, with the root as the empty string. A position reached
+     * through `$ref` is named by what it resolves to rather than by the reference
+     * that pointed at it.
+     *
+     * Present where naming the positions is the useful half of the report, which
+     * is `ambiguous-default`: that two declarations disagree is far less
+     * actionable than which two. Optional because the other codes describe one
+     * schema position, already named by `pointer`.
+     *
+     * Order is not a contract. Which order an adapter walks its own applicators
+     * in is its own business; the set is what is being reported.
+     */
+    sources?: readonly string[];
 }
 export type ProjectionDiagnosticCode = 
 /**
@@ -65,7 +89,22 @@ export type ProjectionDiagnosticCode =
  * JSON Schema permits heterogeneous members, so `enum` says what the values
  * are and not what type they have.
  */
- | 'unresolved-projection-shape';
+ | 'unresolved-projection-shape'
+/**
+ * Two or more `default` declarations apply to the location whatever the
+ * instance is, and they do not agree. `AnnotationSet.default` is omitted:
+ * one value is reported where the schema states one, and where it states two
+ * that disagree there is nothing to report but the disagreement.
+ *
+ * Unconditional is what makes this a fact about the schema. A location's own
+ * declaration and those reached from it through `allOf` and `$ref` all apply
+ * together, so no instance resolves them. Declarations that arrive through
+ * `oneOf`, `anyOf`, `if`/`then`/`else` or `dependentSchemas` are partitioned
+ * by the branch that carries them: they compete with each other within one
+ * branch, and a branch competing with the base is a state of the data, which
+ * this channel deliberately does not carry.
+ */
+ | 'ambiguous-default';
 export interface NodeProjection {
     /**
      * The shape a renderer should present, which is not an assertion about the
@@ -139,6 +178,15 @@ export interface AnnotationSet {
     writeOnly?: boolean;
     deprecated?: boolean;
     examples?: unknown[];
+    /**
+     * The value the schema declares for a location that has none.
+     *
+     * Absent where two or more declarations apply unconditionally and disagree,
+     * with an `ambiguous-default` diagnostic in its place. A single value is
+     * reported where the schema states one; where it states two that disagree,
+     * reporting either would be a merge order presented as an answer, and the
+     * two adapters' merges do not even keep the same one.
+     */
     default?: unknown;
 }
 //# sourceMappingURL=port.d.ts.map

package/dist/schema/port.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"port.d.ts","sourceRoot":"","sources":["../../src/schema/port.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAC9F,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAElE,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,gBAAgB,CAAA;IAExC,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,YAAY,CAAC,gBAAgB,CAAC,CAAA;IAEvD,UAAU,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,GAAG,YAAY,CAAC,gBAAgB,CAAC,CAAA;CACjF;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,GAAG,CAAC,WAAW,EAAE,cAAc,CAAC,CAAA;IACvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,WAAW,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAA;CAC9C;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,WAAW,CAAA;IACpB,IAAI,EAAE,wBAAwB,CAAA;IAC9B,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,MAAM,wBAAwB;AAClC;;;;GAIG;AACD,4BAA4B;AAC9B;;;;;GAKG;GACD,6BAA6B,CAAA;AAEjC,MAAM,WAAW,cAAc;IAC7B;;;;;;;;;OASG;IACH,IAAI,EAAE,cAAc,CAAA;IACpB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,gBAAgB,CAAA;IAC7B,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAA;IAC5B,UAAU,CAAC,EAAE,UAAU,EAAE,CAAA;IACzB;;;;OAIG;IACH,MAAM,EAAE,OAAO,CAAA;IACf;;;;;;;;;;;;;OAaG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,WAAW,EAAE,aAAa,CAAA;IAC1B;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,aAAa,CAAA;CAChC;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,WAAW,CAAA;IACpB,GAAG,EAAE,MAAM,CAAA;IACX,gFAAgF;IAChF,QAAQ,EAAE,OAAO,CAAA;IACjB;;;;;;;;;;OAUG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAC9B;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAA;IACpB,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB"}
+{"version":3,"file":"port.d.ts","sourceRoot":"","sources":["../../src/schema/port.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAC9F,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAElE,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,gBAAgB,CAAA;IAExC,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,YAAY,CAAC,gBAAgB,CAAC,CAAA;IAEvD,UAAU,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,GAAG,YAAY,CAAC,gBAAgB,CAAC,CAAA;CACjF;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,GAAG,CAAC,WAAW,EAAE,cAAc,CAAC,CAAA;IACvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;IACH,WAAW,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAA;CAC9C;AAED;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,WAAW,CAAA;IACpB,IAAI,EAAE,wBAAwB,CAAA;IAC9B,OAAO,EAAE,MAAM,CAAA;IACf;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC5B;AAED,MAAM,MAAM,wBAAwB;AAClC;;;;GAIG;AACD,4BAA4B;AAC9B;;;;;GAKG;GACD,6BAA6B;AAC/B;;;;;;;;;;;;;GAaG;GACD,mBAAmB,CAAA;AAEvB,MAAM,WAAW,cAAc;IAC7B;;;;;;;;;OASG;IACH,IAAI,EAAE,cAAc,CAAA;IACpB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,gBAAgB,CAAA;IAC7B,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAA;IAC5B,UAAU,CAAC,EAAE,UAAU,EAAE,CAAA;IACzB;;;;OAIG;IACH,MAAM,EAAE,OAAO,CAAA;IACf;;;;;;;;;;;;;OAaG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,WAAW,EAAE,aAAa,CAAA;IAC1B;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,aAAa,CAAA;CAChC;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,WAAW,CAAA;IACpB,GAAG,EAAE,MAAM,CAAA;IACX,gFAAgF;IAChF,QAAQ,EAAE,OAAO,CAAA;IACjB;;;;;;;;;;OAUG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAC9B;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAA;IACpB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@texaryn/core",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Framework-neutral UI IR, compiler, runtime, and renderer registry for schema-driven forms",
   "keywords": [
     "json-schema",