Skip to content

feat(plugins/html): add sap.html opt-in plugin for native HTML tags - #13

Merged
petermuessig merged 8 commits into
mainfrom
feat/sap-html-plugin
Nov 1, 2026
Merged

petermuessig merged 8 commits into
mainfrom
feat/sap-html-plugin

Conversation

@petermuessig

@petermuessig petermuessig commented Sep 18, 2026 •

Copy link
Copy Markdown
Member

Summary

Adds plugins/html, an opt-in plugin that maps lowercase HTML tags in TSX views to real sap.html.* UI5 control classes (shipped in OpenUI5 1.154.0). No per-tag imports — just wrap a subtree in withScope(htmlScope, () => …).

import { withScope } from "ui5/community/jsx/runtime/jsx-runtime";
import { htmlScope, preloadSapHtml } from "ui5/community/jsx/runtime/plugins/html/index";

// Component.init():
await preloadSapHtml();

// In a view:
return withScope(htmlScope, () => (
  <div class="myCard">
    <h3>Hello, JSX!</h3>
    <input value="{/name}" input={(e) => { /* explicit write-back via getDomRef */ }} />
    <button click={() => MessageToast.show("Hi!")}>Click me</button>
  </div>
));

Key design points

  • Opt-in scope — withScope(htmlScope, fn) enables HTML tags for a subtree; lowercase tags outside throw "no htmlIntrinsic".
  • Tag resolution — first character uppercased, rest unchanged: <div> → sap/html/Div, <h1> → sap/html/H1, <blockquote> → sap/html/Blockquote.
  • Text children — sole string child → text property; mixed text + controls → sap.ui.core.html.TextContent wrappers in children; void elements (<br>, <input>, …) reject children.
  • Preload — preloadSapHtml() reads the library metadata's controls list and async-requires every sap/html/* module in one batch so the sync resolver can always find them.
  • Full UI5 pipeline reused — data binding, dot-handler events, class=, ref=, and auto-prefix-id all work unchanged.
  • Explicit write-back — sap.html property bindings are model-driven (one-way into the control); getValue() returns the stale model value, not what the user typed. Read the live text via getDomRef().value in input/change handlers.

What's in this PR

Package Changes
jsx-runtime New src/plugins/html/index.ts plugin; per-tag JSX.IntrinsicElements types replacing the old permissive bag; ./plugins/html exports subpath
jsx-runtime tests 26 QUnit assertions using fake sap.html controls via a patched sap.ui.require — no real library required at test time
jsx-runtime-showcase Chapter 19 NativeHtml.tsx sample with live bound <input> demo; Learn + Explore nav entries; native-html.md learn page (incl. write-back section); framework bumped to 1.154.0
docs / misc docs/gotchas.md HTML intrinsic section updated; binding-string sample clarified (change vs liveChange); ui5-workspace.yaml removed (no longer needed now that sap.html ships in the official release); minor changeset

Test plan

  • pnpm --filter @ui5-community/jsx-runtime build — compiles cleanly, no TS errors
  • pnpm --filter @ui5-community/jsx-runtime test — 26/26 plugins/html tests pass, no regressions
  • Showcase (pnpm dev) on OpenUI5 1.154.0 — Native HTML sample renders; typing in <input> updates the <output> and <p> on every keystroke; button/link fire MessageToast; <details> expands/collapses

Maps lowercase HTML tags (<div>, <span>, <input>, …) to the
corresponding sap.html.* UI5 control classes introduced in OpenUI5
1.154.0, so native HTML can be written in TSX views without per-tag
imports.

Key design points:

- Opt-in via withScope(htmlScope, () => …); outside the scope,
  lowercase tags throw a clear "no htmlIntrinsic" error.
- Tag resolution: first character uppercased, rest unchanged
  ("div" → sap/html/Div, "h1" → sap/html/H1).
- Text children: sole text → `text` property; mixed text+controls →
  sap.ui.core.html.TextContent wrappers preserving source order;
  void elements reject children.
- preloadSapHtml() uses the library metadata's `controls` list to
  async-require every sap/html/* module in one batch, so the sync
  sap.ui.require resolver always finds them.
- Full UI5 pipeline reused: data binding, events, dot-handlers,
  class=, ref=, and auto-prefix-id all work unchanged.

Also includes:
- Per-tag JSX.IntrinsicElements types (AnchorAttributes,
  InputAttributes, ButtonHtmlAttributes, …) replacing the previous
  permissive HTMLAttributes bag.
- ./plugins/html exports subpath in package.json.
- NativeHtml.tsx showcase view (chapter 19) with live demo.
- Learn + Explore navigation entries and docs pages.
- QUnit tests (26 assertions) using fake sap.html controls via a
  patched sap.ui.require; no real sap.html library required at
  test time.
The ToolPage aside had no scroll context — `sapTntToolPage`'s
`overflow: hidden` clipped the NavigationList's scrollbar track so
items below the fold were unreachable. Adding `overflow-y: auto` on
`.sapTntToolPageAsideContent` surfaces a scrollbar on the nav panel.

Also scroll the active `.sapTntNLISelected` item into view on each
route change (setTimeout-deferred so the binding update lands first),
so deep-linking to a low item like "Plugins / Extend → Native HTML via
sap.html" reveals the selection without manual scrolling.
- Drop local openui5/sapui5.runtime workspace resolutions from
  packages/jsx-runtime-showcase/ui5-workspace.yaml; sap.html now ships
  in the official OpenUI5 1.154.0 release
- Bump showcase framework version from 1.154.0-SNAPSHOT → 1.154.0
- Update plugins/html README note from SNAPSHOT to stable release
- Fix NativeHtml.tsx input handler: getProperty("value") / getValue()
  returns the stale model-bound value, not what the user typed; read
  current text via getDomRef().value instead
- Fix <output> element: add text="{/name}" so it displays the live name
- Document the getDomRef write-back pattern in native-html.md and the
  NativeHtml.tsx JSDoc with explanation of why getValue() is wrong here
- Add "input vs change" comparison table to native-html.md
- Clarify binding-string sample: mirror updates on change (blur/Enter),
  not every keystroke; remove stale binding-twoway cross-reference
- Add .playwright-mcp/ to .gitignore
sap.html ships in the official OpenUI5 1.154.0 release, so there is no
longer a need to resolve workspace dependencies via a ui5-workspace.yaml.
The pnpm workspace link for jsx-runtime is handled through node_modules
symlinks; the tooling file is unnecessary.

Also drops the .gitignore exception that kept the showcase's copy tracked.
…er, rename Event to UI5Event

- Component.ts: wrap preloadSapHtml() in try/catch; log a structured error
  on failure instead of crashing app init (non-fatal degraded mode)
- NativeHtml.tsx: use href="#native-html" instead of javascript:void(0)
  to avoid CSP issues
- html/index.ts: exclude empty-string text from void-element rejection;
  tighten whitespace filter to newline-bearing strings only so {" "} is
  preserved as intentional content
- runtime.ts: rename imported Event type alias to UI5Event to remove
  ambiguity with the DOM global now that the HTML plugin is in scope
@petermuessig
petermuessig merged commit 6d29d45 into main Nov 1, 2026
3 checks passed
@github-actions github-actions Bot mentioned this pull request Nov 1, 2026
@petermuessig
petermuessig deleted the feat/sap-html-plugin branch November 1, 2026 15:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant