@adobe/helix-md2jcr 1.2.21 → 1.3.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [1.3.0](https://github.com/adobe/helix-md2jcr/compare/v1.2.21...v1.3.0) (2026-06-08)
+
+
+### Features
+
+* **block-options:** support element grouping for block options ([#215](https://github.com/adobe/helix-md2jcr/issues/215)) ([7388c2d](https://github.com/adobe/helix-md2jcr/commit/7388c2dcf95252393c47fc8097235f4612916342)), closes [#214](https://github.com/adobe/helix-md2jcr/issues/214)
+
 ## [1.2.21](https://github.com/adobe/helix-md2jcr/compare/v1.2.20...v1.2.21) (2026-06-08)
 
 

package/README.md

@@ -106,6 +106,9 @@ console.log(xml);
   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.
+- [Block Options (Classes)](docs/block-options.md) — block option classes and
+  element grouping (`classes`, `classes_*`): how header options are routed to
+  fields by their options or boolean name-suffix.
 - [Field Hinting](docs/field-hinting.md) — using `<!-- field: name -->` to skip
   ahead within a field group.
 

package/docs/block-options.md

@@ -0,0 +1,115 @@
+# Block Options (Classes)
+
+Block options let an author pick variants of a block without creating a whole new
+block. They are expressed as CSS classes on the block and appear in the block
+header parentheses in markdown:
+
+```markdown
++--------------------------------------+
+| Teaser (variant-a, light, fullwidth) |
++======================================+
+| My title                             |
++--------------------------------------+
+```
+
+A model exposes block options through its `classes` fields. In the simplest case
+there is a single `classes` field that holds a free-form list of class names.
+
+## Element Grouping for Block Options
+
+When there are several options — especially mutually exclusive ones — it is
+easier for authors to use multiple fields. Following the
+[element grouping](https://www.aem.live/developer/component-model-definitions#element-grouping-for-block-options)
+naming convention, the **classes group** is the base `classes` field plus any
+`classes_<name>` field (the group name `classes` separated from the option name
+by an underscore):
+
+```jsonc
+{ "component": "select",      "name": "classes",            "options": [ "variant-a", "variant-b" ] }
+{ "component": "multiselect", "name": "classes_background", "options": [ "light", "dark" ] }
+{ "component": "boolean",     "name": "classes_fullwidth" }
+```
+
+When AEM renders the block, every field in the group collapses into one flat
+class list — `class="teaser variant-a light fullwidth"` — and that is what lands
+in the block header parentheses.
+
+## How md2jcr maps header options back to fields
+
+Going from markdown to JCR, md2jcr must route each option in the header back to
+the field it came from. Because the rendered class list is **flat** (it does not
+record which field produced each class), routing is driven by the field
+definition — **not by the order of the options**:
+
+- **Boolean field** — matched by its **name suffix** (the part after `classes_`).
+  The token `fullwidth` sets `classes_fullwidth="true"`. If the token is absent,
+  the field is left unset. This suits on/off toggles.
+- **Select / multiselect field** — matched by its **declared option values**. The
+  token `light` is routed to `classes_background` because `light` is one of that
+  field's options. A multiselect claims **all** of its matching tokens.
+- **Base `classes` field** — receives any leftover tokens that no more specific
+  field claimed. This also covers the common case of a single, free-form
+  `classes` field.
+
+Multi fields are written as `[a, b]`; single fields as a comma-separated value.
+
+### Example
+
+Given the model above and the header `Teaser (variant-a, light, fullwidth)`, the
+block node gets these properties:
+
+```text
+classes="variant-a"  classes_background="light"  classes_fullwidth="true"
+```
+
+A multiselect background claims every matching token:
+
+```text
+Teaser (variant-a, light, dark)
+  -> classes="variant-a"  classes_background="[light, dark]"
+```
+
+And an unmatched token falls back to the base `classes` field:
+
+```text
+Promo (highlight, featured, sticky)   // classes is free-form, classes_sticky is boolean
+  -> classes="[highlight, featured]"  classes_sticky="true"
+```
+
+The classes group fields are block options, not content, so they are excluded
+from `modelFields` and never consume content rows.
+
+## Requirements
+
+- Name grouped option fields `classes_<name>`.
+- A `classes_<name>` **select/multiselect must declare `options`** — that is how
+  its tokens are recognized.
+- A `classes_<name>` **boolean** needs no options; its name suffix is the class.
+- A **free-form text** `classes_<name>` field (no options) cannot be
+  reverse-mapped to its field — its token has no matching signal — so it falls
+  back to the base `classes` field. As the spec notes, block options are usually
+  select or multiselect, which avoids this.
+
+## Why options, not position?
+
+Mapping the first option to the first field, the second to the second, and so on
+seems simpler, but it breaks whenever the number of tokens does not equal the
+number of fields — which is common:
+
+- a boolean that is **off** contributes no token,
+- an empty select contributes no token,
+- a multiselect contributes **several** tokens.
+
+Any of these slides every following option into the wrong field. Matching by a
+field's declared options (and a boolean's name suffix) is order-independent and
+survives missing, optional, and multi-value fields.
+
+## Examples in the test suite
+
+Worked fixtures live under
+[`test/fixtures/blocks/core/block-options`](../test/fixtures/blocks/core/block-options):
+
+- `block-options-grouping` — single selects + a boolean that is on
+- `block-options-grouping-multi` — a multiselect claiming several values, boolean off
+- `block-options-grouping-fallback` — free-form base `classes` catch-all + a boolean
+- `block-options-grouping-booleans` — several independent boolean options, mixed on/off

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/helix-md2jcr",
-  "version": "1.2.21",
+  "version": "1.3.0",
   "description": "Helix Service that converts markdown to JCR content structure",
   "main": "src/index.js",
   "type": "module",
@@ -74,12 +74,12 @@
     "husky": "^9.1.7",
     "junit-report-builder": "5.1.2",
     "lint-staged": "16.4.0",
-    "mocha": "11.7.5",
+    "mocha": "11.7.6",
     "mocha-multi-reporters": "1.5.1",
     "nock": "13.5.6",
     "semantic-release": "25.0.3",
     "unist-util-inspect": "8.1.0",
-    "yauzl": "3.3.0"
+    "yauzl": "3.3.1"
   },
   "lint-staged": {
     "*.js": "eslint"

package/src/mdast2jcr/domain/FieldGroup.js

@@ -9,6 +9,8 @@
  * OF ANY KIND, either express or implied. See the License for the specific language
  * governing permissions and limitations under the License.
  */
+import { isClassesField } from './Models.js';
+
 class FieldGroup {
   /**
    * Constructor.
@@ -35,7 +37,7 @@ class FieldGroup {
 
     this.model.fields
       .filter((field) => field.component !== 'tab')
-      .filter((field) => field.name !== 'classes')
+      .filter((field) => !isClassesField(field.name))
       .forEach((field) => {
         if (field.name.includes('_')) {
           const groupName = field.name.split('_')[0];

package/src/mdast2jcr/domain/Models.js

@@ -42,7 +42,19 @@ function getField(model, fieldName) {
 }
 
 /**
- * Return a list of field names in the model, excluding 'classes'.
+ * Returns true if the field name belongs to the `classes` block-options group —
+ * either the base `classes` field or a grouped `classes_*` option field
+ * (element grouping for block options).
+ * @param {string} name The field name.
+ * @return {boolean}
+ */
+function isClassesField(name) {
+  return name === 'classes' || name.startsWith('classes_');
+}
+
+/**
+ * Return a list of field names in the model, excluding the `classes` group
+ * (those fields are block options, not content).
  * @param {Model} model The model.
  * @return {Array<string>} An array of field names.
  */
@@ -51,7 +63,7 @@ function getModelFieldNames(model) {
     ? model.fields
       .filter((f) => f.component !== 'tab')
       .map((f) => f.name)
-      .filter((f) => f !== 'classes')
+      .filter((f) => !isClassesField(f))
     : [];
 }
 
@@ -59,4 +71,5 @@ export {
   getField,
   findModelById,
   getModelFieldNames,
+  isClassesField,
 };

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

@@ -19,7 +19,7 @@ import { toHtml } from 'hast-util-to-html';
 import { getComponentById, getComponentByTitle, getModelId } from '../../domain/Definitions.js';
 import {
   findModelById,
-  getField, getModelFieldNames,
+  getModelFieldNames, isClassesField,
 } from '../../domain/Models.js';
 import { findAll } from '../../utils/mdast.js';
 import link from './supports/link.js';
@@ -38,6 +38,91 @@ 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 -------------------------------------------------------------
 
 /**
@@ -105,14 +190,10 @@ function extractBlockHeaderProperties(models, definition, mdast) {
 
   const model = findModelById(models, blockDetails.modelId);
 
-  // section metadata may not have a model
+  // 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) {
-    const classesField = getField(model, 'classes');
-
-    if (blockDetails.classes.length > 0 && classesField) {
-      props.classes = (classesField.multi === true)
-        ? `[${blockDetails.classes.join(', ')}]` : blockDetails.classes.join(', ');
-    }
+    Object.assign(props, distributeBlockOptions(model, blockDetails.classes));
   }
 
   return props;
@@ -353,14 +434,10 @@ function extractProperties(
 
   // the first cells is the header row, so we skip it
   const rows = findAll(mdast, (node) => node.type === 'gtRow', false);
-  let classesField;
   if (mode === 'blockItem') {
-    classesField = getField(model, 'classes');
-    // if our model defines a classes field then dig out the classes from the first cell
-    if (classesField) {
-      // if we are a block item we need to look at the first cell to see if it has any class
-      // properties by inspecting the text value for any commas
-      // if there is a comma that then becomes the classes property for the block item
+    // if our model defines any classes group field then dig the block options out
+    // of the first cell (the component id followed by optional class names)
+    if ((model.fields || []).some((f) => isClassesField(f.name))) {
       const firstCell = rows[0].children[0];
       const textValue = toString(firstCell);
       const classes = textValue.split(',').map((c) => c.trim());
@@ -368,11 +445,8 @@ function extractProperties(
       // discard the component name leaving only the block option names (class names)
       classes.shift();
 
-      // if we are left with any classes to add to the block item, then add them
-      if (classes.length > 0) {
-        properties.classes = classesField?.multi === true
-          ? `[${classes.join(', ')}]` : classes.join(', ');
-      }
+      // distribute the options across the model's classes group fields
+      Object.assign(properties, distributeBlockOptions(model, classes));
     }
   } else {
     // get rid of the header row, no need for that