@adobe/helix-md2jcr 1.1.33 → 1.1.35

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [1.1.35](https://github.com/adobe/helix-md2jcr/compare/v1.1.34...v1.1.35) (2025-09-23)
+
+
+### Bug Fixes
+
+* support html comments generated with createComment api ([#153](https://github.com/adobe/helix-md2jcr/issues/153)) ([dc8d06e](https://github.com/adobe/helix-md2jcr/commit/dc8d06e62643c738db639cc3276bd77f040d9ae7))
+
+## [1.1.34](https://github.com/adobe/helix-md2jcr/compare/v1.1.33...v1.1.34) (2025-09-16)
+
+
+### Bug Fixes
+
+* **deps:** update adobe fixes ([#152](https://github.com/adobe/helix-md2jcr/issues/152)) ([cd12f99](https://github.com/adobe/helix-md2jcr/commit/cd12f99ec08e953a02769a5737cd2ab8081f8cc7))
+
 ## [1.1.33](https://github.com/adobe/helix-md2jcr/compare/v1.1.32...v1.1.33) (2025-09-03)
 
 

package/docs/field-hinting.md

@@ -0,0 +1,190 @@
+# Modeling Guide
+
+This document provides guidance on modeling content in the Helix MD2JCR system, with a focus on field hinting and its applications.
+
+## 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.
+
+### Purpose of Field Hinting
+
+Field hinting serves several important purposes:
+
+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.
+
+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.
+
+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.
+
+### How Field Hinting Works
+
+Field hints are implemented as HTML comments in your markdown content with the following syntax:
+
+```html
+<!-- field: fieldName -->
+```
+
+The system recognizes these comments and uses them to direct the following content to the specified field. The field hint affects the next content node that would normally be processed.
+
+
+## Examples
+
+### Basic Blocks
+
+Basic blocks typically have a simple field structure where each row corresponds to a single model field. Field hints are generally not useful for basic blocks since the automatic field resolution works well with this straightforward one-to-one mapping.
+
+#### Example: Custom Block
+
+Consider a custom block with the following model:
+
+```json
+{
+  "id": "custom",
+  "fields": [
+    {
+      "component": "text",
+      "name": "classes"
+    },
+    {
+      "component": "richtext",
+      "name": "p_1"
+    },
+    {
+      "component": "reference", 
+      "name": "p_2"
+    },
+    {
+      "component": "text",
+      "name": "p_2Alt"
+    },
+    {
+      "component": "text",
+      "name": "p_3"
+    }
+  ]
+}
+```
+
+**Without field hints** (automatic resolution):
+```markdown
++-------------------------------------------------------+
+| Custom (greedy)                                       |
++=======================================================+
+| All text up to image is included:                     |        
+| ```                                                   |
+| console.log("hello")                                  |
+| ```                                                   |
+| <a href="www.google.com">Google</a>                   |
+|                                                       |
+| ![Image][image0]                                      |
+|                                                       |
+| After image there's more text                         |
++-------------------------------------------------------+
+```
+
+**With field hints** (explicit control skipping optional fields):
+```markdown
++-------------------------------------------------------+
+| Custom (greedy)                                       |
++=======================================================+
+| <!-- field: p_3 -->                                   |
+| After image there's more text                         |
++-------------------------------------------------------+
+```
+
+### Container Blocks
+
+Container blocks are more complex and often benefit significantly from field hinting, especially when they have multiple fields of similar types.
+
+#### Example: Teaser Component
+
+Consider a teaser component with the following model:
+
+```json
+{
+  "id": "teaser",
+  "fields": [
+    {
+      "component": "reference",
+      "name": "image",
+      "label": "Image"
+    },
+    {
+      "component": "text",
+      "name": "teaserText_subtitle",
+      "label": "Sub title"
+    },
+    {
+      "component": "text",
+      "name": "teaserText_title",
+      "label": "Title"
+    },
+    {
+      "component": "text",
+      "name": "teaserText_titleType",
+      "label": "Heading Type"
+    },
+    {
+      "component": "richtext",
+      "name": "teaserText_description",
+      "label": "Description"
+    },
+    {
+      "component": "text",
+      "name": "teaserText_cta",
+      "label": "CTA"
+    },
+    {
+      "component": "text",
+      "name": "teaserText_ctaText",
+      "label": "CTA Text"
+    }
+  ]
+}
+```
+
+**Without field hints** (automatic resolution):
+```markdown
++-------------------------------------------------+
+| Teaser                                          |
++=================================================+
+| ![A group of people sitting on a stage][image0] |
++-------------------------------------------------+
+| Adobe Experience Cloud                          |
+| ## Welcome to AEM                               |
+| Join us in this ask me everything session ...   |
++-------------------------------------------------+
+```
+
+**With field hints** (explicit control):
+```markdown
++-------------------------------------------------+
+| Teaser                                          |
++=================================================+
+| ![A group of people sitting on a stage][image0] |
++-------------------------------------------------+
+| <!-- field:teaserText_title -->                 |
+| ## Welcome to AEM                               |
+| Join us in this ask me everything session ...   |
+| <!-- field:teaserText_cta -->                   |
+| **[Adobe](www.adobe.com)**                      |
++-------------------------------------------------+
+```
+
+### Best Practices
+
+1. **Use field hints sparingly**: Only use field hints when automatic resolution doesn't work as expected or when you need precise control.
+
+2. **Be explicit with field names**: Use the exact field names as defined in your model to avoid mapping errors.
+
+3. **Consider content flow**: Must place field hints immediately before the content you want to map to that field.
+
+4. **Test your mappings**: Verify that your field hints correctly map content to the intended fields by checking the generated JCR output.
+
+### Common Use Cases
+
+1. **Multiple text fields**: When a component has multiple text fields and you want to ensure content goes to the correct one.
+
+2. **Rich text with mixed content**: When you have a rich text field that should contain specific content, followed by other field types.
+
+Field hinting provides the flexibility and control needed to create complex, well-structured content while maintaining the simplicity of markdown authoring.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/helix-md2jcr",
-  "version": "1.1.33",
+  "version": "1.1.35",
   "description": "Helix Service that converts markdown to JCR content structure",
   "main": "src/index.js",
   "type": "module",
@@ -28,7 +28,7 @@
   },
   "homepage": "https://github.com/adobe/helix-md2jcr#readme",
   "dependencies": {
-    "@adobe/fetch": "4.2.2",
+    "@adobe/fetch": "4.2.3",
     "@adobe/helix-markdown-support": "7.1.12",
     "@adobe/helix-shared-process-queue": "3.1.3",
     "@adobe/remark-gridtables": "3.0.14",
@@ -54,8 +54,8 @@
     "xml-formatter": "^3.6.3"
   },
   "devDependencies": {
-    "@adobe/eslint-config-helix": "3.0.9",
-    "@adobe/helix-mediahandler": "2.8.2",
+    "@adobe/eslint-config-helix": "3.0.10",
+    "@adobe/helix-mediahandler": "2.9.2",
     "@commitlint/cli": "^19.6.1",
     "@commitlint/config-conventional": "^19.6.0",
     "@semantic-release/changelog": "6.0.3",
@@ -63,7 +63,7 @@
     "@semantic-release/git": "10.0.1",
     "c8": "10.1.3",
     "chai": "^6.0.0",
-    "dotenv": "17.2.1",
+    "dotenv": "17.2.2",
     "eslint": "^9.0.0",
     "eslint-import-resolver-exports": "1.0.0-beta.5",
     "eslint-plugin-header": "3.1.1",

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

@@ -197,8 +197,31 @@ function extractKeyValueProperties(row, model, fieldResolver, fieldGroup, proper
   }
 }
 
+/**
+ * Check if the node is a field name hint.
+ * @param {Node} node - the node to check
+ * @returns {boolean} - true if the node is a field name hint, false otherwise
+ */
 function isFieldNameHint(node) {
-  return node.type === 'html' && node.value?.startsWith('<!-- field:') && node.value?.endsWith(' -->');
+  // get the node value and remove all whitespace from the value to test if it is a field name hint
+  if (node.type === 'html') {
+    const value = node.value.replace(/\s/g, '');
+    return value?.startsWith('<!--field:') && value?.endsWith('-->');
+  }
+  return false;
+}
+
+/**
+ * Get the field name hint value from the node.
+ * @param {Node} node - the node to get the field name hint value from
+ * @returns {string} - the field name hint value or null if the node is not a field name hint
+ */
+function fieldHintValue(node) {
+  if (node.type === 'html') {
+    const value = node.value.replace(/\s/g, '');
+    return value.split('<!--field:')[1].split('-->')[0].trim();
+  }
+  return null;
 }
 
 function processCell(cell, fieldGroup, fieldResolver, properties) {
@@ -223,7 +246,7 @@ function processCell(cell, fieldGroup, fieldResolver, properties) {
 
       // if we see a property name hint, parse it and continue, unset it if not
       if (isFieldNameHint(node)) {
-        nextFieldName = node.value.split('<!-- field:')[1].split(' -->')[0].trim();
+        nextFieldName = fieldHintValue(node);
         // eslint-disable-next-line no-continue
         continue;
       }