Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions .changeset/html-plugin-sap-html.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
---
"@ui5-community/jsx-runtime": minor
---

Add `plugins/html` opt-in plugin for native HTML tags via `sap.html` (OpenUI5 ≥ 1.154.0).

Lowercase HTML tags (`<div>`, `<span>`, `<input>`, …) now map to the corresponding `sap.html.*` UI5 control classes when wrapped in `withScope(htmlScope, () => …)`. Because these are real `ManagedObject` controls, the full UI5 programming model applies: data binding, events, dot-handler strings, `class=`, `ref=`, and auto-prefix-id all work identically to any other control — no per-tag imports needed.

New exports from `ui5/community/jsx/runtime/plugins/html`:

- `htmlScope` — partial scope to pass to `withScope`
- `preloadSapHtml()` — async bootstrap call that loads `sap.html` and all its controls via library metadata discovery
- `sapHtmlIntrinsic`, `tagToModulePath`, `resolveHtmlControl`, `normaliseHtmlProps` — lower-level exports for testing and custom composition

Also replaces the permissive `HTMLAttributes` fallback in `JSX.IntrinsicElements` with per-tag TypeScript interfaces (`AnchorAttributes`, `InputAttributes`, `ButtonHtmlAttributes`, `FormAttributes`, and more).
9 changes: 3 additions & 6 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -17,12 +17,6 @@ report/
.ui5-tooling-modules/
.ui5-middleware-serveframework/
ui5-workspace.yaml
# Keep the showcase's workspace file tracked — it wires the
# workspace-linked runtime dependency for `pnpm dev` and is the
# same for every developer. Per-developer overrides can live in
# a sibling ui5-workspace.yaml under a different name via the
# `--workspace` CLI flag.
!packages/jsx-runtime-showcase/ui5-workspace.yaml

# TypeScript
*.tsbuildinfo
Expand All @@ -35,6 +29,9 @@ ui5-workspace.yaml
.idea/
Thumbs.db

# Playwright MCP browser-session snapshots
.playwright-mcp/

# Logs
npm-debug.log*
pnpm-debug.log*
Expand Down
40 changes: 35 additions & 5 deletions docs/gotchas.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,16 +28,46 @@ Documented at [src/runtime/scope.ts](../packages/jsx-runtime/src/runtime/scope.t

---

## HTML intrinsic tags are typed but not runtime-supported (yet)
## HTML intrinsic tags — use the `plugins/html` opt-in

`JSX.IntrinsicElements` permissively types `<div>`, `<svg>`, `<my-tag>`, etc. The **default** renderer throws on lowercase tags — it constructs UI5 controls, and a literal `div` cannot become a control.
Lowercase HTML tags (`<div>`, `<span>`, `<input>`, …) are typed in
`JSX.IntrinsicElements` but are **not enabled by default**. The default
scope throws on them — it constructs UI5 controls, and a bare string tag
has no UI5 metadata to construct from.

To use HTML tags, opt in to the `plugins/html` package (requires
**OpenUI5 ≥ 1.154.0**, which ships the `sap.html` library):

```tsx
// ❌ Typechecks, throws at runtime
<div class="wrap"><span>hi</span></div>
import { withScope } from "ui5/community/jsx/runtime/jsx-runtime";
import { htmlScope, preloadSapHtml } from "ui5/community/jsx/runtime/plugins/html/index";

// At bootstrap (once, before any HTML-tag view renders):
await preloadSapHtml();

// In createContent():
return withScope(htmlScope, () => (
<div class="wrap"><span>Hi</span></div>
));
```

An HTML-aware renderer plugin is planned that installs an `htmlIntrinsic` in the scope; until then, treat lowercase tags as unusable in JSX. The error message from `jsx()` names the missing `htmlIntrinsic` explicitly.
Each lowercase tag maps to the corresponding `sap.html.*` control class
(`<div>` → `sap/html/Div`, `<input>` → `sap/html/Input`, etc.). Because
these are real `ManagedObject` controls, data binding, events, `class=`,
and `ref=` all work identically to any other UI5 control.

Outside `withScope(htmlScope, …)`, lowercase tags still throw a clear
error naming the missing `htmlIntrinsic`. The scope boundary is explicit
and reversible.

See [docs: Native HTML via sap.html](../packages/jsx-runtime-showcase/webapp/docs/native-html.md)
and the [plugins/html README](../packages/jsx-runtime/src/plugins/html/README.md)
for full details.

SVG tags (`<svg>`, `<path>`, `<g>`, …) remain unimplemented; there is
no `sap.svg` library equivalent. They are typed permissively in
`JSX.IntrinsicElements` as `HTMLAttributes` (fallback) but will still
throw at runtime if used without a custom `htmlIntrinsic` that handles them.

---

Expand Down
9 changes: 9 additions & 0 deletions packages/jsx-runtime-showcase/samples.json
Original file line number Diff line number Diff line change
Expand Up @@ -163,6 +163,15 @@
"viewName": "ui5.community.jsx.showcase.view.showcases.ForwardedMenu",
"sourcePath": "webapp/view/showcases/ForwardedMenu.tsx",
"docPath": "webapp/docs/samples/forwarded-menu.md"
},
{
"id": "native-html",
"title": "Native HTML via sap.html",
"chapter": 19,
"concepts": ["sap.html controls", "html plugin", "withScope(htmlScope)", "text children", "mixed content", "native events", "import-free HTML tags"],
"viewName": "ui5.community.jsx.showcase.view.showcases.NativeHtml",
"sourcePath": "webapp/view/showcases/NativeHtml.tsx",
"docPath": "webapp/docs/native-html.md"
}
]
}
6 changes: 0 additions & 6 deletions packages/jsx-runtime-showcase/ui5-workspace.yaml

This file was deleted.

3 changes: 2 additions & 1 deletion packages/jsx-runtime-showcase/ui5.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,11 @@ metadata:
type: application
framework:
name: OpenUI5
version: "1.148.2"
version: "1.154.0"
libraries:
- name: sap.m
- name: sap.f
- name: sap.html
- name: sap.tnt
- name: sap.ui.core
- name: sap.ui.layout
Expand Down
25 changes: 24 additions & 1 deletion packages/jsx-runtime-showcase/webapp/Component.ts
Original file line number Diff line number Diff line change
@@ -1,21 +1,28 @@
import UIComponent from "sap/ui/core/UIComponent";
import Log from "sap/base/Log";

import { getMode, setMode } from "./util/theme";
import { preloadSapHtml } from "ui5/community/jsx/runtime/plugins/html/index";

/**
* Root component of the showcase.
*
* The manifest declares `ui5.community.jsx.runtime` as a `libs`
* dependency, so UI5 auto-loads the library before `init()` runs.
*
* `preloadSapHtml()` fetches the `sap.html` library and the
* `sap/ui/core/html/TextContent` module (required for mixed
* text+control children in native HTML JSX tags) before the
* router opens any view.
*
* @namespace ui5.community.jsx.showcase
*/
export default class Component extends UIComponent {
public static metadata = {
manifest: "json"
};

public init(): void {
public async init(): Promise<void> {
super.init();
// Reconcile UI5's runtime theme with the persisted (or
// OS-derived) mode. The pre-paint resolver in
Expand All @@ -24,6 +31,22 @@ export default class Component extends UIComponent {
// Mermaid + the CodeBlock have a consistent view of "the
// theme has arrived" on first render.
setMode(getMode());
// Preload sap.html (and sap/ui/core/html/TextContent) so the
// html plugin can resolve <div>/<span>/… synchronously at JSX
// construction time in the NativeHtml sample view.
// A failure (wrong framework version, network error) is non-fatal:
// the app still works, but HTML-tag views will throw at construction
// time with a clear "module not loaded" message instead of silently.
try {
await preloadSapHtml();
} catch (err) {
Log.error(
"ui5/community/jsx/runtime/plugins/html: preloadSapHtml() failed — " +
"native HTML tags (<div>, <span>, …) will not work in this session.",
err instanceof Error ? err.message : String(err),
"ui5.community.jsx.showcase.Component"
);
}
this.getRouter().initialize();
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,8 @@ export default class Explorer extends Controller {
{ key: "learn.runtime-anatomy", title: "Runtime anatomy", icon: "sap-icon://process", route: "learnDoc", arg: "runtime-anatomy" },
{ key: "learn.auto-prefix", title: "Auto id prefix", icon: "sap-icon://text", route: "learnDoc", arg: "auto-prefix" },
{ key: "learn.plugin-spi", title: "The Plugin SPI", icon: "sap-icon://puzzle", route: "learnDoc", arg: "plugin-spi" },
{ key: "learn.switch-plugin", title: "Case study: <Switch>", icon: "sap-icon://switch-classes", route: "learnDoc", arg: "switch-plugin" }
{ key: "learn.switch-plugin", title: "Case study: <Switch>", icon: "sap-icon://switch-classes", route: "learnDoc", arg: "switch-plugin" },
{ key: "learn.native-html", title: "Native HTML (sap.html)", icon: "sap-icon://html5", route: "learnDoc", arg: "native-html" }
]}
];

Expand Down Expand Up @@ -118,7 +119,8 @@ export default class Explorer extends Controller {
{ key: "explore.forwarded-menu", title: "Forwarded aggregation (Menu)", icon: "sap-icon://menu2", route: "exploreSample", arg: "forwarded-menu" }
]},
{ key: "explore.g.plugins", title: "Plugins / Extend", icon: "sap-icon://puzzle", children: [
{ key: "explore.switch-plugin", title: "Plugin <Switch>", icon: "sap-icon://switch-classes", route: "exploreSample", arg: "switch-plugin" }
{ key: "explore.switch-plugin", title: "Plugin <Switch>", icon: "sap-icon://switch-classes", route: "exploreSample", arg: "switch-plugin" },
{ key: "explore.native-html", title: "Native HTML via sap.html", icon: "sap-icon://html5", route: "exploreSample", arg: "native-html" }
]}
];

Expand Down Expand Up @@ -284,6 +286,15 @@ export default class Explorer extends Controller {
toolPage?.removeStyleClass("jsx-welcome-no-sidenav");
sideNav?.setVisible(true);
toolPage?.setSideExpanded?.(true);
// Scroll the selected nav item into view after the binding
// has updated the DOM (sapTntNLISelected class lands async).
setTimeout(() => {
const view = this.getView();
if (!view) return;
const navListDom = view.byId("explorerNavList")?.getDomRef();
const selected = navListDom?.querySelector(".sapTntNLISelected");
selected?.scrollIntoView({ block: "nearest" });
}, 0);
}
}

Expand Down
12 changes: 12 additions & 0 deletions packages/jsx-runtime-showcase/webapp/css/style.css
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,18 @@
margin-left: 0.5rem;
}

/*
* The ToolPage aside content area needs a scrollbar when the nav list
* is taller than the viewport. UI5's `sapTntNL` already has
* `overflow-y: auto` on the inner UL, but the parent `sapTntToolPage`
* has `overflow: hidden` which clips the scrollbar track. Giving the
* aside content its own `overflow-y: auto` surfaces the scrollbar so
* users can reach nav items below the fold.
*/
.sapTntToolPageAsideContent {
overflow-y: auto;
}

/*
* Welcome view uses the same shared `sap.tnt.ToolPage` shell as
* Learn and Explore. On the welcome route we hide the side
Expand Down
Loading
Loading