@adobe/helix-md2jcr 1.2.19 → 1.2.21

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [1.2.21](https://github.com/adobe/helix-md2jcr/compare/v1.2.20...v1.2.21) (2026-06-08)
+
+
+### Bug Fixes
+
+* **container-blocks:** correctly detect omitted parent rows ([#212](https://github.com/adobe/helix-md2jcr/issues/212)) ([cf89ba4](https://github.com/adobe/helix-md2jcr/commit/cf89ba4f040b990db2bb40a9d1b374087d63668e))
+
+## [1.2.20](https://github.com/adobe/helix-md2jcr/compare/v1.2.19...v1.2.20) (2026-06-03)
+
+
+### Bug Fixes
+
+* **deps:** update adobe fixes ([#205](https://github.com/adobe/helix-md2jcr/issues/205)) ([bd667b0](https://github.com/adobe/helix-md2jcr/commit/bd667b0b5315d49e7e2f4838491c07d72a4f56dd))
+
 ## [1.2.19](https://github.com/adobe/helix-md2jcr/compare/v1.2.18...v1.2.19) (2026-03-31)
 
 

package/README.md

@@ -99,6 +99,16 @@ const xml = await md2jcr(markdown, options);
 console.log(xml);
 ```
 
+## Documentation
+
+- [Container Blocks](docs/container-blocks.md) — how container blocks map parent
+  properties and child items (the one-column / many-column rules, omitting parent
+  rows, and error cases). See also the
+  [container-block test fixtures](test/fixtures/blocks/core/container-block/README.md)
+  for a worked scenario-by-scenario breakdown.
+- [Field Hinting](docs/field-hinting.md) — using `<!-- field: name -->` to skip
+  ahead within a field group.
+
 ## Baseline XML Files
 Running the ./baseline-tests.sh script will detect any md file under test/fixtures and execute the convert2jcr node script.  
 The script will generate new xml files beside the md files it locates. This is helpful when making changes to the converter

package/baseline-tests.sh

@@ -90,8 +90,17 @@ if [ -n "$SPECIFIC_FILE" ]; then
   exit 0
 fi
 
-# Find all .md files recursively in the directory
-MD_FILES=$(find "$MD_DIR" -type f -name "*.md")
+# Find all .md files recursively in the directory.
+# Exclusions:
+#   - fixtures/bin: its .xml is a throwaway artifact generated and cleaned up by
+#     bin.test.js, so it has no committed baseline to diff against.
+#   - error-handling: these fixtures intentionally fail conversion, so running
+#     them through md2jcr is expected to error.
+#   - README.md: documentation, not a fixture.
+MD_FILES=$(find "$MD_DIR" -type f -name "*.md" \
+  -not -name "README.md" \
+  -not -path "*/fixtures/bin/*" \
+  -not -path "*/fixtures/blocks/error-handling/*")
 
 # Check if no .md files are found
 if [ -z "$MD_FILES" ]; then

package/docs/container-blocks.md

@@ -0,0 +1,154 @@
+# Container Blocks
+
+Container blocks are grid-table blocks that can create a parent block node and
+one or more child block item nodes. They are driven by three Universal Editor
+configuration files:
+
+- The parent component definition points to a parent model and a filter.
+- The filter lists the child component ids allowed inside the parent block.
+- Each child component definition points to the model used for that item row.
+
+## Table Shape
+
+The first row is always the block header. It names the parent block and can also
+include block classes:
+
+```markdown
++------------------------------------------------+
+| Vehicles (featured)                            |
++================================================+
+```
+
+Rows after the header can be parent property rows or child item rows.
+
+Parent property rows are single-cell rows. They map to the parent model fields
+in model order:
+
+```markdown
+| Planes, Trains, and Automobiles                |
+```
+
+Child item rows are normally multi-cell rows. The first cell can name the child
+component id, followed by optional classes separated with commas:
+
+```markdown
+| planewithclass, fast, wide | Field 1 | Field 2 | Field 3 |
+```
+
+When the child component id is present, md2jcr skips that first cell while
+mapping child model fields. In the example above, `fast` and `wide` are written
+to the child item's `classes` field when that field exists.
+
+## Omitting Parent Rows
+
+Container blocks can omit parent property rows entirely. When the first body row
+has more than one cell, md2jcr treats all body rows as child item rows:
+
+```markdown
++--------------------------------------------------------+
+| VehiclesWithClass (classy, vroom)                      |
++==========================+=========+=========+=========+
+| planewithclass, x, a     | Field 1 | Field 2 | Field 3 |
++--------------------------+---------+---------+---------+
+| trainwithclass, large    | Field 1 | Field 2 | Field 3 |
++--------------------------------------------------------+
+```
+
+The parent block still gets its default model, filter, name, and any classes
+from the header. No parent model properties are extracted from body rows.
+
+## Default Child Component
+
+If a child row does not start with an allowed child component id, md2jcr uses
+the first component listed in the parent filter. This allows simple child rows:
+
+```markdown
+| Field 1 | Field 2 | Field 3 |
+```
+
+That row maps to the first allowed child component as long as the cells match
+that child model's field groups.
+
+## One Column vs. Many Columns
+
+The simple rule that decides everything:
+
+- **one column = parent info** (a parent property row)
+- **two or more columns = a child item**
+
+```markdown
++----------------------------+
+| Cards                      |   <- the block name
++==============+=============+
+| My heading   |             |   <- ONE column  = parent info
++--------------+-------------+
+| card title 1 | card body 1 |   <- TWO columns = a child card
++--------------+-------------+
+| card title 2 | card body 2 |   <- TWO columns = a child card
++--------------+-------------+
+```
+
+A one-column row is always parent info. md2jcr does not try to guess whether you
+"meant" it to be a child — if you want a child item, give it more than one
+column.
+
+### A container can have parent info and no children
+
+This is allowed. A Cards block can carry block-level properties without any card
+items yet:
+
+```markdown
++----------------+
+| Cards          |
++================+
+| My heading     |   <- parent info, and zero cards. This is fine.
++----------------+
+```
+
+## Child Component Id Without Properties
+
+There is one one-column row that is **not** allowed: a single cell that contains
+only a child component id and nothing else.
+
+```markdown
++----------------+
+| Cards          |
++================+
+| card           |   <- one column, and the word is a child component id
++----------------+
+```
+
+A child item always needs more than one column (its component id followed by its
+property cells), so a lone component id is a half-finished child row — the author
+named the child but gave it no content. md2jcr stops with an error rather than
+quietly storing the component name as a parent property:
+
+```text
+Container block row in "Container": first body row has one cell ("card") which matches the child component "card" but has no property cells. Add the child item's properties as additional cells, or remove the component id if this is parent block data.
+```
+
+To fix it, add the child's property cells:
+
+```markdown
++----------------+-------------+
+| Cards          |             |
++================+=============+
+| card           | card body   |
++----------------+-------------+
+```
+
+Or, if the lone value really is parent info, change it so it no longer matches a
+child component name.
+
+## Best Practices
+
+- Use one column for parent info and two or more columns for child items.
+- Start child rows with the child component id whenever more than one child
+  component is allowed.
+- Never write a child component id on its own line without its property cells.
+
+## Examples
+
+For a worked, scenario-by-scenario breakdown of these rules — including omitted
+parent rows, empty parent properties, field hints, and the error case — see the
+[container-block test fixtures](../test/fixtures/blocks/core/container-block/README.md).

package/docs/field-hinting.md

@@ -4,17 +4,36 @@ This document provides guidance on modeling content in the Helix MD2JCR system,
 
 ## Field Hinting
 
-Field hinting is a powerful feature in the Helix MD2JCR system that allows you to explicitly specify which field in a component model should receive specific content from your markdown. This is particularly useful when the automatic field resolution doesn't match your intended content structure or when you need precise control over field mapping.
+Field hinting lets you skip ahead to a specific field **within a field group**
+when the automatic field resolution would otherwise assign content to an earlier
+field in that group. It is a tool for navigating *grouped* (collapsed) fields —
+the related fields a model collapses together, such as `teaserText_title`,
+`teaserText_subtitle`, and `teaserText_description`.
 
 ### Purpose of Field Hinting
 
-Field hinting serves several important purposes:
+The feature exists to skip over grouped fields you don't want to fill:
 
-1. **Precise Field Mapping**: When content doesn't naturally flow into the expected fields based on the model's field order, field hints allow you to explicitly direct content to specific fields.
+1. **Skip ahead within a field group**: When a group contains several related
+   fields and you only want to populate a later one, a hint jumps directly to it
+   and leaves the skipped fields unset.
 
-2. **Content Structure Control**: In complex components with multiple fields of the same type (e.g., multiple text fields), field hints ensure content goes to the correct field.
+2. **Precise mapping among similar grouped fields**: When a group has multiple
+   fields of the same type (e.g. several text fields), a hint ensures the content
+   lands on the intended one instead of the next one in sequence.
 
-3. **Sequential Field Mapping**: Field hints allow you to skip ahead to a specific field in the model's field sequence, but content must still be processed in the order it appears in the markdown.
+### Scope and Direction
+
+Two constraints follow from how this works, and they define what the feature is
+*not* for:
+
+- **Within a single field group only.** A hint splices the current group's
+  remaining fields. It cannot reach across separate, ungrouped top-level fields
+  (fields that do not share a group prefix) — those are resolved positionally,
+  not by hint.
+- **Forward only.** You can skip *ahead* to a later field in the group. A hint
+  that names a field already consumed is ignored, and the content flows into the
+  next available field. There is no way to hint backward.
 
 ### How Field Hinting Works
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/helix-md2jcr",
-  "version": "1.2.19",
+  "version": "1.2.21",
   "description": "Helix Service that converts markdown to JCR content structure",
   "main": "src/index.js",
   "type": "module",
@@ -31,10 +31,10 @@
   },
   "homepage": "https://github.com/adobe/helix-md2jcr#readme",
   "dependencies": {
-    "@adobe/fetch": "4.2.3",
+    "@adobe/fetch": "4.3.0",
     "@adobe/helix-markdown-support": "7.1.18",
-    "@adobe/helix-shared-process-queue": "3.1.7",
-    "@adobe/remark-gridtables": "3.0.19",
+    "@adobe/helix-shared-process-queue": "3.1.9",
+    "@adobe/remark-gridtables": "3.0.20",
     "entities": "^6.0.0",
     "github-slugger": "2.0.0",
     "handlebars": "^4.7.8",
@@ -57,7 +57,7 @@
     "xml-formatter": "^3.6.3"
   },
   "devDependencies": {
-    "@adobe/eslint-config-helix": "3.0.23",
+    "@adobe/eslint-config-helix": "3.0.28",
     "@adobe/helix-mediahandler": "2.11.0",
     "@commitlint/cli": "^19.6.1",
     "@commitlint/config-conventional": "^19.6.0",
@@ -66,20 +66,20 @@
     "@semantic-release/git": "10.0.1",
     "c8": "10.1.3",
     "chai": "^6.0.0",
-    "dotenv": "17.3.1",
+    "dotenv": "17.4.2",
     "eslint": "^9.0.0",
     "eslint-import-resolver-exports": "1.0.0-beta.5",
     "eslint-plugin-header": "3.1.1",
     "eslint-plugin-import": "2.32.0",
     "husky": "^9.1.7",
-    "junit-report-builder": "5.1.1",
+    "junit-report-builder": "5.1.2",
     "lint-staged": "16.4.0",
     "mocha": "11.7.5",
     "mocha-multi-reporters": "1.5.1",
     "nock": "13.5.6",
     "semantic-release": "25.0.3",
     "unist-util-inspect": "8.1.0",
-    "yauzl": "3.2.1"
+    "yauzl": "3.3.0"
   },
   "lint-staged": {
     "*.js": "eslint"

package/src/mdast2jcr/hast-table-handler.js

@@ -68,7 +68,9 @@ function toRows(children) {
 
       nodes.push(node);
     } else {
-      if (!queue) queue = [];
+      if (!queue) {
+        queue = [];
+      }
       queue.push(node);
     }
   });

package/src/mdast2jcr/hb/partials/grid-table.js

@@ -38,6 +38,8 @@ import ModelHelper from '../../domain/ModelHelper.js';
  * @typedef {import('../../index.d.ts').Filter} Filters
  */
 
+// -- Block Header -------------------------------------------------------------
+
 /**
  * Locate the name of the Block and any classes that are associated with it.
  * Return null if the block name can not be found in the models.
@@ -80,6 +82,44 @@ function getBlockDetails(mdast, definition) {
   return null;
 }
 
+/**
+ * Extract the properties that are belong to the block header.  Properties like
+ * name, model id, and classes.
+ * @param {Array<Model>} models - the models object
+ * @param {Definition} definition - the definitions object
+ * @param {object} mdast - the mdast tree
+ * @return {{
+ *   name: string,
+ *   model: string,
+ *   classes?: string
+ * }}
+ */
+function extractBlockHeaderProperties(models, definition, mdast) {
+  const blockDetails = getBlockDetails(mdast, definition);
+  const props = {};
+
+  props.name = blockDetails.name;
+  if (blockDetails.modelId) {
+    props.model = blockDetails.modelId;
+  }
+
+  const model = findModelById(models, blockDetails.modelId);
+
+  // section metadata may not have a model
+  if (model) {
+    const classesField = getField(model, 'classes');
+
+    if (blockDetails.classes.length > 0 && classesField) {
+      props.classes = (classesField.multi === true)
+        ? `[${blockDetails.classes.join(', ')}]` : blockDetails.classes.join(', ');
+    }
+  }
+
+  return props;
+}
+
+// -- Field Extraction Pipeline ------------------------------------------------
+
 /**
  * Process the field and collapse the field into the properties object.
  * @param id {string} - the id of the field
@@ -187,16 +227,6 @@ function extractPropertiesForNode(field, currentNode, properties) {
   }
 }
 
-function extractKeyValueProperties(row, model, fieldResolver, fieldGroup, properties) {
-  const [, ...nodes] = findAll(row, (node) => node.type === 'gtCell', true);
-
-  for (let i = 0; i < nodes.length; i += 1) {
-    const node = nodes[i];
-    const field = fieldResolver.resolve(node, fieldGroup);
-    extractPropertiesForNode(field, node, properties);
-  }
-}
-
 /**
  * Check if the node is a field name hint.
  * @param {Node} node - the node to check
@@ -264,7 +294,9 @@ function processCell(cell, fieldGroup, fieldResolver, properties) {
 
         while (searching) {
           const n = cellChildren.shift();
-          if (!n) break;
+          if (!n) {
+            break;
+          }
 
           // richtexts are greedy:
           // they will consume all the children until they hit an image or a named field
@@ -286,6 +318,16 @@ function processCell(cell, fieldGroup, fieldResolver, properties) {
   }
 }
 
+function extractKeyValueProperties(row, model, fieldResolver, fieldGroup, properties) {
+  const [, ...nodes] = findAll(row, (node) => node.type === 'gtCell', true);
+
+  for (let i = 0; i < nodes.length; i += 1) {
+    const node = nodes[i];
+    const field = fieldResolver.resolve(node, fieldGroup);
+    extractPropertiesForNode(field, node, properties);
+  }
+}
+
 /**
  * Extract the properties for the block item.
  * @param {*} mdast - The mdast tree.
@@ -373,40 +415,29 @@ function extractProperties(
   }
 }
 
-/**
- * Extract the properties that are belong to the block header.  Properties like
- * name, model id, and classes.
- * @param {Array<Model>} models - the models object
- * @param {Definition} definition - the definitions object
- * @param {object} mdast - the mdast tree
- * @return {{
- *   name: string,
- *   model: string,
- *   classes?: string
- * }}
- */
-function extractBlockHeaderProperties(models, definition, mdast) {
-  const blockDetails = getBlockDetails(mdast, definition);
-  const props = {};
+// -- Container Block / Child Items --------------------------------------------
 
-  props.name = blockDetails.name;
-  if (blockDetails.modelId) {
-    props.model = blockDetails.modelId;
-  }
-
-  const model = findModelById(models, blockDetails.modelId);
-
-  // section metadata may not have a model
-  if (model) {
-    const classesField = getField(model, 'classes');
-
-    if (blockDetails.classes.length > 0 && classesField) {
-      props.classes = (classesField.multi === true)
-        ? `[${blockDetails.classes.join(', ')}]` : blockDetails.classes.join(', ');
-    }
-  }
+function getComponentId(cell) {
+  return stripNewlines(toString(cell)).split(',').shift().trim();
+}
 
-  return props;
+/**
+ * Builds the error thrown when a single-cell body row contains only a child
+ * component id with no property cells. A valid child item row is multi-column
+ * (the component id followed by its property cells), so a lone component id is a
+ * malformed child row and conversion cannot continue.
+ * @param {{name: string}} blockHeaderProperties - The parsed block header.
+ * @param {string} componentId - The child component id found in the cell.
+ * @return {Error}
+ */
+function childItemMissingPropertiesError(blockHeaderProperties, componentId) {
+  const message = [
+    `Container block row in "${blockHeaderProperties.name}": first body row has one cell ("${componentId}")`,
+    `which matches the child component "${componentId}" but has no property cells.`,
+    'Add the child item\'s properties as additional cells, or remove the component id'
+    + ' if this is parent block data.',
+  ].join(' ');
+  return new Error(message);
 }
 
 function getBlockItems(mdast, modelHelper, definitions, allowedComponents) {
@@ -453,6 +484,8 @@ function getBlockItems(mdast, modelHelper, definitions, allowedComponents) {
   return items;
 }
 
+// -- Entry Point --------------------------------------------------------------
+
 /**
  * The gridTablePartial function is a Handlebars partial that generates a block element.
  * @param {{models: Array<Model>,
@@ -529,12 +562,38 @@ function gridTablePartial(context) {
   // child component will, which will be handled in the Component Block Processing
   // section
   try {
+    const allowedComponents = modelHelper.getAllowedComponents(component);
+
+    // Pre-compute fieldGroup so it can be used for both detection and processing.
     if (model) {
       fieldGroup = modelHelper.getModelFieldGroup(model.id);
+    }
+
+    // Per the container-block spec, parent property rows are always single-column
+    // and child item rows are always multi-column. If the first body row has more
+    // than one cell, the author omitted parent rows entirely.
+    let hasParentRows = true;
+    if (fieldGroup && allowedComponents.length > 0) {
+      const allRows = findAll(mdast, (node) => node.type === 'gtRow', false);
+      const firstBodyRow = allRows[1]; // allRows[0] is the header gtRow
+      if (firstBodyRow) {
+        const firstCells = findAll(firstBodyRow, (n) => n.type === 'gtCell', false);
+        hasParentRows = firstCells.length === 1 && fieldGroup.fields.length > 0;
+        if (hasParentRows) {
+          const componentId = getComponentId(firstCells[0]);
+          if (allowedComponents.includes(componentId)) {
+            // a lone component id with no property cells is a malformed child row
+            throw childItemMissingPropertiesError(blockHeaderProperties, componentId);
+          }
+        }
+      }
+    }
+
+    if (model && hasParentRows) {
       extractProperties(mdast, model, mode, component, fieldGroup.fields, properties);
     } else {
-      // because we have no model we expect the block to have a filter with a component that does
-      // so that means we can remove the header row from the mdast tree
+      // no model, or model present but parent rows omitted - remove the header
+      // so getBlockItems only sees child item rows
       remove(mdast, (n) => is(n, { type: 'gtHeader' }));
     }
 
@@ -549,14 +608,13 @@ function gridTablePartial(context) {
     // 1. In this section attempt to locate the associated model for the block.
     // 2. Trim the mdast nodes to only be relevant for the child block.
     // 3. Then getBlockitems will process the mdast nodes and return the block items.
-    const allowedComponents = modelHelper.getAllowedComponents(component);
 
     // collect all rows
     const blockRows = findAll(mdast, (node) => node.type === 'gtRow', true);
     // the fieldGroup (parent model) determines the expected number of rows in the table
     // so we can remove the rows that belong to the parent and leave only the
     // relevant rows for the child
-    if (model) {
+    if (model && hasParentRows) {
       const removed = blockRows.splice(0, fieldGroup.fields.length + 1);
       // remove the elements from the mdast tree that match the items in the removed array
       removed.forEach((r) => {