@adobe/helix-md2jcr 1.3.0 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/helix-md2jcr",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Helix Service that converts markdown to JCR content structure",
   "main": "src/index.js",
   "type": "module",

package/src/mdast2jcr/domain/GroupOptions.js

@@ -0,0 +1,112 @@
+/*
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+import { isGroupField } from './Models.js';
+
+/**
+ * @typedef {import('../index.d.ts').ModelDef} Model
+ */
+
+/**
+ * Recursively collect every option `value` from a field's options tree
+ * (options may be nested under `children`).
+ * @param {Array<object>} options - The field's options array.
+ * @return {Array<string>} The flat list of option values.
+ */
+function collectOptionValues(options) {
+  return (options || []).flatMap((option) => {
+    if (option.children) {
+      return collectOptionValues(option.children);
+    }
+    return option.value !== undefined ? [option.value] : [];
+  });
+}
+
+/**
+ * Distribute element-grouping tokens (a block header's classes, a container
+ * child's leading cell, or a section's `style` cell) across the model's group
+ * fields, per the AEM "element grouping for block options" rules:
+ *
+ * - a boolean field receives "true" when its name suffix (after `${group}_`)
+ *   appears as a token (e.g. token "fullwidth" -> `${group}_fullwidth`="true");
+ * - a text/select field with options claims the tokens that match its option
+ *   values (e.g. token "light" -> `${group}_background`="light");
+ * - any remaining tokens fall back to the base `${group}` field, which also
+ *   covers the common single-field case (a free-form `${group}` field).
+ *
+ * Multi fields are written as `[a, b]`; single fields as a comma-separated list.
+ * The result is emitted in model-field order so callers that do not sort
+ * (e.g. sections) get deterministic, readable output.
+ * @param {Model} model - The block, item, or section model.
+ * @param {Array<string>} tokens - The option tokens.
+ * @param {string} [group] - The group name (defaults to `classes`).
+ * @return {Object<string, string>} A map of group field name to property value.
+ */
+function distributeGroupOptions(model, tokens, group = 'classes') {
+  const groupFields = (model?.fields || []).filter((f) => isGroupField(f.name, group));
+  if (groupFields.length === 0 || tokens.length === 0) {
+    return {};
+  }
+
+  const suffixRegExp = new RegExp(`^${group}_`);
+  const remaining = [...tokens];
+  const assigned = new Map();
+
+  // boolean fields: the suffix after `${group}_` becomes the option when present
+  groupFields
+    .filter((field) => field.component === 'boolean')
+    .forEach((field) => {
+      const suffix = field.name.replace(suffixRegExp, '');
+      const idx = remaining.indexOf(suffix);
+      if (idx !== -1) {
+        assigned.set(field.name, true);
+        remaining.splice(idx, 1);
+      }
+    });
+
+  // text/select fields with options: claim the tokens that match their values
+  groupFields
+    .filter((field) => field.component !== 'boolean' && field.options)
+    .forEach((field) => {
+      const values = collectOptionValues(field.options);
+      const matched = remaining.filter((t) => values.includes(t));
+      if (matched.length > 0) {
+        assigned.set(field.name, matched);
+        matched.forEach((m) => remaining.splice(remaining.indexOf(m), 1));
+      }
+    });
+
+  // leftover tokens fall back to the base `${group}` field (and the single-field case)
+  const base = groupFields.find((f) => f.name === group && f.component !== 'boolean');
+  if (remaining.length > 0 && base) {
+    assigned.set(group, [...(assigned.get(group) || []), ...remaining]);
+  }
+
+  // emit in model-field order for deterministic, readable output
+  const result = {};
+  groupFields.forEach((field) => {
+    if (!assigned.has(field.name)) {
+      return;
+    }
+    const value = assigned.get(field.name);
+    if (value === true) {
+      result[field.name] = 'true';
+    } else {
+      result[field.name] = field.multi === true ? `[${value.join(', ')}]` : value.join(', ');
+    }
+  });
+  return result;
+}
+
+export {
+  collectOptionValues,
+  distributeGroupOptions,
+};

package/src/mdast2jcr/domain/Models.js

@@ -41,6 +41,18 @@ function getField(model, fieldName) {
   return model ? model.fields.find((field) => field.name === fieldName) : undefined;
 }
 
+/**
+ * Returns true if the field name belongs to an element-grouping group — either
+ * the base field named exactly `group`, or a grouped option field `group_<name>`
+ * (element grouping for block options / section styles).
+ * @param {string} name The field name.
+ * @param {string} group The group name (e.g. `classes` or `style`).
+ * @return {boolean}
+ */
+function isGroupField(name, group) {
+  return name === group || name.startsWith(`${group}_`);
+}
+
 /**
  * Returns true if the field name belongs to the `classes` block-options group —
  * either the base `classes` field or a grouped `classes_*` option field
@@ -49,12 +61,14 @@ function getField(model, fieldName) {
  * @return {boolean}
  */
 function isClassesField(name) {
-  return name === 'classes' || name.startsWith('classes_');
+  return isGroupField(name, 'classes');
 }
 
 /**
- * Return a list of field names in the model, excluding the `classes` group
- * (those fields are block options, not content).
+ * Return a list of field names in the model. Block-option / section-style group
+ * fields (`classes`, `classes_*`, `style`, `style_*`) are included so the
+ * Universal Editor can render their controls; only `tab` fields (a UE layout
+ * construct, not a content field) are excluded.
  * @param {Model} model The model.
  * @return {Array<string>} An array of field names.
  */
@@ -63,7 +77,6 @@ function getModelFieldNames(model) {
     ? model.fields
       .filter((f) => f.component !== 'tab')
       .map((f) => f.name)
-      .filter((f) => !isClassesField(f))
     : [];
 }
 
@@ -72,4 +85,5 @@ export {
   findModelById,
   getModelFieldNames,
   isClassesField,
+  isGroupField,
 };

package/src/mdast2jcr/hb/helpers/section-helper.js

@@ -18,6 +18,7 @@ import {
   getField,
   getModelFieldNames,
 } from '../../domain/Models.js';
+import { distributeGroupOptions } from '../../domain/GroupOptions.js';
 
 /**
  * Normalizes strings by converting to lowercase and replacing spaces with hyphens
@@ -61,6 +62,12 @@ function processMetadataRows(rows, model) {
   // always push the model fields so UE can use them, even if no attributes are found
   const modelFields = getModelFieldNames(model);
 
+  // a section uses element grouping when it declares a `style_*` field; in that
+  // case the single well-known `style` cell collapses the whole style group and
+  // must be distributed back across style / style_* fields. A model with only a
+  // base `style` field keeps the simple per-row mapping below.
+  const hasStyleGroup = (model?.fields || []).some((f) => f.name.startsWith('style_'));
+
   for (const row of rows) {
     const cells = findAll(row, (n) => n.type === 'gtCell', true);
     if (cells.length < 2) {
@@ -77,6 +84,22 @@ function processMetadataRows(rows, model) {
       continue;
     }
 
+    // element grouping for section styles: route the flat `style` cell across
+    // the model's style group fields (boolean by name suffix, select/multiselect
+    // by declared options, leftovers to the base `style` field)
+    if (hasStyleGroup && key === 'style') {
+      Object.assign(
+        attributes,
+        distributeGroupOptions(
+          model,
+          value.split(',').map((s) => s.trim()).filter(Boolean),
+          'style',
+        ),
+      );
+      // eslint-disable-next-line no-continue
+      continue;
+    }
+
     const field = getField(model, key);
     if (!field) {
       // eslint-disable-next-line no-continue

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

@@ -16,11 +16,13 @@ import { toString } from 'mdast-util-to-string';
 import Handlebars from 'handlebars';
 import { toHast } from 'mdast-util-to-hast';
 import { toHtml } from 'hast-util-to-html';
+import { customHastHandlers } from './supports/hast-handlers.js';
 import { getComponentById, getComponentByTitle, getModelId } from '../../domain/Definitions.js';
 import {
   findModelById,
   getModelFieldNames, isClassesField,
 } from '../../domain/Models.js';
+import { distributeGroupOptions } from '../../domain/GroupOptions.js';
 import { findAll } from '../../utils/mdast.js';
 import link from './supports/link.js';
 import {
@@ -38,91 +40,6 @@ import ModelHelper from '../../domain/ModelHelper.js';
  * @typedef {import('../../index.d.ts').Filter} Filters
  */
 
-// -- Block Options (classes) --------------------------------------------------
-
-/**
- * Recursively collect every option `value` from a field's options tree
- * (options may be nested under `children`).
- * @param {Array<object>} options - The field's options array.
- * @return {Array<string>} The flat list of option values.
- */
-function collectOptionValues(options) {
-  return (options || []).flatMap((option) => {
-    if (option.children) {
-      return collectOptionValues(option.children);
-    }
-    return option.value !== undefined ? [option.value] : [];
-  });
-}
-
-/**
- * Distribute block-option tokens (the classes from a block header, or the
- * leading cell of a child item) across the model's `classes` group fields, per
- * the AEM "element grouping for block options" rules:
- *
- * - a boolean field receives "true" when its name suffix (after `classes_`)
- *   appears as a token (e.g. token "fullwidth" -> classes_fullwidth="true");
- * - a text/select field with options claims the tokens that match its option
- *   values (e.g. token "light" -> classes_background="light");
- * - any remaining tokens fall back to the base `classes` field, which also
- *   covers the common single-field case (a free-form `classes` field).
- *
- * Multi fields are written as `[a, b]`; single fields as a comma-separated list.
- * @param {Model} model - The block or item model.
- * @param {Array<string>} tokens - The option tokens.
- * @return {Object<string, string>} A map of class field name to property value.
- */
-function distributeBlockOptions(model, tokens) {
-  const groupFields = (model?.fields || []).filter((f) => isClassesField(f.name));
-  if (groupFields.length === 0 || tokens.length === 0) {
-    return {};
-  }
-
-  const remaining = [...tokens];
-  const assigned = new Map();
-
-  // boolean fields: the suffix after `classes_` becomes the option when present
-  groupFields
-    .filter((field) => field.component === 'boolean')
-    .forEach((field) => {
-      const suffix = field.name.replace(/^classes_/, '');
-      const idx = remaining.indexOf(suffix);
-      if (idx !== -1) {
-        assigned.set(field.name, true);
-        remaining.splice(idx, 1);
-      }
-    });
-
-  // text/select fields with options: claim the tokens that match their values
-  groupFields
-    .filter((field) => field.component !== 'boolean' && field.options)
-    .forEach((field) => {
-      const values = collectOptionValues(field.options);
-      const matched = remaining.filter((t) => values.includes(t));
-      if (matched.length > 0) {
-        assigned.set(field.name, matched);
-        matched.forEach((m) => remaining.splice(remaining.indexOf(m), 1));
-      }
-    });
-
-  // leftover tokens fall back to the base `classes` field (and the single-field case)
-  const base = groupFields.find((f) => f.name === 'classes' && f.component !== 'boolean');
-  if (remaining.length > 0 && base) {
-    assigned.set('classes', [...(assigned.get('classes') || []), ...remaining]);
-  }
-
-  const result = {};
-  assigned.forEach((value, name) => {
-    if (value === true) {
-      result[name] = 'true';
-    } else {
-      const field = groupFields.find((f) => f.name === name);
-      result[name] = field.multi === true ? `[${value.join(', ')}]` : value.join(', ');
-    }
-  });
-  return result;
-}
-
 // -- Block Header -------------------------------------------------------------
 
 /**
@@ -193,7 +110,7 @@ function extractBlockHeaderProperties(models, definition, mdast) {
   // section metadata may not have a model. Distribute the header's block options
   // across the model's classes group fields (element grouping for block options).
   if (model) {
-    Object.assign(props, distributeBlockOptions(model, blockDetails.classes));
+    Object.assign(props, distributeGroupOptions(model, blockDetails.classes, 'classes'));
   }
 
   return props;
@@ -261,6 +178,7 @@ function extractPropertiesForNode(field, currentNode, properties) {
       value = currentNode.children.reduce((acc, node) => {
         const hast = toHast(node, {
           allowDangerousHtml: true,
+          handlers: customHastHandlers,
         });
 
         let str = toHtml(hast, {
@@ -274,7 +192,7 @@ function extractPropertiesForNode(field, currentNode, properties) {
         return acc + encodeHtml(str);
       }, '');
     } else {
-      value = encodeHtml(toHtml(toHast(currentNode)));
+      value = encodeHtml(toHtml(toHast(currentNode, { handlers: customHastHandlers })));
     }
 
     // if the node is a code block then don't strip out the newlines
@@ -446,7 +364,7 @@ function extractProperties(
       classes.shift();
 
       // distribute the options across the model's classes group fields
-      Object.assign(properties, distributeBlockOptions(model, classes));
+      Object.assign(properties, distributeGroupOptions(model, classes, 'classes'));
     }
   } else {
     // get rid of the header row, no need for that

package/src/mdast2jcr/hb/partials/paragraph.js

@@ -13,10 +13,11 @@ import Handlebars from 'handlebars';
 
 import { toHast } from 'mdast-util-to-hast';
 import { toHtml } from 'hast-util-to-html';
+import { customHastHandlers } from './supports/hast-handlers.js';
 
 function paragraph(context) {
   const html = context.children.map((child) => {
-    const hast = toHast(child);
+    const hast = toHast(child, { handlers: customHastHandlers });
     return toHtml(hast);
   }).join('');
 

package/src/mdast2jcr/hb/partials/supports/hast-handlers.js

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+/**
+ * Creates a hast handler that maps a custom mdast node type to an inline HTML element.
+ * mdast-util-to-hast has no built-in knowledge of superscript/subscript/underline nodes
+ * (introduced by mdast-sanitize-html), so without these handlers those nodes fall back
+ * to <div>, losing the semantic tag.
+ *
+ * @param {string} tagName - HTML tag to emit (e.g. 'sup', 'sub', 'u')
+ * @returns {function(State, Node): Element} hast handler
+ */
+function formatHandler(tagName) {
+  return (state, node) => ({
+    type: 'element',
+    tagName,
+    properties: {},
+    children: state.all(node),
+  });
+}
+
+/**
+ * Custom hast handlers for mdast node types that mdast-util-to-hast does not recognize
+ * by default. Pass these as the `handlers` option wherever toHast() is called so that
+ * inline formatting round-trips correctly through the mdast → hast → HTML pipeline.
+ */
+export const customHastHandlers = {
+  superscript: formatHandler('sup'),
+  subscript: formatHandler('sub'),
+  underline: formatHandler('u'),
+};