ng-form-foundry-transformers 0.5.5 → 0.6.0

package/README.md

@@ -149,11 +149,16 @@ string / number constraints (`pattern`, `minLength`, `minimum`, `multipleOf`,
 `format`, …) carried onto the leaves as validators, with
 `minProperties`/`maxProperties` becoming present-children bounds on closed
 objects (`minPresent`/`maxPresent`) or entry bounds on open maps.
-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`.
+Non-`required` properties (leaves, groups, choices, maps, **and lists**) become
+**`presence` nodes** — absent from the form and the serialized value until
+enabled, so the output validates against the source schema and a zero-edit
+rebuild never injects a key the source lacked (opt out with `schemaOptions: {
+optionalPresence: false }`); a required property mapping to a choice is marked
+`mandatory`. Pass `schemaOptions: { advisoryRequired: true }` to also treat
+*required* properties as presence nodes — they keep `required: true` for
+validation but stay absent until enabled, so an over-broad `required` list (one
+schema covering several config flavours) does not force-write keys the source
+omitted.
 
 **The schema must agree with the document on container shapes.** A covered
 key whose schema says array where the document holds an object (or scalar
@@ -309,6 +314,13 @@ npm test        # node:test on the compiled output (no Python needed)
 
 ## Status
 
+`0.6.0` — optional **array** properties now map to `presence` nodes (leaf-lists
+and node-group lists included), so a zero-edit rebuild never injects a list the
+source lacked; new `schemaOptions: { advisoryRequired: true }` treats a schema's
+over-broad `required` list as advisory (required keys become presence nodes,
+keeping `required` for validation only). The paired `ng-form-foundry` 0.6.0
+drives a list's add/remove affordance from required-vs-optional.
+
 `0.5.5` — version-alignment release with the workspace (the paired
 `ng-form-foundry` 0.5.5 aligns the standalone form and config editor on list
 cardinality, adds `setNodePresence`, and reflects external form mutations in

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

@@ -56,6 +56,20 @@ export interface JsonSchemaOptions {
      * unconditionally.
      */
     optionalPresence?: boolean;
+    /**
+     * Treat the schema's `required` list as *advisory* rather than structural
+     * (default `false`). A required property then becomes a presence node too, so
+     * presence follows the data: a key present in the initial value materializes,
+     * a key absent stays absent — a round-trip never injects a key the source
+     * lacked, even one the schema marks `required`. `required` still drives
+     * *validation* (a materialized required field must hold a value), it just no
+     * longer forces the key to exist. Use for byte-exact editing of an existing
+     * document against a schema whose `required` list is over-broad (e.g. one
+     * schema covering several config flavors); leave off for new-form authoring,
+     * where a required field should render on a blank form so the user can fill
+     * it.
+     */
+    advisoryRequired?: boolean;
     /**
      * Display metadata injected into the produced schema (`label`,
      * `description`, choice `caseLabels`) — see {@link applyThesaurus}. Fills

package/dist/core/json-schema.js

@@ -23,7 +23,10 @@ const ROOT = '__root__';
 function jsonSchemaToNodeGroup(schema, name = ROOT, options) {
     const documents = [schema, ...(options?.refDocuments ?? [])];
     const resolver = new RefResolver(schema, documents);
-    const ctx = { optionalPresence: options?.optionalPresence ?? true };
+    const ctx = {
+        optionalPresence: options?.optionalPresence ?? true,
+        advisoryRequired: options?.advisoryRequired ?? false,
+    };
     const { schema: root, scope } = resolver.resolve(schema);
     const group = objectToNodeGroup(root, name, scope, ctx, root.title);
     group.root = true;
@@ -32,15 +35,25 @@ function jsonSchemaToNodeGroup(schema, name = ROOT, options) {
 /**
  * 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
+ * form value until enabled — lists included, so an absent optional array is
+ * not injected as an empty one on save. 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`.
+ * properties and must never be marked. Under
+ * {@link JsonSchemaOptions.advisoryRequired}, a `required` property is marked
+ * too (presence then seeds from the data; `required` drives validation only).
  */
 function markOptionalProperty(node, required, ctx) {
-    if (!ctx.optionalPresence || required)
+    if (!ctx.optionalPresence)
         return node;
-    if (node.kind === 'leaf' || node.kind === 'nodeGroup' || node.kind === 'choice' || node.kind === 'map') {
+    if (required && !ctx.advisoryRequired)
+        return node;
+    if (node.kind === 'leaf' ||
+        node.kind === 'nodeGroup' ||
+        node.kind === 'choice' ||
+        node.kind === 'map' ||
+        node.kind === 'leafList' ||
+        node.kind === 'nodeGroupList') {
         node.presence = true;
     }
     return node;

package/dist/core/schema.d.ts

@@ -56,6 +56,11 @@ export interface LeafList {
     maxItems?: number;
     /** Present every item in this base — see {@link Leaf.radix}. */
     radix?: 2 | 8 | 16;
+    /**
+     * Optional list whose presence is itself data — an absent key, distinct from
+     * a present-but-empty list. Mirrors {@link NodeGroup.presence}.
+     */
+    presence?: boolean;
 }
 export interface NodeGroup {
     kind: 'nodeGroup';
@@ -85,6 +90,8 @@ export interface NodeGroupList {
     type: NodeGroup;
     minItems?: number;
     maxItems?: number;
+    /** Optional list whose presence is itself data — see {@link LeafList.presence}. */
+    presence?: boolean;
 }
 /** One case body: a record of named fields, or a single node (a leaf-bodied case). */
 export type ChoiceCase = Record<string, NodeType> | NodeType;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ng-form-foundry-transformers",
-  "version": "0.5.5",
+  "version": "0.6.0",
   "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",