@adobe/helix-md2jcr 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -1,3 +1,24 @@
+# [1.5.0](https://github.com/adobe/helix-md2jcr/compare/v1.4.1...v1.5.0) (2026-06-17)
+
+
+### Features
+
+* **phrasing:** preserve inline HTML tags in text elements ([#217](https://github.com/adobe/helix-md2jcr/issues/217)) ([5f7d274](https://github.com/adobe/helix-md2jcr/commit/5f7d2745005ae0947866fb66989cdb9626cb3e60))
+
+## [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)
 
 

package/README.md

@@ -109,8 +109,13 @@ console.log(xml);
 - [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.
+- [Phrasing Content](docs/phrasing.md) — supported inline HTML tags (`sup`, `sub`,
+  `u`, `del`, `strong`, `em`) and how they survive the markdown → JCR pipeline.
 
 ## Baseline XML Files
 Running the ./baseline-tests.sh script will detect any md file under test/fixtures and execute the convert2jcr node script.  

package/docs/block-options.md

@@ -76,8 +76,9 @@ Promo (highlight, featured, sticky)   // classes is free-form, classes_sticky is
   -> 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.
+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
 

package/docs/phrasing.md

@@ -0,0 +1,54 @@
+# Phrasing Content (Inline HTML)
+
+Phrasing content refers to inline elements that flow within a line of text — as
+opposed to block-level elements like paragraphs, headings, and lists.
+
+When raw HTML inline tags appear in markdown source, remark parses them as `html`
+nodes. The `mdast-sanitize-html` step converts them into typed mdast nodes, and
+the serializer then maps those nodes back to their HTML equivalents when writing
+the `text` attribute of a JCR text component.
+
+## Supported Tags
+
+| HTML tag | mdast node type | Serializes to |
+|---|---|---|
+| `<sup>` | `superscript` | `<sup>` |
+| `<sub>` | `subscript` | `<sub>` |
+| `<u>` | `underline` | `<u>` |
+| `<del>` | `delete` | `<del>` |
+| `<strong>` | `strong` | `<strong>` |
+| `<em>` | `emphasis` | `<em>` |
+
+`superscript`, `subscript`, and `underline` are custom node types introduced by
+`mdast-sanitize-html`. They require explicit handlers in `hast-handlers.js` so
+that `mdast-util-to-hast` knows to emit the correct tag rather than falling back
+to `<div>`. The remaining three (`delete`, `strong`, `emphasis`) are standard
+mdast types with built-in hast handlers.
+
+## Example
+
+Markdown source:
+
+```markdown
+E = mc<sup>2</sup> and H<sub>2</sub>O with <u>underline</u>, <del>strike</del>, <strong>bold</strong>, <em>italic</em>.
+```
+
+Resulting `text` attribute value:
+
+```html
+<p>E = mc<sup>2</sup> and H<sub>2</sub>O with <u>underline</u>, <del>strike</del>, <strong>bold</strong>, <em>italic</em>.</p>
+```
+
+## Pipeline
+
+```
+markdown source
+  → remark parse → html nodes (raw inline HTML)
+  → mdast-sanitize-html → typed mdast nodes (superscript, subscript, etc.)
+  → toHast (with customHastHandlers) → hast element nodes
+  → toHtml → HTML string stored in JCR text attribute
+```
+
+The custom handlers live in
+`src/mdast2jcr/hb/partials/supports/hast-handlers.js` and are applied wherever
+`toHast` is called — currently `paragraph.js` and `grid-table.js`.

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