ng-form-foundry-transformers 0.3.2 → 0.3.3

package/README.md

@@ -80,9 +80,13 @@ covers **draft 2020-12** (back-compatible with draft-07): `object` → nodeGroup
 a `map` for `additionalProperties`/`patternProperties`), `array` → nodeGroupList /
 leafList, `anyOf`/`oneOf` → choice (or a nullable leaf for `[T, null]`), `$ref` →
 `$defs`/`definitions` resolved inline (local **or cross-file** via
-`options.refDocuments`, matched by `$id`), `const` → a read-only leaf, and the string /
-number constraints (`pattern`, `minLength`, `minimum`, `multipleOf`, `format`, …)
-carried onto the leaves as validators.
+`schemaOptions.refDocuments`, matched by `$id`), `const` → a read-only leaf, and the
+string / number constraints (`pattern`, `minLength`, `minimum`, `multipleOf`,
+`format`, …) carried onto the leaves as validators. Non-`required` properties
+become **`presence` nodes** — absent from the form and the serialized value until
+enabled, so the output validates against the source schema (opt out with
+`schemaOptions: { optionalPresence: false }`); a required property mapping to a
+choice is marked `mandatory`.
 
 ## JSON transformer
 
@@ -187,6 +191,15 @@ npm test        # node:test on the compiled output (no Python needed)
 
 ## Status
 
+`0.3.3` — schema-valid round-trips for JSON-Schema-driven forms. Non-`required`
+properties now map to `presence` nodes (absent until enabled; opt out with
+`schemaOptions: { optionalPresence: false }`), a required property mapping to a
+choice is flagged `mandatory`, and the YAML/JSON transformers gained
+`options.schemaOptions` — which also makes `refDocuments` (cross-file `$ref`)
+reachable through them for the first time. Pairs with the library's
+required-aware choice-case inference, empty list seeding, and
+materialized-validity rules.
+
 `0.3.2` — documentation release alongside the library's `serializeForm`: the
 YAML/JSON `toSource` examples now take the wire value (choice `__case`
 discriminators stripped); no transformer code changes.

package/dist/core/json-schema.d.ts

@@ -47,6 +47,15 @@ export interface JsonSchemaOptions {
      * document then resolve against it.
      */
     refDocuments?: JsonSchema[];
+    /**
+     * Map non-required properties to `presence: true` nodes (default `true`):
+     * absent from the form and the serialized value until the user enables them,
+     * which is what `required` + `additionalProperties: false` schemas demand —
+     * an untouched optional materialized as `null` fails validation against the
+     * very schema the form came from. Set `false` to materialize every property
+     * unconditionally.
+     */
+    optionalPresence?: boolean;
 }
 type JsonSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';
 /**
@@ -58,8 +67,11 @@ type JsonSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'bo
  * `additionalProperties`/`patternProperties`); `anyOf`/`oneOf` → a {@link Choice}
  * (or a nullable leaf for the `[T, null]` shape); `array` → nodeGroupList or
  * leafList; a scalar (with `enum`, `const`, `type: [T, 'null']`, and the string /
- * number constraints) → a typed leaf. `required` marks child leaves, `title`
- * becomes the label, `default`/`const` carry a scalar value.
+ * number constraints) → a typed leaf. `required` marks leaves required and a
+ * choice `mandatory`; a property *not* in `required` becomes a `presence` node
+ * — absent from the form value until enabled — unless
+ * {@link JsonSchemaOptions.optionalPresence} is `false`. `title` becomes the
+ * label, `default`/`const` carry a scalar value.
  */
 export declare function jsonSchemaToNodeGroup(schema: JsonSchema, name?: string, options?: JsonSchemaOptions): NodeGroup;
 export {};

package/dist/core/json-schema.js

@@ -11,17 +11,37 @@ const ROOT = '__root__';
  * `additionalProperties`/`patternProperties`); `anyOf`/`oneOf` → a {@link Choice}
  * (or a nullable leaf for the `[T, null]` shape); `array` → nodeGroupList or
  * leafList; a scalar (with `enum`, `const`, `type: [T, 'null']`, and the string /
- * number constraints) → a typed leaf. `required` marks child leaves, `title`
- * becomes the label, `default`/`const` carry a scalar value.
+ * number constraints) → a typed leaf. `required` marks leaves required and a
+ * choice `mandatory`; a property *not* in `required` becomes a `presence` node
+ * — absent from the form value until enabled — unless
+ * {@link JsonSchemaOptions.optionalPresence} is `false`. `title` becomes the
+ * label, `default`/`const` carry a scalar value.
  */
 function jsonSchemaToNodeGroup(schema, name = ROOT, options) {
     const documents = [schema, ...(options?.refDocuments ?? [])];
     const resolver = new RefResolver(schema, documents);
+    const ctx = { optionalPresence: options?.optionalPresence ?? true };
     const { schema: root, scope } = resolver.resolve(schema);
-    const group = objectToNodeGroup(root, name, scope, root.title);
+    const group = objectToNodeGroup(root, name, scope, ctx, root.title);
     group.root = true;
     return group;
 }
+/**
+ * Apply {@link JsonSchemaOptions.optionalPresence} to one *property* node: a
+ * non-required property becomes a presence node, so it stays absent from the
+ * form value until enabled. Only called at property positions
+ * ({@link objectToNodeGroup} children and {@link branchToCase} fields) — a map's
+ * `value` template, an array's item type, and a leaf-bodied case are not
+ * properties and must never be marked. Lists cannot carry `presence`.
+ */
+function markOptionalProperty(node, required, ctx) {
+    if (!ctx.optionalPresence || required)
+        return node;
+    if (node.kind === 'leaf' || node.kind === 'nodeGroup' || node.kind === 'choice' || node.kind === 'map') {
+        node.presence = true;
+    }
+    return node;
+}
 /**
  * Resolves `$ref` chains, following them across documents. A resolver is bound to
  * one document (for `#/…` local refs); crossing into another document via a
@@ -80,11 +100,12 @@ function resolveFragment(doc, fragment) {
     return node;
 }
 // --- objects / maps -----------------------------------------------------------
-function objectToNodeGroup(schema, name, resolver, label) {
+function objectToNodeGroup(schema, name, resolver, ctx, label) {
     const required = new Set(schema.required ?? []);
     const children = {};
     for (const [key, propSchema] of Object.entries(schema.properties ?? {})) {
-        children[key] = schemaToNode(key, propSchema, required.has(key), resolver);
+        const node = schemaToNode(key, propSchema, required.has(key), resolver, ctx);
+        children[key] = markOptionalProperty(node, required.has(key), ctx);
     }
     const group = { kind: 'nodeGroup', name, children };
     if (label)
@@ -100,7 +121,7 @@ function isOpenMap(schema) {
     const hasPattern = !!schema.patternProperties && Object.keys(schema.patternProperties).length > 0;
     return additionalIsSchema || hasPattern;
 }
-function objectToMap(name, schema, resolver) {
+function objectToMap(name, schema, resolver, ctx) {
     let valueSchema = {};
     let keyPattern;
     const pattern = schema.patternProperties && Object.entries(schema.patternProperties)[0];
@@ -110,7 +131,7 @@ function objectToMap(name, schema, resolver) {
     else if (schema.additionalProperties && typeof schema.additionalProperties === 'object') {
         valueSchema = schema.additionalProperties;
     }
-    const node = { kind: 'map', name, value: schemaToNode('value', valueSchema, false, resolver) };
+    const node = { kind: 'map', name, value: schemaToNode('value', valueSchema, false, resolver, ctx) };
     if (schema.title)
         node.label = schema.title;
     if (keyPattern)
@@ -123,7 +144,7 @@ function objectToMap(name, schema, resolver) {
 }
 // --- anyOf / oneOf → choice ---------------------------------------------------
 /** The `anyOf`/`oneOf` `[T, null]` shape collapses to a nullable leaf; anything else is a choice. */
-function branchesToNode(name, schema, rawBranches, required, resolver) {
+function branchesToNode(name, schema, rawBranches, required, resolver, ctx) {
     const branches = rawBranches.map((b) => resolver.resolve(b));
     const nonNull = branches.filter((b) => b.schema.type !== 'null');
     const sole = nonNull.length === 1 ? nonNull[0] : undefined;
@@ -136,11 +157,13 @@ function branchesToNode(name, schema, rawBranches, required, resolver) {
     const caseLabels = {};
     branches.forEach(({ schema: branch, scope }, index) => {
         const caseName = `case${index}`;
-        cases[caseName] = branchToCase(branch, scope);
+        cases[caseName] = branchToCase(branch, scope, ctx);
         if (branch.title)
             caseLabels[caseName] = branch.title;
     });
     const choice = { kind: 'choice', name, cases };
+    if (required)
+        choice.mandatory = true;
     if (schema.title)
         choice.label = schema.title;
     if (Object.keys(caseLabels).length)
@@ -148,29 +171,30 @@ function branchesToNode(name, schema, rawBranches, required, resolver) {
     return choice;
 }
 /** A resolved branch → a case body: a field record for an object branch, else a single node. */
-function branchToCase(branch, scope) {
+function branchToCase(branch, scope, ctx) {
     if (primaryType(branch) === 'object' && branch.properties) {
         const required = new Set(branch.required ?? []);
         const fields = {};
         for (const [key, propSchema] of Object.entries(branch.properties)) {
-            fields[key] = schemaToNode(key, propSchema, required.has(key), scope);
+            const node = schemaToNode(key, propSchema, required.has(key), scope, ctx);
+            fields[key] = markOptionalProperty(node, required.has(key), ctx);
         }
         return fields;
     }
-    return schemaToNode('value', branch, false, scope);
+    return schemaToNode('value', branch, false, scope, ctx);
 }
 // --- dispatch -----------------------------------------------------------------
-function schemaToNode(name, rawSchema, required, resolver) {
+function schemaToNode(name, rawSchema, required, resolver, ctx) {
     const { schema, scope } = resolver.resolve(rawSchema);
     const branches = schema.anyOf ?? schema.oneOf;
     if (branches && branches.length) {
-        return branchesToNode(name, schema, branches, required, scope);
+        return branchesToNode(name, schema, branches, required, scope, ctx);
     }
     const type = primaryType(schema);
     if (type === 'object' || (type === undefined && (schema.properties || isOpenMap(schema)))) {
         if (isOpenMap(schema))
-            return objectToMap(name, schema, scope);
-        return objectToNodeGroup(schema, name, scope, schema.title);
+            return objectToMap(name, schema, scope, ctx);
+        return objectToNodeGroup(schema, name, scope, ctx, schema.title);
     }
     if (type === 'array') {
         const { schema: items, scope: itemScope } = scope.resolve(schema.items ?? {});
@@ -178,7 +202,7 @@ function schemaToNode(name, rawSchema, required, resolver) {
             const node = {
                 kind: 'nodeGroupList',
                 name,
-                type: objectToNodeGroup(items, name, itemScope, items.title),
+                type: objectToNodeGroup(items, name, itemScope, ctx, items.title),
             };
             if (schema.title)
                 node.label = schema.title;

package/dist/core/schema.d.ts

@@ -86,7 +86,10 @@ export interface Choice {
     /** Display labels for cases, keyed by case name. */
     caseLabels?: Record<string, string>;
     default?: string;
+    /** A case must be selected for the form to be valid (a required property). */
     mandatory?: boolean;
+    /** Optional choice whose presence is itself data (mirrors {@link NodeGroup.presence}). */
+    presence?: boolean;
 }
 /**
  * An open, arbitrary-keyed record: unlike {@link NodeGroup} (a fixed key set), a

package/dist/transformers/json/json-transformer.d.ts

@@ -1,6 +1,6 @@
 import type { FormValue } from '../../core/schema';
 import type { TransformResult } from '../../core/transformer';
-import { type JsonSchema } from '../../core/json-schema';
+import { type JsonSchema, type JsonSchemaOptions } from '../../core/json-schema';
 /** Options for {@link jsonTransformer}'s `toSchema`. */
 export interface JsonOptions {
     /**
@@ -10,6 +10,8 @@ export interface JsonOptions {
     schema?: JsonSchema;
     /** Name for the root node group. Defaults to `__root__`. */
     rootName?: string;
+    /** Options forwarded to `jsonSchemaToNodeGroup` (`refDocuments`, `optionalPresence`). */
+    schemaOptions?: JsonSchemaOptions;
 }
 /** How the source was formatted, so `toSource` re-emits it the same way. */
 export interface JsonFormat {

package/dist/transformers/json/json-transformer.js

@@ -28,7 +28,7 @@ exports.jsonTransformer = {
         const parsed = JSON.parse(source, bigIntReviver);
         const data = collectBigInts(parsed ?? {}, [], bigInts);
         const schema = options?.schema
-            ? (0, json_schema_1.jsonSchemaToNodeGroup)(options.schema, options.rootName)
+            ? (0, json_schema_1.jsonSchemaToNodeGroup)(options.schema, options.rootName, options.schemaOptions)
             : (0, infer_1.inferNodeGroup)(data, options?.rootName);
         const binding = {
             indent: detectIndent(source),

package/dist/transformers/yaml/yaml-transformer.d.ts

@@ -1,7 +1,7 @@
 import { type Document } from 'yaml';
 import type { FormValue } from '../../core/schema';
 import type { TransformResult } from '../../core/transformer';
-import { type JsonSchema } from '../../core/json-schema';
+import { type JsonSchema, type JsonSchemaOptions } from '../../core/json-schema';
 /** Options for {@link yamlTransformer}'s `toSchema`. */
 export interface YamlOptions {
     /**
@@ -12,6 +12,8 @@ export interface YamlOptions {
     schema?: JsonSchema;
     /** Name for the root node group. Defaults to `__root__`. */
     rootName?: string;
+    /** Options forwarded to `jsonSchemaToNodeGroup` (`refDocuments`, `optionalPresence`). */
+    schemaOptions?: JsonSchemaOptions;
 }
 /**
  * A YAML {@link Transformer}: turn a YAML config document into a form and write

package/dist/transformers/yaml/yaml-transformer.js

@@ -27,7 +27,7 @@ exports.yamlTransformer = {
         const doc = (0, yaml_1.parseDocument)(source, { intAsBigInt: true });
         const data = (normalizeBigInts(doc.toJS()) ?? {});
         const schema = options?.schema
-            ? (0, json_schema_1.jsonSchemaToNodeGroup)(options.schema, options.rootName)
+            ? (0, json_schema_1.jsonSchemaToNodeGroup)(options.schema, options.rootName, options.schemaOptions)
             : (0, infer_1.inferNodeGroup)(data, options?.rootName);
         return { schema, binding: doc, initialValue: data };
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ng-form-foundry-transformers",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Framework-agnostic Node + TypeScript catalog of source-format transformers: turn a YANG model (and more) into an ng-form-foundry schema and revert the edited form value back to the source format.",
   "keywords": [
     "ng-form-foundry",