@adobe/helix-md2jcr 1.2.21 → 1.4.1

package/CHANGELOG.md

@@ -1,3 +1,24 @@
+## [1.4.1](https://github.com/adobe/helix-md2jcr/compare/v1.4.0...v1.4.1) (2026-06-09)
+
+
+### Bug Fixes
+
+* republish after npm provenance failures ([c078b3f](https://github.com/adobe/helix-md2jcr/commit/c078b3f68de461213347339cc6afd3de1c3cfcd7))
+
+# [1.4.0](https://github.com/adobe/helix-md2jcr/compare/v1.3.0...v1.4.0) (2026-06-09)
+
+
+### Features
+
+* **section-metadata:** element grouping for section style + classes in modelFields ([#216](https://github.com/adobe/helix-md2jcr/issues/216)) ([861bf48](https://github.com/adobe/helix-md2jcr/commit/861bf481d623e74045a81de2a80bbc0af6a31db1)), closes [#215](https://github.com/adobe/helix-md2jcr/issues/215)
+
+# [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,12 @@ 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.
+- [Section Styles](docs/section-styles.md) — element grouping for a section's
+  `style` group (`style`, `style_*`): how the single Section Metadata `style`
+  cell is routed back to fields, mirroring block options.
 - [Field Hinting](docs/field-hinting.md) — using `<!-- field: name -->` to skip
   ahead within a field group.
 

package/docs/block-options.md

@@ -0,0 +1,116 @@
+# 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 never consume
+content rows. They are still listed in `modelFields` so the Universal Editor can
+render their option controls.
+
+## 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/docs/section-styles.md

@@ -0,0 +1,65 @@
+# Section Styles (Element Grouping for `style`)
+
+A section's appearance is controlled by the **Style** property of its Section
+Metadata, which AEM turns into CSS classes on the containing section element.
+`style` is the section counterpart of a block's [`classes`](./block-options.md)
+property.
+
+When a section model exposes several style options — especially mutually
+exclusive ones — it can use the
+[element grouping](https://www.aem.live/developer/component-model-definitions#element-grouping-for-block-options)
+naming convention: a **style group** is the base `style` field plus any
+`style_<name>` field.
+
+```jsonc
+{ "component": "select",      "name": "style",            "options": [ "variant-a", "variant-b" ] }
+{ "component": "multiselect", "name": "style_background", "options": [ "light", "dark" ] }
+{ "component": "boolean",     "name": "style_fullwidth" }
+```
+
+AEM collapses the whole style group into the single, well-known `style` cell of
+the Section Metadata table (a flat, comma-separated list). Going from markdown to
+JCR, md2jcr routes each token back to its field — exactly as it does for block
+`classes`:
+
+- **boolean field** — matched by its name suffix (after `style_`); token
+  `fullwidth` sets `style_fullwidth="true"`, absent leaves it unset;
+- **select / multiselect field** — matched by its declared option values; a
+  multiselect claims all of its matching tokens (`style_background="[light, dark]"`);
+- **base `style` field** — receives any leftover tokens (also the common single,
+  free-form `style` field case).
+
+### Example
+
+```markdown
++-------------------------------------------------------+
+| Section Metadata                                      |
++================+======================================+
+| style          | variant-a, light, fullwidth          |
++----------------+--------------------------------------+
+```
+
+becomes:
+
+```text
+style="variant-a"  style_background="light"  style_fullwidth="true"
+```
+
+### Notes
+
+- The routing rules and the underlying implementation are shared with block
+  options — see [Block Options](./block-options.md).
+- Distribution only kicks in when the section model declares at least one
+  `style_<name>` field. A model with only a base `style` field keeps the simple
+  one-to-one mapping.
+- The `style` group is listed in `modelFields` so the Universal Editor can
+  render those fields — the same as a block's `classes` group.
+
+### Worked fixtures
+
+See [`test/fixtures/blocks/core/section-style-options`](../test/fixtures/blocks/core/section-style-options):
+
+- `section-style-grouping` — single selects + a boolean that is on
+- `section-style-grouping-multi` — a multiselect claiming several values, boolean off
+- `section-style-grouping-fallback` — free-form base `style` catch-all + a boolean
+- `section-style-grouping-booleans` — several independent boolean options, mixed on/off