feat(sdk-angular): accessible semantic block editor renderer

[fmontes]

What

Adds DotCMSBlockEditorRendererNativeComponent (<dotcms-block-editor-renderer-native>), an accessible successor to the block editor renderer that emits clean semantic HTML — <ul><li><p>…</p></li></ul> — with no custom wrapper elements between semantic tags. The original DotCMSBlockEditorRendererComponent is marked @deprecated with its output unchanged for backward compatibility.

Why

An a11y scanner flagged the existing renderer for excessive nested wrapper elements: a dispatcher element sat between <ul> and its <li> children, breaking the list → listitem relationship required by the HTML spec and assistive technology. This is a published SDK, so rather than change existing output we add a new opt-in component.

How

• Host elements are the real semantic tags (attribute-selector hosts); recursion goes through ng-template outlets that render as comment nodes, so semantic nesting stays intact.
• Text + marks are rendered inline as native <strong>/<u>/<a>/… with no wrapper per text node.
• Identical public input API and customRenderers contract — migration is a one-line swap of tag and import.

Notes

• README / MIGRATION / CHANGELOG (v1.5.4) updated; both Angular examples (CSR + SSR) migrated, with a self-contained custom-block example.
• Verified: 206 unit tests pass, lint clean, build emits the new export.
• Follow-up: grid/table cells still reuse the legacy item component internally (one wrapper inside <td>/grid cells, not an ARIA-strict context).

🤖 Generated with Claude Code

This PR fixes: #35852

[claude]

Claude finished @fmontes's task in 5m 2s —— View job

---

Review

A few real concerns worth a second look. None are blocking on their own; #1, #3, #4 are the ones I'd most want resolved (or explicitly accepted) before this ships as a published SDK component pitched as the a11y-correct replacement.

1. Reverse-tabnabbing still possible when author supplies rel

dotcms-block-editor-renderer-native.component.html:278-281

[attr.rel]="
    markAttrs(marks)['rel'] ||
    (markAttrs(marks)['target'] === '_blank' ? 'noopener noreferrer' : null)
"

The noopener noreferrer fallback only fires when the author supplies no rel. If the editor stores rel="nofollow" and target="_blank", the rendered <a> gets rel="nofollow" only — no noopener, no noreferrer. That's the exact reverse-tabnabbing case copilot flagged at line 282; the current fix only catches the empty-rel branch. For a published SDK, this should always force noopener (and ideally noreferrer) into the token set whenever target="_blank", regardless of what else the author put in rel. The dispatch spec at line 175-199 (should preserve an author-supplied rel even when target="_blank") actively asserts the wrong behavior — it locks in the bug.

2. <th> rendered without scope, and cellNode.type is ignored

dotcms-block-editor-renderer-native.component.html:187-224

The PR is explicitly framed as the a11y replacement, but the table dispatch produces <th> elements with no scope attribute. AT can't reliably associate body cells with header cells without scope="col" / scope="row". Worth fixing here, since the whole point of this component is a11y-correct semantic DOM.

Related: the loops slice the first row into <thead><th> and the rest into <tbody><td> regardless of cellNode.type. TipTap's table extension distinguishes tableHeader vs tableCell — that distinction is silently discarded. A table with no header row is rendered with a misleading <thead>; a table whose first row is body cells gets <th> anyway. Both behaviors are inherited from the legacy renderer (blocks/table.component.ts), but the migration to a "semantic-DOM successor" is the right moment to dispatch on cellNode.type.

3. Stale validation/edit-mode state — flagged as deferred, but it's a real correctness bug now

dotcms-block-editor-renderer-native.component.ts:78,82-93

$isInEditMode = signal(getUVEState()?.mode === UVE_MODE.EDIT);

ngOnInit() {
    const state = isValidBlocks(this.blocks() as BlockEditorNode);
    ...
    this.$blockEditorState.set(state);
}

Acknowledging this was deferred to a follow-up — but with input() + OnPush now in place, the asymmetry is sharper than in the legacy renderer:

• blocks is now reactive; CD will re-evaluate the template when the parent rebinds it.
• $blockEditorState is not reactive; it's frozen after ngOnInit.

Concrete consequence: a parent that does blocks = signal(undefined) → blocks.set(asyncDoc) later (the canonical async load pattern with this SDK) renders the new doc through the dispatch, but $blockEditorState still says error: null from the initial undefined run — or, if the initial was an error and the new doc is valid, the error message stays. The legacy renderer had the same shape but with @Input() it at least re-ran on every input change. Deferring is fine, but the deferral note should probably acknowledge this is a regression vs. legacy, not just a missing improvement.

Same story for $isInEditMode — captured once at construction. If getUVEState() returns null at construction (e.g. UVE not yet initialized in SSR/hydration), invalid blocks in production render as nothing with no console error and no DOM trace.

4. <video> has a <track> with no src

dotcms-block-editor-renderer-native.component.html:179

<track default kind="captions" srclang="en" />

<track> requires src. As written this is invalid markup — the track is non-functional and the browser may warn. Parity with legacy, but worth removing rather than carrying forward as part of the "semantic HTML" story.

5. <img alt> falls back to empty when alt is missing

dotcms-block-editor-renderer-native.component.html:165-168

<img
    [alt]="node.attrs?.['alt']"
    [src]="node.attrs?.['src']"
    style="max-width: 100%; height: auto" />

If attrs.alt is missing, Angular renders alt="", which signals "decorative image" to AT and silently swallows the missing-alt failure that scanners would otherwise surface. For an a11y-positioned renderer, a missing alt should arguably either:

• emit no alt attribute (so scanners flag it), or
• in edit mode, surface a visible warning via $blockEditorState (matches how invalid blocks are handled).

Parity with legacy, but it's worth a deliberate decision rather than inheritance.

6. Example CalloutComponent (CSR + SSR) is still missing OnPush

examples/angular/src/app/dotcms/pages/blog/blog-post/customRenderers/callout/callout.component.ts:14-24
examples/angular-ssr/src/app/dotcms/pages/blog/blog-post/customRenderers/callout/callout.component.ts:14-24

oidacra raised this twice and I don't see it addressed in the comment thread or commits — neither file has changeDetection: ChangeDetectionStrategy.OnPush and they still use @Input() instead of input(). As the response thread noted, example code is copied as templates by SDK users; the default matters more here than in normal app code. Either fold this in or explicitly say it's deferred.

7. Minor: track node on the outer node list (line 13)

@for (node of content; track node) tracks by object reference. Block Editor content typically comes from immutable JSON parses, so any re-fetch produces new node references → Angular destroys and recreates the entire subtree on every update. Not a correctness bug, and the rendered tree isn't usually huge, but it negates the OnPush optimization in any "doc is refetched" flow. The table loops now track $index; the outer loop could too (or at least track by node.type + index where stable).

8. Pre-block whitespace

dotcms-block-editor-renderer-native.component.html:149-153

<pre dotCodeBlock>
    <ng-container
        *ngTemplateOutlet="..." /></pre>

<pre> preserves whitespace by spec. The component doesn't set preserveWhitespaces: true, so Angular collapses it in the source, but it's worth verifying the rendered code block doesn't show leading whitespace before the first line of code. No spec covers this — quick check in a browser would be enough.

9. Heading template is duplicated 7×

dotcms-block-editor-renderer-native.component.html:48-118

Each of @case ('1')…@case ('6') and @default is the same <hN [style.text-align]="..."><ng-container *ngTemplateOutlet="..." /></hN> pattern. The @switch is needed (Angular templates can't compute element tag names from an expression), but the structure could be hoisted into a small <ng-template #heading let-tag let-content> helper or rendered through ngComponentOutlet. Not blocking — just expensive to maintain.

---

Clean / acceptable

• The semantic-DOM mechanism itself (attribute-host components + ng-template/ngTemplateOutlet) is sound — the dispatch spec at dotcms-block-editor-renderer-native.dispatch.spec.ts:332-375 verifies <ul> directly contains <li> with no element wrapper, including inside <td> (line 486-533).
• asLevel()'s allow-list regex + default-to-<h2> is a good defensive call.
• The hrefless-<a> recursion through restMarks is correct and well-tested.
• Style passthrough is narrowed to textAlign only — good, and the migration note in MIGRATION.md:53 is clear about it.
• Track-by-$index on table cells closes the keyed-diff bug correctly.

[Copilot]

Pull request overview

Introduces DotCMSBlockEditorRendererNativeComponent, an accessible successor to the existing Angular Block Editor renderer that emits semantic HTML (e.g. <ul><li><p>…</p></li></ul>) with no custom wrapper elements between semantic tags. The legacy renderer is preserved and marked @deprecated. The component reuses existing media/table/grid/contentlet/unknown blocks and uses attribute-selector components plus ng-template/ngTemplateOutlet recursion so list-to-listitem DOM relationships are preserved for assistive technology.

Changes:

• Add DotCMSBlockEditorRendererNativeComponent and internal attribute-selector semantic components, exported from the SDK public_api.ts.
• Mark the existing DotCMSBlockEditorRendererComponent as deprecated; update README/MIGRATION/CHANGELOG (v1.5.4) to describe the migration.
• Migrate the CSR and SSR Angular examples to the new component and add a self-contained CalloutComponent custom renderer demo.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
core-web/libs/sdk/angular/src/public_api.ts	Export the new native renderer component from the SDK.
core-web/libs/sdk/angular/src/lib/components/dotcms-block-editor-renderer-semantic/dotcms-block-editor-renderer-native.component.ts	New component class with identical public API to legacy and same validation flow.
core-web/libs/sdk/angular/src/lib/components/dotcms-block-editor-renderer-semantic/dotcms-block-editor-renderer-native.component.html	Template that dispatches nodes to semantic tags via ng-template/ngTemplateOutlet and renders marks as native inline tags.
core-web/libs/sdk/angular/src/lib/components/dotcms-block-editor-renderer-semantic/blocks/semantic-blocks.component.ts	Internal attribute-selector components keeping semantic tags as DOM hosts.
core-web/libs/sdk/angular/src/lib/components/dotcms-block-editor-renderer-semantic/dotcms-block-editor-renderer-native.component.spec.ts	Unit tests for init, validation, class/style passthrough, and the asLevel helper.
core-web/libs/sdk/angular/src/lib/components/dotcms-block-editor-renderer-semantic/dotcms-block-editor-renderer-native.dispatch.spec.ts	Dispatch-level tests covering semantic DOM output, mark nesting, lists, headings, media, and custom renderers.
core-web/libs/sdk/angular/src/lib/components/dotcms-block-editor-renderer/dotcms-block-editor-renderer.component.ts	Adds @deprecated JSDoc pointing to the native renderer.
core-web/libs/sdk/angular/README.md	Documents new component; deprecation notice on legacy section.
core-web/libs/sdk/angular/MIGRATION.md	Adds migration section with one-line swap diff.
core-web/libs/sdk/angular/CHANGELOG.md	Adds v1.5.4 entry.
examples/angular/.../blog-post.component.{ts,html}	Switches CSR example to the native component and registers a callout custom renderer.
examples/angular/.../customRenderers/callout/callout.component.ts	New self-contained CSR callout custom renderer.
examples/angular-ssr/.../blog-post.component.{ts,html}	Switches SSR example to the native component and registers the callout.
examples/angular-ssr/.../customRenderers/callout/callout.component.ts	New SSR callout custom renderer (mirror of CSR).

[fmontes]

Thanks for the thorough pass. Addressed the three actionable template findings in 1676d04 (tests added, 209 unit tests pass, lint clean):

• Link href="" / target="" → both now bind with || null, so missing attrs omit the attribute instead of emitting a self-link. New test asserts neither attribute is present when the link mark has no attrs.
• Unknown mark drops downstream marks → the @default arm now recurses through restMarks(marks) when a mark is still present, so [unknown, bold] keeps its <strong>. New test covers it.
• [style]="node.attrs" leaking non-CSS attrs → <p> and <h1>–<h6> (incl. the @default heading) now bind [style.text-align]="node.attrs?.['textAlign'] || null". level and any future non-style attr no longer reach the style attribute. New test asserts text-align applies and level does not leak.

Deferring the two signal/lifecycle items as a focused follow-up rather than folding them in here:

• Validation in ngOnInit (stale on blocks change) and $isInEditMode captured at construction — both want the same refactor: blocks = input.required<BlockEditorNode>() + a computed/effect for state and a reactive read of UVE mode. That changes the public input wiring and is worth doing deliberately with its own tests, separate from this a11y-focused PR. The behavior here matches the deprecated renderer, so it's no regression.

• Grid/table cells still use the legacy item component — confirmed, and I'll open a follow-up issue to migrate those to the semantic path so the wrapper-between-<ul>-and-<li> is gone in those contexts too.

OnPush on the host and the dispatch-test fixtures (content: [] + forced state) noted — minor, will fold into the follow-up.

[fmontes]

Thanks for the careful review. Here's what I addressed and what I deliberately didn't, with reasoning:

Fixed in 29087f5:

• Test Branch and Commit #2 — Style passthrough not noted in migration. Added a paragraph to MIGRATION.md: native renderer forwards only textAlign; other inline-style attrs the legacy renderer copied through [style]="node.attrs" are dropped. (Code-side was already in 1676d04.)
• Add .gitignore #3 — <a> with no href. You're right that an empty <a> is worse than the old href="" self-link from an AT standpoint. The renderer now skips the element entirely for a hrefless link mark and recurses into the remaining marks/text. New tests cover no <a> and inner marks surviving beneath a dropped link.
• wezell's issue #5 — Heading @default → <h1>. Changed to <h2>. asLevel() now only normalizes 1–6; anything else (including missing) falls through to the safe default. Comment in the template explains why.
• test rwqrwqrwqr wq #6 — Table/grid still use the legacy item component. Added a "Known scope" callout to the native renderer's README section so the docs no longer read as if the a11y fix is total.
• #7a — BLOCKS → protected readonly.
• #7b — redundant cast in markAttrs → removed (BlockEditorMark.attrs is already Record<string, string>).
• #7d — implements OnInit → added.
• #7e — deprecated section's stale types → table now lists BlockEditorNode, class (not className), and string | Record<string, string> (not CSSProperties).

Deliberately not changing:

• update with latest SVN #1 — naming drift (semantic/ folder vs native class). The folder name describes the mechanism (semantic DOM via attribute-host components — those genuinely are DotSemantic* internals), the class name describes the public API ("native semantic HTML output"). They aren't synonyms. Renaming the folder is churn that doesn't change behavior or discoverability (search hits both). Happy to revisit if it bites in practice.
• New Issue #4 — <hr>/<br> inside <p>. <br> inside <p> is valid HTML. <hr> inside <p> would be malformed, but the editor schema doesn't allow horizontalRule as paragraph content, and emitting a defensive check would be guarding against an input the schema forbids. The legacy renderer had the same code path; if the schema ever changes, it should be caught upstream.

Deferred (per your #8): I'll open a follow-up issue covering OnPush, the $isInEditMode snapshot, the ngOnInit validation not reacting to blocks changes, and migrating to input.required() + computed/effect. Same issue can track the wrapper inside table/grid cells (#6 follow-up).

Verified: 211 unit tests pass, lint clean, build emits the export.