diff --git a/.claude/docs/harmonia-ui.md b/.claude/docs/harmonia-ui.md index 14f920ff10d..944a019a225 100644 --- a/.claude/docs/harmonia-ui.md +++ b/.claude/docs/harmonia-ui.md @@ -1,38 +1,46 @@ ## Harmonia runtime UI (`template-application-ui-harmonia-java` + `template-form-builder-harmonia`) -The runtime UI stack for generated applications: they render as a self-contained **Alpine.js + Harmonia SPA** (client-routed by Pinecone in hash mode, no iframes/`postMessage` hubs), served at `/services/web//gen//index.html`, talking to the **reused** generated Java REST controllers over a `fetch` client. The AngularJS IDE is untouched; the application layer now ships this stack only. `template-application-ui-harmonia-java` (registered on `platform-templates` as "Application - UI (Harmonia) - Java") emits the view types (list, manage, setting, master-detail, reports) + built-in **Process Inbox** (`/inbox`) and **Documents** (`/documents`) shell sections + inline process-task surfacing; `template-form-builder-harmonia` ("Harmonia Generator from Form Model", extension `form`) is the runtime form generator. The whole stack — Alpine 3.15.11, Harmonia 2.6.0, Lucide 1.8.0 — is embedded as **webjars** via `components/resources/application-core` (report charts use Harmonia's own native `x-h-chart-*` SVG charts; the `chart.js` webjar was dropped with the AngularJS dashboard shell) (incl. Pinecone Router — `org.webjars.npm:pinecone-router`, served version-less at `/webjars/pinecone-router/dist/router.min.js`; it was vendored until the 7.5.2 webjar existed). Developed on PR [#6078](https://github.com/eclipse-dirigible/dirigible/pull/6078). - -**Component reference:** the full codbex-harmonia directive catalog (all `x-h-*` components incl. the `x-h-select` combobox contract, theming, layout) lives **upstream** — the docs site and the agent-readable skill (formerly mirrored in-repo under `reference/harmonia/`; that copy was removed to avoid drift — always consult the upstream, version-matched to `harmonia.version` in the root `pom.xml`). [`.../reference/alpinejs/`](components/template/template-application-ui-harmonia-java/reference/alpinejs/) still covers the Alpine patterns (routing, page components), mirrored from `codbex-athena-app`, the reference app this stack was adopted from. Read them before changing Harmonia markup. - -**Detailed guides:** [`components/template/template-application-ui-harmonia-java/README.md`](components/template/template-application-ui-harmonia-java/README.md) (the SPA shell, view-type parity checklist, the master-detail detail registry, process-tasks store) and [`components/template/template-form-builder-harmonia/README.md`](components/template/template-form-builder-harmonia/README.md) (the neutral `formController(ctx)` contract). The repo-root [`HARMONIA_RUNTIME_PLAN.md`](HARMONIA_RUNTIME_PLAN.md) is the design doc + implementation status. **Gotchas that already burned someone — read before changing the templates:** - -- **REST path must use the Java-sanitised names.** `restBase` is `/services/java//gen/${javaGenFolderName}/api` and each page's `apiPath` is the **relative** `/${javaPerspectiveName}/Controller`; the fetch client prepends `restBase` exactly once. Use `javaGenFolderName`/`javaPerspectiveName` (e.g. `sales-order` → `sales_order`), **not** the raw `genFolderName`/lowercased perspective — the generated backend lives under the sanitised Java package. (Phase 0/1 only passed because `edm` needs no sanitising.) -- **`{ baseUrl: '' }` means "URL is absolute, prepend nothing".** The fetch client checks `opts.baseUrl !== undefined`, not truthiness — passing `''` with a relative path (or omitting it with an absolute path) is the classic doubled-URL bug (`/api/services/java/.../api/...`). Entity pages use a relative `apiPath` and **no** override; absolute URLs (relationship dropdowns, the detail registry) pass `{ baseUrl: '' }`. -- **Date/time widgets need conversion both ways.** The form `toPayload()` turns an HTML `date`/`datetime-local` value into a full ISO instant (`…Z`) so a Jackson `java.time.Instant`/`Timestamp` field binds (empty→`null`, a bare `TIME` passes through); `toDateInput()` slices the backend's ISO value back to what the widget expects on edit. Mirrors the AngularJS stack's `new Date(value)`. -- **Master-detail is registry-driven.** A master page renders one `detailPanel` per `App.detailsFor()` entry; each detail self-registers via `App.registerDetail(...)` (relative `apiPath`), so masters never enumerate details at generation time. The detail list filters via the controller's `?=` query (built into the reused rest-java controller for `*_DETAILS` layouts). -- **The `.form` runs the existing AngularJS `code` via compat shims, and the page is self-contained.** `template-form-builder-harmonia` runs the `.form` `code` as the body of `formController(ctx)` (`ctx.{model, params, http, task, notify, close}`) and defines `$scope`/`$http`/`NotificationHub`/`DialogHub` shims so intent-generated AngularJS `.form` code runs **unchanged** (no migration needed). The page loads only `form.js` + its own minimal fetch client (no `window.App`), because a BPM task form opens standalone in an iframe where the SPA shell assets are absent — an earlier `../../js/...` reference 404'd and left `App` undefined. -- **A standalone page must bootstrap `App.config.projectName` before loading `i18n.js`, or every module-authored label silently stays English.** `i18n.js` reads the project namespace off `App.config.projectName` — which only the SPA shell sets — and without it fetches just the platform `application-core` chrome catalog, so the page's own `.t.*` keys never resolve. The failure is invisible: the baked English literals render, no console error, and every shell page around the iframe IS translated. Both standalone pages (the report page and, since [#6692](https://github.com/eclipse-dirigible/dirigible/issues/6692), the task form) therefore set it in a one-line inline script before the ` @@ -69,7 +63,7 @@ - +
    @@ -77,10 +71,10 @@
  • - + - - + +
@@ -89,7 +83,7 @@